@astryxdesign/core 0.1.2 → 0.1.3

package/src/TimeInput/TimeInput.test.tsx

@@ -9,10 +9,11 @@
  * SYNC: When TimeInput.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 {TimeInput} from './TimeInput';
+import {InputGroup, InputGroupText} from '../InputGroup';
 import type {ISOTimeString} from '../utils';
 
 describe('TimeInput', () => {
@@ -23,11 +24,7 @@ describe('TimeInput', () => {
 
   it('renders with placeholder', () => {
     render(
-      <TimeInput
-        label="Time"
-        onChange={() => {}}
-        placeholder="Pick a time"
-      />,
+      <TimeInput label="Time" onChange={() => {}} placeholder="Pick a time" />,
     );
     expect(screen.getByPlaceholderText('Pick a time')).toBeInTheDocument();
   });
@@ -210,4 +207,255 @@ describe('TimeInput', () => {
     fireEvent.click(wrapper);
     expect(input).toHaveFocus();
   });
+  describe('InputGroup integration', () => {
+    it('labels grouped TimeInput from the group and inner input labels', () => {
+      render(
+        <InputGroup label="Schedule" description="Use local time">
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+          />
+        </InputGroup>,
+      );
+
+      const group = screen.getByRole('group', {name: 'Schedule'});
+      const groupLabelID = group.getAttribute('aria-labelledby');
+      const input = screen.getByRole('textbox', {
+        name: 'Schedule Start time',
+      });
+      const labelledByIDs =
+        input.getAttribute('aria-labelledby')?.split(' ') ?? [];
+
+      expect(labelledByIDs).toHaveLength(2);
+      expect(labelledByIDs[0]).toBe(groupLabelID);
+      expect(document.getElementById(labelledByIDs[1])).toHaveTextContent(
+        'Start time',
+      );
+      expect(input).not.toHaveAttribute('aria-label');
+      expect(input).toHaveAttribute(
+        'aria-describedby',
+        group.getAttribute('aria-describedby'),
+      );
+    });
+
+    it('includes group and local described-by content when grouped', () => {
+      render(
+        <InputGroup
+          label="Schedule"
+          description="Use local time"
+          status={{type: 'warning', message: 'Schedule is unusual'}}>
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+            description="Business hours only"
+            status={{type: 'error', message: 'Start time is required'}}
+            isDisabled
+            disabledMessage="Time edits are locked"
+          />
+        </InputGroup>,
+      );
+
+      const input = screen.getByRole('textbox', {
+        name: 'Schedule Start time',
+      });
+      const describedByIDs =
+        input.getAttribute('aria-describedby')?.split(' ') ?? [];
+      const describedText = describedByIDs
+        .map(id => document.getElementById(id)?.textContent)
+        .join(' ');
+
+      expect(describedText).toContain('Use local time');
+      expect(describedText).toContain('Schedule is unusual');
+      expect(describedText).toContain('Business hours only');
+      expect(describedText).toContain('Start time is required');
+      expect(describedText).toContain('Time edits are locked');
+    });
+
+    it('does not render duplicate Field label chrome when grouped', () => {
+      render(
+        <InputGroup label="Schedule">
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+          />
+        </InputGroup>,
+      );
+
+      expect(screen.getByText('Schedule')).toBeInTheDocument();
+      expect(screen.getByText('Start time')).toBeInTheDocument();
+      expect(screen.getByText('Start time').tagName).toBe('SPAN');
+      expect(document.querySelector('label')).toBeNull();
+    });
+
+    it('suppresses the local status icon when grouped', () => {
+      const {container} = render(
+        <InputGroup label="Schedule">
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+            status={{type: 'error'}}
+          />
+        </InputGroup>,
+      );
+
+      // The clock icon remains, but the trailing status icon is suppressed in
+      // grouped mode so the shared InputGroup border/status treatment is not
+      // duplicated.
+      expect(container.querySelectorAll('svg')).toHaveLength(1);
+    });
+  });
+
+  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(
+        <TimeInput
+          label="Time"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const container = screen.getByLabelText('Time')
+        .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(
+        <TimeInput
+          label="Time"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByLabelText('Time')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <TimeInput label="Time" 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(<TimeInput label="Time" isDisabled />);
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <TimeInput
+          label="Time"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByLabelText('Time');
+      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(
+        <TimeInput
+          label="Time"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByLabelText('Time');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks typing and arrow-key changes while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <TimeInput
+          label="Time"
+          onChange={onChange}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const input = screen.getByLabelText('Time');
+      await user.type(input, '2:30 PM');
+      expect(input).toHaveValue('');
+      input.focus();
+      fireEvent.keyDown(input, {key: 'ArrowUp'});
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(<TimeInput label="Time" isDisabled />);
+      const input = screen.getByLabelText('Time');
+      expect(input).toBeDisabled();
+      expect(input).not.toHaveAttribute('aria-disabled');
+    });
+
+    it('does not swap in the format-hint placeholder on focus while disabled', () => {
+      render(
+        <TimeInput
+          label="Time"
+          isDisabled
+          disabledMessage="You need the Editor role"
+          placeholder="Select a time"
+        />,
+      );
+      const input = screen.getByLabelText('Time');
+      input.focus();
+      fireEvent.focus(input);
+      expect(input).toHaveAttribute('placeholder', 'Select a time');
+    });
+  });
 });

package/src/TimeInput/TimeInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file TimeInput.tsx
- * @input Uses React, useId, useState, useEffect, useCallback, useRef, Field, Icon
+ * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, InputGroupContext
  * @output Exports TimeInput component, TimeInputProps
  * @position Core implementation; consumed by index.ts, tested by TimeInput.test.tsx
  *
@@ -48,6 +48,7 @@ import {
 } from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {
   type ISOTimeString,
   parseTimeInput,
@@ -58,11 +59,15 @@ import {
   isTimeInRange,
   mergeProps,
   mergeRefs,
+  getInputARIA,
 } from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {groupStyles} from '../InputGroup/groupStyles';
+import {useTooltip} from '../Tooltip';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -183,6 +188,29 @@ export interface TimeInputProps 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 arrow-key adjustment 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
+   * ```
+   * <TimeInput
+   *   label="Start time"
+   *   value={time}
+   *   onChange={setTime}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
+
   /**
    * The selected time in ISO format (HH:MM or HH:MM:SS).
    */
@@ -301,6 +329,7 @@ export function TimeInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   value,
   onChange,
   changeAction,
@@ -325,15 +354,30 @@ export function TimeInput({
   const size = useSize(sizeProp, 'md');
 
   const id = useId();
+  const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
+  const inputGroup = useInputGroup();
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input container (which already exists) and
+  // the input stays perceivable via aria-disabled instead of the disabled
+  // attribute. Typing is blocked with readOnly and value mutation guards.
+  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',
@@ -350,13 +394,15 @@ export function TimeInput({
     success: 'success',
   };
 
-  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);
@@ -415,6 +461,11 @@ export function TimeInput({
   // Handle input text change - update immediately if valid
   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 (isDisabled) {
+        return;
+      }
       const newValue = e.target.value;
       setPendingInput(newValue);
 
@@ -424,13 +475,19 @@ export function TimeInput({
         fireChange(parsed);
       }
     },
-    [hasSeconds, min, max, value, fireChange],
+    [hasSeconds, min, max, value, fireChange, isDisabled],
   );
 
   // Handle focus
   const handleFocus = useCallback(() => {
+    // A disabled input stays focusable (via aria-disabled) so its reason is
+    // discoverable, but it must not present editing affordances — keep the
+    // static placeholder rather than swapping in the format hint.
+    if (isDisabled) {
+      return;
+    }
     setIsFocused(true);
-  }, []);
+  }, [isDisabled]);
 
   // Handle blur - validate and clear pending input
   const handleBlur = useCallback(
@@ -466,6 +523,11 @@ export function TimeInput({
   // Handle keyboard navigation on input
   const handleInputKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
+      // Arrow-key adjustment mutates the value; block it while showing a
+      // disabled reason (the input keeps focusability via aria-disabled).
+      if (isDisabled) {
+        return;
+      }
       if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
         e.preventDefault();
 
@@ -492,7 +554,7 @@ export function TimeInput({
         }
       }
     },
-    [value, hasSeconds, increment, min, max, fireChange],
+    [value, hasSeconds, increment, min, max, fireChange, isDisabled],
   );
 
   // Handle clear button click
@@ -509,6 +571,109 @@ export function TimeInput({
       disabled: isDisabled,
     });
 
+  const inputWrapper = (
+    <div
+      ref={el => {
+        containerRef.current = el;
+        // Anchor + hover/focus listeners for the disabled-message tooltip.
+        // Handlers are gated internally by isEnabled, so attaching
+        // unconditionally is safe.
+        disabledMessageTooltip.ref(el);
+      }}
+      onClick={handleWrapperClick}
+      onMouseUp={handleWrapperMouseUp}
+      {...mergeProps(
+        themeProps('time-input', {size, status: status?.type ?? null}),
+        stylex.props(
+          inputWrapperStyles.base,
+          sizeStyles[size],
+          isDisabled && inputWrapperStyles.disabled,
+          status && inputStatusBorderStyles[status.type],
+          status && inputStatusHoverShadowStyles[status.type],
+          status && inputStatusFocusWithinStyles[status.type],
+          inputGroup && groupStyles.inGroup,
+          xstyle,
+        ),
+        className,
+        style,
+      )}>
+      <div {...stylex.props(styles.icon)}>
+        <Icon icon="clock" size="sm" color="secondary" />
+      </div>
+      {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
+      {inputGroup && description && (
+        <VisuallyHidden as="div" id={descriptionID}>
+          {description}
+        </VisuallyHidden>
+      )}
+      {inputGroup && status?.message && (
+        <VisuallyHidden
+          as="div"
+          id={statusMessageID}
+          role={status.type === 'error' ? 'alert' : 'status'}
+          aria-live={status.type === 'error' ? 'assertive' : 'polite'}>
+          {status.message}
+        </VisuallyHidden>
+      )}
+      <input
+        ref={mergeRefs(ref, inputRef)}
+        id={id}
+        type="text"
+        value={displayValue}
+        onChange={handleInputChange}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onKeyDown={handleInputKeyDown}
+        placeholder={displayPlaceholder}
+        // With a disabledMessage the input keeps focusability via
+        // aria-disabled so the reason is focus-discoverable; typing and
+        // arrow-key adjustment are blocked with readOnly and the guards.
+        disabled={isDisabled && !showsDisabledMessage}
+        aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        readOnly={showsDisabledMessage || undefined}
+        autoFocus={hasAutoFocus}
+        data-autofocus={hasAutoFocus || undefined}
+        aria-describedby={ariaDescribedBy}
+        aria-required={isRequired === true ? 'true' : undefined}
+        aria-invalid={status?.type === 'error' ? 'true' : undefined}
+        aria-busy={isBusy || undefined}
+        aria-labelledby={ariaLabelledBy}
+        {...stylex.props(
+          styles.input,
+          isDisabled && styles.inputDisabled,
+          !isInputValid && styles.inputInvalid,
+        )}
+      />
+      {isBusy && <Spinner size="sm" />}
+      {hasClear && value && !isDisabled && (
+        <button
+          type="button"
+          onClick={handleClear}
+          aria-label={`Clear ${label}`}
+          {...stylex.props(styles.clearButton)}>
+          <Icon icon="close" size="sm" color="secondary" />
+        </button>
+      )}
+      {status && !inputGroup && (
+        <Icon
+          icon={statusIconMap[status.type]}
+          size="md"
+          color={statusIconColorMap[status.type]}
+        />
+      )}
+    </div>
+  );
+
+  if (inputGroup) {
+    return (
+      <>
+        {inputWrapper}
+        {showsDisabledMessage &&
+          disabledMessageTooltip.renderTooltip(disabledMessage)}
+      </>
+    );
+  }
+
   return (
     <Field
       label={label}
@@ -530,68 +695,9 @@ export function TimeInput({
       }
       labelTooltip={labelTooltip}
       width={width}>
-      <div
-        ref={containerRef}
-        onClick={handleWrapperClick}
-        onMouseUp={handleWrapperMouseUp}
-        {...mergeProps(
-          themeProps('time-input', {size, status: status?.type ?? null}),
-          stylex.props(
-            inputWrapperStyles.base,
-            sizeStyles[size],
-            isDisabled && inputWrapperStyles.disabled,
-            status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
-            status && inputStatusFocusWithinStyles[status.type],
-            xstyle,
-          ),
-          className,
-          style,
-        )}>
-        <div {...stylex.props(styles.icon)}>
-          <Icon icon="clock" size="sm" color="secondary" />
-        </div>
-        <input
-          ref={mergeRefs(ref, inputRef)}
-          id={id}
-          type="text"
-          value={displayValue}
-          onChange={handleInputChange}
-          onFocus={handleFocus}
-          onBlur={handleBlur}
-          onKeyDown={handleInputKeyDown}
-          placeholder={displayPlaceholder}
-          disabled={isDisabled}
-          autoFocus={hasAutoFocus}
-          data-autofocus={hasAutoFocus || undefined}
-          aria-describedby={ariaDescribedBy}
-          aria-required={isRequired === true ? 'true' : undefined}
-          aria-invalid={status?.type === 'error' ? 'true' : undefined}
-          aria-busy={isBusy || undefined}
-          {...stylex.props(
-            styles.input,
-            isDisabled && styles.inputDisabled,
-            !isInputValid && styles.inputInvalid,
-          )}
-        />
-        {isBusy && <Spinner size="sm" />}
-        {hasClear && value && !isDisabled && (
-          <button
-            type="button"
-            onClick={handleClear}
-            aria-label={`Clear ${label}`}
-            {...stylex.props(styles.clearButton)}>
-            <Icon icon="close" size="sm" color="secondary" />
-          </button>
-        )}
-        {status && (
-          <Icon
-            icon={statusIconMap[status.type]}
-            size="md"
-            color={statusIconColorMap[status.type]}
-          />
-        )}
-      </div>
+      {inputWrapper}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }