@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/OverflowList/OverflowList.spec.md

@@ -1,44 +1,65 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:OverflowList
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/OverflowList/OverflowList.test.tsx,
+    packages/core/src/hooks/useOverflow.test.ts,
+    packages/core/src/hooks/computeOverflow.test.ts,
+    packages/core/src/theme/themingTargets.test.ts,
+    .github/visual-baseline/manifest.json,
     scripts/check-knowledge.mjs,
   ]
 modules: []
 families: []
 design_specs: []
-architecture: [architecture:component-theming-surface]
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
 contributing: []
 system_specs: []
 ---
 
 # OverflowList component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `children`, `overflowRenderer`, `onOverflowChange`, `gap`, `minVisibleItems`, `maxVisibleItems`, `maxRows`, `collapseFrom`, `behavior`, root `BaseProps`, `ref`. |
+| Behavior                | Shows as many caller items as fit the measured width, row count, and count limits, and hands the rest to a caller-rendered indicator and callback.               |
+| End-user impact         | People see a single tidy row (or a few rows) of items, with a caller's "more" control standing in for the ones that do not fit.                                  |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                     |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                                       |
+| Review checks           | Reject a measurement copy that is exposed or focusable, an indicator on the wrong edge, a callback that fires before measurement or repeats an unchanged set.    |
+| Governing rules         | `architecture:component-theming-surface`; `architecture:public-component-api` INV5–INV8.                                                                         |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-OverflowList renders a selected subset of caller-supplied items in a visible
-horizontal list and may render a caller-supplied indicator for collapsed items.
-Items may collapse because they exceed the measured space or a configured count
-limit. This draft records the current consumer anatomy and theming ownership
-without changing measurement, collapse behavior, targets, or public API.
+OverflowList renders a measured subset of caller-supplied items in a visible
+list and lets the caller show the collapsed remainder. It owns measurement and
+the choice of visible items; the caller owns the items and the indicator.
+
+Consumer syntax and examples belong in `OverflowList.doc.mjs`.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
-- Controlled/uncontrolled behavior: unchanged
+- Released default preserved: `yes` — `gap` 2, one row, collapse from the end,
+  observe self, no count limits.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
+- Controlled/uncontrolled behavior: not applicable; the visible count is
+  measured.
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
@@ -47,66 +68,86 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The visible list container and its current `overflow-list` theming target.
-- Measuring available space, applying configured count limits, and choosing
-  which supplied items remain visible.
+- The visible list container and its `overflow-list` target.
+- The hidden measurement copy, measuring available space, applying count and
+  row limits, and choosing which items stay visible.
+- When the overflow callback fires.
 
 **Does not own / non-goals**
 
 - The items supplied through `children` — owned by the caller.
