@unmap/themes 0.2.0 → 0.3.0

package/README.md

@@ -20,7 +20,7 @@ import { encodeTheme, decodeTheme, validateTheme, ThemeError } from '@unmap/them
 const code = await encodeTheme({
   v: 1,
   name: 'copper',
-  base: 'outdoor',                                  // base | muted | outdoor | decimal | blueprint
+  base: 'outdoor',                                  // base | muted | outdoor | decimal | blueprint | blush | orchid | canopy | lagoon
   light: { basemap: { water: '#9CCFD2' }, route: { color: '#B85C00', width: 4 } },
   dark:  { basemap: { water: '#12303A' }, route: { color: '#FFA24D', width: 4 } },
 })
@@ -31,7 +31,7 @@ const doc = await decodeTheme(code)                 // validated ThemeDoc, or th
 
 ## What is in a theme
 
-- `base` picks the style: `base`, `muted`, `outdoor`, `decimal` or `blueprint`. Each of `light` and `dark` carries
+- `base` picks the style: `base`, `muted`, `outdoor`, `decimal`, `blueprint`, `blush`, `orchid`, `canopy` or `lagoon`. Each of `light` and `dark` carries
   sparse overrides on that style, so a theme with no overrides renders exactly like its
   `flavor=` twin.
 - `basemap` overrides are colours on the style's recipe (land, water, vegetation, roads, labels,

package/dist/index.d.ts

@@ -199,6 +199,65 @@ declare const cobalt: {
     readonly 950: "#0F1629";
     readonly 1000: "#080B15";
 };
+/**
+ * Rose, hue 20. The `blush` pair's land, buildings and labels: a pink that stays a field at the
+ * light steps and becomes a wine at the dark ones. Same lightness ladder as `ink`; chroma rises
+ * with lightness to the mid steps and eases off toward white.
+ */
+declare const rose: {
+    readonly 25: "#FFF3F3";
+    readonly 50: "#FFEBEA";
+    readonly 100: "#FFDFDE";
+    readonly 200: "#FECFCE";
+    readonly 300: "#FCBDBC";
+    readonly 400: "#F8A4A4";
+    readonly 500: "#E48687";
+    readonly 600: "#BA6D6D";
+    readonly 700: "#8D5151";
+    readonly 800: "#643838";
+    readonly 850: "#4B2929";
+    readonly 900: "#351B1B";
+    readonly 950: "#241111";
+    readonly 1000: "#150808";
+};
+/**
+ * Lilac, hue 300, low chroma. The `orchid` pair's land, buildings and labels — a lavender grey
+ * rather than a purple, so the vivid teal parks and sky water are what carry the colour. Chroma
+ * grows a little toward the dark steps so the labels read as violet rather than as grey.
+ */
+declare const lilac: {
+    readonly 25: "#F8F5FF";
+    readonly 50: "#F2EDFF";
+    readonly 100: "#EAE4F9";
+    readonly 200: "#DFD8EE";
+    readonly 300: "#D2CBE1";
+    readonly 400: "#C1BACF";
+    readonly 500: "#A7A1B5";
+    readonly 600: "#888296";
+    readonly 700: "#676174";
+    readonly 800: "#4A415A";
+    readonly 850: "#382E4A";
+    readonly 900: "#281C3C";
+    readonly 950: "#1C0E30";
+    readonly 1000: "#110225";
+};
+/**
+ * Aqua, hue 205. Vivid teal on the `wave` ladder for `orchid`'s and `lagoon`'s parks — the
+ * only park colour on the map that is not a green. Chroma peaks at the mid steps.
+ */
+declare const aqua: {
+    readonly 100: "#C7F1F5";
+    readonly 200: "#ACE3E9";
+    readonly 300: "#89D2DB";
+    readonly 400: "#57BEC9";
+    readonly 500: "#00A6B3";
+    readonly 600: "#00858F";
+    readonly 700: "#00636B";
+    readonly 800: "#004349";
+    readonly 900: "#05292D";
+    readonly 950: "#081B1D";
+    readonly 980: "#060E0F";
+};
 
 /**
  * The unmap cartography authoring surface, moved here from apps/gateway/src/flavors.ts so the
@@ -217,7 +276,7 @@ declare const cobalt: {
  * `relief` and `street` were retired; they are not listed here. Short preset codes still
  * decode those slots via `normalizeThemeBase` / the slot table in `preset.ts`.
  */
-declare const THEME_BASES: readonly ["base", "muted", "outdoor", "decimal", "blueprint"];
+declare const THEME_BASES: readonly ["base", "muted", "outdoor", "decimal", "blueprint", "blush", "orchid", "canopy", "lagoon"];
 type ThemeBase = (typeof THEME_BASES)[number];
 /** Map a theme `base` — living or retired — onto a shipped style. `null` if unknown. */
 declare function normalizeThemeBase(base: string): ThemeBase | null;
@@ -317,6 +376,9 @@ interface RampSet {
     mist: typeof mist;
     jade: typeof jade;
     cobalt: typeof cobalt;
+    rose: typeof rose;
+    lilac: typeof lilac;
+    aqua: typeof aqua;
     ember: typeof ember;
 }
 declare const STOCK_RAMPS: RampSet;
