create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/src/components/overlays/Sheet.tsx

@@ -0,0 +1,48 @@
+import { useId, useRef, type ReactNode } from 'react'
+import { IconButton } from '../base/IconButton'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import { TEXT_FIELD, inertWhen, useDialog } from './use-dialog'
+import './Sheet.css'
+
+/**
+ * Nova 13 · 00 Sheet — the phone surface: from the bottom, radius 16 top,
+ * ≤ 90% height, a decorative grabber, header 56 with Close. Popovers and
+ * menus become a sheet at 390 ("adapt, don't shrink"). Slide up 240ms; fade
+ * only under reduced motion. Modal: focus trapped, Esc and the scrim close.
+ */
+export interface SheetProps {
+  open: boolean
+  onClose: () => void
+  title: string
+  /** The title is merchant text (a page's own title): isolated in <bdi> so it keeps its own direction. Theme strings leave it off. */
+  isolateTitle?: boolean
+  children: ReactNode
+  footer?: ReactNode
+  /** The sheet body scrolls inside; this caps it lower (popup ≤ 70%). */
+  maxHeight?: '90' | '70'
+}
+
+export function Sheet({ open, onClose, title, children, footer, maxHeight = '90', isolateTitle }: SheetProps): JSX.Element {
+  const panel = useRef<HTMLDivElement>(null)
+  const { strings } = useNova()
+  const titleId = useId()
+  // Nova 13 focus rule: the first field, else the title.
+  useDialog(open, onClose, panel, () => panel.current?.querySelector<HTMLElement>(`.nv-sheet__body ${TEXT_FIELD}`) ?? panel.current?.querySelector<HTMLElement>('[data-dialog-title]'))
+  return (
+    <div className="nv-overlay nv-sheet-layer" data-open={open ? '' : undefined} {...inertWhen(!open)} aria-hidden={open ? undefined : true}>
+      <div className="nv-overlay__scrim" onClick={onClose} aria-hidden />
+      <div ref={panel} className="nv-sheet" data-max={maxHeight} role="dialog" aria-modal="true" aria-labelledby={titleId} tabIndex={-1}>
+        <span className="nv-sheet__grabber" aria-hidden />
+        <div className="nv-sheet__head">
+          <h2 className="nv-sheet__title" id={titleId} tabIndex={-1} data-dialog-title="">
+            {isolateTitle ? <bdi>{title}</bdi> : title}
+          </h2>
+          <IconButton icon="close" label={fmt(strings.closeNamed, { name: title })} onClick={onClose} className="nv-sheet__close" />
+        </div>
+        <div className="nv-sheet__body">{children}</div>
+        {footer && <div className="nv-sheet__foot">{footer}</div>}
+      </div>
+    </div>
+  )
+}

package/templates/nova/src/components/overlays/SizeGuide.css

@@ -0,0 +1,8 @@
+.nv-size-guide { display: grid; gap: var(--space-4); padding-block: var(--space-2); }
+.nv-size-guide__units { display: inline-flex; justify-self: start; padding: 3px; border-radius: var(--radius-md); background: var(--color-bg-muted); }
+.nv-size-guide__units button { min-width: 4.5rem; min-height: 36px; padding: 0 var(--space-3); border: 0; border-radius: calc(var(--radius-md) - 2px); background: none; color: var(--color-fg-muted); font: inherit; font-size: 0.875rem; cursor: pointer; }
+.nv-size-guide__units button[aria-pressed='true'] { background: var(--color-bg); color: var(--color-fg); font-weight: var(--weight-medium); box-shadow: 0 1px 2px rgba(17, 17, 17, 0.08); }
+.nv-size-guide__prose { font-size: 0.9375rem; }
+.nv-size-guide__prose table { font-size: 0.875rem; }
+.nv-size-guide__prose tr[data-selected] > * { background: var(--color-bg-muted); font-weight: var(--weight-medium); }
+.nv-size-guide__note { color: var(--color-fg-muted); font-size: var(--type-caption); }

package/templates/nova/src/components/overlays/SizeGuide.tsx

@@ -0,0 +1,74 @@
+import { useEffect, useRef, useState } from 'react'
+import { LongForm } from '../content/LongForm'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import { PHONE_QUERY, useMediaQuery } from '../../styles/viewport'
+import { Drawer } from './Drawer'
+import { Sheet } from './Sheet'
+import './SizeGuide.css'
+
+export interface SizeGuideProps {
+  open: boolean
+  onClose: () => void
+  title: string
+  /** The guide: page-body prose (12C sizeGuidePage) or the picker's richtext. */
+  html: string
+  /** The same table in inches, when the merchant provides both — then a cm / in toggle shows. */
+  htmlInches?: string
+  /** The selected size ("Queen"): its table row is highlighted. */
+  selected?: string
+}
+
+/**
+ * Nova 13 · 7 size guide — an end-side drawer 480 so the product stays
+ * visible (a 90% sheet on phone), page-body prose with tables that scroll
+ * sideways and the selected variant's row highlighted. The cm / in toggle
+ * shows only when the merchant provides both tables. Structured size tables
+ * (auto unit conversion) are a NEEDS NEW FIELD TYPE.
+ */
+export function SizeGuide({ open, onClose, title, html, htmlInches, selected }: SizeGuideProps): JSX.Element {
+  const { strings } = useNova()
+  const phone = useMediaQuery(PHONE_QUERY)
+  const [unit, setUnit] = useState<'cm' | 'in'>('cm')
+  const [marked, setMarked] = useState(false)
+  const body = useRef<HTMLDivElement>(null)
+  const shown = unit === 'in' && htmlInches ? htmlInches : html
+  // Highlight the row whose first cell is the selected size (real table markup from the prose system).
+  useEffect(() => {
+    const root = body.current
+    if (!root) return
+    let hit = false
+    root.querySelectorAll('tr').forEach((tr) => {
+      const first = tr.querySelector('th, td')?.textContent?.trim().toLowerCase()
+      const on = Boolean(selected && first === selected.trim().toLowerCase())
+      tr.toggleAttribute('data-selected', on)
+      if (on) hit = true
+    })
+    setMarked(hit)
+  }, [shown, selected, open, phone])
+
+  const content = (
+    <div ref={body} className="nv-size-guide">
+      {htmlInches && (
+        <div className="nv-size-guide__units" role="group" aria-label={strings.units}>
+          {(['cm', 'in'] as const).map((u) => (
+            <button key={u} type="button" aria-pressed={unit === u} onClick={() => setUnit(u)}>
+              {u}
+            </button>
+          ))}
+        </div>
+      )}
+      <LongForm html={shown} measure="narrow" className="nv-size-guide__prose" />
+      {marked && selected && <p className="nv-size-guide__note">{fmt(strings.selectedSizeNote, { size: selected })}</p>}
+    </div>
+  )
+  return phone ? (
+    <Sheet open={open} onClose={onClose} title={title} isolateTitle>
+      {content}
+    </Sheet>
+  ) : (
+    <Drawer open={open} onClose={onClose} side="end" title={title} width={480} isolateTitle>
+      {content}
+    </Drawer>
+  )
+}

package/templates/nova/src/components/overlays/Toast.css

