Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

### Changed

- **A skin that reads a custom property nothing defines no longer builds:** a `var(--x)` without a fallback in the
project's styles needs `--x` defined in the style guide or its packages, a fallback, or `--x` listed in
`storefront.checks.allowProperties` (see Added).
- `toc` is a key the build owns now (the table of contents): a layout's schema that declares it must rename it.
- **A storefront page's "last changed" date is the author's, never git's.** Git's last commit counts a typo fix or a
reformat as a change, so it is no longer used for anything a reader or a search engine sees. A page sets
Expand Down Expand Up @@ -37,6 +40,16 @@

### Added

- **The class check.** `pd build` lists each class on a site page that no component or style of the style guide
defines, naming the page's file and line: `about.md:12: class "hero-big-title" isn't defined by any component or
style`. State classes (`is-`, `has-`, `js-`) and Pattern Dump's own are allowed, and so is
`storefront.checks.allowClasses`. A warning; `storefront.checks.classes: "error"` stops the build, `"off"` skips it.
- **Custom properties nothing defines stop the build.** A `var(--x)` without a fallback in the project's own styles,
with no `--x` in any stylesheet of the style guide or its packages (or a `style` attribute the build writes), fails
`pd build`, naming the file and line. A property JavaScript sets goes in `storefront.checks.allowProperties`.
- **`llms.txt`.** `pd build` writes one at the site's root (llmstxt.org): the site's title and description, then
the top-level pages and each collection, every page with its title, link and teaser. The same pages as the sitemap;
absolute URLs with `storefront.url`, under the site's path. On by default; `storefront.llms: false` turns it off.
- **Regions.** A layout declares regions besides the body on `page.regions` (`"x-pd-regions": ["sidebar"]`) and writes
each as `{{{page.regions.sidebar}}}`, null when the page puts nothing there. A placed component goes into one with
`region="sidebar"` on its tag, or its schema's `"x-pd-region"`; components keep the page's order there. A region
Expand Down
13 changes: 10 additions & 3 deletions apps/dev-ui/src/inspector/panel.ts
Original file line number Diff line number Diff line change
Expand Up @@ -147,9 +147,16 @@ export async function renderPanel(): Promise<void> {
appendComponentGroup("Used by", relAvail.usedBy, section);
// A layout of a project with a website: the pages that render with it, and where each got its layout.
if (relAvail.pages) {
appendPlainGroup("Pages", relAvail.pages.map(p => `${p.path} (${
p.source === "own" ? "its own layout" : p.source === "default" ? "the default layout" : `childLayout of ${p.from ?? "its folder"}`
})`), section);
appendPlainGroup("Pages", relAvail.pages.map(p => {
if (p.source === "generated") {
const kind = p.generated.kind;
const what = p.generated.term !== undefined ? `the page of the ${kind} "${p.generated.term}"` : `the index of the ${kind === "tag" ? "tags" : "categories"}`;
return `${p.route} (${what}, from storefront.${kind}Pages)`;
}
return `${p.path} (${
p.source === "own" ? "its own layout" : p.source === "default" ? "the default layout" : `childLayout of ${p.from ?? "its folder"}`
})`;
}), section);
}

// Style umbrella: groups Style uses + Style modules under a shared heading.
Expand Down
4 changes: 4 additions & 0 deletions docs/guide/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,10 @@ in [storefront.md](storefront.md).
| `storefront.tagPages` | boolean or object | on when the skin has `layouts/tag` | A page per tag at `/tags/<key>/` and an index at `/tags/`. `false`: off; `true` or `{ path, title }`: on, and a missing layout is a problem ([storefront.md](storefront.md#tag-and-category-pages)) |
| `storefront.categoryPages` | boolean or object | on when the skin has `layouts/category` | The same for categories, at `/categories/` |
| `storefront.search` | boolean | on when the project has Pagefind | Search: `pd build` indexes every page's own content with Pagefind into `_pd/search/`. `true`: a build without Pagefind stops; `false`: off ([storefront.md](storefront.md#search)) |
| `storefront.llms` | boolean | `true` (`false` with `index: false`) | `pd build` writes `llms.txt` at the site's root: the site's title and description and each page's title, link and teaser, by collection ([storefront.md](storefront.md#search-engines-and-link-previews)). `false`: none |
| `storefront.checks.classes` | `"warning"`, `"error"` or `"off"` | `"warning"` | The class check: a class on a page that no component or style of the style guide defines is listed in the report, stops the build, or isn't checked ([storefront.md](storefront.md#the-class-check)) |
| `storefront.checks.allowClasses` | list of strings | `[]` | Classes a page may carry anyway: names, or a prefix ending in `*` (`"chart-*"`) |
| `storefront.checks.allowProperties` | list of strings | `[]` | Custom properties JavaScript sets, which the skin's `var()` may read with no definition in CSS: names, or a prefix ending in `*` (`"--chart-*"`). Any other `var()` without a fallback and without a definition stops the build ([storefront.md](storefront.md#custom-properties-nothing-defines)) |
| `storefront.site` | object | (none) | Values every page shares, such as the site's title or footer line. Every layout gets them as `site`, and a page cannot set them. Their keys and types are what the `site` property of `partials/base`'s schema declares, and they are checked against it. One key is Pattern Dump's: `navigations`, named lists of links ([storefront.md](storefront.md#declared-navigations)) |

## When changes take effect
Expand Down
53 changes: 53 additions & 0 deletions docs/guide/storefront.md
Original file line number Diff line number Diff line change
Expand Up @@ -999,6 +999,15 @@ redirect pages, each with a `lastmod` of its `updated`, else its `date`, else no
shallow clone, a `datePublished` git would give is left out of the JSON-LD and the build notes it once (in CI,
check out with `fetch-depth: 0`). A layout that shows `page.created` still fails the build there.

**`llms.txt`** ([llmstxt.org](https://llmstxt.org/)) gives a language model the site in one file: the site's title
(`storefront.site.title`, else the home page's) and the home page's description as a quote, then a `## Pages` section
with the top-level pages and one section per collection (a folder with an `index.md`, headed by its title and led by
it), in nav order. Each page is a line `- [title](url): teaser`, its description else its first paragraph. It lists
the same pages as the sitemap (no draft, no scheduled page, none with `index: false`); tag and category pages are left
out, since their pages are listed. URLs are absolute with `storefront.url`, else paths from the site's root. `pd
build` writes it to the site's root (under a path, at `<path>llms.txt`); `pd dev` has none. On unless the site has
`index: false`; `storefront.llms: false` turns it off.

**`robots.txt`.** Both output roots get one. The storefront's keeps crawlers out of `/preview/` (the live
examples: component demos, not pages) and names the sitemap. The workbench's keeps them out of its
previews only; the workbench itself stays searchable. A workbench on the storefront's own host
Expand Down Expand Up @@ -1097,6 +1106,7 @@ site/
404.html the 404 page
setup/index.html start/index.html pages that forward from old routes
robots.txt sitemap.xml for crawlers (the sitemap with storefront.url)
llms.txt the site for language models
preview/components/callout/index.html the previews the pages show
_pd/ assets/ what pages and previews reference
.nojekyll
Expand Down Expand Up @@ -1183,6 +1193,49 @@ pd build: the storefront has broken links, so nothing was written:
Code examples are text, so a link written in one is not checked. In `pd dev`, a page's links to pages that don't
exist and to anchors it doesn't have are warnings in the terminal; the full check runs in `pd build`.

### The class check

Before it writes anything, `pd build` looks at every class on every page of the site (its pages and its 404 page)
and lists each one the style guide doesn't define, so a class improvised outside the design system shows, whether a
person or an agent wrote it.

- **Defined:** a class a stylesheet of the style guide names in a selector (the project's and its packages', and each
stylesheet the site loads), and a class a component's template writes, styled or not. A word a template builds
from a value, such as `doc-toc-h{{level}}`, defines every class that starts that way. A page's own `<style>` counts
too.
- **Allowed:** state classes JavaScript adds (`is-`, `has-`, `js-`), the classes Pattern Dump writes itself (code
highlighting, the copy button, pattern links, live examples), and the names in `storefront.checks.allowClasses`
(a trailing `*` for a prefix).
- A page's markdown can't write HTML, so what the check finds is a value a component writes into a `class`
attribute (`<pd-components-badge look="hero-big-title">`, a template with `class="{{look}}"`). It names the page's
file and the line that gives the value.

```
[pd build] classes: 1 outside the design system:
[pd build] warning: about.md:12: class "hero-big-title" isn't defined by any component or style
```

A warning by default; with `storefront.checks.classes: "error"` it stops the build, and `"off"` skips the check.

### Custom properties nothing defines

A `var(--x)` in the project's own styles (its styles folder, SCSS or CSS) with no `--x` defined anywhere stops the
build, naming the file and line. Without the check it falls back to nothing, and a colour just goes missing on screen.

- **Defined:** `--x:` or `@property --x` in any compiled stylesheet of the style guide (the project's and its
packages', the base layer and the themes) or one the site loads, and `--x:` in a `style` attribute of a page or
preview the build writes (`style="--cols: {{cols}}"` in a template).
- `var(--x, fallback)` is fine: it says what to show without `--x`. A name Sass builds (`var(--#{$name})`) and a
`var()` in a comment are not checked. A package's own stylesheets are not checked: they are not the project's to fix.
- A property JavaScript sets goes in `storefront.checks.allowProperties` (a trailing `*` for a prefix).

```
pd build: the skin reads custom properties nothing defines, so nothing was written:
- src/styles/components/card.scss:42: var(--card-gap) reads a custom property nothing defines: define --card-gap
in the skin, give it a fallback (var(--card-gap, ...)), or, if JavaScript sets it, list it in
storefront.checks.allowProperties
```

### The accessibility check

After the link check, `pd build` checks every page of the site (not the previews or the pages that forward from old
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
"e2e:storefront": "nx run storefront-bench:e2e",
"e2e:package-bench": "nx run package-bench:e2e",
"dev:check": "node scripts/check-server-fresh.mjs",
"test:scripts": "node --test scripts/ci/burn-in.test.mjs scripts/no-em-dash.test.mjs",
"test:scripts": "node --test scripts/ci/burn-in.test.mjs scripts/no-em-dash.test.mjs scripts/e2e-specs.test.mjs",
"burn-in": "node scripts/ci/burn-in.mjs",
"pack:pd": "npm run build && node packages/cli/scripts/pack.mjs",
"verify:install": "node scripts/verify-install.mjs",
Expand Down
22 changes: 22 additions & 0 deletions packages/config/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,28 @@ export interface StorefrontConfig {
* `true`: on, and a build without Pagefind stops. `false`: off. The search UI is a component of the skin's.
*/
search?: boolean;
/**
* llms.txt (llmstxt.org): pd build writes one at the site's root, with the site's title and description and each
* page's title, link and teaser, by collection; the same pages as the sitemap. Left out: on, unless `index` is
* false. `false`: none.
*/
llms?: boolean;
/** pd build's checks of the site against its style guide. */
checks?: StorefrontChecks;
}

/** storefront.checks: what pd build checks the site's classes and custom properties against. */
export interface StorefrontChecks {
/**
* A class on a page that no component or style of the style guide defines: `"warning"` (the default) lists it in
* the report, `"error"` stops the build, `"off"` skips the check.
*/
classes?: "warning" | "error" | "off";
/** Classes a page may carry anyway: names, or a prefix ending in `*` (`"chart-*"`). */
allowClasses?: string[];
/** Custom properties JavaScript sets, which a skin's var() may read without a definition in CSS: names, or a prefix
* ending in `*` (`"--chart-*"`). */
allowProperties?: string[];
}

/** storefront.tagPages and storefront.categoryPages as an object. */
Expand Down
16 changes: 16 additions & 0 deletions packages/config/src/validate.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,22 @@ describe("configProblems — storefront", () => {
expect(storefront({ ...base, search: "pagefind" })).toEqual([`"storefront.search" must be true or false`]);
});

it("takes llms: true or false", () => {
const base = { pagesDir: "./pages", outDir: "./www" };
expect(storefront({ ...base, llms: false })).toEqual([]);
expect(storefront({ ...base, llms: "no" })).toEqual([`"storefront.llms" must be true or false`]);
});

it("takes checks: classes warning, error or off, and lists of allowed classes and properties", () => {
const base = { pagesDir: "./pages", outDir: "./www" };
expect(storefront({ ...base, checks: { classes: "error", allowClasses: ["chart-*"], allowProperties: ["--x"] } })).toEqual([]);
expect(storefront({ ...base, checks: { classes: "strict", allowClasses: "chart-*", allowProperty: [] } })).toEqual([
`unknown key "storefront.checks.allowProperty": did you mean "storefront.checks.allowProperties"?`,
`"storefront.checks.classes" must be "warning" or "error" or "off"`,
`"storefront.checks.allowClasses" must be a list of strings`,
]);
});

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" }]) {
Expand Down
2 changes: 2 additions & 0 deletions packages/config/src/validate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,8 @@ const SHAPE: Shape = {
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", tags: "tags", tagPages: "term-pages", categoryPages: "term-pages", search: "boolean",
llms: "boolean",
checks: { keys: { classes: { values: ["warning", "error", "off"] }, allowClasses: "strings", allowProperties: "strings" } },
},
required: ["pagesDir", "outDir"],
},
Expand Down
19 changes: 17 additions & 2 deletions packages/contracts/src/dev-protocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -483,8 +483,12 @@ export interface RelationshipsAvailable {
pages?: LayoutPageUse[];
}

/** A storefront page that renders with a layout, and where its layout came from. */
export interface LayoutPageUse {
/** A storefront page that renders with a layout, and where its layout came from: a page file, or a page Pattern Dump
* generated. */
export type LayoutPageUse = LayoutFilePageUse | LayoutGeneratedPageUse;

/** A page of the pages folder that renders with a layout. */
export interface LayoutFilePageUse {
route: string;
/** The page file, relative to the pages folder ("articles/one.md"). */
path: string;
Expand All @@ -495,6 +499,17 @@ export interface LayoutPageUse {
from?: string;
}

/** A page Pattern Dump generated (a tag's or category's page, or the index of them: storefront.tagPages,
* storefront.categoryPages), which has no file. Its layout is the one of its kind (layouts/tag, tags, category,
* categories). */
export interface LayoutGeneratedPageUse {
route: string;
source: "generated";
/** What generated it: the tag or category whose page it is (`term`, its key), or without `term` the index of
* that kind. */
generated: { kind: "tag" | "category"; term?: string };
}

export type Relationships = RelationshipsAvailable;

/**
Expand Down
6 changes: 6 additions & 0 deletions packages/core/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,12 @@ export async function runBuild(
console.log(`[pd build] images: ${n ? `${n} with a variant that doesn't fit:` : "every variant fits its box"}`);
for (const w of report.images.warnings) console.log(`[pd build] warning: ${w}`);
}
if (report.classes) {
const n = report.classes.warnings.length;
console.log(`[pd build] classes: ${n ? `${n} outside the design system:` : "every class on the site's pages is the style guide's"}`);
for (const w of report.classes.warnings) console.log(`[pd build] warning: ${w}`);
}
if (report.llms) console.log(`[pd build] llms.txt: ${report.llms.pages} page${report.llms.pages === 1 ? "" : "s"}`);
if (report.search) {
console.log(`[pd build] search: ${report.search.pages} pages indexed → ${report.search.files} files in _pd/search/ (${(report.search.bytes / 1024).toFixed(0)} KB)`);
}
Expand Down
20 changes: 18 additions & 2 deletions packages/dev-server/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ const SILENT_RELOADER: HotReloader = {
close: async () => { /* nothing opened */ },
};
import { createServer } from "node:http";
import { stat } from "node:fs/promises";
import { readFile, stat } from "node:fs/promises";
import { join, sep } from "node:path";
import { fileURLToPath } from "node:url";
// HTTP/HTML leaf helpers. Kept in their own module because `escapeHtml` is shared by the Markdown
Expand Down Expand Up @@ -72,7 +72,7 @@ export type { StaticBuildOptions, StaticBuildReport } from "./static-build.js";
// All mutable server state in one typed object — the seam that lets routes and the watcher
// stop sharing lexical scope. Its header documents the three hazards.
import { reportUnresolvableScripts } from "./requires.js";
import { applyStyleData, cachedDiscovery, compositionFor, createServerState, setDiscovery } from "./server-state.js";
import { applyStyleData, cachedDiscovery, compositionFor, createServerState, currentDiscovery, setDiscovery } from "./server-state.js";
// Resolved paths + flags, derived once from PatternDumpConfig against the ONE resolution base.
import { resolveServerConfig } from "./server-config.js";
import { createImageService } from "./image-service.js";
Expand Down Expand Up @@ -154,6 +154,15 @@ export interface DevServerOptions {
export interface DevServer {
port: number;
close(): Promise<void>;
/** For pd build's style checks (class-check.ts, property-check.ts), not part of the HTTP contract: every compiled
* stylesheet of the style guide (each component's, the base layer, each theme; project and packages) and every
* component template's source. */
styleGuide(): Promise<StyleGuideSources>;
}

export interface StyleGuideSources {
stylesheets: string[];
templates: string[];
}

const devUiDist = resolveDevUiDist(import.meta.url);
Expand Down Expand Up @@ -391,6 +400,13 @@ export async function startDevServer(

return {
port: actualPort,
async styleGuide() {
const discovery = await currentDiscovery(state, patternRoots);
await state.style.get(() => buildAllStyleData(styleRoots, baseComponentIds(discovery)));
const templates = await Promise.all([...discovery.discoveryMap.values()].filter(e => e.hbsPath !== "")
.map(e => readFile(e.hbsPath, "utf8").catch(() => "")));
return { stylesheets: [...state.perComponentCss.values(), state.baseCss, ...state.themeCss.values()], templates };
},
async close() {
await watcher?.close();
await hotreloader.close();
Expand Down
3 changes: 2 additions & 1 deletion packages/dev-server/src/routes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -481,7 +481,8 @@ async function routeRequest(
// 200 + RENDER_ERROR, not 404.
// A layout of a project with a website: the pages that render with it, and where each got it.
if (cfg.storefront && /^layouts\/[^/~]+$/.test(componentId)) {
detail.relationships.pages = layoutPages(await readStorefrontPages(ctx, cfg.storefront), componentId.slice("layouts/".length));
// With the discovery map, so the tag and category pages its layouts generate are in the model too.
detail.relationships.pages = layoutPages(await readStorefrontPages(ctx, cfg.storefront, discovery.discoveryMap), componentId.slice("layouts/".length));
}
const quarantineEntry = discovery.quarantineMap.get(componentId);
const { previewHtml, diagnostics } = await checkComponent(componentId, variant, render, quarantineEntry);
Expand Down
Loading
Loading