Skip to content

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

TypeScript

feat(list): add bounded inline edge compensation (#4590)

Jiun Shind07687a1d5d8
diff --git a/.changeset/list-full-bleed.md b/.changeset/list-full-bleed.md
new file mode 100644
index 0000000000..0259af3478
--- /dev/null
+++ b/.changeset/list-full-bleed.md
@@ -0,0 +1,10 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `List`: add `edgeCompensation="inline"` to compensate for item content inset within container padding (#2626)
+
+`ListItem` insets its content by a density-dependent horizontal padding, so a list under a section heading reads as misaligned and consumers reach for negative-margin custom CSS. `edgeCompensation="inline"` on `List` cancels, per inline edge, the smaller of that inset and the container's published padding on that edge; zero-padding and full-bleed surfaces therefore stay in place, asymmetric container padding never over-cancels an edge, and headers, hover backgrounds, and selection backgrounds keep their existing geometry.
+
+`Item` now publishes its inline inset as `--_item-inset-inline` and derives its own `paddingInline` from it, and the clamped cancelling margin reads the same variable — so the cancel tracks density and theme overrides instead of mirroring hardcoded values. Themes that set `paddingInline` on `item` feed the variable automatically via the derived var registry.
+@jiunshinn
diff --git a/apps/storybook/stories/List.stories.tsx b/apps/storybook/stories/List.stories.tsx
index 408e60e0a7..cc7ebbbffc 100644
--- a/apps/storybook/stories/List.stories.tsx
+++ b/apps/storybook/stories/List.stories.tsx
@@ -1,6 +1,13 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-import {useState} from 'react';
+/**
+ * @file List.stories.tsx
+ * @input List, ListItem, and Storybook args
+ * @output List examples, including bounded inline edge compensation
+ * @position Storybook demonstrations for List consumers
+ */
+
+import {useState, type CSSProperties} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {List, ListItem} from '@astryxdesign/core/List';
import {Avatar} from '@astryxdesign/core/Avatar';
@@ -32,6 +39,13 @@ const meta: Meta<typeof List> = {
control: 'boolean',
description: 'Whether to show dividers between items',
},
+ edgeCompensation: {
+ control: 'select',
+ options: [undefined, 'inline'],
+ description:
+ "Cancel each item's inset up to the padded container edge so row " +
+ 'text moves toward sibling content',
+ },
listStyle: {
control: 'select',
options: ['none', 'disc', 'decimal', 'circle'],
@@ -112,6 +126,57 @@ 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'},
+ render: args => (
+ <div style={inlineEdgeCompensationContainerStyle}>
+ <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={() => {}}
+ />
+ </List>
+ </div>
+ ),
+ parameters: {
+ 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.',
+ },
+ },
+ },
+};
+
export const Interactive: Story = {
render: args => (
<List {...args}>
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
index 127aef0f06..73ab3d60f4 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
@@ -3,7 +3,7 @@
/**
* @file DropdownMenu.test.tsx
* @input Uses vitest, @testing-library/react, DropdownMenu component
- * @output Unit tests for DropdownMenu component behavior
+ * @output Unit tests for DropdownMenu behavior and derived bottom-sheet item padding
* @position Testing; validates DropdownMenu.tsx implementation
*
* SYNC: When DropdownMenu.tsx changes, update tests to match new behavior
@@ -165,7 +165,10 @@ describe('DropdownMenu', () => {
});
expect(
screen.getByRole('button', {name: 'Edit project'}).closest('li'),
- ).toHaveStyle({paddingInline: 'var(--spacing-3)'});
+ ).toHaveStyle({
+ paddingInline: 'var(--_item-inset-inline)',
+ '--_item-inset-inline': 'var(--spacing-3)',
+ });
});
it('drills into nested data items in bottom-sheet presentation', async () => {
diff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjs
index f475b1a3c2..084afb38f3 100644
--- a/packages/core/src/Item/Item.doc.mjs
+++ b/packages/core/src/Item/Item.doc.mjs
@@ -22,6 +22,10 @@ export const docs = {
vars: [
{name: '--_item-label-color', description: 'Color of the label line. Unset by default (the label uses the primary text token); a parent sets it to recolor the label it renders, as the destructive dropdown/context menu item does.', default: 'var(--color-text-primary)', private: true},
{name: '--_item-description-color', description: 'Companion to --_item-label-color for the secondary description line.', default: 'var(--color-text-secondary)', private: true},
+ {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.', default: 'var(--spacing-2) (var(--spacing-3) for density="spacious")', private: true},
+ ],
+ derived: [
+ {property: 'paddingInline', vars: ['--_item-inset-inline']},
],
},
components: [
diff --git a/packages/core/src/Item/Item.tsx b/packages/core/src/Item/Item.tsx
index 2576d2746d..5b035f708f 100644
--- a/packages/core/src/Item/Item.tsx
+++ b/packages/core/src/Item/Item.tsx
@@ -5,7 +5,7 @@
/**
* @file Item.tsx
* @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
- * @output Exports Item component, ItemProps type
+ * @output Exports Item component, ItemProps type; publishes the shared inline inset
* @position Core layout primitive; consumed by index.ts, tested by Item.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
@@ -209,7 +209,13 @@ const styles = stylex.create({
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
- paddingInline: 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.
+ // 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'],
+ paddingInline: 'var(--_item-inset-inline)',
position: 'relative',
boxSizing: 'border-box',
textAlign: 'start',
@@ -356,7 +362,7 @@ const densityStyles = stylex.create({
},
spacious: {
paddingBlock: spacingVars['--spacing-3'],
- paddingInline: spacingVars['--spacing-3'],
+ '--_item-inset-inline': spacingVars['--spacing-3'],
},
});
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index f24c3dfd29..983953a3fa 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -41,6 +41,12 @@ export const docs = {
description: 'Show dividers between items.',
default: 'false',
},
+ {
+ 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.",
+ },
{
name: 'header',
type: 'ReactNode',
diff --git a/packages/core/src/List/List.test.tsx b/packages/core/src/List/List.test.tsx
index dc501eb4cc..35c776bf51 100644
--- a/packages/core/src/List/List.test.tsx
+++ b/packages/core/src/List/List.test.tsx
@@ -3,7 +3,7 @@
/**
* @file List.test.tsx
* @input Uses vitest, @testing-library/react, List, ListItem
- * @output Unit tests for List and ListItem components
+ * @output Unit tests for List and ListItem, including bounded inline edge compensation
* @position Testing; validates List.tsx and ListItem.tsx implementation
*
* SYNC: When modified, update this header
@@ -255,6 +255,122 @@ describe('List', () => {
expect(item).toHaveAttribute('data-density', 'spacious');
});
+ // ===========================================================================
+ // Inline edge compensation
+ // ===========================================================================
+
+ it('does not apply inline edge compensation styles by default', () => {
+ const {container} = render(
+ <List>
+ <ListItem label="Item" />
+ </List>,
+ );
+ const item = container.querySelector('li')!;
+ expect(item.className).not.toContain('inlineEdgeCompensation');
+ });
+
+ 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);
+ for (const item of items) {
+ expect(item.className).toContain('inlineEdgeCompensation');
+ }
+ expect(container.querySelector('ul')!.className).not.toContain(
+ 'inlineEdgeCompensation',
+ );
+ });
+
+ 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.
+ 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();
+ }
+ });
+
+ 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('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
+ }
+ }
+ 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', () => {
+ const {container} = render(<ListItem label="Standalone" />);
+ expect(container.querySelector('li')!.className).not.toContain(
+ 'inlineEdgeCompensation',
+ );
+ });
+
// ===========================================================================
// Dividers
// ===========================================================================
diff --git a/packages/core/src/List/List.tsx b/packages/core/src/List/List.tsx
index 5b63cd6b67..12b0422da9 100644
--- a/packages/core/src/List/List.tsx
+++ b/packages/core/src/List/List.tsx
@@ -5,6 +5,7 @@
/**
* @file List.tsx
* @input Uses React, ReactNode, StyleXStyles, theme tokens, ListContext
+ * with optional inline edge compensation
* @output Exports List component, ListProps, ListDensity, ListStyle types
* @position Core implementation; consumed by index.ts, tested by List.test.tsx
*
@@ -58,6 +59,20 @@ 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.
+ */
+ edgeCompensation?: 'inline';
+
/**
* Header content rendered above the list.
* Semantically associated via aria-labelledby.
@@ -128,6 +143,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.
+ *
* @example
* ```
* <List>
@@ -144,6 +163,7 @@ export function List({
children,
density = 'balanced',
hasDividers = false,
+ edgeCompensation,
header,
listStyle = 'none',
start,
@@ -159,8 +179,8 @@ export function List({
const Tag = isOrdered ? 'ol' : 'ul';
const contextValue = useMemo(
- () => ({density, hasDividers, listStyle}),
- [density, hasDividers, listStyle],
+ () => ({density, hasDividers, listStyle, edgeCompensation}),
+ [density, hasDividers, listStyle, edgeCompensation],
);
const listElement = (
diff --git a/packages/core/src/List/ListContext.tsx b/packages/core/src/List/ListContext.tsx
index dbe45d3ef6..ff95d81a3a 100644
--- a/packages/core/src/List/ListContext.tsx
+++ b/packages/core/src/List/ListContext.tsx
@@ -5,7 +5,8 @@
/**
* @file ListContext.tsx
* @input Uses React createContext
- * @output Exports ListContext for sharing density between List and ListItem
+ * @output Exports ListContext for sharing density, dividers, marker style,
+ * and optional inline edge compensation between List and ListItem
* @position Internal context; consumed by List.tsx and ListItem.tsx
*/
@@ -18,6 +19,7 @@ export interface ListContextValue {
density: ListDensity;
hasDividers: boolean;
listStyle: ListMarkerStyle;
+ edgeCompensation?: 'inline';
}
export const ListContext = createContext<ListContextValue | null>(null);
diff --git a/packages/core/src/List/ListItem.tsx b/packages/core/src/List/ListItem.tsx
index a3b56347ef..668eae8826 100644
--- a/packages/core/src/List/ListItem.tsx
+++ b/packages/core/src/List/ListItem.tsx
@@ -4,7 +4,7 @@
/**
* @file ListItem.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, List edge compensation
* @output Exports ListItem component, ListItemProps type
* @position Core implementation; consumed by List, index.ts, tested by List.test.tsx
*
@@ -124,6 +124,24 @@ 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: {
+ marginInlineStart:
+ 'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-start, 0px)))',
+ marginInlineEnd:
+ 'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-end, 0px)))',
+ },
withDivider: {
borderBlockEndWidth: borderVars['--border-width'],
borderBlockEndStyle: 'solid',
@@ -230,6 +248,7 @@ export function ListItem({
const density = ctx?.density ?? 'balanced';
const hasDividers = ctx?.hasDividers ?? false;
const listStyle = ctx?.listStyle ?? 'none';
+ const edgeCompensation = ctx?.edgeCompensation;
const hasMarkers = listStyle !== 'none';
const marker =
@@ -266,6 +285,7 @@ export function ListItem({
hasMarkers && styles.withCounter,
hasDividers && styles.withDivider,
hasDividers && embeddedStyles.noRadius,
+ edgeCompensation === 'inline' && styles.inlineEdgeCompensation,
xstyle,
]}
{...mergeProps(themeProps('list-item'), {className, style})}
diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.ts
index 5ee6cfc69c..bcbfb77013 100644
--- a/packages/core/src/theme/derivedVarRegistry.test.ts
+++ b/packages/core/src/theme/derivedVarRegistry.test.ts
@@ -223,6 +223,7 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
DropdownMenu: 'dropdown-menu',
Field: 'field',
HoverCard: 'hover-card',
+ Item: 'item',
NumberInput: 'number-input',
Popover: 'popover',
ProgressBar: 'progress-bar-mark',
@@ -321,6 +322,12 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([
'--spinner-color',
'--spinner-track-color',
'--spinner-arc-fraction',
+ // Set by a PARENT component (e.g. the destructive dropdown/context menu
+ // item) to recolor the two text lines it renders. A single standard `color`
+ // property cannot map onto both lines, and the root color is not what they
+ // control — a theme reaches them by setting the vars directly.
+ '--_item-label-color',
+ '--_item-description-color',
]);
// ---------------------------------------------------------------------------
diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.ts
index 85001700c5..dddb65bdb2 100644
--- a/packages/core/src/theme/derivedVarRegistry.ts
+++ b/packages/core/src/theme/derivedVarRegistry.ts
@@ -68,6 +68,7 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
],
field: [{property: 'borderRadius', vars: ['--_field-radius']}],
'hover-card': [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
+ item: [{property: 'paddingInline', vars: ['--_item-inset-inline']}],
'number-input': [
{property: 'padding', expand: 'container'},
{property: 'borderRadius', vars: ['--_field-radius']},
diff --git a/packages/core/src/theme/generateThemeRules.test.ts b/packages/core/src/theme/generateThemeRules.test.ts
index 389986ece7..318cd18177 100644
--- a/packages/core/src/theme/generateThemeRules.test.ts
+++ b/packages/core/src/theme/generateThemeRules.test.ts
@@ -957,6 +957,33 @@ describe('derived var expansion', () => {
expect(rule).toContain('--_dropdown-menu-padding: 8px');
});
+ it('emits paddingInline AND internal inset var for item', () => {
+ // The inset var is what keeps List's isFullBleed cancel in sync with a
+ // themed row padding — the padding override alone would move the text
+ // while the cancel keeps the default width.
+ const theme = defineTheme({
+ name: 'test-derived-item',
+ components: {
+ item: {
+ base: {paddingInline: 'var(--spacing-3)'},
+ 'density:spacious': {paddingInline: 'var(--spacing-4)'},
+ },
+ },
+ });
+ const rules = generateThemeRules(theme);
+ const baseRule = rules.find(
+ r => r.includes('.astryx-item ') || r.includes('.astryx-item {'),
+ );
+ expect(baseRule).toBeDefined();
+ expect(baseRule).toContain('padding-inline: var(--spacing-3)');
+ expect(baseRule).toContain('--_item-inset-inline: var(--spacing-3)');
+ const spaciousRule = rules.find(r =>
+ r.includes('.astryx-item[data-density="spacious"]'),
+ );
+ expect(spaciousRule).toBeDefined();
+ expect(spaciousRule).toContain('--_item-inset-inline: var(--spacing-4)');
+ });
+
it('emits internal vars for chat composer', () => {
const theme = defineTheme({
name: 'test-derived-chat',