@zalify/storefront-kit 0.1.0

package/src/react/registries.server.ts

@@ -0,0 +1,110 @@
+/**
+ * Built-in server loaders, keyed by section type (import from
+ * '@zalify/storefront-kit/react/server'). Apps spread these into installTheme()
+ * alongside their own app-local loaders.
+ *
+ * featured-collection: server loader for sections/featured-collection
+ * .liquid's data needs — the Liquid `section.settings.collection
+ * .products` lookup becomes a Storefront API query. When the collection
+ * setting is blank (fresh install), fall back to the first available
+ * collection so the section still merchandises real products; if
+ * nothing resolves the component renders its placeholder cards (the
+ * Liquid onboarding state).
+ */
+import {PRODUCT_CARD_FRAGMENT} from './components/ProductCard';
+import type {SectionLoader} from './engine/types';
+
+const FEATURED_COLLECTION_QUERY = `#graphql
+  query ThemeFeaturedCollection($handle: String!, $first: Int!) {
+    collection(handle: $handle) {
+      id
+      handle
+      title
+      products(first: $first) {
+        nodes {
+          ...ProductCard
+        }
+      }
+    }
+  }
+  ${PRODUCT_CARD_FRAGMENT}
+` as const;
+
+const FIRST_COLLECTIONS_QUERY = `#graphql
+  query ThemeFirstCollections($first: Int!) {
+    collections(first: 10) {
+      nodes {
+        id
+        handle
+        title
+        products(first: $first) {
+          nodes {
+            ...ProductCard
+          }
+        }
+      }
+    }
+  }
+  ${PRODUCT_CARD_FRAGMENT}
+` as const;
+
+const LATEST_PRODUCTS_QUERY = `#graphql
+  query ThemeLatestProducts($first: Int!) {
+    products(first: $first, sortKey: CREATED_AT, reverse: true) {
+      nodes {
+        ...ProductCard
+      }
+    }
+  }
+  ${PRODUCT_CARD_FRAGMENT}
+` as const;
+
+const featuredCollectionLoader: SectionLoader = async ({
+  settings,
+  storefront,
+}) => {
+  const first = Number(settings.products_to_show ?? 4) || 4;
+  const handle =
+    typeof settings.collection === 'string' && settings.collection
+      ? settings.collection
+      : null;
+
+  if (handle) {
+    const data = await storefront.query(FEATURED_COLLECTION_QUERY, {
+      variables: {handle, first},
+      cache: storefront.CacheLong?.(),
+    });
+    if (data?.collection) return {collection: data.collection};
+  }
+
+  // Fresh-install fallback: first collection that actually has
+  // products, then the latest products as a synthetic collection —
+  // placeholders only when the store is truly empty.
+  const data = await storefront.query(FIRST_COLLECTIONS_QUERY, {
+    variables: {first},
+    cache: storefront.CacheLong?.(),
+  });
+  const nonEmpty = (data?.collections?.nodes ?? []).find(
+    (node: {products?: {nodes?: unknown[]}}) => node.products?.nodes?.length,
+  );
+  if (nonEmpty) return {collection: nonEmpty};
+
+  const latest = await storefront.query(LATEST_PRODUCTS_QUERY, {
+    variables: {first},
+    cache: storefront.CacheLong?.(),
+  });
+  const products = latest?.products?.nodes ?? [];
+  if (!products.length) return {collection: null};
+  return {
+    collection: {
+      id: 'latest',
+      handle: 'all',
+      title: 'Featured products',
+      products: {nodes: products},
+    },
+  };
+};
+
+export const builtinSectionLoaders: Record<string, SectionLoader> = {
+  'featured-collection': featuredCollectionLoader,
+};

package/src/react/registries.ts

