@weaverse/hydrogen 5.17.1 → 5.18.0

package/src/utils/index.ts

@@ -0,0 +1,351 @@
+import type { HydrogenEnv } from '@shopify/hydrogen'
+import type {
+  HydrogenComponent,
+  HydrogenComponentSchema,
+  HydrogenThemeSchema,
+  WeaverseLoaderData,
+  WeaverseProjectConfigs,
+  WeaverseStudioQueries,
+} from '../types'
+import { isTrustedStudioHost } from './studio-script-src'
+
+// Track warned types to avoid spam
+let warnedTypes = new Set<string>()
+
+function logOnce(type: string, message: string) {
+  if (!warnedTypes.has(type)) {
+    console.warn(message)
+    warnedTypes.add(type)
+  }
+}
+
+function deepMergeArrays<T>(target: T[], source: T[]): T[] {
+  return [...target, ...source]
+}
+
+function mergeInspectorSettings(
+  settings: any[],
+  inspector: any[],
+  type: string
+): any[] {
+  if (!inspector?.length) {
+    return settings
+  }
+  if (!settings?.length) {
+    return inspector
+  }
+
+  // Log collision notice
+  console.info(
+    `Schema "${type}": Both 'settings' and 'inspector' found. Using 'settings' with 'inspector' as fallback.`
+  )
+
+  return deepMergeArrays(settings, inspector)
+}
+
+/** Options for extracting query parameters from a request URL. */
+export interface RequestQueryOptions {
+  /** Query parameter names to include; all parameters are included when omitted. */
+  allowedKeys?: string[]
+}
+
+/**
+ * Extract and parse query parameters from a request URL.
+ * Supports optional allowlist for security-sensitive applications.
+ *
+ * @param request - The incoming request
+ * @param options - Optional configuration
+ * @param options.allowedKeys - If provided, only these keys will be extracted
+ * @returns Parsed query parameters with type coercion for booleans
+ *
+ * @example
+ * ```typescript
+ * // Extract all params
+ * const queries = getRequestQueries(request)
+ *
+ * // Extract only allowed params (security-sensitive)
+ * const queries = getRequestQueries(request, {
+ *   allowedKeys: ['weaverseProjectId', 'weaverseHost']
+ * })
+ * ```
+ */
+export function getRequestQueries<T = Record<string, string | boolean>>(
+  request: Request,
+  options?: RequestQueryOptions
+): T {
+  let url = new URL(request.url)
+  let queries: Record<string, unknown> = {}
+
+  for (let [key, value] of url.searchParams.entries()) {
+    // If allowlist provided, skip non-allowed keys
+    if (options?.allowedKeys && !options.allowedKeys.includes(key)) {
+      continue
+    }
+
+    // Type-safe conversion for known boolean patterns
+    if (value === 'true') {
+      queries[key] = true
+    } else if (value === 'false') {
+      queries[key] = false
+    } else {
+      queries[key] = value
+    }
+  }
+
+  return queries as T
+}
+
+/**
+ * Resolves project, endpoint, and Studio mode configuration for a request.
+ * URL-provided Studio values take precedence over environment defaults.
+ */
+export function getWeaverseConfigs(
+  request: Request,
+  env: HydrogenEnv
+): WeaverseProjectConfigs {
+  let queries = getRequestQueries<WeaverseStudioQueries>(request)
+  let {
+    WEAVERSE_PROJECT_ID,
+    WEAVERSE_API_KEY,
+    WEAVERSE_HOST,
+    WEAVERSE_PUBLIC_API_BASE,
+    PUBLIC_STORE_DOMAIN,
+    PUBLIC_STOREFRONT_API_TOKEN,
+  } = env || {}
+  let envFromProcess = (typeof process !== 'undefined' && process.env) || {}
+  let {
+    weaverseProjectId,
+    weaverseHost,
+    isDesignMode,
+    isPreviewMode,
+    sectionType,
+    weaverseVersion,
+    weaverseApiKey,
+  } = queries
+
+  let url = new URL(request.url)
+  let isRevisionPreview = url.searchParams.has('__revisionId')
+  let configuredWeaverseHost = WEAVERSE_HOST || envFromProcess.WEAVERSE_HOST
+  // `weaverseHost` arrives from the request URL (Studio drives the preview
+  // iframe with it), so it is attacker-controllable; only honor it when it is a
+  // trusted Weaverse origin, otherwise fall back to the env/default host. This
+  // stops a crafted `?weaverseHost=` from pointing Studio scripts or data reads
+  // at an arbitrary origin.
+  let trustedUrlHost =
+    typeof weaverseHost === 'string' && isTrustedStudioHost(weaverseHost)
+      ? weaverseHost
+      : ''
+  let resolvedWeaverseHost =
+    trustedUrlHost || configuredWeaverseHost || 'https://studio.weaverse.io'
+  // Public data reads default to the edge proxy, but an explicit custom
+  // WEAVERSE_HOST (staging/self-hosted Weaverse) must stay the API base so
+  // those deployments don't fetch page/config data from the production proxy.
+  let resolvedWeaverseApiBase = trustedUrlHost
+    ? trustedUrlHost
+    : WEAVERSE_PUBLIC_API_BASE ||
+      envFromProcess.WEAVERSE_PUBLIC_API_BASE ||
+      (configuredWeaverseHost &&
+      configuredWeaverseHost !== 'https://studio.weaverse.io'
+        ? configuredWeaverseHost
+        : 'https://api.weaverse.io')
+
+  return {
+    projectId:
+      weaverseProjectId ||
+      WEAVERSE_PROJECT_ID ||
+      envFromProcess.WEAVERSE_PROJECT_ID ||
+      '',
+    weaverseHost: resolvedWeaverseHost,
+    weaverseApiBase: resolvedWeaverseApiBase,
+    weaversePublicApiBase: resolvedWeaverseApiBase,
+    weaverseApiKey:
+      weaverseApiKey ||
+      WEAVERSE_API_KEY ||
+      envFromProcess.WEAVERSE_API_KEY ||
+      '',
+    weaverseVersion: weaverseVersion || '',
+    isDesignMode,
+    isPreviewMode,
+    isRevisionPreview,
+    sectionType: sectionType || '',
+    publicEnv: {
+      PUBLIC_STORE_DOMAIN: PUBLIC_STORE_DOMAIN || '',
+      PUBLIC_STOREFRONT_API_TOKEN: PUBLIC_STOREFRONT_API_TOKEN || '',
+    },
+  }
+}
+
+/**
+ * Cache for generateDataFromSchema results using WeakMap.
+ * WeakMap allows garbage collection when schema objects are no longer referenced.
+ */
+const schemaDefaultsCache = new WeakMap<
+  HydrogenComponentSchema | HydrogenThemeSchema,
+  Record<string, any>
+>()
+
+/**
+ * Generate default data from component or theme schema.
+ * Results are memoized using WeakMap for performance.
+ *
+ * @param schema - Component or theme schema
+ * @returns Default data object extracted from schema inputs
+ */
+export function generateDataFromSchema(
+  schema: HydrogenComponentSchema | HydrogenThemeSchema
+) {
+  // Check cache first for performance
+  const cached = schemaDefaultsCache.get(schema)
+  if (cached) {
+    return cached
+  }
+
+  let data: Record<string, any> = {}
+
+  // Handle migration from inspector to settings
+  let inspectorGroups: any[] = []
+
+  // Type guard to check if it's a component schema
+  const isComponentSchema = (
+    s: HydrogenComponentSchema | HydrogenThemeSchema
+  ): s is HydrogenComponentSchema => 'type' in s && typeof s.type === 'string'
+
+  if (isComponentSchema(schema)) {
+    // Handle HydrogenComponentSchema
+    if (schema.settings) {
+      inspectorGroups = schema.settings
+    }
+
+    if (schema.inspector) {
+      if (schema.settings?.length) {
+        // Both exist - merge with settings taking priority
+        inspectorGroups = mergeInspectorSettings(
+          schema.settings,
+          schema.inspector,
+          schema.type || 'unknown'
+        )
+      } else {
+        // Only inspector exists - use it but warn about deprecation
+        inspectorGroups = schema.inspector
+        if (schema.type) {
+          logOnce(
+            schema.type,
+            `⚠️  Schema "${schema.type}": The 'inspector' property is deprecated. Please use 'settings' instead.`
+          )
+        }
+      }
+    }
+  } else {
+    // Handle HydrogenThemeSchema
+    if (schema.settings) {
+      inspectorGroups = schema.settings
+    }
+
+    if (schema.inspector) {
+      if (schema.settings?.length) {
+        // Both exist - merge with settings taking priority
+        inspectorGroups = mergeInspectorSettings(
+          schema.settings,
+          schema.inspector,
+          'Theme Schema'
+        )
+      } else {
+        // Only inspector exists - use it but warn about deprecation
+        inspectorGroups = schema.inspector
+        logOnce(
+          'ThemeSchema',
+          `⚠️  Theme Schema: The 'inspector' property is deprecated. Please use 'settings' instead.`
+        )
+      }
+    }
+  }
+
+  if (inspectorGroups?.length) {
+    for (let group of inspectorGroups) {
+      for (let input of group.inputs) {
+        let { name, defaultValue } = input
+        if (name && defaultValue !== null && defaultValue !== undefined) {
+          data[name] = defaultValue
+        }
+      }
+    }
+  }
+
+  // Cache the result before returning
+  schemaDefaultsCache.set(schema, data)
+
+  return data
+}
+
+function recursivelyAddDataItem(
+  type: string,
+  components: HydrogenComponent<any>[],
+  items: any[],
+  initData?: object
+) {
+  let component = components.find((c) => c.schema.type === type)
+  if (!component) {
+    return
+  }
+  let childIds = []
+  let id = crypto.randomUUID()
+  let { children, ...data } = component.schema?.presets || {}
+  if (children) {
+    for (let c of children) {
+      let { type, children, ...data } = c
+      let childId = recursivelyAddDataItem(type, components, items, data)
+      childIds.push({ id: childId } as never)
+    }
+  }
+  items.push({
+    data: { ...data, ...initData },
+    id,
+    type,
+    children: childIds,
+  })
+  return id
+}
+
+/** Creates synthetic loader data for previewing one registered component type. */
+export function getPreviewData(
+  type: string,
+  components: HydrogenComponent[],
+  weaverseHost: string
+) {
+  let items = []
+  return {
+    project: { id: 'x', weaverseShopId: 'shop-id', name: 'Section Preview' },
+    configs: {
+      projectId: 'x',
+      weaverseHost,
+      isDesignMode: false,
+      isPreviewMode: true,
+      requestInfo: {
+        i18n: {
+          label: 'United States (USD $)',
+          language: 'EN',
+          country: 'US',
+          currency: 'USD',
+          pathPrefix: '',
+        },
+        queries: {},
+        pathname: '/',
+        search: '',
+      },
+    },
+    page: {
+      id: 'weaverse-preview-page',
+      name: 'Preview section',
+      rootId: '1',
+      items: [
+        {
+          data: {},
+          id: '1',
+          type: 'main',
+          children: [{ id: recursivelyAddDataItem(type, components, items) }],
+        },
+        ...items,
+      ],
+    },
+  } as unknown as WeaverseLoaderData
+}

