create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/tests/cases/components/states/Error.cases.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '../../../support/case'
+import { StateBlock } from '../../../../src/components/states/StateBlock'
+import { Alert } from '../../../../src/components/states/Alert'
+import { OfflineNotice } from '../../../../src/components/states/OfflineNotice'
+import { Button } from '../../../../src/components/base/Button'
+import { Pad } from '../../../support/story-helpers'
+
+const meta = {
+  title: 'Nova/02 Components/States/Error',
+  component: StateBlock,
+  tags: ['autodocs'],
+  args: { variant: 'error', title: "Couldn't load", description: 'Check your connection.' },
+  decorators: [(S, c) => (c.parameters.wide ? <Pad><S /></Pad> : <Pad><div style={{ maxWidth: 320 }}><S /></div></Pad>)],
+} satisfies Meta<typeof StateBlock>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}
+export const WithAction: Story = { name: 'Variants · with retry', args: { action: <Button size="sm">Try again</Button> } }
+
+export const PageLevel: Story = {
+  name: 'Nova 14 · page-level (500) · Try again + Go to home',
+  args: { variant: 'page-error', title: 'Something went wrong on our side', description: 'Please try again in a moment.', action: <Button>Try again</Button>, secondaryAction: <Button variant="secondary" href="/">Go to home</Button> },
+  parameters: { wide: true },
+}
+export const Families: Story = {
+  name: 'Nova 14 · inline · form · commerce · network · offline',
+  parameters: { wide: true },
+  render: () => (
+    <div style={{ display: 'grid', gap: 12, maxWidth: 560 }}>
+      <Alert tone="error" title="We couldn't load these products" action={{ label: 'Try again', onClick: () => {} }}>Check your connection.</Alert>
+      <Alert tone="error" title="2 fields need attention">Email and postcode.</Alert>
+      <Alert tone="error" title="Couldn't add to cart" action={{ label: 'Add 2 instead', onClick: () => {} }}>Only 2 are available.</Alert>
+      <Alert tone="warning" title="You're offline">We'll retry when you're back.</Alert>
+      <div style={{ position: 'relative', minHeight: 64, transform: 'translateZ(0)' }}><OfflineNotice onRetry={() => {}} /></div>
+    </div>
+  ),
+}

package/templates/nova/tests/cases/components/states/Loading.cases.tsx

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '../../../support/case'
+import { StateBlock } from '../../../../src/components/states/StateBlock'
+import { Pad } from '../../../support/story-helpers'
+
+const meta = {
+  title: 'Nova/02 Components/States/Loading',
+  component: StateBlock,
+  tags: ['autodocs'],
+  args: { variant: 'loading', title: "Loading products", description: 'Short waits only' },
+  decorators: [(S) => <Pad><div style={{ maxWidth: 320 }}><S /></div></Pad>],
+} satisfies Meta<typeof StateBlock>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}

package/templates/nova/tests/cases/components/states/MediaState.cases.tsx

@@ -0,0 +1,29 @@
+import type { Meta, StoryObj } from '../../../support/case'
+import { fn } from '../../../support/case'
+import { MediaState } from '../../../../src/components/states/MediaState'
+
+const reasons = ['missing', 'failed', 'unsupported', 'unconfigured', 'video-unavailable'] as const
+const Grid = () => (
+  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(220px, 1fr))', gap: 16, padding: 32, alignItems: 'start' }}>
+    {reasons.map((r) => (
+      <div key={r} style={{ display: 'grid', gap: 8 }}>
+        <code style={{ fontSize: 12 }}>{r}</code>
+        <MediaState reason={r} ratio={r === 'video-unavailable' ? '16 / 9' : '4 / 3'} onAction={() => {}} />
+      </div>
+    ))}
+  </div>
+)
+
+const meta = {
+  title: 'Nova/02 Components/States/MediaState',
+  component: MediaState,
+  tags: ['autodocs'],
+  args: { reason: 'failed', ratio: '4 / 3', onAction: fn() },
+  render: (a) => <div style={{ padding: 32, maxWidth: 420 }}><MediaState {...a} /></div>,
+} satisfies Meta<typeof MediaState>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Storefront: Story = { name: 'Overview · storefront', render: () => <Grid /> }
+export const Editor: Story = { name: 'Overview · editor', render: () => <Grid />, parameters: { nova: { mode: 'editor' } } }
+export const Playground: Story = {}

package/templates/nova/tests/cases/components/states/SkeletonLayout.cases.tsx

