An open source design system that's fully customizable and agent ready
TypeScript
fix(Card): let a card yield to its flex row or grid track (#6813)
David Petersen1bbbf636b0f0
diff --git a/.changeset/card-yields-to-track.md b/.changeset/card-yields-to-track.mdnew file mode 100644index 0000000000..f1e25edd6c--- /dev/null+++ b/.changeset/card-yields-to-track.md@@ -0,0 +1,16 @@+---+'@astryxdesign/core': patch+---++[fix] Card: yield to a flex row or grid track instead of widening it to the card's content.++A card no longer holds its row or `1fr` grid track at its min-content width,+so a long unbroken value (an ID, a hash) inside a card can no longer push+side-by-side cards past a phone screen. Cards that fit are unchanged. Content+that cannot wrap is clipped at the card edge, as it already was for cards with+an explicit `width`; truncate such values with `Text maxLines={1}` and give wide+content its own scroll region. An explicit `width` is now the card's preferred+width in a row rather than a floor. To hold it, wrap the card in `StackItem` in+a flex row, or set a consumer `minWidth` on the Card in Grid.++@thedjpetersendiff --git a/apps/storybook/stories/Card.stories.tsx b/apps/storybook/stories/Card.stories.tsxindex 42f1936b3e..64126523c8 100644--- a/apps/storybook/stories/Card.stories.tsx+++ b/apps/storybook/stories/Card.stories.tsx@@ -1,5 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+import type {ReactNode} from 'react';import type {Meta, StoryObj} from '@storybook/react';import * as stylex from '@stylexjs/stylex';import {Card} from '@astryxdesign/core/Card';@@ -14,7 +15,8 @@ import {LayoutFooter,} from '@astryxdesign/core/Layout';import {Button} from '@astryxdesign/core/Button';-import {Heading} from '@astryxdesign/core/Text';+import {Heading, Text} from '@astryxdesign/core/Text';+import {Grid} from '@astryxdesign/core/Grid';import {Theme, defineTheme} from '@astryxdesign/core/theme';import {colorVars,@@ -54,6 +56,19 @@ const styles = stylex.create({narrowContainer: {width: 320,},+ frames: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-6'],+ },+ frame: {+ borderWidth: 1,+ borderStyle: 'dashed',+ borderColor: colorVars['--color-border'],+ borderRadius: 8,+ },+ frame320: {width: 320},+ frame390: {width: 390},});const meta: Meta<typeof Card> = {@@ -617,3 +632,110 @@ export const NarrowContainer: Story = {</div>),};++const payouts = [+ {label: 'Payout', amount: '$1,240.00', id: 'po_1Q8ZK4X7M2N5P3R6T9V1W4YB'},+ {label: 'Refund', amount: '-$86.50', id: 're_3NfK9Lm2Qx7Vb4Tz8Rw1Hy6C'},+ {label: 'Adjustment', amount: '$12.00', id: 'adj_7Hq2Wm9Kx4Lz8Vn3Rb6Tf1PD'},+];++function PayoutCard({+ payout,+ truncateId,+}: {+ payout: (typeof payouts)[number];+ truncateId?: boolean;+}) {+ return (+ <Card>+ <VStack gap={1}>+ <Heading level={3}>{payout.label}</Heading>+ <Text hasTabularNumbers>{payout.amount}</Text>+ <Text type="supporting" maxLines={truncateId ? 1 : undefined}>+ {payout.id}+ </Text>+ </VStack>+ </Card>+ );+}++function RowFrame({+ label,+ width,+ children,+}: {+ label: string;+ width?: 320 | 390;+ children: ReactNode;+}) {+ return (+ <div>+ <p {...stylex.props(styles.heading)}>{label}</p>+ <div+ {...stylex.props(+ styles.frame,+ width === 320 && styles.frame320,+ width === 390 && styles.frame390,+ )}>+ {children}+ </div>+ </div>+ );+}++/**+ * Three cards sharing a row in 320px and 390px frames and at full width.+ * Each card shrinks to its HStack share or Grid track instead of widening+ * the row to fit its longest unbroken value, so the row stays inside the+ * frame. A value that cannot wrap is clipped at the card edge (the raw IDs+ * in the first two frames); the Grid frames truncate it with+ * `maxLines={1}`, the recommended form, which shows the full value in a+ * tooltip.+ */+export const InNarrowRow: Story = {+ render: () => (+ <div {...stylex.props(styles.frames)}>+ <RowFrame+ label="HStack, 390px frame, raw IDs (clipped at the card edge)"+ width={390}>+ <HStack gap={3}>+ {payouts.map(payout => (+ <PayoutCard key={payout.id} payout={payout} />+ ))}+ </HStack>+ </RowFrame>+ <RowFrame label="HStack, 320px frame, raw IDs" width={320}>+ <HStack gap={3}>+ {payouts.map(payout => (+ <PayoutCard key={payout.id} payout={payout} />+ ))}+ </HStack>+ </RowFrame>+ <RowFrame+ label="Grid columns={3}, 390px frame, IDs truncated with maxLines={1}"+ width={390}>+ <Grid columns={3} gap={3}>+ {payouts.map(payout => (+ <PayoutCard key={payout.id} payout={payout} truncateId />+ ))}+ </Grid>+ </RowFrame>+ <RowFrame+ label="Grid columns={3}, 320px frame, IDs truncated"+ width={320}>+ <Grid columns={3} gap={3}>+ {payouts.map(payout => (+ <PayoutCard key={payout.id} payout={payout} truncateId />+ ))}+ </Grid>+ </RowFrame>+ <RowFrame label="Grid columns={3}, full width (unchanged)">+ <Grid columns={3} gap={3}>+ {payouts.map(payout => (+ <PayoutCard key={payout.id} payout={payout} truncateId />+ ))}+ </Grid>+ </RowFrame>+ </div>+ ),+};diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex 3f24581bb3..247552e656 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -17,6 +17,7 @@ export const docs = {{guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container; try removing the card and see if the grouping is still clear from whitespace and typography.'},{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},{guidance: true, description: 'Pair a card with Layout when you need a structured header, scrollable content, and footer with actions.'},+ {guidance: true, description: 'Let cards share a row or grid on a phone: a card shrinks to fit its track and clips content that cannot wrap at its edge. Truncate long IDs, hashes, and URLs with Text maxLines={1} (the full value shows in a tooltip), and give wide content its own scroll region: Table scrolls by itself; put code or other wide content in a ScrollableArea.'},{guidance: false, description: 'Default to cards for visual grouping. A heading + Stack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},{guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use Section or heading + stack.'},{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},@@ -32,7 +33,7 @@ export const docs = {{name: 'width',type: 'SizeValue',- description: 'Width of the card (number = pixels, string = used as-is).',+ description: 'Width of the card (number = pixels, string = used as-is). In a flex row or grid track this is the preferred width: the card shrinks below it when the row is narrower. To hold the width in a flex row, wrap the card in StackItem (static by default) and let the row wrap or scroll. In Grid, set a consumer minWidth on the Card and size the track accordingly.',},{name: 'height',@@ -76,6 +77,46 @@ export const docs = {default: "'none'",},],+ examples: [+ {+ label: 'Cards sharing a row on a phone, with long IDs',+ code: `+import {Card} from '@astryxdesign/core/Card';+import {Grid} from '@astryxdesign/core/Grid';+import {VStack} from '@astryxdesign/core/Layout';+import {Heading} from '@astryxdesign/core/Heading';+import {Text} from '@astryxdesign/core/Text';++const payouts = [+ {label: 'Payout', amount: '$1,240.00', id: 'po_1Q8ZK4X7M2N5P3R6T9V1W4YB'},+ {label: 'Refund', amount: '-$86.50', id: 're_3NfK9Lm2Qx7Vb4Tz8Rw1Hy6C'},+ {label: 'Adjustment', amount: '$12.00', id: 'adj_7Hq2Wm9Kx4Lz8Vn3Rb6Tf1PD'},+];++// Each card takes one grid track and shrinks with it, so three cards fit a+// 390px phone without widening the page. The ID cannot wrap, so it truncates+// with maxLines={1} (the full value shows in a tooltip) instead of running+// past the card edge.+function PayoutCards() {+ return (+ <Grid columns={3} gap={3}>+ {payouts.map(payout => (+ <Card key={payout.id}>+ <VStack gap={1}>+ <Heading level={3}>{payout.label}</Heading>+ <Text hasTabularNumbers>{payout.amount}</Text>+ <Text type="supporting" maxLines={1}>+ {payout.id}+ </Text>+ </VStack>+ </Card>+ ))}+ </Grid>+ );+}+`,+ },+ ],playground: {defaults: {children: {@@ -118,6 +159,7 @@ export const docsZh = {{guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container; try removing the card and see if the grouping is still clear from whitespace and typography.'},{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},{guidance: true, description: 'Pair a card with Layout when you need a structured header, scrollable content, and footer with actions.'},+ {guidance: true, description: 'Let cards share a row or grid on a phone: a card shrinks to fit its track and clips content that cannot wrap at its edge. Truncate long IDs, hashes, and URLs with Text maxLines={1} (the full value shows in a tooltip), and give wide content its own scroll region: Table scrolls by itself; put code or other wide content in a ScrollableArea.'},{guidance: false, description: 'Default to cards for visual grouping. A heading + Stack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},{guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use Section or heading + stack.'},{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},@@ -168,6 +210,7 @@ export const docsDense = {{guidance: true, description: 'Spacing + alignment alone create visual grouping. Not everything needs a container; try removing the card; if grouping still reads from whitespace + typography, skip it.'},{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},{guidance: true, description: 'Pair a card w/ Layout when you need a structured header, scrollable content, and footer with actions.'},+ {guidance: true, description: 'Card shrinks to its row/grid track, clips unwrappable content at its edge. Long IDs/hashes/URLs → Text maxLines={1} (tooltip shows full value). Wide content → own scroll region (Table scrolls itself; ScrollableArea otherwise).'},{guidance: false, description: 'Default to cards for grouping. Heading + Stack w/ proper spacing creates hierarchy w/o borders everywhere. Cards are the exception, not the default.'},{guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups are page regions; use Section or heading + stack.'},{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},diff --git a/packages/core/src/Card/Card.test.tsx b/packages/core/src/Card/Card.test.tsxindex 8338725cfc..435b94e3d6 100644--- a/packages/core/src/Card/Card.test.tsx+++ b/packages/core/src/Card/Card.test.tsx@@ -3,6 +3,7 @@import {createRef} from 'react';import {describe, it, expect} from 'vitest';import {render} from '@testing-library/react';+import * as stylex from '@stylexjs/stylex';import {Card} from './Card';import type {CardVariant} from './Card';@@ -12,6 +13,68 @@ describe('Card', () => {expect(getByText('Hello')).toBeInTheDocument();});+ describe('in a flex row or grid track', () => {+ it('yields to its track instead of holding it at its min-content width', () => {+ const {getByTestId} = render(<Card data-testid="card">C</Card>);+ // Without this, `overflow: clip` keeps the automatic minimum size, so a+ // long unbroken value widens the row or a `1fr` track past its parent.+ expect(getComputedStyle(getByTestId('card')).minWidth).toBe('0');+ });++ it('clips rather than scrolls, so it never becomes a scroll container', () => {+ const {getByTestId} = render(<Card data-testid="card">C</Card>);+ const style = getComputedStyle(getByTestId('card'));+ // A scroll container would capture sticky descendants and become an+ // unnamed keyboard tab stop whenever its content overflows.+ expect(style.overflow).toBe('clip');+ expect(style.overflowX).not.toBe('auto');+ });++ it('yields the same way for every variant and elevation', () => {+ const {getByTestId} = render(+ <>+ <Card data-testid="muted" variant="muted" elevation="high">+ C+ </Card>+ <Card data-testid="transparent" variant="transparent">+ C+ </Card>+ </>,+ );+ expect(getComputedStyle(getByTestId('muted')).minWidth).toBe('0');+ expect(getComputedStyle(getByTestId('transparent')).minWidth).toBe('0');+ });++ it('still scrolls a fixed-height card and lets it yield', () => {+ const {getByTestId} = render(+ <Card data-testid="card" height={200}>+ C+ </Card>,+ );+ const style = getComputedStyle(getByTestId('card'));+ expect(style.overflow).toBe('auto');+ expect(style.minWidth).toBe('0');+ });++ it('keeps width as the preferred size and lets a consumer minimum win', () => {+ const overrides = stylex.create({hold: {minWidth: 240}});+ const {getByTestId} = render(+ <>+ <Card data-testid="sized" width={320}>+ C+ </Card>+ <Card data-testid="held" width={320} xstyle={overrides.hold}>+ C+ </Card>+ </>,+ );+ // An explicit width does not become a floor: in a narrow row the card+ // still yields, and a consumer minimum is the way to hold it.+ expect(getComputedStyle(getByTestId('sized')).minWidth).toBe('0');+ expect(getComputedStyle(getByTestId('held')).minWidth).toBe('240px');+ });+ });+it('forwards ref to the rendered element', () => {const ref = createRef<HTMLDivElement>();const {container} = render(<Card ref={ref}>C</Card>);diff --git a/packages/core/src/Card/Card.tsx b/packages/core/src/Card/Card.tsxindex 83f870c8ea..52f4f3f833 100644--- a/packages/core/src/Card/Card.tsx+++ b/packages/core/src/Card/Card.tsx@@ -60,6 +60,16 @@ const styles = stylex.create({card: {'--_card-radius': radiusVars['--radius-container'],borderRadius: 'var(--_card-radius)',+ // A card in a flex row or grid cell yields to its track instead of+ // holding it at the card's min-content width (a long ID or a nowrap row+ // inside used to widen `1fr` tracks and overflow phone rows).+ minWidth: 0,+ // Clip, not scroll: `overflow-x: auto` would make every card a scroll+ // container, so sticky descendants would stick to the card instead of+ // the page, and an overflowing card would become an unnamed keyboard tab+ // stop. Content that cannot wrap is clipped at the card edge; long+ // values truncate (Text maxLines) and wide content brings its own scroll+ // region (Table, ScrollableArea).overflow: 'clip',// Resting elevation is set via --_card-elevation (see elevationStyles).// The shadow list also reads --_card-ring so composing surfaces — e.g.