@guildofgleks/ui 21.3.2 → 21.4.1

package/AGENTS.md

@@ -5,7 +5,7 @@ an app that **consumes** the published `@guildofgleks/ui` npm package. It is not
 authoring the library — if you are working inside the `gleks_web_ui` monorepo itself, read
 `.github/instructions/*.md` instead.
 
-Everything below reflects the library's actual source as of **`21.3.2`**. `README.md` covers the
+Everything below reflects the library's actual source as of **`21.4.0`**. `README.md` covers the
 same ground at a higher level — install, setup, theming, global configuration — and is accurate;
 this file goes further, into per-component input tables, and is the one to trust for exact names,
 types and defaults.
@@ -211,9 +211,10 @@ parent's config**, one level deep per key — it does not replace it.
 | `button`       | `debounce`                                                         | `gog-button`.                                                                                                                                                                                                                                                                                                                                                                                                |
 | `inputfield`   | `showSpinButtons`                                                  | `gog-inputfield`.                                                                                                                                                                                                                                                                                                                                                                                            |
 | `textarea`     | `resize`                                                           | `gog-textarea`.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `paginator`    | `showPageSizeSelect`, `pageSizeOptions`                            | `gog-paginator`, and through it `gog-table`'s built-in pagination.
 | `toast`        | `position`, `duration`                                             | `ToastService`.                                                                                                                                                                                                                                                                                                                                                                                              |
 | `theme`        | `storageKey`, `defaultTheme`, `followSystem`, `lightTheme`, `darkTheme` | `ThemeService`. All off/neutral by default — see below.                                                                                                                                                                                                                                                                                                                                                 |
-| `labels`       | every fixed string the library renders — see below                 | inputfield, textarea, select, multiselect, autocomplete, datepicker, calendar, paginator, `DialogService`, `ToastService`.                                                                                                                                                                                                                                                                                    |
+| `labels`       | every fixed string the library renders — see below                 | inputfield, textarea, select, multiselect, autocomplete, datepicker, calendar, paginator, table, `DialogService`, `ToastService`.                                                                                                                                                                                                                                                                                    |
 
 Anything visual does **not** belong here — override the `--gog-*` token instead.
 
