@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.
Files changed (116) hide show
  1. package/CHANGELOG.md +792 -333
  2. package/README.md +111 -55
  3. package/charts/src/lib/llms.txt +23 -15
  4. package/chat/src/lib/llms.txt +68 -33
  5. package/fesm2022/konce-pt-angular-charts.mjs +149 -68
  6. package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
  7. package/fesm2022/konce-pt-angular-chat.mjs +296 -135
  8. package/fesm2022/konce-pt-angular-chat.mjs.map +1 -1
  9. package/fesm2022/konce-pt-angular-grid.mjs +16 -16
  10. package/fesm2022/konce-pt-angular-grid.mjs.map +1 -1
  11. package/fesm2022/konce-pt-angular-icons.mjs +5 -5
  12. package/fesm2022/konce-pt-angular-icons.mjs.map +1 -1
  13. package/fesm2022/konce-pt-angular-map.mjs +360 -293
  14. package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
  15. package/fesm2022/konce-pt-angular-roadmap.mjs +120 -34
  16. package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
  17. package/fesm2022/konce-pt-angular.mjs +7117 -3373
  18. package/fesm2022/konce-pt-angular.mjs.map +1 -1
  19. package/grid/src/lib/llms.txt +18 -18
  20. package/map/src/lib/llms.txt +142 -140
  21. package/package.json +14 -12
  22. package/roadmap/src/lib/llms.txt +37 -27
  23. package/src/lib/accordion/llms.txt +18 -6
  24. package/src/lib/alert/llms.txt +5 -4
  25. package/src/lib/app-shell/llms.txt +25 -22
  26. package/src/lib/auth/llms.txt +26 -22
  27. package/src/lib/autocomplete/llms.txt +18 -4
  28. package/src/lib/avatar/llms.txt +3 -3
  29. package/src/lib/avatar-group/llms.txt +5 -5
  30. package/src/lib/backdrop/llms.txt +35 -35
  31. package/src/lib/badge/llms.txt +7 -7
  32. package/src/lib/bottom-sheet/llms.txt +6 -3
  33. package/src/lib/breadcrumb/llms.txt +9 -1
  34. package/src/lib/breakpoint/llms.txt +8 -8
  35. package/src/lib/button/llms.txt +26 -18
  36. package/src/lib/button-group/llms.txt +40 -31
  37. package/src/lib/card/llms.txt +19 -19
  38. package/src/lib/carousel/llms.txt +6 -6
  39. package/src/lib/checkbox/llms.txt +17 -2
  40. package/src/lib/chip/llms.txt +6 -6
  41. package/src/lib/chips-input/llms.txt +14 -4
  42. package/src/lib/color-picker/llms.txt +7 -4
  43. package/src/lib/confirm/llms.txt +9 -3
  44. package/src/lib/context-menu/llms.txt +7 -4
  45. package/src/lib/data-table/llms.txt +280 -227
  46. package/src/lib/data-view/llms.txt +25 -4
  47. package/src/lib/date-range/llms.txt +37 -18
  48. package/src/lib/datepicker/llms.txt +46 -29
  49. package/src/lib/dialog/llms.txt +29 -26
  50. package/src/lib/divider/llms.txt +2 -1
  51. package/src/lib/drawer/llms.txt +9 -6
  52. package/src/lib/empty/llms.txt +4 -4
  53. package/src/lib/fab/llms.txt +6 -2
  54. package/src/lib/fieldset/llms.txt +22 -4
  55. package/src/lib/file-upload/llms.txt +3 -0
  56. package/src/lib/form-field/llms.txt +33 -19
  57. package/src/lib/galleria/llms.txt +3 -3
  58. package/src/lib/i18n/llms.txt +15 -8
  59. package/src/lib/icon/llms.txt +9 -9
  60. package/src/lib/icon-button/llms.txt +8 -3
  61. package/src/lib/image/llms.txt +4 -4
  62. package/src/lib/input/llms.txt +21 -7
  63. package/src/lib/input-mask/llms.txt +5 -2
  64. package/src/lib/input-number/llms.txt +18 -15
  65. package/src/lib/input-otp/llms.txt +15 -4
  66. package/src/lib/knob/llms.txt +14 -7
  67. package/src/lib/listbox/llms.txt +8 -5
  68. package/src/lib/loader/llms.txt +72 -0
  69. package/src/lib/megamenu/llms.txt +16 -5
  70. package/src/lib/mention/llms.txt +15 -15
  71. package/src/lib/menu/llms.txt +12 -12
  72. package/src/lib/menubar/llms.txt +16 -5
  73. package/src/lib/meter-group/llms.txt +7 -7
  74. package/src/lib/order-list/llms.txt +20 -5
  75. package/src/lib/paginator/llms.txt +5 -5
  76. package/src/lib/panel/llms.txt +20 -8
  77. package/src/lib/password/llms.txt +17 -5
  78. package/src/lib/peek/llms.txt +11 -11
  79. package/src/lib/pick-list/llms.txt +28 -5
  80. package/src/lib/popover/llms.txt +9 -6
  81. package/src/lib/progress/llms.txt +16 -16
  82. package/src/lib/radio-group/llms.txt +13 -3
  83. package/src/lib/rating/llms.txt +13 -6
  84. package/src/lib/rich-text/llms.txt +42 -24
  85. package/src/lib/scroll-top/llms.txt +3 -3
  86. package/src/lib/select/llms.txt +23 -13
  87. package/src/lib/sidenav/llms.txt +8 -8
  88. package/src/lib/slider/llms.txt +23 -7
  89. package/src/lib/speech/llms.txt +108 -0
  90. package/src/lib/speed-dial/llms.txt +9 -3
  91. package/src/lib/spinner/llms.txt +2 -2
  92. package/src/lib/split-button/llms.txt +14 -8
  93. package/src/lib/splitter/llms.txt +8 -8
  94. package/src/lib/stepper/llms.txt +26 -7
  95. package/src/lib/switch/llms.txt +13 -3
  96. package/src/lib/switch-group/llms.txt +12 -9
  97. package/src/lib/tabs/llms.txt +7 -4
  98. package/src/lib/textarea/llms.txt +16 -5
  99. package/src/lib/timeline/llms.txt +1 -1
  100. package/src/lib/toast/llms.txt +36 -5
  101. package/src/lib/toolbar/llms.txt +3 -3
  102. package/src/lib/tooltip/llms.txt +13 -10
  103. package/src/lib/tree/llms.txt +19 -5
  104. package/src/lib/update/llms.txt +52 -0
  105. package/types/konce-pt-angular-charts.d.ts +11 -0
  106. package/types/konce-pt-angular-charts.d.ts.map +1 -1
  107. package/types/konce-pt-angular-chat.d.ts +98 -40
  108. package/types/konce-pt-angular-chat.d.ts.map +1 -1
  109. package/types/konce-pt-angular-grid.d.ts +14 -14
  110. package/types/konce-pt-angular-icons.d.ts +3 -3
  111. package/types/konce-pt-angular-map.d.ts +147 -119
  112. package/types/konce-pt-angular-map.d.ts.map +1 -1
  113. package/types/konce-pt-angular-roadmap.d.ts +34 -9
  114. package/types/konce-pt-angular-roadmap.d.ts.map +1 -1
  115. package/types/konce-pt-angular.d.ts +1774 -651
  116. package/types/konce-pt-angular.d.ts.map +1 -1