@@ -0,0 +1,20 @@
+import type { Meta, StoryObj } from '../../../support/case'
+import { SkeletonLayout } from '../../../../src/components/states/SkeletonLayout'
+
+const meta = {
+  title: 'Nova/02 Components/States/Skeletons',
+  component: SkeletonLayout,
+  tags: ['autodocs'],
+  args: { kind: 'product-grid', name: 'products', columns: 4 },
+  render: (a) => <div style={{ padding: '32px var(--page-gutter)' }}><SkeletonLayout {...a} /></div>,
+} satisfies Meta<typeof SkeletonLayout>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const ProductGrid: Story = { name: 'Product grid' }
+export const Pdp: Story = { name: 'PDP', args: { kind: 'pdp', name: 'product' } }
+export const Search: Story = { name: 'Search results', args: { kind: 'search', name: 'results', count: 3 } }
+export const Cart: Story = { name: 'Cart lines', args: { kind: 'cart', name: 'your cart', count: 2 } }
+export const Article: Story = { name: 'Article', args: { kind: 'article', name: 'the article' } }
+export const Row: Story = { name: 'Recommendations row', args: { kind: 'row', name: 'recommendations', columns: 4 } }
+export const Mobile: Story = { name: 'Responsive · 390 · grid 2 columns', globals: { viewport: { value: 'mobile', isRotated: false } } }

package/templates/nova/tests/cases/components/states/Unavailable.cases.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from '../../../support/case'
+import { StateBlock } from '../../../../src/components/states/StateBlock'
+import { Button } from '../../../../src/components/base/Button'
+
+const meta = {
+  title: 'Nova/02 Components/States/Unavailable',
+  component: StateBlock,
+  tags: ['autodocs'],
+  args: { variant: 'unavailable', title: 'This product is no longer available', description: 'It may have sold out for good.', action: <Button href="/collections/all">Shop similar</Button> },
+  render: (a) => <div style={{ padding: 32 }}><StateBlock {...a} /></div>,
+} satisfies Meta<typeof StateBlock>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}
+export const Mobile: Story = { name: 'Responsive · 390', globals: { viewport: { value: 'mobile', isRotated: false } } }

package/templates/nova/tests/cases/components/states/media/MediaError.cases.tsx

@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from '../../../../support/case'
+import { MediaError } from '../../../../../src/components/states/media/MediaError'
+import { Pad } from '../../../../support/story-helpers'
+
+const meta = {
+  title: 'Nova/02 Components/States/MediaError',
+  component: MediaError,
+  tags: ['autodocs'],
+  args: { reason: 'missing', ratio: '4 / 3', rounded: true },
+  decorators: [(S) => <Pad><div style={{ maxWidth: 320 }}><S /></div></Pad>],
+} satisfies Meta<typeof MediaError>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Overview: Story = { render: () => <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(100px, 1fr))', gap: 16, width: '100%' }}><MediaError ratio="1 / 1" /><MediaError reason="failed" ratio="4 / 5" /><MediaError ratio="16 / 9" rounded={false} /></div> }
+export const Playground: Story = {}
+export const GridTile: Story = { name: 'States · grid needs a tile · the name in it', args: { label: 'Linen Napkins, Set of 4', showLabel: true, ratio: '1 / 1' }, decorators: [(S) => <Pad><div style={{ maxWidth: 280 }}><S /></div></Pad>] }
+export const VideoUnavailable: Story = { name: 'States · video unavailable', args: { reason: 'video-unavailable', ratio: '16 / 9' }, decorators: [(S) => <Pad><div style={{ maxWidth: 520 }}><S /></div></Pad>] }

