@astryxdesign/core 0.2.0 → 0.3.0

package/src/Collapsible/Collapsible.tsx

@@ -24,7 +24,7 @@
  * - /packages/core/src/Collapsible/index.ts (exports)
  * - /packages/core/src/Collapsible/Collapsible.doc.mjs
  * - /apps/storybook/stories/Collapsible.stories.tsx
- * - /packages/cli/templates/blocks/components/Collapsible/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Collapsible/ (showcase blocks)
  */
 
 import {use, useId, type ReactNode} from 'react';
@@ -42,7 +42,7 @@ import {
 
 import {useCollapsible} from './useCollapsible';
 import {CollapsibleGroupPresentationContext} from './CollapsibleGroupContext';
-import {getIcon} from '../Icon/globalIconRegistry';
+import {useIcon} from '../Icon';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -293,7 +293,7 @@ export function Collapsible({
   const isDivided = presentation?.hasDividers ?? false;
   const density = presentation?.density ?? null;
 
-  const chevronIcon = getIcon('chevronDown');
+  const chevronIcon = useIcon('chevronDown');
 
   // Links the trigger to the region it shows/hides so assistive tech can move
   // from the button to its controlled content (disclosure pattern).

package/src/Collapsible/CollapsibleGroup.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CollapsibleGroup',

package/src/Collapsible/CollapsibleGroup.tsx

@@ -24,7 +24,7 @@
  * - /packages/core/src/Collapsible/Collapsible.doc.mjs
  * - /packages/core/src/Collapsible/index.ts (exports)
  * - /apps/storybook/stories/Collapsible.stories.tsx
- * - /packages/cli/templates/blocks/components/Collapsible/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Collapsible/ (showcase blocks)
  */
 
 import React, {useCallback, useMemo, useState, type ReactNode} from 'react';

package/src/Collapsible/CollapsibleGroupContext.tsx

@@ -13,7 +13,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Collapsible/CollapsibleGroup.tsx (provider)
  * - /packages/core/src/Collapsible/Collapsible.doc.mjs
- * - /packages/cli/templates/blocks/components/Collapsible/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Collapsible/ (showcase blocks)
  */
 
 import {createContext} from 'react';

package/src/Collapsible/useCollapsible.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useCollapsible',
   displayName: 'useCollapsible',
@@ -49,7 +49,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Encapsulates collapsible state machine. 3 modes: group-controlled (inside CollapsibleGroup), controlled (isOpen + onOpenChange), uncontrolled (self-managed w/ defaultIsOpen). Used internally by Card + Section.',
   paramDescriptions: {

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'CommandPalette',
   displayName: 'Command Palette',
@@ -22,7 +22,7 @@ export const docs = {
   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
+  // showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay
   // in docs-types.ts (#3657).
   playground: {
     defaults: {
@@ -162,7 +162,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
@@ -175,7 +175,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same SearchSource interface as Typeahead',

package/src/CommandPalette/CommandPalette.tsx

@@ -9,7 +9,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /apps/storybook/stories/CommandPalette.stories.tsx
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 import {

package/src/CommandPalette/CommandPaletteEmpty.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CommandPaletteEmpty',

package/src/CommandPalette/CommandPaletteEmpty.tsx

@@ -7,7 +7,7 @@
  * @position Sub-component; empty state shown when there are no items to display
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/CommandPalette/CommandPaletteFooter.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CommandPaletteFooter',

package/src/CommandPalette/CommandPaletteFooter.tsx

@@ -7,7 +7,7 @@
  * @position Sub-component; footer with keyboard hints
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/CommandPalette/CommandPaletteGroup.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CommandPaletteGroup',

package/src/CommandPalette/CommandPaletteGroup.test.tsx

@@ -10,8 +10,12 @@ import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {CommandPaletteGroup} from './CommandPaletteGroup';
 import {defineTheme} from '../theme/defineTheme';
-import {generateThemeCSSFlat} from '../theme/generateThemeRules';
+import {generateThemeCSS} from '../theme/generateThemeRules';
 
+function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
+  const {prose, component} = generateThemeCSS(theme);
+  return [prose, component].filter(Boolean).join('\n\n');
+}
 describe('CommandPaletteGroup', () => {
   it('renders heading', () => {
     render(
@@ -116,7 +120,7 @@ describe('CommandPaletteGroup', () => {
           },
         },
       });
-      const css = generateThemeCSSFlat(theme);
+      const css = generateThemeTestCSS(theme);
       expect(css).toContain('.astryx-command-palette-group-heading {');
       expect(css).toContain('padding-block: var(--spacing-2)');
       expect(css).toContain('font-weight: var(--font-weight-bold)');

package/src/CommandPalette/CommandPaletteGroup.tsx

@@ -7,7 +7,7 @@
  * @position Sub-component; visual grouping with heading
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/CommandPalette/CommandPaletteInput.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CommandPaletteInput',

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -9,7 +9,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /apps/storybook/stories/CommandPalette.stories.tsx
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 import {useCallback, useEffect, useRef, type ReactNode} from 'react';
@@ -163,6 +163,8 @@ export function CommandPaletteInput({
   onKeyDown,
   ref,
   xstyle,
+  className,
+  style,
   ...props
 }: CommandPaletteInputProps) {
   const t = useTranslator();
@@ -207,6 +209,8 @@ export function CommandPaletteInput({
       {...mergeProps(
         themeProps('command-palette-input'),
         stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
       )}>
       <span {...stylex.props(styles.icon)}>
         <Icon icon="search" size="sm" color="inherit" />

package/src/CommandPalette/CommandPaletteItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CommandPaletteItem',

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -8,7 +8,7 @@
  * @position Sub-component; individual selectable item
  *
  * SYNC: When modified, update:
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 import {useCallback, useEffect, useMemo, useRef, type ReactNode} from 'react';

package/src/CommandPalette/CommandPaletteList.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CommandPaletteList',

package/src/CommandPalette/CommandPaletteList.tsx

@@ -8,7 +8,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/CommandPalette/index.ts
- * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
 'use client';

package/src/ComplexSelector/ComplexSelector.doc.mjs

@@ -0,0 +1,179 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'ComplexSelector',
+  displayName: 'Complex Selector',
+  group: 'Selector',
+  category: 'Data Input',
+  keywords: [
+    'selector',
+    'picker',
+    'popover',
+    'dialog',
+    'custom',
+    'rich',
+    'matrix',
+    'grid',
+  ],
+  theming: {
+    targets: [
+      {className: 'astryx-complex-selector', visualProps: ['size', 'status']},
+      {
+        className: 'astryx-complex-selector-indicator-icon',
+        states: ['state'],
+      },
+    ],
+  },
+  components: [
+    {
+      name: 'ComplexSelector',
+      displayName: 'Complex Selector',
+      description:
+        'A field and dialog-popover shell for custom selector content.',
+      props: [
+        {
+          name: 'label',
+          type: 'string',
+          description: 'Label text for accessibility and the field label.',
+          required: true,
+        },
+        {
+          name: 'value',
+          type: 'Value',
+          description: 'Current controlled value.',
+          required: true,
+        },
+        {
+          name: 'onChange',
+          type: '(value: Value) => void',
+          description: 'Called when custom content commits a new value.',
+        },
+        {
+          name: 'changeAction',
+          type: '(value: Value) => void | Promise<void>',
+          description:
+            'Async action after onChange. ComplexSelector exposes optimistic value and busy state while pending.',
+        },
+        {
+          name: 'children',
+          type: '(value: Value, onChange: (value: Value) => void, close: () => void, state: ComplexSelectorRenderState) => ReactNode',
+          description:
+            'Custom dialog content. Receives positional value, onChange, close, and state helpers.',
+          required: true,
+        },
+        {
+          name: 'triggerLabel',
+          type: 'ReactNode',
+          description: 'Label/content shown in the closed trigger.',
+        },
+        {
+          name: 'placeholder',
+          type: 'ReactNode',
+          description: 'Placeholder shown when triggerLabel is omitted.',
+          default: "'Select...'",
+        },
+        {
+          name: 'isDisabled',
+          type: 'boolean',
+          description: 'Disables the selector.',
+        },
+        {
+          name: 'isLoading',
+          type: 'boolean',
+          description: 'Shows loading state on the trigger.',
+        },
+        {
+          name: 'status',
+          type: "{type: 'warning' | 'error' | 'success', message?: string}",
+          description: 'Validation status.',
+        },
+        {
+          name: 'size',
+          type: "'sm' | 'md' | 'lg'",
+          description: 'Trigger and field size.',
+          default: "'md'",
+        },
+        {
+          name: 'width',
+          type: 'SizeValue',
+          description: 'Width of the field.',
+        },
+        {
+          name: 'placement',
+          type: "'above' | 'below' | 'start' | 'end'",
+          description: 'Popup placement.',
+          default: "'below'",
+        },
+        {
+          name: 'contentXstyle',
+          type: 'StyleXStyles',
+          description: 'StyleX styles for the popup content container.',
+        },
+      ],
+    },
+  ],
+  usage: {
+    description:
+      'Use ComplexSelector when a selection needs richer custom content than a Selector option row. It is intentionally one component: ComplexSelector owns the field, trigger, popover, focus restore, and changeAction flow, while the content render prop owns the selector-specific accessible structure.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Compose the dialog content from the appropriate accessible structure for the job: RadioList for a simple choice, Calendar/date inputs for date picking, TreeList or a searchable list for hierarchy, or a custom grid when two-dimensional arrow navigation is useful.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use the provided onChange helper from children; it already calls both onChange and changeAction and updates optimistic busy state.',
+      },
+      {
+        guidance: true,
+        description:
+          'Call close() from custom content when a selection should dismiss the popup. Keep it open for multi-step content or freeform entry flows.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use Astryx focus hooks for custom content: useGridFocus for two-dimensional grids, useTreeFocus through TreeList for hierarchies, and useListFocus for custom linear collections.',
+      },
+      {
+        guidance: true,
+        description:
+          'Evaluate custom content against WCAG 2.2: keyboard operation, focus visible/not obscured, names and roles, labels/instructions, target size, and contrast/non-text contrast are especially relevant for selector popovers.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not rebuild trigger ARIA, popover focus management, or changeAction handling in product code.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not use ComplexSelector for a plain single-column text list; use Selector instead.',
+      },
+    ],
+  },
+};
+
+export const docsDense = {
+  name: 'ComplexSelector',
+  displayName: 'Complex Selector',
+  group: 'Selector',
+  category: 'Data Input',
+  description:
+    'Field+dialog-popover shell for rich custom selectors. Content gets value/onChange/close/state; content owns semantics. Use focus hooks and evaluate custom content against WCAG 2.2.',
+  propDescriptions: {
+    label: 'Accessible field label.',
+    value: 'Controlled value.',
+    onChange: 'Commit value.',
+    changeAction: 'Async action after onChange; drives optimistic value/busy.',
+    children:
+      'Render custom dialog content from (value,onChange,close,state).',
+    triggerLabel: 'Closed trigger label/content.',
+    placement: 'Popup placement.',
+    accessibility:
+      'Custom content must provide its own accessible structure. Use focus hooks and evaluate against WCAG 2.2.',
+  },
+};

package/src/ComplexSelector/ComplexSelector.test.tsx

@@ -0,0 +1,156 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ComplexSelector.test.tsx
+ * @input Uses vitest, Testing Library, user-event
+ * @output Unit tests for ComplexSelector
+ * @position Tests; validates custom content, async actions, and dialog composition
+ *
+ * SYNC: When ComplexSelector.tsx API changes, update these tests.
+ */
+
+import {describe, expect, it, vi} from 'vitest';
+import {render, screen, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {ComplexSelector} from './ComplexSelector';
+
+type FruitValue = {
+  fruit: 'Apple' | 'Banana';
+  ripeness: 'Crisp' | 'Ripe' | 'Juicy';
+};
+
+const FRUITS = ['Apple', 'Banana'] as const;
+const RIPENESS = ['Crisp', 'Ripe', 'Juicy'] as const;
+const h = {hidden: true} as const;
+
+function FruitGrid({
+  value,
+  onChange,
+}: {
+  value: FruitValue;
+  onChange: (value: FruitValue) => void;
+}) {
+  return (
+    <div role="grid" aria-label="Fruit blend choices">
+      {FRUITS.flatMap(fruit =>
+        RIPENESS.map(ripeness => {
+          const isSelected =
+            value.fruit === fruit && value.ripeness === ripeness;
+          return (
+            <button
+              key={`${fruit}-${ripeness}`}
+              type="button"
+              role="gridcell"
+              aria-label={`${fruit} ${ripeness}`}
+              aria-selected={isSelected || undefined}
+              onClick={() => onChange({fruit, ripeness})}>
+              {fruit} {ripeness}
+            </button>
+          );
+        }),
+      )}
+    </div>
+  );
+}
+
+function FruitComplexSelector({
+  value,
+  onChange,
+  changeAction,
+}: {
+  value: FruitValue;
+  onChange: (value: FruitValue) => void;
+  changeAction?: (value: FruitValue) => void | Promise<void>;
+}) {
+  return (
+    <ComplexSelector
+      label="Fruit blend"
+      value={value}
+      onChange={onChange}
+      changeAction={changeAction}
+      triggerLabel={`${value.fruit} ${value.ripeness}`}>
+      {(value, onChange, close) => (
+        <FruitGrid
+          value={value}
+          onChange={nextValue => {
+            onChange(nextValue);
+            close();
+          }}
+        />
+      )}
+    </ComplexSelector>
+  );
+}
+
+describe('ComplexSelector', () => {
+  it('renders custom content with value and commits through onChange', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(
+      <FruitComplexSelector
+        value={{fruit: 'Apple', ripeness: 'Ripe'}}
+        onChange={onChange}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    await user.click(
+      screen.getByRole('gridcell', {name: 'Banana Juicy', ...h}),
+    );
+
+    expect(onChange).toHaveBeenCalledWith({fruit: 'Banana', ripeness: 'Juicy'});
+    expect(screen.getByRole('button', {name: 'Fruit blend'})).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+  });
+
+  it('runs changeAction through the provided onChange helper', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const changeAction = vi.fn();
+
+    render(
+      <FruitComplexSelector
+        value={{fruit: 'Apple', ripeness: 'Ripe'}}
+        onChange={onChange}
+        changeAction={changeAction}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    await user.click(
+      screen.getByRole('gridcell', {name: 'Banana Crisp', ...h}),
+    );
+
+    expect(onChange).toHaveBeenCalledWith({fruit: 'Banana', ripeness: 'Crisp'});
+    await waitFor(() => {
+      expect(changeAction).toHaveBeenCalledWith({
+        fruit: 'Banana',
+        ripeness: 'Crisp',
+      });
+    });
+  });
+
+  it('passes a close helper to composed content', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <ComplexSelector label="Fruit blend" value="Apple" triggerLabel="Apple">
+        {(_value, _onChange, close) => (
+          <button type="button" onClick={close}>
+            Done
+          </button>
+        )}
+      </ComplexSelector>,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Fruit blend'});
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+    await user.click(screen.getByRole('button', {name: 'Done', ...h}));
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+});