create-tanqory-theme 0.0.0-stage → 0.2.2

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

@@ -0,0 +1,25 @@
+/* heading.size: 20 / 28 / 40 / 64 desktop · 18 / 24 / 32 / 40 at 390 (fluid between). */
+.nv-block-h { font-family: var(--font-display); font-weight: var(--weight-heading); text-wrap: balance; max-width: 30ch; }
+.nv-block-h--small { font-size: clamp(1.125rem, calc(1.125rem + (100vw - 24.375rem) * 0.00315), 1.25rem); line-height: var(--leading-h3); letter-spacing: var(--tracking-h3); }
+.nv-block-h--medium { font-size: clamp(1.5rem, calc(1.5rem + (100vw - 24.375rem) * 0.00631), 1.75rem); line-height: var(--leading-h2); letter-spacing: var(--tracking-h2); }
+.nv-block-h--large { font-size: clamp(2rem, calc(2rem + (100vw - 24.375rem) * 0.01262), 2.5rem); line-height: var(--leading-h1); letter-spacing: var(--tracking-h1); }
+.nv-block-h--display { font-size: clamp(2.5rem, calc(2.5rem + (100vw - 24.375rem) * 0.03785), 4rem); line-height: var(--leading-display); letter-spacing: var(--tracking-display); max-width: 20ch; }
+.nv-block[data-align='center'] .nv-block-h { margin-inline: auto; }
+.nv-block[data-block='text'] .nv-prose { max-width: 60ch; color: inherit; }
+.nv-block[data-block='text'][data-size='small'] { font-size: var(--type-body-sm); }
+.nv-block[data-block='text'][data-size='large'] { font-size: var(--text-body-lg); line-height: var(--leading-relaxed); }
+.nv-block[data-block='text'][data-muted] { color: var(--color-fg-muted); }
+.nv-block[data-align='center'][data-block='text'] .nv-prose { margin-inline: auto; }
+/* A block left on "inherit" follows its section's contentAlignment: the text
+   centres by inheritance, so its capped box must centre (or end) with it. */
+[data-align='center'] .nv-block[data-align='inherit'] :is(.nv-block-h, .nv-prose) { margin-inline: auto; }
+[data-align='right'] .nv-block[data-align='inherit'] :is(.nv-block-h, .nv-prose) { margin-inline-start: auto; }
+.nv-block[data-block='icon'] { display: flex; }
+.nv-block[data-block='icon'][data-align='center'] { justify-content: center; }
+.nv-block[data-block='icon'][data-align='right'] { justify-content: flex-end; }
+.nv-block[data-block='spacer'] { height: var(--nv-spacer); }
+@media (max-width: 639.98px) { .nv-block[data-block='spacer'] { height: calc(var(--nv-spacer) * 0.67); } }
+.nv-block__caption { margin-top: var(--space-2); font-size: var(--type-caption); color: var(--color-fg-muted); }
+.nv-block__image-link { display: block; border-radius: var(--radius-media); }
+.nv-block__video { width: 100%; aspect-ratio: 16 / 9; border-radius: var(--radius-media); background: var(--color-media-bg); }
+.nv-block__jumbo { font-family: var(--font-display); font-size: clamp(2.5rem, 7vw, 7rem); line-height: var(--leading-display); letter-spacing: var(--tracking-display); font-weight: var(--weight-heading); text-wrap: balance; }

package/templates/nova/src/components/content/blocks/shared.ts

@@ -0,0 +1,5 @@
+/** Option vocabularies shared by the 12D basic blocks (persisted IDs). */
+export const ALIGN4 = ['inherit', 'left', 'center', 'right'] as const
+export const ALIGN3 = ['left', 'center', 'right'] as const
+/** Sections the basic blocks list as parents in the contract. */
+export const PARENTS = ['group', 'feature-grid-blocks', 'product-details'] as const

package/templates/nova/src/components/forms/ContactForm.css

