@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/TreeList/TreeList.spec.md

@@ -1,15 +1,15 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 5
 kind: component
 id: component:TreeList
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-09-20
 owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
+review_triggers: [public-api, behavior, theming, accessibility]
 verified_by:
   [
     packages/core/src/TreeList/TreeList.test.tsx,
@@ -26,27 +26,44 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: [spec:AST-005/DEC-1]
+system_specs: [spec:AST-002/DEC-1, spec:AST-005/DEC-1]
 ---
 
 # TreeList component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row.                                                                                                                                                       |
+| Behavior                | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `<li>`.                                                                      |
+| End-user impact         | A builder can reveal or style content for one row without causing every row in the tree to react.                                                                                                                                                                        |
+| Builder impact          | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in.                                                                                                     |
+| Compatibility/readiness | The contract is additive and preserves default output. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row.                                               |
+| Review checks           | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `<li>`, or moves the promised row target without an explicit compatibility decision.                    |
+| Governing rules         | [Public component API INV5–INV6](../../../../docs/architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../../../docs/specs/AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-TreeList presents hierarchical data as expandable tree rows. This draft records
-its current consumer anatomy, target ownership, delegated Icon glyph, and
-unreached stable parts without changing runtime behavior, styling, targets, or
-public API.
+TreeList presents hierarchical data as expandable tree rows. It owns the stable
+row boundary needed for one item's caller-supplied presentation or relational
+styling to differ from its peers without exposing the semantic list container or
+requiring product code to reconstruct TreeList behavior.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, aliases, and public API remain unchanged
+- Compatibility class: additive optional public API; no default rendering, DOM,
+  styling, or interaction changes when the inputs are absent
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: none
+- Migration decision: none; existing callsites remain valid
 
-Consumer migration instructions belong in consumer docs and release notes.
+The durable contract includes `className`, `style`, and `xstyle` even while
+implementation work is staged. Current implementation availability does not narrow
+the accepted API direction. Consumer syntax and release timing belong in
+`TreeList.doc.mjs` and release notes.
 
 ## Ownership boundary
 
@@ -56,28 +73,37 @@ Consumer migration instructions belong in consumer docs and release notes.
   targets.
 - The stable Item description rendered below an Item label.
 - Hierarchical placement, indentation, expansion, selection, and tree semantics.
+- One stable per-item styling seam on the Item row box.
 
 **Does not own / non-goals**
 
+- The caller's style values, selector vocabulary, or authored class names.
+- A styling seam on the semantic `<li>`, child group, or caller-provided slot
+  content.
 - The Chevron glyph artwork and Icon target — owned by `component:Icon`.
 - Header, Start content, and End content supplied through consumer slots — owned
   by the product callsite.
-- New targets for Item description or caller-provided slots — unresolved by this
-  factual backfill.
+- New targets for Item description or caller-provided slots.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer data, props, slots, and usage
-remain documented in `TreeList.doc.mjs`.
+| Concept          | Closed values or states               | Meaning                                                                                        | Availability by variant/orientation/state | Default | Owner                | Stability | Invalid-value behavior                                          |
+| ---------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | --------------------------------------------------------------- |
+| Item row styling | `className`, `style`, and/or `xstyle` | Applies caller-supplied classes, inline styles, or StyleX styles to one item's stable row box. | Every rendered item row                   | Absent  | `component:TreeList` | Stable    | TypeScript rejects unsupported values; supplied inputs compose. |
+
+The three mechanisms are one styling concept, not three separate feature tiers.
+Supporting one does not justify omitting another from the durable contract.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                          | Basis                             | Draft review state                                                        |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------- |
-| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs. | Current source, docs, and tests   | Verified current behavior; no new behavior decided                        |
-| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                | Current source and target docs    | Verified current inventory; focused placement coverage is partial         |
-| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                      | Current source and component docs | Verified current ownership; no target change                              |
-| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.  | Current source and target docs    | Verified current reachability; long-term theming intent remains unsettled |
+| ID  | Invariant                                                                                                                                                                                                                                                                 | Basis                                                                               | Contract state                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs.                                                              | Current source, docs, and tests                                                     | Current behavior                                    |
+| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                                                                             | Current source and target docs                                                      | Current behavior                                    |
+| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                                                                                   | Current source and component docs                                                   | Current ownership                                   |
+| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.                                                               | Current source and target docs                                                      | Current reachability gap; no new target is accepted |
+| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two. | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged        |
+| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision.    | Owner decision and the caller-owned per-row interaction boundary                    | Settled intent                                      |
 
 ### Allowed variation
 
@@ -88,49 +114,57 @@ remain documented in `TreeList.doc.mjs`.
   TreeList target.
 - **AV3 — Delegated glyph.** Icon may change the Chevron glyph's internal element
   shape while preserving its own public contract.
+- **AV4 — Row implementation.** The row's HTML tag and internal descendants may
+  change while the same logical row remains the target of all three styling
+  inputs and keeps the observable boundary in FR6.
 
 ### Representative states
 
-| State                    | Required invariant                                    | Allowed variation                             |
-| ------------------------ | ----------------------------------------------------- | --------------------------------------------- |
-| Empty tree               | Tree list remains; no Item instances render.          | Optional Header content.                      |
-| Flat items               | Each Item contains an Item label.                     | Description and consumer slots may be absent. |
-| Expandable item          | Item may contain Chevron and delegated Chevron glyph. | Expanded or collapsed state.                  |
-| Nested `lineGuides` tree | Guide instances show parent-child relationships.      | Count and position follow hierarchy.          |
-| `noGuides` tree          | Guide instances are absent; indentation remains.      | All other anatomy remains unchanged.          |
-| Described item           | Item description renders below Item label.            | Caller-provided description text.             |
+| State                    | Required invariant                                                                          | Allowed variation                             |
+| ------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| Empty tree               | Tree list remains; no Item instances render.                                                | Optional Header content.                      |
+| Flat items               | Each Item contains an Item label.                                                           | Description and consumer slots may be absent. |
+| Styled item              | The supplied `className`, `style`, and `xstyle` values compose on only that item's row box. | Any subset of the three inputs may be absent. |
+| Expandable item          | Item may contain Chevron and delegated Chevron glyph.                                       | Expanded or collapsed state.                  |
+| Nested `lineGuides` tree | Guide instances show parent-child relationships.                                            | Count and position follow hierarchy.          |
+| `noGuides` tree          | Guide instances are absent; indentation remains.                                            | All other anatomy remains unchanged.          |
+| Described item           | Item description renders below Item label.                                                  | Caller-provided description text.             |
 
 ### Transformation and precedence order
 
-- No new hierarchy, focus, expansion, layout, or styling precedence rule is
-  introduced.
+- **ORD1 — Item row styling.** Apply the Item target and component-owned row
+  styles, then consumer `xstyle`, then `className`, then inline `style`, using the
+  shared merge behavior. All three inputs combine; none replaces or suppresses
+  another input as a whole.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- The per-item styling seam adds no measurement, listener, observer, or global
+  resource requirement.
 
 ## Accessibility contract
 
-This draft does not change or extend TreeList's current tree, treeitem, group,
-roving-focus, expansion, selection, disabled, or activation behavior.
+The styling seam does not change TreeList's tree, treeitem, group, roving-focus,
+expansion, selection, disabled, or activation behavior. Styling inputs MUST NOT
+replace component-owned semantic or interaction props.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                   | Representation authority       | Hierarchy role    | Component contract |
-| ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
-| Tree list        | Groups the hierarchical tree and owns its density and guide variant. | Current source and public docs | Supporting        | FR1, FR2           |
-| Header           | Visibly names the tree with caller-provided content.                 | Caller-supplied content        | Prominent         | FR1, FR3           |
-| Item             | Paints one row and reflects density, selection, and disabled state.  | Current source and public docs | Prominent         | FR1, FR2           |
-| Chevron          | Provides the expand and collapse control for an Item with children.  | Current source and public docs | Supporting        | FR1, FR2           |
-| Chevron glyph    | Presents the current directional symbol inside Chevron.              | `component:Icon`               | Supporting        | FR1, FR3           |
-| Item label       | Presents the primary content that identifies an Item.                | Current source and public docs | Prominent         | FR1, FR2           |
-| Item description | Presents stable secondary text below Item label.                     | Current source and public docs | Supporting        | FR1, FR4           |
-| Start content    | Presents caller-provided content before Item label.                  | Caller-supplied content        | Context-dependent | FR1, FR3           |
-| End content      | Presents caller-provided content after Item label.                   | Caller-supplied content        | Context-dependent | FR1, FR3           |
-| Guide            | Paints a connector between related hierarchy levels.                 | Current source and public docs | Supporting        | FR1, FR2           |
+| Anatomy or state | Design requirement                                                               | Representation authority        | Hierarchy role    | Component contract |
+| ---------------- | -------------------------------------------------------------------------------- | ------------------------------- | ----------------- | ------------------ |
+| Tree list        | Groups the hierarchical tree and owns its density and guide variant.             | Current source and public docs  | Supporting        | FR1, FR2           |
+| Header           | Visibly names the tree with caller-provided content.                             | Caller-supplied content         | Prominent         | FR1, FR3           |
+| Item             | Paints one row and reflects density, selection, disabled state, and row styling. | Current source and owner choice | Prominent         | FR1, FR2, FR5, FR6 |
+| Chevron          | Provides the expand and collapse control for an Item with children.              | Current source and public docs  | Supporting        | FR1, FR2           |
+| Chevron glyph    | Presents the current directional symbol inside Chevron.                          | `component:Icon`                | Supporting        | FR1, FR3           |
+| Item label       | Presents the primary content that identifies an Item.                            | Current source and public docs  | Prominent         | FR1, FR2           |
+| Item description | Presents stable secondary text below Item label.                                 | Current source and public docs  | Supporting        | FR1, FR4           |
+| Start content    | Presents caller-provided content before Item label.                              | Caller-supplied content         | Context-dependent | FR1, FR3           |
+| End content      | Presents caller-provided content after Item label.                               | Caller-supplied content         | Context-dependent | FR1, FR3           |
+| Guide            | Paints a connector between related hierarchy levels.                             | Current source and public docs  | Supporting        | FR1, FR2           |
 
 Item description is stable TreeList-rendered anatomy, not consumer-owned slot
-structure. Its current lack of a target is observed reachability, not a decision
+structure. Its current lack of a target is a reachability gap, not a decision
 that it must remain unthemeable. Header, Start content, and End content remain
 caller-owned even though TreeList positions their slot wrappers.
 
@@ -154,7 +188,7 @@ caller-owned even though TreeList positions their slot wrappers.
   "Item label": {"target": "tree-list-item-label"},
   "Item description": {
     "none": {
-      "reason": "unsettled: No current public target reaches the stable Item description; future exposure still needs an owner decision"
+      "reason": "reachability-gap: No current public target reaches the stable Item description"
     }
   },
   "Start content": {
@@ -172,16 +206,17 @@ caller-owned even though TreeList positions their slot wrappers.
 ```
 
 The five local targets are current public seams. The Chevron glyph retains Icon
-ownership. Consumer-slot `none` dispositions are ownership boundaries; Item
-description's `none` disposition records a current audit gap and does not
-authorize a new target.
+ownership. Consumer-slot `none` dispositions are ownership boundaries. Item
+description's `none` disposition records current reachability only and does not
+authorize or prohibit a future target.
 
 ## Family and system relationships
 
+- `architecture:public-component-api` owns the shared `className`, `style`, and
+  `xstyle` composition order and preservation rules; this record admits that seam
+  for each TreeList Item row and fixes its target.
 - `architecture:component-theming-surface` owns anatomy qualification, target
   mapping, delegation, and factual `none` dispositions.
-- `architecture:public-component-api` owns the stable data, props, and slot
-  surface; this documentation adds no API.
 - `architecture:interaction-modality` owns shared keyboard and pointer modality;
   TreeList continues to own its existing tree focus and activation behavior.
 - `family:navigation-destinations` owns the shared accept/block result for a
@@ -192,33 +227,46 @@ authorize a new target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                    | Representative states                              | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section            |
-| ------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
-| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                | Five local targets and their documented states     | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming` |
-| FR3                 | Source inspection plus Icon public target metadata                                              | Expandable rows and caller-provided slots          | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming` |
-| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                            | Item with description                              | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                   | Canonical anatomy and five current local targets   | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                               | `audit:TreeList/theming` |
+| Contract            | Verification                                                                                            | Representative states                                 | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section            |
+| ------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection         | Flat, nested, described, headed, and slotted items    | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
+| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                        | Five local targets and their documented states        | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming` |
+| FR3                 | Source inspection plus Icon public target metadata                                                      | Expandable rows and caller-provided slots             | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming` |
+| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                                    | Item with description                                 | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy` |
+| FR5, FR6, ORD1      | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation | One input at a time; all three together; sibling rows | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails.                                                                                                  | `audit:TreeList/api`     |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                           | Canonical anatomy and five current local targets      | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                                                                                                                                 | `audit:TreeList/theming` |
 
-Focused target-placement assertions cover all five local targets: Tree list,
-Item, Chevron, Item label, and Guide. Existing tests do not assert the Icon
-instance that renders Chevron glyph.
+Focused target-placement assertions cover all five local targets. Runtime support
+and mutation-sensitive coverage for the item styling seam may land separately,
+but every implementation is judged against the complete three-mechanism contract.
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-API, behavior, or theming decision.
+### DEC-1 — Each Item row supports the complete standard styling seam
+
+**Reference:** `component:TreeList/DEC-1`
+**Decider:** cixzhang, 2026-09-20
+
+A caller may attach `className`, `style`, and `xstyle` to one TreeList item. All
+three compose on the Item row box so per-row presentation and relational styling
+can remain scoped to that row. `className` is intentionally supported, including
+for a StyleX marker class; the standard `style` and `xstyle` mechanisms remain
+part of the same durable seam even if implementation work arrives in stages.
+
+Rejected: exposing only `className` because it is sufficient for the motivating
+marker use case. That would make a temporary implementation slice define a
+permanent exception to Astryx's standard styling contract.
+
+Rejected: applying the seam to the outer semantic `<li>`. That element owns tree
+semantics and child grouping, while the row box is the stable visual and hover
+boundary callers need to address.
 
 ## Open questions
 
-- **OQ1 — Should Item description gain a stable public theming target?**
-  (`human-api`) Its current lack of reachability is an audit gap, not settled
-  intent.
-- **OQ2 — Should a focused test pin the delegated Chevron glyph's Icon
-  instance?** (`checkable`) Its presence is currently source-inspected rather
-  than asserted.
+None.
 
 ## Content boundary
 
 This file does not duplicate consumer prop tables/examples, shared modality
-rules, current audit results, or implementation steps. It links to their owners.
+rules, current audit results, implementation steps, or family/system rules. It
+links to their owners.

package/src/TreeList/TreeList.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
 import {TreeList} from './TreeList';
 import type {TreeListItemData} from './TreeListTypes';
 import {defineTheme} from '../theme/defineTheme';
@@ -45,6 +46,10 @@ function collectCssText(): string {
     .join('\n');
   return out;
 }
+const rowStyles = stylex.create({
+  custom: {opacity: 0.75},
+});
+
 const simpleItems: TreeListItemData[] = [
   {id: 'a', label: 'Item A'},
   {id: 'b', label: 'Item B'},
@@ -458,6 +463,30 @@ describe('TreeList', () => {
     expect(screen.getByTestId('badge')).toBeInTheDocument();
   });
 
+  it('forwards xstyle, className, and style to an item row', () => {
+    const items: TreeListItemData[] = [
+      {
+        id: 'a',
+        label: 'Styled row',
+        xstyle: rowStyles.custom,
+        className: 'consumer-row',
+        style: {visibility: 'visible'},
+      },
+    ];
+    render(<TreeList items={items} />);
+
+    const row = screen
+      .getByText('Styled row')
+      .closest('li')!
+      .querySelector('.astryx-tree-list-item')!;
+    expect(row).toHaveClass('consumer-row');
+    expect(row.className).toContain(
+      stylex.props(rowStyles.custom).className!.split(' ')[0],
+    );
+    expect(row).toHaveStyle({visibility: 'visible'});
+    expect(row.getAttribute('style')).toContain('--_tree-indent');
+  });
+
   // ===========================================================================
   // Density
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -325,6 +325,9 @@ export function TreeList({
           description={item.description}
           startContent={item.startContent}
           endContent={item.endContent}
+          xstyle={item.xstyle}
+          className={item.className}
+          style={item.style}
           hasChildren={hasChildren}
           hasExpandableItems={hasExpandableItems}
           onClick={item.onClick}

package/src/TreeList/TreeListItem.tsx

@@ -292,6 +292,10 @@ export interface TreeListItemInternalProps {
   target?: string;
   isDisabled?: boolean;
   isSelected?: boolean;
+  /** Consumer styles for the row element. See `TreeListItemData`. */
+  xstyle?: stylex.StyleXStyles;
+  className?: string;
+  style?: React.CSSProperties;
   hasChildren: boolean;
   /**
    * Whether the tree contains at least one expandable item anywhere (i.e. a
@@ -339,6 +343,9 @@ export function TreeListItem({
   description,
   startContent,
   endContent,
+  xstyle,
+  className,
+  style,
   onClick,
   href,
   target,
@@ -589,15 +596,22 @@ export function TreeListItem({
                   interactionOverlayStyles.backgroundImage,
                   isDisabled && styles.disabled,
                   isSelected && styles.selected,
+                  xstyle,
                 )
               : stylex.props(
                   styles.contentWrapper,
                   densityStyles[density],
                   isDisabled && styles.disabled,
                   isSelected && styles.selected,
+                  xstyle,
                 ),
+            // Consumer row props are merged last so useContainerReveal can
+            // publish both its classes and inline custom properties. Seed the
+            // private indent first, then preserve the standard inline-style
+            // precedence promised by the TreeList contract.
+            className,
+            {...indentStyle, ...style},
           )}
-          style={indentStyle}
           onClick={handleClick}>
           {innerContent}
         </div>

package/src/TreeList/TreeListTypes.ts

@@ -11,7 +11,8 @@
  * - /packages/core/src/TreeList/index.ts
  */
 
-import type {ReactNode} from 'react';
+import type {CSSProperties, ReactNode} from 'react';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import type {TreeListVariantMap} from './index';
 
 /** Spacing density for tree list items. */
@@ -62,4 +63,13 @@ export interface TreeListItemData {
 
   /** Whether the item is initially expanded. Only meaningful for items with children. */
   isExpanded?: boolean;
+
+  /** StyleX styles applied to the item's row element. */
+  xstyle?: StyleXStyles;
+
+  /** Class applied to the item's row element. */
+  className?: string;
+
+  /** Inline styles applied to the item's row element. */
+  style?: CSSProperties;
 }

package/src/Typeahead/BaseTypeahead.spec.md

@@ -98,7 +98,7 @@ Draft requirements identify their observational or current-authority basis.
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
 | FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input.                                                        | Current source and tests                              | verified shipped behavior                      |
 | FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched.                                                                                                       | Public API, current i18n character utility, tests     | verified audit remediation                     |
-| FR3 | A newer query, selection, clear, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation).                                           | Current source, focused retained-red probe, and tests | verified shipped behavior                      |
+| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation).                       | Current source, focused retained-red probe, and tests | verified shipped behavior                      |
 | FR4 | The popup is a named listbox whose result rows are options. A completed empty search renders one disabled option so the listbox retains a valid owned child.                                                                                                  | APG combobox pattern, axe, tests                      | verified audit remediation                     |
 | FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3). | Current source and tests                              | verified shipped behavior; Escape gap retained |
 | FR6 | Pending asynchronous source work sets `aria-busy` and renders one named Spinner unless the composed wrapper owns the busy indicator lane.                                                                                                                     | Current source, input-family FR7, tests               | verified shipped behavior                      |
@@ -139,8 +139,9 @@ Draft requirements identify their observational or current-authority basis.
 
 ### Performance and resources
 
-- **PR1 — Search lifetime.** One generation counter rejects stale responses;
-  debounce timers and optional source cancellation are cleared on replacement and
+- **PR1 — Search lifetime.** One generation counter rejects stale responses,
+  including responses from a source that has since been replaced; debounce
+  timers and optional source cancellation are cleared on replacement and
   unmount.
 
 ## Accessibility contract

package/src/Typeahead/BaseTypeahead.tsx

@@ -262,9 +262,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],
@@ -533,9 +538,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // Debounce ref
   const searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  // Monotonic counter incremented on selection and query-clear. Async
-  // searches that resolve after a selection compare their captured
-  // generation to the current value and discard stale results.
+  // Monotonic counter incremented on selection, query-clear, and source
+  // replacement. Async searches that resolve afterwards compare their
+  // captured generation to the current value and discard stale results.
   const searchGenRef = useRef(0);
   // The generation at which results were last populated. handleFocus
   // compares this to searchGenRef — if they differ, the cached results
@@ -543,6 +548,15 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // be re-shown.
   const resultsGenRef = useRef(0);
 
+  // Results still arriving from a replaced source must not land in the new
+  // one's menu.
+  const prevSearchSourceRef = useRef(searchSource);
+  if (prevSearchSourceRef.current !== searchSource) {
+    prevSearchSourceRef.current.cancel?.();
+    prevSearchSourceRef.current = searchSource;
+    searchGenRef.current++;
+  }
+
   // Layer for dropdown
   const handleLayerShow = useCallback(() => {
     onOpenChange?.(true);
@@ -987,15 +1001,15 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   const selectedKey =
     value == null ? null : getKey(value.id, () => results.indexOf(value));
 
-  // Cleanup timeout and cancel in-flight searches on unmount
+  // Unmount: clear the pending debounce and cancel in-flight work.
   useEffect(() => {
     return () => {
       if (searchTimeoutRef.current) {
         clearTimeout(searchTimeoutRef.current);
       }
-      searchSource.cancel?.();
+      prevSearchSourceRef.current.cancel?.();
     };
-  }, [searchSource]);
+  }, []);
 
   return (
     <>

package/src/Typeahead/Typeahead.test.tsx

@@ -574,6 +574,59 @@ describe('Typeahead', () => {
       expect(screen.getByText('Apple')).toBeInTheDocument();
       expect(screen.queryByText('Avocado')).not.toBeInTheDocument();
     });
+
+    it('discards a response from a source that was replaced while it was in flight', async () => {
+      let resolveOld: ((items: SearchableItem[]) => void) | null = null;
+      const oldSource: SearchSource = {
+        search: async () =>
+          new Promise<SearchableItem[]>(resolve => {
+            resolveOld = resolve;
+          }),
+        bootstrap: () => [],
+      };
+      const newSource: SearchSource = {
+        search: () => [{id: 'banana', label: 'Banana'}],
+        bootstrap: () => [],
+      };
+
+      const {rerender} = render(
+        <Typeahead
+          label="Fruit"
+          searchSource={oldSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'a'}});
+      await waitFor(() => expect(resolveOld).not.toBeNull());
+
+      // The source is swapped while the old search is still pending and no
+      // new query is typed. The stale response must not populate a menu that
+      // now reads from a different source.
+      rerender(
+        <Typeahead
+          label="Fruit"
+          searchSource={newSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+
+      await act(async () => {
+        resolveOld!([{id: 'apple', label: 'Apple'}]);
+      });
+      expect(screen.queryByText('Apple')).not.toBeInTheDocument();
+
+      // Work started against the new source still lands normally.
+      fireEvent.change(input, {target: {value: 'ba'}});
+      await waitFor(() =>
+        expect(screen.getByText('Banana')).toBeInTheDocument(),
+      );
+    });
   });
 
   it('renders with label', () => {