@@ -378,12 +440,41 @@ interface ThemeSeeds {
     /** Marker + route accent. Defaults to the interface magenta. */
     accent?: string;
 }
+/**
+ * The major layer groups a theme can hide or reorder, in their stock bottom-to-top draw order.
+ * Every layer the cartography draws belongs to exactly one of these (see `layerGroupOf`) except
+ * the background, which always stays underneath. `buildings3d` is the one group that is off by
+ * default: it draws building extrusions from the tiles' `height` property on top of the roads.
+ *
+ * Append only, like `THEME_BASES`: the names are on the wire in every `ut1.` code.
+ */
+declare const LAYER_GROUPS: readonly ["land", "water", "buildings", "roads", "boundaries", "buildings3d", "labels"];
+type LayerGroup = (typeof LAYER_GROUPS)[number];
+/**
+ * Structural overrides on the layer groups. Doc-level, not per half: which layers draw, and in
+ * what order, is one decision for both modes — colour is the only thing that differs between
+ * light and dark. Sparse like the halves: an absent field means stock.
+ */
+interface ThemeLayers {
+    /**
+     * Per-group visibility; a missing key means the group's default (every group on except
+     * `buildings3d`). Hidden groups are dropped from the style entirely.
+     */
+    visible?: Partial<Record<LayerGroup, boolean>>;
+    /**
+     * Bottom-to-top draw order, always the full set of groups exactly once. Absent means the
+     * stock cartography order, in which the groups interleave (tunnels under buildings, bridges
+     * over boundaries); an explicit order regroups every layer under its group.
+     */
+    order?: LayerGroup[];
+}
 interface ThemeDoc {
     v: 1;
     /** Display name, ≤ 40 chars. */
     name?: string;
     base: ThemeBase;
     seeds?: ThemeSeeds;
+    layers?: ThemeLayers;
     light?: ThemeHalf;
     dark?: ThemeHalf;
 }
@@ -429,9 +520,10 @@ declare function decodeTheme(code: string): Promise<ThemeDoc>;
  *
  *   u00, u01, u04   living styles from the original lineup (base, muted, outdoor)
  *   u02, u03        retired styles (relief → outdoor, street → base)
- *   u05, u06        styles added later (decimal, blueprint); u07 is the one spare slot
+ *   u05, u06        the second wave (decimal, blueprint)
+ *   u5K, u5N, …     the third wave (blush, orchid, canopy, lagoon) and any style after them
  *   u08…            named theme preset on one of the original style slots
- *   u5K…            named theme preset on one of the later slots
+ *   u5L…            named theme preset on a later style
  *   longer          custom seed colours (4× RGB) on any style
  *
  * Advanced overrides — anything `generateTheme` would not emit — still use the `ut1.` deflate
@@ -485,6 +577,58 @@ declare function mergeRecipe(base: Recipe, overrides?: BasemapOverrides): Recipe
  */
 declare function resolveTheme(doc: ThemeDoc, mode: ThemeMode): ResolvedTheme;
 
+/**
+ * Layer groups: the structural half of a theme. A theme can hide any of the seven major groups
+ * and redraw them in another order, the way kepler.gl's base-map panel does. This module owns
+ * the mapping from the expanded Protomaps layer list onto those groups and applies a document's
+ * `layers` field to a style's layer array.
+ *
+ * It works on the expanded layers rather than the Flavor because the groups are about what
+ * draws, not what colour it draws in — the Recipe stays the colour surface, this is the only
+ * structural one, and both are still data (booleans and one enum list on the wire).
+ */
+/** Stock visibility: every group draws except the extrusions, which are opt-in. */
+declare const DEFAULT_LAYER_VISIBILITY: Readonly<Record<LayerGroup, boolean>>;
+/** The id of the synthetic extrusion layer `buildings3d` draws. */
+declare const BUILDINGS_3D_LAYER_ID = "buildings_3d";
+/**
+ * Which group an expanded Protomaps layer belongs to, or `null` for the background, which is
+ * never hidden or moved: with land off it is what you see. Symbol layers are labels regardless
+ * of their source, so the POI icons, shields and one-way arrows hide with the text.
+ *
+ * The contract test asserts every stock layer lands in a group, so an upstream layer this
+ * cannot place fails loudly rather than becoming an unmovable, unhideable stray.
+ */
+declare function layerGroupOf(layer: {
+    id: string;
+    type: string;
+}): LayerGroup | null;
+/** Whether a group draws under this `layers` field (absent field means stock). */
+declare function isLayerVisible(layers: ThemeLayers | undefined, group: LayerGroup): boolean;
+/** The bottom-to-top group order this `layers` field asks for; stock when it names none. */
+declare function effectiveLayerOrder(layers: ThemeLayers | undefined): readonly LayerGroup[];
+/** True when `order` is the stock order (or absent), so nothing needs regrouping. */
+declare function isStockLayerOrder(order: readonly LayerGroup[] | undefined): boolean;
+/** True when the field changes nothing — the builder strips such a field back to absent. */
+declare function isStockLayers(layers: ThemeLayers | undefined): boolean;
+/**
+ * Apply a theme's `layers` field to an expanded style layer array. Returns the input untouched
+ * when the field changes nothing, so a zero-override theme stays byte-identical to its flavor.
+ *
+ * Hidden groups are removed outright rather than set to `visibility: none` — a smaller style,
+ * and nothing left for a client to accidentally switch back on. With the stock order the
+ * remaining layers keep their stock positions (and the extrusions, if on, slot in just under
+ * the labels). With a custom order every group's layers are gathered under it, in stock
+ * relative order within the group; the background and any layer outside every group stay
+ * first, in their stock order.
+ *
+ * `buildingsColor` paints the extrusions: the resolved theme's `buildings` slot.
+ */
+declare function applyThemeLayers<T extends {
+    id: string;
+    type: string;
+}>(styleLayers: T[], layers: ThemeLayers | undefined, buildingsColor: string): T[];
+
 /** 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. */
