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

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 {
@@ -48,8 +48,6 @@ interface Block<Schema extends StandardSchemaV1 = StandardSchemaV1, Component =
     /** 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. */
@@ -99,7 +97,11 @@ 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;
@@ -154,7 +156,7 @@ interface ArtifactStore {
     unpublish(route: string): Promise<void>;
 }
 
-type CompileIssueCode = "unknown-block" | "dangling-child" | "cycle" | "unreachable" | "slot-not-allowed" | "slot-min" | "slot-max" | "invalid-props";
+type CompileIssueCode = "no-roots" | "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. */
@@ -255,8 +257,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>;
 
@@ -280,6 +281,53 @@ declare function formatCompatibilityReport(report: CompatibilityReport): string;
  */
 declare function parseMatchKind(route: string): RoutePointer["matchKind"];
 
+/**
+ * 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 +343,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 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 RichText, type RichTextBlock, type RichTextBlockKind, type RichTextMark, type RichTextSpan, type RollbackCheck, type RouteIncompatibility, type RoutePointer, type SchemaAdapter, type SlotConstraint, type StandardDataSchema, type UnknownProps, checkCompatibility, checkRollback, compile, createRegistry, defineBlock, defineCatalog, formatCompatibilityReport, parseMatchKind, richText, setAtPath, setNodeProp, zodAdapter };

package/dist/index.js

@@ -191,7 +191,7 @@ function wireSlots(version, built) {
 
 // src/denormalize.ts
 function denormalize(version, resolve) {
-  const pending = [version.root];
+  const pending = [...version.roots];
   const built = /* @__PURE__ */ new Map();
   while (pending.length > 0) {
     const id = pending.pop();
@@ -204,8 +204,10 @@ function denormalize(version, resolve) {
     }
   }
   wireSlots(version, built);
-  const root = built.get(version.root);
-  return root === void 0 ? [] : [root];
+  return version.roots.flatMap((id) => {
+    const root = built.get(id);
+    return root === void 0 ? [] : [root];
+  });
 }
 
 // src/fnv1a.ts
@@ -232,18 +234,43 @@ function hashArtifact(artifact) {
   return fnv1a(JSON.stringify(artifact, sortKeys));
 }
 
