add example to better explain selectable a11y props

Author: wise-king-sullyman

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

@@ -71,6 +71,23 @@ import pfLogoSmall from './pf-logo-small.svg';
 ```ts file='./CardSelectable.tsx'
 ```
 
+### Selectable accessibility highlight
+
+This example demonstrates how the `hasSelectableInput` and `onSelectableInputChange` props enable improved accessibility for selectable cards.
+
+The first card sets `hasSelectableInput` to true, which renders a checkbox input that is only visible to, and navigable by, screen readers. This input communicates to assistive technology users that a card is selectable , and the current selection state if so.
+
+By default this input will have an aria-label that corresponds to the title given to the card if using the card title component. If you don't use the card title component in your selectable card you must pass a custom aria-label for this input using the `selectableInputAriaLabel` prop.
+
+The first card also (by passing an onchange callback to `onSelectableInputChange`) enables the selection/deselection of the associated card by checking/unchecking the checkbox input.
+
+The second card does not set `hasSelectableInput` to true, so the input is not rendered. It does not communicate to screen reader users that it is selectable or if it is currently selected.
+
+To best understand this example it is encouraged that you navigate both of these cards using a screen reader.
+
+```ts file='./CardSelectableA11yHighlight.tsx'
+```
+
 ### With heading element
 
 ```ts file='./CardWithHeadingElement.tsx'

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

@@ -0,0 +1,61 @@
+import React from 'react';
+import { Card, CardTitle, CardBody } from '@patternfly/react-core';
+
+export const CardSelectableA11yHighlight: React.FunctionComponent = () => {
+  const [selected, setSelected] = React.useState<string>('');
+
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    if (event.target !== event.currentTarget) {
+      return;
+    }
+    if ([' ', 'Enter'].includes(event.key)) {
+      event.preventDefault();
+      const newSelected = event.currentTarget.id === selected ? null : event.currentTarget.id;
+      setSelected(newSelected);
+    }
+  };
+
+  const onClick = (event: React.MouseEvent) => {
+    const newSelected = event.currentTarget.id === selected ? null : event.currentTarget.id;
+    setSelected(newSelected);
+  };
+
+  const onChange = (labelledById: string, _event: React.FormEvent<HTMLInputElement>) => {
+    const newSelected = labelledById === selected ? null : labelledById;
+    setSelected(newSelected);
+  };
+
+  return (
+    <React.Fragment>
+      <Card
+        id="selectable-first-card"
+        onKeyDown={onKeyDown}
+        onClick={onClick}
+        hasSelectableInput
+        onSelectableInputChange={onChange}
+        isSelectableRaised
+        isSelected={selected === 'selectable-first-card'}
+      >
+        <CardTitle>Selectable card with proper accessibility considerations</CardTitle>
+        <CardBody>
+          When using a screen reader a checkbox will become navigable that indicates this card is selectable and
+          communicate if it is currently selected.
+        </CardBody>
+      </Card>
+      <br />
+      <Card
+        id="selectable-second-card"
+        onKeyDown={onKeyDown}
+        onClick={onClick}
+        isSelectableRaised
+        isSelected={selected === 'selectable-second-card'}
+      >
+        <CardTitle>Selectable card without proper accessibility considerations</CardTitle>
+        <CardBody>
+          When using a screen reader there are no indications that this card is selectable or if it is currently
+          selected.
+        </CardBody>
+      </Card>
+    </React.Fragment>
+  );
+};