mage-obsidian 1.1.2 → 2.0.0

package/src/runtime/i18nCore.ts

@@ -0,0 +1,113 @@
+/**
+ * Framework i18n core — Magento-parity phrase translation for the Vue/ESM side.
+ *
+ * Mirrors Magento's `$t` / `$.mage.__`: a phrase is looked up in the dictionary
+ * (the per-locale `js-translation.json` Magento already generates during static
+ * deploy) and falls back to the original phrase when absent; then `%1`, `%2`, …
+ * placeholders are substituted positionally.
+ *
+ * Kept free of Vue and the DOM so it is unit-testable in isolation — the Vue
+ * plugin (shipped as a module web asset) wraps these primitives.
+ */
+
+export interface I18nConfig {
+    locale?: string;
+    dictionaryUrl?: string;
+}
+
+interface I18nScope {
+    __MAGE_OBSIDIAN_I18N__?: I18nConfig;
+}
+
+export type Dictionary = Record<string, string>;
+
+// Published by PHP on the page before the ESM runtime loads.
+declare global {
+    interface Window {
+        __MAGE_OBSIDIAN_I18N__?: I18nConfig;
+    }
+}
+
+const PLACEHOLDER = /%(\d+)/g;
+
+/**
+ * Replace `%1`, `%2`, … with positional args. An out-of-range placeholder is
+ * left untouched so a malformed phrase never throws or yields "undefined".
+ */
+export function interpolate(text: string, args: unknown[] = []): string {
+    if (typeof text !== "string" || !args || args.length === 0) {
+        return text;
+    }
+    return text.replace(PLACEHOLDER, (match, index) => {
+        const value = args[Number(index) - 1];
+        return value === undefined ? match : String(value);
+    });
+}
+
+/**
+ * Translate a phrase against a dictionary, falling back to the phrase itself,
+ * then interpolate placeholders.
+ */
+export function translatePhrase(
+    dictionary: Dictionary | null | undefined,
+    phrase: string,
+    args: unknown[] = [],
+): string {
+    const dict = dictionary && typeof dictionary === "object" ? dictionary : {};
+    const translated = Object.prototype.hasOwnProperty.call(dict, phrase) ? dict[phrase] : phrase;
+    return interpolate(translated, args);
+}
+
+/**
+ * Read the runtime i18n config published by PHP as `window.__MAGE_OBSIDIAN_I18N__`.
+ * Returns sane defaults when absent so the layer degrades to passthrough.
+ */
+export function readI18nConfig(
+    scope: I18nScope | undefined = typeof window !== "undefined" ? window : undefined,
+): { locale: string; dictionaryUrl: string | null } {
+    const config = scope && scope.__MAGE_OBSIDIAN_I18N__;
+    return {
+        locale: (config && config.locale) || "en_US",
+        dictionaryUrl: (config && config.dictionaryUrl) || null,
+    };
+}
+
+const dictionaryCache = new Map<string, Promise<Dictionary>>();
+
+/**
+ * Fetch and cache a dictionary by URL. The fetch happens at most once per URL
+ * regardless of how many Vue apps request it. Magento emits `[]` for an empty
+ * dictionary, which is normalized to `{}`; any failure degrades to `{}` so the
+ * UI keeps rendering original phrases.
+ */
+export function loadDictionary(
+    url: string | null | undefined,
+    fetchImpl: typeof fetch | undefined = typeof fetch !== "undefined" ? fetch : undefined,
+): Promise<Dictionary> {
+    if (!url) {
+        return Promise.resolve({});
+    }
+    if (!dictionaryCache.has(url)) {
+        if (typeof fetchImpl !== "function") {
+            return Promise.resolve({});
+        }
+        const promise: Promise<Dictionary> = fetchImpl(url)
+            .then((res) => (res && res.ok ? res.json() : {}))
+            .then(
+                (data: unknown): Dictionary =>
+                    data && typeof data === "object" && !Array.isArray(data)
+                        ? (data as Dictionary)
+                        : {},
+            )
+            .catch((): Dictionary => ({}));
+        dictionaryCache.set(url, promise);
+    }
+    return dictionaryCache.get(url)!;
+}
+
+/**
+ * Test-only: clear the dictionary cache between cases.
+ */
+export function _resetDictionaryCache(): void {
+    dictionaryCache.clear();
+}

package/src/runtime/interceptorManager.ts