@@ -0,0 +1,80 @@
+/**
+ * Built-in component registries. Keys are the theme type names — the
+ * section/block `type` values in templates/*.json, which equal the old
+ * app/sections/*.tsx and app/blocks/*.tsx file names (including leading
+ * underscores and '404'). Apps spread these into installTheme() and add
+ * their own app-local sections/blocks on top.
+ */
+import type {BlockComponent, SectionComponent} from './engine/types';
+
+// Blocks
+import text from './blocks/text';
+import button from './blocks/button';
+import group from './blocks/group';
+import spacer from './blocks/spacer';
+import image from './blocks/image';
+import box from './blocks/_box';
+import slide from './blocks/_slide';
+import story from './blocks/story';
+import message from './blocks/message';
+import quote from './blocks/quote';
+import accordion from './blocks/accordion';
+import countdown from './blocks/countdown';
+import customLiquidBlock from './blocks/custom-liquid';
+import video from './blocks/video';
+import videoCard from './blocks/_video-card';
+
+// Sections
+import hero from './sections/hero';
+import stories from './sections/stories';
+import featuredCollection from './sections/featured-collection';
+import multicolumn from './sections/multicolumn';
+import imageWithText from './sections/image-with-text';
+import richText from './sections/rich-text';
+import customSection from './sections/custom-section';
+import customLiquidSection from './sections/custom-liquid';
+import announcementBar from './sections/announcement-bar';
+import notFound from './sections/404';
+import page from './sections/page';
+import article from './sections/article';
+import password from './sections/password';
+import contactForm from './sections/contact-form';
+import videoCarousel from './sections/video-carousel';
+import videoBubble from './sections/video-bubble';
+
+export const builtinSections: Record<string, SectionComponent> = {
+  hero,
+  stories,
+  'featured-collection': featuredCollection,
+  multicolumn,
+  'image-with-text': imageWithText,
+  'rich-text': richText,
+  'custom-section': customSection,
+  'custom-liquid': customLiquidSection,
+  'announcement-bar': announcementBar,
+  '404': notFound,
+  page,
+  article,
+  password,
+  'contact-form': contactForm,
+  'video-carousel': videoCarousel,
+  'video-bubble': videoBubble,
+};
+
+export const builtinBlocks: Record<string, BlockComponent> = {
+  text,
+  button,
+  group,
+  spacer,
+  image,
+  _box: box,
+  _slide: slide,
+  story,
+  message,
+  quote,
+  accordion,
+  countdown,
+  'custom-liquid': customLiquidBlock,
+  video,
+  '_video-card': videoCard,
+};

package/src/react/sections/404.tsx

