pattern-dump 0.2.0-alpha.0 → 0.4.0

package/dist/types/config/index.d.ts

@@ -1,6 +1,7 @@
 import type { ShellBrandConfig, SwatchSlots, ThemeSwitch } from "../contracts/index.js";
 export type { ShellBrandConfig, SwatchSlots, ThemeSwitch };
-export { ConfigError, configProblems, sameHostWorkbenchPath, suggest, validateConfig } from "./validate.js";
+export { ConfigError, configProblems, sameHostWorkbenchPath, storefrontBasePath, suggest, validateConfig, withSourceDefaults } from "./validate.js";
+export { withOwnManifest } from "./own-manifest.js";
 export interface AssetsConfig {
     /** Where assets live. Only 'central' (the default: one assets dir, served at /assets/) is supported
      *  so far; 'component-relative' is reserved, and the config check rejects it as not supported yet. */
@@ -195,10 +196,11 @@ export interface StorefrontConfig {
      */
     workbenchUrl?: string;
     /**
-     * The site's address, such as `https://example.com/`: an absolute http(s) URL with no path (the storefront
-     * is served from the root of its host), no query or fragment; loaded as its origin followed by `/`. With it,
-     * pages get a canonical URL, Open Graph and JSON-LD, and `pd build` writes a sitemap; without it they are
-     * left out, and `pd build` says so once.
+     * The site's address, such as `https://example.com/`: an absolute http(s) URL with no query or fragment; loaded
+     * with exactly one trailing slash. It may have a path, such as `https://example.github.io/project/`: the site is
+     * then published under that path (its base path), and every page, stylesheet, script and image it links is
+     * served under it, in `pd dev` too. With it, pages get a canonical URL, Open Graph and JSON-LD, and `pd build`
+     * writes a sitemap; without it they are left out, `pd build` says so once, and the site is served from `/`.
      */
     url?: string;
     /** The language of every page, as `<html lang>` takes it (a BCP 47 tag such as `de-AT`). Default: `en`. */
@@ -213,6 +215,13 @@ export interface StorefrontConfig {
     image?: string;
     /** This site's image encoding, over the project's `images`. */
     images?: ImageSettings;
+    /**
+     * The site's own additions to every page's `<head>`, such as an analytics script or a search engine's verification
+     * tag: a Handlebars file relative to the root, such as `./head.hbs`, rendered with `site` (plain Handlebars, without
+     * Pattern Dump's helpers) and placed after the skin's `partials/head`. It is checked as `partials/head` is: only
+     * `<meta>`, `<link>`, `<script>`, `<style>` and `<noscript>`, and none of the tags Pattern Dump writes itself.
+     */
+    head?: string;
     /**
      * Values every page of the site shares, such as its title or the line in its footer. Every layout gets
      * them as `site`; a page cannot set them. Which keys there are, and their types, is what the `site`
@@ -242,4 +251,10 @@ export type StorefrontNavEntry = {
     label: string;
     children: StorefrontNavEntry[];
 };
-export declare function defineConfig(config: PatternDumpConfig): PatternDumpConfig;
+/**
+ * What a project writes: the config, where `sourceDir`, `patternsDir` and `styles` may be left out (a site whose
+ * patterns and styles all come from pattern packages has none of its own). `defineConfig` and `validateConfig` fill
+ * them in (`withSourceDefaults`), so everything that reads a config gets all three.
+ */
+export type PatternDumpConfigInput = Omit<PatternDumpConfig, "sourceDir" | "patternsDir" | "styles"> & Partial<Pick<PatternDumpConfig, "sourceDir" | "patternsDir" | "styles">>;
+export declare function defineConfig(config: PatternDumpConfigInput): PatternDumpConfig;

package/dist/types/config/own-manifest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The config with each folder its project's own manifest names and the config doesn't, or the config as it is when
+ * there is no manifest. `where` names the two files in the error. A config that sets a field the manifest sets too,
+ * to another value, throws a ConfigError listing every such field. The raw config is never changed.
+ */
+export declare function withOwnManifest(raw: unknown, manifest: unknown, where: {
+    config: string;
+    manifest: string;
+}): unknown;

package/dist/types/config/validate.d.ts

@@ -1,4 +1,4 @@
-import type { PatternDumpConfig } from "./index.js";
+import type { PatternDumpConfig, PatternDumpConfigInput } from "./index.js";
 /** The closest of `known` to `key` when it is near enough to be a typo of it, else undefined. Used for
  *  "did you mean" in config problems, and by other checks that name an unknown key. */
 export declare function suggest(key: string, known: string[]): string | undefined;
@@ -10,11 +10,24 @@ export declare class ConfigError extends Error {
 /** The problems with a loaded config, one line each; empty when it is valid. */
 export declare function configProblems(raw: unknown): string[];
 /** Check a loaded config and return it typed, or throw one error listing every problem. */
+/**
+ * A config with its source folders filled in where it names none: `sourceDir` is "./src", and `patternsDir` and
+ * `styles.dir` are its `patterns` and `styles` folders. None of them has to exist: a site whose patterns and styles
+ * all come from pattern packages has none of its own. What the config names is kept as it is.
+ */
+export declare function withSourceDefaults(config: PatternDumpConfigInput): PatternDumpConfig;
 export declare function validateConfig(raw: unknown, source: string): PatternDumpConfig;
+/**
+ * The storefront's base path: the path of `storefront.url` ("/" at the root of a host, "/project/" under a path), or
+ * "/" for a site with no address. Reads a validated config, so the URL is already in its one form.
+ */
+export declare function storefrontBasePath(storefront: {
+    url?: string;
+} | undefined): string;
 /**
  * The path of a workbench published on the storefront's own host, or undefined when it has a host of its own.
  * Same-host means a root-relative `workbenchUrl` ("/workbench/"), or an absolute one on the origin of
- * `storefront.url`. Reads a validated config, so both are already normalised (one trailing slash).
+ * `storefront.url` (whatever the site's own path). The path is the workbench's full path on the host. Reads a validated config, so both are already normalised (one trailing slash).
  */
 export declare function sameHostWorkbenchPath(storefront: {
     workbenchUrl?: string;

package/dist/types/contracts/dev-protocol.d.ts

@@ -70,7 +70,7 @@ export interface TreeNode {
     children?: TreeNode[];
 }
 export type DiagnosticSeverity = "error" | "warning" | "info";
-export type DiagnosticKind = "RENDER_ERROR" | "UNFILLED_REQUIRED" | "SHAPE_MISMATCH" | "HTML_INVALID" | "CASCADE_WARNING" | "A11Y" | "HIGHLIGHT_FALLBACK" | "HANDLE_COLLISION" | "DATA_INVALID" | "SCHEMA_INVALID";
+export type DiagnosticKind = "RENDER_ERROR" | "UNFILLED_REQUIRED" | "SHAPE_MISMATCH" | "HTML_INVALID" | "CASCADE_WARNING" | "A11Y" | "HIGHLIGHT_FALLBACK" | "HANDLE_COLLISION" | "DATA_INVALID" | "SCHEMA_INVALID" | "HELPER_SHADOW";
 /** Fields every diagnostic carries, whichever engine produced it. */
 interface DiagnosticBase {
     severity: DiagnosticSeverity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-dump",
-  "version": "0.2.0-alpha.0",
+  "version": "0.4.0",
   "description": "A workbench for HTML and CSS design systems: live component previews, docs, checks and static publishing.",
   "keywords": [
     "design-system",

package/templates/storefront/.github/workflows/pages.yml

@@ -1,5 +1,6 @@
-# Builds the website and the workbench, and publishes both to GitHub Pages:
-# the website at the root of your domain, the workbench under /workbench/.
+# Builds the website and the workbench, and publishes both to GitHub Pages: the website at the address in
+# storefront.url (your domain, or a project page's address with its path), the workbench inside it at
+# workbench/ (build.basePath gives its full path).
 # Before the first run: Settings → Pages → Source: "GitHub Actions", and your custom domain: see "Publish it" in the README.
 name: Pages
 

package/templates/storefront/pages/articles/hello.md

@@ -0,0 +1,10 @@
+---
+title: Hello, articles
+description: The example article. Copy it to start a new one.
+date: 2026-11-14
+tags: [getting-started, notes]
+---
+
+An article is a page in `pages/articles/` with a `date` (`YYYY-MM-DD`), which orders the listing and is the page's
+publication date for search engines. `tags` are lowercase words for grouping. A page with `draft: true` shows while
+you work and is left out of `pd build`.

package/templates/storefront/pages/articles/index.md

@@ -0,0 +1,10 @@
+---
+title: Articles
+description: Everything written here, newest first.
+layout: listing
+sort: date
+order: 2
+---
+
+This page is `pages/articles/index.md`. Every page in this folder is listed below, newest first. Add a markdown
+file with a `date` and it shows up here, with no link to write.

package/templates/storefront/src/patterns/layouts/listing/listing.hbs

@@ -0,0 +1,16 @@
+{{#> partials-base }}
+<article class="page listing">
+  <h1 class="page-title">{{title}}</h1>
+  {{#if description}}<p class="page-description">{{description}}</p>{{/if}}
+  <div class="page-body">{{{body}}}</div>
+  <ul class="listing-entries" role="list">
+    {{#each page.children}}
+    <li class="listing-entry">
+      <a class="listing-title" href="{{route}}">{{title}}</a>
+      {{#if date}}<time class="listing-date" datetime="{{date}}">{{date}}</time>{{/if}}
+      {{#if description}}<p class="listing-teaser">{{description}}</p>{{/if}}
+    </li>
+    {{/each}}
+  </ul>
+</article>
+{{/partials-base}}

package/templates/storefront/src/patterns/layouts/listing/listing.json

@@ -0,0 +1,13 @@
+{
+  "title": "Articles",
+  "description": "Everything written here, newest first.",
+  "body": "<p>The folder's index.md, rendered.</p>",
+  "site": { "title": __PD_BRAND_JSON__, "footer": "Made with Pattern Dump." },
+  "nav": [{ "route": "/", "title": "Home" }, { "route": "/articles/", "title": "Articles", "current": true }],
+  "page": {
+    "children": [
+      { "route": "/articles/second/", "title": "A second article", "description": "Its teaser: the page's description, or its first paragraph.", "date": "2026-11-14", "image": null, "tags": ["notes"], "draft": false },
+      { "route": "/articles/first/", "title": "A first article", "description": "Listed below the newer one.", "date": "2026-11-01", "image": null, "tags": [], "draft": false }
+    ]
+  }
+}

package/templates/storefront/src/patterns/layouts/listing/listing.md

@@ -0,0 +1,7 @@
+---
+title: Listing
+---
+
+The layout of a folder's `index.md` that lists the folder's pages, such as `pages/articles/index.md`: set
+`layout: listing`, and `sort: date` to list the newest first. It declares `page.children`, so the storefront fills
+it with the folder's pages, each with its route, title, description (or its first paragraph), date, image and tags.

package/templates/storefront/src/patterns/layouts/listing/listing.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Listing",
+  "description": "A folder's index.md that lists the folder's pages: a collection, such as articles.",
+  "type": "object",
+  "required": ["title"],
+  "properties": {
+    "title": { "type": "string", "description": "The listing's heading, and its title in the navigation" },
+    "description": { "type": "string", "description": "One sentence under the heading, and the page's description for search results" },
+    "page": {
+      "type": "object",
+      "description": "What the storefront works out for the page",
+      "properties": {
+        "children": { "description": "The folder's pages, newest first with sort: date" }
+      }
+    }
+  }
+}

package/templates/storefront/src/patterns/layouts/page/page.hbs

@@ -2,6 +2,7 @@
 <article class="page">
   <h1 class="page-title">{{title}}</h1>
   {{#if description}}<p class="page-description">{{description}}</p>{{/if}}
+  {{#if page.date}}<div class="page-meta"><time datetime="{{page.date}}">{{page.date}}</time>{{#if page.tags.length}}<ul class="page-tags" aria-label="Tags">{{#each page.tags}}<li>{{this}}</li>{{/each}}</ul>{{/if}}</div>{{/if}}
   <div class="page-body">{{{body}}}</div>
   {{#if page.next}}<p class="page-next"><a rel="next" href="{{page.next.route}}">Next: {{page.next.title}}</a></p>{{/if}}
 </article>

package/templates/storefront/src/patterns/layouts/page/page.json

@@ -4,5 +4,5 @@
   "body": "<p>The page's markdown, rendered.</p>",
   "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" } }
+  "page": { "next": { "route": "/about/", "title": "About" }, "date": "2026-11-14", "tags": ["notes"] }
 }

package/templates/storefront/src/patterns/layouts/page/page.md

@@ -3,4 +3,5 @@ title: Page
 ---
 
 The layout every page renders with, unless its frontmatter names another with `layout: <name>`.
-Its schema is the frontmatter contract: a page may set `title` (required) and `description`.
+Its schema is the frontmatter contract: a page may set `title` (required) and `description`. A page with a `date`
+(an article) shows it under the description, with its `tags`.

package/templates/storefront/src/patterns/layouts/page/page.schema.json

@@ -12,7 +12,9 @@
       "type": "object",
       "description": "What the storefront works out for the page",
       "properties": {
-        "next": { "description": "The page after this one in the navigation" }
+        "next": { "description": "The page after this one in the navigation" },
+        "date": { "description": "The page's date, from its frontmatter, for an article" },
+        "tags": { "description": "The page's tags, from its frontmatter" }
       }
     }
   }

package/templates/storefront/src/styles/layouts/listing.scss

@@ -0,0 +1,15 @@
+@use "../base/tokens";
+
+.listing-entries { margin: tokens.$space-lg 0 0; padding: 0; list-style: none; }
+.listing-entry { margin-block-end: tokens.$space-lg; }
+.listing-title { font-weight: 600; }
+.listing-date { margin-inline-start: tokens.$space-sm; color: var(--color-text-muted, #4b5563); }
+.listing-teaser {
+  margin: 0;
+  // The teaser is never shortened in the data: three lines at most here.
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+  line-clamp: 3;
+  overflow: hidden;
+}

package/templates/storefront/src/styles/layouts/page.scss

@@ -4,3 +4,6 @@
 .page-description { margin-block: 0 tokens.$space-lg; color: var(--color-text-muted, #4b5563); }
 .page-body iframe { width: 100%; border: 0; }
 .page-next { margin-top: tokens.$space-lg; }
+.page-meta { margin-block: 0 tokens.$space-lg; color: var(--color-text-muted, #4b5563); }
+.page-tags { display: inline; margin: 0; padding: 0; list-style: none; }
+.page-tags li { display: inline; margin-inline-start: tokens.$space-sm; }

package/templates/storefront-fills/config.txt

@@ -6,8 +6,11 @@
     // The workbench is published on the website's own host, under /workbench/ (and built for that path,
     // build.basePath below).
     workbenchUrl: "/workbench/",
-    // Your domain, once you have one: canonical URLs, link previews and the sitemap are built from it.
+    // The site's address, once you know it: canonical URLs, link previews and the sitemap are built from it.
     // url: "https://www.example.com/",
+    // Or a subfolder, such as a GitHub project page: the site is then served under the path, in `npm run dev` too,
+    // and the workbench goes under it as well (workbenchUrl and build.basePath "/<repository>/workbench/").
+    // url: "https://<owner>.github.io/<repository>/",
     site: { title: __PD_BRAND_JSON__, footer: "Made with Pattern Dump." },
   },
   build: { basePath: "/workbench/" },

package/templates/storefront-fills/readme.md

@@ -30,6 +30,9 @@ returns by itself. How `pd-` tags work:
 | `src/patterns/components/note/` | the component the home page shows |
 | `pattern-dump.config.ts` | `storefront`: the website's name and footer (`site`), and where it is published |
 
+`pages/articles/` is a collection: its `index.md` (layout `listing`, `sort: date`) lists every page in the folder,
+newest first, by its `date`. Copy `hello.md` to write another; `draft: true` keeps one out of the build.
+
 A page that doesn't exist shows a built-in 404 page; write `pages/404.md` to change it. A page that moved
 can forward from its old address (`redirectFrom: [/old/]`), and `index: false` keeps a page out of search
 engines. All of it is in the [storefront guide](https://github.com/n8design/pattern-dump/blob/main/docs/guide/storefront.md).
@@ -42,9 +45,14 @@ what the GitHub Pages workflow does.
 
 ### Publish it
 
-`.github/workflows/pages.yml` publishes both to GitHub Pages on every push to `main`. The website lives at
-the root of its host, so it needs a custom domain (a project page under `/<repository>/` can't host it).
-Once, in the repository on GitHub:
+`.github/workflows/pages.yml` publishes both to GitHub Pages on every push to `main`, at a custom domain
+or as a project page.
+
+**As a project page** (`https://<owner>.github.io/<repository>/`, no domain needed): in
+`pattern-dump.config.ts`, set `storefront.url` to that address, and `storefront.workbenchUrl` and
+`build.basePath` to `/<repository>/workbench/`. Then **Settings → Pages → Source:** "GitHub Actions".
+
+**At a custom domain**, once, in the repository on GitHub:
 
 1. **Settings → Pages → Source:** "GitHub Actions".
 2. **Settings → Pages → Custom domain:** your domain, then Save. GitHub recommends verifying the domain in