@astryxdesign/core 0.7.4 → 0.7.5-canary.04434e7

package/src/Skeleton/Skeleton.tsx

@@ -39,9 +39,36 @@ const STAGGER_TIME = 100;
 // Animation Keyframes
 // =============================================================================
 
+/**
+ * The pulse climbs from 0.25 to 0.925 opacity in ten equal steps, then plays
+ * back down (`alternate`). The steps are written out as holds joined by
+ * 0.01% ramps, with a linear timing function, rather than produced by a
+ * `steps()` timing function: WebKit never runs a `steps()` animation on the
+ * compositor, so Safari would repaint the pulse on the main thread and freeze
+ * it whenever a script runs. These keyframes give the same values at the same
+ * times, which every engine can animate off the main thread.
+ */
 const skeletonFade = stylex.keyframes({
   '0%': {opacity: 0.25},
-  '100%': {opacity: 1},
+  '9.99%': {opacity: 0.25},
+  '10%': {opacity: 0.325},
+  '19.99%': {opacity: 0.325},
+  '20%': {opacity: 0.4},
+  '29.99%': {opacity: 0.4},
+  '30%': {opacity: 0.475},
+  '39.99%': {opacity: 0.475},
+  '40%': {opacity: 0.55},
+  '49.99%': {opacity: 0.55},
+  '50%': {opacity: 0.625},
+  '59.99%': {opacity: 0.625},
+  '60%': {opacity: 0.7},
+  '69.99%': {opacity: 0.7},
+  '70%': {opacity: 0.775},
+  '79.99%': {opacity: 0.775},
+  '80%': {opacity: 0.85},
+  '89.99%': {opacity: 0.85},
+  '90%': {opacity: 0.925},
+  '100%': {opacity: 0.925},
 });
 
 // =============================================================================
@@ -78,7 +105,8 @@ const styles = stylex.create({
       default: skeletonFade,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
-    animationTimingFunction: 'steps(10, end)',
+    // Linear between the keyframes' holds; see skeletonFade.
+    animationTimingFunction: 'linear',
   },
 });
 

package/src/Stepper/Step.tsx

