create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/tests/theme-config.test.ts

@@ -0,0 +1,82 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import theme from '../theme.config'
+import { BLOCK_SCHEMAS } from './support/sections'
+import manifest from '../theme.manifest.json'
+import Main from '../src/layouts/Main'
+
+const SECTIONS_DIR = join(__dirname, '../src/sections')
+
+/** Every src/sections/<Name>/schema.ts that declares a section: persisted id → folder. */
+function declaredSections(): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const dir of readdirSync(SECTIONS_DIR, { withFileTypes: true })) {
+    const file = join(SECTIONS_DIR, dir.name, 'schema.ts')
+    if (!dir.isDirectory() || !existsSync(file)) continue
+    const m = /defineSchema\(\s*\{\s*kind:\s*'section',\s*name:\s*'([^']+)'/.exec(readFileSync(file, 'utf8'))
+    if (m) out.set(m[1], dir.name)
+  }
+  return out
+}
+
+describe('theme.config.ts lists every section, once', () => {
+  const declared = declaredSections()
+
+  it('lists every section folder the theme declares, once', () => {
+    expect(theme.sections.map((s) => s.id).sort()).toEqual([...declared.keys()].sort())
+    expect(new Set(theme.sections.map((s) => s.id)).size).toBe(theme.sections.length)
+  })
+  it('each section folder has the standard files', () => {
+    for (const folder of declared.values())
+      for (const f of [`${folder}.tsx`, 'schema.ts', 'presets.ts', 'index.ts']) expect(existsSync(join(SECTIONS_DIR, folder, f)), `${folder}/${f}`).toBe(true)
+  })
+  it('the id is the schema name', () => {
+    for (const s of theme.sections) {
+      expect(s.schema.name).toBe(s.id)
+      expect(s.schema.kind).toBe('section')
+    }
+  })
+  it('every section has an editor title and description', () => {
+    for (const s of theme.sections) {
+      expect(s.title, s.id).toBeTruthy()
+      expect(s.description, s.id).toBeTruthy()
+    }
+  })
+  it('each section declares the block schemas it accepts, and each names the section as a parent', () => {
+    for (const s of theme.sections) {
+      const accepted = [...new Set([...(s.schema.blocks ?? []), ...(s.schema.legacyBlocks ?? [])])].sort()
+      // A block's earlier names (legacyNames) are what its parents keep accepting for saved content.
+      expect([...new Set((s.blocks ?? []).flatMap((b) => [b.name, ...(b.legacyNames ?? [])]))].sort(), s.id).toEqual(accepted)
+      for (const b of s.blocks ?? []) {
+        expect(b.kind, `${s.id} → ${b.name}`).toBe('block')
+        expect(b.parents, `${b.name} lists ${s.id}`).toContain(s.id)
+      }
+    }
+  })
+  it('there is no block no section accepts: the sections are the only block list', () => {
+    const declared = new Set(BLOCK_SCHEMAS)
+    const files = import.meta.glob<Record<string, unknown>>('../src/**/blocks/*.tsx', { eager: true })
+    const orphans = Object.entries(files).flatMap(([path, mod]) =>
+      Object.values(mod).filter((v) => (v as { kind?: string })?.kind === 'block' && !declared.has(v as never)).map((v) => `${path}: ${(v as { name: string }).name}`),
+    )
+    expect(orphans).toEqual([])
+  })
+  it('"Section" means the 50 merchant-placeable sections; blocks and the layout are counted apart', () => {
+    expect(theme.sections).toHaveLength(50)
+    expect(manifest.stats).toMatchObject({ sections: 50, headerFooterSections: 3, blocks: 39, blockSchemas: 41, units: 89, layouts: 0 })
+    // What the editor's Add section picker offers: every catalog unit that is not a block.
+    expect(manifest.sections.filter((u) => u.role !== 'block').map((u) => u.name).sort()).toEqual(theme.sections.map((s) => s.id).sort())
+  })
+  it('no block shares a section\'s name: the catalog has one entry per name, and a block that collapsed into a section could never be offered in "Add block"', () => {
+    const sectionIds = new Set(theme.sections.map((s) => s.id))
+    const blockNames = [...new Set(theme.sections.flatMap((s) => (s.blocks ?? []).map((b) => b.name)))]
+    expect(blockNames.filter((n) => sectionIds.has(n))).toEqual([])
+  })
+  it('only the header zone holds header + announcement bar, the footer zone the footer', () => {
+    expect(theme.sections.filter((s) => s.zone !== 'main').map((s) => `${s.zone}:${s.id}`).sort()).toEqual(['footer:footer', 'header:announcement-bar', 'header:header'])
+  })
+  it('the layout is never a section', () => {
+    expect(theme.sections.some((s) => s.component === (Main as unknown))).toBe(false)
+  })
+})

