@usequeek/theme-kit 0.1.0

package/theme-variant-resolver.ts

@@ -0,0 +1,44 @@
+import type { FC } from 'react';
+
+type VariantComponent = FC<any>;
+
+export type ThemeVariantImplementations = Record<string, Record<string, VariantComponent>>;
+export type LegacyBlockImplementations = Record<string, Record<string, VariantComponent>>;
+
+function resolveVariant<T extends VariantComponent>(
+  implementations: ThemeVariantImplementations,
+  scope: string,
+  variant: string | undefined,
+  fallback: T,
+): T {
+  if (!variant) return fallback;
+  return (implementations[scope]?.[variant] as T | undefined) ?? fallback;
+}
+
+export function resolveThemeHeader<T extends VariantComponent>(
+  implementations: ThemeVariantImplementations,
+  variant: string | undefined,
+  fallback: T,
+): T {
+  return resolveVariant(implementations, 'header', variant, fallback);
+}
+
+export function resolveThemeFooter<T extends VariantComponent>(
+  implementations: ThemeVariantImplementations,
+  variant: string | undefined,
+  fallback: T,
+): T {
+  return resolveVariant(implementations, 'footer', variant, fallback);
+}
+
+export function resolveThemeBlock<T extends VariantComponent>(
+  implementations: ThemeVariantImplementations,
+  type: string,
+  variant: string | undefined,
+  fallback: T,
+  legacyImplementations?: LegacyBlockImplementations,
+): T {
+  if (!variant) return fallback;
+  const implementation = implementations[type]?.[variant] ?? legacyImplementations?.[type]?.[variant];
+  return (implementation as T | undefined) ?? fallback;
+}

package/types/block.ts