@@ -1316,6 +1316,10 @@ export function Step({
   const iconLabelNode = (
     <div {...stylex.props(styles.iconLabelRow)}>
       {(!isCompact || indicatorPosition !== 'on-track') && indicatorNode}
+      {/* A space between the indicator and the label: the row is a flex
+          container, which drops whitespace-only text, so nothing changes on
+          screen, but a text reading of the button then keeps "1 Account" as two
+          words instead of "1Account". */}{' '}
       <span
         {...mergeProps(
           labelThemeProps,
@@ -1576,6 +1580,8 @@ export function Step({
               )}
             />
           </div>
+          {/* Whitespace between the indicator column and the label, as in
+              iconLabelNode. */}{' '}
           <div {...stylex.props(styles.otBodyV)}>
             {labelLineNode}
             {otDescriptionNode}
@@ -1658,6 +1664,7 @@ export function Step({
             )}
           />
         </div>
+        {/* Whitespace between the rail and the label, as in iconLabelNode. */}{' '}
         {/* The on-track indicator remains visible as a node on the rail at
             compact widths, but the wrapper becomes presentational with its
             label. Navigation moves to the named controls in the summary row. */}

package/src/Stepper/Stepper.test.tsx

@@ -2016,3 +2016,36 @@ describe('step-label and step-description theme targets', () => {
     );
   });
 });
+
+describe('clickable step text reading', () => {
+  // axe-core's Label in Name rule joins a button's text nodes with nothing
+  // between them, aria-hidden ones included, so a number badge next to a label
+  // reads as one word ("1Account") that the step's name does not contain.
+  // Whitespace between them changes nothing on screen (the rows are flex
+  // containers) and keeps the two words apart.
+  it.each([
+    ['vertical', 'separated'],
+    ['horizontal', 'separated'],
+    ['vertical', 'on-track'],
+    ['horizontal', 'on-track'],
+  ] as const)(
+    'keeps the number and label apart in a %s %s step',
+    (orientation, indicatorPosition) => {
+      render(
+        <Stepper
+          orientation={orientation}
+          indicatorPosition={indicatorPosition}
+          activeStep={0}
+          label="Steps"
+          onStepClick={() => {}}>
+          <Step step={0} label="Account" indicator="number" />
+          <Step step={1} label="Payment" indicator="number" />
+        </Stepper>,
+      );
+
+      const button = screen.getByRole('button', {name: /Account/});
+      expect(button.textContent).toMatch(/1\s+Account/);
+      expect(button.textContent).not.toMatch(/1Account/);
+    },
+  );
+});

package/src/TextArea/TextArea.doc.mjs

@@ -151,14 +151,14 @@ export const docs = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        'Makes the textarea read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only textarea is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.',
+        'Makes the textarea read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only textarea is not dimmed and keeps its form value. isDisabled takes precedence when both are set.',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip, so the reason is attached to the field itself.',
     },
     {
       name: 'isLoading',
@@ -364,7 +364,7 @@ export const docs = {
       {
         guidance: false,
         description:
-          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
   },
@@ -437,7 +437,7 @@ export const docsZh = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        '将文本域设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读文本域不会变暗，并保留在 Tab 顺序中。同时设置时 isDisabled 优先。',
+        '将文本域设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读文本域不会变暗，并保留其表单值。同时设置时 isDisabled 优先。',
       default: 'false',
     },
     {
@@ -637,7 +637,7 @@ export const docsZh = {
       {
         guidance: false,
         description:
-          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
   },
@@ -710,7 +710,7 @@ export const docsDense = {
       'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables textarea, prevents interaction.',
     isReadOnly:
-      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
+      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed.',
     disabledMessage:
       'Explains why textarea is disabled. With isDisabled, shows tooltip on hover/focus + keeps textarea focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextArea in Tooltip.',
     isLoading: 'Loading state w/ spinner inside input.',

package/src/TextArea/TextArea.test.tsx

@@ -13,10 +13,27 @@ import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {TextArea} from './TextArea';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
+// jsdom cannot match `:focus-visible`: compare the ring's StyleX class hash.
+const RING = stylex
+  .props(
+    stylex.create({
+      ring: {
+        boxShadow: {
+          default: null,
+          ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+        },
+      },
+    }).ring,
+  )
+  .className!.split(' ')
+  .pop()!;
+
 // FieldStatus announces status messages through the persistent useAnnounce
 // singletons; remove them between tests so role/aria-live queries in this
 // file never match a leftover region.
@@ -166,11 +183,50 @@ describe('TextArea', () => {
     expect(screen.getByRole('textbox')).toHaveAttribute('rows', '3');
   });
 
-  it('is disabled when isDisabled is true', () => {
+  it('exposes aria-disabled and read-only, not native disabled, when isDisabled is true', () => {
     render(
       <TextArea label="Description" isDisabled value="" onChange={() => {}} />,
     );
-    expect(screen.getByRole('textbox')).toBeDisabled();
+    const textarea = screen.getByRole('textbox');
+    expect(textarea).not.toBeDisabled();
+    expect(textarea).toHaveAttribute('aria-disabled', 'true');
+    expect(textarea).toHaveAttribute('readonly');
+  });
+
+  it('keeps a disabled textarea in the tab order (spec:AST-085)', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <TextArea label="First" value="" onChange={() => {}} />
+        <TextArea label="Second" isDisabled value="" onChange={() => {}} />
+        <TextArea label="Third" value="" onChange={() => {}} />
+      </>,
+    );
+    await user.tab();
+    await user.tab();
+    expect(screen.getByRole('textbox', {name: 'Second'})).toHaveFocus();
+  });
+
+  it('runs no caller handler from a disabled textarea and rings it under focus (spec:AST-085 FR2, FR6)', async () => {
+    const user = userEvent.setup();
+    const handlers = {onPaste: vi.fn(), onKeyDown: vi.fn()};
+    render(
+      <TextArea
+        label="Notes"
+        isDisabled
+        value=""
+        onChange={() => {}}
+        {...handlers}
+      />,
+    );
+    const textarea = screen.getByRole('textbox');
+    await user.click(textarea);
+    await user.keyboard('a');
+    await user.paste('x');
+    for (const handler of Object.values(handlers)) {
+      expect(handler).not.toHaveBeenCalled();
+    }
+    expect(textarea.parentElement).toHaveClass(RING);
   });
 
   it('is not disabled by default', () => {
@@ -872,7 +928,10 @@ describe('TextArea', () => {
           />
         </form>,
       );
-      expect(screen.getByRole('textbox')).toBeDisabled();
+      expect(screen.getByRole('textbox')).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
       expect([
         ...new FormData(container.querySelector('form')!).keys(),
       ]).toEqual([]);
@@ -1049,13 +1108,13 @@ describe('TextArea', () => {
       expect(textarea).toHaveValue('');
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
+    it('stays focusable when disabled without a reason', () => {
       render(
         <TextArea label="Notes" value="" onChange={() => {}} isDisabled />,
       );
       const textarea = screen.getByRole('textbox');
-      expect(textarea).toBeDisabled();
-      expect(textarea).not.toHaveAttribute('aria-disabled');
+      expect(textarea).not.toBeDisabled();
+      expect(textarea).toHaveAttribute('aria-disabled', 'true');
     });
   });
 });

package/src/TextArea/TextArea.tsx

@@ -52,6 +52,7 @@ import {
   type FieldInputBaseProps,
   useFieldInputStyling,
 } from '../Field/fieldParts';
+import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
@@ -253,7 +254,9 @@ export interface TextAreaProps extends Omit<
    */
   rows?: number;
   /**
-   * Whether the textarea is disabled.
+   * Whether the textarea is disabled. A disabled textarea is dimmed, cannot be
+   * edited, and is left out of form submission, but it stays in the tab order
+   * (`aria-disabled`, not the native attribute).
    * @default false
    */
   isDisabled?: boolean;
@@ -261,7 +264,7 @@ export interface TextAreaProps extends Omit<
    * Whether the textarea is read-only.
    * The value is shown at full opacity and still submits with the form, but
    * cannot be edited. Unlike `isDisabled`, a read-only textarea is not dimmed
-   * and stays in the tab order — use it for a value the user should see and
+   * and keeps its form value — use it for a value the user should see and
    * send but not change. `isDisabled` takes precedence when both are set.
    * @default false
    */
@@ -273,8 +276,8 @@ export interface TextAreaProps extends Omit<
    * discoverable by keyboard and assistive technology. The field cannot be
    * edited (it becomes read-only) while disabled.
    *
-   * Use this instead of wrapping a disabled textarea in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled textarea in `Tooltip`, so the
+   * reason is attached to the field itself.
    *
    * @example
    * ```
@@ -443,12 +446,20 @@ export function TextArea({
   // (spec:AST-086 FR8).
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), containerRef);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the textarea container (which already exists)
+  // Disabled-reason tooltip. The tooltip listeners attach to the textarea container (which already exists)
   // and the textarea stays perceivable via aria-disabled instead of the native
   // disabled attribute. The field is made read-only so it can't be typed into,
   // and value mutation is blocked by the isDisabled guard in handleChange.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
+  // A disabled field keeps its tab stop but, like a natively disabled one,
+  // runs no caller event handler other than focus and blur (`spec:AST-085` FR2).
+  const fieldProps = isDisabled
+    ? Object.fromEntries(
+        Object.entries(rest).filter(
+          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
+        ),
+      )
+    : rest;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
     // The container div is not naturally focusable; focusin bubbles up from
@@ -598,6 +609,7 @@ export function TextArea({
             inputWrapperStyles.base,
             styles.wrapper,
             isDisabled && inputWrapperStyles.disabled,
+            isDisabled && inputDisabledFocusStyles.ring,
             status && inputStatusBorderStyles[status.type],
             status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
@@ -612,23 +624,23 @@ export function TextArea({
           </span>
         )}
         <textarea
-          {...rest}
+          {...fieldProps}
           ref={useMergedRefs(ref, textareaRef)}
           id={id}
           name={isDisabled ? undefined : htmlName}
           value={optimisticValue}
           onChange={handleChange}
-          onPaste={onPaste}
+          onPaste={isDisabled ? undefined : onPaste}
           onFocus={onFocus}
           onBlur={onBlur}
           placeholder={placeholder}
           rows={rows}
-          // With a disabledMessage the textarea keeps focusability via
-          // aria-disabled so the reason is focus-discoverable; readOnly + the
-          // handleChange guard keep the value from changing.
-          disabled={isDisabled && !showsDisabledMessage}
-          aria-disabled={showsDisabledMessage ? 'true' : undefined}
-          readOnly={isReadOnly || showsDisabledMessage || undefined}
+          // A disabled textarea keeps its place in the tab order
+          // (spec:AST-085): aria-disabled instead of the native attribute,
+          // with readOnly + the handleChange guard keeping the value from
+          // changing.
+          aria-disabled={isDisabled ? 'true' : undefined}
+          readOnly={isReadOnly || isDisabled || undefined}
           spellCheck={hasSpellCheck}
           autoFocus={hasAutoFocus}
           data-autofocus={hasAutoFocus || undefined}

package/src/TextInput/TextInput.doc.mjs

@@ -93,14 +93,14 @@ export const docs = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.',
+        'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and keeps its form value. isDisabled takes precedence when both are set.',
       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 input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput 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 keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput in Tooltip, so the reason is attached to the field itself.',
     },
     {
       name: 'isLoading',
@@ -219,7 +219,7 @@ export const docs = {
       {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
       {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
       {guidance: false, description: "Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors."},
-      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead."},
+      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -311,14 +311,14 @@ export const docsZh = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        '将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留在 Tab 顺序中。同时设置时 isDisabled 优先。',
+        '将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留其表单值。同时设置时 isDisabled 优先。',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        '说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持输入框可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TextInput——已禁用的控件会吞掉外部 Tooltip 所需的悬停事件。',
+        '说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持输入框可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TextInput，以便把原因附加在字段本身上。',
     },
     {
       name: 'isLoading',
@@ -430,7 +430,7 @@ export const docsZh = {
       {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
       {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
       {guidance: false, description: "Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors."},
-      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead."},
+      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -458,7 +458,7 @@ export const docsDense = {
       {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
       {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
       {guidance: false, description: "Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors."},
-      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead."},
+      {guidance: false, description: "Don't wrap a disabled TextInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -489,7 +489,7 @@ export const docsDense = {
     isRequired: 'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables input, prevents interaction, dims element.',
     isReadOnly:
-      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
+      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed.',
     disabledMessage:
       'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextInput in Tooltip.',
     isLoading: 'Loading state w/ spinner+aria-busy.',

package/src/TextInput/TextInput.test.tsx

@@ -13,11 +13,28 @@
 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 * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {declaredValue} from '../__tests__/stylexDeclarations';
 import {InputGroup} from '../InputGroup';
 import {TextInput} from './TextInput';
 
+// jsdom cannot match `:focus-visible`: compare the ring's StyleX class hash.
+const RING = stylex
+  .props(
+    stylex.create({
+      ring: {
+        boxShadow: {
+          default: null,
+          ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+        },
+      },
+    }).ring,
+  )
+  .className!.split(' ')
+  .pop()!;
+
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
 // disabledMessage tooltip.
 beforeEach(() => {
@@ -138,9 +155,55 @@ describe('TextInput', () => {
     expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-required');
   });
 
-  it('sets disabled attribute when isDisabled is true', () => {
+  it('exposes aria-disabled and read-only, not native disabled, when isDisabled is true', () => {
     render(<TextInput label="Name" isDisabled value="" onChange={() => {}} />);
-    expect(screen.getByRole('textbox')).toBeDisabled();
+    const input = screen.getByRole('textbox');
+    expect(input).not.toBeDisabled();
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).toHaveAttribute('readonly');
+  });
+
+  it('keeps a disabled input in the tab order (spec:AST-085)', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <TextInput label="First" value="" onChange={() => {}} />
+        <TextInput label="Second" isDisabled value="" onChange={() => {}} />
+        <TextInput label="Third" value="" onChange={() => {}} />
+      </>,
+    );
+    await user.tab();
+    await user.tab();
+    expect(screen.getByRole('textbox', {name: 'Second'})).toHaveFocus();
+  });
+
+  it('runs no caller handler and submits no form from a disabled input (spec:AST-085 FR2)', async () => {
+    const user = userEvent.setup();
+    const handlers = {onEnter: vi.fn(), onKeyDown: vi.fn(), onPaste: vi.fn()};
+    const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
+    render(
+      <form onSubmit={onSubmit}>
+        <TextInput
+          label="Name"
+          isDisabled
+          value=""
+          onChange={() => {}}
+          {...handlers}
+        />
+      </form>,
+    );
+    await user.click(screen.getByRole('textbox'));
+    await user.keyboard('{Enter}');
+    await user.paste('x');
+    for (const handler of [...Object.values(handlers), onSubmit]) {
+      expect(handler).not.toHaveBeenCalled();
+    }
+  });
+
+  it('rings a disabled input under keyboard focus (spec:AST-085 FR6)', () => {
+    render(<TextInput label="Name" isDisabled value="" onChange={() => {}} />);
+    const wrapper = screen.getByRole('textbox').parentElement!;
+    expect(wrapper).toHaveClass(RING);
   });
 
   it('does not fire onChange when disabled', async () => {
@@ -515,7 +578,10 @@ describe('TextInput', () => {
           />
         </form>,
       );
-      expect(screen.getByRole('textbox')).toBeDisabled();
+      expect(screen.getByRole('textbox')).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
       expect([
         ...new FormData(container.querySelector('form')!).keys(),
       ]).toEqual([]);
@@ -888,13 +954,13 @@ describe('TextInput', () => {
       expect(input).toHaveValue('');
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
+    it('stays focusable when disabled without a reason', () => {
       render(
         <TextInput label="Owner" value="" onChange={() => {}} isDisabled />,
       );
       const input = screen.getByRole('textbox');
-      expect(input).toBeDisabled();
-      expect(input).not.toHaveAttribute('aria-disabled');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
     });
   });
 });
@@ -1093,8 +1159,12 @@ describe('TextInput clear button focus behavior', () => {
     expect(document.activeElement).toBe(input);
   });
 
-  it('defers focus restoration via requestAnimationFrame on pointer activation', () => {
+  it('focuses the input inside the tap on pointer activation, without scrolling', () => {
+    // iOS Safari brings up its keyboard only for a focus made while handling
+    // the touch: a deferred focus would leave an unfocused field focused but
+    // keyboardless.
     const handleChange = vi.fn();
+    const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
     const rafSpy = vi.spyOn(window, 'requestAnimationFrame');
     render(
       <TextInput
@@ -1104,14 +1174,17 @@ describe('TextInput clear button focus behavior', () => {
         onChange={handleChange}
       />,
     );
-
+    const input = screen.getByRole('textbox');
     const clearButton = screen.getByRole('button', {name: /clear/i});
+    expect(document.activeElement).not.toBe(input);
 
-    // Pointer activation (detail > 0)
     fireEvent.click(clearButton, {detail: 1});
 
     expect(handleChange).toHaveBeenCalledWith('', expect.any(Object));
-    expect(rafSpy).toHaveBeenCalled();
+    expect(document.activeElement).toBe(input);
+    expect(focusSpy).toHaveBeenLastCalledWith({preventScroll: true});
+    expect(rafSpy).not.toHaveBeenCalled();
+    focusSpy.mockRestore();
     rafSpy.mockRestore();
   });
 });