@pharos-ds/core 0.1.9

package/src/Icon/Icon.doc.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'Icon',
+  displayName: 'Icon',
+  category: 'Content',
+  keywords: ["icon","svg","glyph","symbol","pictogram","graphic","vector"],
+  playground: {
+    // `icon` is required and its type can't be auto-generated, so the
+    // properties-tab preview showed "Missing: icon". Seed a valid semantic
+    // icon name so the interactive preview renders.
+    defaults: {
+      icon: 'search',
+    },
+  },
+  props: [
+    {
+      name: 'icon',
+      type: 'IconName | ComponentType<SVGProps>',
+      description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+      required: true,
+    },
+    {
+      name: 'color',
+      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
+      description: 'Color variant mapped to Pharos icon color tokens.',
+      default: "'inherit'",
+    },
+    {
+      name: 'size',
+      type: "'xsm' | 'sm' | 'md' | 'lg'",
+      description: 'Icon size.',
+      default: "'md'",
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons: one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for customization (color, size, opacity). Folded into the icon\'s own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'pharos-icon', visualProps: ['color', 'size']},
+    ],
+  },
+  usage: {
+    description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    bestPractices: [
+      { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
+      { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
+      { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop: it sets role="img" + aria-label and unhides the icon.' },
+      { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
+      { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
+      { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
+      { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
+      { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
+      { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
+      { guidance: false, description: 'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'Icon',
+  displayName: 'Icon',
+  props: [
+    {
+      name: 'icon',
+      type: 'IconName | ComponentType<SVGProps>',
+      description: '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+      required: true,
+    },
+    {
+      name: 'color',
+      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
+      description: '映射到 Pharos 图标颜色令牌的颜色变体。',
+      default: "'inherit'",
+    },
+    {
+      name: 'size',
+      type: "'xsm' | 'sm' | 'md' | 'lg'",
+      description: '图标尺寸。',
+      default: "'md'",
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'pharos-icon', visualProps: ['color', 'size']},
+    ],
+  },
+  usage: {
+    description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    bestPractices: [
+      { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
+      { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
+      { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
+      { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
+      { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
+      { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
+      { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
+      { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
+      { guidance: false, description: 'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Renders icons w/ Pharos design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
+  usage: {
+    description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    bestPractices: [
+      { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
+      { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
+      { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), set an accessible name via `label`: sets role="img" + aria-label, unhides icon.' },
+      { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
+      { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
+      { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
+      { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
+      { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
+      { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
+      { guidance: false, description: '`name` prop, which does not exist. Use `icon` to specify which icon to render.' },
+    ],
+  },
+  propDescriptions: {
+    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
+    color: 'Color variant mapped to Pharos icon color tokens.',
+    size: 'Icon size.',
+    label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
+    xstyle: 'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
+  },
+};

package/src/Icon/Icon.test.tsx

@@ -0,0 +1,371 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Icon.test.tsx
+ * @input Uses vitest, @testing-library/react, Icon component
+ * @output Unit tests for Icon component behavior
+ * @position Testing; validates Icon.tsx implementation
+ *
+ * SYNC: When Icon.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {TestIcon} from '../__tests__/TestIcon';
+import {Icon} from './Icon';
+
+describe('Icon', () => {
+  it('renders the icon component', () => {
+    render(<Icon icon={TestIcon} data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+  });
+
+  it('renders as an SVG element', () => {
+    render(<Icon icon={TestIcon} data-testid="icon" />);
+    const icon = screen.getByTestId('icon');
+    expect(icon.tagName.toLowerCase()).toBe('svg');
+  });
+
+  it('applies aria-hidden by default', () => {
+    render(<Icon icon={TestIcon} data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('renders with different color variants', () => {
+    const {rerender} = render(
+      <Icon icon={TestIcon} color="primary" data-testid="icon" />,
+    );
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} color="secondary" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} color="accent" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} color="success" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} color="error" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} color="warning" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} color="inherit" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+  });
+
+  it('renders with non-semantic color variants', () => {
+    const nonSemanticColors = [
+      'blue',
+      'red',
+      'green',
+      'gray',
+      'cyan',
+      'teal',
+      'yellow',
+      'orange',
+      'pink',
+      'purple',
+    ] as const;
+    const {rerender} = render(
+      <Icon icon={TestIcon} color={nonSemanticColors[0]} data-testid="icon" />,
+    );
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    for (const c of nonSemanticColors.slice(1)) {
+      rerender(<Icon icon={TestIcon} color={c} data-testid="icon" />);
+      expect(screen.getByTestId('icon')).toBeInTheDocument();
+    }
+  });
+
+  it('renders with different size variants', () => {
+    const {rerender} = render(
+      <Icon icon={TestIcon} size="xsm" data-testid="icon" />,
+    );
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} size="sm" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} size="md" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+
+    rerender(<Icon icon={TestIcon} size="lg" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+  });
+
+  it('sizes component-mode icons in rem so they scale with root font-size', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon={TestIcon}
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      unmount();
+    }
+  });
+
+  it('sizes registry (string-mode) icons in rem, including fontSize', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon="check"
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      // fontSize is expressed in rem so 1em-based registry icons scale too.
+      expect(style.fontSize).toBe(expected);
+      unmount();
+    }
+  });
+
+  it('forwards ref correctly', () => {
+    const ref = vi.fn();
+    render(<Icon icon={TestIcon} ref={ref} />);
+    expect(ref).toHaveBeenCalledWith(expect.any(SVGSVGElement));
+  });
+
+  it('passes additional SVG props', () => {
+    render(
+      <Icon icon={TestIcon} data-testid="icon" role="img" aria-label="Home" />,
+    );
+    const icon = screen.getByTestId('icon');
+    expect(icon).toHaveAttribute('role', 'img');
+    expect(icon).toHaveAttribute('aria-label', 'Home');
+  });
+
+  it('uses default color and size when not specified', () => {
+    render(<Icon icon={TestIcon} data-testid="icon" />);
+    // The component should render without errors with defaults
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+  });
+
+  it('applies aria-hidden by default in string (registry) mode', () => {
+    render(<Icon icon="check" data-testid="icon" />);
+    expect(screen.getByTestId('icon')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('lets a string-mode icon be made meaningful by overriding aria-hidden', () => {
+    render(
+      <Icon
+        icon="check"
+        data-testid="icon"
+        role="img"
+        aria-label="Done"
+        aria-hidden={false}
+      />,
+    );
+    const icon = screen.getByTestId('icon');
+    expect(icon).toHaveAttribute('role', 'img');
+    expect(icon).toHaveAttribute('aria-label', 'Done');
+    expect(icon).toHaveAttribute('aria-hidden', 'false');
+  });
+
+  describe('label (accessible name)', () => {
+    it('makes a component-mode icon meaningful: role="img" + aria-label, no aria-hidden', () => {
+      render(<Icon icon={TestIcon} label="Completed" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('role', 'img');
+      expect(icon).toHaveAttribute('aria-label', 'Completed');
+      expect(icon).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('makes a string-mode (registry) icon meaningful: role="img" + aria-label, no aria-hidden', () => {
+      render(<Icon icon="check" label="Completed" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('role', 'img');
+      expect(icon).toHaveAttribute('aria-label', 'Completed');
+      expect(icon).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('keeps the decorative default when label is omitted (component mode)', () => {
+      render(<Icon icon={TestIcon} data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('keeps the decorative default when label is omitted (string mode)', () => {
+      render(<Icon icon="check" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('treats an empty string label as decorative (component mode)', () => {
+      render(<Icon icon={TestIcon} label="" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('treats an empty string label as decorative (string mode)', () => {
+      render(<Icon icon="check" label="" data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon).not.toHaveAttribute('role');
+      expect(icon).not.toHaveAttribute('aria-label');
+    });
+
+    it('lets an explicit aria-hidden win over label (component mode)', () => {
+      render(
+        <Icon icon={TestIcon} label="Close" aria-hidden data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('lets an explicit aria-hidden win over label (string mode)', () => {
+      render(
+        <Icon icon="check" label="Close" aria-hidden data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('lets an explicit aria-label override the label-derived name (component mode)', () => {
+      render(
+        <Icon
+          icon={TestIcon}
+          label="Close"
+          aria-label="Dismiss"
+          data-testid="icon"
+        />,
+      );
+      expect(screen.getByTestId('icon')).toHaveAttribute(
+        'aria-label',
+        'Dismiss',
+      );
+    });
+
+    it('lets an explicit role override the label-derived role (string mode)', () => {
+      render(
+        <Icon
+          icon="check"
+          label="Close"
+          role="presentation"
+          data-testid="icon"
+        />,
+      );
+      expect(screen.getByTestId('icon')).toHaveAttribute(
+        'role',
+        'presentation',
+      );
+    });
+  });
+
+  describe('styling prop handling', () => {
+    it('composes a consumer className with the internal classes (string mode)', () => {
+      render(
+        <Icon icon="check" className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      // Consumer className must survive alongside the stable pharos-icon class
+      // and the StyleX classes — previously it was clobbered by the later
+      // internal spread.
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('pharos-icon');
+      // At least one StyleX-generated class is still present.
+      expect(icon.className.split(' ').length).toBeGreaterThan(2);
+    });
+
+    it('forwards a consumer className in component (SVG) mode', () => {
+      render(
+        <Icon icon={TestIcon} className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('pharos-icon');
+    });
+
+    it('merges a consumer style onto the rendered element (string mode)', () => {
+      render(<Icon icon="check" style={{opacity: 0.5}} data-testid="icon" />);
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('merges a consumer style onto the rendered element (component mode)', () => {
+      render(
+        <Icon icon={TestIcon} style={{opacity: 0.5}} data-testid="icon" />,
+      );
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('applies xstyle to the rendered element (string mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(<Icon icon="check" xstyle={overrides.root} data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      // xstyle is folded into stylex.props, so it contributes a StyleX class
+      // (and, in jsdom's stylex runtime, an inline style) alongside the base
+      // color/size classes rather than clobbering them.
+      expect(icon).toHaveClass('pharos-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('applies xstyle to the rendered element (component mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(
+        <Icon icon={TestIcon} xstyle={overrides.root} data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('pharos-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (string mode)', () => {
+      const {container} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.pharos-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.pharos-icon') as HTMLElement;
+      // Default output is identical to itself — the styling-prop handling adds
+      // nothing (no extra class, no inline style) unless a prop is passed.
+      expect(icon.className).toBe(refIcon.className);
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (component mode)', () => {
+      const {container} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.pharos-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.pharos-icon') as HTMLElement;
+      // SVGElement.className is an SVGAnimatedString, so compare the class
+      // attribute string rather than the property object.
+      expect(icon.getAttribute('class')).toBe(refIcon.getAttribute('class'));
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+  });
+});