@@ -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 — Google Maps — needs no package
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 — the library does not install it:
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 — like `@angular/cdk/overlay-prebuilt.css`, through `angular.json → styles[]`,
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` — a block element. The height is set by `[height]` (default `480px`).
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>[]` — **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`
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? }` — `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
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` — 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
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` = `''` — 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
- - `geocoder`: `KptMapGeocoderPort | null` = `null` — **this** map's geocoder; it wins over
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'` — `card` hands the popup over to the content entirely:
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` — the reference point for the distance handed
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` — OSM tiles by default (see "Tiles" below); **irrelevant for the Google engine**
70
- - `attribution`: `string | null` — `© OpenStreetMap contributors` by default; likewise
71
- - `engine`: `KptMapEngineFactory | null` — this map's engine; it wins over `KPT_MAP_ENGINE` from DI
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[]>` — the ids of categories hidden in the legend
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 }` — the component appends **nothing** to `locations`;
80
+ - `locationCreate`: `{ at, categoryId, value }` - the component appends **nothing** to `locations`;
80
81
  the application is the source of truth
81
- - `searchSelect`: `KptMapSearchResult` — a suggestion was picked; the map has **already** moved the view itself
82
- - `viewChange`: `{ center, zoom, bounds }` — after the map's movement ends
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 — the rest are saturated and read fine in either function. Hence the third function:
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 · Wrocław', data: { … } }
114
+ title: '2210, Wrocław', data: { ... } }
113
115
 
