@usequeek/theme-kit 0.1.0

package/shared-blocks/divider.tsx

@@ -0,0 +1,17 @@
+'use client';
+
+import type { DividerBlockData } from '../types/block';
+
+/**
+ * Framework-owned divider block. Themes style via `.core-block-divider`
+ * and the modifier classes in their theme.css.
+ */
+export function CoreDividerBlock({ style }: DividerBlockData): JSX.Element {
+  const modifier = style === 'space' ? 'core-block-divider--space' : 'core-block-divider--line';
+
+  return (
+    <div className={`core-block-divider ${modifier}`} role="separator">
+      {style !== 'space' ? <hr className="core-block-divider__line" /> : null}
+    </div>
+  );
+}

package/shared-blocks/embed.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import type { EmbedBlockData } from '../types/block';
+
+/**
+ * Framework-owned embed block. Renders an iframe for any external URL
+ * (Instagram, Spotify, Twitter, custom). Themes style via `.core-block-embed`.
+ */
+export function CoreEmbedBlock({ url }: EmbedBlockData): JSX.Element {
+  if (!url) {
+    return (
+      <section className="core-block core-block-embed">
+        <div className="core-block-embed__wrap core-block-embed__wrap--empty">
+          <div className="core-block-embed__placeholder">
+            <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+              <polyline points="16 18 22 12 16 6" />
+              <polyline points="8 6 2 12 8 18" />
+            </svg>
+            <span>Paste an Instagram, Spotify, or iframe URL</span>
+          </div>
+        </div>
+      </section>
+    );
+  }
+
+  return (
+    <section className="core-block core-block-embed">
+      <div className="core-block-embed__wrap">
+        <iframe
+          className="core-block-embed__frame"
+          src={url}
+          title="Embedded content"
+          allowFullScreen
+          loading="lazy"
+          referrerPolicy="no-referrer-when-downgrade"
+        />
+      </div>
+    </section>
+  );
+}

package/shared-blocks/faq.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import type { FaqBlockData } from '../types/block';
+
+/**
+ * Framework-owned FAQ block. Renders an accessible, SSR-friendly accordion
+ * using native <details>/<summary> — works with zero JS. Themes style via
+ * `.core-block-faq` + sub-elements.
+ */
+export function CoreFaqBlock({ heading, items }: FaqBlockData): JSX.Element | null {
+  const safeItems = Array.isArray(items) ? items.filter((item) => item && item.question) : [];
+
+  if (safeItems.length === 0) return null;
+
+  return (
+    <section className="core-block core-block-faq">
+      {heading ? <h2 className="core-block-faq__heading">{heading}</h2> : null}
+      <div className="core-block-faq__list">
+        {safeItems.map((item, index) => (
+          <details key={index} className="core-block-faq__item">
+            <summary className="core-block-faq__question">
+              <span>{item.question}</span>
+              <svg
+                className="core-block-faq__chevron"
+                width="18"
+                height="18"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <polyline points="6 9 12 15 18 9" />
+              </svg>
+            </summary>
+            <div className="core-block-faq__answer">{item.answer}</div>
+          </details>
+        ))}
+      </div>
+    </section>
+  );
+}

package/shared-blocks/image.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import type { ImageBlockData } from '../types/block';
+import { Image } from '../components/image';
+
+/**
+ * Framework-owned image block. Wraps the core <Image> (with Smart Placeholder
+ * support) and an optional caption. Themes style via `.core-block-image`.
+ */
+export function CoreImageBlock({ url, alt, caption }: ImageBlockData): JSX.Element {
+  return (
+    <section className="core-block core-block-image">
+      <figure className="core-block-image__figure">
+        <Image
+          src={url || undefined}
+          alt={alt ?? ''}
+          className="core-block-image__img"
+          placeholder={{
+            label: alt ?? caption ?? undefined,
+            width: 1200,
+            height: 800,
+            variant: 'photo',
+          }}
+        />
+        {caption ? <figcaption className="core-block-image__caption">{caption}</figcaption> : null}
+      </figure>
+    </section>
+  );
+}

package/shared-blocks/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Framework-owned blocks. Themes do NOT implement these — the React logic
+ * lives here, themes only style them via `.core-block-*` scoped selectors
+ * in their theme.css.
+ */
+
+export { CoreDividerBlock } from './divider';
+export { CoreCalloutBlock } from './callout';
+export { CoreQuoteBlock } from './quote';
+export { CoreEmbedBlock } from './embed';
+export { CoreVideoBlock } from './video';
+export { CoreTableBlock } from './table';
+export { CoreButtonBlock } from './button';
+export { CoreImageBlock } from './image';
+export { CoreContentDefaultBlock } from './content-default';
+export { CoreReviewsBlock } from './reviews';
+export { CoreFaqBlock } from './faq';
+export { CoreProductQaBlock } from './product-qa';
+
+export {
+  FRAMEWORK_BLOCK_MANIFEST,
+  FRAMEWORK_OWNED_TYPES,
+  CONTENT_DEFAULT_IS_FRAMEWORK_OWNED,
+} from './manifest';

