blockprint 0.0.1 → 0.1.1

package/README.md

@@ -1,16 +1,52 @@
 # blockprint
 
-Typed, config-driven block rendering for React. See the [repository README](../../README.md) for the full introduction.
+**Typed, config-driven block rendering for React.** Render arbitrary UI trees from CMS-controlled JSON — with compile-time safety between your components and the config, and runtime validation at the boundary.
+
+**Live demo: [blockprint.terzidest.com](https://blockprint.terzidest.com)** — three completely different pages (commerce, SaaS, editorial) from one renderer and one registry, plus a deliberately broken config showing graceful fallback. · [GitHub](https://github.com/terzidest/blockprint)
+
+## The problem
+
+Content teams compose pages from a fixed set of block types; your app receives JSON like `[{ "type": "hero", "props": { … } }, …]`. Consuming that in React usually collapses into a `switch` on `block.type` — every block imported into every page, props typed `any`, unknown types crashing the page.
+
+blockprint inverts it: you define the blocks and their prop types, register them once, and render any config — including configs containing block types or malformed props you've never seen.
+
+## Usage
+
+```tsx
+import { createRegistry, Renderer } from "blockprint";
+import { z } from "zod";
+
+const HeroBanner = ({ title, subtitle }: { title: string; subtitle?: string }) => (
+  <header><h1>{title}</h1>{subtitle && <p>{subtitle}</p>}</header>
+);
+
+const registry = createRegistry({
+  hero: HeroBanner,                                   // compile-time trust
+  gameGrid: {                                         // runtime guarantee
+    component: GameGrid,
+    schema: z.object({ games: z.array(gameSchema) }),
+  },
+});
+
+// config typically arrives from a CMS at runtime
+<Renderer config={pageConfig} registry={registry} />;
+```
+
+- A registered component whose props don't match its schema is a **compile error on that key**, with a message naming the block — not a runtime crash.
+- Unknown block types and schema-rejected props render a configurable **fallback**; the rest of the page renders normally.
+- Configs authored in TypeScript get block-name autocomplete and per-block prop checking via `ConfigFor<typeof registry>`.
+- **Zero runtime dependencies.** Schemas are typed against [Standard Schema](https://standardschema.dev), so zod (≥ 3.24), valibot, and arktype all work — blockprint depends on none of them.
+- Framework-agnostic: React only. No Next.js/Remix imports; the library ships the mechanism, not the content.
 
 ## API
 
 ### `createRegistry(blocks)`
 
-Builds a typed registry from a map of block-type strings to definitions. A definition is either a bare component or `{ component, schema? }`, where `schema` is any [Standard Schema](https://standardschema.dev) validator (zod ≥ 3.24, valibot, arktype, …).
+Builds a typed registry from a map of block-type strings to definitions. A definition is either a bare component or `{ component, schema? }`, where `schema` is any Standard Schema validator.
 
 When a schema is present it is the source of truth: the component receives the schema's parsed output (so schema defaults become prop defaults), and a component that cannot accept that output is a compile error on the offending key.
 
-### `<Renderer config registry fallback? />`
+### `<Renderer config registry fallback? wrapBlock? />`
 
 Renders a config against a registry. `config` is `unknown` on purpose — the outer shape is validated internally at a single boundary. Every entry resolves to exactly one of:
 
@@ -18,7 +54,9 @@ Renders a config against a registry. `config` is `unknown` on purpose — the ou
 2. unknown type → `fallback` with `{ reason: "unknown-type" }`;
 3. schema-rejected props → `fallback` with `{ reason: "invalid-props", issues }`.
 
-The default fallback renders a warning box in development and `null` in production.
+The default fallback renders a warning box in development and `null` in production — a page that wants visible failure in production must pass its own `fallback`.
+
+The optional `wrapBlock={(node, entry, index) => …}` prop wraps every rendered entry — blocks and fallbacks alike — with access to the config entry and its index. This is the hook point for visual-editing overlays, analytics boundaries, or per-block chrome.
 
 ### `parseConfig(input)`
 
@@ -28,11 +66,16 @@ The boundary validator, exported for consumers who want to fail at fetch time ra
 
 - `Registry<T>` — the registry's captured shape.
 - `BlockConfig` — one untrusted config entry: `{ type: string; props?: unknown; id?: string | number }`.
-- `ConfigFor<R>` — the closed, fully typed config union for a registry; for configs authored in TypeScript.
+- `ConfigFor<R>` — the closed, fully typed config union for a registry, for configs authored in TypeScript. Typed as each schema's *input*, so fields with defaults are optional to write.
 - `FallbackProps` — the fallback contract.
 - `StandardSchemaV1` — re-exported for custom schema implementations.
 
-## Notes
+## Gotchas
 
-- Async schemas are not supported (React render is synchronous); an async validation routes the entry to the fallback with an explanatory issue.
+- **`exactOptionalPropertyTypes` + zod's `.optional()`**: with that compiler flag enabled, a schema field like `z.string().optional()` produces `prop?: string | undefined`, which is not assignable to a component prop declared `prop?: string` — so the registry's compile-time check (correctly) rejects the registration. Either declare such component props as `prop?: string | undefined`, or leave the flag off in the consuming app.
+- **Async schemas are not supported** (React render is synchronous); an async validation routes the entry to the fallback with an explanatory issue.
 - Entries use `id` for React keys when present, falling back to `type-index`.
+
+## License
+
+MIT © [Triantafillos Terzidis](https://github.com/terzidest)

package/dist/Renderer.d.ts

@@ -1,9 +1,15 @@
 import type { ComponentType, ReactNode } from "react";
-import type { BlocksShape, FallbackProps, Registry } from "./types";
+import type { BlockConfig, BlocksShape, FallbackProps, Registry } from "./types";
 export interface RendererProps<T extends BlocksShape> {
     /** Untrusted input; the outer shape is validated internally. */
     config: unknown;
     registry: Registry<T>;
     fallback?: ComponentType<FallbackProps>;
+    /**
+     * Wraps every rendered entry — blocks and fallbacks alike — with access to
+     * the config entry and its index. The hook point for visual-editing
+     * overlays, analytics boundaries, or per-block chrome.
+     */
+    wrapBlock?: (node: ReactNode, entry: BlockConfig, index: number) => ReactNode;
 }
-export declare function Renderer<T extends BlocksShape>({ config, registry, fallback, }: RendererProps<T>): ReactNode;
+export declare function Renderer<T extends BlocksShape>({ config, registry, fallback, wrapBlock, }: RendererProps<T>): ReactNode;

package/dist/Renderer.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment } from "react";
 import { parseConfig } from "./parseConfig";
 import { DefaultFallback } from "./fallback";
 // `memo`/`forwardRef` components are exotic objects, not functions, so the
@@ -9,32 +10,37 @@ function resolveDef(def) {
     }
     return { component: def };
 }
-export function Renderer({ config, registry, fallback, }) {
+export function Renderer({ config, registry, fallback, wrapBlock, }) {
     const Fallback = fallback ?? DefaultFallback;
     const entries = parseConfig(config);
     return entries.map((entry, index) => {
         const key = entry.id ?? `${entry.type}-${index}`;
-        if (!Object.hasOwn(registry.blocks, entry.type)) {
-            return (_jsx(Fallback, { reason: "unknown-type", type: entry.type, props: entry.props }, key));
+        const node = renderEntry(entry, registry, Fallback);
+        // The key lives on a Fragment so it survives whatever wrapBlock returns.
+        return (_jsx(Fragment, { children: wrapBlock ? wrapBlock(node, entry, index) : node }, key));
+    });
+}
+function renderEntry(entry, registry, Fallback) {
+    if (!Object.hasOwn(registry.blocks, entry.type)) {
+        return (_jsx(Fallback, { reason: "unknown-type", type: entry.type, props: entry.props }));
+    }
+    const { component: Component, schema } = resolveDef(registry.blocks[entry.type]);
+    let props = entry.props;
+    if (schema) {
+        const result = schema["~standard"].validate(entry.props);
+        // React render is synchronous; async schemas are a config mistake and
+        // are contained like any other invalid block.
+        if (result instanceof Promise) {
+            return (_jsx(Fallback, { reason: "invalid-props", type: entry.type, props: entry.props, issues: [
+                    {
+                        message: "schema validated asynchronously; blockprint only supports synchronous schemas",
+                    },
+                ] }));
         }
-        const { component: Component, schema } = resolveDef(registry.blocks[entry.type]);
-        let props = entry.props;
-        if (schema) {
-            const result = schema["~standard"].validate(entry.props);
-            // React render is synchronous; async schemas are a config mistake and
-            // are contained like any other invalid block.
-            if (result instanceof Promise) {
-                return (_jsx(Fallback, { reason: "invalid-props", type: entry.type, props: entry.props, issues: [
-                        {
-                            message: "schema validated asynchronously; blockprint only supports synchronous schemas",
-                        },
-                    ] }, key));
-            }
-            if (result.issues) {
-                return (_jsx(Fallback, { reason: "invalid-props", type: entry.type, props: entry.props, issues: result.issues }, key));
-            }
-            props = result.value;
+        if (result.issues) {
+            return (_jsx(Fallback, { reason: "invalid-props", type: entry.type, props: entry.props, issues: result.issues }));
         }
-        return _jsx(Component, { ...props }, key);
-    });
+        props = result.value;
+    }
+    return _jsx(Component, { ...props });
 }

package/dist/types.d.ts

@@ -28,6 +28,15 @@ export interface BlockConfig {
     props?: unknown;
     id?: string | number;
 }
+/**
+ * The props a consumer may author for a definition. With a schema this is the
+ * schema's INPUT type — authored configs are pre-validation data, so fields
+ * with defaults are optional. (The component still receives the parsed
+ * output; see PropsOfDef.)
+ */
+export type InputOfDef<D> = D extends {
+    schema: StandardSchemaV1<infer I, any>;
+} ? I : PropsOfDef<D>;
 /**
  * The closed, fully typed config union for a given registry — for configs
  * authored in TypeScript rather than fetched from a CMS. Block names
@@ -36,7 +45,7 @@ export interface BlockConfig {
 export type ConfigFor<R extends Registry<BlocksShape>> = R extends Registry<infer T> ? Array<{
     [K in keyof T]: {
         type: K;
-        props: PropsOfDef<T[K]>;
+        props: InputOfDef<T[K]>;
         id?: string | number;
     };
 }[keyof T]> : never;

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "blockprint",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Typed, config-driven block renderer for React. Render arbitrary UI trees from untrusted JSON with compile-time registry safety and runtime schema validation.",
   "license": "MIT",
+  "homepage": "https://blockprint.terzidest.com",
+  "bugs": {
+    "url": "https://github.com/terzidest/blockprint/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/terzidest/blockprint.git",