Skip to content

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

TypeScript

fix(api): rename on*Action props to *Action (React 19 convention) (#1942)

Cindy Zhang0f3825f16a18
diff --git a/internal/vibe-tests/selector-naming-test/variant-a-items.md b/internal/vibe-tests/selector-naming-test/variant-a-items.md
index 6ab404eef7..116c145486 100644
--- a/internal/vibe-tests/selector-naming-test/variant-a-items.md
+++ b/internal/vibe-tests/selector-naming-test/variant-a-items.md
@@ -73,22 +73,22 @@ import {XDSSelector, XDSSelectorItem} from '@xds/core';
### XDSSelector
-| Prop | Type | Default | Description |
-| -------------- | ------------------------------------------------------------- | ----------- | ------------------------------------- |
-| label | string | required | Label text (always rendered for a11y) |
-| items | Array<string \| ItemData \| Divider \| Section> | required | The items to display |
-| value | string | — | Currently selected value |
-| onChange | (value: string) => void | — | Selection change callback |
-| onChangeAction | (value: string) => Promise<void> | — | Async action on change |
-| placeholder | string | 'Select...' | Placeholder when nothing selected |
-| size | 'sm' \| 'md' \| 'lg' | 'md' | Trigger size |
-| isDisabled | boolean | false | Disabled state |
-| isLabelHidden | boolean | false | Visually hide label |
-| description | string | — | Help text below label |
-| isOptional | boolean | false | Show optional indicator |
-| isRequired | boolean | false | Show required indicator |
-| status | { type: 'warning' \| 'error' \| 'success', message?: string } | — | Validation status |
-| children | (item: ItemData) => ReactNode | — | Custom item renderer |
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------------------------------- | ----------- | ------------------------------------- |
+| label | string | required | Label text (always rendered for a11y) |
+| items | Array<string \| ItemData \| Divider \| Section> | required | The items to display |
+| value | string | — | Currently selected value |
+| onChange | (value: string) => void | — | Selection change callback |
+| changeAction | (value: string) => Promise<void> | — | Async action on change |
+| placeholder | string | 'Select...' | Placeholder when nothing selected |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Trigger size |
+| isDisabled | boolean | false | Disabled state |
+| isLabelHidden | boolean | false | Visually hide label |
+| description | string | — | Help text below label |
+| isOptional | boolean | false | Show optional indicator |
+| isRequired | boolean | false | Show required indicator |
+| status | { type: 'warning' \| 'error' \| 'success', message?: string } | — | Validation status |
+| children | (item: ItemData) => ReactNode | — | Custom item renderer |
### XDSSelectorItem (for custom rendering)
diff --git a/internal/vibe-tests/selector-naming-test/variant-b-options.md b/internal/vibe-tests/selector-naming-test/variant-b-options.md
index 104ebf0f04..c08939b452 100644
--- a/internal/vibe-tests/selector-naming-test/variant-b-options.md
+++ b/internal/vibe-tests/selector-naming-test/variant-b-options.md
@@ -73,22 +73,22 @@ import {XDSSelector, XDSSelectorOption} from '@xds/core';
### XDSSelector
-| Prop | Type | Default | Description |
-| -------------- | ------------------------------------------------------------- | ----------- | ------------------------------------- |
-| label | string | required | Label text (always rendered for a11y) |
-| options | Array<string \| OptionData \| Divider \| Section> | required | The options to display |
-| value | string | — | Currently selected value |
-| onChange | (value: string) => void | — | Selection change callback |
-| onChangeAction | (value: string) => Promise<void> | — | Async action on change |
-| placeholder | string | 'Select...' | Placeholder when nothing selected |
-| size | 'sm' \| 'md' \| 'lg' | 'md' | Trigger size |
-| isDisabled | boolean | false | Disabled state |
-| isLabelHidden | boolean | false | Visually hide label |
-| description | string | — | Help text below label |
-| isOptional | boolean | false | Show optional indicator |
-| isRequired | boolean | false | Show required indicator |
-| status | { type: 'warning' \| 'error' \| 'success', message?: string } | — | Validation status |
-| children | (option: OptionData) => ReactNode | — | Custom option renderer |
+| Prop | Type | Default | Description |
+| ------------- | ------------------------------------------------------------- | ----------- | ------------------------------------- |
+| label | string | required | Label text (always rendered for a11y) |
+| options | Array<string \| OptionData \| Divider \| Section> | required | The options to display |
+| value | string | — | Currently selected value |
+| onChange | (value: string) => void | — | Selection change callback |
+| changeAction | (value: string) => Promise<void> | — | Async action on change |
+| placeholder | string | 'Select...' | Placeholder when nothing selected |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Trigger size |
+| isDisabled | boolean | false | Disabled state |
+| isLabelHidden | boolean | false | Visually hide label |
+| description | string | — | Help text below label |
+| isOptional | boolean | false | Show optional indicator |
+| isRequired | boolean | false | Show required indicator |
+| status | { type: 'warning' \| 'error' \| 'success', message?: string } | — | Validation status |
+| children | (option: OptionData) => ReactNode | — | Custom option renderer |
### XDSSelectorOption (for custom rendering)
diff --git a/packages/cli/src/codemods/__tests__/registry.test.mjs b/packages/cli/src/codemods/__tests__/registry.test.mjs
index 5ba168575f..4e25e4b6c5 100644
--- a/packages/cli/src/codemods/__tests__/registry.test.mjs
+++ b/packages/cli/src/codemods/__tests__/registry.test.mjs
@@ -4,7 +4,7 @@ import {versions, getTransformsBetween} from '../registry.mjs';
describe('registry', () => {
describe('versions', () => {
test('are sorted in ascending semver order across digit boundaries', () => {
- expect(versions).toEqual(['0.0.2', '0.0.6', '0.0.7', '0.0.8', '0.0.10', '0.0.12', '0.0.13']);
+ expect(versions).toEqual(['0.0.2', '0.0.6', '0.0.7', '0.0.8', '0.0.10', '0.0.12', '0.0.13', '0.0.14']);
});
});
diff --git a/packages/cli/src/codemods/registry.mjs b/packages/cli/src/codemods/registry.mjs
index fb93afe145..9812ec5c0c 100644
--- a/packages/cli/src/codemods/registry.mjs
+++ b/packages/cli/src/codemods/registry.mjs
@@ -13,6 +13,7 @@ const registry = new Map([
['0.0.10', () => import('./transforms/v0.0.10/index.mjs')],
['0.0.12', () => import('./transforms/v0.0.12/index.mjs')],
['0.0.13', () => import('./transforms/v0.0.13/index.mjs')],
+ ['0.0.14', () => import('./transforms/v0.0.14/index.mjs')],
]);
/**
diff --git a/packages/cli/src/codemods/transforms/v0.0.14/__tests__/rename-action-props.test.mjs b/packages/cli/src/codemods/transforms/v0.0.14/__tests__/rename-action-props.test.mjs
new file mode 100644
index 0000000000..d48bc6df04
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.14/__tests__/rename-action-props.test.mjs
@@ -0,0 +1,127 @@
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+ const {default: transform} = await import(
+ '../rename-action-props.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-action-props', () => {
+ it('renames onChangeAction to changeAction on JSX', async () => {
+ const input = `<XDSSelector value="a" onChange={fn} onChangeAction={asyncFn} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('changeAction={asyncFn}');
+ expect(output).not.toContain('onChangeAction');
+ });
+
+ it('renames onClickAction to clickAction on JSX', async () => {
+ const input = `<XDSButton label="Go" onClickAction={asyncFn} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('clickAction={asyncFn}');
+ expect(output).not.toContain('onClickAction');
+ });
+
+ it('renames onPressedChangeAction to pressedChangeAction', async () => {
+ const input = `<XDSToggleButton onPressedChangeAction={asyncFn} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('pressedChangeAction={asyncFn}');
+ expect(output).not.toContain('onPressedChangeAction');
+ });
+
+ it('renames onScrollToTopAction to scrollToTopAction', async () => {
+ const input = `<XDSChatMessageList onScrollToTopAction={loadMore} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('scrollToTopAction={loadMore}');
+ expect(output).not.toContain('onScrollToTopAction');
+ });
+
+ it('handles multiple action props on one element', async () => {
+ const input = `<XDSTextInput onChange={fn} onChangeAction={asyncFn} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('changeAction={asyncFn}');
+ expect(output).toContain('onChange={fn}');
+ expect(output).not.toContain('onChangeAction');
+ });
+
+ it('renames object property keys', async () => {
+ const input = `createConfig({ onChangeAction: async () => {} });`;
+ const output = await applyTransform(input);
+ expect(output).toContain('changeAction:');
+ expect(output).not.toContain('onChangeAction:');
+ });
+
+ it('renames destructured props', async () => {
+ const input = `function MyInput({ onChangeAction, onChange }) { return null; }`;
+ const output = await applyTransform(input);
+ expect(output).toContain('changeAction');
+ expect(output).not.toContain('onChangeAction');
+ });
+
+ it('renames aliased destructured props', async () => {
+ const input = `function MyInput({ onChangeAction: handler }) { return null; }`;
+ const output = await applyTransform(input);
+ expect(output).toContain('changeAction: handler');
+ expect(output).not.toContain('onChangeAction');
+ });
+
+ it('renames TypeScript interface properties', async () => {
+ const input = `interface Props { onChangeAction?: (v: string) => Promise<void>; }`;
+ const output = await applyTransform(input);
+ expect(output).toContain('changeAction?:');
+ expect(output).not.toContain('onChangeAction');
+ });
+
+ it('returns undefined when no changes needed', async () => {
+ const {default: transform} = await import(
+ '../rename-action-props.mjs'
+ );
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const source = `<XDSSelector value="a" changeAction={fn} />`;
+ const result = transform({source, path: 'test.tsx'}, api);
+ expect(result).toBeUndefined();
+ });
+
+ it('does not rename onChange or onClick (non-action callbacks)', async () => {
+ const input = `<XDSSelector value="a" onChange={fn} onClick={fn2} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('onChange={fn}');
+ expect(output).toContain('onClick={fn2}');
+ });
+
+ it('does not rename onAction (not a transition-wrapped prop)', async () => {
+ const input = `<XDSAlertDialog title="Delete?" onAction={asyncFn} />`;
+ const output = await applyTransform(input);
+ expect(output).toContain('onAction={asyncFn}');
+ });
+
+ it('handles a full component file', async () => {
+ const input = `import { XDSSelector } from '@xds/core/Selector';
+
+interface MyProps {
+ onChangeAction?: (value: string) => Promise<void>;
+}
+
+function MySelector({ onChangeAction }: MyProps) {
+ return (
+ <XDSSelector
+ value="a"
+ onChange={fn}
+ onChangeAction={onChangeAction}
+ />
+ );
+}`;
+ const output = await applyTransform(input);
+ expect(output).toContain('changeAction');
+ expect(output).not.toContain('onChangeAction');
+ // onChange should be untouched
+ expect(output).toContain('onChange={fn}');
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.0.14/index.mjs b/packages/cli/src/codemods/transforms/v0.0.14/index.mjs
new file mode 100644
index 0000000000..5c581e0e46
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.14/index.mjs
@@ -0,0 +1,17 @@
+/**
+ * @file v0.0.14 transform manifest
+ *
+ * Lists all codemods for the v0.0.14 release in the order they should run.
+ */
+
+import renameActionProps, {
+ meta as renameActionPropsMeta,
+} from './rename-action-props.mjs';
+
+export default [
+ {
+ name: 'rename-action-props',
+ transform: renameActionProps,
+ meta: renameActionPropsMeta,
+ },
+];
diff --git a/packages/cli/src/codemods/transforms/v0.0.14/rename-action-props.mjs b/packages/cli/src/codemods/transforms/v0.0.14/rename-action-props.mjs
new file mode 100644
index 0000000000..ae8161454c
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.0.14/rename-action-props.mjs
@@ -0,0 +1,158 @@
+/**
+ * @file Codemod: Rename on*Action props to *Action (React 19 Action prop convention)
+ *
+ * Transforms:
+ * - onChangeAction → changeAction
+ * - onClickAction → clickAction
+ * - onPressedChangeAction → pressedChangeAction
+ * - onScrollToTopAction → scrollToTopAction
+ *
+ * Applies to JSX attributes on any component. The "Action" suffix signals
+ * that the function runs inside a React transition — the `on` prefix is
+ * dropped to align with the React 19 convention (e.g. `<form action={...}>`).
+ *
+ * @see https://react.dev/reference/react/useActionState#using-with-action-props
+ * @see https://aurorascharff.no/posts/building-design-components-with-action-props-using-async-react/
+ */
+
+export const meta = {
+ title: 'Rename on*Action props to *Action',
+ description:
+ 'Renames `onChangeAction` → `changeAction`, `onClickAction` → `clickAction`, ' +
+ '`onPressedChangeAction` → `pressedChangeAction`, ' +
+ 'and `onScrollToTopAction` → `scrollToTopAction` to align with the React 19 ' +
+ 'Action prop naming convention.',
+};
+
+/**
+ * Map of old prop names → new prop names.
+ * Ordered longest-first to avoid partial matches during iteration.
+ */
+const PROP_RENAMES = {
+ onPressedChangeAction: 'pressedChangeAction',
+ onScrollToTopAction: 'scrollToTopAction',
+ onChangeAction: 'changeAction',
+ onClickAction: 'clickAction',
+};
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ // --- 1. Rename JSX attributes ---
+ root.find(j.JSXAttribute).forEach((path) => {
+ const name = path.node.name;
+ if (name.type !== 'JSXIdentifier') return;
+
+ const newName = PROP_RENAMES[name.name];
+ if (newName) {
+ name.name = newName;
+ hasChanges = true;
+ }
+ });
+
+ // --- 2. Rename destructured parameter names (before general ObjectProperty) ---
+ // Covers: function MyComponent({ onChangeAction, ...rest }) → { changeAction, ...rest }
+ // Must run before step 3 so the ObjectPattern keys are renamed first and tracked.
+ const renamedBindings = new Map(); // oldLocalName → newLocalName
+
+ root.find(j.ObjectPattern).forEach((path) => {
+ for (const prop of path.node.properties) {
+ if (prop.type !== 'ObjectProperty') continue;
+ const key = prop.key;
+ if (key.type !== 'Identifier') continue;
+
+ const newName = PROP_RENAMES[key.name];
+ if (!newName) continue;
+
+ if (
+ prop.shorthand &&
+ prop.value.type === 'Identifier' &&
+ prop.value.name === key.name
+ ) {
+ // Shorthand: { onChangeAction } → { changeAction }
+ const oldLocal = key.name;
+ key.name = newName;
+ prop.value.name = newName;
+ renamedBindings.set(oldLocal, newName);
+ hasChanges = true;
+ } else if (prop.value.type === 'Identifier' && prop.value.name === key.name) {
+ // Non-shorthand same name: { onChangeAction: onChangeAction }
+ const oldLocal = prop.value.name;
+ key.name = newName;
+ prop.value.name = newName;
+ renamedBindings.set(oldLocal, newName);
+ hasChanges = true;
+ } else {
+ // Aliased: { onChangeAction: myHandler } → { changeAction: myHandler }
+ key.name = newName;
+ hasChanges = true;
+ }
+ }
+ });
+
+ // --- 3. Rename object property keys (e.g. { onChangeAction: fn }) ---
+ // Covers cases like useXDSImperativeAlertDialog({ onAction: ... })
+ // Skips ObjectProperty inside ObjectPattern (already handled in step 2).
+ root.find(j.ObjectProperty).forEach((path) => {
+ // Skip if inside a destructuring pattern
+ if (path.parent.node.type === 'ObjectPattern') return;
+
+ const key = path.node.key;
+ if (key.type === 'Identifier') {
+ const newName = PROP_RENAMES[key.name];
+ if (newName) {
+ key.name = newName;
+ // Also rename value if it's the same identifier (shorthand)
+ if (
+ path.node.shorthand &&
+ path.node.value.type === 'Identifier' &&
+ path.node.value.name !== newName
+ ) {
+ path.node.value.name = newName;
+ }
+ hasChanges = true;
+ }
+ }
+ });
+
+ // --- 4. Rename interface/type property signatures ---
+ // Covers: interface Props { onChangeAction?: ... } → { changeAction?: ... }
+ root.find(j.TSPropertySignature).forEach((path) => {
+ const key = path.node.key;
+ if (key.type === 'Identifier') {
+ const newName = PROP_RENAMES[key.name];
+ if (newName) {
+ key.name = newName;
+ hasChanges = true;
+ }
+ }
+ });
+
+ // --- 5. Rename identifier references from renamed destructured bindings ---
+ // When { onChangeAction } was renamed to { changeAction }, all references
+ // to the local variable `onChangeAction` must become `changeAction`.
+ if (renamedBindings.size > 0) {
+ root.find(j.Identifier).forEach((path) => {
+ const newName = renamedBindings.get(path.node.name);
+ if (!newName) return;
+
+ // Skip if this is the destructuring site itself (already renamed)
+ const parent = path.parent.node;
+ if (parent.type === 'ObjectProperty') return;
+ // Skip import specifiers
+ if (parent.type === 'ImportSpecifier') return;
+ // Skip JSX attribute names (handled in step 1)
+ if (parent.type === 'JSXAttribute' && path.name === 'name') return;
+ // Skip object keys in non-pattern contexts (handled in step 2)
+ if (parent.type === 'Property' && path.name === 'key') return;
+
+ path.node.name = newName;
+ hasChanges = true;
+ });
+ }
+
+ if (!hasChanges) return undefined;
+ return root.toSource({quote: 'single'});
+}
diff --git a/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx b/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx
index 93681bd61b..384f21df97 100644
--- a/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx
+++ b/packages/cli/templates/blocks/components/IconButton/IconButtonActionBar.tsx
@@ -4,7 +4,7 @@ import {XDSIconButton} from '@xds/core/IconButton';
import {XDSIcon} from '@xds/core/Icon';
import {XDSHStack} from '@xds/core/Stack';
-export default function IconButtonActionBar() {
+export default function IconButtactionBar() {
return (
<XDSHStack gap={1}>
<XDSIconButton
diff --git a/packages/cli/templates/pages/product-detail/page.tsx b/packages/cli/templates/pages/product-detail/page.tsx
index 7df93703f7..cfca4e626e 100644
--- a/packages/cli/templates/pages/product-detail/page.tsx
+++ b/packages/cli/templates/pages/product-detail/page.tsx
@@ -309,7 +309,7 @@ function ProductInfo() {
label="Decrease quantity"
variant="ghost"
icon={<XDSIcon icon={MinusIcon} size="sm" />}
- onClickAction={decrement}
+ clickAction={decrement}
isDisabled={(quantity ?? 1) <= 1}
isIconOnly
/>
@@ -328,7 +328,7 @@ function ProductInfo() {
label="Increase quantity"
variant="ghost"
icon={<XDSIcon icon={PlusIcon} size="sm" />}
- onClickAction={increment}
+ clickAction={increment}
isDisabled={(quantity ?? 1) >= 10}
isIconOnly
/>
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index d2c8f3a61b..503f8e1170 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -116,7 +116,7 @@ export const docs = {
'Standard click handler (passed through from ButtonHTMLAttributes).',
},
{
- name: 'onClickAction',
+ name: 'clickAction',
type: '(e: MouseEvent) => void | Promise<void>',
description:
'Async click handler. Shows loading state while the returned promise is pending.',
@@ -192,7 +192,7 @@ export const docsZh = {
{name: 'tooltip', type: 'string', description: '悬停时显示的提示文本。'},
{name: 'onClick', type: '(e: MouseEvent) => void', description: '标准点击处理函数(从 ButtonHTMLAttributes 透传)。'},
{
- name: 'onClickAction',
+ name: 'clickAction',
type: '(e: MouseEvent) => void | Promise<void>',
description: '异步点击处理函数。返回的 Promise 处于 pending 状态时显示加载状态。',
},
@@ -250,8 +250,8 @@ export const docsDense = {
children: 'optional visible content; rendered instead of label when provided',
endContent: 'trailing icon/badge after label; ignored when isIconOnly; color inherited',
tooltip: 'tooltip on hover',
- onClick: 'standard click handler; fires before onClickAction',
- onClickAction: 'async click handler; shows loading while promise pending',
+ onClick: 'standard click handler; fires before clickAction',
+ clickAction: 'async click handler; shows loading while promise pending',
isDisabled: 'disables button; uses aria-disabled when tooltip present',
},
};
diff --git a/packages/core/src/Button/XDSButton.test.tsx b/packages/core/src/Button/XDSButton.test.tsx
index ee43887a17..8a5ea65fdc 100644
--- a/packages/core/src/Button/XDSButton.test.tsx
+++ b/packages/core/src/Button/XDSButton.test.tsx
@@ -193,27 +193,27 @@ describe('XDSButton', () => {
expect(button.className).toContain('sm');
});
- // P0: onClick fires before onClickAction, onClickAction respects preventDefault
- it('fires onClick before onClickAction', async () => {
+ // P0: onClick fires before clickAction, clickAction respects preventDefault
+ it('fires onClick before clickAction', async () => {
const user = userEvent.setup();
const order: string[] = [];
const handleClick = vi.fn(() => order.push('onClick'));
- const handleAction = vi.fn(() => order.push('onClickAction'));
+ const handleAction = vi.fn(() => order.push('clickAction'));
render(
<XDSButton
label="Test"
onClick={handleClick}
- onClickAction={handleAction}
+ clickAction={handleAction}
/>,
);
await user.click(screen.getByRole('button'));
expect(handleClick).toHaveBeenCalledTimes(1);
expect(handleAction).toHaveBeenCalledTimes(1);
- expect(order).toEqual(['onClick', 'onClickAction']);
+ expect(order).toEqual(['onClick', 'clickAction']);
});
- it('does not call onClickAction when onClick calls preventDefault', async () => {
+ it('does not call clickAction when onClick calls preventDefault', async () => {
const user = userEvent.setup();
const handleClick = vi.fn((e: React.MouseEvent) => e.preventDefault());
const handleAction = vi.fn();
@@ -221,7 +221,7 @@ describe('XDSButton', () => {
<XDSButton
label="Test"
onClick={handleClick}
- onClickAction={handleAction}
+ clickAction={handleAction}
/>,
);
diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsx
index ed04ef96be..b174db0ad8 100644
--- a/packages/core/src/Button/XDSButton.tsx
+++ b/packages/core/src/Button/XDSButton.tsx
@@ -13,7 +13,7 @@
* - /apps/storybook/stories/Button.stories.tsx (storybook stories)
* - /packages/cli/templates/blocks/components/Button/ (showcase blocks)
*
- * Last synced props: label, variant, size, isDisabled, isLoading, onClickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
+ * Last synced props: label, variant, size, isDisabled, isLoading, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
*/
import {useRef, useTransition, type ReactNode} from 'react';
@@ -315,13 +315,13 @@ export interface XDSButtonProps extends XDSBaseProps<HTMLButtonElement> {
isLoading?: boolean;
/**
* Click handler. For async actions that should show a loading state,
- * use `onClickAction` instead.
+ * use `clickAction` instead.
*/
onClick?: React.MouseEventHandler<HTMLButtonElement>;
/**
* Async click action. Shows loading state while pending.
*/
- onClickAction?: (
+ clickAction?: (
e: React.MouseEvent<HTMLButtonElement>,
) => void | Promise<void>;
/**
@@ -422,7 +422,7 @@ export function XDSButton({
type = 'button',
isDisabled = false,
isLoading = false,
- onClickAction,
+ clickAction,
icon,
isIconOnly = false,
children,
@@ -464,11 +464,11 @@ export function XDSButton({
return;
}
props.onClick?.(e);
- if (onClickAction && !e.defaultPrevented) {
+ if (clickAction && !e.defaultPrevented) {
actionInFlightRef.current = true;
startTransition(async () => {
try {
- await onClickAction(e);
+ await clickAction(e);
} finally {
actionInFlightRef.current = false;
}
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index c2f7bb14ed..7cc901eb07 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -37,7 +37,7 @@ export const docs = {
props: [
{name: 'children', type: 'ReactNode', description: 'Message elements — typically XDSChatMessage or XDSChatSystemMessage.', required: true},
{name: 'emptyState', type: 'ReactNode', description: 'Content shown when the list has no messages.'},
- {name: 'onScrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.'},
+ {name: 'scrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.'},
{name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density — flows to child messages via context.', default: "'balanced'"},
],
},
@@ -267,7 +267,7 @@ export const docsZh = {
propDescriptions: {
children: '消息元素,通常是 XDSChatMessage 或 XDSChatSystemMessage。',
emptyState: '列表无消息时显示的内容。',
- onScrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
+ scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
density: '视觉密度,通过上下文传递给子消息。',
},
},
@@ -438,7 +438,7 @@ export const docsDense = {
propDescriptions: {
children: 'msg elements (XDSChatMessage or XDSChatSystemMessage)',
emptyState: 'content when no msgs',
- onScrollToTopAction: 'async action at scroll top; load older msgs',
+ scrollToTopAction: 'async action at scroll top; load older msgs',
density: 'visual density; flows to children via context',
},
},
diff --git a/packages/core/src/Chat/XDSChatMessageList.tsx b/packages/core/src/Chat/XDSChatMessageList.tsx
index f97b307657..72c5c5025b 100644
--- a/packages/core/src/Chat/XDSChatMessageList.tsx
+++ b/packages/core/src/Chat/XDSChatMessageList.tsx
@@ -31,7 +31,11 @@ import {
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {spacingVars} from '../theme/tokens.stylex';
-import {XDSChatListContext, type XDSChatDensity, useXDSChatLayoutContext} from './XDSChatContext';
+import {
+ XDSChatListContext,
+ type XDSChatDensity,
+ useXDSChatLayoutContext,
+} from './XDSChatContext';
import {xdsClassName, mergeProps} from '../utils';
import {XDSSpinner} from '../Spinner';
@@ -55,7 +59,7 @@ export interface XDSChatMessageListProps {
* Use for loading older messages. Wrapped in useTransition —
* shows a spinner at the top while pending.
*/
- onScrollToTopAction?: () => Promise<void>;
+ scrollToTopAction?: () => Promise<void>;
/**
* Visual density — flows to child messages via context.
@@ -135,7 +139,7 @@ const styles = stylex.create({
*
* Renders messages in a flex column with density-based spacing.
* A spacer pushes content to the bottom when the list isn't full.
- * Supports loading older messages via `onScrollToTopAction`.
+ * Supports loading older messages via `scrollToTopAction`.
*
* Auto-scroll and the scroll-to-bottom button are owned by
* XDSChatLayout. Use useXDSChatStreamScroll for standalone scroll control.
@@ -152,7 +156,7 @@ const styles = stylex.create({
export function XDSChatMessageList({
children,
emptyState,
- onScrollToTopAction,
+ scrollToTopAction,
density = 'balanced',
xstyle,
className,
@@ -181,13 +185,13 @@ export function XDSChatMessageList({
// IntersectionObserver for scroll-to-top infinite scroll
useEffect(() => {
const scrollContainer = layoutContext?.scrollContainerRef?.current;
- if (!onScrollToTopAction || !sentinelRef.current) return;
+ if (!scrollToTopAction || !sentinelRef.current) return;
const observer = new IntersectionObserver(
entries => {
if (entries[0]?.isIntersecting) {
startTransition(async () => {
- await onScrollToTopAction();
+ await scrollToTopAction();
});
}
},
@@ -196,7 +200,7 @@ export function XDSChatMessageList({
observer.observe(sentinelRef.current);
return () => observer.disconnect();
- }, [onScrollToTopAction, layoutContext]);
+ }, [scrollToTopAction, layoutContext]);
const contextValue = useMemo(() => ({density}), [density]);
@@ -223,7 +227,7 @@ export function XDSChatMessageList({
)}>
<div ref={innerRef} {...stylex.props(styles.inner, gapStyle)}>
{/* Sentinel for infinite scroll */}
- {onScrollToTopAction && <div ref={sentinelRef} aria-hidden />}
+ {scrollToTopAction && <div ref={sentinelRef} aria-hidden />}
{/* Loading spinner at top */}
{isLoadingTop && (
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 567dfc5c6f..92d63c9a07 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -42,7 +42,7 @@ export const docs = {
description: 'Callback fired when the checkbox state changes.',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
description:
'Async action on change. Fires after onChange if not prevented. Shows loading spinner while pending.',
@@ -144,7 +144,7 @@ export const docsZh = {
{name: 'value', type: "boolean | 'indeterminate'", description: '复选框是否为选中、未选中或不确定状态。', required: true},
{name: 'onChange', type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void', description: '复选框状态变更时触发的回调。'},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type:
'(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
description: '异步变更操作。在 onChange 之后触发(未被阻止时)。等待期间显示加载旋转器。',
@@ -193,7 +193,7 @@ export const docsDense = {
description: 'text below label',
value: 'checked, unchecked, or indeterminate',
onChange: 'callback on state change',
- onChangeAction: 'async action; fires after onChange, shows spinner while pending',
+ changeAction: 'async action; fires after onChange, shows spinner while pending',
isLoading: 'shows spinner + prevents interaction',
isDisabled: 'disable checkbox',
isOptional: 'mark field as optional (mutually exclusive w/ isRequired)',
diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
index dce4e7e593..85f7687a34 100644
--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
@@ -240,7 +240,7 @@ export interface XDSCheckboxInputProps extends Omit<XDSBaseProps, 'onChange'> {
/**
* Async action on change. Fires after onChange if not prevented.
*/
- onChangeAction?: (
+ changeAction?: (
checked: boolean,
e: ChangeEvent<HTMLInputElement>,
) => void | Promise<void>;
@@ -324,7 +324,7 @@ export function XDSCheckboxInput({
isLabelHidden = false,
description,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
value,
isDisabled = false,
@@ -398,10 +398,10 @@ export function XDSCheckboxInput({
if (isBusy || isReadOnly) return;
const checked = e.target.checked;
onChange?.(checked, e);
- if (onChangeAction && !e.defaultPrevented) {
+ if (changeAction && !e.defaultPrevented) {
startTransition(async () => {
setOptimisticValue(checked);
- await onChangeAction(checked, e);
+ await changeAction(checked, e);
});
}
}}
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index c07ac792fb..b8f659e257 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -33,7 +33,7 @@ export const docs = {
description: 'Callback fired when the selected values change.',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(values: string[]) => void | Promise<void>',
description: 'Async action on change with optimistic updates.',
},
@@ -164,7 +164,7 @@ export const docsZh = {
{name: 'children', type: 'ReactNode', description: 'XDSCheckboxListItem 元素。', required: true},
{name: 'value', type: 'string[]', description: '当前选中的值(集合模式)。'},
{name: 'onChange', type: '(values: string[]) => void', description: '选中值变更时触发的回调函数。'},
- {name: 'onChangeAction', type: '(values: string[]) => void | Promise<void>', description: '变更时的异步操作,配合乐观更新。'},
+ {name: 'changeAction', type: '(values: string[]) => void | Promise<void>', description: '变更时的异步操作,配合乐观更新。'},
{name: 'isLoading', type: 'boolean', description: '外部加载状态。', default: 'false'},
{name: 'isLabelHidden', type: 'boolean', description: '是否在视觉上隐藏标签。', default: 'false'},
{name: 'description', type: 'string', description: '显示在标签下方的描述文本。'},
@@ -215,7 +215,7 @@ export const docsDense = {
children: 'XDSCheckboxListItem elements.',
value: 'Currently selected values (collection mode).',
onChange: 'Callback fired when selected values change.',
- onChangeAction: 'Async action on change w/ optimistic updates.',
+ changeAction: 'Async action on change w/ optimistic updates.',
isLoading: 'External loading state.',
isLabelHidden: 'Whether to visually hide label.',
description: 'Description text below label.',
diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
index 81a0ae533f..3d5e1421c4 100644
--- a/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
+++ b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx
@@ -388,7 +388,7 @@ describe('XDSCheckboxListItem ARIA props', () => {
});
it('sets aria-busy during async actions', () => {
- // Render with a pending async action by providing onChangeAction
+ // Render with a pending async action by providing changeAction
// that returns a promise that never resolves
render(
<XDSCheckboxList label="Prefs" value={['a']} onChange={() => {}}>
diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.tsx
index 7fd8111482..dcf861b1bc 100644
--- a/packages/core/src/CheckboxList/XDSCheckboxList.tsx
+++ b/packages/core/src/CheckboxList/XDSCheckboxList.tsx
@@ -59,7 +59,7 @@ export interface XDSCheckboxListProps {
* Async action on change. Fires after onChange.
* While pending, items show reduced opacity and aria-busy.
*/
- onChangeAction?: (values: string[]) => void | Promise<void>;
+ changeAction?: (values: string[]) => void | Promise<void>;
/**
* Whether the checkbox group is in an external loading state.
* @default false
@@ -145,7 +145,7 @@ export function XDSCheckboxList({
status,
value,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
density = 'balanced',
hasDividers = false,
@@ -170,10 +170,10 @@ export function XDSCheckboxList({
const handleChange = (newValues: string[]) => {
onChange?.(newValues);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValues);
- await onChangeAction(newValues);
+ await changeAction(newValues);
});
}
};
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index aabb3d93ce..e27da9a944 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -50,7 +50,7 @@ export const docs = {
description: 'Callback invoked when the selected date changes.',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: ISODateString | undefined) => void | Promise<void>',
description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',
},
@@ -131,7 +131,7 @@ export const docs = {
{ guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },
{ guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
{ guidance: true, description: 'Use hasClear when the date is optional so the user can easily reset it.' },
- { guidance: true, description: 'Show a loading state with onChangeAction when the date triggers a server-side save.' },
+ { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },
{ guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },
{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
{ guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },
@@ -156,7 +156,7 @@ export const docsZh = {
{ guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },
{ guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
{ guidance: true, description: 'Use hasClear when the date is optional so the user can easily reset it.' },
- { guidance: true, description: 'Show a loading state with onChangeAction when the date triggers a server-side save.' },
+ { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },
{ guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },
{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
{ guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },
@@ -172,7 +172,7 @@ export const docsZh = {
{name: 'value', type: 'ISODateString', description: '选中的日期,YYYY-MM-DD 格式。'},
{name: 'onChange', type: '(value: ISODateString | undefined) => void', description: '选中日期变更时调用的回调。'},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: ISODateString | undefined) => void | Promise<void>',
description: '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',
},
@@ -212,7 +212,7 @@ export const docsDense = {
description: 'DateInput lets the user type or pick a date from a calendar popover. Use for scheduling, deadlines, booking dates, or any form field needing a calendar date.',
bestPractices: [
{ guidance: true, description: 'Clear labels + descriptions. Use min/max/dateConstraints for valid ranges.' },
- { guidance: true, description: 'Use hasClear for optional dates. Use onChangeAction for server-side saves.' },
+ { guidance: true, description: 'Use hasClear for optional dates. Use changeAction for server-side saves.' },
{ guidance: false, description: 'Use for free-form text that is not a calendar date.' },
{ guidance: false, description: 'Hide the label without surrounding context. Don\'t ignore the text input — users can type dates directly.' },
],
@@ -226,7 +226,7 @@ export const docsDense = {
isDisabled: 'disable input+calendar',
value: 'selected date YYYY-MM-DD',
onChange: 'callback on date change',
- onChangeAction: 'async action after onChange; drives optimistic UI',
+ changeAction: 'async action after onChange; drives optimistic UI',
isLoading: 'loading state; disables interaction, shows spinner',
min: 'min selectable date (YYYY-MM-DD)',
max: 'max selectable date (YYYY-MM-DD)',
diff --git a/packages/core/src/DateInput/XDSDateInput.tsx b/packages/core/src/DateInput/XDSDateInput.tsx
index 5e26596c93..5ba7e0fe3c 100644
--- a/packages/core/src/DateInput/XDSDateInput.tsx
+++ b/packages/core/src/DateInput/XDSDateInput.tsx
@@ -179,7 +179,7 @@ export interface XDSDateInputProps extends Omit<
/**
* Async action on change. Fires after onChange.
*/
- onChangeAction?: (value: ISODateString | undefined) => void | Promise<void>;
+ changeAction?: (value: ISODateString | undefined) => void | Promise<void>;
/**
* Whether the input is in a loading state.
@@ -263,7 +263,7 @@ export function XDSDateInput({
isDisabled = false,
value,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
min,
max,
@@ -369,19 +369,19 @@ export function XDSDateInput({
}
}, [isEffectivelyDisabled, popover]);
- // Unified change handler that fires both onChange and onChangeAction
+ // Unified change handler that fires both onChange and changeAction
const fireChange = useCallback(
(newValue: ISODateString | undefined) => {
if (isBusy) return;
onChange?.(newValue);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
- await onChangeAction(newValue);
+ await changeAction(newValue);
});
}
},
- [isBusy, onChange, onChangeAction, startTransition, setOptimisticValue],
+ [isBusy, onChange, changeAction, startTransition, setOptimisticValue],
);
// Handle clear button click
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index 3a4dc52009..3f81666e40 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -54,7 +54,7 @@ export const docs = {
description: 'Standard click handler.',
},
{
- name: 'onClickAction',
+ name: 'clickAction',
type: '(e: MouseEvent) => void | Promise<void>',
description: 'Async click handler with automatic loading state.',
},
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 94c2c22bdb..42ba0c37e4 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -41,7 +41,7 @@ export const docs = {
required: true,
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: string[]) => void | Promise<void>',
description: 'Async action on change. Fires after onChange.',
},
@@ -164,7 +164,7 @@ export const docsZh = {
options: '项目数组——字符串、带 value/label/icon/disabled 的对象、分隔线或分组。',
value: '当前选中的值。',
onChange: '选择变化时触发的回调。',
- onChangeAction: '变化时的异步操作,在 onChange 之后触发。',
+ changeAction: '变化时的异步操作,在 onChange 之后触发。',
placeholder: '未选择值时显示的占位文本。',
size: '选择器的尺寸变体。',
triggerDisplay: '在触发器中显示选中项的方式。',
@@ -221,7 +221,7 @@ export const docsDense = {
options: 'items: strings, objects w/ value/label/icon/disabled, dividers, sections',
value: 'selected values',
onChange: 'callback on selection change',
- onChangeAction: 'async; fires after onChange',
+ changeAction: 'async; fires after onChange',
placeholder: 'text when nothing selected',
size: 'size variant',
triggerDisplay: 'how to show selected in trigger',
diff --git a/packages/core/src/MultiSelector/XDSMultiSelector.tsx b/packages/core/src/MultiSelector/XDSMultiSelector.tsx
index 0aba81831c..5e5b5b97ed 100644
--- a/packages/core/src/MultiSelector/XDSMultiSelector.tsx
+++ b/packages/core/src/MultiSelector/XDSMultiSelector.tsx
@@ -436,7 +436,7 @@ export interface XDSMultiSelectorProps<
/**
* Async action on change. Fires after onChange.
*/
- onChangeAction?: (value: string[]) => void | Promise<void>;
+ changeAction?: (value: string[]) => void | Promise<void>;
/**
* Whether the selector is in a loading state.
@@ -557,7 +557,7 @@ export function XDSMultiSelector<T extends XDSMultiSelectorOptionType>({
options,
value,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
placeholder = 'Select...',
size = 'md',
@@ -714,14 +714,14 @@ export function XDSMultiSelector<T extends XDSMultiSelectorOptionType>({
(e: React.MouseEvent) => {
e.stopPropagation(); // Don't open dropdown
onChange([]);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue([]);
- await onChangeAction([]);
+ await changeAction([]);
});
}
},
- [onChange, onChangeAction, startTransition, setOptimisticValue],
+ [onChange, changeAction, startTransition, setOptimisticValue],
);
const handleToggle = useCallback(
@@ -731,17 +731,17 @@ export function XDSMultiSelector<T extends XDSMultiSelectorOptionType>({
: [...optimisticValue, itemValue];
onChange(newValue);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
- await onChangeAction(newValue);
+ await changeAction(newValue);
});
}
},
[
optimisticValue,
onChange,
- onChangeAction,
+ changeAction,
startTransition,
setOptimisticValue,
],
@@ -789,10 +789,10 @@ export function XDSMultiSelector<T extends XDSMultiSelectorOptionType>({
}
onChange(newValue);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
- await onChangeAction(newValue);
+ await changeAction(newValue);
});
}
}, [
@@ -800,7 +800,7 @@ export function XDSMultiSelector<T extends XDSMultiSelectorOptionType>({
enabledItems,
optimisticValue,
onChange,
- onChangeAction,
+ changeAction,
startTransition,
setOptimisticValue,
]);
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
index 0b9be67696..97e2f93371 100644
--- a/packages/core/src/Pagination/Pagination.doc.mjs
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -17,7 +17,7 @@ export const docs = {
required: true,
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(page: number) => void | Promise<void>',
description:
'Async action on page change. Fires after onChange and uses React transitions for built-in loading state.',
@@ -136,7 +136,7 @@ export const docsZh = {
required: true,
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(page: number) => void | Promise<void>',
description:
'页码变化时的异步操作。在 onChange 之后触发,使用 React transitions 实现内置加载状态。',
@@ -259,7 +259,7 @@ export const docsDense = {
propDescriptions: {
page: 'Current page number (1-based).',
onChange: 'Called on page change.',
- onChangeAction:
+ changeAction:
'Async action on page change. Fires after onChange; uses React transitions for loading.',
totalItems: 'Total items. Calculates page count. Precedence over totalPages.',
totalPages: 'Total pages. Use when page count known but not item count.',
diff --git a/packages/core/src/Pagination/XDSPagination.tsx b/packages/core/src/Pagination/XDSPagination.tsx
index d8976324be..a7d4425a4b 100644
--- a/packages/core/src/Pagination/XDSPagination.tsx
+++ b/packages/core/src/Pagination/XDSPagination.tsx
@@ -12,7 +12,7 @@
* - /apps/storybook/stories/Pagination.stories.tsx (storybook stories)
* - /packages/cli/templates/blocks/components/Pagination/ (showcase blocks)
*
- * Last synced props: page, onChange, onChangeAction, totalItems, totalPages, hasMore,
+ * Last synced props: page, onChange, changeAction, totalItems, totalPages, hasMore,
* pageSize, pageSizeOptions, onPageSizeChange, variant, siblingCount, size, isDisabled,
* label, data-testid, xstyle
*/
@@ -83,7 +83,7 @@ export interface XDSPaginationProps extends Omit<
* Async action on page change. Fires after onChange.
* Uses React transitions for built-in loading state.
*/
- onChangeAction?: (page: number) => void | Promise<void>;
+ changeAction?: (page: number) => void | Promise<void>;
// --- Data shape (provide one) ---
/**
@@ -328,7 +328,7 @@ export function generatePageRange(
export function XDSPagination({
page,
onChange,
- onChangeAction,
+ changeAction,
totalItems,
totalPages: totalPagesProp,
hasMore,
@@ -368,9 +368,9 @@ export function XDSPagination({
const handlePageChange = (newPage: number) => {
if (isDisabled || isPending) return;
onChange(newPage);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
- await onChangeAction(newPage);
+ await changeAction(newPage);
});
}
};
@@ -392,9 +392,9 @@ export function XDSPagination({
onPageSizeChange?.(newSize);
// Reset to page 1 when page size changes
onChange(1);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
- await onChangeAction(1);
+ await changeAction(1);
});
}
};
diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsx
index d3e918641f..1c41e3083c 100644
--- a/packages/core/src/Selector/XDSSelector.tsx
+++ b/packages/core/src/Selector/XDSSelector.tsx
@@ -364,7 +364,7 @@ interface XDSSelectorPropsBase<
*/
options: T[];
- // value, onChange, onChangeAction, and hasClear are in the discriminated union below
+ // value, onChange, changeAction, and hasClear are in the discriminated union below
/**
* Whether the selector is in a loading state.
@@ -427,7 +427,7 @@ type XDSSelectorPropsNonClearable<
hasClear?: false;
value?: string;
onChange?: (value: string) => void;
- onChangeAction?: (value: string) => void | Promise<void>;
+ changeAction?: (value: string) => void | Promise<void>;
};
type XDSSelectorPropsClearable<
@@ -442,7 +442,7 @@ type XDSSelectorPropsClearable<
hasClear: true;
value: string | null;
onChange?: (value: string | null) => void;
- onChangeAction?: (value: string | null) => void | Promise<void>;
+ changeAction?: (value: string | null) => void | Promise<void>;
};
export type XDSSelectorProps<
@@ -488,7 +488,7 @@ export function XDSSelector<T extends XDSSelectorOptionType>(
options,
value,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
placeholder = 'Select...',
size: sizeProp,
@@ -594,14 +594,14 @@ export function XDSSelector<T extends XDSSelectorOptionType>(
onSelect: useCallback(
(newValue: string) => {
onChange?.(newValue);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
- await onChangeAction(newValue);
+ await changeAction(newValue);
});
}
},
- [onChange, onChangeAction, startTransition, setOptimisticValue],
+ [onChange, changeAction, startTransition, setOptimisticValue],
),
listboxId,
});
@@ -611,16 +611,16 @@ export function XDSSelector<T extends XDSSelectorOptionType>(
(e: React.MouseEvent) => {
e.stopPropagation(); // Don't open dropdown
(onChange as ((value: string | null) => void) | undefined)?.(null);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue(undefined as unknown as string);
await (
- onChangeAction as (value: string | null) => void | Promise<void>
+ changeAction as (value: string | null) => void | Promise<void>
)(null);
});
}
},
- [onChange, onChangeAction, startTransition, setOptimisticValue],
+ [onChange, changeAction, startTransition, setOptimisticValue],
);
// Render an individual item
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index 6bd7812462..e58713b0ee 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -28,7 +28,7 @@ export const docs = {
description: 'Callback fired when the switch state changes.',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
description:
'Async action fired after onChange. Triggers optimistic UI and shows a loading spinner until the promise resolves.',
@@ -161,7 +161,7 @@ export const docsZh = {
description: '开关状态变化时触发的回调。',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
description:
'在 onChange 之后触发的异步操作。触发乐观 UI 并显示加载旋转器直到 Promise 完成。',
@@ -284,7 +284,7 @@ export const docsDense = {
label: 'Label text (always rendered for a11y).',
value: 'Whether switch is on or off.',
onChange: 'Fired when switch state changes.',
- onChangeAction: 'Async action after onChange; triggers optimistic UI + loading spinner until resolved.',
+ changeAction: 'Async action after onChange; triggers optimistic UI + loading spinner until resolved.',
isLoading: 'Loading state; shows spinner in thumb.',
isLabelHidden: 'Visually hides label; still accessible to screen readers.',
description: 'Description text below label.',
diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsx
index c0e4e16762..372aa550c3 100644
--- a/packages/core/src/Switch/XDSSwitch.tsx
+++ b/packages/core/src/Switch/XDSSwitch.tsx
@@ -214,7 +214,7 @@ export interface XDSSwitchProps extends Omit<XDSBaseProps, 'onChange'> {
/**
* Async action on change. Fires after onChange if not prevented.
*/
- onChangeAction?: (
+ changeAction?: (
checked: boolean,
e: ChangeEvent<HTMLInputElement>,
) => void | Promise<void>;
@@ -302,7 +302,7 @@ export function XDSSwitch({
isLabelHidden = false,
description,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
value,
isDisabled = false,
@@ -352,10 +352,10 @@ export function XDSSwitch({
if (isBusy) return;
const checked = e.target.checked;
onChange?.(checked, e);
- if (onChangeAction && !e.defaultPrevented) {
+ if (changeAction && !e.defaultPrevented) {
startTransition(async () => {
setOptimisticValue(checked);
- await onChangeAction(checked, e);
+ await changeAction(checked, e);
});
}
}}
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index f02a4f0c19..d78201ee80 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -29,7 +29,7 @@ export const docs = {
description: 'Callback fired when the textarea value changes.',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>',
description:
'Async action fired after onChange inside a React transition. Enables optimistic updates via useOptimistic.',
@@ -195,7 +195,7 @@ export const docsZh = {
description: '文本域值变化时触发的回调。',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>',
description: '在 React transition 内于 onChange 之后触发的异步操作。通过 useOptimistic 启用乐观更新。',
},
@@ -344,7 +344,7 @@ export const docsDense = {
label: 'Label text for textarea; always rendered for a11y.',
value: 'Current textarea value.',
onChange: 'Fired on textarea value change.',
- onChangeAction: 'Async action after onChange in React transition. Enables useOptimistic.',
+ changeAction: 'Async action after onChange in React transition. Enables useOptimistic.',
isLabelHidden: 'Visually hides label; keeps screen reader access.',
description: 'Helper text between label+textarea.',
isOptional: 'Shows "Optional" indicator. Mutually exclusive w/ isRequired.',
diff --git a/packages/core/src/TextArea/XDSTextArea.tsx b/packages/core/src/TextArea/XDSTextArea.tsx
index 84903fc727..3706cf497d 100644
--- a/packages/core/src/TextArea/XDSTextArea.tsx
+++ b/packages/core/src/TextArea/XDSTextArea.tsx
@@ -161,7 +161,7 @@ export interface XDSTextAreaProps extends Omit<
*/
onChange?: (value: string, e: ChangeEvent<HTMLTextAreaElement>) => void;
/** Async action on change. Fires after onChange if not prevented. */
- onChangeAction?: (
+ changeAction?: (
value: string,
e: ChangeEvent<HTMLTextAreaElement>,
) => void | Promise<void>;
@@ -252,7 +252,7 @@ export function XDSTextArea({
isOptional = false,
isRequired = false,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
value = '',
placeholder,
@@ -312,10 +312,10 @@ export function XDSTextArea({
const handleChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
const newValue = e.target.value;
onChange?.(newValue, e);
- if (onChangeAction && !e.defaultPrevented) {
+ if (changeAction && !e.defaultPrevented) {
startTransition(async () => {
setOptimisticValue(newValue);
- await onChangeAction(newValue, e);
+ await changeAction(newValue, e);
});
}
};
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 4768ab72fc..07d1c016b1 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -30,7 +30,7 @@ export const docs = {
description: 'Callback fired when the input value changes.',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: string, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
description:
'Async action fired after onChange (if not prevented). Triggers optimistic update and shows a loading spinner while pending.',
@@ -182,7 +182,7 @@ export const docsZh = {
description: '输入框值变化时触发的回调。',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: string, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
description:
'在 onChange 之后(如果未被阻止)触发的异步操作。触发乐观更新并在挂起时显示加载旋转器。',
@@ -334,7 +334,7 @@ export const docsDense = {
label: 'Label text for input; always rendered for a11y.',
value: 'Current input value.',
onChange: 'Fired on input value change.',
- onChangeAction: 'Async action after onChange (if not prevented). Triggers optimistic update+spinner while pending.',
+ changeAction: 'Async action after onChange (if not prevented). Triggers optimistic update+spinner while pending.',
size: 'Size variant of input.',
isLabelHidden: 'Visually hides label; keeps screen reader access.',
description: 'Description text between label+input.',
diff --git a/packages/core/src/TextInput/XDSTextInput.tsx b/packages/core/src/TextInput/XDSTextInput.tsx
index 5817f73bd9..838908a6f4 100644
--- a/packages/core/src/TextInput/XDSTextInput.tsx
+++ b/packages/core/src/TextInput/XDSTextInput.tsx
@@ -178,7 +178,7 @@ export interface XDSTextInputProps extends Omit<
*/
onChange?: (value: string, e: ChangeEvent<HTMLInputElement>) => void;
/** Async action on change. Fires after onChange if not prevented. */
- onChangeAction?: (
+ changeAction?: (
value: string,
e: ChangeEvent<HTMLInputElement>,
) => void | Promise<void>;
@@ -243,7 +243,7 @@ export function XDSTextInput({
status,
size: sizeProp,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
value = '',
placeholder,
@@ -297,10 +297,10 @@ export function XDSTextInput({
const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
const newValue = e.target.value;
onChange?.(newValue, e);
- if (onChangeAction && !e.defaultPrevented) {
+ if (changeAction && !e.defaultPrevented) {
startTransition(async () => {
setOptimisticValue(newValue);
- await onChangeAction(newValue, e);
+ await changeAction(newValue, e);
});
}
};
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 9b377feb03..53087e6841 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -77,7 +77,7 @@ export const docs = {
'Callback fired when the time changes. Receives undefined when the input is cleared.',
},
{
- name: 'onChangeAction',
+ name: 'changeAction',
type: '(value: ISOTimeString | undefined) => void | Promise<void>',
description:
'Async action fired after onChange. Wrapped in a React transition to provide optimistic UI; triggers the loading spinner while pending.',
@@ -179,7 +179,7 @@ export const docsZh = {
{name: 'isDisabled', type: 'boolean', description: '禁用输入框并抑制交互。', default: 'false'},
{name: 'value', type: 'ISOTimeString', description: 'ISO 格式的受控时间值(HH:MM 或 HH:MM:SS)。'},
{name: 'onChange', type: '(value: ISOTimeString | undefined) => void', description: '时间变化时触发的回调。输入被清除时接收 undefined。'},
- {name: 'onChangeAction', type: '(value: ISOTimeString | undefined) => void | Promise<void>', description: '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI;挂起时触发加载旋转器。'},
+ {name: 'changeAction', type: '(value: ISOTimeString | undefined) => void | Promise<void>', description: '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI;挂起时触发加载旋转器。'},
{name: 'isLoading', type: 'boolean', description: '使输入框进入加载状态,显示旋转器。', default: 'false'},
{name: 'min', type: 'ISOTimeString', description: 'ISO 格式的最小可选时间。超出范围的值将被拒绝。'},
{name: 'max', type: 'ISOTimeString', description: 'ISO 格式的最大可选时间。超出范围的值将被拒绝。'},
@@ -245,7 +245,7 @@ export const docsDense = {
isDisabled: 'Disables input, suppresses interactions.',
value: 'Controlled time in ISO format (HH:MM or HH:MM:SS).',
onChange: 'Fired on time change. Receives undefined when cleared.',
- onChangeAction: 'Async action after onChange in React transition; triggers spinner while pending.',
+ changeAction: 'Async action after onChange in React transition; triggers spinner while pending.',
isLoading: 'Loading state w/ spinner.',
min: 'Min selectable time in ISO format. Out-of-range rejected.',
max: 'Max selectable time in ISO format. Out-of-range rejected.',
diff --git a/packages/core/src/TimeInput/XDSTimeInput.tsx b/packages/core/src/TimeInput/XDSTimeInput.tsx
index c46f770efd..d9add4a04a 100644
--- a/packages/core/src/TimeInput/XDSTimeInput.tsx
+++ b/packages/core/src/TimeInput/XDSTimeInput.tsx
@@ -190,7 +190,7 @@ export interface XDSTimeInputProps extends Omit<
/**
* Async action on change. Fires after onChange.
*/
- onChangeAction?: (value: ISOTimeString | undefined) => void | Promise<void>;
+ changeAction?: (value: ISOTimeString | undefined) => void | Promise<void>;
/**
* Whether the input is in a loading state.
@@ -290,7 +290,7 @@ export function XDSTimeInput({
isDisabled = false,
value,
onChange,
- onChangeAction,
+ changeAction,
isLoading = false,
min,
max,
@@ -352,18 +352,18 @@ export function XDSTimeInput({
const formatDisplayTime =
hourFormat === '12h' ? formatDisplayTime12h : formatDisplayTime24h;
- // Unified change handler that fires both onChange and onChangeAction
+ // Unified change handler that fires both onChange and changeAction
const fireChange = useCallback(
(newValue: ISOTimeString | undefined) => {
onChange?.(newValue);
- if (onChangeAction) {
+ if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
- await onChangeAction(newValue);
+ await changeAction(newValue);
});
}
},
- [onChange, onChangeAction, startTransition, setOptimisticValue],
+ [onChange, changeAction, startTransition, setOptimisticValue],
);
// Display value: pending input if typing, otherwise formatted value
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index 5584b29d46..708f9fd665 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -17,7 +17,7 @@ export const docs = {
{name: 'label', type: 'string', description: 'Accessible label for the button. Used as visible text, or as aria-label for icon-only buttons.', required: true},
{name: 'isPressed', type: 'boolean', description: 'Whether the button is currently pressed. Ignored when inside a group.'},
{name: 'onPressedChange', type: '(isPressed: boolean) => void', description: 'Called when pressed state should change. Ignored when inside a group.'},
- {name: 'onPressedChangeAction', type: '(isPressed: boolean) => Promise<void>', description: 'Async action handler for API-backed toggles. Shows loading spinner while pending.'},
+ {name: 'pressedChangeAction', type: '(isPressed: boolean) => Promise<void>', description: 'Async action handler for API-backed toggles. Shows loading spinner while pending.'},
{name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Button size. Defaults to group size when inside a group.', default: "'md'"},
{name: 'isDisabled', type: 'boolean', description: 'Whether the button is disabled.', default: 'false'},
{name: 'isLoading', type: 'boolean', description: 'Whether the button shows a loading spinner.', default: 'false'},
@@ -60,7 +60,7 @@ export const docs = {
{name: 'Icon', required: false, description: 'A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.'},
{name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state.'},
{name: 'Label', required: true, description: 'The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.'},
- {name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by onPressedChangeAction.'},
+ {name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by pressedChangeAction.'},
],
},
};
@@ -75,7 +75,7 @@ export const docsZh = {
label: '按钮的无障碍标签。作为可见文本或仅图标按钮的 aria-label。',
isPressed: '按钮是否处于按下状态。在分组内时被忽略。',
onPressedChange: '按下状态变更时的回调。在分组内时被忽略。',
- onPressedChangeAction: 'API 调用的异步操作处理器。等待期间显示加载动画。',
+ pressedChangeAction: 'API 调用的异步操作处理器。等待期间显示加载动画。',
size: '按钮尺寸。在分组内时默认使用分组尺寸。',
isDisabled: '按钮是否禁用。',
isLoading: '按钮是否显示加载动画。',
@@ -119,7 +119,7 @@ export const docsZh = {
{name: 'Icon', required: false, description: 'A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.'},
{name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state.'},
{name: 'Label', required: true, description: 'The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.'},
- {name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by onPressedChangeAction.'},
+ {name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by pressedChangeAction.'},
],
},
};
@@ -147,7 +147,7 @@ export const docsDense = {
label: 'a11y label; visible text or aria-label for icon-only',
isPressed: 'pressed state; ignored in group',
onPressedChange: 'pressed state change cb; ignored in group',
- onPressedChangeAction: 'async toggle handler w/ loading spinner',
+ pressedChangeAction: 'async toggle handler w/ loading spinner',
size: 'btn size; defaults to group size in group',
isDisabled: 'disabled state',
isLoading: 'shows loading spinner',
diff --git a/packages/core/src/ToggleButton/XDSToggleButton.tsx b/packages/core/src/ToggleButton/XDSToggleButton.tsx
index 5bf2d4631f..18def7ddcb 100644
--- a/packages/core/src/ToggleButton/XDSToggleButton.tsx
+++ b/packages/core/src/ToggleButton/XDSToggleButton.tsx
@@ -96,13 +96,13 @@ export interface XDSToggleButtonProps {
* label="Favorite"
* isPressed={isFavorited}
* onPressedChange={setIsFavorited}
- * onPressedChangeAction={async (newState) => {
+ * pressedChangeAction={async (newState) => {
* await api.setFavorite(itemId, newState);
* }}
* />
* ```
*/
- onPressedChangeAction?: (isPressed: boolean) => Promise<void>;
+ pressedChangeAction?: (isPressed: boolean) => Promise<void>;
/**
* The size of the toggle button.
@@ -217,7 +217,7 @@ export function XDSToggleButton({
label,
isPressed: isPressedProp,
onPressedChange: onPressedChangeProp,
- onPressedChangeAction,
+ pressedChangeAction,
size: sizeProp,
isDisabled: isDisabledProp = false,
isLoading = false,
@@ -255,8 +255,8 @@ export function XDSToggleButton({
// Standalone toggle
const newState = !isPressed;
onPressedChangeProp(newState);
- if (onPressedChangeAction) {
- onPressedChangeAction(newState);
+ if (pressedChangeAction) {
+ pressedChangeAction(newState);
}
}
}, [
@@ -265,7 +265,7 @@ export function XDSToggleButton({
group,
value,
onPressedChangeProp,
- onPressedChangeAction,
+ pressedChangeAction,
isPressed,
]);