package/src/utils/normalize-page-url.ts

@@ -0,0 +1,44 @@
+// Query params that influence Weaverse page resolution on the Builder:
+// revision previews, design-mode flags, and `weaverse*` control params
+// (host, version, project id). Everything else — utm_*, fbclid, gclid,
+// storefront filters — is irrelevant to which page the Builder returns.
+const KEPT_PARAM_RE = /^(?:__revisionId|isDesignMode|weaverse)/
+
+/**
+ * Normalize the storefront URL sent in the Builder page API request body.
+ *
+ * The POST body participates in the `withCache` cache key, so a raw
+ * `request.url` fragments the cache by every marketing/tracking param:
+ * each distinct `?utm_…`/`fbclid` URL is a guaranteed Builder round-trip
+ * even when the resolved page is identical — precisely the paid/social
+ * traffic that needs the cache most (builder#2450).
+ *
+ * The Builder reads only the pathname (locale/type/handle fallback) and
+ * the params matched above from this URL, so keep exactly those. Params
+ * are sorted for a stable cache key regardless of their order in the
+ * incoming URL.
+ */
+export function normalizePageUrl(url: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    // Not an absolute URL (shouldn't happen for request.url) — send as-is.
+    return url
+  }
+  const kept = [...parsed.searchParams].filter(([key]) =>
+    KEPT_PARAM_RE.test(key)
+  )
+  kept.sort(([a], [b]) => a.localeCompare(b))
+  const search = new URLSearchParams(kept).toString()
+  // React Router single-fetch requests loader data from `/<path>.data`, which
+  // resolves to the same Builder page as `/<path>`. Strip the suffix so a
+  // client navigation and a document load hash to one edge-cache key (the
+  // api.weaverse.io worker keys on this url) instead of two — keeping a page's
+  // first client navigation off the cold-MISS path.
+  let { pathname } = parsed
+  if (pathname.endsWith('.data')) {
+    pathname = pathname.slice(0, -'.data'.length)
+  }
+  return `${parsed.origin}${pathname}${search ? `?${search}` : ''}`
+}

