@astryxdesign/core 0.7.2-canary.fdd384f → 0.7.2

package/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts

@@ -0,0 +1,296 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FieldLabelAudit.a11y.chromium.spec.ts
+ * @input Exact-head FieldLabel story across semantics, themes, direction, and viewport sizes
+ * @output Screenshots and fail-closed sensor receipts for the FieldLabel whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a FieldLabel audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('field-label-audit-evidence');
+const WIDE = {width: 1024, height: 900};
+const NARROW = {width: 320, height: 900};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+
+type AuditCase = {
+  key: string;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  viewport: {width: number; height: number};
+};
+
+type AuditReceipt = {
+  passed: boolean;
+  expected: Record<string, unknown>;
+};
+
+const cases: AuditCase[] = [];
+function addPair(
+  key: string,
+  options: Partial<Omit<AuditCase, 'key' | 'mode'>> = {},
+) {
+  for (const mode of ['light', 'dark'] as const) {
+    cases.push({
+      key: `${key}-${mode}`,
+      mode,
+      direction: options.direction ?? 'ltr',
+      theme: options.theme ?? 'neutral',
+      viewport: options.viewport ?? WIDE,
+    });
+  }
+}
+
+addPair('default');
+addPair('custom-theme', {theme: 'butter'});
+addPair('rtl', {direction: 'rtl'});
+addPair('narrow', {viewport: NARROW});
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+  return `${server.origin}/iframe.html?id=core-fieldlabel--states&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+  await holdMotionStill(page);
+  await page.evaluate(async () => document.fonts.ready);
+  await page.waitForTimeout(40);
+}
+
+test.beforeAll(async () => {
+  fs.rmSync(OUTPUT, {recursive: true, force: true});
+  fs.mkdirSync(OUTPUT, {recursive: true});
+  checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+    encoding: 'utf8',
+  }).trim();
+  const expected = process.env.ASTRYX_HEAD_SHA;
+  if (expected && expected !== checkoutSha) {
+    throw new Error(
+      `checkout ${checkoutSha} does not match expected head ${expected}`,
+    );
+  }
+  server = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+  const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+  if (!response.ok) {
+    throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+  }
+  storybookSha = (await response.text()).trim();
+  if (storybookSha !== checkoutSha) {
+    throw new Error(
+      `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+    );
+  }
+});
+
+test.afterAll(async () => {
+  await server?.close();
+});
+
+for (const item of cases) {
+  test(item.key, async ({browser}) => {
+    const context = await browser.newContext({
+      viewport: item.viewport,
+      colorScheme: item.mode,
+      reducedMotion: 'reduce',
+    });
+    const page = await context.newPage();
+    const pageErrors: string[] = [];
+    page.on('pageerror', error => pageErrors.push(String(error)));
+    await page.goto(storyUrl(item), {waitUntil: 'load'});
+    await page.locator('#storybook-root').waitFor();
+
+    const targets = page.locator('.astryx-field-label');
+    await expect(targets).toHaveCount(7);
+    await expect(page.locator('label[for="field-label-default"]')).toHaveText(
+      'Email',
+    );
+    const description = page.locator('#field-label-description-help');
+    await expect(description).toHaveText(
+      'Shown in navigation and invitations.',
+    );
+    await expect(description.locator('xpath=ancestor::label')).toHaveCount(0);
+    await expect(page.locator('#field-label-group-label')).toHaveJSProperty(
+      'tagName',
+      'SPAN',
+    );
+    await expect(
+      page.getByRole('radiogroup', {name: 'Visibility'}),
+    ).toBeVisible();
+    await expect(page.getByText(/Required/)).toBeVisible();
+    await expect(page.getByText(/Optional/)).toBeVisible();
+    await expect(page.getByLabel('Search')).toBeVisible();
+    const tooltipAnchor = page
+      .locator('label[for="field-label-optional"] [aria-describedby]')
+      .first();
+    await expect(tooltipAnchor).toHaveCount(1);
+
+    await settle(page);
+    const observed = await page.evaluate(() => {
+      const labels = Array.from(
+        document.querySelectorAll<HTMLElement>('.astryx-field-label'),
+      ).map(label => {
+        const style = getComputedStyle(label);
+        const box = label.getBoundingClientRect();
+        return {
+          text: label.textContent?.replace(/\s+/g, ' ').trim(),
+          tagName: label.tagName,
+          htmlFor: label.getAttribute('for'),
+          color: style.color,
+          cursor: style.cursor,
+          geometry: {x: box.x, y: box.y, width: box.width, height: box.height},
+        };
+      });
+      const hidden = document.querySelector<HTMLElement>(
+        'label[for="field-label-hidden"]',
+      );
+      const hiddenBox = hidden?.getBoundingClientRect();
+      const firstLabel = document.querySelector<HTMLElement>(
+        '.astryx-field-label',
+      );
+      const currentTooltipAnchor = document.querySelector<HTMLElement>(
+        'label[for="field-label-optional"] [aria-describedby]',
+      );
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: firstLabel ? getComputedStyle(firstLabel).direction : null,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        labels,
+        hiddenGeometry: hiddenBox
+          ? {width: hiddenBox.width, height: hiddenBox.height}
+          : null,
+        tooltipAnchor: currentTooltipAnchor
+          ? {
+              ariaHidden: currentTooltipAnchor.getAttribute('aria-hidden'),
+              ariaLabel: currentTooltipAnchor.getAttribute('aria-label'),
+              describedBy:
+                currentTooltipAnchor.getAttribute('aria-describedby'),
+              tabIndex: currentTooltipAnchor.getAttribute('tabindex'),
+            }
+          : null,
+      };
+    });
+
+    const semanticsPass =
+      observed.labels.length === 7 &&
+      observed.labels.filter(label => label.tagName === 'SPAN').length === 1 &&
+      observed.labels.every(label => label.geometry.width > 0) &&
+      observed.hiddenGeometry?.width === 1 &&
+      observed.hiddenGeometry.height === 1;
+    const knownTooltipGapObserved =
+      observed.tooltipAnchor?.ariaHidden === 'true' &&
+      observed.tooltipAnchor.ariaLabel == null &&
+      observed.tooltipAnchor.tabIndex == null;
+
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: 'core-fieldlabel--states',
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+        targetCount: 7,
+        groupLabelTag: 'SPAN',
+        hiddenGeometry: {width: 1, height: 1},
+        knownGap:
+          'the tooltip anchor is anonymous and nonfocusable on this audited head',
+      },
+      observed: {
+        build: storybookSha,
+        ...observed,
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      checks: {semanticsPass, knownTooltipGapObserved},
+      passed:
+        storybookSha === checkoutSha &&
+        pageErrors.length === 0 &&
+        observed.theme === item.theme &&
+        observed.mode === item.mode &&
+        observed.direction === item.direction &&
+        observed.viewport.width === item.viewport.width &&
+        observed.viewport.height === item.viewport.height &&
+        observed.reducedMotion &&
+        !observed.horizontalOverflow &&
+        observed.fonts === 'loaded' &&
+        semanticsPass,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    await context.close();
+  });
+}
+
+test('manifest is complete', async () => {
+  const receiptFiles = fs
+    .readdirSync(OUTPUT)
+    .filter(file => file.endsWith('.sensors.json'));
+  const receipts = receiptFiles.map(
+    (file): AuditReceipt =>
+      JSON.parse(
+        fs.readFileSync(path.join(OUTPUT, file), 'utf8'),
+      ) as AuditReceipt,
+  );
+  fs.writeFileSync(
+    path.join(OUTPUT, 'manifest.json'),
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        component: 'core/FieldLabel',
+        build: checkoutSha,
+        frames: cases.map(item => ({
+          key: item.key,
+          image: `${item.key}.png`,
+          receipt: `${item.key}.sensors.json`,
+        })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  expect(receiptFiles).toHaveLength(cases.length);
+  expect(
+    receipts
+      .filter(receipt => !receipt.passed)
+      .map(receipt => receipt.expected),
+  ).toEqual([]);
+});

package/src/FormLayout/FormLayout.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
       name: 'direction',
       type: "'vertical' | 'horizontal' | 'horizontal-labels'",
       description:
-        'Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px).',
+        'Controls field arrangement. Vertical stacks top-to-bottom, horizontal uses one fractional grid track per field in logical inline order, and horizontal-labels uses CSS Grid with labels beside inputs on the inline-start side (collapsing to vertical when the viewport is <=480px).',
       default: "'vertical'",
     },
     {
@@ -51,6 +51,7 @@ export const docs = {
       { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
     ],
     anatomy: [
+      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
       {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
       {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
       {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
@@ -67,7 +68,7 @@ export const docsZh = {
       name: 'direction',
       type: "'vertical' | 'horizontal' | 'horizontal-labels'",
       description:
-        '控制字段排列方式。vertical 从上到下堆叠，horizontal 从左到右排列且等比弹性增长，horizontal-labels 使用 CSS Grid 将标签放在输入框左侧（在窄视口 <=480px 时折叠为垂直布局）。',
+        '控制字段排列方式。vertical 从上到下堆叠；horizontal 为每个字段使用一个 1fr 网格轨道，并按逻辑行内方向排列；horizontal-labels 使用 CSS Grid，将标签放在输入框的行内起始侧（当视口宽度 <=480px 时折叠为垂直布局）。',
       default: "'vertical'",
     },
     {
@@ -105,6 +106,7 @@ export const docsZh = {
       { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
     ],
     anatomy: [
+      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
       {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
       {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
       {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
@@ -127,13 +129,14 @@ export const docsDense = {
       { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
     ],
     anatomy: [
+      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
       {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
       {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
       {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
     ],
   },
   propDescriptions: {
-    direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
+    direction: 'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
     defaultOptionality: 'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required). Unset = per-field behavior.',
     children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',

package/src/FormLayout/FormLayout.spec.md

@@ -0,0 +1,192 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:FormLayout
+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/FormLayout/FormLayout.test.tsx,
+    apps/storybook/stories/FormLayout.stories.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: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+  ]
+contributing: []
+system_specs: []
+---
+
+# FormLayout component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `FormLayout` arranges caller-owned fields through `vertical`, `horizontal`, and `horizontal-labels` directions, provides a form-level optionality default, exports its context and supporting types, and accepts root `BaseProps`.                                      |
+| Behavior                | Vertical stacks children; horizontal creates one fractional grid track per child in logical inline order; horizontal-labels pairs Field labels and controls, then collapses below a 481px viewport.                                                                     |
+| End-user impact         | People encounter predictable field spacing and order, and assistive technology receives required-state information even when the form-wide visual convention leaves the common case unmarked.                                                                           |
+| Builder impact          | Builders supply the fields and any semantic `<form>`, title, or footer; nested layouts replace the outer direction and optionality context for their descendants.                                                                                                       |
+| Compatibility/readiness | This draft records released behavior. It changes no public API, default, or runtime behavior.                                                                                                                                                                           |
+| Review checks           | Reject lost root props, physical inline ordering, changed collapse boundaries, caller-overridable direction reflection, lost nested-context shadowing, or a visible optionality convention that disagrees with ARIA. Narrow label/control grouping remains open in OQ1. |
+| Governing rules         | Established public FormLayout interface; `family:input-fields` outer-arrangement ownership; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                                                          |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+`FormLayout` owns the outer spatial relationship among caller-owned form fields. It does not create form submission, field state, labels, controls, or action regions.
+
+## Compatibility and migration
+
+- Released default preserved: yes; direction defaults to `vertical`, and optionality remains field-owned when `defaultOptionality` is unset.
+- Compatibility class: observational only; this draft changes no public prop, default, or behavior.
+- Controlled/uncontrolled behavior: not applicable; FormLayout owns no form value or submission state.
+- Migration decision: none.
+
+## Ownership boundary
+
+**Owns**
+
+- Outer field arrangement, spacing, direction, and the viewport collapse for horizontal labels.
+- Form-level optionality context and nested-layout shadowing.
+- The root DOM element, root prop composition, and the `form-layout` theme target.
+
+**Does not own / non-goals**
+
+- Form semantics, submission, validation, or action placement — owned by the product callsite and native `<form>`.
+- Field labels, controls, status, and internal geometry — owned by `component:Field`, each input, and `family:input-fields`.
+- The content or visual contract of caller-supplied titles and footers — owned by their rendered components or the callsite.
+
+## Public concepts
+
+| Concept             | Closed values or states                         | Meaning                                                                 | Availability by variant/orientation/state                    | Default              | Owner                  | Stability | Invalid-value behavior |
+| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------- | ---------------------- | --------- | ---------------------- |
+| direction           | `vertical`; `horizontal`; `horizontal-labels`   | Selects the outer arrangement and provides that value to descendants.   | All layouts.                                                 | `vertical`           | `component:FormLayout` | released  | Type-constrained       |
+| default optionality | unset; `optional`; `required`                   | Marks only exceptions while controls preserve resolved required state.  | All directions; the nearest nested layout shadows the outer. | unset / per-field    | `component:FormLayout` | released  | Type-constrained       |
+| root composition    | DOM/data/ARIA/events; ref; class/style/`xstyle` | Extends the root layout container without replacing owned reflection.   | All directions.                                              | no caller decoration | `component:FormLayout` | released  | Shared merge contract  |
+| layout context      | direction plus optionality                      | Lets Field and inputs adapt their layout and required-state projection. | Descendants in the same layer scope.                         | vertical / unset     | `component:FormLayout` | released  | Nearest provider wins  |
+
+## 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 | Vertical direction stacks children with the shared spacing token.                                                                                                                                                                                                                                                           | Established public interface; current source and stories            | settled observation                                   |
+| FR2 | Horizontal direction places every direct child in one `1fr` grid track and follows the document's logical inline order without a component-owned wrap rule.                                                                                                                                                                 | Established public interface; current source and stories            | settled observation                                   |
+| FR3 | Horizontal-labels direction lets Field labels and control groups participate in a two-column grid, with the label on the inline-start side; at a viewport width of 480px or below it becomes one vertical flex column. Whether the collapsed label/control gap distinguishes each pair strongly enough remains open in OQ1. | Established public interface; Field composition and browser fixture | wide behavior settled; narrow grouping human decision |
+| FR4 | A nested FormLayout replaces the outer direction and optionality context for its descendants.                                                                                                                                                                                                                               | Existing context and unit tests                                     | settled observation                                   |
+| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose resolved `aria-required`, while native `required` remains tied to explicit field intent.                                                                                                           | Existing tests; `family:input-fields` ownership                     | settled observation                                   |
+| FR6 | Root ref, DOM/data/ARIA/event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the canonical target.                                                                                                                                                        | `architecture:public-component-api/INV5–INV8`                       | settled observation                                   |
+
+### Allowed variation
+
+- **AV1 — Caller content.** Any caller-owned field, heading, explanatory content, or action region may be a child; FormLayout does not inspect or rewrite it.
+- **AV2 — Nested arrangement.** Builders may nest vertical and horizontal layouts; each provider owns only its descendant scope.
+- **AV3 — Root styling.** Caller styling may change the container's presentation while preserving the public direction and child contracts.
+
+### Representative states
+
+| State                      | Required invariant                                                      | Allowed variation                                                  |
+| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| vertical                   | One block-axis stack with tokenized gaps.                               | Any caller-owned children.                                         |
+| horizontal                 | One `1fr` grid track per child in logical inline order.                 | Child count and content.                                           |
+| horizontal labels / wide   | Label/control pairs share consistent two-column tracks.                 | Label and control content.                                         |
+| horizontal labels / narrow | One vertical column at 480px or below with no component-owned overflow. | Label/control grouping remains OQ1; caller-owned content may wrap. |
+| optional by default        | Only explicitly required fields show the exception marker.              | Field and input type.                                              |
+| required by default        | Only explicitly optional fields show the exception marker.              | Field and input type.                                              |
+| nested                     | Inner direction and optionality replace outer values.                   | Any supported inner direction/default combination.                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Context.** Explicit props resolve against `vertical` and unset defaults, then the nearest provider exposes the resolved values to descendants.
+- **ORD2 — Root props.** FormLayout-owned target and direction reflection compose with StyleX and caller styling; caller DOM props reach the same root without replacing owned reflection.
+- **ORD3 — Optionality.** The layout default establishes the unmarked majority; a field-level `isRequired` or `isOptional` marks the exception and controls native validation only when explicitly requested.
+
+### Performance and resources
+
+- **PR1 — Stable context identity.** Descendants receive one memoized context value per direction/optionality pair; FormLayout owns no listener, observer, timer, or external resource.
+
+## Accessibility contract
+
+- **AR1 — Layout remains nonsemantic.** FormLayout renders a `<div>` and does not imply `<form>`, group, label, or submission semantics; callers provide those when their composition needs them.
+- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology.
+- **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
+
+## Design relationships
+
+No current component-local or shared design record prescribes a FormLayout-specific representation. Spacing uses the current token scale; exact tuning remains token-owned.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Layout container": {"target": "form-layout"},
+  "Form title": {
+    "none": {
+      "reason": "intentional: A title is caller-owned content; FormLayout neither renders nor styles a title part."
+    }
+  },
+  "Fields": {
+    "none": {
+      "reason": "intentional: Caller-owned Field and input components retain their own theming targets."
+    }
+  },
+  "Footer": {
+    "none": {
+      "reason": "intentional: A footer is caller-owned content; FormLayout neither renders nor styles an action region."
+    }
+  }
+}
+```
+
+The root target reflects the closed `direction` axis. It owns the outer arrangement container and does not claim the visual parts rendered by child components.
+
+## Family and system relationships
+
+- `family:input-fields` identifies FormLayout as the owner of outer arrangement, spacing, direction, and form-level optionality.
+- `component:Field` consumes horizontal-label direction and optionality while retaining label, control, description, and status ownership.
+- `architecture:public-component-api` owns root prop, styling, event, ref, and released-type composition.
+- `architecture:component-theming-surface` owns the root target's anatomy mapping and reflected direction axis.
+- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence selection.
+
+## Verification map
+
+| Contract          | Verification                                                                                           | Representative states                                            | Mutation or failure expectation                                                                               | Audit section                    |
+| ----------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1–FR4, ORD1     | `FormLayout.test.tsx`, exact-head `AuditMatrix` story-play guards, and independent rendered inspection | vertical, horizontal, horizontal-label wide/narrow, nested       | Changed display, order, breakpoint, or provider shadowing fails; narrow grouping remains visible for OQ1.     | `audit:FormLayout/behavior`      |
+| FR5, ORD3, AR2    | `FormLayout.test.tsx`, Field tests, and scoped browser accessibility audit                             | required/optional/unset defaults; explicit exceptions            | A redundant marker returns, resolved `aria-required` disappears, or native validation changes.                | `audit:FormLayout/accessibility` |
+| FR6, ORD2         | root composition tests, BaseProps lint, theming-target tests, and exact-head AuditMatrix play          | ref, DOM/data/ARIA/events, class/style/`xstyle`, every direction | A caller input drops, direction reflection is replaced, or the public target disappears.                      | `audit:FormLayout/api`           |
+| AR1, AR3          | DOM tests and exact-head browser/a11y evidence                                                         | plain root, native form wrapper, LTR/RTL                         | Layout invents semantics, changes DOM/keyboard order, or uses physical inline placement.                      | `audit:FormLayout/accessibility` |
+| Theming anatomy   | knowledge validation, consumer-doc projection, and theming-target tests                                | root target; caller-owned title, fields, and footer              | The target loses its semantic owner or FormLayout claims a child component's painter.                         | `audit:FormLayout/theming`       |
+| Documentation     | docs typecheck and prop literal/reference tests                                                        | all directions, breakpoint, optionality, root anatomy            | Docs claim wrapping, physical order, flex growth, or another behavior the released code lacks.                | `audit:FormLayout/docs`          |
+| RTL applicability | verified-N/A registry plus exact-head AuditMatrix logical-order assertion                              | horizontal and horizontal-labels in LTR/RTL                      | A physical side, directional glyph, transform, scroll/drag, overlay, or directional key path makes N/A stale. | `audit:FormLayout/i18n-rtl`      |
+
+## Decision log
+
+No component-local decision is asserted. This draft records released behavior and its current shared owners.
+
+## Open questions
+
+- **OQ1 — At 480px and below, should each horizontal-label pair preserve a smaller intra-field label/control gap than the gap between adjacent fields?** (`human-design`)
+
+## Content boundary
+
+This draft records verified shipped behavior and the unresolved narrow grouping relationship. It does not create form semantics, prescribe caller content, approve a new API or target, or duplicate consumer prop tables and audit-run scores.

package/src/FormLayout/FormLayout.test.tsx

@@ -71,6 +71,21 @@ describe('FormLayout', () => {
     expect(el).toHaveAttribute('role', 'group');
   });
 
+  it('keeps component-owned direction metadata over a colliding pass-through', () => {
+    render(
+      <FormLayout
+        direction="horizontal"
+        data-direction="vertical"
+        data-testid="layout">
+        content
+      </FormLayout>,
+    );
+    expect(screen.getByTestId('layout')).toHaveAttribute(
+      'data-direction',
+      'horizontal',
+    );
+  });
+
   // ─── Direction modes ────────────────────────────────────────────────────
 
   it('defaults to vertical direction', () => {

package/src/FormLayout/FormLayout.tsx

@@ -82,10 +82,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
    * Direction of field arrangement.
    *
    * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
-   * - `'horizontal'` — Fields arrange left-to-right in equal-width columns
-   *   using CSS Grid. Each child occupies one equal column.
-   * - `'horizontal-labels'` — CSS Grid with labels to the left of inputs.
-   *   Collapses to vertical when the container is narrow (≤480px).
+   * - `'horizontal'` — Fields occupy one `1fr` CSS Grid track per child in
+   *   logical inline order.
+   * - `'horizontal-labels'` — CSS Grid with labels beside their inputs on the
+   *   inline-start side. Collapses to vertical when the viewport is narrow
+   *   (≤480px).
    *
    * @default 'vertical'
    */
@@ -153,6 +154,7 @@ export function FormLayout({
     <FormLayoutContext value={contextValue}>
       <div
         ref={ref}
+        {...props}
         {...mergeProps(
           themeProps('form-layout', {direction}),
           stylex.props(
@@ -163,8 +165,7 @@ export function FormLayout({
           ),
           className,
           style,
-        )}
-        {...props}>
+        )}>
         {children}
       </div>
     </FormLayoutContext>

package/src/FormLayout/FormLayoutContext.ts

@@ -20,9 +20,9 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
  * Direction of form field arrangement.
  *
  * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
- * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.
- * - `'horizontal-labels'` — Fields stack vertically but labels sit to the left
- *   of their inputs (settings/admin panel pattern).
+ * - `'horizontal'` — Fields occupy one `1fr` grid track per child in logical inline order.
+ * - `'horizontal-labels'` — Fields stack vertically while labels sit beside
+ *   their inputs on the inline-start side (settings/admin panel pattern).
  */
 export type FormLayoutDirection =
   'vertical' | 'horizontal' | 'horizontal-labels';

package/src/Grid/Grid.doc.mjs

@@ -60,7 +60,7 @@ export const docs = {
     {
       name: 'columns',
       type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
-      description: 'Column configuration. A number is exactly N equal columns at every width and never reflows (e.g. `columns={3}`); for columns that reflow on small screens, use `{minWidth, max}`. Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
+      description: 'Column configuration. A number creates exactly N `1fr` tracks at every width and never reflows (e.g. `columns={3}`); a child\'s minimum content may widen its track. For columns that reflow on small screens, use `{minWidth, max}`. Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
     },
     {
       name: 'width',
@@ -97,6 +97,12 @@ export const docs = {
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Column spacing; overrides `gap` for the column axis.',
     },
+    {
+      name: 'rowHeight',
+      type: 'number',
+      description:
+        'Height of each implicit row track in pixels. Pair with `GridSpan rows={N}` for masonry-style layouts.',
+    },
     {
       name: 'align',
       type: "'start' | 'center' | 'end' | 'stretch'",