@usequeek/theme-kit 0.1.0

package/types/vendor.ts

@@ -0,0 +1,243 @@
+import type { Menu } from './menu';
+import type { ImageVariants } from './media';
+
+export interface BrandFont {
+  heading: string;
+  body: string;
+}
+
+/**
+ * Semantic design-token shapes — the FROZEN contract
+ * (`.agent/.tmp/design-token-contract.md` in queek_backend). Backend resolves
+ * theme defaults ← legacy vendor fields ← vendor `tokens` overrides and
+ * returns this object under `StorefrontConfig.tokens`. Every field is
+ * optional: during the transition many vendors have no `tokens` at all, and
+ * the storefront injector (`lib/core/utils/brand.ts`) fills every gap with a
+ * sane default so it can never crash or omit a CSS var.
+ */
+export type DesignColorScheme = 'light' | 'dark';
+export type DesignScaleRatio = 1.125 | 1.2 | 1.25 | 1.333;
+export type DesignHeadingCase = 'none' | 'upper' | 'small-caps';
+export type DesignDensity = 'compact' | 'cozy' | 'comfortable';
+export type DesignRadius = 'sharp' | 'soft' | 'rounded' | 'pill';
+export type DesignBorderWeight = 'hairline' | 'medium' | 'bold';
+export type DesignElevation = 'flat' | 'subtle' | 'lifted';
+export type DesignMotion = 'none' | 'subtle' | 'lively';
+export type DesignImageRadius = 'sharp' | 'soft' | 'rounded';
+export type DesignImageFit = 'cover' | 'contain';
+export type DesignImageFilter = 'none' | 'mono' | 'warm';
+
+export interface DesignTokenColor {
+  scheme?: DesignColorScheme;
+  bg?: string;
+  surface?: string;
+  surface_muted?: string;
+  text?: string;
+  text_muted?: string;
+  primary?: string;
+  accent?: string;
+  on_accent?: string;
+  border?: string;
+  success?: string;
+  warning?: string;
+  danger?: string;
+}
+
+export interface DesignTokenType {
+  heading_font?: string;
+  body_font?: string;
+  scale_ratio?: DesignScaleRatio;
+  heading_weight?: number;
+  body_weight?: number;
+  heading_case?: DesignHeadingCase;
+  heading_tracking?: number;
+  body_tracking?: number;
+}
+
+export interface DesignTokenSpace {
+  density?: DesignDensity;
+}
+
+export interface DesignTokenShape {
+  radius?: DesignRadius;
+  border_weight?: DesignBorderWeight;
+}
+
+export interface DesignTokenImage {
+  radius?: DesignImageRadius;
+  fit?: DesignImageFit;
+  filter?: DesignImageFilter;
+}
+
+export interface DesignTokens {
+  color?: DesignTokenColor;
+  type?: DesignTokenType;
+  space?: DesignTokenSpace;
+  shape?: DesignTokenShape;
+  elevation?: DesignElevation;
+  motion?: DesignMotion;
+  image?: DesignTokenImage;
+}
+
+/**
+ * One of the 7 top-level design-token dimensions.
+ */
+export type DesignTokenAxis = keyof DesignTokens;
+
+/**
+ * A single stylable LEAF inside those 7 dimensions. `ThemeManifestVariant.editable`
+ * lists exactly which of these a variant's rendered markup/CSS actually consumes —
+ * not just the parent dimension as a whole. A dimension with multiple UI sub-controls
+ * (shape → radius + border_weight; image → radius + fit + filter; color → primary +
+ * accent) can be live on ONE sub-control while hardcoded on another — e.g. a
+ * variant's `<img>` genuinely reads `--image-fit`/`--image-filter` while its
+ * container's radius is a hardcoded literal, or a button's border reads
+ * `--border-weight` while its radius doesn't. Declaring only the dimension name
+ * (e.g. `'shape'`) would show a dead sub-dial next to a live one — this is the
+ * exact 2026-08-03 gap found in Allure's products/carousel section (Image radius
+ * and Corner radius dead, Image fit/filter and Border weight live, all under the
+ * same 'shape'/'image' bundle). `type`/`elevation`/`motion` have no UI sub-controls
+ * today, so they stay bare (no `.field` suffix) — add one here the day a sub-dial
+ * is added for them.
+ */
+export type DesignTokenAxisPath =
+  | 'color.primary'
+  | 'color.accent'
+  | 'type'
+  | 'space.density'
+  | 'shape.radius'
+  | 'shape.border_weight'
+  | 'elevation'
+  | 'motion'
+  | 'image.radius'
+  | 'image.fit'
+  | 'image.filter';
+
+export interface BrandPalette {
+  primary: string;
+  accent: string;
+  background: string;
+  surface: string;
+  text: string;
+  text_muted: string;
+  border: string;
+}
+
+export interface Brand {
+  id: string;
+  name: string;
+  mode: 'light' | 'dark';
+  font_key?: string;
+  font?: BrandFont;
+  colors: BrandPalette;
+}
+
+export interface VendorProfile {
+  id: string;
+  slug: string | null;
+  name: string | null;
+  logo: string | null;
+  banner?: string | null;
+  /** VendorResource:126-127. Sits beside the unchanged raw `logo`/`banner`
+   *  urls; null when the file has no Media row (common on older vendors). */
+  logo_variants?: ImageVariants | null;
+  banner_variants?: ImageVariants | null;
+  tagline?: string | null;
+  address?: string | null;
+  delivery_time?: string | null;
+  currency?: string | null;
+  rating_value?: number;
+  rating_count?: number;
+  rating_label?: string | null;
+}
+
+export interface StorefrontConfig {
+  theme: string;
+  brand: Brand;
+  available_brands?: Array<{ id: string; name: string }>;
+  header?: {
+    variant?: string;
+    logo_url?: string | null;
+    announcement?: {
+      enabled: boolean;
+      text: string;
+      link?: string | null;
+    } | null;
+    show_search?: boolean;
+    show_cart?: boolean;
+    show_account?: boolean;
+    show_offers?: boolean;
+  };
+  footer?: {
+    variant?: string;
+    heading?: string | null;
+    tagline?: string | null;
+    columns?: Array<{ heading: string; content: string }>;
+    socials?: Record<string, string>;
+    copyright?: string | null;
+    bg?: string | null;
+    text?: string | null;
+    muted?: string | null;
+  };
+  colors?: Partial<BrandPalette> & { button?: string; button_text?: string };
+  typography?: {
+    font?: string;
+    heading?: string;
+    body?: string;
+  };
+  /** Resolved semantic design tokens (see design-token-contract.md). Absent for stores not yet migrated. */
+  tokens?: DesignTokens | null;
+  menus?: {
+    header?: Menu;
+    footer?: Menu;
+  };
+  default_variants?: Record<string, string>;
+  pages?: Record<string, {
+    banner?: string;
+    title?: string;
+    subtitle?: string;
+    /** QR-only header overrides, each falling back to the vendor's own
+     * profile field when unset (see QrHeader). `phones` has NO vendor
+     * fallback — the vendor's own support_phone is deliberately masked in
+     * the public API (Customer\VendorResource — anti-scraping/privacy), so
+     * a phone only ever shows on the QR page if explicitly published here. */
+    address?: string;
+    slogan?: string;
+    phones?: string[];
+    /** QR page footer (only emitted for `pages.qr` when in-store ordering is on). */
+    footer?: {
+      enabled?: boolean;
+      text?: string;
+      show_socials?: boolean;
+    };
+    /** QR product-row layout (only emitted for `pages.qr`). Defaults to 'row'. */
+    listing_style?: 'row' | 'stacked';
+    /** Darkening scrim over the QR home page's collection/category card
+     * images (only emitted for `pages.qr`). Defaults to 'medium' — bright
+     * vendor photos otherwise swallow the white card label. */
+    tile_overlay?: 'none' | 'light' | 'medium' | 'strong';
+    seo?: {
+      title?: string;
+      description?: string;
+      og_image?: string;
+      keywords?: string[];
+      canonical_url?: string;
+      noindex?: boolean;
+    };
+  }>;
+  apps?: {
+    whatsapp_chat?: { enabled?: boolean; number?: string; message?: string; position?: string; bottom_offset?: number };
+    analytics?: { enabled?: boolean; ga_id?: string };
+    follow_card?: { enabled?: boolean; display?: 'floating' | 'footer' | 'block'; position?: string };
+    subscribe?: {
+      enabled?: boolean;
+      variant?: string;
+      heading?: string;
+      tagline?: string;
+      cta?: string;
+      /** `modal` variant only — when it should pop up. Backend field pending; defaults to 'scroll' when unset. */
+      trigger?: 'immediate' | 'delay' | 'scroll';
+    };
+  };
+  followers_count?: number;
+}

