@unmap/themes 0.0.1 → 0.1.2
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.
- package/README.md +59 -0
- package/dist/index.d.ts +1 -1
- package/package.json +21 -1
package/README.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# @unmap/themes
|
|
2
|
+
|
|
3
|
+
The data model behind custom [unmap](https://unmap.dev) map themes: the `ThemeDoc` document,
|
|
4
|
+
its compact `ut1.` code, the validator, and the composer the gateway uses to turn a theme into
|
|
5
|
+
cartography. A theme is data only, colours, bounded numbers and one enum, so it is safe to carry
|
|
6
|
+
on a public URL.
|
|
7
|
+
|
|
8
|
+
Most applications never import this package. Design a theme at
|
|
9
|
+
[unmap.dev/create](https://unmap.dev/create), copy the code, and pass it as `theme` to
|
|
10
|
+
`@unmap/sdk`, `@unmap/maps`, or a style URL. Install this when you generate or validate theme
|
|
11
|
+
codes yourself.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm i @unmap/themes
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { encodeTheme, decodeTheme, validateTheme, ThemeError } from '@unmap/themes'
|
|
19
|
+
|
|
20
|
+
const code = await encodeTheme({
|
|
21
|
+
v: 1,
|
|
22
|
+
name: 'copper',
|
|
23
|
+
base: 'street', // base | muted | relief | street | outdoor
|
|
24
|
+
light: { basemap: { water: '#9CCFD2' }, route: { color: '#B85C00', width: 4 } },
|
|
25
|
+
dark: { basemap: { water: '#12303A' }, route: { color: '#FFA24D', width: 4 } },
|
|
26
|
+
})
|
|
27
|
+
// 'ut1.eJy…' — pass as `theme` to new Unmap({ ... }) or ?theme= on a style URL
|
|
28
|
+
|
|
29
|
+
const doc = await decodeTheme(code) // validated ThemeDoc, or throws ThemeError
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## What is in a theme
|
|
33
|
+
|
|
34
|
+
- `base` picks the chassis: one of the five shipped styles. Each of `light` and `dark` carries
|
|
35
|
+
sparse overrides on that chassis, so a theme with no overrides renders exactly like its
|
|
36
|
+
`flavor=` twin.
|
|
37
|
+
- `basemap` overrides are colours on the chassis recipe (land, water, vegetation, roads, labels,
|
|
38
|
+
points of interest, landcover). `marker` styles the geocoding pin (`color`, `scale` 0.5 to 2).
|
|
39
|
+
`route` styles the routing line (`color`, `width` 1 to 12, `opacity`, and a casing).
|
|
40
|
+
- Colours are `#RRGGBB` or `#RRGGBBAA`. Unknown fields, URLs, and expressions are rejected: a
|
|
41
|
+
theme can never point a map at another host.
|
|
42
|
+
|
|
43
|
+
## Exports
|
|
44
|
+
|
|
45
|
+
- `encodeTheme(doc)` and `decodeTheme(code)`: async, validate on both sides, throw `ThemeError`
|
|
46
|
+
with a `detail` array naming each problem. Codes are at most 4096 characters.
|
|
47
|
+
- `validateTheme(input)`: the synchronous validator, returns a typed `ThemeDoc`.
|
|
48
|
+
- `resolveTheme(doc, mode)`: what the gateway calls. Returns the chassis flavor name, the
|
|
49
|
+
composed colour flavor, and the resolved `marker` and `route` styles with defaults filled in.
|
|
50
|
+
- `PRESET_THEMES`: the five shipped styles as zero-override documents.
|
|
51
|
+
- `generateTheme(base, seeds)` and `contrastWarnings(doc)`: the pieces the builder uses to
|
|
52
|
+
derive a coherent light and dark pair from a few seed colours, and to flag label contrast
|
|
53
|
+
below 4.5:1 and 3:1.
|
|
54
|
+
- `RECIPES`, `makeFlavor`, `THEME_BASES`, `MODES`: the shipped cartography the gateway and the
|
|
55
|
+
themes are both built from.
|
|
56
|
+
|
|
57
|
+
Runs in browsers, Cloudflare Workers, and Node 18 or later (it uses the web `CompressionStream`).
|
|
58
|
+
Docs: [unmap.dev/docs/tiles-and-styles](https://unmap.dev/docs/tiles-and-styles) covers the
|
|
59
|
+
`?theme=` parameter and the `invalid_theme` error.
|
package/dist/index.d.ts
CHANGED
|
@@ -224,7 +224,7 @@ declare const RECIPES: Record<ThemeBase, Record<ThemeMode, Recipe>>;
|
|
|
224
224
|
* arrive on public query strings and are composed into style JSON the gateway signs its own
|
|
225
225
|
* asset URLs into. `validateTheme` is the only door in.
|
|
226
226
|
*
|
|
227
|
-
* `base` names the structural chassis (one of the
|
|
227
|
+
* `base` names the structural chassis (one of the five shipped styles); each half carries only
|
|
228
228
|
* sparse overrides on that chassis, so presets are near-empty documents and codes stay short.
|
|
229
229
|
*/
|
|
230
230
|
type DeepPartial<T> = {
|
package/package.json
CHANGED
|
@@ -1,7 +1,24 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@unmap/themes",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "unmap theme documents: types, recipes, validation, codec (data-only map themes)",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"unmap",
|
|
7
|
+
"maps",
|
|
8
|
+
"canada",
|
|
9
|
+
"maplibre",
|
|
10
|
+
"theme",
|
|
11
|
+
"cartography"
|
|
12
|
+
],
|
|
13
|
+
"homepage": "https://unmap.dev/create",
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "git+https://github.com/unmap-dev/unmap.git",
|
|
17
|
+
"directory": "packages/themes"
|
|
18
|
+
},
|
|
19
|
+
"bugs": {
|
|
20
|
+
"url": "https://github.com/unmap-dev/unmap/issues"
|
|
21
|
+
},
|
|
5
22
|
"type": "module",
|
|
6
23
|
"main": "./dist/index.js",
|
|
7
24
|
"module": "./dist/index.js",
|
|
@@ -27,6 +44,9 @@
|
|
|
27
44
|
"typescript": "^5.6.0",
|
|
28
45
|
"vitest": "^2.1.0"
|
|
29
46
|
},
|
|
47
|
+
"engines": {
|
|
48
|
+
"node": ">=18"
|
|
49
|
+
},
|
|
30
50
|
"scripts": {
|
|
31
51
|
"build": "tsup",
|
|
32
52
|
"test": "vitest run",
|