@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.
Files changed (114) hide show
  1. package/CHANGELOG.md +591 -369
  2. package/README.md +111 -55
  3. package/charts/src/lib/llms.txt +17 -17
  4. package/chat/src/lib/llms.txt +61 -35
  5. package/fesm2022/konce-pt-angular-charts.mjs +11 -11
  6. package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
  7. package/fesm2022/konce-pt-angular-chat.mjs +236 -127
  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 +308 -280
  14. package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
  15. package/fesm2022/konce-pt-angular-roadmap.mjs +23 -23
  16. package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
  17. package/fesm2022/konce-pt-angular.mjs +4410 -2128
  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 -141
  21. package/package.json +14 -12
  22. package/roadmap/src/lib/llms.txt +27 -27
  23. package/src/lib/accordion/llms.txt +18 -6
  24. package/src/lib/alert/llms.txt +5 -5
  25. package/src/lib/app-shell/llms.txt +23 -21
  26. package/src/lib/auth/llms.txt +22 -22
  27. package/src/lib/autocomplete/llms.txt +15 -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 +4 -4
  33. package/src/lib/breadcrumb/llms.txt +2 -2
  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 +37 -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 +15 -3
  40. package/src/lib/chip/llms.txt +6 -6
  41. package/src/lib/chips-input/llms.txt +11 -4
  42. package/src/lib/color-picker/llms.txt +4 -4
  43. package/src/lib/confirm/llms.txt +5 -5
  44. package/src/lib/context-menu/llms.txt +4 -4
  45. package/src/lib/data-table/llms.txt +280 -239
  46. package/src/lib/data-view/llms.txt +25 -4
  47. package/src/lib/date-range/llms.txt +27 -27
  48. package/src/lib/datepicker/llms.txt +34 -34
  49. package/src/lib/dialog/llms.txt +27 -27
  50. package/src/lib/divider/llms.txt +2 -2
  51. package/src/lib/drawer/llms.txt +7 -7
  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 +1 -1
  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 +9 -9
  59. package/src/lib/icon/llms.txt +8 -8
  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 +2 -2
  64. package/src/lib/input-number/llms.txt +14 -14
  65. package/src/lib/input-otp/llms.txt +6 -6
  66. package/src/lib/knob/llms.txt +11 -6
  67. package/src/lib/listbox/llms.txt +6 -6
  68. package/src/lib/loader/llms.txt +72 -0
  69. package/src/lib/megamenu/llms.txt +7 -7
  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 +7 -7
  73. package/src/lib/meter-group/llms.txt +7 -7
  74. package/src/lib/order-list/llms.txt +18 -6
  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 +14 -6
  78. package/src/lib/peek/llms.txt +10 -10
  79. package/src/lib/pick-list/llms.txt +26 -6
  80. package/src/lib/popover/llms.txt +7 -7
  81. package/src/lib/progress/llms.txt +16 -16
  82. package/src/lib/radio-group/llms.txt +10 -3
  83. package/src/lib/rating/llms.txt +13 -6
  84. package/src/lib/rich-text/llms.txt +34 -29
  85. package/src/lib/scroll-top/llms.txt +3 -3
  86. package/src/lib/select/llms.txt +20 -13
  87. package/src/lib/sidenav/llms.txt +8 -8
  88. package/src/lib/slider/llms.txt +21 -8
  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 +24 -8
  95. package/src/lib/switch/llms.txt +10 -3
  96. package/src/lib/switch-group/llms.txt +10 -10
  97. package/src/lib/tabs/llms.txt +5 -5
  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 +33 -5
  101. package/src/lib/toolbar/llms.txt +3 -3
  102. package/src/lib/tooltip/llms.txt +10 -10
  103. package/src/lib/tree/llms.txt +19 -6
  104. package/src/lib/update/llms.txt +52 -0
  105. package/types/konce-pt-angular-charts.d.ts +2 -2
  106. package/types/konce-pt-angular-chat.d.ts +87 -44
  107. package/types/konce-pt-angular-chat.d.ts.map +1 -1
  108. package/types/konce-pt-angular-grid.d.ts +14 -14
  109. package/types/konce-pt-angular-icons.d.ts +3 -3
  110. package/types/konce-pt-angular-map.d.ts +137 -121
  111. package/types/konce-pt-angular-map.d.ts.map +1 -1
  112. package/types/konce-pt-angular-roadmap.d.ts +13 -13
  113. package/types/konce-pt-angular.d.ts +1383 -625
  114. 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,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` — 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`
85
- - `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
+ - `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 — 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:
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 · Wrocław', data: { … } }
114
+ title: '2210, Wrocław', data: { ... } }
114
115
 
