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

package/src/Item/Item.spec.md

@@ -0,0 +1,226 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Item
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-16
+owners: [cixzhang]
+review_triggers: [public-api, layout, theming]
+verified_by:
+  [
+    packages/core/src/Item/Item.test.tsx,
+    packages/core/src/List/List.test.tsx,
+    packages/core/src/RadioList/RadioList.test.tsx,
+    packages/core/src/CheckboxList/CheckboxList.test.tsx,
+    apps/storybook/stories/Item.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+    architecture:internationalization,
+  ]
+contributing: [contributing:api-conventions]
+system_specs: [spec:AST-017/FR3, spec:AST-057]
+---
+
+# Item component contract
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+This record governs how Item aligns its start and end content against the
+label. Item's swipe actions are governed by `spec:AST-057`, and its link and
+navigation semantics by `family:navigation-destinations`; other Item behavior
+remains described by its source, tests, and `Item.doc.mjs` until a record
+claims it.
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `align?: 'center' \| 'start' \| 'first-line'` on Item, ListItem, RadioListItem, and CheckboxListItem; default `center`.                                                             |
+| Behavior                | `first-line` centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row.          |
+| End-user impact         | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (`center`) or riding above the line (`start`).    |
+| Builder impact          | None by default. A builder opts in per row with `align="first-line"`; theme authors may style the `item` target's `first-line` alignment.                                           |
+| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit `align` are unchanged.                                    |
+| Review checks           | Reject a changed default, changed `center`/`start` geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. |
+| Governing rules         | FR1–FR8 below; `architecture:component-theming-surface/INV6`; `spec:AST-017/FR3`.                                                                                                   |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Item is the shared row behind lists, menus, pickers, and option rows. Its label
+can wrap, while its start and end content is often a single-line-sized mark: a
+status dot, a radio or checkbox, an icon, a short timestamp. Those marks belong
+to the first line of text they annotate. Item owns the alignment because only
+Item knows where its label's first line sits; a caller cannot place a slot
+against it without copying Item's typography.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; omitted `align` resolves to `center`.
+- Compatibility class: additive closed-axis value; additive typed prop on three
+  composing rows that already forward unknown props to Item at runtime.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: `component:Item/DEC-1`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The `align` axis: its values, default, and the geometry of each value for
+  the start and end content slots.
+- Reflecting the resolved alignment on the `item` theme target.
+- The forwarding rule for rows that compose Item and expose `align`.
+
+**Does not own / non-goals**
+
+- The `marker` slot's alignment — owned by whoever renders the marker; ListItem
+  positions its own markers against the first line.
+- Typography of caller content inside `label` — owned by the caller.
+- A theme-wide default alignment — themes style values; they do not choose a
+  component's prop default (`architecture:component-theming-surface`).
+- Alignment inside a slot's own content (for example, an avatar stack) — owned
+  by that content.
+
+## Public concepts
+
+| Concept   | Closed values or states         | Meaning                                                                                                                                              | Availability by variant/orientation/state                                   | Default  | Owner            | Stability | Invalid-value behavior                       |
+| --------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------- | ---------------- | --------- | -------------------------------------------- |
+| Alignment | `center`, `start`, `first-line` | `center`: slots centered on the whole text block. `start`: slot tops on the text block's top. `first-line`: slot centers on the first line's center. | Every density, layout, interaction mode, and direction; start and end slots | `center` | `component:Item` | stable    | Other values are rejected by the public type |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                             | Basis                                                                 | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------ |
+| FR1 | Item MUST accept `align` with exactly `center`, `start`, and `first-line`, and MUST resolve an omitted value to `center`. The geometry of `center` and `start` MUST NOT change.                                                                                                                                       | `component:Item/DEC-1`                                                | settled            |
+| FR2 | Under `first-line`, the block-axis center of each rendered start-content and end-content slot MUST coincide with the block-axis center of the label's first line box, for every slot block size.                                                                                                                      | Owner direction                                                       | settled            |
+| FR3 | Under `first-line`, a slot taller than the label's first line MUST stay inside the row's content box: the label and description move down by the difference, and the row grows to fit. No slot is clipped or painted into the row's block padding.                                                                    | Owner direction                                                       | settled            |
+| FR4 | A row whose label renders a single line and which has no description MUST render identically under `first-line` and `center`, for every slot block size.                                                                                                                                                              | Follows from FR2 and FR3                                              | settled            |
+| FR5 | The first line box is the label line as Item styles it, from the active theme's body text size and leading. A theme that changes those tokens moves the alignment with them. Caller content inside `label` that sets its own font size or line height is outside the FR2 guarantee.                                   | Shared typography source                                              | settled            |
+| FR6 | `first-line` MUST hold in every density, in `stacked` and `inline` layouts, with `labelLines` truncation, and in plain, button, link, link-root, delegated, and parent-role rows. In right-to-left text it MUST produce the same block-axis placement with the slots mirrored by logical order and no DOM reordering. | `architecture:internationalization`                                   | settled            |
+| FR7 | The `item` theme target MUST reflect the resolved alignment as its existing `align` selector axis, including `first-line`, and Item's public theming metadata MUST list that value. No new target, state, or theme-level default is added.                                                                            | `architecture:component-theming-surface/INV6`; `component:Item/DEC-2` | settled            |
+| FR8 | ListItem, RadioListItem, and CheckboxListItem MUST expose `align` with Item's values and default and forward it unchanged to the Item row they render. A composing row MUST NOT drop, remap, or narrow the value.                                                                                                     | Owner direction                                                       | settled            |
+
+### Allowed variation
+
+- **AV1 — Slot content.** Any slot content and size may appear; FR2 holds for
+  each slot independently, so a start slot and an end slot of different heights
+  each center on the first line.
+- **AV2 — Theme typography.** Body text size and leading may vary by theme; the
+  first line box follows them (FR5).
+- **AV3 — Row height.** Under `first-line` a row may be taller than the same
+  row under `center` when a slot is taller than the first line and a
+  description or second label line is present (FR3).
+
+### Representative states
+
+| State                                        | Required invariant                                                    | Allowed variation                     |
+| -------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------- |
+| Wrapped label, 6px dot start, short-text end | Both slot centers on the first line's center.                         | Density, theme typography, direction. |
+| One-line label, no description, any slot     | Identical to `center`.                                                | Slot size.                            |
+| Label and description, 40px avatar start     | Avatar center on the first line's center; text moves down; row grows. | Avatar size.                          |
+| Radio or checkbox row with a wrapped label   | The control centers on the first line.                                | Control size by Field size.           |
+| Right-to-left                                | Same block-axis placement; slots mirrored by logical order.           | Writing direction.                    |
+| Omitted `align`                              | Identical to today's `center`.                                        | None.                                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Resolution.** An explicit `align` on a composing row forwards to
+  Item unchanged; Item resolves an omitted value to `center`; the resolved value
+  drives both geometry and the `item` target's selector axis, so the two never
+  disagree.
+
+### Performance and resources
+
+- **PR1 — CSS geometry only.** Every alignment value MUST be achieved in CSS:
+  no measurement, observer, listener, state, Effect, or extra render pass.
+
+## Accessibility contract
+
+- **AR1 — Presentation only.** Alignment MUST NOT change the DOM order, role,
+  accessible name or description, focus target, tab order, or hit target of the
+  row or its slots.
+- **AR2 — No exposed text.** Any construct that implements `first-line` MUST
+  contribute no text to the accessibility tree.
+
+## Design relationships
+
+| Anatomy or state      | Design requirement                                    | Representation authority | Hierarchy role | Component contract |
+| --------------------- | ----------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Start and end content | Annotates the first line of the label it sits beside. | Owner direction          | Supporting     | FR2–FR4            |
+| Label first line      | The reference line the slots align to.                | Item typography          | Prominent      | FR5                |
+
+## Family and system relationships
+
+- `spec:AST-057` owns Item's swipe actions and their panels; alignment does
+  not change them, because the panels sit outside the row's flow.
+- `family:navigation-destinations` owns Item's link and navigation semantics;
+  alignment does not change them.
+- `architecture:component-theming-surface` owns how visual axes reach theme
+  targets; this record adds one value to Item's existing `align` axis.
+- `architecture:public-component-api` owns prop admission; FR8 types an existing
+  runtime pass-through rather than adding a parallel concept.
+- `architecture:internationalization` owns logical-direction behavior; FR6
+  applies it.
+- `spec:AST-017/FR3` classifies this as a non-breaking feature: it adds a value
+  and a typed prop, narrows nothing, and a caller who never sets `align` sees no
+  change.
+
+## Verification map
+
+| Contract | Verification                                                                    | Representative states                                         | Mutation or failure expectation                                                       | Audit section       |
+| -------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------- |
+| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test         | Omitted, `center`, `start`, `first-line`                      | A changed default, a missing `data-align="first-line"`, or a widened type fails.      | `audit:Item/api`    |
+| FR2–FR6  | Real-Chromium geometry assertions over the Item alignment stories               | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` |
+| FR8      | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"`                  | A row whose Item root lacks `data-align="first-line"` fails.                          | `audit:Item/api`    |
+| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row        | Plain and option rows                                         | Any difference in name, role, description, or order fails.                            | `audit:Item/a11y`   |
+| PR1      | Source review of Item's alignment styles                                        | All values                                                    | A ref, observer, or Effect added for alignment fails review.                          | `audit:Item/layout` |
+
+## Decision log
+
+<!-- Record the boundary or requirement, not how it was reached. A rejected alternative is at most one line here, kept only when it is consequential and likely to recur. -->
+
+### DEC-1 — `first-line` is an opt-in value; `center` stays the default
+
+**Reference:** `component:Item/DEC-1`
+**Decider:** cixzhang, 2026-10-16
+
+A wrapped label with a single-line-sized mark needs the mark on its first line,
+and neither existing value does that: `center` drops the mark to the middle of
+the row and `start` pins its top, which leaves a small mark above the line's
+center. A new value fixes those rows without moving any row that relies on
+today's default.
+
+Rejected: making `first-line` the default, because a slot sized to the whole
+text block, such as an avatar beside a label and description, is correct under
+`center`.
+
+### DEC-2 — The theme setting is the `item` target's alignment axis
+
+**Reference:** `component:Item/DEC-2`
+**Decider:** cixzhang, 2026-10-16
+
+Themes reach `first-line` rows through the `item` target's existing `align`
+selector axis, the same way they reach `center` and `start`. A theme can style
+those rows; it does not choose which value a row receives.
+
+## 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/Item/Item.test.tsx