@@ -0,0 +1,20 @@
+/* Nova 13 · 11 Toast — bottom-start desktop, max 3, newest on top. */
+.nv-toasts { position: fixed; inset-block-end: var(--space-6); inset-inline-start: var(--space-6); z-index: var(--z-toast); width: min(380px, calc(100vw - 2 * var(--space-6))); pointer-events: none; }
+.nv-toasts__list { display: grid; gap: var(--space-2); list-style: none; margin: 0; padding: 0; }
+.nv-toast { display: flex; align-items: flex-start; gap: var(--space-3); padding: var(--space-3) var(--space-2) var(--space-3) var(--space-4); border: var(--overlay-hairline); border-radius: var(--overlay-radius-toast); background: var(--color-bg-elevated); color: var(--color-fg); box-shadow: var(--overlay-toast-shadow); font-size: 0.875rem; line-height: 1.4; pointer-events: auto; animation: nv-toast-in var(--duration-base) var(--ease-standard); }
+@keyframes nv-toast-in { from { opacity: 0; transform: translateY(8px); } }
+.nv-toast__icon { flex: none; margin-block-start: 1px; }
+.nv-toast[data-tone='success'] .nv-toast__icon { color: var(--color-success); }
+.nv-toast[data-tone='info'] .nv-toast__icon { color: var(--color-info); }
+.nv-toast[data-tone='warning'] .nv-toast__icon { color: var(--color-warning-ink); }
+.nv-toast[data-tone='error'] .nv-toast__icon { color: var(--color-danger); }
+.nv-toast__text { flex: 1; min-width: 0; }
+.nv-toast__title { font-weight: var(--weight-medium); }
+.nv-toast__desc { color: var(--color-fg-muted); }
+.nv-toast__action { flex: none; align-self: center; min-height: 24px; padding: 0; border: 0; background: none; color: var(--color-fg); font: inherit; font-weight: var(--weight-medium); text-decoration: underline; text-underline-offset: var(--underline-offset); white-space: nowrap; cursor: pointer; }
+.nv-toast__close { flex: none; align-self: center; width: 32px; height: 32px; }
+@media (max-width: 639.98px) {
+  /* Above sticky bars (Checkout / Add to cart): hosts set --nv-toast-lift to the bar height. */
+  .nv-toasts { inset-inline: 12px; inset-block-end: calc(12px + var(--nv-toast-lift, 0px) + env(safe-area-inset-bottom)); width: auto; }
+}
+@media (prefers-reduced-motion: reduce) { .nv-toast { animation-name: nv-fade-in; } @keyframes nv-fade-in { from { opacity: 0; } } }

package/templates/nova/src/components/overlays/Toast.tsx