package/utils/addon-selection.ts

@@ -0,0 +1,31 @@
+import type { ProductAddon } from '../types/product';
+import type { CartAddon } from '../types/cart';
+
+/**
+ * Every PDP `pages/product.tsx` tracks addon picks as a `Set<"addonId:itemId">`
+ * (see each theme's `toggleAddon`). This turns that selection into the
+ * `CartAddon[]` shape `addItemWithAddons` actually persists — the piece every
+ * theme's PDP was missing, so a customer's addon/pack picks were silently
+ * dropped on add-to-cart regardless of what the UI showed them selecting.
+ */
+export function resolveSelectedAddons(addons: ProductAddon[], selected: Set<string>): CartAddon[] {
+  const result: CartAddon[] = [];
+  for (const addon of addons) {
+    for (const item of addon.items) {
+      if (selected.has(`${addon.id}:${item.id}`)) {
+        result.push({ addon_id: addon.id, item_id: item.id, name: item.display_name ?? item.name, price: item.price });
+      }
+    }
+  }
+  return result;
+}
+
+/** True once every required addon group's minimum is met by `selected`. */
+export function requiredAddonsSatisfied(addons: ProductAddon[], selected: Set<string>): boolean {
+  return addons
+    .filter((addon) => addon.required)
+    .every((addon) => {
+      const count = addon.items.filter((item) => selected.has(`${addon.id}:${item.id}`)).length;
+      return count >= Math.max(1, addon.min || 1);
+    });
+}