@@ -0,0 +1,292 @@
+import type { DesignTokens } from './vendor';
+import type { Product } from './product';
+
+export type BlockType =
+  | 'content'
+  | 'image'
+  | 'gallery'
+  | 'video'
+  | 'table'
+  | 'button'
+  | 'embed'
+  | 'divider'
+  | 'callout'
+  | 'quote'
+  | 'products'
+  | 'categories'
+  | 'contact'
+  | 'reviews'
+  | 'faq'
+  | 'product_qa'
+  | 'blog';
+
+export interface ContentBlockData {
+  markdown: string;
+  /** Marquee variant: explicit items list set in admin (preferred over markdown). */
+  items?: string[];
+  /** Optional per-block background colour (e.g. marquee, promo). */
+  bg_color?: string;
+  /** Optional per-block text colour. */
+  text_color?: string;
+}
+
+export interface ImageBlockData {
+  url: string;
+  alt?: string | null;
+  caption?: string | null;
+}
+
+export interface GalleryBlockData {
+  /** Optional section copy (e.g. for the social-feed / insta-gallery variant). */
+  heading?: string | null;
+  description?: string | null;
+  /** Block-level (not per-slide) hero display controls — currently only
+   *  glow's 'slider'/'thumb-rail' variants read these; harmless no-op
+   *  elsewhere. */
+  zoom_effect?: boolean | null;
+  overlay?: 'none' | 'light' | 'medium' | 'strong' | null;
+  content_position?: 'bottom-right' | 'bottom-left' | 'bottom-center' | 'center' | null;
+  images: Array<{
+    url: string;
+    alt?: string | null;
+    caption?: string | null;
+    title?: string | null;
+    subtitle?: string | null;
+    link?: string | null;
+    cta_label?: string | null;
+    cta_url?: string | null;
+    /** Product ids featured in this image — lets a theme's social/UGC gallery
+     * variant open a shoppable modal on click instead of just linking out. */
+    product_ids?: string[] | null;
+    /** YouTube/Vimeo/direct file URL — takes over from `url` as the slide's
+     * media when set, with `url` still used as the poster/fallback. Only
+     * takes effect on themes/variants that render a single full-bleed slide
+     * (e.g. glow's `slider`/`thumb-rail` with exactly 1 image) — a
+     * multi-slide carousel would autoplay every slide's video concurrently
+     * since inactive slides stay mounted, not unmounted. */
+    video?: string | null;
+  }>;
+}
+
+export interface VideoBlockData {
+  url: string;
+}
+
+export interface TableBlockData {
+  headers: string[];
+  rows: string[][];
+}
+
+export interface ButtonBlockData {
+  text: string;
+  url: string;
+  bg_color?: string;
+  text_color?: string;
+}
+
+export interface EmbedBlockData {
+  url: string;
+  provider?: string | null;
+}
+
+export interface DividerBlockData {
+  style?: 'line' | 'space';
+}
+
+export type CalloutTone = 'info' | 'warn' | 'success' | 'note';
+
+export interface CalloutBlockData {
+  markdown: string;
+  tone?: CalloutTone;
+  title?: string | null;
+}
+
+export interface QuoteBlockData {
+  /** The quote body — plain text or short markdown. */
+  markdown?: string;
+  /** Legacy/alternate field name for the quote text. */
+  text?: string;
+  /** Attribution line (author, source). */
+  cite?: string | null;
+}
+
+export interface ProductsBlockData {
+  collection?: string | null;
+  ids?: string[];
+  sort?: 'latest' | 'popular' | 'price_low' | 'price_high';
+  limit?: number;
+  title?: string | null;
+  /** Single-product spotlight only — merchant-authored supporting copy, never product facts. */
+  description?: string | null;
+  /** Single-product spotlight only — label for the derived product route. */
+  cta_label?: string | null;
+  /**
+   * Single-product spotlight only — where the product image sits relative to
+   * the copy. 'left'/'right' set them side-by-side (mirrored), 'top' stacks a
+   * full-width image above centred copy. Same vocabulary as content/brand-story
+   * so a repeated spotlight can alternate instead of rendering three identical
+   * rows. Layout only — it never re-authors a derived product fact.
+   */
+  align?: 'left' | 'right' | 'top';
+  layout?: 'grid' | 'carousel' | 'list' | 'featured';
+  /** 'featured' variant only. Default true — hides the product excerpt/description. */
+  show_description?: boolean;
+  /** 'featured' variant only. Default 'top' — vertical alignment of the gallery/info columns. */
+  content_align?: 'top' | 'center' | 'bottom';
+}
+
+export interface CategoriesBlockData {
+  parent?: string | null;
+  ids?: string[];
+  limit?: number;
+  title?: string | null;
+  layout?: 'grid' | 'carousel';
+}
+
+export interface ContactSocialLink {
+  label: string;
+  url: string;
+}
+
+export interface ContactBlockData {
+  heading?: string;
+  info_heading?: string;
+  description?: string;
+  email?: string;
+  phone?: string;
+  address?: string;
+  hours?: string;
+  socials?: ContactSocialLink[];
+  cta_label?: string;
+  cta_url?: string;
+  map_embed_url?: string;
+  map_lat?: number | string | null;
+  map_lng?: number | string | null;
+}
+
+export interface ReviewMediaItem {
+  type: 'image' | 'video';
+  url: string;
+}
+
+export interface ReviewItem {
+  id: string;
+  rating: number;
+  title?: string | null;
+  description?: string | null;
+  media?: ReviewMediaItem[];
+  is_verified_purchase: boolean;
+  created_at: string;
+  edited_at?: string | null;
+  vendor_response?: string | null;
+  vendor_response_at?: string | null;
+  user: { id: string; name: string; avatar?: string | null };
+  product?: {
+    id: string;
+    slug: string;
+    title: string;
+    thumbnail?: string | null;
+  } | null;
+}
+
+export interface ReviewsSummary {
+  average_rating: number;
+  total_reviews: number;
+  rating_breakdown: Record<string, number>;
+}
+
+export interface ReviewsBlockData {
+  scope?: 'vendor' | 'product' | 'ids';
+  product_slug?: string | null;
+  ids?: string[];
+  min_rating?: 1 | 2 | 3 | 4 | 5;
+  verified_only?: boolean;
+  with_media?: boolean;
+  limit?: number;
+  sort?: 'newest' | 'highest' | 'featured';
+  layout?: 'grid' | 'carousel' | 'wall' | 'compact' | 'spotlight' | 'minimal';
+  title?: string | null;
+  /** Optional inline preview data — used by theme preview / demo mode when backend is unavailable. */
+  _preview?: { summary?: ReviewsSummary; reviews?: ReviewItem[] };
+}
+
+export interface FaqItem {
+  question: string;
+  answer: string;
+}
+
+export interface FaqBlockData {
+  heading?: string | null;
+  items: FaqItem[];
+}
+
+export interface ProductQuestionItem {
+  id: string;
+  question: string;
+  answer: string | null;
+  status: 'answered';
+  created_at: string;
+  answered_at: string | null;
+  user: { id: string; name: string; avatar?: string | null };
+}
+
+export interface ProductQaBlockData {
+  product_slug: string;
+  limit?: number;
+  title?: string | null;
+  /** Optional inline preview data — used by theme preview / demo mode when backend is unavailable. */
+  _preview?: { questions?: ProductQuestionItem[] };
+}
+
+export interface BlogBlockData {
+  title?: string | null;
+  /** Blog category slug. Blank/absent = every published post ("use all"). */
+  category?: string | null;
+  limit?: number;
+}
+
+export type BlockDataMap = {
+  content: ContentBlockData;
+  image: ImageBlockData;
+  gallery: GalleryBlockData;
+  video: VideoBlockData;
+  table: TableBlockData;
+  button: ButtonBlockData;
+  embed: EmbedBlockData;
+  divider: DividerBlockData;
+  callout: CalloutBlockData;
+  quote: QuoteBlockData;
+  products: ProductsBlockData;
+  categories: CategoriesBlockData;
+  contact: ContactBlockData;
+  reviews: ReviewsBlockData;
+  faq: FaqBlockData;
+  product_qa: ProductQaBlockData;
+  blog: BlogBlockData;
+};
+
+export type Block<T extends BlockType = BlockType> = {
+  type: T;
+  data: BlockDataMap[T];
+  variant?: string;
+  /**
+   * Section-scoped design-token overrides — only the keys set here are
+   * applied; everything else inherits the global tokens via the CSS
+   * cascade. See `expandDesignTokensPartial` in `lib/core/utils/brand.ts`.
+   */
+  tokens?: Partial<DesignTokens>;
+  /**
+   * Stable in-page-scroll target — a menu item's `meta.anchor` links here.
+   * Lowercase-kebab, enforced by the backend (ValidStorefrontBlocks).
+   */
+  anchor_id?: string;
+  /**
+   * Server-seeded product data for `products` blocks — set by
+   * `hydrateProductBlocks` (lib/core/api/products.ts) before blocks reach
+   * `PageRenderer`, which awaits it via `use()` inside a per-block
+   * `<Suspense>` boundary. Lives on the block, not inside `data`, so it never
+   * gets spread into theme components as a prop. Absent for every other
+   * block type and for any route that hasn't been wired to hydrate.
+   */
+  productsPromise?: Promise<Product[]>;
+};