package/templates/nova/tests/theme-integrity.test.ts

@@ -0,0 +1,315 @@
+/**
+ * Theme content integrity: the templates the theme SHIPS must be renderable by
+ * the sections the theme SHIPS.
+ *
+ * `pnpm manifest:check` proves the manifest matches the code. This proves the
+ * templates match the manifest — the drift that reaches a merchant as a setting
+ * that silently does nothing, a not-found card on their home page, or a
+ * composition the editor would refuse to save.
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import manifest from '../theme.manifest.json'
+import sampleStore from './fixtures/sample-store.json'
+
+interface Node {
+  type?: string
+  settings?: Record<string, unknown>
+  blocks?: Node[]
+}
+
+/** What this test needs from a manifest section entry. `theme.manifest.json` is
+ *  imported for its values; TypeScript infers `never[]` for a section whose
+ *  `allowedBlocks` happens to be empty in the committed file, so the shape is
+ *  stated explicitly here rather than inferred from one sample. */
+interface ManifestSection {
+  name: string
+  attributes: Record<string, { default?: unknown }>
+  allowedBlocks: string[]
+}
+
+const TEMPLATE_DIR = join(__dirname, '..', 'templates')
+const templates = readdirSync(TEMPLATE_DIR)
+  .filter((f) => f.endsWith('.json'))
+  .map((f) => ({
+    name: f.replace(/\.json$/, ''),
+    doc: JSON.parse(readFileSync(join(TEMPLATE_DIR, f), 'utf8')) as { sections?: Node[] },
+  }))
+
+const manifestSections = manifest.sections as unknown as ManifestSection[]
+const sections = new Map<string, ManifestSection>(manifestSections.map((s) => [s.name, s]))
+
+function walk(nodes: Node[] | undefined, visit: (node: Node, parent?: string) => void, parent?: string): void {
+  for (const node of nodes ?? []) {
+    visit(node, parent)
+    walk(node.blocks, visit, node.type)
+  }
+}
+
+describe('templates reference only sections the theme ships', () => {
+  it.each(templates)('$name', ({ doc }) => {
+    const unknown: string[] = []
+    walk(doc.sections, (node) => {
+      if (node.type && !sections.has(node.type)) unknown.push(node.type)
+    })
+    expect(unknown).toEqual([])
+  })
+})
+
+describe('templates only set settings their section declares', () => {
+  it.each(templates)('$name', ({ doc }) => {
+    const undeclared: string[] = []
+    walk(doc.sections, (node) => {
+      const def = node.type ? sections.get(node.type) : undefined
+      if (!def) return
+      for (const key of Object.keys(node.settings ?? {})) {
+        if (!(key in def.attributes)) undeclared.push(`${node.type}.${key}`)
+      }
+    })
+    // A setting the section does not declare is dropped on render and invisible
+    // in the editor — the template appears to configure something it does not.
+    expect(undeclared).toEqual([])
+  })
+})
+
+describe('nested blocks are permitted by their parent', () => {
+  it.each(templates)('$name', ({ doc }) => {
+    const disallowed: string[] = []
+    walk(doc.sections, (node, parent) => {
+      if (!parent || !node.type) return
+      const parentDef = sections.get(parent)
+      if (parentDef && !parentDef.allowedBlocks.includes(node.type)) {
+        disallowed.push(`${parent} > ${node.type}`)
+      }
+    })
+    expect(disallowed).toEqual([])
+  })
+})
+
+describe('starter content makes no claims on the merchant’s behalf', () => {
+  const BANNED = [
+    /free shipping/i,
+    /\d+-day returns?/i,
+    // "Free returns within 30 days" came back in `announcement-bar` after P1-7
+    // removed "30-day returns" — the claim, not its wording, is what is banned.
+    /free returns?/i,
+    /returns? within \d+/i,
+    /organic cotton/i,
+    /ships in \d+ ?h/i,
+    // A discount is a promise the merchant has to honour; "no spam /
+    // unsubscribe anytime" is a policy statement. Both came back in newsletter.
+    /\d+ ?% off/i,
+    /no spam/i,
+    /unsubscribe anytime/i,
+    // Where the goods ship from is the merchant's fact to state.
+    /ships? from our/i,
+    // A reply time is a service promise: "we'll reply within one business day" shipped on the contact page.
+    /reply within/i,
+    /within (one|\d+) business days?/i,
+  ]
+
+  it('no template ships a shipping/returns/materials claim', () => {
+    const hits: string[] = []
+    for (const { name, doc } of templates) {
+      const json = JSON.stringify(doc)
+      for (const re of BANNED) {
+        const m = json.match(re)
+        if (m) hits.push(`${name}: ${m[0]}`)
+      }
+    }
+    expect(hits).toEqual([])
+  })
+
+  it('no section DEFAULT ships one either', () => {
+    // A default reaches a live storefront the moment the section is placed —
+    // `announcement-bar` defaulted to "Free shipping on orders over $50".
+    const hits: string[] = []
+    for (const s of manifestSections) {
+      for (const [key, spec] of Object.entries(s.attributes)) {
+        const value = spec?.default
+        if (typeof value !== 'string') continue
+        for (const re of BANNED) {
+          if (re.test(value)) hits.push(`${s.name}.${key}`)
+        }
+      }
+    }
+    expect(hits).toEqual([])
+  })
+
+  it('no UI or runtime SOURCE ships one in a preset, a default string or a hardcoded fallback', () => {
+    // The two tests above read the manifest, which carries `attributes` but not
+    // the presets, built-in strings and fallbacks in code — `Multicolumn`'s
+    // DEFAULT_ITEMS once shipped "Free shipping — on orders over $50" after the
+    // templates were cleaned. Everything a storefront renders is scanned;
+    // fixtures and test cases are offline example data and are not.
+    const roots = ['src', 'sections', 'locales'].map((d) => join(__dirname, '..', d))
+    const files: string[] = []
+    const walk = (dir: string): void => {
+      let entries: import('node:fs').Dirent[]
+      try {
+        entries = readdirSync(dir, { withFileTypes: true })
+      } catch {
+        return
+      }
+      for (const e of entries) {
+        const full = join(dir, e.name)
+        if (e.isDirectory()) {
+          if (e.name !== 'fixtures' && e.name !== 'test') walk(full)
+        } else if (/\.(tsx?|json)$/.test(e.name) && !/\.test\.tsx?$/.test(e.name)) files.push(full)
+      }
+    }
+    roots.forEach(walk)
+    const hits: string[] = []
+    for (const file of files) {
+      const body = readFileSync(file, 'utf8')
+      // Strip comments so prose ABOUT the removed claims does not trip it.
+      const code = body.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
+      for (const re of BANNED) {
+        const m = code.match(re)
+        if (m) hits.push(`${file.slice(join(__dirname, '..').length + 1)}: ${m[0]}`)
+      }
+    }
+    expect(files.length).toBeGreaterThan(100)
+    // The free-shipping progress line renders only when the platform supplies
+    // the merchant's own threshold (CartDrawer `freeShipping`), never by default.
+    const ALLOWED = [
+      'locales/en.json: free shipping',
+      // KNOWN, NOT ACCEPTED: the approved 12B contract's "slideshow-compact"
+      // preset carries this heading. It shipped before presets moved into
+      // source (the scan could not see the contract JSON). Changing it is a
+      // design decision, so it is pinned here until the contract changes.
+      'src/sections/Slideshow/presets.ts: Free shipping',
+      // KNOWN, NOT ACCEPTED: the approved contract's contact-form `subheading`
+      // default promises a reply time. Same reason as above — the contract
+      // locks it, so changing it is a design decision; pinned until it changes.
+      "src/sections/ContactForm/schema.ts: reply within",
+      'src/sections/ContactForm/schema.ts: within one business day',
+      // The same pinned default as its shipped-copy entry (copy.weReplyWithinOneBusinessDay), so a store that
+      // saved it reads it in its own language. It goes when the default goes.
+      'locales/en.json: reply within',
+      'locales/en.json: within one business day',
+    ]
+    hits.splice(0, hits.length, ...hits.filter((h) => !ALLOWED.includes(h)))
+    expect(hits).toEqual([])
+  })
+})
+
+describe('theme settings schema', () => {
+  it('has no drift between schema and values', () => {
+    expect(manifest.warnings.settingsUndeclared).toEqual([])
+    expect(manifest.warnings.settingsMissingValue).toEqual([])
+  })
+
+  it('records no template drift', () => {
+    expect(manifest.warnings.danglingTemplateRefs).toEqual([])
+    expect(manifest.warnings.unknownTemplateSettings).toEqual([])
+    expect(manifest.warnings.disallowedTemplateBlocks).toEqual([])
+  })
+})
+
+describe('translations', () => {
+  const locales = readdirSync(join(__dirname, '..', 'locales')).filter((f) => f.endsWith('.json'))
+  const load = (f: string): Record<string, string> =>
+    JSON.parse(readFileSync(join(__dirname, '..', 'locales', f), 'utf8'))
+  const en = load('en.json')
+
+  it.each(locales.filter((f) => f !== 'en.json'))('%s covers every en key', (file) => {
+    const other = load(file)
+    // A missing key falls back to English silently; the shopper sees a mixed
+    // page and nothing reports it.
+    expect(Object.keys(en).filter((k) => !(k in other))).toEqual([])
+  })
+})
+
+describe('starter content resolves against the shipped fixtures', () => {
+  // A handle that is not in the v1 runtime's offline sample store (`tests/fixtures/sample-store.json`) renders as an empty row or a
+  // 404 CTA for every merchant who has not yet replaced the starter content,
+  // and for anyone developing offline. `test-collection` / `blazer` / `featured`
+  // were a dev store's handles and shipped in `index.json` for months.
+  const fixtures = new Set(
+    (sampleStore as unknown as { handle: string }[]).map((c) => c.handle),
+  )
+
+  /** Every collection handle a template references, wherever it appears. */
+  const handles = (doc: { sections?: Node[] }): string[] => {
+    const out: string[] = []
+    const walk = (n: Node): void => {
+      const s = n.settings ?? {}
+      for (const [key, value] of Object.entries(s)) {
+        if (typeof value !== 'string' || !value) continue
+        if (key === 'collection') out.push(value)
+        else if (key === 'collections') out.push(...value.split(',').map((h) => h.trim()))
+        else if (key.toLowerCase().endsWith('link')) {
+          const m = /^\/collections\/([^/?#]+)/.exec(value)
+          if (m?.[1]) out.push(m[1])
+        }
+      }
+      n.blocks?.forEach(walk)
+    }
+    doc.sections?.forEach(walk)
+    return out.filter(Boolean)
+  }
+
+  it.each(templates)('$name references only collections that exist', ({ doc }) => {
+    expect(handles(doc).filter((h) => !fixtures.has(h))).toEqual([])
+  })
+
+  /**
+   * Existing in the v1 runtime's offline sample store (`tests/fixtures/sample-store.json`) is NOT enough.
+   *
+   * Those fixtures are the theme's offline/editor data. A handle can be in
+   * them and absent from the shop the theme is installed on — `new-arrivals`
+   * passed the test above and still rendered "No products in this collection
+   * yet" against a live store, exactly as the dev store's `test-collection`
+   * did before it. `all` is the one handle every storefront has.
+   */
+  it.each(templates)('$name starter content only references `all`', ({ doc }) => {
+    expect([...new Set(handles(doc))].filter((h) => h !== 'all')).toEqual([])
+  })
+})
+
+/**
+ * This repository is public. It must describe itself in its own words and never
+ * name another commerce platform, its themes, its template language or its
+ * documentation — a rule the team already applied once by hand and that then
+ * regressed. The list cannot know every name; it pins the ones that have
+ * actually appeared here, across every tracked text file.
+ */
+describe('no third-party platform references in a public repository', () => {
+  const ROOT_DIR = join(__dirname, '..')
+  const SKIP_DIRS = new Set(['node_modules', 'dist', 'dist-ssr', '.git', '.vite', 'qa', 'vendor'])
+  const TEXT = /\.(tsx?|mjs|cjs|js|json|css|md|html|ya?ml|txt)$/
+  // Built from parts so this file does not contain the names it forbids.
+  const FORBIDDEN = new RegExp(
+    [['shop', 'ify'], ['\\bliq', 'uid\\b'], ['\\.liq', 'uid\\b'], ['\\{', '%'], ['my', 'shop', 'ify'], ['woo', 'commerce'], ['big', 'commerce'], ['\\bmag', 'ento\\b']]
+      .map((p) => p.join(''))
+      .join('|'),
+    'i',
+  )
+  const files: string[] = []
+  const scan = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP_DIRS.has(entry.name)) continue
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) scan(full)
+      else if (TEXT.test(entry.name) && entry.name !== 'pnpm-lock.yaml') files.push(full)
+    }
+  }
+  scan(ROOT_DIR)
+
+  it('scans the repository', () => {
+    expect(files.length).toBeGreaterThan(100)
+  })
+
+  it('names no other platform, theme or template language', () => {
+    const hits: string[] = []
+    for (const file of files) {
+      const lines = readFileSync(file, 'utf8').split('\n')
+      lines.forEach((line, i) => {
+        if (FORBIDDEN.test(line)) hits.push(`${file.slice(ROOT_DIR.length + 1)}:${i + 1}: ${line.trim().slice(0, 90)}`)
+      })
+    }
+    expect(hits).toEqual([])
+  })
+})

