@usequeek/theme-kit 0.1.22 → 0.1.24

package/components/language-menu.tsx

@@ -0,0 +1,371 @@
+'use client';
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type JSX,
+  type KeyboardEvent,
+  type MouseEvent,
+} from 'react';
+import type { LocalesState } from '../hooks/use-locales';
+import type { StoreLocale } from '../utils/locale-switch';
+import { computePlacement, type MenuAlign, type MenuSide } from '../utils/menu-placement';
+import './language-menu.css';
+
+/** Below this width the menu is a bottom sheet. The same value is in language-menu.css. */
+export const LANGUAGE_MENU_SHEET_QUERY = '(max-width: 639.98px)';
+
+/** More languages than this: the root gets `data-many="true"` (a theme may use two columns). */
+const MANY_LANGUAGES = 10;
+const TYPEAHEAD_RESET_MS = 500;
+const LOCK_CLASS = 'qn-lang-lock';
+
+type Mode = 'popover' | 'sheet';
+type Focus = 'selected' | 'last';
+
+export interface LanguageMenuProps {
+  state: LocalesState & { open: boolean; setOpen: (open: boolean) => void; label: string };
+  rootClass: string;
+  showCode: boolean;
+  side: MenuSide;
+  align: MenuAlign;
+  /** The language's name as shown (native or English). */
+  nameOf: (locale: StoreLocale) => string;
+  /** "Language: <shown name>" — the trigger's accessible name. */
+  triggerLabelFor: (locale: StoreLocale) => string;
+}
+
+function codeOf(locale: StoreLocale): string {
+  return locale.locale.toUpperCase();
+}
+
+function isSheetViewport(): boolean {
+  return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+    ? window.matchMedia(LANGUAGE_MENU_SHEET_QUERY).matches
+    : false;
+}
+
+function isRtl(element: Element): boolean {
+  const attr = element.closest('[dir]')?.getAttribute('dir');
+  if (attr === 'rtl' || attr === 'ltr') return attr === 'rtl';
+  return getComputedStyle(element).direction === 'rtl';
+}
+
+function isPlainPrimaryClick(event: MouseEvent): boolean {
+  return event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+}
+
+/**
+ * The `menu` variant of `LanguageSwitcher`: a disclosure button and a list of
+ * language links — a popover on wide screens, a bottom sheet on narrow ones.
+ * The items navigate, so they are plain links (`aria-current` marks the
+ * current one), not listbox options. Arrow keys, Home/End and typeahead move
+ * focus between the links; Enter follows the focused link natively.
+ *
+ * The wide/narrow LAYOUT is CSS only (one media query), so the markup is the
+ * same in both and server and client agree. JavaScript asks the media query
+ * only while the menu is opening or open: to lock page scroll behind a sheet
+ * and to run collision handling for a popover.
+ */
+export function LanguageMenu({
+  state,
+  rootClass,
+  showCode,
+  side,
+  align,
+  nameOf,
+  triggerLabelFor,
+}: LanguageMenuProps): JSX.Element {
+  const { locales, active, hrefFor, switchTo, open, setOpen, label } = state;
+  const uid = useId();
+  const popoverId = `${uid}-popover`;
+  const titleId = `${uid}-title`;
+
+  const rootRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const optionRefs = useRef<Array<HTMLAnchorElement | null>>([]);
+  const pendingFocus = useRef<Focus>('selected');
+  const typeahead = useRef({ text: '', timer: 0 });
+
+  const [mode, setMode] = useState<Mode>('popover');
+  const [placement, setPlacement] = useState<{ side: MenuSide; align: MenuAlign; shift: number; available: number | null }>({
+    side,
+    align,
+    shift: 0,
+    available: null,
+  });
+  const activeIndex = Math.max(0, locales.findIndex((locale) => locale.locale === active.locale));
+  const [rovingIndex, setRovingIndex] = useState(activeIndex);
+
+  const placed = open && mode === 'popover' ? placement : { side, align, shift: 0, available: null };
+
+  const close = useCallback(
+    (returnFocus: boolean) => {
+      setOpen(false);
+      if (returnFocus) triggerRef.current?.focus();
+    },
+    [setOpen],
+  );
+
+  const openMenu = useCallback(
+    (focus: Focus) => {
+      pendingFocus.current = focus;
+      setMode(isSheetViewport() ? 'sheet' : 'popover');
+      setRovingIndex(focus === 'last' ? locales.length - 1 : activeIndex);
+      setOpen(true);
+    },
+    [setOpen, locales.length, activeIndex],
+  );
+
+  const focusOption = useCallback(
+    (index: number) => {
+      const count = locales.length;
+      if (count === 0) return;
+      const next = (index + count) % count;
+      setRovingIndex(next);
+      optionRefs.current[next]?.focus();
+    },
+    [locales.length],
+  );
+
+  const select = useCallback(
+    (locale: StoreLocale) => {
+      close(true);
+      if (locale.locale !== active.locale) switchTo(locale);
+    },
+    [close, active.locale, switchTo],
+  );
+
+  // Focus moves into the list on open.
+  useEffect(() => {
+    if (!open) return;
+    const index = pendingFocus.current === 'last' ? locales.length - 1 : activeIndex;
+    const option = optionRefs.current[index];
+    option?.focus();
+    option?.scrollIntoView?.({ block: 'nearest' });
+    // Only when the menu opens.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  // Collision handling for the popover (plain measurements, no portal).
+  useLayoutEffect(() => {
+    if (!open || mode !== 'popover') return;
+    const root = rootRef.current;
+    const trigger = triggerRef.current;
+    const popover = popoverRef.current;
+    if (!root || !trigger || !popover) return;
+
+    const run = () => {
+      const t = trigger.getBoundingClientRect();
+      const p = popover.getBoundingClientRect();
+      const next = computePlacement({
+        trigger: { top: t.top, right: t.right, bottom: t.bottom, left: t.left },
+        popover: { width: p.width, height: p.height },
+        viewport: { width: window.innerWidth, height: window.innerHeight },
+        side,
+        align,
+        dir: isRtl(root) ? 'rtl' : 'ltr',
+      });
+      setPlacement((prev) =>
+        prev.side === next.side && prev.align === next.align && prev.shift === next.shift && prev.available === next.available
+          ? prev
+          : next,
+      );
+    };
+    run();
+    window.addEventListener('resize', run);
+    return () => window.removeEventListener('resize', run);
+  }, [open, mode, side, align, locales.length]);
+
+  // Follow the viewport crossing the breakpoint while open.
+  useEffect(() => {
+    if (!open || typeof window.matchMedia !== 'function') return;
+    const query = window.matchMedia(LANGUAGE_MENU_SHEET_QUERY);
+    const onChange = () => setMode(query.matches ? 'sheet' : 'popover');
+    query.addEventListener?.('change', onChange);
+    return () => query.removeEventListener?.('change', onChange);
+  }, [open]);
+
+  // A sheet locks page scroll behind it.
+  useEffect(() => {
+    if (!open || mode !== 'sheet') return;
+    document.body.classList.add(LOCK_CLASS);
+    return () => document.body.classList.remove(LOCK_CLASS);
+  }, [open, mode]);
+
+  // Outside tap or click closes without taking focus.
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (event: Event) => {
+      if (rootRef.current && event.target instanceof Node && !rootRef.current.contains(event.target)) close(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown);
+    return () => document.removeEventListener('pointerdown', onPointerDown);
+  }, [open, close]);
+
+  useEffect(() => () => window.clearTimeout(typeahead.current.timer), []);
+
+  const onTriggerKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+    event.preventDefault();
+    const focus: Focus = event.key === 'ArrowUp' ? 'last' : 'selected';
+    if (!open) return openMenu(focus);
+    focusOption(focus === 'last' ? locales.length - 1 : activeIndex);
+  };
+
+  const onRootKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!open) return;
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      return close(true);
+    }
+    if (event.key === 'Tab') return close(false);
+
+    const target = event.target instanceof Element ? event.target.closest('a') : null;
+    const index = target ? optionRefs.current.indexOf(target as HTMLAnchorElement) : -1;
+    if (index < 0) return;
+
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        return focusOption(index + 1);
+      case 'ArrowUp':
+        event.preventDefault();
+        return focusOption(index - 1);
+      case 'Home':
+        event.preventDefault();
+        return focusOption(0);
+      case 'End':
+        event.preventDefault();
+        return focusOption(locales.length - 1);
+      case ' ':
+        event.preventDefault();
+        return select(locales[index]!);
+      default:
+        break;
+    }
+
+    if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+      const buffer = typeahead.current;
+      buffer.text += event.key.toLocaleLowerCase();
+      window.clearTimeout(buffer.timer);
+      buffer.timer = window.setTimeout(() => {
+        buffer.text = '';
+      }, TYPEAHEAD_RESET_MS);
+      const found = locales.findIndex(
+        (locale) =>
+          nameOf(locale).toLocaleLowerCase().startsWith(buffer.text) ||
+          locale.name.toLocaleLowerCase().startsWith(buffer.text) ||
+          locale.locale.toLocaleLowerCase().startsWith(buffer.text),
+      );
+      if (found >= 0) focusOption(found);
+    }
+  };
+
+  const dataState = open ? 'open' : 'closed';
+  const popoverStyle: Record<string, string> = {};
+  if (placed.shift) popoverStyle['--qn-lang-shift'] = `${placed.shift}px`;
+  if (placed.available !== null) popoverStyle['--qn-lang-avail'] = `${placed.available}px`;
+
+  return (
+    <div
+      ref={rootRef}
+      className={rootClass}
+      data-qn-language-switcher=""
+      data-variant="menu"
+      data-state={dataState}
+      data-side={placed.side}
+      data-align={placed.align}
+      data-mode={open ? mode : undefined}
+      data-count={locales.length}
+      data-many={locales.length > MANY_LANGUAGES ? 'true' : undefined}
+      data-show-code={showCode ? 'true' : undefined}
+      onKeyDown={onRootKeyDown}
+    >
+      <button
+        ref={triggerRef}
+        type="button"
+        className="qn-lang__trigger"
+        data-part="trigger"
+        aria-expanded={open}
+        aria-controls={popoverId}
+        aria-label={triggerLabelFor(active)}
+        onClick={() => (open ? close(false) : openMenu('selected'))}
+        onKeyDown={onTriggerKeyDown}
+      >
+        <span className="qn-lang__trigger-label" data-part="trigger-label">
+          {nameOf(active)}
+        </span>
+        <span className="qn-lang__trigger-code" data-part="trigger-code">
+          {codeOf(active)}
+        </span>
+        <svg className="qn-lang__chevron" data-part="chevron" aria-hidden="true" viewBox="0 0 10 10" focusable="false">
+          <path d="M1 3.5 5 7.5 9 3.5" />
+        </svg>
+      </button>
+      <div className="qn-lang__scrim" data-part="scrim" aria-hidden="true" hidden={!open} onClick={() => close(false)} />
+      <div
+        ref={popoverRef}
+        id={popoverId}
+        className="qn-lang__popover"
+        data-part="popover"
+        data-state={dataState}
+        hidden={!open}
+        style={popoverStyle}
+      >
+        <div className="qn-lang__handle" data-part="handle" aria-hidden="true" />
+        <div id={titleId} className="qn-lang__title" data-part="title">
+          {label}
+        </div>
+        <ul className="qn-lang__options" data-part="list" aria-labelledby={titleId}>
+          {locales.map((locale, index) => {
+            const current = locale.locale === active.locale;
+            return (
+              <li key={locale.locale} className="qn-lang__item" data-part="item">
+                <a
+                  ref={(node) => {
+                    optionRefs.current[index] = node;
+                  }}
+                  className="qn-lang__option"
+                  data-part="option"
+                  data-current={current ? 'true' : undefined}
+                  href={hrefFor(locale)}
+                  lang={locale.html_lang}
+                  hrefLang={locale.hreflang}
+                  aria-current={current ? 'true' : undefined}
+                  tabIndex={index === rovingIndex ? 0 : -1}
+                  onFocus={() => setRovingIndex(index)}
+                  onClick={(event) => {
+                    // Modified clicks keep the browser default (new tab, copy link).
+                    if (event.defaultPrevented || !isPlainPrimaryClick(event)) return;
+                    event.preventDefault();
+                    select(locale);
+                  }}
+                >
+                  <span className="qn-lang__name" data-part="name">
+                    <bdi lang={locale.html_lang} dir={locale.dir === 'rtl' ? 'rtl' : undefined}>
+                      {nameOf(locale)}
+                    </bdi>
+                  </span>
+                  <span className="qn-lang__code" data-part="code">
+                    {codeOf(locale)}
+                  </span>
+                  <span className="qn-lang__mark" data-part="mark" aria-hidden="true">
+                    <svg viewBox="0 0 16 16" focusable="false">
+                      <path d="m3 8.5 3.2 3.2L13 5" />
+                    </svg>
+                  </span>
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    </div>
+  );
+}

package/components/language-switcher.tsx

@@ -1,21 +1,30 @@
 'use client';
 
-import { useContext, type JSX, type MouseEvent, type ReactNode } from 'react';
+import { useContext, useState, type JSX, type MouseEvent, type ReactNode } from 'react';
 import { StorefrontContext, useThemeStrings } from '../provider';
 import { Link } from '../navigation';
 import { useLocales, type LocalesState } from '../hooks/use-locales';
 import type { StoreLocale } from '../utils/locale-switch';
+import type { MenuAlign, MenuSide } from '../utils/menu-placement';
+import { LanguageMenu } from './language-menu';
 import './language-switcher.css';
 
+/** Props for `LanguageSwitcher`. The README lists each prop with its default. */
 export interface LanguageSwitcherProps {
   /** Extra class on the root, to position or restyle the control. */
   className?: string;
   /**
-   * `'select'` (default): one native dropdown — the best keyboard, touch and
-   * screen-reader behaviour for free. `'inline-list'`: every language as a
-   * link, wrapping onto new lines on narrow screens; suits a footer.
+   * `'menu'`: a trigger button and a list of language links — a popover on
+   * wide screens, a bottom sheet on narrow ones; fully restylable through
+   * documented parts and `--qn-lang-*` variables. `'select'` (default, legacy):
+   * one native dropdown. `'inline-list'`: every language as a link, wrapping
+   * onto new lines on narrow screens; suits a footer with up to four languages.
    */
-  variant?: 'select' | 'inline-list';
+  variant?: 'select' | 'inline-list' | 'menu';
+  /** `menu` only: open below (`'bottom'`, default) or above (`'top'`, for footers) the trigger. Flips on its own when it does not fit. */
+  side?: MenuSide;
+  /** `menu` only: line the popover up with the trigger's inline `'end'` (default) or `'start'` edge. */
+  align?: MenuAlign;
   /** Append the language code, e.g. `Français · FR`. Default false. */
   showCode?: boolean;
   /** Label each language in its own language (`Français`) rather than English (`French`). Default true. */
@@ -32,6 +41,9 @@ export interface LanguageSwitcherProps {
 export interface LanguageSwitcherState extends LocalesState {
   /** "Language" — the group label. */
   label: string;
+  /** Whether the `menu` variant is open. A custom UI may drive it with `setOpen`. */
+  open: boolean;
+  setOpen: (open: boolean) => void;
   /** "Language: French" — names the control and the current language. */
   labelFor: (locale: StoreLocale) => string;
   /** The text to show for one language, honouring `showNativeName` / `showCode`. */
@@ -60,13 +72,16 @@ export function LanguageSwitcher(props: LanguageSwitcherProps): JSX.Element | nu
 function LanguageSwitcherInner({
   className,
   variant = 'select',
+  side = 'bottom',
+  align = 'end',
   showCode = false,
   showNativeName = true,
   children,
 }: LanguageSwitcherProps): JSX.Element | null {
   const t = useThemeStrings();
-  const state = useLocales();
-  const { locales, active, hasMultiple, hrefFor, switchTo } = state;
+  const base = useLocales();
+  const [open, setOpen] = useState(false);
+  const { locales, active, hasMultiple, hrefFor, switchTo } = base;
 
   if (!hasMultiple) return null;
 
@@ -77,10 +92,27 @@ function LanguageSwitcherInner({
     return showCode ? `${name} · ${locale.locale.toUpperCase()}` : name;
   };
 
-  if (children) return <>{children({ ...state, label, labelFor, displayName })}</>;
+  const state: LanguageSwitcherState = { ...base, label, open, setOpen, labelFor, displayName };
+
+  if (children) return <>{children(state)}</>;
 
   const rootClass = ['qn-lang', `qn-lang--${variant}`, className].filter(Boolean).join(' ');
 
+  if (variant === 'menu') {
+    const nameOf = (locale: StoreLocale): string => (showNativeName ? locale.native_name : locale.name);
+    return (
+      <LanguageMenu
+        state={state}
+        rootClass={rootClass}
+        showCode={showCode}
+        side={side}
+        align={align}
+        nameOf={nameOf}
+        triggerLabelFor={(locale) => t('language.named', { name: nameOf(locale) })}
+      />
+    );
+  }
+
   if (variant === 'inline-list') {
     return (
       <nav className={rootClass} aria-label={label} data-qn-language-switcher="" data-variant="inline-list">

package/components/powered-by-queek.tsx

@@ -4,6 +4,7 @@ import { useContext, type JSX } from 'react';
 import { StorefrontContext } from '../provider';
 import { poweredByQueekUrl } from '../utils/powered-by';
 
+/** Props for {@link PoweredByQueek}. */
 export interface PoweredByQueekProps {
   /** Extra class so a footer can position the link — styling stays theme-owned. */
   className?: string;
@@ -15,11 +16,11 @@ export interface PoweredByQueekProps {
 }
 
 /**
- * Core-owned storefront attribution — the `ProductMetafields` pattern: themes
- * import-and-place it, never re-implement it.
+ * The storefront attribution link, owned by the kit: themes import and place
+ * it, and never re-implement it.
  *
  * Required on every footer variant of every theme (enforced by the
- * `theme/footer-shows-powered-by` rule of the theme check). The link
+ * `theme/footer-shows-powered-by` rule of `npm run check`). The link
  * target (`https://usequeek.com/business`) and `rel` are the contract —
  * do not change them. The href is tagged `utm_source=powered_by`,
  * `utm_medium=storefront`, `utm_campaign=<store slug>` via `poweredByQueekUrl`

package/components/product-media-frame.tsx

@@ -19,6 +19,11 @@ interface ProductMediaFrameProps {
   intent?: ImageIntent;
 }
 
+/**
+ * One frame of a product's media gallery: an image through `Image`, or a video.
+ * Pass a frame from `buildMediaFrames(product)`. `variant="thumbnail"` renders a
+ * muted video with no controls, so the browser shows its first frame.
+ */
 export function ProductMediaFrame({
   frame,
   className,

package/components/product-metafields.tsx

@@ -7,10 +7,12 @@ import type {
 } from '../types/product';
 import { formatDisplayDate } from '../utils/format';
 
+/** Merchant-set labels and types for custom fields, keyed by field key. Passed as `metafieldDefinitions` on the product page. */
 export interface ProductMetafieldDefinitionLabels {
   [key: string]: { name: string; type: string };
 }
 
+/** Props for {@link ProductMetafields}. */
 export interface ProductMetafieldsProps {
   product: Product;
   definitions?: ProductMetafieldDefinitionLabels;
@@ -205,6 +207,13 @@ export function renderValue(value: MetafieldValue, fieldKey: string, label: stri
   return renderScalar(value as MetafieldScalar, fieldKey, label, type);
 }
 
+/**
+ * Place this on the product page to show the product's custom fields.
+ * Renders nothing when there are none to show.
+ *
+ * @example
+ * <ProductMetafields product={product} definitions={metafieldDefinitions} />
+ */
 export function ProductMetafields({ product, definitions }: ProductMetafieldsProps): JSX.Element | null {
   const metafields = product.metafields && typeof product.metafields === 'object' ? product.metafields : {};
   const visible = Object.entries(metafields).filter(([, value]) => isVisibleValue(value as MetafieldValue));

package/components/variant-picker.css

@@ -1,11 +1,8 @@
 /* ============================================================
-   VariantPicker — shared option-selection UI (QR ordering sheet,
-   default theme's quick-view modal). Prefix: qk-variant-.
-   Reads --brand-* directly (not a context-scoped token set like
-   --qr- or --qka-) so it renders correctly regardless of which
-   surface mounts it. Mirrors quick-add-page.css's qka-option/qka-swatch
-   rules — same visual language, kept as a separate small file since
-   this component is reused outside that page's scope.
+   VariantPicker: shared option-selection UI (in-store ordering sheet,
+   quick-view modal). Class prefix: qk-variant-.
+   Reads --brand-* directly, not a surface-scoped token set, so it renders
+   correctly whichever surface mounts it.
    ============================================================ */
 
 .qk-variant-option {

package/edit-mode.tsx

@@ -6,9 +6,10 @@ import dynamic from 'next/dynamic';
 
 const QK_EDIT_FLAG = 'edit';
 
-// Lightweight: reads `?edit=1` once on mount. Always shipped to the
-// storefront bundle, but cheap (one URLSearchParams parse) and adds no
-// runtime overhead for public visitors.
+/**
+ * True when the page was opened by the merchant editor (`?edit=1`). Read once
+ * on mount. Cheap enough to ship to every visitor: one query-string parse.
+ */
 export function useEditMode(): boolean {
   const [isEdit, setIsEdit] = useState(false);
 

package/hooks/use-address-autocomplete.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react';
 import { useStorefront } from '../provider';
 import { getQueekClient } from '../sdk/queek-client';
 
+/** One address suggestion. Pass `place_id` to `useResolveCoordinates` to get its position. */
 export interface AddressSuggestion {
   description: string;
   place_id: string;
@@ -11,6 +12,14 @@ export interface AddressSuggestion {
 
 const DEBOUNCE_MS = 300;
 
+/**
+ * Address suggestions for what the shopper has typed, after a 300 ms pause.
+ * Nothing is requested for fewer than two characters. A failed request clears
+ * the suggestions rather than throwing, so the field stays usable.
+ *
+ * @example
+ * const { suggestions, loading } = useAddressAutocomplete(text);
+ */
 export function useAddressAutocomplete(query: string): {
   suggestions: AddressSuggestion[];
   loading: boolean;

package/hooks/use-auth-flow.tsx

@@ -246,14 +246,9 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       const returnTo = typeof window !== 'undefined' ? window.location.href : '';
       const slug = vendor.slug ?? '';
       const url = `${QUEEK_AUTH_URL}/oauth/google/start?channel=storefront&vendor_slug=${encodeURIComponent(slug)}&return_to=${encodeURIComponent(returnTo)}`;
-      // eslint-disable-next-line no-console
-      console.info('[google-auth] requesting redirect URL from', url);
       const res = await fetch(url);
       if (!res.ok) {
-        const text = await res.text().catch(() => '');
-        // eslint-disable-next-line no-console
-        console.warn('[google-auth] redirect endpoint returned non-2xx', res.status, text);
-        throw new Error(`Failed to initiate Google auth (HTTP ${res.status}).`);
+        throw new Error(`The Queek sign-in service answered HTTP ${res.status} when starting Google sign-in. Retry, or use email sign-in.`);
       }
       // Response envelope: { status, message, data: { url } }
       const body = (await res.json()) as {
@@ -266,13 +261,11 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       if (redirectUrl) {
         window.location.href = redirectUrl;
       } else {
-        // eslint-disable-next-line no-console
-        console.warn('[google-auth] no redirect URL in response body', body);
-        throw new Error('No redirect URL returned.');
+        throw new Error('The Queek sign-in service did not return a Google redirect URL.');
       }
     } catch (err) {
-      // eslint-disable-next-line no-console
-      console.error('[google-auth] initiate failed', err);
+      // The shopper sees the translated message; the cause stays in the console for the theme developer.
+      console.error('[theme-kit] could not start Google sign-in:', err);
       setError(t('auth.error.google'));
     } finally {
       setLoading(false);
@@ -342,7 +335,9 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
 export function useAuthFlow(): AuthFlowValue {
   const ctx = useContext(AuthFlowContext);
   if (!ctx) {
-    throw new Error('useAuthFlow must be used within an AuthFlowProvider');
+    throw new Error(
+      'useAuthFlow() was called outside <AuthFlowProvider>. Render the auth step components inside <AuthFlow> (or wrap them in <AuthFlowProvider>).',
+    );
   }
   return ctx;
 }

package/hooks/use-auth.ts

@@ -3,6 +3,16 @@
 import { useAuthModalStore } from '../stores/auth-modal-store';
 import { useUserStore } from '../stores/user-store';
 
+/**
+ * The signed-in customer and the sign-in modal controls.
+ *
+ * `user` is null and `isAuthenticated` false until the shopper signs in.
+ * `openAuthModal('signup')` opens the kit's sign-in flow on the sign-up step.
+ *
+ * @example
+ * const { user, isAuthenticated, openAuthModal, logout } = useAuth();
+ * return isAuthenticated ? <button onClick={logout}>Sign out</button> : <button onClick={() => openAuthModal()}>Sign in</button>;
+ */
 export function useAuth() {
   return {
     user: useUserStore((state) => state.user),

package/hooks/use-cart.ts

@@ -2,6 +2,18 @@
 
 import { useCartStore } from '../stores/cart-store';
 
+/**
+ * The shopper's cart and the actions that change it. The cart is kept in the
+ * browser (per sales channel) and survives a reload. `addProduct` refuses a
+ * product that needs a variant when none is given and tells the shopper to
+ * choose an option; otherwise it adds the line and shows an "Added to cart" toast.
+ *
+ * Use {@link useShopCart} for the lines and totals of a single shop.
+ *
+ * @example
+ * const { items, addProduct, setQuantity } = useCart();
+ * <button onClick={() => addProduct(product, 1, matchedVariant)}>Add to cart</button>
+ */
 export function useCart() {
   return {
     items: useCartStore((state) => state.items),