Templates
Rules, checks and diagnostics
The rules a template holds every design to, what its check() returns, the order it checks in, snapshots, the rules decided by measuring a Canvas, and every template diagnostic with what triggers it.
A rule is something that must hold on the finished design, whatever filled it. A check is the template testing one design: its values, then the design they build, then its rules. A diagnostic is what a check says when something fails, with what to change.
Template examples shows checks from the command line; this page is the reference.
Rules over the result
Rules are checked on the finished design, whatever filled it: values, blocks or a slot’s content.
import { lint } from "@hyper-elements/lint";
rules: {
plugins: { lint: lint({ kind: "marketing" }) },
require: {
lint: ["unsubscribe", "preview-text", "contrast", "link-text", "lang"],
core: ["layout/overflow"],
},
links: { domains: ["acme.com", "*.acme.com"], params: { utm_source: "newsletter" }, schemes: ["mailto"] },
root: { lang: true },
},
| Rule | It requires | Where it fails |
|---|---|---|
require.lint |
Lint’s rules, by id: a finding of one is an error, with “(required by …)” | The lint rule’s own code |
require.core |
Checks of Elements’ own, by their codes: the list below | That code |
links.domains |
Every http(s) link’s host: acme.com itself, *.acme.com its subdomains |
template/link-domain |
links.params |
A query parameter on every link | template/link-param |
links.schemes |
The other schemes a link may use (mailto) |
template/link-scheme |
| A relative link is refused | template/link-relative |
|
root |
Root props that must be set. For a prop render takes from a value that may be missing, such as an optional language |
template/root-prop |
Each required rule ends passed, failed or not-run, in check()’s rules. One that didn’t run never counts as
passed.
plugins.lintislint()from@hyper-elements/lint, as you’d configure it for any design.require.lintnames the rules of it a design must pass.- Whether lint has each required rule is checked when the template is defined, before any design. A rule lint
doesn’t have, one that’s off as lint is configured (
unsubscribeneedskind: "marketing"), or one that doesn’t run on the template’s root (lint checks Emails and Pages) istemplate/rule-unavailable. If lint itself throws, its rules arenot-run, an error (template/rule-not-run). - A Canvas’s
image/…rules are decided when the image is measured.check()leaves themnot-run, andrenderImage()decides them as it draws. See measured rules. - Links are checked everywhere: in locked parts and a Menu’s too. A URL with a sending service’s tag (
{{…}}) is listed for review, or refused withtags: "deny"(template/link-tag). plugins.otherruns other plugins (email-clients’), whose findings are reported but can’t be required.
What require.core takes
| Code | What it finds | Runs on |
|---|---|---|
layout/overflow |
Content wider than the space it has | Every root |
layout/shrunk |
A Row’s children narrowed, because their widths add up to more than it has | Every root |
document/overflow |
A page’s content that looks taller than the page (an estimate) | Document |
canvas/overflow |
A Canvas’s content that looks taller than the Canvas (an estimate, made before it’s measured) | Canvas |
image/overflow |
Content that runs past the Canvas, measured | Canvas |
image/glyph |
A character no font given has | Canvas |
image/fit |
Fitted text that fits at none of its sizes | Canvas |
Requiring a check does two things. A finding of it is an error, with “(required by …)”, where on a design of its own
most of these are warnings. And the check has to have run: check() reports it not-run until it has, and a design
with a required rule that hasn’t run can’t be rendered. That’s what stops a Canvas passing on its values alone, before
anything measured it.
check()
check() is a template’s own method. launch.check(values, { format }) never throws. It checks one format: a
template with several needs one named. It returns
{ valid, values, diagnostics, review, rules, snapshots, template }:
import { formatDiagnostics } from "@hyper-elements/react";
import launch from "./templates/launch-graphic";
const checked = launch.check(values, { format: "square" });
if (!checked.valid) console.error(formatDiagnostics(checked.diagnostics));
The same from code is a whole script: it checks a launch’s values, then draws the image with its fonts and pictures.
| It returns | What it is |
|---|---|
valid |
Whether nothing is an error |
values |
The values as read: defaults filled in |
diagnostics |
What it found, each with its code, path and message |
review |
Each field’s guidance and the template’s own, for a person to judge. Never an error |
rules |
Each required rule: passed, failed or not-run |
snapshots |
The checked design, by the format’s name (default for a template with one size), where it’s valid |
template |
Its id and version |
It checks in two steps:
- The values, by their fields: unknown fields, missing required ones, values a field refuses, lists outside their counts, and each image’s declared size and name against its rules.
- The design it builds in each format, as
validate()checks any design, and what only the template knows: its root and its format’s size, its bindings, how each bound image is shown, a slot’s content against its limits, and the rules over the result.
The second step catches the template’s own mistakes, not only bad values: a contain image drawn at another aspect
than its file’s, say.
check(element), a function imported from @hyper-elements/react/template, checks a design whose root is a template
(<Launch … />), in its format or, without one, in every format, as the command line does.
Snapshots
A snapshot is the checked design, built once and recorded as plain data. check() returns one for each format.
render(), validate(), prepare(), inspect(), renderPdf() and renderImage() take one in place of an element,
and never build it again.
So what was checked is what’s rendered: a slot’s content that would render something else the second time never gets
a second time. Rendering launch.design()’s element instead runs a slot’s code again, unchecked.
Measured rules and checkLayout()
Some things can only be known by laying the design out with its real fonts and files: whether fitted text fits,
whether anything runs past the Canvas, whether a font has every character. That’s measuring, and only a Canvas is
measured. A required rule that needs it is not-run after check().
You rarely measure by hand:
| To | Use | What it does with the measured rules |
|---|---|---|
| Draw the image | renderImage() |
Measures as it draws, strictly: a missing font or content past the Canvas is an error, not a warning. A required rule that fails rejects, naming the rule |
| Check or render from the shell | The command line | Measures each format, and reports each rule |
| Get the report without drawing | layoutImage(), then checkLayout() |
Returns each image’s region, each fitted size and each rule’s result. It doesn’t draw, and doesn’t change the snapshot |
Anything else that writes output from a Canvas’s snapshot with a required rule still not-run refuses it
(template/rule-not-run): render(), which writes a Canvas’s HTML preview, can’t measure, and a rule that didn’t
run never counts as passed.
import { layoutImage } from "@hyper-elements/react/image";
import { checkLayout, sniffImage } from "@hyper-elements/react/template";
// fonts and images: as renderImage() takes them, each as bytes.
const checked = launch.check(values, { format: "square" });
const layout = await layoutImage(checked.snapshots.square!, { fonts, images, scale: 2 });
const report = checkLayout(launch, checked.values, { format: "square", layout, files: { artwork: sniffImage(artworkBytes)! }, checked });
// report: { regions, fits, rules, diagnostics }
It takes the checked values (to find each image field), the measured layout, each image’s files where you have
them, and checked itself so rules comes back whole: what check() decided, with the measured ones added.
checkLayout() is synchronous and pure. It gives:
| It gives | What it is |
|---|---|
regions |
Each bound image’s box, and the pixels it needs at the scale it’s rendered |
fits |
Each fitted field’s sizes that fit, and the one chosen |
rules |
The complete rules: the measured ones a template requires (image/overflow, image/glyph, image/fit) decided, by format |
diagnostics |
What it found: each image’s file against its declared size, its type and its transparency, and whether it would be upscaled in its region |
- An image’s region is the template’s own element bound to its field. A slot’s content that names the field is never read as one.
- It checks image files for the other roots too. An Email, a Page or a Document has no layout to measure, so to
check its image files in your own code, give an empty layout and the files:
checkLayout(template, values, { layout: { nodes: [], fits: [], diagnostics: [] }, files }).
Diagnostics
Every diagnostic has a code, a path into the values or the design, and a message that says what to change. One
on a bound node also names its field. Errors make a design invalid; warnings and notes don’t.
The values
| Code | What triggers it |
|---|---|
template/unknown-field |
A value for a field the template doesn’t have. The message names the fields it has |
template/required |
A required field isn’t given, or required text is empty or only spaces |
template/value |
A value its field refuses: the wrong type, text over its maxLength or outside its pattern, a block of an unknown type |
template/count |
A list or blocks outside its min and max |
template/format |
A format the template doesn’t have; none named where it has several; or a design built at another size than its format’s |
Images
| Code | What triggers it |
|---|---|
template/asset-aspect |
The size given is outside the field’s aspect |
template/asset-pixels |
The size given is under minWidth or minHeight, or the image would be upscaled in its region |
template/asset-type |
Its type isn’t one the field accepts: by its name, or by its file |
template/asset-size |
The size given isn’t its file’s |
template/asset-alpha |
Its file’s transparency isn’t what transparent asks |
template/asset-unread (note) |
A rule only the file decides (transparent, a type its name doesn’t give) wasn’t decided: the file wasn’t read |
template/asset-distorted |
A contain image is drawn at another aspect than its file’s. Size it with fitInside() |
template/asset-cropped |
A contain image is a Layer’s base (drawn as a cover), or a cover image loses more than maxCrop |
template/unbound (warning) |
An image field with rules that no node shows with field |
The design and its bindings
| Code | What triggers it |
|---|---|
template/render |
The template’s render threw |
template/root |
Its render returned another root than the template’s, or another template |
template/unknown-binding |
A field that names no field with a value |
template/field-path |
A field that isn’t a field’s path (headline, features[1], stories[1].image) |
field/dropped (note) |
A field inside a custom element’s own render: it’s left out |
template/not-root |
A template used beside or inside another node, or twice: a template is a design’s root |
template/not-template |
check(element) given a design whose root isn’t a template |
Slots
| Code | What triggers it |
|---|---|
template/slot-element |
Content uses an element the slot doesn’t allow, a root, an Html block, or its own definition of a custom element |
template/slot-style |
A style or a brand value the slot’s styles doesn’t take: a literal under "theme", any style under "none" |
template/slot-tokens |
Content sets tokens or theme |
template/slot-attrs |
Content sets attrs |
template/slot-count |
A type’s count is outside the slot’s count |
template/slot-field (note) |
A field inside the content: it’s the content’s own |
template/slot-host |
The template places the slot nowhere, more than once, or in a node that isn’t bound to it |
template/slot-unloaded |
A slot stored as its module, with no capture given in fragments |
template/slot-twice |
A slot’s content given both in the values and in fragments |
Rules over the result
| Code | What triggers it |
|---|---|
template/link-domain |
A link to a host that isn’t in links.domains |
template/link-param |
A link without a parameter links.params requires |
template/link-scheme |
A link with a scheme that isn’t in links.schemes |
template/link-relative |
A relative link |
template/link-tag |
A link with a sending service’s tag: a note for review, or an error with tags: "deny" |
template/root-prop |
A root prop rules.root requires isn’t set |
template/rule-not-run |
A required rule that didn’t run: a note for a measured rule until the image is measured; an error if lint failed, or an output function was given the snapshot first |
A lint rule’s code, image/overflow, layout/overflow… |
A finding of a required rule: an error, its message ending “(required by …)” |
Fitted text and measuring
| Code | What triggers it |
|---|---|
image/fit |
Fitted text fits at none of its sizes. The message has the lines it takes and roughly how much to cut |
image/overflow |
Content runs past the Canvas |
image/glyph |
A character no font given has |
image/font, image/font-weight |
A family, or a weight, with no font file given |
fit/inline |
A run inside fitted text is in another size, font, weight or line height |
style/fit |
A fontSize written beside fit’s sizes |
image/overflow, image/glyph and the font codes are warnings for a design on its own, and errors where it’s drawn strictly, as a design made from a template always is. The others are always errors.
Defining a template
These are thrown by template() itself, when the module loads:
| Code | What triggers it |
|---|---|
template/spec |
A spec that isn’t a template’s: a bad id or version, a missing example, fields beside design |
template/field-name |
A field named format, key, ref or children |
template/block-type |
A block type with a field named type |
template/slot-allow |
A slot’s allow isn’t a list of elements or "all" |
template/rule-unavailable |
A required rule that lint doesn’t have, that’s off as lint is configured, or that doesn’t run on the template’s root |
template/plugin |
A plugin in rules.plugins.other that’s a Promise: await it first |
An annotated template’s markers have their own:
| Code | What triggers it |
|---|---|
template/inline-kind |
A marker for a field that isn’t text, a link, an image or a slot |
template/inline-target |
A marker that isn’t on a built-in element |
template/inline-content |
A text marker’s node holds something other than one string |
template/inline-unplaced |
A field in open whose marker isn’t in design |
template/inline-unlisted |
A marker in design that isn’t named in open |
template/inline-twice |
One marker given two names |
template/inline-nested |
A marker inside a slot’s host, where the slot’s content replaces it |
template/inline-hidden |
A marker inside the render of a function or a custom element of your own |
Values files
| Code | What triggers it |
|---|---|
template/values-file |
A file that isn’t { version: 1, template: { module, id, version }, values, … } |
template/id |
A file made for another template |
template/version |
A file made with a newer version; a new major with no migration from the file’s; or a migration that threw |
template/upgraded (note) |
A file made with an older version, read with this one |
template/changed (warning) |
The template’s module changed under the same version (the command line) |
template/asset-changed (warning) |
A file a design recorded changed under the same name (the command line) |
Snapshots and captured content
| Code | What triggers it |
|---|---|
jsx/value |
A value that isn’t plain data: a function, a class instance |
jsx/fragment |
A capture that isn’t one: its kind, its version, a node’s keys, more than 64 levels deep or 8 MB |
jsx/slot-mark |
slotMark() used outside a snapshot |
builder/snapshot, builder/template |
toDesign() given a snapshot or a template design: it takes a design’s element (design(values)) |
The command line’s own codes (cli/…, extract/…) are on Templates in the command line.