package/src/utils/pick-weaverse-data.ts

@@ -0,0 +1,89 @@
+import type { UIMatch } from 'react-router'
+import type { WeaverseLoaderData } from '../types'
+
+/**
+ * Weaverse page data accepted by {@link WeaverseHydrogenRoot}, including
+ * deferred React Router loader results and an explicit no-render value.
+ */
+export type WeaverseDataValue =
+  | WeaverseLoaderData
+  | Promise<WeaverseLoaderData>
+  | null
+
+/**
+ * Resolve the `weaverseData` payload for a `<WeaverseHydrogenRoot>` instance.
+ *
+ * Resolution order (first match wins):
+ *
+ *  1. **Explicit prop** — the caller passed `data` directly. Used as-is,
+ *     including when it is a `Promise` (handled upstream via `<Await>`) or
+ *     an explicit `null` (suppresses rendering).
+ *  2. **Own route's loader data** — the loader data for the route that
+ *     rendered this component, obtained via `useLoaderData()`. This is
+ *     React Router's route-scoped primitive and is what makes nested
+ *     layout + child Weaverse pages work: each `<WeaverseContent />`
+ *     resolves to *its own* route's `weaverseData` regardless of siblings.
+ *  3. **Ancestor match fallback** — walk `useMatches()` from leaf to root
+ *     and return the first ancestor whose `loaderData` exposes a
+ *     `weaverseData` key. This preserves the long-standing behaviour where
+ *     a child route with no loader (e.g. an `index.tsx` that omits
+ *     `weaverseData`) still renders its layout's Weaverse page.
+ *
+ * The helper is intentionally pure (no hook calls) so it can be unit-tested
+ * without a React Router context. Hook calls happen in the component.
+ *
+ * ## Back-compat contract
+ *
+ * Themes that pre-date the `data` prop addition pass `dataProp === undefined`,
+ * so resolution starts at Tier 2. For the canonical single-instance pattern
+ * (one `<WeaverseContent />` inside a route whose loader returns
+ * `{ weaverseData }`), Tier 2 returns the same value the old `useMatches()`
+ * walk did. For the index-without-loader pattern (leaf route exposes no
+ * `weaverseData`, layout does), Tier 3's leaf→root walk produces an
+ * identical result to the pre-fix code. The only intentional behaviour
+ * change is the issue #451 case: two `<WeaverseContent />` instances on the
+ * same URL (layout + child, both with their own `weaverseData`) now each
+ * render their own page instead of both rendering the deepest one.
+ */
+export function pickWeaverseData(
+  dataProp: WeaverseDataValue | undefined,
+  ownLoaderData: unknown,
+  matches: ReadonlyArray<Pick<UIMatch, 'loaderData'>>
+): WeaverseDataValue {
+  // Tier 1: explicit prop wins (including explicit `null`).
+  if (dataProp !== undefined) {
+    return dataProp
+  }
+
+  // Tier 2: own route's loader data — the route-scoped primitive.
+  if (hasWeaverseData(ownLoaderData)) {
+    return ownLoaderData.weaverseData as WeaverseDataValue
+  }
+
+  // Tier 3: ancestor walk (leaf → root) for legacy / index-without-loader cases.
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const loaderData = matches[i].loaderData
+    if (hasWeaverseData(loaderData)) {
+      return loaderData.weaverseData as WeaverseDataValue
+    }
+  }
+
+  return null
+}
+
+function hasWeaverseData(
+  value: unknown
+): value is Record<string, unknown> & { weaverseData: unknown } {
+  // The `in` check alone returns true for `{ weaverseData: undefined }`,
+  // which would let Tier 2 short-circuit and return `undefined` — bypassing
+  // the Tier 3 ancestor walk that would otherwise resolve the missing data.
+  // Require the value to be present (not `undefined`).
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !('weaverseData' in (value as Record<string, unknown>))
+  ) {
+    return false
+  }
+  return (value as Record<string, unknown>).weaverseData !== undefined
+}

