@aceshooting/lyra-ui 1.0.0 → 1.1.0

package/dist/components/heatmap/heatmap.stories.js

@@ -22,3 +22,133 @@ export const Default = {
     ></lyra-heatmap>
   `,
 };
+export const SqrtScaleFitToWidth = {
+    render: () => html `
+    <lyra-heatmap
+      scale="sqrt"
+      fit-to-width
+      value-label="requests"
+      .rowLabels=${['Mon', 'Tue', 'Wed']}
+      .colLabels=${['0h', '6h', '12h', '18h']}
+      .values=${[
+        [1, 8, 400, 20],
+        [0, 2, 6, 3],
+        [-1, 1, 4, 7],
+    ]}
+    ></lyra-heatmap>
+  `,
+};
+export const CalendarMode = {
+    render: () => {
+        const days = [];
+        const start = Date.UTC(2026, 0, 1);
+        for (let i = 0; i < 120; i++) {
+            const date = new Date(start + i * 86_400_000).toISOString().slice(0, 10);
+            const value = Math.round(Math.abs(Math.sin(i / 6)) * 10);
+            days.push({ date, value });
+        }
+        return html `
+      <lyra-heatmap mode="calendar" value-label="commits" bucket-count="5" .days=${days}></lyra-heatmap>
+    `;
+    },
+};
+export const CustomTheme = {
+    render: () => html `
+    <lyra-heatmap
+      style="
+        --lyra-heatmap-scale-lo: #fde7e9;
+        --lyra-heatmap-scale-hi: #b3122f;
+        --lyra-heatmap-no-data-fill: rgba(0, 0, 0, 0.08);
+        --lyra-heatmap-label-font: 11px monospace;
+      "
+      cell-size="24"
+      value-label="events"
+      .rowLabels=${['Mon', 'Tue', 'Wed']}
+      .colLabels=${['0h', '6h', '12h']}
+      .values=${[
+        [1, 4, 9],
+        [0, 2, 6],
+        [-1, 1, 4],
+    ]}
+    ></lyra-heatmap>
+  `,
+};
+/**
+ * Hover a cell for its tooltip, tab to the grid and use the arrow keys to
+ * move the focus ring (a visually-hidden live region announces each move),
+ * and click or press Enter/Space on a cell to see its `lyra-cell-click`
+ * detail logged below.
+ */
+export const HoverFocusClick = {
+    render: () => {
+        const onCellClick = (e) => {
+            const detail = e.detail;
+            const out = document.getElementById('cell-click-out');
+            if (out)
+                out.textContent = JSON.stringify(detail);
+        };
+        return html `
+      <lyra-heatmap
+        cell-size="28"
+        value-label="events"
+        .rowLabels=${['Mon', 'Tue', 'Wed', 'Thu', 'Fri']}
+        .colLabels=${['0h', '6h', '12h', '18h']}
+        .values=${[
+            [1, 4, 9, 2],
+            [0, 2, 6, 3],
+            [5, 8, 3, 1],
+            [-1, 1, 4, 7],
+            [2, 3, 5, 6],
+        ]}
+        @lyra-cell-click=${onCellClick}
+      ></lyra-heatmap>
+      <p>Last <code>lyra-cell-click</code> detail: <code id="cell-click-out">(none yet)</code></p>
+    `;
+    },
+};
+/**
+ * Cells flagged via `annotations` get a stroked ring; ones with a `label`
+ * also surface a swatch + text entry in the legend.
+ */
+export const Annotations = {
+    render: () => html `
+    <lyra-heatmap
+      cell-size="24"
+      value-label="events"
+      .rowLabels=${['Mon', 'Tue', 'Wed', 'Thu', 'Fri']}
+      .colLabels=${['0h', '6h', '12h', '18h']}
+      .values=${[
+        [1, 4, 9, 2],
+        [0, 2, 6, 3],
+        [5, 8, 3, 1],
+        [-1, 1, 4, 7],
+        [2, 3, 5, 6],
+    ]}
+      .annotations=${[
+        { row: 0, col: 2, label: 'Peak load' },
+        { row: 2, col: 1, label: 'Incident' },
+    ]}
+    ></lyra-heatmap>
+  `,
+};
+/** `annotations` in calendar mode match by ISO `date` instead of `row`/`col`. */
+export const CalendarAnnotations = {
+    render: () => {
+        const days = [];
+        const start = Date.UTC(2026, 0, 1);
+        for (let i = 0; i < 120; i++) {
+            const date = new Date(start + i * 86_400_000).toISOString().slice(0, 10);
+            const value = Math.round(Math.abs(Math.sin(i / 6)) * 10);
+            days.push({ date, value });
+        }
+        return html `
+      <lyra-heatmap
+        mode="calendar"
+        value-label="commits"
+        bucket-count="5"
+        .days=${days}
+        .annotations=${[{ date: '2026-02-14', label: 'Release day' }]}
+      ></lyra-heatmap>
+    `;
+    },
+};

package/dist/components/heatmap/heatmap.styles.js

@@ -4,8 +4,8 @@ export const styles = css `
     display: block;
     /* Sequential ramp endpoints for the data-driven cell colors (canvas can't
        consume var() directly, so heatmap.ts resolves these via
-       getComputedStyle and interpolates between them). Componentspecific
-       business color per Global Constraints — exposed so hosts can retheme
+       getComputedStyle and interpolates between them). Component-specific
+       business color — exposed so hosts can retheme
        the ramp without raw hex leaking into the public API. */
     --lyra-heatmap-scale-lo: #cde2fb;
     --lyra-heatmap-scale-hi: #0969da;
@@ -13,8 +13,34 @@ export const styles = css `
        getComputedStyle pattern as the ramp endpoints above, so hosts can
        retheme it instead of it being a hardcoded literal in heatmap.ts. */
     --lyra-heatmap-no-data-fill: rgba(128, 128, 128, 0.25);
+    /* Canvas-drawn axis/month/weekday label font — same resolve-via-
+       getComputedStyle pattern as the ramp endpoints above (canvas can't
+       consume var() directly). */
+    --lyra-heatmap-label-font: 10px sans-serif;
+    /* [part="tooltip"] is a real DOM element (not canvas-drawn), so unlike
+       the tokens above it consumes these var()s directly — no getComputedStyle
+       resolution needed. Own tokens (not the bare --lyra-color-surface/-text)
+       so a host can retheme just the heatmap tooltip, same rationale as
+       chart.ts's --lyra-chart-tooltip-bg/-text. */
+    --lyra-heatmap-tooltip-bg: var(--lyra-color-surface);
+    --lyra-heatmap-tooltip-text: var(--lyra-color-text);
+    /* Canvas-drawn focus-ring stroke around the keyboard-focused cell — same
+       resolve-via-getComputedStyle pattern as the ramp endpoints (canvas
+       can't consume var() directly). A dedicated token (rather than reusing
+       --lyra-focus-ring-color straight from tokens.styles.ts) so a host can
+       retheme the in-canvas ring independently of every other :focus-visible
+       outline in the library, while defaulting to that same brand color —
+       also reused by the [part="canvas"]:focus-visible outline below so the
+       two stay visually in sync. */
+    --lyra-heatmap-focus-ring-color: var(--lyra-focus-ring-color);
+    /* Canvas-drawn ring around annotated cells — same resolve-via-
+       getComputedStyle pattern. Defaults to --lyra-color-danger (a loud,
+       attention-grabbing color distinct from the sequential data ramp) so an
+       annotation reads clearly against any point on that ramp. */
+    --lyra-heatmap-annotation-color: var(--lyra-color-danger);
   }
   [part='base'] {
+    position: relative;
     display: flex;
     flex-direction: column;
     gap: var(--lyra-space-xs);
@@ -23,6 +49,27 @@ export const styles = css `
     display: block;
     inline-size: 100%;
   }