package/templates/nova/tests/cases/components/states/media/MediaPlaceholder.cases.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from '../../../../support/case'
+import { MediaPlaceholder, PLACEHOLDER_FAMILIES } from '../../../../../src/components/states/media/MediaPlaceholder'
+import { PLACEHOLDER_ART } from '../../../../../src/components/states/media/placeholder-art'
+
+/** Nova 14 · SVG placeholder system — the nine families, token-driven, plus what applies to every family (ratio, scheme, density). */
+const meta = {
+  title: 'Nova/02 Components/States/MediaPlaceholder',
+  component: MediaPlaceholder,
+  tags: ['autodocs'],
+  args: { family: 'generic', rounded: true },
+  decorators: [(S, c) => (c.parameters.wide ? <S /> : <div style={{ padding: 32, maxWidth: 480 }}><S /></div>)],
+} satisfies Meta<typeof MediaPlaceholder>
+export default meta
+type Story = StoryObj<typeof meta>
+
+const family = (f: (typeof PLACEHOLDER_FAMILIES)[number]): Story => ({ name: f[0].toUpperCase() + f.slice(1), args: { family: f }, parameters: { docs: { description: { story: PLACEHOLDER_ART[f].label } } } })
+
+export const Overview: Story = {
+  decorators: [(S) => <div style={{ padding: 32 }}><S /></div>],
+  render: () => (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))', gap: 16 }}>
+      {PLACEHOLDER_FAMILIES.map((f) => (
+        <figure key={f} style={{ margin: 0, display: 'grid', gap: 8 }}>
+          <MediaPlaceholder family={f} ratio="4 / 5" />
+          <figcaption style={{ fontSize: 12, color: 'var(--color-fg-muted)' }}>
+            <code>nova-ph-{f}</code> · {PLACEHOLDER_ART[f].label}
+          </figcaption>
+        </figure>
+      ))}
+    </div>
+  ),
+}
+export const Generic = family('generic')
+export const Product = family('product')
+export const Collection = family('collection')
+export const Hero = family('hero')
+export const Editorial = family('editorial')
+export const Avatar = family('avatar')
+export const Store = family('store')
+export const Video = family('video')
+export const Ugc: Story = { ...family('ugc'), name: 'UGC' }
+export const AnyRatio: Story = { name: 'Variants · slice fills any ratio', decorators: [(S) => <div style={{ padding: 32 }}><S /></div>], render: () => <div style={{ display: 'grid', gridTemplateColumns: '2fr 1fr 1fr', gap: 12 }}><MediaPlaceholder family="hero" ratio="21 / 9" /><MediaPlaceholder family="hero" ratio="1 / 1" /><MediaPlaceholder family="hero" ratio="4 / 5" /></div> }
+
+const Row = ({ scheme, bg }: { scheme?: 'page' | 'muted' | 'inverse'; bg: string }) => (
+  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(9, minmax(0, 1fr))', gap: 8, padding: 12, background: bg }}>
+    {PLACEHOLDER_FAMILIES.map((f) => <MediaPlaceholder key={f} family={f} ratio="1 / 1" scheme={scheme} />)}
+  </div>
+)
+export const Schemes: Story = {
+  name: 'Variants · schemes · page · muted · inverse (Nova 14)',
+  parameters: { wide: true },
+  decorators: [(S) => <div style={{ padding: 32 }}><S /></div>],
+  render: () => (
+    <div style={{ display: 'grid', gap: 12 }}>
+      <Row scheme="page" bg="var(--color-bg)" />
+      <Row scheme="muted" bg="var(--color-bg-muted)" />
+      <Row scheme="inverse" bg="#111111" />
+    </div>
+  ),
+}
+export const FromContext: Story = {
+  name: 'Variants · scheme follows the section (muted · inverse surface)',
+  parameters: { wide: true },
+  decorators: [(S) => <div style={{ padding: 32 }}><S /></div>],
+  render: () => (
+    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
+      <div data-nv-surface="muted" style={{ padding: 12, background: 'var(--color-bg-muted)' }}><MediaPlaceholder family="product" ratio="4 / 3" /></div>
+      <div data-nv-surface="inverse" style={{ padding: 12, background: 'var(--color-bg-inverse)' }}><MediaPlaceholder family="product" ratio="4 / 3" /></div>
+    </div>
+  ),
+}
+export const Density: Story = {
+  name: 'Variants · density · < 160px drops secondary layers',
+  parameters: { wide: true },
+  decorators: [(S) => <div style={{ padding: 32 }}><S /></div>],
+  render: () => (
+    <div style={{ display: 'flex', gap: 16, alignItems: 'flex-end', flexWrap: 'wrap' }}>
+      {(['product', 'collection', 'avatar', 'ugc', 'store', 'editorial'] as const).map((f) => (
+        <div key={f} style={{ display: 'grid', gap: 8 }}>
+          <div style={{ width: 88 }}><MediaPlaceholder family={f} ratio="1 / 1" /></div>
+          <div style={{ width: 200 }}><MediaPlaceholder family={f} ratio="1 / 1" /></div>
+        </div>
+      ))}
+    </div>
+  ),
+}
+export const VideoUnavailable: Story = { name: 'States · video unavailable · slashed play', args: { family: 'video', state: 'unavailable' } }

package/templates/nova/tests/cases/sections/Overview.cases.tsx

@@ -0,0 +1,8 @@
+import type { Meta, StoryObj } from '../../support/case'
+import { SectionsOverview } from '../../support/ia-pages'
+
+/** Sections = page-level compositions of Components. */
+const meta = { title: 'Nova/03 Sections/Overview', parameters: { layout: 'fullscreen' } } satisfies Meta
+export default meta
+
+export const Overview: StoryObj = { render: () => <SectionsOverview /> }