package/utils/benefit-icon.tsx

@@ -0,0 +1,145 @@
+/**
+ * Shared icon-keyword vocabulary for "benefit row" content blocks (glow's
+ * `trust-badges`, any theme's `features-columns`, and similar icon+title+text
+ * item lists). qee generates a short keyword per item (e.g. "star", "truck"),
+ * never raw SVG markup — themes render that keyword through this resolver
+ * instead of each theme re-declaring its own switch (glow and allure both
+ * had one, independently, before this was extracted) or a theme trying to
+ * `dangerouslySetInnerHTML` the keyword directly (renders as literal text,
+ * not an icon — the bug that prompted this).
+ *
+ * `currentColor` throughout — the caller controls color via CSS `color` on
+ * an ancestor, same convention every existing usage already followed.
+ */
+export const BENEFIT_ICON_KEYS = [
+  'check',
+  'shipping',
+  'leaf',
+  'shield',
+  'star',
+  'wallet',
+  'refresh',
+  'heart',
+  'gift',
+  'clock',
+  'lock',
+  'sparkle',
+] as const;
+
+export type BenefitIconKey = (typeof BENEFIT_ICON_KEYS)[number];
+
+const PATHS: Record<BenefitIconKey, JSX.Element> = {
+  check: <path d="M5 12.5l4.5 4.5L19 7" />,
+  shipping: (
+    <>
+      <path d="M3 7h11v9H3zM14 10h4l3 3v3h-7z" />
+      <circle cx="7.5" cy="18" r="1.6" />
+      <circle cx="17.5" cy="18" r="1.6" />
+    </>
+  ),
+  leaf: (
+    <>
+      <path d="M20 4C10 4 4 10 4 18c8 0 14-6 14-14z" />
+      <path d="M6 18c4-4 8-6 12-10" />
+    </>
+  ),
+  shield: <path d="M12 3l7 3v6c0 5-3.5 7.5-7 9-3.5-1.5-7-4-7-9V6z" />,
+  star: <path d="M12 3.5l2.6 5.6 6.1.7-4.5 4.2 1.2 6-5.4-3-5.4 3 1.2-6-4.5-4.2 6.1-.7z" />,
+  wallet: (
+    <>
+      <rect x="3" y="6" width="18" height="13" rx="2" />
+      <path d="M3 10h18" />
+      <circle cx="16.5" cy="14" r="1.2" />
+    </>
+  ),
+  refresh: (
+    <>
+      <path d="M4 12a8 8 0 0 1 13.66-5.66L20 8" />
+      <path d="M20 4v4h-4" />
+      <path d="M20 12a8 8 0 0 1-13.66 5.66L4 16" />
+      <path d="M4 20v-4h4" />
+    </>
+  ),
+  heart: <path d="M12 20.5S3.5 15 3.5 9a4.5 4.5 0 0 1 8.5-2 4.5 4.5 0 0 1 8.5 2c0 6-8.5 11.5-8.5 11.5z" />,
+  gift: (
+    <>
+      <rect x="4" y="9" width="16" height="11" rx="1" />
+      <path d="M4 13h16M12 9v11" />
+      <path d="M12 9c-1.5-4-6-4-6-1.5S9 9 12 9zM12 9c1.5-4 6-4 6-1.5S15 9 12 9z" />
+    </>
+  ),
+  clock: (
+    <>
+      <circle cx="12" cy="12" r="9" />
+      <path d="M12 7v5l3.5 2" />
+    </>
+  ),
+  lock: (
+    <>
+      <rect x="5" y="11" width="14" height="9" rx="1.5" />
+      <path d="M8 11V7a4 4 0 0 1 8 0v4" />
+    </>
+  ),
+  sparkle: (
+    <>
+      <path d="M12 3l1.6 5.4L19 10l-5.4 1.6L12 17l-1.6-5.4L5 10l5.4-1.6z" />
+    </>
+  ),
+};
+
+// Synonyms qee has actually generated in practice for a key in BENEFIT_ICON_KEYS
+// (confirmed live: "truck" for a shipping/delivery benefit) — the AI is given
+// the canonical keyword list in the manifest/prompt, but a close synonym
+// should still resolve to the right icon instead of silently falling back.
+const ALIASES: Record<string, BenefitIconKey> = {
+  truck: 'shipping',
+  delivery: 'shipping',
+  return: 'refresh',
+  returns: 'refresh',
+  secure: 'shield',
+  security: 'shield',
+  guarantee: 'shield',
+  quality: 'star',
+  payment: 'wallet',
+  price: 'wallet',
+  // Carried over from glow's pre-shared TrustIcon switch — real demo data
+  // and, presumably, real qee-generated pages already use this word.
+  sustainability: 'leaf',
+};
+
+/** A vendor-uploaded icon takes over from the fixed keyword vocabulary — checked
+ *  on the ORIGINAL casing (a URL path can be case-sensitive) before the
+ *  keyword lookup below lowercases its own input. */
+function isImageUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value) || value.startsWith('/');
+}
+
+export function BenefitIcon({ icon, className }: { icon?: string; className?: string }): JSX.Element {
+  const trimmed = (icon ?? '').trim();
+
+  if (isImageUrl(trimmed)) {
+    // Fixed-size icon slot, not a content photo — the shared <Image>
+    // wrapper's placeholder/lazy-load machinery is built for larger,
+    // layout-affecting media.
+    // eslint-disable-next-line @next/next/no-img-element
+    return <img src={trimmed} alt="" className={className} loading="lazy" />;
+  }
+
+  const raw = trimmed.toLowerCase();
+  const key = ALIASES[raw] ?? raw;
+  const body = PATHS[key as BenefitIconKey] ?? PATHS.check;
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      {body}
+    </svg>
+  );
+}

