stipple-maplibre 0.2.0 → 0.3.0

package/README.md

@@ -66,7 +66,7 @@ and provides the corresponding `fill-pattern` value.
     </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>Or even your custom SVG</em></sub>
+      <sub><em>Custom</em></sub>
     </td>
   </tr>
 </table>
@@ -227,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.
 
-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
+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 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
@@ -321,7 +339,7 @@ in Node.
 
 ## Project status
 
-Version `0.2.0` 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.2.0",
+  "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",