stipple-maplibre 0.1.1 → 0.3.0

package/README.md

@@ -8,9 +8,10 @@ It supports geometric patterns, repeated text, and SVG symbols. Patterns can
 be configured in JavaScript or prepared in the playground and exported as
 MapLibre code.
 
-<p align="center"><strong><a href="https://stipple.pages.dev/">Run the playground</a></strong></p>
+<img width="1456" alt="Stipple playground showing pattern customization on a MapLibre map" src="./assets/readme/playground.png" />
+
+<p align="center"><strong><a href="https://stipple.pages.dev/">➞ Run the playground</a></strong></p>
 
-<img width="1456" height="858" alt="Stipple playground showing a patterned polygon on a MapLibre map" src="https://github.com/user-attachments/assets/f7d28a0f-267a-4bd3-b7a2-30b49eabf709" />
 
 ## What problem does it solve?
 
@@ -20,8 +21,7 @@ map, and kept at an appropriate resolution when the display or style changes.
 
 Stipple generates this image from a small set of pattern parameters. It draws
 the tile in the browser, installs it with MapLibre's public `addImage` API,
-and provides the corresponding `fill-pattern` value. It does not patch or
-fork MapLibre.
+and provides the corresponding `fill-pattern` value.
 
 ## What can I make with it?
 
@@ -30,6 +30,47 @@ fork MapLibre.
 - SVG fills: repeat one of the bundled symbols or bring your own SVG.
 - A background colour and polygon outline to go with the pattern.
 
+### Examples
+
+<table>
+  <tr>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-solid.png" alt="Polygon with a solid fill" width="100%"><br>
+      <sub><em>Solid</em></sub>
+    </td>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-stipple.png" alt="Polygon filled with a stipple pattern" width="100%"><br>
+      <sub><em>Stipple</em></sub>
+    </td>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-hatches.png" alt="Polygon filled with diagonal hatches" width="100%"><br>
+      <sub><em>Hatches</em></sub>
+    </td>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-dots.png" alt="Polygon filled with a regular dot pattern" width="100%"><br>
+      <sub><em>Dots</em></sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-grid.png" alt="Polygon filled with a grid pattern" width="100%"><br>
+      <sub><em>Grid</em></sub>
+    </td>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-font-fill.png" alt="Polygon filled with repeated text" width="100%"><br>
+      <sub><em>Font fill</em></sub>
+    </td>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-svg-symbol.png" alt="Polygon filled with a bundled SVG motif" width="100%"><br>
+      <sub><em>SVG fill</em></sub>
+    </td>
+    <td align="center" width="25%">
+      <img src="./assets/readme/example-custom-svg.png" alt="Polygon filled with a custom SVG motif" width="100%"><br>
+      <sub><em>Custom</em></sub>
+    </td>
+  </tr>
+</table>
+
 You can change the colour, opacity, spacing, weight, angle, scale, and layout.
 Font fills also let you choose the typeface, style, and letter spacing. SVG
 fills can use regular rows, offset rows, or a more natural-looking seeded
@@ -39,7 +80,6 @@ The playground includes 34 SVG motifs covering vegetation, trees,
 agriculture, water, terrain, land use, and simple shapes. The same seed always
 produces the same arrangement.
 
-<!-- Add a small gallery here: geometric, font, SVG, and custom SVG. -->
 
 ## But can’t I just ask AI to do this?
 
@@ -64,16 +104,17 @@ locally in the browser and are not uploaded to a server.
 
 ### Run it locally
 
-To work from the source repository, install the dependencies and build the
-library:
+From a clone of this repository, install the development dependencies and
+build Stipple:
 
 ```sh
 npm install
 npm run build
 ```
 
-Then open the local [`demo/index.html`](./demo/index.html) file in your
-browser.
+The repository itself is the `stipple-maplibre` package, so you do not need to
+install it separately. Then open the local
+[`demo/index.html`](./demo/index.html) file in your browser.
 
 ## Supported file formats
 
