@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/themeRecipeWords.js

@@ -0,0 +1,156 @@
+export const RECIPE_WORDS = {
+    nav: {
+        tint: 'The current entry sits on a soft tint of the accent; the other rows stay plain.',
+        inverted: 'The current entry is inverted, the menu’s ink as its ground: the boldest mark, square and high-contrast.',
+        wash: 'The current entry sits on a wash of the menu’s own accent, stronger than tint, for a menu in a brand color.',
+        underline: 'The current entry in the top bar is marked by a 3px rule of the menu’s accent under it, with no fill.',
+        pill: 'Every row is a rounded pill with room around it; the current one is filled in the accent’s tint, its word in the accent.',
+        quiet: 'The current entry is barely shaded in the menu’s ink, with no accent at all: the calmest mark.',
+        slot: 'The current entry is an ink block, as inverted, with a 3px marker of the menu’s accent beside it, like a tool’s slot on a pegboard.',
+    },
+    bar: {
+        plain: 'The top bar is the menu’s ground with a hairline under it.',
+        ruled: 'The top bar ends in a 2px rule instead of a hairline, and casts no shadow.',
+        dark: 'The top bar takes the menu’s ground and inks, so a dark or brand-colored menu runs across the top too.',
+        airy: 'The top bar is taller, with a large bold brand name and a wide, raised search box.',
+        soft: 'The top bar is a panel in the surface color with a hairline under it, apart from the menu beside it.',
+    },
+    tabs: {
+        pill: 'The chosen tab is a filled pill; the others are plain words.',
+        inverted: 'The chosen tab is inverted, the ink as its ground: square, high-contrast.',
+        underline: 'The tabs stand on a hairline, wide apart, the chosen one underlined in the accent with no fill.',
+        rule: 'The chosen tab is underlined by a 2px rule in the link color with no fill, the tabs packed as written.',
+        chosen: 'The chosen tab sits on a soft tint of the accent in the ink, wider apart, with no underline.',
+    },
+    windows: {
+        segmented: 'The period picker is a segmented control, the chosen period filled.',
+        lifted: 'The period picker is a sunken tray, the chosen period a raised white key on it.',
+        chosen: 'The period picker has no tray; the chosen period sits on a soft tint of the accent.',
+    },
+    stat: {
+        plain: 'A stat is a figure and its label with no frame.',
+        framed: 'Each stat is a card framed by a line in the ink: square and stark.',
+        topline: 'Each stat card has a 3px rule in the first chart color along its top.',
+        ruled: 'Each stat stands open under a 2px rule in the ink, with no card or shadow, like a printed page.',
+        icon: 'Each stat is a card with its icon in a round tint of a chart color above the label, and a large bold figure.',
+        panel: 'Each stat is a panel on the surface with a hairline and the look’s card shadow.',
+        divided: 'The stats share one strip, parted by hairlines, with no cards: the quietest arrangement.',
+    },
+    section: {
+        open: 'A dashboard section stands open on the page under its rule.',
+        card: 'Each dashboard section is a card with a hairline and the card shadow, its table drawn to the card’s edges.',
+        panel: 'Each dashboard section is a panel like card, but a section in the side column stays open on the page.',
+    },
+    fields: {
+        open: 'A record’s field groups and forms stand open on the page.',
+        panel: 'Each field group and form is a panel on the surface with a hairline; its labels stay as the look draws them.',
+        card: 'Each field group and form is a card with a hairline and the card shadow, its labels muted and the values in the interface face.',
+        rail: 'Field groups stand open, and the side column’s cards become captioned groups between hairlines.',
+    },
+    table: {
+        open: 'Rows stand on the page under a rule, the head as the look draws it.',
+        tinted: 'As open, but a hovered row takes a tint of the accent and its check boxes the accent: the same until a pointer moves.',
+        hairline: 'The head sits on a hairline in 12.5px semibold, the rows in 13.5px: open, a little roomier.',
+        card: 'The table is a card: muted 12px heads on a hairline, faint row rules and taller rows.',
+        quiet: 'The table is a card of quiet rows, a work queue’s open button folded to a chevron at the row’s end.',
+        banded: 'As open, but every other row lies on the band color (colors.band, or the raised ground), each ink measured on it.',
+    },
+    status: {
+        dot: 'A status word in its tone with a dot before it.',
+        pill: 'A status word on a pill tinted with its tone, without a dot.',
+        'pill-dot': 'A status word on a pill tinted with its tone, with a small dot inside it.',
+        quiet: 'A status word in the ink with a dot in its tone: the color is only the dot.',
+    },
+    board: {
+        ruled: 'A board’s lanes are outlined by a hairline; its cards lie flat on them.',
+        soft: 'As ruled, but each card casts the look’s card shadow: only the cards lift.',
+        strip: 'Each lane is headed by a strip tinted with its tone, its cards white on the lane.',
+    },
+    chart: {
+        plain: 'A chart is its lines or bars on a light grid.',
+        wash: 'An area under a line is washed in the first chart color.',
+        gradient: 'An area fades from the line down to nothing, the line heavier and the grid dashed.',
+        line: 'Only the lines: no areas, a fine solid grid and small ticks.',
+    },
+    buttons: {
+        accent: 'The primary button is filled in the accent; the rest are quiet.',
+        raised: 'Secondary buttons are white keys with a hairline and a small shadow, raised off the page.',
+        keyed: 'Buttons are hard-edged keys: the primary one filled in the accent with an ink edge, like a hazard tag, the rest edged in the ink.',
+    },
+    links: {
+        plain: 'A link to another record is in the link color without an underline.',
+        underline: 'A link to another record is underlined, so it reads as one without color.',
+    },
+    rules: {
+        ink: 'A record’s sections are announced by a 2px rule in the ink.',
+        hairline: 'A record’s sections are announced by a 1px hairline instead.',
+        double: 'A 1px hairline announces a record’s sections as in hairline, a box is ruled in the strong line, and a table’s heads close with a double rule.',
+    },
+    avatar: {
+        plain: 'A record’s avatar is its initials in a small square.',
+        large: 'A record’s avatar is 44px, in the look’s corners.',
+        round: 'A record’s avatar is 44px and round, and the menu’s and the account’s marks are round too.',
+    },
+    workflow: {
+        markers: 'A workflow is a track of thin segments, the label under each.',
+        pills: 'A workflow is a row of pills with a dot each: a step walked in the good tint, the current one in the accent’s.',
+    },
+    banner: {
+        tint: 'A dashboard’s banner note is a box tinted with the accent.',
+        gradient: 'A dashboard’s banner note is a soft gradient from the accent to the second chart color.',
+        plain: 'A dashboard’s banner note stands on the page with no box, its eyebrow in the link color.',
+    },
+    steps: {
+        flat: 'A breakdown drawn as steps is a row of cards on the surface with a hairline.',
+        tinted: 'Each step’s card is tinted with its tone: good, warning, critical or the accent.',
+        strip: 'The steps are one strip of figures parted by hairlines, with no cards or marks.',
+    },
+    lanes: {
+        tint: 'A board lane’s value in its head is on its tone’s tint.',
+        tag: 'A board lane’s value is a solid tag in its tone, in white capitals.',
+        plain: 'A board lane’s value is its name in plain ink.',
+    },
+    header: {
+        plain: 'A record’s head and a list’s stand on the page’s ground, under the trail’s hairline.',
+        band: 'A record’s head and a list’s are one band of the raised ground from edge to edge: the trail, the title, its status, facts and verbs, a list’s tabs and filters; the contents keep their edge.',
+        hero: 'A band, with the record’s avatar large beside its title (above it on a phone); a record without one, and a list, draw the band.',
+    },
+    required: {
+        star: 'A required field wears a red star after its label; an optional one wears nothing.',
+        'optional-word': 'A required field wears nothing and an optional one says “(optional)” after its label, quietly; the form’s own words, in the reader’s language.',
+    },
+    checkbox: {
+        native: 'A checkbox is the browser’s own, in the accent.',
+        drawn: 'A checkbox is drawn: a square in the field’s fill with the control’s edge and corner, the accent with a check when on.',
+    },
+    formStep: {
+        plain: 'A multi-step form’s step header is its title over its lead, with nothing between it and the fields.',
+        ruled: 'A multi-step form’s step header ends in a hairline, which parts it from the fields under it.',
+    },
+    actionBar: {
+        plain: 'A form’s sticky action bar stands on a hairline over the page.',
+        raised: 'A form’s sticky action bar is raised on the surface with a soft lift, in place of the hairline.',
+    },
+};
+/** One part's values said, in the menu's order: "`tint`: …. `inverted`: …." — the schema's description of the part. */
+export function recipeDescription(part) {
+    return Object.entries(RECIPE_WORDS[part])
+        .map(([value, words]) => `\`${value}\`: ${words}`)
+        .join(' ');
+}
+/**
+ * Each type role said in a sentence: what it draws and what it takes. A role is not a menu of values but a few
+ * properties (themeType.ts holds their ranges), so this is the schema's description of the role and the gallery's
+ * Type section, where the three recipes it replaced (labels, headings, figures) were.
+ */
+export const TYPE_WORDS = {
+    display: 'A landing’s headline: its face, size (28px to 56px), leading, tracking, weight and features.',
+    title: 'A record’s and a dashboard’s name: its face, size (20px to 36px), leading, tracking, weight, case and features; its weight is every heading’s.',
+    heading: 'A list naming itself over its rows: its face, size (16px to 28px), leading, tracking, weight (omitted, the title’s), case and features.',
+    section: 'A section’s title on a record and a dashboard: its face, case and features; a dashboard’s section title also takes a size (12px to 20px), tracking and weight.',
+    body: 'Prose, fields and the interface, at the base size: its leading (1.35 to 1.8) and features.',
+    label: 'A column’s head, a stat’s label and a record’s tabs, at the base size: their face, tracking, weight (400 to 700), case and features; upper sets them a step smaller.',
+    data: 'A table’s cells and a record’s values, in the data face at the base size: their features, tabular figures kept, and its reach: every value, or figures only (figures, keys and dates, a record header’s facts too).',
+    figure: 'A stat’s figure: its face, size (18px to 40px), tracking, weight and features, tabular figures kept.',
+    nav: 'The menu’s entries in the bar, at the base size: their face, tracking, weight (400 to 600) and case; upper sets them a step smaller.',
+};

