pattern-dump 0.1.0-alpha.0 → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 0.1.0-alpha.2
+
+Fixes found while moving a PatternLab styleguide to Pattern Dump, and the changes they needed.
+
+### Check before upgrading
+
+These can change how an existing project loads or renders:
+
+- **The config is checked when it loads.** A missing required option, an unknown option or a value
+  of the wrong type now stops `pd` with a list of every problem, with a suggestion for likely typos.
+  `styles.strategy: "co-located"` and `assets.strategy: "component-relative"` were accepted but never
+  implemented; they are now rejected as not supported yet.
+- **Numbered folders lose their number in handles.** `00-atoms/badge` is included as
+  `{{> atoms-badge }}`, as in PatternLab. Its id and address keep the number (`/00-atoms/badge`).
+  Includes written with the number (`{{> 00-atoms-badge }}`) need updating.
+- **`documentBase` paths are authoritative.** A file or folder listed there always goes into the base
+  layer, even one that belongs to a component; `"."` makes the whole styles tree global. Rules that no
+  component owns still join the base layer, as before.
+- **Previews have no wrapper element.** The markup sits directly in `<body>`; the `<main>` with inline
+  styles around it is gone. CSS or tests that target `main.layout-centered`, `main.layout-full` or
+  `main[data-component-id]` inside a preview need updating; `data-component-id` is now on `<body>`.
+- **`/api/component/<id>` returns 404** for an id that no component has.
+
+### Added
+
+- `assets.css` accepts full URLs, such as a web-font stylesheet.
+- References that start with an asset folder's name are rewritten to the served `/assets/…` path
+  when written root-absolute (`/images/logo.svg`), as PatternLab projects write them, and in `url()`
+  in compiled CSS.
+- A `centered` preview frame is as wide as its content and centred in the Stage. If a width media or
+  container query that styles the component would change at that width, the frame keeps the full
+  width instead. Gallery tiles fit and centre the same way.
+- PatternLab-style links (`/#/atoms/button`) open the matching view. An address that names nothing
+  says so in the Stage and links the closest matches; a view that fails to load says so too.
+- `pd dev` warns at startup about a `documentBase` entry that matches no file, and summarises the
+  unowned rules that are global without being listed.
+
+### Fixed
+
+- A `centered` preview whose height comes from the viewport (`height: 200vh` in the base layer, a
+  percentage chain) no longer grows without bound. Content-fitting such a height is circular — the
+  frame's height feeds the content's — and the frame used to double every tick to the browser's
+  layout ceiling, showing a size like `785 × 33554428`. The run of growth is now detected, the frame
+  keeps its last steady height and the content scrolls inside it, and the Console says why.
+- SCSS edits reach the preview live when `styles.entry` is set, and edits to base-layer styles
+  update live too.
+- `@import`, `@charset`, `@layer a, b` and `@namespace` kept their `;`: the next rule was being
+  swallowed and both were dropped, in `pd dev` and in `pd build`.
+- Components in numbered pattern folders own their CSS, whatever the styles folders are called.
+- Missing files return 404 instead of 200 with the workbench page, so broken asset paths show up.
+- Every `href` and `src` written into a preview is escaped.
+- The flattening and conflicts reports print their full path, and a bare wrapper element around
+  different includes is no longer reported as a flattened copy.
+- `styles.strategy` is optional.
+
+## 0.1.0-alpha.0
+
+First public alpha.

package/README.md

@@ -4,7 +4,7 @@ A workbench for HTML and CSS design systems, and a successor to PatternLab. Writ
 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.1.0-alpha.0).** Published under the `alpha` tag. Options and file conventions can still change
+> **Alpha (0.1.0-alpha.2).** Published under the `alpha` tag. Options and file conventions can still change
 > between releases.
 
 ## Requirements
@@ -32,6 +32,18 @@ npx pd init
 few starter components, and adds `dev`, `audit`, `typecheck` and `build:scripts` scripts. It never
 overwrites an existing file.
 
+### Installing `pd` globally
+
+```bash
+npm install --global pattern-dump@alpha
+pd init my-design-system
+```
+
+A global `pd` is handy for creating projects, but each project still needs its own local
+`pattern-dump` (which `pd init` installs): the config file imports `defineConfig` from it. A global `pd`
+runs its own version, not the project's, so inside a project prefer `npm run dev`, `npm run audit`
+and `npx pd build`, which always use the version the project depends on.
+
 ## Commands
 
 | Command | What it does |
