@elasticias/screens 0.0.16 → 1.0.1

package/types/elasticias-screens.d.ts

@@ -1,11 +1,12 @@
-import * as i0 from '@angular/core';
+import * as _angular_core from '@angular/core';
 import { OnInit, OnDestroy, Signal, InjectionToken, AfterViewInit, ChangeDetectorRef, Injector } from '@angular/core';
-import { Subject } from 'rxjs';
-import { PermissionsEnum } from '@elasticias/types';
+import { Subject, Observable } from 'rxjs';
+import { Permissions } from '@elasticias/types';
 import { Router, ActivatedRoute } from '@angular/router';
 import { NgForm } from '@angular/forms';
 import { CacheService, ToastService, ConfirmDialogService } from '@elasticias/core';
 import { Table, TableLazyLoadEvent } from 'primeng/table';
+import { Location } from '@angular/common';
 
 declare abstract class AbstractEntity {
     [key: string]: unknown;
@@ -21,8 +22,8 @@ declare abstract class AbstractComponent implements OnInit, OnDestroy {
     protected destroyed$: Subject<void>;
     abstract ngOnInit(): void;
     abstract ngOnDestroy(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<AbstractComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<AbstractComponent, "ng-component", never, { "readOnly": { "alias": "readOnly"; "required": false; }; }, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractComponent, "ng-component", never, { "readOnly": { "alias": "readOnly"; "required": false; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -50,7 +51,15 @@ declare class ScreenContext extends AbstractEntity {
         has: (key: string) => boolean;
     };
     getLabel(key: string): string;
-    isGranted(permission: PermissionsEnum): boolean;
+    isGranted(permission: Permissions): boolean;
+    get hasReadPermission(): boolean;
+    get hasCreatePermission(): boolean;
+    get hasEditPermission(): boolean;
+    get hasDeletePermission(): boolean;
+    get hasDuplicatePermission(): boolean;
+    get hasPrintPermission(): boolean;
+    get hasExportPermission(): boolean;
+    get hasImportPermission(): boolean;
     isReadOnly(): boolean;
 }
 
@@ -82,6 +91,36 @@ declare class SearchEntity extends AbstractEntity {
     getSearchCriteria(): Record<string, unknown>;
 }
 
+/**
+ * Built-in date-preset keys. `AbstractSearchScreenV2.buildDefaultDateRange`
+ * and `ef-datepicker-advanced` recognise these and compute start/end
+ * automatically; consumers can also pass a `string` for custom keys
+ * paired with a compute callback in the picker's preset list.
+ */
+type EfDatePresetKey = 'today' | 'this_week' | 'this_month' | 'last_30_days' | 'last_90_days' | 'this_quarter' | 'this_year' | 'custom' | string;
+/**
+ * Active date-range filter, owned by `AbstractSearchScreenV2.dateRange`
+ * and round-tripped through `ef-datepicker-advanced`. `start`/`end` are
+ * inclusive day boundaries (both at 00:00 local time).
+ */
+interface EfDateRange {
+    /** Inclusive start. */
+    start: Date;
+    /** Inclusive end — 00:00 local on the last day. Strict comparisons
+     *  should treat this as `< end + 1 day`. */
+    end: Date;
+    /** Which preset is active (`'custom'` for a manually picked range). */
+    presetKey: EfDatePresetKey;
+    /** Resolved literal label — formatted date range for `'custom'`,
+     *  the preset's `label` (or built-in hint) for built-ins. Used by
+     *  the trigger as the fallback when `labelKey` is empty. */
+    label: string;
+    /** Translation key for the trigger's bold value text. The picker
+     *  renders this through `| translate` so it stays reactive when
+     *  translations finish loading or the language changes. */
+    labelKey?: string;
+}
+
 interface DefaultSort {
     field: string;
     direction: SortDirectionEnum;
@@ -103,6 +142,24 @@ declare abstract class ScreenConfig {
     REFRESH_ON_SAVE?: boolean;
     REF_DATA_OPTIONS?: LoadOptions;
     DEFAULT_SORT?: DefaultSort;
+    /**
+     * Backend entity type for the standardized change-history box. When set,
+     * AbstractDetailScreenV2 auto-loads the record's audit trail (via the
+     * AUDIT_HISTORY_SERVICE token) into its `auditEntries` signal — the screen
+     * only needs `<ef-change-history [entries]="auditEntries()" />`. Leave unset
+     * to opt out. Must match the backend IAuditable.AuditEntityType (e.g. 'Client').
+     */
+    AUDIT_ENTITY_TYPE?: string;
+    /**
+     * Report screens (AbstractReportScreenV2): starting period preset for the
+     * screen's ef-datepicker-advanced. Unset → 'last_30_days'.
+     */
+    DEFAULT_PERIOD?: EfDatePresetKey;
+    /**
+     * Report screens: translatable static lists preloaded before the first
+     * loadAll() — same mechanism as SEARCH_STATIC_LISTS on list screens.
+     */
+    REPORT_STATIC_LISTS?: string[];
 }
 
 /**
@@ -151,7 +208,7 @@ declare abstract class AbstractScreenComponent extends AbstractComponent impleme
     context: ScreenContext;
     connectedUser: any;
     entityForm: NgForm;
-    serverErrors: i0.WritableSignal<{
+    serverErrors: _angular_core.WritableSignal<{
         [key: string]: string[];
     }>;
     protected refDataLoaded$: Subject<void>;
@@ -171,6 +228,20 @@ declare abstract class AbstractScreenComponent extends AbstractComponent impleme
     processGrants(): void;
     isFormValid(): boolean;
     getConfig(): any;
+    /**
+     * Read a query param from the activated route's snapshot. Shared
+     * accessor for deep-links on both search and detail screens (e.g.
+     * `?status=PendingApproval`, `?mode=duplicate`) so screens don't
+     * reach into `route.snapshot.queryParamMap` themselves.
+     */
+    protected queryParam(name: string): string | null;
+    /**
+     * Grant check for ANY screen (not just this one's `SCREEN` code) —
+     * e.g. an operational strip or report widget calling a
+     * differently-gated endpoint. For this screen's own grants prefer
+     * `context.isGranted(...)`.
+     */
+    protected hasGrant(screen: string, permission: Permissions): boolean;
     getBundleName(): string;
     setFormErrors(errors: {
         [key: string]: string[];
@@ -190,15 +261,16 @@ declare abstract class AbstractScreenComponent extends AbstractComponent impleme
     }): void;
     clearServerErrors(): void;
     disableAllControls(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<AbstractScreenComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<AbstractScreenComponent, "ng-component", never, { "context": { "alias": "context"; "required": false; }; }, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractScreenComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractScreenComponent, "ng-component", never, { "context": { "alias": "context"; "required": false; }; }, {}, never, never, true, never>;
 }
 
 declare enum ScreenStateEnum {
     READ_ONLY = "READ_ONLY",
     DETAIL = "DETAIL",
     SEARCH = "SEARCH",
-    CUSTOM = "CUSTOM"
+    CUSTOM = "CUSTOM",
+    REPORT = "REPORT"
 }
 declare enum StateUtilsEnum {
     REMOVE = "removeState",
@@ -235,8 +307,8 @@ declare abstract class AbstractDetailScreenComponent extends AbstractScreenCompo
     print(): void;
     delete(): void;
     navigateBack(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<AbstractDetailScreenComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<AbstractDetailScreenComponent, "ng-component", never, {}, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractDetailScreenComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractDetailScreenComponent, "ng-component", never, {}, {}, never, never, true, never>;
 }
 
 /**
@@ -279,21 +351,763 @@ declare abstract class AbstractSearchScreenComponent extends AbstractScreenCompo
     duplicate(id: any): void;
     clear(): void;
     ngOnDestroy(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<AbstractSearchScreenComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<AbstractSearchScreenComponent, "ng-component", never, {}, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractSearchScreenComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractSearchScreenComponent, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Display shape for an active filter chip in the smart-bar. The
+ * abstract search screen owns a writable signal of `ActiveFilter[]`
+ * that consumers populate when an advanced filter is applied;
+ * `removeFilter(key)` slices the matching entry out.
+ */
+interface ActiveFilter {
+    /** Stable identifier — passed back to `removeFilter`. */
+    key: string;
+    /** i18n key for the chip's label (e.g. `'filter_client'`). */
+    labelKey: string;
+    /** Pre-formatted display value (e.g. `'Leila Bennani'`,
+     *  `'30 derniers jours'`). The chip renders this verbatim. */
+    value: string;
+}
+
+/**
+ * Built-in cell-rendering types. Each type ships a default cell
+ * template in ef-data-card; the `'custom'` type defers to a
+ * `<ng-template efColumnTemplate="…">` projected by the consumer.
+ *
+ * Lives in `@elasticias/screens` so AbstractSearchScreenV2 can return
+ * column descriptors from its `add*Column` builders without a
+ * circular import on `@elasticias/ui`. ef-data-card consumes the same
+ * type via re-export.
+ */
+type EfDataCardColumnType = 'text' | 'number' | 'money' | 'date' | 'datetime' | 'boolean' | 'mono' | 'chip' | 'status' | 'reference' | 'custom';
+type EfDataCardColumnAlign = 'start' | 'center' | 'end';
+type EfDataCardSortDirection = 'asc' | 'desc';
+interface EfDataCardSort {
+    /** Backend field name (matches `column.sortField` or `column.field`). */
+    field: string;
+    direction: EfDataCardSortDirection;
+}
+interface EfDataCardColumn {
+    /**
+     * Stable column identifier. Used as the trackBy key, the
+     * `efColumnTemplate` selector, and the cell's `data-col`
+     * attribute. Must be unique within a table.
+     */
+    id: string;
+    /** Dotted path into the row (defaults to `id`). */
+    field?: string;
+    /** Direct header text — used only when `headerKey` is empty. */
+    header?: string;
+    /** Translation key for the header — preferred. */
+    headerKey?: string;
+    /** Built-in renderer; falls back to `'text'`. */
+    type?: EfDataCardColumnType;
+    /** `'end'` is auto-applied for `'number'` / `'money'`. */
+    align?: EfDataCardColumnAlign;
+    /** Inline CSS width (e.g. `'40px'`, `'15%'`). */
+    width?: string;
+    /** Extra CSS classes to apply on the `<td>` (e.g. `'num'`). */
+    cellClass?: string;
+    /** Sort enabled for this column (default: `false` — opt-in). */
+    sortable?: boolean;
+    /** Backend sort field — defaults to `field` then `id`. */
+    sortField?: string;
+    /** Date / datetime: pipe format string (default: `'shortDate'` / `'short'`). */
+    dateFormat?: string;
+    /** Money: ISO currency code (default: `'EUR'`). */
+    currencyCode?: string;
+    /** Money: how the symbol renders (default: `'symbol'`). */
+    currencyDisplay?: 'symbol' | 'code' | 'name';
+    /** Locale for number / date / currency pipes (default: `'fr-FR'`). */
+    locale?: string;
+    /** Number/money fraction digits. */
+    minFractionDigits?: number;
+    maxFractionDigits?: number;
+    /** Reference data lookup key for `type: 'reference'`. */
+    referenceKey?: string;
+    referenceValueField?: string;
+    referenceLabelField?: string;
+    /** Chip column: prefix prepended to the value to form the class
+     * (e.g. `'chip-'` so value `'pending'` → `'chip chip-pending'`). */
+    chipPrefix?: string;
+}
+/**
+ * Caller-friendly opts for `addReferenceColumn` — exposes
+ * `valueField` / `labelField` shorthands instead of the verbose
+ * `referenceValueField` / `referenceLabelField` properties.
+ */
+interface EfReferenceColumnOpts extends Partial<EfDataCardColumn> {
+    /** Shorthand for `referenceValueField` (defaults to `'id'`). */
+    valueField?: string;
+    /** Shorthand for `referenceLabelField` (defaults to `'label'`). */
+    labelField?: string;
+}
+
+/**
+ * Declarative definition of an advanced-search select filter rendered in
+ * the filter drawer. One `<ef-select>` is rendered per entry; the screen
+ * stays type-agnostic — `key` is simply the criteria property name sent to
+ * the backend (which must expose a matching typed query prop, e.g.
+ * `CityIds: List<int>`, `ClientIds: List<string>`, a scalar code, …). Works
+ * for both single-select (`multiple` omitted/false → scalar value) and
+ * multi-select (`multiple: true` → array value).
+ */
+interface AdvancedSelectFilter {
+    /** Criteria property name sent to the backend (must match a typed query prop). */
+    key: string;
+    /** Reference-data key supplying the options (e.g. `'cities'`). */
+    refKey: string;
+    /** i18n key for the field label (rendered by `ef-select`). */
+    labelKey: string;
+    /** Multi-select when `true` (array value); single-select otherwise (scalar). */
+    multiple?: boolean;
+    /** Option value field (default `'code'`). */
+    valueField?: string;
+    /** Option label field (default `'label'`). */
+    labelField?: string;
+    /** Placeholder i18n key (default `'common_all'`). */
+    placeholderKey?: string;
+}
+/**
+ * Signal-first counterpart to {@link AbstractSearchScreenComponent}.
+ *
+ * Built for V2 + zoneless apps: state is exposed as signals
+ * (`items`, `loading`, `errorMsg`, `totalCount`, `criteria`) and the
+ * class is intentionally **decoupled from PrimeNG `<p-table>`** —
+ * subclasses render however they want (Comptoir `.tbl` patterns,
+ * cards, virtual lists, …) and call the helpers below to mutate the
+ * search criteria + re-execute.
+ *
+ * Same `ScreenConfig` surface as the legacy abstract:
+ * - `SCREEN` (string code matching backend grants)
+ * - `SERVICE` (NSwag client class with `search(criteria)` method)
+ * - `SEARCH_REFERENTIALS_KEYS` / `SEARCH_STATIC_LISTS` for ref-data
+ * - `DEFAULT_SORT` for first load
+ *
+ * Subclasses typically:
+ *
+ * ```ts
+ * @Component({ ... })
+ * export class FooComponent extends AbstractSearchScreenV2<FooDto> {
+ *   protected override getConfig() { return FooConfig; }
+ *   readonly rows = computed(() => this.items().map(toRow));
+ * }
+ * ```
+ */
+declare abstract class AbstractSearchScreenV2<TItem = any> extends AbstractScreenComponent implements OnInit {
+    protected readonly screenState = ScreenStateEnum.SEARCH;
+    protected readonly injector: Injector;
+    private serviceInstance;
+    /** Monotonic guard: bumped on every `search()` call so an
+     *  out-of-order (stale) response from an earlier search can be
+     *  dropped instead of overwriting the latest results. */
+    private searchSeq;
+    /** Current search results — populated after each `search()`. */
+    readonly items: _angular_core.WritableSignal<TItem[]>;
+    readonly totalCount: _angular_core.WritableSignal<number>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly errorMsg: _angular_core.WritableSignal<string | null>;
+    /** Live search criteria (paging, sort, text, dates, custom). */
+    readonly criteria: _angular_core.WritableSignal<SearchEntity>;
+    /**
+     * Active date-range filter shown in `ef-datepicker-advanced`'s
+     * trigger. Display-only at construction time — actually filters
+     * the search once `onDateRangeChange()` fires (or a screen wires
+     * one in `ngOnInit`).
+     *
+     * Override `buildDefaultDateRange()` per screen to ship a
+     * different starting preset.
+     */
+    readonly dateRange: _angular_core.WritableSignal<EfDateRange>;
+    /** Free-text search input value — bound `[(searchText)]` on
+     *  ef-smart-bar; drives `runSearch()`. */
+    readonly searchQuery: _angular_core.WritableSignal<string>;
+    /** Active status pill-group selection (defaults to `'all'`). */
+    readonly statusFilter: _angular_core.WritableSignal<string>;
+    /** Whether the advanced-filter drawer is open. */
+    readonly drawerOpen: _angular_core.WritableSignal<boolean>;
+    /** Active named filter chips shown in the smart-bar. */
+    readonly activeFilters: _angular_core.WritableSignal<ActiveFilter[]>;
+    /** Advanced-filter select definitions. Empty = no advanced filters. */
+    readonly advancedFilters: AdvancedSelectFilter[];
+    /** Criteria key of the screen's activation tri-state filter
+     *  (`ef-activation-filter`), e.g. `'isActive'`. When set, the base
+     *  applies, baseline-clears, and cache-restores the boolean like any
+     *  declared advanced filter — the screen only binds the component to
+     *  `advancedValues()` / `setAdvancedValue()`. `null` = no activation
+     *  filter. */
+    protected readonly activationFilterKey: string | null;
+    /** Live values per advanced filter, keyed by `AdvancedSelectFilter.key`. */
+    readonly advancedValues: _angular_core.WritableSignal<Record<string, unknown>>;
+    /** Store the picked value(s) for one advanced filter (no search yet —
+     *  the drawer's `(apply)` runs it). */
+    setAdvancedValue(key: string, value: unknown): void;
+    /** Push every advanced-filter value into the criteria as typed
+     *  top-level props and re-run the search. Wired to the drawer's
+     *  `(apply)`. Every DECLARED key is written on apply — a cleared
+     *  control must actively remove its (possibly cache-restored)
+     *  criteria value, not silently leave it behind. */
+    applyAdvancedFilters(): void;
+    /** Selected row ids — keyed by `String(rowId(row))`. */
+    readonly selected: _angular_core.WritableSignal<ReadonlySet<string>>;
+    /** Live count derived from `selected`. */
+    readonly selectionCount: _angular_core.Signal<number>;
+    readonly currentSort: _angular_core.Signal<EfDataCardSort | null>;
+    readonly showViewAction: _angular_core.WritableSignal<boolean>;
+    readonly showEditAction: _angular_core.WritableSignal<boolean>;
+    readonly showDuplicateAction: _angular_core.WritableSignal<boolean>;
+    readonly showDeleteAction: _angular_core.WritableSignal<boolean>;
+    /**
+     * PK accessor for a row. Default returns `row?.id` — override when
+     * the backend names its primary key something else (e.g. sales-orders'
+     * `orderId`). Used by the row-actions dispatcher and as the implicit
+     * navigateToDetails / edit / delete argument.
+     */
+    rowId(row: any): any;
+    /**
+     * Dispatch helper wired to ef-data-card's `(rowAction)` output and
+     * the auto-rendered row-actions cell. Routes the standard four
+     * actions to the inherited methods so subclasses don't have to
+     * declare per-screen rowActions arrays.
+     */
+    onRowAction(action: 'view' | 'edit' | 'duplicate' | 'delete', row: any): void;
+    /**
+     * Wired to `<ef-datepicker-advanced (rangeChange)>` — stores the
+     * range for trigger display and pushes it into the search criteria
+     * so the next `search()` filters by it.
+     */
+    onDateRangeChange(range: EfDateRange): void;
+    /**
+     * Reset the date range to the default. Called automatically by
+     * `clear()` so screens don't have to remember to invoke it from
+     * their own `clearAll()` orchestration.
+     */
+    protected resetDateRange(): void;
+    /**
+     * Build the default `EfDateRange`. Override per screen to ship a
+     * different default — e.g., a 90-day window for low-velocity
+     * catalogues. Default: last 30 days.
+     */
+    protected buildDefaultDateRange(): EfDateRange;
+    /** Today at 00:00 local time. */
+    protected startOfToday(): Date;
+    /** N days before today, at 00:00 local time. */
+    protected daysAgo(n: number): Date;
+    /** Wired to filter-drawer's `(apply)` — pushes the current
+     *  searchQuery into the criteria and re-runs the search. */
+    runSearch(): void;
+    /** Pill-group click handler. Stores the selected status code; the
+     *  search itself only re-runs once the consumer pushes the value
+     *  into the criteria (or wires it via beforeSearch). */
+    setStatus(key: string): void;
+    toggleDrawer(): void;
+    /** Drop a chip from the active-filters list. */
+    removeFilter(key: string): void;
+    toggleSelection(id: string): void;
+    /** Toggle every visible row in or out of the selection in one shot. */
+    toggleAllSelection(): void;
+    isSelected(id: string): boolean;
+    /** Selection checkbox column — paired with `efColumnTemplate="select"`
+     *  for the row's checkbox. 40px wide, no other props. */
+    protected addSelectColumn(width?: string): EfDataCardColumn;
+    /** Plain text column. */
+    protected addTextColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Monospace column — JetBrains Mono with tabular-nums; for codes,
+     *  IDs, refs, anything where character alignment matters. */
+    protected addMonoColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Number column — end-aligned, integer by default. Override
+     *  `minFractionDigits` / `maxFractionDigits` via opts for decimals. */
+    protected addNumberColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Money column — end-aligned. ISO currency code defaults to `'MAD'`
+     *  (Elasticias' primary tenant locale); pass `opts.currencyCode` for
+     *  euros / USD / etc. */
+    protected addMoneyColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Date column — formats as `dd/MM/yyyy` by default. */
+    protected addDateColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Datetime column — formats as `dd/MM/yyyy HH:mm` by default. */
+    protected addDatetimeColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Boolean column — renders the `bool yes / bool no` indicator. */
+    protected addBooleanColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Static-class chip column — renders `chip <chipPrefix><value>`.
+     *  Use `addStatusColumn` for reference_data-driven palettes. */
+    protected addChipColumn(field: string, headerKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Status chip column — palette + label resolved from
+     *  `reference_data` via `referenceKey`. Sortable by default. */
+    protected addStatusColumn(field: string, headerKey: string, referenceKey: string, opts?: Partial<EfDataCardColumn>): EfDataCardColumn;
+    /** Reference column — looks up `field`'s value in the reference
+     *  list keyed by `referenceKey`, renders the matching item's label.
+     *  Defaults: `valueField: 'id'`, `labelField: 'label'`. */
+    protected addReferenceColumn(field: string, headerKey: string, referenceKey: string, opts?: EfReferenceColumnOpts): EfDataCardColumn;
+    ngOnInit(): void;
+    /**
+     * Deep-link support: `/<list>?status=<code>` pre-selects the status
+     * pill after the initial criteria bootstrap (so the reset doesn't
+     * clobber it). Runs through `setStatus()`, so a subclass override
+     * that pushes the status into the criteria (the usual pattern) gets
+     * the deep-linked value too. No-op without the query param.
+     */
+    private applyDeepLinkStatus;
+    /** Restore criteria from cache (returning to a screen) or seed defaults. */
+    private bootstrapInitialSearch;
+    /**
+     * Cache-restore sync: when a revisit restores cached criteria,
+     * reflect the restored filters back into the filter-bar UI state so
+     * what the drawer / search box displays matches what the search will
+     * actually send (otherwise a stale criteria filter keeps applying
+     * while every control reads "Tous"). Base handles the free-text
+     * input and the declared advanced filters; override (calling super)
+     * to sync screen-specific state — status pill, custom switches, ….
+     */
+    protected restoreFilterUiFromCriteria(cached: Record<string, any>): void;
+    /**
+     * Run a search with the current `criteria()`. Always populates
+     * `items` / `totalCount` / `loading` / `errorMsg` and persists the
+     * criteria to cache on success so revisits can restore.
+     */
+    search(): void;
+    setSearchText(text: string): void;
+    setPage(pageNumber: number, pageSize?: number): void;
+    setSort(field: string, direction?: string): void;
+    setDateRange(start: Date | null, end: Date | null): void;
+    /** Patch arbitrary extra fields onto the criteria (for module-specific filters). */
+    patchCriteria(patch: Record<string, any>): void;
+    /** Reset everything to defaults and re-fetch. Subclasses bind this
+     *  to ef-smart-bar's `(clear)` output directly — no per-screen
+     *  `clearAll()` orchestration needed. */
+    clear(): void;
+    private cloneCriteria;
+    /** Resolve the list-screen URL at call time. Drops query / fragment
+     *  and strips a trailing slash. */
+    protected resolveListUrl(): string;
+    navigateToDetails(id?: any): void;
+    /** Open the create form. */
+    add(): void;
+    edit(id: any): void;
+    delete(id: any): void;
+    duplicate(id: any): void;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractSearchScreenV2<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractSearchScreenV2<any>, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Declarative custom action consumed by `ef-detail-toolbar`'s
+ * `[customActions]` input AND produced by
+ * `AbstractDetailScreenV2.getCustomActions()`.
+ *
+ * Lives in `@elasticias/screens` so the abstract can return arrays
+ * of these without a circular dep on `@elasticias/ui`. ef-detail-
+ * toolbar consumes the same type via re-export from
+ * `@elasticias/ui/.../ef-detail-toolbar.types`.
+ *
+ * Custom actions render in the toolbar's right group, before the
+ * standard `print | duplicate | delete | save` row, separated by
+ * a `|` divider when both groups are present.
+ */
+interface EfDetailToolbarAction {
+    /** Stable identifier for trackBy / tests. */
+    id?: string;
+    /** Translation key — preferred. */
+    labelKey?: string;
+    /** Direct label fallback when `labelKey` is empty. */
+    label?: string;
+    /** PrimeIcons class (e.g. `'pi pi-eye'`). */
+    icon?: string;
+    /**
+     * Visual tone:
+     * - `'ghost'`   (default) — outlined paper-alt button
+     * - `'primary'`           — ink-active fill
+     * - `'tenant'`            — tenant accent fill (use for the
+     *                           screen's principal action)
+     * - `'danger'`            — ghost styling tinted with
+     *                           `--st-cancelled-fg`
+     */
+    severity?: 'ghost' | 'primary' | 'tenant' | 'danger';
+    /**
+     * Hide the action regardless of the permission check. Useful for
+     * conditional visibility tied to entity state (e.g. only show
+     * "Approve" when `entity.status === 'pending'`). Default `true`.
+     */
+    visible?: boolean;
+    /** Disable without removing. */
+    disabled?: boolean;
+    /**
+     * If set, the action is hidden unless the bound `ScreenContext`
+     * grants this permission. Actions with no `permission` always
+     * show (subject to `visible`).
+     */
+    permission?: Permissions;
+    /** Click handler. */
+    command?: () => void;
+}
+
+/**
+ * Signal-first counterpart to {@link AbstractDetailScreenComponent}.
+ *
+ * Same business mechanism as v1 but signal-based and zoneless-friendly:
+ * `entity` / `entityId` / `editionState` / `duplicateMode` / `loading`
+ * / `errorMsg` are all writable signals.
+ *
+ * Routing convention (V2):
+ * - `/<resource>/details`         → new (create mode, `editionState=false`)
+ * - `/<resource>/details/:id`     → edit mode (loads via `service.get(id)`)
+ * - `/<resource>/details/:id?mode=duplicate` → loads then strips id on save
+ *
+ * The same component handles all three paths — the route param +
+ * `mode` query string drives the state. After a successful create
+ * (or duplicate-save), the screen navigates to
+ * `/<resource>/details/<new-id>` so the user lands in edit mode.
+ *
+ * Subclasses typically override:
+ * - `getConfig()`               — returns ScreenConfig with SERVICE
+ * - `beforeSave(): boolean`     — return false to cancel save
+ *                                 (default: true)
+ * - `afterLoad()`               — post-process loaded entity
+ * - `afterSave(result)`         — default invalidates refs + navigates
+ *                                 to the new edit URL after create
+ * - `onSaveError(errors)`       — surface form-level validation errors
+ * - `customizeDuplicatedEntity` — clean fields before duplicating
+ *
+ * ```ts
+ * @Component({ ... })
+ * export class FooDetailComponent extends AbstractDetailScreenV2<FooDto> {
+ *   override getConfig() { return FooConfig; }
+ *
+ *   protected override beforeSave(): boolean {
+ *     // validate this.entity() shape; return false to cancel
+ *     return true;
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AbstractDetailScreenV2<TItem extends object = any> extends AbstractScreenComponent implements OnInit {
+    protected readonly screenState = ScreenStateEnum.DETAIL;
+    protected readonly injector: Injector;
+    protected readonly location: Location;
+    private readonly destroyRef;
+    private readonly auditHistoryService;
+    protected serviceInstance: any;
+    /**
+     * Change-history entries for the loaded record, newest first. Populated
+     * automatically when the config sets `AUDIT_ENTITY_TYPE` and an
+     * `AUDIT_HISTORY_SERVICE` is provided. Bind it directly:
+     * `<ef-change-history [entries]="auditEntries()" />`.
+     */
+    readonly auditEntries: _angular_core.WritableSignal<any[]>;
+    /** Loaded entity. Empty object when on `/details` (create mode). */
+    readonly entity: _angular_core.WritableSignal<TItem>;
+    /** PK from the route param, or `null` on `/details` (new). */
+    readonly entityId: _angular_core.WritableSignal<any>;
+    /** Edit-mode flag — true when an id is present and we're not duplicating. */
+    readonly editionState: _angular_core.WritableSignal<boolean>;
+    /**
+     * When true, the loaded entity is treated as a template — saving
+     * runs `service.create()` instead of `service.update()`. Set by
+     * the `?mode=duplicate` query param.
+     */
+    readonly duplicateMode: _angular_core.WritableSignal<boolean>;
+    /** True while service.get / create / update / delete is in flight. */
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    /** Last load / save error message — empty string when none. */
+    readonly errorMsg: _angular_core.WritableSignal<string | null>;
+    /**
+     * Reactive list of custom actions for `<ef-detail-toolbar>`'s
+     * `[customActions]` input — recomputes whenever editionState /
+     * duplicateMode flip. Default contents:
+     * - Edit mode      → empty (the standard `print | duplicate |
+     *                    delete | save` row covers it)
+     * - Create mode    → `[Cancel]` — navigates back to the list
+     * - Duplicate mode → `[Cancel]` — drops `?mode=duplicate` and
+     *                    returns to edit view of the source entity
+     *
+     * Subclasses override `getCustomActions()` to add screen-specific
+     * actions (Approve / Print PDF / Mark as paid / etc.). Call
+     * `super.getCustomActions()` to keep the Cancel default.
+     */
+    readonly customActions: _angular_core.Signal<readonly EfDetailToolbarAction[]>;
+    /**
+     * Builder for `customActions`. Override per screen to add or
+     * replace the defaults. Pure function — reads other signals
+     * freely, returns a fresh array each call.
+     */
+    protected getCustomActions(): EfDetailToolbarAction[];
+    ngOnInit(): void;
+    /**
+     * Merge a partial patch into the `entity` signal — the canonical
+     * way for form inputs to write back. Spread-immutably so OnPush
+     * change detection picks it up.
+     *
+     * ```html
+     * <ef-input-text
+     *   variant="comptoir"
+     *   [value]="title()"
+     *   (valueChangeEvent)="patchEntity({ title: $event })"
+     * />
+     * ```
+     */
+    patchEntity(patch: Partial<TItem>): void;
+    /** Fetch the entity from the backend and populate `entity`. */
+    loadData(): void;
+    /**
+     * Persist the entity. Routes to `service.create()` when in new
+     * or duplicate mode, `service.update(id, entity)` when editing.
+     * Subclass `beforeSave()` can return `false` to cancel.
+     */
+    save(): void;
+    /**
+     * Soft-delete-then-navigate-back. Confirms with the user first.
+     */
+    delete(): void;
+    /** Navigate to `/details/:id?mode=duplicate` so the abstract can
+     *  reload the source entity, treat it as a template, and persist
+     *  via `service.create()` after the user hits Save.
+     *  Without the id, the duplicate route would have nothing to
+     *  fetch — `entity` would be empty and the clone-as-template
+     *  flow would fall back to creating a blank record. */
+    duplicate(): void;
+    /**
+     * Cancel handler for the default toolbar action:
+     * - Duplicate mode → drop `?mode=duplicate` and return to
+     *   `/details/:id`. The route subscription re-fires and reloads
+     *   the source entity, discarding any in-memory edits.
+     * - Create mode (no id) → navigate back to the list.
+     *
+     * Subclasses may override to add a confirm dialog when the form
+     * is dirty.
+     */
+    cancel(): void;
+    /** Navigate back to the list (strip `/details` and any id). */
+    navigateBack(): void;
+    /** Subclass print hook — no-op default. */
+    print(): void;
+    /**
+     * Load the standardized change-history into `auditEntries` when the config
+     * opts in via `AUDIT_ENTITY_TYPE` and an `AUDIT_HISTORY_SERVICE` is provided.
+     * Called automatically after a successful `loadData()`. Failures degrade to
+     * an empty history rather than blocking the screen.
+     */
+    protected loadAuditHistory(): void;
+    /**
+     * Called right before `save()` dispatches to the backend. Return
+     * `false` to cancel (e.g., form validation failed). Default: no-op.
+     */
+    protected beforeSave(): boolean | void;
+    /** Override to post-process the loaded `entity` (or to refresh
+     *  derived signals). Default: no-op. */
+    protected afterLoad(): void;
+    /**
+     * Default post-save behaviour:
+     * - invalidate / refresh reference data per ScreenConfig
+     * - after a CREATE (or duplicate-save), navigate to
+     *   `/details/<new-id>` so the user lands in edit mode
+     */
+    protected afterSave(result: any): void;
+    /** Override to surface form-level validation errors after a 4xx
+     *  response. Default: no-op (errors are already on `serverErrors`). */
+    protected onSaveError(_errors: {
+        [key: string]: string[];
+    }): void;
+    /** Strip id (if present) from the entity before a duplicate save. */
+    protected prepareEntityForDuplication(): any;
+    /** Override to clear additional fields (codes, slugs, refs)
+     *  before saving a duplicated entity. */
+    protected customizeDuplicatedEntity(entity: any): any;
+    /** Resolve the bare `/<resource>/details` base URL — strips a
+     *  trailing `:id`, query string, fragment, trailing slash. */
+    protected detailsBaseUrl(): string;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractDetailScreenV2<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractDetailScreenV2<any>, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
+type ReportWidgetStatus = 'loading' | 'ready' | 'error';
+/**
+ * Handle returned by {@link AbstractReportScreenV2.widget}. Each widget owns
+ * an independent loading/error lifecycle — one failing report block never
+ * blanks its siblings.
+ */
+interface ReportWidget<T> {
+    /** Last successful payload — null until the first `ready`. */
+    readonly data: Signal<T | null>;
+    readonly status: Signal<ReportWidgetStatus>;
+    /** Re-run this widget's loader against the current period. */
+    reload(): void;
+}
+/**
+ * Signal-first base for report/dashboard screens — the third V2 abstract,
+ * alongside {@link AbstractSearchScreenV2} / AbstractDetailScreenV2.
+ *
+ * Owns the report CHASSIS only: period state (`dateRange`, seeded from the
+ * config's `DEFAULT_PERIOD` preset), per-widget lifecycle (`widget()` +
+ * `loadAll()`), `REPORT_STATIC_LISTS` preload, and Export-gated CSV
+ * (Task 2). Widget COMPOSITION stays in each screen's template — a
+ * metadata-driven report renderer was rejected in ADR-015 and this class
+ * must not become its frontend half.
+ *
+ * `ScreenConfig` surface: `SCREEN` (backend screen code), `SERVICE` (NSwag
+ * reports client), `DEFAULT_PERIOD`, `REPORT_STATIC_LISTS`.
+ *
+ * Subclasses typically:
+ *
+ * ```ts
+ * export class FooDashboardComponent extends AbstractReportScreenV2 {
+ *   protected override getConfig() { return FooDashboardConfig; }
+ *   readonly kpisW = this.widget((start, end) =>
+ *     this.client.kpis(new GetFooKpisQuery({ start, end })));
+ * }
+ * ```
+ *
+ * Loaders close over the screen's own filter signals; the screen calls
+ * `loadAll()` (period-wide) or `someW.reload()` (single widget) when its
+ * filters change. Period-independent blocks (operational strips) load
+ * outside the registry on purpose.
+ */
+declare abstract class AbstractReportScreenV2 extends AbstractScreenComponent implements OnInit {
+    protected readonly screenState = ScreenStateEnum.REPORT;
+    protected readonly injector: Injector;
+    /** NSwag reports client resolved from `ScreenConfig.SERVICE` — expose a
+     *  typed getter in the screen: `get client() { return this.reportsService as XClient; }` */
+    protected reportsService: any;
+    private readonly registeredWidgets;
+    /** Active period. Bound to `ef-datepicker-advanced`; every widget loader
+     *  receives its UTC-normalized start/end. */
+    readonly dateRange: _angular_core.WritableSignal<EfDateRange>;
+    ngOnInit(): void;
+    /** Wired to `<ef-datepicker-advanced (rangeChange)>`. */
+    onDateRangeChange(range: EfDateRange): void;
+    /** Default period from the config's `DEFAULT_PERIOD` preset. */
+    protected buildDefaultDateRange(): EfDateRange;
+    /**
+     * Resolve a built-in {@link EfDatePresetKey} to an inclusive day range
+     * (both boundaries at 00:00 local). Unknown keys normalize to
+     * `last_30_days`. Weeks start Monday (matches `$dateTrunc`, ADR-015).
+     */
+    protected rangeFromPreset(key: EfDatePresetKey): EfDateRange;
+    private startOfToday;
+    /**
+     * Re-anchor a local-midnight Date to UTC midnight of the same calendar
+     * date. NSwag serializes via toISOString(); for UTC+ users (Morocco)
+     * local midnight would otherwise shift into the previous UTC day.
+     */
+    protected toUtcDate(d: Date): Date;
+    /**
+     * Register a report widget. The loader receives the current period's
+     * UTC-normalized start/end and returns the NSwag observable; extra
+     * filters are simply closed over from the screen's own signals.
+     */
+    protected widget<T>(loader: (start: Date, end: Date) => Observable<T>): ReportWidget<T>;
+    /** Reload every registered widget against the current period. */
+    loadAll(): void;
+    /** Export grant (ADR-011) on this screen's own code. Grants are loaded
+     *  once by `processGrants()` in ngOnInit — safe to call from templates. */
+    canExport(): boolean;
+    /** CSV download gated by the Export grant — silently no-ops without it. */
+    protected exportCsv(filename: string, rows: object[], columns: {
+        key: string;
+        header: string;
+    }[]): void;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractReportScreenV2, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractReportScreenV2, "ng-component", never, {}, {}, never, never, true, never>;
 }
 
 declare abstract class AbstractSubScreenComponent extends AbstractScreenComponent {
     protected readonly screenState: null;
     ngOnInit(): void;
     ngAfterViewInit(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<AbstractSubScreenComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<AbstractSubScreenComponent, "ng-component", never, {}, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractSubScreenComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractSubScreenComponent, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Signal-first base for SUB-screens — self-contained fragments embedded
+ * inside a host screen (dashboard strips, side panels, …) rather than
+ * routed on their own. The V2 counterpart to the legacy
+ * {@link AbstractSubScreenComponent}.
+ *
+ * A sub-screen typically borrows ANOTHER screen's identity: its config
+ * sets `SCREEN` to the code whose grants gate the data it shows (e.g. a
+ * recent-orders strip on the sales dashboard uses `'SalesOrders'`), so
+ * `canRead()` and `ScreenContext` permissions line up with the backend
+ * seed without any cross-screen plumbing in the component.
+ *
+ * `ScreenConfig` surface (same fields as list screens, reused here):
+ * - `SCREEN` — screen code whose grants apply to this fragment
+ * - `SERVICE` — NSwag client resolved into `serviceInstance`
+ * - `SEARCH_REFERENTIALS_KEYS` / `SEARCH_STATIC_LISTS` — ref-data the
+ *   fragment's columns/labels need; loaded on init, `refDataLoaded$`
+ *   fires when ready (reference columns resolve reactively, so data
+ *   fetches don't have to wait for it)
+ *
+ * No criteria caching, no routing, no toolbar — a sub-screen renders one
+ * `ef-card` (or similar) and owns only its data + collapse state.
+ */
+declare abstract class AbstractSubScreenV2 extends AbstractScreenComponent implements OnInit {
+    protected readonly screenState: null;
+    protected readonly injector: Injector;
+    /** NSwag client resolved from `ScreenConfig.SERVICE` (null-safe: a
+     *  sub-screen fed entirely by inputs may omit SERVICE). */
+    protected serviceInstance: any;
+    /**
+     * Collapse state, bound `[(collapsed)]` on the sub-screen's `ef-card`.
+     * Starts collapsed: sub-screens are secondary content on their host
+     * screen, so they open on demand. Subclasses that must start open set
+     * `this.collapsed.set(false)` in their constructor.
+     */
+    readonly collapsed: _angular_core.WritableSignal<boolean>;
+    toggleCollapsed(): void;
+    /** Read grant on the config's `SCREEN` — gate the whole fragment on
+     *  this so an unauthorized user gets nothing (not an erroring card). */
+    canRead(): boolean;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractSubScreenV2, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AbstractSubScreenV2, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Abstract contract for the change-history (audit trail) backend client used by
+ * {@link AbstractDetailScreenV2}. Apps provide their NSwag-generated `AuditClient`
+ * via the {@link AUDIT_HISTORY_SERVICE} token — kept abstract so `@elasticias/screens`
+ * stays decoupled from any app's generated API client.
+ */
+interface AuditHistoryService {
+    /**
+     * Fetch the change-history for a single record, newest first.
+     * @param entityType Stable backend entity type discriminator (e.g. `'Client'`).
+     * @param id Record identifier.
+     */
+    get(entityType: string, id: string): Observable<any[]>;
 }
+/**
+ * Injection token for the change-history client. Provide it once at app root:
+ *
+ * @example
+ * { provide: AUDIT_HISTORY_SERVICE, useExisting: AuditClient }
+ *
+ * Detail screens then only declare `static AUDIT_ENTITY_TYPE = 'Client'` on
+ * their config — {@link AbstractDetailScreenV2} loads the history automatically
+ * into its `auditEntries` signal.
+ */
+declare const AUDIT_HISTORY_SERVICE: InjectionToken<AuditHistoryService>;
 
 declare class ViewModelEntity extends AbstractEntity {
     constructor(entity: Record<string, unknown>);
 }
 
-export { AbstractComponent, AbstractDetailScreenComponent, AbstractEntity, AbstractScreenComponent, AbstractSearchScreenComponent, AbstractSubScreenComponent, PaginationEnum, SCREEN_REF_DATA_SERVICE, ScreenConfig, ScreenContext, ScreenStateEnum, SearchEntity, SortDirectionEnum, StateUtilsEnum, ViewModelEntity };
-export type { DefaultSort, LoadOptions, ReferenceDataProvider, ScreenDatatableColumn, ScreenReferenceDataService };
+/**
+ * Declarative custom action consumed by `ef-search-toolbar`'s
+ * `[customActions]` input AND produced by
+ * `AbstractSearchScreenV2.getCustomActions()` (when wired).
+ *
+ * Shape-identical to {@link EfDetailToolbarAction} — kept as a
+ * distinct alias so the search-toolbar can diverge later (e.g.
+ * bulk-only actions, selection-aware visibility) without churning
+ * every detail-screen call site.
+ */
+type EfSearchToolbarAction = EfDetailToolbarAction;
+
+export { AUDIT_HISTORY_SERVICE, AbstractComponent, AbstractDetailScreenComponent, AbstractDetailScreenV2, AbstractEntity, AbstractReportScreenV2, AbstractScreenComponent, AbstractSearchScreenComponent, AbstractSearchScreenV2, AbstractSubScreenComponent, AbstractSubScreenV2, PaginationEnum, SCREEN_REF_DATA_SERVICE, ScreenConfig, ScreenContext, ScreenStateEnum, SearchEntity, SortDirectionEnum, StateUtilsEnum, ViewModelEntity };
+export type { ActiveFilter, AdvancedSelectFilter, AuditHistoryService, DefaultSort, EfDataCardColumn, EfDataCardColumnAlign, EfDataCardColumnType, EfDataCardSort, EfDataCardSortDirection, EfDatePresetKey, EfDateRange, EfDetailToolbarAction, EfReferenceColumnOpts, EfSearchToolbarAction, LoadOptions, ReferenceDataProvider, ReportWidget, ReportWidgetStatus, ScreenDatatableColumn, ScreenReferenceDataService };