Component files
The files of a Pattern Dump component and what each holds: Handlebars partials, data, docs and schema, variants, folder index.md files, scripts and assets.
src/patterns/
├── index.md the top-level folders' order
└── atoms/
├── index.md the folder's title, order and preview
└── button/
├── button.hbs the template: atoms/button
├── button.json its data
├── button.md its docs and metadata
├── button.schema.json its schema
├── button~icon.hbs a variant with markup of its own
└── button~secondary.json a variant with other data
A component is a Handlebars template, a .hbs file, in a folder under a patterns root. The files beside it with the same name give it data, documentation and a schema. A component's id names it in links and messages, and its handle names it in includes and tags.
Ids and handles
Pattern Dump reads only the folders inside each patterns root: a .hbs lying directly in the root is not a component. Files and folders whose name starts with . are skipped at every depth. Each root can leave out files and folders by glob: ** spans folders, * stays in one, ? is one character, and a folder's glob also matches with a trailing /.
- Id
- The template's path below the patterns root, without
.hbs. A file named like its folder takes the folder's id:atoms/button/button.hbsisatoms/button. - Handle
- The id's first and last segments, joined by
-, with the folders between dropped and~<variant>kept:molecules/quick-links/ql-list-buttonismolecules-ql-list-button. Numbers in front of a segment (00-,01_: digits followed by-or_) are dropped from the handle but kept in the id:00-atoms/01-global/00-colorsisatoms-colors. Digits that are part of a name stay (atoms/h1isatoms-h1,atoms/2col-gridisatoms-2col-grid), but2-colloses its2-.
Two components, one handle
- In one patterns root
- A collision. The first by sorted path keeps the handle; the other is quarantined, left out of the tree, and its page answers with a
HANDLE_COLLISIONerror naming both. Components that differ only by numbers in front, such as00-atoms/badgeandatoms/badge, collide too. - Across roots
- An override. The project comes first, then the pattern packages in order, and the earlier root's component wins, so the project's wins over any package's.
- A variant handle that is taken
- Dropped, without a
HANDLE_COLLISION.
Data, docs and schema
Files belong to a template by its exact name, in its folder: <name>.json, <name>.md and <name>.schema.json.
<name>.json- The data the component renders with. A component renders with the global data, then its
.json, then a variant's.json, then the data a render passes. Objects merge key by key; anything else, lists included, is replaced. A file that isn't valid JSON is aDATA_INVALIDerror,<file> is not valid JSON (<reason>); its data was not used, with the line and column; for an included component, the component that includes it reports it. <name>.md- The component's documentation, shown in the Inspector's Docs tab, with its metadata in the frontmatter (see The
.mdfile). <name>.schema.json- A JSON Schema for the component's data, checked against the merged data on every render. A name in the top-level
requiredthat is missing ornullis anUNFILLED_REQUIREDerror. A top-level property whose value doesn't match itstypeis aSHAPE_MISMATCHwarning; nested properties aren't type-checked. Every variant is checked against the base component's schema. A schema that isn't valid JSON is aSCHEMA_INVALIDerror at its line and column, and with a site it stopspd build.
A render's data is read-only: a helper that changes it throws.
Variants
A variant is a file beside the template, <name>~<variant>. Its name is the text between the first ~ and the next.
<name>~<variant>.hbs- Markup of its own, with its own sidecars by the same name:
button~icon.json,button~icon.md,button~icon.schema.json. <name>~<variant>.json- A data overlay: the base template with this data over the base's. It can have its own
.mdand.schema.jsontoo. It needs a<name>.hbsto overlay; without one, it is left out, andpd devreports it:[dev-server] <variant path>: a data variant needs <base path> to overlay, and there is none, so it is left out, shown in the Console as a warning.
A component made of variants with markup of their own alone, with no <name>.hbs, gets a base that renders empty, titled from <name>.md when there is one, with its variants listed.
A variant included or previewed by its own id, such as atoms/chip~danger, is the base rendered with that variant. It gets the base's data with the variant's on top, and the base's template unless it has its own. /preview/<base>~<variant> is the same document as /preview/<base>?variant=<variant>.
Includes
{{> <handle> }} includes another component, and the block form {{#> <handle>}}…{{/<handle>}} wraps content, which the included component places with {{> @partial-block}}. {{#if @partial-block}} is true only in a block call, and a block partial viewed on its own renders an empty block. A handle with ~ is quoted: {{> "atoms-button~secondary" }}.
An included component's own .json is only its default. The context it is included in, with the include's arguments, goes over it: a field of the including component with the same name wins, even when it isn't passed. A variant included by its handle gets its base's .json beneath its own. Inside an include, @root is still the top-level render's data, and @index and the like stay visible. An include on an indented line is not indented again, so a <pre> inside it keeps its text.
Relationships explains which includes count.
The .md file
Its metadata is read from the --- block at its top only: a key: line in the body, or in a file without the block, is text. A quoted value loses its quotes, and a key with an empty value counts as not set.
title- The name in the Nav Rail and the Inspector. Default: the last segment of the id. A variant without its own
.mdis titled<name>~<variant>. description- One line of free text, shown with the component.
statusstable,deprecatedordraft. Any other value, or none, isdraft.deprecated-use- One line of free text, shown with the component.
visibilitypublicorprivate; any other value is ignored. A private component is marked private in the tree and left out of folder galleries.order- A number that ranks the component among its siblings. See Folders.
previewcenteredorfull: how the component is previewed. See Preview layout.requireScript- A script, or a list (
[toggle, menu], or one- itemper line), loaded as a module after the markup, in order, each once. An item's path and.tsor.jsare dropped:scripts/toggleandtoggle.jsaretoggle, so a script in a subfolder of the scripts folder can't be named. A repeatedrequireScript:line counts only once, with its last value. requireAssets- A symbol set, or a list:
<id>.svg, elseimages/<id>.svg, from the first asset folder that has it, the project's before the packages'. It is inlined, hidden, into the preview; a preview leaves out a set no folder has without a word, while a site page fails on it.
A variant with no .md, or an empty one, takes the base's documentation, and keeps its own title, description and status.
The scripts and symbol sets of everything a component includes load with it. A script is looked up as <scripts folder>/<id>.ts, the project's first; one that doesn't exist is reported once at startup, [dev-server] requireScript "<raw>" on <component>: no <id>.ts in <dirs>, and its address answers 404. A full address (://) in globalScripts is loaded as it is.
Folders
A folder's index.md gives the folder its title, order and gallery, in its frontmatter; its body renders above the folder's gallery, with live examples and source blocks working. The first index.md found across the patterns roots, the project's first, is used whole.
title- Default: the folder's name, with
-and_as spaces and the first letter capitalised, numbers kept:04-templatesis "04 templates",quick-links"Quick links". order- A number ranks the folder among its siblings (default 0, lower first). A list (inline, one item per line, or text with commas) orders the folder's children. In it,
...stands for every child it doesn't name; without it, those come after the named ones. Unknown names are ignored. A number always wins over the list, and ties go alphabetically, withitem2beforeitem10.src/patterns/index.md's list orders the top-level folders. visibilityprivatekeeps the folder's components out of the galleries above it; its own gallery still lists them.overviewfalsegives the folder no gallery page.overviews: falsein the config does so for every folder.previewcenteredorfull. In a top-level folder it sets how its components are previewed; in a nested folder, only its own gallery page.
A folder gets a gallery page when it holds a public component somewhere below it that isn't inside a private folder. A gallery lists every public component at or under the folder, in tree order, except those in a private folder below it. A folder that is also a component, such as atoms/button/ with atoms/button/input/input.hbs, is a component with children: its index.md orders them but gives no title, and it gets no gallery page.
Preview layout
How a component is previewed, centered or full, is decided in this order, a later step winning over an earlier one:
fullfor the top-level folderspages,templatesandlayouts(numbers in front ignored), elsecentered;preview:in the top-level folder'sindex.md;x-pd-previewin the component's schema;preview:in the component's.md. An invalidx-pd-preview, or a schema that isn't valid JSON, leaves the earlier one.
Stylesheets
A stylesheet belongs to the component at the same path under the styles folder, with .scss and a leading _ dropped from every segment; <folder>/_index.scss and <folder>/<folder>.scss belong to <folder>. An exact match wins; otherwise numbers in front are ignored on both sides, and a name two components share after that belongs to neither and goes into the base layer. Style a component has which component owns a class.
Assets
Addresses that lead into an asset folder are rewritten by the folder's name: ../../<name>/… and /<name>/… become /assets/<name>/…, and a folder named assets needs no rewrite. With one asset folder, ./assets, /images/logo.svg is not rewritten.