@@ -80,6 +92,7 @@ export default defineConfig({
 - [Pattern packages](https://github.com/n8design/pattern-dump/blob/main/docs/guide/pattern-packages.md)
 - [Static build](https://github.com/n8design/pattern-dump/blob/main/docs/guide/static-build.md)
 - [Command line](https://github.com/n8design/pattern-dump/blob/main/docs/guide/cli.md)
+- [Changelog](https://github.com/n8design/pattern-dump/blob/main/CHANGELOG.md): what changed in each release
 
 ## Support
 

package/dist/chunks/chunk-3WZHFYHZ.js

@@ -0,0 +1,160 @@
+// packages/config/src/validate.ts
+var SHAPE = {
+  $schema: "string",
+  sourceDir: "string",
+  patternsDir: "string",
+  outDir: "string",
+  styles: {
+    keys: {
+      strategy: { values: ["parallel"], unsupported: ["co-located"] },
+      dir: "string",
+      entry: "string-or-strings"
+    },
+    required: ["dir"]
+  },
+  themes: {
+    keys: {
+      dir: "string",
+      default: "string",
+      switch: { values: ["attribute", "stylesheet"] },
+      swatch: { keys: { slots: "strings" }, required: ["slots"] }
+    },
+    required: ["dir", "default"]
+  },
+  assets: {
+    keys: {
+      strategy: { values: ["central"], unsupported: ["component-relative"] },
+      dir: "string-or-strings",
+      css: "strings"
+    }
+  },
+  scriptsDir: "string",
+  globalScripts: "strings",
+  dataDir: "string",
+  helpers: "string",
+  documentBase: "strings",
+  overviews: "boolean",
+  shell: {
+    keys: { brand: { keys: { title: "string", logo: "logo", logoAlt: "string", href: "string" } } }
+  },
+  packages: "packages",
+  exclude: "strings",
+  build: { keys: { outDir: "string", basePath: "string", audit: "boolean" } }
+};
+var REQUIRED = ["sourceDir", "patternsDir", "outDir", "styles"];
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isStrings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cur = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1));
+      prev = cur;
+    }
+  }
+  return row[b.length];
+}
+function suggest(key, known) {
+  let best;
+  let bestD = Infinity;
+  for (const k of known) {
+    const d = distance(key, k);
+    if (d < bestD) {
+      best = k;
+      bestD = d;
+    }
+  }
+  if (best === void 0) return void 0;
+  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) {
+  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}"`);
+  }
+  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}"?` : ""}`);
+  }
+  for (const key of known) {
+    if (value[key] !== void 0) checkValue(value[key], shape[key], `${at}${key}`, problems);
+  }
+}
+function checkValue(value, rule, at, problems) {
+  const fail = (expected) => problems.push(`"${at}" must be ${expected}`);
+  if (rule === "string") {
+    if (typeof value !== "string") fail("a string");
+    return;
+  }
+  if (rule === "boolean") {
+    if (typeof value !== "boolean") fail("true or false");
+    return;
+  }
+  if (rule === "strings") {
+    if (!isStrings(value)) fail("a list of strings");
+    return;
+  }
+  if (rule === "string-or-strings") {
+    if (typeof value !== "string" && !isStrings(value)) fail("a string or a list of strings");
+    return;
+  }
+  if (rule === "packages") {
+    const ok = Array.isArray(value) && value.every((p) => typeof p === "string" || isObject(p) && typeof p.name === "string" && (p.exclude === void 0 || isStrings(p.exclude)));
+    if (!ok) fail(`a list of package names or { name, exclude } objects`);
+    return;
+  }
+  if (rule === "logo") {
+    const ok = typeof value === "string" || isObject(value) && typeof value.light === "string" && typeof value.dark === "string";
+    if (!ok) fail(`a path or { light, dark }`);
+    return;
+  }
+  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`);
+    } else if (typeof value !== "string" || !rule.values.includes(value)) {
+      fail(rule.values.map((v) => `"${v}"`).join(" or "));
+    }
+    return;
+  }
+  if (!isObject(value)) {
+    fail("an object");
+    return;
+  }
+  checkObject(value, rule.keys, rule.required ?? [], `${at}.`, problems);
+}
+var ConfigError = class extends Error {
+  name = "ConfigError";
+};
+function configProblems(raw) {
+  if (!isObject(raw)) return ["the config must be an object (a .ts config must `export default defineConfig({ \u2026 })`)"];
+  const problems = [];
+  checkObject(raw, SHAPE, REQUIRED, "", problems);
+  return problems;
+}
+function validateConfig(raw, source) {
+  const problems = configProblems(raw);
+  if (problems.length > 0) {
+    throw new ConfigError(`${source}: invalid config
+${problems.map((p) => `  - ${p}`).join("\n")}`);
+  }
+  return raw;
+}
+
+// packages/config/src/index.ts
+function defineConfig(config) {
+  return config;
+}
+
+export {
+  ConfigError,
+  validateConfig,
+  defineConfig
+};

package/dist/dev-ui/main.css

@@ -914,6 +914,9 @@ figure.preview {
   margin-inline: auto;
   transition: width 2s ease;
 }
+.single-preview iframe.vp-measuring {
+  transition: none;
+}
 
 #preview-frame {
   background: Canvas;
@@ -986,7 +989,9 @@ figure.preview {
   padding-top: 0.5rem;
 }
 .gallery-item iframe {
-  width: 100%;
+  width: var(--vp-w, 100%);
+  max-width: 100%;
+  margin-inline: auto;
   height: var(--vp-h, auto); /* pd-height sets --vp-h; auto = UA 150px until first fire */
   border: none;
   display: block;
@@ -1773,16 +1778,42 @@ dialog.fullpage.fp-chrome-visible .fullpage-close {
   cursor: pointer;
 }
 
-.audit-scope-body {
-  margin: 0.4rem 0 0;
-  overflow-x: auto;
-  font-family: ui-monospace, Menlo, Consolas, monospace;
-  font-size: 0.72rem;
+.audit-scope-label {
+  margin: 0.5rem 0 0.25rem;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--pd-ink-muted);
+}
+
+.audit-scope-list {
+  margin: 0;
+  padding-inline-start: 1rem;
+  font-size: 0.75rem;
   line-height: 1.5;
-  white-space: pre-wrap;
   color: var(--pd-ink-muted);
 }
 
+.audit-scope-item + .audit-scope-item {
+  margin-top: 0.2rem;
+}
+
+.audit-scope-name {
+  color: var(--pd-ink);
+  font-weight: 600;
+}
+
+.audit-scope-code {
+  font-family: ui-monospace, Menlo, Consolas, monospace;
+  font-size: 0.95em;
+}
+
+.audit-scope-note {
+  margin: 0.5rem 0 0;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--pd-ink);
+}
+
 [data-resize] {
   position: absolute;
   z-index: 5;