@createcms/core 0.1.1

package/dist/react/blocks.d.ts

@@ -0,0 +1,320 @@
+import { ReactNode } from 'react';
+
+type BlockTreeNode = {
+    blockId: string;
+    type: string;
+    properties: Record<string, unknown>;
+    children: BlockTreeNode[];
+};
+
+/**
+ * One published branch of a root, as a snapshot. Shared by the page-level
+ * variant shape and the block-level A/B `variants` (below) so the two can't
+ * drift. `properties` mirrors the (depth-1 typed) reference `properties`.
+ */
+type PublishedBranchSnapshot<TProps = Record<string, unknown>> = {
+    branchId: string;
+    isControl: boolean;
+    properties: TProps;
+    tree: BlockTreeNode;
+};
+type ResolvedReference<TProps = Record<string, unknown>> = {
+    rootId: string;
+    collection: string;
+    properties: TProps;
+    tree: BlockTreeNode;
+    /**
+     * Present only when this referenced root has a RUNNING A/B test (AB_FANOUT
+     * F2 server fan-out). The server stays a pure, cacheable function: top-level
+     * `tree`/`properties` are the CONTROL branch (a no-JS / AB-disabled client
+     * renders it as-is), and the client pre-render pass (F3) picks the visitor's
+     * variant from `variants` and swaps it in. `variants` includes the control.
+     * An OPTIONAL field (not a discriminated union) so `isResolvedReference` —
+     * which narrows on `tree`/`properties` — keeps matching.
+     */
+    abTest?: {
+        testId: string;
+        trafficPercentage: number;
+        variants: PublishedBranchSnapshot<TProps>[];
+    };
+};
+type BlockTypes = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    date: string;
+    richText: string;
+    image: string;
+    select: string;
+    reference: string;
+};
+/** Reference inference mode: `raw` (write input + getBlockTree editor read) keeps
+ *  a `reference` as its stored rootId string; `resolved` (getPublishedContent)
+ *  surfaces the inlined `ResolvedReference`. */
+type RefMode = 'raw' | 'resolved';
+type BlockPropertyType = keyof BlockTypes;
+type SelectOption = {
+    readonly label: string;
+    readonly value: string;
+};
+type BlockPropertySpec<T extends BlockPropertyType> = {
+    type: T;
+    required?: boolean;
+    defaultValue?: BlockTypes[T];
+    label: string;
+    description?: string;
+    placeholder?: string;
+} & (T extends 'select' ? {
+    options: readonly SelectOption[];
+} : {}) & (T extends 'reference' ? {
+    collection: string;
+} : {});
+/** Discriminated union over all concrete block-property specs. */
+type BlockProperty = {
+    [K in BlockPropertyType]: BlockPropertySpec<K>;
+}[BlockPropertyType];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+/** Extracts the runtime value type for a block property.
+ *  For `select` properties with options, returns the union of option values.
+ *  A `reference` is a rootId string in `raw` mode (write input + editor read) and
+ *  a `ResolvedReference` in `resolved` mode (published read).
+ *  For all other types, returns the corresponding primitive type. */
+type InferPropertyValue<T extends BlockProperty, M extends RefMode = 'raw', TCol extends Record<string, AnyCollectionDefinition> = {}> = T extends {
+    type: 'select';
+    options: readonly {
+        readonly value: infer V extends string;
+    }[];
+} ? V : T extends {
+    type: 'reference';
+    collection: infer C extends string;
+} ? M extends 'resolved' ? C extends keyof TCol ? ResolvedReference<NonNullable<InferBlockProperties<TCol[C]['root']['properties'], 'resolved'>>> : ResolvedReference : string : BlockTypes[T['type']];
+type RequiredPart<T extends Record<string, BlockProperty>, M extends RefMode, TCol extends Record<string, AnyCollectionDefinition>> = {
+    [K in keyof T as T[K] extends {
+        required: true;
+    } ? K : never]: InferPropertyValue<T[K], M, TCol>;
+};
+type OptionalPart<T extends Record<string, BlockProperty>, M extends RefMode, TCol extends Record<string, AnyCollectionDefinition>> = {
+    [K in keyof T as T[K] extends {
+        required: true;
+    } ? never : K]?: InferPropertyValue<T[K], M, TCol>;
+};
+type HasRequiredKeys<T extends Record<string, BlockProperty>> = true extends {
+    [K in keyof T]: T[K] extends {
+        required: true;
+    } ? true : never;
+}[keyof T] ? true : false;
+/** Maps a properties record to its runtime value types, respecting `required`.
+ *  When all properties are optional, the entire input becomes optional (| undefined). */
+type InferBlockProperties<T extends Record<string, BlockProperty>, M extends RefMode = 'raw', TCol extends Record<string, AnyCollectionDefinition> = {}> = HasRequiredKeys<T> extends true ? Simplify<RequiredPart<T, M, TCol> & OptionalPart<T, M, TCol>> : Simplify<RequiredPart<T, M, TCol> & OptionalPart<T, M, TCol>> | undefined;
+/** Scalar property subset usable as an event parameter (no references/media). */
+type ScalarBlockProperty = Extract<BlockProperty, {
+    type: 'string' | 'number' | 'boolean' | 'select' | 'date';
+}>;
+/**
+ * Declares a meaningful event a functional block can emit (e.g. a form's
+ * `submitSuccess`). Living on the block DEFINITION makes it the single source of
+ * truth for the typed `fire(...)` union, the test-creation goal picker, and the
+ * analytics wire name. `name` overrides the GA4/dataLayer wire name (defaults to
+ * `cms_<blockType>_<eventKey>`, computed by the measurement layer). Whether an
+ * event counts as a conversion is decided per test in the UI, not here.
+ */
+type EventDeclaration = {
+    /** Analytics wire-name override (snake_case). Defaults to cms_<type>_<key>. */
+    name?: string;
+    /** Typed parameters carried with the event (scalar only). */
+    params?: Record<string, ScalarBlockProperty>;
+    /** Human label for the goal picker. */
+    label?: string;
+};
+type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TEvents extends Record<string, EventDeclaration> = Record<string, never>> = {
+    properties: TProps;
+    label: string;
+    description?: string;
+    previewImageUrl?: string;
+    /** Events this (functional) block can emit — see {@link EventDeclaration}. */
+    events?: TEvents;
+} & ({
+    allowChildren?: false;
+} | {
+    allowChildren: true;
+    allowedChildBlocks?: string[];
+});
+type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
+type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
+    properties: TProps;
+};
+type SlugConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    root: string;
+    allowRoot?: boolean;
+    normalize?: boolean;
+    nested?: boolean;
+};
+type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition> = Record<string, AnyBlockDefinition>> = {
+    slug?: SlugConfig;
+    root: RootDefinition<TProps>;
+    blocks?: TBlocks;
+    label: string;
+    description?: string;
+    /**
+     * Marks this collection as one whose roots are meant to be EMBEDDED into other
+     * roots via a `reference` property (a "reusable block" library). Purely an
+     * ergonomic hint — it informs editor pickers and which endpoints to surface; it
+     * NEVER gates safety (the delete-in-use guard protects every referenced root
+     * regardless of this flag). Any collection can still be a reference target.
+     */
+    reusableBlock?: boolean;
+};
+type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
+
+/** Props passed to each block component in the renderer map. The renderer
+ *  consumes RESOLVED content (getPublishedContent), so `reference` properties
+ *  surface as `ResolvedReference` objects — the `resolved` inference mode. */
+type BlockComponentProps<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
+    properties: InferBlockProperties<TProps, 'resolved'>;
+    children: ReactNode;
+    blockId: string;
+    node: BlockTreeNode;
+};
+/** Shorthand to derive block component props from a collection definition. */
+type BlockProps<TCollection extends {
+    blocks: Record<string, AnyBlockDefinition>;
+}, TBlock extends keyof TCollection['blocks'] & string> = BlockComponentProps<TCollection['blocks'][TBlock]['properties']>;
+type BlockComponentMap<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks & string]: (props: BlockComponentProps<TBlocks[K]['properties']>) => ReactNode;
+};
+declare function isResolvedReference(value: unknown): value is ResolvedReference;
+/**
+ * Opaque handle returned by `createBlocksMap`. Pass it to `<BlocksRenderer>`.
+ * Carries the React component map AND the per-block-type event declarations
+ * (the runtime half of the M2a typed-events seam) so the renderer can tell a
+ * functional block (one that declared `events`) from a presentational one.
+ */
+type BlocksMap = {
+    readonly __brand: 'BlocksMap';
+    readonly _components: Record<string, (props: any) => ReactNode>;
+    readonly _events: Record<string, Record<string, EventDeclaration>>;
+};
+/**
+ * Extracts the per-block-type event declarations from a collection definition —
+ * the runtime half of the M2a typed-events seam. Only functional blocks (those
+ * that declared a non-empty `events`) get an entry; presentational blocks are
+ * omitted, so `type in blocksMap._events` is the runtime "is this block
+ * functional?" test the M3 BlockTracker keys on.
+ */
+declare function extractBlockEvents(blocks: Record<string, AnyBlockDefinition> | undefined): Record<string, Record<string, EventDeclaration>>;
+/**
+ * Creates a type-safe block component map for a CMS collection. Pass the
+ * collection DEFINITION (the runtime object) as the single source of truth:
+ * the component-prop types are inferred from its blocks, and its `events`
+ * declarations are carried into the map for the M3 tracker.
+ *
+ * @example
+ * ```tsx
+ * import { createBlocksMap } from '@createcms/core/react';
+ * import { pagesCollection } from '@/cms/collections/pages/definition';
+ *
+ * export const pageBlocks = createBlocksMap(pagesCollection, {
+ *   headline: ({ properties }) => <h1>{properties.text}</h1>,
+ *   hero: ({ properties, children }) => (
+ *     <section>
+ *       <h1>{properties.headline}</h1>
+ *       {children}
+ *     </section>
+ *   ),
+ * });
+ * ```
+ */
+declare function createBlocksMap<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(collection: CollectionDefinition<TProps, TBlocks>, components: BlockComponentMap<TBlocks>): BlocksMap;
+/**
+ * Renders a `BlockTreeNode` tree using a block component map.
+ *
+ * Delegates to the reference-aware `renderContentNode`, which is a strict
+ * superset: for the reference-free trees that `getBlockTree` produces it
+ * behaves identically, and it additionally resolves inline references should a
+ * tree ever carry them.
+ *
+ * @example
+ * ```tsx
+ * import { BlocksRenderer } from '@createcms/core/react';
+ * import { pageBlocks } from '@/lib/blocks/pages';
+ *
+ * export default async function Page() {
+ *   const tree = await cms.api.pages.getBlockTree(...);
+ *   return <BlocksRenderer blocks={pageBlocks} tree={tree} />;
+ * }
+ * ```
+ */
+declare function BlocksRenderer({ blocks, tree, }: {
+    blocks: BlocksMap;
+    tree: BlockTreeNode;
+}): ReactNode;
+/**
+ * Creates a type-safe block renderer component for a CMS collection.
+ * Convenience shorthand that combines `createBlocksMap` + `BlocksRenderer`.
+ *
+ * @example
+ * ```tsx
+ * import { createBlocksRenderer } from '@createcms/core/react';
+ * import { pagesCollection } from '@/cms/collections/pages/definition';
+ *
+ * const PageBlocks = createBlocksRenderer(pagesCollection, {
+ *   headline: ({ properties }) => <h1>{properties.text}</h1>,
+ *   hero: ({ properties, children }) => (
+ *     <section>
+ *       <h1>{properties.headline}</h1>
+ *       {children}
+ *     </section>
+ *   ),
+ * });
+ *
+ * // In a page component:
+ * <PageBlocks tree={tree} />
+ * ```
+ */
+declare function createBlocksRenderer<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(collection: CollectionDefinition<TProps, TBlocks>, components: BlockComponentMap<TBlocks>): {
+    ({ tree }: {
+        tree: BlockTreeNode;
+    }): ReactNode;
+    displayName: string;
+};
+/**
+ * Renders a block tree with automatic reference resolution.
+ *
+ * When a block has a `reference` property that was resolved by
+ * `getPublishedContent`, the referenced block tree is rendered inline
+ * using the same block components. Data-only references (collections
+ * without blocks) are available directly in `properties`.
+ *
+ * @example
+ * ```tsx
+ * import { createContentRenderer } from '@createcms/core/react';
+ * import { pagesCollection } from '@/cms/collections/pages/definition';
+ *
+ * const RenderPage = createContentRenderer(pagesCollection, {
+ *   headline: ({ properties }) => <h1>{properties.text}</h1>,
+ *   paragraph: ({ properties }) => <p>{properties.text}</p>,
+ *   authorCard: ({ properties }) => (
+ *     <div>{properties.author.properties.name}</div>
+ *   ),
+ *   // No component needed for blocks that just embed a referenced tree —
+ *   // the referenced content renders inline automatically.
+ * });
+ *
+ * // Usage:
+ * <RenderPage tree={tree} />
+ * ```
+ */
+declare function createContentRenderer<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(collection: CollectionDefinition<TProps, TBlocks>, components: Partial<BlockComponentMap<TBlocks>>): {
+    ({ tree, }: {
+        tree: BlockTreeNode;
+    }): ReactNode;
+    displayName: string;
+};
+
+export { BlocksRenderer, createBlocksMap, createBlocksRenderer, createContentRenderer, extractBlockEvents, isResolvedReference };
+export type { BlockComponentProps, BlockProps, BlocksMap };

