From d310ebff95a80d0554b8a644420e0e95fc984a56 Mon Sep 17 00:00:00 2001 From: Stefan Bauer Date: Mon, 16 Nov 2026 00:45:20 +0100 Subject: [PATCH 1/5] feat(config): storefront.tags, tagPages and categoryPages Tags are declared as categories are (label, description, old keys), with the same checks. tagPages and categoryPages turn the generated pages on or off, or set their path and the index's title; the two paths must differ. --- packages/config/src/index.ts | 25 +++++++++++++ packages/config/src/validate.spec.ts | 34 +++++++++++++++++ packages/config/src/validate.ts | 56 ++++++++++++++++++++-------- 3 files changed, 99 insertions(+), 16 deletions(-) diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts index 3e5d212..b062997 100644 --- a/packages/config/src/index.ts +++ b/packages/config/src/index.ts @@ -241,8 +241,33 @@ export interface StorefrontConfig { * category, with a note naming the page so it can be updated. */ categories?: Record; + /** + * The tags a page can have (its `tags:`), by key, declared as categories are. Optional: without it every tag works, + * labelled with its key. With it, it is the list, so a typo fails the build; an alias is an old key that still builds. + */ + tags?: Record; + /** + * A page per tag (`/tags//`) and an index of them (`/tags/`), each through the skin's `layouts/tag` and + * `layouts/tags`. Left out: on when the skin has `layouts/tag`. `false`: off. `true` or an object: on, and a missing + * layout is a problem. `path`: the URL segment (default `tags`); `title`: the index page's title (default "Tags"). + */ + tagPages?: boolean | StorefrontTermPages; + /** A page per category and an index of them, as tagPages (`layouts/category`, `layouts/categories`; default path + * `categories`, title "Categories"). */ + categoryPages?: boolean | StorefrontTermPages; } +/** storefront.tagPages and storefront.categoryPages as an object. */ +export interface StorefrontTermPages { + /** The pages' first URL segment: lowercase letters, digits and hyphens. */ + path?: string; + /** The index page's title. */ + title?: string; +} + +/** A declared tag (`storefront.tags.`): the same shape as a category. */ +export type StorefrontTag = StorefrontCategory; + /** A declared category (`storefront.categories.`). */ export interface StorefrontCategory { label: string; diff --git a/packages/config/src/validate.spec.ts b/packages/config/src/validate.spec.ts index 9ff1b2d..3665717 100644 --- a/packages/config/src/validate.spec.ts +++ b/packages/config/src/validate.spec.ts @@ -245,6 +245,40 @@ describe("configProblems — storefront", () => { ]); }); + it("takes tags as categories are: each key a URL segment, with a label, an optional description and old keys", () => { + const base = { pagesDir: "./pages", outDir: "./www" }; + expect(storefront({ ...base, tags: { css: { label: "CSS", aliases: ["styles"] }, "design-tokens": { label: "Design tokens" } } })).toEqual([]); + expect(storefront({ ...base, tags: ["css"] })).toEqual([ + `"storefront.tags" must be an object of tags by key, such as { css: { label: "CSS" } }`, + ]); + expect(storefront({ ...base, tags: { CSS: { label: "CSS" }, js: {}, html: { label: "HTML", aliases: ["js"] } } })).toEqual([ + `"storefront.tags.CSS": a tag's key is part of a URL, so it is lowercase letters, digits and hyphens only`, + `missing required "storefront.tags.js.label"`, + `"storefront.tags.html.aliases": "js" is a tag of its own, so it can't be an old key of "html"`, + ]); + }); + + it("takes tagPages and categoryPages: true, false, or { path, title }", () => { + const base = { pagesDir: "./pages", outDir: "./www" }; + for (const ok of [true, false, {}, { path: "topics" }, { title: "Topics" }, { path: "t2", title: "All tags" }]) { + expect(storefront({ ...base, tagPages: ok }), JSON.stringify(ok)).toEqual([]); + expect(storefront({ ...base, categoryPages: ok }), JSON.stringify(ok)).toEqual([]); + } + expect(storefront({ ...base, tagPages: "yes" })).toEqual([ + `"storefront.tagPages" must be true, false, or { path, title }, such as { path: "topics" }`, + ]); + expect(storefront({ ...base, categoryPages: { path: "Topics/x", slug: 1 } })).toEqual([ + `"storefront.categoryPages.path": the pages' first URL segment, so lowercase letters, digits and hyphens only, such as "topics"`, + `unknown key "storefront.categoryPages.slug"`, + ]); + expect(storefront({ ...base, tagPages: { path: "topics" }, categoryPages: { path: "topics" } })).toEqual([ + `"storefront.tagPages.path" and "storefront.categoryPages.path" are both "topics": tag pages and category pages need a path each`, + ]); + expect(storefront({ ...base, categoryPages: { path: "tags" } })).toEqual([ + `"storefront.tagPages.path" and "storefront.categoryPages.path" are both "tags": tag pages and category pages need a path each`, + ]); + }); + it("accepts a workbench URL with a subpath", () => { const base = { pagesDir: "./pages", outDir: "./www" }; expect(storefront({ ...base, workbenchUrl: "https://htwoo.io/workbench/" })).toEqual([]); diff --git a/packages/config/src/validate.ts b/packages/config/src/validate.ts index 4a14985..c7206eb 100644 --- a/packages/config/src/validate.ts +++ b/packages/config/src/validate.ts @@ -11,7 +11,7 @@ type Rule = | { values: readonly string[]; unsupported?: readonly string[] } | { keys: Shape; required?: readonly string[] } | "packages" | "logo" | "workbench-url" | "site-url" | "lang" | "asset-path" | "host" | "plain-object" | "hbs-file" - | "quality" | "effort" | "categories"; + | "quality" | "effort" | "categories" | "tags" | "term-pages"; type Shape = Readonly>; /** How responsive image variants are encoded: for the project, and overridden per site. */ @@ -63,7 +63,7 @@ const SHAPE: Shape = { keys: { pagesDir: "string", outDir: "string", host: "host", workbenchUrl: "workbench-url", site: "plain-object", url: "site-url", lang: "lang", index: "boolean", image: "asset-path", images: IMAGES, head: "hbs-file", - categories: "categories", + categories: "categories", tags: "tags", tagPages: "term-pages", categoryPages: "term-pages", }, required: ["pagesDir", "outDir"], }, @@ -213,8 +213,17 @@ function checkValue(value: unknown, rule: Rule, at: string, problems: string[]): if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 6) fail("a whole number from 0 to 6 (WebP effort: 0 fastest, 6 smallest)"); return; } - if (rule === "categories") { - checkCategories(value, at, problems); + if (rule === "categories" || rule === "tags") { + checkTerms(value, at, problems, rule === "tags" ? TAG_WORDS : CATEGORY_WORDS); + return; + } + if (rule === "term-pages") { + if (typeof value === "boolean") return; + if (!isObject(value)) { fail(`true, false, or { path, title }, such as { path: "topics" }`); return; } + if (typeof value.path === "string" && !SEGMENT.test(value.path)) { + problems.push(`"${at}.path": the pages' first URL segment, so lowercase letters, digits and hyphens only, such as "topics"`); + } + checkObject(value, TERM_PAGES, [], `${at}.`, problems); return; } if (rule === "plain-object") { @@ -241,36 +250,44 @@ function checkValue(value: unknown, rule: Rule, at: string, problems: string[]): checkObject(value, rule.keys, rule.required ?? [], `${at}.`, problems); } -/** A category's key, and each old key of one: a URL segment (step 4 gives each category a page), as a tag is. */ +/** A category's or tag's key, and each old key of one: a URL segment (each gets a page of its own). */ const SEGMENT = /^[a-z0-9-]+$/; -const CATEGORY: Shape = { label: "string", description: "string", aliases: "strings" }; +const TERM: Shape = { label: "string", description: "string", aliases: "strings" }; +/** storefront.tagPages and storefront.categoryPages as an object. */ +const TERM_PAGES: Shape = { path: "string", title: "string" }; + +/** How the messages name a kind of term. */ +interface TermWords { one: string; example: string } +const CATEGORY_WORDS: TermWords = { one: "category", example: `{ guides: { label: "Guides" } }` }; +const TAG_WORDS: TermWords = { one: "tag", example: `{ css: { label: "CSS" } }` }; /** - * storefront.categories: `{ : { label, description?, aliases? } }`. An alias is a category's old key: pages that - * still name it build, resolved to the category (with a note). So an alias is never a key of its own, and one alias - * leads to one category. + * storefront.categories and storefront.tags: `{ : { label, description?, aliases? } }`. An alias is an old key: + * pages that still name it build, resolved to the term (with a note), and its old page forwards to the new one. So an + * alias is never a key of its own, and one alias leads to one term. */ -function checkCategories(value: unknown, at: string, problems: string[]): void { +function checkTerms(value: unknown, at: string, problems: string[], w: TermWords): void { + const plural = w.one === "category" ? "categories" : `${w.one}s`; if (!isObject(value)) { - problems.push(`"${at}" must be an object of categories by key, such as { guides: { label: "Guides" } }`); + problems.push(`"${at}" must be an object of ${plural} by key, such as ${w.example}`); return; } const claimed = new Map(); for (const [key, category] of Object.entries(value)) { if (!SEGMENT.test(key)) { - problems.push(`"${at}.${key}": a category's key is part of a URL, so it is lowercase letters, digits and hyphens only`); + problems.push(`"${at}.${key}": a ${w.one}'s key is part of a URL, so it is lowercase letters, digits and hyphens only`); continue; } - if (!isObject(category)) { problems.push(`"${at}.${key}" must be an object, such as { label: "Guides" }`); continue; } - checkObject(category, CATEGORY, ["label"], `${at}.${key}.`, problems); + if (!isObject(category)) { problems.push(`"${at}.${key}" must be an object, such as { label: "${w.one === "tag" ? "CSS" : "Guides"}" }`); continue; } + checkObject(category, TERM, ["label"], `${at}.${key}.`, problems); if (!isStrings(category.aliases)) continue; for (const alias of category.aliases as string[]) { if (!SEGMENT.test(alias)) { problems.push(`"${at}.${key}.aliases": "${alias}" is not a key: an old key is lowercase letters, digits and hyphens, as a key is`); } else if (Object.hasOwn(value, alias)) { - problems.push(`"${at}.${key}.aliases": "${alias}" is a category of its own, so it can't be an old key of "${key}"`); + problems.push(`"${at}.${key}.aliases": "${alias}" is a ${w.one} of its own, so it can't be an old key of "${key}"`); } else if (claimed.has(alias)) { - problems.push(`"${at}.${key}.aliases": "${alias}" is an old key of "${claimed.get(alias)}" already: one old key leads to one category`); + problems.push(`"${at}.${key}.aliases": "${alias}" is an old key of "${claimed.get(alias)}" already: one old key leads to one ${w.one}`); } else claimed.set(alias, key); } } @@ -286,6 +303,13 @@ export class ConfigError extends Error { function checkRelations(raw: Record, problems: string[]): void { const sf = raw.storefront; if (!isObject(sf)) return; + // Tag pages and category pages each under a path of their own (when both are on). + const pathOf = (v: unknown, fallback: string): string | undefined => + v === false ? undefined : isObject(v) && typeof v.path === "string" ? v.path : fallback; + const tagPath = pathOf(sf.tagPages, "tags"), categoryPath = pathOf(sf.categoryPages, "categories"); + if (tagPath !== undefined && tagPath === categoryPath) { + problems.push(`"storefront.tagPages.path" and "storefront.categoryPages.path" are both "${tagPath}": tag pages and category pages need a path each`); + } // Three folders that must not share files, so they are pairwise disjoint: not the same folder, and // neither inside the other. Pages are markdown that is not component docs (under patternsDir the // watcher could not tell which an edit belongs to, and the reverse puts component docs among the From b6ad09a16336779aa06dd13bb638bcceb5b65d48 Mon Sep 17 00:00:00 2001 From: Stefan Bauer Date: Mon, 16 Nov 2026 00:46:48 +0100 Subject: [PATCH 2/5] feat(renderer): find a list's items written as text in an each over it --- packages/renderer/src/index.ts | 1 + packages/renderer/src/item-text.ts | 52 ++++++++++++++++++++++++ packages/renderer/test/item-text.spec.ts | 32 +++++++++++++++ 3 files changed, 85 insertions(+) create mode 100644 packages/renderer/src/item-text.ts create mode 100644 packages/renderer/test/item-text.spec.ts diff --git a/packages/renderer/src/index.ts b/packages/renderer/src/index.ts index 64510dd..f2e9754 100644 --- a/packages/renderer/src/index.ts +++ b/packages/renderer/src/index.ts @@ -7,6 +7,7 @@ // from @pattern-dump/discovery — never the old walk. No path reconstruction anywhere. export { initHighlighter, highlight, getShikiCSS, wrapWithCopyButton } from "./highlight"; export { unescapedOutputs, type UnescapedOutput } from "./unescaped"; +export { itemsWrittenAsText, type ItemAsText } from "./item-text"; export { checkSchemaExtensions, QUERY_OPTIONS, readExampleHeight, readProseSlot, type ProseSlot, type SchemaExtensionContext, type SchemaExtensionProblem } from "./schema-extensions"; export { checkSchemaHelperNames, isHelperNameProblem, type SchemaHelperNameProblem } from "./schema-helper-names"; export { helperShadows, type HelperShadow } from "./helper-shadow"; diff --git a/packages/renderer/src/item-text.ts b/packages/renderer/src/item-text.ts new file mode 100644 index 0000000..295e771 --- /dev/null +++ b/packages/renderer/src/item-text.ts @@ -0,0 +1,52 @@ +// A list's items written as text: `{{this}}` or `{{.}}` inside an `{{#each}}` over the list, read from the template's +// AST. A storefront check uses it where a list's items changed from strings to objects (tags in 0.5.0): written as +// text, an object prints "[object Object]", so the page fails and names the field to write instead. +import Handlebars from "handlebars"; + +/** One place an item is written whole: the list's path as the template writes it, and where. */ +export interface ItemAsText { list: string; line: number; column: number } + +type Node = { type: string; loc?: { start: { line: number; column: number } } } & Record; +type PathNode = { type: string; original?: unknown; parts?: unknown }; + +/** Blocks that keep the item as their context: what they hold still writes the item. */ +const SAME_CONTEXT = new Set(["if", "unless"]); + +/** + * Every `{{this}}` / `{{.}}` (escaped or not) written directly in an `{{#each }}` whose path's last segment is + * `name` (`page.tags`, `tags`), also inside its #if and #unless. Not its {{else}}, not inside a block that changes the + * context (another #each, #with), not as a helper's argument. A template that does not parse has none here. + */ +export function itemsWrittenAsText(template: string, name: string): ItemAsText[] { + let ast: Node; + try { ast = Handlebars.parse(template) as unknown as Node; } catch { return []; } + const out: ItemAsText[] = []; + const isItem = (p: PathNode | undefined) => p?.type === "PathExpression" && (p.original === "this" || p.original === "."); + const inEach = (body: unknown[], list: string): void => { + for (const s of body as Node[]) { + if (s.type === "MustacheStatement") { + const params = (s["params"] as unknown[] | undefined) ?? []; + if (params.length === 0 && isItem(s["path"] as PathNode)) { + const loc = s.loc?.start ?? { line: 1, column: 0 }; + out.push({ list, line: loc.line, column: loc.column + 1 }); + } + } else if (s.type === "BlockStatement" && SAME_CONTEXT.has(String((s["path"] as PathNode).original))) { + inEach(((s["program"] as Node | undefined)?.["body"] as unknown[]) ?? [], list); + inEach(((s["inverse"] as Node | undefined)?.["body"] as unknown[]) ?? [], list); + } + } + }; + const visit = (node: unknown): void => { + if (!node || typeof node !== "object") return; + if (Array.isArray(node)) { node.forEach(visit); return; } + const n = node as Node; + if (n.type === "BlockStatement" && (n["path"] as PathNode).original === "each") { + const p = ((n["params"] as PathNode[] | undefined) ?? [])[0]; + const parts = p?.type === "PathExpression" && Array.isArray(p.parts) ? p.parts as string[] : []; + if (parts.at(-1) === name) inEach(((n["program"] as Node | undefined)?.["body"] as unknown[]) ?? [], String(p!.original)); + } + for (const [k, v] of Object.entries(n)) if (k !== "loc" && v && typeof v === "object") visit(v); + }; + visit(ast); + return out; +} diff --git a/packages/renderer/test/item-text.spec.ts b/packages/renderer/test/item-text.spec.ts new file mode 100644 index 0000000..6371b69 --- /dev/null +++ b/packages/renderer/test/item-text.spec.ts @@ -0,0 +1,32 @@ +import { describe, expect, it } from "vitest"; +import { itemsWrittenAsText } from "../src/index.js"; + +describe("itemsWrittenAsText: a list's items written as text in an #each over it", () => { + it("finds {{this}} and {{.}} in an #each over a path ending in the name, with its line and the list's path", () => { + const t = `
    \n{{#each page.tags}}
  • {{this}}
  • {{/each}}\n{{#each tags}}{{.}}{{/each}}\n
`; + expect(itemsWrittenAsText(t, "tags")).toEqual([ + { list: "page.tags", line: 2, column: 24 }, + { list: "tags", line: 3, column: 15 }, + ]); + }); + + it("looks inside #if and #unless, which keep the item as context, also triple-stash", () => { + const t = `{{#each tags}}{{#if @first}}{{{this}}}{{/if}}{{#unless @last}}{{this}}{{/unless}}{{/each}}`; + expect(itemsWrittenAsText(t, "tags").map(f => f.line)).toEqual([1, 1]); + }); + + it("leaves fields of the item, other lists, nested context changes, helpers and the else branch alone", () => { + const t = [ + `{{#each page.tags}}{{label}}{{this.label}}{{/each}}`, + `{{#each page.headings}}{{this}}{{/each}}`, + `{{#each tags}}{{#each ../other}}{{this}}{{/each}}{{#with x}}{{this}}{{/with}}{{/each}}`, + `{{#each tags}}{{upper this}}{{else}}{{this}}{{/each}}`, + `{{#each nottags}}{{this}}{{/each}}`, + ].join("\n"); + expect(itemsWrittenAsText(t, "tags")).toEqual([]); + }); + + it("returns nothing for a template that does not parse", () => { + expect(itemsWrittenAsText(`{{#each tags}}{{this}}`, "tags")).toEqual([]); + }); +}); From ac2c44b24c4ec27d7a09f9cfaabbd8d235e849b0 Mon Sep 17 00:00:00 2001 From: Stefan Bauer Date: Mon, 16 Nov 2026 01:22:21 +0100 Subject: [PATCH 3/5] feat(renderer): say which item a template writes as text (this or .) --- packages/renderer/src/item-text.ts | 4 +- packages/renderer/test/item-text.spec.ts | 4 +- storefront-bench/pattern-dump.config.ts | 6 +++ .../patterns/components/card/card.schema.json | 51 +++++++++++++++---- .../components/card/card~article.json | 2 +- .../layouts/categories/categories.hbs | 10 ++++ .../layouts/categories/categories.json | 14 +++++ .../patterns/layouts/categories/categories.md | 6 +++ .../layouts/categories/categories.schema.json | 24 +++++++++ .../patterns/layouts/category/category.hbs | 8 +++ .../patterns/layouts/category/category.json | 29 +++++++++++ .../src/patterns/layouts/category/category.md | 6 +++ .../layouts/category/category.schema.json | 36 +++++++++++++ .../src/patterns/layouts/home/home.json | 7 ++- .../src/patterns/layouts/listing/listing.json | 27 +++++++++- .../src/patterns/layouts/tag/tag.hbs | 8 +++ .../src/patterns/layouts/tag/tag.json | 29 +++++++++++ .../src/patterns/layouts/tag/tag.md | 6 +++ .../src/patterns/layouts/tag/tag.schema.json | 36 +++++++++++++ .../src/patterns/layouts/tags/tags.hbs | 10 ++++ .../src/patterns/layouts/tags/tags.json | 21 ++++++++ .../src/patterns/layouts/tags/tags.md | 6 +++ .../patterns/layouts/tags/tags.schema.json | 24 +++++++++ 23 files changed, 357 insertions(+), 17 deletions(-) create mode 100644 storefront-bench/src/patterns/layouts/categories/categories.hbs create mode 100644 storefront-bench/src/patterns/layouts/categories/categories.json create mode 100644 storefront-bench/src/patterns/layouts/categories/categories.md create mode 100644 storefront-bench/src/patterns/layouts/categories/categories.schema.json create mode 100644 storefront-bench/src/patterns/layouts/category/category.hbs create mode 100644 storefront-bench/src/patterns/layouts/category/category.json create mode 100644 storefront-bench/src/patterns/layouts/category/category.md create mode 100644 storefront-bench/src/patterns/layouts/category/category.schema.json create mode 100644 storefront-bench/src/patterns/layouts/tag/tag.hbs create mode 100644 storefront-bench/src/patterns/layouts/tag/tag.json create mode 100644 storefront-bench/src/patterns/layouts/tag/tag.md create mode 100644 storefront-bench/src/patterns/layouts/tag/tag.schema.json create mode 100644 storefront-bench/src/patterns/layouts/tags/tags.hbs create mode 100644 storefront-bench/src/patterns/layouts/tags/tags.json create mode 100644 storefront-bench/src/patterns/layouts/tags/tags.md create mode 100644 storefront-bench/src/patterns/layouts/tags/tags.schema.json diff --git a/packages/renderer/src/item-text.ts b/packages/renderer/src/item-text.ts index 295e771..6332722 100644 --- a/packages/renderer/src/item-text.ts +++ b/packages/renderer/src/item-text.ts @@ -4,7 +4,7 @@ import Handlebars from "handlebars"; /** One place an item is written whole: the list's path as the template writes it, and where. */ -export interface ItemAsText { list: string; line: number; column: number } +export interface ItemAsText { list: string; item: "this" | "."; line: number; column: number } type Node = { type: string; loc?: { start: { line: number; column: number } } } & Record; type PathNode = { type: string; original?: unknown; parts?: unknown }; @@ -28,7 +28,7 @@ export function itemsWrittenAsText(template: string, name: string): ItemAsText[] const params = (s["params"] as unknown[] | undefined) ?? []; if (params.length === 0 && isItem(s["path"] as PathNode)) { const loc = s.loc?.start ?? { line: 1, column: 0 }; - out.push({ list, line: loc.line, column: loc.column + 1 }); + out.push({ list, item: (s["path"] as PathNode).original === "." ? "." : "this", line: loc.line, column: loc.column + 1 }); } } else if (s.type === "BlockStatement" && SAME_CONTEXT.has(String((s["path"] as PathNode).original))) { inEach(((s["program"] as Node | undefined)?.["body"] as unknown[]) ?? [], list); diff --git a/packages/renderer/test/item-text.spec.ts b/packages/renderer/test/item-text.spec.ts index 6371b69..707817c 100644 --- a/packages/renderer/test/item-text.spec.ts +++ b/packages/renderer/test/item-text.spec.ts @@ -5,8 +5,8 @@ describe("itemsWrittenAsText: a list's items written as text in an #each over it it("finds {{this}} and {{.}} in an #each over a path ending in the name, with its line and the list's path", () => { const t = `
    \n{{#each page.tags}}
  • {{this}}
  • {{/each}}\n{{#each tags}}{{.}}{{/each}}\n
`; expect(itemsWrittenAsText(t, "tags")).toEqual([ - { list: "page.tags", line: 2, column: 24 }, - { list: "tags", line: 3, column: 15 }, + { list: "page.tags", item: "this", line: 2, column: 24 }, + { list: "tags", item: ".", line: 3, column: 15 }, ]); }); diff --git a/storefront-bench/pattern-dump.config.ts b/storefront-bench/pattern-dump.config.ts index cbd7f66..96c8002 100644 --- a/storefront-bench/pattern-dump.config.ts +++ b/storefront-bench/pattern-dump.config.ts @@ -25,6 +25,12 @@ export default defineConfig({ "design-systems": { label: "Design systems", description: "How a design system is built and kept", aliases: ["ds"] }, guides: { label: "Guides" }, }, + // The tags a page can have: declared, so a typo fails the build. "pictures" is an old key of "images". + tags: { + design: { label: "Design" }, + images: { label: "Images", description: "Pictures, and how pages show them", aliases: ["pictures"] }, + layout: { label: "Layout" }, + }, // The link-preview image of every page that names none of its own. image: "/assets/images/share.png", site: { diff --git a/storefront-bench/src/patterns/components/card/card.schema.json b/storefront-bench/src/patterns/components/card/card.schema.json index b065853..4c88437 100644 --- a/storefront-bench/src/patterns/components/card/card.schema.json +++ b/storefront-bench/src/patterns/components/card/card.schema.json @@ -2,16 +2,49 @@ "type": "object", "description": "One entry of a listing, as Pattern Dump fills it.", "properties": { - "route": { "type": "string" }, - "title": { "type": "string" }, - "description": { "type": ["string", "null"] }, - "date": { "type": ["string", "null"] }, + "route": { + "type": "string" + }, + "title": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "date": { + "type": [ + "string", + "null" + ] + }, "image": { - "type": ["string", "null"], - "x-pd-image": { "widths": [160, 320, 640], "sizes": "8rem" } + "type": [ + "string", + "null" + ], + "x-pd-image": { + "widths": [ + 160, + 320, + 640 + ], + "sizes": "8rem" + } + }, + "tags": { + "type": "array", + "items": { + "type": "object" + } + }, + "draft": { + "type": "boolean" }, - "tags": { "type": "array", "items": { "type": "string" } }, - "draft": { "type": "boolean" }, - "scheduled": { "type": "boolean" } + "scheduled": { + "type": "boolean" + } } } diff --git a/storefront-bench/src/patterns/components/card/card~article.json b/storefront-bench/src/patterns/components/card/card~article.json index 8a53aa8..f462629 100644 --- a/storefront-bench/src/patterns/components/card/card~article.json +++ b/storefront-bench/src/patterns/components/card/card~article.json @@ -1 +1 @@ -{ "route": "/articles/harbour/", "title": "A harbour of cable cars", "description": "The bench's one photograph, and how a listing shows a page's image. A teaser runs as long as the page's description or first paragraph, and the card shows three lines of it.", "date": "2026-11-01", "image": "/assets/images/cable-cars.jpg", "tags": ["images"], "draft": false } +{"route":"/articles/harbour/","title":"A harbour of cable cars","description":"The bench's one photograph, and how a listing shows a page's image. A teaser runs as long as the page's description or first paragraph, and the card shows three lines of it.","date":"2026-11-01","image":"/assets/images/cable-cars.jpg","tags":[{"key":"images","label":"Images","description":null,"route":"/tags/images/"}],"draft":false} diff --git a/storefront-bench/src/patterns/layouts/categories/categories.hbs b/storefront-bench/src/patterns/layouts/categories/categories.hbs new file mode 100644 index 0000000..465ce44 --- /dev/null +++ b/storefront-bench/src/patterns/layouts/categories/categories.hbs @@ -0,0 +1,10 @@ +{{#> partials-base }} +
+

{{title}}

+
    + {{#each page.terms}} +
  • {{label}} ({{count}})
  • + {{/each}} +
+
+{{/partials-base}} diff --git a/storefront-bench/src/patterns/layouts/categories/categories.json b/storefront-bench/src/patterns/layouts/categories/categories.json new file mode 100644 index 0000000..62d3459 --- /dev/null +++ b/storefront-bench/src/patterns/layouts/categories/categories.json @@ -0,0 +1,14 @@ +{ + "title": "Categories", + "page": { + "terms": [ + { + "key": "guides", + "label": "Guides", + "description": null, + "route": "/categories/guides/", + "count": 1 + } + ] + } +} diff --git a/storefront-bench/src/patterns/layouts/categories/categories.md b/storefront-bench/src/patterns/layouts/categories/categories.md new file mode 100644 index 0000000..3e62f5e --- /dev/null +++ b/storefront-bench/src/patterns/layouts/categories/categories.md @@ -0,0 +1,6 @@ +--- +title: Categories +description: The index of the categories, each linked to its page, with its count. +--- + +The index of the categories, generated by Pattern Dump at `/categories/`: `page.terms` is every category with a published page, by label. diff --git a/storefront-bench/src/patterns/layouts/categories/categories.schema.json b/storefront-bench/src/patterns/layouts/categories/categories.schema.json new file mode 100644 index 0000000..e122363 --- /dev/null +++ b/storefront-bench/src/patterns/layouts/categories/categories.schema.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Categories layout", + "description": "The index of the categories: every category with a published page, by label.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The index's title" + }, + "page": { + "type": "object", + "description": "Derived by the storefront for the page", + "properties": { + "terms": { + "description": "Every category with a page: key, label, description, route and count" + } + } + } + } +} diff --git a/storefront-bench/src/patterns/layouts/category/category.hbs b/storefront-bench/src/patterns/layouts/category/category.hbs new file mode 100644 index 0000000..4ddaccd --- /dev/null +++ b/storefront-bench/src/patterns/layouts/category/category.hbs @@ -0,0 +1,8 @@ +{{#> partials-base }} +
+

{{title}}

+ {{#if description}}

{{description}}

{{/if}} +

{{page.term.count}} {{#if (eq page.term.count 1)}}page{{else}}pages{{/if}}

+ {{{page.pages.listing}}} +
+{{/partials-base}} diff --git a/storefront-bench/src/patterns/layouts/category/category.json b/storefront-bench/src/patterns/layouts/category/category.json new file mode 100644 index 0000000..be65de1 --- /dev/null +++ b/storefront-bench/src/patterns/layouts/category/category.json @@ -0,0 +1,29 @@ +{ + "title": "Guides", + "page": { + "term": { + "key": "guides", + "label": "Guides", + "description": null, + "route": "/categories/guides/", + "count": 1 + }, + "pages": { + "entries": [ + { + "route": "/articles/harbour/", + "title": "A harbour of cable cars", + "description": null, + "date": "2026-11-01", + "updated": null, + "image": null, + "tags": [], + "categories": [], + "draft": false, + "scheduled": false + } + ], + "listing": "

Setup

" + } + } +} diff --git a/storefront-bench/src/patterns/layouts/category/category.md b/storefront-bench/src/patterns/layouts/category/category.md new file mode 100644 index 0000000..07bd52f --- /dev/null +++ b/storefront-bench/src/patterns/layouts/category/category.md @@ -0,0 +1,6 @@ +--- +title: Category +description: The page of one category, with every published page in it. +--- + +The page of one category, generated by Pattern Dump for every category a published page is in (`storefront.categoryPages`). Its title is the category's label, `page.term` the category with its count, and its pages are a query with `categories: same`, shown in the compact view. diff --git a/storefront-bench/src/patterns/layouts/category/category.schema.json b/storefront-bench/src/patterns/layouts/category/category.schema.json new file mode 100644 index 0000000..6e429ed --- /dev/null +++ b/storefront-bench/src/patterns/layouts/category/category.schema.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Category layout", + "description": "The page of one category, generated for each category with a published page: its title is the category's label.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The category's label" + }, + "description": { + "type": "string", + "description": "The category's description, when the config gives one" + }, + "page": { + "type": "object", + "description": "Derived by the storefront for the page", + "properties": { + "term": { + "description": "The category: key, label, description, route and its count of pages" + }, + "pages": { + "description": "Every page with the category, newest first, through the compact view", + "x-pd-query": { + "categories": "same", + "sort": "date", + "view": "compact" + } + } + } + } + } +} diff --git a/storefront-bench/src/patterns/layouts/home/home.json b/storefront-bench/src/patterns/layouts/home/home.json index a066238..4058cdc 100644 --- a/storefront-bench/src/patterns/layouts/home/home.json +++ b/storefront-bench/src/patterns/layouts/home/home.json @@ -39,7 +39,12 @@ "date": "2026-11-01", "image": null, "tags": [ - "images" + { + "key": "images", + "label": "Images", + "description": null, + "route": "/tags/images/" + } ], "draft": false }, diff --git a/storefront-bench/src/patterns/layouts/listing/listing.json b/storefront-bench/src/patterns/layouts/listing/listing.json index 0d33267..8583835 100644 --- a/storefront-bench/src/patterns/layouts/listing/listing.json +++ b/storefront-bench/src/patterns/layouts/listing/listing.json @@ -4,8 +4,31 @@ "body": "

The folder's pages, listed by its index.md.

", "page": { "children": [ - { "route": "/articles/harbour/", "title": "A harbour of cable cars", "description": "The bench's one photograph, and how a listing shows a page's image.", "date": "2026-11-01", "image": "/assets/images/cable-cars.jpg", "tags": ["images"], "draft": false }, - { "route": "/articles/plain/", "title": "Plain on purpose", "description": "Why the bench's skin is a wireframe.", "date": "2026-10-02", "image": null, "tags": [], "draft": false } + { + "route": "/articles/harbour/", + "title": "A harbour of cable cars", + "description": "The bench's one photograph, and how a listing shows a page's image.", + "date": "2026-11-01", + "image": "/assets/images/cable-cars.jpg", + "tags": [ + { + "key": "images", + "label": "Images", + "description": null, + "route": "/tags/images/" + } + ], + "draft": false + }, + { + "route": "/articles/plain/", + "title": "Plain on purpose", + "description": "Why the bench's skin is a wireframe.", + "date": "2026-10-02", + "image": null, + "tags": [], + "draft": false + } ] } } diff --git a/storefront-bench/src/patterns/layouts/tag/tag.hbs b/storefront-bench/src/patterns/layouts/tag/tag.hbs new file mode 100644 index 0000000..4ddaccd --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tag/tag.hbs @@ -0,0 +1,8 @@ +{{#> partials-base }} +
+

{{title}}

+ {{#if description}}

{{description}}

{{/if}} +

{{page.term.count}} {{#if (eq page.term.count 1)}}page{{else}}pages{{/if}}

+ {{{page.pages.listing}}} +
+{{/partials-base}} diff --git a/storefront-bench/src/patterns/layouts/tag/tag.json b/storefront-bench/src/patterns/layouts/tag/tag.json new file mode 100644 index 0000000..e73040d --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tag/tag.json @@ -0,0 +1,29 @@ +{ + "title": "Images", + "page": { + "term": { + "key": "images", + "label": "Images", + "description": null, + "route": "/tags/images/", + "count": 1 + }, + "pages": { + "entries": [ + { + "route": "/articles/harbour/", + "title": "A harbour of cable cars", + "description": null, + "date": "2026-11-01", + "updated": null, + "image": null, + "tags": [], + "categories": [], + "draft": false, + "scheduled": false + } + ], + "listing": "

A harbour of cable cars

" + } + } +} diff --git a/storefront-bench/src/patterns/layouts/tag/tag.md b/storefront-bench/src/patterns/layouts/tag/tag.md new file mode 100644 index 0000000..cd4a0a1 --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tag/tag.md @@ -0,0 +1,6 @@ +--- +title: Tag +description: The page of one tag, with every published page that has it. +--- + +The page of one tag, generated by Pattern Dump for every tag a published page has (`storefront.tagPages`). Its title is the tag's label, `page.term` the tag with its count, and its pages are a query with `tags: same`, shown in the compact view. diff --git a/storefront-bench/src/patterns/layouts/tag/tag.schema.json b/storefront-bench/src/patterns/layouts/tag/tag.schema.json new file mode 100644 index 0000000..31278b3 --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tag/tag.schema.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Tag layout", + "description": "The page of one tag, generated for each tag with a published page: its title is the tag's label.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The tag's label" + }, + "description": { + "type": "string", + "description": "The tag's description, when the config gives one" + }, + "page": { + "type": "object", + "description": "Derived by the storefront for the page", + "properties": { + "term": { + "description": "The tag: key, label, description, route and its count of pages" + }, + "pages": { + "description": "Every page with the tag, newest first, through the compact view", + "x-pd-query": { + "tags": "same", + "sort": "date", + "view": "compact" + } + } + } + } + } +} diff --git a/storefront-bench/src/patterns/layouts/tags/tags.hbs b/storefront-bench/src/patterns/layouts/tags/tags.hbs new file mode 100644 index 0000000..465ce44 --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tags/tags.hbs @@ -0,0 +1,10 @@ +{{#> partials-base }} +
+

{{title}}

+
    + {{#each page.terms}} +
  • {{label}} ({{count}})
  • + {{/each}} +
+
+{{/partials-base}} diff --git a/storefront-bench/src/patterns/layouts/tags/tags.json b/storefront-bench/src/patterns/layouts/tags/tags.json new file mode 100644 index 0000000..a6935bb --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tags/tags.json @@ -0,0 +1,21 @@ +{ + "title": "Tags", + "page": { + "terms": [ + { + "key": "design", + "label": "Design", + "description": null, + "route": "/tags/design/", + "count": 2 + }, + { + "key": "images", + "label": "Images", + "description": null, + "route": "/tags/images/", + "count": 1 + } + ] + } +} diff --git a/storefront-bench/src/patterns/layouts/tags/tags.md b/storefront-bench/src/patterns/layouts/tags/tags.md new file mode 100644 index 0000000..024936b --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tags/tags.md @@ -0,0 +1,6 @@ +--- +title: Tags +description: The index of the tags, each linked to its page, with its count. +--- + +The index of the tags, generated by Pattern Dump at `/tags/`: `page.terms` is every tag with a published page, by label. diff --git a/storefront-bench/src/patterns/layouts/tags/tags.schema.json b/storefront-bench/src/patterns/layouts/tags/tags.schema.json new file mode 100644 index 0000000..3b4209e --- /dev/null +++ b/storefront-bench/src/patterns/layouts/tags/tags.schema.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Tags layout", + "description": "The index of the tags: every tag with a published page, by label.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The index's title" + }, + "page": { + "type": "object", + "description": "Derived by the storefront for the page", + "properties": { + "terms": { + "description": "Every tag with a page: key, label, description, route and count" + } + } + } + } +} From b02f9ff350d8f674dd6ed35e61989f1895564177 Mon Sep 17 00:00:00 2001 From: Stefan Bauer Date: Mon, 16 Nov 2026 01:22:23 +0100 Subject: [PATCH 4/5] feat(storefront): tag and category pages, tags as objects - Tags can be declared (storefront.tags), as categories are; without declarations any tag works, labelled with its key. - page.tags and every entry's tags are { key, label, description, route }, and categories gain route. A template that writes a tag as text, or a card declaring tags as strings, stops the page and names the fix. - A page per tag and per category with a published page, and an index of each, through the skin's layouts/tag, tags, category and categories; storefront.tagPages and categoryPages turn them off, ask for them, or set the path and the index's title. Old keys forward. In the sitemap, with JSON-LD CollectionPage. - A query's tags and categories take "same", the page's own. - article:section and articleSection from the categories; article:tag and keywords write labels. - The bench and the starter get the four layouts; the bench's categories E2E is registered and runs. --- packages/cli/src/init/starter.spec.ts | 19 +- .../cli/templates/storefront-fills/config.txt | 6 + .../storefront/pages/articles/hello.md | 1 + .../storefront/pages/articles/related.md | 1 + .../components/listing-card/listing-card.hbs | 2 +- .../components/listing-card/listing-card.json | 14 +- .../listing-card/listing-card.schema.json | 24 +- .../src/patterns/layouts/article/article.hbs | 2 +- .../src/patterns/layouts/article/article.json | 2 +- .../layouts/categories/categories.hbs | 10 + .../layouts/categories/categories.json | 14 + .../patterns/layouts/categories/categories.md | 7 + .../layouts/categories/categories.schema.json | 24 ++ .../patterns/layouts/category/category.hbs | 7 + .../patterns/layouts/category/category.json | 29 ++ .../src/patterns/layouts/category/category.md | 8 + .../layouts/category/category.schema.json | 36 ++ .../src/patterns/layouts/listing/listing.json | 2 +- .../src/patterns/layouts/page/page.hbs | 2 +- .../src/patterns/layouts/page/page.json | 2 +- .../src/patterns/layouts/tag/tag.hbs | 7 + .../src/patterns/layouts/tag/tag.json | 29 ++ .../src/patterns/layouts/tag/tag.md | 8 + .../src/patterns/layouts/tag/tag.schema.json | 36 ++ .../src/patterns/layouts/tags/tags.hbs | 10 + .../src/patterns/layouts/tags/tags.json | 14 + .../src/patterns/layouts/tags/tags.md | 7 + .../patterns/layouts/tags/tags.schema.json | 24 ++ .../src/patterns/views/list/list.json | 7 +- packages/dev-server/src/routes.ts | 12 +- packages/dev-server/src/server-config.ts | 10 +- packages/dev-server/src/storefront/cards.ts | 6 + .../dev-server/src/storefront/categories.ts | 62 +++- .../dev-server/src/storefront/collections.ts | 4 +- packages/dev-server/src/storefront/derived.ts | 26 +- .../src/storefront/frontmatter-contract.ts | 33 +- packages/dev-server/src/storefront/json-ld.ts | 9 +- .../dev-server/src/storefront/listing-keys.ts | 38 +- packages/dev-server/src/storefront/page.ts | 88 ++++- packages/dev-server/src/storefront/pages.ts | 65 +++- packages/dev-server/src/storefront/query.ts | 65 ++-- .../dev-server/src/storefront/site-files.ts | 3 + packages/dev-server/src/storefront/terms.ts | 126 +++++++ packages/dev-server/src/watch.ts | 4 +- .../dev-server/test/storefront-bench.spec.ts | 5 + .../dev-server/test/storefront-build.spec.ts | 33 +- .../dev-server/test/storefront-cards.spec.ts | 9 +- .../test/storefront-categories.spec.ts | 4 +- .../test/storefront-collections.spec.ts | 6 +- .../test/storefront-derived.spec.ts | 6 +- .../dev-server/test/storefront-page.spec.ts | 7 +- .../dev-server/test/storefront-pages.spec.ts | 4 +- .../dev-server/test/storefront-serve.spec.ts | 16 +- .../dev-server/test/storefront-terms.spec.ts | 329 ++++++++++++++++++ storefront-bench/e2e/playwright.config.ts | 4 +- storefront-bench/e2e/seo.spec.ts | 21 +- storefront-bench/e2e/terms.spec.ts | 47 +++ storefront-bench/e2e/workbench.spec.ts | 2 +- .../src/patterns/layouts/doc/doc.md | 2 +- 59 files changed, 1239 insertions(+), 161 deletions(-) create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/categories/categories.hbs create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/categories/categories.json create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/categories/categories.md create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/categories/categories.schema.json create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/category/category.hbs create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/category/category.json create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/category/category.md create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/category/category.schema.json create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tag/tag.hbs create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tag/tag.json create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tag/tag.md create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tag/tag.schema.json create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tags/tags.hbs create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tags/tags.json create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tags/tags.md create mode 100644 packages/cli/templates/storefront/src/patterns/layouts/tags/tags.schema.json create mode 100644 packages/dev-server/src/storefront/terms.ts create mode 100644 packages/dev-server/test/storefront-terms.spec.ts create mode 100644 storefront-bench/e2e/terms.spec.ts diff --git a/packages/cli/src/init/starter.spec.ts b/packages/cli/src/init/starter.spec.ts index 1888cc5..21243c8 100644 --- a/packages/cli/src/init/starter.spec.ts +++ b/packages/cli/src/init/starter.spec.ts @@ -175,7 +175,8 @@ describe("the starter project with a website (--storefront, no examples)", () => expect(graph.occurrences).toEqual([]); expect(graph.components.map(c => [c.id, c.render]).sort()).toEqual( [["components/compact-card", "ok"], ["components/feature-card", "ok"], ["components/grid-card", "ok"], ["components/listing-card", "ok"], ["components/note", "ok"], - ["layouts/article", "ok"], ["layouts/home", "ok"], ["layouts/listing", "ok"], ["layouts/page", "ok"], ["partials/base", "ok"], ["partials/head", "ok"], + ["layouts/article", "ok"], ["layouts/categories", "ok"], ["layouts/category", "ok"], ["layouts/home", "ok"], ["layouts/listing", "ok"], ["layouts/page", "ok"], + ["layouts/tag", "ok"], ["layouts/tags", "ok"], ["partials/base", "ok"], ["partials/head", "ok"], ["views/compact", "ok"], ["views/featured", "ok"], ["views/grid", "ok"], ["views/list", "ok"]]); }, 120_000); @@ -203,7 +204,21 @@ describe("the starter project with a website (--storefront, no examples)", () => expect(articles.body).toContain(`href="${componentCssUrl("components/listing-card").replace(/\.css$/, "")}`); const hello = await onHost(server.port, "live.localhost", "/articles/hello/"); expect(hello.status).toBe(200); - expect(hello.body).toContain(`
  • getting-started
  • notes
`); + // Each tag by its label, linked to its tag page. + expect(hello.body).toContain(``); + // The tag and category pages, and their indexes, through the starter's plain layouts. + const notes = await onHost(server.port, "live.localhost", "/tags/notes/"); + expect(notes.status).toBe(200); + expect(notes.body).toContain(`

notes

`); + expect([...notes.body.matchAll(/

m[1])).toEqual(["/articles/related/", "/articles/hello/"]); + const tags = await onHost(server.port, "live.localhost", "/tags/"); + expect(tags.body).toContain(`
  • getting-started (1)
  • `); + expect(tags.body).toContain(`
  • notes (2)
  • `); + const category = await onHost(server.port, "live.localhost", "/categories/notes/"); + expect(category.status).toBe(200); + expect(category.body).toContain(`

    Notes

    `); + expect(category.body).toContain(`

    Short articles about this site

    `); + expect((await onHost(server.port, "live.localhost", "/categories/")).body).toContain(`
  • Notes (2)
  • `); // Its related articles: the article layout's query (the same folder, by relevance, three), in the compact view. expect(hello.body).toMatch(/

    Related articles<\/h2>\s*
      \s*
    • Related articles<\/a>

      {{title}}

      {{#if date}}

      {{/if}} {{#if description}}

      {{description}}

      {{/if}} - {{#if tags.length}}
        {{#each tags}}
      • {{this}}
      • {{/each}}
      {{/if}} + {{#if tags.length}}
        {{#each tags}}
      • {{#if route}}{{label}}{{else}}{{label}}{{/if}}
      • {{/each}}
      {{/if}} diff --git a/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.json b/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.json index 64c262b..1d7dc78 100644 --- a/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.json +++ b/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.json @@ -4,7 +4,17 @@ "date": "2026-11-14", "description": "The example article. Copy it to start a new one.", "tags": [ - "getting-started", - "notes" + { + "key": "getting-started", + "label": "getting-started", + "description": null, + "route": "/tags/getting-started/" + }, + { + "key": "notes", + "label": "notes", + "description": null, + "route": "/tags/notes/" + } ] } diff --git a/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.schema.json b/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.schema.json index 1e4af59..1ffcf2f 100644 --- a/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.schema.json +++ b/packages/cli/templates/storefront/src/patterns/components/listing-card/listing-card.schema.json @@ -33,9 +33,29 @@ "tags": { "type": "array", "items": { - "type": "string" + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "label": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "route": { + "type": [ + "string", + "null" + ] + } + } }, - "description": "The page's tags" + "description": "The page's tags: each its label, linked to its tag page when the site has one" } } } diff --git a/packages/cli/templates/storefront/src/patterns/layouts/article/article.hbs b/packages/cli/templates/storefront/src/patterns/layouts/article/article.hbs index 1ea176d..cb33d68 100644 --- a/packages/cli/templates/storefront/src/patterns/layouts/article/article.hbs +++ b/packages/cli/templates/storefront/src/patterns/layouts/article/article.hbs @@ -2,7 +2,7 @@

      {{title}}

      {{#if description}}

      {{description}}

      {{/if}} - {{#if page.date}}
      {{#if page.tags.length}}
        {{#each page.tags}}
      • {{this}}
      • {{/each}}
      {{/if}}
      {{/if}} + {{#if page.date}}
      {{#if page.tags.length}}
        {{#each page.tags}}
      • {{#if route}}{{label}}{{else}}{{label}}{{/if}}
      • {{/each}}
      {{/if}}
      {{/if}}
      {{{body}}}
      {{#if page.related.listing}}
      diff --git a/packages/cli/templates/storefront/src/patterns/layouts/article/article.json b/packages/cli/templates/storefront/src/patterns/layouts/article/article.json index cf60a09..6183797 100644 --- a/packages/cli/templates/storefront/src/patterns/layouts/article/article.json +++ b/packages/cli/templates/storefront/src/patterns/layouts/article/article.json @@ -6,7 +6,7 @@ "nav": [{ "route": "/", "title": "Home" }, { "route": "/articles/", "title": "Articles", "current": true }], "page": { "date": "2026-11-14", - "tags": ["notes"], + "tags": [{ "key": "notes", "label": "notes", "description": null, "route": "/tags/notes/" }], "related": { "entries": [{ "route": "/articles/second/", "title": "A second article", "date": "2026-11-15" }], "listing": "" diff --git a/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.hbs b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.hbs new file mode 100644 index 0000000..1a36b88 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.hbs @@ -0,0 +1,10 @@ +{{#> partials-base }} +
      +

      {{title}}

      +
        + {{#each page.terms}} +
      • {{label}} ({{count}})
      • + {{/each}} +
      +
      +{{/partials-base}} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.json b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.json new file mode 100644 index 0000000..6ee99a7 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.json @@ -0,0 +1,14 @@ +{ + "title": "Categories", + "page": { + "terms": [ + { + "key": "notes", + "label": "notes", + "description": null, + "route": "/categories/notes/", + "count": 2 + } + ] + } +} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.md b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.md new file mode 100644 index 0000000..06771f9 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.md @@ -0,0 +1,7 @@ +--- +title: Categories +description: The index of the categories, each linked to its page. +--- + +Pattern Dump makes this page at `/categories/` when the site has category pages: `page.terms` is every category with a published +page, by label, with how many pages have it. diff --git a/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.schema.json b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.schema.json new file mode 100644 index 0000000..4be13ed --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/categories/categories.schema.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Categories", + "description": "The index of the categories, at /categories/: each category with a published page, linked, with its count.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The index's title: \"Categories\", or categoryPages.title in the config" + }, + "page": { + "type": "object", + "description": "What the storefront works out for the page", + "properties": { + "terms": { + "description": "Every category with a page, by label: key, label, description, route and count" + } + } + } + } +} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/category/category.hbs b/packages/cli/templates/storefront/src/patterns/layouts/category/category.hbs new file mode 100644 index 0000000..d8dc13a --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/category/category.hbs @@ -0,0 +1,7 @@ +{{#> partials-base }} +
      +

      {{title}}

      + {{#if description}}

      {{description}}

      {{/if}} +
      {{{page.pages.listing}}}
      +
      +{{/partials-base}} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/category/category.json b/packages/cli/templates/storefront/src/patterns/layouts/category/category.json new file mode 100644 index 0000000..68ca6da --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/category/category.json @@ -0,0 +1,29 @@ +{ + "title": "notes", + "page": { + "term": { + "key": "notes", + "label": "notes", + "description": null, + "route": "/categories/notes/", + "count": 1 + }, + "pages": { + "entries": [ + { + "route": "/articles/hello/", + "title": "Hello, articles", + "description": "The example article.", + "date": "2026-11-14", + "updated": null, + "image": null, + "tags": [], + "categories": [], + "draft": false, + "scheduled": false + } + ], + "listing": "

      The pages, in the list view.

      " + } + } +} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/category/category.md b/packages/cli/templates/storefront/src/patterns/layouts/category/category.md new file mode 100644 index 0000000..47bfd0f --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/category/category.md @@ -0,0 +1,8 @@ +--- +title: Category +description: The page of one category, with every published page that has it. +--- + +Pattern Dump makes this page for every category a published page has, at `/categories//`. Its pages are a query with +`categories: same` (the page's own category), so any view and its card work here. Without this layout the site has no +category pages; `categoryPages: false` in the config turns them off. diff --git a/packages/cli/templates/storefront/src/patterns/layouts/category/category.schema.json b/packages/cli/templates/storefront/src/patterns/layouts/category/category.schema.json new file mode 100644 index 0000000..c77dfbb --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/category/category.schema.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Category", + "description": "The page of one category: Pattern Dump makes one at /categories// for every category a published page has, titled with its label.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The category's label" + }, + "description": { + "type": "string", + "description": "The category's description, when storefront.categories gives one" + }, + "page": { + "type": "object", + "description": "What the storefront works out for the page", + "properties": { + "term": { + "description": "The category: its key, label, description, route and how many pages have it" + }, + "pages": { + "description": "Every page with the category, newest first, in the list view", + "x-pd-query": { + "categories": "same", + "sort": "date", + "view": "list" + } + } + } + } + } +} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/listing/listing.json b/packages/cli/templates/storefront/src/patterns/layouts/listing/listing.json index d9e6425..0ef6b2a 100644 --- a/packages/cli/templates/storefront/src/patterns/layouts/listing/listing.json +++ b/packages/cli/templates/storefront/src/patterns/layouts/listing/listing.json @@ -5,6 +5,6 @@ "site": { "title": __PD_BRAND_JSON__, "footer": "Made with Pattern Dump." }, "nav": [{ "route": "/", "title": "Home" }, { "route": "/articles/", "title": "Articles", "current": true }], "page": { - "listing": "" + "listing": "" } } diff --git a/packages/cli/templates/storefront/src/patterns/layouts/page/page.hbs b/packages/cli/templates/storefront/src/patterns/layouts/page/page.hbs index cbef49b..8581f1f 100644 --- a/packages/cli/templates/storefront/src/patterns/layouts/page/page.hbs +++ b/packages/cli/templates/storefront/src/patterns/layouts/page/page.hbs @@ -2,7 +2,7 @@

      {{title}}

      {{#if description}}

      {{description}}

      {{/if}} - {{#if page.date}}
      {{#if page.tags.length}}
        {{#each page.tags}}
      • {{this}}
      • {{/each}}
      {{/if}}
      {{/if}} + {{#if page.date}}
      {{#if page.tags.length}}
        {{#each page.tags}}
      • {{#if route}}{{label}}{{else}}{{label}}{{/if}}
      • {{/each}}
      {{/if}}
      {{/if}}
      {{{body}}}
      {{#if page.next}}

      {{/if}}
      diff --git a/packages/cli/templates/storefront/src/patterns/layouts/page/page.json b/packages/cli/templates/storefront/src/patterns/layouts/page/page.json index 7db4868..7dff17d 100644 --- a/packages/cli/templates/storefront/src/patterns/layouts/page/page.json +++ b/packages/cli/templates/storefront/src/patterns/layouts/page/page.json @@ -4,5 +4,5 @@ "body": "

      The page's markdown, rendered.

      ", "site": { "title": __PD_BRAND_JSON__, "footer": "Made with Pattern Dump." }, "nav": [{ "route": "/", "title": "Home", "current": true }, { "route": "/about/", "title": "About" }], - "page": { "next": { "route": "/about/", "title": "About" }, "date": "2026-11-14", "tags": ["notes"] } + "page": { "next": { "route": "/about/", "title": "About" }, "date": "2026-11-14", "tags": [{ "key": "notes", "label": "notes", "description": null, "route": "/tags/notes/" }] } } diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.hbs b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.hbs new file mode 100644 index 0000000..d8dc13a --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.hbs @@ -0,0 +1,7 @@ +{{#> partials-base }} +
      +

      {{title}}

      + {{#if description}}

      {{description}}

      {{/if}} +
      {{{page.pages.listing}}}
      +
      +{{/partials-base}} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.json b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.json new file mode 100644 index 0000000..3a3fdb7 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.json @@ -0,0 +1,29 @@ +{ + "title": "notes", + "page": { + "term": { + "key": "notes", + "label": "notes", + "description": null, + "route": "/tags/notes/", + "count": 1 + }, + "pages": { + "entries": [ + { + "route": "/articles/hello/", + "title": "Hello, articles", + "description": "The example article.", + "date": "2026-11-14", + "updated": null, + "image": null, + "tags": [], + "categories": [], + "draft": false, + "scheduled": false + } + ], + "listing": "

      The pages, in the list view.

      " + } + } +} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.md b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.md new file mode 100644 index 0000000..8676dd2 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.md @@ -0,0 +1,8 @@ +--- +title: Tag +description: The page of one tag, with every published page that has it. +--- + +Pattern Dump makes this page for every tag a published page has, at `/tags//`. Its pages are a query with +`tags: same` (the page's own tag), so any view and its card work here. Without this layout the site has no +tag pages; `tagPages: false` in the config turns them off. diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.schema.json b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.schema.json new file mode 100644 index 0000000..0a63eef --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tag/tag.schema.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Tag", + "description": "The page of one tag: Pattern Dump makes one at /tags// for every tag a published page has, titled with its label.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The tag's label" + }, + "description": { + "type": "string", + "description": "The tag's description, when storefront.tags gives one" + }, + "page": { + "type": "object", + "description": "What the storefront works out for the page", + "properties": { + "term": { + "description": "The tag: its key, label, description, route and how many pages have it" + }, + "pages": { + "description": "Every page with the tag, newest first, in the list view", + "x-pd-query": { + "tags": "same", + "sort": "date", + "view": "list" + } + } + } + } + } +} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.hbs b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.hbs new file mode 100644 index 0000000..1a36b88 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.hbs @@ -0,0 +1,10 @@ +{{#> partials-base }} +
      +

      {{title}}

      +
        + {{#each page.terms}} +
      • {{label}} ({{count}})
      • + {{/each}} +
      +
      +{{/partials-base}} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.json b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.json new file mode 100644 index 0000000..27b3d56 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.json @@ -0,0 +1,14 @@ +{ + "title": "Tags", + "page": { + "terms": [ + { + "key": "notes", + "label": "notes", + "description": null, + "route": "/tags/notes/", + "count": 2 + } + ] + } +} diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.md b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.md new file mode 100644 index 0000000..dbd0ecc --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.md @@ -0,0 +1,7 @@ +--- +title: Tags +description: The index of the tags, each linked to its page. +--- + +Pattern Dump makes this page at `/tags/` when the site has tag pages: `page.terms` is every tag with a published +page, by label, with how many pages have it. diff --git a/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.schema.json b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.schema.json new file mode 100644 index 0000000..b61dcb1 --- /dev/null +++ b/packages/cli/templates/storefront/src/patterns/layouts/tags/tags.schema.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Tags", + "description": "The index of the tags, at /tags/: each tag with a published page, linked, with its count.", + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The index's title: \"Tags\", or tagPages.title in the config" + }, + "page": { + "type": "object", + "description": "What the storefront works out for the page", + "properties": { + "terms": { + "description": "Every tag with a page, by label: key, label, description, route and count" + } + } + } + } +} diff --git a/packages/cli/templates/storefront/src/patterns/views/list/list.json b/packages/cli/templates/storefront/src/patterns/views/list/list.json index c693135..6edfb90 100644 --- a/packages/cli/templates/storefront/src/patterns/views/list/list.json +++ b/packages/cli/templates/storefront/src/patterns/views/list/list.json @@ -6,7 +6,12 @@ "date": "2026-11-14", "description": "Its teaser: the page's description, or its first paragraph.", "tags": [ - "notes" + { + "key": "notes", + "label": "notes", + "description": null, + "route": "/tags/notes/" + } ] }, { diff --git a/packages/dev-server/src/routes.ts b/packages/dev-server/src/routes.ts index 1954cb7..8bcc716 100644 --- a/packages/dev-server/src/routes.ts +++ b/packages/dev-server/src/routes.ts @@ -18,7 +18,7 @@ import type { GitDates } from "./storefront/git-dates.js"; import type { IncomingMessage, ServerResponse } from "node:http"; import { basename, extname, join, relative } from "node:path"; import { readFile } from "node:fs/promises"; -import { PD_GENERATION_HEADER, PD_HOSTS, PD_PROTOCOL_HEADER, PD_PROTOCOL_VERSION, PD_ROUTE_PREFIX, PD_ROUTES } from "@pattern-dump/contracts"; +import { PD_GENERATION_HEADER, PD_HOSTS, PD_PROTOCOL_HEADER, PD_PROTOCOL_VERSION, PD_ROUTE_PREFIX, PD_ROUTES, type DiscoveryMap } from "@pattern-dump/contracts"; import type { ApiError, AuditResponse, ComponentDetailResponse, ComponentTree, DiagnosticsGraph, FolderOverview, ImageLookup, RuleTiers, ShellClientConfig, StorefrontPagesResponse, ThemeSummary, VersionInfo, @@ -75,10 +75,12 @@ const printedNotes = new WeakMap>(); /** The website's pages as this server serves them: pd dev shows drafts and scheduled pages; pd build leaves them out, * as if their files weren't there. */ -function readStorefrontPages(ctx: RouteContext, sf: NonNullable): ReturnType { +function readStorefrontPages(ctx: RouteContext, sf: NonNullable, discoveryMap?: DiscoveryMap): ReturnType { return readPages(sf.pagesDir, { workbenchPath: sameHostWorkbenchPath(sf), drafts: ctx.live ? "show" : "leave-out", scheduled: ctx.live ? "show" : "leave-out", - today: ctx.today ?? todayOf(ctx.now()), categories: sf.categories, + today: ctx.today ?? todayOf(ctx.now()), categories: sf.categories, tags: sf.tags, tagPages: sf.tagPages, categoryPages: sf.categoryPages, + // The skin's layouts: tag and category pages are generated through them (terms.ts). + ...(discoveryMap ? { layouts: new Set([...discoveryMap.keys()].filter(id => /^layouts\/[^/~]+$/.test(id)).map(id => id.slice("layouts/".length))) } : {}), }); } @@ -640,7 +642,7 @@ async function routeRequest( if (cfg.storefront && host === cfg.storefront.host) { const discovery = await currentDiscovery(state, patternRoots); const discoveryMap = discovery.discoveryMap; - const model = await readStorefrontPages(ctx, cfg.storefront); + const model = await readStorefrontPages(ctx, cfg.storefront, discoveryMap); if (pathname === PD_ROUTES.pages) { if (model.problems.length) { json(res, 500, { error: model.problems.join("\n") } satisfies ApiError); return; } json(res, 200, { pages: model.pages, nav: model.nav } satisfies StorefrontPagesResponse); @@ -675,7 +677,7 @@ async function routeRequest( } // /404.html, and every address with no page, is the site's 404 page with status 404, as a static host // serves it (a 404 page with problems is a 500 listing them). - const target = pathname === PD_ROUTES.notFound || route === null || (!model.problems.length && !model.files.has(route)) + const target = pathname === PD_ROUTES.notFound || route === null || (!model.problems.length && !model.files.has(route) && !model.generated.has(route)) ? PD_ROUTES.notFound : route; // In pd dev a page links to the workbench of this same process, whatever the config's build-time // URL; pd build passes that URL in, for the built site. diff --git a/packages/dev-server/src/server-config.ts b/packages/dev-server/src/server-config.ts index 5a1e103..5542c00 100644 --- a/packages/dev-server/src/server-config.ts +++ b/packages/dev-server/src/server-config.ts @@ -10,7 +10,7 @@ import { basename, join, resolve } from "node:path"; import type { ImageEncoding } from "@pattern-dump/build"; -import { storefrontBasePath, type PatternDumpConfig, type StorefrontCategory } from "@pattern-dump/config"; +import { storefrontBasePath, type PatternDumpConfig, type StorefrontCategory, StorefrontTermPages } from "@pattern-dump/config"; import { PD_HOSTS, type ThemeSwitch } from "@pattern-dump/contracts"; import type { PatternRoot } from "@pattern-dump/discovery"; import type { ResolvedPackage } from "./packages.js"; @@ -102,6 +102,11 @@ export interface ResolvedConfig { readonly headName: string | undefined; /** storefront.categories: what a page's `categories:` may name. */ readonly categories: Readonly> | undefined; + /** storefront.tags: what a page's `tags:` may name; any tag when left out. */ + readonly tags: Readonly> | undefined; + /** storefront.tagPages and storefront.categoryPages, as the config writes them (terms.ts reads them). */ + readonly tagPages: boolean | StorefrontTermPages | undefined; + readonly categoryPages: boolean | StorefrontTermPages | undefined; } | null; readonly overviewsEnabled: boolean; @@ -242,6 +247,9 @@ export function resolveServerConfig( head: config.storefront.head !== undefined ? resolve(cwd, config.storefront.head) : undefined, headName: config.storefront.head, categories: config.storefront.categories, + tags: config.storefront.tags, + tagPages: config.storefront.tagPages, + categoryPages: config.storefront.categoryPages, } : null, images, overviewsEnabled: config.overviews !== false, diff --git a/packages/dev-server/src/storefront/cards.ts b/packages/dev-server/src/storefront/cards.ts index 325e489..c5129c9 100644 --- a/packages/dev-server/src/storefront/cards.ts +++ b/packages/dev-server/src/storefront/cards.ts @@ -51,6 +51,12 @@ export async function readCard(id: string, owner: string, role: string, discover const outside = [...new Set(declared.filter(k => !ENTRY_FIELDS.includes(k)))]; const problems = outside.map(k => `${id} (${role}, ${owner}) declares "${k}", which a page in a listing doesn't have: ` + `a card declares only the fields Pattern Dump fills (${ENTRY_FIELDS.join(", ")})`); + // Tags were strings before 0.5.0: a card still declaring them so would fail every page with a type mismatch. + const tagItems = (read.schema.properties?.["tags"] as { items?: { type?: unknown } } | undefined)?.items?.type; + if (tagItems === "string" || (Array.isArray(tagItems) && tagItems.includes("string") && !tagItems.includes("object"))) { + problems.push(`${id} (${role}, ${owner}) declares tags as a list of strings, but a tag is an object since 0.5.0 ` + + `(key, label, description, route): declare its items as "type": "object", or leave items out`); + } return problems.length ? { problems } : { card: { id, schema: read.schema, label: `${role} (${id})` }, problems }; } diff --git a/packages/dev-server/src/storefront/categories.ts b/packages/dev-server/src/storefront/categories.ts index a354310..02f5465 100644 --- a/packages/dev-server/src/storefront/categories.ts +++ b/packages/dev-server/src/storefront/categories.ts @@ -1,34 +1,64 @@ -// Categories: what a page is about, independent of the folder it is in, so a page changes category without changing -// its URL. The config declares them (storefront.categories: key, label, optional description, and old keys kept after -// a rename); a page names them in its reserved `categories:` (listing-keys.ts readCategories). A layout gets them as -// page.categories, a listing entry carries them, and site.categories is every declared one, in the config's order, -// when partials/base lists `categories` under site (no shape of its own: a category's shape is Pattern Dump's). +// Tags and categories, "terms": what a page is about, independent of the folder it is in, so a page changes category +// without changing its URL. +// +// - Categories are declared in the config (storefront.categories: key, label, optional description, and old keys +// kept after a rename); a page names them in its reserved `categories:`. +// - Tags may be declared the same way (storefront.tags). Without declarations every tag works, labelled with its +// key; with them, they are the list, as categories are. +// +// A layout gets a page's terms as page.tags and page.categories, `{ key, label, description, route }`, route the +// term's generated page (terms.ts) or null; a listing entry carries them, and site.categories is every declared +// category, in the config's order, when partials/base lists `categories` under site (no shape of its own). import type { StorefrontCategory } from "@pattern-dump/config"; export const CATEGORIES_KEY = "categories"; +/** A kind of term. */ +export type TermKind = "tag" | "category"; + +/** A tag or a category as layouts get it. */ +export interface Term { key: string; label: string; description: string | null; route: string | null } /** A category as layouts get it. */ -export interface Category { key: string; label: string; description: string | null } +export type Category = Term; -/** The declared categories, ready to resolve a page's values against. */ -export interface CategoryIndex { - /** In the config's order. */ - list: Category[]; - byKey: ReadonlyMap; +/** The declared terms of one kind, ready to resolve a page's values against. */ +export interface TermIndex { + kind: TermKind; + /** Whether the config declares them (storefront.tags may be left out: then any tag is one, labelled with its key). */ + declared: boolean; + /** In the config's order. Their route is set once the generated pages are known (pages.ts). */ + list: Term[]; + byKey: ReadonlyMap; /** Old key → the key it is now. */ aliases: ReadonlyMap; } +export type CategoryIndex = TermIndex; + +/** How messages name a kind. */ +export const TERM_WORDS: Readonly> = { + tag: { one: "tag", many: "tags", config: "storefront.tags" }, + category: { one: "category", many: "categories", config: "storefront.categories" }, +}; -/** storefront.categories (already checked by the config's validation), indexed. */ -export function categoryIndex(declared: Readonly> | undefined): CategoryIndex { - const list: Category[] = []; +/** storefront.tags or storefront.categories (already checked by the config's validation), indexed. */ +export function termIndex(kind: TermKind, declared: Readonly> | undefined): TermIndex { + const list: Term[] = []; const aliases = new Map(); for (const [key, c] of Object.entries(declared ?? {})) { - list.push({ key, label: c.label, description: c.description ?? null }); + list.push({ key, label: c.label, description: c.description ?? null, route: null }); for (const a of c.aliases ?? []) aliases.set(a, key); } - return { list, byKey: new Map(list.map(c => [c.key, c])), aliases }; + // Categories are always the declared list (none declared: no page may name one); tags only when declared. + return { kind, declared: kind === "category" || declared !== undefined, list, byKey: new Map(list.map(c => [c.key, c])), aliases }; +} + +/** storefront.categories, indexed. */ +export const categoryIndex = (declared: Readonly> | undefined): CategoryIndex => termIndex("category", declared); + +/** The term `key` of `index` as layouts get it: the declared one, or (undeclared tags) labelled with its key. */ +export function termOf(index: TermIndex, key: string): Term { + return index.byKey.get(key) ?? { key, label: key, description: null, route: null }; } type Obj = Record; diff --git a/packages/dev-server/src/storefront/collections.ts b/packages/dev-server/src/storefront/collections.ts index 706d4e5..e796d11 100644 --- a/packages/dev-server/src/storefront/collections.ts +++ b/packages/dev-server/src/storefront/collections.ts @@ -15,7 +15,7 @@ import { suggest } from "@pattern-dump/config"; import type { DatesMode, GitDates } from "./git-dates.js"; import type { PageModel } from "./pages.js"; -import type { Category } from "./categories.js"; +import type { Category, Term } from "./categories.js"; /** One page in a listing. */ export interface Entry { @@ -25,7 +25,7 @@ export interface Entry { date: string | null; updated: string | null; image: string | null; - tags: string[]; + tags: Term[]; categories: Category[]; draft: boolean; /** Its date is after today: pd dev only, since pd build leaves it out. */ diff --git a/packages/dev-server/src/storefront/derived.ts b/packages/dev-server/src/storefront/derived.ts index 36ed368..c857e5f 100644 --- a/packages/dev-server/src/storefront/derived.ts +++ b/packages/dev-server/src/storefront/derived.ts @@ -11,7 +11,7 @@ import type { StorefrontNavItem, StorefrontPagesResponse } from "@pattern-dump/contracts"; import type { Entry } from "./collections.js"; -import type { Category } from "./categories.js"; +import type { Category, Term } from "./categories.js"; /** A link to another page. */ export interface PageLink { route: string; title: string } @@ -33,23 +33,33 @@ export interface DerivedPage { children: Entry[]; /** The page's date, YYYY-MM-DD: its own, else the day git first saw it. */ date: string | null; - tags: string[]; + /** The page's tags (categories.ts), in its order; [] when it has none. */ + tags: Term[]; /** The page's categories (categories.ts), in its order; [] when it has none. */ categories: Category[]; + /** A generated tag or category page (terms.ts): its term, with its count of pages; null on any other page. */ + term: TermPage | null; + /** A generated index of tags or categories: every term with a page, by label; null on any other page. */ + terms: TermPage[] | null; /** A folder's index.md: its pages rendered through the view it names (views.ts), as HTML; null on any other page. */ listing: string | null; } +/** A tag or category with a generated page, as its page and its index get it. */ +export interface TermPage { key: string; label: string; description: string | null; route: string; count: number } + /** A value with no keys of its own; an object with exactly these fields; a list of one shape. */ export type Shape = "value" | { fields: Record } | { items: Shape }; const LINK: Shape = { fields: { route: "value", title: "value" } }; -/** A category (categories.ts). */ -export const CATEGORY: Shape = { fields: { key: "value", label: "value", description: "value" } }; +/** A tag or a category (categories.ts). */ +export const TERM: Shape = { fields: { key: "value", label: "value", description: "value", route: "value" } }; +export const CATEGORY: Shape = TERM; +const TERM_PAGE: Shape = { fields: { key: "value", label: "value", description: "value", route: "value", count: "value" } }; /** An entry of a listing (collections.ts). */ export const ENTRY: Shape = { fields: { - route: "value", title: "value", description: "value", date: "value", updated: "value", image: "value", tags: "value", + route: "value", title: "value", description: "value", date: "value", updated: "value", image: "value", tags: { items: TERM }, categories: { items: CATEGORY }, draft: "value", scheduled: "value", }, }; @@ -66,14 +76,16 @@ export const PAGE_SHAPE: { fields: Record } = { updated: "value", children: { items: ENTRY }, date: "value", - tags: "value", + tags: { items: TERM }, categories: { items: CATEGORY }, + term: TERM_PAGE, + terms: { items: TERM_PAGE }, listing: "value", }, }; /** The sub-keys of `page` Pattern Dump fills today. Each later step adds the keys it derives. */ -export const FILLED: readonly (keyof DerivedPage)[] = ["headings", "section", "breadcrumbs", "prev", "next", "created", "updated", "children", "date", "tags", "categories", "listing"]; +export const FILLED: readonly (keyof DerivedPage)[] = ["headings", "section", "breadcrumbs", "prev", "next", "created", "updated", "children", "date", "tags", "categories", "term", "terms", "listing"]; /** Sub-keys Pattern Dump filled once and no longer does, with what to declare instead. */ export const RETIRED: Readonly> = { diff --git a/packages/dev-server/src/storefront/frontmatter-contract.ts b/packages/dev-server/src/storefront/frontmatter-contract.ts index 00f9f40..5b51bdd 100644 --- a/packages/dev-server/src/storefront/frontmatter-contract.ts +++ b/packages/dev-server/src/storefront/frontmatter-contract.ts @@ -21,8 +21,8 @@ import { suggest } from "@pattern-dump/config"; import { checkDeclared, readSchema, type PropertySchema } from "./declared-values.js"; import { DEFAULT_LAYOUT, type PageFile } from "./pages.js"; import type { FrontmatterValue } from "../frontmatter.js"; -import { readCategories, readChildLayout, readDate, readDraft, readSort, readTags, readUpdated, readView, type Read, type SortBy } from "./listing-keys.js"; -import { categoryIndex, type CategoryIndex } from "./categories.js"; +import { readChildLayout, readDate, readDraft, readSort, readTerms, readUpdated, readView, type Read, type SortBy } from "./listing-keys.js"; +import { categoryIndex, termIndex, TERM_WORDS, type CategoryIndex, type TermIndex, type TermKind } from "./categories.js"; import { declaredQueries } from "./query.js"; /** Keys the build owns: they are read by the storefront, never passed to the layout. */ @@ -66,7 +66,7 @@ const OLD_ROUTE = /^\/(?:(?!\.\.?\/)[^/?#\s]+\/)+$/; const ASSET_PATH = /^\/assets\/[^?#]+[^/?#]$/; function checkBuildKeys(values: Record, path: string, at: (key: string, message: string) => void, - categories: CategoryIndex, renamed: (from: string, to: string) => void): BuildKeys { + terms: { categories: CategoryIndex; tags: TermIndex }, renamed: (kind: TermKind, from: string, to: string) => void): BuildKeys { const out: BuildKeys = {}; const redirect = values["redirectFrom"]; if (redirect !== undefined) { @@ -87,7 +87,7 @@ function checkBuildKeys(values: Record, path: string, if (typeof image === "string" && ASSET_PATH.test(image)) out.image = image; else at("image", `image must be a path to a file in the assets, such as "/assets/images/share.png"`); } - const take = (key: K, r: Read> | undefined): void => { + const take = (key: K, r: Read> | undefined): void => { if (r === undefined) return; if (r.ok) out[key] = r.value; else at(key, r.message); @@ -95,12 +95,13 @@ function checkBuildKeys(values: Record, path: string, const v = (key: string) => values[key]; take("date", v("date") === undefined ? undefined : readDate(v("date")!)); take("updated", v("updated") === undefined ? undefined : readUpdated(v("updated")!, out.date)); - take("tags", v("tags") === undefined ? undefined : readTags(v("tags")!)); - const cats = v("categories") === undefined ? undefined : readCategories(v("categories")!, categories); - if (cats?.ok) { - out.categories = cats.value.keys; - for (const r of cats.value.renamed) renamed(r.from, r.to); - } else if (cats) at("categories", cats.message); + for (const [key, index] of [["tags", terms.tags], ["categories", terms.categories]] as const) { + const r = v(key) === undefined ? undefined : readTerms(v(key)!, index); + if (r?.ok) { + out[key] = r.value.keys; + for (const x of r.value.renamed) renamed(index.kind, x.from, x.to); + } else if (r) at(key, r.message); + } take("draft", v("draft") === undefined ? undefined : readDraft(v("draft")!)); take("sort", v("sort") === undefined ? undefined : readSort(v("sort")!, path)); take("view", v("view") === undefined ? undefined : readView(v("view")!, path)); @@ -129,8 +130,9 @@ export function layoutNames(discoveryMap: DiscoveryMap): string[] { .sort(); } -/** `categories`: the declared ones (the page model's); none when left out. */ -export async function checkPageFrontmatter(page: PageFile, discoveryMap: DiscoveryMap, categories: CategoryIndex = categoryIndex(undefined)): Promise { +/** `categories` and `tags`: the declared ones (the page model's); no categories and any tag when left out. */ +export async function checkPageFrontmatter(page: PageFile, discoveryMap: DiscoveryMap, categories: CategoryIndex = categoryIndex(undefined), + tags: TermIndex = termIndex("tag", undefined)): Promise { const { values, errors, lines } = page.frontmatter; const problems: PageProblem[] = errors.map(e => ({ file: page.path, line: e.line, message: e.message })); const at = (key: string, message: string): void => { @@ -138,10 +140,11 @@ export async function checkPageFrontmatter(page: PageFile, discoveryMap: Discove }; const notes: string[] = []; const where = (key: string) => `${page.path}${lines[key] !== undefined ? `:${lines[key]}` : ""}`; - const renamed = (from: string, to: string): void => { - notes.push(`warning: ${where("categories")}: category "${from}" is now "${to}" (renamed in storefront.categories): write "${to}"`); + const renamed = (kind: TermKind, from: string, to: string): void => { + const w = TERM_WORDS[kind]; + notes.push(`warning: ${where(w.many)}: ${w.one} "${from}" is now "${to}" (renamed in ${w.config}): write "${to}"`); }; - const buildKeys = () => checkBuildKeys(values, page.path, at, categories, renamed); + const buildKeys = () => checkBuildKeys(values, page.path, at, { categories, tags }, renamed); // ---- layout: its own, else its folder's childLayout (pages.ts), else the default ---- const known = layoutNames(discoveryMap); diff --git a/packages/dev-server/src/storefront/json-ld.ts b/packages/dev-server/src/storefront/json-ld.ts index 6a43da4..26266a4 100644 --- a/packages/dev-server/src/storefront/json-ld.ts +++ b/packages/dev-server/src/storefront/json-ld.ts @@ -19,8 +19,10 @@ export interface JsonLdPage { modified: string | null; /** The page's date: its own (frontmatter `date`, YYYY-MM-DD), else git's first commit of it (ISO 8601), or null. */ published?: string | null; - /** The page is an article: its own date and its tags (page.ts articleOf). */ - article?: { published: string; tags: string[] } | undefined; + /** The page is an article: its own date, its tags' and its categories' labels (page.ts articleOf). */ + article?: { published: string; tags: string[]; sections: string[] } | undefined; + /** A generated tag or category page, or an index of them (terms.ts): a CollectionPage, not a WebPage. */ + collection?: boolean; } /** The page's JSON-LD as a