@@ -0,0 +1,37 @@
+/**
+ * Port of sections/404.liquid. CSS: app/styles/components/sections-404.css
+ */
+import type {SectionProps} from '../engine/types';
+import {t} from '../engine/translate';
+import {useAdapter} from '../adapter';
+
+interface NotFoundSettings {
+  color_scheme?: string;
+  section_spacing?: string;
+}
+
+export default function NotFoundSection({
+  settings,
+}: SectionProps<NotFoundSettings>) {
+  const {Link} = useAdapter();
+  const {color_scheme: colorScheme = 'scheme-1', section_spacing: spacing = 'md'} =
+    settings;
+  return (
+    <div
+      className={`not-found section color-${colorScheme} full-width`}
+      style={
+        {
+          '--section-spacing': `var(--space-section-${spacing})`,
+        } as React.CSSProperties
+      }
+    >
+      <div className="not-found__inner stack">
+        <h1 className="not-found__title">{t('404.title')}</h1>
+        <p>{t('404.not_found')}</p>
+        <Link to="/collections/all" className="button">
+          {t('404.back_to_shopping')}
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/react/sections/announcement-bar.tsx

@@ -0,0 +1,170 @@
+/**
+ * Port of sections/announcement-bar.liquid — rotating messages bar.
+ * The Liquid theme drives rotation with the <announcement-bar> web
+ * component (src/entries/announcement.ts); here the same behavior
+ * lives in React: autoplay (paused for reduced motion), prev/next,
+ * pause/play. data-paused on the host drives the icon swap in CSS.
+ * CSS: app/styles/components/sections-announcement-bar.css
+ */
+import {useEffect, useRef, useState} from 'react';
+import type {SectionProps} from '../engine/types';
+import {t} from '../engine/translate';
+import {Icon} from '../components/Icon';
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      /* The extracted CSS targets the announcement-bar element itself
+         (announcement-bar[data-paused] …), so the tag name is part of
+         the styling contract and must be kept. */
+      'announcement-bar': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement>,
+        HTMLElement
+      >;
+    }
+  }
+}
+
+interface AnnouncementBarSettings {
+  rotation_speed?: number;
+  color_scheme?: string;
+}
+
+/*
+ * The bar's height is a CONSTANT, published as a token so layout math
+ * (e.g. the large hero's "viewport minus header stack") can be computed
+ * in pure CSS at first paint — mirror of the section's {% style %} tag.
+ * Removing this section removes the token (consumers fall back to 0).
+ */
+const HEIGHT_TOKEN_CSS = `
+:root {
+  --announcement-bar-height: calc(0.6875rem * 2.8 + 2 * var(--space-xs));
+}
+@media (min-width: 48rem) {
+  :root {
+    --announcement-bar-height: calc(var(--type-xs) * 2.8 + 2 * var(--space-xs));
+  }
+}
+`;
+
+export default function AnnouncementBarSection({
+  section,
+  settings,
+  children,
+}: SectionProps<AnnouncementBarSettings>) {
+  const {rotation_speed: rotationSpeed = 5, color_scheme: colorScheme = 'scheme-4'} =
+    settings;
+  const messageCount = (section.block_order ?? []).filter((key) => {
+    const block = section.blocks?.[key];
+    return block && !block.disabled;
+  }).length;
+
+  const hostRef = useRef<HTMLElement>(null);
+  const indexRef = useRef(0);
+  const timerRef = useRef<ReturnType<typeof setInterval>>();
+  const pausedRef = useRef(false);
+  const [paused, setPaused] = useState(false);
+
+  const messages = (): HTMLElement[] =>
+    Array.from(
+      hostRef.current?.querySelectorAll<HTMLElement>(
+        '.announcement-bar__message',
+      ) ?? [],
+    );
+
+  const show = (index: number) => {
+    const items = messages();
+    if (items.length < 2) return;
+    indexRef.current = (index + items.length) % items.length;
+    items.forEach((message, i) => {
+      message.hidden = i !== indexRef.current;
+    });
+  };
+
+  const start = () => {
+    clearInterval(timerRef.current);
+    if (pausedRef.current || messageCount < 2) return;
+    const speed = rotationSpeed || 5;
+    timerRef.current = setInterval(
+      () => show(indexRef.current + 1),
+      speed * 1000,
+    );
+  };
+
+  const setPausedState = (value: boolean) => {
+    pausedRef.current = value;
+    setPaused(value);
+  };
+
+  useEffect(() => {
+    // Autoplay starts paused when the user prefers reduced motion.
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+      setPausedState(true);
+    }
+    start();
+    return () => clearInterval(timerRef.current);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [messageCount, rotationSpeed]);
+
+  const previous = () => {
+    show(indexRef.current - 1);
+    start();
+  };
+  const next = () => {
+    show(indexRef.current + 1);
+    start();
+  };
+  const toggle = () => {
+    setPausedState(!pausedRef.current);
+    // pausedRef is already updated; restart (or stop) the timer.
+    start();
+  };
+
+  return (
+    <announcement-bar
+      ref={hostRef}
+      className={`announcement-bar color-${colorScheme} full-width`}
+      data-speed={rotationSpeed}
+      data-paused={paused ? '' : undefined}
+    >
+      <style dangerouslySetInnerHTML={{__html: HEIGHT_TOKEN_CSS}} />
+      <div className="announcement-bar__inner">
+        <div className="announcement-bar__messages">{children}</div>
+
+        {messageCount > 1 && (
+          <div className="announcement-bar__controls">
+            <button
+              type="button"
+              className="announcement-bar__control"
+              onClick={previous}
+              aria-label={t('general.previous')}
+            >
+              <Icon name="icon-chevron-left" />
+            </button>
+            <button
+              type="button"
+              className="announcement-bar__control"
+              onClick={next}
+              aria-label={t('general.next')}
+            >
+              <Icon name="icon-chevron-right" />
+            </button>
+            <button
+              type="button"
+              className="announcement-bar__control announcement-bar__toggle"
+              onClick={toggle}
+              aria-label={t('general.pause')}
+            >
+              <span className="announcement-bar__icon-pause">
+                <Icon name="icon-pause" />
+              </span>
+              <span className="announcement-bar__icon-play">
+                <Icon name="icon-play" />
+              </span>
+            </button>
+          </div>
+        )}
+      </div>
+    </announcement-bar>
+  );
+}

package/src/react/sections/article.tsx

