@mapcairn/theme 0.0.0-stage → 0.1.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,866 @@
1
+ /**
2
+ * The one accent: a clear blue at hue 255. Chroma follows the sRGB gamut edge
3
+ * at each lightness, which is why it peaks in the middle of the ramp.
4
+ * Step 600 is the map overlay blue and the light focus ring; 700 is the light
5
+ * accent used for text and fills; 300 is the dark accent.
6
+ */
7
+ declare const accent: {
8
+ readonly 50: "oklch(0.97 0.013 255)";
9
+ readonly 100: "oklch(0.93 0.032 255)";
10
+ readonly 200: "oklch(0.87 0.06 255)";
11
+ readonly 300: "oklch(0.8 0.095 255)";
12
+ readonly 400: "oklch(0.74 0.125 255)";
13
+ readonly 500: "oklch(0.66 0.17 255)";
14
+ readonly 600: "oklch(0.55 0.175 255)";
15
+ readonly 700: "oklch(0.46 0.15 255)";
16
+ readonly 800: "oklch(0.39 0.125 255)";
17
+ readonly 900: "oklch(0.32 0.095 255)";
18
+ };
19
+
20
+ /**
21
+ * Name of one of the representative map backdrops: white, black, a light map
22
+ * and the default basemap's land colour. Indexing `representativeBackdrops`
23
+ * with it keeps the two in step at compile time.
24
+ */
25
+ export declare type BackdropName = "white" | "black" | "lightMap" | "defaultBasemap";
26
+
27
+ /** The backdrop blur applied behind translucent surfaces, or `none` when they are opaque. */
28
+ declare const blur_2: `var(--${string})`;
29
+ export { blur_2 as blur }
30
+
31
+ /** Backdrop blur applied behind translucent surfaces. */
32
+ declare const blurValue = "blur(20px) saturate(150%)";
33
+
34
+ /**
35
+ * Checks a proposed theme against WCAG 2.2 AA: 4.5:1 for text, 3:1 for icons,
36
+ * control edges, selection and the focus ring. A role left out is checked at
37
+ * its default, so a changed `accent` is also checked against the default
38
+ * `accentTint`. Translucent surfaces are flattened over each representative
39
+ * map backdrop (white, black, a light map and the default basemap), so the
40
+ * worst case is reported.
41
+ *
42
+ * Pure and total: it never throws and never decides whether a theme is
43
+ * accepted. A colour it cannot check is reported in `invalid`, and the pairs
44
+ * that depend on it are left out of `findings`; the host decides what a
45
+ * failure means. Only the default colour set is checked: the opaque and
46
+ * `prefers-contrast: more` sets are not overridable.
47
+ *
48
+ * @param override The proposed colours for light and dark.
49
+ * @returns A finding for every checked pair and backdrop, in both themes.
50
+ */
51
+ export declare function checkThemeContrast(override: ThemeOverride): ThemeContrastCheck;
52
+
53
+ /** A colour as the token files write it, or one already parsed. */
54
+ export declare type ColourInput = string | Rgba;
55
+
56
+ /** Names of the colour roles, in declaration order. */
57
+ declare const colourRoleNames: readonly ["surface", "surfaceRaised", "text", "textMuted", "accent", "accentTint", "accentContrast", "hairline", "controlBoundary", "chromeBorder", "danger", "dangerTint", "scrim", "focusRing", "focusRingInner", "pageBackground", "mapBackground", "mapGlobeSpace", "mapPin", "mapMeasureLine", "mapMeasureFill", "mapAccuracy", "mapAccuracyFill", "mapHalo"];
58
+
59
+ /** The semantic colour roles. Components use these and never a ramp step. */
60
+ declare interface ColourRoles {
61
+ /** Floating chrome (search pill, control groups, sheet). Translucent by default. */
62
+ surface: string;
63
+ /** A surface raised inside another surface (inputs, cards). */
64
+ surfaceRaised: string;
65
+ /** Body text and icons. */
66
+ text: string;
67
+ /** Secondary text. Never used below 13px and never as the only cue. */
68
+ textMuted: string;
69
+ /** The accent: links, selected state, switch-on, selected basemap outline. */
70
+ accent: string;
71
+ /** Opaque tint behind selected rows and chips. */
72
+ accentTint: string;
73
+ /** Text and icons placed on `accent`. */
74
+ accentContrast: string;
75
+ /** Dividers inside lists and between grouped controls. Decorative. */
76
+ hairline: string;
77
+ /** The edge of an input, switch track or slider track, where the edge identifies the control. */
78
+ controlBoundary: string;
79
+ /** Border for floating chrome. Transparent by default so forced colours can paint it. */
80
+ chromeBorder: string;
81
+ /** Error text and icons. */
82
+ danger: string;
83
+ /** Opaque tint behind an error message. */
84
+ dangerTint: string;
85
+ /** Veil behind a modal sheet. */
86
+ scrim: string;
87
+ /** Outer tone of the two-tone focus ring. */
88
+ focusRing: string;
89
+ /** Inner tone of the focus ring, in the surface colour. */
90
+ focusRingInner: string;
91
+ /**
92
+ * Full pages that are not the map (privacy, errors, the style guide) and
93
+ * the document behind everything. Follows the theme.
94
+ */
95
+ pageBackground: string;
96
+ /**
97
+ * Colour of the map region before the map draws: the default basemap's
98
+ * land colour, the same in both themes, so the first view does not flash a
99
+ * different colour before the basemap appears.
100
+ */
101
+ mapBackground: string;
102
+ /**
103
+ * The space around the sphere when the map is drawn as a globe, in place
104
+ * of `mapBackground`. Darker than every pale basemap's land, so the edge
105
+ * of the globe shows, and in the dark theme lighter and bluer than the
106
+ * near-black Dark basemap, so its edge shows too. A flat map never uses it.
107
+ */
108
+ mapGlobeSpace: string;
109
+ /** Dropped pin. */
110
+ mapPin: string;
111
+ /** Measurement line. */
112
+ mapMeasureLine: string;
113
+ /** Measured area fill. Translucent by design. */
114
+ mapMeasureFill: string;
115
+ /** Location accuracy circle outline. */
116
+ mapAccuracy: string;
117
+ /** Location accuracy circle fill. Translucent by design. */
118
+ mapAccuracyFill: string;
119
+ /** Outline that separates a pin or line from the map beneath. */
120
+ mapHalo: string;
121
+ }
122
+
123
+ /**
124
+ * Composites `foreground` over `backdrop` in gamma-encoded sRGB, which is
125
+ * what browsers do for `rgba()` and `oklch(... / a)`. The result is opaque
126
+ * whenever the backdrop is.
127
+ */
128
+ export declare function compositeOver(foreground: ColourInput, backdrop: ColourInput): Rgba;
129
+
130
+ /**
131
+ * The colour a pair's foreground sits on. `surface` and `surfaceRaised` are
132
+ * translucent, so they are flattened over each backdrop first; `map` is the
133
+ * bare map itself; the page background and the map halo are fixed defaults
134
+ * a host cannot override; the rest are opaque roles.
135
+ */
136
+ export declare type ContrastBackground = ThemeColourRole | "pageBackground" | "mapHalo" | "map";
137
+
138
+ /** The measured contrast of one pair, in one theme, over one backdrop. */
139
+ export declare interface ContrastFinding {
140
+ /** The theme the finding is for. */
141
+ theme: ThemeName;
142
+ /** The role drawn: text, an icon, an edge or a ring. */
143
+ foreground: ThemeColourRole;
144
+ /** The role it sits on, or `map` for the bare map. */
145
+ background: ContrastBackground;
146
+ /** The map backdrop checked over, or `null` for an opaque background. */
147
+ backdrop: BackdropName | null;
148
+ /** Whether the foreground is text or a non-text mark. */
149
+ kind: PairKind;
150
+ /** The contrast ratio, unrounded. */
151
+ ratio: number;
152
+ /** The WCAG 2.2 AA minimum for this kind of pair. */
153
+ required: number;
154
+ /** Whether `ratio` reaches `required`. */
155
+ passes: boolean;
156
+ }
157
+
158
+ /**
159
+ * WCAG contrast ratio, from 1 to 21, between two opaque colours.
160
+ * @throws When either colour is translucent. Composite it over a backdrop
161
+ * with {@link compositeOver} first, because the ratio depends on it.
162
+ */
163
+ export declare function contrastRatio(a: ColourInput, b: ColourInput): number;
164
+
165
+ /**
166
+ * Generates the stylesheet that applies a colour override to the SDK's
167
+ * interface inside `options.scope`, or refuses.
168
+ *
169
+ * The host serves the result as a same-origin file, linked after the SDK's
170
+ * own stylesheet: it holds no inline style, needs no nonce and shows no flash
171
+ * under a strict policy. The names it writes are resolved from the built
172
+ * `tokens`, so they match the SDK's stylesheet only for the same installed
173
+ * version of this package, and the host never writes one.
174
+ *
175
+ * A theme below WCAG 2.2 AA is refused: the result carries the findings and
176
+ * no CSS, so a host fixes its colours first. The check measures the colours
177
+ * as written to the stylesheet, with the inner focus ring and the opaque
178
+ * surfaces derived. The opaque surface is the surface flattened over the
179
+ * theme's page background, used where `backdrop-filter` is not supported and
180
+ * under `prefers-reduced-transparency`. The page background, the map overlay
181
+ * roles and the data palette are not overridable.
182
+ *
183
+ * Every rule is written for `(not (prefers-contrast: more))` and
184
+ * `(not (forced-colors: active))`, so high-contrast and forced-colours users
185
+ * keep the SDK's own values. A colour is written back as `#rrggbb` or
186
+ * `#rrggbbaa`, parsed with the same strict reader as
187
+ * {@link checkThemeContrast}, so nothing else can enter the stylesheet.
188
+ *
189
+ * Total: it never throws. A tooltip renders in a portal outside the scope, so
190
+ * it keeps the SDK's colours in a `#id` or `.class` scope.
191
+ *
192
+ * @param override - The colours to change, per theme.
193
+ * @param options - The scope to apply them in.
194
+ * @returns The stylesheet and the findings, or the reasons it was refused.
195
+ */
196
+ export declare function createThemeStylesheet(override: ThemeOverride, options: ThemeStylesheetOptions): ThemeStylesheet;
197
+
198
+ /**
199
+ * The two-tone edge of a data marker: a dark line just outside the fill, and
200
+ * a white halo outside that. The same in both themes and on every basemap,
201
+ * because a marker looks the same wherever it is drawn. On a light map the
202
+ * dark edge shows the pale colours (yellow, the lightest ramp step); on a
203
+ * dark surface the halo shows the dark ones (the darkest step). Plain hex,
204
+ * because the map engine draws markers as bitmaps.
205
+ */
206
+ declare const dataMarker: {
207
+ readonly edge: "#1c2733";
208
+ readonly halo: "#ffffff";
209
+ /** Width of the dark edge, in CSS pixels. */
210
+ readonly edgeWidth: 1;
211
+ /** Width of the white halo outside the edge, in CSS pixels. */
212
+ readonly haloWidth: 1.5;
213
+ };
214
+
215
+ /**
216
+ * The data palette: the colours data layers draw with, named by the slots
217
+ * `@mapcairn/core` lets a layer definition use (`PALETTE_SLOTS`). Six-digit hex,
218
+ * because the map engine and SVG `fill` attributes read it directly.
219
+ *
220
+ * The categorical colours are Okabe-Ito (without black, which vanishes on a
221
+ * dark basemap). The ordinal ramp runs light to dark in the manner of
222
+ * viridis, for ordered values such as magnitude. Every marker also has a
223
+ * dark edge and white halo (`dataMarker`) and a shape or size, so colour is never the only signal.
224
+ */
225
+ declare const dataPalette: {
226
+ readonly orange: "#e69f00";
227
+ readonly "sky-blue": "#56b4e9";
228
+ readonly "bluish-green": "#009e73";
229
+ readonly yellow: "#f0e442";
230
+ readonly blue: "#0072b2";
231
+ readonly vermillion: "#d55e00";
232
+ readonly "reddish-purple": "#cc79a7";
233
+ readonly "ordinal-1": "#fde725";
234
+ readonly "ordinal-2": "#5ec962";
235
+ readonly "ordinal-3": "#21918c";
236
+ readonly "ordinal-4": "#3b528b";
237
+ readonly "ordinal-5": "#440154";
238
+ };
239
+
240
+ /**
241
+ * Two-tone focus ring for every interactive element and the focused map.
242
+ * The inner ring is a shadow in the surface colour and the outer ring is an
243
+ * outline, so that `forced-colors: active` (which removes shadows but keeps
244
+ * outlines) still shows a ring, recoloured to `Highlight`.
245
+ */
246
+ export declare const focusRing: {
247
+ readonly outline: `var(--${string}) solid var(--${string})`;
248
+ readonly outlineOffset: `var(--${string})`;
249
+ readonly boxShadow: `0 0 0 var(--${string}) var(--${string})`;
250
+ };
251
+
252
+ /** Focus ring widths. `prefers-contrast: more` raises both. */
253
+ declare const focusWidth: {
254
+ readonly inner: "2px";
255
+ readonly outer: "2px";
256
+ };
257
+
258
+ /** Focus ring widths under `prefers-contrast: more`. */
259
+ declare const focusWidthContrastMore: {
260
+ readonly inner: "3px";
261
+ readonly outer: "3px";
262
+ };
263
+
264
+ /**
265
+ * The font stack: the self-hosted variable face, its metric-matched fallback
266
+ * (declared in `packages/web/src/fonts/fonts.css`) and then system fonts that
267
+ * also cover non-Latin place names.
268
+ */
269
+ declare const fontFamily = "\"IBM Plex Sans Variable\", \"IBM Plex Sans Fallback\", system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
270
+
271
+ /**
272
+ * The stack for code samples only: the system's own monospaced faces, so no
273
+ * second web font is downloaded. Interface text never uses it.
274
+ */
275
+ declare const fontFamilyMono = "ui-monospace, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace";
276
+
277
+ /** Font weights. Nothing else is declared in `@font-face`. */
278
+ declare const fontWeight: {
279
+ readonly regular: "400";
280
+ readonly semibold: "600";
281
+ };
282
+
283
+ /**
284
+ * Colours for `forced-colors: active`, written as CSS system colours. Only the
285
+ * chrome roles are mapped; map overlay colours stay as they are because the
286
+ * map is drawn on a canvas that forced colours does not recolour.
287
+ */
288
+ declare const forcedColors: Partial<ColourRoles>;
289
+
290
+ /** Distance from the screen edge to floating chrome. */
291
+ declare const inset = "12px";
292
+
293
+ /** A proposed colour that was not checked, so its pairs are missing from the findings. */
294
+ export declare interface InvalidColour {
295
+ /** The theme it was proposed for, or `null` when it concerns the whole override. */
296
+ theme: ThemeName | null;
297
+ /**
298
+ * The role, or the key or section that could not be used: `override` for
299
+ * an override that is not a plain object, `colour` for a section that is not
300
+ * (with `theme` set when it is one theme's section).
301
+ */
302
+ role: string;
303
+ /** The value as the host supplied it. */
304
+ value: unknown;
305
+ /** Why it could not be checked. */
306
+ reason: InvalidColourReason;
307
+ }
308
+
309
+ /** Why a proposed colour could not be checked. */
310
+ export declare type InvalidColourReason = "unknown-role" | "unparseable" | "out-of-gamut" | "translucent" | "unknown-key" | "malformed" | "unreadable";
311
+
312
+ /**
313
+ * The CSS variable references for everything drawn over the map: pin,
314
+ * measure line and fill, accuracy circle, halo, loading indicator and
315
+ * tile-error banner. Overlay components style from these alone, so they
316
+ * look the same on every map engine and never import an engine's styles.
317
+ *
318
+ * Each colour clears 3:1 against light and dark basemaps; `contrast.test.ts`
319
+ * enforces it. The fills are translucent by design, so the outline beside
320
+ * them carries the contrast.
321
+ */
322
+ export declare const mapOverlayTokens: {
323
+ /** The map element's colour before tiles load. */
324
+ readonly background: `var(--${string})`;
325
+ /** The space around the sphere when the map is drawn as a globe. */
326
+ readonly globeSpace: `var(--${string})`;
327
+ /** Dropped pin. */
328
+ readonly pin: `var(--${string})`;
329
+ /** Outline that separates a pin or line from the map beneath. */
330
+ readonly halo: `var(--${string})`;
331
+ /** Measurement line. */
332
+ readonly measureLine: `var(--${string})`;
333
+ /** Measured area fill. */
334
+ readonly measureFill: `var(--${string})`;
335
+ /** Location accuracy circle outline. */
336
+ readonly accuracyStroke: `var(--${string})`;
337
+ /** Location accuracy circle fill. */
338
+ readonly accuracyFill: `var(--${string})`;
339
+ /** The moving arc of the tile-loading indicator. */
340
+ readonly loadingIndicator: `var(--${string})`;
341
+ /** The track behind the loading indicator. */
342
+ readonly loadingTrack: `var(--${string})`;
343
+ /** Tile-error banner background. */
344
+ readonly tileErrorBackground: `var(--${string})`;
345
+ /** Tile-error banner text and icon. */
346
+ readonly tileErrorText: `var(--${string})`;
347
+ };
348
+
349
+ /** Motion tokens. Only transform and opacity animate. */
350
+ declare const motion: {
351
+ readonly duration: {
352
+ readonly fast: "120ms";
353
+ readonly base: "200ms";
354
+ readonly slow: "320ms";
355
+ };
356
+ /** Durations when `prefers-reduced-motion: reduce` is set. */
357
+ readonly durationReduced: "0.01ms";
358
+ readonly easing: "cubic-bezier(0.2, 0, 0, 1)";
359
+ readonly spring: "linear(0, 0.229, 0.593, 0.858, 0.992, 1.035, 1.035, 1.021, 1.009, 1.002, 0.999, 0.999, 0.999, 0.999, 1, 1, 1, 1, 1)";
360
+ };
361
+
362
+ /**
363
+ * Neutral ramp with a faint cool tint (hue 250, chroma at most 0.012).
364
+ * Steps run light to dark; the number is the usual 50 to 950 scale.
365
+ */
366
+ declare const neutral: {
367
+ readonly 50: "oklch(0.975 0.003 250)";
368
+ readonly 100: "oklch(0.955 0.004 250)";
369
+ readonly 200: "oklch(0.915 0.005 250)";
370
+ readonly 300: "oklch(0.86 0.007 250)";
371
+ readonly 400: "oklch(0.74 0.009 250)";
372
+ readonly 500: "oklch(0.62 0.011 250)";
373
+ readonly 600: "oklch(0.53 0.012 250)";
374
+ readonly 700: "oklch(0.44 0.012 250)";
375
+ readonly 800: "oklch(0.34 0.011 250)";
376
+ readonly 850: "oklch(0.28 0.01 250)";
377
+ readonly 900: "oklch(0.22 0.01 250)";
378
+ readonly 950: "oklch(0.17 0.008 250)";
379
+ };
380
+
381
+ /**
382
+ * The language subtags that take {@link nonLatinType}, matched with `:lang()`
383
+ * so a region or script subtag (`zh-Hans`) matches too. The list is not
384
+ * exhaustive; a host adds rules for others. Custom properties inherit, so a
385
+ * Latin span inside a listed language keeps these values.
386
+ */
387
+ declare const nonLatinLanguages: readonly ["ar", "fa", "ur", "ps", "sd", "ug", "ckb", "ku", "yi", "ji", "dv", "syr", "he", "iw", "hi", "mr", "ne", "bn", "as", "sa", "gu", "pa", "or", "ta", "te", "kn", "ml", "si", "th", "lo", "km", "my", "am", "ti", "bo", "dz", "mn", "jv", "ks", "ka", "hy", "ja", "ko", "zh", "yue", "cmn"];
388
+
389
+ /**
390
+ * Tracking and line height for text in a script that tracking or a tight line
391
+ * breaks. Letter spacing, positive or negative, cuts the joins of Arabic
392
+ * script and the conjuncts of the Indic scripts, and the tall marks of Indic,
393
+ * Thai and Khmer text collide at the Latin line heights. Tracking is zero and
394
+ * every step gets a line height of 1.5 or more. A host may set these tokens;
395
+ * Latin text never reads them.
396
+ */
397
+ declare const nonLatinType: {
398
+ readonly tracking: "0em";
399
+ readonly lineHeight: {
400
+ readonly small: "1.6";
401
+ readonly body: "1.6";
402
+ readonly large: "1.6";
403
+ readonly title: "1.5";
404
+ readonly display: "1.5";
405
+ };
406
+ };
407
+
408
+ /** What a pair's foreground is: text, or a non-text mark such as an edge or ring. */
409
+ export declare type PairKind = "text" | "non-text";
410
+
411
+ /**
412
+ * Parses a hex, `rgb()`/`rgba()` or `oklch()` colour to gamma-encoded sRGB.
413
+ * Numbers and percentages are read strictly: each component must be a finite
414
+ * number or percentage, the argument count must be right, and an `oklch()`
415
+ * hue may be plain or in degrees (other angle units are refused). Components
416
+ * outside their range are clamped as CSS does. OKLCH colours that fall outside the gamut are clipped per channel; use
417
+ * {@link isInSrgbGamut} to keep tokens from relying on that.
418
+ * @throws When the string is not in a supported syntax.
419
+ */
420
+ export declare function parseColour(colour: string): Rgba;
421
+
422
+ /** Corner radii by role. */
423
+ declare const radius: {
424
+ readonly pill: "24px";
425
+ readonly sheet: "20px";
426
+ readonly control: "14px";
427
+ readonly inner: "10px";
428
+ readonly round: "50%";
429
+ };
430
+
431
+ /**
432
+ * Backdrops that surface contrast is measured over. A translucent surface
433
+ * takes on whatever map is under it, so tests composite over both extremes,
434
+ * plus the light basemaps for the things drawn on the map. Every built-in
435
+ * basemap is light; pure black stands in for any dark map a host adds.
436
+ */
437
+ declare const representativeBackdrops: {
438
+ readonly white: "#ffffff";
439
+ readonly black: "#000000";
440
+ /** Close to a light OpenStreetMap or Positron land colour. */
441
+ readonly lightMap: "#f2efe9";
442
+ /**
443
+ * The land (background layer) colour of OpenFreeMap Bright, the default
444
+ * basemap in both themes. It must equal `DEFAULT_BASEMAP_BACKGROUND` in
445
+ * `@mapcairn/core`, which this package cannot import; a test in
446
+ * `packages/web` checks that they agree.
447
+ */
448
+ readonly defaultBasemap: "#f8f4f0";
449
+ };
450
+
451
+ /**
452
+ * WCAG contrast maths with no dependencies. It parses the colour syntaxes the
453
+ * token file uses (hex, `rgb()`/`rgba()` and `oklch()`), composites alpha the
454
+ * way browsers do and computes relative luminance and contrast ratios. The
455
+ * token tests use it to enforce AA over the worst-case map backdrops.
456
+ */
457
+ /** A colour in gamma-encoded sRGB. Channels are 0 to 255, alpha is 0 to 1. */
458
+ export declare interface Rgba {
459
+ r: number;
460
+ g: number;
461
+ b: number;
462
+ a: number;
463
+ }
464
+
465
+ /** Interactive sizes and the icon system. */
466
+ declare const size: {
467
+ readonly control: "3rem";
468
+ readonly minTarget: "2.75rem";
469
+ readonly gapBetweenTargets: "0.5rem";
470
+ readonly icon: "24px";
471
+ readonly iconStroke: "1.75";
472
+ };
473
+
474
+ /** Spacing scale in pixels, plus the screen inset. */
475
+ declare const space: {
476
+ readonly xxs: "4px";
477
+ readonly xs: "8px";
478
+ readonly sm: "12px";
479
+ readonly md: "16px";
480
+ readonly lg: "24px";
481
+ readonly xl: "32px";
482
+ };
483
+
484
+ /**
485
+ * A critically damped-ish spring (damping ratio 0.72) sampled to `linear()`,
486
+ * peaking about 3.5% over. Used for the sheet only.
487
+ */
488
+ declare const spring = "linear(0, 0.229, 0.593, 0.858, 0.992, 1.035, 1.035, 1.021, 1.009, 1.002, 0.999, 0.999, 0.999, 0.999, 1, 1, 1, 1, 1)";
489
+
490
+ /**
491
+ * Surface styling for floating chrome: the translucent surface colour with
492
+ * its backdrop blur, with the `-webkit-` spelling Safari needs. Spread it
493
+ * into a vanilla-extract style.
494
+ */
495
+ export declare const surfaceBlurStyle: {
496
+ readonly backgroundColor: `var(--${string})`;
497
+ readonly backdropFilter: `var(--${string})`;
498
+ readonly WebkitBackdropFilter: `var(--${string})`;
499
+ };
500
+
501
+ /**
502
+ * The support test for `backdrop-filter` in both spellings. Surfaces are
503
+ * translucent only where this holds.
504
+ */
505
+ export declare const surfaceBlurSupported = "(backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))";
506
+
507
+ /**
508
+ * Opaque colours for the `theme-color` meta tag: the default surface
509
+ * flattened over each theme's page background, so the browser chrome keeps
510
+ * the theme's own lightness above the map and on every other page.
511
+ */
512
+ declare const themeColor: Record<ThemeName, string>;
513
+
514
+ /**
515
+ * The interface colour roles a host may override, and so the roles a
516
+ * finding's foreground can name.
517
+ */
518
+ export declare type ThemeColourRole = "surface" | "surfaceRaised" | "text" | "textMuted" | "accent" | "accentTint" | "accentContrast" | "hairline" | "controlBoundary" | "danger" | "dangerTint" | "scrim" | "focusRing" | "focusRingInner";
519
+
520
+ /**
521
+ * The interface colour roles a host may override. Page and map roles, the
522
+ * overlay roles and the data palette are not here: they carry their own
523
+ * guarantees or belong to the host.
524
+ */
525
+ export declare type ThemeColours = Record<ThemeColourRole, string>;
526
+
527
+ /** The result of {@link checkThemeContrast}. */
528
+ export declare interface ThemeContrastCheck {
529
+ /** True when nothing is invalid and every finding passes. */
530
+ passes: boolean;
531
+ /** One finding for each pair, theme and backdrop that could be checked. */
532
+ findings: ContrastFinding[];
533
+ /** What could not be checked, and why. */
534
+ invalid: InvalidColour[];
535
+ }
536
+
537
+ /** The two themes. */
538
+ export declare type ThemeName = "light" | "dark";
539
+
540
+ /** A proposed theme: some colour roles, per theme. A role left out keeps its default. */
541
+ export declare interface ThemeOverride {
542
+ /** Colour roles to change, per theme. */
543
+ colour?: {
544
+ light?: Partial<ThemeColours>;
545
+ dark?: Partial<ThemeColours>;
546
+ };
547
+ }
548
+
549
+ /** The result of {@link createThemeStylesheet}. */
550
+ export declare type ThemeStylesheet = ThemeStylesheetCreated | ThemeStylesheetRefused;
551
+
552
+ /** A theme override that was accepted: the stylesheet and what was measured. */
553
+ export declare interface ThemeStylesheetCreated {
554
+ /** True: the override passed and `css` holds the stylesheet. */
555
+ ok: true;
556
+ /**
557
+ * The stylesheet text, to serve as a same-origin file. It is empty when the
558
+ * override sets no colour.
559
+ */
560
+ css: string;
561
+ /**
562
+ * One finding for each pair, theme and backdrop, measured on the colours
563
+ * written to `css` with the surface as written (translucent). Every one
564
+ * passes. The opaque surfaces written for reduced transparency are checked
565
+ * as well, and a failure there refuses the theme, so no finding for them is
566
+ * listed here.
567
+ */
568
+ findings: ContrastFinding[];
569
+ }
570
+
571
+ /** Where a theme override applies. */
572
+ export declare interface ThemeStylesheetOptions {
573
+ /**
574
+ * The selector of the element that wraps the SDK's interface, written as
575
+ * `:root`, `#id` or `.class` with an ASCII name. It must be an element the
576
+ * host owns and puts around the map: the SDK adds no markup or attribute of
577
+ * its own for this. The page's theme is read from `data-theme` on the root
578
+ * element, which is where the SDK sets it, so a theme change reaches the
579
+ * scope without any script.
580
+ *
581
+ * A `#id` or `.class` scope is matched as a descendant of `:root`, so a class
582
+ * on `<html>` itself does nothing: use `:root` to theme the whole page.
583
+ *
584
+ * Two maps on one page take two scopes and two calls.
585
+ */
586
+ scope: string;
587
+ }
588
+
589
+ /** A theme override that was refused, with the reasons and no stylesheet. */
590
+ export declare interface ThemeStylesheetRefused {
591
+ /** False: nothing was written. */
592
+ ok: false;
593
+ /** Always `undefined`: a refused theme produces no CSS. */
594
+ css: undefined;
595
+ /**
596
+ * The pairs that could be measured, passing and failing. Where a colour
597
+ * or the scope could not be used, the pairs that depend on a colour are
598
+ * missing, as in {@link checkThemeContrast}.
599
+ */
600
+ findings: ContrastFinding[];
601
+ /** The colours and keys that could not be used, and why. */
602
+ invalid: InvalidColour[];
603
+ /** True when `scope` is not `:root`, `#id` or `.class`, or could not be read. */
604
+ invalidScope: boolean;
605
+ }
606
+
607
+ /** Everything that differs between light and dark. */
608
+ declare interface ThemeValues {
609
+ /** Default colours. Surfaces are translucent and sit behind a backdrop blur. */
610
+ colour: ColourRoles;
611
+ /**
612
+ * The same roles with opaque surfaces. Used where `backdrop-filter` is not
613
+ * supported and under `prefers-reduced-transparency`.
614
+ */
615
+ opaque: ColourRoles;
616
+ /**
617
+ * `prefers-contrast: more`: opaque surfaces, muted text and hairlines raised
618
+ * to at least 4.5:1 and 3:1. Fully merged so tests can treat every set alike.
619
+ */
620
+ contrastMore: ColourRoles;
621
+ /** The two elevation shadows. Dark values are stronger and add a faint top highlight. */
622
+ shadow: {
623
+ floating: string;
624
+ sheet: string;
625
+ };
626
+ }
627
+
628
+ /** Light and dark values for every themed token. */
629
+ declare const themeValues: Record<ThemeName, ThemeValues>;
630
+
631
+ /** Formats a colour as `#rrggbb`, or `#rrggbbaa` when it is translucent. */
632
+ export declare function toHex(colour: Rgba): string;
633
+
634
+ /**
635
+ * The whole token contract: every custom property that components may read.
636
+ * Colours, shadows and the blur change with the theme; everything else is
637
+ * assigned once on `:root`.
638
+ *
639
+ * Components use these references in vanilla-extract styles, so a typo is a
640
+ * type error rather than a silently missing variable.
641
+ */
642
+ export declare const tokens: {
643
+ color: {
644
+ surface: `var(--${string})`;
645
+ surfaceRaised: `var(--${string})`;
646
+ text: `var(--${string})`;
647
+ textMuted: `var(--${string})`;
648
+ accent: `var(--${string})`;
649
+ accentTint: `var(--${string})`;
650
+ accentContrast: `var(--${string})`;
651
+ hairline: `var(--${string})`;
652
+ controlBoundary: `var(--${string})`;
653
+ chromeBorder: `var(--${string})`;
654
+ danger: `var(--${string})`;
655
+ dangerTint: `var(--${string})`;
656
+ scrim: `var(--${string})`;
657
+ focusRing: `var(--${string})`;
658
+ focusRingInner: `var(--${string})`;
659
+ pageBackground: `var(--${string})`;
660
+ mapBackground: `var(--${string})`;
661
+ mapGlobeSpace: `var(--${string})`;
662
+ mapPin: `var(--${string})`;
663
+ mapMeasureLine: `var(--${string})`;
664
+ mapMeasureFill: `var(--${string})`;
665
+ mapAccuracy: `var(--${string})`;
666
+ mapAccuracyFill: `var(--${string})`;
667
+ mapHalo: `var(--${string})`;
668
+ };
669
+ shadow: {
670
+ floating: `var(--${string})`;
671
+ sheet: `var(--${string})`;
672
+ };
673
+ effect: {
674
+ blur: `var(--${string})`;
675
+ };
676
+ space: {
677
+ xxs: `var(--${string})`;
678
+ xs: `var(--${string})`;
679
+ sm: `var(--${string})`;
680
+ md: `var(--${string})`;
681
+ lg: `var(--${string})`;
682
+ xl: `var(--${string})`;
683
+ inset: `var(--${string})`;
684
+ };
685
+ radius: {
686
+ pill: `var(--${string})`;
687
+ sheet: `var(--${string})`;
688
+ control: `var(--${string})`;
689
+ inner: `var(--${string})`;
690
+ round: `var(--${string})`;
691
+ };
692
+ type: {
693
+ family: `var(--${string})`;
694
+ familyMono: `var(--${string})`;
695
+ weight: {
696
+ regular: `var(--${string})`;
697
+ semibold: `var(--${string})`;
698
+ };
699
+ small: {
700
+ size: `var(--${string})`;
701
+ lineHeight: `var(--${string})`;
702
+ tracking: `var(--${string})`;
703
+ };
704
+ body: {
705
+ size: `var(--${string})`;
706
+ lineHeight: `var(--${string})`;
707
+ tracking: `var(--${string})`;
708
+ };
709
+ large: {
710
+ size: `var(--${string})`;
711
+ lineHeight: `var(--${string})`;
712
+ tracking: `var(--${string})`;
713
+ };
714
+ title: {
715
+ size: `var(--${string})`;
716
+ lineHeight: `var(--${string})`;
717
+ tracking: `var(--${string})`;
718
+ };
719
+ display: {
720
+ size: `var(--${string})`;
721
+ lineHeight: `var(--${string})`;
722
+ tracking: `var(--${string})`;
723
+ };
724
+ nonLatin: {
725
+ tracking: `var(--${string})`;
726
+ lineHeight: {
727
+ small: `var(--${string})`;
728
+ body: `var(--${string})`;
729
+ large: `var(--${string})`;
730
+ title: `var(--${string})`;
731
+ display: `var(--${string})`;
732
+ };
733
+ };
734
+ };
735
+ size: {
736
+ control: `var(--${string})`;
737
+ minTarget: `var(--${string})`;
738
+ gapBetweenTargets: `var(--${string})`;
739
+ icon: `var(--${string})`;
740
+ iconStroke: `var(--${string})`;
741
+ };
742
+ focus: {
743
+ innerWidth: `var(--${string})`;
744
+ outerWidth: `var(--${string})`;
745
+ };
746
+ motion: {
747
+ duration: {
748
+ fast: `var(--${string})`;
749
+ base: `var(--${string})`;
750
+ slow: `var(--${string})`;
751
+ };
752
+ easing: `var(--${string})`;
753
+ spring: `var(--${string})`;
754
+ };
755
+ z: {
756
+ map: `var(--${string})`;
757
+ mapOverlay: `var(--${string})`;
758
+ chrome: `var(--${string})`;
759
+ chromeRaised: `var(--${string})`;
760
+ sheet: `var(--${string})`;
761
+ toolbar: `var(--${string})`;
762
+ popover: `var(--${string})`;
763
+ toast: `var(--${string})`;
764
+ };
765
+ };
766
+
767
+ export declare namespace tokenValues {
768
+ export {
769
+ neutral,
770
+ accent,
771
+ dataPalette,
772
+ dataMarker,
773
+ representativeBackdrops,
774
+ ColourRoles,
775
+ colourRoleNames,
776
+ ThemeName,
777
+ ThemeValues,
778
+ themeValues,
779
+ forcedColors,
780
+ themeColor,
781
+ blurValue,
782
+ space,
783
+ inset,
784
+ radius,
785
+ typeScale,
786
+ nonLatinType,
787
+ nonLatinLanguages,
788
+ fontWeight,
789
+ fontFamily,
790
+ fontFamilyMono,
791
+ size,
792
+ focusWidth,
793
+ focusWidthContrastMore,
794
+ spring,
795
+ motion,
796
+ ZLayerName,
797
+ zIndex,
798
+ zLayerOrder
799
+ }
800
+ }
801
+
802
+ /**
803
+ * Type scale. Sizes are in rem so they follow the user's font size; line
804
+ * height is unitless and tracking is in em. Only weights 400 and 600 exist.
805
+ */
806
+ declare const typeScale: {
807
+ readonly small: {
808
+ readonly size: "0.8125rem";
809
+ readonly lineHeight: "1.4";
810
+ readonly tracking: "0.01em";
811
+ };
812
+ readonly body: {
813
+ readonly size: "0.9375rem";
814
+ readonly lineHeight: "1.45";
815
+ readonly tracking: "0em";
816
+ };
817
+ readonly large: {
818
+ readonly size: "1.0625rem";
819
+ readonly lineHeight: "1.4";
820
+ readonly tracking: "-0.005em";
821
+ };
822
+ readonly title: {
823
+ readonly size: "1.375rem";
824
+ readonly lineHeight: "1.25";
825
+ readonly tracking: "-0.015em";
826
+ };
827
+ /**
828
+ * The one display size, for the heading of a full page that is not the map
829
+ * (the reference host's product page). The map's chrome never uses it.
830
+ */
831
+ readonly display: {
832
+ readonly size: "2.5rem";
833
+ readonly lineHeight: "1.1";
834
+ readonly tracking: "-0.025em";
835
+ };
836
+ };
837
+
838
+ /** Z layers from bottom to top, with room between for local adjustments. */
839
+ declare const zIndex: {
840
+ readonly map: "0";
841
+ readonly mapOverlay: "10";
842
+ readonly chrome: "20";
843
+ readonly chromeRaised: "30";
844
+ readonly sheet: "40";
845
+ readonly toolbar: "50";
846
+ readonly popover: "60";
847
+ readonly toast: "70";
848
+ };
849
+
850
+ /**
851
+ * The z-index variable for a named layer, bottom to top: map, mapOverlay,
852
+ * chrome, chromeRaised, sheet, toolbar, popover, toast. Components name a
853
+ * layer and never write a number; `tokens.css.ts` and the engine style file
854
+ * are the only places raw z-index values may appear.
855
+ * @remarks Lives outside `tokens.css.ts` because a `.css.ts` module may only
856
+ * export serialisable values, not functions.
857
+ */
858
+ export declare function zLayer(name: ZLayerName): string;
859
+
860
+ /** Name of a z layer. */
861
+ export declare type ZLayerName = "map" | "mapOverlay" | "chrome" | "chromeRaised" | "sheet" | "toolbar" | "popover" | "toast";
862
+
863
+ /** Z layer names in stacking order, bottom to top. */
864
+ declare const zLayerOrder: readonly ["map", "mapOverlay", "chrome", "chromeRaised", "sheet", "toolbar", "popover", "toast"];
865
+
866
+ export { }