@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/DateInput/DateInput.tsx

@@ -44,14 +44,12 @@ import {
   inputStatusFocusWithinStyles,
 } from '../Field';
 import {Icon} from '../Icon';
+import {VisuallyHidden} from '../VisuallyHidden';
 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 {useTooltip} from '../Tooltip';
 import {parseDateInput} from '../utils';
 import {
   plainDateFromISO,
@@ -177,6 +175,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 +300,7 @@ export function DateInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   value,
   onChange,
   changeAction,
@@ -311,6 +333,22 @@ export function DateInput({
   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',
@@ -334,6 +372,7 @@ export function DateInput({
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -428,6 +467,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 +489,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,12 +527,22 @@ 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],
   );
 
   return (
@@ -513,7 +567,13 @@ export function DateInput({
       labelTooltip={labelTooltip}
       width={width}>
       <div
-        ref={popover.triggerRef}
+        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}),
@@ -551,10 +611,18 @@ export function DateInput({
           onClick={handleInputClick}
           onKeyDown={handleInputKeyDown}
           placeholder={placeholder}
-          disabled={isEffectivelyDisabled}
+          // 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-describedby={ariaDescribedBy}
           aria-required={isRequired === true ? 'true' : undefined}
-          aria-invalid={status?.type === 'error' ? 'true' : undefined}
+          aria-invalid={
+            status?.type === 'error' || !isInputValid ? 'true' : undefined
+          }
           aria-busy={isBusy || undefined}
           aria-expanded={popover.isOpen}
           aria-haspopup="dialog"
@@ -567,6 +635,14 @@ export function DateInput({
             !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"
@@ -598,6 +674,9 @@ export function DateInput({
         />,
         {placement: 'below', alignment: 'start'},
       )}
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -7,69 +7,271 @@ export const docs = {
   displayName: 'Date Range Input',
   group: 'DateInput',
   category: 'Data Input',
-  keywords: ["daterangepicker","daterange","range","calendar","filter","analytics","period","schedule"],
+  keywords: [
+    'daterangepicker',
+    'daterange',
+    'range',
+    'calendar',
+    'filter',
+    'analytics',
+    'period',
+    'schedule',
+  ],
   props: [
-    { name: 'label', type: 'string', description: 'Label text.', required: true },
-    { name: 'isLabelHidden', type: 'boolean', description: 'Visually hide the label.', default: 'false' },
-    { name: 'description', type: 'string', description: 'Helper text displayed below the label.' },
-    { name: 'isOptional', type: 'boolean', description: 'Show an "(optional)" indicator.', default: 'false' },
-    { name: 'isRequired', type: 'boolean', description: 'Mark the field as required.', default: 'false' },
-    { name: 'isDisabled', type: 'boolean', description: 'Disable the trigger and picker.', default: 'false' },
-    { name: 'value', type: 'DateRange | null', description: 'Selected date range ({start, end} in ISO format), or null.', required: true },
-    { name: 'onChange', type: '(value: DateRange | null) => void', description: 'Callback when the range changes. Called with null on clear.', required: true },
-    { name: 'changeAction', type: '(value: DateRange | null) => void | Promise<void>', description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.' },
-    { name: 'isLoading', type: 'boolean', description: 'Whether the input is in a loading state. Disables interaction and shows a spinner.', default: 'false' },
-    { name: 'min', type: 'ISODateString', description: 'Minimum selectable date.' },
-    { name: 'max', type: 'ISODateString', description: 'Maximum selectable date.' },
-    { name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: 'Custom constraint functions to disable specific dates.' },
-    { name: 'presets', type: 'Array<DateRangePreset>', description: 'Preset ranges shown as quick-select options beside the calendar.' },
-    { name: 'hasClear', type: 'boolean', description: 'Shows a clear button when a range is selected.', default: 'true' },
-    { name: 'placeholder', type: 'string', description: 'Placeholder text when no range is selected.', default: "'Select date range'" },
-    { name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Size of the trigger.', default: "'md'" },
-    { name: 'status', type: 'InputStatus', description: 'Status indicator for error, warning, or success states.' },
-    { name: 'labelTooltip', type: 'string', description: 'Tooltip text via info icon at label end.' },
-    { name: 'numberOfMonths', type: '1 | 2', description: 'Number of months in the calendar.', default: '2' },
-    { name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization.' },
+    {name: 'label', type: 'string', description: 'Label text.', required: true},
+    {
+      name: 'isLabelHidden',
+      type: 'boolean',
+      description: 'Visually hide the label.',
+      default: 'false',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description: 'Helper text displayed below the label.',
+    },
+    {
+      name: 'isOptional',
+      type: 'boolean',
+      description: 'Show an "(optional)" indicator.',
+      default: 'false',
+    },
+    {
+      name: 'isRequired',
+      type: 'boolean',
+      description: 'Mark the field as required.',
+      default: 'false',
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description: 'Disable the trigger and picker.',
+      default: 'false',
+    },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateRangeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
+    {
+      name: 'value',
+      type: 'DateRange | null',
+      description: 'Selected date range ({start, end} in ISO format), or null.',
+      required: true,
+    },
+    {
+      name: 'onChange',
+      type: '(value: DateRange | null) => void',
+      description:
+        'Callback when the range changes. Called with null on clear.',
+      required: true,
+    },
+    {
+      name: 'changeAction',
+      type: '(value: DateRange | null) => void | Promise<void>',
+      description:
+        'Async action fired after onChange. Drives optimistic UI updates via useTransition.',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description:
+        'Whether the input is in a loading state. Disables interaction and shows a spinner.',
+      default: 'false',
+    },
+    {
+      name: 'min',
+      type: 'ISODateString',
+      description: 'Minimum selectable date.',
+    },
+    {
+      name: 'max',
+      type: 'ISODateString',
+      description: 'Maximum selectable date.',
+    },
+    {
+      name: 'dateConstraints',
+      type: 'Array<(date: Date) => boolean>',
+      description: 'Custom constraint functions to disable specific dates.',
+    },
+    {
+      name: 'presets',
+      type: 'Array<DateRangePreset>',
+      description:
+        'Preset ranges shown as quick-select options beside the calendar.',
+    },
+    {
+      name: 'hasClear',
+      type: 'boolean',
+      description: 'Shows a clear button when a range is selected.',
+      default: 'true',
+    },
+    {
+      name: 'placeholder',
+      type: 'string',
+      description: 'Placeholder text when no range is selected.',
+      default: "'Select date range'",
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: 'Size of the trigger.',
+      default: "'md'",
+    },
+    {
+      name: 'status',
+      type: 'InputStatus',
+      description: 'Status indicator for error, warning, or success states.',
+    },
+    {
+      name: 'labelTooltip',
+      type: 'string',
+      description: 'Tooltip text via info icon at label end.',
+    },
+    {
+      name: 'numberOfMonths',
+      type: '1 | 2',
+      description: 'Number of months in the calendar.',
+      default: '2',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: 'StyleX styles for layout customization.',
+    },
   ],
   theming: {
     targets: [
-      { className: 'astryx-date-range-input', visualProps: ['size', 'status'] },
+      {className: 'astryx-date-range-input', visualProps: ['size', 'status']},
     ],
   },
   usage: {
-    description: 'DateRangeInput lets users select a start and end date from a dual-month calendar popover. Use it for filtering data by time period, report generation, analytics dashboards, and booking flows.',
+    description:
+      'DateRangeInput lets users select a start and end date from a dual-month calendar popover. Use it for filtering data by time period, report generation, analytics dashboards, and booking flows.',
     bestPractices: [
-      { guidance: true, description: 'Use presets for common ranges like "Last 7 days" to speed up selection.' },
-      { guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },
-      { guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },
-      { guidance: true, description: 'Provide clear labels and descriptions so users understand what the range controls.' },
-      { guidance: false, description: 'Use DateRangeInput when only a single date is needed; use DateInput instead.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },
+      {
+        guidance: true,
+        description:
+          'Use presets for common ranges like "Last 7 days" to speed up selection.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min/max to constrain selectable dates to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep hasClear enabled (default) so users can reset the filter.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels and descriptions so users understand what the range controls.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateRangeInput when only a single date is needed; use DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateRangeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
     anatomy: [
-      { name: 'Label', required: true, description: 'Text above the trigger describing what date range is expected.' },
-      { name: 'Trigger button', required: true, description: 'A button showing the formatted range or placeholder. Clicking opens the popover.' },
-      { name: 'Calendar icon', required: true, description: 'A trailing icon that also opens the popover.' },
-      { name: 'Calendar popover', required: true, description: 'A dual-month calendar grid with range selection and hover preview.' },
-      { name: 'Preset sidebar', required: false, description: 'A list of preset range options beside the calendar.' },
-      { name: 'Clear button', required: false, description: 'A × button that resets the range to null.' },
-      { name: 'Status message', required: false, description: 'An error, warning, or success message below the trigger.' },
+      {
+        name: 'Label',
+        required: true,
+        description:
+          'Text above the trigger describing what date range is expected.',
+      },
+      {
+        name: 'Trigger button',
+        required: true,
+        description:
+          'A button showing the formatted range or placeholder. Clicking opens the popover.',
+      },
+      {
+        name: 'Calendar icon',
+        required: true,
+        description: 'A trailing icon that also opens the popover.',
+      },
+      {
+        name: 'Calendar popover',
+        required: true,
+        description:
+          'A dual-month calendar grid with range selection and hover preview.',
+      },
+      {
+        name: 'Preset sidebar',
+        required: false,
+        description: 'A list of preset range options beside the calendar.',
+      },
+      {
+        name: 'Clear button',
+        required: false,
+        description: 'A × button that resets the range to null.',
+      },
+      {
+        name: 'Status message',
+        required: false,
+        description: 'An error, warning, or success message below the trigger.',
+      },
     ],
   },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'date range picker with dual-month calendar popover and preset ranges',
+  description:
+    'date range picker with dual-month calendar popover and preset ranges',
   usage: {
-    description: 'DateRangeInput lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',
+    description:
+      'DateRangeInput lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',
     bestPractices: [
-      { guidance: true, description: 'Use presets for common ranges like "Last 7 days" to speed up selection.' },
-      { guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },
-      { guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },
-      { guidance: true, description: 'Provide clear labels + descriptions so users understand what the range controls.' },
-      { guidance: false, description: 'Use DateRangeInput when only a single date is needed; use DateInput instead.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },
+      {
+        guidance: true,
+        description:
+          'Use presets for common ranges like "Last 7 days" to speed up selection.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min/max to constrain selectable dates to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep hasClear enabled (default) so users can reset the filter.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels + descriptions so users understand what the range controls.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateRangeInput when only a single date is needed; use DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateRangeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   propDescriptions: {
@@ -79,6 +281,8 @@ export const docsDense = {
     isOptional: 'show "(optional)" indicator',
     isRequired: 'mark field required',
     isDisabled: 'disable trigger+picker',
+    disabledMessage:
+      'reason shown in a tooltip on hover/focus when disabled; keeps trigger focusable via aria-disabled',
     value: 'selected range {start, end} or null',
     onChange: 'callback on range change; null on clear',
     min: 'min selectable date',
@@ -91,7 +295,8 @@ export const docsDense = {
     status: 'error/warning/success status',
     labelTooltip: 'tooltip via info icon at label end',
     numberOfMonths: 'months in calendar (default 2)',
-    changeAction: 'async action fired after onChange; drives optimistic UI updates via useTransition',
+    changeAction:
+      'async action fired after onChange; drives optimistic UI updates via useTransition',
     isLoading: 'loading state; disables interaction + shows a spinner',
     xstyle: 'StyleX styles for layout',
   },