blockprint 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Triantafillos Terzidis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# blockprint
+
+Typed, config-driven block rendering for React. See the [repository README](../../README.md) for the full introduction.
+
+## 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, …).
+
+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? />`
+
+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:
+
+1. known type, valid props → the component renders with parsed props;
+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.
+
+### `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.
+
+### 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.
+- `FallbackProps` — the fallback contract.
+- `StandardSchemaV1` — re-exported for custom schema implementations.
+
+## Notes
+
+- 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`.

package/dist/Renderer.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentType, ReactNode } from "react";
+import type { 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>;
+}
+export declare function Renderer<T extends BlocksShape>({ config, registry, fallback, }: RendererProps<T>): ReactNode;

package/dist/Renderer.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { parseConfig } from "./parseConfig";
+import { DefaultFallback } from "./fallback";
+// `memo`/`forwardRef` components are exotic objects, not functions, so the
+// bare-vs-definition split must discriminate on the `component` key.
+function resolveDef(def) {
+    if (typeof def === "object" && def !== null && "component" in def) {
+        return def;
+    }
+    return { component: def };
+}
+export function Renderer({ config, registry, fallback, }) {
+    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 { 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;
+        }
+        return _jsx(Component, { ...props }, key);
+    });
+}

package/dist/createRegistry.d.ts

@@ -0,0 +1,18 @@
+import type { ComponentType } from "react";
+import type { StandardSchemaV1 } from "./standard-schema";
+import type { BlocksShape, Registry } from "./types";
+/**
+ * Maps every compatible entry to `unknown` (an identity when intersected) and
+ * every entry whose schema output is not assignable to its component's props
+ * to an impossible shape — so the type error lands on the offending key with
+ * a message naming it.
+ */
+export type ValidateBlocks<T extends BlocksShape> = {
+    [K in keyof T]: T[K] extends {
+        component: ComponentType<infer P>;
+        schema: StandardSchemaV1<unknown, infer S>;
+    } ? [S] extends [P] ? unknown : {
+        schema: `schema output is not assignable to props of '${K & string}'`;
+    } : unknown;
+};
+export declare function createRegistry<T extends BlocksShape>(blocks: T & ValidateBlocks<T>): Registry<T>;

package/dist/createRegistry.js

@@ -0,0 +1,3 @@
+export function createRegistry(blocks) {
+    return { blocks: blocks };
+}

package/dist/fallback.d.ts

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

package/dist/fallback.js

@@ -0,0 +1,17 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+export function DefaultFallback(props) {
+    if (process.env.NODE_ENV === "production") {
+        return null;
+    }
+    const detail = props.reason === "invalid-props"
+        ? props.issues.map((issue) => issue.message).join("; ")
+        : "no component registered for this type";
+    return (_jsxs("div", { role: "note", style: {
+            border: "1px dashed #c00",
+            borderRadius: 4,
+            padding: "8px 12px",
+            fontFamily: "monospace",
+            fontSize: 13,
+            color: "#c00",
+        }, children: ["blockprint: block \"", props.type, "\" not rendered (", props.reason, "):", " ", detail] }));
+}

package/dist/index.d.ts

@@ -0,0 +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";

package/dist/index.js

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

package/dist/parseConfig.d.ts

@@ -0,0 +1,10 @@
+import type { BlockConfig } from "./types";
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * The single boundary where untrusted input becomes a typed config. Validates
+ * the outer shape only; per-block props are validated against their registered
+ * schema at render time.
+ */
+export declare function parseConfig(input: unknown): BlockConfig[];

package/dist/parseConfig.js

@@ -0,0 +1,29 @@
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/**
+ * The single boundary where untrusted input becomes a typed config. Validates
+ * the outer shape only; per-block props are validated against their registered
+ * schema at render time.
+ */
+export 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 !== undefined && typeof id !== "string" && typeof id !== "number") {
+            throw new ConfigError(`config[${index}].id must be a string or number when present`);
+        }
+        return id === undefined ? { type, props } : { type, props, id };
+    });
+}

package/dist/standard-schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Standard Schema interface (https://standardschema.dev), vendored so
+ * blockprint has zero runtime and zero type-level dependencies. Any library
+ * implementing the spec (zod >= 3.24, valibot, arktype, ...) satisfies it.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type InferInput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"];
+    type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
+}

package/dist/standard-schema.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+import type { ComponentType } from "react";
+import type { StandardSchemaV1 } from "./standard-schema";
+export type AnyComponent = ComponentType<any>;
+export type BlockDef = AnyComponent | {
+    component: AnyComponent;
+    schema?: StandardSchemaV1<unknown, any>;
+};
+export type BlocksShape = Record<string, BlockDef>;
+/**
+ * The props a definition delivers at runtime. When a schema is present it is
+ * the source of truth: the component receives the schema's parsed output.
+ */
+export type PropsOfDef<D> = D extends {
+    schema: StandardSchemaV1<unknown, infer S>;
+} ? S : D extends {
+    component: ComponentType<infer P>;
+} ? P : D extends ComponentType<infer P> ? P : never;
+export interface Registry<T extends BlocksShape> {
+    readonly blocks: T;
+}
+/**
+ * A single entry as it arrives from a CMS. Deliberately open: `type` is any
+ * string, because untrusted configs may contain types the registry has never
+ * seen — those route to the fallback instead of crashing.
+ */
+export interface BlockConfig {
+    type: string;
+    props?: unknown;
+    id?: string | number;
+}
+/**
+ * The closed, fully typed config union for a given registry — for configs
+ * authored in TypeScript rather than fetched from a CMS. Block names
+ * autocomplete and props are checked per block.
+ */
+export type ConfigFor<R extends Registry<BlocksShape>> = R extends Registry<infer T> ? Array<{
+    [K in keyof T]: {
+        type: K;
+        props: PropsOfDef<T[K]>;
+        id?: string | number;
+    };
+}[keyof T]> : never;
+export type FallbackProps = {
+    reason: "unknown-type";
+    type: string;
+    props: unknown;
+} | {
+    reason: "invalid-props";
+    type: string;
+    props: unknown;
+    issues: ReadonlyArray<StandardSchemaV1.Issue>;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "blockprint",
+  "version": "0.0.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/terzidest/blockprint.git",
+    "directory": "packages/blockprint"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "keywords": [
+    "react",
+    "cms",
+    "renderer",
+    "blocks",
+    "page-builder",
+    "typescript",
+    "standard-schema"
+  ],
+  "devDependencies": {
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc",
+    "test": "vitest run"
+  }
+}