@usequeek/theme-kit 0.1.9 → 0.1.11

package/README.md

@@ -128,10 +128,25 @@ export default function Footer() {
   the seam for a possible future plan perk. There is no merchant-facing
   toggle for it in v1 — always render it visible.
 
+## Links and navigation
+
+```ts
+import { Link, useRouter, usePathname } from '@usequeek/theme-kit/navigation';
+```
+
+A theme links and navigates through these, never through `next/link` or
+`next/navigation`. Which framework runs the storefront is Queek's decision: the
+kit is the one place that knows it, so a change there is a kit release, not an
+update to every theme. `Link` is an `<a>` that moves inside the store without a
+full page load (`href`, `prefetch`, `replace`, plus any anchor attribute);
+`useRouter()` gives `push`, `replace`, `back` and `refresh`; `usePathname()`
+returns the current path. The theme check rejects a theme that imports `next`.
+
 ## Boundary
 
 The kit must never import the storefront app, its themes, or `lib/storefront`.
-That one-way rule is what makes this package extractable at all.
+That one-way rule is what makes this package extractable at all. The reverse
+also holds for the framework: the kit may import `next`, a theme may not.
 
 ## Develop
 

package/client.ts

@@ -6,6 +6,7 @@
  */
 
 export * from './provider';
+export * from './navigation';
 export * from './page-renderer';
 export * from './edit-mode';
 export * from './theme-variant-resolver';

package/navigation.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+/**
+ * How a theme links and moves between pages. Themes import these, never
+ * `next/link` or `next/navigation`: which framework runs the storefront is
+ * Queek's decision, and a theme written against this module keeps working
+ * when that changes — only this file does.
+ *
+ *   import { Link, useRouter, usePathname } from '@usequeek/theme-kit/navigation';
+ *
+ * The surface is deliberately small (what every theme so far has needed).
+ * Ask for an addition rather than reaching past it to the framework.
+ */
+import NextLink from 'next/link';
+import { usePathname as useFrameworkPathname, useRouter as useFrameworkRouter } from 'next/navigation';
+import { useMemo, type AnchorHTMLAttributes, type ReactNode, type Ref } from 'react';
+
+export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  /** A path inside the store (`menuItemToHref()`, `useHref()`) or a full URL. */
+  href: string;
+  /** Load the page in the background before it is clicked. Leave unset and the storefront decides. */
+  prefetch?: boolean;
+  /** Replace the current history entry instead of adding one. */
+  replace?: boolean;
+  ref?: Ref<HTMLAnchorElement>;
+  children?: ReactNode;
+}
+
+/** An `<a>` that moves inside the store without a full page load. */
+export function Link({ href, prefetch, replace, ...anchor }: LinkProps) {
+  return <NextLink href={href} prefetch={prefetch} replace={replace} {...anchor} />;
+}
+
+export interface Router {
+  /** Go to `href`, adding a history entry. */
+  push(href: string): void;
+  /** Go to `href`, replacing the current history entry. */
+  replace(href: string): void;
+  back(): void;
+  /** Re-render the current page with fresh data from the server. */
+  refresh(): void;
+}
+
+/** Move between pages from code — after a form submits, a filter changes, a search runs. */
+export function useRouter(): Router {
+  const router = useFrameworkRouter();
+  return useMemo(() => ({
+    push: (href: string) => router.push(href),
+    replace: (href: string) => router.replace(href),
+    back: () => router.back(),
+    refresh: () => router.refresh(),
+  }), [router]);
+}
+
+/** The current path, e.g. `/medley/shop` — to mark the active menu item. */
+export function usePathname(): string {
+  return useFrameworkPathname() ?? '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/tests/navigation.test.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import * as navigation from '../navigation';
+import { Link } from '../navigation';
+
+describe('navigation — what a theme links and navigates with', () => {
+  it('is exactly Link, useRouter and usePathname', () => {
+    expect(Object.keys(navigation).sort()).toEqual(['Link', 'usePathname', 'useRouter']);
+  });
+
+  it('renders Link as a plain anchor carrying its href, class and children', () => {
+    const html = renderToStaticMarkup(
+      React.createElement(Link, { href: '/medley/shop', className: 'md-nav__link', 'aria-current': 'page' }, 'Shop'),
+    );
+
+    expect(html).toContain('<a');
+    expect(html).toContain('href="/medley/shop"');
+    expect(html).toContain('class="md-nav__link"');
+    expect(html).toContain('aria-current="page"');
+    expect(html).toContain('>Shop</a>');
+  });
+
+  it('keeps a full URL as is', () => {
+    const html = renderToStaticMarkup(React.createElement(Link, { href: 'https://usequeek.com/business', target: '_blank' }, 'Queek'));
+
+    expect(html).toContain('href="https://usequeek.com/business"');
+    expect(html).toContain('target="_blank"');
+  });
+});

package/tests/product-images.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'vitest';
+import type { LegacyProductLike, Product } from '../types/product';
+import { normalizeProduct } from '../utils/product-normalizer';
+import { buildMediaFrames, getHoverImage, getSlideshowImages } from '../utils/product-media';
+
+function raw(overrides: LegacyProductLike = {}): LegacyProductLike {
+  return { id: 'p1', title: 'Ankara Gown', slug: 'ankara-gown', ...overrides };
+}
+
+function viewVariants(url: string) {
+  return {
+    thumb: null,
+    card: { url: '/card.jpg', w: 480, h: 480 },
+    card2x: { url: '/card2x.jpg', w: 800, h: 800 },
+    view: { url, w: 1600, h: 1600 },
+    original: { url: '/orig.jpg', w: 2400, h: 2400 },
+  };
+}
+
+describe('normalizeProduct images', () => {
+  it('carries backend images verbatim, ordered primary-first', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          thumbnail: 'https://cdn/x/thumb.jpg',
+          images: [
+            { id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Front', variants: null },
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side', variants: viewVariants('https://cdn/x/side-view.jpg') },
+          ],
+        },
+      }),
+    );
+
+    expect(product.media.images).toHaveLength(2);
+    expect(product.media.images?.[0]).toMatchObject({ id: 11, url: 'https://cdn/x/primary.jpg' });
+    expect(product.media.images?.[1]?.variants).toMatchObject({ view: { url: 'https://cdn/x/side-view.jpg' } });
+    // The featured shortcut is untouched.
+    expect(product.media.image).toBe('https://cdn/x/primary.jpg');
+  });
+
+  it('drops blank entries from a provided images list', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          images: [
+            { id: 11, url: '', alt: 'Blank' },
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+          ],
+        },
+      }),
+    );
+
+    expect(product.media.images?.map((i) => i.url)).toEqual(['https://cdn/x/side.jpg']);
+  });
+
+  it('falls back to gallery/image for old payloads: primary first, dupes removed', () => {
+    const product = normalizeProduct(
+      raw({
+        image: 'https://cdn/x/primary.jpg',
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          gallery: [
+            { id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Dupe of primary' },
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+            { id: 13, url: '', alt: 'Blank' },
+          ],
+        },
+      }),
+    );
+
+    expect(product.media.images?.map((i) => i.url)).toEqual([
+      'https://cdn/x/primary.jpg',
+      'https://cdn/x/side.jpg',
+    ]);
+    expect(product.media.images?.[0].id).toBe('main');
+  });
+
+  it('falls back to a raw-URL-only single and to [] when there is no imagery', () => {
+    const single = normalizeProduct(raw({ image: 'https://cdn/x/only.jpg' }));
+    expect(single.media.images?.map((i) => i.url)).toEqual(['https://cdn/x/only.jpg']);
+
+    const none = normalizeProduct(raw({}));
+    expect(none.media.images).toEqual([]);
+    expect(none.media.gallery).toEqual([]);
+  });
+
+  it('falls back when a provided images list is entirely blank', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          gallery: [{ id: 12, url: 'https://cdn/x/side.jpg' }],
+          images: [{ id: 11, url: '' }],
+        },
+      }),
+    );
+
+    expect(product.media.images?.map((i) => i.url)).toEqual([
+      'https://cdn/x/primary.jpg',
+      'https://cdn/x/side.jpg',
+    ]);
+  });
+});
+
+describe('getHoverImage / getSlideshowImages', () => {
+  const product = (urls: string[]): Product =>
+    normalizeProduct(
+      raw({
+        media: {
+          image: urls[0] ?? null,
+          images: urls.map((url, i) => ({ id: i + 1, url })),
+        },
+      }),
+    );
+
+  it('returns images[1] and null unless two images exist', () => {
+    expect(getHoverImage(product([]))).toBeNull();
+    expect(getHoverImage(product(['https://cdn/x/a.jpg']))).toBeNull();
+    expect(getHoverImage(product(['https://cdn/x/a.jpg', 'https://cdn/x/b.jpg']))).toBe(
+      'https://cdn/x/b.jpg',
+    );
+  });
+
+  it('returns the ordered slideshow list', () => {
+    const list = getSlideshowImages(product(['https://cdn/x/a.jpg', 'https://cdn/x/b.jpg']));
+    expect(list.map((i) => i.url)).toEqual(['https://cdn/x/a.jpg', 'https://cdn/x/b.jpg']);
+  });
+
+  it('treats a missing images key as no slideshow', () => {
+    const legacy = normalizeProduct(raw({ image: 'https://cdn/x/a.jpg' }));
+    delete legacy.media.images;
+    expect(getSlideshowImages(legacy)).toEqual([]);
+    expect(getHoverImage(legacy)).toBeNull();
+  });
+});
+
+describe('buildMediaFrames reads images', () => {
+  it('renders identical frames for a legacy payload and its images-carrying twin', () => {
+    const legacy = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          original: 'https://cdn/x/primary-orig.jpg',
+          gallery: [
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
+          ],
+        },
+      }),
+    );
+    delete legacy.media.images;
+
+    const next = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          original: 'https://cdn/x/primary-orig.jpg',
+          gallery: [
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
+          ],
+          images: [
+            { id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Ankara Gown' },
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
+          ],
+        },
+      }),
+    );
+
+    const legacyUrls = buildMediaFrames(legacy).map((f) => f.url);
+    const nextUrls = buildMediaFrames(next).map((f) => f.url);
+    expect(nextUrls).toEqual(legacyUrls);
+    expect(nextUrls).toEqual([
+      'https://cdn/x/primary-orig.jpg',
+      'https://cdn/x/side.jpg',
+      'https://cdn/x/back.jpg',
+    ]);
+  });
+
+  it('prefers the view tier off images entries and appends video last', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          images: [
+            { id: 11, url: 'https://cdn/x/primary.jpg', variants: viewVariants('https://cdn/x/primary-view.jpg') },
+            { id: 12, url: 'https://cdn/x/side.jpg' },
+          ],
+          video_url: 'https://cdn/x/clip.mp4',
+        },
+      }),
+    );
+
+    const frames = buildMediaFrames(product);
+    expect(frames.map((f) => f.type)).toEqual(['image', 'image', 'video']);
+    expect(frames[0].url).toBe('https://cdn/x/primary-view.jpg');
+    expect(frames[2].url).toBe('https://cdn/x/clip.mp4');
+  });
+});

