@usequeek/theme-kit 0.1.0

package/types/product.ts

@@ -0,0 +1,279 @@
+import type { ImageVariants } from './media';
+
+export type ProductKind = 'physical' | 'service' | 'digital';
+export type ProductStatus = 'active' | 'inactive';
+
+export interface ProductPriceRange {
+  min_amount: number;
+  max_amount: number;
+}
+
+export interface ProductPricing {
+  base_amount: number;
+  sale_amount: number;
+  compare_at_amount: number;
+  discount_amount: number;
+  discount_percent: number;
+  is_price_from: boolean;
+  tax_inclusive: boolean;
+  price_range: ProductPriceRange;
+}
+
+export interface ProductShop {
+  id: string;
+  name: string | null;
+  slug: string | null;
+  logo: string | null;
+  rating: number;
+  rating_count: number;
+}
+
+export interface ProductMedia {
+  thumbnail: string | null;
+  image: string | null;
+  original?: string | null;
+  primary_variant_image?: string | null;
+  video_url?: string | null;
+  /** Falls back to `image` server-side when the vendor hasn't set an explicit
+   *  poster (ProductResource::resolveVideoPosterUrl) — always a usable value
+   *  whenever video_url is set. */
+  video_poster_url?: string | null;
+  /** Srcset tier map for `image` (ProductResource::buildBaseMediaPayload /
+   *  buildDetailMediaPayload — present on BOTH list and detail responses).
+   *  null when the primary image isn't Media-backed. */
+  image_variants?: ImageVariants | null;
+  /** Sibling to `primary_variant_image`, same contract. */
+  primary_variant_image_variants?: ImageVariants | null;
+  gallery?: Array<{
+    id: string | number;
+    url: string;
+    alt?: string;
+    /** Per-gallery-item tier map (ProductResource::buildGalleryPayload).
+     *  Detail responses only — the list payload has no `gallery` at all.
+     *  Note `url` here is already the CARD url server-side, not the original. */
+    variants?: ImageVariants | null;
+  }>;
+}
+
+export interface ProductInventory {
+  in_stock: boolean;
+  tracking: boolean;
+  quantity: number;
+}
+
+export interface ProductReviewSummary {
+  rating: number;
+  review_count: number;
+}
+
+export interface ProductCategory {
+  id: string;
+  name: string;
+  slug: string;
+}
+
+export interface ProductOptionValue {
+  value: string;
+  label: string;
+  color_code: string | null;
+  /** Representative image for this option value (e.g. the "Denim" swatch's variant photo) —
+   *  used when there's no color_code to render as a swatch (standard e-commerce pattern:
+   *  color if color, else image if image, else text). */
+  image: string | null;
+}
+
+export interface ProductOption {
+  name: string;
+  type: string | null;
+  values: ProductOptionValue[];
+}
+
+export interface ProductVariantOptionValue {
+  option_name: string;
+  value: string;
+}
+
+export interface ProductVariant {
+  id: string;
+  sku: string | null;
+  /** Printed barcode / GTIN (EAN-13/8, UPC-A/E) for in-store scan-to-cart. */
+  barcode: string | null;
+  title: string | null;
+  option_values: ProductVariantOptionValue[];
+  pricing: {
+    base_amount: number;
+    sale_amount: number;
+    compare_at_amount: number;
+    discount_amount: number;
+    discount_percent: number;
+  };
+  inventory: {
+    in_stock: boolean;
+    tracking: boolean;
+    quantity: number;
+  };
+  media: ProductMedia;
+  weight: string | null;
+  position: number | null;
+  is_active: boolean;
+}
+
+export interface ProductAddonItem {
+  id: string;
+  name: string;
+  display_name: string | null;
+  price: number;
+  in_stock: boolean;
+}
+
+export interface ProductAddon {
+  id: string;
+  title: string;
+  min: number;
+  max: number;
+  required: boolean;
+  multiple_selection: boolean;
+  /** Every item in the group is takeaway/delivery packaging rather than a real
+   *  product choice. A required pack group is only genuinely required when the
+   *  order leaves the premises — dine-in customers eat off a plate, so forcing
+   *  one on them blocks checkout. Backend-derived; never re-derive it here. */
+  is_pack_group?: boolean;
+  items: ProductAddonItem[];
+}
+
+export interface ProductReview {
+  id: string;
+  title: string | null;
+  description: string | null;
+  rating: number;
+  customer_name: string | null;
+  created_at: string | null;
+}
+
+export interface ProductFlags {
+  featured: boolean;
+  is_marketplace: boolean;
+  is_wholesale: boolean;
+  is_new: boolean;
+}
+
+export interface Product {
+  shop_id: string;
+  id: string;
+  p_id: number;
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  description: string | null;
+  kind: ProductKind;
+  status: ProductStatus;
+  /** Printed barcode / GTIN for products without variants. Variant-level
+   *  barcodes live on `variants[].barcode`. Powers QR in-store scan-to-cart. */
+  barcode: string | null;
+  currency: string;
+  pricing: ProductPricing;
+  shop: ProductShop;
+  media: ProductMedia;
+  inventory: ProductInventory;
+  variants_count: number;
+  review_summary: ProductReviewSummary;
+  flags: ProductFlags;
+  categories: ProductCategory[];
+  options: ProductOption[];
+  variants: ProductVariant[];
+  addons: ProductAddon[];
+  reviews: ProductReview[];
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface ProductListMeta {
+  next_cursor?: string | null;
+  has_more?: boolean;
+}
+
+export interface ApiResponse<T, M = Record<string, unknown>> {
+  data: T;
+  message?: string;
+  meta?: M;
+  /** Present on Laravel `simplePaginate()` resource responses (e.g. collection
+   *  products) — that paginator never computes a total/last-page count (it's
+   *  deliberately cheap on large catalogues), so `links.next`/`links.prev`
+   *  (a URL or null) is the only reliable "is there another page" signal,
+   *  not `meta.has_more` or a page count. */
+  links?: {
+    first?: string | null;
+    last?: string | null;
+    prev?: string | null;
+    next?: string | null;
+  };
+}
+
+export interface LegacyProductLike {
+  id?: string;
+  p_id?: number;
+  title?: string;
+  slug?: string;
+  excerpt?: string | null;
+  description?: string | null;
+  compare_at_price?: number | null;
+  rating?: number;
+  review_count?: number;
+  kind?: string;
+  type?: string;
+  status?: string;
+  barcode?: string | null;
+  currency?: string;
+  price?: number;
+  discount_price?: number;
+  is_price_from?: boolean;
+  shop_id?: string;
+  vendor_id?: string;
+  thumbnail?: string | null;
+  image?: string | null;
+  // Sibling top-level fields on the real backend payload (ProductResource::
+  // buildBasePayload) — NOT nested under `media` server-side, unlike
+  // image/thumbnail which are sent in both places.
+  video_url?: string | null;
+  video_poster_url?: string | null;
+  stock?: number;
+  in_stock?: boolean;
+  inventory_tracking?: boolean;
+  pricing?: Partial<ProductPricing>;
+  inventory?: Partial<ProductInventory>;
+  flags?: Partial<ProductFlags>;
+  media?: Partial<ProductMedia>;
+  categories?: Array<Partial<ProductCategory>>;
+  options?: Array<{
+    name?: string;
+    type?: string | null;
+    values?: Array<string | Partial<ProductOptionValue>>;
+    values_detailed?: Array<Partial<ProductOptionValue>>;
+  }>;
+  variants?: Array<
+    Omit<Partial<ProductVariant>, 'option_values'> & {
+      // Partial<ProductVariant>'s own option_values is a plain array; a raw/legacy payload can
+      // also send it as a {optionName: value} map (normalizeVariantOptionValues handles both) —
+      // intersecting the two types directly collapses to an unsatisfiable type, hence the Omit.
+      option_values?: ProductVariantOptionValue[] | Record<string, string>;
+      // The backend sends a variant's own price/stock as FLAT fields (see
+      // ProductResource::resolveShopVariants), never nested under pricing/inventory —
+      // those nested keys only exist if some other caller pre-shapes the payload.
+      price?: number;
+      discount_price?: number;
+      compare_at_price?: number | null;
+      discount_amount?: number;
+      has_discount?: boolean;
+      in_stock?: boolean;
+      stock?: number;
+      track_inventory?: boolean;
+    }
+  >;
+  addons?: ProductAddon[];
+  reviews?: ProductReview[];
+  review_summary?: Partial<ProductReviewSummary>;
+  created_at?: string | null;
+  updated_at?: string | null;
+  shop?: Partial<ProductShop>;
+  vendor?: Partial<ProductShop>;
+}

package/types/theme.ts

@@ -0,0 +1,380 @@
+import type { FC, ReactNode } from 'react';
+import type { Block, BlockDataMap, BlockType, BlogBlockData, CategoriesBlockData, ProductsBlockData } from './block';
+import type { CartItem as CartLineItem } from './cart';
+import type { ImageVariants } from './media';
+import type { MenuItem } from './menu';
+import type { BlogCategory, Collection, Page, Pagination, Post } from './page';
+import type { Product } from './product';
+import type { DesignTokenAxisPath, DesignTokens, StorefrontConfig, VendorProfile } from './vendor';
+
+export interface HomePageProps {
+  blocks: Block[];
+}
+
+export interface GenericPageProps {
+  page: Page;
+}
+
+export interface BlogPageProps {
+  posts: Post[];
+  pagination?: Pagination;
+  /** Vendor blog categories with >=1 live post (for the filter bar). */
+  categories?: BlogCategory[];
+  /** Currently-filtered category slug, if any. */
+  activeCategory?: string;
+}
+
+export interface PostPageProps {
+  post: Post;
+}
+
+export interface CollectionsPageProps {
+  collections: Collection[];
+}
+
+export interface PoliciesPageProps {
+  /** Published policies (returns, shipping, privacy, terms, …). Each is a
+   *  `Page` with `type: 'policy'`; its detail view resolves through the
+   *  generic `/[vendor]/[slug]` route. */
+  policies: Page[];
+}
+
+export interface ShopCategory {
+  id: string;
+  slug: string;
+  name: string;
+  image?: string | null;
+  /** TaxonomyCategoryResource:22 — attached to every node of the tree
+   *  (MediaVariantMap::attachUrlVariants walks `children` too). */
+  image_variants?: ImageVariants | null;
+  products_count?: number;
+  children?: ShopCategory[];
+}
+
+export interface ShopPageProps {
+  categories: ShopCategory[];
+}
+
+export interface CollectionPageProps {
+  collection: Collection;
+  products: Product[];
+  pagination?: Pagination;
+}
+
+export interface ProductPageProps {
+  product: Product;
+}
+
+export interface GalleryPageProps {
+  gallery: Page;
+}
+
+export interface LayoutProps {
+  children: ReactNode;
+}
+
+export interface SubscribeFormProps {
+  heading?: string;
+  tagline?: string;
+  cta?: string;
+}
+
+export interface HeaderProps {
+  menu: MenuItem[];
+  logo?: string | null;
+  announcement?: {
+    enabled: boolean;
+    text: string;
+    link?: string | null;
+  } | null;
+  /** Site-wide header icon visibility — all default true (see config.header.show_*). */
+  showSearch?: boolean;
+  showCart?: boolean;
+  showAccount?: boolean;
+  /** Theme-specific extra header icon (currently only glow/overlay's "Offers" shortcut). */
+  showOffers?: boolean;
+}
+
+export interface FooterProps {
+  /** Footer brand heading override; falls back to the vendor name. */
+  heading?: string | null;
+  /** Footer brand description/tagline override; falls back to vendor.tagline. */
+  tagline?: string | null;
+  columns?: Array<{ heading: string; content: string }>;
+  socials?: Record<string, string>;
+  copyright?: string | null;
+}
+
+export interface CartShellProps {
+  items: CartLineItem[];
+  currency: string;
+  total: number;
+  empty: boolean;
+  onIncrease: (id: string, shopId: string) => void;
+  onDecrease: (id: string, shopId: string) => void;
+  onRemove: (id: string, shopId: string) => void;
+}
+
+export interface CheckoutShellProps {
+  cartItems: ReactNode;
+  deliveryModes: ReactNode;
+  addressPicker: ReactNode | null;
+  /** Rendered when two delivery options (queek/vendor) are available for customer selection */
+  deliverySourcePicker: ReactNode | null;
+  /** Rendered when delivery_mode is 'shipping' — lets customer pick a shipping zone */
+  shippingZonePicker: ReactNode | null;
+  schedulePicker: ReactNode | null;
+  paymentPicker: ReactNode;
+  promoInput: ReactNode;
+  noteInputs: ReactNode;
+  feesBreakdown: ReactNode;
+  deliveryMessage: { type: 'warning' | 'danger'; message: string } | null;
+  submitButton: ReactNode;
+  /** Whether the customer is signed in. Shells that skip the summary→checkout
+   *  step (e.g. the QR single-modal sheet) use this to show a sign-in CTA that
+   *  routes guests into the auth flow via `onTabChange('checkout')`. */
+  isAuthenticated?: boolean;
+  activeTab: 'summary' | 'checkout';
+  onTabChange: (tab: 'summary' | 'checkout') => void;
+  onBack?: () => void;
+  totalCount: number;
+  subtotal: number;
+  currency: string;
+  mode?: 'page' | 'panel';
+  /** Published policies (refund/shipping/privacy/terms) for the checkout footer links. */
+  policies: Page[];
+}
+
+export interface LoginShellProps {
+  children: ReactNode;
+}
+
+export interface SignupShellProps {
+  children: ReactNode;
+}
+
+export interface AccountShellProps {
+  children: ReactNode;
+}
+
+export interface ProductCardProps {
+  product: Product;
+  href?: string;
+}
+
+export interface ThemeContextValue {
+  vendor: VendorProfile;
+  config: StorefrontConfig;
+}
+
+export interface ProductsBlockProps extends ProductsBlockData {
+  products?: Product[];
+}
+
+export interface CategoriesBlockProps extends CategoriesBlockData {
+  categories?: Array<{ id: string; slug: string; name: string; image?: string | null }>;
+}
+
+export interface BlogBlockProps extends BlogBlockData {
+  posts?: Post[];
+}
+
+export type ThemeManifestFieldType =
+  | 'string'
+  | 'text'
+  | 'markdown'
+  | 'image'
+  | 'url'
+  | 'int'
+  | 'number'
+  | 'boolean'
+  | 'color'
+  | 'string[]'
+  | 'object'
+  | 'object[]'
+  | 'enum';
+
+export interface ThemeManifestField {
+  type: ThemeManifestFieldType;
+  required?: boolean;
+  note?: string;
+  default?: string | number | boolean | null;
+  options?: string[];
+  of?: Record<string, ThemeManifestField>;
+}
+
+export interface ThemeManifestVariant {
+  id: string;
+  label: string;
+  default?: boolean;
+  purpose?: string;
+  /**
+   * The data fields this variant's component actually renders. During the
+   * incremental migration, an existing prose string remains valid. Converted
+   * content fields use FieldDefinition so the merchant editor reads a closed
+   * control type while Qee receives the same explanatory note from the backend.
+   */
+  fields?: Record<string, string | ThemeManifestField>;
+  /**
+   * Which design-token LEAVES (`DesignTokenAxisPath` — see its doc comment
+   * in vendor.ts) this variant's rendered markup actually consumes via CSS
+   * vars, i.e. which controls a per-section `block.tokens` override on THIS
+   * variant will visibly change. Authored next to the component/CSS that
+   * consumes the vars so it can't drift — flows verbatim through
+   * generate-theme-registry.ts → registry.json → Laravel's Theme.variants →
+   * ThemeManifestService (mirrors `fields`).
+   *
+   * Granular per sub-control, NOT per parent dimension — `'shape'` is not a
+   * valid entry; declare `'shape.radius'` and/or `'shape.border_weight'`
+   * independently, since one can be CSS-var-driven while the other is a
+   * hardcoded literal on the same or a sibling element (same for `image.*`
+   * and `color.*`). Declare `image.*` entries only once that variant's image
+   * element(s) are actually wired to the corresponding `--image-*` var (see
+   * each theme's own theme.css). If a variant renders no image, omit all
+   * `image.*` entries.
+   *
+   * No back-compat default: an omitted `editable` (or an omitted leaf) means
+   * NOT stylable for that control — every variant in every theme has an
+   * explicit, audited array as of the 2026-08-03 granular pass.
+   */
+  editable?: DesignTokenAxisPath[];
+  /**
+   * Business buckets this variant is a strong fit for, as
+   * `config/category_packs.php` keys ONLY (queek_backend): food | supermarket |
+   * product | pharmacy | laundry | delivery | service | gas-refill |
+   * local_market. Omitted = universal. Authored next to the component (same
+   * anti-drift placement as `fields`/`editable`) and flows verbatim through
+   * generate-theme-registry.ts -> registry.json -> Laravel's Theme.variants ->
+   * ThemeManifestService, where BuildHomepageTool's scored resolver boosts a
+   * bucket match when auto-building a store. The backend matches buckets with
+   * `_`/`-` treated as equivalent.
+   */
+  best_for?: string[];
+  /**
+   * Default true. false = the AI store builder must never auto-select this
+   * variant (special-purpose layouts: review-screenshot walls, decorative
+   * galleries, checkout/focused chrome). Manual/qee selection stays allowed.
+   */
+  auto_pick?: boolean;
+  /**
+   * Gallery scope only: minimum slides this variant needs to render well
+   * (e.g. mosaic collages need 3). The builder gates on the vendor's actual
+   * hero slide count. Omitted = 1.
+   */
+  min_images?: number;
+  /**
+   * Gallery hero variants only, in a theme that also declares an "overlay"
+   * header: does this hero present a dark, full-bleed area directly behind
+   * the nav, so a transparent header with white text reads clearly over it?
+   * The backend resolves the `header` scope per vendor from this — a hero
+   * declaring `true` gets the overlay header, everything else gets a solid
+   * one. Declared per variant (audited against the actual component/CSS),
+   * never inferred from the id — "does it have images" is not the same
+   * question, and "does it have a photo" isn't either: a variant can be
+   * full of photos and still have no dark band under the nav (a side-by-side
+   * split with a light copy panel, a gapped multi-panel diptych).
+   */
+  supports_overlay_header?: boolean;
+  /**
+   * Header scope only: the inverse of `supports_overlay_header` — does THIS
+   * header variant need a hero that can carry a transparent bar to make
+   * sense at all? Omitted = false (a solid/always-visible header works
+   * regardless of what hero, if any, precedes it). The backend resolver
+   * reads both flags without ever checking a header's own id, so a theme is
+   * free to name its transparent header anything, or make a solid one the
+   * default, without breaking resolution.
+   */
+  requires_overlay_hero?: boolean;
+}
+
+export interface ThemeImageSpec {
+  width: number;
+  height: number;
+  label: string;
+}
+
+export interface ThemeManifest {
+  name: string;
+  slug: string;
+  description: string;
+  version: string;
+  variants: Record<string, ThemeManifestVariant[]>;
+  /**
+   * A per-scope migration marker. A marked scope may only contain structured
+   * field metadata; an unmarked scope remains transitional. More scopes can
+   * be added without creating a parallel top-level marker for each one.
+   */
+  fields_contract?: Partial<Record<string, 'structured'>>;
+  features?: string[];
+  images?: Record<string, ThemeImageSpec>;
+  /**
+   * Theme's default semantic design-token set (design-token-contract.md,
+   * queek_backend `.agent/.tmp/`) — the theme's current look expressed as
+   * tokens. Surfaced via `ThemeManifestService`/registry.json as the
+   * baseline the backend resolver layers vendor `tokens` overrides onto
+   * (theme defaults ← legacy fields ← vendor overrides). Optional during
+   * the pilot rollout — themes without it fall back to the storefront
+   * injector's own hardcoded defaults (`lib/core/utils/brand.ts`).
+   */
+  tokens?: DesignTokens;
+}
+
+/**
+ * Block types that are framework-owned (React logic ships in core, themes
+ * only style via `.core-block-*` CSS). Themes do NOT implement these.
+ */
+export type FrameworkBlockType = 'divider' | 'embed' | 'video' | 'table' | 'button' | 'image' | 'reviews' | 'faq' | 'callout' | 'quote' | 'product_qa';
+
+/**
+ * Block types the theme is responsible for implementing. Framework-owned
+ * types are excluded — page-renderer routes those directly to core.
+ *
+ * `content` is theme-owned for structured variants (promo, brand-story,
+ * testimonials, marquee, etc.), but the default markdown variant is
+ * framework-owned at the renderer level.
+ */
+export type ThemeBlockType = Exclude<BlockType, FrameworkBlockType>;
+
+export type ThemeBlocks = {
+  [K in ThemeBlockType]: FC<BlockDataMap[K]>;
+};
+
+export interface ThemeModule {
+  Layout: FC<LayoutProps>;
+  /** @deprecated Use getHeader(variant) instead */
+  Header: FC<HeaderProps>;
+  /** @deprecated Use getFooter(variant) instead */
+  Footer: FC<FooterProps>;
+  /** @deprecated Use getBlock(type, variant) instead */
+  blocks: ThemeBlocks;
+  getHeader: (variant?: string) => FC<HeaderProps>;
+  getFooter: (variant?: string) => FC<FooterProps>;
+  getBlock: <T extends ThemeBlockType>(type: T, variant?: string) => ThemeBlocks[T];
+  pages: {
+    Home: FC<HomePageProps>;
+    Page: FC<GenericPageProps>;
+    Blog: FC<BlogPageProps>;
+    Post: FC<PostPageProps>;
+    Shop?: FC<ShopPageProps>;
+    Collections?: FC<CollectionsPageProps>;
+    /** Optional override for the `/policies` listing. When absent, core renders
+     *  `DefaultPoliciesPage` (themeable via `.core-policies-*` CSS). */
+    Policies?: FC<PoliciesPageProps>;
+    Collection: FC<CollectionPageProps>;
+    Product: FC<ProductPageProps>;
+    Gallery: FC<GalleryPageProps>;
+  };
+  shells?: {
+    CartShell?: FC<CartShellProps>;
+    CheckoutShell?: FC<CheckoutShellProps>;
+    LoginShell?: FC<LoginShellProps>;
+    SignupShell?: FC<SignupShellProps>;
+    AccountShell?: FC<AccountShellProps>;
+  };
+  productCard?: FC<ProductCardProps>;
+  ModalLayer?: FC;
+  /** Optional override for the default auth modal presentation. Theme can
+   *  wrap <AuthFlow /> in any layout (sidebar, full-page split, inline card, etc). */
+  AuthRenderer?: FC;
+  manifest: ThemeManifest;
+}