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

package/src/DateInput/DateInput.doc.mjs

@@ -7,7 +7,15 @@ export const docs = {
   displayName: 'Date Input',
   group: 'DateInput',
   category: 'Data Input',
-  keywords: ["dateinput","datepicker","datefield","calendar","dateselect","dateentry","datechooser"],
+  keywords: [
+    'dateinput',
+    'datepicker',
+    'datefield',
+    'calendar',
+    'dateselect',
+    'dateentry',
+    'datechooser',
+  ],
   props: [
     {
       name: 'label',
@@ -44,6 +52,12 @@ export const docs = {
       description: 'Disable the input and calendar.',
       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 DateInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'value',
       type: 'ISODateString',
@@ -57,12 +71,14 @@ export const docs = {
     {
       name: 'changeAction',
       type: '(value: ISODateString | undefined) => void | Promise<void>',
-      description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',
+      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.',
+      description:
+        'Whether the input is in a loading state. Disables interaction and shows a spinner.',
       default: 'false',
     },
     {
@@ -102,7 +118,8 @@ export const docs = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description: 'Tooltip text displayed via an info icon at the end of the label.',
+      description:
+        'Tooltip text displayed via an info icon at the end of the label.',
     },
     {
       name: 'hasClear',
@@ -131,23 +148,85 @@ export const docs = {
     ],
   },
   usage: {
-    description: 'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',
+    description:
+      'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',
     bestPractices: [
-      { guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },
-      { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
-      { guidance: true, description: 'Use hasClear when the date is optional so the user can reset it.' },
-      { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },
-      { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
-      { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels and descriptions so users understand what date is expected.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasClear when the date is optional so the user can reset it.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show a loading state with changeAction when the date triggers a server-side save.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a DateInput for free-form text that does not represent a calendar date.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the field purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateInput 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 input describing what date is expected.'},
-      {name: 'Text input', required: true, description: 'A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.'},
-      {name: 'Calendar icon', required: true, description: 'A button that opens the calendar popover for visual date picking.'},
-      {name: 'Calendar popover', required: false, description: 'A month grid that appears when the icon is clicked or the input is focused.'},
-      {name: 'Clear button', required: false, description: 'A × button that resets the date value. Shown when hasClear is true and a date is set.'},
-      {name: 'Status message', required: false, description: 'An error, warning, or success message below the input.'},
+      {
+        name: 'Label',
+        required: true,
+        description: 'Text above the input describing what date is expected.',
+      },
+      {
+        name: 'Text input',
+        required: true,
+        description:
+          'A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.',
+      },
+      {
+        name: 'Calendar icon',
+        required: true,
+        description:
+          'A button that opens the calendar popover for visual date picking.',
+      },
+      {
+        name: 'Calendar popover',
+        required: false,
+        description:
+          'A month grid that appears when the icon is clicked or the input is focused.',
+      },
+      {
+        name: 'Clear button',
+        required: false,
+        description:
+          'A × button that resets the date value. Shown when hasClear is true and a date is set.',
+      },
+      {
+        name: 'Status message',
+        required: false,
+        description: 'An error, warning, or success message below the input.',
+      },
     ],
   },
 };
@@ -157,40 +236,153 @@ export const docsZh = {
   name: 'DateInput',
   displayName: 'Date Input',
   usage: {
-    description: 'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',
+    description:
+      'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',
     bestPractices: [
-      { guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },
-      { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
-      { guidance: true, description: 'Use hasClear when the date is optional so the user can reset it.' },
-      { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },
-      { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
-      { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels and descriptions so users understand what date is expected.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasClear when the date is optional so the user can reset it.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show a loading state with changeAction when the date triggers a server-side save.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a DateInput for free-form text that does not represent a calendar date.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the field purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   props: [
     {name: 'label', type: 'string', description: '标签文本。', required: true},
-    {name: 'isLabelHidden', type: 'boolean', description: '视觉隐藏标签。', default: 'false'},
-    {name: 'description', type: 'string', description: '显示在标签下方的辅助文本。'},
-    {name: 'isOptional', type: 'boolean', description: '在标签旁显示"(optional)"指示器。', default: 'false'},
-    {name: 'isRequired', type: 'boolean', description: '将字段标记为必填。', default: 'false'},
-    {name: 'isDisabled', type: 'boolean', description: '禁用输入框和日历。', default: 'false'},
-    {name: 'value', type: 'ISODateString', description: '选中的日期，YYYY-MM-DD 格式。'},
-    {name: 'onChange', type: '(value: ISODateString | undefined) => void', description: '选中日期变更时调用的回调。'},
+    {
+      name: 'isLabelHidden',
+      type: 'boolean',
+      description: '视觉隐藏标签。',
+      default: 'false',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description: '显示在标签下方的辅助文本。',
+    },
+    {
+      name: 'isOptional',
+      type: 'boolean',
+      description: '在标签旁显示"(optional)"指示器。',
+      default: 'false',
+    },
+    {
+      name: 'isRequired',
+      type: 'boolean',
+      description: '将字段标记为必填。',
+      default: 'false',
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description: '禁用输入框和日历。',
+      default: 'false',
+    },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持输入框可聚焦（仍阻止输入和激活）。请使用此属性，而不是用 Tooltip 包裹已禁用的 DateInput。',
+    },
+    {
+      name: 'value',
+      type: 'ISODateString',
+      description: '选中的日期，YYYY-MM-DD 格式。',
+    },
+    {
+      name: 'onChange',
+      type: '(value: ISODateString | undefined) => void',
+      description: '选中日期变更时调用的回调。',
+    },
     {
       name: 'changeAction',
       type: '(value: ISODateString | undefined) => void | Promise<void>',
-      description: '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',
-    },
-    {name: 'isLoading', type: 'boolean', description: '输入框是否处于加载状态。禁用交互并显示加载指示器。', default: 'false'},
-    {name: 'min', type: 'ISODateString', description: '可选择的最早日期（YYYY-MM-DD）。'},
-    {name: 'max', type: 'ISODateString', description: '可选择的最晚日期（YYYY-MM-DD）。'},
-    {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数数组，用于禁用特定日期。'},
-    {name: 'placeholder', type: 'string', description: '文本输入框中显示的占位符文本。', default: "'Select a date'"},
-    {name: 'size', type: "'sm' | 'md' | 'lg'", description: '输入控件的尺寸。', default: "'md'"},
-    {name: 'status', type: 'InputStatus', description: '错误、警告或成功状态的状态指示对象，附带消息。'},
-    {name: 'labelTooltip', type: 'string', description: '通过标签末尾的信息图标显示的提示文本。'},
-    {name: 'numberOfMonths', type: '1 | 2', description: '日历弹出层中同时显示的月份数量。', default: '1'},
+      description:
+        '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description: '输入框是否处于加载状态。禁用交互并显示加载指示器。',
+      default: 'false',
+    },
+    {
+      name: 'min',
+      type: 'ISODateString',
+      description: '可选择的最早日期（YYYY-MM-DD）。',
+    },
+    {
+      name: 'max',
+      type: 'ISODateString',
+      description: '可选择的最晚日期（YYYY-MM-DD）。',
+    },
+    {
+      name: 'dateConstraints',
+      type: 'Array<(date: Date) => boolean>',
+      description: '自定义约束函数数组，用于禁用特定日期。',
+    },
+    {
+      name: 'placeholder',
+      type: 'string',
+      description: '文本输入框中显示的占位符文本。',
+      default: "'Select a date'",
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: '输入控件的尺寸。',
+      default: "'md'",
+    },
+    {
+      name: 'status',
+      type: 'InputStatus',
+      description: '错误、警告或成功状态的状态指示对象，附带消息。',
+    },
+    {
+      name: 'labelTooltip',
+      type: 'string',
+      description: '通过标签末尾的信息图标显示的提示文本。',
+    },
+    {
+      name: 'numberOfMonths',
+      type: '1 | 2',
+      description: '日历弹出层中同时显示的月份数量。',
+      default: '1',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -202,10 +394,7 @@ export const docsZh = {
     targets: [
       {
         className: 'astryx-date-input',
-        visualProps: [
-          'size',
-          'status',
-        ],
+        visualProps: ['size', 'status'],
       },
     ],
   },
@@ -215,15 +404,49 @@ export const docsZh = {
 export const docsDense = {
   description: 'text input w/ calendar popover for picking a date',
   usage: {
-    description: 'DateInput lets the user type or pick a date from a calendar popover. Use for scheduling, deadlines, booking dates, or any form field needing a calendar date.',
+    description:
+      'DateInput lets the user type or pick a date from a calendar popover. Use for scheduling, deadlines, booking dates, or any form field needing a calendar date.',
     bestPractices: [
-      { guidance: true, description: 'Provide clear labels + descriptions so users understand what date is expected.' },
-      { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
-      { guidance: true, description: 'Use hasClear when the date is optional so the user can reset it.' },
-      { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },
-      { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
-      { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels + descriptions so users understand what date is expected.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasClear when the date is optional so the user can reset it.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show a loading state with changeAction when the date triggers a server-side save.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a DateInput for free-form text that does not represent a calendar date.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the field purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   propDescriptions: {
@@ -233,6 +456,8 @@ export const docsDense = {
     isOptional: 'show "(optional)" indicator',
     isRequired: 'mark field required',
     isDisabled: 'disable input+calendar',
+    disabledMessage:
+      'reason shown in a tooltip on hover/focus when disabled; keeps field focusable via aria-disabled',
     value: 'selected date YYYY-MM-DD',
     onChange: 'callback on date change',
     changeAction: 'async action after onChange; drives optimistic UI',

package/src/DateInput/DateInput.test.tsx

@@ -9,8 +9,9 @@
  * 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';
 
 describe('DateInput', () => {
@@ -110,6 +111,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 +318,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 +645,130 @@ describe('DateInput', () => {
       expect(input).toHaveValue('March 20, 2026');
     });
   });
+  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');
+    });
+  });
 });