blockprint 0.1.1 → 0.2.0

package/README.md

@@ -62,14 +62,46 @@ The optional `wrapBlock={(node, entry, index) => …}` prop wraps every rendered
 
 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.ts";
 export interface RendererProps<T extends BlocksShape> {
     /** Untrusted input; the outer shape is validated internally. */
     config: unknown;

package/dist/Renderer.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Fragment } from "react";
-import { parseConfig } from "./parseConfig";
-import { DefaultFallback } from "./fallback";
+import { parseConfig } from "./parseConfig.js";
+import { DefaultFallback } from "./fallback.js";
 // `memo`/`forwardRef` components are exotic objects, not functions, so the
 // bare-vs-definition split must discriminate on the `component` key.
 function resolveDef(def) {

package/dist/chunk-4JB5QQUK.js

@@ -0,0 +1,37 @@
+// src/parseConfig.ts
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function parseConfig(input) {
+  if (!Array.isArray(input)) {
+    throw new ConfigError(
+      `config must be an array, received ${input === null ? "null" : typeof input}`
+    );
+  }
+  return input.map((entry, index) => {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new ConfigError(`config[${index}] must be an object`);
+    }
+    const { type, props, id } = entry;
+    if (typeof type !== "string" || type.length === 0) {
+      throw new ConfigError(
+        `config[${index}].type must be a non-empty string`
+      );
+    }
+    if (id !== void 0 && typeof id !== "string" && typeof id !== "number") {
+      throw new ConfigError(
+        `config[${index}].id must be a string or number when present`
+      );
+    }
+    return id === void 0 ? { type, props } : { type, props, id };
+  });
+}
+
+export {
+  ConfigError,
+  parseConfig
+};
+//# sourceMappingURL=chunk-4JB5QQUK.js.map

