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

package/dist/shared/themeColor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The colour arithmetic a theme is measured with: a bounded evaluator of the colours a palette is written in, mixing
+ * and compositing as the page does, and WCAG contrast. Apart from theme.ts, which judges whole themes, because the
+ * client draws with one result of it (heatTop, a matrix's strongest tint) on every first paint, and theme.ts with its
+ * recipes, faces and checks is several kilobytes no first paint should carry.
+ */
+import type { ThemePalette } from '../../schema/theme.js';
+export type Color = readonly [number, number, number, number];
+/** A deliberately bounded color evaluator, not a CSS parser. Fractional sRGB
+    channels stay unrounded through compositing and luminance calculation. */
+export declare function diagnosticColor(value: string, depth?: number): Color | undefined;
+export declare function mixColor(a: Color, b: Color, weight: number): Color;
+export declare function over(color: Color, ground: Color): Color;
+export declare function measuredContrast(foreground: Color, background: Color): number | undefined;
+/** A composited colour as the page paints it, `#rrggbb` (alpha dropped: a ground is opaque, an ink composited on one). */
+export declare function colorHex(color: Color): string;
+/** The strongest a heat tint is drawn (a matrix's heaviest cell), as a share of the accent over the panel. */
+export declare const HEAT_TOP = 0.62;
+/**
+ * How strong a heat tint may be drawn under a palette: the strongest share of the accent over the panel, at most
+ * HEAT_TOP, on which the ink still reads at 4.5:1. A matrix's cells say their figure (and, folded, their column) in
+ * the ink on that tint, so the scale stops where the words would fade: 62% under Lumen's blue, about half under
+ * Mono's black or a dark mode's light accent, where the ink sits near the accent. Unmeasurable colors keep HEAT_TOP.
+ */
+export declare function heatTop(palette: Pick<ThemePalette, 'accent' | 'surface' | 'ink'>): number;
+/**
+ * A command form's field edge at rest (formDress.css, `--field-edge`): a clean outline at 3:1 on what the field
+ * stands on (WCAG 1.4.11). Where the look's control edge (`lineControl`) already reads at up to 4.5:1 on its surface
+ * and its page, it is that edge, so a form's field and a record's inline edit wear one line (Lumen, Sage). A stronger
+ * one — Mono's ink, a theme's near-black — is mixed toward the surface to the lightest that still clears FIELD_EDGE on
+ * both: a box of solid ink round every answer read as a form shouting. Undefined keeps the look's own edge (the sheet
+ * falls back to `--line-control`), and so does a color this cannot measure.
+ */
+export declare function fieldEdge(palette: Pick<ThemePalette, 'lineControl' | 'surface' | 'ground'>): string | undefined;

package/dist/shared/themeColor.js

@@ -0,0 +1,109 @@
+/** A deliberately bounded color evaluator, not a CSS parser. Fractional sRGB
+    channels stay unrounded through compositing and luminance calculation. */
+export function diagnosticColor(value, depth = 0) {
+    if (depth > 8)
+        return undefined;
+    value = value.trim().toLowerCase();
+    if (value === 'transparent')
+        return [0, 0, 0, 0];
+    if (value === 'white')
+        return [1, 1, 1, 1];
+    if (value === 'black')
+        return [0, 0, 0, 1];
+    if (/^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(value)) {
+        const hex = value.length < 6
+            ? value
+                .slice(1)
+                .split('')
+                .map((char) => char + char)
+                .join('')
+            : value.slice(1);
+        return [
+            parseInt(hex.slice(0, 2), 16) / 255,
+            parseInt(hex.slice(2, 4), 16) / 255,
+            parseInt(hex.slice(4, 6), 16) / 255,
+            hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1,
+        ];
+    }
+    // The two expressions emitted by effectiveThemePalette. The inner legacy
+    // color can be unknown; that remains unmeasured rather than guessed.
+    const mix = /^color-mix\(in srgb, (.+) (62|14)%, (white|transparent)\)$/.exec(value);
+    const color = mix && diagnosticColor(mix[1], depth + 1);
+    return color ? mixColor(color, diagnosticColor(mix[3]), Number(mix[2]) / 100) : undefined;
+}
+export function mixColor(a, b, weight) {
+    const alpha = a[3] * weight + b[3] * (1 - weight);
+    const channel = (index) => (alpha ? (a[index] * a[3] * weight + b[index] * b[3] * (1 - weight)) / alpha : 0);
+    return [channel(0), channel(1), channel(2), alpha];
+}
+export function over(color, ground) {
+    const alpha = color[3] + ground[3] * (1 - color[3]);
+    const channel = (index) => (alpha ? (color[index] * color[3] + ground[index] * ground[3] * (1 - color[3])) / alpha : 0);
+    return [channel(0), channel(1), channel(2), alpha];
+}
+export function measuredContrast(foreground, background) {
+    if (background[3] !== 1)
+        return undefined; // No known opaque ground.
+    const luminance = (color) => color
+        .slice(0, 3)
+        .map((value) => (value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4))
+        .reduce((total, value, index) => total + value * [0.2126, 0.7152, 0.0722][index], 0);
+    const a = luminance(over(foreground, background)), b = luminance(background);
+    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+/** A composited colour as the page paints it, `#rrggbb` (alpha dropped: a ground is opaque, an ink composited on one). */
+export function colorHex(color) {
+    return `#${color
+        .slice(0, 3)
+        .map((value) => Math.round(Math.min(1, Math.max(0, value)) * 255)
+        .toString(16)
+        .padStart(2, '0'))
+        .join('')}`;
+}
+/** The strongest a heat tint is drawn (a matrix's heaviest cell), as a share of the accent over the panel. */
+export const HEAT_TOP = 0.62;
+/** Below this a heat scale stops reading as one: the palette's heaviest cell is drawn here and `check` says why. */
+const HEAT_FLOOR = 0.2;
+/**
+ * How strong a heat tint may be drawn under a palette: the strongest share of the accent over the panel, at most
+ * HEAT_TOP, on which the ink still reads at 4.5:1. A matrix's cells say their figure (and, folded, their column) in
+ * the ink on that tint, so the scale stops where the words would fade: 62% under Lumen's blue, about half under
+ * Mono's black or a dark mode's light accent, where the ink sits near the accent. Unmeasurable colors keep HEAT_TOP.
+ */
+export function heatTop(palette) {
+    const accent = palette.accent && diagnosticColor(palette.accent), surface = palette.surface && diagnosticColor(palette.surface), ink = palette.ink && diagnosticColor(palette.ink);
+    if (!accent || !surface || !ink)
+        return HEAT_TOP;
+    for (let step = Math.round(HEAT_TOP * 100); step > HEAT_FLOOR * 100; step--) {
+        const ratio = measuredContrast(ink, over(mixColor(accent, [0, 0, 0, 0], step / 100), surface));
+        if (ratio === undefined || ratio >= 4.5)
+            return step / 100;
+    }
+    return HEAT_FLOOR;
+}
+/** What a command form's field edge at rest is drawn to: 3:1 with room to spare, short of a line that shouts. */
+const FIELD_EDGE = 3.5;
+/** Past this a control's edge is a line drawn to be seen (Mono's ink), not a field's quiet boundary. */
+const FIELD_EDGE_CEILING = 4.5;
+/**
+ * A command form's field edge at rest (formDress.css, `--field-edge`): a clean outline at 3:1 on what the field
+ * stands on (WCAG 1.4.11). Where the look's control edge (`lineControl`) already reads at up to 4.5:1 on its surface
+ * and its page, it is that edge, so a form's field and a record's inline edit wear one line (Lumen, Sage). A stronger
+ * one — Mono's ink, a theme's near-black — is mixed toward the surface to the lightest that still clears FIELD_EDGE on
+ * both: a box of solid ink round every answer read as a form shouting. Undefined keeps the look's own edge (the sheet
+ * falls back to `--line-control`), and so does a color this cannot measure.
+ */
+export function fieldEdge(palette) {
+    const edge = palette.lineControl && diagnosticColor(palette.lineControl), surface = palette.surface && diagnosticColor(palette.surface), ground = palette.ground ? diagnosticColor(palette.ground) : surface;
+    if (!edge || !surface || !ground)
+        return undefined;
+    const least = (color) => Math.min(measuredContrast(color, surface) ?? 0, measuredContrast(color, ground) ?? 0);
+    if (least(edge) <= FIELD_EDGE_CEILING)
+        return undefined;
+    for (let step = 1; step < 100; step++) {
+        const mixed = mixColor(edge, surface, step / 100);
+        if (least(mixed) >= FIELD_EDGE)
+            return colorHex(mixed);
+    }
+    return undefined;
+}

package/dist/shared/themeFaces.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A theme's own font files (`type.faces`) as a page declares them: the
+ * `@font-face` rules, the face its headings are drawn in, and the families a
+ * stack names. Shared by the server's first paint (clientSurface.ts) and the
+ * browser's look (client visualTheme.ts), so a face is declared the same way
+ * before the script runs and after; the files themselves are the server's
+ * (server/app/appFonts.ts).
+ */
+import type { ThemeDefinition, ThemeFaceDefinition } from '../../schema/theme.js';
+/** The path segment an App's fonts are served under, beside its `_components`. */
+export declare const FONTS_SEGMENT = "_fonts";
+/** A stack's families, unquoted. */
+export declare function families(stack: string): string[];
+/**
+ * The face a theme's headings are drawn in, preloaded on first paint: the
+ * first served face of the family its heading stack leads with, at the
+ * heading weight where it ships one. A theme whose headings lead with a
+ * family it does not ship has none: nothing is fetched for a face the page
+ * would not draw a line in.
+ */
+export declare function headingFace(theme: ThemeDefinition): ThemeFaceDefinition | undefined;
+/**
+ * The `@font-face` rules for a theme's served faces, each `url()` the
+ * browser's own form of its address (`shown`). `swap`, as Inter's is
+ * (lumenLook.css): the text is drawn at once in the stack's next family and
+ * set again when the face lands, never held invisible. The family and the
+ * address are both checked to a character set that cannot close the rule
+ * (themeSpec.ts, appFonts.ts), so nothing a theme says becomes a stylesheet.
+ */
+export declare function faceRules(theme: ThemeDefinition | undefined, shown?: (href: string) => string): string;

package/dist/shared/themeFaces.js

@@ -0,0 +1,42 @@
+/** The path segment an App's fonts are served under, beside its `_components`. */
+export const FONTS_SEGMENT = '_fonts';
+/** A stack's families, unquoted. */
+export function families(stack) {
+    return stack
+        .split(',')
+        .map((family) => family.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean);
+}
+/**
+ * The face a theme's headings are drawn in, preloaded on first paint: the
+ * first served face of the family its heading stack leads with, at the
+ * heading weight where it ships one. A theme whose headings lead with a
+ * family it does not ship has none: nothing is fetched for a face the page
+ * would not draw a line in.
+ */
+export function headingFace(theme) {
+    const lead = families(theme.fonts?.heading ?? theme.fonts?.ui ?? '')[0]?.toLowerCase();
+    if (!lead)
+        return undefined;
+    const faces = (theme.faces ?? []).filter((face) => face.family.toLowerCase() === lead && face.style === 'normal' && face.href);
+    const weight = theme.type?.roles?.title?.weight ?? 700;
+    return (faces.find((face) => {
+        const [low, high = low] = face.weight.split(' ').map(Number);
+        return weight >= low && weight <= high;
+    }) ?? faces[0]);
+}
+/**
+ * The `@font-face` rules for a theme's served faces, each `url()` the
+ * browser's own form of its address (`shown`). `swap`, as Inter's is
+ * (lumenLook.css): the text is drawn at once in the stack's next family and
+ * set again when the face lands, never held invisible. The family and the
+ * address are both checked to a character set that cannot close the rule
+ * (themeSpec.ts, appFonts.ts), so nothing a theme says becomes a stylesheet.
+ */
+export function faceRules(theme, shown = (href) => href) {
+    return (theme?.faces ?? [])
+        .filter((face) => face.href && /^[\w/.%-]+$/.test(face.href))
+        .map((face) => `@font-face{font-family:"${face.family}";src:url("${shown(face.href)}") format("${face.href.endsWith('.woff') ? 'woff' : 'woff2'}");` +
+        `font-weight:${face.weight};font-style:${face.style};font-display:swap}`)
+        .join('\n');
+}

package/dist/shared/themeInk.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The two inks an accent needs that are not the accent. A brand accent is
+ * chosen as a fill (a button, a tab, a meter), and the words drawn on it and
+ * the words drawn in it are two other colors: a bright orange wants near-black
+ * words on it, and is 2.3:1 as text on a white page. A theme may say them
+ * (`onAccent`, `accentInk`); where it says nothing and the accent as it stands
+ * would fail, the one that passes is taken, so most themes never name either.
+ * Both are answered only when they differ from what the sheets already do
+ * (the page's color on the accent, the accent itself as text): an accent that
+ * passes keeps every theme's tokens exactly as they were.
+ */
+import type { ThemePalette } from '../../schema/theme.js';
+type Colors = Pick<ThemePalette, 'accent' | 'ink' | 'surface'> & Partial<ThemePalette>;
+/** The words on an accent fill when the page's color would not read on it: the ink if that does, else the better of white and black. Undefined where the default reads, or where a color is no hex to measure. */
+export declare function deriveOnAccent(palette: Colors): string | undefined;
+/** The accent as text and links when it would not read on the grounds a word stands on: the accent drawn toward the ink until it does, so the hue stays the brand's. Undefined where it reads already.
+    `soft`: the accent's own 14% tint is a ground too (a selected item, where an App's accent draws accentSoft as that
+    tint): on a ground darker than white, Workshop's paper, a blue that reads on the page fell to 4.4:1 on its tint. */
+export declare function deriveAccentInk(palette: Colors, soft?: boolean): string | undefined;
+export {};

package/dist/shared/themeInk.js

@@ -0,0 +1,52 @@
+const HEX = /^#[0-9a-f]{6}$/i;
+/** Text needs this much against what it is drawn on (WCAG 1.4.3). */
+const TEXT = 4.5;
+function luminance(hex) {
+    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 r * 0.2126 + g * 0.7152 + b * 0.0722;
+}
+function contrast(a, b) {
+    const x = luminance(a), y = luminance(b);
+    return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+}
+function mix(a, b, weight) {
+    return `#${[1, 3, 5]
+        .map((start) => Math.round(parseInt(a.slice(start, start + 2), 16) * weight + parseInt(b.slice(start, start + 2), 16) * (1 - weight))
+        .toString(16)
+        .padStart(2, '0'))
+        .join('')}`;
+}
+/** The words on an accent fill when the page's color would not read on it: the ink if that does, else the better of white and black. Undefined where the default reads, or where a color is no hex to measure. */
+export function deriveOnAccent(palette) {
+    const fill = palette.accent;
+    const given = palette.ground ?? palette.surface;
+    if (!HEX.test(fill) || !HEX.test(given) || contrast(given, fill) >= TEXT)
+        return undefined;
+    if (HEX.test(palette.ink) && contrast(palette.ink, fill) >= TEXT)
+        return palette.ink.toLowerCase();
+    return contrast('#ffffff', fill) >= contrast('#000000', fill) ? '#ffffff' : '#000000';
+}
+/** The accent as text and links when it would not read on the grounds a word stands on: the accent drawn toward the ink until it does, so the hue stays the brand's. Undefined where it reads already.
+    `soft`: the accent's own 14% tint is a ground too (a selected item, where an App's accent draws accentSoft as that
+    tint): on a ground darker than white, Workshop's paper, a blue that reads on the page fell to 4.4:1 on its tint. */
+export function deriveAccentInk(palette, soft = false) {
+    const accent = palette.accent;
+    if (!HEX.test(accent) || !HEX.test(palette.ink))
+        return undefined;
+    const pages = [palette.surface, palette.ground, palette.raised].filter((color) => Boolean(color && HEX.test(color)));
+    if (!pages.length)
+        return undefined;
+    const grounds = soft ? [...pages, ...pages.map((page) => mix(accent, page, 0.14))] : pages;
+    const reads = (color) => grounds.every((ground) => contrast(color, ground) >= TEXT);
+    if (reads(accent))
+        return undefined;
+    for (let step = 1; step <= 20; step++) {
+        const color = mix(palette.ink, accent, step / 20);
+        if (reads(color))
+            return color;
+    }
+    return palette.ink.toLowerCase();
+}

package/dist/shared/themeLooks.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The built-in looks as authored specs: each look's palettes, faces, shape,
+ * density and recipe picks, written by purpose as an App's own theme is.
+ * themePresets.ts compiles them into the presets the server and the browser
+ * both wear; the builder and the checks are elsewhere, so they stay out of a
+ * first paint that needs only the looks.
+ */
+import type { ThemeSpec } from '../../schema/theme.js';
+export declare const LOOKS: readonly ThemeSpec[];