package/types/cart.ts

@@ -0,0 +1,21 @@
+export interface CartAddon {
+  addon_id: string;
+  item_id: string;
+  name: string;
+  price: number;
+}
+
+export interface CartItem {
+  id: string;
+  product_id: string;
+  shop_id: string;
+  title: string;
+  slug?: string | null;
+  image: string | null;
+  unit_price: number;
+  quantity: number;
+  addons: CartAddon[];
+  variant_id?: string | null;
+  /** e.g. "Denim" — the selected variant's display name, when this line has one. */
+  variant_title?: string | null;
+}

package/types/media.ts

@@ -0,0 +1,55 @@
+/**
+ * The srcset-ready tier map emitted by the backend's MediaVariantMap
+ * (queek_backend: app/Services/Media/MediaVariantMap.php). Sits BESIDE the
+ * existing collapsed url fields (media.image, vendor.logo, collection.image, …),
+ * which are unchanged — this is purely additive.
+ *
+ * Contract (enforced backend-side, relied on here):
+ *  1. All 5 keys are ALWAYS present when the map itself is non-null.
+ *  2. A tier that doesn't exist is the WHOLE VALUE null — never a partial
+ *     object, never a fallback url. Skip it; never synthesize a filename.
+ *  3. `original` is never null when the map is non-null. Modeled as
+ *     `ImageVariantTier | null` anyway rather than a type-level invariant:
+ *     making it non-nullable would buy zero runtime safety against a backend
+ *     regression while forcing every consumer through a `!` or a cast. The
+ *     invariant is documented, not encoded.
+ *  4. `w`/`h` are `min(tier_cap, original.width)` and the proportional height —
+ *     so on a small original SEVERAL TIERS LEGITIMATELY SHARE A WIDTH. That is
+ *     correct backend behavior, and the reason resolveImageSources() dedupes
+ *     srcset candidates by width (duplicate `w` descriptors make a srcset
+ *     non-deterministic).
+ *  5. `thumb` ALWAYS has `w: null, h: null` — it's a legacy 150→240px tier with
+ *     a non-uniform crop history, so a computed width would misrepresent it.
+ *     It must NEVER enter a srcset; it is a fixed `src` tier only.
+ *  6. The WHOLE map is null when the image isn't Media-backed (external/off-host
+ *     url, SVG, some legacy uploads). Consumers fall back to the existing
+ *     collapsed field, exactly as today.
+ *
+ * Tier caps (queek_backend config/media.php `variant_widths`):
+ *   thumb ~240 (uncapped/legacy) · card 480 · card2x 800 · view 1600 · original raw
+ */
+export interface ImageVariantTier {
+  url: string;
+  /** Rendered width in px. null on `thumb` (always) and when the original has no
+   *  recorded dimensions. A tier with a null `w` cannot enter a srcset. */
+  w: number | null;
+  h: number | null;
+}
+
+export type ImageVariantTierName = 'thumb' | 'card' | 'card2x' | 'view' | 'original';
+
+export type ImageVariants = {
+  [K in ImageVariantTierName]: ImageVariantTier | null;
+};
+
+/**
+ * The flat url→variants sidecar on a Page/Post response
+ * (StorePageResource::toArray → 'media_index'). Keyed by the EXACT raw url
+ * string as it appears in that same response's `content[]` block JSON —
+ * block schemas were not changed, so a consumer looks up
+ * `mediaIndex[url] ?? null` per raw url it finds in block content.
+ *
+ * Serialized as `(object)` server-side: always present, `{}` when empty,
+ * NEVER null. Individual values can still be null (rule 6 above).
+ */
+export type MediaIndex = Record<string, ImageVariants | null>;

