lecodes-sdk 2.0.4 → 2.0.6

package/dist/types/ui/UINode.d.ts

@@ -1,7 +1,9 @@
 import type { FetchResponse } from "../runtime/fetch";
+import type { SvgSourceValue } from "../runtime/misc";
 import type { ColorInput } from "../core/color";
 import type { Animation } from "../animate/tween/Animation";
 import { type TweenMeta } from "../animate/tween/spec";
+import { type ThemeRoles } from "./theme";
 import { type TreeElement } from "./tree";
 export interface UINode {
     readonly type: string;
@@ -18,7 +20,7 @@ export type UINodeChild = UINode | null | undefined | false;
  *  needs no spread. */
 export type UIChildArg = UINodeChild | UINodeChild[];
 /** A color: any CSS color string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"green"`, `"hsl(210 50% 40%)"`),
- *  a theme reference (`"var(--primaryColor)"`), an opaque `0xRRGGBB` number or `[r, g, b(, a)]` in
+ *  a theme reference (`"var(--accent)"`), an opaque `0xRRGGBB` number or `[r, g, b(, a)]` in
  *  0..1; `null` clears. A string is the core's to parse (an unknown one is transparent, as in
  *  CSS); a number or an array that is not a color throws at the write. */
 export type Color = ColorInput | null;
@@ -37,12 +39,13 @@ export type BaseStyle = {
 };
 /** Painted-box props: background, gradient, border, radius. */
 export type DrawableStyle = {
-    backgroundImage?: FetchResponse | File | string | null;
+    backgroundImage?: FetchResponse | File | SvgSourceValue | string | null;
     bgGradient?: string;
     backgroundGradient?: string;
-    bgImage?: FetchResponse | File | string | null;
-    backgroundSize?: "cover" | "contain" | "tile";
-    bgSize?: "cover" | "contain" | "tile";
+    bgImage?: FetchResponse | File | SvgSourceValue | string | null;
+    /** How the image fills the box. "tile": repeated at its own size from the top-left corner. */
+    backgroundSize?: "cover" | "contain" | "fill" | "tile";
+    bgSize?: "cover" | "contain" | "fill" | "tile";
     border?: string | number | null;
     borderWidth?: number;
     borderColor?: Color;
@@ -223,6 +226,16 @@ export interface UIElementBase<S extends object, A extends object = S> {
     name?: string;
     /** Set the semantic name (chainable). */
     named(name: string): this;
+    /** Theme variables for THIS element's subtree (chainable): the same keys as the app-wide
+     *  `theme()`, read by everything under the element — and by the kit components there — before
+     *  the app's table. `null` takes a key out of the scope. Reaches the element's descendants in
+     *  the tree (a pager's pages and a list's items included); a screen pushed over it and a widget
+     *  are roots of their own. Re-calling restyles the live subtree.
+     *  ```ts
+     *  promo.theme({ accent: "#FF3B30" })            // one card in another accent
+     *  sheet.theme({ bg: "#000", text: "#FFF" })     // a dark screen in a light app
+     *  ``` */
+    theme(values: ThemeRoles & Record<string, string | number | null>): this;
     /** Tween to the target style — meta keys `duration`/`delay`/`loop`/…, see {@link AnimateStyle}. */
     animateTo: AnimateStyle<this, A>;
     /** Tween from the given style to the current one (entrance animations). */
@@ -305,6 +318,7 @@ export declare class Element<T extends string> implements TreeElement {
     get name(): string | undefined;
     set name(value: string | undefined);
     named(name: string): this;
+    theme(values: Record<string, string | number | null>): this;
     get style(): any;
     /** Tween to the target style and commit it (unless `commit: false` or looping — a loop is an
      *  effect, not a state change). A prop value may be an array of keyframes; meta keys

package/dist/types/ui/UIScreen.d.ts

@@ -48,6 +48,7 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
     onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this;
 }
 export declare class ScreenElement extends ContainerElement<"screen"> {
+    constructor(type: "screen", style: any, children: any);
     open(options?: PresentOptions): void;
     close(options?: DismissOptions): void;
     protected ol: (() => void)[];

package/dist/types/ui/UITabs.d.ts

@@ -23,8 +23,9 @@ export type UITabDef = {
  * ```
  *
  * In-tab navigation stays the pager's: `UIPager.push(detail)` from any screen (bar stays);
- * `Router.push` opens above the shell (bar covered). Restyle via `theme()` (primaryColor,
- * mutedColor, tabbarBg, …) or the `bar` handle; for a fully custom bar build on `UIPager`.
+ * `Router.push` opens above the shell (bar covered). The bar is colored by the theme's roles
+ * (`accent`, `textMuted`, `surface`, `border`); `tabs.bar.theme({...})` overrides them for this
+ * bar alone, the `bar` handle restyles its box; for a fully custom bar build on `UIPager`.
  */
 export interface UITabs extends UIScreen {
     /** The active tab id. */
@@ -37,7 +38,8 @@ export interface UITabs extends UIScreen {
     badge(id: string, value: number | string | boolean | null): this;
     /** The pager under the bar — in-tab stacks (`push`/`pop`/`depth`). */
     readonly pager: UIPager;
-    /** The bar row (named "tabbar") — for restyling beyond the theme variables. */
+    /** The bar row (named "tabbar") — `bar.theme({ accent, textMuted, surface, border })` for this
+     *  bar's own colors, `bar.style({...})` for its box. */
     readonly bar: UIRowType;
 }
 export declare class TabsElement extends ScreenElement {
@@ -89,8 +91,8 @@ export type TabsHandle<T extends Record<string, TabDef>> = {
  * export default () => mainTabs.screen("home", [ ...content ])
  * ```
  *
- * Restyle through the theme — `theme({ primaryColor, mutedColor, tabbarBg, screenBg })` recolors
- * every bar at once. The built app passes the same keys (plus each tab's root screen) to `UITabs`,
- * which renders the identical bar interactively.
+ * The bar reads the theme's roles (`accent`, `textMuted`, `surface`, `border`), the screen its
+ * `bg` — one `theme({...})` colors every bar at once. The built app passes the same keys (plus
+ * each tab's root screen) to `UITabs`, which renders the identical bar interactively.
  */
 export declare function defineTabs<T extends Record<string, TabDef>>(tabs: T): TabsHandle<T>;

package/dist/types/ui/theme.d.ts

@@ -1,21 +1,56 @@
 import type { Transition } from "./presentable";
 export type ThemeValues = Record<string, string | number | null>;
+/** The keys the SDK itself reads — the ROLES of a theme. An app's own keys sit beside them in the
+ *  same call; kit components (`UITabs`) and the defaults of screens and text read these and nothing
+ *  else, so one palette colors the app and the kit alike. A color is a string, never a number. */
+export type ThemeRoles = {
+    /** The background of every screen. */
+    bg?: string | null;
+    /** A raised surface — cards, bars, sheets. The tab bar's background (without it: `bg`). */
+    surface?: string | null;
+    /** Hairlines and outlines. The tab bar's top line. */
+    border?: string | null;
+    /** Text that names no `color` of its own. */
+    text?: string | null;
+    /** Secondary text and inactive controls. The tab bar's inactive tabs. */
+    textMuted?: string | null;
+    /** The brand / active color. The tab bar's active tab. */
+    accent?: string | null;
+    /** The font of text that names no `fontFamily` of its own. */
+    fontFamily?: string | null;
+};
+/** What only the app-wide `theme()` takes: the comfort knobs (logical px) and the Router's default
+ *  `replace` transition. */
+export type ThemeAppKeys = {
+    "comfort-top"?: number | string | null;
+    "comfort-bottom"?: number | string | null;
+    "comfort-left"?: number | string | null;
+    "comfort-right"?: number | string | null;
+    replaceTransition?: Transition | null;
+};
+/** The `var(--key)` strings of the keys a `theme()` call defined — plain strings, so a helper's
+ *  `(color = colors.accent)` parameter takes any color. */
 export type ThemeAccessors<T> = {
-    readonly [K in keyof T]: K extends string ? `var(--${K})` : never;
+    readonly [K in Exclude<keyof T, "replaceTransition">]: string;
 };
 /** 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 declare const theme: (<T extends Record<string, string | number | Transition | null>>(values: T & { [K in Exclude<keyof T, "replaceTransition">]: string | number | null; }) => ThemeAccessors<Omit<T, "replaceTransition">>) & {
-    /** The app accent color. Kit components will read it via `var(--primaryColor, <fallback>)`. */
-    readonly primaryColor: "var(--primaryColor)";
-    /** Secondary / inactive content color for kit components. */
-    readonly mutedColor: "var(--mutedColor)";
-    /** DEFAULT text color — text without an explicit `color` follows it (hosts source their
-     *  default from the theme; unset = the host default, white on dark screens). Set it once for
-     *  a light theme instead of `color: "black"` on every label. */
-    readonly color: "var(--color)";
-    /** DEFAULT text font — text without an explicit `fontFamily` follows it. */
+ *  dark mode is just a second call), with the roles as static properties (`theme.accent`,
+ *  `theme["comfort-top"]`, …) for code that has no tokens module to import. */
+export declare const theme: (<T extends ThemeRoles & ThemeAppKeys & Record<string, string | number | Transition | null>>(values: T & { [K in Exclude<keyof T, "replaceTransition">]: string | number | null; }) => ThemeAccessors<T>) & {
+    /** The background of every screen. */
+    readonly bg: "var(--bg)";
+    /** A raised surface — cards, bars, sheets. */
+    readonly surface: "var(--surface)";
+    /** Hairlines and outlines. */
+    readonly border: "var(--border)";
+    /** DEFAULT text color — text without a `color` of its own follows it (unset = the host's
+     *  default: white). Set it once for a light theme instead of a color on every label. */
+    readonly text: "var(--text)";
+    /** Secondary text and inactive controls. */
+    readonly textMuted: "var(--textMuted)";
+    /** The brand / active color. */
+    readonly accent: "var(--accent)";
+    /** DEFAULT text font — text without a `fontFamily` of its own follows it. */
     readonly fontFamily: "var(--fontFamily)";
     /** Raw comfort knobs (logical px). The bare `comfort-top` style TOKEN applies the safe-area
      *  formula — these accessors read the knob value itself, for manual composition. */

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.0.4";
+export declare const SDK_VERSION = "2.0.6";
 /** The major of a semver string, or null when it is not one. */
 export declare const sdkMajor: (version: string | null | undefined) => number | null;
 /** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from