package/shared-blocks/manifest.ts

@@ -0,0 +1,76 @@
+import type { ThemeManifestVariant } from '../types/theme';
+
+/**
+ * Framework-owned block manifest. These variants are available in EVERY
+ * theme's Section Library drawer — themes don't implement them and can't
+ * override their React logic, only their CSS styling via `.core-block-*`
+ * scoped selectors.
+ *
+ * Keep in sync with FRAMEWORK_OWNED_TYPES in page-renderer.tsx and the
+ * shared-blocks index export.
+ */
+export const FRAMEWORK_BLOCK_MANIFEST: Record<string, ThemeManifestVariant[]> = {
+  divider: [
+    { id: 'default', label: 'Divider', default: true, purpose: 'Visual separator between sections' },
+  ],
+  callout: [
+    { id: 'default', label: 'Callout', default: true, purpose: 'Highlighted info/warn/success/note box for article emphasis' },
+  ],
+  quote: [
+    { id: 'default', label: 'Quote', default: true, purpose: 'Pull-quote with optional attribution' },
+  ],
+  embed: [
+    { id: 'default', label: 'Embed', default: true, purpose: 'Instagram, Spotify, Twitter, or any iframe URL' },
+  ],
+  video: [
+    { id: 'default', label: 'Video', default: true, purpose: 'Embed a YouTube, Vimeo, or self-hosted video' },
+  ],
+  table: [
+    { id: 'default', label: 'Table', default: true, purpose: 'Pricing, specs, or comparison tables' },
+  ],
+  button: [
+    { id: 'default', label: 'Button', default: true, purpose: 'Standalone call-to-action link' },
+  ],
+  image: [
+    { id: 'default', label: 'Image', default: true, purpose: 'A single standalone image with caption' },
+  ],
+  reviews: [
+    { id: 'grid', label: 'Grid', default: true, purpose: 'Verified customer reviews in a responsive grid' },
+    { id: 'carousel', label: 'Carousel', purpose: 'Verified customer reviews in a horizontal scroller' },
+    { id: 'wall', label: 'Wall', purpose: 'Masonry-style wall of verified customer reviews' },
+    { id: 'compact', label: 'Compact', purpose: 'Compact list with rating breakdown header' },
+  ],
+  faq: [
+    { id: 'default', label: 'FAQ', default: true, purpose: 'Accordion of question/answer pairs' },
+  ],
+  product_qa: [
+    { id: 'default', label: 'Product Q&A', default: true, purpose: 'Customer questions and vendor answers for this product' },
+  ],
+};
+
+/**
+ * Block types that are fully framework-owned (React logic + routing).
+ * Themes can style these via `.core-block-*` CSS but do NOT implement the
+ * React components. page-renderer.tsx routes these to core directly.
+ */
+export const FRAMEWORK_OWNED_TYPES = new Set<string>([
+  'divider',
+  'callout',
+  'quote',
+  'embed',
+  'video',
+  'table',
+  'button',
+  'image',
+  'reviews',
+  'faq',
+  'product_qa',
+]);
+
+/**
+ * `content/default` is a special case — the default content variant is
+ * framework-owned (plain markdown rendering), but content variants with
+ * specific IDs (promo, brand-story, testimonials, marquee, features-columns,
+ * before-after) stay theme-owned. page-renderer.tsx handles this split.
+ */
+export const CONTENT_DEFAULT_IS_FRAMEWORK_OWNED = true;

package/shared-blocks/product-qa.tsx

