@cdx-ui/styles 0.0.1-beta.54 → 0.0.1-beta.55

package/src/types.ts

@@ -0,0 +1,112 @@
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A DTCG token leaf node. */
+export interface TokenValue {
+  $type: string;
+  $value: string | number;
+  $extensions?: Record<string, unknown>;
+}
+
+/** Recursive token group — every non-leaf node in a theme object. */
+export interface TokenGroup {
+  [key: string]: TokenValue | TokenGroup;
+}
+
+/** The three built-in Forge UI theme presets. */
+export type Preset = 'poise' | 'prestige' | 'pulse';
+
+/** Theme metadata stored under `$extensions.com.forge.ui.theme`. */
+export interface ThemeMetadata {
+  name: string;
+  preset: Preset;
+  schemaVersion: string;
+}
+
+/** Override metadata stored under `$extensions.com.forge.ui.themeOverride`. */
+export interface ThemeOverrideMetadata {
+  basePreset: Preset;
+  schemaVersion: string;
+}
+
+/**
+ * A complete Forge UI theme object (DTCG-compatible).
+ *
+ * Presets (Poise, Prestige, Pulse) are full theme objects. At runtime the
+ * build-time default preset is augmented by FI overrides via
+ * `applyThemeOverrides`.
+ */
+export type ThemeObject = TokenGroup & {
+  $extensions: {
+    'com.forge.ui.theme': ThemeMetadata;
+    [key: string]: unknown;
+  };
+  modes: {
+    light: TokenGroup;
+    dark: TokenGroup;
+  };
+  platform: {
+    web: TokenGroup;
+    ios: TokenGroup;
+    android: TokenGroup;
+  };
+};
+
+/**
+ * A theme override using the hybrid input + semantic structure.
+ *
+ * - `inputs` — flat map of abstract FI-selected brand values (e.g.
+ *   `brandPrimary`, `displayFont`). Palette generation expands these into
+ *   full token scales at runtime.
+ * - `overrides` — per-mode flat maps of token dot-paths to resolved values
+ *   for direct semantic token overrides beyond what inputs generate.
+ * - `$extensions` — required metadata including base preset and schema version.
+ */
+export interface ThemeOverride {
+  $extensions: {
+    'com.forge.ui.themeOverride': ThemeOverrideMetadata;
+    [key: string]: unknown;
+  };
+  inputs?: Record<string, string | number>;
+  overrides?: Partial<Record<Mode, Record<string, string | number>>>;
+}
+
+export type Mode = 'light' | 'dark';
+export type Platform = 'web' | 'ios' | 'android';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Current override schema version. Consuming apps gate compatibility on this. */
+export const OVERRIDE_SCHEMA_VERSION = '1.0.0' as const;
+
+/**
+ * Schema versions that consuming apps accept. Includes the current version and
+ * may include the immediately prior version during transition windows.
+ * @see docs/internal/token-architecture/16-override-structure.md § 4
+ */
+export const SUPPORTED_OVERRIDE_SCHEMA_VERSIONS: readonly string[] = ['1.0.0'] as const;
+
+/**
+ * Schema-level mapping from known input keys to the token path pattern each
+ * affects. Used by override application (S5) to route inputs to the correct
+ * palette/token namespace. Distinct from the full runtime map (S3).
+ */
+export const INPUT_TOKEN_MAP = {
+  brandPrimary: 'color.brand',
+  accentPrimary: 'color.accent',
+  basePrimary: 'color.base',
+  displayFont: 'font.display',
+} as const satisfies Record<string, string>;
+
+/**
+ * Allowed display font families per preset, consumed by the theme editor for
+ * font selection and by consuming apps for validation.
+ */
+export const presetFonts: Record<Preset, readonly string[]> = {
+  poise: ['Crimson Pro', 'Bitter', 'DM Sans'],
+  prestige: ['Libre Caslon Text', 'Cormorant', 'Libre Franklin'],
+  pulse: ['Outfit', 'Manrope', 'Public Sans'],
+} as const;