@nubbin/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -22,6 +22,12 @@ interface FieldNode {
     optional: boolean;
     /** Present only for `enum`. */
     members?: readonly string[];
+    /** The schema's own upper bound on a `string` field's length, when it declares one. */
+    maxLength?: number;
+    /** The schema's own lower bound on an `array` field's row count, when it declares one. */
+    minItems?: number;
+    /** The schema's own upper bound on an `array` field's row count, when it declares one. */
+    maxItems?: number;
 }
 /** The contract for reading a schema's field structure — what `defineCatalog` resolves hint
  * paths through, and what an editing surface reads a block's fields from. */
@@ -161,6 +167,31 @@ interface Block<Schema extends StandardSchemaV1 = StandardSchemaV1, Component =
      * registry — two blocks sharing a name are refused.
      */
     name: string;
+    /**
+     * One line saying what the block is for, shown wherever an editing surface lists blocks.
+     * Editor metadata with the same standing as editing hints: it sits beside the schema, never
+     * inside it, and compile never reads it — no artifact carries a description.
+     */
+    description?: string;
+    /**
+     * A single glyph — an emoji or short string the consumer chooses — shown beside the name
+     * wherever an editing surface lists blocks. A string rather than a component, so `core` stays
+     * render-agnostic. Editor metadata like `description`: compile never reads it.
+     */
+    icon?: string;
+    /**
+     * The palette section the block files under, wherever an editing surface groups blocks. An
+     * opaque label the consumer chooses — Nubbin holds no taxonomy of its own, and a surface may
+     * derive a grouping for a block that omits it. Editor metadata like `description`: compile
+     * never reads it.
+     */
+    category?: string;
+    /**
+     * Opaque links keyed by destination — `docs: { figma: "…", storybook: "…" }` — that an editing
+     * surface renders as "Open in {Key}" for the selected block. Nubbin never inspects a URL or
+     * knows what is behind it; the consumer supplies them. Compile never reads it.
+     */
+    docs?: Record<string, string>;
     /**
      * The schema props are validated against, through its own `~standard.validate`. It must answer
      * synchronously; compile refuses a schema that returns a promise.
@@ -352,6 +383,12 @@ interface FieldHint {
      * path, fails registration.
      */
     data?: FieldHintData;
+    /**
+     * Names the control an editing surface renders for the field — `"link"` for a string holding
+     * a destination. Core validates the path and reads nothing else: an unrecognised name falls
+     * back to the field's kind, so a hint never breaks an editor that predates it.
+     */
+    control?: string;
 }
 /**
  * The editing half of a catalog entry: how the studio should treat this block's fields.
@@ -393,6 +430,28 @@ interface CatalogEntry {
      * read through `~standard.jsonSchema`.
      */
     schema: unknown;
+    /**
+     * One line saying what the block is for, shown wherever an editing surface lists blocks. The
+     * serializable twin of `Block.description`, for a studio that fetches the catalog without the
+     * components. Compile never reads it.
+     */
+    description?: string;
+    /**
+     * A single glyph shown beside the name wherever an editing surface lists blocks. The
+     * serializable twin of `Block.icon` — a string, never a component. Compile never reads it.
+     */
+    icon?: string;
+    /**
+     * Opaque links keyed by destination, the serializable twin of `Block.docs`. An editing surface
+     * renders each as "Open in {Key}"; the consumer supplies the URLs. Compile never reads it.
+     */
+    docs?: Record<string, string>;
+    /**
+     * The palette section the block files under, the serializable twin of `Block.category` — an
+     * opaque label the consumer chooses; a surface may derive a grouping for a block that omits
+     * it. Compile never reads it.
+     */
+    category?: string;
     /** Editing hints, keyed by schema path. Omit it and every field is treated as static. */
     ui?: BlockUi;
     /**
@@ -557,8 +616,9 @@ interface PointerMove {
  * repeated `write` as a no-op and a repeated `publish` as an ordinary one so a retried publish
  * succeeds, and by writing each pointer whole — two publishes racing for one route must leave one
  * of them intact, never a blend. `@nubbin/store-fs` is the reference implementation, and
- * `packages/store-fs/src/testing/runArtifactStoreContract.ts` is the suite every implementation
- * is expected to pass.
+ * `runArtifactStoreContract` from `@nubbin/store-fs/testing` is the suite every implementation is
+ * expected to pass — call it with a factory for your store and the guarantees above are executed
+ * rather than read. It needs vitest, which the package declares as an optional peer.
  *
  * @example
  * ```ts
@@ -1331,6 +1391,41 @@ declare function defineCatalog(entries: Record<string, CatalogEntry>): Catalog;
  */
 declare function formatCompatibilityReport(report: CompatibilityReport): string;
 