package/dist/shared/themeRecipes.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The recipe menu: every part a theme may dress, the treatments it may pick,
+ * and the `data-look-*` attributes a worn theme sets on the root. The browser
+ * needs this at first paint and nothing else of the theme machinery, so it is
+ * a module of its own: a module a first-paint file imports is in the first
+ * paint whole.
+ */
+import type { ThemeDefinition, ThemeDensity, ThemePart, ThemePartStyle, ThemeRecipes, ThemeTypeDefinition, ThemeTypeRoleDefinition } from '../../schema/theme.js';
+/**
+ * Every part a theme may dress and the treatments it may pick, and the sheet
+ * its rules live in: `null` is the first stylesheet (themeFamilies.css,
+ * kit.css), a name is a sheet of its own, fetched when a worn theme picks the
+ * value (visualTheme.ts): a built-in look's, or `brand`, the few treatments
+ * no built-in wears that an App's own theme may (a bar in its colour, a
+ * printed page's rules and small capitals; docs/theming.md). The first value
+ * is the default and has no rules of its own. test/theme-recipes.test.ts
+ * holds the sheets to this: every `data-look-*` value they answer is here, in
+ * its sheet.
+ */
+export declare const RECIPE_MENU: {
+    readonly nav: {
+        readonly tint: null;
+        readonly inverted: null;
+        readonly wash: 'brand';
+        readonly underline: 'brand';
+        readonly pill: 'lumen';
+        readonly quiet: 'sage';
+        readonly slot: 'workshop';
+    };
+    readonly bar: {
+        readonly plain: null;
+        readonly ruled: null;
+        readonly dark: 'brand';
+        readonly airy: 'lumen';
+        readonly soft: 'sage';
+    };
+    readonly tabs: {
+        readonly pill: null;
+        readonly inverted: null;
+        readonly underline: 'lumen';
+        readonly rule: 'brand';
+        readonly chosen: 'sage';
+    };
+    readonly windows: {
+        readonly segmented: null;
+        readonly lifted: 'lumen';
+        readonly chosen: 'sage';
+    };
+    readonly stat: {
+        readonly plain: null;
+        readonly framed: null;
+        readonly topline: 'brand';
+        readonly ruled: 'brand';
+        readonly icon: 'lumen';
+        readonly panel: 'sage';
+        readonly divided: 'lumen';
+    };
+    readonly section: {
+        readonly open: null;
+        readonly card: 'lumen';
+        readonly panel: 'sage';
+    };
+    readonly fields: {
+        readonly open: null;
+        readonly panel: 'sage';
+        readonly card: 'lumen';
+        readonly rail: 'lumen';
+    };
+    readonly table: {
+        readonly open: null;
+        readonly tinted: 'brand';
+        readonly hairline: 'sage';
+        readonly card: 'lumen';
+        readonly quiet: 'lumen';
+        readonly banded: 'brand';
+    };
+    readonly status: {
+        readonly dot: null;
+        readonly pill: 'sage';
+        readonly 'pill-dot': 'lumen';
+        readonly quiet: 'lumen';
+    };
+    readonly board: {
+        readonly ruled: null;
+        readonly soft: 'sage';
+        readonly strip: 'lumen';
+    };
+    readonly chart: {
+        readonly plain: null;
+        readonly wash: 'sage';
+        readonly gradient: 'lumen';
+        readonly line: 'lumen';
+    };
+    readonly buttons: {
+        readonly accent: null;
+        readonly raised: 'lumen';
+        readonly keyed: 'workshop';
+    };
+    readonly links: {
+        readonly plain: null;
+        readonly underline: null;
+    };
+    readonly rules: {
+        readonly ink: null;
+        readonly hairline: null;
+        readonly double: 'ledger';
+    };
+    readonly avatar: {
+        readonly plain: null;
+        readonly large: 'sage';
+        readonly round: 'lumen';
+    };
+    readonly workflow: {
+        readonly markers: null;
+        readonly pills: 'lumen';
+    };
+    readonly banner: {
+        readonly tint: null;
+        readonly gradient: 'lumen';
+        readonly plain: 'lumen';
+    };
+    readonly steps: {
+        readonly flat: null;
+        readonly tinted: 'lumen';
+        readonly strip: 'lumen';
+    };
+    readonly lanes: {
+        readonly tint: null;
+        readonly tag: 'brand';
+        readonly plain: 'brand';
+    };
+    readonly header: {
+        readonly plain: null;
+        readonly band: null;
+        readonly hero: null;
+    };
+    readonly required: {
+        readonly star: null;
+        readonly 'optional-word': null;
+    };
+    readonly checkbox: {
+        readonly native: null;
+        readonly drawn: null;
+    };
+    readonly formStep: {
+        readonly plain: null;
+        readonly ruled: null;
+    };
+    readonly actionBar: {
+        readonly plain: null;
+        readonly raised: null;
+    };
+};
+/** Recipe parts renamed before 1.0, refused with the new name: "head" is a table's column heads (`rules.head`). */
+export declare const RECIPES_RENAMED: Readonly<Record<string, string>>;
+/** Shape rides the same attributes (`data-look-elevation`); type rides its own (`data-type-<role>`, themeType.ts). */
+export declare const ELEVATIONS: {
+    readonly hairline: null;
+    readonly flat: null;
+    readonly soft: 'sage';
+    readonly raised: 'lumen';
+};
+export declare const DENSITIES: readonly ThemeDensity[];
+/** The lifts (`data-look-card`, `data-look-float`): `look` is the elevation's own drawing, then each step, drawn in
+    the theme's shadow colour (themeFamilies.css). */
+export declare const LIFTS: {
+    readonly look: null;
+    readonly none: null;
+    readonly hairline: null;
+    readonly low: null;
+    readonly mid: null;
+    readonly high: null;
+};
+/** The paces (`data-look-motion`): each is the house's five durations, quickened or silenced, in themeFamilies.css. */
+export declare const MOTIONS: {
+    readonly house: null;
+    readonly brisk: null;
+    readonly still: null;
+};
+/** The rhythms (`data-look-rhythm`): the space scale's layout steps, closer or wider, in themeFamilies.css. */
+export declare const RHYTHMS: {
+    readonly house: null;
+    readonly tight: null;
+    readonly airy: null;
+};
+/** A part's root attribute: `data-look-nav`, and for a part of two words `data-look-form-step`, since an attribute
+    name is read in lower case and `formStep` would not be found by `[data-look-formStep]` in every context. */
+export declare const lookAttribute: (part: string) => string;
+export declare const RECIPE_PARTS: (keyof ThemeRecipes)[];
+export type ResolvedRecipes = {
+    [K in keyof ThemeRecipes]-?: NonNullable<ThemeRecipes[K]>;
+};
+/** Every part at its first value: the plain structure a theme that extends nothing starts from. */
+export declare const DEFAULT_RECIPES: ResolvedRecipes;
+/** The attributes a worn theme sets on the root, and the look sheets they need. */
+export declare function recipeAttributes(theme: ThemeDefinition, lookNav?: ThemeTypeRoleDefinition): {
+    attributes: Record<string, string>;
+    sheets: string[];
+};
+export declare const TYPE_ATTRIBUTES: string[];
+/** Each role's `data-type-<role>` attribute: the properties it says, and its capitals. A role that says nothing has
+    none, so no rule of its turns on. A title's weight is `--heading-weight`, which every heading reads, so it is no
+    word here. */
+export declare function typeAttributes(type: ThemeTypeDefinition | undefined): Record<string, string>;
+/**
+ * The published parts a theme may dress one by one (themeParts.ts says what each may take and how it is worn). Here,
+ * with the words the root wears for them, because the first paint sets `data-parts` as it sets the recipes'.
+ */
+export declare const THEME_PARTS: readonly ["ground", "bar", "bar.search", "nav", "nav.item", "nav.current", "nav.group", "logo", "page.title", "tabs", "tab.current", "section", "section.title", "stat", "stat.figure", "fields", "field.label", "table", "table.head", "table.row", "status", "tag", "button.primary", "button.secondary", "button.quiet", "link", "board.lane", "board.card", "workflow.step", "banner", "steps.step", "avatar", "menu", "dialog", "chart"];
+/** What a part style may say, in the order its words are written. */
+export declare const PART_PROPERTIES: readonly ['ground', 'ink', 'edge', 'radius', 'lift', 'face', 'weight', 'case'];
+/** The root's `data-parts`: one word per property a part says (`stat:ground button.primary:case`); undefined when none. */
+export declare function partAttribute(parts: Partial<Record<ThemePart, ThemePartStyle>> | undefined): string | undefined;

