create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/tests/support/ia-pages.tsx

@@ -0,0 +1,154 @@
+import type { ReactNode } from 'react'
+import { FAMILIES, type Applicability } from '../../scripts/compiler/contracts/index'
+import { SECTION_CATEGORIES, sectionsByCategory } from './sections'
+import { Table, mono, muted, page } from './foundation-pages'
+
+/**
+ * The information-architecture pages: the Overviews (Styles → Components →
+ * Sections → Layouts) plus Styles / Layout and the shared section settings.
+ * Sections and Shared Settings render FROM the live schemas and approved contracts.
+ */
+
+const Flow = () => (
+  <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12, ...mono, fontSize: 13 }} aria-label="Styles, then Components, then Sections, then Layouts">
+    {['01 STYLES', '02 COMPONENTS', '03 SECTIONS', '04 LAYOUTS'].map((s, i) => (
+      <span key={s} style={{ display: 'contents' }}>
+        {i > 0 && <span aria-hidden="true">→</span>}
+        <span style={{ padding: '8px 12px', border: '1px solid var(--color-fg)', borderRadius: 'var(--radius-sm)' }}>{s}</span>
+      </span>
+    ))}
+  </div>
+)
+
+const Rule = ({ children }: { children: ReactNode }) => (
+  <p style={{ margin: 0, padding: '12px 16px', borderInlineStart: '3px solid var(--color-fg)', background: 'var(--color-bg-muted)', fontSize: 14 }}>{children}</p>
+)
+
+const Groups = ({ rows }: { rows: [string, string, string][] }) => <Table head={['group', 'what lives here', 'pages']} rows={rows.map(([g, w, p]) => [<strong>{g}</strong>, w, <span style={muted}>{p}</span>])} />
+
+export function StylesOverview() {
+  return (
+    <div style={page}>
+      <h1 className="nv-h2">Styles</h1>
+      <Flow />
+      <p>Styles are the visual system, not components: tokens, type, spacing, layout, motion, icons and the settings shared across the theme. They import nothing from the rest of Nova; everything else is built from them.</p>
+      <Rule>Styles define the visual system. Change a token or a theme setting here and every component, section and layout follows.</Rule>
+      <Groups
+        rows={[
+          ['Foundations', 'the Nova 01 token families, each shown beside its live computed value', 'Colors · Typography · Spacing · Radius · Borders · Shadows · Motion · Breakpoints · Icons'],
+          ['Layout', 'page gutter, grid and header height per breakpoint', 'Layout'],
+          ['Settings', 'global theme settings and the section settings every section shares', 'Shared Theme Settings'],
+        ]}
+      />
+      <p style={muted}>Source: src/styles/ (tokens.css, base.css, global-settings.css, theme.ts, NovaProvider, Icon, strings).</p>
+    </div>
+  )
+}
+
+export function ComponentsOverview() {
+  return (
+    <div style={page}>
+      <h1 className="nv-h2">Components</h1>
+      <Flow />
+      <p>Components are the reusable building blocks: typed props, never fetch, never declare merchant settings — except the reusable blocks in components/*/blocks/, which carry a persisted block schema because several sections accept them.</p>
+      <Rule>Components must never import Sections. The architecture test (test/architecture.ts) fails the build if one does.</Rule>
+      <Groups
+        rows={[
+          ['Base', 'controls every other part uses', 'Button · IconButton · Link · Badge · Input · Textarea · Select · Checkbox · Radio · Switch · Divider · Tabs · Accordion · Skeleton · Spinner · Chip'],
+          ['Commerce', 'product, price and cart parts', 'ProductCard · CollectionCard · Price · ProductBadge · Rating · VariantPicker · Swatches · QuantitySelector · …'],
+          ['Content', 'media and text', 'Heading · RichText · MediaFrame · Image · Video · Carousel · …'],
+          ['Navigation', 'ways through the store', 'BrandLogo · Menu · Breadcrumb · Pagination · LocaleSelector · …'],
+          ['Forms', 'fields and small complete forms', 'FormField · NewsletterForm · ContactFields · SearchField'],
+          ['Overlays', 'surfaces over the page', 'Modal · Drawer · Popover · Tooltip · CartDrawer · MobileNavDrawer · SearchModal · AccountMenu · QuickView · SizeGuide · MarketSelector · …'],
+          ['States', 'what a part shows while loading, empty, failed or unset', 'Loading · Empty · Error · Unavailable · EditorSetup · MediaPlaceholder · …'],
+        ]}
+      />
+      <p style={muted}>Source: src/components/base · commerce · content · navigation · forms · overlays · states.</p>
+    </div>
+  )
+}
+
+export function SectionsOverview() {
+  const groups = sectionsByCategory()
+  return (
+    <div style={page}>
+      <h1 className="nv-h2">Sections</h1>
+      <Flow />
+      <p>Sections are what a merchant adds, reorders and configures. Every one is listed once in the theme.config.ts — the list the editor's Add section picker reads. Categories are navigation only; the design batch is metadata.</p>
+      <Rule>Sections are built from Components. Components never import Sections; Sections never import Layouts.</Rule>
+      <Table
+        head={['category', 'id', 'label', 'blocks', 'presets', 'status']}
+        rows={SECTION_CATEGORIES.flatMap((c) =>
+          groups[c].map((s, i) => [
+            i === 0 ? <strong>{c}</strong> : '',
+            <code style={mono}>{s.id}</code>,
+            s.label,
+            <span style={muted}>{s.blocks.join(' · ') || '—'}</span>,
+            s.presets.length || '—',
+            <span style={mono}>{s.status}</span>,
+          ]),
+        )}
+      />
+      <p style={muted}>Source: src/sections/&lt;category&gt;/&lt;id&gt;/ — a block only that section accepts lives in its blocks/ folder.</p>
+    </div>
+  )
+}
+
+export function LayoutPage() {
+  return (
+    <div style={page}>
+      <h1 className="nv-h2">Layout</h1>
+      <p style={muted}>Page gutter, grid and header height per breakpoint (phone &lt; 640 · tablet 640 · desktop 1024 · wide 1280), from tokens.css. Containers are on Breakpoints; section spacing is on Spacing.</p>
+      <Table
+        head={['token', '< 640', '640', '1024', '1280']}
+        rows={[
+          ['--page-gutter', '16', '24', '40', '40'],
+          ['--grid-columns', '4', '8', '12', '12'],
+          ['--grid-gap', '12', '16', '16', '16'],
+          ['--grid-products', '2', '3', '3', '4'],
+          ['--header-height', '56', '60', '72', '72'],
+        ].map(([t, ...v]) => [<code style={mono}>{t}</code>, ...v])}
+      />
+    </div>
+  )
+}
+
+const SHARED = FAMILIES['12A'].shared
+/** The Nova 12 section families, each with its own shared-applicability table. */
+const SECTION_FAMILIES = ['12A', '12B', '12C', '12D', '12E', '12F', '12G'] as const
+
+/** How many sections, across the Nova 12 families, apply / override / skip a shared setting. */
+function applicability(prop: string) {
+  const count: Record<Applicability, number> = { APPLIES: 0, 'OVERRIDDEN BY SECTION-SPECIFIC BEHAVIOR': 0, 'NOT APPLICABLE': 0 }
+  for (const f of SECTION_FAMILIES) {
+    const row = FAMILIES[f].sharedApplicability.find((a) => a.prop === prop)
+    if (!row) continue
+    for (const [k, v] of Object.entries(row)) if (k !== 'prop' && !k.endsWith('Note') && v in count) count[v]++
+  }
+  return count
+}
+
+export function SharedSettingsPage() {
+  return (
+    <div style={page}>
+      <h1 className="nv-h2">Shared Settings</h1>
+      <p style={muted}>The Nova 12 shared vocabulary (12A · 00): section-level settings that keep the same ID, options and meaning in every section that uses them. Each section records its own default. Rendered from the approved contract (nova-12A.json · shared) and every family's applicability table; code: src/sections/shared.ts.</p>
+      <Table
+        head={['setting', 'label', 'control', 'options (persisted IDs)', 'group default', 'applies · overridden · n/a']}
+        rows={SHARED.map((r) => {
+          const a = applicability(r.name)
+          return [
+            <code style={mono}>{r.name}</code>,
+            r.label,
+            <code style={mono}>{r.control}</code>,
+            r.options.length ? <span style={mono}>{r.options.map((o, i) => `${o}${r.optionLabels[i] && r.optionLabels[i] !== o ? ` (${r.optionLabels[i]})` : ''}`).join(' · ')}</span> : '—',
+            <code style={mono}>{String(r.def ?? '') || '—'}</code>,
+            <span style={mono}>{a.APPLIES} · {a['OVERRIDDEN BY SECTION-SPECIFIC BEHAVIOR']} · {a['NOT APPLICABLE']}</span>,
+          ]
+        })}
+      />
+      <h2 className="nv-h3">Notes from the contract</h2>
+      <Table head={['setting', 'responsive', 'description']} rows={SHARED.map((r) => [<code style={mono}>{r.name}</code>, <span style={muted}>{r.resp || '—'}</span>, <span style={muted}>{r.desc || '—'}</span>])} />
+    </div>
+  )
+}

package/templates/nova/tests/support/listing-demo.tsx

@@ -0,0 +1,29 @@
+import { useState } from 'react'
+import type { Facet, Product } from '@tanqory/theme-kit'
+import * as fx from '../fixtures/index'
+
+/**
+ * Lab-only host for the listing sections: keeps facet / sort state and
+ * "fetches" by filtering fixtures, the way a storefront host would with the
+ * platform API. Components stay presentational.
+ */
+export function useListingDemo(start: { facets?: Facet[]; products?: Product[] } = {}) {
+  const [facets, setFacets] = useState<Facet[]>(start.facets ?? fx.merchFacets)
+  const [sort, setSort] = useState('featured')
+  const all = start.products ?? fx.merchListing
+  const active = facets.flatMap((f) => (f.values ?? []).filter((v) => v.active).map((v) => v.id))
+  // Fixture rule: "textiles" and "out" match nothing; anything else keeps the list.
+  const products = active.some((id) => id === 'textiles') ? [] : all
+  return {
+    facets,
+    sort,
+    sortOptions: fx.merchSortOptions,
+    products,
+    total: products.length,
+    onToggleFilter: (facetId: string, valueId: string) =>
+      setFacets((fs) => fs.map((f) => (f.id !== facetId ? f : { ...f, values: f.values?.map((v) => (v.id === valueId ? { ...v, active: !v.active } : v)) }))),
+    onPriceFilter: (facetId: string, from?: number, to?: number) => setFacets((fs) => fs.map((f) => (f.id === facetId && f.range ? { ...f, range: { ...f.range, from, to } } : f))),
+    onClearFilters: () => setFacets((fs) => fs.map((f) => ({ ...f, values: f.values?.map((v) => ({ ...v, active: false })), range: f.range ? { ...f.range, from: undefined, to: undefined } : undefined }))),
+    onSortChange: setSort,
+  }
+}

package/templates/nova/tests/support/presets.ts

@@ -0,0 +1,14 @@
+import { resolveSettings, type Schema, type SettingsOf } from '@tanqory/theme-kit'
+import { presetsFor } from '../../scripts/compiler/contracts/index'
+
+/**
+ * A contract preset as story args: ONLY the settings the preset names,
+ * resolved through the schema (legacy / coercion). Spread it over a story's
+ * content so the preset never resets copy or data to schema defaults.
+ */
+export function presetArgs<S extends Schema>(schema: S, name: string): Partial<SettingsOf<S>> {
+  const p = presetsFor(schema.name).find((x) => x.name === name)
+  if (!p) throw new Error(`no preset "${name}" for ${schema.name}`)
+  const all = resolveSettings(schema, p.settings).settings as Record<string, unknown>
+  return Object.fromEntries(Object.keys(p.settings).filter((k) => k in all).map((k) => [k, all[k]])) as Partial<SettingsOf<S>>
+}

package/templates/nova/tests/support/sections.ts

@@ -0,0 +1,36 @@
+import type { Schema, ThemeSection } from '@tanqory/theme-kit'
+import theme from '../../theme.config'
+import { presetsFor } from '../../scripts/compiler/contracts/index'
+
+/** A section as the test pages show it: theme.config's entry plus its contract label/presets. */
+export type SectionEntry = Omit<ThemeSection, 'presets' | 'blocks'> & {
+  label: string
+  /** Accepted block names (schema.blocks); the schemas themselves are `blockSchemas`. */
+  blocks: readonly string[]
+  blockSchemas: readonly Schema[]
+  presets: readonly { name: string }[]
+  status: string
+}
+
+export const SECTIONS: readonly SectionEntry[] = theme.sections.map((s) => ({
+  ...s,
+  label: s.title ?? s.id,
+  blocks: s.schema.blocks ?? [],
+  blockSchemas: s.blocks ?? [],
+  presets: s.presets ?? presetsFor(s.id),
+  status: 'READY',
+}))
+
+export const sectionRegistry: Readonly<Record<string, SectionEntry>> = Object.fromEntries(SECTIONS.map((s) => [s.id, s]))
+export const SECTION_SCHEMAS: readonly Schema[] = SECTIONS.map((s) => s.schema)
+/** Picker groups, in the order theme.config first uses them. */
+export const SECTION_CATEGORIES: readonly string[] = [...new Set(SECTIONS.map((s) => s.category))]
+
+export function sectionsByCategory(): Record<string, SectionEntry[]> {
+  const out: Record<string, SectionEntry[]> = Object.fromEntries(SECTION_CATEGORIES.map((c) => [c, []]))
+  for (const s of SECTIONS) out[s.category].push(s)
+  return out
+}
+
+/** Every block schema the theme's sections declare (a section owns its blocks; there is no separate list). */
+export const BLOCK_SCHEMAS: readonly Schema[] = [...new Set(theme.sections.flatMap((s) => s.blocks ?? []))]

package/templates/nova/tests/support/story-content.ts

@@ -0,0 +1,321 @@
+import { placeholderImage } from '../../src/components/states/media/MediaPlaceholder'
+import type { Cart, CartLine, Collection, CustomerAccount, NovaImage, NovaLink, NovaMenu, NovaVideo, PaymentMethod, Policy, Product, ProductVariant, Review, ReviewsData, SearchResults, StoreLocation } from '@tanqory/theme-kit'
+import { resolveSettings } from '@tanqory/theme-kit'
+import { columnSchema, type ColumnInstance } from '../../src/components/content/blocks/Column'
+import { stepSchema, type StepInstance } from '../../src/sections/Timeline/blocks/Step'
+import type { FaqItemSettings } from '../../src/sections/Faq/blocks/FaqItem'
+import type { BadgeBlockSettings } from '../../src/components/commerce/blocks/Badge'
+import { testimonialSchema, type TestimonialInstance } from '../../src/sections/Testimonials/blocks/Testimonial'
+import { logoSchema, type LogoInstance } from '../../src/sections/LogoList/blocks/Logo'
+import { ugcImageSchema, type UgcPhotoInstance } from '../../src/sections/UgcGallery/blocks/UgcImage'
+import { hotspotSchema, type HotspotInstance } from '../../src/sections/ShopTheLook/blocks/Hotspot'
+import { compareItemSchema, type CompareItemInstance } from '../../src/sections/ComparisonTable/blocks/CompareItem'
+import { merchBoard, merchCandle, merchCarafe, merchDuvet, merchDuvetBlend, merchDuvetPercale, merchMug, merchNapkins, merchOil, merchPlatter, merchPourOver, merchSimple, merchThrow } from '../fixtures/merch'
+import type { ContactDetailSettings } from '../../src/sections/ContactForm/blocks/ContactDetail'
+
+/** The canvas cart's candle is in stock (the listing fixture sells it out). */
+const merchCandleInStock: Product = { ...merchCandle, available: true, variants: merchCandle.variants.map((v) => ({ ...v, available: true, quantityAvailable: 24 })) }
+
+/** 12D · the approved canvas copy (Halden story page). */
+const col = (s: Record<string, unknown>, family?: Parameters<typeof placeholderImage>[0]): ColumnInstance => ({
+  settings: resolveSettings(columnSchema, s).settings,
+  image: family ? placeholderImage(family, 900, 600, String(s.heading)) : null,
+})
+
+export const storyColumns: ColumnInstance[] = [
+  col({ heading: 'Small batches', body: 'Every glaze run is forty pieces or fewer, so slight variation is part of the design.', linkLabel: 'How we make it', link: '/pages/process' }, 'editorial'),
+  col({ heading: 'Honest materials', body: 'European flax, FSC walnut, lead-free stoneware. Origins are listed on every product.', linkLabel: 'Our materials', link: '/pages/materials' }, 'product'),
+  col({ heading: 'Repair, not replace', body: 'Chipped a mug in year one? We re-glaze or replace it at no cost.', linkLabel: 'Our guarantee', link: '/pages/guarantee' }, 'store'),
+]
+export const storyIconColumns: ColumnInstance[] = [
+  col({ icon: 'truck', heading: 'Free shipping', body: 'Over $120' }),
+  col({ icon: 'return', heading: '30-day returns', body: 'Collected from your door' }),
+  col({ icon: 'shield', heading: 'Repair guarantee', body: 'Year one, free' }),
+  col({ icon: 'leaf', heading: 'Carbon-neutral', body: 'Every delivery' }),
+]
+export const storyBento: ColumnInstance[] = [
+  { ...col({ heading: 'European flax, grown without irrigation.', body: 'Materials' }), image: placeholderImage('hero', 1200, 1000, 'Flax field') },
+  col({ icon: 'leaf', heading: 'Rain-fed flax', body: 'No irrigation, no pesticides.' }),
+  col({ icon: 'clock', heading: 'Stonewashed 3 hours', body: 'Soft from the first night.' }),
+  col({ icon: 'shield', heading: 'Oeko-Tex certified', body: 'Tested for 350 substances.' }),
+  col({ icon: 'return', heading: 'Gets better with washing', body: 'Stronger when wet.' }),
+]
+export const storyFeatures = 'truck: Free shipping | Over $120\nreturn: 30-day returns | Collected from your door\nshield: Repair guarantee | Year one, free\nleaf: Carbon-neutral | Every delivery'
+
+export const storyFaq: FaqItemSettings[] = [
+  { question: 'How long does delivery take?', answer: '<p>Orders ship from Chiang Mai within two business days and arrive in 2–4 days across Thailand. International orders leave every Tuesday and Friday.</p>' },
+  { question: 'Can I put stoneware in the dishwasher?', answer: '<p>Yes — everything except pieces with a gold rim. Hand-washing keeps the glaze glossy for longer.</p>' },
+  { question: 'What if something arrives broken?', answer: '<p>Send us a photo within 7 days and we send a replacement, no return needed.</p>' },
+  { question: 'Do you offer gift wrapping?', answer: '<p>Every order can be wrapped in recycled kraft paper with a handwritten card.</p>' },
+  { question: 'How do returns work?', answer: '<p>30 days, collected from your door. Refunds land within 5 business days.</p>' },
+]
+
+const step = (s: Record<string, unknown>): StepInstance => ({ settings: resolveSettings(stepSchema, s).settings, image: placeholderImage('editorial', 800, 600, String(s.heading)) })
+export const storySteps: StepInstance[] = [
+  step({ label: 'Day 1', heading: 'Throw', body: 'Local clay is thrown on the wheel and left to firm overnight.' }),
+  step({ label: 'Day 3', heading: 'Trim & dry', body: 'Each piece is trimmed by hand, then dries for a week.' }),
+  step({ label: 'Day 10', heading: 'Glaze', body: 'Dipped in Sea Salt glaze; the iron speckles appear in the kiln.' }),
+  step({ label: 'Day 12', heading: 'Fire', body: 'Fired to 1,240°C, then checked one by one before packing.' }),
+]
+
+const u = (h: string) => `/collections/${h}`
+export const storyBrowseMenu: NovaMenu = {
+  handle: 'browse',
+  title: 'Browse the shop',
+  items: [
+    { title: 'Kitchen & Table', url: u('kitchen-table') },
+    { title: 'Bedroom & Bath', url: u('bedroom-bath') },
+    { title: 'Pantry', url: u('pantry') },
+    { title: 'Candles & Scent', url: u('candles') },
+    { title: 'Gift Sets', url: u('gift-sets') },
+    { title: 'New in', url: u('new') },
+    { title: 'Sale', url: u('sale') },
+    { title: 'Gift Cards', url: '/products/gift-card' },
+    { title: 'Studio Seconds', url: u('seconds') },
+    { title: 'Workshops', url: '/pages/workshops' },
+  ],
+}
+
+export const storyGallery = [
+  { type: 'image' as const, settings: { caption: 'The kiln at dawn' }, image: placeholderImage('hero', 1200, 1200, 'The kiln at dawn') },
+  { type: 'image' as const, settings: {}, image: placeholderImage('product', 800, 800, 'Glaze buckets') },
+  { type: 'image' as const, settings: { caption: 'Sea Salt test tiles' }, image: placeholderImage('collection', 800, 800, 'Sea Salt test tiles') },
+  { type: 'image' as const, settings: {}, image: placeholderImage('editorial', 800, 800, 'Drying racks') },
+  { type: 'image' as const, settings: {}, image: placeholderImage('store', 800, 800, 'The studio shop') },
+]
+export const storyImage = placeholderImage('editorial', 1000, 1250, 'A potter glazing a bowl')
+
+// ── 12E · editorial (the canvas copy) ─────────────────────────────────────
+import type { Article, Blog } from '@tanqory/theme-kit'
+import { personSchema, type PersonInstance } from '../../src/sections/TeamFounders/blocks/Person'
+import type { ComparisonInstance } from '../../src/sections/BeforeAfter/blocks/Comparison'
+import { comparisonSchema } from '../../src/sections/BeforeAfter/blocks/Comparison'
+
+export const storyArticleHtml = `<p>Wash at 40°C with a mild detergent, and <a href="/pages/care">skip the softener</a> — it coats the fibres and stops them breathing. Line-dry when you can; if you tumble, take it out while still slightly damp.</p>
+<h2>Four steps</h2>
+<ol><li>Turn covers inside out and close the buttons.</li><li>Wash cool, on a gentle cycle.</li><li>Line dry, or tumble on low until just damp.</li><li>Shake out and smooth by hand — no iron needed.</li></ol>
+<blockquote>"Linen is the only fabric that gets better the more you use it."</blockquote>
+<h2>Care symbols</h2>
+<table><thead><tr><th>Item</th><th>Wash</th><th>Dry</th></tr></thead><tbody><tr><td>Duvet cover</td><td>40°C gentle</td><td>Line / low</td></tr><tr><td>Napkins</td><td>60°C</td><td>Tumble low</td></tr></tbody></table>
+<h2>Storing</h2>
+<ul><li>Store dry, folded loosely.</li><li>Small pulls: trim, never pull.</li></ul>
+<h2>When to replace</h2>
+<p>Linen doesn't need ironing. Shake it out, smooth it by hand, and let the creases settle overnight.</p>
+<hr><p>Last reviewed by the studio team. <strong>Questions?</strong> Email hello@halden.co.</p>`
+
+const art = (id: string, title: string, tag: string, date: string, family: Parameters<typeof placeholderImage>[0] | null, excerpt?: string): Article => ({
+  id, handle: id, title, excerpt, url: `/blogs/journal/${id}`, image: family ? placeholderImage(family, 1200, 800, title) : null, author: 'Mali Srisuk', publishedAt: date, tags: [tag], blogHandle: 'journal',
+})
+export const storyArticle: Article & { contentHtml: string } = {
+  ...art('how-to-wash-linen', 'How to wash linen so it lasts twenty years', 'care', '2026-09-12', 'product', "Heat and softener are linen's only real enemies. A four-step routine for sheets, napkins and everything between."),
+  tags: ['care', 'linen'],
+  contentHtml: storyArticleHtml,
+}
+export const storyJournal: Blog = {
+  id: 'journal', handle: 'journal', title: 'Journal', url: '/blogs/journal',
+  articles: [
+    storyArticle,
+    art('inside-the-kiln', 'Inside the kiln: firing the Sea Salt glaze', 'studio', '2026-08-28', 'editorial', 'Twelve hours, 1,240°C and a very early morning.'),
+    art('slow-sunday-breakfast', 'A slow Sunday breakfast for four', 'recipes', '2026-08-09', 'collection', 'Eggs, sourdough and the Pour-Over set, start to finish.'),
+    art('oiling-walnut', 'Oiling a walnut board: a five-minute ritual', 'care', '2026-07-03', null, 'Once a month keeps the grain from drying out.'),
+    art('meet-niran', 'Meet Niran, our glaze chemist', 'makers', '2026-06-18', 'store', 'Four hundred test tiles for one colour.'),
+    art('table-for-summer', 'Setting a table for summer', 'studio', '2026-06-02', 'hero', 'Three layers, no rules.'),
+    art('flax-harvest', 'The flax harvest in Normandy', 'makers', '2026-05-15', 'editorial', 'Where our linen starts.'),
+  ],
+}
+
+const person = (s: Record<string, unknown>, family: Parameters<typeof placeholderImage>[0] | null): PersonInstance => ({ settings: resolveSettings(personSchema, s).settings, image: family ? placeholderImage(family, 800, 1000, String(s.name)) : null })
+export const storyPeople: PersonInstance[] = [
+  person({ name: 'Mali Srisuk', role: 'Founder & potter', quote: "I started Halden because I couldn't find a mug I wanted to keep for twenty years.", bio: 'Mali trained in Mashiko before opening a two-kiln studio outside Chiang Mai in 2016. She still throws every new shape herself.', linkLabel: "Read Mali's story", link: '/pages/mali' }, 'editorial'),
+  person({ name: 'Niran Chaiya', role: 'Glaze chemist', bio: 'Four hundred test tiles for one colour.' }, 'store'),
+  person({ name: 'Ploy Anan', role: 'Linen & textiles' }, null),
+  person({ name: 'Tom Becker', role: 'Woodwork' }, 'product'),
+]
+const cmp = (s: Record<string, unknown>): ComparisonInstance => ({ settings: resolveSettings(comparisonSchema, s).settings, before: placeholderImage('hero', 1200, 800, 'The chipped rim, before'), after: placeholderImage('product', 1200, 800, 'The rim re-glazed in Sea Salt') })
+export const storyComparisons: ComparisonInstance[] = [
+  cmp({ caption: 'Chipped in the dishwasher; re-glazed in Sea Salt.', alt: 'A mug with a chipped rim, then the same mug re-glazed and smooth' }),
+  cmp({ caption: 'A cracked bowl, kintsugi-style repair.', alt: 'A cracked bowl, then repaired with a visible seam' }),
+  cmp({ caption: 'A stained board, oiled and sanded.', alt: 'A stained walnut board, then oiled and even' }),
+]
+
+/* ── 12F · Trust & Advanced Commerce — the approved canvas copy. Quotes, logos and
+      badges are the merchant's; reviews stand in for a future reviews source. */
+const tm = (s: Record<string, unknown>, avatar: boolean, video?: NovaVideo): TestimonialInstance => ({
+  settings: resolveSettings(testimonialSchema, s).settings,
+  avatar: avatar ? placeholderImage('avatar', 400, 400, String(s.name)) : null,
+  video: video ?? null,
+})
+export const storyTestimonials: TestimonialInstance[] = [
+  tm({ quote: '"The linen is softer every wash, and the Oat colour is perfect in morning light."', name: 'Ploy R.', role: 'Bangkok', rating: 5 }, true),
+  tm({ quote: '"Our mugs chipped after two years and Halden re-glazed them for free. Who does that?"', name: 'Tom W.', role: 'Melbourne', rating: 5 }, false),
+  tm({ quote: '"Slow shipping to Europe, but worth every day of waiting."', name: 'Anna L.', role: 'Stockholm', rating: 4 }, true),
+  tm({ quote: '"The walnut board is the first thing guests ask about."', name: 'Kenji M.', role: 'Osaka', rating: 5 }, false),
+  tm({ quote: '"Ordered napkins for a wedding table — every one arrived pressed and perfect."', name: 'Sara B.', role: 'Lisbon', rating: 5 }, true),
+  tm({ quote: '"Customer service answered a glaze question in an hour, on a Sunday."', name: 'Niran P.', role: 'Chiang Mai', rating: 0 }, false),
+]
+export const storySpotlight: TestimonialInstance = tm(
+  { quote: '"Three years of daily use and the mugs still look new. The repair service is the real thing."', name: 'Anna Lindqvist', role: 'Stockholm', rating: 5 },
+  true,
+  { src: 'media/studio-loop.webm', poster: placeholderImage('editorial', 600, 800, 'Anna Lindqvist at her kitchen table'), captions: 'media/testimonial-anna.en.vtt', captionsLang: 'en' },
+)
+
+const logo = (slug: string, name: string, w: number): LogoInstance => ({ settings: resolveSettings(logoSchema, { alt: name, href: '' }).settings, image: { src: `media/logos/${slug}.svg`, alt: name, width: w, height: 32 } })
+/** Fictional press names — a lab must not ship real publications' marks. */
+export const storyLogos: LogoInstance[] = [
+  logo('northlight', 'Northlight', 273),
+  logo('field-and-form', 'Field & Form', 185),
+  logo('slow-house', 'Slow House', 275),
+  logo('atelier', 'Atelier', 106),
+  logo('the-table', 'The Table', 206),
+  logo('harbour', 'Harbour', 205),
+]
+
+export const storyBadges: BadgeBlockSettings[] = [
+  { icon: 'truck', label: 'Free shipping over $120', detail: 'Carbon-neutral, 2–4 days', link: '/policies/shipping' },
+  { icon: 'return', label: '30-day returns', detail: 'Collected from your door', link: '/policies/returns' },
+  { icon: 'shield', label: 'Repair guarantee', detail: 'Re-glazed free in year one', link: '' },
+  { icon: 'card', label: 'Secure checkout', detail: 'Card or PromptPay', link: '' },
+]
+
+const rv = (id: string, rating: Review['rating'], title: string, body: string, author: string, createdAt: string, variant: string, photos = 0): Review => ({
+  id, rating, title, body, author, createdAt, variant, verified: true,
+  photos: Array.from({ length: photos }, (_, i) => placeholderImage('product', 800, 800, `${author}'s photo ${i + 1}`)),
+})
+export const storyReviews: ReviewsData = {
+  average: 4.8,
+  count: 212,
+  distribution: [174, 25, 8, 3, 2],
+  reviews: [
+    rv('r1', 5, 'Softer every single wash', 'Bought the Queen in Oat. It arrived a little stiff, and after three washes it drapes beautifully. Sleeps cool in Bangkok heat.', 'Ploy R.', '2026-09-02', 'Queen · Oat', 2),
+    rv('r2', 5, 'Worth the price', 'The stitching is excellent and the buttons are hidden well. Colour exactly as pictured.', 'James K.', '2026-08-21', 'King · Chalk'),
+    rv('r3', 4, 'Lovely, runs slightly large', 'Beautiful linen. The Queen is a little generous on our mattress — fine for us, but check the size guide.', 'Mai T.', '2026-08-03', 'Queen · Clay'),
+    rv('r4', 5, 'Our third one', 'We keep buying these for the guest rooms. Still the nicest bedding we own.', 'Hannah S.', '2026-07-19', 'Full · Chalk', 1),
+    rv('r5', 3, 'Beautiful, but creases', 'Exactly as described — it is linen, so it creases. I knew that, but it is more than I expected.', 'Daniel O.', '2026-07-02', 'Queen · Sage'),
+    rv('r6', 5, 'Perfect in the heat', 'Cool at night even without air-conditioning.', 'Wan C.', '2026-06-14', 'King · Charcoal'),
+    rv('r7', 2, 'Colour lighter than photos', 'The Clay is paler than on my screen. Quality is good.', 'Petra V.', '2026-05-30', 'Queen · Clay'),
+  ],
+}
+
+const ugc = (handle: string, family: Parameters<typeof placeholderImage>[0], product?: Product): UgcPhotoInstance => ({
+  settings: resolveSettings(ugcImageSchema, { caption: handle, alt: `A customer's home, shared by ${handle}`, link: product?.url ?? '' }).settings,
+  image: placeholderImage(family, 800, 800, `Shared by ${handle}`),
+  product: product ?? null,
+})
+export const storyUgc: UgcPhotoInstance[] = [
+  ugc('@ploy.home', 'ugc', merchDuvet),
+  ugc('@slowmornings', 'hero', merchMug),
+  ugc('@anna.l', 'editorial'),
+  ugc('@tomw', 'collection', merchBoard),
+  ugc('@mai.t', 'store', merchCarafe),
+  ugc('@kenji.cooks', 'product', merchPourOver),
+  ugc('@lisbonlinen', 'ugc', merchNapkins),
+  ugc('@wan.c', 'generic'),
+  ugc('@hannah.s', 'hero', merchThrow),
+  ugc('@petra.v', 'editorial', merchCandle),
+]
+
+const spot = (product: Product | null, x: number, y: number): HotspotInstance => ({ settings: resolveSettings(hotspotSchema, { x, y }).settings, product })
+export const storyLookImage: NovaImage = placeholderImage('hero', 1000, 1250, 'A slow Sunday corner: a mug, a linen throw and a walnut board by the window')
+export const storyHotspots: HotspotInstance[] = [spot(merchMug, 30, 62), spot(merchThrow, 55, 40), spot(merchBoard, 72, 78)]
+
+const cmpItem = (product: Product | null, title: string, values: string): CompareItemInstance => ({ settings: resolveSettings(compareItemSchema, { title, values }).settings, product, image: null })
+export const storyCompareFeatures = ['Fabric', 'Feel', 'Best for', 'Oeko-Tex', 'Needs ironing', 'Warranty'].join('\n')
+export const storyCompareItems: CompareItemInstance[] = [
+  cmpItem(merchDuvet, 'Washed Linen', ['100% European flax', 'Soft, relaxed', 'All seasons', 'yes', 'no', '5 years'].join('\n')),
+  cmpItem(merchDuvetBlend, 'Linen-Cotton', ['55% linen, 45% cotton', 'Smooth, light crease', 'Warm climates', 'yes', 'no', '3 years'].join('\n')),
+  cmpItem(merchDuvetPercale, 'Organic Percale', ['100% organic cotton', 'Crisp, cool', 'Hot sleepers', 'yes', 'Optional', '3 years'].join('\n')),
+]
+
+/* ── 12G · Utility & Customer Experience — the approved canvas copy. */
+const USD = (amount: number) => ({ amount, currencyCode: 'USD' })
+const lineOf = (id: string, product: Product, variantTitle: string | null, quantity: number, over: Partial<ProductVariant> = {}): CartLine => {
+  const v = { ...(variantTitle ? product.variants.find((x) => x.title === variantTitle)! : product.variants[0]), image: product.featuredImage, ...over }
+  return {
+    id, quantity, variant: v,
+    product: { title: product.title, handle: product.handle, url: product.url, vendor: product.vendor },
+    cost: { total: USD(v.price.amount * quantity), compareAtTotal: v.compareAtPrice ? USD(v.compareAtPrice.amount * quantity) : null },
+  }
+}
+export const storeCartLines: CartLine[] = [
+  lineOf('l1', { ...merchDuvet, title: 'Washed Linen Duvet Cover — Queen' }, 'Queen / Oat', 1, { quantityAvailable: 12 }),
+  lineOf('l2', merchMug, 'Oat', 2, { quantityAvailable: 3 }),
+  lineOf('l3', merchCandleInStock, null, 1),
+]
+export const storeCart: Cart = { id: 'gid://cart/12g', lines: storeCartLines, note: '', itemCount: 4, subtotal: USD(281), total: USD(281) }
+export const storeCartBadges = [
+  { label: '30-day returns, collected from your door', link: '' },
+  { label: 'Repair guarantee in year one', link: '/pages/guarantee' },
+]
+export const storePayments: PaymentMethod[] = ['visa', 'mastercard', 'amex', 'promptpay']
+export const storeNewSeason: Collection = { id: 'new', handle: 'new-this-season', title: 'New this season', url: '/collections/new-this-season', productsCount: 4, products: [merchMug, merchThrow, merchOil, merchCarafe] }
+
+export const storeSearch: SearchResults = {
+  query: 'linen',
+  products: [merchDuvet, merchNapkins, merchThrow, merchSimple, merchDuvetBlend, merchDuvetPercale, merchMug, merchBoard],
+  articles: storyJournal.articles.slice(0, 3),
+  pages: [{ title: 'Linen care guide', url: '/pages/care', excerpt: 'Wash at 40°C, skip the softener, line-dry when you can.' }],
+  total: 12,
+}
+export const storeSuggestions: NovaLink[] = [
+  { title: 'Bedroom & Bath', url: '/collections/bedroom-bath' },
+  { title: 'Kitchen & Table', url: '/collections/kitchen-table' },
+  { title: 'New in', url: '/collections/new' },
+  { title: 'Gift Sets', url: '/collections/gift-sets' },
+]
+
+export const storeCustomer: CustomerAccount = {
+  firstName: 'Mali', lastName: 'Srisuk', email: 'mali@halden.co',
+  orders: [
+    { id: 'o1', number: '#HC-10482', processedAt: '2026-09-14', status: 'fulfilled', total: USD(245), itemCount: 3, url: '/account/orders/10482' },
+    { id: 'o2', number: '#HC-10417', processedAt: '2026-08-02', status: 'fulfilled', total: USD(74), itemCount: 1, url: '/account/orders/10417' },
+    { id: 'o3', number: '#HC-10309', processedAt: '2026-06-21', status: 'fulfilled', total: USD(36), itemCount: 1, url: '/account/orders/10309' },
+  ],
+  addresses: [],
+}
+export const storeLoginImage: NovaImage = placeholderImage('editorial', 900, 1100, 'Folded linen on a studio shelf')
+
+export const storeRefundPolicy: Policy = {
+  handle: 'refund-policy', title: 'Refund policy', url: '/policies/refund-policy',
+  bodyHtml: `<h2>Returns within 30 days</h2><p>Unused items in their original packaging can be returned within 30 days of delivery. We collect from your door at no cost within Thailand.</p>
+<h2>Refunds</h2><p>Refunds go back to the original payment method within 5 business days of the return reaching our studio.</p>
+<h2>Exchanges</h2><p>Want a different size or colour? Start a return and place a new order — it's the fastest way to get the one you want.</p>
+<h2>Damaged items</h2><p>If something arrives chipped or torn, send us a photo within 7 days and we'll replace it or re-glaze it.</p>
+<h2>Contact</h2><p>Questions about a return? Email hello@halden.co and we'll reply within one business day.</p>`,
+}
+
+const store = (id: string, name: string, address: string[], phone?: string, hours?: string, family?: Parameters<typeof placeholderImage>[0]): StoreLocation => ({ id, name, address, phone, hours, image: family ? placeholderImage(family, 800, 450, `${name} storefront`) : null })
+export const storeLocations: StoreLocation[] = [
+  store('s1', 'Nimman Studio', ['88 Nimmanhaemin Soi 9', 'Chiang Mai 50200'], '+66 53 123 456', 'Mon–Sun, 10 am–7 pm', 'store'),
+  store('s2', 'Siam Discovery', ['194 Phaya Thai Rd, 4F', 'Bangkok 10330'], '+66 2 123 4567', undefined, 'editorial'),
+  store('s3', 'Thong Lo', ['335 Thong Lo 17', 'Bangkok 10110'], '+66 2 765 4321', 'Mon–Sun, 10 am–9 pm', 'collection'),
+  store('s4', 'Old Town', ['12 Thanon Ratchadamnoen', 'Chiang Mai 50200'], undefined, undefined, 'hero'),
+]
+
+export const storeContactDetails: ContactDetailSettings[] = [
+  { label: 'Email', value: 'hello@halden.co', link: 'mailto:hello@halden.co' },
+  { label: 'Phone', value: '+66 53 123 456', link: 'tel:+6653123456' },
+  { label: 'Studio', value: 'Mon–Fri, 9 am–5 pm', link: '' },
+]
+
+/* ── 13 · Overlays — the canvas copy. */
+const guideTable = (unit: 'cm' | 'in') => {
+  const rows = unit === 'cm'
+    ? [['Twin', '172 cm', '218 cm', '90–100 cm'], ['Full', '200 cm', '218 cm', '135–140 cm'], ['Queen', '228 cm', '233 cm', '150–160 cm'], ['King', '264 cm', '233 cm', '180–200 cm']]
+    : [['Twin', '68 in', '86 in', '35–39 in'], ['Full', '79 in', '86 in', '53–55 in'], ['Queen', '90 in', '92 in', '59–63 in'], ['King', '104 in', '92 in', '71–79 in']]
+  return `<table><thead><tr><th>Size</th><th>Width</th><th>Length</th><th>Fits mattress</th></tr></thead><tbody>${rows.map((r) => `<tr><th>${r[0]}</th>${r.slice(1).map((c) => `<td>${c}</td>`).join('')}</tr>`).join('')}</tbody></table>
+<h2>How to measure</h2><ol><li>Measure your duvet insert, not the bed.</li><li>Width across the top edge, length down the side.</li><li>Choose the cover within 5 cm of the insert.</li></ol>`
+}
+export const storeSizeGuideCm = guideTable('cm')
+export const storeSizeGuideIn = guideTable('in')
+export const storeDrawerCart: Cart = {
+  ...storeCart,
+  lines: [
+    lineOf('d1', { ...merchDuvet, title: 'Washed Linen Duvet Cover — Queen, Oat' }, 'Queen / Oat', 1, { quantityAvailable: 12 }),
+    lineOf('d2', { ...merchPlatter, title: 'Extra-Large Hand-Thrown Speckled Stoneware Serving Bowl with Walnut Lid, Set of Two' }, null, 1, { price: USD(1249), compareAtPrice: null, quantityAvailable: 6 }),
+    lineOf('d3', merchCandle, null, 1, { available: false }),
+  ],
+  itemCount: 3,
+  discounts: [{ code: 'AUTUMN10', amount: USD(143.8) }],
+  subtotal: USD(1438),
+  total: USD(1294.2),
+}

package/templates/nova/tests/support/story-helpers.tsx

@@ -0,0 +1,37 @@
+import type { CSSProperties, ReactNode } from 'react'
+
+/** A labelled specimen row for component stories. */
+export function Row({ label, children, style }: { label?: string; children: ReactNode; style?: CSSProperties }): JSX.Element {
+  return (
+    <div style={{ display: 'grid', gap: 8, marginBottom: 24 }}>
+      {label && <p style={{ fontFamily: 'var(--font-mono)', fontSize: 11, color: 'var(--color-fg-muted)', margin: 0 }}>{label}</p>}
+      <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 12, ...style }}>{children}</div>
+    </div>
+  )
+}
+
+export function Pad({ children, surface }: { children: ReactNode; surface?: 'muted' | 'inverse' }): JSX.Element {
+  const bg = surface === 'inverse' ? 'var(--color-bg-inverse)' : surface === 'muted' ? 'var(--color-bg-muted)' : undefined
+  return (
+    <div style={{ padding: 32, background: bg, color: surface === 'inverse' ? 'var(--color-fg-inverse)' : undefined }} data-nv-surface={surface}>
+      {children}
+    </div>
+  )
+}
+
+/**
+ * A section's Overview: the named stories stacked, each under a mono caption.
+ * `render` is how one set of args renders (the section component).
+ */
+export function Stack<A>({ base, items, render }: { base: A; items: { name?: string; args?: Partial<A> }[]; render: (args: A) => JSX.Element | null }): JSX.Element {
+  return (
+    <div style={{ display: 'grid', gap: 48, paddingBlock: 24 }}>
+      {items.map((s) => (
+        <section key={s.name} aria-label={s.name}>
+          <p style={{ font: '500 11px/1 var(--font-mono)', color: 'var(--color-fg-muted)', padding: '0 var(--page-gutter) 12px', margin: 0 }}>{s.name}</p>
+          {render({ ...base, ...s.args } as A)}
+        </section>
+      ))}
+    </div>
+  )
+}

