@pwfabric/authoring 0.0.0-stage → 1.0.0-rc.1

package/dist/types.d.ts

@@ -0,0 +1,281 @@
+/**
+ * @pwfabric/authoring Type Definitions
+ *
+ * Core type definitions for the Custom Block SDK.
+ *
+ * @module @pwfabric/authoring/types
+ */
+import type { ZodSchema, ZodTypeAny, output as ZodOutput } from 'zod';
+import type { Block, BlockCategory } from '@pwfabric/core';
+import type { BlockComponentRegistry } from '@pwfabric/runtime';
+import type { ReactNode } from 'react';
+/**
+ * Custom block definition options
+ *
+ * Used with `defineBlock()` to create a type-safe custom block.
+ */
+export type SchemaProps<TSchema extends ZodTypeAny> = ZodOutput<TSchema> extends Record<string, unknown> ? ZodOutput<TSchema> : Record<string, unknown>;
+/**
+ * Options for `defineBlock()`. The block's props are the schema's output
+ * (`SchemaProps<TSchema>`): they are inferred from `schema` alone, and
+ * `defaultProps` and `component` are checked against them.
+ */
+export interface CustomBlockOptions<TSchema extends ZodTypeAny = ZodTypeAny, TProps extends Record<string, unknown> = SchemaProps<TSchema>> {
+    /** Unique block type identifier (kebab-case) */
+    readonly type: string;
+    /** Human-readable display name */
+    readonly name: string;
+    /** Block category for grouping */
+    readonly category?: BlockCategory;
+    /** Icon character or identifier */
+    readonly icon?: string;
+    /** Zod schema for props validation */
+    readonly schema: TSchema;
+    /**
+     * Default props for new instances. Checked against the schema, never used to
+     * infer the props: a field the schema marks optional stays optional even when
+     * it has a default here.
+     */
+    readonly defaultProps: TProps;
+    /** Whether this block can contain children */
+    readonly canHaveChildren?: boolean;
+    /** Restrict which block types can be children */
+    readonly allowedChildren?: readonly string[];
+    /** Restrict which block types can be parents */
+    readonly allowedParents?: readonly string[];
+    /** open trait vocabulary this block carries (kebab-case). */
+    readonly traits?: readonly string[];
+    /** children must carry ANY of these traits (containers only). */
+    readonly allowedChildTraits?: readonly string[];
+    /** Maximum instances allowed in a surface */
+    readonly maxInstances?: number;
+    /** React component to render this block; its props are the schema's output. */
+    readonly component: CustomBlockComponent<TProps>;
+}
+/**
+ * Custom block context
+ *
+ * Narrowed view of the runtime BlockContext for custom block authors.
+ * Excludes platform internals (capabilities, imageAdapter, basePath).
+ */
+export interface CustomBlockContext {
+    /** Current theme */
+    readonly theme: 'light' | 'dark';
+    /** Current viewport breakpoint */
+    readonly viewport: string;
+    /** Event handler for block-level events */
+    readonly onEvent?: ((event: {
+        type: string;
+        blockId?: string;
+        payload?: unknown;
+    }) => void) | undefined;
+}
+/**
+ * Custom block component props
+ */
+export interface CustomBlockComponentProps<TProps = Record<string, unknown>> {
+    /** The resolved, type-safe props */
+    readonly props: TProps;
+    /** Block ID */
+    readonly blockId: string;
+    /** Rendered children (for container blocks) */
+    readonly children?: ReactNode;
+    /** Runtime context (theme, viewport, events) */
+    readonly context?: CustomBlockContext | undefined;
+}
+/**
+ * Custom block component type
+ */
+export type CustomBlockComponent<TProps = Record<string, unknown>> = (props: CustomBlockComponentProps<TProps>) => ReactNode;
+/**
+ * Custom block definition (result of defineBlock)
+ *
+ * Contains both the block metadata and the component for rendering.
+ */
+export interface CustomBlockDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique block type identifier */
+    readonly type: string;
+    /** Human-readable display name */
+    readonly name: string;
+    /** Block category */
+    readonly category: BlockCategory;
+    /** Icon character or identifier */
+    readonly icon: string;
+    /** Zod schema for validation */
+    readonly schema: ZodSchema<TProps>;
+    /** Default props */
+    readonly defaultProps: TProps;
+    /** Whether this block can contain children */
+    readonly canHaveChildren: boolean;
+    /** Allowed child block types */
+    readonly allowedChildren?: readonly string[];
+    /** Allowed parent block types */
+    readonly allowedParents?: readonly string[];
+    /** open trait vocabulary this block carries (kebab-case). */
+    readonly traits?: readonly string[];
+    /** children must carry ANY of these traits (containers only). */
+    readonly allowedChildTraits?: readonly string[];
+    /** Maximum instances */
+    readonly maxInstances?: number;
+    /** React component */
+    readonly component: CustomBlockComponent<TProps>;
+}
+/**
+ * Factory configuration input
+ *
+ * Passed to the build function to customize the generated blocks.
+ */
+export type FactoryConfig = Record<string, unknown>;
+/**
+ * Block specification for factory output
+ *
+ * Simplified block definition without requiring an id (auto-generated).
+ */
+export interface BlockSpec {
+    /** Block type */
+    readonly type: string;
+    /** Block props */
+    readonly props: Record<string, unknown>;
+    /** Nested children */
+    readonly children?: readonly BlockSpec[];
+}
+/**
+ * Factory definition options
+ *
+ * Used with `defineFactory()` to create a factory function.
+ */
+export interface FactoryOptions<TConfig extends FactoryConfig = FactoryConfig> {
+    /** Unique factory identifier (kebab-case) */
+    readonly id: string;
+    /** Human-readable factory name */
+    readonly name?: string;
+    /** Factory description */
+    readonly description?: string;
+    /** Optional Zod schema for config validation */
+    readonly configSchema?: ZodSchema<TConfig>;
+    /** Build function that returns block specifications */
+    readonly build: (config: TConfig) => readonly BlockSpec[];
+}
+/**
+ * Factory definition (result of defineFactory)
+ */
+export interface FactoryDefinition<TConfig extends FactoryConfig = FactoryConfig> {
+    /** Factory identifier */
+    readonly id: string;
+    /** Factory name */
+    readonly name: string;
+    /** Factory description */
+    readonly description: string;
+    /** Config schema (if provided) */
+    readonly configSchema?: ZodSchema<TConfig>;
+    /** Build function */
+    readonly build: (config: TConfig) => readonly Block[];
+    /** Validate config against schema (if provided) */
+    readonly validateConfig: (config: unknown) => FactoryValidationResult<TConfig>;
+}
+/**
+ * Factory validation result
+ */
+export interface FactoryValidationResult<TConfig = FactoryConfig> {
+    /** Whether validation passed */
+    readonly valid: boolean;
+    /** Validated config (if valid) */
+    readonly config?: TConfig;
+    /** Validation errors (if invalid) */
+    readonly errors?: readonly FactoryValidationError[];
+}
+/**
+ * Factory validation error
+ */
+export interface FactoryValidationError {
+    /** Error path in the config */
+    readonly path: string;
+    /** Error message */
+    readonly message: string;
+}
+/**
+ * Custom block registry interface
+ */
+export interface ICustomBlockRegistry {
+    /**
+     * Register a custom block definition
+     */
+    register<TProps extends Record<string, unknown>>(definition: CustomBlockDefinition<TProps>): void;
+    /**
+     * Get a custom block definition by type
+     */
+    get(type: string): CustomBlockDefinition | undefined;
+    /**
+     * Check if a block type is registered
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered custom block definitions
+     */
+    list(): readonly CustomBlockDefinition[];
+    /**
+     * Get block definitions by category
+     */
+    getByCategory(category: BlockCategory): readonly CustomBlockDefinition[];
+    /**
+     * Get all registered block types
+     */
+    types(): readonly string[];
+    /**
+     * Unregister a custom block
+     */
+    unregister(type: string): boolean;
+    /**
+     * Clear all registrations
+     */
+    clear(): void;
+    /**
+     * Get a component registry for use with SurfaceRenderer
+     */
+    getComponents(): BlockComponentRegistry;
+}
+/**
+ * Block validation result
+ */
+export interface BlockValidationResult {
+    /** Whether the block is valid */
+    readonly valid: boolean;
+    /** The validated block (with defaults applied) */
+    readonly block?: Block;
+    /** Validation errors */
+    readonly errors: readonly BlockValidationError[];
+}
+/**
+ * Block validation error
+ */
+export interface BlockValidationError {
+    /** Error code */
+    readonly code: string;
+    /** Error message */
+    readonly message: string;
+    /** Path to the invalid property */
+    readonly path?: string;
+}
+/**
+ * Props validation result
+ */
+export interface PropsValidationResult<TProps = Record<string, unknown>> {
+    /** Whether the props are valid */
+    readonly valid: boolean;
+    /** The validated props (with defaults applied) */
+    readonly props?: TProps;
+    /** Validation errors */
+    readonly errors: readonly BlockValidationError[];
+}
+/**
+ * Infer props type from a custom block definition
+ */
+export type InferBlockProps<T> = T extends CustomBlockDefinition<infer TProps> ? TProps : never;
+/**
+ * Infer config type from a factory definition
+ */
+export type InferFactoryConfig<T> = T extends FactoryDefinition<infer TConfig> ? TConfig : never;
+/**
+ * Infer props type from a Zod schema
+ */
+export type InferSchemaProps<T> = T extends ZodSchema<infer TOutput> ? TOutput : never;

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * @pwfabric/authoring Type Definitions
+ *
+ * Core type definitions for the Custom Block SDK.
+ *
+ * @module @pwfabric/authoring/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * @pwfabric/authoring Type Definitions\n *\n * Core type definitions for the Custom Block SDK.\n *\n * @module @pwfabric/authoring/types\n */\n\nimport type { ZodSchema, ZodTypeAny, output as ZodOutput } from 'zod'\nimport type { Block, BlockCategory } from '@pwfabric/core'\nimport type { BlockComponentRegistry } from '@pwfabric/runtime'\nimport type { ReactNode } from 'react'\n\n// ============================================================\n// CUSTOM BLOCK DEFINITION\n// ============================================================\n\n/**\n * Custom block definition options\n *\n * Used with `defineBlock()` to create a type-safe custom block.\n */\nexport type SchemaProps<TSchema extends ZodTypeAny> =\n  ZodOutput<TSchema> extends Record<string, unknown> ? ZodOutput<TSchema> : Record<string, unknown>\n\n/**\n * Options for `defineBlock()`. The block's props are the schema's output\n * (`SchemaProps<TSchema>`): they are inferred from `schema` alone, and\n * `defaultProps` and `component` are checked against them.\n */\nexport interface CustomBlockOptions<\n  TSchema extends ZodTypeAny = ZodTypeAny,\n  TProps extends Record<string, unknown> = SchemaProps<TSchema>,\n> {\n  /** Unique block type identifier (kebab-case) */\n  readonly type: string\n\n  /** Human-readable display name */\n  readonly name: string\n\n  /** Block category for grouping */\n  readonly category?: BlockCategory\n\n  /** Icon character or identifier */\n  readonly icon?: string\n\n  /** Zod schema for props validation */\n  readonly schema: TSchema\n\n  /**\n   * Default props for new instances. Checked against the schema, never used to\n   * infer the props: a field the schema marks optional stays optional even when\n   * it has a default here.\n   */\n  readonly defaultProps: TProps\n\n  /** Whether this block can contain children */\n  readonly canHaveChildren?: boolean\n\n  /** Restrict which block types can be children */\n  readonly allowedChildren?: readonly string[]\n\n  /** Restrict which block types can be parents */\n  readonly allowedParents?: readonly string[]\n\n  /** open trait vocabulary this block carries (kebab-case). */\n  readonly traits?: readonly string[]\n\n  /** children must carry ANY of these traits (containers only). */\n  readonly allowedChildTraits?: readonly string[]\n\n  /** Maximum instances allowed in a surface */\n  readonly maxInstances?: number\n\n  /** React component to render this block; its props are the schema's output. */\n  readonly component: CustomBlockComponent<TProps>\n}\n\n/**\n * Custom block context\n *\n * Narrowed view of the runtime BlockContext for custom block authors.\n * Excludes platform internals (capabilities, imageAdapter, basePath).\n */\nexport interface CustomBlockContext {\n  /** Current theme */\n  readonly theme: 'light' | 'dark'\n  /** Current viewport breakpoint */\n  readonly viewport: string\n  /** Event handler for block-level events */\n  readonly onEvent?:\n    | ((event: { type: string; blockId?: string; payload?: unknown }) => void)\n    | undefined\n}\n\n/**\n * Custom block component props\n */\nexport interface CustomBlockComponentProps<TProps = Record<string, unknown>> {\n  /** The resolved, type-safe props */\n  readonly props: TProps\n  /** Block ID */\n  readonly blockId: string\n  /** Rendered children (for container blocks) */\n  readonly children?: ReactNode\n  /** Runtime context (theme, viewport, events) */\n  readonly context?: CustomBlockContext | undefined\n}\n\n/**\n * Custom block component type\n */\nexport type CustomBlockComponent<TProps = Record<string, unknown>> = (\n  props: CustomBlockComponentProps<TProps>\n) => ReactNode\n\n/**\n * Custom block definition (result of defineBlock)\n *\n * Contains both the block metadata and the component for rendering.\n */\nexport interface CustomBlockDefinition<\n  TProps extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /** Unique block type identifier */\n  readonly type: string\n\n  /** Human-readable display name */\n  readonly name: string\n\n  /** Block category */\n  readonly category: BlockCategory\n\n  /** Icon character or identifier */\n  readonly icon: string\n\n  /** Zod schema for validation */\n  readonly schema: ZodSchema<TProps>\n\n  /** Default props */\n  readonly defaultProps: TProps\n\n  /** Whether this block can contain children */\n  readonly canHaveChildren: boolean\n\n  /** Allowed child block types */\n  readonly allowedChildren?: readonly string[]\n\n  /** Allowed parent block types */\n  readonly allowedParents?: readonly string[]\n\n  /** open trait vocabulary this block carries (kebab-case). */\n  readonly traits?: readonly string[]\n\n  /** children must carry ANY of these traits (containers only). */\n  readonly allowedChildTraits?: readonly string[]\n\n  /** Maximum instances */\n  readonly maxInstances?: number\n\n  /** React component */\n  readonly component: CustomBlockComponent<TProps>\n}\n\n// ============================================================\n// FACTORY DEFINITION\n// ============================================================\n\n/**\n * Factory configuration input\n *\n * Passed to the build function to customize the generated blocks.\n */\nexport type FactoryConfig = Record<string, unknown>\n\n/**\n * Block specification for factory output\n *\n * Simplified block definition without requiring an id (auto-generated).\n */\nexport interface BlockSpec {\n  /** Block type */\n  readonly type: string\n  /** Block props */\n  readonly props: Record<string, unknown>\n  /** Nested children */\n  readonly children?: readonly BlockSpec[]\n}\n\n/**\n * Factory definition options\n *\n * Used with `defineFactory()` to create a factory function.\n */\nexport interface FactoryOptions<TConfig extends FactoryConfig = FactoryConfig> {\n  /** Unique factory identifier (kebab-case) */\n  readonly id: string\n\n  /** Human-readable factory name */\n  readonly name?: string\n\n  /** Factory description */\n  readonly description?: string\n\n  /** Optional Zod schema for config validation */\n  readonly configSchema?: ZodSchema<TConfig>\n\n  /** Build function that returns block specifications */\n  readonly build: (config: TConfig) => readonly BlockSpec[]\n}\n\n/**\n * Factory definition (result of defineFactory)\n */\nexport interface FactoryDefinition<TConfig extends FactoryConfig = FactoryConfig> {\n  /** Factory identifier */\n  readonly id: string\n\n  /** Factory name */\n  readonly name: string\n\n  /** Factory description */\n  readonly description: string\n\n  /** Config schema (if provided) */\n  readonly configSchema?: ZodSchema<TConfig>\n\n  /** Build function */\n  readonly build: (config: TConfig) => readonly Block[]\n\n  /** Validate config against schema (if provided) */\n  readonly validateConfig: (config: unknown) => FactoryValidationResult<TConfig>\n}\n\n/**\n * Factory validation result\n */\nexport interface FactoryValidationResult<TConfig = FactoryConfig> {\n  /** Whether validation passed */\n  readonly valid: boolean\n  /** Validated config (if valid) */\n  readonly config?: TConfig\n  /** Validation errors (if invalid) */\n  readonly errors?: readonly FactoryValidationError[]\n}\n\n/**\n * Factory validation error\n */\nexport interface FactoryValidationError {\n  /** Error path in the config */\n  readonly path: string\n  /** Error message */\n  readonly message: string\n}\n\n// ============================================================\n// REGISTRY TYPES\n// ============================================================\n\n/**\n * Custom block registry interface\n */\nexport interface ICustomBlockRegistry {\n  /**\n   * Register a custom block definition\n   */\n  register<TProps extends Record<string, unknown>>(definition: CustomBlockDefinition<TProps>): void\n\n  /**\n   * Get a custom block definition by type\n   */\n  get(type: string): CustomBlockDefinition | undefined\n\n  /**\n   * Check if a block type is registered\n   */\n  has(type: string): boolean\n\n  /**\n   * Get all registered custom block definitions\n   */\n  list(): readonly CustomBlockDefinition[]\n\n  /**\n   * Get block definitions by category\n   */\n  getByCategory(category: BlockCategory): readonly CustomBlockDefinition[]\n\n  /**\n   * Get all registered block types\n   */\n  types(): readonly string[]\n\n  /**\n   * Unregister a custom block\n   */\n  unregister(type: string): boolean\n\n  /**\n   * Clear all registrations\n   */\n  clear(): void\n\n  /**\n   * Get a component registry for use with SurfaceRenderer\n   */\n  getComponents(): BlockComponentRegistry\n}\n\n// ============================================================\n// VALIDATION TYPES\n// ============================================================\n\n/**\n * Block validation result\n */\nexport interface BlockValidationResult {\n  /** Whether the block is valid */\n  readonly valid: boolean\n  /** The validated block (with defaults applied) */\n  readonly block?: Block\n  /** Validation errors */\n  readonly errors: readonly BlockValidationError[]\n}\n\n/**\n * Block validation error\n */\nexport interface BlockValidationError {\n  /** Error code */\n  readonly code: string\n  /** Error message */\n  readonly message: string\n  /** Path to the invalid property */\n  readonly path?: string\n}\n\n/**\n * Props validation result\n */\nexport interface PropsValidationResult<TProps = Record<string, unknown>> {\n  /** Whether the props are valid */\n  readonly valid: boolean\n  /** The validated props (with defaults applied) */\n  readonly props?: TProps\n  /** Validation errors */\n  readonly errors: readonly BlockValidationError[]\n}\n\n// ============================================================\n// UTILITY TYPES\n// ============================================================\n\n/**\n * Infer props type from a custom block definition\n */\nexport type InferBlockProps<T> = T extends CustomBlockDefinition<infer TProps> ? TProps : never\n\n/**\n * Infer config type from a factory definition\n */\nexport type InferFactoryConfig<T> = T extends FactoryDefinition<infer TConfig> ? TConfig : never\n\n/**\n * Infer props type from a Zod schema\n */\nexport type InferSchemaProps<T> = T extends ZodSchema<infer TOutput> ? TOutput : never\n"]}

