@salesforce/storefront-next-runtime 0.1.0

package/dist/design-styles.css

@@ -0,0 +1,232 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+/* Base styles shared by both component and fragment */
+.pd-design__decorator {
+  /* Temporary color for drop targets */
+  --pd-design-drop-target-color: #008827;
+  --pd-design-outline-width: 1px;
+  --pd-design-selected-color: #005fb2;
+  --pd-design-drop-target-width: 2px;
+  --pd-design-fallback-badge-color: rgb(172, 47, 109);
+  --pd-design-region-border-color: #3e3e3c;
+  --pd-design-drop-target-offset: 10px;
+  --pd-design-base-z-index: 30;
+}
+
+.pd-design__component,
+.pd-design__region,
+.pd-design__fragment {
+  position: relative;
+}
+
+.pd-design__component {
+  --pd-design-color: #0070d2;
+}
+
+.pd-design__fragment {
+  --pd-design-color: #8402ad;
+}
+
+.pd-design__component.pd-design__component--unlocalized,
+.pd-design__component.pd-design__decorator--selected.pd-design__component--unlocalized {
+  --pd-design-color: rgb(215, 58, 138);
+}
+
+.pd-design__frame__overlay {
+  pointer-events: none;
+  display: none;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: calc(var(--pd-design-base-z-index) + 2);
+}
+
+.pd-design__component--unlocalized .pd-design__frame--visible .pd-design__frame__overlay {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+
+
+.pd-design__component--unlocalized .pd-design__frame__overlay {
+  background-color: rgba(0, 0, 0, 0.25);
+}
+
+/* Shared state styles */
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--x::before,
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--x::after,
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--y::before,
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--y::after {
+  background-color: var(--pd-design-color);
+  content: '';
+  display: block;
+  position: absolute;
+  z-index: var(--pd-design-base-z-index);
+}
+
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--y::before {
+  height: var(--pd-design-outline-width);
+  left: -1px;
+  top: -1px;
+  width: calc(100% + 2px);
+}
+
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--y::after {
+  bottom: -1px;
+  height: var(--pd-design-outline-width);
+  left: -1px;
+  width: calc(100% + 2px)
+}
+
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--x::before {
+  height: 100%;
+  left: -1px;
+  width: var(--pd-design-outline-width);
+}
+
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame--x::after {
+  height: 100%;
+  right: -1px;
+  width: var(--pd-design-outline-width);
+}
+
+.pd-design__frame__label {
+  align-items: center;
+  background: var(--pd-design-color);
+  border-top-left-radius: 4px;
+  border-top-right-radius: 4px;
+  color: white;
+  font-family: 'Salesforce Sans', sans-serif;
+  font-size: 0.75rem;
+  font-weight: 500;
+  height: 32px;
+  left: 50%;
+  letter-spacing: 0.5px;
+  padding: 0 12px;
+  position: absolute;
+  top: -32px;
+  transform: translateX(-50%);
+  display: none;
+  white-space: nowrap;
+}
+
+.pd-design__frame__toolbox {
+  align-items: center;
+  background: var(--pd-design-color);
+  display: flex;
+  position: absolute;
+  right: 0;
+  top: 0;
+  visibility: hidden;
+  z-index: calc(var(--pd-design-base-z-index) + 3);
+}
+
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame__toolbox {
+  visibility: visible;
+}
+
+.pd-design__frame.pd-design__frame--visible > .pd-design__frame__label {
+  display: inline-flex;
+}
+
+.pd-design__component.pd-design__decorator--selected {
+  --pd-design-color: var(--pd-design-selected-color);
+  --pd-design-outline-width: 2px;
+}
+
+.pd-design__frame__name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.pd-design__frame__toolbox-button {
+  align-items: center;
+  background: rgba(0, 0, 0, 0);
+  border: none;
+  cursor: pointer;
+  display: flex;
+  height: 20px;
+  justify-content: center;
+  padding: 0;
+  transition: background-color 0.2s ease-in-out;
+  width: 20px;
+}
+
+.pd-design__frame__toolbox-button:hover {
+  background: rgba(0, 0, 0, 0.2);
+}
+
+.pd-design__frame__delete-icon,
+.pd-design__frame__move-icon {
+  color: white;
+  fill: white;
+  height: 12px;
+  width: 12px;
+}
+
+.pd-design__frame__fallback-badge {
+  background: var(--pd-design-fallback-badge-color);
+  border-radius: 15rem;
+  display: inline-block;
+  font-size: .75rem;
+  line-height: normal;
+  margin-left: .5rem;
+  padding: .25rem .5rem;
+  white-space: nowrap;
+}
+
+.pd-design__region {
+  --pd-design-color: var(--pd-design-drop-target-color);
+
+  outline: 1px dotted var(--pd-design-region-border-color);
+  min-height: 50px;
+  min-width: 50px;
+}
+
+.pd-design__region--hovered {
+  --pd-design-outline-width: 1px;
+}
+
+.pd-design__component__drop-target {
+  background-color: var(--pd-design-drop-target-color);
+  height: 0;
+  left: 0;
+  position: absolute;
+  top: 0;
+  width: 0;
+  z-index: var(--pd-design-base-z-index);
+}
+
+.pd-design__drop-target__y-before > .pd-design__component__drop-target {
+  height: var(--pd-design-drop-target-width);
+  top: calc(calc(var(--pd-design-drop-target-offset) * -1) - calc(var(--pd-design-drop-target-width) / 2));
+  width: 100%;
+}
+
+.pd-design__drop-target__y-after > .pd-design__component__drop-target {
+  bottom: calc(var(--pd-design-drop-target-offset) - calc(var(--pd-design-drop-target-width) / 2));
+  height: var(--pd-design-drop-target-width);
+  top: unset;
+  width: 100%;
+}
+
+.pd-design__drop-target__x-before > .pd-design__component__drop-target {
+  height: 100%;
+  left: calc(calc(var(--pd-design-drop-target-offset) * -1) - calc(var(--pd-design-drop-target-width) / 2));
+  width: var(--pd-design-drop-target-width);
+}
+
+.pd-design__drop-target__x-after > .pd-design__component__drop-target {
+  height: 100%;
+  left: unset;
+  right: calc(var(--pd-design-drop-target-offset) - calc(var(--pd-design-drop-target-width) / 2));
+  width: var(--pd-design-drop-target-width);
+}

package/dist/design.d.ts

@@ -0,0 +1,2 @@
+import { a as DesignMetadata, c as LoaderNames, i as ComponentRegistryOptions, n as ComponentId, o as Entry, r as ComponentModule, s as FrameworkAdapter, t as ComponentRegistry } from "./index.js";
+export { ComponentId, ComponentModule, ComponentRegistry, ComponentRegistryOptions, DesignMetadata, Entry, FrameworkAdapter, LoaderNames };

package/dist/design.js

@@ -0,0 +1,219 @@
+//#region src/design/registry/registry.ts
+/**
+* Framework-agnostic ComponentRegistry manages component loading with static registration.
+*
+* Features:
+* - Framework agnostic core with adapter pattern
+* - Lazy loading via framework adapters for code splitting
+* - Static component registration via build plugins (no dynamic discovery)
+* - Design mode decoration via framework adapters
+* - Request deduplication for concurrent component loads
+* - Component metadata handled via API (not stored in registry)
+*
+* @template TProps - Component props type
+*
+* @example
+* ```tsx
+* const registry = new ComponentRegistry({
+*   adapter: new ReactAdapter(),
+*   designDecorator: createDesignDecorator,
+* });
+*
+* // Components are pre-registered via static registry plugin
+* // Get a component
+* const Hero = registry.getComponent('hero');
+*
+* // Preload for SSR
+* await registry.preload('hero');
+* ```
+*/
+var ComponentRegistry = class {
+	registry = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	cancelled = /* @__PURE__ */ new Set();
+	adapter;
+	constructor({ adapter }) {
+		this.adapter = adapter;
+	}
+	/**
+	* Registers a component in the registry with the specified id.
+	* If a component with the same id already exists, it will be overwritten.
+	*/
+	registerComponent(id, component) {
+		const prev = this.registry.get(id) ?? {
+			id,
+			raw: null
+		};
+		this.registry.set(id, {
+			...prev,
+			id,
+			raw: component
+		});
+	}
+	/**
+	* Registers a dynamic importer for a component id. Useful if you don't want to rely on scanning.
+	*/
+	registerImporter(id, importer, loaderNames) {
+		const prev = this.registry.get(id) ?? {
+			id,
+			raw: null
+		};
+		this.registry.set(id, {
+			...prev,
+			id,
+			import: importer,
+			loaderNames
+		});
+	}
+	/**
+	* Retrieves a component by id. Returns a framework-specific component type.
+	* In lazy loading scenarios, this will be a lazy component if the component
+	* is discovered via dynamic import. In design mode, the returned component
+	* is decorated via `designDecorator`.
+	*/
+	getComponent(id) {
+		const e = this.ensureLocalEntry(id);
+		if (!e) return null;
+		const comp = e.raw ?? e.lazy ?? null;
+		if (!comp) return null;
+		return this.adapter.decorateComponent(comp);
+	}
+	/**
+	* Preload the JS chunk for a component id (use in route loaders/SSR to avoid waterfalls).
+	*
+	* This method ensures the component module is loaded and cached. Concurrent calls
+	* for the same component ID are automatically deduplicated via the pending map
+	* in ensureDiscovered().
+	*
+	* @throws Error if the component cannot be discovered
+	*/
+	async preload(id) {
+		const e = await this.ensureDiscovered(id);
+		if (e?.lazy || e?.raw) return;
+		throw new Error(`Component "${id}" could not be discovered (no importer, no raw/lazy).`);
+	}
+	/** Get loader function names for external invocation. */
+	getLoaderNames(id) {
+		return this.registry.get(id)?.loaderNames;
+	}
+	hasLoaders(id) {
+		return Object.values(this.registry.get(id)?.loaderNames || {}).filter(Boolean).length > 0;
+	}
+	/**
+	* Call a loader function for a component externally.
+	*
+	* @param id - Component ID
+	* @param loaderArgs - Arguments to pass to the loader function
+	* @param loaderType - Type of loader to call ('loader' or 'clientLoader')
+	* @returns Promise resolving to the loader result
+	*/
+	async callLoader(id, loaderArgs, loaderType = "loader") {
+		const loaderName = this.getLoaderNames(id)?.[loaderType];
+		if (!loaderName) return Promise.resolve(void 0);
+		const entry = this.registry.get(id);
+		if (!entry?.import) throw new Error(`No importer found for component: ${id}`);
+		try {
+			const loaderFunction = (await entry.import())[loaderName];
+			if (typeof loaderFunction !== "function") return;
+			return await loaderFunction(loaderArgs);
+		} catch (error) {
+			throw new Error(`Failed to call ${loaderType} for component '${id}': ${error.message}`);
+		}
+	}
+	/** Get fallback component if available. */
+	getFallback(id) {
+		return this.registry.get(id)?.fallback;
+	}
+	/**
+	* Returns all registered component IDs.
+	* Useful for debugging and introspection.
+	*/
+	getRegisteredIds() {
+		return Array.from(this.registry.keys());
+	}
+	/**
+	* Checks if a component is registered.
+	*/
+	has(id) {
+		return this.registry.has(id);
+	}
+	/**
+	* Clears all cached components and cancels pending discoveries.
+	* In-flight async operations will be cancelled and their promises will reject.
+	* Useful for testing or hot module replacement.
+	*/
+	clear() {
+		for (const id of this.pending.keys()) this.cancelled.add(id);
+		this.registry.clear();
+		this.pending.clear();
+	}
+	ensureLocalEntry(id) {
+		const cached = this.registry.get(id);
+		if (cached) return cached;
+		const placeholder = {
+			id,
+			raw: null
+		};
+		this.registry.set(id, placeholder);
+		this.ensureDiscovered(id);
+		return placeholder;
+	}
+	/**
+	* Ensures a component is discovered and cached.
+	* Only returns early if a raw (eagerly loaded) component exists.
+	* Otherwise, attempts to discover via registered importer.
+	*
+	* @throws Error if the discovery is cancelled via clear()
+	*/
+	async ensureDiscovered(id) {
+		const existing = this.registry.get(id);
+		if (existing?.raw) return existing;
+		if (this.pending.has(id)) return this.pending.get(id) ?? null;
+		const work = (async () => {
+			if (this.cancelled.has(id)) {
+				this.cancelled.delete(id);
+				throw new Error(`Component discovery for "${id}" was cancelled`);
+			}
+			let entry = this.registry.get(id) ?? {
+				id,
+				raw: null
+			};
+			if (entry.import) {
+				entry = await this.buildFromImporter(id, entry.import);
+				if (this.cancelled.has(id)) {
+					this.cancelled.delete(id);
+					throw new Error(`Component discovery for "${id}" was cancelled`);
+				}
+				this.registry.set(id, entry);
+				return entry;
+			}
+			return this.registry.get(id) ?? null;
+		})();
+		this.pending.set(id, work);
+		try {
+			const done = await work;
+			this.pending.delete(id);
+			return done;
+		} catch (error) {
+			this.pending.delete(id);
+			throw error;
+		}
+	}
+	async buildFromImporter(id, importer) {
+		const mod = await importer();
+		return this.buildFromLoadedModule(id, importer, mod);
+	}
+	buildFromLoadedModule(id, importer, mod) {
+		return {
+			id,
+			raw: null,
+			lazy: this.adapter.createLazyComponent(importer),
+			import: importer,
+			fallback: mod.fallback
+		};
+	}
+};
+
+//#endregion
+export { ComponentRegistry };
+//# sourceMappingURL=design.js.map

package/dist/design.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.js","names":["placeholder: Entry<TProps, TFrameworkComponent>"],"sources":["../src/design/registry/registry.ts"],"sourcesContent":["/**\n * Copyright 2026 Salesforce, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n    ComponentId,\n    LoaderNames,\n    ComponentModule,\n    Entry,\n    FrameworkAdapter,\n    ComponentRegistryOptions,\n} from './types';\n\n/**\n * Framework-agnostic ComponentRegistry manages component loading with static registration.\n *\n * Features:\n * - Framework agnostic core with adapter pattern\n * - Lazy loading via framework adapters for code splitting\n * - Static component registration via build plugins (no dynamic discovery)\n * - Design mode decoration via framework adapters\n * - Request deduplication for concurrent component loads\n * - Component metadata handled via API (not stored in registry)\n *\n * @template TProps - Component props type\n *\n * @example\n * ```tsx\n * const registry = new ComponentRegistry({\n *   adapter: new ReactAdapter(),\n *   designDecorator: createDesignDecorator,\n * });\n *\n * // Components are pre-registered via static registry plugin\n * // Get a component\n * const Hero = registry.getComponent('hero');\n *\n * // Preload for SSR\n * await registry.preload('hero');\n * ```\n */\nexport class ComponentRegistry<TProps, TFrameworkComponent = unknown> {\n    private readonly registry = new Map<ComponentId, Entry<TProps, TFrameworkComponent>>();\n    private readonly pending = new Map<ComponentId, Promise<Entry<TProps, TFrameworkComponent> | null>>();\n    private readonly cancelled = new Set<ComponentId>();\n\n    private readonly adapter: FrameworkAdapter<TProps, TFrameworkComponent>;\n\n    constructor({ adapter }: ComponentRegistryOptions<TProps, TFrameworkComponent>) {\n        this.adapter = adapter;\n    }\n\n    /**\n     * Registers a component in the registry with the specified id.\n     * If a component with the same id already exists, it will be overwritten.\n     */\n    registerComponent(id: ComponentId, component: TFrameworkComponent): void {\n        const prev = this.registry.get(id) ?? ({ id, raw: null } as Entry<TProps, TFrameworkComponent>);\n        this.registry.set(id, { ...prev, id, raw: component });\n    }\n\n    /**\n     * Registers a dynamic importer for a component id. Useful if you don't want to rely on scanning.\n     */\n    registerImporter(\n        id: ComponentId,\n        importer: () => Promise<ComponentModule<TProps, TFrameworkComponent>>,\n        loaderNames?: LoaderNames\n    ): void {\n        const prev = this.registry.get(id) ?? ({ id, raw: null } as Entry<TProps, TFrameworkComponent>);\n        this.registry.set(id, { ...prev, id, import: importer, loaderNames });\n    }\n\n    /**\n     * Retrieves a component by id. Returns a framework-specific component type.\n     * In lazy loading scenarios, this will be a lazy component if the component\n     * is discovered via dynamic import. In design mode, the returned component\n     * is decorated via `designDecorator`.\n     */\n    getComponent(id: ComponentId): TFrameworkComponent | null {\n        const e = this.ensureLocalEntry(id);\n        if (!e) return null;\n\n        const comp = e.raw ?? e.lazy ?? null;\n        if (!comp) return null;\n\n        return this.adapter.decorateComponent(comp);\n    }\n\n    /**\n     * Preload the JS chunk for a component id (use in route loaders/SSR to avoid waterfalls).\n     *\n     * This method ensures the component module is loaded and cached. Concurrent calls\n     * for the same component ID are automatically deduplicated via the pending map\n     * in ensureDiscovered().\n     *\n     * @throws Error if the component cannot be discovered\n     */\n    async preload(id: ComponentId): Promise<void> {\n        // Wait for discovery to finish (this.pending deduplicates concurrent calls)\n        const e = await this.ensureDiscovered(id);\n\n        // If we have a lazy or raw component, we're done.\n        // The importer was already called during ensureDiscovered if needed.\n        if (e?.lazy || e?.raw) {\n            return;\n        }\n\n        // At this point discovery finished and we still don't have a component:\n        // reject so the nearest ErrorBoundary can render an error state.\n        throw new Error(`Component \"${id}\" could not be discovered (no importer, no raw/lazy).`);\n    }\n\n    /** Get loader function names for external invocation. */\n    getLoaderNames(id: ComponentId): LoaderNames | undefined {\n        return this.registry.get(id)?.loaderNames;\n    }\n\n    hasLoaders(id: ComponentId): boolean {\n        return Object.values(this.registry.get(id)?.loaderNames || {}).filter(Boolean).length > 0;\n    }\n\n    /**\n     * Call a loader function for a component externally.\n     *\n     * @param id - Component ID\n     * @param loaderArgs - Arguments to pass to the loader function\n     * @param loaderType - Type of loader to call ('loader' or 'clientLoader')\n     * @returns Promise resolving to the loader result\n     */\n    async callLoader(id: ComponentId, loaderArgs: unknown, loaderType: keyof LoaderNames = 'loader'): Promise<unknown> {\n        // Get loader names for the component\n        const loaderNames = this.getLoaderNames(id);\n        const loaderName = loaderNames?.[loaderType];\n\n        if (!loaderName) {\n            return Promise.resolve(undefined);\n        }\n\n        // Get the entry to access the import function\n        const entry = this.registry.get(id);\n        if (!entry?.import) {\n            throw new Error(`No importer found for component: ${id}`);\n        }\n\n        try {\n            // Import the module and get the loader function\n            const module = await entry.import();\n            const loaderFunction = module[loaderName];\n\n            if (typeof loaderFunction !== 'function') {\n                return undefined;\n            }\n\n            // Call the loader function with the provided arguments\n            return await loaderFunction(loaderArgs);\n        } catch (error) {\n            throw new Error(`Failed to call ${loaderType} for component '${id}': ${(error as Error).message}`);\n        }\n    }\n\n    /** Get fallback component if available. */\n    getFallback(id: ComponentId): TFrameworkComponent | undefined {\n        return this.registry.get(id)?.fallback;\n    }\n\n    /**\n     * Returns all registered component IDs.\n     * Useful for debugging and introspection.\n     */\n    getRegisteredIds(): ComponentId[] {\n        return Array.from(this.registry.keys());\n    }\n\n    /**\n     * Checks if a component is registered.\n     */\n    has(id: ComponentId): boolean {\n        return this.registry.has(id);\n    }\n\n    /**\n     * Clears all cached components and cancels pending discoveries.\n     * In-flight async operations will be cancelled and their promises will reject.\n     * Useful for testing or hot module replacement.\n     */\n    clear(): void {\n        // Mark all pending discoveries as cancelled\n        for (const id of this.pending.keys()) {\n            this.cancelled.add(id);\n        }\n\n        this.registry.clear();\n        this.pending.clear();\n    }\n\n    /* ==================== Private Methods ==================== */\n\n    private ensureLocalEntry(id: ComponentId): Entry<TProps, TFrameworkComponent> | null {\n        const cached = this.registry.get(id);\n        if (cached) {\n            return cached;\n        }\n\n        // Create a placeholder entry so concurrent calls coalesce.\n        const placeholder: Entry<TProps, TFrameworkComponent> = { id, raw: null };\n        this.registry.set(id, placeholder);\n\n        // Kick off discovery in background; callers that need it awaited should call ensureDiscovered.\n        // eslint-disable-next-line @typescript-eslint/no-floating-promises\n        this.ensureDiscovered(id);\n\n        return placeholder;\n    }\n\n    /**\n     * Ensures a component is discovered and cached.\n     * Only returns early if a raw (eagerly loaded) component exists.\n     * Otherwise, attempts to discover via registered importer.\n     *\n     * @throws Error if the discovery is cancelled via clear()\n     */\n    private async ensureDiscovered(id: ComponentId): Promise<Entry<TProps, TFrameworkComponent> | null> {\n        const existing = this.registry.get(id);\n\n        if (existing?.raw) return existing;\n\n        if (this.pending.has(id)) {\n            return this.pending.get(id) ?? null;\n        }\n\n        const work = (async () => {\n            // Check if cancelled before starting work\n            if (this.cancelled.has(id)) {\n                this.cancelled.delete(id);\n                throw new Error(`Component discovery for \"${id}\" was cancelled`);\n            }\n\n            // Handle explicit importer registered via static registry\n            let entry = this.registry.get(id) ?? ({ id, raw: null } as Entry<TProps, TFrameworkComponent>);\n            if (entry.import) {\n                entry = await this.buildFromImporter(id, entry.import);\n\n                // Check if cancelled after async operation\n                if (this.cancelled.has(id)) {\n                    this.cancelled.delete(id);\n                    throw new Error(`Component discovery for \"${id}\" was cancelled`);\n                }\n\n                this.registry.set(id, entry);\n                return entry;\n            }\n\n            // No fallback scanning needed - components are pre-registered via static registry\n            return this.registry.get(id) ?? null;\n        })();\n\n        this.pending.set(id, work);\n        try {\n            const done = await work;\n            this.pending.delete(id);\n            return done;\n        } catch (error) {\n            this.pending.delete(id);\n            throw error;\n        }\n    }\n\n    private async buildFromImporter(\n        id: ComponentId,\n        importer: () => Promise<ComponentModule<TProps, TFrameworkComponent>>\n    ): Promise<Entry<TProps, TFrameworkComponent>> {\n        const mod = await importer();\n        return this.buildFromLoadedModule(id, importer, mod);\n    }\n\n    private buildFromLoadedModule(\n        id: ComponentId,\n        importer: () => Promise<ComponentModule<TProps, TFrameworkComponent>>,\n        mod: ComponentModule<TProps, TFrameworkComponent>\n    ): Entry<TProps, TFrameworkComponent> {\n        // Use adapter to create lazy component\n        const lazyComp = this.adapter.createLazyComponent(importer);\n\n        return {\n            id,\n            raw: null,\n            lazy: lazyComp,\n            import: importer,\n            fallback: mod.fallback,\n        };\n    }\n}\n"],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,208 @@
+import { a as ShopperSearch, i as ShopperProducts, n as ShopperBasketsV2, t as ShopperBasketsV1 } from "./types.js";
+import "openapi-fetch";
+
+//#region src/events/types.d.ts
+
+type BasketProductItem = ShopperBasketsV1.schemas['ProductItem'] | ShopperBasketsV2.schemas['ProductItem'];
+type Basket = ShopperBasketsV1.schemas['Basket'] | ShopperBasketsV2.schemas['Basket'];
+/**
+ * Interface for analytics user properties.
+ * This can be extended by external code via module augmentation without modifying the events module.
+ *
+ * @example
+ * ```typescript
+ * declare module '@storefront-next/runtime/events' {
+ *   interface AnalyticsUser {
+ *     customField: string;
+ *     preferences: Record<string, any>;
+ *     loyaltyTier?: 'bronze' | 'silver' | 'gold';
+ *   }
+ * }
+ * ```
+ */
+interface AnalyticsUser {
+  userType: 'registered' | 'guest';
+  usid?: string;
+  sid?: string;
+  encUserId?: string;
+  customerId?: string;
+  customerNo?: string;
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+}
+/**
+ * Placeholder type for future payload types.
+ * This allows the payload union to be extended in the future.
+ */
+interface PayloadTbd {}
+/**
+ * Union type for analytics event payloads.
+ * Currently includes AnalyticsUser, with PayloadTbd as a placeholder for future types.
+ */
+type AnalyticsPayload = AnalyticsUser | PayloadTbd;
+type BaseEvent = {
+  eventType: string;
+  payload: AnalyticsPayload;
+  deviceInfo?: string;
+};
+interface ViewPageEvent extends BaseEvent {
+  eventType: 'view_page';
+  path: string;
+}
+interface ViewProductEvent extends BaseEvent {
+  eventType: 'view_product';
+  product: ShopperProducts.schemas['Product'];
+}
+interface ViewSearchEvent extends BaseEvent {
+  eventType: 'view_search';
+  searchInputText: string;
+  searchResults: ShopperSearch.schemas['ProductSearchHit'][];
+  sort: string;
+  refinements: ShopperSearch.schemas['ProductSearchResult']['selectedRefinements'];
+}
+interface ViewCategoryEvent extends BaseEvent {
+  eventType: 'view_category';
+  category: ShopperProducts.schemas['Category'];
+  searchResults: ShopperSearch.schemas['ProductSearchHit'][];
+  sort: string;
+  refinements: ShopperSearch.schemas['ProductSearchResult']['selectedRefinements'];
+}
+interface ViewRecommenderEvent extends BaseEvent {
+  eventType: 'view_recommender';
+  recommenderId: string;
+  recommenderName: string;
+  products: ShopperSearch.schemas['ProductSearchHit'][];
+}
+interface ClickProductInCategoryEvent extends BaseEvent {
+  eventType: 'click_product_in_category';
+  category: ShopperProducts.schemas['Category'];
+  product: ShopperSearch.schemas['ProductSearchHit'];
+}
+interface ClickProductInSearchEvent extends BaseEvent {
+  eventType: 'click_product_in_search';
+  searchInputText: string;
+  product: ShopperSearch.schemas['ProductSearchHit'];
+}
+interface ClickProductInRecommenderEvent extends BaseEvent {
+  eventType: 'click_product_in_recommender';
+  recommenderId: string;
+  recommenderName: string;
+  product: ShopperSearch.schemas['ProductSearchHit'];
+}
+interface CartItemAddEvent extends BaseEvent {
+  eventType: 'cart_item_add';
+  cartItems: Array<BasketProductItem>;
+}
+interface CheckoutStartEvent extends BaseEvent {
+  eventType: 'checkout_start';
+  basket: Basket;
+}
+interface CheckoutStepEvent extends BaseEvent {
+  eventType: 'checkout_step';
+  stepName: string;
+  stepNumber: number;
+  basket: Basket;
+}
+interface ViewSearchSuggestionEvent extends BaseEvent {
+  eventType: 'view_search_suggestion';
+  searchInputText: string;
+  suggestions: Array<string>;
+}
+interface ClickSearchSuggestionEvent extends BaseEvent {
+  eventType: 'click_search_suggestion';
+  searchInputText: string;
+  suggestion: string;
+}
+/**
+ * Interface for custom analytics events.
+ * Extend this interface via module augmentation.
+ *
+ * @example
+ * ```typescript
+ * declare module '@storefront-next/runtime/events' {
+ *   interface AnalyticsEventExtensions {
+ *     CustomEvent: BaseEvent & { eventType: 'custom'; data: string };
+ *   }
+ * }
+ * ```
+ */
+interface AnalyticsEventExtensions {}
+/**
+ * Union type for all analytics events.
+ *
+ * Custom types can be added by extending the AnalyticsEventExtensions interface.
+ */
+type AnalyticsEvent = ViewPageEvent | ViewProductEvent | ViewSearchEvent | ViewCategoryEvent | ViewRecommenderEvent | ClickProductInCategoryEvent | ClickProductInSearchEvent | ClickProductInRecommenderEvent | CartItemAddEvent | CheckoutStartEvent | CheckoutStepEvent | ViewSearchSuggestionEvent | ClickSearchSuggestionEvent | AnalyticsEventExtensions[keyof AnalyticsEventExtensions];
+/**
+ * Helper type for mapping event_type to the corresponding event type.
+ */
+type EventTypeMap = { [K in AnalyticsEvent as K['eventType']]: K };
+/**
+ * Helper type for extracting event payload data for a given event type.
+ */
+type EventPayload<T extends AnalyticsEvent['eventType']> = Omit<EventTypeMap[T], 'eventType' | 'payload'> & {
+  payload: AnalyticsPayload;
+};
+/**
+ * Minimal interface for engagement adapters that can send analytics events.
+ * Engagemet Adapters must implement this interface to work with the event mediator.
+ */
+interface EventAdapter {
+  name: string;
+  sendEvent?: (event: AnalyticsEvent) => Promise<unknown>;
+}
+/**
+ * Generic event mediator interface for tracking events.
+ * This can be used for analytics, telemetry, or any other event tracking system.
+ */
+type EventMediator = {
+  track: (event: AnalyticsEvent) => void;
+};
+//#endregion
+//#region src/events/events.d.ts
+/**
+ * Type-safe event creation function
+ *
+ * This generic function allows creating any event type under AnalyticsEvent
+ * with full type safety. The event type is inferred from the string literal
+ * passed as the first parameter, and TypeScript will enforce the correct
+ * data properties for that specific event type.
+ *
+ * @example
+ * ```typescript
+ * const viewPageEvent = createEvent('view_page', { path: '/products', payload });
+ * const viewProductEvent = createEvent('view_product', { product, payload });
+ * ```
+ */
+declare function createEvent<T extends AnalyticsEvent['eventType']>(eventType: T, data: EventPayload<T>): EventTypeMap[T];
+/**
+ * Send a view page event to the event mediator
+ *
+ * This wrapper function is used in the automated page view event tracking client middleware.
+ * This function exists to support build-time checks and type safety.
+ *
+ * @param event - The view page event to send
+ * @param eventMediator - The event mediator to send the event to
+ */
+declare function sendViewPageEvent(event: ViewPageEvent, eventMediator: EventMediator): void;
+//#endregion
+//#region src/events/mediator.d.ts
+/**
+ * Get the event mediator singleton instance
+ *
+ * Returns the singleton EventMediator instance, creating it if it doesn't exist.
+ *
+ * @param getAdapters - Function that returns the current array of engagement adapters.
+ * @returns EventMediator instance (singleton) or undefined if not on client side
+ */
+declare function getEventMediator(getAdapters: () => EventAdapter[]): EventMediator | undefined;
+/**
+ * Reset the event mediator singleton (for testing only)
+ *
+ * This function clears the singleton instance, allowing tests to create a fresh mediator.
+ */
+declare function resetEventMediator(): void;
+//#endregion
+export { AnalyticsEvent, AnalyticsEventExtensions, AnalyticsPayload, AnalyticsUser, BaseEvent, CartItemAddEvent, CheckoutStartEvent, CheckoutStepEvent, ClickProductInCategoryEvent, ClickProductInRecommenderEvent, ClickProductInSearchEvent, ClickSearchSuggestionEvent, EventAdapter, EventMediator, EventPayload, EventTypeMap, PayloadTbd, ViewCategoryEvent, ViewPageEvent, ViewProductEvent, ViewRecommenderEvent, ViewSearchEvent, ViewSearchSuggestionEvent, createEvent, getEventMediator, resetEventMediator, sendViewPageEvent };
+//# sourceMappingURL=events.d.ts.map