@mapcairn/map 0.0.0-stage → 0.1.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +661 -0
- package/README.md +167 -2
- package/dist/chrome/Attribution/Attribution.js +304 -0
- package/dist/chrome/Attribution/Attribution.js.map +1 -0
- package/dist/chrome/Attribution/Attribution.styles.js +10 -0
- package/dist/chrome/Attribution/Attribution.styles.js.map +1 -0
- package/dist/chrome/Attribution/AttributionSkeleton.js +29 -0
- package/dist/chrome/Attribution/AttributionSkeleton.js.map +1 -0
- package/dist/chrome/ChromeSkeleton/ChromeSkeleton.js +83 -0
- package/dist/chrome/ChromeSkeleton/ChromeSkeleton.js.map +1 -0
- package/dist/chrome/EndStack/EndStack.js +157 -0
- package/dist/chrome/EndStack/EndStack.js.map +1 -0
- package/dist/chrome/EndStack/EndStack.styles.js +12 -0
- package/dist/chrome/EndStack/EndStack.styles.js.map +1 -0
- package/dist/chrome/EndStack/EndStackSkeleton.js +78 -0
- package/dist/chrome/EndStack/EndStackSkeleton.js.map +1 -0
- package/dist/chrome/EndStack/endStackHeight.js +22 -0
- package/dist/chrome/EndStack/endStackHeight.js.map +1 -0
- package/dist/chrome/MapChrome/MapChrome.js +488 -0
- package/dist/chrome/MapChrome/MapChrome.js.map +1 -0
- package/dist/chrome/MapChrome/MapChrome.styles.js +15 -0
- package/dist/chrome/MapChrome/MapChrome.styles.js.map +1 -0
- package/dist/chrome/MapChrome/chromeSurface.js +18 -0
- package/dist/chrome/MapChrome/chromeSurface.js.map +1 -0
- package/dist/chrome/MapChrome/chromeVars.js +71 -0
- package/dist/chrome/MapChrome/chromeVars.js.map +1 -0
- package/dist/chrome/MapChrome/mapKeyPlacement.js +41 -0
- package/dist/chrome/MapChrome/mapKeyPlacement.js.map +1 -0
- package/dist/chrome/MapChrome/sharesWidth.js +13 -0
- package/dist/chrome/MapChrome/sharesWidth.js.map +1 -0
- package/dist/chrome/MapReadout/MapReadout.js +199 -0
- package/dist/chrome/MapReadout/MapReadout.js.map +1 -0
- package/dist/chrome/MapReadout/MapReadout.styles.js +14 -0
- package/dist/chrome/MapReadout/MapReadout.styles.js.map +1 -0
- package/dist/chrome/Sheet/Sheet.js +412 -0
- package/dist/chrome/Sheet/Sheet.js.map +1 -0
- package/dist/chrome/Sheet/Sheet.styles.js +14 -0
- package/dist/chrome/Sheet/Sheet.styles.js.map +1 -0
- package/dist/chrome/focusRegistry.js +76 -0
- package/dist/chrome/focusRegistry.js.map +1 -0
- package/dist/chrome/layoutContext.js +30 -0
- package/dist/chrome/layoutContext.js.map +1 -0
- package/dist/chrome/useScrollEdges.js +53 -0
- package/dist/chrome/useScrollEdges.js.map +1 -0
- package/dist/host/MapContext.js +16 -0
- package/dist/host/MapContext.js.map +1 -0
- package/dist/host/MapView.js +189 -0
- package/dist/host/MapView.js.map +1 -0
- package/dist/host/MapView.styles.js +16 -0
- package/dist/host/MapView.styles.js.map +1 -0
- package/dist/host/overlays/AccuracyCircle.js +36 -0
- package/dist/host/overlays/AccuracyCircle.js.map +1 -0
- package/dist/host/overlays/CentreCrosshair.js +40 -0
- package/dist/host/overlays/CentreCrosshair.js.map +1 -0
- package/dist/host/overlays/DrawOverlay.js +221 -0
- package/dist/host/overlays/DrawOverlay.js.map +1 -0
- package/dist/host/overlays/MapOverlayLayer.js +27 -0
- package/dist/host/overlays/MapOverlayLayer.js.map +1 -0
- package/dist/host/overlays/MeasureOverlay.js +87 -0
- package/dist/host/overlays/MeasureOverlay.js.map +1 -0
- package/dist/host/overlays/PinMarker.js +40 -0
- package/dist/host/overlays/PinMarker.js.map +1 -0
- package/dist/host/overlays/geometry.js +41 -0
- package/dist/host/overlays/geometry.js.map +1 -0
- package/dist/host/overlays/overlays.styles.js +27 -0
- package/dist/host/overlays/overlays.styles.js.map +1 -0
- package/dist/host/pointerTargets.js +22 -0
- package/dist/host/pointerTargets.js.map +1 -0
- package/dist/host/useLongPress.js +102 -0
- package/dist/host/useLongPress.js.map +1 -0
- package/dist/host/useMapEngine.js +352 -0
- package/dist/host/useMapEngine.js.map +1 -0
- package/dist/host/usePointerPosition.js +60 -0
- package/dist/host/usePointerPosition.js.map +1 -0
- package/dist/index.d.ts +3845 -0
- package/dist/index.js +89 -0
- package/dist/layers/CatalogueStatus.js +138 -0
- package/dist/layers/CatalogueStatus.js.map +1 -0
- package/dist/layers/DateTimeControl.js +101 -0
- package/dist/layers/DateTimeControl.js.map +1 -0
- package/dist/layers/FeatureCard.js +147 -0
- package/dist/layers/FeatureCard.js.map +1 -0
- package/dist/layers/FeatureChoices.js +101 -0
- package/dist/layers/FeatureChoices.js.map +1 -0
- package/dist/layers/FeatureGlyph.js +56 -0
- package/dist/layers/FeatureGlyph.js.map +1 -0
- package/dist/layers/IdentifyStatus.js +36 -0
- package/dist/layers/IdentifyStatus.js.map +1 -0
- package/dist/layers/LayerItem.js +321 -0
- package/dist/layers/LayerItem.js.map +1 -0
- package/dist/layers/LayerKey.js +36 -0
- package/dist/layers/LayerKey.js.map +1 -0
- package/dist/layers/Layers.styles.js +50 -0
- package/dist/layers/Layers.styles.js.map +1 -0
- package/dist/layers/LayersSection.js +267 -0
- package/dist/layers/LayersSection.js.map +1 -0
- package/dist/layers/MapDataLayers.js +261 -0
- package/dist/layers/MapDataLayers.js.map +1 -0
- package/dist/layers/MapKey.js +131 -0
- package/dist/layers/MapKey.js.map +1 -0
- package/dist/layers/MapKey.styles.js +16 -0
- package/dist/layers/MapKey.styles.js.map +1 -0
- package/dist/layers/MarkerGlyph.js +84 -0
- package/dist/layers/MarkerGlyph.js.map +1 -0
- package/dist/layers/SelectionProvider.js +27 -0
- package/dist/layers/SelectionProvider.js.map +1 -0
- package/dist/layers/ShapeGlyph.js +122 -0
- package/dist/layers/ShapeGlyph.js.map +1 -0
- package/dist/layers/TurnOffActions.js +147 -0
- package/dist/layers/TurnOffActions.js.map +1 -0
- package/dist/layers/answersTap.js +16 -0
- package/dist/layers/answersTap.js.map +1 -0
- package/dist/layers/catalogueNotice.js +65 -0
- package/dist/layers/catalogueNotice.js.map +1 -0
- package/dist/layers/catalogueReconcile.js +55 -0
- package/dist/layers/catalogueReconcile.js.map +1 -0
- package/dist/layers/catalogueView.js +32 -0
- package/dist/layers/catalogueView.js.map +1 -0
- package/dist/layers/featureTitle.js +14 -0
- package/dist/layers/featureTitle.js.map +1 -0
- package/dist/layers/identifyFeedback.js +30 -0
- package/dist/layers/identifyFeedback.js.map +1 -0
- package/dist/layers/identifyRun.js +148 -0
- package/dist/layers/identifyRun.js.map +1 -0
- package/dist/layers/layerStatus.js +13 -0
- package/dist/layers/layerStatus.js.map +1 -0
- package/dist/layers/loadOutcome.js +107 -0
- package/dist/layers/loadOutcome.js.map +1 -0
- package/dist/layers/loadReport.js +33 -0
- package/dist/layers/loadReport.js.map +1 -0
- package/dist/layers/loadRequests.js +73 -0
- package/dist/layers/loadRequests.js.map +1 -0
- package/dist/layers/mapFeatures.js +307 -0
- package/dist/layers/mapFeatures.js.map +1 -0
- package/dist/layers/mapKeyBlocks.js +24 -0
- package/dist/layers/mapKeyBlocks.js.map +1 -0
- package/dist/layers/reveal.js +119 -0
- package/dist/layers/reveal.js.map +1 -0
- package/dist/layers/selectionMessages.js +53 -0
- package/dist/layers/selectionMessages.js.map +1 -0
- package/dist/layers/selectionResolve.js +111 -0
- package/dist/layers/selectionResolve.js.map +1 -0
- package/dist/layers/useDataLayers.js +940 -0
- package/dist/layers/useDataLayers.js.map +1 -0
- package/dist/layers/useFeatureSelection.js +179 -0
- package/dist/layers/useFeatureSelection.js.map +1 -0
- package/dist/layers/useScrolls.js +37 -0
- package/dist/layers/useScrolls.js.map +1 -0
- package/dist/panels/BasemapPicker/BasemapPicker.js +169 -0
- package/dist/panels/BasemapPicker/BasemapPicker.js.map +1 -0
- package/dist/panels/BasemapPicker/BasemapPicker.styles.js +42 -0
- package/dist/panels/BasemapPicker/BasemapPicker.styles.js.map +1 -0
- package/dist/panels/ExportSection/ExportSection.js +91 -0
- package/dist/panels/ExportSection/ExportSection.js.map +1 -0
- package/dist/panels/HelpSection/HelpSection.js +163 -0
- package/dist/panels/HelpSection/HelpSection.js.map +1 -0
- package/dist/panels/HelpSection/HelpSection.styles.js +9 -0
- package/dist/panels/HelpSection/HelpSection.styles.js.map +1 -0
- package/dist/panels/PinSection/PinSection.js +39 -0
- package/dist/panels/PinSection/PinSection.js.map +1 -0
- package/dist/panels/Section/Section.js +43 -0
- package/dist/panels/Section/Section.js.map +1 -0
- package/dist/panels/Section/Section.styles.js +13 -0
- package/dist/panels/Section/Section.styles.js.map +1 -0
- package/dist/panels/SettingsSection/LanguageField.js +126 -0
- package/dist/panels/SettingsSection/LanguageField.js.map +1 -0
- package/dist/panels/SettingsSection/SettingsSection.js +175 -0
- package/dist/panels/SettingsSection/SettingsSection.js.map +1 -0
- package/dist/panels/SettingsSection/SettingsSection.styles.js +9 -0
- package/dist/panels/SettingsSection/SettingsSection.styles.js.map +1 -0
- package/dist/panels/ShapesSection/ShapesSection.js +229 -0
- package/dist/panels/ShapesSection/ShapesSection.js.map +1 -0
- package/dist/panels/ShapesSection/ShapesSection.styles.js +7 -0
- package/dist/panels/ShapesSection/ShapesSection.styles.js.map +1 -0
- package/dist/panels/SheetContent/SheetContent.js +92 -0
- package/dist/panels/SheetContent/SheetContent.js.map +1 -0
- package/dist/panels/SheetContent/SheetContent.styles.js +6 -0
- package/dist/panels/SheetContent/SheetContent.styles.js.map +1 -0
- package/dist/services/ServicesProvider.js +42 -0
- package/dist/services/ServicesProvider.js.map +1 -0
- package/dist/services/activeMessages.js +140 -0
- package/dist/services/activeMessages.js.map +1 -0
- package/dist/services/basemapAvailability.js +78 -0
- package/dist/services/basemapAvailability.js.map +1 -0
- package/dist/services/englishMessages.js +10 -0
- package/dist/services/englishMessages.js.map +1 -0
- package/dist/services/hooks.js +214 -0
- package/dist/services/hooks.js.map +1 -0
- package/dist/styles.css +2866 -0
- package/dist/styles.css.d.ts +1 -0
- package/dist/tools/Directions/Directions.styles.js +25 -0
- package/dist/tools/Directions/Directions.styles.js.map +1 -0
- package/dist/tools/Directions/DirectionsOverlay.js +46 -0
- package/dist/tools/Directions/DirectionsOverlay.js.map +1 -0
- package/dist/tools/Directions/DirectionsPanel.js +428 -0
- package/dist/tools/Directions/DirectionsPanel.js.map +1 -0
- package/dist/tools/Directions/MapDirections.js +84 -0
- package/dist/tools/Directions/MapDirections.js.map +1 -0
- package/dist/tools/Directions/useDirections.js +226 -0
- package/dist/tools/Directions/useDirections.js.map +1 -0
- package/dist/tools/Directions/useFreeCentre.js +30 -0
- package/dist/tools/Directions/useFreeCentre.js.map +1 -0
- package/dist/tools/DrawToolbar/DrawMapBindings.js +34 -0
- package/dist/tools/DrawToolbar/DrawMapBindings.js.map +1 -0
- package/dist/tools/DrawToolbar/DrawToolbar.js +296 -0
- package/dist/tools/DrawToolbar/DrawToolbar.js.map +1 -0
- package/dist/tools/DrawToolbar/DrawToolbar.styles.js +21 -0
- package/dist/tools/DrawToolbar/DrawToolbar.styles.js.map +1 -0
- package/dist/tools/DrawToolbar/imageDrawing.js +24 -0
- package/dist/tools/DrawToolbar/imageDrawing.js.map +1 -0
- package/dist/tools/DrawToolbar/useDraw.js +543 -0
- package/dist/tools/DrawToolbar/useDraw.js.map +1 -0
- package/dist/tools/MeasureToolbar/MeasureToolbar.js +116 -0
- package/dist/tools/MeasureToolbar/MeasureToolbar.js.map +1 -0
- package/dist/tools/MeasureToolbar/MeasureToolbar.styles.js +12 -0
- package/dist/tools/MeasureToolbar/MeasureToolbar.styles.js.map +1 -0
- package/dist/tools/MeasureToolbar/useMeasure.js +75 -0
- package/dist/tools/MeasureToolbar/useMeasure.js.map +1 -0
- package/dist/tools/PinCard/PinCard.js +174 -0
- package/dist/tools/PinCard/PinCard.js.map +1 -0
- package/dist/tools/PinCard/PinCard.styles.js +16 -0
- package/dist/tools/PinCard/PinCard.styles.js.map +1 -0
- package/dist/tools/PinCard/useReverseAddress.js +77 -0
- package/dist/tools/PinCard/useReverseAddress.js.map +1 -0
- package/dist/tools/SearchPill/SearchPill.js +292 -0
- package/dist/tools/SearchPill/SearchPill.js.map +1 -0
- package/dist/tools/SearchPill/SearchPill.styles.js +16 -0
- package/dist/tools/SearchPill/SearchPill.styles.js.map +1 -0
- package/dist/tools/SearchPill/SearchPillSkeleton.js +41 -0
- package/dist/tools/SearchPill/SearchPillSkeleton.js.map +1 -0
- package/dist/tools/SearchPill/useSearch.js +143 -0
- package/dist/tools/SearchPill/useSearch.js.map +1 -0
- package/dist/tools/SearchPill/useSuggestions.js +105 -0
- package/dist/tools/SearchPill/useSuggestions.js.map +1 -0
- package/dist/tools/Tour/TourCard.js +156 -0
- package/dist/tools/Tour/TourCard.js.map +1 -0
- package/dist/tools/Tour/TourCard.styles.js +10 -0
- package/dist/tools/Tour/TourCard.styles.js.map +1 -0
- package/dist/tools/Tour/useTour.js +110 -0
- package/dist/tools/Tour/useTour.js.map +1 -0
- package/dist/tools/locate/useLocate.js +94 -0
- package/dist/tools/locate/useLocate.js.map +1 -0
- package/dist/ui/Button/Button.js +36 -0
- package/dist/ui/Button/Button.js.map +1 -0
- package/dist/ui/Button/Button.styles.js +17 -0
- package/dist/ui/Button/Button.styles.js.map +1 -0
- package/dist/ui/Chip/Chip.js +37 -0
- package/dist/ui/Chip/Chip.js.map +1 -0
- package/dist/ui/Chip/Chip.styles.js +29 -0
- package/dist/ui/Chip/Chip.styles.js.map +1 -0
- package/dist/ui/ControlGroup/ControlGroup.js +23 -0
- package/dist/ui/ControlGroup/ControlGroup.js.map +1 -0
- package/dist/ui/ControlGroup/ControlGroup.styles.js +6 -0
- package/dist/ui/ControlGroup/ControlGroup.styles.js.map +1 -0
- package/dist/ui/EmptyState/EmptyState.js +37 -0
- package/dist/ui/EmptyState/EmptyState.js.map +1 -0
- package/dist/ui/EmptyState/EmptyState.styles.js +10 -0
- package/dist/ui/EmptyState/EmptyState.styles.js.map +1 -0
- package/dist/ui/Icon/Icon.js +28 -0
- package/dist/ui/Icon/Icon.js.map +1 -0
- package/dist/ui/Icon/Icon.styles.js +8 -0
- package/dist/ui/Icon/Icon.styles.js.map +1 -0
- package/dist/ui/IconButton/IconButton.js +47 -0
- package/dist/ui/IconButton/IconButton.js.map +1 -0
- package/dist/ui/IconButton/IconButton.styles.js +27 -0
- package/dist/ui/IconButton/IconButton.styles.js.map +1 -0
- package/dist/ui/Isolate/Isolate.js +26 -0
- package/dist/ui/Isolate/Isolate.js.map +1 -0
- package/dist/ui/Isolate/fillSlots.js +27 -0
- package/dist/ui/Isolate/fillSlots.js.map +1 -0
- package/dist/ui/ListRow/ListRow.js +59 -0
- package/dist/ui/ListRow/ListRow.js.map +1 -0
- package/dist/ui/ListRow/ListRow.styles.js +30 -0
- package/dist/ui/ListRow/ListRow.styles.js.map +1 -0
- package/dist/ui/LiveRegion/LiveRegion.js +88 -0
- package/dist/ui/LiveRegion/LiveRegion.js.map +1 -0
- package/dist/ui/LiveRegion/announcer.js +114 -0
- package/dist/ui/LiveRegion/announcer.js.map +1 -0
- package/dist/ui/SegmentedControl/SegmentedControl.js +55 -0
- package/dist/ui/SegmentedControl/SegmentedControl.js.map +1 -0
- package/dist/ui/SegmentedControl/SegmentedControl.styles.js +9 -0
- package/dist/ui/SegmentedControl/SegmentedControl.styles.js.map +1 -0
- package/dist/ui/SkipLink/SkipLink.js +35 -0
- package/dist/ui/SkipLink/SkipLink.js.map +1 -0
- package/dist/ui/SkipLink/SkipLink.styles.js +6 -0
- package/dist/ui/SkipLink/SkipLink.styles.js.map +1 -0
- package/dist/ui/Slider/Slider.js +68 -0
- package/dist/ui/Slider/Slider.js.map +1 -0
- package/dist/ui/Slider/Slider.styles.js +13 -0
- package/dist/ui/Slider/Slider.styles.js.map +1 -0
- package/dist/ui/StatusMessage/StatusMessage.js +124 -0
- package/dist/ui/StatusMessage/StatusMessage.js.map +1 -0
- package/dist/ui/StatusMessage/StatusMessage.styles.js +28 -0
- package/dist/ui/StatusMessage/StatusMessage.styles.js.map +1 -0
- package/dist/ui/StatusMessage/StatusMessageFocus.js +30 -0
- package/dist/ui/StatusMessage/StatusMessageFocus.js.map +1 -0
- package/dist/ui/Surface/Surface.js +22 -0
- package/dist/ui/Surface/Surface.js.map +1 -0
- package/dist/ui/Surface/Surface.styles.js +27 -0
- package/dist/ui/Surface/Surface.styles.js.map +1 -0
- package/dist/ui/Switch/Switch.js +58 -0
- package/dist/ui/Switch/Switch.js.map +1 -0
- package/dist/ui/Switch/Switch.styles.js +13 -0
- package/dist/ui/Switch/Switch.styles.js.map +1 -0
- package/dist/ui/Tooltip/Tooltip.js +66 -0
- package/dist/ui/Tooltip/Tooltip.js.map +1 -0
- package/dist/ui/Tooltip/Tooltip.styles.js +6 -0
- package/dist/ui/Tooltip/Tooltip.styles.js.map +1 -0
- package/dist/ui/Tooltip/inheritColours.js +27 -0
- package/dist/ui/Tooltip/inheritColours.js.map +1 -0
- package/dist/ui/VisuallyHidden/VisuallyHidden.js +16 -0
- package/dist/ui/VisuallyHidden/VisuallyHidden.js.map +1 -0
- package/dist/ui/VisuallyHidden/VisuallyHidden.styles.js +6 -0
- package/dist/ui/VisuallyHidden/VisuallyHidden.styles.js.map +1 -0
- package/package.json +82 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,3845 @@
|
|
|
1
|
+
import type { AnchorHTMLAttributes } from 'react';
|
|
2
|
+
import { BasemapCatalogue } from '@mapcairn/core';
|
|
3
|
+
import { BasemapDefinition } from '@mapcairn/core';
|
|
4
|
+
import { Bounds } from '@mapcairn/core';
|
|
5
|
+
import type { ButtonHTMLAttributes } from 'react';
|
|
6
|
+
import type { CatalogueRefresh } from '@mapcairn/core';
|
|
7
|
+
import type { CatalogueState } from '@mapcairn/core';
|
|
8
|
+
import type { ChromeLayout } from '@mapcairn/core';
|
|
9
|
+
import { ClipboardPort } from '@mapcairn/core';
|
|
10
|
+
import type { ComponentType } from 'react';
|
|
11
|
+
import { Context } from 'react';
|
|
12
|
+
import { ControlValues } from '@mapcairn/core';
|
|
13
|
+
import { DefinitionText } from '@mapcairn/core';
|
|
14
|
+
import { DevicePreferencesValue } from '@mapcairn/core';
|
|
15
|
+
import { DirectionStop } from '@mapcairn/core';
|
|
16
|
+
import { DrawIssue } from '@mapcairn/core';
|
|
17
|
+
import { DrawKeyEvent } from '@mapcairn/core';
|
|
18
|
+
import { DrawKind } from '@mapcairn/core';
|
|
19
|
+
import { DrawSelection } from '@mapcairn/core';
|
|
20
|
+
import { DrawShape } from '@mapcairn/core';
|
|
21
|
+
import { DrawState } from '@mapcairn/core';
|
|
22
|
+
import type { ElementType } from 'react';
|
|
23
|
+
import { FeatureQuery } from '@mapcairn/core';
|
|
24
|
+
import { FeatureRef } from '@mapcairn/core';
|
|
25
|
+
import { FeatureSelection } from '@mapcairn/core';
|
|
26
|
+
import { FeedLayerDefinition } from '@mapcairn/core';
|
|
27
|
+
import { FeedShapeStyle } from '@mapcairn/core';
|
|
28
|
+
import { FileOpener } from '@mapcairn/core';
|
|
29
|
+
import { FileSaver } from '@mapcairn/core';
|
|
30
|
+
import { FocusEventHandler } from 'react';
|
|
31
|
+
import type { FocusTarget } from '@mapcairn/core';
|
|
32
|
+
import { FormatterRegistry } from '@mapcairn/core';
|
|
33
|
+
import { HeatmapLayerDefinition } from '@mapcairn/core';
|
|
34
|
+
import { HTMLAttributes } from 'react';
|
|
35
|
+
import { IdentifyTarget } from '@mapcairn/core';
|
|
36
|
+
import { JSX } from 'react';
|
|
37
|
+
import { KeyboardEvent as KeyboardEvent_2 } from 'react';
|
|
38
|
+
import { LanguageCatalogue } from '@mapcairn/core';
|
|
39
|
+
import { LatLng } from '@mapcairn/core';
|
|
40
|
+
import { LayerAttribution } from '@mapcairn/core';
|
|
41
|
+
import { LayerCatalogue } from '@mapcairn/core';
|
|
42
|
+
import { LayerDefinition } from '@mapcairn/core';
|
|
43
|
+
import { LayerFeature } from '@mapcairn/core';
|
|
44
|
+
import { LayersUrlState } from '@mapcairn/core';
|
|
45
|
+
import { LegendEntry } from '@mapcairn/core';
|
|
46
|
+
import type { LiHTMLAttributes } from 'react';
|
|
47
|
+
import { LocationErrorKind } from '@mapcairn/core';
|
|
48
|
+
import { LocationFix } from '@mapcairn/core';
|
|
49
|
+
import { LocationProvider } from '@mapcairn/core';
|
|
50
|
+
import { MapAdapter } from '@mapcairn/core';
|
|
51
|
+
import { MapAdapterFactory } from '@mapcairn/core';
|
|
52
|
+
import { MapClickEvent } from '@mapcairn/core';
|
|
53
|
+
import { MapEditHandle } from '@mapcairn/core';
|
|
54
|
+
import { MapEngineError } from '@mapcairn/core';
|
|
55
|
+
import { MapFeature } from '@mapcairn/core';
|
|
56
|
+
import { MapFeatureTap } from '@mapcairn/core';
|
|
57
|
+
import { MapHandleDrag } from '@mapcairn/core';
|
|
58
|
+
import { MapHeatmap } from '@mapcairn/core';
|
|
59
|
+
import { MapImageDrawing } from '@mapcairn/core';
|
|
60
|
+
import { MapKeyHelpEntry } from '@mapcairn/core';
|
|
61
|
+
import { MapLookRule } from '@mapcairn/core';
|
|
62
|
+
import type { MapPlacement } from '@mapcairn/core';
|
|
63
|
+
import type { MapProjection } from '@mapcairn/core';
|
|
64
|
+
import { MapStyledShapes } from '@mapcairn/core';
|
|
65
|
+
import { MapVectorTiles } from '@mapcairn/core';
|
|
66
|
+
import type { MarkerShape } from '@mapcairn/core';
|
|
67
|
+
import { Message } from '@mapcairn/core';
|
|
68
|
+
import { MessageCatalogue } from '@mapcairn/core';
|
|
69
|
+
import { MouseEvent as MouseEvent_2 } from 'react';
|
|
70
|
+
import type { MouseEventHandler } from 'react';
|
|
71
|
+
import { PaletteSlot } from '@mapcairn/core';
|
|
72
|
+
import type { PixelPoint } from '@mapcairn/core';
|
|
73
|
+
import { PointerEvent as PointerEvent_2 } from 'react';
|
|
74
|
+
import { PointStyle } from '@mapcairn/core';
|
|
75
|
+
import { ReachableAreaFeature } from '@mapcairn/core';
|
|
76
|
+
import type { ReactElement } from 'react';
|
|
77
|
+
import { ReactNode } from 'react';
|
|
78
|
+
import { Ref } from 'react';
|
|
79
|
+
import { RefObject } from 'react';
|
|
80
|
+
import { ResolvedTheme } from '@mapcairn/core';
|
|
81
|
+
import { RouteLeg } from '@mapcairn/core';
|
|
82
|
+
import { RoutingErrorKind } from '@mapcairn/core';
|
|
83
|
+
import { RoutingProvider } from '@mapcairn/core';
|
|
84
|
+
import { RoutingRequestKind } from '@mapcairn/core';
|
|
85
|
+
import { SearchErrorKind } from '@mapcairn/core';
|
|
86
|
+
import { SearchProvider } from '@mapcairn/core';
|
|
87
|
+
import { SearchResult } from '@mapcairn/core';
|
|
88
|
+
import type { Services } from '@mapcairn/core';
|
|
89
|
+
import { Settings } from '@mapcairn/core';
|
|
90
|
+
import { SheetDetent } from '@mapcairn/core';
|
|
91
|
+
import { SheetSection } from '@mapcairn/core';
|
|
92
|
+
import { SuggestionProvider } from '@mapcairn/core';
|
|
93
|
+
import type { SVGProps } from 'react';
|
|
94
|
+
import { ThemeChoice } from '@mapcairn/core';
|
|
95
|
+
import { ThemeSource } from '@mapcairn/core';
|
|
96
|
+
import { TourAdvance } from '@mapcairn/core';
|
|
97
|
+
import { TourSnapshot } from '@mapcairn/core';
|
|
98
|
+
import { TourState } from '@mapcairn/core';
|
|
99
|
+
import { TravelMode } from '@mapcairn/core';
|
|
100
|
+
import { UnitSystem } from '@mapcairn/core';
|
|
101
|
+
import { UrlState } from '@mapcairn/core';
|
|
102
|
+
import { VectorTileLayerDefinition } from '@mapcairn/core';
|
|
103
|
+
import { ViewState } from '@mapcairn/core';
|
|
104
|
+
import { WktAxisOrder } from '@mapcairn/core';
|
|
105
|
+
import { ZoomLimit } from '@mapcairn/core';
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* The circle around a found location, sized from the ground resolution at its
|
|
109
|
+
* latitude so it matches the real accuracy at every zoom (on a globe, the
|
|
110
|
+
* resolution at the view centre, which holds across the sphere). Render it
|
|
111
|
+
* inside `MapOverlayLayer`.
|
|
112
|
+
*/
|
|
113
|
+
export declare function AccuracyCircle({ center, accuracyMetres, testId, }: AccuracyCircleProps): JSX.Element | null;
|
|
114
|
+
|
|
115
|
+
/** Props for {@link AccuracyCircle}. */
|
|
116
|
+
export declare interface AccuracyCircleProps {
|
|
117
|
+
readonly center: LatLng;
|
|
118
|
+
/** The location's accuracy radius on the ground. */
|
|
119
|
+
readonly accuracyMetres: number;
|
|
120
|
+
readonly testId?: string;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Where the address lookup for a position stands. */
|
|
124
|
+
export declare type AddressState = {
|
|
125
|
+
readonly status: "idle";
|
|
126
|
+
} | {
|
|
127
|
+
readonly status: "loading";
|
|
128
|
+
} | {
|
|
129
|
+
readonly status: "found";
|
|
130
|
+
readonly text: string;
|
|
131
|
+
} | {
|
|
132
|
+
readonly status: "none";
|
|
133
|
+
} | {
|
|
134
|
+
readonly status: "error";
|
|
135
|
+
};
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Sends a message to the one app-wide announcer: text, or a {@link Message}
|
|
139
|
+
* (a key and its parameters) that is formatted with the active catalogue
|
|
140
|
+
* just before it is queued.
|
|
141
|
+
*/
|
|
142
|
+
export declare type Announce = (message: string | Message, options?: AnnounceOptions) => void;
|
|
143
|
+
|
|
144
|
+
/** Options for a single announcement. */
|
|
145
|
+
export declare interface AnnounceOptions {
|
|
146
|
+
/** `polite` waits for the screen reader to finish; `assertive` interrupts. Defaults to `polite`. */
|
|
147
|
+
readonly priority?: AnnouncePriority;
|
|
148
|
+
/**
|
|
149
|
+
* Speak this message even when others follow it closely. A message that is
|
|
150
|
+
* not kept is replaced by a later one that arrives before the throttle
|
|
151
|
+
* window ends, which suits a stream of updates. Set `keep` on a message that
|
|
152
|
+
* reports the outcome of something the person did, so a later message does
|
|
153
|
+
* not replace it. Kept messages wait their turn, one per window, in order.
|
|
154
|
+
*/
|
|
155
|
+
readonly keep?: boolean;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** How urgently a message is read out. */
|
|
159
|
+
export declare type AnnouncePriority = "polite" | "assertive";
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Map id of the travel-time area.
|
|
163
|
+
*
|
|
164
|
+
* @internal
|
|
165
|
+
*/
|
|
166
|
+
export declare const AREA_LAYER_ID = ":area";
|
|
167
|
+
|
|
168
|
+
/** A travel-time area that is on the map. */
|
|
169
|
+
export declare interface AreaOutcome {
|
|
170
|
+
readonly kind: "area";
|
|
171
|
+
readonly mode: TravelMode;
|
|
172
|
+
readonly minutes: number;
|
|
173
|
+
/** Where the area is reachable from: the first stop. */
|
|
174
|
+
readonly origin: LatLng;
|
|
175
|
+
readonly features: readonly ReachableAreaFeature[];
|
|
176
|
+
/** The ground area, in square metres. */
|
|
177
|
+
readonly size: number;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The map credits for the bottom-end slot: a compact "Map credits" button
|
|
182
|
+
* (a 44 px target around a small info glyph) that expands into a labelled
|
|
183
|
+
* region of credit links built with `buildAttribution`.
|
|
184
|
+
*
|
|
185
|
+
* @remarks The credits are shown by themselves once, when the map has
|
|
186
|
+
* started, because the OpenStreetMap attribution guidelines allow them to
|
|
187
|
+
* be collapsed only after they have been seen. That first showing moves no
|
|
188
|
+
* focus and is a plain region, not a dialog or live region, so nothing is
|
|
189
|
+
* announced. It collapses on the first map interaction (a zoom the person
|
|
190
|
+
* makes, the map moving, a press outside it) or after
|
|
191
|
+
* {@link ATTRIBUTION_INTRO_MS}, whichever comes first, fading out unless
|
|
192
|
+
* reduced motion is on. Focus moving into it during that time keeps it
|
|
193
|
+
* open as if the person had opened it.
|
|
194
|
+
*
|
|
195
|
+
* After that it behaves as a popover the person opens. It opens above the
|
|
196
|
+
* bottom row, clear of the readout beside the button; where it starts a gap
|
|
197
|
+
* after the readout's end edge, so the two share no width, it sits next to
|
|
198
|
+
* the button instead of rising over the readout's height, and it is
|
|
199
|
+
* measured again when the readout resizes or slides sideways. If the
|
|
200
|
+
* credits would scroll there, it moves beside the end stack before it is
|
|
201
|
+
* painted, where
|
|
202
|
+
* `MapChrome` measures more room; it scrolls only if that is not enough
|
|
203
|
+
* either. Opening moves focus to the first link.
|
|
204
|
+
* The popover closes on Escape, on a second press of the button, on a
|
|
205
|
+
* pointer down outside it, and when the map moves; if focus was inside it,
|
|
206
|
+
* focus goes back to the button with an explicit `focus()` (Safari does not
|
|
207
|
+
* focus buttons on click). The credits are always reachable through the
|
|
208
|
+
* button; nothing here hides or removes them. Reads the map with
|
|
209
|
+
* `useMap()`, so it must sit inside the map context.
|
|
210
|
+
*/
|
|
211
|
+
export declare function Attribution({ basemap, layerCredits, }: AttributionProps): JSX.Element;
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* How long the credits take to fade out after their first showing.
|
|
215
|
+
*
|
|
216
|
+
* @internal
|
|
217
|
+
*/
|
|
218
|
+
export declare const ATTRIBUTION_FADE_MS = 200;
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* How long the credits stay on screen by themselves once the map has
|
|
222
|
+
* started, if the person does nothing with the map first.
|
|
223
|
+
*
|
|
224
|
+
* @internal
|
|
225
|
+
*/
|
|
226
|
+
export declare const ATTRIBUTION_INTRO_MS = 5000;
|
|
227
|
+
|
|
228
|
+
/** Props for {@link Attribution}. */
|
|
229
|
+
export declare interface AttributionProps {
|
|
230
|
+
/** The active basemap. Its credits, plus the engine's, are listed. */
|
|
231
|
+
readonly basemap: BasemapDefinition;
|
|
232
|
+
/** Credits of the data layers that are on, listed after the map's own. */
|
|
233
|
+
readonly layerCredits?: readonly LayerAttribution[];
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* The credits button as a decorative stand-in for the server-rendered
|
|
238
|
+
* `ChromeSkeleton`: the same anchor and icon classes as {@link Attribution},
|
|
239
|
+
* so it sits in the same box, with the popover left out.
|
|
240
|
+
*
|
|
241
|
+
* @remarks Only ever rendered inside an `aria-hidden`, `inert` container. It
|
|
242
|
+
* uses no hooks, so it needs no map or provider: its name arrives as `label`.
|
|
243
|
+
*/
|
|
244
|
+
export declare function AttributionSkeleton({ label }: AttributionSkeletonProps): JSX.Element;
|
|
245
|
+
|
|
246
|
+
/** Props for {@link AttributionSkeleton}. */
|
|
247
|
+
export declare interface AttributionSkeletonProps {
|
|
248
|
+
/** The credits button's name, in the host's default language. */
|
|
249
|
+
readonly label: string;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/** What {@link useBasemapAvailability} returns. */
|
|
253
|
+
export declare interface BasemapAvailability {
|
|
254
|
+
/** The ids of the basemaps that are not working right now. Held in memory, never stored. */
|
|
255
|
+
readonly unavailable: ReadonlySet<string>;
|
|
256
|
+
/**
|
|
257
|
+
* Marks a basemap unavailable. The mark lapses after
|
|
258
|
+
* {@link UNAVAILABLE_FOR_MS}, so a provider that recovers returns without a
|
|
259
|
+
* reload, and marking it again restarts that time.
|
|
260
|
+
*/
|
|
261
|
+
readonly markUnavailable: (id: string) => void;
|
|
262
|
+
/** Marks one basemap, or every basemap when no id is given, available again. */
|
|
263
|
+
readonly clear: (id?: string) => void;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
/**
|
|
267
|
+
* Keeps which basemaps are not working, for the picker (which disables their
|
|
268
|
+
* tiles) and for the app (which marks a basemap whose tiles all failed).
|
|
269
|
+
* {@link ServicesProvider} mounts it, so every component below can read it.
|
|
270
|
+
*/
|
|
271
|
+
export declare function BasemapAvailabilityProvider({ children, }: {
|
|
272
|
+
readonly children: ReactNode;
|
|
273
|
+
}): JSX.Element;
|
|
274
|
+
|
|
275
|
+
/**
|
|
276
|
+
* Chooses the basemap: a three-across grid of previews as a radio group, one
|
|
277
|
+
* tile for each basemap the host offers (`useBasemaps`).
|
|
278
|
+
*
|
|
279
|
+
* Each tile is a native radio input, visually hidden and drawn through its
|
|
280
|
+
* label. Native radios give one tab stop for the group, arrow keys that move
|
|
281
|
+
* and select in one step (wrapping at the ends and following the writing
|
|
282
|
+
* direction) and the radio role in every screen reader, with no script. The
|
|
283
|
+
* selected tile has an accent outline and a check badge, so selection never
|
|
284
|
+
* relies on colour. A preview that fails to load gives way to the basemap's
|
|
285
|
+
* swatch, as a basemap with no preview does, with the name still visible. The
|
|
286
|
+
* basemap does not follow the interface theme: a host's dark basemap is an
|
|
287
|
+
* ordinary choice, as the others are.
|
|
288
|
+
*
|
|
289
|
+
* @remarks In Save data mode (`useSaveData`), and for a basemap that has no
|
|
290
|
+
* preview image, no preview is requested: the tile shows the same frame
|
|
291
|
+
* with a plain colour swatch, the basemap's own `swatch` colour or else the
|
|
292
|
+
* map background. A basemap whose tiles are images (`usesMoreData`: a
|
|
293
|
+
* raster map, or imagery under labels) carries the note "Uses more data". Names,
|
|
294
|
+
* the radios and the selection badge are unchanged, and every basemap can
|
|
295
|
+
* still be chosen.
|
|
296
|
+
*
|
|
297
|
+
* A basemap marked unavailable (`useBasemapAvailability`, which the host
|
|
298
|
+
* sets when every tile of it failed) has the words "Not available right
|
|
299
|
+
* now" inside its label, so they are part of the radio's name, and its
|
|
300
|
+
* radio is natively disabled, so the arrow keys skip it, unless it is the
|
|
301
|
+
* chosen one. While any basemap is marked, a "Try again" button under the
|
|
302
|
+
* group clears every mark, so the map judges a basemap again when it is
|
|
303
|
+
* chosen, and moves focus to the chosen radio, because the button goes.
|
|
304
|
+
*/
|
|
305
|
+
export declare function BasemapPicker({ value, onChange }: BasemapPickerProps): JSX.Element;
|
|
306
|
+
|
|
307
|
+
/** Props for {@link BasemapPicker}. */
|
|
308
|
+
export declare interface BasemapPickerProps {
|
|
309
|
+
/**
|
|
310
|
+
* The chosen basemap id. An id that names no basemap on offer is shown as
|
|
311
|
+
* the default basemap.
|
|
312
|
+
*/
|
|
313
|
+
readonly value: string;
|
|
314
|
+
/** Called with the id of the tile the user chose. */
|
|
315
|
+
readonly onChange: (id: string) => void;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* A text button, 48 px tall at least. Defaults to `type="button"` so it never
|
|
320
|
+
* submits a form by accident.
|
|
321
|
+
*/
|
|
322
|
+
export declare function Button({ variant, icon, mirrorInRtl, busy, disabled, type, className, onClick, children, ...rest }: ButtonProps): JSX.Element;
|
|
323
|
+
|
|
324
|
+
/** Props for {@link Button}. */
|
|
325
|
+
export declare interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-busy" | "aria-disabled" | "disabled"> {
|
|
326
|
+
/** `primary` is the filled accent button, `quiet` has no fill. Defaults to `primary`. */
|
|
327
|
+
readonly variant?: "primary" | "secondary" | "quiet";
|
|
328
|
+
/** A leading icon, imported by name from `lucide-react`. */
|
|
329
|
+
readonly icon?: IconComponent;
|
|
330
|
+
/** Flips the leading icon when the page reads right to left, for one that points along the reading direction. */
|
|
331
|
+
readonly mirrorInRtl?: boolean;
|
|
332
|
+
/**
|
|
333
|
+
* Replaces the leading icon with a loader and sets `aria-busy`. Clicks are
|
|
334
|
+
* ignored while busy. The visible label stays, so the name is stable.
|
|
335
|
+
*/
|
|
336
|
+
readonly busy?: boolean;
|
|
337
|
+
/**
|
|
338
|
+
* Disables the action with `aria-disabled`. The button stays focusable and
|
|
339
|
+
* clicks do nothing.
|
|
340
|
+
*/
|
|
341
|
+
readonly disabled?: boolean;
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/** What the Layers section needs to know about the catalogue besides its layers. */
|
|
345
|
+
export declare interface CatalogueView {
|
|
346
|
+
readonly status: CatalogueState["status"];
|
|
347
|
+
/** How many definitions the host supplied that were left out. Zero unless `ready`. */
|
|
348
|
+
readonly skipped: number;
|
|
349
|
+
/** Where a refresh of the list has got to. `idle` unless `ready`. */
|
|
350
|
+
readonly refresh: CatalogueRefresh;
|
|
351
|
+
/** Whether the last attempt to load failed (see {@link loadFailed}), so Try again has something to do. */
|
|
352
|
+
readonly failed: boolean;
|
|
353
|
+
/**
|
|
354
|
+
* True when the catalogue was not ready at mount, so its list arrived or
|
|
355
|
+
* will arrive later and an empty one is worth saying. False for a host whose
|
|
356
|
+
* layers were there from the start.
|
|
357
|
+
*/
|
|
358
|
+
readonly awaited: boolean;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/**
|
|
362
|
+
* A small crosshair at the centre of the map, shown while measuring so "Add
|
|
363
|
+
* point at map centre" has a visible target. Render it inside
|
|
364
|
+
* `MapOverlayLayer` only while measuring.
|
|
365
|
+
*/
|
|
366
|
+
export declare function CentreCrosshair({ at, testId }: CentreCrosshairProps): JSX.Element | null;
|
|
367
|
+
|
|
368
|
+
/** Props for {@link CentreCrosshair}. */
|
|
369
|
+
export declare interface CentreCrosshairProps {
|
|
370
|
+
/**
|
|
371
|
+
* Where to draw it, in pixels from the map's top left. Defaults to the
|
|
372
|
+
* centre of the whole map; a tool whose panel covers part of the map passes
|
|
373
|
+
* the middle of what is left.
|
|
374
|
+
*/
|
|
375
|
+
readonly at?: {
|
|
376
|
+
readonly x: number;
|
|
377
|
+
readonly y: number;
|
|
378
|
+
};
|
|
379
|
+
readonly testId?: string;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
/**
|
|
383
|
+
* A small pill. With `onClick` it is a toggle `button` with `aria-pressed`;
|
|
384
|
+
* without it, a static `span` that only labels.
|
|
385
|
+
*/
|
|
386
|
+
export declare function Chip({ children, icon, selected, onClick, className, ...rest }: ChipProps): JSX.Element;
|
|
387
|
+
|
|
388
|
+
/** Props for {@link Chip}. */
|
|
389
|
+
export declare interface ChipProps extends Omit<HTMLAttributes<HTMLElement>, "children" | "onClick"> {
|
|
390
|
+
/** The chip text. */
|
|
391
|
+
readonly children: ReactNode;
|
|
392
|
+
/** A leading icon, imported by name from `lucide-react`. */
|
|
393
|
+
readonly icon?: IconComponent;
|
|
394
|
+
/**
|
|
395
|
+
* Whether the chip is on. Shown with a check icon in place of the leading
|
|
396
|
+
* icon. On a chip with `onClick` it is also `aria-pressed`.
|
|
397
|
+
*/
|
|
398
|
+
readonly selected?: boolean;
|
|
399
|
+
/** Makes the chip a toggle button. Without it the chip is a plain label. */
|
|
400
|
+
readonly onClick?: MouseEventHandler<HTMLButtonElement>;
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
/** Provides layout facts and the edge-publishing callbacks. Only `MapChrome` mounts this. */
|
|
404
|
+
export declare function ChromeLayoutProvider({ value, children, }: ChromeLayoutProviderProps): JSX.Element;
|
|
405
|
+
|
|
406
|
+
/** Props for {@link ChromeLayoutProvider}. */
|
|
407
|
+
export declare interface ChromeLayoutProviderProps {
|
|
408
|
+
readonly value: ChromeLayoutValue;
|
|
409
|
+
readonly children: ReactNode;
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/** What {@link MapChrome} tells the surfaces and slots inside it. */
|
|
413
|
+
export declare interface ChromeLayoutValue {
|
|
414
|
+
/** Bottom sheet on narrow, tall screens; side panel from 768px wide or under 500px tall. */
|
|
415
|
+
readonly layout: ChromeLayout;
|
|
416
|
+
/** The size of the chrome container, in CSS pixels. */
|
|
417
|
+
readonly viewport: {
|
|
418
|
+
readonly width: number;
|
|
419
|
+
readonly height: number;
|
|
420
|
+
};
|
|
421
|
+
/** The primary input is a fine pointer, so zoom buttons and keyboard help make sense by default. */
|
|
422
|
+
readonly finePointer: boolean;
|
|
423
|
+
/** The distance from inline-start to the open panel's far edge, in px. Null in the sheet layout or before measurement. */
|
|
424
|
+
readonly panelEdge: number | null;
|
|
425
|
+
/**
|
|
426
|
+
* Distance from the map's bottom edge to the top of the visible map key.
|
|
427
|
+
* Null while the key is absent or has given way.
|
|
428
|
+
*/
|
|
429
|
+
readonly mapKeyClearance?: number | null;
|
|
430
|
+
/**
|
|
431
|
+
* The sheet publishes its current top edge (px from the top of the chrome
|
|
432
|
+
* container) so the bottom slots can ride above it. Pass null when closed.
|
|
433
|
+
*/
|
|
434
|
+
publishSheetTop(px: number | null): void;
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
/**
|
|
438
|
+
* The server-rendered stand-in for `MapChrome`: the search pill, the map
|
|
439
|
+
* controls, the zoom group on a device with a fine pointer and the credits
|
|
440
|
+
* button, each in the slot and grid the live chrome uses, so the live chrome
|
|
441
|
+
* replaces it in the same boxes. Render it over the map's background colour,
|
|
442
|
+
* as the first paint before the map app mounts.
|
|
443
|
+
*
|
|
444
|
+
* @remarks It is decorative: `aria-hidden` and `inert`, so nobody can focus a
|
|
445
|
+
* control that does nothing yet. It reuses the {@link MapChrome} grid,
|
|
446
|
+
* padding and slot classes, and the real controls' own classes. The layout
|
|
447
|
+
* (bottom sheet or side panel) follows a media query built from the
|
|
448
|
+
* constants `chooseLayout` uses, because the server cannot measure the
|
|
449
|
+
* container. It writes no `style` attribute (production CSP is
|
|
450
|
+
* `style-src 'self'`), uses no hooks and needs no provider (its words arrive
|
|
451
|
+
* as `copy`), and is the same
|
|
452
|
+
* in light and dark themes because it uses only theme tokens.
|
|
453
|
+
*/
|
|
454
|
+
export declare function ChromeSkeleton({ copy, directions, draw, }: ChromeSkeletonProps): JSX.Element;
|
|
455
|
+
|
|
456
|
+
/** The words of every control {@link ChromeSkeleton} draws, in the host's default language. */
|
|
457
|
+
export declare interface ChromeSkeletonCopy {
|
|
458
|
+
readonly search: SearchPillSkeletonCopy;
|
|
459
|
+
readonly endStack: EndStackSkeletonCopy;
|
|
460
|
+
/** The credits button's name. */
|
|
461
|
+
readonly credits: string;
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
/**
|
|
465
|
+
* The skeleton's words from `catalogue`, by the keys the live search pill,
|
|
466
|
+
* end stack and credits button use, so the skeleton and the controls that
|
|
467
|
+
* replace it say the same. A host calls it with its default-language
|
|
468
|
+
* catalogue, on the server and in the browser alike, because the skeleton
|
|
469
|
+
* uses no hook and no provider.
|
|
470
|
+
*/
|
|
471
|
+
export declare function chromeSkeletonCopy({ t, }: MessageCatalogue): ChromeSkeletonCopy;
|
|
472
|
+
|
|
473
|
+
/** Props for {@link ChromeSkeleton}. */
|
|
474
|
+
export declare interface ChromeSkeletonProps {
|
|
475
|
+
/** The words of every control, from {@link chromeSkeletonCopy}. */
|
|
476
|
+
readonly copy: ChromeSkeletonCopy;
|
|
477
|
+
/**
|
|
478
|
+
* Draws the Directions button, which the live chrome shows when the host
|
|
479
|
+
* offers directions, so the controls are in their final places on first paint.
|
|
480
|
+
*/
|
|
481
|
+
readonly directions?: boolean;
|
|
482
|
+
/** Show the Draw shapes button, so the skeleton matches a host whose live chrome offers drawing. */
|
|
483
|
+
readonly draw?: boolean;
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
/**
|
|
487
|
+
* Icon buttons stacked on one floating surface, separated by hairlines. It is
|
|
488
|
+
* a plain `group`, not a toolbar, so it adds no arrow-key behaviour.
|
|
489
|
+
* @remarks Children should be `IconButton`s, which keep their 48 px targets.
|
|
490
|
+
* Pass `data-chrome` through for the layout owner.
|
|
491
|
+
*/
|
|
492
|
+
export declare function ControlGroup({ label, className, children, ...rest }: ControlGroupProps): JSX.Element;
|
|
493
|
+
|
|
494
|
+
/** Props for {@link ControlGroup}. */
|
|
495
|
+
export declare interface ControlGroupProps extends Omit<HTMLAttributes<HTMLElement>, "aria-label" | "role"> {
|
|
496
|
+
/** The accessible name of the group, for example "Zoom". */
|
|
497
|
+
readonly label: string;
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
/**
|
|
501
|
+
* The position under the pointer and the zoom level, as plain muted text with
|
|
502
|
+
* tabular figures. It is not a live region: the settled zoom is already
|
|
503
|
+
* announced after each zoom, so a change here is not spoken.
|
|
504
|
+
*
|
|
505
|
+
* @remarks The zoom is drawn as "z 12.4", which is `aria-hidden` and not
|
|
506
|
+
* selectable, and carried as visually hidden text ("Zoom 12.4", after a
|
|
507
|
+
* comma when a position comes first), so a screen reader and a copy of the
|
|
508
|
+
* text read it once and in full, in the order the eye sees it.
|
|
509
|
+
*/
|
|
510
|
+
export declare function CursorCoordinates({ latlng, zoom }: CursorCoordinatesProps): JSX.Element | null;
|
|
511
|
+
|
|
512
|
+
/** Props for {@link CursorCoordinates}. */
|
|
513
|
+
export declare interface CursorCoordinatesProps {
|
|
514
|
+
/**
|
|
515
|
+
* The position under the pointer, or null to show nothing. The app passes
|
|
516
|
+
* null on touch devices, where there is no hovering pointer.
|
|
517
|
+
*/
|
|
518
|
+
readonly latlng: LatLng | null;
|
|
519
|
+
/**
|
|
520
|
+
* The map's zoom level in the 256 px tile convention, shown beside the
|
|
521
|
+
* position as "z 12.4", or undefined to leave it out.
|
|
522
|
+
*/
|
|
523
|
+
readonly zoom?: number;
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
/** What {@link useDataLayers} returns: the layers' state and every action on them. */
|
|
527
|
+
export declare interface DataLayers {
|
|
528
|
+
/** Every registered layer, in catalogue order. Empty while the catalogue is loading or has failed. */
|
|
529
|
+
readonly layers: readonly DataLayerState[];
|
|
530
|
+
/** What the catalogue is doing besides holding layers: loading, failed, how many definitions it skipped, and how a refresh went. */
|
|
531
|
+
readonly catalogue: CatalogueView;
|
|
532
|
+
/**
|
|
533
|
+
* Asks the catalogue to load again after a failed load or a failed refresh,
|
|
534
|
+
* which the section's Try again does. It does nothing in any other state:
|
|
535
|
+
* only the host refreshes a catalogue that is working.
|
|
536
|
+
*/
|
|
537
|
+
retryCatalogue(): void;
|
|
538
|
+
readonly selected: SelectedFeature | null;
|
|
539
|
+
/**
|
|
540
|
+
* The features a tap or the keyboard found together, when there were
|
|
541
|
+
* several, so one can be chosen. Null when no list is open. The open card
|
|
542
|
+
* offers a way back to it while it is.
|
|
543
|
+
*/
|
|
544
|
+
readonly choices: readonly SelectedFeature[] | null;
|
|
545
|
+
readonly detail: DetailState | null;
|
|
546
|
+
/** Grows each time opening a card asks for it to take focus (a tap on the map). */
|
|
547
|
+
readonly focusRequest: number;
|
|
548
|
+
/**
|
|
549
|
+
* True from a request for the card to take focus until
|
|
550
|
+
* {@link DataLayers.consumeFocus}. The section that shows the card is
|
|
551
|
+
* unmounted whenever the sheet closes, so what has been acted on is kept
|
|
552
|
+
* here: reopening the sheet later must not repeat it.
|
|
553
|
+
*/
|
|
554
|
+
readonly focusPending: boolean;
|
|
555
|
+
/** Marks the latest focus request as acted on. */
|
|
556
|
+
readonly consumeFocus: () => void;
|
|
557
|
+
/**
|
|
558
|
+
* The layers part of the permalink: the layers that are on, and the
|
|
559
|
+
* link's layers still waiting for a catalogue that is loading or has
|
|
560
|
+
* failed, so writing the address does not erase them.
|
|
561
|
+
*/
|
|
562
|
+
readonly urlValue: LayersUrlState;
|
|
563
|
+
/** The credits of the layers that are on, for the map credits. */
|
|
564
|
+
readonly credits: readonly LayerAttribution[];
|
|
565
|
+
/** The clock the hook uses, for relative times in cards and lists. */
|
|
566
|
+
readonly now: () => number;
|
|
567
|
+
setEnabled(id: string, enabled: boolean): void;
|
|
568
|
+
/**
|
|
569
|
+
* Turns several layers off as one change: one state update, so one redraw
|
|
570
|
+
* and one address update, and one announcement ("3 layers turned off. Undo available"). Ids
|
|
571
|
+
* that are not on, or not known, are ignored, and nothing happens when none
|
|
572
|
+
* is on. Each layer's open card, list of choices and affected area
|
|
573
|
+
* close as they do for a single layer. It offers {@link DataLayers.turnedOff}
|
|
574
|
+
* for {@link UNDO_TIMEOUT_MS}, replacing any earlier offer. `group` says
|
|
575
|
+
* which group's action asked, so the ui can tell a group's action from the
|
|
576
|
+
* one for every layer; it is not words, and the ui finds the group to show
|
|
577
|
+
* the Undo beside by {@link TurnedOff.ids}.
|
|
578
|
+
*/
|
|
579
|
+
turnOff(ids: readonly string[], options?: {
|
|
580
|
+
readonly group?: string;
|
|
581
|
+
}): void;
|
|
582
|
+
/** The batch Undo would turn back on, or null when none is on offer (none yet, used, replaced, expired or every layer of it already on again). */
|
|
583
|
+
readonly turnedOff: TurnedOff | null;
|
|
584
|
+
/**
|
|
585
|
+
* Turns back on the layers of the last {@link DataLayers.turnOff}, in one
|
|
586
|
+
* change and one announcement. A layer's control values stay while it is
|
|
587
|
+
* off, so they come back as they are. A layer that is on again, or no
|
|
588
|
+
* longer in the catalogue, is skipped; the rest of what the person changed
|
|
589
|
+
* meanwhile is left as it is. Does nothing when no offer is open.
|
|
590
|
+
*/
|
|
591
|
+
undoTurnOff(): void;
|
|
592
|
+
/** Pauses the offer's countdown while `by` is on its status. The countdown waits until every holder has released. */
|
|
593
|
+
holdUndo(by: UndoHolder): void;
|
|
594
|
+
/** Ends `by`'s hold; once none is left the countdown starts again, in full. */
|
|
595
|
+
releaseUndo(by: UndoHolder): void;
|
|
596
|
+
setControl(id: string, controlId: string, value: string): void;
|
|
597
|
+
setSort(id: string, sortId: string): void;
|
|
598
|
+
retry(id: string): void;
|
|
599
|
+
/**
|
|
600
|
+
* Records that a tile layer has had tiles asked for and none has loaded for
|
|
601
|
+
* a long while, which `MapDataLayers` calls from the adapter's report. `tiles`
|
|
602
|
+
* is the template those tiles came from: a report for anything but the
|
|
603
|
+
* layer's current tiles, or for a layer that is off, is ignored, as is one
|
|
604
|
+
* for tiles the layer already reported as slow or unavailable. The layer then
|
|
605
|
+
* says it is still waiting, and announces it once in a message that is kept,
|
|
606
|
+
* because the person turned the layer on and would otherwise see nothing,
|
|
607
|
+
* until its tiles change, it is turned off, or a tile loads later (see
|
|
608
|
+
* {@link DataLayers.reportTilesRecovered}).
|
|
609
|
+
*/
|
|
610
|
+
reportTilesSlow(id: string, tiles: string): void;
|
|
611
|
+
/**
|
|
612
|
+
* Records that the map settled with none of a tile layer's tiles loaded,
|
|
613
|
+
* which `MapDataLayers` calls from the adapter's report. `tiles` is the
|
|
614
|
+
* template those tiles came from: a report for anything but the layer's
|
|
615
|
+
* current tiles, or for a layer that is off, is ignored. The layer then
|
|
616
|
+
* says so and announces it once, until its tiles change, it is turned off, or
|
|
617
|
+
* a tile loads later (see {@link DataLayers.reportTilesRecovered}). It
|
|
618
|
+
* replaces the status of a layer reported slow for the same tiles.
|
|
619
|
+
*/
|
|
620
|
+
reportTilesUnavailable(id: string, tiles: string): void;
|
|
621
|
+
/**
|
|
622
|
+
* Records that a tile loaded for the `tiles` a layer had reported slow or
|
|
623
|
+
* with no tiles, which `MapDataLayers` calls from the adapter's report. The
|
|
624
|
+
* layer's status goes and the layer says so once, politely. A recovery for
|
|
625
|
+
* any other tiles, or for a layer that is not showing the status, is ignored.
|
|
626
|
+
*/
|
|
627
|
+
reportTilesRecovered(id: string, tiles: string): void;
|
|
628
|
+
/**
|
|
629
|
+
* Opens a feature's card, or closes it (and any list) with `null`. A card
|
|
630
|
+
* opened without `keepChoices` also closes the list of features found
|
|
631
|
+
* together.
|
|
632
|
+
*/
|
|
633
|
+
select(layerId: string, featureId: string | null, options?: {
|
|
634
|
+
readonly focus?: boolean;
|
|
635
|
+
/** Keeps the list of features found together open behind the card. */
|
|
636
|
+
readonly keepChoices?: boolean;
|
|
637
|
+
}): void;
|
|
638
|
+
/**
|
|
639
|
+
* Handles several features found at once (a tap or the keyboard route):
|
|
640
|
+
* with one it opens its card, with more it opens the list to choose from,
|
|
641
|
+
* and with none it does nothing. Features no loaded layer has are dropped.
|
|
642
|
+
*/
|
|
643
|
+
choose(hits: readonly {
|
|
644
|
+
readonly layerId: string;
|
|
645
|
+
readonly featureId: string;
|
|
646
|
+
}[], options?: {
|
|
647
|
+
readonly focus?: boolean;
|
|
648
|
+
}): void;
|
|
649
|
+
/**
|
|
650
|
+
* Asks the raster layers that answer a tap what is at a place, and opens
|
|
651
|
+
* what they find: one feature opens its card, several open the list to
|
|
652
|
+
* choose from, and none leaves an open card alone.
|
|
653
|
+
*
|
|
654
|
+
* It asks each layer that is on, has an `identify` block, shows imagery and
|
|
655
|
+
* whose `bounds` hold the place, at most {@link MAX_IDENTIFY_LAYERS} in
|
|
656
|
+
* catalogue order. The requests start together, each with
|
|
657
|
+
* {@link IDENTIFY_TIMEOUT_MS} to answer. It waits for all of them, changes
|
|
658
|
+
* the state once and says one message: how many were found, which layers
|
|
659
|
+
* did not answer, and how many it asked when the cap held some back. A
|
|
660
|
+
* layer that did not answer leaves what it showed before as it was.
|
|
661
|
+
*
|
|
662
|
+
* Resolves with how many layers were asked and how many features they
|
|
663
|
+
* found, or with null when this tap was replaced or cancelled before it
|
|
664
|
+
* settled, which opens and says nothing. When no layer can be asked it
|
|
665
|
+
* resolves at once with `asked` of zero, changes nothing and says nothing,
|
|
666
|
+
* so the caller can fall back to its own message. Starting a tap cancels the
|
|
667
|
+
* one in flight.
|
|
668
|
+
*/
|
|
669
|
+
identifyAt(target: IdentifyTarget, options?: {
|
|
670
|
+
readonly focus?: boolean;
|
|
671
|
+
}): Promise<IdentifyResult | null>;
|
|
672
|
+
/**
|
|
673
|
+
* Cancels the tap in flight, if there is one: its requests are aborted and it
|
|
674
|
+
* opens and says nothing. Returns whether there was one. The host calls it
|
|
675
|
+
* when the person leaves the plain map (another surface opens, taps stop
|
|
676
|
+
* meaning "look here", a long press), and Escape calls it before it closes
|
|
677
|
+
* anything. A layer turned off, whose tiles change, or an unmount cancels
|
|
678
|
+
* what concerns it without a call, and so does opening a card or a list
|
|
679
|
+
* with {@link DataLayers.select} or {@link DataLayers.choose}.
|
|
680
|
+
*/
|
|
681
|
+
cancelIdentify(): boolean;
|
|
682
|
+
/**
|
|
683
|
+
* True from the start of {@link DataLayers.identifyAt} until it settles or is
|
|
684
|
+
* cancelled. It is the status data for a "looking up" line, which waits a
|
|
685
|
+
* moment before it shows so a quick answer never flickers.
|
|
686
|
+
*/
|
|
687
|
+
readonly identifying: boolean;
|
|
688
|
+
/** Closes the open card and returns to the list of features found together. */
|
|
689
|
+
backToChoices(options?: {
|
|
690
|
+
readonly focus?: boolean;
|
|
691
|
+
}): void;
|
|
692
|
+
/**
|
|
693
|
+
* Tells layers what the map shows, once it has settled: the visible box and
|
|
694
|
+
* the normalised zoom. A query layer asks for the features in a window
|
|
695
|
+
* around it. A layer with a zoom window in its definition (a query layer's
|
|
696
|
+
* `minzoom`, a vector tile layer's `minzoom` and `maxzoom`) says which
|
|
697
|
+
* level to zoom to when the zoom is outside it.
|
|
698
|
+
*/
|
|
699
|
+
setView(area: Bounds, zoom: number): void;
|
|
700
|
+
showDetail(layerId: string, featureId: string): void;
|
|
701
|
+
hideDetail(): void;
|
|
702
|
+
}
|
|
703
|
+
|
|
704
|
+
/** One layer as the ui shows it. */
|
|
705
|
+
export declare interface DataLayerState {
|
|
706
|
+
readonly definition: LayerDefinition;
|
|
707
|
+
readonly enabled: boolean;
|
|
708
|
+
/** Every control's value, resolved against the definition. */
|
|
709
|
+
readonly controls: ControlValues;
|
|
710
|
+
readonly status: LayerStatus;
|
|
711
|
+
/** The loaded features, in the order the provider sent them. */
|
|
712
|
+
readonly features: readonly LayerFeature[];
|
|
713
|
+
/** The id of the list's sort option. */
|
|
714
|
+
readonly sortId: string;
|
|
715
|
+
/** The features in list order. */
|
|
716
|
+
readonly sorted: readonly LayerFeature[];
|
|
717
|
+
}
|
|
718
|
+
|
|
719
|
+
/** A feature's affected area, loaded on request. */
|
|
720
|
+
export declare interface DetailState {
|
|
721
|
+
readonly layerId: string;
|
|
722
|
+
readonly featureId: string;
|
|
723
|
+
readonly status: "loading" | "shown" | "error";
|
|
724
|
+
readonly shapes: readonly LayerFeature[];
|
|
725
|
+
}
|
|
726
|
+
|
|
727
|
+
/** The failures a person is told about. A cancelled request is never one of them. */
|
|
728
|
+
export declare type DirectionsFailure = Exclude<RoutingErrorKind, "aborted">;
|
|
729
|
+
|
|
730
|
+
/** What the directions tool has put on the map. */
|
|
731
|
+
export declare type DirectionsOutcome = RouteOutcome | AreaOutcome;
|
|
732
|
+
|
|
733
|
+
/**
|
|
734
|
+
* The stops of a set of directions, drawn as lettered discs, and the crosshair
|
|
735
|
+
* that shows where the next stop goes when it is added at the map centre.
|
|
736
|
+
* Render it inside `MapOverlayLayer`. Like every overlay it is a picture of
|
|
737
|
+
* state the panel gives in words, and the letters mean it never depends on
|
|
738
|
+
* colour.
|
|
739
|
+
*/
|
|
740
|
+
export declare function DirectionsOverlay({ stops, showCrosshair, testId, }: DirectionsOverlayProps): JSX.Element | null;
|
|
741
|
+
|
|
742
|
+
/** Props for {@link DirectionsOverlay}. */
|
|
743
|
+
export declare interface DirectionsOverlayProps {
|
|
744
|
+
/** The stops, in order. Each is drawn as a lettered disc. */
|
|
745
|
+
readonly stops: readonly DirectionStop[];
|
|
746
|
+
/**
|
|
747
|
+
* Draws a crosshair where "Add stop at map centre" will put a stop, which
|
|
748
|
+
* is the middle of the part of the map the panel leaves free.
|
|
749
|
+
*/
|
|
750
|
+
readonly showCrosshair: boolean;
|
|
751
|
+
readonly testId?: string;
|
|
752
|
+
}
|
|
753
|
+
|
|
754
|
+
/**
|
|
755
|
+
* The directions tool's panel, for the sheet or side panel: the stops (added
|
|
756
|
+
* by tapping the map, at the map centre, from a place search or from the
|
|
757
|
+
* dropped pin, and reordered or removed with buttons), the way of travelling,
|
|
758
|
+
* "Get route", the travel time areas and the result.
|
|
759
|
+
*
|
|
760
|
+
* @remarks Every action a pointer can do has a button: adding a stop at the
|
|
761
|
+
* map centre stands in for a tap on the map, and Move up, Move down and
|
|
762
|
+
* Remove stand in for any drag. "Add stop at map centre" uses the middle of
|
|
763
|
+
* the part of the map the panel leaves free, which is where the crosshair is
|
|
764
|
+
* drawn. Results and failures are announced by `useDirections`, so the
|
|
765
|
+
* panel's own text carries no live region. A request is sent only when a
|
|
766
|
+
* button asks for it, and the note under them says what goes where.
|
|
767
|
+
*/
|
|
768
|
+
export declare function DirectionsPanel({ directions, pin, getBias, note, headingLevel, }: DirectionsPanelProps): JSX.Element;
|
|
769
|
+
|
|
770
|
+
/** Props for {@link DirectionsPanel}. */
|
|
771
|
+
export declare interface DirectionsPanelProps {
|
|
772
|
+
/** The directions state and actions, from `useDirections`. */
|
|
773
|
+
readonly directions: UseDirections;
|
|
774
|
+
/** The dropped pin, offered as a stop, or null when there is none. */
|
|
775
|
+
readonly pin: LatLng | null;
|
|
776
|
+
/**
|
|
777
|
+
* Returns the box to favour in the place search, usually the visible map.
|
|
778
|
+
* Optional, and passed to {@link useSearch}, whose note on what a bias
|
|
779
|
+
* sends applies.
|
|
780
|
+
*/
|
|
781
|
+
readonly getBias?: () => Bounds | undefined;
|
|
782
|
+
/**
|
|
783
|
+
* What a request sends and to whom, shown under the buttons. Defaults to
|
|
784
|
+
* the catalogue's `tools.directions.note`, which does not name the service.
|
|
785
|
+
* A host names its routing service here.
|
|
786
|
+
*/
|
|
787
|
+
readonly note?: ReactNode;
|
|
788
|
+
/** The level of the group headings, one below the sheet's title. Defaults to 3. */
|
|
789
|
+
readonly headingLevel?: 3 | 4;
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
/** Where the directions tool stands. Exactly one of these is true at a time. */
|
|
793
|
+
export declare type DirectionsState = {
|
|
794
|
+
readonly status: "idle";
|
|
795
|
+
} | {
|
|
796
|
+
readonly status: "loading";
|
|
797
|
+
readonly request: RoutingRequestKind;
|
|
798
|
+
/** The travel time of an area request, so its button can show it is working. */
|
|
799
|
+
readonly minutes?: number;
|
|
800
|
+
} | {
|
|
801
|
+
readonly status: "done";
|
|
802
|
+
readonly result: DirectionsOutcome;
|
|
803
|
+
} | {
|
|
804
|
+
readonly status: "error";
|
|
805
|
+
readonly request: RoutingRequestKind;
|
|
806
|
+
readonly kind: DirectionsFailure;
|
|
807
|
+
};
|
|
808
|
+
|
|
809
|
+
/**
|
|
810
|
+
* How long a moved vertex must stay still before the new measure is announced, in milliseconds.
|
|
811
|
+
*
|
|
812
|
+
* @internal
|
|
813
|
+
*/
|
|
814
|
+
export declare const DRAW_ANNOUNCE_DELAY_MS = 800;
|
|
815
|
+
|
|
816
|
+
/** The outcome of an export or a copy, shown beside the buttons and announced. */
|
|
817
|
+
export declare interface DrawFeedback {
|
|
818
|
+
readonly kind: "success" | "error";
|
|
819
|
+
readonly text: string;
|
|
820
|
+
/**
|
|
821
|
+
* Set on an import that read nothing because the file fits only this
|
|
822
|
+
* other WKT axis order: the order that {@link UseDraw.rereadImport} reads
|
|
823
|
+
* the same file in.
|
|
824
|
+
*/
|
|
825
|
+
readonly readAs?: WktAxisOrder;
|
|
826
|
+
}
|
|
827
|
+
|
|
828
|
+
/**
|
|
829
|
+
* The shapes as a drawing for a saved map image, in the overlay's colours for
|
|
830
|
+
* the light theme (the basemap never follows the theme, so the image does not
|
|
831
|
+
* either). Undefined when there is nothing to draw, so the image is the map
|
|
832
|
+
* alone.
|
|
833
|
+
*
|
|
834
|
+
* @internal
|
|
835
|
+
*/
|
|
836
|
+
export declare function drawingForImage(shapes: readonly DrawShape[]): MapImageDrawing | undefined;
|
|
837
|
+
|
|
838
|
+
/**
|
|
839
|
+
* Connects the draw tool to the live map without drawing anything: it gives
|
|
840
|
+
* the adapter the handles of the selected shape, and passes the adapter's
|
|
841
|
+
* handle presses and hovers to the tool. Render it inside `MapView`.
|
|
842
|
+
*
|
|
843
|
+
* @remarks The handles are cleared when the tool closes or the map goes, so a
|
|
844
|
+
* press on the bare map never starts a drag that nothing draws.
|
|
845
|
+
*/
|
|
846
|
+
export declare function DrawMapBindings({ draw }: DrawMapBindingsProps): null;
|
|
847
|
+
|
|
848
|
+
/** Props for {@link DrawMapBindings}. */
|
|
849
|
+
export declare interface DrawMapBindingsProps {
|
|
850
|
+
/** The drawing state from `useDraw`. */
|
|
851
|
+
readonly draw: UseDraw;
|
|
852
|
+
}
|
|
853
|
+
|
|
854
|
+
/**
|
|
855
|
+
* The draw tool's drawing: every shape with its fill and outline, the
|
|
856
|
+
* unfinished one dashed, the selected one drawn heavier, a dashed preview of
|
|
857
|
+
* the next edge, and the handles of the selected shape. Render it inside
|
|
858
|
+
* `MapOverlayLayer`.
|
|
859
|
+
*
|
|
860
|
+
* @remarks Edges go the short way across the antimeridian. On a globe each
|
|
861
|
+
* edge follows its great circle and stops at the horizon: a point or
|
|
862
|
+
* handle beyond it is left out, and a closed shape's fill is drawn only
|
|
863
|
+
* while all of its outline is in sight.
|
|
864
|
+
* Selection is shown by weight, handles and a filled vertex as well
|
|
865
|
+
* as colour. The layer never takes the pointer: the adapter owns the press
|
|
866
|
+
* on a handle, and this only draws where the handles are.
|
|
867
|
+
*/
|
|
868
|
+
export declare function DrawOverlay({ shapes, selection, handles, hoveredHandle, hover, testId, }: DrawOverlayProps): JSX.Element | null;
|
|
869
|
+
|
|
870
|
+
/** Props for {@link DrawOverlay}. */
|
|
871
|
+
export declare interface DrawOverlayProps {
|
|
872
|
+
/** Every shape, finished or being drawn. */
|
|
873
|
+
readonly shapes: readonly DrawShape[];
|
|
874
|
+
/** The selected shape and vertex. */
|
|
875
|
+
readonly selection: DrawSelection | null;
|
|
876
|
+
/**
|
|
877
|
+
* The handles to draw, normally those of the selected shape. Leave empty
|
|
878
|
+
* while the tool is closed, so finished shapes show with no handles.
|
|
879
|
+
*/
|
|
880
|
+
readonly handles?: readonly MapEditHandle[];
|
|
881
|
+
/** The handle a mouse is over, drawn larger. */
|
|
882
|
+
readonly hoveredHandle?: string | null;
|
|
883
|
+
/** The position under the pointer, for the dashed preview of the next edge. */
|
|
884
|
+
readonly hover?: LatLng;
|
|
885
|
+
readonly testId?: string;
|
|
886
|
+
}
|
|
887
|
+
|
|
888
|
+
/**
|
|
889
|
+
* The draw toolbar: a switch for what to draw, the name and measures of the
|
|
890
|
+
* shape under way or selected, buttons to add a point at the map centre, undo,
|
|
891
|
+
* redo, cancel or delete, open the list of shapes and finish, and a group of
|
|
892
|
+
* controls for the selected shape. It sits in a landmark named "Drawing", so
|
|
893
|
+
* it is inside a landmark wherever the host places it.
|
|
894
|
+
*
|
|
895
|
+
* On mount focus moves to the chosen shape type, because the person has just
|
|
896
|
+
* chosen Draw and the next thing to do is here. The bottom-centre slot it sits
|
|
897
|
+
* in is what the slots below it ride above. The toolbar registers its Shapes
|
|
898
|
+
* button as a focus target, so closing the sheet over a drawing puts focus
|
|
899
|
+
* back on it.
|
|
900
|
+
* @remarks Every pointer action has a button: Add point at map centre places a
|
|
901
|
+
* point (or moves the selected one), Previous and Next point select, the
|
|
902
|
+
* group moves, adds and removes points, and the circle group sets the
|
|
903
|
+
* radius. The arrow keys move the selected point from the map, or while
|
|
904
|
+
* focus is in the selected shape's group, and Escape and the undo keys work
|
|
905
|
+
* from anywhere in the toolbar. The primary button is Finish while a shape
|
|
906
|
+
* is being drawn and Done otherwise, in one element, so focus stays put when
|
|
907
|
+
* it changes. Cancel and Delete are one button for the same reason. The
|
|
908
|
+
* button keeps the width of the longer label and its check mark in both
|
|
909
|
+
* states, so the row does not wrap, and the toolbar does not change height,
|
|
910
|
+
* when the label changes.
|
|
911
|
+
*/
|
|
912
|
+
export declare function DrawToolbar({ draw, onDone, onOpenShapes }: DrawToolbarProps): JSX.Element;
|
|
913
|
+
|
|
914
|
+
/** Props for {@link DrawToolbar}. */
|
|
915
|
+
export declare interface DrawToolbarProps {
|
|
916
|
+
/** The drawing state from `useDraw`. */
|
|
917
|
+
readonly draw: UseDraw;
|
|
918
|
+
/** Called by "Done". */
|
|
919
|
+
readonly onDone: () => void;
|
|
920
|
+
/** Called by "Shapes and export", which opens the list of shapes in the sheet. */
|
|
921
|
+
readonly onOpenShapes: () => void;
|
|
922
|
+
}
|
|
923
|
+
|
|
924
|
+
/**
|
|
925
|
+
* What a list or panel shows when it has nothing to show: an icon, a real
|
|
926
|
+
* heading, an explanation and an optional action. The heading is never empty,
|
|
927
|
+
* because a blank heading is announced as a heading with no name.
|
|
928
|
+
*/
|
|
929
|
+
export declare function EmptyState({ icon, heading: headingText, headingLevel, children, action: actionNode, className, ...rest }: EmptyStateProps): JSX.Element;
|
|
930
|
+
|
|
931
|
+
/** Props for {@link EmptyState}. */
|
|
932
|
+
export declare interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
|
|
933
|
+
/** A decorative icon above the heading, imported by name from `lucide-react`. */
|
|
934
|
+
readonly icon?: IconComponent;
|
|
935
|
+
/** The heading text. A blank heading renders no heading element at all. */
|
|
936
|
+
readonly heading: string;
|
|
937
|
+
/** The heading level, 2 to 6. Pick the level that fits the page outline. */
|
|
938
|
+
readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
|
|
939
|
+
/** The explanation, rendered as one paragraph. */
|
|
940
|
+
readonly children?: ReactNode;
|
|
941
|
+
/** An optional next step, usually a `Button`. */
|
|
942
|
+
readonly action?: ReactNode;
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
/**
|
|
946
|
+
* The end-stack slot content, a landmark named "Map tools" holding, top to
|
|
947
|
+
* bottom: the compass (only while the map is rotated and the engine can
|
|
948
|
+
* rotate), the "Map controls" group (Map options, Measure, Directions and Draw
|
|
949
|
+
* shapes when the host offers them, Locate me, Settings) and the "Zoom
|
|
950
|
+
* controls" group. The zoom group is never placed anywhere else.
|
|
951
|
+
*
|
|
952
|
+
* @remarks The zoom group follows `shouldShowZoomButtons`: the user's
|
|
953
|
+
* setting wins; otherwise it shows for a fine pointer unless the height
|
|
954
|
+
* `MapChrome` measured for the stack is too short. At a zoom limit the
|
|
955
|
+
* button is `aria-disabled` but stays focusable. Map options, Measure,
|
|
956
|
+
* Directions, Draw shapes and Settings register as focus targets, so
|
|
957
|
+
* closing their surfaces returns focus to them. The stack does not read the
|
|
958
|
+
* map; the app passes its state in.
|
|
959
|
+
*/
|
|
960
|
+
export declare function EndStack({ bearing, onResetBearing, mapOptionsOpen, mapOptionsControls, onMapOptions, settingsOpen, settingsControls, onSettings, measuring, onMeasure, directions, drawing, onDraw, locating, onLocate, canZoomIn, canZoomOut, onZoomIn, onZoomOut, }: EndStackProps): JSX.Element;
|
|
961
|
+
|
|
962
|
+
/** The Directions button, shown only when the host offers directions. */
|
|
963
|
+
export declare interface EndStackDirections {
|
|
964
|
+
/** The directions panel is open. */
|
|
965
|
+
readonly active: boolean;
|
|
966
|
+
/** The id of the sheet or panel that Directions opens. */
|
|
967
|
+
readonly controls: string;
|
|
968
|
+
readonly onToggle: () => void;
|
|
969
|
+
}
|
|
970
|
+
|
|
971
|
+
/**
|
|
972
|
+
* The height the end stack needs to show the zoom group under the main
|
|
973
|
+
* group: four main controls (Map options, Measure, Locate me and Settings),
|
|
974
|
+
* two zoom controls, the gap between the groups and eight hairlines (the
|
|
975
|
+
* dividers between neighbours and the groups' borders), plus the compass and
|
|
976
|
+
* its gap while it shows, and one more control and hairline while the
|
|
977
|
+
* Directions or Draw shapes button shows. Below this, and only when the user
|
|
978
|
+
* has not chosen to show zoom buttons, the zoom group yields.
|
|
979
|
+
*
|
|
980
|
+
* @remarks The stack's own padding is not counted. It lives in its own file,
|
|
981
|
+
* with no styles, so that the browser tests can read it too.
|
|
982
|
+
*/
|
|
983
|
+
export declare function endStackMinHeightForZoom(compassShown: boolean, directionsShown?: boolean, drawShown?: boolean): number;
|
|
984
|
+
|
|
985
|
+
/** Props for {@link EndStack}. The app passes map state from `useMap()`. */
|
|
986
|
+
export declare interface EndStackProps {
|
|
987
|
+
/** Map bearing in degrees clockwise from north. */
|
|
988
|
+
readonly bearing: number;
|
|
989
|
+
readonly onResetBearing: () => void;
|
|
990
|
+
/**
|
|
991
|
+
* The sheet or panel that Map options opens is the open surface. False
|
|
992
|
+
* while Settings is open, and while a pin card or Directions is shown in the
|
|
993
|
+
* sheet.
|
|
994
|
+
*/
|
|
995
|
+
readonly mapOptionsOpen: boolean;
|
|
996
|
+
/** The id of the sheet or panel that Map options opens. */
|
|
997
|
+
readonly mapOptionsControls: string;
|
|
998
|
+
readonly onMapOptions: () => void;
|
|
999
|
+
/** The settings sheet or panel (Settings and Help) is open. */
|
|
1000
|
+
readonly settingsOpen: boolean;
|
|
1001
|
+
/** The id of the sheet or panel that Settings opens. */
|
|
1002
|
+
readonly settingsControls: string;
|
|
1003
|
+
readonly onSettings: () => void;
|
|
1004
|
+
/** Measuring is on. */
|
|
1005
|
+
readonly measuring: boolean;
|
|
1006
|
+
readonly onMeasure: () => void;
|
|
1007
|
+
/**
|
|
1008
|
+
* The Directions button, between Measure and Locate me. Leave it out and
|
|
1009
|
+
* the button is not shown, for a host with no routing service.
|
|
1010
|
+
*/
|
|
1011
|
+
readonly directions?: EndStackDirections;
|
|
1012
|
+
/**
|
|
1013
|
+
* Draw is on. With `onDraw`, the stack shows a Draw shapes button between
|
|
1014
|
+
* Measure and Locate me; without it the button is left out.
|
|
1015
|
+
*/
|
|
1016
|
+
readonly drawing?: boolean;
|
|
1017
|
+
readonly onDraw?: () => void;
|
|
1018
|
+
/** A location request is in progress. Presses are ignored meanwhile. */
|
|
1019
|
+
readonly locating: boolean;
|
|
1020
|
+
readonly onLocate: () => void;
|
|
1021
|
+
readonly canZoomIn: boolean;
|
|
1022
|
+
readonly canZoomOut: boolean;
|
|
1023
|
+
readonly onZoomIn: () => void;
|
|
1024
|
+
readonly onZoomOut: () => void;
|
|
1025
|
+
}
|
|
1026
|
+
|
|
1027
|
+
/**
|
|
1028
|
+
* The end stack as a decorative stand-in for the server-rendered
|
|
1029
|
+
* `ChromeSkeleton`: the same column, groups and buttons as {@link EndStack},
|
|
1030
|
+
* with the Map options, Measure, Locate me and Settings group (and Directions
|
|
1031
|
+
* and Draw shapes when the host sets them) and, on a device with a fine
|
|
1032
|
+
* pointer, the zoom group. No compass, because the map starts facing north.
|
|
1033
|
+
*
|
|
1034
|
+
* @remarks Only ever rendered inside an `aria-hidden`, `inert` container. It
|
|
1035
|
+
* uses no hooks and needs no provider: the names arrive as `copy`.
|
|
1036
|
+
*/
|
|
1037
|
+
export declare function EndStackSkeleton({ copy, directions, draw, }: EndStackSkeletonProps): JSX.Element;
|
|
1038
|
+
|
|
1039
|
+
/** The names of the controls {@link EndStackSkeleton} draws, in the host's default language. */
|
|
1040
|
+
export declare interface EndStackSkeletonCopy {
|
|
1041
|
+
readonly controls: string;
|
|
1042
|
+
readonly mapOptions: string;
|
|
1043
|
+
readonly measure: string;
|
|
1044
|
+
readonly directions: string;
|
|
1045
|
+
readonly draw: string;
|
|
1046
|
+
readonly locate: string;
|
|
1047
|
+
readonly settings: string;
|
|
1048
|
+
readonly zoomControls: string;
|
|
1049
|
+
readonly zoomIn: string;
|
|
1050
|
+
readonly zoomOut: string;
|
|
1051
|
+
}
|
|
1052
|
+
|
|
1053
|
+
/** Props for {@link EndStackSkeleton}. */
|
|
1054
|
+
export declare interface EndStackSkeletonProps {
|
|
1055
|
+
readonly copy: EndStackSkeletonCopy;
|
|
1056
|
+
/** Shows the Directions button, as the live stack does when the host offers directions. */
|
|
1057
|
+
readonly directions?: boolean;
|
|
1058
|
+
/** Show the Draw shapes button, as the live stack does when its host offers drawing. */
|
|
1059
|
+
readonly draw?: boolean;
|
|
1060
|
+
}
|
|
1061
|
+
|
|
1062
|
+
/**
|
|
1063
|
+
* Saves the map as it looks now, with its layers and credits, as a PNG file.
|
|
1064
|
+
* The image is drawn in the browser from what the map has already loaded, so
|
|
1065
|
+
* nothing is requested or sent anywhere. A plain button, so it works from the
|
|
1066
|
+
* keyboard; the result is announced through the shared live region.
|
|
1067
|
+
*
|
|
1068
|
+
* @remarks Every failure is logged and announced assertively.
|
|
1069
|
+
*/
|
|
1070
|
+
export declare function ExportSection({ credits, drawing, headingLevel, headingRef, }: ExportSectionProps): JSX.Element;
|
|
1071
|
+
|
|
1072
|
+
/** Props for {@link ExportSection}. */
|
|
1073
|
+
export declare interface ExportSectionProps {
|
|
1074
|
+
/**
|
|
1075
|
+
* The credits drawn along the bottom of the saved image, such as the
|
|
1076
|
+
* basemap's and those of the layers that are on (see `creditsLine`).
|
|
1077
|
+
*/
|
|
1078
|
+
readonly credits?: string;
|
|
1079
|
+
/** Shapes drawn over the map, put into the image because the engine does not hold them. */
|
|
1080
|
+
readonly drawing?: MapImageDrawing;
|
|
1081
|
+
/** The heading level. Defaults to 3, below the sheet's h2 title. */
|
|
1082
|
+
readonly headingLevel?: HeadingLevel;
|
|
1083
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
1084
|
+
}
|
|
1085
|
+
|
|
1086
|
+
/**
|
|
1087
|
+
* The box around a feature's geometry, or null when it has no coordinates.
|
|
1088
|
+
*
|
|
1089
|
+
* @internal
|
|
1090
|
+
*/
|
|
1091
|
+
export declare function featureBounds(feature: LayerFeature): Bounds | null;
|
|
1092
|
+
|
|
1093
|
+
/**
|
|
1094
|
+
* The card for one feature, drawn from its definition's card template (a
|
|
1095
|
+
* feed's own, or the `identify` card of a tile layer): the title, for a feed
|
|
1096
|
+
* layer the words for its colour (with the same glyph as the map), its lines,
|
|
1097
|
+
* a link to the provider, the layer's disclaimer, "Show on map" and, for
|
|
1098
|
+
* layers with a detail source, "Show affected area" with what it costs. A
|
|
1099
|
+
* feature found by a tap has no style, so its card has no glyph or class
|
|
1100
|
+
* line. Renders nothing for a layer whose features have no card.
|
|
1101
|
+
*/
|
|
1102
|
+
export declare function FeatureCard({ layers, selected, formatters, headingLevel, headingRef, onShowOnMap, }: FeatureCardProps): JSX.Element | null;
|
|
1103
|
+
|
|
1104
|
+
/** Props for {@link FeatureCard}. */
|
|
1105
|
+
export declare interface FeatureCardProps {
|
|
1106
|
+
readonly layers: DataLayers;
|
|
1107
|
+
readonly selected: SelectedFeature;
|
|
1108
|
+
readonly formatters: FormatterRegistry;
|
|
1109
|
+
readonly headingLevel: 3 | 4 | 5 | 6;
|
|
1110
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
1111
|
+
/** Centres the map on the feature. */
|
|
1112
|
+
readonly onShowOnMap: () => void;
|
|
1113
|
+
}
|
|
1114
|
+
|
|
1115
|
+
/** One ring or line of a feature, ready to draw as a path. */
|
|
1116
|
+
export declare interface FeatureOutline {
|
|
1117
|
+
readonly points: readonly LatLng[];
|
|
1118
|
+
/** True for a polygon ring, whose path closes. */
|
|
1119
|
+
readonly closed: boolean;
|
|
1120
|
+
}
|
|
1121
|
+
|
|
1122
|
+
/**
|
|
1123
|
+
* The rings and lines of a polygon or line feature, thinned so an outline
|
|
1124
|
+
* drawn from them over the map stays cheap to redraw while the map moves. A
|
|
1125
|
+
* point has none.
|
|
1126
|
+
*
|
|
1127
|
+
* @internal
|
|
1128
|
+
*/
|
|
1129
|
+
export declare function featureOutlines(feature: LayerFeature): FeatureOutline[];
|
|
1130
|
+
|
|
1131
|
+
/**
|
|
1132
|
+
* Where a feature is: a point's own position, and for a polygon or line the
|
|
1133
|
+
* centre of its box. Null when the geometry has no coordinates.
|
|
1134
|
+
*
|
|
1135
|
+
* @internal
|
|
1136
|
+
*/
|
|
1137
|
+
export declare function featurePosition(feature: LayerFeature): LatLng | null;
|
|
1138
|
+
|
|
1139
|
+
/** What {@link useFeatureSelection} returns: the selected set as the ui shows it, and every action on it. */
|
|
1140
|
+
export declare interface FeatureSelectionState {
|
|
1141
|
+
/** The selected references in selection order, each resolved against the layers (see {@link SelectedEntry}). */
|
|
1142
|
+
readonly entries: readonly SelectedEntry[];
|
|
1143
|
+
/** The most references the store holds. */
|
|
1144
|
+
readonly limit: number;
|
|
1145
|
+
/** Whether select mode is on. It is only a flag: nothing here reads it. */
|
|
1146
|
+
readonly selecting: boolean;
|
|
1147
|
+
/** Turns select mode on or off. */
|
|
1148
|
+
setSelecting(selecting: boolean): void;
|
|
1149
|
+
/** Selects the feature, or deselects it when it is selected. */
|
|
1150
|
+
toggle(ref: FeatureRef): void;
|
|
1151
|
+
/**
|
|
1152
|
+
* Selects the references that are not yet selected and belong to a feed
|
|
1153
|
+
* layer. The store refuses the whole batch when it would pass its limit.
|
|
1154
|
+
*/
|
|
1155
|
+
add(refs: readonly FeatureRef[]): void;
|
|
1156
|
+
/** Deselects the references that are selected. Always allowed. */
|
|
1157
|
+
remove(refs: readonly FeatureRef[]): void;
|
|
1158
|
+
/** Empties the selection. */
|
|
1159
|
+
clear(): void;
|
|
1160
|
+
}
|
|
1161
|
+
|
|
1162
|
+
/**
|
|
1163
|
+
* Splits `text` around its `{name}` slots and puts `slots[name]` in each, so
|
|
1164
|
+
* a value in a sentence can be an element of its own, such as an `Isolate`.
|
|
1165
|
+
* Get `text` from the catalogue by passing each slot's own placeholder as its
|
|
1166
|
+
* parameter, for example `t("tools.directions.leg", { distance: "{distance}" })`.
|
|
1167
|
+
* A name with no entry in `slots` is left as written.
|
|
1168
|
+
*
|
|
1169
|
+
* @internal
|
|
1170
|
+
*/
|
|
1171
|
+
export declare function fillSlots(text: string, slots: Readonly<Record<string, ReactNode>>): ReactNode;
|
|
1172
|
+
|
|
1173
|
+
/** The controls focus can return to when a surface closes. */
|
|
1174
|
+
export declare type FocusName = FocusTarget;
|
|
1175
|
+
|
|
1176
|
+
/**
|
|
1177
|
+
* Remembers the elements that open surfaces, so closing a surface can put
|
|
1178
|
+
* focus back on the control that opened it, or on the map when that control is
|
|
1179
|
+
* gone. Safari does not focus buttons on click, so focus is always moved with
|
|
1180
|
+
* an explicit `focus()` call.
|
|
1181
|
+
*/
|
|
1182
|
+
export declare function FocusRegistryProvider({ focusMap, children, }: FocusRegistryProviderProps): JSX.Element;
|
|
1183
|
+
|
|
1184
|
+
/** Props for {@link FocusRegistryProvider}. */
|
|
1185
|
+
export declare interface FocusRegistryProviderProps {
|
|
1186
|
+
/** Focuses the map region. Used when the control that opened a surface no longer exists. */
|
|
1187
|
+
readonly focusMap: () => void;
|
|
1188
|
+
readonly children: ReactNode;
|
|
1189
|
+
}
|
|
1190
|
+
|
|
1191
|
+
/** What {@link useFreeCentre} returns. */
|
|
1192
|
+
export declare interface FreeCentre {
|
|
1193
|
+
/**
|
|
1194
|
+
* The middle of the part of the map the sheet or side panel leaves free, in
|
|
1195
|
+
* pixels, or the middle of the whole map before the chrome has measured.
|
|
1196
|
+
* Null before the map has mounted.
|
|
1197
|
+
*/
|
|
1198
|
+
readonly pixel: PixelPoint | null;
|
|
1199
|
+
/** The place under {@link FreeCentre.pixel}, read when asked, or null before the map has mounted. */
|
|
1200
|
+
readonly position: () => LatLng | null;
|
|
1201
|
+
}
|
|
1202
|
+
|
|
1203
|
+
/** A heading level. The sheet title is an h2, so its sections start at 3. */
|
|
1204
|
+
export declare type HeadingLevel = 2 | 3 | 4 | 5 | 6;
|
|
1205
|
+
|
|
1206
|
+
/**
|
|
1207
|
+
* A host's About block in Help: a heading, a line of text, one link out and,
|
|
1208
|
+
* optionally, a link to the host's own page about the site. The link out is
|
|
1209
|
+
* drawn only when its address is an absolute http or https one, and the
|
|
1210
|
+
* own-page link only when it is that or a path on the site; otherwise Help
|
|
1211
|
+
* shows the block without it.
|
|
1212
|
+
*/
|
|
1213
|
+
export declare interface HelpAbout {
|
|
1214
|
+
/** The block's heading, in the host's words. */
|
|
1215
|
+
readonly heading: string;
|
|
1216
|
+
/** What the host wants to say about the site, as plain text. */
|
|
1217
|
+
readonly text: string;
|
|
1218
|
+
/** A link out, opened in a new tab and announced as doing so. */
|
|
1219
|
+
readonly link: HelpAboutLink;
|
|
1220
|
+
/**
|
|
1221
|
+
* A link to the host's own page about the site (a product or home page),
|
|
1222
|
+
* shown before the link out and opened in the same tab, like the privacy
|
|
1223
|
+
* policy link in Settings.
|
|
1224
|
+
*/
|
|
1225
|
+
readonly homeLink?: HelpAboutLink;
|
|
1226
|
+
}
|
|
1227
|
+
|
|
1228
|
+
/** A link in the About block: where it goes and what it is called. */
|
|
1229
|
+
export declare interface HelpAboutLink {
|
|
1230
|
+
/** The host must supply a trusted address, as with its other links. */
|
|
1231
|
+
readonly href: string;
|
|
1232
|
+
/** A name that says where the link goes, not "click here". */
|
|
1233
|
+
readonly label: string;
|
|
1234
|
+
}
|
|
1235
|
+
|
|
1236
|
+
/**
|
|
1237
|
+
* Help: what the search box accepts, the keyboard shortcuts, a statement
|
|
1238
|
+
* of the accessibility target and, when the host supplies one, its About block.
|
|
1239
|
+
* @remarks The Keyboard group is shown only when the primary pointer is fine
|
|
1240
|
+
* (a mouse or trackpad), the signal this app uses for "has a keyboard". On a
|
|
1241
|
+
* touch device it is left out entirely rather than replaced by a hint. A
|
|
1242
|
+
* keyboard attached to a touch device is not detected, so the same shortcuts
|
|
1243
|
+
* stay in the map's own hidden keyboard instructions.
|
|
1244
|
+
*/
|
|
1245
|
+
export declare function HelpSection({ headingLevel, headingRef, onStartTour, about, }: HelpSectionProps): JSX.Element;
|
|
1246
|
+
|
|
1247
|
+
/** Props for {@link HelpSection}. */
|
|
1248
|
+
export declare interface HelpSectionProps {
|
|
1249
|
+
/** The heading level. Defaults to 3, below the sheet's h2 title. */
|
|
1250
|
+
readonly headingLevel?: HeadingLevel;
|
|
1251
|
+
/** Receives the heading, so the sheet can focus it. */
|
|
1252
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
1253
|
+
/** Starts the first-visit tour. Without it Help offers no tour. */
|
|
1254
|
+
readonly onStartTour?: () => void;
|
|
1255
|
+
/**
|
|
1256
|
+
* The host's About block, shown below the other subsections. Without it Help
|
|
1257
|
+
* has none. Its link address must be a trusted http or https one that the
|
|
1258
|
+
* host supplies; any other address leaves the link out.
|
|
1259
|
+
*/
|
|
1260
|
+
readonly about?: HelpAbout;
|
|
1261
|
+
}
|
|
1262
|
+
|
|
1263
|
+
/**
|
|
1264
|
+
* A selected reference with nothing to show: its layer is off, still loading,
|
|
1265
|
+
* not in the catalogue or not selectable. It stays selected and counts.
|
|
1266
|
+
*/
|
|
1267
|
+
export declare interface HiddenSelection {
|
|
1268
|
+
readonly status: "not-shown";
|
|
1269
|
+
readonly ref: FeatureRef;
|
|
1270
|
+
}
|
|
1271
|
+
|
|
1272
|
+
/**
|
|
1273
|
+
* Draws one icon at the system size and stroke width. Decorative by default
|
|
1274
|
+
* (`aria-hidden`); pass `label` when it carries meaning on its own.
|
|
1275
|
+
*/
|
|
1276
|
+
export declare function Icon({ icon: Glyph, label, spinning: isSpinning, mirrorInRtl, className, ...rest }: IconProps): JSX.Element;
|
|
1277
|
+
|
|
1278
|
+
/**
|
|
1279
|
+
* A button that shows only an icon. It activates on click (pointer up or
|
|
1280
|
+
* keyboard) and never on pointer down, so a press can be cancelled by moving
|
|
1281
|
+
* away before release.
|
|
1282
|
+
*/
|
|
1283
|
+
export declare function IconButton({ label, icon, mirrorInRtl, pressed, busy, disabled, expanded, controls, size, className, onClick, ...rest }: IconButtonProps): JSX.Element;
|
|
1284
|
+
|
|
1285
|
+
/** Props for {@link IconButton}. */
|
|
1286
|
+
export declare interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-busy" | "aria-controls" | "aria-disabled" | "aria-expanded" | "aria-label" | "aria-pressed" | "children" | "disabled" | "type"> {
|
|
1287
|
+
/** The accessible name. Describe the action, for example "Zoom in". */
|
|
1288
|
+
readonly label: string;
|
|
1289
|
+
/** The icon to show, imported by name from `lucide-react`. */
|
|
1290
|
+
readonly icon: IconComponent;
|
|
1291
|
+
/** Flips the icon when the page reads right to left, for one that points along the reading direction. */
|
|
1292
|
+
readonly mirrorInRtl?: boolean;
|
|
1293
|
+
/**
|
|
1294
|
+
* Makes it a toggle. Renders `aria-pressed` and a shape change (tinted fill
|
|
1295
|
+
* plus a bar under the icon). Leave undefined for a plain action button.
|
|
1296
|
+
*/
|
|
1297
|
+
readonly pressed?: boolean;
|
|
1298
|
+
/**
|
|
1299
|
+
* Shows a loader in place of the icon and sets `aria-busy`. Clicks are
|
|
1300
|
+
* ignored while busy. The loader spins only when motion is allowed.
|
|
1301
|
+
*/
|
|
1302
|
+
readonly busy?: boolean;
|
|
1303
|
+
/**
|
|
1304
|
+
* Disables the action with `aria-disabled`. The button stays focusable so
|
|
1305
|
+
* its name is still discoverable, and clicks do nothing.
|
|
1306
|
+
*/
|
|
1307
|
+
readonly disabled?: boolean;
|
|
1308
|
+
/** Sets `aria-expanded` for a button that opens a popover or panel. */
|
|
1309
|
+
readonly expanded?: boolean;
|
|
1310
|
+
/** Sets `aria-controls` to the id of the element it opens or changes. */
|
|
1311
|
+
readonly controls?: string;
|
|
1312
|
+
/** `control` is 48 px square and `compact` is 44 px. Defaults to `control`. */
|
|
1313
|
+
readonly size?: "control" | "compact";
|
|
1314
|
+
}
|
|
1315
|
+
|
|
1316
|
+
/**
|
|
1317
|
+
* The shape of an icon component such as a lucide icon. Callers import the
|
|
1318
|
+
* icon by name from `lucide-react` and pass it in.
|
|
1319
|
+
*/
|
|
1320
|
+
export declare type IconComponent = ComponentType<SVGProps<SVGSVGElement> & {
|
|
1321
|
+
size?: number | string;
|
|
1322
|
+
strokeWidth?: number | string;
|
|
1323
|
+
}>;
|
|
1324
|
+
|
|
1325
|
+
/** Props for {@link Icon}. */
|
|
1326
|
+
export declare interface IconProps extends Omit<SVGProps<SVGSVGElement>, "ref" | "children"> {
|
|
1327
|
+
/** The icon component to draw, for example `Search` from `lucide-react`. */
|
|
1328
|
+
readonly icon: IconComponent;
|
|
1329
|
+
/**
|
|
1330
|
+
* An accessible name. Give one only when the icon is the sole content of
|
|
1331
|
+
* something; the icon then becomes `role="img"`. Without it the icon is
|
|
1332
|
+
* hidden from assistive technology.
|
|
1333
|
+
*/
|
|
1334
|
+
readonly label?: string;
|
|
1335
|
+
/** Rotates the icon continuously. Stops under `prefers-reduced-motion`. */
|
|
1336
|
+
readonly spinning?: boolean;
|
|
1337
|
+
/**
|
|
1338
|
+
* Flips the icon when the page reads right to left. Set it on an icon that
|
|
1339
|
+
* points along the reading direction, such as a back arrow or a next
|
|
1340
|
+
* chevron; leave it off for one that does not.
|
|
1341
|
+
*/
|
|
1342
|
+
readonly mirrorInRtl?: boolean;
|
|
1343
|
+
}
|
|
1344
|
+
|
|
1345
|
+
/**
|
|
1346
|
+
* How long a lookup may run before the interface says it is waiting. An
|
|
1347
|
+
* answer that comes sooner shows nothing, so a quick tap does not flash a
|
|
1348
|
+
* line.
|
|
1349
|
+
*/
|
|
1350
|
+
export declare const IDENTIFY_FEEDBACK_MS = 400;
|
|
1351
|
+
|
|
1352
|
+
/**
|
|
1353
|
+
* How long one layer has to answer a tap, in milliseconds. The hook counts it
|
|
1354
|
+
* itself: a source only sees that its request was aborted.
|
|
1355
|
+
*/
|
|
1356
|
+
export declare const IDENTIFY_TIMEOUT_MS = 8000;
|
|
1357
|
+
|
|
1358
|
+
/** What a tap that asked raster layers came to. */
|
|
1359
|
+
export declare interface IdentifyResult {
|
|
1360
|
+
/** How many layers were asked. Zero when none could be, and then nothing was requested. */
|
|
1361
|
+
readonly asked: number;
|
|
1362
|
+
/** How many features the layers that answered found, in all. */
|
|
1363
|
+
readonly found: number;
|
|
1364
|
+
}
|
|
1365
|
+
|
|
1366
|
+
/**
|
|
1367
|
+
* The line a host shows in the bottom-centre slot while a tap's lookup is
|
|
1368
|
+
* taking time ("Looking up what is here"): show it when
|
|
1369
|
+
* `useIdentifyFeedback(layers.identifying)` is true, and pass
|
|
1370
|
+
* `layers.cancelIdentify` as `onCancel`.
|
|
1371
|
+
*
|
|
1372
|
+
* @remarks It is a `StatusMessage`, so it says itself once, politely, when it
|
|
1373
|
+
* appears at the delay, and the page's content stays inside a live region.
|
|
1374
|
+
* The lookup's result is said separately when it arrives, through the
|
|
1375
|
+
* announcer with `keep`, so the two never replace each other. Dismissing the
|
|
1376
|
+
* line ends the lookup, the same as Escape.
|
|
1377
|
+
*/
|
|
1378
|
+
export declare function IdentifyStatus({ onCancel }: IdentifyStatusProps): JSX.Element;
|
|
1379
|
+
|
|
1380
|
+
/** Props for {@link IdentifyStatus}. */
|
|
1381
|
+
export declare interface IdentifyStatusProps {
|
|
1382
|
+
/** Ends the lookup, as Escape does. Called from the line's dismiss button. */
|
|
1383
|
+
readonly onCancel: () => void;
|
|
1384
|
+
}
|
|
1385
|
+
|
|
1386
|
+
/**
|
|
1387
|
+
* Keeps a run of text in its own bidirectional context. Use it for anything
|
|
1388
|
+
* that is not copy from the message catalogue and may differ in direction or
|
|
1389
|
+
* language from its surroundings: a place name, an address, a feature title, a
|
|
1390
|
+
* coordinate, a scale label or a number with its unit. In right-to-left text
|
|
1391
|
+
* these would otherwise reorder, because the neighbouring punctuation and
|
|
1392
|
+
* numbers take the direction of the paragraph.
|
|
1393
|
+
*
|
|
1394
|
+
* @remarks Renders a `bdi`, which isolates its content and, unless `figure` is
|
|
1395
|
+
* set, takes its direction from the first strong letter. Pass `lang` where
|
|
1396
|
+
* the language is known, so a screen reader pronounces a name in its own
|
|
1397
|
+
* language. Text the catalogue substitutes into a sentence is isolated by
|
|
1398
|
+
* the catalogue instead (`isolateParameters` in `createMessageCatalogue`).
|
|
1399
|
+
*/
|
|
1400
|
+
export declare function Isolate({ figure, ...rest }: IsolateProps): JSX.Element;
|
|
1401
|
+
|
|
1402
|
+
/** Props for {@link Isolate}. */
|
|
1403
|
+
export declare interface IsolateProps extends Omit<HTMLAttributes<HTMLElement>, "dir"> {
|
|
1404
|
+
/**
|
|
1405
|
+
* Marks ASCII figures that always read left to right, such as the signed
|
|
1406
|
+
* coordinates `formatLatLng` writes. It sets `dir="ltr"` and
|
|
1407
|
+
* `translate="no"`. Leave it off for a name, a distance or any text whose
|
|
1408
|
+
* direction depends on its letters.
|
|
1409
|
+
*/
|
|
1410
|
+
readonly figure?: boolean;
|
|
1411
|
+
}
|
|
1412
|
+
|
|
1413
|
+
/** What {@link useLanguageLoad} returns. */
|
|
1414
|
+
export declare interface LanguageLoad {
|
|
1415
|
+
/**
|
|
1416
|
+
* The tag whose messages could not be loaded, while the interface is still in
|
|
1417
|
+
* the language before it, or null when no load has failed.
|
|
1418
|
+
*/
|
|
1419
|
+
readonly failed: string | null;
|
|
1420
|
+
/** Whether a load of {@link LanguageLoad.failed} is under way again. */
|
|
1421
|
+
readonly retrying: boolean;
|
|
1422
|
+
/** Loads the failed language again. It does nothing when none has failed. */
|
|
1423
|
+
readonly retry: () => void;
|
|
1424
|
+
}
|
|
1425
|
+
|
|
1426
|
+
/**
|
|
1427
|
+
* One layer in the Layers section: its switch with what it costs, and while
|
|
1428
|
+
* it is on, its status, controls, legend, disclaimer and list. Everything
|
|
1429
|
+
* comes from the definition.
|
|
1430
|
+
*/
|
|
1431
|
+
export declare function LayerItem({ layer, layers, formatters, onShow, }: LayerItemProps): JSX.Element;
|
|
1432
|
+
|
|
1433
|
+
/** Props for {@link LayerItem}. */
|
|
1434
|
+
export declare interface LayerItemProps {
|
|
1435
|
+
readonly layer: DataLayerState;
|
|
1436
|
+
readonly layers: DataLayers;
|
|
1437
|
+
readonly formatters: FormatterRegistry;
|
|
1438
|
+
readonly onShow: (layerId: string, feature: LayerFeature) => void;
|
|
1439
|
+
}
|
|
1440
|
+
|
|
1441
|
+
/**
|
|
1442
|
+
* A layer's key: one row for each colour, shape or class its style draws,
|
|
1443
|
+
* with the same glyph the map uses and the words for it. The Layers section
|
|
1444
|
+
* and the map key both draw it, so the two cannot disagree. Renders nothing
|
|
1445
|
+
* for a layer whose definition has no key.
|
|
1446
|
+
*
|
|
1447
|
+
* @remarks The caller names the list, so two lists for one layer can sit on
|
|
1448
|
+
* a page with different names.
|
|
1449
|
+
*/
|
|
1450
|
+
export declare function LayerKey({ definition, label, testId, layout, }: LayerKeyProps): JSX.Element | null;
|
|
1451
|
+
|
|
1452
|
+
/** How a {@link LayerKey} arranges its rows. */
|
|
1453
|
+
export declare type LayerKeyLayout = "wrap" | "stacked";
|
|
1454
|
+
|
|
1455
|
+
/** Props for {@link LayerKey}. */
|
|
1456
|
+
export declare interface LayerKeyProps {
|
|
1457
|
+
readonly definition: LayerDefinition;
|
|
1458
|
+
/** The list's accessible name, such as `Key for Earthquakes`. */
|
|
1459
|
+
readonly label: string;
|
|
1460
|
+
/** The list's `data-testid`. */
|
|
1461
|
+
readonly testId: string;
|
|
1462
|
+
/**
|
|
1463
|
+
* How the rows sit: `wrap` (the default) side by side, wrapping as the
|
|
1464
|
+
* line fills; `stacked` one to a line, with the glyphs in a fixed-width
|
|
1465
|
+
* column so the words line up.
|
|
1466
|
+
*/
|
|
1467
|
+
readonly layout?: LayerKeyLayout;
|
|
1468
|
+
}
|
|
1469
|
+
|
|
1470
|
+
/**
|
|
1471
|
+
* The Layers section of the sheet and side panel, drawn entirely from the
|
|
1472
|
+
* layer definitions: a switch per layer with its data cost, and while a layer
|
|
1473
|
+
* is on, its status, controls, legend, disclaimer and the list of what
|
|
1474
|
+
* loaded. The open feature's card sits at the top. When the catalogue is
|
|
1475
|
+
* loading, has failed, is empty or skipped definitions, it says so (see
|
|
1476
|
+
* `CatalogueStatus`). Renders nothing for a host whose layers were there from
|
|
1477
|
+
* the start and are none.
|
|
1478
|
+
*
|
|
1479
|
+
* @remarks A tap on the map asks for the card to take focus
|
|
1480
|
+
* (`layers.focusPending`); the focus moves after the sheet's own focus
|
|
1481
|
+
* effects, so the card heading wins over the section heading.
|
|
1482
|
+
*/
|
|
1483
|
+
export declare function LayersSection({ layers, headingLevel, headingRef, formatters, onShowOnMap, showTurnOffAll, intro, }: LayersSectionProps): JSX.Element | null;
|
|
1484
|
+
|
|
1485
|
+
/** Props for {@link LayersSection}. */
|
|
1486
|
+
export declare interface LayersSectionProps {
|
|
1487
|
+
readonly layers: DataLayers;
|
|
1488
|
+
/** The heading level. Defaults to 3, below the sheet's h2 title. */
|
|
1489
|
+
readonly headingLevel?: HeadingLevel;
|
|
1490
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
1491
|
+
/** The formatters card and list templates may name. Defaults to the built-ins. */
|
|
1492
|
+
readonly formatters?: FormatterRegistry;
|
|
1493
|
+
/**
|
|
1494
|
+
* Called after "Show on map" has centred a feature, so the host can make
|
|
1495
|
+
* room for the map: the section keeps the feature clear of the sheet at
|
|
1496
|
+
* `REVEAL_DETENT`, so the host should bring the sheet to that detent.
|
|
1497
|
+
*/
|
|
1498
|
+
readonly onShowOnMap?: () => void;
|
|
1499
|
+
/**
|
|
1500
|
+
* Whether the section offers "Turn off all layers", the action for each
|
|
1501
|
+
* group and the Undo that follows. Defaults to true; a host that does not
|
|
1502
|
+
* want them passes false.
|
|
1503
|
+
*/
|
|
1504
|
+
readonly showTurnOffAll?: boolean;
|
|
1505
|
+
/**
|
|
1506
|
+
* The line above the layers, in place of the catalogue's `layers.intro` ("Open
|
|
1507
|
+
* data from public providers. Nothing is requested until you turn a layer
|
|
1508
|
+
* on."), which is not true of every host (one behind a login serves its own
|
|
1509
|
+
* data). An empty string leaves the line out.
|
|
1510
|
+
*/
|
|
1511
|
+
readonly intro?: string;
|
|
1512
|
+
}
|
|
1513
|
+
|
|
1514
|
+
/**
|
|
1515
|
+
* Where a layer is: off, on (tiles), loading, loaded, empty, failed, or
|
|
1516
|
+
* outside its zoom window. Outside it, the status says the normalised level
|
|
1517
|
+
* to zoom to: `zoom-in` for a query layer too far out to ask for features or
|
|
1518
|
+
* a vector tile layer too far out to show, `zoom-out` for a vector tile layer
|
|
1519
|
+
* too far in. A tile layer is `on` until the map reports that it is still
|
|
1520
|
+
* waiting for its first tile (`tiles-slow`) or that none of its tiles loaded
|
|
1521
|
+
* (`tiles-unavailable`, which replaces `tiles-slow`). Either lasts until its
|
|
1522
|
+
* tiles change, it is turned off, or the map reports that a tile loaded
|
|
1523
|
+
* later, when it is `on` again.
|
|
1524
|
+
*/
|
|
1525
|
+
export declare type LayerStatus = {
|
|
1526
|
+
readonly kind: "off";
|
|
1527
|
+
} | {
|
|
1528
|
+
readonly kind: "on";
|
|
1529
|
+
} | {
|
|
1530
|
+
readonly kind: "tiles-slow";
|
|
1531
|
+
} | {
|
|
1532
|
+
readonly kind: "tiles-unavailable";
|
|
1533
|
+
} | {
|
|
1534
|
+
readonly kind: "loading";
|
|
1535
|
+
} | {
|
|
1536
|
+
readonly kind: "ready";
|
|
1537
|
+
/** How many are drawn. */
|
|
1538
|
+
readonly count: number;
|
|
1539
|
+
readonly updatedAt: number;
|
|
1540
|
+
/** True when the query had more than its cap, so only the first are drawn. */
|
|
1541
|
+
readonly capped?: boolean;
|
|
1542
|
+
} | ZoomLimit | {
|
|
1543
|
+
readonly kind: "empty";
|
|
1544
|
+
readonly updatedAt: number;
|
|
1545
|
+
} | {
|
|
1546
|
+
readonly kind: "error";
|
|
1547
|
+
readonly error: "network" | "invalid";
|
|
1548
|
+
/**
|
|
1549
|
+
* Set when the device said it was offline as the request failed, so
|
|
1550
|
+
* the layer can word it as that while it still is. Absent otherwise.
|
|
1551
|
+
*/
|
|
1552
|
+
readonly offline?: true;
|
|
1553
|
+
};
|
|
1554
|
+
|
|
1555
|
+
/**
|
|
1556
|
+
* A list item for lists of places, layers and options. Render rows inside a
|
|
1557
|
+
* `ul` (or `ol`). Without `onClick` the row is plain content; with it the row
|
|
1558
|
+
* is a single full-width button, so the whole row is the target.
|
|
1559
|
+
*/
|
|
1560
|
+
export declare function ListRow({ icon, label, secondary: secondaryText, trailing: trailingNode, selected, onClick, className, ...rest }: ListRowProps): JSX.Element;
|
|
1561
|
+
|
|
1562
|
+
/** Props for {@link ListRow}. */
|
|
1563
|
+
export declare interface ListRowProps extends Omit<LiHTMLAttributes<HTMLLIElement>, "children" | "onClick"> {
|
|
1564
|
+
/** A leading icon, imported by name from `lucide-react`. */
|
|
1565
|
+
readonly icon?: IconComponent;
|
|
1566
|
+
/** The row's main text. */
|
|
1567
|
+
readonly label: ReactNode;
|
|
1568
|
+
/** A second, quieter line under the label. */
|
|
1569
|
+
readonly secondary?: ReactNode;
|
|
1570
|
+
/** Anything to show at the end, such as a value. Rendered before the check. */
|
|
1571
|
+
readonly trailing?: ReactNode;
|
|
1572
|
+
/**
|
|
1573
|
+
* Marks the row as the current choice. Shown with a check icon and
|
|
1574
|
+
* `aria-current`, so selection does not depend on colour.
|
|
1575
|
+
*/
|
|
1576
|
+
readonly selected?: boolean;
|
|
1577
|
+
/** Makes the whole row a full-width button inside the `li`. */
|
|
1578
|
+
readonly onClick?: MouseEventHandler<HTMLButtonElement>;
|
|
1579
|
+
}
|
|
1580
|
+
|
|
1581
|
+
/**
|
|
1582
|
+
* Mounts the one app-wide announcer: a visually hidden polite `status` region
|
|
1583
|
+
* and a visually hidden assertive `alert` region. Nothing else in the app may
|
|
1584
|
+
* create a live region except `StatusMessage`, which is a visible message.
|
|
1585
|
+
* @remarks Mount it once, near the root. A second provider logs a warning in
|
|
1586
|
+
* development, because two announcers would read the same message twice.
|
|
1587
|
+
*/
|
|
1588
|
+
export declare function LiveRegionProvider({ children }: LiveRegionProviderProps): JSX.Element;
|
|
1589
|
+
|
|
1590
|
+
/** Props for {@link LiveRegionProvider}. */
|
|
1591
|
+
export declare interface LiveRegionProviderProps {
|
|
1592
|
+
readonly children?: ReactNode;
|
|
1593
|
+
}
|
|
1594
|
+
|
|
1595
|
+
/** Where a locate request stands. */
|
|
1596
|
+
export declare type LocateState = "idle" | "locating" | "found" | "error";
|
|
1597
|
+
|
|
1598
|
+
/** How long a still press must last to count as a long-press, in milliseconds. */
|
|
1599
|
+
export declare const LONG_PRESS_DELAY_MS = 500;
|
|
1600
|
+
|
|
1601
|
+
/**
|
|
1602
|
+
* The one owner of everything floating over the map. It draws the map
|
|
1603
|
+
* full-bleed inside `main`, lays the slots out with flow layout, and keeps
|
|
1604
|
+
* the bottom slots clear of the sheet, the side panel and the measure
|
|
1605
|
+
* toolbar.
|
|
1606
|
+
*
|
|
1607
|
+
* @remarks
|
|
1608
|
+
* - DOM order is reading order: top-start, tour, end-stack, the sheet, the map
|
|
1609
|
+
* (`main`), the map key, then bottom-start, bottom-centre and bottom-end.
|
|
1610
|
+
* The app renders the skip link before this component and the page's h1
|
|
1611
|
+
* itself.
|
|
1612
|
+
* - While `modal`, every group except the sheet gets `inert`. That is one
|
|
1613
|
+
* inert attribute per group rather than one wrapper, because the sheet sits
|
|
1614
|
+
* between the groups in reading order.
|
|
1615
|
+
* - The container ignores the pointer; each slot takes it back, so the map
|
|
1616
|
+
* stays draggable in every gap. Every slot wrapper has `data-chrome` with
|
|
1617
|
+
* its slot name; the sheet carries its own `data-chrome="sheet"`.
|
|
1618
|
+
* - A `ResizeObserver` measures the container (which already reflects the
|
|
1619
|
+
* visual viewport) and the slots. From that it chooses the layout, gives
|
|
1620
|
+
* `ChromeLayoutProvider` the viewport and the pointer preference, and sets
|
|
1621
|
+
* the {@link chromeVars} on the root with CSSOM: never a `style` attribute,
|
|
1622
|
+
* because production CSP is `style-src 'self'`.
|
|
1623
|
+
* - The sheet publishes its top edge (`publishSheetTop`) and detent, and the
|
|
1624
|
+
* side panel its right edge. Whatever is shown in bottom-centre, a toolbar
|
|
1625
|
+
* first, is an obstruction too, measured from its slot.
|
|
1626
|
+
* `computeBottomSlotLayout` turns these into the lift and shift of the
|
|
1627
|
+
* bottom slots, which hide at the full detent.
|
|
1628
|
+
* - The bottom row rides above the sheet with a `transform`, which slides, and
|
|
1629
|
+
* above the bottom-centre slot with the separate `translate` property
|
|
1630
|
+
* (`bottomStartRaise`, `bottomEndRaise` and `mapKeyRaise`, each zero for a slot
|
|
1631
|
+
* that shares no width with the bottom-centre slot), which does not, and which
|
|
1632
|
+
* the measuring observer sets in
|
|
1633
|
+
* its own callback. A toolbar that changes height therefore never has the
|
|
1634
|
+
* row over it, in any frame, with motion or without.
|
|
1635
|
+
* - Before the first measurement (and in server rendering) the layout is the
|
|
1636
|
+
* bottom sheet, the narrow-screen default.
|
|
1637
|
+
*/
|
|
1638
|
+
export declare function MapChrome({ background, topStart, endStack, bottomStart, bottomEnd, bottomCentre, tour, tourSide, mapKey, sheet, modal, onViewportChange, }: MapChromeProps): JSX.Element;
|
|
1639
|
+
|
|
1640
|
+
/** Props for {@link MapChrome}. */
|
|
1641
|
+
export declare interface MapChromeProps {
|
|
1642
|
+
/** The map, drawn full-bleed behind everything inside the `main` landmark. */
|
|
1643
|
+
readonly background: ReactNode;
|
|
1644
|
+
/** Search pill. */
|
|
1645
|
+
readonly topStart?: ReactNode;
|
|
1646
|
+
/** Compass, main control group and zoom group (`EndStack`). */
|
|
1647
|
+
readonly endStack?: ReactNode;
|
|
1648
|
+
/** Scale bar, cursor coordinates and zoom level (`MapReadout`). */
|
|
1649
|
+
readonly bottomStart?: ReactNode;
|
|
1650
|
+
/** Attribution. */
|
|
1651
|
+
readonly bottomEnd?: ReactNode;
|
|
1652
|
+
/** Measure toolbar, toasts and the tile-error banner. */
|
|
1653
|
+
readonly bottomCentre?: ReactNode;
|
|
1654
|
+
/**
|
|
1655
|
+
* The first-visit tour card. It sits in the free space at the top of the
|
|
1656
|
+
* map: under the search pill on a narrow screen, and between the search
|
|
1657
|
+
* column and the end stack in the panel layout. It hides, like the bottom
|
|
1658
|
+
* slots, while the sheet is at full, and while the bottom row, lifted above
|
|
1659
|
+
* the sheet or a toolbar, would run into it.
|
|
1660
|
+
*/
|
|
1661
|
+
readonly tour?: ReactNode;
|
|
1662
|
+
/**
|
|
1663
|
+
* In the panel layout, whether the tour card sits against the search
|
|
1664
|
+
* column and panel (`"start"`, the default) or against the end stack.
|
|
1665
|
+
*/
|
|
1666
|
+
readonly tourSide?: "start" | "end";
|
|
1667
|
+
/**
|
|
1668
|
+
* The key to the layers that are on (`MapKey`). It sits above the scale
|
|
1669
|
+
* bar, rides above the sheet or beside the side panel with it, is as tall
|
|
1670
|
+
* as the room under the search pill allows, and hides when there is no room
|
|
1671
|
+
* for its chip, while the credits are open, and at the full detent. A
|
|
1672
|
+
* prop named `key` would be React's own, so it is `mapKey`.
|
|
1673
|
+
*/
|
|
1674
|
+
readonly mapKey?: ReactNode;
|
|
1675
|
+
/**
|
|
1676
|
+
* The `Sheet` (bottom sheet or side panel). Rendered outside every inert
|
|
1677
|
+
* group, so it stays operable while the rest of the chrome is inert.
|
|
1678
|
+
*/
|
|
1679
|
+
readonly sheet?: ReactNode;
|
|
1680
|
+
/** True while the sheet is modal: everything but the sheet becomes `inert`. */
|
|
1681
|
+
readonly modal: boolean;
|
|
1682
|
+
/** Called when the measured container size changes. */
|
|
1683
|
+
readonly onViewportChange?: (viewport: {
|
|
1684
|
+
readonly width: number;
|
|
1685
|
+
readonly height: number;
|
|
1686
|
+
}) => void;
|
|
1687
|
+
}
|
|
1688
|
+
|
|
1689
|
+
/** The map context. Provided by `MapView`; read it with {@link useMap}. */
|
|
1690
|
+
export declare const MapContext: Context<MapContextValue | null>;
|
|
1691
|
+
|
|
1692
|
+
/** What {@link useMap} returns: the live map, as seen by overlays and chrome. */
|
|
1693
|
+
export declare interface MapContextValue {
|
|
1694
|
+
/**
|
|
1695
|
+
* The mounted adapter, or null while the engine is starting, after it failed
|
|
1696
|
+
* and during server rendering. Overlays draw nothing while it is null.
|
|
1697
|
+
*/
|
|
1698
|
+
readonly adapter: MapAdapter | null;
|
|
1699
|
+
/**
|
|
1700
|
+
* The element the engine is mounted in, or null with no mounted engine.
|
|
1701
|
+
* A new element replaces it when a failed mount is retried.
|
|
1702
|
+
*/
|
|
1703
|
+
readonly hostElement: HTMLElement | null;
|
|
1704
|
+
/**
|
|
1705
|
+
* The current view, updated at most once per animation frame while the map
|
|
1706
|
+
* moves, zooms or rotates, so overlays re-project without thrashing.
|
|
1707
|
+
*/
|
|
1708
|
+
readonly view: ViewState;
|
|
1709
|
+
/**
|
|
1710
|
+
* The shape the map is drawn as, from the settings: flat or a globe.
|
|
1711
|
+
* Overlays read it to curve long lines and hide the far side.
|
|
1712
|
+
*/
|
|
1713
|
+
readonly projection: MapProjection;
|
|
1714
|
+
/** Normalised zoom limits of the active basemap. */
|
|
1715
|
+
readonly minZoom: number;
|
|
1716
|
+
readonly maxZoom: number;
|
|
1717
|
+
readonly canZoomIn: boolean;
|
|
1718
|
+
readonly canZoomOut: boolean;
|
|
1719
|
+
/** True while the engine starts, the basemap changes or tiles load. */
|
|
1720
|
+
readonly loading: boolean;
|
|
1721
|
+
/** True after a tile or style request failed, until a later load succeeds without one. */
|
|
1722
|
+
readonly tileError: boolean;
|
|
1723
|
+
/**
|
|
1724
|
+
* Why the engine could not start, or why it stopped after it loaded
|
|
1725
|
+
* (reason `stopped`), or null. The app decides the fallback.
|
|
1726
|
+
*/
|
|
1727
|
+
readonly error: MapEngineError | null;
|
|
1728
|
+
/**
|
|
1729
|
+
* Re-applies the active basemap after a tile error. After an engine error it
|
|
1730
|
+
* mounts the engine again instead.
|
|
1731
|
+
*/
|
|
1732
|
+
readonly retry: () => void;
|
|
1733
|
+
/** Moves keyboard focus to the map region without scrolling. */
|
|
1734
|
+
readonly focusMap: () => void;
|
|
1735
|
+
/**
|
|
1736
|
+
* Calls `listener` each time the person zooms the map itself: with the
|
|
1737
|
+
* zoom keys on the map region, or with a gesture the engine handles (a
|
|
1738
|
+
* wheel, a pinch, a double-click). Zooms made in code, such as restoring a
|
|
1739
|
+
* permalink or applying a basemap's limits, never call it. Returns the
|
|
1740
|
+
* function that unsubscribes.
|
|
1741
|
+
*/
|
|
1742
|
+
readonly onUserZoom: (listener: () => void) => () => void;
|
|
1743
|
+
}
|
|
1744
|
+
|
|
1745
|
+
/** The pointer shown over the map: grab for panning, crosshair while measuring. */
|
|
1746
|
+
export declare type MapCursor = "grab" | "crosshair";
|
|
1747
|
+
|
|
1748
|
+
/**
|
|
1749
|
+
* Draws the layers that are on, and a shown affected area, through the map
|
|
1750
|
+
* adapter, and turns a tap on a point into an open card. Renders nothing; put
|
|
1751
|
+
* it inside `MapView`. Every layer is drawn from its definition, so nothing
|
|
1752
|
+
* here names one.
|
|
1753
|
+
*/
|
|
1754
|
+
export declare function MapDataLayers({ layers, onFeatureTap, ignoreTaps, formatters, }: MapDataLayersProps): null;
|
|
1755
|
+
|
|
1756
|
+
/** Props for {@link MapDataLayers}. */
|
|
1757
|
+
export declare interface MapDataLayersProps {
|
|
1758
|
+
readonly layers: DataLayers;
|
|
1759
|
+
/** Called after a tap on a point has selected it, so the app can open its card. */
|
|
1760
|
+
readonly onFeatureTap?: (tap: MapFeatureTap) => void;
|
|
1761
|
+
/** True while taps on the map mean something else, such as measuring. */
|
|
1762
|
+
readonly ignoreTaps?: boolean;
|
|
1763
|
+
/** The formatters label templates may name. Defaults to the built-ins. */
|
|
1764
|
+
readonly formatters?: FormatterRegistry;
|
|
1765
|
+
}
|
|
1766
|
+
|
|
1767
|
+
/**
|
|
1768
|
+
* Draws a route as a line with a white casing, or a travel-time area as an
|
|
1769
|
+
* outlined, tinted shape, through the map adapter's shape layers, and fits the
|
|
1770
|
+
* map to it, clear of the sheet or side panel. Renders nothing; put it inside
|
|
1771
|
+
* `MapView`. The engine draws the shapes, so they stay sharp while the map
|
|
1772
|
+
* moves and come back after a basemap swap.
|
|
1773
|
+
*/
|
|
1774
|
+
export declare function MapDirections({ result }: MapDirectionsProps): null;
|
|
1775
|
+
|
|
1776
|
+
/** Props for {@link MapDirections}. */
|
|
1777
|
+
export declare interface MapDirectionsProps {
|
|
1778
|
+
/** The route or area to draw, or null for none. */
|
|
1779
|
+
readonly result: DirectionsOutcome | null;
|
|
1780
|
+
}
|
|
1781
|
+
|
|
1782
|
+
/**
|
|
1783
|
+
* The key to the layers that are on, for the map itself: a panel named "Map
|
|
1784
|
+
* key" with one block for each layer that has a key, so a person can read
|
|
1785
|
+
* what the colours and shapes mean without opening the Layers section. It
|
|
1786
|
+
* draws the same rows the section does ({@link LayerKey}). It minimises to a
|
|
1787
|
+
* chip that shows a strip of glyphs and how many layers it covers, and renders
|
|
1788
|
+
* nothing while no layer that is on has a key.
|
|
1789
|
+
*
|
|
1790
|
+
* @remarks Put it in `MapChrome`'s `mapKey` slot, which keeps it clear of the
|
|
1791
|
+
* other floating elements and caps its height. The minimised state is held
|
|
1792
|
+
* in memory, so it lasts for the visit but not a reload. The button's name
|
|
1793
|
+
* is "Key, 3 layers" open and minimised, and `aria-expanded` says which.
|
|
1794
|
+
*/
|
|
1795
|
+
export declare function MapKey({ layers, defaultMinimised }: MapKeyProps): JSX.Element | null;
|
|
1796
|
+
|
|
1797
|
+
/** What the map key shows for one layer that is on. */
|
|
1798
|
+
export declare interface MapKeyBlock {
|
|
1799
|
+
readonly id: string;
|
|
1800
|
+
readonly name: string;
|
|
1801
|
+
readonly definition: LayerDefinition;
|
|
1802
|
+
/** The key's rows, in the order the layer's style lists them. Never empty. */
|
|
1803
|
+
readonly entries: readonly [LegendEntry, ...LegendEntry[]];
|
|
1804
|
+
/**
|
|
1805
|
+
* The day or time the layer is set to, in words such as `13:00 UTC on 11
|
|
1806
|
+
* November 2026`, or null when it has no date or time control.
|
|
1807
|
+
*/
|
|
1808
|
+
readonly chosenTime: Message | null;
|
|
1809
|
+
}
|
|
1810
|
+
|
|
1811
|
+
/**
|
|
1812
|
+
* The blocks of the map key: one for each layer that is on and has a key, in
|
|
1813
|
+
* catalogue order. Pure, so the image export can draw the same key the map
|
|
1814
|
+
* shows. The words for an interval are written in `catalogue`'s language.
|
|
1815
|
+
* An empty result means there is no key to show at all.
|
|
1816
|
+
*/
|
|
1817
|
+
export declare function mapKeyBlocks(layers: readonly DataLayerState[], catalogue: MessageCatalogue): readonly MapKeyBlock[];
|
|
1818
|
+
|
|
1819
|
+
/** Props for {@link MapKey}. */
|
|
1820
|
+
export declare interface MapKeyProps {
|
|
1821
|
+
readonly layers: DataLayers;
|
|
1822
|
+
/**
|
|
1823
|
+
* Whether the key starts minimised. Left out, a phone in either orientation
|
|
1824
|
+
* starts it minimised (the viewport is narrower than the bottom sheet's
|
|
1825
|
+
* width or shorter than the side panel's height threshold) and a larger
|
|
1826
|
+
* screen starts it open. It is decided when the key first appears, so
|
|
1827
|
+
* turning the phone does not change it, and the person's own choice
|
|
1828
|
+
* replaces it from then on.
|
|
1829
|
+
*/
|
|
1830
|
+
readonly defaultMinimised?: boolean;
|
|
1831
|
+
}
|
|
1832
|
+
|
|
1833
|
+
/** Where a long-press (or right-click) happened. */
|
|
1834
|
+
export declare interface MapLongPressEvent {
|
|
1835
|
+
readonly latlng: LatLng;
|
|
1836
|
+
/** Pixels from the top-left corner of the map host. */
|
|
1837
|
+
readonly point: PixelPoint;
|
|
1838
|
+
}
|
|
1839
|
+
|
|
1840
|
+
/**
|
|
1841
|
+
* The single layer every map overlay draws into: one SVG spanning the map
|
|
1842
|
+
* host, above the engine and below the chrome. Place it inside `MapView`.
|
|
1843
|
+
*
|
|
1844
|
+
* @remarks It is hidden from assistive technology and never takes pointer
|
|
1845
|
+
* events. Overlays are pictures of state that the interface also gives in
|
|
1846
|
+
* text (the pin's coordinates, the measured distance, the location accuracy).
|
|
1847
|
+
*/
|
|
1848
|
+
export declare function MapOverlayLayer({ children, testId }: MapOverlayLayerProps): JSX.Element;
|
|
1849
|
+
|
|
1850
|
+
/** Props for {@link MapOverlayLayer}. */
|
|
1851
|
+
export declare interface MapOverlayLayerProps {
|
|
1852
|
+
/** SVG overlays such as `PinMarker` and `MeasureOverlay`. */
|
|
1853
|
+
readonly children?: ReactNode;
|
|
1854
|
+
readonly testId?: string;
|
|
1855
|
+
}
|
|
1856
|
+
|
|
1857
|
+
/**
|
|
1858
|
+
* The bottom-start readout: the scale bar with the cursor coordinates and
|
|
1859
|
+
* zoom level under it. One floating element, for the layout collision test,
|
|
1860
|
+
* and a landmark named "Map scale" so its content is inside a landmark.
|
|
1861
|
+
* Reads the zoom with `useMap()` and the layout with `useChromeLayout()`, so
|
|
1862
|
+
* it must sit inside the map context and a `MapChrome`.
|
|
1863
|
+
*/
|
|
1864
|
+
export declare function MapReadout({ units, latlng, showZoom, onCursorLeave, }: MapReadoutProps): JSX.Element;
|
|
1865
|
+
|
|
1866
|
+
/** Props for {@link MapReadout}. */
|
|
1867
|
+
export declare interface MapReadoutProps extends ScaleBarProps, Pick<CursorCoordinatesProps, "latlng"> {
|
|
1868
|
+
/**
|
|
1869
|
+
* Whether to show the map's zoom level beside the coordinates. Left out, it
|
|
1870
|
+
* follows the chrome layout: shown in the side panel layout and left out in
|
|
1871
|
+
* the bottom sheet layout, which keeps the readout short on a small screen.
|
|
1872
|
+
* Pass true or false to decide it yourself. The credits popover clears the
|
|
1873
|
+
* readout either way.
|
|
1874
|
+
*/
|
|
1875
|
+
readonly showZoom?: boolean;
|
|
1876
|
+
/**
|
|
1877
|
+
* Called when the pointer leaves the readout for anything but the map. The
|
|
1878
|
+
* map keeps the last position while the pointer moves from it onto the
|
|
1879
|
+
* readout, so the coordinates stay put and can be copied; this is where the
|
|
1880
|
+
* host clears them.
|
|
1881
|
+
*/
|
|
1882
|
+
readonly onCursorLeave?: () => void;
|
|
1883
|
+
}
|
|
1884
|
+
|
|
1885
|
+
/**
|
|
1886
|
+
* The engine host: the map region and the single focus stop of the map. It
|
|
1887
|
+
* mounts the adapter the services build, without knowing which engine that
|
|
1888
|
+
* is, and provides the live map to `children` through `useMap`.
|
|
1889
|
+
*
|
|
1890
|
+
* @remarks
|
|
1891
|
+
* - Keyboard and long-press are implemented here once, against the adapter;
|
|
1892
|
+
* the engine's own key handling is turned off.
|
|
1893
|
+
* - A new basemap is swapped in on the mounted engine, keeping the centre,
|
|
1894
|
+
* zoom and bearing. This component, its children and the chrome around it
|
|
1895
|
+
* stay mounted.
|
|
1896
|
+
* - Server rendering produces the empty region only; no style attributes are
|
|
1897
|
+
* rendered, so it works under `style-src 'self'`. `data-zoom` is written
|
|
1898
|
+
* with `setAttribute` once the engine reports a zoom.
|
|
1899
|
+
* - The host fills its parent; `MapChrome` owns its placement.
|
|
1900
|
+
* - The whole output, including `chrome`, is inside the map context.
|
|
1901
|
+
*/
|
|
1902
|
+
export declare function MapView({ initialView, basemap, onViewChange, onEngineError, onBasemapApplied, onBasemapError, onBasemapUnavailable, onClick, onLongPress, onPointerMove, onDropPinKey, onIdentifyKey, onEscape, onKeyCommand, keyHelp, cursor, children, id, chrome, testId, }: MapViewProps): JSX.Element;
|
|
1903
|
+
|
|
1904
|
+
/** Props for {@link MapView}. */
|
|
1905
|
+
export declare interface MapViewProps {
|
|
1906
|
+
/** The view the engine mounts with. Later changes are ignored. */
|
|
1907
|
+
readonly initialView: ViewState;
|
|
1908
|
+
/** The active basemap. A change is applied to the mounted engine with `setBasemap`. */
|
|
1909
|
+
readonly basemap: BasemapDefinition;
|
|
1910
|
+
/** Called when the view stops changing (`moveEnd`), not on every frame. */
|
|
1911
|
+
readonly onViewChange?: (view: ViewState) => void;
|
|
1912
|
+
/**
|
|
1913
|
+
* Called when the engine cannot start or stops working. The
|
|
1914
|
+
* app decides what to show, for example a message when WebGL is missing.
|
|
1915
|
+
*/
|
|
1916
|
+
readonly onEngineError?: (error: MapEngineError, basemap: BasemapDefinition) => void;
|
|
1917
|
+
/**
|
|
1918
|
+
* Called when a change of `basemap` has loaded on the mounted engine, so
|
|
1919
|
+
* the app can save the choice only once it is known to work.
|
|
1920
|
+
*/
|
|
1921
|
+
readonly onBasemapApplied?: (basemap: BasemapDefinition) => void;
|
|
1922
|
+
/**
|
|
1923
|
+
* Called when a change of `basemap` could not load. The map keeps drawing
|
|
1924
|
+
* `kept`, the basemap that last loaded, and this is not an engine error:
|
|
1925
|
+
* `useMap().error` stays null. Passing `kept` back as `basemap` causes no
|
|
1926
|
+
* second swap.
|
|
1927
|
+
*/
|
|
1928
|
+
readonly onBasemapError?: (error: MapEngineError, failed: BasemapDefinition, kept: BasemapDefinition) => void;
|
|
1929
|
+
/**
|
|
1930
|
+
* Called when every tile of the basemap being drawn failed to load and none
|
|
1931
|
+
* loaded, once the map settled (its provider is down). The map keeps
|
|
1932
|
+
* working, so the host decides whether to draw another basemap instead.
|
|
1933
|
+
*/
|
|
1934
|
+
readonly onBasemapUnavailable?: (basemap: BasemapDefinition) => void;
|
|
1935
|
+
/** A click or tap on the map. Not called for the click that ends a long-press. */
|
|
1936
|
+
readonly onClick?: (event: MapClickEvent) => void;
|
|
1937
|
+
/** A long-press (touch or mouse) or a right-click. */
|
|
1938
|
+
readonly onLongPress?: (event: MapLongPressEvent) => void;
|
|
1939
|
+
/**
|
|
1940
|
+
* The position under a mouse or pen, at most once per frame, or null when
|
|
1941
|
+
* it leaves the map. For the cursor coordinates readout; touch is ignored.
|
|
1942
|
+
* Leaving the map for `MapReadout` reports nothing, so the coordinates stay
|
|
1943
|
+
* put while the readout grows under the pointer: pass `MapReadout` an
|
|
1944
|
+
* `onCursorLeave` that clears the position, or it stays shown after the
|
|
1945
|
+
* pointer leaves the readout.
|
|
1946
|
+
*/
|
|
1947
|
+
readonly onPointerMove?: (latlng: LatLng | null) => void;
|
|
1948
|
+
/** The P key, which drops a pin at the centre of the map. */
|
|
1949
|
+
readonly onDropPinKey?: () => void;
|
|
1950
|
+
/** The I key, which lists the features at the centre of the map. */
|
|
1951
|
+
readonly onIdentifyKey?: () => void;
|
|
1952
|
+
/** The Escape key while the map has focus. */
|
|
1953
|
+
readonly onEscape?: () => void;
|
|
1954
|
+
/**
|
|
1955
|
+
* Runs before the map's own keys, with each key pressed on the map region.
|
|
1956
|
+
* Return true to say the key was handled: the map then does nothing with it
|
|
1957
|
+
* and its default is prevented. A tool uses this to take keys the map would
|
|
1958
|
+
* otherwise use, such as the arrows that move a selected point.
|
|
1959
|
+
*/
|
|
1960
|
+
readonly onKeyCommand?: (event: KeyboardEvent_2<HTMLElement>) => boolean;
|
|
1961
|
+
/**
|
|
1962
|
+
* Extra lines for the hidden keyboard instructions, after the map's own,
|
|
1963
|
+
* for the keys a tool adds while it is open. Descriptions are used as
|
|
1964
|
+
* written, so write each as a complete sentence without a trailing full
|
|
1965
|
+
* stop.
|
|
1966
|
+
*/
|
|
1967
|
+
readonly keyHelp?: readonly MapKeyHelpEntry[];
|
|
1968
|
+
/** Defaults to `grab`. */
|
|
1969
|
+
readonly cursor?: MapCursor;
|
|
1970
|
+
/** Overlays and other content that reads the map through `useMap`. */
|
|
1971
|
+
readonly children?: ReactNode;
|
|
1972
|
+
/** The id of the map region, for example the target of a skip link. */
|
|
1973
|
+
readonly id?: string;
|
|
1974
|
+
/**
|
|
1975
|
+
* Renders the chrome around the map, inside the map context. It receives
|
|
1976
|
+
* the map region (with its hidden keyboard help) and returns the tree to
|
|
1977
|
+
* render in its place, so controls that call `useMap`, such as the scale
|
|
1978
|
+
* bar and the credits, can sit beside the map rather than inside it:
|
|
1979
|
+
* `chrome={(map) => <MapChrome background={map} ... />}`. Called on every
|
|
1980
|
+
* render; put hooks in the components it returns, not in the function.
|
|
1981
|
+
*/
|
|
1982
|
+
readonly chrome?: (map: ReactNode) => ReactNode;
|
|
1983
|
+
readonly testId?: string;
|
|
1984
|
+
}
|
|
1985
|
+
|
|
1986
|
+
/**
|
|
1987
|
+
* The marker a layer draws for a feature, as a small picture for the legend,
|
|
1988
|
+
* the list and the card, so words and map look the same: the fill over a
|
|
1989
|
+
* dark edge over a white halo, which shows on a light surface (the edge) and
|
|
1990
|
+
* a dark one (the halo) alike. Decorative: the words beside it carry the
|
|
1991
|
+
* meaning. Colours are SVG attributes, not styles, so they need nothing from
|
|
1992
|
+
* the Content-Security-Policy.
|
|
1993
|
+
*/
|
|
1994
|
+
export declare function MarkerGlyph({ shape, colour, radius }: MarkerGlyphProps): JSX.Element;
|
|
1995
|
+
|
|
1996
|
+
/** Props for {@link MarkerGlyph}. */
|
|
1997
|
+
export declare interface MarkerGlyphProps {
|
|
1998
|
+
readonly shape: MarkerShape;
|
|
1999
|
+
readonly colour: PaletteSlot;
|
|
2000
|
+
/** The radius the map draws it at, in CSS pixels. */
|
|
2001
|
+
readonly radius: number;
|
|
2002
|
+
}
|
|
2003
|
+
|
|
2004
|
+
/** The most layers one tap asks, in catalogue order. A tap that could ask more says how many it asked. */
|
|
2005
|
+
export declare const MAX_IDENTIFY_LAYERS = 4;
|
|
2006
|
+
|
|
2007
|
+
/** The most vertices one ring or line contributes to an outline drawn over the map. */
|
|
2008
|
+
export declare const MAX_OUTLINE_POINTS = 400;
|
|
2009
|
+
|
|
2010
|
+
/**
|
|
2011
|
+
* How long the points must stay still before the total is announced.
|
|
2012
|
+
*
|
|
2013
|
+
* @internal
|
|
2014
|
+
*/
|
|
2015
|
+
export declare const MEASURE_ANNOUNCE_DELAY_MS = 800;
|
|
2016
|
+
|
|
2017
|
+
/**
|
|
2018
|
+
* Radius of a measure vertex, in pixels.
|
|
2019
|
+
*
|
|
2020
|
+
* @internal
|
|
2021
|
+
*/
|
|
2022
|
+
export declare const MEASURE_VERTEX_RADIUS_PX = 5;
|
|
2023
|
+
|
|
2024
|
+
/** What is being measured. */
|
|
2025
|
+
export declare type MeasureMode = "distance" | "area";
|
|
2026
|
+
|
|
2027
|
+
/**
|
|
2028
|
+
* The measuring tool's drawing: vertices, the line between them and, for an
|
|
2029
|
+
* area, the closed polygon and its fill. Render it inside `MapOverlayLayer`.
|
|
2030
|
+
* @remarks Segments go the short way across the antimeridian. On a globe each
|
|
2031
|
+
* segment follows its great circle, the path the measured distance runs
|
|
2032
|
+
* along, and stops at the horizon: a vertex beyond it is not drawn, and the
|
|
2033
|
+
* fill and the closing edge of an area are drawn whole only while all of
|
|
2034
|
+
* the outline is in sight.
|
|
2035
|
+
*/
|
|
2036
|
+
export declare function MeasureOverlay({ points, mode, hover, testId, }: MeasureOverlayProps): JSX.Element | null;
|
|
2037
|
+
|
|
2038
|
+
/** Props for {@link MeasureOverlay}. */
|
|
2039
|
+
export declare interface MeasureOverlayProps {
|
|
2040
|
+
/** The committed points, in the order they were added. */
|
|
2041
|
+
readonly points: readonly LatLng[];
|
|
2042
|
+
/** A distance is an open line; an area is a closed, filled polygon. */
|
|
2043
|
+
readonly mode: "distance" | "area";
|
|
2044
|
+
/** The point under the pointer, drawn as a dashed preview to the last point. */
|
|
2045
|
+
readonly hover?: LatLng;
|
|
2046
|
+
readonly testId?: string;
|
|
2047
|
+
}
|
|
2048
|
+
|
|
2049
|
+
/**
|
|
2050
|
+
* The measure toolbar: a Distance or Area switch, the running total, buttons
|
|
2051
|
+
* to add a point at the map centre, undo and clear, and Done. It sits in a
|
|
2052
|
+
* landmark named "Measurement", so it is inside a landmark wherever the host
|
|
2053
|
+
* places it.
|
|
2054
|
+
*
|
|
2055
|
+
* On mount focus moves to its first button, because the person has just
|
|
2056
|
+
* chosen Measure and the next thing to do is here. The bottom-centre slot it
|
|
2057
|
+
* sits in is what the slots below it ride above.
|
|
2058
|
+
* @remarks The total is plain text. It is read out by the announcer after the
|
|
2059
|
+
* points settle (see `useMeasure`), not by a live region of its own.
|
|
2060
|
+
* The controls are all reachable with Tab rather than a single roving tab
|
|
2061
|
+
* stop, which keeps the mode switch's own arrow keys unambiguous.
|
|
2062
|
+
* The published edge is `getBoundingClientRect().top`, in viewport pixels,
|
|
2063
|
+
* which equals the chrome container's own coordinates when the container
|
|
2064
|
+
* fills the viewport.
|
|
2065
|
+
*/
|
|
2066
|
+
export declare function MeasureToolbar({ measure, onAddPointAtCentre, onDone, }: MeasureToolbarProps): JSX.Element;
|
|
2067
|
+
|
|
2068
|
+
/** Props for {@link MeasureToolbar}. */
|
|
2069
|
+
export declare interface MeasureToolbarProps {
|
|
2070
|
+
/** The measurement state from `useMeasure`. */
|
|
2071
|
+
readonly measure: UseMeasure;
|
|
2072
|
+
/** Called by "Add point at map centre", the keyboard and single-tap way to place a point. */
|
|
2073
|
+
readonly onAddPointAtCentre: () => void;
|
|
2074
|
+
/** Called by "Done". */
|
|
2075
|
+
readonly onDone: () => void;
|
|
2076
|
+
}
|
|
2077
|
+
|
|
2078
|
+
/**
|
|
2079
|
+
* The smallest radius drawn, so a very precise fix still shows a circle.
|
|
2080
|
+
*
|
|
2081
|
+
* @internal
|
|
2082
|
+
*/
|
|
2083
|
+
export declare const MIN_ACCURACY_RADIUS_PX = 8;
|
|
2084
|
+
|
|
2085
|
+
/**
|
|
2086
|
+
* The fewest characters (after trimming) that a submitted search needs.
|
|
2087
|
+
*
|
|
2088
|
+
* @internal
|
|
2089
|
+
*/
|
|
2090
|
+
export declare const MIN_SEARCH_LENGTH = 2;
|
|
2091
|
+
|
|
2092
|
+
/** The fewest characters (after trimming) that suggestions are asked for. */
|
|
2093
|
+
export declare const MIN_SUGGEST_LENGTH = 3;
|
|
2094
|
+
|
|
2095
|
+
/**
|
|
2096
|
+
* The level one below `level`, stopping at 6.
|
|
2097
|
+
*
|
|
2098
|
+
* @internal
|
|
2099
|
+
*/
|
|
2100
|
+
export declare function nextHeadingLevel(level: HeadingLevel): HeadingLevel;
|
|
2101
|
+
|
|
2102
|
+
/** The part of the map port an overlay needs to place and hide its marks. */
|
|
2103
|
+
export declare type OverlayMap = Pick<MapAdapter, "project" | "isVisible">;
|
|
2104
|
+
|
|
2105
|
+
/**
|
|
2106
|
+
* The hex value of a palette slot. Definitions name slots, `@mapcairn/theme`
|
|
2107
|
+
* holds the values, and the definition schema only accepts slots that exist,
|
|
2108
|
+
* so a missing value is a wiring bug.
|
|
2109
|
+
*
|
|
2110
|
+
* @internal
|
|
2111
|
+
*/
|
|
2112
|
+
export declare function paletteColour(slot: PaletteSlot): string;
|
|
2113
|
+
|
|
2114
|
+
/**
|
|
2115
|
+
* The content of the pin surface: a heading, the coordinates as selectable
|
|
2116
|
+
* text, "Copy coordinates" and "Clear pin" buttons, and an address lookup
|
|
2117
|
+
* that the user starts.
|
|
2118
|
+
*
|
|
2119
|
+
* The lookup sends the pin's position, rounded to about 11 m, to a third
|
|
2120
|
+
* party, so nothing is sent until "Look up address" is pressed. While it
|
|
2121
|
+
* runs the button is busy; the address, "No address found here." or an error
|
|
2122
|
+
* with "Try again" follows, and the announcer says the same. Moving the pin
|
|
2123
|
+
* puts the card back to not looked up.
|
|
2124
|
+
*
|
|
2125
|
+
* The card has no position or surface of its own; the sheet or peek that
|
|
2126
|
+
* holds it provides both. Copying shows "Copied" or "Could not copy" inline
|
|
2127
|
+
* with an icon, and the announcer says the same, so neither relies on colour
|
|
2128
|
+
* or on sight alone.
|
|
2129
|
+
*/
|
|
2130
|
+
export declare function PinCard({ position, onClear, onClose, headingLevel, headingRef, lookupNote, }: PinCardProps): JSX.Element;
|
|
2131
|
+
|
|
2132
|
+
/** Props for {@link PinCard}. */
|
|
2133
|
+
export declare interface PinCardProps {
|
|
2134
|
+
/** Where the pin is. */
|
|
2135
|
+
readonly position: LatLng;
|
|
2136
|
+
/** Called when the user chooses "Clear pin". */
|
|
2137
|
+
readonly onClear: () => void;
|
|
2138
|
+
/** When given, a close button is shown that calls it. */
|
|
2139
|
+
readonly onClose?: () => void;
|
|
2140
|
+
/** The level of the "Dropped pin" heading, so it fits the host's outline. Defaults to 2. */
|
|
2141
|
+
readonly headingLevel?: 2 | 3 | 4;
|
|
2142
|
+
/**
|
|
2143
|
+
* Receives the heading element, which takes focus by script (`tabIndex`
|
|
2144
|
+
* -1), so the sheet that opens the card can move focus to it.
|
|
2145
|
+
*/
|
|
2146
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
2147
|
+
/**
|
|
2148
|
+
* What the address lookup sends and to whom, shown under the "Look up
|
|
2149
|
+
* address" button, which it describes. Defaults to the catalogue's
|
|
2150
|
+
* `tools.pin.lookupNote`, which does not name the service because the SDK
|
|
2151
|
+
* does not know which one a host uses. A host names its search provider
|
|
2152
|
+
* here. Phrasing content only: it sits inside a paragraph.
|
|
2153
|
+
*/
|
|
2154
|
+
readonly lookupNote?: ReactNode;
|
|
2155
|
+
}
|
|
2156
|
+
|
|
2157
|
+
/**
|
|
2158
|
+
* A dropped pin, drawn in the overlay layer and re-projected whenever the view
|
|
2159
|
+
* changes. It is not drawn while it is on the far side of a globe, and on a
|
|
2160
|
+
* flat map it is drawn on the copy of the world nearest the view centre.
|
|
2161
|
+
* Render it inside `MapOverlayLayer`.
|
|
2162
|
+
*/
|
|
2163
|
+
export declare function PinMarker({ position, testId }: PinMarkerProps): JSX.Element | null;
|
|
2164
|
+
|
|
2165
|
+
/** Props for {@link PinMarker}. */
|
|
2166
|
+
export declare interface PinMarkerProps {
|
|
2167
|
+
/** Where the pin's tip points. */
|
|
2168
|
+
readonly position: LatLng;
|
|
2169
|
+
readonly testId?: string;
|
|
2170
|
+
}
|
|
2171
|
+
|
|
2172
|
+
/**
|
|
2173
|
+
* The pin: a button that drops a pin at the centre of the map, which is the
|
|
2174
|
+
* button equivalent of a long press and of the P key, and a note while a pin
|
|
2175
|
+
* is on the map. The pin's details are the caller's `children`.
|
|
2176
|
+
*/
|
|
2177
|
+
export declare function PinSection({ hasPin, onDropPin, children, headingLevel, headingRef, }: PinSectionProps): JSX.Element;
|
|
2178
|
+
|
|
2179
|
+
/** Props for {@link PinSection}. */
|
|
2180
|
+
export declare interface PinSectionProps {
|
|
2181
|
+
/** Whether a pin is on the map. */
|
|
2182
|
+
readonly hasPin: boolean;
|
|
2183
|
+
/** Drops a pin at the centre of the map. */
|
|
2184
|
+
readonly onDropPin: () => void;
|
|
2185
|
+
/** The pin's details, such as the pin card, shown under the note. */
|
|
2186
|
+
readonly children?: ReactNode;
|
|
2187
|
+
/** The heading level. Defaults to 3, below the sheet's h2 title. */
|
|
2188
|
+
readonly headingLevel?: HeadingLevel;
|
|
2189
|
+
/** Receives the heading, so the sheet can focus it. */
|
|
2190
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
2191
|
+
}
|
|
2192
|
+
|
|
2193
|
+
/**
|
|
2194
|
+
* The detent a bottom sheet rests at when a feature is shown, so its card and
|
|
2195
|
+
* the map share the screen. The host raises or lowers the sheet to it after
|
|
2196
|
+
* "Show on map" and after a tap on a point.
|
|
2197
|
+
*/
|
|
2198
|
+
export declare const REVEAL_DETENT: SheetDetent;
|
|
2199
|
+
|
|
2200
|
+
/** What {@link useReverseAddress} returns. */
|
|
2201
|
+
export declare interface ReverseAddress {
|
|
2202
|
+
/** Where the lookup stands. It is `idle` until `lookUp` is called. */
|
|
2203
|
+
readonly state: AddressState;
|
|
2204
|
+
/**
|
|
2205
|
+
* Sends the position, rounded to about 11 m, to the search provider.
|
|
2206
|
+
* Calling it again aborts a lookup still in flight and starts a new one.
|
|
2207
|
+
*/
|
|
2208
|
+
readonly lookUp: () => void;
|
|
2209
|
+
}
|
|
2210
|
+
|
|
2211
|
+
/**
|
|
2212
|
+
* Map ids of what directions draws. Definition ids cannot contain a colon, so they never meet a layer's.
|
|
2213
|
+
*
|
|
2214
|
+
* @internal
|
|
2215
|
+
*/
|
|
2216
|
+
export declare const ROUTE_CASING_LAYER_ID = ":route-casing";
|
|
2217
|
+
|
|
2218
|
+
/**
|
|
2219
|
+
* Map id of the route line.
|
|
2220
|
+
*
|
|
2221
|
+
* @internal
|
|
2222
|
+
*/
|
|
2223
|
+
export declare const ROUTE_LAYER_ID = ":route";
|
|
2224
|
+
|
|
2225
|
+
/** A route that is on the map. */
|
|
2226
|
+
export declare interface RouteOutcome {
|
|
2227
|
+
readonly kind: "route";
|
|
2228
|
+
readonly mode: TravelMode;
|
|
2229
|
+
/** The stops it was found for, in order. */
|
|
2230
|
+
readonly stops: readonly DirectionStop[];
|
|
2231
|
+
/** One line for each pair of consecutive stops. */
|
|
2232
|
+
readonly legs: readonly RouteLeg[];
|
|
2233
|
+
/** The whole route's length, in metres. */
|
|
2234
|
+
readonly distance: number;
|
|
2235
|
+
/** The whole route's travel time, in seconds. */
|
|
2236
|
+
readonly duration: number;
|
|
2237
|
+
}
|
|
2238
|
+
|
|
2239
|
+
/** How long the scale bar stays after the zoom last changed before it fades. */
|
|
2240
|
+
export declare const SCALE_BAR_IDLE_MS = 2000;
|
|
2241
|
+
|
|
2242
|
+
/**
|
|
2243
|
+
* The widest the scale bar may be, in CSS pixels.
|
|
2244
|
+
*
|
|
2245
|
+
* @internal
|
|
2246
|
+
*/
|
|
2247
|
+
export declare const SCALE_BAR_MAX_WIDTH_PX = 96;
|
|
2248
|
+
|
|
2249
|
+
/**
|
|
2250
|
+
* A scale bar drawn straight on the map: a thin line with end ticks and a
|
|
2251
|
+
* haloed label, re-computed whenever the view changes.
|
|
2252
|
+
*
|
|
2253
|
+
* @remarks It is an image named with the spoken scale ("Scale: 200 metres").
|
|
2254
|
+
* It fades about two seconds after the zoom last changed and comes back on
|
|
2255
|
+
* the next zoom, but never while the map has keyboard focus or the user
|
|
2256
|
+
* asked for reduced motion. Its width changes through a CSS custom property
|
|
2257
|
+
* and a transform, set with CSSOM so no `style` attribute is rendered.
|
|
2258
|
+
* Reads the map with `useMap()`, so it must sit inside the map context.
|
|
2259
|
+
*/
|
|
2260
|
+
export declare function ScaleBar({ units }: ScaleBarProps): JSX.Element | null;
|
|
2261
|
+
|
|
2262
|
+
/** Props for {@link ScaleBar}. */
|
|
2263
|
+
export declare interface ScaleBarProps {
|
|
2264
|
+
readonly units: UnitSystem;
|
|
2265
|
+
}
|
|
2266
|
+
|
|
2267
|
+
/**
|
|
2268
|
+
* The floating search pill: a 48px pill holding an ARIA 1.2 combobox and a
|
|
2269
|
+
* Search button, with the results in a listbox just below it. It must be
|
|
2270
|
+
* rendered inside a `FocusRegistryProvider`, which it tells where the input is
|
|
2271
|
+
* so that closing the search surface can return focus to it.
|
|
2272
|
+
*
|
|
2273
|
+
* The geocoder searches only on submit (Enter, or the Search button), never
|
|
2274
|
+
* as the user types, because the OpenStreetMap Foundation's Nominatim policy
|
|
2275
|
+
* forbids client-side autocomplete. Editing the text hides any results for
|
|
2276
|
+
* the old text. When the host supplies a suggestion provider, the listbox also
|
|
2277
|
+
* holds suggestions for the text as it is typed (see {@link useSuggestions}):
|
|
2278
|
+
* they are the same options with the same keys, picking one goes straight to
|
|
2279
|
+
* its place with no second lookup, and Enter with none highlighted still
|
|
2280
|
+
* submits the text to the geocoder. When the provider is missing or failing,
|
|
2281
|
+
* typing shows nothing and Enter works as it always did.
|
|
2282
|
+
*
|
|
2283
|
+
* Keyboard, following the WAI-ARIA Authoring Practices "list" combobox, with
|
|
2284
|
+
* the listbox filled by suggestions or by a submitted search:
|
|
2285
|
+
* - Results never take focus: the input keeps focus and
|
|
2286
|
+
* `aria-activedescendant` names the active option.
|
|
2287
|
+
* - ArrowDown and ArrowUp move the active option, wrapping at the ends, and
|
|
2288
|
+
* open a closed list that has something to show. They are the only keys
|
|
2289
|
+
* that move between options.
|
|
2290
|
+
* - Home and End are left to the browser, so they move the caret as in any
|
|
2291
|
+
* text field. When an option is active they also hand visual focus back to
|
|
2292
|
+
* the text box (the active option is cleared), as the pattern describes.
|
|
2293
|
+
* - Enter selects the active option. With no active option it submits the
|
|
2294
|
+
* text, or reopens the list when it already holds that text's results.
|
|
2295
|
+
* - Escape closes the list. With the list already closed, a second Escape
|
|
2296
|
+
* clears the text, and a third reaches the page (closing the surface).
|
|
2297
|
+
*
|
|
2298
|
+
* Selecting a result or a suggestion fills the box with its label without
|
|
2299
|
+
* searching again, and suggests nothing more for that label.
|
|
2300
|
+
* @remarks The panel is in normal flow below the pill; the chrome slot that
|
|
2301
|
+
* holds this component decides where both sit. Text states in the panel
|
|
2302
|
+
* ("Searching...", "Nothing matched that search.", the unavailable message)
|
|
2303
|
+
* carry no live-region role, because the announcer speaks the outcome.
|
|
2304
|
+
*/
|
|
2305
|
+
export declare function SearchPill({ onSelect, getBias, onFocus, onBlur, }: SearchPillProps): JSX.Element;
|
|
2306
|
+
|
|
2307
|
+
/** Props for {@link SearchPill}. */
|
|
2308
|
+
export declare interface SearchPillProps {
|
|
2309
|
+
/** Called when the user picks a result, by click, tap or Enter. */
|
|
2310
|
+
readonly onSelect: (result: SearchResult) => void;
|
|
2311
|
+
/**
|
|
2312
|
+
* Returns the box to favour results inside, usually the visible map. Read
|
|
2313
|
+
* once when each search is submitted. Optional, and passed to
|
|
2314
|
+
* {@link useSearch}, whose note on what a bias sends applies.
|
|
2315
|
+
*/
|
|
2316
|
+
readonly getBias?: () => Bounds | undefined;
|
|
2317
|
+
/** Passed through from the input, for example to open the search surface. */
|
|
2318
|
+
readonly onFocus?: FocusEventHandler<HTMLInputElement>;
|
|
2319
|
+
/** Passed through from the input, for example to close the search surface. */
|
|
2320
|
+
readonly onBlur?: FocusEventHandler<HTMLInputElement>;
|
|
2321
|
+
}
|
|
2322
|
+
|
|
2323
|
+
/**
|
|
2324
|
+
* The search pill as a decorative stand-in for the server-rendered
|
|
2325
|
+
* `ChromeSkeleton`: the same wrapper, pill and input classes as
|
|
2326
|
+
* {@link SearchPill}, so it fills the same box, with nothing wired up.
|
|
2327
|
+
*
|
|
2328
|
+
* @remarks Only ever rendered inside an `aria-hidden`, `inert` container. It
|
|
2329
|
+
* uses no hooks and needs no provider: its words arrive as `copy`. The Search button is disabled, as the
|
|
2330
|
+
* real one is while the box is empty.
|
|
2331
|
+
*/
|
|
2332
|
+
export declare function SearchPillSkeleton({ copy }: SearchPillSkeletonProps): JSX.Element;
|
|
2333
|
+
|
|
2334
|
+
/** The words of {@link SearchPillSkeleton}, in the host's default language. */
|
|
2335
|
+
export declare interface SearchPillSkeletonCopy {
|
|
2336
|
+
/** The input's placeholder, as the live pill's. */
|
|
2337
|
+
readonly placeholder: string;
|
|
2338
|
+
/** The Search button's name. */
|
|
2339
|
+
readonly searchLabel: string;
|
|
2340
|
+
}
|
|
2341
|
+
|
|
2342
|
+
/** Props for {@link SearchPillSkeleton}. */
|
|
2343
|
+
export declare interface SearchPillSkeletonProps {
|
|
2344
|
+
readonly copy: SearchPillSkeletonCopy;
|
|
2345
|
+
}
|
|
2346
|
+
|
|
2347
|
+
/** Where a search stands. Exactly one of these is true at a time. */
|
|
2348
|
+
export declare type SearchState = {
|
|
2349
|
+
readonly status: "idle";
|
|
2350
|
+
} | {
|
|
2351
|
+
readonly status: "loading";
|
|
2352
|
+
} | {
|
|
2353
|
+
readonly status: "results";
|
|
2354
|
+
readonly results: readonly SearchResult[];
|
|
2355
|
+
} | {
|
|
2356
|
+
readonly status: "empty";
|
|
2357
|
+
} | {
|
|
2358
|
+
readonly status: "error";
|
|
2359
|
+
readonly kind: SearchErrorKind;
|
|
2360
|
+
};
|
|
2361
|
+
|
|
2362
|
+
/**
|
|
2363
|
+
* A titled block of the sheet: a `section` named by a real heading. All the
|
|
2364
|
+
* sheet's sections use it, so headings, spacing and naming stay uniform.
|
|
2365
|
+
*/
|
|
2366
|
+
export declare function Section({ title, headingLevel, headingRef, className, children, ...rest }: SectionProps): JSX.Element;
|
|
2367
|
+
|
|
2368
|
+
/** Props for {@link Section}. */
|
|
2369
|
+
export declare interface SectionProps extends Omit<HTMLAttributes<HTMLElement>, "children" | "title"> {
|
|
2370
|
+
/** The heading text. It also names the section. */
|
|
2371
|
+
readonly title: string;
|
|
2372
|
+
/** The heading level. Defaults to 3, below the sheet's h2 title. */
|
|
2373
|
+
readonly headingLevel?: HeadingLevel;
|
|
2374
|
+
/**
|
|
2375
|
+
* Receives the heading element. The heading takes focus from script
|
|
2376
|
+
* (`tabIndex` -1), so the sheet can move focus to a section it opens on.
|
|
2377
|
+
*/
|
|
2378
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
2379
|
+
readonly children?: ReactNode;
|
|
2380
|
+
}
|
|
2381
|
+
|
|
2382
|
+
/**
|
|
2383
|
+
* A single-choice control that shows all options at once, built on the Radix
|
|
2384
|
+
* ToggleGroup in single mode.
|
|
2385
|
+
*
|
|
2386
|
+
* Radix renders the group as a `radiogroup` and each item as a `radio`, which
|
|
2387
|
+
* is the right semantics for a mutually exclusive choice. Focus moves between
|
|
2388
|
+
* items with the arrow keys (one tab stop for the whole group) and Space or
|
|
2389
|
+
* Enter chooses the focused item.
|
|
2390
|
+
*
|
|
2391
|
+
* Unlike a raw toggle group, the selection can never be cleared: pressing the
|
|
2392
|
+
* active item again is ignored. The selected item is filled and shows a check
|
|
2393
|
+
* mark, so selection never relies on colour alone.
|
|
2394
|
+
*/
|
|
2395
|
+
export declare function SegmentedControl({ label, options, value, onValueChange, disabled, className, "data-testid": testId, }: SegmentedControlProps): JSX.Element;
|
|
2396
|
+
|
|
2397
|
+
/** One choice in a {@link SegmentedControl}. */
|
|
2398
|
+
export declare interface SegmentedControlOption {
|
|
2399
|
+
/** The value reported through `onValueChange` when this item is chosen. */
|
|
2400
|
+
readonly value: string;
|
|
2401
|
+
/** The visible text, which is also the item's accessible name. */
|
|
2402
|
+
readonly label: string;
|
|
2403
|
+
/** Optional decorative icon shown before the label. It is hidden from assistive technology. */
|
|
2404
|
+
readonly icon?: ReactNode;
|
|
2405
|
+
/**
|
|
2406
|
+
* The BCP 47 language the label is written in, when it differs from the
|
|
2407
|
+
* page's, so assistive technology reads it in that language.
|
|
2408
|
+
*/
|
|
2409
|
+
readonly lang?: string;
|
|
2410
|
+
}
|
|
2411
|
+
|
|
2412
|
+
/** Props for {@link SegmentedControl}. */
|
|
2413
|
+
export declare interface SegmentedControlProps {
|
|
2414
|
+
/** Accessible name of the group, for example "Theme". Required. */
|
|
2415
|
+
readonly label: string;
|
|
2416
|
+
/** The choices, in display order. */
|
|
2417
|
+
readonly options: readonly SegmentedControlOption[];
|
|
2418
|
+
/** The selected value. The component is controlled and always has a selection. */
|
|
2419
|
+
readonly value: string;
|
|
2420
|
+
/** Called with the new value when the user picks a different item. */
|
|
2421
|
+
readonly onValueChange: (value: string) => void;
|
|
2422
|
+
/** Stops every item from being chosen and dims the group. */
|
|
2423
|
+
readonly disabled?: boolean;
|
|
2424
|
+
/** Applied to the group element. */
|
|
2425
|
+
readonly className?: string;
|
|
2426
|
+
/** Applied to the group. Each item gets the same id plus `-` and its value. */
|
|
2427
|
+
readonly "data-testid"?: string;
|
|
2428
|
+
}
|
|
2429
|
+
|
|
2430
|
+
/** One selected reference, resolved against the layers as they are now. */
|
|
2431
|
+
export declare type SelectedEntry = ShownSelection | HiddenSelection;
|
|
2432
|
+
|
|
2433
|
+
/** The feature whose card is open, with its layer. */
|
|
2434
|
+
export declare interface SelectedFeature {
|
|
2435
|
+
readonly layer: DataLayerState;
|
|
2436
|
+
readonly feature: LayerFeature;
|
|
2437
|
+
}
|
|
2438
|
+
|
|
2439
|
+
/**
|
|
2440
|
+
* A ring around the point whose card is open, so the card and the map agree on which
|
|
2441
|
+
* one it is. Render it inside `MapOverlayLayer`; like every overlay it is a
|
|
2442
|
+
* picture of state the card already gives in words.
|
|
2443
|
+
*/
|
|
2444
|
+
export declare function SelectionMarker({ layers }: SelectionMarkerProps): JSX.Element | null;
|
|
2445
|
+
|
|
2446
|
+
/** Props for {@link SelectionMarker}. */
|
|
2447
|
+
export declare interface SelectionMarkerProps {
|
|
2448
|
+
readonly layers: DataLayers;
|
|
2449
|
+
}
|
|
2450
|
+
|
|
2451
|
+
/**
|
|
2452
|
+
* Hands the selected set down to the components that show or change it, so
|
|
2453
|
+
* none needs a prop for it. Put it where the host calls `useFeatureSelection`,
|
|
2454
|
+
* around the map and the sheet. With `selection` null it provides nothing, so
|
|
2455
|
+
* a host with no store passes the hook's result as it is.
|
|
2456
|
+
*/
|
|
2457
|
+
export declare function SelectionProvider({ selection, children, }: SelectionProviderProps): JSX.Element;
|
|
2458
|
+
|
|
2459
|
+
/** Props for {@link SelectionProvider}. */
|
|
2460
|
+
export declare interface SelectionProviderProps {
|
|
2461
|
+
/** What {@link useFeatureSelection} returned: null when the host has no store. */
|
|
2462
|
+
readonly selection: FeatureSelectionState | null;
|
|
2463
|
+
readonly children?: ReactNode;
|
|
2464
|
+
}
|
|
2465
|
+
|
|
2466
|
+
/**
|
|
2467
|
+
* Makes the app's services available to every component below it. This is the
|
|
2468
|
+
* only way components reach adapters, browser services or map engines, so tests
|
|
2469
|
+
* can swap in fakes by wrapping a tree in this provider. It also keeps which
|
|
2470
|
+
* basemaps are not working (see `useBasemapAvailability`) and the active
|
|
2471
|
+
* message catalogue (see `useMessages`).
|
|
2472
|
+
*/
|
|
2473
|
+
export declare function ServicesProvider({ services, children, }: ServicesProviderProps): JSX.Element;
|
|
2474
|
+
|
|
2475
|
+
/** Props for {@link ServicesProvider}. */
|
|
2476
|
+
export declare interface ServicesProviderProps {
|
|
2477
|
+
/** Built once by the composition root, or by `createFakeServices` in tests. */
|
|
2478
|
+
readonly services: Services;
|
|
2479
|
+
readonly children: ReactNode;
|
|
2480
|
+
}
|
|
2481
|
+
|
|
2482
|
+
/**
|
|
2483
|
+
* The settings: theme, units, map shape (flat or globe), language (only when
|
|
2484
|
+
* the host offers more than one; see {@link LanguageField}), zoom buttons and
|
|
2485
|
+
* Save data, a note when changes will not be remembered, and a short privacy
|
|
2486
|
+
* statement (the host's, or the catalogue's `settings.privacy.default`) with a
|
|
2487
|
+
* link to the policy.
|
|
2488
|
+
* @remarks The zoom switch shows the stored choice, or the device default
|
|
2489
|
+
* (on with a mouse, off on touch) while nothing is stored. Toggling it stores
|
|
2490
|
+
* an explicit boolean, so a person who turns it on keeps it on everywhere.
|
|
2491
|
+
* The Save data switch works the same way: its default is the device's
|
|
2492
|
+
* signal (a data saver or a very slow connection, where the browser reports
|
|
2493
|
+
* one), and a person's own choice always wins.
|
|
2494
|
+
*/
|
|
2495
|
+
export declare function SettingsSection({ headingLevel, privacyHref, privacyNote, headingRef, }: SettingsSectionProps): JSX.Element;
|
|
2496
|
+
|
|
2497
|
+
/** Props for {@link SettingsSection}. */
|
|
2498
|
+
export declare interface SettingsSectionProps {
|
|
2499
|
+
/** The heading level. Defaults to 3, below the sheet's h2 title. */
|
|
2500
|
+
readonly headingLevel?: HeadingLevel;
|
|
2501
|
+
/** Where the privacy policy is. Defaults to `/privacy`. */
|
|
2502
|
+
readonly privacyHref?: string;
|
|
2503
|
+
/**
|
|
2504
|
+
* The host's privacy statement, shown under the Privacy heading. Defaults to
|
|
2505
|
+
* the catalogue's `settings.privacy.default`, which names no provider because
|
|
2506
|
+
* the SDK does not know which services a host uses. A host names its own
|
|
2507
|
+
* providers here and says what it sends to each. `null` or an empty string
|
|
2508
|
+
* shows no statement. Phrasing content only: it sits inside a paragraph.
|
|
2509
|
+
*/
|
|
2510
|
+
readonly privacyNote?: ReactNode;
|
|
2511
|
+
/** Receives the heading, so the sheet can focus it. */
|
|
2512
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
2513
|
+
}
|
|
2514
|
+
|
|
2515
|
+
/**
|
|
2516
|
+
* The shapes the person has drawn: a list where each row selects a shape (so
|
|
2517
|
+
* it can be edited with the keyboard from the draw tool), buttons to delete
|
|
2518
|
+
* the selected shape or all of them, an import from a GeoJSON, CSV or WKT file
|
|
2519
|
+
* (when the host supplies a file opener),
|
|
2520
|
+
* and the export buttons. Shapes are saved to a file or into a link only when
|
|
2521
|
+
* a button is pressed, a file is read only on this device, and the note says
|
|
2522
|
+
* so. The map fits to what an import added.
|
|
2523
|
+
*/
|
|
2524
|
+
export declare function ShapesSection({ draw, headingLevel, headingRef, }: ShapesSectionProps): JSX.Element;
|
|
2525
|
+
|
|
2526
|
+
/** Props for {@link ShapesSection}. */
|
|
2527
|
+
export declare interface ShapesSectionProps {
|
|
2528
|
+
/** The drawing state from `useDraw`. */
|
|
2529
|
+
readonly draw: UseDraw;
|
|
2530
|
+
/** The heading level. Defaults to 3, below the sheet's h2 title. */
|
|
2531
|
+
readonly headingLevel?: HeadingLevel;
|
|
2532
|
+
/** Receives the heading, so the sheet can focus it. */
|
|
2533
|
+
readonly headingRef?: Ref<HTMLHeadingElement>;
|
|
2534
|
+
}
|
|
2535
|
+
|
|
2536
|
+
/**
|
|
2537
|
+
* The map options surface: a bottom sheet with peek, half and full detents on
|
|
2538
|
+
* narrow screens, and a floating side panel in the panel layout. Rendered by
|
|
2539
|
+
* the app into `MapChrome`'s `sheet` slot, outside the inert wrapper.
|
|
2540
|
+
*
|
|
2541
|
+
* @remarks
|
|
2542
|
+
* Sheet layout: a `dialog` labelled by its heading. It is non-modal at peek
|
|
2543
|
+
* and half, so the map stays usable. At full it sets `aria-modal`, reports
|
|
2544
|
+
* `onModalChange(true)` (the app makes the rest of the chrome inert) and
|
|
2545
|
+
* loops Tab inside itself. Safari's default Tab skips links and buttons, so
|
|
2546
|
+
* the keydown loop cannot see focus reach the last control there; at full
|
|
2547
|
+
* the sheet also has an empty focus sentinel at each end, and the browser's
|
|
2548
|
+
* own Tab landing on one sends focus round to the other end. The handle is a "Resize panel" button: Enter or
|
|
2549
|
+
* Space cycles detents, the arrow keys step them, and the handle and header
|
|
2550
|
+
* can be dragged, with rubber-banding past the ends and a velocity-aware
|
|
2551
|
+
* snap on release. Detent changes are announced. The top edge and detent are
|
|
2552
|
+
* published for the bottom slots, once per animation frame while dragging.
|
|
2553
|
+
*
|
|
2554
|
+
* Panel layout: a `complementary` region labelled by its heading, never
|
|
2555
|
+
* modal, with no handle. It publishes its right edge so bottom-start can move
|
|
2556
|
+
* clear of it.
|
|
2557
|
+
*
|
|
2558
|
+
* Both: focus moves to the heading on open; Escape and Close call `onClose`;
|
|
2559
|
+
* `restoreFocus` runs after closing. One element serves both layouts (its
|
|
2560
|
+
* role and `data-layout` change) so content stays mounted across a rotation.
|
|
2561
|
+
* The detent heights take no bottom safe-area inset; the content pads for it.
|
|
2562
|
+
*/
|
|
2563
|
+
export declare function Sheet({ id, open, title, onClose, detent, onDetentChange, onModalChange, restoreFocus, testId, brand, children, }: SheetProps): JSX.Element;
|
|
2564
|
+
|
|
2565
|
+
/**
|
|
2566
|
+
* Everything inside the sheet, under its own h2 title, each part a `section`
|
|
2567
|
+
* named by an h3. For the `settings` and `help` sections that is Settings
|
|
2568
|
+
* and Help. Otherwise it is Basemap, Pin, Layers (only when the host has
|
|
2569
|
+
* layers or a catalogue that loads), Shapes (only when the host offers drawing) and Save image.
|
|
2570
|
+
*/
|
|
2571
|
+
export declare function SheetContent({ basemapId, onBasemapChange, hasPin, onDropPin, section, pinCard, layers, draw, onShowOnMap, showTurnOffAll, intro, imageCredits, privacyHref, privacyNote, onStartTour, about, }: SheetContentProps): JSX.Element;
|
|
2572
|
+
|
|
2573
|
+
/** Props for {@link SheetContent}. */
|
|
2574
|
+
export declare interface SheetContentProps {
|
|
2575
|
+
/** The chosen basemap id. */
|
|
2576
|
+
readonly basemapId: string;
|
|
2577
|
+
/** Called with the basemap id the user chose. */
|
|
2578
|
+
readonly onBasemapChange: (id: string) => void;
|
|
2579
|
+
/** Whether a pin is on the map. */
|
|
2580
|
+
readonly hasPin: boolean;
|
|
2581
|
+
/** Drops a pin at the centre of the map. */
|
|
2582
|
+
readonly onDropPin: () => void;
|
|
2583
|
+
/**
|
|
2584
|
+
* The section to bring into view, which also picks what the sheet holds:
|
|
2585
|
+
* Settings and Help for `settings` and `help`, and Basemap, Pin, Layers,
|
|
2586
|
+
* Shapes and Save image for any other section or none. When it changes, the
|
|
2587
|
+
* section scrolls to the top of the sheet and its heading takes focus.
|
|
2588
|
+
* Choosing the same section again while this component stays mounted does
|
|
2589
|
+
* nothing, so the caller should unmount the content when the sheet closes.
|
|
2590
|
+
*/
|
|
2591
|
+
readonly section?: SheetSection;
|
|
2592
|
+
/** The pin's details, shown inside the Pin section. */
|
|
2593
|
+
readonly pinCard?: ReactNode;
|
|
2594
|
+
/**
|
|
2595
|
+
* The data layers, from `useDataLayers`. Without it, or for a host whose
|
|
2596
|
+
* catalogue was ready with no layers at mount, there is no Layers section;
|
|
2597
|
+
* a catalogue that loads shows its state there (loading, failed, empty).
|
|
2598
|
+
*/
|
|
2599
|
+
readonly layers?: DataLayers;
|
|
2600
|
+
/**
|
|
2601
|
+
* The drawing, from `useDraw`. Without it there is no Shapes section.
|
|
2602
|
+
*/
|
|
2603
|
+
readonly draw?: UseDraw;
|
|
2604
|
+
/** Called after "Show on map" in the Layers section, so the host can make room for the map. */
|
|
2605
|
+
readonly onShowOnMap?: () => void;
|
|
2606
|
+
/** Whether the Layers section offers "Turn off all layers" and the Undo after it. Defaults to true. */
|
|
2607
|
+
readonly showTurnOffAll?: boolean;
|
|
2608
|
+
/** The line above the layers, in place of "Open data from public providers", for a host whose layers are not that. */
|
|
2609
|
+
readonly intro?: string;
|
|
2610
|
+
/** The credits drawn into a saved map image (see `creditsLine`). */
|
|
2611
|
+
readonly imageCredits?: string;
|
|
2612
|
+
/** Where the privacy policy is. Defaults to `/privacy`. */
|
|
2613
|
+
readonly privacyHref?: string;
|
|
2614
|
+
/** The host's privacy statement for Settings, shown in place of the default. */
|
|
2615
|
+
readonly privacyNote?: ReactNode;
|
|
2616
|
+
/** Starts the first-visit tour from Help. Without it Help offers no tour. */
|
|
2617
|
+
readonly onStartTour?: () => void;
|
|
2618
|
+
/**
|
|
2619
|
+
* The host's About block for Help. Without it Help has none. Its link
|
|
2620
|
+
* address must be a trusted http or https one that the host supplies.
|
|
2621
|
+
*/
|
|
2622
|
+
readonly about?: HelpAbout;
|
|
2623
|
+
}
|
|
2624
|
+
|
|
2625
|
+
/** Props for {@link Sheet}. */
|
|
2626
|
+
export declare interface SheetProps {
|
|
2627
|
+
/** The element id, for `aria-controls` on the control that opens it. */
|
|
2628
|
+
readonly id: string;
|
|
2629
|
+
readonly open: boolean;
|
|
2630
|
+
/** The heading text, which also names the dialog or region. */
|
|
2631
|
+
readonly title: string;
|
|
2632
|
+
/** The app's single close action (Close button and Escape). */
|
|
2633
|
+
readonly onClose: () => void;
|
|
2634
|
+
/** The current detent. Used only in the sheet layout. */
|
|
2635
|
+
readonly detent: SheetDetent;
|
|
2636
|
+
readonly onDetentChange: (detent: SheetDetent) => void;
|
|
2637
|
+
/**
|
|
2638
|
+
* Called with true while the sheet is modal (open at the full detent in the
|
|
2639
|
+
* sheet layout), and false otherwise. The app passes it on to `MapChrome`'s
|
|
2640
|
+
* `modal`, which makes everything else `inert`.
|
|
2641
|
+
*/
|
|
2642
|
+
readonly onModalChange?: (modal: boolean) => void;
|
|
2643
|
+
/** Called after the sheet closes, to put focus back where it came from. */
|
|
2644
|
+
readonly restoreFocus?: () => void;
|
|
2645
|
+
/** Sets `data-testid`. Defaults to the id. */
|
|
2646
|
+
readonly testId?: string;
|
|
2647
|
+
/**
|
|
2648
|
+
* A decorative brand (a host's mark and name) shown in a row above the
|
|
2649
|
+
* title. It is `aria-hidden`, so the title stays the accessible name; pass
|
|
2650
|
+
* nothing for no row. In the sheet layout the row is left out at the peek
|
|
2651
|
+
* detent, where there is no room for it.
|
|
2652
|
+
*/
|
|
2653
|
+
readonly brand?: ReactNode;
|
|
2654
|
+
readonly children: ReactNode;
|
|
2655
|
+
}
|
|
2656
|
+
|
|
2657
|
+
/**
|
|
2658
|
+
* The closest "Show on map" zooms out to: far enough to see the region.
|
|
2659
|
+
*
|
|
2660
|
+
* @internal
|
|
2661
|
+
*/
|
|
2662
|
+
export declare const SHOW_ON_MAP_MIN_ZOOM = 5;
|
|
2663
|
+
|
|
2664
|
+
/** A selected reference whose feature can be shown, with the definition of the layer that holds it. */
|
|
2665
|
+
export declare interface ShownSelection {
|
|
2666
|
+
readonly status: "shown";
|
|
2667
|
+
readonly ref: FeatureRef;
|
|
2668
|
+
readonly definition: LayerDefinition;
|
|
2669
|
+
readonly feature: LayerFeature;
|
|
2670
|
+
}
|
|
2671
|
+
|
|
2672
|
+
/**
|
|
2673
|
+
* The first focusable element on the page. It is visually hidden (with the
|
|
2674
|
+
* shared `visuallyHidden` class) until it receives focus, then shows with the
|
|
2675
|
+
* focus ring. Activating it moves focus to the
|
|
2676
|
+
* target, which must be focusable (for example a region with `tabIndex={-1}`).
|
|
2677
|
+
* @remarks The native hash jump is only prevented when the target exists, so
|
|
2678
|
+
* the link still works as an ordinary anchor if the target is missing.
|
|
2679
|
+
*/
|
|
2680
|
+
export declare function SkipLink({ targetId, children, className, onClick, ...rest }: SkipLinkProps): JSX.Element;
|
|
2681
|
+
|
|
2682
|
+
/** Props for {@link SkipLink}. */
|
|
2683
|
+
export declare interface SkipLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children" | "href"> {
|
|
2684
|
+
/** The id of the element to move focus to. It must be focusable. */
|
|
2685
|
+
readonly targetId: string;
|
|
2686
|
+
/** The link text. Defaults to the catalogue's "ui.skipToMap". */
|
|
2687
|
+
readonly children?: ReactNode;
|
|
2688
|
+
}
|
|
2689
|
+
|
|
2690
|
+
/**
|
|
2691
|
+
* A single-thumb slider built on the Radix Slider primitive, with a visible
|
|
2692
|
+
* label and a visible value readout.
|
|
2693
|
+
*
|
|
2694
|
+
* Radix provides the keyboard model (arrows, Home, End, PageUp and PageDown).
|
|
2695
|
+
* The thumb is a 24px circle inside a 44px hit area. The value text is also
|
|
2696
|
+
* exposed as `aria-valuetext`, so assistive technology hears the formatted
|
|
2697
|
+
* value rather than the raw number.
|
|
2698
|
+
*/
|
|
2699
|
+
export declare function Slider({ label, min, max, step, value, onValueChange, formatValue, disabled, className, "data-testid": testId, }: SliderProps): JSX.Element;
|
|
2700
|
+
|
|
2701
|
+
/** Props for {@link Slider}. */
|
|
2702
|
+
export declare interface SliderProps {
|
|
2703
|
+
/** The visible label. Required: the slider is named by it. */
|
|
2704
|
+
readonly label: string;
|
|
2705
|
+
/** Lowest value. */
|
|
2706
|
+
readonly min: number;
|
|
2707
|
+
/** Highest value. */
|
|
2708
|
+
readonly max: number;
|
|
2709
|
+
/** Distance between allowed values. Arrow keys move by one step. */
|
|
2710
|
+
readonly step: number;
|
|
2711
|
+
/** The current value. The component is controlled. */
|
|
2712
|
+
readonly value: number;
|
|
2713
|
+
/** Called with the next value as the user drags or presses keys. */
|
|
2714
|
+
readonly onValueChange: (value: number) => void;
|
|
2715
|
+
/**
|
|
2716
|
+
* Turns a value into the text shown beside the label and announced as the
|
|
2717
|
+
* slider's aria-valuetext. For example, a percentage slider returns "60%"
|
|
2718
|
+
* for 60.
|
|
2719
|
+
*/
|
|
2720
|
+
readonly formatValue: (value: number) => string;
|
|
2721
|
+
/** Stops the slider from changing and dims it. */
|
|
2722
|
+
readonly disabled?: boolean;
|
|
2723
|
+
/** Applied to the outer wrapper. */
|
|
2724
|
+
readonly className?: string;
|
|
2725
|
+
/**
|
|
2726
|
+
* Applied to the outer wrapper. The value readout gets the same id with a
|
|
2727
|
+
* `-value` suffix and the track a `-track` suffix.
|
|
2728
|
+
*/
|
|
2729
|
+
readonly "data-testid"?: string;
|
|
2730
|
+
}
|
|
2731
|
+
|
|
2732
|
+
/**
|
|
2733
|
+
* A toast or banner: an icon, text and a dismiss button, so the variant is
|
|
2734
|
+
* never conveyed by colour alone. It is the one visible live region besides
|
|
2735
|
+
* the hidden announcer: `role="status"` for info and success, `role="alert"`
|
|
2736
|
+
* for errors. The role sits on the text only, so a screen reader never reads
|
|
2737
|
+
* the Retry and Dismiss buttons as part of the message.
|
|
2738
|
+
*
|
|
2739
|
+
* When the message goes away while focus is inside it (Dismiss, or an
|
|
2740
|
+
* action that ends the condition), focus returns to the element it came from,
|
|
2741
|
+
* or to the stop a `StatusMessageFocusProvider` supplies (`MapView` supplies
|
|
2742
|
+
* its map region) when that element is gone, cannot take focus or focus came
|
|
2743
|
+
* from the page, so a keyboard person keeps their place. Without a provider
|
|
2744
|
+
* focus is left where it is. Focus is left alone if it was elsewhere.
|
|
2745
|
+
*
|
|
2746
|
+
* Errors stay until dismissed. Other messages dismiss themselves after the
|
|
2747
|
+
* delay, and the countdown pauses while the pointer is over the message or
|
|
2748
|
+
* focus is inside it, then resumes with the time left.
|
|
2749
|
+
*/
|
|
2750
|
+
export declare function StatusMessage({ variant, children, onDismiss, action, autoDismissMs, dismissLabel, className, ...rest }: StatusMessageProps): JSX.Element;
|
|
2751
|
+
|
|
2752
|
+
/**
|
|
2753
|
+
* Says where focus goes when a `StatusMessage` below it goes away and focus
|
|
2754
|
+
* cannot return to where it came from. `MapView` supplies its own map region,
|
|
2755
|
+
* so each map restores to itself; a host that renders messages without a
|
|
2756
|
+
* `MapView` can supply its own stop. Without a provider, focus is left alone.
|
|
2757
|
+
*/
|
|
2758
|
+
export declare function StatusMessageFocusProvider({ fallback, children, }: StatusMessageFocusProviderProps): JSX.Element;
|
|
2759
|
+
|
|
2760
|
+
/** Props for {@link StatusMessageFocusProvider}. */
|
|
2761
|
+
export declare interface StatusMessageFocusProviderProps {
|
|
2762
|
+
/**
|
|
2763
|
+
* Moves focus to a stable stop, such as the map region. A `StatusMessage`
|
|
2764
|
+
* below the provider calls it when it goes away with focus inside it and the
|
|
2765
|
+
* element focus came from cannot take focus. The latest function is used.
|
|
2766
|
+
*/
|
|
2767
|
+
readonly fallback: () => void;
|
|
2768
|
+
readonly children: ReactNode;
|
|
2769
|
+
}
|
|
2770
|
+
|
|
2771
|
+
/** Props for {@link StatusMessage}. */
|
|
2772
|
+
export declare interface StatusMessageProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onBlur" | "onFocus" | "onMouseEnter" | "onMouseLeave" | "role"> {
|
|
2773
|
+
/** `info` and `success` are polite status messages; `error` is an alert. */
|
|
2774
|
+
readonly variant: StatusMessageVariant;
|
|
2775
|
+
/** The message text. Keep it short and specific. */
|
|
2776
|
+
readonly children: ReactNode;
|
|
2777
|
+
/** Called when the person dismisses the message, and when it times out. */
|
|
2778
|
+
readonly onDismiss: () => void;
|
|
2779
|
+
/** An optional action, such as "Retry". It does not dismiss the message. */
|
|
2780
|
+
readonly action?: {
|
|
2781
|
+
readonly label: string;
|
|
2782
|
+
readonly onClick: () => void;
|
|
2783
|
+
};
|
|
2784
|
+
/**
|
|
2785
|
+
* How long an `info` or `success` message stays before `onDismiss` is
|
|
2786
|
+
* called. Values under 6000 are raised to 6000. Ignored for errors.
|
|
2787
|
+
* Changing it after mount has no effect; remount with a `key` instead.
|
|
2788
|
+
*/
|
|
2789
|
+
readonly autoDismissMs?: number;
|
|
2790
|
+
/** The accessible name of the dismiss button. Defaults to the catalogue's "ui.dismiss". */
|
|
2791
|
+
readonly dismissLabel?: string;
|
|
2792
|
+
}
|
|
2793
|
+
|
|
2794
|
+
/** The kind of message. Errors never dismiss themselves. */
|
|
2795
|
+
export declare type StatusMessageVariant = "info" | "success" | "error";
|
|
2796
|
+
|
|
2797
|
+
/** A heading for a group inside a section, such as Privacy or Keyboard. */
|
|
2798
|
+
export declare function Subheading({ level, children }: SubheadingProps): JSX.Element;
|
|
2799
|
+
|
|
2800
|
+
/** Props for {@link Subheading}. */
|
|
2801
|
+
export declare interface SubheadingProps {
|
|
2802
|
+
/** The level of the heading, normally one below its section's. */
|
|
2803
|
+
readonly level: HeadingLevel;
|
|
2804
|
+
readonly children: ReactNode;
|
|
2805
|
+
}
|
|
2806
|
+
|
|
2807
|
+
/** How long suggestions stay paused after repeated failures, in milliseconds. */
|
|
2808
|
+
export declare const SUGGEST_COOLDOWN_MS = 60000;
|
|
2809
|
+
|
|
2810
|
+
/** How long the text must stay unchanged before suggestions are asked for. */
|
|
2811
|
+
export declare const SUGGEST_DEBOUNCE_MS = 275;
|
|
2812
|
+
|
|
2813
|
+
/** How many requests in a row may fail before suggestions pause. */
|
|
2814
|
+
export declare const SUGGEST_FAILURE_LIMIT = 3;
|
|
2815
|
+
|
|
2816
|
+
/**
|
|
2817
|
+
* A translucent surface with backdrop blur, used by every floating control.
|
|
2818
|
+
* Floating surfaces carry a shadow rather than a visible border.
|
|
2819
|
+
* @remarks Pass `data-chrome` and `data-testid` straight through; a
|
|
2820
|
+
* `section`, `aside` or `nav` needs an accessible name from the caller.
|
|
2821
|
+
*/
|
|
2822
|
+
export declare function Surface({ as: Component, variant, radius, className, ...rest }: SurfaceProps): JSX.Element;
|
|
2823
|
+
|
|
2824
|
+
/** Props for {@link Surface}. */
|
|
2825
|
+
export declare interface SurfaceProps extends HTMLAttributes<HTMLElement> {
|
|
2826
|
+
/** The element to render. Defaults to `div`. */
|
|
2827
|
+
readonly as?: "div" | "section" | "aside" | "nav";
|
|
2828
|
+
/**
|
|
2829
|
+
* `floating` has the floating shadow, `raised` uses the raised surface
|
|
2830
|
+
* colour with no shadow, `flat` has neither. Defaults to `floating`.
|
|
2831
|
+
*/
|
|
2832
|
+
readonly variant?: "floating" | "raised" | "flat";
|
|
2833
|
+
/** Corner radius role. Defaults to `control`. */
|
|
2834
|
+
readonly radius?: "pill" | "control" | "sheet";
|
|
2835
|
+
}
|
|
2836
|
+
|
|
2837
|
+
/**
|
|
2838
|
+
* A labelled on/off switch built on the Radix Switch primitive. The label is a
|
|
2839
|
+
* real `label` element tied to the control, so clicking the text toggles it,
|
|
2840
|
+
* and the optional description is exposed through `aria-describedby`.
|
|
2841
|
+
*
|
|
2842
|
+
* The on state is shown three ways: the thumb slides, the track fills with the
|
|
2843
|
+
* accent, and the thumb carries a tick, so it never relies on colour alone.
|
|
2844
|
+
* The row is at least 48px tall, and the control itself, not only its row,
|
|
2845
|
+
* is a target at least 44px tall around the smaller visible track.
|
|
2846
|
+
*/
|
|
2847
|
+
export declare function Switch({ label, description, checked, onCheckedChange, disabled, className, "data-testid": testId, }: SwitchProps): JSX.Element;
|
|
2848
|
+
|
|
2849
|
+
/** Props for {@link Switch}. */
|
|
2850
|
+
export declare interface SwitchProps {
|
|
2851
|
+
/** The visible label. Required: a switch is never unnamed or named only by an icon. */
|
|
2852
|
+
readonly label: string;
|
|
2853
|
+
/** Optional supporting text, announced as the control's description. */
|
|
2854
|
+
readonly description?: string;
|
|
2855
|
+
/** Whether the switch is on. The component is controlled. */
|
|
2856
|
+
readonly checked: boolean;
|
|
2857
|
+
/** Called with the next state when the user toggles the switch. */
|
|
2858
|
+
readonly onCheckedChange: (checked: boolean) => void;
|
|
2859
|
+
/** Stops the switch from being toggled and dims it. */
|
|
2860
|
+
readonly disabled?: boolean;
|
|
2861
|
+
/** Applied to the row element. */
|
|
2862
|
+
readonly className?: string;
|
|
2863
|
+
/** Applied to the control. The row gets the same id with a `-row` suffix. */
|
|
2864
|
+
readonly "data-testid"?: string;
|
|
2865
|
+
}
|
|
2866
|
+
|
|
2867
|
+
/**
|
|
2868
|
+
* Turns a shape style's colour rule into the rule a vector tile engine
|
|
2869
|
+
* evaluates for each feature: categories become cases with the other class
|
|
2870
|
+
* as the fallback, and steps and equal intervals become ascending minimums.
|
|
2871
|
+
*
|
|
2872
|
+
* @internal
|
|
2873
|
+
*/
|
|
2874
|
+
export declare function toLookRule(style: FeedShapeStyle): MapLookRule;
|
|
2875
|
+
|
|
2876
|
+
/**
|
|
2877
|
+
* Works out how each point of a feed layer is drawn, so the map adapter gets
|
|
2878
|
+
* plain colours, sizes and shapes and needs no style rule.
|
|
2879
|
+
*
|
|
2880
|
+
* @internal
|
|
2881
|
+
*/
|
|
2882
|
+
export declare function toMapFeatures(style: PointStyle, features: readonly LayerFeature[]): MapFeature[];
|
|
2883
|
+
|
|
2884
|
+
/**
|
|
2885
|
+
* A heatmap of a feed or query layer's points, weighted by its weight field.
|
|
2886
|
+
*
|
|
2887
|
+
* @internal
|
|
2888
|
+
*/
|
|
2889
|
+
export declare function toMapHeatmap(definition: HeatmapLayerDefinition, features: readonly LayerFeature[], controls: ControlValues): MapHeatmap;
|
|
2890
|
+
|
|
2891
|
+
/**
|
|
2892
|
+
* The vector tile layer for the polygon and line source layers of a
|
|
2893
|
+
* definition, with each rule, window and label worked out. Heatmap source
|
|
2894
|
+
* layers are drawn separately (see {@link toVectorHeatmaps}).
|
|
2895
|
+
*
|
|
2896
|
+
* @internal
|
|
2897
|
+
*/
|
|
2898
|
+
export declare function toMapVector(definition: VectorTileLayerDefinition, controls: ControlValues, now: number): MapVectorTiles;
|
|
2899
|
+
|
|
2900
|
+
/**
|
|
2901
|
+
* A short hint attached to a focusable control, built on the Radix Tooltip.
|
|
2902
|
+
*
|
|
2903
|
+
* A tooltip supplements an accessible name and never replaces one: the
|
|
2904
|
+
* trigger must already be named by its own text or `aria-label`, and the
|
|
2905
|
+
* tooltip is exposed as its description.
|
|
2906
|
+
*
|
|
2907
|
+
* It opens on keyboard focus as well as hover, closes with Escape, and stays
|
|
2908
|
+
* open while the pointer is over the tooltip itself (WCAG 1.4.13). Touch
|
|
2909
|
+
* devices cannot hover, so when the device preferences report no fine
|
|
2910
|
+
* pointer the tooltip does not exist at all and only the trigger renders.
|
|
2911
|
+
*
|
|
2912
|
+
* The bubble renders in a portal under `body`, outside any element a host
|
|
2913
|
+
* scoped a theme to, so it takes the colours its trigger sees (see
|
|
2914
|
+
* `inheritColours`). A host's scoped theme therefore reaches it with no
|
|
2915
|
+
* markup or option of its own. The colours are read once, when the bubble
|
|
2916
|
+
* opens: a theme or colour scheme change while it is open applies the next
|
|
2917
|
+
* time it opens.
|
|
2918
|
+
*/
|
|
2919
|
+
export declare function Tooltip({ content, children }: TooltipProps): JSX.Element;
|
|
2920
|
+
|
|
2921
|
+
/** Props for {@link Tooltip}. */
|
|
2922
|
+
export declare interface TooltipProps {
|
|
2923
|
+
/** The tooltip text. Keep it short and never put the only copy of important information here. */
|
|
2924
|
+
readonly content: ReactNode;
|
|
2925
|
+
/**
|
|
2926
|
+
* The one focusable element the tooltip belongs to, such as a button. It
|
|
2927
|
+
* must forward its ref and spread extra props onto a DOM element.
|
|
2928
|
+
*/
|
|
2929
|
+
readonly children: ReactElement;
|
|
2930
|
+
}
|
|
2931
|
+
|
|
2932
|
+
/**
|
|
2933
|
+
* Shares the open delay between every {@link Tooltip} below it. The app mounts
|
|
2934
|
+
* it once at the root. A {@link Tooltip} outside a provider throws.
|
|
2935
|
+
*/
|
|
2936
|
+
export declare function TooltipProvider({ delayDuration, skipDelayDuration, children, }: TooltipProviderProps): JSX.Element;
|
|
2937
|
+
|
|
2938
|
+
/** Props for {@link TooltipProvider}. */
|
|
2939
|
+
export declare interface TooltipProviderProps {
|
|
2940
|
+
/** Milliseconds a hover must last before the first tooltip opens. Defaults to 400. */
|
|
2941
|
+
readonly delayDuration?: number;
|
|
2942
|
+
/**
|
|
2943
|
+
* Milliseconds after a tooltip closes during which the next one opens
|
|
2944
|
+
* with no delay, so sweeping across a control group feels continuous.
|
|
2945
|
+
* Defaults to 300.
|
|
2946
|
+
*/
|
|
2947
|
+
readonly skipDelayDuration?: number;
|
|
2948
|
+
readonly children: ReactNode;
|
|
2949
|
+
}
|
|
2950
|
+
|
|
2951
|
+
/**
|
|
2952
|
+
* Works out how each polygon or line of a feed layer is drawn, with its label
|
|
2953
|
+
* text, so the map adapter gets plain colours, widths and patterns and needs
|
|
2954
|
+
* no style rule. Features of the geometry the style does not draw are skipped.
|
|
2955
|
+
*
|
|
2956
|
+
* @internal
|
|
2957
|
+
*/
|
|
2958
|
+
export declare function toStyledShapes(definition: FeedLayerDefinition<FeedShapeStyle>, features: readonly LayerFeature[], formatters: FormatterRegistry, now: number, catalogue: MessageCatalogue): MapStyledShapes;
|
|
2959
|
+
|
|
2960
|
+
/**
|
|
2961
|
+
* The first-visit tour's card: the welcome card, a step, or the ending. It is
|
|
2962
|
+
* a region named by its heading, not a dialog, because nothing is modal.
|
|
2963
|
+
*
|
|
2964
|
+
* @remarks The welcome card never takes focus. Taking the tour, Next and a
|
|
2965
|
+
* restart from Help move focus to the heading; a step finished by doing it
|
|
2966
|
+
* leaves focus with the person. Escape inside the card skips (or closes the
|
|
2967
|
+
* ending) and prevents the default, so the app's own Escape does not also
|
|
2968
|
+
* close a surface. When the card closes, or its slot hides because the sheet
|
|
2969
|
+
* is modal or the bottom row has come up to it, with focus inside it, focus
|
|
2970
|
+
* goes to the map. A request for focus made while the slot is hidden (a
|
|
2971
|
+
* restart from Help that closes a sheet in the same update) waits until the
|
|
2972
|
+
* slot shows, because an inert element cannot take it. While a step is current, its control carries
|
|
2973
|
+
* `data-tour-highlight` and is scrolled into view.
|
|
2974
|
+
*/
|
|
2975
|
+
export declare function TourCard({ tour, welcome, ending }: TourCardProps): JSX.Element | null;
|
|
2976
|
+
|
|
2977
|
+
/** The words of a card that is not a step. */
|
|
2978
|
+
export declare interface TourCardCopy {
|
|
2979
|
+
readonly heading: DefinitionText;
|
|
2980
|
+
readonly text: DefinitionText;
|
|
2981
|
+
}
|
|
2982
|
+
|
|
2983
|
+
/** Props for {@link TourCard}. */
|
|
2984
|
+
export declare interface TourCardProps {
|
|
2985
|
+
readonly tour: UseTour;
|
|
2986
|
+
/** The welcome card, offered on a first visit. */
|
|
2987
|
+
readonly welcome: TourCardCopy & {
|
|
2988
|
+
/** Read out once when the welcome card appears, which takes no focus. */
|
|
2989
|
+
readonly announcement: DefinitionText;
|
|
2990
|
+
};
|
|
2991
|
+
/** The ending, after the last step. */
|
|
2992
|
+
readonly ending: TourCardCopy;
|
|
2993
|
+
}
|
|
2994
|
+
|
|
2995
|
+
/** One step of a tour, as data. The host writes the words. */
|
|
2996
|
+
export declare interface TourStep {
|
|
2997
|
+
/** A stable id, for the host's own wiring (for example "layers"). */
|
|
2998
|
+
readonly id: string;
|
|
2999
|
+
/** A message key or plain text, read in the active language where the card and the announcement show it. */
|
|
3000
|
+
readonly heading: DefinitionText;
|
|
3001
|
+
/** As `heading`. */
|
|
3002
|
+
readonly text: DefinitionText;
|
|
3003
|
+
/** What the person does to finish the step. */
|
|
3004
|
+
readonly advance: TourAdvance;
|
|
3005
|
+
/** The registered control to ring while the step is current, if any. */
|
|
3006
|
+
readonly target?: FocusName;
|
|
3007
|
+
/** In the panel layout, which side the card sits against. Defaults to start. */
|
|
3008
|
+
readonly side?: "start" | "end";
|
|
3009
|
+
}
|
|
3010
|
+
|
|
3011
|
+
/**
|
|
3012
|
+
* One heatmap for each heatmap source layer of a vector tile definition, in order.
|
|
3013
|
+
*
|
|
3014
|
+
* @internal
|
|
3015
|
+
*/
|
|
3016
|
+
export declare function toVectorHeatmaps(definition: VectorTileLayerDefinition, controls: ControlValues, now: number): MapHeatmap[];
|
|
3017
|
+
|
|
3018
|
+
/** The batch of layers that was last turned off at once, which Undo would turn back on. */
|
|
3019
|
+
export declare interface TurnedOff {
|
|
3020
|
+
/** How many layers Undo would turn back on: those of the batch that are still off and still in the catalogue. */
|
|
3021
|
+
readonly count: number;
|
|
3022
|
+
/** The ids Undo would turn back on, so the ui can find the group they belong to by its layers, whatever the language calls it. */
|
|
3023
|
+
readonly ids: readonly string[];
|
|
3024
|
+
/** The `group` the ui passed to `turnOff`, or null when the action covered every layer. */
|
|
3025
|
+
readonly group: string | null;
|
|
3026
|
+
}
|
|
3027
|
+
|
|
3028
|
+
/**
|
|
3029
|
+
* How long a basemap stays marked unavailable before it is offered normally again.
|
|
3030
|
+
*
|
|
3031
|
+
* @internal
|
|
3032
|
+
*/
|
|
3033
|
+
export declare const UNAVAILABLE_FOR_MS: number;
|
|
3034
|
+
|
|
3035
|
+
/**
|
|
3036
|
+
* How long the Undo after turning layers off stays on offer, in milliseconds.
|
|
3037
|
+
* It is not shorter than a status message's shortest stay, so there is time to
|
|
3038
|
+
* read it and to reach Undo by keyboard.
|
|
3039
|
+
*/
|
|
3040
|
+
export declare const UNDO_TIMEOUT_MS = 10000;
|
|
3041
|
+
|
|
3042
|
+
/** What can hold the countdown to an Undo offer's expiry: the pointer over its status, or focus inside it. */
|
|
3043
|
+
export declare type UndoHolder = "pointer" | "focus";
|
|
3044
|
+
|
|
3045
|
+
/**
|
|
3046
|
+
* Returns `announce(message, { priority?, keep? })`, which reads a message out
|
|
3047
|
+
* through the app-wide live regions. The message is text or a `Message` from
|
|
3048
|
+
* core, which is formatted with the active catalogue. Pass `keep` for the outcome of something
|
|
3049
|
+
* the person did, so a later message cannot replace it while it waits for the
|
|
3050
|
+
* throttle window. The function is stable between renders.
|
|
3051
|
+
* Outside a `LiveRegionProvider` it does nothing, and warns once in development.
|
|
3052
|
+
*/
|
|
3053
|
+
export declare function useAnnounce(): Announce;
|
|
3054
|
+
|
|
3055
|
+
/**
|
|
3056
|
+
* Which basemaps are not working right now, and how to mark one. Throws
|
|
3057
|
+
* outside a {@link ServicesProvider}, because a missing provider is a wiring bug.
|
|
3058
|
+
*/
|
|
3059
|
+
export declare function useBasemapAvailability(): BasemapAvailability;
|
|
3060
|
+
|
|
3061
|
+
/**
|
|
3062
|
+
* The basemaps on offer: the host's catalogue, or the built-in basemaps when
|
|
3063
|
+
* it supplies none.
|
|
3064
|
+
*/
|
|
3065
|
+
export declare function useBasemaps(): BasemapCatalogue;
|
|
3066
|
+
|
|
3067
|
+
/**
|
|
3068
|
+
* Reads the chrome layout. Outside a `MapChrome` it returns a harmless default
|
|
3069
|
+
* (sheet layout, no-op publishers) so a component can be tested on its own.
|
|
3070
|
+
*/
|
|
3071
|
+
export declare function useChromeLayout(): ChromeLayoutValue;
|
|
3072
|
+
|
|
3073
|
+
/** The clipboard port. */
|
|
3074
|
+
export declare function useClipboard(): ClipboardPort;
|
|
3075
|
+
|
|
3076
|
+
/**
|
|
3077
|
+
* The state of every data layer and the actions on it, driven entirely by
|
|
3078
|
+
* the definitions in the catalogue: nothing here names a layer. It reads the
|
|
3079
|
+
* catalogue as a store, so the layers appear when a catalogue that loads
|
|
3080
|
+
* becomes ready; while it is loading or has failed there are none, and the
|
|
3081
|
+
* layers a link names wait for the first list. Each list that arrives is
|
|
3082
|
+
* reconciled with the choices in the same render, before anything is drawn
|
|
3083
|
+
* or requested: a layer that arrives has its controls' defaults, one that
|
|
3084
|
+
* changed keeps the values that are still valid, and an enabled one that went
|
|
3085
|
+
* is turned off as `setEnabled(id, false)` turns it off and said once.
|
|
3086
|
+
*
|
|
3087
|
+
* @remarks Nothing is requested until a layer is turned on. A feed layer is
|
|
3088
|
+
* loaded on enable, on a control change and on retry; the request for the
|
|
3089
|
+
* previous URL is cancelled. Tile layers need no request here: the map
|
|
3090
|
+
* draws their tiles, and says through `reportTilesSlow` when none has
|
|
3091
|
+
* loaded for a long while, `reportTilesUnavailable` when the map settled
|
|
3092
|
+
* with none loaded and `reportTilesRecovered` when one loads later. Loads,
|
|
3093
|
+
* empty feeds and failures are announced once each through the shared live
|
|
3094
|
+
* region, failures assertively and a tile layer that is slow or has no
|
|
3095
|
+
* tiles, and its recovery, politely. Turning a layer off clears its features, its open card
|
|
3096
|
+
* and its affected area.
|
|
3097
|
+
*/
|
|
3098
|
+
export declare function useDataLayers(options?: UseDataLayersOptions): DataLayers;
|
|
3099
|
+
|
|
3100
|
+
/** Options for {@link useDataLayers}. */
|
|
3101
|
+
export declare interface UseDataLayersOptions {
|
|
3102
|
+
/**
|
|
3103
|
+
* Layers and control values from a permalink. Control values are resolved
|
|
3104
|
+
* against each layer's definition, so an invalid one becomes the default.
|
|
3105
|
+
* A layer the catalogue has not got is dropped. A catalogue that is still
|
|
3106
|
+
* loading has no layers yet, so the link's layers wait for its first list
|
|
3107
|
+
* and stay in {@link DataLayers.urlValue} meanwhile; one that is not there
|
|
3108
|
+
* when the list arrives is dropped then, and said once, for good. The ids
|
|
3109
|
+
* the link carried past its limit (`initial.dropped`) are said in the same
|
|
3110
|
+
* message.
|
|
3111
|
+
*/
|
|
3112
|
+
readonly initial?: LayersUrlState;
|
|
3113
|
+
/** The clock. Defaults to `Date.now`. */
|
|
3114
|
+
readonly now?: () => number;
|
|
3115
|
+
}
|
|
3116
|
+
|
|
3117
|
+
/** What {@link useDirections} returns. */
|
|
3118
|
+
export declare interface UseDirections {
|
|
3119
|
+
/** Whether the host provides a routing service. Without one the tool is not offered. */
|
|
3120
|
+
readonly available: boolean;
|
|
3121
|
+
/** The stops, in order. */
|
|
3122
|
+
readonly stops: readonly DirectionStop[];
|
|
3123
|
+
readonly mode: TravelMode;
|
|
3124
|
+
readonly state: DirectionsState;
|
|
3125
|
+
/** The route or area on the map, or null. */
|
|
3126
|
+
readonly result: DirectionsOutcome | null;
|
|
3127
|
+
/** Whether another stop fits. */
|
|
3128
|
+
readonly canAddStop: boolean;
|
|
3129
|
+
/** Adds a stop at the end, naming it when `label` is given. Says so when the list is full. */
|
|
3130
|
+
readonly addStop: (position: LatLng, label?: string) => void;
|
|
3131
|
+
readonly removeStop: (id: string) => void;
|
|
3132
|
+
/** Moves a stop one place earlier (`-1`) or later (`1`). */
|
|
3133
|
+
readonly moveStop: (id: string, direction: -1 | 1) => void;
|
|
3134
|
+
/** Chooses how to travel. A different mode clears the result, which was for the old one. */
|
|
3135
|
+
readonly setMode: (mode: TravelMode) => void;
|
|
3136
|
+
/** Asks the service for a route through the stops. Needs at least two. */
|
|
3137
|
+
readonly requestRoute: () => void;
|
|
3138
|
+
/** Asks the service for the area reachable from the first stop within `minutes`. */
|
|
3139
|
+
readonly requestArea: (minutes: number) => void;
|
|
3140
|
+
/** Asks again for the request that failed. */
|
|
3141
|
+
readonly retry: () => void;
|
|
3142
|
+
/** Stops a request that is running. */
|
|
3143
|
+
readonly cancel: () => void;
|
|
3144
|
+
/** Removes every stop and the result, and stops a request that is running. */
|
|
3145
|
+
readonly clear: () => void;
|
|
3146
|
+
}
|
|
3147
|
+
|
|
3148
|
+
/**
|
|
3149
|
+
* The state of one set of directions: the stops, the travel mode and the
|
|
3150
|
+
* route or travel-time area the service found for them, with the requests
|
|
3151
|
+
* cancellable and nothing stored. A request is sent only when the person asks
|
|
3152
|
+
* (`requestRoute`, `requestArea`, `retry`), never as stops change.
|
|
3153
|
+
*
|
|
3154
|
+
* @remarks A result belongs to the stops and mode it was found for, so
|
|
3155
|
+
* changing either goes back to idle: a line that no longer matches the
|
|
3156
|
+
* stops is never left on the map. One request runs at a time; a newer one
|
|
3157
|
+
* replaces it, and the answer to a replaced or cancelled request is ignored.
|
|
3158
|
+
* Outcomes are announced through the app-wide announcer, errors assertively.
|
|
3159
|
+
* Any failure the service does not describe is a `network` failure.
|
|
3160
|
+
* @param units - The unit system for the announcements.
|
|
3161
|
+
*/
|
|
3162
|
+
export declare function useDirections(units: UnitSystem): UseDirections;
|
|
3163
|
+
|
|
3164
|
+
/** What {@link useDraw} returns. */
|
|
3165
|
+
export declare interface UseDraw {
|
|
3166
|
+
readonly state: DrawState;
|
|
3167
|
+
readonly shapes: readonly DrawShape[];
|
|
3168
|
+
readonly mode: DrawKind;
|
|
3169
|
+
readonly selection: DrawSelection | null;
|
|
3170
|
+
/** The shape being drawn, or null. */
|
|
3171
|
+
readonly draft: DrawShape | null;
|
|
3172
|
+
/** The selected shape, or null. */
|
|
3173
|
+
readonly selected: DrawShape | null;
|
|
3174
|
+
/** A line for the toolbar, such as "Polygon 1, 3 points", or "Nothing drawn yet". */
|
|
3175
|
+
readonly status: string;
|
|
3176
|
+
/** The measures of the shape being drawn or selected, such as "1.2 ha · 480 m". Empty when none. */
|
|
3177
|
+
readonly measure: string;
|
|
3178
|
+
/** Why the selected shape is not valid after an edit, or null. */
|
|
3179
|
+
readonly issue: DrawIssue | null;
|
|
3180
|
+
/** What to do about {@link UseDraw.issue}, or an empty string. */
|
|
3181
|
+
readonly issueMessage: string;
|
|
3182
|
+
readonly canUndo: boolean;
|
|
3183
|
+
readonly canRedo: boolean;
|
|
3184
|
+
/** The handles to give the map adapter: those of the selected shape while the tool is open. */
|
|
3185
|
+
readonly handles: readonly MapEditHandle[];
|
|
3186
|
+
/** The handle a mouse is over, or null. */
|
|
3187
|
+
readonly hoveredHandle: string | null;
|
|
3188
|
+
/** The outcome of the last export or copy, until the shapes change. */
|
|
3189
|
+
readonly feedback: DrawFeedback | null;
|
|
3190
|
+
/** What the last import added or why it added nothing, until the shapes change again. */
|
|
3191
|
+
readonly importFeedback: DrawFeedback | null;
|
|
3192
|
+
readonly setMode: (kind: DrawKind) => void;
|
|
3193
|
+
/** Adds a point, or starts a shape, at a position. */
|
|
3194
|
+
readonly addPoint: (at: LatLng) => void;
|
|
3195
|
+
/** Adds a point at the map centre, or moves the selected vertex there. */
|
|
3196
|
+
readonly placeAtCentre: () => void;
|
|
3197
|
+
/** Moves the selected vertex to a position. */
|
|
3198
|
+
readonly moveSelectedTo: (at: LatLng) => void;
|
|
3199
|
+
/** Moves the selected vertex by screen pixels (positive x is right, positive y is down). */
|
|
3200
|
+
readonly nudge: (dx: number, dy: number) => void;
|
|
3201
|
+
readonly undo: () => void;
|
|
3202
|
+
readonly redo: () => void;
|
|
3203
|
+
readonly finish: () => void;
|
|
3204
|
+
readonly cancel: () => void;
|
|
3205
|
+
/** Removes the shape being drawn without a word, when Done closes the tool. */
|
|
3206
|
+
readonly discardDraft: () => void;
|
|
3207
|
+
/**
|
|
3208
|
+
* Selects a shape, and a vertex of it when `vertex` is a number. Without
|
|
3209
|
+
* `vertex`, a point or a circle selects its one vertex, so the arrow keys
|
|
3210
|
+
* and Move to map centre work on it; any other shape selects as a whole.
|
|
3211
|
+
*/
|
|
3212
|
+
readonly select: (shapeId: string, vertex?: number | null) => void;
|
|
3213
|
+
readonly deselect: () => void;
|
|
3214
|
+
readonly stepVertex: (delta: 1 | -1) => void;
|
|
3215
|
+
/** Removes the selected vertex. */
|
|
3216
|
+
readonly removeVertex: () => void;
|
|
3217
|
+
/** Adds a vertex at the map centre after the selected one. */
|
|
3218
|
+
readonly insertAtCentre: () => void;
|
|
3219
|
+
readonly deleteSelected: () => void;
|
|
3220
|
+
readonly deleteShape: (shapeId: string) => void;
|
|
3221
|
+
readonly clear: () => void;
|
|
3222
|
+
/** Sets the selected circle's radius to its distance from the map centre. */
|
|
3223
|
+
readonly setRadiusToCentre: () => void;
|
|
3224
|
+
/** Multiplies the selected circle's radius. */
|
|
3225
|
+
readonly scaleRadius: (factor: number) => void;
|
|
3226
|
+
/** A click or tap on the map. Starts, extends or selects a shape. */
|
|
3227
|
+
readonly onMapClick: (event: Pick<MapClickEvent, "latlng" | "point">) => void;
|
|
3228
|
+
/** A step of a press on an edit handle, from the adapter. */
|
|
3229
|
+
readonly onHandleDrag: (drag: MapHandleDrag) => void;
|
|
3230
|
+
readonly onHandleHover: (id: string | null) => void;
|
|
3231
|
+
/** Runs a key press as a draw command. Returns true when it was one, so the caller can stop the key. */
|
|
3232
|
+
readonly keyCommand: (event: DrawKeyEvent) => boolean;
|
|
3233
|
+
readonly exportGeoJson: () => Promise<void>;
|
|
3234
|
+
readonly exportCsv: () => Promise<void>;
|
|
3235
|
+
readonly exportWkt: () => Promise<void>;
|
|
3236
|
+
/** Copies a link with the shapes in it, built from the current address. */
|
|
3237
|
+
readonly copyLink: () => Promise<void>;
|
|
3238
|
+
/**
|
|
3239
|
+
* Asks the person for a GeoJSON, CSV or WKT file and adds its shapes as one undo
|
|
3240
|
+
* step. Call it straight from a press, so the browser shows the picker.
|
|
3241
|
+
* @returns The box holding the shapes it added, for the map to fit, or
|
|
3242
|
+
* null when it added none, including when the host has no file opener.
|
|
3243
|
+
*/
|
|
3244
|
+
readonly importFile: () => Promise<Bounds | null>;
|
|
3245
|
+
/** The order of the two numbers in a WKT position that an import reads: longitude first until changed. Kept for the session only. */
|
|
3246
|
+
readonly wktAxisOrder: WktAxisOrder;
|
|
3247
|
+
/** Chooses the order by hand. An offer to read the last file the other way, and the file it kept, are dropped. */
|
|
3248
|
+
readonly setWktAxisOrder: (order: WktAxisOrder) => void;
|
|
3249
|
+
/**
|
|
3250
|
+
* Reads the file whose import offered {@link DrawFeedback.readAs} again in
|
|
3251
|
+
* `order`, and keeps `order` as the WKT axis order.
|
|
3252
|
+
* @returns The box holding the shapes it added, as {@link UseDraw.importFile}
|
|
3253
|
+
* does, or null when it added none or there is no such file.
|
|
3254
|
+
*/
|
|
3255
|
+
readonly rereadImport: (order: WktAxisOrder) => Bounds | null;
|
|
3256
|
+
}
|
|
3257
|
+
|
|
3258
|
+
/**
|
|
3259
|
+
* The state of the Draw tool: the shapes, what is selected, undo, and every
|
|
3260
|
+
* way to change them, by pointer and by keyboard.
|
|
3261
|
+
*
|
|
3262
|
+
* @remarks The pure rules live in core (`drawReducer` and friends). This hook
|
|
3263
|
+
* adds what needs the map and the ports: the map centre and projection for
|
|
3264
|
+
* "at map centre", nudges and shape picking; the announcer; the file saver
|
|
3265
|
+
* and the clipboard for export; and the address for a link with shapes.
|
|
3266
|
+
*
|
|
3267
|
+
* Shapes belong to the app, not to the toolbar, so they stay on the map when
|
|
3268
|
+
* the tool closes. Nothing is stored, and nothing reaches the address bar:
|
|
3269
|
+
* shapes are read once, from a link that carries them, and written only into
|
|
3270
|
+
* the link {@link UseDraw.copyLink} builds.
|
|
3271
|
+
*
|
|
3272
|
+
* Announcements follow the reducer's `lastEvent`, so a drag that moves a
|
|
3273
|
+
* vertex many times is announced once, {@link DRAW_ANNOUNCE_DELAY_MS} after
|
|
3274
|
+
* it settles, and a refusal is announced assertively.
|
|
3275
|
+
*/
|
|
3276
|
+
export declare function useDraw({ units, active, getAdapter, }: UseDrawOptions): UseDraw;
|
|
3277
|
+
|
|
3278
|
+
/** Options for {@link useDraw}. */
|
|
3279
|
+
export declare interface UseDrawOptions {
|
|
3280
|
+
/** The unit system for the readout and the announcements. */
|
|
3281
|
+
readonly units: UnitSystem;
|
|
3282
|
+
/** Whether the Draw tool is open. Handles, clicks and keys only work then. */
|
|
3283
|
+
readonly active: boolean;
|
|
3284
|
+
/** Returns the mounted adapter, or null. Read when a position or the map centre is needed. */
|
|
3285
|
+
readonly getAdapter: () => MapAdapter | null;
|
|
3286
|
+
}
|
|
3287
|
+
|
|
3288
|
+
/**
|
|
3289
|
+
* The query for the features inside a shape, or `undefined` when the host
|
|
3290
|
+
* supplies none. Selecting by shape needs it, so a host without one offers no
|
|
3291
|
+
* such action. Nothing is requested until a user action asks.
|
|
3292
|
+
*/
|
|
3293
|
+
export declare function useFeatureQuery(): FeatureQuery | undefined;
|
|
3294
|
+
|
|
3295
|
+
/**
|
|
3296
|
+
* The selected set as the ui shows it: the host's `FeatureSelection` store,
|
|
3297
|
+
* resolved against the layers, with the select-mode flag and one message to
|
|
3298
|
+
* the live region for each change a person makes.
|
|
3299
|
+
*
|
|
3300
|
+
* Call it once, in the host beside `useDataLayers`, and hand the result down
|
|
3301
|
+
* with `SelectionProvider`: its state outlives the sheet's sections, which
|
|
3302
|
+
* unmount. It returns null when the host supplies no store, so a host without
|
|
3303
|
+
* one offers no selection.
|
|
3304
|
+
*
|
|
3305
|
+
* @remarks A reference shows its layer's loaded feature, else a snapshot kept
|
|
3306
|
+
* while it was loaded, but only while its layer is on and is a feed layer.
|
|
3307
|
+
* Otherwise it is not shown, and it stays in the store and counts. Turning a
|
|
3308
|
+
* layer off drops nothing and says nothing here: `useDataLayers` announces
|
|
3309
|
+
* the turning off itself, and its Undo brings the references back. A layer
|
|
3310
|
+
* that a ready catalogue removes is different: it cannot come back by Undo,
|
|
3311
|
+
* so its references are dropped, once and in one message, when the removal
|
|
3312
|
+
* is seen. Nothing is dropped at mount, while the catalogue is loading or
|
|
3313
|
+
* has failed, for a layer the catalogue never listed, or for a reference a
|
|
3314
|
+
* store hydrates later. A change made outside (hydration, a failed save)
|
|
3315
|
+
* updates `entries` and is not announced. Each message carries the new
|
|
3316
|
+
* total, because the live region replaces a waiting message that is not
|
|
3317
|
+
* kept with a later one when both arrive within `THROTTLE_MS` of the last
|
|
3318
|
+
* one sent. The refusal of a batch past the limit is assertive, the rest
|
|
3319
|
+
* polite.
|
|
3320
|
+
*/
|
|
3321
|
+
export declare function useFeatureSelection(layers: DataLayers, options?: UseFeatureSelectionOptions): FeatureSelectionState | null;
|
|
3322
|
+
|
|
3323
|
+
/** Options for {@link useFeatureSelection}. */
|
|
3324
|
+
export declare interface UseFeatureSelectionOptions {
|
|
3325
|
+
/** The formatters card templates may name, for the titles in messages. Defaults to the built-ins. */
|
|
3326
|
+
readonly formatters?: FormatterRegistry;
|
|
3327
|
+
}
|
|
3328
|
+
|
|
3329
|
+
/**
|
|
3330
|
+
* The file opener, which asks the person for a file and reads it in the
|
|
3331
|
+
* browser, or `undefined` when the host supplies none. Shape import needs it,
|
|
3332
|
+
* so a host without one gets no Import control.
|
|
3333
|
+
*/
|
|
3334
|
+
export declare function useFileOpener(): FileOpener | undefined;
|
|
3335
|
+
|
|
3336
|
+
/** The file saver, which offers a file the ui built as a download. */
|
|
3337
|
+
export declare function useFileSaver(): FileSaver;
|
|
3338
|
+
|
|
3339
|
+
/**
|
|
3340
|
+
* Returns `element(name)`, the registered control in the document, or null.
|
|
3341
|
+
* Read-only: the first-visit tour uses it to ring the control a step names.
|
|
3342
|
+
*/
|
|
3343
|
+
export declare function useFocusElement(): (name: FocusName) => HTMLElement | null;
|
|
3344
|
+
|
|
3345
|
+
/**
|
|
3346
|
+
* Returns `restore(name)`, which focuses the registered control, or the map
|
|
3347
|
+
* region when the name is null or the control is no longer in the document.
|
|
3348
|
+
*/
|
|
3349
|
+
export declare function useFocusReturn(): (name: FocusName | null) => void;
|
|
3350
|
+
|
|
3351
|
+
/**
|
|
3352
|
+
* Returns a ref callback to put on the control that opens a surface, so focus
|
|
3353
|
+
* can come back to it: `<IconButton ref={useFocusTarget("map-options")} />`.
|
|
3354
|
+
*/
|
|
3355
|
+
export declare function useFocusTarget(name: FocusName): (element: HTMLElement | null) => void;
|
|
3356
|
+
|
|
3357
|
+
/**
|
|
3358
|
+
* Formats a core {@link Message} (a key and its parameters) with the active
|
|
3359
|
+
* catalogue, for text a component shows or hands on as a string. The function
|
|
3360
|
+
* is stable while the catalogue is.
|
|
3361
|
+
*/
|
|
3362
|
+
export declare function useFormatMessage(): (message: Message) => string;
|
|
3363
|
+
|
|
3364
|
+
/**
|
|
3365
|
+
* The target of "at the map centre" for a tool whose panel covers part of the
|
|
3366
|
+
* map: the middle of what is left uncovered, so it is never under the sheet.
|
|
3367
|
+
* Read it inside the map context and the chrome.
|
|
3368
|
+
*/
|
|
3369
|
+
export declare function useFreeCentre(): FreeCentre;
|
|
3370
|
+
|
|
3371
|
+
/**
|
|
3372
|
+
* Whether to show the "Looking up what is here" line: true once `identifying`
|
|
3373
|
+
* (see `DataLayers.identifying`) has been true for {@link IDENTIFY_FEEDBACK_MS},
|
|
3374
|
+
* and false again the moment it ends. The line is for the eye only. The
|
|
3375
|
+
* lookup's result is said once, when it arrives, so nothing is announced
|
|
3376
|
+
* while waiting: a message at the delay would be coalesced with the result.
|
|
3377
|
+
*/
|
|
3378
|
+
export declare function useIdentifyFeedback(identifying: boolean): boolean;
|
|
3379
|
+
|
|
3380
|
+
/**
|
|
3381
|
+
* Whether the messages for the language the person chose have failed to load,
|
|
3382
|
+
* and a way to try again, or `undefined` when the host offers no languages. The
|
|
3383
|
+
* interface stays in the language it was in until a load succeeds, so a status
|
|
3384
|
+
* built from this reads in that language. {@link LanguageLoad.retry} also works
|
|
3385
|
+
* when the setting has not changed, which a failed load otherwise waits for.
|
|
3386
|
+
*/
|
|
3387
|
+
export declare function useLanguageLoad(): LanguageLoad | undefined;
|
|
3388
|
+
|
|
3389
|
+
/**
|
|
3390
|
+
* The languages the host offers, or `undefined` when it offers none to choose
|
|
3391
|
+
* between. The Settings panel shows its language switcher only when there is
|
|
3392
|
+
* more than one.
|
|
3393
|
+
*/
|
|
3394
|
+
export declare function useLanguages(): LanguageCatalogue | undefined;
|
|
3395
|
+
|
|
3396
|
+
/**
|
|
3397
|
+
* The data layer catalogue: a store of the host's layer definitions and
|
|
3398
|
+
* whether they have loaded. Read it with `useSyncExternalStore` and pass
|
|
3399
|
+
* `getState` as the server snapshot, as `useDataLayers` does.
|
|
3400
|
+
*/
|
|
3401
|
+
export declare function useLayers(): LayerCatalogue;
|
|
3402
|
+
|
|
3403
|
+
/** What {@link useLocate} returns. */
|
|
3404
|
+
export declare interface UseLocate {
|
|
3405
|
+
readonly state: LocateState;
|
|
3406
|
+
/** The latest fix. Set only while `state` is `found`. */
|
|
3407
|
+
readonly fix: LocationFix | null;
|
|
3408
|
+
/** Why the last request failed. Set only while `state` is `error`. */
|
|
3409
|
+
readonly error: LocationErrorKind | null;
|
|
3410
|
+
/**
|
|
3411
|
+
* Visible status text for the app to show in a `StatusMessage`: empty when
|
|
3412
|
+
* idle, "Finding your location..." while locating, the accuracy when found
|
|
3413
|
+
* and what went wrong, with a next step, on an error. The text for an error
|
|
3414
|
+
* must stay on screen until the user dismisses it.
|
|
3415
|
+
*/
|
|
3416
|
+
readonly message: string;
|
|
3417
|
+
/**
|
|
3418
|
+
* Asks for the user's location. Call it only from a user action, such as a
|
|
3419
|
+
* click on "Locate me": the browser may show a permission prompt. A second
|
|
3420
|
+
* call cancels the first.
|
|
3421
|
+
*/
|
|
3422
|
+
readonly locate: () => void;
|
|
3423
|
+
/**
|
|
3424
|
+
* Cancels a request in flight and returns to `idle`. Calling it after a
|
|
3425
|
+
* result or an error also returns to `idle`, which is how the app dismisses
|
|
3426
|
+
* the status message.
|
|
3427
|
+
*/
|
|
3428
|
+
readonly cancel: () => void;
|
|
3429
|
+
}
|
|
3430
|
+
|
|
3431
|
+
/**
|
|
3432
|
+
* Finds the user's location through the services' `LocationProvider`, one
|
|
3433
|
+
* request at a time. Each request has its own `AbortController`, aborted by
|
|
3434
|
+
* a newer request, by `cancel` and on unmount; a cancelled request never
|
|
3435
|
+
* changes state or announces anything.
|
|
3436
|
+
*
|
|
3437
|
+
* The outcome is announced through the app-wide announcer, and `message`
|
|
3438
|
+
* carries the same wording for the visible status.
|
|
3439
|
+
* @remarks Announcing and showing the same error means a screen reader may
|
|
3440
|
+
* hear it twice if the app puts `message` in an alert `StatusMessage`;
|
|
3441
|
+
* pass `announceErrors: false` in that case.
|
|
3442
|
+
*/
|
|
3443
|
+
export declare function useLocate(units: UnitSystem, { timeoutMs, announceErrors }?: UseLocateOptions): UseLocate;
|
|
3444
|
+
|
|
3445
|
+
/** Options for {@link useLocate}. */
|
|
3446
|
+
export declare interface UseLocateOptions {
|
|
3447
|
+
/** Passed to the provider, which decides its own default when absent. */
|
|
3448
|
+
readonly timeoutMs?: number;
|
|
3449
|
+
/**
|
|
3450
|
+
* Whether to announce errors through the announcer. Defaults to true. Pass
|
|
3451
|
+
* false when the app shows `message` in an error `StatusMessage`, which is
|
|
3452
|
+
* an alert itself, so the error is spoken once. A fix is always announced.
|
|
3453
|
+
*/
|
|
3454
|
+
readonly announceErrors?: boolean;
|
|
3455
|
+
}
|
|
3456
|
+
|
|
3457
|
+
/** The location provider. Nothing is requested until a user action calls it. */
|
|
3458
|
+
export declare function useLocationProvider(): LocationProvider;
|
|
3459
|
+
|
|
3460
|
+
/** The pointer handlers to spread on the host, plus hooks for the map engine. */
|
|
3461
|
+
export declare interface UseLongPress {
|
|
3462
|
+
readonly handlers: {
|
|
3463
|
+
readonly onPointerDown: (event: PointerEvent_2) => void;
|
|
3464
|
+
readonly onPointerMove: (event: PointerEvent_2) => void;
|
|
3465
|
+
readonly onPointerUp: (event: PointerEvent_2) => void;
|
|
3466
|
+
readonly onPointerCancel: (event: PointerEvent_2) => void;
|
|
3467
|
+
readonly onContextMenu: (event: MouseEvent_2) => void;
|
|
3468
|
+
};
|
|
3469
|
+
/** Cancels a pending press. Call it when the map moves. */
|
|
3470
|
+
readonly cancel: () => void;
|
|
3471
|
+
/**
|
|
3472
|
+
* Returns true, once, for the engine click that follows a long-press, so the
|
|
3473
|
+
* caller can drop it. A new press clears the flag, so a missing engine click
|
|
3474
|
+
* never swallows a later one.
|
|
3475
|
+
*/
|
|
3476
|
+
readonly consumeClick: () => boolean;
|
|
3477
|
+
}
|
|
3478
|
+
|
|
3479
|
+
/**
|
|
3480
|
+
* Long-press on the map, implemented once with pointer events so it behaves
|
|
3481
|
+
* the same on every engine. A press fires after {@link LONG_PRESS_DELAY_MS}
|
|
3482
|
+
* unless the pointer moves more than 10 CSS pixels, a second
|
|
3483
|
+
* pointer joins (pinch), the pointer is released or cancelled, or the map
|
|
3484
|
+
* moves (`cancel`). Right-click fires it at once and suppresses the browser's
|
|
3485
|
+
* context menu.
|
|
3486
|
+
*
|
|
3487
|
+
* @remarks Android raises `contextmenu` during a touch long-press as well, so a
|
|
3488
|
+
* press fires at most once whichever comes first. Only the primary button
|
|
3489
|
+
* starts a timed press.
|
|
3490
|
+
*/
|
|
3491
|
+
export declare function useLongPress(options: UseLongPressOptions): UseLongPress;
|
|
3492
|
+
|
|
3493
|
+
/** Options for {@link useLongPress}. */
|
|
3494
|
+
export declare interface UseLongPressOptions {
|
|
3495
|
+
/** The map region element; points are measured from its top-left corner. */
|
|
3496
|
+
readonly hostRef: RefObject<HTMLElement | null>;
|
|
3497
|
+
/** Returns the mounted adapter, or null while there is none. */
|
|
3498
|
+
readonly getAdapter: () => MapAdapter | null;
|
|
3499
|
+
/** Called once per long-press. Without it, presses are ignored. */
|
|
3500
|
+
readonly onLongPress?: (event: MapLongPressEvent) => void;
|
|
3501
|
+
}
|
|
3502
|
+
|
|
3503
|
+
/**
|
|
3504
|
+
* Returns the live map. Throws outside a `MapView`, because a missing map is a
|
|
3505
|
+
* wiring bug, not a runtime condition.
|
|
3506
|
+
*/
|
|
3507
|
+
export declare function useMap(): MapContextValue;
|
|
3508
|
+
|
|
3509
|
+
/** The map adapter factory, used by the map host to pick an engine for a basemap. */
|
|
3510
|
+
export declare function useMapAdapterFactory(): MapAdapterFactory;
|
|
3511
|
+
|
|
3512
|
+
/** What {@link useMeasure} returns. */
|
|
3513
|
+
export declare interface UseMeasure {
|
|
3514
|
+
readonly mode: MeasureMode;
|
|
3515
|
+
/** The vertices, in the order they were added. */
|
|
3516
|
+
readonly points: readonly LatLng[];
|
|
3517
|
+
/**
|
|
3518
|
+
* The total in metres (`distance`) or square metres (`area`), measured
|
|
3519
|
+
* along the geodesic. `null` until there are enough points: two for a
|
|
3520
|
+
* distance, three for an area.
|
|
3521
|
+
*/
|
|
3522
|
+
readonly total: number | null;
|
|
3523
|
+
/** The total as text in the chosen units, for example "1.25 km". "0 m" or "0 m²" until there are enough points. */
|
|
3524
|
+
readonly readout: string;
|
|
3525
|
+
/** Adds a vertex at the end. */
|
|
3526
|
+
readonly addPoint: (point: LatLng) => void;
|
|
3527
|
+
/** Moves the vertex at `index`, for example while it is dragged. Out-of-range indexes are ignored. */
|
|
3528
|
+
readonly movePoint: (index: number, point: LatLng) => void;
|
|
3529
|
+
/** Removes the last vertex. Does nothing with no points. */
|
|
3530
|
+
readonly undo: () => void;
|
|
3531
|
+
/** Removes every vertex. */
|
|
3532
|
+
readonly clear: () => void;
|
|
3533
|
+
/** Switches between distance and area, keeping the points. */
|
|
3534
|
+
readonly setMode: (mode: MeasureMode) => void;
|
|
3535
|
+
}
|
|
3536
|
+
|
|
3537
|
+
/**
|
|
3538
|
+
* The state of one measurement: the points the user has placed, the mode and
|
|
3539
|
+
* the total, worked out with the core geodesic maths (WGS 84, not flat
|
|
3540
|
+
* pixels).
|
|
3541
|
+
*
|
|
3542
|
+
* The total is announced through the app-wide announcer only after the points
|
|
3543
|
+
* have been still for {@link MEASURE_ANNOUNCE_DELAY_MS}, so adding points in
|
|
3544
|
+
* quick succession or dragging a vertex gives one announcement at the end,
|
|
3545
|
+
* not one per change. Nothing is announced before there is a total.
|
|
3546
|
+
* @param units - The unit system for the readout and the announcement.
|
|
3547
|
+
*/
|
|
3548
|
+
export declare function useMeasure(units: UnitSystem): UseMeasure;
|
|
3549
|
+
|
|
3550
|
+
/**
|
|
3551
|
+
* The active message catalogue, for `t`/`plural`/`list` calls that look up
|
|
3552
|
+
* copy by key instead of writing it inline. With `Services.languages` it is
|
|
3553
|
+
* the language the person's setting, or else the browser's languages, resolve
|
|
3554
|
+
* to; the catalogue changes when either does, and keeps the previous one while
|
|
3555
|
+
* a lazily loaded language is still arriving. Without it, it is always
|
|
3556
|
+
* `Services.messages`.
|
|
3557
|
+
*/
|
|
3558
|
+
export declare function useMessages(): MessageCatalogue;
|
|
3559
|
+
|
|
3560
|
+
/**
|
|
3561
|
+
* Whether the browser says the device has a connection, updating live. It is
|
|
3562
|
+
* a hint: a device can report online with no route, and `true` where the host
|
|
3563
|
+
* gives no signal.
|
|
3564
|
+
*/
|
|
3565
|
+
export declare function useOnline(): boolean;
|
|
3566
|
+
|
|
3567
|
+
/**
|
|
3568
|
+
* As {@link useMessages}, but without a {@link ServicesProvider} above it the
|
|
3569
|
+
* SDK's English catalogue, so a piece a consumer may render on its own (the
|
|
3570
|
+
* skip link, a status message) keeps working. Inside a provider it is the
|
|
3571
|
+
* active catalogue.
|
|
3572
|
+
*/
|
|
3573
|
+
export declare function useOptionalMessages(): MessageCatalogue;
|
|
3574
|
+
|
|
3575
|
+
/**
|
|
3576
|
+
* Returns the services, or null outside a {@link ServicesProvider}. For the
|
|
3577
|
+
* few pieces, such as the live regions, that must still work when a test or
|
|
3578
|
+
* a host mounts them without one.
|
|
3579
|
+
*/
|
|
3580
|
+
export declare function useOptionalServices(): Services | null;
|
|
3581
|
+
|
|
3582
|
+
/**
|
|
3583
|
+
* The placement every overlay uses: the live adapter, the current view and
|
|
3584
|
+
* the map shape, or null before the map has mounted. Read it inside the map
|
|
3585
|
+
* context.
|
|
3586
|
+
*/
|
|
3587
|
+
export declare function usePlacement(): MapPlacement | null;
|
|
3588
|
+
|
|
3589
|
+
/** Device and accessibility preferences (reduced motion, fine pointer, save data), updating live. */
|
|
3590
|
+
export declare function usePreferences(): DevicePreferencesValue;
|
|
3591
|
+
|
|
3592
|
+
/**
|
|
3593
|
+
* Reads a definition's text in the active language: a message key is looked
|
|
3594
|
+
* up in the catalogue, a plain string is returned as written (see
|
|
3595
|
+
* `resolveText`). The function is stable while the catalogue is.
|
|
3596
|
+
*/
|
|
3597
|
+
export declare function useResolveText(): (text: DefinitionText) => string;
|
|
3598
|
+
|
|
3599
|
+
/**
|
|
3600
|
+
* Looks up the address at a position with the search provider's `reverse`,
|
|
3601
|
+
* but only when `lookUp` is called, because the position leaves the device.
|
|
3602
|
+
* The provider receives the position rounded with `roundForLookup`.
|
|
3603
|
+
*
|
|
3604
|
+
* @remarks Moving the position, or unmounting, aborts the lookup in flight and
|
|
3605
|
+
* returns the state to `idle`. An aborted lookup never changes state, and an
|
|
3606
|
+
* answer is only ever shown for the position it was asked for. A failed
|
|
3607
|
+
* lookup is `error`, which callers should show with a way to try again.
|
|
3608
|
+
*/
|
|
3609
|
+
export declare function useReverseAddress({ lat, lng }: LatLng): ReverseAddress;
|
|
3610
|
+
|
|
3611
|
+
/**
|
|
3612
|
+
* The routing provider, or `undefined` when the host supplies none. The
|
|
3613
|
+
* Directions tool needs it, so a host without one gets no such tool. Nothing
|
|
3614
|
+
* is requested until a user action asks for a route or area.
|
|
3615
|
+
*/
|
|
3616
|
+
export declare function useRoutingProvider(): RoutingProvider | undefined;
|
|
3617
|
+
|
|
3618
|
+
/**
|
|
3619
|
+
* Whether Save data mode is on: the person's own choice from Settings when
|
|
3620
|
+
* they made one, otherwise the device's signal (a data saver or a very slow
|
|
3621
|
+
* connection, where the browser reports one). Re-renders when either changes.
|
|
3622
|
+
*/
|
|
3623
|
+
export declare function useSaveData(): boolean;
|
|
3624
|
+
|
|
3625
|
+
/** What {@link useSearch} returns. */
|
|
3626
|
+
export declare interface UseSearch {
|
|
3627
|
+
/** The text in the search box. */
|
|
3628
|
+
readonly query: string;
|
|
3629
|
+
/** Where the search stands. */
|
|
3630
|
+
readonly state: SearchState;
|
|
3631
|
+
/**
|
|
3632
|
+
* Sets the text as the user typed it. Never searches: it cancels any search
|
|
3633
|
+
* in flight and returns to `idle`, so results for older text never sit
|
|
3634
|
+
* under new text.
|
|
3635
|
+
*/
|
|
3636
|
+
readonly setQuery: (query: string) => void;
|
|
3637
|
+
/**
|
|
3638
|
+
* Searches for the current text, for Enter or the Search button. Answers a
|
|
3639
|
+
* coordinate pair itself, without the provider. Does
|
|
3640
|
+
* nothing when the trimmed text is shorter than {@link MIN_SEARCH_LENGTH},
|
|
3641
|
+
* or when the text's own search is already loading or showing its outcome
|
|
3642
|
+
* (after a failure it searches again).
|
|
3643
|
+
*/
|
|
3644
|
+
readonly submit: () => void;
|
|
3645
|
+
/**
|
|
3646
|
+
* Puts text in the box without searching: cancels anything in flight and
|
|
3647
|
+
* returns to `idle`. Used when the user picks a result, so the box shows
|
|
3648
|
+
* its label.
|
|
3649
|
+
*/
|
|
3650
|
+
readonly settle: (query: string) => void;
|
|
3651
|
+
/** Empties the box and cancels everything. */
|
|
3652
|
+
readonly clear: () => void;
|
|
3653
|
+
/** Runs the current query again at once, for the Retry button. */
|
|
3654
|
+
readonly retry: () => void;
|
|
3655
|
+
}
|
|
3656
|
+
|
|
3657
|
+
/**
|
|
3658
|
+
* Cancellable place search over the services' `SearchProvider`, run only
|
|
3659
|
+
* when the user submits. Text that is a coordinate pair, such as
|
|
3660
|
+
* `-26.2041, 28.0473` or `26°12'14.8"S 28°02'50.3"E`, is answered here with
|
|
3661
|
+
* one result for that place and never reaches the provider, so it sends no
|
|
3662
|
+
* request. Nothing is sent to the geocoder while they type, as the
|
|
3663
|
+
* OpenStreetMap Foundation's Nominatim policy forbids client-side
|
|
3664
|
+
* autocomplete; suggestions as they type come from a separate provider (see
|
|
3665
|
+
* `useSuggestions`). This is the one place that owns the `AbortController`: each
|
|
3666
|
+
* search aborts the one before it, and an aborted request never changes state
|
|
3667
|
+
* or reaches the announcer. The provider itself keeps to the service's rate
|
|
3668
|
+
* limit.
|
|
3669
|
+
*
|
|
3670
|
+
* Announcements go through the app-wide announcer: the result count (or "No
|
|
3671
|
+
* results", or the error) once the search settles. An identical message is
|
|
3672
|
+
* not repeated for consecutive searches until the box has been emptied or
|
|
3673
|
+
* Retry is pressed.
|
|
3674
|
+
*/
|
|
3675
|
+
export declare function useSearch({ getBias }?: UseSearchOptions): UseSearch;
|
|
3676
|
+
|
|
3677
|
+
/** Options for {@link useSearch}. */
|
|
3678
|
+
export declare interface UseSearchOptions {
|
|
3679
|
+
/**
|
|
3680
|
+
* Returns the box to favour results inside, usually the visible map. Called
|
|
3681
|
+
* once when each search starts, so the bias follows the map without the
|
|
3682
|
+
* caller recomputing it on every frame. Leave it out to send only the
|
|
3683
|
+
* query: a host that passes it sends that box to its geocoder with every
|
|
3684
|
+
* search, which can show where the person is, so its privacy text must say so.
|
|
3685
|
+
*/
|
|
3686
|
+
readonly getBias?: () => Bounds | undefined;
|
|
3687
|
+
}
|
|
3688
|
+
|
|
3689
|
+
/** The place search provider. Debounce and cancellation live in `useSearch`, not here. */
|
|
3690
|
+
export declare function useSearchProvider(): SearchProvider;
|
|
3691
|
+
|
|
3692
|
+
/**
|
|
3693
|
+
* The selected set, or undefined outside a {@link SelectionProvider} or when
|
|
3694
|
+
* the host offers no selection. A component that selects or lists features
|
|
3695
|
+
* renders nothing then.
|
|
3696
|
+
*/
|
|
3697
|
+
export declare function useSelection(): FeatureSelectionState | undefined;
|
|
3698
|
+
|
|
3699
|
+
/**
|
|
3700
|
+
* The store of selected features, or `undefined` when the host supplies none.
|
|
3701
|
+
* Nothing in the ui selects a feature without it. A component that needs the
|
|
3702
|
+
* set to follow changes reads it with `useSyncExternalStore`, passing
|
|
3703
|
+
* `getState` as the server snapshot.
|
|
3704
|
+
*/
|
|
3705
|
+
export declare function useSelectionStore(): FeatureSelection | undefined;
|
|
3706
|
+
|
|
3707
|
+
/**
|
|
3708
|
+
* Returns the services. Throws when called outside a {@link ServicesProvider},
|
|
3709
|
+
* because a missing provider is a wiring bug, not a runtime condition.
|
|
3710
|
+
*/
|
|
3711
|
+
export declare function useServices(): Services;
|
|
3712
|
+
|
|
3713
|
+
/** What {@link useSettings} returns. */
|
|
3714
|
+
export declare interface UseSettings {
|
|
3715
|
+
readonly settings: Settings;
|
|
3716
|
+
/** Merges a patch into the stored settings. */
|
|
3717
|
+
readonly update: (patch: Partial<Settings>) => void;
|
|
3718
|
+
/** False when storage is blocked, so changes will not be remembered. */
|
|
3719
|
+
readonly persistent: boolean;
|
|
3720
|
+
}
|
|
3721
|
+
|
|
3722
|
+
/** Subscribes to the settings store. Re-renders only when a setting changes. */
|
|
3723
|
+
export declare function useSettings(): UseSettings;
|
|
3724
|
+
|
|
3725
|
+
/**
|
|
3726
|
+
* The suggestion provider, or `undefined` when the host supplies none. The
|
|
3727
|
+
* search pill suggests places as the person types only when it exists, so a
|
|
3728
|
+
* host without one keeps submit-only search. Nothing is requested until the
|
|
3729
|
+
* person has typed.
|
|
3730
|
+
*/
|
|
3731
|
+
export declare function useSuggestionProvider(): SuggestionProvider | undefined;
|
|
3732
|
+
|
|
3733
|
+
/**
|
|
3734
|
+
* Suggests places for text as it is typed, over the services' optional
|
|
3735
|
+
* `SuggestionProvider`. Returns the suggestions for the latest text that has
|
|
3736
|
+
* settled, or none.
|
|
3737
|
+
*
|
|
3738
|
+
* A request starts only when the trimmed text has been unchanged for
|
|
3739
|
+
* {@link SUGGEST_DEBOUNCE_MS}, is at least {@link MIN_SUGGEST_LENGTH}
|
|
3740
|
+
* characters and has a word in it, so a coordinate pair typed digit by digit
|
|
3741
|
+
* is never sent (the search itself answers a whole pair without a service).
|
|
3742
|
+
* Each change of text aborts the request before it, so an
|
|
3743
|
+
* answer for older text never arrives after a newer one. Nothing is asked
|
|
3744
|
+
* while `enabled` is false, which a caller uses after the person has picked
|
|
3745
|
+
* a suggestion so the box showing its label does not suggest again.
|
|
3746
|
+
*
|
|
3747
|
+
* When the service fails the person is not interrupted: no suggestions show,
|
|
3748
|
+
* and Enter still searches. After {@link SUGGEST_FAILURE_LIMIT} failures in a
|
|
3749
|
+
* row, or one `rate-limited` answer, it stops asking for
|
|
3750
|
+
* {@link SUGGEST_COOLDOWN_MS} and announces once that suggestions are
|
|
3751
|
+
* unavailable and Enter still works. It announces again only after a request
|
|
3752
|
+
* has worked in between. A host without a provider gets no suggestions and no
|
|
3753
|
+
* announcements.
|
|
3754
|
+
*
|
|
3755
|
+
* Counts go out through the app-wide announcer, politely.
|
|
3756
|
+
*/
|
|
3757
|
+
export declare function useSuggestions(query: string, enabled: boolean): readonly SearchResult[];
|
|
3758
|
+
|
|
3759
|
+
/** What {@link useTheme} returns. */
|
|
3760
|
+
export declare interface UseTheme {
|
|
3761
|
+
/** What the user chose: system, light or dark. */
|
|
3762
|
+
readonly choice: ThemeChoice;
|
|
3763
|
+
/** What is actually shown. */
|
|
3764
|
+
readonly resolved: ResolvedTheme;
|
|
3765
|
+
readonly setChoice: (choice: ThemeChoice) => void;
|
|
3766
|
+
}
|
|
3767
|
+
|
|
3768
|
+
/**
|
|
3769
|
+
* Combines the stored theme choice with the system preference, follows system
|
|
3770
|
+
* changes live without a reload, and reflects the result onto the document
|
|
3771
|
+
* through the theme source.
|
|
3772
|
+
*/
|
|
3773
|
+
export declare function useTheme(): UseTheme;
|
|
3774
|
+
|
|
3775
|
+
/** The theme source. Most components want {@link useTheme} instead. */
|
|
3776
|
+
export declare function useThemeSource(): ThemeSource;
|
|
3777
|
+
|
|
3778
|
+
/** What {@link useTour} returns. */
|
|
3779
|
+
export declare interface UseTour {
|
|
3780
|
+
readonly state: TourState;
|
|
3781
|
+
readonly steps: readonly TourStep[];
|
|
3782
|
+
/** The current step while running, else null. */
|
|
3783
|
+
readonly step: TourStep | null;
|
|
3784
|
+
/** Grows each time the card's heading should take focus. */
|
|
3785
|
+
readonly focusRequest: number;
|
|
3786
|
+
/** Starts at the first step, from the welcome card or from Help. */
|
|
3787
|
+
start(): void;
|
|
3788
|
+
/** Goes to the next step, or to the ending after the last. */
|
|
3789
|
+
next(): void;
|
|
3790
|
+
/** Ends the tour from the welcome card or any step. */
|
|
3791
|
+
skip(): void;
|
|
3792
|
+
/** Closes the ending card. */
|
|
3793
|
+
close(): void;
|
|
3794
|
+
}
|
|
3795
|
+
|
|
3796
|
+
/**
|
|
3797
|
+
* Runs the first-visit tour: the welcome card, the steps and the ending.
|
|
3798
|
+
*
|
|
3799
|
+
* @remarks A step advances when the person does what it asks, judged by
|
|
3800
|
+
* `stepDone` against the snapshot taken when the step began, or on Next.
|
|
3801
|
+
* An advance by doing announces the next step and leaves focus where it is;
|
|
3802
|
+
* Next and start ask the card to focus its heading instead. Taking the
|
|
3803
|
+
* tour, skipping it, or turning on a layer while the welcome card is up
|
|
3804
|
+
* stores the version, so the tour is not offered again.
|
|
3805
|
+
*/
|
|
3806
|
+
export declare function useTour({ steps, version, offer, snapshot, }: UseTourOptions): UseTour;
|
|
3807
|
+
|
|
3808
|
+
/** Options for {@link useTour}. */
|
|
3809
|
+
export declare interface UseTourOptions {
|
|
3810
|
+
readonly steps: readonly TourStep[];
|
|
3811
|
+
/** The host's tour version, stored in `Settings.tourSeen` once answered. */
|
|
3812
|
+
readonly version: number;
|
|
3813
|
+
/** Whether to show the welcome card on this page load (`shouldOfferTour`). */
|
|
3814
|
+
readonly offer: boolean;
|
|
3815
|
+
/** The app state now, which decides when a step is done. */
|
|
3816
|
+
readonly snapshot: TourSnapshot;
|
|
3817
|
+
}
|
|
3818
|
+
|
|
3819
|
+
/** The shareable URL state port. */
|
|
3820
|
+
export declare function useUrlState(): UrlState;
|
|
3821
|
+
|
|
3822
|
+
/** How long the map must stay still, in milliseconds, before layers that depend on its view are told it. */
|
|
3823
|
+
export declare const VIEW_SETTLE_MS = 400;
|
|
3824
|
+
|
|
3825
|
+
/**
|
|
3826
|
+
* The one way to provide screen-reader-only text, such as a hidden heading or
|
|
3827
|
+
* keyboard instructions. Nothing else in the app may hide text this way.
|
|
3828
|
+
*/
|
|
3829
|
+
export declare function VisuallyHidden({ as: Component, className, ...rest }: VisuallyHiddenProps): JSX.Element;
|
|
3830
|
+
|
|
3831
|
+
/**
|
|
3832
|
+
* Hides content visually while keeping it available to assistive technology.
|
|
3833
|
+
* The clip pattern, not `display: none`, so screen readers still read it.
|
|
3834
|
+
*
|
|
3835
|
+
* @internal
|
|
3836
|
+
*/
|
|
3837
|
+
export declare const visuallyHidden: string;
|
|
3838
|
+
|
|
3839
|
+
/** Props for {@link VisuallyHidden}. */
|
|
3840
|
+
export declare interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement> {
|
|
3841
|
+
/** The element to render. Defaults to `span`. */
|
|
3842
|
+
readonly as?: ElementType;
|
|
3843
|
+
}
|
|
3844
|
+
|
|
3845
|
+
export { }
|