An open source design system that's fully customizable and agent ready
TypeScript
metadata list (#931)
Andrey Goder47cc726b18a3
diff --git a/apps/storybook/stories/MetadataList.stories.tsx b/apps/storybook/stories/MetadataList.stories.tsxnew file mode 100644index 0000000000..f3f1304063--- /dev/null+++ b/apps/storybook/stories/MetadataList.stories.tsx@@ -0,0 +1,171 @@+import type {Meta, StoryObj} from '@storybook/react';+import {XDSMetadataList, XDSMetadataListItem} from '@xds/core/MetadataList';+import {XDSIcon} from '@xds/core/Icon';+import {XDSToken} from '@xds/core/Token';+import {+ InformationCircleIcon,+ CalendarIcon,+ TagIcon,+} from '@heroicons/react/24/outline';++const meta: Meta<typeof XDSMetadataList> = {+ title: 'Core/XDSMetadataList',+ component: XDSMetadataList,+ tags: ['autodocs'],+ argTypes: {+ columns: {+ control: 'select',+ options: ['single', 'multi', 2, 3],+ description: 'Column layout mode',+ },+ orientation: {+ control: 'select',+ options: ['vertical', 'horizontal'],+ description: 'Layout orientation',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSMetadataList>;++export const Basic: Story = {+ render: args => (+ <XDSMetadataList {...args}>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const MultiColumn: Story = {+ render: args => (+ <XDSMetadataList columns="multi" {...args}>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>+ <XDSMetadataListItem label="Tags">+ <span style={{display: 'flex', gap: 4}}>+ <XDSToken label="component" />+ <XDSToken label="xds" />+ </span>+ </XDSMetadataListItem>+ <XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const WithTitle: Story = {+ render: args => (+ <XDSMetadataList+ title={<strong>Component Details</strong>}+ columns="multi"+ {...args}>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const Horizontal: Story = {+ render: args => (+ <XDSMetadataList orientation="horizontal" {...args}>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Type">Premium</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const StackedLabelsSingleColumn: Story = {+ render: args => (+ <XDSMetadataList label={{position: 'top'}} {...args}>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Tags">+ <span style={{display: 'flex', gap: 4}}>+ <XDSToken label="component" />+ <XDSToken label="xds" />+ </span>+ </XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const ShowMore: Story = {+ render: args => (+ <XDSMetadataList maxNumOfItems={3} {...args}>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>+ <XDSMetadataListItem label="Updated">Mar 26, 2026</XDSMetadataListItem>+ <XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const TwoColumns: Story = {+ render: args => (+ <XDSMetadataList columns={2} {...args}>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Priority">Tier 1</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const CustomLabelWidth: Story = {+ render: args => (+ <XDSMetadataList label={{position: 'start', width: 200}} {...args}>+ <XDSMetadataListItem label="Full Name">+ XDSMetadataList Component+ </XDSMetadataListItem>+ <XDSMetadataListItem label="Current Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Primary Owner">Joey</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const MultiColumnSideLabels: Story = {+ render: args => (+ <XDSMetadataList columns="multi" label={{position: 'start'}} {...args}>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>+ </XDSMetadataList>+ ),+};++export const WithIcons: Story = {+ render: args => (+ <XDSMetadataList columns="multi" {...args}>+ <XDSMetadataListItem+ label="Information"+ icon={<XDSIcon icon={InformationCircleIcon} size="sm" />}>+ Important details about this component+ </XDSMetadataListItem>+ <XDSMetadataListItem+ label="Created"+ icon={<XDSIcon icon={CalendarIcon} size="sm" />}>+ January 1, 2023+ </XDSMetadataListItem>+ <XDSMetadataListItem+ label="Tags"+ icon={<XDSIcon icon={TagIcon} size="sm" />}>+ <span style={{display: 'flex', gap: 4}}>+ <XDSToken label="component" />+ <XDSToken label="xds" />+ </span>+ </XDSMetadataListItem>+ </XDSMetadataList>+ ),+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex 9857b87447..12b69d03f9 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -190,6 +190,12 @@"import": "./dist/List/index.mjs","require": "./dist/List/index.js"},+ "./MetadataList": {+ "source": "./src/MetadataList/index.ts",+ "types": "./dist/MetadataList/index.d.ts",+ "import": "./dist/MetadataList/index.mjs",+ "require": "./dist/MetadataList/index.js"+ },"./MobileNav": {"source": "./src/MobileNav/index.ts","types": "./dist/MobileNav/index.d.ts",diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjsnew file mode 100644index 0000000000..80e476d540--- /dev/null+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs@@ -0,0 +1,159 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'MetadataList',+ description:+ 'A read-only labeled list for displaying key-value metadata. Semantic equivalent of HTML <dl>/<dt>/<dd> with layout control, column modes, and consistent styling. Uses a composition model: XDSMetadataList wraps XDSMetadataListItem sub-components.',+ features: [+ 'Composition model — XDSMetadataList wraps XDSMetadataListItem sub-components',+ 'Column modes: single, multi (auto-fill), or fixed number',+ 'Label positioning: start (side-by-side) or top (stacked)',+ 'Horizontal orientation with flex-wrap',+ 'Show more / show less toggle when items exceed maxNumOfItems',+ 'Optional title heading above the list',+ 'Optional icon before label text',+ 'Semantic <dl>/<dt>/<dd> HTML structure',+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSMetadataList>+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+</XDSMetadataList>`,+ },+ {+ label: 'Multi-column',+ code: `<XDSMetadataList columns="multi">+ <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Created">Jan 15, 2026</XDSMetadataListItem>+</XDSMetadataList>`,+ },+ {+ label: 'Horizontal',+ code: `<XDSMetadataList orientation="horizontal">+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Type">Premium</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+</XDSMetadataList>`,+ },+ {+ label: 'With title and show more',+ code: `<XDSMetadataList title={<XDSHeading type="header4">Details</XDSHeading>} maxNumOfItems={3}>+ <XDSMetadataListItem label="Name">Value</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ <XDSMetadataListItem label="Owner">Joey</XDSMetadataListItem>+ <XDSMetadataListItem label="Created">Jan 2026</XDSMetadataListItem>+ <XDSMetadataListItem label="Updated">Mar 2026</XDSMetadataListItem>+</XDSMetadataList>`,+ },+ ],+ accessibility: [+ 'Semantic <dl> with <dt>/<dd> pairs',+ 'aria-controls links the show more/less button to the list',+ 'aria-expanded indicates whether the list is fully expanded',+ ],+ theming: {+ targets: [+ {+ className: 'xds-metadata-list',+ visualProps: ['columns', 'orientation'],+ },+ {className: 'xds-metadata-list-item'},+ ],+ },+ components: [+ {+ name: 'XDSMetadataList',+ description:+ 'Container for metadata items with column layout, orientation, and collapse support.',+ examples: [+ {+ label: 'With title',+ code: `<XDSMetadataList title={<strong>Details</strong>} columns="multi">+ <XDSMetadataListItem label="Name">Value</XDSMetadataListItem>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+</XDSMetadataList>`,+ },+ ],+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Metadata items (XDSMetadataListItem components).',+ required: true,+ },+ {+ name: 'columns',+ type: "'multi' | 'single' | number",+ description: 'Column layout mode.',+ default: "'single'",+ },+ {+ name: 'label',+ type: "{ position?: 'start' | 'top', width?: number | string }",+ description:+ "Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts.",+ default: "{ position: 'start' } (single-column) / { position: 'top' } (multi-column)",+ },+ {+ name: 'maxNumOfItems',+ type: 'number',+ description:+ 'Maximum items to show before collapsing with a show more/less toggle.',+ },+ {+ name: 'orientation',+ type: "'vertical' | 'horizontal'",+ description:+ 'Layout orientation. Horizontal mode flows items in a row with flex-wrap.',+ default: "'vertical'",+ },+ {+ name: 'title',+ type: 'ReactNode',+ description: 'Optional title or heading above the list.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ },+ {+ name: 'XDSMetadataListItem',+ description: 'A single labeled metadata value within an XDSMetadataList.',+ examples: [+ {+ label: 'With icon',+ code: `<XDSMetadataListItem label="Status" icon={<StatusIcon />}>+ Active+</XDSMetadataListItem>`,+ },+ ],+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content value for this metadata item.',+ required: true,+ },+ {+ name: 'label',+ type: 'string',+ description: 'Label text for this metadata item.',+ required: true,+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Icon rendered before the label text.',+ },+ ],+ },+ ],+};diff --git a/packages/core/src/MetadataList/XDSMetadataList.test.tsx b/packages/core/src/MetadataList/XDSMetadataList.test.tsxnew file mode 100644index 0000000000..7bd8f2ff44--- /dev/null+++ b/packages/core/src/MetadataList/XDSMetadataList.test.tsx@@ -0,0 +1,141 @@+import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {XDSMetadataList} from './XDSMetadataList';+import {XDSMetadataListItem} from './XDSMetadataListItem';++describe('XDSMetadataList', () => {+ it('renders a description list with items', () => {+ render(+ <XDSMetadataList>+ <XDSMetadataListItem label="Name">Alice</XDSMetadataListItem>+ <XDSMetadataListItem label="Role">Engineer</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.getByText('Name')).toBeInTheDocument();+ expect(screen.getByText('Alice')).toBeInTheDocument();+ expect(screen.getByText('Role')).toBeInTheDocument();+ expect(screen.getByText('Engineer')).toBeInTheDocument();+ });++ it('renders a semantic dl element', () => {+ const {container} = render(+ <XDSMetadataList>+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(container.querySelector('dl')).toBeInTheDocument();+ expect(container.querySelector('dt')).toBeInTheDocument();+ expect(container.querySelector('dd')).toBeInTheDocument();+ });++ it('renders a title when provided', () => {+ render(+ <XDSMetadataList title={<h3>Details</h3>}>+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.getByText('Details')).toBeInTheDocument();+ });++ it('supports data-testid', () => {+ render(+ <XDSMetadataList data-testid="my-list">+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.getByTestId('my-list')).toBeInTheDocument();+ });++ it('shows "Show more" button when items exceed maxNumOfItems', () => {+ render(+ <XDSMetadataList maxNumOfItems={2}>+ <XDSMetadataListItem label="A">1</XDSMetadataListItem>+ <XDSMetadataListItem label="B">2</XDSMetadataListItem>+ <XDSMetadataListItem label="C">3</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.getByText('Show more')).toBeInTheDocument();+ // Third item should be hidden+ expect(screen.queryByText('C')).not.toBeInTheDocument();+ });++ it('toggles show more / show less', async () => {+ const user = userEvent.setup();++ render(+ <XDSMetadataList maxNumOfItems={1}>+ <XDSMetadataListItem label="A">1</XDSMetadataListItem>+ <XDSMetadataListItem label="B">2</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.queryByText('B')).not.toBeInTheDocument();++ await user.click(screen.getByText('Show more'));+ expect(screen.getByText('B')).toBeInTheDocument();+ expect(screen.getByText('Show less')).toBeInTheDocument();++ await user.click(screen.getByText('Show less'));+ expect(screen.queryByText('B')).not.toBeInTheDocument();+ });++ it('does not show toggle in horizontal mode even with maxNumOfItems', () => {+ render(+ <XDSMetadataList orientation="horizontal" maxNumOfItems={1}>+ <XDSMetadataListItem label="A">1</XDSMetadataListItem>+ <XDSMetadataListItem label="B">2</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.queryByText('Show more')).not.toBeInTheDocument();+ expect(screen.getByText('A')).toBeInTheDocument();+ expect(screen.getByText('B')).toBeInTheDocument();+ });+});++describe('XDSMetadataListItem', () => {+ it('renders label and children', () => {+ render(+ <XDSMetadataList>+ <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.getByText('Status')).toBeInTheDocument();+ expect(screen.getByText('Active')).toBeInTheDocument();+ });++ it('renders an icon when provided', () => {+ render(+ <XDSMetadataList>+ <XDSMetadataListItem+ label="Info"+ icon={<span data-testid="test-icon">*</span>}>+ Details+ </XDSMetadataListItem>+ </XDSMetadataList>,+ );++ expect(screen.getByTestId('test-icon')).toBeInTheDocument();+ });++ it('renders in stacked mode when label position is top', () => {+ const {container} = render(+ <XDSMetadataList label={{position: 'top'}}>+ <XDSMetadataListItem label="Key">Value</XDSMetadataListItem>+ </XDSMetadataList>,+ );++ // In stacked mode, dt and dd are inside a wrapper div+ const wrapper = container.querySelector('.xds-metadata-list-item');+ expect(wrapper).toBeInTheDocument();+ expect(wrapper?.querySelector('dt')).toBeInTheDocument();+ expect(wrapper?.querySelector('dd')).toBeInTheDocument();+ });+});diff --git a/packages/core/src/MetadataList/XDSMetadataList.tsx b/packages/core/src/MetadataList/XDSMetadataList.tsxnew file mode 100644index 0000000000..1904cbf023--- /dev/null+++ b/packages/core/src/MetadataList/XDSMetadataList.tsx@@ -0,0 +1,296 @@+'use client';++/**+ * @file XDSMetadataList.tsx+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, XDSMetadataListContext+ * @output Exports XDSMetadataList component, XDSMetadataListProps, XDSMetadataListColumns types+ * @position Core implementation; consumed by index.ts, tested by XDSMetadataList.test.tsx+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/MetadataList/MetadataList.doc.mjs+ * - /packages/core/src/MetadataList/XDSMetadataList.test.tsx+ * - /packages/core/src/MetadataList/index.ts+ * - /apps/storybook/stories/MetadataList.stories.tsx+ */++import {Children, useId, useMemo, useState, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ spacingVars,+ colorVars,+ typeScaleVars,+ fontWeightVars,+} from '../theme/tokens.stylex';+import {+ XDSMetadataListContext,+ type XDSMetadataListLabelConfig,+} from './XDSMetadataListContext';+import {xdsClassName, mergeProps} from '../utils';++// =============================================================================+// Types+// =============================================================================++export type XDSMetadataListColumns = 'multi' | 'single' | number;++export interface XDSMetadataListProps {+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLDivElement>;+ /**+ * Metadata list items. Should be XDSMetadataListItem components.+ */+ children: ReactNode;+ /**+ * Column layout mode.+ * - 'single': Items in a single column+ * - 'multi': Auto-fill columns based on available width+ * - number: Fixed number of columns+ * @default 'single'+ */+ columns?: XDSMetadataListColumns;+ /**+ * Label display configuration.+ * - position: 'start' places labels to the left, 'top' stacks labels above content+ * - width: Custom label width (number in px or CSS string)+ *+ * Defaults to `{ position: 'top' }` for multi-column layouts and+ * `{ position: 'start' }` for single-column layouts.+ */+ label?: XDSMetadataListLabelConfig;+ /**+ * Maximum number of items to show before collapsing.+ * When set and items exceed this count, a "Show more" / "Show less"+ * toggle appears.+ */+ maxNumOfItems?: number;+ /**+ * Layout orientation for metadata items.+ * - 'vertical': Items stack vertically (default)+ * - 'horizontal': Items flow horizontally with flex-wrap+ *+ * In horizontal mode, items display with labels stacked above content+ * and wrap to new lines as needed. The following props are ignored:+ * `columns`, `label`, `maxNumOfItems`.+ * @default 'vertical'+ */+ orientation?: 'vertical' | 'horizontal';+ /**+ * Optional title or heading rendered above the list.+ */+ title?: ReactNode;+ /**+ * StyleX styles created via `stylex.create()`.+ */+ xstyle?: StyleXStyles;+ /**+ * CSS class name(s) appended to the root element.+ */+ className?: string;+ /**+ * Inline styles to apply to the root element.+ */+ style?: React.CSSProperties;+ /**+ * Test ID for testing frameworks.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ display: 'flex',+ flexDirection: 'column',+ },+ title: {+ marginBottom: spacingVars['--spacing-3'],+ },+ // dl reset+ dl: {+ margin: 0,+ padding: 0,+ },+ // Vertical orientation — grid layout for label-value pairs+ gridSingle: {+ display: 'grid',+ gridTemplateColumns: 'auto 1fr',+ gap: `${spacingVars['--spacing-2']} ${spacingVars['--spacing-4']}`,+ alignItems: 'baseline',+ },+ gridMulti: {+ display: 'grid',+ gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))',+ gap: spacingVars['--spacing-4'],+ },+ // Stacked labels (position: 'top') within a single-column layout+ gridStackedSingle: {+ display: 'grid',+ gridTemplateColumns: '1fr',+ gap: spacingVars['--spacing-3'],+ },+ gridStackedMulti: {+ display: 'grid',+ gridTemplateColumns: 'repeat(auto-fill, minmax(280px, 1fr))',+ gap: spacingVars['--spacing-4'],+ },+ // Horizontal orientation — flex row with wrapping+ horizontal: {+ display: 'flex',+ flexDirection: 'row',+ flexWrap: 'wrap',+ gap: spacingVars['--spacing-4'],+ },+ // Show more/less button+ toggleButton: {+ appearance: 'none',+ background: 'none',+ border: 'none',+ padding: `${spacingVars['--spacing-2']} 0`,+ cursor: 'pointer',+ color: colorVars['--color-accent'],+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ fontWeight: fontWeightVars['--font-weight-medium'],+ fontFamily: 'inherit',+ textAlign: 'start',+ alignSelf: 'flex-start',+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * A read-only labeled list for displaying key-value metadata.+ *+ * Renders semantic `<dl>` / `<dt>` / `<dd>` elements. Supports multiple+ * column layouts, horizontal orientation, and show more/less collapsing.+ *+ * @example+ * ```+ * <XDSMetadataList columns="multi">+ * <XDSMetadataListItem label="Name">XDSMetadataList</XDSMetadataListItem>+ * <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ * </XDSMetadataList>+ * ```+ */+const LABEL_START: XDSMetadataListLabelConfig = {position: 'start'};+const LABEL_TOP: XDSMetadataListLabelConfig = {position: 'top'};++export function XDSMetadataList({+ children,+ columns = 'single',+ label,+ maxNumOfItems,+ orientation = 'vertical',+ title,+ xstyle,+ className,+ style,+ 'data-testid': testId,+ ref,+}: XDSMetadataListProps) {+ const isMultiColumn =+ columns === 'multi' || (typeof columns === 'number' && columns > 1);+ // Default to 'top' for multi-column and horizontal layouts since side labels+ // don't work well when items are in separate grid cells.+ const labelConfig = label ?? (isMultiColumn ? LABEL_TOP : LABEL_START);+ const [isShowAll, setIsShowAll] = useState(false);+ const contentId = useId();++ const contextValue = useMemo(+ () => ({+ labelConfig: orientation === 'horizontal' ? LABEL_TOP : labelConfig,+ orientation,+ }),+ [labelConfig, orientation],+ );++ const childrenArray = Children.toArray(children);+ const isHorizontal = orientation === 'horizontal';++ // In horizontal mode, ignore maxNumOfItems+ const effectiveMax = isHorizontal ? undefined : maxNumOfItems;+ const isExceedMax =+ effectiveMax != null && childrenArray.length > effectiveMax;+ const visibleChildren =+ isExceedMax && !isShowAll+ ? childrenArray.slice(0, effectiveMax)+ : childrenArray;++ const titleContent =+ title != null ? <div {...stylex.props(styles.title)}>{title}</div> : null;++ // Determine grid style based on columns and label position+ const getGridStyle = () => {+ if (isHorizontal) return styles.horizontal;+ const isStacked = labelConfig.position === 'top';+ if (isStacked) {+ return columns === 'single' || columns === 1+ ? styles.gridStackedSingle+ : styles.gridStackedMulti;+ }+ // Labels on the left+ if (columns === 'single' || columns === 1) {+ return styles.gridSingle;+ }+ return styles.gridMulti;+ };++ // For numeric columns > 1 with side labels, use inline style for dynamic grid+ const dynamicGridStyle =+ !isHorizontal &&+ labelConfig.position === 'start' &&+ typeof columns === 'number' &&+ columns > 1+ ? {gridTemplateColumns: `repeat(${columns}, auto 1fr)`}+ : !isHorizontal &&+ labelConfig.position === 'start' &&+ labelConfig.width != null+ ? {+ gridTemplateColumns: `${typeof labelConfig.width === 'number' ? `${labelConfig.width}px` : labelConfig.width} 1fr`,+ }+ : undefined;++ return (+ <XDSMetadataListContext.Provider value={contextValue}>+ <div+ ref={ref}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('metadata-list', {+ columns: String(columns),+ orientation,+ }),+ stylex.props(styles.root, xstyle),+ className,+ style,+ )}>+ {titleContent}+ <dl+ id={contentId}+ style={dynamicGridStyle}+ {...stylex.props(styles.dl, getGridStyle())}>+ {visibleChildren}+ </dl>+ {isExceedMax && (+ <button+ type="button"+ aria-controls={contentId}+ aria-expanded={isShowAll}+ onClick={() => setIsShowAll(prev => !prev)}+ {...stylex.props(styles.toggleButton)}>+ {isShowAll ? 'Show less' : 'Show more'}+ </button>+ )}+ </div>+ </XDSMetadataListContext.Provider>+ );+}++XDSMetadataList.displayName = 'XDSMetadataList';diff --git a/packages/core/src/MetadataList/XDSMetadataListContext.tsx b/packages/core/src/MetadataList/XDSMetadataListContext.tsxnew file mode 100644index 0000000000..6ba6215123--- /dev/null+++ b/packages/core/src/MetadataList/XDSMetadataListContext.tsx@@ -0,0 +1,23 @@+'use client';++/**+ * @file XDSMetadataListContext.tsx+ * @input Uses React createContext+ * @output Exports XDSMetadataListContext for sharing config between XDSMetadataList and XDSMetadataListItem+ * @position Internal context; consumed by XDSMetadataList.tsx and XDSMetadataListItem.tsx+ */++import {createContext} from 'react';++export interface XDSMetadataListLabelConfig {+ position: 'start' | 'top';+ width?: number | string;+}++export interface XDSMetadataListContextValue {+ labelConfig: XDSMetadataListLabelConfig;+ orientation: 'vertical' | 'horizontal';+}++export const XDSMetadataListContext =+ createContext<XDSMetadataListContextValue | null>(null);diff --git a/packages/core/src/MetadataList/XDSMetadataListItem.tsx b/packages/core/src/MetadataList/XDSMetadataListItem.tsxnew file mode 100644index 0000000000..d4d0fad079--- /dev/null+++ b/packages/core/src/MetadataList/XDSMetadataListItem.tsx@@ -0,0 +1,211 @@+'use client';++/**+ * @file XDSMetadataListItem.tsx+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, XDSMetadataListContext+ * @output Exports XDSMetadataListItem component, XDSMetadataListItemProps type+ * @position Core implementation; consumed by XDSMetadataList, index.ts+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/MetadataList/MetadataList.doc.mjs+ * - /packages/core/src/MetadataList/XDSMetadataList.test.tsx+ * - /packages/core/src/MetadataList/index.ts+ * - /apps/storybook/stories/MetadataList.stories.tsx+ */++import {useContext, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ typeScaleVars,+ fontWeightVars,+} from '../theme/tokens.stylex';+import {XDSMetadataListContext} from './XDSMetadataListContext';+import {xdsClassName, mergeProps} from '../utils';++// =============================================================================+// Types+// =============================================================================++export interface XDSMetadataListItemProps {+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLDivElement>;+ /**+ * Content value for this metadata item.+ */+ children: ReactNode;+ /**+ * Icon rendered before the label text.+ */+ icon?: ReactNode;+ /**+ * Label text for this metadata item.+ */+ label: string;+ /**+ * StyleX styles created via `stylex.create()`.+ */+ xstyle?: StyleXStyles;+ /**+ * CSS class name(s) appended to the root element.+ */+ className?: string;+ /**+ * Inline styles to apply to the root element.+ */+ style?: React.CSSProperties;+ /**+ * Test ID for testing frameworks.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ // Label (dt) — inline (side-by-side with value)+ label: {+ color: colorVars['--color-text-secondary'],+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ fontWeight: fontWeightVars['--font-weight-medium'],+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ margin: 0,+ padding: 0,+ minHeight: 24,+ wordBreak: 'break-word',+ },+ // Value (dd) — inline+ value: {+ color: colorVars['--color-text-primary'],+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ margin: 0,+ padding: 0,+ minHeight: 24,+ wordBreak: 'break-word',+ },+ // Stacked layout wrapper (label on top)+ stackedWrapper: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-0-5'],+ },+ // Stacked label+ stackedLabel: {+ color: colorVars['--color-text-secondary'],+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ fontWeight: fontWeightVars['--font-weight-medium'],+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ margin: 0,+ padding: 0,+ },+ stackedValue: {+ color: colorVars['--color-text-primary'],+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ margin: 0,+ padding: 0,+ wordBreak: 'break-word',+ },+ iconWrapper: {+ display: 'inline-flex',+ alignItems: 'center',+ flexShrink: 0,+ color: colorVars['--color-text-secondary'],+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * A single labeled metadata value within an XDSMetadataList.+ *+ * Renders a `<dt>` / `<dd>` pair. Layout (side-by-side or stacked) is+ * determined by the parent XDSMetadataList's label configuration.+ *+ * @example+ * ```+ * <XDSMetadataListItem label="Status">Active</XDSMetadataListItem>+ * <XDSMetadataListItem label="Created" icon={<CalendarIcon />}>+ * January 1, 2023+ * </XDSMetadataListItem>+ * ```+ */+export function XDSMetadataListItem({+ children,+ icon,+ label,+ xstyle,+ className,+ style,+ 'data-testid': testId,+ ref,+}: XDSMetadataListItemProps) {+ const ctx = useContext(XDSMetadataListContext);+ const labelPosition = ctx?.labelConfig.position ?? 'start';+ const isStacked =+ labelPosition === 'top' || ctx?.orientation === 'horizontal';++ const labelContent = (+ <>+ {icon != null && (+ <span {...stylex.props(styles.iconWrapper)}>{icon}</span>+ )}+ {label}+ </>+ );++ // Stacked layout: label above content, wrapped in a div+ if (isStacked) {+ return (+ <div+ ref={ref}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('metadata-list-item'),+ stylex.props(styles.stackedWrapper, xstyle),+ className,+ style,+ )}>+ <dt {...stylex.props(styles.stackedLabel)}>{labelContent}</dt>+ <dd {...stylex.props(styles.stackedValue)}>{children}</dd>+ </div>+ );+ }++ // Inline layout: dt and dd are direct grid children+ return (+ <>+ <dt+ ref={ref}+ data-testid={testId ? `${testId}-label` : undefined}+ {...mergeProps(+ xdsClassName('metadata-list-item'),+ stylex.props(styles.label, xstyle),+ className,+ style,+ )}>+ {labelContent}+ </dt>+ <dd+ data-testid={testId ? `${testId}-value` : undefined}+ {...stylex.props(styles.value)}>+ {children}+ </dd>+ </>+ );+}++XDSMetadataListItem.displayName = 'XDSMetadataListItem';diff --git a/packages/core/src/MetadataList/index.ts b/packages/core/src/MetadataList/index.tsnew file mode 100644index 0000000000..b42041de07--- /dev/null+++ b/packages/core/src/MetadataList/index.ts@@ -0,0 +1,18 @@+'use client';++/**+ * @file index.ts+ * @input Imports from XDSMetadataList.tsx and XDSMetadataListItem.tsx+ * @output Exports XDSMetadataList, XDSMetadataListItem components and their props/types+ * @position Package entry point for MetadataList+ *+ * SYNC: When modified, update /packages/core/src/MetadataList/MetadataList.doc.mjs+ */++export {XDSMetadataList} from './XDSMetadataList';+export type {+ XDSMetadataListProps,+ XDSMetadataListColumns,+} from './XDSMetadataList';+export {XDSMetadataListItem} from './XDSMetadataListItem';+export type {XDSMetadataListItemProps} from './XDSMetadataListItem';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 42e3147803..82661370f8 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -29,6 +29,7 @@ export * from './Divider';export * from './EmptyState';export * from './Link';export * from './List';+export * from './MetadataList';export * from './NavIcon';export * from './NavItem';export * from './Slider';