blockprint 0.1.1 → 0.2.1

package/README.md

@@ -4,6 +4,8 @@
 
 **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)
 
+In production at [ethereal_nature](https://github.com/terzidest/ethereal_nature): storefront pages from DB-stored configs, an admin page editor, and server-side validation via `blockprint/config`.
+
 ## 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.
@@ -58,18 +60,70 @@ The default fallback renders a warning box in development and `null` in producti
 
 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.
 
+A common recipe — shared section chrome, deep-link anchors, and analytics attributes in one place instead of repeated in every block:
+
+```tsx
+<Renderer
+  config={config}
+  registry={registry}
+  wrapBlock={(node, entry) => (
+    <section
+      id={entry.id != null ? String(entry.id) : undefined} // anchor: /page#hero-1
+      data-block={entry.type}                        // analytics / e2e hooks
+      className="mx-auto max-w-5xl px-6 py-10"
+    >
+      {node}
+    </section>
+  )}
+/>
+```
+
+Rendering and schema validation are memoised per `(config, registry)` identity — keep the config referentially stable across renders (state, loader data, `useMemo`) to benefit. Duplicate `id`s warn in development and render under collision-safe keys.
+
 ### `parseConfig(input)`
 
 The boundary validator, exported for consumers who want to fail at fetch time rather than render time. Throws `ConfigError` with the entry index and reason.
 
+### `blockprint/config` — the React-free entry point
+
+Backends that store and validate configs want exactly `parseConfig` and nothing React-shaped. The `blockprint/config` subpath exports `parseConfig`, `ConfigError`, and the `BlockConfig` / `StandardSchemaV1` types with **no React requirement** (the React peer dependency is marked optional):
+
+```ts
+// in a Node server — no react in node_modules required
+import { parseConfig, ConfigError } from "blockprint/config";
+
+app.put("/pages/:slug", (req, res) => {
+  const config = parseConfig(req.body); // throws ConfigError with entry index
+  …
+});
+```
+
+Validate structure on the server, validate props at render time in the client — the registry schemas are the real trust boundary, so the server never needs to know the blocks.
+
 ### Types
 
 - `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. Typed as each schema's *input*, so fields with defaults are optional to write.
+- `PropsFor<R, K>` / `InputFor<R, K>` — one block type's rendered props (schema output) / authorable props (schema input). For building editors and tooling against a registry.
 - `FallbackProps` — the fallback contract.
 - `StandardSchemaV1` — re-exported for custom schema implementations.
 
+## Sharing schemas with an editor app
+
+An admin/editor app usually can't import the rendering app's registry — that would drag every block component (and its styling, routing, data hooks) into the editor bundle. The pattern that works:
+
+1. Put the **zod schemas in a shared package** (`packages/blocks-contract`), importable by both apps.
+2. The rendering app joins schemas with components at the edge: `createRegistry({ hero: { component: Hero, schema: heroSchema } })`.
+3. The editor imports only the schemas (labels, defaults, field shapes) and `blockprint/config` for structure — never the components.
+
+`PropsFor`/`InputFor` give the editor the exact prop types per block without any runtime import of the registry.
+
+## Config storage notes
+
+- **Entry-level key order is irrelevant** — the array order is the only order that matters. Storage layers that canonicalize JSON (e.g. Postgres `jsonb` reorders object keys) are fully compatible; don't be alarmed when a round-tripped config diffs at the key level.
+- `parseConfig` strips unknown entry-level keys (only `type`, `props`, `id` survive) and deliberately allows unknown `type` values — unknown block types are the renderer's fallback case, which is what makes configs forward-compatible across deploys.
+
 ## Gotchas
 
 - **`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.

package/dist/Renderer.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactNode } from "react";
-import type { BlockConfig, BlocksShape, FallbackProps, Registry } from "./types";
+import type { BlockConfig, BlocksShape, FallbackProps, Registry } from "./types.js";
 export interface RendererProps<T extends BlocksShape> {
     /** Untrusted input; the outer shape is validated internally. */
     config: unknown;

package/dist/Renderer.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Fragment } from "react";
-import { parseConfig } from "./parseConfig";
-import { DefaultFallback } from "./fallback";
+import { Fragment, useMemo } from "react";
+import { parseConfig } from "./parseConfig.js";
+import { DefaultFallback } from "./fallback.js";
+import { isDev } from "./env.js";
+// StrictMode double-invokes render (and therefore the memo) in development;
+// remember what we've already warned about so each duplicate id logs once.
+const warnedDuplicateIds = new Set();
 // `memo`/`forwardRef` components are exotic objects, not functions, so the
 // bare-vs-definition split must discriminate on the `component` key.
 function resolveDef(def) {
@@ -10,37 +14,92 @@ function resolveDef(def) {
     }
     return { component: def };
 }