-- The overflow indicator returned by `overflowRenderer` — owned by the caller.
-- The hidden inert measurement container as consumer-facing anatomy or a public
-  target.
+- The indicator returned by `overflowRenderer`, and any menu it opens — owned
+  by the caller.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `OverflowList.doc.mjs`.
+| Concept          | Closed values or states                | Meaning                                                                  | Availability by variant/orientation/state | Default       | Owner                    | Stability | Invalid-value behavior             |
+| ---------------- | -------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------- | ------------- | ------------------------ | --------- | ---------------------------------- |
+| Collapse edge    | `start`; `end`                         | Which end loses items first and holds the indicator.                     | Always                                    | `end`         | `component:OverflowList` | Stable    | Closed union; rejected by types.   |
+| Gap              | spacing step                           | Space between items and the indicator.                                   | Always                                    | 2             | `component:OverflowList` | Stable    | Closed union; rejected by types.   |
+| Count limits     | `minVisibleItems`; `maxVisibleItems`   | A floor and a cap on visible items.                                      | Always                                    | 0; no cap     | `component:OverflowList` | Stable    | The floor wins over a smaller cap. |
+| Rows             | positive number; unset                 | How many wrapped rows may show.                                          | Always                                    | one row       | `component:OverflowList` | Stable    | 1 or unset is a single line.       |
+| Measured box     | `observeSelf`; `observeParent`         | Whether the list measures its own width or its parent's.                 | Always                                    | `observeSelf` | `component:OverflowList` | Stable    | Closed union; rejected by types.   |
+| Overflow outputs | `overflowRenderer`; `onOverflowChange` | An indicator for the collapsed items; a callback with the collapsed set. | Optional                                  | none          | caller                   | Stable    | —                                  |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                               | Basis                           | Draft review state                                 |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The visible list container carries the `overflow-list` target and renders the caller-supplied items selected by current width and count limits.   | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR2 | When the current overflow calculation collapses items and a renderer is supplied, its returned indicator appears at the configured collapse edge. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR3 | The hidden inert measurement copy carries no public theming target and is not consumer-facing anatomy.                                            | Current source and tests        | Verified current behavior; no target change        |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                                                                   |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| FR1 | OverflowList renders a hidden measurement copy of every item, plus the indicator rendered for all items, and a visible container carrying the `overflow-list` target. The copy is `aria-hidden`, `inert`, invisible, zero-height, and takes no pointer input, so it is neither read, focused, nor clicked.                                                                                                                                       | Current source and tests                                                |
+| FR2 | Once measured, the visible container shows the items that fit the measured width (its own, or its parent's with `observeParent`), at least `minVisibleItems` and at most `maxVisibleItems`, with the floor winning over a smaller cap. Before measurement, including a server render, it shows every item and no indicator. With `collapseFrom="end"` it keeps the leading items; with `start`, the trailing ones. Items render in caller order. | Current source and tests                                                |
+| FR3 | When items collapse, the indicator `overflowRenderer` returns for the collapsed items renders after the visible items with `end`, or before them with `start`; without a renderer, collapsed items are dropped and no indicator renders.                                                                                                                                                                                                         | Current source and tests                                                |
+| FR4 | One row is a non-wrapping flex line that clips overflow. `maxRows` above 1 wraps items and limits the container's height to that many measured rows plus gaps. `gap` sets the spacing between items. With `observeParent` and items collapsed, the container fills its parent's width.                                                                                                                                                           | Current source and tests                                                |
+| FR5 | `onOverflowChange` receives the collapsed items, by original index, once the current content is measured: once on mount while overflowing, then only when the collapsed set's membership or order changes, including back to empty; never while nothing has overflowed, and never after unmount.                                                                                                                                                 | Current source and tests                                                |
+| FR6 | `ref`, DOM, data, ARIA, and event props, `xstyle`, `className`, and `style` reach or compose on the visible container.                                                                                                                                                                                                                                                                                                                           | Current source and tests; `architecture:public-component-api` INV5–INV8 |
 
 ### Allowed variation
 
-- Item and overflow-indicator content may vary without becoming
-  OverflowList-owned theming targets.
+- **AV1 — Content.** Item and indicator content may vary without becoming
+  OverflowList-owned targets.
 
 ### Representative states
 
-- With no configured count cap, a sufficiently wide list shows every item and
-  no indicator. Width pressure or `maxVisibleItems` may instead collapse a
-  subset; the remaining items and optional indicator stay inside the same
-  targeted list container.
+| State              | Required invariant                                                    | Allowed variation  |
+| ------------------ | --------------------------------------------------------------------- | ------------------ |
+| All fit            | Every item, no indicator, no callback.                                | Gap.               |
+| Collapse end       | Leading items; indicator after them.                                  | Indicator content. |
+| Collapse start     | Trailing items; indicator before them.                                | Indicator content. |
+| Capped             | Once measured, at most `maxVisibleItems`, unless the floor is larger. | —                  |
+| Before measurement | Every item; no indicator.                                             | Server render.     |
+| Multi-row          | Wrapped items within `maxRows` rows.                                  | Rows.              |
 
 ### Transformation and precedence order
 
-- No new measurement, collapse, or rendering order is introduced.
+- **ORD1 — Visible count.** Before measurement, every item; once measured, the
+  measured fit → at most `maxVisibleItems` → at least `minVisibleItems`.
+- **ORD2 — Reporting.** Measure the current content first; report only a
+  changed collapsed set.
 
 ### Performance and resources
 
-- This draft records the existing hidden measurement structure but introduces no
-  new measurement or observer requirement.
+- **PR1 — Measurement.** OverflowList observes the measured box's size, renders
+  every item in the hidden copy and the visible ones again in the list, and
+  reports collapsed sets after measurement, before the frame paints.
 
 ## Accessibility contract
 
-This draft does not change or extend the existing hidden measurement container,
-DOM forwarding, or caller-content accessibility behavior.
+- **AR1 — One readable copy.** Only the visible container's items reach
+  assistive technology and keyboard focus; the measurement copy is hidden and
+  inert (FR1).
+- **AR2 — Caller-owned access to collapsed items.** Collapsed items leave the
+  visible list; the caller's indicator is the way to reach them, and its
+  semantics are the caller's.
 
 ## Design relationships
 
-| Anatomy or state   | Design requirement                                                                      | Representation authority       | Hierarchy role    | Component contract |
-| ------------------ | --------------------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
-| List               | Presents the current visible list container.                                            | Current source and public docs | Supporting        | FR1                |
-| Items              | Present caller-supplied content selected for visible display by width and count limits. | Caller-supplied content        | Context-dependent | FR1                |
-| Overflow indicator | Presents caller-rendered access to or a count of collapsed items.                       | Caller-supplied content        | Context-dependent | FR2                |
+| Anatomy or state   | Design requirement                                                  | Representation authority | Hierarchy role    | Component contract |
+| ------------------ | ------------------------------------------------------------------- | ------------------------ | ----------------- | ------------------ |
+| List               | The visible list container.                                         | Current source and docs  | Supporting        | FR1, FR4           |
+| Items              | Caller items selected for display by width, rows, and count limits. | Caller-supplied content  | Context-dependent | FR2                |
+| Overflow indicator | Caller-rendered access to, or a count of, collapsed items.          | Caller-supplied content  | Context-dependent | FR3                |
 
-The hidden measurement copy is implementation plumbing rather than
-consumer-facing anatomy.
+The hidden measurement copy is implementation structure, not consumer anatomy.
 
 ### Theming anatomy
 
@@ -130,21 +171,27 @@ consumer-facing anatomy.
 
 ## Family and system relationships
 
-- `architecture:component-theming-surface` owns anatomy qualification and factual
-  `none` dispositions for caller-owned content.
+- `architecture:component-theming-surface` owns anatomy qualification and the
+  `none` dispositions for caller content.
+- `architecture:public-component-api` owns caller-input routing; FR6 applies
+  it.
 
 ## Verification map
 
-| Contract            | Verification                                          | Representative states                               | Mutation or failure expectation                                                                               | Audit section                |
-| ------------------- | ----------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1, FR2            | `OverflowList.test.tsx` fit, cap, and overflow suites | All items visible; count-capped; start/end overflow | Removing visible items or changing capped/width-driven indicator placement fails existing content assertions. | `audit:OverflowList/anatomy` |
-| FR1, FR3            | `OverflowList.test.tsx` rendering-contract suites     | Visible and hidden measurement containers           | Moving the target from the visible list or exposing measurement content fails assertions.                     | `audit:OverflowList/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                         | Canonical anatomy and current target                | Missing, extra, prefixed, or stale mappings fail repository validation.                                       | `audit:OverflowList/theming` |
+| Contract            | Verification                                                                                                                                                                                                                           | Representative states                                                                                                                             | Mutation or failure expectation                                                                                                                              | Audit section                 |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
+| FR1, AR1            | `OverflowList.test.tsx` measurement-container and rendering-contract tests                                                                                                                                                             | Hidden copy; indicator measured against all items; visible class                                                                                  | A measurement copy that is not `aria-hidden` and `inert`, an indicator measured against fewer items, or a target off the visible container fails.            | `audit:OverflowList/theming`  |
+| FR2, ORD1           | `OverflowList.test.tsx` fit, overflow, `minVisibleItems`, and cap tests; `useOverflow.test.ts` (including `observeParent`); `computeOverflow.test.ts`; stable visual baselines `core-overflowlist--default` (neutral and probe themes) | All fit; end and start; floor; cap; floor over cap                                                                                                | Wrong visible items, too few under a floor, too many under a cap, or a cap beating the floor fails; a changed default row comes back changed for review.     | `audit:OverflowList/behavior` |
+| FR3                 | `OverflowList.test.tsx` indicator-placement and no-renderer tests                                                                                                                                                                      | End; start; no renderer                                                                                                                           | An indicator on the wrong side, or one rendered without a renderer, fails.                                                                                   | `audit:OverflowList/anatomy`  |
+| FR4                 | `OverflowList.test.tsx` gap and `maxRows` tests                                                                                                                                                                                        | Gap change; `maxRows` 2 and 1                                                                                                                     | No class change for a new gap or for wrapping, or wrapping at `maxRows={1}`, fails. Gap: the row height limit and the `observeParent` fill have no check.    | `audit:OverflowList/layout`   |
+| FR5, ORD2           | `OverflowList.test.tsx` `onOverflowChange` suite                                                                                                                                                                                       | Silent fit; mount; original indices; back to empty; unchanged; reorder; content change; count change; callback swap; state update; unmount; start | A callback that fires without overflow, repeats an unchanged set, misses a change, reports unmeasured content, loops on state, or fires after unmount fails. | `audit:OverflowList/behavior` |
+| FR6                 | `OverflowList.test.tsx` ref and passthrough tests                                                                                                                                                                                      | Ref; DOM props                                                                                                                                    | A ref on another element or a dropped DOM prop fails. Gap: no test covers `className`, `style`, or the `xstyle` merge order.                                 | `audit:OverflowList/api`      |
+| AR2, PR1            | Source review                                                                                                                                                                                                                          | Collapsed items                                                                                                                                   | Gap: no automated check covers keyboard reach to collapsed items or the observer lifecycle.                                                                  | `audit:OverflowList/a11y`     |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                          | Canonical anatomy and current target                                                                                                              | Missing, extra, or stale mappings fail repository validation.                                                                                                | `audit:OverflowList/theming`  |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design
-or API decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions