feat: add explicit light/dark theme option to PrintControl (#92)

The panel previously only followed the system prefers-color-scheme.
Add a `theme` option and `setTheme()` method so host apps that manage
their own light/dark mode can force the panel to match.

Author: giswqs

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "maplibre-gl-components",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Legend, colorbar, and HTML control components for MapLibre GL JS maps",
   "type": "module",
   "main": "./dist/index.cjs",

package.json

@@ -307,6 +307,7 @@ export type {
   PrintColorbarConfig,
   PrintEvent,
   PrintEventHandler,
+  PrintTheme,
   MinimapControlOptions,
   MinimapControlState,
   MinimapEvent,

src/index.ts

@@ -15,6 +15,7 @@ import type {
   PrintOrientation,
   PrintFitMode,
   PrintFormat,
+  PrintTheme,
   ColormapName,
   ColorStop,
 } from "./types";
@@ -47,6 +48,7 @@ const DEFAULT_OPTIONS: Required<Omit<PrintControlOptions, "colorbar">> & {
   className: "",
   visible: true,
   collapsed: true,
+  theme: "auto",
   format: "png",
   quality: 0.92,
   filename: "map-export",
@@ -312,6 +314,7 @@ export class PrintControl implements IControl {
   private _createContainer(): HTMLElement {
     const container = document.createElement("div");
     container.className = `maplibregl-ctrl maplibre-gl-print-control ${this._options.className}`;
+    this._applyThemeClass(container);
 
     if (!this._state.visible) {
       container.style.display = "none";
@@ -876,7 +879,10 @@ export class PrintControl implements IControl {
     this._marginInput.min = "0";
     this._marginInput.value = String(this._state.margin);
     this._marginInput.addEventListener("input", () => {
-      this._state.margin = Math.max(0, parseFloat(this._marginInput!.value) || 0);
+      this._state.margin = Math.max(
+        0,
+        parseFloat(this._marginInput!.value) || 0,
+      );
     });
     row2.appendChild(this._makeField("Margin (pt)", this._marginInput));
     wrapper.appendChild(row2);
@@ -1037,7 +1043,7 @@ export class PrintControl implements IControl {
         crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
       }
     }
-    return (~crc) >>> 0;
+    return ~crc >>> 0;
   }
 
   /**
@@ -1113,10 +1119,7 @@ export class PrintControl implements IControl {
    * @param format - The raster format.
    * @returns A new blob carrying the current DPI, or the original on failure.
    */
-  private async _embedDpi(
-    blob: Blob,
-    format: "png" | "jpeg",
-  ): Promise<Blob> {
+  private async _embedDpi(blob: Blob, format: "png" | "jpeg"): Promise<Blob> {
     try {
       const bytes = new Uint8Array(await blob.arrayBuffer());
       const dpi = this._effectiveDpi();
@@ -1757,7 +1760,10 @@ export class PrintControl implements IControl {
 
         if (content.w >= minCanvasWidthForArrow) {
           const arrowX = content.x + content.w - arrowSize - 18;
-          const arrowY = Math.max(content.y + 18, content.y + titleBarHeight + 8);
+          const arrowY = Math.max(
+            content.y + 18,
+            content.y + titleBarHeight + 8,
+          );
           const bearing = this._map.getBearing();
           this._drawNorthArrow(ctx, arrowX, arrowY, arrowSize, bearing);
         }
@@ -1951,6 +1957,41 @@ export class PrintControl implements IControl {
     return { ...this._state };
   }
 
+  /**
+   * Set the panel theme.
+   *
+   * Use `'light'` or `'dark'` to force a theme when the host application
+   * manages its own light/dark mode, or `'auto'` to follow the system
+   * `prefers-color-scheme`. Updates the live panel immediately.
+   *
+   * @param theme - The theme to apply.
+   * @returns This control instance for chaining.
+   */
+  setTheme(theme: PrintTheme): this {
+    this._options.theme = theme;
+    if (this._container) {
+      this._applyThemeClass(this._container);
+    }
+    return this;
+  }
+
+  /**
+   * Apply the theme modifier class to the given element so the panel honors an
+   * explicitly forced light/dark theme. `'auto'` removes both modifiers and
+   * lets the CSS `prefers-color-scheme` media query drive the theme.
+   */
+  private _applyThemeClass(container: HTMLElement): void {
+    container.classList.remove(
+      "maplibre-gl-print-control--light",
+      "maplibre-gl-print-control--dark",
+    );
+    if (this._options.theme === "light") {
+      container.classList.add("maplibre-gl-print-control--light");
+    } else if (this._options.theme === "dark") {
+      container.classList.add("maplibre-gl-print-control--dark");
+    }
+  }
+
   /**
    * Set the export format.
    */

src/lib/core/PrintControl.ts

@@ -3146,6 +3146,16 @@ export type PrintFitMode = "contain" | "cover";
  */
 export type PrintFormat = "png" | "jpeg" | "pdf" | "svg";
 
+/**
+ * Panel theme for the PrintControl.
+ *
+ * - `'auto'` (default) follows the system `prefers-color-scheme`.
+ * - `'light'` / `'dark'` force the panel into that theme regardless of the
+ *   system setting. Use this when the host application manages its own theme
+ *   (e.g. a class toggled on `<html>`) so the panel can be kept in sync.
+ */
+export type PrintTheme = "auto" | "light" | "dark";
+
 /**
  * Options for configuring the PrintControl.
  */
@@ -3158,6 +3168,13 @@ export interface PrintControlOptions {
   visible?: boolean;
   /** Whether to start collapsed. Default: true. */
   collapsed?: boolean;
+  /**
+   * Panel theme. `'auto'` (default) follows the system `prefers-color-scheme`.
+   * Set to `'light'` or `'dark'` to force a theme when the host application
+   * manages its own light/dark mode. Can be changed at runtime with
+   * {@link PrintControl.setTheme}.
+   */
+  theme?: PrintTheme;
   /** Default image format. Default: 'png'. */
   format?: PrintFormat;
   /** JPEG quality (0-1). Default: 0.92. */

src/lib/core/types.ts

@@ -10,7 +10,8 @@
   color-scheme: light dark;
 
   /* Theme tokens (light defaults). Overridden by the dark media query below
-     so the control adapts to the system light/dark theme. */
+     so the control adapts to the system light/dark theme, or by the explicit
+     `--light` / `--dark` modifier classes when the host app forces a theme. */
   --print-panel-bg: rgba(255, 255, 255, 0.95);
   --print-subtle-bg: #f9fafb;
   --print-text: #374151;
@@ -27,6 +28,50 @@
   --print-feedback: #16a34a;
 }
 
+/* Forced light theme. The host app sets the `--light` modifier (via the
+   PrintControl `theme: 'light'` option / setTheme) so the panel stays light
+   even when the system prefers dark. Higher specificity than the default rule
+   above and wins over the dark media query because that query excludes this
+   modifier. */
+.maplibre-gl-print-control.maplibre-gl-print-control--light {
+  color-scheme: light;
+  --print-panel-bg: rgba(255, 255, 255, 0.95);
+  --print-subtle-bg: #f9fafb;
+  --print-text: #374151;
+  --print-muted: #6b7280;
+  --print-subtle: #9ca3af;
+  --print-border: #e5e7eb;
+  --print-input-bg: #fff;
+  --print-input-text: #111;
+  --print-placeholder: #9ca3af;
+  --print-hover-bg: #f3f4f6;
+  --print-focus: #3b82f6;
+  --print-button-bg: #fff;
+  --print-button-text: #333;
+  --print-feedback: #16a34a;
+}
+
+/* Forced dark theme. The host app sets the `--dark` modifier (via the
+   PrintControl `theme: 'dark'` option / setTheme) so the panel stays dark even
+   when the system prefers light. */
+.maplibre-gl-print-control.maplibre-gl-print-control--dark {
+  color-scheme: dark;
+  --print-panel-bg: rgba(40, 40, 40, 0.95);
+  --print-subtle-bg: rgba(255, 255, 255, 0.05);
+  --print-text: #e0e0e0;
+  --print-muted: #aaa;
+  --print-subtle: #999;
+  --print-border: #555;
+  --print-input-bg: #2a2a2a;
+  --print-input-text: #e0e0e0;
+  --print-placeholder: #888;
+  --print-hover-bg: rgba(255, 255, 255, 0.08);
+  --print-focus: #3b82f6;
+  --print-button-bg: #2a2a2a;
+  --print-button-text: #e0e0e0;
+  --print-feedback: #4ade80;
+}
+
 .maplibre-gl-print-control .print-button {
   display: flex;
   align-items: center;
@@ -419,9 +464,13 @@
   flex: none;
 }
 
-/* Dark mode support */
+/* Dark mode support (system preference). Applies only when no explicit theme
+   is forced via the `--light` / `--dark` modifier classes, so a host app that
+   manages its own theme is never overridden by the OS setting. */
 @media (prefers-color-scheme: dark) {
-  .maplibre-gl-print-control {
+  .maplibre-gl-print-control:not(.maplibre-gl-print-control--light):not(
+      .maplibre-gl-print-control--dark
+    ) {
     --print-panel-bg: rgba(40, 40, 40, 0.95);
     --print-subtle-bg: rgba(255, 255, 255, 0.05);
     --print-text: #e0e0e0;