@@ -0,0 +1,19 @@
+.nv-contact-form { display: grid; gap: var(--space-5); justify-items: start; }
+.nv-contact-form__grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--space-4); width: 100%; }
+.nv-contact-form__cell { grid-column: 1 / -1; min-width: 0; }
+.nv-contact-form__cell:is([data-field='name'], [data-field='phone']) { grid-column: auto; }
+.nv-contact-form__grid:not(:has([data-field='phone'])) [data-field='name'] { grid-column: 1 / -1; }
+.nv-contact-form .nv-input, .nv-contact-form .nv-textarea { width: 100%; font-size: 1rem; }
+.nv-contact-form [aria-invalid='true'] { border-width: 1.5px; border-color: var(--color-danger); }
+.nv-contact-form__summary { width: 100%; padding: var(--space-4); border: 1.5px solid var(--color-danger); border-radius: var(--radius-md); font-size: var(--type-body-sm); }
+.nv-contact-form__summary p { font-weight: var(--weight-medium); }
+.nv-contact-form__summary ul { margin: var(--space-2) 0 0; padding-inline-start: var(--space-5); }
+.nv-contact-form__summary button { min-height: 24px; padding: 0; border: 0; background: none; color: var(--color-danger); font: inherit; text-align: start; text-decoration: underline; text-underline-offset: var(--underline-offset); cursor: pointer; }
+.nv-contact-form__submit { min-width: 10rem; }
+.nv-contact-form__failed { font-size: var(--type-body-sm); color: var(--color-fg); }
+.nv-contact-form__sent { display: flex; align-items: flex-start; gap: var(--space-2); width: 100%; padding: var(--space-4); border-radius: var(--radius-md); background: var(--color-success-surface); color: var(--color-success); font-weight: var(--weight-medium); }
+@media (max-width: 639.98px) {
+  .nv-contact-form__grid { grid-template-columns: minmax(0, 1fr); }
+  .nv-contact-form__cell[data-field] { grid-column: 1 / -1; }
+  .nv-contact-form__submit { width: 100%; }
+}

package/templates/nova/src/components/forms/ContactForm.tsx

