An open source design system that's fully customizable and agent ready
TypeScript
feat(Item): align="first-line" centers start and end content on the label's first line (#7643)
Cindy Zhangcaec7cab6c7e
diff --git a/.changeset/item-align-first-line.md b/.changeset/item-align-first-line.mdnew file mode 100644index 0000000000..0fd9d39559--- /dev/null+++ b/.changeset/item-align-first-line.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] `Item` accepts `align="first-line"`, which centers each start and end slot on the label's first line. A small status dot, radio, checkbox, or timestamp beside a wrapping label now stays level with the first line, where `center` drops it to the middle of the row and `start` leaves it above the line. A slot taller than the first line moves the text down rather than leaving the row, and a one-line row with no description looks the same as `center`. `ListItem`, `RadioListItem`, and `CheckboxListItem` accept the same `align` and pass it to their row. Themes can style these rows through the `item` target's `align` axis. The default stays `center`, so existing rows don't change.++@cixzhangdiff --git a/.github/scripts/story-play-guard.js b/.github/scripts/story-play-guard.jsindex 50c8f12e2c..c889e3f40f 100644--- a/.github/scripts/story-play-guard.js+++ b/.github/scripts/story-play-guard.js@@ -38,6 +38,12 @@ const port = Number(getArg('port') || 6010);// Stories whose play assertions are load-bearing. Adding a story here is the// whole cost of promoting its play function into required CI.const TARGETS = [+ {+ component: 'Item',+ story: 'core-item--align-first-line',+ guards:+ 'under align="first-line" every start and end slot centers on the label\'s first line (wrapped, clamped, dense, spacious, avatar, interactive, RTL, ListItem, RadioListItem) and never rises into the row padding',+ },{component: 'Selector',story: 'core-selector--size-variants',diff --git a/apps/storybook/stories/Item.stories.tsx b/apps/storybook/stories/Item.stories.tsxindex f8b29b3743..eb8c2d3655 100644--- a/apps/storybook/stories/Item.stories.tsx+++ b/apps/storybook/stories/Item.stories.tsx@@ -1,8 +1,9 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {useState} from 'react';+import {useState, type ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';import type {Meta, StoryObj} from '@storybook/react';+import {expect} from 'storybook/test';import {Item} from '@astryxdesign/core/Item';import {Avatar} from '@astryxdesign/core/Avatar';import {Badge} from '@astryxdesign/core/Badge';@@ -10,6 +11,8 @@ import {Icon} from '@astryxdesign/core/Icon';import {Text} from '@astryxdesign/core/Text';import {Stack} from '@astryxdesign/core/Layout';import {List, ListItem} from '@astryxdesign/core/List';+import {RadioList, RadioListItem} from '@astryxdesign/core/RadioList';+import {StatusDot} from '@astryxdesign/core/StatusDot';const storyStyles = stylex.create({iconCircle: {@@ -40,7 +43,7 @@ const meta: Meta<typeof Item> = {component: Item,tags: ['autodocs'],argTypes: {- align: {control: 'select', options: ['center', 'start']},+ align: {control: 'select', options: ['center', 'start', 'first-line']},density: {control: 'select', options: ['compact', 'balanced', 'spacious']},},};@@ -279,6 +282,190 @@ export const AlignStart: Story = {),};+const WRAPPING_TITLE =+ 'Investigate why the session list jumps when a long title wraps onto a second line';++function FirstLineCase({+ name,+ dir,+ children,+}: {+ name: string;+ dir?: 'rtl';+ children: ReactNode;+}) {+ return (+ <div data-first-line-case={name} dir={dir} style={{inlineSize: 320}}>+ {children}+ </div>+ );+}++/**+ * `align="first-line"` centers each start and end slot on the label's first+ * line: a status dot and an age stay level with the first line of a wrapped+ * title, a taller slot (an avatar beside a description) moves the text down+ * instead of leaving the row, and a one-line row looks the same as `center`.+ * The play function measures every case in a real browser.+ */+export const AlignFirstLine: Story = {+ render: () => {+ const dot = <StatusDot variant="success" label="Active" />;+ const age = (+ <Text type="supporting" color="secondary">+ 12m+ </Text>+ );+ return (+ <Stack gap={4}>+ <FirstLineCase name="wrapped">+ <Item+ align="first-line"+ startContent={dot}+ label={<span>{WRAPPING_TITLE}</span>}+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="wrapped-description">+ <Item+ align="first-line"+ startContent={dot}+ label={<span>{WRAPPING_TITLE}</span>}+ description="astryx · 3 files changed"+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="clamped">+ <Item+ align="first-line"+ startContent={dot}+ label={WRAPPING_TITLE}+ labelLines={2}+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="compact">+ <Item+ align="first-line"+ density="compact"+ startContent={dot}+ label={<span>{WRAPPING_TITLE}</span>}+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="spacious">+ <Item+ align="first-line"+ density="spacious"+ startContent={dot}+ label={<span>{WRAPPING_TITLE}</span>}+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="avatar-description">+ <Item+ align="first-line"+ startContent={<Avatar name="Ada Lovelace" size="lg" />}+ label="Ada Lovelace"+ description="Design systems"+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="interactive">+ <Item+ align="first-line"+ onClick={() => {}}+ startContent={dot}+ label={<span>{WRAPPING_TITLE}</span>}+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="rtl" dir="rtl">+ <Item+ align="first-line"+ startContent={dot}+ label={+ <span>+ تحقق من سبب قفز قائمة الجلسات عندما يلتف عنوان طويل إلى سطر ثان+ </span>+ }+ endContent={age}+ />+ </FirstLineCase>+ <FirstLineCase name="list-item">+ <List>+ <ListItem+ align="first-line"+ startContent={dot}+ label={<span>{WRAPPING_TITLE}</span>}+ endContent={age}+ />+ </List>+ </FirstLineCase>+ <FirstLineCase name="radio-list-item">+ <RadioList label="Plan" value="team" onChange={() => {}}>+ <RadioListItem+ value="team"+ align="first-line"+ label={<span>{WRAPPING_TITLE}</span>}+ />+ </RadioList>+ </FirstLineCase>+ </Stack>+ );+ },+ play: async ({canvasElement}) => {+ const cases = canvasElement.querySelectorAll<HTMLElement>(+ '[data-first-line-case]',+ );+ expect(cases).toHaveLength(10);+ for (const testCase of cases) {+ const row = testCase.querySelector<HTMLElement>('.astryx-item');+ expect(row?.dataset.align).toBe('first-line');+ if (row == null) {+ continue;+ }+ const children = [...row.children] as HTMLElement[];+ const content = children.find(+ child => getComputedStyle(child).flexGrow === '1',+ );+ const label = content?.firstElementChild as HTMLElement | null;+ expect(label).toBeTruthy();+ if (content == null || label == null) {+ continue;+ }+ const lineHeight = parseFloat(getComputedStyle(label).lineHeight);+ const firstLineCenter =+ label.getBoundingClientRect().top + lineHeight / 2;+ const rowBox = row.getBoundingClientRect();+ const contentTop =+ rowBox.top + parseFloat(getComputedStyle(row).paddingBlockStart);+ // The start and end slots: in-flow children other than the text.+ // Out-of-flow children (a slot's own popover, such as Avatar's+ // tooltip) are not slots.+ const slots = children.filter(+ child =>+ child !== content &&+ !['absolute', 'fixed'].includes(getComputedStyle(child).position),+ );+ expect(slots.length).toBeGreaterThan(0);+ for (const slot of slots) {+ const mark = (slot.firstElementChild as HTMLElement | null) ?? slot;+ const box = mark.getBoundingClientRect();+ // Each slot's center sits on the first line's center...+ expect(+ Math.abs(box.top + box.height / 2 - firstLineCenter),+ `${testCase.dataset.firstLineCase}: slot center off the first line`,+ ).toBeLessThanOrEqual(0.5);+ // ...and never rises into the row's padding.+ expect(slot.getBoundingClientRect().top).toBeGreaterThanOrEqual(+ contentTop - 0.5,+ );+ }+ }+ },+};+/*** Swipe actions, as a mail list uses them: on a touch screen a drag toward* the inline start uncovers Archive and Delete (Delete outermost, so a longdiff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsxindex 209a2676df..2c68f7e253 100644--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx@@ -59,6 +59,28 @@ beforeEach(() => {});describe('CheckboxList', () => {+ it('forwards CheckboxListItem align to its Item row unchanged', () => {+ render(+ <CheckboxList label="Toppings" value={[]} onChange={() => {}}>+ <CheckboxListItem label="Cheese" value="cheese" data-testid="cheese" />+ <CheckboxListItem+ label="Olives"+ value="olives"+ align="first-line"+ data-testid="olives"+ />+ </CheckboxList>,+ );+ expect(screen.getByTestId('cheese')).toHaveAttribute(+ 'data-align',+ 'center',+ );+ expect(screen.getByTestId('olives')).toHaveAttribute(+ 'data-align',+ 'first-line',+ );+ });+it('renders with label', () => {render(<CheckboxList label="Preferences" value={[]} onChange={() => {}}>diff --git a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjsindex 878a0540c5..8dfac9edc6 100644--- a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs+++ b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs@@ -55,6 +55,13 @@ export const docs = {},],},+ {+ name: 'align',+ type: "'center' | 'start' | 'first-line'",+ description:+ 'Vertical alignment of the start and end content against the label, passed through to Item unchanged. `first-line` keeps a small mark (a checkbox) level with the first line of a wrapped label. See Item.align.',+ default: "'center'",+ },{name: 'isDisabled',type: 'boolean',@@ -130,6 +137,13 @@ export const docsZh = {type: 'ReactNode',description: '在标签区域后渲染的内容。',},+ {+ name: 'align',+ type: "'center' | 'start' | 'first-line'",+ description:+ '起始和结束内容相对于标签的垂直对齐方式,原样传递给 Item。`first-line` 让小标记(复选框)与换行标签的第一行保持水平。参见 Item.align。',+ default: "'center'",+ },{name: 'isDisabled',type: 'boolean',@@ -165,6 +179,8 @@ export const docsDense = {description:'Individual checkbox item w/ label, description, end content slot. Collection mode inside CheckboxList with value; standalone inside List or CheckboxList without value.',propDescriptions: {+ align:+ "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",label:'Primary label. String or ReactNode; nested controls keep their behavior. A ReactNode names the checkbox from its visible text.','aria-label':diff --git a/packages/core/src/CheckboxList/CheckboxListItem.tsx b/packages/core/src/CheckboxList/CheckboxListItem.tsxindex 1e65681599..591bf799d9 100644--- a/packages/core/src/CheckboxList/CheckboxListItem.tsx+++ b/packages/core/src/CheckboxList/CheckboxListItem.tsx@@ -29,6 +29,7 @@ import {ListContext} from '../List/ListContext';import {CheckboxListContext} from './CheckboxListContext';import {useTranslator} from '../i18n';import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';+import type {ItemAlign} from '../Item';// =============================================================================// Styles@@ -45,6 +46,13 @@ const styles = stylex.create({// =============================================================================export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {+ /**+ * Vertical alignment of the start and end content against the label,+ * forwarded to Item. Use `first-line` to keep the checkbox level with the+ * first line of a wrapped label.+ * @default 'center'+ */+ align?: ItemAlign;/*** Primary text label for the item.*@@ -192,6 +200,7 @@ export function CheckboxListItem({className,style,onClick: onClickProp,+ align,...restProps}: CheckboxListItemProps) {const t = useTranslator();@@ -297,6 +306,7 @@ export function CheckboxListItem({label={namesFromVisibleLabel ? <span id={labelID}>{label}</span> : label}description={description}endContent={endContent}+ align={align}isDisabled={effectiveDisabled}// Delegate row clicks to the checkbox instead of wiring onClick (which// would add an invisible row button = a second tab stop). The checkboxdiff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjsindex f73d12c6df..e7c814f7a2 100644--- a/packages/core/src/Item/Item.doc.mjs+++ b/packages/core/src/Item/Item.doc.mjs@@ -118,8 +118,9 @@ export const docs = {},{name: 'align',- type: "'center' | 'start'",- description: 'Vertical alignment of start/end content slots.',+ type: "'center' | 'start' | 'first-line'",+ description:+ "Vertical alignment of start/end content slots. 'center' centers each slot on the whole text block; 'start' lines up slot tops with the text's top; 'first-line' centers each slot on the label's first line, so a small mark stays level with the first line of a wrapped label. A slot taller than that line moves the text down. The `item` theme target reflects the value as `align`.",default: "'center'",},{@@ -248,7 +249,7 @@ export const docs = {{guidance: true,description:- 'Use align="start" when start or end content is taller than a single line of text.',+ 'Use align="first-line" when a wrapping label sits beside a small mark (a status dot, a radio, a timestamp) that belongs to its first line. Use align="start" to line up the tops of a tall slot and the text.',},{guidance: true,@@ -321,7 +322,8 @@ export const docsZh = {endContent:'在标签/描述区域之后渲染的内容,例如徽章、元数据、时间戳或操作按钮。',as: '根元素的 HTML 元素。',- align: '起始/结束内容插槽的垂直对齐方式。',+ align:+ "起始/结束内容插槽的垂直对齐方式:'center'(默认)、'start'(顶部对齐)或 'first-line'(以标签第一行为中心)。",density:'间距密度。"compact" 使用 4px 块内距,"balanced" 使用 8px,"spacious" 使用 12px 块内距和内联内距。',labelLines: '标签截断前的最大行数。',@@ -363,7 +365,8 @@ export const docsZh = {},{guidance: true,- description: '当起始或结束内容高于单行文本时使用 align="start"。',+ description:+ '当换行标签旁边是属于其第一行的小标记(状态点、单选按钮、时间戳)时,使用 align="first-line"。使用 align="start" 让较高插槽与文本顶部对齐。',},{guidance: false,@@ -426,7 +429,7 @@ export const docsDense = {{guidance: true,description:- 'align="start" when start/end content is taller than one text line.',+ 'align="first-line" for a small mark beside a wrapping label; align="start" to top-align a tall slot with the text.',},{guidance: false,@@ -458,7 +461,8 @@ export const docsDense = {endContent:'Content after label/description: badges, timestamps, actions.',as: 'Root HTML element.',- align: 'Vertical alignment of start/end content slots.',+ align:+ "Start/end slot alignment: 'center' (default), 'start' (tops), or 'first-line' (centered on the label's first line).",density:'Spacing: "compact" (4px), "balanced" (8px), or "spacious" (12px).',labelLines: 'Max label lines before truncation.',diff --git a/packages/core/src/Item/Item.test.tsx b/packages/core/src/Item/Item.test.tsxindex 6d68c32838..760c48f3ab 100644--- a/packages/core/src/Item/Item.test.tsx+++ b/packages/core/src/Item/Item.test.tsx@@ -531,6 +531,67 @@ describe('Item', () => {expect(screen.getByTestId('item')).toBeInTheDocument();});+ it('reflects the resolved alignment on the item theme target', () => {+ const {rerender} = render(<Item label="Item" data-testid="item" />);+ expect(screen.getByTestId('item')).toHaveAttribute('data-align', 'center');+ for (const align of ['center', 'start', 'first-line'] as const) {+ rerender(<Item label="Item" align={align} data-testid="item" />);+ const item = screen.getByTestId('item');+ expect(item).toHaveClass('astryx-item');+ expect(item).toHaveAttribute('data-align', align);+ }+ });++ it('aligns the row on first baselines only under first-line', () => {+ const {rerender} = render(<Item label="Item" data-testid="item" />);+ const declares = (value: string) =>+ rulesDeclaredFor(screen.getByTestId('item')).some(rule =>+ rule.includes(`align-items: ${value}`),+ );+ expect(declares('baseline')).toBe(false);+ rerender(<Item label="Item" align="start" data-testid="item" />);+ expect(declares('baseline')).toBe(false);+ rerender(<Item label="Item" align="first-line" data-testid="item" />);+ expect(declares('baseline')).toBe(true);+ });++ it('gives each first-line slot a strut with no accessible text', () => {+ render(+ <Item+ label="Item"+ align="first-line"+ startContent={<span data-testid="start">S</span>}+ endContent={<span data-testid="end">E</span>}+ />,+ );+ for (const id of ['start', 'end']) {+ const slot = screen.getByTestId(id).parentElement!;+ const before = rulesDeclaredFor(slot).filter(rule =>+ rule.slice(0, rule.indexOf('{')).includes('::before'),+ );+ expect(before.some(rule => rule.includes('/ ""'))).toBe(true);+ }+ });++ it('leaves center and start slots without a strut', () => {+ const {rerender} = render(+ <Item label="Item" startContent={<span data-testid="start">S</span>} />,+ );+ const hasStrut = () =>+ rulesDeclaredFor(screen.getByTestId('start').parentElement!).some(rule =>+ rule.slice(0, rule.indexOf('{')).includes('::before'),+ );+ expect(hasStrut()).toBe(false);+ rerender(+ <Item+ label="Item"+ align="start"+ startContent={<span data-testid="start">S</span>}+ />,+ );+ expect(hasStrut()).toBe(false);+ });+// ===========================================================================// Description rendering// ===========================================================================diff --git a/packages/core/src/Item/Item.tsx b/packages/core/src/Item/Item.tsxindex bbff0f0385..4fd6683629 100644--- a/packages/core/src/Item/Item.tsx+++ b/packages/core/src/Item/Item.tsx@@ -67,7 +67,7 @@ const LazyItemSwipeLayer = lazy(async () => import('./ItemSwipeLayer'));// Types// =============================================================================-export type ItemAlign = 'center' | 'start';+export type ItemAlign = 'center' | 'start' | 'first-line';export type ItemDensity = 'compact' | 'balanced' | 'spacious';/**@@ -168,7 +168,11 @@ export interface ItemProps extends BaseProps<HTMLElement> {endContent?: ReactNode;/**- * Vertical alignment of the start/end content slots.+ * Vertical alignment of the start/end content slots. `center` centers each+ * slot on the whole text block; `start` lines up slot tops with the text's+ * top; `first-line` centers each slot on the label's first line, so a small+ * mark (a status dot, a radio, a timestamp) stays level with the first line+ * of a wrapped label. A slot taller than that line moves the text down.* @default 'center'*/align?: ItemAlign;@@ -351,6 +355,30 @@ const styles = stylex.create({alignStart: {alignItems: 'flex-start',},+ // `first-line`: the row aligns its children on their first baselines. The+ // label's first baseline is its first line's; each slot gets the same+ // baseline from its strut (below), which the slot centers against its+ // content. So each slot's center lands on the first line's center for any+ // slot height, and a taller slot pushes the text down instead of leaving+ // the row. Pure CSS: no measurement.+ alignFirstLine: {+ alignItems: 'baseline',+ },+ // A zero-width line of label text inside the slot: same size and leading as+ // the label, so its line box is the label's first line box. The slot centers+ // it against the slot's content, and the row's baseline alignment puts it on+ // the label's first line. Its content carries empty alternative text so+ // assistive technology reads nothing from it.+ firstLineSlot: {+ alignItems: 'center',+ '::before': {+ content: stylex.firstThatWorks('"\\200B" / ""', '"\\200B"'),+ inlineSize: 0,+ overflow: 'hidden',+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ },+ },interactive: {cursor: {default: 'pointer',@@ -712,7 +740,13 @@ export function Item({<>{marker}{startContent != null && (- <span {...stylex.props(styles.startContent)}>{startContent}</span>+ <span+ {...stylex.props(+ styles.startContent,+ align === 'first-line' && styles.firstLineSlot,+ )}>+ {startContent}+ </span>)}{hasParentRole || isDelegate ? (@@ -768,6 +802,7 @@ export function Item({<span{...stylex.props(styles.endContent,+ align === 'first-line' && styles.firstLineSlot,isDisabled && styles.disabledContent,)}>{endContent}@@ -846,6 +881,7 @@ export function Item({styles.root,densityStyles[density],align === 'start' && styles.alignStart,+ align === 'first-line' && styles.alignFirstLine,isInteractive && styles.interactive,isInteractive && interactionOverlayStyles.backgroundColor,isLinkRoot && styles.linkRoot,diff --git a/packages/core/src/List/List.test.tsx b/packages/core/src/List/List.test.tsxindex 57a530f241..009f21165b 100644--- a/packages/core/src/List/List.test.tsx+++ b/packages/core/src/List/List.test.tsx@@ -18,6 +18,25 @@ import {ListItem} from './ListItem';import {ListMarkerScope} from './ListContext';describe('List', () => {+ it('forwards ListItem align to its Item row unchanged', () => {+ render(+ <List>+ <ListItem label="Default" data-testid="default" />+ <ListItem label="Start" align="start" data-testid="start" />+ <ListItem label="First" align="first-line" data-testid="first" />+ </List>,+ );+ expect(screen.getByTestId('default')).toHaveAttribute(+ 'data-align',+ 'center',+ );+ expect(screen.getByTestId('start')).toHaveAttribute('data-align', 'start');+ expect(screen.getByTestId('first')).toHaveAttribute(+ 'data-align',+ 'first-line',+ );+ });+// ===========================================================================// Basic rendering// ===========================================================================diff --git a/packages/core/src/List/ListItem.doc.mjs b/packages/core/src/List/ListItem.doc.mjsindex aa3c9e6159..60c5ff3f89 100644--- a/packages/core/src/List/ListItem.doc.mjs+++ b/packages/core/src/List/ListItem.doc.mjs@@ -88,6 +88,13 @@ export const docs = {description:'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".',},+ {+ name: 'align',+ type: "'center' | 'start' | 'first-line'",+ description:+ 'Vertical alignment of the start and end content against the label, passed through to Item unchanged. `first-line` keeps a small mark (a status dot, an icon) level with the first line of a wrapped label. See Item.align.',+ default: "'center'",+ },{name: 'isDisabled',type: 'boolean',@@ -173,6 +180,13 @@ export const docsZh = {description:'链接关系标记。target="_blank" 会自动合并 noopener noreferrer。',},+ {+ name: 'align',+ type: "'center' | 'start' | 'first-line'",+ description:+ '起始和结束内容相对于标签的垂直对齐方式,原样传递给 Item。`first-line` 让小标记(状态点、图标)与换行标签的第一行保持水平。参见 Item.align。',+ default: "'center'",+ },{name: 'isDisabled',type: 'boolean',@@ -207,6 +221,8 @@ export const docsDense = {description:'List item w/ label, description, start/end content slots, interactive patterns.',propDescriptions: {+ align:+ "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",label:'Primary content. String auto-truncates; ReactNode renders as given.',description: 'Secondary text below label.',diff --git a/packages/core/src/List/ListItem.tsx b/packages/core/src/List/ListItem.tsxindex a2d7457695..41ffd18c15 100644--- a/packages/core/src/List/ListItem.tsx+++ b/packages/core/src/List/ListItem.tsx@@ -34,7 +34,7 @@ import {ListContext, type ListMarker} from './ListContext';import {CheckboxInput} from '../CheckboxInput';import {mergeProps} from '../utils';import {Item} from '../Item';-import type {ItemSwipeActions, ItemSwipeBehavior} from '../Item';+import type {ItemAlign, ItemSwipeActions, ItemSwipeBehavior} from '../Item';import {themeProps} from '../utils/themeProps';// =============================================================================@@ -44,6 +44,13 @@ import {themeProps} from '../utils/themeProps';export interface ListItemProps extends BaseProps<HTMLLIElement> {/** Ref forwarded to the root element */ref?: React.Ref<HTMLLIElement>;+ /**+ * Vertical alignment of the start and end content against the label,+ * forwarded to Item. Use `first-line` to keep the start and end content level with the+ * first line of a wrapped label.+ * @default 'center'+ */+ align?: ItemAlign;/*** Primary text label for the item.*@@ -296,6 +303,7 @@ export function ListItem({rel,isDisabled = false,isSelected = false,+ align,xstyle,className,style,@@ -360,6 +368,7 @@ export function ListItem({rel={rel}isDisabled={isDisabled}isSelected={isSelected}+ align={align}density={density}xstyle={[hasMarkers && styles.withCounter,diff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsxindex 45abe1862f..5d5b4ae986 100644--- a/packages/core/src/RadioList/RadioList.test.tsx+++ b/packages/core/src/RadioList/RadioList.test.tsx@@ -524,6 +524,28 @@ describe('RadioList', () => {});describe('RadioListItem rest forwarding', () => {+ it('forwards align to its Item row unchanged', () => {+ render(+ <RadioList label="Preference" value="" onChange={() => {}}>+ <RadioListItem label="Option A" value="a" data-testid="item-a" />+ <RadioListItem+ label="Option B"+ value="b"+ align="first-line"+ data-testid="item-b"+ />+ </RadioList>,+ );+ expect(screen.getByTestId('item-a')).toHaveAttribute(+ 'data-align',+ 'center',+ );+ expect(screen.getByTestId('item-b')).toHaveAttribute(+ 'data-align',+ 'first-line',+ );+ });+it('forwards data-testid, id, and aria-* to the item root element', () => {render(<RadioList label="Preference" value="" onChange={() => {}}>diff --git a/packages/core/src/RadioList/RadioListItem.doc.mjs b/packages/core/src/RadioList/RadioListItem.doc.mjsindex b664130a15..f784cb28d3 100644--- a/packages/core/src/RadioList/RadioListItem.doc.mjs+++ b/packages/core/src/RadioList/RadioListItem.doc.mjs@@ -43,6 +43,13 @@ export const docs = {description:'Secondary content displayed below the label. Links and buttons keep their own click behaviour — the row only delegates clicks from its non-interactive surface to the radio.',},+ {+ name: 'align',+ type: "'center' | 'start' | 'first-line'",+ description:+ 'Vertical alignment of the start and end content against the label, passed through to Item unchanged. `first-line` keeps a small mark (a radio) level with the first line of a wrapped label. See Item.align.',+ default: "'center'",+ },{name: 'isDisabled',type: 'boolean',@@ -117,6 +124,13 @@ export const docsZh = {description:'显示在标签下方的次要内容。链接和按钮保留自身的点击行为——整行仅将非交互区域的点击委派给单选框。',},+ {+ name: 'align',+ type: "'center' | 'start' | 'first-line'",+ description:+ '起始和结束内容相对于标签的垂直对齐方式,原样传递给 Item。`first-line` 让小标记(单选按钮)与换行标签的第一行保持水平。参见 Item.align。',+ default: "'center'",+ },{name: 'isDisabled',type: 'boolean',@@ -142,6 +156,8 @@ export const docsDense = {displayName: 'Radio List Item',description: 'Individual radio item w/ label, description, content slots.',propDescriptions: {+ align:+ "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",label:'Primary label. String or ReactNode; nested controls keep their behavior.','aria-label':diff --git a/packages/core/src/RadioList/RadioListItem.tsx b/packages/core/src/RadioList/RadioListItem.tsxindex 406d71e7ac..7df2df5245 100644--- a/packages/core/src/RadioList/RadioListItem.tsx+++ b/packages/core/src/RadioList/RadioListItem.tsx@@ -29,7 +29,7 @@ import {indicatorScope} from '../Indicator/indicator.markers.stylex';import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';import {usePressFeedback} from '../hooks/usePressFeedback';import {useIndicator} from '../Indicator';-import {Item} from '../Item';+import {Item, type ItemAlign} from '../Item';import {themeProps} from '../utils/themeProps';// The touch press's paint, declared by the shared overlay styles on the@@ -156,6 +156,13 @@ const rowStyles = stylex.create({export interface RadioListItemProps extends BaseProps<HTMLDivElement> {ref?: React.Ref<HTMLDivElement>;+ /**+ * Vertical alignment of the start and end content against the label,+ * forwarded to Item. Use `first-line` to keep the radio level with the+ * first line of a wrapped label.+ * @default 'center'+ */+ align?: ItemAlign;/*** Primary label for the radio item.*@@ -232,6 +239,7 @@ export function RadioListItem({isDisabled: isItemDisabled = false,startContent,endContent,+ align,xstyle,className,style,@@ -366,6 +374,7 @@ export function RadioListItem({) : undefined}endContent={endContent}+ align={align}xstyle={[// Hover reaches the radio visual through this ancestor marker rather