@mapmap/maps 0.7.0 → 0.8.0

package/README.md

@@ -751,13 +751,29 @@ actionable `console.error` per issue per page, each with a docs link:
 
 `runMapDiagnostics(…)` is exported for apps wrapping a raw `maplibregl.Map`.
 
-## The MapMap mark
+## The MapMap mark and the attribution
 
 Maps render a small MapMap wordmark bottom-right (the same convention as
 Google Maps and Mapbox). It links to mapmap.ai, needs no network fetch,
-and is on by default: pass `logo: false` to `createMap` to remove it, or
-`logo: { position, href }` to customise. Attribution is separate and not
-removable.
+and is always on: pass `logo: { position, href }` to `createMap` to move
+or relink it.
+
+Neither the mark nor the attribution can be switched off:
+
+- **The MapMap mark.** Every displayed MapMap map carries it, which is a
+  condition of the `@mapmap/maps` licence (the same model as Mapbox GL JS
+  v2+). `logo: false` still type-checks, so nothing stops compiling, but
+  it is ignored and the SDK logs one `console.warn` per map.
+- **The OpenStreetMap attribution.** The credit is a condition of the ODbL
+  that the map data is served under, for MapMap and for you.
+  `mapOptions: { attributionControl: false }` is ignored the same way.
+  Everything else MapLibre offers still works:
+  `attributionControl: { compact: true }` collapses it, and
+  `attributionControl: { customAttribution: "© Your Co" }` adds your own
+  credit alongside the OSM one.
+
+In a bottom corner the mark sits above the attribution: MapLibre prepends
+controls in the bottom corners, so the control added last is the highest.
 
 ## Turn-by-turn guidance
 

package/dist/index.d.ts

