@peerproblem/sw3-ui 0.0.0-stage → 0.3.0

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.
Files changed (144) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +109 -2
  3. package/agent/components/accordion.md +95 -0
  4. package/agent/components/action-square.md +106 -0
  5. package/agent/components/agent-bridge.md +87 -0
  6. package/agent/components/agent-console.md +123 -0
  7. package/agent/components/alert-dialog.md +82 -0
  8. package/agent/components/app-shell.md +105 -0
  9. package/agent/components/area-chart.md +56 -0
  10. package/agent/components/async-options.md +47 -0
  11. package/agent/components/autocomplete.md +69 -0
  12. package/agent/components/avatar.md +88 -0
  13. package/agent/components/badge.md +51 -0
  14. package/agent/components/bar-chart.md +56 -0
  15. package/agent/components/bar-list.md +49 -0
  16. package/agent/components/breadcrumbs.md +43 -0
  17. package/agent/components/button.md +109 -0
  18. package/agent/components/calendar.md +114 -0
  19. package/agent/components/canvas.md +105 -0
  20. package/agent/components/card.md +78 -0
  21. package/agent/components/carousel.md +113 -0
  22. package/agent/components/chart-card.md +41 -0
  23. package/agent/components/chart-surface.md +56 -0
  24. package/agent/components/checkbox.md +88 -0
  25. package/agent/components/citation-chip.md +61 -0
  26. package/agent/components/collapsible.md +69 -0
  27. package/agent/components/color-picker.md +82 -0
  28. package/agent/components/combobox.md +104 -0
  29. package/agent/components/command.md +92 -0
  30. package/agent/components/dashboard-grid.md +73 -0
  31. package/agent/components/date-input.md +87 -0
  32. package/agent/components/date-picker.md +122 -0
  33. package/agent/components/dialog.md +97 -0
  34. package/agent/components/donut-chart.md +50 -0
  35. package/agent/components/drawer.md +101 -0
  36. package/agent/components/empty-state.md +52 -0
  37. package/agent/components/field.md +80 -0
  38. package/agent/components/file-input.md +84 -0
  39. package/agent/components/hover-card.md +64 -0
  40. package/agent/components/image-cropper.md +77 -0
  41. package/agent/components/input.md +49 -0
  42. package/agent/components/label.md +53 -0
  43. package/agent/components/line-chart.md +60 -0
  44. package/agent/components/listbox.md +84 -0
  45. package/agent/components/map-view.md +104 -0
  46. package/agent/components/menu.md +117 -0
  47. package/agent/components/menubar.md +67 -0
  48. package/agent/components/meter.md +59 -0
  49. package/agent/components/navigation-menu.md +98 -0
  50. package/agent/components/number-input.md +81 -0
  51. package/agent/components/otp-input.md +67 -0
  52. package/agent/components/pagination.md +80 -0
  53. package/agent/components/password-input.md +67 -0
  54. package/agent/components/pill-button.md +116 -0
  55. package/agent/components/popover.md +85 -0
  56. package/agent/components/poster-card.md +61 -0
  57. package/agent/components/preferences.md +92 -0
  58. package/agent/components/progress.md +63 -0
  59. package/agent/components/provider.md +47 -0
  60. package/agent/components/radio.md +91 -0
  61. package/agent/components/rating.md +66 -0
  62. package/agent/components/reorder.md +61 -0
  63. package/agent/components/resizable.md +87 -0
  64. package/agent/components/scatter-chart.md +49 -0
  65. package/agent/components/scroll-area.md +81 -0
  66. package/agent/components/segmented-control.md +56 -0
  67. package/agent/components/select.md +130 -0
  68. package/agent/components/separator.md +60 -0
  69. package/agent/components/shortcuts.md +50 -0
  70. package/agent/components/sidebar-nav.md +68 -0
  71. package/agent/components/skeleton.md +58 -0
  72. package/agent/components/slider.md +79 -0
  73. package/agent/components/sparkline.md +39 -0
  74. package/agent/components/squircle.md +58 -0
  75. package/agent/components/stat.md +58 -0
  76. package/agent/components/switch.md +48 -0
  77. package/agent/components/table.md +58 -0
  78. package/agent/components/tabs.md +108 -0
  79. package/agent/components/textarea.md +68 -0
  80. package/agent/components/time-input.md +84 -0
  81. package/agent/components/timeline.md +91 -0
  82. package/agent/components/toast.md +85 -0
  83. package/agent/components/toggle.md +76 -0
  84. package/agent/components/token-input.md +66 -0
  85. package/agent/components/toolbar.md +76 -0
  86. package/agent/components/tooltip.md +83 -0
  87. package/agent/components/tracker.md +47 -0
  88. package/agent/components/tree.md +87 -0
  89. package/agent/components/treemap.md +72 -0
  90. package/agent/components/trend-chart.md +80 -0
  91. package/agent/components/trigger-menu.md +67 -0
  92. package/agent/components/typography.md +51 -0
  93. package/agent/components/waterfall.md +78 -0
  94. package/agent/components/week-schedule.md +113 -0
  95. package/agent/llms/actions-and-layout.txt +1749 -0
  96. package/agent/llms/agents.txt +505 -0
  97. package/agent/llms/charts.txt +778 -0
  98. package/agent/llms/dashboards.txt +457 -0
  99. package/agent/llms/extend.txt +132 -0
  100. package/agent/llms/extras.txt +527 -0
  101. package/agent/llms/forms.txt +2152 -0
  102. package/agent/llms/foundations.txt +674 -0
  103. package/agent/llms/hooks.txt +178 -0
  104. package/agent/llms/maps.txt +229 -0
  105. package/agent/llms/overlays-and-navigation.txt +1167 -0
  106. package/agent/llms-full.txt +8717 -0
  107. package/agent/llms.txt +145 -0
  108. package/agent/registry.json +11289 -0
  109. package/agent/tokens.md +66 -0
  110. package/dist/agent/index.d.ts +235 -0
  111. package/dist/agent/index.js +21 -0
  112. package/dist/card-Ipm-Cj5f.d.ts +490 -0
  113. package/dist/charts/index.d.ts +289 -0
  114. package/dist/charts/index.js +815 -0
  115. package/dist/check/cli.d.ts +1 -0
  116. package/dist/check/cli.js +48 -0
  117. package/dist/check/rendered.d.ts +11 -0
  118. package/dist/check/rendered.js +77 -0
  119. package/dist/check/source.d.ts +13 -0
  120. package/dist/check/source.js +182 -0
  121. package/dist/chunk-3DXBM65D.js +65 -0
  122. package/dist/chunk-3H5X4ZP6.js +55 -0
  123. package/dist/chunk-6XC4BC5C.js +92 -0
  124. package/dist/chunk-7H6TEAWD.js +507 -0
  125. package/dist/chunk-I63ZTJOI.js +1089 -0
  126. package/dist/chunk-JCIRUM4W.js +33 -0
  127. package/dist/chunk-LTBEHZ3P.js +25 -0
  128. package/dist/chunk-QDPPLO4U.js +60 -0
  129. package/dist/chunk-U2XFBPU4.js +56 -0
  130. package/dist/chunk-UY2WH5AY.js +681 -0
  131. package/dist/extras.d.ts +203 -0
  132. package/dist/extras.js +904 -0
  133. package/dist/icons-BJiGEAnU.d.ts +68 -0
  134. package/dist/index.d.ts +3737 -0
  135. package/dist/index.js +14477 -0
  136. package/dist/map/index.d.ts +115 -0
  137. package/dist/map/index.js +394 -0
  138. package/dist/meta/index.d.ts +3314 -0
  139. package/dist/meta/index.js +5106 -0
  140. package/dist/rules-1RIZ_JZr.d.ts +38 -0
  141. package/dist/styles.css +4037 -0
  142. package/dist/themes/calm.css +42 -0
  143. package/dist/themes/frost.css +40 -0
  144. package/package.json +142 -4
@@ -0,0 +1,178 @@
1
+ # SW3 UI SDK · Hooks and utilities
2
+
3
+ > useReorder, useAsyncOptions, useShortcut and other hooks for building with SW3.
4
+
5
+ Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in `<SwProvider>`, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`.
6
+ Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps.
7
+ Index of all topics and components: llms.txt.
8
+
9
+ ---
10
+
11
+ # Components
12
+
13
+ # useReorder
14
+
15
+ > The headless drag-and-drop and keyboard reordering behind Listbox and DashboardGrid. Use it for your own sortable rows, chips or columns.
16
+
17
+ Category: hooks · Status: beta · Slug: `reorder`
18
+
19
+ ```tsx
20
+ import { useReorder, moveItem, applyOrder } from '@peerproblem/sw3-ui'
21
+ ```
22
+
23
+ ## When to use
24
+ - A custom reorderable layout that Listbox or DashboardGrid does not cover.
25
+
26
+ ## Avoid
27
+ - Moving items between containers or into groups. This handles reordering within one list.
28
+ - Reimplementing it with HTML5 drag events, which have no keyboard support or announcements.
29
+
30
+ ## Props
31
+
32
+ | Prop | Type | Default | Description |
33
+ | --- | --- | --- | --- |
34
+ | `ids` * | `string[]` | | Item ids in their current order. |
35
+ | `onReorder` * | `(ids, { id, from, to }) => void` | | New order after a drop or a keyboard move. |
36
+ | `orientation` | `'vertical' \| 'horizontal' \| 'grid'` | `'vertical'` | Stacked rows, one row, or wrapping tiles. |
37
+ | `getLabel` | `(id) => string` | | Name used in announcements and the drag preview. |
38
+ | `returns` | `object` | | getContainerProps(), getItemProps(id, { dragFromItem }), getHandleProps(id), moveBy(id, delta), moveTo(id, index), dropIndicator, overlay, dragId, liftedId. |
39
+
40
+ ## Examples
41
+
42
+ ### Sortable chips
43
+
44
+ ```tsx
45
+ const r = useReorder({ ids: tags.map((t) => t.id), orientation: 'horizontal', onReorder: (ids) => setTags(applyOrder(tags, ids, (t) => t.id)), getLabel: (id) => id })
46
+
47
+ <div {...r.getContainerProps()} style={{ position: 'relative', display: 'flex', gap: 6 }}>
48
+ {tags.map((t) => (
49
+ <span key={t.id} {...r.getItemProps(t.id)}>
50
+ <button {...r.getHandleProps(t.id)}><Icon name="grip" /></button>{t.label}
51
+ </span>
52
+ ))}
53
+ {r.dropIndicator}
54
+ {r.overlay}
55
+ </div>
56
+ ```
57
+
58
+ ## Rules
59
+ - Items stay in place while dragging. The source dims to 0.4, a preview follows the pointer, and a 2px line marks the drop point.
60
+ - A drag starts after 5px of movement. Touch drags start only from the handle, so pages still scroll.
61
+ - After a drop, flash the item (built in) and update optimistically.
62
+
63
+ ## Accessibility
64
+ - Handles: Space or Enter lifts, the arrows move, Space or Enter drops, Escape cancels. Every step is announced in a polite live region with the item name and position.
65
+
66
+ ## DOM contract (for agents operating the page)
67
+
68
+ - Selector: `[data-reorder-root]`
69
+ - `data-dragging`: on the item being dragged
70
+ - `data-lifted`: on a keyboard-lifted item
71
+ - `data-flash`: for 700ms after a drop
72
+
73
+ Related: `listbox`, `dashboard-grid`
74
+
75
+ ---
76
+
77
+ # useAsyncOptions
78
+
79
+ > Hook that loads list items as someone types: debounced, cancels stale requests, keeps old results while loading, pages with loadMore.
80
+
81
+ Category: hooks · Status: beta · Slug: `async-options`
82
+
83
+ ```tsx
84
+ import { useAsyncOptions } from '@peerproblem/sw3-ui'
85
+ ```
86
+
87
+ ## When to use
88
+ - Server-side search for Combobox, Select, Autocomplete or Command.
89
+ - Paged results that load as the list scrolls.
90
+
91
+ ## Avoid
92
+ - Fetching in an effect on every keystroke. Use this hook instead.
93
+ - Client-side filtering on top of server results. Turn the component filter off.
94
+
95
+ ## Props
96
+
97
+ | Prop | Type | Default | Description |
98
+ | --- | --- | --- | --- |
99
+ | `loader` * | `(query, { signal, page }) => Promise<T[] \| { items: T[]; hasMore: boolean }>` | | Pass `signal` to fetch so replaced requests cancel. |
100
+ | `options.debounce` | `number` | `200` | Pause in ms before loading. |
101
+ | `options.query` | `string` | `''` | Starting search text. |
102
+ | `options.immediate` | `boolean` | `false` | Load the starting query on mount. |
103
+ | `returns` | `{ query, setQuery, items, status, error, hasMore, loadMore, reload }` | | `status` is 'idle' | 'loading' | 'error'. |
104
+
105
+ ## Examples
106
+
107
+ ### Search as you type
108
+
109
+ ```tsx
110
+ const repos = useAsyncOptions<{ value: string; label: string }>(async (q, { signal }) => {
111
+ const res = await fetch(`/api/repos?q=${encodeURIComponent(q)}`, { signal })
112
+ if (!res.ok) throw new Error('Could not load repos')
113
+ return res.json()
114
+ }, { immediate: true })
115
+
116
+ // <Combobox items={repos.items} onInputChange={repos.setQuery} loading={repos.status === 'loading'} />
117
+ ```
118
+
119
+ ## DOM contract (for agents operating the page)
120
+
121
+ - Selector: `(hook, no DOM)`
122
+
123
+ Related: `combobox`, `select`, `autocomplete`, `command`
124
+
125
+ ---
126
+
127
+ # useShortcut
128
+
129
+ > Keyboard shortcuts with platform-aware hints. `mod` is ⌘ on Apple and Ctrl elsewhere. `shortcuts.list()` exposes them to agents.
130
+
131
+ Category: hooks · Status: beta · Slug: `shortcuts`
132
+
133
+ ```tsx
134
+ import { useShortcut, useShortcutHint, shortcuts, formatShortcut } from '@peerproblem/sw3-ui'
135
+ ```
136
+
137
+ ## When to use
138
+ - App-level actions: save, new, search (⌘K), toggle sidebar.
139
+ - Showing the key next to a button or menu item.
140
+
141
+ ## Avoid
142
+ - Single-letter shortcuts that fire while typing. They are skipped in fields unless `allowInInput`.
143
+ - Overriding browser shortcuts people rely on (⌘W, ⌘T, ⌘L).
144
+
145
+ ## Props
146
+
147
+ | Prop | Type | Default | Description |
148
+ | --- | --- | --- | --- |
149
+ | `useShortcut(keys, handler, options?)` | `(keys: string \| null, handler, { description?, allowInInput?, when?, scope?, preventDefault? })` | | Keys like "mod+s", "shift+?", "escape". Unregisters on unmount; null keys = off. |
150
+ | `useShortcutHint(keys)` | `{ text: string; ariaKeyshortcuts: string }` | | ⌘S / Ctrl+S plus the aria-keyshortcuts value. |
151
+ | `shortcuts.setScope(name, active)` | `void` | | Turn scoped shortcuts on while an area has focus. |
152
+ | `shortcuts.list()` | `{ keys, text, description, scope, active }[]` | | All registered shortcuts (help dialog, agents). |
153
+
154
+ ## Examples
155
+
156
+ ### Save with a hint
157
+
158
+ ```tsx
159
+ function SaveButton({ onSave }: { onSave(): void }) {
160
+ useShortcut('mod+s', onSave, { description: 'Save' })
161
+ const hint = useShortcutHint('mod+s')
162
+ return (
163
+ <Button onClick={onSave} aria-keyshortcuts={hint.ariaKeyshortcuts} trailing={<Kbd>{hint.text}</Kbd>}>Save</Button>
164
+ )
165
+ }
166
+ ```
167
+
168
+ ## Rules
169
+ - Always show the shortcut somewhere (button hint, menu item, help). Hidden shortcuts help nobody.
170
+
171
+ ## DOM contract (for agents operating the page)
172
+
173
+ - Selector: `[aria-keyshortcuts]`
174
+ - How to operate: Agents can read shortcuts.list() or aria-keyshortcuts; prefer the bridge actions over synthesizing key events.
175
+
176
+ Related: `command`, `menu`, `kbd`
177
+
178
+ ---
@@ -0,0 +1,229 @@
1
+ # SW3 UI SDK · Maps
2
+
3
+ > @peerproblem/sw3-ui/map: MapLibre maps with routes, pins and areas, bundler setup.
4
+
5
+ Setup: `import "@peerproblem/sw3-ui/styles.css"` once, wrap the app in `<SwProvider>`, add `className="sw-root"` to the page. Charts: `@peerproblem/sw3-ui/charts`. Maps: `@peerproblem/sw3-ui/map`.
6
+ Optional peers: install `@unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0` for charts or `maplibre-gl@^6.18.0` for maps.
7
+ Index of all topics and components: llms.txt.
8
+
9
+ ---
10
+
11
+ # Maps
12
+
13
+ `MapView` from `@peerproblem/sw3-ui/map` wraps [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/). It follows the "Add a GeoJSON line" example and adds tokens, markers, theming and a squircle frame.
14
+
15
+ ```tsx
16
+ import { MapView } from '@peerproblem/sw3-ui/map'
17
+
18
+ <MapView routes={[{ coordinates }]} markers={[{ lngLat: coordinates[0], kind: 'start', label: 'Start' }]} animateRoutes />
19
+ ```
20
+
21
+ ## Categorized locations
22
+
23
+ Pass `markers` by themselves for a point map. The supported categories are `impact`, `incident`, `shelter`, `closure`, `resource`, and `origin`. Each category uses a distinct glyph and visible label. Give each point a short `label` and add a `description` for details such as opening hours or which lane is closed.
24
+
25
+ ```tsx
26
+ <MapView
27
+ markerListLabel="Emergency locations"
28
+ markers={[
29
+ { lngLat: [24.83, 60.18], kind: 'closure', label: 'Ring I', description: 'Eastbound lane closed.' },
30
+ { lngLat: [24.79, 60.20], kind: 'shelter', label: 'Community center', description: 'Open overnight.' },
31
+ ]}
32
+ />
33
+ ```
34
+
35
+ The list below the map shows each categorized point’s type, name, and description. `markerListLabel` defaults to `Map locations`. Static markers stay out of the tab order.
36
+
37
+ Add `popup: { title: 'Ring I', description: 'Use the westbound detour.' }` to a marker to open a plain-text popup on click. The list provides a keyboard-accessible Show details button. Escape closes the popup and returns focus to its trigger.
38
+
39
+ ## Pins and areas
40
+
41
+ Use `kind: 'pin'` for a named place without an incident category. Pass `areas` for boundaries such as flood advisories or service coverage. They contribute to fit-to-data, and each named area is listed below the map with a zoom button on interactive maps. The tint stays under place labels. Use a solid boundary (the default) for defined extents and `boundary: 'approximate'` for dashed edges on estimated or illustrative extents.
42
+
43
+ ```tsx
44
+ <MapView
45
+ markers={[{ lngLat: [24.79, 60.20], kind: 'pin', label: 'Meeting point' }]}
46
+ areas={[{
47
+ id: 'advisory',
48
+ label: 'Flood advisory area',
49
+ tone: 'warning',
50
+ boundary: 'approximate',
51
+ geometry: { type: 'Polygon', coordinates: [[[24.78, 60.19], [24.81, 60.19], [24.81, 60.21], [24.78, 60.19]]] },
52
+ }]}
53
+ />
54
+ ```
55
+
56
+ ## Map controls
57
+
58
+ The zoom group keeps the `sm` squircle on a full-bleed map (`radius={0}`). Put map actions such as a basemap picker in `controls`. The map aligns this slot below the zoom group and keeps it in place when a basemap changes. Use an accessible, icon-only SW3 `Button` with `size="md"` for the same corner smoothing and control size.
59
+
60
+ ```tsx
61
+ import { Icon, Popover, PopoverContent, PopoverTitle, PopoverTrigger } from '@peerproblem/sw3-ui'
62
+ import { MapView } from '@peerproblem/sw3-ui/map'
63
+
64
+ <MapView
65
+ radius={0}
66
+ controls={
67
+ <Popover>
68
+ <PopoverTrigger variant="secondary" size="md" iconOnly aria-label="Map information" leading={<Icon name="info" />} />
69
+ <PopoverContent align="end" padding="sm">
70
+ <PopoverTitle>Map information</PopoverTitle>
71
+ Pin locations are approximate.
72
+ </PopoverContent>
73
+ </Popover>
74
+ }
75
+ />
76
+ ```
77
+
78
+ ## Bundler setup
79
+
80
+ Resolve the worker from the same MapLibre package as the map. In Vite, set the bundled URL in the app's entry module before rendering any map:
81
+
82
+ ```ts
83
+ import { setWorkerUrl } from 'maplibre-gl'
84
+ import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url'
85
+
86
+ setWorkerUrl(workerUrl)
87
+ ```
88
+
89
+ For Next.js 15+ App Router, resolve the worker from a Client Component. Next emits the worker as a build asset. Pass its URL before mounting the first map because MapLibre shares its worker pool.
90
+
91
+ ```tsx
92
+ 'use client'
93
+
94
+ import { MapView } from '@peerproblem/sw3-ui/map'
95
+
96
+ const workerUrl = new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url).toString()
97
+
98
+ export function IncidentsMap() {
99
+ return <MapView workerUrl={workerUrl} />
100
+ }
101
+ ```
102
+
103
+ In the app's global CSS, layer the vendor stylesheet before SW3 so the map can apply its theme:
104
+
105
+ ```css
106
+ @layer maplibre, sw3;
107
+ @import 'maplibre-gl/dist/maplibre-gl.css' layer(maplibre);
108
+ @import '@peerproblem/sw3-ui/styles.css';
109
+ ```
110
+
111
+ ## Rules
112
+
113
+ - Coordinates are **[longitude, latitude]**, in GeoJSON order.
114
+ - Basemaps come from OpenFreeMap (no API key): `positron` for light and `dark` for dark, switched automatically with `basemap="auto"`. OpenMapTiles and OpenStreetMap credits are visible below the built-in basemaps. Custom styles retain MapLibre’s attribution control.
115
+ - Lines are drawn with a `background`-colored halo so they read on any basemap. The main route uses `--sw-accent`. Secondary routes use chart colors or `dashed`.
116
+ - Use `start` for a filled accent dot at the beginning of a route and `end` for a ring at its finish. `default` shows an ink dot. Labels are mono uppercase.
117
+ - Overlays (e.g. a distance `Stat`) go in `overlay`, inside a small `Card padding="sm"`.
118
+ - For custom layers, use `onLoad(map)` and the raw MapLibre API.
119
+
120
+ ---
121
+
122
+ # Components
123
+
124
+ # MapView
125
+
126
+ > A MapLibre GL map in a squircle Card with routes, pins, categorized locations, and highlighted areas.
127
+
128
+ Category: map · Status: beta · Slug: `map-view`
129
+
130
+ ```tsx
131
+ import { MapView } from '@peerproblem/sw3-ui/map'
132
+ import 'maplibre-gl/dist/maplibre-gl.css'
133
+ ```
134
+
135
+ ## When to use
136
+ - Showing a route, track or path (GeoJSON LineString).
137
+ - Showing locations such as shelters, closures, and emergency resources with or without routes.
138
+ - Highlighting a known advisory, closure or coverage boundary.
139
+
140
+ ## Avoid
141
+ - Forgetting the maplibre-gl CSS import — controls and canvas will be misplaced.
142
+ - Relying on the default MapLibre worker URL in a bundled app. Configure the worker before the first map. See the Maps guide.
143
+ - Thousands of markers — add a GeoJSON circle layer through onLoad instead.
144
+ - Picking line colors by hand — leave `color` unset to use the accent token.
145
+
146
+ ## Props
147
+
148
+ | Prop | Type | Default | Description |
149
+ | --- | --- | --- | --- |
150
+ | `routes` | `Array<{ coordinates: [lng, lat][]; color?: string; width?: number; dashed?: boolean; id?: string }>` | | Lines to draw. Coordinates are [longitude, latitude] — GeoJSON order. |
151
+ | `geojson` | `GeoJSON.Feature \| GeoJSON.FeatureCollection` | | Alternative input: any LineString features. |
152
+ | `markers` | `Array<{ lngLat: [lng, lat]; label?: string; description?: string; kind?: 'default' \| 'start' \| 'end' \| 'pin' \| 'impact' \| 'incident' \| 'shelter' \| 'closure' \| 'resource' \| 'origin' }>` | | Points with or without routes. Categorized markers use a glyph and category label, and appear with their name and optional description in the locations list. |
153
+ | `areas` | `readonly MapArea[]` | | Named GeoJSON Polygon or MultiPolygon regions with a stable id, label, optional description, accent, warning or danger tone, and a defined (solid) or approximate (dashed) boundary. |
154
+ | `areaListLabel` | `string` | `Map areas` | Label for the visible list of regions below the map. |
155
+ | `markerListLabel` | `string` | `Map locations` | Label for the visible list below the map when categorized markers are present. |
156
+ | `MapMarker.popup` | `{ title?: string; description: string }` | | Plain-text details opened by clicking the marker or its Show details button. |
157
+ | `workerUrl` | `string` | | Bundled MapLibre worker URL. See the Maps guide for Next.js. |
158
+ | `fitToData` | `boolean` | `true` | Zoom to fit routes, markers and areas. |
159
+ | `center / zoom` | `[lng, lat] / number` | `first point / 13` | Initial camera when not fitting. |
160
+ | `animateRoutes` | `boolean` | `false` | Draw the lines on with a 1.6s motion animation. |
161
+ | `height` | `number` | `360` | Pixels. |
162
+ | `basemap` | `'auto' \| 'light' \| 'dark' \| 'bright' \| string` | `'auto'` | auto follows the theme (OpenFreeMap positron/dark, no API key). Or any MapLibre style URL. |
163
+ | `interactive` | `boolean` | `true` | Pan/zoom + zoom buttons. |
164
+ | `overlay` | `ReactNode` | | Content pinned 12px from the top and left edges. Use <Squircle concentric borderWidth={0}> for an overlay surface that follows the map’s radius minus the inset and inherits its smoothing. |
165
+ | `controls` | `ReactNode` | | Additional actions below the zoom group (top-right). Use an icon-only Button with size="md" and an accessible name. |
166
+ | `onLoad` | `(map: maplibregl.Map) => void` | | Escape hatch for custom layers. |
167
+ | `radius` | `RadiusValue` | `'lg'` | Squircle corners of the frame. |
168
+
169
+ ## Examples
170
+
171
+ ### Route with start/end
172
+
173
+ ```tsx
174
+ const route: [number, number][] = [
175
+ [-122.48369693756104, 37.83381888486939],
176
+ [-122.48348236083984, 37.83317489144141],
177
+ // …
178
+ [-122.49378204345702, 37.83368330777276],
179
+ ]
180
+
181
+ <MapView
182
+ height={420}
183
+ animateRoutes
184
+ routes={[{ coordinates: route }]}
185
+ markers={[
186
+ { lngLat: route[0], kind: 'start', label: 'Start' },
187
+ { lngLat: route[route.length - 1], kind: 'end', label: 'Finish' },
188
+ ]}
189
+ />
190
+ ```
191
+
192
+ ### Emergency locations
193
+
194
+ ```tsx
195
+ <MapView
196
+ markerListLabel="Emergency locations"
197
+ areas={[{
198
+ id: 'advisory', label: 'Flood advisory area', tone: 'warning', boundary: 'approximate',
199
+ geometry: { type: 'Polygon', coordinates: [[[24.78, 60.19], [24.81, 60.19], [24.81, 60.21], [24.78, 60.19]]] },
200
+ }]}
201
+ markers={[
202
+ { lngLat: [24.79, 60.20], kind: 'pin', label: 'Meeting point' },
203
+ { lngLat: [24.83, 60.18], kind: 'closure', label: 'Ring I', description: 'Eastbound lane closed.' },
204
+ { lngLat: [24.79, 60.20], kind: 'shelter', label: 'Community center', description: 'Open overnight.' },
205
+ ]}
206
+ />
207
+ ```
208
+
209
+ ## Rules
210
+ - Pass coordinates in GeoJSON order: [longitude, latitude].
211
+ - Use one accent route and style additional routes with chart tokens or the dashed option.
212
+ - Supply a short location name and put useful details in description for pins, categorized markers and areas.
213
+ - Use approximate for estimated extent and defined for a known boundary. The map renders a subtle tint below place labels.
214
+ - Close each polygon ring by repeating its first coordinate. Keep map credits visible for the selected basemap.
215
+ - The zoom group uses its own sm squircle, including when the map frame is square. Use controls for nearby map actions.
216
+
217
+ ## Accessibility
218
+ - Give the surrounding section a heading that describes the map.
219
+ - Categorized points use glyphs and text labels so categories can be distinguished without color.
220
+ - The locations list below the map provides each categorized point’s type, name and description as readable text. Static markers do not add tab stops. Areas have names and textual boundary status in a separate list. In interactive maps, each area has a keyboard-accessible zoom button.
221
+
222
+ ## DOM contract (for agents operating the page)
223
+
224
+ - Selector: `[data-sw="map"]`
225
+ - `[data-sw="map-marker"]`: marker elements with data-kind and text labels
226
+ - `[data-sw="map-controls"]`: additional map actions supplied by the app
227
+ - How to operate: Read area names and boundary status in the areas list and use its zoom buttons to inspect boundaries. Read location details in the locations list. Use onLoad to expose the map instance if an agent must control the camera.
228
+
229
+ ---