@unmap/themes 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+import { Flavor } from '@protomaps/basemaps';
+
+/**
+ * Named colour ramps: the single source of colour truth for unmap cartography.
+ *
+ * Moved here from apps/gateway/src/palette.ts (which now re-exports these) so themes, the
+ * gateway, and the builder all draw from one vocabulary. Flavors and theme recipes reference
+ * these by name and never inline a hex literal.
+ *
+ * Ramps run light to dark by ascending key.
+ */
+/**
+ * Ember. Pre-rebrand brand accent; survives only as the `street` motorway orange, which is
+ * cartographic convention (orange motorways) rather than brand. Never the interface accent —
+ * that is magenta, which stays out of every basemap.
+ */
+declare const ember: {
+    readonly 200: "#ffe9c9";
+    readonly 300: "#ffc08c";
+    readonly 400: "#f7a35c";
+    readonly 500: "#f97316";
+    readonly 600: "#e07b2e";
+    readonly 700: "#b45309";
+};
+/** Cool neutrals, hue 212. The spine of every Process Ink flavour. */
+declare const ink: {
+    readonly 25: "#F1F8FA";
+    readonly 50: "#EAF2F3";
+    readonly 100: "#E2E9EB";
+    readonly 200: "#D6DEE0";
+    readonly 300: "#C9D1D3";
+    readonly 400: "#B7C0C2";
+    readonly 500: "#9DA7A9";
+    readonly 600: "#7E888B";
+    readonly 700: "#5C6769";
+    readonly 800: "#3D494B";
+    readonly 850: "#2B3639";
+    readonly 900: "#1A2628";
+    readonly 950: "#0E191C";
+    readonly 1000: "#030E10";
+};
+/** Water, hue 200. Cooler and more chromatic than the land it meets. */
+declare const wave: {
+    readonly 100: "#C7F1F3";
+    readonly 200: "#B3E2E4";
+    readonly 300: "#9CCFD2";
+    readonly 400: "#7FB8BB";
+    readonly 500: "#5F9FA2";
+    readonly 600: "#368286";
+    readonly 700: "#1C6265";
+    readonly 800: "#024347";
+    readonly 900: "#002A2C";
+    readonly 950: "#001C1E";
+    readonly 980: "#001012";
+};
+/** Vegetation, hue 152: park, wood, scrub. */
+declare const verdant: {
+    readonly 100: "#D3F1DA";
+    readonly 200: "#C3E3CA";
+    readonly 300: "#AFD2B7";
+    readonly 400: "#96BC9F";
+    readonly 500: "#76A281";
+    readonly 600: "#50825E";
+    readonly 700: "#366042";
+    readonly 800: "#1E4128";
+    readonly 900: "#0B2815";
+};
+/** Warm landcover, hue 82: sand, beach, farmland. */
+declare const sandstone: {
+    readonly 100: "#F5E8D0";
+    readonly 200: "#E7D9BF";
+    readonly 300: "#D6C7AC";
+    readonly 400: "#BFAF92";
+    readonly 500: "#A19070";
+};
+/**
+ * Pure neutrals, zero chroma. The `muted` pair only.
+ *
+ * `ink` carries a hue-212 cool cast, which is right for every other flavour and wrong for this
+ * one: `muted` exists to vanish under a customer's data, and a basemap with *any* hue biases the
+ * colours laid on top of it. So muted gets its own ramp where R=G=B exactly.
+ *
+ * Calibrated against Mapbox Light and Protomaps' `WHITE`, whose land/water/building relationships
+ * this flavour follows: land a light grey, roads *brighter* than the land rather than darker,
+ * buildings a single step down, and water the only tone with any real weight.
+ *
+ * Their label colours are deliberately NOT copied. Protomaps `WHITE` puts `state_label` #b3b3b3
+ * on #ffffff, roughly 2:1, which fails the 4.5:1 floor `cartography.test.ts` enforces. The
+ * structure is worth borrowing; the label contrast is not.
+ */
+declare const graphite: {
+    readonly 25: "#FAFAFA";
+    readonly 50: "#F2F2F2";
+    readonly 100: "#E9E9E9";
+    readonly 200: "#DEDEDE";
+    readonly 300: "#D1D1D1";
+    readonly 400: "#BEBEBE";
+    readonly 500: "#A4A4A4";
+    readonly 600: "#868686";
+    readonly 700: "#656565";
+    readonly 800: "#464646";
+    readonly 900: "#232323";
+    readonly 1000: "#0B0B0B";
+};
+
+/**
+ * The unmap cartography authoring surface, moved here from apps/gateway/src/flavors.ts so the
+ * gateway, the theme system, and the unmap.dev builder share one definition.
+ *
+ * A `Recipe` is what a theme can override: every colour a Flavor controls, expressed at the
+ * level we author at. Expanding through `makeFlavor` keeps the consistency guarantees a raw
+ * Flavor cannot: a casing is always derived beside its fill, and the tunnel and bridge families
+ * cannot drift out of step with the surface roads they mirror.
+ */
+/**
+ * Appended, never inserted. This array's order drives the style picker in the unmap.dev builder,
+ * so inserting a base mid-array silently reorders a control people have already learned.
+ */
+declare const THEME_BASES: readonly ["base", "muted", "relief", "street", "outdoor"];
+type ThemeBase = (typeof THEME_BASES)[number];
+declare const MODES: readonly ["light", "dark"];
+type ThemeMode = (typeof MODES)[number];
+interface RoadRamp {
+    /** Unclassified / track. The bottom of the hierarchy. */
+    other: string;
+    otherCasing: string;
+    /** Residential and service. */
+    minor: string;
+    minorCasing: string;
+    service: string;
+    serviceCasing: string;
+    /** Primary / secondary. */
+    major: string;
+    majorCasing: string;
+    /** Motorway. */
+    highway: string;
+    highwayCasing: string;
+    /** Slip roads. */
+    link: string;
+    linkCasing: string;
+}
+interface LabelRamp {
+    city: string;
+    cityHalo: string;
+    state: string;
+    stateHalo: string;
+    country: string;
+    subplace: string;
+    subplaceHalo: string;
+    address: string;
+    addressHalo: string;
+    roadMinor: string;
+    roadMinorHalo: string;
+    roadMajor: string;
+    roadMajorHalo: string;
+    ocean: string;
+}
+interface Recipe {
+    background: string;
+    earth: string;
+    water: string;
+    /** Park, wood and scrub each take two tones; `b` is the slightly deeper of the pair. */
+    parkA: string;
+    parkB: string;
+    woodA: string;
+    woodB: string;
+    scrubA: string;
+    scrubB: string;
+    sand: string;
+    beach: string;
+    glacier: string;
+    /** Institutional land: hospital, school, industrial, military, zoo, aerodrome. */
+    institutional: string;
+    pedestrian: string;
+    aerodrome: string;
+    runway: string;
+    pier: string;
+    buildings: string;
+    railway: string;
+    boundaries: string;
+    roads: RoadRamp;
+    labels: LabelRamp;
+    /**
+     * Tunnels read one step recessive against the surface road, bridges one step assertive.
+     * Expressed as the colours to substitute rather than a computed shift, so a style can opt
+     * out of the convention where it does not suit the palette.
+     */
+    tunnelFill: string;
+    tunnelCasing: string;
+    bridgeCasing: string;
+    pois: Flavor["pois"];
+    landcover: Flavor["landcover"];
+}
+/**
+ * Expand a recipe into the full Flavor. Every one of the interface's required slots is written
+ * here exactly once, so a missing slot is a compile error rather than a silently black layer.
+ */
+declare function makeFlavor(r: Recipe): Flavor;
+
+/**
+ * The five ramp families (plus ember) a recipe draws from. `buildRecipes` is parameterized on
+ * this so the theme generator can re-emit the same recipes from *generated* ramps — same
+ * lightness ladders, a customer's hues — while the stock `RECIPES` stay byte-identical to the
+ * hand-tuned originals (they are `buildRecipes(STOCK_RAMPS)`).
+ */
+interface RampSet {
+    ink: typeof ink;
+    wave: typeof wave;
+    verdant: typeof verdant;
+    sandstone: typeof sandstone;
+    graphite: typeof graphite;
+    ember: typeof ember;
+}
+declare const STOCK_RAMPS: RampSet;
+/** Build the eight recipes from a ramp set. Stock ramps in → the shipped cartography out. */
+declare function buildRecipes(r: RampSet): Record<ThemeBase, Record<ThemeMode, Recipe>>;
+declare const RECIPES: Record<ThemeBase, Record<ThemeMode, Recipe>>;
+
+/**
+ * The unmap theme document: one theme, both modes, data only.
+ *
+ * A theme is colours, bounded numbers and one enum — never URLs, never expressions, never
+ * arbitrary style JSON. That is a security boundary, not a modelling choice: theme documents
+ * arrive on public query strings and are composed into style JSON the gateway signs its own
+ * asset URLs into. `validateTheme` is the only door in.
+ *
+ * `base` names the structural chassis (one of the four shipped styles); each half carries only
+ * sparse overrides on that chassis, so presets are near-empty documents and codes stay short.
+ */
+type DeepPartial<T> = {
+    [K in keyof T]?: NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
+};
+type BasemapOverrides = DeepPartial<Recipe>;
+interface MarkerTheme {
+    /** Pin colour, #RRGGBB or #RRGGBBAA. */
+    color?: string;
+    /** Pin scale, 0.5–2. */
+    scale?: number;
+}
+interface RouteTheme {
+    /** Main stroke colour. */
+    color?: string;
+    /** Main stroke width in px, 1–12. */
+    width?: number;
+    /** Main stroke opacity, 0–1. */
+    opacity?: number;
+    /** Under-stroke (casing) colour. */
+    casingColor?: string;
+    /** Casing width in px, 0–24. 0 disables the casing. */
+    casingWidth?: number;
+    /** Casing opacity, 0–1. */
+    casingOpacity?: number;
+}
+interface ThemeHalf {
+    basemap?: BasemapOverrides;
+    marker?: MarkerTheme;
+    route?: RouteTheme;
+}
+/**
+ * The simple-mode seed colours a generated theme was built from. Carried on the document so a
+ * shared code reopens the builder in simple mode with the seeds intact; the gateway validates
+ * them like any other field and otherwise ignores them — composition reads only the halves.
+ */
+interface ThemeSeeds {
+    /** Neutral cast: land, buildings, roads, labels. */
+    land: string;
+    water: string;
+    /** Vegetation: parks, wood, scrub, forest landcover. */
+    nature: string;
+    /** Marker + route accent. Defaults to the interface magenta. */
+    accent?: string;
+}
+interface ThemeDoc {
+    v: 1;
+    /** Display name, ≤ 40 chars. */
+    name?: string;
+    base: ThemeBase;
+    seeds?: ThemeSeeds;
+    light?: ThemeHalf;
+    dark?: ThemeHalf;
+}
+
+/**
+ * Validation failure. `detail` lists every bad path in one throw — collect-then-throw, so a
+ * builder user fixing a hand-edited document sees all of it at once rather than one field per
+ * round trip (the same reporting philosophy as the cartography contrast tests).
+ */
+declare class ThemeError extends Error {
+    readonly detail: string[];
+    constructor(message: string, detail: string[]);
+}
+/**
+ * Validate an untrusted value as a ThemeDoc. Returns the (unchanged) document on success;
+ * throws a `ThemeError` naming every invalid path otherwise. Unknown fields anywhere are
+ * errors — a theme is data only, and the reject-unknown posture is what keeps it that way.
+ */
+declare function validateTheme(input: unknown): ThemeDoc;
+
+/**
+ * The compact theme code: `ut1.` + base64url(deflate(minified JSON)).
+ *
+ * Web-standard streams only (CompressionStream/DecompressionStream, Blob, btoa/atob) so the
+ * same module runs in Workers, browsers and Node 18+. `deflate` (zlib) rather than
+ * `deflate-raw`, which Node 20 — the repo floor — does not implement; the wrapper costs six
+ * bytes and buys a checksum.
+ *
+ * `ut1` is the wire version. Bump it only for a breaking change, and keep decoding old
+ * prefixes forever: codes get hardcoded into customers' pages.
+ */
+declare const THEME_CODE_PREFIX = "ut1.";
+declare const MAX_CODE_LENGTH = 4096;
+/** Validate and encode a theme document to its compact `ut1.` code. Throws `ThemeError`. */
+declare function encodeTheme(doc: ThemeDoc): Promise<string>;
+/** Decode and validate a compact `ut1.` code. Every failure lands as `ThemeError`. */
+declare function decodeTheme(code: string): Promise<ThemeDoc>;
+
+/**
+ * Platform drawing defaults for the two client-side overlays a theme styles. These are exactly
+ * the convention the unmap.dev hero has always drawn: a magenta pin, and a route as a solid
+ * line over a wide translucent casing so it stays legible on light and dark cartography alike.
+ */
+declare const DEFAULT_MARKER: Required<MarkerTheme>;
+declare const DEFAULT_ROUTE: Required<RouteTheme>;
+interface ResolvedTheme {
+    /** `<base>-<mode>`, the chassis name — what selects sprites and terrain behaviour. */
+    flavorName: `${ThemeBase}-${ThemeMode}`;
+    flavor: Flavor;
+    marker: Required<MarkerTheme>;
+    route: Required<RouteTheme>;
+}
+/**
+ * Merge sparse overrides onto a base recipe, walking the base's own shape. Composing from the
+ * base's keys (never spreading the override object) means an unexpected key cannot ride along
+ * even if a caller skipped validation — defence in depth behind `validateTheme`.
+ */
+declare function mergeRecipe(base: Recipe, overrides?: BasemapOverrides): Recipe;
+/**
+ * Resolve one half of a theme into everything a renderer needs: the expanded Flavor, the
+ * chassis name, and marker/route styles with defaults filled in.
+ */
+declare function resolveTheme(doc: ThemeDoc, mode: ThemeMode): ResolvedTheme;
+
+/** WCAG contrast ratio between two hex colours (1–21). */
+declare function contrast(a: string, b: string): number;
+/** Every enforced pair with its floor — the generator's contrast-clamp iterates these. */
+declare const LABEL_PAIRS: Array<[keyof Flavor, keyof Flavor, number]>;
+interface ContrastWarning {
+    mode: ThemeMode;
+    /** The Flavor label slot that breaches, e.g. "city_label". */
+    label: string;
+    /** The Flavor slot it was checked against, e.g. "city_label_halo". */
+    background: string;
+    ratio: number;
+    /** 4.5 for primary labels, 3 for secondary. */
+    floor: number;
+}
+/** Every label-contrast breach in the theme, across both modes. Empty means clean. */
+declare function contrastWarnings(doc: ThemeDoc): ContrastWarning[];
+
+/**
+ * The shipped styles as starting-point themes: zero overrides, so each is guaranteed identical
+ * to its `flavor=` twin (asserted in the gateway theme tests). The builder opens on these.
+ */
+declare const PRESET_THEMES: Record<ThemeBase, ThemeDoc>;
+
+/**
+ * Minimal sRGB ↔ OKLCH conversion (Björn Ottosson's OKLab constants), plus a chroma-reducing
+ * gamut map. Zero dependencies — the generator is the only consumer and needs exactly this.
+ *
+ * OKLCH is the working space for the same reason the hand-built ramps in `palette.ts` were
+ * generated in it: perceived lightness is carried almost entirely by L, so a generator can swap
+ * hue and chroma while *preserving a ramp's lightness ladder* — which is where the label
+ * contrast the cartography tests enforce actually lives.
+ */
+interface Oklch {
+    /** Perceptual lightness, 0–1. */
+    l: number;
+    /** Chroma, 0 upward (~0.37 max for sRGB). */
+    c: number;
+    /** Hue in degrees, 0–360. */
+    h: number;
+}
+/** Parse #RRGGBB (or #RRGGBBAA — alpha ignored) into OKLCH. */
+declare function hexToOklch(hex: string): Oklch;
+/**
+ * OKLCH → #RRGGBB. Out-of-gamut colours are mapped by *reducing chroma* at constant L and h
+ * (bisection), never by clipping channels — clipping shifts perceived lightness, and the whole
+ * generator contract is that L is preserved.
+ */
+declare function oklchToHex(color: Oklch): string;
+
+/** The seeds that reproduce (approximately) the stock cartography. Simple mode opens on these. */
+declare const DEFAULT_SEEDS: Required<ThemeSeeds>;
+/**
+ * Generate a full theme from seed colours. Deterministic; the result always clears the label
+ * floors in both modes (enforced, and asserted by the hue-sweep test).
+ *
+ * Family mapping: `land` recolours the neutral spine (and `muted`'s graphite, at a whisper of
+ * chroma — that flavour exists to vanish under data), `water` the wave ramp, `nature` the
+ * verdant ramp. Warm landcover (sandstone), POI accents, white road fills and the street
+ * motorway orange stay stock: they are tuned relationships, not identity. `accent` styles the
+ * marker and route overlays only — it never enters the basemap, same rule as the brand magenta.
+ */
+declare function generateTheme(base: ThemeBase, seeds: ThemeSeeds): ThemeDoc;
+
+/**
+ * Curated seed palettes for the builder's simple mode — the hand-picked starting points, named
+ * for Canadian landscapes. Each is just a seed trio + accent; `generateTheme` does the rest,
+ * and its contrast guarantee holds for these like any other seeds (asserted in tests).
+ */
+interface SeedPalette {
+    /** Display name, lowercase like the flavour names. Not translated — these are names. */
+    name: string;
+    seeds: Required<ThemeSeeds>;
+}
+declare const SEED_PALETTES: SeedPalette[];
+/**
+ * A random but *harmonic* seed trio — the shuffle button. Hues are related (water lands
+ * cool-of-complementary, nature analogous-of-triadic, the accent opposes the land) and chroma
+ * stays inside a tasteful band, so shuffles read as designed rather than random; the
+ * generator's contrast guarantee makes every one of them legible regardless.
+ *
+ * `rng` is injectable (returns [0,1)) so tests can drive it deterministically.
+ */
+declare function shuffleSeeds(rng?: () => number): Required<ThemeSeeds>;
+
+export { type BasemapOverrides, type ContrastWarning, DEFAULT_MARKER, DEFAULT_ROUTE, DEFAULT_SEEDS, type DeepPartial, LABEL_PAIRS, type LabelRamp, MAX_CODE_LENGTH, MODES, type MarkerTheme, type Oklch, PRESET_THEMES, RECIPES, type RampSet, type Recipe, type ResolvedTheme, type RoadRamp, type RouteTheme, SEED_PALETTES, STOCK_RAMPS, type SeedPalette, THEME_BASES, THEME_CODE_PREFIX, type ThemeBase, type ThemeDoc, ThemeError, type ThemeHalf, type ThemeMode, type ThemeSeeds, buildRecipes, contrast, contrastWarnings, decodeTheme, ember, encodeTheme, generateTheme, graphite, hexToOklch, ink, makeFlavor, mergeRecipe, oklchToHex, resolveTheme, sandstone, shuffleSeeds, validateTheme, verdant, wave };