Skip to content

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

TypeScript

fix(api): unify uncontrolled state props to defaultX pattern (#466) (#470)

Cindy Zhangc329e119911a
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsx
index c84a0017c9..9c20006b0d 100644
--- a/apps/storybook/stories/AppShell.stories.tsx
+++ b/apps/storybook/stories/AppShell.stories.tsx
@@ -236,7 +236,7 @@ const meta: Meta<typeof XDSAppShell> = {
control: 'radio',
options: ['fill', 'auto'],
},
- initialIsSideNavCollapsed: {
+ defaultIsSideNavCollapsed: {
control: 'boolean',
description: 'Whether the side nav starts collapsed',
},
diff --git a/apps/storybook/stories/Banner.stories.tsx b/apps/storybook/stories/Banner.stories.tsx
index 6736dfe59e..2756a51e90 100644
--- a/apps/storybook/stories/Banner.stories.tsx
+++ b/apps/storybook/stories/Banner.stories.tsx
@@ -24,7 +24,7 @@ const meta: Meta<typeof XDSBanner> = {
description:
'Whether the banner can be dismissed (manages its own hidden state)',
},
- isDefaultExpanded: {
+ defaultIsExpanded: {
control: 'boolean',
description:
'Whether the content area starts expanded (only relevant when children are provided)',
@@ -137,7 +137,7 @@ export const CollapsibleContentExpanded: Story = {
status: 'info',
title: 'Emphasized Text',
description: 'Description text',
- isDefaultExpanded: true,
+ defaultIsExpanded: true,
endContent: <XDSButton label="Button" variant="secondary" size="sm" />,
isDismissable: true,
children: (
@@ -160,7 +160,7 @@ export const WithContentArea: Story = {
status: 'error',
title: 'Multiple errors found',
description: 'The following issues need to be resolved:',
- isDefaultExpanded: true,
+ defaultIsExpanded: true,
children: (
<ul style={{margin: 0, paddingInlineStart: '20px', fontSize: '13px'}}>
<li>Email address is invalid</li>
@@ -179,7 +179,7 @@ export const ContentAreaWithAction: Story = {
description: 'Review the changes before they take effect.',
endContent: <XDSButton label="Review" variant="secondary" size="sm" />,
isDismissable: true,
- isDefaultExpanded: true,
+ defaultIsExpanded: true,
children: (
<div style={{fontSize: '13px'}}>
<p style={{margin: '0 0 8px'}}>Changed settings:</p>
@@ -245,10 +245,10 @@ export const AllFeatures: Story = {
status="success"
title="Expanded by default"
description="This content area starts open."
- isDefaultExpanded
+ defaultIsExpanded
isDismissable>
<div style={{fontSize: '13px'}}>
- Content is visible immediately because isDefaultExpanded is true.
+ Content is visible immediately because defaultIsExpanded is true.
</div>
</XDSBanner>
<XDSBanner
diff --git a/apps/storybook/stories/Collapsible.stories.tsx b/apps/storybook/stories/Collapsible.stories.tsx
index b373cf7214..e9974f1d32 100644
--- a/apps/storybook/stories/Collapsible.stories.tsx
+++ b/apps/storybook/stories/Collapsible.stories.tsx
@@ -153,7 +153,7 @@ export const StandaloneCollapsible: Story = {
</XDSCollapsible>
</XDSCard>
<XDSCard>
- <XDSCollapsible trigger="Starts collapsed" initialIsOpen={false}>
+ <XDSCollapsible trigger="Starts collapsed" defaultIsOpen={false}>
<p {...stylex.props(styles.text)}>
This collapsible starts collapsed. Click to reveal.
</p>
@@ -172,7 +172,7 @@ export const WithoutCard: Story = {
XDSCollapsible works anywhere — it doesn't require a card wrapper.
</p>
</XDSCollapsible>
- <XDSCollapsible trigger="Another section" initialIsOpen={false}>
+ <XDSCollapsible trigger="Another section" defaultIsOpen={false}>
<p {...stylex.props(styles.text)}>This section starts collapsed.</p>
</XDSCollapsible>
</XDSVStack>
diff --git a/internal/eslint-plugin-xds/boolean-prop-naming.js b/internal/eslint-plugin-xds/boolean-prop-naming.js
index b9eef63ac8..126006f55c 100644
--- a/internal/eslint-plugin-xds/boolean-prop-naming.js
+++ b/internal/eslint-plugin-xds/boolean-prop-naming.js
@@ -5,7 +5,8 @@
* Boolean props in *Props interfaces/types must use:
* - `is` prefix for state/condition booleans (isDisabled, isRequired, isLoading)
* - `has` prefix for feature toggles (hasAutoFocus, hasClear, hasSeconds)
- * - `initialIs` / `initialHas` for uncontrolled boolean defaults
+ * - `defaultIs` / `defaultHas` for uncontrolled boolean defaults
+ * - `initialIs` / `initialHas` (deprecated aliases, kept for backward compat)
*
* Exceptions:
* - aria-* and data-* attributes (follow their own conventions)
@@ -37,6 +38,8 @@ function isValidBooleanPropName(name) {
return (
name.startsWith('is') ||
name.startsWith('has') ||
+ name.startsWith('defaultIs') ||
+ name.startsWith('defaultHas') ||
name.startsWith('initialIs') ||
name.startsWith('initialHas')
);
diff --git a/internal/eslint-plugin-xds/boolean-prop-naming.test.mjs b/internal/eslint-plugin-xds/boolean-prop-naming.test.mjs
index 9e86a8ce49..cf1f42dbe0 100644
--- a/internal/eslint-plugin-xds/boolean-prop-naming.test.mjs
+++ b/internal/eslint-plugin-xds/boolean-prop-naming.test.mjs
@@ -53,6 +53,30 @@ describe('boolean-prop-naming', () => {
}
`,
},
+ // ✅ Correct "defaultIs" prefix
+ {
+ code: `
+ interface XDSCollapsibleProps {
+ defaultIsOpen?: boolean;
+ }
+ `,
+ },
+ // ✅ Correct "defaultHas" prefix
+ {
+ code: `
+ interface XDSSelectorProps {
+ defaultHasSelection?: boolean;
+ }
+ `,
+ },
+ // ✅ Correct "defaultIs" prefix — expanded
+ {
+ code: `
+ interface XDSBannerProps {
+ defaultIsExpanded?: boolean;
+ }
+ `,
+ },
// ✅ Non-boolean prop — should be ignored
{
code: `
diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.md
index 46f41aa524..91a8618117 100644
--- a/packages/core/src/AppShell/README.md
+++ b/packages/core/src/AppShell/README.md
@@ -195,7 +195,7 @@ const isMobile = useMediaQuery('(max-width: 768px)');
| `banner` | `ReactNode` | — | Banner slot for system-wide announcements |
| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior |
| `isSideNavCollapsed` | `boolean` | — | Whether sideNav is collapsed (controlled) |
-| `initialIsSideNavCollapsed` | `boolean` | `false` | Initial collapsed state (uncontrolled) |
+| `defaultIsSideNavCollapsed` | `boolean` | `false` | Default collapsed state (uncontrolled) |
| `mobileNav` | `ReactNode` | — | Mobile navigation (typically XDSMobileNav) |
| `onSideNavCollapsedChange` | `(isCollapsed: boolean) => void` | — | Collapse change callback |
| `sideNavBreakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | Breakpoint for auto-collapse |
@@ -223,7 +223,7 @@ const isMobile = useMediaQuery('(max-width: 768px)');
## SideNav Behavior
- **Controlled**: Use `isSideNavCollapsed` + `onSideNavCollapsedChange`
-- **Uncontrolled**: Use `initialIsSideNavCollapsed`
+- **Uncontrolled**: Use `defaultIsSideNavCollapsed`
- **Responsive**: `sideNavBreakpoint` auto-collapses below the specified width
- **Mobile**: Collapsed sideNav renders as an overlay with backdrop
- **Animations**: Snap open/closed for now; ViewTransitions support planned
diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsx
index fa75e406da..ec542509a7 100644
--- a/packages/core/src/AppShell/XDSAppShell.test.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.test.tsx
@@ -216,11 +216,11 @@ describe('XDSAppShell', () => {
expect(screen.getByRole('navigation')).toBeInTheDocument();
});
- it('sideNav is hidden when initialIsSideNavCollapsed is true', () => {
+ it('sideNav is hidden when defaultIsSideNavCollapsed is true', () => {
render(
<XDSAppShell
sideNav={<div>Nav Items</div>}
- initialIsSideNavCollapsed={true}>
+ defaultIsSideNavCollapsed={true}>
<div>Content</div>
</XDSAppShell>,
);
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 13682af0e1..718c2991e0 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -92,10 +92,10 @@ export interface XDSAppShellProps {
height?: 'fill' | 'auto';
/**
- * Initial collapsed state for uncontrolled usage.
+ * Default collapsed state for uncontrolled usage.
* @default false
*/
- initialIsSideNavCollapsed?: boolean;
+ defaultIsSideNavCollapsed?: boolean;
/**
* Whether the side nav is collapsed (controlled).
@@ -281,7 +281,7 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
children,
'data-testid': dataTestId,
height = 'fill',
- initialIsSideNavCollapsed = false,
+ defaultIsSideNavCollapsed = false,
isSideNavCollapsed: controlledCollapsed,
mobileNav,
onSideNavCollapsedChange,
@@ -298,7 +298,7 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
// =========================================================================
const isControlled = controlledCollapsed !== undefined;
const [uncontrolledCollapsed, setUncontrolledCollapsed] = useState(
- initialIsSideNavCollapsed,
+ defaultIsSideNavCollapsed,
);
const isCollapsed = isControlled
? controlledCollapsed
diff --git a/packages/core/src/Banner/XDSBanner.test.tsx b/packages/core/src/Banner/XDSBanner.test.tsx
index 909e38b6f7..e686631b55 100644
--- a/packages/core/src/Banner/XDSBanner.test.tsx
+++ b/packages/core/src/Banner/XDSBanner.test.tsx
@@ -175,9 +175,9 @@ describe('XDSBanner', () => {
expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
});
- it('shows children when isDefaultExpanded is true', () => {
+ it('shows children when defaultIsExpanded is true', () => {
render(
- <XDSBanner status="info" title="Expanded" isDefaultExpanded>
+ <XDSBanner status="info" title="Expanded" defaultIsExpanded>
<div data-testid="child-content">Extra content</div>
</XDSBanner>,
);
@@ -226,9 +226,9 @@ describe('XDSBanner', () => {
expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
});
- it('shows collapse button when isDefaultExpanded', () => {
+ it('shows collapse button when defaultIsExpanded', () => {
render(
- <XDSBanner status="info" title="Expanded" isDefaultExpanded>
+ <XDSBanner status="info" title="Expanded" defaultIsExpanded>
<div>Content</div>
</XDSBanner>,
);
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index 3df2565311..d5f84b108e 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -105,7 +105,7 @@ export interface XDSBannerProps {
* Only relevant when children are provided.
* @default false
*/
- isDefaultExpanded?: boolean;
+ defaultIsExpanded?: boolean;
/**
* Extra content rendered below the header in a collapsible card-background area.
* Use for rich content like lists, links, or detailed information.
@@ -313,7 +313,7 @@ const statusStyles = stylex.create({
* <XDSBanner
* status="warning"
* title="Configuration changes"
- * isDefaultExpanded
+ * defaultIsExpanded
* >
* <p>Details here...</p>
* </XDSBanner>
@@ -330,7 +330,7 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
onDismiss,
endContent,
variant = 'card',
- isDefaultExpanded = false,
+ defaultIsExpanded = false,
children,
xstyle,
'data-testid': testId,
@@ -338,7 +338,7 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
ref,
) => {
const [isDismissed, setIsDismissed] = useState(false);
- const [isExpanded, setIsExpanded] = useState(isDefaultExpanded);
+ const [isExpanded, setIsExpanded] = useState(defaultIsExpanded);
const DefaultIcon = defaultIcons[status];
const role = statusRole[status];
const iconColor = statusIconColor[status];
diff --git a/packages/core/src/Collapsible/README.md b/packages/core/src/Collapsible/README.md
index cc2728600f..1ab93a3440 100644
--- a/packages/core/src/Collapsible/README.md
+++ b/packages/core/src/Collapsible/README.md
@@ -30,7 +30,7 @@ import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
// Starts collapsed
<XDSCard>
- <XDSCollapsible trigger="Advanced" initialIsOpen={false}>
+ <XDSCollapsible trigger="Advanced" defaultIsOpen={false}>
<p>Hidden by default</p>
</XDSCollapsible>
</XDSCard>
@@ -107,7 +107,7 @@ import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
| --------------- | --------------------------- | ------- | -------------------------------------------------- |
| `trigger` | `ReactNode` | — | Content shown in the trigger area (always visible) |
| `children` | `ReactNode` | — | Content that collapses/expands |
-| `initialIsOpen` | `boolean` | `true` | Initial open state (uncontrolled) |
+| `defaultIsOpen` | `boolean` | `true` | Default open state (uncontrolled) |
| `isOpen` | `boolean` | — | Controlled open state |
| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when open state changes |
| `value` | `string` | — | Identifier for group coordination |
diff --git a/packages/core/src/Collapsible/XDSCollapsible.tsx b/packages/core/src/Collapsible/XDSCollapsible.tsx
index b74fa8d74e..04ee7a6ea6 100644
--- a/packages/core/src/Collapsible/XDSCollapsible.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsible.tsx
@@ -83,10 +83,10 @@ export interface XDSCollapsibleProps {
children?: ReactNode;
/**
- * Initial open state for uncontrolled usage.
+ * Default open state for uncontrolled usage.
* @default true
*/
- initialIsOpen?: boolean;
+ defaultIsOpen?: boolean;
/**
* Controlled open state. When provided, the component is fully controlled.
@@ -154,7 +154,7 @@ export const XDSCollapsible = forwardRef<HTMLDivElement, XDSCollapsibleProps>(
{
trigger,
children,
- initialIsOpen,
+ defaultIsOpen,
isOpen: controlledIsOpen,
onOpenChange,
value,
@@ -166,7 +166,7 @@ export const XDSCollapsible = forwardRef<HTMLDivElement, XDSCollapsibleProps>(
const collapsibleConfig =
controlledIsOpen !== undefined
? {isOpen: controlledIsOpen, onOpenChange}
- : {initialIsOpen: initialIsOpen ?? true, onOpenChange};
+ : {defaultIsOpen: defaultIsOpen ?? true, onOpenChange};
const {isOpen, toggle} = useXDSCollapsible({
isCollapsible: collapsibleConfig,
diff --git a/packages/core/src/Collapsible/XDSCollapsibleGroup.test.tsx b/packages/core/src/Collapsible/XDSCollapsibleGroup.test.tsx
index 898f4ff49a..37647f3835 100644
--- a/packages/core/src/Collapsible/XDSCollapsibleGroup.test.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsibleGroup.test.tsx
@@ -63,9 +63,9 @@ describe('XDSCollapsible', () => {
expect(screen.getByText('Collapsible content')).toBeVisible();
});
- it('starts collapsed when initialIsOpen is false', () => {
+ it('starts collapsed when defaultIsOpen is false', () => {
render(
- <XDSCollapsible trigger="Details" initialIsOpen={false}>
+ <XDSCollapsible trigger="Details" defaultIsOpen={false}>
<p>Hidden content</p>
</XDSCollapsible>,
);
diff --git a/packages/core/src/Collapsible/useXDSCollapsible.ts b/packages/core/src/Collapsible/useXDSCollapsible.ts
index b51cd89d64..4be346ccf4 100644
--- a/packages/core/src/Collapsible/useXDSCollapsible.ts
+++ b/packages/core/src/Collapsible/useXDSCollapsible.ts
@@ -24,8 +24,8 @@ import {CollapsibleGroupContext} from './XDSCollapsibleGroupContext';
* Configuration for collapsible behavior.
*/
export type CollapsibleConfig = {
- /** Whether the component starts open. @default true */
- initialIsOpen?: boolean;
+ /** Default open state for uncontrolled usage. @default true */
+ defaultIsOpen?: boolean;
/** Controlled open state. */
isOpen?: boolean;
/** Callback when open state changes. */
@@ -36,7 +36,7 @@ export interface UseXDSCollapsibleOptions {
/**
* Whether the component is collapsible.
* - `true` — self-managed, starts open
- * - `{ initialIsOpen: false }` — self-managed, starts collapsed
+ * - `{ defaultIsOpen: false }` — self-managed, starts collapsed
* - `{ isOpen, onOpenChange }` — controlled externally
*/
isCollapsible?: boolean | CollapsibleConfig;
@@ -62,7 +62,7 @@ export interface UseXDSCollapsibleReturn {
* Supports three modes:
* 1. **Group-controlled**: When inside a CollapsibleGroup with a `value`, defers to group.
* 2. **Controlled**: When `isOpen` and `onOpenChange` are provided in config.
- * 3. **Uncontrolled**: Self-managed internal state with optional `initialIsOpen`.
+ * 3. **Uncontrolled**: Self-managed internal state with optional `defaultIsOpen`.
*
* @example
* ```
@@ -90,7 +90,7 @@ export function useXDSCollapsible(
const [internalIsOpen, setInternalIsOpen] = useState(() => {
if (isControlledByGroup) return true; // group manages this
if (config?.isOpen !== undefined) return config.isOpen;
- return config?.initialIsOpen ?? true;
+ return config?.defaultIsOpen ?? true;
});
// Determine open state from the appropriate source