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

package/dist/registry.d.ts

@@ -0,0 +1,164 @@
+/**
+ * CustomBlockRegistry
+ *
+ * Registry for managing custom block definitions.
+ *
+ * @module @pwfabric/authoring/registry
+ *
+ * @example
+ * ```typescript
+ * import { createCustomBlockRegistry, defineBlock } from '@pwfabric/authoring'
+ * import { z } from 'zod'
+ *
+ * const registry = createCustomBlockRegistry()
+ *
+ * const MyBlock = defineBlock({
+ *   type: 'my-block',
+ *   name: 'My Block',
+ *   schema: z.object({ title: z.string() }),
+ *   defaultProps: { title: 'Default' },
+ *   component: ({ props }) => <div>{props.title}</div>
+ * })
+ *
+ * registry.register(MyBlock)
+ *
+ * // Use with SurfaceRenderer
+ * <SurfaceRenderer components={registry.getComponents()} />
+ * ```
+ */
+import type { BlockCategory } from '@pwfabric/core';
+import type { BlockComponentRegistry } from '@pwfabric/runtime';
+import type { CustomBlockDefinition, ICustomBlockRegistry } from './types.js';
+/**
+ * CustomBlockRegistry
+ *
+ * Manages registration and retrieval of custom block definitions.
+ * Provides a bridge between custom block definitions and the
+ * SurfaceRenderer component registry.
+ */
+export declare class CustomBlockRegistry implements ICustomBlockRegistry {
+    private readonly definitions;
+    /**
+     * Register a custom block definition
+     *
+     * @param definition - The custom block definition to register
+     * @throws Error if block type already registered
+     */
+    register<TProps extends Record<string, unknown>>(definition: CustomBlockDefinition<TProps>): void;
+    /**
+     * Register multiple custom block definitions
+     *
+     * @param definitions - Array of custom block definitions
+     */
+    registerMany(definitions: readonly CustomBlockDefinition[]): void;
+    /**
+     * Get a custom block definition by type
+     *
+     * @param type - Block type identifier
+     * @returns The block definition or undefined
+     */
+    get(type: string): CustomBlockDefinition | undefined;
+    /**
+     * Check if a block type is registered
+     *
+     * @param type - Block type identifier
+     * @returns True if registered
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered custom block definitions
+     *
+     * @returns Array of all block definitions
+     */
+    list(): readonly CustomBlockDefinition[];
+    /**
+     * Get block definitions by category
+     *
+     * @param category - Block category
+     * @returns Array of block definitions in category
+     */
+    getByCategory(category: BlockCategory): readonly CustomBlockDefinition[];
+    /**
+     * Get all registered block types
+     *
+     * @returns Array of block type identifiers
+     */
+    types(): readonly string[];
+    /**
+     * Unregister a custom block
+     *
+     * @param type - Block type identifier
+     * @returns True if block was unregistered
+     */
+    unregister(type: string): boolean;
+    /**
+     * Clear all registrations
+     */
+    clear(): void;
+    /**
+     * Get number of registered blocks
+     */
+    get size(): number;
+    /**
+     * Get a component registry for use with SurfaceRenderer
+     *
+     * This method creates a BlockComponentRegistry that can be passed
+     * to the SurfaceRenderer's `components` prop to enable rendering
+     * of custom blocks.
+     *
+     * @returns BlockComponentRegistry with all registered custom blocks
+     *
+     * @example
+     * ```typescript
+     * import { SurfaceRenderer } from '@pwfabric/runtime'
+     *
+     * const registry = createCustomBlockRegistry()
+     * registry.register(MyCustomBlock)
+     *
+     * // Pass to SurfaceRenderer
+     * <SurfaceRenderer
+     *   surface={mySurface}
+     *   components={registry.getComponents()}
+     * />
+     * ```
+     */
+    getComponents(): BlockComponentRegistry;
+}
+/**
+ * Create a new CustomBlockRegistry
+ *
+ * @returns A new CustomBlockRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createCustomBlockRegistry()
+ * registry.register(MyBlock)
+ * ```
+ */
+export declare function createCustomBlockRegistry(): CustomBlockRegistry;
+export declare function getCustomBlockRegistry(): CustomBlockRegistry;
+/**
+ * Reset the global registry
+ *
+ * Useful for testing or when you need to clear all registrations.
+ */
+export declare function resetGlobalRegistry(): void;
+/**
+ * Merge multiple custom block registries into one
+ *
+ * @param registries - Registries to merge
+ * @returns A new registry containing all blocks from input registries
+ * @throws Error if there are duplicate block types
+ */
+export declare function mergeRegistries(...registries: readonly CustomBlockRegistry[]): CustomBlockRegistry;
+/**
+ * Merge a custom block registry with a base BlockComponentRegistry
+ *
+ * This is useful when you want to extend the default block components
+ * with custom blocks.
+ *
+ * @param baseComponents - The base component registry (e.g., defaultBlockComponents)
+ * @param customRegistry - The custom block registry
+ * @returns A merged BlockComponentRegistry
+ */
+export declare function mergeWithBaseComponents(baseComponents: BlockComponentRegistry, customRegistry: CustomBlockRegistry): BlockComponentRegistry;

