@salesforce/storefront-next-runtime 0.3.1 → 0.4.0-alpha.1

package/dist/design-react-core.d.ts

@@ -3,7 +3,7 @@ import { n as ComponentModule, o as FrameworkAdapter } from "./types3.js";
 import { g as IsomorphicConfiguration } from "./index.js";
 import { i as RegionDecoratorProps, t as ComponentDecoratorProps } from "./component.types.js";
 import React$1 from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime1 from "react/jsx-runtime";
 
 //#region src/design/react/core/PageDesignerProvider.d.ts
 type PageDesignerContextType = {
@@ -49,7 +49,7 @@ declare function PageDesignerPageMetadataProvider({
   children
 }: React.PropsWithChildren<{
   page: ShopperExperience.schemas['Page'];
-}>): react_jsx_runtime0.JSX.Element;
+}>): react_jsx_runtime1.JSX.Element;
 //#endregion
 //#region src/design/react/core/RegionContext.d.ts
 interface RegionContextType {

package/dist/events.d.ts

@@ -114,6 +114,11 @@ interface ClickSearchSuggestionEvent extends BaseEvent {
   searchInputText: string;
   suggestion: string;
 }
+/** Shopper opened agentic commerce (e.g. header or search assistant entry point). */
+interface CommerceAgentEngagementEvent extends BaseEvent {
+  eventType: 'commerce_agent_engagement';
+  surface: 'header' | 'search';
+}
 /**
  * Interface for custom analytics events.
  * Extend this interface via module augmentation.
@@ -133,7 +138,7 @@ interface AnalyticsEventExtensions {}
  *
  * 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];
+type AnalyticsEvent = ViewPageEvent | ViewProductEvent | ViewSearchEvent | ViewCategoryEvent | ViewRecommenderEvent | ClickProductInCategoryEvent | ClickProductInSearchEvent | ClickProductInRecommenderEvent | CartItemAddEvent | CheckoutStartEvent | CheckoutStepEvent | ViewSearchSuggestionEvent | ClickSearchSuggestionEvent | CommerceAgentEngagementEvent | AnalyticsEventExtensions[keyof AnalyticsEventExtensions];
 /**
  * Helper type for mapping event_type to the corresponding event type.
  */
@@ -149,20 +154,43 @@ type EventSiteInfo = {
   siteId: string;
   localeId: string;
 };
+/**
+ * Consent categories for granular tracking control.
+ *
+ * Adapters declare which consent category they require via configuration.
+ * The event system passes the shopper's granted categories (consentPreferences) to each adapter,
+ * allowing per-adapter consent decisions.
+ *
+ * This is typed as `string` so projects can define categories that match their
+ * consent management platform. Common conventions:
+ *
+ * - `'necessary'` — Essential cookies/tracking required for site functionality
+ * - `'analytics'` — Usage analytics and performance measurement
+ * - `'marketing'` — Marketing, advertising, and retargeting
+ * - `'personalization'` — Product recommendations and personalized experiences
+ */
+type ConsentCategory = string;
+/**
+ * The set of consent categories a shopper has granted.
+ *
+ * Each adapter checks whether its required `consentCategory` is included
+ * in the preferences before sending events.
+ */
+type ConsentPreferences = ConsentCategory[];
 /**
  * Minimal interface for engagement adapters that can send analytics events.
- * Engagemet Adapters must implement this interface to work with the event mediator.
+ * Engagement Adapters must implement this interface to work with the event mediator.
  */
 interface EventAdapter {
   name: string;
-  sendEvent?: (event: AnalyticsEvent, siteInfo?: EventSiteInfo) => Promise<unknown>;
+  sendEvent?: (event: AnalyticsEvent, siteInfo?: EventSiteInfo, consentPreferences?: ConsentPreferences) => 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, siteInfo?: EventSiteInfo) => void;
+  track: (event: AnalyticsEvent, siteInfo?: EventSiteInfo, consentPreferences?: ConsentPreferences) => void;
 };
 //#endregion
 //#region src/events/events.d.ts
@@ -190,7 +218,7 @@ declare function createEvent<T extends AnalyticsEvent['eventType']>(eventType: T
  * @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, siteInfo?: EventSiteInfo): void;
+declare function sendViewPageEvent(event: ViewPageEvent, eventMediator: EventMediator, siteInfo?: EventSiteInfo, consentPreferences?: ConsentPreferences): void;
 //#endregion
 //#region src/events/mediator.d.ts
 /**
@@ -209,5 +237,5 @@ declare function getEventMediator(getAdapters: () => EventAdapter[]): EventMedia
  */
 declare function resetEventMediator(): void;
 //#endregion
-export { AnalyticsEvent, AnalyticsEventExtensions, AnalyticsPayload, AnalyticsUser, BaseEvent, CartItemAddEvent, CheckoutStartEvent, CheckoutStepEvent, ClickProductInCategoryEvent, ClickProductInRecommenderEvent, ClickProductInSearchEvent, ClickSearchSuggestionEvent, EventAdapter, EventMediator, EventPayload, EventSiteInfo, EventTypeMap, PayloadTbd, ViewCategoryEvent, ViewPageEvent, ViewProductEvent, ViewRecommenderEvent, ViewSearchEvent, ViewSearchSuggestionEvent, createEvent, getEventMediator, resetEventMediator, sendViewPageEvent };
+export { AnalyticsEvent, AnalyticsEventExtensions, AnalyticsPayload, AnalyticsUser, BaseEvent, CartItemAddEvent, CheckoutStartEvent, CheckoutStepEvent, ClickProductInCategoryEvent, ClickProductInRecommenderEvent, ClickProductInSearchEvent, ClickSearchSuggestionEvent, CommerceAgentEngagementEvent, ConsentCategory, ConsentPreferences, EventAdapter, EventMediator, EventPayload, EventSiteInfo, EventTypeMap, PayloadTbd, ViewCategoryEvent, ViewPageEvent, ViewProductEvent, ViewRecommenderEvent, ViewSearchEvent, ViewSearchSuggestionEvent, createEvent, getEventMediator, resetEventMediator, sendViewPageEvent };
 //# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","names":[],"sources":["../src/events/types.ts","../src/events/events.ts","../src/events/mediator.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"events.d.ts","names":[],"sources":["../src/events/types.ts","../src/events/events.ts","../src/events/mediator.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/events.js

