Updated API to have isSelected control selectable card state

Author: Eric Olkowski

packages/react-core/src/components/Card/Card.tsx

@@ -18,8 +18,8 @@ export interface CardProps extends React.HTMLProps<HTMLElement>, OUIAProps {
   isSelectable?: boolean;
   /** Flag indicating that the card is clickable and contains some action that triggers on click. */
   isClickable?: boolean;
-  /** Flag indicating whether a card that is both clickable and selectable is currently selected and has selected styling.
-   * This will not determine the card's actual selected state.
+  /** Flag indicating whether a card that is either selectable only or both clickable and selectable is
+   * currently selected and has selected styling.
    */
   isSelected?: boolean;
   /** Flag indicating whether a card that is either only clickable or that is both clickable and selectable
@@ -49,6 +49,7 @@ interface CardContextProps {
   isExpanded: boolean;
   isClickable: boolean;
   isSelectable: boolean;
+  isSelected: boolean;
   isClicked: boolean;
   isDisabled: boolean;
 }
@@ -58,6 +59,7 @@ export const CardContext = React.createContext<Partial<CardContextProps>>({
   isExpanded: false,
   isClickable: false,
   isSelectable: false,
+  isSelected: false,
   isClicked: false,
   isDisabled: false
 });
@@ -119,6 +121,7 @@ export const Card: React.FunctionComponent<CardProps> = ({
         isExpanded,
         isClickable,
         isSelectable,
+        isSelected,
         isClicked,
         isDisabled
       }}

packages/react-core/src/components/Card/CardHeader.tsx

@@ -44,7 +44,9 @@ export interface CardHeaderSelectableActionsObject {
   isExternalLink?: boolean;
   /** Name for the input element of a clickable or selectable card. */
   name?: string;
-  /** Flag indicating whether the selectable card input is checked */
+  /** @deprecated Flag indicating whether the selectable card input is checked. We recommend using
+   * the isSelected prop on the card component instead.
+   */
   isChecked?: boolean;
 }
 