114
- `title` is required — it goes into the marker's `aria-label`. `data` is arbitrary and is handed
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` — the details popup, chosen by category. A template with no `category` attribute
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 · {{ d.status }}</p>
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 — geolocation is disabled or was refused.
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 — Angular does not carry the generic from `kpt-map` onto a directive
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 — before that we do not know its dimensions).
149
+ after the first render - before that we do not know its dimensions).
148
150
 
149
- `kptMapCreateForm` — your own create form. Its presence disables the form built
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` — **required**
180
- - `distance`: `number | null` = `null` — meters; `null` hides the distance row
181
- - `category`: `KptMapCategory | null` = `null` — the icon, the color and the label of the category row
182
- - `primaryLabel`: `string` = `''` — an empty value hides the primary button
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** — the `location.data → KptMapPoi` mapping is done by
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 — the card does not tell them apart. Without one it draws a placeholder
196
- with an icon instead of collapsing the frame to zero. `facts` are arbitrary "icon · label · value" rows below the contacts.
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 — on touch and from the keyboard
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 — a plain
214
- `<h3>` would catch every `h3 { … }` rule from the page's layout (in the playground that turned the place title
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 — the `kpt-map` popup is already `role="dialog"`.
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 — fixed
222
- .kpt-map-poi__meta distance + address — fixed
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 — to make them scroll with the content,
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` — the `::after` arrow hangs at `top: 100%` and would be
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 → a menu of categories → a `kpt-dialog` with a form. By default the form is built
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 — phone numbers can be odd |
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?://…` pattern |
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** — the library knows
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 — otherwise
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">` — that one renders its own system dropdown, which
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 — per this repo's Signal Forms contract.
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 — from DI (`KPT_MAP_GEOCODER`)
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 — a date or a number will not take a fragment of an address.
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** — only fields that are
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 — which is why the default depends on `baseUrl`:
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: '…', minIntervalMs: 200 })
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 — the requests
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 — the **same** one as the address suggestions in the create form, just
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 — without this there will be no field
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 — there is no second address model.
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 — it is what
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 — the field will not even call it.
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` → `selected` fires **immediately**, with no extra request;
367
- - a suggestion without `at` → `resolve()` once, **after the entry is picked**, never while typing;
368
- the panel stays open with a "Searching…" note, and `aria-busy` on the field carries that to a screen reader;
369
- - `null` or an error → the label stays in the field, the list comes back (another entry can be picked),
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 — without it there is no way to demo the path without an API key:
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 — `setView` at `[searchZoom]`. The
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 — with the threshold, addresses land at a repeatable `[searchZoom]`,
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) — it is in the public API, it has tests and it applies to every adapter, not just Nominatim.
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 — that is bias only, it reorders the results and cuts nothing off. A hard
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 — through `engine.setMarkers()` — so it moves with the map frame by frame.
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 × and after a click on the map.
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()`** — one request per second for the whole
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 — like the legend, so that it can stand outside the map
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 — that is how
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`** — the question keeps coming back, so in writing: that one filters options
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 — otherwise a pick would immediately fire another query
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` — a separate component, so that it can be placed outside the map. The entries are
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 → KptBrowserGeolocation (by default)
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 — that is not a bug in the component. A denied permission
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** → the engine (`L.divIcon` with HTML from the core),
477
- - **the popup, the controls, the menu, the legend, the dialog** → an Angular layer over the map container.
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 — and it buys full Angular in the content
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** — the API is pulled in by a script with the first map — but it does need a key,
491
- a billing account with a card and a `mapId` from the console (*Map management → Create Map ID*).
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** — Google supplies the tiles |
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 — not with the default Leaflet. The library itself
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 — it would have to break the rule on one
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]` — two maps, two engines, one page
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 — swapping it after startup does not reload the map. No engine
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]` — the port follows the engine
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 … /> <!-- the port from DI (Nominatim, say) -->
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 — a `200` arrives with `REQUEST_DENIED`
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 — the same SKU, just a different route. Access to the API
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 — unsubscribing merely stops listening.
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`) — that attribute is what the few
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 — with no Angular and no engine, portable
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–7 (ISO), closed?, ranges: [{ from, to }] }`
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 — the current one and the previous one — because a `22:00–01:00` range covers
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–Fri`), but it does **not** wrap the week across the Sunday–Monday boundary: a week reads
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` — plain TypeScript, tested
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 — how it works and what it does not do
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 — the same
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 — that is the price
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 — the OSM policy
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 — commercial traffic
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 — it is a license requirement, not decoration.
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 — do not touch
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–700, controls 800) inside its own stacking context. Without that the panes compete
634
- directly with the Angular layer stretched over the map — and the popup (`z-index: 3`), the zoom controls
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 — do not "simplify"
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 — and Angular injects a child's styles **after** the parent's.
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** — it is a pure hook for attaching things from outside. A rule
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` — do not "fix" this
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 × button
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 ↑/↓/Enter keys, the first Esc closes the list, the second clears the field; the result count
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.*` — `placeholder`, `label`, `results`, `clear`, `noResults`,
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.*` — `distanceAway`, `openNow`, `closedNow`, `opensAt`, `closesAt`,
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.*` — `invalidEmail`, `invalidUrl`, `imageTooLarge`, `pickImage`,
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 — `Intl.DateTimeFormat` takes them from the locale, so the card
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 {