@pharos-ds/core 0.1.9

package/src/CommandPalette/CommandPaletteItem.test.tsx

@@ -0,0 +1,169 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandPaletteItem.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Unit tests for CommandPaletteItem
+ */
+
+import {afterEach, describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {Dialog} from '../Dialog/Dialog';
+import {CommandPaletteItem} from './CommandPaletteItem';
+
+const scrollIntoViewDescriptor = Object.getOwnPropertyDescriptor(
+  HTMLElement.prototype,
+  'scrollIntoView',
+);
+
+function mockScrollIntoView() {
+  const scrollIntoView = vi.fn();
+  Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+    configurable: true,
+    value: scrollIntoView,
+  });
+  return scrollIntoView;
+}
+
+afterEach(() => {
+  if (scrollIntoViewDescriptor) {
+    Object.defineProperty(
+      HTMLElement.prototype,
+      'scrollIntoView',
+      scrollIntoViewDescriptor,
+    );
+  } else {
+    delete (HTMLElement.prototype as unknown as {scrollIntoView?: unknown})
+      .scrollIntoView;
+  }
+});
+
+describe('CommandPaletteItem', () => {
+  it('renders children', () => {
+    render(
+      <CommandPaletteItem value="test">Test Item</CommandPaletteItem>,
+    );
+    expect(screen.getByText('Test Item')).toBeInTheDocument();
+  });
+
+  it('has option role', () => {
+    render(<CommandPaletteItem value="test">Item</CommandPaletteItem>);
+    expect(screen.getByRole('option')).toBeInTheDocument();
+  });
+
+  it('calls onSelect when clicked', () => {
+    const handleSelect = vi.fn();
+    render(
+      <CommandPaletteItem value="test" onSelect={handleSelect}>
+        Item
+      </CommandPaletteItem>,
+    );
+    fireEvent.click(screen.getByRole('option'));
+    expect(handleSelect).toHaveBeenCalledWith('test');
+  });
+
+  it('does not call onSelect when disabled', () => {
+    const handleSelect = vi.fn();
+    render(
+      <CommandPaletteItem value="test" onSelect={handleSelect} isDisabled>
+        Item
+      </CommandPaletteItem>,
+    );
+    fireEvent.click(screen.getByRole('option'));
+    expect(handleSelect).not.toHaveBeenCalled();
+  });
+
+  it('sets aria-disabled when disabled', () => {
+    render(
+      <CommandPaletteItem value="test" isDisabled>
+        Item
+      </CommandPaletteItem>,
+    );
+    expect(screen.getByRole('option')).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('sets aria-selected when selected (not highlighted)', () => {
+    render(
+      <CommandPaletteItem value="test" isSelected>
+        Item
+      </CommandPaletteItem>,
+    );
+    expect(screen.getByRole('option')).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('does not set aria-selected when only highlighted', () => {
+    // Highlight is visual only — aria-activedescendant on the input conveys
+    // keyboard focus, so aria-selected must not be set on highlight alone.
+    render(
+      <CommandPaletteItem value="test" isHighlighted>
+        Item
+      </CommandPaletteItem>,
+    );
+    expect(screen.getByRole('option')).toHaveAttribute(
+      'aria-selected',
+      'false',
+    );
+  });
+
+  it('scrolls highlighted items into view by default', async () => {
+    const scrollIntoView = mockScrollIntoView();
+
+    render(
+      <CommandPaletteItem value="test" isHighlighted>
+        Item
+      </CommandPaletteItem>,
+    );
+
+    await waitFor(() => {
+      expect(scrollIntoView).toHaveBeenCalledWith({block: 'nearest'});
+    });
+  });
+
+  it('does not scroll initially highlighted items in inline dialogs', () => {
+    const scrollIntoView = mockScrollIntoView();
+
+    render(
+      <Dialog isOpen isInline onOpenChange={() => {}}>
+        <CommandPaletteItem value="test" isHighlighted>
+          Item
+        </CommandPaletteItem>
+      </Dialog>,
+    );
+
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+
+  it('scrolls inline dialog items after highlight changes', async () => {
+    const scrollIntoView = mockScrollIntoView();
+
+    const {rerender} = render(
+      <Dialog isOpen isInline onOpenChange={() => {}}>
+        <CommandPaletteItem value="test" isHighlighted={false}>
+          Item
+        </CommandPaletteItem>
+      </Dialog>,
+    );
+
+    rerender(
+      <Dialog isOpen isInline onOpenChange={() => {}}>
+        <CommandPaletteItem value="test" isHighlighted>
+          Item
+        </CommandPaletteItem>
+      </Dialog>,
+    );
+
+    await waitFor(() => {
+      expect(scrollIntoView).toHaveBeenCalledWith({block: 'nearest'});
+    });
+  });
+
+  it('sets data-value attribute', () => {
+    render(
+      <CommandPaletteItem value="my-value">Item</CommandPaletteItem>,
+    );
+    expect(screen.getByRole('option')).toHaveAttribute(
+      'data-value',
+      'my-value',
+    );
+  });
+});

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -0,0 +1,215 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+/**
+ * @file CommandPaletteItem.tsx
+ * @input Uses React, StyleX, CommandPaletteContext, DialogContext
+ * @output Exports CommandPaletteItem component
+ * @position Sub-component; individual selectable item
+ *
+ * SYNC: When modified, update:
+ * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ */
+
+import {useCallback, useEffect, useMemo, useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps, mergeRefs} from '../utils';
+import {
+  colorVars,
+  spacingVars,
+  radiusVars,
+  typographyVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+import {useCommandPaletteContext} from './CommandPaletteContext';
+import {useDialogContext} from '../Dialog/DialogContext';
+import {themeProps} from '../utils/themeProps';
+
+const HOVER_HOVER = '@media (hover: hover)';
+
+const styles = stylex.create({
+  item: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    width: '100%',
+    paddingInline: spacingVars['--spacing-3'],
+    paddingBlock: spacingVars['--spacing-2'],
+    borderRadius: radiusVars['--radius-inner'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-label-size'],
+    color: colorVars['--color-text-primary'],
+    backgroundColor: 'transparent',
+    border: 'none',
+    cursor: 'pointer',
+    textAlign: 'start' as const,
+    outline: 'none',
+    userSelect: 'none',
+  },
+  itemHover: {
+    ':hover': {
+      [HOVER_HOVER]: {
+        backgroundColor: colorVars['--color-overlay-hover'],
+      },
+    },
+    ':active': {
+      backgroundColor: colorVars['--color-overlay-pressed'],
+    },
+  },
+  itemHighlighted: {
+    backgroundColor: colorVars['--color-overlay-hover'],
+  },
+  itemDisabled: {
+    opacity: 0.5,
+    cursor: 'not-allowed',
+  },
+  itemSelected: {
+    backgroundColor: colorVars['--color-accent-muted'],
+  },
+});
+
+export interface CommandPaletteItemProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'onChange' | 'onSelect'
+> {
+  /** Ref forwarded to the root element. */
+  ref?: React.Ref<HTMLDivElement>;
+  /** Unique value for identification and selection. */
+  value: string;
+  /** Called when this item is selected (via click or Enter). */
+  onSelect?: (value: string) => void;
+  /**
+   * Whether this item is visually highlighted (keyboard focus).
+   * When omitted inside CommandPalette, derived from context.
+   * @default false
+   */
+  isHighlighted?: boolean;
+  /**
+   * Whether this item is currently selected (picker mode).
+   * @default false
+   */
+  isSelected?: boolean;
+  /**
+   * Whether the item is disabled.
+   * @default false
+   */
+  isDisabled?: boolean;
+  /** Item content. Fully custom — render icons, descriptions, shortcuts, etc. */
+  children: ReactNode;
+}
+
+/**
+ * A selectable item in the command palette.
+ * Accepts arbitrary children for full rendering control.
+ *
+ * When used inside CommandPalette, registers with context for
+ * keyboard navigation and selection. Can also be used
+ * standalone with explicit isHighlighted/isSelected props.
+ *
+ * @compositionHint Place inside CommandPaletteList or CommandPaletteGroup.
+ *
+ * @example
+ * ```
+ * <CommandPaletteItem value="settings" onSelect={() => navigate('/settings')}>
+ *   Settings
+ * </CommandPaletteItem>
+ * ```
+ */
+export function CommandPaletteItem({
+  value,
+  onSelect,
+  isHighlighted: controlledHighlighted,
+  isSelected: controlledSelected,
+  isDisabled = false,
+  children,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...props
+}: CommandPaletteItemProps) {
+  const ctx = useCommandPaletteContext();
+  const dialogContext = useDialogContext();
+  const isInlineDialog = dialogContext?.isInline === true;
+  const itemRef = useRef<HTMLDivElement>(null);
+  const didMountRef = useRef(false);
+
+  // Find this item's index in the flat selectable items list (DOM order).
+  // This aligns with useCombobox's index-based navigation.
+  const itemIndex = useMemo(
+    () => ctx?.selectableItems.findIndex(item => item.value === value) ?? -1,
+    [ctx?.selectableItems, value],
+  );
+
+  // Highlight from useCombobox: index-based, matches DOM order
+  const isHighlighted =
+    controlledHighlighted ??
+    (ctx ? ctx.highlightedIndex === itemIndex && itemIndex >= 0 : false);
+  const isSelected = controlledSelected ?? (ctx ? ctx.value === value : false);
+
+  useEffect(() => {
+    // Inline dialogs are documentation/showcase previews. Avoid scrolling the
+    // surrounding page when picker mode auto-highlights its selected item on
+    // mount, while preserving scroll-into-view after user navigation.
+    const shouldSkipInitialInlineScroll =
+      isInlineDialog && !didMountRef.current;
+    didMountRef.current = true;
+
+    if (shouldSkipInitialInlineScroll) {
+      return;
+    }
+
+    if (isHighlighted && itemRef.current) {
+      itemRef.current.scrollIntoView?.({block: 'nearest'});
+    }
+  }, [isHighlighted, isInlineDialog]);
+
+  const handleClick = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    onSelect?.(value);
+    if (ctx) {
+      ctx.selectItem(value);
+      ctx.onClose();
+    }
+  }, [isDisabled, value, onSelect, ctx]);
+
+  const handleMouseEnter = useCallback(() => {
+    if (isDisabled || !ctx || itemIndex < 0) {
+      return;
+    }
+    ctx.setHighlightedIndex(itemIndex);
+  }, [isDisabled, itemIndex, ctx]);
+
+  return (
+    <div
+      ref={mergeRefs(ref, itemRef)}
+      id={ctx && itemIndex >= 0 ? ctx.getItemId(itemIndex) : undefined}
+      role="option"
+      aria-selected={isSelected}
+      aria-disabled={isDisabled || undefined}
+      data-value={value}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      {...mergeProps(
+        themeProps('command-palette-item'),
+        stylex.props(
+          styles.item,
+          !isDisabled && styles.itemHover,
+          isHighlighted && styles.itemHighlighted,
+          isSelected && styles.itemSelected,
+          isDisabled && styles.itemDisabled,
+          xstyle,
+        ),
+        className,
+        style,
+      )}
+      {...props}>
+      {children}
+    </div>
+  );
+}
+
+CommandPaletteItem.displayName = 'CommandPaletteItem';

package/src/CommandPalette/CommandPaletteList.doc.mjs

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'CommandPaletteList',
+  subComponentOf: 'CommandPalette',
+  displayName: 'Command Palette List',
+  isHiddenFromOverview: true,
+  description: 'Scrollable results container. Renders as a listbox for ARIA. Contains CommandPaletteItem and CommandPaletteGroup children.',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Items, groups, and empty states.',
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible label for the listbox.',
+      default: "'Commands'",
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+    },
+  ],
+  playground: {
+    defaults: {
+      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 = {
+  name: 'CommandPaletteList',
+  isHiddenFromOverview: true,
+  displayName: 'Command Palette List',
+  description: '可滚动的结果容器。作为 listbox 渲染以符合 ARIA 规范。',
+  propDescriptions: {
+    children: '条目、分组和空状态。',
+    label: 'listbox 的无障碍标签。',
+    xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
+  },
+};
+
+export const docsDense = {
+  name: 'CommandPaletteList',
+  isHiddenFromOverview: true,
+  displayName: 'Command Palette List',
+  description: 'scrollable results container; role=listbox',
+  propDescriptions: {
+    children: 'items, groups, empty states',
+    label: 'a11y label for listbox',
+    xstyle: 'StyleX layout styles; must be stylex.create() value',
+  },
+};

package/src/CommandPalette/CommandPaletteList.test.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandPaletteList.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Unit tests for CommandPaletteList
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {CommandPaletteList} from './CommandPaletteList';
+
+describe('CommandPaletteList', () => {
+  it('renders children', () => {
+    render(
+      <CommandPaletteList>
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </CommandPaletteList>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+    expect(screen.getByText('Item 2')).toBeInTheDocument();
+  });
+
+  it('has listbox role', () => {
+    render(
+      <CommandPaletteList>
+        <div>Item</div>
+      </CommandPaletteList>,
+    );
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  it('has default aria-label', () => {
+    render(
+      <CommandPaletteList>
+        <div>Item</div>
+      </CommandPaletteList>,
+    );
+    expect(screen.getByRole('listbox')).toHaveAttribute(
+      'aria-label',
+      'Commands',
+    );
+  });
+
+  it('supports custom label', () => {
+    render(
+      <CommandPaletteList label="Search results">
+        <div>Item</div>
+      </CommandPaletteList>,
+    );
+    expect(screen.getByRole('listbox')).toHaveAttribute(
+      'aria-label',
+      'Search results',
+    );
+  });
+});

package/src/CommandPalette/CommandPaletteList.tsx

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandPaletteList.tsx
+ * @input Uses React, StyleX, CommandPaletteContext
+ * @output Exports CommandPaletteList component
+ * @position Sub-component; scrollable results container
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/CommandPalette/index.ts
+ * - /packages/cli/templates/blocks/components/CommandPalette/ (showcase blocks)
+ */
+
+'use client';
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+import {spacingVars} from '../theme/tokens.stylex';
+import {useCommandPaletteContext} from './CommandPaletteContext';
+import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
+
+const styles = stylex.create({
+  list: {
+    overflowY: 'auto',
+    maxHeight: '100%',
+    padding: spacingVars['--spacing-1'],
+    flex: 1,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-0-5'],
+  },
+});
+
+export interface CommandPaletteListProps extends BaseProps<HTMLDivElement> {
+  /**
+   * Ref forwarded to the root element.
+   */
+  ref?: React.Ref<HTMLDivElement>;
+
+  /**
+   * Command palette items, groups, empty states, etc.
+   */
+  children: ReactNode;
+
+  /**
+   * Accessible label for the listbox.
+   * @default 'Commands'
+   */
+  label?: string;
+}
+
+/**
+ * Scrollable results container for the command palette.
+ * Renders as a listbox for ARIA compliance.
+ *
+ * When used inside CommandPalette, automatically gets the correct
+ * ID for aria-controls linking with the input.
+ *
+ * @compositionHint Place inside CommandPalette, after CommandPaletteInput.
+ *   Contains CommandPaletteItem and CommandPaletteGroup children.
+ *
+ * @example
+ * ```
+ * <CommandPaletteList>
+ *   <CommandPaletteItem value="home" onSelect={goHome}>
+ *     Go Home
+ *   </CommandPaletteItem>
+ * </CommandPaletteList>
+ * ```
+ */
+export function CommandPaletteList({
+  children,
+  label: labelFromProps,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...props
+}: CommandPaletteListProps) {
+  const t = useTranslator();
+  const label = labelFromProps ?? t('@pharos.commandPalette.list.label');
+  const ctx = useCommandPaletteContext();
+
+  return (
+    <div
+      ref={ref}
+      id={ctx?.listId}
+      role="listbox"
+      aria-label={label}
+      {...mergeProps(
+        themeProps('command-palette-list'),
+        stylex.props(styles.list, xstyle),
+        className,
+        style,
+      )}
+      {...props}>
+      {children}
+    </div>
+  );
+}
+
+CommandPaletteList.displayName = 'CommandPaletteList';

package/src/CommandPalette/index.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports CommandPalette components and types
+ * @output Exports all CommandPalette components and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header
+ */
+
+export {CommandPalette} from './CommandPalette';
+export type {CommandPaletteProps} from './CommandPalette';
+
+export {CommandPaletteInput} from './CommandPaletteInput';
+export type {CommandPaletteInputProps} from './CommandPaletteInput';
+
+export {CommandPaletteList} from './CommandPaletteList';
+export type {CommandPaletteListProps} from './CommandPaletteList';
+
+export {CommandPaletteItem} from './CommandPaletteItem';
+export type {CommandPaletteItemProps} from './CommandPaletteItem';
+
+export {CommandPaletteGroup} from './CommandPaletteGroup';
+export type {CommandPaletteGroupProps} from './CommandPaletteGroup';
+
+export {CommandPaletteFooter} from './CommandPaletteFooter';
+export type {CommandPaletteFooterProps} from './CommandPaletteFooter';
+
+export {CommandPaletteEmpty} from './CommandPaletteEmpty';
+export type {CommandPaletteEmptyProps} from './CommandPaletteEmpty';
+
+export {useCommandPaletteContext} from './CommandPaletteContext';
+export type {CommandPaletteContextValue} from './CommandPaletteContext';