@aceshooting/lyra-ui 18.0.0 → 18.2.0

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

@@ -1,6 +1,11 @@
 import{type TemplateResult,type PropertyValues}from'lit';import type{Feature,FeatureCollection}from'geojson';import{LyraElement}from'../../../internal/lyra-element.js';import{type MapLibreGeoJsonDiff}from'./map-loader.js';import'../../overlays/skeleton/skeleton.class.js';
 /** Non-color encoding retained when a legend entry's authored color is unavailable. */
 export type LyraMapLegendPattern='solid'|'diagonal'|'dots'|'crosshatch';
+/**
+* Presentation role for each keyed `legendInteractive` row's toggle control. See the
+* `legendControlRole` property JSDoc for the full contract.
+*/
+export type LyraMapLegendControlRole='button'|'checkbox';
 /** One immutable, bounded map-legend row. Pattern is required so color is never the sole cue. */
 export interface LyraMapLegendEntry{readonly color:string;readonly label:string;readonly pattern:LyraMapLegendPattern;
 /**
@@ -37,7 +42,30 @@ readonly value?:string;
 * most 8192 characters. A glyph omission is not counted in `legendProjection` either, because
 * the row it belongs to still renders — only dropped rows are omissions.
 */
-readonly icon?:LyraMapPointIcon|Omit<LyraMapPointIcon,'value'>;}
+readonly icon?:LyraMapPointIcon|Omit<LyraMapPointIcon,'value'>;
+/**
+* Optional section this row belongs to. A key describing two layers at once could previously
+* only be one flat list, with nothing saying which rows belonged to which.
+*
+* **The grouping rule, which is pinned rather than inferred:** CONSECUTIVE entries sharing an
+* identical `group` render as one section -- a visible heading plus a `role="group"` the heading
+* names. An entry with no `group` keeps its DECLARED position: it is never hoisted above or sunk
+* below a section, and a `group` that reappears after an interruption opens a SECOND section
+* rather than reordering rows to merge them. Declaration order is the one thing the legend never
+* rewrites, because the order is itself information about the map.
+*
+* It is caller-supplied DATA, so it renders verbatim and is never passed through the locale
+* catalog. It is trimmed and bounded to 256 characters (ellipsized, since it is rendered prose
+* rather than a matched key); a non-string, empty or whitespace-only value leaves no `group` key
+* at all, so an empty string means "ungrouped" instead of an empty heading, and a legend that
+* never used sections reads back exactly as it did before this field existed.
+*
+* Like the row-level `value`, it is NOT charged to the aggregate label budget: a budget bounds
+* rendered text, and the rendered total here is already finite and stated -- at most one heading
+* per rendered row, so at most 100 of them, each at most 256 characters. A section is also not a
+* row: the 100-row cap and the `legend-limit` summary count rows, never sections.
+*/
+readonly group?:string;}
 /**
 * One `[value, color]` stop of a continuous legend ramp — deliberately the same shape as
 * `LyraMapChoroplethLayer['stops']`, so a consumer passes the choropleth's own stops straight
@@ -349,7 +377,15 @@ readonly value:string;
 /** Proposed visibility of `value` after this toggle. */
 readonly visible:boolean;
 /** Complete canonical proposed hidden-category set, in the order it would be committed. */
-readonly hiddenCategories:readonly string[];}export interface LyraMapEventMap{'lr-map-load':CustomEvent<null>;'lr-map-marker-activate':CustomEvent<LyraMapMarkerActivationDetail>;'lr-map-legend-toggle':CustomEvent<LyraMapLegendToggleDetail>;'lr-map-click':CustomEvent<{readonly lngLat:readonly[number,number];readonly feature:Feature|undefined;
+readonly hiddenCategories:readonly string[];}
+/**
+* Proposed disclosure state for the legend PANEL, which is a different thing from one category's
+* visibility -- hence its own detail type rather than a reuse of `LyraMapLegendToggleDetail`.
+* Frozen, and detached from the component's own state.
+*/
+export interface LyraMapLegendPanelToggleDetail{
+/** Proposed `legendOpen` after this activation. */
+readonly open:boolean;}export interface LyraMapEventMap{'lr-map-load':CustomEvent<null>;'lr-map-marker-activate':CustomEvent<LyraMapMarkerActivationDetail>;'lr-map-legend-toggle':CustomEvent<LyraMapLegendToggleDetail>;'lr-map-legend-panel-toggle':CustomEvent<LyraMapLegendPanelToggleDetail>;'lr-map-click':CustomEvent<{readonly lngLat:readonly[number,number];readonly feature:Feature|undefined;
 /** Which layer `feature` was hit on, so a click is attributable when both a choropleth and
 *  `dataLayers` are painted. `'cluster'` marks a hit on a clustered entry's aggregate circle,
 *  whose `point_count`/`cluster_id` properties describe the group rather than one feature.
@@ -405,6 +441,14 @@ readonly sourceId:string|undefined;}>;}
 *   before/after vocabulary would be permanent public surface nobody asked for. A programmatic
 *   `hiddenCategories` assignment reconciles without emitting anything -- this event is a
 *   DOM-interaction proposal only.
+* @event lr-map-legend-panel-toggle - **Cancelable.** Fired once when the `legendCollapsible`
+*   disclosure is activated by pointer or by Enter/Space, carrying the immutable
+*   `detail: { open }` -- the proposed `legendOpen` value. It is the *panel's* disclosure, not a
+*   *category's* visibility, so it deliberately does not reuse `lr-map-legend-toggle`.
+*   `preventDefault()` is a real veto: `legendOpen` is not written, the rendered rows and the
+*   disclosure's `aria-expanded` do not change, which is what lets a host own the open state and
+*   write it itself. A programmatic `legendOpen` assignment reconciles without emitting anything,
+*   so a controlled host cannot loop.
 * @event lr-map-marker-activate - Fired once when an accepted declarative marker is activated by
 *   pointer/click or by Enter/Space. The immutable detail carries its normalized `id`, validated
 *   `lngLat`, accepted marker snapshot, and activation `source`.
@@ -421,6 +465,11 @@ readonly sourceId:string|undefined;}>;}
 * @slot legend - Custom legend content, rendered inside the legend panel's own layout so it stays
 *  positioned with the map instead of floating beside it. Slotted content is never made
 *  interactive by `legendInteractive`, which only reaches rows projected from `legend`.
+* @slot legend-start - The same extension point at the TOP of the legend panel: it renders ahead
+*  of the gradient bar and every projected row, where `legend` renders after them. A panel header
+*  -- a title, a source note, a host-built control -- could previously only ever be a footer,
+*  because `legend` was the only slot. Content here alone opens the panel, exactly as `legend`
+*  content alone does, and it is never made interactive by `legendInteractive`.
 * @csspart legend - The map legend.
 * @csspart legend-swatch - A legend color swatch, or the entry's glyph when it carries an `icon`
 *   — in which case the swatch drops its color block and pattern overlay, keeps the `pattern`
@@ -433,6 +482,18 @@ readonly sourceId:string|undefined;}>;}
 * @csspart legend-toggle-hidden - Second token carried alongside `legend-toggle` while that row's
 *   category is in `hiddenCategories`. State lives in the part name rather than a separate
 *   attribute, so `::part(legend-toggle-hidden)` is a reachable styling hook.
+* @csspart legend-group - The `role="group"` wrapping one consecutive run of legend rows that
+*   share a `group`. Absent entirely when no admitted entry carries one, so an ungrouped legend's
+*   markup is unchanged.
+* @csspart legend-group-heading - The visible heading naming a `legend-group`. It renders the
+*   caller-supplied `group` string verbatim and names the group through `aria-labelledby`.
+* @csspart legend-disclosure - The `button` that collapses and expands the whole legend panel.
+*   Rendered only when `legendCollapsible` is set, so an unset map's legend markup is unchanged.
+*   It carries the localized panel name as its visible, accessible label plus `aria-expanded`
+*   rendered as the literal `"true"`/`"false"`, and it grows to the shared `--lr-icon-button-size`
+*   hit-area floor.
+* @csspart legend-disclosure-icon - The decorative chevron inside `legend-disclosure`. It is the
+*   wrapping part that rotates (per the shared icon set's contract), including under RTL.
 * @csspart legend-gradient - The continuous ramp bar rendered from `legendGradient`.
 * @csspart legend-lo - The low endpoint caption of the `legendGradient` bar (mirrors `lr-heatmap`).
 * @csspart legend-hi - The high endpoint caption of the `legendGradient` bar (mirrors `lr-heatmap`).
@@ -520,7 +581,7 @@ renderWorldCopies?:boolean;
 maxBounds:LyraMapBounds|null;
 /** Required MapLibre style URL or peer-neutral style specification. No provider is contacted
 * unless a consumer assigns this property. */
-mapStyle?:Readonly<LyraMapStyleSpecification> |string;private _legend;private _legendProjection;
+mapStyle?:Readonly<LyraMapStyleSpecification> |string;private _legend;private _legendProjection;private _legendGrouped;
 /** Immutable, bounded entries rendered in the optional map legend. A required pattern keeps
 * category identity available when authored colors collapse or are unavailable. */
 get legend():readonly LyraMapLegendEntry[];set legend(value:readonly LyraMapLegendEntry[]);
@@ -532,6 +593,9 @@ get legend():readonly LyraMapLegendEntry[];set legend(value:readonly LyraMapLege
 * it. `slotchange` still runs afterwards to track content added or removed later.
 */
 private hasLegendSlot;
+/** The same presence flag for `slot="legend-start"`, tracked separately so a header alone opens
+*  the panel and so the two extension points never stand in for one another. */
+private hasLegendStartSlot;
 /** Light-DOM probe for slotted legend content, valid before the slot itself has ever rendered. */
 private probeLegendSlot;private _legendGradient;
 /**
@@ -573,7 +637,72 @@ get legendProjection():LyraMapLegendProjection;
 * 100-series `lr-chart` legend does. Each row also grows to the `--lr-icon-button-size` hit-area
 * floor; the legend panel's own `max-block-size`/`overflow: auto` contains the taller list.
 */
-legendInteractive:boolean;private _hiddenCategories;
+legendInteractive:boolean;private _legendControlRole;
+/**
+* How each keyed `legendInteractive` row's toggle control presents itself to assistive tech.
+* Inert while `legendInteractive` is unset, exactly like the toggle itself.
+*
+* - `'button'` (default) -- `<button aria-pressed>`, byte-identical to every 18.1.0 interactive
+*   legend. Leaving this property unset changes nothing.
+* - `'checkbox'` -- the SAME `<button>` element `renderLegendRow()` already renders, with its
+*   implicit role overridden to `role="checkbox"` and `aria-checked` in place of `aria-pressed`.
+*   A native `<input type="checkbox">` was considered and rejected: it would need its own
+*   swatch/label markup and its own click/keyboard wiring duplicated from the button branch,
+*   splitting `renderLegendRowContent()` in two. `<button role="checkbox">` keeps the swatch,
+*   the label, the click handler and the platform's own Enter/Space activation exactly as they
+*   are for the button branch -- only the two ARIA attributes differ, so the CSS in
+*   `map.styles.ts` (which targets `button[part~='legend-toggle']`, never a role or an ARIA
+*   state) needs no `'checkbox'`-specific rule.
+*
+* `aria-checked` tracks the same `visible` flag `aria-pressed` does, inverted from
+* `hiddenCategories`: a hidden category renders `aria-checked="false"`. Both states always
+* render explicitly (`"true"`/`"false"`), never a Lit `?aria-*` presence directive, which cannot
+* express the false state at all.
+*/
+get legendControlRole():LyraMapLegendControlRole;set legendControlRole(next:LyraMapLegendControlRole);
+/**
+* Renders a disclosure button inside the legend panel that collapses the key down to its header.
+* Default `false`, and an unset map renders exactly the panel it rendered before this property
+* existed -- no button, no `id` minted on the row list, and no `hidden` attribute anywhere.
+*
+* A collapsed panel hides the gradient bar, the rows, the `legend-limit` summary and the
+* trailing `legend` slot; the `legend-start` slot and the disclosure itself stay visible, so a
+* slotted header survives the collapse and the control that would restore the key is never the
+* thing the collapse hides.
+*/
+legendCollapsible:boolean;
+/**
+* Whether a `legendCollapsible` panel is expanded. Defaults **open**, so adding only
+* `legendCollapsible` never hides an existing key; it does nothing at all while
+* `legendCollapsible` is unset.
+*
+* It is a `true`-defaulting boolean, so it uses `trueDefaultBooleanConverter` rather than Lit's
+* presence-based boolean converter, which cannot express `legend-open="false"` at all. The
+* reflection follows the same converter: open (the default) reflects as an ABSENT attribute and
+* collapsed reflects as `legend-open="false"`.
+*
+* Controlled public state, so -- exactly like `hiddenCategories` -- it deliberately survives a
+* disconnect and reconnect: the "reset transient open-state in `disconnectedCallback()`" rule
+* covers dropdown/preview/tooltip `@state`, not a documented property a host owns and re-reads.
+* A programmatic assignment reconciles the rendered panel without emitting
+* `lr-map-legend-panel-toggle`, so a controlled host cannot loop.
+*/
+legendOpen:boolean;
+/** True only when a collapsible panel is actually collapsed. `legendOpen` alone never hides
+*  anything, so an author who sets `legend-open="false"` without `legendCollapsible` -- and
+*  therefore renders no control to restore it -- still gets a readable key. */
+private get legendCollapsed();
+/**
+* Flips the whole panel's disclosure from the `legendCollapsible` button.
+*
+* The veto is the absence of a write, not a write that is undone afterwards: a listener that
+* owns the open state can assign its own `legendOpen` without this handler clobbering it.
+*/
+private toggleLegendPanel;
+/** The panel disclosure, or nothing at all when the panel cannot collapse. The chevron is
+*  decorative: the button's own visible, localized text carries its name, and `aria-expanded`
+*  carries the state. */
+private renderLegendDisclosure;private _hiddenCategories;
 /**
 * Complete controlled set of muted category keys, mirroring `lr-chart`'s `hiddenDatasets`.
 * Clone-owned and frozen; non-string, empty, whitespace-only and duplicate entries are dropped,
@@ -812,4 +941,31 @@ private toggleLegendCategory;
 private announceLegendVisibility;
 /** Acquired lazily on the first toggle, and re-acquired against a new owner document, so a map
 *  that never renders an interactive legend never mounts a live region at all. */
-private syncLegendAnnouncementSink;private releaseLegendAnnouncementSink;private renderLegendGradient;render():TemplateResult;}declare global{interface HTMLElementTagNameMap{'lr-map':LyraMap;}}
+private syncLegendAnnouncementSink;private releaseLegendAnnouncementSink;
+/**
+* One legend row. Extracted verbatim from the list template so the grouped and ungrouped section
+* paths below render the same node rather than two copies that can drift.
+*
+* `aria-posinset`/`aria-setsize` deliberately stay whole-key values inside a section too.
+* `aria-setsize` already reports the *input* count rather than the rendered one, so a bounded key
+* stays honest; per-section input counts do not exist, because a row dropped by the bound carries
+* no attributable group. A section adds a labelled sub-region; it does not renumber the key.
+*/
+private renderLegendRow;
+/**
+* The row list's children: bare rows when no admitted entry carries a `group`, and otherwise one
+* `role="group"` per CONSECUTIVE run sharing a group name, with ungrouped rows left exactly where
+* they were declared. The ungrouped branch is literally the expression this list has always been,
+* so a legend that uses no sections keeps rendering the markup it rendered before they existed.
+*
+* `group` is caller-supplied data: the heading renders it verbatim and never resolves it through
+* the locale catalog.
+*
+* Each section owns its OWN `role="list"` rather than the sections sitting directly inside the
+* outer one. `list` requires `listitem` children, and a `group` is not one -- axe reports both
+* `aria-required-children` on the outer list and `aria-required-parent` on every row inside the
+* group, critical, which is how this shape was caught. So a grouped legend renders one list per
+* run (including each ungrouped run) and the outer element drops its own `role`, while an
+* ungrouped legend keeps the single `role="list"` it has always had.
+*/
+private renderLegendRows;private renderLegendGradient;render():TemplateResult;}declare global{interface HTMLElementTagNameMap{'lr-map':LyraMap;}}