package/dist/shared/themeRecipes.js

@@ -0,0 +1,234 @@
+/**
+ * Every part a theme may dress and the treatments it may pick, and the sheet
+ * its rules live in: `null` is the first stylesheet (themeFamilies.css,
+ * kit.css), a name is a sheet of its own, fetched when a worn theme picks the
+ * value (visualTheme.ts): a built-in look's, or `brand`, the few treatments
+ * no built-in wears that an App's own theme may (a bar in its colour, a
+ * printed page's rules and small capitals; docs/theming.md). The first value
+ * is the default and has no rules of its own. test/theme-recipes.test.ts
+ * holds the sheets to this: every `data-look-*` value they answer is here, in
+ * its sheet.
+ */
+export const RECIPE_MENU = {
+    nav: { tint: null, inverted: null, wash: 'brand', underline: 'brand', pill: 'lumen', quiet: 'sage', slot: 'workshop' },
+    bar: { plain: null, ruled: null, dark: 'brand', airy: 'lumen', soft: 'sage' },
+    tabs: { pill: null, inverted: null, underline: 'lumen', rule: 'brand', chosen: 'sage' },
+    windows: { segmented: null, lifted: 'lumen', chosen: 'sage' },
+    stat: { plain: null, framed: null, topline: 'brand', ruled: 'brand', icon: 'lumen', panel: 'sage', divided: 'lumen' },
+    section: { open: null, card: 'lumen', panel: 'sage' },
+    fields: { open: null, panel: 'sage', card: 'lumen', rail: 'lumen' },
+    table: { open: null, tinted: 'brand', hairline: 'sage', card: 'lumen', quiet: 'lumen', banded: 'brand' },
+    status: { dot: null, pill: 'sage', 'pill-dot': 'lumen', quiet: 'lumen' },
+    board: { ruled: null, soft: 'sage', strip: 'lumen' },
+    chart: { plain: null, wash: 'sage', gradient: 'lumen', line: 'lumen' },
+    buttons: { accent: null, raised: 'lumen', keyed: 'workshop' },
+    links: { plain: null, underline: null },
+    rules: { ink: null, hairline: null, double: 'ledger' },
+    avatar: { plain: null, large: 'sage', round: 'lumen' },
+    workflow: { markers: null, pills: 'lumen' },
+    banner: { tint: null, gradient: 'lumen', plain: 'lumen' },
+    steps: { flat: null, tinted: 'lumen', strip: 'lumen' },
+    lanes: { tint: null, tag: 'brand', plain: 'brand' },
+    header: { plain: null, band: null, hero: null },
+    /* The four below are a form's: their rules are in @mistriwork/ui's forms.css, which arrives with the first control
+       a page draws, so no first stylesheet carries them and the menu names no sheet of a look. */
+    required: { star: null, 'optional-word': null },
+    checkbox: { native: null, drawn: null },
+    formStep: { plain: null, ruled: null },
+    actionBar: { plain: null, raised: null },
+};
+/** Recipe parts renamed before 1.0, refused with the new name: "head" is a table's column heads (`rules.head`). */
+export const RECIPES_RENAMED = { head: 'header' };
+/** Shape rides the same attributes (`data-look-elevation`); type rides its own (`data-type-<role>`, themeType.ts). */
+export const ELEVATIONS = { hairline: null, flat: null, soft: 'sage', raised: 'lumen' };
+export const DENSITIES = ['compact', 'comfortable', 'spacious'];
+/** The lifts (`data-look-card`, `data-look-float`): `look` is the elevation's own drawing, then each step, drawn in
+    the theme's shadow colour (themeFamilies.css). */
+export const LIFTS = { look: null, none: null, hairline: null, low: null, mid: null, high: null };
+/** The paces (`data-look-motion`): each is the house's five durations, quickened or silenced, in themeFamilies.css. */
+export const MOTIONS = { house: null, brisk: null, still: null };
+/** The rhythms (`data-look-rhythm`): the space scale's layout steps, closer or wider, in themeFamilies.css. */
+export const RHYTHMS = { house: null, tight: null, airy: null };
+/** A part's root attribute: `data-look-nav`, and for a part of two words `data-look-form-step`, since an attribute
+    name is read in lower case and `formStep` would not be found by `[data-look-formStep]` in every context. */
+export const lookAttribute = (part) => `data-look-${part.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+export const RECIPE_PARTS = Object.keys(RECIPE_MENU);
+/** Every part at its first value: the plain structure a theme that extends nothing starts from. */
+export const DEFAULT_RECIPES = Object.fromEntries(RECIPE_PARTS.map((part) => [part, Object.keys(RECIPE_MENU[part])[0]]));
+/** The attributes a worn theme sets on the root, and the look sheets they need. */
+export function recipeAttributes(theme, lookNav) {
+    const recipes = { ...DEFAULT_RECIPES, ...theme.recipes };
+    const attributes = {};
+    const sheets = new Set();
+    for (const part of RECIPE_PARTS) {
+        const value = recipes[part];
+        attributes[lookAttribute(part)] = value;
+        const sheet = RECIPE_MENU[part][value];
+        if (sheet)
+            sheets.add(sheet);
+    }
+    const elevation = theme.elevation ?? 'hairline';
+    attributes['data-look-elevation'] = elevation;
+    attributes['data-look-motion'] = theme.motion ?? 'house';
+    attributes['data-look-rhythm'] = theme.rhythm ?? 'house';
+    /* A shadow colour of the theme's own under the platform's hairline draws the platform's popups in it: its low step,
+       the house geometry mixed from the theme's shadow rather than the house's black. */
+    const ownShadow = Boolean(theme.light.shadow || theme.dark.shadow) && elevation === 'hairline';
+    attributes['data-look-card'] = theme.lifts?.card ?? 'look';
+    attributes['data-look-float'] = theme.lifts?.float ?? (ownShadow ? 'low' : 'look');
+    const lifted = ELEVATIONS[elevation];
+    if (lifted)
+        sheets.add(lifted);
+    Object.assign(attributes, typeAttributes(theme.type));
+    const side = sideNavWords(theme.type, lookNav);
+    if (side.length)
+        attributes['data-type-nav-side'] = side.join(' ');
+    const bar = barGround(theme, recipes.bar);
+    if (bar)
+        attributes['data-bar-ground'] = bar;
+    /* What a theme says beyond the menu (themeParts.ts): each an attribute only where it is said, and its sheet. */
+    const parts = partAttribute(theme.parts);
+    if (parts) {
+        attributes['data-parts'] = parts;
+        sheets.add('parts');
+    }
+    for (const place of ['ground', 'nav']) {
+        const pattern = theme.surface?.[place];
+        if (!pattern)
+            continue;
+        attributes[`data-surface-${place}`] = `${pattern.kind} ${pattern.strength ?? 1}`;
+        sheets.add('surfaces');
+    }
+    if (theme.icons && theme.icons !== 'regular')
+        attributes['data-icons'] = theme.icons;
+    return { attributes, sheets: [...sheets] };
+}
+/** Whether a color is dark: nearer black than white for text drawn on it (WCAG's luminance, its even point). */
+function dark(hex) {
+    if (!hex || !/^#[0-9a-f]{6}$/i.test(hex))
+        return undefined;
+    const [r, g, b] = [1, 3, 5].map((start) => {
+        const value = parseInt(hex.slice(start, start + 2), 16) / 255;
+        return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.179;
+}
+/**
+ * The bar's ground against the reader's mode, where they disagree: `light:dark` a dark bar by day, `dark:light` a
+ * light one by night. The logo is drawn on the bar, so its picture is chosen by the bar's ground (appBrand.css): a
+ * light-mode App with an inverted bar wears the night picture there. Undefined where each mode's bar is its mode's.
+ */
+function barGround(theme, bar) {
+    /* A soft bar is drawn on the page's surface (sageLook.css); every other on the navigation's ground. */
+    const ground = (mode) => dark(bar === 'soft' ? theme[mode].surface : (theme[mode].navGround ?? theme[mode].surface));
+    const words = [...(ground('light') ? ['light:dark'] : []), ...(ground('dark') === false ? ['dark:light'] : [])];
+    return words.length ? words.join(' ') : undefined;
+}
+/** The type roles in their attribute order (themeType.ts holds what each takes; test/theme-type.test.ts holds the two
+    lists to one). */
+const TYPE_ROLE_ORDER = ['display', 'title', 'heading', 'section', 'body', 'label', 'data', 'figure', 'nav'];
+/** The features `font-variant-numeric` says, worn as a role's `numeric`; the rest are its `features`. */
+const NUMERIC_FEATURES = new Set(['lnum', 'onum', 'tnum', 'zero']);
+export const TYPE_ATTRIBUTES = [...TYPE_ROLE_ORDER.map((name) => `data-type-${name}`), 'data-type-nav-side'];
+/** Each role's `data-type-<role>` attribute: the properties it says, and its capitals. A role that says nothing has
+    none, so no rule of its turns on. A title's weight is `--heading-weight`, which every heading reads, so it is no
+    word here. */
+export function typeAttributes(type) {
+    const out = {};
+    for (const name of TYPE_ROLE_ORDER) {
+        const words = roleWords(name, type?.roles?.[name]);
+        if (words.length)
+            out[`data-type-${name}`] = words.join(' ');
+    }
+    return out;
+}
+function roleWords(name, role) {
+    const words = [];
+    if (!role)
+        return words;
+    for (const property of ['face', 'size', 'leading', 'tracking', 'weight'])
+        if (role[property] !== undefined && !(property === 'weight' && name === 'title'))
+            words.push(property);
+    if (role.features?.some((feature) => NUMERIC_FEATURES.has(feature)))
+        words.push('numeric');
+    if (role.features?.some((feature) => !NUMERIC_FEATURES.has(feature)))
+        words.push('features');
+    if (role.case && role.case !== 'none')
+        words.push(role.case);
+    if (role.reach === 'figures')
+        words.push('figures');
+    return words;
+}
+/**
+ * What the theme itself says of the nav role, beyond what its base look already says: `data-type-nav-side`, which
+ * dresses the side menu's entries. The compiled theme carries the look's roles merged under its own, and a look that
+ * sets nav (Mono's mono capitals) dresses the bar's entries only, as it always did; the side menu keeps the look's
+ * face until a theme sets the role itself. Compared per property, so a theme that only changes the weight does not
+ * bring the look's capitals down the side.
+ */
+function sideNavWords(type, lookNav) {
+    const role = type?.roles?.nav;
+    if (!role)
+        return [];
+    const own = {};
+    for (const [key, value] of Object.entries(role))
+        if (JSON.stringify(value) !== JSON.stringify(lookNav?.[key]))
+            own[key] = value;
+    return roleWords('nav', own);
+}
+/**
+ * The published parts a theme may dress one by one (themeParts.ts says what each may take and how it is worn). Here,
+ * with the words the root wears for them, because the first paint sets `data-parts` as it sets the recipes'.
+ */
+export const THEME_PARTS = [
+    'ground',
+    'bar',
+    'bar.search',
+    'nav',
+    'nav.item',
+    'nav.current',
+    'nav.group',
+    'logo',
+    'page.title',
+    'tabs',
+    'tab.current',
+    'section',
+    'section.title',
+    'stat',
+    'stat.figure',
+    'fields',
+    'field.label',
+    'table',
+    'table.head',
+    'table.row',
+    'status',
+    'tag',
+    'button.primary',
+    'button.secondary',
+    'button.quiet',
+    'link',
+    'board.lane',
+    'board.card',
+    'workflow.step',
+    'banner',
+    'steps.step',
+    'avatar',
+    'menu',
+    'dialog',
+    'chart',
+];
+/** What a part style may say, in the order its words are written. */
+export const PART_PROPERTIES = ['ground', 'ink', 'edge', 'radius', 'lift', 'face', 'weight', 'case'];
+/** The root's `data-parts`: one word per property a part says (`stat:ground button.primary:case`); undefined when none. */
+export function partAttribute(parts) {
+    const words = [];
+    for (const part of THEME_PARTS) {
+        const style = parts?.[part];
+        if (!style)
+            continue;
+        for (const property of PART_PROPERTIES)
+            if (style[property] !== undefined)
+                words.push(`${part}:${property}`);
+    }
+    return words.length ? words.join(' ') : undefined;
+}

package/dist/shared/themeResolve.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Which theme a page wears: one function, read by the server where it
+ * projects an App for a principal (appViewRoles.ts) and guesses a first
+ * paint's sheets (clientSurface.ts), and by the browser where it applies the
+ * look (client visualTheme.ts), so the two never disagree about a page.
+ *
+ * The order (docs/theming.md, Precedence):
+ *
+ * 1. A public surface — a landing, the sign-in screen, a public form, or any
+ *    page a signed-out visitor sees — wears `ui.theme.for.public` where the
+ *    App names one, whatever a reader picked once: public pages are a
+ *    storefront, the same for everyone, and so can be cached.
+ * 2. Otherwise the reader's own pick, where the App offers a picker.
+ * 3. Otherwise the first `for.roles` entry, in the order it is written, that
+ *    the account holds: a portal's look is the App's design.
+ * 4. Otherwise the tenant's saved theme: its staff's default.
+ * 5. Otherwise the App's `ui.theme.preset`, and Workshop where it names none.
+ *
+ * Each id is taken only where the App offers it (a built-in look or one of
+ * its own), so a theme removed since a pick was saved falls through to the
+ * next rank instead of to nothing.
+ */
+/** `ui.theme.for`: a theme for signed-out visitors, and one per role. */
+export interface ThemeAudiences {
+    public?: string;
+    roles?: Readonly<Record<string, string>>;
+}
+/** Where a page's theme came from. */
+type ThemeSource = 'public' | 'reader' | 'role' | 'tenant' | 'app' | 'default';
+export interface ThemeAsk {
+    /** A public surface, or a visitor who is not signed in. */
+    public?: boolean;
+    /** The account's roles; none when signed out. */
+    roles?: readonly string[];
+    /** The reader's own pick. */
+    pick?: string;
+    for?: ThemeAudiences;
+    /** The tenant's saved theme (tenant branding's `theme`). */
+    tenant?: string;
+    /** `ui.theme.preset`. */
+    preset?: string;
+    /** Whether the App offers a theme by this id: a built-in look, or one of `ui.customThemes`. */
+    offered: (id: string) => boolean;
+}
+/** The theme a page wears, where it came from and, for a role's, which role. */
+export declare function resolveTheme(ask: ThemeAsk): {
+    id: string;
+    source: ThemeSource;
+    role?: string;
+};
+/** The role theme a principal holding `roles` wears, if `for.roles` maps one it holds: the first in written order. */
+export declare function roleTheme(audiences: ThemeAudiences | undefined, roles: readonly string[]): string | undefined;
+/** Every theme a mapping can dress a page in: the public one, then each role's, once each. */
+export declare function audienceThemes(audiences: ThemeAudiences | undefined): string[];
+export {};