Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Stack): add align/justify aliases on HStack, VStack, and Stack (#1703)

Cindy Zhang8b5efebae875
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index 0190955f1b..4e6372fc0e 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -22,12 +22,27 @@ export const docs = {
description:
'Numeric spacing step controlling the gap between items: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',
},
+ {
+ name: 'hAlign',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: 'Horizontal (main-axis) alignment of items.',
+ },
{
name: 'vAlign',
type: "'start' | 'center' | 'end' | 'stretch'",
description: 'Vertical (cross-axis) alignment of items.',
default: "'stretch'",
},
+ {
+ name: 'justify',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: 'Main-axis alignment alias for hAlign. Mirrors CSS justify-content.',
+ },
+ {
+ name: 'align',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description: 'Cross-axis alignment alias for vAlign. Mirrors CSS align-items.',
+ },
{
name: 'wrap',
type: "'nowrap' | 'wrap' | 'wrap-reverse'",
@@ -69,6 +84,21 @@ export const docs = {
description: 'Horizontal (cross-axis) alignment of items.',
default: "'stretch'",
},
+ {
+ name: 'vAlign',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: 'Vertical (main-axis) alignment of items.',
+ },
+ {
+ name: 'justify',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: 'Main-axis alignment alias for vAlign. Mirrors CSS justify-content.',
+ },
+ {
+ name: 'align',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description: 'Cross-axis alignment alias for hAlign. Mirrors CSS align-items.',
+ },
{
name: 'wrap',
type: "'nowrap' | 'wrap' | 'wrap-reverse'",
@@ -203,12 +233,27 @@ export const docsZh = {
description:
'控制元素间距的数值间距步进:0、0.5、1、1.5、2、3、4、5、6、8、10。',
},
+ {
+ name: 'hAlign',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: '水平(主轴)对齐方式。',
+ },
{
name: 'vAlign',
type: "'start' | 'center' | 'end' | 'stretch'",
description: '元素的垂直(交叉轴)对齐方式。',
default: "'stretch'",
},
+ {
+ name: 'justify',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: 'hAlign 的别名。对应 CSS justify-content。',
+ },
+ {
+ name: 'align',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description: 'vAlign 的别名。对应 CSS align-items。',
+ },
{
name: 'wrap',
type: "'nowrap' | 'wrap' | 'wrap-reverse'",
@@ -251,6 +296,21 @@ export const docsZh = {
description: '元素的水平(交叉轴)对齐方式。',
default: "'stretch'",
},
+ {
+ name: 'vAlign',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: '垂直(主轴)对齐方式。',
+ },
+ {
+ name: 'justify',
+ type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+ description: 'vAlign 的别名。对应 CSS justify-content。',
+ },
+ {
+ name: 'align',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description: 'hAlign 的别名。对应 CSS align-items。',
+ },
{
name: 'wrap',
type: "'nowrap' | 'wrap' | 'wrap-reverse'",
@@ -381,7 +441,10 @@ export const docsDense = {
description: 'Horizontal stack; left-to-right, polymorphic rendering.',
propDescriptions: {
gap: 'Numeric spacing step for gap: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',
+ hAlign: 'Horizontal (main-axis) alignment.',
vAlign: 'Vertical (cross-axis) alignment.',
+ justify: 'Main-axis alignment alias for hAlign. Mirrors CSS justify-content.',
+ align: 'Cross-axis alignment alias for vAlign. Mirrors CSS align-items.',
wrap: 'Flex wrap behavior.',
element: 'HTML element to render as container.',
children: 'Stack content.',
@@ -394,6 +457,9 @@ export const docsDense = {
propDescriptions: {
gap: 'Numeric spacing step for gap: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',
hAlign: 'Horizontal (cross-axis) alignment.',
+ vAlign: 'Vertical (main-axis) alignment.',
+ justify: 'Main-axis alignment alias for vAlign. Mirrors CSS justify-content.',
+ align: 'Cross-axis alignment alias for hAlign. Mirrors CSS align-items.',
wrap: 'Flex wrap behavior.',
element: 'HTML element to render as container.',
children: 'Stack content.',
diff --git a/packages/core/src/Stack/XDSHStack.test.tsx b/packages/core/src/Stack/XDSHStack.test.tsx
index eaf9185c45..fb784d8fea 100644
--- a/packages/core/src/Stack/XDSHStack.test.tsx
+++ b/packages/core/src/Stack/XDSHStack.test.tsx
@@ -96,4 +96,32 @@ describe('XDSHStack', () => {
);
expect(screen.getByTestId('hstack')).toBeInTheDocument();
});
+
+ it('accepts justify as alias for hAlign', () => {
+ const {container} = render(
+ <XDSHStack justify="between">
+ <div>A</div>
+ <div>B</div>
+ </XDSHStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
+
+ it('accepts align as alias for vAlign', () => {
+ const {container} = render(
+ <XDSHStack align="center">
+ <div>A</div>
+ </XDSHStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
+
+ it('prefers explicit hAlign over justify', () => {
+ const {container} = render(
+ <XDSHStack hAlign="center" justify="end">
+ <div>A</div>
+ </XDSHStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
});
diff --git a/packages/core/src/Stack/XDSHStack.tsx b/packages/core/src/Stack/XDSHStack.tsx
index a666a0fda2..2d60bccbc9 100644
--- a/packages/core/src/Stack/XDSHStack.tsx
+++ b/packages/core/src/Stack/XDSHStack.tsx
@@ -34,6 +34,18 @@ export interface XDSHStackProps extends Omit<
* @default 'stretch'
*/
vAlign?: StackCrossAlignment;
+
+ /**
+ * Main-axis alignment alias. Maps to `hAlign` on HStack.
+ * Mirrors CSS `justify-content` / Tailwind `justify-*`.
+ */
+ justify?: StackMainAlignment;
+
+ /**
+ * Cross-axis alignment alias. Maps to `vAlign` on HStack.
+ * Mirrors CSS `align-items` / Tailwind `items-*`.
+ */
+ align?: StackCrossAlignment;
}
/**
@@ -48,8 +60,23 @@ export interface XDSHStackProps extends Omit<
* </XDSHStack>
* ```
*/
-export function XDSHStack({ref, ...props}: XDSHStackProps) {
- return <XDSStack {...props} direction="horizontal" ref={ref} />;
+export function XDSHStack({
+ ref,
+ justify,
+ align,
+ hAlign,
+ vAlign,
+ ...props
+}: XDSHStackProps) {
+ return (
+ <XDSStack
+ {...props}
+ direction="horizontal"
+ hAlign={hAlign ?? justify}
+ vAlign={vAlign ?? align}
+ ref={ref}
+ />
+ );
}
XDSHStack.displayName = 'XDSHStack';
diff --git a/packages/core/src/Stack/XDSStack.test.tsx b/packages/core/src/Stack/XDSStack.test.tsx
index fd35831be3..bdd7c9b5b8 100644
--- a/packages/core/src/Stack/XDSStack.test.tsx
+++ b/packages/core/src/Stack/XDSStack.test.tsx
@@ -165,4 +165,41 @@ describe('XDSStack', () => {
const element = screen.getByTestId('stack');
expect(element).toHaveAttribute('aria-label', 'Stack container');
});
+
+ it('accepts justify as main-axis alias (horizontal)', () => {
+ const {container} = render(
+ <XDSStack direction="horizontal" justify="between">
+ <div>A</div>
+ <div>B</div>
+ </XDSStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
+
+ it('accepts align as cross-axis alias (horizontal)', () => {
+ const {container} = render(
+ <XDSStack direction="horizontal" align="center">
+ <div>A</div>
+ </XDSStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
+
+ it('accepts justify as main-axis alias (vertical)', () => {
+ const {container} = render(
+ <XDSStack direction="vertical" justify="center">
+ <div>A</div>
+ </XDSStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
+
+ it('prefers explicit hAlign/vAlign over aliases', () => {
+ const {container} = render(
+ <XDSStack direction="horizontal" hAlign="center" justify="end">
+ <div>A</div>
+ </XDSStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
});
diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsx
index a89ba8f649..58a8bb5cc0 100644
--- a/packages/core/src/Stack/XDSStack.tsx
+++ b/packages/core/src/Stack/XDSStack.tsx
@@ -73,6 +73,24 @@ export interface XDSStackProps extends XDSBaseProps<HTMLDivElement> {
*/
vAlign?: XDSStackAlignment;
+ /**
+ * Main-axis alignment alias. Resolves based on `direction`:
+ * - `horizontal` → `hAlign` (justify-content)
+ * - `vertical` → `vAlign` (justify-content)
+ *
+ * Mirrors CSS `justify-content` / Tailwind `justify-*`.
+ */
+ justify?: StackMainAlignment;
+
+ /**
+ * Cross-axis alignment alias. Resolves based on `direction`:
+ * - `horizontal` → `vAlign` (align-items)
+ * - `vertical` → `hAlign` (align-items)
+ *
+ * Mirrors CSS `align-items` / Tailwind `items-*`.
+ */
+ align?: StackCrossAlignment;
+
/**
* Spacing between items.
* Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
@@ -149,6 +167,8 @@ export function XDSStack({
direction,
hAlign,
vAlign,
+ justify,
+ align,
gap,
wrap,
element = 'div',
@@ -159,15 +179,27 @@ export function XDSStack({
ref,
...props
}: XDSStackProps) {
+ // Resolve align/justify aliases based on direction
+ const resolvedHAlign =
+ hAlign ??
+ (direction === 'horizontal'
+ ? (justify as XDSStackAlignment | undefined)
+ : (align as XDSStackAlignment | undefined));
+ const resolvedVAlign =
+ vAlign ??
+ (direction === 'horizontal'
+ ? (align as XDSStackAlignment | undefined)
+ : (justify as XDSStackAlignment | undefined));
+
// Map hAlign/vAlign to mainAlign/crossAlign based on direction
const mainAlign =
direction === 'horizontal'
- ? (hAlign as StackMainAlignment | undefined)
- : (vAlign as StackMainAlignment | undefined);
+ ? (resolvedHAlign as StackMainAlignment | undefined)
+ : (resolvedVAlign as StackMainAlignment | undefined);
const crossAlign =
direction === 'horizontal'
- ? (vAlign as StackCrossAlignment | undefined)
- : (hAlign as StackCrossAlignment | undefined);
+ ? (resolvedVAlign as StackCrossAlignment | undefined)
+ : (resolvedHAlign as StackCrossAlignment | undefined);
const stylexProps = stylex.props(
...stack({
diff --git a/packages/core/src/Stack/XDSVStack.test.tsx b/packages/core/src/Stack/XDSVStack.test.tsx
index 00b6ca4254..09f3d16243 100644
--- a/packages/core/src/Stack/XDSVStack.test.tsx
+++ b/packages/core/src/Stack/XDSVStack.test.tsx
@@ -96,4 +96,31 @@ describe('XDSVStack', () => {
);
expect(screen.getByTestId('vstack')).toBeInTheDocument();
});
+
+ it('accepts justify as alias for vAlign', () => {
+ const {container} = render(
+ <XDSVStack justify="center">
+ <div>A</div>
+ </XDSVStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
+
+ it('accepts align as alias for hAlign', () => {
+ const {container} = render(
+ <XDSVStack align="center">
+ <div>A</div>
+ </XDSVStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
+
+ it('prefers explicit vAlign over justify', () => {
+ const {container} = render(
+ <XDSVStack vAlign="center" justify="end">
+ <div>A</div>
+ </XDSVStack>,
+ );
+ expect(container.firstChild).toBeInTheDocument();
+ });
});
diff --git a/packages/core/src/Stack/XDSVStack.tsx b/packages/core/src/Stack/XDSVStack.tsx
index 4f5bca17d2..06527fc111 100644
--- a/packages/core/src/Stack/XDSVStack.tsx
+++ b/packages/core/src/Stack/XDSVStack.tsx
@@ -34,6 +34,18 @@ export interface XDSVStackProps extends Omit<
* - `evenly`: Even space distribution
*/
vAlign?: StackMainAlignment;
+
+ /**
+ * Main-axis alignment alias. Maps to `vAlign` on VStack.
+ * Mirrors CSS `justify-content` / Tailwind `justify-*`.
+ */
+ justify?: StackMainAlignment;
+
+ /**
+ * Cross-axis alignment alias. Maps to `hAlign` on VStack.
+ * Mirrors CSS `align-items` / Tailwind `items-*`.
+ */
+ align?: StackCrossAlignment;
}
/**
@@ -48,8 +60,23 @@ export interface XDSVStackProps extends Omit<
* </XDSVStack>
* ```
*/
-export function XDSVStack({ref, ...props}: XDSVStackProps) {
- return <XDSStack {...props} direction="vertical" ref={ref} />;
+export function XDSVStack({
+ ref,
+ justify,
+ align,
+ hAlign,
+ vAlign,
+ ...props
+}: XDSVStackProps) {
+ return (
+ <XDSStack
+ {...props}
+ direction="vertical"
+ hAlign={hAlign ?? align}
+ vAlign={vAlign ?? justify}
+ ref={ref}
+ />
+ );
}
XDSVStack.displayName = 'XDSVStack';