@usequeek/theme-kit 0.1.0

package/apps/follow-card.tsx

@@ -0,0 +1,192 @@
+'use client';
+
+import { useState, useCallback, useEffect } from 'react';
+import { useStorefront } from '../provider';
+import { useUserStore } from '../stores/user-store';
+import { useAuthModalStore } from '../stores/auth-modal-store';
+import { getQueekClient } from '../sdk/queek-client';
+
+interface FollowData {
+  following: boolean;
+  shared_contact: boolean;
+  followers_count: number;
+}
+
+const DISMISS_KEY = 'queek_follow_card_dismissed';
+
+function getDismissedVendors(): string[] {
+  try {
+    return JSON.parse(localStorage.getItem(DISMISS_KEY) || '[]');
+  } catch {
+    return [];
+  }
+}
+
+function persistDismiss(vendorId: string) {
+  try {
+    const list = getDismissedVendors();
+    if (!list.includes(vendorId)) {
+      list.push(vendorId);
+      localStorage.setItem(DISMISS_KEY, JSON.stringify(list));
+    }
+  } catch { /* noop */ }
+}
+
+const POSITION_CLASS: Record<string, string> = {
+  'bottom-right': 'core-follow-card--bottom-right',
+  'bottom-left': 'core-follow-card--bottom-left',
+  'center-right': 'core-follow-card--center-right',
+  'center-left': 'core-follow-card--center-left',
+};
+
+export function FollowCard({ display }: { display?: 'floating' | 'inline' } = {}): JSX.Element | null {
+  const { config, vendor } = useStorefront();
+  const followConfig = config.apps?.follow_card;
+  const resolvedDisplay = display ?? followConfig?.display ?? 'floating';
+  const user = useUserStore((s) => s.user);
+  const openAuth = useAuthModalStore((s) => s.open);
+
+  const [isFollowing, setIsFollowing] = useState(false);
+  const [followersCount, setFollowersCount] = useState(config.followers_count ?? 0);
+  const [shareContact, setShareContact] = useState(true);
+  const [loading, setLoading] = useState(false);
+  const [dismissed, setDismissed] = useState(false);
+  const [checked, setChecked] = useState(false);
+
+  // Check follow status when user is logged in
+  useEffect(() => {
+    if (!user || !vendor.slug) {
+      setChecked(true);
+      return;
+    }
+    const client = getQueekClient(vendor.slug);
+    client.get<FollowData>('/client/store/follow/status')
+      .then((res) => {
+        setIsFollowing(res.data?.following ?? false);
+        setFollowersCount(res.data?.followers_count ?? followersCount);
+      })
+      .catch(() => {})
+      .finally(() => setChecked(true));
+  }, [user, vendor.slug]);
+
+  // Check persistent dismiss
+  useEffect(() => {
+    if (vendor.id && getDismissedVendors().includes(vendor.id)) {
+      setDismissed(true);
+    }
+  }, [vendor.id]);
+
+  const handleFollow = useCallback(async () => {
+    if (!user) {
+      openAuth('login');
+      return;
+    }
+
+    setLoading(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      const res = await client.post<FollowData>('/client/store/follow', {
+        share_contact: shareContact,
+      });
+      setIsFollowing(res.data?.following ?? true);
+      setFollowersCount(res.data?.followers_count ?? followersCount + 1);
+    } catch {
+      // Silently fail
+    } finally {
+      setLoading(false);
+    }
+  }, [user, vendor.slug, openAuth, shareContact]);
+
+  const handleUnfollow = useCallback(async () => {
+    if (!user) return;
+
+    setLoading(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      const res = await client.post<FollowData>('/client/store/follow?_method=DELETE', {});
+      setIsFollowing(res.data?.following ?? false);
+      setFollowersCount(res.data?.followers_count ?? Math.max(0, followersCount - 1));
+    } catch {
+      // Silently fail
+    } finally {
+      setLoading(false);
+    }
+  }, [user, vendor.slug]);
+
+  const handleDismiss = useCallback(() => {
+    setDismissed(true);
+    if (vendor.id) persistDismiss(vendor.id);
+  }, [vendor.id]);
+
+  if (!followConfig?.enabled || dismissed || !checked) return null;
+  // Don't show to users already following
+  if (isFollowing) return null;
+
+  const isFloating = resolvedDisplay === 'floating';
+  const posClass = isFloating
+    ? POSITION_CLASS[followConfig.position ?? 'bottom-right'] ?? POSITION_CLASS['bottom-right']
+    : '';
+
+  return (
+    <div
+      className={`core-follow-card ${isFloating ? `core-follow-card--floating ${posClass}` : 'core-follow-card--inline'}`}
+      role="complementary"
+      aria-label="Follow this store"
+    >
+      {isFloating && (
+        <button
+          type="button"
+          className="core-follow-card__dismiss"
+          onClick={handleDismiss}
+          aria-label="Don't show again"
+          title="Don't show again"
+        >
+          <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" width="12" height="12">
+            <path d="M3 3l10 10M13 3L3 13" />
+          </svg>
+        </button>
+      )}
+
+      <div className="core-follow-card__body">
+        {vendor.logo && (
+          <img
+            src={vendor.logo}
+            alt={vendor.name ?? ''}
+            className="core-follow-card__logo"
+          />
+        )}
+        <div className="core-follow-card__text">
+          <p className="core-follow-card__title">
+            Follow {vendor.name ?? 'this store'}
+          </p>
+          <p className="core-follow-card__sub">
+            Get notified about new arrivals and exclusive offers.
+          </p>
+          {followersCount > 0 && (
+            <p className="core-follow-card__count">
+              {followersCount.toLocaleString()} {followersCount === 1 ? 'follower' : 'followers'}
+            </p>
+          )}
+        </div>
+      </div>
+
+      <label className="core-follow-card__consent">
+        <input
+          type="checkbox"
+          checked={shareContact}
+          onChange={(e) => setShareContact(e.target.checked)}
+          className="core-follow-card__checkbox"
+        />
+        <span>Share my contact info with this store</span>
+      </label>
+      <button
+        type="button"
+        className="core-follow-card__btn"
+        onClick={handleFollow}
+        disabled={loading}
+      >
+        {loading ? 'Following...' : 'Follow'}
+      </button>
+    </div>
+  );
+}