package/dist/registry.js

@@ -0,0 +1,277 @@
+/**
+ * CustomBlockRegistry
+ *
+ * Registry for managing custom block definitions.
+ *
+ * @module @pwfabric/authoring/registry
+ *
+ * @example
+ * ```typescript
+ * import { createCustomBlockRegistry, defineBlock } from '@pwfabric/authoring'
+ * import { z } from 'zod'
+ *
+ * const registry = createCustomBlockRegistry()
+ *
+ * const MyBlock = defineBlock({
+ *   type: 'my-block',
+ *   name: 'My Block',
+ *   schema: z.object({ title: z.string() }),
+ *   defaultProps: { title: 'Default' },
+ *   component: ({ props }) => <div>{props.title}</div>
+ * })
+ *
+ * registry.register(MyBlock)
+ *
+ * // Use with SurfaceRenderer
+ * <SurfaceRenderer components={registry.getComponents()} />
+ * ```
+ */
+import { createElement } from 'react';
+// ============================================================
+// CUSTOM BLOCK REGISTRY
+// ============================================================
+/**
+ * CustomBlockRegistry
+ *
+ * Manages registration and retrieval of custom block definitions.
+ * Provides a bridge between custom block definitions and the
+ * SurfaceRenderer component registry.
+ */
+export class CustomBlockRegistry {
+    definitions = new Map();
+    /**
+     * Register a custom block definition
+     *
+     * @param definition - The custom block definition to register
+     * @throws Error if block type already registered
+     */
+    register(definition) {
+        if (this.definitions.has(definition.type)) {
+            throw new Error(`Block type "${definition.type}" is already registered`);
+        }
+        this.definitions.set(definition.type, definition);
+    }
+    /**
+     * Register multiple custom block definitions
+     *
+     * @param definitions - Array of custom block definitions
+     */
+    registerMany(definitions) {
+        for (const definition of definitions) {
+            this.register(definition);
+        }
+    }
+    /**
+     * Get a custom block definition by type
+     *
+     * @param type - Block type identifier
+     * @returns The block definition or undefined
+     */
+    get(type) {
+        return this.definitions.get(type);
+    }
+    /**
+     * Check if a block type is registered
+     *
+     * @param type - Block type identifier
+     * @returns True if registered
+     */
+    has(type) {
+        return this.definitions.has(type);
+    }
+    /**
+     * Get all registered custom block definitions
+     *
+     * @returns Array of all block definitions
+     */
+    list() {
+        return Array.from(this.definitions.values());
+    }
+    /**
+     * Get block definitions by category
+     *
+     * @param category - Block category
+     * @returns Array of block definitions in category
+     */
+    getByCategory(category) {
+        return this.list().filter((def) => def.category === category);
+    }
+    /**
+     * Get all registered block types
+     *
+     * @returns Array of block type identifiers
+     */
+    types() {
+        return Array.from(this.definitions.keys());
+    }
+    /**
+     * Unregister a custom block
+     *
+     * @param type - Block type identifier
+     * @returns True if block was unregistered
+     */
+    unregister(type) {
+        return this.definitions.delete(type);
+    }
+    /**
+     * Clear all registrations
+     */
+    clear() {
+        this.definitions.clear();
+    }
+    /**
+     * Get number of registered blocks
+     */
+    get size() {
+        return this.definitions.size;
+    }
+    /**
+     * Get a component registry for use with SurfaceRenderer
+     *
+     * This method creates a BlockComponentRegistry that can be passed
+     * to the SurfaceRenderer's `components` prop to enable rendering
+     * of custom blocks.
+     *
+     * @returns BlockComponentRegistry with all registered custom blocks
+     *
+     * @example
+     * ```typescript
+     * import { SurfaceRenderer } from '@pwfabric/runtime'
+     *
+     * const registry = createCustomBlockRegistry()
+     * registry.register(MyCustomBlock)
+     *
+     * // Pass to SurfaceRenderer
+     * <SurfaceRenderer
+     *   surface={mySurface}
+     *   components={registry.getComponents()}
+     * />
+     * ```
+     */
+    getComponents() {
+        const components = {};
+        for (const definition of this.definitions.values()) {
+            components[definition.type] = createBlockComponentWrapper(definition);
+        }
+        return components;
+    }
+}
+/**
+ * Create a wrapper component that adapts CustomBlockComponent to BlockComponent
+ *
+ * This bridges the gap between the SDK's CustomBlockComponent interface
+ * and the runtime's BlockComponent interface.
+ */
+/**
+ * Map runtime BlockContext to SDK CustomBlockContext
+ *
+ * Narrows the full runtime context to only what custom block authors need.
+ * Excludes: capabilities, imageAdapter, basePath (platform internals).
+ */
+function mapToCustomBlockContext(runtimeContext) {
+    if (!runtimeContext || typeof runtimeContext !== 'object')
+        return undefined;
+    const ctx = runtimeContext;
+    return {
+        theme: ctx.theme ?? 'light',
+        viewport: ctx.viewport ?? 'lg',
+        onEvent: typeof ctx.onEvent === 'function'
+            ? (event) => {
+                ;
+                ctx.onEvent(event);
+            }
+            : undefined,
+    };
+}
+function createBlockComponentWrapper(definition) {
+    return function WrappedComponent({ block, props: rawProps, children, context, }) {
+        // Validate and apply defaults using the schema
+        const result = definition.schema.safeParse(rawProps);
+        const validatedProps = result.success ? result.data : definition.defaultProps;
+        // Map runtime context to custom block context
+        const customContext = mapToCustomBlockContext(context);
+        // Create the custom block component props
+        const customProps = {
+            props: validatedProps,
+            blockId: block.id,
+            children,
+            context: customContext,
+        };
+        // Render using the custom component
+        return createElement(definition.component, customProps);
+    };
+}
+// ============================================================
+// FACTORY FUNCTIONS
+// ============================================================
+/**
+ * Create a new CustomBlockRegistry
+ *
+ * @returns A new CustomBlockRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createCustomBlockRegistry()
+ * registry.register(MyBlock)
+ * ```
+ */
+export function createCustomBlockRegistry() {
+    return new CustomBlockRegistry();
+}
+/**
+ * Get a singleton instance of CustomBlockRegistry
+ *
+ * Use this when you want a shared registry across your application.
+ * For isolated registries (e.g., in tests), use `createCustomBlockRegistry()`.
+ */
+let globalRegistry = null;
+export function getCustomBlockRegistry() {
+    if (!globalRegistry) {
+        globalRegistry = new CustomBlockRegistry();
+    }
+    return globalRegistry;
+}
+/**
+ * Reset the global registry
+ *
+ * Useful for testing or when you need to clear all registrations.
+ */
+export function resetGlobalRegistry() {
+    globalRegistry = null;
+}
+// ============================================================
+// MERGE UTILITIES
+// ============================================================
+/**
+ * Merge multiple custom block registries into one
+ *
+ * @param registries - Registries to merge
+ * @returns A new registry containing all blocks from input registries
+ * @throws Error if there are duplicate block types
+ */
+export function mergeRegistries(...registries) {
+    const merged = new CustomBlockRegistry();
+    for (const registry of registries) {
+        for (const definition of registry.list()) {
+            merged.register(definition);
+        }
+    }
+    return merged;
+}
+/**
+ * Merge a custom block registry with a base BlockComponentRegistry
+ *
+ * This is useful when you want to extend the default block components
+ * with custom blocks.
+ *
+ * @param baseComponents - The base component registry (e.g., defaultBlockComponents)
+ * @param customRegistry - The custom block registry
+ * @returns A merged BlockComponentRegistry
+ */
+export function mergeWithBaseComponents(baseComponents, customRegistry) {
+    return {
+        ...baseComponents,
+        ...customRegistry.getComponents(),
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * CustomBlockRegistry\n *\n * Registry for managing custom block definitions.\n *\n * @module @pwfabric/authoring/registry\n *\n * @example\n * ```typescript\n * import { createCustomBlockRegistry, defineBlock } from '@pwfabric/authoring'\n * import { z } from 'zod'\n *\n * const registry = createCustomBlockRegistry()\n *\n * const MyBlock = defineBlock({\n *   type: 'my-block',\n *   name: 'My Block',\n *   schema: z.object({ title: z.string() }),\n *   defaultProps: { title: 'Default' },\n *   component: ({ props }) => <div>{props.title}</div>\n * })\n *\n * registry.register(MyBlock)\n *\n * // Use with SurfaceRenderer\n * <SurfaceRenderer components={registry.getComponents()} />\n * ```\n */\n\nimport type { BlockCategory, Block } from '@pwfabric/core'\nimport type { BlockComponentRegistry } from '@pwfabric/runtime'\nimport type {\n  CustomBlockDefinition,\n  ICustomBlockRegistry,\n  CustomBlockComponentProps,\n  CustomBlockContext,\n} from './types.js'\nimport { createElement, type ReactNode } from 'react'\n\n// ============================================================\n// CUSTOM BLOCK REGISTRY\n// ============================================================\n\n/**\n * CustomBlockRegistry\n *\n * Manages registration and retrieval of custom block definitions.\n * Provides a bridge between custom block definitions and the\n * SurfaceRenderer component registry.\n */\nexport class CustomBlockRegistry implements ICustomBlockRegistry {\n  private readonly definitions = new Map<string, CustomBlockDefinition>()\n\n  /**\n   * Register a custom block definition\n   *\n   * @param definition - The custom block definition to register\n   * @throws Error if block type already registered\n   */\n  register<TProps extends Record<string, unknown>>(\n    definition: CustomBlockDefinition<TProps>\n  ): void {\n    if (this.definitions.has(definition.type)) {\n      throw new Error(`Block type \"${definition.type}\" is already registered`)\n    }\n    this.definitions.set(definition.type, definition as CustomBlockDefinition)\n  }\n\n  /**\n   * Register multiple custom block definitions\n   *\n   * @param definitions - Array of custom block definitions\n   */\n  registerMany(definitions: readonly CustomBlockDefinition[]): void {\n    for (const definition of definitions) {\n      this.register(definition)\n    }\n  }\n\n  /**\n   * Get a custom block definition by type\n   *\n   * @param type - Block type identifier\n   * @returns The block definition or undefined\n   */\n  get(type: string): CustomBlockDefinition | undefined {\n    return this.definitions.get(type)\n  }\n\n  /**\n   * Check if a block type is registered\n   *\n   * @param type - Block type identifier\n   * @returns True if registered\n   */\n  has(type: string): boolean {\n    return this.definitions.has(type)\n  }\n\n  /**\n   * Get all registered custom block definitions\n   *\n   * @returns Array of all block definitions\n   */\n  list(): readonly CustomBlockDefinition[] {\n    return Array.from(this.definitions.values())\n  }\n\n  /**\n   * Get block definitions by category\n   *\n   * @param category - Block category\n   * @returns Array of block definitions in category\n   */\n  getByCategory(category: BlockCategory): readonly CustomBlockDefinition[] {\n    return this.list().filter((def) => def.category === category)\n  }\n\n  /**\n   * Get all registered block types\n   *\n   * @returns Array of block type identifiers\n   */\n  types(): readonly string[] {\n    return Array.from(this.definitions.keys())\n  }\n\n  /**\n   * Unregister a custom block\n   *\n   * @param type - Block type identifier\n   * @returns True if block was unregistered\n   */\n  unregister(type: string): boolean {\n    return this.definitions.delete(type)\n  }\n\n  /**\n   * Clear all registrations\n   */\n  clear(): void {\n    this.definitions.clear()\n  }\n\n  /**\n   * Get number of registered blocks\n   */\n  get size(): number {\n    return this.definitions.size\n  }\n\n  /**\n   * Get a component registry for use with SurfaceRenderer\n   *\n   * This method creates a BlockComponentRegistry that can be passed\n   * to the SurfaceRenderer's `components` prop to enable rendering\n   * of custom blocks.\n   *\n   * @returns BlockComponentRegistry with all registered custom blocks\n   *\n   * @example\n   * ```typescript\n   * import { SurfaceRenderer } from '@pwfabric/runtime'\n   *\n   * const registry = createCustomBlockRegistry()\n   * registry.register(MyCustomBlock)\n   *\n   * // Pass to SurfaceRenderer\n   * <SurfaceRenderer\n   *   surface={mySurface}\n   *   components={registry.getComponents()}\n   * />\n   * ```\n   */\n  getComponents(): BlockComponentRegistry {\n    const components: BlockComponentRegistry = {}\n\n    for (const definition of this.definitions.values()) {\n      components[definition.type] = createBlockComponentWrapper(definition)\n    }\n\n    return components\n  }\n}\n\n/**\n * Create a wrapper component that adapts CustomBlockComponent to BlockComponent\n *\n * This bridges the gap between the SDK's CustomBlockComponent interface\n * and the runtime's BlockComponent interface.\n */\n/**\n * Map runtime BlockContext to SDK CustomBlockContext\n *\n * Narrows the full runtime context to only what custom block authors need.\n * Excludes: capabilities, imageAdapter, basePath (platform internals).\n */\nfunction mapToCustomBlockContext(runtimeContext: unknown): CustomBlockContext | undefined {\n  if (!runtimeContext || typeof runtimeContext !== 'object') return undefined\n\n  const ctx = runtimeContext as Record<string, unknown>\n  return {\n    theme: (ctx.theme as 'light' | 'dark') ?? 'light',\n    viewport: (ctx.viewport as string) ?? 'lg',\n    onEvent:\n      typeof ctx.onEvent === 'function'\n        ? (event: { type: string; blockId?: string; payload?: unknown }) => {\n            ;(ctx.onEvent as (e: unknown) => void)(event)\n          }\n        : undefined,\n  }\n}\n\nfunction createBlockComponentWrapper(\n  definition: CustomBlockDefinition\n): (props: {\n  block: Block\n  props: Record<string, unknown>\n  children?: ReactNode\n  context: unknown\n}) => ReactNode {\n  return function WrappedComponent({\n    block,\n    props: rawProps,\n    children,\n    context,\n  }: {\n    block: Block\n    props: Record<string, unknown>\n    children?: ReactNode\n    context: unknown\n  }): ReactNode {\n    // Validate and apply defaults using the schema\n    const result = definition.schema.safeParse(rawProps)\n    const validatedProps = result.success ? result.data : definition.defaultProps\n\n    // Map runtime context to custom block context\n    const customContext = mapToCustomBlockContext(context)\n\n    // Create the custom block component props\n    const customProps: CustomBlockComponentProps = {\n      props: validatedProps,\n      blockId: block.id,\n      children,\n      context: customContext,\n    }\n\n    // Render using the custom component\n    return createElement(\n      definition.component as React.ComponentType<CustomBlockComponentProps>,\n      customProps\n    )\n  }\n}\n\n// ============================================================\n// FACTORY FUNCTIONS\n// ============================================================\n\n/**\n * Create a new CustomBlockRegistry\n *\n * @returns A new CustomBlockRegistry instance\n *\n * @example\n * ```typescript\n * const registry = createCustomBlockRegistry()\n * registry.register(MyBlock)\n * ```\n */\nexport function createCustomBlockRegistry(): CustomBlockRegistry {\n  return new CustomBlockRegistry()\n}\n\n/**\n * Get a singleton instance of CustomBlockRegistry\n *\n * Use this when you want a shared registry across your application.\n * For isolated registries (e.g., in tests), use `createCustomBlockRegistry()`.\n */\nlet globalRegistry: CustomBlockRegistry | null = null\n\nexport function getCustomBlockRegistry(): CustomBlockRegistry {\n  if (!globalRegistry) {\n    globalRegistry = new CustomBlockRegistry()\n  }\n  return globalRegistry\n}\n\n/**\n * Reset the global registry\n *\n * Useful for testing or when you need to clear all registrations.\n */\nexport function resetGlobalRegistry(): void {\n  globalRegistry = null\n}\n\n// ============================================================\n// MERGE UTILITIES\n// ============================================================\n\n/**\n * Merge multiple custom block registries into one\n *\n * @param registries - Registries to merge\n * @returns A new registry containing all blocks from input registries\n * @throws Error if there are duplicate block types\n */\nexport function mergeRegistries(\n  ...registries: readonly CustomBlockRegistry[]\n): CustomBlockRegistry {\n  const merged = new CustomBlockRegistry()\n\n  for (const registry of registries) {\n    for (const definition of registry.list()) {\n      merged.register(definition)\n    }\n  }\n\n  return merged\n}\n\n/**\n * Merge a custom block registry with a base BlockComponentRegistry\n *\n * This is useful when you want to extend the default block components\n * with custom blocks.\n *\n * @param baseComponents - The base component registry (e.g., defaultBlockComponents)\n * @param customRegistry - The custom block registry\n * @returns A merged BlockComponentRegistry\n */\nexport function mergeWithBaseComponents(\n  baseComponents: BlockComponentRegistry,\n  customRegistry: CustomBlockRegistry\n): BlockComponentRegistry {\n  return {\n    ...baseComponents,\n    ...customRegistry.getComponents(),\n  }\n}\n"]}