spiderly 19.11.3 → 19.11.4

package/agent/docs/angular-customization/index.md

@@ -22,7 +22,7 @@ Keep admin UI **responsive and mobile-first**, matching the layout/grid conventi
 Two cross-cutting behaviors ship with every Spiderly admin and cover **every** generated-client call automatically. Re-implementing them per call is the most common needless boilerplate in admin code:
 
 - **Loading:** an HTTP interceptor shows the global full-screen blocking spinner for every request and hides it when the request settles. Read-shaped responses (autocomplete, dropdowns, table pagination, bare-scalar GETs) are exempted server-side via `[SkipSpinner]` inference — see the `custom-endpoints` skill to tune that per endpoint. Don't add per-component spinners around API calls; for layout placeholders use `card-skeleton` (catalog below).
-- **Errors:** an HTTP interceptor toasts every failed request — server-unreachable warning, the server's `BusinessException` message on 400, login/permission/not-found messages on 401/403/404, a generic error toast for the rest — then **rethrows**, so callers only ever run their success path. Uncaught non-HTTP runtime errors get a generic toast from the global `ErrorHandler`. So: **subscribe to the success path only** — no per-call `catchError` toasts, no `try/catch` around generated client calls. Add `catchError` only when you need to *react* to a specific failure (e.g. roll back optimistic UI state); the user-facing message has already been shown by the time your handler runs.
+- **Errors:** an HTTP interceptor toasts every failed request — server-unreachable warning, the server's `BusinessException` message on 400, login/permission/not-found messages on 401/403/404, a generic error toast for the rest — then **rethrows**, so callers only ever run their success path. Uncaught non-HTTP runtime errors get a generic toast from the global `ErrorHandler`. Both surfaces `console.error` every error, production included — the toast is deliberately vague, so the console is where a developer reads what actually broke. That toast tells the user the team was notified, which is only true if you make it so: **wire an error tracker** by providing an `ErrorHandler` that reports and then delegates to `SpiderlyErrorHandler` (inject it) for the toast. Report non-HTTP errors only — the interceptor already owns HTTP-error UX, and a server 5xx is in your backend's tracker under the same `traceId` the toast shows the user. So: **subscribe to the success path only** — no per-call `catchError` toasts, no `try/catch` around generated client calls. Add `catchError` only when you need to *react* to a specific failure (e.g. roll back optimistic UI state); the user-facing message has already been shown by the time your handler runs.
 
 ## Generated File Structure
 
@@ -138,6 +138,27 @@ Names are PascalCase: `show{PropertyName}For{EntityName}` (plus `showTimeOn{Prop
 
 Library components/controls also expose their own `show*` `@Input()`s (e.g. `showLabel` on every control, `showAddButton` on the data table, `showPanelHeader` on the panel) — each a plain boolean, bound the same way: `[showAddButton]="canCreate"`. See the *UI Controls Reference* and *Presentational & Layout Components* tables below for the available inputs.
 
+### Replacing a field with your own control (`below*` slots)
+
+Each property block also emits an `<ng-content select="[below{PropertyName}For{EntityName}]">` right where the field sits. Pair it with the `show*` input to swap a generated control for your own without editing generated code: hide the generated one, project yours into its slot, and bind yours to the same form control so the save body picks the value up unchanged.
+
+```html
+<user-base-details [parentFormGroup]="parentFormGroup" [showEmailForUser]="false" (onSave)="onSave()">
+  <div belowEmailForUser>
+    @if (parentFormGroup.controls.userDTO; as userDTO) {
+      <spiderly-textbox [control]="userDTO.getControl('email')"></spiderly-textbox>
+    }
+  </div>
+</user-base-details>
+```
+
+**The `@if` is required, not defensive.** Projected content belongs to *your* view, and Angular creates it with your view — the `@defer` the generated form sits behind does not defer it. So your control renders while `parentFormGroup` is still the empty group `BaseFormComponent` starts with, before `get{Entity}MainUIFormDTO` answers, and `controls.{entity}DTO` is undefined for those first change-detection passes. Unguarded, `controls.{entity}DTO.getControl(...)` throws on each one, and the global `ErrorHandler` turns every throw into the generic error toast. It stops once the data lands, so the symptom is a burst of error toasts on entering the page and then a form that works — easy to misread as a server problem.
+
+Two details that decide whether the guard actually works:
+
+- **Keep the slot attribute on a real element and put the `@if` inside it.** An `@if` anchor node carries no attribute selector, so wrapping the `<div belowEmailForUser>` in an `@if` drops the content into the default slot instead. (Same rule as conditional `[buttons]`, which needs `<ng-container ngProjectAs="[buttons]">`.)
+- **`?.` alone is not a substitute.** It hands the control `undefined`, which every control's *template* renders fine, but `spiderly-autocomplete`, `spiderly-colorpicker` and `spiderly-checkbox` (with `initializeToFalse`) dereference the control in their own `ngOnInit` and still throw. A component of your own has to be equally tolerant if you rely on `?.` instead of the guard.
+
 ## Data Table
 
 ### Lazy Load Mode (server-side pagination, default)
@@ -182,6 +203,10 @@ cols: Column<ProductDTO>[] = [
 ];
 ```
 
+Headers are click-to-sort by default; disable with `sortable: false`. Columns whose `field` ends in `CommaSeparated` are auto-disabled — the backend generates no sort case for collection columns and rejects unknown sort fields with a 400, so the table never offers the click.
+
+Column widths default per `filterType` and are sized for the **header** — the filter input plus its match-mode dropdown — so a column of short values (an amount, a status code) reserves more than it uses. `minWidth: '8rem'` overrides that floor for one column; it stays a minimum, so the table still distributes the leftover space.
+
 ### Column chooser (show/hide columns)
 
 Lazy tables render a **Columns** toolbar button opening a checkbox list of all data columns. Because a column's header is the table's only filter surface, showing a column is what makes it filterable — declare rarely-needed but filter-worthy columns with `visible: false` (available in the chooser, hidden by default) and pin the row's identifying column with `lockVisible: true`. Rules the table enforces: hiding a column clears its active filter + sort (one reload; plain hides don't hit the server), choices persist per table in `localStorage` under `` `${stateKey}:columns` `` (durable even with `stateStorage: 'session'`; only explicit toggles are stored, so later declared-default changes flow through), the last visible data column can't be hidden, and *Reset to default* restores the declared configuration.
@@ -192,21 +217,56 @@ For a click on the cell value itself (not an action icon), set a column's `onCel
 
 ```typescript
 new Column({ field: 'total', name: 'Total', filterType: 'numeric',
-  // Reusing one popover across cells: show() updates the anchor element, but it will NOT move a
-  // popover that is already open — PrimeNG re-positions via align() only during the open animation,
-  // which an already-open popover never re-enters (and hide()+show() in the same tick collapses to
-  // no state change). So after show(), call align() to re-anchor it to the new cell.
-  onCellClick: (e) => {
-    const wasOpen = this.itemsPopover.overlayVisible;
-    this.itemsPopover.show(e.originalEvent, e.element);
-    if (wasOpen) this.itemsPopover.align();
-  } }),
+  onCellClick: (e) => this.showItems(e) }),
+```
+
+It receives a `CellClickEvent` — `{ id, field, row, value, displayValue, element, originalEvent }`, where `value` is the raw cell value and `displayValue` is the formatted text shown. Only columns that set it become clickable (they get a `cursor`/hover affordance), and the click stops propagation so it does **not** also trigger `navigateOnRowClick`. Anchor overlays with `element` — it's the clicked `<td>`, captured synchronously, so it stays valid inside an async handler (`originalEvent.currentTarget` is null once dispatch ends). Not applied to editable cells.
+
+**Reusing ONE popover across cells: close it and reopen it, never re-anchor in place.** Two PrimeNG 19.1.3 bugs make the in-place move (`show()` then `align()`) unfixable from outside the library: `align()` only ever *adds* its flip class and arrow offset and never clears them, so moving from a cell the panel opened above to one it opens below leaves the arrow pointing the wrong way; and PrimeNG emits `(onHide)` from inside its own animation callback, one step *before* it clears `isOverlayAnimationInProgress`, so a `show()` fired from there hits the library's own guard and silently does nothing. Stash the new anchor, `hide()`, and reopen from `(onHide)` deferred by one microtask — every open then runs `align()` once on a fresh container:
+
+```typescript
+onCellClick: (e) => {
+  if (this.popover.overlayVisible) {
+    this.reopenAnchor = e.element;   // re-anchor: close first, reopen from (onHide)
+    this.popover.hide();
+  } else {
+    this.popover.show(e.originalEvent, e.element);
+  }
+},
+```
+
+```typescript
+onPopoverHide(): void {
+  const el = this.reopenAnchor;
+  if (el == null) return;            // ordinary dismiss (outside click / Esc)
+  this.reopenAnchor = null;
+  queueMicrotask(() => this.popover.show(null, el));
+}
 ```
 
