@astryxdesign/core 0.7.2-canary.caec7ca → 0.7.2-canary.cbb7fa3

package/src/Field/Field.doc.mjs

@@ -114,7 +114,7 @@ export const docs = {
     },
     {
       name: 'labelIcon',
-      type: 'IconType',
+      type: 'ReactNode | IconType',
       description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
@@ -129,8 +129,8 @@ export const docs = {
     },
     {
       name: 'statusVariant',
-      type: "'attached' | 'detached'",
-      description: 'How the status message renders relative to the input. Attached overlaps the input border; detached floats below.',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description: 'How status feedback is placed. Attached overlaps an eligible opaque, bordered, fixed-height control; detached renders a message below custom or non-bordered controls; tooltip leaves the visible affordance to the wrapped input and announces its message without a FieldStatus box.',
       default: "'attached'",
     },
     {
@@ -170,17 +170,23 @@ export const docs = {
       { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
       { guidance: true, description: 'Use inputID and descriptionID to connect the label and description to the inner control with htmlFor and aria-describedby.' },
       { guidance: false, description: 'Nest Field around styled inputs such as TextInput, Typeahead, Select, DateInput, or TextArea; those components already render their own Field shell.' },
-      { guidance: false, description: 'Use the attached status variant on non-bordered controls such as sliders, switches, or checkboxes; use detached so the message does not overlap the control.' },
+      { guidance: true, description: 'Use attached status only when the wrapped control is opaque, bordered, and fixed-height; use detached for custom, tall, translucent, or non-bordered controls.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
       { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
     ],
     anatomy: [
+      {name: 'Container', required: true, description: 'Root field box that owns layout, width, and local stacking for the label, control, and status.'},
       {name: 'Label', required: true, description: 'Text identifying the field. Always rendered for accessibility, optionally hidden visually.'},
-      {name: 'Description', required: false, description: 'Helper text between the label and input explaining what to enter.'},
+      {name: 'Ordinary description', required: false, description: 'Helper text under the label in the ordinary field layout.'},
+      {name: 'Horizontal-label description', required: false, description: 'Helper text in the control column when FormLayout owns horizontal labels.'},
       {name: 'Control slot', required: true, description: 'A custom, native, or third-party control that does not already render a field shell.'},
       {name: 'Status message', required: false, description: 'Inline validation feedback showing error, warning, or success with a message.'},
+      {name: 'Input status icon', required: false, description: 'Shared status affordance used by Field-composed input controls.'},
+      {name: 'Input clear button', required: false, description: 'Shared clear action used by Field-composed input controls.'},
+      {name: 'Input clear icon', required: false, description: 'Glyph inside the shared input clear action.'},
       {name: 'Optional/Required indicator', required: false, description: 'Badge next to the label showing whether the field is optional or required.'},
-      {name: 'Label tooltip', required: false, description: 'Info icon at the end of the label with a tooltip explaining the field.'},
+      {name: 'Label tooltip trigger', required: false, description: 'Info icon beside the label that opens explanatory content.'},
+      {name: 'Label tooltip surface', required: false, description: 'Layer-hosted explanatory content for the label tooltip.'},
     ],
   },
   examples: [
@@ -279,7 +285,7 @@ export const docsZh = {
       { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
       { guidance: true, description: 'Use inputID and descriptionID to connect the label and description to the inner control with htmlFor and aria-describedby.' },
       { guidance: false, description: 'Nest Field around styled inputs such as TextInput, Typeahead, Select, DateInput, or TextArea; those components already render their own Field shell.' },
-      { guidance: false, description: 'Use the attached status variant on non-bordered controls such as sliders, switches, or checkboxes; use detached so the message does not overlap the control.' },
+      { guidance: true, description: 'Use attached status only when the wrapped control is opaque, bordered, and fixed-height; use detached for custom, tall, translucent, or non-bordered controls.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
       { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
     ],
@@ -297,7 +303,7 @@ export const docsDense = {
       { guidance: true, description: 'Always provide a label; visually hide it only when context is clear.' },
       { guidance: true, description: 'Wire inputID/descriptionID to htmlFor and aria-describedby on the inner control.' },
       { guidance: false, description: 'Nest Field around styled inputs; it double-renders labels and status UI.' },
-      { guidance: false, description: 'Use attached status on sliders/switches/checkboxes; use detached so messages do not overlap.' },
+      { guidance: true, description: 'Use attached status only for opaque, bordered, fixed-height controls; use detached for custom, tall, translucent, or non-bordered controls.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
       { guidance: false, description: 'Hide the label without another way to understand field purpose.' },
     ],

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/Item/Item.doc.mjs

@@ -49,7 +49,7 @@ export const docs = {
       {
         name: '--_item-inset-inline',
         description:
-          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to cancel the inset when edgeCompensation="inline". Set paddingInline on `item` in a theme and both stay in sync.',
+          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to place rows for its edge treatments (edge="flush", "outset", and "bleed"). Set paddingInline on `item` in a theme and both stay in sync.',
         default: 'var(--spacing-2) (var(--spacing-3) for density="spacious")',
         private: true,
       },

package/src/Item/Item.tsx

@@ -342,7 +342,7 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-2'],
     // The inline inset is published as --_item-inset-inline and the padding
     // derives from it, so consumers that need to compensate for the inset
-    // (List's edgeCompensation) read the var instead of mirroring the values.
+    // (List's edge treatments) read the var instead of mirroring the values.
     // Themes that set paddingInline on `item` also feed this var via the
     // derived var registry, keeping padding and compensation in sync.
     '--_item-inset-inline': spacingVars['--spacing-2'],

package/src/List/List.doc.mjs

@@ -41,11 +41,18 @@ export const docs = {
       description: 'Show dividers between items.',
       default: 'false',
     },
+    {
+      name: 'edge',
+      type: "'padded' | 'flush' | 'outset' | 'bleed'",
+      description:
+        "Where each row's text, dividers, and hover and selection backgrounds sit, relative to the list's edges and the container around it. 'padded' keeps text inside each row's padding, so it starts a little in from a heading above the list and backgrounds have room around it. 'flush' drops the rows' side padding: text starts on the heading's line, and dividers and backgrounds stop at the row's content, with no room beyond it on either side. It works anywhere and suits static rows. 'outset' puts text on the heading's line and reaches dividers and backgrounds a little past it into the container's padding; it suits interactive rows in a container. 'bleed' puts text on the heading's line and reaches dividers and backgrounds to the container's edges with square corners, like Table rows in a Card. A row's first content is what lines up with the heading: its marker, icon, or avatar when it has one, otherwise its label. 'outset' and 'bleed' reach into the padding of the nearest container that shares its padding: a Card, Section, Dialog, or BottomSheet, or a transparent container such as a Layout region with explicit padding or a padded ScrollableArea. Place the List directly in that container's padding: padding that Stack, Center, or your own styles add in between is not counted. Drawers and the automatic padding of LayoutContent and LayoutPanel aren't supported yet. With no such container, including in a Popover, they look like 'padded'. In a container with less padding than the rows' own, text starts a little after the heading's line. A theme's inline padding on `item` replaces the row padding of every value, including the zero padding of flush.",
+      default: "'padded'",
+    },
     {
       name: 'edgeCompensation',
       type: "'inline'",
       description:
-        "Compensate for item content inset on each inline edge by cancelling the smaller of each item's built-in horizontal inset and the container's published inline padding. The margin reads the same variable the items derive their inline padding from, so it tracks density and theme padding overrides automatically without pulling rows outside zero-padding or full-bleed surfaces. Use under a section heading to bring row text toward the heading text. Content aligns when container padding is at least the item inset; smaller padding leaves some inset uncompensated. Omit to leave item positions unchanged.",
+        "Deprecated: use edge=\"outset\", which this sets. Still works; edge wins when both are set. `astryx upgrade` rewrites existing usage.",
     },
     {
       name: 'header',
@@ -89,6 +96,8 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -109,6 +118,8 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -132,6 +143,8 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },