create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/src/sections/Faq/Faq.tsx

@@ -0,0 +1,51 @@
+import { useState } from 'react'
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { Accordion, AccordionItem } from '../../components/base/Accordion'
+import { RichText } from '../../components/content/RichText'
+import { SectionHead } from '../../components/content/SectionHead'
+import { faqItemIsEmpty, type FaqItemSettings } from './blocks/FaqItem'
+import { useNova } from '../../styles/NovaProvider'
+import { EmptySection, Shell } from '../../components/section/shell'
+import '../../components/section/shared.css'
+import '../../styles/sections/content.css'
+import { faqSchema } from './schema'
+
+export type FaqSettings = SettingsOf<typeof faqSchema>
+export interface FaqProps extends FaqSettings {
+  items?: FaqItemSettings[]
+}
+
+export function Faq(props: FaqProps): JSX.Element | null {
+  const { layout, singleOpen, firstOpen, headerAlignment, sectionWidth, contentWidth, heading, eyebrow, description, headerSize, items = [] } = props
+  const { strings } = useNova()
+  const list = items.filter((i) => !faqItemIsEmpty(i))
+  const [open, setOpen] = useState<Set<number>>(() => new Set(firstOpen ? [0] : []))
+  if (!list.length) return <EmptySection props={props} type="faq" width={sectionWidth} title={strings.editorAddBlocks} />
+  const toggle = (i: number, next: boolean) =>
+    setOpen((cur) => {
+      const s = singleOpen ? new Set<number>() : new Set(cur)
+      if (next) s.add(i)
+      else s.delete(i)
+      return s
+    })
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: list.map((q) => ({ '@type': 'Question', name: q.question, acceptedAnswer: { '@type': 'Answer', text: q.answer.replace(/<[^>]*>/g, '').trim() } })),
+  }
+  return (
+    <Shell props={props} type="faq" width={sectionWidth} className="nv-faq" data-layout={layout} data-measure={contentWidth}>
+      <div className="nv-faq__grid">
+        <SectionHead eyebrow={eyebrow} heading={heading} description={description} headerSize={headerSize} align={layout === 'above' ? headerAlignment : 'left'} />
+        <Accordion className="nv-faq__list">
+          {list.map((q, i) => (
+            <AccordionItem key={i} title={q.question} open={open.has(i)} onOpenChange={(n) => toggle(i, n)} level={heading ? 3 : 2}>
+              <RichText html={q.answer} />
+            </AccordionItem>
+          ))}
+        </Accordion>
+      </div>
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c') }} />
+    </Shell>
+  )
+}

package/templates/nova/src/sections/Faq/blocks/FaqItem.tsx

@@ -0,0 +1,13 @@
+import { defineSchema, field, type SettingsOf } from '@tanqory/theme-kit'
+import '../../../styles/blocks.css'
+
+/** 12D · faq-item block — one question and its answer. Skipped when the question is empty; an empty answer hides the item. */
+export const faqItemSchema = defineSchema(
+  { kind: 'block', name: 'faq-item', family: '12D', parents: ['faq'], title: 'Question', description: 'One question and its answer.', icon: '?' },
+  {
+    question: field.text('Your question?'),
+    answer: field.richtext(''),
+  },
+)
+export type FaqItemSettings = SettingsOf<typeof faqItemSchema>
+export const faqItemIsEmpty = (s: FaqItemSettings) => !s.question.trim() || !s.answer.replace(/<[^>]*>/g, '').trim()

package/templates/nova/src/sections/Faq/index.ts

@@ -0,0 +1,28 @@
+import { defineSection, resolveSettings } from '@tanqory/theme-kit'
+import { Faq } from './Faq'
+import { faqItemSchema } from './blocks/FaqItem'
+import { presets } from './presets'
+import { faqSchema } from './schema'
+
+export default defineSection({
+  id: 'faq',
+  schema: faqSchema,
+  blocks: [faqItemSchema],
+  component: Faq,
+  category: 'content',
+  zone: 'main',
+  title: 'FAQ',
+  description: 'Questions and answers that open on tap.',
+  icon: '?',
+  presets,
+  data: (node) => {
+      const r = resolveSettings(faqSchema, node.settings)
+      const issues = [...r.issues]
+      const items = (node.blocks ?? []).filter((b) => b.type === 'faq-item').map((b) => {
+        const br = resolveSettings(faqItemSchema, b.settings)
+        issues.push(...br.issues)
+        return br.settings
+      })
+      return { ...r.settings, items }
+  },
+})

package/templates/nova/src/sections/Faq/presets.ts

@@ -0,0 +1,8 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Default FAQ
+  {"name": "faq-beside", "label": "FAQ beside", "settings": {"layout": "beside", "firstOpen": true}, "blocks": []},
+  // Short FAQ in a narrow column
+  {"name": "faq-centered", "label": "FAQ centered", "settings": {"layout": "above", "headerAlignment": "center", "contentWidth": "narrow"}, "blocks": []},
+]

package/templates/nova/src/sections/Faq/schema.ts

