@astryxdesign/core 0.7.1 → 0.7.2-canary.01eab6a

package/src/Field/Field.spec.md

@@ -0,0 +1,217 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Field
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Field/Field.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/docPropLiterals.test.ts,
+    packages/core/src/docPropReferences.test.ts,
+  ]
+modules: []
+families: [family:input-fields]
+design_specs:
+  [design:spatial-hierarchy, design:typography-hierarchy, design:system-states]
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+  ]
+contributing: []
+system_specs:
+  [spec:AST-027/FR1, spec:AST-027/FR2, spec:AST-027/FR3, spec:AST-027/FR11]
+---
+
+# Field component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                        |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `Field` wraps one caller-owned control with a label, optional description and status, optionality indicators, an explicit width, and root `BaseProps`; it also consumes FormLayout's horizontal-label mode.                                                     |
+| Behavior                | Single controls use a native label association; groups use a labelled span. Status messages receive stable IDs and use persistent live regions. Horizontal-label mode exposes one protected `data-layout` theme axis.                                           |
+| End-user impact         | People can identify a custom control, hear its description and changing status, and keep label/control/status relationships together across ordinary and horizontal form layouts.                                                                               |
+| Builder impact          | Builders provide the control and its ID, wire descriptions/status IDs to that control, choose group semantics when needed, and use a status placement that is safe for the wrapped surface.                                                                     |
+| Compatibility/readiness | This draft records released behavior. It adds no API or policy. The released default `statusVariant="attached"` for arbitrary children conflicts with the capability boundary in `family:input-fields/FR8` and remains open.                                    |
+| Review checks           | Reject a lost label/group association, dropped root props, caller replacement of `data-layout`, duplicate/missing status announcement, escaped local z-index, undocumented public literals, or a claim that all custom controls safely support attached status. |
+| Governing rules         | Established public `Field` interface; `family:input-fields` shared ownership and FR8; `architecture:public-component-api/INV5–INV8`; `spec:AST-027/FR1–FR3`; HTML label and ARIA naming/description semantics.                                                  |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+`Field` supplies shared label, description, status, width, and layout chrome for a native, custom, or third-party control that does not already own an Astryx field shell. The caller continues to own the control's value, interaction model, and control-specific accessibility semantics.
+
+## Compatibility and migration
+
+- Released default preserved: yes; `statusVariant` still defaults to `attached` in the current implementation.
+- Compatibility class: observational only; this draft changes no public prop, default, or behavior.
+- Controlled/uncontrolled behavior: caller-owned and unchanged.
+- Migration decision: none; resolving OQ1 requires a separate compatibility decision.
+
+## Ownership boundary
+
+**Owns**
+
+- The root field box, explicit width, local stacking boundary, and composition order.
+- Label and description placement around the caller-owned control.
+- Single-control versus grouped-label semantics.
+- Status-message placement and persistent live-region announcement.
+- The FormLayout horizontal-label projection.
+
+**Does not own / non-goals**
+
+- The wrapped control's value, focus model, keyboard behavior, disabled behavior, or event semantics — owned by the caller or wrapped component.
+- Applying `aria-describedby` to the wrapped control — the caller supplies the control and wires the generated or explicit IDs.
+- The visual and semantic contract of `FieldLabel`, `FieldStatus`, `Tooltip`, or caller-owned children — owned by those components.
+- Input-family member APIs and control-box part props — owned by `family:input-fields` and each member.
+
+## Public concepts
+
+| Concept                | Closed values or states                           | Meaning                                                                                          | Availability by variant/orientation/state                              | Default                        | Owner                 | Stability                 | Invalid-value behavior                |
+| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------ | --------------------- | ------------------------- | ------------------------------------- |
+| label mode             | single control; group                             | Chooses a native `<label htmlFor>` or a `<span>` named through `aria-labelledby`.                | All layouts.                                                           | single control                 | `component:Field`     | released                  | Type-constrained                      |
+| label visibility       | visible; visually hidden                          | Hides label and description visually while preserving them for assistive technology.             | All layouts.                                                           | visible                        | `component:Field`     | released                  | Type-constrained                      |
+| optionality marker     | none; optional; required                          | Shows the localized exception to FormLayout's optionality default.                               | Label presentation.                                                    | none                           | `component:Field`     | released                  | Both set warns; optional wins visibly |
+| status placement       | `attached`; `detached`; `tooltip`                 | Places a status box behind the control, below it, or leaves visible tooltip affordance to input. | Message required for a rendered box; tooltip still announces messages. | `attached` (see OQ1)           | `family:input-fields` | released; conformance gap | Type-constrained                      |
+| width                  | absent; number; CSS size string                   | Sizes the complete ordinary field box.                                                           | Ordinary box layout; horizontal-label mode uses `display: contents`.   | containing layout              | `component:Field`     | released                  | Type-constrained                      |
+| field layout           | ordinary box; `horizontal-labels` from FormLayout | Stacks content or projects label and input group into the parent grid.                           | Resolved from `FormLayoutContext`.                                     | ordinary box                   | `component:Field`     | released                  | Context-constrained                   |
+| description/status IDs | explicit; generated from `inputID`; absent        | Names stable description and message elements for caller-owned `aria-describedby` wiring.        | Generated only when the corresponding text is present.                 | generated when text is present | `component:Field`     | released                  | Empty text omits output               |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                          | Basis                                                                  | Draft review state                  |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ----------------------------------- |
+| FR1 | A single-control label renders as `<label htmlFor={inputID}>`; a group label renders as a non-label element with `labelID` for caller-owned `aria-labelledby`.                                                                                               | Established public interface; HTML and ARIA semantics                  | settled observation                 |
+| FR2 | Visually hidden labels and descriptions remain in the DOM and out of layout flow.                                                                                                                                                                            | Established public interface and accessibility behavior                | settled observation                 |
+| FR3 | Description and status IDs use explicit values when supplied and otherwise resolve to `${inputID}-desc` and `${inputID}-status` only when text exists.                                                                                                       | Established public interface                                           | settled observation                 |
+| FR4 | Error status messages announce assertively and warning/success messages politely through persistent live regions; tooltip placement renders no `FieldStatus` box but preserves the announcement.                                                             | Existing tests; family ownership                                       | settled observation                 |
+| FR5 | Ordinary layout orders label, control, then optional status. Horizontal-label mode places the label wrapper before one description/control/status group and reflects `data-layout="horizontal-labels"`; caller props cannot replace that owned theme marker. | Established layout interface; `architecture:public-component-api/INV5` | settled observation                 |
+| FR6 | `width` applies to the ordinary root field box; it does not style the caller-owned control and has no box to target in horizontal-label mode.                                                                                                                | Established public interface; `family:input-fields` shared owner       | settled observation                 |
+| FR7 | Root ref, data/ARIA/DOM inputs, events, `xstyle`, class name, and inline style reach or compose on the root without replacing component-owned semantics.                                                                                                     | `architecture:public-component-api/INV5–INV8`                          | settled observation                 |
+| FR8 | The Field root isolates every local attached-status paint relationship without assigning the root a page-level z-index.                                                                                                                                      | `spec:AST-027/FR1–FR3`, `FR11`                                         | settled observation                 |
+| FR9 | Attached status is safe only for an opaque, bordered, fixed-height control with reliable size reflection; custom, tall, wrapped, translucent, or non-bordered controls use detached or component-owned placement.                                            | `family:input-fields/FR8`; current default mismatch                    | human decision for released default |
+
+### Allowed variation
+
+- **AV1 — Caller-owned control.** Any control markup may occupy the slot; Field does not inspect, clone, or change it.
+- **AV2 — Form arrangement.** FormLayout may choose ordinary or horizontal-label arrangement without changing label, description, status, or announcement ownership.
+- **AV3 — Status surface.** Eligible controls may use attached placement; other controls use detached or a member-owned tooltip presentation.
+
+### Representative states
+
+| State             | Required invariant                                                             | Allowed variation                                          |
+| ----------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| label only        | One associated label precedes the caller-owned control.                        | Visible or visually hidden.                                |
+| description       | One description element receives the resolved ID.                              | Caller may use an explicit ID or the generated value.      |
+| group             | Group label is not a literal `<label>` and is referenceable by ID.             | Caller owns the group role and `aria-labelledby`.          |
+| status            | Message receives resolved ID and is announced once on its urgency channel.     | Attached/detached box or tooltip-owned visible affordance. |
+| horizontal labels | Label and input group participate in the parent grid and retain `data-layout`. | Description/status may be absent.                          |
+| explicit width    | Ordinary root receives the requested size and remains shrinkable.              | Number or CSS size string.                                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Root props.** Caller DOM/data/event props are forwarded first; Field-owned visual-state reflection is applied afterward; StyleX, caller class, and caller inline style compose in the documented order.
+- **ORD2 — IDs.** Explicit description/status ID wins; otherwise text presence derives an ID from `inputID`; absent text produces no ID-bearing element.
+- **ORD3 — Optionality.** FormLayout default optionality suppresses the matching visible marker; if both local booleans are true, Field warns and the optional marker wins visibly.
+
+### Performance and resources
+
+- **PR1 — No per-field global resource.** Field owns no listener, observer, timer, or external store. Status announcement delegates to the shared persistent live-region runtime.
+
+## Accessibility contract
+
+- **AR1 — Label association.** Single controls receive a native label association; grouped controls use caller-wired `aria-labelledby` and never a misleading literal `<label>`.
+- **AR2 — Description association.** Description text remains separate from the accessible name and exposes a stable ID for caller-owned `aria-describedby`.
+- **AR3 — Status announcement.** Changing status text is announced through the persistent live region, including tooltip placement where no message box renders.
+- **AR4 — Hidden labels.** Visually hidden label and description text remain available to assistive technology.
+
+## Design relationships
+
+| Anatomy or state              | Design requirement                                       | Representation authority                               | Hierarchy role            | Component contract |
+| ----------------------------- | -------------------------------------------------------- | ------------------------------------------------------ | ------------------------- | ------------------ |
+| Label and description         | `design:typography-hierarchy/DR4`, `DR6`                 | prescribed roles; exact tuning remains token-owned     | label and supporting text | FR1–FR3            |
+| Label/control/status grouping | `design:spatial-hierarchy` local and group relationships | prescribed relationship; exact gap remains token-owned | one field group           | FR5                |
+| Semantic status               | `design:system-states/DR2`                               | delegated to FieldStatus and wrapped input             | supporting feedback       | FR4, FR9           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Container": {"target": "field"},
+  "Label": {"target": "field-label"},
+  "Ordinary description": {
+    "none": {
+      "reason": "reachability-gap: The ordinary-layout description paints supporting text outside the field-label target and has no current public target of its own."
+    }
+  },
+  "Horizontal-label description": {
+    "delegatesTo": {"owner": "component:Text", "target": "text"}
+  },
+  "Control slot": {
+    "none": {
+      "reason": "intentional: The wrapped control is caller-owned or another Astryx component and retains its own theming surface."
+    }
+  },
+  "Status message": {"target": "field-status"},
+  "Input status icon": {"target": "input-status-icon"},
+  "Input clear button": {"target": "input-clear-button"},
+  "Input clear icon": {"target": "input-clear-icon"},
+  "Optional/Required indicator": {"inherits": "field-label"},
+  "Label tooltip trigger": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Label tooltip surface": {
+    "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
+  }
+}
+```
+
+The ordinary description remains stable consumer anatomy without a Field-owned target. A visible horizontal-label description delegates to `Text/text`; when `isLabelHidden` is true, the same content delegates to `VisuallyHidden` and exposes no painted target. The label tooltip splits its visible `Icon/icon` trigger from its layer-hosted `Tooltip/tooltip` surface.
+
+## Family and system relationships
+
+- `family:input-fields` owns shared status-placement capability and identifies Field as the standalone label, description, status-placement, and explicit-width owner.
+- `architecture:public-component-api` owns root prop, style, event, and ref composition.
+- `architecture:component-theming-surface` owns anatomy qualification and target disposition.
+- `architecture:component-test-sufficiency` owns mutation-sensitive evidence and bounded partitions.
+- `spec:AST-027` owns the isolated local paint relationship between the control and attached status.
+
+## Verification map
+
+| Contract                 | Verification                                                                           | Representative states                                                                                | Mutation or failure expectation                                                                                                | Audit section               |
+| ------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
+| FR1–FR3, AR1–AR2, AR4    | `Field.test.tsx` DOM/accessibility tests                                               | single control, group, visible/hidden label, explicit/generated IDs                                  | A lost association, wrong element, missing hidden text, or wrong ID fails.                                                     | `audit:Field/accessibility` |
+| FR4, AR3                 | `Field.test.tsx` announcement tests plus exact-head browser accessibility evidence     | first mount, update, repeat, error, warning, attached, detached, tooltip                             | A missing, duplicate, stale, or wrong-urgency announcement fails.                                                              | `audit:Field/accessibility` |
+| FR5–FR7, ORD1            | `Field.test.tsx`, BaseProps lint, theming-target tests, and exact-head visual evidence | ordinary/horizontal layout; class/style/xstyle/data/event/ref; description/status                    | Dropped caller input, replaceable layout marker, wrong order, or lost target fails.                                            | `audit:Field/api`           |
+| FR8                      | computed-style tests and exact-head browser rendering                                  | attached, detached, tooltip, no status                                                               | Removing isolation or ranking the root outside its parent fails.                                                               | `audit:Field/code-health`   |
+| FR9                      | family contract review and component-owned visual evidence                             | eligible bordered control; custom/tall/non-bordered control                                          | Attached placement on an ineligible surface remains visible as the current conformance gap.                                    | `audit:Field/behavior`      |
+| Theming anatomy          | knowledge validation and theming-target tests                                          | Field root, label, description, caller control, status, shared input affordances, indicator, tooltip | Missing, duplicate, or wrongly owned dispositions fail.                                                                        | `audit:Field/theming`       |
+| Documentation projection | docs typecheck and prop literal/reference tests                                        | labelIcon; all status placements; anatomy and usage guidance                                         | Docs omit or misstate a public type/literal/owner and validation fails or review rejects it.                                   | `audit:Field/docs`          |
+| RTL applicability        | exact-head RTL audit and verified-N/A registry                                         | all checked-in Field stories and source                                                              | A directional glyph, physical inline placement, order, scroll/drag, overlay, or directional keyboard behavior makes N/A stale. | `audit:Field/i18n-rtl`      |
+
+## Decision log
+
+No component-local decision is asserted. This draft records released behavior and leaves the current family-owned status-placement conflict in OQ1.
+
+## Open questions
+
+- **OQ1 — How should Field migrate the released `attached` default so arbitrary custom controls cannot receive a placement that `family:input-fields/FR8` says they may not safely support?** (`human-api`)
+
+## Content boundary
+
+This draft records verified shipped behavior and the current family-owned conformance gap. It does not approve a new default, migration, theme target, or compatibility promise, and it does not duplicate audit scores or run evidence.

package/src/Field/Field.test.tsx

@@ -2,7 +2,7 @@
 
 /**
  * @file Field.test.tsx
- * @input Uses vitest, @testing-library/react, Field component
+ * @input Uses Vitest, Testing Library, StyleX, Field, FormLayoutContext
  * @output Unit tests for Field component behavior
  * @position Testing; validates Field.tsx implementation
  *
@@ -10,11 +10,18 @@
  */
 
 import {describe, it, expect, vi, afterEach} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {Field} from './Field';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
+const testStyles = stylex.create({
+  root: {
+    minWidth: '123px',
+  },
+});
+
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
 }
@@ -572,6 +579,57 @@ describe('Field', () => {
       </FormLayoutContext>
     );
 
+    it('composes root props without letting callers replace layout semantics', () => {
+      const onClick = vi.fn();
+      const expectedXstyleClass = stylex.props(testStyles.root).className;
+      if (expectedXstyleClass == null) {
+        throw new Error('Expected the test xstyle to produce a class name.');
+      }
+
+      render(
+        <Field
+          label="Name"
+          inputID="name-input"
+          data-testid="field"
+          data-layout="consumer"
+          data-owner="consumer"
+          className="consumer-class"
+          style={{width: '321px'}}
+          xstyle={testStyles.root}
+          onClick={onClick}>
+          <input id="name-input" />
+        </Field>,
+        {wrapper: horizontalLabelsWrapper},
+      );
+
+      const field = screen.getByTestId('field');
+      expect(field).toHaveClass('astryx-field', 'consumer-class');
+      expect(field).toHaveClass(expectedXstyleClass);
+      expect(field).toHaveAttribute('data-layout', 'horizontal-labels');
+      expect(field).toHaveAttribute('data-owner', 'consumer');
+      expect(field).toHaveStyle({width: '321px'});
+      fireEvent.click(field);
+      expect(onClick).toHaveBeenCalledOnce();
+    });
+
+    it('visually hides the description in horizontal-label mode when the label is hidden', () => {
+      render(
+        <Field
+          label="Search"
+          inputID="search-input"
+          isLabelHidden
+          description="Search for items"
+          descriptionID="search-desc">
+          <input id="search-input" aria-describedby="search-desc" />
+        </Field>,
+        {wrapper: horizontalLabelsWrapper},
+      );
+
+      const description = screen.getByText('Search for items');
+      expect(description.className).toContain('visuallyHidden');
+      expect(description).toHaveAttribute('id', 'search-desc');
+    });
+
     it('applies display:contents when in horizontal-labels context', () => {
       const {container} = render(
         <Field label="Name" inputID="name-input">

package/src/Field/Field.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Field.tsx
- * @input Uses React, HTMLAttributes, ReactNode, FieldLabel, IconType, useFieldStatusAnnouncement
+ * @input Uses React, StyleX, BaseProps, FieldLabel/FieldStatus, FormLayoutContext, Text, VisuallyHidden, theme/status utilities
  * @output Exports Field component, FieldProps
  * @position Core implementation; consumed by index.ts, tested by Field.test.tsx
  *
@@ -30,6 +30,7 @@ import {mergeProps} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -298,20 +299,28 @@ export function Field({
     return (
       <div
         ref={ref}
+        {...props}
         {...mergeProps(
           themeProps('field', {layout: 'horizontal-labels'}),
           stylex.props(styles.horizontalLabels, xstyle),
           className,
           style,
-        )}
-        {...props}>
+        )}>
         <div {...stylex.props(styles.horizontalLabelAlign)}>{labelNode}</div>
         <div {...stylex.props(styles.inputStatusWrapper)}>
-          {description && (
-            <Text type="supporting" display="block" id={resolvedDescriptionID}>
-              {description}
-            </Text>
-          )}
+          {description &&
+            (isLabelHidden ? (
+              <VisuallyHidden id={resolvedDescriptionID}>
+                {description}
+              </VisuallyHidden>
+            ) : (
+              <Text
+                type="supporting"
+                display="block"
+                id={resolvedDescriptionID}>
+                {description}
+              </Text>
+            ))}
           {children}
           {statusNode}
         </div>

package/src/Grid/GridSpan.tsx

@@ -47,6 +47,9 @@ const baseStyles = stylex.create({
     minWidth: 0, // Prevent overflow in grid
     // Make span fill grid cell and stretch children
     display: 'grid',
+    // The implicit `auto` column would grow to a child's min-content width;
+    // a zero minimum keeps it inside the span.
+    gridTemplateColumns: 'minmax(0, 1fr)',
     height: '100%',
   },
 });

package/src/Heading/Heading.test.tsx

@@ -269,3 +269,60 @@ describe('Heading', () => {
     expect(element).not.toHaveAttribute('data-type', 'editorial');
   });
 });
+
+// With hasTruncateTooltip={false} nothing reads the measured overflow, so a
+// long table of truncated cells must not pay a layout read per cell.
+function countScrollWidthReads(run: () => void): number {
+  const proto = window.HTMLElement.prototype;
+  const original = Object.getOwnPropertyDescriptor(proto, 'scrollWidth');
+  let reads = 0;
+  Object.defineProperty(proto, 'scrollWidth', {
+    configurable: true,
+    get() {
+      reads += 1;
+      return 0;
+    },
+  });
+  try {
+    run();
+  } finally {
+    if (original) {
+      Object.defineProperty(proto, 'scrollWidth', original);
+    } else {
+      delete (proto as {scrollWidth?: number}).scrollWidth;
+    }
+  }
+  return reads;
+}
+
+describe('Heading maxLines without a truncation tooltip', () => {
+  it('takes no truncation measurement when hasTruncateTooltip is false', () => {
+    const reads = countScrollWidthReads(() => {
+      render(
+        <>
+          {Array.from({length: 20}, (_, index) => (
+            <Heading
+              level={3}
+              maxLines={1}
+              hasTruncateTooltip={false}
+              key={index}>
+              Cell {index} with text far wider than its column
+            </Heading>
+          ))}
+        </>,
+      );
+    });
+    expect(reads).toBe(0);
+  });
+
+  it('still measures when the tooltip is enabled', () => {
+    const reads = countScrollWidthReads(() => {
+      render(
+        <Heading level={3} maxLines={1}>
+          Text far wider than its column
+        </Heading>,
+      );
+    });
+    expect(reads).toBeGreaterThan(0);
+  });
+});

package/src/Heading/Heading.tsx

@@ -253,8 +253,12 @@ export function Heading({
   // the closed built-in StyleX maps with an unknown name.
   const builtinType = type && isBuiltinHeadingType(type) ? type : undefined;
 
-  // Truncation detection
-  const truncation = useTruncation({maxLines});
+  // Truncation detection. Only the tooltip reads the measured overflow, so
+  // with the tooltip off the text is clipped by CSS alone and nothing is
+  // measured or observed.
+  const truncation = useTruncation({
+    maxLines: hasTruncateTooltip === false ? 0 : maxLines,
+  });
 
   // Tooltip for truncated text
   const tooltipPlacement: LayerPlacement =

package/src/HoverCard/HoverCard.test.tsx

@@ -109,6 +109,64 @@ describe('useHoverCard identity', () => {
   });
 });
 
+// A card closed while the pointer rests on it unmounts without a mouseleave,
+// so the hook must not keep believing the pointer is over the card: if it
+// does, the next open of the same trigger never closes on leave.
+describe('useHoverCard closing while the pointer is on the card', () => {
+  function Harness() {
+    const card = useHoverCard({delay: 0, hideDelay: 0});
+    return (
+      <div>
+        <span ref={card.ref}>Trigger</span>
+        <output data-testid="state">{card.isOpen ? 'open' : 'closed'}</output>
+        {card.renderHoverCard(
+          <button type="button" onClick={card.hide}>
+            Pick
+          </button>,
+        )}
+      </div>
+    );
+  }
+
+  async function openThenRestOnCard() {
+    const state = screen.getByTestId('state');
+    fireEvent.mouseEnter(screen.getByText('Trigger'));
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    const pick = screen.getByRole('button', {name: 'Pick', hidden: true});
+    fireEvent.mouseLeave(screen.getByText('Trigger'));
+    fireEvent.mouseEnter(pick.parentElement!);
+    return {state, pick};
+  }
+
+  async function expectNextOpenClosesOnLeave(state: HTMLElement) {
+    const trigger = screen.getByText('Trigger');
+    fireEvent.mouseEnter(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    fireEvent.mouseLeave(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+  }
+
+  it('closes the next open on leave after hide() from inside the card', async () => {
+    render(<Harness />);
+    const {state, pick} = await openThenRestOnCard();
+
+    fireEvent.click(pick);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+
+  it('closes the next open on leave after Escape dismisses the card', async () => {
+    render(<Harness />);
+    const {state} = await openThenRestOnCard();
+
+    fireEvent.keyDown(document.body, {key: 'Escape'});
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+});
+
 describe('HoverCard', () => {
   it('renders trigger element', () => {
     render(

package/src/HoverCard/useHoverCard.tsx

@@ -345,6 +345,14 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     hideLayer();
   }, [clearTimeouts, hideLayer]);
 
+  // The imperative hide. A card closed while the pointer rests on it unmounts
+  // without a mouseleave, so the content-hover latch is cleared here; left set,
+  // it would keep the trigger's next hover-open from closing on leave.
+  const hide = useCallback(() => {
+    isHoveringContentRef.current = false;
+    hideLayer();
+  }, [hideLayer]);
+
   const {
     isTouchPointerRef,
     isTouchInteraction,
@@ -508,7 +516,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           ? null
           : document.getElementById(layerId);
       const hadFocus = card?.contains(document.activeElement) ?? false;
-      hideLayer();
+      hide();
       if (hadFocus) {
         isEscapeDismissingRef.current = true;
         triggerRef.current?.focus();
@@ -720,6 +728,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     isOpen: isLayerOpen,
     renderHoverCard,
     show: showLayer,
-    hide: hideLayer,
+    hide,
   };
 }

package/src/IconButton/IconButton.doc.mjs

@@ -46,7 +46,7 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and disables interaction.',
+      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
       default: 'false',
     },
     {
@@ -141,7 +141,7 @@ export const docsDense = {
     variant: 'visual style variant',
     size: 'size variant',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
-    isLoading: 'shows loading spinner + disables interaction',
+    isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
     isDisabled: 'disables button',
     tooltip: 'tooltip text shown on hover',
     onClick: 'standard click handler',

package/src/IconButton/IconButton.test.tsx

@@ -124,7 +124,9 @@ describe('IconButton', () => {
   it('shows loading state', () => {
     render(<IconButton label="Save" icon={<span>💾</span>} isLoading />);
     const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('forwards ref correctly', () => {