lecodes-cli 0.10.3 → 0.11.0

package/runtime/sdk/ui/theme.ts

@@ -1,29 +1,7 @@
-// theme() — app theme variables (docs/ui-theme-plan.md).
-//
-// One global variable table lives in the UI core. Styles reference entries with CSS syntax —
-// `color: "var(--primaryColor)"` — resolved at style-apply time in the core, so re-calling
-// theme() with new values re-styles the LIVE UI (dark mode is just a second call). Two access
-// forms with one rule: bare style tokens (`pt: "comfort-top"`) are keywords that may expand to
-// formulas (max(safe-top, knob)); `var(--comfort-top)` always reads the raw table value (the
-// knob itself).
-//
-// theme(values) MERGES into the table and returns typed accessors whose values ARE the var()
-// strings — define once in a module, import where custom keys need typing:
-//
-//   export const T = theme({ primaryColor: "#0A84FF", cardBg: "#1C1C1E" })
-//   card.style({ bgColor: T.cardBg })            // T.cardBg === "var(--cardBg)"
-//
-// System vars need no import — they're static properties on the callable itself:
-// theme.primaryColor, theme.fontFamily, theme["comfort-top"], …
-//
-// Values: strings pass through (colors, fonts, expressions like "max(safe-top, 24px)");
-// numbers are LENGTHS (px). `null` removes a key (comfort knobs reset to their defaults:
-// 12 vertical, 16 horizontal — the page gutter). Env names (safe-*, vw/vh/vmin/vmax) are
-// host-owned facts, never theme keys — they're skipped with a warning.
-//
-// One key is not a style var: `replaceTransition` — the app-wide default for
-// `Router.replace` (any Transition, name or custom spec; `null` resets to "none"). The
-// router resolves it in the SDK, so it's consumed here and never sent to the host table.
+// theme() — app theme variables (docs/ui-theme-plan.md). One global var table lives in the UI
+// core; `var(--key)` references resolve at style-apply time, so re-calling theme() re-styles the
+// LIVE UI. Bare style tokens (`pt: "comfort-top"`) are keywords that may expand to formulas
+// (max(safe-top, knob)); `var(--comfort-top)` always reads the raw table value.
 
 import type { Transition } from "./presentable"
 
@@ -41,10 +19,20 @@ export type ThemeAccessors<T> = {
 
 const RESERVED = ["safe-top", "safe-bottom", "safe-left", "safe-right", "vw", "vh", "vmin", "vmax"]
 
-/** Merge app theme variables and get typed `var(--key)` accessors back. Strings/numbers are
- *  style values (numbers = px); `null` removes a key. One special key: `replaceTransition` —
- *  the app-wide default transition for `Router.replace` (any transition name or custom spec;
- *  out of the box `"none"`). */
+/**
+ * Merge app theme variables into the live table and get typed `var(--key)` accessors back:
+ *
+ * ```ts
+ * export const T = theme({ primaryColor: "#0A84FF", cardBg: "#1C1C1E" })
+ * card.style({ bgColor: T.cardBg })   // T.cardBg === "var(--cardBg)"
+ * ```
+ *
+ * Strings pass through (colors, fonts, expressions like `"max(safe-top, 24px)"`); numbers are
+ * lengths (px); `null` removes a key (comfort knobs reset to their defaults). Env names
+ * (`safe-*`, `vw`/`vh`/…) are host-owned — skipped with a warning. One special key:
+ * `replaceTransition` — the app-wide default transition for `Router.replace` (consumed SDK-side,
+ * never sent to the host table).
+ */
 const setTheme = <T extends Record<string, string | number | Transition | null>>(
   // Only `replaceTransition` may carry a Transition — every other key is a style value.
   values: T & { [K in Exclude<keyof T, "replaceTransition">]: string | number | null }
@@ -73,6 +61,9 @@ const setTheme = <T extends Record<string, string | number | Transition | null>>
   return accessors as ThemeAccessors<Omit<T, "replaceTransition">>
 }
 
+/** App theme: callable to merge variables (`theme({...})` — re-calling re-styles the live UI, so
+ *  dark mode is just a second call), with the system vars as static properties
+ *  (`theme.primaryColor`, `theme["comfort-top"]`, …). */
 export const theme = Object.assign(setTheme, {
   /** The app accent color. Kit components will read it via `var(--primaryColor, <fallback>)`. */
   primaryColor: "var(--primaryColor)",