@moda/om 21.6.10 → 21.6.12

package/dist/src/components/Field/FormControlContext.d.ts

@@ -0,0 +1,6 @@
+type FormControlContextValue = {
+    displaysError: boolean;
+};
+export declare const FormControlContext: import("react").Context<FormControlContextValue>;
+export declare const useFormControlContext: () => FormControlContextValue;
+export {};

package/dist/src/components/Field/index.d.ts

@@ -1,3 +1,4 @@
 import { Field } from './Field';
 export { Field as Input };
 export * from './Field';
+export * from './FormControlContext';

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.10",
+  "version": "21.6.12",
   "description": "Moda Operandi design system",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/src/components/Field/Field.tsx

@@ -1,8 +1,9 @@
-import React, { JSX } from 'react';
+import React, { JSX, useMemo } from 'react';
 import classNames from 'classnames';
 import WarningIcon from '@moda/icons/warning-16';
 import { TextInput, TextInputProps } from '../TextInput';
 import { Select } from '../Select';
+import { FormControlContext } from './FormControlContext';
 
 import './Field.scss';
 
@@ -15,50 +16,54 @@ export const Field = React.forwardRef(
     { className, children, error, label, placeholder, ...rest }: FieldProps,
     ref: React.Ref<HTMLInputElement>
   ) => {
+    const fieldContextValue = useMemo(() => ({ displaysError: Boolean(error) }), [error]);
+
     return (
-      <label className={classNames('Field', className)}>
-        {label && <span className='Field__label'>{label}</span>}
+      <FormControlContext.Provider value={fieldContextValue}>
+        <label className={classNames('Field', className)}>
+          {label && <span className='Field__label'>{label}</span>}
 
-        {/* TODO: Codify some kind of IconWrapper component */}
-        <span className='Field__context'>
-          {children ? (
-            <>
-              {React.cloneElement(children, {
-                ref,
-                error,
-                placeholder,
-                label,
-                shiftIconLeftwards: error && children.type === Select,
-                ...rest,
-                ...children.props
-              })}
+          {/* TODO: Codify some kind of IconWrapper component */}
+          <span className='Field__context'>
+            {children ? (
+              <>
+                {React.cloneElement(children, {
+                  ref,
+                  error,
+                  placeholder,
+                  label,
+                  shiftIconLeftwards: error && children.type === Select,
+                  ...rest,
+                  ...children.props
+                })}
 
-              {error && (
-                <span className='Field__icon'>
-                  <WarningIcon />
-                </span>
-              )}
-            </>
-          ) : (
-            <>
-              <TextInput
-                ref={ref}
-                placeholder={placeholder}
-                label={label}
-                error={error}
-                {...rest}
-              />
-              {error && (
-                <span className='Field__icon'>
-                  <WarningIcon />
-                </span>
-              )}
-            </>
-          )}
-        </span>
+                {error && (
+                  <span className='Field__icon'>
+                    <WarningIcon />
+                  </span>
+                )}
+              </>
+            ) : (
+              <>
+                <TextInput
+                  ref={ref}
+                  placeholder={placeholder}
+                  label={label}
+                  error={error}
+                  {...rest}
+                />
+                {error && (
+                  <span className='Field__icon'>
+                    <WarningIcon />
+                  </span>
+                )}
+              </>
+            )}
+          </span>
 
-        {error && <span className='Field__error'>{error}</span>}
-      </label>
+          {error && <span className='Field__error'>{error}</span>}
+        </label>
+      </FormControlContext.Provider>
     );
   }
 );

package/src/components/Field/FormControlContext.tsx

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+
+type FormControlContextValue = {
+  displaysError: boolean;
+};
+
+export const FormControlContext = createContext<FormControlContextValue>({
+  displaysError: false
+});
+
+export const useFormControlContext = () => useContext(FormControlContext);

package/src/components/Field/index.ts

@@ -2,3 +2,4 @@ import { Field } from './Field';
 
 export { Field as Input };
 export * from './Field';
+export * from './FormControlContext';

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>

package/src/components/Select/Select.tsx

@@ -5,6 +5,7 @@ import ChevronUpIcon from '@moda/icons/chevron-up-12';
 import { colors } from '@moda/tokens';
 import { Clickable } from '../Clickable';
 import { TextColor } from '../Text';
+import { useFormControlContext } from '../Field/FormControlContext';
 import { SelectOptions } from './SelectOptions';
 import { SelectLabel } from './SelectLabel';
 import { useSelect } from './useSelect';
@@ -75,6 +76,7 @@ export const Select: React.FC<SelectProps> = ({
   smallMobileText = false,
   ...rest
 }) => {
+  const { displaysError: errorDisplayedByParent } = useFormControlContext();
   const { state, dispatch, Mode, selectRef, buttonRef } = useSelect({
     value,
     defaultValue
@@ -207,7 +209,7 @@ export const Select: React.FC<SelectProps> = ({
         )}
       </div>
 
-      {typeof error === 'string' && (
+      {typeof error === 'string' && !errorDisplayedByParent && (
         <div role='status' aria-live='polite' aria-atomic='true' className='Select__live-region'>
           {error}
         </div>