@molecule/app-theme-css-variables-liquid-glass 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,168 @@
+<!--
+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:58.968Z
+-->
+
+# @molecule/app-theme-css-variables-liquid-glass
+
+> **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.
+
+Liquid glass theme preset for molecule.dev.
+
+Provides translucent, frosted-glass-inspired light and dark themes
+designed to pair with backdrop-filter blur effects. Uses the standard
+CSS custom properties provider from `@molecule/app-theme-css-variables`.
+
+## Quick Start
+
+```typescript
+import {
+  createCSSVariablesThemeProvider,
+  lightTheme,
+  darkTheme,
+} from '@molecule/app-theme-css-variables-liquid-glass'
+import { setProvider } from '@molecule/app-theme'
+
+const provider = createCSSVariablesThemeProvider({
+  themes: [lightTheme, darkTheme],
+  defaultTheme: 'dark',
+  persistKey: 'molecule-theme',
+})
+
+setProvider(provider)
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/app-theme-css-variables-liquid-glass @molecule/app-theme @molecule/app-theme-css-variables
+```
+
+## API
+
+### Interfaces
+
+#### `CSSVariablesThemeConfig`
+
+Configuration for css variables theme.
+
+```typescript
+interface CSSVariablesThemeConfig {
+  /** Available themes. */
+  themes: Theme[]
+  /** Name of the default theme to use. */
+  defaultTheme?: string
+  /** CSS variable prefix (default: 'mol'). */
+  prefix?: string
+  /** Whether to auto-apply CSS variables to :root (default: true). */
+  applyToDocument?: boolean
+  /**
+   * Key for persisting the selected theme name across reloads. When `storage`
+   * is omitted, persistence falls back to `window.localStorage` in browser
+   * environments; in SSR / non-browser environments persistence is skipped.
+   */
+  persistKey?: string
+  /**
+   * Storage adapter for persisting theme preference. Optional — when omitted
+   * and `persistKey` is set, `window.localStorage` is used when available.
+   * Provide an adapter for React Native (AsyncStorage wrapper) or custom stores.
+   */
+  storage?: ThemeStorageAdapter
+  /**
+   * With no persisted choice, start on the theme whose `mode` matches the
+   * OS preference (`prefers-color-scheme`) instead of `defaultTheme`.
+   * Browser-only: a render without a window — a server, a build-time
+   * prerender — starts on `defaultTheme`, which `getServerTheme()` reports
+   * so a hydrating client renders the markup it was sent before switching.
+   * Default: false.
+   */
+  systemDefault?: boolean
+}
+```
+
+#### `ThemeStorageAdapter`
+
+Minimal storage adapter for theme persistence. Compatible with
+localStorage, sessionStorage, or any custom implementation
+(e.g., React Native AsyncStorage wrapper, SSR no-op).
+
+```typescript
+interface ThemeStorageAdapter {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+```
+
+### Functions
+
+#### `createCSSVariablesThemeProvider(config)`
+
+Creates a framework-agnostic ThemeProvider that applies theme tokens
+as CSS custom properties on the document root element.
+
+```typescript
+function createCSSVariablesThemeProvider(config: CSSVariablesThemeConfig): ThemeProvider
+```
+
+- `config` — Theme provider configuration (available themes, default theme, CSS variable prefix, persistence).
+
+**Returns:** A ThemeProvider that applies themes as CSS custom properties on the document root.
+
+### Constants
+
+#### `darkTheme`
+
+Liquid glass dark theme.
+
+Translucent dark surfaces over blurred backgrounds.
+
+```typescript
+const darkTheme: Theme
+```
+
+#### `lightTheme`
+
+Liquid glass light theme.
+
+Translucent white surfaces over blurred backgrounds.
+
+```typescript
+const lightTheme: Theme
+```
+
+## Core Interface
+
+Implements `@molecule/app-theme` interface.
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-theme` ^1.0.1
+- `@molecule/app-theme-css-variables` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/app-theme`
+- `@molecule/app-theme-css-variables`
+
+- The frosted BLUR comes from the ClassMap, not from these themes: pair with
+  `@molecule/app-ui-tailwind-glass` (`setClassMap(classMap)`), which layers
+  `backdrop-filter` onto surface components. These themes alone give
+  translucent colors with no blur.
+- Same precedence trap as the base bond: template-based apps ship
+  `app/src/theme.css` whose `--color-*` variables SHADOW these theme colors —
+  when `theme.css` defines colors, wiring this preset changes nothing visible;
+  port the glass palette into `theme.css` instead (see
+  `@molecule/app-theme-css-variables` remarks for the full mechanism).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-theme-css-variables-liquid-glass",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Liquid glass theme preset with translucent surfaces for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -31,18 +32,18 @@
   "devDependencies": {
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
-    "@molecule/app-theme": "^1.0.0",
-    "@molecule/app-theme-css-variables": "^1.0.0"
+    "@molecule/app-theme": "^1.0.1",
+    "@molecule/app-theme-css-variables": "^1.0.1"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/molecule-dev/molecule.git",
     "directory": "packages/app/bonds/theme/css-variables-liquid-glass"
   },
-  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/app/bonds/theme/css-variables-liquid-glass",
+  "homepage": "https://www.molecule.dev/packages/app-theme-css-variables-liquid-glass",
   "bugs": "https://github.com/molecule-dev/molecule/issues",
   "publishConfig": {
     "access": "public"