@nubbin/react 0.1.0-rc.0 → 0.1.0-rc.4

package/README.md

@@ -0,0 +1,51 @@
+# @nubbin/react
+
+The React render path for Nubbin. It walks a compiled artifact, loads the blocks that artifact
+names, resolves the data holes it declares, and renders them.
+
+```bash
+npm install @nubbin/react@rc
+```
+
+```tsx
+import { defineRegistry, Renderer } from "@nubbin/react";
+
+export const registry = defineRegistry({
+  Hero: () => import("./blocks/Hero").then((m) => m.Hero),
+});
+
+export default async function Page() {
+  const artifact = await resolveArtifact(store, slug);
+  return <Renderer artifact={artifact} registry={registry} />;
+}
+```
+
+Each registry value is an `import()` the bundler can see, which is what gives one chunk per
+block; a route resolves only the names its artifact carries, so the hundredth block costs pages
+that do not use it nothing. A block author types their component as `BlockComponent<HeroProps>`;
+the registry stores it with its props erased, because function parameters are contravariant and
+a shared props type would be assignable from no real component.
+
+`Renderer` is an async server component. It invokes each block and stamps `data-nubbin-node` on
+the element that block returns, which is how the studio maps a node in the tree to a region on
+the page. **A block is therefore a server component returning exactly one root element** — a
+Fragment root or a client reference has no root to stamp, and the renderer throws naming the
+block rather than wrapping it in an element the consumer's layout did not ask for.
+
+Slot children arrive as props: `slots.sections` renders to `props.sections`, an array of
+elements the block places itself.
+
+```tsx
+<Renderer
+  artifact={artifact}
+  registry={registry}
+  resolveHole={async ({ block, path, spec }) => fetchLiveValue(block, path, spec)}
+/>
+```
+
+A hole is a field a block marked as fetched per request or on an interval, which compile
+deliberately left unfrozen; `spec` is `"request"` or `{ revalidate: n }` — exactly what compile
+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.

package/dist/index.d.ts

@@ -1,4 +1,31 @@
-import { FieldHintData, ArtifactNode, UnknownProps } from '@nubbin/core';
+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.
+ */
+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.
+ *
+ * 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.
+ */
+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.
+ *
+ * `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.
+ */
+declare function defineRegistry<R extends BlockRegistry>(registry: R): R;
 
 interface HoleContext {
     route: string;
@@ -16,15 +43,31 @@ interface HoleContext {
 type HoleResolver = (context: HoleContext) => Promise<unknown>;
 
 /**
- * The static path is the fast path: no holes means the frozen props object is returned as-is,
- * with no clone and no resolver call — that absence is asserted, not assumed.
+ * 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.
  *
- * A node declaring holes with no resolver throws naming the node. Rendering a placeholder
- * would put a compile-time artefact in front of a visitor with nothing to notice it.
+ * 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.
+ */
+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.
  */
-declare function resolveNodeHoles(node: ArtifactNode, route: string, resolveHole: HoleResolver | undefined): Promise<UnknownProps>;
+interface RendererProps {
+    artifact: Artifact;
+    registry: BlockRegistry;
+    resolveHole?: HoleResolver | undefined;
+}
 
-/** Copy-on-write down one dotted path. Holes address object fields only; `[]` has no single target. */
-declare function setAtPath(target: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+/**
+ * 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.
+ */
+declare function Renderer({ artifact, registry, resolveHole, }: RendererProps): Promise<ReactElement>;
 
-export { type HoleContext, type HoleResolver, resolveNodeHoles, setAtPath };
+export { type BlockComponent, type BlockRegistry, type HoleContext, type HoleResolver, Renderer, type RendererProps, defineRegistry, loadBlocks };

package/dist/index.js

@@ -1,3 +1,44 @@
+// src/defineRegistry.ts
+function defineRegistry(registry) {
+  return registry;
+}
+
+// src/loadBlocks.ts
+async function loadBlocks(registry, names) {
+  const missing = names.filter((name) => registry[name] === void 0);
+  if (missing.length > 0) {
+    throw new Error(`registry has no importer for: ${missing.join(", ")}`);
+  }
+  const wanted = new Set(names);
+  const loaded = await Promise.all(
+    Object.entries(registry).filter(([name]) => wanted.has(name)).map(async ([name, importer]) => [name, await importer()])
+  );
+  return Object.fromEntries(loaded);
+}
+
+// src/Renderer.ts
+import { createElement, Fragment as Fragment2 } from "react";
+
+// src/invokeBlock.ts
+import { cloneElement, Fragment, isValidElement } from "react";
+async function invokeBlock(component, props, node) {
+  const rendered = await component(props);
+  if (!isValidElement(rendered) || rendered.type === Fragment) {
+    throw new Error(`block "${node.block}" (node ${node.id}) must render exactly one root element`);
+  }
+  return cloneElement(rendered, { "data-nubbin-node": node.id, key: node.id });
+}
+
+// src/renderSlots.ts
+async function renderSlots(slots, renderChild) {
+  const rendered = await Promise.all(
+    Object.entries(slots ?? {}).map(
+      async ([slot, children]) => [slot, await Promise.all(children.map((child) => renderChild(child)))]
+    )
+  );
+  return Object.fromEntries(rendered);
+}
+
 // src/setAtPath.ts
 function setAtPath(target, path, value) {
   const [head, ...rest] = path.split(".");
@@ -28,7 +69,31 @@ async function resolveNodeHoles(node, route, resolveHole) {
   }
   return props;
 }
+
+// src/renderNode.ts
+async function renderNode(node, context) {
+  const component = context.blocks[node.block];
+  if (component === void 0) {
+    throw new Error(`artifact for ${context.route} names "${node.block}" but it was not loaded`);
+  }
+  const props = await resolveNodeHoles(node, context.route, context.resolveHole);
+  const slotProps = await renderSlots(node.slots, (child) => renderNode(child, context));
+  return invokeBlock(component, { ...props, ...slotProps }, node);
+}
+
+// src/Renderer.ts
+async function Renderer({
+  artifact,
+  registry,
+  resolveHole
+}) {
+  const blocks = await loadBlocks(registry, Object.keys(artifact.blockVersions));
+  const context = { route: artifact.route, blocks, resolveHole };
+  const children = await Promise.all(artifact.tree.map((node) => renderNode(node, context)));
+  return createElement(Fragment2, null, children);
+}
 export {
-  resolveNodeHoles,
-  setAtPath
+  Renderer,
+  defineRegistry,
+  loadBlocks
 };

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@nubbin/react",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.4",
+  "description": "The React render path for Nubbin: render a compiled artifact against a block registry.",
+  "keywords": [
+    "nubbin",
+    "react",
+    "page-builder",
+    "cms",
+    "server-components"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/effekt/nubbin.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://effekt.github.io/nubbin/",
+  "bugs": "https://github.com/effekt/nubbin/issues",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -16,12 +32,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@nubbin/core": "0.1.0-rc.0"
+    "@nubbin/core": "0.1.0-rc.4"
   },
   "peerDependencies": {
     "react": ">=19.0.0"
   },
   "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
     "tsup": "8.5.1",
     "typescript": "6.0.3",
     "vitest": "4.1.10"