+/**
+ * The inline emphasis a span may carry. A mark outside this set is a validation issue at the
+ * mark's own path, never a dropped value.
+ */
+type RichTextMark = "strong" | "em" | "code";
+/** The block kinds rich text is built from. A renderer maps each to an element it chooses. */
+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 {
+    /** The literal text of the run. Never markup — a tag here renders as the characters typed. */
+    text: string;
+    /** Emphasis over the whole run. Absent and empty mean the same thing: plain text. */
+    marks?: readonly RichTextMark[];
+    /** Link target for the whole run. Absent leaves the run unlinked. */
+    href?: string;
+}
+/** One block of a rich-text value: its kind, and the ordered spans it reads as. */
+interface RichTextBlock {
+    /** What the block is, which decides how a renderer wraps its spans. */
+    kind: RichTextBlockKind;
+    /** The runs the block reads as, in order. An empty array is a block with no text. */
+    spans: readonly RichTextSpan[];
+}
+/**
+ * An ordered array of blocks — the whole value a `richText()` field holds. An empty array is a
+ * valid empty document.
+ */
+type RichText = readonly RichTextBlock[];
+
+/** Narrows a value to a member of the closed block-kind set. */
+declare function isRichTextBlockKind(value: unknown): value is RichTextBlockKind;
+
+/** Narrows a value to a member of the closed mark set. */
+declare function isRichTextMark(value: unknown): value is RichTextMark;
+
 /**
  * Moves a node into a slot: the reference is taken out of whatever held it — a slot, or the
  * document's roots — and placed in the target slot.
@@ -1496,35 +1591,6 @@ declare function refuse(code: NubbinIssue["code"], message: string, at?: string)
  */
 declare function removeNode(version: DocumentVersion, nodeId: string): DocumentVersion;
 
-/**
- * The inline emphasis a span may carry. A mark outside this set is a validation issue at the
- * mark's own path, never a dropped value.
- */
-type RichTextMark = "strong" | "em" | "code";
-/** The block kinds rich text is built from. A renderer maps each to an element it chooses. */
-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 {
-    /** The literal text of the run. Never markup — a tag here renders as the characters typed. */
-    text: string;
-    /** Emphasis over the whole run. Absent and empty mean the same thing: plain text. */
-    marks?: readonly RichTextMark[];
-    /** Link target for the whole run. Absent leaves the run unlinked. */
-    href?: string;
-}
-/** One block of a rich-text value: its kind, and the ordered spans it reads as. */
-interface RichTextBlock {
-    /** What the block is, which decides how a renderer wraps its spans. */
-    kind: RichTextBlockKind;
-    /** The runs the block reads as, in order. An empty array is a block with no text. */
-    spans: readonly RichTextSpan[];
-}
-/**
- * An ordered array of blocks — the whole value a `richText()` field holds. An empty array is a
- * valid empty document.
- */
-type RichText = readonly RichTextBlock[];
-
 /**
  * A schema `core` writes itself, such as the one `richText()` returns. It satisfies both
  * `StandardSchemaV1` and `StandardJSONSchemaV1`, so a block, a catalog entry or an adapter takes
@@ -1607,6 +1673,11 @@ interface StandardDataSchema<Value> {
  */
 declare function richText(): StandardDataSchema<RichText>;
 
+/** The closed mark set, in the order an editor would offer it. */
+declare const RICH_TEXT_MARKS: readonly ["strong", "em", "code"];
+/** The closed block-kind set. */
+declare const RICH_TEXT_BLOCK_KINDS: readonly ["paragraph", "listItem"];
+
 /**
  * Writes a value at a dotted path in a plain object, copying every level the path passes
  * through. `setNodeProp` edits props with it, and the renderer fills a resolved hole with it.
@@ -1667,4 +1738,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 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 PointerMove, 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 };
+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 PointerMove, RICH_TEXT_BLOCK_KINDS, RICH_TEXT_MARKS, 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, isRichTextBlockKind, isRichTextMark, moveNode, parseMatchKind, refuse, removeNode, richText, setAtPath, setNodeProp, zodAdapter };

package/dist/index.js

@@ -194,6 +194,15 @@ function fieldNodeAt(path, node, optional) {
   if (kind === "enum" && Array.isArray(node.enum)) {
     return { path, kind, optional, members: node.enum.map(String) };
   }
+  if (kind === "string" && typeof node.maxLength === "number") {
+    return { path, kind, optional, maxLength: node.maxLength };
+  }
+  if (kind === "array") {
+    const field = { path, kind, optional };
+    if (typeof node.minItems === "number") field.minItems = node.minItems;
+    if (typeof node.maxItems === "number") field.maxItems = node.maxItems;
+    return field;
+  }
   return { path, kind, optional };
 }
 
@@ -874,7 +883,7 @@ function validateStructure(version, registry) {
 }
 
 // src/version.constants.ts
-var NUBBIN_VERSION = "0.2.0";
+var NUBBIN_VERSION = "0.3.0";
 
 // src/compile.ts
 function compile(version, catalog, registry, route) {
@@ -1044,6 +1053,22 @@ function formatCompatibilityReport(report) {
   return [summary, ...report.incompatible.map(formatRouteIncompatibility)].join("\n");
 }
 
+// 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/isRichTextMark.ts
+function isRichTextMark(value) {
+  return RICH_TEXT_MARKS.some((mark) => mark === value);
+}
+
 // src/withoutSlotChildren.ts
 function withoutSlotChildren(node, removed) {
   const entries = Object.entries(node.slots ?? {});
@@ -1117,17 +1142,6 @@ function defineStandardSchema(issuesOf, 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);
@@ -1138,11 +1152,6 @@ function nestedSchemaIssues(schema, value, prefix) {
   }));
 }
 
-// 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 [];
@@ -1273,6 +1282,8 @@ function setNodeProp(version, nodeId, path, value) {
 export {
   NubbinError,
   NubbinIssueCode,
+  RICH_TEXT_BLOCK_KINDS,
+  RICH_TEXT_MARKS,
   addNode,
   checkCompatibility,
   checkRollback,
@@ -1281,6 +1292,8 @@ export {
   defineBlock,
   defineCatalog,
   formatCompatibilityReport,
+  isRichTextBlockKind,
+  isRichTextMark,
   moveNode,
   parseMatchKind,
   refuse,

package/package.json

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