@usequeek/theme-kit 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Queek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/client.ts

@@ -50,3 +50,7 @@ export * from './stores/location-store';
 export * from './stores/address-modal-store';
 export * from './stores/auth-modal-store';
 export * from './stores/cart-store';
+
+// Mounting a theme — the piece a theme developer cannot build without.
+export * from './theme-mount';
+export * from './theme-context';

package/demo.ts

@@ -0,0 +1,201 @@
+/**
+ * Turns a theme's `demo.json` into the props its components expect.
+ *
+ * SHIPPED WITH THE KIT because without it a theme developer has demo data and
+ * no way to render it. THEME.md already requires every theme to carry a
+ * demo.json; these are the functions that resolve its block references into
+ * real products, categories, posts and collections. They lived in the
+ * storefront's own preview routes, so they existed only here — a theme could be
+ * written outside this repo and never shown running against its own data.
+ *
+ * Pure and type-only by construction: no `fs`, no `next`, no app imports. That
+ * is what made moving it a rename rather than a rewrite, and it is why these
+ * work identically in a developer's preview and in this repo's preview routes.
+ */
+import type { Block, ReviewItem } from './types/block';
+import type { Menu } from './types/menu';
+import type { Collection, Page, Post } from './types/page';
+import type { Product } from './types/product';
+import type { StorefrontConfig, VendorProfile } from './types/vendor';
+
+/**
+ * Pure demo-data transforms — no filesystem access, so this file is safe to
+ * import from a 'use client' component (unlike `demo.ts`, which pulls in
+ * Node's `fs`/`path` for `loadDemoData` and will break the browser bundle if
+ * a client component imports a value from it). `demo.ts` re-exports
+ * everything here for existing server-component call sites; new client-side
+ * code should import from here directly.
+ */
+
+export type DemoCategory = { id: string; slug: string; name: string; image?: string | null };
+
+export interface PreviewDemoData {
+  profile: VendorProfile;
+  config: StorefrontConfig;
+  menus: Menu[];
+  pages: Record<string, Page>;
+  products?: Product[];
+  categories?: DemoCategory[];
+  // Raw shape varies across themes that predate the `content: Block[]` /
+  // `cover_image_url` convention (see `normalizePost`) — kept loose here and
+  // normalized on read via `getPosts`/`getPost`.
+  posts?: Record<string, unknown>[];
+}
+
+export function enrichBlocks(blocks: Block[], demo: PreviewDemoData): Block[] {
+  return blocks.map((block) => {
+    if (block.type === 'products' && demo.products) {
+      const data = (block.data ?? {}) as Record<string, unknown>;
+      const title = (data.title as string) ?? '';
+      const limit = (data.limit as number) ?? demo.products.length;
+      const ids = data.ids as string[] | undefined;
+      let items = demo.products;
+
+      if (Array.isArray(ids) && ids.length > 0) {
+        // Explicit ids field — preserve order from ids array for section variety
+        const byId = new Map(demo.products.map((p) => [p.id, p]));
+        items = ids.map((id) => byId.get(id)).filter((p): p is NonNullable<typeof p> => Boolean(p));
+      } else if (/new|arrival/i.test(title)) {
+        items = demo.products.filter((product) => product.flags?.is_new);
+      } else if (/featured|popular|best|focus|lookbook/i.test(title)) {
+        items = demo.products.filter((product) => product.flags?.featured);
+      }
+
+      if (items.length === 0) items = demo.products;
+      return { ...block, data: { ...block.data, products: items.slice(0, limit) } };
+    }
+
+    if (block.type === 'categories' && demo.categories) {
+      return { ...block, data: { ...block.data, categories: demo.categories } };
+    }
+
+    return block;
+  });
+}
+
+export function getEnrichedPage<T extends Page>(page: T, demo: PreviewDemoData): T {
+  return {
+    ...page,
+    content: enrichBlocks(page.content ?? [], demo),
+  };
+}
+
+/**
+ * `demo.json`'s `posts` array is the documented, spec-correct source (see
+ * `themes/THEME.md` — "must mirror the vendor bootstrap shape") — a few
+ * themes authored it before the `content: Block[]` / `cover_image_url`
+ * convention settled, so this tolerates the older shapes instead of
+ * assuming every theme's data is current.
+ */
+function normalizePost(raw: Record<string, unknown>): Post {
+  const legacyMedia = raw.media as { image?: string; thumbnail?: string } | undefined;
+  const coverImageUrl =
+    (raw.cover_image_url as string | undefined) ?? legacyMedia?.image ?? legacyMedia?.thumbnail ?? null;
+
+  let content = raw.content;
+  if (typeof content === 'string') {
+    // Legacy raw-HTML content string — convert the handful of tags these
+    // themes actually used into one markdown content block rather than
+    // rendering literal "<p>"/"<h2>" text.
+    const markdown = content
+      .replace(/<h2>(.*?)<\/h2>/gi, '\n\n## $1\n\n')
+      .replace(/<h3>(.*?)<\/h3>/gi, '\n\n### $1\n\n')
+      .replace(/<p>(.*?)<\/p>/gi, '$1\n\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim();
+    content = [{ type: 'content', data: { markdown } }];
+  }
+
+  return {
+    ...raw,
+    type: 'post',
+    content: Array.isArray(content) ? (content as Block[]) : [],
+    cover_image_url: coverImageUrl,
+  } as Post;
+}
+
+export function getPosts(demo: PreviewDemoData): Post[] {
+  return (demo.posts ?? [])
+    .map(normalizePost)
+    .sort((left, right) => {
+      const leftDate = left.published_at ? new Date(left.published_at).getTime() : 0;
+      const rightDate = right.published_at ? new Date(right.published_at).getTime() : 0;
+      return rightDate - leftDate;
+    });
+}
+
+/**
+ * Vendor-scope reviews for preview surfaces, flattened from the demo's own
+ * product reviews.
+ *
+ * Review-backed sections (beaurify's `content/testimonials`) render real vendor
+ * reviews rather than merchant-authored copy — deliberately, see its manifest.
+ * But nothing seeded them in preview, so the section returned null everywhere a
+ * vendor evaluates it: theme preview, style guide, and the section-library
+ * thumbnails. Themes already ship product reviews in demo.json; this exposes
+ * them at vendor scope instead of asking every theme to duplicate the data.
+ *
+ * Demo review records predate `ReviewItem` (`user` is a bare name, the body is
+ * `comment`), so both spellings are accepted.
+ */
+export function getVendorReviews(demo: PreviewDemoData): ReviewItem[] {
+  return (demo.products ?? []).flatMap((product) => {
+    const raw = (product as unknown as { reviews?: Record<string, unknown>[] }).reviews ?? [];
+
+    return raw.map((review, index): ReviewItem => {
+      const author = typeof review.user === 'string'
+        ? review.user
+        : (review.customer_name as string | null) ?? 'Verified buyer';
+
+      return {
+        id: String(review.id ?? `${product.id}-review-${index}`),
+        rating: Number(review.rating ?? 5),
+        title: (review.title as string | null) ?? null,
+        description: (review.description as string | null) ?? (review.comment as string | null) ?? null,
+        media: [],
+        is_verified_purchase: review.is_verified_purchase !== false,
+        created_at: String(review.created_at ?? ''),
+        user: { id: `${product.id}-reviewer-${index}`, name: author, avatar: null },
+        product: { id: product.id, slug: product.slug, title: product.title, thumbnail: product.media?.thumbnail ?? null },
+      };
+    });
+  });
+}
+
+export function getPost(demo: PreviewDemoData, slug: string): Post | null {
+  return getPosts(demo).find((post) => post.slug === slug) ?? null;
+}
+
+export function getPolicies(demo: PreviewDemoData): Page[] {
+  return Object.values(demo.pages).filter((page) => page.type === 'policy');
+}
+
+export function getCollections(demo: PreviewDemoData): Collection[] {
+  const categories = demo.categories ?? [];
+  const products = demo.products ?? [];
+
+  return categories.map((category) => ({
+    id: category.id,
+    slug: category.slug,
+    name: category.name,
+    description: `${category.name} — curated picks from this collection.`,
+    image: category.image ?? null,
+    mode: 'manual',
+    products_count: products.filter((product) => product.categories.some((item) => item.slug === category.slug)).length,
+  }));
+}
+
+export function getCollection(demo: PreviewDemoData, slug: string): { collection: Collection; products: Product[] } | null {
+  const collection = getCollections(demo).find((item) => item.slug === slug);
+  if (!collection) return null;
+
+  const products = (demo.products ?? []).filter((product) => product.categories.some((category) => category.slug === slug));
+
+  return {
+    collection: {
+      ...collection,
+      products,
+    },
+    products,
+  };
+}

package/index.ts

@@ -47,3 +47,6 @@ export * from './utils/contact-location';
 export * from './utils/benefit-icon';
 export * from './utils/video-embed';
 export * from './utils/match-variant';
+
+// Rendering a theme's own demo.json — what makes local preview possible.
+export * from './demo';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
-  "license": "UNLICENSED",
+  "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",
   "repository": {
     "type": "git",
@@ -24,7 +24,8 @@
     "**/*.ts",
     "**/*.tsx",
     "**/*.css",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "peerDependencies": {
     "next": ">=15",

package/theme-mount.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import { Component, createElement, type ErrorInfo, type JSX, type ReactNode } from 'react';
+import type { FooterProps, HeaderProps, ThemeModule } from './types/theme';
+import { ThemeProvider } from './theme-context';
+
+/**
+ * Renders a theme. THE MINIMUM A THEME NEEDS TO BE SEEN.
+ *
+ * Without this, installing `@usequeek/theme-kit` gave a developer every hook,
+ * store, type and shared block — and no way to actually mount what they built.
+ * The component that does it, `VendorShell`, lives in the storefront app, so it
+ * was never part of what shipped. A theme could be written and typechecked from
+ * outside this repo but never rendered.
+ *
+ * DELIBERATELY SMALLER THAN VendorShell. That composes the same three pieces and
+ * then layers on the Queek storefront's own chrome — checkout header, cart and
+ * auth modals, toasts, WhatsApp chat, analytics, the merchant edit-mode bridge.
+ * None of that is a theme's concern, and pulling it in would drag the whole app
+ * into the package. What is left is the actual contract: a Layout wrapping a
+ * header, the page, and a footer.
+ *
+ * Themes render inside a boundary because a theme's header and footer are
+ * SIBLINGS of the page, so a crash in either escapes any boundary the page sets
+ * up and blanks the whole screen. A theme developer should see which part broke,
+ * not an empty document.
+ */
+
+class ThemeBoundary extends Component<
+  { part: string; children: ReactNode },
+  { error: Error | null }
+> {
+  state: { error: Error | null } = { error: null };
+
+  static getDerivedStateFromError(error: Error): { error: Error } {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    console.error(`[theme-kit] the theme's ${this.props.part} threw`, error, info.componentStack);
+  }
+
+  render(): ReactNode {
+    if (!this.state.error) return this.props.children;
+
+    // Visible on purpose. A silent fallback during theme development means
+    // staring at a missing header wondering whether it is CSS.
+    return (
+      <div role="alert" style={{ padding: '1rem', border: '2px solid #e0492f', background: '#fff5f3', color: '#211711', font: '14px/1.5 ui-monospace, monospace' }}>
+        <strong>Theme {this.props.part} crashed.</strong>
+        <pre style={{ margin: '0.5rem 0 0', whiteSpace: 'pre-wrap' }}>{this.state.error.message}</pre>
+      </div>
+    );
+  }
+}
+
+export interface ThemeMountProps {
+  theme: ThemeModule;
+  headerProps: HeaderProps;
+  footerProps: FooterProps;
+  /** Variant ids from the store's config; omit to render the theme's default. */
+  headerVariant?: string;
+  footerVariant?: string;
+  children: ReactNode;
+}
+
+export function ThemeMount({
+  theme,
+  headerProps,
+  footerProps,
+  headerVariant,
+  footerVariant,
+  children,
+}: ThemeMountProps): JSX.Element {
+  return (
+    <ThemeProvider theme={theme}>
+      <theme.Layout>
+        <ThemeBoundary part="header">
+          {createElement(theme.getHeader(headerVariant), headerProps)}
+        </ThemeBoundary>
+        <main className="storefront-main">{children}</main>
+        <ThemeBoundary part="footer">
+          {createElement(theme.getFooter(footerVariant), footerProps)}
+        </ThemeBoundary>
+      </theme.Layout>
+    </ThemeProvider>
+  );
+}