lecodes-cli 0.11.0 → 0.13.0

package/runtime/sdk/ui/UINode.ts

@@ -362,6 +362,43 @@ export type ClassValue = boolean | (() => boolean)
  *  single-key writes are runtime-coerced with `!!`. */
 export type Classes<R> = ((classes: Record<string, ClassValue>) => R) & { [key: string]: any }
 
+/** Members every UI element shares — element interfaces extend this so docs and types live in one
+ *  place. `S` is the element's style object; `A` is the subset `animateTo` accepts (defaults to `S`). */
+export interface UIElementBase<S extends object, A extends object = S> {
+  // NB: no `name` member here. Declaring it would give every element a property in common with
+  // the style types (BaseStyle.name), letting TS's weak-type check match a NODE against a legacy
+  // style-first overload — `UIPager(UIText("x"))` must stay a type error (tests/ui-types.test.ts).
+  /** Style: `.style({...})` merges (chainable); `el.style.key = v` writes one prop, a `() => v`
+   *  value binds it to signals — see {@link Style}. */
+  style: Style<this, S>
+  /** 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). */
+  animateFrom: AnimateStyle<this, A>
+  /** Fires after every layout pass with the parent-relative box. */
+  onLayout(onLayout: OnLayoutCallback): this
+  /** Absolute rect in device space, read live (includes scroll); `null` before mount. */
+  getBoundingClientRect(): BoundingClientRect | null
+  /** 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>
+}
+
+/** {@link UIElementBase} plus the child-management surface every container shares. */
+export interface UIContainerBase<S extends object, A extends object = S> extends UIElementBase<S, A> {
+  /** Append children. */
+  append(...nodes: UINodeChild[]): this
+  /** Insert children at `index`. */
+  insert(index: number, ...nodes: UINodeChild[]): this
+  /** Remove (unmount) the given children. */
+  remove(...nodes: UINodeChild[]): this
+  /** Replace all children — an array, or a function for reactive children. */
+  setContent(nodes: UINodeChild[] | ChildrenFn): this
+  /** The children array — mutate via `append`/`insert`/`remove`/`setContent`. */
+  readonly children: UINodeChild[]
+}
+
 /** Orientation state blocks — override props applied only in landscape / portrait (like a
  *  `$`-class, keyed by device orientation instead of `el.class`). Same full-`T` rule as class
  *  blocks. */

package/runtime/sdk/ui/UIPager.ts

@@ -1,4 +1,4 @@
-import { ContainerElement, type AnimateStyle, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type UINodeChild } from "./UINode"
+import { ContainerElement, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode"
 import { disposeBinding } from "../core/signals"
 import type { UIScreen } from "./UIScreen"
 
@@ -41,11 +41,8 @@ const _activeStack: PagerElement[] = []
  *
  * To open something over *everything* (above bars, above the pager), use `Router.push` instead.
  */
-export interface UIPager {
+export interface UIPager extends UIElementBase<UIPagerStyle, DrawableStyle & BaseStyle> {
   readonly type: "pager",
-  style: Style<this, UIPagerStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>,
 
   /** Replace the pager's tabs — one screen per tab, in order. Every tab becomes a fresh
    *  one-screen stack (pushed screens are dropped) and the selection is clamped into range;
@@ -80,14 +77,6 @@ export interface UIPager {
   readonly depth: number,
   /** Fires when the current tab's depth changes — push, pop, replace, or a back-swipe. */
   onChange(callback: (depth: number) => void): this,
-
-  onLayout(onLayout: OnLayoutCallback): this,
-  getBoundingClientRect(): BoundingClientRect | null,
-
-  /** 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>,
 }
 
 export class PagerElement extends ContainerElement<"pager"> {

package/runtime/sdk/ui/UIScreen.ts

@@ -1,6 +1,6 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { ContainerElement, buildUI, type AnimateStyle, type BaseStyle, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, type UIChildArg, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { ContainerElement, buildUI, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, } from "./UINode"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle
 
@@ -8,24 +8,15 @@ export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
  *  fixed chrome (header, tab bar) plus, when the content overflows, one `UIScrollable` body child
  *  (`flexGrow: 1`). Scroll events and pull-to-refresh live on the scroll containers
  *  (`UIScrollable`, `UIVirtualizedList`). */
-export interface UIScreen {
+export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle & BaseStyle> {
   readonly type: "screen",
-  style: Style<this, UIScreenStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   /** Show this screen as the current destination (replaces whatever is visible — a screen, a
    *  scene, a native view — suspending an active Router until `Router.restore()`). */
   open(options?: PresentOptions): void,
+  /** Dismiss if this screen is the visible destination. */
   close(): void
 
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  readonly children: UINodeChild[],
-
   /** Hardware/system back while this screen is current. */
   onBackPressed(callback: () => void): this
 
@@ -45,14 +36,7 @@ export interface UIScreen {
   /** Free a `keepAlive()` screen's retained tree now. No-op unless it's currently detached-and-kept. */
   dispose(): this
 
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** 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>
-
+  /** Touch began on the screen; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
 }
 

package/runtime/sdk/ui/UIScrollable.ts

@@ -1,5 +1,5 @@
 import type { UIContainerStyle } from "./UIContainer"
-import { type Classes, type Style, type AnimateStyle, type UIChildArg, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type Color, ContainerElement, buildUI } from "./UINode"
+import { type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type Color, ContainerElement, buildUI } from "./UINode"
 
 export type ScrollStyle = {
   showScrollbar?: boolean,
@@ -21,24 +21,8 @@ export type UIScrollableStyle = UIContainerStyle & ScrollStyle & { scrollDirecti
 
 /** A scroll container — vertical by default, `scrollDirection: "horizontal"` for carousels/chip
  *  rows. The scrolling body of a screen (screens themselves never scroll). */
-export interface UIScrollable {
+export interface UIScrollable extends UIContainerBase<UIScrollableStyle> {
   readonly type: "scrollable",
-  style: Style<this, UIScrollableStyle>,
-  animateTo: AnimateStyle<this, UIScrollableStyle>,
-  animateFrom: AnimateStyle<this, UIScrollableStyle>,
-  
-  append(...nodes: UINodeChild[]): UIScrollable
-  insert(index: number, ...nodes: UINodeChild[]): UIScrollable
-  remove(...nodes: UINodeChild[]): UIScrollable
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** 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>
 
   /** Scroll position changed (px from the start edge). */
   onScroll(callback: (scrollPosition: number) => void): UIScrollable,
@@ -49,8 +33,6 @@ export interface UIScrollable {
   /** Pull-to-refresh: the spinner stays until the returned promise settles. Attach BEFORE the
    *  node mounts (hosts read it at creation). Vertical only; native hosts — no-op on web. */
   onRefresh(callback: () => void | Promise<void>): UIScrollable
-
-  readonly children: UINodeChild[]
 }
 
 class ScrollableElement extends ContainerElement<"scrollable"> {

package/runtime/sdk/ui/UISpacer.ts

@@ -1,16 +1,10 @@
-import { Element, type ElementStyle, type Classes, type Style, type StyleFn } from "./UINode"
+import { Element, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UISpacerStyle = ElementStyle
 
 /** A flexible gap — `flexGrow: 1` by default, pushes its siblings apart. */
-export interface UISpacer {
+export interface UISpacer extends UIElementBase<UISpacerStyle> {
   readonly type: "spacer",
-  style: Style<this, UISpacerStyle>,
-
-  /** 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>
 }
 /** Create a flexible gap (`flexGrow: 1`) — e.g. between a header's title and its actions. */
 export function UISpacer(): UISpacer

package/runtime/sdk/ui/UIText.ts

@@ -1,24 +1,13 @@
 import { createBinding } from "../core/signals"
-import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type TextStyle } from "./UINode"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type TextStyle, type UIElementBase } from "./UINode"
 
 export type UITextStyle = ElementStyle & TextStyle & DrawableStyle
 
 /** A text label. */
-export interface UIText {
+export interface UIText extends UIElementBase<UITextStyle, DrawableStyle & BaseStyle & TextStyle> {
   readonly type: "text",
   /** The displayed string — writable at any time. */
   text: string,
-  style: Style<this, UITextStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** 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>
 }
 
 export class TextElement extends Element<"text"> {

package/runtime/sdk/ui/UIVideo.ts

@@ -1,34 +1,27 @@
 import type { VideoPlayer } from "../runtime/media"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { Element, type AnimateStyle, type AppearStyle, type BaseStyle, type DisappearStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type StyleFn } from "./UINode"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UIVideoStyle = ElementStyle & DrawableStyle & { objectFit?: "cover" | "contain" | "fill" }
 
 /** A video surface showing a `VideoPlayer`'s output — embeddable in a screen AND
  *  fullscreen-presentable (`open()`), with seamless promotion between the two. */
-export interface UIVideo {
+export interface UIVideo extends UIElementBase<UIVideoStyle, DrawableStyle & BaseStyle> {
   readonly type: "video",
   /** The player driving this surface (playback control lives on it). */
   player: VideoPlayer
-  style: Style<this, UIVideoStyle>
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   /** Show fullscreen as the current destination. Promotion: if this video is mounted in a screen,
    *  the SAME native player moves fullscreen — playback uninterrupted; a pop moves it back. */
   open(options?: PresentOptions): void
+  /** Dismiss if this is the visible destination. */
   close(): void
+  /** Became the visible destination. */
   onOpen(callback: () => void): this
+  /** Stopped being the visible destination. */
   onClose(callback: () => void): this
+  /** Hardware/system back while current. */
   onBackPressed(callback: () => void): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** 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>
 }
 
 class VideoElement extends Element<"video"> implements Presentable {

package/runtime/sdk/ui/UIVirtualizedList.ts

@@ -1,4 +1,4 @@
-import { Element, type Color, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, type UINodeChild } from "./UINode"
+import { Element, type Color, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode"
 
 export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & {
   /** Tint of the native pull-to-refresh spinner (pairs with `onRefresh`). */
@@ -27,27 +27,34 @@ export interface VListConfig<T> {
 
 /** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
  *  and chats. Items are keyed; feed it via `setData`/`append`/`prepend`. */
-export interface UIVirtualizedList<T = unknown> {
+export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
     readonly type: "vlist"
-    style: Style<this, UIVirtualizedListStyle>
 
     /** Replace the data wholesale — vanished keys are unmounted by the host's window sync. */
     setData(items: T[]): this
+    /** Append items to the end (auto-scrolls when `inverted` and resting at the bottom). */
     append(...items: T[]): this
     /** Insert at the start WITHOUT a scroll jump (the host compensates the offset). */
     prepend(...items: T[]): this
     /** Update items with the same keys: mounted ones re-render; the cached height persists until
      *  re-measured. */
     update(...items: T[]): this
+    /** Remove items by key. */
     removeByKey(...keys: string[]): this
 
+    /** Number of data items (mounted or not). */
     readonly itemCount: number
+    /** The data item under `key`, if any. */
     getItem(key: string): T | undefined
 
+    /** Scroll to `offset` px. */
     scrollTo(offset: number, animated?: boolean): void
+    /** Scroll to the item with `key`. */
     scrollToKey(key: string, animated?: boolean): void
+    /** Scroll to the end of the content. */
     scrollToEnd(animated?: boolean): void
 
+    /** Scroll position changed (px from the start edge). */
     onScroll(callback: (scrollPosition: number) => void): this
     /** Pull-to-refresh: the spinner stays until the returned promise settles. Attach BEFORE the
      *  node mounts (hosts read it at creation). Native hosts only — no-op on web. */
@@ -57,13 +64,6 @@ export interface UIVirtualizedList<T = unknown> {
     onEndReached(thresholdPx: number, callback: () => void): this
     /** Same, for the top edge — chat history loading. */
     onStartReached(thresholdPx: number, callback: () => void): this
-    onLayout(onLayout: OnLayoutCallback): this
-    getBoundingClientRect(): BoundingClientRect | null
-
-    /** 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>
 }
 
 export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedList<T> {

package/runtime/sdk/ui/UIWidget.ts

@@ -1,6 +1,6 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _descOf, _navSupported, Presentable } from "./presentable"
-import { ContainerElement, buildUI, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type PositionStyle, type Classes, type Style, type UIChildArg, 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 & {
@@ -13,11 +13,8 @@ export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
 /** 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 {
+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
@@ -42,25 +39,12 @@ export interface UIWidget {
   /** 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>
 }