package/apps/gtag.ts

@@ -0,0 +1,19 @@
+'use client';
+
+declare global {
+  interface Window {
+    dataLayer?: unknown[];
+  }
+}
+
+/**
+ * Pushes straight to `dataLayer` rather than calling `window.gtag()` directly —
+ * this queues correctly even before gtag.js has finished loading (the same
+ * mechanism the inline bootstrap snippet in analytics.tsx relies on), so
+ * callers never need to guard on load order.
+ */
+export function gtagPush(...args: unknown[]): void {
+  if (typeof window === 'undefined') return;
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push(args);
+}

package/apps/subscribe-form.tsx

@@ -0,0 +1,124 @@
+'use client';
+
+import { useCallback, useId, useState } from 'react';
+import { useStorefront } from '../provider';
+import { getQueekClient } from '../sdk/queek-client';
+import type { SubscribeFormProps } from '../types/theme';
+
+type Status = 'idle' | 'saving' | 'done' | 'error';
+
+/**
+ * Newsletter capture — the storefront's only way to hand a vendor an email
+ * without forcing a full account signup. `FollowCard` requires an account
+ * (it opens the auth modal), so before this the cheapest path into a
+ * vendor's campaign audience was a whole registration flow.
+ *
+ * Backed by `POST /client/store/subscribe`, which is public by design: no
+ * auth, one field. It answers identically whether the address is new,
+ * already subscribed, or previously opted out, so this form can never be
+ * used to probe who shops here.
+ *
+ * The `subscribe` app's `inline` variant (the theme-declared default) — a
+ * theme's own `getSubscribeForm` dispatch renders this directly, passing
+ * heading/tagline/cta straight through with no gate of its own; gating on
+ * `config.apps?.subscribe?.enabled` happens once, centrally, in whichever
+ * variant dispatch mounts it (see vendor-shell.tsx / a theme's footer).
+ */
+export function SubscribeForm({
+  heading = 'Stay in the loop',
+  tagline = 'New arrivals and offers, straight to your inbox.',
+  cta = 'Subscribe',
+  layout = 'stacked',
+  onSuccess,
+}: SubscribeFormProps & { layout?: 'stacked' | 'inline'; onSuccess?: () => void } = {}): JSX.Element {
+  const { vendor } = useStorefront();
+  const emailId = useId();
+  const nameId = useId();
+
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [status, setStatus] = useState<Status>('idle');
+  const [message, setMessage] = useState('');
+
+  const handleSubmit = useCallback(
+    async (event: React.FormEvent) => {
+      event.preventDefault();
+      if (status === 'saving' || email.trim() === '') return;
+
+      setStatus('saving');
+      try {
+        const res = await getQueekClient(vendor.slug ?? undefined).post<{ message?: string }>(
+          '/client/store/subscribe',
+          { email: email.trim(), name: name.trim() || undefined },
+        );
+        setStatus('done');
+        setMessage(res.data?.message ?? "You're subscribed.");
+        setName('');
+        setEmail('');
+        onSuccess?.();
+      } catch {
+        setStatus('error');
+        setMessage('That didn’t go through. Please check the address and try again.');
+      }
+    },
+    [name, email, status, vendor.slug, onSuccess],
+  );
+
+  if (status === 'done') {
+    return (
+      <div className="core-subscribe core-subscribe--done" role="status">
+        <p className="core-subscribe__done">{message}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`core-subscribe core-subscribe--${layout}`}>
+      {heading ? <p className="core-subscribe__heading">{heading}</p> : null}
+      {tagline ? <p className="core-subscribe__tagline">{tagline}</p> : null}
+
+      <form className="core-subscribe__form" onSubmit={handleSubmit} noValidate>
+        <label className="core-subscribe__label" htmlFor={nameId}>
+          Name
+        </label>
+        <input
+          id={nameId}
+          className="core-subscribe__input"
+          type="text"
+          name="name"
+          autoComplete="name"
+          placeholder="Name (optional)"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+        />
+        <label className="core-subscribe__label" htmlFor={emailId}>
+          Email address
+        </label>
+        <input
+          id={emailId}
+          className="core-subscribe__input"
+          type="email"
+          name="email"
+          autoComplete="email"
+          inputMode="email"
+          placeholder="you@example.com"
+          value={email}
+          onChange={(e) => {
+            setEmail(e.target.value);
+            if (status === 'error') setStatus('idle');
+          }}
+          required
+        />
+        <button className="core-subscribe__button" type="submit" disabled={status === 'saving'}>
+          {status === 'saving' ? 'Subscribing…' : cta}
+        </button>
+      </form>
+
+      {status === 'error' ? (
+        <p className="core-subscribe__error" role="alert">
+          {message}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/client.ts

@@ -0,0 +1,52 @@
+'use client';
+
+/**
+ * The client half of the public theme surface — hooks, stores and components.
+ * See ./index.ts for why this is split.
+ */
+
+export * from './provider';
+export * from './page-renderer';
+export * from './edit-mode';
+export * from './theme-variant-resolver';
+export * from './shared-blocks';
+export * from './components/blog';
+export * from './components/image';
+export * from './components/product-media-frame';
+export * from './components/variant-picker';
+export * from './components/auth/auth-flow';
+export * from './components/cart/default-cart-shell';
+export * from './components/cart/cart-panel-controller';
+export * from './components/checkout/default-checkout-shell';
+export * from './components/checkout/checkout-contact';
+export * from './components/checkout/policy-links';
+export * from './apps/follow-card';
+export * from './apps/subscribe-form';
+export * from './api/collections';
+export * from './api/orders';
+export * from './hooks/use-href';
+export * from './hooks/use-auth';
+export * from './hooks/use-cart';
+export * from './hooks/use-shop-cart';
+export * from './hooks/use-products';
+export * from './hooks/use-product-detail';
+export * from './hooks/use-product-sections';
+export * from './hooks/use-related-products';
+export * from './hooks/use-categories';
+export * from './hooks/use-collection-params';
+export * from './hooks/use-shop';
+export * from './hooks/use-shop-params';
+export * from './hooks/use-search';
+export * from './hooks/use-posts';
+export * from './hooks/use-reviews';
+export * from './hooks/use-variant-selection';
+export * from './hooks/use-address-autocomplete';
+export * from './hooks/use-resolve-coordinates';
+export * from './stores/cart-panel-store';
+export * from './stores/product-modal-store';
+export * from './stores/search-modal-store';
+export * from './stores/orders-sheet-store';
+export * from './stores/location-store';
+export * from './stores/address-modal-store';
+export * from './stores/auth-modal-store';
+export * from './stores/cart-store';

package/components/auth/auth-email-login-step.tsx

@@ -0,0 +1,46 @@
+'use client';
+import { useAuthFlow } from '../../hooks/use-auth-flow';
+
+export function AuthEmailLoginStep(): JSX.Element {
+  const { email, setEmail, password, setPassword, submitEmailLogin, loading, error, goToEmailRegister, goToEmailOtp } = useAuthFlow();
+
+  return (
+    <div className="core-auth__step core-auth__step--email-login">
+      <h2 className="core-auth__title">Sign in</h2>
+      <p className="core-auth__sub">Enter your email and password</p>
+      <input
+        type="email"
+        className="core-input"
+        placeholder="Email address"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        autoComplete="email"
+        autoFocus
+      />
+      <input
+        type="password"
+        className="core-input"
+        placeholder="Password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        onKeyDown={(e) => { if (e.key === 'Enter') void submitEmailLogin(); }}
+        autoComplete="current-password"
+      />
+      {error ? <p className="core-auth__error">{error}</p> : null}
+      <button
+        type="button"
+        className="core-submit-btn"
+        onClick={() => void submitEmailLogin()}
+        disabled={loading || !email.trim() || !password}
+      >
+        {loading ? 'Signing in…' : 'Sign in'}
+      </button>
+      <button type="button" className="core-auth__link" onClick={goToEmailRegister}>
+        Don&apos;t have an account? Create one
+      </button>
+      <button type="button" className="core-auth__link" onClick={goToEmailOtp}>
+        Use an email code instead
+      </button>
+    </div>
+  );
+}

package/components/auth/auth-email-otp-step.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { useAuthFlow } from '../../hooks/use-auth-flow';
+
+export function AuthEmailOtpStep(): JSX.Element {
+  const { email, setEmail, submitEmailRequestOtp, loading, error, initiateGoogleAuth, goToEmailLogin } = useAuthFlow();
+
+  return (
+    <div className="core-auth__step core-auth__step--email-otp">
+      <h2 className="core-auth__title">Sign in</h2>
+      <p className="core-auth__sub">Enter your email to continue</p>
+
+      <button
+        type="button"
+        className="core-auth__google-btn"
+        onClick={() => void initiateGoogleAuth()}
+        disabled={loading}
+      >
+        <svg className="core-auth__google-icon" viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" fill="#4285F4"/>
+          <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" fill="#34A853"/>
+          <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l3.66-2.84z" fill="#FBBC05"/>
+          <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" fill="#EA4335"/>
+        </svg>
+        Continue with Google
+      </button>
+
+      <div className="core-auth__divider"><span>or</span></div>
+
+      <input
+        type="email"
+        className="core-input"
+        placeholder="your@email.com"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        onKeyDown={(e) => { if (e.key === 'Enter') void submitEmailRequestOtp(); }}
+        autoComplete="email"
+        autoFocus
+      />
+      {error ? <p className="core-auth__error">{error}</p> : null}
+      <button
+        type="button"
+        className="core-submit-btn"
+        onClick={() => void submitEmailRequestOtp()}
+        disabled={loading || !email.trim()}
+      >
+        {loading ? 'Sending code…' : 'Continue'}
+      </button>
+      <button type="button" className="core-auth__link" onClick={goToEmailLogin}>
+        Have a password? Sign in with it instead
+      </button>
+    </div>
+  );
+}

package/components/auth/auth-email-otp-verify-step.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { useRef } from 'react';
+import { useAuthFlow } from '../../hooks/use-auth-flow';
+
+const OTP_LENGTH = 6;
+
+export function AuthEmailOtpVerifyStep(): JSX.Element {
+  const { email, otp, setOtp, submitEmailVerifyOtp, submitEmailRequestOtp, goToEmailOtp, loading, error } = useAuthFlow();
+  const refs = useRef<(HTMLInputElement | null)[]>([]);
+
+  const focus = (i: number): void => {
+    refs.current[i]?.focus();
+  };
+
+  const handleChange = (i: number, raw: string): void => {
+    const char = raw.replace(/\D/g, '').slice(-1);
+    const next = otp.split('');
+    next[i] = char;
+    const joined = next.join('').slice(0, OTP_LENGTH);
+    setOtp(joined);
+    if (char && i < OTP_LENGTH - 1) focus(i + 1);
+    if (joined.length === OTP_LENGTH) void submitEmailVerifyOtp();
+  };
+
+  const handleKeyDown = (i: number, e: React.KeyboardEvent<HTMLInputElement>): void => {
+    if (e.key === 'Backspace') {
+      if (otp[i]) {
+        const next = otp.split('');
+        next[i] = '';
+        setOtp(next.join(''));
+      } else if (i > 0) {
+        focus(i - 1);
+      }
+    } else if (e.key === 'Enter' && otp.length === OTP_LENGTH) {
+      void submitEmailVerifyOtp();
+    }
+  };
+
+  return (
+    <div className="core-auth__step core-auth__step--email-otp-verify">
+      <h2 className="core-auth__title">Enter code</h2>
+      <p className="core-auth__sub">
+        {OTP_LENGTH}-digit code sent to <strong>{email}</strong>
+      </p>
+      <div className="core-auth-otp">
+        {Array.from({ length: OTP_LENGTH }).map((_, i) => (
+          <input
+            key={i}
+            ref={(el) => { refs.current[i] = el; }}
+            className="core-auth-otp__box"
+            type="text"
+            inputMode="numeric"
+            maxLength={1}
+            value={otp[i] ?? ''}
+            onChange={(e) => handleChange(i, e.target.value)}
+            onKeyDown={(e) => handleKeyDown(i, e)}
+            onFocus={(e) => e.target.select()}
+            disabled={loading}
+            autoComplete={i === 0 ? 'one-time-code' : 'off'}
+            aria-label={`Digit ${i + 1}`}
+          />
+        ))}
+      </div>
+      {error ? <p className="core-auth__error">{error}</p> : null}
+      <button
+        type="button"
+        className="core-submit-btn"
+        onClick={() => void submitEmailVerifyOtp()}
+        disabled={loading || otp.length < OTP_LENGTH}
+      >
+        {loading ? 'Verifying…' : 'Verify'}
+      </button>
+      <button type="button" className="core-auth__link" onClick={() => void submitEmailRequestOtp()}>
+        Resend code
+      </button>
+      <button type="button" className="core-auth__link" onClick={goToEmailOtp}>
+        ← Change email
+      </button>
+    </div>
+  );
+}

package/components/auth/auth-email-register-step.tsx

@@ -0,0 +1,59 @@
+'use client';
+import { useAuthFlow } from '../../hooks/use-auth-flow';
+
+export function AuthEmailRegisterStep(): JSX.Element {
+  const { firstName, setFirstName, lastName, setLastName, email, setEmail, password, setPassword, submitEmailRegister, loading, error, goToEmailLogin } = useAuthFlow();
+
+  return (
+    <div className="core-auth__step core-auth__step--email-register">
+      <h2 className="core-auth__title">Create account</h2>
+      <p className="core-auth__sub">Fill in your details to get started</p>
+      <input
+        type="text"
+        className="core-input"
+        placeholder="First name"
+        value={firstName}
+        onChange={(e) => setFirstName(e.target.value)}
+        autoComplete="given-name"
+        autoFocus
+      />
+      <input
+        type="text"
+        className="core-input"
+        placeholder="Last name (optional)"
+        value={lastName}
+        onChange={(e) => setLastName(e.target.value)}
+        autoComplete="family-name"
+      />
+      <input
+        type="email"
+        className="core-input"
+        placeholder="Email address"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        autoComplete="email"
+      />
+      <input
+        type="password"
+        className="core-input"
+        placeholder="Password (min 8 characters)"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        onKeyDown={(e) => { if (e.key === 'Enter') void submitEmailRegister(); }}
+        autoComplete="new-password"
+      />
+      {error ? <p className="core-auth__error">{error}</p> : null}
+      <button
+        type="button"
+        className="core-submit-btn"
+        onClick={() => void submitEmailRegister()}
+        disabled={loading || !firstName.trim() || !email.trim() || password.length < 8}
+      >
+        {loading ? 'Creating account…' : 'Create account'}
+      </button>
+      <button type="button" className="core-auth__link" onClick={goToEmailLogin}>
+        Already have an account? Sign in
+      </button>
+    </div>
+  );
+}

package/components/auth/auth-flow.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { AuthFlowProvider, useAuthFlow } from '../../hooks/use-auth-flow';
+import { AuthEmailOtpStep } from './auth-email-otp-step';
+import { AuthEmailOtpVerifyStep } from './auth-email-otp-verify-step';
+import { AuthSignupStep } from './auth-signup-step';
+import { AuthEmailLoginStep } from './auth-email-login-step';
+import { AuthEmailRegisterStep } from './auth-email-register-step';
+
+function AuthFlowInner(): JSX.Element | null {
+  const { step } = useAuthFlow();
+  if (step === 'email-otp') return <AuthEmailOtpStep />;
+  if (step === 'email-otp-verify') return <AuthEmailOtpVerifyStep />;
+  if (step === 'signup') return <AuthSignupStep />;
+  if (step === 'email-login') return <AuthEmailLoginStep />;
+  if (step === 'email-register') return <AuthEmailRegisterStep />;
+  return null;
+}
+
+export function AuthFlow(): JSX.Element {
+  return (
+    <AuthFlowProvider>
+      <AuthFlowInner />
+    </AuthFlowProvider>
+  );
+}