package/dist/validation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Validation Utilities
+ *
+ * Schema validation utilities for custom blocks.
+ *
+ * @module @pwfabric/authoring/validation
+ */
+import type { ZodSchema } from 'zod';
+import type { Block } from '@pwfabric/core';
+import type { CustomBlockDefinition, BlockValidationResult, BlockValidationError, PropsValidationResult, ICustomBlockRegistry } from './types.js';
+/**
+ * Validate props against a Zod schema
+ *
+ * @param props - The props to validate
+ * @param schema - The Zod schema to validate against
+ * @returns Validation result with validated props or errors
+ */
+export declare function validateProps<TProps extends Record<string, unknown>>(props: unknown, schema: ZodSchema<TProps>): PropsValidationResult<TProps>;
+/**
+ * Validate props with defaults applied
+ *
+ * If validation fails, returns the default props.
+ *
+ * @param props - The props to validate
+ * @param schema - The Zod schema
+ * @param defaultProps - Default props to use if validation fails
+ * @returns Validated props or defaults
+ */
+export declare function validatePropsWithDefaults<TProps extends Record<string, unknown>>(props: unknown, schema: ZodSchema<TProps>, defaultProps: TProps): TProps;
+/**
+ * Validate a block against its definition
+ *
+ * @param block - The block to validate
+ * @param definition - The block definition
+ * @returns Validation result
+ */
+export declare function validateBlock<TProps extends Record<string, unknown>>(block: Block, definition: CustomBlockDefinition<TProps>): BlockValidationResult;
+/**
+ * Validate a block tree against a registry of definitions
+ *
+ * Recursively validates all blocks in the tree.
+ *
+ * @param blocks - The blocks to validate
+ * @param registry - The block registry
+ * @returns Array of validation errors (empty if all valid)
+ */
+export declare function validateBlockTree(blocks: readonly Block[], registry: ICustomBlockRegistry): readonly BlockValidationError[];
+/**
+ * Create a validation function for a specific block type
+ *
+ * @param definition - The block definition
+ * @returns A validation function
+ */
+export declare function createBlockValidator<TProps extends Record<string, unknown>>(definition: CustomBlockDefinition<TProps>): (block: Block) => BlockValidationResult;
+/**
+ * Create a props validation function for a specific schema
+ *
+ * @param schema - The Zod schema
+ * @returns A validation function
+ */
+export declare function createPropsValidator<TProps extends Record<string, unknown>>(schema: ZodSchema<TProps>): (props: unknown) => PropsValidationResult<TProps>;
+/**
+ * Format validation errors as a human-readable string
+ *
+ * @param errors - The validation errors
+ * @returns Formatted error string
+ */
+export declare function formatValidationErrors(errors: readonly BlockValidationError[]): string;
+/**
+ * Check if a validation result has errors
+ */
+export declare function hasErrors(result: BlockValidationResult | PropsValidationResult): boolean;
+/**
+ * Check if a value is a valid Block
+ */
+export declare function isBlock(value: unknown): value is Block;
+/**
+ * Check if a value is a valid Block array
+ */
+export declare function isBlockArray(value: unknown): value is Block[];

