spiderly 19.12.1 → 19.12.2

package/lib/components/spiderly-data-table/spiderly-data-table.component.d.ts

@@ -10,7 +10,7 @@ import { Filter } from '../../entities/filter';
 import { LazyLoadSelectedIdsResult } from '../../entities/lazy-load-selected-ids-result';
 import { PaginatedResult } from '../../entities/paginated-result';
 import { PrimengOption } from '../../entities/primeng-option';
-import { FilterSource, SortKeyLabel } from '../../filters/filter-store';
+import { FilterSource, SortKeyLabel, SortPickOption } from '../../filters/filter-store';
 import { SpiderlyFilterTemplateDirective } from '../../directives/spiderly-filter-template.directive';
 import { ConfigServiceBase } from '../../services/config.service.base';
 import { SpiderlyMessageService } from '../../services/spiderly-message.service';
@@ -416,23 +416,32 @@ export declare class SpiderlyDataTableComponent implements OnInit, OnChanges, Af
     private get viewSortStateKey();
     /** The operator's stored sort for the active view, sanitized like any persisted sort. */
     private persistedViewSort;
-    /** The sort this view asks for: the operator's stored override, else its declared sort. */
-    private viewSort;
+    /**
+     * THE resolution ladder, named once: the operator's stored override, else the declared
+     * default (`defaultMultiSortMeta` = view's declared sort ?? table default). Null means
+     * "unsorted" — callers append their own `?? []` / blob terms rather than re-spelling the
+     * ladder, so a future term (a per-view default refinement, decision 10's columns half)
+     * lands everywhere at once.
+     */
+    private resolvedViewSort;
     /**
      * Records the current sort as the active view's override — called from the EXPLICIT sort
-     * gestures only (header click, menu sort, Clear filters), never from a load: a sort merely
-     * inherited at init must not crystallize into an override, or a later change to the view's
-     * declared sort would stop flowing to operators who never touched sort — the same
-     * flows-through rule `columnVisibilityOverrides` documents. A sort equal to the declared
-     * default is stored as ABSENCE for the same reason.
+     * gestures only (header click, `applySort` — the menu and both bar entry points), never
+     * from a load: a sort merely inherited at init must not crystallize into an override, or a
+     * later change to the view's declared sort would stop flowing to operators who never
+     * touched sort — the same flows-through rule `columnVisibilityOverrides` documents. A sort
+     * equal to the declared default is stored as ABSENCE for the same reason.
      */
     private persistActiveViewSort;
     /**
-     * Puts the entering view's sort on the grid — stored override first, then the declared sort;
-     * a view stating no preference keeps the ordering already there (the pre-decision-10-sort
-     * behavior, and the least surprising for the tab an operator never sorted). Broadcast only —
-     * the caller owns the refetch, because which request carries the new sort differs between the
-     * store and storeless paths.
+     * Puts the entering view's sort on the grid — stored override, else declared sort, else the
+     * table default, else UNSORTED. A view is a COMPLETE state, sort included (2026-09-06,
+     * grilled — supersedes the "a view stating no preference keeps the ordering already there"
+     * this first shipped with): the carried-over ordering read as a bug in its first live week,
+     * when "Poslate"'s statusChangedAt rode onto "Sve", whose sorted column ships hidden —
+     * read-only chip, no header to tri-state, no way out. Polaris IndexFilters is the model:
+     * sort is part of a view's saved definition. Broadcast only — the caller owns the refetch,
+     * because which request carries the new sort differs between the store and storeless paths.
      */
     private applyViewSort;
     /**
@@ -538,8 +547,8 @@ export declare class SpiderlyDataTableComponent implements OnInit, OnChanges, Af
     /**
      * Switches to a view. Clears first, always: a view is a STATE rather than an addition, and two
      * of them composed produce a question nobody asked. The clear runs through the store directly
-     * rather than through `clear(table)`, which would also wipe the sort and the persisted state a
-     * view is entitled to keep.
+     * rather than through `clear()`, whose requery effect would spend a fetch before the entering
+     * view's filters are in place.
      */
     selectView(view: TableView): void;
     /**
@@ -636,6 +645,35 @@ export declare class SpiderlyDataTableComponent implements OnInit, OnChanges, Af
      * left falls back to its own name rather than vanishing.
      */
     private refreshSortKeys;