@@ -0,0 +1,186 @@
+export type InterceptorType = "before" | "around" | "after";
+
+// Handlers receive the intercepted subject first (Magento plugin parity); the
+// remaining shape varies per type, so the tail stays `any[]`.
+export type InterceptorHandler = (subject: any, ...rest: any[]) => any;
+
+export interface InterceptorEntry {
+    name: string;
+    handler: InterceptorHandler;
+    sortOrder: number;
+}
+
+type InterceptorBuckets = Record<InterceptorType, InterceptorEntry[]>;
+
+const TYPES: readonly InterceptorType[] = ["before", "around", "after"];
+
+function emptyBuckets(): InterceptorBuckets {
+    return { before: [], around: [], after: [] };
+}
+
+class InterceptorManager {
+    // `declare` keeps this type-only (erasable): the runtime field is created by
+    // the constructor assignment below, type-stripping emits nothing for this.
+    declare interceptors: Record<string, InterceptorBuckets>;
+
+    constructor() {
+        this.interceptors = {};
+    }
+
+    /**
+     * Register an interceptor. `target` is the function/method name to wrap;
+     * `name` is a unique id; `sortOrder` controls execution order.
+     */
+    addInterceptor(
+        target: string,
+        name: string,
+        type: InterceptorType,
+        handler: InterceptorHandler,
+        sortOrder: number = 10,
+    ) {
+        if (!this.interceptors[target]) {
+            this.interceptors[target] = emptyBuckets();
+        }
+        if (!TYPES.includes(type)) {
+            throw new Error(`Invalid interceptor type: ${type}`);
+        }
+        this.interceptors[target][type].push({ name, handler, sortOrder });
+        this.interceptors[target][type].sort((a, b) => a.sortOrder - b.sortOrder);
+    }
+
+    /**
+     * Execute the intercepted method chain synchronously.
+     *
+     * Handlers receive the intercepted module exports as an explicit `subject`
+     * first argument (Magento plugin parity): before(subject, ...args),
+     * around(subject, proceed, ...args), after(subject, result, ...args).
+     * `this` is still bound to the same object, so handlers written against the
+     * legacy `this`-based access keep working (arrow functions now have a path
+     * to the subject they could not reach via `this`).
+     */
+    executeSync(
+        target: string,
+        originalMethod: (...args: any[]) => any,
+        context: any,
+        ...args: any[]
+    ): any {
+        const interceptors = this.interceptors[target] || emptyBuckets();
+
+        // Execute 'before' interceptors
+        for (const interceptor of interceptors.before) {
+            const result = interceptor.handler.apply(context, [context, ...args]);
+            if (Array.isArray(result)) {
+                args = result;
+            }
+        }
+
+        // Execute 'around' interceptors
+        let methodToExecute = (...currentArgs: any[]) => {
+            return originalMethod.apply(context, currentArgs);
+        };
+
+        if (interceptors.around.length > 0) {
+            const aroundInterceptors = [...interceptors.around].reverse();
+            for (const interceptor of aroundInterceptors) {
+                const next = methodToExecute;
+                methodToExecute = (...currentArgs: any[]) => {
+                    return interceptor.handler.apply(context, [context, next, ...currentArgs]);
+                };
+            }
+        }
+
+        let result = methodToExecute(...args);
+
+        // Execute 'after' interceptors
+        for (const interceptor of interceptors.after) {
+            result = interceptor.handler.apply(context, [context, result, ...args]);
+        }
+
+        return result;
+    }
+
+    /**
+     * Execute the intercepted method chain.
+     *
+     * Same `subject`-first contract as {@link executeSync}: before(subject,
+     * ...args), around(subject, proceed, ...args), after(subject, result,
+     * ...args), with `this` still bound to the subject for backward compat.
+     */
+    async execute(
+        target: string,
+        originalMethod: (...args: any[]) => any,
+        context: any,
+        ...args: any[]
+    ): Promise<any> {
+        const interceptors = this.interceptors[target] || emptyBuckets();
+
+        // Execute 'before' interceptors
+        // Before interceptors receive (subject, ...args) and can modify args by
+        // returning an array of the (subject-less) args.
+        for (const interceptor of interceptors.before) {
+            const result = await interceptor.handler.apply(context, [context, ...args]);
+            if (Array.isArray(result)) {
+                args = result;
+            }
+        }
+
+        // Execute 'around' interceptors
+        // Around interceptors receive (subject, proceed, ...args)
+        let methodToExecute = async (...currentArgs: any[]) => {
+            return await originalMethod.apply(context, currentArgs);
+        };
+
+        // Wrap around interceptors: first registered is outer-most
+        if (interceptors.around.length > 0) {
+            const aroundInterceptors = [...interceptors.around].reverse();
+            for (const interceptor of aroundInterceptors) {
+                const next = methodToExecute;
+                methodToExecute = async (...currentArgs: any[]) => {
+                    return await interceptor.handler.apply(context, [
+                        context,
+                        next,
+                        ...currentArgs,
+                    ]);
+                };
+            }
+        }
+
+        let result = await methodToExecute(...args);
+
+        // Execute 'after' interceptors
+        // After interceptors receive (subject, result, ...args) and must return result
+        for (const interceptor of interceptors.after) {
+            result = await interceptor.handler.apply(context, [context, result, ...args]);
+        }
+
+        return result;
+    }
+
+    /**
+     * Create a proxy that intercepts method calls on an object (e.g. module
+     * exports). `namespace` scopes the interceptor keys; `useAsync` picks the
+     * async or sync chain.
+     */
+    intercept(target: object, namespace: string, useAsync: boolean = true) {
+        return new Proxy(target, {
+            get: (obj: any, prop) => {
+                const value = obj[prop];
+                if (typeof value === "function") {
+                    return (...args: any[]) => {
+                        const method = useAsync ? this.execute : this.executeSync;
+                        return method.call(
+                            this,
+                            `${namespace}::${String(prop)}`,
+                            value,
+                            obj,
+                            ...args,
+                        );
+                    };
+                }
+                return value;
+            },
+        });
+    }
+}
+
+export default new InterceptorManager();

