@astryxdesign/core 0.1.2 → 0.1.3

package/src/DateInput/DateInput.test.tsx

@@ -9,9 +9,12 @@
  * SYNC: When DateInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {DateInput} from './DateInput';
+import {InputGroup} from '../InputGroup';
+import {InputGroupText} from '../InputGroup/InputGroupText';
 
 describe('DateInput', () => {
   it('renders with label', () => {
@@ -110,6 +113,43 @@ describe('DateInput', () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
+  it('sets aria-invalid="true" when typed input is unparseable', () => {
+    render(<DateInput label="Date" onChange={() => {}} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: '13/45/2024'}});
+
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('does not set aria-invalid when typed input is a valid date', () => {
+    render(<DateInput label="Date" onChange={() => {}} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: '03/15/2026'}});
+
+    expect(input).not.toHaveAttribute('aria-invalid');
+  });
+
+  it('announces an alert message when typed input is invalid', () => {
+    render(<DateInput label="Date" onChange={() => {}} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: '13/45/2024'}});
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Invalid date');
+  });
+
+  it('does not announce an alert message when input is valid', () => {
+    render(<DateInput label="Date" onChange={() => {}} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: '03/15/2026'}});
+
+    expect(screen.getByRole('alert')).toHaveTextContent('');
+    expect(screen.queryByText('Invalid date')).not.toBeInTheDocument();
+  });
+
   it('reverts to previous value on blur when input is invalid', async () => {
     const onChange = vi.fn();
     render(<DateInput label="Date" value="2026-01-25" onChange={onChange} />);
@@ -280,6 +320,28 @@ describe('DateInput', () => {
     );
   });
 
+  it('opens the calendar popover on ArrowDown (keyboard, forms-13)', () => {
+    render(<DateInput label="Date" onChange={() => {}} />);
+    const input = screen.getByRole('combobox');
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('opens the calendar popover on Alt+ArrowDown (keyboard, forms-13)', () => {
+    render(<DateInput label="Date" onChange={() => {}} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.keyDown(input, {key: 'ArrowDown', altKey: true});
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('does not open on ArrowDown when disabled', () => {
+    render(<DateInput label="Date" isDisabled onChange={() => {}} />);
+    const input = screen.getByRole('combobox');
+    fireEvent.keyDown(input, {key: 'ArrowDown'});
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+  });
+
   it('input has aria-haspopup="dialog"', () => {
     render(<DateInput label="Date" onChange={() => {}} />);
     expect(screen.getByRole('combobox')).toHaveAttribute(
@@ -585,4 +647,188 @@ describe('DateInput', () => {
       expect(input).toHaveValue('March 20, 2026');
     });
   });
+
+  describe('InputGroup', () => {
+    it('uses group ARIA and skips standalone Field chrome when grouped', () => {
+      render(
+        <InputGroup
+          label="Availability"
+          description="Choose a start date"
+          status={{type: 'error', message: 'Date is required'}}>
+          <InputGroupText>Starts</InputGroupText>
+          <DateInput label="Date" isLabelHidden onChange={() => {}} />
+        </InputGroup>,
+      );
+
+      const group = screen.getByRole('group', {name: 'Availability'});
+      const input = screen.getByRole('combobox', {
+        name: 'Availability Date',
+      });
+
+      expect(document.querySelectorAll('.astryx-field')).toHaveLength(1);
+      expect(input).toHaveAttribute('aria-labelledby');
+      expect(input.getAttribute('aria-labelledby')).toContain(
+        group.getAttribute('aria-labelledby'),
+      );
+      expect(input).toHaveAttribute(
+        'aria-describedby',
+        group.getAttribute('aria-describedby'),
+      );
+      expect(input).not.toHaveAttribute('aria-invalid');
+      expect(screen.getByText('Date is required')).toBeInTheDocument();
+    });
+
+    it('preserves disabledMessage tooltip wiring when grouped', () => {
+      render(
+        <InputGroup label="Availability">
+          <InputGroupText>Starts</InputGroupText>
+          <DateInput
+            label="Date"
+            isLabelHidden
+            isDisabled
+            disabledMessage="Scheduling is locked"
+            onChange={() => {}}
+          />
+        </InputGroup>,
+      );
+
+      const input = screen.getByRole('combobox', {name: 'Availability Date'});
+      const tooltip = screen.getByRole('tooltip', {hidden: true});
+
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
+      expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+      expect(tooltip).toHaveTextContent('Scheduling is locked');
+      expect(
+        screen.getByRole('button', {name: 'Open calendar'}),
+      ).toBeDisabled();
+    });
+  });
+
+  describe('disabledMessage', () => {
+    // jsdom does not implement the Popover API used by the tooltip, so mock
+    // showPopover/hidePopover to toggle a `popover-open` attribute the tests
+    // can assert on.
+    beforeEach(() => {
+      HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+        this.setAttribute('popover-open', '');
+      });
+      HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+        this.removeAttribute('popover-open');
+      });
+    });
+
+    // jsdom popover content is in the DOM but not "visible" in the
+    // accessibility tree; use hidden: true to find it.
+    const h = {hidden: true} as const;
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <DateInput
+          label="Date"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const container = screen.getByRole('combobox')
+        .parentElement as HTMLElement;
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need the Editor role');
+
+      fireEvent.mouseEnter(container);
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+
+      fireEvent.mouseLeave(container);
+      await waitFor(() => {
+        expect(tooltip).not.toHaveAttribute('popover-open');
+      });
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <DateInput
+          label="Date"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <DateInput label="Date" disabledMessage="You need the Editor role" />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(<DateInput label="Date" isDisabled />);
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <DateInput
+          label="Date"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
+      expect(input).toHaveAttribute('readonly');
+    });
+
+    it('links the reason tooltip from the input via aria-describedby', () => {
+      render(
+        <DateInput
+          label="Date"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks value changes and opening while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <DateInput
+          label="Date"
+          onChange={onChange}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      await user.click(input);
+      await user.type(input, '2026-03-15');
+      expect(input).toHaveValue('');
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(<DateInput label="Date" isDisabled />);
+      const input = screen.getByRole('combobox');
+      expect(input).toBeDisabled();
+      expect(input).not.toHaveAttribute('aria-disabled');
+    });
+  });
 });

