@nubbin/react 0.1.1 → 0.2.0

package/README.md

@@ -48,4 +48,4 @@ deliberately left unfrozen; `spec` is `"request"` or `{ revalidate: n }` — exa
 wrote. A node with no holes never calls the resolver. A node that declares holes and gets no
 resolver throws naming the node, rather than rendering a compile-time placeholder to a visitor.
 
-<https://effekt.github.io/nubbin/>. MIT.
+Read the [Nubbin documentation](https://nubbin.io) for the complete renderer reference. MIT.

package/dist/index.d.ts

@@ -2,71 +2,335 @@ import { UnknownProps, FieldHintData, Artifact } from '@nubbin/core';
 import { ReactNode, ReactElement } from 'react';
 
 /**
- * `P` is the block's own props, so a block author has a name for their component —
- * `BlockComponent<HeroProps>`. Async is allowed because rendering happens on the server.
+ * The shape a block's component has: props in, markup out. Type a block with it and the render
+ * path's expectations are checked where the block is written rather than where it renders.
+ *
+ * It may be `async`, because a block renders on the server and never in the browser — a block
+ * awaiting its own data is the ordinary case, and the renderer awaits what it returns either way.
+ *
+ * The return type permits any `ReactNode`; the renderer does not. It clones what the block
+ * returned to stamp `data-nubbin-node` on it, so the root has to be exactly one HTML element. A
+ * Fragment, an array, `null`, a string, or a composite such as `<Card>` is refused at render with
+ * `not-one-host-element`, and no type here catches that earlier.
+ *
+ * @typeParam P - The block's own props. Pass `InferProps<typeof schema>` from `@nubbin/core` so
+ *   they are derived from the block's schema rather than declared a second time beside it.
+ *   Defaults to `UnknownProps`, which is what a component is held as once it has come out of a
+ *   registry and lost its own type.
+ *
+ * @example A block typed from the schema that validates it
+ * ```tsx
+ * import type { InferProps } from "@nubbin/core";
+ * import type { BlockComponent } from "@nubbin/react";
+ * import { z } from "zod";
+ *
+ * const heroSchema = z.object({ title: z.string(), tone: z.enum(["light", "dark"]) });
+ *
+ * export const Hero: BlockComponent<InferProps<typeof heroSchema>> = ({ title, tone }) => (
+ *   <section data-tone={tone}>
+ *     <h1>{title}</h1>
+ *   </section>
+ * );
+ * ```
  */
 type BlockComponent<P extends UnknownProps = UnknownProps> = (props: P) => ReactNode | Promise<ReactNode>;
 /**
- * name → lazy importer. A literal map of `import()` calls, so the bundler emits a chunk per block.
+ * A registry as the renderer holds it: block name → a function that imports that block's
+ * component. It is the widened form of what `defineRegistry` returns, keyed by `string` because a
+ * renderer indexes it by whatever names an artifact carries — which no literal type covers.
  *
- * The stored props type is `never` because parameters are contravariant: a component that reads
- * `title` cannot stand in for one obliged to accept any record, so `BlockComponent<UnknownProps>`
- * here would reject every real block ([#88](https://github.com/effekt/nubbin/issues/88)). The
- * render site widens back with a single cast, because it is what holds the props compile
- * validated against the block's schema.
+ * Annotate a variable with it to hand a registry around; build one with `defineRegistry`, which
+ * keeps the literal's own keys where it is written and only widens to this at the render seam.
+ *
+ * The stored component's props are `never`, which is why a value pulled straight out of a
+ * registry cannot be invoked: nothing satisfies `never`. `loadBlocks` is where that is undone, so
+ * load through it rather than calling an importer by hand.
+ *
+ * @example
+ * ```ts
+ * import type { BlockRegistry } from "@nubbin/react";
+ *
+ * const registry: BlockRegistry = {
+ *   Hero: async () => (await import("./blocks/Hero")).Hero,
+ * };
+ *
+ * registry["Hero"]; // `(() => Promise<BlockComponent<never>>) | undefined`
+ * ```
  */
 type BlockRegistry = Record<string, () => Promise<BlockComponent<never>>>;
 
 /**
- * Identity at runtime. The call site's object literal is the point: each value is an `import()`
- * the bundler can see statically, which is what per-block code-splitting rests on.
+ * Declares the registry a render reads: block name → a function importing that block's component.
+ * It hands back the object it was given, unchanged and with the same identity, so the value a
+ * renderer holds is the call site's own literal — which is what a bundler analyses to emit one
+ * chunk per block.
+ *
+ * The return type is the literal's own, so `registry.Hero` is a known key where it is written and
+ * a misspelling is a compile error. Handing it to `Renderer` widens it to {@link BlockRegistry},
+ * where the keys are `string`: the renderer indexes it by whatever names an artifact carries, and
+ * no literal type covers those.
  *
- * `R` is returned rather than `BlockRegistry` so the map keeps its exact keys where it is
- * written. Indexing the widened form by an arbitrary string is the renderer's problem, and the
- * renderer takes `BlockRegistry` for exactly that reason.
+ * There are no schemas here. A block's schema belongs to the authoring side — `defineBlock` and
+ * `defineCatalog` in `@nubbin/core` — and `compile` has already validated every prop against it
+ * before an artifact exists. A registry entry is therefore a component and nothing more: what a
+ * route pulls in is the block, not the schema that judged its props.
+ *
+ * @typeParam R - Inferred from the argument. Widen it deliberately by annotating the variable
+ *   `BlockRegistry`; there is no reason to pass it explicitly.
+ * @param registry - Block name → an importer for that block's component. Write it as an object
+ *   literal of `import()` calls: a specifier assembled at runtime, or a registry spread together
+ *   from variables, defeats the static analysis the per-block splitting rests on. Each key has to
+ *   match the `name` its block was registered under, casing included, because that is the name an
+ *   artifact carries.
+ * @returns The same object. Nothing is copied, frozen or checked — a key naming no real block is
+ *   found when an artifact naming it fails to load, not here.
+ *
+ * @example A registry the bundler can split
+ * ```ts
+ * import { defineRegistry } from "@nubbin/react";
+ *
+ * export const registry = defineRegistry({
+ *   Hero: async () => (await import("./blocks/Hero")).Hero,
+ *   Price: async () => (await import("./blocks/Price")).Price,
+ * });
+ *
+ * registry.Hero; // a known key here — `registry.Herro` does not compile
+ * ```
+ *
+ * @example What the renderer holds instead
+ * ```ts
+ * import type { BlockRegistry } from "@nubbin/react";
+ *
+ * const widened: BlockRegistry = registry;
+ * widened["Anything"]; // `(() => Promise<BlockComponent<never>>) | undefined`
+ * ```
  */
 declare function defineRegistry<R extends BlockRegistry>(registry: R): R;
 
+/**
+ * What the renderer tells a hole resolver about the field it is asking for. One of these reaches
+ * {@link HoleResolver} per hole per render, immediately before the block that reads that field is
+ * invoked.
+ *
+ * @example Route a hole to whichever source owns that field
+ * ```ts
+ * import type { HoleContext } from "@nubbin/react";
+ *
+ * const sourceFor = ({ block, path }: HoleContext) =>
+ *   block === "Price" && path === "amount" ? pricing : cms;
+ * ```
+ */
 interface HoleContext {
+    /**
+     * The route the artifact was compiled for, as `artifact.route` carries it. That is the pattern
+     * a `param` or `prefix` page was published at — `/guides/[city]`, not the `/guides/lisbon` a
+     * request matched against it.
+     */
     route: string;
+    /**
+     * The id of the node whose field this is, stable across recompiles of the same document
+     * element. It is what the renderer stamps into `data-nubbin-node`, so a value traced in the
+     * browser leads back to the resolver call that produced it.
+     */
     nodeId: string;
+    /** The block's registered name — the same name the registry is keyed by. */
     block: string;
+    /**
+     * The field, as the dotted schema path the block's `ui.fields` hint named it: `amount`,
+     * `cta.label`. The resolved value is written back at exactly this path.
+     */
     path: string;
     /** `{ revalidate: n }` — exactly what compile wrote into the artifact. */
     spec: FieldHintData;
 }
 /**
- * Supplied by the consumer. The renderer decides where a value lands; the resolver decides
- * what it is. It receives the spec and never a value — the stored placeholder was dropped at
- * compile, and mapping a lifecycle onto a caching layer belongs to the framework binding.
+ * The consumer's answer to "what goes in this field": one async function, called once per hole
+ * per render, returning the value that field should hold.
+ *
+ * Where the value lands is the renderer's business — it is written back at the hole's dotted path
+ * before the block is invoked, so the block reads it as an ordinary prop and cannot tell a
+ * resolved field from a frozen one. What the value is, and what caching or fetching produces it,
+ * is entirely this function's.
+ *
+ * It is handed the field's spec and never a stored value: `compile` discarded whatever the author
+ * had typed into a field it turned into a hole, so there is no placeholder to fall back on. Turning
+ * `spec.revalidate` into a framework's caching options is the framework binding's job —
+ * `@nubbin/next` ships `holeFetchOptions` for exactly that.
+ *
+ * @param context - The hole being asked for: route, node, block, dotted path and spec. See
+ *   {@link HoleContext}.
+ * @returns The field's value, in the shape the block's schema described at that path. Nothing
+ *   re-validates it — the artifact was validated at compile and this value was not there then —
+ *   so a resolver returning the wrong shape reaches the component unchallenged.
+ * @throws Nothing is caught. A rejection propagates out of `Renderer` and fails the render, rather
+ *   than rendering the node with the field missing.
+ *
+ * @example Map the field's declared lifecycle onto a caching layer
+ * ```ts
+ * import type { HoleResolver } from "@nubbin/react";
+ *
+ * const resolveHole: HoleResolver = async ({ block, path, spec }) => {
+ *   const response = await fetch(`https://api.example.com/${block}/${path}`, {
+ *     next: { revalidate: spec.revalidate },
+ *   });
+ *   return response.json();
+ * };
+ * ```
  */
 type HoleResolver = (context: HoleContext) => Promise<unknown>;
 
 /**
- * Resolves only the named importers, in parallel. The unnamed rest of the registry is never
- * touched — that, plus one chunk per importer, is why the hundredth block costs this route
- * nothing.
+ * Resolves named blocks out of a registry, in parallel, into a map from name to component.
+ * `Renderer` calls it with `Object.keys(artifact.blockVersions)` before it walks the tree; call it
+ * directly to warm a route, or to check a registry against an artifact ahead of serving one.
+ *
+ * Only the named importers run — an importer for a name not asked for is never invoked, so a
+ * registry naming every block in the app costs a route only the blocks its own page uses.
+ *
+ * Every name is checked before any importer runs, so a missing one loads nothing at all: the
+ * result is the whole set or a refusal, never a partial map. The refusal names every block the
+ * registry cannot satisfy, comma-separated in one message.
  *
- * Every missing name is reported at once: an artifact compiled against a registry the app has
- * since shrunk needs each name fixed separately, so failing on the first hides the work.
+ * @param registry - Where the importers come from. Keys it holds and `names` does not are neither
+ *   read nor invoked, so passing the application's whole registry is the intended use.
+ * @param names - The blocks to load, matched against the registry's keys exactly, casing
+ *   included. A name repeated in the list loads its importer once; an empty list resolves to `{}`
+ *   and invokes nothing.
+ * @returns Name → the component that name's importer resolved to, holding exactly the names asked
+ *   for and no others. The components come back typed `BlockComponent`, widened from the
+ *   `BlockComponent<never>` a registry stores — sound at this seam because what reaches them at
+ *   render are props `compile` already validated against that block's schema.
+ * @throws {NubbinError} Coded `block-not-loaded` when the registry has no importer for one or more
+ *   of `names`. It is raised before any importer runs, so nothing has loaded when it lands.
+ * @throws Whatever an importer raises. A dynamic `import()` that fails to resolve propagates
+ *   unchanged, and one importer failing rejects the whole call.
+ *
+ * @example Load the blocks one artifact needs
+ * ```ts
+ * import { loadBlocks } from "@nubbin/react";
+ *
+ * const blocks = await loadBlocks(registry, Object.keys(artifact.blockVersions));
+ * const Hero = blocks.Hero;
+ * if (Hero !== undefined) {
+ *   await Hero({ title: "Summer sale" });
+ * }
+ * ```
+ *
+ * @example Every missing name in one message
+ * ```ts
+ * await loadBlocks(registry, ["Ghost", "Hero", "Phantom"]);
+ * // NubbinError: registry has no importer for: Ghost, Phantom
+ * ```
  */
 declare function loadBlocks(registry: BlockRegistry, names: readonly string[]): Promise<Record<string, BlockComponent>>;
 
 /**
- * `resolveHole` is written `?: HoleResolver | undefined` rather than `?: HoleResolver` because
- * `exactOptionalPropertyTypes` is on: destructuring an absent optional yields `undefined`, and
- * `Renderer` assigns exactly that into `RenderContext`. Callers that omit it still typecheck.
+ * Everything `Renderer` reads. Nothing else on the object is looked at, so a page that carries
+ * extra keys through loses nothing by handing the whole thing over.
+ *
+ * @example
+ * ```tsx
+ * import { Renderer } from "@nubbin/react";
+ * import type { RendererProps } from "@nubbin/react";
+ *
+ * const props: RendererProps = { artifact, registry, resolveHole };
+ * const page = <Renderer {...props} />;
+ * ```
  */
 interface RendererProps {
+    /**
+     * The compiled page to render, as `compile` produced it and a store handed it back. Its
+     * `blockVersions` decides which blocks load, its `tree` is walked in order, and its `route` is
+     * what every hole on the page resolves against. It is read, never mutated, and nothing it
+     * carries is evaluated.
+     */
     artifact: Artifact;
+    /**
+     * Where the blocks come from. It may name far more blocks than this artifact uses — the extra
+     * importers are never invoked — but a name the artifact carries and this omits refuses the
+     * render before any block loads.
+     */
     registry: BlockRegistry;
+    /**
+     * How a hole gets its value. Any artifact whose tree declares one needs it: omit it and that
+     * node refuses rather than rendering without the field. A wholly static artifact renders with no
+     * resolver at all, which is the fast path — the frozen props go through untouched.
+     */
     resolveHole?: HoleResolver | undefined;
 }
 
 /**
- * An async server component. It reads an already-validated artifact — no schema is parsed
- * here, and nothing the artifact carries is evaluated. `blockVersions` is the whole list of
- * blocks the artifact names, so a registry of any size costs this route only those imports.
+ * An async server component that renders one compiled artifact against a registry of blocks. It
+ * loads the blocks the artifact names, walks `artifact.tree` in order, and returns every root
+ * inside a single `Fragment`. It reads nothing and writes nothing — fetching the artifact belongs
+ * to the caller.
+ *
+ * Each node fills its holes, renders its slots, then invokes its block. Holes are filled first
+ * because a block reads a resolved field as an ordinary prop, and a value arriving after the call
+ * would render as `undefined` with nothing to notice it. Slot children reach the block the same
+ * way: the nodes filling `slots.sections` arrive as `props.sections`, an array of elements the
+ * block places itself, with no wrapper invented around them.
+ *
+ * What a block returns is cloned rather than wrapped, so the element the consumer wrote comes
+ * back carrying `data-nubbin-node` and nothing is added to the tree. That is what obliges a block
+ * to return exactly one HTML element.
+ *
+ * Sibling nodes render concurrently — the roots of `tree` and the children of one slot are all in
+ * flight together — while the holes on a single node resolve one after another, in the order the
+ * artifact lists them.
+ *
+ * @param props - The artifact to render, the registry to render it against, and the optional
+ *   `resolveHole`; every field is described on {@link RendererProps}. Only those three are read,
+ *   and none of them is mutated.
+ * @returns One `Fragment` holding one element per entry in `artifact.tree`, in that order. A
+ *   server tree can render the component directly — awaiting it by hand is only needed off the
+ *   render path, such as in a test.
+ *
+ * @throws {NubbinError} Coded `block-not-loaded` when the registry has no importer for a block
+ *   the artifact names, listing every missing name in one message rather than the first. The same
+ *   code covers the narrower case of a node naming a block absent from `blockVersions`, which
+ *   names the node.
+ * @throws {NubbinError} Coded `no-hole-resolver` when a node declares holes and no `resolveHole`
+ *   was given, naming the node. Rendering the node without the field would put a compile-time
+ *   artefact in front of a visitor with nothing to notice it.
+ * @throws {NubbinError} Coded `not-one-host-element` when a block returns anything but a single
+ *   HTML element — a Fragment, an array, `null`, or a composite such as `<Card>`. Cloning a
+ *   composite root succeeds and sets `data-nubbin-node` as a prop the component never spreads, so
+ *   the block would render correctly and be unselectable; the renderer refuses instead.
+ * @throws Whatever an importer, a `resolveHole` call or a block itself raises, unchanged. None of
+ *   them is caught, so a failed hole fails the render rather than rendering the node without it.
+ *
+ * @example Serve whatever is published at a route
+ * ```tsx
+ * import { Renderer, defineRegistry } from "@nubbin/react";
+ * import { notFound } from "next/navigation";
+ *
+ * const registry = defineRegistry({
+ *   Hero: async () => (await import("./blocks/Hero")).Hero,
+ *   Price: async () => (await import("./blocks/Price")).Price,
+ * });
+ *
+ * export default async function Page() {
+ *   const pointer = await store.pointer("/promotions/summer");
+ *   const artifact = pointer === null ? null : await store.read(pointer.hash);
+ *   if (artifact === null) notFound();
+ *   return <Renderer artifact={artifact} registry={registry} resolveHole={resolveHole} />;
+ * }
+ * ```
+ *
+ * @example Render to markup, filling the fields compile left as holes
+ * ```tsx
+ * import { renderToStaticMarkup } from "react-dom/server";
+ *
+ * const html = renderToStaticMarkup(
+ *   await Renderer({
+ *     artifact,
+ *     registry,
+ *     resolveHole: async ({ route, block, path, spec }) =>
+ *       priceFor(route, block, path, spec.revalidate),
+ *   }),
+ * );
+ * ```
  */
 declare function Renderer({ artifact, registry, resolveHole, }: RendererProps): Promise<ReactElement>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubbin/react",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The React render path for Nubbin: render a compiled artifact against a block registry.",
   "keywords": [
     "nubbin",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nubbin/core": "0.1.1"
+    "@nubbin/core": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=19.0.0"