@@ -506,7 +650,7 @@ 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.
  *
- * Named after the style itself — `base`, `muted`, `outdoor`, `decimal`, `blueprint` — the same word the homepage, the
+ * Named after the style itself — `base`, `muted`, `outdoor`, `decimal`, `blueprint`, `blush`, … — the same word the homepage, the
  * SDK's `style` option and the gateway URL use. The theme presets (`process ink`, `boreal`, …)
  * are a separate set layered on a style; a style never borrows one's name.
  */
@@ -547,7 +691,8 @@ declare const DEFAULT_SEEDS: Required<ThemeSeeds>;
  * Family mapping: `land` recolours the land spines — `ink`, `base`'s `paper`, `muted`'s
  * `graphite` at a whisper of chroma (that style exists to vanish under data), and the
  * single-hue families of `decimal` (`jade`) and `blueprint` (`cobalt`) at full chroma, so a
- * seed can carry them to any hue. `water` recolours the wave, sky, and mist ramps (`mist` is
+ * seed can carry them to any hue, plus `blush`'s `rose` and `orchid`'s `lilac`. `nature`
+ * recolours `verdant` and the teal `aqua` of `orchid` and `lagoon`. `water` recolours the wave, sky, and mist ramps (`mist` is
  * greyscale in stock `muted` and takes the water seed's hue outright), `nature` the verdant
  * ramp. Warm landcover (sandstone), POI accents and white road fills stay stock: they
  * are tuned relationships, not identity. `accent` styles the marker and route overlays only —
@@ -576,4 +721,4 @@ declare const THEME_PRESETS: ThemePreset[];
  */
 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_CODE_PREFIX, PRESET_CODE_RE, RECIPES, type RampSet, type Recipe, type ResolvedTheme, type RoadRamp, type RouteTheme, STOCK_RAMPS, STYLE_THEMES, THEME_BASES, THEME_CODE_PREFIX, THEME_PRESETS, type ThemeBase, type ThemeDoc, ThemeError, type ThemeHalf, type ThemeMode, type ThemePreset, type ThemeSeeds, buildRecipes, cobalt, contrast, contrastWarnings, decodePreset, decodeTheme, ember, encodePreset, encodeTheme, generateTheme, graphite, hexToOklch, ink, isThemePresetCode, jade, makeFlavor, mergeRecipe, mist, normalizeThemeBase, oklchToHex, paper, presetId, registryThemeKey, resolveTheme, sandstone, shuffleSeeds, sky, validateTheme, verdant, wave };
+export { BUILDINGS_3D_LAYER_ID, type BasemapOverrides, type ContrastWarning, DEFAULT_LAYER_VISIBILITY, DEFAULT_MARKER, DEFAULT_ROUTE, DEFAULT_SEEDS, type DeepPartial, LABEL_PAIRS, LAYER_GROUPS, type LabelRamp, type LayerGroup, MAX_CODE_LENGTH, MODES, type MarkerTheme, type Oklch, PRESET_CODE_PREFIX, PRESET_CODE_RE, RECIPES, type RampSet, type Recipe, type ResolvedTheme, type RoadRamp, type RouteTheme, STOCK_RAMPS, STYLE_THEMES, THEME_BASES, THEME_CODE_PREFIX, THEME_PRESETS, type ThemeBase, type ThemeDoc, ThemeError, type ThemeHalf, type ThemeLayers, type ThemeMode, type ThemePreset, type ThemeSeeds, applyThemeLayers, aqua, buildRecipes, cobalt, contrast, contrastWarnings, decodePreset, decodeTheme, effectiveLayerOrder, ember, encodePreset, encodeTheme, generateTheme, graphite, hexToOklch, ink, isLayerVisible, isStockLayerOrder, isStockLayers, isThemePresetCode, jade, layerGroupOf, lilac, makeFlavor, mergeRecipe, mist, normalizeThemeBase, oklchToHex, paper, presetId, registryThemeKey, resolveTheme, rose, sandstone, shuffleSeeds, sky, validateTheme, verdant, wave };