@@ -28,8 +28,8 @@ function createEvent(eventType, data) {
 * @param event - The view page event to send
 * @param eventMediator - The event mediator to send the event to
 */
-function sendViewPageEvent(event, eventMediator, siteInfo) {
-	eventMediator.track(event, siteInfo);
+function sendViewPageEvent(event, eventMediator, siteInfo, consentPreferences) {
+	eventMediator.track(event, siteInfo, consentPreferences);
 }
 
 //#endregion
@@ -48,8 +48,8 @@ let mediatorInstance;
 * @returns EventMediator instance
 */
 function createEventMediator(getAdapters) {
-	return { track: (event, siteInfo) => {
-		processEventWithAdapters(event, getAdapters, siteInfo).catch((error) => {
+	return { track: (event, siteInfo, consentPreferences) => {
+		processEventWithAdapters(event, getAdapters, siteInfo, consentPreferences).catch((error) => {
 			console.error("Analytics tracking failed:", error);
 		});
 	} };
@@ -82,7 +82,7 @@ function resetEventMediator() {
 * @param event - The analytics event to process
 * @param getAdapters - Function that returns the current array of event adapters
 */
-async function processEventWithAdapters(event, getAdapters, siteInfo) {
+async function processEventWithAdapters(event, getAdapters, siteInfo, consentPreferences) {
 	const eventAdapters = getAdapters();
 	if (eventAdapters.length === 0) {
 		console.warn(`There are no active adapters to send the event to`);
@@ -90,7 +90,7 @@ async function processEventWithAdapters(event, getAdapters, siteInfo) {
 	}
 	const promises = eventAdapters.map(async (adapter) => {
 		try {
-			if (typeof adapter.sendEvent === "function") await adapter.sendEvent(event, siteInfo);
+			if (typeof adapter.sendEvent === "function") await adapter.sendEvent(event, siteInfo, consentPreferences);
 			else console.warn(`Adapter ${adapter.name} does not implement sendEvent`);
 		} catch (error) {
 			console.error(`Failed to send event to ${adapter.name}:`, error);

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":["mediatorInstance: EventMediator | undefined"],"sources":["../src/events/events.ts","../src/events/mediator.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 { AnalyticsEvent, EventMediator, EventPayload, EventSiteInfo, EventTypeMap, ViewPageEvent } from './types';\n\n/**\n * Type-safe event creation function\n *\n * This generic function allows creating any event type under AnalyticsEvent\n * with full type safety. The event type is inferred from the string literal\n * passed as the first parameter, and TypeScript will enforce the correct\n * data properties for that specific event type.\n *\n * @example\n * ```typescript\n * const viewPageEvent = createEvent('view_page', { path: '/products', payload });\n * const viewProductEvent = createEvent('view_product', { product, payload });\n * ```\n */\nexport function createEvent<T extends AnalyticsEvent['eventType']>(\n    eventType: T,\n    data: EventPayload<T>\n): EventTypeMap[T] {\n    return {\n        eventType,\n        ...data,\n    } as EventTypeMap[T];\n}\n\n/**\n * Send a view page event to the event mediator\n *\n * This wrapper function is used in the automated page view event tracking client middleware.\n * This function exists to support build-time checks and type safety.\n *\n * @param event - The view page event to send\n * @param eventMediator - The event mediator to send the event to\n */\nexport function sendViewPageEvent(event: ViewPageEvent, eventMediator: EventMediator, siteInfo?: EventSiteInfo): void {\n    eventMediator.track(event, siteInfo);\n}\n","/**\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 { EventMediator, AnalyticsEvent, EventAdapter, EventSiteInfo } from './types';\n\n// Module-level storage for the event mediator singleton\n// This ensures a single mediator instance across all usages\nlet mediatorInstance: EventMediator | undefined;\n\n/**\n * Create an event mediator instance\n *\n * Creates a new EventMediator that processes events through the provided adapters.\n * The mediator uses the getAdapters function on each track() invocation to ensure\n * it always uses the latest adapters from the adapter registry.\n *\n * @param getAdapters - Function that returns the current array of engagement adapters.\n *                      This function is called on each track() invocation to ensure\n *                      the mediator always uses the latest adapters from the adapter registry.\n * @returns EventMediator instance\n */\nfunction createEventMediator(getAdapters: () => EventAdapter[]): EventMediator {\n    return {\n        track: (event: AnalyticsEvent, siteInfo?: EventSiteInfo) => {\n            processEventWithAdapters(event, getAdapters, siteInfo).catch((error) => {\n                // eslint-disable-next-line no-console\n                console.error('Analytics tracking failed:', error);\n            });\n        },\n    };\n}\n\n/**\n * Get the event mediator singleton instance\n *\n * Returns the singleton EventMediator instance, creating it if it doesn't exist.\n *\n * @param getAdapters - Function that returns the current array of engagement adapters.\n * @returns EventMediator instance (singleton) or undefined if not on client side\n */\nexport function getEventMediator(getAdapters: () => EventAdapter[]): EventMediator | undefined {\n    // If mediator already exists, return it\n    if (mediatorInstance) {\n        return mediatorInstance;\n    }\n\n    // Only create on client side\n    if (typeof window === 'undefined') {\n        return undefined;\n    }\n\n    // Create the event mediator singleton\n    mediatorInstance = createEventMediator(getAdapters);\n    return mediatorInstance;\n}\n\n/**\n * Reset the event mediator singleton (for testing only)\n *\n * This function clears the singleton instance, allowing tests to create a fresh mediator.\n */\nexport function resetEventMediator(): void {\n    mediatorInstance = undefined;\n}\n\n/**\n * Process an event with all registered adapters\n *\n * @param event - The analytics event to process\n * @param getAdapters - Function that returns the current array of event adapters\n */\nasync function processEventWithAdapters(\n    event: AnalyticsEvent,\n    getAdapters: () => EventAdapter[],\n    siteInfo?: EventSiteInfo\n): Promise<void> {\n    // Get the current array of event adapters\n    const eventAdapters = getAdapters();\n    if (eventAdapters.length === 0) {\n        // eslint-disable-next-line no-console\n        console.warn(`There are no active adapters to send the event to`);\n        return;\n    }\n\n    // Send event to all registered adapters that implement sendEvent in parallel\n    const promises = eventAdapters.map(async (adapter) => {\n        try {\n            if (typeof adapter.sendEvent === 'function') {\n                await adapter.sendEvent(event, siteInfo);\n            } else {\n                // eslint-disable-next-line no-console\n                console.warn(`Adapter ${adapter.name} does not implement sendEvent`);\n            }\n        } catch (error) {\n            // eslint-disable-next-line no-console\n            console.error(`Failed to send event to ${adapter.name}:`, error);\n        }\n    });\n\n    await Promise.allSettled(promises);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgCA,SAAgB,YACZ,WACA,MACe;AACf,QAAO;EACH;EACA,GAAG;EACN;;;;;;;;;;;AAYL,SAAgB,kBAAkB,OAAsB,eAA8B,UAAgC;AAClH,eAAc,MAAM,OAAO,SAAS;;;;;AChCxC,IAAIA;;;;;;;;;;;;;AAcJ,SAAS,oBAAoB,aAAkD;AAC3E,QAAO,EACH,QAAQ,OAAuB,aAA6B;AACxD,2BAAyB,OAAO,aAAa,SAAS,CAAC,OAAO,UAAU;AAEpE,WAAQ,MAAM,8BAA8B,MAAM;IACpD;IAET;;;;;;;;;;AAWL,SAAgB,iBAAiB,aAA8D;AAE3F,KAAI,iBACA,QAAO;AAIX,KAAI,OAAO,WAAW,YAClB;AAIJ,oBAAmB,oBAAoB,YAAY;AACnD,QAAO;;;;;;;AAQX,SAAgB,qBAA2B;AACvC,oBAAmB;;;;;;;;AASvB,eAAe,yBACX,OACA,aACA,UACa;CAEb,MAAM,gBAAgB,aAAa;AACnC,KAAI,cAAc,WAAW,GAAG;AAE5B,UAAQ,KAAK,oDAAoD;AACjE;;CAIJ,MAAM,WAAW,cAAc,IAAI,OAAO,YAAY;AAClD,MAAI;AACA,OAAI,OAAO,QAAQ,cAAc,WAC7B,OAAM,QAAQ,UAAU,OAAO,SAAS;OAGxC,SAAQ,KAAK,WAAW,QAAQ,KAAK,+BAA+B;WAEnE,OAAO;AAEZ,WAAQ,MAAM,2BAA2B,QAAQ,KAAK,IAAI,MAAM;;GAEtE;AAEF,OAAM,QAAQ,WAAW,SAAS"}
+{"version":3,"file":"events.js","names":["mediatorInstance: EventMediator | undefined"],"sources":["../src/events/events.ts","../src/events/mediator.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    AnalyticsEvent,\n    ConsentPreferences,\n    EventMediator,\n    EventPayload,\n    EventSiteInfo,\n    EventTypeMap,\n    ViewPageEvent,\n} from './types';\n\n/**\n * Type-safe event creation function\n *\n * This generic function allows creating any event type under AnalyticsEvent\n * with full type safety. The event type is inferred from the string literal\n * passed as the first parameter, and TypeScript will enforce the correct\n * data properties for that specific event type.\n *\n * @example\n * ```typescript\n * const viewPageEvent = createEvent('view_page', { path: '/products', payload });\n * const viewProductEvent = createEvent('view_product', { product, payload });\n * ```\n */\nexport function createEvent<T extends AnalyticsEvent['eventType']>(\n    eventType: T,\n    data: EventPayload<T>\n): EventTypeMap[T] {\n    return {\n        eventType,\n        ...data,\n    } as EventTypeMap[T];\n}\n\n/**\n * Send a view page event to the event mediator\n *\n * This wrapper function is used in the automated page view event tracking client middleware.\n * This function exists to support build-time checks and type safety.\n *\n * @param event - The view page event to send\n * @param eventMediator - The event mediator to send the event to\n */\nexport function sendViewPageEvent(\n    event: ViewPageEvent,\n    eventMediator: EventMediator,\n    siteInfo?: EventSiteInfo,\n    consentPreferences?: ConsentPreferences\n): void {\n    eventMediator.track(event, siteInfo, consentPreferences);\n}\n","/**\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 { EventMediator, AnalyticsEvent, EventAdapter, EventSiteInfo, ConsentPreferences } from './types';\n\n// Module-level storage for the event mediator singleton\n// This ensures a single mediator instance across all usages\nlet mediatorInstance: EventMediator | undefined;\n\n/**\n * Create an event mediator instance\n *\n * Creates a new EventMediator that processes events through the provided adapters.\n * The mediator uses the getAdapters function on each track() invocation to ensure\n * it always uses the latest adapters from the adapter registry.\n *\n * @param getAdapters - Function that returns the current array of engagement adapters.\n *                      This function is called on each track() invocation to ensure\n *                      the mediator always uses the latest adapters from the adapter registry.\n * @returns EventMediator instance\n */\nfunction createEventMediator(getAdapters: () => EventAdapter[]): EventMediator {\n    return {\n        track: (event: AnalyticsEvent, siteInfo?: EventSiteInfo, consentPreferences?: ConsentPreferences) => {\n            processEventWithAdapters(event, getAdapters, siteInfo, consentPreferences).catch((error) => {\n                // eslint-disable-next-line no-console\n                console.error('Analytics tracking failed:', error);\n            });\n        },\n    };\n}\n\n/**\n * Get the event mediator singleton instance\n *\n * Returns the singleton EventMediator instance, creating it if it doesn't exist.\n *\n * @param getAdapters - Function that returns the current array of engagement adapters.\n * @returns EventMediator instance (singleton) or undefined if not on client side\n */\nexport function getEventMediator(getAdapters: () => EventAdapter[]): EventMediator | undefined {\n    // If mediator already exists, return it\n    if (mediatorInstance) {\n        return mediatorInstance;\n    }\n\n    // Only create on client side\n    if (typeof window === 'undefined') {\n        return undefined;\n    }\n\n    // Create the event mediator singleton\n    mediatorInstance = createEventMediator(getAdapters);\n    return mediatorInstance;\n}\n\n/**\n * Reset the event mediator singleton (for testing only)\n *\n * This function clears the singleton instance, allowing tests to create a fresh mediator.\n */\nexport function resetEventMediator(): void {\n    mediatorInstance = undefined;\n}\n\n/**\n * Process an event with all registered adapters\n *\n * @param event - The analytics event to process\n * @param getAdapters - Function that returns the current array of event adapters\n */\nasync function processEventWithAdapters(\n    event: AnalyticsEvent,\n    getAdapters: () => EventAdapter[],\n    siteInfo?: EventSiteInfo,\n    consentPreferences?: ConsentPreferences\n): Promise<void> {\n    // Get the current array of event adapters\n    const eventAdapters = getAdapters();\n    if (eventAdapters.length === 0) {\n        // eslint-disable-next-line no-console\n        console.warn(`There are no active adapters to send the event to`);\n        return;\n    }\n\n    // Send event to all registered adapters that implement sendEvent in parallel\n    const promises = eventAdapters.map(async (adapter) => {\n        try {\n            if (typeof adapter.sendEvent === 'function') {\n                await adapter.sendEvent(event, siteInfo, consentPreferences);\n            } else {\n                // eslint-disable-next-line no-console\n                console.warn(`Adapter ${adapter.name} does not implement sendEvent`);\n            }\n        } catch (error) {\n            // eslint-disable-next-line no-console\n            console.error(`Failed to send event to ${adapter.name}:`, error);\n        }\n    });\n\n    await Promise.allSettled(promises);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwCA,SAAgB,YACZ,WACA,MACe;AACf,QAAO;EACH;EACA,GAAG;EACN;;;;;;;;;;;AAYL,SAAgB,kBACZ,OACA,eACA,UACA,oBACI;AACJ,eAAc,MAAM,OAAO,UAAU,mBAAmB;;;;;AC7C5D,IAAIA;;;;;;;;;;;;;AAcJ,SAAS,oBAAoB,aAAkD;AAC3E,QAAO,EACH,QAAQ,OAAuB,UAA0B,uBAA4C;AACjG,2BAAyB,OAAO,aAAa,UAAU,mBAAmB,CAAC,OAAO,UAAU;AAExF,WAAQ,MAAM,8BAA8B,MAAM;IACpD;IAET;;;;;;;;;;AAWL,SAAgB,iBAAiB,aAA8D;AAE3F,KAAI,iBACA,QAAO;AAIX,KAAI,OAAO,WAAW,YAClB;AAIJ,oBAAmB,oBAAoB,YAAY;AACnD,QAAO;;;;;;;AAQX,SAAgB,qBAA2B;AACvC,oBAAmB;;;;;;;;AASvB,eAAe,yBACX,OACA,aACA,UACA,oBACa;CAEb,MAAM,gBAAgB,aAAa;AACnC,KAAI,cAAc,WAAW,GAAG;AAE5B,UAAQ,KAAK,oDAAoD;AACjE;;CAIJ,MAAM,WAAW,cAAc,IAAI,OAAO,YAAY;AAClD,MAAI;AACA,OAAI,OAAO,QAAQ,cAAc,WAC7B,OAAM,QAAQ,UAAU,OAAO,UAAU,mBAAmB;OAG5D,SAAQ,KAAK,WAAW,QAAQ,KAAK,+BAA+B;WAEnE,OAAO;AAEZ,WAAQ,MAAM,2BAA2B,QAAQ,KAAK,IAAI,MAAM;;GAEtE;AAEF,OAAM,QAAQ,WAAW,SAAS"}

package/dist/gcp-preferences.d.ts

@@ -0,0 +1,52 @@
+import * as react_router0 from "react-router";
+import { RouterContextProvider } from "react-router";
+
+//#region src/data-store/middleware/gcp-preferences.d.ts
+
+/**
+ * OOTB Google Cloud Platform preferences sourced from the MRT data store.
+ *
+ * Additional fields (e.g. `projectId`, `region`) may be added here as the
+ * ECOM MRT sync job expands the `gcp` entry. Consumers should read the
+ * object as a whole via `getGcpPreferences`, or use a specific convenience
+ * getter like `getGcpApiKey` for a single field.
+ */
+type GcpPreferences = {
+  apiKey: string;
+};
+declare const DEFAULT_GCP_PREFERENCES_KEY = "gcp";
+declare const gcpPreferencesContext: react_router0.RouterContext<GcpPreferences | null>;
+/**
+ * Read the GCP (Google Cloud Platform) preferences object from router context.
+ *
+ * The preferences are sourced from the MRT data store entry `gcp`, which is
+ * populated only for storefronts connecting to production ECOM instances.
+ * In non-production environments, or when the entry is missing, returns an
+ * object whose fields are all empty/default.
+ *
+ * @param context - Router context provider
+ * @returns GCP preferences object; fields are empty/default when the entry is unavailable
+ */
+declare function getGcpPreferences(context: Readonly<RouterContextProvider>): GcpPreferences;
+/**
+ * Convenience getter for the Google Cloud API key alone.
+ *
+ * Equivalent to `getGcpPreferences(context).apiKey`.
+ *
+ * @param context - Router context provider
+ * @returns The GCP API key, or an empty string when unavailable
+ */
+declare function getGcpApiKey(context: Readonly<RouterContextProvider>): string;
+/**
+ * Middleware that reads the OOTB GCP preferences from the MRT data store and
+ * stores them in the router context. The entry shape is `{ "api-key": string, ... }`
+ * under data store key `gcp`. Missing/invalid fields coerce to empty/default values.
+ *
+ * Only available for storefronts connecting to production ECOM instances.
+ * Must run before any loader/middleware that reads `getGcpPreferences(context)`
+ * or `getGcpApiKey(context)`.
+ */
+declare const gcpPreferencesMiddleware: react_router0.MiddlewareFunction<Response>;
+//#endregion
+export { getGcpApiKey as a, gcpPreferencesMiddleware as i, GcpPreferences as n, getGcpPreferences as o, gcpPreferencesContext as r, DEFAULT_GCP_PREFERENCES_KEY as t };
+//# sourceMappingURL=gcp-preferences.d.ts.map

package/dist/gcp-preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp-preferences.d.ts","names":[],"sources":["../src/data-store/middleware/gcp-preferences.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;KA2BY,cAAA;;;cAIC,2BAAA;cAQA,uBAAqB,aAAA,CAAA,cAAA;;;;;;;;;;;;iBAalB,iBAAA,UAA2B,SAAS,yBAAyB;;;;;;;;;iBAoB7D,YAAA,UAAsB,SAAS;;;;;;;;;;cAalC,0BAAwB,aAAA,CAAA,mBAAA"}

package/dist/gcp-preferences.js

@@ -0,0 +1,61 @@
+import { n as createDataStoreMiddleware, t as createDataStoreContext } from "./utils.js";
+
+//#region src/data-store/middleware/gcp-preferences.ts
+const DEFAULT_GCP_PREFERENCES_KEY = "gcp";
+/**
+* Map keys inside the `gcp` data store entry. The ECOM MRT sync job writes
+* to these exact keys; keep in sync with the sync job contract.
+*/
+const API_KEY_MAP_KEY = "api-key";
+const gcpPreferencesContext = createDataStoreContext();
+/**
+* Read the GCP (Google Cloud Platform) preferences object from router context.
+*
+* The preferences are sourced from the MRT data store entry `gcp`, which is
+* populated only for storefronts connecting to production ECOM instances.
+* In non-production environments, or when the entry is missing, returns an
+* object whose fields are all empty/default.
+*
+* @param context - Router context provider
+* @returns GCP preferences object; fields are empty/default when the entry is unavailable
+*/
+function getGcpPreferences(context) {
+	const data = context.get(gcpPreferencesContext);
+	if (data === null) {
+		console.warn("GCP preferences context not found. Ensure gcpPreferencesMiddleware runs before loaders, or expect empty values in environments without the MRT data store entry.");
+		return { apiKey: "" };
+	}
+	return data;
+}
+/**
+* Convenience getter for the Google Cloud API key alone.
+*
+* Equivalent to `getGcpPreferences(context).apiKey`.
+*
+* @param context - Router context provider
+* @returns The GCP API key, or an empty string when unavailable
+*/
+function getGcpApiKey(context) {
+	return getGcpPreferences(context).apiKey;
+}
+/**
+* Middleware that reads the OOTB GCP preferences from the MRT data store and
+* stores them in the router context. The entry shape is `{ "api-key": string, ... }`
+* under data store key `gcp`. Missing/invalid fields coerce to empty/default values.
+*
+* Only available for storefronts connecting to production ECOM instances.
+* Must run before any loader/middleware that reads `getGcpPreferences(context)`
+* or `getGcpApiKey(context)`.
+*/
+const gcpPreferencesMiddleware = createDataStoreMiddleware({
+	entryKey: DEFAULT_GCP_PREFERENCES_KEY,
+	context: gcpPreferencesContext,
+	transform: (value) => {
+		const rawKey = value[API_KEY_MAP_KEY];
+		return { apiKey: typeof rawKey === "string" ? rawKey : "" };
+	}
+});
+
+//#endregion
+export { getGcpPreferences as a, getGcpApiKey as i, gcpPreferencesContext as n, gcpPreferencesMiddleware as r, DEFAULT_GCP_PREFERENCES_KEY as t };
+//# sourceMappingURL=gcp-preferences.js.map

package/dist/gcp-preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp-preferences.js","names":[],"sources":["../src/data-store/middleware/gcp-preferences.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 { RouterContextProvider } from 'react-router';\nimport { createDataStoreContext, createDataStoreMiddleware } from '../utils';\n\n/**\n * OOTB Google Cloud Platform preferences sourced from the MRT data store.\n *\n * Additional fields (e.g. `projectId`, `region`) may be added here as the\n * ECOM MRT sync job expands the `gcp` entry. Consumers should read the\n * object as a whole via `getGcpPreferences`, or use a specific convenience\n * getter like `getGcpApiKey` for a single field.\n */\nexport type GcpPreferences = {\n    apiKey: string;\n};\n\nexport const DEFAULT_GCP_PREFERENCES_KEY = 'gcp';\n\n/**\n * Map keys inside the `gcp` data store entry. The ECOM MRT sync job writes\n * to these exact keys; keep in sync with the sync job contract.\n */\nconst API_KEY_MAP_KEY = 'api-key';\n\nexport const gcpPreferencesContext = createDataStoreContext<GcpPreferences>();\n\n/**\n * Read the GCP (Google Cloud Platform) preferences object from router context.\n *\n * The preferences are sourced from the MRT data store entry `gcp`, which is\n * populated only for storefronts connecting to production ECOM instances.\n * In non-production environments, or when the entry is missing, returns an\n * object whose fields are all empty/default.\n *\n * @param context - Router context provider\n * @returns GCP preferences object; fields are empty/default when the entry is unavailable\n */\nexport function getGcpPreferences(context: Readonly<RouterContextProvider>): GcpPreferences {\n    const data = context.get(gcpPreferencesContext);\n    if (data === null) {\n        // eslint-disable-next-line no-console\n        console.warn(\n            'GCP preferences context not found. Ensure gcpPreferencesMiddleware runs before loaders, or expect empty values in environments without the MRT data store entry.'\n        );\n        return { apiKey: '' };\n    }\n    return data;\n}\n\n/**\n * Convenience getter for the Google Cloud API key alone.\n *\n * Equivalent to `getGcpPreferences(context).apiKey`.\n *\n * @param context - Router context provider\n * @returns The GCP API key, or an empty string when unavailable\n */\nexport function getGcpApiKey(context: Readonly<RouterContextProvider>): string {\n    return getGcpPreferences(context).apiKey;\n}\n\n/**\n * Middleware that reads the OOTB GCP preferences from the MRT data store and\n * stores them in the router context. The entry shape is `{ \"api-key\": string, ... }`\n * under data store key `gcp`. Missing/invalid fields coerce to empty/default values.\n *\n * Only available for storefronts connecting to production ECOM instances.\n * Must run before any loader/middleware that reads `getGcpPreferences(context)`\n * or `getGcpApiKey(context)`.\n */\nexport const gcpPreferencesMiddleware = createDataStoreMiddleware<GcpPreferences>({\n    entryKey: DEFAULT_GCP_PREFERENCES_KEY,\n    context: gcpPreferencesContext,\n    transform: (value) => {\n        const rawKey = value[API_KEY_MAP_KEY];\n        return { apiKey: typeof rawKey === 'string' ? rawKey : '' };\n    },\n});\n"],"mappings":";;;AA+BA,MAAa,8BAA8B;;;;;AAM3C,MAAM,kBAAkB;AAExB,MAAa,wBAAwB,wBAAwC;;;;;;;;;;;;AAa7E,SAAgB,kBAAkB,SAA0D;CACxF,MAAM,OAAO,QAAQ,IAAI,sBAAsB;AAC/C,KAAI,SAAS,MAAM;AAEf,UAAQ,KACJ,mKACH;AACD,SAAO,EAAE,QAAQ,IAAI;;AAEzB,QAAO;;;;;;;;;;AAWX,SAAgB,aAAa,SAAkD;AAC3E,QAAO,kBAAkB,QAAQ,CAAC;;;;;;;;;;;AAYtC,MAAa,2BAA2B,0BAA0C;CAC9E,UAAU;CACV,SAAS;CACT,YAAY,UAAU;EAClB,MAAM,SAAS,MAAM;AACrB,SAAO,EAAE,QAAQ,OAAO,WAAW,WAAW,SAAS,IAAI;;CAElE,CAAC"}

package/dist/i18n-client.d.ts

@@ -0,0 +1,38 @@
+import { ResourceLanguage, i18n } from "i18next";
+
+//#region src/i18n/types.d.ts
+
+/**
+ * Callback that dynamically imports all translations for a given language.
+ * Must be defined in template code so Vite can resolve the `import()` path at build time
+ * and split translations into per-language chunks.
+ *
+ * @example
+ * const loadLocale: LocaleLoader = (language) => import(`@/locales/${language}/index.ts`);
+ */
+type LocaleLoader = (language: string) => Promise<{
+  default: ResourceLanguage;
+}>;
+//#endregion
+//#region src/i18n/client.d.ts
+
+/**
+ * Initialize i18next on the client side.
+ * Pass a `loadLocale` callback containing the dynamic import so Vite can resolve it
+ * at build time relative to the template's source tree.
+ *
+ * @example
+ * // In root.tsx — Vite resolves the import() relative to this file
+ * initI18next({
+ *     language: document.documentElement.lang || undefined,
+ *     loadLocale: (language) => import(`@/locales/${language}/index.ts`),
+ * });
+ */
+declare function initI18next(options?: {
+  language?: string;
+  instance?: i18n;
+  loadLocale?: LocaleLoader;
+}): i18n;
+//#endregion
+export { initI18next };
+//# sourceMappingURL=i18n-client.d.ts.map

package/dist/i18n-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n-client.d.ts","names":[],"sources":["../src/i18n/types.ts","../src/i18n/client.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;KAoCY,YAAA,yBAAqC;WAAmB;;;;;;;;;;;;;;;;;iBCwBpD,WAAA;;aAAsD;eAAmB;IAAiB"}

package/dist/i18n-client.js

@@ -0,0 +1,72 @@
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import I18nextBrowserLanguageDetector from "i18next-browser-languagedetector";
+
+//#region src/i18n/defaults.ts
+/** Shared i18next interpolation config. Disables HTML escaping (React handles that) and adds `{{ value, number }}` formatting via `toLocaleString`. */
+const defaultInterpolation = {
+	escapeValue: false,
+	format: (value, format) => {
+		if (format === "number" && typeof value === "number") return value.toLocaleString();
+		return value;
+	}
+};
+
+//#endregion
+//#region src/i18n/client.ts
+/**
+* Custom i18next backend that calls the provided `loadLocale` callback to dynamically
+* import translations. Keeping the import() call in the template lets Vite resolve the
+* dynamic path at build time and split translations into per-language chunks.
+*/
+function createDynamicImportBackend(instance, loadLocale) {
+	return {
+		type: "backend",
+		init() {},
+		read(language, namespace, callback) {
+			loadLocale(language).then((module) => {
+				const translations = module.default;
+				Object.entries(translations).forEach(([ns, nsTranslations]) => {
+					instance.addResourceBundle(language, ns, nsTranslations, true, true);
+				});
+				callback(null, translations[namespace] ?? {});
+			}).catch((error) => {
+				callback(error, false);
+			});
+		}
+	};
+}
+/**
+* Initialize i18next on the client side.
+* Pass a `loadLocale` callback containing the dynamic import so Vite can resolve it
+* at build time relative to the template's source tree.
+*
+* @example
+* // In root.tsx — Vite resolves the import() relative to this file
+* initI18next({
+*     language: document.documentElement.lang || undefined,
+*     loadLocale: (language) => import(`@/locales/${language}/index.ts`),
+* });
+*/
+function initI18next(options) {
+	const language = options?.language;
+	const instance = options?.instance ?? i18next;
+	const loadLocale = options?.loadLocale;
+	if (language) instance.language = language;
+	const i18nextInstance = instance.use(initReactI18next);
+	if (loadLocale) i18nextInstance.use(createDynamicImportBackend(instance, loadLocale));
+	if (!language) i18nextInstance.use(I18nextBrowserLanguageDetector);
+	i18nextInstance.init({
+		ns: [],
+		...language ? { lng: language } : { detection: {
+			order: ["htmlTag"],
+			caches: []
+		} },
+		interpolation: defaultInterpolation
+	});
+	return instance;
+}
+
+//#endregion
+export { initI18next };
+//# sourceMappingURL=i18n-client.js.map

package/dist/i18n-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n-client.js","names":["defaultInterpolation: InterpolationOptions"],"sources":["../src/i18n/defaults.ts","../src/i18n/client.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 */\nimport type { InterpolationOptions } from 'i18next';\n\n/** Shared i18next interpolation config. Disables HTML escaping (React handles that) and adds `{{ value, number }}` formatting via `toLocaleString`. */\nexport const defaultInterpolation: InterpolationOptions = {\n    escapeValue: false,\n    format: (value, format) => {\n        if (format === 'number' && typeof value === 'number') {\n            return value.toLocaleString();\n        }\n        return value;\n    },\n};\n","/**\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 */\nimport i18next, { type i18n, type BackendModule, type ReadCallback } from 'i18next';\nimport { initReactI18next } from 'react-i18next';\nimport I18nextBrowserLanguageDetector from 'i18next-browser-languagedetector';\nimport { defaultInterpolation } from './defaults.js';\nimport type { LocaleLoader } from './types.js';\n\n/**\n * Custom i18next backend that calls the provided `loadLocale` callback to dynamically\n * import translations. Keeping the import() call in the template lets Vite resolve the\n * dynamic path at build time and split translations into per-language chunks.\n */\nfunction createDynamicImportBackend(instance: i18n, loadLocale: LocaleLoader): BackendModule {\n    return {\n        type: 'backend',\n        init() {\n            // No initialization needed\n        },\n        read(language: string, namespace: string, callback: ReadCallback) {\n            loadLocale(language)\n                .then((module) => {\n                    const translations = module.default;\n                    Object.entries(translations).forEach(([ns, nsTranslations]) => {\n                        instance.addResourceBundle(language, ns, nsTranslations, true, true);\n                    });\n                    callback(null, translations[namespace] ?? {});\n                })\n                .catch((error: Error) => {\n                    callback(error, false);\n                });\n        },\n    };\n}\n\n/**\n * Initialize i18next on the client side.\n * Pass a `loadLocale` callback containing the dynamic import so Vite can resolve it\n * at build time relative to the template's source tree.\n *\n * @example\n * // In root.tsx — Vite resolves the import() relative to this file\n * initI18next({\n *     language: document.documentElement.lang || undefined,\n *     loadLocale: (language) => import(`@/locales/${language}/index.ts`),\n * });\n */\nexport function initI18next(options?: { language?: string; instance?: i18n; loadLocale?: LocaleLoader }): i18n {\n    // NOTE: For any changes to this function, verify that Vite HMR still works with translations\n\n    const language = options?.language;\n    const instance = options?.instance ?? i18next;\n    const loadLocale = options?.loadLocale;\n\n    if (language) {\n        instance.language = language;\n    }\n\n    const i18nextInstance = instance.use(initReactI18next);\n\n    if (loadLocale) {\n        i18nextInstance.use(createDynamicImportBackend(instance, loadLocale));\n    }\n\n    if (!language) {\n        i18nextInstance.use(I18nextBrowserLanguageDetector);\n    }\n\n    void i18nextInstance.init({\n        ns: [],\n        ...(language\n            ? { lng: language }\n            : {\n                  detection: { order: ['htmlTag'], caches: [] },\n              }),\n        interpolation: defaultInterpolation,\n    });\n\n    return instance;\n}\n"],"mappings":";;;;;;AAkBA,MAAaA,uBAA6C;CACtD,aAAa;CACb,SAAS,OAAO,WAAW;AACvB,MAAI,WAAW,YAAY,OAAO,UAAU,SACxC,QAAO,MAAM,gBAAgB;AAEjC,SAAO;;CAEd;;;;;;;;;ACAD,SAAS,2BAA2B,UAAgB,YAAyC;AACzF,QAAO;EACH,MAAM;EACN,OAAO;EAGP,KAAK,UAAkB,WAAmB,UAAwB;AAC9D,cAAW,SAAS,CACf,MAAM,WAAW;IACd,MAAM,eAAe,OAAO;AAC5B,WAAO,QAAQ,aAAa,CAAC,SAAS,CAAC,IAAI,oBAAoB;AAC3D,cAAS,kBAAkB,UAAU,IAAI,gBAAgB,MAAM,KAAK;MACtE;AACF,aAAS,MAAM,aAAa,cAAc,EAAE,CAAC;KAC/C,CACD,OAAO,UAAiB;AACrB,aAAS,OAAO,MAAM;KACxB;;EAEb;;;;;;;;;;;;;;AAeL,SAAgB,YAAY,SAAmF;CAG3G,MAAM,WAAW,SAAS;CAC1B,MAAM,WAAW,SAAS,YAAY;CACtC,MAAM,aAAa,SAAS;AAE5B,KAAI,SACA,UAAS,WAAW;CAGxB,MAAM,kBAAkB,SAAS,IAAI,iBAAiB;AAEtD,KAAI,WACA,iBAAgB,IAAI,2BAA2B,UAAU,WAAW,CAAC;AAGzE,KAAI,CAAC,SACD,iBAAgB,IAAI,+BAA+B;AAGvD,CAAK,gBAAgB,KAAK;EACtB,IAAI,EAAE;EACN,GAAI,WACE,EAAE,KAAK,UAAU,GACjB,EACI,WAAW;GAAE,OAAO,CAAC,UAAU;GAAE,QAAQ,EAAE;GAAE,EAChD;EACP,eAAe;EAClB,CAAC;AAEF,QAAO"}

package/dist/i18n.d.ts

@@ -0,0 +1,63 @@
+import { MiddlewareFunction, RouterContextProvider } from "react-router";
+import * as i18next0 from "i18next";
+import { InterpolationOptions, Resource, ResourceLanguage, ThirdPartyModule, i18n } from "i18next";
+
+//#region src/i18n/context.d.ts
+
+/**
+ * Gets the i18next instance and translation function for non-component code.
+ * Use `useTranslation` hook for React components. Mirrors the `getConfig`/`useConfig` pattern.
+ */
+declare function getTranslation(context?: Readonly<RouterContextProvider>): {
+  i18next: i18n;
+  t: i18next0.TFunction<["translation", ...string[]], undefined>;
+};
+/**
+ * Gets the active locale string from server context.
+ * Returns undefined on the client (locale is on the document element or URL).
+ */
+declare function getLocale(context: Readonly<RouterContextProvider>): string | undefined;
+/**
+ * Sets up a mock i18n context on a RouterContextProvider for use in tests.
+ * Replaces the need to import the internal i18nextContext key directly.
+ */
+declare function mockI18nContext(contextProvider: RouterContextProvider, options?: {
+  locale?: string;
+  instance?: i18n;
+}): void;
+//#endregion
+//#region src/i18n/types.d.ts
+
+/** Config passed to `createI18nMiddleware`. All values come from the template — the SDK never reads config values directly. */
+interface I18nMiddlewareConfig {
+  resources: Resource;
+  supportedLanguages: string[];
+  fallbackLanguage: string;
+  interpolation?: InterpolationOptions;
+  plugins?: ThirdPartyModule[];
+}
+/**
+ * Callback that dynamically imports all translations for a given language.
+ * Must be defined in template code so Vite can resolve the `import()` path at build time
+ * and split translations into per-language chunks.
+ *
+ * @example
+ * const loadLocale: LocaleLoader = (language) => import(`@/locales/${language}/index.ts`);
+ */
+type LocaleLoader = (language: string) => Promise<{
+  default: ResourceLanguage;
+}>;
+//#endregion
+//#region src/i18n/middleware.d.ts
+/**
+ * Creates a server-side i18next middleware from the provided config.
+ * Lazy-initializes on first request so supported languages can come from runtime config.
+ */
+declare function createI18nMiddleware(config: I18nMiddlewareConfig): MiddlewareFunction<Response>;
+//#endregion
+//#region src/i18n/defaults.d.ts
+/** Shared i18next interpolation config. Disables HTML escaping (React handles that) and adds `{{ value, number }}` formatting via `toLocaleString`. */
+declare const defaultInterpolation: InterpolationOptions;
+//#endregion
+export { type I18nMiddlewareConfig, type LocaleLoader, type Resource, type ResourceLanguage, createI18nMiddleware, defaultInterpolation, getLocale, getTranslation, mockI18nContext };
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","names":[],"sources":["../src/i18n/context.ts","../src/i18n/types.ts","../src/i18n/middleware.ts","../src/i18n/defaults.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AE2BA;AAA6C,iBFI7B,cAAA,CEJ6B,OAAA,CAAA,EFIJ,QEJI,CFIK,qBEJL,CAAA,CAAA,EAAA;EAA0C,OAAA,MAAA;EAAnB,CAAA,oBAAA,CAAA,CAAA,aAAA,EAAA,GAAA,MAAA,EAAA,CAAA,EAAA,SAAA,CAAA;CAAkB;;;;ACTtF;iBHqCgB,SAAA,UAAmB,SAAS;;;;;iBAQ5B,eAAA,kBACK;;aACsB;;;;;;ACzCvB,UAJH,oBAAA,CAIG;EACN,SAAA,EAJC,QAID;EAAgB,kBAAA,EAAA,MAAA,EAAA;EAWlB,gBAAY,EAAA,MAAA;kBAZJ;YACN;;ACEd;;;;;;;;ACTa,KFkBD,YAAA,GEVX,CAAA,QAAA,EAAA,MARkC,EAAA,GFkBc,OElBd,CAAA;WFkBiC;;;;;;;ADLpE;AAAkD,iBEJlC,oBAAA,CFIkC,MAAA,EEJL,oBFIK,CAAA,EEJkB,kBFIlB,CEJqC,QFIrC,CAAA;;;ACXlD;AACe,cEHF,oBFGE,EEHoB,oBFGpB"}

package/dist/i18n.js

@@ -0,0 +1,98 @@
+import { a as requestToLocaleMap } from "./site-context2.js";
+import "./apply-url-config.js";
+import { createContext } from "react-router";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { createI18nextMiddleware } from "remix-i18next/middleware";
+
+//#region src/i18n/context.ts
+const i18nextContext = createContext(null);
+/**
+* Gets the i18next instance and translation function for non-component code.
+* Use `useTranslation` hook for React components. Mirrors the `getConfig`/`useConfig` pattern.
+*/
+function getTranslation(context) {
+	if (context && typeof window === "undefined") {
+		const i18nextData = context.get(i18nextContext);
+		if (!i18nextData) throw new Error("i18next data not found in context. Ensure i18next middleware runs before loaders.");
+		const i18nextInstance = i18nextData.getI18nextInstance();
+		return {
+			i18next: i18nextInstance,
+			t: i18nextInstance.t
+		};
+	}
+	return {
+		i18next,
+		t: i18next.t
+	};
+}
+/**
+* Gets the active locale string from server context.
+* Returns undefined on the client (locale is on the document element or URL).
+*/
+function getLocale(context) {
+	return context.get(i18nextContext)?.getLocale();
+}
+/**
+* Sets up a mock i18n context on a RouterContextProvider for use in tests.
+* Replaces the need to import the internal i18nextContext key directly.
+*/
+function mockI18nContext(contextProvider, options = {}) {
+	const { locale = "en-GB", instance = i18next } = options;
+	contextProvider.set(i18nextContext, {
+		getLocale: () => locale,
+		getI18nextInstance: () => instance
+	});
+}
+
+//#endregion
+//#region src/i18n/defaults.ts
+/** Shared i18next interpolation config. Disables HTML escaping (React handles that) and adds `{{ value, number }}` formatting via `toLocaleString`. */
+const defaultInterpolation = {
+	escapeValue: false,
+	format: (value, format) => {
+		if (format === "number" && typeof value === "number") return value.toLocaleString();
+		return value;
+	}
+};
+
+//#endregion
+//#region src/i18n/middleware.ts
+/**
+* Creates a server-side i18next middleware from the provided config.
+* Lazy-initializes on first request so supported languages can come from runtime config.
+*/
+function createI18nMiddleware(config) {
+	const { resources, supportedLanguages, fallbackLanguage, interpolation, plugins = [] } = config;
+	let cached = null;
+	return async (args, next) => {
+		if (!cached) cached = createI18nextMiddleware({
+			detection: {
+				order: ["custom"],
+				findLocale: async (request) => {
+					return requestToLocaleMap.get(request) ?? null;
+				},
+				fallbackLanguage,
+				supportedLanguages
+			},
+			i18next: {
+				resources,
+				interpolation: {
+					...defaultInterpolation,
+					...interpolation
+				}
+			},
+			plugins: [initReactI18next, ...plugins]
+		});
+		const [originalMiddleware, getLocale$1, getInstance] = cached;
+		args.context.set(i18nextContext, {
+			getLocale: () => getLocale$1(args.context),
+			getI18nextInstance: () => getInstance(args.context)
+		});
+		return originalMiddleware(args, next);
+	};
+}
+
+//#endregion
+export { createI18nMiddleware, defaultInterpolation, getLocale, getTranslation, mockI18nContext };
+//# sourceMappingURL=i18n.js.map