package/templates/nova/tests/cases/sections/commerce/collection-list/CollectionList.cases.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '../../../../support/case'
+import { expect, within } from '../../../../support/case'
+import { CollectionList, type CollectionListProps } from '../../../../../src/sections/CollectionList/CollectionList'
+import { collectionListSchema } from '../../../../../src/sections/CollectionList/schema'
+import { collectionItemSchema } from '../../../../../src/sections/CollectionList/blocks/CollectionItem'
+import { defaultsOf, resolveSettings } from '@tanqory/theme-kit'
+import { presetArgs } from '../../../../support/presets'
+import { Stack } from '../../../../support/story-helpers'
+import * as fx from '../../../../fixtures/index'
+
+const preset = (name: string) => presetArgs(collectionListSchema, name)
+const items = fx.merchRooms.slice(0, 4).map((c) => ({ settings: resolveSettings(collectionItemSchema, {}).settings, collection: c }))
+const base: CollectionListProps = { ...defaultsOf(collectionListSchema), heading: 'Shop by room', items }
+const mobile = { viewport: { value: 'mobile', isRotated: false } }
+
+const meta = {
+  title: 'Nova/03 Sections/Commerce/CollectionList',
+  component: CollectionList,
+  tags: ['autodocs'],
+  args: base,
+} satisfies Meta<typeof CollectionList>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Overview: Story = { render: (a) => <Stack base={a} items={[PresetGrid, PresetOverlay, PresetEditorial]} render={(x) => <CollectionList {...x} />} /> }
+export const Playground: Story = {}
+export const PresetGrid: Story = { name: 'Preset · Grid', args: preset('cl-grid') }
+export const PresetOverlay: Story = { name: 'Preset · Labels on image', args: { ...preset('cl-overlay'), items: items.slice(0, 3) } }
+export const PresetEditorial: Story = { name: 'Preset · Editorial · first leads', args: { ...preset('cl-editorial'), items: items.slice(0, 3) } }
+export const Carousel: Story = { name: 'Option · layout · carousel', args: { layout: 'carousel', items: fx.merchRooms.map((c) => ({ settings: items[0].settings, collection: c })) } }
+export const Description: Story = { name: 'Option · showDescription', args: { showDescription: true } }
+export const Two: Story = { name: 'State · 2 collections → two wide landscape tiles', args: { items: items.slice(0, 2) } }
+export const NoImage: Story = { name: 'State · collection without image → first product image', args: { items: [...items.slice(0, 3), { settings: items[0].settings, collection: fx.merchRoomNoImage }] } }
+export const Fallback: Story = { name: 'State · no blocks → newest collections (limit)', args: { items: [], fallbackCollections: fx.merchRooms, limit: 4 } }
+export const Skipped: Story = { name: 'State · unpublished item · editor flags it', args: { items: [...items.slice(0, 3), { settings: items[0].settings, collection: null }] }, parameters: { nova: { mode: 'editor' } } }
+export const Empty: Story = { name: 'State · none · editor setup', args: { items: [] }, parameters: { nova: { mode: 'editor' } } }
+export const Mobile: Story = { name: 'Responsive · 390 · carousel 2.3 visible', globals: mobile }
+export const PageHeading: Story = {
+  name: 'Accessibility · pageHeading → the heading is the h1',
+  args: { pageHeading: true },
+  play: async ({ canvasElement }) => expect(within(canvasElement).getByRole('heading', { level: 1 })).toHaveTextContent('Shop by room'),
+}
+export const LegacyCollections: Story = {
+  name: 'Legacy · collections text list (resolved by the adapter) when no blocks',
+  args: { ...resolveSettings(collectionListSchema, { collections: 'kitchen-table,pantry', heading: 'Shop by room' }).settings, items: [], fallbackCollections: [fx.merchRooms[0], fx.merchRooms[2]] },
+}

package/templates/nova/tests/cases/sections/commerce/collection-list/blocks/CollectionItem.cases.tsx

@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from '../../../../../support/case'
+import { CollectionCard } from '../../../../../../src/components/commerce/CollectionCard'
+import { blockFrame } from '../../../../../support/block-stories'
+import * as fx from '../../../../../fixtures/index'
+
+/** collection-item renders as a CollectionCard inside collection-list (tile per layout). */
+const meta = {
+  title: 'Nova/03 Sections/Commerce/Blocks/CollectionItem',
+  component: CollectionCard,
+  tags: ['autodocs'],
+  args: { collection: fx.merchRooms[1], title: '' },
+  decorators: [blockFrame],
+} satisfies Meta<typeof CollectionCard>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}
+export const CustomTitle: Story = { name: 'Variants · custom title', args: { title: 'For the bedroom' } }

