lecodes-sdk 1.1.0 → 2.0.0

package/src/ui/UIButton.ts

@@ -1,12 +1,13 @@
-import { ClickEvent, TouchStartEvent, LongPressEvent } from "../runtime/touch"
-import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType } from "../runtime/touch"
-import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color, type LayerEasing } from "./UINode"
+import { ClickEvent, TouchStartEvent, LongPressEvent, MouseEnterEvent } from "../runtime/touch"
+import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType, MouseEnterEvent as MouseEnterEventType } from "../runtime/touch"
+import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode"
+import { TREE_FLAG_CLICK, TREE_FLAG_HOVER, TREE_FLAG_INTERACTIVE, TREE_FLAG_LONG_PRESS, tree } from "./tree"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
 
-/** A tappable container — row + centered children by default. Press feedback via the `onPressed`
- *  style block, the `$pressed` class, or `rippleColor`. */
-export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number, delay?: number, easing?: LayerEasing } }, DrawableStyle & BaseStyle> {
+/** A tappable container — row + centered children by default. Press feedback via the `$pressed`
+ *  class block or `rippleColor`. */
+export interface UIButton extends UIContainerBase<UIButtonStyle, DrawableStyle & BaseStyle> {
   readonly type: "button",
 
   /** Fired on a completed tap/click. */
@@ -17,8 +18,14 @@ export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?:
    *  `ev.track(...)` the rest of the gesture (like `onTouchStart`), so a hold can flow straight into
    *  dragging the element. A handled long-press suppresses the click that would follow the release. */
   onLongPress(callback: (ev: LongPressEventType<UIButton>) => void): this,
+  /** Fired when a mouse cursor (no button) enters the button — desktop / web; touch never fires it.
+   *  There is no leave event: `ev.track({ onMove, onEnd, onCancel })` follows the hover to its
+   *  end. The visual state is the reserved `$hovered` class (cascades like `$pressed`). */
+  onMouseEnter(callback: (ev: MouseEnterEventType<UIButton>) => void): this,
   /** Is a finger currently down on the button? */
-  isPressed(): boolean,
+  readonly isPressed: boolean,
+  /** Is a mouse cursor currently over the button (the topmost interactive node under it)? */
+  readonly isHovered: boolean,
 }
 
 
@@ -27,11 +34,19 @@ class ButtonElement extends ContainerElement<"button"> {
   readonly clickListeners: any[] = []
   readonly touchStartListeners: any[] = []
   readonly longPressListeners: any[] = []
+  readonly mouseEnterListeners: any[] = []
+
+  constructor(type: "button", style: any, children: any) {
+    super(type, style, children)
+    this._addFlags(TREE_FLAG_INTERACTIVE)   // a button is a touch target from the start (press feedback)
+  }
 
   onClick (callback: any): this {
     this.clickListeners.push(callback)
+    this._addFlags(TREE_FLAG_CLICK)
     return this
   }
+  /** @internal */
   _emitClick(pointerId: number, clientX: number, clientY: number) {
     const touchEvent = new ClickEvent(clientX, clientY, pointerId)
     touchEvent.target = this
@@ -45,6 +60,7 @@ class ButtonElement extends ContainerElement<"button"> {
     this.touchStartListeners.push(callback)
     return this
   }
+  /** @internal */
   _emitTouchStart(pointerId: number, clientX: number, clientY: number): any {
     const touchEvent = new TouchStartEvent(clientX, clientY, pointerId)
     touchEvent.target = this
@@ -59,12 +75,13 @@ class ButtonElement extends ContainerElement<"button"> {
 
   onLongPress (callback: any): this {
     this.longPressListeners.push(callback)
+    this._addFlags(TREE_FLAG_LONG_PRESS)
     return this
   }
-  // Fired by the host when the finger is held past the long-press threshold. Returns null when
-  // nothing is listening — the host then lets the trailing click through as usual. Otherwise it
-  // returns an object whose presence tells the host to swallow that click, carrying the optional
-  // drag handler a listener registered via `ev.track(...)` for the host to drive the gesture.
+  /** @internal Fired by the host when the finger is held past the long-press threshold. Returns
+   *  null when nothing is listening — the trailing click then goes through as usual. Otherwise the
+   *  wrapper whose presence swallows that click, carrying the optional drag handler a listener
+   *  registered via `ev.track(...)`. */
   _emitLongPress(pointerId: number, clientX: number, clientY: number): any {
     if (this.longPressListeners.length === 0) return null
     const longPressEvent = new LongPressEvent(clientX, clientY, pointerId)
@@ -75,9 +92,32 @@ class ButtonElement extends ContainerElement<"button"> {
     return { track: (longPressEvent as any)._trackHandler ?? null }
   }
 
-  isPressed(): boolean {
-    if (!this._id) return false
-    return _creatorUI.isButtonPressed(this._id)
+  get isPressed(): boolean {
+    if (!this._h.id) return false
+    return tree().isButtonPressed(this._h.id)
+  }
+
+  onMouseEnter (callback: any): this {
+    this.mouseEnterListeners.push(callback)
+    this._addFlags(TREE_FLAG_HOVER)   // the runtime crosses into JS for hover only on flagged nodes
+    return this
+  }
+  /** @internal Fired by the runtime when the cursor enters (TREE_EVENT_HOVER_ENTER). Returns the
+   *  hover track handler a listener registered via `ev.track(...)`, or null — the emitter keeps it
+   *  in its one hover slot and answers whether moves are wanted. */
+  _emitMouseEnter(clientX: number, clientY: number): any {
+    const ev = new MouseEnterEvent(clientX, clientY)
+    ev.target = this
+    for (let callback of this.mouseEnterListeners) {
+      callback(ev)
+      if ((ev as any)._trackHandler) return (ev as any)._trackHandler
+    }
+    return null
+  }
+
+  get isHovered(): boolean {
+    if (!this._h.id) return false
+    return tree().isHovered(this._h.id)
   }
 }
 
@@ -94,8 +134,6 @@ export const __UIButton = (children: UINodeChild[] | ChildrenFn): UIButton => ma
  *  `UIColumn`; attach behavior with `.onClick(...)`. */
 export function UIButton(...children: UIChildArg[]): UIButton;
 export function UIButton(children: UINodeChild[] | ChildrenFn): UIButton;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIButton(style: UIButtonStyle, children?: UINodeChild[] | ChildrenFn): UIButton;
 export function UIButton(...args: any[]): UIButton {
   return buildUI(args, BUTTON_DEFAULTS, makeButton)
 }

package/src/ui/UIContainer.ts

@@ -19,8 +19,6 @@ export const __UIBox = (children: UINodeChild[] | ChildrenFn): UIBox => makeBox(
  *  entries are skipped; a lone function makes the children reactive. */
 export function UIColumn(...children: UIChildArg[]): UIColumn
 export function UIColumn(children: UINodeChild[] | ChildrenFn): UIColumn
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIColumn(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIColumn
 export function UIColumn(...args: any[]): UIColumn {
   return buildUI(args, null, makeColumn)
 }
@@ -35,8 +33,6 @@ const makeRow = (style: any, children: any) => new ContainerElement("row", style
 /** Create a horizontal flex container (same argument forms as `UIColumn`). */
 export function UIRow(...children: UIChildArg[]): UIRow
 export function UIRow(children: UINodeChild[] | ChildrenFn): UIRow
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIRow(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIRow
 export function UIRow(...args: any[]): UIRow {
   return buildUI(args, ROW_DEFAULTS, makeRow)
 }
@@ -53,8 +49,6 @@ const makeBox = (style: any, children: any) => new ContainerElement("box", style
  *  avatars, empty states). Same argument forms as `UIColumn`. */
 export function UIBox(...children: UIChildArg[]): UIBox
 export function UIBox(children: UINodeChild[] | ChildrenFn): UIBox
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIBox(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIBox
 export function UIBox(...args: any[]): UIBox {
   return buildUI(args, BOX_DEFAULTS, makeBox)
 }

package/src/ui/UIImage.ts

@@ -4,11 +4,12 @@ import type { File } from "../runtime/fetch"
 import { Canvas, isCanvas } from "../canvas/Canvas"
 import type { Scene2D } from "../g2/Scene2D"
 import { Element, type Color, type ElementStyle, type UIElementBase } from "./UINode"
+import { wireColor } from "./styleColor"
+import { tree } from "./tree"
 
 export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "cover" | "contain" | "fill", tintColor?: Color }
 
-/** A baked Canvas surface as an image source. The UI backend resolves it to a UI texture — see
- *  docs/canvas-contract.md ("Pending"). */
+/** A baked Canvas surface as an image source. The UI backend resolves it to a UI texture. */
 export type CanvasImageSource = { canvasSurface: number }
 
 /** A live 2D scene as an image source: the host draws the scene into the node's box every frame
@@ -50,48 +51,51 @@ export interface UIImage extends UIElementBase<UIImageStyle> {
 }
 
 class ImageElement extends Element<"image"> {
-  private _src: ResolvedImageSource
-  // Current source sub-rect; undefined until the first setSourceRect. Kept on the node (not
-  // just sent as a command) so a crop set while detached (_id == 0) is reapplied at mount —
-  // the viewer reads it when it creates the element.
-  private _sourceRect?: [number, number, number, number]
+  private _src!: ResolvedImageSource
   constructor(style: any, src: ImageSource) {
     super("image", style)
-    this._src = toSrc(src)
+    this.src = src
   }
 
   get src(): ResolvedImageSource {
     return this._src
   }
   set src(value: ImageSource) {
-    this._src = toSrc(value)
-    if (this._id !== 0) {
-      _creatorUI.updateNode(this._id, "src", this._src)
+    const next = toSrc(value)
+    // A source tint that is not a colour throws BEFORE anything is applied, like a style colour.
+    const n: any = next
+    const tint = n && typeof n === "object" && "svg" in n && n.tintColor != null ? wireColor("tintColor", n.tintColor) as string : null
+    this._src = next
+    if (this._h.id === 0) return
+    // The wire spellings of a source (the host resolves each prefix): a url as is, "id:<bufferId>"
+    // for a fetch / asset buffer, "svg:<source>" (+ "srcTintColor", '#rrggbbaa' or a var(), AFTER
+    // the src: a src write resets the source tint), "canvas:<surfaceId>", "scene2d:<sceneId>".
+    const s: any = this._src
+    if (typeof s === "string") {
+      tree().setString(this._h.id, "src", s)
+    } else if (s && typeof s === "object") {
+      if ("svg" in s) {
+        tree().setString(this._h.id, "src", "svg:" + s.svg)
+        if (tint != null) tree().setString(this._h.id, "srcTintColor", tint)
+      } else if ("canvasSurface" in s) {
+        tree().setString(this._h.id, "src", "canvas:" + s.canvasSurface)
+      } else if ("scene2d" in s) {
+        tree().setString(this._h.id, "src", "scene2d:" + s.scene2d)
+      } else if ("_h" in s) {
+        tree().setString(this._h.id, "src", "id:" + s._h.id)
+      }
     }
   }
 
   setSourceRect(x: number, y: number, w: number, h: number): this {
-    // Stash on the node so a crop set before mount is reapplied when the element is created.
-    this._sourceRect = [x, y, w, h]
-    // Live mutation: fast channel (not _style → no PX_VALUE density scaling: these are texture
-    // pixels, a different coordinate space). On a detached node there is nothing to mutate yet —
-    // the stash above carries it to mount. The viewer decides relayout vs draw-only by comparing
-    // w/h against the rect it has stashed on the element.
-    if (this._id !== 0) {
-      _creatorUI.setSourceRect(this._id, x, y, w, h)
-    }
+    // Texture pixels (not a style → no density scaling); the host decides relayout vs draw-only by
+    // comparing w/h against the rect it has.
+    if (this._h.id !== 0) tree().setString(this._h.id, "sourceRect", `${x} ${y} ${w} ${h}`)
     return this
   }
 }
 
 /** Create an image element from a source (see {@link ImageSource}). */
-export function UIImage(src: ImageSource): UIImage
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIImage(style: UIImageStyle, src: ImageSource): UIImage
-export function UIImage(...args: [ImageSource] | [UIImageStyle, ImageSource]): UIImage {
-  if (args.length === 1) {
-    return new ImageElement({}, args[0])
-  } else {
-    return new ImageElement(args[0], args[1])
-  }
-}
+export function UIImage(src: ImageSource): UIImage {
+  return new ImageElement({}, src)
+}

package/src/ui/UIInput.ts

@@ -1,4 +1,5 @@
-import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase, type LayerEasing } from "./UINode";
+import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
+import { TREE_FLAG_BLUR, TREE_FLAG_CHANGE, TREE_FLAG_FOCUS, TREE_FLAG_SUBMIT, tree } from "./tree"
 
 type InputStyle = {
   placeholder?: string,
@@ -51,15 +52,11 @@ type SubmitStyle = {
 
 /** A single-line text input. Keyboard/picker kind via the `type` style, return-key behavior via
  *  `enterKey` + `onSubmit`; keyboard policy on `keyboardShrink`/`keyboardDismiss`. */
-export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number, delay?: number, easing?: LayerEasing } }, DrawableStyle & BaseStyle> {
+export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle, DrawableStyle & BaseStyle> {
   readonly type: "input",
 
-  /**
-   * The field's text. Writable at any time — set it BEFORE the screen opens to pre-fill a form
-   * (settings, edit-profile); the value is stashed on the node and applied when the host builds
-   * it. Reads return the live text while the screen is open, and the last value you set while it
-   * isn't. The user's typing is not preserved across close/open (use `keepAlive()` for that).
-   */
+  /** The field's text. Writable at any time; reads return the live text (the host owns the field
+   *  while the user types — IME composition, paste, the maxLength clamp, date/time canonicalization). */
   value: string
 
   /** The text changed — fires on every user edit. */
@@ -71,17 +68,17 @@ export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { on
   /** The keyboard's return key was pressed. `value` is the current text. See `enterKey`. */
   onSubmit(callback: (value: string) => void): UIInput
 
-  /** Focus the input (opens the keyboard). No-op before mount. */
+  /** Focus the input (opens the keyboard). */
   focus(): void
   /** Release focus (dismisses the keyboard when this input held it). */
   blur(): void
 }
 
 /** A multi-line text field — see the {@link UITextArea} factory for the auto-grow contract. */
-export interface UITextArea extends UIElementBase<UIInputStyle & { onFocused?: UIInputStyle & { duration?: number, delay?: number, easing?: LayerEasing } }, DrawableStyle & BaseStyle> {
+export interface UITextArea extends UIElementBase<UIInputStyle, DrawableStyle & BaseStyle> {
   readonly type: "textarea",
 
-  /** The field's text — same contract as {@link UIInput.value}: settable before mount to pre-fill. */
+  /** The field's text — same contract as {@link UIInput.value}. */
   value: string
 
   /** The text changed — fires on every user edit. */
@@ -91,7 +88,7 @@ export interface UITextArea extends UIElementBase<UIInputStyle & { onFocused?: U
   /** Lost focus. */
   onBlur(callback: () => void): UITextArea
 
-  /** Focus the text area (opens the keyboard). No-op before mount. */
+  /** Focus the text area (opens the keyboard). */
   focus(): void
   /** Release focus (dismisses the keyboard when this text area held it). */
   blur(): void
@@ -104,25 +101,12 @@ class InputElement<T extends "input" | "textarea"> extends Element<T> {
   readonly bl: Function[] = []
   readonly sl: Function[] = []
 
-  /** @internal The value as last set by CODE. Hosts read it at node creation (after the initial
-   *  style, so a `date` field's canonical parse and `maxLength` are already in place), which is
-   *  what makes a value assigned before mount — a pre-filled settings form — land on the field.
-   *  Same pre-mount stash as UIImage's `_sourceRect`. Typing does NOT sync back here: while
-   *  mounted the HOST owns the text (IME composition, paste, the maxLength clamp, date/time
-   *  canonicalization) and the getter reads it over the bridge. So on a remount the field comes
-   *  back with the last code-set value, not what the user typed — screens that must keep live
-   *  editing state across close/open use `keepAlive()`, the mechanism built for it. */
-  _value = ""
-
-  get value() {
-    // Mounted: the host is authoritative. Unmounted: what code last set (0 => never mounted).
-    return this._id !== 0 ? _creatorUI.getTextValue(this._id) : this._value
+  get value(): string {
+    // The host is authoritative for the field's text (typing never round-trips through JS).
+    return this._h.id !== 0 ? tree().getTextValue(this._h.id) : ""
   }
   set value(value: string) {
-    this._value = value
-    if (this._id !== 0) {
-      _creatorUI.updateNode(this._id, "value", value)
-    }
+    if (this._h.id !== 0) tree().setString(this._h.id, "value", value)
   }
 
   // `phone` is SDK-surface only — hosts (and the web's verbatim `el.type`) keep HTML's `tel` as
@@ -133,31 +117,39 @@ class InputElement<T extends "input" | "textarea"> extends Element<T> {
 
   onChange (callback: (value: string) => void): this {
     this.cl.push(callback)
+    this._addFlags(TREE_FLAG_CHANGE)
     return this
   }
   onFocus(callback: () => void): this {
     this.fl.push(callback)
+    this._addFlags(TREE_FLAG_FOCUS)
     return this
   }
   onBlur(callback: () => void): this {
     this.bl.push(callback)
+    this._addFlags(TREE_FLAG_BLUR)
     return this
   }
   onSubmit(callback: (value: string) => void): this {
     this.sl.push(callback)
+    this._addFlags(TREE_FLAG_SUBMIT)
     return this
   }
-
-  // Focus rides the existing value channel (updateNode "focus") — no new ABI method.
+  /** @internal */
+  _emitChange(value: string): void { for (const cb of this.cl.slice()) cb(value) }
+  /** @internal */
+  _emitFocus(): void { for (const cb of this.fl.slice()) cb() }
+  /** @internal */
+  _emitBlur(): void { for (const cb of this.bl.slice()) cb() }
+  /** @internal */
+  _emitSubmit(value: string): void { for (const cb of this.sl.slice()) cb(value) }
+
+  // Focus rides the content channel ("focus" = "1" / "0") — no dedicated bridge method.
   focus(): void {
-    if (this._id !== 0) {
-      _creatorUI.updateNode(this._id, "focus", true)
-    }
+    if (this._h.id !== 0) tree().setString(this._h.id, "focus", "1")
   }
   blur(): void {
-    if (this._id !== 0) {
-      _creatorUI.updateNode(this._id, "focus", false)
-    }
+    if (this._h.id !== 0) tree().setString(this._h.id, "focus", "0")
   }
 }
 

package/src/ui/UIModal.ts

@@ -63,7 +63,7 @@ export class ModalElement extends WidgetElement {
   constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn) {
     super("widget", { overlayColor: "rgba(0, 0, 0, 0.5)", ...style }, children)
     this.onOverlayTap(() => { if (this._dismissible) this.hide() })
-    this.onBackPressed(() => { if (this._dismissible) this.hide() })
+    this.onBack(() => { if (this._dismissible) this.hide() })
   }
 
   // The full animate argument: hidden pose + duration, plus the scrim fade — only when the
@@ -132,8 +132,6 @@ const makeModal = (style: any, children: any) => new ModalElement(style, childre
  *  `show()`/`hide()`. Same argument forms as `UIColumn`. */
 export function UIModal(...children: UIChildArg[]): UIModal;
 export function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIModal(style: UIModalStyle, children?: UINodeChild[] | ChildrenFn): UIModal;
 export function UIModal(...args: any[]): UIModal {
   return buildUI(args, null, makeModal)
 }