@mark1russell7/render-biblo 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,69 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/render-biblo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "The class registry and the instance store of render, and the class-level NodeOps.",
+  "keywords": [
+    "classes",
+    "templates",
+    "traits",
+    "prototype",
+    "reactive",
+    "typescript"
+  ],
+  "homepage": "https://mark1russell7.github.io/render/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/render/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/render.git",
+    "directory": "packages/biblo"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/main.tsx",
+    "!src/page.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "@mark1russell7/coeval": "^0.4.0",
+    "@mark1russell7/render-dsl": "0.2.0",
+    "@mark1russell7/render-node": "0.2.0",
+    "@mark1russell7/render-optional": "0.1.0"
+  },
+  "devDependencies": {
+    "@mark1russell7/cue": "github:mark1russell7/cue",
+    "@types/node": "^26.6.4",
+    "tsdown": "^0.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json"
+  }
 }

package/src/class.ts

@@ -0,0 +1,64 @@
+import type { Expr } from "@mark1russell7/render-dsl";
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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 const componentClass = (
+  name: string,
+  cells: Readonly<Record<string, CellDef>>,
+  ext?: string,
+  methods?: Readonly<Record<string, unknown>>,
+): ComponentClass => ({
+  name,
+  cells,
+  ...(ext !== undefined ? { extends: ext } : {}),
+  ...(methods !== undefined ? { methods } : {}),
+});
+
+/**
+ * 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 const extendClass = (
+  base: ComponentClass,
+  overrides: {
+    readonly cells?: Readonly<Record<string, CellDef>>;
+    readonly methods?: Readonly<Record<string, unknown>>;
+  },
+): ComponentClass => ({
+  ...base,
+  cells: { ...base.cells, ...overrides.cells },
+  methods: { ...base.methods, ...overrides.methods },
+});

package/src/index.ts

@@ -0,0 +1,9 @@
+export { type CellDef, type ComponentClass, componentClass, extendClass } from "./class.ts";
+export type { InstanceId, Scope, Instance } from "./instance.ts";
+export {
+  type Biblo, biblo, forkBiblo, registerClass, registerClasses, resolveCells, resolveMethods,
+  instantiate, destroyInstance, moveChild, updateClass, ownerOf, renameClass,
+  registerTrait, unregisterTrait, resolveTraits, classFingerprint, primeOf,
+} from "./registry.ts";
+export { type Trait, type TraitResolution, requirementAtoms } from "./traits.ts";
+export { classNodeOps } from "./nodeops.ts";

package/src/instance.ts

@@ -0,0 +1,23 @@
+/** The identity of an instance. It is also the ID of the root node of the instance. */
+export 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.
+ */
+export 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.
+ */
+export type Instance = {
+  readonly id: InstanceId;
+  readonly classRef: string;
+  readonly scope: Scope;
+};

package/src/nodeops.ts

@@ -0,0 +1,31 @@
+import type { NodeOps, SplashFn, FlowFn, DerefFn, TargetsFn, Node, NodeStore } from "@mark1russell7/render-node";
+import { defaultOps } from "@mark1russell7/render-node";
+import type { Biblo } from "./registry.ts";
+import { ownerOf, resolveMethods } from "./registry.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 const classNodeOps = (b: Biblo, fallback: NodeOps = defaultOps): NodeOps => {
+  type Methods = { readonly splash: SplashFn; readonly flow: FlowFn; readonly deref: DerefFn; readonly targets: TargetsFn };
+  const methodFor = <K extends keyof Methods>(n: Node, store: NodeStore, name: K): Methods[K] => {
+    const owner = ownerOf(b, store, n.id);
+    const inst = owner === undefined ? undefined : b.instances.get(owner);
+    const method = inst ? resolveMethods(b, inst.classRef)[name] : undefined;
+    return typeof method === "function" ? (method as Methods[K]) : fallback[name];
+  };
+
+  return {
+    splash: (value, target, store) => methodFor(target, store, "splash")(value, target, store),
+    flow: (target, store) => methodFor(target, store, "flow")(target, store),
+    deref: (root, path, store) => methodFor(root, store, "deref")(root, path, store),
+    targets: (root, path, store) => methodFor(root, store, "targets")(root, path, store),
+  };
+};