@@ -0,0 +1,32 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12D · 06 faq — the questions that stop a purchase. beside = heading 4/12 +
+ * list 8/12 (above < 1024). Questions are buttons with aria-expanded; answers
+ * are regions labelled by the question; rows ≥ 56; questions wrap, never
+ * truncate. singleOpen closes the others; firstOpen affects the first render
+ * only. FAQPage structured data comes from the faq-item blocks.
+ */
+export const faqSchema = defineSchema(
+  { kind: 'section', name: 'faq', family: '12D', blocks: ['faq-item'] },
+  {
+    layout: field.select(['beside', 'above'], 'beside'),
+    singleOpen: field.boolean(false),
+    firstOpen: field.boolean(true),
+    headerAlignment: field.select(['left', 'center'], 'left'),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    contentWidth: shared.contentWidth('content'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    spacingTop: shared.spacingTop('large'),
+    spacingBottom: shared.spacingBottom('large'),
+    background: shared.background('surface'),
+    heading: shared.heading(),
+    eyebrow: shared.eyebrow(),
+    description: shared.description(),
+    headerSize: shared.headerSize('medium'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)

package/templates/nova/src/sections/FeatureGridBlocks/FeatureGridBlocks.tsx

@@ -0,0 +1,90 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties, ReactNode } from 'react'
+import { resolveSettings, type SettingsOf } from '@tanqory/theme-kit'
+import { RichText } from '../../components/content/RichText'
+import { SectionHead } from '../../components/content/SectionHead'
+import { HeroMedia } from '../../components/content/HeroMedia'
+import { ButtonBlock, buttonSchema } from '../../components/content/blocks/Button'
+import { HeadingBlock, headingSchema } from '../../components/content/blocks/Heading'
+import { IconBlock, iconSchema } from '../../components/content/blocks/Icon'
+import { ImageBlock, imageSchema } from '../../components/content/blocks/Image'
+import { TextBlock, textSchema } from '../../components/content/blocks/Text'
+import { columnIsEmpty, type ColumnInstance } from '../../components/content/blocks/Column'
+import { Icon, type IconName } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import type { NovaImage } from '@tanqory/theme-kit'
+import { EmptySection, Shell } from '../../components/section/shell'
+import '../../components/section/shared.css'
+import '../../styles/sections/content.css'
+import { featureGridBlocksSchema } from './schema'
+
+export type FeatureGridBlock =
+  | ({ type: 'column' } & ColumnInstance)
+  | { type: 'heading' | 'text' | 'button' | 'icon'; settings?: Record<string, unknown> }
+  | { type: 'image'; settings?: Record<string, unknown>; image?: NovaImage | null }
+
+export type FeatureGridBlocksSettings = SettingsOf<typeof featureGridBlocksSchema>
+export interface FeatureGridBlocksProps extends FeatureGridBlocksSettings {
+  blocks?: FeatureGridBlock[]
+}
+
+const LEADS = new Set(['1+4', '1+2'])
+
+export function FeatureGridBlocks(props: FeatureGridBlocksProps): JSX.Element | null {
+  const { columns, preset, rowHeight, blockBackground, sectionWidth, contentAlignment, heading, eyebrow, description, headerSize, blocks = [] } = props
+  const { strings } = useNova()
+  const tiles = blocks.filter((b) => b.type !== 'column' || !columnIsEmpty(b))
+  if (!tiles.length) return <EmptySection props={props} type="feature-grid-blocks" width={sectionWidth} title={strings.editorAddBlocks} hint={strings.editorAddBlocksHint} />
+  // Graceful fewer: a lead layout with too few tiles becomes equal tiles.
+  const layout = LEADS.has(preset) && tiles.length < 3 ? '2+2' : preset
+  const H = heading ? 'h3' : 'h2'
+
+  const tile = (b: FeatureGridBlock, i: number): ReactNode => {
+    const lead = i === 0 && LEADS.has(layout)
+    if (b.type === 'column') {
+      const s = b.settings
+      // The lead tile carries its image; other tiles only when blockBackground = image (62% floor).
+      const onImage = Boolean(b.image) && (lead || blockBackground === 'image')
+      return (
+        <li key={i} className="nv-fgb__tile" data-lead={lead ? '' : undefined} data-bg={onImage ? 'image' : blockBackground === 'image' ? 'surface-secondary' : blockBackground}>
+          {onImage && <HeroMedia image={b.image} video={lead ? b.video : null} priority={false} />}
+          {onImage && <span className="nv-fgb__scrim" aria-hidden />}
+          <div className="nv-fgb__content" data-nv-surface={onImage || blockBackground === 'primary' ? 'inverse' : undefined}>
+            {!onImage && s.icon !== 'none' && <Icon name={s.icon as IconName} size="md" />}
+            <div className="nv-fgb__text">
+              {s.heading.trim() && <H className="nv-fgb__title"><bdi>{s.heading}</bdi></H>}
+              <RichText html={s.body} className="nv-fgb__body" />
+              {s.linkLabel.trim() && s.link.trim() && (
+                <a className="nv-fgb__link" href={s.link}>
+                  <bdi>{s.linkLabel}</bdi>
+                </a>
+              )}
+            </div>
+          </div>
+        </li>
+      )
+    }
+    const content =
+      b.type === 'heading' ? <HeadingBlock {...resolveSettings(headingSchema, { size: 'small', ...b.settings }).settings} /> :
+      b.type === 'text' ? <TextBlock {...resolveSettings(textSchema, b.settings).settings} /> :
+      b.type === 'button' ? <ButtonBlock {...resolveSettings(buttonSchema, b.settings).settings} /> :
+      b.type === 'icon' ? <IconBlock {...resolveSettings(iconSchema, b.settings).settings} /> :
+      <ImageBlock {...resolveSettings(imageSchema, b.settings).settings} image={(b as { image?: NovaImage | null }).image ?? null} />
+    return (
+      <li key={i} className="nv-fgb__tile" data-lead={lead ? '' : undefined} data-bg={b.type === 'image' ? 'image' : blockBackground === 'image' ? 'surface-secondary' : blockBackground} data-kind={b.type}>
+        <div className="nv-fgb__content" data-nv-surface={blockBackground === 'primary' && b.type !== 'image' ? 'inverse' : undefined}>
+          {content}
+        </div>
+      </li>
+    )
+  }
+
+  return (
+    <Shell props={props} type="feature-grid-blocks" width={sectionWidth} className="nv-fgb" data-preset={layout} data-row={rowHeight}>
+      <SectionHead eyebrow={eyebrow} heading={heading} description={description} headerSize={headerSize} align={contentAlignment} />
+      <ul className={sxJoin("nv-fgb__grid", sx({ '--nv-cols': columns } as CSSProperties))}>
+        {tiles.map(tile)}
+      </ul>
+    </Shell>
+  )
+}

package/templates/nova/src/sections/FeatureGridBlocks/index.ts

@@ -0,0 +1,35 @@
+import { defineSection, imageFor, resolveSettings } from '@tanqory/theme-kit'
+import { columnsOf } from '../data'
+import { FeatureGridBlock, FeatureGridBlocks } from './FeatureGridBlocks'
+import { presets } from './presets'
+import { featureGridBlocksSchema } from './schema'
+import { iconSchema } from '../../components/content/blocks/Icon'
+import { headingSchema } from '../../components/content/blocks/Heading'
+import { buttonSchema } from '../../components/content/blocks/Button'
+import { imageSchema } from '../../components/content/blocks/Image'
+import { textSchema } from '../../components/content/blocks/Text'
+import { columnSchema } from '../../components/content/blocks/Column'
+
+export default defineSection({
+  id: 'feature-grid-blocks',
+  schema: featureGridBlocksSchema,
+  blocks: [iconSchema, headingSchema, buttonSchema, imageSchema, textSchema, columnSchema],
+  component: FeatureGridBlocks,
+  category: 'content',
+  zone: 'main',
+  title: 'Feature grid (blocks)',
+  description: 'A grid of features you compose from blocks.',
+  icon: 'star',
+  presets,
+  data: (node, store) => {
+      const r = resolveSettings(featureGridBlocksSchema, node.settings)
+      const issues = [...r.issues]
+      const blocks: FeatureGridBlock[] = (node.blocks ?? []).flatMap((b): FeatureGridBlock[] => {
+        if (b.type === 'column') return [{ type: 'column', ...columnsOf(store, [b], issues)[0] }]
+        if (b.type === 'image') return [{ type: 'image', settings: b.settings, image: imageFor(store, b.settings?.image as string | undefined) }]
+        if (b.type === 'heading' || b.type === 'text' || b.type === 'button' || b.type === 'icon') return [{ type: b.type, settings: b.settings }]
+        return []
+      })
+      return { ...r.settings, blocks }
+  },
+})

package/templates/nova/src/sections/FeatureGridBlocks/presets.ts

@@ -0,0 +1,8 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Feature story with one lead
+  {"name": "fgb-bento", "label": "Bento features", "settings": {"preset": "1+4", "rowHeight": "medium", "blockBackground": "surface-secondary"}, "blocks": []},
+  // Two-by-two comparison
+  {"name": "fgb-pairs", "label": "Pairs", "settings": {"preset": "2+2", "rowHeight": "small"}, "blocks": []},
+]

package/templates/nova/src/sections/FeatureGridBlocks/schema.ts

@@ -0,0 +1,35 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12D · 04 feature-grid-blocks — a bento grid for feature stories: one lead
+ * tile (1+4 · 1+2) or equal tiles (2+2 · 3-equal). Each block is a tile:
+ * column blocks (icon · title · body · link), or a heading / text / button /
+ * image / icon block. The lead tile carries its column image under a 62%
+ * floor with white text (and may play a muted video, image = poster); other
+ * tiles take blockBackground — muted · inverse, or `image`: their own column
+ * image under the same floor.
+ * 1 column below 640, 2 at 640–1023; row heights 160 / 220 / 300 (auto at 390).
+ */
+export const featureGridBlocksSchema = defineSchema(
+  { kind: 'section', name: 'feature-grid-blocks', family: '12D', blocks: ['heading', 'text', 'button', 'image', 'icon', 'column'] },
+  {
+    columns: field.range(3, 2, 4, 1),
+    preset: field.select(['1+4', '2+2', '3-equal', '1+2'], '1+4'),
+    rowHeight: field.select(['small', 'medium', 'large'], 'medium'),
+    blockBackground: field.select(['surface-secondary', 'primary', 'image'], 'surface-secondary'),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    contentAlignment: shared.contentAlignment('left'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    spacingTop: shared.spacingTop('large'),
+    spacingBottom: shared.spacingBottom('large'),
+    background: shared.background('surface'),
+    heading: shared.heading(),
+    eyebrow: shared.eyebrow(),
+    description: shared.description(),
+    headerSize: shared.headerSize('medium'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)

package/templates/nova/src/sections/FeatureHighlights/FeatureHighlights.tsx

@@ -0,0 +1,56 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties } from 'react'
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { Icon, type IconName } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import { EmptySection, Shell } from '../../components/section/shell'
+import '../../components/section/shared.css'
+import '../../styles/sections/content.css'
+import { featureHighlightsSchema } from './schema'
+
+export type FeatureHighlightsSettings = SettingsOf<typeof featureHighlightsSchema>
+export type FeatureHighlightsProps = FeatureHighlightsSettings
+
+const ICONS = new Set(['truck', 'return', 'chat', 'shield', 'star', 'gift', 'leaf', 'clock', 'check', 'card', 'heart', 'globe', 'mail'])
+
+/** "icon: Title | detail" per line; an unknown icon word is shown as text. */
+export function parseFeatures(text: string): { icon?: IconName; title: string; detail?: string }[] {
+  return text
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const m = /^([a-z-]+)\s*:\s*(.+)$/i.exec(line)
+      const icon = m && ICONS.has(m[1].toLowerCase()) ? (m[1].toLowerCase() as IconName) : undefined
+      const rest = icon ? m![2] : line
+      const [title, detail] = rest.split('|').map((x) => x.trim())
+      return { icon, title, detail: detail || undefined }
+    })
+    .filter((f) => f.title)
+}
+
+export function FeatureHighlights(props: FeatureHighlightsProps): JSX.Element | null {
+  const { features, columns, iconStyle, textAlignment, sectionWidth, contentWidth } = props
+  const { strings } = useNova()
+  const items = parseFeatures(features)
+  if (!items.length) return <EmptySection props={props} type="feature-highlights" width={sectionWidth} title={strings.editorAddFeatures} hint={strings.editorAddFeaturesHint} />
+  return (
+    <Shell props={props} type="feature-highlights" width={sectionWidth} className="nv-highlights" data-icon-style={iconStyle} data-align-text={textAlignment} data-measure={contentWidth}>
+      <ul className={sxJoin("nv-highlights__list", sx({ '--nv-cols': Number(columns) } as CSSProperties))}>
+        {items.map((f, i) => (
+          <li key={i} className="nv-highlights__item">
+            {iconStyle !== 'none' && f.icon && (
+              <span className="nv-highlights__icon" aria-hidden>
+                <Icon name={f.icon} size="sm" />
+              </span>
+            )}
+            <span className="nv-highlights__text">
+              <span className="nv-highlights__title"><bdi>{f.title}</bdi></span>
+              {f.detail && <span className="nv-highlights__detail">{f.detail}</span>}
+            </span>
+          </li>
+        ))}
+      </ul>
+    </Shell>
+  )
+}

package/templates/nova/src/sections/FeatureHighlights/index.ts

@@ -0,0 +1,20 @@
+import { defineSection, resolveSettings } from '@tanqory/theme-kit'
+import { FeatureHighlights } from './FeatureHighlights'
+import { presets } from './presets'
+import { featureHighlightsSchema } from './schema'
+
+export default defineSection({
+  id: 'feature-highlights',
+  schema: featureHighlightsSchema,
+  component: FeatureHighlights,
+  category: 'content',
+  zone: 'main',
+  title: 'Feature Highlights',
+  description: 'A row of three or four short points, each a title and a detail.',
+  icon: 'star',
+  presets,
+  data: (node) => {
+      const r = resolveSettings(featureHighlightsSchema, node.settings)
+      return r.settings
+  },
+})

package/templates/nova/src/sections/FeatureHighlights/presets.ts

@@ -0,0 +1,6 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Compact USP row
+  {"name": "fh-service-strip", "label": "Service strip", "settings": {"columns": "4", "iconStyle": "outline", "textAlignment": "left"}, "blocks": []},
+]

