+
+
+
+
+
+ {INSTALL}
+
+
+
+
+
+ {USAGE}
+
+
+
+
+
+
+
+
+ {OVERRIDE}
+
+
+
+ );
+}
diff --git a/apps/blocks/src/app/blocks/page.tsx b/apps/blocks/src/app/blocks/page.tsx
index fe79855..7230aa1 100644
--- a/apps/blocks/src/app/blocks/page.tsx
+++ b/apps/blocks/src/app/blocks/page.tsx
@@ -34,6 +34,12 @@ const APPLICATION_CATALOG = [
description:
'A full-page console driven by injected endpoints, session state, adapters, and versioned _meta.',
},
+ {
+ href: '/blocks/documents',
+ title: 'JSON documents',
+ description:
+ 'Declarative JSON UI documents rendered by the default widget registry, generated from JSON Schema or database metadata.',
+ },
{
href: '/blocks/ai',
title: 'AI',
diff --git a/apps/blocks/src/app/llms.txt/route.test.ts b/apps/blocks/src/app/llms.txt/route.test.ts
index 7682941..479dda3 100644
--- a/apps/blocks/src/app/llms.txt/route.test.ts
+++ b/apps/blocks/src/app/llms.txt/route.test.ts
@@ -29,6 +29,7 @@ describe('llms.txt', () => {
'/blocks/billing/',
'/blocks/features/',
'/blocks/console-kit/',
+ '/blocks/documents/',
]) {
expect(source).toContain(
`https://constructive-io.github.io/blocks${route}`,
diff --git a/apps/blocks/src/app/llms.txt/route.ts b/apps/blocks/src/app/llms.txt/route.ts
index d668603..dd76628 100644
--- a/apps/blocks/src/app/llms.txt/route.ts
+++ b/apps/blocks/src/app/llms.txt/route.ts
@@ -52,6 +52,12 @@ const surfaceLinks: readonly SurfaceLink[] = [
description:
'Composable tenant-console roots, modules, presets, endpoint contracts, and integration diagnostics.',
},
+ {
+ title: 'JSON documents',
+ path: '/blocks/documents/',
+ description:
+ 'Declarative JSON UI documents plus the default widget registry that renders them, generated from JSON Schema or database metadata.',
+ },
{
title: 'Primitives and bundles',
path: '/blocks/',
diff --git a/apps/blocks/src/app/sitemap.ts b/apps/blocks/src/app/sitemap.ts
index 6d8aadc..785e62e 100644
--- a/apps/blocks/src/app/sitemap.ts
+++ b/apps/blocks/src/app/sitemap.ts
@@ -23,6 +23,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
...SOURCE_BLOCKS.map(({ name }) => `/blocks/${name}`),
...APPLICATION_BLOCKS.map(({ name }) => `/blocks/${name}`),
'/blocks/console-kit',
+ '/blocks/documents',
...BASE_PRIMITIVES.map(({ name }) => `/blocks/ui/${name}`),
'/blocks/billing',
...BILLING_BLOCKS.map(({ name }) => `/blocks/billing/${name}`),
@@ -42,6 +43,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
path === '/blocks/ai' ||
SOURCE_BLOCKS.some(({ name }) => path === `/blocks/${name}`) ||
path === '/blocks/console-kit' ||
+ path === '/blocks/documents' ||
path === '/blocks/billing'
? 0.9
: 0.7,
diff --git a/apps/blocks/src/components/documents-showcase/document-form-demo.tsx b/apps/blocks/src/components/documents-showcase/document-form-demo.tsx
new file mode 100644
index 0000000..2f1bba2
--- /dev/null
+++ b/apps/blocks/src/components/documents-showcase/document-form-demo.tsx
@@ -0,0 +1,78 @@
+'use client';
+
+import { defaultBlockRegistry } from '@constructive-io/blocks-ui';
+import { Card, CardContent } from '@constructive-io/ui';
+import { DocumentRenderer } from 'blocks-renderer';
+import type { JSONSchema } from 'json-schema-to-blocks';
+import { schemaToDocument } from 'json-schema-to-blocks';
+import { useMemo, useState } from 'react';
+
+/**
+ * The JSON Schema is the only input: `json-schema-to-blocks` lowers it to a
+ * document and the default registry renders it, so this page hand-writes no UI
+ * for any of the fields below.
+ */
+const POST_SCHEMA: JSONSchema = {
+ $id: 'post',
+ type: 'object',
+ title: 'Publish a post',
+ required: ['title', 'status'],
+ properties: {
+ title: { type: 'string', title: 'Title', maxLength: 120 },
+ slug: { type: 'string', title: 'Slug', pattern: '^[a-z0-9-]+$' },
+ summary: { type: 'string', title: 'Summary', maxLength: 400 },
+ status: {
+ type: 'string',
+ title: 'Status',
+ enum: ['draft', 'in_review', 'published', 'archived'],
+ },
+ reading_time: {
+ type: 'integer',
+ title: 'Reading time (minutes)',
+ minimum: 1,
+ maximum: 120,
+ },
+ publish_at: { type: 'string', title: 'Publish at', format: 'date-time' },
+ featured: { type: 'boolean', title: 'Featured' },
+ },
+};
+
+export function DocumentFormDemo() {
+ const document = useMemo(
+ () => schemaToDocument(POST_SCHEMA),
+ [],
+ );
+ const [submitted, setSubmitted] = useStateDocuments
++ {TITLE} +
++ {DESCRIPTION} +
+
+
+
+
+
+
+ );
+}
diff --git a/apps/blocks/src/components/site/site-sidebar.tsx b/apps/blocks/src/components/site/site-sidebar.tsx
index 6c58c06..36f77cb 100644
--- a/apps/blocks/src/components/site/site-sidebar.tsx
+++ b/apps/blocks/src/components/site/site-sidebar.tsx
@@ -294,6 +294,11 @@ export const SiteSidebar = forwardRef
+
+
+
+ Generated document
+
+ {JSON.stringify(document, null, 2)}
+
+
+
+ Submitted values
+
+ {submitted
+ ? JSON.stringify(submitted, null, 2)
+ : 'Submit the form. Validation comes from the document constraints, not from this page.'}
+
+
+ 
+
+
+ 
+
+ 
+ 
+ {children}
+
+ );
+}
+
+/**
+ * Markdown source is rendered as pre-wrapped text rather than parsed: a parser
+ * is a dependency and an XSS surface, and a host that wants one registers it.
+ */
+export function MarkdownBlock({ props }: BlockProps) {
+ const content = text(props, 'content', 'text', 'markdown') ?? '';
+
+ return {content}
;
+}
+
+export function StatCardBlock({ props }: BlockProps) {
+ const label = text(props, 'label', 'title') ?? '';
+ const value = props.value;
+ const description = text(props, 'description');
+
+ return (
+
+ {(title || description) && (
+
+ {title &&
+ )}
+ {children}
+
+ );
+}
+
+/**
+ * Submitting delegates to the renderer: it validates every field against the
+ * document's constraints before calling the host's `onSubmit`, so this component
+ * never inspects values itself.
+ */
+export function FormBlock({ node, props, children }: BlockProps) {
+ const { onAction } = useRenderer();
+ const submitLabel = text(props, 'submitLabel') ?? (props.mode === 'update' ? 'Save' : 'Submit');
+
+ return (
+
+ );
+}
+
+export function SectionBlock({ props, children }: BlockProps) {
+ const title = text(props, 'title');
+
+ if (!title) {
+ return {title}
} + {description &&{description}
} +{children}
;
+}
+
+// Spelled out rather than interpolated, because Tailwind only ships classes it
+// can see in the source.
+const SPANS = ['', 'md:col-span-2', 'md:col-span-3', 'md:col-span-4'];
+
+export function GridColumnBlock({ props, children }: BlockProps) {
+ const span = typeof props.span === 'number' ? Math.min(Math.max(props.span, 1), 4) : 1;
+
+ return {children}
;
+}
+
+export function TabsBlock({ node }: BlockProps) {
+ const tabs = node.children ?? [];
+ if (tabs.length === 0) return null;
+
+ const first = tabs[0]!.key;
+
+ return (
+ {children}
;
+}
diff --git a/packages/blocks-ui/src/field.tsx b/packages/blocks-ui/src/field.tsx
new file mode 100644
index 0000000..63a0be4
--- /dev/null
+++ b/packages/blocks-ui/src/field.tsx
@@ -0,0 +1,90 @@
+'use client';
+
+/**
+ * The field plumbing every widget shares: a node's props are presentation
+ * (`label`, `description`, `required`), while its value lives in the renderer's
+ * form state keyed by `props.name`. Widgets therefore never own state; they read
+ * and write the document's.
+ */
+
+import { Field } from '@constructive-io/ui';
+import { useBlockField } from 'blocks-renderer';
+import type { UINodeProps } from 'blocks-schema';
+import { useId } from 'react';
+import type { ReactNode } from 'react';
+
+/** The value/error wiring for one widget node, plus a stable control id. */
+export function useNodeField(props: UINodeProps) {
+ const name = typeof props.name === 'string' ? props.name : undefined;
+ const { value, error, setValue, mode } = useBlockField(name);
+ const id = useId();
+
+ return {
+ name,
+ id,
+ value,
+ error,
+ setValue,
+ /** `edit` is the authoring surface, so widgets are inert there. */
+ disabled: Boolean(props.disabled) || mode === 'edit',
+ required: Boolean(props.required),
+ placeholder: typeof props.placeholder === 'string' ? props.placeholder : undefined,
+ };
+}
+
+export interface FieldShellProps {
+ props: UINodeProps;
+ id: string;
+ error?: string;
+ children: ReactNode;
+}
+
+/**
+ * Label, description, and error chrome around a control. `hidden` fields stay
+ * in the document (they still carry a value) but render nothing.
+ */
+export function FieldShell({ props, id, error, children }: FieldShellProps) {
+ if (props.hidden) return null;
+
+ const label = typeof props.label === 'string' ? props.label : (props.name as string | undefined) ?? '';
+
+ return (
+