@shopkit/builder 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1338 @@
+import React, { ComponentType, ReactNode } from 'react';
+
+/**
+ * Commerce Client Interface
+ *
+ * Consumers implement this interface to provide data fetching capabilities
+ * for the page builder. This abstraction allows the page builder to work
+ * with any commerce platform (Shopify, custom backends, etc.)
+ */
+/**
+ * Parameters for fetching a single product
+ */
+interface ProductQueryParams {
+    handle?: string;
+    id?: string;
+}
+/**
+ * Parameters for fetching multiple products
+ */
+interface ProductsQueryParams {
+    first?: number;
+    after?: string;
+    handles?: string[];
+    query?: string;
+    sortKey?: string;
+    reverse?: boolean;
+}
+/**
+ * Parameters for fetching a single collection
+ */
+interface CollectionQueryParams {
+    handle?: string;
+    id?: string;
+    productLimit?: number;
+}
+/**
+ * Parameters for fetching multiple collections
+ */
+interface CollectionsQueryParams {
+    first?: number;
+    after?: string;
+    query?: string;
+}
+/**
+ * Parameters for fetching collection with filters (faceted search)
+ */
+interface CollectionWithFiltersParams {
+    handle: string;
+    filters?: Array<Record<string, any>>;
+    sortKey?: string;
+    reverse?: boolean;
+    first?: number;
+    after?: string;
+    page?: number;
+    itemsPerPage?: number;
+}
+/**
+ * Parameters for fetching collection by handler
+ */
+interface CollectionsByHandlerParams {
+    handle: string;
+    productLimit?: number;
+    sort?: string;
+    filter?: Record<string, any>;
+}
+/**
+ * Commerce Client Interface
+ *
+ * Required methods that must be implemented by consumers.
+ * Optional methods can be implemented for advanced features.
+ */
+interface ICommerceClient {
+    /**
+     * Fetch a single product by handle or ID
+     */
+    getProduct(params: ProductQueryParams): Promise<any>;
+    /**
+     * Fetch multiple products with pagination and filtering
+     */
+    getProducts(params: ProductsQueryParams): Promise<{
+        products: any[];
+        pageInfo?: any;
+    }>;
+    /**
+     * Fetch product recommendations for a given product
+     */
+    getProductRecommendations(productIdOrHandle: string): Promise<any[]>;
+    /**
+     * Fetch a single collection by handle or ID
+     */
+    getCollection(params: CollectionQueryParams): Promise<any>;
+    /**
+     * Fetch multiple collections with pagination
+     */
+    getCollections(params: CollectionsQueryParams): Promise<{
+        collections: any[];
+        pageInfo?: any;
+    }>;
+    /**
+     * Optional: Fetch collection with faceted filters
+     * Used for collection pages with filtering functionality
+     */
+    getCollectionWithFilters?(params: CollectionWithFiltersParams): Promise<any>;
+    /**
+     * Optional: Fetch collection by handler with specific parameters
+     * Used for featured collections, category pages, etc.
+     */
+    getCollectionsByHandler?(params: CollectionsByHandlerParams): Promise<any>;
+}
+
+/**
+ * Page Builder Theme Types
+ *
+ * Local type definitions for theme-related functionality within the page builder.
+ * These types are intentionally defined here to maintain package independence.
+ *
+ * When the page builder is extracted as a standalone package, these types
+ * will be the contract that consumers must implement.
+ *
+ * NOTE: These types mirror @/lib/theme/types/theme.ts to maintain consistency.
+ * When updating these types, ensure the theme module types are kept in sync.
+ *
+ * @module lib/page-builder/types/theme
+ */
+/**
+ * Theme role - determines the state/purpose of a theme
+ */
+type ThemeRole = "live" | "draft" | "preview";
+/**
+ * Theme configuration object
+ *
+ * Contains design tokens organized by category.
+ * All values are CSS-compatible strings or numbers.
+ */
+interface ThemeConfig {
+    /**
+     * Color palette (e.g., primary, secondary, background, text)
+     */
+    colors?: Record<string, string>;
+    /**
+     * Typography settings (fonts, sizes, weights, line heights)
+     */
+    typography?: Record<string, string | number>;
+    /**
+     * Spacing values (margins, paddings, gaps)
+     */
+    spacing?: Record<string, string>;
+    /**
+     * Border radius values
+     */
+    borderRadius?: Record<string, string>;
+    /**
+     * Box shadow definitions
+     */
+    boxShadow?: Record<string, string>;
+    /**
+     * Transition settings (duration, timing)
+     */
+    transition?: Record<string, string>;
+    /**
+     * Z-index layer definitions
+     */
+    zIndex?: Record<string, number>;
+    /**
+     * Font weight definitions
+     */
+    fontWeight?: Record<string, number>;
+    /**
+     * Width definitions
+     */
+    width?: Record<string, string>;
+    /**
+     * Allow additional custom configuration sections
+     */
+    [key: string]: Record<string, string | number> | undefined;
+}
+/**
+ * Complete theme object with metadata
+ */
+interface Theme {
+    /**
+     * Unique theme identifier
+     */
+    id: string;
+    /**
+     * Human-readable theme name
+     */
+    name: string;
+    /**
+     * Theme role (live, draft, preview)
+     */
+    role: ThemeRole;
+    /**
+     * Theme configuration with all design tokens
+     */
+    config: ThemeConfig;
+    /**
+     * Creation timestamp (ISO string)
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp (ISO string)
+     */
+    updatedAt: string;
+}
+/**
+ * Theme Loader Interface
+ *
+ * Consumers implement this interface to provide theme loading capabilities.
+ * Themes can be loaded from file system, API, database, or any other source.
+ *
+ * @example
+ * ```typescript
+ * const themeLoader: IThemeLoader = {
+ *   async loadTheme(merchantName: string): Promise<Theme> {
+ *     const data = await fetchThemeFromAPI(merchantName);
+ *     return {
+ *       id: data.id,
+ *       name: data.name,
+ *       role: data.role,
+ *       config: data.config,
+ *       createdAt: data.createdAt,
+ *       updatedAt: data.updatedAt,
+ *     };
+ *   }
+ * };
+ * ```
+ */
+interface IThemeLoader {
+    /**
+     * Load the active theme for a merchant
+     *
+     * @param merchantName - The merchant identifier
+     * @returns Promise resolving to the theme configuration
+     * @throws Error if theme cannot be loaded
+     */
+    loadTheme(merchantName: string): Promise<Theme>;
+}
+
+/**
+ * Data Source Types
+ *
+ * Defines data source configuration for fetching commerce data.
+ */
+/**
+ * Data source types constant
+ * Defines all available data source types
+ */
+declare const DATA_SOURCE_TYPES: {
+    /** Single product by handle or ID */
+    readonly PRODUCT: "PRODUCT";
+    /** Multiple products with query/pagination */
+    readonly PRODUCTS: "PRODUCTS";
+    /** Multiple products by specific handles */
+    readonly PRODUCTS_BY_HANDLES: "PRODUCTS_BY_HANDLES";
+    /** Single collection by handle or ID */
+    readonly COLLECTION: "COLLECTION";
+    /** Multiple collections with pagination */
+    readonly COLLECTIONS: "COLLECTIONS";
+    /** Collection with faceted filters (for collection pages) */
+    readonly COLLECTION_PAGE_WITH_FILTERS: "COLLECTION_PAGE_WITH_FILTERS";
+    /** Collection by handler with custom params */
+    readonly COLLECTION_BY_HANDLES: "COLLECTION_BY_HANDLES";
+    /** Static data (no fetching required) */
+    readonly STATIC: "STATIC";
+    /** Product recommendations */
+    readonly PRODUCT_RECOMMENDATIONS: "PRODUCT_RECOMMENDATIONS";
+};
+/**
+ * Data source type union
+ */
+type DataSourceType = (typeof DATA_SOURCE_TYPES)[keyof typeof DATA_SOURCE_TYPES];
+/**
+ * Data source configuration
+ *
+ * Defines how to fetch data for a page or widget.
+ */
+interface DataSourceConfig {
+    /**
+     * Type of data source
+     */
+    type: DataSourceType | string;
+    /**
+     * Parameters for the data source
+     * Structure depends on the data source type
+     */
+    params: Record<string, any>;
+    /**
+     * Whether this data source is required for page rendering
+     * If true, page will fail if data cannot be fetched
+     */
+    required: boolean;
+}
+
+/**
+ * Page Configuration Types
+ *
+ * Defines the structure of page templates including sections and widgets.
+ */
+
+/**
+ * Spacing values for padding/margin
+ */
+interface Spacing {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Responsive spacing configuration
+ */
+interface ResponsiveSpacing {
+    padding?: Spacing;
+    margin?: Spacing;
+}
+/**
+ * Section settings configuration
+ */
+interface SectionSettings {
+    /**
+     * Layout mode
+     * - "page": Constrained to container width
+     * - "full": Full viewport width
+     */
+    layout: "page" | "full";
+    /**
+     * Responsive settings per breakpoint
+     */
+    responsive?: {
+        mobile?: ResponsiveSpacing;
+        tablet?: ResponsiveSpacing;
+        desktop?: ResponsiveSpacing;
+        wide?: ResponsiveSpacing;
+    };
+    /**
+     * Default padding (fallback)
+     */
+    padding?: Spacing;
+    /**
+     * Default margin (fallback)
+     */
+    margin?: Spacing;
+    /**
+     * Additional custom settings
+     */
+    [key: string]: any;
+}
+/**
+ * Widget responsive configuration
+ */
+interface WidgetResponsiveConfig {
+    mobile?: Record<string, any>;
+    tablet?: Record<string, any>;
+    desktop?: Record<string, any>;
+    wide?: Record<string, any>;
+}
+/**
+ * Widget configuration
+ *
+ * Defines a single widget within a section.
+ */
+interface WidgetConfig {
+    /**
+     * Unique widget identifier
+     */
+    id: string;
+    /**
+     * Human-readable widget name
+     */
+    name: string;
+    /**
+     * Widget type - must match a registered widget in the registry
+     */
+    type: string;
+    /**
+     * Reference to a data source key in the page's dataSources
+     */
+    dataSourceKey?: string;
+    /**
+     * Widget settings/configuration
+     * Supports translation keys with "t:" prefix
+     */
+    settings: Record<string, any>;
+    /**
+     * Responsive setting overrides per breakpoint
+     */
+    responsive?: WidgetResponsiveConfig;
+}
+/**
+ * Section configuration
+ *
+ * Defines a section of a page containing widgets.
+ */
+interface SectionConfig {
+    /**
+     * Unique section identifier
+     */
+    id: string;
+    /**
+     * Human-readable section name
+     */
+    name: string;
+    /**
+     * Section type identifier
+     */
+    type: string;
+    /**
+     * Section settings including layout and spacing
+     */
+    settings: SectionSettings;
+    /**
+     * Widgets contained in this section
+     */
+    widgets: WidgetConfig[];
+}
+/**
+ * Page configuration
+ *
+ * The root configuration object defining a complete page template.
+ */
+interface PageConfig {
+    /**
+     * Unique page/template identifier
+     */
+    id: string;
+    /**
+     * Data sources available to widgets on this page
+     * Key is the data source identifier, value is the configuration
+     */
+    dataSources: Record<string, DataSourceConfig>;
+    /**
+     * Page sections in render order
+     */
+    sections: SectionConfig[];
+    /**
+     * Theme overrides for this specific page
+     */
+    theme?: Record<string, any>;
+    /**
+     * Responsive configuration for the page
+     */
+    responsive?: any;
+    /**
+     * Custom breakpoint configuration
+     */
+    breakpoints?: any;
+    /**
+     * Additional metadata
+     */
+    [key: string]: any;
+}
+/**
+ * Template type alias
+ * A template is just a PageConfig
+ */
+type Template = PageConfig;
+/**
+ * Page configuration helpers
+ */
+declare class PageConfigHelpers {
+    /**
+     * Get all data source keys used by widgets
+     */
+    static getUsedDataSources(pageConfig: PageConfig): string[];
+    /**
+     * Find a widget by ID
+     */
+    static findWidget(pageConfig: PageConfig, widgetId: string): WidgetConfig | null;
+    /**
+     * Find a section by ID
+     */
+    static findSection(pageConfig: PageConfig, sectionId: string): SectionConfig | null;
+    /**
+     * Generate a unique ID with prefix
+     */
+    static generateId(prefix: string): string;
+    /**
+     * Validate page configuration structure
+     */
+    static validate(pageConfig: PageConfig): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+/**
+ * Schema definition for sections - used by the editor to generate forms
+ */
+interface SectionSchema {
+    /** Section type identifier */
+    type: string;
+    /** Display name for the editor */
+    name: string;
+    /** Description for the editor */
+    description?: string;
+    /** Settings schema for the section (editor-only, shape matches DynamicForm) */
+    settingsSchema: Record<string, {
+        type: "text" | "number" | "boolean" | "select" | "spacing" | "image" | "faq" | "richtext" | "objectArray" | "array";
+        label?: string;
+        default?: any;
+        options?: Array<{
+            value: any;
+            label: string;
+        }>;
+        min?: number;
+        max?: number;
+        step?: number;
+        unit?: string;
+        optional?: boolean;
+        fields?: string[];
+        placeholder?: string;
+    }>;
+}
+/**
+ * Schema definition for widgets - used by the editor to generate forms
+ */
+interface WidgetSchema {
+    /** Widget type identifier */
+    type: string;
+    /** Display name for the editor */
+    name: string;
+    /** Description for the editor */
+    description?: string;
+    /** Settings schema for the widget */
+    settingsSchema: Record<string, {
+        type: "text" | "number" | "boolean" | "select" | "spacing" | "object" | "array" | "objectArray" | "richtext";
+        label?: string;
+        default?: any;
+        options?: Array<{
+            value: any;
+            label: string;
+        }>;
+        min?: number;
+        max?: number;
+        unit?: string;
+        optional?: boolean;
+        properties?: Record<string, any>;
+        fields?: string[];
+    }>;
+    /** Whether this widget requires a data source */
+    requiresDataSource?: boolean;
+    /** Compatible data source types */
+    compatibleDataSources?: string[];
+    /** Responsive settings that can be overridden */
+    responsiveSettings?: string[];
+}
+/**
+ * Registry types for the editor
+ */
+interface SectionRegistry {
+    [key: string]: SectionSchema;
+}
+/**
+ * Widget Registry for editor (different from IWidgetRegistry)
+ * Maps widget type names to their schemas
+ */
+interface WidgetSchemaRegistry {
+    [key: string]: WidgetSchema;
+}
+
+/**
+ * Template Loader Interface
+ *
+ * Consumers implement this interface to provide template loading capabilities.
+ * Templates can be loaded from file system, API, CMS, or any other source.
+ */
+
+/**
+ * Template variant mapping configuration
+ * Maps API data fields to template variants
+ */
+interface TemplateVariantMapping {
+    /**
+     * The API field to check for variant determination
+     * Supports dot notation for nested fields (e.g., "collection.handle")
+     */
+    apiField: string;
+    /**
+     * Map of API field values to template variant names
+     * Optional - if not provided, defaultVariant is used
+     */
+    variantMap?: Record<string, string>;
+    /**
+     * Default variant to use if no match is found
+     */
+    defaultVariant: string;
+}
+/**
+ * Template Variant Registry
+ * Registry of template variant mappings by template type
+ */
+interface TemplateVariantRegistry {
+    [templateType: string]: TemplateVariantMapping;
+}
+/**
+ * Variant Registry Result
+ * Wrapper for variant registry returned by loadVariantRegistry
+ */
+interface VariantRegistryResult {
+    variantRegistry: TemplateVariantRegistry;
+}
+/**
+ * Template Loader Interface
+ *
+ * Provides methods to load page templates and variant registries.
+ */
+interface ITemplateLoader {
+    /**
+     * Load a page template configuration
+     *
+     * @param merchantName - The merchant identifier
+     * @param templateName - The template type (e.g., "home", "product", "collection")
+     * @param variant - The template variant (e.g., "default", "featured")
+     * @returns Promise resolving to the page configuration
+     */
+    loadTemplate(merchantName: string, templateName: string, variant: string): Promise<PageConfig>;
+    /**
+     * Load variant registry for automatic variant selection
+     * Optional - if not implemented, "default" variant is always used
+     *
+     * @param merchantName - The merchant identifier
+     * @returns Promise resolving to the variant registry wrapper or null
+     */
+    loadVariantRegistry?(merchantName: string): Promise<VariantRegistryResult | null>;
+}
+
+/**
+ * Widget Registry Interface and Default Implementation
+ *
+ * The widget registry maps widget type strings to React components.
+ * Consumers can use the default WidgetRegistry class or provide their own implementation.
+ */
+
+/**
+ * Widget registration entry
+ */
+interface WidgetRegistration {
+    type: string;
+    component: ComponentType<any>;
+}
+/**
+ * Widget Registry Interface
+ *
+ * Maps widget type strings to React components for rendering.
+ */
+interface IWidgetRegistry {
+    /**
+     * Register a single widget component
+     *
+     * @param type - The widget type identifier
+     * @param component - The React component to render
+     */
+    register(type: string, component: ComponentType<any>): void;
+    /**
+     * Register multiple widget components at once
+     *
+     * @param widgets - Array of widget registrations
+     */
+    registerAll(widgets: WidgetRegistration[]): void;
+    /**
+     * Get a widget component by type
+     *
+     * @param type - The widget type identifier
+     * @returns The React component or undefined if not found
+     */
+    get(type: string): ComponentType<any> | undefined;
+    /**
+     * Check if a widget type is registered
+     *
+     * @param type - The widget type identifier
+     * @returns True if the widget is registered
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered widget types
+     *
+     * @returns Array of registered widget type identifiers
+     */
+    getRegisteredTypes(): string[];
+}
+/**
+ * Default Widget Registry Implementation
+ *
+ * A simple Map-based implementation of the widget registry.
+ * Consumers can use this directly or provide their own implementation.
+ */
+declare class WidgetRegistry implements IWidgetRegistry {
+    private widgets;
+    /**
+     * Register a single widget component
+     */
+    register(type: string, component: ComponentType<any>): void;
+    /**
+     * Register multiple widget components at once
+     */
+    registerAll(widgets: WidgetRegistration[]): void;
+    /**
+     * Get a widget component by type
+     */
+    get(type: string): ComponentType<any> | undefined;
+    /**
+     * Check if a widget type is registered
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered widget types
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Clear all registered widgets
+     */
+    clear(): void;
+    /**
+     * Get the total count of registered widgets
+     */
+    get size(): number;
+}
+
+/**
+ * Route Context Types
+ *
+ * Defines the context passed to the page builder for rendering.
+ */
+/**
+ * Viewport breakpoint type
+ */
+type Breakpoint = "mobile" | "tablet" | "desktop" | "wide";
+/**
+ * Breakpoint configuration for responsive design
+ */
+interface BreakpointConfig {
+    mobile: {
+        max: number;
+    };
+    tablet: {
+        min: number;
+        max: number;
+    };
+    desktop: {
+        min: number;
+        max: number;
+    };
+    wide: {
+        min: number;
+    };
+    custom?: Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+}
+/**
+ * Default breakpoints
+ */
+declare const DEFAULT_BREAKPOINTS: BreakpointConfig;
+/**
+ * Viewport information
+ */
+interface ViewportInfo {
+    width: number;
+    height: number;
+    breakpoint: Breakpoint;
+}
+/**
+ * Route Context
+ *
+ * Contains all information about the current route being rendered.
+ */
+interface RouteContext {
+    /**
+     * Template name to use for rendering
+     * e.g., "home", "product", "collection"
+     */
+    templateName: string;
+    /**
+     * Current page path
+     * e.g., "/", "/products/my-product", "/collections/featured"
+     */
+    path: string;
+    /**
+     * URL path parameters
+     * e.g., { handle: "my-product" }
+     */
+    params: Record<string, string>;
+    /**
+     * URL query parameters
+     * e.g., { sort: "price-asc", page: "2" }
+     */
+    query?: Record<string, string | string[] | undefined>;
+    /**
+     * Product handle (for product pages)
+     */
+    productHandle?: string;
+    /**
+     * Collection handle (for collection pages)
+     */
+    collectionHandle?: string;
+    /**
+     * Current viewport information
+     */
+    viewport?: ViewportInfo;
+    /**
+     * Whether to fetch template from API (for visual editor integration)
+     */
+    fetchAPITemplate?: boolean;
+    /**
+     * Additional custom context data
+     */
+    [key: string]: any;
+}
+
+/**
+ * Section Renderer Interface
+ *
+ * Defines the function type for rendering section wrappers.
+ * Consumers can provide custom section rendering logic for styling,
+ * responsive behavior, or special section types.
+ */
+
+/**
+ * Context provided to section renderers
+ */
+interface SectionRenderContext {
+    /**
+     * Merged theme and page styles
+     */
+    styles: Record<string, any>;
+    /**
+     * Current route context
+     */
+    routeContext: RouteContext;
+    /**
+     * Current breakpoint (if detected)
+     */
+    breakpoint?: "mobile" | "tablet" | "desktop" | "wide";
+}
+/**
+ * Section Renderer Function Type
+ *
+ * A function that renders a section wrapper around its children widgets.
+ *
+ * @param section - The section configuration
+ * @param children - The rendered widget React nodes
+ * @param context - Additional context including styles and route info
+ * @returns A React node representing the rendered section
+ */
+type SectionRenderer = (section: SectionConfig, children: ReactNode[], context: SectionRenderContext) => ReactNode;
+
+/**
+ * Locale Type
+ *
+ * Defines supported locales for the page builder.
+ * Internalized to avoid external dependencies.
+ */
+/**
+ * Supported locale codes
+ */
+type Locale = "en" | "hi" | string;
+/**
+ * Default locale
+ */
+declare const DEFAULT_LOCALE: Locale;
+
+/**
+ * Page Building Engine
+ *
+ * The main orchestrator that coordinates all other components to render a page.
+ * All dependencies are injected via constructor for complete encapsulation.
+ */
+
+/**
+ * Render Page Parameters
+ */
+interface RenderPageParams {
+    /**
+     * Merchant identifier - REQUIRED, no fallback
+     */
+    merchantName: string;
+    /**
+     * Route context with template name, path, params
+     */
+    routeContext: RouteContext;
+    /**
+     * Locale for this render
+     */
+    locale?: Locale;
+    /**
+     * Translation messages for i18n
+     */
+    messages?: Record<string, any>;
+    /**
+     * Optional pre-loaded page config (skips template loading)
+     */
+    pageConfig?: PageConfig;
+}
+
+/**
+ * Page Builder Factory Function
+ *
+ * The single public API for creating a page builder instance.
+ * All dependencies are injected through the options parameter.
+ */
+
+/**
+ * Options for creating a page builder instance
+ */
+interface PageBuilderOptions {
+    /**
+     * Commerce client for fetching products, collections, etc.
+     * REQUIRED - consumers must implement ICommerceClient
+     */
+    commerceClient: ICommerceClient;
+    /**
+     * Theme loader for fetching merchant themes
+     * REQUIRED - consumers implement how themes are loaded
+     */
+    themeLoader: IThemeLoader;
+    /**
+     * Template loader for fetching page templates
+     * REQUIRED - consumers implement how templates are loaded
+     */
+    templateLoader: ITemplateLoader;
+    /**
+     * Widget registry with all registered widget components
+     * REQUIRED - consumers populate with their widgets
+     */
+    widgetRegistry: IWidgetRegistry;
+    /**
+     * Custom section renderer component
+     * OPTIONAL - defaults to a basic <section> wrapper
+     */
+    sectionRenderer?: SectionRenderer;
+    /**
+     * Default locale for the page builder
+     * OPTIONAL - defaults to 'en'
+     */
+    defaultLocale?: Locale;
+}
+/**
+ * Validation result for page config
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Page Builder Interface
+ *
+ * The public interface returned by createPageBuilder()
+ */
+interface PageBuilder {
+    /**
+     * Render a page to React nodes
+     */
+    renderPage(params: RenderPageParams): Promise<React.ReactNode>;
+    /**
+     * Clear internal caches
+     */
+    clearCache(): void;
+    /**
+     * Validate a page configuration
+     */
+    validateConfig(config: PageConfig): ValidationResult;
+}
+/**
+ * Create a new page builder instance
+ *
+ * This is the main entry point for using the page builder.
+ * All dependencies are provided through the options parameter.
+ *
+ * @example
+ * ```typescript
+ * import { createPageBuilder, WidgetRegistry } from '@/lib/page-builder';
+ *
+ * // Create and populate widget registry
+ * const widgetRegistry = new WidgetRegistry();
+ * widgetRegistry.registerAll([
+ *   { type: 'Header', component: HeaderWidget },
+ *   { type: 'ProductCard', component: ProductCardWidget },
+ * ]);
+ *
+ * // Create page builder with all dependencies
+ * const pageBuilder = createPageBuilder({
+ *   commerceClient: myCommerceClient,
+ *   themeLoader: myThemeLoader,
+ *   templateLoader: myTemplateLoader,
+ *   widgetRegistry,
+ *   defaultLocale: 'en',
+ * });
+ *
+ * // Use in pages
+ * const content = await pageBuilder.renderPage({
+ *   merchantName: 'my-merchant',
+ *   routeContext: {
+ *     templateName: 'home',
+ *     path: '/',
+ *     params: {},
+ *   },
+ * });
+ * ```
+ */
+declare function createPageBuilder(options: PageBuilderOptions): PageBuilder;
+
+/**
+ * Layout and Alignment Options
+ *
+ * Type-safe constants for layout and alignment values used in templates.
+ * These constants are exported from the page-builder package for use in templates.
+ */
+/**
+ * Section Types
+ * Defines the semantic types of sections in a page layout.
+ * Moved here from ui/layout/constants to centralize all template constants.
+ */
+declare const SECTION_TYPES: {
+    readonly HEADER_SECTION: "HEADER_SECTION";
+    readonly GRID_SECTION: "GRID_SECTION";
+    readonly HERO_SECTION: "HERO_SECTION";
+    readonly CONTENT_SECTION: "CONTENT_SECTION";
+    readonly FOOTER_SECTION: "FOOTER_SECTION";
+};
+type SectionType = (typeof SECTION_TYPES)[keyof typeof SECTION_TYPES];
+/**
+ * Section Layout Options
+ * Extracted from section schema registry
+ */
+declare const SECTION_LAYOUT_OPTIONS: {
+    readonly PAGE: "page";
+    readonly FULL: "full";
+};
+/**
+ * Section Alignment Options
+ * Extracted from section schema registry
+ */
+declare const SECTION_ALIGNMENT_OPTIONS: {
+    readonly LEFT: "left";
+    readonly CENTER: "center";
+    readonly RIGHT: "right";
+};
+/**
+ * Widget Aspect Ratio Options
+ * Extracted from widget schema registry
+ */
+declare const ASPECT_RATIO_OPTIONS: {
+    readonly SQUARE: "1:1";
+    readonly STANDARD: "4:3";
+    readonly CLASSIC: "3:2";
+    readonly WIDE: "16:9";
+};
+/**
+ * Widget Text Alignment Options
+ */
+declare const TEXT_ALIGNMENT_OPTIONS: {
+    readonly LEFT: "left";
+    readonly CENTER: "center";
+    readonly RIGHT: "right";
+};
+/**
+ * Card Style Options
+ */
+declare const CARD_STYLE_OPTIONS: {
+    readonly STANDARD: "standard";
+    readonly COMPACT: "compact";
+    readonly MINIMAL: "minimal";
+};
+/**
+ * Type definitions for better type safety
+ */
+type SectionLayoutOption = (typeof SECTION_LAYOUT_OPTIONS)[keyof typeof SECTION_LAYOUT_OPTIONS];
+type SectionAlignmentOption = (typeof SECTION_ALIGNMENT_OPTIONS)[keyof typeof SECTION_ALIGNMENT_OPTIONS];
+type AspectRatioOption = (typeof ASPECT_RATIO_OPTIONS)[keyof typeof ASPECT_RATIO_OPTIONS];
+type TextAlignmentOption = (typeof TEXT_ALIGNMENT_OPTIONS)[keyof typeof TEXT_ALIGNMENT_OPTIONS];
+type CardStyleOption = (typeof CARD_STYLE_OPTIONS)[keyof typeof CARD_STYLE_OPTIONS];
+
+/**
+ * Widget Props Types
+ *
+ * Base prop types that all widgets receive from the page builder.
+ */
+
+/**
+ * Base Widget Props
+ *
+ * All widgets receive these props from the page builder.
+ * Widgets can extend this with their own specific data and settings types.
+ *
+ * @template TData - Type of data the widget receives (default: any)
+ * @template TSettings - Type of settings the widget accepts (default: Record<string, any>)
+ */
+interface WidgetProps<TData = any, TSettings = Record<string, any>> {
+    /**
+     * Unique widget instance ID
+     */
+    id: string;
+    /**
+     * Data fetched from the widget's data source
+     */
+    data: TData;
+    /**
+     * Widget configuration settings
+     * These come from the template and may include translated values
+     */
+    settings: TSettings;
+    /**
+     * Current locale
+     */
+    locale?: Locale;
+    /**
+     * Current route context
+     */
+    routeContext?: RouteContext;
+    /**
+     * Optional CSS class name for additional styling
+     */
+    className?: string;
+}
+
+/**
+ * Default Section Wrapper Component
+ *
+ * A simple default section wrapper used when consumers don't provide
+ * a custom section renderer.
+ */
+
+/**
+ * Default Section Wrapper
+ *
+ * Renders a section with responsive spacing and layout constraints.
+ */
+declare function DefaultSectionWrapper(section: SectionConfig, children: React.ReactNode[], context: SectionRenderContext): React.ReactNode;
+
+/**
+ * File System Preset
+ *
+ * Pre-configured page builder for file-system based theme and template loading.
+ * This preset is fully injectable - all dependencies must be provided by the consumer.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { getPageBuilder } from "@/lib/page-builder/presets";
+ * import { WIDGET_MANIFEST } from "@/widgets/.generated/manifest";
+ * import { getCommerceClient } from "@/lib/data-layer";
+ * import { SectionWrapper } from "@/ui/layout/SectionWrapper";
+ *
+ * // Initialize with required dependencies
+ * const pageBuilder = getPageBuilder({
+ *   widgets: WIDGET_MANIFEST,
+ *   commerceClient: getCommerceClient(),
+ *   sectionRenderer: SectionWrapper,
+ *   themeLoader: { loadTheme: async (merchant) => import(`@/themes/${merchant}/theme.json`) },
+ *   templateLoader: { loadTemplate: async (merchant, template, variant) => ... },
+ * });
+ *
+ * // Use in page
+ * const content = await pageBuilder.renderPage({
+ *   merchantName: "wellversed",
+ *   routeContext: { templateName: "home", path: "/", params: {} },
+ * });
+ * ```
+ */
+
+/**
+ * Widget registration entry
+ */
+interface WidgetEntry {
+    type: string;
+    component: React.ComponentType<any>;
+}
+/**
+ * Options for creating a file-system based page builder
+ *
+ * All dependencies are injectable - no external imports are used internally.
+ */
+interface FileSystemPresetOptions {
+    /**
+     * Array of widget registrations.
+     * REQUIRED - must be provided by consumer.
+     *
+     * @example
+     * ```typescript
+     * import { WIDGET_MANIFEST } from "@/widgets/.generated/manifest";
+     * getPageBuilder({ widgets: WIDGET_MANIFEST, ... });
+     * ```
+     */
+    widgets: WidgetEntry[];
+    /**
+     * Commerce client for fetching products/collections.
+     * REQUIRED - must be provided by consumer.
+     *
+     * @example
+     * ```typescript
+     * import { getCommerceClient } from "@/lib/data-layer";
+     * getPageBuilder({ commerceClient: getCommerceClient(), ... });
+     * ```
+     */
+    commerceClient: ICommerceClient;
+    /**
+     * Theme loader for loading merchant themes.
+     * REQUIRED - must be provided by consumer.
+     *
+     * @example
+     * ```typescript
+     * const themeLoader = {
+     *   loadTheme: async (merchant) => {
+     *     const mod = await import(`@/themes/${merchant}/theme.json`);
+     *     return { id: mod.default.id, name: mod.default.name, ... };
+     *   }
+     * };
+     * ```
+     */
+    themeLoader: IThemeLoader;
+    /**
+     * Template loader for loading page templates.
+     * REQUIRED - must be provided by consumer.
+     *
+     * @example
+     * ```typescript
+     * const templateLoader = {
+     *   loadTemplate: async (merchant, template, variant) => {
+     *     const mod = await import(`@/themes/${merchant}/templates/${template}/${variant}`);
+     *     return mod.template;
+     *   },
+     *   loadVariantRegistry: async (merchant) => {
+     *     try {
+     *       return await import(`@/themes/${merchant}/templates/variant-registry`);
+     *     } catch { return null; }
+     *   }
+     * };
+     * ```
+     */
+    templateLoader: ITemplateLoader;
+    /**
+     * Custom section renderer function or component.
+     * OPTIONAL - defaults to DefaultSectionWrapper.
+     *
+     * @example
+     * ```typescript
+     * import { SectionWrapper } from "@/ui/layout/SectionWrapper";
+     *
+     * // Wrap component as SectionRenderer function
+     * const sectionRenderer = (section, children, context) =>
+     *   React.createElement(SectionWrapper, { section, styles: context.styles, children });
+     * ```
+     */
+    sectionRenderer?: SectionRenderer;
+    /**
+     * Default locale for translations.
+     * OPTIONAL - defaults to "en".
+     */
+    defaultLocale?: string;
+}
+/**
+ * Creates a new file-system based page builder instance
+ *
+ * Use this when you need a fresh instance (e.g., testing).
+ * For most cases, use `getPageBuilder()` instead.
+ *
+ * @throws Error if required options are missing
+ */
+declare function createFileSystemPageBuilder(options: FileSystemPresetOptions): PageBuilder;
+/**
+ * Gets the singleton page builder instance
+ *
+ * This is the recommended way to get a page builder in production.
+ * The instance is created on first call and reused thereafter.
+ *
+ * NOTE: All dependencies must be provided on first call.
+ * Subsequent calls can omit options (singleton is returned).
+ *
+ * @throws Error if required options are missing on first call
+ *
+ * @example
+ * ```typescript
+ * // First call - provide all dependencies
+ * const pageBuilder = getPageBuilder({
+ *   widgets: WIDGET_MANIFEST,
+ *   commerceClient: getCommerceClient(),
+ *   themeLoader: myThemeLoader,
+ *   templateLoader: myTemplateLoader,
+ * });
+ *
+ * // Subsequent calls - singleton returned
+ * const same = getPageBuilder(); // Returns same instance
+ * ```
+ */
+declare function getPageBuilder(options?: FileSystemPresetOptions): PageBuilder;
+/**
+ * Resets the singleton instance
+ *
+ * Useful for testing or when you need to reinitialize with different options.
+ */
+declare function resetPageBuilder(): void;
+/**
+ * Creates a section renderer from a React component
+ *
+ * Utility to wrap a SectionWrapper component as a SectionRenderer function.
+ *
+ * @example
+ * ```typescript
+ * import { SectionWrapper } from "@/ui/layout/SectionWrapper";
+ *
+ * getPageBuilder({
+ *   sectionRenderer: createSectionRendererFromComponent(SectionWrapper),
+ *   ...
+ * });
+ * ```
+ */
+declare function createSectionRendererFromComponent(Component: React.ComponentType<{
+    section: SectionConfig;
+    styles: Record<string, any>;
+    children: React.ReactNode[];
+}>): SectionRenderer;
+/**
+ * Creates a commerce client adapter
+ *
+ * Wraps an existing client to ensure it matches the ICommerceClient interface.
+ *
+ * @example
+ * ```typescript
+ * import { shopifyClient } from "@/lib/shopify";
+ *
+ * getPageBuilder({
+ *   commerceClient: createCommerceClientAdapter(shopifyClient),
+ *   ...
+ * });
+ * ```
+ */
+declare function createCommerceClientAdapter(client: {
+    getProduct: (params: any) => Promise<any>;
+    getProducts: (params: any) => Promise<any>;
+    getProductRecommendations: (id: string) => Promise<any>;
+    getCollection: (params: any) => Promise<any>;
+    getCollections: (params: any) => Promise<any>;
+    getCollectionWithFilters?: (params: any) => Promise<any>;
+    getCollectionsByHandler?: (params: any) => Promise<any>;
+}): ICommerceClient;
+
+export { ASPECT_RATIO_OPTIONS, type AspectRatioOption, type Breakpoint, type BreakpointConfig, CARD_STYLE_OPTIONS, type CardStyleOption, DATA_SOURCE_TYPES, DEFAULT_BREAKPOINTS, DEFAULT_LOCALE, type DataSourceConfig, type DataSourceType, DefaultSectionWrapper, type FileSystemPresetOptions, type ICommerceClient, type ITemplateLoader, type IThemeLoader, type IWidgetRegistry, type Locale, type PageBuilder, type PageBuilderOptions, type PageConfig, PageConfigHelpers, type RenderPageParams, type ResponsiveSpacing, type RouteContext, SECTION_ALIGNMENT_OPTIONS, SECTION_LAYOUT_OPTIONS, SECTION_TYPES, type SectionAlignmentOption, type SectionConfig, type SectionLayoutOption, type SectionRegistry, type SectionRenderContext, type SectionRenderer, type SectionSchema, type SectionSettings, type SectionType, type Spacing, TEXT_ALIGNMENT_OPTIONS, type Template, type TemplateVariantRegistry, type TextAlignmentOption, type Theme, type ThemeConfig, type ThemeRole, type ValidationResult, type VariantRegistryResult, type ViewportInfo, type WidgetConfig, type WidgetEntry, type WidgetProps, WidgetRegistry, type WidgetResponsiveConfig, type WidgetSchema, type WidgetSchemaRegistry, createCommerceClientAdapter, createFileSystemPageBuilder, createPageBuilder, createSectionRendererFromComponent, getPageBuilder, resetPageBuilder };