Skip to content

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

TypeScript

fix(Stack): rename `element` prop to `as` for consistency (#2441)

Andrey Goder2cc4733246be
diff --git a/packages/cli/src/codemods/transforms/v0.0.15/__tests__/rename-stack-element-to-as.test.mjs b/packages/cli/src/codemods/transforms/v0.0.15/__tests__/rename-stack-element-to-as.test.mjs
new file mode 100644
index 0000000000..c0ea5565eb
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.15/__tests__/rename-stack-element-to-as.test.mjs
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../rename-stack-element-to-as.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const file = {source, path: 'test.tsx'};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('rename-stack-element-to-as', () => {
+ it('renames element to as on XDSStack', async () => {
+ const input = `<XDSStack element="nav">Content</XDSStack>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('as="nav"');
+ expect(output).not.toContain('element=');
+ });
+
+ it('renames element to as on XDSHStack', async () => {
+ const input = `<XDSHStack element="section">Content</XDSHStack>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('as="section"');
+ expect(output).not.toContain('element=');
+ });
+
+ it('renames element to as on XDSVStack', async () => {
+ const input = `<XDSVStack element="main">Content</XDSVStack>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('as="main"');
+ expect(output).not.toContain('element=');
+ });
+
+ it('renames element to as on XDSStackItem', async () => {
+ const input = `<XDSStackItem element="li">Content</XDSStackItem>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('as="li"');
+ expect(output).not.toContain('element=');
+ });
+
+ it('handles multiple components in one file', async () => {
+ const input = `<XDSHStack element="nav"><XDSStackItem element="li">Item</XDSStackItem></XDSHStack>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('<XDSHStack as="nav"');
+ expect(output).toContain('<XDSStackItem as="li"');
+ expect(output).not.toContain('element=');
+ });
+
+ it('does not touch unrelated components', async () => {
+ const input = `<XDSButton element="a">Link</XDSButton>`;
+ const output = await applyTransform(input);
+ expect(output).toContain('element="a"');
+ });
+
+ it('returns undefined when no changes needed', async () => {
+ const {default: transform} = await import(
+ '../rename-stack-element-to-as.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const source = `<XDSStack as="nav">Content</XDSStack>`;
+ const result = transform({source, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.0.15/index.mjs b/packages/cli/src/codemods/transforms/v0.0.15/index.mjs
index 2d0caa49fc..20efb3f4a9 100644
--- a/packages/cli/src/codemods/transforms/v0.0.15/index.mjs
+++ b/packages/cli/src/codemods/transforms/v0.0.15/index.mjs
@@ -18,6 +18,10 @@ import renameImperativeRefToHandleRef, {
meta as renameImperativeRefToHandleRefMeta,
} from './rename-imperative-ref-to-handleRef.mjs';
+import renameStackElementToAs, {
+ meta as renameStackElementToAsMeta,
+} from './rename-stack-element-to-as.mjs';
+
export default [
{
name: 'rename-date-picker-to-input',
@@ -34,4 +38,9 @@ export default [
transform: renameImperativeRefToHandleRef,
meta: renameImperativeRefToHandleRefMeta,
},
+ {
+ name: 'rename-stack-element-to-as',
+ transform: renameStackElementToAs,
+ meta: renameStackElementToAsMeta,
+ },
];
diff --git a/packages/cli/src/codemods/transforms/v0.0.15/rename-stack-element-to-as.mjs b/packages/cli/src/codemods/transforms/v0.0.15/rename-stack-element-to-as.mjs
new file mode 100644
index 0000000000..4e8d248019
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.15/rename-stack-element-to-as.mjs
@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename `element` prop to `as` on Stack components
+ */
+
+export const meta = {
+ title: 'Rename element → as on Stack components',
+ description:
+ 'Renames the `element` prop to `as` on XDSStack, XDSHStack, XDSVStack, and XDSStackItem for consistency with other polymorphic components.',
+};
+
+const TARGET_COMPONENTS = new Set([
+ 'XDSStack',
+ 'XDSHStack',
+ 'XDSVStack',
+ 'XDSStackItem',
+]);
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ root
+ .find(j.JSXOpeningElement)
+ .filter((path) => {
+ const name = path.node.name;
+ return name.type === 'JSXIdentifier' && TARGET_COMPONENTS.has(name.name);
+ })
+ .forEach((path) => {
+ path.node.attributes.forEach((attr) => {
+ if (attr.type === 'JSXAttribute' && attr.name.name === 'element') {
+ attr.name.name = 'as';
+ hasChanges = true;
+ }
+ });
+ });
+
+ return hasChanges ? root.toSource({quote: 'single'}) : undefined;
+}
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index 39c6b19421..9d388994bb 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -65,7 +65,7 @@ export const docs = {
default: "'nowrap'",
},
{
- name: 'element',
+ name: 'as',
type: 'ElementType',
description: 'HTML element to render as the stack container.',
default: "'div'",
@@ -132,7 +132,7 @@ export const docs = {
default: "'nowrap'",
},
{
- name: 'element',
+ name: 'as',
type: 'ElementType',
description: 'HTML element to render as the stack container.',
default: "'div'",
@@ -164,7 +164,7 @@ export const docs = {
'Override the cross-axis alignment for this individual item, ignoring the parent stack alignment.',
},
{
- name: 'element',
+ name: 'as',
type: 'ElementType',
description: 'HTML element to render as the item wrapper.',
default: "'div'",
@@ -250,7 +250,7 @@ export const docsZh = {
default: "'nowrap'",
},
{
- name: 'element',
+ name: 'as',
type: 'ElementType',
description: '作为堆叠容器渲染的 HTML 元素。',
default: "'div'",
@@ -318,7 +318,7 @@ export const docsZh = {
default: "'nowrap'",
},
{
- name: 'element',
+ name: 'as',
type: 'ElementType',
description: '作为堆叠容器渲染的 HTML 元素。',
default: "'div'",
@@ -350,7 +350,7 @@ export const docsZh = {
'覆盖此元素的交叉轴对齐方式,忽略父堆叠的对齐设置。',
},
{
- name: 'element',
+ name: 'as',
type: 'ElementType',
description: '作为子元素包装器渲染的 HTML 元素。',
default: "'div'",
@@ -400,7 +400,7 @@ export const docsDense = {
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.',
+ as: 'HTML element to render as container.',
children: 'Stack content.',
xstyle: 'StyleX layout styles; must be stylex.create() value.',
},
@@ -418,7 +418,7 @@ export const docsDense = {
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.',
+ as: 'HTML element to render as container.',
children: 'Stack content.',
},
},
@@ -429,7 +429,7 @@ export const docsDense = {
propDescriptions: {
size: 'Flex grow: static=natural size, fill=expand to remaining space.',
crossAlignSelf: 'Override cross-axis alignment for this item, ignoring parent.',
- element: 'HTML element to render as wrapper.',
+ as: 'HTML element to render as wrapper.',
children: 'Item content.',
},
},
diff --git a/packages/core/src/Stack/XDSHStack.test.tsx b/packages/core/src/Stack/XDSHStack.test.tsx
index d58e760cfd..3a04159358 100644
--- a/packages/core/src/Stack/XDSHStack.test.tsx
+++ b/packages/core/src/Stack/XDSHStack.test.tsx
@@ -31,9 +31,9 @@ describe('XDSHStack', () => {
expect(element.tagName).toBe('DIV');
});
- it('renders with polymorphic element prop', () => {
+ it('renders with polymorphic as prop', () => {
render(
- <XDSHStack element="nav" data-testid="hstack">
+ <XDSHStack as="nav" data-testid="hstack">
Content
</XDSHStack>,
);
@@ -80,10 +80,10 @@ describe('XDSHStack', () => {
expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
});
- it('forwards ref with polymorphic element', () => {
+ it('forwards ref with polymorphic as', () => {
const ref = vi.fn();
render(
- <XDSHStack element="section" ref={ref}>
+ <XDSHStack as="section" ref={ref}>
<div>Test</div>
</XDSHStack>,
);
diff --git a/packages/core/src/Stack/XDSStack.test.tsx b/packages/core/src/Stack/XDSStack.test.tsx
index 2d05447710..f6f0a32637 100644
--- a/packages/core/src/Stack/XDSStack.test.tsx
+++ b/packages/core/src/Stack/XDSStack.test.tsx
@@ -65,9 +65,9 @@ describe('XDSStack', () => {
expect(screen.getByTestId('stack')).toBeInTheDocument();
});
- it('renders with polymorphic element prop', () => {
+ it('renders with polymorphic as prop', () => {
render(
- <XDSStack direction="vertical" element="nav" data-testid="stack">
+ <XDSStack direction="vertical" as="nav" data-testid="stack">
Content
</XDSStack>,
);
@@ -75,9 +75,9 @@ describe('XDSStack', () => {
expect(element.tagName).toBe('NAV');
});
- it('renders with polymorphic element as section', () => {
+ it('renders with polymorphic as section', () => {
render(
- <XDSStack direction="vertical" element="section" data-testid="stack">
+ <XDSStack direction="vertical" as="section" data-testid="stack">
Content
</XDSStack>,
);
@@ -155,10 +155,10 @@ describe('XDSStack', () => {
expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
});
- it('forwards ref with polymorphic element', () => {
+ it('forwards ref with polymorphic as', () => {
const ref = vi.fn();
render(
- <XDSStack direction="vertical" element="section" ref={ref}>
+ <XDSStack direction="vertical" as="section" ref={ref}>
<div>Test</div>
</XDSStack>,
);
diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsx
index b8be039c83..f1e5cb6903 100644
--- a/packages/core/src/Stack/XDSStack.tsx
+++ b/packages/core/src/Stack/XDSStack.tsx
@@ -120,7 +120,7 @@ export interface XDSStackProps extends XDSBaseProps<HTMLElement> {
* The element type to render.
* @default 'div'
*/
- element?: ElementType;
+ as?: ElementType;
/**
* StyleX styles created via `stylex.create()`. Merged with the component's
@@ -184,7 +184,7 @@ export function XDSStack({
width,
height,
wrap,
- element = 'div',
+ as: element = 'div',
xstyle,
className,
style,
diff --git a/packages/core/src/Stack/XDSStackItem.test.tsx b/packages/core/src/Stack/XDSStackItem.test.tsx
index 30892492e5..0bd7698aba 100644
--- a/packages/core/src/Stack/XDSStackItem.test.tsx
+++ b/packages/core/src/Stack/XDSStackItem.test.tsx
@@ -25,9 +25,9 @@ describe('XDSStackItem', () => {
expect(element.tagName).toBe('DIV');
});
- it('renders with polymorphic element prop', () => {
+ it('renders with polymorphic as prop', () => {
render(
- <XDSStackItem element="section" data-testid="stack-item">
+ <XDSStackItem as="section" data-testid="stack-item">
Content
</XDSStackItem>,
);
@@ -60,10 +60,10 @@ describe('XDSStackItem', () => {
expect(ref).toHaveBeenCalledWith(expect.any(HTMLDivElement));
});
- it('forwards ref with polymorphic element', () => {
+ it('forwards ref with polymorphic as', () => {
const ref = vi.fn();
render(
- <XDSStackItem element="section" ref={ref}>
+ <XDSStackItem as="section" ref={ref}>
<div>Test</div>
</XDSStackItem>,
);
diff --git a/packages/core/src/Stack/XDSStackItem.tsx b/packages/core/src/Stack/XDSStackItem.tsx
index 6b9925f087..95dee5527e 100644
--- a/packages/core/src/Stack/XDSStackItem.tsx
+++ b/packages/core/src/Stack/XDSStackItem.tsx
@@ -44,7 +44,7 @@ export interface XDSStackItemProps extends XDSBaseProps<HTMLElement> {
* The element type to render.
* @default 'div'
*/
- element?: ElementType;
+ as?: ElementType;
/**
* StyleX styles created via `stylex.create()`. Merged with the component's
@@ -77,7 +77,7 @@ export interface XDSStackItemProps extends XDSBaseProps<HTMLElement> {
/**
* Stack item component for controlling individual item behavior within a stack.
*
- * Supports polymorphic rendering via the `element` prop.
+ * Supports polymorphic rendering via the `as` prop.
*
* @example
* ```
@@ -91,7 +91,7 @@ export interface XDSStackItemProps extends XDSBaseProps<HTMLElement> {
export function XDSStackItem({
crossAlignSelf,
size,
- element = 'div',
+ as: element = 'div',
xstyle,
className,
style,
diff --git a/packages/core/src/Stack/XDSVStack.test.tsx b/packages/core/src/Stack/XDSVStack.test.tsx
index 8da7043cf6..47f308ebaa 100644
--- a/packages/core/src/Stack/XDSVStack.test.tsx
+++ b/packages/core/src/Stack/XDSVStack.test.tsx
@@ -31,9 +31,9 @@ describe('XDSVStack', () => {
expect(element.tagName).toBe('DIV');
});
- it('renders with polymorphic element prop', () => {
+ it('renders with polymorphic as prop', () => {
render(
- <XDSVStack element="main" data-testid="vstack">
+ <XDSVStack as="main" data-testid="vstack">
Content
</XDSVStack>,
);
@@ -80,10 +80,10 @@ describe('XDSVStack', () => {
expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
});
- it('forwards ref with polymorphic element', () => {
+ it('forwards ref with polymorphic as', () => {
const ref = vi.fn();
render(
- <XDSVStack element="section" ref={ref}>
+ <XDSVStack as="section" ref={ref}>
<div>Test</div>
</XDSVStack>,
);