@pharos-ds/core 0.1.9

package/src/theme/types.ts

@@ -0,0 +1,246 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Pharos Type Definitions
+ *
+ * Shared types used across Pharos components.
+ */
+
+// =============================================================================
+// Typography config types
+// =============================================================================
+
+/**
+ * Named font weight — maps to var(--font-weight-*) at the token layer.
+ * Raw CSS values (e.g. '800') are accepted as an escape hatch.
+ */
+export type FontWeight =
+  | 'normal'
+  | 'medium'
+  | 'semibold'
+  | 'bold'
+  | (string & {});
+
+/**
+ * A typography role declaration (body, heading, or code).
+ *
+ * Fonts must be loaded by the consumer (e.g. via a <link> tag in <head>
+ * or an @import in CSS). Pharos does not handle font loading — it only
+ * sets the font-family token so the font is used once available.
+ *
+ * @example
+ * ```
+ * body: {
+ *   family: 'Geist',
+ *   fallbacks: '"Geist Fallback", -apple-system, sans-serif',
+ *   weight: 'normal',
+ * }
+ * ```
+ */
+export interface TypographyRole {
+  /** Primary font name — must be loaded by the consumer (e.g. Google Fonts link tag) */
+  family?: string;
+  /** CSS fallback font stack (appended after family in the computed --font-* token) */
+  fallbacks?: string;
+  /** Default font weight for this role */
+  weight?: FontWeight;
+  /** Per-level weight overrides (heading only: keys are heading levels 1–6) */
+  weights?: Partial<Record<1 | 2 | 3 | 4 | 5 | 6, FontWeight>>;
+}
+
+/**
+ * Unified typography configuration.
+ *
+ * - `scale` controls the geometric type scale (base size + ratio)
+ * - `body`, `heading`, `code` declare fonts, fallbacks, weights per role
+ * - `heading` inherits family/fallbacks from `body` if not specified
+ *
+ * Font loading is the consumer's responsibility. Add a <link> or @import
+ * for your fonts before rendering the theme.
+ *
+ * @example
+ * ```
+ * typography: {
+ *   scale: { base: 14, ratio: 1.2 },
+ *   body: { family: 'Geist', fallbacks: '-apple-system, sans-serif' },
+ *   heading: { weight: 'semibold', weights: { 3: 'bold', 4: 'bold' } },
+ *   code: { family: 'Geist Mono', fallbacks: '"SF Mono", monospace' },
+ * }
+ * ```
+ */
+export interface TypographyConfig {
+  /** Type scale: generates text size tokens from base + ratio */
+  scale?: {base: number; ratio: number};
+  /** Body text font configuration */
+  body?: TypographyRole;
+  /** Heading font configuration. Inherits family/fallbacks/url from body if omitted. */
+  heading?: TypographyRole;
+  /** Code/monospace font configuration */
+  code?: TypographyRole;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type StyleXStyles = any;
+
+/**
+ * Theme mode - system follows OS preference
+ */
+export type ThemeMode = 'system' | 'light' | 'dark';
+
+/**
+ * Heading element tags (h1–h6). Distinct from the Heading component's numeric
+ * `HeadingLevel` (1–6) — this is the HTML tag form used by prose theming.
+ */
+export type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+/**
+ * Built-in semantic text types for Text.
+ */
+export type BuiltinTextType =
+  | 'body'
+  | 'large'
+  | 'label'
+  | 'supporting'
+  | 'code'
+  | 'display-1'
+  | 'display-2'
+  | 'display-3'
+  | 'inherit';
+
+/**
+ * Semantic text types for Text.
+ *
+ * Themes can define custom text types via component overrides in defineTheme.
+ * Custom types render with `body` baseline styles and receive their visual
+ * treatment from theme CSS (`.pharos-text.<custom-type> { ... }`).
+ *
+ * To add type-safe custom types, use module augmentation:
+ * ```ts
+ * declare module '@pharos-ds/core/theme' {
+ *   interface CustomTextTypes {
+ *     hero: true;
+ *     caption: true;
+ *   }
+ * }
+ * ```
+ *
+ * `pharos theme build` generates these augmentations automatically when it
+ * detects new `type:*` values in a theme's component overrides.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface CustomTextTypes {}
+
+export type TextType = BuiltinTextType | (keyof CustomTextTypes & string);
+
+/**
+ * Text size scale for Text size prop override
+ * Maps to --text-* tokens
+ */
+export type TextSize =
+  | '4xs'
+  | '3xs'
+  | '2xs'
+  | 'xsm'
+  | 'sm'
+  | 'base'
+  | 'lg'
+  | 'xl'
+  | '2xl'
+  | '3xl'
+  | '4xl';
+
+/**
+ * Font weight variants for Text/Heading
+ */
+export type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+
+/**
+ * Text color variants for Text/Heading
+ */
+export type TextColor =
+  | 'primary'
+  | 'secondary'
+  | 'disabled'
+  | 'placeholder'
+  | 'accent'
+  | 'inherit';
+
+/**
+ * Display mode for Text/Heading
+ */
+export type TextDisplay = 'inline' | 'block';
+
+/**
+ * Word break behavior for truncated text
+ */
+export type WordBreak = 'break-word' | 'break-all';
+
+/**
+ * Text wrap behavior
+ */
+export type TextWrap = 'wrap' | 'nowrap' | 'balance' | 'pretty';
+
+/**
+ * Text alignment (justification). Uses logical properties (start/end)
+ * for i18n/RTL compatibility.
+ */
+export type TextJustify = 'start' | 'center' | 'end';
+
+/**
+ * Allowed CSS properties for Text/Heading xstyle prop.
+ * Constrained to layout-only properties to prevent typography escapes.
+ */
+export type TextXStyleAllowed = {
+  // Index signature required for StyleXStyles compatibility
+  [key: string]: unknown;
+
+  // Margins
+  margin?: unknown;
+  marginTop?: unknown;
+  marginBottom?: unknown;
+  marginStart?: unknown;
+  marginEnd?: unknown;
+  marginBlock?: unknown;
+  marginBlockStart?: unknown;
+  marginBlockEnd?: unknown;
+  marginInline?: unknown;
+  marginInlineStart?: unknown;
+  marginInlineEnd?: unknown;
+
+  // Width constraints
+  width?: unknown;
+  minWidth?: unknown;
+  maxWidth?: unknown;
+
+  // Flex child properties
+  alignSelf?: unknown;
+  flexBasis?: unknown;
+  flexGrow?: unknown;
+  flexShrink?: unknown;
+
+  // Text layout (non-typography)
+  textAlign?: unknown;
+  textAlignLast?: unknown;
+  verticalAlign?: unknown;
+};
+
+/**
+ * Prose element types for typography CSS
+ */
+export type ProseElement =
+  | 'p'
+  | 'ul'
+  | 'ol'
+  | 'li'
+  | 'liLast'
+  | 'blockquote'
+  | 'code'
+  | 'pre'
+  | 'preCode'
+  | 'hr'
+  | 'strong'
+  | 'em'
+  | 'a'
+  | 'aHover'
+  | 'firstChild'
+  | 'lastChild';

package/src/theme/useTheme.doc.mjs

@@ -0,0 +1,134 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useTheme',
+  displayName: 'useTheme',
+  group: 'Utilities',
+  category: 'Utility',
+  keywords: [
+    'theme',
+    'tokens',
+    'color',
+    'mode',
+    'dark',
+    'light',
+    'provider',
+    'data visualization',
+    'canvas',
+    'svg',
+    'chart',
+  ],
+  params: [],
+  returns: [
+    {
+      name: 'name',
+      type: 'string',
+      description:
+        'Name of the nearest theme, or default when no provider is present.',
+    },
+    {
+      name: 'mode',
+      type: "'light' | 'dark'",
+      description:
+        'Resolved effective color mode. system mode is resolved to light or dark.',
+    },
+    {
+      name: 'token',
+      type: '(name: string) => string',
+      description:
+        'Resolve a single design token to its current CSS value for the effective mode.',
+    },
+    {
+      name: 'tokens',
+      type: 'Record<string, string>',
+      description:
+        'All tokens resolved for the current mode, including defaults and theme overrides. Stable until the active theme or mode changes; uses the same resolution logic as resolveThemeTokens(theme, {mode}).',
+    },
+  ],
+  usage: {
+    description:
+      'Programmatic access to theme tokens for non-CSS consumers like SVG, canvas, Vega, D3, maps, or chart libraries that need values in JavaScript instead of CSS custom property references.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use tokens or token(name) when integrating theme colors into SVG attributes, canvas drawing, chart options, or other non-CSS configuration objects inside React components.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use resolveThemeTokens(theme, {mode}) for the same token resolution outside React hooks.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer CSS variables or StyleX tokens for ordinary component styling; use this hook only when JavaScript needs token values.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use data visualization tokens such as --color-data-categorical-blue for chart series instead of arbitrary UI colors.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hardcode light/dark colors in data visualizations: resolve them through the current theme instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Assume the hook reflects every CSS cascade override. It resolves tokens for the current Theme mode; local media-surface overrides and arbitrary external CSS may not be represented.',
+      },
+    ],
+  },
+  relatedComponents: ['Theme'],
+  relatedHooks: ['useMediaQuery'],
+  importPath: '@pharos-ds/core/theme',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Programmatic access to theme tokens for SVG/canvas/charts needing JS values instead of CSS vars.',
+  returnDescriptions: {
+    name: 'nearest theme name or default.',
+    mode: 'resolved light/dark mode.',
+    token: 'resolve one design token for effective mode.',
+    tokens:
+      'all tokens resolved for current mode; stable until theme/mode changes; same resolver as resolveThemeTokens.',
+  },
+  usage: {
+    description:
+      'Programmatic access to theme tokens for SVG/canvas/charts needing JS values instead of CSS vars.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: 'Use tokens/token(name) for SVG/canvas/chart config theme colors in React.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use resolveThemeTokens(theme, {mode}) outside React hooks.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer CSS vars / StyleX tokens for ordinary styling; use hook when JS needs values.',
+      },
+      {
+        guidance: true,
+        description: 'Use --color-data-* tokens for chart series.',
+      },
+      {
+        guidance: false,
+        description: 'Hardcode light/dark chart colors: resolve from current theme.',
+      },
+      {
+        guidance: false,
+        description:
+          'Assume hook reflects arbitrary CSS cascade/media-surface overrides.',
+      },
+    ],
+  },
+};

package/src/theme/useTheme.test.tsx

@@ -0,0 +1,249 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {render, renderHook, act, waitFor} from '@testing-library/react';
+import React from 'react';
+import {Theme} from './Theme';
+import {defineTheme} from './defineTheme';
+import {useTheme} from './useTheme';
+import {resolveThemeTokens} from './tokens';
+
+// Mock useMediaQuery — default to light mode
+vi.mock('../hooks/useMediaQuery', () => ({
+  useMediaQuery: vi.fn(() => false),
+}));
+
+const testTheme = defineTheme({
+  name: 'test',
+  tokens: {
+    '--color-accent': ['#AA0000', '#FF5555'],
+    '--spacing-4': '20px',
+  },
+});
+
+function wrapper({
+  children,
+  mode,
+}: {
+  children: React.ReactNode;
+  mode?: 'light' | 'dark' | 'system';
+}) {
+  return (
+    <Theme theme={testTheme} mode={mode}>
+      {children}
+    </Theme>
+  );
+}
+
+describe('useTheme', () => {
+  it('returns defaults when used outside Theme', () => {
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.name).toBe('default');
+    // Should resolve default light-dark() tokens for light mode (useMediaQuery mocked to false = light)
+    expect(result.current.token('--color-text-primary')).toBe('#0A1317');
+    expect(result.current.token('--spacing-1')).toBe('4px');
+    expect(result.current.mode).toBe('light');
+  });
+
+  it('returns the theme name', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'light'}),
+    });
+    expect(result.current.name).toBe('test');
+  });
+
+  it('resolves tuple tokens to light values in light mode', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'light'}),
+    });
+    expect(result.current.token('--color-accent')).toBe('#AA0000');
+  });
+
+  it('resolves tuple tokens to dark values in dark mode', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'dark'}),
+    });
+    expect(result.current.token('--color-accent')).toBe('#FF5555');
+  });
+
+  it('resolves single-value tokens unchanged', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'light'}),
+    });
+    expect(result.current.token('--spacing-4')).toBe('20px');
+  });
+
+  it('falls back to defaults for tokens not in theme', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'light'}),
+    });
+    // --spacing-1 is not overridden — should be the default '4px'
+    expect(result.current.token('--spacing-1')).toBe('4px');
+  });
+
+  it('resolves default light-dark() string tokens for the mode', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'dark'}),
+    });
+    // --color-text-primary defaults to light-dark(#0A1317, #DFE2E5)
+    expect(result.current.token('--color-text-primary')).toBe('#DFE2E5');
+  });
+
+  it('returns empty string for unknown tokens', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'light'}),
+    });
+    expect(result.current.token('--nonexistent')).toBe('');
+  });
+
+  it('exposes mode reflecting effective mode', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'dark'}),
+    });
+    expect(result.current.mode).toBe('dark');
+  });
+
+  it('provides a tokens map with all resolved values', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'light'}),
+    });
+    const tokens = result.current.tokens;
+    expect(tokens['--color-accent']).toBe('#AA0000');
+    expect(tokens['--spacing-4']).toBe('20px');
+    expect(tokens['--spacing-1']).toBe('4px');
+  });
+
+  it('uses the same token resolution as resolveThemeTokens', () => {
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => wrapper({children, mode: 'dark'}),
+    });
+
+    expect(result.current.tokens).toEqual(
+      resolveThemeTokens(testTheme, {mode: 'dark'}),
+    );
+  });
+
+  it('resolves derived accent tokens to raw values, not var()/color-mix', () => {
+    const brandTheme = defineTheme({name: 'brand', color: {accent: '#0064E0'}});
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => (
+        <Theme theme={brandTheme} mode="light">
+          {children}
+        </Theme>
+      ),
+    });
+
+    const accent = result.current.token('--color-accent');
+    expect(result.current.token('--color-text-accent')).toBe(accent);
+    expect(result.current.token('--color-icon-accent')).toBe(accent);
+    expect(result.current.token('--color-accent-muted')).toMatch(/^(#|rgb)/);
+    expect(result.current.token('--color-accent-muted')).not.toContain('var(');
+    expect(result.current.token('--color-accent-muted')).not.toContain(
+      'color-mix',
+    );
+  });
+});
+
+// Covers the fallback used when a component calls useTheme() with no
+// ThemeContext ancestor reachable — e.g. a detached tree (useToast's
+// fallback viewport, other portals appended straight to document.body).
+// Root Theme instances sync their mode to <html data-theme> specifically so
+// this fallback can resolve the app's actual mode instead of jumping
+// straight to OS preference (see Theme.tsx's useRootThemeSync).
+describe('useTheme mode resolution without a ThemeContext ancestor', () => {
+  afterEach(async () => {
+    // The hook from each `it` below is still mounted and subscribed to the
+    // shared MutationObserver when this runs (RTL's own cleanup — which
+    // unmounts it — is registered after this file's afterEach), so removing
+    // the attribute here triggers a live state update; flush it inside act
+    // so React doesn't warn about an update outside one.
+    await act(async () => {
+      document.documentElement.removeAttribute('data-theme');
+    });
+  });
+
+  it('resolves mode from <html data-theme> when set', () => {
+    document.documentElement.setAttribute('data-theme', 'dark');
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.mode).toBe('dark');
+  });
+
+  it('falls back to OS preference when <html data-theme> is absent', () => {
+    // useMediaQuery is mocked to false (light) at the top of this file.
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.mode).toBe('light');
+  });
+
+  it('stays live when <html data-theme> changes after mount', async () => {
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.mode).toBe('light');
+
+    act(() => {
+      document.documentElement.setAttribute('data-theme', 'dark');
+    });
+
+    await waitFor(() => expect(result.current.mode).toBe('dark'));
+  });
+});
+
+// Covers the singleton MutationObserver + no-op gating in useRootThemeModeAttr:
+// provider-path consumers (a ThemeContext ancestor is reachable) must not
+// create an observer or react to <html data-theme> at all, and every
+// no-context consumer must share exactly one observer, refcounted down to
+// zero as they unmount.
+describe('useTheme root-attribute observer lifecycle', () => {
+  afterEach(() => {
+    document.documentElement.removeAttribute('data-theme');
+    // vi.stubGlobal'd MutationObserver stubs below are torn down here even if
+    // a test fails partway through, instead of relying on a manual restore
+    // line at the end of each test that a mid-test throw would skip.
+    vi.unstubAllGlobals();
+  });
+
+  it('creates no observer and does not re-render provider-path consumers when <html data-theme> changes', () => {
+    const ObserverSpy = vi.fn();
+    vi.stubGlobal('MutationObserver', ObserverSpy);
+
+    const renders = {count: 0};
+    function Consumer() {
+      useTheme();
+      renders.count++;
+      return null;
+    }
+
+    render(
+      <Theme theme={testTheme} mode="light">
+        <Consumer />
+      </Theme>,
+    );
+
+    expect(ObserverSpy).not.toHaveBeenCalled();
+
+    const before = renders.count;
+    act(() => {
+      document.documentElement.setAttribute('data-theme', 'dark');
+    });
+    expect(renders.count).toBe(before);
+  });
+
+  it('shares one observer across multiple no-context consumers and disconnects once all unmount', () => {
+    const observe = vi.fn();
+    const disconnect = vi.fn();
+    const ObserverSpy = vi.fn().mockImplementation(function () {
+      return {observe, disconnect};
+    });
+    vi.stubGlobal('MutationObserver', ObserverSpy);
+
+    const first = renderHook(() => useTheme());
+    const second = renderHook(() => useTheme());
+
+    expect(ObserverSpy).toHaveBeenCalledTimes(1);
+    expect(observe).toHaveBeenCalledTimes(1);
+
+    first.unmount();
+    expect(disconnect).not.toHaveBeenCalled();
+
+    second.unmount();
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
+});