@guildofgleks/ui 21.12.0 → 21.13.0

package/AGENTS.md

@@ -36,7 +36,14 @@ defaults.
 - Theming is 100% CSS custom properties (`--gog-*`) — no Sass config, no JS theme objects, no
   build step to restyle anything.
 - Tree-shakeable: `"sideEffects": false` and every component is a separate standalone import, so
-  importing `ButtonComponent` alone does not pull in the rest of the library.
+  importing `ButtonComponent` alone does not pull in the rest of the library — measured on the real
+  CLI, a button costs about 10 kB gzip over an empty app and all 31 components about 75 kB.
+  **It does not yet code-split**: a component used only behind a lazy route still ships in the
+  initial bundle, because the root is one module. `docs/entry-points.md` in the repository is the
+  plan that fixes it.
+- **Import from `@guildofgleks/ui`.** `@guildofgleks/ui/shared` also resolves — it is the
+  package's internal entry point, which the root and its other entry points share so that
+  `GOG_CONFIG` exists once. It is not an API to build an app on.
 - SSR-safe: anything touching `window`/`document` is guarded with `isPlatformBrowser`/
   `afterNextRender`.
 
@@ -301,7 +308,7 @@ parent's config**, one level deep per key — it does not replace it.
 | Key            | Fields                                                                                | Applies to                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | -------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `control`      | `size`, `errorDisplay`, `clearable`                                                   | `size`: button, `[gogButton]`, button-toggle-group, checkbox, toggle, radio-group, inputfield, textarea, select, multiselect, autocomplete, datepicker. `errorDisplay`: inputfield, textarea, select, multiselect, autocomplete, datepicker, radio-group, slider. `clearable`: inputfield, textarea, select, multiselect, autocomplete, datepicker. Not table/accordion/paginator (density, not form size), not spinner/skeleton/tag/chip. |
