An open source design system that's fully customizable and agent ready
TypeScript
feat(stack): consolidate HStack/VStack into unified XDSStack (#374)
Cindy Zhangfd8cf43ce580
diff --git a/apps/storybook/stories/Stack.stories.tsx b/apps/storybook/stories/Stack.stories.tsxnew file mode 100644index 0000000000..82f19a4a88--- /dev/null+++ b/apps/storybook/stories/Stack.stories.tsx@@ -0,0 +1,575 @@+import type {Meta, StoryObj} from '@storybook/react';+import * as stylex from '@stylexjs/stylex';+import {XDSStack, XDSStackItem} from '@xds/core/Layout';+import {+ colorVars,+ spacingVars,+ radiusVars,+ typographyVars,+} from '@xds/core/theme/tokens.stylex';++const styles = stylex.create({+ box: {+ backgroundColor: colorVars['--color-blue-background'],+ color: colorVars['--color-blue-text'],+ borderWidth: 1,+ borderStyle: 'solid',+ borderColor: colorVars['--color-blue-border'],+ paddingBlock: spacingVars['--spacing-4'],+ paddingInline: spacingVars['--spacing-6'],+ borderRadius: radiusVars['--radius-element'],+ fontWeight: 500,+ height: '100%',+ boxSizing: 'border-box',+ },+ boxAlt: {+ backgroundColor: colorVars['--color-gray-background'],+ color: colorVars['--color-gray-text'],+ borderColor: colorVars['--color-gray-border'],+ },+ boxGreen: {+ backgroundColor: colorVars['--color-green-background'],+ color: colorVars['--color-green-text'],+ borderColor: colorVars['--color-green-border'],+ },+ boxPurple: {+ backgroundColor: colorVars['--color-purple-background'],+ color: colorVars['--color-purple-text'],+ borderColor: colorVars['--color-purple-border'],+ },+ boxOrange: {+ backgroundColor: colorVars['--color-orange-background'],+ color: colorVars['--color-orange-text'],+ borderColor: colorVars['--color-orange-border'],+ },+ container: {+ backgroundColor: colorVars['--color-wash'],+ },+ containerWidth: {+ width: 300,+ },+ containerWidthMedium: {+ width: 500,+ },+ containerWidthLarge: {+ width: 600,+ },+ containerWidthSmall: {+ width: 150,+ },+ containerHeight: {+ height: 120,+ },+ containerHeightSmall: {+ height: 80,+ },+ containerHeightMedium: {+ height: 150,+ },+ containerHeightLarge: {+ height: 200,+ },+ containerPadding: {+ padding: spacingVars['--spacing-2'],+ },+ sidebarWidth: {+ width: 150,+ },+ storyWrapper: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-6'],+ },+ storyWrapperRow: {+ display: 'flex',+ gap: spacingVars['--spacing-6'],+ },+ heading: {+ margin: `0 0 ${spacingVars['--spacing-2']} 0`,+ fontFamily: typographyVars['--font-body'],+ },+});++// Demo box component for visibility+const Box = ({+ children,+ alt = false,+ green = false,+ purple = false,+ orange = false,+}: {+ children: React.ReactNode;+ alt?: boolean;+ green?: boolean;+ purple?: boolean;+ orange?: boolean;+}) => (+ <div+ {...stylex.props(+ styles.box,+ alt && styles.boxAlt,+ green && styles.boxGreen,+ purple && styles.boxPurple,+ orange && styles.boxOrange,+ )}>+ {children}+ </div>+);++const meta: Meta<typeof XDSStack> = {+ title: 'Layout/XDSStack',+ component: XDSStack,+ tags: ['autodocs'],+ argTypes: {+ direction: {+ control: 'select',+ options: ['horizontal', 'vertical'],+ description: 'Direction of the stack layout',+ },+ gap: {+ control: 'select',+ options: [+ 'space0',+ 'space0.5',+ 'space1',+ 'space2',+ 'space3',+ 'space4',+ 'space5',+ 'space6',+ 'space7',+ ],+ description: 'Spacing token for gap between items',+ },+ hAlign: {+ control: 'select',+ options: [+ 'start',+ 'center',+ 'end',+ 'stretch',+ 'between',+ 'around',+ 'evenly',+ ],+ description:+ 'Horizontal alignment. Main-axis when horizontal, cross-axis when vertical.',+ },+ vAlign: {+ control: 'select',+ options: [+ 'start',+ 'center',+ 'end',+ 'stretch',+ 'between',+ 'around',+ 'evenly',+ ],+ description:+ 'Vertical alignment. Cross-axis when horizontal, main-axis when vertical.',+ },+ wrap: {+ control: 'select',+ options: ['nowrap', 'wrap', 'wrap-reverse'],+ description: 'Flex wrap behavior',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSStack>;++// ============================================================================+// Basic examples+// ============================================================================++export const Default: Story = {+ args: {+ direction: 'vertical',+ gap: 'space2',+ children: null,+ },+ render: args => (+ <XDSStack {...args}>+ <Box>Item 1</Box>+ <Box>Item 2</Box>+ <Box>Item 3</Box>+ </XDSStack>+ ),+};++export const Horizontal: Story = {+ args: {+ direction: 'horizontal',+ gap: 'space2',+ },+ render: args => (+ <XDSStack {...args}>+ <Box>Item 1</Box>+ <Box>Item 2</Box>+ <Box>Item 3</Box>+ </XDSStack>+ ),+};++export const Vertical: Story = {+ args: {+ direction: 'vertical',+ gap: 'space4',+ },+ render: args => (+ <XDSStack {...args}>+ <Box>Item 1</Box>+ <Box>Item 2</Box>+ <Box>Item 3</Box>+ </XDSStack>+ ),+};++// ============================================================================+// Alignment+// ============================================================================++export const HorizontalAlignments: Story = {+ render: () => (+ <div {...stylex.props(styles.storyWrapper)}>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="horizontal", vAlign: start+ </h4>+ <XDSStack+ direction="horizontal"+ gap="space2"+ vAlign="start"+ xstyle={[styles.container, styles.containerHeightSmall]}>+ <Box>A</Box>+ <Box>+ B<br />B+ </Box>+ <Box>C</Box>+ </XDSStack>+ </div>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="horizontal", vAlign: center+ </h4>+ <XDSStack+ direction="horizontal"+ gap="space2"+ vAlign="center"+ xstyle={[styles.container, styles.containerHeightSmall]}>+ <Box>A</Box>+ <Box>+ B<br />B+ </Box>+ <Box>C</Box>+ </XDSStack>+ </div>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="horizontal", vAlign: end+ </h4>+ <XDSStack+ direction="horizontal"+ gap="space2"+ vAlign="end"+ xstyle={[styles.container, styles.containerHeightSmall]}>+ <Box>A</Box>+ <Box>+ B<br />B+ </Box>+ <Box>C</Box>+ </XDSStack>+ </div>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="horizontal", vAlign: stretch (default)+ </h4>+ <XDSStack+ direction="horizontal"+ gap="space2"+ vAlign="stretch"+ xstyle={[styles.container, styles.containerHeightSmall]}>+ <Box>A</Box>+ <Box>+ B<br />B+ </Box>+ <Box>C</Box>+ </XDSStack>+ </div>+ </div>+ ),+};++export const VerticalAlignments: Story = {+ render: () => (+ <div {...stylex.props(styles.storyWrapperRow)}>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="vertical", hAlign: start+ </h4>+ <XDSStack+ direction="vertical"+ gap="space2"+ hAlign="start"+ xstyle={[+ styles.container,+ styles.containerWidthSmall,+ styles.containerPadding,+ ]}>+ <Box>A</Box>+ <Box>BB</Box>+ <Box>CCC</Box>+ </XDSStack>+ </div>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="vertical", hAlign: center+ </h4>+ <XDSStack+ direction="vertical"+ gap="space2"+ hAlign="center"+ xstyle={[+ styles.container,+ styles.containerWidthSmall,+ styles.containerPadding,+ ]}>+ <Box>A</Box>+ <Box>BB</Box>+ <Box>CCC</Box>+ </XDSStack>+ </div>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="vertical", hAlign: end+ </h4>+ <XDSStack+ direction="vertical"+ gap="space2"+ hAlign="end"+ xstyle={[+ styles.container,+ styles.containerWidthSmall,+ styles.containerPadding,+ ]}>+ <Box>A</Box>+ <Box>BB</Box>+ <Box>CCC</Box>+ </XDSStack>+ </div>+ <div>+ <h4 {...stylex.props(styles.heading)}>+ direction="vertical", hAlign: stretch+ </h4>+ <XDSStack+ direction="vertical"+ gap="space2"+ hAlign="stretch"+ xstyle={[+ styles.container,+ styles.containerWidthSmall,+ styles.containerPadding,+ ]}>+ <Box>A</Box>+ <Box>BB</Box>+ <Box>CCC</Box>+ </XDSStack>+ </div>+ </div>+ ),+};++// ============================================================================+// Wrapping+// ============================================================================++export const Wrapping: Story = {+ args: {+ direction: 'horizontal',+ gap: 'space2',+ wrap: 'wrap',+ },+ render: args => (+ <XDSStack+ {...args}+ xstyle={[+ styles.container,+ styles.containerWidth,+ styles.containerPadding,+ ]}>+ <Box>Item 1</Box>+ <Box>Item 2</Box>+ <Box>Item 3</Box>+ <Box>Item 4</Box>+ <Box>Item 5</Box>+ </XDSStack>+ ),+};++// ============================================================================+// XDSStackItem examples (merged from StackItem stories)+// ============================================================================++export const StackItemFillSize: Story = {+ render: () => (+ <XDSStack+ direction="horizontal"+ gap="space2"+ xstyle={[+ styles.container,+ styles.containerWidthMedium,+ styles.containerPadding,+ ]}>+ <XDSStackItem size="static">+ <Box alt>Static</Box>+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Box>Fill (grows to fill remaining space)</Box>+ </XDSStackItem>+ <XDSStackItem size="static">+ <Box alt>Static</Box>+ </XDSStackItem>+ </XDSStack>+ ),+};++export const StackItemEqualFill: Story = {+ render: () => (+ <div>+ <h4 {...stylex.props(styles.heading)}>Equal Fill (1:1:1)</h4>+ <XDSStack+ direction="horizontal"+ gap="space2"+ xstyle={[+ styles.container,+ styles.containerWidthMedium,+ styles.containerPadding,+ ]}>+ <XDSStackItem size="fill">+ <Box>fill</Box>+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Box green>fill</Box>+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Box purple>fill</Box>+ </XDSStackItem>+ </XDSStack>+ </div>+ ),+};++export const StackItemCrossAlignSelf: Story = {+ render: () => (+ <XDSStack+ direction="horizontal"+ gap="space2"+ xstyle={[+ styles.container,+ styles.containerHeightMedium,+ styles.containerPadding,+ ]}>+ <XDSStackItem crossAlignSelf="start">+ <Box>start</Box>+ </XDSStackItem>+ <XDSStackItem crossAlignSelf="center">+ <Box green>center</Box>+ </XDSStackItem>+ <XDSStackItem crossAlignSelf="end">+ <Box purple>end</Box>+ </XDSStackItem>+ <XDSStackItem crossAlignSelf="stretch">+ <Box orange>stretch</Box>+ </XDSStackItem>+ </XDSStack>+ ),+};++// ============================================================================+// Common layout patterns+// ============================================================================++export const HeaderLayout: Story = {+ render: () => (+ <XDSStack+ direction="horizontal"+ gap="space2"+ xstyle={[+ styles.container,+ styles.containerWidthLarge,+ styles.containerPadding,+ ]}>+ <XDSStackItem size="static">+ <Box alt>Logo</Box>+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Box>Navigation</Box>+ </XDSStackItem>+ <XDSStackItem size="static">+ <Box alt>Actions</Box>+ </XDSStackItem>+ </XDSStack>+ ),+};++export const SidebarLayout: Story = {+ render: () => (+ <XDSStack+ direction="horizontal"+ gap="space2"+ xstyle={[+ styles.container,+ styles.containerWidthLarge,+ styles.containerHeightLarge,+ styles.containerPadding,+ ]}>+ <XDSStackItem size="static" xstyle={styles.sidebarWidth}>+ <Box alt>Sidebar</Box>+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Box>Main Content</Box>+ </XDSStackItem>+ </XDSStack>+ ),+};++export const PageLayout: Story = {+ render: () => (+ <XDSStack+ direction="vertical"+ gap="space2"+ xstyle={styles.containerWidthLarge}>+ <XDSStack+ direction="horizontal"+ gap="space2"+ xstyle={[styles.container, styles.containerPadding]}>+ <XDSStackItem size="static">+ <Box alt>Logo</Box>+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Box>Navigation</Box>+ </XDSStackItem>+ <XDSStackItem size="static">+ <Box alt>Actions</Box>+ </XDSStackItem>+ </XDSStack>+ <XDSStack+ direction="horizontal"+ gap="space2"+ xstyle={[+ styles.container,+ styles.containerHeightLarge,+ styles.containerPadding,+ ]}>+ <XDSStackItem size="static" xstyle={styles.sidebarWidth}>+ <Box alt>Sidebar</Box>+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Box>Main Content</Box>+ </XDSStackItem>+ </XDSStack>+ </XDSStack>+ ),+};diff --git a/apps/storybook/stories/StackItem.stories.tsx b/apps/storybook/stories/StackItem.stories.tsxdeleted file mode 100644index 21fbb68ec3..0000000000--- a/apps/storybook/stories/StackItem.stories.tsx+++ /dev/null@@ -1,287 +0,0 @@-import type {Meta, StoryObj} from '@storybook/react';-import * as stylex from '@stylexjs/stylex';-import {XDSHStack, XDSVStack, XDSStackItem} from '@xds/core/Layout';-import {- colorVars,- spacingVars,- radiusVars,- typographyVars,-} from '@xds/core/theme/tokens.stylex';--const styles = stylex.create({- box: {- backgroundColor: colorVars['--color-blue-background'],- color: colorVars['--color-blue-text'],- borderWidth: 1,- borderStyle: 'solid',- borderColor: colorVars['--color-blue-border'],- paddingBlock: spacingVars['--spacing-4'],- paddingInline: spacingVars['--spacing-6'],- borderRadius: radiusVars['--radius-element'],- fontWeight: 500,- height: '100%',- boxSizing: 'border-box',- },- boxAlt: {- backgroundColor: colorVars['--color-gray-background'],- color: colorVars['--color-gray-text'],- borderColor: colorVars['--color-gray-border'],- },- boxGreen: {- backgroundColor: colorVars['--color-green-background'],- color: colorVars['--color-green-text'],- borderColor: colorVars['--color-green-border'],- },- boxPurple: {- backgroundColor: colorVars['--color-purple-background'],- color: colorVars['--color-purple-text'],- borderColor: colorVars['--color-purple-border'],- },- boxOrange: {- backgroundColor: colorVars['--color-orange-background'],- color: colorVars['--color-orange-text'],- borderColor: colorVars['--color-orange-border'],- },- container: {- backgroundColor: colorVars['--color-wash'],- },- containerWidth: {- width: 500,- },- containerWidthLarge: {- width: 600,- },- containerHeight: {- height: 150,- },- containerHeightLarge: {- height: 200,- },- containerPadding: {- padding: spacingVars['--spacing-2'],- },- sidebarWidth: {- width: 150,- },- storyWrapper: {- display: 'flex',- flexDirection: 'column',- gap: spacingVars['--spacing-6'],- },- heading: {- margin: `0 0 ${spacingVars['--spacing-2']} 0`,- fontFamily: typographyVars['--font-body'],- },-});--// Demo box component for visibility-const Box = ({- children,- alt = false,- green = false,- purple = false,- orange = false,-}: {- children: React.ReactNode;- alt?: boolean;- green?: boolean;- purple?: boolean;- orange?: boolean;-}) => (- <div- {...stylex.props(- styles.box,- alt && styles.boxAlt,- green && styles.boxGreen,- purple && styles.boxPurple,- orange && styles.boxOrange,- )}>- {children}- </div>-);--const meta: Meta<typeof XDSStackItem> = {- title: 'Layout/XDSStackItem',- component: XDSStackItem,- tags: ['autodocs'],- argTypes: {- size: {- control: 'select',- options: ['static', 'fill'],- description: 'Size behavior within the stack',- },- crossAlignSelf: {- control: 'select',- options: ['start', 'center', 'end', 'stretch'],- description: 'Override cross-axis alignment for this item',- },- element: {- control: 'select',- options: ['div', 'section', 'article', 'aside', 'span'],- description: 'HTML element to render',- },- },-};--export default meta;-type Story = StoryObj<typeof XDSStackItem>;--export const Default: Story = {- args: {- size: 'static',- children: null,- },- render: args => (- <XDSHStack- gap="space2"- xstyle={[- styles.container,- styles.containerWidth,- styles.containerPadding,- ]}>- <XDSStackItem {...args}>- <Box>Stack Item</Box>- </XDSStackItem>- <Box alt>Other Item</Box>- </XDSHStack>- ),-};--export const FillSize: Story = {- render: () => (- <XDSHStack- gap="space2"- xstyle={[- styles.container,- styles.containerWidth,- styles.containerPadding,- ]}>- <XDSStackItem size="static">- <Box alt>Static</Box>- </XDSStackItem>- <XDSStackItem size="fill">- <Box>Fill (grows to fill remaining space)</Box>- </XDSStackItem>- <XDSStackItem size="static">- <Box alt>Static</Box>- </XDSStackItem>- </XDSHStack>- ),-};--export const EqualFill: Story = {- render: () => (- <div>- <h4 {...stylex.props(styles.heading)}>Equal Fill (1:1:1)</h4>- <XDSHStack- gap="space2"- xstyle={[- styles.container,- styles.containerWidth,- styles.containerPadding,- ]}>- <XDSStackItem size="fill">- <Box>fill</Box>- </XDSStackItem>- <XDSStackItem size="fill">- <Box green>fill</Box>- </XDSStackItem>- <XDSStackItem size="fill">- <Box purple>fill</Box>- </XDSStackItem>- </XDSHStack>- </div>- ),-};--export const CrossAlignSelf: Story = {- render: () => (- <XDSHStack- gap="space2"- xstyle={[- styles.container,- styles.containerHeight,- styles.containerPadding,- ]}>- <XDSStackItem crossAlignSelf="start">- <Box>start</Box>- </XDSStackItem>- <XDSStackItem crossAlignSelf="center">- <Box green>center</Box>- </XDSStackItem>- <XDSStackItem crossAlignSelf="end">- <Box purple>end</Box>- </XDSStackItem>- <XDSStackItem crossAlignSelf="stretch">- <Box orange>stretch</Box>- </XDSStackItem>- </XDSHStack>- ),-};--export const PolymorphicElement: Story = {- render: () => (- <XDSHStack- gap="space2"- xstyle={[- styles.container,- styles.containerWidth,- styles.containerPadding,- ]}>- <XDSStackItem element="section" size="fill">- <Box>section element</Box>- </XDSStackItem>- <XDSStackItem element="article" size="fill">- <Box green>article element</Box>- </XDSStackItem>- <XDSStackItem element="aside" size="static">- <Box purple>aside element</Box>- </XDSStackItem>- </XDSHStack>- ),-};--export const CommonLayoutPattern: Story = {- render: () => (- <XDSVStack gap="space4">- <div>- <h4 {...stylex.props(styles.heading)}>Header Layout</h4>- <XDSHStack- gap="space2"- xstyle={[- styles.container,- styles.containerWidthLarge,- styles.containerPadding,- ]}>- <XDSStackItem size="static">- <Box alt>Logo</Box>- </XDSStackItem>- <XDSStackItem size="fill">- <Box>Navigation</Box>- </XDSStackItem>- <XDSStackItem size="static">- <Box alt>Actions</Box>- </XDSStackItem>- </XDSHStack>- </div>- <div>- <h4 {...stylex.props(styles.heading)}>Sidebar Layout</h4>- <XDSHStack- gap="space2"- xstyle={[- styles.container,- styles.containerWidthLarge,- styles.containerHeightLarge,- styles.containerPadding,- ]}>- <XDSStackItem size="static" xstyle={styles.sidebarWidth}>- <Box alt>Sidebar</Box>- </XDSStackItem>- <XDSStackItem size="fill">- <Box>Main Content</Box>- </XDSStackItem>- </XDSHStack>- </div>- </XDSVStack>- ),-};diff --git a/packages/core/src/Layout/index.ts b/packages/core/src/Layout/index.tsindex e26a7e49b8..f5c791585a 100644--- a/packages/core/src/Layout/index.ts+++ b/packages/core/src/Layout/index.ts@@ -30,8 +30,14 @@ export type {} from '../Stack/stackItem.stylex';// Stack components (re-exported from Stack module)-export {XDSHStack, XDSVStack, XDSStackItem} from '../Stack';-export type {XDSHStackProps, XDSVStackProps, XDSStackItemProps} from '../Stack';+export {XDSStack, XDSHStack, XDSVStack, XDSStackItem} from '../Stack';+export type {+ XDSStackProps,+ StackAlignment,+ XDSHStackProps,+ XDSVStackProps,+ XDSStackItemProps,+} from '../Stack';// Container components (re-exported from their own modules)export {XDSCard} from '../Card';diff --git a/packages/core/src/Stack/XDSHStack.tsx b/packages/core/src/Stack/XDSHStack.tsxindex 306e9df311..107c22f09b 100644--- a/packages/core/src/Stack/XDSHStack.tsx+++ b/packages/core/src/Stack/XDSHStack.tsx@@ -1,8 +1,8 @@/*** @file XDSHStack.tsx- * @input Uses React forwardRef, ElementType, stack utility- * @output Exports XDSHStack polymorphic component and XDSHStackProps- * @position Layout/Stack component; uses stack.stylex.ts+ * @input Uses XDSStack component+ * @output Exports XDSHStack as a thin wrapper around XDSStack+ * @position Layout/Stack component; wraps XDSStack with direction='horizontal'** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Layout/Stack/README.md@@ -10,27 +10,13 @@* - /apps/storybook/stories/HStack.stories.tsx*/-import {- forwardRef,- createElement,- type ElementType,- type HTMLAttributes,- type ReactNode,- type Ref,-} from 'react';-import * as stylex from '@stylexjs/stylex';-import type {StyleXStyles} from '@stylexjs/stylex';-import {- stack,- type StackCrossAlignment,- type StackMainAlignment,- type StackWrap,- type SpacingScale,-} from './stack.stylex';+import {forwardRef} from 'react';+import {XDSStack, type XDSStackProps} from './XDSStack';+import type {StackCrossAlignment, StackMainAlignment} from './stack.stylex';export interface XDSHStackProps extends Omit<- HTMLAttributes<HTMLElement>,- 'style' | 'className'+ XDSStackProps,+ 'direction' | 'hAlign' | 'vAlign'> {/*** Horizontal alignment of items (main-axis for horizontal stack).@@ -48,83 +34,25 @@ export interface XDSHStackProps extends Omit<* @default 'stretch'*/vAlign?: StackCrossAlignment;-- /**- * Spacing between items using theme spacing tokens.- * Use token names: 'space0', 'space1', 'space2', 'space3', 'space4', 'space5', 'space6', 'space7'- */- gap?: SpacingScale;-- /**- * Whether items should wrap.- * - `nowrap`: Items stay on one line (default)- * - `wrap`: Items wrap to next line- * - `wrap-reverse`: Items wrap to previous line- * @default 'nowrap'- */- wrap?: StackWrap;-- /**- * The element type to render.- * @default 'div'- */- element?: ElementType;-- /**- * StyleX styles to apply to the stack.- */- xstyle?: StyleXStyles;-- /**- * Content to render inside the stack.- */- children?: ReactNode;}/*** Horizontal stack component for arranging items left-to-right.*- * Uses the stack utility internally with `direction: 'horizontal'`.- * The `vAlign` prop controls vertical alignment of items.- * Supports polymorphic rendering via the `element` prop.+ * @deprecated Use `XDSStack` with `direction="horizontal"` instead.** @example* ```tsx- * <XDSHStack gap="space2">- * <Item />- * <Item />- * </XDSHStack>- * <XDSHStack gap="space4" vAlign="center">- * <Item />- * <Item />- * </XDSHStack>+ * // Before+ * <XDSHStack gap="space2">...</XDSHStack>+ *+ * // After+ * <XDSStack direction="horizontal" gap="space2">...</XDSStack>* ```*/export const XDSHStack = forwardRef<HTMLElement, XDSHStackProps>(- function XDSHStack(- {hAlign, vAlign, gap, wrap, element = 'div', xstyle, children, ...props},- ref,- ) {- const stylexProps = stylex.props(- ...stack({- direction: 'horizontal',- crossAlign: vAlign,- mainAlign: hAlign,- gap,- wrap,- }),- xstyle,- );-- return createElement(- element,- {- ref: ref as Ref<Element>,- ...stylexProps,- ...props,- },- children,- );+ function XDSHStack(props, ref) {+ return <XDSStack {...props} direction="horizontal" ref={ref} />;},);diff --git a/packages/core/src/Stack/XDSStack.test.tsx b/packages/core/src/Stack/XDSStack.test.tsxnew file mode 100644index 0000000000..ebd356737c--- /dev/null+++ b/packages/core/src/Stack/XDSStack.test.tsx@@ -0,0 +1,179 @@+/**+ * @file XDSStack.test.tsx+ * @input Uses vitest, @testing-library/react, XDSStack component+ * @output Unit tests for XDSStack component behavior+ * @position Testing; validates XDSStack.tsx implementation+ *+ * SYNC: When XDSStack.tsx changes, update tests to match new behavior+ */++import {describe, it, expect, vi} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSStack} from './XDSStack';++describe('XDSStack', () => {+ it('renders children correctly', () => {+ render(+ <XDSStack direction="vertical">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSStack>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ expect(screen.getByText('Item 2')).toBeInTheDocument();+ });++ it('renders as div by default', () => {+ render(+ <XDSStack direction="vertical" data-testid="stack">+ Content+ </XDSStack>,+ );+ const element = screen.getByTestId('stack');+ expect(element.tagName).toBe('DIV');+ });++ it('renders with horizontal direction', () => {+ render(+ <XDSStack direction="horizontal" data-testid="stack">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSStack>,+ );+ expect(screen.getByTestId('stack')).toBeInTheDocument();+ });++ it('renders with vertical direction', () => {+ render(+ <XDSStack direction="vertical" data-testid="stack">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSStack>,+ );+ expect(screen.getByTestId('stack')).toBeInTheDocument();+ });++ it('renders with polymorphic element prop', () => {+ render(+ <XDSStack direction="vertical" element="nav" data-testid="stack">+ Content+ </XDSStack>,+ );+ const element = screen.getByTestId('stack');+ expect(element.tagName).toBe('NAV');+ });++ it('renders with polymorphic element as section', () => {+ render(+ <XDSStack direction="vertical" element="section" data-testid="stack">+ Content+ </XDSStack>,+ );+ const element = screen.getByTestId('stack');+ expect(element.tagName).toBe('SECTION');+ });++ it('renders with gap prop', () => {+ render(+ <XDSStack direction="vertical" gap="space4">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSStack>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ });++ it('renders with hAlign prop', () => {+ render(+ <XDSStack direction="vertical" hAlign="center">+ <div>Item 1</div>+ </XDSStack>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ });++ it('renders with vAlign prop', () => {+ render(+ <XDSStack direction="vertical" vAlign="center">+ <div>Item 1</div>+ </XDSStack>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ });++ it('renders with wrap prop', () => {+ render(+ <XDSStack direction="vertical" wrap="wrap">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSStack>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ });++ it('renders horizontal with hAlign and vAlign', () => {+ render(+ <XDSStack direction="horizontal" hAlign="between" vAlign="center">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSStack>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ expect(screen.getByText('Item 2')).toBeInTheDocument();+ });++ it('renders vertical with hAlign and vAlign', () => {+ render(+ <XDSStack direction="vertical" hAlign="center" vAlign="between">+ <div>Item 1</div>+ <div>Item 2</div>+ </XDSStack>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ expect(screen.getByText('Item 2')).toBeInTheDocument();+ });++ it('forwards ref correctly', () => {+ const ref = vi.fn();+ render(+ <XDSStack direction="vertical" ref={ref}>+ <div>Test</div>+ </XDSStack>,+ );+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));+ });++ it('forwards ref with polymorphic element', () => {+ const ref = vi.fn();+ render(+ <XDSStack direction="vertical" element="section" ref={ref}>+ <div>Test</div>+ </XDSStack>,+ );+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));+ });++ it('passes through additional props', () => {+ render(+ <XDSStack+ direction="vertical"+ data-testid="stack"+ aria-label="Stack container">+ <div>Item</div>+ </XDSStack>,+ );+ const element = screen.getByTestId('stack');+ expect(element).toHaveAttribute('aria-label', 'Stack container');+ });++ it('passes through event handlers', () => {+ const onClick = vi.fn();+ render(+ <XDSStack direction="vertical" data-testid="stack" onClick={onClick}>+ <div>Item</div>+ </XDSStack>,+ );+ screen.getByTestId('stack').click();+ expect(onClick).toHaveBeenCalledTimes(1);+ });+});diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsxnew file mode 100644index 0000000000..2c09a95225--- /dev/null+++ b/packages/core/src/Stack/XDSStack.tsx@@ -0,0 +1,179 @@+/**+ * @file XDSStack.tsx+ * @input Uses React forwardRef, ElementType, stack utility+ * @output Exports XDSStack polymorphic component and XDSStackProps+ * @position Layout/Stack component; uses stack.stylex.ts+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Layout/Stack/README.md+ * - /packages/core/src/Layout/Stack/XDSStack.test.tsx+ * - /apps/storybook/stories/Stack.stories.tsx+ */++import {+ forwardRef,+ createElement,+ type ElementType,+ type HTMLAttributes,+ type ReactNode,+ type Ref,+} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ stack,+ type StackCrossAlignment,+ type StackDirection,+ type StackMainAlignment,+ type StackWrap,+ type SpacingScale,+} from './stack.stylex';++/**+ * Alignment values accepted by XDSStack.+ *+ * The full union of main-axis and cross-axis alignment values.+ * Which values are valid depends on direction and axis:+ * - Main axis (hAlign for horizontal, vAlign for vertical):+ * `'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'`+ * - Cross axis (vAlign for horizontal, hAlign for vertical):+ * `'start' | 'center' | 'end' | 'stretch'`+ */+export type StackAlignment = StackMainAlignment | StackCrossAlignment;++export interface XDSStackProps extends Omit<+ HTMLAttributes<HTMLElement>,+ 'style' | 'className'+> {+ /**+ * Direction of the stack layout.+ * - `horizontal`: Items flow left-to-right (like XDSHStack)+ * - `vertical`: Items flow top-to-bottom (like XDSVStack)+ */+ direction: StackDirection;++ /**+ * Horizontal alignment of items.+ * - When `direction='horizontal'`: controls main-axis (justify-content).+ * Accepts: `'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'`+ * - When `direction='vertical'`: controls cross-axis (align-items).+ * Accepts: `'start' | 'center' | 'end' | 'stretch'`+ */+ hAlign?: StackAlignment;++ /**+ * Vertical alignment of items.+ * - When `direction='horizontal'`: controls cross-axis (align-items).+ * Accepts: `'start' | 'center' | 'end' | 'stretch'`+ * - When `direction='vertical'`: controls main-axis (justify-content).+ * Accepts: `'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'`+ */+ vAlign?: StackAlignment;++ /**+ * Spacing between items using theme spacing tokens.+ * Use token names: 'space0', 'space1', 'space2', 'space3', 'space4', 'space5', 'space6', 'space7'+ */+ gap?: SpacingScale;++ /**+ * Whether items should wrap.+ * - `nowrap`: Items stay on one line (default)+ * - `wrap`: Items wrap to next line+ * - `wrap-reverse`: Items wrap to previous line+ * @default 'nowrap'+ */+ wrap?: StackWrap;++ /**+ * The element type to render.+ * @default 'div'+ */+ element?: ElementType;++ /**+ * StyleX styles to apply to the stack.+ */+ xstyle?: StyleXStyles;++ /**+ * Content to render inside the stack.+ */+ children?: ReactNode;+}++/**+ * Unified stack component for arranging items in a horizontal or vertical layout.+ *+ * Replaces `XDSHStack` and `XDSVStack` with a single component that accepts+ * a required `direction` prop so the layout intent is always explicit.+ *+ * The `hAlign` and `vAlign` props automatically map to the correct CSS axis+ * based on the direction:+ * - `direction='horizontal'`: hAlign → justify-content, vAlign → align-items+ * - `direction='vertical'`: hAlign → align-items, vAlign → justify-content+ *+ * @example+ * ```tsx+ * // Vertical stack+ * <XDSStack direction="vertical" gap="space2">+ * <Item />+ * <Item />+ * </XDSStack>+ *+ * // Horizontal stack+ * <XDSStack direction="horizontal" gap="space4" vAlign="center">+ * <Item />+ * <Item />+ * </XDSStack>+ * ```+ */+export const XDSStack = forwardRef<HTMLElement, XDSStackProps>(+ function XDSStack(+ {+ direction,+ hAlign,+ vAlign,+ gap,+ wrap,+ element = 'div',+ xstyle,+ children,+ ...props+ },+ ref,+ ) {+ // Map hAlign/vAlign to mainAlign/crossAlign based on direction+ const mainAlign =+ direction === 'horizontal'+ ? (hAlign as StackMainAlignment | undefined)+ : (vAlign as StackMainAlignment | undefined);+ const crossAlign =+ direction === 'horizontal'+ ? (vAlign as StackCrossAlignment | undefined)+ : (hAlign as StackCrossAlignment | undefined);++ const stylexProps = stylex.props(+ ...stack({+ direction,+ crossAlign,+ mainAlign,+ gap,+ wrap,+ }),+ xstyle,+ );++ return createElement(+ element,+ {+ ref: ref as Ref<Element>,+ ...stylexProps,+ ...props,+ },+ children,+ );+ },+);++XDSStack.displayName = 'XDSStack';diff --git a/packages/core/src/Stack/XDSVStack.tsx b/packages/core/src/Stack/XDSVStack.tsxindex 4b4121152e..889eccd71e 100644--- a/packages/core/src/Stack/XDSVStack.tsx+++ b/packages/core/src/Stack/XDSVStack.tsx@@ -1,8 +1,8 @@/*** @file XDSVStack.tsx- * @input Uses React forwardRef, ElementType, stack utility- * @output Exports XDSVStack polymorphic component and XDSVStackProps- * @position Layout/Stack component; uses stack.stylex.ts+ * @input Uses XDSStack component+ * @output Exports XDSVStack as a thin wrapper around XDSStack+ * @position Layout/Stack component; wraps XDSStack with direction='vertical'** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Layout/Stack/README.md@@ -10,27 +10,13 @@* - /apps/storybook/stories/VStack.stories.tsx*/-import {- forwardRef,- createElement,- type ElementType,- type HTMLAttributes,- type ReactNode,- type Ref,-} from 'react';-import * as stylex from '@stylexjs/stylex';-import type {StyleXStyles} from '@stylexjs/stylex';-import {- stack,- type StackCrossAlignment,- type StackMainAlignment,- type StackWrap,- type SpacingScale,-} from './stack.stylex';+import {forwardRef} from 'react';+import {XDSStack, type XDSStackProps} from './XDSStack';+import type {StackCrossAlignment, StackMainAlignment} from './stack.stylex';export interface XDSVStackProps extends Omit<- HTMLAttributes<HTMLElement>,- 'style' | 'className'+ XDSStackProps,+ 'direction' | 'hAlign' | 'vAlign'> {/*** Horizontal alignment of items (cross-axis for vertical stack).@@ -48,83 +34,25 @@ export interface XDSVStackProps extends Omit<* - `evenly`: Even space distribution*/vAlign?: StackMainAlignment;-- /**- * Spacing between items using theme spacing tokens.- * Use token names: 'space0', 'space1', 'space2', 'space3', 'space4', 'space5', 'space6', 'space7'- */- gap?: SpacingScale;-- /**- * Whether items should wrap.- * - `nowrap`: Items stay on one line (default)- * - `wrap`: Items wrap to next line- * - `wrap-reverse`: Items wrap to previous line- * @default 'nowrap'- */- wrap?: StackWrap;-- /**- * The element type to render.- * @default 'div'- */- element?: ElementType;-- /**- * StyleX styles to apply to the stack.- */- xstyle?: StyleXStyles;-- /**- * Content to render inside the stack.- */- children?: ReactNode;}/*** Vertical stack component for arranging items top-to-bottom.*- * Uses the stack utility internally with `direction: 'vertical'`.- * The `hAlign` prop controls horizontal alignment of items.- * Supports polymorphic rendering via the `element` prop.+ * @deprecated Use `XDSStack` with `direction="vertical"` (or omit direction) instead.** @example* ```tsx- * <XDSVStack gap="space2">- * <Item />- * <Item />- * </XDSVStack>- * <XDSVStack gap="space4" hAlign="center">- * <Item />- * <Item />- * </XDSVStack>+ * // Before+ * <XDSVStack gap="space2">...</XDSVStack>+ *+ * // After+ * <XDSStack gap="space2">...</XDSStack>* ```*/export const XDSVStack = forwardRef<HTMLElement, XDSVStackProps>(- function XDSVStack(- {hAlign, vAlign, gap, wrap, element = 'div', xstyle, children, ...props},- ref,- ) {- const stylexProps = stylex.props(- ...stack({- direction: 'vertical',- crossAlign: hAlign,- mainAlign: vAlign,- gap,- wrap,- }),- xstyle,- );-- return createElement(- element,- {- ref: ref as Ref<Element>,- ...stylexProps,- ...props,- },- children,- );+ function XDSVStack(props, ref) {+ return <XDSStack {...props} direction="vertical" ref={ref} />;},);diff --git a/packages/core/src/Stack/index.ts b/packages/core/src/Stack/index.tsindex 133307cb77..8d671f7803 100644--- a/packages/core/src/Stack/index.ts+++ b/packages/core/src/Stack/index.ts@@ -1,13 +1,17 @@/*** @file index.ts* @input Imports stack components- * @output Exports XDSHStack, XDSVStack, XDSStackItem components+ * @output Exports XDSStack, XDSHStack, XDSVStack, XDSStackItem components* @position Entry point for Layout/Stack** SYNC: When modified, update /packages/core/src/Layout/README.md*/-// Components+// Unified stack component+export {XDSStack} from './XDSStack';+export type {XDSStackProps, StackAlignment} from './XDSStack';++// Legacy wrappers (deprecated — use XDSStack instead)export {XDSHStack} from './XDSHStack';export type {XDSHStackProps} from './XDSHStack';