-export function Renderer({ config, registry, fallback, wrapBlock, }) {
-    const Fallback = fallback ?? DefaultFallback;
+function prepare(config, registry) {
     const entries = parseConfig(config);
+    const seenKeys = new Set();
     return entries.map((entry, index) => {
-        const key = entry.id ?? `${entry.type}-${index}`;
-        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) {
+        let key = entry.id ?? `${entry.type}-${index}`;
+        if (seenKeys.has(key)) {
+            if (isDev() && !warnedDuplicateIds.has(key)) {
+                warnedDuplicateIds.add(key);
+                console.warn(`blockprint: duplicate block id "${key}" at config[${index}]; ids should be unique per config`);
+            }
+            key = `${key}__dup${index}`;
+        }
+        seenKeys.add(key);
+        if (!Object.hasOwn(registry.blocks, entry.type)) {
+            return {
+                key,
+                entry,
+                kind: "fallback",
+                fallbackProps: {
+                    reason: "unknown-type",
+                    type: entry.type,
+                    props: entry.props,
+                },
+            };
+        }
+        const { component, schema } = resolveDef(registry.blocks[entry.type]);
+        if (!schema) {
+            return {
+                key,
+                entry,
+                kind: "block",
+                component,
+                props: entry.props,
+            };
+        }
         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",
-                    },
-                ] }));
+            return {
+                key,
+                entry,
+                kind: "fallback",
+                fallbackProps: {
+                    reason: "invalid-props",
+                    type: entry.type,
+                    props: entry.props,
+                    issues: [
+                        {
+                            message: "schema validated asynchronously; blockprint only supports synchronous schemas",
+                        },
+                    ],
+                },
+            };
         }
         if (result.issues) {
-            return (_jsx(Fallback, { reason: "invalid-props", type: entry.type, props: entry.props, issues: result.issues }));
+            return {
+                key,
+                entry,
+                kind: "fallback",
+                fallbackProps: {
+                    reason: "invalid-props",
+                    type: entry.type,
+                    props: entry.props,
+                    issues: result.issues,
+                },
+            };
         }
-        props = result.value;
-    }
-    return _jsx(Component, { ...props });
+        return {
+            key,
+            entry,
+            kind: "block",
+            component,
+            props: result.value,
+        };
+    });
+}
+export function Renderer({ config, registry, fallback, wrapBlock, }) {
+    const Fallback = fallback ?? DefaultFallback;
+    // Parsing and schema validation run once per (config, registry) identity,
+    // not on every render; a consumer recreating the config array each render
+    // opts out of the caching, not the correctness.
+    const prepared = useMemo(() => prepare(config, registry), [config, registry]);
+    return prepared.map((item, index) => {
+        const node = item.kind === "block" ? (_jsx(item.component, { ...item.props })) : (_jsx(Fallback, { ...item.fallbackProps }));
+        // The key lives on a Fragment so it survives whatever wrapBlock returns.
+        return (_jsx(Fragment, { children: wrapBlock ? wrapBlock(node, item.entry, index) : node }, item.key));
+    });
 }

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * React-free entry point (`blockprint/config`): the boundary validator and
+ * config types, importable from Node backends without a React peer. Keep
+ * this module (and its imports) free of React — servers validating stored
+ * configs want exactly this and nothing more.
+ */
+export { parseConfig, ConfigError } from "./parseConfig.js";
+export type { BlockConfig } from "./types.js";
+export type { StandardSchemaV1 } from "./standard-schema.js";

package/dist/config.js

@@ -0,0 +1,7 @@
+/**
+ * React-free entry point (`blockprint/config`): the boundary validator and
+ * config types, importable from Node backends without a React peer. Keep
+ * this module (and its imports) free of React — servers validating stored
+ * configs want exactly this and nothing more.
+ */
+export { parseConfig, ConfigError } from "./parseConfig.js";

package/dist/createRegistry.d.ts

@@ -1,6 +1,6 @@
 import type { ComponentType } from "react";
