@zalify/storefront-kit 0.1.0

package/src/react/engine/render.tsx

@@ -0,0 +1,190 @@
+/**
+ * The rendering mirror of Shopify's section/blocks runtime:
+ *
+ * - <ThemeTemplate name="index" …/>   ≙ {{ content_for_layout }} for a JSON template
+ * - <SectionGroup name="header-group"/> ≙ {% sections 'header-group' %}
+ * - Child blocks arrive as `children`   ≙ {% content_for 'blocks' %}
+ *
+ * Sections are wrapped in `.shopify-section` divs and blocks in
+ * `.shopify-block` divs, matching the wrappers Shopify emits — the
+ * extracted component CSS relies on them.
+ *
+ * Every wrapper also carries a `data-z-path` attribute (the wire form
+ * of a @zalify/storefront-kit/schemas ThemeJsonPath) identifying the node in
+ * the theme JSON. The canvas-editor bridge hit-tests against it; it is
+ * emitted unconditionally so server and client markup stay identical.
+ */
+import {formatThemePath, DATA_PATH_ATTR} from '../../schemas/index.ts';
+import {getSectionGroup, getTemplate, getThemeStore} from './store';
+import {SectionProvider, TemplateProvider} from './context';
+import type {BlockData, SectionData, TemplateData} from './types';
+
+/** The scope half of a ThemeJsonPath, threaded through rendering. */
+export interface RenderScope {
+  kind: 'template' | 'group';
+  name: string;
+}
+
+const warned = new Set<string>();
+function warnMissing(kind: 'section' | 'block', type: string) {
+  const key = `${kind}:${type}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  // eslint-disable-next-line no-console
+  console.warn(`[theme] No ${kind} component registered for type "${type}"`);
+}
+
+function pathAttr(
+  scope: RenderScope | undefined,
+  sectionKey: string,
+  blockKeys: string[],
+): Record<string, string> {
+  if (!scope) return {};
+  return {
+    [DATA_PATH_ATTR]: formatThemePath({scope, sectionKey, blockKeys}),
+  };
+}
+
+function RenderBlocks({
+  container,
+  sectionId,
+  scope,
+  parentBlockKeys = [],
+}: {
+  container: {blocks?: Record<string, BlockData>; block_order?: string[]};
+  sectionId: string;
+  scope?: RenderScope;
+  parentBlockKeys?: string[];
+}) {
+  const {blocks: blockRegistry} = getThemeStore();
+  const order = container.block_order ?? [];
+  if (!order.length || !container.blocks) return null;
+  const visible = order.filter((key) => {
+    const block = container.blocks![key];
+    return block && !block.disabled;
+  });
+  return (
+    <>
+      {visible.map((key, index) => {
+        const block = container.blocks![key];
+        const Component = blockRegistry[block.type];
+        if (!Component) {
+          warnMissing('block', block.type);
+          return null;
+        }
+        const blockKeys = [...parentBlockKeys, key];
+        return (
+          <div
+            key={key}
+            className="shopify-block"
+            data-block-type={block.type}
+            {...pathAttr(scope, sectionId, blockKeys)}
+          >
+            <Component
+              id={key}
+              block={block}
+              settings={block.settings ?? {}}
+              index={index}
+              total={visible.length}
+              sectionId={sectionId}
+            >
+              <RenderBlocks
+                container={block}
+                sectionId={sectionId}
+                scope={scope}
+                parentBlockKeys={blockKeys}
+              />
+            </Component>
+          </div>
+        );
+      })}
+    </>
+  );
+}
+
+export function RenderSection({
+  id,
+  section,
+  scope,
+}: {
+  id: string;
+  section: SectionData;
+  scope?: RenderScope;
+}) {
+  if (section.disabled) return null;
+  const Component = getThemeStore().sections[section.type];
+  if (!Component) {
+    warnMissing('section', section.type);
+    return null;
+  }
+  return (
+    <div
+      id={`shopify-section-${id}`}
+      className={`shopify-section shopify-section--${section.type}`}
+      {...pathAttr(scope, id, [])}
+    >
+      <SectionProvider id={id}>
+        <Component id={id} section={section} settings={section.settings ?? {}}>
+          <RenderBlocks container={section} sectionId={id} scope={scope} />
+        </Component>
+      </SectionProvider>
+    </div>
+  );
+}
+
+export function RenderSections({
+  template,
+  scope,
+}: {
+  template: TemplateData;
+  scope?: RenderScope;
+}) {
+  return (
+    <>
+      {template.order.map((key) => {
+        const section = template.sections[key];
+        if (!section) return null;
+        return (
+          <RenderSection key={key} id={key} section={section} scope={scope} />
+        );
+      })}
+    </>
+  );
+}
+
+/**
+ * Render a page template by name with its route resources and
+ * per-section loader data (from loadSectionData in the server module).
+ */
+export function ThemeTemplate({
+  name,
+  resources = {},
+  sectionData = {},
+}: {
+  name: string;
+  resources?: Record<string, unknown>;
+  sectionData?: Record<string, unknown>;
+}) {
+  const template = getTemplate(name);
+  return (
+    <TemplateProvider value={{name, kind: 'template', resources, sectionData}}>
+      <RenderSections template={template} scope={{kind: 'template', name}} />
+    </TemplateProvider>
+  );
+}
+
+/** Mirror of `{% sections 'header-group' %}` in layout/theme.liquid. */
+export function SectionGroup({
+  name,
+  sectionData = {},
+}: {
+  name: string;
+  sectionData?: Record<string, unknown>;
+}) {
+  const group = getSectionGroup(name);
+  return (
+    <TemplateProvider value={{name, kind: 'group', resources: {}, sectionData}}>
+      <RenderSections template={group} scope={{kind: 'group', name}} />
+    </TemplateProvider>
+  );
+}

package/src/react/engine/settings.ts

@@ -0,0 +1,89 @@
+/**
+ * Resolves global theme settings the same way Shopify does: schema
+ * defaults from config/settings_schema.json, overlaid with the current
+ * preset (or flat values) in config/settings_data.json — both provided
+ * at installTheme() time.
+ */
+import {getThemeStore} from './store';
+import type {ColorScheme, ThemeSettings} from './types';
+
+interface Resolved {
+  settings: ThemeSettings;
+  schemes: ColorScheme[];
+}
+
+let cache: Resolved | null = null;
+
+function resolve(): Resolved {
+  if (cache) return cache;
+  const store = getThemeStore();
+  const {settingsSchema, settingsData} = store.schema;
+
+  const defaults: Record<string, unknown> = {};
+  for (const group of settingsSchema) {
+    for (const setting of group.settings ?? []) {
+      const id = setting.id as string | undefined;
+      if (!id || setting.type === 'color_scheme_group') continue;
+      if ('default' in setting) defaults[id] = setting.default;
+    }
+  }
+
+  const current =
+    typeof settingsData.current === 'string'
+      ? (settingsData.presets?.[settingsData.current] ?? {})
+      : (settingsData.current ?? {});
+
+  const settings = {
+    ...defaults,
+    ...current,
+    ...store.settingsOverride,
+  } as ThemeSettings;
+
+  const rawSchemes = settings.color_schemes as
+    | Record<string, {settings: ColorScheme['settings']}>
+    | undefined;
+  let schemes: ColorScheme[];
+  if (rawSchemes) {
+    schemes = Object.entries(rawSchemes).map(([id, value]) => ({
+      id,
+      settings: value.settings,
+    }));
+  } else {
+    // Fall back to the schema definition defaults as a single scheme.
+    const group = settingsSchema
+      .flatMap((g) => g.settings ?? [])
+      .find((s) => s.type === 'color_scheme_group');
+    const definition = (group?.definition ?? []) as Array<{
+      id: string;
+      default?: string;
+    }>;
+    const schemeSettings = Object.fromEntries(
+      definition.map((d) => [d.id, d.default ?? '#000000']),
+    ) as unknown as ColorScheme['settings'];
+    schemes = [{id: 'scheme-1', settings: schemeSettings}];
+  }
+
+  cache = {settings, schemes};
+  return cache;
+}
+
+/**
+ * Global theme settings. A lazy proxy so call sites can keep reading
+ * `themeSettings.card_density` while resolution waits for installTheme().
+ */
+export const themeSettings: ThemeSettings = new Proxy({} as ThemeSettings, {
+  get: (_target, key) => resolve().settings[key as keyof ThemeSettings],
+  has: (_target, key) => key in resolve().settings,
+  ownKeys: () => Reflect.ownKeys(resolve().settings),
+  getOwnPropertyDescriptor: (_target, key) =>
+    Object.getOwnPropertyDescriptor(resolve().settings, key),
+});
+
+export function colorSchemes(): ColorScheme[] {
+  return resolve().schemes;
+}
+
+export function getColorScheme(id: string | undefined): ColorScheme {
+  const schemes = resolve().schemes;
+  return schemes.find((s) => s.id === id) ?? schemes[0];
+}

package/src/react/engine/store.ts

@@ -0,0 +1,103 @@
+/**
+ * The engine's data store. Apps install the theme schema (the JSON
+ * copied from apps/liquid by `pnpm sync`) plus their component
+ * registries once at startup:
+ *
+ *   // app/lib/theme-setup.ts — imported for side effects by root
+ *   installTheme({schema, sections, blocks, sectionLoaders});
+ *
+ * No import.meta.glob in here — data loading is the app's business
+ * (Vite apps glob, other bundlers can use generated modules), which
+ * keeps this package bundler-agnostic.
+ */
+import type {
+  BlockComponent,
+  SectionComponent,
+  SectionGroupData,
+  SectionLoader,
+  TemplateData,
+} from './types';
+
+export interface ThemeSchema {
+  /** templates/*.json keyed by name ("index", "product"…). */
+  templates: Record<string, TemplateData>;
+  /** templates/customers/*.json keyed by name ("login"…). */
+  customerTemplates?: Record<string, TemplateData>;
+  /** sections/*-group.json keyed by file name ("header-group"…). */
+  sectionGroups: Record<string, SectionGroupData>;
+  /** config/settings_schema.json. */
+  settingsSchema: Array<{name: string; settings?: Array<Record<string, unknown>>}>;
+  /** config/settings_data.json. */
+  settingsData: {
+    current: string | Record<string, unknown>;
+    presets?: Record<string, Record<string, unknown>>;
+  };
+  /** locales/*.json keyed by file name ("en.default", "en.default.schema"). */
+  locales: Record<string, Record<string, unknown>>;
+}
+
+export interface InstallThemeOptions {
+  schema: ThemeSchema;
+  /** Full section registry (spread builtinSections, then app extras). */
+  sections: Record<string, SectionComponent>;
+  /** Full block registry (spread builtinBlocks, then app extras). */
+  blocks: Record<string, BlockComponent>;
+  /** Server loaders keyed by section type (spread builtinSectionLoaders…). */
+  sectionLoaders?: Record<string, SectionLoader>;
+  /**
+   * App-level overrides applied on top of the resolved theme settings
+   * (schema defaults + current preset). The synced schema stays the
+   * shared source of truth; this is the seam for one app to diverge
+   * deliberately (e.g. a different Google font in one storefront).
+   */
+  settingsOverride?: Record<string, unknown>;
+}
+
+interface ThemeStore extends InstallThemeOptions {}
+
+let store: ThemeStore | null = null;
+
+export function installTheme(options: InstallThemeOptions): void {
+  store = options;
+}
+
+export function getThemeStore(): ThemeStore {
+  if (!store) {
+    throw new Error(
+      '[storefront-kit] installTheme() has not been called. Import your app\'s ' +
+        'theme-setup module (which calls installTheme) before rendering.',
+    );
+  }
+  return store;
+}
+
+/** Look up a page template ("index", "product", "customers/login"…). */
+export function getTemplate(name: string): TemplateData {
+  const {schema} = getThemeStore();
+  const template = name.startsWith('customers/')
+    ? schema.customerTemplates?.[name.slice('customers/'.length)]
+    : schema.templates[name];
+  if (!template) throw new Error(`Unknown theme template: ${name}`);
+  return template;
+}
+
+/** Look up a section group ("header-group", "footer-group", "overlay-group"). */
+export function getSectionGroup(name: string): SectionGroupData {
+  const group = getThemeStore().schema.sectionGroups[name];
+  if (!group) throw new Error(`Unknown section group: ${name}`);
+  return group;
+}
+
+/**
+ * Parse theme JSON that may carry Shopify's leading block comment
+ * (templates/*.json are written by the theme editor with a header).
+ * Exposed for apps that load the schema from raw strings.
+ */
+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(`Failed to parse ${name}: ${String(error)}`);
+  }
+}

package/src/react/engine/translate.ts

@@ -0,0 +1,40 @@
+/**
+ * Mirror of Liquid's `| t` filter over the theme's locale files
+ * (locales/en.default.json, provided at installTheme() time). Keys
+ * prefixed with "t:" resolve against the schema locale file
+ * (en.default.schema.json), matching the theme editor.
+ */
+import {getThemeStore} from './store';
+
+type LocaleTree = Record<string, unknown>;
+
+function lookup(tree: LocaleTree, key: string): string | undefined {
+  let node: unknown = tree;
+  for (const part of key.split('.')) {
+    if (node == null || typeof node !== 'object') return undefined;
+    node = (node as LocaleTree)[part];
+  }
+  return typeof node === 'string' ? node : undefined;
+}
+
+/**
+ * Translate a locale key with `{{ var }}` interpolation.
+ *
+ *   t('general.go_to_slide', {number: 2}) // "Go to slide 2"
+ *   t('t:general.hero')                   // schema label
+ */
+export function t(
+  key: string,
+  vars?: Record<string, string | number>,
+): string {
+  const {locales} = getThemeStore().schema;
+  const isSchemaKey = key.startsWith('t:');
+  const cleanKey = isSchemaKey ? key.slice(2) : key;
+  const tree = (locales[isSchemaKey ? 'en.default.schema' : 'en.default'] ??
+    {}) as LocaleTree;
+  const raw = lookup(tree, cleanKey) ?? cleanKey.split('.').pop() ?? cleanKey;
+  if (!vars) return raw;
+  return raw.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, name: string) =>
+    name in vars ? String(vars[name]) : match,
+  );
+}

package/src/react/engine/types.ts

@@ -0,0 +1,142 @@
+/**
+ * Data shapes mirrored from the Zalify Liquid theme's JSON schema
+ * (templates/*.json, sections/*-group.json, config/settings_data.json).
+ * Those files are copied verbatim from the theme and are the source of
+ * truth for page structure; these types describe them.
+ */
+import type {ComponentType, ReactNode} from 'react';
+
+export type SettingsBag = Record<string, unknown>;
+
+export interface BlockData {
+  type: string;
+  settings?: SettingsBag;
+  blocks?: Record<string, BlockData>;
+  block_order?: string[];
+  disabled?: boolean;
+}
+
+export interface SectionData {
+  type: string;
+  settings?: SettingsBag;
+  blocks?: Record<string, BlockData>;
+  block_order?: string[];
+  disabled?: boolean;
+  custom_css?: string[];
+}
+
+export interface TemplateData {
+  layout?: string | false;
+  wrapper?: string;
+  sections: Record<string, SectionData>;
+  order: string[];
+}
+
+export interface SectionGroupData extends TemplateData {
+  type: string;
+  name: string;
+}
+
+/** One color scheme from the color_scheme_group setting. */
+export interface ColorScheme {
+  id: string;
+  settings: {
+    background: string;
+    text: string;
+    accent: string;
+    button: string;
+    button_label: string;
+  };
+}
+
+/**
+ * Global theme settings: schema defaults from config/settings_schema.json
+ * overlaid with the current preset in config/settings_data.json.
+ * Individual ids are looked up loosely; well-known ones are typed below.
+ */
+export interface ThemeSettings extends SettingsBag {
+  type_body_font?: string;
+  type_body_google?: string;
+  type_heading_font?: string;
+  type_heading_google?: string;
+  type_mono_google?: string;
+  max_page_width?: string;
+  min_page_margin?: number;
+  button_corner_radius?: number;
+  input_corner_radius?: number;
+  card_corner_radius?: number;
+  card_swatch_style?: 'swatch' | 'variant_image' | 'none';
+  card_density?: 'comfortable' | 'compact';
+  card_show_quick_add?: boolean;
+  card_show_secondary_image?: boolean;
+  card_show_rating?: boolean;
+  card_badge_position?: 'corner' | 'below';
+  card_badge_background?: string;
+  card_badge_text?: string;
+  card_badge_sale_background?: string;
+  card_badge_sale_text?: string;
+  badge_style_1_labels?: string;
+  badge_style_1_background?: string;
+  badge_style_1_text?: string;
+  badge_style_2_labels?: string;
+  badge_style_2_background?: string;
+  badge_style_2_text?: string;
+  favicon?: string;
+  social_instagram?: string;
+  social_tiktok?: string;
+  social_x?: string;
+  social_facebook?: string;
+  social_youtube?: string;
+  social_pinterest?: string;
+}
+
+/** Props every ported section component (app/sections/*.tsx) receives. */
+export interface SectionProps<S extends object = SettingsBag> {
+  /** Section key inside its template, e.g. "hero" or "main". */
+  id: string;
+  section: SectionData;
+  /** section.settings (defaults are applied by the component itself). */
+  settings: S;
+  /** Pre-rendered child blocks — the mirror of `{% content_for 'blocks' %}`. */
+  children?: ReactNode;
+}
+
+/** Props every ported block component (app/blocks/*.tsx) receives. */
+export interface BlockProps<S extends object = SettingsBag> {
+  id: string;
+  block: BlockData;
+  settings: S;
+  /** Position among siblings — mirror of forloop/find_index tricks. */
+  index: number;
+  total: number;
+  /** Key of the section this block ultimately lives in. */
+  sectionId: string;
+  /** Pre-rendered nested blocks. */
+  children?: ReactNode;
+}
+
+export type SectionComponent = ComponentType<SectionProps>;
+export type BlockComponent = ComponentType<BlockProps>;
+
+/**
+ * Optional per-section server loader (app/sections/<type>.server.ts).
+ * Runs from route loaders for every instance of the section in the
+ * page's template; its result is delivered to the component via
+ * useSectionData().
+ */
+export interface SectionLoaderArgs {
+  settings: SettingsBag;
+  section: SectionData;
+  sectionId: string;
+  /* Storefront client from Hydrogen context (typed loosely to keep the
+     theme engine decoupled from generated types). */
+  storefront: {
+    query: (query: string, options?: Record<string, unknown>) => Promise<any>;
+    CacheLong?: () => unknown;
+    CacheShort?: () => unknown;
+  };
+  params: Record<string, string | undefined>;
+  request: Request;
+}
+
+export type SectionLoader = (args: SectionLoaderArgs) => Promise<unknown>;

package/src/react/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @zalify/storefront-kit/react — the Zalify theme engine and shared React
+ * components, host-framework-agnostic. An app:
+ *
+ *   1. installTheme({schema, sections, blocks, sectionLoaders}) at
+ *      startup, merging builtinSections/builtinBlocks with its own
+ *      app-local components;
+ *   2. wraps the tree in <AdapterProvider adapter={…}> injecting its
+ *      router/cart primitives;
+ *   3. renders pages with <ThemeTemplate>/<SectionGroup> and
+ *      <CssVariables/> in <head>.
+ *
+ * Server loaders: import {loadSectionData} from '@zalify/storefront-kit/react/server'.
+ */
+
+// Engine
+export * from './engine/types';
+export {
+  installTheme,
+  getTemplate,
+  getSectionGroup,
+  parseThemeJson,
+} from './engine/store';
+export type {ThemeSchema, InstallThemeOptions} from './engine/store';
+export {themeSettings, colorSchemes, getColorScheme} from './engine/settings';
+export {t} from './engine/translate';
+export {
+  ThemeTemplate,
+  SectionGroup,
+  RenderSection,
+  RenderSections,
+} from './engine/render';
+export {
+  ThemeDataProvider,
+  TemplateProvider,
+  useThemeGlobals,
+  useResource,
+  useSectionData,
+  useTemplateScope,
+} from './engine/context';
+export {CssVariables} from './engine/CssVariables';
+export {parseFontHandle, googleFontsHref} from './engine/fonts';
+export {
+  settingImageUrl,
+  imageUrl,
+  imageSrcSet,
+  PlaceholderSvg,
+} from './engine/images';
+
+// Adapter seam
+export {AdapterProvider, useAdapter} from './adapter';
+export type {
+  ThemeAdapter,
+  AdapterLinkProps,
+  CartAddFormProps,
+  CartLineInput,
+} from './adapter';
+
+// Shared components
+export {Icon} from './components/Icon';
+export type {IconName} from './components/Icon';
+export {PaymentIcons} from './components/PaymentIcons';
+export type {PaymentType} from './components/PaymentIcons';
+export {Price} from './components/Price';
+export {Rating} from './components/Rating';
+export {ProductBadges, hasProductBadges} from './components/ProductBadges';
+export {swatchStyle} from './components/SwatchStyle';
+export {ProductCard, PRODUCT_CARD_FRAGMENT} from './components/ProductCard';
+export * from './components/VideoModal';
+export {
+  Facets,
+  COLLECTION_SORT_OPTIONS,
+  SEARCH_SORT_OPTIONS,
+} from './components/Facets';
+
+// Built-in registries (spread into installTheme with app extras).
+// Server-only loaders live in '@zalify/storefront-kit/react/server'.
+export {builtinSections, builtinBlocks} from './registries';