@@ -79,7 +81,7 @@ export const CardHeader: React.FunctionComponent<CardHeaderProps> = ({
   ...props
 }: CardHeaderProps) => (
   <CardContext.Consumer>
-    {({ cardId, isClickable, isSelectable, isClicked, isDisabled: isCardDisabled }) => {
+    {({ cardId, isClickable, isSelectable, isSelected, isClicked, isDisabled: isCardDisabled }) => {
       const cardHeaderToggle = (
         <div className={css(styles.cardHeaderToggle)}>
           <Button
@@ -126,6 +128,7 @@ export const CardHeader: React.FunctionComponent<CardHeaderProps> = ({
           name: selectableActions.name,
           isDisabled: isCardDisabled
         };
+        const isSelectableInputChecked = selectableActions.isChecked ?? isSelected;
 
         if (isClickable && !isSelectable) {
           return {
@@ -135,7 +138,7 @@ export const CardHeader: React.FunctionComponent<CardHeaderProps> = ({
           };
         }
         if (isSelectable) {
-          return { ...baseProps, onChange: selectableActions.onChange, isChecked: selectableActions.isChecked };
+          return { ...baseProps, onChange: selectableActions.onChange, isChecked: isSelectableInputChecked };
         }
 
         return baseProps;

packages/react-core/src/components/Card/examples/Card.md

@@ -133,7 +133,7 @@ When a group of single selectable cards are related, you must pass the same `nam
 
 ### Actionable
 
-An actionable card can perform an action or navigate to a link by clicking anywhere within the card. You can also pass in the `isExternalLink` property to `selectableActions` if you want an actionable card's link to open in a new tab or window.
+An actionable card can perform an action or navigate to a link by clicking anywhere within the card. To open a link in a new tab or window, pass the `isExternalLink` property to `selectableActions`.
 
 You can pass the `isClicked` property to `<Card>` to convey that a card is the currently clicked one, such as when clicking a card would open a [primary-detail view](/patterns/primary-detail). This must not be used simply for "selection" of a card, and you should instead use our [selectable card](#selectable) or [single selectable card](#single-selectable).
 

packages/react-core/src/components/Card/examples/CardClickableSelectable.tsx

@@ -5,15 +5,15 @@ export const CardClickable: React.FunctionComponent = () => {
   const [isChecked1, setIsChecked1] = React.useState(false);
   const [isChecked2, setIsChecked2] = React.useState(false);
   const [isChecked3, setIsChecked3] = React.useState(false);
-  const [isSelected1, setIsSelected1] = React.useState(false);
+  const [isClicked, setIsClicked] = React.useState(false);
   const [isSecondary, setIsSecondary] = React.useState<boolean>(false);
 
   const id1 = 'clickable-selectable-card-input-1';
   const id2 = 'clickable-selectable-card-input-2';
   const id3 = 'clickable-selectable-card-input-3';
 
   const onClick = () => {
-    setIsSelected1((prevState) => !prevState);
+    setIsClicked((prevState) => !prevState);
   };
 
   const onChange = (event: React.FormEvent<HTMLInputElement>, checked: boolean) => {
@@ -52,15 +52,15 @@ export const CardClickable: React.FunctionComponent = () => {
             id="clickable-selectable-card-example-1"
             isClickable
             isSelectable
-            isSelected={isSelected1}
+            isSelected={isChecked1}
+            isClicked={isClicked}
             variant={isSecondary ? 'secondary' : 'default'}
           >
             <CardHeader
               selectableActions={{
                 selectableActionId: id1,
                 selectableActionAriaLabelledby: 'clickable-selectable-card-example-1',
                 name: id1,
-                isChecked: isChecked1,
                 onChange
               }}
             >
@@ -76,14 +76,14 @@ export const CardClickable: React.FunctionComponent = () => {
             id="clickable-selectable-card-example-2"
             isClickable
             isSelectable
+            isSelected={isChecked2}
             variant={isSecondary ? 'secondary' : 'default'}
           >
             <CardHeader
               selectableActions={{
                 selectableActionId: id2,
                 selectableActionAriaLabelledby: 'clickable-selectable-card-example-2',
                 name: id2,
-                isChecked: isChecked2,
                 onChange
               }}
             >
@@ -102,14 +102,14 @@ export const CardClickable: React.FunctionComponent = () => {
             isClickable
             isSelectable
             isDisabled
+            isSelected={isChecked3}
             variant={isSecondary ? 'secondary' : 'default'}
           >
             <CardHeader
               selectableActions={{
                 selectableActionId: id3,
                 selectableActionAriaLabelledby: 'clickable-selectable-card-example-3',
                 name: id3,
-                isChecked: isChecked3,
                 onChange
               }}
             >

packages/react-core/src/components/Card/examples/CardSelectable.tsx

@@ -42,41 +42,54 @@ export const SelectableCard: React.FunctionComponent = () => {
       />
       <div style={{ marginTop: '15px' }}>
         <Gallery hasGutter>
-          <Card id="selectable-card-example-1" isSelectable variant={isSecondary ? 'secondary' : 'default'}>
+          <Card
+            id="selectable-card-example-1"
+            isSelectable
+            isSelected={isChecked1}
+            variant={isSecondary ? 'secondary' : 'default'}
+          >
             <CardHeader
               selectableActions={{
                 selectableActionId: id1,
                 selectableActionAriaLabelledby: 'selectable-card-example-1',
                 name: id1,
-                isChecked: isChecked1,
                 onChange
               }}
             >
               <CardTitle>First card</CardTitle>
             </CardHeader>
             <CardBody>This card is selectable.</CardBody>
           </Card>
-          <Card id="selectable-card-example-2" isSelectable variant={isSecondary ? 'secondary' : 'default'}>
+          <Card
+            id="selectable-card-example-2"
+            isSelectable
+            isSelected={isChecked2}
+            variant={isSecondary ? 'secondary' : 'default'}
+          >
             <CardHeader
               selectableActions={{
                 selectableActionId: id2,
                 selectableActionAriaLabelledby: 'selectable-card-example-2',
                 name: id2,
-                isChecked: isChecked2,
                 onChange
               }}
             >
               <CardTitle>Second card</CardTitle>
             </CardHeader>
             <CardBody>This card is selectable.</CardBody>
           </Card>
-          <Card id="selectable-card-example-3" isSelectable isDisabled variant={isSecondary ? 'secondary' : 'default'}>
+          <Card
+            id="selectable-card-example-3"
+            isSelectable
+            isDisabled
+            isSelected={isChecked3}
+            variant={isSecondary ? 'secondary' : 'default'}
+          >
             <CardHeader
               selectableActions={{
                 selectableActionId: id3,
                 selectableActionAriaLabelledby: 'selectable-card-example-3',
                 name: id3,
-                isChecked: isChecked3,
                 onChange
               }}
             >

packages/react-core/src/components/Card/examples/CardSingleSelectable.tsx

@@ -13,44 +13,41 @@ export const SingleSelectableCard: React.FunctionComponent = () => {
 
   return (
     <Gallery hasGutter>
-      <Card id="single-selectable-card-example-1" isSelectable>
+      <Card id="single-selectable-card-example-1" isSelectable isSelected={isChecked === id1}>
         <CardHeader
           selectableActions={{
             selectableActionId: id1,
             selectableActionAriaLabelledby: 'single-selectable-card-example-1',
             name: 'single-selectable-card-example',
             variant: 'single',
-            isChecked: isChecked === id1,
             onChange
           }}
         >
           <CardTitle>First card</CardTitle>
         </CardHeader>
         <CardBody>This card is single selectable.</CardBody>
       </Card>
-      <Card id="single-selectable-card-example-2" isSelectable>
+      <Card id="single-selectable-card-example-2" isSelectable isSelected={isChecked === id2}>
         <CardHeader
           selectableActions={{
             selectableActionId: id2,
             selectableActionAriaLabelledby: 'single-selectable-card-example-2',
             name: 'single-selectable-card-example',
             variant: 'single',
-            isChecked: isChecked === id2,
             onChange
           }}
         >
           <CardTitle>Second card</CardTitle>
         </CardHeader>
         <CardBody>This card is single selectable.</CardBody>
       </Card>
-      <Card id="single-selectable-card-example-3" isSelectable isDisabled>
+      <Card id="single-selectable-card-example-3" isSelectable isDisabled isSelected={isChecked === id3}>
         <CardHeader
           selectableActions={{
             selectableActionId: id3,
             selectableActionAriaLabelledby: 'single-selectable-card-example-3',
             name: 'single-selectable-card-example',
             variant: 'single',
-            isChecked: isChecked === id3,
             onChange
           }}
         >

packages/react-integration/demo-app-ts/src/components/demos/CardDemo/CardDemo.tsx

@@ -26,13 +26,14 @@ interface CardDemoState {
   isOpen: boolean;
   selectableChecked1: boolean;
   selectableChecked2: boolean;
+  singleSelectableChecked: string;
   drawerIsExpanded: boolean;
   selectableClickableChecked: boolean;
   selectableClickableSelected: boolean;
   selectaleClickableDrawerIsExpanded: boolean;
 }
 
-export class CardDemo extends Component {
+class CardDemo extends Component {
   static displayName = 'CardDemo';
 
   state: CardDemoState = {
@@ -41,6 +42,7 @@ export class CardDemo extends Component {
     isOpen: false,
     selectableChecked1: false,
     selectableChecked2: false,
+    singleSelectableChecked: '',
     drawerIsExpanded: false,
     selectableClickableChecked: false,
     selectableClickableSelected: false,
@@ -94,6 +96,10 @@ export class CardDemo extends Component {
     }
   };
 
+  onSingleSelectableChange = (event: React.FormEvent<HTMLInputElement>) => {
+    this.setState({ singleSelectableChecked: (event.target as HTMLElement).id });
+  };
+
   onSelectableClickableChange = (_event: React.FormEvent<HTMLInputElement>, checked: boolean) => {
     this.setState({ selectableClickableChecked: checked });
   };
@@ -109,6 +115,7 @@ export class CardDemo extends Component {
     const {
       selectableChecked1,
       selectableChecked2,
+      singleSelectableChecked,
       drawerIsExpanded,
       selectableClickableChecked,
       selectableClickableSelected,
@@ -213,26 +220,36 @@ export class CardDemo extends Component {
           <CardBody>This card is selectable.</CardBody>
         </Card>
         <br></br>
-        <Card id="single-selectable-card-example-1" isSelectable>
+        <Card
+          id="single-selectable-card-example-1"
+          isSelectable
+          isSelected={singleSelectableChecked === 'single-selectable-card-input-1'}
+        >
           <CardHeader
             selectableActions={{
               selectableActionId: 'single-selectable-card-input-1',
               selectableActionAriaLabelledby: 'single-selectable-card-example-1',
               name: 'single-selectable-card-example',
-              variant: 'single'
+              variant: 'single',
+              onChange: this.onSingleSelectableChange
             }}
           >
             <CardTitle>First single selectable card</CardTitle>
           </CardHeader>
           <CardBody>This card is single selectable.</CardBody>
         </Card>
-        <Card id="single-selectable-card-example-2" isSelectable>
+        <Card
+          id="single-selectable-card-example-2"
+          isSelectable
+          isSelected={singleSelectableChecked === 'single-selectable-card-input-2'}
+        >
           <CardHeader
             selectableActions={{
               selectableActionId: 'single-selectable-card-input-2',
               selectableActionAriaLabelledby: 'single-selectable-card-example-2',
               name: 'single-selectable-card-example',
-              variant: 'single'
+              variant: 'single',
+              onChange: this.onSingleSelectableChange
             }}
           >
             <CardTitle>Second single selectable card</CardTitle>
@@ -325,3 +342,7 @@ export class CardDemo extends Component {
     );
   }
 }
+
+CardDemo.displayName = 'CardDemo';
+
+export { CardDemo };