package/dist/react/blocks.js

@@ -0,0 +1,226 @@
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
+import { BlockTracker } from './tracking.js';
+
+function isResolvedReference(value) {
+    return typeof value === 'object' && value !== null && 'rootId' in value && 'collection' in value && 'tree' in value && 'properties' in value;
+}
+/**
+ * Extracts the per-block-type event declarations from a collection definition —
+ * the runtime half of the M2a typed-events seam. Only functional blocks (those
+ * that declared a non-empty `events`) get an entry; presentational blocks are
+ * omitted, so `type in blocksMap._events` is the runtime "is this block
+ * functional?" test the M3 BlockTracker keys on.
+ */ function extractBlockEvents(blocks) {
+    const out = {};
+    if (!blocks) return out;
+    for (const [type, def] of Object.entries(blocks)){
+        if (def.events && Object.keys(def.events).length > 0) {
+            // Shallow-copy so the map OWNS its event records (the `readonly` on
+            // BlocksMap._events is a real contract): never alias the live collection
+            // definition, so a consumer can't mutate it through the map.
+            out[type] = {
+                ...def.events
+            };
+        }
+    }
+    return out;
+}
+/**
+ * Creates a type-safe block component map for a CMS collection. Pass the
+ * collection DEFINITION (the runtime object) as the single source of truth:
+ * the component-prop types are inferred from its blocks, and its `events`
+ * declarations are carried into the map for the M3 tracker.
+ *
+ * @example
+ * ```tsx
+ * import { createBlocksMap } from '@createcms/core/react';
+ * import { pagesCollection } from '@/cms/collections/pages/definition';
+ *
+ * export const pageBlocks = createBlocksMap(pagesCollection, {
+ *   headline: ({ properties }) => <h1>{properties.text}</h1>,
+ *   hero: ({ properties, children }) => (
+ *     <section>
+ *       <h1>{properties.headline}</h1>
+ *       {children}
+ *     </section>
+ *   ),
+ * });
+ * ```
+ */ function createBlocksMap(collection, components) {
+    return {
+        __brand: 'BlocksMap',
+        _components: components,
+        _events: extractBlockEvents(collection.blocks)
+    };
+}
+// ============================================================================
+// BlocksRenderer
+// ============================================================================
+/**
+ * Renders a `BlockTreeNode` tree using a block component map.
+ *
+ * Delegates to the reference-aware `renderContentNode`, which is a strict
+ * superset: for the reference-free trees that `getBlockTree` produces it
+ * behaves identically, and it additionally resolves inline references should a
+ * tree ever carry them.
+ *
+ * @example
+ * ```tsx
+ * import { BlocksRenderer } from '@createcms/core/react';
+ * import { pageBlocks } from '@/lib/blocks/pages';
+ *
+ * export default async function Page() {
+ *   const tree = await cms.api.pages.getBlockTree(...);
+ *   return <BlocksRenderer blocks={pageBlocks} tree={tree} />;
+ * }
+ * ```
+ */ function BlocksRenderer({ blocks, tree }) {
+    return renderContentNode(tree, blocks._components, blocks._events);
+}
+// ============================================================================
+// createBlocksRenderer (convenience shorthand)
+// ============================================================================
+/**
+ * Creates a type-safe block renderer component for a CMS collection.
+ * Convenience shorthand that combines `createBlocksMap` + `BlocksRenderer`.
+ *
+ * @example
+ * ```tsx
+ * import { createBlocksRenderer } from '@createcms/core/react';
+ * import { pagesCollection } from '@/cms/collections/pages/definition';
+ *
+ * const PageBlocks = createBlocksRenderer(pagesCollection, {
+ *   headline: ({ properties }) => <h1>{properties.text}</h1>,
+ *   hero: ({ properties, children }) => (
+ *     <section>
+ *       <h1>{properties.headline}</h1>
+ *       {children}
+ *     </section>
+ *   ),
+ * });
+ *
+ * // In a page component:
+ * <PageBlocks tree={tree} />
+ * ```
+ */ function createBlocksRenderer(collection, components) {
+    const blocksMap = createBlocksMap(collection, components);
+    function Renderer({ tree }) {
+        return /*#__PURE__*/ jsx(BlocksRenderer, {
+            blocks: blocksMap,
+            tree: tree
+        });
+    }
+    Renderer.displayName = `BlocksRenderer(${collection.label})`;
+    return Renderer;
+}
+// ============================================================================
+// ContentRenderer (reference-aware tree rendering)
+// ============================================================================
+function renderContentNode(node, components, events, fromReference = false) {
+    const renderedChildren = node.children.map((child)=>renderContentNode(child, components, events));
+    const childrenNode = renderedChildren.length > 0 ? /*#__PURE__*/ jsx(Fragment, {
+        children: renderedChildren
+    }) : null;
+    if (node.type === 'root') {
+        return /*#__PURE__*/ jsx(Fragment, {
+            children: childrenNode
+        });
+    }
+    const Component = components[node.type];
+    if (!Component) {
+        // No component mapped for this block type.
+        // Check if any property is a resolved reference with a tree —
+        // if so, render the referenced tree inline using the same components.
+        for (const value of Object.values(node.properties)){
+            if (isResolvedReference(value) && value.tree.children.length > 0) {
+                const refChildren = value.tree.children.map((child)=>renderContentNode(child, components, events));
+                return /*#__PURE__*/ jsx(Fragment, {
+                    children: refChildren
+                });
+            }
+        }
+        // Blocks from referenced data-only collections won't have a mapped
+        // component — that's expected, not an error.
+        if (!fromReference && process.env.NODE_ENV !== 'production') {
+            console.warn(`[cms] No component mapped for block type "${node.type}"`);
+        }
+        return null;
+    }
+    // If the block has reference properties with block trees, render them
+    // and pass as children (appended after the block's own children). The same
+    // `events` map flows down so a functional block embedded via a reference
+    // still binds to the host page's ambient ab-context.
+    let refRendered = [];
+    for (const value of Object.values(node.properties)){
+        if (isResolvedReference(value) && value.tree.children.length > 0) {
+            for (const child of value.tree.children){
+                refRendered.push(renderContentNode(child, components, events, true));
+            }
+        }
+    }
+    const allChildren = renderedChildren.length > 0 || refRendered.length > 0 ? /*#__PURE__*/ jsxs(Fragment, {
+        children: [
+            renderedChildren,
+            refRendered
+        ]
+    }) : null;
+    const element = /*#__PURE__*/ jsx(Component, {
+        properties: node.properties,
+        children: allChildren,
+        blockId: node.blockId,
+        node: node
+    }, node.blockId);
+    // M3c — a FUNCTIONAL block (declared `events`, carried in BlocksMap._events)
+    // is wrapped in the 'use client' <BlockTracker> so it can fire its declared
+    // events. children-as-props: `element` is server-rendered and just passed
+    // through, so presentational subtrees stay RSC. The dispatch + ab-context come
+    // from the consumer's <TrackingRuntimeProvider>, not from here.
+    if (node.type in events) {
+        const rawTrackingId = node.properties.trackingId;
+        return /*#__PURE__*/ jsx(BlockTracker, {
+            blockType: node.type,
+            blockId: node.blockId,
+            trackingId: typeof rawTrackingId === 'string' ? rawTrackingId : undefined,
+            events: events[node.type],
+            children: element
+        }, node.blockId);
+    }
+    return element;
+}
+/**
+ * Renders a block tree with automatic reference resolution.
+ *
+ * When a block has a `reference` property that was resolved by
+ * `getPublishedContent`, the referenced block tree is rendered inline
+ * using the same block components. Data-only references (collections
+ * without blocks) are available directly in `properties`.
+ *
+ * @example
+ * ```tsx
+ * import { createContentRenderer } from '@createcms/core/react';
+ * import { pagesCollection } from '@/cms/collections/pages/definition';
+ *
+ * const RenderPage = createContentRenderer(pagesCollection, {
+ *   headline: ({ properties }) => <h1>{properties.text}</h1>,
+ *   paragraph: ({ properties }) => <p>{properties.text}</p>,
+ *   authorCard: ({ properties }) => (
+ *     <div>{properties.author.properties.name}</div>
+ *   ),
+ *   // No component needed for blocks that just embed a referenced tree —
+ *   // the referenced content renders inline automatically.
+ * });
+ *
+ * // Usage:
+ * <RenderPage tree={tree} />
+ * ```
+ */ function createContentRenderer(collection, components) {
+    const componentMap = components;
+    const events = extractBlockEvents(collection.blocks);
+    function ContentRendererComponent({ tree }) {
+        return renderContentNode(tree, componentMap, events);
+    }
+    ContentRendererComponent.displayName = `ContentRenderer(${collection.label})`;
+    return ContentRendererComponent;
+}
+
+export { BlocksRenderer, createBlocksMap, createBlocksRenderer, createContentRenderer, extractBlockEvents, isResolvedReference };