@zalify/storefront-kit 0.1.0

package/src/react/server.ts

@@ -0,0 +1,60 @@
+/**
+ * Server side of the section engine (import from '@zalify/storefront-kit/react/server').
+ * Route loaders run the registered per-section-type loaders for a
+ * template and pass the result to <ThemeTemplate sectionData={…}/>.
+ */
+import {getSectionGroup, getTemplate, getThemeStore} from './engine/store';
+import type {SectionLoaderArgs, TemplateData} from './engine/types';
+
+export {builtinSectionLoaders} from './registries.server';
+
+type LoaderContext = Omit<
+  SectionLoaderArgs,
+  'settings' | 'section' | 'sectionId'
+>;
+
+async function runLoaders(
+  template: TemplateData,
+  context: LoaderContext,
+): Promise<Record<string, unknown>> {
+  const loaders = getThemeStore().sectionLoaders ?? {};
+  const entries = await Promise.all(
+    template.order.map(async (sectionId) => {
+      const section = template.sections[sectionId];
+      if (!section || section.disabled) return null;
+      const loader = loaders[section.type];
+      if (!loader) return null;
+      try {
+        const data = await loader({
+          ...context,
+          settings: section.settings ?? {},
+          section,
+          sectionId,
+        });
+        return [sectionId, data] as const;
+      } catch (error) {
+        // A failing section must not take down the page.
+        // eslint-disable-next-line no-console
+        console.error(`[theme] loader for section "${sectionId}" failed`, error);
+        return null;
+      }
+    }),
+  );
+  return Object.fromEntries(entries.filter(Boolean) as [string, unknown][]);
+}
+
+/** Run all section loaders for a page template. */
+export async function loadSectionData(
+  templateName: string,
+  context: LoaderContext,
+): Promise<Record<string, unknown>> {
+  return runLoaders(getTemplate(templateName), context);
+}
+
+/** Run all section loaders for a section group (header/footer/overlay). */
+export async function loadGroupSectionData(
+  groupName: string,
+  context: LoaderContext,
+): Promise<Record<string, unknown>> {
+  return runLoaders(getSectionGroup(groupName), context);
+}

package/src/schemas/bridge.ts