@@ -0,0 +1,203 @@
+'use client';
+
+import { useState } from 'react';
+import type { ProductQaBlockData, ProductQuestionItem } from '../types/block';
+import { Image } from '../components/image';
+import { useProductQuestions } from '../hooks/use-product-questions';
+import { useAuth } from '../hooks/use-auth';
+import { useStorefront } from '../provider';
+import { getQueekClient } from '../sdk/queek-client';
+
+const MAX_QUESTION_LENGTH = 1000;
+
+/**
+ * Framework-owned Product Q&A block. Renders answered customer questions
+ * fetched from `GET /client/store/products/{slug}/questions` and lets
+ * authenticated customers ask new ones via `POST` to the same path. Themes
+ * style via `.core-block-product-qa` and its `__` sub-elements.
+ */
+export function CoreProductQaBlock(props: ProductQaBlockData): JSX.Element {
+  const { questions, isLoading } = useProductQuestions(props);
+  const title = props.title;
+  const hasQuestions = questions.length > 0;
+
+  return (
+    <section className="core-block core-block-product-qa" data-loading={isLoading ? 'true' : undefined}>
+      <header className="core-block-product-qa__header">
+        {title ? <h2 className="core-block-product-qa__title">{title}</h2> : null}
+        <AskQuestionPanel productSlug={props.product_slug} />
+      </header>
+
+      {!hasQuestions && !isLoading && (
+        <p className="core-block-product-qa__empty">No questions yet — be the first to ask.</p>
+      )}
+
+      {hasQuestions && (
+        <div className="core-block-product-qa__list">
+          {questions.map((question) => (
+            <QuestionCard key={question.id} question={question} />
+          ))}
+        </div>
+      )}
+    </section>
+  );
+}
+
+function AskQuestionPanel({ productSlug }: { productSlug: string }): JSX.Element {
+  const { vendor } = useStorefront();
+  const { user, openAuthModal } = useAuth();
+  const [open, setOpen] = useState(false);
+  const [question, setQuestion] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [submitted, setSubmitted] = useState(false);
+
+  const handleOpen = (): void => {
+    if (!user) {
+      openAuthModal('login');
+      return;
+    }
+    setSubmitted(false);
+    setOpen(true);
+  };
+
+  const handleCancel = (): void => {
+    setOpen(false);
+    setError(null);
+    setQuestion('');
+  };
+
+  const handleSubmit = async (): Promise<void> => {
+    const trimmed = question.trim();
+    if (!trimmed) {
+      setError('Please write a question.');
+      return;
+    }
+
+    setSubmitting(true);
+    setError(null);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      await client.post(`/client/store/products/${productSlug}/questions`, { question: trimmed });
+      setOpen(false);
+      setQuestion('');
+      setSubmitted(true);
+    } catch {
+      setError('Could not submit your question. Please try again.');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (submitted) {
+    return (
+      <div className="core-block-product-qa__ask">
+        <p className="core-block-product-qa__thanks">
+          Thanks — we&apos;ll notify you when the vendor answers.
+        </p>
+      </div>
+    );
+  }
+
+  if (!open) {
+    return (
+      <div className="core-block-product-qa__ask">
+        <button type="button" className="core-block-product-qa__ask-btn" onClick={handleOpen}>
+          Ask a question
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="core-block-product-qa__ask core-block-product-qa__ask--open">
+      <textarea
+        className="core-block-product-qa__textarea"
+        rows={3}
+        maxLength={MAX_QUESTION_LENGTH}
+        placeholder="What would you like to know about this product?"
+        value={question}
+        onChange={(e) => setQuestion(e.target.value)}
+        disabled={submitting}
+      />
+      {error ? <p className="core-block-product-qa__error">{error}</p> : null}
+      <div className="core-block-product-qa__ask-actions">
+        <button
+          type="button"
+          className="core-block-product-qa__cancel-btn"
+          onClick={handleCancel}
+          disabled={submitting}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          className="core-block-product-qa__submit-btn"
+          onClick={() => void handleSubmit()}
+          disabled={submitting || question.trim().length === 0}
+        >
+          {submitting ? 'Submitting…' : 'Submit question'}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function QuestionCard({ question }: { question: ProductQuestionItem }): JSX.Element {
+  return (
+    <article className="core-block-product-qa__card">
+      <header className="core-block-product-qa__card-head">
+        <div className="core-block-product-qa__avatar">
+          {question.user.avatar ? (
+            <Image
+              src={question.user.avatar}
+              alt={question.user.name}
+              className="core-block-product-qa__avatar-img"
+            />
+          ) : (
+            <span className="core-block-product-qa__avatar-initials" aria-hidden="true">
+              {initialsFor(question.user.name)}
+            </span>
+          )}
+        </div>
+        <div className="core-block-product-qa__card-meta">
+          <p className="core-block-product-qa__author">{question.user.name}</p>
+          <p className="core-block-product-qa__date">{formatDate(question.created_at)}</p>
+        </div>
+      </header>
+
+      <p className="core-block-product-qa__question">{question.question}</p>
+
+      {question.answer ? (
+        <div className="core-block-product-qa__answer">
+          <p className="core-block-product-qa__answer-label">
+            Answered{question.answered_at ? ` · ${formatDate(question.answered_at)}` : ''}
+          </p>
+          <p className="core-block-product-qa__answer-body">{question.answer}</p>
+        </div>
+      ) : null}
+    </article>
+  );
+}
+
+function initialsFor(name: string): string {
+  return name
+    .split(/\s+/)
+    .map((part) => part.charAt(0))
+    .filter(Boolean)
+    .slice(0, 2)
+    .join('')
+    .toUpperCase();
+}
+
+function formatDate(iso: string): string {
+  try {
+    return new Date(iso).toLocaleDateString(undefined, {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+    });
+  } catch {
+    return '';
+  }
+}

package/shared-blocks/quote.tsx

@@ -0,0 +1,20 @@
+'use client';
+
+import type { QuoteBlockData } from '../types/block';
+
+/**
+ * Framework-owned pull-quote block. Renders a blockquote with an optional
+ * attribution line. Themes style via `.core-block-quote` scoped selectors.
+ */
+export function CoreQuoteBlock({ markdown, text, cite }: QuoteBlockData): JSX.Element {
+  const body = (markdown ?? text ?? '').trim();
+
+  return (
+    <section className="core-block core-block-quote">
+      <blockquote className="core-block-quote__inner">
+        <p className="core-block-quote__text">{body}</p>
+        {cite ? <cite className="core-block-quote__cite">{cite}</cite> : null}
+      </blockquote>
+    </section>
+  );
+}