@usequeek/theme-kit 0.1.23 → 0.1.25

package/theme-context.tsx

@@ -6,6 +6,10 @@ import type { ThemeModule } from './types/theme';
 
 const ThemeContext = createContext<ThemeModule | null>(null);
 
+/**
+ * Makes a theme module available to `useTheme()`. `ThemeMount` renders it for
+ * you; use it directly only when you mount a theme yourself.
+ */
 export function ThemeProvider({
   theme,
   children,
@@ -18,11 +22,17 @@ export function ThemeProvider({
   );
 }
 
+/**
+ * The mounted theme module (manifest, pages, header and footer variants).
+ *
+ * @throws {Error} when called outside `ThemeMount` or `ThemeProvider`. Use
+ * `useOptionalTheme()` where a theme may be absent.
+ */
 export function useTheme(): ThemeModule {
   const theme = useContext(ThemeContext);
 
   if (!theme) {
-    throw new Error('useTheme must be used within ThemeProvider');
+    throw new Error('useTheme() was called outside <ThemeProvider>. Render the component inside <ThemeMount> (or <ThemeProvider theme={...}>).');
   }
 
   return theme;

package/theme-mount.tsx

@@ -49,6 +49,7 @@ class ThemeBoundary extends Component<
   }
 }
 
+/** Props for {@link ThemeMount}. */
 export interface ThemeMountProps {
   theme: ThemeModule;
   headerProps: HeaderProps;
@@ -59,6 +60,19 @@ export interface ThemeMountProps {
   children: ReactNode;
 }
 
+/**
+ * Render a theme: its layout, the header and footer chosen by variant id, and
+ * `children` (the page) between them. A header or footer that throws is
+ * replaced by a visible error box naming the part, so one broken component
+ * does not blank the screen.
+ *
+ * @example
+ * <StorefrontProvider vendor={vendor} config={config} menus={menus}>
+ *   <ThemeMount theme={theme} headerProps={headerProps} footerProps={footerProps}>
+ *     <HomePage blocks={blocks} />
+ *   </ThemeMount>
+ * </StorefrontProvider>
+ */
 export function ThemeMount({
   theme,
   headerProps,

package/utils/format.ts

@@ -125,7 +125,7 @@ export function formatRelativeTime(
 /**
  * Platform default — the LAST resort only. Item rows carry their own
  * `currency` code (see normalizeProduct) and store-wide display uses the
- * vendor's currency (cart-store, set from vendor-shell on mount). A missing
+ * vendor's currency (held in the cart store, which the storefront host sets on mount). A missing
  * or malformed code must resolve through this function, never a bare
  * `?? 'NGN'` at a call site, so the fallback stays in exactly one place.
  */
@@ -144,6 +144,14 @@ export function normalizeCurrencyCode(value: unknown, fallback: string = PLATFOR
   return /^[A-Z]{3}$/.test(cleanFallback) ? cleanFallback : PLATFORM_DEFAULT_CURRENCY;
 }
 
+/**
+ * Format an amount in a currency (ISO 4217 code), in the shopper's locale.
+ * Decimals show only when the amount has them (`₦5,000`, `₦0.28`). An invalid
+ * currency code falls back to the platform default. Never throws.
+ *
+ * @example
+ * formatMoney(5000, 'NGN'); // "₦5,000"
+ */
 export function formatMoney(
   amount: number,
   currency = PLATFORM_DEFAULT_CURRENCY,
@@ -163,6 +171,7 @@ export function formatMoney(
   }
 }
 
+/** A whole-number percentage string, e.g. `toPercent(12.4)` is `"12%"`. */
 export function toPercent(value: number): string {
   return `${Math.max(0, Math.round(value))}%`;
 }

package/utils/menu-link.ts

@@ -11,6 +11,14 @@ export function menuItemKey(item: MenuItem, index: number): string {
   return `${item.type}:${item.ref ?? ''}:${item.meta?.anchor ?? ''}:${index}`;
 }
 
+/**
+ * The link target for a menu item: pages, collections, the shop, the blog, posts
+ * and galleries resolve under `basePath`; a `url` item is used as is; anything
+ * unknown becomes `#`. Pass `useStorefront().basePath` (or use `useHref`).
+ *
+ * @example
+ * <Link href={menuItemToHref(item, basePath)}>{item.label}</Link>
+ */
 export function menuItemToHref(item: MenuItem, basePath: string = ''): string {
   switch (item.type) {
     case 'page': {

package/utils/to-error.ts

@@ -0,0 +1,4 @@
+/** Normalises anything a `catch` can hand back into an `Error`, so hooks can expose one `error` type. */
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}

package/utils/vendor-host.ts

@@ -84,8 +84,7 @@ export async function resolveCustomDomainVendorSlugRemote(hostname: string): Pro
   }
 
   // Middleware runs server-side — prefer the server-only absolute URL. The
-  // public var can be a same-origin relative path (checkout-proxy rollout),
-  // which `fetch()` can't resolve without a document origin here.
+  // public var can be a same-origin relative path, which `fetch()` can't resolve without a document origin here.
   const baseUrl = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL;
   if (!baseUrl) {
     return null;

package/scripts/verify-package.ts

@@ -1,102 +0,0 @@
-/**
- * Consumes the kit the way an OUTSIDER does, from a packed tarball.
- *
- * WHY THIS EXISTS. @usequeek/theme-kit@0.1.0 was published and was broken for
- * every external consumer:
- *
- *     node_modules/@usequeek/theme-kit/provider.tsx(58,5):
- *     error TS2503: Cannot find namespace 'JSX'.
- *
- * 42 modules annotated returns as `JSX.Element`, relying on a GLOBAL JSX
- * namespace that came from a host app's `next-env.d.ts` — not from React.
- * Inside a host app the kit free-rode on that file, so tsc, the tests, the
- * build and the render smoke were ALL green. The workspace supplies exactly the
- * file whose absence is the bug, which is why no in-repo check could ever have
- * found it. (Every module now does `import type { JSX } from 'react'`, and this
- * script proves it.)
- *
- * It packs the CURRENT SOURCE rather than installing the published version, so
- * it fails before a broken version ships instead of after. Installing from the
- * registry would only ever test the last release.
- */
-import { execFileSync } from 'node:child_process';
-import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, readdirSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// The kit package is `"type": "module"`, so `__dirname` does not exist here.
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const KIT = ROOT;
-
-function run(cmd: string, args: string[], cwd: string): string {
-  return execFileSync(cmd, args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-}
-
-function main(): void {
-  const sandbox = mkdtempSync(join(tmpdir(), 'kit-consumer-'));
-  let failed = false;
-
-  try {
-    const kitPkg = JSON.parse(readFileSync(join(KIT, 'package.json'), 'utf-8')) as {
-      name: string; version: string; peerDependencies?: Record<string, string>;
-    };
-
-    console.log(`verify-package: packing ${kitPkg.name}@${kitPkg.version} and consuming it as an outsider`);
-    run('npm', ['pack', '--pack-destination', sandbox], KIT);
-    const tarball = readdirSync(sandbox).find((f) => f.endsWith('.tgz'));
-    if (!tarball) throw new Error('npm pack produced no tarball');
-
-    // Peers are declared by the kit; pin the ones the fixture needs to compile.
-    const peers = kitPkg.peerDependencies ?? {};
-    writeFileSync(join(sandbox, 'package.json'), JSON.stringify({
-      name: 'kit-consumer', private: true, version: '1.0.0',
-      dependencies: {
-        [kitPkg.name]: `file:./${tarball}`,
-        '@queekai/client-sdk': peers['@queekai/client-sdk'] ?? '*',
-        next: '^16.0.0', react: '^19.0.0', 'react-dom': '^19.0.0',
-      },
-      devDependencies: { typescript: '^5', '@types/react': '^19', '@types/react-dom': '^19', '@types/node': '^22' },
-    }, null, 2));
-
-    // `bundler` resolution + no ambient Next types — exactly what a theme
-    // developer's own project looks like. NOT this repo's tsconfig.
-    writeFileSync(join(sandbox, 'tsconfig.json'), JSON.stringify({
-      compilerOptions: {
-        target: 'ES2017', lib: ['dom', 'dom.iterable', 'esnext'], jsx: 'react-jsx',
-        module: 'esnext', moduleResolution: 'bundler', strict: true, noEmit: true,
-        skipLibCheck: true, esModuleInterop: true, isolatedModules: true,
-      },
-      include: ['app/**/*.ts', 'app/**/*.tsx'],
-    }, null, 2));
-
-    mkdirSync(join(sandbox, 'app'), { recursive: true });
-    writeFileSync(join(sandbox, 'app/theme.tsx'), readFileSync(join(ROOT, 'tests/fixtures/external-theme.tsx'), 'utf-8'));
-
-    console.log('verify-package: installing from the tarball…');
-    run('npm', ['install', '--no-audit', '--no-fund'], sandbox);
-
-    console.log('verify-package: typechecking a real theme against it…');
-    try {
-      run(join(sandbox, 'node_modules/.bin/tsc'), ['--noEmit'], sandbox);
-      console.log(`\n✓ ${kitPkg.name} is consumable from outside this repo.`);
-    } catch (error) {
-      const out = (error as { stdout?: string; stderr?: string });
-      console.error('\n✗ the packed kit does NOT work for an external consumer:\n');
-      console.error((out.stdout ?? '') + (out.stderr ?? ''));
-      console.error('Errors inside node_modules/@usequeek/theme-kit are PACKAGE bugs — the kit is');
-      console.error('relying on something only this repo provides. Errors in app/theme.tsx mean the');
-      console.error('fixture drifted from the real API.');
-      failed = true;
-    }
-  } catch (error) {
-    console.error('✗ verify-package failed to run:', (error as Error).message);
-    failed = true;
-  } finally {
-    rmSync(sandbox, { recursive: true, force: true });
-  }
-
-  process.exit(failed ? 1 : 0);
-}
-
-main();

package/tests/apps.test.tsx

@@ -1,33 +0,0 @@
-import React from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it } from 'vitest';
-import * as apps from '../apps';
-import { AppBlocks, AppBlocksProvider } from '../apps';
-
-describe('apps — the theme-facing app-block slot', () => {
-  it('is exactly the provider, the slot, and the shared types', () => {
-    expect(Object.keys(apps).sort()).toEqual(['AppBlocks', 'AppBlocksProvider']);
-  });
-
-  it('renders nothing without a host registration (SSR-safe)', () => {
-    const html = renderToStaticMarkup(
-      React.createElement(AppBlocks, { target: 'product', productId: 'p1' }),
-    );
-
-    expect(html).toBe('');
-  });
-
-  it('renders whatever the host registered, with the slot props', () => {
-    function HostBlocks({ target, productId }: { target: 'product'; productId?: string }) {
-      return <div data-host-blocks={`${target}:${productId ?? ''}`} />;
-    }
-
-    const html = renderToStaticMarkup(
-      <AppBlocksProvider renderBlocks={HostBlocks}>
-        <AppBlocks target="product" productId="p1" vendorSlug="glow" />
-      </AppBlocksProvider>,
-    );
-
-    expect(html).toContain('data-host-blocks="product:p1"');
-  });
-});

package/tests/auth-email-errors.test.tsx

@@ -1,55 +0,0 @@
-/**
- * Auth error English pins.
- *
- * `mapEmailError` maps SDK failure codes to `t('auth.error.*')` strings, and
- * three more error keys are set directly in the provider. Every English value
- * below is resolved through the REAL default dictionary, so renaming a key or
- * changing any English value fails here.
- */
-import { describe, expect, it } from 'vitest';
-import { QueekSdkError } from '@queekai/client-sdk';
-import { t, defaultThemeStrings } from '../strings/theme-strings';
-import { mapEmailError } from '../hooks/use-auth-flow';
-
-const tt = (key: string): string => t(defaultThemeStrings, key);
-
-function sdkError(code: string, message: string): QueekSdkError {
-  return new QueekSdkError(message, code, 400);
-}
-
-describe('mapEmailError code -> English pins', () => {
-  it.each([
-    ['invalid_credentials', 'Wrong email or password. Please try again.'],
-    ['login_mode_mismatch', 'This account uses a different sign-in method (Google or phone).'],
-    ['account_already_exists', 'Email already registered. Please sign in instead.'],
-    ['phone_already_exists', 'Phone number already in use.'],
-    ['otp_resend_too_soon', 'Please wait before requesting another code.'],
-    ['invalid_otp', 'Incorrect code. Please try again.'],
-  ] as Array<[string, string]>)('code %s maps to its exact English', (code, english) => {
-    expect(mapEmailError(sdkError(code, 'server message'), tt)).toBe(english);
-  });
-
-  it('passes an unknown-code server message through untouched', () => {
-    expect(mapEmailError(sdkError('something_else', 'Server says no.'), tt)).toBe('Server says no.');
-  });
-
-  it('falls back to generic English when the server message is empty', () => {
-    expect(mapEmailError(sdkError('something_else', ''), tt)).toBe('Something went wrong. Please try again.');
-  });
-
-  it('falls back to generic English for non-SDK failures', () => {
-    expect(mapEmailError(new Error('boom'), tt)).toBe('Something went wrong. Please try again.');
-    expect(mapEmailError('boom', tt)).toBe('Something went wrong. Please try again.');
-  });
-});
-
-describe('direct-set auth.error.* English pins', () => {
-  it.each([
-    ['auth.error.firstname', 'Please enter your first name.'],
-    ['auth.error.register', 'Registration failed. Try again.'],
-    ['auth.error.google', 'Could not connect to Google sign-in. Please try again.'],
-    ['auth.error.generic', 'Something went wrong. Please try again.'],
-  ] as Array<[string, string]>)('%s resolves to its exact English', (key, english) => {
-    expect(tt(key)).toBe(english);
-  });
-});

package/tests/currency-contract.test.ts

@@ -1,85 +0,0 @@
-import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative, resolve } from 'node:path';
-import { describe, expect, it } from 'vitest';
-import { formatMoney, normalizeCurrencyCode, PLATFORM_DEFAULT_CURRENCY } from '../utils/format';
-import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
-import { useCartStore } from '../stores/cart-store';
-
-/**
- * Client readers do not use `meta.currency`. List-level `meta.currency` stamps the PLATFORM default (NGN) even on
- * non-NGN stores, so the item's own `currency` code is the source and the
- * vendor's currency is the store-wide source. Missing codes fall back to the
- * platform default as a LAST resort, in exactly one place.
- */
-describe('currency resolution', () => {
-  it('exposes NGN as the platform default last resort', () => {
-    expect(PLATFORM_DEFAULT_CURRENCY).toBe('NGN');
-  });
-
-  it('normalizeCurrencyCode keeps valid item/vendor codes', () => {
-    expect(normalizeCurrencyCode('USD')).toBe('USD');
-    expect(normalizeCurrencyCode('ngn')).toBe('NGN');
-    expect(normalizeCurrencyCode('  eur  ')).toBe('EUR');
-  });
-
-  it('normalizeCurrencyCode falls back instead of passing garbage through', () => {
-    expect(normalizeCurrencyCode(undefined)).toBe('NGN');
-    expect(normalizeCurrencyCode(null)).toBe('NGN');
-    expect(normalizeCurrencyCode('')).toBe('NGN');
-    expect(normalizeCurrencyCode('US')).toBe('NGN');
-    expect(normalizeCurrencyCode('USDD')).toBe('NGN');
-    expect(normalizeCurrencyCode(42)).toBe('NGN');
-  });
-
-  it('normalizeCurrencyCode honors an explicit vendor fallback', () => {
-    expect(normalizeCurrencyCode(undefined, 'USD')).toBe('USD');
-    expect(normalizeCurrencyCode('', 'eur')).toBe('EUR');
-    expect(normalizeCurrencyCode(undefined, 'bogus')).toBe('NGN');
-  });
-
-  it('normalizeProduct keeps the item currency, ignoring list-level meta', () => {
-    const envelope = {
-      data: [{ id: 'p1', title: 'Tote', price: 5000, currency: 'usd' }],
-      meta: { currency: { code: 'NGN', symbol: '₦' } },
-    };
-    const [raw] = extractProducts(envelope);
-    expect(normalizeProduct(raw).currency).toBe('USD');
-  });
-
-  it('normalizeProduct falls back to the platform default when the item has none', () => {
-    const [raw] = extractProducts({ data: [{ id: 'p2', title: 'Cap', price: 1000 }] });
-    expect(normalizeProduct(raw).currency).toBe('NGN');
-  });
-
-  it('formatMoney formats through the item code, not a wired symbol', () => {
-    expect(formatMoney(12500)).toBe('₦12,500');
-    const usd = formatMoney(5000, 'USD');
-    expect(usd).toContain('5,000');
-    expect(usd).not.toContain('₦');
-  });
-
-  it('cart-store currency starts at the platform default and normalizes vendor init', () => {
-    expect(useCartStore.getState().currency).toBe('NGN');
-    useCartStore.getState().setCurrency('usd');
-    expect(useCartStore.getState().currency).toBe('USD');
-    useCartStore.getState().setCurrency('');
-    expect(useCartStore.getState().currency).toBe('NGN');
-  });
-
-  it('no kit source reads list-level meta.currency', () => {
-    const ROOT = resolve(__dirname, '..');
-    const walk = (dir: string): string[] => readdirSync(dir).flatMap((entry) => {
-      const path = join(dir, entry);
-      if (entry === 'node_modules' || entry === 'tests' || entry.startsWith('.')) return [];
-      if (statSync(path).isDirectory()) return walk(path);
-      return /\.(ts|tsx)$/.test(entry) ? [path] : [];
-    });
-    const offenders = walk(ROOT).flatMap((file) => {
-      const source = readFileSync(file, 'utf8');
-      // Real reads use `?.` or a `.meta` access (`payload?.meta?.currency`,
-      // `data.meta.currency`); prose comments naming the contract don't count.
-      return /meta\?\.\s*currency|\.meta\.currency/.test(source) ? [relative(ROOT, file)] : [];
-    });
-    expect(offenders).toEqual([]);
-  });
-});

package/tests/default-metaobject-page.test.tsx

@@ -1,56 +0,0 @@
-import React from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it } from 'vitest';
-import { DefaultMetaobjectPage } from '../components/default-metaobject-page';
-import type { MetaobjectEntry } from '../types/product';
-import type { MetaobjectPageDefinition } from '../types/theme';
-
-function render(fields: MetaobjectEntry['fields'], fieldDefs: MetaobjectPageDefinition['fields']): string {
-  const entry: MetaobjectEntry = {
-    p_id: 1,
-    type: 'designer',
-    handle: 'adaeze',
-    display_name: 'Adaeze',
-    fields,
-  };
-  const definition: MetaobjectPageDefinition = { type: 'designer', name: 'Designer', fields: fieldDefs };
-
-  return renderToStaticMarkup(React.createElement(DefaultMetaobjectPage, { entry, definition }));
-}
-
-describe('DefaultMetaobjectPage', () => {
-  it('renders the entry display name as the title', () => {
-    const html = render({}, []);
-    expect(html).toContain('core-metaobject-page__title');
-    expect(html).toContain('Adaeze');
-  });
-
-  it('renders a text field with its definition label', () => {
-    const html = render({ bio: 'Lagos-based designer' }, [{ key: 'bio', name: 'Biography', type: 'single_line_text' }]);
-    expect(html).toContain('Biography');
-    expect(html).toContain('Lagos-based designer');
-  });
-
-  it('falls back to a humanised key label when no definition field matches', () => {
-    const html = render({ years_active: '10' }, []);
-    expect(html).toContain('Years active');
-  });
-
-  it('renders a boolean field as Yes/No', () => {
-    const html = render({ verified: true }, [{ key: 'verified', name: 'Verified', type: 'boolean' }]);
-    expect(html).toContain('>Yes<');
-  });
-
-  it('renders a url field as a link', () => {
-    const html = render({ portfolio: 'https://example.com/adaeze' }, [{ key: 'portfolio', name: 'Portfolio', type: 'url' }]);
-    expect(html).toContain('<a');
-    expect(html).toContain('href="https://example.com/adaeze"');
-  });
-
-  it('renders a list field as bullets', () => {
-    const html = render({ tags: ['couture', 'bridal'] }, [{ key: 'tags', name: 'Tags', type: 'list.single_line_text' }]);
-    expect(html).toContain('<ul');
-    expect(html).toContain('couture');
-    expect(html).toContain('bridal');
-  });
-});