xv-webcomponents 1.22.2 → 1.22.4-qa.0

package/dist/types/components.d.ts

@@ -9,6 +9,7 @@ import { SIZE_VAR_STR, XV_SORT_DIR } from "./types/enum";
 import { XvDataTableCheck, XvDataTableReorder } from "./components/xv-data-table/_vars";
 import { DropdownItemData } from "./components/xv-dropdown/_vars";
 import { XvFileUploaderVariants } from "./components/xv-file-uploader/_vars";
+import { GeoMapSelection } from "./components/xv-geo-map/xv-geo-map";
 import { MenuItem } from "./components/xv-mega-menu-next/xv-mega-menu-next.model";
 import { NOTIFICATION_VARIANTS_STR } from "./components/xv-notification/_vars";
 import { OverflowMenuEvent, OverflowMenuVariant } from "./components/xv-overflow-menu/_vars";
@@ -22,6 +23,7 @@ export { SIZE_VAR_STR, XV_SORT_DIR } from "./types/enum";
 export { XvDataTableCheck, XvDataTableReorder } from "./components/xv-data-table/_vars";
 export { DropdownItemData } from "./components/xv-dropdown/_vars";
 export { XvFileUploaderVariants } from "./components/xv-file-uploader/_vars";
+export { GeoMapSelection } from "./components/xv-geo-map/xv-geo-map";
 export { MenuItem } from "./components/xv-mega-menu-next/xv-mega-menu-next.model";
 export { NOTIFICATION_VARIANTS_STR } from "./components/xv-notification/_vars";
 export { OverflowMenuEvent, OverflowMenuVariant } from "./components/xv-overflow-menu/_vars";
