@sjvair/map-sdk 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/presets/FireTooltip.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+	import type { FeatureListItem } from "../core/plugin.js";
+	import type { FormatProvider } from "../data/format.js";
+	import type { MessageProvider } from "../data/messages.js";
+	import { NO_LEVEL, numericValue } from "../data/scale.js";
+	import { formatValue } from "../ui/value-format.js";
+	import MonitorReadingBox from "./MonitorReadingBox.svelte";
+
+	// A fire's power in the monitors' reading box, beside its name and level. The value is cut
+	// off, not rounded, so it never reads as the next level (9.96 MW shows 9.9 beside "<10").
+	// No detection time: a satellite pass isn't when the fire started or whether it still burns.
+
+	interface Props {
+		item: FeatureListItem;
+		/** How many detections a group averages; null for a single detection. */
+		count: number | null;
+		messages: MessageProvider;
+		format: FormatProvider;
+	}
+
+	let { item, count, messages, format }: Props = $props();
+
+	const level = $derived(item.level !== NO_LEVEL ? item.level : null);
+	const value = $derived.by(() => {
+		const n = numericValue(item.value);
+		return n === null ? null : formatValue(n, item.precision, format, true);
+	});
+	const header = $derived(
+		item.units
+			? messages("mapsdk_hms_fire_box_header", { units: item.units })
+			: messages("mapsdk_hms_fire_box_header_no_units")
+	);
+</script>
+
+<div class="mapsdk-fire-tip mapsdk-tooltip-wide">
+	<MonitorReadingBox
+		color={level?.color || null}
+		{header}
+		value={value ?? messages("mapsdk_no_reading")}
+		large={value !== null}
+		subheading={count !== null && count >= 2 ? messages("mapsdk_hms_fire_average") : undefined}
+	/>
+	<div class="mapsdk-fire-detail">
+		<span class="mapsdk-fire-name text-lg">{item.name}</span>
+		<span>
+			{level
+				? item.units
+					? messages("mapsdk_level_with_units", { level: level.label, units: item.units })
+					: level.label
+				: messages("mapsdk_no_level")}
+		</span>
+	</div>
+</div>
+
+<style>
+	.mapsdk-fire-tip {
+		display: flex;
+		gap: 0.5rem;
+	}
+
+	.mapsdk-fire-name {
+		font-weight: 700;
+	}
+
+	.mapsdk-fire-detail {
+		display: flex;
+		flex-direction: column;
+		gap: 0.25rem;
+	}
+</style>

package/dist/presets/FireTooltip.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { FeatureListItem } from "../core/plugin.js";
+import type { FormatProvider } from "../data/format.js";
+import type { MessageProvider } from "../data/messages.js";
+interface Props {
+    item: FeatureListItem;
+    /** How many detections a group averages; null for a single detection. */
+    count: number | null;
+    messages: MessageProvider;
+    format: FormatProvider;
+}
+declare const FireTooltip: import("svelte").Component<Props, {}, "">;
+type FireTooltip = ReturnType<typeof FireTooltip>;
+export default FireTooltip;

package/dist/presets/MonitorClusterTooltip.svelte

@@ -7,12 +7,14 @@
 	import type { MonitorFeatureProperties } from "../data/types.js";
 	import type { ClusterInfo } from "../plugins/points-clusters.js";
 	import { formatValue } from "../ui/value-format.js";
+	import { clusterAreaSqMiles } from "./cluster-area.js";
 	import MonitorReadingBox from "./MonitorReadingBox.svelte";
 
 	// Ported from monitor-map's MonitorClusterTooltip: the cluster's average in a level-colored
 	// box beside its monitor type, count, and highest and lowest readings. The count and average
 	// come from the bubble itself, so they show at once; the rest fills in from the cluster's
 	// monitors. The average is a whole number and max and min are as reported, as monitor-map's.
+	// The count line adds the area the monitors are within (their convex hull) once they load.
 
 	interface Props {
 		cluster: ClusterInfo<MonitorFeatureProperties>;
@@ -29,6 +31,8 @@
 		isSjvair: boolean;
 		/** Readings only; monitors without one are left out. */
 		values: number[];
+		/** Square miles of the monitors' convex hull, every monitor included. */
+		area: number;
 	}
 
 	let leaves = $state.raw<Leaves | null>(null);