@@ -531,6 +531,67 @@ describe('Item', () => {
     expect(screen.getByTestId('item')).toBeInTheDocument();
   });
 
+  it('reflects the resolved alignment on the item theme target', () => {
+    const {rerender} = render(<Item label="Item" data-testid="item" />);
+    expect(screen.getByTestId('item')).toHaveAttribute('data-align', 'center');
+    for (const align of ['center', 'start', 'first-line'] as const) {
+      rerender(<Item label="Item" align={align} data-testid="item" />);
+      const item = screen.getByTestId('item');
+      expect(item).toHaveClass('astryx-item');
+      expect(item).toHaveAttribute('data-align', align);
+    }
+  });
+
+  it('aligns the row on first baselines only under first-line', () => {
+    const {rerender} = render(<Item label="Item" data-testid="item" />);
+    const declares = (value: string) =>
+      rulesDeclaredFor(screen.getByTestId('item')).some(rule =>
+        rule.includes(`align-items: ${value}`),
+      );
+    expect(declares('baseline')).toBe(false);
+    rerender(<Item label="Item" align="start" data-testid="item" />);
+    expect(declares('baseline')).toBe(false);
+    rerender(<Item label="Item" align="first-line" data-testid="item" />);
+    expect(declares('baseline')).toBe(true);
+  });
+
+  it('gives each first-line slot a strut with no accessible text', () => {
+    render(
+      <Item
+        label="Item"
+        align="first-line"
+        startContent={<span data-testid="start">S</span>}
+        endContent={<span data-testid="end">E</span>}
+      />,
+    );
+    for (const id of ['start', 'end']) {
+      const slot = screen.getByTestId(id).parentElement!;
+      const before = rulesDeclaredFor(slot).filter(rule =>
+        rule.slice(0, rule.indexOf('{')).includes('::before'),
+      );
+      expect(before.some(rule => rule.includes('/ ""'))).toBe(true);
+    }
+  });
+
+  it('leaves center and start slots without a strut', () => {
+    const {rerender} = render(
+      <Item label="Item" startContent={<span data-testid="start">S</span>} />,
+    );
+    const hasStrut = () =>
+      rulesDeclaredFor(screen.getByTestId('start').parentElement!).some(rule =>
+        rule.slice(0, rule.indexOf('{')).includes('::before'),
+      );
+    expect(hasStrut()).toBe(false);
+    rerender(
+      <Item
+        label="Item"
+        align="start"
+        startContent={<span data-testid="start">S</span>}
+      />,
+    );
+    expect(hasStrut()).toBe(false);
+  });
+
   // ===========================================================================
   // Description rendering
   // ===========================================================================

