@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/Collapsible/CollapsibleGroup.test.tsx

@@ -77,6 +77,22 @@ describe('Collapsible', () => {
     expect(screen.getByText('Hidden content')).not.toBeVisible();
   });
 
+  it('links the trigger to its content region via aria-controls', () => {
+    render(
+      <Collapsible trigger="Details">
+        <p>Region content</p>
+      </Collapsible>,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Details/});
+    const controlsId = trigger.getAttribute('aria-controls');
+    // aria-controls must be present and point at the real content region.
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByText('Region content'));
+  });
+
   it('respects controlled isOpen/onOpenChange', async () => {
     const onOpenChange = vi.fn();
     const user = userEvent.setup();
@@ -111,6 +127,36 @@ describe('Collapsible', () => {
     expect(screen.getByText('Controlled content')).not.toBeVisible();
   });
 
+  it('self-toggles in uncontrolled mode even when onOpenChange is supplied', async () => {
+    // Regression: passing onOpenChange without isOpen must NOT make the
+    // component behave as controlled. Internal state should still drive
+    // visibility, and the callback should fire in addition.
+    const onOpenChange = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <Collapsible trigger="Uncontrolled" onOpenChange={onOpenChange}>
+        <p>Uncontrolled content</p>
+      </Collapsible>,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Uncontrolled/});
+    // Starts open (defaultIsOpen defaults to true).
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    expect(screen.getByText('Uncontrolled content')).toBeVisible();
+
+    // Click collapses via internal state AND notifies.
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(screen.getByText('Uncontrolled content')).not.toBeVisible();
+    expect(onOpenChange).toHaveBeenNthCalledWith(1, false);
+
+    // Click again re-expands — proving the component isn't stuck.
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    expect(screen.getByText('Uncontrolled content')).toBeVisible();
+    expect(onOpenChange).toHaveBeenNthCalledWith(2, true);
+  });
+
   it('renders chevron indicator', () => {
     render(
       <Collapsible trigger="With Chevron">
@@ -397,4 +443,272 @@ describe('CollapsibleGroup', () => {
       expect(trigger).toHaveAttribute('aria-expanded', 'true');
     });
   });
+
+  describe('dividers', () => {
+    function getItem(name: RegExp): HTMLElement {
+      const root = screen
+        .getByRole('button', {name})
+        .closest('.astryx-collapsible');
+      expect(root).not.toBeNull();
+      return root as HTMLElement;
+    }
+
+    it('renders no wrapper DOM by default and with hasDividers={false}', () => {
+      const {container, rerender} = render(
+        <CollapsibleGroup>
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      expect(container.querySelector('.astryx-collapsible-group')).toBeNull();
+
+      rerender(
+        <CollapsibleGroup hasDividers={false}>
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      expect(container.querySelector('.astryx-collapsible-group')).toBeNull();
+    });
+
+    it('renders a wrapper with default density when dividers are enabled', () => {
+      const {container} = render(
+        <CollapsibleGroup hasDividers>
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+          <Collapsible trigger="Item B" value="b">
+            <p>Content B</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      const wrapper = container.querySelector('.astryx-collapsible-group');
+      expect(wrapper).not.toBeNull();
+      // Divided groups default to balanced density
+      expect(wrapper).toHaveAttribute('data-density', 'balanced');
+      expect(wrapper).toContainElement(getItem(/Item A/));
+      expect(wrapper).toContainElement(getItem(/Item B/));
+    });
+
+    it('reflects density on each item when dividers are enabled', () => {
+      render(
+        <CollapsibleGroup hasDividers density="compact">
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(getItem(/Item A/)).toHaveAttribute('data-density', 'compact');
+    });
+
+    it('does not reflect divider chrome on items without dividers', () => {
+      render(
+        <CollapsibleGroup>
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(getItem(/Item A/)).not.toHaveAttribute('data-density');
+    });
+
+    it('applies density without dividers (and without a wrapper)', () => {
+      const {container} = render(
+        <CollapsibleGroup density="spacious">
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(container.querySelector('.astryx-collapsible-group')).toBeNull();
+      expect(getItem(/Item A/)).toHaveAttribute('data-density', 'spacious');
+    });
+
+    it('does not leak divider chrome into nested collapsibles', () => {
+      render(
+        <CollapsibleGroup hasDividers defaultValue="outer">
+          <Collapsible trigger="Outer" value="outer">
+            <Collapsible trigger="Nested">
+              <p>Nested content</p>
+            </Collapsible>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(getItem(/Outer/)).toHaveAttribute('data-density', 'balanced');
+      expect(getItem(/Nested/)).not.toHaveAttribute('data-density');
+    });
+
+    it('keeps group coordination working with dividers enabled', async () => {
+      const user = userEvent.setup();
+      render(
+        <CollapsibleGroup type="single" hasDividers defaultValue="a">
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+          <Collapsible trigger="Item B" value="b">
+            <p>Content B</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(screen.getByText('Content A')).toBeVisible();
+      await user.click(screen.getByRole('button', {name: /Item B/}));
+      expect(screen.getByText('Content A')).not.toBeVisible();
+      expect(screen.getByText('Content B')).toBeVisible();
+    });
+
+    it('applies xstyle/className/style to the wrapper in divider mode', () => {
+      const {container} = render(
+        <CollapsibleGroup
+          hasDividers
+          className="custom-class"
+          data-testid="group">
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      const wrapper = container.querySelector('.astryx-collapsible-group');
+      expect(wrapper).toHaveClass('custom-class');
+      expect(wrapper).toHaveAttribute('data-testid', 'group');
+    });
+
+    it('forwards ref to the wrapper in divider mode', () => {
+      const ref = {current: null as HTMLElement | null};
+      const {container} = render(
+        <CollapsibleGroup hasDividers ref={ref}>
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(ref.current).toBe(
+        container.querySelector('.astryx-collapsible-group'),
+      );
+    });
+
+    it('explicit density overrides the divider default', () => {
+      const {container} = render(
+        <CollapsibleGroup hasDividers density="spacious">
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      const wrapper = container.querySelector('.astryx-collapsible-group');
+      expect(wrapper).toHaveAttribute('data-density', 'spacious');
+      expect(getItem(/Item A/)).toHaveAttribute('data-density', 'spacious');
+    });
+
+    it('tolerates interleaved non-Collapsible children', async () => {
+      const user = userEvent.setup();
+      render(
+        <CollapsibleGroup type="single" hasDividers defaultValue="a">
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+          <hr data-testid="separator" />
+          <Collapsible trigger="Item B" value="b">
+            <p>Content B</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(screen.getByTestId('separator')).toBeInTheDocument();
+      expect(getItem(/Item A/)).toHaveAttribute('data-density', 'balanced');
+      expect(getItem(/Item B/)).toHaveAttribute('data-density', 'balanced');
+      await user.click(screen.getByRole('button', {name: /Item B/}));
+      expect(screen.getByText('Content A')).not.toBeVisible();
+      expect(screen.getByText('Content B')).toBeVisible();
+    });
+
+    it('lets a nested group define its own chrome instead of inheriting', () => {
+      render(
+        <CollapsibleGroup hasDividers defaultValue="outer">
+          <Collapsible trigger="Outer" value="outer">
+            <CollapsibleGroup type="multiple" hasDividers density="compact">
+              <Collapsible trigger="Inner divided" value="in-a">
+                <p>Inner content</p>
+              </Collapsible>
+            </CollapsibleGroup>
+            <CollapsibleGroup type="multiple">
+              <Collapsible trigger="Inner plain" value="in-b">
+                <p>Inner content</p>
+              </Collapsible>
+            </CollapsibleGroup>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      expect(getItem(/Outer/)).toHaveAttribute('data-density', 'balanced');
+      expect(getItem(/Inner divided/)).toHaveAttribute(
+        'data-density',
+        'compact',
+      );
+      expect(getItem(/Inner plain/)).not.toHaveAttribute('data-density');
+    });
+
+    it('keeps controlled coordination and onChange shape with dividers', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const {rerender} = render(
+        <CollapsibleGroup
+          type="single"
+          hasDividers
+          value="a"
+          onChange={onChange}>
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+          <Collapsible trigger="Item B" value="b">
+            <p>Content B</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+
+      await user.click(screen.getByRole('button', {name: /Item B/}));
+      expect(onChange).toHaveBeenCalledWith('b');
+      // Controlled: nothing opens until the parent passes the new value
+      expect(screen.getByText('Content B')).not.toBeVisible();
+
+      rerender(
+        <CollapsibleGroup
+          type="single"
+          hasDividers
+          value="b"
+          onChange={onChange}>
+          <Collapsible trigger="Item A" value="a">
+            <p>Content A</p>
+          </Collapsible>
+          <Collapsible trigger="Item B" value="b">
+            <p>Content B</p>
+          </Collapsible>
+        </CollapsibleGroup>,
+      );
+      expect(screen.getByText('Content A')).not.toBeVisible();
+      expect(screen.getByText('Content B')).toBeVisible();
+    });
+
+    it('renders standalone Collapsible without any group chrome', () => {
+      render(
+        <Collapsible trigger="Alone">
+          <p>Standalone content</p>
+        </Collapsible>,
+      );
+
+      const item = getItem(/Alone/);
+      expect(item).not.toHaveAttribute('data-density');
+      expect(item.querySelector('.astryx-collapsible-group')).toBeNull();
+    });
+  });
 });

package/src/Collapsible/CollapsibleGroup.tsx

@@ -4,13 +4,17 @@
 
 /**
  * @file CollapsibleGroup.tsx
- * @input Uses React useState, useCallback, CollapsibleGroupContext
+ * @input Uses React useState, useCallback, CollapsibleGroupContext, StyleX, theme tokens
  * @output Exports CollapsibleGroup component and CollapsibleGroupProps
- * @position Core collapsible group coordination provider — renders no wrapper DOM
+ * @position Core collapsible group coordination provider — renders no wrapper
+ *   DOM unless `hasDividers` is set
  *
  * CollapsibleGroup groups collapsible components (Card, etc.) with
- * coordinated open/close behavior. It renders only `{children}` — no wrapper
- * DOM element.
+ * coordinated open/close behavior. By default it renders only `{children}` —
+ * no wrapper DOM element. When `hasDividers` is set it renders a wrapper div
+ * that anchors reliable :first-child divider suppression and provides
+ * hasDividers/density to items via CollapsibleGroupPresentationContext — each
+ * Collapsible draws its own borders since StyleX has no child selectors.
  *
  * In "single" mode (default), only one item can be open at a time.
  * In "multiple" mode, any number of items can be open simultaneously.
@@ -24,10 +28,29 @@
  */
 
 import React, {useCallback, useMemo, useState, type ReactNode} from 'react';
-import {CollapsibleGroupContext} from './CollapsibleGroupContext';
-import type {CollapsibleGroupContextValue} from './CollapsibleGroupContext';
+import * as stylex from '@stylexjs/stylex';
+import {
+  CollapsibleGroupContext,
+  CollapsibleGroupPresentationContext,
+} from './CollapsibleGroupContext';
+import type {
+  CollapsibleGroupContextValue,
+  CollapsibleGroupDensity,
+  CollapsibleGroupPresentationValue,
+} from './CollapsibleGroupContext';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
 import type {BaseProps} from '../BaseProps';
 
+const styles = stylex.create({
+  // The wrapper lays items out in a column; between-item hairlines are drawn
+  // by each Collapsible (borderBlockStart, suppressed on :first-child).
+  wrapper: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
+});
+
 export interface CollapsibleGroupProps extends Omit<
   BaseProps<HTMLElement>,
   'onChange'
@@ -56,6 +79,23 @@ export interface CollapsibleGroupProps extends Omit<
    */
   onChange?: (value: string | string[]) => void;
 
+  /**
+   * Whether to draw hairline dividers between the group's items — the
+   * accordion row chrome. When set, the group renders a wrapper div (it
+   * otherwise renders no DOM) and items get 'balanced' density unless
+   * `density` says otherwise. Pair with bare Collapsible children; Card-wrapped
+   * items provide their own separation.
+   * @default false
+   */
+  hasDividers?: boolean;
+
+  /**
+   * Row density controlling trigger and content block padding on the group's
+   * items. Defaults to 'balanced' when dividers are shown; otherwise items
+   * keep their default unpadded look.
+   */
+  density?: CollapsibleGroupDensity;
+
   /**
    * Children — any components that support isCollapsible + value.
    *
@@ -92,16 +132,26 @@ function normalizeToArray(value: string | string[] | undefined): string[] {
 
 /**
  * Groups collapsible components with coordinated open/close behavior.
- * Renders no wrapper DOM.
+ * Renders no wrapper DOM unless `hasDividers` is set.
  *
  * In "single" mode (default), opening one item closes the others.
  * In "multiple" mode, items toggle independently.
  *
  * @compositionHint Wrap Collapsible instances to coordinate their open/close state.
- * Each Collapsible needs a `value` prop to participate.
+ * Each Collapsible needs a `value` prop to participate. For FAQ-style lists,
+ * use `hasDividers` with bare Collapsible children instead of wrapping each
+ * item in Card.
  *
  * @example
  * ```
+ * <CollapsibleGroup type="single" hasDividers defaultValue="faq1">
+ *   <Collapsible trigger="What is Astryx?" value="faq1">
+ *     Astryx is a design system for building internal tools.
+ *   </Collapsible>
+ *   <Collapsible trigger="How do I start?" value="faq2">
+ *     Install the package and import components.
+ *   </Collapsible>
+ * </CollapsibleGroup>
  * <CollapsibleGroup type="single" defaultValue="faq1">
  *   <VStack gap={2}>
  *     <Card>
@@ -123,7 +173,14 @@ export function CollapsibleGroup({
   defaultValue,
   value: controlledValue,
   onChange,
+  hasDividers = false,
+  density,
   children,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...props
 }: CollapsibleGroupProps) {
   const isControlled = controlledValue !== undefined;
   const [internalValue, setInternalValue] = useState<string[]>(() =>
@@ -174,9 +231,40 @@ export function CollapsibleGroup({
     [isOpen, toggle],
   );
 
+  const resolvedDensity = density ?? (hasDividers ? 'balanced' : null);
+
+  const presentationValue = useMemo<CollapsibleGroupPresentationValue>(
+    () => ({hasDividers, density: resolvedDensity}),
+    [hasDividers, resolvedDensity],
+  );
+
+  // The wrapper anchors divider chrome: it makes the items' :first-child
+  // suppression independent of surrounding siblings. Without dividers the
+  // group stays DOM-less (documented contract), so ref/xstyle/className/style
+  // only take effect in wrapper mode.
+  const content = hasDividers ? (
+    <div
+      ref={ref as React.Ref<HTMLDivElement>}
+      {...mergeProps(
+        themeProps('collapsible-group', {
+          density: resolvedDensity ?? undefined,
+        }),
+        stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
+      )}
+      {...props}>
+      {children}
+    </div>
+  ) : (
+    children
+  );
+
   return (
     <CollapsibleGroupContext value={contextValue}>
-      {children}
+      <CollapsibleGroupPresentationContext value={presentationValue}>
+        {content}
+      </CollapsibleGroupPresentationContext>
     </CollapsibleGroupContext>
   );
 }

package/src/Collapsible/CollapsibleGroupContext.tsx

@@ -5,8 +5,10 @@
 /**
  * @file CollapsibleGroupContext.tsx
  * @input Uses React createContext
- * @output Exports CollapsibleGroupContext and CollapsibleGroupContextValue type
- * @position Context definition for collapsible group coordination
+ * @output Exports CollapsibleGroupContext, CollapsibleGroupContextValue,
+ *   CollapsibleGroupPresentationContext, CollapsibleGroupPresentationValue,
+ *   and CollapsibleGroupDensity types
+ * @position Context definitions for collapsible group coordination and presentation
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Collapsible/CollapsibleGroup.tsx (provider)
@@ -33,3 +35,33 @@ export interface CollapsibleGroupContextValue {
 export const CollapsibleGroupContext =
   createContext<CollapsibleGroupContextValue | null>(null);
 CollapsibleGroupContext.displayName = 'CollapsibleGroupContext';
+
+/**
+ * Row density for the items of a CollapsibleGroup, controlling trigger and
+ * content block padding. Shares the repo-wide density vocabulary
+ * (Table, List, Item).
+ */
+export type CollapsibleGroupDensity = 'compact' | 'balanced' | 'spacious';
+
+/**
+ * Presentation value provided by CollapsibleGroup so each Collapsible can
+ * draw its own group chrome (StyleX has no child selectors, so the group
+ * cannot style items from the outside).
+ */
+export interface CollapsibleGroupPresentationValue {
+  /** Whether the group's items draw hairline dividers between one another. */
+  hasDividers: boolean;
+  /** Resolved row density, or null to keep the default (unpadded) look. */
+  density: CollapsibleGroupDensity | null;
+}
+
+/**
+ * Context for collapsible group presentation (dividers, density).
+ * Kept separate from CollapsibleGroupContext so the public useCollapsible
+ * state API is unaffected. Collapsible resets this context around its
+ * children so nested collapsibles never inherit row chrome.
+ */
+export const CollapsibleGroupPresentationContext =
+  createContext<CollapsibleGroupPresentationValue | null>(null);
+CollapsibleGroupPresentationContext.displayName =
+  'CollapsibleGroupPresentationContext';

package/src/Collapsible/index.ts

@@ -16,6 +16,7 @@ export type {CollapsibleProps} from './Collapsible';
 
 export {CollapsibleGroup} from './CollapsibleGroup';
 export type {CollapsibleGroupProps} from './CollapsibleGroup';
+export type {CollapsibleGroupDensity} from './CollapsibleGroupContext';
 
 export {useCollapsible} from './useCollapsible';
 export type {

package/src/Collapsible/useCollapsible.ts

@@ -65,8 +65,11 @@ export interface UseCollapsibleReturn {
  *
  * 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.
+ * 2. **Controlled**: When `isOpen` is provided in config, the parent owns state;
+ *    `toggle` only calls `onOpenChange` and never mutates internal state.
  * 3. **Uncontrolled**: Self-managed internal state with optional `defaultIsOpen`.
+ *    `onOpenChange`, if supplied, is invoked in addition to the internal update —
+ *    it is a notification callback, not a signal that the component is controlled.
  *
  * @example
  * ```
@@ -111,15 +114,26 @@ export function useCollapsible(
     isOpen = internalIsOpen;
   }
 
-  // Toggle handler dispatches to the appropriate controller
+  // Toggle handler dispatches to the appropriate controller.
+  //
+  // Controlled vs uncontrolled is decided by whether `isOpen` was provided —
+  // mirroring how `isOpen` is derived above. `onOpenChange` is a notification
+  // callback, not a signal of control: an uncontrolled component may still want
+  // to observe changes. So in uncontrolled mode we drive internal state AND
+  // fire the callback; only in controlled mode do we defer entirely to the
+  // parent via the callback.
   const toggle = () => {
     if (isControlledByGroup && value != null) {
       group.toggle(value);
-    } else if (config?.onOpenChange) {
-      config.onOpenChange(!isOpen);
-    } else {
-      setInternalIsOpen(prev => !prev);
+      return;
     }
+    const next = !isOpen;
+    // Uncontrolled: internal state is the source of truth, so update it.
+    if (config?.isOpen === undefined) {
+      setInternalIsOpen(next);
+    }
+    // Always notify — for both controlled and uncontrolled usage.
+    config?.onOpenChange?.(next);
   };
 
   return {isEnabled, isOpen, toggle};

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -20,6 +20,10 @@ export const docs = {
     'navigation',
   ],
   description: 'Root component. Manages open state, search, keyboard navigation, and composition slots.',
+  // Intentionally a contained isInline preview, not playground.overlay: the
+  // component stays visible on load and knobs stay live, whereas a real
+  // showModal() overlay makes the page inert — see PlaygroundConfig.overlay
+  // in docs-types.ts (#3657).
   playground: {
     defaults: {
       isOpen: true,
@@ -138,6 +142,7 @@ export const docs = {
   ],
   theming: {
     targets: [
+      {className: 'astryx-command-palette-empty'},
       {className: 'astryx-command-palette-footer'},
       {className: 'astryx-command-palette-group'},
       {className: 'astryx-command-palette-input'},

package/src/CommandPalette/CommandPalette.tsx

@@ -438,11 +438,13 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   const contextValue = useMemo(
     () => ({
       // Input uses optimisticSearch — reflects keystrokes immediately.
-      // setSearch calls setOptimisticSearch for instant feedback then
-      // triggers the async search directly (no effect indirection).
+      // setSearch calls setOptimisticSearch inside a transition for instant
+      // feedback then triggers the async search directly (no effect indirection).
       search: optimisticSearch,
       setSearch: (query: string) => {
-        setOptimisticSearch(query);
+        startTransition(() => {
+          setOptimisticSearch(query);
+        });
         runSearch(query);
       },
       value,

package/src/CommandPalette/CommandPaletteEmpty.doc.mjs

@@ -16,6 +16,11 @@ export const docs = {
       required: true,
     },
   ],
+  playground: {
+    defaults: {
+      children: 'No results found. Try a different search.',
+    },
+  },
 };
 
 export const docsZh = {

package/src/CommandPalette/CommandPaletteGroup.doc.mjs

@@ -27,6 +27,16 @@ export const docs = {
       description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
   ],
+  playground: {
+    defaults: {
+      heading: 'Navigation',
+      children: [
+        {__element: 'CommandPaletteItem', props: {value: 'home', onSelect: undefined}, children: 'Go Home'},
+        {__element: 'CommandPaletteItem', props: {value: 'settings', onSelect: undefined}, children: 'Open Settings'},
+        {__element: 'CommandPaletteItem', props: {value: 'profile', onSelect: undefined}, children: 'View Profile'},
+      ],
+    },
+  },
 };
 
 export const docsZh = {

package/src/CommandPalette/CommandPaletteInput.doc.mjs

@@ -57,6 +57,12 @@ export const docs = {
       description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
   ],
+  playground: {
+    defaults: {
+      placeholder: 'Search commands, files, or actions...',
+      hasAutoFocus: false,
+    },
+  },
 };
 
 export const docsZh = {