@@ -240,6 +241,11 @@ provideGogConfig({
     previousPage: 'Предыдущая страница',
     nextPage: 'Следующая страница',
     openCalendar: 'Открыть календарь',
+    rowsPerPage: 'Строк на странице', // gog-paginator's size select
+    total: 'Всего', // gog-table's row-count label
+    tablePagination: 'Навигация по таблице',
+    selectRow: 'Выбрать строку',
+    selectAllRows: 'Выбрать все строки на странице',
     today: 'Сегодня',
     thisMonth: 'Текущий месяц',
     previousMonth: 'Предыдущий месяц',
@@ -717,16 +723,102 @@ family of date-math helpers (`addDays`, `addMonths`, `isSameDay`, `isWithinBound
 | `title`      | `string`              | `''`                                               |
 | `ariaHidden` | `boolean`             | `true`                                             |
 
-`GogIconName` is a **closed set of exactly 20 names**: `check`, `close`, `chevron-up`,
-`chevron-down`, `chevron-left`, `chevron-right`, `calendar`, `clock`, `sort`, `sort-up`,
-`sort-down`, `success`, `error`, `warning`, `info`, `checkbox`, `checkbox-checked`, `eye`,
-`eye-off`, `copy`. There is no way to pass an arbitrary SVG/URL as `name` — use the `template`
-input (or project your own `<svg>`/icon component elsewhere) for anything outside this set.
+The package ships **41** glyphs (`GogBuiltinIconName`), all from [Lucide](https://lucide.dev)
+and inlined so the package keeps zero runtime dependencies:
+
+| Group | Names |
+| --- | --- |
+| Chevrons & arrows | `chevron-up`, `chevron-down`, `chevron-left`, `chevron-right`, `arrow-left`, `arrow-right` |
+| Confirm & dismiss | `check`, `close`, `checkbox`, `checkbox-checked` |
+| Status | `success`, `error`, `warning`, `info` |
+| Sorting | `sort`, `sort-up`, `sort-down`, `filter` |
+| Actions | `search`, `plus`, `minus`, `trash`, `pencil`, `copy`, `download`, `upload`, `refresh`, `external-link` |
+| Chrome | `menu`, `more-horizontal`, `more-vertical`, `settings` |
+| Objects & state | `user`, `lock`, `mail`, `calendar`, `clock`, `eye`, `eye-off`, `star`, `star-filled` |
+
+`star` / `star-filled` is the one outline/filled pair, for a rating or favourite **toggle** —
+the same reason `checkbox` / `checkbox-checked` exists. The set is otherwise outline-only on
+purpose; a blanket solid duplicate of every glyph would double the payload for a distinction
+almost nothing needs. If you want a filled variant of something else, register it with
+`provideGogIcons`.
+
+`Object.keys(ICON_DEFS)` is the runtime list, if you need to enumerate them (an icon picker, a
+gallery). Do not hand-copy the names into an array — that is what goes stale.
 
 ```html
 <gog-icon name="calendar" />
 ```
 
+##### Registering your own icons — `provideGogIcons(...)`
+
+`name` is typed `GogIconName = GogBuiltinIconName | (string & {})`: the built-ins autocomplete,
+and any name you register is accepted. **This is the supported way to use your own icon set** —
+prefer it over the `template` input, which costs an `<ng-template>` at every use site and is for
+one-offs.
+
+```ts
+// app.config.ts
+import { provideGogIcons } from '@guildofgleks/ui';
+
+providers: [
+  provideGogIcons({
+    cart: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>',
+    rocket: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>',
+  }),
+];
+```
+
+```html
+<gog-icon name="cart" />
+<gog-tag iconName="cart">In basket</gog-tag>
+<!-- works anywhere an icon *name* is taken -->
+```
+
+- **Registered names win over built-ins of the same name** — that is how you replace the
+  library's checkmark or chevrons across every component at once, without touching any of them.
+- **Nested `provideGogIcons(...)` layers onto the parent set** rather than replacing it, the same
+  as `provideGogConfig`: a lazy route can register only what it uses.
+- **An unknown name renders nothing and warns in dev mode; it never throws.** An icon is
+  decoration — failing the render over a typo would be the worse outcome.
+- **Write the SVG for inheritance:** a `viewBox`, `stroke="currentColor"` (or `fill`), and no
+  width/height — `gog-icon` drives size and stroke width from the `--gog-icon-*` tokens, so a
+  registered icon scales and colours like a built-in.
+- **Security:** the markup is inserted with `bypassSecurityTrustHtml` (Angular's HTML sanitizer
+  strips SVG, so there is no alternative). That is fine for static icon markup you authored;
+  **never** build a registered icon string from user input or fetch it at runtime unsanitized.
+
+#### `[gogButton]` — the link-flavoured button
+
+`gog-button` renders its own `<button>`, so it can never *be* a link. `[gogButton]` inverts that:
+the element stays yours and the directive only gives it the look.
+
+```html
+<a gogButton routerLink="/pricing">See pricing</a>
+<a gogButton variant="ghost" href="https://example.com" target="_blank" rel="noreferrer">Docs</a>
+<button gogButton variant="outline" size="sm" type="submit">Save</button>
+<a gogButton fullWidth routerLink="/checkout">Checkout</a>
+```
+
+| Input       | Type                    | Default                              |
+| ----------- | ----------------------- | ------------------------------------ |
+| `variant`   | `GogVariant`            | `'primary'`                          |
+| `size`      | `GogSize \| undefined`  | `'md'`; via `GOG_CONFIG.control.size` |
+| `fullWidth` | `boolean` (bare attr ok) | `false`                              |
+
+Selector is `a[gogButton], button[gogButton]` — deliberately not a bare `[gogButton]`, because on
+a `<div>` the result looks like a button and is invisible to the keyboard and to assistive tech.
+
+**Which to reach for.** `gog-button` for a button that acts on the page: it owns `loading` (a
+centred spinner it projects), `debounce` click throttling and the `gogClick` output, none of which
+a bare element can provide. `[gogButton]` when the element must be a link, or when you need to
+keep directives of your own on it — `routerLink`, `href`, `target`, `download`, `type="submit"`
+and anything else keep working because they were never brokered through an input in the first
+place. That is also why the library still has no `@angular/router` dependency.
+
+Two things it deliberately does not do: no `disabled` on an `<a>` (there is no such thing — drop
+the `href` or render a real `<button>`), and no loading state (the spinner is a projected child a
+directive cannot add without taking over the element's content).
+
 #### `[gogBadge]` — directive, not a component
 
 Decorates an existing element (a button, an icon, an avatar) with a count/status dot — it never
@@ -960,13 +1052,36 @@ hidden via `[hidden]` while inactive — preserves scroll/input state).
 | `siblingCount`                  | `number`                                         | `2` — `'ellipsis'` mode only   |
 | `size`                          | `GogSize`                                        | `'sm'`                         |
 | `disabled`, `ariaLabel`         |                                                  | `false`, `'Pagination'`        |
+| `totalRecords`                  | `number \| null`                                 | `null` — see below             |
+| `pageSize`                      | `model<number>`                                  | `10` — two-way bindable        |
+| `showPageSizeSelect`            | `boolean \| undefined`                           | `false`; via `GOG_CONFIG.paginator` |
+| `pageSizeOptions`               | `number[] \| undefined`                          | `[10, 20, 30, 40, 50]`; via `GOG_CONFIG.paginator` |
 
 The step buttons (`'Previous page'`/`'Next page'`) and the per-page names are configured, not
 input-driven: `GOG_CONFIG.labels.previousPage`/`nextPage`, and `labels.page`, a
 `(page: number, isCurrent: boolean) => string` formatter defaulting to
 `` `Page ${page}, current page` `` / `` `Go to page ${page}` ``.
 
-Model: `page: number` (1-based, self-clamps to `totalPages`).
+Models: `page: number` (1-based, self-clamps) and `pageSize: number`.
+
+**Give it `totalRecords` instead of `totalPages` when you know the row count** — it then derives
+the page count from `pageSize` itself, which is what removes the
+`computed(() => Math.ceil(total / size))` a consumer would otherwise have to write *and* keep in
+sync with the rows-per-page select:
+
+```html
+<gog-paginator
+  [(page)]="page"
+  [(pageSize)]="size"
+  [totalRecords]="items().length"
+  [showPageSizeSelect]="true"
+/>
+```
+
+`totalPages` still works and is the right input when the server tells you a page count directly;
+`totalRecords` wins when both are set. Changing the page size always returns to page 1 — "page 5"
+of 10-row pages is not "page 5" of 50-row ones, so clamping alone would leave the user somewhere
+they never asked to be.
 
 `'window'`: a fixed number of page buttons that slides to keep the current page centered.
 `'ellipsis'`: first/last pinned, `siblingCount` around the current page, "…" fills the gap
@@ -982,7 +1097,9 @@ Model: `page: number` (1-based, self-clamps to `totalPages`).
 | ----------------------------- | ----------------------------- | --------------------------------- |
 | `value`                       | `T[]`                         | `[]`                              |
 | `fullWidth`                   | `boolean`                     | `true`                            |
-| `pageSize`                    | `number`                      | `0` (no pagination)               |
+| `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'`                        |
@@ -991,6 +1108,18 @@ Model: `page: number` (1-based, self-clamps to `totalPages`).
 | `showColumnBorders`           | `boolean`                     | `false`                           |
 | `stickyHeader`                | `boolean`                     | `false`                           |
 | `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`                           |
+
+Outputs: `gogSortChange: GogTableSortEvent` (`{ field, direction }`, `{ field: '', direction:
+null }` when the third click clears it), `gogPageChange: number` (1-based; **does not fire** on
+first render, nor for the page reset a new sort causes — that reset belongs to the sort),
+`gogRowClick: GogTableRowClickEvent<T>` (`{ row, index, originalEvent }`).
 
 Columns are declared as **projected `gog-column` children**, not an input array:
 
@@ -1006,6 +1135,75 @@ Columns are declared as **projected `gog-column` children**, not an input array:
 </gog-table>
 ```
 
+##### Server-driven tables — `lazy`
+
+By default the table owns the whole data set: it sorts `value` and slices the page itself. With
+`[lazy]="true"` it does neither — `value` **is** the current page, already sorted, and the table
+renders it untouched. Supply `totalRecords` (without it the table cannot know how many pages
+exist, so pagination stays hidden and it warns in dev), then refetch from the two outputs:
+
+```html
+<gog-table
+  [value]="page()"
+  [lazy]="true"
+  [totalRecords]="total()"
+  [pageSize]="20"
+  [loading]="loading()"
+  dataKey="id"
+  (gogSortChange)="sort.set($event); reload()"
+  (gogPageChange)="pageNumber.set($event); reload()"
+>
+```
+
+Row numbers still count from the current page (`(page - 1) * pageSize + i + 1`), and `showTotal`
+reports `totalRecords` rather than `value.length`. **Do not** sort or slice `value` yourself in
+addition — that is what the flag turns off.
+
+##### Rows per page
+
+`pageSize` is a **`model`**, not an input: `[pageSize]="20"` works exactly as before, and
+`[(pageSize)]="size"` becomes possible. That is what makes the rows-per-page select work with no
+wiring — the table binds its own model straight to the paginator's, the select writes back
+through it, and there is no intermediate signal to keep in sync in either direction.
+
+```html
+<!-- off by default; turn it on per table, or app-wide via GOG_CONFIG.paginator -->
+<gog-table [value]="rows" [(pageSize)]="size" [showPageSizeSelect]="true" [pageSizeOptions]="[5, 10, 20]">
+```
+
+Changing the size returns to page 1 and does **not** emit `gogPageChange` — the consumer already
+knows from `pageSizeChange`, and firing both would make a lazy table fetch twice. In `lazy` mode
+`pageSizeChange` is the refetch signal; bind `[pageSize]` + `(pageSizeChange)` rather than the
+banana-box if you need to act on it.
+
+The footer stays visible at a single page whenever the select is on — hiding it would strand the
+user on whatever size produced that one page, with no control left to pick a smaller one.
+
+##### Selection
+
+`selectionMode` turns it on; `[(selection)]` is always a `T[]`, including in `'single'` mode
+where it holds zero or one row — one shape rather than a union to narrow on every read.
+
+```html
+<gog-table [value]="rows" selectionMode="multiple" [(selection)]="selected" dataKey="id">
+```
+
+- **Set `dataKey`.** Without it rows are matched by object identity, so any refetch that produces
+  new objects silently drops the selection. It is also the `@for` track key, which is what lets
+  the DOM survive a refetch instead of being rebuilt.
+- The checkbox column renders automatically (`showSelectionColumn` to turn it off, e.g. for a
+  table that selects by row click — pair that with `interactiveRows`).
+- The header select-all appears only in `'multiple'` mode and covers **the current page**, never
+  the whole data set: in `lazy` mode the table has never seen the other pages, and a control that
+  behaved differently between the two modes would be worse than either.
+
+##### Clickable rows
+
+`gogRowClick` fires on a click regardless, but a `<tr>` is not focusable, so on its own that is a
+mouse-only affordance. `interactiveRows` makes rows focusable and styles them as clickable, and
+Enter/Space then activate the focused row. If the action is really "open this one thing", a link
+or button inside a cell is better than a whole-row target.
+
 `gog-column` inputs: `field` (required, dot-paths ok), `header`, `sortable` (default `false`),
 `width`/`minWidth`/`maxWidth`, `comparator` (custom `(a, b) => number`, defaults to a
 locale-aware collator for strings). Slots inside a column: `<ng-template gogColumnBody let-row let-value="value" let-index="index">`,
@@ -1143,7 +1341,11 @@ Shared enum-like types (`import type { ... } from '@guildofgleks/ui'`):
 | `GogTextareaResize`           | `'vertical' \| 'horizontal' \| 'both' \| 'none'`                                              |
 | `GogInputType`                | `'text' \| 'password' \| 'email' \| 'number' \| 'search' \| 'tel' \| 'url' \| 'date' \| 'time' \| 'datetime-local'` |
 | `GogInputMode`                | `'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'`         |
+| `GogTableSelectionMode`       | `'none' \| 'single' \| 'multiple'`                                                            |
+| `GogTableSortEvent`           | `{ field: string; direction: SortDirection }`                                                 |
+| `GogTableRowClickEvent<T>`    | `{ row: T; index: number; originalEvent: MouseEvent \| KeyboardEvent }`                       |
 | `GogErrorDisplay`             | `'auto' \| 'manual'`                                                                          |
 | `GogDropdownDirection`        | `'auto' \| 'up' \| 'down'`                                                                    |
 | `GogTooltipSide`              | `'top' \| 'bottom' \| 'left' \| 'right'` (resolved form of `GogTooltipPosition`, no `'auto'`) |
-| `GogIconName`                 | closed set of 20 — see [`gog-icon`](#gog-icon)                                                |
+| `GogBuiltinIconName`          | the 20 glyphs the package ships — see [`gog-icon`](#gog-icon)                                 |
+| `GogIconName`                 | `GogBuiltinIconName \| (string & {})` — built-ins plus anything registered via `provideGogIcons` |