spiderly 19.12.4 → 19.14.0

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

@@ -268,9 +268,41 @@ The table renders the store as a **chip bar** above the header: one chip per *ap
 
 **Views** (`[views]`, `TableView[]`) are saved questions rendered as tabs above the bar: each `apply` receives the cleared store (a view is a state, not an addition) and writes with `setAndCommit`; a view whose apply is a function of *now* ("received today") declares `transient: true` so selecting it re-derives instead of restoring yesterday's answer. Column layout (visibility, order, widths, wrap) persists per view. A stored view id whose view is not in `[views]` yet (async-licensed views) is adopted when it arrives — unless the operator picked another tab meanwhile — and a restored transient view re-derives its question. **Sort is view state too**: entering a view resolves the user's per-view sort override ?? the view's declared `sort` ?? the table's `defaultSortField` ?? unsorted — it never inherits the previous tab's ordering, so give the catch-all first view a table-level default when "newest first" isn't what you want there.
 
+**A view tab can show a count**: `count?: number | null` renders a badge beside the label (`null` or absent shows none, `0` shows one). The table never computes it — run your own count query beside each list load and rebuild `[views]` with the fresh numbers, keeping each view's `id` stable. A rebuild neither re-enters the active view nor sends a request: a stored view id is adopted only from a change that *brings* that view, and the tabs are tracked by `id`, so the focused tab keeps focus.
+
+```typescript
+this.views = this.views.map((view) => ({ ...view, count: counts[view.id] }));
+```
+
+**A count can honor each view's saved filters**: the table's `viewFilterPayload(viewId)` returns the `filters` payload that view's own list request carries, so a count query that applies it counts the rows that tab lists (on screen for the active view, after a click for the others), including bar filters the user saved on that view. The active view answers with the live filters; any other view with what a click would enter: its saved filters, else its `apply` (always `apply` for a transient view). It switches nothing and sends no request. `apply` runs on a scratch store for this, so it must write only into the store it receives. It returns `{}` on a table without `[filters]` and `null` for an id not in `[views]` (yet). Call it beside each list load; a non-static `@ViewChild` is still unresolved during the first one, so hand the table in from a template reference:
+
+```html
+<spiderly-data-table #table [views]="views" (onLazyLoad)="refreshCounts(table)" ...></spiderly-data-table>
+```
+
+```typescript
+refreshCounts(table: SpiderlyDataTableComponent): void {
+  const filtersByView: Record<string, Record<string, FilterRule[]>> = {};
+  for (const view of this.views) {
+    const filters = table.viewFilterPayload(view.id);
+    if (filters) filtersByView[view.id] = filters; // null: the table does not hold this view yet
+  }
+  // send filtersByView with your count query, then rebuild [views] with the counts
+}
+```
+
+**A view can declare its columns**: `columns` is a field → visible map that overrides `Column.visible` in that view only, naming just the deviation — a column it does not name keeps its `Column.visible`. Visibility resolves per field as the user's own per-view choice ?? the view's `columns` ?? `Column.visible`; the user's choice is stored only where it differs from the view's declaration, *Reset to default* returns to the declaration, and `lockVisible` columns always show. To swap one column for another, declare them next to each other in `cols` (the swapped-in one `visible: false`) and the view's column takes the other's place. Type the row as the second generic to check the field names.
+
+```typescript
+const views: TableView<OrderFilters, Order>[] = [
+  { id: 'all', label: 'All' },
+  { id: 'late', label: 'Late goods', columns: { why: true, assignedLocation: false } },
+];
+```
+
 ### Column chooser (show/hide columns)
 
-Lazy tables render a **Columns** toolbar button opening a checkbox list of all data columns. Declare rarely-needed columns with `visible: false` (available in the chooser, hidden by default) and pin the row's identifying column with `lockVisible: true`. Hiding a column never touches its filter or sort — the chip bar is where both stay visible. 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.
+Lazy tables render a **Columns** toolbar button opening a checkbox list of all data columns. Declare rarely-needed columns with `visible: false` (available in the chooser, hidden by default) and pin the row's identifying column with `lockVisible: true`. Hiding a column never touches its filter or sort — the chip bar is where both stay visible. 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. On a table with `[views]` the key carries the view (`` `${stateKey}:${viewId}:columns` ``) and the declared configuration is the active view's `columns` over `Column.visible`.
 
 The `onClick` callback receives an `ActionClickEvent` — `{ id, row, element, originalEvent }`. Use `element` (or `originalEvent`) to anchor an overlay/popover to the clicked action; `row` gives you the full row object. It fires only for custom `field` values (never `'Details'` / `'Delete'`).
 
@@ -371,7 +403,7 @@ Set the inset rather than stretching `--spiderly-topbar-height`, which is the to
 | ---------------------------------- | ------------------------ | ------- | ----------------------- |
 | `cols`                             | `Column[]`               | —       | Column definitions      |
 | `filters`                          | `FilterSource`           | —       | The page's filter store (see Filtering); read once at init |
-| `views`                            | `TableView[]`            | —       | Saved questions rendered as tabs above the bar |
+| `views`                            | `TableView[]`            | —       | Saved questions rendered as tabs above the bar, each with an optional `count` badge and declared `columns` |
 | `getPaginatedListObservableMethod` | `(filter) => Observable` | —       | Server-side data source |
 | `additionalFilterIdLong`           | `number`                 | —       | Parent entity filter    |
 | `hasLazyLoad`                      | `boolean`                | `true`  | Server vs client mode   |

package/agent/docs/entity-design/index.md

@@ -89,8 +89,8 @@ public virtual Brand Brand { get; set; }
 ### Rules
 
 - Naming convention: `{NavigationName}Id` — resolved automatically. Use `[ForeignKey(nameof(OtherName))]` only when you need a different scalar name.
-- Nullability must match the relationship: `[Required]` navigation → non-nullable scalar (`long BrandId`); optional nav (`[SetNull]`) → nullable scalar (`long? BrandId`). Mismatch raises **SPID001**.
-- Scalar type must match the parent's `Id` type (`byte`/`int`/`long`). Mismatch raises **SPID003**.
+- Nullability must match the relationship: `[Required]` navigation → non-nullable scalar (`long BrandId`); optional nav (`[SetNull]`) → nullable scalar (`long? BrandId`). Mismatch raises **SPIDERLY006**.
+- Scalar type must match the parent's `Id` type (`byte`/`int`/`long`). Mismatch raises **SPIDERLY004**.
 
 ### Caveat — generated CRUD still loads the nav