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.mjsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 directionconst 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.tsxindex 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.tsxindex 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';