@object-ui/types 0.5.0 → 2.0.0

package/src/theme.ts

@@ -8,281 +8,174 @@
 
 /**
  * @object-ui/types - Theme Schema
- * 
- * Defines theme configuration for dynamic theme switching and customization.
+ *
+ * Defines theme configuration aligned with @objectstack/spec.
+ * Provides the complete design token system: colors, typography,
+ * spacing, borders, shadows, breakpoints, animation, z-index.
+ *
+ * @module theme
+ * @packageDocumentation
  */
 
 import type { BaseSchema } from './base';
 
+// ============================================================================
+// Spec-Canonical Theme Sub-types — imported from @objectstack/spec/ui
+// Rule: "Never Redefine Types. ALWAYS import them."
+// ============================================================================
+
 /**
  * Color Palette Definition
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface ColorPalette {
-  /**
-   * Primary brand color
-   */
-  primary?: string;
-
-  /**
-   * Secondary color
-   */
-  secondary?: string;
-
-  /**
-   * Accent color
-   */
-  accent?: string;
-
-  /**
-   * Background color
-   */
-  background?: string;
-
-  /**
-   * Foreground/text color
-   */
-  foreground?: string;
-
-  /**
-   * Muted color (for less prominent elements)
-   */
-  muted?: string;
-
-  /**
-   * Muted foreground color
-   */
-  mutedForeground?: string;
-
-  /**
-   * Border color
-   */
-  border?: string;
-
-  /**
-   * Input border color
-   */
-  input?: string;
-
-  /**
-   * Ring/focus color
-   */
-  ring?: string;
-
-  /**
-   * Success color
-   */
-  success?: string;
-
-  /**
-   * Warning color
-   */
-  warning?: string;
-
-  /**
-   * Error/destructive color
-   */
-  destructive?: string;
-
-  /**
-   * Info color
-   */
-  info?: string;
-
-  /**
-   * Card background color
-   */
-  card?: string;
-
-  /**
-   * Card foreground color
-   */
-  cardForeground?: string;
-
-  /**
-   * Popover background color
-   */
-  popover?: string;
-
-  /**
-   * Popover foreground color
-   */
-  popoverForeground?: string;
-}
+export type { ColorPalette } from '@objectstack/spec/ui';
 
 /**
  * Typography Configuration
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface Typography {
-  /**
-   * Font family for sans-serif text
-   */
-  fontSans?: string[];
-
-  /**
-   * Font family for serif text
-   */
-  fontSerif?: string[];
-
-  /**
-   * Font family for monospace text
-   */
-  fontMono?: string[];
-
-  /**
-   * Base font size (in rem)
-   */
-  fontSize?: number;
-
-  /**
-   * Line height
-   */
-  lineHeight?: number;
-
-  /**
-   * Font weight for headings
-   */
-  headingWeight?: number;
-
-  /**
-   * Font weight for body text
-   */
-  bodyWeight?: number;
-}
+export type { Typography } from '@objectstack/spec/ui';
 
 /**
  * Spacing Scale Configuration
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface SpacingScale {
-  /**
-   * Base spacing unit (in rem)
-   */
-  base?: number;
-
-  /**
-   * Custom spacing values
-   */
-  scale?: Record<string, string>;
-}
+export type { Spacing } from '@objectstack/spec/ui';
 
 /**
  * Border Radius Configuration
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface BorderRadius {
-  /**
-   * Small radius
-   */
-  sm?: string;
-
-  /**
-   * Default radius
-   */
-  default?: string;
-
-  /**
-   * Medium radius
-   */
-  md?: string;
-
-  /**
-   * Large radius
-   */
-  lg?: string;
-
-  /**
-   * Extra large radius
-   */
-  xl?: string;
-}
+export type { BorderRadius } from '@objectstack/spec/ui';
 
 /**
- * Theme Mode
+ * Shadow Configuration
+ * Canonical definition from @objectstack/spec/ui.
  */
-export type ThemeMode = 'light' | 'dark' | 'system';
+export type { Shadow } from '@objectstack/spec/ui';
 
 /**
- * Complete Theme Definition
+ * Responsive Breakpoints Configuration
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface ThemeDefinition {
-  /**
-   * Theme name/identifier
-   */
-  name: string;
+export type { Breakpoints } from '@objectstack/spec/ui';
 
-  /**
-   * Theme display label
-   */
-  label?: string;
+/**
+ * Animation Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { Animation } from '@objectstack/spec/ui';
 
-  /**
-   * Light mode color palette
-   */
-  light?: ColorPalette;
+/**
+ * Z-Index Layer Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { ZIndex } from '@objectstack/spec/ui';
 
-  /**
-   * Dark mode color palette
-   */
-  dark?: ColorPalette;
+/**
+ * Theme Mode
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { ThemeMode } from '@objectstack/spec/ui';
+
+// Import spec types for local use in interfaces below
+import type {
+  ColorPalette,
+  Typography,
+  Spacing,
+  BorderRadius,
+  Shadow,
+  Breakpoints,
+  Animation,
+  ZIndex,
+  ThemeMode,
+} from '@objectstack/spec/ui';
 
-  /**
-   * Typography configuration
-   */
-  typography?: Typography;
+/**
+ * Logo / Branding Assets
+ * ObjectUI-specific convenience type matching the inline logo object
+ * in @objectstack/spec ThemeSchema.
+ */
+export interface ThemeLogo {
+  /** Logo URL for light mode */
+  light?: string;
+  /** Logo URL for dark mode */
+  dark?: string;
+  /** Favicon URL */
+  favicon?: string;
+}
 
