@moda/om 21.6.11 → 21.6.12

package/dist/src/components/Popover/Popover.d.ts

@@ -8,6 +8,22 @@ export type PopoverProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'content'>
     zIndex?: number;
     autoPreview?: boolean;
     smoothTransitioning?: boolean;
+    /** Semantic role for the popover content (e.g., 'tooltip', 'dialog', 'menu', 'listbox') */
+    role?: 'tooltip' | 'dialog' | 'menu' | 'listbox';
+    /** Accessible label for the popover content */
+    'aria-label'?: string;
+    /** ID of element that labels the popover */
+    'aria-labelledby'?: string;
+    /** ID for the popover content */
+    popoverId?: string;
+    /** Open popover when trigger receives focus */
+    openOnFocus?: boolean;
+    /** Close popover when Escape is pressed */
+    closeOnEscape?: boolean;
+    /** Callback fired when user attempts to close (e.g., Escape key). */
+    onClose?: () => void;
+    /** Automatically focus the popover content when opened */
+    autoFocus?: boolean;
 };
 export declare const POPOVER_MOUSEOUT_DELAY_MS = 200;
 export declare const Popover: React.FC<PopoverProps>;

package/dist/src/components/Popover/Popover.stories.d.ts

@@ -4,3 +4,56 @@ declare const _default: {
 };
 export default _default;
 export declare const Default: () => React.JSX.Element;
