Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(List): one edge prop for padded, flush, outset, and bleed rows (#7592)

Kenton Quatman7c206edbb914
diff --git a/.changeset/list-edge-codemod.md b/.changeset/list-edge-codemod.md
new file mode 100644
index 0000000000..0dcb5f8ed6
--- /dev/null
+++ b/.changeset/list-edge-codemod.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] `astryx upgrade` renames a static `edgeCompensation="inline"` on `List` to `edge="outset"`, and drops `edgeCompensation` beside an `edge` that is a fixed string. It keeps `edgeCompensation` with a `TODO(astryx upgrade)` comment where it can't prove the result: where `edge` is computed (it may be undefined, and then `edgeCompensation` still applies), on a dynamic `edgeCompensation` value, and where the `List` also spreads props, which may set `edge`. The deprecated prop keeps working there.
+
+@kentonquatman
diff --git a/.changeset/list-edge.md b/.changeset/list-edge.md
new file mode 100644
index 0000000000..9629a014bc
--- /dev/null
+++ b/.changeset/list-edge.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `List`: add `edge` to choose where each row's text, dividers, and hover and selection backgrounds sit. `padded` (default) keeps today's look. `flush` drops the rows' side padding, so text and dividers start on the same line as the list header and a heading above, with no container needed. `outset` keeps backgrounds' room around the text while reaching into the padding of a Card, Section, or Dialog, so text lands on the heading's line. `bleed` reaches rows to the container's edges with square corners, like Table rows in a Card. `edgeCompensation="inline"` is deprecated in favor of `edge="outset"` and keeps working; its rows' outer room is no longer cut off by the list's swipe clip. Run `astryx upgrade` to rename it.
+
+@kentonquatman
diff --git a/apps/storybook/stories/List.stories.tsx b/apps/storybook/stories/List.stories.tsx
index cc7ebbbffc..881f53db54 100644
--- a/apps/storybook/stories/List.stories.tsx
+++ b/apps/storybook/stories/List.stories.tsx
@@ -3,18 +3,21 @@
/**
* @file List.stories.tsx
* @input List, ListItem, and Storybook args
- * @output List examples, including bounded inline edge compensation
+ * @output List examples, including the four row edge treatments
* @position Storybook demonstrations for List consumers
*/
-import {useState, type CSSProperties} from 'react';
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
import type {Meta, StoryObj} from '@storybook/react';
import {List, ListItem} from '@astryxdesign/core/List';
import {Avatar} from '@astryxdesign/core/Avatar';
import {Badge} from '@astryxdesign/core/Badge';
+import {Card} from '@astryxdesign/core/Card';
import {Icon} from '@astryxdesign/core/Icon';
import {Switch} from '@astryxdesign/core/Switch';
-import {Text} from '@astryxdesign/core/Text';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
import {
Cog6ToothIcon,
BellIcon,
@@ -39,12 +42,12 @@ const meta: Meta<typeof List> = {
control: 'boolean',
description: 'Whether to show dividers between items',
},
- edgeCompensation: {
+ edge: {
control: 'select',
- options: [undefined, 'inline'],
+ options: ['padded', 'flush', 'outset', 'bleed'],
description:
- "Cancel each item's inset up to the padded container edge so row " +
- 'text moves toward sibling content',
+ "Where row text, dividers, and backgrounds sit relative to the list's " +
+ "edges and the container's padding",
},
listStyle: {
control: 'select',
@@ -57,6 +60,14 @@ const meta: Meta<typeof List> = {
export default meta;
type Story = StoryObj<typeof List>;
+const edgeStoryStyles = stylex.create({
+ grid: {
+ display: 'grid',
+ gridTemplateColumns: 'repeat(auto-fill, minmax(260px, 1fr))',
+ gap: 24,
+ },
+});
+
export const Basic: Story = {
render: args => (
<List {...args}>
@@ -126,38 +137,17 @@ export const Spacious: Story = {
),
};
-const inlineEdgeCompensationContainerStyle: CSSProperties & {
- '--container-padding-inline-start': string;
- '--container-padding-inline-end': string;
-} = {
- paddingInline: 16,
- '--container-padding-inline-start': '16px',
- '--container-padding-inline-end': '16px',
-};
-
-export const InlineEdgeCompensation: Story = {
- args: {edgeCompensation: 'inline'},
+export const Flush: Story = {
+ args: {edge: 'flush', hasDividers: true},
render: args => (
- <div style={inlineEdgeCompensationContainerStyle}>
+ <div>
<Text type="label" size="lg">
Order items
</Text>
<List {...args}>
- <ListItem
- label="Solstice Mug"
- description="Ceramic, 12 oz"
- onClick={() => {}}
- />
- <ListItem
- label="Meridian Notebook"
- description="Dot grid, A5"
- onClick={() => {}}
- />
- <ListItem
- label="Field Pen"
- description="0.5 mm, black ink"
- onClick={() => {}}
- />
+ <ListItem label="Solstice Mug" description="Ceramic, 12 oz" />
+ <ListItem label="Meridian Notebook" description="Dot grid, A5" />
+ <ListItem label="Field Pen" description="0.5 mm, black ink" />
</List>
</div>
),
@@ -165,13 +155,58 @@ export const InlineEdgeCompensation: Story = {
docs: {
description: {
story:
- 'edgeCompensation="inline" cancels the smaller of each item\'s inline inset ' +
- 'and its container padding on each edge. The 16px container padding ' +
- 'here is sufficient to align row text with the heading; smaller ' +
- 'padding leaves some inset uncompensated. The cancelling margin reads the ' +
- 'same variable the items derive their inline padding from, so it ' +
- 'tracks density and theme padding overrides automatically while ' +
- 'zero-padding containers stay unchanged.',
+ 'edge="flush" drops the rows\' side padding, so row text starts on ' +
+ 'the same line as the heading and the ends of the dividers, with no ' +
+ 'container needed. Switch edge to compare.',
+ },
+ },
+ },
+};
+
+const EDGES = ['padded', 'flush', 'outset', 'bleed'] as const;
+
+/**
+ * The four edge treatments inside a Card, for a static list with dividers
+ * and an interactive list with a selected row.
+ */
+export const EdgeInCard: Story = {
+ render: args => (
+ <div {...stylex.props(edgeStoryStyles.grid)}>
+ {EDGES.map(edge => (
+ <Card key={edge} data-edge={edge}>
+ <VStack gap={3}>
+ <Heading level={3}>{`edge="${edge}"`}</Heading>
+ <List {...args} edge={edge} hasDividers>
+ <ListItem label="Ada Lovelace" description="Engineer" />
+ <ListItem label="Grace Hopper" description="Admiral" />
+ </List>
+ <List {...args} edge={edge}>
+ <ListItem
+ label="Inbox"
+ onClick={() => {}}
+ startContent={<Icon icon={InboxIcon} />}
+ />
+ <ListItem
+ label="Sent"
+ isSelected
+ onClick={() => {}}
+ startContent={<Icon icon={PaperAirplaneIcon} />}
+ />
+ </List>
+ </VStack>
+ </Card>
+ ))}
+ </div>
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ "padded keeps text inside each row's padding. flush puts text, " +
+ "dividers, and backgrounds on the heading's line. outset puts text " +
+ "on the heading's line and reaches backgrounds into the card's " +
+ "padding by the rows' own padding. bleed reaches rows to the card's " +
+ "edges, like Table rows, with text on the card's padding line.",
},
},
},
diff --git a/docs/architecture/container-padding.md b/docs/architecture/container-padding.md
index 582b583453..bf99eacd45 100644
--- a/docs/architecture/container-padding.md
+++ b/docs/architecture/container-padding.md
@@ -96,20 +96,21 @@ The protocol has four layers:
### Current and admitted publishers and consumers
-| Role | Participants | Contract responsibility |
-| -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Container publisher | Card, Section, Dialog, BottomSheet, ScrollableArea | Resolve component padding or publish explicit content-box padding as logical-edge and Layout inset variables |
-| Region publisher | LayoutHeader, LayoutContent, LayoutFooter, LayoutPanel | Publish baseline or explicit-padding geometry; automatic outer-edge publication has the conformance gap below |
-| Bleed consumer | Section, ScrollableArea, Layout, Divider, Table | Subtract inherited inset on the edges each component is designed to escape; ScrollableArea does so only with `isFullBleed` |
-| Edge-compensation consumer | TabList; List/ListItem rows (admitted) | Move visible content toward the container content line while retaining component-owned interaction padding; exact alignment depends on each component's bounded geometry |
-| Alignment consumer | Toolbar and edge-compensating child components | Read the current inline inset to align visible content rather than stacked touch-target padding |
-| Boundary owner | Layer surfaces and dialog-based overlay roots | Apply `overlayPaddingReset` before descendants read inherited page geometry |
+| Role | Participants | Contract responsibility |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Container publisher | Card, Section, Dialog, BottomSheet, ScrollableArea | Resolve component padding or publish explicit content-box padding as logical-edge and Layout inset variables |
+| Region publisher | LayoutHeader, LayoutContent, LayoutFooter, LayoutPanel | Publish baseline or explicit-padding geometry; automatic outer-edge publication has the conformance gap below |
+| Bleed consumer | Section, ScrollableArea, Layout, Divider, Table, TabList, List | Subtract inherited inset on the edges each component is designed to escape; ScrollableArea does so only with `isFullBleed`, TabList and List only with `edge="bleed"` |
+| Edge-compensation consumer | List/ListItem rows with `edge="outset"` | Move visible content toward the container content line while retaining component-owned interaction padding; exact alignment depends on each component's bounded geometry |
+| Alignment consumer | Toolbar and edge-compensating child components | Read the current inline inset to align visible content rather than stacked touch-target padding |
+| Boundary owner | Layer surfaces and dialog-based overlay roots | Apply `overlayPaddingReset` before descendants read inherited page geometry |
The participant list is the shared container system, not a Layout-owned family:
Section and ScrollableArea publish content inset, Section and opt-in full-bleed
ScrollableArea instances consume inherited inset, Layout redistributes inset,
-Table and Divider consume bleed geometry, TabList consumes current edge-
-compensation geometry, List is the admitted next consumer, and Toolbar consumes
+Table and Divider consume bleed geometry, TabList consumes bleed geometry with
+`edge="bleed"`, List consumes edge-compensation geometry with
+`edge="outset"` and bleed geometry with `edge="bleed"`, and Toolbar consumes
alignment geometry. Participation here does not by itself make any of those
components a member of `family:layout-regions`.
@@ -132,8 +133,8 @@ Edge compensation is a two-sided geometry contract, not a token contract:
2. **Component side.** A participating component owns the inset retained around
its content and derives that inset from the same density- and theme-aware
source as its normal padding. The component consumes only the logical edges
- its public value selects and never requires the container to understand its
- component tokens.
+ its contract applies its public value to and never requires the container to
+ understand its component tokens.
For a new self-compensating row or surface, the default eligible host state is
visually neutral: it contributes no background, border, clipping, or interactive
@@ -151,44 +152,66 @@ does not read inherited container padding or give those children a
caller-controlled compensation API. This revision leaves that mechanism
unchanged.
-A component with a documented anatomy container that applies edge compensation
-MAY expose an anatomy-targeted `<anatomy>EdgeCompensation` prop to modify that
-container's compensation. The prop MUST use the shared axis values `inline`,
-`block`, or `all`, preserve the component's documented omission behavior, and
-keep the compensation amount component-owned. `inline` means the named
-container's logical inline edge, `block` means both block edges, and `all`
-combines them. These values do not extend the self-compensation vocabulary below.
-`endContentEdgeCompensation` is DialogHeader's projection of this rule.
-
-`edgeCompensation` names the caller's intent: reduce component-owned inset at
-selected ancestor container content edges while keeping the component's own paint
-or interaction inset. The component contract states when that bounded adjustment
-reaches the host content line. Omission means no compensation. The shared logical
-value vocabulary is:
-
-- `start`: compensate only the logical inline-start edge;
-- `end`: compensate only the logical inline-end edge; and
-- `inline`: compensate both logical inline edges independently.
-
-A component exposes only the values its current contract and evidence support.
-This mode does not promise that the component box reaches the container's outer
-edge. Reserve `isFullBleed` for components such as ScrollableArea whose visible
-surface consumes the full inherited container inset. New self-compensation APIs
-use `edgeCompensation` rather than exposing margin values or inventing a second
-name.
+`edge` is the shared public vocabulary for edge treatment. Its values name where
+a participating component's paint and content sit relative to the host's content
+edges, and each states its bounded geometry:
+
+- `padded`: the component keeps its own inset and reads no host padding. It is
+ a self-compensating component's default, and omission means it.
+- `flush`: the component removes its own inset, so content and paint share the
+ component's edges. It reads no host padding.
+- `outset`: paint reaches past the host content line by the smaller of the
+ component's own inset and the host inset, and the component keeps its own
+ inset inside that paint. Content reaches the host content line when the host
+ inset is at least the component's inset.
+- `bleed`: paint reaches the host's padding edge, consuming the full inherited
+ inset. Content sits on the host content line, or at the component's own inset
+ from its edge when the host inset is smaller.
+
+A component applies a value to the logical edges its contract names, resolves
+each edge independently, and exposes only the values its current contract and
+evidence support. Outside an eligible host, `outset` and `bleed` read zero host
+inset and place content as `padded` does. The amount stays component-owned
+(INV9). This vocabulary does not promise that the component box reaches the
+container's outer edge except under `bleed`, and new APIs use it rather than
+exposing margin values or another name.
+
+`isFullBleed` moves a component's whole visible surface to the host's padding
+edge with no content line of its own to keep: Divider's line, and ScrollableArea's
+viewport, whose content padding is its own prop. `bleed` makes the same promise
+for paint and adds that content stays on the host content line. A new full-bleed
+projection that keeps a content line uses `edge="bleed"`. TabList's
+`isFullBleed` behaves as `bleed`, so `component:TabList` spells that mode
+`edge="bleed"` and keeps `isFullBleed` as its deprecated alias.
+`edgeCompensation` is the released name of `outset`: List's
+`edgeCompensation="inline"` is a deprecated alias of `edge="outset"` through its
+compatibility window.
+
+A component with a documented anatomy container that applies edge treatment MAY
+expose an anatomy-targeted `<anatomy>Edge` prop with the same values, applied to
+that container's documented edges. It keeps the amount component-owned and the
+component's documented omission behavior. DialogHeader's and DrawerHeader's
+released `endContentEdgeCompensation` props are outside this form: their
+`inline`, `block`, and `all` values choose the axes of the end slot's
+compensation rather than a treatment. Both stay supported as released. How
+those axis values map onto `endContentEdge` treatment values is an open
+question owned by `module:Dialog/DialogHeader` and `component:Drawer`; each
+deprecates its old prop through its own compatibility window once that mapping
+is decided.
### Edge-compensation ledger
-| Participant | Source requirement | Canonical owner | Why it belongs | Done criteria | Status |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| Container and region publishers | The host owns the actual padding available at each logical edge | `architecture:container-padding` | A consumer cannot compensate safely without a per-edge upper bound from the host | Eligible states publish values matching applied padding, nesting, and overlay reset; missing values resolve to zero; known mismatch states remain excluded | current where conformant |
-| TabList / Tab | The strip moves its first and last visible tab content toward the host lines while retaining tab interaction padding, focus-ring room, overflow controls, its divider rail, and its selection indicator | `component:TabList` | The shipped behavior is edge compensation despite its current name | Preserve bounded content movement, full host-inset consumption, divider span, overflow, clipping, scroll controls, indicator geometry, logical direction, compatibility, and defaults | current behavior; rename deferred |
-| List / ListItem, using Item inset | An optional List header is not horizontally inset, while every row keeps Item's density- and theme-aware inline padding | `component:List` | The caller knows whether the List sits in a neutral container beside content that should share its logical content line | Default unchanged; every row respects its own inset and the available host padding; header and row-local paint stay in place; required geometry evidence passes | accepted; implementation pending |
-| Button | An uncontained ghost Button may need its icon or label aligned while retaining its interaction inset | No current component projection | Its transparent interaction padding can create the same alignment need | Exclude filled and bordered presentations; prove composition, focus/hover paint, logical direction, and unchanged defaults; obtain owner approval | candidate only |
-
-`component:List` owns the only new API projection admitted by this revision.
-`component:TabList` owns its existing behavior and the separately scoped public
-rename and deprecation path. Button remains a candidate and cannot authorize
+| Participant | Source requirement | Canonical owner | Why it belongs | Done criteria | Status |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Container and region publishers | The host owns the actual padding available at each logical edge | `architecture:container-padding` | A consumer cannot compensate safely without a per-edge upper bound from the host | Eligible states publish values matching applied padding, nesting, and overlay reset; missing values resolve to zero; known mismatch states remain excluded | current where conformant |
+| TabList / Tab | The strip moves its first and last visible tab content toward the host lines while retaining tab interaction padding, focus-ring room, overflow controls, its divider rail, and its selection indicator | `component:TabList` | The shipped behavior is `bleed` under the released name `isFullBleed` | Preserve bounded content movement, full host-inset consumption, divider span, overflow, clipping, scroll controls, indicator geometry, logical direction, compatibility, and defaults | current behavior; `edge="bleed"` canonical, alias pending |
+| List / ListItem, using Item inset | An optional List header is not horizontally inset, while every row keeps Item's density- and theme-aware inline padding | `component:List` | The caller knows whether the List sits in a neutral container beside content that should share its logical content line, and whether its rows need room around their paint | `padded` unchanged by default; `outset` respects each row's own inset and the available host padding; `bleed` reaches the host's padding edge; header stays in place; required geometry evidence passes | current through `edge`; `edgeCompensation` deprecated |
+| Button | An uncontained ghost Button may need its icon or label aligned while retaining its interaction inset | No current component projection | Its transparent interaction padding can create the same alignment need | Exclude filled and bordered presentations; prove composition, focus/hover paint, logical direction, and unchanged defaults; obtain owner approval | candidate only |
+
+`component:List` owns the only new API projection admitted by this revision,
+its `edge` prop.
+`component:TabList` owns its existing behavior and its `edge="bleed"` rename and
+deprecation path. Button remains a candidate and cannot authorize
implementation; a future projection requires a component contract, evidence, and
the named owner's explicit approval.
@@ -241,14 +264,17 @@ without dropping the active theme's Section default.
logical edge. A participating component owns the inset retained around its
content and derives compensation from the same component-owned source as its
applied padding. Neither side names or duplicates the other's theme tokens.
-- **INV10 — The public vocabulary names intent.** `edgeCompensation` means reduce
- component-owned inset at selected logical host content edges while preserving
- component-owned interaction or paint inset. Each component contract states the
- bounded geometry and when content reaches the host line. Omission means no
- compensation. `start` selects logical inline-start, `end` selects logical
- inline-end, and `inline` selects both independently. A component exposes only
- the values its current component contract admits. `isFullBleed` remains for a
- surface whose public promise is to consume the full available host inset.
+- **INV10 — The public vocabulary names intent.** `edge` names a component's
+ edge treatment with the values `padded`, `flush`, `outset`, and `bleed`
+ defined above. Each component contract states the edges a value applies to,
+ its bounded geometry, and when content reaches the host line, and exposes only
+ the values it admits. Omission means `padded`, except that an anatomy
+ container keeps its documented omission behavior. `isFullBleed` remains for a
+ surface whose public promise is to consume the full host inset without a
+ content line of its own. `edgeCompensation` survives as List's deprecated
+ alias of `edge="outset"` and in the released `endContentEdgeCompensation` of
+ DialogHeader and DrawerHeader until their `endContentEdge` mapping is
+ decided.
- **INV11 — Participation and host eligibility are explicit.** A new
self-compensating row or surface requires a component contract and defaults to
visually neutral host states. A component-specific contract may admit a bounded
@@ -285,21 +311,23 @@ evidence, not part of this documentation stack.
contract relies on that role.
- An edge-compensation host publishes actual available inset per logical edge;
it does not publish a token choice or infer a child's retained padding.
-- A component exposing edge compensation uses `edgeCompensation`, declares only
- the logical values it currently supports, and keeps its effective inset and
- compensation on one derived source. Adding another value requires per-edge,
- asymmetric, zero-padding, RTL, and theme-override evidence.
-- Renaming an existing compensation API preserves the old name as a deprecated
- alias through its approved compatibility window, moves maintained examples to
- the canonical name, and tests both paths before removal.
+- A component exposing an edge treatment uses `edge`, or `<anatomy>Edge` for an
+ anatomy container, declares only the values it currently supports, and keeps
+ its effective inset and compensation on one derived source. Adding another
+ value requires per-edge, asymmetric, zero-padding, RTL, and theme-override
+ evidence.
+- Moving an existing compensation or full-bleed API to `edge` preserves the old
+ name as a deprecated alias through its approved compatibility window, moves
+ maintained examples to `edge`, and tests both paths before removal.
- Changing `container()` or the public-to-private padding lowering reviews Card,
Section, Dialog, BottomSheet, Layout regions, and overlay behavior together.
- Changing overlay hosting or adding an overlay root verifies that stale page
geometry stops at the new boundary without suppressing public theme values.
- A component other than BottomSheet that wants a new public full-bleed mode or
padding prop follows its component/family API review; this architecture does
- not authorize that API. `component:List` owns List's first new projection, and
- `component:TabList` owns its existing behavior and migration. This record does
+ not authorize that API. `component:List` owns List's `edge` projection,
+ including its full-bleed `bleed` value, and `component:TabList` owns its
+ existing behavior and migration. This record does
not authorize another component projection.
## Owning code
@@ -312,10 +340,10 @@ evidence, not part of this documentation stack.
alignment adjustment for marked edge content.
- Card, Section, Dialog, BottomSheet, ScrollableArea, and Layout region
implementations — publish their current geometry.
-- Section, ScrollableArea, Layout, Divider, Table, TabList, and Toolbar
+- Section, ScrollableArea, Layout, Divider, Table, TabList, List, and Toolbar
implementations — consume the current geometry for bleed or alignment.
-- TabList currently lowers its component-owned projection; List owns its admitted
- next projection. `component:TabList` and `component:List` define their local
+- TabList currently lowers its component-owned projection; List lowers its
+ `edge` projection. `component:TabList` and `component:List` define their local
padding, row/strip geometry, and private propagation.
- Overlay roots — apply the reset at the visual boundary.
@@ -326,11 +354,12 @@ evidence, not part of this documentation stack.
token mechanism.
- `spec:AST-025/DEC-2` and `component:ScrollableArea/FR5` establish the
contrasting full-bleed contract: ScrollableArea consumes the full inherited
- inset only through explicit `isFullBleed`. List cancels at most its own Item
- inset and may stop inside the container padding; TabList consumes the full host
- inset but restores `max(host inset - edge-tab padding, 0)` inside its strip, so
- tab content may likewise stop short of the host line. Both are edge compensation
- rather than content-level full bleed.
+ inset only through explicit `isFullBleed`, with no content line of its own to
+ keep. List's `edge="outset"` cancels at most its own Item inset and may stop
+ inside the container padding. List's `edge="bleed"` and TabList's
+ `isFullBleed` consume the full host inset with their paint and pad back in by
+ `max(host inset - own inset, 0)`, so their content lands on the host line, or
+ further in when the host inset is smaller than their own.
## Verification
@@ -345,9 +374,10 @@ evidence, not part of this documentation stack.
| INV9, INV10 | `List.test.tsx` plus real-browser geometry evidence | The header moves; a row reads the wrong logical edge, diverges from themed/density padding, applies the wrong bounded movement, or loses paint inset |
| INV10, INV11 | `TabList.test.tsx` plus real-browser overflow, divider, and indicator evidence | Full host-inset consumption, bounded content movement, divider span, interaction, focus, overflow, scroll controls, or indicator geometry regresses |
-The List evidence must cover its neutral root with the optional header,
-interactive and static rows, all densities, a theme `item.paddingInline`
-override, LTR and RTL, host inset smaller than/equal to/larger than Item inset,
-uniform/asymmetric/zero/missing container padding, and hover/selection paint
-geometry. TabList uses its separately scoped evidence; Buttons, menu rows, and
+The List evidence must cover each `edge` value in its neutral root and in each
+bounded host List admits (Card, Section, Dialog, BottomSheet), with the optional
+header, interactive and static rows, all densities, a theme
+`item.paddingInline` override, LTR and RTL, host inset smaller than/equal
+to/larger than Item inset, uniform/asymmetric/zero/missing container padding,
+hover/selection paint geometry, and a swiped row under `outset` and `bleed`. TabList uses its separately scoped evidence; Buttons, menu rows, and
toolbar items are not admitted or verified by List's evidence.
diff --git a/packages/cli/assets/codemods/transforms/next/__tests__/migrate-list-edge-compensation-to-edge.test.mjs b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-list-edge-compensation-to-edge.test.mjs
new file mode 100644
index 0000000000..735212e7a6
--- /dev/null
+++ b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-list-edge-compensation-to-edge.test.mjs
@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import transform from '../migrate-list-edge-compensation-to-edge.mjs';
+
+async function applyTransform(source) {
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ return transform({source, path: 'test.tsx'}, api) ?? source;
+}
+
+describe('migrate-list-edge-compensation-to-edge', () => {
+ it("renames edgeCompensation='inline' to edge='outset'", async () => {
+ const output =
+ await applyTransform(`import {List, ListItem} from '@astryxdesign/core/List';
+const a = <List edgeCompensation="inline"><ListItem label="a" /></List>;
+const b = <List hasDividers edgeCompensation={'inline'} />;`);
+
+ expect(output).not.toContain('edgeCompensation');
+ expect(output.match(/edge='outset'/g)).toHaveLength(2);
+ expect(output).toContain('hasDividers');
+ });
+
+ it('follows aliases and the package root import', async () => {
+ const output =
+ await applyTransform(`import {List as Rows} from '@astryxdesign/core';
+const a = <Rows edgeCompensation="inline" />;`);
+
+ expect(output).toContain("<Rows edge='outset' />");
+ });
+
+ it('drops edgeCompensation beside an edge string, whatever its value', async () => {
+ const output =
+ await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edge="bleed" edgeCompensation="inline" />;
+const b = <List edge={'flush'} edgeCompensation={mode} />;
+const c = <List {...rest} edge="padded" edgeCompensation="inline" />;`);
+
+ // c: the spread comes before edge, so it cannot override it.
+ expect(output).toContain('edge="bleed"');
+ expect(output).toContain("edge={'flush'}");
+ expect(output).toContain('edge="padded"');
+ expect(output).not.toContain('edgeCompensation');
+ expect(output).not.toContain('TODO');
+ });
+
+ it('leaves a TODO where edge may be undefined at runtime', async () => {
+ const output =
+ await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edge={edge} edgeCompensation="inline" />;
+const b = <List edge="flush" {...rest} edgeCompensation="inline" />;
+const c = <List edge={props.edge} edgeCompensation={mode} />;`);
+
+ // a and c: a computed edge falls back to the old prop when undefined.
+ // b: the spread after edge may set it to undefined.
+ expect(output.match(/TODO\(astryx upgrade\)/g)).toHaveLength(3);
+ expect(output.match(/edgeCompensation=/g)).toHaveLength(3);
+ expect(output).toContain('edge={edge}');
+ expect(output).toContain('edge={props.edge}');
+ });
+
+ it('leaves a TODO on a dynamic value and keeps it working', async () => {
+ const output =
+ await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edgeCompensation={mode} />;
+const b = <List edgeCompensation={flag ? 'inline' : undefined} />;`);
+
+ expect(output.match(/TODO\(astryx upgrade\)/g)).toHaveLength(2);
+ expect(output).toContain('edgeCompensation={mode}');
+ expect(output).toContain("edgeCompensation={flag ? 'inline' : undefined}");
+ });
+
+ it('keeps edgeCompensation with a TODO when the List also spreads props', async () => {
+ const output =
+ await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List {...rest} edgeCompensation="inline" />;
+const b = <List edgeCompensation="inline" {...rest} />;
+const c = <List {...rest} edgeCompensation={mode} />;
+const d = <List {...props} />;
+const e = <List {...rest} edge="padded" />;`);
+
+ // a: an edge in the spread wins today, and a new edge would override
+ // it. b: the spread may override either prop. c: dynamic value and a
+ // spread, one TODO. d: no evidence of the old prop, so unchanged; its
+ // @deprecated type reports a typed use where the props are written.
+ // e: no old prop.
+ expect(output.match(/TODO\(astryx upgrade\)/g)).toHaveLength(3);
+ const code = output.replace(/\/\*[\s\S]*?\*\//g, '');
+ expect(code).not.toContain("edge='outset'");
+ expect(code.match(/edgeCompensation="inline"/g)).toHaveLength(2);
+ expect(output).toContain('edgeCompensation={mode}');
+ expect(output).toContain('const d = <List {...props} />;');
+ expect(output).toContain('edge="padded"');
+ });
+
+ it('leaves other components, other packages, and unrelated spreads alone', async () => {
+ const source = `import {List} from '@astryxdesign/core/List';
+import {TabList} from '@astryxdesign/core/TabList';
+import {List as Other} from 'some-other-package';
+const a = <TabList edgeCompensation="inline" {...props} />;
+const b = <Other edgeCompensation="inline" {...props} />;
+const c = <div {...props} />;`;
+ expect(await applyTransform(source)).toBe(source);
+ });
+
+ it('changes nothing on a second run', async () => {
+ const once =
+ await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edgeCompensation="inline" />;
+const b = <List edgeCompensation={mode} />;
+const c = <List {...props} edgeCompensation="inline" />;
+const d = <List edge="flush" edgeCompensation="inline" />;
+const e = <List edge={edge} edgeCompensation="inline" />;`);
+ const twice = await applyTransform(once);
+
+ expect(twice).toBe(once);
+ expect(twice.match(/TODO\(astryx upgrade\)/g)).toHaveLength(3);
+ });
+});
diff --git a/packages/cli/assets/codemods/transforms/next/index.mjs b/packages/cli/assets/codemods/transforms/next/index.mjs
index 2af3bdfcf0..011471c817 100644
--- a/packages/cli/assets/codemods/transforms/next/index.mjs
+++ b/packages/cli/assets/codemods/transforms/next/index.mjs
@@ -7,4 +7,14 @@
* this file into the resolved version folder.
*/
-export default [];
+import migrateListEdgeCompensationToEdge, {
+ meta as migrateListEdgeCompensationToEdgeMeta,
+} from './migrate-list-edge-compensation-to-edge.mjs';
+
+export default [
+ {
+ name: 'migrate-list-edge-compensation-to-edge',
+ transform: migrateListEdgeCompensationToEdge,
+ meta: migrateListEdgeCompensationToEdgeMeta,
+ },
+];
diff --git a/packages/cli/assets/codemods/transforms/next/migrate-list-edge-compensation-to-edge.mjs b/packages/cli/assets/codemods/transforms/next/migrate-list-edge-compensation-to-edge.mjs
new file mode 100644
index 0000000000..7ac60f32ef
--- /dev/null
+++ b/packages/cli/assets/codemods/transforms/next/migrate-list-edge-compensation-to-edge.mjs
@@ -0,0 +1,198 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate List edgeCompensation to edge
+ *
+ * `edgeCompensation="inline"` on an imported `List` becomes `edge="outset"`,
+ * the value it already resolves to. List resolves
+ * `edge ?? (edgeCompensation === 'inline' ? 'outset' : 'padded')`, so `edge`
+ * wins only when it has a value. The deprecated prop is removed beside an
+ * `edge` string that no later spread can override; beside a computed `edge`,
+ * which may be undefined at runtime, it gets a TODO instead.
+ *
+ * Built on the shared `transformProp` helper, so it does not follow
+ * variables, helpers, wrappers, or types. Where a List writes
+ * `edgeCompensation` but the codemod cannot prove the result, it keeps the
+ * old prop and leaves a TODO instead of guessing: on a dynamic value, and
+ * wherever the List also spreads props. A spread before the old prop may
+ * carry an `edge` that wins today and that a new `edge` would override; one
+ * after it may override either prop. A spread onto a List that never writes
+ * `edgeCompensation` is not evidence of use, so it stays unchanged
+ * (`spec:AST-040` FR1): the deprecated prop keeps working through it, and
+ * its `@deprecated` type reports a typed use where the props are written.
+ * Comments are the codemod's only report channel (`api.report` is a stub),
+ * and each is added once, so a second run changes nothing.
+ */
+
+import {transformProp} from '../../transform-prop.mjs';
+
+export const meta = {
+ title: 'Migrate List edgeCompensation to edge',
+ description:
+ 'Renames `edgeCompensation="inline"` to `edge="outset"` on List, and ' +
+ 'drops `edgeCompensation` beside an `edge` string. Keeps the old prop ' +
+ 'with a TODO where `edge` is computed or a later spread may override ' +
+ 'it, on a dynamic value, and where the List also spreads props; the ' +
+ 'deprecated prop still works there.',
+};
+
+const OLD_NAME = 'edgeCompensation';
+const NEW_NAME = 'edge';
+const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;
+
+const COMPONENT_PROPS = new Map([['List', new Set([OLD_NAME])]]);
+
+const DYNAMIC_COMMENT =
+ ' TODO(astryx upgrade): edgeCompensation is deprecated. Replace ' +
+ 'edgeCompensation="inline" with edge="outset" by hand; this value is ' +
+ 'computed. ';
+const BOTH_SET_COMMENT =
+ ' TODO(astryx upgrade): edgeCompensation is deprecated. edge is also set ' +
+ 'here, but it may be undefined, and then edgeCompensation still applies. ' +
+ 'Make edge default to "outset" where edgeCompensation is "inline", then ' +
+ 'remove edgeCompensation. ';
+const SPREAD_COMMENT =
+ ' TODO(astryx upgrade): edgeCompensation is deprecated, but this List ' +
+ 'also spreads props that may set edge, so it was left unchanged. Replace ' +
+ 'edgeCompensation="inline" with edge="outset" by hand, after checking ' +
+ 'which edge the spread passes. ';
+
+const TYPE_WRAPPERS = new Set([
+ 'TSAsExpression',
+ 'TSSatisfiesExpression',
+ 'TSTypeAssertion',
+ 'TSNonNullExpression',
+ 'TypeCastExpression',
+ 'ParenthesizedExpression',
+]);
+
+/** @param {any} node */
+function unwrap(node) {
+ let current = node;
+ while (current && TYPE_WRAPPERS.has(current.type)) {
+ current = current.expression;
+ }
+ return current;
+}
+
+/** @param {any} node */
+function isStringLiteral(node) {
+ const value = unwrap(node);
+ return (
+ value != null &&
+ (value.type === 'StringLiteral' || value.type === 'Literal') &&
+ typeof value.value === 'string'
+ );
+}
+
+/**
+ * The value of a JSX attribute: the string of `edge="flush"`, or the
+ * expression inside `edge={...}`.
+ * @param {any} attribute
+ */
+function attributeValue(attribute) {
+ return attribute.value?.type === 'JSXExpressionContainer'
+ ? attribute.value.expression
+ : attribute.value;
+}
+
+/** @param {any} node */
+function isInlineLiteral(node) {
+ const value = unwrap(node);
+ return (
+ value != null &&
+ (value.type === 'StringLiteral' || value.type === 'Literal') &&
+ value.value === 'inline'
+ );
+}
+
+/**
+ * Attach a comment to a node once, so re-running the codemod adds nothing.
+ * @param {any} j @param {any} node @param {string} text
+ */
+function addComment(j, node, text) {
+ node.comments ??= [];
+ if (node.comments.some((/** @type {any} */ c) => c.value === text)) {
+ return false;
+ }
+ node.comments.push(j.commentBlock(text, true, false));
+ return true;
+}
+
+/** @param {any} attributes */
+function firstSpread(attributes) {
+ return attributes.find(
+ (/** @type {any} */ attribute) => attribute.type === 'JSXSpreadAttribute',
+ );
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ transformProp(
+ root,
+ j,
+ {
+ matchesImport: source => CORE_IMPORT_RE.test(source),
+ components: COMPONENT_PROPS,
+ },
+ propPath => {
+ const opening = propPath.parent?.node;
+ const attributes = opening?.attributes ?? [];
+ const prop = propPath.node;
+ const edgeIndex = attributes.findIndex(
+ (/** @type {any} */ attribute) =>
+ attribute.type === 'JSXAttribute' &&
+ attribute.name?.name === NEW_NAME,
+ );
+ if (edgeIndex !== -1) {
+ // `edge` wins only when it has a value. A string that no later
+ // spread can override always does, so the old prop is inert and
+ // removing it changes nothing. A computed `edge` may be undefined,
+ // and then the old prop still decides.
+ const isProven =
+ isStringLiteral(attributeValue(attributes[edgeIndex])) &&
+ !attributes
+ .slice(edgeIndex + 1)
+ .some(
+ (/** @type {any} */ attribute) =>
+ attribute.type === 'JSXSpreadAttribute',
+ );
+ if (isProven) {
+ opening.attributes = attributes.filter(
+ (/** @type {any} */ attribute) => attribute !== prop,
+ );
+ hasChanges = true;
+ } else {
+ hasChanges = addComment(j, prop, BOTH_SET_COMMENT) || hasChanges;
+ }
+ return;
+ }
+ // With a spread on the element the rename cannot be proven: a spread
+ // before the old prop may carry an `edge` that wins today and that a
+ // new `edge` would override, and one after it may override either
+ // prop. The old prop keeps working, so it stays, with a TODO.
+ if (firstSpread(attributes)) {
+ hasChanges = addComment(j, prop, SPREAD_COMMENT) || hasChanges;
+ return;
+ }
+ if (isInlineLiteral(attributeValue(prop))) {
+ prop.name.name = NEW_NAME;
+ prop.value = j.stringLiteral('outset');
+ hasChanges = true;
+ } else {
+ hasChanges = addComment(j, prop, DYNAMIC_COMMENT) || hasChanges;
+ }
+ },
+ );
+
+ if (!hasChanges) return undefined;
+ return root.toSource({quote: 'single'});
+}
diff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjs
index e7c814f7a2..b5cf3702eb 100644
--- a/packages/core/src/Item/Item.doc.mjs
+++ b/packages/core/src/Item/Item.doc.mjs
@@ -49,7 +49,7 @@ export const docs = {
{
name: '--_item-inset-inline',
description:
- 'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to cancel the inset when edgeCompensation="inline". Set paddingInline on `item` in a theme and both stay in sync.',
+ 'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to place rows for its edge treatments (edge="flush", "outset", and "bleed"). Set paddingInline on `item` in a theme and both stay in sync.',
default: 'var(--spacing-2) (var(--spacing-3) for density="spacious")',
private: true,
},
diff --git a/packages/core/src/Item/Item.tsx b/packages/core/src/Item/Item.tsx
index 4fd6683629..40501799c6 100644
--- a/packages/core/src/Item/Item.tsx
+++ b/packages/core/src/Item/Item.tsx
@@ -342,7 +342,7 @@ const styles = stylex.create({
gap: spacingVars['--spacing-2'],
// The inline inset is published as --_item-inset-inline and the padding
// derives from it, so consumers that need to compensate for the inset
- // (List's edgeCompensation) read the var instead of mirroring the values.
+ // (List's edge treatments) read the var instead of mirroring the values.
// Themes that set paddingInline on `item` also feed this var via the
// derived var registry, keeping padding and compensation in sync.
'--_item-inset-inline': spacingVars['--spacing-2'],
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index 983953a3fa..81b2acaba5 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -41,11 +41,18 @@ export const docs = {
description: 'Show dividers between items.',
default: 'false',
},
+ {
+ name: 'edge',
+ type: "'padded' | 'flush' | 'outset' | 'bleed'",
+ description:
+ "Where each row's text, dividers, and hover and selection backgrounds sit, relative to the list's edges and the container around it. 'padded' keeps text inside each row's padding, so it starts a little in from a heading above the list and backgrounds have room around it. 'flush' drops the rows' side padding: text starts on the heading's line, and dividers and backgrounds stop at the row's content, with no room beyond it on either side. It works anywhere and suits static rows. 'outset' puts text on the heading's line and reaches dividers and backgrounds a little past it into the container's padding; it suits interactive rows in a container. 'bleed' puts text on the heading's line and reaches dividers and backgrounds to the container's edges with square corners, like Table rows in a Card. A row's first content is what lines up with the heading: its marker, icon, or avatar when it has one, otherwise its label. 'outset' and 'bleed' reach into the padding of the nearest container that shares its padding: a Card, Section, Dialog, or BottomSheet, or a transparent container such as a Layout region with explicit padding or a padded ScrollableArea. Place the List directly in that container's padding: padding that Stack, Center, or your own styles add in between is not counted. Drawers and the automatic padding of LayoutContent and LayoutPanel aren't supported yet. With no such container, including in a Popover, they look like 'padded'. In a container with less padding than the rows' own, text starts a little after the heading's line. A theme's inline padding on `item` replaces the row padding of every value, including the zero padding of flush.",
+ default: "'padded'",
+ },
{
name: 'edgeCompensation',
type: "'inline'",
description:
- "Compensate for item content inset on each inline edge by cancelling the smaller of each item's built-in horizontal inset and the container's published inline padding. The margin reads the same variable the items derive their inline padding from, so it tracks density and theme padding overrides automatically without pulling rows outside zero-padding or full-bleed surfaces. Use under a section heading to bring row text toward the heading text. Content aligns when container padding is at least the item inset; smaller padding leaves some inset uncompensated. Omit to leave item positions unchanged.",
+ "Deprecated: use edge=\"outset\", which this sets. Still works; edge wins when both are set. `astryx upgrade` rewrites existing usage.",
},
{
name: 'header',
@@ -89,6 +96,8 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
{ guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+ { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+ { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
{ guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
{ guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
{ guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -109,6 +118,8 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
{ guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+ { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+ { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
{ guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
{ guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
{ guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -132,6 +143,8 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
{ guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+ { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+ { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
{ guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
{ guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
{ guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
diff --git a/packages/core/src/List/List.spec.md b/packages/core/src/List/List.spec.md
index d66175de56..6aee7aea9f 100644
--- a/packages/core/src/List/List.spec.md
+++ b/packages/core/src/List/List.spec.md
@@ -25,38 +25,51 @@ design_specs: []
architecture:
[architecture:container-padding, architecture:public-component-api]
contributing: [contributing:api-conventions]
-system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2, spec:AST-057/FR9]
+system_specs:
+ [spec:AST-002/DEC-1, spec:AST-002/DEC-2, spec:AST-017/FR4, spec:AST-057/FR9]
---
# List component contract
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | Add optional `edgeCompensation?: 'inline'`; omission preserves current layout. |
-| Behavior | Every ListItem row moves its content toward a neutral host's inline content edges, reaching them when the host inset is at least the Item inset, while retaining Item-owned interaction padding. |
-| End-user impact | List content can reduce or remove the extra inset beside its optional header and adjacent content without shrinking hover, press, selection, or focus paint. |
-| Builder impact | Builders opt in only when the List is placed directly in an eligible container-padding host state. |
-| Compatibility/readiness | Additive API; implementation and required real-browser evidence are pending. |
-| Review checks | Reject header movement, unbounded negative margins, duplicated padding values, physical-edge logic, automatic opt-in, or a ListItem-level public prop. |
-| Governing rules | `architecture:container-padding/INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | Optional `edge?: 'padded' \| 'flush' \| 'outset' \| 'bleed'`, default `'padded'`. Deprecated `edgeCompensation?: 'inline'` resolves to `'outset'`. |
+| Behavior | One edge treatment applies to every ListItem row and decides where row content and row paint sit relative to the list's edges and the host's padding. |
+| End-user impact | Row text can share the line of the list header and a heading above, with row paint stopping at the text, reaching into the host padding, or reaching the host edges. |
+| Builder impact | One choice per list. `flush` works anywhere; `outset` and `bleed` act only inside a host that publishes container padding. |
+| Compatibility/readiness | Additive; omission keeps current geometry; `edgeCompensation` keeps working with a codemod to `edge`. |
+| Review checks | Reject header movement, row paint past the host's padding edge, duplicated padding values, physical-edge logic, automatic opt-in, a ListItem-level prop, or a second prop that can contradict `edge`. |
+| Governing rules | `architecture:container-padding/INV3`, `INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`; `spec:AST-017/FR4`; `spec:AST-057/FR9`. |
This table is a review projection; the body below is authoritative.
## Intent
-List owns collection-wide edge alignment because its optional header is not
-horizontally inset while every ListItem retains Item's inline padding. The caller
-knows whether the List is placed in a neutral host where these content lines
-should align; List cannot derive that design relationship from its children.
+Every ListItem keeps Item's inline inset so hover, press, and selection paint has
+room around row content. That inset leaves row text off the line of the List
+header, a heading above the list, and the host container's padding. How a
+collection resolves that depends on its rows and its host: static rows need no
+room around paint, interactive rows do, and a list inside a padded container can
+reach into that padding. The caller knows which applies; List cannot derive it
+from its rows, and the choice must hold for the whole collection.
## Compatibility and migration
- Released default preserved: `yes`; omission keeps current List and ListItem geometry.
-- Compatibility class: additive optional prop with no default behavior change.
+- Compatibility class: additive optional prop; `edgeCompensation` is a deprecated
+ alias with the same meaning as `edge="outset"`. Its `@deprecated` type reports
+ plain use; development warns only when both props are set, naming
+ `astryx upgrade` (`spec:AST-017` FR29–FR29b).
- Controlled/uncontrolled behavior: not applicable.
-- Migration decision: `component:List/DEC-1` and `component:List/DEC-2`.
+- Migration decision: `component:List/DEC-3`; an `astryx upgrade` codemod renames
+ static `edgeCompensation="inline"` to `edge="outset"`, removes
+ `edgeCompensation` beside an `edge` string that no later spread can override,
+ and keeps the old prop with a TODO where `edge` is computed, on a dynamic value,
+ and where the List also spreads props (`spec:AST-017` FR29c–FR29d). A spread onto a
+ List that never writes `edgeCompensation` stays unchanged (`spec:AST-040` FR1);
+ the `@deprecated` type reports a typed use where the props are written.
Consumer migration instructions belong in consumer docs and release notes.
@@ -64,108 +77,118 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
-- The collection-wide `edgeCompensation` opt-in and its propagation to every
- ListItem row.
-- Keeping the optional header in place while moving row content toward its line.
-- The supported relationship between ListItem row geometry and Item's normal
- density- and theme-aware inline inset.
+- The collection-wide `edge` treatment and its application to every ListItem row.
+- The deprecated `edgeCompensation` alias and its resolution.
+- Keeping the optional header in place for every treatment.
+- The relationship between row geometry and Item's density- and theme-aware
+ inline inset.
**Does not own / non-goals**
- Container padding values, nesting, or overlay resets — owned by
`architecture:container-padding`.
-- A ListItem-level compensation prop, automatic host detection, full bleed, or
- arbitrary margin controls.
+- A ListItem-level edge prop, per-edge or arbitrary inset values, automatic host
+ detection, or block-axis bleed.
- TabList or Button projections.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------- | ---------------- | -------------------------------- | -------------------------------------------- |
-| Edge compensation | omitted, `inline` | Move row content toward both logical host content edges while retaining row-local interaction padding | Every List density and marker style in an eligible host | omitted | `component:List` | accepted; implementation pending | Other values are rejected by the public type |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ---------------- | ---------- | -------------------------------------------- |
+| Edge treatment | `padded`, `flush`, `outset`, `bleed` | Where row content and row paint sit relative to the list's edges and the host's padding | Every density, marker style, and divider setting; `outset` and `bleed` read host padding | `padded` | `component:List` | accepted | Other values are rejected by the public type |
+| Edge compensation (deprecated) | omitted, `inline` | Same as `edge="outset"` | As `outset` | omitted | `component:List` | deprecated | Other values are rejected by the public type |
## Behavioral and layout contract
-| ID | Invariant | Basis | Status |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
-| FR1 | List MUST own `edgeCompensation?: 'inline'`; ListItem MUST NOT expose a parallel public prop. | `component:List/DEC-1` | Accepted contract; implementation pending |
-| FR2 | Omission MUST preserve current header, list, and row geometry. Enabling `inline` MUST leave the optional header in place and apply one compensation policy to every ListItem, including non-interactive rows. | Owner direction | Accepted contract; implementation pending |
-| FR3 | Each row MUST resolve each logical margin independently as the negative smaller of its own component-owned inline inset and the matching available host inset. Missing host inset MUST resolve to zero. Content reaches the host line only when the host inset is at least the row inset; otherwise it moves toward that line without crossing the host boundary. | `architecture:container-padding/INV9–INV10`; `component:List/DEC-2` | Accepted contract; implementation pending |
-| FR4 | The retained row inset MUST come from the same private density- and theme-derived source as Item's applied inline padding. A consumer override of row padding through `xstyle`, `className`, or `style` is outside the alignment guarantee; `edgeCompensation` MUST NOT mirror or infer that arbitrary CSS. | Shared two-owner geometry contract | Accepted contract; implementation pending |
-| FR5 | Compensation MUST preserve Item's hover, press, selection, focus, content, semantics, and hit target. It MUST NOT make the row a full-bleed surface or pull it past either available host edge. | Owner direction | Accepted contract; implementation pending |
-| FR6 | The opt-in is valid only under a host state whose published inline inset matches its applied padding and whose relevant boundary is visually neutral. Current automatic LayoutContent/LayoutPanel states with known publication mismatch are not eligible until that conformance gap is fixed. | `architecture:container-padding/INV8–INV11` | Accepted contract; implementation pending |
-| FR7 | The list element containing the rows MUST clip in the inline axis with `overflow-inline: clip`, never `hidden`, so a row dragged aside for its swipe actions paints no further than the list's inline edge without the list becoming a scroll container. | `spec:AST-057/FR9` | Verified by `List.test.tsx` |
+| ID | Invariant | Basis | Status |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| FR1 | List MUST own `edge` and apply one treatment to every ListItem row, interactive or not; ListItem MUST NOT expose a parallel public prop. A defined `edge` MUST win over `edgeCompensation`, and `edgeCompensation="inline"` with `edge` undefined MUST resolve to `outset`. | `component:List/DEC-1`, `component:List/DEC-3` | Accepted contract |
+| FR2 | `padded` MUST preserve current header, list, and row geometry. No treatment MAY move the header or change row block padding, gap, markers, start and end content, semantics, or hit target relative to the row box. | Owner direction | Accepted contract |
+| FR3 | `flush` MUST resolve each row's inline inset to zero through the private source that supplies Item's applied inline padding, so row content and row paint share the list's inline edges. It reads no host padding. A theme override of row inline padding takes precedence over the zero (FR7). | `component:List/DEC-3` | Accepted contract |
+| FR4 | `outset` MUST place each row so it reaches past the host content line by the smaller of its own inline inset and the matching host inset, per logical edge, keeping its inset inside. Content reaches the host line when the host inset is at least the row inset. | `architecture:container-padding/INV9–INV10`; `component:List/DEC-2` | Accepted contract |
+| FR5 | `bleed` MUST place each row so it reaches the host's padding edge on each logical edge, with square corners. Row content sits on the host content line, or at the row's own inset from its edge when the host inset is smaller. A theme override of row inline padding sets the content's inset instead (FR7). | `architecture:container-padding/INV3`; `component:List/DEC-4` | Accepted contract |
+| FR6 | Missing or reset host inset MUST resolve to zero, so `outset` and `bleed` place content as `padded` does outside a padded host. No row paint MAY reach past the host's padding edge. | `architecture:container-padding/INV6`, `INV9` | Accepted contract |
+| FR7 | Each row's retained inset MUST come from the same private density- and theme-derived source as Item's applied inline padding. A theme `item.paddingInline` override takes precedence over every treatment's row padding, as it does over density. A consumer override of row padding through `xstyle`, `className`, or `style` is outside the alignment guarantee. | Shared two-owner geometry contract | Accepted contract |
+| FR8 | `outset` and `bleed` are valid only under a host state whose published inline inset matches its applied padding: a visually neutral host, such as a Layout region with explicit padding or a padded ScrollableArea, or the content area of a Card, Section (any variant), Dialog, or BottomSheet. Those hosts bound their padding with a border, background, or clip; FR6 keeps row paint inside the padding edge, so it never covers the border or changes the host's outline. Automatic LayoutContent/LayoutPanel states with a known publication mismatch are not eligible until that gap is fixed, and Drawer's content area is not admitted until it has its own evidence. | `architecture:container-padding/INV8–INV11`; real-browser evidence in each admitted host | Accepted contract |
+| FR9 | The list element containing the rows MUST clip in the inline axis with `overflow-inline: clip`, never `hidden`. Under `outset` and `bleed` its inline edges MUST reach the host's padding edge, so the clip never cuts resting row paint and a swiped row paints no further than that edge. | `spec:AST-057/FR9` | Verified by `List.test.tsx` and real-browser geometry |
### Allowed variation
- Density and `item.paddingInline` theme overrides may change the retained inset;
- compensation follows the same derived value.
-- Container padding may be uniform, asymmetric, zero, or absent; each logical
- edge resolves independently.
+ every treatment follows the same derived value. A theme override of row inline
+ padding takes precedence over every treatment, as it does over density.
+- Host padding may be uniform, asymmetric, zero, or absent; each logical edge
+ resolves independently.
- Labels, descriptions, markers, start/end content, interactivity, and selection
- may vary without changing the collection-wide alignment rule.
+ may vary without changing the collection-wide treatment.
### Representative states
-| State | Required invariant | Allowed variation |
-| ------------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| Default/omitted | Header and every row keep current geometry. | Any current List content and density. |
-| Host inset at least Item inset | Row content reaches the host content line; row-local paint keeps Item padding. | Uniform or asymmetric inline padding. |
-| Smaller, zero, or missing host inset | The row moves only by the available inset and is never pulled beyond the host boundary. | Either logical edge may independently be smaller or zero. |
-| LTR or RTL | Logical start/end mapping follows direction without changing the `inline` meaning. | Writing direction. |
-| Themed Item padding | Row padding and compensation move together. | Supported `item.paddingInline` value. |
+| State | Required invariant | Allowed variation |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------- |
+| `padded` (default) | Header and every row keep current geometry. | Any content, density, or host. |
+| `flush` | Row content and paint share the list's inline edges with the header and divider ends. | Any host, including none. |
+| `outset`, host inset at least row inset | Row content reaches the host content line; row paint reaches past it by the row inset. | Uniform or asymmetric host padding. |
+| `bleed`, host inset at least row inset | Row paint reaches the host's padding edge; row content sits on the host content line. | Uniform or asymmetric host padding. |
+| `outset` or `bleed`, host inset smaller than row inset | Row paint stops at the host's padding edge; content keeps the row inset. | Either logical edge independently. |
+| `outset` or `bleed`, no host inset | Content placed as `padded`; `bleed` rows are square. | Standalone lists and overlays. |
+| LTR or RTL | Logical start/end mapping follows direction. | Writing direction. |
### Transformation and precedence order
-- **ORD1 — Host bound.** Read the matching published host inset for each selected
- logical edge, with missing values falling back to zero.
-- **ORD2 — Local inset.** Resolve Item's component-owned inline inset from density
- and theme through the same private value that supplies applied padding.
-- **ORD3 — Compensation.** Apply the negative minimum of those values to the row;
- then compose supported consumer styles without claiming alignment for a consumer
+- **ORD1 — Treatment.** Resolve `edge`, else `outset` for `edgeCompensation="inline"`,
+ else `padded`.
+- **ORD2 — Host bound.** Read the matching published host inset for each logical
+ edge, with missing values falling back to zero.
+- **ORD3 — Local inset.** Resolve Item's inline inset through the private value
+ that supplies applied padding: density sets it, `flush` replaces it with zero,
+ and a theme `item.paddingInline` override replaces either.
+- **ORD4 — Placement.** Apply the treatment's geometry from those values; then
+ compose supported consumer styles without claiming alignment for a consumer
override of row inline padding.
### Performance and resources
-- **PR1 — CSS geometry only.** Edge compensation MUST add no measurement,
- observer, listener, state, Effect, or render pass.
+- **PR1 — CSS geometry only.** Every treatment MUST add no measurement, observer,
+ listener, state, Effect, or render pass. Deprecation warnings are dev-only.
## Accessibility contract
-- **AR1 — Interaction geometry remains local.** Compensation MUST NOT change the
- interactive element, accessible role/name/state, focus target, tab order, or
- hit target.
-- **AR2 — Direction remains logical.** The same `inline` value MUST produce the
- corresponding mirrored geometry under RTL without changing DOM order.
+- **AR1 — Interaction geometry remains local.** No treatment MAY change the
+ interactive element, accessible role/name/state, focus target, or tab order.
+- **AR2 — Direction remains logical.** Each treatment MUST produce the mirrored
+ geometry under RTL without changing DOM order.
## Design relationships
-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------ | ------------------ |
-| Optional header | Stays on the host content line and is not moved by row compensation. | `component:List/DEC-1` | Context | FR2 |
-| ListItem row | Retains local interaction paint and hit-target padding. | Item composition | Supporting surface | FR3–FR5 |
-| Row content | Moves toward each host content line and reaches it only when the host inset can fully absorb the row inset. | `component:List/DEC-2` | Prominent | FR2–FR5 |
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------ | ------------------ |
+| Optional header | Stays on the host content line for every treatment. | `component:List/DEC-1` | Context | FR2 |
+| ListItem row paint | Stops at the content (`flush`), reaches past it by the row inset (`padded`, `outset`), or reaches the host edge (`bleed`). | `component:List/DEC-3` | Supporting surface | FR3–FR6 |
+| Row content | The row's first content (its marker, start content, or label) sits inside the row inset (`padded`) or on the host content line when the host inset allows (`flush`, `outset`, `bleed`). | `component:List/DEC-3` | Prominent | FR2–FR5 |
## Family and system relationships
-- `architecture:container-padding` owns host publication, the shared
- `edgeCompensation` vocabulary, eligibility, logical-edge semantics, and overlay
- reset.
-- `architecture:public-component-api` and `spec:AST-002` own public API admission.
+- `architecture:container-padding` owns host publication, eligibility,
+ logical-edge semantics, overlay reset, and the shared `edge` vocabulary. List's
+ `edge` projects all four values onto both inline edges of every row.
+- `architecture:public-component-api`, `spec:AST-002`, and `spec:AST-017` own
+ public API admission and the deprecation lifecycle.
- Item remains the implementation owner of row padding and interaction paint;
- List owns only the collection-level opt-in and row application.
+ List owns only the collection-level treatment and row placement.
- `spec:AST-057` owns swipe actions on `Item` and the rule that the element
- containing swipe-capable rows clips in the inline axis; List carries that
- clip (FR7) and `ListItem` passes `swipeActions` and `swipeBehavior` through
- to `Item` unchanged.
+ containing swipe-capable rows clips in the inline axis; List carries that clip
+ (FR9) and `ListItem` passes `swipeActions` and `swipeBehavior` through to
+ `Item` unchanged.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
-| FR1–FR4 | List, Item, and theme-registry tests | omitted/enabled; all densities; theme override; static/interactive rows | Removing context propagation, duplicating a padding value, or using one host edge for both margins fails | `audit:List/layout` |
-| FR2–FR6, AR1–AR2 | Real-browser List geometry evidence | header; LTR/RTL; uniform/asymmetric/zero/missing host inset; host inset smaller/equal/larger than Item inset; hover/selection/focus | Header movement, over-pull, wrong bounded movement, or lost row-local paint fails | `audit:List/visual` |
-| Documentation | `List.doc.mjs`, Storybook, and `scripts/check-knowledge.mjs` | public prop/default and representative composition | Missing or stale contract, docs, or example fails | `audit:List/docs` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| FR1–FR7, FR9 | List, Item, and theme-registry tests | every treatment; all densities; static and interactive rows; header; deprecated alias alone and with `edge`; ListItem outside a List | Removing context propagation, using one host edge for both inline edges, zeroing padding without the shared inset source, or dropping the list's reach or clip fails | `audit:List/layout` |
+| FR2–FR6, FR8–FR9, AR1–AR2 | Real-browser List geometry evidence | each treatment in a Card at two paddings, a Section, an inline Dialog with and without Layout, a BottomSheet, a padded ScrollableArea scrolling vertically and in both axes, a LayoutContent with explicit padding, and standalone; header and dividers; LTR/RTL; hovered and selected rows; a swiped row under `outset` and `bleed` | Header movement, content off the expected line, paint past the host's padding edge, clipped resting paint, or a changed row box fails | `audit:List/visual` |
+| Migration | `astryx upgrade` codemod tests | static, aliased, already-migrated, dynamic, and computed-`edge` callsites; a second run | A dynamic value or a computed `edge` rewritten, a static one missed, or a second run that changes output fails | `audit:List/docs` |
+| Documentation | `List.doc.mjs`, Storybook, and `scripts/check-knowledge.mjs` | public prop, values, default, deprecation, and representative composition | Missing or stale contract, docs, or example fails | `audit:List/docs` |
## Decision log
@@ -194,6 +217,35 @@ without pulling row paint beyond the host boundary.
Rejected: `isFullBleed`, because the row may stop inside the host padding and the
name would promise outer-edge bleed that the component does not provide.
+### DEC-3 — One edge prop names every row edge treatment
+
+**Reference:** `component:List/DEC-3`
+
+**Decider:** cixzhang, 2026-10-15
+
+`padded`, `flush`, `outset`, and `bleed` are mutually exclusive answers to one
+question, so one closed-value prop carries them and no combination can
+contradict. The names are the shared edge vocabulary of
+`architecture:container-padding`. `outset` is the bounded compensation of DEC-2;
+`edgeCompensation` remains its deprecated alias.
+
+Rejected: separate boolean props beside `edgeCompensation`, because they could
+request two treatments at once.
+
+### DEC-4 — Bleed reaches the host edge and keeps content on its padding line
+
+**Reference:** `component:List/DEC-4`
+
+**Decider:** cixzhang, 2026-10-15
+
+`bleed` matches Table rows in a padded host: row paint reaches the host's padding
+edge with square corners, and content sits on the host content line, never closer
+to the row edge than the row's own inset. It is opt-in, so existing lists keep
+their geometry.
+
+Rejected: bleed as the default inside padded hosts, because it would move every
+existing list in a container.
+
## Open questions
None.
diff --git a/packages/core/src/List/List.test.tsx b/packages/core/src/List/List.test.tsx
index 009f21165b..8ed1f09f40 100644
--- a/packages/core/src/List/List.test.tsx
+++ b/packages/core/src/List/List.test.tsx
@@ -3,14 +3,14 @@
/**
* @file List.test.tsx
* @input Uses vitest, @testing-library/react, List, ListItem
- * @output Unit tests for List and ListItem, including bounded inline edge compensation
+ * @output Unit tests for List and ListItem, including the row edge treatment
* @position Testing; validates List.tsx and ListItem.tsx implementation
*
* SYNC: When modified, update this header
*/
import {describe, it, expect, vi} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import {cleanup, render, screen, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {rulesDeclaredFor} from '../__tests__/pressState';
import {List} from './List';
@@ -277,121 +277,171 @@ describe('List', () => {
});
// ===========================================================================
- // Inline edge compensation
+ // Edge treatment
// ===========================================================================
- it('does not apply inline edge compensation styles by default', () => {
+ /** Every injected rule that names one of the element's classes. */
+ function declarationsFor(el: Element): string {
+ return rulesDeclaredFor(el).join('\n').replace(/\s+/g, '');
+ }
+
+ /** The declarations of the row inset variable that reach the row. */
+ function insetDeclarations(item: Element): string[] {
+ return rulesDeclaredFor(item).filter(rule =>
+ rule.includes('--_item-inset-inline:'),
+ );
+ }
+
+ const ZERO_INSET = /--_item-inset-inline:\s*0(px)?\s*;/;
+ const LIST_REACH = [
+ 'margin-inline-start:calc(-1*var(--container-padding-inline-start,0px))',
+ 'margin-inline-end:calc(-1*var(--container-padding-inline-end,0px))',
+ 'width:calc(100%+var(--container-padding-inline-start,0px)+var(--container-padding-inline-end,0px))',
+ ];
+ const OUTSET_ROW = [
+ 'margin-inline-start:max(var(--container-padding-inline-start,0px)-var(--_item-inset-inline),0px)',
+ 'margin-inline-end:max(var(--container-padding-inline-end,0px)-var(--_item-inset-inline),0px)',
+ ];
+ const BLEED_ROW = [
+ 'padding-inline-start:max(var(--container-padding-inline-start,0px),var(--_item-inset-inline))',
+ 'padding-inline-end:max(var(--container-padding-inline-end,0px),var(--_item-inset-inline))',
+ ];
+
+ function renderEdge(props: Partial<React.ComponentProps<typeof List>>) {
const {container} = render(
- <List>
- <ListItem label="Item" />
+ <List header={<span>Items</span>} {...props}>
+ <ListItem label="Static" />
+ <ListItem label="Button" onClick={() => {}} />
+ <ListItem label="Link" href="/docs" />
</List>,
);
- const item = container.querySelector('li')!;
- expect(item.className).not.toContain('inlineEdgeCompensation');
- });
+ const ul = container.querySelector('ul')!;
+ return {
+ ul,
+ header: ul.parentElement!,
+ items: [...ul.querySelectorAll('li')],
+ };
+ }
- it('applies the clamped cancelling margin to each item when edgeCompensation is inline', () => {
- // The margin lives on the row element itself — the only place that can
- // read --_item-inset-inline, which Item sets on the same element (custom
- // properties cascade downward, so the <ul> cannot read it).
- const {container} = render(
- <List edgeCompensation="inline">
- <ListItem label="Item 1" />
- <ListItem label="Item 2" />
- </List>,
- );
- const items = container.querySelectorAll('li');
- expect(items).toHaveLength(2);
+ it('keeps the row padding and leaves the list and rows in place by default', () => {
+ const {ul, items} = renderEdge({});
for (const item of items) {
- expect(item.className).toContain('inlineEdgeCompensation');
+ expect(item.className).not.toMatch(/edge(Flush|Outset|Bleed)/);
+ expect(insetDeclarations(item)).toHaveLength(1);
+ expect(insetDeclarations(item)[0]).not.toMatch(ZERO_INSET);
}
- expect(container.querySelector('ul')!.className).not.toContain(
- 'inlineEdgeCompensation',
- );
+ expect(ul.className).not.toContain('reachesContainerPadding');
+ expect(edgeContext(ul)).toBe('padded');
});
- it('uses the same var-derived cancel for every density', () => {
- // The cancelling margin reads --_item-inset-inline instead of hardcoding
- // per-density values, so all densities (and theme paddingInline
- // overrides on `item`) share one style.
+ /** The edge each row resolved, read from the row's own edge class. */
+ function edgeContext(ul: Element): string {
+ const edges = [...ul.querySelectorAll('li')].map(li => {
+ const match = /edge(Flush|Outset|Bleed)/.exec(li.className);
+ return match ? match[1].toLowerCase() : 'padded';
+ });
+ expect(new Set(edges).size).toBe(1);
+ return edges[0];
+ }
+
+ it('applies one treatment to every row, static or interactive, and never to the header', () => {
+ for (const edge of ['flush', 'outset', 'bleed'] as const) {
+ const {ul, header, items} = renderEdge({edge});
+ expect(items).toHaveLength(3);
+ expect(edgeContext(ul)).toBe(edge);
+ expect(header.className).not.toMatch(/edge|reachesContainerPadding/);
+ cleanup();
+ }
+ });
+
+ it('flush: zeroes the shared inset at every density and leaves the list in place', () => {
for (const density of ['compact', 'balanced', 'spacious'] as const) {
- const {container, unmount} = render(
- <List edgeCompensation="inline" density={density}>
- <ListItem label="Item" />
- </List>,
- );
- expect(container.querySelector('li')!.className).toContain(
- 'inlineEdgeCompensation',
- );
- unmount();
+ const {ul, items} = renderEdge({edge: 'flush', density});
+ expect(ul.className).not.toContain('reachesContainerPadding');
+ for (const item of items) {
+ expect(item).toHaveAttribute('data-density', density);
+ const insets = insetDeclarations(item);
+ expect(insets).toHaveLength(1);
+ expect(insets[0]).toMatch(ZERO_INSET);
+ }
+ cleanup();
}
});
- it('does not pull the header when edgeCompensation is inline', () => {
- // The negative margin lives on the row elements, so the header keeps its
- // position and the row text aligns up to it.
- const {container} = render(
- <List edgeCompensation="inline" header={<span>Items</span>}>
- <ListItem label="Item" />
- </List>,
- );
- expect(container.querySelector('li')!.className).toContain(
- 'inlineEdgeCompensation',
- );
- const ul = container.querySelector('ul')!;
- expect(ul.className).not.toContain('inlineEdgeCompensation');
- expect(ul.parentElement?.className).not.toContain('inlineEdgeCompensation');
+ it('outset: the list reaches the container padding and each row steps back in by what its inset does not fill, per edge', () => {
+ // Each edge reads its own container padding var: one var on both edges
+ // over-reaches the other edge under asymmetric padding (16px start /
+ // 4px end), so a selected row would paint past the outer border.
+ const {ul, items} = renderEdge({edge: 'outset'});
+ const listCss = declarationsFor(ul);
+ for (const declaration of LIST_REACH) {
+ expect(listCss).toContain(declaration);
+ }
+ for (const item of items) {
+ const css = declarationsFor(item);
+ for (const declaration of OUTSET_ROW) {
+ expect(css).toContain(declaration);
+ }
+ expect(css).not.toContain(
+ 'margin-inline-end:max(var(--container-padding-inline-start',
+ );
+ expect(insetDeclarations(item)[0]).not.toMatch(ZERO_INSET);
+ }
});
- it('clamps each inline edge against its own container padding var', () => {
- // Regression for asymmetric container padding (16px start / 4px end):
- // clamping BOTH margins against --container-padding-inline-start
- // over-cancels the end edge by the difference, and the selected row
- // paints past the outer border (RTL mirrors the spill). Each edge must
- // clamp against its matching var; logical properties keep RTL correct.
- // jsdom does no real layout, so assert on the injected StyleX CSS
- // (runtimeInjection is on in the test config).
- const {container} = render(
- <List edgeCompensation="inline">
- <ListItem label="Item" />
- </List>,
- );
- expect(container.querySelector('li')!.className).toContain(
- 'inlineEdgeCompensation',
- );
- let out = '';
- for (const sheet of Array.from(document.styleSheets)) {
- try {
- for (const rule of Array.from(sheet.cssRules)) {
- out += rule.cssText + '\n';
- }
- } catch {
- // ignore cross-origin sheets
+ it('bleed: the list reaches the container padding and rows fill it with text on the padding line, per edge', () => {
+ const {ul, items} = renderEdge({edge: 'bleed'});
+ const listCss = declarationsFor(ul);
+ for (const declaration of LIST_REACH) {
+ expect(listCss).toContain(declaration);
+ }
+ for (const item of items) {
+ const css = declarationsFor(item);
+ for (const declaration of BLEED_ROW) {
+ expect(css).toContain(declaration);
}
+ expect(css).toContain('border-radius:0');
+ expect(css).not.toMatch(/margin-inline-(start|end):max/);
}
- out += Array.from(document.querySelectorAll('style'))
- .map(s => s.textContent || '')
- .join('\n');
- const css = out.replace(/\s+/g, '');
- expect(css).toContain(
- 'margin-inline-start:calc(-1*min(var(--_item-inset-inline),var(--container-padding-inline-start,0px)))',
- );
- expect(css).toContain(
- 'margin-inline-end:calc(-1*min(var(--_item-inset-inline),var(--container-padding-inline-end,0px)))',
- );
- // The end edge must not clamp against the start var (the over-cancel).
- expect(css).not.toContain(
- 'margin-inline-end:calc(-1*min(var(--_item-inset-inline),var(--container-padding-inline-start,0px)))',
- );
});
- it('does not apply the cancelling margin to a ListItem outside a List', () => {
+ it('keeps the inline clip on the list for every treatment', () => {
+ for (const edge of ['padded', 'flush', 'outset', 'bleed'] as const) {
+ const {ul} = renderEdge({edge});
+ expect(declarationsFor(ul)).toContain('overflow-x:clip');
+ cleanup();
+ }
+ });
+
+ it('treats the deprecated edgeCompensation="inline" as edge="outset" without a runtime warning', () => {
+ // Plain use is reported statically by the @deprecated type; rendering
+ // never warns merely because the old name is used (spec:AST-017 FR29a).
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {ul} = renderEdge({edgeCompensation: 'inline'});
+ expect(edgeContext(ul)).toBe('outset');
+ expect(ul.className).toContain('reachesContainerPadding');
+ expect(warn).not.toHaveBeenCalled();
+ warn.mockRestore();
+ });
+
+ it('lets edge win over the deprecated edgeCompensation and warns about the conflict', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const {ul} = renderEdge({edge: 'flush', edgeCompensation: 'inline'});
+ expect(edgeContext(ul)).toBe('flush');
+ expect(ul.className).not.toContain('reachesContainerPadding');
+ expect(warn).toHaveBeenCalledTimes(1);
+ const message = String(warn.mock.calls[0][0]);
+ expect(message).toContain('`edge` wins');
+ expect(message).toContain('astryx upgrade');
+ warn.mockRestore();
+ });
+
+ it('keeps the inset of a ListItem outside a List', () => {
const {container} = render(<ListItem label="Standalone" />);
- expect(container.querySelector('li')!.className).not.toContain(
- 'inlineEdgeCompensation',
+ expect(container.querySelector('li')!.className).not.toMatch(
+ /edge(Flush|Outset|Bleed)/,
);
});
-
// ===========================================================================
// Dividers
// ===========================================================================
diff --git a/packages/core/src/List/List.tsx b/packages/core/src/List/List.tsx
index 315bf16a08..b2379d9104 100644
--- a/packages/core/src/List/List.tsx
+++ b/packages/core/src/List/List.tsx
@@ -4,9 +4,10 @@
/**
* @file List.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens, ListContext
- * with optional inline edge compensation
- * @output Exports List component, ListProps, ListDensity, ListStyle types
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useDevWarning,
+ * and ListContext with the row edge treatment
+ * @output Exports List component, ListProps, ListDensity, ListEdge, ListStyle
+ * types
* @position Core implementation; consumed by index.ts, tested by List.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
@@ -24,13 +25,16 @@ import type {BaseProps} from '../BaseProps';
import {
ListContext,
type ListDensity,
+ type ListEdge,
type ListMarkerStyle,
} from './ListContext';
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
+import {useDevWarning} from '../hooks/useDevWarning';
export {
type ListDensity,
+ type ListEdge,
type ListMarkerStyle as ListStyle,
} from './ListContext';
@@ -60,16 +64,39 @@ export interface ListProps extends BaseProps<
hasDividers?: boolean;
/**
- * Compensates for each item's built-in inline inset, up to the container
- * padding available on each edge. Use "inline" to bring row content toward
- * sibling content such as a section heading. Content aligns when the
- * container padding is at least the item inset; smaller padding leaves
- * some inset uncompensated.
- * The cancelling margin reads the same variable the items derive their
- * inline padding from, so it tracks density and theme padding overrides
- * automatically. Hover and selection backgrounds still extend past the
- * text by the inset.
- * Omit to leave item positions unchanged.
+ * Where each row's text, dividers, and hover and selection backgrounds sit,
+ * relative to the list's edges and the container around it.
+ * - 'padded': text sits inside each row's padding, so it starts a little in
+ * from a heading above the list and backgrounds have room around it
+ * - 'flush': rows drop their side padding, so text starts on the heading's
+ * line and dividers and backgrounds stop at the row's content, with no
+ * room beyond it on either side. Works anywhere. Suits static rows
+ * - 'outset': text sits on the heading's line, and dividers and backgrounds
+ * reach a little past it into the container's padding. Suits interactive
+ * rows in a container
+ * - 'bleed': text sits on the heading's line, and dividers and backgrounds
+ * reach the container's edges with square corners, like Table rows in a
+ * Card
+ *
+ * A row's first content is what lines up with the heading: its marker,
+ * icon, or avatar when it has one, otherwise its label. 'outset' and
+ * 'bleed' reach into the padding of the nearest container that shares its
+ * padding: a Card, Section, Dialog, or BottomSheet, or a transparent
+ * container such as a Layout region with explicit padding or a padded
+ * ScrollableArea. Place the List directly in that container's padding:
+ * padding that Stack, Center, or your own styles add in between is not
+ * counted. Drawers and the automatic padding of LayoutContent and
+ * LayoutPanel aren't supported yet. With no such container, including in a Popover, they look
+ * like 'padded'. In a container with less padding than the rows' own, text
+ * starts a little after the heading's line. A theme's inline padding on `item` replaces the row
+ * padding of every value, including the zero padding of 'flush'.
+ * @default 'padded'
+ */
+ edge?: ListEdge;
+
+ /**
+ * @deprecated Use `edge="outset"`, which this sets. Still works; `edge`
+ * wins when both are set. `astryx upgrade` rewrites existing usage.
*/
edgeCompensation?: 'inline';
@@ -121,6 +148,18 @@ const styles = stylex.create({
// vertical scroller. (StyleX emits the physical longhand of this axis.)
overflowInline: 'clip',
},
+ // 'outset' and 'bleed' rows reach into the container's padding. The list
+ // reaches the container's padding edge on each inline edge first, so its
+ // inline clip (above) moves out with the rows instead of cutting them; each
+ // row then places itself inside it. Container padding vars are inherited,
+ // so the list can read them, while the rows' own inset is scoped to the
+ // rows. Missing or reset container padding resolves to zero.
+ reachesContainerPadding: {
+ marginInlineStart: 'calc(-1 * var(--container-padding-inline-start, 0px))',
+ marginInlineEnd: 'calc(-1 * var(--container-padding-inline-end, 0px))',
+ width:
+ 'calc(100% + var(--container-padding-inline-start, 0px) + var(--container-padding-inline-end, 0px))',
+ },
withDividers: {
gap: 0,
},
@@ -148,9 +187,10 @@ const dynamicStyles = stylex.create({
* Renders semantic `<ul>` or `<ol>` elements with configurable density,
* dividers, marker styles, and an optional header.
*
- * Set `edgeCompensation="inline"` to compensate for the items' inline inset
- * up to the container padding available on each edge, for alignment with
- * sibling content such as a section heading.
+ * Set `edge` to choose where row text, dividers, and backgrounds sit: inside
+ * each row's padding (`padded`, the default), at the list's edges (`flush`),
+ * on a heading's line with backgrounds reaching into the container's padding
+ * (`outset`), or reaching the container's edges like Table rows (`bleed`).
*
* @example
* ```
@@ -162,12 +202,16 @@ const dynamicStyles = stylex.create({
* <ListItem label="First step" />
* <ListItem label="Second step" />
* </List>
+ * <List edge="flush" hasDividers>
+ * <ListItem label="Solstice Mug" description="Ceramic, 12 oz" />
+ * </List>
* ```
*/
export function List({
children,
density = 'balanced',
hasDividers = false,
+ edge: edgeProp,
edgeCompensation,
header,
listStyle = 'none',
@@ -182,10 +226,21 @@ export function List({
const headerId = useId();
const isOrdered = listStyle === 'decimal';
const Tag = isOrdered ? 'ol' : 'ul';
+ // Plain use of the deprecated prop is reported by its @deprecated type;
+ // development warns only when the two names conflict (spec:AST-017 FR29).
+ useDevWarning(
+ 'List',
+ '`edge` and the deprecated `edgeCompensation` are both set; `edge` wins. ' +
+ 'Remove `edgeCompensation`. `astryx upgrade` rewrites existing usage.',
+ edgeProp != null && edgeCompensation != null,
+ );
+ const edge: ListEdge =
+ edgeProp ?? (edgeCompensation === 'inline' ? 'outset' : 'padded');
+ const reachesContainerPadding = edge === 'outset' || edge === 'bleed';
const contextValue = useMemo(
- () => ({density, hasDividers, listStyle, edgeCompensation}),
- [density, hasDividers, listStyle, edgeCompensation],
+ () => ({density, hasDividers, edge, listStyle}),
+ [density, hasDividers, edge, listStyle],
);
const listElement = (
@@ -211,6 +266,7 @@ export function List({
stylex.props(
styles.list,
hasDividers && styles.withDividers,
+ reachesContainerPadding && styles.reachesContainerPadding,
listStyle !== 'none' &&
(start != null && start !== 1
? dynamicStyles.counterStart(start - 1)
diff --git a/packages/core/src/List/ListContext.tsx b/packages/core/src/List/ListContext.tsx
index 455c4d036c..2d48ed47e1 100644
--- a/packages/core/src/List/ListContext.tsx
+++ b/packages/core/src/List/ListContext.tsx
@@ -5,8 +5,8 @@
/**
* @file ListContext.tsx
* @input Layer-scoped React context
- * @output Exports ListContext for sharing density, dividers, marker style,
- * and optional inline edge compensation between List and ListItem, and
+ * @output Exports ListContext for sharing density, dividers, the row edge
+ * treatment, and marker style between List and ListItem, and
* ListMarkerScope, which sets the marker for the items inside it, or a
* task item's checkbox in its place
* @position Internal context; consumed by List.tsx and ListItem.tsx
@@ -18,6 +18,12 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
export type ListDensity = 'compact' | 'balanced' | 'spacious';
export type ListMarkerStyle = 'none' | 'disc' | 'decimal' | 'circle';
+/**
+ * Where each row's content and its lines and backgrounds sit relative to the
+ * list's edges and the padding of the container around the list.
+ */
+export type ListEdge = 'padded' | 'flush' | 'outset' | 'bleed';
+
/**
* Every marker ListItem draws: the public styles, and the square, letter,
* and roman markers Markdown's nested lists use (spec:AST-061 DEC-6).
@@ -35,8 +41,8 @@ export interface ListTaskMarker {
export interface ListContextValue {
density: ListDensity;
hasDividers: boolean;
+ edge: ListEdge;
listStyle: ListMarkerStyle;
- edgeCompensation?: 'inline';
/**
* The marker items draw instead of the one `listStyle` names, set by
* ListMarkerScope; internal. Ignored when `listStyle` is `'none'`.
diff --git a/packages/core/src/List/ListItem.tsx b/packages/core/src/List/ListItem.tsx
index 41ffd18c15..249d20f960 100644
--- a/packages/core/src/List/ListItem.tsx
+++ b/packages/core/src/List/ListItem.tsx
@@ -4,9 +4,10 @@
/**
* @file ListItem.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens, List edge compensation,
- * CheckboxInput, and the marker or task checkbox a ListMarkerScope sets
- * (Markdown's nested lists and the task items of mixed lists)
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, the List row edge
+ * treatment, CheckboxInput, and the marker or task checkbox a
+ * ListMarkerScope sets (Markdown's nested lists and the task items of mixed
+ * lists)
* @output Exports ListItem component, ListItemProps type
* @position Core implementation; consumed by List, index.ts, tested by List.test.tsx
*
@@ -23,6 +24,7 @@
import {use, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
@@ -149,23 +151,37 @@ const styles = stylex.create({
withCounter: {
counterIncrement: 'astryx-list',
},
- // List's inline edge compensation cancels as much of the row's built-in
- // inline inset as the container padding allows (e.g. under a heading).
- // The margins read --_item-inset-inline — the same variable Item derives
- // its paddingInline from — on the row element itself (custom properties
- // only cascade downward, so the <ul> could not read it). Density changes
- // and theme paddingInline overrides on `item` move both values together.
- // Each edge clamps against ITS OWN container padding var: a single
- // start-var clamp on both margins over-cancels the end edge under
- // asymmetric container padding (16px start / 4px end) and the selected
- // row paints past the outer border. Logical properties keep RTL correct,
- // and a zero-padding/full-bleed surface (min(inset, 0px) = 0px) leaves
- // the row in place instead of pulling it outside its content edge.
- inlineEdgeCompensation: {
+ // List's edge treatments. Each reads --_item-inset-inline, the variable
+ // Item derives its paddingInline from, on the row itself (custom properties
+ // only cascade downward, so the <ul> cannot read it); density and theme
+ // paddingInline overrides on `item` move it. Each edge resolves against ITS
+ // OWN container padding var, so asymmetric padding never over-reaches an
+ // edge, and logical properties keep RTL correct.
+ //
+ // 'flush': no inset, so content meets the row's edges.
+ edgeFlush: {
+ '--_item-inset-inline': '0px',
+ },
+ // 'outset': the list reaches the container's padding edge (List.tsx); the
+ // row steps back in by whatever padding its inset does not fill, so the row
+ // reaches min(inset, container padding) past the content line and its text
+ // lands on that line when the padding is at least the inset.
+ edgeOutset: {
marginInlineStart:
- 'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-start, 0px)))',
+ 'max(var(--container-padding-inline-start, 0px) - var(--_item-inset-inline), 0px)',
marginInlineEnd:
- 'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-end, 0px)))',
+ 'max(var(--container-padding-inline-end, 0px) - var(--_item-inset-inline), 0px)',
+ },
+ // 'bleed': the row fills the list, which reaches the container's padding
+ // edge (List.tsx); its text sits on the container's padding line, never
+ // closer to the row's edge than its own inset. Square corners: the row
+ // meets the container's straight sides.
+ edgeBleed: {
+ paddingInlineStart:
+ 'max(var(--container-padding-inline-start, 0px), var(--_item-inset-inline))',
+ paddingInlineEnd:
+ 'max(var(--container-padding-inline-end, 0px), var(--_item-inset-inline))',
+ borderRadius: 0,
},
withDivider: {
borderBlockEndWidth: borderVars['--border-width'],
@@ -313,8 +329,8 @@ export function ListItem({
const ctx = use(ListContext);
const density = ctx?.density ?? 'balanced';
const hasDividers = ctx?.hasDividers ?? false;
+ const edge = ctx?.edge ?? 'padded';
const listStyle = ctx?.listStyle ?? 'none';
- const edgeCompensation = ctx?.edgeCompensation;
const hasMarkers = listStyle !== 'none';
// ListMarkerScope may name another marker for this item.
const markerKind: ListMarker | null =
@@ -370,13 +386,17 @@ export function ListItem({
isSelected={isSelected}
align={align}
density={density}
- xstyle={[
- hasMarkers && styles.withCounter,
- hasDividers && styles.withDivider,
- hasDividers && embeddedStyles.noRadius,
- edgeCompensation === 'inline' && styles.inlineEdgeCompensation,
- xstyle,
- ]}
+ xstyle={
+ [
+ hasMarkers && styles.withCounter,
+ hasDividers && styles.withDivider,
+ hasDividers && embeddedStyles.noRadius,
+ edge === 'flush' && styles.edgeFlush,
+ edge === 'outset' && styles.edgeOutset,
+ edge === 'bleed' && styles.edgeBleed,
+ xstyle,
+ ] as StyleXStyles
+ }
{...mergeProps(themeProps('list-item'), {className, style})}
{...restProps}
/>
diff --git a/packages/core/src/List/index.ts b/packages/core/src/List/index.ts
index 8021940604..7126a7fbba 100644
--- a/packages/core/src/List/index.ts
+++ b/packages/core/src/List/index.ts
@@ -12,6 +12,6 @@
*/
export {List} from './List';
-export type {ListProps, ListStyle, ListDensity} from './List';
+export type {ListProps, ListStyle, ListDensity, ListEdge} from './List';
export {ListItem} from './ListItem';
export type {ListItemProps} from './ListItem';
diff --git a/packages/core/src/TabList/TabList.spec.md b/packages/core/src/TabList/TabList.spec.md
index b613bc543f..02b0c34070 100644
--- a/packages/core/src/TabList/TabList.spec.md
+++ b/packages/core/src/TabList/TabList.spec.md
@@ -31,10 +31,10 @@ system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2, spec:AST-017/DEC-1]
| Area | Contract |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | Canonicalize the existing alignment mode as `edgeCompensation?: 'inline'`; deprecate `isFullBleed` and remove it in the next minor release. |
+| Public contract | Canonicalize the existing mode as `edge?: 'padded' \| 'bleed'` (default `'padded'`) from the shared `edge` vocabulary; deprecate `isFullBleed` as an alias of `edge="bleed"` and remove it in the next minor release. |
| Behavior | Move first and last visible tab content toward the host content line, reaching it when the host inset is at least the edge-tab padding, while preserving tab interaction padding, focus-ring room, overflow controls, selection-indicator geometry, and the optional divider rail. |
| End-user impact | Edge tabs lose unnecessary extra inset where host geometry permits and remain fully interactive without clipped focus, selection, overflow, or divider treatment. |
-| Builder impact | Existing `isFullBleed` callsites keep working during the deprecation window and migrate mechanically to `edgeCompensation="inline"`. |
+| Builder impact | Existing `isFullBleed` callsites keep working during the deprecation window and migrate mechanically to `edge="bleed"`. |
| Compatibility/readiness | Current behavior is shipped; the canonical alias is additive, while removing the released legacy prop is a separately implemented breaking change in the next minor release. |
| Review checks | Reject a behavior change disguised as a rename, directional values without overflow/indicator proof, or early removal of the legacy prop. |
| Governing rules | `architecture:container-padding/INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`; `spec:AST-017/DEC-1`. |
@@ -43,12 +43,13 @@ This table is a review projection; the body below is authoritative.
## Intent
-TabList's current opt-in is edge compensation: it consumes the full inherited
-host inset, moves visible edge-tab content toward the surrounding content line,
+TabList's current opt-in is the shared `bleed` edge treatment: it consumes the
+full inherited host inset, moves visible edge-tab content toward the surrounding content line,
and retains Tab-owned interaction padding plus TabList-owned divider, overflow,
and indicator geometry. Content reaches the host line only when that inset is at
least the edge tab's own padding. The public `isFullBleed` name is misleading
-because the strip restores uncovered content inset after the outer box expands.
+because the strip keeps a content line: it restores uncovered content inset
+after the outer box expands, which `architecture:container-padding` names `bleed`.
## Compatibility and migration
@@ -61,21 +62,21 @@ because the strip restores uncovered content inset after the outer box expands.
During the compatibility window:
-- `edgeCompensation="inline"` is the canonical spelling;
-- omitted `edgeCompensation` plus `isFullBleed={true}` selects the same mode;
+- `edge="bleed"` is the canonical spelling, and omitted `edge` means `padded`;
+- omitted `edge` plus `isFullBleed={true}` selects `bleed`;
- `isFullBleed` is deprecated and maintained examples use the canonical prop;
-- if both props are supplied, explicit `edgeCompensation` is canonical and the
- legacy boolean cannot disable it.
+- if both props are supplied, explicit `edge` is canonical and the legacy
+ boolean cannot override it.
The removal release MUST include a `[breaking]` Changeset for
`@astryxdesign/core`, consumer release notes, and an `astryx upgrade` codemod that rewrites
-`isFullBleed` to `edgeCompensation="inline"`.
+`isFullBleed` to `edge="bleed"`.
## Ownership boundary
**Owns**
-- The TabList-wide edge-compensation mode and its compatibility alias.
+- The TabList-wide `bleed` edge treatment and its compatibility alias.
- The relationship between the outer TabList box, inner strip padding, edge tabs,
focus-ring room, overflow controls, and selection indicator.
- Which logical edges are supported by the public mode.
@@ -84,33 +85,34 @@ The removal release MUST include a `[breaking]` Changeset for
- Host padding publication, nesting, or overlay resets — owned by
`architecture:container-padding`.
-- Button or List edge-compensation projections.
-- New `start` or `end` values without separate proof and owner approval.
+- Button or List edge projections.
+- The `flush` or `outset` values, or per-edge application, without separate
+ proof and owner approval.
- A change to navigation/tab semantics, selection state, keyboard behavior, or
overflow ownership.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ----------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------- | ------------------- | ------------------------------- | ------------------------------------------------------ |
-| Edge compensation | omitted, `inline` | Consume both inherited inline host insets and move edge-tab content toward the host lines while retaining local interaction and strip-owned geometry | Navigation and tabs patterns across current layout/overflow states | omitted | `component:TabList` | accepted; canonical API pending | Other values are rejected by the public type |
-| Legacy alias | omitted, `false`, `true` | Compatibility spelling for omitted or inline edge compensation | Until the next minor release | omitted/`false` | `component:TabList` | deprecated | `true` maps to `inline`; explicit canonical input wins |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------ | ------------------- | ------------------------------- | -------------------------------------------- |
+| Edge treatment | omitted, `padded`, `bleed` | `bleed`: consume both inherited inline host insets and move edge-tab content toward the host lines while retaining local interaction and strip-owned geometry; `padded`: current default geometry | Navigation and tabs patterns across current layout/overflow states | omitted (`padded`) | `component:TabList` | accepted; canonical API pending | Other values are rejected by the public type |
+| Legacy alias | omitted, `false`, `true` | Compatibility spelling for `padded` or `bleed` | Until the next minor release | omitted/`false` | `component:TabList` | deprecated | `true` maps to `bleed`; explicit `edge` wins |
## Behavioral and layout contract
-| ID | Invariant | Basis | Status |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
-| FR1 | The current opt-in MUST remain edge compensation: the outer TabList box consumes the full inherited inline host inset and any `hasDivider` rail spans that expanded width; the inner strip restores `max(host inset - edge-tab padding, 0)` at each logical edge. Visible edge-tab content reaches the host line only when the host inset is at least the tab padding; otherwise it moves toward that line without crossing the host boundary. | Current source and `component:TabList/DEC-1` | Shipped behavior |
-| FR2 | Compensation MUST preserve Tab interaction padding, focus-ring room, overflow detection and controls, scroll access, selection-indicator geometry, and the optional divider rail's expanded inline span. | Current source plus owner direction | Shipped behavior; expanded evidence required with rename |
-| FR3 | `edgeCompensation?: 'inline'` MUST become the canonical API without changing FR1–FR2 geometry or the omitted default. | `architecture:container-padding/INV10`; `component:TabList/DEC-1` | Accepted contract; implementation pending |
-| FR4 | During the deprecation window, omitted `edgeCompensation` plus `isFullBleed={true}` MUST produce the canonical `inline` behavior. Explicit `edgeCompensation` MUST remain authoritative when both props are supplied. | Compatibility decision | Accepted contract; implementation pending |
-| FR5 | `isFullBleed` MUST be removed in the next minor release only after maintained docs/examples use `edgeCompensation`, both paths have compatibility evidence, and the removal includes a `[breaking]` Changeset plus an `astryx upgrade` codemod for mechanical consumer migration. | `component:TabList/DEC-1`; `spec:AST-017/DEC-1` | Accepted contract; implementation pending |
-| FR6 | `start` and `end` MUST remain rejected until per-edge overflow, clipping, scroll-control, focus-ring, indicator, direction, and theme-padding evidence receives owner approval. | Shared logical vocabulary and TabList boundary | Accepted boundary |
+| ID | Invariant | Basis | Status |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
+| FR1 | The current opt-in MUST remain the `bleed` treatment: the outer TabList box consumes the full inherited inline host inset and any `hasDivider` rail spans that expanded width; the inner strip restores `max(host inset - edge-tab padding, 0)` at each logical edge. Visible edge-tab content reaches the host line only when the host inset is at least the tab padding; otherwise it moves toward that line without crossing the host boundary. | Current source and `component:TabList/DEC-1` | Shipped behavior |
+| FR2 | Compensation MUST preserve Tab interaction padding, focus-ring room, overflow detection and controls, scroll access, selection-indicator geometry, and the optional divider rail's expanded inline span. | Current source plus owner direction | Shipped behavior; expanded evidence required with rename |
+| FR3 | `edge?: 'padded' \| 'bleed'` MUST become the canonical API, with `bleed` selecting FR1–FR2 geometry and `padded` the omitted default, without changing either. | `architecture:container-padding/INV10`; `component:TabList/DEC-1` | Accepted contract; implementation pending |
+| FR4 | During the deprecation window, omitted `edge` plus `isFullBleed={true}` MUST produce the canonical `bleed` behavior. Explicit `edge` MUST remain authoritative when both props are supplied. | Compatibility decision | Accepted contract; implementation pending |
+| FR5 | `isFullBleed` MUST be removed in the next minor release only after maintained docs/examples use `edge`, both paths have compatibility evidence, and the removal includes a `[breaking]` Changeset plus an `astryx upgrade` codemod for mechanical consumer migration. | `component:TabList/DEC-1`; `spec:AST-017/DEC-1` | Accepted contract; implementation pending |
+| FR6 | `flush`, `outset`, and per-edge application MUST remain rejected until overflow, clipping, scroll-control, focus-ring, indicator, direction, and theme-padding evidence receives owner approval. | Shared edge vocabulary and TabList boundary | Accepted boundary |
### Allowed variation
- Layout, size, role, selected value, labels, tab content, and overflow mode may
- vary while the same edge-compensation meaning is preserved.
+ vary while the same `bleed` meaning is preserved.
- The implementation may retain the current outer-box/inner-strip technique or
replace it with equivalent geometry that satisfies FR1–FR2.
- A host may be painted or bounded only where TabList's component-specific
@@ -118,20 +120,20 @@ The removal release MUST include a `[breaking]` Changeset for
### Representative states
-| State | Required invariant | Allowed variation |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| Default/omitted | Current TabList box, strip, and tab geometry are unchanged. | Any current layout, role, or overflow mode. |
-| Canonical inline mode | Outer box consumes each host inset; edge content reaches the host line only when that inset is at least the tab padding. | Host inset smaller than, equal to, or larger than edge-tab padding; asymmetric insets; LTR/RTL. |
-| Divider | `hasDivider` rail spans the expanded outer inline width. | Fitting or overflowing strips. |
-| Legacy alias | `isFullBleed={true}` matches canonical inline geometry during the compatibility window. | The canonical prop may also be present. |
-| Overflowing strip | Scroll access, edge fades, controls, and selected-tab reveal remain correct. | Start/end overflow independently. |
-| Focused edge tab | The focus ring remains visible and local to the tab. | Keyboard or pointer focus. |
+| State | Required invariant | Allowed variation |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| Default/omitted | Current TabList box, strip, and tab geometry are unchanged. | Any current layout, role, or overflow mode. |
+| Canonical `bleed` | Outer box consumes each host inset; edge content reaches the host line only when that inset is at least the tab padding. | Host inset smaller than, equal to, or larger than edge-tab padding; asymmetric insets; LTR/RTL. |
+| Divider | `hasDivider` rail spans the expanded outer inline width. | Fitting or overflowing strips. |
+| Legacy alias | `isFullBleed={true}` matches canonical `bleed` geometry during the compatibility window. | The canonical prop may also be present. |
+| Overflowing strip | Scroll access, edge fades, controls, and selected-tab reveal remain correct. | Start/end overflow independently. |
+| Focused edge tab | The focus ring remains visible and local to the tab. | Keyboard or pointer focus. |
### Transformation and precedence order
-- **ORD1 — Public input.** Resolve explicit `edgeCompensation`; otherwise map
- `isFullBleed={true}` to `inline` during the compatibility window; otherwise use
- no compensation.
+- **ORD1 — Public input.** Resolve explicit `edge`; otherwise map
+ `isFullBleed={true}` to `bleed` during the compatibility window; otherwise use
+ `padded`.
- **ORD2 — Host geometry.** Read the matching inherited logical host insets, with
missing values falling back to zero.
- **ORD3 — Component geometry.** Resolve edge-tab padding and focus/indicator
@@ -145,10 +147,10 @@ The removal release MUST include a `[breaking]` Changeset for
## Accessibility contract
-- **AR1 — Interaction remains stable.** Edge compensation MUST NOT change the
+- **AR1 — Interaction remains stable.** The `bleed` treatment MUST NOT change the
tab/nav pattern, accessible names, selected state, keyboard movement, tab stop,
focus target, or controlled value behavior.
-- **AR2 — Overflow remains reachable.** Compensated edge geometry MUST NOT clip or
+- **AR2 — Overflow remains reachable.** `bleed` geometry MUST NOT clip or
hide a focus ring, selected indicator, visible tab content, or an overflow
control required to reach offscreen tabs.
@@ -162,8 +164,8 @@ The removal release MUST include a `[breaking]` Changeset for
## Family and system relationships
-- `architecture:container-padding` owns host publication, the shared
- `edgeCompensation` vocabulary, logical-edge semantics, and overlay reset.
+- `architecture:container-padding` owns host publication, the shared `edge`
+ vocabulary, logical-edge semantics, and overlay reset.
- `architecture:public-component-api` and `spec:AST-002` own public API
admission; `spec:AST-017/DEC-1` owns the breaking classification and migration
evidence required when the released alias is removed.
@@ -189,9 +191,20 @@ TabList's current mode consumes the full inherited inline host inset, keeps an
optional divider across that expanded width, and restores only the portion of
content inset not already supplied by edge-tab padding. The user-facing intent is
therefore edge compensation, not a promise that tab content itself reaches an
-outer edge. `edgeCompensation="inline"` becomes the canonical spelling;
-`isFullBleed` remains a compatibility alias until its `[breaking]` next-minor
-removal, with the required codemod and release evidence.
+outer edge. DEC-2 sets the canonical spelling; `isFullBleed` remains a
+compatibility alias until its `[breaking]` next-minor removal, with the required
+codemod and release evidence.
+
+### DEC-2 — TabList spells its mode with the shared edge vocabulary
+
+**Reference:** `component:TabList/DEC-2`
+
+**Decider:** cixzhang, 2026-10-16
+
+`architecture:container-padding` names TabList's geometry `bleed`: paint reaches
+the host's padding edge and content stays on the host content line, or at the
+edge tab's own padding when the host inset is smaller. `edge="bleed"` is the
+canonical spelling, so TabList and List share one prop name and one value set.
## Open questions
diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.ts
index 8127b8d568..e7a0f799ec 100644
--- a/packages/core/src/theme/derivedVarRegistry.test.ts
+++ b/packages/core/src/theme/derivedVarRegistry.test.ts
@@ -261,6 +261,9 @@ const CROSS_COMPONENT_VARS: Record<string, string[]> = {
// The destructive item variant recolors the Item it renders; Item owns,
// documents and reads both slots.
DropdownMenu: ['--_item-label-color', '--_item-description-color'],
+ // List's edge="flush" zeroes the inline inset of the Item each ListItem
+ // renders; Item owns, documents and reads it.
+ List: ['--_item-inset-inline'],
// A layer content root stops an outer Stepper's connector gap; Stepper owns,
// documents and reads it.
Layer: ['--step-connector-gap'],