package/templates/nova/tests/cases/sections/commerce/featured-collection/FeaturedCollection.cases.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '../../../../support/case'
+import { expect, within } from '../../../../support/case'
+import { FeaturedCollection, type FeaturedCollectionProps } from '../../../../../src/sections/FeaturedCollection/FeaturedCollection'
+import { featuredCollectionSchema } from '../../../../../src/sections/FeaturedCollection/schema'
+import { defaultsOf, resolveSettings } from '@tanqory/theme-kit'
+import { presetArgs } from '../../../../support/presets'
+import { Stack } from '../../../../support/story-helpers'
+import * as fx from '../../../../fixtures/index'
+
+const preset = (name: string) => presetArgs(featuredCollectionSchema, name)
+const newSeason = { ...fx.merchRooms[0], products: fx.merchProducts }
+const base: FeaturedCollectionProps = { ...defaultsOf(featuredCollectionSchema), eyebrow: 'Just in', heading: 'New this season', collection: newSeason }
+const mobile = { viewport: { value: 'mobile', isRotated: false } }
+
+const meta = {
+  title: 'Nova/03 Sections/Commerce/FeaturedCollection',
+  component: FeaturedCollection,
+  tags: ['autodocs'],
+  args: base,
+} satisfies Meta<typeof FeaturedCollection>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Overview: Story = { render: (a) => <Stack base={a} items={[PresetNewArrivals, PresetCarousel, PresetDense]} render={(x) => <FeaturedCollection {...x} />} /> }
+export const Playground: Story = {}
+export const PresetNewArrivals: Story = { name: 'Preset · New arrivals', args: preset('fc-new-arrivals') }
+export const PresetCarousel: Story = { name: 'Preset · Carousel', args: preset('fc-carousel') }
+export const PresetDense: Story = { name: 'Preset · Dense bestsellers', args: { ...preset('fc-bestsellers-dense'), heading: 'Bestsellers', eyebrow: '' } }
+export const Centered: Story = { name: 'Option · headerAlignment · center · View all under the grid', args: { headerAlignment: 'center' } }
+export const Portrait: Story = { name: 'Option · cardImageRatio · portrait', args: { cardImageRatio: 'portrait' } }
+export const MobileOne: Story = { name: 'Option · mobileColumns · 1', args: { mobileColumns: '1' }, globals: mobile }
+export const FewProducts: Story = { name: 'State · 2 products · keep 4-column width · View all hidden', args: { collection: { ...newSeason, products: fx.merchProducts.slice(0, 2), productsCount: 2 } } }
+export const Empty: Story = { name: 'State · empty collection · storefront hidden', args: { collection: { ...newSeason, products: [] } } }
+export const EmptyEditor: Story = { ...Empty, name: 'State · empty collection · editor setup', parameters: { nova: { mode: 'editor' } } }
+export const Thai: Story = { name: 'Stress · Thai', args: { eyebrow: 'มาใหม่', heading: 'คอลเลกชันใหม่ประจำฤดูกาล' }, parameters: { nova: { locale: 'th' } } }
+export const Arabic: Story = { name: 'Stress · RTL · Arabic · carousel mirrors', args: { ...preset('fc-carousel'), eyebrow: 'وصل حديثًا', heading: 'جديد هذا الموسم' }, parameters: { nova: { locale: 'ar' } } }
+export const Mobile: Story = { name: 'Responsive · 390 · carouselOnMobile · peek', args: { carouselOnMobile: true }, globals: mobile }
+export const LegacySubheading: Story = {
+  name: 'Legacy · subheading → eyebrow',
+  args: { ...resolveSettings(featuredCollectionSchema, { subheading: 'Just in', heading: 'New this season' }).settings, collection: newSeason },
+  play: async ({ canvasElement }) => expect(within(canvasElement).getByText('Just in')).toBeInTheDocument(),
+}
+export const ViewAllCount: Story = {
+  name: 'Accessibility · View all names the count',
+  play: async ({ canvasElement }) => expect(within(canvasElement).getByRole('link', { name: 'View all 48' })).toHaveAttribute('href', '/collections/kitchen-table'),
+}

package/templates/nova/tests/cases/sections/commerce/featured-product/FeaturedProduct.cases.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '../../../../support/case'
+import { expect, fn, userEvent, waitFor, within } from '../../../../support/case'
+import { FeaturedProduct, type FeaturedProductProps } from '../../../../../src/sections/FeaturedProduct/FeaturedProduct'
+import { featuredProductSchema } from '../../../../../src/sections/FeaturedProduct/schema'
+import { defaultsOf } from '@tanqory/theme-kit'
+import { presetArgs } from '../../../../support/presets'
+import * as fx from '../../../../fixtures/index'
+
+const base: FeaturedProductProps = { ...defaultsOf(featuredProductSchema), eyebrow: 'Product of the month', product: fx.merchPourOver, background: 'surface-secondary', onAddToCart: fn(async () => {}) }
+const mobile = { viewport: { value: 'mobile', isRotated: false } }
+
+const meta = {
+  title: 'Nova/03 Sections/Commerce/FeaturedProduct',
+  component: FeaturedProduct,
+  tags: ['autodocs'],
+  args: base,
+} satisfies Meta<typeof FeaturedProduct>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Overview: Story = { args: presetArgs(featuredProductSchema, 'fp-spotlight') }
+export const Playground: Story = {}
+export const PresetSpotlight: Story = { name: 'Preset · Spotlight', args: presetArgs(featuredProductSchema, 'fp-spotlight') }
+export const PresetStory: Story = { name: 'Preset · Story', args: { ...presetArgs(featuredProductSchema, 'fp-story'), product: fx.merchDuvet } }
+export const NoVariants: Story = { name: 'Option · showVariants · off · price + button', args: { showVariants: false } }
+export const Sold: Story = { name: 'State · sold out · disabled + View details', args: { product: fx.merchCandle } }
+export const NoImage: Story = { name: 'State · no image · text-only spotlight', args: { product: fx.merchNapkins } }
+export const None: Story = { name: 'State · no product · storefront hidden', args: { product: null } }
+export const NoneEditor: Story = { name: 'State · product unpublished · editor explains', args: { product: null, productUnavailable: true }, parameters: { nova: { mode: 'editor' } } }
+export const LongTitle: Story = { name: 'Stress · long title wraps to 3 lines', args: { product: fx.merchPlatter } }
+export const Mobile: Story = { name: 'Responsive · 390 · image first · full-width button', globals: mobile }
+export const Add: Story = {
+  name: 'Accessibility · Add to cart → Adding… → Added',
+  play: async ({ canvasElement, args }) => {
+    const c = within(canvasElement)
+    await userEvent.click(c.getByRole('button', { name: 'Add to cart' }))
+    await waitFor(() => expect(c.getByRole('button', { name: 'Added' })).toBeInTheDocument())
+    await expect(args.onAddToCart).toHaveBeenCalled()
+  },
+}