package/src/DateInput/DateInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file DateInput.tsx
- * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, Calendar, usePopover
+ * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, Calendar, usePopover, InputGroupContext
  * @output Exports DateInput component, DateInputProps
  * @position Core implementation; consumed by index.ts, tested by DateInput.test.tsx
  *
@@ -44,15 +44,16 @@ import {
   inputStatusFocusWithinStyles,
 } from '../Field';
 import {Icon} from '../Icon';
+import {VisuallyHidden} from '../VisuallyHidden';
+import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {groupStyles} from '../InputGroup/groupStyles';
+import {useSize} from '../SizeContext/SizeContext';
 import {Spinner} from '../Spinner';
-import {
-  Calendar,
-  type ISODateString,
-  type CalendarHandle,
-} from '../Calendar';
+import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';
 import {useCalendarConstraints} from '../Calendar/hooks';
 import {usePopover} from '../Popover';
-import {parseDateInput} from '../utils';
+import {useTooltip} from '../Tooltip';
+import {getInputARIA, parseDateInput} from '../utils';
 import {
   plainDateFromISO,
   plainDateToISO,
@@ -177,6 +178,29 @@ export interface DateInputProps extends Omit<
    */
   isDisabled?: boolean;
 
+  /**
+   * Explains why the input is disabled. When set together with
+   * `isDisabled`, the input shows a tooltip with this text on hover and
+   * keyboard focus, and the field stays focusable (via `aria-disabled`)
+   * so the reason is discoverable by keyboard and assistive technology.
+   * Typing and calendar activation stay blocked.
+   *
+   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <DateInput
+   *   label="Event date"
+   *   value={date}
+   *   onChange={setDate}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
+
   /**
    * The selected date in ISO format (YYYY-MM-DD).
    */
@@ -279,6 +303,7 @@ export function DateInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   value,
   onChange,
   changeAction,
@@ -287,7 +312,7 @@ export function DateInput({
   max,
   dateConstraints,
   placeholder = 'Select a date',
-  size = 'md',
+  size: sizeProp,
   status,
   labelTooltip,
   hasClear = false,
@@ -299,18 +324,37 @@ export function DateInput({
   ref,
   ...rest
 }: DateInputProps) {
+  const size = useSize(sizeProp, 'md');
   const id = useId();
+  const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
   const calendarRef = useRef<CalendarHandle | null>(null);
   const lastFiredValueRef = useRef<ISODateString | undefined>(undefined);
+  const inputGroup = useInputGroup();
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input container (which already exists) and
+  // the text input stays perceivable via aria-disabled instead of the disabled
+  // attribute. Typing is blocked with readOnly and value mutation guards;
+  // calendar activation is blocked by the isEffectivelyDisabled guards. Only
+  // the persistent isDisabled state (not the transient busy state) surfaces a
+  // reason.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   // Status icon mapping
   const statusIconMap: Record<InputStatusType, IconName> = {
     warning: 'warning',
@@ -330,13 +374,15 @@ export function DateInput({
   // Constraint checking for text input validation (reuses calendar logic)
   const {isDateDisabled} = useCalendarConstraints({min, max, dateConstraints});
 
-  const ariaDescribedBy =
+  const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
+    inputLabelID,
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
-    ]
-      .filter(Boolean)
-      .join(' ') || undefined;
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+    ],
+    inputGroup,
+  );
 
   // Pending input while user is typing (null = show formatted value)
   const [pendingInput, setPendingInput] = useState<string | null>(null);
@@ -428,6 +474,11 @@ export function DateInput({
   // Handle input text change - update immediately if valid and allowed
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
+      // With a disabledMessage the input drops `disabled` for focusability, so
+      // guard value mutation explicitly (readOnly also blocks typing).
+      if (isEffectivelyDisabled) {
+        return;
+      }
       const newValue = e.target.value;
       setPendingInput(newValue);
 
@@ -445,7 +496,7 @@ export function DateInput({
         calendarRef.current?.navigateTo(parsedISO);
       }
     },
-    [value, fireChange, isDateDisabled],
+    [value, fireChange, isDateDisabled, isEffectivelyDisabled],
   );
 
   // Commit pending input (shared by blur and Enter key)
@@ -483,14 +534,144 @@ export function DateInput({
       if (e.key === 'Escape' && popover.isOpen) {
         e.preventDefault();
         popover.hide();
+      } else if (
+        (e.key === 'ArrowDown' || (e.altKey && e.key === 'ArrowDown')) &&
+        !popover.isOpen
+      ) {
+        // APG combobox: ArrowDown (and Alt+ArrowDown) opens the calendar
+        // popover from the keyboard, keeping focus in the input (forms-13).
+        e.preventDefault();
+        if (!isEffectivelyDisabled) {
+          popover.show({skipAutoFocus: true});
+        }
       } else if (e.key === 'Enter') {
         e.preventDefault();
         commitPendingInput();
       }
     },
-    [popover, commitPendingInput],
+    [popover, commitPendingInput, isEffectivelyDisabled],
+  );
+
+  const inputWrapper = (
+    <div
+      ref={el => {
+        popover.triggerRef(el);
+        // Anchor + hover/focus listeners for the disabled-message tooltip.
+        // Handlers are gated internally by isEnabled, and anchor names
+        // compose, so attaching unconditionally is safe.
+        disabledMessageTooltip.ref(el);
+      }}
+      {...rest}
+      {...mergeProps(
+        themeProps('date-input', {size, status: status?.type ?? null}),
+        stylex.props(
+          inputWrapperStyles.base,
+          sizeStyles[size],
+          isEffectivelyDisabled && inputWrapperStyles.disabled,
+          status && inputStatusBorderStyles[status.type],
+          status && inputStatusHoverShadowStyles[status.type],
+          status && inputStatusFocusWithinStyles[status.type],
+          inputGroup && groupStyles.inGroup,
+          xstyle,
+        ),
+        className,
+        style,
+      )}>
+      {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
+      <button
+        type="button"
+        onClick={handleToggle}
+        disabled={isEffectivelyDisabled}
+        aria-label={popover.isOpen ? 'Close calendar' : 'Open calendar'}
+        {...stylex.props(
+          styles.iconButton,
+          isEffectivelyDisabled && styles.iconButtonDisabled,
+        )}>
+        <Icon icon="calendar" size="sm" color="secondary" />
+      </button>
+      <input
+        ref={mergeRefs(ref, inputRef)}
+        id={id}
+        type="text"
+        role="combobox"
+        value={displayValue}
+        onChange={handleInputChange}
+        onBlur={handleBlur}
+        onClick={handleInputClick}
+        onKeyDown={handleInputKeyDown}
+        placeholder={placeholder}
+        // With a disabledMessage the input keeps focusability via
+        // aria-disabled so the reason is focus-discoverable; typing is
+        // blocked with readOnly and the mutation guards, and calendar
+        // activation is blocked by the isEffectivelyDisabled guards.
+        disabled={isEffectivelyDisabled && !showsDisabledMessage}
+        aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        readOnly={showsDisabledMessage || undefined}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        aria-required={isRequired === true ? 'true' : undefined}
+        aria-invalid={
+          status?.type === 'error' || !isInputValid ? 'true' : undefined
+        }
+        aria-busy={isBusy || undefined}
+        aria-expanded={popover.isOpen}
+        aria-haspopup="dialog"
+        aria-controls={popover.isOpen ? popover.id : undefined}
+        aria-autocomplete="none"
+        autoComplete="off"
+        {...stylex.props(
+          styles.input,
+          isEffectivelyDisabled && styles.inputDisabled,
+          !isInputValid && styles.inputInvalid,
+        )}
+      />
+      {/*
+          Live region announcing invalid typed input to assistive technology.
+          The value silently reverts on blur, so without this a screen-reader
+          user would get no feedback that their entry was rejected (WCAG 3.3.1).
+        */}
+      <VisuallyHidden as="div" role="alert" aria-live="assertive">
+        {!isInputValid ? 'Invalid date' : ''}
+      </VisuallyHidden>
+      {hasClear && value !== undefined && !isEffectivelyDisabled && (
+        <button
+          type="button"
+          onClick={handleClear}
+          aria-label={`Clear ${label}`}
+          {...stylex.props(styles.iconButton)}>
+          <Icon icon="close" size="sm" color="secondary" />
+        </button>
+      )}
+      {isBusy && <Spinner size="sm" />}
+      {status && !inputGroup && (
+        <Icon
+          icon={statusIconMap[status.type]}
+          size="md"
+          color={statusIconColorMap[status.type]}
+        />
+      )}
+      {popover.render(
+        <Calendar
+          handleRef={calendarRef}
+          mode="single"
+          value={optimisticValue}
+          onChange={handleDateSelect}
+          min={min}
+          max={max}
+          dateConstraints={dateConstraints}
+          numberOfMonths={numberOfMonths}
+        />,
+        {placement: 'below', alignment: 'start'},
+      )}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
+    </div>
   );
 
+  if (inputGroup) {
+    return inputWrapper;
+  }
+
   return (
     <Field
       label={label}
@@ -512,92 +693,7 @@ export function DateInput({
       }
       labelTooltip={labelTooltip}
       width={width}>
-      <div
-        ref={popover.triggerRef}
-        {...rest}
-        {...mergeProps(
-          themeProps('date-input', {size, status: status?.type ?? null}),
-          stylex.props(
-            inputWrapperStyles.base,
-            sizeStyles[size],
-            isEffectivelyDisabled && inputWrapperStyles.disabled,
-            status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
-            status && inputStatusFocusWithinStyles[status.type],
-            xstyle,
-          ),
-          className,
-          style,
-        )}>
-        <button
-          type="button"
-          onClick={handleToggle}
-          disabled={isEffectivelyDisabled}
-          aria-label={popover.isOpen ? 'Close calendar' : 'Open calendar'}
-          {...stylex.props(
-            styles.iconButton,
-            isEffectivelyDisabled && styles.iconButtonDisabled,
-          )}>
-          <Icon icon="calendar" size="sm" color="secondary" />
-        </button>
-        <input
-          ref={mergeRefs(ref, inputRef)}
-          id={id}
-          type="text"
-          role="combobox"
-          value={displayValue}
-          onChange={handleInputChange}
-          onBlur={handleBlur}
-          onClick={handleInputClick}
-          onKeyDown={handleInputKeyDown}
-          placeholder={placeholder}
-          disabled={isEffectivelyDisabled}
-          aria-describedby={ariaDescribedBy}
-          aria-required={isRequired === true ? 'true' : undefined}
-          aria-invalid={status?.type === 'error' ? 'true' : undefined}
-          aria-busy={isBusy || undefined}
-          aria-expanded={popover.isOpen}
-          aria-haspopup="dialog"
-          aria-controls={popover.isOpen ? popover.id : undefined}
-          aria-autocomplete="none"
-          autoComplete="off"
-          {...stylex.props(
-            styles.input,
-            isEffectivelyDisabled && styles.inputDisabled,
-            !isInputValid && styles.inputInvalid,
-          )}
-        />
-        {hasClear && value !== undefined && !isEffectivelyDisabled && (
-          <button
-            type="button"
-            onClick={handleClear}
-            aria-label={`Clear ${label}`}
-            {...stylex.props(styles.iconButton)}>
-            <Icon icon="close" size="sm" color="secondary" />
-          </button>
-        )}
-        {isBusy && <Spinner size="sm" />}
-        {status && (
-          <Icon
-            icon={statusIconMap[status.type]}
-            size="md"
-            color={statusIconColorMap[status.type]}
-          />
-        )}
-      </div>
-      {popover.render(
-        <Calendar
-          handleRef={calendarRef}
-          mode="single"
-          value={optimisticValue}
-          onChange={handleDateSelect}
-          min={min}
-          max={max}
-          dateConstraints={dateConstraints}
-          numberOfMonths={numberOfMonths}
-        />,
-        {placement: 'below', alignment: 'start'},
-      )}
+      {inputWrapper}
     </Field>
   );
 }