@mapsight/traffic-style 5.0.5 → 5.1.0

package/README.md

@@ -1,48 +1,155 @@
 # @mapsight/traffic-style
 
-For SCSS/CSS syntax and semantics, see @mapsight/vector-style-compiler.
+> **Package:** `@mapsight/traffic-style` · **Hub:** [Documentation index](https://github.com/open-mapsight/mapsight/blob/main/docs/README.md)
 
-## Style function (SCSS/JS)
+Default **icons** and **vector map styles** for [Mapsight](https://github.com/open-mapsight/mapsight) —
+an OpenLayers + React framework.
 
-You have basically four options to include this in your project:
+**Mapsight vector style** is the styling syntax (a CSS subset compiled to
+OpenLayers style functions — see
+[`@mapsight/vector-style-compiler`](https://github.com/open-mapsight/mapsight/tree/main/packages/vector-style-compiler)).
+**Traffic-style** is one opinionated but flexible base implementation: good defaults
+for city maps and traffic applications (hence the name), and equally usable as a
+starting point you can trim or extend. It covers feature selection and highlight
+states, clustering, lines, dynamic parking indications, POI icons, labels, and more.
 
-1. Use `import '@mapsight/traffic-style/default'` which is the precompiled map style
-2. Compile a style yourself from SCSS using `@mapsight/vector-style-compiler`
-    - `_full.scss` is the complete style (like `default`)
-    - `_base.scss` is a base selection of styles
-3. Compile a style yourself from SCSS using `@mapsight/vector-style-compiler`
-    - using only parts of `src/scss/*`
+### How it fits together
 
-## Icons (SCSS/PNG)
+Pass a compiled `styleFunction` into
+[`@mapsight/ui`](https://github.com/open-mapsight/mapsight/tree/main/packages/ui)
+(or `@mapsight/core`). The function is produced by `vector-style-compiler` and
+wraps [`createCachedStyleFunction`](https://github.com/open-mapsight/mapsight/tree/main/packages/lib-ol)
+from `@mapsight/lib-ol` — a 3-level LRU cache keyed on env, feature props,
+geometry, and volatile values (e.g. async runtime icons).
 
-You have basically two options to include this in your project:
+Vector layers select which rules apply through **layer styles** and **env**. Each
+layer's `style` option is a style name (string) or a `MapsightStyleFunctionEnv`
+object, merged with map state (zoom, etc.) on every render:
 
-1. use the icon sprites described in `mapsight-traffic-style-icon-sprite-1x.scss` and `mapsight-traffic-style-icon-sprite-2x.scss` and
-   the corresponding sprite images at `img/mapsight-traffic-style-icon-sprite-1x.png` and `img/mapsight-traffic-style-icon-sprite-2x.png` (which are already optimized)
-2. use the separate icon images in `img/mapsight-icons/*.png`, `img/mapsight-icons-2x/*.png` and `img/mapsight-icons/*.svg` (which are also already optimized)
+```ts
+import styleFunction from "@mapsight/traffic-style/default";
+import {create} from "@mapsight/ui";
 
-# Development
+create(container, styleFunction, {
+	/* layers, controllers, … */
+});
 
-## How to add a new icon
+// Style name → matches #features in the compiled style
+features("hotels", true, true, meta, "features");
 
-1. Add **vector based** Icon symbol to `docs/icons.sketch` file and export the symbols (see others for reference)
-2. Add SVGs (at least `-default.svg` and `-plain.svg`, optionally `-small.svg` and `-xsmall.svg`) to `img/mapsight-icons-svg/`
-3. Add 1x PNGs (at least `-default.png` and `-plain.png`, optionally `-small.png` and `-xsmall.png`) to `img/mapsight-icons/`
-4. Add 2x PNGs (at least `-default.png` and `-plain.png`, optionally `-small.png` and `-xsmall.png`) to `img/mapsight-icons-2x/`
-5. Describe new icon in `src/meta.json`
-6. Optionally add them to the fallback map in `src/scss/_variables.scss`
-7. Search and replace cache busting strings in `src/scss/**` in the format `?v=xxxx-xx-xx-xx-xx` TODO: Automate or at least centralize in one file!
-8. Build everything using `pnpm run clean-build`
+// Style env → overrides env fields used in selectors like [env|mapsightIconId]
+features("hotels", true, true, meta, {
+	style: "features",
+	mapsightIconId: "hotel",
+});
+```
+
+Feature properties (`mapsightIconId`, `state`, …) and env fields drive which rules
+match. Selection, clustering, zoom-dependent icons, and runtime pictograms all
+flow through this pipeline.
+
+### Related packages
+
+| Package                                                                                                                 | Role                                                     |
+| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| [`@mapsight/ui`](https://github.com/open-mapsight/mapsight/tree/main/packages/ui)                                       | React UI, map config, layer helpers, runtime icon plugin |
+| [`@mapsight/core`](https://github.com/open-mapsight/mapsight/tree/main/packages/core)                                   | Redux store, map controller, `setStyleFunction`          |
+| [`@mapsight/vector-style-compiler`](https://github.com/open-mapsight/mapsight/tree/main/packages/vector-style-compiler) | Vector-style syntax → compiled `styleFunction`           |
+| [`@mapsight/lib-ol`](https://github.com/open-mapsight/mapsight/tree/main/packages/lib-ol)                               | `createCachedStyleFunction`, style env types, OL helpers |
+
+## Quick start with `@mapsight/ui`
+
+Import the precompiled default style and pass it to `create()`:
+
+```ts
+import styleFunction from "@mapsight/traffic-style/default";
+import {create} from "@mapsight/ui";
+
+create(container, styleFunction, baseMapsightConfig);
+```
+
+Icons work out of the box: set `mapsightIconId` on features (or per-layer via
+style env as above). `@mapsight/ui` browser defaults include the runtime icon
+plugin; feature lists use `useMapsightIcon` automatically.
+
+```json
+{ "mapsightIconId": "museum" }
+{ "mapsightIconId": "museum/#be123c" }
+```
+
+Optional Font Awesome pictograms (`fa-*` ids):
+
+```ts
+import "@mapsight/traffic-style/pictograms-fontawesome";
+```
 
-## How to publish
+Need different colors, zoom thresholds, or style partials? See
+[Customize the style](#customize-the-style) below.
 
-- Publish:
+Not using `@mapsight/ui`? See [ICON_INTEGRATION.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/ICON_INTEGRATION.md).
 
+## Customize the style
+
+When the precompiled `default` export is not enough, compile your own entry from
+traffic-style SCSS sources with `vector-style-compiler`:
+
+```json
+{
+	"scripts": {
+		"build:mapsightStyle": "vector-style-compiler src/vector-styles/app.scss --output src/generated/mapsight-vector-styles --name app"
+	}
+}
+```
+
+```ts
+import styleFunction from "@/generated/mapsight-vector-styles/app";
 ```
-git status
-git commit
-pnpm version x.x.x|major|minor|patch
-pnpm run publish
-git push
-git push --tags
+
+Tune the style through Sass module variables (`$MAPSIGHT_TRAFFIC_STYLE__…` in
+`src/scss/_variables.scss`) and pick entry partials (`base`, `full`, or
+individual `features/*`). Configure variables **before** loading any traffic-style
+partial — the first `@use` of `variables` applies to the whole compilation.
+
+```scss
+@use "@mapsight/traffic-style/src/scss/icons-2x" with (
+	$MAPSIGHT_TRAFFIC_STYLE__SPRITE_PATH:
+		"/img/mapsight-traffic-style-icon-sprite-2x.png?v=2026-01-01"
+);
+
+@use "@mapsight/traffic-style/src/scss/full";
+
+// App-specific rules on top
+#features [type="myLayer"] {
+	stroke-color: #467aff;
+}
 ```
+
+Full variable reference, manual sprite wiring, and partial composition:
+[docs/CUSTOMIZING_SCSS.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/CUSTOMIZING_SCSS.md).
+
+## Icon assets
+
+The package ships ready-to-use sprites and individual PNG/SVG files under `img/`.
+You can also **subset**, **extend**, or **replace** icons for your app:
+
+| Goal                         | Approach                                                                                                                                                       |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Use defaults as-is           | Sprite SCSS + PNG, or individual files under `img/`                                                                                                            |
+| Smaller deploy               | Subset sprites/composable icons at build time (`traffic-icon-sprite`, `traffic-composable-icons`)                                                              |
+| Custom sprite tiles          | `traffic-icon-sprite --overrides ./my-icons/` — swap or add PNGs, regenerate sprite SCSS                                                                       |
+| Custom composable pictograms | `registerPictograms` from `@mapsight/traffic-style/pictograms`, or pre-bake with `traffic-composable-icons` + custom `meta.json`                               |
+| Contribute to the catalog    | Add pictograms/sprites to this package — [docs/DEVELOPMENT.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/DEVELOPMENT.md) |
+
+Details and CLI examples: [docs/CUSTOM_ICON_BUILDS.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/CUSTOM_ICON_BUILDS.md).
+Catalog concepts (sprite vs composable, pictogram packs): [docs/ICON_CATALOG.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/ICON_CATALOG.md).
+
+## Documentation
+
+| Doc                                                                                                                                 | What you'll find                                                      |
+| ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [docs/CUSTOMIZING_SCSS.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/CUSTOMIZING_SCSS.md)     | Customize the style — variables, module patterns, partial composition |
+| [docs/ICON_INTEGRATION.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/ICON_INTEGRATION.md)     | Icons without `@mapsight/ui` (direct runtime API)                     |
+| [docs/RUNTIME_ICONS.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/RUNTIME_ICONS.md)           | Runtime icon architecture, caching, compiler integration              |
+| [docs/ICON_CATALOG.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/ICON_CATALOG.md)             | Sprite vs composable, `meta.json`, pictogram packs                    |
+| [docs/CUSTOM_ICON_BUILDS.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/CUSTOM_ICON_BUILDS.md) | `traffic-icon-sprite` and `traffic-composable-icons` CLIs             |
+| [docs/DEVELOPMENT.md](https://github.com/open-mapsight/mapsight/blob/main/packages/traffic-style/docs/DEVELOPMENT.md)               | Contributing: tests, new icons, publishing                            |