package/templates/nova/tests/cases/sections/commerce/main-collection/MainCollection.cases.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '../../../../support/case'
+import { expect, userEvent, waitFor, within } from '../../../../support/case'
+import { MainCollection, type MainCollectionProps } from '../../../../../src/sections/MainCollection/MainCollection'
+import { mainCollectionSchema } from '../../../../../src/sections/MainCollection/schema'
+import { defaultsOf } from '@tanqory/theme-kit'
+import { presetArgs } from '../../../../support/presets'
+import { useListingDemo } from '../../../../support/listing-demo'
+import * as fx from '../../../../fixtures/index'
+
+const preset = (name: string) => presetArgs(mainCollectionSchema, name)
+const trail = [{ title: 'Home', url: '/' }, { title: 'Collections', url: '/collections' }, { title: 'Kitchen & Table' }]
+const base: MainCollectionProps = { ...defaultsOf(mainCollectionSchema), collection: fx.merchRooms[0], breadcrumbs: trail, productsPerPage: '6', showBreadcrumb: true }
+const mobile = { viewport: { value: 'mobile', isRotated: false } }
+
+function Demo(args: MainCollectionProps) {
+  const demo = useListingDemo()
+  return <MainCollection {...args} {...demo} {...(args.products ? { products: args.products, total: args.total } : {})} facets={args.facets ?? demo.facets} />
+}
+
+const meta = {
+  title: 'Nova/03 Sections/Commerce/MainCollection',
+  component: MainCollection,
+  tags: ['autodocs'],
+  args: base,
+  render: (a) => <Demo {...a} />,
+} satisfies Meta<typeof MainCollection>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Overview: Story = { name: 'Overview', args: preset('collection-sidebar') }
+export const Playground: Story = { name: 'Playground' }
+export const PresetSidebar: Story = { name: 'Preset · Sidebar filters', args: preset('collection-sidebar') }
+export const PresetTopBar: Story = { name: 'Preset · Top-bar filters', args: preset('collection-top-bar') }
+export const PresetDrawer: Story = { name: 'Preset · Drawer filters', args: preset('collection-drawer') }
+export const Banner: Story = { name: 'Option · showCollectionImage · banner 21:9', args: { showCollectionImage: 'banner' } }
+export const NoHeader: Story = { name: 'Option · showHeader · off (a collection-banner above)', args: { showHeader: false } }
+export const Pages: Story = { name: 'Option · pagination · pages', args: { pagination: 'pages', page: 1, pageHref: (n: number) => `?page=${n}` } as Partial<MainCollectionProps> }
+export const NoFilters: Story = { name: 'Option · filterLayout · none', args: { filterLayout: 'none' } }
+
+export const Loading: Story = { name: 'State · loading · skeleton at card geometry', args: { state: 'loading' } }
+export const Failed: Story = { name: 'State · loading failed · Try again', args: { state: 'error' } }
+export const NoMatches: Story = {
+  name: 'State · filters exclude everything → Clear all',
+  args: { facets: fx.merchFacets.map((f) => (f.id === 'type' ? { ...f, values: f.values!.map((v) => ({ ...v, active: v.id === 'textiles' })) } : f)), products: [], total: 0 } as Partial<MainCollectionProps>,
+}
+export const Empty: Story = { name: 'State · empty collection → Shop all', args: { facets: [], products: [], total: 0 } as Partial<MainCollectionProps> }
+export const NoFacetsEditor: Story = { name: 'State · no facets configured · editor explains', args: { facets: [] } as Partial<MainCollectionProps>, parameters: { nova: { mode: 'editor' } } }
+export const Thai: Story = { name: 'Stress · Thai', args: { collection: fx.bannerCollectionThai }, parameters: { nova: { locale: 'th' } } }
+
+export const Mobile: Story = { name: 'Responsive · 390 · Filter + Sort · 2 columns', globals: mobile }
+export const Tablet: Story = { name: 'Responsive · 768 · sheet filters · 2 columns', globals: { viewport: { value: 'tablet', isRotated: false } } }
+
+export const FilterChips: Story = {
+  name: 'Accessibility · removing a chip updates the grid',
+  tags: ['viewport:desktop'],
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement)
+    await userEvent.click(c.getByRole('button', { name: 'Remove filter: Stoneware' }))
+    await waitFor(() => expect(c.queryByRole('button', { name: 'Remove filter: Stoneware' })).toBeNull())
+  },
+}
+export const LoadMoreStory: Story = {
+  name: 'Accessibility · Load more shows the next page',
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement)
+    await expect(c.getByText('Showing 6 of 21')).toBeInTheDocument()
+    await userEvent.click(c.getByRole('button', { name: 'Load more' }))
+    await waitFor(() => expect(c.getByText('Showing 12 of 21')).toBeInTheDocument())
+  },
+}
+export const SortPopover: Story = {
+  name: 'Accessibility · sort opens a list, Esc closes and returns focus',
+  tags: ['viewport:desktop'],
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement)
+    const button = c.getAllByRole('button', { name: /Sort: Featured/ }).find((b) => b.offsetParent !== null) ?? c.getAllByRole('button', { name: /Sort: Featured/ })[0]
+    await userEvent.click(button)
+    await userEvent.click(c.getByRole('button', { name: 'Newest' }))
+    await waitFor(() => expect(c.getAllByRole('button', { name: /Sort: Newest/ }).length).toBeGreaterThan(0))
+  },
+}