@@ -0,0 +1,143 @@
+/**
+ * L3 — Canvas-editor bridge protocol.
+ *
+ * postMessage contract between the Zalify canvas editor (host) and a
+ * theme preview running on another origin inside an iframe (frame).
+ * Both sides validate `event.origin` and the message envelope before
+ * acting; versions negotiate on CONTRACT_VERSION's major component.
+ */
+import type {SectionGroupData, SettingsBag, TemplateData} from './data.ts';
+import type {ThemeEditorManifest} from './manifest.ts';
+
+export const BRIDGE_NAMESPACE = 'zalify-editor-bridge';
+
+/** Query param that switches a theme preview into editor mode. */
+export const EDITOR_MODE_PARAM = 'zalify-editor';
+
+/** DOM attribute carrying a node's theme-JSON path (wire format). */
+export const DATA_PATH_ATTR = 'data-z-path';
+/** DOM attribute the bridge sets on the selected node. */
+export const DATA_SELECTED_ATTR = 'data-z-selected';
+
+export type Device = 'desktop' | 'mobile';
+
+export interface DOMRectLike {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/* ------------------------------ paths ------------------------------ */
+
+/** Locates a section or block inside a template or section group. */
+export interface ThemeJsonPath {
+  scope: {kind: 'template' | 'group'; name: string};
+  sectionKey: string;
+  /** Nested block keys, outermost first; empty = the section itself. */
+  blockKeys: string[];
+}
+
+/**
+ * Wire format: "template:index/hero/slide/box", "group:header-group/header".
+ * Every segment is URI-component-encoded so names containing "/" stay
+ * unambiguous (customer templates are named "customers/login").
+ */
+export function formatThemePath(path: ThemeJsonPath): string {
+  return [
+    `${path.scope.kind}:${encodeURIComponent(path.scope.name)}`,
+    encodeURIComponent(path.sectionKey),
+    ...path.blockKeys.map(encodeURIComponent),
+  ].join('/');
+}
+
+export function parseThemePath(wire: string): ThemeJsonPath | null {
+  const [scopePart, sectionKey, ...blockKeys] = wire.split('/');
+  if (!scopePart || !sectionKey) return null;
+  const colon = scopePart.indexOf(':');
+  if (colon === -1) return null;
+  const kind = scopePart.slice(0, colon);
+  const name = scopePart.slice(colon + 1);
+  if ((kind !== 'template' && kind !== 'group') || !name) return null;
+  return {
+    scope: {kind, name: decodeURIComponent(name)},
+    sectionKey: decodeURIComponent(sectionKey),
+    blockKeys: blockKeys.map(decodeURIComponent),
+  };
+}
+
+/* ---------------------------- envelope ----------------------------- */
+
+export interface BridgeEnvelope<TType extends string, TPayload> {
+  z: typeof BRIDGE_NAMESPACE;
+  /** CONTRACT_VERSION of the sender. */
+  v: string;
+  type: TType;
+  payload: TPayload;
+}
+
+/* ------------------------- host -> frame ---------------------------- */
+
+export type HostMessage =
+  | BridgeEnvelope<
+      'bridge:init',
+      {
+        editorOrigin: string;
+        device: Device;
+        selectedPath: string | null;
+      }
+    >
+  | BridgeEnvelope<'block:select', {path: string | null}>
+  | BridgeEnvelope<'block:hover', {path: string | null}>
+  | BridgeEnvelope<'block:scroll-to', {path: string}>
+  | BridgeEnvelope<
+      'template:apply',
+      {
+        templateName: string;
+        template: TemplateData;
+        groups?: Record<string, SectionGroupData>;
+        settingsData?: SettingsBag;
+      }
+    >
+  | BridgeEnvelope<'device:set', {device: Device}>
+  | BridgeEnvelope<'manifest:request', Record<string, never>>;
+
+/* ------------------------- frame -> host ---------------------------- */
+
+export type FrameMessage =
+  | BridgeEnvelope<
+      'bridge:ready',
+      {contractVersion: string; templateName: string; hash: string}
+    >
+  | BridgeEnvelope<'block:clicked', {path: string; rect: DOMRectLike}>
+  | BridgeEnvelope<'block:hovered', {path: string | null; rect?: DOMRectLike}>
+  | BridgeEnvelope<
+      'block:rects',
+      {rects: Array<{path: string; rect: DOMRectLike}>}
+    >
+  | BridgeEnvelope<'manifest:response', {manifest: ThemeEditorManifest}>
+  | BridgeEnvelope<'template:synced', {hash: string}>
+  | BridgeEnvelope<'height:changed', {height: number}>
+  | BridgeEnvelope<'navigation', {templateName: string; url: string}>
+  | BridgeEnvelope<'bridge:error', {code: string; message: string}>;
+
+export type BridgeMessage = HostMessage | FrameMessage;
+
+/* ----------------------------- guards ------------------------------- */
+
+export function isBridgeMessage(data: unknown): data is BridgeMessage {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    (data as {z?: unknown}).z === BRIDGE_NAMESPACE &&
+    typeof (data as {v?: unknown}).v === 'string' &&
+    typeof (data as {type?: unknown}).type === 'string' &&
+    typeof (data as {payload?: unknown}).payload === 'object' &&
+    (data as {payload?: unknown}).payload !== null
+  );
+}
+
+/** Same-major = compatible; anything else degrades to read-only preview. */
+export function isCompatibleVersion(mine: string, theirs: string): boolean {
+  return mine.split('.')[0] === theirs.split('.')[0];
+}

package/src/schemas/data.ts

