ol-layer-control 0.1.0

package/types/ol-layer-control.d.ts

@@ -0,0 +1,451 @@
+/**
+ * All user-visible strings. Pass a (partial) object with the same keys as
+ * the `i18n` option to translate the UI.
+ *
+ * @typedef {Object} LayerControlI18n
+ * @property {string} buttonTitle   Tooltip / accessible name of the map button.
+ * @property {string} panelTitle    Heading of the panel.
+ * @property {string} closeTitle    Tooltip of the close button.
+ * @property {string} resizeTitle   Tooltip of the resize handle.
+ * @property {string} collapseTitle Tooltip of the fold button when a group is expanded.
+ * @property {string} expandTitle   Tooltip of the fold button when a group is collapsed.
+ * @property {string} exclusiveHint Tooltip of a group title when it can be right-clicked
+ *     to switch between exclusive and non-exclusive.
+ * @property {string} outOfRangeHint Tooltip of a layer that is not shown at the
+ *     current zoom level (outside its min/max resolution or zoom).
+ * @property {string} groupOffHint Tooltip of a layer inside a switched-off group.
+ *     `{group}` is replaced by the title of that group.
+ * @property {string} opacityTitle Tooltip of the opacity button and label of the slider.
+ * @property {string} searchToggleTitle Tooltip of the panel title (click shows/hides the search box).
+ * @property {string} searchPlaceholder Placeholder text of the search box.
+ * @property {string} searchClearTitle Tooltip of the button that clears the search box.
+ * @property {string} searchNoResults Message shown when no layer matches the search.
+ */
+/** @type {LayerControlI18n} */
+export const DEFAULT_I18N: LayerControlI18n;
+/**
+ * Where the map button sits on the map. Each position leaves room for the
+ * OpenLayers default control that normally occupies that corner:
+ *
+ *   'top-left'      below the Zoom buttons
+ *   'bottom-left'   in the bottom-left corner
+ *   'top-right'     in the top-right corner (shared with the Rotate button,
+ *                   which only shows when the map is rotated)
+ *   'right'         top-right, below the Rotate button
+ *   'bottom-right'  above the Attribution button
+ *
+ * @typedef {'top-left'|'bottom-left'|'top-right'|'right'|'bottom-right'} ButtonPosition
+ */
+/** @type {ReadonlyArray<ButtonPosition>} */
+export const BUTTON_POSITIONS: ReadonlyArray<ButtonPosition>;
+/**
+ * Layer control: a map button plus a docked, resizable side panel.
+ *
+ * Observable properties (use `control.on('change:open', ...)` etc.):
+ *   - `open`       boolean, whether the panel is shown
+ *   - `panelWidth` number, current panel width in pixels
+ *
+ * @extends {Control}
+ */
+export default class LayerControl extends Control {
+    /**
+     * @param {LayerControlOptions} [options]
+     */
+    constructor(options?: LayerControlOptions);
+    /** @private @type {LayerControlI18n} */
+    private i18n_;
+    /** @private @type {'left'|'right'} */
+    private side_;
+    /** @private @type {ButtonPosition} */
+    private defaultButtonPosition_;
+    /** @private */
+    private defaultPanelWidth_;
+    /** @private */
+    private minPanelWidth_;
+    /** @private */
+    private maxPanelWidth_;
+    /** @private */
+    private resizable_;
+    /** @private */
+    private reverse_;
+    /** @private */
+    private exclusiveToggle_;
+    /** @private */
+    private opacitySlider_;
+    /** @private @type {HTMLElement|null} */
+    private panelTarget_;
+    /** @private @type {HTMLElement|null} The map's target element we shrink. */
+    private hostElement_;
+    /** @private @type {{width: string, marginLeft: string}|null} */
+    private hostSavedStyle_;
+    /** @private @type {Array<import('ol/events.js').EventsKey>} */
+    private mapListenerKeys_;
+    /** @private @type {Array<import('ol/events.js').EventsKey>} */
+    private layerListenerKeys_;
+    /** @private */
+    private rebuildScheduled_;
+    /** @private */
+    private layoutScheduled_;
+    /** @private @type {Array<HTMLButtonElement>} */
+    private foldButtons_;
+    /** @private @type {Array<{layer: import('ol/layer/Base.js').default, parent: LayerGroup|null, item: HTMLElement, label: HTMLElement}>} */
+    private entries_;
+    /** @private @type {Map<import('ol/layer/Base.js').default, LayerGroup|null>} */
+    private parents_;
+    /** @private @type {Array<import('ol/events.js').EventsKey>} */
+    private viewListenerKeys_;
+    /** @private @type {HTMLElement|null} */
+    private resizer_;
+    /** @private @type {HTMLButtonElement} */
+    private button_;
+    /** @private @type {HTMLElement} */
+    private panel_;
+    /** @private @type {HTMLButtonElement} */
+    private titleElement_;
+    /** @private @type {HTMLButtonElement} */
+    private closeButton_;
+    /** @private @type {HTMLElement} */
+    private searchRow_;
+    /** @private @type {HTMLInputElement} */
+    private searchInput_;
+    /** @private @type {HTMLButtonElement} */
+    private searchClear_;
+    /** @private @type {HTMLElement} */
+    private rootList_;
+    /** @private @type {HTMLElement} */
+    private noResults_;
+    /** Show the panel. */
+    open(): void;
+    /** Hide the panel. */
+    close(): void;
+    /** Show the panel if hidden, hide it if shown. */
+    toggle(): void;
+    /** @return {boolean} Whether the panel is shown. */
+    isOpen(): boolean;
+    /**
+     * @param {number} width Panel width in pixels (clamped to min/max).
+     */
+    setPanelWidth(width: number): void;
+    /** @return {number} Current panel width in pixels. */
+    getPanelWidth(): number;
+    /** @return {HTMLElement} The panel element. */
+    getPanelElement(): HTMLElement;
+    /**
+     * Move the map button. An unknown value falls back to the default for the
+     * panel's side.
+     * @param {ButtonPosition} position
+     */
+    setButtonPosition(position: ButtonPosition): void;
+    /** @return {ButtonPosition} Where the map button sits. */
+    getButtonPosition(): ButtonPosition;
+    /**
+     * Show or hide the search box. Hiding it clears the filter.
+     * @param {boolean} [visible=true]
+     */
+    showSearch(visible?: boolean): void;
+    /** Show the search box if hidden, hide it if shown. */
+    toggleSearch(): void;
+    /** @return {boolean} Whether the search box is shown. */
+    isSearchVisible(): boolean;
+    /**
+     * Filter the layer list by (part of) a title, case-insensitive. Groups
+     * stay listed when their title or any of their layers match.
+     * @param {string} query Empty string shows everything.
+     */
+    setFilter(query: string): void;
+    /** @return {string} The current filter text. */
+    getFilter(): string;
+    /**
+     * Replace (part of) the UI strings.
+     * @param {Partial<LayerControlI18n>} i18n
+     */
+    setI18n(i18n: Partial<LayerControlI18n>): void;
+    /** @return {LayerControlI18n} The strings in use. */
+    getI18n(): LayerControlI18n;
+    /**
+     * Rebuild the layer list from the map. Normally not needed: the control
+     * follows layer additions, removals and visibility changes by itself.
+     */
+    refresh(): void;
+    /**
+     * Make a layer group exclusive (children as radio buttons, at most one
+     * visible) or non-exclusive (checkboxes). When switching to exclusive and
+     * several children are visible, only the top-most one stays visible.
+     *
+     * Basemap groups (children with `type: 'base'`) are always exclusive.
+     *
+     * @param {LayerGroup} group
+     * @param {boolean} exclusive
+     */
+    setExclusive(group: LayerGroup, exclusive: boolean): void;
+    /** @private Follow the (possibly new) view's resolution. */
+    private observeView_;
+    /**
+     * Dim entries that are outside their resolution/zoom range and explain,
+     * in a tooltip, why an entry is not shown on the map (out of range and/or
+     * inside a switched-off group).
+     * @private
+     */
+    private updateStates_;
+    /** @private */
+    private attachPanel_;
+    /** @private */
+    private restoreHost_;
+    /** @private */
+    private detach_;
+    /** @private */
+    private scheduleLayout_;
+    /** @private */
+    private applyLayout_;
+    /**
+     * @private
+     * @param {number} width
+     * @return {number}
+     */
+    private clampWidth_;
+    /**
+     * @private
+     * @param {HTMLElement} handle
+     */
+    private initResizer_;
+    /** @private */
+    private applyTexts_;
+    /**
+     * @private
+     * @param {string|undefined} position
+     * @return {ButtonPosition}
+     */
+    private normalizeButtonPosition_;
+    /** @private */
+    private applyButtonPosition_;
+    /** @private */
+    private applySearchVisibility_;
+    /** @private Show only entries that match the search text. */
+    private applyFilter_;
+    /** @private */
+    private clearLayerListeners_;
+    /** @private */
+    private scheduleRebuild_;
+    /** @private */
+    private rebuild_;
+    /**
+     * @private
+     * @param {import('ol/layer/Base.js').default} layer
+     * @param {LayerGroup|null} parent
+     * @param {HTMLElement} item
+     * @param {HTMLElement} label
+     */
+    private registerEntry_;
+    /**
+     * @private
+     * @param {import('ol/Collection.js').default<import('ol/layer/Base.js').default>} collection
+     * @param {HTMLElement} list The <ul> to render into.
+     * @param {string|null} radioName Non-null when the parent group is exclusive.
+     * @param {LayerGroup|null} parent The group that owns the collection.
+     */
+    private renderCollection_;
+    /**
+     * The layers of a collection that appear in the panel, in panel order.
+     * @private
+     * @param {import('ol/Collection.js').default<import('ol/layer/Base.js').default>} collection
+     * @return {Array<import('ol/layer/Base.js').default>}
+     */
+    private listedLayers_;
+    /**
+     * @private
+     * @param {LayerGroup} group
+     * @return {Array<import('ol/layer/Base.js').default>}
+     */
+    private listedChildren_;
+    /**
+     * @private
+     * @param {import('ol/layer/Base.js').default} layer
+     * @param {Array<import('ol/layer/Base.js').default>} siblings Rendered siblings, incl. the layer itself.
+     * @param {HTMLElement} list
+     * @param {string|null} radioName
+     * @param {LayerGroup|null} parent
+     */
+    private renderLayer_;
+    /**
+     * Adds an opacity button to the row and a (collapsed) slider row to the item.
+     * @private
+     * @param {import('ol/layer/Base.js').default} layer
+     * @param {HTMLElement} item The <li>.
+     * @param {HTMLElement} row The row holding the input and label.
+     */
+    private addOpacitySlider_;
+    /**
+     * @private
+     * @param {LayerGroup} group
+     * @param {Array<import('ol/layer/Base.js').default>} siblings
+     * @param {HTMLElement} list
+     * @param {string|null} radioName
+     * @param {LayerGroup|null} parent
+     */
+    private renderGroup_;
+    /**
+     * @private
+     * @param {import('ol/layer/Base.js').default} layer
+     * @param {Array<import('ol/layer/Base.js').default>} siblings
+     * @param {string|null} radioName
+     * @return {HTMLInputElement}
+     */
+    private createInput_;
+    /**
+     * @private
+     * @param {import('ol/layer/Base.js').default} layer
+     * @param {HTMLInputElement|null} input
+     * @return {HTMLElement}
+     */
+    private createLabel_;
+    /**
+     * @private
+     * @param {HTMLButtonElement} button
+     */
+    private updateFoldButton_;
+}
+/**
+ * All user-visible strings. Pass a (partial) object with the same keys as
+ * the `i18n` option to translate the UI.
+ */
+export type LayerControlI18n = {
+    /**
+     * Tooltip / accessible name of the map button.
+     */
+    buttonTitle: string;
+    /**
+     * Heading of the panel.
+     */
+    panelTitle: string;
+    /**
+     * Tooltip of the close button.
+     */
+    closeTitle: string;
+    /**
+     * Tooltip of the resize handle.
+     */
+    resizeTitle: string;
+    /**
+     * Tooltip of the fold button when a group is expanded.
+     */
+    collapseTitle: string;
+    /**
+     * Tooltip of the fold button when a group is collapsed.
+     */
+    expandTitle: string;
+    /**
+     * Tooltip of a group title when it can be right-clicked
+     * to switch between exclusive and non-exclusive.
+     */
+    exclusiveHint: string;
+    /**
+     * Tooltip of a layer that is not shown at the
+     * current zoom level (outside its min/max resolution or zoom).
+     */
+    outOfRangeHint: string;
+    /**
+     * Tooltip of a layer inside a switched-off group.
+     * `{group}` is replaced by the title of that group.
+     */
+    groupOffHint: string;
+    /**
+     * Tooltip of the opacity button and label of the slider.
+     */
+    opacityTitle: string;
+    /**
+     * Tooltip of the panel title (click shows/hides the search box).
+     */
+    searchToggleTitle: string;
+    /**
+     * Placeholder text of the search box.
+     */
+    searchPlaceholder: string;
+    /**
+     * Tooltip of the button that clears the search box.
+     */
+    searchClearTitle: string;
+    /**
+     * Message shown when no layer matches the search.
+     */
+    searchNoResults: string;
+};
+export type LayerControlOptions = {
+    /**
+     * Where to render the map button
+     * (standard OpenLayers control option). Default: the map's control container.
+     */
+    target?: HTMLElement | string;
+    /**
+     * Element (or element id) to
+     * render the panel into. When set, the control leaves the map element
+     * alone and the host page is responsible for the layout.
+     */
+    panelTarget?: HTMLElement | string;
+    /**
+     * Side of the map the panel docks to.
+     */
+    side?: "left" | "right";
+    /**
+     * Where the map button sits. Defaults to
+     * `'top-left'` when `side` is `'left'` and `'right'` otherwise.
+     */
+    buttonPosition?: ButtonPosition;
+    /**
+     * Initial panel width in pixels.
+     */
+    panelWidth?: number;
+    /**
+     * Smallest width the user can resize to.
+     */
+    minPanelWidth?: number;
+    /**
+     * Largest width the user can resize to.
+     */
+    maxPanelWidth?: number;
+    /**
+     * Show a drag handle to resize the panel.
+     */
+    resizable?: boolean;
+    /**
+     * Start with the panel open.
+     */
+    open?: boolean;
+    /**
+     * List layers top-most first (rendering order reversed).
+     */
+    reverse?: boolean;
+    /**
+     * Let the user switch a group between
+     * exclusive (radio buttons) and non-exclusive (checkboxes) by right-clicking
+     * its title. Basemap groups are always exclusive.
+     */
+    exclusiveToggle?: boolean;
+    /**
+     * Give every layer a button that reveals
+     * an opacity slider.
+     */
+    opacitySlider?: boolean;
+    /**
+     * Show the search box from the start. The user
+     * can always show or hide it by clicking the panel title.
+     */
+    search?: boolean;
+    /**
+     * Translations, see {@link DEFAULT_I18N}.
+     */
+    i18n?: Partial<LayerControlI18n>;
+};
+/**
+ * Where the map button sits on the map. Each position leaves room for the
+ * OpenLayers default control that normally occupies that corner:
+ *
+ *   'top-left'      below the Zoom buttons
+ *   'bottom-left'   in the bottom-left corner
+ *   'top-right'     in the top-right corner (shared with the Rotate button,
+ *                   which only shows when the map is rotated)
+ *   'right'         top-right, below the Rotate button
+ *   'bottom-right'  above the Attribution button
+ */
+export type ButtonPosition = "top-left" | "bottom-left" | "top-right" | "right" | "bottom-right";
+import Control from 'ol/control/Control.js';
+import LayerGroup from 'ol/layer/Group.js';