package/src/utils/pixel.ts

@@ -0,0 +1,71 @@
+// One pixel per page per navigation. A few facts shape the dedup:
+//
+// 1. Co-located instances: nested compositions mount multiple Weaverse
+//    instances on one URL; each page is counted at most once.
+// 2. The pixel FIRE effect runs once per instance mount (see `usePixel`), so
+//    an instance never re-fires on its own — a navigation is a fresh mount.
+// 3. `location.key` is stable per history entry. A back/forward POP restores
+//    the entry's ORIGINAL key, and an in-place remount on the same entry
+//    (e.g. the `data={null}` suppress/restore path in WeaverseHydrogenRoot)
+//    keeps that same key. A REAL navigation is therefore a key CHANGE.
+//
+// `firedPageIds` is the set of pages already counted for the current
+// navigation. It is forgotten in two ways:
+//   - On a key TRANSITION reported by ANY mounted instance via
+//     `observeNavigation` (driven by a per-navigation effect). A persistent
+//     layout-level instance keeps observing across a detour through a
+//     non-Weaverse route (cart, search, account), so a Back to the original
+//     entry is recognised as a new navigation and the page re-counts — while
+//     an in-place suppress/restore (no key change) does NOT re-count.
+//   - When the LAST instance unmounts (`registerPixelInstance`), covering the
+//     detour case where no instance survives to observe the key round-trip
+//     (a page with no persistent layout going to /cart and back).
+//
+// Known tradeoff: React StrictMode's dev-only mount→cleanup→mount cycle
+// resets state and double-fires in development — parity with the pre-dedupe
+// behavior; production semantics are unaffected.
+let currentNavigationKey: string | null = null
+let firedPageIds = new Set<string>()
+let mountedInstances = 0
+
+/**
+ * Record the navigation key seen by a mounted instance. A change of key is a
+ * real navigation and forgets the previous navigation's fired pages; an
+ * unchanged key (an in-place remount / suppress-restore on the same history
+ * entry) leaves them intact, so the page is not double-counted.
+ */
+export function observeNavigation(navigationKey: string): void {
+  if (navigationKey !== currentNavigationKey) {
+    currentNavigationKey = navigationKey
+    firedPageIds.clear()
+  }
+}
+
+export function shouldFirePixel(
+  navigationKey: string,
+  pageId: string
+): boolean {
+  observeNavigation(navigationKey)
+  if (firedPageIds.has(pageId)) {
+    return false
+  }
+  firedPageIds.add(pageId)
+  return true
+}
+
+/**
+ * Track a mounted Weaverse instance; returns the unmount cleanup. When the
+ * last instance unmounts, the navigation state is forgotten so a Back that
+ * restores the same history entry counts again even if no instance survived
+ * to observe the detour.
+ */
+export function registerPixelInstance(): () => void {
+  mountedInstances += 1
+  return () => {
+    mountedInstances -= 1
+    if (mountedInstances === 0) {
+      currentNavigationKey = null
+      firedPageIds.clear()
+    }
+  }
+}