package/src/runtime/islands.ts

@@ -0,0 +1,84 @@
+/**
+ * Framework island runtime — the browser side of `renderVueComponent`.
+ *
+ * PHP emits an inert marker per component
+ * (`<div data-mage-island data-component data-props data-strategy>`); this
+ * module turns each marker into a mounted Vue app. Every island is its own app
+ * (preserving isolation), but the Vue runtime and the i18n plugin are loaded
+ * once per page and shared, and "visible" islands hydrate only when they enter
+ * the viewport — so below-the-fold components cost nothing until scrolled to.
+ *
+ * All side effects (dynamic import, app creation, plugin wiring, viewport
+ * observation) are injected, so the discovery/hydration logic is unit-testable
+ * in Node without a DOM, a bundler, or Vue. The concrete wiring lives in the
+ * module's `web/js/islands.js`.
+ */
+
+// Set synchronously before the async import so a second observer callback for
+// the same element is a no-op (dataset key for `data-mage-island-mounted`).
+const MOUNTED_FLAG = "mageIslandMounted";
+
+interface IslandElement {
+    dataset: Record<string, string | undefined>;
+}
+
+interface AppLike {
+    mount(el: unknown): unknown;
+}
+
+interface HydrateDeps {
+    importComponent(source: string): Promise<{ default?: unknown }>;
+    createApp(component: unknown, props?: Record<string, unknown>): AppLike;
+    configureApp(app: AppLike): void;
+}
+
+interface DiscoverDeps extends HydrateDeps {
+    observe(element: IslandElement, onVisible: () => void): void;
+}
+
+/**
+ * Mount a single island. Idempotent: the first call claims the element and
+ * later calls return immediately, so re-observation never double-mounts.
+ *
+ * @throws Error When the marker has no `data-component`.
+ */
+export async function hydrateIsland(
+    element: IslandElement,
+    deps: HydrateDeps,
+): Promise<AppLike | undefined> {
+    if (element.dataset[MOUNTED_FLAG]) {
+        return undefined;
+    }
+    element.dataset[MOUNTED_FLAG] = "1";
+
+    const source = element.dataset.component;
+    if (!source) {
+        throw new Error("Island marker is missing data-component.");
+    }
+
+    const module = await deps.importComponent(source);
+    const component = module.default ?? module;
+    const props = element.dataset.props ? JSON.parse(element.dataset.props) : {};
+
+    const app = deps.createApp(component, props);
+    deps.configureApp(app);
+    app.mount(element);
+    return app;
+}
+
+/**
+ * Hydrate every marker. `eager` markers mount now; the rest mount when the
+ * injected observer reports them visible.
+ */
+export function hydrateAll(elements: Iterable<IslandElement>, deps: DiscoverDeps): void {
+    for (const element of elements) {
+        const strategy = element.dataset.strategy ?? "visible";
+        if (strategy === "eager") {
+            void hydrateIsland(element, deps);
+        } else {
+            deps.observe(element, () => {
+                void hydrateIsland(element, deps);
+            });
+        }
+    }
+}

