@zalify/storefront-kit 0.1.0

package/dist/schemas/validate.js

@@ -0,0 +1,199 @@
+import { DEFAULT_MAX_BLOCKS, allowedChildTypes, isInputSetting, isLocalBlockDefinition, } from "./schema.js";
+function checkOrder(order, keys, path, issues) {
+    if (!order)
+        return;
+    const seen = new Set();
+    for (const key of order) {
+        if (seen.has(key)) {
+            issues.push({
+                path,
+                code: 'order-duplicate-key',
+                message: `"${key}" appears more than once in the order array`,
+            });
+        }
+        seen.add(key);
+        if (!keys || !(key in keys)) {
+            issues.push({
+                path,
+                code: 'order-unknown-key',
+                message: `order references "${key}" which has no entry`,
+            });
+        }
+    }
+}
+/** Local block definitions in a section's schema, keyed by type. */
+function localDefinitions(rules) {
+    const defs = {};
+    for (const rule of rules ?? []) {
+        if (isLocalBlockDefinition(rule)) {
+            defs[rule.type] = { name: rule.name, settings: rule.settings };
+        }
+    }
+    return defs;
+}
+function checkBlocks(parentPath, parentRules, parentMaxBlocks, blocks, blockOrder, ctx, issues) {
+    checkOrder(blockOrder, blocks, parentPath, issues);
+    if (!blocks)
+        return;
+    if (ctx) {
+        const allowed = allowedChildTypes(parentRules, ctx.allBlockTypes);
+        const localDefs = localDefinitions(parentRules);
+        const count = blockOrder?.length ?? Object.keys(blocks).length;
+        const cap = parentRules?.length
+            ? (parentMaxBlocks ?? DEFAULT_MAX_BLOCKS)
+            : 0;
+        if (count > cap) {
+            issues.push({
+                path: parentPath,
+                code: 'max-blocks-exceeded',
+                message: `${count} blocks exceed the allowed maximum of ${cap}`,
+            });
+        }
+        for (const [key, block] of Object.entries(blocks)) {
+            const blockPath = `${parentPath}.blocks.${key}`;
+            const schema = ctx.manifest.blocks[block.type] ?? localDefs[block.type];
+            if (!schema) {
+                issues.push({
+                    path: blockPath,
+                    code: 'unknown-type',
+                    message: `block type "${block.type}" is not in the manifest`,
+                });
+            }
+            else if (!allowed.includes(block.type)) {
+                issues.push({
+                    path: blockPath,
+                    code: 'block-not-allowed',
+                    message: `block type "${block.type}" is not allowed here`,
+                });
+            }
+            checkBlocks(blockPath, schema?.blocks, undefined, block.blocks, block.block_order, ctx, issues);
+        }
+    }
+    else {
+        for (const [key, block] of Object.entries(blocks)) {
+            checkBlocks(`${parentPath}.blocks.${key}`, undefined, undefined, block.blocks, block.block_order, null, issues);
+        }
+    }
+}
+/**
+ * Validate a template (or section group) against the L1 invariants,
+ * and — when a manifest is given — against the section/block schemas.
+ */
+export function validateTemplate(template, manifest) {
+    const issues = [];
+    const ctx = manifest
+        ? { manifest, allBlockTypes: Object.keys(manifest.blocks) }
+        : null;
+    checkOrder(template.order, template.sections, 'order', issues);
+    for (const [key, section] of Object.entries(template.sections ?? {})) {
+        const sectionPath = `sections.${key}`;
+        const schema = ctx?.manifest.sections[section.type];
+        if (ctx && !schema) {
+            issues.push({
+                path: sectionPath,
+                code: 'unknown-type',
+                message: `section type "${section.type}" is not in the manifest`,
+            });
+        }
+        checkBlocks(sectionPath, schema?.blocks, schema?.max_blocks, section.blocks, section.block_order, ctx, issues);
+    }
+    return issues;
+}
+function checkSettings(settings, path, issues) {
+    if (!settings)
+        return;
+    const ids = new Set();
+    for (const [index, setting] of settings.entries()) {
+        if (!isInputSetting(setting))
+            continue;
+        if (!setting.id) {
+            issues.push({
+                path: `${path}[${index}]`,
+                code: 'setting-missing-id',
+                message: `input setting of type "${setting.type}" has no id`,
+            });
+            continue;
+        }
+        if (ids.has(setting.id)) {
+            issues.push({
+                path: `${path}[${index}]`,
+                code: 'setting-duplicate-id',
+                message: `duplicate setting id "${setting.id}"`,
+            });
+        }
+        ids.add(setting.id);
+    }
+}
+/** Validate a manifest's own consistency. */
+export function validateManifest(manifest) {
+    const issues = [];
+    for (const field of [
+        'contractVersion',
+        'theme',
+        'sections',
+        'blocks',
+        'settingsSchema',
+        'templates',
+        'sectionGroups',
+        'locales',
+        'hash',
+    ]) {
+        if (manifest[field] === undefined || manifest[field] === null) {
+            issues.push({
+                path: field,
+                code: 'manifest-missing-field',
+                message: `manifest is missing "${field}"`,
+            });
+        }
+    }
+    const allBlockTypes = Object.keys(manifest.blocks ?? {});
+    for (const [type, section] of Object.entries(manifest.sections ?? {})) {
+        checkSettings(section.settings, `sections.${type}.settings`, issues);
+        for (const [ruleIndex, rule] of (section.blocks ?? []).entries()) {
+            if (isLocalBlockDefinition(rule)) {
+                checkSettings(rule.settings, `sections.${type}.blocks[${ruleIndex}].settings`, issues);
+            }
+            else if (rule.type !== '@theme' &&
+                rule.type !== '@app' &&
+                !allBlockTypes.includes(rule.type)) {
+                issues.push({
+                    path: `sections.${type}.blocks`,
+                    code: 'unknown-type',
+                    message: `block rule references unknown block type "${rule.type}"`,
+                });
+            }
+        }
+        for (const [index, preset] of (section.presets ?? []).entries()) {
+            const allowed = allowedChildTypes(section.blocks, allBlockTypes);
+            const walk = (blocks, rules, where) => {
+                for (const block of blocks ?? []) {
+                    if (!rules.includes(block.type)) {
+                        issues.push({
+                            path: where,
+                            code: 'block-not-allowed',
+                            message: `preset uses block type "${block.type}" which the parent does not allow`,
+                        });
+                    }
+                    const child = manifest.blocks[block.type];
+                    walk(block.blocks, allowedChildTypes(child?.blocks, allBlockTypes), where);
+                }
+            };
+            walk(preset.blocks, allowed, `sections.${type}.presets[${index}]`);
+        }
+    }
+    for (const [type, block] of Object.entries(manifest.blocks ?? {})) {
+        checkSettings(block.settings, `blocks.${type}.settings`, issues);
+        for (const rule of block.blocks ?? []) {
+            if (rule.type !== '@theme' &&
+                rule.type !== '@app' &&
+                !allBlockTypes.includes(rule.type)) {
+                issues.push({
+                    path: `blocks.${type}.blocks`,
+                    code: 'unknown-type',
+                    message: `block rule references unknown block type "${rule.type}"`,
+                });
+            }
+        }
+    }
+    return issues;
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@zalify/storefront-kit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The Zalify storefront SDK: framework-agnostic commerce logic (/commerce), the theme contract types and validators (/schemas), the canvas-editor bridge (/editor), and the React theme engine + shared components (/ui, /react/server). Consumed as TypeScript source inside the zalify-storefronts monorepo; published as compiled ESM + d.ts.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "sideEffects": false,
+  "exports": {
+    "./commerce": {
+      "types": "./dist/commerce/index.d.ts",
+      "default": "./dist/commerce/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "default": "./dist/schemas/index.js"
+    },
+    "./editor": {
+      "types": "./dist/editor/index.d.ts",
+      "default": "./dist/editor/index.js"
+    },
+    "./editor/frame": {
+      "types": "./dist/editor/frame.d.ts",
+      "default": "./dist/editor/frame.js"
+    },
+    "./editor/host": {
+      "types": "./dist/editor/host.d.ts",
+      "default": "./dist/editor/host.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./react/server": {
+      "types": "./dist/react/server.d.ts",
+      "default": "./dist/react/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^18.3.28",
+    "typescript": "^5.9.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zalify/zalify-theme-2026.git",
+    "directory": "packages/storefront-kit"
+  },
+  "homepage": "https://github.com/zalify/zalify-theme-2026/tree/main/packages/storefront-kit#readme",
+  "bugs": {
+    "url": "https://github.com/zalify/zalify-theme-2026/issues"
+  },
+  "keywords": [
+    "zalify",
+    "shopify",
+    "storefront",
+    "theme",
+    "hydrogen",
+    "nextjs",
+    "sections",
+    "headless",
+    "sdk"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "node --test \"src/schemas/*.test.ts\" \"src/editor/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/src/commerce/countdown.ts

@@ -0,0 +1,38 @@
+/**
+ * Countdown math shared by the theme's <countdown-timer> island and the
+ * React countdown block. Rendering (digit slots, hidden flips) stays in
+ * each runtime; only the clock logic lives here.
+ */
+
+/** Tolerant end-time parse — accepts ISO and "2026/08/01 00:00:00+0800". */
+export function parseEndTime(raw: string): number {
+  const direct = Date.parse(raw);
+  if (!Number.isNaN(direct)) return direct;
+  return Date.parse(raw.replaceAll('/', '-').replace(' ', 'T'));
+}
+
+/** Whole seconds remaining until `end` (epoch ms), floored at 0. */
+export function secondsUntil(end: number, now: number = Date.now()): number {
+  return Math.max(0, Math.floor((end - now) / 1000));
+}
+
+export interface CountdownParts {
+  days: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+}
+
+export function splitCountdown(remainSeconds: number): CountdownParts {
+  return {
+    days: Math.floor(remainSeconds / 86400),
+    hours: Math.floor(remainSeconds / 3600) % 24,
+    minutes: Math.floor(remainSeconds / 60) % 60,
+    seconds: remainSeconds % 60,
+  };
+}
+
+/** Two-digit display padding ("07"). */
+export function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}

package/src/commerce/events.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed pub/sub bus for cross-component state — THE event contract
+ * every storefront implementation speaks (the Liquid theme's islands
+ * and the React apps use the same names and payloads).
+ *
+ * Add new event names + payload shapes to ThemeEvents; both emit() and
+ * on() are checked against it. Keep payloads small and serializable —
+ * components should re-read the DOM or refetch, not sync big state here.
+ */
+import type {CardProduct} from './product';
+
+export interface ThemeEvents {
+  'cart:updated': {itemCount: number; sections?: Record<string, string>};
+  'cart:error': {message: string};
+  /** React runtimes: open the quick-add dialog for a product.
+      (The Liquid theme reaches its <dialog> directly instead.) */
+  'quick-add:open': {product: CardProduct};
+}
+
+/* SSR-safe: EventTarget exists in workers/Node 18+/browsers, but guard
+   anyway so importing this module can never throw at load time. */
+const bus: EventTarget | null =
+  typeof EventTarget === 'undefined' ? null : new EventTarget();
+
+export function emit<K extends keyof ThemeEvents>(
+  type: K,
+  detail: ThemeEvents[K],
+): void {
+  bus?.dispatchEvent(new CustomEvent(type, {detail}));
+}
+
+/** Subscribe. Returns an unsubscribe function; also accepts an AbortSignal. */
+export function on<K extends keyof ThemeEvents>(
+  type: K,
+  handler: (detail: ThemeEvents[K]) => void,
+  options?: {signal?: AbortSignal},
+): () => void {
+  if (!bus) return () => {};
+  const listener = (event: Event) =>
+    handler((event as CustomEvent<ThemeEvents[K]>).detail);
+  bus.addEventListener(type, listener, options);
+  return () => bus.removeEventListener(type, listener);
+}

package/src/commerce/facets.ts

@@ -0,0 +1,88 @@
+/**
+ * Facets (filter/sort) URL codec shared by every storefront:
+ *
+ * - cleanFormParams: form entries → clean query params (empty values
+ *   dropped) — the theme island's #formUrl and the React Facets form
+ *   both build their navigation URLs with it.
+ * - parseFilters/parseSort/parseSearchSort: URL → Storefront API
+ *   query inputs, used by the React apps' route loaders.
+ *
+ * URL contract (Hydrogen-skeleton style):
+ *   sort_by=<handle>            theme sort handle
+ *   filter.<key>=<json>         one param per applied Storefront filter
+ *     e.g. filter.variantOption={"name":"color","value":"Red"}
+ *          filter.price={"min":10,"max":50}
+ */
+
+/** Form entries → query params, dropping empty values. */
+export function cleanFormParams(
+  entries: Iterable<[string, FormDataEntryValue | string]>,
+): URLSearchParams {
+  const params = new URLSearchParams();
+  for (const [name, value] of entries) {
+    if (typeof value === 'string' && value !== '') params.append(name, value);
+  }
+  return params;
+}
+
+export type ProductFilterInput = Record<string, unknown>;
+
+export function parseFilters(
+  searchParams: URLSearchParams,
+): ProductFilterInput[] {
+  const filters: ProductFilterInput[] = [];
+  for (const [param, raw] of searchParams.entries()) {
+    if (!param.startsWith('filter.')) continue;
+    const key = param.slice('filter.'.length);
+    if (!key) continue;
+    let value: unknown = raw;
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      // plain-string filter values (e.g. tag) pass through as-is
+    }
+    filters.push({[key]: value});
+  }
+  return filters;
+}
+
+export interface SortSelection {
+  sortKey: string;
+  reverse: boolean;
+}
+
+const DEFAULT_SORT: SortSelection = {sortKey: 'MANUAL', reverse: false};
+
+const SORT_MAP: Record<string, SortSelection> = {
+  manual: DEFAULT_SORT,
+  'best-selling': {sortKey: 'BEST_SELLING', reverse: false},
+  'title-ascending': {sortKey: 'TITLE', reverse: false},
+  'title-descending': {sortKey: 'TITLE', reverse: true},
+  'price-ascending': {sortKey: 'PRICE', reverse: false},
+  'price-descending': {sortKey: 'PRICE', reverse: true},
+  'created-ascending': {sortKey: 'CREATED', reverse: false},
+  'created-descending': {sortKey: 'CREATED', reverse: true},
+};
+
+/** Collection pages: theme sort handle → ProductCollectionSortKeys. */
+export function parseSort(searchParams: URLSearchParams): SortSelection {
+  return SORT_MAP[searchParams.get('sort_by') ?? ''] ?? DEFAULT_SORT;
+}
+
+const DEFAULT_SEARCH_SORT: SortSelection = {
+  sortKey: 'RELEVANCE',
+  reverse: false,
+};
+
+const SEARCH_SORT_MAP: Record<string, SortSelection> = {
+  relevance: DEFAULT_SEARCH_SORT,
+  'price-ascending': {sortKey: 'PRICE', reverse: false},
+  'price-descending': {sortKey: 'PRICE', reverse: true},
+};
+
+/** Search page: theme sort handle → SearchSortKeys. */
+export function parseSearchSort(searchParams: URLSearchParams): SortSelection {
+  return (
+    SEARCH_SORT_MAP[searchParams.get('sort_by') ?? ''] ?? DEFAULT_SEARCH_SORT
+  );
+}

package/src/commerce/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @zalify/storefront-kit/commerce — framework-agnostic commerce logic shared by
+ * every Zalify storefront (Liquid theme islands, Hydrogen, Next.js…).
+ * Pure TypeScript: no DOM assumptions beyond web-standard globals, no
+ * React. Consumers bundle it as source.
+ */
+export * from './money';
+export * from './events';
+export * from './countdown';
+export * from './facets';
+export * from './product';

package/src/commerce/money.ts

@@ -0,0 +1,120 @@
+/**
+ * Money formatting for both storefront runtimes:
+ *
+ * - The Liquid theme's islands receive integer cents plus the shop's
+ *   money format string (window.Theme.moneyFormat) → formatMoneyCents.
+ * - React apps receive Storefront API Money objects → formatMoney.
+ */
+
+/** Money shape from the Storefront API. */
+export interface Money {
+  amount: string;
+  currencyCode: string;
+}
+
+export interface UnitPriceMeasurement {
+  referenceValue?: number | null;
+  referenceUnit?: string | null;
+}
+
+/**
+ * Format integer cents using a Shopify money format string
+ * (e.g. "${{amount}}") — mirror of Liquid's `| money` for client JS.
+ */
+export function formatMoneyCents(cents: number, format: string): string {
+  const amount = cents / 100;
+  return format.replace(/\{\{\s*(\w+)\s*\}\}/, (_, key: string) => {
+    switch (key) {
+      case 'amount_no_decimals':
+        return String(Math.round(amount));
+      case 'amount_with_comma_separator':
+        return amount.toFixed(2).replace('.', ',');
+      case 'amount_no_decimals_with_comma_separator':
+        return String(Math.round(amount));
+      default:
+        return amount.toFixed(2);
+    }
+  });
+}
+
+/** Format a Storefront API Money via Intl (drops .00 like the theme). */
+export function formatMoney(money: Money | null | undefined): string {
+  if (!money) return '';
+  const amount = Number(money.amount);
+  try {
+    return new Intl.NumberFormat('en', {
+      style: 'currency',
+      currency: money.currencyCode,
+      minimumFractionDigits: amount % 1 === 0 ? 0 : 2,
+    }).format(amount);
+  } catch {
+    return `${money.currencyCode} ${money.amount}`;
+  }
+}
+
+export function isOnSale(
+  price: Money | null | undefined,
+  compareAt: Money | null | undefined,
+): boolean {
+  if (!price || !compareAt) return false;
+  return Number(compareAt.amount) > Number(price.amount);
+}
+
+/** A discount allocation as the Storefront API returns it. */
+export interface DiscountAllocation {
+  /** CartCodeDiscountAllocation */
+  code?: string | null;
+  /** CartAutomaticDiscountAllocation / CartCustomDiscountAllocation */
+  title?: string | null;
+  discountedAmount?: Money | null;
+}
+
+export interface AggregatedDiscount {
+  label: string;
+  amount: Money;
+}
+
+/**
+ * Group Storefront API discount allocations by code/title and sum
+ * their amounts. The API returns cart-level `discountAllocations` as
+ * one entry per line the discount applies to (an order discount over
+ * four lines yields four allocations of the same code) — Liquid's
+ * `cart_level_discount_applications` comes pre-aggregated, and
+ * checkout shows one summed row per code. This is the React apps'
+ * equivalent for the cart/drawer summary rows.
+ */
+export function aggregateDiscountAllocations(
+  allocations: ReadonlyArray<DiscountAllocation> | null | undefined,
+): AggregatedDiscount[] {
+  const byLabel = new Map<
+    string,
+    {label: string; total: number; currencyCode: string}
+  >();
+  for (const allocation of allocations ?? []) {
+    const label = allocation.code ?? allocation.title ?? '';
+    const amount = Number(allocation.discountedAmount?.amount ?? 0);
+    const currencyCode = allocation.discountedAmount?.currencyCode ?? '';
+    const entry = byLabel.get(label);
+    if (entry) entry.total += amount;
+    else byLabel.set(label, {label, total: amount, currencyCode});
+  }
+  return [...byLabel.values()].map(({label, total, currencyCode}) => ({
+    label,
+    amount: {amount: total.toFixed(2), currencyCode},
+  }));
+}
+
+/**
+ * Mirror of Liquid's `unit_price_with_measurement` the way the theme's
+ * own JS formats it: "$4.99/100ml".
+ */
+export function formatUnitPrice(
+  unitPrice: Money,
+  measurement?: UnitPriceMeasurement | null,
+): string {
+  const referenceValue = measurement?.referenceValue ?? 1;
+  const referenceUnit = (measurement?.referenceUnit ?? '').toLowerCase();
+  const reference =
+    (referenceValue !== 1 ? String(referenceValue) : '') + referenceUnit;
+  return `${formatMoney(unitPrice)}/${reference}`;
+}