Skip to content

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.tsx
new file mode 100644
index 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=&quot;horizontal&quot;, 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=&quot;horizontal&quot;, 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=&quot;horizontal&quot;, 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=&quot;horizontal&quot;, 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=&quot;vertical&quot;, 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=&quot;vertical&quot;, 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=&quot;vertical&quot;, 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=&quot;vertical&quot;, 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.tsx
deleted file mode 100644
index 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.ts
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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';