package/templates/nova/tests/cases/sections/commerce/product-details/ProductDetails.cases.tsx

@@ -0,0 +1,110 @@
+import type { Meta, StoryObj } from '../../../../support/case'
+import { expect, fn, userEvent, waitFor, within } from '../../../../support/case'
+import { ProductDetails, type ProductDetailsBlock, type ProductDetailsProps } from '../../../../../src/sections/ProductDetails/ProductDetails'
+import { productDetailsSchema } from '../../../../../src/sections/ProductDetails/schema'
+import { defaultsOf } from '@tanqory/theme-kit'
+import { presetsFor } from '../../../../../scripts/compiler/contracts/index'
+import { presetArgs } from '../../../../support/presets'
+import * as fx from '../../../../fixtures/index'
+
+// The pdp-standard preset's blocks, with the canvas copy for the custom tab and badges.
+const standard: ProductDetailsBlock[] = [
+  ...(presetsFor('product-details').find((p) => p.name === 'pdp-standard')!.blocks.filter((b) => b.type !== 'tab' && b.type !== 'badge') as ProductDetailsBlock[]),
+  { type: 'tab', settings: { source: 'product-description', openByDefault: true } },
+  { type: 'tab', settings: { source: 'custom', heading: 'Materials & care', body: '<p>100% European flax. Machine wash warm, tumble dry low. Softens with every wash.</p>' } },
+  { type: 'tab', settings: { source: 'custom', heading: 'Shipping & returns', body: '<p>Free shipping over $120, 2–4 days. 30-day returns, collected from your door.</p>' } },
+  { type: 'badge', settings: { icon: 'truck', label: 'Free shipping', detail: 'Over $120, 2–4 days' } },
+  { type: 'badge', settings: { icon: 'return', label: '30-day returns', detail: 'Collected from your door' } },
+]
+const sizeGuide = { title: 'Size guide', html: '<table><thead><tr><th>Size</th><th>Width</th><th>Length</th></tr></thead><tbody><tr><td>Twin</td><td>172 cm</td><td>218 cm</td></tr><tr><td>Full</td><td>200 cm</td><td>218 cm</td></tr><tr><td>Queen</td><td>228 cm</td><td>233 cm</td></tr><tr><td>King</td><td>264 cm</td><td>233 cm</td></tr></tbody></table>' }
+const trail = [{ title: 'Home', url: '/' }, { title: 'Bedroom & Bath', url: '/collections/bedroom-bath' }, { title: 'Washed Linen Duvet Cover' }]
+const base: ProductDetailsProps = {
+  ...defaultsOf(productDetailsSchema),
+  showVendor: true,
+  priceNote: 'Taxes included. Shipping calculated at checkout.',
+  product: fx.merchDuvet,
+  blocks: standard,
+  breadcrumbs: trail,
+  sizeGuide,
+  initialVariantId: fx.merchDuvet.variants.find((v) => v.title === 'Queen / Oat')!.id,
+  onAddToCart: fn(async () => {}),
+}
+const mobile = { viewport: { value: 'mobile', isRotated: false } }
+
+const meta = {
+  title: 'Nova/03 Sections/Commerce/ProductDetails',
+  component: ProductDetails,
+  tags: ['autodocs'],
+  args: base,
+} satisfies Meta<typeof ProductDetails>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Overview: Story = {}
+export const Playground: Story = {}
+export const PresetStandard: Story = { name: 'Preset · Standard', args: presetArgs(productDetailsSchema, 'pdp-standard') }
+export const PresetEditorial: Story = { name: 'Preset · Editorial · stacked gallery', args: presetArgs(productDetailsSchema, 'pdp-editorial') }
+export const PresetCompact: Story = { name: 'Preset · Compact · thumbnails below · square', args: presetArgs(productDetailsSchema, 'pdp-compact') }
+export const Buttons: Story = { name: 'Option · variantStyle · buttons', args: { variantStyle: 'buttons' } }
+export const Select: Story = { name: 'Option · variantStyle · select', args: { variantStyle: 'select' } }
+export const Tabs: Story = { name: 'Option · accordionItems · off → tabs on desktop', args: { accordionItems: false } }
+export const Sku: Story = { name: 'Option · showSku · on', args: { showSku: true, blocks: [...standard, { type: 'product-sku' }] } }
+export const StockAlways: Story = { name: 'Option · showInventory · always', args: { showInventory: 'always', initialVariantId: fx.merchDuvet.variants[0].id } }
+export const Swatches: Story = { name: 'Option · swatches block · colour on its own row', args: { blocks: [...standard, { type: 'swatches' }] } }
+export const ContentBlocks: Story = {
+  name: 'Option · heading / text / button blocks below the buy box',
+  args: { blocks: [...standard, { type: 'heading', settings: { text: 'Made in Portugal' } }, { type: 'text', settings: { text: 'Woven on shuttle looms by a family mill since 1932.' } }, { type: 'button', settings: { label: 'Our makers', link: '/pages/makers', variant: 'secondary' } }] },
+}
+export const Unavailable: Story = { name: 'State · King is not made in Oat → reason shown', args: { initialVariantId: undefined, blocks: standard }, play: async ({ canvasElement }) => { const c = within(canvasElement); await userEvent.click(c.getByRole('radio', { name: /King/ })); await waitFor(() => expect(c.getByText('King / Oat is not available')).toBeInTheDocument()) } }
+export const SoldOut: Story = { name: 'State · all variants sold out', args: { product: fx.merchCandle, blocks: standard } }
+export const NoImages: Story = { name: 'State · no images → neutral tile with the name', args: { product: fx.merchNapkins, blocks: standard } }
+export const Single: Story = { name: 'State · one image, no options', args: { product: fx.merchSimple, blocks: standard } }
+export const None: Story = { name: 'State · no product · editor setup', args: { product: null }, parameters: { nova: { mode: 'editor' } } }
+export const Thai: Story = { name: 'Stress · Thai', args: { product: { ...fx.merchDuvet, title: 'ปลอกผ้านวมลินินฟอก — ควีน สีโอ๊ต' } }, parameters: { nova: { locale: 'th' } } }
+export const Arabic: Story = { name: 'Stress · RTL · Arabic · gallery mirrors', parameters: { nova: { locale: 'ar' } } }
+export const Mobile: Story = { name: 'Responsive · 390 · swipe gallery · accordion', globals: mobile }
+
+export const AddFlow: Story = {
+  name: 'Accessibility · Add to cart → Adding… → Added (host called with variant + qty)',
+  play: async ({ canvasElement, args }) => {
+    const c = within(canvasElement)
+    await userEvent.click(c.getByRole('button', { name: 'Increase quantity' }))
+    await userEvent.click(c.getAllByRole('button', { name: 'Add to cart' })[0])
+    await waitFor(() => expect(c.getAllByRole('button', { name: 'Added' }).length).toBeGreaterThan(0))
+    await expect(args.onAddToCart).toHaveBeenCalledWith(expect.objectContaining({ title: 'Queen / Oat' }), 2)
+  },
+}
+export const AddError: Story = {
+  name: 'Accessibility · add failed → inline error (role="alert")',
+  args: { onAddToCart: fn(async () => Promise.reject(new Error('network'))) },
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement)
+    await userEvent.click(c.getAllByRole('button', { name: 'Add to cart' })[0])
+    await waitFor(() => expect(c.getByRole('alert')).toHaveTextContent("Couldn't add. Try again."))
+  },
+}
+export const SizeGuide: Story = {
+  name: 'Accessibility · Size guide opens a drawer; Esc closes',
+  tags: ['browser-only'],
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement.ownerDocument.body)
+    await userEvent.click(c.getByRole('button', { name: 'Size guide' }))
+    await waitFor(() => expect(c.getByRole('dialog', { name: 'Size guide' })).toBeVisible())
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(c.queryByRole('dialog', { name: 'Size guide' })).toBeNull())
+  },
+}
+export const Zoom: Story = {
+  name: 'Accessibility · zoom lightbox · ← → · Esc returns focus',
+  tags: ['browser-only', 'viewport:desktop'],
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement.ownerDocument.body)
+    const zoom = c.getAllByRole('button', { name: 'Zoom image' })[0]
+    await userEvent.click(zoom)
+    await waitFor(() => expect(c.getByText('Image 1 of 6')).toBeVisible())
+    await userEvent.keyboard('{ArrowRight}')
+    await waitFor(() => expect(c.getByText('Image 2 of 6')).toBeVisible())
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(c.queryByText('Image 2 of 6')).toBeNull())
+  },
+}