+/**
+ * ## Accessibility
+ *
+ * The Popover component supports several accessibility props to make it usable
+ * with screen readers and keyboard navigation. **Consumers are responsible for
+ * adding ARIA attributes to their trigger elements.**
+ *
+ * ### Available Props
+ *
+ * | Prop | Type | Description |
+ * |------|------|-------------|
+ * | `role` | `'tooltip' \| 'dialog' \| 'menu' \| 'listbox'` | Semantic role for the popover content |
+ * | `aria-label` | `string` | Accessible label for the popover |
+ * | `aria-labelledby` | `string` | ID of element that labels the popover |
+ * | `popoverId` | `string` | ID for the content - use in trigger's `aria-controls` or `aria-describedby` |
+ * | `openOnFocus` | `boolean` | Open popover when trigger receives focus |
+ * | `closeOnEscape` | `boolean` | Close on Escape key (default: true) |
+ * | `onClose` | `() => void` | Callback when user attempts to close (Escape key). Required for controlled popovers. |
+ * | `autoFocus` | `boolean` | Automatically focus the popover content when opened |
+ *
+ * ### Trigger ARIA Attributes (Consumer Responsibility)
+ *
+ * For **dialogs/menus**, add to your trigger:
+ * - `aria-expanded={isOpen}`
+ * - `aria-haspopup="dialog"` (or "menu", "listbox")
+ * - `aria-controls={popoverId}` (when open)
+ *
+ * For **tooltips**, add to your trigger:
+ * - `aria-describedby={popoverId}` (when open)
+ */
+export declare const AccessibilityTooltip: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * For controlled popovers like dialogs or menus, you manage the open state
+ * and add the appropriate ARIA attributes to your trigger.
+ *
+ * Use `onClose` to handle dismiss actions (like Escape key) for controlled popovers.
+ * Use `autoFocus` to move focus into the dialog when it opens.
+ */
+export declare const AccessibilityDialog: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * Use `openOnFocus` to make hover-triggered popovers accessible to keyboard users.
+ * The popover opens when the trigger receives focus and closes when focus leaves.
+ */
+export declare const AccessibilityKeyboardNavigation: {
+    (): React.JSX.Element;
+    storyName: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda/om",
-  "version": "21.6.11",
+  "version": "21.6.12",
   "description": "Moda Operandi design system",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/src/components/Popover/Popover.stories.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { States } from '../../utilities';
 import { ControlLink } from '..';
 import { Text } from '../Text';
@@ -39,3 +39,191 @@ export const Default = () => (
     </States>
   </div>
 );
+
+/**
+ * ## Accessibility
+ *
+ * The Popover component supports several accessibility props to make it usable
+ * with screen readers and keyboard navigation. **Consumers are responsible for
+ * adding ARIA attributes to their trigger elements.**
+ *
+ * ### Available Props
+ *
+ * | Prop | Type | Description |
+ * |------|------|-------------|
+ * | `role` | `'tooltip' \| 'dialog' \| 'menu' \| 'listbox'` | Semantic role for the popover content |
+ * | `aria-label` | `string` | Accessible label for the popover |
+ * | `aria-labelledby` | `string` | ID of element that labels the popover |
+ * | `popoverId` | `string` | ID for the content - use in trigger's `aria-controls` or `aria-describedby` |
+ * | `openOnFocus` | `boolean` | Open popover when trigger receives focus |
+ * | `closeOnEscape` | `boolean` | Close on Escape key (default: true) |
+ * | `onClose` | `() => void` | Callback when user attempts to close (Escape key). Required for controlled popovers. |
+ * | `autoFocus` | `boolean` | Automatically focus the popover content when opened |
+ *
+ * ### Trigger ARIA Attributes (Consumer Responsibility)
+ *
+ * For **dialogs/menus**, add to your trigger:
+ * - `aria-expanded={isOpen}`
+ * - `aria-haspopup="dialog"` (or "menu", "listbox")
+ * - `aria-controls={popoverId}` (when open)
+ *
+ * For **tooltips**, add to your trigger:
+ * - `aria-describedby={popoverId}` (when open)
+ */
+export const AccessibilityTooltip = () => (
+  <div style={{ textAlign: 'center', padding: '2rem' }}>
+    <Text>Hover or focus the button to see a tooltip. Press Escape to dismiss.</Text>
+    <br />
+    <br />
+    <Popover
+      role='tooltip'
+      popoverId='price-tooltip'
+      aria-label='Price explanation'
+      openOnFocus
+      content={
+        <div style={{ padding: '0.5rem', maxWidth: '200px' }}>
+          <Text>
+            This is the estimated total you&apos;ll pay at checkout, including taxes and shipping.
+          </Text>
+        </div>
+      }
+    >
+      <button
+        type='button'
+        aria-describedby='price-tooltip'
+        style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+      >
+        Est. Total (?)
+      </button>
+    </Popover>
+  </div>
+);
+
+AccessibilityTooltip.storyName = 'Accessibility: Tooltip';
+
+/**
+ * For controlled popovers like dialogs or menus, you manage the open state
+ * and add the appropriate ARIA attributes to your trigger.
+ *
+ * Use `onClose` to handle dismiss actions (like Escape key) for controlled popovers.
+ * Use `autoFocus` to move focus into the dialog when it opens.
+ */
+export const AccessibilityDialog = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div style={{ textAlign: 'center', padding: '2rem' }}>
+      <Text>Click the button to open a dialog. Press Escape or click Close to dismiss.</Text>
+      <br />
+      <br />
+      <Popover
+        role='dialog'
+        popoverId='cart-dialog'
+        aria-label='Shopping bag contents'
+        open={open}
+        onClose={() => setOpen(false)}
+        autoFocus
+        content={
+          <div style={{ padding: '1rem', width: '250px' }}>
+            <Text treatment='h4'>Your Bag</Text>
+            <hr />
+            <Text>2 items in your bag</Text>
+            <br />
+            <button
+              type='button'
+              onClick={() => setOpen(false)}
+              style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+            >
+              Close
+            </button>
+          </div>
+        }
+      >
+        <button
+          type='button'
+          onClick={() => setOpen(!open)}
+          aria-expanded={open}
+          aria-haspopup='dialog'
+          aria-controls={open ? 'cart-dialog' : undefined}
+          style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+        >
+          Shopping Bag (2)
+        </button>
+      </Popover>
+    </div>
+  );
+};
+
+AccessibilityDialog.storyName = 'Accessibility: Dialog';
+
+/**
+ * Use `openOnFocus` to make hover-triggered popovers accessible to keyboard users.
+ * The popover opens when the trigger receives focus and closes when focus leaves.
+ */
+export const AccessibilityKeyboardNavigation = () => (
+  <div style={{ textAlign: 'center', padding: '2rem' }}>
+    <Text>Tab to each button to see the popover open on focus.</Text>
+    <br />
+    <br />
+    <div style={{ display: 'flex', gap: '2rem', justifyContent: 'center' }}>
+      <Popover
+        role='tooltip'
+        popoverId='info-1'
+        openOnFocus
+        content={
+          <div style={{ padding: '0.5rem' }}>
+            <Text>First item info</Text>
+          </div>
+        }
+      >
+        <button
+          type='button'
+          aria-describedby='info-1'
+          style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+        >
+          Item 1
+        </button>
+      </Popover>
+
+      <Popover
+        role='tooltip'
+        popoverId='info-2'
+        openOnFocus
+        content={
+          <div style={{ padding: '0.5rem' }}>
+            <Text>Second item info</Text>
+          </div>
+        }
+      >
+        <button
+          type='button'
+          aria-describedby='info-2'
+          style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+        >
+          Item 2
+        </button>
+      </Popover>
+
+      <Popover
+        role='tooltip'
+        popoverId='info-3'
+        openOnFocus
+        content={
+          <div style={{ padding: '0.5rem' }}>
+            <Text>Third item info</Text>
+          </div>
+        }
+      >
+        <button
+          type='button'
+          aria-describedby='info-3'
+          style={{ padding: '0.5rem 1rem', cursor: 'pointer' }}
+        >
+          Item 3
+        </button>
+      </Popover>
+    </div>
+  </div>
+);
+
+AccessibilityKeyboardNavigation.storyName = 'Accessibility: Keyboard Navigation';