-  /**
-   * Spacing scale configuration
-   */
-  spacing?: SpacingScale;
-
-  /**
-   * Border radius configuration
-   */
-  radius?: BorderRadius;
-
-  /**
-   * Custom CSS variables
-   */
-  cssVariables?: Record<string, string>;
-
-  /**
-   * Tailwind configuration overrides
-   */
-  tailwind?: Record<string, any>;
+/**
+ * Complete Theme Definition
+ * Compatible with @objectstack/spec Theme (input shape).
+ *
+ * Note: The spec's z.infer<Theme> has `mode` required (via ZodDefault).
+ * ObjectUI uses the input shape where `mode` is optional (defaults to 'auto').
+ *
+ * This is the canonical JSON shape for a theme.
+ * It can be serialized, stored, and applied at runtime via ThemeProvider.
+ */
+export interface Theme {
+  /** Theme identifier (required) */
+  name: string;
+  /** Display label (required) */
+  label: string;
+  /** Human-readable description */
+  description?: string;
+  /** Theme mode: light, dark, or auto (default: 'auto') */
+  mode?: ThemeMode;
+  /** Semantic color palette (primary is required) */
+  colors: ColorPalette;
+  /** Typography design tokens */
+  typography?: Typography;
+  /** Spacing scale */
+  spacing?: Spacing;
+  /** Border radius scale */
+  borderRadius?: BorderRadius;
+  /** Shadow scale */
+  shadows?: Shadow;
+  /** Responsive breakpoint definitions */
+  breakpoints?: Breakpoints;
+  /** Animation duration and timing */
+  animation?: Animation;
+  /** Z-index layering system */
+  zIndex?: ZIndex;
+  /** Arbitrary CSS custom properties */
+  customVars?: Record<string, string>;
+  /** Logo/branding assets */
+  logo?: ThemeLogo;
+  /** Extend another theme by name */
+  extends?: string;
 }
 
+// ============================================================================
+// ObjectUI Component Schemas (UI rendering)
+// ============================================================================
+
 /**
- * Theme Schema - Theme configuration and switching
+ * Theme Component Schema
+ *
+ * Used by SchemaRenderer to render a theme manager component.
  */
 export interface ThemeSchema extends BaseSchema {
   type: 'theme';
 
-  /**
-   * Current theme mode
-   */
+  /** Current theme mode */
   mode?: ThemeMode;
 
-  /**
-   * Available themes
-   */
-  themes?: ThemeDefinition[];
+  /** Available themes */
+  themes?: Theme[];
 
-  /**
-   * Active theme name
-   */
+  /** Active theme name */
   activeTheme?: string;
 
-  /**
-   * Allow user theme switching
-   */
+  /** Allow user theme switching */
   allowSwitching?: boolean;
 
-  /**
-   * Persist theme preference
-   */
+  /** Persist theme preference to storage */
   persistPreference?: boolean;
 
-  /**
-   * Storage key for persisting theme
-   */
+  /** Storage key for persisting theme */
   storageKey?: string;
 }
 
@@ -292,29 +185,19 @@ export interface ThemeSchema extends BaseSchema {
 export interface ThemeSwitcherSchema extends BaseSchema {
   type: 'theme-switcher';
 
-  /**
-   * Switcher variant
-   */
+  /** Switcher variant */
   variant?: 'dropdown' | 'toggle' | 'buttons';
 
-  /**
-   * Show mode selector (light/dark)
-   */
+  /** Show mode selector (light/dark) */
   showMode?: boolean;
 
-  /**
-   * Show theme selector
-   */
+  /** Show theme selector */
   showThemes?: boolean;
 
-  /**
-   * Icon for light mode
-   */
+  /** Icon for light mode */
   lightIcon?: string;
 
-  /**
-   * Icon for dark mode
-   */
+  /** Icon for dark mode */
   darkIcon?: string;
 }
 
@@ -324,28 +207,32 @@ export interface ThemeSwitcherSchema extends BaseSchema {
 export interface ThemePreviewSchema extends BaseSchema {
   type: 'theme-preview';
 
-  /**
-   * Theme to preview
-   */
-  theme?: ThemeDefinition;
+  /** Theme to preview */
+  theme?: Theme;
 
-  /**
-   * Preview mode
-   */
+  /** Preview mode */
   mode?: ThemeMode;
 
-  /**
-   * Show color palette
-   */
+  /** Show color palette */
   showColors?: boolean;
 
-  /**
-   * Show typography samples
-   */
+  /** Show typography samples */
   showTypography?: boolean;
 
-  /**
-   * Show component samples
-   */
+  /** Show component samples */
   showComponents?: boolean;
 }
+
+// ============================================================================
+// Legacy Aliases (Backward Compatibility)
+// ============================================================================
+
+/**
+ * @deprecated Use `Theme` instead. Kept for backward compatibility.
+ */
+export type ThemeDefinition = Theme;
+
+/**
+ * @deprecated Use `Spacing` instead. Kept for backward compatibility.
+ */
+export type SpacingScale = Spacing;