package/dist/validation.js

@@ -0,0 +1,217 @@
+/**
+ * Validation Utilities
+ *
+ * Schema validation utilities for custom blocks.
+ *
+ * @module @pwfabric/authoring/validation
+ */
+// ============================================================
+// PROPS VALIDATION
+// ============================================================
+/**
+ * Validate props against a Zod schema
+ *
+ * @param props - The props to validate
+ * @param schema - The Zod schema to validate against
+ * @returns Validation result with validated props or errors
+ */
+export function validateProps(props, schema) {
+    const result = schema.safeParse(props);
+    if (result.success) {
+        return {
+            valid: true,
+            props: result.data,
+            errors: [],
+        };
+    }
+    const errors = result.error.errors.map((e) => ({
+        code: 'VALIDATION_ERROR',
+        message: e.message,
+        path: e.path.join('.'),
+    }));
+    return {
+        valid: false,
+        errors,
+    };
+}
+/**
+ * Validate props with defaults applied
+ *
+ * If validation fails, returns the default props.
+ *
+ * @param props - The props to validate
+ * @param schema - The Zod schema
+ * @param defaultProps - Default props to use if validation fails
+ * @returns Validated props or defaults
+ */
+export function validatePropsWithDefaults(props, schema, defaultProps) {
+    const result = schema.safeParse(props);
+    return result.success ? result.data : defaultProps;
+}
+// ============================================================
+// BLOCK VALIDATION
+// ============================================================
+/**
+ * Validate a block against its definition
+ *
+ * @param block - The block to validate
+ * @param definition - The block definition
+ * @returns Validation result
+ */
+export function validateBlock(block, definition) {
+    const errors = [];
+    // Validate type matches
+    if (block.type !== definition.type) {
+        errors.push({
+            code: 'TYPE_MISMATCH',
+            message: `Expected block type "${definition.type}", got "${block.type}"`,
+        });
+        return { valid: false, errors };
+    }
+    // Validate props
+    const propsResult = validateProps(block.props, definition.schema);
+    if (!propsResult.valid) {
+        errors.push(...propsResult.errors);
+    }
+    // Validate children constraints
+    if (block.children && block.children.length > 0) {
+        if (!definition.canHaveChildren) {
+            errors.push({
+                code: 'CHILDREN_NOT_ALLOWED',
+                message: `Block type "${definition.type}" cannot have children`,
+            });
+        }
+        if (definition.allowedChildren && definition.allowedChildren.length > 0) {
+            for (const child of block.children) {
+                if (!definition.allowedChildren.includes(child.type)) {
+                    errors.push({
+                        code: 'INVALID_CHILD_TYPE',
+                        message: `Block type "${child.type}" is not allowed as a child of "${definition.type}"`,
+                        path: `children.${child.id}`,
+                    });
+                }
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    return {
+        valid: true,
+        block: {
+            ...block,
+            props: propsResult.props ?? block.props,
+        },
+        errors: [],
+    };
+}
+/**
+ * Validate a block tree against a registry of definitions
+ *
+ * Recursively validates all blocks in the tree.
+ *
+ * @param blocks - The blocks to validate
+ * @param registry - The block registry
+ * @returns Array of validation errors (empty if all valid)
+ */
+export function validateBlockTree(blocks, registry) {
+    const errors = [];
+    function validateRecursive(block, path) {
+        const definition = registry.get(block.type);
+        if (!definition) {
+            // Not a custom block, skip validation
+            // (could be a built-in block type)
+            if (block.children) {
+                block.children.forEach((child, index) => {
+                    validateRecursive(child, `${path}.children[${index}]`);
+                });
+            }
+            return;
+        }
+        const result = validateBlock(block, definition);
+        if (!result.valid) {
+            errors.push(...result.errors.map((e) => ({
+                ...e,
+                path: e.path ? `${path}.${e.path}` : path,
+            })));
+        }
+        if (block.children) {
+            block.children.forEach((child, index) => {
+                validateRecursive(child, `${path}.children[${index}]`);
+            });
+        }
+    }
+    blocks.forEach((block, index) => {
+        validateRecursive(block, `blocks[${index}]`);
+    });
+    return errors;
+}
+// ============================================================
+// SCHEMA UTILITIES
+// ============================================================
+/**
+ * Create a validation function for a specific block type
+ *
+ * @param definition - The block definition
+ * @returns A validation function
+ */
+export function createBlockValidator(definition) {
+    return (block) => validateBlock(block, definition);
+}
+/**
+ * Create a props validation function for a specific schema
+ *
+ * @param schema - The Zod schema
+ * @returns A validation function
+ */
+export function createPropsValidator(schema) {
+    return (props) => validateProps(props, schema);
+}
+// ============================================================
+// ERROR FORMATTING
+// ============================================================
+/**
+ * Format validation errors as a human-readable string
+ *
+ * @param errors - The validation errors
+ * @returns Formatted error string
+ */
+export function formatValidationErrors(errors) {
+    if (errors.length === 0) {
+        return 'No errors';
+    }
+    return errors
+        .map((e) => {
+        const path = e.path ? ` at ${e.path}` : '';
+        return `[${e.code}]${path}: ${e.message}`;
+    })
+        .join('\n');
+}
+/**
+ * Check if a validation result has errors
+ */
+export function hasErrors(result) {
+    return !result.valid && result.errors.length > 0;
+}
+// ============================================================
+// TYPE GUARDS
+// ============================================================
+/**
+ * Check if a value is a valid Block
+ */
+export function isBlock(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const block = value;
+    return (typeof block.id === 'string' &&
+        typeof block.type === 'string' &&
+        typeof block.props === 'object');
+}
+/**
+ * Check if a value is a valid Block array
+ */
+export function isBlockArray(value) {
+    return Array.isArray(value) && value.every(isBlock);
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validation Utilities\n *\n * Schema validation utilities for custom blocks.\n *\n * @module @pwfabric/authoring/validation\n */\n\nimport type { ZodSchema } from 'zod'\nimport type { Block } from '@pwfabric/core'\nimport type {\n  CustomBlockDefinition,\n  BlockValidationResult,\n  BlockValidationError,\n  PropsValidationResult,\n  ICustomBlockRegistry,\n} from './types.js'\n\n// ============================================================\n// PROPS VALIDATION\n// ============================================================\n\n/**\n * Validate props against a Zod schema\n *\n * @param props - The props to validate\n * @param schema - The Zod schema to validate against\n * @returns Validation result with validated props or errors\n */\nexport function validateProps<TProps extends Record<string, unknown>>(\n  props: unknown,\n  schema: ZodSchema<TProps>\n): PropsValidationResult<TProps> {\n  const result = schema.safeParse(props)\n\n  if (result.success) {\n    return {\n      valid: true,\n      props: result.data,\n      errors: [],\n    }\n  }\n\n  const errors: BlockValidationError[] = result.error.errors.map((e) => ({\n    code: 'VALIDATION_ERROR',\n    message: e.message,\n    path: e.path.join('.'),\n  }))\n\n  return {\n    valid: false,\n    errors,\n  }\n}\n\n/**\n * Validate props with defaults applied\n *\n * If validation fails, returns the default props.\n *\n * @param props - The props to validate\n * @param schema - The Zod schema\n * @param defaultProps - Default props to use if validation fails\n * @returns Validated props or defaults\n */\nexport function validatePropsWithDefaults<TProps extends Record<string, unknown>>(\n  props: unknown,\n  schema: ZodSchema<TProps>,\n  defaultProps: TProps\n): TProps {\n  const result = schema.safeParse(props)\n  return result.success ? result.data : defaultProps\n}\n\n// ============================================================\n// BLOCK VALIDATION\n// ============================================================\n\n/**\n * Validate a block against its definition\n *\n * @param block - The block to validate\n * @param definition - The block definition\n * @returns Validation result\n */\nexport function validateBlock<TProps extends Record<string, unknown>>(\n  block: Block,\n  definition: CustomBlockDefinition<TProps>\n): BlockValidationResult {\n  const errors: BlockValidationError[] = []\n\n  // Validate type matches\n  if (block.type !== definition.type) {\n    errors.push({\n      code: 'TYPE_MISMATCH',\n      message: `Expected block type \"${definition.type}\", got \"${block.type}\"`,\n    })\n    return { valid: false, errors }\n  }\n\n  // Validate props\n  const propsResult = validateProps(block.props, definition.schema)\n  if (!propsResult.valid) {\n    errors.push(...propsResult.errors)\n  }\n\n  // Validate children constraints\n  if (block.children && block.children.length > 0) {\n    if (!definition.canHaveChildren) {\n      errors.push({\n        code: 'CHILDREN_NOT_ALLOWED',\n        message: `Block type \"${definition.type}\" cannot have children`,\n      })\n    }\n\n    if (definition.allowedChildren && definition.allowedChildren.length > 0) {\n      for (const child of block.children) {\n        if (!definition.allowedChildren.includes(child.type)) {\n          errors.push({\n            code: 'INVALID_CHILD_TYPE',\n            message: `Block type \"${child.type}\" is not allowed as a child of \"${definition.type}\"`,\n            path: `children.${child.id}`,\n          })\n        }\n      }\n    }\n  }\n\n  if (errors.length > 0) {\n    return { valid: false, errors }\n  }\n\n  return {\n    valid: true,\n    block: {\n      ...block,\n      props: propsResult.props ?? block.props,\n    },\n    errors: [],\n  }\n}\n\n/**\n * Validate a block tree against a registry of definitions\n *\n * Recursively validates all blocks in the tree.\n *\n * @param blocks - The blocks to validate\n * @param registry - The block registry\n * @returns Array of validation errors (empty if all valid)\n */\nexport function validateBlockTree(\n  blocks: readonly Block[],\n  registry: ICustomBlockRegistry\n): readonly BlockValidationError[] {\n  const errors: BlockValidationError[] = []\n\n  function validateRecursive(block: Block, path: string): void {\n    const definition = registry.get(block.type)\n\n    if (!definition) {\n      // Not a custom block, skip validation\n      // (could be a built-in block type)\n      if (block.children) {\n        block.children.forEach((child: Block, index: number) => {\n          validateRecursive(child, `${path}.children[${index}]`)\n        })\n      }\n      return\n    }\n\n    const result = validateBlock(block, definition)\n    if (!result.valid) {\n      errors.push(\n        ...result.errors.map((e) => ({\n          ...e,\n          path: e.path ? `${path}.${e.path}` : path,\n        }))\n      )\n    }\n\n    if (block.children) {\n      block.children.forEach((child: Block, index: number) => {\n        validateRecursive(child, `${path}.children[${index}]`)\n      })\n    }\n  }\n\n  blocks.forEach((block, index) => {\n    validateRecursive(block, `blocks[${index}]`)\n  })\n\n  return errors\n}\n\n// ============================================================\n// SCHEMA UTILITIES\n// ============================================================\n\n/**\n * Create a validation function for a specific block type\n *\n * @param definition - The block definition\n * @returns A validation function\n */\nexport function createBlockValidator<TProps extends Record<string, unknown>>(\n  definition: CustomBlockDefinition<TProps>\n): (block: Block) => BlockValidationResult {\n  return (block: Block) => validateBlock(block, definition)\n}\n\n/**\n * Create a props validation function for a specific schema\n *\n * @param schema - The Zod schema\n * @returns A validation function\n */\nexport function createPropsValidator<TProps extends Record<string, unknown>>(\n  schema: ZodSchema<TProps>\n): (props: unknown) => PropsValidationResult<TProps> {\n  return (props: unknown) => validateProps(props, schema)\n}\n\n// ============================================================\n// ERROR FORMATTING\n// ============================================================\n\n/**\n * Format validation errors as a human-readable string\n *\n * @param errors - The validation errors\n * @returns Formatted error string\n */\nexport function formatValidationErrors(errors: readonly BlockValidationError[]): string {\n  if (errors.length === 0) {\n    return 'No errors'\n  }\n\n  return errors\n    .map((e) => {\n      const path = e.path ? ` at ${e.path}` : ''\n      return `[${e.code}]${path}: ${e.message}`\n    })\n    .join('\\n')\n}\n\n/**\n * Check if a validation result has errors\n */\nexport function hasErrors(result: BlockValidationResult | PropsValidationResult): boolean {\n  return !result.valid && result.errors.length > 0\n}\n\n// ============================================================\n// TYPE GUARDS\n// ============================================================\n\n/**\n * Check if a value is a valid Block\n */\nexport function isBlock(value: unknown): value is Block {\n  if (!value || typeof value !== 'object') {\n    return false\n  }\n\n  const block = value as Partial<Block>\n  return (\n    typeof block.id === 'string' &&\n    typeof block.type === 'string' &&\n    typeof block.props === 'object'\n  )\n}\n\n/**\n * Check if a value is a valid Block array\n */\nexport function isBlockArray(value: unknown): value is Block[] {\n  return Array.isArray(value) && value.every(isBlock)\n}\n"]}