@@ -258,9 +258,10 @@ declare function createRouteEffect(name: RouteEffectName, geometry: RouteGeometr
 
 /**
  * The MapMap logo control: a small wordmark on the map, the same
- * convention as Google Maps' and Mapbox's marks. On by default in
- * {@link MapMapMap}; positionable, and removable with `logo: false`
- * (attribution itself is separate and never removable).
+ * convention as Google Maps' and Mapbox's marks. Always on in
+ * {@link MapMapMap} and positionable with `logo: { position }`; it cannot
+ * be removed (carrying the mark is a condition of the SDK licence), and
+ * the OpenStreetMap attribution is a separate, equally permanent control.
  *
  * The mark is an inline SVG (no network fetch, works offline and under
  * strict CSPs): the MapMap brand lockup — the three-colour route mark
@@ -271,7 +272,15 @@ declare function createRouteEffect(name: RouteEffectName, geometry: RouteGeometr
 type LogoPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 /** Options for {@link LogoControl}. */
 interface LogoOptions {
-    /** Corner to render in. Default `bottom-right`, above the attribution. */
+    /**
+     * Corner to render in. Default `bottom-right`.
+     *
+     * In a bottom corner the mark sits ABOVE the attribution, despite being
+     * added after it: MapLibre prepends controls in the bottom corners
+     * (`insertBefore(container.firstChild)`) and the corner is anchored to
+     * the bottom edge, so the control added last is the one that ends up
+     * highest. Verified against maplibre-gl 5's `addControl`.
+     */
     position?: LogoPosition;
     /** Link target when clicked. Default the MapMap site. */
     href?: string;
@@ -1046,8 +1055,18 @@ declare function registerPmtilesProtocol(gl?: typeof maplibregl): void;
 interface MapMapOptions {
     /**
      * The MapMap wordmark on the map (like the Google Maps / Mapbox marks).
-     * Default on at bottom-right, above the attribution; `false` removes
-     * it, or pass `{ position, href }` to customise.
+     * Always on, at bottom-right above the attribution by default; pass
+     * `{ position, href }` to move or relink it.
+     *
+     * The mark cannot be taken off. Every displayed MapMap map carries it,
+     * which is a condition of the SDK licence, the same model as Mapbox GL
+     * JS v2+. `false` (and `true`) are still accepted so existing code keeps
+     * compiling: passing `false` is ignored, the mark is added anyway, and
+     * the SDK logs one `console.warn` for that map.
+     *
+     * `false` is soft-deprecated: it does nothing and will be dropped from
+     * the type in the next major. Use `{ position }` to get the mark out of
+     * the way instead.
      */
     logo?: boolean | LogoOptions;
     /** The container element or its id. */
@@ -1071,6 +1090,13 @@ interface MapMapOptions {
     /**
      * Extra MapLibre `MapOptions` merged last (escape hatch for hash, bearing,
      * maxBounds, etc.). `container` and `style` here are ignored.
+     *
+     * `attributionControl` is honoured but never allowed to remove the
+     * credit: `{ compact }` and `{ customAttribution }` work as MapLibre
+     * documents them, while `attributionControl: false` is ignored (the
+     * attribution stays, and the SDK logs one `console.warn` for that map).
+     * The OpenStreetMap credit is a condition of the ODbL the map data is
+     * served under, for MapMap and for you.
      */
     mapOptions?: Partial<Omit<MapOptions, "container" | "style">>;
 }
@@ -1114,7 +1140,15 @@ declare class MapMapMap {
     private effectWaiting;
     private destroyed;
     private readonly pendingWaits;
+    private readonly notices;
     constructor(options: MapMapOptions);
+    /**
+     * Log an enforcement notice at most once for this map. A warning, not
+     * an error and never a throw: `logo: false` and
+     * `attributionControl: false` are published, documented options, and a
+     * hard failure would break a customer's build on a patch upgrade.
+     */
+    private notice;
     /**
      * Run `action` as soon as the style can take layer edits, or now if it
      * already can.

package/dist/index.js

@@ -1891,6 +1891,12 @@ var MapMapMap = class {
     // style load, and the cleanups let it detach those listeners.
     this.destroyed = false;
     this.pendingWaits = /* @__PURE__ */ new Set();
+    // Enforcement notices already logged for THIS map. Per instance, not
+    // per page (diagnostics.ts dedups per page because a duplicated
+    // maplibre-gl is one page-level fault): each map that asks for a
+    // removal is its own licence problem and deserves its own line, but a
+    // theme swap or re-render must never repeat one.
+    this.notices = /* @__PURE__ */ new Set();
     this.handleStyleLoadForEffects = () => {
       if (this.destroyed) return;
       if (!this.effectExplicit) {
@@ -1908,21 +1914,36 @@ var MapMapMap = class {
     this.navDesign = navDesignFromTheme(theme);
     this.poiDesign = poiDesignFromTheme(theme);
     const style = resolveStyle(options.style, options.territoryTilesUrl);
+    const requestedAttribution = options.mapOptions?.attributionControl;
+    if (requestedAttribution === false) {
+      this.notice(
+        "attribution-removal",
+        "mapOptions.attributionControl: false is ignored - the OpenStreetMap attribution stays on. The credit is a condition of the ODbL that the map data is served under, for MapMap and for you. Pass { compact: true } to collapse it, or { customAttribution } to add your own credit alongside it."
+      );
+    }
+    const attributionControl = {
+      compact: false,
+      ...requestedAttribution === false ? void 0 : requestedAttribution
+    };
     this.map = new maplibregl.Map({
       container: options.container,
       style,
       center: options.center ?? DEFAULT_CENTER,
       zoom: options.zoom ?? DEFAULT_ZOOM,
-      attributionControl: { compact: false },
-      ...options.mapOptions
+      ...options.mapOptions,
+      attributionControl
     });
-    if (options.logo !== false) {
-      const logoOptions = options.logo === true ? {} : options.logo ?? {};
-      this.map.addControl(
-        new LogoControl(logoOptions),
-        logoOptions.position ?? "bottom-right"
+    if (options.logo === false) {
+      this.notice(
+        "logo-removal",
+        "logo: false is ignored - the MapMap mark stays on the map. Carrying the mark is a condition of the @mapmap/maps licence. Pass logo: { position } to move it to another corner."
       );
     }
+    const logoOptions = typeof options.logo === "object" && options.logo !== null ? options.logo : {};
+    this.map.addControl(
+      new LogoControl(logoOptions),
+      logoOptions.position ?? "bottom-right"
+    );
     this.map.on("style.load", this.handleStyleLoadForEffects);
     runMapDiagnostics({
       container: options.container,
@@ -1931,6 +1952,17 @@ var MapMapMap = class {
       apiKey: this.apiKey
     });
   }
+  /**
+   * Log an enforcement notice at most once for this map. A warning, not
+   * an error and never a throw: `logo: false` and
+   * `attributionControl: false` are published, documented options, and a
+   * hard failure would break a customer's build on a patch upgrade.
+   */
+  notice(notice, message) {
+    if (this.notices.has(notice)) return;
+    this.notices.add(notice);
+    console.warn(`MapMap [${notice}]: ${message}`);
+  }
   /**
    * Run `action` as soon as the style can take layer edits, or now if it
    * already can.