package/src/components/Popover/Popover.tsx

@@ -10,6 +10,22 @@ export type PopoverProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'content'>
   zIndex?: number;
   autoPreview?: boolean;
   smoothTransitioning?: boolean;
+  /** Semantic role for the popover content (e.g., 'tooltip', 'dialog', 'menu', 'listbox') */
+  role?: 'tooltip' | 'dialog' | 'menu' | 'listbox';
+  /** Accessible label for the popover content */
+  'aria-label'?: string;
+  /** ID of element that labels the popover */
+  'aria-labelledby'?: string;
+  /** ID for the popover content */
+  popoverId?: string;
+  /** Open popover when trigger receives focus */
+  openOnFocus?: boolean;
+  /** Close popover when Escape is pressed */
+  closeOnEscape?: boolean;
+  /** Callback fired when user attempts to close (e.g., Escape key). */
+  onClose?: () => void;
+  /** Automatically focus the popover content when opened */
+  autoFocus?: boolean;
 };
 
 export const POPOVER_MOUSEOUT_DELAY_MS = 200;
@@ -35,6 +51,14 @@ export const Popover: React.FC<PopoverProps> = ({
   zIndex,
   autoPreview = false,
   smoothTransitioning = false,
+  role,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledby,
+  popoverId,
+  openOnFocus = false,
+  closeOnEscape = true,
+  onClose,
+  autoFocus = false,
   ...rest
 }) => {
   const [mode, setMode] = useState(() => {
@@ -54,6 +78,7 @@ export const Popover: React.FC<PopoverProps> = ({
   });
 
   const timeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
 
   const handleOpen = useCallback(() => {
     if (smoothTransitioning) setMode(Mode.Opening);
@@ -80,6 +105,36 @@ export const Popover: React.FC<PopoverProps> = ({
     timeout.current = setTimeout(handleClose, POPOVER_MOUSEOUT_DELAY_MS);
   }, [handleClose, open]);
 
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (closeOnEscape && event.key === 'Escape') {
+        onClose?.();
+        handleClose();
+        event.preventDefault();
+      }
+    },
+    [closeOnEscape, onClose, handleClose]
+  );
+
+  const handleFocus = useCallback(() => {
+    if (openOnFocus && open === undefined) {
+      if (timeout.current) clearTimeout(timeout.current);
+      handleOpen();
+    }
+  }, [openOnFocus, open, handleOpen]);
+
+  const handleBlur = useCallback(
+    (event: React.FocusEvent) => {
+      if (openOnFocus && open === undefined) {
+        // Only close if focus moved outside the popover entirely
+        if (!event.currentTarget.contains(event.relatedTarget)) {
+          timeout.current = setTimeout(handleClose, POPOVER_MOUSEOUT_DELAY_MS);
+        }
+      }
+    },
+    [openOnFocus, open, handleClose]
+  );
+
   useEffect(() => {
     if (mode !== Mode.Closing) return;
 
@@ -125,11 +180,20 @@ export const Popover: React.FC<PopoverProps> = ({
   const isOpen =
     mode === Mode.AutoOpen || mode === Mode.Opening || mode === Mode.Open || mode === Mode.Closing;
 
+  useEffect(() => {
+    if (autoFocus && isOpen && contentRef.current) {
+      contentRef.current.focus();
+    }
+  }, [autoFocus, isOpen]);
+
   return (
     <div
       className={classNames(`Popover Popover--anchor-${anchor}`, className)}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}
+      onBlur={handleBlur}
       {...rest}
     >
       <span className='Popover__trigger'>
@@ -142,10 +206,20 @@ export const Popover: React.FC<PopoverProps> = ({
           >
             <div
               className='Popover__caret'
+              aria-hidden='true'
               style={{ zIndex: zIndex != null ? zIndex + 1 : undefined }}
             />
 
-            <div className='Popover__content' style={{ zIndex }}>
+            <div
+              ref={contentRef}
+              id={popoverId}
+              role={role}
+              aria-label={ariaLabel}
+              aria-labelledby={ariaLabelledby}
+              tabIndex={autoFocus ? -1 : undefined}
+              className='Popover__content'
+              style={{ zIndex }}
+            >
               {content}
             </div>
           </div>