@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/EmptyState/EmptyState.spec.md

@@ -0,0 +1,189 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:EmptyState
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
+verified_by:
+  [
+    packages/core/src/EmptyState/EmptyState.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/docPropReferences.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+  ]
+contributing: []
+system_specs: [spec:AST-020/FR1, spec:AST-029/FR3]
+---
+
+# EmptyState component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one status region; callers choose heading level and compact layout.                |
+| Behavior                | Null, undefined, boolean, and empty-string optional values create no slot wrapper. Rendered content follows icon, text, then actions order; compact layout reduces spacing and stacks actions.   |
+| End-user impact         | A person reaches a named empty-content message and any next action without blank gaps from shallow-empty optional values; the title fits the surrounding document outline.                       |
+| Builder impact          | Callers supply content and actions, select heading semantics, and may compose supported root props and styling. No additional setup is required.                                                 |
+| Compatibility/readiness | The released default is preserved. This draft observes shipped behavior plus the narrow scalar-slot remediation; it adds no API, default, or compatibility promise.                              |
+| Review checks           | Reject a missing heading, an informative icon hidden as decorative, a shallow-empty optional scalar that still changes layout, a dropped root prop/ref/style, or a theme target without anatomy. |
+| Governing rules         | `architecture:public-component-api` INV1 and INV5–INV9; `architecture:component-theming-surface` INV2–INV6; `architecture:component-test-sufficiency` INV1–INV7, INV10–INV11; WCAG 2.2.          |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+`EmptyState` gives an otherwise empty content area a semantic heading, supporting
+context, optional decorative visual, and optional caller-owned next actions.
+
+## Compatibility and migration
+
+- Released default preserved: yes
+- Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- the status-region root, content order, heading element, and default/compact layout;
+- hiding the icon slot from assistive technology as decorative; and
+- whether optional slots create component-owned wrappers and spacing.
+
+**Does not own / non-goals**
+
+- the message copy, icon meaning, action controls, or action behavior — those belong to the product callsite and the components it supplies;
+- page-level heading order — the caller chooses `headingLevel` for its document; or
+- error, loading, or populated-content behavior.
+
+## Public concepts
+
+| Concept        | Closed values or states | Meaning                                                                   | Availability by variant/orientation/state | Default  | Owner                  | Stability | Invalid-value behavior                                  |
+| -------------- | ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------- | -------- | ---------------------- | --------- | ------------------------------------------------------- |
+| title          | string                  | The empty region's heading content.                                       | all                                       | required | `component:EmptyState` | stable    | type rejection                                          |
+| description    | string or absent        | Optional supporting context below the title.                              | all                                       | absent   | `component:EmptyState` | stable    | nullish and empty-string values omit the part           |
+| icon           | React node or absent    | Optional caller visual, exposed as decorative beside the textual message. | all                                       | absent   | product callsite       | stable    | nullish, boolean, and empty-string values omit the slot |
+| actions        | React node or absent    | Optional caller-owned next actions below the message.                     | all                                       | absent   | product callsite       | stable    | nullish, boolean, and empty-string values omit the slot |
+| heading level  | `1` through `6`         | The title's HTML heading level in the surrounding document outline.       | all                                       | `3`      | product callsite       | stable    | type rejection                                          |
+| layout variant | default, compact        | Compact reduces spacing and stacks the action slot vertically.            | all                                       | default  | `component:EmptyState` | stable    | type rejection                                          |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision. A `current` contract contains no unresolved rows.
+
+| ID  | Candidate invariant                                                                                                                                                                     | Basis                                                                                | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
+| FR1 | The component MUST render one status-region root containing the icon, text group, and actions in that reading order when present.                                                       | Current implementation and consumer docs; WCAG 2.2 SC 1.3.2 and SC 4.1.3             | verify             |
+| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role.                                                                  | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6     | verify             |
+| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface | verify             |
+| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered.                                                                  | Current implementation and tests; WCAG 2.2 SC 1.1.1                                  | verify             |
+| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the status-region root.                                                               | `architecture:public-component-api` INV5–INV8                                        | verify             |
+| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics.                                                              | Current implementation, tests, and consumer docs                                     | verify             |
+
+### Allowed variation
+
+- **AV1 — Caller content.** Message wording, decorative artwork, and action
+  composition may vary at the product callsite.
+- **AV2 — Theme paint.** Theme-controlled paint and typography may vary through
+  the documented targets while anatomy and content order remain stable.
+
+### Representative states
+
+| State                         | Required invariant                                        | Allowed variation                      |
+| ----------------------------- | --------------------------------------------------------- | -------------------------------------- |
+| title only                    | status root and selected heading level remain present     | message wording                        |
+| description                   | supporting text follows the title                         | text length and wrapping               |
+| decorative icon               | visual precedes text and is hidden from assistive tech    | artwork supplied by the caller         |
+| actions                       | caller controls follow the text group                     | one or more caller-owned controls      |
+| compact                       | reduced spacing and vertical actions preserve semantics   | theme paint and caller content         |
+| shallow-empty optional scalar | nullish, boolean, and empty-string values emit no wrapper | which optional slot receives the value |
+
+### Transformation and precedence order
+
+- **ORD1 — Root composition.** Component semantics and theme metadata combine
+  with component styles, then consumer `xstyle`, `className`, and `style` under
+  the shared merge contract; component-owned `role="status"` remains authoritative.
+
+### Performance and resources
+
+- **PR1 — Render-only surface.** EmptyState owns no retained state, listener,
+  observer, timer, or external resource.
+
+## Accessibility contract
+
+- **AR1 — Heading semantics.** The title is a heading at the caller-selected level.
+- **AR2 — Decorative visual.** The icon slot is hidden from assistive technology;
+  callers keep all necessary meaning in the title or description.
+- **AR3 — Status exposure.** The root exposes the empty message as a status region
+  without moving focus; action controls keep their own names, roles, and behavior.
+
+## Design relationships
+
+No current design record governs EmptyState-specific representation. Visual
+judgment remains evidence, not product authority.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Container": {"target": "empty-state"},
+  "Icon": {
+    "none": {
+      "reason": "intentional: caller-supplied decorative content keeps its own styling and has no component-owned paint target"
+    }
+  },
+  "Title": {"target": "empty-state-title"},
+  "Description": {"target": "empty-state-description"},
+  "Actions": {
+    "none": {
+      "reason": "intentional: caller-supplied controls keep their own component targets and behavior"
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+No current family record owns EmptyState-specific behavior.
+
+## Verification map
+
+| Contract       | Verification                                                        | Representative states                             | Mutation or failure expectation                                      | Audit section             |
+| -------------- | ------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
+| FR1–FR4, AR1–3 | focused DOM tests plus required exact-head accessibility evidence   | title only, all slots, absent/shallow-empty slots | order, heading, status, or decorative treatment regresses            | `audit:EmptyState/a11y`   |
+| FR5, ORD1      | focused root composition tests plus shared API guards               | DOM/data/event/style inputs, ref, root target     | accepted input is dropped or component semantics/styles are replaced | `audit:EmptyState/api`    |
+| FR6            | compact target/DOM tests plus required exact-head rendered evidence | default and compact, wide and narrow              | compact state, spacing, or action direction no longer applies        | `audit:EmptyState/layout` |
+| PR1            | source review                                                       | every render path                                 | a retained resource appears without a named owner                    | `audit:EmptyState/code`   |
+
+## Decision log
+
+No component-local decision is approved in this draft.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/EmptyState/EmptyState.test.tsx

@@ -1,7 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {EmptyState} from './EmptyState';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
@@ -11,6 +12,12 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   return [prose, component].filter(Boolean).join('\n\n');
 }
 
+const testStyles = stylex.create({
+  root: {
+    minWidth: '123px',
+  },
+});
+
 describe('EmptyState', () => {
   it('renders with title', () => {
     render(<EmptyState title="No results found" />);
@@ -52,7 +59,7 @@ describe('EmptyState', () => {
       />,
     );
     expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
-    // Description renders as <div> (never <p>) so block content composes safely.
+    // Description keeps its stable target element instead of paragraph semantics.
     expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
   });
 
@@ -132,6 +139,70 @@ describe('EmptyState', () => {
     expect(screen.getByTestId('empty-state')).toBeInTheDocument();
   });
 
+  it('does not render empty optional slot wrappers', () => {
+    const {container} = render(
+      <EmptyState title="No results" description="" icon={false} actions="" />,
+    );
+    const root = screen.getByRole('status');
+    expect(root).toHaveTextContent('No results');
+    expect(root).toHaveTextContent(/^No results$/);
+    expect(root.children).toHaveLength(1);
+    expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
+    expect(
+      container.querySelector('.astryx-empty-state-description'),
+    ).toBeNull();
+  });
+
+  it('composes root props and keeps component semantics authoritative', () => {
+    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(
+      <EmptyState
+        title="No results"
+        role="region"
+        data-owner="consumer"
+        className="consumer-class"
+        style={{width: '321px'}}
+        xstyle={testStyles.root}
+        onClick={onClick}
+      />,
+    );
+
+    const root = screen.getByRole('status');
+    expect(root).toHaveClass('astryx-empty-state', 'consumer-class');
+    expect(root).toHaveClass(expectedXstyleClass);
+    expect(root).toHaveAttribute('data-owner', 'consumer');
+    expect(root).toHaveStyle({width: '321px'});
+    fireEvent.click(root);
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('reflects compact layout on the root and preserves slot order', () => {
+    render(
+      <EmptyState
+        title="No results"
+        description="Try again."
+        icon={<span data-testid="icon">Icon</span>}
+        actions={<button type="button">Retry</button>}
+        isCompact
+      />,
+    );
+
+    const root = screen.getByRole('status');
+    expect(root).toHaveAttribute('data-variant', 'compact');
+    expect(root.children).toHaveLength(3);
+    expect(root.children[0]).toContainElement(screen.getByTestId('icon'));
+    expect(root.children[1]).toContainElement(
+      screen.getByRole('heading', {name: 'No results'}),
+    );
+    expect(root.children[2]).toContainElement(
+      screen.getByRole('button', {name: 'Retry'}),
+    );
+  });
+
   it('renders all slots together', () => {
     render(
       <EmptyState

package/src/EmptyState/EmptyState.tsx

@@ -23,7 +23,7 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -169,7 +169,7 @@ export function EmptyState({
         className,
         style,
       )}>
-      {icon != null && <div aria-hidden="true">{icon}</div>}
+      {isRenderable(icon) && <div aria-hidden="true">{icon}</div>}
       <div {...stylex.props(styles.textGroup)}>
         {createElement(
           HeadingTag,
@@ -181,11 +181,7 @@ export function EmptyState({
           ),
           title,
         )}
-        {description != null && (
-          // Rendered as <div> (not <p>): description accepts ReactNode and a
-          // <p> cannot legally contain block children, which causes hydration
-          // mismatches. The StyleX style sets margin: 0, so appearance is
-          // unchanged.
+        {isRenderable(description) && (
           <div
             {...mergeProps(
               themeProps('empty-state-description', {
@@ -200,7 +196,7 @@ export function EmptyState({
           </div>
         )}
       </div>
-      {actions != null && (
+      {isRenderable(actions) && (
         <div
           {...stylex.props(styles.actions, isCompact && styles.actionsCompact)}>
           {actions}

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.