Merge pull request #25 from constructive-io/feat/block-renderer

feat: add blocks-schema and blocks-renderer packages

Author: pyramation

package.json

@@ -10,7 +10,7 @@
   },
   "scripts": {
     "build": "lerna run build",
-    "build:packages": "pnpm --filter @constructive-io/ui build && pnpm --filter @constructive-io/data build && pnpm --filter @constructive-io/command-palette build && pnpm --filter @constructive-io/sheets build && pnpm --filter @constructive-io/schema-builder build",
+    "build:packages": "pnpm --filter @constructive-io/ui build && pnpm --filter @constructive-io/data build && pnpm --filter @constructive-io/command-palette build && pnpm --filter @constructive-io/sheets build && pnpm --filter @constructive-io/schema-builder build && pnpm --filter blocks-schema build && pnpm --filter blocks-renderer build",
     "build:registry": "pnpm --filter @constructive-io/registry build && pnpm check:console-kit-inspector",
     "build:pages": "pnpm build:packages && pnpm build:registry && pnpm --filter blocks build:pages && pnpm pages:artifact",
     "build:storybook": "pnpm --filter @constructive-io/ui build-sb",

packages/blocks-renderer/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Constructive
+
+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.

packages/blocks-renderer/README.md

@@ -0,0 +1,45 @@
+# blocks-renderer
+
+React adapter for `blocks-schema` UI documents: a recursive
+renderer with layerable widget registries, binding resolution, form state, and
+a visible unknown-block fallback.
+
+## Usage
+
+```tsx
+import { DocumentRenderer, composeRegistry } from 'blocks-renderer';
+
+const registry = composeRegistry(
+  baseRegistry,        // shadcn-style primitives
+  appRegistry,         // app-specific blocks
+  documentOverrides,   // per-document swaps
+);
+
+<DocumentRenderer
+  document={document}
+  registry={registry}
+  scope={{ row, user }}
+  initialValues={{ title: 'Draft' }}
+  onSubmit={(values) => save(values)}
+  onAction={(action, event) => runFlow(action)}
+/>;
+```
+
+## Concepts
+
+- **Registry layering** — `composeRegistry(...layers)` merges
+  `type → component` maps left-to-right, later layers winning. Hosts customize
+  widgets (inputs, textareas, rich text, custom blocks) by layering, never by
+  forking the renderer.
+- **Blocks** — every component receives `{ node, props, children }`, where
+  `props` has the node's `bindings` resolved against the current scope and
+  `children` are already rendered.
+- **Bindings** — `{{ path.to.value }}` templates resolve against
+  `scope + values`; a lone placeholder yields the raw value, mixed text
+  interpolates.
+- **Fields** — widget implementations call `useBlockField(name)` for
+  value/error wiring; constraints from the document (`required`, length,
+  range, `pattern`) validate on change and on submit.
+- **Unknown blocks** — unregistered node types render `UnknownBlock`, a
+  visible gap instead of a crash, so documents can name blocks a host has not
+  installed.

packages/blocks-renderer/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "blocks-renderer",
+  "version": "0.1.0",
+  "description": "Recursive React renderer for Constructive Blocks JSON UI documents, with layerable widget registries",
+  "private": false,
+  "license": "MIT",
+  "homepage": "https://constructive-io.github.io/blocks/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/constructive-io/blocks.git",
+    "directory": "packages/blocks-renderer"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/blocks/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint:types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "blocks-schema": "workspace:^"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

packages/blocks-renderer/src/__tests__/renderer.test.tsx

@@ -0,0 +1,129 @@
+import type { UIDocument, UINode } from 'blocks-schema';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { readPath, resolveBinding, resolveNodeProps } from '../bindings';
+import { composeRegistry, registeredTypes } from '../registry';
+import { DocumentRenderer } from '../renderer';
+import type { BlockProps, BlockRegistry } from '../types';
+
+function Passthrough({ node, children }: BlockProps) {
+	return (
+		<div data-type={node.type} data-key={node.key}>
+			{children}
+		</div>
+	);
+}
+
+function Text({ props }: BlockProps) {
+	return <span>{String(props.text ?? '')}</span>;
+}
+
+const registry: BlockRegistry = {
+	Page: Passthrough,
+	Section: Passthrough,
+	Markdown: Text,
+};
+
+function doc(page: UINode): UIDocument {
+	return { formatVersion: '1.0', type: 'UISchema', id: 'doc-1', page };
+}
+
+describe('DocumentRenderer', () => {
+	it('renders the node tree recursively through the registry', () => {
+		const html = renderToStaticMarkup(
+			<DocumentRenderer
+				document={doc({
+					type: 'Page',
+					key: 'page',
+					props: {},
+					children: [
+						{
+							type: 'Section',
+							key: 'intro',
+							props: {},
+							children: [{ type: 'Markdown', key: 'text', props: { text: 'hello' }, children: [] }],
+						},
+					],
+				})}
+				registry={registry}
+			/>,
+		);
+
+		expect(html).toContain('data-key="page"');
+		expect(html).toContain('data-key="intro"');
+		expect(html).toContain('<span>hello</span>');
+	});
+
+	it('falls back to UnknownBlock for unregistered node types', () => {
+		const html = renderToStaticMarkup(
+			<DocumentRenderer
+				document={doc({ type: 'Page', key: 'page', props: {}, children: [
+					{ type: 'HoloDeck', key: 'holo', props: {}, children: [] },
+				] })}
+				registry={registry}
+			/>,
+		);
+
+		expect(html).toContain('data-block-unknown="HoloDeck"');
+		expect(html).toContain('Unknown block: HoloDeck');
+	});
+
+	it('resolves bindings against the external scope', () => {
+		const html = renderToStaticMarkup(
+			<DocumentRenderer
+				document={doc({
+					type: 'Page',
+					key: 'page',
+					props: {},
+					children: [
+						{
+							type: 'Markdown',
+							key: 'text',
+							props: { text: 'static' },
+							bindings: { text: '{{ row.title }}' },
+							children: [],
+						},
+					],
+				})}
+				registry={registry}
+				scope={{ row: { title: 'Bound Title' } }}
+			/>,
+		);
+
+		expect(html).toContain('<span>Bound Title</span>');
+	});
+});
+
+describe('registry layering', () => {
+	it('later layers win', () => {
+		const composed = composeRegistry(registry, { Markdown: Passthrough });
+		expect(composed.Markdown).toBe(Passthrough);
+		expect(composed.Page).toBe(Passthrough);
+		expect(registeredTypes(composed)).toEqual(['Markdown', 'Page', 'Section']);
+	});
+});
+
+describe('bindings', () => {
+	it('reads dotted paths', () => {
+		expect(readPath({ a: { b: { c: 1 } } }, 'a.b.c')).toBe(1);
+		expect(readPath({ a: 1 }, 'a.b')).toBeUndefined();
+	});
+
+	it('returns raw values for single-placeholder expressions', () => {
+		expect(resolveBinding('{{ flag }}', { flag: false })).toBe(false);
+		expect(resolveBinding('Hello {{ name }}!', { name: 'Ada' })).toBe('Hello Ada!');
+		expect(resolveBinding('Hi {{ missing }}.', {})).toBe('Hi .');
+	});
+
+	it('overlays bindings on static props', () => {
+		const node: UINode = {
+			type: 'Markdown',
+			key: 'k',
+			props: { text: 'static', keep: true },
+			bindings: { text: '{{ title }}' },
+			children: [],
+		};
+		expect(resolveNodeProps(node, { title: 'dyn' })).toEqual({ text: 'dyn', keep: true });
+	});
+});

packages/blocks-renderer/src/bindings.ts

@@ -0,0 +1,41 @@
+import type { UINode, UINodeProps } from 'blocks-schema';
+
+const TEMPLATE = /\{\{\s*([^}\s]+)\s*\}\}/g;
+
+/** Read a dotted path (`row.author.name`) out of a scope object. */
+export function readPath(scope: Record<string, unknown>, path: string): unknown {
+	let current: unknown = scope;
+	for (const segment of path.split('.')) {
+		if (current == null || typeof current !== 'object') return undefined;
+		current = (current as Record<string, unknown>)[segment];
+	}
+	return current;
+}
+
+/**
+ * Resolve a binding expression. A template that is exactly one placeholder
+ * yields the raw value (so a boolean or an object survives); a template mixed
+ * with text is interpolated as a string.
+ */
+export function resolveBinding(expression: string, scope: Record<string, unknown>): unknown {
+	const single = expression.match(/^\{\{\s*([^}\s]+)\s*\}\}$/);
+	if (single) {
+		return readPath(scope, single[1]);
+	}
+
+	return expression.replace(TEMPLATE, (_match, path: string) => {
+		const value = readPath(scope, path);
+		return value == null ? '' : String(value);
+	});
+}
+
+/** Apply a node's `bindings` over its static props. */
+export function resolveNodeProps(node: UINode, scope: Record<string, unknown>): UINodeProps {
+	if (!node.bindings) return node.props ?? {};
+
+	const resolved: UINodeProps = { ...(node.props ?? {}) };
+	for (const [prop, expression] of Object.entries(node.bindings)) {
+		resolved[prop] = resolveBinding(expression, scope);
+	}
+	return resolved;
+}