package/types/menu.ts

@@ -0,0 +1,27 @@
+export type MenuItemType =
+  | 'page'
+  | 'collection'
+  | 'collections'
+  | 'shop'
+  | 'blog'
+  | 'post'
+  | 'gallery'
+  | 'url'
+  | 'group';
+
+export interface MenuItem {
+  label: string;
+  type: MenuItemType;
+  ref?: string | null;
+  /** `anchor`: for a `page` item, scroll straight to that section (its `anchor_id`) instead of just the top. */
+  meta?: (Record<string, unknown> & { anchor?: string | null }) | null;
+  children?: MenuItem[];
+}
+
+export interface Menu {
+  id: string;
+  location: string;
+  items: MenuItem[];
+  created_at?: string | null;
+  updated_at?: string | null;
+}

package/types/order.ts

@@ -0,0 +1,119 @@
+export interface OrderListItem {
+  id: string;
+  order_no: string;
+  status: string;
+  is_completed?: boolean;
+  total_price: number | string;
+  grand_total?: number | string;
+  items_count: number | null;
+  payment_status: string;
+  created_at: string;
+  payment_method?: string;
+  payment_link?: string | null;
+  currency?: string;
+  delivery_method?: string;
+  /** @deprecated backend sends `delivery_method`; kept for type back-compat. */
+  delivery_mode?: string;
+  vendor?: { id: string; name: string; slug: string };
+}
+
+export interface OrderItem {
+  id: string;
+  quantity: number;
+  title: string;
+  total_price: number | string;
+  unit_price: number | string;
+  addons: Array<Record<string, unknown>>;
+  product?: { id: string; thumbnail_image?: string | null } | null;
+}
+
+export interface OrderTimeline {
+  time: string | null;
+  title: string;
+  description: string;
+}
+
+export interface AmountSummaryRow {
+  key: string;
+  label: string;
+  type?: string;
+  amount: number | string;
+  is_total?: boolean;
+}
+
+export interface OrderDetail {
+  id: string;
+  order_no: string;
+  status: string;
+  is_completed?: boolean;
+  status_label?: string;
+  payment_status: string;
+  payment_method?: string;
+  total_price: number | string;
+  grand_total?: number | string;
+  payment_link: string | null;
+  pay_link?: string | null;
+  items: OrderItem[];
+  timeline?: OrderTimeline[];
+  stage?: number | null;
+  amount_summary?: {
+    title?: string;
+    items: AmountSummaryRow[];
+  };
+  subtotal?: number;
+  delivery_fee?: number;
+  currency?: string;
+  delivery_method?: string;
+  /** @deprecated backend sends `delivery_method`; kept for type back-compat. */
+  delivery_mode?: string;
+  delivery_address?: string | null;
+  vendor_note?: string | null;
+  rider_note?: string | null;
+  created_at?: string;
+  vendor?: {
+    id: string;
+    name: string;
+    slug: string;
+    logo?: string | null;
+    address?: string | null;
+    phone?: string | null;
+    email?: string | null;
+    map_lat?: number | string | null;
+    map_lng?: number | string | null;
+  };
+  pickup_address?: string | null;
+  table?: { id: string; name: string; section?: string | null } | null;
+}
+
+export interface OrderPageMeta {
+  current_page: number;
+  last_page: number;
+  per_page: number;
+  total: number;
+}
+
+export interface OrderListResponse {
+  data: OrderListItem[];
+  meta: OrderPageMeta;
+}
+
+export interface CheckoutPayload {
+  delivery_mode: string;
+  payment_method: string;
+  cart_items: Array<{
+    id: string;
+    item_id: string;
+    title: string;
+    price: number;
+    quantity: number;
+    selectedAddons: Array<{ id: string; name: string; price: number }>;
+  }>;
+  delivery_address?: string;
+  map_lat?: number;
+  map_lng?: number;
+  order_type?: 'instant' | 'schedule';
+  schedule_date?: string;
+  schedule_time?: string;
+  vendor_note?: string;
+  customer_phone?: string;
+}

