lecodes-cli 0.10.4 → 0.12.0

package/runtime/sdk/ui/UINode.ts

@@ -10,10 +10,19 @@ export interface UINode {
   readonly class: Classes<this>
 }
 
+/** A child slot value: a node, or falsy (conditional rendering — falsy entries are skipped). */
 export type UINodeChild = UINode | null | undefined | false
 
+/** A factory child argument: a node (or falsy for conditionals), or an array of them — arrays are
+ *  flattened one level at the argument position, so `UIColumn(header, items.map(row), footer)`
+ *  needs no spread. */
+export type UIChildArg = UINodeChild | UINodeChild[]
+
+/** A color: CSS-style string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"var(--primaryColor)"`) or
+ *  packed number; `null` clears. */
 export type Color = number | string | null
 
+/** Style props every element accepts. */
 export type BaseStyle = {
   opacity?: number | `${number}`,
   transform?: string | null,
@@ -29,6 +38,7 @@ export type BaseStyle = {
   name?: string,
 }
 
+/** Painted-box props: background, gradient, border, radius. */
 export type DrawableStyle = {
   backgroundImage?: FetchResponse | File | string | null,
   bgGradient?: string,
@@ -62,6 +72,7 @@ export type DrawableStyle = {
   pointerEvents?: "all" | "none",
 }
 
+/** Flex-layout props of a container (how it lays out its children). */
 export type ContainerStyle = {
   flexDirection?: "row" | "column",
   justifyContent?: "flex-start" | "center" | "flex-end" | "space-between" | "space-evenly",
@@ -70,6 +81,7 @@ export type ContainerStyle = {
   flexWrap?: "nowrap" | "wrap" | "wrap-reverse"
 }
 
+/** A dimension: a number (logical px) or a CSS-style unit / function string. */
 type UIValue = number |
   `${number}px` |
   `${number}vw` |
@@ -84,6 +96,8 @@ type UIValue = number |
   `clamp(${string})` |
   `var(--${string})`
 
+/** Padding, with `p`/`px`/`pl`… shorthands. `safe-*` insets by the device safe area,
+ *  `comfort-*` by the theme's comfort knobs (max of both). */
 export type PaddingStyle = {
   paddingLeft?: UIValue | "safe-left" | "comfort-left",
   paddingTop?: UIValue | "safe-top" | "comfort-top",
@@ -102,8 +116,7 @@ export type PaddingStyle = {
   py?: UIValue | "comfort-y",
 }
 
-
-
+/** Margin, with `m`/`mx`/`ml`… shorthands; `"auto"` centers/pushes like CSS. */
 export type MarginStyle = {
   marginLeft?: UIValue | "auto" | "safe-left" | "comfort-left",
   marginTop?: UIValue | "auto" | "safe-top" | "comfort-top",
@@ -122,6 +135,7 @@ export type MarginStyle = {
   my?: UIValue | "auto" | "comfort-y",
 }
 
+/** Box position (for `position: "absolute"`) and size constraints. */
 export type PositionStyle = {
   top?: UIValue | `${number}%` | 'safe-top' | 'comfort-top',
   left?: UIValue | `${number}%` | 'safe-left' | 'comfort-left',
@@ -137,6 +151,7 @@ export type PositionStyle = {
   minHeight?: UIValue | `${number}%` | "auto",
 }
 
+/** The base style of every element: box + flex-child props. */
 export type ElementStyle = PaddingStyle & MarginStyle & BaseStyle & PositionStyle & {
   position?: "absolute" | "static" | "relative",
   aspectRatio?: number,
@@ -148,6 +163,7 @@ export type ElementStyle = PaddingStyle & MarginStyle & BaseStyle & PositionStyl
   display?: "none" | "flex"
 }
 
+/** Typography props. */
 export type TextStyle =  {
   textAlign?: "start" | "center" | "end" | "left" | "right"
   fontFamily?: string,
@@ -189,7 +205,7 @@ function applyBindings(el: any, fns: [string, () => any][]) {
   }
 }
 
-// Не надо переписывать эту функцию 10 раз, обрати внимание, что у тебя тут возвращается this
+// NB: returns `this` — `.style()` must chain. Don't rewrite.
 function styleFunction(this: any, newStyle: any) {
   // `name` is a JS-node selector (read by hosts off el.name), not a layout property — extract it
   // exactly like the constructor so `.style({ name })` is equivalent to the first-arg style. Left
@@ -305,26 +321,21 @@ const classHandler: ProxyHandler<any> = {
   }
 }
 
-function Style() {
-
-}
-
-// Reactive style input: every primitive-valued prop also accepts a `() => value` binding that
-// re-applies when a signal it read changes. Nested state blocks (onPressed, onLandscape, …) stay
-// static — bindings are extracted at the top level only.
+/** Reactive style input: every primitive-valued prop also accepts a `() => value` binding that
+ *  re-applies when a signal it read changes. Nested state blocks (onPressed, onLandscape, …) stay
+ *  static — bindings are extracted at the top level only. */
 export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]) }
 
-// User-defined style classes: any `$`-prefixed key in .style() declares a state block (like
-// onPressed, but with any name), toggled from code via the `el.class` proxy. `duration`/`delay`
-// make the swap transition. Class state INHERITS down the tree (CSS-`.dark`-on-body style): a
-// class set on a node also activates same-name `$` blocks on all descendants within the same
-// root — see docs/style-class-cascade-plan.md. `$pressed`/`$focused` are reserved: hosts toggle
-// them on press/focus (they beat other classes, lose to onPressed/onFocused), so children can
-// react to an ancestor's press. Instantiate with the node's own style `T` (see StyleFn below) — a
-// class block accepts everything the node's `.style()` does (e.g. `color` on text, layout on any
-// node), exactly like `onLandscape`/`onPortrait`. Narrowing it (it once was `DrawableStyle &
-// BaseStyle`) wrongly rejected valid props such as `$active: { color }`. Guarded by
-// tests/ui-types.test.ts.
+/** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
+ *  from code via the `el.class` proxy; `duration`/`delay` animate the swap. Class state INHERITS
+ *  down the tree (CSS-`.dark`-on-body style): a class set on a node also activates same-name `$`
+ *  blocks on all descendants within the same root (docs/style-class-cascade-plan.md).
+ *  `$pressed`/`$focused` are reserved — hosts toggle them on press/focus (they beat other
+ *  classes, lose to onPressed/onFocused), so children can react to an ancestor's press.
+ *
+ *  Instantiated with the node's FULL style `T` — a class block accepts everything the node's
+ *  `.style()` does, like `onLandscape`. Narrowing it wrongly rejects valid props such as
+ *  `$active: { color }`; guarded by tests/ui-types.test.ts. */
 export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number } }
 
 /** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
@@ -351,15 +362,46 @@ export type ClassValue = boolean | (() => boolean)
  *  single-key writes are runtime-coerced with `!!`. */
 export type Classes<R> = ((classes: Record<string, ClassValue>) => R) & { [key: string]: any }
 
-// NB: do NOT annotate `this: R` here. `this` is a parameter position, so it makes R contravariant,
-// which makes every node type INVARIANT in its own type params (and in `this`). That is what made
-// `UIScreen<false>` unassignable to `UIScreen<boolean>` (a navigator page), and would block any
-// UINode subtype from being assignable to its base. Runtime `this` is already fixed by the
-// `styleFunction.bind(this)` in the `style` getter — the annotation bought nothing and cost variance.
-// R stays only in the (covariant) return, so `.style()` still returns the concrete node type for
-// chaining. Guarded by the type tests in tests/ui-types.test-d.ts.
-// 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.
+/** 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. */
 export type OrientationStyles<T> = {
   onLandscape?: T,
   onPortrait?: T,
@@ -368,11 +410,19 @@ export type OrientationStyles<T> = {
   onPortait?: T,
 }
 
+// NB: do NOT annotate `this: R` on StyleFn. As a parameter it makes R contravariant, turning every
+// node type INVARIANT (UIScreen<false> stopped being assignable to UIScreen<boolean>). Runtime
+// `this` is already fixed by `styleFunction.bind(this)`; R stays covariant in the return, so
+// `.style()` still chains. Guarded by tests/ui-types.test-d.ts.
 export type StyleFn <R, T extends object> = ((style: Reactive<T> & OrientationStyles<T> & ClassStyles<T>) => R)
+
+/** The `el.style` surface: callable — `.style({...})` merges and returns the element for
+ *  chaining — and per-key readable/writable (`el.style.opacity = 0.5`; a `() => value` write
+ *  installs a reactive binding). */
 export type Style <R, T extends object> = StyleFn<R,T> & T & OrientationStyles<T> & ClassStyles<T>
 
-// The options bag of animateTo/animateFrom: the target style plus flat meta keys. Meta keys are
-// stripped before the commit into _style and skipped by the hosts' style staging.
+/** The `animateTo`/`animateFrom` surface: target style props plus the flat meta keys below
+ *  (stripped before the commit into the element's style). */
 export type AnimateStyle<R, T extends object> = ((style: T & {
   /** Tween length in **milliseconds** (default 225). */
   duration?: number,
@@ -397,10 +447,11 @@ const ANIMATE_META = new Set(["duration", "delay", "layer", "commit", "loop", "l
 export type AppearStyle <R, T> = (arg: { from: T, duration?: number, delay?: number }) => R
 export type DisappearStyle <R, T> = (arg: { to: T, duration?: number, delay?: number }) => R
 
+/** `onLayout` payload — the node's box in PARENT-relative coordinates. */
 export type OnLayoutCallback = (layout: { left: number, top: number, width: number, height: number }) => void
 
-// Web-DOMRect shape on purpose (getBoundingClientRect priors must hold): all eight fields, with
-// right/bottom/x/y derived SDK-side so hosts only report [left, top, width, height].
+/** Web-DOMRect shape on purpose (getBoundingClientRect priors must hold): all eight fields, with
+ *  right/bottom/x/y derived SDK-side — hosts only report [left, top, width, height]. */
 export type BoundingClientRect = {
   x: number, y: number,
   left: number, top: number, right: number, bottom: number,
@@ -462,10 +513,10 @@ export class Element<T extends string> {
     return proxy
   }
 
+  /** Tween to the target style and commit it (unless `commit: false` or looping — a loop is an
+   *  effect, not a state change). Meta keys: `duration`/`delay`/`loop`/… — see {@link AnimateStyle}. */
   animateTo(style: any): this{
     _creatorUI.animateTo(this._id, style)
-    // A loop is an effect, not a state change — looping animations never commit. Meta keys
-    // (duration/delay/…) stay out of the stored style.
     if (style.commit !== false && !style.loop) {
       for (const key in style) {
         if (!ANIMATE_META.has(key)) this._style[key] = style[key]
@@ -473,6 +524,7 @@ export class Element<T extends string> {
     }
     return this
   }
+  /** Tween FROM the given style to the element's current one (entrance animations). */
   animateFrom(style: any): this{
     _creatorUI.animateFrom(this._id, style)
     return this
@@ -511,6 +563,7 @@ export class Element<T extends string> {
   }
 
   protected ll?: OnLayoutCallback[]
+  /** Observe layout: fires after every host layout pass with the parent-relative box. */
   onLayout(onLayout: OnLayoutCallback): this {
     if (this.ll) {
       this.ll.push(onLayout)
@@ -536,6 +589,8 @@ export class Element<T extends string> {
 
 // ---- reactive children --------------------------------------------------------------------------
 
+/** Reactive children: re-runs when a signal it read changes; the result is reconciled against
+ *  the mounted children (kept nodes stay mounted, state intact). */
 export type ChildrenFn = () => UINodeChild[]
 
 // The container whose children binding is currently executing. __uiMap uses it as the cache owner;
@@ -580,6 +635,53 @@ export function __uiMap(list: any, render: (item: any, index: number) => any, sl
   return out
 }
 
+// ---- factory argument dispatch ------------------------------------------------------------------
+
+/** @internal Shared argument dispatch for the UI factories (`UIRow(...)`, `UIButton(...)`, …).
+ *  Children are variadic; an array argument is flattened one level, so both the legacy
+ *  `UIColumn([a, b])` and `UIColumn(header, items.map(row), footer)` work. A lone function
+ *  argument is a reactive {@link ChildrenFn}. A plain non-node object in first position is the
+ *  legacy style bag: it is spread over `defaults`, or — when `defaults` is null — stored as-is
+ *  (the Element constructor mutates it in place, matching the old path). The rest-args array is
+ *  taken over as the children array when nothing needs flattening — callers must hand it off. */
+export function buildUI<R>(args: any[], defaults: any, make: (style: any, children: any[] | ChildrenFn) => R): R {
+  const n = args.length
+  const a0 = n > 0 ? args[0] : undefined
+  let style: any
+  let start = 0
+  if (a0 !== null && typeof a0 === "object" && !Array.isArray(a0) && !(a0 instanceof Element)) {
+    style = defaults ? { ...defaults, ...a0 } : a0
+    start = 1
+  } else {
+    style = defaults ? { ...defaults } : {}
+  }
+  if (n === start + 1) {
+    const a = args[start]
+    // lone function → reactive children; lone array → used as the children array directly
+    // (the legacy zero-copy path — nested arrays inside it are NOT flattened)
+    if (typeof a === "function" || Array.isArray(a)) return make(style, a)
+  }
+  // Single pass: reuse the rest-args array as the children array until the first array argument
+  // shows up, then copy the prefix once and flatten from there. Falsy entries stay — they are
+  // compacted at mount like always.
+  let flat: any[] | undefined
+  for (let i = start; i < n; i++) {
+    const a = args[i]
+    if (flat === undefined) {
+      if (Array.isArray(a)) {
+        flat = args.slice(start, i)
+        for (let j = 0; j < a.length; j++) flat.push(a[j])
+      }
+    } else if (Array.isArray(a)) {
+      for (let j = 0; j < a.length; j++) flat.push(a[j])
+    } else {
+      flat.push(a)
+    }
+  }
+  if (flat !== undefined) return make(style, flat)
+  return make(style, start === 0 ? args : args.slice(1))
+}
+
 export class ContainerElement<T extends string> extends Element<T> {
   children: any[] = []
 
@@ -641,6 +743,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     }
   }
 
+  /** Append children (falsy entries are kept in the array but never mounted). */
   append(...nodes: UINodeChild[]): this {
     if (this._id === 0) {
       this.children.push(...nodes)
@@ -660,6 +763,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     this.children.push(...nodes)
     return this
   }
+  /** Insert children at `index` of the children array. */
   insert(index: number, ...nodes: UINodeChild[]): this {
     if (this._id === 0) {
       this.children.splice(index, 0, ...nodes)
@@ -680,6 +784,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     this.children.splice(index, 0, ...nodes)
     return this
   }
+  /** Remove (unmount) the given children. */
   remove(...nodesToDelete: UINode[]): this {
     const set = new Set(nodesToDelete)
 
@@ -704,6 +809,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     return this
   }
   
+  /** Replace all children — a plain array, or a function for reactive children. */
   setContent(children: UINodeChild[] | ChildrenFn): this {
     if (typeof children === "function") {
       this._bindChildren(children)   // createBinding replaces a previous "#children" binding

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"> {
@@ -104,7 +93,10 @@ export class PagerElement extends ContainerElement<"pager"> {
   private ncl: ((depth: number) => void)[] = []   // onChange listeners
 
   constructor(style: UIPagerStyle | null, tabs: UIScreen[]) {
-    super("pager", style ?? {}, tabs as any)
+    // flexShrink: 1 default (SDK-owned, like UIScrollable's): pages are separate layout roots
+    // sized to the pager's box, so yoga sees no shrinkable content — without this a pager in a
+    // flex column overflows the screen instead of leaving room for the tab bar.
+    super("pager", { flexShrink: 1, ...style }, tabs as any)
     this._lens = tabs.map(() => 1)
     for (const s of this.children) this._track(s)
   }
@@ -294,13 +286,13 @@ const isScreenArg = (v: any): boolean => v != null && typeof v === "object" && v
 /** Callable factory + ambient statics. The name `UIPager` is a value (this factory) and a type
  *  (the instance interface above) — a standard value/type merge. */
 interface UIPagerConstructor {
-  /** One tab — a plain navigation stack rooted at `root` (push/pop, no tab swiping). */
-  (root: UIScreen): UIPager
-  /** Sibling tabs, one per screen, in order — swipe (or `select`) between them. Tabs are fixed
-   *  at construction; each starts as its own one-screen stack. */
-  (tabs: UIScreen[]): UIPager
-  /** Styled pager + content (a single root screen or an array of tab screens). */
-  (style: UIPagerStyle, content: UIScreen | UIScreen[]): UIPager
+  /** Tabs — each argument is a screen or an array of screens (arrays flatten one level, falsy
+   *  entries are skipped). One screen → a plain navigation stack rooted at it (push/pop, no tab
+   *  swiping); several → swipeable sibling tabs, fixed at construction, each starting as its own
+   *  one-screen stack. */
+  (...tabs: (UIScreen | UIScreen[] | false | null | undefined)[]): UIPager
+  /** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+  (style: UIPagerStyle, content?: UIScreen | UIScreen[]): UIPager
   /** The pager that owns the currently visible screen, or `null` when the visible screen isn't
    *  hosted by one. With pagers nested inside pages, resolves to the **innermost** — so ambient
    *  calls act on the pager the user is actually looking at. */
@@ -316,14 +308,23 @@ interface UIPagerConstructor {
 }
 
 function pagerFactory(...args: any[]): UIPager {
-  if (args.length === 1) {
-    const a = args[0]
-    if (Array.isArray(a)) return new PagerElement(null, a) as unknown as UIPager
-    if (isScreenArg(a)) return new PagerElement(null, [a]) as unknown as UIPager
-    return new PagerElement(a, []) as unknown as UIPager
+  let style: any = null
+  let start = 0
+  const a0 = args.length > 0 ? args[0] : undefined
+  if (a0 != null && typeof a0 === "object" && !Array.isArray(a0) && !isScreenArg(a0)) {
+    style = a0
+    start = 1
+  }
+  const tabs: any[] = []
+  for (let i = start; i < args.length; i++) {
+    const a = args[i]
+    if (Array.isArray(a)) {
+      for (let j = 0; j < a.length; j++) if (a[j]) tabs.push(a[j])
+    } else if (a) {
+      tabs.push(a)
+    }
   }
-  const content = args[1]
-  return new PagerElement(args[0] ?? null, Array.isArray(content) ? content : content ? [content] : []) as unknown as UIPager
+  return new PagerElement(style, tabs) as unknown as UIPager
 }
 
 /**

package/runtime/sdk/ui/UIPopover.ts

@@ -1,7 +1,7 @@
 import { ModalElement, type UIModal, type UIModalStyle } from "./UIModal"
 import { Presentable } from "./presentable"
 import { device } from "../runtime/device"
-import type { BoundingClientRect, ChildrenFn, UINodeChild } from "./UINode"
+import { buildUI, type BoundingClientRect, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
 
 export type UIPopoverStyle = UIModalStyle
 
@@ -87,20 +87,14 @@ export class PopoverElement extends ModalElement {
   }
 }
 
-export function UIPopover(): UIPopover;
+const makePopover = (style: any, children: any) => new PopoverElement(style, children)
+
+/** Create an anchored popover (see {@link UIPopover}) — create once at module scope, then
+ *  `show(anchor)` next to an element or `{x, y}` point. Same argument forms as `UIColumn`. */
+export function UIPopover(...children: UIChildArg[]): 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])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIPopover(style: UIPopoverStyle, children?: UINodeChild[] | ChildrenFn): UIPopover;
+export function UIPopover(...args: any[]): UIPopover {
+  return buildUI(args, null, makePopover)
 }

package/runtime/sdk/ui/UIScreen.ts

@@ -1,35 +1,28 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { ContainerElement, type AnimateStyle, type BaseStyle, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, 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
 
-// A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
-// 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`) — see docs/scroll-forms-plan.md (the former
-// `makeScrollable()` screen mode was removed 2026-07-22).
-export interface UIScreen {
+/** A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
+ *  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 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
 
+  /** The screen became the visible destination (first open, or revealed by a pop). */
   onOpen(callback: () => void): this
+  /** The screen stopped being visible — closed, replaced, or covered by a push. */
   onClose(callback: () => void): this
 
   /**
@@ -43,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,
 }
 
@@ -121,20 +107,17 @@ export class ScreenElement extends ContainerElement<"screen"> {
   }
 }
 
-export function UIScreen(): UIScreen;
+const makeScreen = (style: any, children: any) => new ScreenElement("screen", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
+export const __UIScreen = (children: UINodeChild[] | ChildrenFn): UIScreen => makeScreen({}, children)
+
+/** Create a screen. Present it with `.open()`, or via `Router` / `UIPager`. Same argument forms
+ *  as `UIColumn`. */
+export function UIScreen(...children: UIChildArg[]): UIScreen;
 export function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen;
-export function UIScreen(style: UIScreenStyle): UIScreen;
-export function UIScreen(style: UIScreenStyle, children: UINodeChild[]): UIScreen;
-export function UIScreen(...args: [] | [UINodeChild[] | ChildrenFn | UIScreenStyle] | [UIScreenStyle, children: UINodeChild[] | ChildrenFn]): UIScreen {
-  if (args.length === 0) {
-    return new ScreenElement("screen", {}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ScreenElement("screen", {}, args[0])
-    } else {
-      return new ScreenElement("screen", args[0], [])
-    }
-  } else {
-    return new ScreenElement("screen", args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIScreen(style: UIScreenStyle, children?: UINodeChild[] | ChildrenFn): UIScreen;
+export function UIScreen(...args: any[]): UIScreen {
+  return buildUI(args, null, makeScreen)
 }