pattern-dump 0.2.0-alpha.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## 0.4.0
+
+### Added
+
+- `pd build --browser` also checks a storefront's pages in Chromium, at a desktop and a phone width: colour contrast
+  and the other accessibility rules that need a rendered page (a critical or serious finding stops the build), and
+  each image's variant against the box it is laid out in (a warning when its slot's `sizes` doesn't match). It uses
+  the project's own Playwright: `npm install --save-dev playwright`, then `npx playwright install chromium`.
+- Collections: a folder of storefront pages is a collection. A layout that declares `page.children` lists the
+  folder's pages on its `index.md` (route, title, description, date, image, tags), newest first with `sort: date`;
+  a page without a description is listed with the first paragraph of its body. `partials/base` can list folders
+  under `site.collections` to show their pages on every page, such as a home page's latest articles. Layouts can
+  show a page's own `page.date` and `page.tags`.
+- A storefront can be published under a path, such as a GitHub project page: `storefront.url` takes the full
+  address (`https://example.github.io/project/`). Every page, stylesheet, script and image is then served under the
+  path, in `pd dev` too, with links still written from the site's root; canonical URLs, Open Graph, JSON-LD and the
+  sitemap carry it. Every page names its path in `<meta name="pd-base-path">` for a skin's own scripts, and
+  `pd build --browser` stops on a request outside the path. Under a path there is no `robots.txt` (the build says what
+  the host's own needs) and previews carry a robots `noindex` tag, as a workbench's do when it is built with `--base`.
+- A project that is a pattern package itself (a style guide with its own workbench) describes its folders once: its
+  config takes each folder it doesn't name from its `package.json`'s `patternDump` field (patterns, data, helpers,
+  assets, styles with `entry` and `documentBase`, themes, scripts, `globalScripts`, `exclude`). A folder named in
+  both with different values is a config error naming both files.
+- `storefront.head`: a site's own additions to every page's head (an analytics script, a verification tag), a
+  Handlebars file rendered with `site` after the skin's `partials/head` and checked like it. For a site whose skin
+  is a shared package.
+- A `HELPER_SHADOW` warning on a component whose template has a bare `{{name}}` that calls a registered helper
+  while its data has a field of that name, at any depth: `{{id}}` inside `{{#each palettes}}` showed the `id`
+  helper's output instead of each palette's `id`, silently. Read the field as `{{this.id}}`, or rename it.
+- `pd init --storefront` writes an `articles/` collection (a listing page and one dated, tagged article) with a
+  `listing` layout, shows a page's date and tags in its page layout, and its config shows a `storefront.url` for a
+  subfolder.
+- `date`, `tags` and `draft` in a page's frontmatter. `date` (`YYYY-MM-DD`) is the page's date for listings and its
+  JSON-LD `datePublished`, which falls back to the page's first commit. `draft: true` shows a page in `pd dev` and
+  leaves it out of `pd build`, which names the drafts it left out.
+
+### Fixed
+
+- A storefront page loads the behaviour scripts its components bring (`requireScript` of its layout's components and
+  of the components it places, and `globalScripts`), as their workbench previews do. Before, only the markup and CSS
+  reached the page.
+- A code block on a storefront page, or in a component's `<pre>`, keeps its lines as written when its partial is
+  included on an indented line (as a skin's `{{> @partial-block }}` usually is). Handlebars indented every line after
+  the first by the include's indentation.
+- A schema field named like a registered helper (`id`, `eq`, …) is no longer an error only the workbench's Diagnostics
+  tab shows: `pd dev` and `pd build` say it in the terminal, a storefront page that places the component fails (as
+  one whose layout has such a field already did), and `pd audit` re-audits a component when its schema changes
+  instead of reusing a verdict cached before.
+- An image in a site page's markdown from a pattern package's assets, when that package's folder is the site's only
+  asset folder, gets its variants. Before, the page failed with "is not an image in the assets" for a URL that was
+  served.
+- `pd dev` no longer keeps base-layer rules that a component's stylesheet stopped writing (through a mixin) until it is
+  restarted.
+
+### Changed
+
+- **Breaking:** `date`, `tags`, `draft` and `sort` are now frontmatter keys of the build, like `layout` and
+  `image`. A layout whose schema declares one of them fails every page that uses it; rename the field in the
+  layout's schema (and show the page's date or tags through `page.date` and `page.tags`).
+- A storefront page's JSON-LD carries `datePublished`.
+
+## 0.3.0
+
+From this release Pattern Dump is published as plain 0.x versions under npm's `latest` tag: install it with
+`npx pattern-dump init`, without `@alpha`. Being at 0.x, breaking changes are possible between minor versions, and
+this changelog names them.
+
+### Added
+
+- `sourceDir`, `patternsDir` and `styles` are optional. A site whose components, skin and styles all come from
+  pattern packages names none of them; they default to `./src`, `./src/patterns` and `./src/styles`, and the folders
+  don't have to exist.
+
+### Changed
+
+- `pd build` now checks every page of a storefront with axe before it writes anything, and **stops on an
+  accessibility error**: a WCAG rule rated critical or serious (an image without alt text, a button with no name, a
+  page without a language), or a page without exactly one `<main>` and one `<h1>`. Each error is printed with its
+  page, the rule, the elements it was found on and a link to the rule's explanation; moderate and minor findings,
+  and axe's best practices, are listed as warnings and don't stop the build. To see them before a build, run
+  `pd build` locally: nothing is written while there are errors. In `pd dev`, a page without one `<main>` and one
+  `<h1>` is a warning in the terminal.
+
 ## 0.2.0-alpha.0
 
 The storefront: a website written as markdown pages, dressed by a skin made of ordinary components, served by

package/README.md

@@ -1,22 +1,27 @@
 # Pattern Dump
 
-A workbench for HTML and CSS design systems, and a successor to PatternLab. Write components as
+A workbench for HTML and CSS design systems, and a successor to Pattern Lab. Write components as
 Handlebars templates with SCSS, data and Markdown docs; Pattern Dump shows them live, checks them, maps
 how they relate, and publishes the result as a static site.
 
-> **Alpha (0.2.0-alpha.0).** Published under the `alpha` tag. Options and file conventions can still change
-> between releases.
+**Demo:** a style guide and the website built from it, at https://lab.n8d.studio/pattern-dump-demo/
+
+> **0.4.0.** Pattern Dump is at 0.x, so breaking changes are possible between minor versions (0.3 to 0.4);
+> the [changelog](https://github.com/n8design/pattern-dump/blob/main/CHANGELOG.md) names them.
+
+**Coming from Pattern Lab?** Point `patternsDir` at your patterns folder: Handlebars templates, `.json` data and
+`~` variants work as they are, and no build step of your own is needed.
 
 ## Requirements
 
-Node.js 20.10 or later, and npm.
+Node.js 22.22 or later, and npm.
 
 ## Quick start
 
 Create a new project:
 
 ```bash
-npx pattern-dump@alpha init my-design-system
+npx pattern-dump init my-design-system
 cd my-design-system
 npm run dev              # → http://localhost:4000
 ```
@@ -24,7 +29,7 @@ npm run dev              # → http://localhost:4000
 Or add Pattern Dump to an existing project:
 
 ```bash
-npm install --save-dev pattern-dump@alpha
+npm install --save-dev pattern-dump
 npx pd init
 ```
 
@@ -35,7 +40,7 @@ overwrites an existing file.
 ### Installing `pd` globally
 
 ```bash
-npm install --global pattern-dump@alpha
+npm install --global pattern-dump
 pd init my-design-system
 ```
 

package/dist/chunks/{chunk-ESMZAOP2.js → chunk-DIDJPCLS.js}

@@ -54,12 +54,13 @@ var SHAPE = {
       lang: "lang",
       index: "boolean",
       image: "asset-path",
-      images: IMAGES
+      images: IMAGES,
+      head: "hbs-file"
     },
     required: ["pagesDir", "outDir"]
   }
 };