+  [part='canvas']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-heatmap-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='tooltip'] {
+    position: absolute;
+    transform: translate(-50%, -100%);
+    margin-block-start: -6px;
+    padding: 2px 6px;
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-heatmap-tooltip-bg);
+    color: var(--lyra-heatmap-tooltip-text);
+    font-size: 0.75rem;
+    white-space: nowrap;
+    box-shadow: var(--lyra-shadow);
+    pointer-events: none;
+    z-index: 1;
+  }
+  [part='tooltip'][hidden] {
+    display: none;
+  }
   [part='legend'] {
     display: flex;
     align-items: center;
@@ -40,4 +87,15 @@ export const styles = css `
       var(--lyra-heatmap-scale-hi)
     );
   }
+  [part='legend-annotation'] {
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+  }
+  [part='legend-annotation'] .ring-swatch {
+    inline-size: 0.6rem;
+    block-size: 0.6rem;
+    border-radius: 50%;
+    border: 2px solid var(--lyra-heatmap-annotation-color);
+  }
 `;

package/dist/components/map/map.d.ts

@@ -6,10 +6,20 @@ export interface LegendEntry {
     color: string;
     label: string;
 }
+/**
+ * Declarative GeoJSON fill layer, colored by interpolating `field`'s value
+ * across `stops`.
+ */
 export interface ChoroplethLayer {
     sourceId: string;
     geojson: GeoJSON.FeatureCollection;
     field: string;
+    /**
+     * `[value, color]` pairs, ascending by `value`, fed to a maplibre-gl
+     * `interpolate` expression. Must contain at least one pair -- an empty
+     * array can't build a valid expression, so it's ignored (the existing fill
+     * layer, if any, is left as-is) rather than applied.
+     */
     stops: [number, string][];
 }
 export interface MapMarker {
@@ -17,6 +27,12 @@ export interface MapMarker {
     lngLat: [number, number];
     color?: string;
     label?: string;
+    /**
+     * Rendered as the marker's popup content via maplibre-gl's
+     * `Popup.setHTML()` -- parsed as raw markup, inline event handlers
+     * included. Only ever pass trusted content; sanitize anything derived
+     * from user input before assigning it here.
+     */
     html?: string;
 }
 /**
@@ -49,7 +65,7 @@ export declare class LyraMap extends LyraElement {
     private _styleLoaded;
     private _appliedChoroplethSourceId?;
     private _appliedFillLayerId?;
-    private _maplibreModule;
+    private _maplibreModule?;
     private _markerInstances;
     private _connectGeneration;
     /** The raw `maplibregl.Map` instance — escape hatch for anything this wrapper doesn't expose. */

package/dist/components/map/map.js

@@ -38,17 +38,27 @@ const DEFAULT_STYLE = {
     layers: [{ id: 'lyra-osm', type: 'raster', source: 'lyra-osm' }],
 };
 /**
- * Rejects a `LegendEntry.color` that could break out of the single
- * `background` declaration it's assigned to — `;`, `{`, and `}` are all a
- * value needs to terminate that declaration and start another. This matters
- * even though the swatch's color is set via Lit's `styleMap` directive (not
- * raw string interpolation): `styleMap`'s first commit for a given
- * attribute part serializes the whole `style` value as a single string
+ * Matches only actual CSS color syntax: hex (`#fff`/`#ffffff`/`#ffffffff`),
+ * bare keywords (named colors, `transparent`, `currentColor`), the standard
+ * color functions, and `var(--custom-property)` references. Anything else --
+ * notably `url(...)`, which is otherwise valid `background` syntax -- is
+ * rejected.
+ */
+const SAFE_SWATCH_COLOR = /^(?:#[0-9a-fA-F]{3,8}|[a-zA-Z]+|(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch)\([-+0-9.%,/\s]+\)|var\(--[\w-]+\))$/;
+/**
+ * Rejects a `LegendEntry.color` that isn't recognizable CSS color syntax --
+ * both to stop it breaking out of the single `background` declaration it's
+ * assigned to (e.g. `;`, `{`, `}`, which terminate/reopen a declaration) and
+ * to stop non-color values such as `url(...)` from being accepted, which
+ * `background` also parses and would fetch as soon as the swatch renders.
+ * This matters even though the swatch's color is set via Lit's `styleMap`
+ * directive (not raw string interpolation): `styleMap`'s first commit for a
+ * given attribute part serializes the whole `style` value as a single string
  * (only later updates go through the safe `CSSStyleDeclaration.setProperty()`
  * path), so an unsanitized value could still inject on that first render.
  */
 function sanitizeSwatchColor(color) {
-    return /[;{}]/.test(color) ? undefined : color;
+    return SAFE_SWATCH_COLOR.test(color.trim()) ? color : undefined;
 }
 /**
  * `<lyra-map>` — a maplibre-gl wrapper with a declarative legend and
@@ -207,19 +217,34 @@ export class LyraMap extends LyraElement {
         if (this._appliedChoroplethSourceId && this._appliedChoroplethSourceId !== sourceId) {
             this.removeChoropleth();
         }
-        const colorExpr = ['interpolate', ['linear'], ['get', field]];
-        for (const [value, color] of stops)
-            colorExpr.push(value, color);
         const existingSource = this._map.getSource(sourceId);
         if (existingSource) {
-            // Re-apply both the data and the color expression: `field`/`stops` may have
-            // changed even though `sourceId` didn't (e.g. switching which metric colors
-            // the same GeoJSON), so the paint property must be refreshed too.
+            // Re-apply the data even if the color expression below ends up skipped:
+            // `geojson` may have changed even though `sourceId`/`stops` didn't.
             existingSource.setData(geojson);
-            this._map.setPaintProperty(fillLayerId, 'fill-color', colorExpr);
         }
         else {
             this._map.addSource(sourceId, { type: 'geojson', data: geojson, promoteId: 'id' });
+        }
+        this._appliedChoroplethSourceId = sourceId;
+        // An `interpolate` expression needs at least one [value, color] stop pair
+        // -- maplibre-gl's own expression parser requires it and otherwise fires a
+        // silently-ignored ErrorEvent instead of throwing (`addLayer`/
+        // `setPaintProperty` just no-op), so an empty `stops` would otherwise
+        // "succeed" here without ever creating/updating the fill layer, and every
+        // later update (valid `stops`, same `sourceId`) would find `existingSource`
+        // and wrongly assume `setPaintProperty` has a real layer to target. Bail
+        // before touching the layer at all and leave whatever fill layer already
+        // exists (if any) untouched until `stops` is non-empty again.
+        if (stops.length === 0)
+            return;
+        const colorExpr = ['interpolate', ['linear'], ['get', field]];
+        for (const [value, color] of stops)
+            colorExpr.push(value, color);
+        if (this._map.getLayer(fillLayerId)) {
+            this._map.setPaintProperty(fillLayerId, 'fill-color', colorExpr);
+        }
+        else {
             this._map.addLayer({
                 id: fillLayerId,
                 type: 'fill',
@@ -227,7 +252,6 @@ export class LyraMap extends LyraElement {
                 paint: { 'fill-color': colorExpr, 'fill-opacity': 0.75 },
             });
         }
-        this._appliedChoroplethSourceId = sourceId;
         this._appliedFillLayerId = fillLayerId;
     }
     /** Removes whatever choropleth layer/source is currently applied, if any. */
@@ -243,11 +267,18 @@ export class LyraMap extends LyraElement {
         this._appliedChoroplethSourceId = undefined;
         this._appliedFillLayerId = undefined;
     }
-    async applyMarkers() {
-        if (!this._map)
-            return;
-        const mod = await loadMaplibre();
-        if (!mod)
+    // Deliberately synchronous (no `await loadMaplibre()`): `_maplibreModule` is
+    // already cached by the time `_map` exists (both are set in the same
+    // connectedCallback closure, see above), and every caller here is
+    // fire-and-forget. Re-awaiting the loader would open a window between the
+    // `_map` check and the marker mutations below where a disconnect (which
+    // synchronously clears `_map`) could resume into a torn-down map -- staying
+    // synchronous closes that window by construction instead of re-checking
+    // after the fact.
+    applyMarkers() {
+        const map = this._map;
+        const mod = this._maplibreModule;
+        if (!map || !mod)
             return;
         const visible = new Set();
         for (const m of this.markers) {
@@ -264,11 +295,27 @@ export class LyraMap extends LyraElement {
                         popup.setText(m.label);
                     marker.setPopup(popup);
                 }
-                marker.addTo(this._map);
+                marker.addTo(map);
                 this._markerInstances.set(key, marker);
             }
             else {
                 existing.setLngLat(m.lngLat);
+                const popup = existing.getPopup();
+                if (m.html) {
+                    if (popup)
+                        popup.setHTML(m.html);
+                    else
+                        existing.setPopup(new mod.Popup({ offset: 12 }).setHTML(m.html));
+                }
+                else if (m.label) {
+                    if (popup)
+                        popup.setText(m.label);
+                    else
+                        existing.setPopup(new mod.Popup({ offset: 12 }).setText(m.label));
+                }
+                else if (popup) {
+                    existing.setPopup(undefined);
+                }
             }
         }
         for (const [key, marker] of this._markerInstances) {

package/dist/components/map/map.stories.d.ts

@@ -3,3 +3,13 @@ declare const meta: Meta;
 export default meta;
 type Story = StoryObj;
 export declare const Default: Story;
+/**
+ * `choropleth` adds a GeoJSON fill layer, colored by interpolating `field`'s
+ * value across `stops` -- pair it with `legend` to label the color ramp.
+ */
+export declare const Choropleth: Story;
+/**
+ * `markers` renders a pin per entry, each with an optional colored tint and
+ * an openable popup built from `label` (plain text) or `html` (raw markup).
+ */
+export declare const Markers: Story;

package/dist/components/map/map.stories.js

@@ -3,6 +3,18 @@ const legend = [
     { color: '#5b8def', label: 'Low' },
     { color: '#e5484d', label: 'High' },
 ];
+const RASTER_STYLE = {
+    version: 8,
+    sources: {
+        demo: {
+            type: 'raster',
+            tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
+            tileSize: 256,
+            attribution: '© OpenStreetMap contributors',
+        },
+    },
+    layers: [{ id: 'demo', type: 'raster', source: 'demo' }],
+};
 const meta = {
     title: 'Map',
     component: 'lyra-map',
@@ -23,18 +35,101 @@ export const Default = {
       center="[2.3522, 48.8566]"
       zoom="4"
       .legend=${legend}
-      .mapStyle=${{
-        version: 8,
-        sources: {
-            demo: {
-                type: 'raster',
-                tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
-                tileSize: 256,
-                attribution: '© OpenStreetMap contributors',
-            },
-        },
-        layers: [{ id: 'demo', type: 'raster', source: 'demo' }],
-    }}
+      .mapStyle=${RASTER_STYLE}
     ></lyra-map>
   `,
 };
+/**
+ * `choropleth` adds a GeoJSON fill layer, colored by interpolating `field`'s
+ * value across `stops` -- pair it with `legend` to label the color ramp.
+ */
+export const Choropleth = {
+    render: () => {
+        const choropleth = {
+            sourceId: 'regions',
+            field: 'value',
+            stops: [
+                [0, '#5b8def'],
+                [50, '#f2c94c'],
+                [100, '#e5484d'],
+            ],
+            geojson: {
+                type: 'FeatureCollection',
+                features: [
+                    {
+                        type: 'Feature',
+                        properties: { value: 20 },
+                        geometry: {
+                            type: 'Polygon',
+                            coordinates: [
+                                [
+                                    [2.25, 48.9],
+                                    [2.35, 48.9],
+                                    [2.35, 48.85],
+                                    [2.25, 48.85],
+                                    [2.25, 48.9],
+                                ],
+                            ],
+                        },
+                    },
+                    {
+                        type: 'Feature',
+                        properties: { value: 80 },
+                        geometry: {
+                            type: 'Polygon',
+                            coordinates: [
+                                [
+                                    [2.35, 48.9],
+                                    [2.45, 48.9],
+                                    [2.45, 48.85],
+                                    [2.35, 48.85],
+                                    [2.35, 48.9],
+                                ],
+                            ],
+                        },
+                    },
+                ],
+            },
+        };
+        return html `
+      <lyra-map
+        style="height: 20rem"
+        center="[2.3522, 48.8566]"
+        zoom="10"
+        .legend=${[
+            { color: '#5b8def', label: 'Low' },
+            { color: '#f2c94c', label: 'Medium' },
+            { color: '#e5484d', label: 'High' },
+        ]}
+        .choropleth=${choropleth}
+        .mapStyle=${RASTER_STYLE}
+      ></lyra-map>
+    `;
+    },
+};
+/**
+ * `markers` renders a pin per entry, each with an optional colored tint and
+ * an openable popup built from `label` (plain text) or `html` (raw markup).
+ */
+export const Markers = {
+    render: () => {
+        const markers = [
+            { id: 'eiffel', lngLat: [2.2945, 48.8584], label: 'Eiffel Tower' },
+            {
+                id: 'louvre',
+                lngLat: [2.3364, 48.8606],
+                color: '#e5484d',
+                html: '<strong>Louvre</strong><br>Museum',
+            },
+        ];
+        return html `
+      <lyra-map
+        style="height: 20rem"
+        center="[2.3522, 48.8566]"
+        zoom="12"
+        .markers=${markers}
+        .mapStyle=${RASTER_STYLE}
+      ></lyra-map>
+    `;
+    },
+};

package/dist/components/map/map.styles.js

@@ -26,7 +26,7 @@ export const styles = css `
     z-index: 1;
     display: flex;
     flex-direction: column;
-    gap: 0.2rem;
+    gap: var(--lyra-space-xs);
     padding: var(--lyra-space-xs) var(--lyra-space-s);
     background: var(--lyra-color-surface);
     border: 1px solid var(--lyra-color-border);
@@ -37,7 +37,7 @@ export const styles = css `
   .legend-row {
     display: flex;
     align-items: center;
-    gap: 0.35rem;
+    gap: var(--lyra-space-xs);
   }
   [part='legend-swatch'] {
     inline-size: 0.75rem;

package/dist/components/playback/playback.d.ts

@@ -6,8 +6,8 @@ import { LyraElement } from '../../internal/lyra-element.js';
  * play-timers in time-series dashboards.
  *
  * @customElement lyra-playback
- * @event lyra-play
- * @event lyra-pause
+ * @event lyra-play - Fired when playback starts.
+ * @event lyra-pause - Fired when playback stops (including auto-pause).
  * @event lyra-step - `detail: { index }`, fired on every tick and manual step.
  * @csspart base, play-button, slider
  */
@@ -27,13 +27,17 @@ export declare class LyraPlayback extends LyraElement {
      */
     hidden: boolean;
     private timer?;
+    /** Largest index reachable at the current `length` (never negative). */
+    private get maxIndex();
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     /** Start playback; no-op if there's nothing to advance through. */
     play(): void;
     /** Stop playback. */
     pause(): void;
+    /** Toggle between playing and paused. */
     toggle(): void;
+    private scheduleTick;
     private tick;
     private setIndex;
     /** Advance one step without starting playback. */