@mailwoman/cartographer 9.4.0 → 10.1.0

package/lib/base/buildings.ts

@@ -11,7 +11,7 @@ import type {
 } from "@maplibre/maplibre-gl-style-spec"
 
 import { MailwomanBaseTileSetID } from "#base/theme"
-import { PROTOMAPS_FONT_REGULAR } from "#styles/fonts"
+import { MAP_FONT_REGULAR } from "#styles/fonts"
 import { LayerID } from "#styles/layers"
 
 const BuildingLayerID = LayerID.bind(null, "buildings")
@@ -80,8 +80,7 @@ export const BuildingLayers: LayerSpecification[] = [
 			"fill-extrusion-vertical-gradient": false,
 			"fill-extrusion-translate-anchor": "map",
 			"fill-extrusion-opacity": 1,
-			// top of the band = full building height
-			// "fill-extrusion-height": popHeight(buildingHeight()),
+			// top of the band = full building height "fill-extrusion-height": popHeight(buildingHeight()),
 			// // base of the band = full height minus the cap thickness (clamped ≥ 0)
 			// "fill-extrusion-base": popHeight([ "max", [ "-", buildingHeight(), ROOF_CAP ], 0 ]),
 			"fill-extrusion-height": popHeight(["+", buildingHeight(), ROOF_GAP, ROOF_CAP]),
@@ -115,7 +114,7 @@ export const BuildingLayers: LayerSpecification[] = [
 			"text-field": ["to-string", ["id"]],
 			"text-offset": [0, 0],
 			"text-anchor": "center",
-			"text-font": [PROTOMAPS_FONT_REGULAR],
+			"text-font": [MAP_FONT_REGULAR],
 		},
 
 		paint: {

package/lib/base/composition.ts

@@ -16,9 +16,9 @@ import {
 } from "#styles/layers"
 import type { TileSetSourceRecord } from "#styles/sources"
 
-//#endregion
+// #endregion
 
-//#region Spec Creators
+// #region Spec Creators
 
 export function createLightSpec(spec?: Partial<LightSpecification>): LightSpecification {
 	return {
@@ -46,19 +46,23 @@ export function createSkySpec(spec?: Partial<SkySpecification>): SkySpecificatio
 	}
 }
 
-//#endregion
+// #endregion
 
-//#region Style Composition
+// #region Style Composition
 
 /**
- * The glyph host every style composed here reads fonts from. The Protomaps font set, mirrored under the public bucket
- * so a style never depends on an upstream host at render time.
+ * The glyph host every style composed here reads fonts from.
+ *
+ * The Protomaps font set, mirrored under the public bucket so a style never
+ * depends on an upstream host at render time.
  */
 export const PROTOMAPS_GLYPHS_URL = "https://public.mailwoman.ai/protomaps/fonts/{fontstack}/{range}.pbf"
 
 /**
- * The Earth sprite. It must match the basemap schema version: the v4 sprite carries the icons the v4 theme's layers
- * reference by name, so a style over a different basemap version needs a different sprite.
+ * The Earth sprite.
+ *
+ * It must match the basemap schema version: the v4 sprite includes the icons the v4 theme's
+ * layers reference by name, so a style over a different basemap version needs a different sprite.
  */
 export const PROTOMAPS_SPRITE_URL = "https://public.mailwoman.ai/protomaps/sprites/v4/light"
 
@@ -69,16 +73,22 @@ export interface StyleSpecificationComposition {
 	sky?: Partial<SkySpecification>
 	terrain?: Partial<TerrainSpecification>
 	/**
-	 * The layer list every `layers` entry inserts into. Earth's basemap layers by default; a body with no roads, water or
-	 * buildings brings its own.
+	 * The layer list every `layers` entry inserts into.
+	 *
+	 * Earth's basemap layers by default.
+	 * A body with no roads, water or buildings brings its own.
 	 */
 	baseLayers?: LayerSpecification[]
 	/**
-	 * The `hillshade` source. Earth's terrarium DEM by default; `null` adds no such source.
+	 * The `hillshade` source.
+	 *
+	 * Earth's terrarium DEM by default; `null` adds no such source.
 	 */
 	hillshadeSource?: SourceSpecification | null
 	/**
-	 * The sprite URL. Earth's Protomaps v4 sprite by default; `null` omits the key, for a style with no icons.
+	 * The sprite URL.
+	 *
+	 * Earth's Protomaps v4 sprite by default; `null` omits the key, for a style with no icons.
 	 */
 	sprite?: string | null
 	glyphs?: string
@@ -146,4 +156,4 @@ export class StyleSpecificationComposer {
 	}
 }
 
-//#endregion
+// #endregion

package/lib/base/layers.ts

@@ -18,9 +18,15 @@ import { LayerID } from "#styles/layers"
 export const HillsLayerID = LayerID(HillshadeTileSetID, "hills")
 
 /**
- * Splits `layers()` into non-label + label groups so building footprints, water outlines, and hillshade sit between
- * base geometry and labels. `@protomaps/basemaps@5.x` doesn't expose a `noLabels` helper — `labelsOnly: true` gives
- * only the label layers; subtracting that set from the full list yields the non-label group.
+ * Splits `layers()` into non-label and label groups.
+ *
+ * The interval between base geometry and labels holds the footprints.
+ * It also holds water outlines and hillshade.
+ *
+ * `@protomaps/basemaps@5.x` doesn't expose a `noLabels` helper.
+ * `labelsOnly: true` gives only the label layers.
+ *
+ * The full list minus that set yields the non-label group.
  */
 const allBaseLayers = layers(MailwomanBaseTileSetID, MailwomanBaseFlavor, { lang: "en" })
 const labelLayers = layers(MailwomanBaseTileSetID, MailwomanBaseFlavor, { lang: "en", labelsOnly: true })

package/lib/base/theme.ts

@@ -6,25 +6,34 @@
 
 import { type Flavor, namedFlavor } from "@protomaps/basemaps"
 
+import { MAP_FONT_ITALIC, MAP_FONT_MEDIUM, MAP_FONT_REGULAR } from "#styles/fonts"
 import { TileSetSourceID } from "#styles/sources"
 
 /**
- * Identifier for the Mailwoman base tileset. Matches the R2 object basename (`nexus-assets/tiles/basemap-v4.pmtiles`) —
- * `tiles.mailwoman.ai/basemap-v4.json` returns its tilejson, `tiles.mailwoman.ai/basemap-v4/{z}/{x}/{y}.mvt` returns
- * vector tiles.
+ * Identifier for the Mailwoman base tileset.
+ *
+ * Matches the R2 object basename (`nexus-assets/tiles/basemap-v4.pmtiles`).
+ * `tiles.mailwoman.ai/basemap-v4.json` returns its tilejson,
+ * `tiles.mailwoman.ai/basemap-v4/{z}/{x}/{y}.mvt` returns vector tiles.
  */
 export const MailwomanBaseTileSetID = TileSetSourceID("basemap-v4")
 
 const darkFlavor = namedFlavor("dark")
 
 /**
- * The Mailwoman theme for Protomaps via MapLibre. Keys follow `@protomaps/basemaps@5.x` which targets the v4 tile
- * schema (`["==","kind","..."]` filters), matching the basemap-v4 PMTiles on R2.
+ * The Mailwoman theme for Protomaps via MapLibre.
+ *
+ * Keys follow `@protomaps/basemaps@5.x` which targets the v4 tile schema
+ * (`["==","kind","..."]` filters), matching the basemap-v4 PMTiles on R2.
  */
 export const MailwomanBaseFlavor: Flavor = {
 	...darkFlavor,
 
-	//#region Base
+	regular: MAP_FONT_REGULAR,
+	bold: MAP_FONT_MEDIUM,
+	italic: MAP_FONT_ITALIC,
+
+	// #region Base
 	background: "hsl(0deg 10% 5%)",
 	earth: "hsl(0deg 10% 5%)",
 
@@ -51,8 +60,8 @@ export const MailwomanBaseFlavor: Flavor = {
 	zoo: "#222323",
 	military: "#242323",
 
-	//#endregion
-	//#region Tunnel
+	// #endregion
+	// #region Tunnel
 	tunnel_other_casing: "#141414",
 	tunnel_minor_casing: "#141414",
 	tunnel_link_casing: "#141414",
@@ -64,10 +73,10 @@ export const MailwomanBaseFlavor: Flavor = {
 	tunnel_major: "#292929",
 	tunnel_highway: "#292929",
 
-	//#endregion
+	// #endregion
 	buildings: "#111111",
 
-	//#region Casing
+	// #region Casing
 	minor_service_casing: "#1f1f1f",
 	minor_casing: "#1f1f1f",
 	link_casing: "#1f1f1f",
@@ -83,11 +92,11 @@ export const MailwomanBaseFlavor: Flavor = {
 	highway_casing_early: "#1f1f1f",
 	highway: "hsl(36deg 10% 50%)",
 
-	//#endregion
+	// #endregion
 	railway: "#000000",
 	boundaries: "hsl(240deg 100% 90%)",
 
-	//#region Bridges
+	// #region Bridges
 	bridges_other_casing: "#2b2b2b",
 	bridges_minor_casing: "#1f1f1f",
 	bridges_link_casing: "#1f1f1f",
@@ -99,7 +108,7 @@ export const MailwomanBaseFlavor: Flavor = {
 	bridges_major: "#3d3d3d",
 	bridges_highway: "#474747",
 
-	//#endregion
+	// #endregion
 
 	ocean_label: "#717784",
 	subplace_label: "hsl(50deg 50% 70%)",

package/lib/{bdc/index.ts → bdc.ts}

@@ -47,13 +47,14 @@ export type BaseBDCLayerSpecification<T> = T extends BDCLayerSpecificationInput
 	: never
 
 /**
- * The three builders below take a spec WITHOUT the source fields and return one with them filled in.
+ * The three builders below take a spec without the source fields and return one with them filled in.
  *
- * They are not generic, and the assertion each ends with is single rather than through `unknown`, both for the same
- * reason: TypeScript cannot verify that `Omit<T, K>` plus the omitted keys reconstitutes `T`, so a builder declared
- * `<T>(…): T` can only reach its return type by defeating the checker entirely — which then covers the `id`, `minzoom`
- * and `maxzoom` values too. Nothing wanted the narrowing: the sole consumer, {@linkcode BroadbandDataCollectionLayers},
- * annotates the union.
+ * These are specific assertions.
+ * Each avoids `unknown`.
+ *
+ * TypeScript cannot verify that because TypeScript cannot verify that `Omit<T, K>` plus
+ * the omitted keys reconstitutes `T` — a `<T>(…): T` builder could only reach its return
+ * type by defeating the checker, covering the `id`, `minzoom` and `maxzoom` values too.
  */
 type BDCLayerBuilderInput = BaseBDCLayerSpecification<BDCLayerSpecificationInput>
 
@@ -101,9 +102,6 @@ const GIGABIT_BROADBAND_SPEED = 1000
 export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 	{
 		afterID: "earth",
-		// metadata: {
-		// 	queryable: false,
-		// },
 		id: "blocks-underserved",
 		layout: {
 			visibility: "none",
@@ -112,43 +110,19 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		source: BDCTileSetID,
 		type: "fill",
 		filter: [
-			// ---
 			"all",
 			["in", 50, ["get", "technology_codes"]], // Fiber only
 			[">", ["get", "land_area_sqm"], 0],
-			// ["==", ["get", "UR"], "R"],
 		],
 		paint: {
-			// "fill-extrusion-height": [
-			// 	// Our extrusion height represents the magnitude of broadband underservice,
-			// 	// e.g. How many people are underserved per square meter of land area.
-			// 	"let",
-			// 	"population_density",
-			// 	["/", ["to-number", ["get", "population"]], ["to-number", ["get", "land_area_sqm"]]],
-			// 	["*", ["var", "population_density"], 10000],
-			// ],
 			"fill-color": "hsl(60deg, 100%, 50%)",
 			"fill-opacity": [
-				// Underserved areas are emphasized to their level importance,
-				// relative to the impact of the underservice.
 				"let",
 				"internet_speed_impact",
 				["/", ["to-number", ["get", "average_download_speed"]], GIGABIT_BROADBAND_SPEED],
-				[
-					// ---
-					"interpolate",
-					["linear"],
-					["var", "internet_speed_impact"],
-					0,
-					0.1,
-					1,
-					0.5,
-				],
+				["interpolate", ["linear"], ["var", "internet_speed_impact"], 0, 0.1, 1, 0.5],
 			],
 		},
-		// layout: {
-		// 	visibility: "none",
-		// },
 	},
 
 	{
@@ -163,7 +137,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		"source-layer": `bdc_${TIGERLevel.Block}`,
 		source: BDCTileSetID,
 		type: "line",
-		// filter: [">=", ["get", "ALAND"], 0],
 		minzoom: 9,
 		paint: {
 			"line-color": "#000",
@@ -180,13 +153,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		"source-layer": `bdc_${TIGERLevel.Block}`,
 		source: BDCTileSetID,
 		type: "symbol",
-		filter: [
-			// ---
-			"all",
-			// ["in", 50, ["get", "technology_codes"]], // Fiber only
-			[">", ["get", "land_area_sqm"], 0],
-			// ["==", ["get", "UR"], "R"],
-		],
+		filter: ["all", [">", ["get", "land_area_sqm"], 0]],
 		paint: {
 			"text-color": "black",
 			"text-halo-color": "white",
@@ -208,13 +175,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 	...createBDCLayer({
 		id: "coverage-fiber-label",
 		beforeID: "places_subplace",
-		filter: [
-			// ---
-
-			"all",
-			["==", ["get", "provider_id"], 131_425],
-			// ["in", 50, ["get", "technology_codes"]],
-		],
+		filter: ["all", ["==", ["get", "provider_id"], 131_425]],
 		type: "symbol",
 		layout: {
 			visibility: "none",
@@ -224,13 +185,8 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 				" Mbps",
 			],
 			"text-size": [
-				// ---
 				"let",
 				"multiplier",
-				// We scale the text size based on the average download speed.
-				// By default, we're no smaller than 14, Any speed above the gigabit threshold
-				// acts as a multiplier for the text size.
-				// ---
 				["/", ["get", "average_download_speed"], GIGABIT_BROADBAND_SPEED / 4],
 				["+", 14, ["var", "multiplier"]],
 			],
@@ -246,7 +202,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		paint: {
 			"text-halo-width": 2,
 			"text-halo-color": [
-				// ---
 				"interpolate",
 				["exponential", 0.5],
 				["get", "average_download_speed"],
@@ -258,7 +213,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 			],
 
 			"text-color": [
-				// ---
 				"interpolate",
 				["exponential", 0.25],
 				["get", "average_download_speed"],
@@ -287,22 +241,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		paint: {
 			"line-color": "#ff009c",
 
-			"line-width": [
-				"interpolate",
-				["exponential", 1.6],
-				["zoom"],
-				// ---
-				3,
-				0,
-				6,
-				1.1,
-				12,
-				1.6,
-				15,
-				5,
-				18,
-				15,
-			],
+			"line-width": ["interpolate", ["exponential", 1.6], ["zoom"], 3, 0, 6, 1.1, 12, 1.6, 15, 5, 18, 15],
 		},
 		layout: {
 			"line-cap": "round",
@@ -312,12 +251,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 	...createBDCLayer({
 		afterID: "earth",
 		id: "coverage-fiber-heat",
-		filter: [
-			// ---
-
-			"all",
-			["==", ["get", "provider_id"], 131_425],
-		],
+		filter: ["all", ["==", ["get", "provider_id"], 131_425]],
 		minzoom: 10,
 		type: "heatmap",
 		layout: {
@@ -325,7 +259,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		},
 		paint: {
 			"heatmap-color": [
-				// ---
 				"interpolate",
 				["linear"],
 				["heatmap-density"],
@@ -334,22 +267,8 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 				}).flat(),
 			],
 
-			"heatmap-radius": [
-				// ---
-				"interpolate",
-				["linear"],
-				["zoom"],
-				10,
-				5,
-				15,
-				20,
-			],
-			"heatmap-weight": [
-				// ---
-				"*",
-				["get", "land_area_sqm"],
-				0.00001,
-			],
+			"heatmap-radius": ["interpolate", ["linear"], ["zoom"], 10, 5, 15, 20],
+			"heatmap-weight": ["*", ["get", "land_area_sqm"], 0.00001],
 		},
 	}),
 
@@ -381,30 +300,17 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		source: "composite",
 		"source-layer": "DataCentersCombined20220921",
 		layout: {
-			// visibility: "none",
 			"text-field": ["get", "Category"],
 			"text-size": 12,
 			"text-anchor": "top",
 			"text-offset": [0, 0.5],
-			// "text-allow-overlap": true,
 			"text-font": ["Fira Code Regular"],
 		},
 		paint: {
 			"text-color": "#fff",
 			"text-halo-color": "#fb8429",
 			"text-halo-width": 1,
-			"text-opacity": [
-				// We fade out the outline at higher zoom levels
-				"interpolate",
-				["linear"],
-				["zoom"],
-				1,
-				0.01,
-				6,
-				0.5,
-				16,
-				1,
-			],
+			"text-opacity": ["interpolate", ["linear"], ["zoom"], 1, 0.01, 6, 0.5, 16, 1],
 		},
 	},
 ]

package/lib/coverage.ts

@@ -0,0 +1,73 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Address-coverage overlays rendered from the `mailwoman coverage build` H3 tile set. Each cell
+ *   supplies optimistic (`fog_opt`) and observed-coverage (`fog`) values. The demo exposes both as
+ *   default-off layers. Tiles are served from `coverage-v5.pmtiles`.
+ */
+
+import type { FillLayerSpecification, VectorSourceSpecification } from "@maplibre/maplibre-gl-style-spec"
+
+import { TileSetSourceID } from "#styles/sources"
+
+/**
+ * MapLibre source ID for the v5 coverage tiles.
+ * Keep it aligned with the archive and layer specs.
+ */
+export const CoverageTileSetID = TileSetSourceID("coverage-v5")
+
+/**
+ * Source-layer name stored in the coverage archive.
+ */
+export const COVERAGE_SOURCE_LAYER = "coverage"
+
+/**
+ * Near-black indigo used to mark unknown or unsurveyed areas.
+ */
+export const COVERAGE_FOG_COLOR = "#663399" // Rebecca Purple
+
+/**
+ * Maximum opacity for an uncovered cell.
+ */
+export const COVERAGE_MAX_FOG_OPACITY = 0.9
+
+/**
+ * IDs for the optimistic and observed-coverage layers.
+ */
+export const CoverageLayerID = {
+	optimistic: "coverage-opt-fog",
+	honest: "coverage-honest-fog",
+} as const
+
+/**
+ * Create a vector source from its TileJSON URL.
+ */
+export function createCoverageSource(url: string): VectorSourceSpecification {
+	return { type: "vector", url }
+}
+
+function fogFill(id: string, fogProperty: "fog" | "fog_opt"): FillLayerSpecification {
+	return {
+		id,
+		type: "fill",
+		source: CoverageTileSetID,
+		"source-layer": COVERAGE_SOURCE_LAYER,
+		// Keep coverage overlays hidden until selected.
+		layout: { visibility: "none" },
+		paint: {
+			"fill-color": COVERAGE_FOG_COLOR,
+			// Rows without coverage values render as clear.
+			"fill-opacity": ["*", ["coalesce", ["to-number", ["get", fogProperty]], 0], COVERAGE_MAX_FOG_OPACITY],
+		},
+	}
+}
+
+/**
+ * The two hidden fog layers, added beneath place labels by the demo.
+ */
+export const CoverageLayers: FillLayerSpecification[] = [
+	fogFill(CoverageLayerID.optimistic, "fog_opt"),
+	fogFill(CoverageLayerID.honest, "fog"),
+]

package/lib/index.ts

@@ -4,9 +4,9 @@
  * @author Teffen Ellis, et al.
  */
 
-export * from "#base/index"
-export * from "#bdc/index"
-export * from "#hspa/index"
-export * from "#styles/index"
-export * from "#tiger/index"
-export * from "#tiles/index"
+export * from "#base"
+export * from "#bdc"
+export * from "#hspa"
+export * from "#styles"
+export * from "#tiger"
+export * from "#tiles"