@usequeek/theme-kit 0.1.23 → 0.1.25

package/hooks/use-reviews.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react';
 import { useStorefront, useStorefrontLocale } from '../provider';
 import { createBrowserClient } from '../sdk/client';
 import { withLocaleQuery } from '../utils/locale';
+import { toError } from '../utils/to-error';
 import type { ReviewItem, ReviewsBlockData, ReviewsSummary } from '../types/block';
 
 interface ReviewsResponse {
@@ -62,10 +63,20 @@ function summarize(reviews: ReviewItem[]): ReviewsSummary {
   };
 }
 
+/**
+ * Customer reviews for a `reviews` block: a list plus the rating summary
+ * (average and 1 to 5 breakdown). Scope, filters and sorting come from the
+ * block's own data. On failure the list is empty and `error` is set; the hook
+ * never throws.
+ *
+ * @example
+ * const { reviews, summary, isLoading } = useReviews({ scope: 'product', product_slug: 'oak-chair', limit: 6 });
+ */
 export function useReviews(options: ReviewsBlockData): {
   reviews: ReviewItem[];
   summary: ReviewsSummary;
   isLoading: boolean;
+  error: Error | null;
 } {
   const { vendor, previewData } = useStorefront();
   const locale = useStorefrontLocale();
@@ -73,6 +84,7 @@ export function useReviews(options: ReviewsBlockData): {
   const [reviews, setReviews] = useState<ReviewItem[]>(seeded);
   const [summary, setSummary] = useState<ReviewsSummary>(options._preview?.summary ?? summarize(seeded));
   const [isLoading, setIsLoading] = useState(!options._preview && !previewData);
+  const [error, setError] = useState<Error | null>(null);
 
   const {
     scope,
@@ -114,6 +126,7 @@ export function useReviews(options: ReviewsBlockData): {
 
     async function run(): Promise<void> {
       setIsLoading(true);
+      setError(null);
       try {
         let path = '/reviews';
         if (ids && ids.length > 0) {
@@ -136,10 +149,11 @@ export function useReviews(options: ReviewsBlockData): {
           setReviews(response.data.reviews ?? []);
           setSummary(response.data.summary ?? EMPTY_SUMMARY);
         }
-      } catch {
+      } catch (caught) {
         if (!cancelled) {
           setReviews([]);
           setSummary(EMPTY_SUMMARY);
+          setError(toError(caught));
         }
       } finally {
         if (!cancelled) setIsLoading(false);
@@ -166,5 +180,5 @@ export function useReviews(options: ReviewsBlockData): {
     locale,
   ]);
 
-  return { reviews, summary, isLoading };
+  return { reviews, summary, isLoading, error };
 }

package/hooks/use-search.ts

@@ -4,12 +4,22 @@ import { useMemo } from 'react';
 import type { Product } from '../types/product';
 import type { Collection } from '../types/page';
 
+/** What {@link useSearch} returns: the matches to show in a search panel. */
 export interface SearchResults {
   products: Product[];
   categories: Array<[slug: string, name: string]>;
   collections: Collection[];
 }
 
+/**
+ * Instant search over products and collections you already hold (no request).
+ * An empty query returns the first products and categories as suggestions.
+ * Matches are case-insensitive on product title, category name and collection
+ * name, capped at 5 products, 4 categories and 2 collections.
+ *
+ * @example
+ * const { products, categories, collections } = useSearch(query, allProducts, allCollections);
+ */
 export function useSearch(
   query: string,
   products: Product[],

package/hooks/use-shop-cart.ts

@@ -3,6 +3,14 @@
 import { useMemo } from 'react';
 import { useCartStore } from '../stores/cart-store';
 
+/**
+ * The cart lines for one shop, with the unit count and the total (in the
+ * currency's major unit, before delivery and discounts). Pass the shop id from
+ * `product.shop_id`; a missing id gives an empty cart.
+ *
+ * @example
+ * const { items, count, total } = useShopCart(product.shop_id);
+ */
 export function useShopCart(shopId: string | null | undefined): {
   items: ReturnType<typeof useCartStore.getState>['items'];
   count: number;

package/hooks/use-shop.ts

@@ -5,6 +5,7 @@ import { useStorefront, useStorefrontLocale } from '../provider';
 import type { Product, ApiResponse } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
 import { localeCacheKeySegment, withLocaleQuery } from '../utils/locale';
+import { toError } from '../utils/to-error';
 import {
   SHOP_DEFAULT_PER_PAGE,
   normalizeShopQuery,
@@ -78,11 +79,18 @@ function filterProducts(
 }
 
 /**
- * Shop catalogue data source. Hits the live products endpoint in production.
- * In preview (when the provider carries `previewData.products`) it filters,
- * sorts and paginates the demo catalogue in-memory so themes render real cards.
+ * The shop page's catalogue: one page of products for a category, keyword,
+ * sort and page number. Reads the live products endpoint in production. In
+ * preview (when the provider carries `previewData.products`) it filters, sorts
+ * and paginates the demo catalogue in memory, so themes render real cards.
  *
- * Page is controlled by the caller — pair with `useShopParams` for URL sync.
+ * The page is controlled by the caller; pair this with `useShopParams` to keep
+ * it in the URL. On failure the previous page of products stays on screen and
+ * `error` is set; the hook never throws.
+ *
+ * @example
+ * const { categorySlug, keyword, sort, page } = useShopParams();
+ * const { products, isLoading, pagination, error } = useShop({ categorySlug, keyword, sort, page });
  */
 export function useShop(options?: {
   categorySlug?: string | null;
@@ -94,6 +102,7 @@ export function useShop(options?: {
   products: Product[];
   isLoading: boolean;
   pagination: ShopPagination;
+  error: Error | null;
 } {
   const { vendor, previewData } = useStorefront();
   const locale = useStorefrontLocale();
@@ -123,6 +132,7 @@ export function useShop(options?: {
 
   const [products, setProducts] = useState<Product[]>(seed?.products ?? []);
   const [isLoading, setIsLoading] = useState(!isPreview && !seed);
+  const [error, setError] = useState<Error | null>(null);
   const [pagination, setPagination] = useState<ShopPagination>(seed?.pagination ?? { ...EMPTY_PAGINATION, perPage });
   // The key whose results are already in state. Seeded with the prefetch so
   // the first effect run does not refetch the page the server just rendered
@@ -166,6 +176,7 @@ export function useShop(options?: {
     // a newer one (filters B) had reset it, overwriting B's products.
     let cancelled = false;
     setIsLoading(true);
+    setError(null);
 
     const client = createBrowserClient(vendor.slug ?? undefined);
     const current = JSON.parse(queryKey) as typeof query;
@@ -182,6 +193,8 @@ export function useShop(options?: {
         setPagination(parsed.pagination);
         setProducts(parsed.products);
         loadedQueryRef.current = fetchKey;
+      } catch (caught) {
+        if (!cancelled) setError(toError(caught));
       } finally {
         if (!cancelled) setIsLoading(false);
       }
@@ -195,8 +208,8 @@ export function useShop(options?: {
   }, [isPreview, vendor.slug, queryKey, fetchKey, locale]);
 
   if (isPreview && previewResult) {
-    return { products: previewResult.products, isLoading: false, pagination: previewResult.pagination };
+    return { products: previewResult.products, isLoading: false, pagination: previewResult.pagination, error: null };
   }
 
-  return { products, isLoading, pagination };
+  return { products, isLoading, pagination, error };
 }

package/hooks/use-variant-selection.ts

@@ -25,25 +25,6 @@ export interface VariantSelection {
   activeHasDiscount: boolean;
 }
 
-/**
- * The option-selection state machine every theme's product page used to
- * hand-roll — six near-identical copies, all of which gated their add button
- * on stock and addons but never on a resolved variant.
- *
- * Two things it fixes that the copies got wrong:
- *
- * 1. It seeds from a real variant (first in-stock, else first) rather than
- *    from the first value of each option independently. On a sparse matrix —
- *    Red/S is not stocked but Red/M and Blue/S are — first-value-of-each
- *    produces a combination that matches nothing, so the page opened with an
- *    unresolvable selection.
- * 2. It exposes `variantSatisfied`, so a selection that resolves to nothing
- *    (mid-change, or that sparse seed) disables the add instead of sending a
- *    line the backend rejects.
- *
- * Themes keep their own option markup and call `selectOption` — core owns the
- * state, the theme owns the design.
- */
 /**
  * The opening selection. Seeded from a variant that actually exists, so the
  * initial state is always resolvable — preferring one in stock, since opening
@@ -85,6 +66,29 @@ export function resolveVariantState(
   };
 }
 
+/**
+ * The option-selection state machine every theme's product page used to
+ * hand-roll, and which gated the add button on stock and add-ons but never on a
+ * resolved variant.
+ *
+ * It does two things a hand-rolled version tends to get wrong:
+ *
+ * 1. It seeds from a real variant (first in-stock, else first) rather than
+ *    from the first value of each option independently. On a sparse matrix —
+ *    Red/S is not stocked but Red/M and Blue/S are — first-value-of-each
+ *    produces a combination that matches nothing, so the page opened with an
+ *    unresolvable selection.
+ * 2. It exposes `variantSatisfied`, so a selection that resolves to nothing
+ *    (mid-change, or that sparse seed) disables the add instead of sending a
+ *    line the backend rejects.
+ *
+ * Themes keep their own option markup and call `selectOption`: the kit owns the
+ * state, the theme owns the design.
+ *
+ * @example
+ * const { selectedOptions, selectOption, variantSatisfied, activePrice } = useVariantSelection(product);
+ * <button disabled={!variantSatisfied || !activeInStock}>Add to cart</button>
+ */
 export function useVariantSelection(product: Product): VariantSelection {
   const [selectedOptions, setSelectedOptions] = useState<Record<string, string>>(() => seedVariantOptions(product));
 

package/index.ts

@@ -11,19 +11,18 @@
  * Two entries because the split is real, not cosmetic: this one is types and
  * pure functions, importable from anywhere including node tooling; `client.ts`
  * is React state and components and needs a client boundary at the consumer.
- * Core also holds one `next/headers` caller, which belongs in neither and is
- * deliberately unreachable from both.
+ * Modules that call `next/headers` (`sdk/server-store-client.ts` and the
+ * `api/collections.ts` and `api/shop.ts` fetchers built on it) are server-only:
+ * import them from server components, never from a client module.
  *
  * THESE ARE A DECLARATION, NOT AN IMPORT PATH. Do not migrate themes onto them.
- * Pointing a theme's files at `client.ts` fails the build outright: tooling that
- * imports theme components under tsx (a theme registry generator, for example)
- * would reach a gallery block through the barrel, which transitively pulls the
- * SDK, and the SDK does not resolve outside a bundler. It is the same reason a barrel would bloat every
- * theme chunk: the stores call `create()` at import time and package.json
- * declares no `sideEffects`, so webpack must treat every re-export as live and
- * cannot drop the unused ones. Themes keep importing the exact module they use;
- * these barrels stay the machine-checkable statement of what is in the public
- * surface.
+ * Pointing a theme's files at `client.ts` can fail the build outright: tooling
+ * that imports theme components under `tsx` (a theme registry generator, for
+ * example) would reach a gallery block through the barrel, which transitively
+ * pulls the SDK, and the SDK does not resolve outside a bundler. A barrel also
+ * makes every client module reachable from one entry, which bloats each theme
+ * chunk. Themes import the exact module they use; these barrels stay the
+ * machine-checkable statement of what is in the public surface.
  */
 
 export * from './types/theme';

package/locales/en.default.json

@@ -176,5 +176,9 @@
   "language": {
     "label": "Language",
     "named": "Language: {name}"
+  },
+  "embed": {
+    "placeholder": "Paste the link or embed code of the content you want to show",
+    "title": "Embedded content"
   }
 }

package/navigation.tsx

@@ -15,6 +15,7 @@ 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';
 
+/** Props for {@link Link}: any anchor attribute except `href`, plus `prefetch` and `replace`. */
 export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
   /** A path inside the store (`menuItemToHref()`, `useHref()`) or a full URL. */
   href: string;
@@ -31,6 +32,7 @@ export function Link({ href, prefetch, replace, ...anchor }: LinkProps) {
   return <NextLink href={href} prefetch={prefetch} replace={replace} {...anchor} />;
 }
 
+/** What {@link useRouter} returns. */
 export interface Router {
   /** Go to `href`, adding a history entry. */
   push(href: string): void;

package/package.json

@@ -1,9 +1,24 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": false,
   "license": "MIT",
-  "description": "The framework a Queek storefront theme is built against.",
+  "description": "The runtime a Queek storefront theme is built on: hooks, stores, page renderer, navigation, shared blocks and locale strings.",
+  "keywords": [
+    "queek",
+    "storefront",
+    "theme",
+    "themes",
+    "react",
+    "nextjs",
+    "commerce",
+    "ecommerce"
+  ],
+  "homepage": "https://docs.usequeek.com/docs/themes",
+  "bugs": {
+    "url": "https://github.com/usequeek/theme-kit/issues"
+  },
+  "author": "Queekx Technology LTD",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/usequeek/theme-kit.git"
@@ -25,25 +40,31 @@
     "**/*.css",
     "locales/*.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md",
+    "!tests",
+    "!scripts"
   ],
   "peerDependencies": {
+    "@usequeek/client-sdk": "^0.4.0",
     "next": ">=15",
     "react": ">=19",
-    "react-dom": ">=19",
-    "@queekai/client-sdk": "*"
+    "react-dom": ">=19"
+  },
+  "engines": {
+    "node": ">=22"
   },
   "dependencies": {
-    "zustand": "^5.0.11",
+    "html-to-image": "^1.11.0",
     "react-markdown": "^10.0.0",
     "remark-gfm": "^4.0.0",
-    "html-to-image": "^1.11.0"
+    "zustand": "^5.0.11"
   },
   "devDependencies": {
-    "@queekai/client-sdk": "^0.3.0",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@usequeek/client-sdk": "^0.4.0",
     "jsdom": "^28.1.0",
     "next": "^16.0.0",
     "react": "^19.2.3",

package/page-renderer.tsx

@@ -65,6 +65,17 @@ function signatureReplacer(_key: string, value: unknown): unknown {
   return value;
 }
 
+/**
+ * Renders a page's blocks in order, choosing each block's theme variant (or
+ * the kit's shared block). Block data arrives already resolved: a theme never
+ * fetches it. While a merchant edits, a draft section that cannot render shows
+ * a short "can't be previewed yet" notice instead of blanking the page.
+ *
+ * @example
+ * export default function HomePage({ blocks }: HomePageProps) {
+ *   return <PageRenderer blocks={blocks} />;
+ * }
+ */
 export function PageRenderer({ blocks }: { blocks: Block[] }): JSX.Element {
   const draftBlocks = useEditPreviewStore((state) => state.blocks);
   const reconcileDraftBlocks = useEditPreviewStore((state) => state.reconcile);

package/provider.tsx

@@ -61,8 +61,23 @@ interface StorefrontContextValue {
   locales?: StoreLocale[];
 }
 
+/** The context behind {@link StorefrontProvider}. Read it through the hooks; use it directly only to test for a provider without throwing. */
 export const StorefrontContext = createContext<StorefrontContextValue | null>(null);
 
+/**
+ * Gives every kit hook and component the store they render for: its profile,
+ * configuration, menus, locale, languages and strings. The Queek storefront
+ * mounts it for every theme, so a theme never renders it. Render it yourself
+ * only in a test, a preview or a script.
+ *
+ * `basePath` defaults to `/<vendor.slug>`; pass `''` for a store served on its
+ * own domain. Brand design tokens become CSS variables on a wrapping element.
+ *
+ * @example
+ * <StorefrontProvider vendor={vendor} config={config} menus={[]}>
+ *   <MySection />
+ * </StorefrontProvider>
+ */
 export function StorefrontProvider({
   vendor,
   config,
@@ -147,11 +162,22 @@ export function StorefrontProvider({
   );
 }
 
+/**
+ * The current store: `vendor`, `config`, `menus`, `basePath`, `locale` and the
+ * rest of what the host passed to {@link StorefrontProvider}.
+ *
+ * @throws {Error} when called outside a `StorefrontProvider`.
+ *
+ * @example
+ * const { vendor, config } = useStorefront();
+ */
 export function useStorefront(): StorefrontContextValue {
   const context = useContext(StorefrontContext);
 
   if (!context) {
-    throw new Error('useStorefront must be used within StorefrontProvider');
+    throw new Error(
+      'useStorefront() was called outside <StorefrontProvider>. Render the component inside StorefrontProvider (the Queek storefront does this for every theme). In a test, wrap it yourself.',
+    );
   }
 
   return context;
@@ -167,7 +193,7 @@ export function useStorefrontLocale(): string | null {
   const context = useContext(StorefrontContext);
 
   if (!context) {
-    throw new Error('useStorefrontLocale must be used within StorefrontProvider');
+    throw new Error('useStorefrontLocale() was called outside <StorefrontProvider>. Render the component inside StorefrontProvider.');
   }
 
   return context.locale ?? null;
@@ -188,7 +214,7 @@ export function useThemeStrings(): ThemeStringsFn {
   const context = useContext(StorefrontContext);
 
   if (!context) {
-    throw new Error('useThemeStrings must be used within StorefrontProvider');
+    throw new Error('useThemeStrings() was called outside <StorefrontProvider>. Render the component inside StorefrontProvider.');
   }
 
   const theme = useOptionalTheme();