@astryxdesign/core 0.1.2 → 0.1.3

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',
   },

package/src/DateRangeInput/DateRangeInput.test.tsx

@@ -9,8 +9,9 @@
  * SYNC: When DateRangeInput.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 {DateRangeInput} from './DateRangeInput';
 import type {DateRange} from './DateRangeInput';
 
@@ -23,9 +24,7 @@ describe('DateRangeInput', () => {
   });
 
   it('renders placeholder when value is null', () => {
-    render(
-      <DateRangeInput label="Range" value={null} onChange={() => {}} />,
-    );
+    render(<DateRangeInput label="Range" value={null} onChange={() => {}} />);
     expect(screen.getByText('Select date range')).toBeInTheDocument();
   });
 
@@ -99,9 +98,7 @@ describe('DateRangeInput', () => {
   });
 
   it('does not set aria-required when isRequired is false', () => {
-    render(
-      <DateRangeInput label="Range" value={null} onChange={() => {}} />,
-    );
+    render(<DateRangeInput label="Range" value={null} onChange={() => {}} />);
     const trigger = screen.getByRole('button', {name: /Range/});
     expect(trigger).not.toHaveAttribute('aria-required');
   });
@@ -120,25 +117,19 @@ describe('DateRangeInput', () => {
   });
 
   it('is not disabled by default', () => {
-    render(
-      <DateRangeInput label="Range" value={null} onChange={() => {}} />,
-    );
+    render(<DateRangeInput label="Range" value={null} onChange={() => {}} />);
     const trigger = screen.getByRole('button', {name: /Range/});
     expect(trigger).not.toBeDisabled();
   });
 
   it('trigger has aria-haspopup="dialog"', () => {
-    render(
-      <DateRangeInput label="Range" value={null} onChange={() => {}} />,
-    );
+    render(<DateRangeInput label="Range" value={null} onChange={() => {}} />);
     const trigger = screen.getByRole('button', {name: /Range/});
     expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
   });
 
   it('trigger has aria-expanded=false by default', () => {
-    render(
-      <DateRangeInput label="Range" value={null} onChange={() => {}} />,
-    );
+    render(<DateRangeInput label="Range" value={null} onChange={() => {}} />);
     const trigger = screen.getByRole('button', {name: /Range/});
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
@@ -201,9 +192,7 @@ describe('DateRangeInput', () => {
   });
 
   it('calendar icon button is present', () => {
-    render(
-      <DateRangeInput label="Range" value={null} onChange={() => {}} />,
-    );
+    render(<DateRangeInput label="Range" value={null} onChange={() => {}} />);
     expect(
       screen.getByRole('button', {name: 'Open calendar'}),
     ).toBeInTheDocument();
@@ -321,4 +310,177 @@ describe('DateRangeInput', () => {
       expect(onChange).toHaveBeenCalledWith(null);
     });
   });
+
+  describe('presets', () => {
+    const presets = [
+      {
+        label: 'Last 7 days',
+        getRange: (): DateRange => ({
+          start: '2026-03-01',
+          end: '2026-03-07',
+        }),
+      },
+      {
+        label: 'This month',
+        getRange: (): DateRange => ({
+          start: '2026-03-01',
+          end: '2026-03-31',
+        }),
+      },
+    ];
+
+    it('renders presets as a labeled group of buttons, not a listbox (forms-5)', () => {
+      render(
+        <DateRangeInput
+          label="Range"
+          value={null}
+          onChange={() => {}}
+          presets={presets}
+        />,
+      );
+      // The preset sidebar is a group of action buttons — not a listbox of
+      // options (which would announce a Tab-navigable listbox it isn't).
+      expect(
+        screen.queryByRole('listbox', {hidden: true}),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.getByRole('group', {name: 'Preset date ranges', hidden: true}),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('button', {name: 'Last 7 days', hidden: true}),
+      ).toBeInTheDocument();
+    });
+
+    it('marks the applied preset with aria-current, not aria-selected', () => {
+      render(
+        <DateRangeInput
+          label="Range"
+          value={{start: '2026-03-01', end: '2026-03-07'}}
+          onChange={() => {}}
+          presets={presets}
+        />,
+      );
+      const active = screen.getByRole('button', {
+        name: 'Last 7 days',
+        hidden: true,
+      });
+      expect(active).toHaveAttribute('aria-current', 'true');
+      expect(active).not.toHaveAttribute('aria-selected');
+      const inactive = screen.getByRole('button', {
+        name: 'This month',
+        hidden: true,
+      });
+      expect(inactive).not.toHaveAttribute('aria-current');
+    });
+  });
+  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;
+
+    function renderDisabled(props?: {disabledMessage?: string}) {
+      return render(
+        <DateRangeInput
+          label="Range"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+          {...props}
+        />,
+      );
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      renderDisabled({disabledMessage: 'You need the Editor role'});
+
+      const trigger = screen.getByRole('button', {name: /Range:/, ...h});
+      const container = trigger.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();
+      renderDisabled({disabledMessage: 'You need the Editor role'});
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('button', {name: /Range:/, ...h})).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <DateRangeInput
+          label="Range"
+          value={null}
+          onChange={() => {}}
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      renderDisabled();
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the trigger focusable via aria-disabled when a reason is provided', () => {
+      renderDisabled({disabledMessage: 'You need the Editor role'});
+      const trigger = screen.getByRole('button', {name: /Range:/, ...h});
+      expect(trigger).not.toBeDisabled();
+      expect(trigger).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('links the reason tooltip from the trigger via aria-describedby', () => {
+      renderDisabled({disabledMessage: 'You need the Editor role'});
+      const trigger = screen.getByRole('button', {name: /Range:/, ...h});
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(trigger.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks activation while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      renderDisabled({disabledMessage: 'You need the Editor role'});
+
+      const trigger = screen.getByRole('button', {name: /Range:/, ...h});
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+      await user.keyboard('{Enter}');
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      renderDisabled();
+      const trigger = screen.getByRole('button', {name: /Range:/, ...h});
+      expect(trigger).toBeDisabled();
+      expect(trigger).not.toHaveAttribute('aria-disabled');
+    });
+  });
 });