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.tsxindex 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.tsxindex 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+ defaultIsExpandedisDismissable><div style={{fontSize: '13px'}}>- Content is visible immediately because isDefaultExpanded is true.+ Content is visible immediately because defaultIsExpanded is true.</div></XDSBanner><XDSBannerdiff --git a/apps/storybook/stories/Collapsible.stories.tsx b/apps/storybook/stories/Collapsible.stories.tsxindex 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.jsindex 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.mjsindex 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.mdindex 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 planneddiff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsxindex 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(<XDSAppShellsideNav={<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.tsxindex 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? controlledCollapseddiff --git a/packages/core/src/Banner/XDSBanner.test.tsx b/packages/core/src/Banner/XDSBanner.test.tsxindex 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.tsxindex 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.mdindex 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.tsxindex 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.tsxindex 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.tsindex 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 thisif (config?.isOpen !== undefined) return config.isOpen;- return config?.initialIsOpen ?? true;+ return config?.defaultIsOpen ?? true;});// Determine open state from the appropriate source