@molecule/app-theme 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,474 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-09-13T23:39:57.945Z
+-->
+
+# @molecule/app-theme
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Theme interface and utilities for molecule.dev.
+
+Framework-agnostic theme contract — a {@link Theme} (colors, spacing,
+typography, radii, shadows, z-index) plus a {@link ThemeProvider} bond for
+reading/switching themes, dark/light toggling, and change subscriptions.
+Bond a provider (e.g. `@molecule/app-theme-css-variables`, which applies the
+palette as CSS variables) at startup; {@link lightTheme}/{@link darkTheme}
+are the base defaults.
+
+## Quick Start
+
+```typescript
+import { getProvider } from '@molecule/app-theme'
+
+const theme = getProvider() // null until a bond is wired at startup
+theme?.toggleMode() // light <-> dark
+const unsubscribe = theme?.subscribe((t) => applyBranding(t))
+```
+
+## Type
+
+`core`
+
+## Installation
+
+```bash
+npm install @molecule/app-theme @molecule/app-bond
+```
+
+## API
+
+### Interfaces
+
+#### `Theme`
+
+Complete theme definition.
+
+```typescript
+interface Theme {
+  name: string
+  mode: 'light' | 'dark'
+  colors: ThemeColors
+  breakpoints: ThemeBreakpoints
+  spacing: ThemeSpacing
+  typography: ThemeTypography
+  borderRadius: ThemeBorderRadius
+  shadows: ThemeShadows
+  transitions: ThemeTransitions
+  zIndex: ThemeZIndex
+}
+```
+
+#### `ThemeBorderRadius`
+
+Border radius scale.
+
+```typescript
+interface ThemeBorderRadius {
+  none: string
+  sm: string
+  md: string
+  lg: string
+  xl: string
+  full: string
+}
+```
+
+#### `ThemeBreakpoints`
+
+Responsive viewport breakpoints from mobileS (320px) to desktop (2560px).
+
+```typescript
+interface ThemeBreakpoints {
+  mobileS: string // 320px
+  mobileM: string // 375px
+  mobileL: string // 425px
+  tablet: string // 768px
+  laptop: string // 1024px
+  laptopL: string // 1440px
+  desktop: string // 2560px
+}
+```
+
+#### `ThemeColors`
+
+Color palette definition.
+
+```typescript
+interface ThemeColors {
+  // Base colors
+  background: string
+  backgroundSecondary: string
+  backgroundTertiary: string
+  surface: string
+  surfaceSecondary: string
+  inputBackground: string
+
+  // Text colors
+  text: string
+  textSecondary: string
+  textTertiary: string
+  textInverse: string
+
+  // Brand colors
+  primary: string
+  primaryLight: string
+  primaryDark: string
+  secondary: string
+  secondaryLight: string
+  secondaryDark: string
+
+  // Semantic colors
+  success: string
+  successLight: string
+  warning: string
+  warningLight: string
+  error: string
+  errorLight: string
+  info: string
+  infoLight: string
+
+  // Border colors
+  border: string
+  borderSecondary: string
+  borderFocus: string
+
+  // Other
+  overlay: string
+  shadow: string
+}
+```
+
+#### `ThemeProvider`
+
+Manages theme state including the active theme, mode toggling,
+and change subscriptions.
+
+```typescript
+interface ThemeProvider {
+  /**
+   * Returns the currently active theme.
+   */
+  getTheme(): Theme
+
+  /**
+   * Sets the active theme by reference or by name.
+   *
+   * @param theme - A `Theme` object or a theme name string to activate.
+   */
+  setTheme(theme: Theme | string): void
+
+  /**
+   * Toggles between light and dark mode for the active theme.
+   */
+  toggleMode(): void
+
+  /**
+   * Subscribes to theme changes. The callback fires whenever
+   * `setTheme()` or `toggleMode()` is called.
+   *
+   * @param callback - Invoked with the new theme after each change.
+   * @returns An unsubscribe function.
+   */
+  subscribe(callback: (theme: Theme) => void): () => void
+
+  /**
+   * Returns all registered themes. Optional — not all providers
+   * support multiple themes.
+   */
+  getThemes?(): Theme[]
+
+  /**
+   * Returns the theme a render WITHOUT a browser produces — a server or
+   * build-time render, which has no storage and no `prefers-color-scheme`
+   * to read. A hydrating client renders this theme first, so its markup
+   * matches what the server sent, and switches to `getTheme()` right
+   * after. Optional — a provider whose theme cannot differ between the two
+   * need not implement it.
+   */
+  getServerTheme?(): Theme
+}
+```
+
+#### `ThemeShadows`
+
+Box-shadow scale from none to xl for elevation levels.
+
+```typescript
+interface ThemeShadows {
+  none: string
+  sm: string
+  md: string
+  lg: string
+  xl: string
+}
+```
+
+#### `ThemeSpacing`
+
+Theme spacing scale mapping size tokens (xs–3xl) to CSS values (e.g. '4px', '16px').
+
+```typescript
+interface ThemeSpacing {
+  xs: string // 4px
+  sm: string // 8px
+  md: string // 16px
+  lg: string // 24px
+  xl: string // 32px
+  xxl: string // 48px
+  xxxl: string // 64px
+}
+```
+
+#### `ThemeTransitions`
+
+CSS transition duration presets (fast, normal, slow).
+
+```typescript
+interface ThemeTransitions {
+  fast: string
+  normal: string
+  slow: string
+}
+```
+
+#### `ThemeTypography`
+
+Typography scale (font families, sizes, weights, and line heights).
+
+```typescript
+interface ThemeTypography {
+  fontFamily: {
+    sans: string
+    serif: string
+    mono: string
+  }
+  fontSize: {
+    xs: string // 12px
+    sm: string // 14px
+    base: string // 16px
+    lg: string // 18px
+    xl: string // 20px
+    '2xl': string // 24px
+    '3xl': string // 30px
+    '4xl': string // 36px
+    '5xl': string // 48px
+  }
+  fontWeight: {
+    light: number
+    normal: number
+    medium: number
+    semibold: number
+    bold: number
+  }
+  lineHeight: {
+    tight: number
+    normal: number
+    relaxed: number
+  }
+}
+```
+
+#### `ThemeZIndex`
+
+Theme z-index scale for layering UI elements (dropdowns, modals, toasts, etc.).
+
+```typescript
+interface ThemeZIndex {
+  hide: number
+  base: number
+  dropdown: number
+  sticky: number
+  fixed: number
+  modal: number
+  popover: number
+  tooltip: number
+  toast: number
+}
+```
+
+### Functions
+
+#### `createDarkTheme(overrides)`
+
+Creates a dark theme by merging default dark-mode tokens with
+optional overrides for colors, spacing, typography, etc.
+
+```typescript
+function createDarkTheme(overrides?: Partial<Theme>): Theme
+```
+
+- `overrides` — Partial theme tokens to merge over the defaults.
+
+**Returns:** A complete `Theme` object with `mode: 'dark'`.
+
+#### `createLightTheme(overrides)`
+
+Creates a light theme by merging default light-mode tokens with
+optional overrides for colors, spacing, typography, etc.
+
+```typescript
+function createLightTheme(overrides?: Partial<Theme>): Theme
+```
+
+- `overrides` — Partial theme tokens to merge over the defaults.
+
+**Returns:** A complete `Theme` object with `mode: 'light'`.
+
+#### `getProvider()`
+
+Retrieves the bonded theme provider, or `null` if none is configured.
+
+```typescript
+function getProvider(): ThemeProvider | null
+```
+
+**Returns:** The bonded theme provider, or `null`.
+
+#### `hasProvider()`
+
+Checks whether a theme provider is currently bonded.
+
+```typescript
+function hasProvider(): boolean
+```
+
+**Returns:** `true` if a theme provider is bonded.
+
+#### `setProvider(provider)`
+
+Registers a theme provider as the active singleton.
+
+```typescript
+function setProvider(provider: ThemeProvider): void
+```
+
+- `provider` — The theme provider implementation to bond.
+
+### Constants
+
+#### `darkColors`
+
+Default dark theme colors.
+
+```typescript
+const darkColors: ThemeColors
+```
+
+#### `darkTheme`
+
+Default dark theme.
+
+```typescript
+const darkTheme: Theme
+```
+
+#### `defaultBorderRadius`
+
+Default border radius.
+
+```typescript
+const defaultBorderRadius: ThemeBorderRadius
+```
+
+#### `defaultBreakpoints`
+
+Default responsive breakpoints (320px mobileS → 2560px desktop).
+
+```typescript
+const defaultBreakpoints: ThemeBreakpoints
+```
+
+#### `defaultShadows`
+
+Default box-shadow scale (none → xl, rgba-based).
+
+```typescript
+const defaultShadows: ThemeShadows
+```
+
+#### `defaultSpacing`
+
+Default spacing scale (4px xs → 64px xxxl).
+
+```typescript
+const defaultSpacing: ThemeSpacing
+```
+
+#### `defaultTransitions`
+
+Default CSS transition durations (150ms fast, 250ms normal, 350ms slow).
+
+```typescript
+const defaultTransitions: ThemeTransitions
+```
+
+#### `defaultTypography`
+
+Default typography scale (system font stacks, rem-based sizes, weight/line-height presets).
+
+```typescript
+const defaultTypography: ThemeTypography
+```
+
+#### `defaultZIndex`
+
+Default z-index scale.
+
+```typescript
+const defaultZIndex: ThemeZIndex
+```
+
+#### `lightColors`
+
+Default light theme colors.
+
+```typescript
+const lightColors: ThemeColors
+```
+
+#### `lightTheme`
+
+Default light theme.
+
+```typescript
+const lightTheme: Theme
+```
+
+## Available Providers
+
+| Provider      | Package                                          |
+| ------------- | ------------------------------------------------ |
+| CSS Variables | `@molecule/app-theme-css-variables`              |
+| Liquid Glass  | `@molecule/app-theme-css-variables-liquid-glass` |
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-bond` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/app-bond`
+
+- **Recoloring: find the REAL source of truth first.** Apps scaffolded from a
+  template ship a per-app stylesheet (e.g. `app/src/theme.css`) that
+  hardcodes the `--color-*` variables and loads AFTER the bond — its values
+  win, and editing this package's `Theme` objects (or the bond's palette) has
+  NO visible effect there. Precedence: per-app theme stylesheet > theme
+  bond > base defaults. Recolor by editing whichever file actually defines
+  the variables; the bond's `Theme` palette applies only when no per-app
+  stylesheet defines colors.
+- Read theme values through the provider or the CSS variables it emits —
+  never hardcode hex values in components; surfaces and status colors come
+  from the theme so light AND dark both work.
+- {@link getProvider} returns `null` when nothing is bonded — theme switching
+  is optional; guard rather than throw.