package/src/utils/studio-request-info.ts

@@ -0,0 +1,66 @@
+import type { WeaverseHydrogenParams } from '../types'
+
+interface BrowserLocationLike {
+  pathname: string
+  search: string
+}
+
+function getBrowserLocation(): BrowserLocationLike | undefined {
+  if (typeof window === 'undefined') {
+    return
+  }
+  return window.location
+}
+
+function getQueriesFromSearch(
+  search: string
+): Record<string, string | boolean> {
+  let queries: Record<string, string | boolean> = {}
+  let params = new URLSearchParams(search)
+  for (let [key, value] of params.entries()) {
+    if (value === 'true') {
+      queries[key] = true
+    } else if (value === 'false') {
+      queries[key] = false
+    } else {
+      queries[key] = value
+    }
+  }
+  return queries
+}
+
+/**
+ * React Router v7 single-fetch revalidation can render client data returned
+ * from a `*.data` request while the browser is still on the canonical URL.
+ * Instance identity must follow the browser URL, not the transient data
+ * endpoint, otherwise the SDK creates a fresh Weaverse instance mid-session:
+ * in design mode that drops the existing Studio bridge/interactions, and in
+ * the live theme it resets every section's runtime state after any
+ * revalidation (cart mutations, locale switches, `revalidate()`). See #451.
+ */
+export function normalizeRequestInfo(
+  params: WeaverseHydrogenParams,
+  browserLocation: BrowserLocationLike | undefined = getBrowserLocation()
+): WeaverseHydrogenParams {
+  if (!browserLocation) {
+    return params
+  }
+
+  let { pathname, search } = browserLocation
+  if (
+    params.requestInfo.pathname === pathname &&
+    params.requestInfo.search === search
+  ) {
+    return params
+  }
+
+  return {
+    ...params,
+    requestInfo: {
+      ...params.requestInfo,
+      pathname,
+      queries: getQueriesFromSearch(search),
+      search,
+    },
+  }
+}