@mark1russell7/render-biblo 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @mark1russell7/render-biblo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@mark1russell7/render-biblo?color=2346c4)](https://www.npmjs.com/package/@mark1russell7/render-biblo) [![CI](https://github.com/mark1russell7/render/actions/workflows/ci.yml/badge.svg)](https://github.com/mark1russell7/render/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-2346c4)](https://github.com/mark1russell7/render/blob/main/LICENSE)
+
+The classes of render. A class is a template of nodes: cells with expressions, and methods. An instance is an ID and a scope. A change of a class reaches each instance that still follows it.
+
+```sh
+npm i @mark1russell7/render-biblo @mark1russell7/render-node @mark1russell7/render-dsl
+```
+
+```ts
+import { app, lit, ref } from "@mark1russell7/render-dsl";
+import { biblo, classNodeOps, componentClass, instantiate, registerClass, updateClass } from "@mark1russell7/render-biblo";
+import { nodeStore, readValue } from "@mark1russell7/render-node";
+
+const ops = { concat: (...parts: unknown[]) => parts.join("") };
+const badge = (label: string) =>
+  componentClass("Badge", {
+    label: { expr: lit(label) },
+    text: { expr: app("concat", lit("[ "), ref("self", "label"), lit(" ]")) },
+  });
+
+const b = biblo();
+const store = nodeStore({ nodeOps: classNodeOps(b), ops });
+registerClass(b, badge("star"));
+const inst = instantiate(b, store, "Badge");
+const text = store.nodes.get(inst.id)!.slots.get("text")!;
+readValue(store, text); // { tag: "some", value: "[ star ]" }
+
+updateClass(b, store, badge("planet"));
+readValue(store, text); // { tag: "some", value: "[ planet ]" }
+```
+
+Traits give methods to each class with a set of cells. The fingerprint of a class is a product of primes, thus the match of a trait is one division.
+
+A class is data: each expression is a [coeval](https://github.com/mark1russell7/coeval) document, thus a class from JSON text registers as it is. An instance scopes its cells with `mapRefs` of the kernel: `self` and `parent` become node IDs, and the parameters of a `fn` stay. `updateClass` compares the expressions with `docEquals`.
+
+## More
+
+- [The site](https://mark1russell7.github.io/render/): the guide, live demos and the viewer.
+- [The API reference](https://mark1russell7.github.io/render/reference/api/): the exports of each package.
+- [The repository](https://github.com/mark1russell7/render): the source, the tests and the review of each known defect.
+
+Each package of render is ESM, has TypeScript declarations, and works in Node.js 22.12 or later and in browsers. The license is MIT.

package/build/index.d.ts

@@ -0,0 +1,209 @@
+import { Expr } from "@mark1russell7/render-dsl";
+import { NodeId, NodeOps, NodeStore } from "@mark1russell7/render-node";
+//#region src/class.d.ts
+/**
+ * A cell template of a class. It has an expression (a coeval document), and optionally a type: the name of
+ * another class. A typed cell holds an instance of that class, thus the class level knows the paths through its children.
+ */
+type CellDef = {
+  readonly expr: Expr;
+  /** The class of the child instance that this cell holds. */
+  readonly type?: string | undefined;
+  /**
+   * The bindings of a typed cell: expressions that replace cells of the child.
+   * They are in the scope of the child. For example, `{ value: ref("parent", "key") }` binds the cell `value`
+   * of the child to the cell `key` of this instance.
+   */
+  readonly bindings?: Readonly<Record<string, Expr>> | undefined;
+};
+/**
+ * A class is a template. Instances share it, and nothing copies it.
+ *
+ * - `cells`: the reactive structure, which is the data that each instance holds.
+ * - `methods`: the behavior. The extends chain resolves them, and the most specific method wins.
+ * - `extends`: the parent class. Cells and methods both resolve through it.
+ *
+ * The values of `methods` are opaque. Each layer reads the method names that it knows, for example
+ * `render` for splay and `splash` for the node engine. The class `Top` gives the defaults. An expression method is
+ * a coeval document, thus a class is data from end to end.
+ */
+type ComponentClass = {
+  readonly name: string;
+  readonly cells: Readonly<Record<string, CellDef>>;
+  readonly extends?: string | undefined;
+  readonly methods?: Readonly<Record<string, unknown>> | undefined;
+};
+/** This function makes a class. */
+export declare const componentClass: (name: string, cells: Readonly<Record<string, CellDef>>, ext?: string, methods?: Readonly<Record<string, unknown>>) => ComponentClass;
+/**
+ * This function gives a copy of a class with more cells and methods. The copy keeps the name.
+ * An override with the name of an existing cell or method replaces it.
+ */
+export declare const extendClass: (base: ComponentClass, overrides: {
+  readonly cells?: Readonly<Record<string, CellDef>>;
+  readonly methods?: Readonly<Record<string, unknown>>;
+}) => ComponentClass;
+//#endregion
+//#region src/instance.d.ts
+/** The identity of an instance. It is also the ID of the root node of the instance. */
+type InstanceId = string;
+/**
+ * The scope of an instance: the names that its expressions can use.
+ * `ref("self", ...)` reads this instance, and `ref("parent", ...)` reads the parent instance.
+ */
+type Scope = {
+  readonly self: InstanceId;
+  readonly parent: InstanceId | undefined;
+  /** The child instances, in order. Splay renders them, and dehydrate reads them. */
+  readonly children: readonly InstanceId[];
+};
+/**
+ * An instance is small: an ID, a class name and a scope. It copies no data of its class.
+ * The values of its cells are in the node store, in the slots of its root node.
+ */
+type Instance = {
+  readonly id: InstanceId;
+  readonly classRef: string;
+  readonly scope: Scope;
+};
+//#endregion
+//#region src/traits.d.ts
+/**
+ * Structural traits with prime fingerprints: a granular polymorphism.
+ *
+ * Each atomic feature of a class gets a unique prime: a cell (`value`), or a typed cell (`kid:Point`).
+ * The fingerprint of a class is the product of the primes of its features. The product does not depend on
+ * the order of the features, thus two classes with the same features have the same fingerprint.
+ *
+ * A trait gives methods to each class that has the features of its list. Then the fingerprint of the trait
+ * divides the fingerprint of the class. Among the traits that apply, only the most specific ones count
+ * (a trait whose fingerprint divides the fingerprint of another applicable trait is dominated). When two of
+ * them give the same method, the method is ambiguous: no trait gives it, and the ambiguity is visible.
+ */
+/** A trait: methods for each class that has the cells of its list. */
+type Trait = {
+  readonly name: string;
+  /** The features that a class must have: a cell name (`label`), or a typed cell (`kid:Point`). */
+  readonly requires: readonly string[];
+  readonly methods: Readonly<Record<string, unknown>>;
+};
+/** The traits that apply to a class, and the names of the methods that two of them give. */
+type TraitResolution = {
+  readonly applied: readonly Trait[];
+  readonly ambiguous: readonly string[];
+};
+/** This function gives the features of an item of the list of a trait: `kid:Point` is the cell `kid` with the type `Point`. */
+export declare const requirementAtoms: (requirement: string) => string[];
+//#endregion
+//#region src/registry.d.ts
+/**
+ * The biblo is the class registry and the instance store.
+ *
+ * Classes are shared templates. Instances are small (an ID and a scope), and the values of their cells
+ * are in the node store. A trait gives methods to each class that has the cells of its list.
+ * Change a biblo only through its functions, for example `registerClass`, `registerTrait` and `instantiate`.
+ */
+type Biblo = {
+  readonly classes: ReadonlyMap<string, ComponentClass>;
+  readonly instances: ReadonlyMap<InstanceId, Instance>;
+  readonly traits: ReadonlyMap<string, Trait>;
+};
+/** This function makes an empty biblo. */
+export declare const biblo: () => Biblo;
+/**
+ * This function gives an independent copy of a biblo: the same classes, traits, instances and counters. The
+ * classes and the traits are immutable, thus the copy shares them. Pair the copy with a copy of its store
+ * (`forkStore`), with the class semantics of the copy (`classNodeOps`).
+ */
+export declare const forkBiblo: (b: Biblo) => Biblo;
+/**
+ * This function registers a class, or replaces the class with the same name. The live instances do not change.
+ * The expressions of the class are coeval documents, thus a class from JSON text registers as it is.
+ */
+export declare const registerClass: (b: Biblo, cls: ComponentClass) => void;
+/** This function registers a trait, or replaces the trait with the same name. The live instances use it at once. */
+export declare const registerTrait: (b: Biblo, trait: Trait) => void;
+/** This function removes a trait. */
+export declare const unregisterTrait: (b: Biblo, name: string) => void;
+/**
+ * This function renames a class. Its subclasses, the typed cells that use it and its live instances use the
+ * new name. A trait whose list has a typed cell of the class (`kid:Point`) also uses the new name. The function
+ * does nothing and gives `false` when the class is missing or the new name is in use.
+ */
+export declare const renameClass: (b: Biblo, from: string, to: string) => boolean;
+/** This function registers each class of a list, in order. */
+export declare const registerClasses: (b: Biblo, classes: readonly ComponentClass[]) => void;
+/** This function gives all cell templates of a class through its extends chain. A subclass cell replaces a parent cell. */
+export declare const resolveCells: (b: Biblo, className: string) => Readonly<Record<string, CellDef>>;
+/** This function gives the fingerprint of a class: the product of the primes of its cells and typed cells. */
+export declare const classFingerprint: (b: Biblo, className: string) => bigint;
+/** This function gives the prime of an atomic feature, for example `cell:value`. */
+export declare const primeOf: (b: Biblo, atom: string) => bigint;
+/** This function gives the traits that apply to a class (the most specific ones), and the ambiguous method names. */
+export declare const resolveTraits: (b: Biblo, className: string) => TraitResolution;
+/**
+ * This function gives all methods of a class. There are three layers, from the lowest to the highest.
+ * The first layer is the root of the extends chain, for example `Top`. The second layer is the traits that apply.
+ * The third layer is the other classes of the chain, to the class itself.
+ *
+ * Thus a trait changes the defaults of the root, and a class changes a trait.
+ * A method that two traits give is ambiguous: no trait gives it.
+ */
+export declare const resolveMethods: (b: Biblo, className: string) => Readonly<Record<string, unknown>>;
+/**
+ * This function makes an instance of a class. The class is not copied: the instance gets an ID, a scope,
+ * and a root node with one slot for each cell. All nodes are evaluated before the end of the function.
+ *
+ * - A typed cell becomes a child instance of its class, with the bindings of the cell. The slot of the cell
+ *   holds the root node of the child, thus `ref("self", "kid", "value")` reads a cell of the child.
+ *   A typed cell whose class is already above it on the chain of typed cells is a plain cell.
+ * - `bindings` replace cells of this instance. They are in the scope of this instance. A binding for a typed
+ *   cell makes it a plain cell with the bound expression.
+ * - An unknown class gives an instance with no cells.
+ */
+export declare const instantiate: (b: Biblo, store: NodeStore, className: string, parentId?: InstanceId, bindings?: Readonly<Record<string, Expr>>) => Instance;
+/**
+ * This function moves a child instance to a position in the children of its parent. A position past the end
+ * moves it to the end. It does nothing for an instance without a parent.
+ */
+export declare const moveChild: (b: Biblo, childId: InstanceId, index: number) => void;
+/**
+ * This function destroys an instance, the inverse of `instantiate`. It destroys the children first, then
+ * removes the nodes of the instance and detaches it from its parent. The readers of the removed nodes
+ * become `none` in one epoch.
+ */
+export declare const destroyInstance: (b: Biblo, store: NodeStore, instanceId: InstanceId) => void;
+/**
+ * This function registers a new version of a class and updates the live instances: the class is a template,
+ * and the instances follow it. The update applies to each instance of the class and of its subclasses.
+ * When a cell of the resolved class changes, the instance cell changes too, if it still has the old expression.
+ *
+ * - A cell with an edit of its own keeps it. A cell that a binding gave keeps the binding.
+ * - A new cell is added, and a removed cell is removed. A shared cell node only loses its slot.
+ * - A typed cell that changes its type gets a new child instance. A change of its bindings reaches the cells of
+ *   the child that still follow the old bindings. A change between a typed cell and a plain cell replaces the cell.
+ *
+ * All changes evaluate in one epoch.
+ */
+export declare const updateClass: (b: Biblo, store: NodeStore, cls: ComponentClass) => void;
+/**
+ * This function gives the instance that owns a node. For an instance root, it is the node itself.
+ * For another node, it is the nearest owner up the slot tree. A node outside all instances gives `undefined`.
+ */
+export declare const ownerOf: (b: Biblo, store: NodeStore, nodeId: NodeId) => InstanceId | undefined;
+//#endregion
+//#region src/nodeops.d.ts
+/**
+ * This function makes the class-level reactive semantics (the defaults of `Top`).
+ *
+ * The ops of the result use the `splash`, `flow`, `deref` and `targets` methods of the class that owns each node.
+ * The extends chain resolves them, thus the defaults of `Top` apply to all classes, and a class can
+ * change them. A node without an owner, or a class without the method, uses `fallback`.
+ *
+ * The node layer knows nothing of biblo. This factory is how the class layer gives semantics to the
+ * node layer without a dependency in the wrong direction. Give the result to `nodeStore`.
+ */
+export declare const classNodeOps: (b: Biblo, fallback?: NodeOps) => NodeOps;
+//#endregion
+export type { Biblo, CellDef, ComponentClass, Instance, InstanceId, Scope, Trait, TraitResolution };
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/class.ts","../src/instance.ts","../src/traits.ts","../src/registry.ts","../src/nodeops.ts"],"mappings":";;;;;;;KAMY;WACD,MAAM;;WAEN;;;;;;WAMA,WAAW,SAAS,eAAe;;;;;;;;;;;;;KAclC;WACD;WACA,OAAO,SAAS,eAAe;WAC/B;WACA,UAAU,SAAS;;;qBAIjB,iBACX,cACA,OAAO,SAAS,eAAe,WAC/B,cACA,UAAU,SAAS,6BAClB;;;;;qBAWU,cACX,MAAM,gBACN;WACW,QAAQ,SAAS,eAAe;WAChC,UAAU,SAAS;MAE7B;;;;KC1DS;;;;;KAMA;WACD,MAAM;WACN,QAAQ;;WAER,mBAAmB;;;;;;KAOlB;WACD,IAAI;WACJ;WACA,OAAO;;;;;;;;;;;;;;;;;KCPN;WACD;;WAEA;WACA,SAAS,SAAS;;;KAIjB;WACD,kBAAkB;WAClB;;;qBAkDE,mBAAoB;;;;;;;;;;KCzDrB;WACD,SAAS,oBAAoB;WAC7B,WAAW,YAAY,YAAY;WACnC,QAAQ,oBAAoB;;;qBA+B1B,aAAY;;;;;;qBAoBZ,YAAa,GAAG,UAAQ;;;;;qBA+BxB,gBAAiB,GAAG,OAAO,KAAK;;qBAOhC,gBAAiB,GAAG,OAAO,OAAO;;qBAOlC,kBAAmB,GAAG,OAAO;;;;;;qBAW7B,cAAe,GAAG,OAAO,cAAc;;qBAiCvC,kBAAmB,GAAG,OAAO,kBAAkB;;qBAiC/C,eAAgB,GAAG,OAAO,sBAAoB,SAAS,eAAe;;qBAWtE,mBAAoB,GAAG,OAAO;;qBAU9B,UAAW,GAAG,OAAO;;qBAGrB,gBAAiB,GAAG,OAAO,sBAAoB;;;;;;;;;qBAkB/C,iBAAkB,GAAG,OAAO,sBAAoB,SAAS;;;;;;;;;;;;qBAuGzD,cACX,GAAG,OACH,OAAO,WACP,mBACA,WAAW,YACX,WAAW,SAAS,eAAe,WAClC;;;;;qBAqBU,YAAa,GAAG,OAAO,SAAS,YAAY;;;;;;qBAiB5C,kBAAmB,GAAG,OAAO,OAAO,WAAW,YAAY;;;;;;;;;;;;;qBAuE3D,cAAe,GAAG,OAAO,OAAO,WAAW,KAAK;;;;;qBAsDhD,UAAW,GAAG,OAAO,OAAO,WAAW,QAAQ,WAAS;;;;;;;;;;;;;qBC5exD,eAAgB,GAAG,OAAO,WAAU,YAAuB"}