@@ -0,0 +1,164 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { IconButton } from "../base/IconButton";
+import { Icon } from "../../styles/Icon";
+import { useNova } from "../../styles/NovaProvider";
+import { fmt } from "../../styles/strings";
+import { usePageHidden } from "../../styles/motion";
+import { TONE_ICON, type FeedbackTone } from "../states/Alert";
+import "./Toast.css";
+
+export interface ToastData {
+  id: string;
+  tone: FeedbackTone;
+  title: string;
+  description?: string;
+  /** One follow-up ("View cart", "Undo", "Try again"). */
+  action?: { label: string; href?: string; onClick?: () => void };
+}
+
+/** Success and info leave after 4 s (paused on hover / focus); warnings after 6 s; errors stay until dismissed. */
+export const TOAST_MS: Record<FeedbackTone, number | null> = {
+  success: 4000,
+  info: 4000,
+  warning: 6000,
+  error: null,
+};
+/** Max 3 on screen, newest on top. */
+export const TOAST_MAX = 3;
+
+export function ToastItem({
+  toast: t,
+  onDismiss,
+  paused,
+}: {
+  toast: ToastData;
+  onDismiss: (id: string) => void;
+  paused?: boolean;
+}): JSX.Element {
+  const { strings } = useNova();
+  const [hold, setHold] = useState(false);
+  const hidden = usePageHidden();
+  const ms = TOAST_MS[t.tone];
+  useEffect(() => {
+    if (ms == null || hold || paused || hidden) return;
+    const timer = window.setTimeout(() => onDismiss(t.id), ms);
+    return () => window.clearTimeout(timer);
+  }, [ms, hold, paused, hidden, onDismiss, t.id]);
+  return (
+    <li className="nv-toasts__item">
+      <div
+        className="nv-toast"
+        data-tone={t.tone}
+        role={t.tone === "error" ? "alert" : "status"}
+        onPointerEnter={() => setHold(true)}
+        onPointerLeave={() => setHold(false)}
+        onFocus={() => setHold(true)}
+        onBlur={() => setHold(false)}
+      >
+        <Icon name={TONE_ICON[t.tone]} size="sm" className="nv-toast__icon" />
+        <div className="nv-toast__text">
+          <p className="nv-toast__title">{t.title}</p>
+          {t.description && <p className="nv-toast__desc">{t.description}</p>}
+        </div>
+        {t.action &&
+          (t.action.href ? (
+            <a className="nv-toast__action" href={t.action.href}>
+              {t.action.label}
+            </a>
+          ) : (
+            <button
+              type="button"
+              className="nv-toast__action"
+              onClick={() => {
+                t.action?.onClick?.();
+                onDismiss(t.id);
+              }}
+            >
+              {t.action.label}
+            </button>
+          ))}
+        <IconButton
+          icon="close"
+          label={fmt(strings.dismissNamed, { name: t.title })}
+          onClick={() => onDismiss(t.id)}
+          className="nv-toast__close"
+        />
+      </div>
+    </li>
+  );
+}
+
+/** The toast stack: bottom-start on desktop; full width minus 12 at 390, above sticky bars (--nv-toast-lift). */
+export function ToastStack({
+  toasts,
+  onDismiss,
+}: {
+  toasts: readonly ToastData[];
+  onDismiss: (id: string) => void;
+}): JSX.Element {
+  const { strings } = useNova();
+  return (
+    <section className="nv-toasts" aria-label={strings.notifications}>
+      <ol className="nv-toasts__list">
+        {toasts.slice(0, TOAST_MAX).map((t) => (
+          <ToastItem key={t.id} toast={t} onDismiss={onDismiss} />
+        ))}
+      </ol>
+    </section>
+  );
+}
+
+interface ToastApi {
+  show: (toast: Omit<ToastData, "id"> & { id?: string }) => string;
+  dismiss: (id: string) => void;
+}
+const ToastContext = createContext<ToastApi | null>(null);
+
+/**
+ * Nova 13 · 11 Toast — confirms, never interrupts: icon + title (+ text,
+ * + one action), radius 10, the toast shadow. Newest on top, max 3.
+ * Status toasts are polite; errors are assertive and stay.
+ */
+export function ToastProvider({
+  children,
+  initial = [],
+}: {
+  children: ReactNode;
+  initial?: ToastData[];
+}): JSX.Element {
+  const [toasts, setToasts] = useState<ToastData[]>(initial);
+  const seq = useRef(0);
+  const dismiss = useCallback(
+    (id: string) => setToasts((all) => all.filter((t) => t.id !== id)),
+    [],
+  );
+  const show = useCallback<ToastApi["show"]>((t) => {
+    const id = t.id ?? `toast-${++seq.current}`;
+    setToasts((all) =>
+      [{ ...t, id }, ...all.filter((x) => x.id !== id)].slice(0, TOAST_MAX),
+    );
+    return id;
+  }, []);
+  const api = useMemo(() => ({ show, dismiss }), [show, dismiss]);
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      <ToastStack toasts={toasts} onDismiss={dismiss} />
+    </ToastContext.Provider>
+  );
+}
+
+export function useToast(): ToastApi {
+  const api = useContext(ToastContext);
+  if (!api) throw new Error("useToast needs a <ToastProvider>");
+  return api;
+}

package/templates/nova/src/components/overlays/Tooltip.css

@@ -0,0 +1,6 @@
+.nv-tooltip-wrap { position: relative; display: inline-flex; }
+.nv-tooltip { position: absolute; inset-block-end: calc(100% + 8px); inset-inline-start: 50%; z-index: var(--z-popover); width: max-content; max-width: 240px; padding: var(--space-1) var(--space-2); border-radius: 6px; background: var(--color-bg-inverse); color: var(--color-fg-inverse); font-size: 0.78125rem; line-height: 1.4; font-weight: var(--weight-medium); text-align: center; pointer-events: none; transform: translateX(calc(-50% + var(--nv-tip-shift, 0px))); visibility: hidden; opacity: 0; transition: opacity var(--overlay-popover-in) var(--ease-standard), visibility 0s linear var(--overlay-popover-in); }
+[dir='rtl'] .nv-tooltip { transform: translateX(calc(50% + var(--nv-tip-shift, 0px))); }
+.nv-tooltip::after { content: ''; position: absolute; inset-block-start: 100%; inset-inline-start: 50%; margin-inline-start: calc(-5px - var(--nv-tip-shift, 0px)); border: 5px solid transparent; border-block-start-color: var(--color-bg-inverse); }
+.nv-tooltip[data-shown] { visibility: visible; opacity: 1; transition: opacity var(--overlay-popover-in) var(--ease-standard); }
+@media (prefers-reduced-motion: reduce) { .nv-tooltip { transition: none; } }