@@ -0,0 +1,97 @@
+/**
+ * Port of sections/article.liquid. CSS: app/styles/components/sections-article.css
+ *
+ * Data: useResource('article') — the scaffold ARTICLE query shape
+ * ({handle, title, contentHtml, publishedAt, author: {name}, image}),
+ * plus useResource('blog') ({handle, title}) for the back link.
+ *
+ * The Liquid comments block (blog.comments_enabled?, {% form
+ * 'new_comment' %}) has no Storefront API mirror and is omitted.
+ */
+import type {SectionProps} from '../engine/types';
+import {useResource} from '../engine/context';
+import {t} from '../engine/translate';
+import {imageSrcSet, imageUrl} from '../engine/images';
+import {useAdapter} from '../adapter';
+
+interface ArticleSettings {
+  color_scheme?: string;
+  section_spacing?: string;
+}
+
+function articleDateHtml(publishedAt?: string): string {
+  if (!publishedAt) return '';
+  const formatted = new Intl.DateTimeFormat('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  }).format(new Date(publishedAt));
+  return `<time datetime="${publishedAt}">${formatted}</time>`;
+}
+
+export default function ArticleSection({
+  settings,
+}: SectionProps<ArticleSettings>) {
+  const {Link} = useAdapter();
+  const {color_scheme: colorScheme = 'scheme-1', section_spacing: spacing = 'md'} =
+    settings;
+  const article = useResource<any>('article');
+  const blog = useResource<any>('blog') ?? article?.blog;
+
+  if (!article) return null;
+
+  return (
+    <article
+      className={`article section color-${colorScheme} full-width`}
+      style={
+        {
+          '--section-spacing': `var(--space-section-${spacing})`,
+        } as React.CSSProperties
+      }
+    >
+      <div
+        className="article__inner stack"
+        style={{'--stack-gap': 'var(--space-lg)'} as React.CSSProperties}
+      >
+        <header
+          className="article__header stack"
+          style={{'--stack-gap': 'var(--space-sm)'} as React.CSSProperties}
+        >
+          {blog?.handle && (
+            <Link className="article__back" to={`/blogs/${blog.handle}`}>
+              {t('blog.back_to_blog', {blog: blog.title ?? blog.handle})}
+            </Link>
+          )}
+          <p
+            className="article__meta"
+            dangerouslySetInnerHTML={{
+              __html: t('blog.article_metadata_html', {
+                date: articleDateHtml(article.publishedAt),
+                author: article.author?.name ?? '',
+              }),
+            }}
+          />
+          <h1 className="article__title">{article.title}</h1>
+        </header>
+
+        {article.image?.url && (
+          <img
+            className="article__image"
+            src={imageUrl(article.image.url, 1500)}
+            srcSet={imageSrcSet(article.image.url)}
+            sizes="(min-width: 64rem) 60rem, 100vw"
+            loading="eager"
+            width={article.image.width ?? undefined}
+            height={article.image.height ?? undefined}
+            alt={article.image.altText ?? article.title ?? ''}
+          />
+        )}
+
+        <div
+          className="article__content prose"
+          dangerouslySetInnerHTML={{__html: article.contentHtml ?? ''}}
+        />
+      </div>
+    </article>
+  );
+}

package/src/react/sections/contact-form.tsx

@@ -0,0 +1,104 @@
+/**
+ * Port of sections/contact-form.liquid.
+ * CSS: app/styles/components/sections-contact-form.css
+ *
+ * Shopify's native `{% form 'contact' %}` POST endpoint isn't available
+ * in Hydrogen — the markup is rendered faithfully but submission is a
+ * no-op. TODO: wire the submit to a route action (e.g. a proxy to the
+ * Online Store contact endpoint or a third-party form service).
+ */
+import type {SectionProps} from '../engine/types';
+import {t} from '../engine/translate';
+
+interface ContactFormSettings {
+  color_scheme?: string;
+  section_spacing?: string;
+}
+
+export default function ContactFormSection({
+  id,
+  settings,
+}: SectionProps<ContactFormSettings>) {
+  const {color_scheme: colorScheme = 'scheme-1', section_spacing: spacing = 'md'} =
+    settings;
+
+  return (
+    <div
+      className={`contact section color-${colorScheme} full-width`}
+      style={
+        {
+          '--section-spacing': `var(--space-section-${spacing})`,
+        } as React.CSSProperties
+      }
+    >
+      <div
+        className="contact__inner stack"
+        style={{'--stack-gap': 'var(--space-lg)'} as React.CSSProperties}
+      >
+        {/* TODO: POST somewhere useful — Shopify contact form posts aren't available in Hydrogen. */}
+        <form
+          className="contact__form stack"
+          method="post"
+          onSubmit={(event) => event.preventDefault()}
+        >
+          <div className="contact__row">
+            <div className="field">
+              <label className="field__label" htmlFor={`ContactName-${id}`}>
+                {t('contact.name')}
+              </label>
+              <input
+                id={`ContactName-${id}`}
+                type="text"
+                name="contact[name]"
+                autoComplete="name"
+              />
+            </div>
+            <div className="field">
+              <label className="field__label" htmlFor={`ContactEmail-${id}`}>
+                {t('contact.email')}
+              </label>
+              <input
+                id={`ContactEmail-${id}`}
+                type="email"
+                name="contact[email]"
+                autoComplete="email"
+                spellCheck={false}
+                autoCapitalize="off"
+                required
+              />
+            </div>
+          </div>
+
+          <div className="field">
+            <label className="field__label" htmlFor={`ContactPhone-${id}`}>
+              {t('contact.phone')}
+            </label>
+            <input
+              id={`ContactPhone-${id}`}
+              type="tel"
+              name="contact[phone]"
+              autoComplete="tel"
+              pattern="[0-9\-]*"
+            />
+          </div>
+
+          <div className="field">
+            <label className="field__label" htmlFor={`ContactMessage-${id}`}>
+              {t('contact.message')}
+            </label>
+            <textarea
+              id={`ContactMessage-${id}`}
+              name="contact[body]"
+              rows={8}
+              required
+            />
+          </div>
+
+          <button type="submit" className="button contact__submit">
+            {t('contact.send')}
+          </button>
+        </form>
+      </div>
+    </div>
+  );
+}

package/src/react/sections/custom-liquid.tsx

@@ -0,0 +1,39 @@
+/**
+ * Port of sections/custom-liquid.liquid — merchant-pasted markup.
+ * The setting's raw HTML is injected as-is; any Liquid tags/objects in
+ * it cannot execute here (no Liquid runtime), so only the plain-HTML
+ * use case survives the mirror. CSS: sections-custom-liquid.css
+ */
+import type {SectionProps} from '../engine/types';
+
+interface CustomLiquidSettings {
+  custom_liquid?: string;
+  color_scheme?: string;
+  section_spacing?: 'none' | 'sm' | 'md' | 'lg';
+}
+
+export default function CustomLiquidSection({
+  settings,
+}: SectionProps<CustomLiquidSettings>) {
+  const {
+    custom_liquid: customLiquid = '',
+    color_scheme: colorScheme = 'scheme-1',
+    section_spacing: sectionSpacing = 'md',
+  } = settings;
+
+  return (
+    <div
+      className={`custom-liquid section color-${colorScheme} full-width`}
+      style={
+        {
+          '--section-spacing': `var(--space-section-${sectionSpacing})`,
+        } as React.CSSProperties
+      }
+    >
+      <div
+        className="custom-liquid__inner"
+        dangerouslySetInnerHTML={{__html: customLiquid}}
+      />
+    </div>
+  );
+}

package/src/react/sections/custom-section.tsx

@@ -0,0 +1,44 @@
+/**
+ * Port of sections/custom-section.liquid — the canonical v3 section
+ * pattern: color_scheme + section_spacing on the wrapper, optional
+ * background image, blocks in a content grid.
+ * CSS: app/styles/components/sections-custom-section.css
+ */
+import type {SectionProps} from '../engine/types';
+import {imageUrl, settingImageUrl} from '../engine/images';
+
+interface CustomSectionSettings {
+  background_image?: string;
+  color_scheme?: string;
+  section_spacing?: 'none' | 'sm' | 'md' | 'lg';
+}
+
+export default function CustomSection({
+  settings,
+  children,
+}: SectionProps<CustomSectionSettings>) {
+  const {
+    color_scheme: colorScheme = 'scheme-1',
+    section_spacing: sectionSpacing = 'md',
+  } = settings;
+  const backgroundImage = settingImageUrl(settings.background_image);
+
+  return (
+    <div
+      className={`custom-section section full-width color-${colorScheme}`}
+      style={
+        {
+          '--section-spacing': `var(--space-section-${sectionSpacing})`,
+        } as React.CSSProperties
+      }
+    >
+      {backgroundImage ? (
+        <div className="custom-section__background">
+          <img src={imageUrl(backgroundImage, 2000)} alt="" />
+        </div>
+      ) : null}
+
+      <div className="custom-section__content">{children}</div>
+    </div>
+  );
+}