package/src/Item/Item.tsx

@@ -67,7 +67,7 @@ const LazyItemSwipeLayer = lazy(async () => import('./ItemSwipeLayer'));
 // Types
 // =============================================================================
 
-export type ItemAlign = 'center' | 'start';
+export type ItemAlign = 'center' | 'start' | 'first-line';
 export type ItemDensity = 'compact' | 'balanced' | 'spacious';
 
 /**
@@ -168,7 +168,11 @@ export interface ItemProps extends BaseProps<HTMLElement> {
   endContent?: ReactNode;
 
   /**
-   * Vertical alignment of the start/end content slots.
+   * Vertical alignment of the start/end content slots. `center` centers each
+   * slot on the whole text block; `start` lines up slot tops with the text's
+   * top; `first-line` centers each slot on the label's first line, so a small
+   * mark (a status dot, a radio, a timestamp) stays level with the first line
+   * of a wrapped label. A slot taller than that line moves the text down.
    * @default 'center'
    */
   align?: ItemAlign;
@@ -338,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'],
@@ -351,6 +355,30 @@ const styles = stylex.create({
   alignStart: {
     alignItems: 'flex-start',
   },
+  // `first-line`: the row aligns its children on their first baselines. The
+  // label's first baseline is its first line's; each slot gets the same
+  // baseline from its strut (below), which the slot centers against its
+  // content. So each slot's center lands on the first line's center for any
+  // slot height, and a taller slot pushes the text down instead of leaving
+  // the row. Pure CSS: no measurement.
+  alignFirstLine: {
+    alignItems: 'baseline',
+  },
+  // A zero-width line of label text inside the slot: same size and leading as
+  // the label, so its line box is the label's first line box. The slot centers
+  // it against the slot's content, and the row's baseline alignment puts it on
+  // the label's first line. Its content carries empty alternative text so
+  // assistive technology reads nothing from it.
+  firstLineSlot: {
+    alignItems: 'center',
+    '::before': {
+      content: stylex.firstThatWorks('"\\200B" / ""', '"\\200B"'),
+      inlineSize: 0,
+      overflow: 'hidden',
+      fontSize: typeScaleVars['--text-body-size'],
+      lineHeight: typeScaleVars['--text-body-leading'],
+    },
+  },
   interactive: {
     cursor: {
       default: 'pointer',
@@ -712,7 +740,13 @@ export function Item({
     <>
       {marker}
       {startContent != null && (
-        <span {...stylex.props(styles.startContent)}>{startContent}</span>
+        <span
+          {...stylex.props(
+            styles.startContent,
+            align === 'first-line' && styles.firstLineSlot,
+          )}>
+          {startContent}
+        </span>
       )}
 
       {hasParentRole || isDelegate ? (
@@ -768,6 +802,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.endContent,
+            align === 'first-line' && styles.firstLineSlot,
             isDisabled && styles.disabledContent,
           )}>
           {endContent}
@@ -846,6 +881,7 @@ export function Item({
           styles.root,
           densityStyles[density],
           align === 'start' && styles.alignStart,
+          align === 'first-line' && styles.alignFirstLine,
           isInteractive && styles.interactive,
           isInteractive && interactionOverlayStyles.backgroundColor,
           isLinkRoot && styles.linkRoot,

package/src/Layer/layerViewportInset.source-build.test.mjs

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layerViewportInset.source-build.test.mjs
+ * @input Uses Babel, the core StyleX build config, the StyleX rule processor,
+ *   and the sources that cap or inset anchored layers
+ * @output Verifies the shipped stylesheet carries the dynamic-viewport,
+ *   safe-area gutter and caps (spec:AST-059 FR1–FR3), not only the fallbacks
+ * @position Regression test for the compiled layer viewport inset
+ *
+ * `stylex.firstThatWorks(a, b)` turns two `var()` arguments into one nested
+ * `var(a, b)`. A `defineConsts` reference compiles to such a `var()`, and the
+ * rule processor inlines a constant only where its `var()` stands alone, so a
+ * pair of bare constant references shipped as `var(--<hash>, <fallback>)`
+ * with `--<hash>` defined nowhere: every engine took the fallback.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {transformAsync} from '@babel/core';
+import stylexBabelPlugin from '@stylexjs/babel-plugin';
+import {describe, expect, it} from 'vitest';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.resolve(__dirname, '..');
+const CORE_ROOT = path.resolve(SRC, '..');
+
+const SOURCES = [
+  'Layer/layerViewportInset.stylex.ts',
+  'Layer/useLayer.tsx',
+  'Popover/Popover.tsx',
+  'DropdownMenu/DropdownMenu.tsx',
+  'DropdownMenu/DropdownMenuSubMenu.tsx',
+];
+
+async function compileStylesheet() {
+  const rules = [];
+  for (const relative of SOURCES) {
+    const filename = path.join(SRC, relative);
+    const result = await transformAsync(await fs.readFile(filename, 'utf8'), {
+      babelrc: false,
+      configFile: path.join(CORE_ROOT, 'babel.config.json'),
+      filename,
+    });
+    rules.push(...(result?.metadata?.stylex ?? []));
+  }
+  return stylexBabelPlugin.processStylexRules(rules, false);
+}
+
+/** Every declaration of `property` in the compiled sheet. */
+function declarations(css, property) {
+  return [...css.matchAll(new RegExp(`[{;]${property}:([^;}]+)`, 'g'))].map(
+    match => match[1],
+  );
+}
+
+describe('layer viewport inset stylesheet (spec:AST-059)', () => {
+  it('leaves no constant reference unresolved behind a fallback', async () => {
+    const css = await compileStylesheet();
+    const defined = new Set(
+      [...css.matchAll(/(--[\w-]+)\s*:/g)].map(match => match[1]),
+    );
+    const undefinedReferences = [
+      ...css.matchAll(/var\((--x[a-z0-9]+),/g),
+    ].flatMap(match => (defined.has(match[1]) ? [] : [match[0]]));
+    // Covers the caps and the four alignment-axis gutter margins.
+    expect(undefinedReferences).toEqual([]);
+  });
+
+  it('caps both axes against the dynamic viewport and the safe-area gutters', async () => {
+    const css = await compileStylesheet();
+    const blockCaps = declarations(css, 'max-height');
+    const inlineCaps = declarations(css, 'max-width');
+
+    expect(blockCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100dvb - .*safe-area-inset-top/),
+    );
+    expect(inlineCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100vi - .*safe-area-inset-left/),
+    );
+    // The older-engine fallbacks still ship, ahead of the preferred value.
+    expect(blockCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100vh - /),
+    );
+    expect(inlineCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100vw - /),
+    );
+  });
+});

package/src/Layer/layerViewportInset.stylex.ts

@@ -56,8 +56,12 @@ const GUTTER_BLOCK = `calc(max(${SPACING}, env(safe-area-inset-top, 0px), env(sa
 
 /**
  * The viewport gutter and the caps derived from it. Every value has an
- * `env()`-less fallback for engines without safe-area support; pair them with
- * `stylex.firstThatWorks(cap, capFallback)`.
+ * `env()`-less fallback for engines without safe-area support; pair them as
+ * `stylex.firstThatWorks(`calc(${cap})`, `calc(${capFallback})`)`. Pass
+ * each inside a `calc()` (or another function), never as a bare reference: a
+ * constant reference compiles to a `var()`, and `firstThatWorks` folds two
+ * `var()` arguments into one `var(cap, capFallback)` whose constant is never
+ * inlined, so every engine would take the fallback.
  */
 export const layerViewportInset = stylex.defineConsts({
   /** Gutter from the block-start viewport edge. */

package/src/Layer/layerViewportInset.test.ts

@@ -22,6 +22,7 @@ const GUTTER_OWNERS = new Set([
   'Dialog/Dialog.tsx',
   'Toast/ToastViewport.tsx',
   'BottomSheet/BottomSheetPanel.tsx',
+  'Drawer/Drawer.tsx',
   'Stepper/Step.tsx',
   'Tokenizer/useEndLaneReserve.ts',
 ]);

package/src/Layer/useLayer.tsx

@@ -102,15 +102,17 @@ const styles = stylex.create({
   // The cap is on the layer box itself: content wider than the viewport
   // overflows inside the layer, where the composing component decides
   // whether it scrolls or clips; the box never leaves the viewport.
+  // Each constant is wrapped in `calc()` so both declarations ship (see
+  // layerViewportInset).
   viewportFit: {
     boxSizing: 'border-box',
     maxInlineSize: stylex.firstThatWorks(
-      layerViewportInset.maxInlineSize,
-      layerViewportInset.maxInlineSizeFallback,
+      `calc(${layerViewportInset.maxInlineSize})`,
+      `calc(${layerViewportInset.maxInlineSizeFallback})`,
     ),
     maxBlockSize: stylex.firstThatWorks(
-      layerViewportInset.maxBlockSize,
-      layerViewportInset.maxBlockSizeFallback,
+      `calc(${layerViewportInset.maxBlockSize})`,
+      `calc(${layerViewportInset.maxBlockSizeFallback})`,
     ),
   },
   // Alignment-axis gutter (spec:AST-059 FR1): a margin on the far viewport
@@ -120,26 +122,26 @@ const styles = stylex.create({
   // (see layerSlideRules.ts).
   gutterInlineEnd: {
     marginInlineEnd: stylex.firstThatWorks(
-      layerViewportInset.gutterInline,
-      layerViewportInset.gutterInlineFallback,
+      `calc(${layerViewportInset.gutterInline})`,
+      `calc(${layerViewportInset.gutterInlineFallback})`,
     ),
   },
   gutterInlineStart: {
     marginInlineStart: stylex.firstThatWorks(
-      layerViewportInset.gutterInline,
-      layerViewportInset.gutterInlineFallback,
+      `calc(${layerViewportInset.gutterInline})`,
+      `calc(${layerViewportInset.gutterInlineFallback})`,
     ),
   },
   gutterBlockEnd: {
     marginBlockEnd: stylex.firstThatWorks(
-      layerViewportInset.gutterBlock,
-      layerViewportInset.gutterBlockFallback,
+      `calc(${layerViewportInset.gutterBlock})`,
+      `calc(${layerViewportInset.gutterBlockFallback})`,
     ),
   },
   gutterBlockStart: {
     marginBlockStart: stylex.firstThatWorks(
-      layerViewportInset.gutterBlock,
-      layerViewportInset.gutterBlockFallback,
+      `calc(${layerViewportInset.gutterBlock})`,
+      `calc(${layerViewportInset.gutterBlockFallback})`,
     ),
   },
 });
@@ -760,7 +762,16 @@ function useLayerImplementation(
         // hosted away from its trigger then still takes its sequential focus
         // order (and its popover nesting) from the trigger rather than from
         // its own DOM position. Browsers without the option ignore it.
-        popover.showPopover({source: triggerRef.current ?? undefined});
+        // `source` is declared as an `HTMLElement`. A caller-rendered icon
+        // trigger is an `SVGElement`, whose dictionary conversion throws
+        // before the popover opens. Omitting the option for it still anchors
+        // the layer, because positioning reads the anchor-name pair, and only
+        // gives up the invoker's focus order.
+        const trigger =
+          triggerRef.current instanceof HTMLElement
+            ? triggerRef.current
+            : undefined;
+        popover.showPopover({source: trigger});
       });
     } else {
       popover.style.display = 'block';

package/src/Layer/useLayerDismissal.ts

@@ -98,7 +98,7 @@ export interface UseLayerDismissalReturn {
  * routes each Escape press to the top-most REGISTERED layer, so one press
  * dismisses exactly one of them. Dialog (and what is built on it, including
  * CommandPalette), Popover and the menus built on it, ContextMenu, Tooltip,
- * HoverCard, Lightbox, MobileNav, BottomSheet, BottomSheetSwitcher and lab's
+ * HoverCard, Lightbox, MobileNav, BottomSheet, BottomSheetSwitcher and
  * `Drawer` register today.
  *
  * `DropdownMenuSubMenu` and `PowerSearchEditPopover` still run their own Escape

package/src/Layout/LayoutHeader.doc.mjs

@@ -6,6 +6,11 @@ export const docs = {
   name: 'LayoutHeader',
   subComponentOf: 'Layout',
   displayName: 'Layout Header',
+  keywords: [
+    'pageheader',
+    'appheader',
+    'header',
+  ],
   isHiddenFromOverview: true,
   description: 'Top bar for page titles, app bars, and toolbars.',
   playground: {

package/src/Layout/container.stylex.ts

@@ -4,8 +4,8 @@
  * @file container.stylex.ts
  * @input Uses @stylexjs/stylex, spacing from theme
  * @output StyleX utility for layout container styling
- * @position Layout utility; used by Card, Section, Dialog, BottomSheet, and the
- * Lab Drawer
+ * @position Layout utility; used by Card, Section, Dialog, BottomSheet, and
+ * Drawer
  *
  * ## Public API for themes
  *
@@ -19,7 +19,7 @@
  *   --astryx-card-padding-block-end
  *
  * Read order per level: `var(--astryx-…, <next level>)`, terminating at
- * `--spacing-4`. Same pattern for section, dialog, bottom-sheet, and the Lab
+ * `--spacing-4`. Same pattern for section, dialog, bottom-sheet, and
  * drawer.
  *
  * ```ts
@@ -150,7 +150,7 @@ const bottomSheetInlineEnd = `var(--astryx-bottom-sheet-padding-inline-end, ${bo
 const bottomSheetBlockStart = `var(--astryx-bottom-sheet-padding-block-start, ${bottomSheetShorthand})`;
 const bottomSheetBlockEnd = `var(--astryx-bottom-sheet-padding-block-end, ${bottomSheetShorthand})`;
 
-// Drawer (Lab) padding chains: --astryx-* then the next specificity level,
+// Drawer padding chains: --astryx-* then the next specificity level,
 // terminating at --spacing-4 like Dialog. Built as chained const strings (no
 // function calls) so StyleX can statically analyze them; see naming.ts for the
 // prefix policy.
@@ -522,8 +522,8 @@ export interface ContainerOptions {
    * This allows themes to override container padding via component-specific
    * public CSS custom properties without touching internal vars.
    *
-   * Used by Card, Section, Dialog, BottomSheet, and the Lab Drawer when no
-   * explicit padding prop is provided.
+   * Used by Card, Section, Dialog, BottomSheet, and Drawer when no explicit
+   * padding prop is provided.
    * @default undefined (uses explicit spacing token values)
    */
   useThemeDefault?: ContainerComponent;