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

package/src/TimeInput/TimeInput.doc.mjs

@@ -6,26 +6,95 @@ export const docs = {
   name: 'TimeInput',
   displayName: 'Time Input',
   category: 'Data Input',
-  keywords: ["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield","schedule"],
+  keywords: [
+    'timeinput',
+    'timepicker',
+    'time',
+    'clock',
+    'hour',
+    'minute',
+    'ampm',
+    'timeselect',
+    'timefield',
+    'schedule',
+  ],
 
   usage: {
     description:
       'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',
     bestPractices: [
-      {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.'},
-      {guidance: true, description: 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.'},
-      {guidance: true, description: 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.'},
-      {guidance: true, description: 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.'},
-      {guidance: true, description: 'Enable hasClear when the field is optional, so users can remove a previously selected time.'},
-      {guidance: false, description: 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.'},
-      {guidance: false, description: 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.'},
+      {
+        guidance: true,
+        description:
+          'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.',
+      },
+      {
+        guidance: true,
+        description:
+          'Enable hasClear when the field is optional, so users can remove a previously selected time.',
+      },
+      {
+        guidance: false,
+        description:
+          'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
     anatomy: [
-      {name: 'Clock icon', required: false, description: 'A leading clock icon that identifies the field as a time input.'},
-      {name: 'Text input', required: true, description: 'The editable text field where users type or see the formatted time.'},
-      {name: 'Clear button', required: false, description: 'A trailing button to reset the value, shown when hasClear is true and a value is set.'},
-      {name: 'Status icon', required: false, description: 'A trailing icon indicating error, warning, or success state.'},
-      {name: 'Spinner', required: false, description: 'Replaces trailing content during loading to show an async action is in progress.'},
+      {
+        name: 'Clock icon',
+        required: false,
+        description:
+          'A leading clock icon that identifies the field as a time input.',
+      },
+      {
+        name: 'Text input',
+        required: true,
+        description:
+          'The editable text field where users type or see the formatted time.',
+      },
+      {
+        name: 'Clear button',
+        required: false,
+        description:
+          'A trailing button to reset the value, shown when hasClear is true and a value is set.',
+      },
+      {
+        name: 'Status icon',
+        required: false,
+        description:
+          'A trailing icon indicating error, warning, or success state.',
+      },
+      {
+        name: 'Spinner',
+        required: false,
+        description:
+          'Replaces trailing content during loading to show an async action is in progress.',
+      },
     ],
   },
 
@@ -33,8 +102,7 @@ export const docs = {
     {
       name: 'label',
       type: 'string',
-      description:
-        'Label text for the input (required for accessibility).',
+      description: 'Label text for the input (required for accessibility).',
       required: true,
     },
     {
@@ -69,6 +137,12 @@ export const docs = {
       description: 'Disables the input and suppresses interactions.',
       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 TimeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'value',
       type: 'ISOTimeString',
@@ -176,27 +250,134 @@ export const docsZh = {
 
   displayName: 'Time Input',
   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: '在标签旁显示"（可选）"指示器。与 isRequired 互斥。', default: 'false'},
-    {name: 'isRequired', type: 'boolean', description: '将字段标记为必填并设置 aria-required。与 isOptional 互斥。', default: 'false'},
-    {name: 'isDisabled', type: 'boolean', description: '禁用输入框并抑制交互。', default: 'false'},
-    {name: 'value', type: 'ISOTimeString', description: 'ISO 格式的受控时间值（HH:MM 或 HH:MM:SS）。'},
-    {name: 'onChange', type: '(value: ISOTimeString | undefined) => void', description: '时间变化时触发的回调。输入被清除时接收 undefined。'},
-    {name: 'changeAction', type: '(value: ISOTimeString | undefined) => void | Promise<void>', description: '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI；挂起时触发加载旋转器。'},
-    {name: 'isLoading', type: 'boolean', description: '使输入框进入加载状态，显示旋转器。', default: 'false'},
-    {name: 'min', type: 'ISOTimeString', description: 'ISO 格式的最小可选时间。超出范围的值将被拒绝。'},
-    {name: 'max', type: 'ISOTimeString', description: 'ISO 格式的最大可选时间。超出范围的值将被拒绝。'},
-    {name: 'hasSeconds', type: 'boolean', description: '在时间显示和解析中包含秒。', default: 'false'},
-    {name: 'hasClear', type: 'boolean', description: '当有值且输入框未被禁用时显示清除按钮。', default: 'false'},
-    {name: 'hourFormat', type: "'12h' | '24h'", description: "控制显示格式。'12h' 显示 AM/PM（例如 '2:30 PM'）；'24h' 使用 24 小时制（例如 '14:30'）。", default: "'12h'"},
-    {name: 'increment', type: 'number', description: '用户按上或下方向键时增加或减少的分钟数。', default: '1'},
-    {name: 'placeholder', type: 'string', description: '未选择时间时显示的占位符文本。当输入框聚焦且为空时，格式提示会覆盖此文本。', default: "'Select a time'"},
-    {name: 'size', type: "'sm' | 'md' | 'lg'", description: '控制输入框元素的高度。', default: "'md'"},
-    {name: 'status', type: 'InputStatus', description: '为边框着色并显示图标的状态指示器。当提供消息时，消息渲染在输入框下方。'},
-    {name: 'labelTooltip', type: 'string', description: '在标签行末尾以信息图标形式渲染的工具提示文本。'},
-    {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX 样式，用于布局自定义（边距、定位、尺寸）。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。'},
+    {
+      name: 'label',
+      type: 'string',
+      description: '输入框的标签文本（无障碍性所必需）。',
+      required: true,
+    },
+    {
+      name: 'isLabelHidden',
+      type: 'boolean',
+      description: '视觉上隐藏标签，同时保持屏幕阅读器的无障碍性。',
+      default: 'false',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description: '显示在标签和输入框之间的描述文本。',
+    },
+    {
+      name: 'isOptional',
+      type: 'boolean',
+      description: '在标签旁显示"（可选）"指示器。与 isRequired 互斥。',
+      default: 'false',
+    },
+    {
+      name: 'isRequired',
+      type: 'boolean',
+      description: '将字段标记为必填并设置 aria-required。与 isOptional 互斥。',
+      default: 'false',
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description: '禁用输入框并抑制交互。',
+      default: 'false',
+    },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持输入框可聚焦（仍阻止输入和调整）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TimeInput。',
+    },
+    {
+      name: 'value',
+      type: 'ISOTimeString',
+      description: 'ISO 格式的受控时间值（HH:MM 或 HH:MM:SS）。',
+    },
+    {
+      name: 'onChange',
+      type: '(value: ISOTimeString | undefined) => void',
+      description: '时间变化时触发的回调。输入被清除时接收 undefined。',
+    },
+    {
+      name: 'changeAction',
+      type: '(value: ISOTimeString | undefined) => void | Promise<void>',
+      description:
+        '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI；挂起时触发加载旋转器。',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description: '使输入框进入加载状态，显示旋转器。',
+      default: 'false',
+    },
+    {
+      name: 'min',
+      type: 'ISOTimeString',
+      description: 'ISO 格式的最小可选时间。超出范围的值将被拒绝。',
+    },
+    {
+      name: 'max',
+      type: 'ISOTimeString',
+      description: 'ISO 格式的最大可选时间。超出范围的值将被拒绝。',
+    },
+    {
+      name: 'hasSeconds',
+      type: 'boolean',
+      description: '在时间显示和解析中包含秒。',
+      default: 'false',
+    },
+    {
+      name: 'hasClear',
+      type: 'boolean',
+      description: '当有值且输入框未被禁用时显示清除按钮。',
+      default: 'false',
+    },
+    {
+      name: 'hourFormat',
+      type: "'12h' | '24h'",
+      description:
+        "控制显示格式。'12h' 显示 AM/PM（例如 '2:30 PM'）；'24h' 使用 24 小时制（例如 '14:30'）。",
+      default: "'12h'",
+    },
+    {
+      name: 'increment',
+      type: 'number',
+      description: '用户按上或下方向键时增加或减少的分钟数。',
+      default: '1',
+    },
+    {
+      name: 'placeholder',
+      type: 'string',
+      description:
+        '未选择时间时显示的占位符文本。当输入框聚焦且为空时，格式提示会覆盖此文本。',
+      default: "'Select a time'",
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: '控制输入框元素的高度。',
+      default: "'md'",
+    },
+    {
+      name: 'status',
+      type: 'InputStatus',
+      description:
+        '为边框着色并显示图标的状态指示器。当提供消息时，消息渲染在输入框下方。',
+    },
+    {
+      name: 'labelTooltip',
+      type: 'string',
+      description: '在标签行末尾以信息图标形式渲染的工具提示文本。',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX 样式，用于布局自定义（边距、定位、尺寸）。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。',
+    },
   ],
   theming: {
     targets: [
@@ -207,61 +388,155 @@ export const docsZh = {
     description:
       'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',
     bestPractices: [
-      {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.'},
-      {guidance: true, description: 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.'},
-      {guidance: true, description: 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.'},
-      {guidance: true, description: 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.'},
-      {guidance: true, description: 'Enable hasClear when the field is optional, so users can remove a previously selected time.'},
-      {guidance: false, description: 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.'},
-      {guidance: false, description: 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.'},
+      {
+        guidance: true,
+        description:
+          'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.',
+      },
+      {
+        guidance: true,
+        description:
+          'Enable hasClear when the field is optional, so users can remove a previously selected time.',
+      },
+      {
+        guidance: false,
+        description:
+          'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
     anatomy: [
-      {name: 'Clock icon', required: false, description: 'A leading clock icon that identifies the field as a time input.'},
-      {name: 'Text input', required: true, description: 'The editable text field where users type or see the formatted time.'},
-      {name: 'Clear button', required: false, description: 'A trailing button to reset the value, shown when hasClear is true and a value is set.'},
-      {name: 'Status icon', required: false, description: 'A trailing icon indicating error, warning, or success state.'},
-      {name: 'Spinner', required: false, description: 'Replaces trailing content during loading to show an async action is in progress.'},
+      {
+        name: 'Clock icon',
+        required: false,
+        description:
+          'A leading clock icon that identifies the field as a time input.',
+      },
+      {
+        name: 'Text input',
+        required: true,
+        description:
+          'The editable text field where users type or see the formatted time.',
+      },
+      {
+        name: 'Clear button',
+        required: false,
+        description:
+          'A trailing button to reset the value, shown when hasClear is true and a value is set.',
+      },
+      {
+        name: 'Status icon',
+        required: false,
+        description:
+          'A trailing icon indicating error, warning, or success state.',
+      },
+      {
+        name: 'Spinner',
+        required: false,
+        description:
+          'Replaces trailing content during loading to show an async action is in progress.',
+      },
     ],
   },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'Time input that converts free-text entry to standard format with arrow-key adjustment.',
+  description:
+    'Time input that converts free-text entry to standard format with arrow-key adjustment.',
   usage: {
     description:
       'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',
     bestPractices: [
-      {guidance: true, description: 'Choose hour format (12h/24h) to match locale \u2014 12h for US, 24h for international.'},
-      {guidance: true, description: 'Set min/max constraints for valid ranges like business hours.'},
-      {guidance: true, description: 'Provide description or placeholder hinting at expected format.'},
-      {guidance: true, description: 'Use status prop for inline validation errors.'},
+      {
+        guidance: true,
+        description:
+          'Choose hour format (12h/24h) to match locale \u2014 12h for US, 24h for international.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set min/max constraints for valid ranges like business hours.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide description or placeholder hinting at expected format.',
+      },
+      {
+        guidance: true,
+        description: 'Use status prop for inline validation errors.',
+      },
       {guidance: true, description: 'Enable hasClear for optional fields.'},
-      {guidance: false, description: 'Don\u2019t use for date-and-time \u2014 pair with DateInput instead.'},
-      {guidance: false, description: 'Don\u2019t hide the label \u2014 keep it visible for clarity.'},
+      {
+        guidance: false,
+        description:
+          'Don\u2019t use for date-and-time \u2014 pair with DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Don\u2019t hide the label \u2014 keep it visible for clarity.',
+      },
+      {
+        guidance: false,
+        description:
+          'Don\u2019t wrap a disabled TimeInput in Tooltip; use the disabledMessage prop instead.',
+      },
     ],
   },
   propDescriptions: {
     label: 'Label text (required for a11y).',
     isLabelHidden: 'Visually hides label; keeps screen reader access.',
     description: 'Description text between label+input.',
-    isOptional: 'Shows "(optional)" indicator. Mutually exclusive w/ isRequired.',
-    isRequired: 'Marks required+sets aria-required. Mutually exclusive w/ isOptional.',
+    isOptional:
+      'Shows "(optional)" indicator. Mutually exclusive w/ isRequired.',
+    isRequired:
+      'Marks required+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables input, suppresses interactions.',
+    disabledMessage:
+      'Reason shown in a tooltip on hover/focus when disabled; keeps input focusable via aria-disabled.',
     value: 'Controlled time in ISO format (HH:MM or HH:MM:SS).',
     onChange: 'Fired on time change. Receives undefined when cleared.',
-    changeAction: 'Async action after onChange in React transition; triggers spinner while pending.',
+    changeAction:
+      'Async action after onChange in React transition; triggers spinner while pending.',
     isLoading: 'Loading state w/ spinner.',
     min: 'Min selectable time in ISO format. Out-of-range rejected.',
     max: 'Max selectable time in ISO format. Out-of-range rejected.',
     hasSeconds: 'Includes seconds in display+parsing.',
     hasClear: 'Shows clear button when value set+not disabled.',
-    hourFormat: "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
+    hourFormat:
+      "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
     increment: 'Minutes to add/subtract on arrow up/down.',
     placeholder: 'Placeholder when empty. Focused+empty shows format hint.',
     size: 'Input element height.',
     status: 'Colored border+icon. Message rendered below input.',
     labelTooltip: 'Tooltip as info icon at label row end.',
-    xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
+    xstyle:
+      'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
   },
 };

package/src/TimeInput/TimeInput.test.tsx

@@ -9,8 +9,8 @@
  * 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 type {ISOTimeString} from '../utils';
@@ -23,11 +23,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 +206,145 @@ describe('TimeInput', () => {
     fireEvent.click(wrapper);
     expect(input).toHaveFocus();
   });
+  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');
+    });
+  });
 });