-| `dropdown`     | `appendToBody`, `direction`, `filter`, `filterPosition`                               | `gog-select`, `gog-multiselect`. `gog-datepicker`/`gog-autocomplete` honour `appendToBody`/`direction` too (autocomplete has no `filter` box — it filters via the trigger's own text).                                                                                                                                                                                                                                                     |
+| `dropdown`     | `appendToBody`, `direction`, `filter`, `filterPosition`, `virtualize`                 | `gog-select`, `gog-multiselect`. `gog-datepicker`/`gog-autocomplete` honour `appendToBody`/`direction` too (autocomplete has no `filter` box — it filters via the trigger's own text). `virtualize` reaches all three dropdowns; not `gog-table`.                                                                                                                                                                                          |
 | `floatLabel`   | `variant`, `showPlaceholder`                                                          | inputfield, textarea, select, multiselect, autocomplete, datepicker.                                                                                                                                                                                                                                                                                                                                                                       |
 | `datepicker`   | `locale`, `firstDayOfWeek`, `format`                                                  | `gog-datepicker`, `gog-calendar`.                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `autocomplete` | `searchDebounce`, `minLength`, `openOnFocus`                                          | `gog-autocomplete`.                                                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -338,6 +345,7 @@ provideGogConfig({
     hidePassword: 'Passwort verbergen',
     closeDialog: 'Schließen',
     closeToast: 'Schließen',
+    closeAlert: 'Meldung schließen', // gog-alert's dismiss button
     pagination: 'Seitennavigation',
     previousPage: 'Vorherige Seite',
     nextPage: 'Nächste Seite',
@@ -426,6 +434,12 @@ place instead of stacking a duplicate.
 
 ### `DialogService`
 
+**Import from `@guildofgleks/ui/dialog`** — `DialogService`, `DIALOG_DATA`, `DIALOG_REF`, `DialogRef`, `DialogConfig` and the dialog components. The root still exports them in 21.13.0 and
+stops in **21.14.0**, which is when the code moves into that entry point and a lazy route that
+uses them stops carrying them in the initial bundle. **Your editor will not strike the root
+import through**: ng-packagr's bundled types drop the deprecation tags on re-exports, measured. The
+notice is this line, `CHANGELOG.md` and `GOG_DEPRECATIONS`.
+
 Root-provided singleton, imperative dynamic-component dialogs. Requires a `<gog-dialog />`
 placed once in your app (see [gog-dialog](#gog-dialog) below — also **not** automatic).
 
@@ -477,7 +491,7 @@ itself via `DIALOG_REF`:
 
 ```ts
 import { Component, inject } from '@angular/core';
-import { DIALOG_DATA, DIALOG_REF } from '@guildofgleks/ui';
+import { DIALOG_DATA, DIALOG_REF } from '@guildofgleks/ui/dialog';
 
 @Component({ selector: 'app-edit-dialog', template: `…` })
 export class EditDialogComponent {
@@ -494,7 +508,11 @@ export class EditDialogComponent {
 
 ## Component reference
 
-Every component below is exported from `@guildofgleks/ui`'s root — `import { X } from '@guildofgleks/ui'`.
+Every component below is exported from `@guildofgleks/ui`'s root — `import { X } from '@guildofgleks/ui'` —
+**except `gog-table`, `gog-datepicker`/`gog-calendar` and `gog-dialog` with `DialogService`**, which
+have their own entry points: `@guildofgleks/ui/table`, `/datepicker` and `/dialog`. They are the
+three components heavy enough to be worth keeping out of an app's initial bundle, and splitting
+them is how that becomes possible (21.14.0; see each section).
 "CVA" = implements `ControlValueAccessor` (works with `[formControl]`/`formControlName`).
 
 ### Buttons & choices
@@ -741,13 +759,47 @@ and multiselect unless noted otherwise):
 | `inputId` (select/autocomplete only)                   | `string`                                | `''`                                                         |                                                                                     |
 | `ripple`                                               | `boolean \| undefined`                  | `false`                                                      | press ripple; via `GOG_CONFIG.ripple.enabled`                                       |
 
-`gog-select`-specific: `value: model<TValue>(null)`.
+`gog-select`-specific: `value: model<TValue>(null)`, and `virtualize: boolean | undefined` (default `false`, via `GOG_CONFIG.dropdown.virtualize`) — see below.
+`virtualize: boolean | undefined` (default `false`, via `GOG_CONFIG.dropdown.virtualize`) is on
+`gog-select`, `gog-multiselect` and `gog-autocomplete` alike.
+
 `gog-multiselect`-specific additions: `value: model<TValue[]>([])`, `showControls: boolean` (default `false`, a select-all/clear row), `controlsPosition: 'top'|'bottom'` (default `'top'`), and `selectAllLabel`/`clearAllLabel` for that row's two buttons (`'Select all'`/`'Clear'`, also via `GOG_CONFIG.labels`).
 
 CVA: yes, both. Slots (shared): `<ng-template gogDropdownChevron>` (custom chevron markup),
 `<ng-template gogDropdownOption let-opt let-selected="selected" let-label="label">` (custom
 option row). Multiselect adds `<ng-template gogMultiselectClearIcon>`.
 
+**`virtualize` for a list in the thousands, and only when you mean it.** Unwindowed, 10 000
+options build 10 000 DOM rows to show about six: measured in Chrome that is 512ms before the panel
+appears, against 21ms windowed, on the same data. Windowed, the DOM holds roughly twenty rows
+whatever the count is, and the scrollbar is identical because spacers stand in for the rows that
+are not there.
+
+It is **off by default and never switched on at a row-count threshold**, which is the same call
+`GOG_CONFIG.ripple.enabled` makes: a windowed list behaves differently in ways nothing about the
+data predicts, so flipping it when enough rows happen to arrive works in development and surprises
+in production. Set it per field, or app-wide with `GOG_CONFIG.dropdown.virtualize`.
+
+What changes while it is on:
+
+- **`Ctrl+F` finds only the rendered rows**, and CSS targeting `:last-child` matches the last
+  _rendered_ row. Those are the two that catch people out.
+- **The announced count stays honest.** `aria-setsize` and `aria-posinset` carry the real list and
+  the real position, so a screen reader is told "10 000 items", not "20".
+- **Scrolling a keyboard-focused row out of view hands focus back to the trigger**, because the
+  row it was on no longer exists. Escape and ArrowDown both work from there. An unwindowed list
+  never has to do this.
+- Arrow keys move through the whole list rather than the rendered part, so ArrowUp from the
+  trigger still reaches option 10 000.
+
+All three dropdowns take it — `gog-select`, `gog-multiselect` and `gog-autocomplete`. **`gog-table`
+does not**, and `[lazy]` is not a substitute: that keeps the _fetch_ small and still stamps every
+row it is handed. The same distinction applies to `gog-autocomplete`'s `gogLoadMore`, and the two
+compose — pair them on a long list, because neither implies the other.
+
+On `gog-autocomplete` the focus caveat above does not apply: it is a combobox, so focus never
+leaves the text field and the highlight is carried by `aria-activedescendant` either way.
+
 **Turn `filter` on past about seven options — or order them instead.** Choice time grows with the
 log of the count (`T = b · log₂(n + 1)`), so beyond roughly seven a panel stops being scanned and
 starts being read. The escape is not always the filter box: the law governs _unordered_ choices,
@@ -908,6 +960,13 @@ control or cut pointer events over the track, which would take the still-enabled
 
 #### `gog-datepicker` / `gog-calendar`
 
+**Import from `@guildofgleks/ui/datepicker`** — `DatepickerComponent`, `CalendarComponent`, `GogCalendarDay` and `GogDatepickerValue`; the date
+helpers (`formatDate`, `parseDate`, …) and `GogDateRange` stay in the root. The root still exports them in 21.13.0 and
+stops in **21.14.0**, which is when the code moves into that entry point and a lazy route that
+uses them stops carrying them in the initial bundle. **Your editor will not strike the root
+import through**: ng-packagr's bundled types drop the deprecation tags on re-exports, measured. The
+notice is this line, `CHANGELOG.md` and `GOG_DEPRECATIONS`.
+
 `gog-datepicker` is a field + panel; `gog-calendar` is the month grid alone (what `inline` mode
 renders). Native `Date` only — no date library, no adapter.
 
@@ -1143,6 +1202,55 @@ cancel out. A `disabled` chip keeps the ring but drops `aria-pressed`, which nee
 `role="button"` a disabled chip does not carry — "selected, and currently unavailable" is a real
 state and hiding it would leave it announced and invisible.
 
+#### `gog-alert`
+
+A **persistent, in-flow message** — the one `gog-toast` cannot be. No timer, no queue, no overlay,
+no service: it renders where you write it and stays until your app removes it.
+
+| Input         | Type                               | Default         |
+| ------------- | ---------------------------------- | --------------- |
+| `severity`    | `GogSeverity`                      | `'accent'`      |
+| `heading`     | `string \| undefined`              | `undefined`     |
+| `dismissible` | `boolean`                          | `false`         |
+| `iconName`    | `GogIconName \| null \| undefined` | `undefined`     |
+| `live`        | `GogAlertLive \| undefined`        | _from severity_ |
+
+| Output      | Type   | When                             |
+| ----------- | ------ | -------------------------------- |
+| `dismissed` | `void` | the close button was **pressed** |
+
+Slot: `<ng-template gogAlertIcon>` for custom icon markup. Body is projected content.
+
+```html
+<gog-alert severity="danger" heading="Payment failed" [dismissible]="true" (dismissed)="hide()">
+  The card issuer declined the charge. No money has left your account.
+</gog-alert>
+```
+
+**`dismissed` means pressed, not removed.** The alert stays in the DOM and your app decides what
+happens — hide it, retry, navigate. A component that deleted itself would take the focused element
+with it and drop a keyboard reader back onto `<body>`.
+
+The severity picks both the edge colour and the glyph (`success`/`error`/`warning`/`info`;
+`'accent'` borrows `info`'s, because it claims nothing). `iconName` overrides the glyph and
+**`[iconName]="null"` removes it** for a message whose words already carry the meaning.
+
+**How it announces.** `live` is `'assertive' | 'polite' | 'off'`, defaulting from the severity —
+`danger` and `warning` interrupt, the rest wait. **Set `'off'` for a message that is already on the
+page when it loads**: that is the commonest case and the one the default gets wrong, because a
+reader arriving at a page does not need it interrupted about something that was already there.
+
+The component cannot tell those apart for you, and that was measured rather than assumed:
+`@angular/core` exposes no stability member a component can read synchronously at construction,
+and `afterNextRender` reports its _own_ first render, which every alert has whenever it mounts.
+
+The announcement lives in a **separate visually-hidden region**, empty until one render after the
+alert mounts, which is the only way it works: a live region filled in the same pass as its own
+creation announces nothing — the trap `gog-toast-container`'s permanently-mounted regions exist to
+avoid. Do not "simplify" this by putting `aria-live` on the alert itself.
+
+`GOG_CONFIG.labels.closeAlert` names the dismiss button.
+
 #### `gog-tag`
 
 | Input       | Type                  | Default     |
@@ -1563,29 +1671,37 @@ they never asked to be.
 
 #### `gog-table<T>`
 
-| Input                         | Type                          | Default                             |
-| ----------------------------- | ----------------------------- | ----------------------------------- |
-| `value`                       | `T[]`                         | `[]`                                |
-| `fullWidth`                   | `boolean`                     | `true`                              |
-| `pageSize`                    | `model<number>`               | `0` (no pagination) — two-way       |
-| `showPageSizeSelect`          | `boolean \| undefined`        | `false`; forwarded to the paginator |
-| `pageSizeOptions`             | `number[] \| undefined`       | `[10, 20, 30, 40, 50]`; forwarded   |
-| `showRowNumbers`, `showTotal` | `boolean`                     | `true`, `false`                     |
-| `emptyPlaceholder`            | `string`                      | `'-'`                               |
-| `paginatorPosition`           | `'left'\|'center'\|'right'`   | `'center'`                          |
-| `totalPosition`               | `'left'\|'right'\|'opposite'` | `'opposite'`                        |
-| `loading`                     | `boolean`                     | `false`                             |
-| `showColumnBorders`           | `boolean`                     | `false`                             |
-| `stickyHeader`                | `boolean`                     | `false` — pair with `maxHeight`     |
-| `maxHeight`                   | `string \| null`              | `null` — any CSS length             |
-| `size`                        | `GogSize`                     | `'lg'` (row density — not `'md'`)   |
-| `lazy`                        | `boolean`                     | `false` — see below                 |
-| `totalRecords`                | `number \| null`              | `null` — `lazy` only                |
-| `selectionMode`               | `GogTableSelectionMode`       | `'none'`                            |
-| `selection`                   | `model<T[]>`                  | `[]` — two-way bindable             |
-| `dataKey`                     | `string`                      | `''` — row identity field           |
-| `showSelectionColumn`         | `boolean`                     | `true` (once selection is on)       |
-| `interactiveRows`             | `boolean`                     | `false`                             |
+**Import from `@guildofgleks/ui/table`** — `TableComponent`, `GogColumn` and its template directives, `defaultCompare`, and the table's
+event and context types. The root still exports them in 21.13.0 and
+stops in **21.14.0**, which is when the code moves into that entry point and a lazy route that
+uses them stops carrying them in the initial bundle. **Your editor will not strike the root
+import through**: ng-packagr's bundled types drop the deprecation tags on re-exports, measured. The
+notice is this line, `CHANGELOG.md` and `GOG_DEPRECATIONS`.
+
+| Input                         | Type                          | Default                                   |
+| ----------------------------- | ----------------------------- | ----------------------------------------- |
+| `value`                       | `T[]`                         | `[]`                                      |
+| `fullWidth`                   | `boolean`                     | `true`                                    |
+| `pageSize`                    | `model<number>`               | `0` (no pagination) — two-way             |
+| `showPageSizeSelect`          | `boolean \| undefined`        | `false`; forwarded to the paginator       |
+| `pageSizeOptions`             | `number[] \| undefined`       | `[10, 20, 30, 40, 50]`; forwarded         |
+| `showRowNumbers`, `showTotal` | `boolean`                     | `true`, `false`                           |
+| `emptyPlaceholder`            | `string`                      | `'-'`                                     |
+| `paginatorPosition`           | `'left'\|'center'\|'right'`   | `'center'`                                |
+| `totalPosition`               | `'left'\|'right'\|'opposite'` | `'opposite'`                              |
+| `loading`                     | `boolean`                     | `false`                                   |
+| `showColumnBorders`           | `boolean`                     | `false`                                   |
+| `stickyHeader`                | `boolean`                     | `false` — pair with `maxHeight`           |
+| `maxHeight`                   | `string \| null`              | `null` — any CSS length                   |
+| `size`                        | `GogSize`                     | `'lg'` (row density — not `'md'`)         |
+| `lazy`                        | `boolean`                     | `false` — see below                       |
+| `totalRecords`                | `number \| null`              | `null` — `lazy` only                      |
+| `selectionMode`               | `GogTableSelectionMode`       | `'none'`                                  |
+| `selection`                   | `model<T[]>`                  | `[]` — two-way bindable                   |
+| `dataKey`                     | `string`                      | `''` — row identity field                 |
+| `showSelectionColumn`         | `boolean`                     | `true` (once selection is on)             |
+| `interactiveRows`             | `boolean`                     | `false`                                   |
+| `virtualize`                  | `boolean`                     | `false` — needs `maxHeight` + `fullWidth` |
 
 Outputs: `gogSortChange: GogTableSortEvent` (`{ field, direction }`, `{ field: '', direction:
 null }` when the third click clears it), `gogPageChange: number` (1-based; **does not fire** on
@@ -1599,6 +1715,41 @@ total evenly. Before 21.6.0 that split clipped the widest header, and a `width`
 the workaround — under auto layout a stated `width` is a suggestion weighed against content
 rather than a hard split, so those can usually go.
 
+**`virtualize` renders only the rows in view**, for a table long enough that stamping every row is
+the cost. It **requires `maxHeight` and `fullWidth`**, does nothing without either, and says which
+is missing in a dev-mode warning rather than half-working:
+
+- Without `maxHeight` the table never scrolls vertically on its own, so there is no viewport to
+  window against — the same constraint `stickyHeader` has, below.
+- `fullWidth="false"` means `table-layout: auto`, and the browser then sizes columns from the rows
+  that are **rendered**. Measured: rendering 2 of 24 rows moved columns by up to 7.8px, so a
+  windowed table would shift its own columns as you scroll.
+
+Unlike the three dropdowns' `virtualize`, this one deals in rows whose heights genuinely differ —
+**a table row's height cannot be pinned**, because `height` on a `<tr>` or `<td>` is a _minimum_ in
+table layout, so a cell whose content wraps makes its row taller and no CSS stops it. The window
+measures each row as it renders and corrects itself, which means the scroll height is an estimate
+that sharpens as you scroll rather than an exact figure from the start.
+
+What else changes while it is on: `Ctrl+F` finds only the rendered rows, CSS targeting
+`:last-child` matches the last rendered one, and with `interactiveRows` scrolling a focused row out
+of view moves focus to the scroll region, because the row it was on no longer exists.
+`aria-rowcount` and `aria-rowindex` keep the announced size and position honest, and every index
+the table hands out — `gogRowClick`'s `index`, the `showRowNumbers` column, and
+`GogColumnBodyContext.index` — still counts from the top of the page rather than the top of the
+window. There is a ceiling: Chrome clamps an element at 33 554 426px, about **745 000 rows** at 45px, and a dev-mode warning says so once when a table passes it — past that the rows stay correct while the scrollbar stops reaching the end of the data.
+
+**Where `gog-table` stops.** No **column resizing or reordering** by the reader — a column's
+`width`/`minWidth`/`maxWidth` are set by whoever writes the template, not dragged by whoever reads
+it. No **frozen columns**, no **expandable rows**, no **row grouping**. `[lazy]="true"` keeps the
+_fetch_ small, which is usually the half that hurts; `virtualize` above is the DOM half, and
+neither substitutes for the other. If a request needs one of the rest, it needs a data grid, and
+this is not one — say so rather than reaching for `::ng-deep`.
+
+`stickyHeader` is not any of them in disguise: it pins the header while rows scroll under it,
+which is the vertical axis. Freezing a first column against horizontal scroll is the thing that
+does not exist.
+
 **`stickyHeader` needs `maxHeight`** (both since 21.6.0 for the pairing). A sticky element
 resolves against its nearest scroll container, and the table wraps itself in a `gog-scroll`;
 once that scroller moves on either axis it is a scroll container on _both_, because CSS coerces