@usequeek/theme-kit 0.1.20 → 0.1.22

package/components/language-switcher.css

@@ -0,0 +1,131 @@
+/* ============================================================
+   LanguageSwitcher — the kit's language control. Prefix: qn-lang.
+   Colours, radius and type come from the --qn-* tokens, each with a
+   neutral fallback, so it sits in a header or a footer without theme
+   CSS. Logical properties only: it mirrors itself in RTL storefronts.
+   ============================================================ */
+
+.qn-lang {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  max-inline-size: 100%;
+  color: var(--qn-text, inherit);
+  font: inherit;
+}
+
+.qn-lang__icon {
+  inline-size: 18px;
+  block-size: 18px;
+  flex: none;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.6;
+  opacity: 0.75;
+}
+
+/* ── select ─────────────────────────────────────────────── */
+
+.qn-lang__field {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-inline-size: 0;
+}
+
+.qn-lang__select {
+  appearance: none;
+  min-inline-size: 44px;
+  min-block-size: 44px;
+  max-inline-size: min(100%, 16rem);
+  padding-block: 8px;
+  padding-inline: 12px 34px;
+  border: 1px solid var(--qn-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: var(--qn-radius-sm, 6px);
+  background-color: var(--qn-surface, transparent);
+  color: inherit;
+  font: inherit;
+  line-height: 1.25;
+  text-overflow: ellipsis;
+  cursor: pointer;
+}
+
+/* The chevron is an element, not a background, so it follows the inline-end
+   edge in both directions. */
+.qn-lang__chevron {
+  position: absolute;
+  inset-inline-end: 12px;
+  inline-size: 10px;
+  block-size: 10px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.8;
+  pointer-events: none;
+}
+
+.qn-lang__select:hover {
+  border-color: var(--qn-border-strong, currentColor);
+}
+
+.qn-lang__select:focus-visible {
+  outline: 2px solid var(--qn-focus, currentColor);
+  outline-offset: 2px;
+}
+
+.qn-lang__select option {
+  color: initial;
+  background: initial;
+}
+
+/* ── inline-list ────────────────────────────────────────── */
+
+.qn-lang--inline-list {
+  display: block;
+}
+
+.qn-lang__list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.qn-lang__link {
+  display: inline-flex;
+  align-items: center;
+  min-inline-size: 44px;
+  min-block-size: 44px;
+  padding-inline: 10px;
+  border-radius: var(--qn-radius-sm, 6px);
+  color: inherit;
+  font: inherit;
+  text-align: center;
+  text-decoration: none;
+  justify-content: center;
+}
+
+.qn-lang__link:hover {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.qn-lang__link[aria-current='true'] {
+  font-weight: 600;
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.qn-lang__link:focus-visible {
+  outline: 2px solid var(--qn-focus, currentColor);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .qn-lang__select,
+  .qn-lang__link {
+    transition: border-color 0.15s ease;
+  }
+}

package/components/language-switcher.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+import { useContext, 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 './language-switcher.css';
+
+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.
+   */
+  variant?: 'select' | 'inline-list';
+  /** 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. */
+  showNativeName?: boolean;
+  /**
+   * Take over the presentation. Called with the languages, the active one
+   * and `hrefFor` / `switchTo`; whatever it returns renders instead of the
+   * default control. Still renders nothing on a single-language store.
+   */
+  children?: (state: LanguageSwitcherState) => ReactNode;
+}
+
+/** What the render-prop receives: the `useLocales()` state plus the translated labels. */
+export interface LanguageSwitcherState extends LocalesState {
+  /** "Language" — the group label. */
+  label: string;
+  /** "Language: French" — names the control and the current language. */
+  labelFor: (locale: StoreLocale) => string;
+  /** The text to show for one language, honouring `showNativeName` / `showCode`. */
+  displayName: (locale: StoreLocale) => string;
+}
+
+/**
+ * The storefront's language control, placed by the theme where it wants it
+ * (a header, a footer, a menu). Renders nothing outside a storefront or when
+ * the store has a single language, so it is safe to place unconditionally.
+ *
+ * Switching keeps the page, the query string and the hash. Labels come from
+ * the theme strings (`language.label`, `language.named`) with English
+ * defaults. Colours and radius come from the `--qn-*` tokens; the layout is
+ * direction-agnostic, so it mirrors in right-to-left storefronts.
+ *
+ * A theme that places this sets `languageSwitcher: 'theme'` in its manifest,
+ * so the storefront does not also render its own floating control.
+ */
+export function LanguageSwitcher(props: LanguageSwitcherProps): JSX.Element | null {
+  const inStorefront = useContext(StorefrontContext) !== null;
+  if (!inStorefront) return null;
+  return <LanguageSwitcherInner {...props} />;
+}
+
+function LanguageSwitcherInner({
+  className,
+  variant = 'select',
+  showCode = false,
+  showNativeName = true,
+  children,
+}: LanguageSwitcherProps): JSX.Element | null {
+  const t = useThemeStrings();
+  const state = useLocales();
+  const { locales, active, hasMultiple, hrefFor, switchTo } = state;
+
+  if (!hasMultiple) return null;
+
+  const label = t('language.label');
+  const labelFor = (locale: StoreLocale): string => t('language.named', { name: locale.name });
+  const displayName = (locale: StoreLocale): string => {
+    const name = showNativeName ? locale.native_name : locale.name;
+    return showCode ? `${name} · ${locale.locale.toUpperCase()}` : name;
+  };
+
+  if (children) return <>{children({ ...state, label, labelFor, displayName })}</>;
+
+  const rootClass = ['qn-lang', `qn-lang--${variant}`, className].filter(Boolean).join(' ');
+
+  if (variant === 'inline-list') {
+    return (
+      <nav className={rootClass} aria-label={label} data-qn-language-switcher="" data-variant="inline-list">
+        <ul className="qn-lang__list">
+          {locales.map((locale) => {
+            const isActive = locale.locale === active.locale;
+            return (
+              <li key={locale.locale}>
+                <Link
+                  className="qn-lang__link"
+                  href={hrefFor(locale)}
+                  prefetch={false}
+                  lang={locale.html_lang}
+                  hrefLang={locale.hreflang}
+                  aria-current={isActive ? 'true' : undefined}
+                  aria-label={isActive ? labelFor(locale) : undefined}
+                  onClick={(event: MouseEvent<HTMLAnchorElement>) => {
+                    // Plain clicks go through `switchTo`, which reads the live
+                    // query string; modified clicks keep the browser default.
+                    if (event.defaultPrevented || event.button !== 0) return;
+                    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+                    event.preventDefault();
+                    switchTo(locale);
+                  }}
+                >
+                  {displayName(locale)}
+                </Link>
+              </li>
+            );
+          })}
+        </ul>
+      </nav>
+    );
+  }
+
+  return (
+    <div className={rootClass} role="group" aria-label={label} data-qn-language-switcher="" data-variant="select">
+      <svg className="qn-lang__icon" aria-hidden="true" viewBox="0 0 24 24" focusable="false">
+        <circle cx="12" cy="12" r="9" />
+        <path d="M3.5 12h17M12 3c2.3 2.4 3.5 5.4 3.5 9s-1.2 6.6-3.5 9c-2.3-2.4-3.5-5.4-3.5-9S9.7 5.4 12 3Z" />
+      </svg>
+      <span className="qn-lang__field">
+        <select
+          className="qn-lang__select"
+          aria-label={labelFor(active)}
+          value={active.locale}
+          onChange={(event) => switchTo(event.target.value)}
+        >
+          {locales.map((locale) => (
+            <option key={locale.locale} value={locale.locale} lang={locale.html_lang} dir={locale.dir}>
+              {displayName(locale)}
+            </option>
+          ))}
+        </select>
+        <svg className="qn-lang__chevron" aria-hidden="true" viewBox="0 0 10 10" focusable="false">
+          <path d="M1 3.5 5 7.5 9 3.5" />
+        </svg>
+      </span>
+    </div>
+  );
+}

package/components/markdown.tsx

@@ -16,7 +16,7 @@ import { Image } from './image';
  * Inline markdown images are routed through the core <Image> component so the
  * Smart Placeholder / fallback system applies (never a bare, unoptimized
  * <img>). Short-form snippets (footers, product blurbs) keep using the
- * lightweight `renderMarkdown` helper in `lib/core/utils/markdown`.
+ * lightweight `renderMarkdown` helper in `utils/markdown`.
  */
 function MarkdownImage({ src, alt }: ComponentPropsWithoutRef<'img'>): JSX.Element | null {
   if (!src || typeof src !== 'string') {

package/components/powered-by-queek.tsx

@@ -8,8 +8,8 @@ export interface PoweredByQueekProps {
   /** Extra class so a footer can position the link — styling stays theme-owned. */
   className?: string;
   /**
-   * Reserved for a future plan perk (paid removal). Defaults to false and is
-   * always rendered in v1 — there is no merchant-facing toggle for it.
+   * Lets a caller hide the link from a prop. Defaults to false; themes always
+   * render it visible — there is no merchant-facing toggle for it.
    */
   hidden?: boolean;
 }
@@ -18,8 +18,8 @@ export interface PoweredByQueekProps {
  * Core-owned storefront attribution — the `ProductMetafields` pattern: themes
  * import-and-place it, never re-implement it.
  *
- * Required on every footer variant of every theme (enforced by `theme-check`
- * rule `theme/footer-shows-powered-by` in the storefront repo). The link
+ * Required on every footer variant of every theme (enforced by the
+ * `theme/footer-shows-powered-by` rule of the theme 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

@@ -41,7 +41,7 @@ export function ProductMediaFrame({
   }
 
   // Thumbnail strips render at ~64-90px across every theme — the `thumb` tier
-  // (a fixed-src, never-in-a-srcset tier by contract) is exactly right there.
+  // (a fixed-src tier that is never part of a srcset) is exactly right there.
   const resolvedIntent: ImageIntent = intent ?? (variant === 'thumbnail' ? 'avatar' : 'hero');
 
   return (

package/components/product-metafields.tsx

@@ -23,8 +23,7 @@ export interface ProductMetafieldsProps {
  * Renders the product's presented metafields (all types), with linked
  * metaobject entries as cards. Renders nothing when there are no visible
  * values. Markup carries `core-metafields*` classes so each theme styles it
- * in its own `theme.css` (framework-owned styling contract) — no theme CSS
- * lives in core.
+ * in its own `theme.css` — no theme CSS ships in the kit.
  */
 
 function isEntry(value: unknown): value is MetaobjectEntry {
@@ -95,7 +94,7 @@ function renderScalar(value: MetafieldScalar, key: string, label: string, type:
 
   if (type === 'media_id') {
     return /^https?:\/\//i.test(text) ? (
-      // Media values arrive as resolved URLs (media contract) — plain <img>:
+      // Media values arrive as resolved URLs — plain <img>:
       // this is core, not a theme, so the themes' <Image> rule doesn't apply.
       <img className="core-metafields__image" src={text} alt={label} loading="lazy" />
     ) : (

package/components/variant-picker.tsx

@@ -14,17 +14,14 @@ interface VariantPickerProps {
 /**
  * Renders a product's option groups as color swatch / image swatch / text
  * buttons — standard e-commerce priority: color_code first, else a
- * representative image, else plain text. Extracted from quick-add-page.tsx
- * (the channel/chat add-to-cart flow, the one place that already got this
- * right) so the other two surfaces missing a picker entirely — the QR
- * ordering sheet and the default theme's quick-view modal — can reuse it
- * instead of a third reimplementation. Pair with `matchVariant()`
- * (lib/core/utils/match-variant.ts) to resolve `selectedOptions` into a real
+ * representative image, else plain text. Shared by every surface that needs
+ * an option picker (quick-add, the QR ordering sheet, a theme's quick-view
+ * modal) instead of each re-implementing it. Pair with `matchVariant()`
+ * (utils/match-variant.ts) to resolve `selectedOptions` into a real
  * `ProductVariant`, and gate the add action on that being non-null before
  * calling `addProduct`/`addItemWithAddons` — a variant-enabled product added
- * without one fails the cart save server-side (DiscountService's
- * VariantSelectionException) rather than merely being "no variant"; there
- * is no valid no-selection state to fall back to.
+ * without one fails the cart save server-side rather than merely being "no
+ * variant"; there is no valid no-selection state to fall back to.
  */
 export function VariantPicker({ product, selectedOptions, onSelect, className }: VariantPickerProps): JSX.Element | null {
   if (product.options.length === 0) return null;

package/demo.ts

@@ -1,16 +1,13 @@
 /**
  * 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.
+ * Shipped with the kit so a theme developer can render the demo data every
+ * theme carries in its `demo.json`: these are the functions that resolve its
+ * block references into real products, categories, posts and collections, so a
+ * theme can be previewed 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.
+ * Pure and type-only by construction: no `fs`, no `next`, no app imports, so
+ * these work identically in any preview.
  */
 import type { Block, ReviewItem } from './types/block';
 import type { Menu } from './types/menu';
@@ -81,11 +78,10 @@ export function getEnrichedPage<T extends Page>(page: T, demo: PreviewDemoData):
 }
 
 /**
- * `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.
+ * `demo.json`'s `posts` array must mirror the shape of a store's blog posts
+ * (`content: Block[]`, `cover_image_url`). Some themes authored it before that
+ * 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;

package/design-token-preview.tsx

@@ -58,8 +58,6 @@ export function attachDesignTokenPreviewListener(target: StylableTarget): () =>
  * onto the brand-root element's inline style, overlaying (not replacing)
  * the SSR vars from `getBrandCssVariables`. Never persisted — a normal
  * navigation/refresh reloads the real config.
- *
- * Frozen protocol: queek_backend `.agent/.tmp/live-preview-protocol.md`.
  */
 export function DesignTokenPreviewListener({
   targetRef,

package/edit-mode-active.tsx

@@ -11,9 +11,8 @@ const MESSAGE_SOURCE = 'queek-storefront';
 const MESSAGE_SOURCE_PARENT = 'queek-merchant';
 
 // Longest edge of the captured JPEG, in CSS px. Keeps the resulting
-// data-URI small (~50-150KB) so it can ride the qee chat POST body inline.
-// TODO: upload the capture to media (media.usequeek.com) and send a URL
-// instead of a data-URI once resume-persistence of attachments is needed.
+// data-URI small (~50-150KB) so it can ride a Qee chat request body inline
+// instead of being uploaded and referenced by URL.
 const CAPTURE_MAX_EDGE = 1000;
 
 async function captureBlock(el: HTMLElement): Promise<string> {
@@ -146,7 +145,7 @@ export function ActiveBlock({
 
   // Screenshot THIS section locally (edit mode only — the whole component tree
   // only renders inside the editor iframe) and hand the JPEG data-URI to the
-  // merchant, which turns it into a pending qee-chat attachment.
+  // merchant, which attaches it to a Qee chat message.
   const captureToQee = async (): Promise<void> => {
     const el = elRef.current;
     if (!el || capturing) return;

package/hooks/use-announcement.ts

@@ -8,7 +8,7 @@ const ROTATE_EVERY_MS = 6000;
  * Turns the stored announcement into the rotating one every header receives:
  * `text` is the message currently showing (so a header that only ever read
  * `text` rotates with no change), `messages`/`index`/`next`/`prev` let a
- * header draw its own pager (roast). Auto-advances while there is more than
+ * header draw its own pager. Auto-advances while there is more than
  * one message; a manual step restarts the clock so the message just chosen
  * gets its full turn.
  */

package/hooks/use-auth-flow.tsx

@@ -3,7 +3,7 @@
 import type { JSX } from 'react';
 import { createContext, useContext, useState, type ReactNode } from 'react';
 import { QueekSdkError, type EmailVerifyOtpResponse } from '@queekai/client-sdk';
-import { useStorefront } from '../provider';
+import { useStorefront, useThemeStrings } from '../provider';
 import { getQueekClient, setAuthTokens, QUEEK_AUTH_URL } from '../sdk/queek-client';
 import { useAuthModalStore } from '../stores/auth-modal-store';
 import { useUserStore } from '../stores/user-store';
@@ -63,32 +63,33 @@ interface PasswordAuthData {
   };
 }
 
-function mapEmailError(err: unknown): string {
+export function mapEmailError(err: unknown, t: (key: string) => string): string {
   if (err instanceof QueekSdkError) {
     switch (err.code) {
       case 'invalid_credentials':
-        return 'Wrong email or password. Please try again.';
+        return t('auth.error.credentials');
       case 'login_mode_mismatch':
-        return 'This account uses a different sign-in method (Google or phone).';
+        return t('auth.error.method');
       case 'account_already_exists':
-        return 'Email already registered. Please sign in instead.';
+        return t('auth.error.exists');
       case 'phone_already_exists':
-        return 'Phone number already in use.';
+        return t('auth.error.phone');
       case 'otp_resend_too_soon':
-        return 'Please wait before requesting another code.';
+        return t('auth.error.resend');
       case 'invalid_otp':
-        return 'Incorrect code. Please try again.';
+        return t('auth.error.code');
       default:
-        return err.message || 'Something went wrong. Please try again.';
+        return err.message || t('auth.error.generic');
     }
   }
-  return 'Something went wrong. Please try again.';
+  return t('auth.error.generic');
 }
 
 const AuthFlowContext = createContext<AuthFlowValue | null>(null);
 
 export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Element {
   const { vendor } = useStorefront();
+  const t = useThemeStrings();
   const closeModal = useAuthModalStore((s) => s.close);
   const setUser = useUserStore((s) => s.setUser);
 
@@ -131,7 +132,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       setOtp('');
       setStep('email-otp-verify');
     } catch (err) {
-      setError(mapEmailError(err));
+      setError(mapEmailError(err, t));
     } finally {
       setLoading(false);
     }
@@ -156,7 +157,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       applyUser(data.user);
       closeModal();
     } catch (err) {
-      setError(mapEmailError(err));
+      setError(mapEmailError(err, t));
       setOtp('');
     } finally {
       setLoading(false);
@@ -167,7 +168,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
 
   const submitRegister = async (): Promise<void> => {
     if (!firstName.trim()) {
-      setError('Please enter your first name.');
+      setError(t('auth.error.firstname'));
       return;
     }
     setError(null);
@@ -183,7 +184,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       applyUser(res.user);
       closeModal();
     } catch (err) {
-      setError(err instanceof QueekSdkError ? err.message : 'Registration failed. Try again.');
+      setError(err instanceof QueekSdkError ? err.message : t('auth.error.register'));
     } finally {
       setLoading(false);
     }
@@ -206,7 +207,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       applyUser(res.data.user);
       closeModal();
     } catch (err) {
-      setError(mapEmailError(err));
+      setError(mapEmailError(err, t));
     } finally {
       setLoading(false);
     }
@@ -230,7 +231,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       applyUser(res.data.user);
       closeModal();
     } catch (err) {
-      setError(mapEmailError(err));
+      setError(mapEmailError(err, t));
     } finally {
       setLoading(false);
     }
@@ -254,7 +255,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
         console.warn('[google-auth] redirect endpoint returned non-2xx', res.status, text);
         throw new Error(`Failed to initiate Google auth (HTTP ${res.status}).`);
       }
-      // Laravel envelope: { status, message, data: { url } }
+      // Response envelope: { status, message, data: { url } }
       const body = (await res.json()) as {
         data?: { url?: string; redirect_url?: string };
         url?: string;
@@ -272,7 +273,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
     } catch (err) {
       // eslint-disable-next-line no-console
       console.error('[google-auth] initiate failed', err);
-      setError('Could not connect to Google sign-in. Please try again.');
+      setError(t('auth.error.google'));
     } finally {
       setLoading(false);
     }