115
- `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
116
117
  to the popup template.
117
118
 
118
119
  ## Templates
119
120
 
120
- `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
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 · {{ d.status }}</p>
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 — geolocation is disabled or was refused.
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 — 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
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 — before that we do not know its dimensions).
149
+ after the first render - before that we do not know its dimensions).
149
150
 
150
- `kptMapCreateForm` — your own create form. Its presence disables the form built
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` — **required**
181
- - `distance`: `number | null` = `null` — meters; `null` hides the distance row
182
- - `category`: `KptMapCategory | null` = `null` — the icon, the color and the label of the category row
183
- - `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
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** — the `location.data → KptMapPoi` mapping is done by
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 — the card does not tell them apart. Without one it draws a placeholder
197
- 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.
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 — on touch and from the keyboard
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 — a plain
215
- `<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
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 — 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"`.
218
219
 
219
220
  Anatomy and scrolling:
220
221
 
221
222
  kpt-map-poi-card
222
- .kpt-map-poi__head title + close button — fixed
223
- .kpt-map-poi__meta distance + address — fixed
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 — 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,
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` — 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
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 → 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
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 — phone numbers can be odd |
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?://…` pattern |
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** — the library knows
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 — otherwise
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">` — that one renders its own system dropdown, which
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 — per this repo's Signal Forms contract.
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 — 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`)
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 — 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.
290
291
 
291
- **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
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 — 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`:
316
317
 
317
318
  provideKptNominatimGeocoder() // 1000 ms
318
319
  provideKptNominatimGeocoder({ baseUrl: 'https://geo.local' }) // 0 ms
319
- provideKptNominatimGeocoder({ baseUrl: '…', minIntervalMs: 200 })
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 — the requests
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 — 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
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 — without this there will be no field
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 — there is no second address model.
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 — it is what
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 — 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.
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` → `selected` fires **immediately**, with no extra request;
368
- - a suggestion without `at` → `resolve()` once, **after the entry is picked**, never while typing;
369
- the panel stays open with a "Searching…" note, and `aria-busy` on the field carries that to a screen reader;
370
- - `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),
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 — 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:
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 — `setView` at `[searchZoom]`. The
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 — with the threshold, addresses land at a repeatable `[searchZoom]`,
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) — 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.
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 — 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
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 — 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.
407
408
  It does not belong to `entries()`, so clicking it opens nothing. It disappears once the field
408
- is cleared with the × and after a click on the map.
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()`** — one request per second for the whole
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 — 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
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 — that is how
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`** — 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
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 — 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
447
448
  for what we just found.
448
449
 
449
450
  ## Legend
450
451
 
451
- `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
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 → KptBrowserGeolocation (by default)
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 — 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
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** → the engine (`L.divIcon` with HTML from the core),
478
- - **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.
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 — 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
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** — the API is pulled in by a script with the first map — but it does need a key,
492
- 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*).
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** — Google supplies the tiles |
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 — not with the default Leaflet. The library itself
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 — 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
513
514
  of the two sides.
514
515
 
515
- ### `[engine]` — two maps, two engines, one page
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 — 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
524
525
  in either source produces a readable error with instructions, not a `NullInjectorError`.
525
526
 
526
- ### `[geocoder]` — the port follows the engine
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 … /> <!-- the port from DI (Nominatim, say) -->
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 — a `200` arrives with `REQUEST_DENIED`
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 — 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
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 — unsubscribing merely stops listening.
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`) — that attribute is what the few
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 — with no Angular and no engine, portable
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–7 (ISO), closed?, ranges: [{ from, to }] }`
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 — 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
585
586
  the early hours of the next day. `groupWeek()` joins adjacent days with an identical schedule
586
- (`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
587
588
  linearly and wrapping would be confusing.
588
589
 
589
- 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
590
591
  (`node --test`), shared with the React port.
591
592
 
592
- ## Clustering — how it works and what it does not do
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 — the same
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 — that is the price
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 — the OSM policy
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 — commercial traffic
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 — it is a license requirement, not decoration.
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 — do not touch
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–700, controls 800) inside its own stacking context. Without that the panes compete
635
- 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
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 — do not "simplify"
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 — 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.
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** — 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
663
664
  added there at any point in the future would fall into the same trap.
664
665
 
665
- ## A deviation from `@layer` — do not "fix" this
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 × button
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 ↑/↓/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
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.*` — `placeholder`, `label`, `results`, `clear`, `noResults`,
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.*` — `distanceAway`, `openNow`, `closedNow`, `opensAt`, `closesAt`,
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.*` — `invalidEmail`, `invalidUrl`, `imageTooLarge`, `pickImage`,
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 — `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
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 {