lecodes-sdk 0.19.0

package/dist/types/server/db/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Type layer: projects a `defineDb({ User: model({...}), … })` literal into marcidb's generic query
+ * types (./marci/query.ts — vendored from marcidb, see scripts/sync-marcidb.ts): each model becomes the
+ * `ModelTypes` bag marcidb's codegen would have emitted, and `db.<model>` is marcidb's own `Query<T>`.
+ * Everything here is type-only; the runtime lives in ./defineDb.ts.
+ *
+ * Naming: `S` = the schema record (model name → Model), `N` = a model name, `F` = a fields record.
+ */
+import type { Field, FieldMeta } from "./fields";
+import type { CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearchValue, FullTextSearch, JsonCondition, JsonPathWhere, Op, PrimitiveListUpdate, Query as MarciQuery, RefListUpdate, RefListUpdateOrdered, RefUpdate, RefUpdateStruct, Rows, Sub, UpdateNumValue, VectorSearch, WhereValue } from "./marci/query";
+export type Fields = Record<string, Field<any, any>>;
+export type Model<F extends Fields = Fields> = {
+    readonly fields: F;
+    readonly __model: true;
+};
+export type Schema = Record<string, Model<any>>;
+export type FieldsOf<M> = M extends Model<infer F> ? F : never;
+type TsOf<Fld> = Fld extends Field<infer T, any> ? T : never;
+type StructFieldsOf<Fld> = TsOf<Fld> extends Fields ? TsOf<Fld> : never;
+type MetaOf<Fld> = Fld extends Field<any, infer M> ? M : never;
+type ModelName<S, Fld> = MetaOf<Fld>["model"] & keyof S & string;
+type Nullable<M extends FieldMeta, T> = M["optional"] extends true ? T | null : T;
+type Arr<M extends FieldMeta, T> = M["array"] extends true ? T[] : T;
+type IsNum<M extends FieldMeta> = M["scalar"] extends "int" | "float" | "date" ? true : false;
+/** Explicit `.id()` fields, or a field literally named `id`. */
+type IdKeys<F extends Fields> = {
+    [K in keyof F]: MetaOf<F[K]>["isId"] extends true ? K : K extends "id" ? K : never;
+}[keyof F];
+type IdValue<S, Fld> = MetaOf<Fld>["kind"] extends "one" ? Id<S, ModelName<S, Fld>> : TsOf<Fld>;
+/** The id object of a model: `{ id: number }` implicitly, or the declared key fields. */
+export type Id<S, N extends keyof S> = [
+    IdKeys<FieldsOf<S[N]>>
+] extends [never] ? {
+    id: number;
+} : {
+    [K in IdKeys<FieldsOf<S[N]>>]: IdValue<S, FieldsOf<S[N]>[K]>;
+};
+/** What `update`/`delete` accept: the id object, or the bare value when the key is a single scalar. */
+export type IdArg<S, N extends keyof S> = Id<S, N> | (Id<S, N> extends {
+    id: infer V;
+} ? V : never);
+type FieldRow<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? Nullable<M, Row<S, ModelName<S, Fld>>> : M["kind"] extends "many" | "list" ? Row<S, ModelName<S, Fld>>[] : M["kind"] extends "struct" ? Nullable<M, StructRow<S, StructFieldsOf<Fld>>> : Nullable<M, Arr<M, TsOf<Fld>>>;
+/** Full row type of a model (relations included) — the `TModel` marcidb's `GetResult` selects from. */
+export type Row<S, N extends keyof S> = Id<S, N> & {
+    [K in Exclude<keyof FieldsOf<S[N]>, IdKeys<FieldsOf<S[N]>>>]: FieldRow<S, FieldsOf<S[N]>[K]>;
+};
+type StructRow<S, F extends Fields> = {
+    [K in keyof F]: FieldRow<S, F[K]>;
+};
+type ScalarKeys<F extends Fields> = {
+    [K in keyof F]: MetaOf<F[K]>["kind"] extends "scalar" | "enum" | "json" ? K : never;
+}[keyof F];
+type NumKeys<F extends Fields> = {
+    [K in keyof F]: IsNum<MetaOf<F[K]>> extends true ? (MetaOf<F[K]>["array"] extends true ? never : K) : never;
+}[keyof F];
+/** What an empty select returns: id + every scalar field. */
+export type Scalars<S, N extends keyof S> = Pick<Row<S, N>, (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>>;
+/** The same, as the `{ field: true }` select shape a query starts with. */
+export type ScalarSelect<S, N extends keyof S> = {
+    [K in (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>]: true;
+};
+type FieldInsert<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? Nullable<M, Id<S, ModelName<S, Fld>>> : M["kind"] extends "many" | "list" ? Id<S, ModelName<S, Fld>>[] : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>>> : Nullable<M, Arr<M, TsOf<Fld>>>;
+type RequiredKeys<F extends Fields> = {
+    [K in keyof F]: K extends IdKeys<F> ? never : MetaOf<F[K]>["optional"] extends true ? never : MetaOf<F[K]>["hasDefault"] extends true ? never : MetaOf<F[K]>["kind"] extends "many" | "list" ? never : K;
+}[keyof F];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type InsertOf<S, F extends Fields> = Simplify<{
+    [K in RequiredKeys<F>]: FieldInsert<S, F[K]>;
+} & {
+    [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K]>;
+}>;
+export type Insert<S, N extends keyof S> = InsertOf<S, FieldsOf<S[N]>>;
+type StructInsert<S, F extends Fields> = InsertOf<S, F>;
+type FieldUpdate<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? Nullable<M, RefUpdate<Id<S, ModelName<S, Fld>>>> : M["kind"] extends "many" ? RefListUpdate<Id<S, ModelName<S, Fld>>> : M["kind"] extends "list" ? RefListUpdateOrdered<Id<S, ModelName<S, Fld>>> : M["kind"] extends "struct" ? RefUpdateStruct<StructInsert<S, StructFieldsOf<Fld>>, UpdateOf<S, StructFieldsOf<Fld>>> | null : M["array"] extends true ? TsOf<Fld>[] | PrimitiveListUpdate<TsOf<Fld>> : Nullable<M, TsOf<Fld> | (IsNum<M> extends true ? UpdateNumValue : never)>;
+type UpdateOf<S, F extends Fields> = {
+    [K in Exclude<keyof F, IdKeys<F>>]?: FieldUpdate<S, F[K]>;
+};
+export type Update<S, N extends keyof S> = UpdateOf<S, FieldsOf<S[N]>>;
+type FieldSelect<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? Select<S, ModelName<S, Fld>> | boolean | Sub<ModelName<S, Fld>> : M["kind"] extends "many" | "list" ? QueryObject<S, ModelName<S, Fld>> | AggregateQuery<S, ModelName<S, Fld>> | boolean | Sub<ModelName<S, Fld>> : M["kind"] extends "struct" ? StructSelect<S, StructFieldsOf<Fld>> | boolean : boolean;
+export type Select<S, N extends keyof S> = {
+    [K in keyof Row<S, N>]?: K extends keyof FieldsOf<S[N]> ? FieldSelect<S, FieldsOf<S[N]>[K]> : boolean;
+};
+type StructSelect<S, F extends Fields> = {
+    [K in keyof F]?: FieldSelect<S, F[K]>;
+};
+type ScalarWhere<T, M extends FieldMeta> = Nullable<M, CompareValue<T>> | (IsNum<M> extends true ? CompareNumValue<T> : M["scalar"] extends "string" ? CompareStrValue<T> : never);
+type FieldWhere<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? CompareRefValue<Where<S, ModelName<S, Fld>> | null> : M["kind"] extends "many" | "list" ? CompareRefListValue<Where<S, ModelName<S, Fld>>> : M["kind"] extends "struct" ? CompareRefValue<WhereValue<StructWhereFields<S, StructFieldsOf<Fld>>> | null> : M["kind"] extends "json" ? JsonPathWhere | JsonCondition : M["array"] extends true ? CompareValue<TsOf<Fld>> : ScalarWhere<TsOf<Fld>, M> | CustomSearchValue<FullTextSearch> | CustomSearchValue<VectorSearch>;
+type WhereFieldsOf<S, F extends Fields> = {
+    [K in keyof F]?: FieldWhere<S, F[K]>;
+};
+type IdWhere<S, N extends keyof S> = {
+    [K in keyof Id<S, N> as K extends keyof FieldsOf<S[N]> ? never : K]?: CompareValue<Id<S, N>[K]> | CompareNumValue<number>;
+};
+export type Where<S, N extends keyof S> = WhereValue<WhereFieldsOf<S, FieldsOf<S[N]>> & IdWhere<S, N>>;
+type StructWhereFields<S, F extends Fields> = WhereFieldsOf<S, F>;
+export type Order<S, N extends keyof S> = {
+    [K in (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>]?: "asc" | "desc";
+};
+/** The query object — marcidb's wire form: a select shape plus the `$`-clauses. */
+export type QueryObject<S, N extends keyof S> = Select<S, N> & {
+    $where?: Where<S, N>;
+    $order?: Order<S, N>;
+    $limit?: number;
+    $skip?: number;
+    $cursor?: Id<S, N>;
+};
+export type AggregateQuery<S, N extends keyof S> = {
+    $where?: Where<S, N>;
+    $count?: true;
+    $sum?: NumKeys<FieldsOf<S[N]>> & string;
+    $avg?: NumKeys<FieldsOf<S[N]>> & string;
+    $min?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string;
+    $max?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string;
+};
+/** The per-model type bag marcidb's generic `Query<T>` is parametrised by (what its codegen emits as `UserTypes`). */
+export type Types<S, N extends keyof S> = {
+    name: N & string;
+    model: Row<S, N>;
+    id: Id<S, N>;
+    scalars: ScalarSelect<S, N>;
+    select: Select<S, N>;
+    query: QueryObject<S, N>;
+    where: Where<S, N>;
+    order: Order<S, N>;
+    insert: Insert<S, N>;
+    update: Update<S, N>;
+    aggregate: AggregateQuery<S, N>;
+    reindex: false;
+};
+/**
+ * `db.<model>` — marcidb's lazy, immutable query over one model: clauses (`where/order/limit/skip/after`)
+ * return a new query, `select(shape)` sets the projection, `await` runs it, `first/count/aggregate` terminate,
+ * `updateMany(data)`/`deleteMany()` write through the chain's `where`; a query placed in another query's
+ * select is a sub-query. `Sel` is the projection: id + scalars until `select(...)` sets a shape.
+ */
+export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>> = MarciQuery<Types<S, N>, Sel>;
+/** The rows a query with projection `Q` resolves to (no field keys = id + scalars; sub-queries resolved). */
+export type Result<S, N extends keyof S, Q> = Rows<Types<S, N>, Q>;
+/** `db.<model>` — the root query of a model. */
+export type Collection<S, N extends keyof S> = Query<S, N>;
+export type Db<S extends Schema> = {
+    [N in keyof S & string as Uncapitalize<N>]: Query<S, N>;
+} & {
+    /** Atomic batch: all ops commit or none. `ref("0.id")` feeds a generated id into a later op. */
+    $transaction<P extends readonly Op<any>[]>(ops: [...P]): Promise<{
+        [K in keyof P]: P[K] extends Op<infer T> ? T : never;
+    }>;
+    /** The `.marci` schema text this db syncs with. */
+    readonly $schema: string;
+};
+type RelKinds = "one" | "many" | "list";
+type CheckField<S, Fld> = MetaOf<Fld>["kind"] extends RelKinds ? MetaOf<Fld>["model"] extends keyof S ? Fld : `Unknown model "${MetaOf<Fld>["model"]}" — not a key of defineDb({...})` : Fld;
+/** Intersected with `S` in `defineDb`'s parameter: an unknown relation target fails to type-check on that field. */
+export type ValidateRefs<S extends Schema> = {
+    [N in keyof S]: {
+        readonly fields: {
+            [K in keyof FieldsOf<S[N]>]: CheckField<S, FieldsOf<S[N]>[K]>;
+        };
+    };
+};
+export {};

package/dist/types/server/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `throw new ApiError(404, "Not found")` inside an endpoint → the client's promise rejects with the
+ * same status + message. Any other throw is a 500 (message hidden, logged to the server console).
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message?: string);
+}

package/dist/types/server/inject.d.ts

@@ -0,0 +1,5 @@
+export { t, model, defineDb, ref } from "./db";
+export { ApiError } from "./errors";
+export { channel } from "./channel";
+export { request } from "./context";
+export { auth } from "./auth/global";

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

@@ -0,0 +1,38 @@
+import { type PresentOptions } from "./presentable";
+import { type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode";
+export type UINativeViewStyle = ElementStyle & DrawableStyle;
+/** An instance of a host-registered platform view (map, QR scanner, camera preview, …) —
+ *  embeddable among a screen's children AND fullscreen-presentable (`open()`); one instance lives
+ *  in one place at a time. Talk to it via the `call`/`on` channel. */
+export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableStyle & BaseStyle> {
+    readonly type: "native";
+    /** The registered view kind this instance resolves to (the `registerView` name). */
+    readonly viewName: string;
+    /** Creation params, passed to the host factory (JSON-serializable). */
+    readonly params: any;
+    /** Show fullscreen as the current destination (see Presentable). */
+    open(options?: PresentOptions): void;
+    /** Dismiss if this is the visible destination. */
+    close(): void;
+    /** Became the visible destination. */
+    onOpen(callback: () => void): this;
+    /** Stopped being the visible destination. */
+    onClose(callback: () => void): this;
+    /** Hardware/system back while current. */
+    onBackPressed(callback: () => void): this;
+    /** Invoke a method on the native view (`map.call("setCenter", [lng, lat])`). Args and the
+     *  result are JSON-serialized. Rejects if the host has no such view/method. */
+    call(method: string, ...args: any[]): Promise<any>;
+    /** Subscribe to an event the native view emits (`map.on("markerTap", cb)`). */
+    on(event: string, callback: (data?: any) => void): this;
+    off(event: string, callback: (data?: any) => void): this;
+}
+/**
+ * Create an instance of a host-registered platform view. `NativeView.isSupported(name)` reports
+ * whether this host registered a factory for it. Style via the chained `.style()`.
+ */
+export declare const NativeView: {
+    (name: string, params?: object): NativeView;
+    /** Whether this host registered a `registerView` factory under `name`. */
+    isSupported(name: string): boolean;
+};

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

@@ -0,0 +1,27 @@
+export { UIButton, type UIButtonStyle } from './UIButton';
+export { UIScreen, type UIScreenStyle } from './UIScreen';
+export { UISpacer, type UISpacerStyle } from './UISpacer';
+export { UIText, type UITextStyle } from './UIText';
+export { registerFont } from './fonts';
+export { UIImage, type UIImageStyle } from './UIImage';
+export { UIVideo, type UIVideoStyle } from './UIVideo';
+export { UIInput, UITextArea, type UIInputStyle } from './UIInput';
+export { UIWidget, type UIWidgetStyle } from './UIWidget';
+export { UIModal, type UIModalStyle } from './UIModal';
+export { UIBottomSheet, type UIBottomSheetStyle } from './UIBottomSheet';
+export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopover';
+export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer';
+export { UIScrollable, type UIScrollableStyle } from './UIScrollable';
+export { UIPager, type UIPagerStyle } from './UIPager';
+export { UITabs, type UITabDef, defineTabs, type TabDef, type TabsHandle } from './UITabs';
+export { UIVirtualizedList } from './UIVirtualizedList';
+export { Router } from './router';
+export { NativeView, type UINativeViewStyle } from './NativeView';
+export { Presentable } from './presentable';
+export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from './presentable';
+export { __uiMap } from './UINode';
+export { __UIColumn, __UIRow, __UIBox } from './UIContainer';
+export { __UIButton } from './UIButton';
+export { __UIScreen } from './UIScreen';
+export { __UIScrollable } from './UIScrollable';
+export { __UIWidget } from './UIWidget';

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

@@ -0,0 +1,71 @@
+import { ModalElement, type UIModalStyle } from "./UIModal";
+import type { UIWidget } from "./UIWidget";
+import { type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode";
+export type UIBottomSheetStyle = UIModalStyle;
+/**
+ * A bottom sheet: a `UIWidget` pinned to the bottom edge. By default it is **content-sized** —
+ * as tall as what's inside (capped at the screen), one position, drag down to dismiss (the
+ * action-sheet shape). Call `detents()` for the multi-position map-app model instead: snap
+ * positions the user drags between on native hosts. Ships as a widget node on the wire (no new
+ * node type — docs/bottom-sheet-plan.md): hosts without sheet support show a static bottom panel.
+ *
+ * With detents, content lays out at the HIGHEST detent's size; lower detents show the top
+ * slice. The scrim, `onOpen`/`onClose`, back-button and scrim-tap dismissal all come from the
+ * modal machinery.
+ *
+ * ```ts
+ * const actions = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [rows])   // content-sized
+ *
+ * const mapSheet = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [results])
+ *   .detents([0.3, 0.6, 1])
+ *   .onDetentChange(i => map.setPadding(...))
+ * ```
+ */
+export interface UIBottomSheet extends UIWidget {
+    /** Snap positions as fractions of screen height, ascending. Also sizes the sheet: its box is
+     *  the last (highest) detent; set this before `show()`. Without a `detents()` call the sheet
+     *  is CONTENT-SIZED instead — one position, as tall as its children (up to the screen). */
+    detents(list: number[]): this;
+    /** Snap to a detent (animated). Clamped to the detents range; fires `onDetentChange`. */
+    setDetent(index: number): void;
+    /** Current detent index. */
+    readonly detent: number;
+    /** Fires on every settle: a finger snap on native hosts, or a `setDetent()` call. */
+    onDetentChange(callback: (index: number) => void): this;
+    /** Mount and slide in to the current detent. No-op while already open. */
+    show(): void;
+    /** Slide out, fade the scrim, then unmount. No-op while closed. */
+    hide(): void;
+    /** True from `show()` until `hide()` starts. */
+    readonly isOpen: boolean;
+    /** Called when `show()` mounts the sheet. */
+    onOpen(callback: () => void): this;
+    /** Called when the sheet starts closing — scrim tap, back button, drag-dismiss, or `hide()`. */
+    onClose(callback: () => void): this;
+    /** `dismissible(false)`: scrim taps, the back button and dragging below the lowest detent no
+     *  longer close the sheet (a drag collapses to the lowest detent instead). Default `true`. */
+    dismissible(enabled: boolean): this;
+}
+export declare class BottomSheetElement extends ModalElement {
+    _detents: number[];
+    _detent: number;
+    /** Host-facing (the `sl`/`otl` contract): hosts read `dtl` at mount and call it with the
+     *  settled detent index for GESTURE settles only — programmatic `setDetent` fires JS-side.
+     *  `-1` = dragged below the lowest detent while dismissible. */
+    readonly dtl: any[];
+    readonly _detentListeners: ((index: number) => void)[];
+    constructor(style: UIBottomSheetStyle, children: UINodeChild[] | ChildrenFn);
+    detents(list: number[]): this;
+    get detent(): number;
+    setDetent(index: number): void;
+    onDetentChange(callback: (index: number) => void): this;
+    show(): void;
+    hide(): void;
+    dismissible(enabled: boolean): this;
+}
+/** Create a bottom sheet (see {@link UIBottomSheet}) — content-sized by default; call
+ *  `.detents([...])` for snap positions. Same argument forms as `UIColumn`. */
+export declare function UIBottomSheet(...children: UIChildArg[]): UIBottomSheet;
+export declare function UIBottomSheet(children: UINodeChild[] | ChildrenFn): UIBottomSheet;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIBottomSheet(style: UIBottomSheetStyle, children?: UINodeChild[] | ChildrenFn): UIBottomSheet;

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

@@ -0,0 +1,30 @@
+import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType } from "../runtime/touch";
+import { type ElementStyle, type ContainerStyle, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode";
+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;
+    };
+}, DrawableStyle & BaseStyle> {
+    readonly type: "button";
+    /** Fired on a completed tap/click. */
+    onClick(callback: (ev: ClickEventType<UIButton>) => void): this;
+    /** Fired when a touch begins; `ev.track(...)` takes over the rest of the gesture (dragging). */
+    onTouchStart(callback: (ev: TouchStartEventType<UIButton>) => void): this;
+    /** Fired when a finger is held on the button past the long-press threshold. The event can
+     *  `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;
+    /** Is a finger currently down on the button? */
+    isPressed(): boolean;
+}
+/** Create a button (row + centered by default — the icon+label shape). Same argument forms as
+ *  `UIColumn`; attach behavior with `.onClick(...)`. */
+export declare function UIButton(...children: UIChildArg[]): UIButton;
+export declare function UIButton(children: UINodeChild[] | ChildrenFn): UIButton;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIButton(style: UIButtonStyle, children?: UINodeChild[] | ChildrenFn): UIButton;

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

@@ -0,0 +1,33 @@
+import { type ChildrenFn, type ContainerStyle, type DrawableStyle, type ElementStyle, type UIChildArg, type UIContainerBase, type UINodeChild } from "./UINode";
+export type UIContainerStyle = ElementStyle & DrawableStyle & ContainerStyle;
+/** A vertical flex container — children stack top to bottom. */
+export interface UIColumn extends UIContainerBase<UIContainerStyle> {
+    readonly type: "column";
+}
+export declare const __UIRow: (children: UINodeChild[] | ChildrenFn) => UIRow;
+export declare const __UIBox: (children: UINodeChild[] | ChildrenFn) => UIBox;
+/** Create a vertical flex container. Children are variadic — arrays flatten one level, falsy
+ *  entries are skipped; a lone function makes the children reactive. */
+export declare function UIColumn(...children: UIChildArg[]): UIColumn;
+export declare function UIColumn(children: UINodeChild[] | ChildrenFn): UIColumn;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIColumn(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIColumn;
+/** A horizontal flex container — children flow left to right. */
+export interface UIRow extends UIContainerBase<UIContainerStyle> {
+    readonly type: "row";
+}
+/** Create a horizontal flex container (same argument forms as `UIColumn`). */
+export declare function UIRow(...children: UIChildArg[]): UIRow;
+export declare function UIRow(children: UINodeChild[] | ChildrenFn): UIRow;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIRow(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIRow;
+/** A centering container — `justifyContent`/`alignItems` default to center. */
+export interface UIBox extends UIContainerBase<UIContainerStyle> {
+    readonly type: "box";
+}
+/** Create a centering container — children are centered on both axes by default (icon badges,
+ *  avatars, empty states). Same argument forms as `UIColumn`. */
+export declare function UIBox(...children: UIChildArg[]): UIBox;
+export declare function UIBox(children: UINodeChild[] | ChildrenFn): UIBox;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIBox(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIBox;

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

@@ -0,0 +1,35 @@
+import type { FetchResponse } from "../runtime/fetch";
+import type { SvgSourceValue as SvgSource } from "../runtime/misc";
+import type { File } from "../runtime/fetch";
+import { Canvas } from "../canvas/Canvas";
+import { type Color, type ElementStyle, type UIElementBase } from "./UINode";
+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"). */
+export type CanvasImageSource = {
+    canvasSurface: number;
+};
+/** Accepted image sources. A Canvas is baked to a surface marker on assign. */
+export type ImageSource = string | FetchResponse | File | SvgSource | Canvas;
+/** The stored/resolved image source (a Canvas is resolved to a surface marker). */
+export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource;
+/** An image element. Sources: URL / `asset(...)`, fetch response / File, an SVG source
+ *  (`assetIcon`), or a live Canvas (`canvas.update()` refreshes the node in place). */
+export interface UIImage extends UIElementBase<UIImageStyle> {
+    readonly type: "image";
+    /** The image source — writable to swap the picture in place. */
+    get src(): ResolvedImageSource;
+    set src(value: ImageSource);
+    /** Render only a sub-rectangle of the source texture (texture pixels) — the atlas/spritesheet
+     *  primitive: crop once, then swap the rect per frame for sprite animation. The rect's w/h
+     *  become the node's intrinsic size and override `objectFit` — the cropped frame fills the box. */
+    setSourceRect(x: number, y: number, w: number, h: number): this;
+}
+/** Create an image element from a source (see {@link ImageSource}). */
+export declare function UIImage(src: ImageSource): UIImage;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIImage(style: UIImageStyle, src: ImageSource): UIImage;

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

@@ -0,0 +1,110 @@
+import { type ElementStyle, type DrawableStyle, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
+type InputStyle = {
+    placeholder?: string;
+    placeholderColor?: Color;
+    /**
+     * Keyboard hint, NOT a validator — `number` does not block pasted letters; validate in your own
+     * onChange. The phone-pad value is `phone` (LeCodes has no `tel`).
+     *
+     * `date` / `time` are PICKER kinds, not keyboards: the host opens its native picker in the
+     * keyboard slot (iOS wheels / browser calendar) and free typing is disabled. `value` is always
+     * canonical — `YYYY-MM-DD` for `date`, `HH:MM` (24h) for `time` — while the field displays a
+     * localized string; set/compare values in the canonical form only.
+     */
+    type?: "text" | "password" | "search" | "phone" | "email" | "number" | "decimal" | "url" | "date" | "time";
+    /**
+     * What the layout does while the keyboard is up (decided by the FOCUSED input). `true` (default):
+     * the layout viewport shrinks to the area above the keyboard — one relayout. `false`: the keyboard
+     * overlays the UI with NO layout recalculation — for chat composers that manage their own inset
+     * (pair with `app.keyboardHeight` / the app `"keyboard"` event) and full-screen canvases where a
+     * reflow is worse than overlap.
+     */
+    keyboardShrink?: boolean;
+    /**
+     * Whether a tap on a non-interactive area dismisses the keyboard while THIS input is focused
+     * (like `keyboardShrink`, the policy of the focused input). `true` (default): tapping dead
+     * space blurs — but a tap on a button or another input NEVER dismisses; the control acts and
+     * focus stays. `false`: taps never dismiss — the chat-composer policy. `blur()`, the return
+     * key (per `enterKey`), and the platform's own gestures (iOS drag-down over the keyboard)
+     * still work in both modes. Scrolling never dismisses the keyboard on any setting.
+     */
+    keyboardDismiss?: boolean;
+    /** Hard cap on the text length — enforced by the host while typing/pasting. */
+    maxLength?: number;
+    /** Auto-capitalization hint; omitted = platform default. */
+    autocapitalize?: "none" | "words" | "sentences" | "characters";
+    /** Enable/disable the platform autocorrection & suggestions; omitted = platform default. */
+    autocorrect?: boolean;
+};
+export type UIInputStyle = ElementStyle & DrawableStyle & TextStyle & InputStyle;
+/** UIInput-only (a UITextArea's Enter is a newline, period): the return-key label. */
+type SubmitStyle = {
+    /**
+     * Return-key label. On submit the keyboard dismisses UNLESS `enterKey` is `"next"` — then the
+     * app is expected to call `otherInput.focus()` from `onSubmit`, so the keyboard never blinks.
+     */
+    enterKey?: "done" | "go" | "next" | "search" | "send";
+};
+/** 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;
+    };
+}, 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).
+     */
+    value: string;
+    /** The text changed — fires on every user edit. */
+    onChange(callback: (value: string) => void): UIInput;
+    /** Gained focus (keyboard opens). */
+    onFocus(callback: () => void): UIInput;
+    /** Lost focus. */
+    onBlur(callback: () => void): UIInput;
+    /** 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(): 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;
+    };
+}, DrawableStyle & BaseStyle> {
+    readonly type: "textarea";
+    /** The field's text — same contract as {@link UIInput.value}: settable before mount to pre-fill. */
+    value: string;
+    /** The text changed — fires on every user edit. */
+    onChange(callback: (value: string) => void): UITextArea;
+    /** Gained focus (keyboard opens). */
+    onFocus(callback: () => void): UITextArea;
+    /** Lost focus. */
+    onBlur(callback: () => void): UITextArea;
+    /** Focus the text area (opens the keyboard). No-op before mount. */
+    focus(): void;
+    /** Release focus (dismisses the keyboard when this text area held it). */
+    blur(): void;
+}
+/** Create a single-line text input. Read/write the text via `.value`, listen with
+ *  `onChange`/`onSubmit`; style keys `placeholder`, `type`, `enterKey`, … configure it. */
+export declare function UIInput(): UIInput;
+export declare function UIInput(style: UIInputStyle): UIInput;
+/**
+ * Multi-line text field. Enter is a newline (submit lives on UIInput / your own button).
+ *
+ * Auto-grow: with no explicit `height` the field measures its own content and grows line by
+ * line — clamp the range with `minHeight` / `maxHeight` (past `maxHeight` the text scrolls
+ * inside). A fixed `height` opts out and scrolls internally from the start. Chat composers are
+ * the canonical use: a bare textarea in a padded pill, `maxHeight` at ~5 lines.
+ */
+export declare function UITextArea(): UITextArea;
+export declare function UITextArea(style: UIInputStyle): UITextArea;
+export {};

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

@@ -0,0 +1,70 @@
+import { type UIWidget, type UIWidgetStyle, WidgetElement } from "./UIWidget";
+import { type BaseStyle, type ChildrenFn, type Color, type DrawableStyle, type UIChildArg, type UINodeChild } from "./UINode";
+export type UIModalStyle = UIWidgetStyle;
+/**
+ * The modal's hidden pose: `show()` animates from it, `hide()` animates to it. `duration` (ms)
+ * applies to both directions.
+ */
+export type UIModalTransition = DrawableStyle & BaseStyle & {
+    overlayColor?: Color | null;
+    duration?: number;
+};
+/**
+ * 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.
+ */
+export interface UIModal extends UIWidget {
+    /** Mount as an overlay 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. */
+    hide(): void;
+    /** True from `show()` until `hide()` starts (already false during the exit animation). */
+    readonly isOpen: boolean;
+    /**
+     * Replace the show/hide animation. `hidden` is the off-screen pose — `show()` animates from
+     * it, `hide()` animates to it. Default `{ opacity: 0, duration: 200 }` (a fade); the pose
+     * replaces it wholesale, so a slide without a fade is just the slide. The scrim keeps its own
+     * fade unless the pose sets `overlayColor` itself.
+     *
+     * ```ts
+     * sheet.transition({ transform: "translateY(480px)", duration: 250 })   // bottom sheet
+     * ```
+     */
+    transition(hidden: UIModalTransition): this;
+    /** Called when `show()` mounts the modal. */
+    onOpen(callback: () => void): this;
+    /** Called when the modal starts closing — scrim tap, back button, or a `hide()` call. */
+    onClose(callback: () => void): this;
+    /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
+     *  (forced-choice dialogs). 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)[];
+    constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn);
+    private _pose;
+    private get _duration();
+    transition(hidden: UIModalTransition): this;
+    show(): void;
+    hide(): void;
+    get isOpen(): boolean;
+    onOpen(callback: () => void): this;
+    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`. */
+export declare function UIModal(...children: UIChildArg[]): UIModal;
+export declare function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIModal(style: UIModalStyle, children?: UINodeChild[] | ChildrenFn): UIModal;