create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/tests/rewards-launcher.test.tsx

@@ -0,0 +1,401 @@
+/**
+ * Storefront rewards (army #7749): the rewards launcher every page shares and the "Earn N points"
+ * hint, rendered the way main.abi.tsx hydrates a page (AbiRewardsProvider over the ABI remote,
+ * `loyalty.state` / `loyalty.redeem`). The remote here is a recorded host answer; everything the
+ * shopper sees is the theme's own. Referrals (army #7751): the launcher's Refer a friend tab, or the launcher
+ * itself with loyalty off, and the friend offer a `?ref=CODE` visit shows (AbiReferralsProvider, inside it).
+ */
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { renderToString } from 'react-dom/server'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { setThemeBundle } from '@tanqory/theme-kit/runtime'
+import { sectionModules } from '@tanqory/theme-kit/runtime'
+import { registerSections } from '@tanqory/theme-kit/runtime'
+import { SectionTree } from '@tanqory/theme-kit/runtime'
+import { DataProvider } from '@tanqory/theme-kit/runtime'
+import { ThemeProvider } from '@tanqory/theme-kit/runtime'
+import { localeStrings } from '@tanqory/theme-kit/runtime'
+import { earnPoints, type RewardsState } from '@tanqory/theme-kit'
+import type { ReferralState } from '@tanqory/theme-kit'
+import { bundle } from '../lib/bundle'
+import { AbiShell } from '@tanqory/theme-kit/runtime'
+import { AbiCartProvider } from '@tanqory/theme-kit/runtime'
+import { AbiRewardsProvider } from '@tanqory/theme-kit/runtime'
+import { AbiWireError, type AbiRemote, type WireEnvelope } from '@tanqory/theme-kit/runtime'
+import { createDataApi } from '@tanqory/theme-kit/runtime'
+import type { PageData } from '@tanqory/theme-kit/runtime'
+import { EarnHint } from '../src/components/commerce/EarnHint'
+
+setThemeBundle(bundle)
+registerSections(Object.values(sectionModules()).map((m) => m.default))
+
+const LOCALES = Object.fromEntries(
+  Object.entries(bundle.locales).map(([path, mod]) => [path.match(/\/([^/]+)\.json$/)?.[1] ?? 'en', (mod as { default: Record<string, string> }).default]),
+)
+
+const PAGE_DATA = {
+  route: 'index',
+  shop: { name: 'Demo', description: null, brand: null, policies: {}, primaryDomain: { host: 'demo.example', url: 'https://demo.example', sslEnabled: true } },
+  menus: {}, products: {}, collections: {}, collectionList: null, pages: {}, blogs: {}, articles: {},
+  search: null, recommendations: {}, policyHandle: null, accountUrls: null, cart: null,
+  localization: { country: { isoCode: 'TH', name: 'Thailand', currency: { isoCode: 'THB', name: 'Thai Baht', symbol: '฿' } }, language: { isoCode: 'EN', name: 'English' }, availableCountries: [], availableLanguages: [] },
+  signedIn: null, unresolved: [], routeMissing: false,
+} as unknown as PageData
+
+const WAYS = [
+  { id: 'w-order', kind: 'PLACE_ORDER', name: 'Place an order', points: null, completed: false },
+  { id: 'w-signup', kind: 'SIGN_UP', name: 'Create an account', points: 100, completed: true },
+]
+const MEMBER: RewardsState = {
+  enabled: true,
+  signedIn: true,
+  member: true,
+  program: { name: 'Leaf Club', earnRates: { THB: 0.1 } },
+  balance: { available: 1250, pending: 40, lifetimeEarned: 3000 },
+  tier: { basis: 'POINTS', currency: null, current: { name: 'Gold', earnMultiplier: 1.5 }, next: { name: 'Platinum', threshold: 5000 }, progress: { qualifying: 3000, remaining: 2000 } },
+  rewards: [
+    { id: 'rw-100', name: '฿100 off', kind: 'AMOUNT_OFF', pointsCost: 1000, affordable: true, pointsNeeded: 0, tierLocked: false, limitReached: false },
+    { id: 'rw-500', name: '฿500 off', kind: 'AMOUNT_OFF', pointsCost: 1500, affordable: false, pointsNeeded: 250, tierLocked: false, limitReached: false },
+  ],
+  codes: [{ code: 'LOYALTY-OLD111', rewardName: 'Free shipping', kind: 'FREE_SHIPPING', expiresAt: '2027-01-20T00:00:00.000Z' }],
+  ways: WAYS,
+}
+const GUEST: RewardsState = { enabled: true, signedIn: false, program: { name: 'Leaf Club', earnRates: { THB: 0.1 } }, ways: WAYS }
+const AFTER_REDEEM: RewardsState = {
+  ...MEMBER,
+  balance: { available: 250, pending: 40, lifetimeEarned: 3000 },
+  codes: [{ code: 'LOYALTY-NEW222', rewardName: '฿100 off', kind: 'AMOUNT_OFF', expiresAt: '2027-01-15T00:00:00.000Z' }, ...MEMBER.codes!],
+}
+
+/** A host answering `loyalty.state` with `state` and the referral ops with `referral` (`undefined`: not offered). */
+function hostWith(state: unknown, referral: { referral?: unknown; offer?: unknown } = {}) {
+  const calls: { kind: 'data' | 'action'; name: string; args: readonly unknown[] }[] = []
+  const answers: Record<string, unknown> = { 'loyalty.state': state, 'referral.state': referral.referral, 'referral.offer': referral.offer }
+  const remote: AbiRemote = {
+    async data(op, args) {
+      calls.push({ kind: 'data', name: op, args })
+      if (answers[op] !== undefined) return answers[op]
+      throw new AbiWireError(404, 'unknown_operation')
+    },
+    async action(name, args) {
+      calls.push({ kind: 'action', name, args })
+      if (name === 'loyalty.redeem') return { ok: true, data: { redemption: { code: 'LOYALTY-NEW222' }, state: AFTER_REDEEM }, dataVersion: '1' } as WireEnvelope<unknown>
+      if (name === 'referral.claim') {
+        return ((args[0] as { email: string }).email === 'mia@example.com'
+          ? { ok: false, error: { code: 'self', requestId: 'r' } }
+          : { ok: true, data: { ok: true, code: 'FRIEND-AB12CD34', expiresAt: null }, dataVersion: '1' }) as WireEnvelope<unknown>
+      }
+      if (name === 'referral.invite') return { ok: true, data: { ok: true }, dataVersion: '1' } as WireEnvelope<unknown>
+      return { ok: false, error: { code: 'unknown_operation', requestId: 'r' } }
+    },
+  }
+  return { remote, calls }
+}
+
+function Page({ remote, children }: { remote: AbiRemote | null; children?: JSX.Element }): JSX.Element {
+  return (
+    <DataProvider value={createDataApi(PAGE_DATA, null)}>
+      <ThemeProvider settings={{}} locale={localeStrings('en', LOCALES)}>
+        <AbiCartProvider initial={null} remote={null}>
+          <AbiRewardsProvider remote={remote}>
+            <AbiShell location="/" locale="en" settings={{}} preview={false}>
+              {children ?? <SectionTree tree={[]} />}
+            </AbiShell>
+          </AbiRewardsProvider>
+        </AbiCartProvider>
+      </ThemeProvider>
+    </DataProvider>
+  )
+}
+
+let root: Root | null = null
+let host: HTMLElement | null = null
+function unmount(): void {
+  act(() => root?.unmount())
+  host?.remove()
+  root = host = null
+}
+afterEach(unmount)
+
+const settle = () => act(() => new Promise((r) => setTimeout(r, 30)))
+async function mount(remote: AbiRemote | null, children?: JSX.Element): Promise<HTMLElement> {
+  unmount()
+  host = document.body.appendChild(document.createElement('div'))
+  root = createRoot(host)
+  act(() => root!.render(<Page remote={remote}>{children}</Page>))
+  await settle()
+  return host
+}
+const launcher = (el: HTMLElement) => el.querySelector<HTMLButtonElement>('button[aria-label="Open rewards"]')
+const dialog = (el: HTMLElement) => el.querySelector<HTMLElement>('[role="dialog"][aria-label="Rewards"]')!
+const isOpen = (el: HTMLElement) => dialog(el).closest('.nv-overlay')!.hasAttribute('data-open')
+const key = (k: string, init: KeyboardEventInit = {}) => act(() => void document.dispatchEvent(new KeyboardEvent('keydown', { key: k, bubbles: true, ...init })))
+const itemFor = (el: HTMLElement, text: string) => [...dialog(el).querySelectorAll('li')].find((li) => li.textContent?.includes(text))!
+
+describe('rewards launcher', () => {
+  it('a member opens it and sees the balance, pending points, tier progress, rewards and codes', async () => {
+    const el = await mount(hostWith(MEMBER).remote)
+    const button = launcher(el)!
+    expect(button.textContent).toBe('Rewards')
+    expect(button.getAttribute('aria-haspopup')).toBe('dialog')
+    expect(isOpen(el)).toBe(false)
+    act(() => button.click())
+    await settle()
+    expect(isOpen(el)).toBe(true)
+    const d = dialog(el)
+    expect(d.getAttribute('aria-modal')).toBe('true')
+    expect(d.textContent).toContain('1,250 points')
+    expect(d.textContent).toContain('40 points pending')
+    expect(d.textContent).toContain('Gold')
+    const bar = d.querySelector('[role="progressbar"]')!
+    expect([bar.getAttribute('aria-valuemin'), bar.getAttribute('aria-valuemax'), bar.getAttribute('aria-valuenow')]).toEqual(['0', '5000', '3000'])
+    expect(d.querySelector(`#${CSS.escape(bar.getAttribute('aria-labelledby')!)}`)?.textContent).toBe('2,000 more points to reach Platinum')
+    expect(itemFor(el, '฿100 off').querySelector('button')?.textContent).toBe('Get a code')
+    expect(itemFor(el, '฿500 off').querySelector('button')).toBeNull()
+    expect(itemFor(el, '฿500 off').textContent).toContain('250 more points needed')
+    const code = itemFor(el, 'LOYALTY-OLD111')
+    expect(code.querySelector('button')?.getAttribute('aria-label')).toBe('Copy LOYALTY-OLD111')
+    expect(code.querySelector('a')?.textContent).toBe('Apply to cart')
+    expect(code.querySelector('a')?.getAttribute('href')).toBe('/discount/LOYALTY-OLD111?redirect=%2Fcart')
+    expect(itemFor(el, 'Place an order').textContent).toContain('10 points for every')
+    expect(itemFor(el, 'Create an account').textContent).toContain('Done')
+    expect(itemFor(el, 'Place an order').textContent).not.toContain('Done')
+    expect(d.querySelector('a[href="/account/rewards"]')?.textContent).toBe('View my rewards')
+  })
+
+  it('Escape closes it and gives focus back to the launcher; Tab stays inside while it is open', async () => {
+    // jsdom lays nothing out (offsetParent is always null): give every element a parent box so the trap sees them.
+    const desc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetParent')!
+    Object.defineProperty(HTMLElement.prototype, 'offsetParent', { configurable: true, get() { return this.parentElement } })
+    try {
+      const el = await mount(hostWith(MEMBER).remote)
+      const button = launcher(el)!
+      button.focus()
+      act(() => button.click())
+      await settle()
+      const d = dialog(el)
+      expect(d.contains(document.activeElement)).toBe(true)
+      const focusables = [...d.querySelectorAll<HTMLElement>('a[href], button:not([disabled])')]
+      focusables[focusables.length - 1].focus()
+      key('Tab')
+      expect(document.activeElement).toBe(focusables[0])
+      key('Tab', { shiftKey: true })
+      expect(document.activeElement).toBe(focusables[focusables.length - 1])
+      key('Escape')
+      await settle()
+      expect(isOpen(el)).toBe(false)
+      expect(document.activeElement).toBe(button)
+    } finally {
+      Object.defineProperty(HTMLElement.prototype, 'offsetParent', desc)
+    }
+  })
+
+  it('Get a code turns points into a code with a fresh idempotency key, says it and lists it with Apply to cart', async () => {
+    const { remote, calls } = hostWith(MEMBER)
+    const el = await mount(remote)
+    act(() => launcher(el)!.click())
+    await settle()
+    act(() => itemFor(el, '฿100 off').querySelector('button')!.click())
+    await settle()
+    const redeem = calls.filter((c) => c.kind === 'action' && c.name === 'loyalty.redeem')
+    expect(redeem).toHaveLength(1)
+    const [arg] = redeem[0].args as [{ rewardId: string; key: string }]
+    expect(arg.rewardId).toBe('rw-100')
+    expect(arg.key).toMatch(/^[A-Za-z0-9_-]{16,64}$/)
+    expect(dialog(el).querySelector('[role="status"]')?.textContent).toBe('Your code is ready: LOYALTY-NEW222')
+    expect(dialog(el).textContent).toContain('250 points')
+    expect(itemFor(el, 'LOYALTY-NEW222').querySelector('a')?.getAttribute('href')).toBe('/discount/LOYALTY-NEW222?redirect=%2Fcart')
+  })
+
+  it('a guest sees the program, ways to earn and Join now or Sign in, and no balance', async () => {
+    const el = await mount(hostWith(GUEST).remote)
+    act(() => launcher(el)!.click())
+    await settle()
+    const d = dialog(el)
+    expect(d.textContent).toContain('Leaf Club')
+    expect(d.querySelector('a[href="/account/register"]')?.textContent).toBe('Join now')
+    expect(d.querySelector('a[href="/account/login"]')?.textContent).toBe('Sign in')
+    expect(itemFor(el, 'Create an account').textContent).toContain('100 points')
+    expect(d.querySelector('[role="progressbar"]')).toBeNull()
+    expect(d.textContent).not.toContain('Get a code')
+  })
+
+  it('renders nothing for a store with loyalty off, a host without loyalty, or on the server', async () => {
+    const off = hostWith({ enabled: false })
+    expect(launcher(await mount(off.remote))).toBeNull()
+    expect(off.calls.filter((c) => c.name.startsWith('loyalty.')).map((c) => c.name)).toEqual(['loyalty.state'])
+    expect(launcher(await mount(hostWith(undefined).remote))).toBeNull()
+    const html = renderToString(<Page remote={null} />)
+    expect(html).toContain('data-tq-client-slot="rewards"')
+    expect(html).not.toContain('Open rewards')
+  })
+})
+
+describe('earn hint', () => {
+  const PRICE = { amount: 1290, currencyCode: 'THB' }
+  const hint = (el: HTMLElement) => el.querySelector('.nv-earn-hint')!
+
+  it('a member earns at the earn rate times the tier multiplier, rounded down', async () => {
+    const el = await mount(hostWith(MEMBER).remote, <EarnHint amount={PRICE} scope="item" />)
+    expect(hint(el).textContent).toBe('Earn 193 points with this item')
+    expect(hint(el).querySelector('a')).toBeNull()
+  })
+
+  it('a guest earns at the earn rate and is asked to sign in to collect', async () => {
+    const el = await mount(hostWith(GUEST).remote, <EarnHint amount={PRICE} scope="order" />)
+    expect(hint(el).querySelector('span')?.textContent).toBe('Earn 129 points with this order')
+    expect(hint(el).querySelector('a[href="/account/login"]')?.textContent).toBe('Sign in to collect your points')
+  })
+
+  it('says nothing in a currency the program does not earn in, with loyalty off, or on the server', async () => {
+    expect(hint(await mount(hostWith(MEMBER).remote, <EarnHint amount={{ amount: 50, currencyCode: 'USD' }} scope="item" />)).textContent).toBe('')
+    expect(hint(await mount(hostWith({ enabled: false }).remote, <EarnHint amount={PRICE} scope="item" />)).textContent).toBe('')
+    expect(renderToString(<Page remote={null}><EarnHint amount={PRICE} scope="item" /></Page>)).toContain('<p class="nv-earn-hint" data-tq-client-slot="earn-hint"></p>')
+  })
+
+  it('earnPoints: floor of amount x rate x multiplier, without float noise', () => {
+    expect(earnPoints(29.9, 'THB', { ...GUEST, program: { name: '', earnRates: { THB: 10 } } })).toBe(299)
+    expect(earnPoints(5, 'THB', GUEST)).toBe(0)
+    expect(earnPoints(1290, 'THB', MEMBER)).toBe(193)
+    expect(earnPoints(1290, 'THB', null)).toBeNull()
+    expect(earnPoints(0, 'THB', GUEST)).toBeNull()
+  })
+})
+
+const LINK = 'https://leaf.example/?ref=MIA7K3QX'
+const ADVOCATE: ReferralState = {
+  ...{ enabled: true, code: 'MIA7K3QX', shareUrl: LINK, offer: { type: 'PERCENTAGE', value: '15', currency: 'THB' } },
+  ...{ reward: { type: 'FIXED_CODE', value: '200.00', points: 0, currency: 'THB' }, stats: { clicks: 12, friendOrders: 3, pending: 2, rewarded: 1 } },
+}
+const OFFER = { enabled: true, code: 'MIA7K3QX', offer: { type: 'FIXED_AMOUNT', value: '100', currency: 'THB' }, minimumOrder: '500.00', advocateFirstName: 'Mia' }
+const button = (el: HTMLElement, label: string) => [...el.querySelectorAll<HTMLButtonElement>('button')].find((b) => (b.getAttribute('aria-label') ?? b.textContent) === label)
+const named = (el: HTMLElement, name: string) => el.querySelector<HTMLElement>(`[role="dialog"][aria-label="${name}"]`)!
+const linkNamed = (el: HTMLElement, name: string) => [...el.querySelectorAll('a')].find((a) => a.textContent === name)
+const offerPanel = (el: HTMLElement) => [...el.querySelectorAll('[role="region"]')].find((r) => r.textContent?.includes('A gift from your friend')) as HTMLElement | undefined
+function type(input: HTMLInputElement, value: string): void {
+  const set = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!
+  act(() => {
+    set.call(input, value)
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+  })
+}
+beforeEach(() => {
+  sessionStorage.clear()
+  for (const c of document.cookie.split('; ').filter(Boolean)) document.cookie = `${c.split('=')[0]}=; Path=/; Max-Age=0`
+  window.history.replaceState(null, '', '/')
+})
+
+describe('referral tab', () => {
+  it('with loyalty on it is the Refer a friend tab: the link, Copy, LINE, WhatsApp, Messenger and X links carrying it, stats', async () => {
+    const el = await mount(hostWith(MEMBER, { referral: ADVOCATE }).remote)
+    act(() => button(el, 'Open rewards')!.click())
+    await settle()
+    const d = named(el, 'Rewards')
+    const tab = [...d.querySelectorAll<HTMLButtonElement>('[role="tab"]')].find((t) => t.textContent === 'Refer a friend')!
+    act(() => tab.click())
+    const panel = d.querySelector<HTMLElement>(`#${CSS.escape(tab.getAttribute('aria-controls')!)}`)!
+    expect(panel.hidden).toBe(false)
+    expect(panel.textContent).toContain('Your friends get 15% off their first order.')
+    expect(panel.textContent).toContain('You get a THB\u00a0200.00 off code for each friend who orders.')
+    const input = panel.querySelector<HTMLInputElement>('input[readonly]')!
+    expect(input.value).toBe(LINK)
+    expect(panel.querySelector(`label[for="${input.id}"]`)?.textContent).toContain('Your link')
+    expect(button(panel, 'Copy link')).toBeTruthy()
+    const href = (name: string) => linkNamed(panel, name)!.getAttribute('href')!
+    expect(href('Share on LINE')).toBe(`https://social-plugins.line.me/lineit/share?url=${encodeURIComponent(LINK)}&text=${encodeURIComponent('Here is 15% off your first order:')}`)
+    expect(decodeURIComponent(href('Share on WhatsApp'))).toBe(`https://wa.me/?text=Here is 15% off your first order: ${LINK}`)
+    expect(href('Share on Messenger')).toBe(`fb-messenger://share/?link=${encodeURIComponent(LINK)}`)
+    expect(href('Share on X')).toContain(`&url=${encodeURIComponent(LINK)}`)
+    expect(linkNamed(panel, 'Share on LINE')!.getAttribute('rel')).toBe('noopener noreferrer')
+    const stats = [...panel.querySelectorAll('dl > div')].map((r) => r.textContent)
+    expect(stats).toEqual(['Link visits12', 'Friends who ordered3', 'Rewards on the way2', 'Rewards earned1'])
+  })
+
+  it('Share by email opens a field and posts the invite', async () => {
+    const { remote, calls } = hostWith(undefined, { referral: ADVOCATE })
+    const el = await mount(remote)
+    act(() => button(el, 'Open refer a friend')!.click())
+    await settle()
+    const d = named(el, 'Refer a friend')
+    const share = button(d, 'Share by email')!
+    expect(share.getAttribute('aria-expanded')).toBe('false')
+    act(() => share.click())
+    expect(share.getAttribute('aria-expanded')).toBe('true')
+    const form = d.querySelector<HTMLFormElement>('form[aria-label="Share by email"]')!
+    type(form.querySelector('input[type="email"]')!, 'ben@example.com')
+    act(() => button(form, 'Send invite')!.click())
+    await settle()
+    expect(calls.filter((c) => c.name === 'referral.invite').map((c) => c.args)).toEqual([[{ email: 'ben@example.com' }]])
+    expect(d.querySelector('.nv-referral [role="status"]')?.textContent).toBe('Invite sent to ben@example.com')
+  })
+
+  it('with loyalty off the launcher is Refer a friend on its own; with both off, or on the server, nothing renders', async () => {
+    const el = await mount(hostWith({ enabled: false }, { referral: ADVOCATE }).remote)
+    expect(button(el, 'Open rewards')).toBeUndefined()
+    act(() => button(el, 'Open refer a friend')!.click())
+    await settle()
+    const d = named(el, 'Refer a friend')
+    expect(d.querySelector('[role="tablist"]')).toBeNull()
+    expect(d.querySelector<HTMLInputElement>('input[readonly]')!.value).toBe(LINK)
+
+    const off = await mount(hostWith({ enabled: false }, { referral: { enabled: false } }).remote)
+    expect(off.querySelector('.nv-rewards-launcher')).toBeNull()
+    const html = renderToString(<Page remote={null} />)
+    expect(html).toContain('data-tq-client-slot="friend-offer"')
+    expect(html).not.toContain('Refer a friend')
+  })
+})
+
+describe('friend offer on ?ref=CODE', () => {
+  it('a new visitor sees the offer, claims it by email, and the code is kept for the session and checkout', async () => {
+    window.history.replaceState(null, '', '/?ref=MIA7K3QX')
+    const { remote, calls } = hostWith(undefined, { referral: { enabled: false }, offer: OFFER })
+    const el = await mount(remote)
+    expect(calls.find((c) => c.name === 'referral.offer')?.args).toEqual(['MIA7K3QX'])
+    expect(document.cookie).toContain('tanqory_ref=MIA7K3QX')
+    const panel = offerPanel(el)!
+    expect(panel.getAttribute('aria-labelledby')).toBe(panel.querySelector('h2')!.id)
+    expect(panel.textContent).toContain('Mia sent you THB\u00a0100.00 off your first order.')
+    expect(panel.textContent).toContain('On orders of THB\u00a0500.00 or more.')
+    const email = panel.querySelector<HTMLInputElement>('input[type="email"]')!
+    expect(panel.querySelector(`label[for="${email.id}"]`)?.textContent).toContain('Email')
+    type(email, 'ben@example.com')
+    act(() => button(panel, 'Claim your offer')!.click())
+    await settle()
+    expect(calls.filter((c) => c.name === 'referral.claim').map((c) => c.args)).toEqual([[{ code: 'MIA7K3QX', email: 'ben@example.com' }]])
+    expect(panel.querySelector('[role="status"]')?.textContent).toBe('Offer claimed. Your discount will be applied at checkout.')
+    expect(document.cookie).toContain('tanqory_ref_claim=FRIEND-AB12CD34')
+
+    // Another page of the same session, without the parameter: the code is still the session's, the panel stays away.
+    window.history.replaceState(null, '', '/products/tea')
+    const next = hostWith(undefined, { referral: { enabled: false }, offer: OFFER })
+    const later = await mount(next.remote)
+    expect(next.calls.find((c) => c.name === 'referral.offer')?.args).toEqual(['MIA7K3QX'])
+    expect(offerPanel(later)).toBeUndefined()
+  })
+
+  it('says why a claim failed; Escape and Close put the panel away for the session', async () => {
+    window.history.replaceState(null, '', '/?ref=MIA7K3QX')
+    const el = await mount(hostWith(undefined, { offer: OFFER }).remote)
+    const panel = offerPanel(el)!
+    type(panel.querySelector<HTMLInputElement>('input[type="email"]')!, 'mia@example.com')
+    act(() => button(panel, 'Claim your offer')!.click())
+    await settle()
+    expect(panel.querySelector('[role="alert"]')?.textContent).toBe('This is your own link. Share it with a friend instead.')
+    act(() => void panel.querySelector('input')!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })))
+    expect(offerPanel(el)).toBeUndefined()
+    expect(offerPanel(await mount(hostWith(undefined, { offer: OFFER }).remote))).toBeUndefined()
+  })
+
+  it('shows nothing to a returning customer, with referrals off, for a host without the op, or without a code', async () => {
+    window.history.replaceState(null, '', '/?ref=MIA7K3QX')
+    expect(offerPanel(await mount(hostWith(undefined, { offer: { enabled: false } }).remote))).toBeUndefined()
+    expect(offerPanel(await mount(hostWith(undefined).remote))).toBeUndefined()
+    sessionStorage.clear()
+    window.history.replaceState(null, '', '/?ref=%3Cscript%3E')
+    const { remote, calls } = hostWith(undefined, { offer: OFFER })
+    expect(offerPanel(await mount(remote))).toBeUndefined()
+    expect(calls.map((c) => c.name)).not.toContain('referral.offer')
+  })
+})