package/templates/nova/tests/cases/sections/commerce/product-details/blocks/AddToCartBlock.cases.tsx

@@ -0,0 +1,21 @@
+import type { Meta, StoryObj } from '../../../../../support/case'
+import { fn } from '../../../../../support/case'
+import { AddToCartBlock } from '../../../../../../src/sections/ProductDetails/blocks/AddToCartBlock'
+import { blockFrame } from '../../../../../support/block-stories'
+
+const meta = {
+  title: 'Nova/03 Sections/Commerce/Blocks/AddToCart',
+  component: AddToCartBlock,
+  tags: ['autodocs'],
+  args: { label: 'Add to cart', onAdd: fn(async () => {}) },
+  decorators: [blockFrame],
+} satisfies Meta<typeof AddToCartBlock>
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {}
+export const Adding: Story = { name: 'States · adding (width kept, aria-busy)', args: { initialState: 'adding' } }
+export const Added: Story = { name: 'States · added', args: { initialState: 'added' } }
+export const ErrorState: Story = { name: 'States · error (role="alert")', args: { initialState: 'error' } }
+export const Unavailable: Story = { name: 'States · unavailable with the reason', args: { unavailableReason: 'King / Oat is not available' } }
+export const SoldOut: Story = { name: 'States · sold out', args: { soldOut: true } }