packages/blocks-renderer/src/context.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+import type { ReactNode } from 'react';
+
+import type { RendererContextValue } from './types';
+
+const RendererContext = createContext<RendererContextValue | null>(null);
+
+export function RendererProvider({ children, value }: { children: ReactNode; value: RendererContextValue }) {
+	return <RendererContext.Provider value={value}>{children}</RendererContext.Provider>;
+}
+
+export function useRenderer(): RendererContextValue {
+	const context = useContext(RendererContext);
+	if (!context) {
+		throw new Error('useRenderer must be used within a RendererProvider (or a DocumentRenderer)');
+	}
+	return context;
+}
+
+/**
+ * Resolved props plus the value/error wiring for a field node. Widget
+ * implementations use this instead of reaching into the document themselves.
+ */
+export function useBlockField(name: string | undefined) {
+	const { values, errors, setValue, setError, mode } = useRenderer();
+	if (!name) {
+		return { value: undefined, error: undefined, setValue: () => {}, setError: () => {}, mode };
+	}
+	return {
+		value: values[name],
+		error: errors[name],
+		setValue: (value: unknown) => setValue(name, value),
+		setError: (error: string | null) => setError(name, error),
+		mode,
+	};
+}

packages/blocks-renderer/src/index.ts

@@ -0,0 +1,7 @@
+export { readPath, resolveBinding, resolveNodeProps } from './bindings';
+export { RendererProvider, useBlockField, useRenderer } from './context';
+export { composeRegistry, registeredTypes, resolveBlock } from './registry';
+export { BlockRenderer, DocumentRenderer } from './renderer';
+export type { DocumentRendererProps } from './renderer';
+export { UnknownBlock } from './unknown-block';
+export type { BlockComponent, BlockProps, BlockRegistry, RenderMode, RendererContextValue } from './types';

packages/blocks-renderer/src/registry.ts

@@ -0,0 +1,24 @@
+import type { BlockComponent, BlockRegistry } from './types';
+
+/**
+ * Layer registries left-to-right, later layers winning. This is how a host
+ * customizes rendering: base primitives, then an app registry, then per-document
+ * overrides — no forking of the renderer, and no single global map.
+ */
+export function composeRegistry(...layers: (BlockRegistry | undefined)[]): BlockRegistry {
+	const composed: BlockRegistry = {};
+	for (const layer of layers) {
+		if (!layer) continue;
+		Object.assign(composed, layer);
+	}
+	return composed;
+}
+
+export function resolveBlock(registry: BlockRegistry, type: string): BlockComponent | undefined {
+	return registry[type];
+}
+
+/** Node types the registry can render, sorted for stable output. */
+export function registeredTypes(registry: BlockRegistry): string[] {
+	return Object.keys(registry).sort();
+}