package/src/runtime/sectionStoreCore.ts

@@ -0,0 +1,259 @@
+/**
+ * Section store core — pure helpers for mirroring a set of server-pushed,
+ * versioned "sections" into a reactive store backed by localStorage.
+ *
+ * This is the GENERIC mechanism, deliberately domain-agnostic: it knows how to
+ * parse/merge/select sections, decide staleness, read a version cookie and
+ * decide when to hydrate — but nothing about WHICH endpoint, cookie or storage
+ * key a given integration uses. A binding (e.g. the Magento customer-data
+ * adapter) supplies those and wraps these primitives with Vue/Pinia reactivity.
+ *
+ * Kept free of Vue, Pinia and the DOM so the parsing/merge/staleness rules are
+ * unit-testable in isolation.
+ */
+
+export type SectionData = Record<string, unknown>;
+export type SectionMap = Record<string, SectionData>;
+
+export interface SectionLoadOptions {
+    baseUrl?: string;
+    forceNewTimestamp?: boolean;
+}
+
+export interface SectionRuntimeConfig {
+    lifetimeSeconds: number;
+    expirableSections: string[];
+}
+
+interface SectionRuntimeScope {
+    __MAGE_OBSIDIAN_SECTIONS__?: { lifetime?: unknown; expirable?: unknown };
+}
+
+// Published by PHP on the page before the ESM runtime loads.
+declare global {
+    interface Window {
+        __MAGE_OBSIDIAN_SECTIONS__?: { lifetime?: unknown; expirable?: unknown };
+    }
+}
+
+/**
+ * Parse the raw section-storage JSON into a map of section objects. Tolerates
+ * missing/corrupt input and drops non-object section values so the caller
+ * always gets a clean `{ [section]: object }` map.
+ */
+export function parseSectionStorage(raw: string | null | undefined): SectionMap {
+    if (typeof raw !== "string" || raw === "") {
+        return {};
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return {};
+    }
+
+    return pickObjectEntries(parsed);
+}
+
+/**
+ * Return a single section, or null when it is absent or not an object.
+ */
+export function selectSection(
+    sections: SectionMap | null | undefined,
+    name: string,
+): SectionData | null {
+    if (!sections || typeof sections !== "object") {
+        return null;
+    }
+    const value = sections[name];
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? (value as SectionData)
+        : null;
+}
+
+/**
+ * Overlay freshly loaded sections onto the current map (a section-load response
+ * merges per section; non-object values are ignored).
+ */
+export function mergeSections(
+    current: SectionMap | null | undefined,
+    incoming: SectionMap | null | undefined,
+): SectionMap {
+    return { ...pickObjectEntries(current), ...pickObjectEntries(incoming) };
+}
+
+/**
+ * Whether a section should be (re)fetched. A missing section is stale; a
+ * section without a positive `data_id` is a client-side section that never
+ * expires; with no positive lifetime nothing expires either. Otherwise it is
+ * stale once `data_id + lifetime` has passed.
+ */
+export function isSectionStale(
+    section: SectionData | null | undefined,
+    lifetimeSeconds: number,
+    nowSeconds: number,
+): boolean {
+    if (!section || typeof section !== "object") {
+        return true;
+    }
+
+    const dataId = Number(section.data_id);
+    if (!Number.isFinite(dataId) || dataId <= 0) {
+        return false;
+    }
+    if (!Number.isFinite(lifetimeSeconds) || lifetimeSeconds <= 0) {
+        return false;
+    }
+
+    return dataId + lifetimeSeconds <= nowSeconds;
+}
+
+/**
+ * Build the section-load URL a binding uses to (re)load sections. `endpoint` is
+ * supplied by the binding (this core is endpoint-agnostic). An empty name list
+ * requests ALL sections by omitting the `sections` param — Magento's protocol
+ * returns every section then and rejects a literal `sections=*` with 400.
+ */
+export function buildSectionLoadUrl(
+    endpoint: string,
+    sectionNames: string[],
+    options: SectionLoadOptions = {},
+): string {
+    const { baseUrl = "/", forceNewTimestamp = false } = options;
+    const names = Array.isArray(sectionNames) ? sectionNames.filter(Boolean) : [];
+    const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const path = endpoint.startsWith("/") ? endpoint.slice(1) : endpoint;
+
+    const params: string[] = [];
+    if (names.length) {
+        params.push(`sections=${names.join(",")}`);
+    }
+    params.push(`force_new_section_timestamp=${forceNewTimestamp ? "true" : "false"}`);
+
+    return `${base}${path}?${params.join("&")}`;
+}
+
+/**
+ * Read a single cookie value from a `document.cookie` string. Returns "" when
+ * the cookie is absent. Kept pure (the binding passes `document.cookie` in) so
+ * the version lookup is testable without a DOM.
+ */
+export function readCookie(cookieString: string | null | undefined, name: string): string {
+    if (typeof cookieString !== "string" || cookieString === "" || !name) {
+        return "";
+    }
+    for (const pair of cookieString.split(";")) {
+        const index = pair.indexOf("=");
+        if (index === -1) {
+            continue;
+        }
+        if (pair.slice(0, index).trim() === name) {
+            return decodeURIComponent(pair.slice(index + 1).trim());
+        }
+    }
+    return "";
+}
+
+/**
+ * Whether the store must hydrate sections from the server on init.
+ *
+ * A binding bumps a version (e.g. Magento's `private_content_version` cookie)
+ * whenever the server's pushed content changes. When nothing is cached yet, or
+ * the current version has moved past the last synced version, the cached
+ * sections are stale.
+ */
+export function needsHydration(
+    sections: SectionMap | null | undefined,
+    syncedVersion: string,
+    currentVersion: string,
+): boolean {
+    if (!sections || typeof sections !== "object" || Object.keys(sections).length === 0) {
+        return true;
+    }
+    return currentVersion !== "" && currentVersion !== syncedVersion;
+}
+
+/**
+ * True when the session marker cookie is gone. Magento's login/logout controllers
+ * delete it server-side, so its absence means cached sections are stale (the
+ * version cookie doesn't move on logout). False when no marker is configured.
+ */
+export function sessionInvalidated(
+    cookieString: string | null | undefined,
+    sessionCookieName: string,
+): boolean {
+    if (!sessionCookieName) {
+        return false;
+    }
+    return readCookie(cookieString, sessionCookieName) === "";
+}
+
+/**
+ * The expirable sections that have aged out and must be re-fetched, mirroring the
+ * lifetime branch of Magento's native `getExpiredSectionNames`: a section listed
+ * in `expirableNames` expires once `data_id + lifetimeSeconds <= now`.
+ *
+ * This is the backstop the version cookie cannot provide: `private_content_version`
+ * only moves on POST, so a section whose server data changed through a non-POST
+ * path the browser took — most commonly the PHP session/quote expiring while
+ * localStorage lives on — is otherwise never re-fetched, leaving a stale snapshot
+ * (e.g. a cart badge that outlives its quote). Absent sections are skipped here,
+ * exactly like native (they reload via the version/empty-cache path instead).
+ */
+export function expiredSectionNames(
+    sections: SectionMap | null | undefined,
+    lifetimeSeconds: number,
+    expirableNames: string[],
+    nowSeconds: number,
+): string[] {
+    if (!Array.isArray(expirableNames) || expirableNames.length === 0) {
+        return [];
+    }
+    const map = sections && typeof sections === "object" ? sections : {};
+    const expired: string[] = [];
+    for (const name of expirableNames) {
+        const section = map[name];
+        if (
+            section &&
+            typeof section === "object" &&
+            isSectionStale(section, lifetimeSeconds, nowSeconds)
+        ) {
+            expired.push(name);
+        }
+    }
+    return expired;
+}
+
+/**
+ * Read the runtime section config a binding's host page publishes (lifetime +
+ * which sections expire by lifetime). Kept pure — the binding passes the scope
+ * (e.g. `window`) — so it is testable without a DOM, like `readI18nConfig`.
+ */
+export function readSectionRuntimeConfig(
+    scope: SectionRuntimeScope | undefined = typeof window !== "undefined" ? window : undefined,
+): SectionRuntimeConfig {
+    const config = scope && scope.__MAGE_OBSIDIAN_SECTIONS__;
+    const lifetime = Number(config && config.lifetime);
+    const expirable = config && config.expirable;
+    return {
+        lifetimeSeconds: Number.isFinite(lifetime) && lifetime > 0 ? lifetime : 0,
+        expirableSections: Array.isArray(expirable)
+            ? expirable.filter((name): name is string => typeof name === "string")
+            : [],
+    };
+}
+
+function pickObjectEntries(value: unknown): SectionMap {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+
+    const result: SectionMap = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+            result[key] = entry as SectionData;
+        }
+    }
+    return result;
+}