+    /**
+     * Gates the picker's reset row. Refreshed with `sortKeys` — same request, same reason it is a
+     * field rather than a getter. "Default" is view-aware (`defaultMultiSortMeta`), so inside a
+     * view the row offers the view's ordering back, not the table's.
+     */
+    sortIsDefault: boolean;
+    /**
+     * What the bar's picker offers: every sortable data column, hidden ones INCLUDED — the picker
+     * exists so an ordering does not need its column on screen. Built once in `ngOnInit` (columns
+     * are a declaration, not state) and labelled here because the bar knows nothing about columns.
+     */
+    sortPickOptions: SortPickOption[];
+    /**
+     * The one body of an explicit sort GESTURE — the thing `persistActiveViewSort`'s doc calls
+     * "explicit gestures only": page one, meta on the grid, fetch, save, selection anchor
+     * invalidated, override recorded. Shared by the header's single-click un-sort, the header
+     * menu and both bar entry points; `broadcastSort` is its deliberate no-fetch sibling. The
+     * page reset, `saveState` and anchor line mirror PrimeNG's own `sort()` (`sortMultiple()`
+     * does none of the three); the "lands on page one" / "survives a reload" specs pin why.
+     */
+    private applySort;
+    /** The picker's ask: one sort, replacing the whole meta — the same contract as the header menu. */
+    sortFromBar(pick: SortMeta): void;
+    /**
+     * Back to the resolved default — the view's declared sort, else the table default, else
+     * unsorted. Persisting right after is what empties the override slot: a sort equal to the
+     * default is stored as absence, so the declared ordering flows through again.
+     */
+    resetSortFromBar(): void;
     /** This column's share, override first, then its declared width, then the per-type default. */
     columnShare(col: Column): number;
     /**
@@ -716,11 +754,16 @@ export declare class SpiderlyDataTableComponent implements OnInit, OnChanges, Af
     actionTrackByFn(index: any, item: Action): string;
     exportListToExcel(): void;
     /**
-     * Clears everything that narrows the grid. With a store supplied it has to reach BOTH — the
-     * store holds the constraints and PrimeNG holds the persisted state and sort — or the bar goes
-     * empty while a reload brings the old filters back.
+     * Clears the FILTERS — and nothing else (2026-09-06, grilled). It used to also reach the
+     * sort and PrimeNG's persisted state, which made "Clear filters" a reset the label never
+     * claimed: sort is its own channel with its own affordances (the bar's picker, the header's
+     * tri-state), mirroring Polaris, where onClearAll is wired to the Filters while
+     * sortSelected never passes through it. The store's requery effect owns the refetch and the
+     * persisted-snapshot update — the button only renders with chips on the bar, so the applied
+     * set always changes — and dropping table.clear() also drops the second, unsequenced
+     * request the 2026-09-05 review flagged on every Clear.
      */
-    clear(table: Table): void;
+    clear(): void;
     setFakeIsAllSelected(): void;
     selectAll(checked: boolean): void;
     /**

package/lib/filters/filter-store.d.ts

@@ -164,12 +164,22 @@ export type FilterSnapshot = Record<string, {
     value: unknown;
 }>;
 /**
- * One sort key as the bar draws it. Sort deliberately does NOT live in the filter store:
- * `multiSortMeta` already holds it, keyed by field, and a copy here would be a second source of
- * truth for one fact. The bar is one surface reading two owners.
+ * One column the bar's sort picker offers, labelled by whoever owns the columns — the bar knows
+ * nothing about them. Hidden sortable columns belong in the list: the picker exists precisely so
+ * an ordering does not need its column on screen (decision 2b's sort half).
  */
