@astryxdesign/core 0.7.2 → 0.7.3-canary.02f5fe4

package/src/DateInput/DateInput.doc.mjs

@@ -49,14 +49,15 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disable the input and calendar.',
+      description:
+        'Disable the input and calendar. The field stays focusable and exposes `aria-disabled`; typing and opening are blocked.',
       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.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus (activation stays blocked). Use this instead of wrapping a disabled DateInput in Tooltip.',
     },
     {
       name: 'value',
@@ -275,7 +276,7 @@ export const docs = {
       {
         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.',
+          'Wrap a disabled DateInput in Tooltip to explain why it is disabled. Use the disabledMessage prop instead, which ties the reason to the field.',
       },
     ],
     anatomy: [
@@ -368,7 +369,7 @@ export const docsZh = {
       {
         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.',
+          'Wrap a disabled DateInput in Tooltip to explain why it is disabled. Use the disabledMessage prop instead, which ties the reason to the field.',
       },
     ],
   },
@@ -400,14 +401,14 @@ export const docsZh = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: '禁用输入框和日历。',
+      description: '禁用输入框和日历。输入框仍可聚焦并暴露 `aria-disabled`，但不能输入或打开日历。',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        '说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持输入框可聚焦（仍阻止输入和激活）。请使用此属性，而不是用 Tooltip 包裹已禁用的 DateInput。',
+        '说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示（仍阻止输入和激活）。请使用此属性，而不是用 Tooltip 包裹已禁用的 DateInput。',
     },
     {
       name: 'value',
@@ -621,7 +622,7 @@ export const docsDense = {
       {
         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.',
+          'Wrap a disabled DateInput in Tooltip to explain why it is disabled. Use the disabledMessage prop instead, which ties the reason to the field.',
       },
     ],
   },
