Skip to content

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

TypeScript

fix(core): remove misleading TabList orientation prop (#4293)

Ojas Mutreja6df1a4cb37d6
diff --git a/.changeset/tablist-remove-orientation-prop-misleading-no-op-5s4p.md b/.changeset/tablist-remove-orientation-prop-misleading-no-op-5s4p.md
new file mode 100644
index 0000000000..5fe2863cbf
--- /dev/null
+++ b/.changeset/tablist-remove-orientation-prop-misleading-no-op-5s4p.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': minor
+---
+
+[breaking] TabList: remove orientation prop (misleading no-op). The prop did not render vertical tabs; it only toggled the keyboard-hint badge arrows. Arrow navigation has always accepted both axes (horizontal and vertical) via orientation: both in useListFocus. Run astryx upgrade to auto-strip the prop from your code.
+@HelloOjasMutreja
diff --git a/packages/cli/codemods/__tests__/registry.test.mjs b/packages/cli/codemods/__tests__/registry.test.mjs
index c6f7f0fad3..1615494cf5 100644
--- a/packages/cli/codemods/__tests__/registry.test.mjs
+++ b/packages/cli/codemods/__tests__/registry.test.mjs
@@ -22,6 +22,7 @@ describe('registry', () => {
'0.1.5',
'0.1.7',
'0.1.8',
+ '0.2.0',
]);
});
});
diff --git a/packages/cli/codemods/registry.mjs b/packages/cli/codemods/registry.mjs
index ccb471c1a6..988c165033 100644
--- a/packages/cli/codemods/registry.mjs
+++ b/packages/cli/codemods/registry.mjs
@@ -23,6 +23,7 @@ const registry = new Map([
['0.1.5', () => import('./transforms/v0.1.5/index.mjs')],
['0.1.7', () => import('./transforms/v0.1.7/index.mjs')],
['0.1.8', () => import('./transforms/v0.1.8/index.mjs')],
+ ['0.2.0', () => import('./transforms/v0.2.0/index.mjs')],
]);
// Re-export from the shared utility so registry callers and other consumers
diff --git a/packages/cli/codemods/transforms/v0.2.0/__tests__/remove-tablist-orientation.test.mjs b/packages/cli/codemods/transforms/v0.2.0/__tests__/remove-tablist-orientation.test.mjs
new file mode 100644
index 0000000000..2609ecc727
--- /dev/null
+++ b/packages/cli/codemods/transforms/v0.2.0/__tests__/remove-tablist-orientation.test.mjs
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import('../remove-tablist-orientation.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('remove-tablist-orientation', () => {
+ it('removes orientation="horizontal" from TabList', async () => {
+ const input = `import {TabList} from '@astryxdesign/core';
+const t = <TabList value="a" onChange={onChange} orientation="horizontal"><Tab value="a" label="A" /></TabList>;`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('orientation');
+ expect(output).toContain('value="a"');
+ });
+
+ it('removes orientation="vertical" from TabList', async () => {
+ const input = `import {TabList} from '@astryxdesign/core';
+const t = <TabList value="a" onChange={onChange} orientation="vertical"><Tab value="a" label="A" /></TabList>;`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('orientation');
+ expect(output).toContain('value="a"');
+ });
+
+ it('removes orientation from a TabList with expression value', async () => {
+ const input = `import {TabList} from '@astryxdesign/core';
+const t = <TabList value={active} orientation={'horizontal'} onChange={fn}><Tab value="a" label="A" /></TabList>;`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('orientation');
+ });
+
+ it('is alias-aware', async () => {
+ const input = `import {TabList as Tabs} from '@astryxdesign/core';
+const t = <Tabs value="a" onChange={fn} orientation="vertical"><Tab value="a" label="A" /></Tabs>;`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('orientation');
+ });
+
+ it('handles the subpath import source', async () => {
+ const input = `import {TabList} from '@astryxdesign/core/TabList';
+const t = <TabList value="a" onChange={fn} orientation="horizontal"><Tab value="a" label="A" /></TabList>;`;
+ const output = await applyTransform(input);
+ expect(output).not.toContain('orientation');
+ });
+
+ it('does not touch orientation on other components', async () => {
+ const input = `import {TabList} from '@astryxdesign/core';
+const t = <SomeOtherComponent orientation="vertical" />;`;
+ const output = await applyTransform(input);
+ // SomeOtherComponent is not a TabList; orientation is preserved
+ expect(output).toContain('orientation="vertical"');
+ });
+
+ it('returns undefined (no-op) when no TabList import is found', async () => {
+ const input = `import {Button} from '@astryxdesign/core';
+const t = <Button label="Click" />;`;
+ const {default: transform} = await import('../remove-tablist-orientation.mjs');
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const file = {source: input, path: 'test.tsx'};
+ const result = transform(file, api);
+ // No TabList import means no-op: transform returns undefined
+ expect(result).toBeUndefined();
+ });
+
+ it('leaves TabList with no orientation prop unchanged', async () => {
+ const input = `import {TabList} from '@astryxdesign/core';
+const t = <TabList value="a" onChange={fn}><Tab value="a" label="A" /></TabList>;`;
+ const output = await applyTransform(input);
+ // Source is returned unchanged (transform returns undefined, applyTransform falls back)
+ expect(output).toBe(input);
+ });
+});
diff --git a/packages/cli/codemods/transforms/v0.2.0/index.mjs b/packages/cli/codemods/transforms/v0.2.0/index.mjs
new file mode 100644
index 0000000000..ab7076be24
--- /dev/null
+++ b/packages/cli/codemods/transforms/v0.2.0/index.mjs
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.2.0 transform manifest
+ *
+ * Lists all codemods for the v0.2.0 release in the order they should run.
+ */
+
+import removeTabListOrientation, {
+ meta as removeTabListOrientationMeta,
+} from './remove-tablist-orientation.mjs';
+
+export default [
+ {
+ name: 'remove-tablist-orientation',
+ transform: removeTabListOrientation,
+ meta: removeTabListOrientationMeta,
+ },
+];
diff --git a/packages/cli/codemods/transforms/v0.2.0/remove-tablist-orientation.mjs b/packages/cli/codemods/transforms/v0.2.0/remove-tablist-orientation.mjs
new file mode 100644
index 0000000000..e6ea612d8f
--- /dev/null
+++ b/packages/cli/codemods/transforms/v0.2.0/remove-tablist-orientation.mjs
@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Remove TabList orientation prop
+ * @see https://github.com/facebook/astryx/issues/4231
+ *
+ * As of v0.2.0, TabList no longer accepts an `orientation` prop. The prop
+ * was misleading: it only drove the keyboard-hint badge, not a real vertical
+ * layout. Arrow-key navigation already accepted both horizontal and vertical
+ * axes unconditionally (orientation: 'both' in useListFocus), so passing
+ * orientation="vertical" had no meaningful effect. Removing it prevents
+ * consumers from assuming a vertical tab-strip layout exists when it does not.
+ *
+ * Migration: simply delete every `orientation` attribute on <TabList>.
+ * No behavior changes. The hint badge defaults to horizontal arrows, which
+ * matches what the navigation has always done.
+ */
+
+export const meta = {
+ title: 'Remove TabList orientation prop (misleading no-op)',
+ description:
+ 'The `orientation` prop is removed from TabList in v0.2.0. It did not ' +
+ 'produce a vertical tab strip; it only changed the keyboard-hint arrow ' +
+ 'badge. Arrow navigation already accepted both axes regardless. This ' +
+ 'codemod strips the prop from all <TabList> usages. No behavior change.',
+ pr: '#4231',
+};
+
+/** Import sources that provide the Astryx TabList component. */
+const IMPORT_SOURCES = new Set([
+ '@astryxdesign/core',
+ '@astryxdesign/core/TabList',
+ '@xds/core',
+ '@xds/core/TabList',
+]);
+
+/** Component names that had the orientation prop. */
+const TARGET_IMPORTED_NAMES = new Set(['TabList']);
+
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ // Track alias-aware local names for the target components.
+ const targetLocals = new Set();
+ root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+ if (!IMPORT_SOURCES.has(path.node.source.value)) return;
+ for (const spec of path.node.specifiers ?? []) {
+ if (
+ spec.type === 'ImportSpecifier' &&
+ TARGET_IMPORTED_NAMES.has(spec.imported.name)
+ ) {
+ targetLocals.add(spec.local.name);
+ }
+ }
+ });
+
+ if (targetLocals.size === 0) return undefined;
+
+ // Remove every `orientation` JSX attribute from target component elements.
+ root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+ const name = path.node.name;
+ const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+ if (!componentName || !targetLocals.has(componentName)) return;
+
+ const before = path.node.attributes.length;
+ path.node.attributes = path.node.attributes.filter(
+ (/** @type {any} */ attr) =>
+ !(attr.type === 'JSXAttribute' && attr.name?.name === 'orientation'),
+ );
+ if (path.node.attributes.length !== before) {
+ hasChanges = true;
+ }
+ });
+
+ if (!hasChanges) return undefined;
+ return root.toSource({quote: 'single'});
+}
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index a5a69ce7c7..63dd992754 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -55,12 +55,6 @@ export const docs = {
description: 'Whether to show a bottom border divider under the tab list.',
default: 'false',
},
- {
- name: 'orientation',
- type: "'horizontal' | 'vertical'",
- description: "Orientation of the tab strip, controlling which arrow keys move focus between tabs and the reported aria-orientation. 'horizontal': ArrowLeft/ArrowRight. 'vertical': ArrowUp/ArrowDown. Both axes' arrows are accepted regardless.",
- default: "'horizontal'",
- },
{
name: 'children',
type: 'ReactNode',
diff --git a/packages/core/src/TabList/TabList.test.tsx b/packages/core/src/TabList/TabList.test.tsx
index e7536998df..1a06ff3b89 100644
--- a/packages/core/src/TabList/TabList.test.tsx
+++ b/packages/core/src/TabList/TabList.test.tsx
@@ -77,10 +77,9 @@ describe('TabList', () => {
it('does not set aria-orientation on the nav (invalid for role navigation)', () => {
// Regression: aria-orientation is not an allowed attribute on the
- // navigation role and produces an axe aria-allowed-attr violation. The
- // `orientation` prop must drive keyboard/hint behavior without emitting
- // this attribute, regardless of the value passed.
- const {rerender} = render(
+ // navigation role and produces an axe aria-allowed-attr violation.
+ // TabList deliberately never sets this attribute.
+ render(
<TabList value="home" onChange={() => {}}>
<Tab value="home" label="Home" />
<Tab value="settings" label="Settings" />
@@ -90,17 +89,6 @@ describe('TabList', () => {
expect(screen.getByRole('navigation')).not.toHaveAttribute(
'aria-orientation',
);
-
- rerender(
- <TabList value="home" onChange={() => {}} orientation="vertical">
- <Tab value="home" label="Home" />
- <Tab value="settings" label="Settings" />
- </TabList>,
- );
-
- expect(screen.getByRole('navigation')).not.toHaveAttribute(
- 'aria-orientation',
- );
});
it('ignores a consumer-supplied aria-orientation on the nav', () => {
diff --git a/packages/core/src/TabList/TabList.tsx b/packages/core/src/TabList/TabList.tsx
index 5dd0941c67..e28e2a065f 100644
--- a/packages/core/src/TabList/TabList.tsx
+++ b/packages/core/src/TabList/TabList.tsx
@@ -22,7 +22,7 @@ import * as stylex from '@stylexjs/stylex';
import {borderVars, colorVars, spacingVars} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import {TabListContext} from './TabListContext';
-import type {TabListOrientation, TabListSize} from './TabListContext';
+import type {TabListSize} from './TabListContext';
import {useSize} from '../SizeContext/SizeContext';
import {mergeProps, mergeRefs} from '../utils';
import {useListFocus} from '../hooks/useListFocus';
@@ -66,15 +66,6 @@ export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
* @default false
*/
hasDivider?: boolean;
- /**
- * Orientation of the tab strip, controlling which arrow keys move
- * focus between tabs.
- * - `'horizontal'` (default): ArrowLeft / ArrowRight (ArrowUp / ArrowDown
- * also work per the WAI-ARIA APG).
- * - `'vertical'`: ArrowUp / ArrowDown (ArrowLeft / ArrowRight also work).
- * @default 'horizontal'
- */
- orientation?: TabListOrientation;
/**
* Tab and TabMenu children.
*/
@@ -130,7 +121,6 @@ export function TabList({
size: sizeProp,
layout = 'hug',
hasDivider = false,
- orientation = 'horizontal',
xstyle,
className,
style,
@@ -150,14 +140,13 @@ export function TabList({
// Roving-tabindex keyboard navigation across the tab strip via the shared
// hook. `orientation: 'both'` accepts both arrow axes per the WAI-ARIA APG
// allowance for tab strips (ArrowRight/ArrowDown advance, ArrowLeft/ArrowUp
- // retreat) regardless of the component's `orientation` prop, which only
- // drives the keyboard hint badge (see useKeyboardHint below). We do not set
- // `aria-orientation` on the `<nav>`: that attribute is invalid on the
- // navigation role and triggers an axe `aria-allowed-attr` violation.
+ // retreat). We do not set `aria-orientation` on the `<nav>`: that attribute
+ // is invalid on the navigation role and triggers an axe `aria-allowed-attr`
+ // violation.
//
// `hasRovingTabIndex` makes the hook own the single tab stop: it stamps
// tabindex 0/-1, repairs the stop on mount and as stops mount/unmount or
- // toggle disabled, and — via `handleFocus` on the nav — keeps the stop in
+ // toggle disabled, and -- via `handleFocus` on the nav -- keeps the stop in
// sync after clicks or programmatic focus. Individual Tabs still render
// `tabIndex={isSelected ? 0 : -1}` (see Tab.tsx) as the initial source of
// truth; the hook's repair preserves an existing tab stop and only promotes
@@ -173,7 +162,7 @@ export function TabList({
onKeyDown: onHintKeyDown,
onFocus: onHintFocus,
onBlur: onHintBlur,
- } = useKeyboardHint({orientation});
+ } = useKeyboardHint();
const contextValue = useMemo(
() => ({value, onChange, size, layout}),
diff --git a/packages/core/src/TabList/TabListContext.ts b/packages/core/src/TabList/TabListContext.ts
index 50d5228c7c..0fb4959021 100644
--- a/packages/core/src/TabList/TabListContext.ts
+++ b/packages/core/src/TabList/TabListContext.ts
@@ -26,12 +26,6 @@ export type TabListSize = 'sm' | 'md' | 'lg';
*/
export type TabListLayout = 'hug' | 'fill';
-/**
- * Orientation of the tab strip. Controls which arrow keys move focus
- * between tabs and the reported `aria-orientation`.
- */
-export type TabListOrientation = 'horizontal' | 'vertical';
-
/**
* Context for communicating value/onChange/size/layout from TabList to children.
*/