@usequeek/theme-kit 0.1.0

package/components/auth/auth-signup-step.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+import { useAuthFlow } from '../../hooks/use-auth-flow';
+
+export function AuthSignupStep(): JSX.Element {
+  const {
+    firstName, setFirstName,
+    lastName, setLastName,
+    submitRegister,
+    loading, error,
+    goToEmailOtp,
+  } = useAuthFlow();
+
+  return (
+    <div className="core-auth__step core-auth__step--signup">
+      <h2 className="core-auth__title">Create your account</h2>
+      <p className="core-auth__sub">Just a few details to get you 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"
+      />
+      {error ? <p className="core-auth__error">{error}</p> : null}
+
+      <button
+        type="button"
+        className="core-submit-btn"
+        onClick={() => void submitRegister()}
+        onKeyDown={(e) => { if (e.key === 'Enter') void submitRegister(); }}
+        disabled={loading || !firstName.trim()}
+      >
+        {loading ? 'Creating account…' : 'Create account'}
+      </button>
+
+      <button type="button" className="core-auth__link" onClick={goToEmailOtp}>
+        ← Use a different email
+      </button>
+    </div>
+  );
+}

package/components/blog/category-filter.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+import Link from 'next/link';
+import type { BlogCategory } from '../../types/page';
+import { useStorefront } from '../../provider';
+
+/**
+ * Shared blog category browse bar. Links to `${basePath}/blog?category=slug`.
+ * Renders nothing when the vendor has no blog categories.
+ *
+ * - `variant="pills"` (default): compact pill filter row.
+ * - `variant="tabs"`: a full tab bar (used at the top of the blog list) with an
+ *   "All" tab, one tab per category, an active-tab underline, and a subtle
+ *   per-tab post count. Scrolls horizontally on overflow instead of wrapping.
+ *
+ * Themes style via `.core-cat-filter*` / `.core-cat-tabs*` (brand-var driven).
+ */
+export function CategoryFilter({
+  categories,
+  active,
+  variant = 'pills',
+  className,
+}: {
+  categories?: BlogCategory[] | null;
+  active?: string;
+  variant?: 'pills' | 'tabs';
+  className?: string;
+}): JSX.Element | null {
+  const { basePath } = useStorefront();
+
+  if (!categories || categories.length === 0) {
+    return null;
+  }
+
+  if (variant === 'tabs') {
+    return (
+      <nav
+        className={`core-cat-tabs${className ? ` ${className}` : ''}`}
+        aria-label="Blog categories"
+      >
+        <Link
+          href={`${basePath}/blog`}
+          className={`core-cat-tabs__item${!active ? ' is-active' : ''}`}
+          aria-current={!active ? 'page' : undefined}
+        >
+          <span className="core-cat-tabs__label">All</span>
+        </Link>
+        {categories.map((category) => {
+          const isActive = active === category.slug;
+          return (
+            <Link
+              key={category.slug}
+              href={`${basePath}/blog?category=${encodeURIComponent(category.slug)}`}
+              className={`core-cat-tabs__item${isActive ? ' is-active' : ''}`}
+              aria-current={isActive ? 'page' : undefined}
+            >
+              <span className="core-cat-tabs__label">{category.name}</span>
+              {typeof category.posts_count === 'number' ? (
+                <span className="core-cat-tabs__count">{category.posts_count}</span>
+              ) : null}
+            </Link>
+          );
+        })}
+      </nav>
+    );
+  }
+
+  return (
+    <nav className={`core-cat-filter${className ? ` ${className}` : ''}`} aria-label="Blog categories">
+      <Link
+        href={`${basePath}/blog`}
+        className={`core-cat-filter__item${!active ? ' is-active' : ''}`}
+        aria-current={!active ? 'page' : undefined}
+      >
+        All
+      </Link>
+      {categories.map((category) => {
+        const isActive = active === category.slug;
+        return (
+          <Link
+            key={category.slug}
+            href={`${basePath}/blog?category=${encodeURIComponent(category.slug)}`}
+            className={`core-cat-filter__item${isActive ? ' is-active' : ''}`}
+            aria-current={isActive ? 'page' : undefined}
+          >
+            {category.name}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}

package/components/blog/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared framework-owned blog components. Themes reuse these across their
+ * blog list + post detail pages so reader features (byline, share, related,
+ * category filter, pagination) live in one place — themes only place and
+ * style them via `.core-*` selectors.
+ */
+export { PostMeta } from './post-meta';
+export { ShareButtons } from './share-buttons';
+export { RelatedPosts } from './related-posts';
+export { CategoryFilter } from './category-filter';
+export { PostCategories } from './post-categories';
+export { BlogPagination } from './pagination';

package/components/blog/pagination.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import Link from 'next/link';
+import type { Pagination } from '../../types/page';
+import { useStorefront } from '../../provider';
+
+/**
+ * Shared blog pagination (Prev / page indicator / Next). SSR page-based
+ * navigation preserving the active category. Renders nothing when there is
+ * only a single page. Themes style via `.core-pagination*` selectors.
+ */
+export function BlogPagination({
+  pagination,
+  category,
+  className,
+}: {
+  pagination?: Pagination;
+  category?: string;
+  className?: string;
+}): JSX.Element | null {
+  const { basePath } = useStorefront();
+
+  if (!pagination) {
+    return null;
+  }
+
+  const current = pagination.current_page ?? 1;
+  const perPage = pagination.per_page ?? 0;
+  const total = pagination.total ?? 0;
+  const lastPage = perPage > 0 && total > 0 ? Math.ceil(total / perPage) : undefined;
+  const hasNext = pagination.has_more ?? (lastPage ? current < lastPage : false);
+  const hasPrev = current > 1;
+
+  if (!hasNext && !hasPrev) {
+    return null;
+  }
+
+  const buildHref = (page: number): string => {
+    const params = new URLSearchParams();
+    if (category) {
+      params.set('category', category);
+    }
+    if (page > 1) {
+      params.set('page', String(page));
+    }
+    const query = params.toString();
+    return `${basePath}/blog${query ? `?${query}` : ''}`;
+  };
+
+  return (
+    <nav className={`core-pagination${className ? ` ${className}` : ''}`} aria-label="Blog pagination">
+      {hasPrev ? (
+        <Link href={buildHref(current - 1)} className="core-pagination__link" rel="prev">
+          ← Previous
+        </Link>
+      ) : (
+        <span className="core-pagination__link is-disabled" aria-disabled="true">
+          ← Previous
+        </span>
+      )}
+      <span className="core-pagination__status">{lastPage ? `Page ${current} of ${lastPage}` : `Page ${current}`}</span>
+      {hasNext ? (
+        <Link href={buildHref(current + 1)} className="core-pagination__link" rel="next">
+          Next →
+        </Link>
+      ) : (
+        <span className="core-pagination__link is-disabled" aria-disabled="true">
+          Next →
+        </span>
+      )}
+    </nav>
+  );
+}

package/components/blog/post-categories.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import Link from 'next/link';
+import type { BlogCategory } from '../../types/page';
+import { useStorefront } from '../../provider';
+
+/**
+ * Renders a post's categories as links to the blog list filtered by category
+ * (`${basePath}/blog?category=slug`, exactly like {@link CategoryFilter}).
+ * Themes pass their own pill className via `itemClassName`. Renders nothing
+ * when the post has no categories — themes keep their own tag fallback around
+ * it. Wrapper carries `.core-post-cats` so themes can optionally style spacing.
+ */
+export function PostCategories({
+  categories,
+  itemClassName,
+  className,
+}: {
+  categories?: BlogCategory[] | null;
+  itemClassName?: string;
+  className?: string;
+}): JSX.Element | null {
+  const { basePath } = useStorefront();
+
+  if (!categories || categories.length === 0) {
+    return null;
+  }
+
+  return (
+    <span className={`core-post-cats${className ? ` ${className}` : ''}`}>
+      {categories.map((category) => (
+        <Link
+          key={category.slug}
+          href={`${basePath}/blog?category=${encodeURIComponent(category.slug)}`}
+          className={itemClassName}
+        >
+          {category.name}
+        </Link>
+      ))}
+    </span>
+  );
+}

package/components/blog/post-meta.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import type { Post } from '../../types/page';
+import { useStorefront } from '../../provider';
+import { Image } from '../image';
+
+function formatDate(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+  return date.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+}
+
+/**
+ * Shared post byline: author (avatar + name, falling back to the vendor),
+ * published date, and reading time. Themes place it in their post header and
+ * style via `.core-post-meta*` selectors (colours inherit brand vars).
+ */
+export function PostMeta({ post, className }: { post: Post; className?: string }): JSX.Element {
+  const { vendor } = useStorefront();
+
+  const authorName = post.author?.name ?? vendor.name ?? null;
+  const authorAvatar = post.author?.avatar_url ?? vendor.logo ?? null;
+  const published = post.published_at ? formatDate(post.published_at) : '';
+  const readingTime = post.reading_time && post.reading_time > 0 ? `${post.reading_time} min read` : '';
+
+  return (
+    <div className={`core-post-meta${className ? ` ${className}` : ''}`}>
+      {authorName ? (
+        <span className="core-post-meta__author">
+          <Image
+            src={authorAvatar || undefined}
+            alt={authorName}
+            className="core-post-meta__avatar"
+            placeholder={{ label: authorName, width: 64, height: 64, variant: 'square' }}
+          />
+          <span className="core-post-meta__author-name">{authorName}</span>
+        </span>
+      ) : null}
+      {published ? (
+        <time className="core-post-meta__date" dateTime={post.published_at ?? undefined}>
+          {published}
+        </time>
+      ) : null}
+      {readingTime ? <span className="core-post-meta__reading">{readingTime}</span> : null}
+    </div>
+  );
+}

package/components/blog/related-posts.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import Link from 'next/link';
+import type { Post } from '../../types/page';
+import { useStorefront } from '../../provider';
+import { Image } from '../image';
+
+/**
+ * Shared "Related posts" grid. Renders nothing when there are no related
+ * posts. Themes style via `.core-related*` selectors.
+ */
+export function RelatedPosts({
+  posts,
+  className,
+  heading = 'Related posts',
+}: {
+  posts?: Post[] | null;
+  className?: string;
+  heading?: string;
+}): JSX.Element | null {
+  const { basePath } = useStorefront();
+
+  if (!posts || posts.length === 0) {
+    return null;
+  }
+
+  return (
+    <section className={`core-related${className ? ` ${className}` : ''}`}>
+      <h2 className="core-related__heading">{heading}</h2>
+      <div className="core-related__grid">
+        {posts.map((post) => (
+          <Link key={post.id ?? post.slug} href={`${basePath}/blog/${post.slug}`} className="core-related__card">
+            <div className="core-related__media">
+              <Image
+                src={post.cover_image_url || undefined}
+                alt={post.title}
+                className="core-related__img"
+                placeholder={{ label: post.title, width: 600, height: 400, variant: 'card' }}
+              />
+            </div>
+            <div className="core-related__body">
+              {post.blog_categories?.[0]?.name ? (
+                <span className="core-related__cat">{post.blog_categories[0].name}</span>
+              ) : post.tags?.[0] ? (
+                <span className="core-related__cat">{post.tags[0]}</span>
+              ) : null}
+              <h3 className="core-related__title">{post.title}</h3>
+            </div>
+          </Link>
+        ))}
+      </div>
+    </section>
+  );
+}

package/components/blog/share-buttons.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+interface ShareButtonsProps {
+  title: string;
+  className?: string;
+}
+
+/**
+ * Shared post share bar: native share (where supported), copy link, and
+ * X / Facebook / WhatsApp intents. The URL is read on the client so it works
+ * on custom domains and subdomains without server knowledge of the host.
+ * Themes style via `.core-share*` selectors.
+ */
+export function ShareButtons({ title, className }: ShareButtonsProps): JSX.Element {
+  const [url, setUrl] = useState('');
+  const [copied, setCopied] = useState(false);
+  const [canNativeShare, setCanNativeShare] = useState(false);
+
+  useEffect(() => {
+    setUrl(window.location.href);
+    setCanNativeShare(typeof navigator !== 'undefined' && typeof navigator.share === 'function');
+  }, []);
+
+  const encodedUrl = encodeURIComponent(url);
+  const encodedTitle = encodeURIComponent(title);
+
+  const nativeShare = async (): Promise<void> => {
+    try {
+      await navigator.share({ title, url });
+    } catch {
+      /* user dismissed — no-op */
+    }
+  };
+
+  const copyLink = async (): Promise<void> => {
+    try {
+      await navigator.clipboard.writeText(url);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 2000);
+    } catch {
+      /* clipboard unavailable — no-op */
+    }
+  };
+
+  return (
+    <div className={`core-share${className ? ` ${className}` : ''}`}>
+      <span className="core-share__label">Share</span>
+      <div className="core-share__actions">
+        {canNativeShare ? (
+          <button type="button" className="core-share__btn" onClick={nativeShare} aria-label="Share">
+            Share
+          </button>
+        ) : null}
+        <a
+          className="core-share__btn"
+          href={`https://x.com/intent/post?url=${encodedUrl}&text=${encodedTitle}`}
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label="Share on X"
+        >
+          X
+        </a>
+        <a
+          className="core-share__btn"
+          href={`https://www.facebook.com/sharer/sharer.php?u=${encodedUrl}`}
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label="Share on Facebook"
+        >
+          Facebook
+        </a>
+        <a
+          className="core-share__btn"
+          href={`https://wa.me/?text=${encodedTitle}%20${encodedUrl}`}
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label="Share on WhatsApp"
+        >
+          WhatsApp
+        </a>
+        <button type="button" className="core-share__btn" onClick={copyLink} aria-label="Copy link">
+          {copied ? 'Copied' : 'Copy link'}
+        </button>
+      </div>
+    </div>
+  );
+}

package/components/cart/cart-panel-controller.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+import { useEffect, type ReactNode } from 'react';
+import { useRouter } from 'next/navigation';
+import type { CartItem } from '../../types/cart';
+import { useStorefront } from '../../provider';
+import { useHref } from '../../hooks/use-href';
+import { useShopCart } from '../../hooks/use-shop-cart';
+import { useCartPanelStore } from '../../stores/cart-panel-store';
+
+export interface CartPanelControllerRenderProps {
+  isOpen: boolean;
+  items: CartItem[];
+  total: number;
+  currency: string;
+  onClose: () => void;
+  onCheckout: () => void;
+  onViewCart: () => void;
+  onBrowseCollections: () => void;
+  onSetQuantity: (id: string, shopId: string, quantity: number) => void;
+  onRemove: (id: string, shopId: string) => void;
+}
+
+export function CartPanelController({
+  children,
+}: {
+  children: (props: CartPanelControllerRenderProps) => ReactNode;
+}): JSX.Element {
+  const { vendor } = useStorefront();
+  const href = useHref();
+  const router = useRouter();
+  const isOpen = useCartPanelStore((state) => state.isOpen);
+  const closePanel = useCartPanelStore((state) => state.close);
+  const { items, total, setQuantity, removeItem } = useShopCart(vendor.id);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const previousOverflow = document.body.style.overflow;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') closePanel();
+    };
+    document.body.style.overflow = 'hidden';
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, [isOpen, closePanel]);
+
+  const navigate = (path: string) => {
+    closePanel();
+    router.push(href(path));
+  };
+
+  return children({
+    isOpen,
+    items,
+    total,
+    currency: vendor.currency ?? 'NGN',
+    onClose: closePanel,
+    onCheckout: () => navigate('/checkout'),
+    onViewCart: () => navigate('/cart'),
+    onBrowseCollections: () => navigate('/collections'),
+    onSetQuantity: setQuantity,
+    onRemove: removeItem,
+  }) as JSX.Element;
+}