@@ -362,6 +364,10 @@ export namespace Components {
     interface XvDatepicker {
         "block"?: boolean;
         "disabled"?: boolean;
+        /**
+          * Individual dates to disable within the min/max range. Each entry may be a `Date`, a bare 'yyyy-MM-dd' string, or a full ISO string — all normalised to a local 'yyyy-MM-dd' key that matches the calendar grid. Composes with min/max: a day is selectable only when it is inside the range AND not listed here (e.g. to allow only certain weekdays / block holidays).
+         */
+        "disabledDates"?: (Date | string)[];
         /**
           * Error status. Can be boolean or string
          */
@@ -481,6 +487,7 @@ export namespace Components {
           * @default []
          */
         "files": File[];
+        "helper"?: string;
         "label"?: string;
         /**
           * @default []
@@ -506,9 +513,110 @@ export namespace Components {
           * @default XvFileUploaderVariants.BUTTON
          */
         "variant": XvFileUploaderVariants;
+        "warning"?: string | boolean;
     }
     interface XvFooter {
     }
+    /**
+     * Minimal ATV planner map: MapLibre + PLZ boundaries from the XvGeoTool API.
+     * Click a PLZ to (de)select it. No further UI — selection state and reach
+     * data are emitted via `changeSelection` for the host page to display.
+     * MapLibre (~250 KB gzip) is loaded lazily when the component scrolls near
+     * the viewport, so the host page's initial load stays untouched.
+     */
+    interface XvGeoMapV2 {
+        /**
+          * Base URL of the geo API (Xv.Api v1/geo — contract-compatible with the XvGeoTool API). Default is the same-origin Front Door route, so no CORS is involved on crossvertise pages.
+          * @default '/api-fd/v1/geo'
+         */
+        "apiBase": string;
+        /**
+          * @default '© CARTO, © OpenStreetMap contributors'
+         */
+        "attribution": string;
+        /**
+          * @default 51.16
+         */
+        "centerLat": number;
+        /**
+          * Initial map center
+          * @default 10.45
+         */
+        "centerLng": number;
+        /**
+          * Remove the optimizer proposal highlight.
+         */
+        "clearPreview": () => Promise<void>;
+        /**
+          * Clear the whole selection.
+         */
+        "clearSelection": () => Promise<void>;
+        /**
+          * Indicator whose per-unit values feed the tooltips and the emitted population sum (e.g. ATV_DEVICES)
+          * @default 'MBI_P_T_2025'
+         */
+        "indicator": string;
+        /**
+          * Unit label shown behind the indicator value in the tooltip
+          * @default 'Einwohner'
+         */
+        "indicatorLabel": string;
+        /**
+          * Label language for the vector basemap (OpenMapTiles `name:{lang}` attribute, falling back to the place's local name). Empty string keeps the style's own labels.
+          * @default 'de'
+         */
+        "language": string;
+        /**
+          * Load the map bundle only when scrolled near the viewport (default: true)
+          * @default true
+         */
+        "lazy": boolean;
+        /**
+          * Geo level to display and select: plz5, gemeinde, kreis, regbez, bundesland
+          * @default 'plz5'
+         */
+        "level": string;
+        /**
+          * Highlight what a radius extension would ADD (optimizer proposal): the units within `km` that are not part of the selection render in the preview color. Visual only — the selection and its change events stay untouched. Returns the number of added units.
+         */
+        "previewByRadius": (startPlz: string, km: number) => Promise<number>;
+        /**
+          * Shape resolution: medium = simplified geometry (snappy), high = originals
+          * @default 'medium'
+         */
+        "resolution": 'medium' | 'high';
+        /**
+          * Select all PLZs within `km` around a start PLZ ("Umkreis"). Replaces the selection unless `add` is true.
+         */
+        "selectByRadius": (startPlz: string, km: number, add?: boolean) => Promise<GeoMapSelection | null>;
+        /**
+          * Select an explicit list of PLZs ("PLZ-Liste" paste, query-param restore). Replaces the selection unless `add` is true.
+         */
+        "selectPostalCodes": (codes: string[], add?: boolean) => Promise<GeoMapSelection | null>;
+        /**
+          * Minimum zoom before boundaries are loaded and selectable (use ~5 for bundesland, 9 for plz5)
+          * @default 9
+         */
+        "selectZoom": number;
+        /**
+          * MapLibre style URL for the vector basemap. Default: OpenFreeMap Positron — the same pale data-overlay look as the previous CARTO light, free for commercial use, no API key (openfreemap.org). Set to an empty string to fall back to the raster `tiles` path.
+          * @default 'https://tiles.openfreemap.org/styles/positron'
+         */
+        "styleUrl": string;
+        /**
+          * Raster tile URL template, used only when `style-url` is empty. The former CARTO default now watermarks keyless traffic ("API KEY REQUIRED"), so this path needs a keyed/licensed tile URL.
+          * @default 'https://basemaps.cartocdn.com/rastertiles/light_all/{z}/{x}/{y}@2x.png'
+         */
+        "tiles": string;
+        /**
+          * Explicit URL of maplibre-gl-worker.mjs (maplibre-gl-shared.mjs must sit next to it). Needed when the host bundler relocates the maplibre chunk so import.meta.url-relative worker resolution breaks (e.g. Angular/Vite dev server).
+         */
+        "workerUrl"?: string;
+        /**
+          * @default 5.5
+         */
+        "zoom": number;
+    }
     interface XvHeader {
     }
     /**
@@ -1213,6 +1321,10 @@ export interface XvFileUploaderCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXvFileUploaderElement;
 }
+export interface XvGeoMapV2CustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXvGeoMapV2Element;
+}
 export interface XvHeaderCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXvHeaderElement;
@@ -1608,6 +1720,31 @@ declare global {
         prototype: HTMLXvFooterElement;
         new (): HTMLXvFooterElement;
     };
+    interface HTMLXvGeoMapV2ElementEventMap {
+        "changeSelection": GeoMapSelection;
+        "mapReady": void;
+    }
+    /**
+     * Minimal ATV planner map: MapLibre + PLZ boundaries from the XvGeoTool API.
+     * Click a PLZ to (de)select it. No further UI — selection state and reach
+     * data are emitted via `changeSelection` for the host page to display.
+     * MapLibre (~250 KB gzip) is loaded lazily when the component scrolls near
+     * the viewport, so the host page's initial load stays untouched.
+     */
+    interface HTMLXvGeoMapV2Element extends Components.XvGeoMapV2, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXvGeoMapV2ElementEventMap>(type: K, listener: (this: HTMLXvGeoMapV2Element, ev: XvGeoMapV2CustomEvent<HTMLXvGeoMapV2ElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXvGeoMapV2ElementEventMap>(type: K, listener: (this: HTMLXvGeoMapV2Element, ev: XvGeoMapV2CustomEvent<HTMLXvGeoMapV2ElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXvGeoMapV2Element: {
+        prototype: HTMLXvGeoMapV2Element;
+        new (): HTMLXvGeoMapV2Element;
+    };
     interface HTMLXvHeaderElementEventMap {
         "xvMetaNavUpdate": any;
     }
@@ -2100,6 +2237,7 @@ declare global {
         "xv-dropdown-v2-item": HTMLXvDropdownV2ItemElement;
         "xv-file-uploader": HTMLXvFileUploaderElement;
         "xv-footer": HTMLXvFooterElement;
+        "xv-geo-map-v2": HTMLXvGeoMapV2Element;
         "xv-header": HTMLXvHeaderElement;
         "xv-header-next": HTMLXvHeaderNextElement;
         "xv-image-viewer": HTMLXvImageViewerElement;
@@ -2492,6 +2630,10 @@ declare namespace LocalJSX {
     interface XvDatepicker {
         "block"?: boolean;
         "disabled"?: boolean;
+        /**
+          * Individual dates to disable within the min/max range. Each entry may be a `Date`, a bare 'yyyy-MM-dd' string, or a full ISO string — all normalised to a local 'yyyy-MM-dd' key that matches the calendar grid. Composes with min/max: a day is selectable only when it is inside the range AND not listed here (e.g. to allow only certain weekdays / block holidays).
+         */
+        "disabledDates"?: (Date | string)[];
         /**
           * Error status. Can be boolean or string
          */
@@ -2615,6 +2757,7 @@ declare namespace LocalJSX {
           * @default []
          */
         "files"?: File[];
+        "helper"?: string;
         "label"?: string;
         /**
           * @default []
@@ -2642,9 +2785,98 @@ declare namespace LocalJSX {
           * @default XvFileUploaderVariants.BUTTON
          */
         "variant"?: XvFileUploaderVariants;
+        "warning"?: string | boolean;
     }
     interface XvFooter {
     }
+    /**
+     * Minimal ATV planner map: MapLibre + PLZ boundaries from the XvGeoTool API.
+     * Click a PLZ to (de)select it. No further UI — selection state and reach
+     * data are emitted via `changeSelection` for the host page to display.
+     * MapLibre (~250 KB gzip) is loaded lazily when the component scrolls near
+     * the viewport, so the host page's initial load stays untouched.
+     */
+    interface XvGeoMapV2 {
+        /**
+          * Base URL of the geo API (Xv.Api v1/geo — contract-compatible with the XvGeoTool API). Default is the same-origin Front Door route, so no CORS is involved on crossvertise pages.
+          * @default '/api-fd/v1/geo'
+         */
+        "apiBase"?: string;
+        /**
+          * @default '© CARTO, © OpenStreetMap contributors'
+         */
+        "attribution"?: string;
+        /**
+          * @default 51.16
+         */
+        "centerLat"?: number;
+        /**
+          * Initial map center
+          * @default 10.45
+         */
+        "centerLng"?: number;
+        /**
+          * Indicator whose per-unit values feed the tooltips and the emitted population sum (e.g. ATV_DEVICES)
+          * @default 'MBI_P_T_2025'
+         */
+        "indicator"?: string;
+        /**
+          * Unit label shown behind the indicator value in the tooltip
+          * @default 'Einwohner'
+         */
+        "indicatorLabel"?: string;
+        /**
+          * Label language for the vector basemap (OpenMapTiles `name:{lang}` attribute, falling back to the place's local name). Empty string keeps the style's own labels.
+          * @default 'de'
+         */
+        "language"?: string;
+        /**
+          * Load the map bundle only when scrolled near the viewport (default: true)
+          * @default true
+         */
+        "lazy"?: boolean;
+        /**
+          * Geo level to display and select: plz5, gemeinde, kreis, regbez, bundesland
+          * @default 'plz5'
+         */
+        "level"?: string;
+        /**
+          * Selection changed: selected PLZs + population sum of the selection
+         */
+        "onChangeSelection"?: (event: XvGeoMapV2CustomEvent<GeoMapSelection>) => void;
+        /**
+          * Map finished initializing
+         */
+        "onMapReady"?: (event: XvGeoMapV2CustomEvent<void>) => void;
+        /**
+          * Shape resolution: medium = simplified geometry (snappy), high = originals
+          * @default 'medium'
+         */
+        "resolution"?: 'medium' | 'high';
+        /**
+          * Minimum zoom before boundaries are loaded and selectable (use ~5 for bundesland, 9 for plz5)
+          * @default 9
+         */
+        "selectZoom"?: number;
+        /**
+          * MapLibre style URL for the vector basemap. Default: OpenFreeMap Positron — the same pale data-overlay look as the previous CARTO light, free for commercial use, no API key (openfreemap.org). Set to an empty string to fall back to the raster `tiles` path.
+          * @default 'https://tiles.openfreemap.org/styles/positron'
+         */
+        "styleUrl"?: string;
+        /**
+          * Raster tile URL template, used only when `style-url` is empty. The former CARTO default now watermarks keyless traffic ("API KEY REQUIRED"), so this path needs a keyed/licensed tile URL.
+          * @default 'https://basemaps.cartocdn.com/rastertiles/light_all/{z}/{x}/{y}@2x.png'
+         */
+        "tiles"?: string;
+        /**
+          * Explicit URL of maplibre-gl-worker.mjs (maplibre-gl-shared.mjs must sit next to it). Needed when the host bundler relocates the maplibre chunk so import.meta.url-relative worker resolution breaks (e.g. Angular/Vite dev server).
+         */
+        "workerUrl"?: string;
+        /**
+          * @default 5.5
+         */
+        "zoom"?: number;
+    }
     interface XvHeader {
         "onXvMetaNavUpdate"?: (event: XvHeaderCustomEvent<any>) => void;
     }
@@ -3339,6 +3571,7 @@ declare namespace LocalJSX {
         "xv-dropdown-v2-item": XvDropdownV2Item;
         "xv-file-uploader": XvFileUploader;
         "xv-footer": XvFooter;
+        "xv-geo-map-v2": XvGeoMapV2;
         "xv-header": XvHeader;
         "xv-header-next": XvHeaderNext;
         "xv-image-viewer": XvImageViewer;
@@ -3440,6 +3673,14 @@ declare module "@stencil/core" {
             "xv-dropdown-v2-item": LocalJSX.XvDropdownV2Item & JSXBase.HTMLAttributes<HTMLXvDropdownV2ItemElement>;
             "xv-file-uploader": LocalJSX.XvFileUploader & JSXBase.HTMLAttributes<HTMLXvFileUploaderElement>;
             "xv-footer": LocalJSX.XvFooter & JSXBase.HTMLAttributes<HTMLXvFooterElement>;
+            /**
+             * Minimal ATV planner map: MapLibre + PLZ boundaries from the XvGeoTool API.
+             * Click a PLZ to (de)select it. No further UI — selection state and reach
+             * data are emitted via `changeSelection` for the host page to display.
+             * MapLibre (~250 KB gzip) is loaded lazily when the component scrolls near
+             * the viewport, so the host page's initial load stays untouched.
+             */
+            "xv-geo-map-v2": LocalJSX.XvGeoMapV2 & JSXBase.HTMLAttributes<HTMLXvGeoMapV2Element>;
             "xv-header": LocalJSX.XvHeader & JSXBase.HTMLAttributes<HTMLXvHeaderElement>;
             /**
              * Drop-in successor of `xv-header` for the new headless CMS.