@konce-pt/angular 0.11.2 → 0.14.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/CHANGELOG.md +792 -333
- package/README.md +111 -55
- package/charts/src/lib/llms.txt +23 -15
- package/chat/src/lib/llms.txt +68 -33
- package/fesm2022/konce-pt-angular-charts.mjs +149 -68
- package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-chat.mjs +296 -135
- package/fesm2022/konce-pt-angular-chat.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-grid.mjs +16 -16
- package/fesm2022/konce-pt-angular-grid.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-icons.mjs +5 -5
- package/fesm2022/konce-pt-angular-icons.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-map.mjs +360 -293
- package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-roadmap.mjs +120 -34
- package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
- package/fesm2022/konce-pt-angular.mjs +7117 -3373
- package/fesm2022/konce-pt-angular.mjs.map +1 -1
- package/grid/src/lib/llms.txt +18 -18
- package/map/src/lib/llms.txt +142 -140
- package/package.json +14 -12
- package/roadmap/src/lib/llms.txt +37 -27
- package/src/lib/accordion/llms.txt +18 -6
- package/src/lib/alert/llms.txt +5 -4
- package/src/lib/app-shell/llms.txt +25 -22
- package/src/lib/auth/llms.txt +26 -22
- package/src/lib/autocomplete/llms.txt +18 -4
- package/src/lib/avatar/llms.txt +3 -3
- package/src/lib/avatar-group/llms.txt +5 -5
- package/src/lib/backdrop/llms.txt +35 -35
- package/src/lib/badge/llms.txt +7 -7
- package/src/lib/bottom-sheet/llms.txt +6 -3
- package/src/lib/breadcrumb/llms.txt +9 -1
- package/src/lib/breakpoint/llms.txt +8 -8
- package/src/lib/button/llms.txt +26 -18
- package/src/lib/button-group/llms.txt +40 -31
- package/src/lib/card/llms.txt +19 -19
- package/src/lib/carousel/llms.txt +6 -6
- package/src/lib/checkbox/llms.txt +17 -2
- package/src/lib/chip/llms.txt +6 -6
- package/src/lib/chips-input/llms.txt +14 -4
- package/src/lib/color-picker/llms.txt +7 -4
- package/src/lib/confirm/llms.txt +9 -3
- package/src/lib/context-menu/llms.txt +7 -4
- package/src/lib/data-table/llms.txt +280 -227
- package/src/lib/data-view/llms.txt +25 -4
- package/src/lib/date-range/llms.txt +37 -18
- package/src/lib/datepicker/llms.txt +46 -29
- package/src/lib/dialog/llms.txt +29 -26
- package/src/lib/divider/llms.txt +2 -1
- package/src/lib/drawer/llms.txt +9 -6
- package/src/lib/empty/llms.txt +4 -4
- package/src/lib/fab/llms.txt +6 -2
- package/src/lib/fieldset/llms.txt +22 -4
- package/src/lib/file-upload/llms.txt +3 -0
- package/src/lib/form-field/llms.txt +33 -19
- package/src/lib/galleria/llms.txt +3 -3
- package/src/lib/i18n/llms.txt +15 -8
- package/src/lib/icon/llms.txt +9 -9
- package/src/lib/icon-button/llms.txt +8 -3
- package/src/lib/image/llms.txt +4 -4
- package/src/lib/input/llms.txt +21 -7
- package/src/lib/input-mask/llms.txt +5 -2
- package/src/lib/input-number/llms.txt +18 -15
- package/src/lib/input-otp/llms.txt +15 -4
- package/src/lib/knob/llms.txt +14 -7
- package/src/lib/listbox/llms.txt +8 -5
- package/src/lib/loader/llms.txt +72 -0
- package/src/lib/megamenu/llms.txt +16 -5
- package/src/lib/mention/llms.txt +15 -15
- package/src/lib/menu/llms.txt +12 -12
- package/src/lib/menubar/llms.txt +16 -5
- package/src/lib/meter-group/llms.txt +7 -7
- package/src/lib/order-list/llms.txt +20 -5
- package/src/lib/paginator/llms.txt +5 -5
- package/src/lib/panel/llms.txt +20 -8
- package/src/lib/password/llms.txt +17 -5
- package/src/lib/peek/llms.txt +11 -11
- package/src/lib/pick-list/llms.txt +28 -5
- package/src/lib/popover/llms.txt +9 -6
- package/src/lib/progress/llms.txt +16 -16
- package/src/lib/radio-group/llms.txt +13 -3
- package/src/lib/rating/llms.txt +13 -6
- package/src/lib/rich-text/llms.txt +42 -24
- package/src/lib/scroll-top/llms.txt +3 -3
- package/src/lib/select/llms.txt +23 -13
- package/src/lib/sidenav/llms.txt +8 -8
- package/src/lib/slider/llms.txt +23 -7
- package/src/lib/speech/llms.txt +108 -0
- package/src/lib/speed-dial/llms.txt +9 -3
- package/src/lib/spinner/llms.txt +2 -2
- package/src/lib/split-button/llms.txt +14 -8
- package/src/lib/splitter/llms.txt +8 -8
- package/src/lib/stepper/llms.txt +26 -7
- package/src/lib/switch/llms.txt +13 -3
- package/src/lib/switch-group/llms.txt +12 -9
- package/src/lib/tabs/llms.txt +7 -4
- package/src/lib/textarea/llms.txt +16 -5
- package/src/lib/timeline/llms.txt +1 -1
- package/src/lib/toast/llms.txt +36 -5
- package/src/lib/toolbar/llms.txt +3 -3
- package/src/lib/tooltip/llms.txt +13 -10
- package/src/lib/tree/llms.txt +19 -5
- package/src/lib/update/llms.txt +52 -0
- package/types/konce-pt-angular-charts.d.ts +11 -0
- package/types/konce-pt-angular-charts.d.ts.map +1 -1
- package/types/konce-pt-angular-chat.d.ts +98 -40
- package/types/konce-pt-angular-chat.d.ts.map +1 -1
- package/types/konce-pt-angular-grid.d.ts +14 -14
- package/types/konce-pt-angular-icons.d.ts +3 -3
- package/types/konce-pt-angular-map.d.ts +147 -119
- package/types/konce-pt-angular-map.d.ts.map +1 -1
- package/types/konce-pt-angular-roadmap.d.ts +34 -9
- package/types/konce-pt-angular-roadmap.d.ts.map +1 -1
- package/types/konce-pt-angular.d.ts +1774 -651
- package/types/konce-pt-angular.d.ts.map +1 -1
package/map/src/lib/llms.txt
CHANGED
|
@@ -9,14 +9,14 @@ Import: `import { KptMap, KptMapPoiCard, KptMapSearch } from '@konce-pt/angular/
|
|
|
9
9
|
|
|
10
10
|
## Requirements (the application)
|
|
11
11
|
|
|
12
|
-
What follows is for the default engine, Leaflet. The alternative
|
|
12
|
+
What follows is for the default engine, Leaflet. The alternative - Google Maps - needs no package
|
|
13
13
|
and no stylesheet, but it does need an API key and a `mapId`; see the "Engines" section.
|
|
14
14
|
|
|
15
|
-
1. The **optional** `leaflet` dependency
|
|
15
|
+
1. The **optional** `leaflet` dependency - the library does not install it:
|
|
16
16
|
|
|
17
17
|
pnpm add leaflet
|
|
18
18
|
|
|
19
|
-
2. Leaflet's stylesheet
|
|
19
|
+
2. Leaflet's stylesheet - like `@angular/cdk/overlay-prebuilt.css`, through `angular.json -> styles[]`,
|
|
20
20
|
NOT as an `import` in `main.ts` (the Angular CLI would turn that into an orphaned chunk):
|
|
21
21
|
|
|
22
22
|
node_modules/leaflet/dist/leaflet.css
|
|
@@ -27,69 +27,71 @@ and no stylesheet, but it does need an API key and a `mapId`; see the "Engines"
|
|
|
27
27
|
|
|
28
28
|
bootstrapApplication(App, { providers: [provideKptLeafletMap()] });
|
|
29
29
|
|
|
30
|
-
Without the `leaflet` package installed the component still compiles and imports without error
|
|
30
|
+
Without the `leaflet` package installed the component still compiles and imports without error -
|
|
31
31
|
only an attempt to render the map ends with a readable message and instructions.
|
|
32
32
|
Leaflet is loaded with a dynamic `import()`, so it does not weigh down applications that use no map.
|
|
33
33
|
|
|
34
34
|
## Selector
|
|
35
35
|
|
|
36
|
-
`kpt-map`
|
|
36
|
+
`kpt-map` - a block element. The height is set by `[height]` (default `480px`).
|
|
37
37
|
|
|
38
38
|
## Inputs
|
|
39
39
|
|
|
40
|
-
- `locations`: `readonly KptMapLocation<T>[]`
|
|
41
|
-
- `categories`: `readonly KptMapCategory[]`
|
|
42
|
-
- `country`: `string` = `'PL'`
|
|
43
|
-
- `view`: `{ center, zoom } | null`
|
|
44
|
-
- `bounds`: `KptMapBounds | null`
|
|
45
|
-
- `restrictToCountry`: `boolean` = `false`
|
|
40
|
+
- `locations`: `readonly KptMapLocation<T>[]` - **required**
|
|
41
|
+
- `categories`: `readonly KptMapCategory[]` - **required**
|
|
42
|
+
- `country`: `string` = `'PL'` - the initial view preset; an unknown code falls back to Poland
|
|
43
|
+
- `view`: `{ center, zoom } | null` - an explicit view; overrides `country`
|
|
44
|
+
- `bounds`: `KptMapBounds | null` - explicit bounds; override `country` and `view`
|
|
45
|
+
- `restrictToCountry`: `boolean` = `false` - blocks panning outside the country's bounds/`bounds`
|
|
46
46
|
- `cluster`: `boolean` = `true`
|
|
47
|
-
- `clusterOptions`: `{ gridSize?, maxZoom?, minPoints? }`
|
|
48
|
-
- `clusterColorBy`: `'dominant' | 'none'` = `'none'`
|
|
49
|
-
- `legend`: `boolean` = `true`
|
|
50
|
-
- `legendCounts`: `boolean` = `true`
|
|
47
|
+
- `clusterOptions`: `{ gridSize?, maxZoom?, minPoints? }` - `60 / 16 / 2` by default
|
|
48
|
+
- `clusterColorBy`: `'dominant' | 'none'` = `'none'` - whether a cluster takes the color of its most numerous category
|
|
49
|
+
- `legend`: `boolean` = `true` - renders `kpt-map-legend` below the map
|
|
50
|
+
- `legendCounts`: `boolean` = `true` - counters next to the legend entries
|
|
51
51
|
- `showUserLocation`: `boolean` = `false`
|
|
52
|
-
- `followUser`: `boolean` = `false`
|
|
53
|
-
- `allowCreate`: `boolean` = `false`
|
|
54
|
-
- `search`: `boolean` = `false`
|
|
52
|
+
- `followUser`: `boolean` = `false` - recenters the map on every new position
|
|
53
|
+
- `allowCreate`: `boolean` = `false` - an "Add location" menu under the right mouse button
|
|
54
|
+
- `search`: `boolean` = `false` - the address search in the map's corner; it requires the
|
|
55
55
|
`KPT_MAP_GEOCODER` port **with a `search()` method**, and without it the field does not render
|
|
56
|
-
- `searchPlaceholder`: `string` = `''`
|
|
57
|
-
- `searchOptions`: `{ minLength?, debounce?, limit?, countryCodes? }`
|
|
58
|
-
- `searchZoom`: `number` = `16`
|
|
59
|
-
- `searchMarker`: `boolean` = `true`
|
|
60
|
-
- `
|
|
56
|
+
- `searchPlaceholder`: `string` = `''` - an empty value hands it over to the dictionary
|
|
57
|
+
- `searchOptions`: `{ minLength?, debounce?, limit?, countryCodes? }` - `3 / 300 / 5` by default
|
|
58
|
+
- `searchZoom`: `number` = `16` - the zoom for a result with no bounds of its own
|
|
59
|
+
- `searchMarker`: `boolean` = `true` - a temporary pin at the found point
|
|
60
|
+
- `searchSpeech`: `boolean` = `false` - a microphone in the search field: a click clears the phrase and one spoken utterance becomes the query (same `debounce`/`minLength` as typing); `searchSpeechLang`: `string | null` - its language (BCP 47); `searchSpeechColor` - listening colour (theme colour by default). Hidden without browser support. `kpt-map-search` on its own takes `speech` / `speechLang` / `speechColor`
|
|
61
|
+
- `geocoder`: `KptMapGeocoderPort | null` = `null` - **this** map's geocoder; it wins over
|
|
61
62
|
`KPT_MAP_GEOCODER` from DI and serves both directions: the search and the address suggestions
|
|
62
63
|
in the create form
|
|
63
|
-
- `popupLayout`: `'plain' | 'card'` = `'plain'`
|
|
64
|
+
- `popupLayout`: `'plain' | 'card'` = `'plain'` - `card` hands the popup over to the content entirely:
|
|
64
65
|
no padding, wider (`--kpt-map-popup-width-card`), scrolling once it exceeds
|
|
65
66
|
`--kpt-map-popup-max-height`, and no built-in close button (the card supplies one)
|
|
66
|
-
- `distanceFrom`: `KptLatLng | null` = `null`
|
|
67
|
+
- `distanceFrom`: `KptLatLng | null` = `null` - the reference point for the distance handed
|
|
67
68
|
to the popup template; `null` means "the user's position from `KPT_MAP_GEOLOCATION`"
|
|
68
69
|
- `height`: `string` = `'480px'`
|
|
69
|
-
- `tileUrl`: `string | null`
|
|
70
|
-
- `attribution`: `string | null`
|
|
71
|
-
- `engine`: `KptMapEngineFactory | null`
|
|
70
|
+
- `tileUrl`: `string | null` - OSM tiles by default (see "Tiles" below); **irrelevant for the Google engine**
|
|
71
|
+
- `attribution`: `string | null` - `© OpenStreetMap contributors` by default; likewise
|
|
72
|
+
- `engine`: `KptMapEngineFactory | null` - this map's engine; it wins over `KPT_MAP_ENGINE` from DI
|
|
72
73
|
(see "Engines")
|
|
73
74
|
|
|
74
75
|
## Model / events
|
|
75
76
|
|
|
76
|
-
- `hiddenCategories`: `model<string[]>`
|
|
77
|
+
- `hiddenCategories`: `model<string[]>` - the ids of categories hidden in the legend
|
|
77
78
|
- `locationClick`: `KptMapLocation<T>`
|
|
78
79
|
- `clusterClick`: `KptMapCluster<T>`
|
|
79
|
-
- `locationCreate`: `{ at, categoryId, value }`
|
|
80
|
+
- `locationCreate`: `{ at, categoryId, value }` - the component appends **nothing** to `locations`;
|
|
80
81
|
the application is the source of truth
|
|
81
|
-
- `searchSelect`: `KptMapSearchResult`
|
|
82
|
-
- `viewChange`: `{ center, zoom, bounds }`
|
|
82
|
+
- `searchSelect`: `KptMapSearchResult` - a suggestion was picked; the map has **already** moved the view itself
|
|
83
|
+
- `viewChange`: `{ center, zoom, bounds }` - after the map's movement ends
|
|
83
84
|
- `userPositionChange`: `KptMapUserPosition | null`
|
|
84
85
|
- `userLocationError`: `KptMapGeolocationError`
|
|
86
|
+
- `engineError`: `unknown` - the engine failed to start (no factory, no `leaflet` package, a rejected Google key); the error is also logged to the console, and destroying the component mid-`init()` waits for it to finish
|
|
85
87
|
|
|
86
88
|
## KptMapCategory
|
|
87
89
|
|
|
88
90
|
{ id: 'closure', label: 'Closure', color: 'danger', icon: 'lock',
|
|
89
|
-
shape: 'pin', legend: true, fields: [
|
|
91
|
+
shape: 'pin', legend: true, fields: [ ... ] }
|
|
90
92
|
|
|
91
93
|
`color` is a role from the semantic layer (`primary | success | warning | danger | info | muted`)
|
|
92
|
-
or a ready `var(--kpt-*)`. Literals (`#c00`, `rgb(...)`) are blocked at the type level
|
|
94
|
+
or a ready `var(--kpt-*)`. Literals (`#c00`, `rgb(...)`) are blocked at the type level -
|
|
93
95
|
the repo's contract requires tokens.
|
|
94
96
|
|
|
95
97
|
A role yields **three** variables, depending on what the element is:
|
|
@@ -101,7 +103,7 @@ A role yields **three** variables, depending on what the element is:
|
|
|
101
103
|
| `foregroundVarOf()` | a glyph standing straight on the surface, with no background | `--kpt-color-on-surface-muted` |
|
|
102
104
|
|
|
103
105
|
Getting it wrong only hurts with `muted`, because it is the only role whose `--kpt-color-*` is a background
|
|
104
|
-
color rather than a content one
|
|
106
|
+
color rather than a content one - the rest are saturated and read fine in either function. Hence the third function:
|
|
105
107
|
the place card paints the category icon straight onto the card's background, and `colorVarOf()` would give it
|
|
106
108
|
neutral-100 on white. `icon` is a name from `KptIconRegistry` (the full Tabler set comes with
|
|
107
109
|
`provideKptTablerIcons()`). `shape`: `pin` (the default, anchored at the tip), `dot`, `square`.
|
|
@@ -109,20 +111,20 @@ neutral-100 on white. `icon` is a name from `KptIconRegistry` (the full Tabler s
|
|
|
109
111
|
## KptMapLocation
|
|
110
112
|
|
|
111
113
|
{ id: 'w1', at: { lat: 51.11, lng: 17.04 }, categoryId: 'opening',
|
|
112
|
-
title: '2210
|
|
114
|
+
title: '2210, Wrocław', data: { ... } }
|
|
113
115
|
|
|
114
|
-
`title` is required
|
|
116
|
+
`title` is required - it goes into the marker's `aria-label`. `data` is arbitrary and is handed
|
|
115
117
|
to the popup template.
|
|
116
118
|
|
|
117
119
|
## Templates
|
|
118
120
|
|
|
119
|
-
`kptMapPopup`
|
|
121
|
+
`kptMapPopup` - the details popup, chosen by category. A template with no `category` attribute
|
|
120
122
|
is the fallback; with no template at all the component shows the title and the category name.
|
|
121
123
|
|
|
122
124
|
<kpt-map [locations]="locations()" [categories]="categories">
|
|
123
125
|
<ng-template kptMapPopup category="closure" let-loc let-d="data">
|
|
124
126
|
<strong>{{ loc.title }}</strong>
|
|
125
|
-
<p>Closure
|
|
127
|
+
<p>Closure, {{ d.status }}</p>
|
|
126
128
|
<kpt-button size="sm" (click)="openCard(loc)">Open the project card</kpt-button>
|
|
127
129
|
</ng-template>
|
|
128
130
|
<ng-template kptMapPopup let-loc><strong>{{ loc.title }}</strong></ng-template>
|
|
@@ -132,10 +134,10 @@ Context: `$implicit` = the location, `data` = `location.data` (typed `T | undefi
|
|
|
132
134
|
is optional), `category`, `distance`, `close()`.
|
|
133
135
|
|
|
134
136
|
`distance` is the point's distance in **meters** from `[distanceFrom]`, or from the user's position
|
|
135
|
-
without it. `null` when there is no reference point
|
|
137
|
+
without it. `null` when there is no reference point - geolocation is disabled or was refused.
|
|
136
138
|
Format it with `formatDistance(meters, locale)` from the core; `kpt-map-poi-card` does it itself.
|
|
137
139
|
|
|
138
|
-
The type of `data` is loose by default
|
|
140
|
+
The type of `data` is loose by default - Angular does not carry the generic from `kpt-map` onto a directive
|
|
139
141
|
embedded in its content. If you want inference, bind `[kptMapPopupTypeFor]` to the same array you feed
|
|
140
142
|
the map (the input exists solely for that and is unused at runtime):
|
|
141
143
|
|
|
@@ -144,9 +146,9 @@ the map (the input exists solely for that and is unused at runtime):
|
|
|
144
146
|
</ng-template>
|
|
145
147
|
|
|
146
148
|
A popup opened near the container's edge pans the map so that it fits (auto-pan measures it
|
|
147
|
-
after the first render
|
|
149
|
+
after the first render - before that we do not know its dimensions).
|
|
148
150
|
|
|
149
|
-
`kptMapCreateForm`
|
|
151
|
+
`kptMapCreateForm` - your own create form. Its presence disables the form built
|
|
150
152
|
from the category schema.
|
|
151
153
|
|
|
152
154
|
<ng-template kptMapCreateForm let-api>
|
|
@@ -176,66 +178,66 @@ rows (phone, website, e-mail, coordinates) with actions and copy-to-clipboard.
|
|
|
176
178
|
|
|
177
179
|
Inputs:
|
|
178
180
|
|
|
179
|
-
- `poi`: `KptMapPoi`
|
|
180
|
-
- `distance`: `number | null` = `null`
|
|
181
|
-
- `category`: `KptMapCategory | null` = `null`
|
|
182
|
-
- `primaryLabel`: `string` = `''`
|
|
181
|
+
- `poi`: `KptMapPoi` - **required**
|
|
182
|
+
- `distance`: `number | null` = `null` - meters; `null` hides the distance row
|
|
183
|
+
- `category`: `KptMapCategory | null` = `null` - the icon, the color and the label of the category row
|
|
184
|
+
- `primaryLabel`: `string` = `''` - an empty value hides the primary button
|
|
183
185
|
- `showShare`, `showFavourite`, `closable`: `boolean` = `true`
|
|
184
186
|
- `favourite`: `model<boolean>` = `false`
|
|
185
187
|
- `hoursExpanded`: `model<boolean>` = `false`
|
|
186
188
|
|
|
187
189
|
Outputs: `primaryAction: KptMapPoi`, `closed: void`, `shared: KptMapPoi`.
|
|
188
190
|
|
|
189
|
-
`KptMapPoi` is **separate from the domain model**
|
|
191
|
+
`KptMapPoi` is **separate from the domain model** - the `location.data -> KptMapPoi` mapping is done by
|
|
190
192
|
the application. The library does not guess which field is the phone number:
|
|
191
193
|
|
|
192
194
|
{ title, address?, photo?, photoAlt?, hours?, phone?, email?, website?, at?,
|
|
193
195
|
facts?: [{ icon?, label, value }] }
|
|
194
196
|
|
|
195
|
-
`photo` takes a URL or a `data:` string
|
|
196
|
-
with an icon instead of collapsing the frame to zero. `facts` are arbitrary "icon
|
|
197
|
+
`photo` takes a URL or a `data:` string - the card does not tell them apart. Without one it draws a placeholder
|
|
198
|
+
with an icon instead of collapsing the frame to zero. `facts` are arbitrary "icon, label, value" rows below the contacts.
|
|
197
199
|
|
|
198
200
|
Behaviors worth remembering:
|
|
199
201
|
|
|
200
|
-
- **The photo** sits in a 16:9 frame with `object-fit: cover` on a plain `<img>`, not on `kpt-image`
|
|
202
|
+
- **The photo** sits in a 16:9 frame with `object-fit: cover` on a plain `<img>`, not on `kpt-image` -
|
|
201
203
|
that one is `inline-block` with `height: auto` and will not hold the frame.
|
|
202
204
|
- **The hours** are a native disclosure (`aria-expanded` + `aria-controls`), not a `kpt-accordion`:
|
|
203
205
|
`KptAccordionPanel.title` accepts a plain string, while the header has to fit an icon, a colored
|
|
204
206
|
status and a chevron. The status is computed by `isOpenAt()`; days are joined by `groupWeek()`.
|
|
205
207
|
- **The row actions** are always in the DOM. They are hidden only by `@media (hover: hover) and
|
|
206
|
-
(pointer: fine)`, and `:hover`/`:focus-within` reveals them
|
|
208
|
+
(pointer: fine)`, and `:hover`/`:focus-within` reveals them - on touch and from the keyboard
|
|
207
209
|
they are available without any tricks.
|
|
208
210
|
- **Copying** goes through `navigator.clipboard`; without that API the button does not render.
|
|
209
211
|
On success the icon changes to `check`, and a message goes to `aria-live`.
|
|
210
212
|
- **Sharing** calls `navigator.share()`, and without it copies the address. The user canceling the sheet
|
|
211
213
|
is not an error and emits no `shared`.
|
|
212
214
|
- **The title is a `<p role="heading" aria-level="3">`, not an `<h3>`.** Component styles live
|
|
213
|
-
in `@layer kpt.components`, and an application's CSS outside any layer always beats them
|
|
214
|
-
`<h3>` would catch every `h3 {
|
|
215
|
+
in `@layer kpt.components`, and an application's CSS outside any layer always beats them - a plain
|
|
216
|
+
`<h3>` would catch every `h3 { ... }` rule from the page's layout (in the playground that turned the place title
|
|
215
217
|
into 13-pixel uppercase). To a screen reader it is still a level 3 heading.
|
|
216
|
-
- The card does not set its own `role` on the host
|
|
218
|
+
- The card does not set its own `role` on the host - the `kpt-map` popup is already `role="dialog"`.
|
|
217
219
|
|
|
218
220
|
Anatomy and scrolling:
|
|
219
221
|
|
|
220
222
|
kpt-map-poi-card
|
|
221
|
-
.kpt-map-poi__head title + close button
|
|
222
|
-
.kpt-map-poi__meta distance + address
|
|
223
|
+
.kpt-map-poi__head title + close button - fixed
|
|
224
|
+
.kpt-map-poi__meta distance + address - fixed
|
|
223
225
|
.kpt-map-poi__scroll photo, actions, category, hours, contacts, aria-live
|
|
224
226
|
|
|
225
227
|
The header stays put, and only `__scroll` scrolls. The distance and the address belong to the header
|
|
226
|
-
block, because they are part of the place's identity
|
|
228
|
+
block, because they are part of the place's identity - to make them scroll with the content,
|
|
227
229
|
just move `__meta` into `__scroll`.
|
|
228
230
|
|
|
229
231
|
The condition for this is that `popupLayout="card"` **hands scrolling to the card**: `.kpt-map__popup-body`
|
|
230
232
|
then gets `display: flex` and `overflow: hidden`, and the card the popup's full height. As long as
|
|
231
233
|
the parent container scrolls, the header cannot be pinned without `sticky` and negative margins.
|
|
232
|
-
The popup itself does not get `overflow: hidden`
|
|
234
|
+
The popup itself does not get `overflow: hidden` - the `::after` arrow hangs at `top: 100%` and would be
|
|
233
235
|
cut off. A card outside a popup (stories, any wrapper with no height limit) does not scroll
|
|
234
236
|
at all: `__scroll` has `flex: 0 1 auto` and simply grows without a height ceiling.
|
|
235
237
|
|
|
236
238
|
## Adding locations
|
|
237
239
|
|
|
238
|
-
Right-click
|
|
240
|
+
Right-click -> a menu of categories -> a `kpt-dialog` with a form. By default the form is built
|
|
239
241
|
from `category.fields` on Signal Forms. Field types and controls:
|
|
240
242
|
|
|
241
243
|
| `type` | control | notes |
|
|
@@ -246,25 +248,25 @@ from `category.fields` on Signal Forms. Field types and controls:
|
|
|
246
248
|
| `date` | `kpt-datepicker` | `min`/`max` as ISO dates |
|
|
247
249
|
| `select` / `multiselect` | `kpt-select` (`multiple`) | requires `options` |
|
|
248
250
|
| `checkbox` | `kpt-checkbox` | `placeholder` serves as the label next to the field |
|
|
249
|
-
| `tel` | `kpt-input type="tel"` | no format validation
|
|
251
|
+
| `tel` | `kpt-input type="tel"` | no format validation - phone numbers can be odd |
|
|
250
252
|
| `email` | `kpt-input type="email"` | the `email()` validator |
|
|
251
|
-
| `url` | `kpt-input type="url"` | the `https
|
|
253
|
+
| `url` | `kpt-input type="url"` | the `https?://...` pattern |
|
|
252
254
|
| `image` | `kpt-map-image-field` | a file picker **or** a pasted URL; the value is a `string` |
|
|
253
255
|
| `hours` | `kpt-map-hours-field` | the value is a `KptMapOpeningHours` |
|
|
254
256
|
|
|
255
257
|
The coordinates from the click are shown but not editable.
|
|
256
258
|
|
|
257
|
-
`image` reads the file with `FileReader.readAsDataURL()` and **sends it nowhere**
|
|
259
|
+
`image` reads the file with `FileReader.readAsDataURL()` and **sends it nowhere** - the library knows
|
|
258
260
|
nothing about the application's storage. The 2 MB limit is real, not decorative: a data URL swells by about a third,
|
|
259
261
|
and the whole value travels in `locationCreate`. Typing a URL clears the chosen file and vice versa.
|
|
260
262
|
|
|
261
263
|
`hours` gives seven rows starting on Monday (day names from `Intl`, not from the dictionary), two
|
|
262
264
|
ranges per day, a "closed" marker and a "same all week" shortcut that copies
|
|
263
|
-
Monday onto the rest. A day not marked as closed must have both times
|
|
265
|
+
Monday onto the rest. A day not marked as closed must have both times - otherwise
|
|
264
266
|
the form is `invalid`.
|
|
265
267
|
|
|
266
268
|
The time is picked on a `kpt-datepicker selectionMode="time"` (a clock dial, `minuteStep=5`),
|
|
267
|
-
not on a native `<input type="time">`
|
|
269
|
+
not on a native `<input type="time">` - that one renders its own system dropdown, which
|
|
268
270
|
cannot be styled and looks alien among the library's controls. The value is the same:
|
|
269
271
|
`HH:mm` or an empty string.
|
|
270
272
|
|
|
@@ -272,12 +274,12 @@ cannot be styled and looks alien among the library's controls. The value is the
|
|
|
272
274
|
are not statically typed. Anyone who needs types supplies their own `kptMapCreateForm`.
|
|
273
275
|
|
|
274
276
|
The "do not scare people with red on a fresh form" gate lives in the presentation (`touched() &&
|
|
275
|
-
invalid()`), not in the validator
|
|
277
|
+
invalid()`), not in the validator - per this repo's Signal Forms contract.
|
|
276
278
|
|
|
277
279
|
## Address suggestions (reverse geocoding)
|
|
278
280
|
|
|
279
281
|
The fields of the "add location" form can fill themselves in with the clicked point's address. Two conditions:
|
|
280
|
-
the field has an `autofill` pointing at a part of the address, and the map has a port
|
|
282
|
+
the field has an `autofill` pointing at a part of the address, and the map has a port - from DI (`KPT_MAP_GEOCODER`)
|
|
281
283
|
or from the `[geocoder]` input, which wins.
|
|
282
284
|
|
|
283
285
|
{ key: 'city', type: 'text', label: 'City', autofill: 'city' },
|
|
@@ -285,9 +287,9 @@ or from the `[geocoder]` input, which wins.
|
|
|
285
287
|
|
|
286
288
|
The address parts (`KptMapAddressPart`): `street`, `houseNumber`, `address` (street with number),
|
|
287
289
|
`city`, `postcode`, `state`, `county`, `country`, `countryCode`, `label` (the full address as one
|
|
288
|
-
string). It works only for `text` and `textarea` fields
|
|
290
|
+
string). It works only for `text` and `textarea` fields - a date or a number will not take a fragment of an address.
|
|
289
291
|
|
|
290
|
-
**A suggestion never overwrites what the user typed**
|
|
292
|
+
**A suggestion never overwrites what the user typed** - only fields that are
|
|
291
293
|
empty at the moment of the response are filled in. A missing port or a failed request does not block the form: the fields
|
|
292
294
|
stay empty, and a note appears under the coordinates.
|
|
293
295
|
|
|
@@ -311,14 +313,14 @@ Only `reverse()` is mandatory. Without `search()` the map shows no search field;
|
|
|
311
313
|
`resolve()` is described below, with suggestions that carry no coordinates.
|
|
312
314
|
|
|
313
315
|
**The interval between requests (`minIntervalMs`).** The one-second gap is not a property of Nominatim, it is a
|
|
314
|
-
requirement of the **public OSM instance's** terms
|
|
316
|
+
requirement of the **public OSM instance's** terms - which is why the default depends on `baseUrl`:
|
|
315
317
|
|
|
316
318
|
provideKptNominatimGeocoder() // 1000 ms
|
|
317
319
|
provideKptNominatimGeocoder({ baseUrl: 'https://geo.local' }) // 0 ms
|
|
318
|
-
provideKptNominatimGeocoder({ baseUrl: '
|
|
320
|
+
provideKptNominatimGeocoder({ baseUrl: '...', minIntervalMs: 200 })
|
|
319
321
|
|
|
320
322
|
On your own server there is nothing to respect, and for as-you-type suggestions a one-second
|
|
321
|
-
delay is the difference between "it works" and "it stutters". `0` also removes the queuing
|
|
323
|
+
delay is the difference between "it works" and "it stutters". `0` also removes the queuing - the requests
|
|
322
324
|
go out in parallel. When pointing at **someone else's shared** instance, set the value explicitly.
|
|
323
325
|
|
|
324
326
|
Tests and Storybook: `provideKptMapGeocoderStub({ city: 'Warszawa', address: 'Marszałkowska 100' })`.
|
|
@@ -326,7 +328,7 @@ Tests and Storybook: `provideKptMapGeocoderStub({ city: 'Warszawa', address: 'Ma
|
|
|
326
328
|
## Address search (forward geocoding)
|
|
327
329
|
|
|
328
330
|
`[search]` puts a field with suggestions in the map's top right corner. Typing a phrase queries
|
|
329
|
-
the geocoder port
|
|
331
|
+
the geocoder port - the **same** one as the address suggestions in the create form, just
|
|
330
332
|
in the other direction; from DI (`KPT_MAP_GEOCODER`) or from the `[geocoder]` input, which wins.
|
|
331
333
|
The `search()` method is **optional** in the port: ports written before it existed still
|
|
332
334
|
compile, and a map without it simply does not render the field.
|
|
@@ -334,7 +336,7 @@ compile, and a map without it simply does not render the field.
|
|
|
334
336
|
<kpt-map [locations]="places()" [categories]="categories" search
|
|
335
337
|
(searchSelect)="onFound($event)" />
|
|
336
338
|
|
|
337
|
-
// main.ts
|
|
339
|
+
// main.ts - without this there will be no field
|
|
338
340
|
providers: [provideKptLeafletMap(), provideKptNominatimGeocoder({ language: 'pl' })]
|
|
339
341
|
|
|
340
342
|
Two types, deliberately kept apart:
|
|
@@ -342,13 +344,13 @@ Two types, deliberately kept apart:
|
|
|
342
344
|
KptMapSuggestion = { id, label, at?, bounds?, address? } // an entry in the list
|
|
343
345
|
KptMapSearchResult = KptMapSuggestion & { at: KptLatLng } // what comes out of the event
|
|
344
346
|
|
|
345
|
-
`address` is the same `KptMapAddress` as in reverse geocoding
|
|
347
|
+
`address` is the same `KptMapAddress` as in reverse geocoding - there is no second address model.
|
|
346
348
|
|
|
347
349
|
### Suggestions with no coordinates (`resolve()`)
|
|
348
350
|
|
|
349
351
|
Most geocoders queried forward (Nominatim, Photon, the Google Geocoding API) give `lat`/`lng`
|
|
350
352
|
right in the list. **Google Places Autocomplete does not**: it returns a `placeId` and text,
|
|
351
|
-
and the coordinates come from a separate Place Details call. This is not one provider's quirk
|
|
353
|
+
and the coordinates come from a separate Place Details call. This is not one provider's quirk - it is what
|
|
352
354
|
its session-based billing rests on, where a whole run of suggestions plus the final Place Details counts
|
|
353
355
|
as one event.
|
|
354
356
|
|
|
@@ -358,15 +360,15 @@ That is why `search()` returns a `KptMapSuggestion` (with `at` **optional**), an
|
|
|
358
360
|
: Observable<KptMapSearchResult | null>;
|
|
359
361
|
|
|
360
362
|
The rule fits in one sentence: **if your `search()` does not return `at`, you must implement
|
|
361
|
-
`resolve()`.** Anyone returning coordinates right away does not need the method
|
|
363
|
+
`resolve()`.** Anyone returning coordinates right away does not need the method - the field will not even call it.
|
|
362
364
|
|
|
363
365
|
The handling lives in `kpt-map-search`, not in `kpt-map`, so the guarantee holds just the same for a field
|
|
364
366
|
standing on its own:
|
|
365
367
|
|
|
366
|
-
- a suggestion with `at`
|
|
367
|
-
- a suggestion without `at`
|
|
368
|
-
the panel stays open with a "Searching
|
|
369
|
-
- `null` or an error
|
|
368
|
+
- a suggestion with `at` -> `selected` fires **immediately**, with no extra request;
|
|
369
|
+
- a suggestion without `at` -> `resolve()` once, **after the entry is picked**, never while typing;
|
|
370
|
+
the panel stays open with a "Searching..." note, and `aria-busy` on the field carries that to a screen reader;
|
|
371
|
+
- `null` or an error -> the label stays in the field, the list comes back (another entry can be picked),
|
|
370
372
|
and `aria-live` says "no matching places";
|
|
371
373
|
- another pick or clearing the field aborts an in-flight request.
|
|
372
374
|
|
|
@@ -375,41 +377,41 @@ standing on its own:
|
|
|
375
377
|
When a port **has no** `resolve()`, suggestions without `at` never reach the list at all: an entry whose
|
|
376
378
|
click would have nowhere to fly is worse than no entry.
|
|
377
379
|
|
|
378
|
-
The stub can pretend to be such a provider
|
|
380
|
+
The stub can pretend to be such a provider - without it there is no way to demo the path without an API key:
|
|
379
381
|
|
|
380
382
|
provideKptMapGeocoderStub(address, results, { deferCoordinates: true })
|
|
381
383
|
|
|
382
384
|
**After a suggestion is picked the map moves the view itself.** A result with `bounds` (a city, a region,
|
|
383
|
-
a province) gets `fitBounds`, and a result without them
|
|
385
|
+
a province) gets `fitBounds`, and a result without them - `setView` at `[searchZoom]`. The
|
|
384
386
|
`searchSelect` event fires after the movement and is there for the application's own purposes (moving
|
|
385
387
|
`[distanceFrom]`, querying for nearby points), not for navigation.
|
|
386
388
|
|
|
387
389
|
The Nominatim adapter **deliberately rejects an overly tight box** and returns the point alone in that case.
|
|
388
390
|
A single address has a bounding box on the order of 0.0001° there, so `fitBounds` would jump to
|
|
389
391
|
the top zoom limit on it and every address would land at a different zoom, depending on how
|
|
390
|
-
the provider traced the building
|
|
392
|
+
the provider traced the building - with the threshold, addresses land at a repeatable `[searchZoom]`,
|
|
391
393
|
while cities still fit into the frame whole.
|
|
392
394
|
|
|
393
395
|
The rule is held by `isFittableBounds(bounds, minSpan?)` from the core (`KPT_MIN_FIT_SPAN` = 0.001°,
|
|
394
|
-
that is ~100 m)
|
|
396
|
+
that is ~100 m) - it is in the public API, it has tests and it applies to every adapter, not just Nominatim.
|
|
395
397
|
The threshold only has to be exceeded on **one** axis: a long, narrow street has one microscopic dimension
|
|
396
398
|
and still deserves `fitBounds`.
|
|
397
399
|
|
|
398
400
|
**Geographic narrowing.** The query gets a `viewbox` from `[bounds]`, or from the `[country]`
|
|
399
|
-
preset without them
|
|
401
|
+
preset without them - that is bias only, it reorders the results and cuts nothing off. A hard
|
|
400
402
|
`countrycodes` is only added with `restrictToCountry` (the map will not let the view move
|
|
401
403
|
outside the country anyway, so a foreign address would be impossible to show) or explicitly
|
|
402
404
|
through `searchOptions.countryCodes`.
|
|
403
405
|
|
|
404
406
|
**The temporary pin** (`[searchMarker]`, on by default) travels the same path as the other
|
|
405
|
-
markers
|
|
407
|
+
markers - through `engine.setMarkers()` - so it moves with the map frame by frame.
|
|
406
408
|
It does not belong to `entries()`, so clicking it opens nothing. It disappears once the field
|
|
407
|
-
is cleared with the
|
|
409
|
+
is cleared with the x and after a click on the map.
|
|
408
410
|
|
|
409
411
|
The Nominatim policy is **stricter here than for `reverse()`**, because as-you-type suggestions
|
|
410
412
|
generate series of requests by their nature. The adapter defends itself two ways: the field waits
|
|
411
413
|
a `debounce` (300 ms) after the last character and does not query below `minLength` (3 characters), while the
|
|
412
|
-
adapter itself keeps **one queue shared with `reverse()`**
|
|
414
|
+
adapter itself keeps **one queue shared with `reverse()`** - one request per second for the whole
|
|
413
415
|
client, not per method. An abandoned request (another character, the field closing) is aborted with
|
|
414
416
|
an `AbortController`. For production, put your own instance or a commercial provider behind it anyway.
|
|
415
417
|
|
|
@@ -420,17 +422,17 @@ no longer costs a second up front.
|
|
|
420
422
|
|
|
421
423
|
### KptMapSearch (kpt-map-search)
|
|
422
424
|
|
|
423
|
-
The field itself is a separate component
|
|
425
|
+
The field itself is a separate component - like the legend, so that it can stand outside the map
|
|
424
426
|
(an application toolbar, a side panel):
|
|
425
427
|
|
|
426
428
|
<kpt-map-search [viewbox]="bounds" (selected)="goTo($event)" (cleared)="clearPin()" />
|
|
427
429
|
|
|
428
430
|
Inputs: `placeholder`, `minLength` (3), `debounce` (300), `limit` (5), `countryCodes`,
|
|
429
|
-
`viewbox`, `disabled`, `geocoder` (this field's port; it wins over DI
|
|
431
|
+
`viewbox`, `disabled`, `geocoder` (this field's port; it wins over DI - that is how
|
|
430
432
|
`kpt-map` passes it in). Outputs: `selected: KptMapSearchResult`, `cleared: void`.
|
|
431
433
|
Without a port that has `search()` the field renders **disabled**, rather than pretending it will find anything.
|
|
432
434
|
|
|
433
|
-
**Why not `kpt-autocomplete`**
|
|
435
|
+
**Why not `kpt-autocomplete`** - the question keeps coming back, so in writing: that one filters options
|
|
434
436
|
client-side (`includes(q)`), so a geocoder result that tolerates typos or is phrased differently
|
|
435
437
|
would drop off the list; its value is a plain `string`, so there is nothing to carry
|
|
436
438
|
coordinates in; and it stands on CDK Overlay, which would add `@angular/cdk/overlay-prebuilt.css`
|
|
@@ -442,15 +444,15 @@ ports use `Observable`/`of` exclusively, and rxjs is not declared as the library
|
|
|
442
444
|
`peerDependency` (it arrives transitively through `@angular/core`).
|
|
443
445
|
|
|
444
446
|
The typed text and the phrase to query are **two separate signals**. Picking a suggestion writes its
|
|
445
|
-
label into the field but does not touch the phrase
|
|
447
|
+
label into the field but does not touch the phrase - otherwise a pick would immediately fire another query
|
|
446
448
|
for what we just found.
|
|
447
449
|
|
|
448
450
|
## Legend
|
|
449
451
|
|
|
450
|
-
`kpt-map-legend`
|
|
452
|
+
`kpt-map-legend` - a separate component, so that it can be placed outside the map. The entries are
|
|
451
453
|
buttons with `aria-pressed`; a click hides the category (it also disappears from the clusters, and the counters drop).
|
|
452
454
|
|
|
453
|
-
<kpt-map [legend]="false" [(hiddenCategories)]="hidden"
|
|
455
|
+
<kpt-map [legend]="false" [(hiddenCategories)]="hidden" ... />
|
|
454
456
|
<kpt-map-legend [categories]="categories" [(hidden)]="hidden" orientation="vertical" />
|
|
455
457
|
|
|
456
458
|
Inputs: `categories` (required), `hidden` (a model), `counts`, `orientation`, `interactive`.
|
|
@@ -460,11 +462,11 @@ Inputs: `categories` (required), `hidden` (a model), `counts`, `orientation`, `i
|
|
|
460
462
|
`[showUserLocation]` enables the marker for the user's own position (the `user` icon) with an accuracy circle
|
|
461
463
|
and a "center on me" control. The position comes through a DI port:
|
|
462
464
|
|
|
463
|
-
KPT_MAP_GEOLOCATION
|
|
465
|
+
KPT_MAP_GEOLOCATION -> KptBrowserGeolocation (by default)
|
|
464
466
|
provideKptMapGeolocationStub({ lat: 52.23, lng: 21.01 }) // Storybook, tests
|
|
465
467
|
|
|
466
468
|
The Geolocation API works **only in a secure context** (HTTPS or `localhost`).
|
|
467
|
-
On `http://` with an IP address the browser refuses
|
|
469
|
+
On `http://` with an IP address the browser refuses - that is not a bug in the component. A denied permission
|
|
468
470
|
disables the control and emits `userLocationError`; the component shows no alert of its own, leaving
|
|
469
471
|
the decision about a message to the application. Under SSR the port returns `null`.
|
|
470
472
|
|
|
@@ -473,12 +475,12 @@ the decision about a message to the application. Under SSR the port returns `nul
|
|
|
473
475
|
The engine is supplied by a factory under the `KPT_MAP_ENGINE` token, and the component talks to it through
|
|
474
476
|
the `KptMapEngine` interface (zero Leaflet types in the signatures). The split of rendering:
|
|
475
477
|
|
|
476
|
-
- tiles, panning, zoom, **markers and clusters**
|
|
477
|
-
- **the popup, the controls, the menu, the legend, the dialog**
|
|
478
|
+
- tiles, panning, zoom, **markers and clusters** -> the engine (`L.divIcon` with HTML from the core),
|
|
479
|
+
- **the popup, the controls, the menu, the legend, the dialog** -> an Angular layer over the map container.
|
|
478
480
|
|
|
479
481
|
Markers go through the engine because they have to move with the map frame by frame (Leaflet does that
|
|
480
482
|
with a single `transform` on the pane). There is one popup at a time, so recomputing its position
|
|
481
|
-
with `engine.project()` on every movement is cheap
|
|
483
|
+
with `engine.project()` on every movement is cheap - and it buys full Angular in the content
|
|
482
484
|
and one implementation for both engines.
|
|
483
485
|
|
|
484
486
|
### Two engines
|
|
@@ -487,13 +489,13 @@ and one implementation for both engines.
|
|
|
487
489
|
provideKptGoogleMap({ apiKey, mapId }) // the Google Maps JavaScript API
|
|
488
490
|
|
|
489
491
|
Leaflet needs the (optional) `leaflet` package and `leaflet/dist/leaflet.css`. Google needs
|
|
490
|
-
**no npm package at all**
|
|
491
|
-
a billing account with a card and a `mapId` from the console (*Map management
|
|
492
|
+
**no npm package at all** - the API is pulled in by a script with the first map - but it does need a key,
|
|
493
|
+
a billing account with a card and a `mapId` from the console (*Map management -> Create Map ID*).
|
|
492
494
|
Without `mapId` `AdvancedMarkerElement` does not work, which means there will be no markers.
|
|
493
495
|
|
|
494
496
|
| | `leaflet` | `google` |
|
|
495
497
|
| ---------------------- | ----------------------------- | ----------------------------------------- |
|
|
496
|
-
| `[tileUrl]`/`[attribution]` | work, swappable on the fly | **ignored**
|
|
498
|
+
| `[tileUrl]`/`[attribution]` | work, swappable on the fly | **ignored** - Google supplies the tiles |
|
|
497
499
|
| attribution | Leaflet's control (ODbL) | the logo and ToS links are built in, **do not cover them** |
|
|
498
500
|
| key / account | not needed | an API key + billing with a card |
|
|
499
501
|
| cost | OSM tiles (no SLA) | the Dynamic Maps SKU: 10k loads/month free |
|
|
@@ -503,15 +505,15 @@ Without `mapId` `AdvancedMarkerElement` does not work, which means there will be
|
|
|
503
505
|
**The last row is the reason this engine exists.** The Google Maps Platform Service
|
|
504
506
|
Specific Terms §6.2 (Geocoding API) and §14.2 (Places API) forbid using their results
|
|
505
507
|
"in conjunction with a non-Google map". A Google adapter under `KPT_MAP_GEOCODER` is therefore compliant
|
|
506
|
-
**only** with the `google` engine
|
|
508
|
+
**only** with the `google` engine - not with the default Leaflet. The library itself
|
|
507
509
|
ships no such adapter; that is the application's decision and code.
|
|
508
510
|
|
|
509
511
|
That is why the geocoder is per map rather than per application: the `[geocoder]` input (below) lets you
|
|
510
512
|
put a Leaflet map with an OSM geocoder next to a Google map with a Google geocoder.
|
|
511
|
-
A global provider could not settle that
|
|
513
|
+
A global provider could not settle that - it would have to break the rule on one
|
|
512
514
|
of the two sides.
|
|
513
515
|
|
|
514
|
-
### `[engine]`
|
|
516
|
+
### `[engine]` - two maps, two engines, one page
|
|
515
517
|
|
|
516
518
|
The input takes a factory and wins over `KPT_MAP_ENGINE` from DI. Without it nothing changes.
|
|
517
519
|
|
|
@@ -519,17 +521,17 @@ The input takes a factory and wins over `KPT_MAP_ENGINE` from DI. Without it not
|
|
|
519
521
|
|
|
520
522
|
<kpt-map [engine]="google" [locations]="places()" [categories]="cats" />
|
|
521
523
|
|
|
522
|
-
It is read once, at initialization
|
|
524
|
+
It is read once, at initialization - swapping it after startup does not reload the map. No engine
|
|
523
525
|
in either source produces a readable error with instructions, not a `NullInjectorError`.
|
|
524
526
|
|
|
525
|
-
### `[geocoder]`
|
|
527
|
+
### `[geocoder]` - the port follows the engine
|
|
526
528
|
|
|
527
529
|
Symmetrical to `[engine]` and for the same reason: a Google geocoder may only be shown
|
|
528
530
|
with a Google map, and that is a property of the **map**, not of the application. The input wins over
|
|
529
531
|
`KPT_MAP_GEOCODER` from DI and reaches both the search and the create form.
|
|
530
532
|
|
|
531
|
-
<kpt-map [engine]="leaflet" search
|
|
532
|
-
<kpt-map [engine]="google" [geocoder]="googleGeocoder" search
|
|
533
|
+
<kpt-map [engine]="leaflet" search ... /> <!-- the port from DI (Nominatim, say) -->
|
|
534
|
+
<kpt-map [engine]="google" [geocoder]="googleGeocoder" search ... />
|
|
533
535
|
|
|
534
536
|
Unlike `[engine]` it is read **reactively**: swapping the port clears the suggestion list
|
|
535
537
|
and queries the new provider from the next phrase on. `null` in both sources means what
|
|
@@ -544,9 +546,9 @@ having no port means today: the search field does not render, and the form sugge
|
|
|
544
546
|
"error_message": "API keys with referer restrictions cannot be used with this API." }
|
|
545
547
|
|
|
546
548
|
and that is the only restriction that makes sense for a key sitting in plain sight in a browser bundle. CORS on
|
|
547
|
-
that endpoint works, so there is not even a network error
|
|
549
|
+
that endpoint works, so there is not even a network error - a `200` arrives with `REQUEST_DENIED`
|
|
548
550
|
in the body, easy to miss. `google.maps.Geocoder` from the loaded SDK authorizes the same way the map itself
|
|
549
|
-
does, so it works with the same key
|
|
551
|
+
does, so it works with the same key - the same SKU, just a different route. Access to the API
|
|
550
552
|
comes from the exported loader (the same one the engine uses):
|
|
551
553
|
|
|
552
554
|
const maps = await loadGoogleMapsApi({ apiKey, language: 'pl' });
|
|
@@ -555,10 +557,10 @@ comes from the exported loader (the same one the engine uses):
|
|
|
555
557
|
|
|
556
558
|
Mind the shape of the response: the SDK returns `location` and `viewport` as objects with methods
|
|
557
559
|
(`lat()`, `getNorthEast()`), not as fields the way REST does. An SDK request **cannot be aborted**,
|
|
558
|
-
so the `signal` from the port's options has nothing behind it
|
|
560
|
+
so the `signal` from the port's options has nothing behind it - unsubscribing merely stops listening.
|
|
559
561
|
An adapter from start to finish: `apps/playground/src/pg-map.google-geocoder.ts`.
|
|
560
562
|
|
|
561
|
-
The engine lands on the host as `[data-engine]` (`leaflet` | `google`)
|
|
563
|
+
The engine lands on the host as `[data-engine]` (`leaflet` | `google`) - that attribute is what the few
|
|
562
564
|
differences are styled by, such as the accuracy circle (an SVG circle in Leaflet, an element with a background in
|
|
563
565
|
Google, because `google.maps.Circle` takes colors in its options while tokens are the rule here).
|
|
564
566
|
|
|
@@ -569,7 +571,7 @@ agrees with the clustering and copes with fractional zoom.
|
|
|
569
571
|
|
|
570
572
|
## Core (pure TS)
|
|
571
573
|
|
|
572
|
-
`@konce-pt/angular/map` exports the computation core
|
|
574
|
+
`@konce-pt/angular/map` exports the computation core - with no Angular and no engine, portable
|
|
573
575
|
to the React port: `clusterLocations`, `dominantCategory`, `countByCategory`, `isSplittable`,
|
|
574
576
|
`project`/`unproject`/`boundsOf`/`haversine`/`metersPerPixel`/`zoomForBounds`/`isFittableBounds`,
|
|
575
577
|
`KPT_MAP_COUNTRIES`/`countryPreset`/`resolveCountryView`,
|
|
@@ -577,43 +579,43 @@ to the React port: `clusterLocations`, `dominantCategory`, `countByCategory`, `i
|
|
|
577
579
|
`formatDistance`/`formatLatLng` and the opening hours: `parseTime`, `formatTime`, `isoWeekday`,
|
|
578
580
|
`isOpenAt`, `isAlwaysOpen`, `nextChange`, `weekdayName`, `groupWeek`, `emptyWeek`.
|
|
579
581
|
|
|
580
|
-
The hours model: `KptMapOpeningHours` = an array of `{ day: 1
|
|
582
|
+
The hours model: `KptMapOpeningHours` = an array of `{ day: 1-7 (ISO), closed?, ranges: [{ from, to }] }`
|
|
581
583
|
in `HH:MM` of the place's local time. A `to` lower than or equal to `from` means "past midnight";
|
|
582
584
|
`24:00` is a valid end of day and does **not** cross midnight. A missing day = closed.
|
|
583
|
-
`isOpenAt()` checks two days
|
|
585
|
+
`isOpenAt()` checks two days - the current one and the previous one - because a `22:00-01:00` range covers
|
|
584
586
|
the early hours of the next day. `groupWeek()` joins adjacent days with an identical schedule
|
|
585
|
-
(`Mon
|
|
587
|
+
(`Mon-Fri`), but it does **not** wrap the week across the Sunday-Monday boundary: a week reads
|
|
586
588
|
linearly and wrapping would be confusing.
|
|
587
589
|
|
|
588
|
-
The core and both engine adapters live in `@konce-pt/map`
|
|
590
|
+
The core and both engine adapters live in `@konce-pt/map` - plain TypeScript, tested
|
|
589
591
|
(`node --test`), shared with the React port.
|
|
590
592
|
|
|
591
|
-
## Clustering
|
|
593
|
+
## Clustering - how it works and what it does not do
|
|
592
594
|
|
|
593
595
|
A grid in pixel space: points are projected onto world pixels for the current zoom
|
|
594
|
-
and assigned to `gridSize` px cells. The algorithm is O(n) and deterministic
|
|
596
|
+
and assigned to `gridSize` px cells. The algorithm is O(n) and deterministic - the same
|
|
595
597
|
data set always yields the same clusters with the same ids.
|
|
596
598
|
|
|
597
599
|
The cluster center is averaged **in pixels, not in degrees**: Mercator stretches degrees toward the
|
|
598
600
|
poles, so an average in degrees lands beside the visual center of the dots on screen.
|
|
599
601
|
|
|
600
602
|
The limitations (deliberate):
|
|
601
|
-
- a cluster can "jump" when a cell boundary is crossed while zooming
|
|
603
|
+
- a cluster can "jump" when a cell boundary is crossed while zooming - that is the price
|
|
602
604
|
for skipping the preprocessing hierarchical clustering requires;
|
|
603
605
|
- **there is no spiderfy.** Points with identical coordinates stay together at every zoom,
|
|
604
606
|
so clicking such a cluster opens a popup listing the entries instead of zooming forever
|
|
605
607
|
(`isSplittable()` recognizes that case);
|
|
606
608
|
- above `clusterMaxZoom` (16 by default) clustering is switched off.
|
|
607
609
|
|
|
608
|
-
## Tiles
|
|
610
|
+
## Tiles - the OSM policy
|
|
609
611
|
|
|
610
612
|
The default `https://tile.openstreetmap.org/{z}/{x}/{y}.png` is a **best-effort service with no SLA**.
|
|
611
613
|
The OSM Foundation requires visible attribution and a sensible `User-Agent`/`Referer`, forbids
|
|
612
|
-
pre-fetching and reserves the right to block traffic without notice
|
|
614
|
+
pre-fetching and reserves the right to block traffic without notice - commercial traffic
|
|
613
615
|
in particular. The default source is there so that the demo works right away.
|
|
614
616
|
|
|
615
617
|
**For production, put your own or a commercial tile server behind it** through `[tileUrl]` + `[attribution]`.
|
|
616
|
-
Do not remove the attribution
|
|
618
|
+
Do not remove the attribution - it is a license requirement, not decoration.
|
|
617
619
|
|
|
618
620
|
## Tokens
|
|
619
621
|
|
|
@@ -627,11 +629,11 @@ Do not remove the attribution — it is a license requirement, not decoration.
|
|
|
627
629
|
Marker and cluster colors come from the category roles: `--kpt-color-{success,warning,danger,
|
|
628
630
|
info,primary,muted}` and their `-contrast` variants.
|
|
629
631
|
|
|
630
|
-
## Leaflet's stacking context
|
|
632
|
+
## Leaflet's stacking context - do not touch
|
|
631
633
|
|
|
632
634
|
`.kpt-map .leaflet-container` gets `z-index: 0`, to close Leaflet's z-index scale
|
|
633
|
-
(panes 200
|
|
634
|
-
directly with the Angular layer stretched over the map
|
|
635
|
+
(panes 200-700, controls 800) inside its own stacking context. Without that the panes compete
|
|
636
|
+
directly with the Angular layer stretched over the map - and the popup (`z-index: 3`), the zoom controls
|
|
635
637
|
(2) and the right-click menu (4) lose and are **painted under the tiles**.
|
|
636
638
|
|
|
637
639
|
The bug is insidious, because a hit test does not show it: the panes and tiles have `pointer-events: none`,
|
|
@@ -641,7 +643,7 @@ cannot see it. The only reliable test is a screenshot.
|
|
|
641
643
|
The scale of the Angular layer over the map: zoom controls `2`, the popup `3`, the right-click menu `4`,
|
|
642
644
|
the search `5` (an expanded suggestion panel has to cover everything above).
|
|
643
645
|
|
|
644
|
-
## The map does not style child components' hosts
|
|
646
|
+
## The map does not style child components' hosts - do not "simplify"
|
|
645
647
|
|
|
646
648
|
The search is positioned by a **wrapper**, `<div class="kpt-map__search">`, and not by a class
|
|
647
649
|
placed directly on `<kpt-map-search>`. Shortening that to a single element looks
|
|
@@ -650,7 +652,7 @@ innocent and **hides the field completely**.
|
|
|
650
652
|
The reason: the search host has its own `.kpt-map-search { position: relative }` rule (the containing
|
|
651
653
|
block for the suggestion panel, needed outside the map too). Both rules would then land on the
|
|
652
654
|
same element with identical specificity (0,1,0) and in the same `kpt.components` layer, so
|
|
653
|
-
injection order decides
|
|
655
|
+
injection order decides - and Angular injects a child's styles **after** the parent's.
|
|
654
656
|
`position: relative` beats `absolute`, the field drops into normal flow behind
|
|
655
657
|
`.kpt-map__canvas` (`height: 100%`) and is clipped by the view's `overflow: hidden`.
|
|
656
658
|
|
|
@@ -658,10 +660,10 @@ The bug is insidious for the same reason as the z-index one: the element is in t
|
|
|
658
660
|
attributes and passes every "did it render" check. It only shows up in a screenshot.
|
|
659
661
|
|
|
660
662
|
`class="kpt-map__legend"` on `<kpt-map-legend>` is safe, because `map.component.scss`
|
|
661
|
-
**has no rule for that class**
|
|
663
|
+
**has no rule for that class** - it is a pure hook for attaching things from outside. A rule
|
|
662
664
|
added there at any point in the future would fall into the same trap.
|
|
663
665
|
|
|
664
|
-
## A deviation from `@layer`
|
|
666
|
+
## A deviation from `@layer` - do not "fix" this
|
|
665
667
|
|
|
666
668
|
`map.component.scss` has two parts: its own styles in `@layer kpt.components` and a section
|
|
667
669
|
of `.leaflet-*` overrides **outside the layer**. It is the only such place in the library and it is deliberate:
|
|
@@ -674,7 +676,7 @@ into the layer "for tidiness" will stop them from working.
|
|
|
674
676
|
- a marker: `role="img"` + `aria-label` = the location's `title`,
|
|
675
677
|
- a cluster: `aria-label` = `map.cluster` with the count,
|
|
676
678
|
- the legend: `role="group"`, entries as `<button aria-pressed>`,
|
|
677
|
-
- the popup: `role="dialog"` with `aria-label` = the title; closed by `Esc`, a click on the map and the
|
|
679
|
+
- the popup: `role="dialog"` with `aria-label` = the title; closed by `Esc`, a click on the map and the x button
|
|
678
680
|
(with `popupLayout="card"` the card supplies the close button, so there are not two),
|
|
679
681
|
- the place card: the title as `role="heading" aria-level="3"`, the contacts as `<ul>`/`<li>`,
|
|
680
682
|
the hours as a disclosure with `aria-expanded` and `aria-controls`, copy confirmation
|
|
@@ -682,7 +684,7 @@ into the layer "for tidiness" will stop them from working.
|
|
|
682
684
|
- the search: `role="combobox"` + `aria-expanded`/`aria-controls`/`aria-autocomplete="list"`,
|
|
683
685
|
the list as `<ul role="listbox">` / `<li role="option">`, the active entry through
|
|
684
686
|
`aria-activedescendant` (the panel sits in the DOM next to the field, so focus stays in the `<input>`),
|
|
685
|
-
the
|
|
687
|
+
the ArrowUp/ArrowDown/Enter keys, the first Esc closes the list, the second clears the field; the result count
|
|
686
688
|
and "no results" go to `aria-live="polite"`,
|
|
687
689
|
- the zoom controls and "center on me": `<button>` with an `aria-label` from the dictionary,
|
|
688
690
|
- the right-click menu: `role="menu"` / `role="menuitem"`.
|
|
@@ -694,18 +696,18 @@ The `map.*` keys in `KptMessages` (EN + PL): `addLocation`, `chooseCategory`, `m
|
|
|
694
696
|
`showCategory`, `hideCategory`, `cluster`, `clusterItems`, `fieldRequired`, `latitude`,
|
|
695
697
|
`longitude`, `empty`, `save`, `cancel`, `lookingUpAddress`, `addressNotFound`.
|
|
696
698
|
|
|
697
|
-
The search: `map.search.*`
|
|
699
|
+
The search: `map.search.*` - `placeholder`, `label`, `results`, `clear`, `noResults`,
|
|
698
700
|
`minLength` ({count}), `searching`, `found` ({count}).
|
|
699
701
|
|
|
700
|
-
The place card: `map.poi.*`
|
|
702
|
+
The place card: `map.poi.*` - `distanceAway`, `openNow`, `closedNow`, `opensAt`, `closesAt`,
|
|
701
703
|
`alwaysOpen`, `openingHours`, `closedDay`, `call`, `sendEmail`, `openWebsite`, `coordinates`,
|
|
702
704
|
`copy`, `copied`, `share`, `addFavourite`, `removeFavourite`, `noPhoto`.
|
|
703
705
|
|
|
704
|
-
The newer form fields: `map.field.*`
|
|
706
|
+
The newer form fields: `map.field.*` - `invalidEmail`, `invalidUrl`, `imageTooLarge`, `pickImage`,
|
|
705
707
|
`orPasteUrl`, `removeImage`, `imagePreview`, `hoursClosed`, `hoursFrom`, `hoursTo`,
|
|
706
708
|
`hoursSameAllWeek`, `hoursAddRange`, `hoursRemoveRange`, `hoursIncomplete`.
|
|
707
709
|
|
|
708
|
-
Weekday names are **not** in the dictionary
|
|
710
|
+
Weekday names are **not** in the dictionary - `Intl.DateTimeFormat` takes them from the locale, so the card
|
|
709
711
|
and the hours editor work for any language without adding translations.
|
|
710
712
|
|
|
711
713
|
## Example
|
|
@@ -718,8 +720,8 @@ and the hours editor work for any language without adding translations.
|
|
|
718
720
|
// the component
|
|
719
721
|
readonly locations = signal<KptMapLocation<Site>[]>(SITES);
|
|
720
722
|
readonly categories: KptMapCategory[] = [
|
|
721
|
-
{ id: 'opening', label: 'Opening', color: 'success', icon: 'building-store', fields: [
|
|
722
|
-
{ id: 'closure', label: 'Closure', color: 'danger', icon: 'lock', fields: [
|
|
723
|
+
{ id: 'opening', label: 'Opening', color: 'success', icon: 'building-store', fields: [ ... ] },
|
|
724
|
+
{ id: 'closure', label: 'Closure', color: 'danger', icon: 'lock', fields: [ ... ] },
|
|
723
725
|
];
|
|
724
726
|
|
|
725
727
|
onCreate(event: KptMapCreateEvent): void {
|