package/templates/nova/tests/support/with-nova.tsx

@@ -0,0 +1,26 @@
+import type { Decorator } from './case'
+import { NovaProvider } from '../../src/styles/NovaProvider'
+
+/**
+ * Every story renders inside <NovaProvider> — tokens, base styles, lang/dir,
+ * storefront vs editor mode, global theme settings. A story's own
+ * `parameters.nova` (or the toolbar globals) pins them.
+ */
+export const withNova: Decorator = (Story, ctx) => {
+  const pinned = (ctx.parameters.nova ?? {}) as { locale?: string; mode?: 'storefront' | 'editor'; scheme?: 'light' | 'dark'; motion?: 'standard' | 'reduced'; theme?: object }
+  const locale = pinned.locale ?? (ctx.globals.locale as string) ?? 'en'
+  const mode = pinned.mode ?? (ctx.globals.mode as 'storefront' | 'editor') ?? 'storefront'
+  const scheme = pinned.scheme ?? (ctx.globals.scheme as 'light' | 'dark') ?? 'light'
+  const motion = pinned.motion ?? (ctx.globals.motion as 'standard' | 'reduced') ?? 'standard'
+  const dir = /^ar/.test(locale) ? 'rtl' : 'ltr'
+  if (typeof document !== 'undefined') {
+    document.documentElement.lang = locale
+    document.documentElement.dir = dir
+    document.body.style.background = scheme === 'dark' ? '#0e0e0e' : '#ffffff'
+  }
+  return (
+    <NovaProvider locale={locale} dir={dir} mode={mode} theme={{ ...(pinned.theme ?? {}), colorScheme: scheme, motion }} className="nv-lab-root">
+      <Story />
+    </NovaProvider>
+  )
+}