+// src/splitPath.ts
+function splitPath(path) {
+  const [head, ...tail] = path.split(".");
+  if (head === void 0 || head === "" || head.includes("[]")) {
+    throw new Error(`path "${path}" is not addressable`);
+  }
+  return { head, tail };
+}
+
+// src/takeAtPath.ts
+function takeAtPath(target, path) {
+  const { head, tail } = splitPath(path);
+  if (!Object.hasOwn(target, head)) return { rest: target, taken: false };
+  if (tail.length === 0) {
+    const remaining = { ...target };
+    delete remaining[head];
+    return { rest: remaining, taken: true };
+  }
+  const child = target[head];
+  if (typeof child !== "object" || child === null || Array.isArray(child)) {
+    return { rest: target, taken: false };
+  }
+  const inner = takeAtPath(child, tail.join("."));
+  if (!inner.taken) return { rest: target, taken: false };
+  return { rest: { ...target, [head]: inner.rest }, taken: true };
+}
+
 // src/partitionProps.ts
 function partitionProps(validated, hints) {
-  const props = {};
+  let props = { ...validated };
   const holes = {};
-  const fields = hints?.fields ?? {};
-  for (const [key, value] of Object.entries(validated)) {
-    const data = fields[key]?.data;
-    if (data === void 0) {
-      props[key] = value;
-    } else {
-      holes[key] = data;
-    }
+  for (const [path, hint] of Object.entries(hints?.fields ?? {})) {
+    if (hint.data === void 0) continue;
+    const { rest, taken } = takeAtPath(props, path);
+    if (!taken) continue;
+    props = rest;
+    holes[path] = hint.data;
   }
   return { props, holes };
 }
@@ -352,12 +379,11 @@ function pushCycleFrame(stack, state, version, id) {
   stack.push({ id, edges: slotEdges(node), next: 0 });
 }
 
-// src/findCycles.ts
-function findCycles(version) {
-  const state = /* @__PURE__ */ new Map();
+// src/findCyclesFrom.ts
+function findCyclesFrom(version, root, state) {
   const stack = [];
   const issues = [];
-  pushCycleFrame(stack, state, version, version.root);
+  pushCycleFrame(stack, state, version, root);
   while (stack.length > 0) {
     const frame = stack.at(-1);
     if (frame === void 0) break;
@@ -382,17 +408,17 @@ function findCycles(version) {
   return issues;
 }
 
+// src/findCycles.ts
+function findCycles(version) {
+  const state = /* @__PURE__ */ new Map();
+  return version.roots.flatMap(
+    (root) => state.has(root) ? [] : findCyclesFrom(version, root, state)
+  );
+}
+
 // src/findDanglingChildren.ts
 function findDanglingChildren(version) {
   const issues = [];
-  if (version.elements[version.root] === void 0) {
-    issues.push({
-      nodeId: version.root,
-      path: "root",
-      code: "dangling-child",
-      message: `root "${version.root}" has no matching element`
-    });
-  }
   for (const node of Object.values(version.elements)) {
     for (const edge of slotEdges(node)) {
       if (version.elements[edge.childId] === void 0) {
@@ -408,6 +434,30 @@ function findDanglingChildren(version) {
   return issues;
 }
 
+// src/findRootIssues.ts
+function findRootIssues(version) {
+  if (version.roots.length === 0) {
+    return [
+      {
+        nodeId: "",
+        path: "roots",
+        code: "no-roots",
+        message: "a document needs at least one root, and this one names none"
+      }
+    ];
+  }
+  return version.roots.flatMap(
+    (root) => version.elements[root] === void 0 ? [
+      {
+        nodeId: root,
+        path: "roots",
+        code: "dangling-child",
+        message: `root "${root}" has no matching element`
+      }
+    ] : []
+  );
+}
+
 // src/disallowedChildren.ts
 function disallowedChildren(parent, path, childIds, allow, version) {
   if (allow === void 0) return [];
@@ -494,8 +544,8 @@ function findUnknownBlocks(version, registry) {
 
 // src/reachableIds.ts
 function reachableIds(version) {
-  const seen = /* @__PURE__ */ new Set([version.root]);
-  const queue = [version.root];
+  const seen = new Set(version.roots);
+  const queue = [...version.roots];
   while (queue.length > 0) {
     const id = queue.pop();
     const node = id === void 0 ? void 0 : version.elements[id];
@@ -519,7 +569,7 @@ function findUnreachable(version) {
       nodeId: node.id,
       path: "",
       code: "unreachable",
-      message: `no slot reaches "${node.id}" from the root`
+      message: `no slot reaches "${node.id}" from any root`
     });
   }
   return issues;
@@ -527,8 +577,11 @@ function findUnreachable(version) {
 
 // src/validateStructure.ts
 function validateStructure(version, registry) {
+  const rootIssues = findRootIssues(version);
+  if (version.roots.length === 0) return rootIssues;
   return [
     ...findUnknownBlocks(version, registry),
+    ...rootIssues,
     ...findDanglingChildren(version),
     ...findCycles(version),
     ...findUnreachable(version),
@@ -537,7 +590,7 @@ function validateStructure(version, registry) {
 }
 
 // src/version.constants.ts
-var NUBBIN_VERSION = "0.1.0-rc.5";
+var NUBBIN_VERSION = "0.1.0-rc.6";
 
 // src/compile.ts
 function compile(version, catalog, registry, route) {
@@ -605,17 +658,6 @@ function assertBlockVersion(name, version) {
   }
 }
 
-// src/assertMigrateKeys.ts
-var FIRST_MIGRATABLE_VERSION = 2;
-function assertMigrateKeys(name, version, migrate) {
-  for (const key of Object.keys(migrate ?? {})) {
-    const target = Number(key);
-    if (target < FIRST_MIGRATABLE_VERSION || target > version) {
-      throw new Error(`${name}: migrate key ${key} is outside the reachable range 2..${version}`);
-    }
-  }
-}
-
 // src/assertSlotBounds.ts
 function assertSlotBounds(name, slots) {
   for (const [slot, { min, max }] of Object.entries(slots)) {
@@ -629,7 +671,6 @@ function assertSlotBounds(name, slots) {
 function defineBlock(block) {
   assertBlockVersion(block.name, block.version);
   assertSlotBounds(block.name, block.slots);
-  assertMigrateKeys(block.name, block.version, block.migrate);
   return block;
 }
 
@@ -646,12 +687,23 @@ function resolveHintPaths(blockName, schema, fields) {
 
 // src/assertDataHintAddressable.ts
 function assertDataHintAddressable(blockName, fields) {
+  const seen = [];
   for (const [path, hint] of Object.entries(fields)) {
-    if (hint.data !== void 0 && path.includes("[]")) {
+    if (hint.data === void 0) continue;
+    if (path.includes("[]")) {
       throw new Error(
         `${blockName}: ui.fields["${path}"] sets \`data\`, but a hole cannot address an array member \u2014 "[]" has no single target`
       );
     }
+    const nested = seen.find(
+      (other) => path.startsWith(`${other}.`) || other.startsWith(`${path}.`)
+    );
+    if (nested !== void 0) {
+      throw new Error(
+        `${blockName}: ui.fields["${nested}"] and ui.fields["${path}"] both set \`data\`, but their paths overlap \u2014 two holes over one value have no defined order of application`
+      );
+    }
+    seen.push(path);
   }
 }
 
@@ -709,18 +761,161 @@ function parseMatchKind(route) {
   return "exact";
 }
 
+// src/defineStandardSchema.ts
+var STANDARD_SCHEMA_VERSION = 1;
+function defineStandardSchema(issuesOf, jsonSchemaOf) {
+  return {
+    "~standard": {
+      version: STANDARD_SCHEMA_VERSION,
+      vendor: "nubbin",
+      validate: (value) => {
+        const issues = issuesOf(value);
+        return issues.length > 0 ? { issues } : { value };
+      },
+      jsonSchema: { input: jsonSchemaOf, output: jsonSchemaOf }
+    }
+  };
+}
+
+// src/richText.constants.ts
+var RICH_TEXT_MARKS = ["strong", "em", "code"];
+var RICH_TEXT_BLOCK_KINDS = ["paragraph", "listItem"];
+var RICH_TEXT_SPAN_KEYS = ["text", "marks", "href"];
+var RICH_TEXT_BLOCK_KEYS = ["kind", "spans"];
+
+// src/isRichTextBlockKind.ts
+function isRichTextBlockKind(value) {
+  return RICH_TEXT_BLOCK_KINDS.some((kind) => kind === value);
+}
+
+// src/nestedSchemaIssues.ts
+function nestedSchemaIssues(schema, value, prefix) {
+  const result = standardValidate(schema, value);
+  if (result.issues === void 0) return [];
+  return result.issues.map((issue) => ({
+    message: issue.message,
+    path: [...prefix, ...issue.path ?? []]
+  }));
+}
+
+// src/isRichTextMark.ts
+function isRichTextMark(value) {
+  return RICH_TEXT_MARKS.some((mark) => mark === value);
+}
+
+// src/richTextMarkIssues.ts
+function richTextMarkIssues(marks) {
+  if (marks === void 0) return [];
+  if (!Array.isArray(marks)) return [{ message: "marks must be an array", path: ["marks"] }];
+  return marks.flatMap(
+    (mark, index) => isRichTextMark(mark) ? [] : [
+      {
+        message: `unknown mark ${JSON.stringify(mark)}; expected one of ${RICH_TEXT_MARKS.join(", ")}`,
+        path: ["marks", index]
+      }
+    ]
+  );
+}
+
+// src/unexpectedKeyIssues.ts
+function unexpectedKeyIssues(value, allowed) {
+  return Object.keys(value).filter((key) => !allowed.includes(key)).map((key) => ({ message: `unexpected key "${key}"`, path: [key] }));
+}
+
+// src/richTextSpanIssues.ts
+function richTextSpanIssues(value) {
+  if (!isUnknownProps(value)) return [{ message: "a span must be an object", path: [] }];
+  const issues = [];
+  if (typeof value.text !== "string") {
+    issues.push({ message: "text must be a string", path: ["text"] });
+  }
+  issues.push(...richTextMarkIssues(value.marks));
+  if (value.href !== void 0 && typeof value.href !== "string") {
+    issues.push({ message: "href must be a string", path: ["href"] });
+  }
+  issues.push(...unexpectedKeyIssues(value, RICH_TEXT_SPAN_KEYS));
+  return issues;
+}
+
+// src/richTextSpanSchema.ts
+var richTextSpanSchema = defineStandardSchema(richTextSpanIssues, () => ({
+  type: "object",
+  properties: {
+    text: { type: "string" },
+    marks: { type: "array", items: { type: "string", enum: [...RICH_TEXT_MARKS] } },
+    href: { type: "string" }
+  },
+  required: ["text"],
+  additionalProperties: false
+}));
+
+// src/richTextBlockIssues.ts
+function richTextBlockIssues(value) {
+  if (!isUnknownProps(value)) return [{ message: "a block must be an object", path: [] }];
+  const issues = [];
+  if (!isRichTextBlockKind(value.kind)) {
+    issues.push({
+      message: `unknown kind ${JSON.stringify(value.kind)}; expected one of ${RICH_TEXT_BLOCK_KINDS.join(", ")}`,
+      path: ["kind"]
+    });
+  }
+  if (Array.isArray(value.spans)) {
+    issues.push(
+      ...value.spans.flatMap(
+        (span, index) => nestedSchemaIssues(richTextSpanSchema, span, ["spans", index])
+      )
+    );
+  } else {
+    issues.push({ message: "spans must be an array", path: ["spans"] });
+  }
+  issues.push(...unexpectedKeyIssues(value, RICH_TEXT_BLOCK_KEYS));
+  return issues;
+}
+
+// src/richTextBlockSchema.ts
+var richTextBlockSchema = defineStandardSchema(
+  richTextBlockIssues,
+  (options) => ({
+    type: "object",
+    properties: {
+      kind: { type: "string", enum: [...RICH_TEXT_BLOCK_KINDS] },
+      spans: { type: "array", items: richTextSpanSchema["~standard"].jsonSchema.input(options) }
+    },
+    required: ["kind", "spans"],
+    additionalProperties: false
+  })
+);
+
+// src/richTextIssues.ts
+function richTextIssues(value) {
+  if (!Array.isArray(value)) {
+    return [{ message: "rich text must be an array of blocks", path: [] }];
+  }
+  return value.flatMap(
+    (block, index) => nestedSchemaIssues(richTextBlockSchema, block, [index])
+  );
+}
+
+// src/richTextSchema.ts
+var richTextSchema = defineStandardSchema(richTextIssues, (options) => ({
+  type: "array",
+  items: richTextBlockSchema["~standard"].jsonSchema.input(options)
+}));
+
+// src/richText.ts
+function richText() {
+  return richTextSchema;
+}
+
 // src/setAtPath.ts
 function setAtPath(target, path, value) {
-  const [head, ...rest] = path.split(".");
-  if (head === void 0 || head === "" || head.includes("[]")) {
-    throw new Error(`path "${path}" is not addressable`);
-  }
-  if (rest.length === 0) {
+  const { head, tail } = splitPath(path);
+  if (tail.length === 0) {
     return { ...target, [head]: value };
   }
   const child = target[head];
   const base = typeof child === "object" && child !== null ? child : {};
-  return { ...target, [head]: setAtPath(base, rest.join("."), value) };
+  return { ...target, [head]: setAtPath(base, tail.join("."), value) };
 }
 
 // src/setNodeProp.ts
@@ -742,6 +937,7 @@ export {
   defineCatalog,
   formatCompatibilityReport,
   parseMatchKind,
+  richText,
   setAtPath,
   setNodeProp,
   zodAdapter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubbin/core",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.6",
   "description": "The Nubbin contract: define blocks, split catalog from registry, and compile a page document into an immutable artifact.",
   "keywords": [
     "nubbin",