create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/tests/localized-copy.test.ts

@@ -0,0 +1,330 @@
+/**
+ * Shipped copy follows the page's language (@tanqory/theme-kit runtime/render/localized-copy.ts).
+ *
+ * A Thai store showed "Thanks — we'll reply soon." after a contact form was
+ * sent, and "Get in touch" / "Send message" from the starter template it was
+ * installed with: words Nova shipped in English that the merchant never
+ * touched. They now render from `copy.*` in locales/<code>.json; anything the
+ * merchant wrote renders as written.
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import type { RenderContext } from '@tanqory/theme-abi'
+import theme from '../theme.config'
+import en from '../locales/en.json'
+import th from '../locales/th.json'
+import ar from '../locales/ar.json'
+import { copyPlanOf, localizeShippedCopy, shippedCopyOf, unknownCopyRefs } from '@tanqory/theme-kit/runtime'
+import { DERIVED_WHEN_UNSET, KEEP_SHIPPED_COPY } from '../src/sections/shipped-copy'
+import { defineSchema, field } from '@tanqory/theme-kit'
+import type { ContentNode } from '@tanqory/theme-kit/runtime'
+import { render } from '../entry.abi'
+import { abiCtx, pageOf, serverHtml } from './support/abi-ctx'
+
+const EN = en as Record<string, string>
+const TH = th as Record<string, string>
+const AR = ar as Record<string, string>
+
+describe('localizeShippedCopy', () => {
+  const section = defineSchema({ kind: 'section', name: 'demo', family: 'T', blocks: ['item', 'shared'] }, {
+    heading: field.text(''),
+    successMessage: field.text('Thanks'),
+    note: field.text('Old promise', { legacyHidden: true }),
+    url: field.url('Thanks'),
+    layout: field.select(['a', 'b'], 'a'),
+  })
+  const item = defineSchema({ kind: 'block', name: 'item', family: 'T' }, { label: field.text('Item') })
+  const sharedA = defineSchema({ kind: 'block', name: 'shared', family: 'T' }, { body: field.text('Thanks') })
+  const sharedB = defineSchema({ kind: 'block', name: 'shared', family: 'T' }, { body: field.text('') })
+  const fakeTheme = { sections: [{ id: 'demo', schema: section, blocks: [item, sharedA, sharedB] }] }
+  const english = { 'copy.thanks': 'Thanks', 'copy.item': 'Item', 'copy.getInTouch': 'Get in touch', 'copy.old': 'Old promise', 'other.key': 'Hello' }
+  const thai = { ...english, 'copy.thanks': 'ขอบคุณ', 'copy.item': 'รายการ', 'copy.getInTouch': 'ติดต่อเรา', 'copy.old': 'สัญญาเก่า', 'other.key': 'สวัสดี' }
+  const copy = shippedCopyOf(english, 'copy.')
+  const plan = copyPlanOf(fakeTheme)
+  const node = (settings: Record<string, unknown>, blocks?: ContentNode[]): ContentNode => ({ id: 's', type: 'demo', settings, ...(blocks ? { blocks } : {}) }) as ContentNode
+
+  it('renders an unset copy field as its default in the page language', () => {
+    expect(localizeShippedCopy(node({}), copy, thai, plan).settings).toEqual({ successMessage: 'ขอบคุณ' })
+  })
+
+  it('treats a saved value equal to the shipped English as untouched (installed starter content)', () => {
+    expect(localizeShippedCopy(node({ heading: 'Get in touch', successMessage: '  Thanks ' }), copy, thai, plan).settings).toEqual({ heading: 'ติดต่อเรา', successMessage: 'ขอบคุณ' })
+  })
+
+  it('renders what the merchant typed verbatim, in any language', () => {
+    const typed = node({ heading: 'Write to Lumora', successMessage: 'ได้รับข้อความแล้วค่ะ' })
+    expect(localizeShippedCopy(typed, copy, thai, plan)).toBe(typed)
+    // an empty string the merchant saved is theirs too: the default does not come back
+    expect(localizeShippedCopy(node({ successMessage: '' }), copy, thai, plan).settings).toEqual({ successMessage: '' })
+  })
+
+  it('returns the same node on an English page', () => {
+    const n = node({ heading: 'Get in touch' })
+    expect(localizeShippedCopy(n, copy, english, plan)).toBe(n)
+  })
+
+  it('only reads copy keys, and only copy fields (text / textarea / richtext)', () => {
+    const n = node({ url: 'Thanks', layout: 'a', heading: 'Hello' })
+    expect(localizeShippedCopy(n, copy, thai, plan).settings).toEqual({ url: 'Thanks', layout: 'a', heading: 'Hello', successMessage: 'ขอบคุณ' })
+  })
+
+  it('never fills in an unset legacy-hidden field, but localizes a saved one', () => {
+    expect(localizeShippedCopy(node({}), copy, thai, plan).settings).not.toHaveProperty('note')
+    expect(localizeShippedCopy(node({ note: 'Old promise' }), copy, thai, plan).settings).toMatchObject({ note: 'สัญญาเก่า' })
+  })
+
+  it('localizes blocks; a block name two schemas share gets no default they disagree on', () => {
+    const out = localizeShippedCopy(node({ successMessage: 'Mine' }, [
+      { id: 'b1', type: 'item', settings: {} } as ContentNode,
+      { id: 'b2', type: 'item', settings: { label: 'My label' } } as ContentNode,
+      { id: 'b3', type: 'shared', settings: {} } as ContentNode,
+      { id: 'b4', type: 'shared', settings: { body: 'Thanks' } } as ContentNode,
+    ]), copy, thai, plan)
+    expect(out.blocks!.map((b) => b.settings)).toEqual([{ label: 'รายการ' }, { label: 'My label' }, {}, { body: 'ขอบคุณ' }])
+  })
+
+  it('keeps English when the locale has no word for a key', () => {
+    expect(localizeShippedCopy(node({}), copy, { 'copy.item': 'รายการ' }, plan).settings).toEqual({})
+  })
+})
+
+// ── Every word Nova ships has an entry in every locale ───────────────────────
+
+const COPY = new Set(['text', 'textarea', 'richtext'])
+type S = { name?: string; fields?: Record<string, { control?: string; default?: unknown }> }
+const copyKeys = new Map<string, Set<string>>()
+const addSchema = (name: string | undefined, s: S) => {
+  if (!name) return
+  const m = copyKeys.get(name) ?? new Set<string>()
+  for (const [k, f] of Object.entries(s.fields ?? {})) if (COPY.has(f.control ?? '')) m.add(k)
+  copyKeys.set(name, m)
+}
+for (const s of theme.sections as unknown as { id: string; schema: S; blocks?: S[] }[]) {
+  addSchema(s.id, s.schema)
+  for (const b of s.blocks ?? []) addSchema(b.name, b)
+}
+const shipped = new Map<string, string>()
+const KEEP = new Set<string>(KEEP_SHIPPED_COPY)
+const kept = (kind: 'section' | 'block', type: string, key: string) => KEEP.has(`${kind}:${type}.${key}`)
+const put = (v: unknown, where: string) => { if (typeof v === 'string' && v.trim()) shipped.set(v.trim(), where) }
+for (const [kind, t, s] of [...(theme.sections as unknown as { id: string; schema: S; blocks?: S[] }[]).flatMap((x) => [['section', x.id, x.schema] as const, ...(x.blocks ?? []).map((b) => ['block', b.name ?? '', b] as const)])])
+  for (const [k, f] of Object.entries(s.fields ?? {})) if (COPY.has(f.control ?? '') && !kept(kind, t, k)) put(f.default, `default ${t}.${k}`)
+const walk = (x: unknown, where: string, inBlocks = false): void => {
+  if (Array.isArray(x)) return x.forEach((n) => walk(n, where, inBlocks))
+  if (!x || typeof x !== 'object') return
+  const n = x as { type?: unknown; settings?: Record<string, unknown> }
+  if (typeof n.type === 'string' && n.settings) for (const [k, v] of Object.entries(n.settings)) if (copyKeys.get(n.type)?.has(k) && !kept(inBlocks ? 'block' : 'section', n.type, k)) put(v, `${where} ${n.type}.${k}`)
+  for (const [k, v] of Object.entries(x)) if (k !== 'settings') walk(v, where, inBlocks || k === 'blocks')
+}
+for (const s of theme.sections as unknown as { id: string; presets?: { name: string; settings?: unknown; blocks?: unknown }[] }[])
+  for (const p of s.presets ?? []) walk({ type: s.id, settings: p.settings ?? {}, blocks: p.blocks }, `preset ${p.name}`)
+for (const d of ['templates', 'groups']) {
+  const dir = join(__dirname, '..', d)
+  for (const f of readdirSync(dir).filter((x) => x.endsWith('.json'))) walk(JSON.parse(readFileSync(join(dir, f), 'utf8')), `${d}/${f}`)
+}
+/** Not words a shopper reads in a language: a language code, an example address. */
+const NOT_COPY = new Set(['en', 'you@example.com'])
+
+// ── Fields whose renderer has a data / placeholder fallback ──────────────────
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) return e.name === 'node_modules' ? [] : sourceFiles(p)
+    return /\.(ts|tsx)$/.test(e.name) && !/\.test\./.test(e.name) ? [p] : []
+  })
+}
+const SOURCES = ['src', 'lib'].flatMap((d) => sourceFiles(join(__dirname, '..', d))).map((f) => ({ f: f.slice(f.indexOf('/themes/') + 1), s: readFileSync(f, 'utf8') }))
+type Ref = { ref: string; kind: 'section' | 'block'; type: string; key: string; def: unknown }
+const COPY_FIELDS: Ref[] = (theme.sections as unknown as { id: string; schema: S; blocks?: S[] }[]).flatMap((x) => [
+  ...Object.entries(x.schema.fields ?? {}).map(([key, f]) => ({ kind: 'section' as const, type: x.id, key, f })),
+  ...(x.blocks ?? []).flatMap((b) => Object.entries(b.fields ?? {}).map(([key, f]) => ({ kind: 'block' as const, type: b.name ?? '', key, f }))),
+]).filter((r) => COPY.has(r.f.control ?? '')).map((r) => ({ ref: `${r.kind}:${r.type}.${r.key}`, kind: r.kind, type: r.type, key: r.key, def: r.f.default }))
+const esc = (v: string) => v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+describe('no field whose renderer has a data or placeholder fallback is filled by localized copy', () => {
+  it('every shippedCopy reference names a copy field', () => {
+    expect(unknownCopyRefs(theme as never)).toEqual([])
+  })
+
+  it('every default the theme compares a value against is kept as shipped', () => {
+    // `title !== 'Your store'`, `quote === TESTIMONIAL_STARTER`: a translated value would no longer match.
+    const consts = new Map<string, string>()
+    for (const { s } of SOURCES) for (const m of s.matchAll(/export const ([A-Z][A-Z0-9_]+) = (['"])((?:(?!\2).)+)\2/g)) consts.set(m[1]!, m[3]!)
+    const compared = new Set<string>()
+    for (const { s } of SOURCES) {
+      for (const m of s.matchAll(/(?:===|!==)\s*(?:(['"])((?:(?!\1).)+)\1|([A-Z][A-Z0-9_]+)\b)|(?:(['"])((?:(?!\4).)+)\4|\b([A-Z][A-Z0-9_]+))\s*(?:===|!==)/g)) {
+        const v = m[2] ?? m[5] ?? consts.get(m[3] ?? m[6] ?? '')
+        if (v) compared.add(v)
+      }
+    }
+    const missing = COPY_FIELDS.filter((r) => typeof r.def === 'string' && r.def.trim() && compared.has(r.def) && !KEEP.has(r.ref)).map((r) => `${r.ref} (${r.def})`)
+    expect(missing).toEqual([])
+  })
+
+  it('every copy field a data adapter reads unresolved (unset → derived) is never filled in', () => {
+    // sections/data.ts: `if (b.type === 'footer-menu') { … b.settings?.heading … || m?.title }`.
+    const listed = new Set<string>([...DERIVED_WHEN_UNSET, ...KEEP_SHIPPED_COPY])
+    const english = shippedCopyOf(EN, 'copy.')
+    const missing: string[] = []
+    // Only a field with a localizable default can be filled in when unset.
+    for (const r of COPY_FIELDS.filter((x) => typeof x.def === 'string' && english.has(x.def.trim()))) {
+      const typeRe = new RegExp(`\\.type === '${esc(r.type)}'`)
+      const readRe = new RegExp(`\\.settings\\??\\.${esc(r.key)}\\b`)
+      for (const { f, s } of SOURCES) {
+        const lines = s.split('\n')
+        lines.forEach((line, i) => {
+          if (typeRe.test(line) && lines.slice(i, i + 8).some((l) => readRe.test(l)) && !listed.has(r.ref)) missing.push(`${r.ref} (${f}:${i + 1})`)
+        })
+      }
+    }
+    expect([...new Set(missing)]).toEqual([])
+  })
+
+  it('leaves every listed field as the renderer expects on a Thai page', () => {
+    const plan = copyPlanOf(theme as never)
+    const copy = shippedCopyOf(EN, 'copy.')
+    const strings = { ...EN, ...TH }
+    for (const ref of [...KEEP_SHIPPED_COPY, ...DERIVED_WHEN_UNSET]) {
+      const r = COPY_FIELDS.find((x) => x.ref === ref)!
+      const wrap = (settings: Record<string, unknown>): ContentNode =>
+        r.kind === 'section' ? ({ id: 's', type: r.type, settings } as ContentNode) : ({ id: 's', type: 'footer', settings: {}, blocks: [{ id: 'b', type: r.type, settings }] } as ContentNode)
+      const settingsOf = (n: ContentNode) => (r.kind === 'section' ? n.settings : n.blocks![0]!.settings)
+      // unset stays unset: the renderer derives it, or shows its own placeholder
+      expect([ref, settingsOf(localizeShippedCopy(wrap({}), copy, strings, plan))?.[r.key]]).toEqual([ref, undefined])
+      if (KEEP.has(ref) && typeof r.def === 'string') expect([ref, settingsOf(localizeShippedCopy(wrap({ [r.key]: r.def }), copy, strings, plan))?.[r.key]]).toEqual([ref, r.def])
+    }
+  })
+})
+
+describe('shipped copy coverage', () => {
+  const english = shippedCopyOf(EN, 'copy.')
+
+  it('every shipped English default, template and preset string has a copy.* key', () => {
+    const missing = [...shipped].filter(([v]) => !NOT_COPY.has(v) && !english.has(v)).map(([v, where]) => `${where}: ${v}`)
+    expect(missing).toEqual([])
+  })
+
+  it('lists no copy.* key nothing ships any more', () => {
+    expect([...english].filter(([v]) => !shipped.has(v)).map(([, k]) => k)).toEqual([])
+  })
+
+  it.each([['th', TH], ['ar', AR]] as const)('%s translates every copy.* key', (_code, map) => {
+    const untranslated = Object.keys(EN).filter((k) => k.startsWith('copy.') && (!map[k]?.trim() || map[k] === EN[k]))
+    expect(untranslated).toEqual([])
+  })
+
+  it('keeps markup and line structure in translated rich text', () => {
+    for (const map of [TH, AR]) {
+      for (const k of Object.keys(EN).filter((x) => x.startsWith('copy.'))) {
+        expect([k, /^<p>.*<\/p>$/.test(map[k]!)]).toEqual([k, /^<p>.*<\/p>$/.test(EN[k]!)])
+        expect([k, map[k]!.split('\n').length]).toEqual([k, EN[k]!.split('\n').length])
+      }
+    }
+  })
+})
+
+// ── On a rendered page (ABI v2) ──────────────────────────────────────────────
+
+type Submit = (formId: string, fields: Readonly<Record<string, string>>) => Promise<{ ok: true } | { ok: false; reason: string }>
+const chrome = (main: Record<string, unknown>[]) => [
+  { region: 'header', sections: [{ type: 'header', id: 'header' }] },
+  { region: 'main', sections: main },
+  { region: 'footer', sections: [{ type: 'footer', id: 'footer', blocks: [{ type: 'footer-brand', id: 'footer-brand' }] }] },
+]
+function contactPage(settings: Record<string, unknown>, language: string, availableLanguages: string[], post = false) {
+  const { ctx } = abiCtx({ kind: 'home', url: 'https://shop.example/', page: pageOf('index', chrome([{ type: 'contact-form', id: 's-contact', settings }])) })
+  const c = ctx as unknown as { locale: Record<string, unknown>; request: Record<string, unknown>; actions: unknown }
+  c.locale = { ...c.locale, language, availableLanguages }
+  if (post) {
+    c.request = { ...c.request, method: 'POST', formId: 'contact', form: { name: 'Ann', email: 'ann@example.com', message: 'Hello' } }
+    c.actions = { form: { submit: vi.fn<Submit>(async () => ({ ok: true })) } }
+  }
+  return ctx as RenderContext
+}
+// What the QA store saved: the contact template's section, successMessage never set.
+const INSTALLED = { heading: 'Send us a message', subheading: 'We read every note.', buttonLabel: 'Send message', fields: 'name,email,message' }
+
+describe('a Thai store after a contact form is sent', () => {
+  it('shows the untouched success message, heading and button in Thai', async () => {
+    const { root } = await serverHtml(render, contactPage(INSTALLED, 'th', ['th'], true))
+    expect(root).toContain(TH['copy.thanksWeReplySoon'])
+    expect(root).toContain(TH['copy.sendUsAMessage'])
+    expect(root).not.toContain(EN['copy.thanksWeReplySoon'])
+    expect(root).not.toContain('Send us a message')
+  })
+
+  it('shows the button in Thai before sending', async () => {
+    const { root } = await serverHtml(render, contactPage(INSTALLED, 'th', ['th']))
+    expect(root).toContain(TH['copy.sendMessage'])
+    expect(root).not.toContain('>Send message<')
+  })
+
+  it('shows a success message the merchant typed exactly as typed', async () => {
+    const { root } = await serverHtml(render, contactPage({ ...INSTALLED, successMessage: 'Got it, talk soon!' }, 'th', ['th'], true))
+    expect(root).toContain('Got it, talk soon!')
+    expect(root).not.toContain(TH['copy.thanksWeReplySoon'])
+  })
+
+  it('follows the shopper on a store with several languages', async () => {
+    const english = await serverHtml(render, contactPage(INSTALLED, 'en', ['th', 'en'], true))
+    expect(english.root).toContain('Thanks — we’ll reply soon.')
+    expect(english.root).toContain('Send us a message')
+    const thai = await serverHtml(render, contactPage(INSTALLED, 'th', ['th', 'en'], true))
+    expect(thai.root).toContain(TH['copy.thanksWeReplySoon'])
+  })
+})
+
+describe('the footer on a Thai store (data fallbacks win)', () => {
+  const footer = (blocks: Record<string, unknown>[]) => [
+    { region: 'header', sections: [{ type: 'header', id: 'header' }] },
+    { region: 'main', sections: [] },
+    { region: 'footer', sections: [{ type: 'footer', id: 'footer', blocks }] },
+  ]
+  const MENUS = [
+    { handle: 'footer-shop', title: 'เลือกซื้อ', items: [{ id: 'a', title: 'สินค้าทั้งหมด', url: '/collections/all', type: 'HTTP', items: [] }] },
+    { handle: 'footer-help', title: 'ช่วยเหลือ', items: [{ id: 'b', title: 'ติดต่อเรา', url: '/pages/contact', type: 'HTTP', items: [] }] },
+    { handle: 'footer-company', title: 'เกี่ยวกับร้าน', items: [{ id: 'c', title: 'เกี่ยวกับเรา', url: '/pages/about', type: 'HTTP', items: [] }] },
+  ]
+  // groups/footer.json as installed: a brand block and three menu columns, no headings.
+  const INSTALLED = [
+    { type: 'footer-brand', id: 'footer-brand', settings: {} },
+    { type: 'footer-menu', id: 'footer-menu-shop', settings: { menu: 'footer-shop' } },
+    { type: 'footer-menu', id: 'footer-menu-help', settings: { menu: 'footer-help' } },
+    { type: 'footer-menu', id: 'footer-menu-company', settings: { menu: 'footer-company' } },
+  ]
+  async function thaiFooter(blocks: Record<string, unknown>[]) {
+    const { ctx } = abiCtx({ kind: 'home', url: 'https://shop.example/', page: pageOf('index', footer(blocks)), store: { shop: { name: 'Lumora', description: 'เทียนหอมทำมือ', primaryDomain: { url: 'https://shop.example' }, paymentSettings: { currencyCode: 'THB', enabledPresentmentCurrencies: ['THB'] }, shipsToCountries: ['TH'], brand: null }, menus: MENUS as never } })
+    const c = ctx as unknown as { locale: Record<string, unknown> }
+    c.locale = { ...c.locale, language: 'th', availableLanguages: ['th'], country: 'TH', currency: 'THB' }
+    const { root } = await serverHtml(render, ctx as RenderContext)
+    return root.slice(root.lastIndexOf('<footer'))
+  }
+
+  it('heads each menu column with its menu name, not the localized default', async () => {
+    const html = await thaiFooter(INSTALLED)
+    for (const m of MENUS) expect(html).toContain(m.title)
+    expect(html).not.toContain(TH['copy.shop'])
+    expect(html).not.toContain('>Shop<')
+  })
+
+  it('a heading the merchant saved still wins over the menu name', async () => {
+    const html = await thaiFooter([{ type: 'footer-menu', id: 'm', settings: { menu: 'footer-help', heading: 'บริการลูกค้า' } }])
+    expect(html).toContain('บริการลูกค้า')
+  })
+
+  it('shows the store name in the brand block, never the placeholder title', async () => {
+    const html = await thaiFooter(INSTALLED)
+    expect(html).toContain('Lumora')
+    expect(html).not.toContain('ร้านของคุณ')
+    expect(html).not.toContain('Your store')
+  })
+
+  it('keeps the tagline placeholder out of the live storefront', async () => {
+    const html = await thaiFooter(INSTALLED)
+    expect(html).not.toContain('ประโยคสั้น ๆ เกี่ยวกับแบรนด์ของคุณ')
+    expect(html).not.toContain('A short line about your brand.')
+    expect(html).not.toMatch(/nv-footer-brand__tagline/)
+  })
+})

package/templates/nova/tests/product-template-blocks.test.ts

@@ -0,0 +1,28 @@
+/**
+ * The starter product pages carry the buy controls a shopper needs.
+ *
+ * product-details renders its variant picker and quantity stepper only when the template lists those
+ * blocks (ProductDetails.tsx: `blocks.find(... 'variant-picker')`, `has(blocks, 'quantity')`). The starter
+ * template listed neither, so on every new store a product with sizes or colours showed no choice at all
+ * and Add to cart always bought the first variant (QA TC-034, prod 2026-10-16).
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+interface Node { type?: string; blocks?: Node[] }
+const blocksOf = (file: string): string[] => {
+  const doc = JSON.parse(readFileSync(join(__dirname, '..', 'templates', file), 'utf8')) as { sections: Node[] }
+  const main = doc.sections.find((s) => s.type === 'product-details')
+  return (main?.blocks ?? []).map((b) => String(b.type))
+}
+
+describe('starter product templates', () => {
+  for (const file of ['product.json', 'product.bundle.json']) {
+    it(`${file}: product-details lists the variant picker and the quantity stepper`, () => {
+      const types = blocksOf(file)
+      expect(types).toContain('variant-picker')
+      expect(types).toContain('quantity')
+    })
+  }
+})