@@ -0,0 +1,72 @@
+/**
+ * L1 — Theme data contract.
+ *
+ * The runtime JSON shapes of a Zalify theme, byte-compatible with
+ * Shopify OS 2.0 theme JSON (templates/*.json, sections/*-group.json,
+ * config/settings_data.json). These are the canonical definitions;
+ * @zalify/storefront-kit/react's engine types mirror them and will re-export from
+ * here as the packages converge.
+ */
+
+/** A section's or block's settings: setting id -> value. */
+export type SettingsBag = Record<string, unknown>;
+
+/** A block instance inside a section (or nested inside another block). */
+export interface BlockData {
+  type: string;
+  settings?: SettingsBag;
+  /** Nested blocks keyed by their stable key. */
+  blocks?: Record<string, BlockData>;
+  /** Render order of `blocks` keys. */
+  block_order?: string[];
+  disabled?: boolean;
+}
+
+/** A section instance inside a template or section group. */
+export interface SectionData {
+  type: string;
+  settings?: SettingsBag;
+  blocks?: Record<string, BlockData>;
+  block_order?: string[];
+  disabled?: boolean;
+  custom_css?: string[];
+}
+
+/** templates/*.json — a page template. */
+export interface TemplateData {
+  layout?: string | false;
+  wrapper?: string;
+  /** Sections keyed by their stable key. */
+  sections: Record<string, SectionData>;
+  /** Render order of `sections` keys. */
+  order: string[];
+}
+
+/** sections/*-group.json — header/footer/overlay section groups. */
+export interface SectionGroupData extends TemplateData {
+  type: string;
+  name: string;
+}
+
+/** config/settings_data.json — current values for global theme settings. */
+export interface SettingsData {
+  current: string | Record<string, unknown>;
+  presets?: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Parse theme JSON that may carry Shopify's leading block comment
+ * (the theme editor writes templates/*.json with a header comment).
+ */
+export function parseThemeJson<T>(raw: string, name = 'theme JSON'): T {
+  const stripped = raw.replace(/^\s*\/\*[\s\S]*?\*\//, '').trim();
+  try {
+    return JSON.parse(stripped) as T;
+  } catch (error) {
+    throw new Error(
+      `[storefront-kit] Failed to parse ${name}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}

package/src/schemas/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @zalify/storefront-kit/schemas — the Zalify theme contract.
+ *
+ * L1 (data.ts):     runtime theme JSON shapes, = Shopify OS 2.0.
+ * L2 (schema.ts):   section/block schema types, = `{% schema %}` semantics.
+ *    (manifest.ts): the generated editor manifest tying L2 together.
+ * L3 (bridge.ts):   the canvas-editor postMessage protocol.
+ * validate.ts:      structural + schema-aware validators.
+ */
+export * from './data.ts';
+export * from './schema.ts';
+export * from './manifest.ts';
+export * from './bridge.ts';
+export * from './validate.ts';

package/src/schemas/manifest.ts

@@ -0,0 +1,85 @@
+/**
+ * The editor manifest: everything the canvas editor needs to drive its
+ * Insert/Layers/Config panels without executing theme code. Generated
+ * into the theme (and every scaffolded project) by `pnpm sync` as
+ * config/editor-manifest.generated.json; served live by the editor
+ * bridge as `manifest:response`.
+ */
+import type {SectionSchema, SettingDefinition, ThemeBlockSchema} from './schema.ts';
+
+/**
+ * Contract version spoken by this package. Bumped with the package;
+ * editors negotiate compatibility on the major component.
+ */
+export const CONTRACT_VERSION = '0.1.0';
+
+/** Repo-relative path of the generated manifest inside a theme/project. */
+export const EDITOR_MANIFEST_PATH = 'config/editor-manifest.generated.json';
+
+export interface SectionManifestEntry extends SectionSchema {
+  /**
+   * True when the section has a server-side data loader; settings
+   * changes may render stale until the file write round-trips.
+   * Enriched at runtime by the bridge (sync.mjs cannot know).
+   */
+  hasLoader?: boolean;
+}
+
+export interface ThemeEditorManifest {
+  /** Provenance note ("scripts/sync.mjs — do not edit…"). */
+  generatedBy?: string;
+  contractVersion: string;
+  theme: {name: string; version: string};
+  /** Section schemas keyed by section type. */
+  sections: Record<string, SectionManifestEntry>;
+  /** Theme block schemas keyed by block type (includes "_" private blocks). */
+  blocks: Record<string, ThemeBlockSchema>;
+  /** = config/settings_schema.json (global theme settings). */
+  settingsSchema: Array<{
+    name: string;
+    theme_name?: string;
+    theme_version?: string;
+    settings?: SettingDefinition[];
+    [key: string]: unknown;
+  }>;
+  /** Editable template names ("index", "product", "customers/login", …). */
+  templates: string[];
+  /** Section group names ("header-group", "footer-group", …). */
+  sectionGroups: string[];
+  /** Flattened "t:" key -> display copy for the editor's locale. */
+  locales: Record<string, string>;
+  /** Content hash of everything above, for snapshot/bridge consistency. */
+  hash: string;
+}
+
+/**
+ * Resolve a "t:"-prefixed locale key against the manifest's flattened
+ * locales; plain strings pass through.
+ */
+export function resolveLocale(
+  value: string,
+  locales: Record<string, string>,
+): string {
+  if (!value.startsWith('t:')) return value;
+  return locales[value.slice(2)] ?? value;
+}
+
+/**
+ * Flatten a nested locale-schema object ({labels: {text: "Text"}}) into
+ * "labels.text" -> "Text" pairs, the form `ThemeEditorManifest.locales`
+ * carries.
+ */
+export function flattenLocales(
+  tree: Record<string, unknown>,
+  prefix = '',
+  out: Record<string, string> = {},
+): Record<string, string> {
+  for (const [key, value] of Object.entries(tree)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === 'string') out[path] = value;
+    else if (value && typeof value === 'object') {
+      flattenLocales(value as Record<string, unknown>, path, out);
+    }
+  }
+  return out;
+}

package/src/schemas/schema.ts

@@ -0,0 +1,287 @@
+/**
+ * L2 — Theme schema contract.
+ *
+ * The editor-facing description of sections and blocks: what Shopify
+ * carries in a section's `{% schema %}` tag. Field semantics follow
+ * Shopify OS 2.0 exactly; this file only gives them an explicit,
+ * React-side home (components export these objects, and sync.mjs
+ * mirrors them out of the Liquid theme's `{% schema %}` tags).
+ */
+import type {BlockData, SectionData, SettingsBag} from './data.ts';
+
+/* ------------------------- setting definitions ------------------------- */
+
+/**
+ * Shopify input setting types, grouped by the tier in which the Zalify
+ * canvas editor implements them. Unknown/future types must degrade to a
+ * read-only display in the editor — never an error, never value loss.
+ */
+export const SETTING_TYPE_TIERS = {
+  /** Phase 1 — must render as editable fields. */
+  t0: [
+    'text',
+    'textarea',
+    'richtext',
+    'inline_richtext',
+    'number',
+    'range',
+    'checkbox',
+    'select',
+    'radio',
+    'color',
+    'image_picker',
+    'url',
+    'text_alignment',
+  ],
+  /** Phase 1.5 — theme-level pickers. */
+  t1: [
+    'font_picker',
+    'color_background',
+    'color_scheme',
+    'color_scheme_group',
+    'video_url',
+    'html',
+    'link_list',
+  ],
+  /** Phase 2 — resource pickers backed by storefront data. */
+  t2: [
+    'product',
+    'product_list',
+    'collection',
+    'collection_list',
+    'blog',
+    'article',
+    'page',
+    'metaobject',
+    'video',
+  ],
+  /** Liquid-only; React themes preserve the value but never render it. */
+  notApplicable: ['liquid'],
+} as const;
+
+export type KnownInputSettingType =
+  | (typeof SETTING_TYPE_TIERS.t0)[number]
+  | (typeof SETTING_TYPE_TIERS.t1)[number]
+  | (typeof SETTING_TYPE_TIERS.t2)[number]
+  | (typeof SETTING_TYPE_TIERS.notApplicable)[number];
+
+export const SIDEBAR_SETTING_TYPES = ['header', 'paragraph'] as const;
+export type SidebarSettingType = (typeof SIDEBAR_SETTING_TYPES)[number];
+
+/** Non-input schema entries (group headers / help copy). */
+export interface SidebarSetting {
+  type: SidebarSettingType;
+  content: string;
+  /** Shopify conditional-visibility expression. */
+  visible_if?: string;
+}
+
+export interface SettingOption {
+  value: string;
+  label: string;
+  group?: string;
+}
+
+/**
+ * An input setting definition. One open shape rather than a closed
+ * discriminated union: this mirrors the JSON reality (Shopify adds
+ * setting types over time) and keeps older editors forward-compatible.
+ * Type-specific fields are optional and only meaningful for the types
+ * that define them (`options` for select/radio, `min`/`max`/`step`/
+ * `unit` for range, `placeholder` for text-likes, …).
+ */
+export interface InputSetting {
+  type: KnownInputSettingType | (string & {});
+  /** Key in the instance's settings bag. */
+  id: string;
+  /** Supports "t:" locale keys. */
+  label: string;
+  info?: string;
+  default?: unknown;
+  visible_if?: string;
+  placeholder?: string;
+  options?: SettingOption[];
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  /** range-style sliders on newer setting types. */
+  accept?: string[];
+}
+
+export type SettingDefinition = InputSetting | SidebarSetting;
+
+export function isSidebarSetting(
+  setting: SettingDefinition,
+): setting is SidebarSetting {
+  return (SIDEBAR_SETTING_TYPES as readonly string[]).includes(setting.type);
+}
+
+export function isInputSetting(
+  setting: SettingDefinition,
+): setting is InputSetting {
+  return !isSidebarSetting(setting);
+}
+
+/* --------------------------- section schemas --------------------------- */
+
+/** Which block types a section (or block) accepts as children. */
+export interface BlockRule {
+  /**
+   * A concrete block type, or a wildcard: "@theme" (all public theme
+   * blocks — types not starting with "_"), "@app" (app blocks).
+   */
+  type: string;
+  limit?: number;
+}
+
+/**
+ * A section-local block defined inline in the section's schema
+ * (Shopify OS 2.0 "section blocks"): the entry carries `name` (and
+ * usually `settings`) instead of referencing a theme block. Local
+ * blocks cannot nest further blocks.
+ */
+export interface LocalBlockDefinition extends BlockRule {
+  name: string;
+  settings?: SettingDefinition[];
+}
+
+/** An entry in a section schema's `blocks` array: reference or inline. */
+export type SectionBlockEntry = BlockRule | LocalBlockDefinition;
+
+export function isLocalBlockDefinition(
+  entry: SectionBlockEntry,
+): entry is LocalBlockDefinition {
+  return 'name' in entry && typeof entry.name === 'string';
+}
+
+export interface PresetBlock {
+  type: string;
+  settings?: SettingsBag;
+  blocks?: PresetBlock[];
+  /** Static preset blocks may pin their key (Shopify allows both forms). */
+  id?: string;
+}
+
+/** An "add section" catalog entry in the editor. */
+export interface SectionPreset {
+  name: string;
+  settings?: SettingsBag;
+  blocks?: PresetBlock[];
+  /** Zalify extension: insert-panel grouping. */
+  category?: string;
+}
+
+export interface TemplateAvailability {
+  templates?: string[];
+  groups?: string[];
+}
+
+/**
+ * = Shopify OS 2.0 section schema, minus Liquid-rendering concerns
+ * (tag/class/javascript/stylesheet stay in the Liquid theme).
+ */
+export interface SectionSchema {
+  /** Supports "t:" locale keys. */
+  name: string;
+  settings?: SettingDefinition[];
+  /** Allowed child blocks (references or local definitions); absent = none. */
+  blocks?: SectionBlockEntry[];
+  /** Defaults to Shopify's cap of 50 when blocks are allowed. */
+  max_blocks?: number;
+  /** Per-template instance cap (e.g. 1 for header-like sections). */
+  limit?: number;
+  /** No presets = not manually insertable (main-* sections). */
+  presets?: SectionPreset[];
+  default?: Pick<SectionData, 'settings' | 'blocks' | 'block_order'>;
+  enabled_on?: TemplateAvailability;
+  disabled_on?: TemplateAvailability;
+}
+
+/** = Shopify OS 2.0 theme block schema (blocks/*.liquid `{% schema %}`). */
+export interface ThemeBlockSchema {
+  name: string;
+  settings?: SettingDefinition[];
+  /** Theme blocks may nest blocks themselves. */
+  blocks?: BlockRule[];
+  presets?: Array<{
+    name: string;
+    settings?: SettingsBag;
+    blocks?: PresetBlock[];
+  }>;
+}
+
+/** Shopify's default max_blocks when a section allows blocks. */
+export const DEFAULT_MAX_BLOCKS = 50;
+
+/** Block types starting with "_" are private to their section. */
+export function isPrivateBlockType(type: string): boolean {
+  return type.startsWith('_');
+}
+
+/**
+ * Resolve a parent's block rules against the full block registry:
+ * which concrete child types may be inserted?
+ */
+export function allowedChildTypes(
+  rules: SectionBlockEntry[] | undefined,
+  allBlockTypes: string[],
+): string[] {
+  if (!rules?.length) return [];
+  const allowed = new Set<string>();
+  for (const rule of rules) {
+    if (rule.type === '@theme') {
+      for (const type of allBlockTypes) {
+        if (!isPrivateBlockType(type)) allowed.add(type);
+      }
+    } else if (rule.type !== '@app') {
+      allowed.add(rule.type);
+    }
+  }
+  return [...allowed];
+}
+
+/** Instantiate a preset's block list into named-map + order form. */
+export function instantiatePresetBlocks(
+  presetBlocks: PresetBlock[] | undefined,
+): Pick<BlockData, 'blocks' | 'block_order'> {
+  if (!presetBlocks?.length) return {};
+  const blocks: Record<string, BlockData> = {};
+  const order: string[] = [];
+  const counters = new Map<string, number>();
+  for (const preset of presetBlocks) {
+    let key = preset.id;
+    if (!key || key in blocks) {
+      const base = preset.type.replace(/^_/, '');
+      const next = (counters.get(base) ?? 0) + 1;
+      counters.set(base, next);
+      key = `${base}-${next}`;
+      while (key in blocks) {
+        const bumped = (counters.get(base) ?? 0) + 1;
+        counters.set(base, bumped);
+        key = `${base}-${bumped}`;
+      }
+    }
+    const nested = instantiatePresetBlocks(preset.blocks);
+    blocks[key] = {
+      type: preset.type,
+      settings: preset.settings ? {...preset.settings} : {},
+      ...nested,
+    };
+    order.push(key);
+  }
+  return {blocks, block_order: order};
+}
+
+/**
+ * Generate a stable, non-colliding key for a newly inserted
+ * section/block, following Shopify's editor convention
+ * (type with private prefix stripped + counter).
+ */
+export function generateKey(type: string, siblings: string[]): string {
+  const base = type.replace(/^_/, '');
+  if (!siblings.includes(base)) return base;
+  let index = 1;
+  while (siblings.includes(`${base}-${index}`)) index += 1;
+  return `${base}-${index}`;
+}