@@ -0,0 +1,139 @@
+import { useRef, useState, type FormEvent } from 'react'
+import { Button } from '../base/Button'
+import { Input } from '../base/Input'
+import { Textarea } from '../base/Textarea'
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import { FormField } from './FormField'
+import { isEmail } from './validate'
+import { ensureGatewayFields, GatewayFields, Honeypot } from './GatewayFields'
+import './ContactForm.css'
+
+export type ContactFieldId = 'name' | 'email' | 'phone' | 'message'
+export type ContactValues = Partial<Record<ContactFieldId, string>>
+
+export interface ContactFormProps {
+  fields: readonly ContactFieldId[]
+  /** The form endpoint. The form renders only with one (12G "no silent forms"). */
+  action: string
+  buttonLabel: string
+  successMessage: string
+  /** Named in the failure message ("Couldn't send. Email us at …"). */
+  fallbackEmail?: string
+  /** Host submission; without it the valid form posts natively to action. */
+  onSend?: (values: ContactValues) => Promise<unknown> | void
+  /** The platform form this posts as (`<form data-tq-form>`, theme-abi §1) — only for the platform's endpoint. */
+  formId?: string
+  /** The outcome of this form's POST, when the page answers one (the platform's `form.submit`). */
+  result?: { status: 'ok' | 'invalid' | 'rate_limited' | 'unavailable' | 'expired'; email?: string }
+}
+
+type Status = 'idle' | 'sending' | 'sent' | 'failed' | 'limited' | 'expired'
+
+const initialOf = (result: ContactFormProps['result']): Status =>
+  result?.status === 'ok' ? 'sent' : result?.status === 'rate_limited' ? 'limited' : result?.status === 'expired' ? 'expired' : result?.status === 'unavailable' || result?.status === 'invalid' ? 'failed' : 'idle'
+
+/**
+ * 12G · contact fields: visible labels above (placeholders are never labels),
+ * 52px inputs with 16px text, autocomplete name / email / tel, name + phone
+ * half width on desktop. On submit, errors go under each field AND in a
+ * summary at the top, and focus moves to the first. Sent → the success
+ * message replaces the form (role=status); a failed send keeps the values.
+ */
+export function ContactForm({ fields, action, buttonLabel, successMessage, fallbackEmail, onSend, formId, result }: ContactFormProps): JSX.Element {
+  const { strings } = useNova()
+  const [errors, setErrors] = useState<Partial<Record<ContactFieldId, string>>>({})
+  const [status, setStatus] = useState<Status>(() => initialOf(result))
+  const form = useRef<HTMLFormElement>(null)
+  const label: Record<ContactFieldId, string> = { name: strings.name, email: strings.email, phone: strings.phone, message: strings.message }
+
+  if (status === 'sent') {
+    return (
+      <p className="nv-contact-form__sent" role="status">
+        <Icon name="check" size="sm" />
+        {successMessage}
+      </p>
+    )
+  }
+
+  const submit = async (e: FormEvent<HTMLFormElement>) => {
+    const data = new FormData(e.currentTarget)
+    const values: ContactValues = Object.fromEntries(fields.map((f) => [f, String(data.get(f) ?? '').trim()]))
+    const next: Partial<Record<ContactFieldId, string>> = {}
+    for (const f of fields) {
+      const v = values[f] ?? ''
+      if (f === 'phone') continue // optional
+      if (!v) next[f] = strings.fieldRequired
+      else if (f === 'email' && !isEmail(v)) next[f] = strings.emailInvalid
+    }
+    setErrors(next)
+    const first = fields.find((f) => next[f])
+    if (first) {
+      e.preventDefault()
+      form.current?.querySelector<HTMLElement>(`[name="${first}"]`)?.focus()
+      return
+    }
+    if (!onSend) {
+      // a native post: the page that answers it shows the outcome
+      if (formId) ensureGatewayFields(e.currentTarget, formId)
+      setStatus('sending')
+      return
+    }
+    e.preventDefault()
+    setStatus('sending')
+    try {
+      await onSend(values)
+      setStatus('sent')
+    } catch {
+      setStatus('failed')
+    }
+  }
+
+  // Name and phone share a row (half width each): phone follows name in the DOM too, so focus order matches what is seen.
+  const order = fields.includes('phone') ? [...fields.filter((f) => f !== 'phone')].flatMap((f) => (f === 'name' ? ['name', 'phone'] as ContactFieldId[] : [f])) : fields
+  const bad = order.filter((f) => errors[f])
+  const control = (f: ContactFieldId) =>
+    f === 'message' ? (
+      <Textarea name="message" rows={5} />
+    ) : (
+      <Input name={f} size="lg" type={f === 'email' ? 'email' : f === 'phone' ? 'tel' : 'text'} inputMode={f === 'phone' ? 'tel' : undefined} autoComplete={f === 'name' ? 'name' : f === 'email' ? 'email' : 'tel'} />
+    )
+  return (
+    <form ref={form} className="nv-contact-form" action={action} method="post" noValidate onSubmit={submit} aria-busy={status === 'sending' || undefined} {...(formId ? { 'data-tq-form': formId } : {})}>
+      {formId && <GatewayFields formId={formId} />}
+      {formId && <Honeypot />}
+      {bad.length > 0 && (
+        <div className="nv-contact-form__summary" role="alert">
+          <p>{fmt(strings.fixFields, { count: bad.length })}</p>
+          <ul>
+            {bad.map((f) => (
+              <li key={f}>
+                <button type="button" onClick={() => form.current?.querySelector<HTMLElement>(`[name="${f}"]`)?.focus()}>
+                  {label[f]}: {errors[f]}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      <div className="nv-contact-form__grid">
+        {order.map((f) => (
+          <div key={f} className="nv-contact-form__cell" data-field={f}>
+            <FormField label={label[f]} optional={f === 'phone' ? strings.optional : undefined} required={f !== 'phone'} error={errors[f]}>
+              {control(f)}
+            </FormField>
+          </div>
+        ))}
+      </div>
+      {(status === 'failed' || status === 'limited' || status === 'expired') && (
+        <p className="nv-contact-form__failed" role="alert">
+          {status === 'limited' ? strings.sendTooMany : status === 'expired' ? strings.formExpired : fallbackEmail ? fmt(strings.sendFailedEmail, { email: fallbackEmail }) : strings.sendFailed}
+        </p>
+      )}
+      <Button type="submit" size="lg" className="nv-contact-form__submit" disabled={status === 'sending'}>
+        {status === 'sending' ? strings.sending : buttonLabel}
+      </Button>
+    </form>
+  )
+}

package/templates/nova/src/components/forms/FormField.css

@@ -0,0 +1,15 @@
+.nv-field { display: grid; gap: var(--space-2); min-width: 0; }
+.nv-field__label { font-size: var(--type-body-sm); font-weight: var(--weight-medium); color: var(--color-fg); }
+.nv-field__optional { color: var(--color-fg-muted); font-weight: var(--weight-body); }
+.nv-field__foot { display: flex; justify-content: space-between; gap: var(--space-3); font-size: var(--type-caption); }
+.nv-field__help { color: var(--color-fg-muted); }
+.nv-field__error { display: inline-flex; align-items: flex-start; gap: var(--space-1); color: var(--color-danger); }
+.nv-field__error .nv-icon { margin-top: 2px; }
+.nv-field__counter { color: var(--color-fg-muted); margin-inline-start: auto; }
+
+.nv-field__success { display: inline-flex; align-items: center; gap: var(--space-1); color: var(--color-success); }
+.nv-field__warning { color: var(--color-warning-ink); }
+.nv-field[data-status='success'] :is(.nv-input, .nv-select__control) { border-color: var(--color-success); }
+.nv-field[data-status='warning'] :is(.nv-input, .nv-select__control) { border-color: var(--color-warning); }
+.nv-field[data-invalid] :is(.nv-input, .nv-select__control) { border-width: 1.5px; border-color: var(--color-danger); }
+.nv-input:read-only:not(:disabled) { background: var(--color-bg-muted); border-color: transparent; }

package/templates/nova/src/components/forms/FormField.tsx

@@ -0,0 +1,77 @@
+import { cloneElement, isValidElement, useId, type ReactElement, type ReactNode } from 'react'
+import { Icon } from '../../styles/Icon'
+import './FormField.css'
+
+/**
+ * Nova 02 · Field — the form row around any control (Input, Textarea,
+ * Select). Label ALWAYS above (never placeholder-only); help below; an
+ * error replaces help with a danger icon + text (never colour alone). Wires
+ * id, aria-invalid, aria-describedby and required onto its child.
+ */
+export interface FormFieldProps {
+  label: string
+  /** Visually hide the label (it stays the accessible name) — search fields. */
+  hideLabel?: boolean
+  help?: ReactNode
+  error?: ReactNode
+  /** Nova 14 · 14.6: a confirmed value ("Delivery available") — green border + ✓ + text. */
+  success?: ReactNode
+  /** A caution that does not block ("Delivery takes 1 extra day") — amber border + text. */
+  warning?: ReactNode
+  /** Mark required fields with * (use when they are the minority; otherwise mark the optional ones). */
+  requiredMark?: boolean
+  optional?: boolean | string
+  required?: boolean
+  /** "46 / 500" under a textarea. */
+  counter?: string
+  children: ReactElement
+}
+
+export function FormField({ label, hideLabel, help, error, success, warning, requiredMark, optional, required, counter, children }: FormFieldProps): JSX.Element {
+  const id = useId()
+  const msgId = `${id}-msg`
+  const control = isValidElement(children)
+    ? cloneElement(children as ReactElement<Record<string, unknown>>, {
+        id,
+        'aria-invalid': error ? true : undefined,
+        'aria-describedby': help || error || success || warning ? msgId : undefined,
+        required,
+      })
+    : children
+  return (
+    <div className="nv-field" data-invalid={error ? '' : undefined} data-status={error ? undefined : warning ? 'warning' : success ? 'success' : undefined}>
+      <label htmlFor={id} className={hideLabel ? 'nv-visually-hidden' : 'nv-field__label'}>
+        {label}
+        {required && requiredMark && <span aria-hidden> *</span>}
+        {optional && <span className="nv-field__optional"> {typeof optional === 'string' ? optional : '(optional)'}</span>}
+      </label>
+      {control}
+      {(error || success || warning || help || counter) && (
+        <div className="nv-field__foot">
+          {error ? (
+            <p id={msgId} className="nv-field__error">
+              <Icon name="alert" size="sm" />
+              {error}
+            </p>
+          ) : warning ? (
+            <p id={msgId} className="nv-field__warning">
+              {warning}
+            </p>
+          ) : success ? (
+            <p id={msgId} className="nv-field__success">
+              <Icon name="check" size="sm" />
+              {success}
+            </p>
+          ) : help ? (
+            <p id={msgId} className="nv-field__help">
+              {help}
+            </p>
+          ) : (
+            <span />
+          )}
+          {counter && <span className="nv-field__counter nv-tabular">{counter}</span>}
+        </div>
+      )}
+    </div>
+  )
+}

package/templates/nova/src/components/forms/GatewayFields.tsx

@@ -0,0 +1,79 @@
+import { useState } from 'react'
+import { useServerRender } from '@tanqory/theme-kit'
+
+const FORM_FIELD = '_tq_form'
+const CSRF_FIELD = '_tq_csrf'
+const CSRF_META = 'tq-csrf'
+
+/** The fields the gateway put at the start of a `<form data-tq-form="<id>">` of the delivered page, or null. */
+// No `instanceof HTML…Element`: those constructors are free identifiers in the server bundle, which the
+// ABI's static scan refuses (suite 1) — an element is recognised by its tag and name instead.
+const hiddenInput = (el: Element | null, name: string): string | null =>
+  el && el.tagName === 'INPUT' && el.getAttribute('name') === name ? (el.getAttribute('value') ?? '') : null
+
+function injectedInto(formId: string): { csrf: string } | null {
+  for (const form of Array.from(document.querySelectorAll(`form[data-tq-form="${formId}"]`))) {
+    const first = form.firstElementChild
+    if (hiddenInput(first, FORM_FIELD) !== null) return { csrf: hiddenInput(first!.nextElementSibling, CSRF_FIELD) ?? '' }
+  }
+  return null
+}
+
+/**
+ * Native platform forms (theme-abi §1, §4.1): the theme writes only `<form data-tq-form="<id>" method="post">`;
+ * the storefront gateway injects, after its cache, `<input type="hidden" name="_tq_form">` and (with the shopper's
+ * token) `<input type="hidden" name="_tq_csrf">` as the form's FIRST children. The server never renders them — a
+ * theme that does is refused. In the browser this mirrors what the delivered page holds, decided once on the
+ * hydrating render: the fields when the gateway injected them (so the tree matches the injected markup and a
+ * re-render never drops them), nothing when it did not (a host without the gateway, the conformance harness).
+ */
+export function GatewayFields({ formId }: { formId: string }): JSX.Element | null {
+  const server = useServerRender()
+  const [present] = useState(() => (server ? null : injectedInto(formId)))
+  if (server || !present) return null
+  return (
+    <>
+      <input type="hidden" name={FORM_FIELD} value={formId} />
+      {present.csrf ? <input type="hidden" name={CSRF_FIELD} value={present.csrf} /> : null}
+    </>
+  )
+}
+
+/**
+ * Right before a native post: a form the gateway never saw (rendered after a soft navigation) gets the same two
+ * fields from the page's `<meta name="tq-csrf">`, so the platform can verify it. A form that has them is untouched.
+ */
+export function ensureGatewayFields(form: HTMLFormElement, formId: string): void {
+  if (form.querySelector(`input[name="${FORM_FIELD}"]`)) return
+  const token = document.querySelector(`meta[name="${CSRF_META}"]`)?.getAttribute('content') ?? ''
+  const add = (name: string, value: string) => {
+    const input = document.createElement('input')
+    input.type = 'hidden'
+    input.name = name
+    input.value = value
+    form.prepend(input)
+  }
+  if (/^[A-Za-z0-9_-]+$/.test(token)) add(CSRF_FIELD, token)
+  add(FORM_FIELD, formId)
+}
+
+/**
+ * The honeypot the platform form endpoints read (`website`): off-screen, out of the tab order and hidden from
+ * assistive technology, so only a bot fills it — and the platform answers that post like a success.
+ */
+export function Honeypot(): JSX.Element {
+  return (
+    <div className="nv-visually-hidden" aria-hidden="true">
+      <label>
+        Website
+        <input type="text" name="website" tabIndex={-1} autoComplete="off" defaultValue="" />
+      </label>
+    </div>
+  )
+}
+
+/** A platform form result names its form; `*` is a post that never ran (origin / CSRF), shown on every form. */
+export function resultFor<T extends { formId: string }>(result: T | undefined | null, formId: string | undefined): T | undefined {
+  if (!result || !formId) return undefined
+  return result.formId === formId || result.formId === '*' ? result : undefined
+}

package/templates/nova/src/components/forms/NewsletterForm.css

@@ -0,0 +1,9 @@
+.nv-newsletter-form { display: flex; flex-wrap: wrap; gap: var(--space-2); flex: 1 1 320px; max-width: 480px; }
+.nv-newsletter-form .nv-input { flex: 1 1 200px; }
+.nv-newsletter-form__note { flex-basis: 100%; font-size: var(--type-caption); color: var(--color-fg-muted); }
+.nv-newsletter-form .nv-input[aria-invalid='true'] { border-width: 1.5px; border-color: var(--color-danger); }
+.nv-newsletter-form__error { display: flex; align-items: center; gap: var(--space-1); flex-basis: 100%; font-size: var(--type-caption); color: var(--color-danger); }
+.nv-newsletter-form__consent { display: grid; gap: var(--space-1); flex-basis: 100%; }
+.nv-newsletter-form__failed { flex-basis: 100%; font-size: var(--type-caption); color: var(--color-fg); }
+.nv-newsletter-form__done { display: inline-flex; align-items: center; gap: var(--space-2); min-height: 44px; font-weight: var(--weight-medium); color: var(--color-success); }
+[data-nv-surface='inverse'] .nv-newsletter-form__done { color: inherit; }

package/templates/nova/src/components/forms/NewsletterForm.tsx

@@ -0,0 +1,141 @@
+import { useId, useState, type FormEvent } from 'react'
+import { Button } from '../base/Button'
+import { Checkbox } from '../base/Checkbox'
+import { Input } from '../base/Input'
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import { isEmail } from './validate'
+import { ensureGatewayFields, GatewayFields, Honeypot } from './GatewayFields'
+import './NewsletterForm.css'
+
+/**
+ * Email sign-up. Posts to the platform endpoint `action` — rendered ONLY
+ * when that endpoint exists (DATA REQUIREMENT: Nova never renders a form
+ * that cannot submit). The email label is visually hidden, never absent.
+ *
+ * 12G states: an incomplete address → inline error (the value stays);
+ * submitting → "Subscribing…", width fixed, aria-busy; done → "You're on the
+ * list." replaces the form (role=status); a server error is neutral — it
+ * never blames the shopper. With `onSubscribe` the host submits; without it
+ * the form posts natively once the address is valid.
+ */
+export interface NewsletterFormProps {
+  action: string
+  placeholder?: string
+  buttonLabel?: string
+  note?: string
+  /** Marketing consent checkbox — unchecked by default; required when shown. */
+  showConsent?: boolean
+  onSubscribe?: (email: string, consent: boolean) => Promise<unknown> | void
+  /** Inputs 48 in bands (md), 52 on their own (lg). */
+  size?: 'md' | 'lg'
+  /**
+   * The platform form this posts as (`<form data-tq-form>`, theme-abi §1) — set only when `action` is the
+   * platform's endpoint, never for a merchant's own URL.
+   */
+  formId?: string
+  /** The outcome of this form's POST, when the page answers one (the platform's `form.submit`). */
+  result?: { status: 'ok' | 'invalid' | 'rate_limited' | 'unavailable' | 'expired'; email?: string }
+}
+
+type Status = 'idle' | 'submitting' | 'done' | 'failed' | 'limited' | 'expired'
+
+/** The page answering this form's POST: done, or the failure to show (an invalid address is the field's error). */
+function initialOf(result: NewsletterFormProps['result']): Status {
+  switch (result?.status) {
+    case 'ok':
+      return 'done'
+    case 'rate_limited':
+      return 'limited'
+    case 'expired':
+      return 'expired'
+    case 'unavailable':
+      return 'failed'
+    default:
+      return 'idle'
+  }
+}
+
+export function NewsletterForm({ action, placeholder = 'you@example.com', buttonLabel, note, showConsent, onSubscribe, size = 'md', formId, result }: NewsletterFormProps): JSX.Element {
+  const { strings } = useNova()
+  const id = useId()
+  const [error, setError] = useState(result?.status === 'invalid' ? strings.emailInvalid : '')
+  const [consentError, setConsentError] = useState('')
+  const [status, setStatus] = useState<Status>(() => initialOf(result))
+
+  if (status === 'done') {
+    return (
+      <p className="nv-newsletter-form__done" role="status">
+        <Icon name="check" size="sm" />
+        {strings.subscribed}
+      </p>
+    )
+  }
+
+  const submit = async (e: FormEvent<HTMLFormElement>) => {
+    const form = e.currentTarget
+    const email = String(new FormData(form).get('email') ?? '')
+    const consent = Boolean(form.querySelector<HTMLInputElement>('input[name="consent"]')?.checked)
+    const emailError = isEmail(email) ? '' : strings.emailInvalid
+    const needConsent = showConsent && !consent ? strings.consentRequired : ''
+    setError(emailError)
+    setConsentError(needConsent)
+    if (emailError || needConsent) {
+      e.preventDefault()
+      form.querySelector<HTMLInputElement>(emailError ? 'input[type="email"]' : 'input[name="consent"]')?.focus()
+      return
+    }
+    if (!onSubscribe) {
+      // a native post: the page that answers it shows the outcome
+      if (formId) ensureGatewayFields(e.currentTarget, formId)
+      setStatus('submitting')
+      return
+    }
+    e.preventDefault()
+    setStatus('submitting')
+    try {
+      await onSubscribe(email.trim(), consent)
+      setStatus('done')
+    } catch {
+      setStatus('failed')
+    }
+  }
+
+  const errId = `${id}-err`
+  return (
+    <form className="nv-newsletter-form" action={action} method="post" noValidate onSubmit={submit} aria-busy={status === 'submitting' || undefined} {...(formId ? { 'data-tq-form': formId } : {})}>
+      {formId && <GatewayFields formId={formId} />}
+      <label className="nv-visually-hidden" htmlFor={id}>
+        {placeholder}
+      </label>
+      <Input id={id} type="email" name="email" required placeholder={placeholder} autoComplete="email" size={size} {...(result?.email ? { defaultValue: result.email } : {})} aria-invalid={error ? true : undefined} aria-describedby={error ? errId : undefined} />
+      {formId && <Honeypot />}
+      <Button type="submit" size={size} disabled={status === 'submitting'} className="nv-newsletter-form__submit">
+        {status === 'submitting' ? strings.subscribing : buttonLabel || strings.newsletterSubscribe}
+      </Button>
+      {error && (
+        <p id={errId} className="nv-newsletter-form__error">
+          <Icon name="alert" size="sm" />
+          {error}
+        </p>
+      )}
+      {showConsent && (
+        <div className="nv-newsletter-form__consent">
+          <Checkbox name="consent" value="yes" label={strings.consentLabel} aria-invalid={consentError ? true : undefined} />
+          {consentError && (
+            <p className="nv-newsletter-form__error">
+              <Icon name="alert" size="sm" />
+              {consentError}
+            </p>
+          )}
+        </div>
+      )}
+      {(status === 'failed' || status === 'limited' || status === 'expired') && (
+        <p className="nv-newsletter-form__failed" role="alert">
+          {status === 'limited' ? strings.subscribeTooMany : status === 'expired' ? strings.formExpired : strings.subscribeFailed}
+        </p>
+      )}
+      {note && <p className="nv-newsletter-form__note">{note}</p>}
+    </form>
+  )
+}

package/templates/nova/src/components/forms/SearchField.css

@@ -0,0 +1,7 @@
+.nv-search-field { display: flex; align-items: center; gap: var(--space-3); width: 100%; max-width: 43rem; min-height: 52px; padding-inline: var(--space-4); border: 1px solid var(--color-border-emphasis); border-radius: var(--input-radius); background: var(--color-bg); color: var(--color-fg); }
+.nv-search-field:focus-within { outline: var(--focus-ring-width) solid var(--color-focus); outline-offset: 2px; }
+.nv-search-field__input { flex: 1; min-width: 0; height: 50px; padding: 0; border: 0; background: none; color: inherit; font: inherit; font-size: 1rem; }
+.nv-search-field__input:focus { outline: none; }
+.nv-search-field__input::-webkit-search-cancel-button { display: none; }
+.nv-search-field__clear { min-height: 32px; padding: 0 var(--space-1); border: 0; background: none; color: var(--color-fg-muted); font: inherit; font-size: var(--type-caption); cursor: pointer; }
+.nv-search-field__clear:hover { color: var(--color-fg); }

package/templates/nova/src/components/forms/SearchField.tsx

@@ -0,0 +1,68 @@
+import { useRef, useState } from 'react'
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import './SearchField.css'
+
+export interface SearchFieldProps {
+  /** Where the query goes (GET ?q=). */
+  action?: string
+  defaultValue?: string
+  placeholder?: string
+  /** Accessible name; the field shows only its placeholder. */
+  label?: string
+  autoFocus?: boolean
+  /** Handle the query in place (SPA); otherwise the form submits to action. */
+  onSearch?: (query: string) => void
+}
+
+/**
+ * 12G · the submitted-query field (search-results, not-found): 52 tall, 16px
+ * text, search icon, Clear. The query stays in the field; Clear resets it
+ * and returns focus. SearchModal (Nova 13) handles typing-ahead.
+ */
+export function SearchField({ action = '/search', defaultValue = '', placeholder, label, autoFocus, onSearch }: SearchFieldProps): JSX.Element {
+  const { strings } = useNova()
+  const [value, setValue] = useState(defaultValue)
+  const input = useRef<HTMLInputElement>(null)
+  return (
+    <form
+      className="nv-search-field"
+      role="search"
+      action={action}
+      method="get"
+      onSubmit={(e) => {
+        if (!onSearch) return
+        e.preventDefault()
+        onSearch(value.trim())
+      }}
+    >
+      <Icon name="search" size="sm" />
+      <input
+        ref={input}
+        className="nv-search-field__input"
+        type="search"
+        name="q"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        placeholder={placeholder ?? strings.searchPlaceholder}
+        aria-label={label ?? strings.search}
+        autoComplete="off"
+        enterKeyHint="search"
+        // eslint-disable-next-line jsx-a11y/no-autofocus -- the results page is FOR searching (12G: "field focused")
+        autoFocus={autoFocus}
+      />
+      {value && (
+        <button
+          type="button"
+          className="nv-search-field__clear"
+          onClick={() => {
+            setValue('')
+            input.current?.focus()
+          }}
+        >
+          {strings.clear}
+        </button>
+      )}
+    </form>
+  )
+}

package/templates/nova/src/components/forms/blocks/Newsletter.css

@@ -0,0 +1,5 @@
+/* newsletter (in footer / group) */
+.nv-newsletter-block { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: var(--space-5); }
+.nv-newsletter-block__heading { font-family: var(--font-display); font-size: var(--type-h3); line-height: var(--leading-h3); letter-spacing: var(--tracking-h3); font-weight: var(--weight-heading); }
+.nv-newsletter-block__body { margin-top: var(--space-1); color: var(--color-fg-muted); }
+[data-nv-surface='inverse'] .nv-newsletter-block .nv-btn[data-variant='secondary'] { min-width: 240px; }