package/dist/chunk-4JB5QQUK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/parseConfig.ts"],"sourcesContent":["import type { BlockConfig } from \"./types\";\n\nexport class ConfigError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ConfigError\";\n  }\n}\n\n/**\n * The single boundary where untrusted input becomes a typed config. Validates\n * the outer shape only; per-block props are validated against their registered\n * schema at render time.\n */\nexport function parseConfig(input: unknown): BlockConfig[] {\n  if (!Array.isArray(input)) {\n    throw new ConfigError(\n      `config must be an array, received ${input === null ? \"null\" : typeof input}`,\n    );\n  }\n\n  return input.map((entry, index) => {\n    if (typeof entry !== \"object\" || entry === null || Array.isArray(entry)) {\n      throw new ConfigError(`config[${index}] must be an object`);\n    }\n    const { type, props, id } = entry as Record<string, unknown>;\n    if (typeof type !== \"string\" || type.length === 0) {\n      throw new ConfigError(\n        `config[${index}].type must be a non-empty string`,\n      );\n    }\n    if (id !== undefined && typeof id !== \"string\" && typeof id !== \"number\") {\n      throw new ConfigError(\n        `config[${index}].id must be a string or number when present`,\n      );\n    }\n    return id === undefined ? { type, props } : { type, props, id };\n  });\n}\n"],"mappings":";AAEO,IAAM,cAAN,cAA0B,MAAM;AAAA,EACrC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAOO,SAAS,YAAY,OAA+B;AACzD,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI;AAAA,MACR,qCAAqC,UAAU,OAAO,SAAS,OAAO,KAAK;AAAA,IAC7E;AAAA,EACF;AAEA,SAAO,MAAM,IAAI,CAAC,OAAO,UAAU;AACjC,QAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG;AACvE,YAAM,IAAI,YAAY,UAAU,KAAK,qBAAqB;AAAA,IAC5D;AACA,UAAM,EAAE,MAAM,OAAO,GAAG,IAAI;AAC5B,QAAI,OAAO,SAAS,YAAY,KAAK,WAAW,GAAG;AACjD,YAAM,IAAI;AAAA,QACR,UAAU,KAAK;AAAA,MACjB;AAAA,IACF;AACA,QAAI,OAAO,UAAa,OAAO,OAAO,YAAY,OAAO,OAAO,UAAU;AACxE,YAAM,IAAI;AAAA,QACR,UAAU,KAAK;AAAA,MACjB;AAAA,IACF;AACA,WAAO,OAAO,SAAY,EAAE,MAAM,MAAM,IAAI,EAAE,MAAM,OAAO,GAAG;AAAA,EAChE,CAAC;AACH;","names":[]}

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.ts";
+export type { BlockConfig } from "./types.ts";
+export type { StandardSchemaV1 } from "./standard-schema.ts";

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/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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.ts";
+import type { BlocksShape, Registry } from "./types.ts";
 /**
  * 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/fallback.d.ts

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

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.ts";
+export { Renderer } from "./Renderer.tsx";
+export type { RendererProps } from "./Renderer.tsx";
+export { parseConfig, ConfigError } from "./parseConfig.ts";
+export type { BlockConfig, BlockDef, BlocksShape, ConfigFor, FallbackProps, InputFor, PropsFor, Registry, } from "./types.ts";
+export type { StandardSchemaV1 } from "./standard-schema.ts";

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/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/createRegistry.ts","../src/Renderer.tsx","../src/fallback.tsx"],"sourcesContent":["import type { ComponentType } from \"react\";\nimport type { StandardSchemaV1 } from \"./standard-schema\";\nimport type { BlocksShape, Registry } from \"./types\";\n\n/**\n * Maps every compatible entry to `unknown` (an identity when intersected) and\n * every entry whose schema output is not assignable to its component's props\n * to an impossible shape — so the type error lands on the offending key with\n * a message naming it.\n */\nexport type ValidateBlocks<T extends BlocksShape> = {\n  [K in keyof T]: T[K] extends {\n    component: ComponentType<infer P>;\n    schema: StandardSchemaV1<unknown, infer S>;\n  }\n    ? [S] extends [P]\n      ? unknown\n      : {\n          schema: `schema output is not assignable to props of '${K & string}'`;\n        }\n    : unknown;\n};\n\nexport function createRegistry<T extends BlocksShape>(\n  blocks: T & ValidateBlocks<T>,\n): Registry<T> {\n  return { blocks: blocks as T };\n}\n","import { Fragment } from \"react\";\nimport type { ComponentType, ReactNode } from \"react\";\nimport type { StandardSchemaV1 } from \"./standard-schema\";\nimport type {\n  AnyComponent,\n  BlockConfig,\n  BlocksShape,\n  FallbackProps,\n  Registry,\n} from \"./types\";\nimport { parseConfig } from \"./parseConfig\";\nimport { DefaultFallback } from \"./fallback\";\n\nexport interface RendererProps<T extends BlocksShape> {\n  /** Untrusted input; the outer shape is validated internally. */\n  config: unknown;\n  registry: Registry<T>;\n  fallback?: ComponentType<FallbackProps>;\n  /**\n   * Wraps every rendered entry — blocks and fallbacks alike — with access to\n   * the config entry and its index. The hook point for visual-editing\n   * overlays, analytics boundaries, or per-block chrome.\n   */\n  wrapBlock?: (node: ReactNode, entry: BlockConfig, index: number) => ReactNode;\n}\n\ninterface ResolvedDef {\n  component: AnyComponent;\n  schema?: StandardSchemaV1<unknown, any>;\n}\n\n// `memo`/`forwardRef` components are exotic objects, not functions, so the\n// bare-vs-definition split must discriminate on the `component` key.\nfunction resolveDef(def: BlocksShape[string]): ResolvedDef {\n  if (typeof def === \"object\" && def !== null && \"component\" in def) {\n    return def;\n  }\n  return { component: def };\n}\n\nexport function Renderer<T extends BlocksShape>({\n  config,\n  registry,\n  fallback,\n  wrapBlock,\n}: RendererProps<T>): ReactNode {\n  const Fallback = fallback ?? DefaultFallback;\n  const entries = parseConfig(config);\n\n  return entries.map((entry, index) => {\n    const key = entry.id ?? `${entry.type}-${index}`;\n    const node = renderEntry(entry, registry, Fallback);\n    // The key lives on a Fragment so it survives whatever wrapBlock returns.\n    return (\n      <Fragment key={key}>\n        {wrapBlock ? wrapBlock(node, entry, index) : node}\n      </Fragment>\n    );\n  });\n}\n\nfunction renderEntry(\n  entry: BlockConfig,\n  registry: Registry<BlocksShape>,\n  Fallback: ComponentType<FallbackProps>,\n): ReactNode {\n  if (!Object.hasOwn(registry.blocks, entry.type)) {\n    return (\n      <Fallback reason=\"unknown-type\" type={entry.type} props={entry.props} />\n    );\n  }\n\n  const { component: Component, schema } = resolveDef(\n    registry.blocks[entry.type] as BlocksShape[string],\n  );\n\n  let props = entry.props;\n  if (schema) {\n    const result = schema[\"~standard\"].validate(entry.props);\n    // React render is synchronous; async schemas are a config mistake and\n    // are contained like any other invalid block.\n    if (result instanceof Promise) {\n      return (\n        <Fallback\n          reason=\"invalid-props\"\n          type={entry.type}\n          props={entry.props}\n          issues={[\n            {\n              message:\n                \"schema validated asynchronously; blockprint only supports synchronous schemas\",\n            },\n          ]}\n        />\n      );\n    }\n    if (result.issues) {\n      return (\n        <Fallback\n          reason=\"invalid-props\"\n          type={entry.type}\n          props={entry.props}\n          issues={result.issues}\n        />\n      );\n    }\n    props = result.value;\n  }\n\n  return <Component {...(props as object | undefined)} />;\n}\n","import type { FallbackProps } from \"./types\";\n\n// Ambient declaration instead of @types/node: bundlers replace\n// process.env.NODE_ENV statically, and the library has no other Node surface.\ndeclare const process: { env: { NODE_ENV?: string } };\n\nexport function DefaultFallback(props: FallbackProps) {\n  if (process.env.NODE_ENV === \"production\") {\n    return null;\n  }\n\n  const detail =\n    props.reason === \"invalid-props\"\n      ? props.issues.map((issue) => issue.message).join(\"; \")\n      : \"no component registered for this type\";\n\n  return (\n    <div\n      role=\"note\"\n      style={{\n        border: \"1px dashed #c00\",\n        borderRadius: 4,\n        padding: \"8px 12px\",\n        fontFamily: \"monospace\",\n        fontSize: 13,\n        color: \"#c00\",\n      }}\n    >\n      blockprint: block &quot;{props.type}&quot; not rendered ({props.reason}):{\" \"}\n      {detail}\n    </div>\n  );\n}\n"],"mappings":";;;;;;AAuBO,SAAS,eACd,QACa;AACb,SAAO,EAAE,OAAoB;AAC/B;;;AC3BA,SAAS,gBAAgB;;;ACiBrB;AAXG,SAAS,gBAAgB,OAAsB;AACpD,MAAI,QAAQ,IAAI,aAAa,cAAc;AACzC,WAAO;AAAA,EACT;AAEA,QAAM,SACJ,MAAM,WAAW,kBACb,MAAM,OAAO,IAAI,CAAC,UAAU,MAAM,OAAO,EAAE,KAAK,IAAI,IACpD;AAEN,SACE;AAAA,IAAC;AAAA;AAAA,MACC,MAAK;AAAA,MACL,OAAO;AAAA,QACL,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,SAAS;AAAA,QACT,YAAY;AAAA,QACZ,UAAU;AAAA,QACV,OAAO;AAAA,MACT;AAAA,MACD;AAAA;AAAA,QAC0B,MAAM;AAAA,QAAK;AAAA,QAAsB,MAAM;AAAA,QAAO;AAAA,QAAG;AAAA,QACzE;AAAA;AAAA;AAAA,EACH;AAEJ;;;ADsBM;AArBN,SAAS,WAAW,KAAuC;AACzD,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,eAAe,KAAK;AACjE,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,IAAI;AAC1B;AAEO,SAAS,SAAgC;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAgC;AAC9B,QAAM,WAAW,YAAY;AAC7B,QAAM,UAAU,YAAY,MAAM;AAElC,SAAO,QAAQ,IAAI,CAAC,OAAO,UAAU;AACnC,UAAM,MAAM,MAAM,MAAM,GAAG,MAAM,IAAI,IAAI,KAAK;AAC9C,UAAM,OAAO,YAAY,OAAO,UAAU,QAAQ;AAElD,WACE,oBAAC,YACE,sBAAY,UAAU,MAAM,OAAO,KAAK,IAAI,QADhC,GAEf;AAAA,EAEJ,CAAC;AACH;AAEA,SAAS,YACP,OACA,UACA,UACW;AACX,MAAI,CAAC,OAAO,OAAO,SAAS,QAAQ,MAAM,IAAI,GAAG;AAC/C,WACE,oBAAC,YAAS,QAAO,gBAAe,MAAM,MAAM,MAAM,OAAO,MAAM,OAAO;AAAA,EAE1E;AAEA,QAAM,EAAE,WAAW,WAAW,OAAO,IAAI;AAAA,IACvC,SAAS,OAAO,MAAM,IAAI;AAAA,EAC5B;AAEA,MAAI,QAAQ,MAAM;AAClB,MAAI,QAAQ;AACV,UAAM,SAAS,OAAO,WAAW,EAAE,SAAS,MAAM,KAAK;AAGvD,QAAI,kBAAkB,SAAS;AAC7B,aACE;AAAA,QAAC;AAAA;AAAA,UACC,QAAO;AAAA,UACP,MAAM,MAAM;AAAA,UACZ,OAAO,MAAM;AAAA,UACb,QAAQ;AAAA,YACN;AAAA,cACE,SACE;AAAA,YACJ;AAAA,UACF;AAAA;AAAA,MACF;AAAA,IAEJ;AACA,QAAI,OAAO,QAAQ;AACjB,aACE;AAAA,QAAC;AAAA;AAAA,UACC,QAAO;AAAA,UACP,MAAM,MAAM;AAAA,UACZ,OAAO,MAAM;AAAA,UACb,QAAQ,OAAO;AAAA;AAAA,MACjB;AAAA,IAEJ;AACA,YAAQ,OAAO;AAAA,EACjB;AAEA,SAAO,oBAAC,aAAW,GAAI,OAA8B;AACvD;","names":[]}

package/dist/parseConfig.d.ts

@@ -1,4 +1,4 @@
-import type { BlockConfig } from "./types";
+import type { BlockConfig } from "./types.ts";
 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.ts";
 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.0",
   "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": [
@@ -45,6 +49,11 @@
     "vitest": "^4.1.10",
     "zod": "^4.4.3"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc",