@powerportalspro/react-maps 0.0.0-stage → 13.0.0

package/dist/index.d.ts

@@ -0,0 +1,689 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties, RefAttributes, ReactElement } from 'react';
+import { GridMapPrint } from '@powerportalspro/react-fluent';
+import { TableRecord, ResolvedColumn, MultiTablePlace, QueryFilter } from '@powerportalspro/core';
+
+interface MapsProviderProps {
+    children?: ReactNode;
+}
+/**
+ * Gives the controls of `@powerportalspro/react-fluent` that show a map this package's maps: the
+ * pin of `<AddressDisplayValue showMap>`, which opens the address on a map in a dialog, a grid's
+ * `GridLayout.Map`, and a grid's Near button (`allowNearSearch`). Put it once
+ * around the app, inside `<PowerPortalsProProvider>` and the theme provider, as the dialog and
+ * overlay providers are.
+ *
+ * ```tsx
+ * <PowerPortalsProProvider>
+ *   <FluentDialogProvider>
+ *     <MapsProvider>
+ *       <RouterProvider router={router} />
+ *     </MapsProvider>
+ *   </FluentDialogProvider>
+ * </PowerPortalsProProvider>
+ * ```
+ */
+declare function MapsProvider({ children }: MapsProviderProps): react_jsx_runtime.JSX.Element;
+
+/** A place on the map, in WGS84 degrees. */
+interface MapPosition {
+    latitude: number;
+    longitude: number;
+}
+/** A rectangle on the map, in WGS84 degrees. `west` is greater than `east` across the antimeridian. */
+interface MapBounds {
+    north: number;
+    south: number;
+    east: number;
+    west: number;
+}
+/** A point in the map's element, in CSS pixels from its top left corner. */
+interface MapPoint {
+    x: number;
+    y: number;
+}
+/** Where the map looks: its center and zoom level (0 shows the whole world; about 15 a street). */
+interface MapCamera {
+    center: MapPosition;
+    zoom: number;
+}
+/** What the map shows now: its camera and the area in view. */
+interface MapView extends MapCamera {
+    bounds: MapBounds;
+}
+/** The kind of base map: streets, aerial imagery, or imagery with streets and labels over it. */
+type MapStyle = 'road' | 'satellite' | 'hybrid';
+interface MapItemBase<TData> {
+    /** Unique among the map's items. What a click on the item reports. */
+    id: string;
+    /** The item's name: its tooltip, what a screen reader announces, and the default popup's heading. */
+    title?: string;
+    /**
+     * Its color, as any CSS color — a Fluent token such as `var(--colorPaletteRedBackground3)`
+     * included. The portal's accent color when unset.
+     */
+    color?: string;
+    /** Anything of the host's, handed back with the item in click events and the popup. */
+    data?: TData;
+    /** Where the default popup's heading links to: the item's own page. */
+    url?: string;
+}
+/** A pin at a position. Pins close together are gathered into a cluster unless clustering is off. */
+interface MapMarker<TData = unknown> extends MapItemBase<TData> {
+    kind: 'marker';
+    position: MapPosition;
+    /**
+     * A few characters drawn on the pin in place of its dot — a number, say, matching the pin to a
+     * list beside the map. Up to four fit comfortably; longer ones are drawn smaller.
+     */
+    label?: string;
+}
+/** A record listed under the map when it is printed. */
+interface MapPrintEntry {
+    /** Its pin's label, beside it in the list. */
+    label?: string;
+    title: string;
+    /** Its columns, each a name and the value shown. */
+    details?: readonly {
+        label: string;
+        value: string;
+    }[];
+    /** The badge's color, as its pin's. The portal's accent color when unset. */
+    color?: string;
+}
+/** A line through positions: a route or a boundary. */
+interface MapPolyline<TData = unknown> extends MapItemBase<TData> {
+    kind: 'polyline';
+    path: readonly MapPosition[];
+    /** Line width in pixels. Default 3. */
+    width?: number;
+}
+/** An area inside positions, closed from the last back to the first. */
+interface MapPolygon<TData = unknown> extends MapItemBase<TData> {
+    kind: 'polygon';
+    path: readonly MapPosition[];
+}
+/** A circle on the ground: a radius around a center, in meters. */
+interface MapCircle<TData = unknown> extends MapItemBase<TData> {
+    kind: 'circle';
+    center: MapPosition;
+    /** In meters. */
+    radius: number;
+}
+/** Something drawn on the map. */
+type MapItem<TData = unknown> = MapMarker<TData> | MapPolyline<TData> | MapPolygon<TData> | MapCircle<TData>;
+/** An item the provider draws itself: everything but a marker, which the map draws on every provider. */
+type MapShape = MapPolyline | MapPolygon | MapCircle;
+/** A click on the map, away from its items. */
+interface MapClickEvent {
+    position: MapPosition;
+}
+/** A click on an item, or Enter on a focused marker. */
+interface MapItemClickEvent {
+    id: string;
+    /** Where it was clicked: a marker's own position, or the point clicked on a shape. */
+    position: MapPosition;
+}
+/** A place an address search found. */
+interface MapPlace {
+    /** The place as the provider writes it: its address, or its name and where it is. */
+    label: string;
+    position: MapPosition;
+    /** The area it covers — a city's, a street's — which the map fits into view. Unset for a point. */
+    bounds?: MapBounds;
+}
+/** A place suggested for the text typed into the address search, found once it is chosen. */
+interface MapAddressSuggestion {
+    /** Unique among the suggestions of one search. */
+    id: string;
+    /** Its main text: a street address, or a place's name. */
+    text: string;
+    /** What tells it from others like it: its city, region and country. */
+    detail?: string;
+}
+
+/** An Entra access token for Azure Maps, issued to the portal's identity, with the account it is for. */
+interface AzureMapsAccessToken {
+    accessToken: string;
+    /** The Azure Maps account's client id. */
+    clientId: string;
+    /** When the token stops working, as an ISO 8601 date and time. */
+    expiresOn: string;
+}
+/**
+ * Azure Maps, drawn with MapLibre from Azure Maps' tiles, signed in with Entra tokens the portal
+ * issues to its own identity, so no Azure Maps key reaches the browser. The portal names the account
+ * in its `PowerPortalsPro:Maps:AzureMaps:ClientId` setting, and its identity needs the Azure Maps
+ * Data Reader role on it.
+ */
+interface AzureMapsSettings {
+    name: 'azureMaps';
+    /**
+     * The country or region whose view of disputed borders to show, such as `US` or `IN`. The
+     * portal's, or Azure Maps' `Auto`, which picks by the viewer's IP address, when unset.
+     */
+    view?: string;
+}
+/**
+ * Esri's basemaps, from the ArcGIS Basemap Styles service, drawn with MapLibre. The key is the
+ * portal's, in its `PowerPortalsPro:Maps:Esri:ApiKey` setting.
+ */
+interface EsriSettings {
+    name: 'esri';
+    /** The road style, such as `arcgis/navigation`. The portal's, or `arcgis/streets`, when unset. */
+    styleName?: string;
+    /** The road style in a dark theme. The portal's, or `arcgis/dark-gray`, when unset. */
+    darkStyleName?: string;
+}
+/**
+ * Google's own map, through the Maps JavaScript API. The key is the portal's, in its
+ * `PowerPortalsPro:Maps:Google:ApiKey` setting.
+ */
+interface GoogleSettings {
+    name: 'google';
+    /**
+     * A map id from the Google Cloud console, for a map styled there. The portal's, or Google's own
+     * styling, when unset.
+     */
+    mapId?: string;
+}
+/**
+ * OpenStreetMap's tiles: no key, for development and light use. OpenStreetMap's tile usage policy
+ * rules out heavy use; a production portal points `tileUrl` at a provider of its own — in its
+ * `PowerPortalsPro:Maps:OpenStreetMap` settings when the URL carries a key — or uses the `mapLibre`
+ * provider with one's style.
+ */
+interface OpenStreetMapSettings {
+    name: 'openStreetMap';
+    /** An XYZ tile URL with `{z}`, `{x}` and `{y}`. Default OpenStreetMap's own. */
+    tileUrl?: string;
+    /** Attribution for `tileUrl`'s tiles, as HTML. */
+    attribution?: string;
+    /**
+     * A Nominatim server for the address search. Default OpenStreetMap's own, whose usage policy
+     * allows light use: a search only once Enter is pressed, never as the viewer types.
+     */
+    geocoderUrl?: string;
+}
+/**
+ * Any map MapLibre can draw: a style URL (MapTiler, OpenFreeMap, Stadia, one of your own) or an
+ * XYZ raster tile URL. Each is the portal's, from its `PowerPortalsPro:Maps:MapLibre` settings, when
+ * the page leaves it unset — the place for a URL that carries a key.
+ */
+interface MapLibreSettings {
+    name: 'mapLibre';
+    /** A MapLibre style JSON URL. */
+    styleUrl?: string;
+    /** The style in a dark theme. `styleUrl` when unset. */
+    darkStyleUrl?: string;
+    /** The style for `satellite`. `styleUrl` when unset. */
+    satelliteStyleUrl?: string;
+    /** The style for `hybrid`. `satelliteStyleUrl` when unset. */
+    hybridStyleUrl?: string;
+    /** An XYZ raster tile URL, used when there is no `styleUrl`. */
+    tileUrl?: string;
+    /** Attribution for `tileUrl`'s tiles, as HTML. */
+    attribution?: string;
+    /** The highest zoom `tileUrl` has tiles for. Default 19. */
+    maxZoom?: number;
+    /** A Nominatim server for the address search. Default OpenStreetMap's own, as `openStreetMap`'s. */
+    geocoderUrl?: string;
+}
+/** A provider registered by the host with `registerMapProvider`, with its own settings. */
+interface CustomMapProviderSettings {
+    name: string;
+    [setting: string]: unknown;
+}
+/**
+ * Which provider draws the map, and how it looks. Its keys are the portal's: the settings a page
+ * leaves unset come from the portal's `PowerPortalsPro:Maps` configuration too.
+ */
+type MapProviderSettings = AzureMapsSettings | EsriSettings | GoogleSettings | OpenStreetMapSettings | MapLibreSettings | CustomMapProviderSettings;
+/** What the portal adds to a provider's settings: its keys, which a page never holds. */
+interface MapProviderKeys {
+    /** Esri's or Google's API key. */
+    apiKey?: string;
+    /** A current Azure Maps token, asked of the portal again shortly before the last one expires. */
+    getToken?: () => Promise<AzureMapsAccessToken>;
+}
+/** What the map tells a provider's surface to report. */
+interface MapSurfaceEvents {
+    /** A click on the map that hit none of the shapes. */
+    click(position: MapPosition, point: MapPoint): void;
+    /** A click on a shape, by its id. */
+    shapeClick(id: string, position: MapPosition, point: MapPoint): void;
+    /** The view is changing — each frame of a pan or zoom. */
+    viewChanging(): void;
+    /** The view has stopped changing. */
+    viewChanged(): void;
+    /**
+     * The surface drew its elements again without the view changing — Google redraws its overlays
+     * whenever it likes. What sits on the map is placed again; the map isn't moving, so nothing waits
+     * for it to stop.
+     */
+    redrawn(): void;
+    /** Something failed that the surface can't recover from, such as a key that was refused. */
+    error(message: string): void;
+}
+/** What an address search asks a geocoder. */
+interface MapAddressQuery {
+    text: string;
+    /** Where the map is looking: places in and near it come first. */
+    view: MapView;
+    /** ISO 3166-1 two-letter country codes the places are limited to; anywhere when empty. */
+    countries: readonly string[];
+    /** The viewer's language, as a culture name such as `en-US`. */
+    language: string;
+    signal?: AbortSignal;
+}
+/** Finds places by their address or name, with a provider's own search. */
+interface MapGeocoder {
+    /**
+     * Whether it suggests places as the viewer types. One that doesn't is asked only when they press
+     * Enter, as OpenStreetMap's Nominatim asks of the users of its free service.
+     */
+    readonly suggestsAsYouType: boolean;
+    /** Places for the text, best first. */
+    suggest(query: MapAddressQuery): Promise<MapAddressSuggestion[]>;
+    /** Where one of its own suggestions is; null when the provider can no longer find it. */
+    resolve(suggestion: MapAddressSuggestion, signal?: AbortSignal): Promise<MapPlace | null>;
+}
+/** An element the surface keeps at a position on the map as it moves. */
+interface MapOverlay {
+    setPosition(position: MapPosition): void;
+    remove(): void;
+}
+/** What a provider is given to draw a map. */
+interface MapSurfaceContext<TSettings extends MapProviderSettings = MapProviderSettings> {
+    /** The element to draw into. Empty, positioned, and sized by the map. */
+    container: HTMLElement;
+    /** The page's settings over the portal's, with the portal's keys. */
+    settings: TSettings & MapProviderKeys;
+    style: MapStyle;
+    /** Whether the portal's theme is dark, for a provider with a dark map. */
+    dark: boolean;
+    /** The viewer's language, as a culture name such as `en-US`. */
+    language: string;
+    camera: MapCamera;
+    /** Passed to the provider's own map as they are, over the map's: the way to its other features. */
+    nativeOptions?: Record<string, unknown>;
+    /**
+     * What a provider that needs a modifier key to zoom with the wheel — so a page scrolls past its
+     * map — shows when someone scrolls without it. Google shows its own.
+     */
+    gestureHelp?: MapGestureHelp;
+    events: MapSurfaceEvents;
+}
+/** The map's hints for zooming and panning a map that doesn't take the page's scrolling, in the viewer's language. */
+interface MapGestureHelp {
+    /** Scrolling with the wheel alone, on Windows and Linux: "Use Ctrl + scroll to zoom the map". */
+    windows: string;
+    /** The same on a Mac, with ⌘. */
+    mac: string;
+    /** A one-finger drag on a touch screen: "Use two fingers to move the map". */
+    mobile: string;
+}
+/**
+ * A provider's map: what the shared map control needs of it. Markers, clusters and the popup are
+ * the control's, drawn the same way on every provider; a surface only places elements, draws
+ * shapes, and reports clicks and moves.
+ */
+interface MapSurface {
+    /** The provider's own map object — a MapLibre `Map`, a `google.maps.Map` — for what the control doesn't cover. */
+    readonly native: unknown;
+    /** The provider's address search, for the map's search box; without one the box isn't shown. */
+    readonly geocoder?: MapGeocoder | null;
+    getView(): MapView;
+    setCamera(camera: MapCamera, animate: boolean): void;
+    fitBounds(bounds: MapBounds, padding: number, maxZoom: number): void;
+    panBy(x: number, y: number): void;
+    /** Where a position is in the container, in CSS pixels. */
+    project(position: MapPosition): MapPoint;
+    /** Keeps `element` at `position`, its bottom center there for `bottom`, its center for `center`. */
+    addOverlay(element: HTMLElement, position: MapPosition, anchor: 'bottom' | 'center'): MapOverlay;
+    /** Replaces the shapes drawn. Their colors are resolved, never a CSS variable. */
+    setShapes(shapes: readonly MapShape[]): void;
+    /**
+     * Changes the base map. Returns false when this provider can't without drawing the map again,
+     * which the control then does.
+     */
+    setStyle(style: MapStyle, dark: boolean): boolean;
+    /**
+     * Changes the hints for zooming and panning, which arrive after the map is drawn when its strings
+     * load late. A provider that shows none of its own leaves it out.
+     */
+    setGestureHelp?(help: MapGestureHelp): void;
+    resize(): void;
+    /**
+     * A copy of the map as it is drawn, once every tile in view has loaded, at `pixelRatio` device
+     * pixels to a CSS pixel: what the map's image and printout are made from. A provider whose map
+     * can't be copied — Google's — leaves it out, and the map is printed as it is on the page.
+     */
+    capture?(pixelRatio: number): Promise<HTMLCanvasElement>;
+    /** The provider's attribution, as text: written on the map's image. */
+    attributionText?(): string;
+    dispose(): void;
+}
+/**
+ * A map provider. Built-in ones are found by name; a host adds its own with `registerMapProvider`
+ * and names it in the map's provider settings.
+ */
+interface MapProvider<TSettings extends MapProviderSettings = MapProviderSettings> {
+    readonly name: string;
+    create(context: MapSurfaceContext<TSettings>): Promise<MapSurface>;
+}
+
+/**
+ * Adds a map provider, or replaces one of the same name — a built-in one included. A map whose
+ * provider settings name it draws with it.
+ */
+declare function registerMapProvider<TSettings extends MapProviderSettings>(provider: MapProvider<TSettings>): void;
+/** The names of the built-in providers. */
+declare const BUILT_IN_MAP_PROVIDERS: readonly string[];
+
+/** A unit distances are measured in, as the server numbers them: miles, or kilometers. */
+declare const DistanceUnits: {
+    readonly Miles: 0;
+    readonly Kilometers: 1;
+};
+type DistanceUnit = (typeof DistanceUnits)[keyof typeof DistanceUnits];
+/** The distances a search near a place offers, unless its page gives others. */
+declare const DEFAULT_NEAR_DISTANCES: readonly number[];
+/** The distance a search near a place starts at, unless its page gives another. */
+declare const DEFAULT_NEAR_DISTANCE = 25;
+/** Where a search near a place is, and how far from it records may be. */
+interface NearPlace {
+    /** The place as it was found: an address, or the visitor's location. */
+    label: string;
+    latitude: number;
+    longitude: number;
+    distance: number;
+    unit: DistanceUnit;
+}
+
+/**
+ * Where MapLibre's worker script is served from. MapLibre 6 loads it as a file of its own, and a
+ * bundled app has to say where its bundler put it — once, before a map is drawn:
+ *
+ * ```ts
+ * // Vite
+ * import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
+ * setMapLibreWorkerUrl(workerUrl);
+ *
+ * // webpack 5, rspack, Next.js
+ * setMapLibreWorkerUrl(new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url).toString());
+ * ```
+ *
+ * Calling MapLibre's own `setWorkerUrl` does the same. A function in place of the URL is called
+ * when a MapLibre map is first drawn, so code that finds it — loading the worker's script, say —
+ * runs only on a page that shows one.
+ */
+declare function setMapLibreWorkerUrl(url: string | (() => string | Promise<string>)): void;
+
+/** Dataverse's own latitude and longitude columns on accounts, contacts and other address tables. */
+declare const DEFAULT_LATITUDE_COLUMN = "address1_latitude";
+declare const DEFAULT_LONGITUDE_COLUMN = "address1_longitude";
+/** The most rows a map reads unless told otherwise. */
+declare const DEFAULT_MAX_ROWS = 1000;
+/** What the map draws for a Dataverse row: a marker, with the row and its view's columns. */
+interface MapRecord {
+    record: TableRecord;
+    /** The view's columns, for a popup showing the row. */
+    columns: readonly ResolvedColumn[];
+    /** For a row of a table registered for maps: where it is, and what its popup shows. */
+    place?: MultiTablePlace;
+}
+/** A marker drawn for a row, carrying it as its data. */
+type MapRecordMarker = MapMarker<MapRecord>;
+
+/** An item clicked on the map, with where it was clicked. */
+interface MapItemClick<TData> {
+    item: MapItem<TData>;
+    position: MapPosition;
+    /** Keeps the map from opening the item's popup: for a page that does something else with the click. */
+    preventDefault(): void;
+    /** Whether `preventDefault` was called. */
+    readonly defaultPrevented: boolean;
+}
+/** A map as a Print button of the page's own works it (`onPrintChange`): a grid's map's, the same. */
+type MapPrint = GridMapPrint;
+/** What a map can be told to do through its ref. */
+interface MapHandle {
+    /** Moves the view, animated unless `animate` is false. */
+    setCamera(camera: MapCamera, animate?: boolean): void;
+    /** Moves the view to show every item — or, given `ids`, the items of those ids. */
+    fitToItems(ids?: readonly string[]): void;
+    /** Opens the popup of the item of that id. */
+    openPopup(id: string): void;
+    closePopup(): void;
+    /**
+     * Finds `text` with the provider's address search and goes there: the first place found, pinned.
+     * Null when nothing is found, or the provider has no search.
+     */
+    goToAddress(text: string): Promise<MapPlace | null>;
+    /** Empties the address search and takes the place it found off the map. */
+    clearAddress(): void;
+    /** What the map shows now; null before it has drawn. */
+    getView(): MapView | null;
+    /**
+     * Prints the map, with `printTitle` above it, its legend, and `printEntries` listed under it — as
+     * the print button does.
+     */
+    print(): Promise<void>;
+    /**
+     * Saves the map as a PNG image of that name, with its legend. False when the provider's map can't
+     * be copied (Google's), or before the map has drawn.
+     */
+    saveImage(fileName?: string): Promise<boolean>;
+    /** The provider's own map object — a MapLibre `Map`, a `google.maps.Map` — or null before it has drawn. */
+    readonly native: unknown;
+}
+interface MapProps<TData = unknown> {
+    /**
+     * Which provider draws the map, and how it looks — the portal's own provider, from its
+     * `PowerPortalsPro:Maps:Provider` setting, when unset. Keys are only ever the portal's: it fills in
+     * each provider's from its `PowerPortalsPro:Maps` settings, with any the page leaves unset.
+     */
+    provider?: MapProviderSettings;
+    /** Markers, lines, areas and circles of the page's own, drawn with any rows read. */
+    items?: readonly MapItem<TData>[];
+    /** A view whose rows to plot, each at its latitude and longitude. */
+    viewId?: string;
+    /** A FetchXML query whose rows to plot, instead of a view. */
+    fetchXml?: string;
+    /** Narrows the rows read — to those related to the page's record, say. */
+    filters?: readonly QueryFilter[];
+    /** The rows' latitude column. Default `address1_latitude`. */
+    latitudeColumn?: string;
+    /** The rows' longitude column. Default `address1_longitude`. */
+    longitudeColumn?: string;
+    /** The column that names each row's marker. The table's primary name column by default. */
+    titleColumn?: string;
+    /**
+     * The rows' markers' color, as any CSS color: one for every row, or each row's own. The portal's
+     * accent color by default.
+     */
+    recordColor?: string | ((record: TableRecord) => string | undefined);
+    /**
+     * A choice, status, status reason or yes/no column whose options color the rows' markers — each
+     * the color Dataverse gives it, or one of Fluent's palette — with a legend of the options shown.
+     */
+    colorColumn?: string;
+    /** Shows the legend of `colorColumn`'s options. Default `true`. */
+    showLegend?: boolean;
+    /**
+     * Each row's page, which its popup's heading links to, in place of its record's page registered
+     * with `AddRecordPage`: a URL with `{0}` in place of the row's id and `{1}` its table's, or the URL
+     * a function makes of the row.
+     */
+    recordUrl?: string | ((record: TableRecord) => string | undefined);
+    /**
+     * Whether a row's popup heading links to its record's page, registered with `AddRecordPage`, when
+     * no `recordUrl` is given. Default `true`; a table with no page shows no link.
+     */
+    showRecordLinks?: boolean;
+    /** Follows a popup's link in place of the browser — `(url) => navigate(url)` for react-router. */
+    onNavigate?: (url: string) => void;
+    /** A box over the map's corner for finding an address with the provider's own search. Default `false`. */
+    showAddressSearch?: boolean;
+    /** ISO 3166-1 two-letter codes of the countries the address search finds places in. Anywhere when unset. */
+    addressSearchCountries?: readonly string[];
+    /**
+     * An address to show, such as `"1 Microsoft Way, Redmond, WA 98052"`: found with the provider's
+     * own search once the map is drawn, and again whenever it changes, then pinned and brought into
+     * view. A spinner shows while it is looked for, and a message when it isn't found.
+     */
+    address?: string;
+    /**
+     * Keeps the view on chosen items: fitted to the items of these ids — or to every item when it is
+     * empty — each time it changes, and when items it was fitted to are gone (a new page of them).
+     * Items only added, or restyled, leave the view where the user moved it. Unset, the view is fitted
+     * to the items only as they first arrive.
+     */
+    fitItemIds?: readonly string[];
+    /**
+     * Puts the rows of the tables registered for maps (`ForMaps`) on the map, beside its own rows and
+     * items: every one, or a view of some, each table's pins in its registration's color, with a toolbar
+     * above the map to choose the view and the tables shown. Default `false`.
+     */
+    multiTable?: boolean;
+    /** Only these of the tables registered for maps, by logical name. Every one the user may read when unset. */
+    tables?: readonly string[];
+    /** The tables shown at first in the view of every table; the others start switched off. Every one when unset. */
+    defaultTables?: readonly string[];
+    /** The view shown at first: one registered for maps, or one of the user's. */
+    defaultViewId?: string;
+    /**
+     * Only these views, in this order: views registered for maps (`AddMultiTableView` with `ForMaps`),
+     * by id. The view of every table is offered only when this is unset; a signed-in user's own views
+     * follow either way. Unset, the view of every table, then every view registered for maps.
+     */
+    viewIds?: readonly string[];
+    /** Only the rows about this record, through each table's regarding column. */
+    regarding?: {
+        tableName: string;
+        id: string;
+    };
+    /** Offers the view's filters to change in the Filter menu, a tab for each table shown. Default `false`. */
+    allowFiltering?: boolean;
+    /**
+     * Lets signed-in users save the tables shown, with their filters, as views of their own, and choose
+     * their default view and hide the views they don't use. Default `false`.
+     */
+    allowSavedViews?: boolean;
+    /** Names this map among the maps, so the views saved on it are its own. Shared with every map without one when unset. */
+    savedViewsKey?: string;
+    /** Where a visitor who isn't signed in is sent to sign in, from the saved views' menu. Default `Account/Login`. */
+    signInUrl?: string;
+    /** The toolbar's heading when there is only one view to show. None when unset. */
+    title?: string;
+    /**
+     * A Near button on the toolbar of a map of several tables: only the rows within a distance of a
+     * place — an address found with the provider's search, or the visitor's location — nearest first,
+     * the circle drawn and the map fitted to it, each popup saying how far its row is. Default `false`.
+     */
+    allowNearSearch?: boolean;
+    /** The distances the Near button offers. Default 1, 5, 10, 25, 50 and 100. */
+    nearDistances?: readonly number[];
+    /** The distance the Near button starts at. Default 25. */
+    nearDistance?: number;
+    /** The unit the Near button starts in: `DistanceUnits.Miles` (default) or `DistanceUnits.Kilometers`. */
+    nearDistanceUnit?: DistanceUnit;
+    /** The most rows read. Default 1000, at most 5000; a note on the map says when there are more. */
+    maxRows?: number;
+    /** Streets, aerial imagery, or both. Default `road`. */
+    mapStyle?: MapStyle;
+    /** Where the map looks first. Fitted to its items when unset. */
+    center?: MapPosition;
+    /** The zoom it starts at, with `center`: 0 is the whole world, about 15 a street. Default 12. */
+    zoom?: number;
+    /** Gather markers close together into clusters, which zoom in when clicked. Default `true`. */
+    cluster?: boolean;
+    /**
+     * A Print button — on the toolbar with `multiTable`, else over the map's top right corner — for
+     * printing the map and, where the provider's map can be copied, saving it as an image. A map is
+     * printed as an image with its pins, legend and the provider's attribution, or, for Google, as it
+     * is on the page. Default `false`.
+     */
+    showPrintButton?: boolean;
+    /** The heading printed above the map. `title` when unset. */
+    printTitle?: string;
+    /**
+     * Records listed under the map when it is printed, each beside its pin's label — or a function
+     * that makes them as it is printed, for a long list, which then costs nothing until someone prints.
+     */
+    printEntries?: readonly MapPrintEntry[] | (() => readonly MapPrintEntry[]);
+    /**
+     * Called as the map can be printed, or no longer — before it has drawn, once it has failed, as it
+     * goes — for a Print button of the page's own, in a toolbar around the map, say.
+     */
+    onPrintChange?: (print: MapPrint | null) => void;
+    /** Draw the dark map, where the provider has one, when the portal's theme is dark. Default `true`. */
+    usePortalTheme?: boolean;
+    /**
+     * Open a popup on the item clicked: `renderPopup`'s content, a row's view columns, or an item's
+     * title. Default `true`. `onItemClick` is called either way.
+     */
+    showPopups?: boolean;
+    /** The popup's content for an item, in place of the default. Return null for no popup. */
+    renderPopup?: (item: MapItem<TData | MapRecord>) => ReactNode;
+    /** Options for the provider's own map, over the map's: the way to its other features. */
+    nativeOptions?: Record<string, unknown>;
+    /** CSS height of the map. Default `400px`. */
+    height?: string | number;
+    /** CSS width of the map. Default `100%`. */
+    width?: string | number;
+    className?: string;
+    style?: CSSProperties;
+    /** A click on the map, away from its items. */
+    onMapClick?: (event: MapClickEvent) => void;
+    /**
+     * A click on an item — a row's marker, a line, an area or a circle. The map opens the item's popup
+     * after it, unless `event.preventDefault()` was called.
+     */
+    onItemClick?: (event: MapItemClick<TData | MapRecord>) => void;
+    /** The address search went to a place, or, with null, was cleared. */
+    onAddressSelected?: (place: MapPlace | null) => void;
+    /** The view has settled after a move. */
+    onViewChanged?: (view: MapView) => void;
+    /** The map couldn't be drawn, or its rows read. */
+    onError?: (message: string) => void;
+}
+/**
+ * A map of Dataverse rows and items of the page's own, drawn by Azure Maps, Esri, Google,
+ * OpenStreetMap or any MapLibre style — the portal's own provider unless `provider` names another,
+ * each with the keys in the portal's `PowerPortalsPro:Maps` settings. Rows come from a view or
+ * FetchXML, each at its latitude and longitude, read with the user's permissions as a grid's are,
+ * and colored by a column's options with `colorColumn`. Clicking an item calls `onItemClick`, then
+ * opens a popup — its row's columns by default, or what `renderPopup` returns — unless the page
+ * prevented it. `showAddressSearch` adds a box for finding an address with the provider's search.
+ */
+declare const Map: <TData = unknown>(props: MapProps<TData> & RefAttributes<MapHandle>) => ReactElement | null;
+
+/** What a search near a place shows and changes. */
+interface NearSearchProps {
+    /** The place searched near, and how far from it; null when the search isn't near anywhere. */
+    value: NearPlace | null;
+    /** A place was chosen, the distance or unit changed, or the search was cleared (null). */
+    onChange: (value: NearPlace | null) => void;
+    /** The distances offered. Default 1, 5, 10, 25, 50 and 100. */
+    distances?: readonly number[] | undefined;
+    /** The distance offered first, before one is chosen. Default 25, or the first offered when 25 isn't. */
+    defaultDistance?: number | undefined;
+    /** The unit offered first, before one is chosen. Default miles. */
+    defaultUnit?: DistanceUnit | undefined;
+    /** Whose address search finds the place: the portal's own map provider unless set. */
+    provider?: MapProviderSettings | undefined;
+    /** ISO 3166-1 two-letter country codes the places found are limited to; anywhere when unset. */
+    countries?: readonly string[] | undefined;
+    className?: string | undefined;
+}
+/**
+ * Finds the records near a place: a toolbar button that opens the place's search — an address, with
+ * the map provider's own search, or the visitor's location — and how far from it, in miles or
+ * kilometers. Shown by a multi-table `<Map allowNearSearch>` and a grid's `allowNearSearch` (through
+ * `<MapsProvider>`). The twin of Blazor's `NearSearch`.
+ */
+declare function NearSearch({ value, onChange, distances, defaultDistance, defaultUnit, provider, countries, className }: NearSearchProps): react_jsx_runtime.JSX.Element;
+
+export { type AzureMapsAccessToken, type AzureMapsSettings, BUILT_IN_MAP_PROVIDERS, type CustomMapProviderSettings, DEFAULT_LATITUDE_COLUMN, DEFAULT_LONGITUDE_COLUMN, DEFAULT_MAX_ROWS, DEFAULT_NEAR_DISTANCE, DEFAULT_NEAR_DISTANCES, type DistanceUnit, DistanceUnits, type EsriSettings, type GoogleSettings, Map, type MapAddressQuery, type MapAddressSuggestion, type MapBounds, type MapCamera, type MapCircle, type MapClickEvent, type MapGeocoder, type MapGestureHelp, type MapHandle, type MapItem, type MapItemClick, type MapItemClickEvent, type MapLibreSettings, type MapMarker, type MapOverlay, type MapPlace, type MapPoint, type MapPolygon, type MapPolyline, type MapPosition, type MapPrint, type MapProps, type MapProvider, type MapProviderKeys, type MapProviderSettings, type MapRecord, type MapRecordMarker, type MapShape, type MapStyle, type MapSurface, type MapSurfaceContext, type MapSurfaceEvents, type MapView, MapsProvider, type MapsProviderProps, type NearPlace, NearSearch, type NearSearchProps, type OpenStreetMapSettings, registerMapProvider, setMapLibreWorkerUrl };