@tur-ng/std 0.0.9 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tur-ng/std",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "types": "src/index.d.ts",
   "files": [
@@ -16,6 +16,6 @@
     "directory": "js/packages/tur-std"
   },
   "dependencies": {
-    "@tur-ng/core": "0.0.7"
+    "@tur-ng/core": "0.0.8"
   }
 }

package/src/index.d.ts

@@ -422,6 +422,45 @@ declare module "tur:std" {
         queryKey?: Val<string[]>;
     }
 
+    /** One `Table.columns` entry. `width` = fixed px; `flex` = share of the
+     *  leftover width (proportional to the total flex weight). A column with
+     *  neither defaults to `flex: 1`. `minWidth` clamps the distributed
+     *  share up (may overflow the available width). */
+    export interface TableColumnDef {
+        width?: number;
+        flex?: number;
+        minWidth?: number;
+    }
+
+    /** A non-scrollable data table with shared column geometry: the header
+     *  row and every body row lay their cells at the same resolved column
+     *  widths (CSS `table-layout: fixed` semantics). `rows` is a reactive
+     *  array — writing a new array value rebuilds the row subtrees (write a
+     *  fresh array; in-place mutation of the same array object with an
+     *  unchanged length is not observed). `build` returns one row's cells,
+     *  positionally mapped to the columns: a `null` entry is an empty cell
+     *  box (the column advances), entries beyond the column count are
+     *  ignored. `buildHeader` follows the same mapping and runs ONCE at
+     *  build — reactive header content flows through `Val` props inside
+     *  the returned cells. Without an extent, a row's height is the max
+     *  intrinsic cell height (cells get loose height constraints); with
+     *  one, cells fill it. Wrap in a `ScrollView` to scroll. */
+    export interface TableProps<T> {
+        columns: TableColumnDef[];
+        rows: Readable<T[]>;
+        build: (item: T, index: number) => (Element | null)[];
+        buildHeader?: () => (Element | null)[];
+        headerExtent?: Val<number>;
+        rowExtent?: Val<number>;
+        rowSpacing?: Val<number>;
+        /** Painted under odd body rows. */
+        stripeColor?: Val<Brush | null>;
+        /** Horizontal rules between body rows + under the header. */
+        dividerColor?: Val<Brush | null>;
+        dividerThickness?: Val<number>;
+        queryKey?: Val<string[]>;
+    }
+
     export interface EachProps<T> {
         items: Readable<T[]>;
         build: (item: T, index: number) => Element;
@@ -664,6 +703,7 @@ declare module "tur:std" {
     export function Each<T>(props: EachProps<T>): Element;
     export function LazyList(props: LazyListProps): Element;
     export function Grid(props: GridProps): Element;
+    export function Table<T>(props: TableProps<T>): Element;
     export function LazyGrid(props: LazyGridProps): Element;
     export function ScrollView(props: ScrollViewProps): Element;
     export function Scrollbar(props: ScrollbarProps): Element;
@@ -817,4 +857,91 @@ declare module "tur:std" {
 
     /** Encode a string into a Uint8Array of UTF-8 bytes. */
     export function encodeUtf8(text: string): Uint8Array;
+
+    // ------------------------------------------------------------------
+    // Virtual apps — VirtualAppView hosts a complete nested engine
+    // instance (own worker, realm, store, tree) and draws the child's
+    // frames from its own paint. The controller is a lazy declaration:
+    // nothing runs until an element binds it (`app$` resolving to a
+    // controller); unbinding destroys the child unless `keepAlive`.
+    // ------------------------------------------------------------------
+
+    /**
+     * Opaque handle to a registered module source (`createModuleSource`).
+     * The source string never crosses the JS API again — only this handle
+     * does (the JS mirror of the Rust-side `ModuleSourceRegistry` /
+     * `load_module_source` flow).
+     */
+    export interface ModuleSourceHandle {
+        readonly __moduleSource: unique symbol;
+    }
+
+    /**
+     * Opaque handle to a worker pool registered on the runtime
+     * (`forWorkerPool`). The JS mirror of the Rust-side `WorkerPoolHandle`
+     * — resolved eagerly against the registry, so an unknown name throws
+     * at the call site.
+     */
+    export interface WorkerPoolHandle {
+        readonly __workerPool: unique symbol;
+    }
+
+    /** Lifecycle state of a hosted virtual app. */
+    export type VirtualAppStatus =
+        | "idle"
+        | "spawning"
+        | "running"
+        | "error"
+        | "destroyed";
+
+    /** A hosted virtual app's controller — a lazy declaration. */
+    export interface VirtualAppController {
+        /** Reactive status — read via `store.get(app.status$)`. */
+        readonly status$: Readable<VirtualAppStatus>;
+        /** Error detail (module load / start failures) — read via `store.get`. */
+        readonly errorMsg$: Readable<string>;
+        /**
+         * The ONLY lifecycle action — a control mutation (the `watch`
+         * `{ start$, stop$ }` convention: side effects ride the mutation
+         * rail). Dispatch via `store.set(app.destroy$)`. New code =
+         * destroy$ + a new controller with a new source.
+         */
+        readonly destroy$: Mutation;
+    }
+
+    /** Register a module source once; reference it by opaque handle. */
+    export function createModuleSource(source: string): ModuleSourceHandle;
+
+    /**
+     * Resolve a registered worker pool by name — eagerly (an unknown name
+     * throws right here). The only source of the handle
+     * `createVirtualAppController({ pool })` accepts.
+     */
+    export function forWorkerPool(name: string): WorkerPoolHandle;
+
+    /** Create a virtual-app controller (lazy — spawns on first bind). */
+    export function createVirtualAppController(opts: {
+        source: ModuleSourceHandle;
+        /**
+         * Target worker pool, from `forWorkerPool(name)` (handle-only — raw
+         * strings are rejected). Omit for the default `"virtual"` pool.
+         */
+        pool?: WorkerPoolHandle;
+        /** Survive element unbind (default `false`). */
+        keepAlive?: boolean;
+    }): VirtualAppController;
+
+    /** Element hosting a virtual app; draws the child's latest frame. */
+    export function VirtualAppView(props: {
+        /** Reactive controller binding — `null` unbinds (destroys). */
+        app$: Readable<VirtualAppController | null>;
+        background?: Val<Color>;
+        width?: Val<number>;
+        height?: Val<number>;
+        queryKey?: Array<string>;
+        /** Painted while the child isn't live. */
+        fallback?: Element;
+        /** Painted on error. */
+        errorView?: Element;
+    }): Element;
 }