lecodes-sdk 2.0.7 → 2.0.9

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

@@ -11,17 +11,20 @@ export type UIModalTransition = DrawableStyle & BaseStyle & {
 };
 /**
  * A dialog: a `UIWidget` with the modal boilerplate built in. Comes with a scrim
- * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), animates on `show()`/`hide()`
- * (a 200 ms fade by default — swap the pose via `transition()`; the exit plays with
- * `commit: false`, so the style is intact for the next show), and closes itself on a scrim tap
- * or the Android back button (disable via `dismissible(false)`). Everything else is a plain
- * widget — same styling, children, touch and `attachTo()` surface; create it **once** at module
- * scope and reuse it.
+ * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), animates on `show()`/`hide()` and on
+ * a state block flipping its `display` (a 200 ms fade by default — swap the pose via
+ * `transition()`; the runtime plays it as tracks that never touch the style), and closes itself
+ * on a scrim tap or the Android back button (disable via `dismissible(false)`). Everything else
+ * is a plain widget: declare it where it belongs — among its screen's children, hidden until a
+ * tap (`display: "none"`), or shown with `show()` from anywhere, which puts a parentless modal in
+ * the app layer. A dialog bound to data (its display from a binding) is declared
+ * `dismissible(false)` and routes `onOverlayTap` / `onBack` into the data's dismiss, so the data
+ * stays what the screen shows.
  */
 export interface UIModal extends UIWidget {
-    /** Mount as an overlay and play the entrance transition. No-op while already open. */
+    /** Show and play the entrance transition. No-op while already open. */
     show(): void;
-    /** Play the exit transition, then unmount. No-op while closed or already closing. */
+    /** Play the exit transition, then hide. No-op while closed or already closing. */
     hide(): void;
     /** True from `show()` until `hide()` starts (already false during the exit animation). */
     readonly isOpen: boolean;
@@ -36,24 +39,24 @@ export interface UIModal extends UIWidget {
      * ```
      */
     transition(hidden: UIModalTransition): this;
-    /** Called when `show()` mounts the modal. */
+    /** Called when the modal opens — `show()`, or a state block flipping its display. */
     onOpen(callback: () => void): this;
-    /** Called when the modal starts closing — scrim tap, back button, or a `hide()` call. */
+    /** Called when the modal starts closing — scrim tap, back button, a `hide()` call, or a state
+     *  block flipping its display. */
     onClose(callback: () => void): this;
     /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
-     *  (forced-choice dialogs). Default `true`. */
+     *  (forced-choice dialogs, a dialog whose display is bound to data). Default `true`. */
     dismissible(enabled: boolean): this;
 }
 export declare class ModalElement extends WidgetElement {
-    _open: boolean;
     _dismissible: boolean;
     _transition: UIModalTransition;
-    _closeTimer?: ReturnType<typeof setTimeout>;
     readonly _openListeners: (() => void)[];
     readonly _closeListeners: (() => void)[];
+    private _poseObj?;
+    private _poseKey;
     constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn);
     private _pose;
-    private get _duration();
     transition(hidden: UIModalTransition): this;
     show(): void;
     hide(): void;
@@ -62,7 +65,8 @@ export declare class ModalElement extends WidgetElement {
     onClose(callback: () => void): this;
     dismissible(enabled: boolean): this;
 }
-/** Create a modal dialog (see {@link UIModal}) — create once at module scope, then
- *  `show()`/`hide()`. Same argument forms as `UIColumn`. */
+/** Create a modal dialog (see {@link UIModal}): declare it among its screen's children with
+ *  `display: "none"` and `show()` it from a tap, or `show()` a parentless one from anywhere.
+ *  Same argument forms as `UIColumn`. */
 export declare function UIModal(...children: UIChildArg[]): UIModal;
 export declare function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;

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

@@ -18,9 +18,11 @@ export type UIPopoverAnchor = {
  * tooltips; create it **once** at module scope and reuse it.
  */
 export interface UIPopover extends UIModal {
-    /** Position next to `anchor` (an element or an `{x, y}` point), attach to
-     *  `Presentable.current` (unless an owner was set via `attachTo`), and play the entrance
-     *  transition. Without an anchor the popover shows wherever its own style puts it. */
+    /** Position next to `anchor` (an element or an `{x, y}` point), put the popover where the
+     *  anchor is — the anchor's screen, page or surface content, found through the tree, so the
+     *  menu lands where it was opened and goes with it — and play the entrance transition. A
+     *  popover with no anchor and no parent goes to the app layer; without an anchor it shows
+     *  wherever its own style puts it. */
     show(anchor?: UIPopoverAnchor): void;
 }
 export declare class PopoverElement extends ModalElement {

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

@@ -1,4 +1,5 @@
 import type { VideoPlayer } from "../runtime/media";
+import { type UIWidgetContent } from "./UILayer";
 import { type DismissOptions, type PresentOptions } from "./presentable";
 import { type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode";
 export type UIVideoStyle = ElementStyle & DrawableStyle & {
@@ -21,6 +22,8 @@ export interface UIVideo extends UIElementBase<UIVideoStyle, DrawableStyle & Bas
     onClose(callback: () => void): this;
     /** Hardware/system back while current. */
     onBack(callback: () => void): this;
+    /** The UI over the video when presented: widgets over it (`Presentable.setContent`). */
+    setContent(content: UIWidgetContent): this;
 }
 /** Create a video node showing `player`'s output. */
 export declare function UIVideo(player: VideoPlayer): UIVideo;

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

@@ -1,36 +1,39 @@
 import { TouchStartEvent } from "../runtime/touch";
-import { Presentable } from "./presentable";
 import { ContainerElement, 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 & {
+    /** 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. */
     onTouchStart(callback: (ev: TouchStartEvent<UIWidget>) => void): this;
@@ -44,10 +47,7 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
 }
 export declare class WidgetElement extends ContainerElement<"widget"> {
     scrollable: false;
-    _owner?: Presentable;
-    private _shown;
     constructor(type: "widget", style: UIWidgetStyle, children: UINodeChild[] | ChildrenFn);
-    attachTo(owner: Presentable | null): this;
     show(): void;
     hide(): void;
     get isShown(): boolean;
@@ -60,7 +60,8 @@ export declare class WidgetElement extends ContainerElement<"widget"> {
     /** @deprecated see the interface */
     onBackPressed(callback: any): this;
 }
-/** 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 declare function UIWidget(...children: UIChildArg[]): UIWidget;
 export declare function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;

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

@@ -1,4 +1,5 @@
 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;
  *  the rest are two-screen moves. */
@@ -14,6 +15,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. */
@@ -70,6 +74,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;
 }
 /** Runtime companion of the `Presentable` interface (declaration merging): the navigation
  *  state that isn't tied to the Router. */

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

@@ -1,4 +1,4 @@
-import type { TransitionSpec } from "./presentable";
+import type { TransitionPose, TransitionSpec } from "./presentable";
 /** Wire ids: a registered transition is > 0. */
 export declare const TRANSITION_NONE = 0;
 /** "The caller names none": the runtime plays what the stack entry remembers (a pop), or keeps
@@ -16,3 +16,4 @@ export declare const TRANSITION_ENTER_ON_TOP = 1;
  *  one that left comes back from its `exit` pose, the same screen stays on top — and the timing and
  *  the curves stay as written. Not a rewind: that would turn an ease-out into a slow start. */
 export declare const mirrored: (s: TransitionSpec) => TransitionSpec;
+export declare const _widgetPoseId: (pose: TransitionPose | null) => number;

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

@@ -33,6 +33,7 @@ export declare const TREE_EVENT_HOVER_ENTER = 32;
 export declare const TREE_EVENT_HOVER_MOVE = 33;
 export declare const TREE_EVENT_HOVER_END = 34;
 export declare const TREE_EVENT_HOVER_CANCEL = 35;
+export declare const TREE_EVENT_WIDGET_VISIBLE = 36;
 export declare const TREE_FLAG_INTERACTIVE: number;
 export declare const TREE_FLAG_CLICK: number;
 export declare const TREE_FLAG_LONG_PRESS: number;

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.0.7";
+export declare const SDK_VERSION = "2.0.9";
 /** 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