package/types/product.ts

@@ -28,10 +28,28 @@ export interface ProductShop {
   rating_count: number;
 }
 
+/**
+ * One entry of the ordered `images` list (backend
+ * `CustomerProductMedia::orderedImages()`): primary first,
+ * `{id, url, alt, variants}`. The listing payload caps the list
+ * (`media.listing.images_limit`); detail/PDP carries the full gallery.
+ */
+export interface ProductImage {
+  id: string | number;
+  url: string;
+  alt?: string;
+  variants?: ImageVariants | null;
+}
+
 export interface ProductMedia {
   thumbnail: string | null;
   image: string | null;
   original?: string | null;
+  /** The ONE ordered product-image list, primary first. Present on both list
+   *  and detail responses once the backend emits it; the normalizer derives
+   *  it from `gallery`/`image` for older payloads, so readers must treat it
+   *  as always available and never build a second ordering. */
+  images?: ProductImage[];
   primary_variant_image?: string | null;
   video_url?: string | null;
   /** Falls back to `image` server-side when the vendor hasn't set an explicit
@@ -44,6 +62,10 @@ export interface ProductMedia {
   image_variants?: ImageVariants | null;
   /** Sibling to `primary_variant_image`, same contract. */
   primary_variant_image_variants?: ImageVariants | null;
+  /**
+   * @deprecated Use `images` instead — frozen legacy alias of the same
+   *  ordered list (primary first), kept for existing clients. Never extend.
+   */
   gallery?: Array<{
     id: string | number;
     url: string;

package/utils/product-media.ts

@@ -1,5 +1,5 @@
 import type { ImageVariants } from '../types/media';
-import type { Product } from '../types/product';
+import type { Product, ProductImage } from '../types/product';
 
 export interface MediaFrame {
   id: string;
@@ -21,47 +21,96 @@ function heroUrl(variants: ImageVariants | null | undefined): string | null {
   return variants?.view?.url ?? variants?.card2x?.url ?? null;
 }
 
+/**
+ * The ordered `media.images` list with blanks dropped — the single source
+ * for card hover/slideshow reads. Empty for products with no imagery at all.
+ */
+export function getSlideshowImages(product: Product): ProductImage[] {
+  const images = product.media.images;
+  if (!Array.isArray(images)) {
+    return [];
+  }
+
+  return images.filter(
+    (entry): entry is ProductImage =>
+      !!entry && typeof entry.url === 'string' && entry.url !== '',
+  );
+}
+
+/**
+ * The card hover-swap source: the second ordered image. Null unless the
+ * product carries at least two images — callers render the primary alone.
+ */
+export function getHoverImage(product: Product): string | null {
+  return getSlideshowImages(product)[1]?.url ?? null;
+}
+
 /**
  * Builds the ordered list of PDP gallery frames for a product: main image,
  * then gallery images, then the product video (if any) appended last — was
  * duplicated verbatim as `buildFrames`/`buildGalleryFrames` in every theme's
  * pages/product.tsx; centralized here per the project's reuse-over-duplication
  * rule. Pair with `ProductMediaFrame` to render whatever comes back.
+ *
+ * Reads `media.images` (primary first) when present and falls back to the
+ * legacy main+`gallery` pair for older payloads — same frames either way, so
+ * no visual change, only the data source moves to the ONE ordered list.
  */
 export function buildMediaFrames(product: Product): MediaFrame[] {
   const frames: MediaFrame[] = [];
-  const mainVariants = product.media.image_variants ?? null;
+  const images = getSlideshowImages(product);
 
-  if (product.media.image) {
-    frames.push({
-      id: 'main',
-      // WAS: `product.media.original ?? product.media.image` — which shipped the
-      // full raw original into every theme's PDP hero, unconditionally. Now the
-      // capped `view` tier (<=1600px webp) wins whenever the backend has one,
-      // and `original ?? image` survives untouched as the fallback for
-      // non-Media-backed images (external url, SVG, legacy upload) where
-      // image_variants is null. Themes that read `frame.url` directly get the
-      // downgrade for free; those that render through ProductMediaFrame also
-      // get a real srcset off `variants`.
-      url: heroUrl(mainVariants) ?? product.media.original ?? product.media.image,
-      alt: product.title,
-      type: 'image',
-      variants: mainVariants,
-    });
-  }
-
-  if (product.media.gallery) {
-    for (const item of product.media.gallery) {
+  if (images.length > 0) {
+    images.forEach((item, index) => {
       const itemVariants = item.variants ?? null;
       frames.push({
-        id: String(item.id),
-        // item.url is already the CARD url server-side (480px) — too small for a
-        // main hero frame, which is why the `view` tier is preferred here too.
-        url: heroUrl(itemVariants) ?? item.url,
+        id: index === 0 ? 'main' : String(item.id),
+        // Same hero-tier preference as the legacy path below: the capped
+        // `view` tier wins whenever the backend has one, and the raw
+        // `original` survives as the primary's fallback for non-Media-backed
+        // images where `variants` is null.
+        url:
+          heroUrl(itemVariants) ??
+          (index === 0 ? (product.media.original ?? item.url) : item.url),
         alt: item.alt ?? product.title,
         type: 'image',
         variants: itemVariants,
       });
+    });
+  } else {
+    const mainVariants = product.media.image_variants ?? null;
+
+    if (product.media.image) {
+      frames.push({
+        id: 'main',
+        // WAS: `product.media.original ?? product.media.image` — which shipped the
+        // full raw original into every theme's PDP hero, unconditionally. Now the
+        // capped `view` tier (<=1600px webp) wins whenever the backend has one,
+        // and `original ?? image` survives untouched as the fallback for
+        // non-Media-backed images (external url, SVG, legacy upload) where
+        // image_variants is null. Themes that read `frame.url` directly get the
+        // downgrade for free; those that render through ProductMediaFrame also
+        // get a real srcset off `variants`.
+        url: heroUrl(mainVariants) ?? product.media.original ?? product.media.image,
+        alt: product.title,
+        type: 'image',
+        variants: mainVariants,
+      });
+    }
+
+    if (product.media.gallery) {
+      for (const item of product.media.gallery) {
+        const itemVariants = item.variants ?? null;
+        frames.push({
+          id: String(item.id),
+          // item.url is already the CARD url server-side (480px) — too small for a
+          // main hero frame, which is why the `view` tier is preferred here too.
+          url: heroUrl(itemVariants) ?? item.url,
+          alt: item.alt ?? product.title,
+          type: 'image',
+          variants: itemVariants,
+        });
+      }
     }
   }
 

package/utils/product-normalizer.ts

@@ -3,6 +3,7 @@ import type {
   MetafieldValue,
   Product,
   ProductCategory,
+  ProductImage,
   ProductOption,
   ProductPricing,
   ProductVariantOptionValue,
@@ -209,6 +210,70 @@ function normalizeMetafields(raw: LegacyProductLike): Record<string, MetafieldVa
   return source as Record<string, MetafieldValue>;
 }
 
+function cleanUrl(value: unknown): string | null {
+  return typeof value === 'string' && value !== '' ? value : null;
+}
+
+/**
+ * The ONE ordered product-image list, primary first. A backend that already
+ * emits `media.images` wins verbatim (order preserved, entries cleaned);
+ * older payloads fall back to the `gallery`/`image` pair — primary first,
+ * then gallery items, skipping blanks and url-dupes of the primary. Never
+ * an empty-string url, never a null: no-media products get `[]`.
+ */
+function normalizeImages(raw: LegacyProductLike): ProductImage[] {
+  const media = raw.media ?? {};
+  const title = typeof raw.title === 'string' ? raw.title : '';
+
+  const provided = media.images;
+  if (Array.isArray(provided) && provided.length > 0) {
+    const cleaned = provided.flatMap((entry, index): ProductImage[] => {
+      const url = entry ? cleanUrl(entry.url) : null;
+      if (!url) {
+        return [];
+      }
+
+      return [
+        {
+          id: entry.id ?? `image-${index}`,
+          url,
+          alt: cleanUrl(entry.alt) ?? title,
+          variants: entry.variants ?? null,
+        },
+      ];
+    });
+    if (cleaned.length > 0) {
+      return cleaned;
+    }
+  }
+
+  const primary = cleanUrl(media.image) ?? cleanUrl(raw.image);
+  const seen = new Set<string>();
+  const items: ProductImage[] = [];
+
+  if (primary) {
+    items.push({ id: 'main', url: primary, alt: title, variants: media.image_variants ?? null });
+    seen.add(primary);
+  }
+
+  const gallery = Array.isArray(media.gallery) ? media.gallery : [];
+  gallery.forEach((entry, index) => {
+    const url = entry ? cleanUrl(entry.url) : null;
+    if (!url || seen.has(url)) {
+      return;
+    }
+    seen.add(url);
+    items.push({
+      id: entry.id ?? `gallery-${index}`,
+      url,
+      alt: cleanUrl(entry.alt) ?? title,
+      variants: entry.variants ?? null,
+    });
+  });
+
+  return items;
+}
+
 export function normalizeProduct(raw: LegacyProductLike): Product {
   const shopId = String(raw.shop_id ?? raw.vendor_id ?? raw.shop?.id ?? raw.vendor?.id ?? '');
 
@@ -257,6 +322,10 @@ export function normalizeProduct(raw: LegacyProductLike): Product {
       // covers a preview/demo payload that happens to nest them there too.
       video_url: raw.media?.video_url ?? raw.video_url ?? null,
       video_poster_url: raw.media?.video_poster_url ?? raw.video_poster_url ?? null,
+      // The ONE ordered list (primary first) — backend `images` verbatim when
+      // present, else derived from gallery/image above. `gallery` stays as
+      // the deprecated frozen alias for existing readers.
+      images: normalizeImages(raw),
       // Pass-through: gallery items carry their own `variants` (ProductResource::
       // buildGalleryPayload) and are not field-whitelisted here.
       gallery: raw.media?.gallery ?? [],