lecodes-cli 0.7.1 → 0.8.0

package/runtime/sdk/ui/UIPopover.ts

@@ -0,0 +1,106 @@
+import { ModalElement, type UIModal, type UIModalStyle } from "./UIModal"
+import { Presentable } from "./presentable"
+import { device } from "../runtime/device"
+import type { BoundingClientRect, ChildrenFn, UINodeChild } from "./UINode"
+
+export type UIPopoverStyle = UIModalStyle
+
+/** What a popover can anchor to: any element (it reads `getBoundingClientRect()`), or a raw
+ *  `{x, y}` point — a long-press context menu anchors to the touch position. */
+export type UIPopoverAnchor = { getBoundingClientRect(): BoundingClientRect | null } | { x: number, y: number }
+
+const POPOVER_ANIM_MS = 120
+const ANCHOR_GAP = 4       // between the anchor's edge and the popover
+const VIEWPORT_MARGIN = 8  // minimum distance kept to every screen edge
+
+/**
+ * An anchored menu: a `UIModal` whose scrim is transparent (invisible but still intercepting —
+ * an outside tap dismisses, and nothing underneath can scroll while it's open) and whose
+ * position comes from the anchor passed to `show(anchor)`: below the anchor's left edge,
+ * flipped above when there's no room, clamped into the viewport. Position is computed once per
+ * show — anchored popovers don't follow their anchor. Backs dropdowns, context menus, and
+ * 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. */
+  show(anchor?: UIPopoverAnchor): void,
+}
+
+export class PopoverElement extends ModalElement {
+  private _anchorRect?: { left: number, top: number, right: number, bottom: number }
+  private _placedLeft?: number
+  private _placedTop?: number
+
+  constructor(style: UIPopoverStyle, children: UINodeChild[] | ChildrenFn) {
+    super({ overlayColor: "transparent", ...style }, children)
+    this.transition({ opacity: 0, duration: POPOVER_ANIM_MS })
+    // The flip/clamp decision needs the popover's measured size, which exists only after the
+    // mount lays it out — so placement is corrected on layout, inside the entrance fade.
+    this.onLayout(({ width, height }) => this._place(width, height))
+  }
+
+  show(anchor?: UIPopoverAnchor): void {
+    if (anchor) {
+      const r = "getBoundingClientRect" in anchor
+        ? anchor.getBoundingClientRect()
+        : { left: anchor.x, top: anchor.y, right: anchor.x, bottom: anchor.y }
+      if (r) {
+        this._anchorRect = { left: r.left, top: r.top, right: r.right, bottom: r.bottom }
+        this._placedLeft = undefined
+        this._placedTop = undefined
+        // Preliminary spot (below, left-aligned) so the first paint is already close; _place
+        // refines it once the size is known.
+        this.style({ left: r.left, top: r.bottom + ANCHOR_GAP })
+      }
+    } else {
+      this._anchorRect = undefined   // unanchored show: the user's own style owns the position
+    }
+    // A menu belongs to the page it opened on: it hides with it and rides its transition. An
+    // explicit attachTo() owner (e.g. a scene HUD's popover) is respected.
+    if (!this._owner) this.attachTo(Presentable.current)
+    super.show()
+  }
+
+  private _place(width: number, height: number): void {
+    const anchor = this._anchorRect
+    if (!anchor || !this._open) return
+    const displayWidth = device.width, displayHeight = device.height   // 0 on hosts without a size
+    let left = anchor.left
+    let top = anchor.bottom + ANCHOR_GAP
+    if (displayWidth > 0) {
+      left = Math.min(left, displayWidth - width - VIEWPORT_MARGIN)
+      left = Math.max(left, VIEWPORT_MARGIN)
+    }
+    if (displayHeight > 0 && top + height > displayHeight - VIEWPORT_MARGIN) {
+      const above = anchor.top - ANCHOR_GAP - height
+      top = above >= VIEWPORT_MARGIN ? above : Math.max(VIEWPORT_MARGIN, displayHeight - VIEWPORT_MARGIN - height)
+    }
+    // Idempotence guard: hosts re-fire onLayout on recalc, and writing the same position would
+    // trigger another recalc — only write when the target actually moved.
+    if (this._placedLeft !== undefined && Math.abs(left - this._placedLeft) < 0.5
+      && this._placedTop !== undefined && Math.abs(top - this._placedTop) < 0.5) return
+    this._placedLeft = left
+    this._placedTop = top
+    this.style({ left, top })
+  }
+}
+
+export function UIPopover(): UIPopover;
+export function UIPopover(children: UINodeChild[] | ChildrenFn): UIPopover;
+export function UIPopover(style: UIPopoverStyle): UIPopover;
+export function UIPopover(style: UIPopoverStyle, children: UINodeChild[] | ChildrenFn): UIPopover;
+export function UIPopover(...args: [] | [UINodeChild[] | ChildrenFn | UIPopoverStyle] | [UIPopoverStyle, children: UINodeChild[] | ChildrenFn]): UIPopover {
+  if (args.length === 0) {
+    return new PopoverElement({}, [])
+  } else if (args.length === 1) {
+    if (Array.isArray(args[0]) || typeof args[0] === "function") {
+      return new PopoverElement({}, args[0])
+    } else {
+      return new PopoverElement(args[0], [])
+    }
+  } else {
+    return new PopoverElement(args[0], args[1])
+  }
+}

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, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type PaddingStyle, type ScrollStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type ScrollStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & ScrollStyle & BaseStyle & ScrollStyle & { refreshControlColor?: Color }
 