package/dist/provider.d.ts

@@ -41,6 +41,15 @@ export interface ThemeProvider {
      * support multiple themes.
      */
     getThemes?(): Theme[];
+    /**
+     * Returns the theme a render WITHOUT a browser produces — a server or
+     * build-time render, which has no storage and no `prefers-color-scheme`
+     * to read. A hydrating client renders this theme first, so its markup
+     * matches what the server sent, and switches to `getTheme()` right
+     * after. Optional — a provider whose theme cannot differ between the two
+     * need not implement it.
+     */
+    getServerTheme?(): Theme;
 }
 /**
  * Registers a theme provider as the active singleton.

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAA;IAEjB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAA;IAErC;;OAEG;IACH,UAAU,IAAI,IAAI,CAAA;IAElB;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEvD;;;OAGG;IACH,SAAS,CAAC,IAAI,KAAK,EAAE,CAAA;CACtB;AAID;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,aAAa,KAAG,IAErD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,aAAa,GAAG,IAAiD,CAAA;AAEhG;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAA8B,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAA;IAEjB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAA;IAErC;;OAEG;IACH,UAAU,IAAI,IAAI,CAAA;IAElB;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEvD;;;OAGG;IACH,SAAS,CAAC,IAAI,KAAK,EAAE,CAAA;IAErB;;;;;;;OAOG;IACH,cAAc,CAAC,IAAI,KAAK,CAAA;CACzB;AAID;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,aAAa,KAAG,IAErD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,aAAa,GAAG,IAAiD,CAAA;AAEhG;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAA8B,CAAA"}

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AA0CnE,MAAM,SAAS,GAAG,OAAO,CAAA;AAEzB;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAuB,EAAQ,EAAE;IAC3D,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAyB,EAAE,CAAC,OAAO,CAAgB,SAAS,CAAC,IAAI,IAAI,CAAA;AAEhG;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAoDnE,MAAM,SAAS,GAAG,OAAO,CAAA;AAEzB;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAuB,EAAQ,EAAE;IAC3D,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAyB,EAAE,CAAC,OAAO,CAAgB,SAAS,CAAC,IAAI,IAAI,CAAA;AAEhG;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-theme",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Theme interface and utilities for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -27,13 +28,13 @@
   ],
   "license": "Apache-2.0",
   "peerDependencies": {
-    "@molecule/app-bond": "^1.0.0"
+    "@molecule/app-bond": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/app-bond": "1.0.0",
+    "@molecule/app-bond": "1.0.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "repository": {
     "type": "git",