package/templates/nova/src/components/overlays/Tooltip.tsx

@@ -0,0 +1,59 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { cloneElement, useEffect, useId, useLayoutEffect, useRef, useState, type CSSProperties, type ReactElement } from 'react'
+import './Tooltip.css'
+
+/**
+ * Nova 13 · 16 Tooltip — a short label for an icon or a term: 400ms after
+ * hover, at once on focus, a tap toggles it on touch; Esc hides it. Max 240,
+ * inverse surface, above the trigger. Never essential: the page works
+ * without it (the trigger keeps its own accessible name).
+ */
+export function Tooltip({ content, children }: { content: string; children: ReactElement }): JSX.Element {
+  const id = useId()
+  const [shown, setShown] = useState(false)
+  const timer = useRef<number>()
+  const tip = useRef<HTMLSpanElement>(null)
+  const [shift, setShift] = useState(0)
+  // Keep the tip inside the viewport (8px from an edge); the arrow stays on the trigger.
+  useLayoutEffect(() => {
+    if (!shown || !tip.current) return setShift(0)
+    const r = tip.current.getBoundingClientRect()
+    const left = r.left - shift
+    const right = r.right - shift
+    setShift(left < 8 ? 8 - left : right > window.innerWidth - 8 ? window.innerWidth - 8 - right : 0)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [shown, content])
+  const clear = () => window.clearTimeout(timer.current)
+  useEffect(() => {
+    if (!shown) return
+    const onKey = (e: KeyboardEvent) => e.key === 'Escape' && setShown(false)
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [shown])
+  useEffect(() => clear, [])
+  const trigger = cloneElement(children as ReactElement<Record<string, unknown>>, {
+    'aria-describedby': id,
+    onPointerEnter: (e: PointerEvent) => {
+      if (e.pointerType === 'touch') return
+      clear()
+      timer.current = window.setTimeout(() => setShown(true), 400)
+    },
+    onPointerLeave: () => {
+      clear()
+      setShown(false)
+    },
+    onPointerDown: (e: PointerEvent) => {
+      if (e.pointerType === 'touch') setShown((s) => !s)
+    },
+    onFocus: () => setShown(true),
+    onBlur: () => setShown(false),
+  })
+  return (
+    <span className="nv-tooltip-wrap">
+      {trigger}
+      <span ref={tip} id={id} role="tooltip" className={sxJoin("nv-tooltip", sx({ '--nv-tip-shift': `${shift}px` } as CSSProperties))} data-shown={shown ? '' : undefined}>
+        {content}
+      </span>
+    </span>
+  )
+}

package/templates/nova/src/components/overlays/use-dialog.ts

@@ -0,0 +1,74 @@
+import { useEffect, useRef, type RefObject } from 'react'
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/**
+ * The modal-surface contract shared by Drawer and Modal (Nova 02 / 13):
+ *   - on open: remember the trigger, move focus inside (first focusable, or
+ *     `initialFocus`), lock page scroll
+ *   - Tab / Shift+Tab cycle inside the panel; Esc closes
+ *   - on close: focus returns to the trigger
+ */
+let scrollLocks = 0
+
+export function useDialog(open: boolean, onClose: () => void, panel: RefObject<HTMLElement>, initialFocus?: RefObject<HTMLElement> | (() => HTMLElement | null | undefined)): void {
+  const trigger = useRef<HTMLElement | null>(null)
+  const close = useRef(onClose)
+  close.current = onClose
+  // Callers pass a fresh function each render: read it through a ref so a re-render while open
+  // (typing in a field, drilling into a menu level) never re-runs the open / focus effect.
+  const focusFirst = useRef(initialFocus)
+  focusFirst.current = initialFocus
+
+  useEffect(() => {
+    if (!open || typeof document === 'undefined') return
+    trigger.current = document.activeElement as HTMLElement | null
+    // A class, not `style.overflow`: the platform CSP forbids style attributes (no 'unsafe-inline').
+    // Counted, so nested dialogs release the page only when the last one closes.
+    scrollLocks++
+    document.documentElement.classList.add('nv-scroll-lock')
+    const id = requestAnimationFrame(() => {
+      const want = focusFirst.current
+      const chosen = typeof want === 'function' ? want() : want?.current
+      const target = chosen ?? panel.current?.querySelector<HTMLElement>(FOCUSABLE) ?? panel.current
+      target?.focus()
+    })
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        close.current()
+        return
+      }
+      if (e.key !== 'Tab' || !panel.current) return
+      const items = [...panel.current.querySelectorAll<HTMLElement>(FOCUSABLE)].filter((el) => el.offsetParent !== null || el === document.activeElement)
+      if (!items.length) return
+      const first = items[0]
+      const last = items[items.length - 1]
+      if (e.shiftKey && (document.activeElement === first || !panel.current.contains(document.activeElement))) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    document.addEventListener('keydown', onKey)
+    return () => {
+      cancelAnimationFrame(id)
+      document.removeEventListener('keydown', onKey)
+      scrollLocks = Math.max(0, scrollLocks - 1)
+      if (scrollLocks === 0) document.documentElement.classList.remove('nv-scroll-lock')
+      const t = trigger.current
+      if (t && typeof t.focus === 'function' && t.isConnected) t.focus()
+    }
+  }, [open, panel])
+}
+
+/** Nova 13 first focus: a field you type into (not a toggle or a stepper) — else the title. */
+export const TEXT_FIELD = ':is(input:is([type=text], [type=email], [type=tel], [type=search], [type=password], [type=url], :not([type])):not([inputmode=numeric]), textarea, select):not([disabled])'
+
+/** React 18 has no `inert` prop type; this spreads the attribute. */
+export function inertWhen(closed: boolean): Record<string, string> {
+  return closed ? { inert: '' } : {}
+}

package/templates/nova/src/components/section/shared.css

@@ -0,0 +1,42 @@
+/* Shared Nova 12 section settings — one vocabulary, one set of rules.
+   Spacing: desktop 0 / 48 / 80 / 112 / 160 · 390: 0 / 32 / 48 / 64 / 88
+   (tokens --section-*), scaled by the global sectionSpacing setting. */
+/* Only sections that carry the shared spacing settings get this padding —
+   footer and divider own their rhythm (sharedApplicability: OVERRIDDEN). */
+[data-nv-section][data-space-top] { padding-top: calc(var(--nv-space-top, 0px) * var(--nv-section-scale, 1)); }
+[data-nv-section][data-space-bottom] { padding-bottom: calc(var(--nv-space-bottom, 0px) * var(--nv-section-scale, 1)); }
+[data-space-top='none'] { --nv-space-top: 0px; }
+[data-space-bottom='none'] { --nv-space-bottom: 0px; }
+[data-space-top='small'] { --nv-space-top: var(--section-sm); }
+[data-space-top='medium'] { --nv-space-top: var(--section-md); }
+[data-space-top='large'] { --nv-space-top: var(--section-lg); }
+[data-space-top='xl'] { --nv-space-top: var(--section-xl); }
+[data-space-bottom='small'] { --nv-space-bottom: var(--section-sm); }
+[data-space-bottom='medium'] { --nv-space-bottom: var(--section-md); }
+[data-space-bottom='large'] { --nv-space-bottom: var(--section-lg); }
+[data-space-bottom='xl'] { --nv-space-bottom: var(--section-xl); }
+
+/* Backgrounds — --color-bg / --color-bg-muted / --color-bg-inverse. */
+[data-nv-section][data-bg='surface'] { background: var(--color-bg); color: var(--color-fg); }
+[data-nv-section][data-bg='surface-secondary'] { background: var(--color-bg-muted); color: var(--color-fg); }
+[data-nv-section][data-bg='primary'] {
+  background: var(--color-bg-inverse);
+  color: var(--color-fg-inverse);
+  --color-border: var(--color-border-inverse);
+  --border-subtle: var(--border-width) solid var(--color-border-inverse);
+}
+[data-nv-surface='inverse'] { --color-fg-muted: color-mix(in srgb, var(--color-fg-inverse) 78%, var(--color-bg-inverse)); }
+
+[data-nv-section][data-align='center'] { text-align: center; }
+[data-nv-section][data-align='right'] { text-align: end; }
+@media (max-width: 639.98px) {
+  [data-nv-section][data-hide-mobile] { display: none; }
+  [data-nv-section][data-mobile-align='left'] { text-align: start; }
+  [data-nv-section][data-mobile-align='center'] { text-align: center; }
+}
+
+/* The section's content container — shared sectionWidth (standard 1280 · wide 1536 · full), page gutter inside. */
+.nv-section-container { width: 100%; margin-inline: auto; padding-inline: var(--page-gutter); }
+.nv-section-container[data-width='standard'] { max-width: calc(var(--container-standard) + 2 * var(--page-gutter)); }
+.nv-section-container[data-width='wide'] { max-width: calc(var(--container-wide) + 2 * var(--page-gutter)); }
+.nv-section-container[data-width='full'] { max-width: none; }

package/templates/nova/src/components/section/shared.ts

@@ -0,0 +1,120 @@
+import type { HTMLAttributes } from 'react'
+import { field } from '@tanqory/theme-kit'
+
+/**
+ * The Nova 12 shared vocabulary (12A · 00 "Shared Nova 12 vocabulary"). IDs are
+ * the persisted manifest IDs; each section records its OWN default (the
+ * contract's per-section rows), so these are factories, not constants.
+ */
+export const SECTION_WIDTH = ['standard', 'wide', 'full'] as const
+export const CONTENT_WIDTH = ['narrow', 'content', 'standard'] as const
+export const SPACING = ['none', 'small', 'medium', 'large', 'xl'] as const
+export const BACKGROUND = ['surface', 'surface-secondary', 'primary'] as const
+export const ALIGNMENT = ['left', 'center'] as const
+export const MOBILE_ALIGNMENT = ['inherit', 'left', 'center'] as const
+export const HEADER_SIZE = ['small', 'medium', 'large'] as const
+
+export type SectionWidth = (typeof SECTION_WIDTH)[number]
+export type ContentWidth = (typeof CONTENT_WIDTH)[number]
+export type Spacing = (typeof SPACING)[number]
+export type Background = (typeof BACKGROUND)[number]
+export type Alignment = (typeof ALIGNMENT)[number]
+export type MobileAlignment = (typeof MOBILE_ALIGNMENT)[number]
+export type HeaderSize = (typeof HEADER_SIZE)[number]
+
+export const shared = {
+  sectionWidth: (def: SectionWidth) => field.select(SECTION_WIDTH, def),
+  contentWidth: (def: ContentWidth) => field.select(CONTENT_WIDTH, def),
+  contentAlignment: (def: Alignment) => field.select(ALIGNMENT, def),
+  spacingTop: (def: Spacing) => field.select(SPACING, def),
+  spacingBottom: (def: Spacing) => field.select(SPACING, def),
+  background: (def: Background) => field.select(BACKGROUND, def),
+  headerSize: (def: HeaderSize) => field.select(HEADER_SIZE, def),
+  mobileContentAlignment: (def: MobileAlignment) => field.select(MOBILE_ALIGNMENT, def),
+  /** Shared copy settings (12A · 00 heading · eyebrow · description). */
+  heading: (def = '') => field.text(def),
+  eyebrow: () => field.text(''),
+  description: () => field.textarea(''),
+  hideOnMobile: () => field.boolean(false),
+  anchorId: () => field.text(''),
+  /** LEGACY-HIDDEN variants (breadcrumbs): saved values keep rendering; no control for new stores. */
+  hideOnMobileLegacy: () => field.boolean(false, { legacyHidden: true }),
+  anchorIdLegacy: () => field.text('', { legacyHidden: true }),
+}
+
+/**
+ * The shared settings as one set, with the editor group each sits in — what the
+ * platform publishes as `sharedAttributes` (a custom section folds them in).
+ */
+export const SHARED_SETTINGS = {
+  fields: {
+    sectionWidth: shared.sectionWidth('wide'),
+    contentWidth: shared.contentWidth('content'),
+    contentAlignment: shared.contentAlignment('left'),
+    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'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+  groups: {
+    sectionWidth: 'Layout',
+    contentWidth: 'Layout',
+    contentAlignment: 'Layout',
+    spacingTop: 'Spacing',
+    spacingBottom: 'Spacing',
+    background: 'Appearance',
+    headerSize: 'Appearance',
+    heading: 'Content',
+    eyebrow: 'Content',
+    description: 'Content',
+    mobileContentAlignment: 'Mobile',
+    hideOnMobile: 'Mobile',
+    anchorId: 'Advanced',
+  },
+  /** Copy a section places itself (heading block, …): never folded in automatically. */
+  contentSlots: ['heading', 'eyebrow', 'description'],
+}
+
+export interface SharedRootSettings {
+  sectionWidth?: SectionWidth
+  contentWidth?: ContentWidth
+  /** 'right' is hero / slide only (persisted text_alignment, 12B conflict 2). */
+  contentAlignment?: Alignment | 'right'
+  mobileContentAlignment?: MobileAlignment
+  spacingTop?: Spacing
+  spacingBottom?: Spacing
+  background?: Background
+  hideOnMobile?: boolean
+  anchorId?: string
+}
+
+/** Background → surface role the descendants branch on (buttons, badges, links). */
+export function surfaceOf(bg: Background | undefined): 'default' | 'muted' | 'inverse' {
+  return bg === 'primary' ? 'inverse' : bg === 'surface-secondary' ? 'muted' : 'default'
+}
+
+/**
+ * The section root's attributes for the shared settings: data-* the CSS
+ * branches on (sections/shared.css), the anchor id, and the surface role.
+ * Spread FIRST so a section's own attributes win.
+ */
+export function sectionRootProps(s: SharedRootSettings, type: string): HTMLAttributes<HTMLElement> & Record<`data-${string}`, string | undefined> {
+  const anchor = s.anchorId?.trim().replace(/[^A-Za-z0-9_-]/g, '-')
+  return {
+    id: anchor || undefined,
+    'data-nv-section': type,
+    'data-bg': s.background,
+    'data-nv-surface': s.background ? surfaceOf(s.background) : undefined,
+    'data-space-top': s.spacingTop,
+    'data-space-bottom': s.spacingBottom,
+    'data-align': s.contentAlignment,
+    'data-mobile-align': s.mobileContentAlignment && s.mobileContentAlignment !== 'inherit' ? s.mobileContentAlignment : undefined,
+    'data-hide-mobile': s.hideOnMobile ? '' : undefined,
+  }
+}

package/templates/nova/src/components/section/shell.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react'
+import { useNova } from '../../styles/NovaProvider'
+import { EditorFrame } from '../states/EditorFrame'
+import { sectionRootProps, type SharedRootSettings, type SectionWidth } from './shared'
+
+/**
+ * The frame every 12D section shares: the section root (shared settings as
+ * data-*), the sectionWidth container, and the "empty" rule — shoppers never
+ * see a placeholder; the editor sees why (Nova 14 setup frame).
+ */
+export function Shell({ props, type, width, className, children, ...data }: { props: SharedRootSettings; type: string; width: SectionWidth; className?: string; children: ReactNode } & Record<`data-${string}`, string | number | undefined>): JSX.Element {
+  return (
+    <section {...sectionRootProps(props, type)} className={['nv-content', className].filter(Boolean).join(' ')} {...data}>
+      <div className="nv-section-container" data-width={width}>
+        {children}
+      </div>
+    </section>
+  )
+}
+
+export function EmptySection({ props, type, width, title, hint }: { props: SharedRootSettings; type: string; width: SectionWidth; title: string; hint?: string }): JSX.Element | null {
+  const { mode } = useNova()
+  if (mode !== 'editor') return null
+  return (
+    <Shell props={props} type={type} width={width}>
+      <EditorFrame section={type} title={title} hint={hint} />
+    </Shell>
+  )
+}