@pharos-ds/core 0.1.9

package/src/DropdownMenu/renderDropdownItems.tsx

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file renderDropdownItems.tsx
+ * @output Converts data-driven menu items into DropdownMenuItem components
+ * @position Utility; used by DropdownMenu to unify data-driven and compound paths
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Divider} from '../Divider';
+import {DropdownMenuItem} from './DropdownMenuItem';
+import {DropdownMenuSubMenu} from './DropdownMenuSubMenu';
+import {
+  spacingVars,
+  typographyVars,
+  typeScaleVars,
+  colorVars,
+} from '../theme/tokens.stylex';
+import type {
+  DropdownMenuItemData,
+  DropdownMenuOption,
+  DropdownMenuSection,
+} from './DropdownMenu';
+
+const styles = stylex.create({
+  sectionHeading: {
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: spacingVars['--spacing-2'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    color: colorVars['--color-text-secondary'],
+    userSelect: 'none',
+  },
+  divider: {
+    marginBlock: spacingVars['--spacing-1'],
+  },
+});
+
+function getItemKey(item: DropdownMenuItemData): string {
+  return `item-${item.label}`;
+}
+
+function getSectionKey(section: DropdownMenuSection, index: number): string {
+  return `section-${section.title ?? index}`;
+}
+
+/**
+ * Converts data-driven items into DropdownMenuItem components,
+ * so both modes share the same rendering and keyboard navigation path.
+ */
+export function renderDropdownItems(items: DropdownMenuOption[]): ReactNode {
+  const elements: ReactNode[] = [];
+
+  for (let i = 0; i < items.length; i++) {
+    const option = items[i];
+
+    if ('type' in option && option.type === 'divider') {
+      elements.push(<Divider key={`divider-${i}`} xstyle={styles.divider} />);
+    } else if ('type' in option && option.type === 'section') {
+      elements.push(
+        <div
+          key={getSectionKey(option, i)}
+          role="group"
+          aria-label={option.title}>
+          {option.title && (
+            <div {...stylex.props(styles.sectionHeading)} aria-hidden="true">
+              {option.title}
+            </div>
+          )}
+          {option.items.map(item => (
+            <DropdownMenuItem
+              key={getItemKey(item)}
+              icon={item.icon}
+              label={item.label}
+              onClick={item.onClick}
+              isDisabled={item.isDisabled}
+            />
+          ))}
+        </div>,
+      );
+    } else if (!('type' in option)) {
+      // A plain item that declares nested `items` becomes a submenu (data-mode
+      // parity with the compound DropdownMenuSubMenu API); otherwise it's a
+      // leaf. renderDropdownItems owns the recursion and hands the rendered
+      // children to DropdownMenuSubMenu — so DropdownMenuSubMenu never imports
+      // this module back (no import cycle).
+      if (option.items && option.items.length > 0) {
+        elements.push(
+          <DropdownMenuSubMenu
+            key={getItemKey(option)}
+            icon={option.icon}
+            label={option.label}
+            isDisabled={option.isDisabled}>
+            {renderDropdownItems(option.items)}
+          </DropdownMenuSubMenu>,
+        );
+      } else {
+        elements.push(
+          <DropdownMenuItem
+            key={getItemKey(option)}
+            icon={option.icon}
+            label={option.label}
+            onClick={option.onClick}
+            isDisabled={option.isDisabled}
+          />,
+        );
+      }
+    }
+  }
+
+  return elements;
+}

package/src/EmptyState/EmptyState.doc.mjs

@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'EmptyState',
+  displayName: 'Empty State',
+  category: 'Content',
+  keywords: ["emptystate","empty","placeholder","nodata","blank","noresults","illustration","blankslate"],
+  props: [
+    {
+      name: 'title',
+      type: 'string',
+      description:
+        'Primary message rendered as an <h3> heading inside the empty state.',
+      required: true,
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description:
+        'Optional secondary text providing additional context below the title.',
+    },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        'Optional icon or illustration displayed above the title; rendered as decorative (aria-hidden="true").',
+      slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
+    },
+    {
+      name: 'actions',
+      type: 'ReactNode',
+      description:
+        'Optional action buttons displayed below the description, laid out horizontally by default and stacked vertically when isCompact is true.',
+      slotElements: [{__element: 'Button', props: {label: 'Action', variant: 'secondary'}}],
+    },
+    {
+      name: 'headingLevel',
+      type: '1 | 2 | 3 | 4 | 5 | 6',
+      description:
+        'Controls only the rendered HTML heading tag (h1-h6) so the title fits the document outline. This is a semantic change for accessibility and does not change the visual size of the title, which stays fixed regardless of level.',
+      default: '3',
+    },
+    {
+      name: 'isCompact',
+      type: 'boolean',
+      description:
+        'Enables the compact variant with reduced spacing for constrained content areas.',
+      default: 'false',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+    },
+  ],
+  playground: {
+    defaults: {
+      title: 'No results found',
+      description: 'Try adjusting your search or filter criteria.',
+      actions: {__element: 'Button', props: {label: 'Clear filters', variant: 'secondary'}},
+    },
+  },
+  theming: {
+    targets: [
+      {className: 'pharos-empty-state', visualProps: ['variant']},
+    ],
+  },
+  usage: {
+    description: 'EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.',
+    bestPractices: [
+      { guidance: true, description: 'Include a clear title and a call-to-action button so users know how to proceed.' },
+      { guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },
+      { guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },
+      { guidance: false, description: 'Leave an empty state without guidance; always explain what happened and what the user can do next.' },
+      { guidance: false, description: 'Use a generic message like "No data"; be specific about what is empty and why.' },
+      { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
+    ],
+    anatomy: [
+      {name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},
+      {name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},
+      {name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},
+      {name: 'Actions', required: false, description: 'One or two buttons guiding the user to a next step, like "Create project" or "Clear filters".'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'EmptyState',
+  displayName: 'Empty State',
+  props: [
+    {
+      name: 'title',
+      type: 'string',
+      description:
+        '在空状态内部渲染为 <h3> 标题的主要信息。',
+      required: true,
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description:
+        '可选的辅助文本，在标题下方提供额外上下文。',
+    },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        '可选的图标或插图，显示在标题上方；渲染为装饰性元素（aria-hidden="true"）。',
+    },
+    {
+      name: 'actions',
+      type: 'ReactNode',
+      description:
+        '可选的操作按钮，显示在描述下方，默认水平排列，isCompact 为 true 时垂直堆叠。',
+    },
+    {
+      name: 'headingLevel',
+      type: '1 | 2 | 3 | 4 | 5 | 6',
+      description:
+        '仅控制渲染的 HTML 标题标签（h1-h6），使标题适配文档大纲。这是用于无障碍的语义变化，不会改变标题的视觉大小，标题大小始终固定，与级别无关。',
+      default: '3',
+    },
+    {
+      name: 'isCompact',
+      type: 'boolean',
+      description:
+        '启用紧凑变体，减少间距，适用于空间受限的内容区域。',
+      default: 'false',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于布局自定义（外边距、定位、尺寸）的 StyleX 样式。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'pharos-empty-state', visualProps: ['variant']},
+    ],
+  },
+  usage: {
+    description: 'EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.',
+    bestPractices: [
+      { guidance: true, description: 'Include a clear title and a call-to-action button so users know how to proceed.' },
+      { guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },
+      { guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },
+      { guidance: false, description: 'Leave an empty state without guidance; always explain what happened and what the user can do next.' },
+      { guidance: false, description: 'Use a generic message like "No data"; be specific about what is empty and why.' },
+      { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'placeholder when a content area has no data: icon, title, description, action buttons',
+  usage: {
+    description: 'EmptyState shows a placeholder for empty lists, zero search results, first-time setups. Always include a title and next step.',
+    bestPractices: [
+      { guidance: true, description: 'Include a clear title + call-to-action button so users know how to proceed.' },
+      { guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },
+      { guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },
+      { guidance: false, description: 'Leave an empty state without guidance; always explain what happened and what user can do next.' },
+      { guidance: false, description: 'Use a generic message like "No data"; be specific about what is empty and why.' },
+      { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
+    ],
+  },
+  propDescriptions: {
+    title: 'Primary msg rendered as heading (h1-h6) inside empty state.',
+    headingLevel: 'Controls only HTML heading tag (h1-h6) for document outline; does not change visual title size.',
+    description: 'Optional secondary text w/ additional context below title.',
+    icon: 'Optional icon/illustration above title; rendered decorative (aria-hidden="true").',
+    actions: 'Optional action buttons below description; horizontal by default, vertical when isCompact.',
+    isCompact: 'Enables compact variant w/ reduced spacing for constrained areas.',
+    xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
+  },
+};

package/src/EmptyState/EmptyState.test.tsx

@@ -0,0 +1,151 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {EmptyState} from './EmptyState';
+
+describe('EmptyState', () => {
+  it('renders with title', () => {
+    render(<EmptyState title="No results found" />);
+    expect(screen.getByText('No results found')).toBeInTheDocument();
+  });
+
+  it('renders title as h3 by default', () => {
+    render(<EmptyState title="No data" />);
+    const heading = screen.getByRole('heading', {name: 'No data'});
+    expect(heading).toBeInTheDocument();
+    expect(heading.tagName).toBe('H3');
+  });
+
+  it('renders custom heading level', () => {
+    render(<EmptyState title="No data" headingLevel={2} />);
+    const heading = screen.getByRole('heading', {name: 'No data'});
+    expect(heading.tagName).toBe('H2');
+  });
+
+  it('renders all heading levels', () => {
+    const levels = [1, 2, 3, 4, 5, 6] as const;
+    for (const level of levels) {
+      const {unmount} = render(
+        <EmptyState title={`Level ${level}`} headingLevel={level} />,
+      );
+      const heading = screen.getByRole('heading', {
+        name: `Level ${level}`,
+      });
+      expect(heading.tagName).toBe(`H${level}`);
+      unmount();
+    }
+  });
+
+  it('renders with description', () => {
+    render(
+      <EmptyState
+        title="No results"
+        description="Try adjusting your search."
+      />,
+    );
+    expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
+    // Description renders as <div> (never <p>) so block content composes safely.
+    expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
+  });
+
+  it('does not render description when not provided', () => {
+    render(<EmptyState title="No results" />);
+    expect(screen.queryByText('Try adjusting your search.')).toBeNull();
+  });
+
+  it('renders with icon', () => {
+    render(
+      <EmptyState
+        title="No results"
+        icon={<span data-testid="empty-icon">📭</span>}
+      />,
+    );
+    expect(screen.getByTestId('empty-icon')).toBeInTheDocument();
+  });
+
+  it('marks icon as decorative with aria-hidden', () => {
+    render(
+      <EmptyState
+        title="No results"
+        icon={<span data-testid="empty-icon">📭</span>}
+      />,
+    );
+    const iconWrapper = screen.getByTestId('empty-icon').parentElement;
+    expect(iconWrapper).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('does not render icon wrapper when icon is not provided', () => {
+    const {container} = render(<EmptyState title="No results" />);
+    expect(
+      container.querySelector('[aria-hidden="true"]'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('renders with actions', () => {
+    render(
+      <EmptyState
+        title="No results"
+        actions={
+          <button type="button" data-testid="action-btn">
+            Retry
+          </button>
+        }
+      />,
+    );
+    expect(screen.getByTestId('action-btn')).toBeInTheDocument();
+  });
+
+  it('does not render actions wrapper when actions is not provided', () => {
+    const {container} = render(<EmptyState title="No results" />);
+    // Container div + text group div, but no actions wrapper
+    const divs = container.querySelectorAll('div');
+    expect(divs).toHaveLength(2); // container + text group
+  });
+
+  it('has role="status" on the container', () => {
+    render(<EmptyState title="No results" />);
+    expect(screen.getByRole('status')).toBeInTheDocument();
+  });
+
+  it('renders compact variant', () => {
+    render(<EmptyState title="No results" isCompact />);
+    expect(screen.getByRole('status')).toBeInTheDocument();
+    expect(screen.getByText('No results')).toBeInTheDocument();
+  });
+
+  it('forwards ref', () => {
+    const ref = {current: null as HTMLDivElement | null};
+    render(<EmptyState ref={ref} title="No results" />);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it('spreads data-testid', () => {
+    render(<EmptyState title="No results" data-testid="empty-state" />);
+    expect(screen.getByTestId('empty-state')).toBeInTheDocument();
+  });
+
+  it('renders all slots together', () => {
+    render(
+      <EmptyState
+        icon={<span data-testid="icon">🔍</span>}
+        title="No results found"
+        description="Try a different search term."
+        actions={
+          <>
+            <button type="button">Clear filters</button>
+            <button type="button">Go back</button>
+          </>
+        }
+        data-testid="full-empty-state"
+      />,
+    );
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+    expect(screen.getByText('No results found')).toBeInTheDocument();
+    expect(
+      screen.getByText('Try a different search term.'),
+    ).toBeInTheDocument();
+    expect(screen.getByText('Clear filters')).toBeInTheDocument();
+    expect(screen.getByText('Go back')).toBeInTheDocument();
+  });
+});

package/src/EmptyState/EmptyState.tsx

@@ -0,0 +1,203 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file EmptyState.tsx
+ * @input Uses React, HTMLAttributes
+ * @output Exports EmptyState component, EmptyStateProps type
+ * @position Core implementation; consumed by index.ts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/EmptyState/EmptyState.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/EmptyState/EmptyState.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/EmptyState/index.ts (exports if types change)
+ * - /apps/storybook/stories/EmptyState.stories.tsx (storybook stories)
+ * - /packages/cli/templates/blocks/components/EmptyState/ (showcase blocks)
+ */
+
+import {type ReactNode, createElement} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  spacingVars,
+  fontWeightVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
+
+const styles = stylex.create({
+  container: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    textAlign: 'center',
+    gap: spacingVars['--spacing-4'],
+    paddingBlock: spacingVars['--spacing-8'],
+    paddingInline: spacingVars['--spacing-6'],
+  },
+  containerCompact: {
+    gap: spacingVars['--spacing-2'],
+    paddingBlock: spacingVars['--spacing-4'],
+    paddingInline: spacingVars['--spacing-4'],
+  },
+  title: {
+    margin: 0,
+    fontFamily: 'inherit',
+    fontSize: typeScaleVars['--text-large-size'],
+    fontWeight: fontWeightVars['--font-weight-semibold'],
+    lineHeight: typeScaleVars['--text-large-leading'],
+    color: colorVars['--color-text-primary'],
+  },
+  titleCompact: {
+    fontSize: typeScaleVars['--text-label-size'],
+  },
+  description: {
+    margin: 0,
+    fontFamily: 'inherit',
+    fontSize: typeScaleVars['--text-body-size'],
+    fontWeight: fontWeightVars['--font-weight-normal'],
+    lineHeight: typeScaleVars['--text-body-leading'],
+    color: colorVars['--color-text-secondary'],
+  },
+  descriptionCompact: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+  },
+  textGroup: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    maxWidth: '360px',
+  },
+  actions: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    marginTop: spacingVars['--spacing-1'],
+  },
+  actionsCompact: {
+    flexDirection: 'column',
+  },
+});
+
+export interface EmptyStateProps extends BaseProps<HTMLDivElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLDivElement>;
+  /**
+   * The primary message displayed in the empty state.
+   */
+  title: string;
+  /**
+   * Optional secondary text providing additional context.
+   */
+  description?: string;
+  /**
+   * Optional icon or illustration displayed above the title.
+   * Rendered as decorative (aria-hidden="true").
+   */
+  icon?: ReactNode;
+  /**
+   * Optional action buttons displayed below the description.
+   * Laid out horizontally by default, stacked vertically when `isCompact`.
+   */
+  actions?: ReactNode;
+  /**
+   * Semantic heading level for the title element.
+   * Controls only the rendered HTML tag (h1–h6) so the title fits the
+   * document outline. This is a semantic change for accessibility and does
+   * not change the visual size of the title, which stays fixed regardless
+   * of level.
+   * @default 3
+   */
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+  /**
+   * Use compact variant for constrained spaces with reduced spacing.
+   * @default false
+   */
+  isCompact?: boolean;
+}
+
+/**
+ * An empty state placeholder for content areas with no data.
+ * Displays an icon or illustration, title, optional description, and action buttons.
+ *
+ * Uses `role="status"` to announce content to screen readers.
+ * Styles use Pharos theme tokens via StyleX. Wrap your app in <Theme> to apply a theme.
+ *
+ * @example
+ * ```
+ * <EmptyState
+ *   title="No results found"
+ *   description="Try adjusting your search or filters."
+ * />
+ * <EmptyState
+ *   icon={<Icon icon={InboxIcon} size="lg" />}
+ *   title="No messages"
+ *   description="You're all caught up!"
+ *   actions={<Button label="Compose" variant="primary" />}
+ * />
+ * ```
+ */
+export function EmptyState({
+  title,
+  description,
+  icon,
+  actions,
+  headingLevel = 3,
+  isCompact = false,
+  xstyle,
+  className,
+  style,
+  ref,
+  ...props
+}: EmptyStateProps) {
+  const HeadingTag = `h${headingLevel}` as const;
+  return (
+    <div
+      ref={ref}
+      role="status"
+      {...mergeProps(
+        themeProps('empty-state', {variant: isCompact ? 'compact' : null}),
+        stylex.props(
+          styles.container,
+          isCompact && styles.containerCompact,
+          xstyle,
+        ),
+        className,
+        style,
+      )}
+      {...props}>
+      {icon != null && <div aria-hidden="true">{icon}</div>}
+      <div {...stylex.props(styles.textGroup)}>
+        {createElement(
+          HeadingTag,
+          stylex.props(styles.title, isCompact && styles.titleCompact),
+          title,
+        )}
+        {description != null && (
+          // Rendered as <div> (not <p>): description accepts ReactNode and a
+          // <p> cannot legally contain block children, which causes hydration
+          // mismatches. The StyleX style sets margin: 0, so appearance is
+          // unchanged.
+          <div
+            {...stylex.props(
+              styles.description,
+              isCompact && styles.descriptionCompact,
+            )}>
+            {description}
+          </div>
+        )}
+      </div>
+      {actions != null && (
+        <div
+          {...stylex.props(styles.actions, isCompact && styles.actionsCompact)}>
+          {actions}
+        </div>
+      )}
+    </div>
+  );
+}
+
+EmptyState.displayName = 'EmptyState';

package/src/EmptyState/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file EmptyState component barrel export
+ */
+
+export {EmptyState} from './EmptyState';
+export type {EmptyStateProps} from './EmptyState';