Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/.github/scripts/story-play-guard.js b/.github/scripts/story-play-guard.js
index 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.tsx
index 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 long
diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsx
index 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.mjs
index 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.tsx
index 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 checkbox
diff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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