@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.
- package/LICENSE +21 -0
- package/README.md +109 -2
- package/agent/components/accordion.md +95 -0
- package/agent/components/action-square.md +106 -0
- package/agent/components/agent-bridge.md +87 -0
- package/agent/components/agent-console.md +123 -0
- package/agent/components/alert-dialog.md +82 -0
- package/agent/components/app-shell.md +105 -0
- package/agent/components/area-chart.md +56 -0
- package/agent/components/async-options.md +47 -0
- package/agent/components/autocomplete.md +69 -0
- package/agent/components/avatar.md +88 -0
- package/agent/components/badge.md +51 -0
- package/agent/components/bar-chart.md +56 -0
- package/agent/components/bar-list.md +49 -0
- package/agent/components/breadcrumbs.md +43 -0
- package/agent/components/button.md +109 -0
- package/agent/components/calendar.md +114 -0
- package/agent/components/canvas.md +105 -0
- package/agent/components/card.md +78 -0
- package/agent/components/carousel.md +113 -0
- package/agent/components/chart-card.md +41 -0
- package/agent/components/chart-surface.md +56 -0
- package/agent/components/checkbox.md +88 -0
- package/agent/components/citation-chip.md +61 -0
- package/agent/components/collapsible.md +69 -0
- package/agent/components/color-picker.md +82 -0
- package/agent/components/combobox.md +104 -0
- package/agent/components/command.md +92 -0
- package/agent/components/dashboard-grid.md +73 -0
- package/agent/components/date-input.md +87 -0
- package/agent/components/date-picker.md +122 -0
- package/agent/components/dialog.md +97 -0
- package/agent/components/donut-chart.md +50 -0
- package/agent/components/drawer.md +101 -0
- package/agent/components/empty-state.md +52 -0
- package/agent/components/field.md +80 -0
- package/agent/components/file-input.md +84 -0
- package/agent/components/hover-card.md +64 -0
- package/agent/components/image-cropper.md +77 -0
- package/agent/components/input.md +49 -0
- package/agent/components/label.md +53 -0
- package/agent/components/line-chart.md +60 -0
- package/agent/components/listbox.md +84 -0
- package/agent/components/map-view.md +104 -0
- package/agent/components/menu.md +117 -0
- package/agent/components/menubar.md +67 -0
- package/agent/components/meter.md +59 -0
- package/agent/components/navigation-menu.md +98 -0
- package/agent/components/number-input.md +81 -0
- package/agent/components/otp-input.md +67 -0
- package/agent/components/pagination.md +80 -0
- package/agent/components/password-input.md +67 -0
- package/agent/components/pill-button.md +116 -0
- package/agent/components/popover.md +85 -0
- package/agent/components/poster-card.md +61 -0
- package/agent/components/preferences.md +92 -0
- package/agent/components/progress.md +63 -0
- package/agent/components/provider.md +47 -0
- package/agent/components/radio.md +91 -0
- package/agent/components/rating.md +66 -0
- package/agent/components/reorder.md +61 -0
- package/agent/components/resizable.md +87 -0
- package/agent/components/scatter-chart.md +49 -0
- package/agent/components/scroll-area.md +81 -0
- package/agent/components/segmented-control.md +56 -0
- package/agent/components/select.md +130 -0
- package/agent/components/separator.md +60 -0
- package/agent/components/shortcuts.md +50 -0
- package/agent/components/sidebar-nav.md +68 -0
- package/agent/components/skeleton.md +58 -0
- package/agent/components/slider.md +79 -0
- package/agent/components/sparkline.md +39 -0
- package/agent/components/squircle.md +58 -0
- package/agent/components/stat.md +58 -0
- package/agent/components/switch.md +48 -0
- package/agent/components/table.md +58 -0
- package/agent/components/tabs.md +108 -0
- package/agent/components/textarea.md +68 -0
- package/agent/components/time-input.md +84 -0
- package/agent/components/timeline.md +91 -0
- package/agent/components/toast.md +85 -0
- package/agent/components/toggle.md +76 -0
- package/agent/components/token-input.md +66 -0
- package/agent/components/toolbar.md +76 -0
- package/agent/components/tooltip.md +83 -0
- package/agent/components/tracker.md +47 -0
- package/agent/components/tree.md +87 -0
- package/agent/components/treemap.md +72 -0
- package/agent/components/trend-chart.md +80 -0
- package/agent/components/trigger-menu.md +67 -0
- package/agent/components/typography.md +51 -0
- package/agent/components/waterfall.md +78 -0
- package/agent/components/week-schedule.md +113 -0
- package/agent/llms/actions-and-layout.txt +1749 -0
- package/agent/llms/agents.txt +505 -0
- package/agent/llms/charts.txt +778 -0
- package/agent/llms/dashboards.txt +457 -0
- package/agent/llms/extend.txt +132 -0
- package/agent/llms/extras.txt +527 -0
- package/agent/llms/forms.txt +2152 -0
- package/agent/llms/foundations.txt +674 -0
- package/agent/llms/hooks.txt +178 -0
- package/agent/llms/maps.txt +229 -0
- package/agent/llms/overlays-and-navigation.txt +1167 -0
- package/agent/llms-full.txt +8717 -0
- package/agent/llms.txt +145 -0
- package/agent/registry.json +11289 -0
- package/agent/tokens.md +66 -0
- package/dist/agent/index.d.ts +235 -0
- package/dist/agent/index.js +21 -0
- package/dist/card-Ipm-Cj5f.d.ts +490 -0
- package/dist/charts/index.d.ts +289 -0
- package/dist/charts/index.js +815 -0
- package/dist/check/cli.d.ts +1 -0
- package/dist/check/cli.js +48 -0
- package/dist/check/rendered.d.ts +11 -0
- package/dist/check/rendered.js +77 -0
- package/dist/check/source.d.ts +13 -0
- package/dist/check/source.js +182 -0
- package/dist/chunk-3DXBM65D.js +65 -0
- package/dist/chunk-3H5X4ZP6.js +55 -0
- package/dist/chunk-6XC4BC5C.js +92 -0
- package/dist/chunk-7H6TEAWD.js +507 -0
- package/dist/chunk-I63ZTJOI.js +1089 -0
- package/dist/chunk-JCIRUM4W.js +33 -0
- package/dist/chunk-LTBEHZ3P.js +25 -0
- package/dist/chunk-QDPPLO4U.js +60 -0
- package/dist/chunk-U2XFBPU4.js +56 -0
- package/dist/chunk-UY2WH5AY.js +681 -0
- package/dist/extras.d.ts +203 -0
- package/dist/extras.js +904 -0
- package/dist/icons-BJiGEAnU.d.ts +68 -0
- package/dist/index.d.ts +3737 -0
- package/dist/index.js +14477 -0
- package/dist/map/index.d.ts +115 -0
- package/dist/map/index.js +394 -0
- package/dist/meta/index.d.ts +3314 -0
- package/dist/meta/index.js +5106 -0
- package/dist/rules-1RIZ_JZr.d.ts +38 -0
- package/dist/styles.css +4037 -0
- package/dist/themes/calm.css +42 -0
- package/dist/themes/frost.css +40 -0
- 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
|
+
---
|