lecodes-cli 0.10.4 → 0.12.0

package/runtime/sdk/ui/UIWidget.ts

@@ -1,20 +1,20 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _descOf, _navSupported, Presentable } from "./presentable"
-import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type PositionStyle, type Classes, type Style, type UINodeChild, type ChildrenFn } from "./UINode"
+import { ContainerElement, buildUI, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type PaddingStyle, type PositionStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn } from "./UINode"
 
 
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
-  // A layer behind the widget that intercepts clicks. "transparent" still intercepts;
-  // null removes the layer. A tap on it fires onOverlayTap.
+  /** A layer behind the widget that intercepts clicks — `"transparent"` still intercepts, `null`
+   *  removes the layer. A tap on it fires `onOverlayTap`. */
   overlayColor?: Color | null
 }
 
 
-export interface UIWidget {
+/** A floating overlay — absolutely positioned in device coordinates, mounted above the page as
+ *  its own layout root (never a child of what's underneath). The base of dialogs, toasts,
+ *  mini-players and scene HUDs; `UIModal`/`UIPopover`/`UIBottomSheet` build on it. */
+export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle & BaseStyle & { overlayColor?: Color | null }> {
   readonly type: "widget",
-  style: Style<this, UIWidgetStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle & { overlayColor?: Color | null }>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle & { overlayColor?: Color | null }>
 
   /**
    * Attach this widget to a destination (a `Scene`, a `UIScreen`, …): the widget lives on that
@@ -33,27 +33,18 @@ export interface UIWidget {
    *  widget was attached via `attachTo(owner)`, it mounts on that page's layer instead and is
    *  only visible while the owner is presented. */
   show(): void,
+  /** Unmount the widget. */
   hide(): void,
 
+  /** Mounted right now (`show()` ran, `hide()` hasn't). */
   readonly isShow: boolean,
 
-  append(...nodes: UINodeChild[]): UIWidget
-  insert(index: number, ...nodes: UINodeChild[]): UIWidget
-  remove(...nodes: UINodeChild[]): UIWidget
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-  
-  readonly children: UINodeChild[],
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
+  /** Touch began on the widget; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIWidget>) => void): this,
+  /** Tap on the overlay layer (requires an `overlayColor`). */
   onOverlayTap(callback: () => void): this,
+  /** Hardware/system back while the widget is shown. */
   onBackPressed(callback: () => void): this
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
 }
 
 
@@ -120,20 +111,17 @@ export class WidgetElement extends ContainerElement<"widget"> {
 }
 
 
-export function UIWidget(): UIWidget;
+const makeWidget = (style: any, children: any) => new WidgetElement("widget", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
+export const __UIWidget = (children: UINodeChild[] | ChildrenFn): UIWidget => makeWidget({}, children)
+
+/** Create a widget (same argument forms as `UIColumn`). Position it with absolute-style props
+ *  (`top`/`left`/`bottom`/`right`), then `show()`/`hide()`. */
+export function UIWidget(...children: UIChildArg[]): UIWidget;
 export function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;
-export function UIWidget(style: UIWidgetStyle): UIWidget;
-export function UIWidget(style: UIWidgetStyle, children: UINodeChild[]): UIWidget;
-export function UIWidget(...args: [] | [UINodeChild[] | ChildrenFn | UIWidgetStyle] | [UIWidgetStyle, children: UINodeChild[] | ChildrenFn]): UIWidget {
-  if (args.length === 0) {
-    return new WidgetElement("widget", {}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new WidgetElement("widget", {}, args[0])
-    } else {
-      return new WidgetElement("widget", args[0], [])
-    }
-  } else {
-    return new WidgetElement("widget", args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIWidget(style: UIWidgetStyle, children?: UINodeChild[] | ChildrenFn): UIWidget;
+export function UIWidget(...args: any[]): UIWidget {
+  return buildUI(args, null, makeWidget)
 }

package/runtime/sdk/ui/fonts.ts

@@ -3,6 +3,9 @@ type FontOptions = {
   style?: "normal" | "italic"
 }
 
+/** Register a font face from a URL at runtime under `fontFamily`; resolves once it's ready to
+ *  use in styles. For registry/project fonts prefer the compile-time `font()` macro — this is the
+ *  dynamic escape hatch. */
 export async function registerFont (fontFamily: string, url: string, options: FontOptions = {}): Promise<void> {
   return new Promise<void>((res, rej) => {
     _creatorUI.registerFont(fontFamily, url, options, res, rej)

package/runtime/sdk/ui/router.ts

@@ -11,8 +11,13 @@ type NavigateOptions = {
   transition?: Transition
 }
 
+/** Stack navigation over `Presentable` destinations. `init` once with the home page, then
+ *  `push`/`replace`/`pop`; the back gesture/button pops natively. A direct `page.open()` suspends
+ *  the router until `restore()`. */
 type Router = {
+  /** The top of the router stack (not necessarily what's on screen — see `Presentable.current`). */
   get current(): Presentable
+  /** Mount the router with `homePage` as the stack root — the app's navigation entry point. */
   init(homePage: Presentable, opts?: RouterOptions): void
   /** Push a destination onto the stack — a `UIScreen`, a `Scene`, a `Scene2D`, a `NativeView`,
    *  or a `UIVideo`. The back gesture/button pops it. Destinations with async preparation
@@ -20,11 +25,19 @@ type Router = {
    *  visible until they're ready, and a rejection (permission denied / superseded) leaves the
    *  stack untouched. */
   push(page: Presentable, opts?: NavigateOptions): void | Promise<void>
+  /** Swap the top of the stack for `page` — no back entry to the replaced one. */
   replace(page: Presentable, opts?: NavigateOptions): void | Promise<void>
+  /** Pop the top destination (the programmatic twin of the back gesture); `to` unwinds to a
+   *  stack index in one step. */
   pop(to?: number, opts?: NavigateOptions): void
+  /** Blank the router's page, keeping the stack — `restore()` brings it back. A destination
+   *  opened directly stays visible. */
   hide(): void
+  /** Re-present the stack top after `hide()` or a direct `open()` suspended the router. */
   restore(): void
 
+  /** `"change"` fires on every stack change — pushes, pops, and native back gestures — with the
+   *  new top destination. */
   addEventListener(channel: "change", callback: (page: Presentable) => void): void
   removeEventListener(channel: "change", callback: (page: Presentable) => void): void
 }

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)",