@@ -8,11 +8,11 @@ export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & Scro
 // plain `UIScreen`, and a `UIScrollableScreen` (a screen that also scrolls). `makeScrollable()`
 // upgrades a plain screen to the scrollable one, where `onScroll`/`onOverscroll`/`onRefresh` live —
 // they mean nothing without scrolling. `UIScrollableScreen extends UIScreen`, so anywhere a
-// `UIScreen` / `HostedScreen` is accepted, a scrollable one works too.
+// `UIScreen` is accepted (router pages, `UIPager`), a scrollable one works too.
 //
 // This is a subtype split, NOT a `UIScreen<Scrollable>` generic: a generic can't work while `style`
 // is `Style<this,…>`, because `this` is then contravariant and the type becomes invariant in its own
-// params — that was the old `UIScreen<false>`-not-assignable-to-`HostedScreen` bug. See the StyleFn
+// params — that was the old `UIScreen<false>`-not-assignable-to-`UIScreen<boolean>` bug. See the StyleFn
 // note in UINode.ts; the contract is pinned by tests/ui-types.test.ts.
 export interface UIScreen {
   readonly type: "screen",
@@ -41,17 +41,18 @@ export interface UIScreen {
   onClose(callback: () => void): this
 
   /**
-   * Keep this screen's built native tree alive when a UIScreenHost detaches it (replace / remove /
-   * pop): instead of being destroyed, its views + layout + live state (scroll position, input text)
-   * are retained, so re-hosting the SAME screen object restores it in place rather than rebuilding.
-   * `onClose`/`onOpen` still fire on detach/re-attach. You own the lifetime — a kept tree is freed
-   * only by `dispose()` or when the project unloads. (Native-only today; web rebuilds.)
+   * Keep this screen's built native tree alive when a host detaches it: instead of being destroyed,
+   * its views + layout + live state (scroll position, input text) are retained, so re-hosting the
+   * SAME screen object restores it in place rather than rebuilding. `onClose`/`onOpen` still fire on
+   * detach/re-attach. You own the lifetime — a kept tree is freed only by `dispose()` or when the
+   * project unloads. (Native-only today; web rebuilds.)
    */
   keepAlive(enabled?: boolean): this
   /** 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
 
   setClass(name: string, enabled: boolean): this
   toggleClass(name: string): this
@@ -63,8 +64,8 @@ export interface UIScreen {
 
 /**
  * A `UIScreen` in scroll mode — what `makeScrollable()` returns. Adds the scroll lifecycle that a
- * plain screen doesn't carry. A subtype of `UIScreen`, so it's accepted anywhere a screen /
- * `HostedScreen` is (router pages, `UIScreenHost`, `UITabs`).
+ * plain screen doesn't carry. A subtype of `UIScreen`, so it's accepted anywhere a screen is
+ * (router pages, `UIPager`).
  */
 export interface UIScrollableScreen extends UIScreen {
   readonly scrollable: true,

package/runtime/sdk/ui/UIScrollable.ts

@@ -1,5 +1,5 @@
 import type { UIContainerStyle } from "./UIContainer"
-import { type Style, type AnimateStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, ContainerElement } from "./UINode"
+import { type Style, type AnimateStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, ContainerElement } from "./UINode"
 
 export type ScrollStyle = { showScrollbar?: boolean, overscrollMode?: "none" | "absorb" | "default" }
 
@@ -17,6 +17,7 @@ export interface UIScrollable {
   setContent(nodes: UINodeChild[] | ChildrenFn): this
 
   onLayout(onLayout: OnLayoutCallback): this
+  getBoundingClientRect(): BoundingClientRect | null
 
   setClass(name: string, enabled: boolean): this
   toggleClass(name: string): this

package/runtime/sdk/ui/UISpacer.ts

@@ -14,5 +14,5 @@ export interface UISpacer {
 export function UISpacer(): UISpacer
 export function UISpacer(style: UISpacerStyle): UISpacer
 export function UISpacer(style?: UISpacerStyle): UISpacer {
-  return new Element("spacer", style ?? {})
+  return new Element("spacer", { flexGrow: 1, ...style })
 }

package/runtime/sdk/ui/UIText.ts

@@ -1,5 +1,5 @@
 import { createBinding } from "../core/signals"
-import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type Style, type TextStyle } from "./UINode"
+import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Style, type TextStyle } from "./UINode"
 
 export type UITextStyle = ElementStyle & TextStyle & DrawableStyle
 
@@ -11,6 +11,7 @@ export interface UIText {
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
 
   onLayout(onLayout: OnLayoutCallback): this
+  getBoundingClientRect(): BoundingClientRect | null
 
   setClass(name: string, enabled: boolean): this
   toggleClass(name: string): this

package/runtime/sdk/ui/UIVideo.ts

@@ -1,6 +1,6 @@
 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 Style, type StyleFn } from "./UINode"
+import { Element, type AnimateStyle, type AppearStyle, type BaseStyle, type DisappearStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Style, type StyleFn } from "./UINode"
 
 export type UIVideoStyle = ElementStyle & DrawableStyle & { objectFit?: "cover" | "contain" | "fill" }
 
@@ -20,6 +20,7 @@ export interface UIVideo {
   onBackPressed(callback: () => void): this
 
   onLayout(onLayout: OnLayoutCallback): this
+  getBoundingClientRect(): BoundingClientRect | null
 
   setClass(name: string, enabled: boolean): this
   toggleClass(name: string): this

package/runtime/sdk/ui/UIVirtualizedList.ts

@@ -1,4 +1,4 @@
-import { Element, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type PaddingStyle, type Style, type UINodeChild } from "./UINode"
+import { Element, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Style, type UINodeChild } from "./UINode"
 
 export type UIVirtualizedListStyle = DrawableStyle & ElementStyle
 
@@ -45,6 +45,7 @@ export interface UIVirtualizedList<T = unknown> {
     /** Порог от верхнего края — подгрузка истории в чате */
     onStartReached(thresholdPx: number, callback: () => void): this
     onLayout(onLayout: OnLayoutCallback): this
+    getBoundingClientRect(): BoundingClientRect | null
 
     setClass(name: string, enabled: boolean): this
     toggleClass(name: string): this

package/runtime/sdk/ui/UIWidget.ts

@@ -1,6 +1,6 @@
 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 PaddingStyle, type PositionStyle, type Style, type UINodeChild, type ChildrenFn } from "./UINode"
+import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type PositionStyle, type Style, type UINodeChild, type ChildrenFn } from "./UINode"
 
 
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
@@ -17,22 +17,18 @@ export interface UIWidget {
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle & { overlayColor?: Color | null }>
 
   /**
-   * Pre-bind this widget to a destination (a `Scene`, a `UIScreen`, …) that is not current yet —
-   * e.g. HUD for an `ARScene` built before opening it, so it's in place from the first frame.
-   * `show()` binds to the *current* destination automatically, so this is only needed ahead of
-   * time (or to target a non-current owner). Sticky: an explicit owner wins over the automatic
-   * one until `attachTo(null)` (= back to automatic). Set it while the widget is hidden.
+   * 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.
    */
   attachTo(owner: Presentable | null): this,
 
-  /** Show the widget, attached to the current destination (or the `attachTo` owner): it mounts
-   *  inside that page, shows/hides with it and rides its transition — a dialog opened on a screen
-   *  disappears when the user navigates away. For an overlay that survives navigation use
-   *  `showDetached()`. */
+  /** 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(): void,
-  /** Show the widget as a global overlay above every destination — it stays visible across
-   *  navigation (mini-player, global loader). */
-  showDetached(): void,
   hide(): void,
 
   readonly isShow: boolean,
@@ -45,6 +41,7 @@ export interface UIWidget {
   readonly children: UINodeChild[],
 
   onLayout(onLayout: OnLayoutCallback): this
+  getBoundingClientRect(): BoundingClientRect | null
   onTouchStart(callback: (ev: TouchStartEvent<UIWidget>) => void): this,
   onOverlayTap(callback: () => void): this,
   onBackPressed(callback: () => void): this
@@ -59,24 +56,24 @@ export interface UIWidget {
 export class WidgetElement extends ContainerElement<"widget"> {
   scrollable = false as const
   _owner?: Presentable
+  constructor(type: "widget", style: UIWidgetStyle, children: UINodeChild[] | ChildrenFn) {
+    // Widgets are absolutely positioned in device coordinates — 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 {
-    // Explicit attachTo() wins; otherwise bind to whatever is on screen right now — re-showing
-    // the same widget from another page re-attaches it there.
-    const owner = this._owner ?? Presentable.current
-    if (owner && _navSupported()) {
-      _creatorUI.showWidget(this, _descOf(owner))
+    // Global overlay unless explicitly attached via attachTo(owner).
+    if (this._owner && _navSupported()) {
+      _creatorUI.showWidget(this, _descOf(this._owner))
     } else {
-      // Legacy host (or nothing presented yet): global overlay.
+      // Unattached (or legacy host): global overlay above navigation.
       _creatorUI.showWidget(this)
     }
   }
-  showDetached(): void {
-    _creatorUI.showWidget(this)
-  }
   hide(): void {
     _creatorUI.hideWidget(this)
   }

package/runtime/sdk/ui/theme.ts

@@ -0,0 +1,66 @@
+// 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.
+
+export type ThemeValues = Record<string, string | number | null>
+
+export type ThemeAccessors<T extends ThemeValues> = {
+  readonly [K in keyof T]: K extends string ? `var(--${K})` : never
+}
+
+const RESERVED = ["safe-top", "safe-bottom", "safe-left", "safe-right", "vw", "vh", "vmin", "vmax"]
+
+const setTheme = <T extends ThemeValues>(values: T): ThemeAccessors<T> => {
+  const accessors: Record<string, string> = {}
+  let send: ThemeValues = values
+  for (const key of Object.keys(values)) {
+    if (RESERVED.includes(key)) {
+      console.warn(`theme(): "${key}" is an environment value (host-owned) — ignored`)
+      if (send === values) send = { ...values }
+      delete send[key]
+      continue
+    }
+    accessors[key] = `var(--${key})`
+  }
+  // Optional during rollout: hosts without the method simply don't theme (values still type).
+  _creatorUI.setTheme?.(send)
+  return accessors as ThemeAccessors<T>
+}
+
+export const theme = Object.assign(setTheme, {
+  /** The app accent color. Kit components will read it via `var(--primaryColor, <fallback>)`. */
+  primaryColor: "var(--primaryColor)",
+  /** Secondary / inactive content color for kit components. */
+  mutedColor: "var(--mutedColor)",
+  /** DEFAULT text color — text without an explicit `color` follows it (hosts source their
+   *  default from the theme; unset = the host default, white on dark screens). Set it once for
+   *  a light theme instead of `color: "black"` on every label. */
+  color: "var(--color)",
+  /** DEFAULT text font — text without an explicit `fontFamily` follows it. */
+  fontFamily: "var(--fontFamily)",
+  /** Raw comfort knobs (logical px). The bare `comfort-top` style TOKEN applies the safe-area
+   *  formula — these accessors read the knob value itself, for manual composition. */
+  "comfort-top": "var(--comfort-top)",
+  "comfort-bottom": "var(--comfort-bottom)",
+  "comfort-left": "var(--comfort-left)",
+  "comfort-right": "var(--comfort-right)",
+} as const)