@nubbin/core 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StandardSchemaV1 } from '@standard-schema/spec';
+import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 
 type FieldKind = "string" | "number" | "boolean" | "enum" | "array" | "object" | "union" | "unknown";
 interface FieldNode {
@@ -45,43 +45,9 @@ interface Block<Schema extends StandardSchemaV1 = StandardSchemaV1, Component =
     component: Component;
     /** Bumped when the schema changes incompatibly. */
     version: number;
-    /** A deprecated block still resolves; the studio hides it from the palette. */
-    status?: "active" | "deprecated";
     slots: Record<string, SlotConstraint>;
-    /** Same-node prop reshaping only. It cannot touch slots, or split or delete a block. */
-    migrate?: Record<number, (props: UnknownProps) => UnknownProps>;
 }
 
-/** How a field's value resolves at render. Absent means static — the value freezes into props. */
-type FieldHintData = "request" | {
-    revalidate: number;
-};
-/**
- * Studio treatment for one schema path. Open by design: control resolution ranks testers over
- * these hints, so a consumer can carry keys core does not read.
- */
-interface FieldHint {
-    label?: string;
-    control?: string;
-    data?: FieldHintData;
-}
-interface BlockUi {
-    /** Keyed by schema path (`title`, `cta.label`, `items[].icon`). Unresolvable paths fail registration. */
-    fields?: Record<string, FieldHint>;
-}
-interface BlockDocs {
-    summary?: string;
-    usage?: string;
-}
-/** Serializable data only — what the studio and CI read. Components live in the registry. */
-interface CatalogEntry {
-    schema: unknown;
-    ui?: BlockUi;
-    defaults?: UnknownProps;
-    docs?: BlockDocs;
-}
-type Catalog = Record<string, CatalogEntry>;
-
 interface DocumentMeta {
     title: string;
     description?: string;
@@ -99,13 +65,57 @@ interface Node {
 interface DocumentVersion {
     documentId: string;
     version: number;
-    root: string;
+    /**
+     * Ordered entry elements — the artifact's tree is these, denormalized, in this order. See
+     * [A document has many roots](../../../docs/decisions/a-document-has-many-roots.md).
+     */
+    roots: readonly string[];
     elements: Record<string, Node>;
     meta: DocumentMeta;
     createdAt: string;
     createdBy: string;
 }
 
+/**
+ * Places a node in a parent's slot: a new `DocumentVersion` with the node registered and the
+ * slot's order rewritten, copy-on-write, every other node untouched by reference.
+ *
+ * `node.id` arrives already minted. `core` runs in a browser, a worker and a build step, and a
+ * generator inside it would make the same composition produce a different document every time —
+ * so the caller mints, and the two things this can still check are the parent it names and the
+ * id it brings.
+ *
+ * Slot legality is not one of them. Whether the block belongs in that slot, and whether the slot
+ * is now over its `max`, is `compile`'s judgment — the same division `setNodeProp` follows for a
+ * prop's validity, and what lets a document be illegal between two edits that end legal.
+ *
+ * `index` inserts; its absence appends.
+ */
+declare function addNode(version: DocumentVersion, parentId: string, slot: string, node: Node, index?: number): DocumentVersion;
+
+/** How a field's value resolves at render. Absent means static — the value freezes into props. */
+type FieldHintData = {
+    revalidate: number;
+};
+/**
+ * Studio treatment for one schema path. Open by design: a consumer may carry keys core does not
+ * read, and core reads exactly one — how the field resolves.
+ */
+interface FieldHint {
+    data?: FieldHintData;
+}
+interface BlockUi {
+    /** Keyed by schema path (`title`, `cta.label`, `items[].icon`). Unresolvable paths fail registration. */
+    fields?: Record<string, FieldHint>;
+}
+/** Serializable data only — what the studio and CI read. Components live in the registry. */
+interface CatalogEntry {
+    schema: unknown;
+    ui?: BlockUi;
+    defaults?: UnknownProps;
+}
+type Catalog = Record<string, CatalogEntry>;
+
 /** Field path → how the field resolves at render. */
 type Holes = Record<string, FieldHintData>;
 /** Resolved — no lookups, no dangling references possible. */
@@ -124,7 +134,6 @@ interface Artifact {
     route: string;
     documentId: string;
     documentVersion: number;
-    registryFingerprint: string;
     /** What this was compiled against — only the blocks the document uses. */
     blockVersions: Record<string, number>;
     tree: ArtifactNode[];
@@ -154,21 +163,6 @@ interface ArtifactStore {
     unpublish(route: string): Promise<void>;
 }
 
-type CompileIssueCode = "unknown-block" | "dangling-child" | "cycle" | "unreachable" | "slot-not-allowed" | "slot-min" | "slot-max" | "invalid-props";
-interface CompileIssue {
-    nodeId: string;
-    /** Where in the node the problem sits: `block`, `slots.items`, or a dotted prop path. */
-    path: string;
-    code: CompileIssueCode;
-    message: string;
-}
-
-/** Carries every issue found in one pass, so an author fixing six problems sees six. */
-declare class CompileError extends Error {
-    readonly issues: readonly CompileIssue[];
-    constructor(issues: readonly CompileIssue[]);
-}
-
 /** One route pointer and the artifact it names, as an adapter read them. */
 interface LiveRoute {
     pointer: RoutePointer;
@@ -207,8 +201,6 @@ interface CompatibilityReport {
 interface Registry {
     get(name: string): Block | undefined;
     names(): string[];
-    /** Hash of every block name and version. Nothing else. */
-    fingerprint(): string;
 }
 
 /**
@@ -236,17 +228,96 @@ type RollbackCheck = {
  */
 declare function checkRollback(artifact: Artifact, registry: Registry): RollbackCheck;
 
+/**
+ * Every reason Nubbin refuses something, as a value a consumer can key off rather than a string
+ * they have to match. Each member's value is its own name in kebab-case, so a serialized issue
+ * reads the same in a log as it does in code.
+ *
+ * A const object rather than a TypeScript `enum`: it yields the same two things — a value to
+ * branch on and a type to check against — without the runtime object an `enum` emits, and `core`
+ * has to run unchanged in a browser, a worker and a build step.
+ *
+ * Closed on purpose. A new refusal is a new member here, which is what makes the reference page
+ * listing them checkable against this file.
+ */
+declare const NubbinIssueCode: {
+    readonly BlockVersion: "block-version";
+    readonly SlotBounds: "slot-bounds";
+    readonly SlotAllowUnknown: "slot-allow-unknown";
+    readonly DuplicateBlockName: "duplicate-block-name";
+    readonly InvalidDefaults: "invalid-defaults";
+    readonly HintPathUnresolvable: "hint-path-unresolvable";
+    readonly HintNotAddressable: "hint-not-addressable";
+    readonly NotStandardSchema: "not-standard-schema";
+    readonly NoJsonSchema: "no-json-schema";
+    readonly NoRoots: "no-roots";
+    readonly UnknownBlock: "unknown-block";
+    readonly DanglingChild: "dangling-child";
+    readonly Cycle: "cycle";
+    readonly Unreachable: "unreachable";
+    readonly SlotNotAllowed: "slot-not-allowed";
+    readonly SlotMin: "slot-min";
+    readonly SlotMax: "slot-max";
+    readonly InvalidProps: "invalid-props";
+    readonly UnknownProp: "unknown-prop";
+    readonly NoSuchNode: "no-such-node";
+    readonly DuplicateNodeId: "duplicate-node-id";
+    readonly PathNotAddressable: "path-not-addressable";
+    readonly InvalidRoute: "invalid-route";
+    readonly BlockNotLoaded: "block-not-loaded";
+    readonly NoHoleResolver: "no-hole-resolver";
+    readonly NotOneHostElement: "not-one-host-element";
+    readonly ArtifactNotStored: "artifact-not-stored";
+};
+/** The value of any member, for a consumer narrowing on `issue.code`. */
+type NubbinIssueCode = (typeof NubbinIssueCode)[keyof typeof NubbinIssueCode];
+
+/**
+ * One reason Nubbin refused something. The shape every refusal takes, whether it was thrown or
+ * returned, so a consumer writes one handler and serializes one thing.
+ *
+ * `code` is for branching and `message` is for reading — the prose says what a person needs and
+ * the code says what a program can act on, and neither is asked to do the other's job.
+ *
+ * `at` and `path` are two coordinates rather than one string because an editing surface needs
+ * both: `at` names the thing to select — a node, a block, a route — and `path` names where
+ * inside it to highlight. Joining them into prose would leave a studio parsing its own error
+ * messages to find the field an author has to fix.
+ */
+interface NubbinIssue {
+    code: NubbinIssueCode;
+    message: string;
+    /** What it concerns: a node id, a block name, or a route. */
+    at?: string;
+    /** Where within that: a dotted prop path, `slots.items`, or `block`. */
+    path?: string;
+}
+
+/**
+ * What `compile` produces: the artifact, and everything it has to say about the document that
+ * did not stop it producing one.
+ *
+ * The two travel together because the split is not severity, it is whether an artifact exists.
+ * A document the schema refuses has none, and `compile` throws; a document carrying a key the
+ * schema did not declare has a perfectly good one, and what became of that key is the consumer's
+ * to log, ship, or ignore.
+ */
+interface CompileResult {
+    artifact: Artifact;
+    issues: readonly NubbinIssue[];
+}
+
 /**
  * Orchestration only. Structure first, and stop there if it failed — prop validation on a
  * document with dangling references produces cascading noise that buries the real cause.
+ *
+ * The route is judged before any of it, because it is baked into the artifact and into the
+ * content address: an unaddressable route would otherwise compile, hash, and store cleanly, and
+ * only fail to match a request once it was live.
  */
-declare function compile(version: DocumentVersion, catalog: Catalog, registry: Registry, route: string): Artifact;
+declare function compile(version: DocumentVersion, catalog: Catalog, registry: Registry, route: string): CompileResult;
 
 /**
- * Sorted by name so registration order cannot change the fingerprint, and built from name and
- * version alone so unrelated edits — a slot constraint, a deprecation — do not invalidate every
- * artifact compiled before them.
- *
  * Slot `allow` lists resolve once the whole array is ingested, so a block may name a sibling
  * registered after it.
  */
@@ -255,8 +326,7 @@ declare function createRegistry(blocks: readonly Block[]): Registry;
 /**
  * Identity at runtime; its job is to fix the generic parameters at the call site so props are
  * inferred from the schema rather than declared beside it. The checks here are the ones the
- * type system cannot make — a slot that no composition could satisfy, or a migration keyed to
- * a version this block never reaches.
+ * type system cannot make — a version below 1, or a slot that no composition could satisfy.
  */
 declare function defineBlock<Schema extends StandardSchemaV1, Component>(block: Block<Schema, Component>): Block<Schema, Component>;
 
@@ -274,12 +344,118 @@ declare function defineCatalog(entries: Record<string, CatalogEntry>): Catalog;
  */
 declare function formatCompatibilityReport(report: CompatibilityReport): string;
 
+/**
+ * Moves a node into a slot: a new `DocumentVersion` with the reference taken out of whatever held
+ * it — a slot or the roots — and placed in the target, the node itself untouched by reference.
+ *
+ * `index` names a position in the target slot *as it stands after the node is taken out*, which
+ * is the only reading under which "move it to the end" is the slot's length. Its absence appends.
+ *
+ * It does not refuse a move into the node's own subtree. That makes a cycle and detaches the node
+ * from the roots, and `compile` refuses both by name — judging it here would be a second opinion
+ * on one question, which is the division every operation in this package follows.
+ */
+declare function moveNode(version: DocumentVersion, nodeId: string, toParentId: string, toSlot: string, index?: number): DocumentVersion;
+
+/**
+ * Every refusal Nubbin throws, carrying its causes as data rather than only as prose. One class
+ * for the whole surface: a consumer writes one `catch`, reads `code` or `issues`, and ships that
+ * shape to whatever tooling they keep — the package neither logs nor decides what a refusal
+ * means to them.
+ *
+ * It extends `Error`, so a handler that only ever read `.message` keeps working.
+ */
+declare class NubbinError extends Error {
+    /**
+     * The first issue's code, so the common case reads as
+     * `error.code === NubbinIssueCode.UnknownProp` with no array to index and no string to typo.
+     * Every refusal but `compile`'s carries exactly one issue; read `issues` for the rest.
+     */
+    readonly code: NubbinIssue["code"];
+    readonly issues: readonly NubbinIssue[];
+    constructor(issues: readonly NubbinIssue[]);
+}
+
 /**
  * matchKind is parsed from the route at publish, never caller-supplied. It lives in core so
  * every adapter derives it from one implementation — a second parser is free to disagree.
+ *
+ * The route is judged before it is classified: this is the last point before a pointer is
+ * written, so an adapter that never called `compile` still cannot publish an unaddressable one.
  */
 declare function parseMatchKind(route: string): RoutePointer["matchKind"];
 
+/**
+ * Throws the one-cause refusal that almost every surface raises, so a site says what it refuses
+ * and why in one line rather than assembling an issue array around it.
+ *
+ * `compile` is the exception and builds its own `NubbinError`, because it collects: an author
+ * fixing six problems should see six, not the first.
+ *
+ * Returns `never`, so a caller need not `return` after it for the narrowing to hold.
+ */
+declare function refuse(code: NubbinIssue["code"], message: string, at?: string): never;
+
+/**
+ * Removes a node and everything beneath it: a new `DocumentVersion` with the subtree gone, the
+ * reference to it dropped from whatever held it, and every other node untouched by reference.
+ *
+ * It cascades because removing a section means removing what was in it. Left behind, the children
+ * would be unreachable — which `compile` already refuses — so the alternative is a document that
+ * cannot compile until an author deletes each orphan by hand.
+ *
+ * Whether the slot it emptied is now below its `min` is `compile`'s judgment, as it is for every
+ * other operation here.
+ */
+declare function removeNode(version: DocumentVersion, nodeId: string): DocumentVersion;
+
+/**
+ * The inline emphasis a span may carry. Semantic, never stylistic, and closed: a construct
+ * outside this set is added as a member deliberately, not smuggled in as markup.
+ */
+type RichTextMark = "strong" | "em" | "code";
+/** The block kinds rich text is built from. Closed for the same reason the marks are. */
+type RichTextBlockKind = "paragraph" | "listItem";
+/** A run of text and what is true of it. Inert: nothing here is parsed or evaluated at render. */
+interface RichTextSpan {
+    text: string;
+    marks?: readonly RichTextMark[];
+    href?: string;
+}
+/** One block of a rich-text value: its kind, and the ordered spans it reads as. */
+interface RichTextBlock {
+    kind: RichTextBlockKind;
+    spans: readonly RichTextSpan[];
+}
+/** An ordered array of blocks — the whole value a `richText()` field holds. */
+type RichText = readonly RichTextBlock[];
+
+/**
+ * A schema `core` hand-writes rather than one a validator brings. Narrower than
+ * `StandardSchemaV1` in the two ways that matter to a consumer hosting it: `validate` is
+ * synchronous, which compile requires anyway, and the JSON Schema converter is always there,
+ * so the studio can read the field tree without testing for it.
+ */
+interface StandardDataSchema<Value> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaV1.Result<Value>;
+        readonly jsonSchema: StandardJSONSchemaV1.Converter;
+    };
+}
+
+/**
+ * The rich-text field type: an ordered array of blocks, each an ordered array of inert spans,
+ * over closed mark and kind sets. Nothing in the value is parsed or evaluated at render, so an
+ * artifact carrying it is as inert as one carrying a string.
+ *
+ * A call rather than a bare value, so a field declaration reads the way the rest of a block's
+ * schema does and so options can arrive without changing call sites that pass none. A scan for
+ * this call finds every rich-text field in a registry.
+ */
+declare function richText(): StandardDataSchema<RichText>;
+
 /** Copy-on-write down one dotted path. Paths address object fields only; `[]` has no single target. */
 declare function setAtPath(target: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
 
@@ -295,4 +471,4 @@ declare function setAtPath(target: Record<string, unknown>, path: string, value:
  */
 declare function setNodeProp(version: DocumentVersion, nodeId: string, path: string, value: unknown): DocumentVersion;
 
-export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDocs, type BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, CompileError, type CompileIssue, type CompileIssueCode, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, type Registry, type RollbackCheck, type RouteIncompatibility, type RoutePointer, type SchemaAdapter, type SlotConstraint, type UnknownProps, checkCompatibility, checkRollback, compile, createRegistry, defineBlock, defineCatalog, formatCompatibilityReport, parseMatchKind, setAtPath, setNodeProp, zodAdapter };
+export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, type CompileResult, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, NubbinError, type NubbinIssue, NubbinIssueCode, type Registry, type RichText, type RichTextBlock, type RichTextBlockKind, type RichTextMark, type RichTextSpan, type RollbackCheck, type RouteIncompatibility, type RoutePointer, type SchemaAdapter, type SlotConstraint, type StandardDataSchema, type UnknownProps, addNode, checkCompatibility, checkRollback, compile, createRegistry, defineBlock, defineCatalog, formatCompatibilityReport, moveNode, parseMatchKind, refuse, removeNode, richText, setAtPath, setNodeProp, zodAdapter };