Skip to content

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.md
index 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: 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