@@ -117,7 +158,7 @@ map.on("load", () => {
   syncPatternTexture(map, {
     imageId: "my-hatches",
     pattern: "hachures",
-    size: 16,
+    size: 33,
     color: "#2c6a5b",
     weight: 2,
     angle: 45,
@@ -186,12 +227,30 @@ The playground can export:
 
 - ready-to-use MapLibre code;
 - a reusable Stipple configuration;
-- a MapLibre style document;
-- a bundle containing the generated pattern images.
+- a static bundle containing style layers, generated pattern images, and an
+  integration helper.
+
+The copied code uses `addPatternFill`, which waits for the map style, installs
+the generated textures, adapts the exported layers to an existing source, and
+adds them in order:
+
+```js
+import { addPatternFill } from "stipple-maplibre";
+
+await addPatternFill(map, {
+  sourceId: "my-polygons",
+  sourceLayer: null, // Use the source-layer name for vector tiles.
+  pattern: exportedPattern,
+});
+```
+
+The source must already exist in the map. An optional `beforeId` places the
+pattern layers below an existing label or symbol layer. The returned
+`layerIds` list contains every layer added to the map.
 
-For code-driven styles, `buildStyleFragment` creates the background, pattern,
-and outline layers together. The resulting style metadata carries the pattern
-recipe. After the style loads, `installPatternFills` reads those recipes and
+For lower-level, code-driven styles, `buildStyleFragment` creates the
+background, pattern, and outline layers together. The resulting style metadata
+carries the pattern recipe. `installPatternFills` reads those recipes and
 installs every texture the map needs:
 
 ```js
@@ -280,7 +339,7 @@ in Node.
 
 ## Project status
 
-Version `0.1.1` is available on
+Version `0.3.0` is available on
 [npm](https://www.npmjs.com/package/stipple-maplibre). The whole-symbol
 scatter API is the only part currently marked experimental.
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Map } from 'maplibre-gl';
+import { Map, LayerSpecification } from 'maplibre-gl';
 
 type PatternType = "solid" | "stipple" | "hachures" | "cross" | "grid" | "dots";
 /** Tile edge length in px. MapLibre does not require power-of-two fill-pattern images. Larger tiles read as a lower-density pattern. */
@@ -396,6 +396,37 @@ interface StyleLike {
  */
 declare function installPatternFills(map: Map, style: StyleLike): Promise<void>;
 
+interface PatternFillLayerTemplate {
+    id: string;
+    type: LayerSpecification["type"];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface PatternFillFragment {
+    layers: PatternFillLayerTemplate[];
+}
+interface AddPatternFillOptions {
+    /** Id of a source that already exists in the map. */
+    sourceId: string;
+    /** Omit or use null for GeoJSON. Required for vector tile sources. */
+    sourceLayer?: string | null;
+    /** Insert every generated layer immediately before this existing layer. */
+    beforeId?: string;
+    /** Source-neutral layer templates exported by Stipple. */
+    pattern: PatternFillFragment;
+}
+interface AddedPatternFill {
+    layerIds: string[];
+}
+/**
+ * Installs a Stipple pattern export on an existing MapLibre source.
+ *
+ * The helper waits for the style, resolves the source placeholders, installs
+ * every generated texture, then adds the exported background, fill, and
+ * outline layers in order.
+ */
+declare function addPatternFill(map: Map, options: AddPatternFillOptions): Promise<AddedPatternFill>;
+
 interface ObservePatternFillsOptions {
     /** Defaults to `map.getStyle()`. Useful when metadata is stored separately. */
     getStyle?: () => StyleLike;
@@ -602,4 +633,4 @@ interface InstallSvgIconScatterOptions {
  */
 declare function installSvgIconScatter(map: Map, options: InstallSvgIconScatterOptions): Promise<void>;
 
-export { type BackgroundFillConfig, type BuildStyleFragmentOptions, type FontPatternDefinition, type FontPatternOptions, type GeoJsonPolygonImport, type GeometricPatternDefinition, type GeometricPatternType, type HachureAngle, type IconScaleMode, type ImportedPolygonFeature, type InstallSvgIconScatterOptions, type MakeTileOptions, type ObservePatternFillsOptions, type OutlineConfig, PATTERN_METADATA_KEY, type PatternDefinition, type PatternFillConfig, type PatternFillObserver, type PatternMetadataV1, type PatternScaleMode, type PatternScaleOptions, type PatternScaleResult, type PatternType, type PatternVariant, type PointFeature, type PointFeatureCollection, type PolygonGeometry, type Ring, type ScatterIconPointsOptions, type ScatterPointsOptions, type ScatteredPoint, type ScreenPatternPhase, type StyleLike, type SvgDistributionMode, type SvgPatternDefinition, type SvgPatternOptions, type SvgScatterLayoutOptions, type SvgStampPlacement, type SyncPatternTextureOptions, type TileContext, type TileImage, type TileSize, buildStyleFragment, createFontPatternDefinition, createFontPatternTile, createMiniContext, createSvgPatternDefinition, createSvgScatterLayout, createSvgScatterTile, hashStringToSeed, importGeoJsonPolygons, installFontPatternFill, installPatternFills, installSvgIconScatter, installSvgPatternFill, makeTile, mulberry32, observePatternFills, parsePatternDefinition, parsePatternMetadata, patternDefinitionId, scalePatternForZoom, scatterIconPoints, scatterPointsInPolygon, screenPatternPhase, serializePatternDefinition, syncPatternTexture };
+export { type AddPatternFillOptions, type AddedPatternFill, type BackgroundFillConfig, type BuildStyleFragmentOptions, type FontPatternDefinition, type FontPatternOptions, type GeoJsonPolygonImport, type GeometricPatternDefinition, type GeometricPatternType, type HachureAngle, type IconScaleMode, type ImportedPolygonFeature, type InstallSvgIconScatterOptions, type MakeTileOptions, type ObservePatternFillsOptions, type OutlineConfig, PATTERN_METADATA_KEY, type PatternDefinition, type PatternFillConfig, type PatternFillFragment, type PatternFillLayerTemplate, type PatternFillObserver, type PatternMetadataV1, type PatternScaleMode, type PatternScaleOptions, type PatternScaleResult, type PatternType, type PatternVariant, type PointFeature, type PointFeatureCollection, type PolygonGeometry, type Ring, type ScatterIconPointsOptions, type ScatterPointsOptions, type ScatteredPoint, type ScreenPatternPhase, type StyleLike, type SvgDistributionMode, type SvgPatternDefinition, type SvgPatternOptions, type SvgScatterLayoutOptions, type SvgStampPlacement, type SyncPatternTextureOptions, type TileContext, type TileImage, type TileSize, addPatternFill, buildStyleFragment, createFontPatternDefinition, createFontPatternTile, createMiniContext, createSvgPatternDefinition, createSvgScatterLayout, createSvgScatterTile, hashStringToSeed, importGeoJsonPolygons, installFontPatternFill, installPatternFills, installSvgIconScatter, installSvgPatternFill, makeTile, mulberry32, observePatternFills, parsePatternDefinition, parsePatternMetadata, patternDefinitionId, scalePatternForZoom, scatterIconPoints, scatterPointsInPolygon, screenPatternPhase, serializePatternDefinition, syncPatternTexture };

package/dist/index.global.js

@@ -22,6 +22,7 @@ var MaplibrePatternFills = (() => {
   var src_exports = {};
   __export(src_exports, {
     PATTERN_METADATA_KEY: () => PATTERN_METADATA_KEY,
+    addPatternFill: () => addPatternFill,
     buildStyleFragment: () => buildStyleFragment,
     createFontPatternDefinition: () => createFontPatternDefinition,
     createFontPatternTile: () => createFontPatternTile,
@@ -1480,6 +1481,83 @@ var MaplibrePatternFills = (() => {
     await Promise.all(pending);
   }
 
+  // src/maplibre/addPatternFill.ts
+  function nonEmptyString2(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new TypeError(`${name} must be a non-empty string`);
+    }
+  }
+  async function waitForStyle(map) {
+    if (map.getStyle()) return;
+    await new Promise((resolve) => {
+      map.once("style.load", () => resolve());
+    });
+  }
+  async function addPatternFill(map, options) {
+    nonEmptyString2(options.sourceId, "sourceId");
+    if (options.sourceLayer !== void 0 && options.sourceLayer !== null) {
+      nonEmptyString2(options.sourceLayer, "sourceLayer");
+    }
+    if (options.beforeId !== void 0) {
+      nonEmptyString2(options.beforeId, "beforeId");
+    }
+    if (!options.pattern || !Array.isArray(options.pattern.layers)) {
+      throw new TypeError("pattern.layers must be an array");
+    }
+    if (options.pattern.layers.length === 0) {
+      throw new RangeError("pattern.layers must contain at least one layer");
+    }
+    await waitForStyle(map);
+    if (!map.getSource(options.sourceId)) {
+      throw new Error(`MapLibre source "${options.sourceId}" was not found`);
+    }
+    if (options.beforeId && !map.getLayer(options.beforeId)) {
+      throw new Error(`MapLibre layer "${options.beforeId}" was not found`);
+    }
+    const layers = options.pattern.layers.map((template, index) => {
+      if (!template || typeof template !== "object") {
+        throw new TypeError(`pattern.layers[${index}] must be an object`);
+      }
+      nonEmptyString2(template.id, `pattern.layers[${index}].id`);
+      nonEmptyString2(template.type, `pattern.layers[${index}].type`);
+      const layer = {
+        ...template,
+        id: template.id.split("<source>").join(options.sourceId),
+        source: options.sourceId
+      };
+      if (options.sourceLayer === void 0 || options.sourceLayer === null) {
+        delete layer["source-layer"];
+      } else {
+        layer["source-layer"] = options.sourceLayer;
+      }
+      return layer;
+    });
+    const layerIds = layers.map((layer) => layer.id);
+    const uniqueIds = new Set(layerIds);
+    if (uniqueIds.size !== layerIds.length) {
+      throw new Error("Pattern fill contains duplicate layer ids");
+    }
+    for (const layerId of layerIds) {
+      if (map.getLayer(layerId)) {
+        throw new Error(`MapLibre layer "${layerId}" already exists`);
+      }
+    }
+    await installPatternFills(map, { layers });
+    const addedLayerIds = [];
+    try {
+      for (const layer of layers) {
+        map.addLayer(layer, options.beforeId);
+        addedLayerIds.push(layer.id);
+      }
+    } catch (error) {
+      for (const layerId of addedLayerIds.reverse()) {
+        if (map.getLayer(layerId)) map.removeLayer(layerId);
+      }
+      throw error;
+    }
+    return { layerIds };
+  }
+
   // src/maplibre/observePatternFills.ts
   function observePatternFills(map, options = {}) {
     const getStyle = options.getStyle ?? (() => map.getStyle());

package/dist/index.js

@@ -1429,6 +1429,83 @@ async function installPatternFills(map, style) {
   await Promise.all(pending);
 }
 
+// src/maplibre/addPatternFill.ts
+function nonEmptyString2(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+}
+async function waitForStyle(map) {
+  if (map.getStyle()) return;
+  await new Promise((resolve) => {
+    map.once("style.load", () => resolve());
+  });
+}
+async function addPatternFill(map, options) {
+  nonEmptyString2(options.sourceId, "sourceId");
+  if (options.sourceLayer !== void 0 && options.sourceLayer !== null) {
+    nonEmptyString2(options.sourceLayer, "sourceLayer");
+  }
+  if (options.beforeId !== void 0) {
+    nonEmptyString2(options.beforeId, "beforeId");
+  }
+  if (!options.pattern || !Array.isArray(options.pattern.layers)) {
+    throw new TypeError("pattern.layers must be an array");
+  }
+  if (options.pattern.layers.length === 0) {
+    throw new RangeError("pattern.layers must contain at least one layer");
+  }
+  await waitForStyle(map);
+  if (!map.getSource(options.sourceId)) {
+    throw new Error(`MapLibre source "${options.sourceId}" was not found`);
+  }
+  if (options.beforeId && !map.getLayer(options.beforeId)) {
+    throw new Error(`MapLibre layer "${options.beforeId}" was not found`);
+  }
+  const layers = options.pattern.layers.map((template, index) => {
+    if (!template || typeof template !== "object") {
+      throw new TypeError(`pattern.layers[${index}] must be an object`);
+    }
+    nonEmptyString2(template.id, `pattern.layers[${index}].id`);
+    nonEmptyString2(template.type, `pattern.layers[${index}].type`);
+    const layer = {
+      ...template,
+      id: template.id.split("<source>").join(options.sourceId),
+      source: options.sourceId
+    };
+    if (options.sourceLayer === void 0 || options.sourceLayer === null) {
+      delete layer["source-layer"];
+    } else {
+      layer["source-layer"] = options.sourceLayer;
+    }
+    return layer;
+  });
+  const layerIds = layers.map((layer) => layer.id);
+  const uniqueIds = new Set(layerIds);
+  if (uniqueIds.size !== layerIds.length) {
+    throw new Error("Pattern fill contains duplicate layer ids");
+  }
+  for (const layerId of layerIds) {
+    if (map.getLayer(layerId)) {
+      throw new Error(`MapLibre layer "${layerId}" already exists`);
+    }
+  }
+  await installPatternFills(map, { layers });
+  const addedLayerIds = [];
+  try {
+    for (const layer of layers) {
+      map.addLayer(layer, options.beforeId);
+      addedLayerIds.push(layer.id);
+    }
+  } catch (error) {
+    for (const layerId of addedLayerIds.reverse()) {
+      if (map.getLayer(layerId)) map.removeLayer(layerId);
+    }
+    throw error;
+  }
+  return { layerIds };
+}
+
 // src/maplibre/observePatternFills.ts
 function observePatternFills(map, options = {}) {
   const getStyle = options.getStyle ?? (() => map.getStyle());
@@ -1734,6 +1811,7 @@ async function installSvgIconScatter(map, options) {
 }
 export {
   PATTERN_METADATA_KEY,
+  addPatternFill,
   buildStyleFragment,
   createFontPatternDefinition,
   createFontPatternTile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stipple-maplibre",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Runtime-generated geometric and SVG fill patterns for MapLibre GL JS, with deterministic styling and a visual playground.",
   "license": "MIT",
   "type": "module",