-import type { StandardSchemaV1 } from "./standard-schema";
-import type { BlocksShape, Registry } from "./types";
+import type { StandardSchemaV1 } from "./standard-schema.js";
+import type { BlocksShape, Registry } from "./types.js";
 /**
  * Maps every compatible entry to `unknown` (an identity when intersected) and
  * every entry whose schema output is not assignable to its component's props

package/dist/env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * True outside production builds. Guarded so a browser without a bundler
+ * defining `process` gets `false` instead of a ReferenceError.
+ */
+export declare function isDev(): boolean;

package/dist/env.js

@@ -0,0 +1,7 @@
+/**
+ * True outside production builds. Guarded so a browser without a bundler
+ * defining `process` gets `false` instead of a ReferenceError.
+ */
+export function isDev() {
+    return typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+}

package/dist/fallback.d.ts

@@ -1,2 +1,2 @@
-import type { FallbackProps } from "./types";
+import type { FallbackProps } from "./types.js";
 export declare function DefaultFallback(props: FallbackProps): import("react").JSX.Element | null;

package/dist/fallback.js

@@ -1,6 +1,7 @@
 import { jsxs as _jsxs } from "react/jsx-runtime";
+import { isDev } from "./env.js";
 export function DefaultFallback(props) {
-    if (process.env.NODE_ENV === "production") {
+    if (!isDev()) {
         return null;
     }
     const detail = props.reason === "invalid-props"

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { createRegistry } from "./createRegistry";
-export { Renderer } from "./Renderer";
-export type { RendererProps } from "./Renderer";
-export { parseConfig, ConfigError } from "./parseConfig";
-export type { BlockConfig, BlockDef, BlocksShape, ConfigFor, FallbackProps, Registry, } from "./types";
-export type { StandardSchemaV1 } from "./standard-schema";
+export { createRegistry } from "./createRegistry.js";
+export { Renderer } from "./Renderer.js";
+export type { RendererProps } from "./Renderer.js";
+export { parseConfig, ConfigError } from "./parseConfig.js";
+export type { BlockConfig, BlockDef, BlocksShape, ConfigFor, FallbackProps, InputFor, PropsFor, Registry, } from "./types.js";
+export type { StandardSchemaV1 } from "./standard-schema.js";

package/dist/index.js

@@ -1,3 +1,3 @@
-export { createRegistry } from "./createRegistry";
-export { Renderer } from "./Renderer";
-export { parseConfig, ConfigError } from "./parseConfig";
+export { createRegistry } from "./createRegistry.js";
+export { Renderer } from "./Renderer.js";
+export { parseConfig, ConfigError } from "./parseConfig.js";

package/dist/parseConfig.d.ts

@@ -1,4 +1,4 @@
-import type { BlockConfig } from "./types";
+import type { BlockConfig } from "./types.js";
 export declare class ConfigError extends Error {
     constructor(message: string);
 }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType } from "react";
-import type { StandardSchemaV1 } from "./standard-schema";
+import type { StandardSchemaV1 } from "./standard-schema.js";
 export type AnyComponent = ComponentType<any>;
 export type BlockDef = AnyComponent | {
     component: AnyComponent;
@@ -49,6 +49,17 @@ export type ConfigFor<R extends Registry<BlocksShape>> = R extends Registry<infe
         id?: string | number;
     };
 }[keyof T]> : never;
+/**
+ * The props a given block type's component receives at render time (schema
+ * OUTPUT when a schema exists). For building editors and tooling against a
+ * registry without importing its components' modules at runtime.
+ */
+export type PropsFor<R extends Registry<BlocksShape>, K extends keyof R["blocks"]> = PropsOfDef<R["blocks"][K]>;
+/**
+ * The props a given block type accepts when authoring a config (schema INPUT
+ * when a schema exists — defaulted fields optional).
+ */
+export type InputFor<R extends Registry<BlocksShape>, K extends keyof R["blocks"]> = InputOfDef<R["blocks"][K]>;
 export type FallbackProps = {
     reason: "unknown-type";
     type: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockprint",
-  "version": "0.1.1",
+  "version": "0.2.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",
@@ -17,6 +17,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
     }
   },
   "files": [
@@ -39,14 +43,20 @@
   "devDependencies": {
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.1.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
     "zod": "^4.4.3"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node scripts/fix-dts.mjs",
     "typecheck": "tsc",
     "test": "vitest run"
   }