-var REQUIRED = ["sourceDir", "patternsDir", "outDir", "styles"];
+var REQUIRED = ["outDir"];
 var WORKBENCH_PATH = /^\/(?:(?!\.{1,2}(?:\/|$))[a-z0-9._~-]+\/?)+$/i;
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isStrings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
@@ -90,25 +91,25 @@ function suggest(key, known) {
   const sameStart = key.slice(0, 3).toLowerCase() === best.slice(0, 3).toLowerCase();
   return bestD <= 2 || bestD <= 3 && sameStart ? best : void 0;
 }
-function checkObject(value, shape, required, at, problems) {
+function checkObject(value, shape, required, at2, problems) {
   const known = Object.keys(shape);
   const unknown = Object.keys(value).filter((k) => !(k in shape));
   for (const key of required) {
     if (value[key] !== void 0) continue;
     const near = unknown.find((u) => suggest(u, [key]) === key);
-    problems.push(near ? `missing required "${at}${key}" (found "${at}${near}" \u2014 did you mean "${at}${key}"?)` : `missing required "${at}${key}"`);
+    problems.push(near ? `missing required "${at2}${key}" (found "${at2}${near}" \u2014 did you mean "${at2}${key}"?)` : `missing required "${at2}${key}"`);
   }
   for (const key of unknown) {
     const near = suggest(key, known);
     if (near && required.includes(near) && value[near] === void 0) continue;
-    problems.push(`unknown key "${at}${key}"${near ? ` \u2014 did you mean "${at}${near}"?` : ""}`);
+    problems.push(`unknown key "${at2}${key}"${near ? ` \u2014 did you mean "${at2}${near}"?` : ""}`);
   }
   for (const key of known) {
-    if (value[key] !== void 0) checkValue(value[key], shape[key], `${at}${key}`, problems);
+    if (value[key] !== void 0) checkValue(value[key], shape[key], `${at2}${key}`, problems);
   }
 }
-function checkValue(value, rule, at, problems) {
-  const fail = (expected) => problems.push(`"${at}" must be ${expected}`);
+function checkValue(value, rule, at2, problems) {
+  const fail = (expected) => problems.push(`"${at2}" must be ${expected}`);
   if (rule === "string") {
     if (typeof value !== "string") fail("a string");
     return;
@@ -154,12 +155,12 @@ function checkValue(value, rule, at, problems) {
     if (typeof value === "string") {
       try {
         const url = new URL(value);
-        ok = /^https?:$/.test(url.protocol) && url.pathname === "/" && url.search === "" && url.hash === "" && !/[?#]/.test(value);
+        ok = /^https?:$/.test(url.protocol) && url.search === "" && url.hash === "" && !/[?#]/.test(value) && !/\/\/./.test(url.pathname);
       } catch {
         ok = false;
       }
     }
-    if (!ok) fail(`the site's absolute http(s) address, with no path, query or fragment, such as "https://example.com/"`);
+    if (!ok) fail(`the site's absolute http(s) address, with no query or fragment, such as "https://example.com/", or "https://example.github.io/project/" for a site published under a path`);
     return;
   }
   if (rule === "lang") {
@@ -168,6 +169,12 @@ function checkValue(value, rule, at, problems) {
     }
     return;
   }
+  if (rule === "hbs-file") {
+    if (typeof value !== "string" || !/\.hbs$/.test(value) || /^(?:\/|[a-zA-Z]:)/.test(value)) {
+      fail(`a Handlebars file relative to the project's root, such as "./head.hbs"`);
+    }
+    return;
+  }
   if (rule === "asset-path") {
     if (typeof value !== "string" || !/^\/assets\/[^?#]+[^/?#]$/.test(value)) {
       fail(`a path to a file in the assets, such as "/assets/images/share.png"`);
@@ -194,7 +201,7 @@ function checkValue(value, rule, at, problems) {
   }
   if ("values" in rule) {
     if (typeof value === "string" && rule.unsupported?.includes(value)) {
-      problems.push(`"${at}": "${value}" is not supported yet \u2014 use ${rule.values.map((v) => `"${v}"`).join(" or ")}, or leave it out`);
+      problems.push(`"${at2}": "${value}" is not supported yet \u2014 use ${rule.values.map((v) => `"${v}"`).join(" or ")}, or leave it out`);
     } else if (typeof value !== "string" || !rule.values.includes(value)) {
       fail(rule.values.map((v) => `"${v}"`).join(" or "));
     }
@@ -204,7 +211,7 @@ function checkValue(value, rule, at, problems) {
     fail("an object");
     return;
   }
-  checkObject(value, rule.keys, rule.required ?? [], `${at}.`, problems);
+  checkObject(value, rule.keys, rule.required ?? [], `${at2}.`, problems);
 }
 var ConfigError = class extends Error {
   name = "ConfigError";
@@ -218,8 +225,8 @@ function checkRelations(raw, problems) {
     ["storefront.outDir", sf.outDir]
   ];
   const root = resolve(sep, "pd-root");
-  const inside = (child, parent) => {
-    const rel = relative(parent, child);
+  const inside = (child2, parent) => {
+    const rel = relative(parent, child2);
     return rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep) && !/^[a-zA-Z]:/.test(rel);
   };
   for (let i = 0; i < folders.length; i++) {
@@ -242,17 +249,28 @@ function configProblems(raw) {
   return problems;
 }
 var withOneTrailingSlash = (url) => `${url.replace(/\/+$/, "")}/`;
+function withSourceDefaults(config) {
+  if (config.sourceDir !== void 0 && config.patternsDir !== void 0 && config.styles !== void 0) return config;
+  const sourceDir = config.sourceDir ?? "./src";
+  const base = sourceDir.replace(/\/+$/, "");
+  return {
+    ...config,
+    sourceDir,
+    patternsDir: config.patternsDir ?? `${base}/patterns`,
+    styles: config.styles ?? { strategy: "parallel", dir: `${base}/styles` }
+  };
+}
 function validateConfig(raw, source) {
   const problems = configProblems(raw);
   if (problems.length > 0) {
     throw new ConfigError(`${source}: invalid config
 ${problems.map((p) => `  - ${p}`).join("\n")}`);
   }
-  const config = raw;
+  const config = withSourceDefaults(raw);
   const sf = config.storefront;
   if (!sf) return config;
   const workbenchUrl = sf.workbenchUrl !== void 0 ? withOneTrailingSlash(sf.workbenchUrl) : void 0;
-  const url = sf.url !== void 0 ? `${new URL(sf.url).origin}/` : void 0;
+  const url = sf.url !== void 0 ? siteUrlForm(sf.url) : void 0;
   if (workbenchUrl === sf.workbenchUrl && url === sf.url) return config;
   return { ...config, storefront: {
     ...sf,
@@ -260,24 +278,165 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
     ...url !== void 0 ? { url } : {}
   } };
 }
+function siteUrlForm(value) {
+  const u = new URL(value);
+  return `${u.origin}${withOneTrailingSlash(u.pathname)}`;
+}
+function storefrontBasePath(storefront) {
+  return storefront?.url === void 0 ? "/" : new URL(storefront.url).pathname;
+}
 function sameHostWorkbenchPath(storefront) {
   const w = storefront?.workbenchUrl;
   if (w === void 0) return void 0;
   if (w.startsWith("/")) return w;
   if (storefront?.url === void 0) return void 0;
   const u = new URL(w);
-  return `${u.origin}/` === storefront.url ? u.pathname : void 0;
+  return u.origin === new URL(storefront.url).origin ? u.pathname : void 0;
+}
+
+// packages/config/src/own-manifest.ts
+var isObject2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var child = (o, key) => {
+  if (!isObject2(o[key])) o[key] = {};
+  return o[key];
+};
+var at = (o, ...keys) => keys.reduce((v, k) => isObject2(v) ? v[k] : void 0, o);
+var top = (from, to, paths = true) => ({
+  from,
+  get: (m) => m[from],
+  to,
+  read: (c) => c[to],
+  write: (c, v) => {
+    c[to] = v;
+  },
+  paths
+});
+var FIELDS = [
+  top("patterns", "patternsDir"),
+  top("data", "dataDir"),
+  top("helpers", "helpers"),
+  top("scripts", "scriptsDir"),
+  top("globalScripts", "globalScripts", false),
+  top("exclude", "exclude", false),
+  {
+    from: "assets",
+    get: (m) => m["assets"],
+    to: "assets.dir",
+    read: (c) => at(c, "assets", "dir"),
+    write: (c, v) => {
+      child(c, "assets")["dir"] = v;
+    },
+    paths: true
+  },
+  {
+    from: "styles.dir",
+    get: (m) => at(m, "styles", "dir"),
+    to: "styles.dir",
+    read: (c) => at(c, "styles", "dir"),
+    write: (c, v) => {
+      child(c, "styles")["dir"] = v;
+    },
+    paths: true
+  },
+  {
+    from: "styles.entry",
+    get: (m) => at(m, "styles", "entry"),
+    to: "styles.entry",
+    read: (c) => at(c, "styles", "entry"),
+    write: (c, v) => {
+      child(c, "styles")["entry"] = v;
+    },
+    paths: true
+  },
+  {
+    from: "styles.documentBase",
+    get: (m) => at(m, "styles", "documentBase"),
+    to: "documentBase",
+    read: (c) => c["documentBase"],
+    write: (c, v) => {
+      c["documentBase"] = v;
+    },
+    paths: true
+  },
+  {
+    from: "themes.dir",
+    get: (m) => at(m, "themes", "dir"),
+    to: "themes.dir",
+    read: (c) => at(c, "themes", "dir"),
+    write: (c, v) => {
+      child(c, "themes")["dir"] = v;
+    },
+    paths: true
+  },
+  {
+    from: "themes.default",
+    get: (m) => at(m, "themes", "default"),
+    to: "themes.default",
+    read: (c) => at(c, "themes", "default"),
+    write: (c, v) => {
+      child(c, "themes")["default"] = v;
+    },
+    paths: false
+  },
+  {
+    from: "themes.switch",
+    get: (m) => at(m, "themes", "switch"),
+    to: "themes.switch",
+    read: (c) => at(c, "themes", "switch"),
+    write: (c, v) => {
+      child(c, "themes")["switch"] = v;
+    },
+    paths: false
+  }
+];
+function samePath(p) {
+  const parts = [];
+  for (const seg of p.replace(/\\/g, "/").split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === ".." && parts.length && parts[parts.length - 1] !== "..") parts.pop();
+    else parts.push(seg);
+  }
+  return parts.join("/") || ".";
+}
+function comparable(v, paths) {
+  const list = Array.isArray(v) ? v : [v];
+  return JSON.stringify(paths ? list.map((x) => typeof x === "string" ? samePath(x) : x) : Array.isArray(v) ? v : [v]);
+}
+var shown = (v) => JSON.stringify(v);
+function withOwnManifest(raw, manifest, where) {
+  if (!isObject2(raw) || !isObject2(manifest)) return raw;
+  const config = structuredClone(raw);
+  const conflicts = [];
+  for (const f of FIELDS) {
+    const value = f.get(manifest);
+    if (value === void 0) continue;
+    const own = f.read(config);
+    if (own === void 0) {
+      f.write(config, structuredClone(value));
+      continue;
+    }
+    if (comparable(own, f.paths) !== comparable(value, f.paths)) {
+      conflicts.push(`"${f.to}" is ${shown(own)} in ${where.config}, but "patternDump.${f.from}" is ${shown(value)} in ${where.manifest}: name it in one of them, or give both the same value`);
+    }
+  }
+  if (conflicts.length) {
+    throw new ConfigError(`${where.config}: the config and the project's own package manifest disagree
+${conflicts.map((c) => `  - ${c}`).join("\n")}`);
+  }
+  return config;
 }
 
 // packages/config/src/index.ts
 function defineConfig(config) {
-  return config;
+  return withSourceDefaults(config);
 }
 
 export {
   suggest,
   ConfigError,
   validateConfig,
+  storefrontBasePath,
   sameHostWorkbenchPath,
+  withOwnManifest,
   defineConfig
 };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   defineConfig
-} from "./chunks/chunk-ESMZAOP2.js";
+} from "./chunks/chunk-DIDJPCLS.js";
 export {
   defineConfig
 };