@tileflow/core 0.1.0-alpha.0 → 0.1.0-alpha.10

package/OSM_BRIGHT_LICENSE.md

@@ -0,0 +1,62 @@
+Copyright (c) 2024, MapTiler.com & OpenMapTiles contributors.
+Copyright (c) 2014, Mapbox.
+All rights reserved.
+
+Modifications by MapTiler.com & OpenMapTiles contributors.
+Derived from "Mapbox Open Styles" https://github.com/mapbox/mapbox-gl-styles
+
+# Code license: BSD 3-Clause License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+# Design license: CC-BY 4.0
+
+The visual design features of the style (also known as the "look and feel" of
+the map) are licensed under the Creative Commons Attribution 4.0 license.
+
+To view a copy of the license, visit https://creativecommons.org/licenses/by/4.0/.
+
+Attribution for the design defined in this repository needs not to be provided
+on map images, but should be reasonably accessible from maps based on this style
+(for example, in a webpage linked from copyright notice on the map).
+
+Products or services using maps derived from OpenMapTiles schema need to visibly
+credit "OpenMapTiles.org" or reference "OpenMapTiles" with a link to
+https://openmaptiles.org/.
+
+For a browsable electronic map based on OpenMapTiles and OpenStreetMap data, the
+credit should appear in the corner of the map. For example:
+
+[© OpenMapTiles](https://openmaptiles.org/)
+[© OpenStreetMap contributors](https://www.openstreetmap.org/copyright)
+
+For printed and static maps a similar attribution should be made in a textual
+description near the image, in the same fashion as if you cite a photograph.
+
+Exceptions to OpenMapTiles attribution requirement can be in a written form granted
+by MapTiler AG (info@maptiler.com).
+The project contributors grant MapTiler AG the license to give such
+exceptions on a commercial basis.

package/README.md

@@ -3,23 +3,134 @@
 Typed Tileflow config helpers and the MapLibre style compiler.
 
 ```ts
-import { defineTileflow } from "@tileflow/core";
+import {defineTileflow, labels, osm, poi} from '@tileflow/core';
 
 export default defineTileflow({
+  icons: {
+    brand: {
+      sprite: 'https://cdn.example.com/tileflow/brand/sprite',
+    },
+  },
+  themes: {
+    light: {
+      colors: {
+        background: '#F8F7F7',
+        land: '#F4F2ED',
+        water: '#8ED6E8',
+        park: '#C3F1D5',
+        building: '#EEF0F2',
+        road: '#FFFFFF',
+        roadMajor: '#F5D58A',
+        roadCasing: '#DDE0E3',
+        boundary: '#C9CED3',
+        text: '#566371',
+        textMuted: '#8A98A8',
+        textHalo: '#FFFFFF',
+      },
+      modules: {
+        labels: {
+          road: '#7A8794',
+          water: '#4B8FA8',
+        },
+        poi: {
+          food: '#D97706',
+          transit: '#2563EB',
+        },
+        roads: {
+          motorway: '#F7C56F',
+        },
+      },
+      typography: {
+        font: 'Inter',
+      },
+    },
+  },
   maps: {
     madrid: {
-      colors: {
-        canvas: "#F8F6F1",
-        land: "#F2EEE6",
-        water: "#B6CBD8",
-        nature: "#AEBB9B",
-        road: "#DED6C8",
-        text: "#2E2E2E",
-        accent: "#C6A15B",
+      basemap: osm(),
+      icons: 'brand',
+      theme: 'light',
+      modules: [
+        labels({roads: 'minimal'}),
+        poi({categories: ['food', 'coffee', 'culture', 'transit'], icons: 'essential'}),
+      ],
+      layers: {
+        'highway-primary': {
+          paint: {
+            'line-opacity': 0.9,
+          },
+        },
+      },
+      view: {
+        center: [-3.7038, 40.4168],
+        zoom: 12,
       },
     },
   },
 });
 ```
 
+## Style contract
+
+Tileflow keeps these levels separate:
+
+- `basemap: osm()` chooses the source defaults, glyphs, sprites, and OSM Bright layer template.
+- `theme.colors` contains human-scale base tokens such as `water`, `park`, `road`, `roadMajor`, `roadCasing`, `text`, and `textHalo`.
+- `theme.modules.<name>` contains advanced, module-specific tokens. These are granular: setting `theme.modules.roads.rail` does not recolor primary roads.
+- `maps.<name>.icons` can point at a reusable root icon set, a hosted MapLibre sprite URL, or a local icon folder for Vite/build output.
+- `maps.<name>.modules` enables semantic behavior such as `labels()`, `poi()`, and `roads()`. Road colors remain in `theme.modules.roads`; `roads()` controls detail, hierarchy, weight, casing, and optional transport extras.
+- `maps.<name>.renderer` can be `auto`, `osm-bright`, or `generated`. `auto` preserves the default template when compatible; `generated` always uses Tileflow's generated layers; `osm-bright` throws if the map config cannot be rendered with the template.
+- `layers` is the raw MapLibre escape hatch for exact layer patches.
+
+Missing colors preserve the basemap default. Legacy aliases such as `accent`, `canvas`, `greenspace`, `fontFamily`, and `fonts` are accepted for compatibility but are not the recommended API.
+
+## Roads module
+
+Use a preset for the overall road-network intent, then override only the behavior you need:
+
+```ts
+roads({
+  preset: 'navigation',
+  detail: 'streets',
+  hierarchy: 'strong',
+  weight: 'regular',
+  casing: 'strong',
+  extras: {
+    paths: false,
+    rail: false,
+    ferry: false,
+  },
+});
+```
+
+| Preset       | Detail    | Hierarchy | Weight    | Casing   | Extras  |
+| ------------ | --------- | --------- | --------- | -------- | ------- |
+| `minimal`    | `streets` | `subtle`  | `thin`    | `subtle` | all off |
+| `standard`   | `streets` | `clear`   | `regular` | `subtle` | all on  |
+| `navigation` | `streets` | `strong`  | `regular` | `strong` | all off |
+| `detailed`   | `all`     | `clear`   | `regular` | `strong` | all on  |
+
+`detail` accepts `none`, `major`, `streets`, or `all`; `hierarchy` accepts `subtle`, `clear`, or `strong`; `weight` accepts `thin`, `regular`, or `bold`; and `casing` accepts `none`, `subtle`, or `strong`. Explicit options override their preset. `extras.paths`, `extras.rail`, and `extras.ferry` are independent.
+
+Colors never belong in `roads()`. Put common colors in `theme.colors` and granular road colors in `theme.modules.roads`. Road-label density remains a `labels({roads: ...})` concern.
+
+## Public API
+
+Use the package root only:
+
+```ts
+import {
+  createStyle,
+  defineTileflow,
+  labels,
+  osm,
+  poi,
+  roads,
+  styleOverride,
+  validateConfig,
+} from '@tileflow/core';
+```
+
+Subpaths under `src/`, `themes/`, `templates/`, and `modules/` are internal implementation details and can change during alpha releases.
+
 Docs: https://tileflow.dev/docs