An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): OverflowList records its shipped contract as current (#9111)
Cindy Zhang1010d4c6149f
diff --git a/packages/core/src/OverflowList/OverflowList.spec.md b/packages/core/src/OverflowList/OverflowList.spec.mdindex d6a99ccce9..d67f8f93f1 100644--- a/packages/core/src/OverflowList/OverflowList.spec.md+++ b/packages/core/src/OverflowList/OverflowList.spec.md@@ -1,44 +1,65 @@---schema_version: 3-template_version: 3+template_version: 7kind: componentid: component:OverflowList-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-31owners: [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: noneConsumer 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