package/types/page.ts

@@ -0,0 +1,86 @@
+import type { Block } from './block';
+import type { ImageVariants, MediaIndex } from './media';
+import type { Product } from './product';
+
+export type PageType = 'page' | 'post' | 'gallery' | 'policy';
+
+export interface Pagination {
+  current_page?: number;
+  per_page?: number;
+  total?: number;
+  has_more?: boolean;
+  next_cursor?: string | null;
+  next_page_url?: string | null;
+  prev_cursor?: string | null;
+  prev_page_url?: string | null;
+}
+
+export interface SeoData {
+  title?: string | null;
+  description?: string | null;
+  image?: string | null;
+}
+
+export interface Page {
+  id: string;
+  slug: string;
+  type: PageType;
+  title: string;
+  content: Block[];
+  excerpt: string | null;
+  cover_image_url: string | null;
+  /** StorePageResource:50 — tier map for cover_image_url. */
+  cover_image_variants?: ImageVariants | null;
+  /**
+   * StorePageResource:47 — flat url→tier-map sidecar for every image url
+   * referenced inside `content[]`. `content[]` itself is byte-identical to
+   * before (block schemas unchanged); a block consumer looks up
+   * `mediaIndex[rawUrl] ?? null`. Serialized as an object, so it is `{}` when
+   * empty and never null — optional here only because older cached responses
+   * and preview/demo fixtures predate the field.
+   */
+  media_index?: MediaIndex;
+  tags: string[];
+  seo: SeoData;
+  published_at: string | null;
+  created_at: string | null;
+  /** 'bare' hides the storefront header/nav/footer — a standalone landing
+   * page with nothing but its own content. Defaults to 'full' server-side. */
+  chrome?: 'full' | 'bare';
+  /** Whether the theme's page-title band (the title as a large heading
+   * under the nav, above the section content) should render for this page.
+   * Defaults to true server-side; the landing-page skill sets it false. */
+  show_page_title?: boolean;
+}
+
+export interface BlogCategory {
+  name: string;
+  slug: string;
+  posts_count?: number;
+}
+
+export interface PostAuthor {
+  name: string;
+  avatar_url?: string | null;
+}
+
+export interface Post extends Page {
+  type: 'post';
+  blog_categories?: BlogCategory[];
+  reading_time?: number | null;
+  author?: PostAuthor | null;
+  related?: Post[];
+}
+
+export interface Collection {
+  id: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  image: string | null;
+  /** CollectionResource:27 — beside the unchanged `image`. */
+  image_variants?: ImageVariants | null;
+  mode: string | null;
+  products_count: number;
+  products?: Product[];
+}