package/utils/brand-palette.ts

@@ -0,0 +1,64 @@
+import type { StorefrontConfig } from '../types/vendor';
+import type { PlaceholderPalette } from './placeholder-resolver';
+
+const FALLBACK: PlaceholderPalette = {
+  from: '#e8e4df',
+  to: '#c9c3ba',
+  text: '#1a1a1a',
+};
+
+/**
+ * Build a two-stop gradient palette from the current storefront config.
+ *
+ * Reads in this order of preference:
+ *   config.colors.surface / config.colors.background / config.colors.text
+ *   → config.brand.colors.surface / ... / .text
+ *   → neutral fallback
+ */
+export function resolveBrandPalette(config?: StorefrontConfig | null): PlaceholderPalette {
+  if (!config) return FALLBACK;
+
+  const override = config.colors ?? {};
+  const brand = config.brand?.colors;
+
+  const from = override.surface ?? brand?.surface ?? override.background ?? brand?.background ?? FALLBACK.from;
+  const to = override.background ?? brand?.background ?? override.surface ?? brand?.surface ?? FALLBACK.to;
+  const text = override.text ?? brand?.text ?? FALLBACK.text;
+
+  // If surface and background resolve to the same value, shift the gradient
+  // stops slightly so it doesn't look flat.
+  if (from === to) {
+    return { from, to: shade(to, -0.08), text };
+  }
+
+  return { from, to, text };
+}
+
+/**
+ * Apply a lightness delta to a hex color. Negative darkens, positive lightens.
+ * Returns a hex string. Internal helper.
+ */
+function shade(hex: string, delta: number): string {
+  const cleaned = hex.replace('#', '');
+  if (cleaned.length !== 3 && cleaned.length !== 6) return hex;
+
+  const expanded =
+    cleaned.length === 3
+      ? cleaned
+          .split('')
+          .map((c) => c + c)
+          .join('')
+      : cleaned;
+
+  const r = parseInt(expanded.slice(0, 2), 16);
+  const g = parseInt(expanded.slice(2, 4), 16);
+  const b = parseInt(expanded.slice(4, 6), 16);
+
+  const adjust = (value: number): number => {
+    const next = Math.round(value + 255 * delta);
+    return Math.max(0, Math.min(255, next));
+  };
+
+  const hex2 = (value: number): string => value.toString(16).padStart(2, '0');
+  return `#${hex2(adjust(r))}${hex2(adjust(g))}${hex2(adjust(b))}`;
+}