-export interface SortKeyLabel {
+export interface SortPickOption {
+    field: string;
     label: string;
+}
+/**
+ * One sort key as the bar draws it — a pick option WITH its direction. Sort deliberately does
+ * NOT live in the filter store: `multiSortMeta` already holds it, keyed by field, and a copy
+ * here would be a second source of truth for one fact. The bar is one surface reading two
+ * owners. `field` is what lets the picker mark the active row and flip its direction; the
+ * label alone could not say which option it names once two columns share a name.
+ */
+export interface SortKeyLabel extends SortPickOption {
     descending: boolean;
 }
 /** One applied constraint, in the shape the chip bar draws. */

package/lib/filters/spiderly-filter-bar.component.d.ts

@@ -1,7 +1,8 @@
 import { QueryList, TemplateRef } from '@angular/core';
+import { SortMeta } from 'primeng/api';
 import { SpiderlyFilterTemplateDirective } from '../directives/spiderly-filter-template.directive';
 import { MatchModeCodes } from '../enums/match-mode-enum-codes';
-import { AppliedFilter, FilterBarSource, FilterHandle, FilterOption, SortKeyLabel } from './filter-store';
+import { AppliedFilter, FilterBarSource, FilterHandle, FilterOption, SortKeyLabel, SortPickOption } from './filter-store';
 import * as i0 from "@angular/core";
 /**
  * Lowercased and stripped of diacritics for matching. NFD decomposition handles č/ć/š/ž, but NOT
@@ -33,8 +34,20 @@ export declare class SpiderlyFilterBarComponent {
      * about columns, so whoever owns the sort resolves the names.
      */
     readonly sort: import("@angular/core").InputSignal<SortKeyLabel[]>;
+    /**
+     * What the picker offers, labelled by the owner — every sortable column, HIDDEN ones
+     * included (their ordering is otherwise unreachable, which is the trap the picker closes).
+     * Empty keeps the chip read-only and the picker off.
+     */
+    readonly sortOptions: import("@angular/core").InputSignal<SortPickOption[]>;
+    /** Whether the grid already sits on its default ordering — gates the reset row, nothing else. */
+    readonly sortIsDefault: import("@angular/core").InputSignal<boolean>;
     /** Asked for, never done here — see the button's comment. */
     readonly clearAll: import("@angular/core").OutputEmitterRef<void>;
+    /** A single-sort ask. Multi-sort stays a header gesture (ctrl-click); the picker replaces. */
+    readonly sortPick: import("@angular/core").OutputEmitterRef<SortMeta>;
+    /** Back to the owner's default ordering — the owner knows what that resolves to, not the bar. */
+    readonly sortReset: import("@angular/core").OutputEmitterRef<void>;
     private readonly transloco;
     /** For the chip's date wording — the same locale mechanism the table's cells format with. */
     private readonly locale;
@@ -45,6 +58,7 @@ export declare class SpiderlyFilterBarComponent {
      */
     readonly controlTemplates: import("@angular/core").InputSignal<QueryList<SpiderlyFilterTemplateDirective>>;
     readonly isAddOpen: import("@angular/core").WritableSignal<boolean>;
+    readonly isSortOpen: import("@angular/core").WritableSignal<boolean>;
     /** Cleared when the popover closes, so reopening never starts inside someone's old query. */
     readonly addSearch: import("@angular/core").WritableSignal<string>;
     /** The filter whose control is open. One at a time: the bar edits, it is not a form. */
@@ -81,6 +95,23 @@ export declare class SpiderlyFilterBarComponent {
     }[]>;
     /** Opens a filter's control. Where it renders, and why not a popover: the template comment. */
     startEditing(id: string): void;
+    /**
+     * The menu's rows: each option decorated with its ACTIVE direction's arrow (any key, not
+     * just the primary), or null. A `computed`, not a per-row method call in the binding — the
+     * popover's content is projected, so it change-detects even while closed, and a `find` per
+     * option per pass is exactly what `operatorChoices` documents against.
+     */
+    readonly sortRows: import("@angular/core").Signal<{
+        arrow: string;
+        field: string;
+        label: string;
+    }[]>;
+    /**
+     * Ascending first; picking the already-ascending primary flips it. The direction is decided
+     * HERE so the owner applies exactly what the menu showed — an owner guessing "toggle" from its
+     * own state could disagree with a stale menu after a concurrent header click.
+     */
+    pickSort(option: SortPickOption): void;
     /** The raw-string controls only. Nothing reaches the bar or the query until `apply`. */
     draft(handle: FilterHandle, event: Event): void;
     controlTemplateFor(handle: FilterHandle): TemplateRef<unknown> | null;
@@ -128,5 +159,5 @@ export declare class SpiderlyFilterBarComponent {
      */
     chipValue(chip: AppliedFilter): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<SpiderlyFilterBarComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SpiderlyFilterBarComponent, "spiderly-filter-bar", never, { "filters": { "alias": "filters"; "required": true; "isSignal": true; }; "totalRecords": { "alias": "totalRecords"; "required": false; "isSignal": true; }; "sort": { "alias": "sort"; "required": false; "isSignal": true; }; "controlTemplates": { "alias": "controlTemplates"; "required": false; "isSignal": true; }; }, { "clearAll": "clearAll"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpiderlyFilterBarComponent, "spiderly-filter-bar", never, { "filters": { "alias": "filters"; "required": true; "isSignal": true; }; "totalRecords": { "alias": "totalRecords"; "required": false; "isSignal": true; }; "sort": { "alias": "sort"; "required": false; "isSignal": true; }; "sortOptions": { "alias": "sortOptions"; "required": false; "isSignal": true; }; "sortIsDefault": { "alias": "sortIsDefault"; "required": false; "isSignal": true; }; "controlTemplates": { "alias": "controlTemplates"; "required": false; "isSignal": true; }; }, { "clearAll": "clearAll"; "sortPick": "sortPick"; "sortReset": "sortReset"; }, never, never, true, never>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spiderly",
-  "version": "19.12.1",
+  "version": "19.12.2",
   "author": "Filip Trivan",
   "license": "MIT",
   "description": "Spiderly Angular Library to use in combination with Spiderly.",

package/styles/filters/spiderly-filter-bar.component.scss

@@ -147,12 +147,49 @@
   font-size: 0.875rem;
 }
 
+// The picker's trigger — same chip, now a button. bare-button resets the UA chrome; the hover
+// underline mirrors the filter chips' edit affordance so "this opens something" reads the same
+// across the bar.
+button.sort-chip {
+  @include bare-button();
+  cursor: pointer;
+
+  &:hover .sort-chip-key,
+  &:hover .sort-chip-label {
+    text-decoration: underline;
+  }
+}
+
+.sort-chip-caret {
+  font-size: 0.65rem;
+}
+
 .sort-chip-key {
   // The direction arrow is the non-colour channel; the priority is the reading order, which is
   // the thing the scattered header icons could never show.
   color: var(--p-text-color);
 }
 
+// Teleported with its popover into document.body, so TOP LEVEL like the add menu above it
+// (Angular/CLAUDE.md → overlay styling); pinned by the "sort menu styles survive the body
+// teleport" spec. Inherits .filter-add-option for the row look.
+.sort-menu-option {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+}
+
+.sort-menu-direction {
+  color: var(--p-primary-color);
+}
+
+.sort-menu-reset {
+  border-top: 1px solid var(--p-content-border-color);
+  border-radius: 0;
+  color: var(--p-text-muted-color);
+}
+
 .filter-bar-clear {
   // Pushed to the far end, away from the chips: a destructive action next to the x it resembles
   // is how a single chip gets removed by someone reaching for all of them. It is also the LAST