@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/theme/tokens.ts

@@ -0,0 +1,196 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tokens.ts
+ * @input DefinedTheme objects and token names
+ * @output Server-safe token helpers for resolving theme values and building CSS var references
+ * @position Public theme utility; backs useTheme and external styling-library adapters
+ *
+ * Use these helpers when code outside React hooks needs Astryx token values:
+ * build-time theme adapters, chart configuration, canvas/SVG rendering, tests,
+ * or plain JS theme objects for other styling libraries.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/useTheme.ts
+ * - /packages/core/src/theme/index.ts
+ */
+
+import {
+  tokenDefaults,
+  type DefinedTheme,
+  type TokenName,
+  type TokenValue,
+} from './defineTheme';
+
+/** Resolved color mode used when choosing the side of light/dark token values. */
+export type ResolvedThemeMode = 'light' | 'dark';
+
+/** Options for resolving all tokens from a theme object. */
+export interface ResolveThemeTokensOptions {
+  /** Effective mode to resolve. Pass an explicit value; this helper does not read media queries. */
+  mode: ResolvedThemeMode;
+}
+
+/** Options for resolving one token from a theme object. */
+export interface ResolveThemeTokenOptions extends ResolveThemeTokensOptions {
+  /** Value to return when the token name is unknown. Defaults to an empty string. */
+  fallback?: string;
+}
+
+/**
+ * Return a CSS custom property reference for an Astryx token name.
+ *
+ * Useful for non-StyleX styling-library configs (Panda, Chakra, MUI,
+ * Emotion, styled-components, UnoCSS, CSS Modules) where the value should
+ * stay connected to the active Astryx theme through the CSS cascade.
+ *
+ * @example
+ * ```ts
+ * const theme = {
+ *   colors: {
+ *     text: tokenVar('--color-text-primary'),
+ *     surface: tokenVar('--color-background-surface'),
+ *   },
+ * };
+ * ```
+ */
+export function tokenVar(name: TokenName | (string & {})): string {
+  return `var(${name})`;
+}
+
+/** Flat map of every known Astryx token name to its `var(--token-name)` reference. */
+export const tokenVars: Record<TokenName, string> = Object.fromEntries(
+  Object.keys(tokenDefaults).map(name => [name, tokenVar(name)]),
+) as Record<TokenName, string>;
+
+/**
+ * Split the arguments of a CSS function body on the first top-level comma.
+ * Handles nested functions such as rgba(), color-mix(), var(), and quoted strings.
+ */
+function splitTopLevelComma(input: string): [string, string] | null {
+  let depth = 0;
+  let quote: '"' | "'" | null = null;
+  let isEscaped = false;
+
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+
+    if (quote !== null) {
+      if (isEscaped) {
+        isEscaped = false;
+      } else if (char === '\\') {
+        isEscaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+
+    if (char === '(') {
+      depth++;
+      continue;
+    }
+
+    if (char === ')') {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+
+    if (char === ',' && depth === 0) {
+      return [input.slice(0, i).trim(), input.slice(i + 1).trim()];
+    }
+  }
+
+  return null;
+}
+
+/** Parse a CSS light-dark(light, dark) function into its two argument values. */
+function parseLightDark(value: string): [light: string, dark: string] | null {
+  const trimmed = value.trim();
+  const prefix = 'light-dark(';
+  if (!trimmed.startsWith(prefix) || !trimmed.endsWith(')')) {
+    return null;
+  }
+
+  const inner = trimmed.slice(prefix.length, -1);
+  return splitTopLevelComma(inner);
+}
+
+/**
+ * Resolve a token value for a specific mode.
+ *
+ * - `[light, dark]` tuple → picks the side for `mode`
+ * - `light-dark(light, dark)` string → parses nested CSS values and picks the side
+ * - any other string → returned unchanged
+ */
+function resolveXDSTokenValue(
+  value: TokenValue,
+  mode: ResolvedThemeMode,
+): string {
+  if (Array.isArray(value)) {
+    return mode === 'dark' ? value[1] : value[0];
+  }
+
+  const parsed = parseLightDark(value);
+  if (parsed !== null) {
+    return mode === 'dark' ? parsed[1] : parsed[0];
+  }
+
+  return value;
+}
+
+/**
+ * Resolve all Astryx token values for a theme and effective color mode.
+ *
+ * The result starts with `tokenDefaults`, applies `theme.tokens`, then
+ * reapplies `theme.__inputTokens` when available so explicit tuple overrides
+ * retain their original light/dark sides instead of relying on CSS parsing.
+ * This mirrors the token resolution used by `useTheme()` but does not need
+ * React context or media queries.
+ *
+ * Pass `theme` as null/undefined to resolve defaults only.
+ */
+export function resolveThemeTokens(
+  theme: DefinedTheme | null | undefined,
+  options: ResolveThemeTokensOptions,
+): Record<string, string> {
+  const {mode} = options;
+  const resolved: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(tokenDefaults)) {
+    resolved[key] = resolveXDSTokenValue(value, mode);
+  }
+
+  if (theme == null) {
+    return resolved;
+  }
+
+  for (const [key, value] of Object.entries(theme.tokens)) {
+    resolved[key] = resolveXDSTokenValue(value, mode);
+  }
+
+  if (theme.__inputTokens) {
+    for (const [key, value] of Object.entries(theme.__inputTokens)) {
+      if (value !== undefined) {
+        resolved[key] = resolveXDSTokenValue(value, mode);
+      }
+    }
+  }
+
+  return resolved;
+}
+
+/** Resolve one Astryx token value for a theme and effective color mode. */
+export function resolveThemeToken(
+  theme: DefinedTheme | null | undefined,
+  name: TokenName | (string & {}),
+  options: ResolveThemeTokenOptions,
+): string {
+  const tokens = resolveThemeTokens(theme, options);
+  return tokens[name] ?? options.fallback ?? '';
+}

package/src/theme/types.ts

@@ -0,0 +1,246 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Astryx Type Definitions
+ *
+ * Shared types used across Astryx 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). Astryx 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 (`.astryx-text.<custom-type> { ... }`).
+ *
+ * To add type-safe custom types, use module augmentation:
+ * ```ts
+ * declare module '@astryxdesign/core/theme' {
+ *   interface CustomTextTypes {
+ *     hero: true;
+ *     caption: true;
+ *   }
+ * }
+ * ```
+ *
+ * `astryx 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'
+  | 'active'
+  | '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: '@astryxdesign/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,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, vi} from 'vitest';
+import {renderHook} 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'}),
+    );
+  });
+});