@@ -633,7 +634,7 @@ export const docsDense = {
     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',
+      "reason shown in a tooltip on hover/focus when disabled; describes the field's focusable controls",
     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

@@ -84,9 +84,14 @@ describe('DateInput', () => {
     expect(screen.getByRole('combobox')).not.toHaveAttribute('aria-required');
   });
 
-  it('sets disabled attribute when isDisabled is true', () => {
+  it('keeps a disabled input focusable without native disabled (AST-085 FR1)', () => {
     render(<DateInput label="Date" isDisabled onChange={() => {}} />);
-    expect(screen.getByRole('combobox')).toBeDisabled();
+    const input = screen.getByRole('combobox');
+    expect(input).not.toHaveAttribute('disabled');
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).toHaveAttribute('readonly');
+    input.focus();
+    expect(input).toHaveFocus();
   });
 
   it('is not disabled by default', () => {
@@ -115,10 +120,16 @@ describe('DateInput', () => {
     expect(button).not.toBeDisabled();
   });
 
-  it('calendar button is disabled when isDisabled is true', () => {
+  it('calendar button is focusable-disabled when isDisabled is true', () => {
     render(<DateInput label="Date" isDisabled onChange={() => {}} />);
     const button = getButton('Open calendar');
-    expect(button).toBeDisabled();
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    fireEvent.click(button);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
   });
 
   it('does not call onChange while typing invalid input', async () => {
@@ -349,10 +360,15 @@ describe('DateInput', () => {
 
   // --- P1: Input disabled during isBusy (isLoading) ---
 
-  it('disables input and button when isLoading is true', () => {
+  it('blocks input and button without native disabled when isLoading is true', () => {
     render(<DateInput label="Date" isLoading onChange={() => {}} />);
-    expect(screen.getByRole('combobox')).toBeDisabled();
-    expect(getButton('Open calendar')).toBeDisabled();
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('disabled');
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+    expect(getButton('Open calendar')).not.toHaveAttribute('disabled');
+    expect(getButton('Open calendar')).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('shows spinner when isLoading is true', () => {
@@ -526,7 +542,8 @@ describe('DateInput', () => {
     render(<DateInput label="Date" isDisabled onChange={() => {}} />);
 
     const input = screen.getByRole('combobox');
-    expect(input).toBeDisabled();
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).not.toHaveAttribute('disabled');
   });
 
   // --- P1: aria-busy on input ---
@@ -818,7 +835,10 @@ describe('DateInput', () => {
       expect(input).toHaveAttribute('aria-disabled', 'true');
       expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
       expect(tooltip).toHaveTextContent('Scheduling is locked');
-      expect(getButton('Open calendar')).toBeDisabled();
+      expect(getButton('Open calendar')).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
     });
   });
 
@@ -875,6 +895,10 @@ describe('DateInput', () => {
       );
 
       const tooltip = screen.getByRole('tooltip', h);
+      // The calendar button keeps its enabled tab stop (spec:AST-085 FR1),
+      // so the input is the second stop.
+      await user.tab();
+      expect(getButton('Open calendar')).toHaveFocus();
       await user.tab();
       expect(screen.getByRole('combobox')).toHaveFocus();
       await waitFor(() => {
@@ -908,6 +932,50 @@ describe('DateInput', () => {
       expect(input).toHaveAttribute('readonly');
     });
 
+    it('does not call a caller onClick while disabled (AST-085 FR2)', () => {
+      const onClick = vi.fn();
+      render(<DateInput label="Date" isDisabled onClick={onClick} />);
+      fireEvent.click(screen.getByRole('combobox'));
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('links the reason tooltip from the calendar button too (AST-085 FR5)', () => {
+      render(
+        <DateInput
+          label="Date"
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(
+        getButton('Open calendar').getAttribute('aria-describedby'),
+      ).toContain(tooltip.id);
+    });
+
+    it('drops a draft instead of committing it when the field becomes disabled (AST-085 FR2)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const {rerender} = render(
+        <DateInput label="Date" value="2026-03-10" onChange={onChange} />,
+      );
+      const input = screen.getByRole('combobox');
+      await user.click(input);
+      await user.clear(input);
+      rerender(
+        <DateInput
+          label="Date"
+          value="2026-03-10"
+          onChange={onChange}
+          isDisabled
+        />,
+      );
+      expect(input).toHaveFocus();
+      await user.keyboard('{Enter}');
+      await user.tab();
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
     it('links the reason tooltip from the input via aria-describedby', () => {
       render(
         <DateInput
@@ -941,11 +1009,18 @@ describe('DateInput', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
-      render(<DateInput label="Date" isDisabled />);
+    it('blocks value changes and opening when disabled without a reason (AST-085 FR1, FR2)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(<DateInput label="Date" onChange={onChange} isDisabled />);
       const input = screen.getByRole('combobox');
-      expect(input).toBeDisabled();
-      expect(input).not.toHaveAttribute('aria-disabled');
+      expect(input).not.toHaveAttribute('disabled');
+      await user.click(input);
+      await user.type(input, '2026-03-15');
+      await user.keyboard('{ArrowDown}');
+      expect(input).toHaveValue('');
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+      expect(onChange).not.toHaveBeenCalled();
     });
   });
 

package/src/DateInput/DateInput.tsx

@@ -79,6 +79,18 @@ import {
 import {useDevWarning} from '../hooks/useDevWarning';
 
 const styles = stylex.create({
+  // The shared disabled style drops the focus ring; restore it while this
+  // field's own input holds focus (spec:AST-085 FR6). Defaults repeat it.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(input:focus)': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(input:focus)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   iconButton: {
     display: 'flex',
     alignItems: 'center',
@@ -241,13 +253,13 @@ export interface DateInputProps extends Omit<
 
   /**
    * 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`)
+   * `isDisabled`, the field shows a tooltip with this text on hover and
+   * keyboard focus, and the field's focusable controls are described by it,
    * 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.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the
+   * reason is tied to the field.
    *
    * @example
    * ```
@@ -537,11 +549,11 @@ function PointerDateField({
   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
+  // A disabled or busy field never renders native `disabled` (spec:AST-085
+  // FR1): the input and calendar button stay focusable via aria-disabled.
+  // Typing is blocked with readOnly and value mutation guards; calendar
+  // activation is blocked by the isEffectivelyDisabled guards. The
+  // disabled-reason tooltip's listeners attach to the input container. Only
   // the persistent isDisabled state (not the transient busy state) surfaces a
   // reason.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
@@ -703,8 +715,8 @@ function PointerDateField({
   // 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).
+      // The input is never natively disabled (spec:AST-085 FR1), so guard
+      // value mutation explicitly (readOnly also blocks typing).
       if (isEffectivelyDisabled) {
         return;
       }
@@ -733,6 +745,11 @@ function PointerDateField({
     if (pendingInput === null) {
       return;
     }
+    // Disabled or busy: keep the value, drop the draft (spec:AST-085 FR2).
+    if (isEffectivelyDisabled) {
+      setPendingInput(null);
+      return;
+    }
 
     if (!pendingInput.trim()) {
       if (value !== undefined) {
@@ -750,7 +767,14 @@ function PointerDateField({
       }
     }
     setPendingInput(null);
-  }, [pendingInput, value, fireChange, isDateDisabled, locale]);
+  }, [
+    pendingInput,
+    isEffectivelyDisabled,
+    value,
+    fireChange,
+    isDateDisabled,
+    locale,
+  ]);
 
   // Handle blur - validate, check constraints, and clear pending input
   const handleBlur = useCallback(() => {
@@ -808,6 +832,7 @@ function PointerDateField({
           inputWrapperStyles.base,
           sizeStyles[size],
           isEffectivelyDisabled && inputWrapperStyles.disabled,
+          isEffectivelyDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status &&
             !isEffectivelyDisabled &&
@@ -823,7 +848,11 @@ function PointerDateField({
       <button
         type="button"
         onClick={handleToggle}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
+        // A tab stop while disabled too, so it carries the reason (FR5).
+        aria-describedby={
+          showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined
+        }
         aria-label={
           popover.isOpen
             ? t('@astryx.dateInput.toggleCalendarClose')
@@ -858,16 +887,15 @@ function PointerDateField({
         value={displayValue}
         onChange={handleInputChange}
         onBlur={chainEventHandlers(handleBlur, onBlurProp)}
-        onClick={chainEventHandlers(handleInputClick, onClickProp)}
+        onClick={
+          isEffectivelyDisabled
+            ? undefined
+            : chainEventHandlers(handleInputClick, onClickProp)
+        }
         onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
         placeholder={placeholder}
-        // 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-disabled={isEffectivelyDisabled ? 'true' : undefined}
+        readOnly={isEffectivelyDisabled || undefined}
         aria-labelledby={
           ariaLabelledByProp != null
             ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)

package/src/DateInput/DateInputTouch.test.tsx

@@ -554,11 +554,32 @@ describe('DateInput — field parity', () => {
         onChange={() => {}}
       />,
     );
-    expect(field()).toBeDisabled();
+    // Focusable, never natively disabled (AST-085 FR1), and still inert.
+    expect(field()).not.toHaveAttribute('disabled');
+    expect(field()).toHaveAttribute('aria-disabled', 'true');
+    field().focus();
+    expect(field()).toHaveFocus();
     fireEvent.click(field());
+    fireEvent.keyDown(field(), {key: 'Enter'});
+    expect(field()).toHaveAttribute('aria-expanded', 'false');
     expect(screen.queryByRole('grid')).not.toBeInTheDocument();
   });
 
+  it('does not call a caller onClick while disabled (AST-085 FR2)', () => {
+    const onClick = vi.fn();
+    render(
+      <DateInput
+        nativePicker="never"
+        label="Ship date"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    fireEvent.click(field());
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
   it('stays focusable and explains itself when disabled with a reason', () => {
     render(
       <DateInput

package/src/DateInput/NativeDateField.test.tsx

@@ -601,12 +601,38 @@ describe('DateInput nativePicker', () => {
     await act(async () => resolveAction());
   });
 
-  it('disables the control and its toggle when isDisabled', () => {
+  it('keeps a disabled control focusable and its toggle inert (AST-085 FR1, FR2)', () => {
     stubPointer(true);
     render(<DateInput label="Date" isDisabled onChange={() => {}} />);
 
-    expect(getInput()).toBeDisabled();
-    expect(screen.getByLabelText('Open calendar')).toBeDisabled();
+    const input = getInput();
+    expect(input).not.toHaveAttribute('disabled');
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).toHaveAttribute('readonly');
+    input.focus();
+    expect(input).toHaveFocus();
+    const toggle = screen.getByLabelText('Open calendar');
+    expect(toggle).not.toHaveAttribute('disabled');
+    expect(toggle).toHaveAttribute('aria-disabled', 'true');
+    const showPicker = vi.fn();
+    Object.defineProperty(input, 'showPicker', {value: showPicker});
+    fireEvent.click(toggle);
+    expect(showPicker).not.toHaveBeenCalled();
+  });
+
+  it('does not call a caller onClick while disabled (AST-085 FR2)', () => {
+    stubPointer(true);
+    const onClick = vi.fn();
+    render(
+      <DateInput
+        label="Date"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    fireEvent.click(getInput());
+    expect(onClick).not.toHaveBeenCalled();
   });
 
   it('ignores a change while disabled', () => {

package/src/DateInput/NativeDateField.tsx

@@ -82,6 +82,17 @@ import {
 import {chainEventHandlers} from '../utils/chainEventHandlers';
 
 const styles = stylex.create({
+  // Same as DateInput's: the focus ring for a focused disabled field.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(input:focus)': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(input:focus)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   wrapper: {
     gap: spacingVars['--spacing-2'],
   },
@@ -323,9 +334,10 @@ export function NativeDateField({
   // platform picker from its input.
   const isEffectivelyDisabled = isDisabled || isLoading;
 
-  // Disabled-reason tooltip, same contract as the other two surfaces: a
-  // disabled control swallows pointer events, so the listeners attach to the
-  // wrapper and the input stays focusable via aria-disabled.
+  // Same contract as the other two surfaces: a disabled field never renders
+  // native `disabled` (spec:AST-085 FR1); the input stays focusable via
+  // aria-disabled and readOnly. The disabled-reason tooltip's listeners
+  // attach to the wrapper.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -582,6 +594,7 @@ export function NativeDateField({
           sizeStyles[size],
           styles.wrapper,
           isEffectivelyDisabled && inputWrapperStyles.disabled,
+          isEffectivelyDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status &&
             !isEffectivelyDisabled &&
@@ -597,7 +610,7 @@ export function NativeDateField({
       <button
         type="button"
         onClick={openPicker}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
         aria-label={t('@astryx.dateInput.openCalendar')}
         tabIndex={-1}
         {...stylex.props(
@@ -615,6 +628,7 @@ export function NativeDateField({
       <span {...stylex.props(styles.slot)}>
         <input
           {...controlProps}
+          onClick={isEffectivelyDisabled ? undefined : controlProps.onClick}
           ref={mergedInputRef}
           id={id}
           type="date"
@@ -626,9 +640,8 @@ export function NativeDateField({
           onBlur={chainEventHandlers(handleBlur, onBlurProp)}
           min={min}
           max={max}
-          disabled={isEffectivelyDisabled && !showsDisabledMessage}
-          aria-disabled={showsDisabledMessage ? 'true' : undefined}
-          readOnly={showsDisabledMessage || undefined}
+          aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
+          readOnly={isEffectivelyDisabled || undefined}
           aria-labelledby={
             ariaLabelledByProp != null
               ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)

package/src/DateInput/TouchDateField.tsx

@@ -166,6 +166,17 @@ const sizeStyles = stylex.create({
 });
 
 const styles = stylex.create({
+  // Same as DateInput's: the focus ring for a focused disabled field.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(input:focus)': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(input:focus)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   // ---- the closed field ----
   wrapper: {
     gap: spacingVars['--spacing-2'],
@@ -620,11 +631,11 @@ export function TouchDateField({
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
 
-  // Disabled-reason tooltip, same contract as DateInput: a disabled control
-  // swallows pointer events, so the listeners attach to the wrapper and the
-  // input stays focusable via aria-disabled rather than the disabled
-  // attribute. Only the persistent disabled state surfaces a reason, never
-  // the transient busy one.
+  // Same contract as DateInput: a disabled or busy field never renders native
+  // `disabled` (spec:AST-085 FR1); the input stays focusable via
+  // aria-disabled. The disabled-reason tooltip's listeners attach to the
+  // wrapper. Only the persistent disabled state surfaces a reason, never the
+  // transient busy one.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1213,6 +1224,7 @@ export function TouchDateField({
           sizeStyles[size],
           styles.wrapper,
           isEffectivelyDisabled && inputWrapperStyles.disabled,
+          isEffectivelyDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status &&
             !isEffectivelyDisabled &&
@@ -1228,7 +1240,7 @@ export function TouchDateField({
       <button
         type="button"
         onClick={openSheet}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
         aria-label={t('@astryx.dateInput.openCalendar')}
         tabIndex={-1}
         {...stylex.props(
@@ -1259,11 +1271,14 @@ export function TouchDateField({
         readOnly
         inputMode="none"
         onChange={() => {}}
-        onClick={chainEventHandlers(openSheet, onClickProp)}
+        onClick={
+          isEffectivelyDisabled
+            ? undefined
+            : chainEventHandlers(openSheet, onClickProp)
+        }
         onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
         placeholder={placeholder}
-        disabled={isEffectivelyDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
         aria-labelledby={
           ariaLabelledByProp != null
             ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -45,14 +45,15 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disable the trigger and picker.',
+      description:
+        'Disable the trigger and picker. The trigger stays focusable and exposes `aria-disabled`; opening is blocked.',
       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.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and describes the trigger (activation stays blocked). Use this instead of wrapping a disabled DateRangeInput in Tooltip.',
     },
     {
       name: 'value',
@@ -240,7 +241,7 @@ export const docs = {
       {
         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.',
+          'Wrap a disabled DateRangeInput in Tooltip to explain why it is disabled. Use the disabledMessage prop instead, which ties the reason to the field.',
       },
     ],
     anatomy: [
@@ -344,7 +345,7 @@ export const docsDense = {
       {
         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.',
+          'Wrap a disabled DateRangeInput in Tooltip to explain why it is disabled. Use the disabledMessage prop instead, which ties the reason to the field.',
       },
     ],
   },
@@ -356,7 +357,7 @@ export const docsDense = {
     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',
+      'reason shown in a tooltip on hover/focus when disabled; describes the trigger',
     value:
       'selected range {start, end} or null; import DateRange type from @astryxdesign/core/DateRangeInput (do not redeclare)',
     onChange: 'callback on range change; null on clear',