package/templates/nova/tests/schema.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import { defaultsOf, resolveSettings } from '@tanqory/theme-kit'
+import { headerSchema } from '../src/sections/Header/schema'
+import { announcementBarSchema } from '../src/sections/AnnouncementBar/schema'
+import { dividerSchema } from '../src/sections/Divider/schema'
+import { breadcrumbsSchema } from '../src/sections/Breadcrumbs/schema'
+import { groupSchema } from '../src/sections/Group/schema'
+import { iconSchema } from '../src/components/content/blocks/Icon'
+import { spacerSchema } from '../src/sections/Group/blocks/Spacer'
+import { FAMILIES } from '../scripts/compiler/contracts/index'
+
+describe('resolveSettings — the adapter core', () => {
+  it('fills every visible default and omits unsaved legacy fields', () => {
+    const d = defaultsOf(headerSchema)
+    expect(d).toMatchObject({ layout: 'logo-left', sticky: 'always', menuStyle: 'mega', background: 'surface', showCart: true })
+    expect('bg' in d).toBe(false)
+    expect('menu' in d).toBe(false) // a handle, not a prop
+  })
+
+  it('defaults equal the approved contract for every 12A row', () => {
+    for (const s of FAMILIES['12A'].sections) {
+      const schema = [headerSchema, announcementBarSchema, dividerSchema, breadcrumbsSchema, groupSchema].find((x) => x.name === s.name)
+      if (!schema) continue
+      const r = resolveSettings(schema, {})
+      for (const row of s.rows) {
+        const f = (schema.fields as Record<string, { binding: string } | undefined>)[row.name]
+        if (row.status === 'LEGACY-HIDDEN' || f?.binding === 'adapter') continue
+        expect([s.name, row.name, (r.settings as Record<string, unknown>)[row.name]]).toEqual([s.name, row.name, row.def])
+      }
+    }
+  })
+
+  it('maps legacy option values to what they render as, and reports them', () => {
+    const r = resolveSettings(announcementBarSchema, { background: 'surface-secondary' })
+    expect(r.settings.background).toBe('muted')
+    expect(r.issues).toContainEqual({ key: 'background', code: 'legacy-value', value: 'surface-secondary', resolved: 'muted' })
+    expect(resolveSettings(announcementBarSchema, { background: 'primary' }).settings.background).toBe('brand')
+  })
+
+  it('keeps saved LEGACY-HIDDEN values', () => {
+    expect(resolveSettings(headerSchema, { bg: '#F3EDE4' }).settings.bg).toBe('#F3EDE4')
+    expect(resolveSettings(dividerSchema, { thickness: 2 }).settings.thickness).toBe('2')
+    expect(resolveSettings(breadcrumbsSchema, { hideOnMobile: true }).settings.hideOnMobile).toBe(true)
+  })
+
+  it('falls back to the default for an unknown option, never throws', () => {
+    const r = resolveSettings(headerSchema, { layout: 'logo-right' })
+    expect(r.settings.layout).toBe('logo-left')
+    expect(r.issues[0]).toMatchObject({ key: 'layout', code: 'unknown-option' })
+  })
+
+  it('coerces string booleans and numbers, clamps and snaps ranges', () => {
+    expect(resolveSettings(headerSchema, { showCart: 'false' }).settings.showCart).toBe(false)
+    expect(resolveSettings(groupSchema, { columns: '3' }).settings.columns).toBe(3)
+    expect(resolveSettings(groupSchema, { columns: 9 }).settings.columns).toBe(4)
+    expect(resolveSettings(iconSchema, { size: 36 }).settings.size).toBe(32)
+    expect(resolveSettings(spacerSchema, { height: 60 }).settings.height).toBe(48)
+  })
+
+  it('separates handles from props and reports unknown settings', () => {
+    const r = resolveSettings(headerSchema, { menu: 'main-menu', nonsense: 1 })
+    expect(r.handles.menu).toBe('main-menu')
+    expect(r.issues).toContainEqual({ key: 'nonsense', code: 'unknown-setting', value: 1 })
+  })
+})

package/templates/nova/tests/schema.typetest.ts

@@ -0,0 +1,7 @@
+// Compile-time assertions: legacy-hidden fields are optional, adapter fields are not props.
+import type { HeaderSettings } from '../src/sections/Header/Header'
+type Expect<T extends true> = T
+type IsOptional<T, K extends keyof T> = {} extends Pick<T, K> ? true : false
+export type _bgOptional = Expect<IsOptional<HeaderSettings, 'bg'>>
+export type _layoutRequired = Expect<IsOptional<HeaderSettings, 'layout'> extends false ? true : false>
+export type _menuNotAProp = Expect<'menu' extends keyof HeaderSettings ? false : true>