create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/src/components/content/HeroCopy.tsx

@@ -0,0 +1,148 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties } from 'react'
+import { Button } from '../base/Button'
+import { RichText } from './RichText'
+import { useNova } from '../../styles/NovaProvider'
+import './HeroCopy.css'
+
+/**
+ * 12B · shared hero copy — eyebrow (13/500) → display heading → body (46ch)
+ * → at most two actions. Used by hero, slide, video-hero and collection-banner
+ * so every loud section speaks with one voice.
+ *
+ *   headerSize   small 48 · medium 72 · large 80 (390: 32 · 40 · 44), balanced,
+ *                never truncated; a heading over 12 words steps down one size.
+ *   onMedia      white text; primary becomes white, secondary a white outline.
+ *   secondary    'outline' on page layouts, 'link' on split / minimal and at 390
+ *                on media ('responsive').
+ */
+export type HeroHeaderSize = 'small' | 'medium' | 'large'
+export type HeroAlign = 'left' | 'center' | 'right'
+export type HeroTextWidth = 'narrow' | 'medium' | 'wide'
+
+export interface HeroAction {
+  label: string
+  link?: string
+}
+
+export interface HeroCopyProps {
+  eyebrow?: string
+  heading?: string
+  /** Merchant rich text (sanitised by the adapter). */
+  body?: string
+  primary?: HeroAction
+  secondary?: HeroAction
+  /** How the second action renders. */
+  secondaryStyle?: 'outline' | 'link' | 'responsive'
+  /** Primary goes full width at 390 (image layouts). */
+  blockOnPhone?: boolean
+  /** Two outline-weight buttons share one row at equal width at 390 (text-first). */
+  pairOnPhone?: boolean
+  headerSize?: HeroHeaderSize
+  /** Element level — one h1 per page; the page decides. */
+  level?: 1 | 2 | 3
+  align?: HeroAlign
+  textWidth?: HeroTextWidth
+  onMedia?: boolean
+  /** 'split': heading beside body + actions (text-first, left-aligned, from 1024). */
+  arrange?: 'stack' | 'split'
+  className?: string
+  style?: CSSProperties
+}
+
+const STEP_DOWN: Record<HeroHeaderSize, HeroHeaderSize> = { large: 'medium', medium: 'small', small: 'small' }
+
+/** Words in a heading — Thai has no spaces, so a long run counts by length. */
+function wordCount(s: string): number {
+  return s.trim().split(/\s+/).reduce((n, w) => n + Math.max(1, Math.ceil(w.length / 12)), 0)
+}
+
+export function heroHasBody(eyebrow?: string, body?: string): boolean {
+  return Boolean(eyebrow?.trim() || body?.replace(/<[^>]*>/g, '').trim())
+}
+
+export function HeroCopy({
+  eyebrow,
+  heading,
+  body,
+  primary,
+  secondary,
+  secondaryStyle = 'outline',
+  blockOnPhone,
+  pairOnPhone,
+  headerSize = 'medium',
+  level = 2,
+  align = 'left',
+  textWidth,
+  onMedia,
+  arrange = 'stack',
+  className,
+  style,
+}: HeroCopyProps): JSX.Element | null {
+  const { mode } = useNova()
+  const editor = mode === 'editor'
+  const H = `h${level}` as 'h2'
+  const size = heading && wordCount(heading) > 12 ? STEP_DOWN[headerSize] : headerSize
+  // An action needs a label AND a link: the storefront never renders a dead link.
+  // The editor keeps a labelled action without a link visible (disabled) so it can be finished.
+  const usable = (a?: HeroAction) => Boolean(a?.label.trim() && (a.link?.trim() || editor))
+  const hasPrimary = usable(primary)
+  const hasSecondary = usable(secondary)
+  if (!heading?.trim() && !eyebrow?.trim() && !body?.trim() && !hasPrimary && !hasSecondary) return null
+  return (
+    <div
+      className={sxJoin(['nv-hero-copy', className].filter(Boolean).join(' '), sx(style))}
+      data-align={align}
+      data-width={textWidth}
+      data-on-media={onMedia ? '' : undefined}
+      data-arrange={arrange === 'split' ? 'split' : undefined}
+      data-nv-surface={onMedia ? 'inverse' : undefined}
+    >
+      {eyebrow?.trim() && <p className="nv-hero-copy__eyebrow"><bdi>{eyebrow}</bdi></p>}
+      {heading?.trim() && (
+        <H className="nv-hero-copy__heading" data-size={size}>
+          <bdi>{heading}</bdi>
+        </H>
+      )}
+      {body?.trim() && <RichText html={body} className="nv-hero-copy__body" />}
+      {(hasPrimary || hasSecondary) && (
+        <div className="nv-hero-copy__actions" data-block-phone={blockOnPhone ? '' : undefined} data-pair-phone={pairOnPhone && hasPrimary && hasSecondary ? '' : undefined}>
+          {hasPrimary && (
+            <Action action={primary!} variant="primary" className="nv-hero-copy__primary" />
+          )}
+          {hasSecondary && (
+            <Action action={secondary!} variant={secondaryStyle === 'link' ? 'tertiary' : 'secondary'} className="nv-hero-copy__secondary" data-style={secondaryStyle} />
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** A link when it has a destination; in the editor, a disabled button until it does. */
+function Action({ action, ...rest }: { action: HeroAction; variant: 'primary' | 'secondary' | 'tertiary'; className: string; 'data-style'?: string }): JSX.Element {
+  const link = action.link?.trim()
+  return link ? (
+    <Button href={link} size="lg" {...rest}>
+      <bdi>{action.label}</bdi>
+    </Button>
+  ) : (
+    <Button size="lg" disabled {...rest}>
+      <bdi>{action.label}</bdi>
+    </Button>
+  )
+}
+
+/**
+ * The overlay floor (Nova 11 · B6, 12B · 00): the merchant picks a strength,
+ * the theme enforces a minimum wherever text sits on media — 45% for large
+ * text + buttons only, 62% once eyebrow or body text is on the image.
+ * `strength` is an overlay ID or a percentage (overlayOpacity).
+ */
+export const OVERLAY_STRENGTH = { none: 0, light: 0.3, medium: 0.45, strong: 0.62 } as const
+export type OverlayId = keyof typeof OVERLAY_STRENGTH
+
+export function scrimAlpha(strength: OverlayId | number, hasBody: boolean): number {
+  const chosen = typeof strength === 'number' ? strength / 100 : OVERLAY_STRENGTH[strength]
+  return Math.max(chosen, hasBody ? 0.62 : 0.45)
+}

package/templates/nova/src/components/content/HeroFrame.css

@@ -0,0 +1,75 @@
+/* 12B · 00 a frame of media with hero copy anchored on it — hero
+   (image-background / contained), slide, video-hero, collection-banner.
+   Height comes from the owner's --nv-hero-h (the one ladder). */
+/* A frame of media with copy anchored on it (hero image-background / contained,
+   slide, video-hero, collection-banner with image). */
+.nv-media-frame {
+  position: relative;
+  display: grid;
+  min-height: var(--nv-hero-h);
+  overflow: hidden;
+  isolation: isolate;
+  background: var(--color-media-bg);
+  color: var(--color-fg-inverse);
+}
+.nv-media-frame__scrim { position: absolute; inset: 0; z-index: var(--z-raised); pointer-events: none; }
+/* Centred copy: a flat overlay (text is mid-image). */
+.nv-media-frame[data-position='middle'] .nv-media-frame__scrim,
+.nv-media-frame[data-position='center'] .nv-media-frame__scrim { background: rgb(0 0 0 / var(--nv-scrim, 0.45)); }
+/* Moving video: an 18% base wash across the whole frame, plus the floor at the text. */
+.nv-media-frame[data-has-video]:not([data-position='middle'], [data-position='center']) .nv-media-frame__scrim { background: rgb(0 0 0 / var(--hero-video-wash)); }
+
+.nv-media-frame__anchor {
+  position: relative;
+  z-index: var(--z-raised);
+  display: grid;
+  align-content: end;
+  justify-items: start;
+  padding: var(--hero-inset-block) var(--hero-inset-inline);
+  pointer-events: none;
+}
+.nv-media-frame__anchor > * { pointer-events: auto; }
+.nv-media-frame[data-position='top'] .nv-media-frame__anchor { align-content: start; }
+.nv-media-frame:is([data-position='middle'], [data-position='center']) .nv-media-frame__anchor { align-content: center; }
+.nv-media-frame[data-align='center'] .nv-media-frame__anchor,
+.nv-media-frame[data-position='center'] .nv-media-frame__anchor { justify-items: center; }
+.nv-media-frame[data-align='right'] .nv-media-frame__anchor { justify-items: end; }
+
+/* The floor gradient starts at the text edge and grows with the text height. */
+.nv-media-frame__copy { position: relative; }
+.nv-media-frame:not([data-position='middle'], [data-position='center']) .nv-media-frame__copy::before {
+  content: '';
+  position: absolute;
+  z-index: -1;
+  inset-inline: -200vw;
+  inset-block-start: calc(-1 * var(--space-10));
+  inset-block-end: calc(-1 * var(--hero-inset-block));
+  background: linear-gradient(to top, rgb(0 0 0 / var(--nv-scrim, 0.45)) 0%, rgb(0 0 0 / var(--nv-scrim, 0.45)) calc(100% - var(--space-10)), rgb(0 0 0 / 0) 100%);
+  pointer-events: none;
+}
+.nv-media-frame[data-position='top'] .nv-media-frame__copy::before {
+  inset-block-start: calc(-1 * var(--hero-inset-block));
+  inset-block-end: calc(-1 * var(--space-10));
+  background: linear-gradient(to bottom, rgb(0 0 0 / var(--nv-scrim, 0.45)) 0%, rgb(0 0 0 / var(--nv-scrim, 0.45)) calc(100% - var(--space-10)), rgb(0 0 0 / 0) 100%);
+}
+/* A pause button sits beside the copy, never over it. */
+.nv-media-frame[data-has-video][data-align='right'] .nv-media-frame__anchor {
+  padding-inline-end: calc(var(--hero-inset-inline) + var(--touch-target) + var(--space-3));
+}
+
+/* 390: media is 4:5; copy anchors bottom unless middle; a video's pause sits beside the copy. */
+@media (max-width: 639.98px) {
+  .nv-media-frame { min-height: 0; aspect-ratio: 4 / 5; }
+  .nv-media-frame[data-position='top'] .nv-media-frame__anchor { align-content: end; }
+  .nv-media-frame[data-position='top'] .nv-media-frame__copy::before {
+    inset-block-start: calc(-1 * var(--space-10));
+    inset-block-end: calc(-1 * var(--hero-inset-block));
+    background: linear-gradient(to top, rgb(0 0 0 / var(--nv-scrim, 0.45)) 0%, rgb(0 0 0 / var(--nv-scrim, 0.45)) calc(100% - var(--space-10)), rgb(0 0 0 / 0) 100%);
+  }
+  .nv-media-frame[data-has-video] .nv-media-frame__anchor { padding-inline-end: calc(var(--hero-inset-inline) + var(--touch-target) + var(--space-3)); }
+}
+
+/* No media (a slide without image): the muted surface with ink text. */
+.nv-media-frame[data-empty] { background: var(--color-bg-muted); color: var(--color-fg); }
+/* Controls never overlap copy: reserve their row when they share the copy's edge. */
+.nv-media-frame[data-reserve] .nv-media-frame__anchor { padding-block-end: calc(var(--hero-inset-block) + var(--touch-target) + var(--space-5)); }

package/templates/nova/src/components/content/HeroFrame.tsx

@@ -0,0 +1,49 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties, ReactNode } from 'react'
+import './HeroFrame.css'
+
+/**
+ * 12B · 00 the shared "copy on media" frame: media layer → scrim → anchored
+ * copy. The anchor grid is position × alignment (hero / slide store
+ * top · middle · bottom × left · center · right; video-hero and
+ * collection-banner store bottom-start · center — same labels). Height is the
+ * owner's --nv-hero-h; 4:5 at 390.
+ *
+ *   scrim     the effective overlay (after the 45 / 62 floor), 0–1
+ *   middle / center → a flat overlay; otherwise a gradient from the text edge
+ *   that grows with the text height; moving video adds an 18% base wash.
+ */
+export interface HeroFrameProps {
+  position: 'top' | 'middle' | 'bottom' | 'bottom-start' | 'center'
+  align?: 'left' | 'center' | 'right'
+  scrim: number
+  media?: ReactNode
+  hasVideo?: boolean
+  /** No media: muted surface, ink text, no scrim. */
+  empty?: boolean
+  /** Reserve the control row under the copy. */
+  reserveControls?: boolean
+  /** The copy (render it with className="nv-media-frame__copy"). */
+  children?: ReactNode
+  /** Layers above the copy (slideshow controls). */
+  overlay?: ReactNode
+  className?: string
+}
+
+export function HeroFrame({ position, align = 'left', scrim, media, hasVideo, empty, reserveControls, children, overlay, className }: HeroFrameProps): JSX.Element {
+  return (
+    <div
+      className={sxJoin(['nv-media-frame', className].filter(Boolean).join(' '), sx({ '--nv-scrim': scrim } as CSSProperties))}
+      data-position={position}
+      data-align={align}
+      data-has-video={hasVideo ? '' : undefined}
+      data-empty={empty ? '' : undefined}
+      data-reserve={reserveControls ? '' : undefined}
+    >
+      {media}
+      {!empty && <div className="nv-media-frame__scrim" aria-hidden />}
+      <div className="nv-media-frame__anchor">{children}</div>
+      {overlay}
+    </div>
+  )
+}

package/templates/nova/src/components/content/HeroMedia.css

@@ -0,0 +1,40 @@
+/* 12B · shared hero media — fills its positioned parent. */
+.nv-hero-media {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  background: var(--color-media-bg);
+}
+.nv-hero-media picture { display: contents; }
+.nv-hero-media__img,
+.nv-hero-media__video {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: var(--nv-focal, 50% 50%);
+}
+.nv-hero-media__img { transition: opacity var(--duration-base) var(--ease-standard); }
+.nv-hero-media[aria-busy='true'] .nv-hero-media__img { opacity: 0; }
+.nv-hero-media[data-fit='contain'] { background: var(--color-bg-muted); }
+.nv-hero-media[data-fit='contain'] :is(.nv-hero-media__img, .nv-hero-media__video) { object-fit: contain; }
+.nv-hero-media[data-focal='top'] { --nv-focal: 50% 0%; }
+.nv-hero-media[data-focal='bottom'] { --nv-focal: 50% 100%; }
+.nv-hero-media[data-focal='left'] { --nv-focal: 0% 50%; }
+.nv-hero-media[data-focal='right'] { --nv-focal: 100% 50%; }
+
+/* The poster is the first paint; the video fades in only once it plays. */
+.nv-hero-media__video { opacity: 0; transition: opacity var(--duration-hero) var(--ease-standard); }
+.nv-hero-media[data-video='playing'] .nv-hero-media__video { opacity: 1; }
+
+/* Pause / play: 44px, bottom inline-end, above the scrim and the copy layer. */
+.nv-hero-media__control.nv-icon-btn {
+  position: absolute;
+  z-index: var(--z-raised);
+  inset-block-end: var(--nv-media-control-block, var(--hero-inset-block));
+  inset-inline-end: var(--nv-media-control-inline, var(--hero-inset-inline));
+  background: var(--color-media-control);
+  color: var(--color-fg-inverse);
+}
+.nv-hero-media__control.nv-icon-btn:hover { background: var(--color-media-control-hover); }

package/templates/nova/src/components/content/HeroMedia.tsx

@@ -0,0 +1,170 @@
+import { useEffect, useRef, useState } from 'react'
+import type { NovaImage, NovaVideo } from '@tanqory/theme-kit'
+import { IconButton } from '../base/IconButton'
+import { useNova } from '../../styles/NovaProvider'
+import { prefersLightMedia, useInView, useReducedMotion } from '../../styles/motion'
+import './HeroMedia.css'
+
+/**
+ * 12B · shared hero media — the picture behind or beside hero copy, used by
+ * hero, slide, video-hero and collection-banner.
+ *
+ *   image + mobileImage (<640) · cover | contain · focal point (object-position)
+ *   optional background video: muted, looped, playsinline; the image is the
+ *   POSTER and the first paint. The video fades in once it plays. Reduced
+ *   motion → poster + play button (never autoplays). Save-Data / 2G → poster
+ *   only. Failure → poster, controls hide. Out of view → paused.
+ *   A pause button (44px) is ALWAYS shown while a video can play (WCAG 2.2.2).
+ *
+ * Fills its positioned parent. Never fetches; the adapter resolves media.
+ */
+export type FocalPoint = 'center' | 'top' | 'bottom' | 'left' | 'right'
+
+export interface HeroMediaProps {
+  image?: NovaImage | null
+  /** Replaces `image` below 640px; falls back to it. */
+  mobileImage?: NovaImage | null
+  video?: NovaVideo | null
+  /** Replaces `video` below 640px; falls back to it. */
+  mobileVideo?: NovaVideo | null
+  fit?: 'cover' | 'contain'
+  focal?: FocalPoint
+  /** The first hero on the page loads eagerly; later slides lazily. */
+  priority?: boolean
+  /** Controlled pause — a slideshow's one pause button drives its video too. */
+  paused?: boolean
+  /** Render the pause / play button (default true). A slideshow renders its own. */
+  control?: boolean
+  onTogglePause?: (paused: boolean) => void
+  /** Fired each time the video completes a loop (slide timer waits for it). */
+  onLoop?: () => void
+  /** The image failed to load — the section falls back (hero → text only). */
+  onImageError?: () => void
+  className?: string
+}
+
+const PHONE = '(max-width: 639.98px)'
+
+export function HeroMedia({ image, mobileImage, video, mobileVideo, fit = 'cover', focal = 'center', priority, paused: controlled, control = true, onTogglePause, onLoop, onImageError, className }: HeroMediaProps): JSX.Element | null {
+  const { strings } = useNova()
+  const root = useRef<HTMLDivElement>(null)
+  const el = useRef<HTMLVideoElement>(null)
+  const reduced = useReducedMotion(root)
+  const inView = useInView(root)
+  const [light, setLight] = useState(false)
+  const [phone, setPhone] = useState(false)
+  // Keyed by src: a new image starts loading without an effect racing its load event.
+  const [img, setImg] = useState<{ src: string; state: 'loaded' | 'error' } | null>(null)
+  const [videoState, setVideoState] = useState<'idle' | 'playing' | 'failed'>('idle')
+  // The shopper's own choice; reduced motion starts paused (play is offered).
+  const [userPaused, setUserPaused] = useState<boolean | null>(null)
+  const lastTime = useRef(0)
+
+  useEffect(() => {
+    setLight(prefersLightMedia())
+    const mq = window.matchMedia?.(PHONE)
+    const read = () => setPhone(Boolean(mq?.matches))
+    read()
+    mq?.addEventListener?.('change', read)
+    return () => mq?.removeEventListener?.('change', read)
+  }, [])
+
+  const poster = image ?? video?.poster ?? null
+  const mobilePoster = mobileImage ?? (mobileVideo ? mobileVideo.poster : null) ?? null
+  // The phone file is chosen declaratively (<source media>), at load.
+  const clip = video ?? mobileVideo ?? null
+  const phoneClip = mobileVideo && mobileVideo.src !== clip?.src ? mobileVideo : null
+  const canPlay = Boolean(clip) && !light && videoState !== 'failed'
+  const paused = controlled ?? userPaused ?? reduced
+  const shouldPlay = canPlay && !paused && inView
+
+  useEffect(() => {
+    const v = el.current
+    if (!v) return
+    if (shouldPlay) {
+      const p = v.play?.()
+      if (p && typeof p.catch === 'function') p.catch(() => {})
+    } else v.pause?.()
+  }, [shouldPlay, clip?.src, phoneClip?.src])
+
+  useEffect(() => setVideoState('idle'), [clip?.src, phoneClip?.src])
+
+  if (!poster && !clip) return null
+  const imgState = img && img.src === poster?.src ? img.state : 'loading'
+  const setImgState = (state: 'loaded' | 'error') => poster && setImg({ src: poster.src, state })
+
+  const toggle = () => {
+    const next = !paused
+    if (controlled === undefined) setUserPaused(next)
+    onTogglePause?.(next)
+  }
+
+  return (
+    <div ref={root} className={['nv-hero-media', className].filter(Boolean).join(' ')} data-fit={fit} data-focal={focal} aria-busy={imgState === 'loading' ? true : undefined} data-video={videoState === 'playing' ? 'playing' : undefined}>
+      {poster && imgState !== 'error' && (
+        <picture>
+          {mobilePoster && <source media={PHONE} srcSet={mobilePoster.srcSet ?? mobilePoster.src} />}
+          <img
+            className="nv-hero-media__img"
+            src={poster.src}
+            srcSet={poster.srcSet}
+            sizes={poster.srcSet ? '100vw' : undefined}
+            alt={poster.alt ?? ''}
+            width={poster.width}
+            height={poster.height}
+            loading={priority ? 'eager' : 'lazy'}
+            // React 18 passes the lowercase attribute through.
+            {...({ fetchpriority: priority ? 'high' : undefined } as object)}
+            decoding="async"
+            onLoad={() => setImgState('loaded')}
+            onError={() => {
+              setImgState('error')
+              onImageError?.()
+            }}
+            ref={(el) => {
+              if (el?.complete && el.naturalWidth > 0 && imgState === 'loading') setImgState('loaded')
+            }}
+          />
+        </picture>
+      )}
+      {canPlay && clip && (
+        <video
+          ref={el}
+          key={`${phoneClip?.src ?? ''}|${clip.src}`}
+          className="nv-hero-media__video"
+          poster={(phone ? mobilePoster : null)?.src ?? poster?.src}
+          muted
+          loop
+          playsInline
+          autoPlay={shouldPlay}
+          preload={priority ? 'auto' : 'metadata'}
+          aria-hidden
+          tabIndex={-1}
+          onPlaying={() => setVideoState('playing')}
+          // A <source> whose media does not match fires "error" by spec, and React
+          // forwards it here: only a video with NO usable source has failed.
+          onError={() => window.setTimeout(() => {
+            const v = el.current
+            if (v && (v.error || v.networkState === 3 /* HTMLMediaElement.NETWORK_NO_SOURCE */)) setVideoState('failed')
+          }, 50)}
+          onTimeUpdate={(e) => {
+            const t = e.currentTarget.currentTime
+            if (t + 0.25 < lastTime.current) onLoop?.()
+            lastTime.current = t
+          }}
+        >
+          {phoneClip && <source src={phoneClip.src} media={PHONE} />}
+          <source src={clip.src} />
+        </video>
+      )}
+      {canPlay && control && (
+        <IconButton
+          className="nv-hero-media__control"
+          icon={paused ? 'play' : 'pause'}
+          label={paused ? strings.playVideo : strings.pauseVideo}
+          onClick={toggle}
+        />
+      )}
+    </div>
+  )
+}

package/templates/nova/src/components/content/LongForm.css

@@ -0,0 +1,40 @@
+/* 12E · 00 prose system. Text stays at the narrow measure; figures, tables and embeds break out to 960. */
+.nv-longform {
+  --nv-lf-text: var(--container-narrow);
+  --nv-lf-wide: var(--container-content);
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  justify-items: center;
+  font-size: var(--text-body-lg);
+  line-height: var(--leading-loose);
+  color: var(--color-fg);
+}
+.nv-longform[data-measure='content'] { --nv-lf-text: var(--container-content); }
+.nv-longform[data-measure='standard'] { --nv-lf-text: var(--container-standard); --nv-lf-wide: var(--container-standard); }
+.nv-longform > * { width: 100%; max-width: var(--nv-lf-text); margin: 0; }
+.nv-longform > :is(figure, .nv-longform__table, iframe, video, img) { max-width: var(--nv-lf-wide); }
+.nv-longform > * + * { margin-block-start: 1.25rem; }
+.nv-longform h2 { font-size: 1.75rem; line-height: 1.2; letter-spacing: var(--tracking-h2); font-weight: var(--weight-heading); margin-block-start: 2.5rem; scroll-margin-top: var(--space-8); }
+.nv-longform h3 { font-size: 1.3125rem; line-height: 1.3; font-weight: var(--weight-heading); margin-block-start: 1.75rem; }
+.nv-longform h4 { font-size: 0.9375rem; line-height: 1.4; font-weight: var(--weight-strong); margin-block-start: 1.25rem; }
+.nv-longform :is(h2, h3, h4) + * { margin-block-start: 0.75rem; }
+.nv-longform a { color: var(--color-fg); text-decoration: underline; text-decoration-color: var(--color-border-emphasis); text-underline-offset: var(--underline-offset-lg); }
+.nv-longform a:hover { text-decoration-color: currentColor; }
+.nv-longform :is(ul, ol) { padding-inline-start: 1.5rem; }
+.nv-longform ul { list-style: disc; }
+.nv-longform ol { list-style: decimal; }
+.nv-longform li::marker { color: var(--color-fg-muted); }
+.nv-longform li + li { margin-block-start: 0.375rem; }
+.nv-longform ol { font-variant-numeric: tabular-nums; }
+.nv-longform blockquote { padding-inline-start: 1.25rem; border-inline-start: 2px solid var(--color-fg); font-size: 1.375rem; line-height: 1.45; font-weight: var(--weight-medium); }
+.nv-longform figure img, .nv-longform > img { display: block; width: 100%; height: auto; border-radius: var(--radius-media); }
+.nv-longform figcaption { margin-block-start: var(--space-2); font-size: var(--type-caption); color: var(--color-fg-muted); }
+.nv-longform__table { overflow-x: auto; }
+.nv-longform table { width: 100%; border-collapse: collapse; font-size: 0.90625rem; }
+.nv-longform th { text-align: start; font-weight: var(--weight-medium); padding: var(--space-3) var(--space-3) var(--space-3) 0; border-block-end: 1px solid var(--color-fg); }
+.nv-longform td { padding: var(--space-3) var(--space-3) var(--space-3) 0; border-block-end: var(--border-subtle); }
+.nv-longform hr { height: 1px; border: 0; background: var(--color-border); margin-block: 1.5rem; }
+.nv-longform code { padding: 0.1em 0.35em; border-radius: var(--radius-sm); background: var(--color-bg-muted); font-family: var(--font-mono); font-size: 0.875rem; }
+.nv-longform iframe, .nv-longform video { aspect-ratio: 16 / 9; width: 100%; height: auto; border: 0; border-radius: var(--radius-media); }
+.nv-root:lang(th) .nv-longform, .nv-root :lang(th) .nv-longform { line-height: 1.85; }
+.nv-root[dir='rtl'] .nv-longform { line-height: 1.8; }

package/templates/nova/src/components/content/LongForm.tsx

@@ -0,0 +1,56 @@
+import { useMemo } from 'react'
+import './LongForm.css'
+import { isolateParagraphs } from './RichText'
+
+/**
+ * 12E · 00 the prose system — every richtext element, one measure. Any
+ * merchant text looks typeset: body 17 / 1.75 at a 640 measure (960 for
+ * figures and tables), h2 · h3 · h4 28 / 21 / 15, lists, blockquote, figure,
+ * table (scrolls at 390), hr, code, embeds 16:9. The page / article title is
+ * the only h1: an h1 inside the richtext becomes an h2.
+ * Used by page-body, article-body, policy-page (12G) and any long richtext.
+ * The adapter sanitises the HTML; this only renders it.
+ */
+export interface LongFormProps {
+  html: string
+  /** narrow 640 · content 960 · standard 1280 (text never wider than 640 unless standard). */
+  measure?: 'narrow' | 'content' | 'standard'
+  /** Give each h2 an id (article contents). */
+  headingIds?: boolean
+  className?: string
+}
+
+export function slug(text: string): string {
+  return text.toLowerCase().replace(/<[^>]*>/g, '').replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-|-$/g, '') || 'section'
+}
+
+/** The article's h2 headings (text + id), for a contents list. */
+export function headingsOf(html: string): { id: string; text: string }[] {
+  return [...html.matchAll(/<h[12][^>]*>([\s\S]*?)<\/h[12]>/gi)].map((m) => {
+    const text = m[1].replace(/<[^>]*>/g, '').trim()
+    return { id: slug(text), text }
+  })
+}
+
+function prepare(html: string, ids: boolean): string {
+  let out = html.replace(/<h1(\s|>)/gi, '<h2$1').replace(/<\/h1>/gi, '</h2>')
+  if (ids) out = out.replace(/<h2([^>]*)>([\s\S]*?)<\/h2>/gi, (_, attrs: string, inner: string) => (/\sid=/.test(attrs) ? `<h2${attrs}>${inner}</h2>` : `<h2${attrs} id="${slug(inner)}">${inner}</h2>`))
+  // Tables scroll inside their own wrapper at 390, never the page.
+  out = out.replace(/<table/gi, '<div class="nv-longform__table"><table').replace(/<\/table>/gi, '</table></div>')
+  return out
+}
+
+export function LongForm({ html, measure = 'narrow', headingIds, className }: LongFormProps): JSX.Element | null {
+  // Heading ids first (they read the raw headings), then each paragraph's merchant text in <bdi>.
+  const prepared = useMemo(() => isolateParagraphs(prepare(html, Boolean(headingIds))), [html, headingIds])
+  if (!html.replace(/<[^>]*>/g, '').trim()) return null
+  return <div className={['nv-longform', className].filter(Boolean).join(' ')} data-measure={measure} dangerouslySetInnerHTML={{ __html: prepared }} />
+}
+
+/** Reading time: ≈ 230 words a minute; Thai (no spaces) by character count. */
+export function readingMinutes(html: string): number {
+  const text = html.replace(/<[^>]*>/g, ' ')
+  const thai = (text.match(/[฀-๿]/g) ?? []).length
+  const words = text.replace(/[฀-๿]/g, ' ').split(/\s+/).filter(Boolean).length
+  return Math.max(1, Math.round(words / 230 + thai / 900))
+}

package/templates/nova/src/components/content/MediaFrame.css

@@ -0,0 +1,5 @@
+.nv-image { position: relative; display: grid; place-items: center; width: 100%; overflow: hidden; background: var(--color-media-bg); color: var(--color-fg-subtle); }
+.nv-image[data-rounded] { border-radius: var(--radius-media); }
+.nv-image img { width: 100%; height: 100%; object-fit: cover; transition: opacity var(--duration-base) var(--ease-standard); }
+.nv-image[data-fit='contain'] img { object-fit: contain; }
+.nv-image[aria-busy='true'] img { opacity: 0; }

package/templates/nova/src/components/content/MediaFrame.tsx

@@ -0,0 +1,52 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { useState, type CSSProperties } from 'react'
+import type { NovaImage } from '@tanqory/theme-kit'
+import { MediaError } from '../states/media/MediaError'
+import './MediaFrame.css'
+
+/**
+ * Nova 02 · MediaFrame — loaded (cover) · contain on media-bg · loading
+ * (LQIP fade, `aria-busy` while loading — the one attribute the hydrated page may change, theme ABI
+ * §10.5) · missing / error (icon on the media tile). ALWAYS reserves its
+ * ratio, so there is no layout shift. `ratio` 'natural' uses the image's own.
+ */
+export interface MediaFrameProps {
+  image?: NovaImage | null
+  /** CSS aspect-ratio, e.g. '4 / 5'; 'natural' = the image's own. */
+  ratio?: string
+  fit?: 'cover' | 'contain'
+  sizes?: string
+  /** Decorative inside a link that already names the destination. */
+  decorative?: boolean
+  priority?: boolean
+  rounded?: boolean
+  className?: string
+}
+
+export function MediaFrame({ image, ratio = 'natural', fit = 'cover', sizes = '100vw', decorative, priority, rounded = true, className }: MediaFrameProps): JSX.Element {
+  const [state, setState] = useState<'loading' | 'loaded' | 'error'>('loading')
+  const aspect = ratio === 'natural' ? (image ? `${image.width} / ${image.height}` : '4 / 3') : ratio
+  const style = { aspectRatio: aspect } as CSSProperties
+  const failed = !image || state === 'error'
+  if (failed) return <MediaError reason={image ? 'failed' : 'missing'} ratio={aspect} rounded={rounded} className={className} />
+  return (
+    <span className={sxJoin(['nv-image', className].filter(Boolean).join(' '), sx(style))} data-fit={fit} aria-busy={state === 'loading' ? true : undefined} data-rounded={rounded ? '' : undefined}>
+      <img
+          src={image.src}
+          srcSet={image.srcSet}
+          sizes={image.srcSet ? sizes : undefined}
+          alt={decorative ? '' : (image.alt ?? '')}
+          width={image.width}
+          height={image.height}
+          loading={priority ? 'eager' : 'lazy'}
+          decoding="async"
+          onLoad={() => setState('loaded')}
+          onError={() => setState('error')}
+          ref={(el) => {
+            // A cached image can finish before React attaches onLoad.
+            if (el?.complete && el.naturalWidth > 0 && state === 'loading') setState('loaded')
+          }}
+      />
+    </span>
+  )
+}