package/templates/nova/src/sections/FeatureHighlights/schema.ts

@@ -0,0 +1,27 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12D · 05 feature-highlights — the compact one-line service strip (3–4 items,
+ * no paragraphs, no header). `features` is a textarea until a structured list
+ * field exists (NEEDS NEW FIELD TYPE): one per line, "icon: Title | detail".
+ * 2 × 2 at 390. Do not use beside trust-badges with the same content.
+ */
+export const featureHighlightsSchema = defineSchema(
+  { kind: 'section', name: 'feature-highlights', family: '12D' },
+  {
+    features: field.textarea(''),
+    columns: field.select(['3', '4'], '4'),
+    iconStyle: field.select(['none', 'outline', 'filled-circle'], 'none'),
+    textAlignment: field.select(['left', 'center'], 'left'),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    contentWidth: shared.contentWidth('standard'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    spacingTop: shared.spacingTop('medium'),
+    spacingBottom: shared.spacingBottom('medium'),
+    background: shared.background('surface'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)

package/templates/nova/src/sections/FeaturedCollection/FeaturedCollection.tsx

@@ -0,0 +1,67 @@
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { CardRow } from '../../components/content/CardRow'
+import { ProductCard, type CardRatio } from '../../components/commerce/ProductCard'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import { EditorFrame } from '../../components/states/EditorFrame'
+import type { Collection } from '@tanqory/theme-kit'
+import { sectionRootProps } from '../../components/section/shared'
+import '../../components/section/shared.css'
+import '../../styles/sections/commerce.css'
+import { featuredCollectionSchema } from './schema'
+
+export type FeaturedCollectionSettings = SettingsOf<typeof featuredCollectionSchema>
+export interface FeaturedCollectionProps extends FeaturedCollectionSettings {
+  collection?: Collection | null
+  /** The saved collection exists but is unpublished (adapter). */
+  collectionUnavailable?: boolean
+  /** The first row on the page: images load eagerly. */
+  priority?: boolean
+}
+
+export function FeaturedCollection(props: FeaturedCollectionProps): JSX.Element | null {
+  const { subheading, productsToShow, layout, columns, mobileColumns, carouselOnMobile, showNavigation, cardImageRatio, showViewAll, headerAlignment, sectionWidth, heading, eyebrow, description, headerSize, collection, collectionUnavailable, priority } = props
+  const { mode, strings } = useNova()
+  const products = (collection?.products ?? []).slice(0, productsToShow)
+  if (!products.length) {
+    if (mode !== 'editor') return null
+    return (
+      <section {...sectionRootProps(props, 'featured-collection')} className="nv-merch">
+        <div className="nv-section-container" data-width={sectionWidth}>
+          <EditorFrame
+            section="featured-collection"
+            title={collection && !collectionUnavailable ? strings.editorNoProducts : strings.editorChooseCollection}
+            hint={collection && !collectionUnavailable ? strings.editorNoProductsHint : strings.editorChooseCollectionHint}
+          />
+        </div>
+      </section>
+    )
+  }
+  const total = collection?.productsCount ?? products.length
+  const viewAll = showViewAll && collection && total > products.length ? { label: total ? fmt(strings.viewAllCount, { count: total }) : strings.viewAll, href: collection.url } : null
+  const ratio: CardRatio | undefined = cardImageRatio === 'inherit' ? undefined : cardImageRatio
+  return (
+    <section {...sectionRootProps(props, 'featured-collection')} className="nv-merch">
+      <div className="nv-section-container" data-width={sectionWidth}>
+        <CardRow
+          eyebrow={eyebrow || subheading}
+          heading={heading}
+          description={description}
+          headerSize={headerSize}
+          align={headerAlignment}
+          viewAll={viewAll}
+          layout={layout}
+          columns={columns}
+          mobileColumns={Number(mobileColumns) as 1 | 2}
+          carouselOnMobile={carouselOnMobile}
+          showNavigation={showNavigation}
+          label={heading || collection?.title}
+        >
+          {products.map((p, i) => (
+            <ProductCard key={p.id} product={p} ratio={ratio} priority={priority && i < columns} titleAs={heading ? 'h3' : 'h2'} />
+          ))}
+        </CardRow>
+      </div>
+    </section>
+  )
+}

package/templates/nova/src/sections/FeaturedCollection/index.ts

@@ -0,0 +1,21 @@
+import { collectionFor, defineSection, resolveSettings } from '@tanqory/theme-kit'
+import { FeaturedCollection } from './FeaturedCollection'
+import { presets } from './presets'
+import { featuredCollectionSchema } from './schema'
+
+export default defineSection({
+  id: 'featured-collection',
+  schema: featuredCollectionSchema,
+  component: FeaturedCollection,
+  category: 'commerce',
+  zone: 'main',
+  title: 'Featured collection',
+  description: 'A grid of products from one collection.',
+  icon: '▦',
+  presets,
+  data: (node, store) => {
+      const r = resolveSettings(featuredCollectionSchema, node.settings)
+      const { collection, unavailable } = collectionFor(store, r.handles.collection)
+      return { ...r.settings, collection, collectionUnavailable: unavailable }
+  },
+})

package/templates/nova/src/sections/FeaturedCollection/presets.ts

@@ -0,0 +1,10 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Latest products row
+  {"name": "fc-new-arrivals", "label": "New arrivals", "settings": {"layout": "grid", "columns": 4, "productsToShow": 4, "showViewAll": true}, "blocks": []},
+  // Longer curated row
+  {"name": "fc-carousel", "label": "Carousel", "settings": {"layout": "carousel", "columns": 4, "productsToShow": 8, "showNavigation": true, "carouselOnMobile": true}, "blocks": []},
+  // Small-item catalogues
+  {"name": "fc-bestsellers-dense", "label": "Dense bestsellers", "settings": {"layout": "grid", "columns": 5, "productsToShow": 10, "cardImageRatio": "square"}, "blocks": []},
+]

package/templates/nova/src/sections/FeaturedCollection/schema.ts

@@ -0,0 +1,39 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12C · 04 featured-collection — the home page's curated product row, grid or
+ * carousel, with the shared header (eyebrow · heading · View all · arrows).
+ *
+ *   grid shows exactly productsToShow; a carousel scrolls through them
+ *   fewer products than columns → cards keep the column width; View all is
+ *   hidden when everything is shown; "View all 48" when the count is known
+ *   empty / unpublished / missing collection → hidden (editor: setup frame)
+ */
+export const featuredCollectionSchema = defineSchema(
+  { kind: 'section', name: 'featured-collection', family: '12C' },
+  {
+    subheading: field.text('', { legacyHidden: true }),
+    collection: field.resource('collection', 'all'),
+    productsToShow: field.range(4, 2, 12, 1),
+    layout: field.select(['grid', 'carousel'], 'grid'),
+    columns: field.range(4, 2, 6, 1),
+    mobileColumns: field.select(['1', '2'], '2'),
+    carouselOnMobile: field.boolean(false),
+    showNavigation: field.boolean(true),
+    cardImageRatio: field.select(['inherit', 'adapt', 'square', 'portrait', 'landscape'], 'inherit'),
+    showViewAll: field.boolean(true),
+    headerAlignment: field.select(['left', 'center'], 'left'),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    spacingTop: shared.spacingTop('large'),
+    spacingBottom: shared.spacingBottom('large'),
+    background: shared.background('surface'),
+    heading: shared.heading(),
+    eyebrow: shared.eyebrow(),
+    description: shared.description(),
+    headerSize: shared.headerSize('medium'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)