@wocart/storefront 0.0.0-stage → 1.1.0

package/dist/routes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The canonical storefront route contract.
+ *
+ * One deployment serves one store, and three parts of the platform meet on the
+ * same public URLs: the theme renders them, the server writes them into a conversion's
+ * landing URL (`/lp/:slug` for an attributed sale, `/thank-you` otherwise), and
+ * the dashboard shows them as the store's public links (`/pages/:slug`). These
+ * patterns are what all three already assume, so they are written down here: a
+ * theme may restyle everything else, but these paths are a platform contract,
+ * not a theme decision.
+ *
+ * Two further paths carry no parameter and no pattern: the root (`/`, the home
+ * surface) and the catalog index (`/products`, the catalog surface). The
+ * surface gate below handles them alongside the six frozen patterns.
+ */
+import type { WidgetSurfaces } from "./types.js";
+/** One route in the contract: the pattern and the surface that renders it. */
+export interface StorefrontRoute {
+    /** Path pattern; `:handle` and `:slug` mark the single path parameter. */
+    readonly path: string;
+    /** The `surfaces` key this route belongs to. */
+    readonly surface: keyof WidgetSurfaces;
+}
+/**
+ * The frozen contract. Adding a route is a deliberate platform change: a path
+ * that renders a surface but is missing here is a surface the merchant cannot
+ * switch on with any confidence.
+ */
+export declare const STOREFRONT_ROUTES: readonly StorefrontRoute[];
+/**
+ * Whether the widget belongs on a pathname.
+ *
+ * The merchant answers "which surfaces" (`surfaces[surface]`); this function
+ * answers the platform half — which surface a pathname *is* — and it reads the
+ * contract above:
+ *
+ * - `/` → the home surface;
+ * - `/products` (the catalog index) and `/category/:slug` → the catalog surface;
+ * - `/products/:handle` → the product surface;
+ * - `/pages/:slug`, `/lp/:slug`, `/checkout`, `/thank-you` → their own surfaces;
+ * - anything else — a 404, `/productsomething`, `/checkout-success` — → no
+ *   surface at all, never a prefix match that leaks a widget onto a page the
+ *   merchant switched off.
+ */
+export declare function showsWidgetOn(surfaces: WidgetSurfaces | null | undefined, rawPathname: string): boolean;

package/dist/routes.js

@@ -0,0 +1,59 @@
+/**
+ * The frozen contract. Adding a route is a deliberate platform change: a path
+ * that renders a surface but is missing here is a surface the merchant cannot
+ * switch on with any confidence.
+ */
+export const STOREFRONT_ROUTES = [
+    { path: "/products/:handle", surface: "product" },
+    { path: "/category/:slug", surface: "catalog" },
+    { path: "/pages/:slug", surface: "pages" },
+    { path: "/lp/:slug", surface: "landing" },
+    { path: "/checkout", surface: "checkout" },
+    { path: "/thank-you", surface: "thankYou" },
+];
+/**
+ * Whether the widget belongs on a pathname.
+ *
+ * The merchant answers "which surfaces" (`surfaces[surface]`); this function
+ * answers the platform half — which surface a pathname *is* — and it reads the
+ * contract above:
+ *
+ * - `/` → the home surface;
+ * - `/products` (the catalog index) and `/category/:slug` → the catalog surface;
+ * - `/products/:handle` → the product surface;
+ * - `/pages/:slug`, `/lp/:slug`, `/checkout`, `/thank-you` → their own surfaces;
+ * - anything else — a 404, `/productsomething`, `/checkout-success` — → no
+ *   surface at all, never a prefix match that leaks a widget onto a page the
+ *   merchant switched off.
+ */
+export function showsWidgetOn(surfaces, rawPathname) {
+    if (!surfaces)
+        return false;
+    // Normalise: strip query/hash, strip trailing slashes (except root "/")
+    const pathname = rawPathname.split("?")[0].split("#")[0].replace(/\/+$/, "") || "/";
+    if (pathname === "/") {
+        return Boolean(surfaces.home);
+    }
+    if (pathname === "/products" || pathname.startsWith("/category/")) {
+        return Boolean(surfaces.catalog);
+    }
+    if (pathname.startsWith("/products/")) {
+        const slug = pathname.slice("/products/".length);
+        return slug.length > 0 ? Boolean(surfaces.product) : Boolean(surfaces.catalog);
+    }
+    if (pathname === "/checkout") {
+        return Boolean(surfaces.checkout);
+    }
+    if (pathname === "/thank-you") {
+        return Boolean(surfaces.thankYou);
+    }
+    if (pathname.startsWith("/pages/")) {
+        const slug = pathname.slice("/pages/".length);
+        return slug.length > 0 ? Boolean(surfaces.pages) : false;
+    }
+    if (pathname.startsWith("/lp/")) {
+        const slug = pathname.slice("/lp/".length);
+        return slug.length > 0 ? Boolean(surfaces.landing) : false;
+    }
+    return false;
+}