-It receives a `CellClickEvent` — `{ id, field, row, value, displayValue, element, originalEvent }`, where `value` is the raw cell value and `displayValue` is the formatted text shown. Only columns that set it become clickable (they get a `cursor`/hover affordance), and the click stops propagation so it does **not** also trigger `navigateOnRowClick`. Anchor overlays with `element` — it's the clicked `<td>`, captured synchronously, so it stays valid inside an async handler (`originalEvent.currentTarget` is null once dispatch ends). Not applied to editable cells. (Reusing one popover across rows is the `show()` + `align()` case shown in the snippet above — bare `show()` swaps content but won't move an already-open panel.)
+The cost is a fade-out/fade-in instead of a slide. Re-check on each PrimeNG bump and delete the dance once both bugs are fixed upstream.
 
 Style the popover's content at your component's SCSS **top level**, never nested under `:host` — PrimeNG appends the open popover to `document.body`, where `:host`-scoped rules (compiled to `[_nghost] … [_ngcontent]` descendant selectors) silently stop matching; top-level rules keep the `[_ngcontent]` scoping that travels with the moved nodes.
 
+### Custom Cell Content (per-column templates)
+
+Project an `<ng-template spiderlyCellTemplate="field">` to render one column's cells yourself instead of the plain formatted value. Import `SpiderlyCellTemplateDirective` in the consuming component. Columns with no matching template keep the built-in rendering, so a table opts in one column at a time.
+
+```html
+<spiderly-data-table [cols]="cols" [getPaginatedListObservableMethod]="getListMethod">
+  <ng-template spiderlyCellTemplate="orderNumber" let-row let-displayValue="displayValue">
+    <a [routerLink]="['/orders', row.id]">{{ displayValue }}</a>
+    <div class="secondary">{{ row.itemCount }} items</div>
+  </ng-template>
+</spiderly-data-table>
+```
+
+- Context: `let-row` (`$implicit`, the full row), `let-value="value"` (raw), `let-displayValue="displayValue"` (**what the table would have rendered** — formatted for the column's `filterType` and the app's `LOCALE_ID`, so a template that only decorates the value never re-implements that), `let-col="col"`. `value` / `displayValue` mean the same here as on `CellClickEvent`, so a column carrying both a click handler and a template reads one vocabulary.
+- **Cells only.** The header, its filter and its sorting are untouched, and the filter still works on the underlying `field` whatever the template draws.
+- The template binds to the **consuming component**, so its handlers and pipes are yours.
+- A real `<a [routerLink]>` here beats `onCellClick` for navigation — middle-click and Ctrl+click open a new tab, which a JavaScript `navigate()` does not.
+- This is also the way out of the enum-cell limit: a `multiselect` column renders the raw stored value in its cell (the table does not map it through `dropdownOrMultiselectValues`), so a template that draws the label from the row's id gets the checkbox filter *and* readable cells.
+
 ### Custom Toolbar Actions
 
 Project an `<ng-template spiderlyDataTableActions>` to add your own buttons (or any markup) to the table's toolbar, alongside the built-in Clear Filters / Export to Excel / Reload / Delete Selected buttons. Import `SpiderlyDataTableActionsDirective` in the consuming component.