@@ -60,7 +64,8 @@
 					values: found.flatMap(({ props }) => {
 						const n = numericValue(props.value);
 						return n === null ? [] : [n];
-					})
+					}),
+					area: clusterAreaSqMiles(found.map(({ lngLat }) => lngLat))
 				};
 			},
 			() => {
@@ -87,6 +92,16 @@
 		return found !== NO_LEVEL ? found : null;
 	});
 	const units = $derived(scale?.units ?? "");
+	/** The area to 3 decimals, or null when there is none to show (it would read 0.000). */
+	const area = $derived.by(() => {
+		// Decided on the number, so a host's own number format can't change what's hidden.
+		if (!leaves || Math.round(leaves.area * 1000) === 0) return null;
+		return format.number(leaves.area, {
+			minimumFractionDigits: 3,
+			maximumFractionDigits: 3,
+			useGrouping: false
+		});
+	});
 	const max = $derived(leaves?.values.length ? Math.max(...leaves.values) : null);
 	const min = $derived(leaves?.values.length ? Math.min(...leaves.values) : null);
 </script>
@@ -108,7 +123,11 @@
 				)}
 			</span>
 		{/if}
-		<span>{messages("mapsdk_monitor_cluster_count", { count: cluster.pointCount })}</span>
+		<span>
+			{area
+				? messages("mapsdk_monitor_cluster_count_area", { count: cluster.pointCount, area })
+				: messages("mapsdk_monitor_cluster_count", { count: cluster.pointCount })}
+		</span>
 		<span>{level ? level.label : messages("mapsdk_no_level")}</span>
 		{#if max !== null && min !== null}
 			<span class="mapsdk-monitor-extremes text-base">

package/dist/presets/cluster-area.d.ts

@@ -0,0 +1,13 @@
+type Point = [number, number];
+/**
+ * The convex hull of lng/lat points (monotone chain): counter-clockwise, without a repeated
+ * closing point, inner and collinear points dropped. Fewer than 3 points means no area.
+ */
+export declare function convexHull(points: Point[]): Point[];
+/**
+ * The area, in square miles, of the smallest shape around a cluster's monitors (their convex
+ * hull), as sjvair.com's map computed area: `@turf/area`, then `convertArea`. 0 for fewer than 3
+ * points not on one line.
+ */
+export declare function clusterAreaSqMiles(points: Point[]): number;
+export {};

package/dist/presets/cluster-area.js

@@ -0,0 +1,34 @@
+import area from "@turf/area";
+import { convertArea, polygon } from "@turf/helpers";
+const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+/**
+ * The convex hull of lng/lat points (monotone chain): counter-clockwise, without a repeated
+ * closing point, inner and collinear points dropped. Fewer than 3 points means no area.
+ */
+export function convexHull(points) {
+    const sorted = [...points].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    if (sorted.length < 3)
+        return sorted;
+    const half = (from) => {
+        const chain = [];
+        for (const p of from) {
+            while (chain.length >= 2 && cross(chain[chain.length - 2], chain[chain.length - 1], p) <= 0)
+                chain.pop();
+            chain.push(p);
+        }
+        chain.pop();
+        return chain;
+    };
+    return [...half(sorted), ...half([...sorted].reverse())];
+}
+/**
+ * The area, in square miles, of the smallest shape around a cluster's monitors (their convex
+ * hull), as sjvair.com's map computed area: `@turf/area`, then `convertArea`. 0 for fewer than 3
+ * points not on one line.
+ */
+export function clusterAreaSqMiles(points) {
+    const hull = convexHull(points);
+    if (hull.length < 3)
+        return 0;
+    return convertArea(area(polygon([[...hull, hull[0]]])), "meters", "miles");
+}

package/dist/presets/hms-fire.d.ts

@@ -1,12 +1,16 @@
 import type { MapPlugin } from "../core/plugin.js";
-import type { DataSource } from "../data/types.js";
+import type { DataSource, FireFeatureProperties } from "../data/types.js";
 export interface HmsFirePluginOptions {
     /** Default "hms-fire". */
     id?: string;
-    /** The fires, or with `hotspots` the groups shown below zoom 10 (listed). */
-    source: DataSource;
+    /**
+     * The fires, or with `hotspots` the groups shown below zoom 10 (listed). A feature with a
+     * `count` is a group (its tooltip says "Average" from 2 detections); one without is a single
+     * detection.
+     */
+    source: DataSource<FireFeatureProperties>;
     /** Single detections shown from zoom 10 instead of `source` (not listed). Default: none. */
-    hotspots?: DataSource;
+    hotspots?: DataSource<FireFeatureProperties>;
     /** Already-translated layer name for the list and summary. */
     layerLabel: string;
 }
@@ -16,9 +20,9 @@ export interface HmsFirePluginOptions {
  *
  * With `hotspots`, it is still one layer (one legend section, one list) that switches by itself
  * while zooming: `source` (groups from `groupFires`, value = `avgFrp`) below zoom 10, `hotspots`
- * (each detection) from zoom 10. Both are hit-tested and show the same tooltip (name, value,
- * level);
- * only the groups are listed.
+ * (each detection) from zoom 10. Both are hit-tested and show the same tooltip: the power in a
+ * reading box colored by its level, beside the name and level; only the groups are listed. Values
+ * are cut off at the display precision, not rounded, in the tooltip, list, and accessible names.
  *
  * The sources' `scale` is expected to be the ScaleRef `{ dataset: "hms-fire", entryType:
  * "fire-frp" }`, and each feature's `value` its FRP. This preset does not fetch.

package/dist/presets/hms-fire.js

@@ -1,7 +1,7 @@
 import { scopedContext } from "../core/scoped-context.js";
 import { fireIcon } from "../plugins/icons.js";
 import { pointsPlugin } from "../plugins/points.svelte.js";
-import TooltipItem from "../ui/TooltipItem.svelte";
+import FireTooltip from "./FireTooltip.svelte";
 import { componentSnippet } from "./monitors.js";
 /** The zoom where `hotspots` replace the groups (inclusive), as sjvair.com's map does. */
 const HOTSPOT_ZOOM = 10;
@@ -22,6 +22,14 @@ function firePoints(id, source, layerLabel, zoomRange) {
         selectable: false,
         zoomRange,
         legendDisplay: "blocks",
+        truncateValues: true,
+        tooltipShowsName: true,
+        tooltip: (item, props, env) => componentSnippet(FireTooltip, {
+            item,
+            count: typeof props.count === "number" ? props.count : null,
+            messages: env.messages,
+            format: env.format
+        }),
         icon: {
             category: () => "fire",
             draw: (_category, color, _theme, levelIndex) => drawFire(color, levelIndex),
@@ -35,9 +43,9 @@ function firePoints(id, source, layerLabel, zoomRange) {
  *
  * With `hotspots`, it is still one layer (one legend section, one list) that switches by itself
  * while zooming: `source` (groups from `groupFires`, value = `avgFrp`) below zoom 10, `hotspots`
- * (each detection) from zoom 10. Both are hit-tested and show the same tooltip (name, value,
- * level);
- * only the groups are listed.
+ * (each detection) from zoom 10. Both are hit-tested and show the same tooltip: the power in a
+ * reading box colored by its level, beside the name and level; only the groups are listed. Values
+ * are cut off at the display precision, not rounded, in the tooltip, list, and accessible names.
  *
  * The sources' `scale` is expected to be the ScaleRef `{ dataset: "hms-fire", entryType:
  * "fire-frp" }`, and each feature's `value` its FRP. This preset does not fetch.
@@ -50,8 +58,6 @@ export function hmsFirePlugin(options) {
     // Both inner plugins share the outer id, so their hits are this plugin's.
     const groups = firePoints(id, source, layerLabel, { max: HOTSPOT_ZOOM });
     const singles = firePoints(id, hotspots, layerLabel, { min: HOTSPOT_ZOOM });
-    // The providers of the running setup, for the hotspots' tooltips.
-    let ctxNow = null;
     return {
         id,
         label: layerLabel,
@@ -60,28 +66,21 @@ export function hmsFirePlugin(options) {
         },
         selectable: false,
         setup(ctx) {
-            ctxNow = ctx;
             const teardownGroups = groups.setup(scopedContext(ctx, "groups:"));
             const teardownSingles = singles.setup(scopedContext(ctx, "hotspots:"));
             return () => {
-                ctxNow = null;
                 teardownSingles();
                 teardownGroups();
             };
         },
         legend: groups.legend,
-        // Only the groups are listed; a hovered hotspot shows what a group's hover does: its name
-        // (the generic header) with its value and level.
+        // Only the groups are listed; a hovered hotspot shows the same box as a group.
         features: groups.features,
+        tooltip: groups.tooltip,
+        tooltipShowsName: true,
         hoverTooltip(hit) {
             const item = singles.features?.().find((f) => f.refKey === hit.refKey);
-            if (!item || !ctxNow)
-                return undefined;
-            return componentSnippet(TooltipItem, {
-                item,
-                messages: ctxNow.messages,
-                format: ctxNow.format
-            });
+            return item && singles.tooltip?.(item);
         }
     };
 }

package/dist/presets/hms-smoke.d.ts

@@ -10,7 +10,8 @@ export interface HmsSmokePluginOptions {
 /**
  * NOAA HMS smoke plumes: polygons filled and outlined (`outline: "level"`) by density, using each
  * level's opacity. Not selectable; listed (each plume a row with its density level), so plumes
- * can be reached without a mouse.
+ * can be reached without a mouse. Hovering a plume shows no tooltip and never hides another
+ * layer's (`hoverable: false`); focusing one from the list still pins its tooltip.
  *
  * The source's `scale` is expected to be the ScaleRef
  * `{ dataset: "hms-smoke", entryType: "smoke-density" }`, and each feature's `value` its density

package/dist/presets/hms-smoke.js

@@ -2,7 +2,8 @@ import { shapesPlugin } from "../plugins/shapes.svelte.js";
 /**
  * NOAA HMS smoke plumes: polygons filled and outlined (`outline: "level"`) by density, using each
  * level's opacity. Not selectable; listed (each plume a row with its density level), so plumes
- * can be reached without a mouse.
+ * can be reached without a mouse. Hovering a plume shows no tooltip and never hides another
+ * layer's (`hoverable: false`); focusing one from the list still pins its tooltip.
  *
  * The source's `scale` is expected to be the ScaleRef
  * `{ dataset: "hms-smoke", entryType: "smoke-density" }`, and each feature's `value` its density
@@ -15,6 +16,7 @@ export function hmsSmokePlugin(options) {
         layerLabel: options.layerLabel,
         mode: "choropleth",
         selectable: false,
-        outline: "level"
+        outline: "level",
+        hoverable: false
     });
 }

package/dist/stores/hms-stores.svelte.d.ts

@@ -1,5 +1,5 @@
 import { type MessageProvider } from "../data/messages.js";
-import type { DataSource, DataStatus } from "../data/types.js";
+import type { DataSource, DataStatus, FireFeatureProperties } from "../data/types.js";
 import type { SignalOptions } from "./abort.js";
 export interface HmsStoreOptions {
     /** Names features ("Smoke", "Fire detection"). Default: the built-in English messages. */
@@ -22,8 +22,11 @@ export interface HmsSmokeStore {
 export interface HmsFireStore {
     /** `loading` until loaded, then `ready` (also when today has no fires) or `error`. */
     readonly status: DataStatus;
-    /** Nearby detections merged (`groupFires`), for `hmsFirePlugin`; `value` is the mean FRP. */
-    readonly groups: DataSource;
+    /**
+     * Nearby detections merged (`groupFires`), for `hmsFirePlugin`; `value` is the mean FRP and
+     * `count` how many detections it merges.
+     */
+    readonly groups: DataSource<FireFeatureProperties>;
     /** Each detection (`cleanFires`), for `hmsFirePlugin`; `value` is its FRP. */
     readonly hotspots: DataSource;
     /** As `HmsSmokeStore.init`. */

package/dist/stores/hms-stores.svelte.js

@@ -69,15 +69,15 @@ export function createHmsFireStore(options = {}) {
                 value: fire.frp
             }
         }));
+        // Every group names its count, a group of 1 included ("1 fire detection").
         const groups = groupFires(detections).map((group) => ({
             type: "Feature",
             geometry: { type: "Point", coordinates: group.coordinates },
             properties: {
                 refKey: encodeRef({ kind: "feature", id: group.id }),
-                name: group.count === 1
-                    ? detection
-                    : messages("mapsdk_hms_fire_detections", { count: group.count }),
-                value: group.avgFrp
+                name: messages("mapsdk_hms_fire_detections", { count: group.count }),
+                value: group.avgFrp,
+                count: group.count
             }
         }));
         return {

package/dist/ui/FeatureList.svelte

@@ -9,12 +9,13 @@
 		inView,
 		optionIdPart,
 		rowLabel,
+		levelText,
 		shownLevel,
+		shownValue,
 		sortItems,
 		typeaheadIndex,
 		type SortBy
 	} from "./feature-list.js";
-	import { formatValue as formatNumber } from "./value-format.js";
 
 	interface Props {
 		map: MapContext;
@@ -200,7 +201,8 @@
 			case "Enter":
 			case " ":
 				e.preventDefault();
-				if (current >= 0) pick(rows[current], e.key === " ");
+				// Space, or Shift with Enter, is the additive key (as Shift-click on a row).
+				if (current >= 0) pick(rows[current], e.key === " " || e.shiftKey);
 				return;
 			default:
 				if (e.key.length === 1 && e.key !== " ") {
@@ -266,13 +268,6 @@
 		pick(rows[index], e.shiftKey || e.metaKey || e.ctrlKey);
 	}
 
-	function formatValue(row: Row): string {
-		if (row.value === null) return "";
-		return typeof row.value === "number"
-			? formatNumber(row.value, row.precision, map.format)
-			: row.value;
-	}
-
 	onDestroy(() => {
 		clearTimeout(typeaheadTimer);
 		clearTimeout(menuSentTimer);
@@ -330,6 +325,8 @@
 			{#each windowRows as row, i (row.key)}
 				{@const index = range.start + i}
 				{@const level = shownLevel(row)}
+				{@const levelPlace = levelText(row, map.messages)}
+				{@const value = shownValue(row, map.format)}
 				{@const isOn = isSelected(row)}
 				<!-- Options aren't focused: the listbox holds focus and handles keys (aria-activedescendant). -->
 				<!-- svelte-ignore a11y_click_events_have_key_events, a11y_interactive_supports_focus -->
@@ -357,15 +354,17 @@
 					</span>
 					<span class="mapsdk-list-name">{row.name}</span>
 					<span class="mapsdk-list-value">
-						{formatValue(row)}{#if row.units && row.value !== null}&nbsp;{row.units}{/if}
+						{value ?? ""}{#if row.units && value !== null}&nbsp;{row.units}{/if}
 					</span>
 					<span class="mapsdk-list-level text-xs">
-						<span
-							class="mapsdk-list-swatch"
-							class:neutral={!level?.color}
-							style:background={level?.color || undefined}
-						></span>
-						{level ? level.label : map.messages("mapsdk_no_level")}
+						{#if levelPlace.kind !== "detail"}
+							<span
+								class="mapsdk-list-swatch"
+								class:neutral={!level?.color}
+								style:background={level?.color || undefined}
+							></span>
+						{/if}
+						{levelPlace.text}
 					</span>
 				</div>
 			{/each}
@@ -383,7 +382,8 @@
 		flex-direction: column;
 		position: relative;
 		width: 21rem;
-		max-width: calc(100vw - 2rem);
+		/* The map's width inside a MapView (set there), else the window's. */
+		max-width: calc(var(--mapsdk-map-width, 100vw) - 2rem);
 		max-height: 100%;
 		box-sizing: border-box;
 		border: 1px solid var(--card-border, var(--border));

package/dist/ui/Legend.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { onMount } from "svelte";
+	import { onMount, untrack } from "svelte";
 	import "./controls.css";
 	import type { MapContext } from "../core/create-map.svelte.js";
 	import { watchTheme } from "../view/create-gl-map.js";
@@ -8,9 +8,19 @@
 
 	let {
 		map,
-		order = "bottom-first"
+		order = "bottom-first",
+		framed = true
 	}: {
 		map: MapContext;
+		/**
+		 * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+		 * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+		 * then blend over the nearest ancestor with an opaque background (a see-through card is
+		 * skipped), else the `--background` token. The color is read on mount, when `framed`
+		 * changes, and on a theme change; a card that changes color through its own class or
+		 * style isn't re-read.
+		 */
+		framed?: boolean;
 		/**
 		 * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
 		 * last.
@@ -43,30 +53,50 @@
 		)
 	);
 
-	/** Computed colors can be oklch() or color(); a 1x1 canvas turns any of them into rgb. */
-	function resolveBackground(el: Element): string {
-		const css = getComputedStyle(el).backgroundColor;
+	/**
+	 * A computed color as rgb and whether it's opaque; computed colors can be oklch() or color(),
+	 * and a 1x1 canvas turns any of them into rgb.
+	 */
+	function toRgb(css: string): { rgb: string; opaque: boolean } {
 		const ctx = document.createElement("canvas").getContext("2d");
-		if (!ctx) return css;
+		if (!ctx) return { rgb: css, opaque: true };
 		ctx.clearRect(0, 0, 1, 1);
 		ctx.fillStyle = css;
 		ctx.fillRect(0, 0, 1, 1);
-		const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
-		return `rgb(${r}, ${g}, ${b})`;
+		const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+		return { rgb: `rgb(${r}, ${g}, ${b})`, opaque: a === 255 };
 	}
 
-	onMount(() => {
-		const update = () => {
-			if (root) background = resolveBackground(root);
-		};
-		update();
-		return watchTheme(root!, update);
+	/**
+	 * What translucent swatches blend over: the legend's own card, or without a frame the nearest
+	 * ancestor with an opaque background (the host's card), else the `--background` token.
+	 */
+	function resolveBackground(el: HTMLElement, frameless: boolean): string {
+		if (!frameless) return toRgb(getComputedStyle(el).backgroundColor).rgb;
+		for (let at = el.parentElement; at; at = at.parentElement) {
+			const color = toRgb(getComputedStyle(at).backgroundColor);
+			if (color.opaque) return color.rgb;
+		}
+		// A computed custom property has its var() references already substituted.
+		return toRgb(getComputedStyle(el).getPropertyValue("--background").trim()).rgb;
+	}
+
+	function update() {
+		if (root) background = resolveBackground(root, !framed);
+	}
+
+	onMount(() => watchTheme(root!, update));
+
+	// On mount, and again when `framed` changes.
+	$effect(() => {
+		void framed;
+		untrack(update);
 	});
 </script>
 
 <section
 	bind:this={root}
-	class="mapsdk-legend"
+	class={["mapsdk-legend", !framed && "mapsdk-legend-frameless"]}
 	aria-label={map.messages("mapsdk_legend_label")}
 	hidden={entries.length === 0}
 >
@@ -113,7 +143,8 @@
 		flex-direction: column;
 		gap: 0.75rem;
 		width: 21rem;
-		max-width: calc(100vw - 2rem);
+		/* The map's width inside a MapView (set there), else the window's. */
+		max-width: calc(var(--mapsdk-map-width, 100vw) - 2rem);
 		box-sizing: border-box;
 		padding: 0.75rem 1rem;
 		border: 1px solid var(--card-border, var(--border));
@@ -124,6 +155,17 @@
 		pointer-events: auto;
 	}
 
+	/* framed={false}: the host's card is the frame. */
+	.mapsdk-legend-frameless {
+		width: auto;
+		max-width: none;
+		padding: 0;
+		border: 0;
+		border-radius: 0;
+		background: none;
+		box-shadow: none;
+	}
+
 	.mapsdk-legend[hidden] {
 		display: none;
 	}

package/dist/ui/Legend.svelte.d.ts

@@ -2,6 +2,15 @@ import "./controls.css";
 import type { MapContext } from "../core/create-map.svelte.js";
 type $$ComponentProps = {
     map: MapContext;
+    /**
+     * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+     * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+     * then blend over the nearest ancestor with an opaque background (a see-through card is
+     * skipped), else the `--background` token. The color is read on mount, when `framed`
+     * changes, and on a theme change; a card that changes color through its own class or
+     * style isn't re-read.
+     */
+    framed?: boolean;
     /**
      * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
      * last.