package/templates/nova/theme.config.ts

@@ -0,0 +1,134 @@
+import { STARTER_TEXT } from './src/sections/starter'
+import { defineTheme } from '@tanqory/theme-kit'
+import { ThemeRoot } from './src/styles/NovaProvider'
+import { BUILTIN_STRINGS, STRINGS_EN } from './src/styles/strings'
+import { Main } from './src/layouts/Main'
+import english from './locales/en.json'
+import { DERIVED_WHEN_UNSET, KEEP_SHIPPED_COPY } from './src/sections/shipped-copy'
+import { SHARED_SETTINGS } from './src/components/section/shared'
+import header from './src/sections/Header'
+import announcementBar from './src/sections/AnnouncementBar'
+import footer from './src/sections/Footer'
+import group from './src/sections/Group'
+import divider from './src/sections/Divider'
+import breadcrumbs from './src/sections/Breadcrumbs'
+import hero from './src/sections/Hero'
+import slideshow from './src/sections/Slideshow'
+import videoHero from './src/sections/VideoHero'
+import promoBanner from './src/sections/PromoBanner'
+import marquee from './src/sections/Marquee'
+import collectionBanner from './src/sections/CollectionBanner'
+import productDetails from './src/sections/ProductDetails'
+import mainCollection from './src/sections/MainCollection'
+import productGrid from './src/sections/ProductGrid'
+import featuredCollection from './src/sections/FeaturedCollection'
+import featuredProduct from './src/sections/FeaturedProduct'
+import collectionList from './src/sections/CollectionList'
+import productRecommendations from './src/sections/ProductRecommendations'
+import recentlyViewed from './src/sections/RecentlyViewed'
+import richText from './src/sections/RichText'
+import imageWithText from './src/sections/ImageWithText'
+import multicolumn from './src/sections/Multicolumn'
+import featureGridBlocks from './src/sections/FeatureGridBlocks'
+import featureHighlights from './src/sections/FeatureHighlights'
+import faq from './src/sections/Faq'
+import collectionLinks from './src/sections/CollectionLinks'
+import imageGallery from './src/sections/ImageGallery'
+import timeline from './src/sections/Timeline'
+import pageBody from './src/sections/PageBody'
+import articleBody from './src/sections/ArticleBody'
+import blogPosts from './src/sections/BlogPosts'
+import teamFounders from './src/sections/TeamFounders'
+import beforeAfter from './src/sections/BeforeAfter'
+import testimonials from './src/sections/Testimonials'
+import logoList from './src/sections/LogoList'
+import trustBadges from './src/sections/TrustBadges'
+import productReviews from './src/sections/ProductReviews'
+import ugcGallery from './src/sections/UgcGallery'
+import shopTheLook from './src/sections/ShopTheLook'
+import comparisonTable from './src/sections/ComparisonTable'
+import cartItems from './src/sections/CartItems'
+import searchResults from './src/sections/SearchResults'
+import account from './src/sections/Account'
+import policyPage from './src/sections/PolicyPage'
+import storeLocator from './src/sections/StoreLocator'
+import newsletter from './src/sections/Newsletter'
+import lineAddFriend from './src/sections/LineAddFriend'
+import contactForm from './src/sections/ContactForm'
+import notFound from './src/sections/NotFound'
+
+/**
+ * Nova — what the platform needs to know about this theme: its sections (in the
+ * order "Add section" lists them), its root provider, its page layout and the
+ * words the breadcrumb trail uses.
+ */
+export default defineTheme({
+  name: 'nova',
+  sections: [
+    header,
+    announcementBar,
+    footer,
+    group,
+    divider,
+    breadcrumbs,
+    hero,
+    slideshow,
+    videoHero,
+    promoBanner,
+    marquee,
+    collectionBanner,
+    productDetails,
+    mainCollection,
+    productGrid,
+    featuredCollection,
+    featuredProduct,
+    collectionList,
+    productRecommendations,
+    recentlyViewed,
+    richText,
+    imageWithText,
+    multicolumn,
+    featureGridBlocks,
+    featureHighlights,
+    faq,
+    collectionLinks,
+    imageGallery,
+    timeline,
+    pageBody,
+    articleBody,
+    blogPosts,
+    teamFounders,
+    beforeAfter,
+    testimonials,
+    logoList,
+    trustBadges,
+    productReviews,
+    ugcGallery,
+    shopTheLook,
+    comparisonTable,
+    cartItems,
+    searchResults,
+    account,
+    policyPage,
+    storeLocator,
+    newsletter,
+    lineAddFriend,
+    contactForm,
+    notFound,
+  ],
+  Provider: ThemeRoot,
+  sharedSettings: SHARED_SETTINGS,
+  // Geist for headings and body, Geist Mono for codes.
+  // Geist is self-hosted (styles/fonts.css): no font CDN in front of the first paint.
+  stylesheets: [],
+  // Instructions to the merchant in the starter content: editor only, never on the live store.
+  starterText: STARTER_TEXT,
+  // Words Nova ships in defaults, templates and presets: shown in the page's language until the merchant writes their own.
+  // Renderers that test a value against the shipped English, or derive an unset one from data, are left alone.
+  shippedCopy: { english, prefix: 'copy.', keep: KEEP_SHIPPED_COPY, derivedWhenUnset: DERIVED_WHEN_UNSET },
+  Layout: Main,
+  labels: (locale) => {
+    const s = BUILTIN_STRINGS[locale.split('-')[0]] ?? STRINGS_EN
+    return { home: s.home, collections: s.collections, search: s.search, cart: s.cart, account: s.account }
+  },
+})