lecodes-sdk 2.0.7 → 2.0.9

package/src/ui/UIWidget.ts

@@ -1,42 +1,45 @@
 import { TouchStartEvent } from "../runtime/touch"
-import { Presentable } from "./presentable"
 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"
-import { TREE_DEST_NONE, TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, pin, tree, unpin } from "./tree"
+import { UIOverlay } from "./UILayer"
+import { TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, tree } from "./tree"
 
 
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
+  /** Shown (`"flex"`, the default) or not: what `show()` / `hide()` write, what a state block may
+   *  flip (`$open: { display: "flex" }`). */
+  display?: "none" | "flex",
   /** A layer behind the widget that intercepts clicks — `"transparent"` still intercepts, `null`
    *  removes the layer. A tap on it fires `onOverlayTap`. */
   overlayColor?: Color | null
 }
 
 
-/** 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. */
+/** A floating overlay that belongs to a WINDOW, not to a box (docs/plans/widgets-plan.md): a dialog,
+ *  a sheet, a HUD, a mini-player. A widget is a CHILD of the place it belongs to — a `UIScreen`
+ *  (among its children), a surface's content (`scene.setContent([hud])`) or the app layer
+ *  (`UIOverlay`) — and is laid out and painted in the box of the outermost presented destination
+ *  that contains it: absolutely positioned in that box, above everything else in it. A widget on a
+ *  tab page covers the tab bar and rides the shell's push and pop. A widget inside a `UIColumn` or
+ *  any other box is an error: a floating element of a box is an absolute child, not a widget.
+ *
+ *  It shows with its place unless its style says `display: "none"`; `show()` / `hide()` flip that,
+ *  and so does a state block (`$class: { display: "flex" }`). `UIModal` / `UIPopover` /
+ *  `UIBottomSheet` build on it. */
 export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle & BaseStyle & { overlayColor?: Color | null }> {
   readonly type: "widget",
 
-  /**
-   * Attach this widget to a destination (a `Scene`, a `UIScreen`, …): the widget lives on that
-   * page's layer — it shows/hides with the page and rides its transition, and a screen pushed
-   * on top covers it (a scene HUD behaves like part of the scene). Sticky until `attachTo(null)`
-   * (= back to a global overlay). Set it while the widget is hidden. The widget is always its own
-   * overlay root mounted into the owner's page view — it never becomes a child of the owner, so it
-   * stays topmost and its updates never trigger the owner's relayout. Works with a `UIScreen` that
-   * is a page inside a `UIPager`: the widget mounts into that tab and rides its swipe.
-   */
-  attachTo(owner: Presentable | null): this,
-
-  /** Show the widget. By default it is a global overlay above every destination — it stays
-   *  visible across navigation until `hide()` (dialogs, mini-player, global loader). If the
-   *  widget was attached via `attachTo(owner)`, it mounts on that page's layer instead and is
-   *  only visible while the owner is presented. */
+  /** Show the widget: `display: "flex"`, on top of its root — it moves to the end of its parent's
+   *  children, so a dialog opened later covers an earlier one and a HUD declared after it. A widget
+   *  with no parent is appended to the app layer first (`UIOverlay`) — a global overlay above every
+   *  destination, up until `hide()`. */
   show(): void,
-  /** Unmount the widget. */
+  /** Hide the widget: `display: "none"`. It stays where it is (its place, the app layer), ready
+   *  for the next `show()`. */
   hide(): void,
 
-  /** Mounted right now (`show()` ran, `hide()` hasn't). */
+  /** Shown right now by its own display (`show()` ran, `hide()` hasn't, no state block hides
+   *  it). True for a widget hidden WITH its page or its covered screen: that is its place's
+   *  visibility, not the widget's. */
   readonly isShown: boolean,
 
   /** Touch began on the widget; `ev.track(...)` takes over the rest of the gesture. */
@@ -53,41 +56,63 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
 
 export class WidgetElement extends ContainerElement<"widget"> {
   scrollable = false as const
-  _owner?: Presentable
-  private _shown = false
+  /** @internal The widget's own display as last known, while it has a place: what the app wrote,
+   *  corrected by the runtime's report when a state block flipped it (TREE_EVENT_WIDGET_VISIBLE).
+   *  False while the widget is nowhere (made, not placed; removed). */
+  _shown = false
   constructor(type: "widget", style: UIWidgetStyle, children: UINodeChild[] | ChildrenFn) {
-    // Widgets are absolutely positioned in device coordinates — in the constructor (not the
+    // Widgets are absolutely positioned in their root's box — in the constructor (not the
     // factory) so subclasses like ModalElement inherit it.
     super(type, { position: "absolute", ...style }, children)
   }
-  attachTo(owner: Presentable | null): this {
-    this._owner = owner ?? undefined
-    return this
-  }
   show(): void {
-    // A widget is always its OWN overlay root (a separate Yoga tree mounted above the owner's
-    // content) — never a child of the owner, so it stays topmost, its updates never relayout the
-    // owner, and it doesn't pollute the owner's children. `attachTo(owner)` just tells the host
-    // which page view to mount that root into; ownerless widgets are global overlays.
-    if (this._h.id === 0 || this._shown) return
-    this._shown = true
-    pin(this)
-    if (this._owner) {
-      const [kind, id] = this._owner._dest()
-      tree().showWidget(this._h.id, kind, id)
+    if (this._h.id === 0) return
+    const parentId = tree().parent(this._h.id)
+    if (parentId !== 0 && this._shown) return
+    if (parentId === 0) {
+      // No place of its own: the app layer takes it HIDDEN, and the flip below shows it — a show()
+      // is a display flip wherever the widget is, so its pose plays (a modal's fade) exactly as on
+      // a placed one. Appended shown, it would merely appear: a widget shows with its place, no pose.
+      this.style({ display: "none" } as any)
+      UIOverlay.append(this as any)   // pins it: _pinned reads the display
     } else {
-      tree().showWidget(this._h.id, TREE_DEST_NONE, 0)
+      // Shown = on top of its root: a show() moves the widget to the TAIL of its parent's children
+      // (child order is the one ordering rule), so a modal opened later covers an earlier one and
+      // the HUD declared after it — while still hidden, so the move is silent (no onClose / onOpen).
+      // A state block flipping the display moves nothing: the order is what the tree says.
+      const siblings = tree().children(parentId)
+      if (siblings[siblings.length - 1] !== this._h.id) {
+        tree().remove(parentId, this._h.id)
+        tree().insert(parentId, this._h.id, siblings.length - 1)
+      }
     }
+    this.style({ display: "flex" } as any)
+    this._setShown(true)
   }
   hide(): void {
     if (this._h.id === 0 || !this._shown) return
-    this._shown = false
-    tree().hideWidget(this._h.id)
-    unpin(this._h.id)
+    this._setShown(false)
+    this.style({ display: "none" } as any)
   }
   get isShown(): boolean {
     return this._shown
   }
+  /** @internal The intent changed (the app's call, or the runtime's report of a cascade flip):
+   *  subclasses hook the change (UIModal's onOpen / onClose). */
+  _setShown(shown: boolean): void {
+    if (shown === this._shown) return
+    this._shown = shown
+    this._shownChanged(shown)
+  }
+  /** @internal */
+  _shownChanged(_shown: boolean): void {}
+  /** @internal The runtime: the widget's resolved display flipped — or, at its place, the cascade
+   *  says otherwise than the style it read in `_pinned` (the runtime reports nothing else there). */
+  _emitVisible(shown: boolean): void { this._setShown(shown) }
+  /** @internal Placed (inserted under a screen, a layer): shown by its own display from here on. */
+  _pinned(): void { this._setShown((this._style as { display?: string }).display !== "none") }
+  /** @internal Taken out of its place: shown nowhere. */
+  _unpinned(): void { this._setShown(false) }
 
   readonly touchStartListeners: any[] = []
   onTouchStart (callback: any): this {
@@ -138,7 +163,8 @@ const makeWidget = (style: any, children: any) => new WidgetElement("widget", st
 /** @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
+/** Create a widget (same argument forms as `UIColumn`). Put it where it belongs — among a screen's
+ *  children, in `scene.setContent([...])`, or `UIOverlay` — 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;

package/src/ui/presentable.ts

@@ -2,7 +2,7 @@
 // Anything that can occupy the app's main slot implements it: UIScreen, Scene (+ARScene),
 // Scene2D, NativeView, UIVideo. Exactly one Presentable is visible at a time — a screen no
 // longer overlays a scene, it replaces it (with a transition); UI over a scene goes through
-// `UIWidget.attachTo(scene)`.
+// `scene.setContent([hud])` — a widget is the destination's content (docs/plans/widgets-plan.md).
 //
 // A destination is addressed by (kind, id): a screen / video by its node id, a scene by its
 // scene id, a native view by its viewId (`_dest()`). The runtime reports the lifecycle back through
@@ -12,6 +12,7 @@
 // element code into engine-only bundles.
 
 import type { EasingInput } from "../animate/tween/easing"
+import type { UIWidget } from "./UIWidget"
 
 /** The built-in transitions (ui/transitions.ts holds what each one is). `push` / `pop` are the
  *  stacked-navigation pair — the incoming screen slides over the other one, which drifts and dims;
@@ -32,6 +33,9 @@ export type TransitionPose = {
   opacity?: number | number[]
   /** Black over this screen, 0..1: how dark the screen UNDER the other one gets. */
   dim?: number | number[]
+  /** A widget's overlay layer (its scrim) in the pose — a widget's enter / exit pose only
+   *  (`UIModal.transition`): `"transparent"` fades the scrim in with the dialog. */
+  overlayColor?: string | string[]
   /** ms (default 300). */
   duration?: number
   /** ms to wait; the screen holds its first pose through it. */
@@ -97,6 +101,12 @@ export interface Presentable {
   onOpen(callback: () => void): this
   onClose(callback: () => void): this
   onBack(callback: () => void): this
+  /** The destination's widgets (docs/plans/widgets-plan.md): a dialog, a HUD, a sheet declared as
+   *  CONTENT of the place they belong to. A `UIScreen` takes them among its children; a surface — a
+   *  `Scene`, a `Scene2D`, a `NativeView`, a `UIVideo` — takes widgets alone, laid out over it while
+   *  it is presented (touches outside a widget's box reach the surface). A widget shows with its
+   *  destination unless its style says `display: "none"`; `show()` / `hide()` flip that. */
+  setContent(content: (UIWidget | null | undefined | false)[] | (() => (UIWidget | null | undefined | false)[])): this
   /** @internal Async work that must finish BEFORE this destination replaces the current one
    *  (camera permission, warm render, session launch — ARScene). The previous destination —
    *  typically a loading screen — stays visible while it runs; `open()` and `Router.push/replace`

package/src/ui/transitions.ts

@@ -9,7 +9,7 @@
 
 import type { Easing } from "../animate/easings"
 import { DEFAULT_EASING, parseEasing, type EasingSpec } from "../animate/tween/easing"
-import { CLOCK_UI, DOM_UI, KIND_FLOAT, KIND_TRANSFORM, buildBlob, parseTransformList, transformLanes, warnOnce, type Keyframe, type Track, type TweenTarget } from "../animate/tween/spec"
+import { CLOCK_UI, DOM_UI, KIND_FLOAT, KIND_STRING, KIND_TRANSFORM, buildBlob, parseTransformList, transformLanes, warnOnce, type Keyframe, type Track, type TweenTarget } from "../animate/tween/spec"
 import type { Transition, TransitionName, TransitionPose, TransitionSpec } from "./presentable"
 
 /** Wire ids: a registered transition is > 0. */
@@ -120,7 +120,9 @@ export const mirrored = (s: TransitionSpec): TransitionSpec => ({
 
 /** One prop of a side: its keys in the order the side plays them (an incoming side ends at rest
  *  after them, an outgoing one starts at rest before them), and what rest is. */
-type Lane = { prop: string, kind: number, sig?: string, keys: number[][], rest: number[] }
+// A string lane (a widget's `overlayColor`): its keys are strings, its rest is CAPTURED at play —
+// the widget's own scrim color, which the transition cannot know.
+type Lane = { prop: string, kind: number, sig?: string, keys: number[][], rest: number[], strKeys?: string[] }
 type Side = { lanes: Lane[], atMs: number, durMs: number, easing: EasingSpec }
 
 const list = <T>(v: T | T[]): T[] => (Array.isArray(v) ? v : [v])
@@ -141,12 +143,16 @@ const transformLane = (value: string | string[]): Lane | null => {
 const floatLane = (prop: string, value: number | number[], rest: number): Lane =>
   ({ prop, kind: KIND_FLOAT, keys: list(value).map((v) => [v]), rest: [rest] })
 
+const stringLane = (prop: string, value: string | string[]): Lane =>
+  ({ prop, kind: KIND_STRING, keys: list(value).map(() => [0]), rest: [0], strKeys: list(value) })
+
 const sideOf = (pose: TransitionPose | undefined): Side | null => {
   if (!pose) return null
   const lanes: Lane[] = []
   if (pose.transform !== undefined) { const l = transformLane(pose.transform); if (l) lanes.push(l) }
   if (pose.opacity !== undefined) lanes.push(floatLane("opacity", pose.opacity, 1))
   if (pose.dim !== undefined) lanes.push(floatLane("dim", pose.dim, 0))
+  if (pose.overlayColor !== undefined) lanes.push(stringLane("overlayColor", pose.overlayColor))
   if (lanes.length === 0) return null
   return {
     lanes,
@@ -162,7 +168,7 @@ const sideOf = (pose: TransitionPose | undefined): Side | null => {
  *  the direction being the opposite one. No dim: nothing is over it. */
 const borrowed = (side: Side | null): Side | null => {
   if (!side) return null
-  const lanes = side.lanes.filter((l) => l.prop !== "dim").map((l) => {
+  const lanes = side.lanes.filter((l) => l.prop !== "dim" && l.strKeys === undefined).map((l) => {
     if (l.kind !== KIND_TRANSFORM) return { ...l, keys: l.keys.slice().reverse() }
     const sign: number[] = []
     for (const fn of l.sig!.split(",")) for (let i = transformLanes(fn); i > 0; i--) sign.push(fn.startsWith("translate") ? -1 : 1)
@@ -178,6 +184,12 @@ const tracksOf = (side: Side | null, role: number, incoming: boolean): Track[] =
   if (!side) return []
   const channel = { domain: DOM_UI, id: () => role + 1, value: () => null }
   return side.lanes.map((l) => {
+    if (l.strKeys !== undefined) {
+      // a string lane: the keys as strings, the rest captured at play (the node's own value)
+      const values: (string | null)[] = incoming ? [...l.strKeys, null] : [null, ...l.strKeys]
+      const keys: Keyframe[] = values.map((str, i) => ({ t: i / (values.length - 1), easing: side.easing, value: str === null ? undefined : { str } }))
+      return { target: roleTarget, prop: l.prop, channel, kind: l.kind, lanes: 1, atMs: side.atMs, durMs: side.durMs, commit: false, keys }
+    }
     // explicit keys at both ends: a captured one that fails to read would leave a screen in its pose
     const values = incoming ? [...l.keys, l.rest] : [l.rest, ...l.keys]
     const keys: Keyframe[] = values.map((lanes, i) => ({ t: i / (values.length - 1), easing: side.easing, value: { lanes } }))
@@ -186,15 +198,16 @@ const tracksOf = (side: Side | null, role: number, incoming: boolean): Track[] =
 }
 
 /** @internal The blob of a spec: `roles[i]` is the role of the blob's target `i`. Null = the spec
- *  moves nothing. */
-export const _transitionBlob = (spec: TransitionSpec): { data: Float32Array, strings: string[], roles: number[], flags: number } | null => {
+ *  moves nothing. `ownAlone`: the ALONE roles are the spec's own sides as written (a widget's pose:
+ *  it enters from `enter`, leaves to `exit`, nothing is borrowed from the other side). */
+export const _transitionBlob = (spec: TransitionSpec, ownAlone = false): { data: Float32Array, strings: string[], roles: number[], flags: number } | null => {
   const enter = sideOf(spec.enter), exit = sideOf(spec.exit)
   const enterOnTop = (spec.onTop ?? "enter") === "enter"
   const tracks = [
     ...tracksOf(enter, ROLE_ENTER, true),
     ...tracksOf(exit, ROLE_EXIT, false),
-    ...tracksOf(enterOnTop ? enter : borrowed(exit), ROLE_ENTER_ALONE, true),
-    ...tracksOf(enterOnTop ? borrowed(enter) : exit, ROLE_EXIT_ALONE, false),
+    ...tracksOf(ownAlone ? enter : enterOnTop ? enter : borrowed(exit), ROLE_ENTER_ALONE, true),
+    ...tracksOf(ownAlone ? exit : enterOnTop ? borrowed(enter) : exit, ROLE_EXIT_ALONE, false),
   ]
   if (tracks.length === 0) return null
   let durationMs = 0
@@ -242,8 +255,24 @@ export const _transitionBack = (t: Transition): number => {
   return e.back
 }
 
+/** @internal The wire id of a WIDGET's pose (docs/plans/widgets-plan.md decision 11): the pose it
+ *  enters from and leaves to, as one transition whose ALONE roles the runtime plays on the widget's
+ *  display flips. Registered once per distinct pose object; `null` = no pose (TRANSITION_NONE). */
+let poseIds = new WeakMap<TransitionPose, number>()
+export const _widgetPoseId = (pose: TransitionPose | null): number => {
+  if (!pose) return TRANSITION_NONE
+  let id = poseIds.get(pose)
+  if (id === undefined) {
+    const blob = _transitionBlob({ enter: pose, exit: pose }, true)
+    id = blob ? _creatorTree.defineTransition(blob.data, blob.strings, blob.roles, blob.flags) : TRANSITION_NONE
+    poseIds.set(pose, id)
+  }
+  return id
+}
+
 /** @internal Tests: a new fake runtime has no transition of the previous one. */
 export const _resetTransitions = (): void => {
   byName = new Map()
   bySpec = new WeakMap()
+  poseIds = new WeakMap()
 }

package/src/ui/tree.ts

@@ -45,6 +45,7 @@ export const TREE_EVENT_HOVER_ENTER = 32
 export const TREE_EVENT_HOVER_MOVE = 33
 export const TREE_EVENT_HOVER_END = 34
 export const TREE_EVENT_HOVER_CANCEL = 35
+export const TREE_EVENT_WIDGET_VISIBLE = 36
 
 // ---- setFlags(id, mask) ---------------------------------------------------------------------------
 export const TREE_FLAG_INTERACTIVE = 1 << 0
@@ -132,6 +133,8 @@ export interface TreeElement {
   _pinned?(): void
   _unpinned?(): void
   _emitBack?(): boolean
+  /** A widget: its resolved display flipped (a style write or the cascade) — `isShown` follows. */
+  _emitVisible?(shown: boolean): void
 }
 
 /** @internal A track handler (runtime/touch.ts TrackHandler), as the emitter reads it. */
@@ -285,6 +288,7 @@ const emit = (id: number, kind: number, a?: any, b?: any, c?: any, d?: any, e?:
       t?.onEnd?.({ clientX: a, clientY: b, deltaX: c, deltaY: d })
       return
     }
+    case TREE_EVENT_WIDGET_VISIBLE: pins.get(id)?._emitVisible?.(!!a); return
     case TREE_EVENT_HOVER_CANCEL: {
       const t = hoverTracker
       hoverTracker = null

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.0.7"
+export const SDK_VERSION = "2.0.9"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {

package/tests/helpers/fakeTree.ts

@@ -9,6 +9,7 @@ import {
   TREE_EVENT_CLOSE, TREE_EVENT_DETACHED, TREE_EVENT_FREED, TREE_EVENT_OPEN, TREE_EVENT_ROUTER_CHANGE, TREE_EVENT_VLIST_SYNC,
 } from "../../src/ui/tree"
 import { _resetTransitions } from "../../src/ui/transitions"
+import { _resetOverlay } from "../../src/ui/UILayer"
 
 export type FakeNode = {
   id: number, type: string, parent: number, children: number[],
@@ -28,7 +29,9 @@ export class FakeTree {
   displaySize: [number, number] = [0, 0]
   current: Dest | null = null
   stack: Dest[] = []
-  widgets: number[] = []
+  /** The layers by destination key (`kind:id`; `255:0` = the app layer) and the widgets' poses. */
+  layers = new Map<string, number>()
+  poses = new Map<number, number>()
   freed: number[] = []
   tweens: { id: number, data: Float32Array, strings: string[], targets: number[] }[] = []
   tweenEvent: ((id: number, kind: number, index: number, ...lanes: number[]) => void) | null = null
@@ -207,8 +210,8 @@ export class FakeTree {
     else onReject(`no view ${viewId}`)
   }
   viewCallHandler: ((viewId: number, method: string, args: any[], res: (r?: unknown) => void, rej: (m: string) => void) => void) | null = null
-  showWidget = (id: number, ownerKind: number, ownerId: number): void => { this.rec("showWidget", id, ownerKind, ownerId); if (!this.widgets.includes(id)) this.widgets.push(id) }
-  hideWidget = (id: number): void => { this.rec("hideWidget", id); this.widgets = this.widgets.filter((w) => w !== id) }
+  setLayer = (kind: number, id: number, layer: number): void => { this.rec("setLayer", kind, id, layer); if (layer) this.layers.set(`${kind}:${id}`, layer); else this.layers.delete(`${kind}:${id}`) }
+  setWidgetPose = (id: number, transition: number): void => { this.rec("setWidgetPose", id, transition); this.poses.set(id, transition) }
 
   // ---- pager -----------------------------------------------------------------------------------------
   private pagerTop(p: FakeNode): number | null {
@@ -341,6 +344,7 @@ export const installFakeTree = (): FakeTree => {
   fake.emitter = FakeTree.primary ?? prev?.emitter ?? null
   if (prev?.tweenEvent) fake.tweenEvent = prev.tweenEvent   // registered once per world too
   _resetTransitions()   // …while a transition is registered per RUNTIME: the new fake has none
+  _resetOverlay()       // …and the app layer is a node of the previous fake
   ;(globalThis as any)._creatorTree = fake
   return fake
 }