package/agent/docs/authorization/references/api-error-codes.generated.md

@@ -12,6 +12,9 @@ Machine-readable error codes returned in ErrorCode. Treat as a public contract
 | `ExternalEmailMissing` | `external_email_missing` | An external (OAuth/OIDC) login was validated but the provider returned no email address (e.g. the user declined the email permission, or a phone-only Facebook account). Auto-provisioning needs an email to key the account on, so login is rejected with this code and the client should route the user to another sign-in method. Distinct from EmailNotVerified, which means an email was returned but not verified. |
 | `ExternalProviderNotConfigured` | `external_provider_not_configured` | An external (OAuth) login was attempted for a provider that is not configured on the server, or that provider's token exchange failed. |
 | `ForeignKeyViolation` | `foreign_key_violation` | A database foreign-key constraint was violated — e.g. referencing a row that does not exist, or deleting a row that is still referenced by dependent rows. |
+| `InvalidMatchMode` | `invalid_match_mode` | A pagination filter rule used a match mode that is not valid for the field's type. Returned with HTTP 400. Thrown via PaginationErrors. |
 | `InvalidToken` | `invalid_token` | The JWT bearer token is missing, malformed, or expired. Returned with HTTP 401 (also surfaced in the WWW-Authenticate header); the client should refresh the token or re-authenticate. |
 | `UniqueViolation` | `unique_violation` | A database unique constraint (or unique index) was violated — e.g. saving a duplicate value for a column that must be unique. |
+| `UnknownFilterField` | `unknown_filter_field` | A pagination request filtered on a key with no generated filter case. Returned with HTTP 400; the message names the key and lists the filterable fields. Thrown via PaginationErrors. |
+| `UnknownSortField` | `unknown_sort_field` | A pagination request sorted on a field with no generated sort case (misspelled, or a non-sortable collection column). Returned with HTTP 400; the message names the field and lists the sortable fields. Thrown via PaginationErrors. |
 | `ValidationFailed` | `validation_failed` | One or more request fields failed server-side validation. Returned with HTTP 400; the per-field messages are carried in ApiErrorDTO.FieldErrors. |

package/agent/docs/filtering-patterns/index.md

@@ -31,6 +31,8 @@ public class FilterRuleDTO
 
 Filter dictionary keys are **camelCase DTO property names**. The generated `PaginatedResultGenerator` auto-resolves them to entity paths (e.g., `categoryDisplayName` → `x.Category.Name`).
 
+**Unknown fields are rejected, not ignored.** A filter key or `MultiSortMeta.Field` that matches no generated case, and any invalid `MatchMode`, throws `BusinessException` (HTTP 400) with a message naming the offender and listing the valid fields — never a silent no-op (a silently ignored filter would return unfiltered rows the caller treats as filtered). The throws come from `PaginationErrors` (`Spiderly.Shared.Exceptions`) and carry `ApiErrorCodes.UnknownFilterField` / `UnknownSortField` / `InvalidMatchMode` in `ApiErrorDTO.errorCode`, so clients branch on the code rather than the message text. `*CommaSeparated` collection fields are filterable but **not sortable**. If a hand-written override consumes a pseudo filter key the generated switch doesn't know, it must `filterDTO.Filters.Remove("...")` that key before calling `base.GetPaginated{Entity}List(...)`, or the base will reject it.
+
 ## Override `GetPaginated{Entity}List` (Most Common)
 
 The most common customization — pre-filter the query before pagination: