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