@elasticias/screens 0.0.16 → 1.0.0

package/fesm2022/elasticias-screens.mjs

@@ -1,11 +1,12 @@
 import * as i0 from '@angular/core';
-import { Input, Component, signal, InjectionToken, inject, ChangeDetectorRef, ViewChild, Injector } from '@angular/core';
+import { Input, Component, signal, InjectionToken, inject, ChangeDetectorRef, ViewChild, Injector, computed, DestroyRef } from '@angular/core';
 import { Subject, combineLatest, take } from 'rxjs';
-import { PermissionsEnum } from '@elasticias/types';
+import { Permissions } from '@elasticias/types';
 import { Router, ActivatedRoute } from '@angular/router';
-import { StorageUtils, AppUtils } from '@elasticias/utils';
+import { StorageUtils, AppUtils, CsvUtils } from '@elasticias/utils';
 import { CacheService, ToastService, ConfirmDialogService } from '@elasticias/core';
 import { Location } from '@angular/common';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 
 class AbstractEntity {
     clone(entity) {
@@ -105,11 +106,40 @@ class ScreenContext extends AbstractEntity {
     isGranted(permission) {
         return this.grants?.some((value) => value === permission) ?? false;
     }
+    /* ── Permission convenience getters ───────────────────────────────
+       Shared components (ef-row-actions, ef-data-card auto actions cell,
+       toolbars) read these to default-show / default-hide CRUD buttons
+       against the current user's grants without re-importing
+       Permissions at every call site. */
+    get hasReadPermission() {
+        return this.isGranted(Permissions.Read);
+    }
+    get hasCreatePermission() {
+        return this.isGranted(Permissions.Create);
+    }
+    get hasEditPermission() {
+        return this.isGranted(Permissions.Edit);
+    }
+    get hasDeletePermission() {
+        return this.isGranted(Permissions.Delete);
+    }
+    get hasDuplicatePermission() {
+        return this.isGranted(Permissions.Duplicate);
+    }
+    get hasPrintPermission() {
+        return this.isGranted(Permissions.Print);
+    }
+    get hasExportPermission() {
+        return this.isGranted(Permissions.Export);
+    }
+    get hasImportPermission() {
+        return this.isGranted(Permissions.Import);
+    }
     isReadOnly() {
-        return (this.isGranted(PermissionsEnum.Read) &&
-            !this.isGranted(PermissionsEnum.Write) &&
-            !this.isGranted(PermissionsEnum.Edit) &&
-            !this.isGranted(PermissionsEnum.Delete));
+        return (this.isGranted(Permissions.Read) &&
+            !this.isGranted(Permissions.Create) &&
+            !this.isGranted(Permissions.Edit) &&
+            !this.isGranted(Permissions.Delete));
     }
 }
 
@@ -175,6 +205,25 @@ class AbstractScreenComponent extends AbstractComponent {
     getConfig() {
         return null;
     }
+    /**
+     * 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.
+     */
+    queryParam(name) {
+        return this.route.snapshot.queryParamMap.get(name);
+    }
+    /**
+     * 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(...)`.
+     */
+    hasGrant(screen, permission) {
+        const grants = StorageUtils.getLocal('CURRENT_USER_GRANTS');
+        return !!grants?.[screen]?.permissions?.includes(permission);
+    }
     getBundleName() {
         const config = this.getConfig();
         if (config) {
@@ -288,7 +337,17 @@ class AbstractScreenComponent extends AbstractComponent {
         }
     }
     setServerErrors(errors) {
-        this.serverErrors.set(errors || {});
+        // Backend (FluentValidation) keys are PascalCase (e.g. `ClientType`);
+        // template field bindings and the camelCased `setFormErrors` path use
+        // camelCase. Normalize here so screens can read `serverErrors()['clientType']`
+        // and pass it straight to an `ef-*` control's `[errors]` input.
+        const normalized = {};
+        if (errors) {
+            Object.keys(errors).forEach((key) => {
+                normalized[AppUtils.toCamelCase(key)] = errors[key];
+            });
+        }
+        this.serverErrors.set(normalized);
     }
     clearServerErrors() {
         this.serverErrors.set({});
@@ -327,6 +386,7 @@ var ScreenStateEnum;
     ScreenStateEnum["DETAIL"] = "DETAIL";
     ScreenStateEnum["SEARCH"] = "SEARCH";
     ScreenStateEnum["CUSTOM"] = "CUSTOM";
+    ScreenStateEnum["REPORT"] = "REPORT";
 })(ScreenStateEnum || (ScreenStateEnum = {}));
 var StateUtilsEnum;
 (function (StateUtilsEnum) {
@@ -803,6 +863,1209 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImpo
                 args: ['pTable']
             }] } });
 
+/**
+ * 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));
+ * }
+ * ```
+ */
+class AbstractSearchScreenV2 extends AbstractScreenComponent {
+    screenState = ScreenStateEnum.SEARCH;
+    injector = inject(Injector);
+    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. */
+    searchSeq = 0;
+    /** Current search results — populated after each `search()`. */
+    items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : /* istanbul ignore next */ []));
+    totalCount = signal(0, ...(ngDevMode ? [{ debugName: "totalCount" }] : /* istanbul ignore next */ []));
+    loading = signal(false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
+    errorMsg = signal(null, ...(ngDevMode ? [{ debugName: "errorMsg" }] : /* istanbul ignore next */ []));
+    /** Live search criteria (paging, sort, text, dates, custom). */
+    criteria = signal(new SearchEntity({}), ...(ngDevMode ? [{ debugName: "criteria" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    dateRange = signal(this.buildDefaultDateRange(), ...(ngDevMode ? [{ debugName: "dateRange" }] : /* istanbul ignore next */ []));
+    /* ── Filter-bar UI state (DRY) ──────────────────────────────────
+         Identical across every list screen — lifted up so subclasses
+         don't re-declare. `clear()` resets all four signals. */
+    /** Free-text search input value — bound `[(searchText)]` on
+     *  ef-smart-bar; drives `runSearch()`. */
+    searchQuery = signal('', ...(ngDevMode ? [{ debugName: "searchQuery" }] : /* istanbul ignore next */ []));
+    /** Active status pill-group selection (defaults to `'all'`). */
+    statusFilter = signal('all', ...(ngDevMode ? [{ debugName: "statusFilter" }] : /* istanbul ignore next */ []));
+    /** Whether the advanced-filter drawer is open. */
+    drawerOpen = signal(false, ...(ngDevMode ? [{ debugName: "drawerOpen" }] : /* istanbul ignore next */ []));
+    /** Active named filter chips shown in the smart-bar. */
+    activeFilters = signal([], ...(ngDevMode ? [{ debugName: "activeFilters" }] : /* istanbul ignore next */ []));
+    /* ── Advanced-filter selects (DRY) ──────────────────────────────
+         Declarative `<ef-select>` filters rendered in the filter drawer.
+         Override `advancedFilters` per screen; the base owns the value
+         state, the apply→criteria push, and the reset. Type-agnostic:
+         each `key` maps to a typed backend query prop of any shape. */
+    /** Advanced-filter select definitions. Empty = no advanced filters. */
+    advancedFilters = [];
+    /** 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. */
+    activationFilterKey = null;
+    /** Live values per advanced filter, keyed by `AdvancedSelectFilter.key`. */
+    advancedValues = signal({}, ...(ngDevMode ? [{ debugName: "advancedValues" }] : /* istanbul ignore next */ []));
+    /** Store the picked value(s) for one advanced filter (no search yet —
+     *  the drawer's `(apply)` runs it). */
+    setAdvancedValue(key, value) {
+        this.advancedValues.update((v) => ({ ...v, [key]: value }));
+    }
+    /** 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() {
+        const patch = {};
+        for (const f of this.advancedFilters)
+            patch[f.key] = undefined;
+        if (this.activationFilterKey)
+            patch[this.activationFilterKey] = undefined;
+        Object.assign(patch, this.advancedValues());
+        this.patchCriteria(patch);
+    }
+    /* ── Selection (DRY) ────────────────────────────────────────────
+         Per-row checkbox state, used by `ef-bulk-bar` and the auto
+         row-actions cell. */
+    /** Selected row ids — keyed by `String(rowId(row))`. */
+    selected = signal(new Set(), ...(ngDevMode ? [{ debugName: "selected" }] : /* istanbul ignore next */ []));
+    /** Live count derived from `selected`. */
+    selectionCount = computed(() => this.selected().size, ...(ngDevMode ? [{ debugName: "selectionCount" }] : /* istanbul ignore next */ []));
+    /* ── Sort indicator (DRY) ───────────────────────────────────────
+         ef-data-card consumes `[sort]` as `{ field, direction: 'asc' |
+         'desc' }`. The base criteria stores the legacy
+         'Ascending' / 'Descending' strings — convert lazily here. */
+    currentSort = computed(() => {
+        const s = this.criteria().sort?.[0];
+        if (!s?.field)
+            return null;
+        return {
+            field: s.field,
+            direction: (s.sortDirection ?? '').toLowerCase().startsWith('asc')
+                ? 'asc'
+                : 'desc',
+        };
+    }, ...(ngDevMode ? [{ debugName: "currentSort" }] : /* istanbul ignore next */ []));
+    /* ── Row-actions standard surface ───────────────────────────────
+         Subclasses can flip these off when a particular CRUD action
+         isn't applicable. Defaults are all-on; permission filtering
+         still happens at render time via ScreenContext, so an action
+         that the user can't perform is hidden regardless of these
+         flags. */
+    showViewAction = signal(true, ...(ngDevMode ? [{ debugName: "showViewAction" }] : /* istanbul ignore next */ []));
+    showEditAction = signal(true, ...(ngDevMode ? [{ debugName: "showEditAction" }] : /* istanbul ignore next */ []));
+    showDuplicateAction = signal(true, ...(ngDevMode ? [{ debugName: "showDuplicateAction" }] : /* istanbul ignore next */ []));
+    showDeleteAction = signal(true, ...(ngDevMode ? [{ debugName: "showDeleteAction" }] : /* istanbul ignore next */ []));
+    /**
+     * 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) {
+        return row?.id;
+    }
+    /**
+     * 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, row) {
+        const id = this.rowId(row);
+        switch (action) {
+            case 'view':
+                this.navigateToDetails(id);
+                break;
+            case 'edit':
+                this.edit(id);
+                break;
+            case 'duplicate':
+                this.duplicate(id);
+                break;
+            case 'delete':
+                this.delete(id);
+                break;
+        }
+    }
+    /* ── Date-range filter (DRY) ────────────────────────────────────
+         Wired to ef-datepicker-advanced. The default range is
+         `last_30_days` — override `buildDefaultDateRange()` per screen
+         if a different starting preset is needed. */
+    /**
+     * 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) {
+        this.dateRange.set(range);
+        this.setDateRange(range.start, range.end);
+    }
+    /**
+     * 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.
+     */
+    resetDateRange() {
+        this.dateRange.set(this.buildDefaultDateRange());
+    }
+    /**
+     * 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.
+     */
+    buildDefaultDateRange() {
+        return {
+            start: this.daysAgo(29),
+            end: this.startOfToday(),
+            presetKey: 'last_30_days',
+            labelKey: 'date_preset_last_30_days',
+            label: '30 derniers jours',
+        };
+    }
+    /** Today at 00:00 local time. */
+    startOfToday() {
+        const d = new Date();
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+    }
+    /** N days before today, at 00:00 local time. */
+    daysAgo(n) {
+        const t = this.startOfToday();
+        t.setDate(t.getDate() - n);
+        return t;
+    }
+    /* ── Filter-bar handlers (DRY) ──────────────────────────────────
+         Wired to ef-smart-bar / pill-group / filter-drawer / chip
+         removal. None of these need overriding — subclasses use them
+         through inherited template bindings. */
+    /** Wired to filter-drawer's `(apply)` — pushes the current
+     *  searchQuery into the criteria and re-runs the search. */
+    runSearch() {
+        this.setSearchText(this.searchQuery());
+    }
+    /** 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) {
+        this.statusFilter.set(key);
+    }
+    toggleDrawer() {
+        this.drawerOpen.update((o) => !o);
+    }
+    /** Drop a chip from the active-filters list. */
+    removeFilter(key) {
+        this.activeFilters.update((filters) => filters.filter((f) => f.key !== key));
+    }
+    /* ── Selection helpers (DRY) ────────────────────────────────────
+         Mutate `selected` (Set<string>); template binds via
+         `[checked]="isSelected(rowId(row))"` and
+         `(change)="toggleSelection(rowId(row))"`. */
+    toggleSelection(id) {
+        this.selected.update((set) => {
+            const next = new Set(set);
+            if (next.has(id))
+                next.delete(id);
+            else
+                next.add(id);
+            return next;
+        });
+    }
+    /** Toggle every visible row in or out of the selection in one shot. */
+    toggleAllSelection() {
+        const all = this.items().map((item) => String(this.rowId(item)));
+        this.selected.update((set) => set.size === all.length ? new Set() : new Set(all));
+    }
+    isSelected(id) {
+        return this.selected().has(id);
+    }
+    /* ── Column builders (DRY) ──────────────────────────────────────
+         Convenience helpers that return a fully-formed EfDataCardColumn
+         with sensible per-type defaults. Pass `opts` to override any
+         property — `opts` always wins over the builder's defaults. */
+    /** Selection checkbox column — paired with `efColumnTemplate="select"`
+     *  for the row's checkbox. 40px wide, no other props. */
+    addSelectColumn(width = '40px') {
+        return { id: 'select', width };
+    }
+    /** Plain text column. */
+    addTextColumn(field, headerKey, opts = {}) {
+        return { id: field, ...opts, field, headerKey, type: 'text' };
+    }
+    /** Monospace column — JetBrains Mono with tabular-nums; for codes,
+     *  IDs, refs, anything where character alignment matters. */
+    addMonoColumn(field, headerKey, opts = {}) {
+        return { id: field, ...opts, field, headerKey, type: 'mono' };
+    }
+    /** Number column — end-aligned, integer by default. Override
+     *  `minFractionDigits` / `maxFractionDigits` via opts for decimals. */
+    addNumberColumn(field, headerKey, opts = {}) {
+        return {
+            id: field,
+            minFractionDigits: 0,
+            maxFractionDigits: 0,
+            ...opts,
+            field,
+            headerKey,
+            type: 'number',
+            align: opts.align ?? 'end',
+        };
+    }
+    /** Money column — end-aligned. ISO currency code defaults to `'MAD'`
+     *  (Elasticias' primary tenant locale); pass `opts.currencyCode` for
+     *  euros / USD / etc. */
+    addMoneyColumn(field, headerKey, opts = {}) {
+        return {
+            id: field,
+            currencyCode: 'MAD',
+            ...opts,
+            field,
+            headerKey,
+            type: 'money',
+            align: opts.align ?? 'end',
+        };
+    }
+    /** Date column — formats as `dd/MM/yyyy` by default. */
+    addDateColumn(field, headerKey, opts = {}) {
+        return { id: field, ...opts, field, headerKey, type: 'date' };
+    }
+    /** Datetime column — formats as `dd/MM/yyyy HH:mm` by default. */
+    addDatetimeColumn(field, headerKey, opts = {}) {
+        return { id: field, ...opts, field, headerKey, type: 'datetime' };
+    }
+    /** Boolean column — renders the `bool yes / bool no` indicator. */
+    addBooleanColumn(field, headerKey, opts = {}) {
+        return { id: field, ...opts, field, headerKey, type: 'boolean' };
+    }
+    /** Static-class chip column — renders `chip <chipPrefix><value>`.
+     *  Use `addStatusColumn` for reference_data-driven palettes. */
+    addChipColumn(field, headerKey, opts = {}) {
+        return {
+            id: field,
+            chipPrefix: 'chip-',
+            ...opts,
+            field,
+            headerKey,
+            type: 'chip',
+        };
+    }
+    /** Status chip column — palette + label resolved from
+     *  `reference_data` via `referenceKey`. Sortable by default. */
+    addStatusColumn(field, headerKey, referenceKey, opts = {}) {
+        return {
+            id: field,
+            sortable: true,
+            ...opts,
+            field,
+            headerKey,
+            type: 'status',
+            referenceKey,
+        };
+    }
+    /** 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'`. */
+    addReferenceColumn(field, headerKey, referenceKey, opts = {}) {
+        const { valueField, labelField, ...rest } = opts;
+        return {
+            id: field,
+            ...rest,
+            field,
+            headerKey,
+            type: 'reference',
+            referenceKey,
+            referenceValueField: valueField ?? rest.referenceValueField ?? 'code',
+            referenceLabelField: labelField ?? rest.referenceLabelField ?? 'label',
+        };
+    }
+    ngOnInit() {
+        super.ngOnInit();
+        this.serviceInstance = this.injector.get(this.getConfig().SERVICE);
+        const cfg = this.getConfig();
+        const hasDynamicRefs = (cfg?.SEARCH_REFERENTIALS_KEYS?.length ?? 0) > 0;
+        const hasStaticLists = (cfg?.SEARCH_STATIC_LISTS?.length ?? 0) > 0;
+        if (hasDynamicRefs || hasStaticLists) {
+            if (hasDynamicRefs)
+                this.initializeReferenceKeys(cfg.SEARCH_REFERENTIALS_KEYS);
+            if (hasStaticLists)
+                this.initializeStaticLists(cfg.SEARCH_STATIC_LISTS);
+            this.loadReferenceData(cfg.REF_DATA_OPTIONS);
+            this.refDataLoaded$.pipe(take(1)).subscribe(() => {
+                this.bootstrapInitialSearch();
+                this.applyDeepLinkStatus();
+            });
+        }
+        else {
+            this.bootstrapInitialSearch();
+            this.applyDeepLinkStatus();
+        }
+    }
+    /**
+     * 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.
+     */
+    applyDeepLinkStatus() {
+        const status = this.queryParam('status');
+        if (status)
+            this.setStatus(status);
+    }
+    /** Restore criteria from cache (returning to a screen) or seed defaults. */
+    bootstrapInitialSearch() {
+        const cached = this.cacheService.getCache(this.screenStateKey);
+        if (cached) {
+            this.criteria.set(new SearchEntity(cached));
+            this.restoreFilterUiFromCriteria(cached);
+        }
+        else {
+            const cfg = this.getConfig();
+            const fresh = new SearchEntity({});
+            if (cfg?.DEFAULT_SORT) {
+                fresh.sort = [
+                    {
+                        field: cfg.DEFAULT_SORT.field,
+                        sortDirection: cfg.DEFAULT_SORT.direction,
+                    },
+                ];
+            }
+            fresh.pagination = {
+                pageNumber: PaginationEnum.DEFAULT_PAGE,
+                pageSize: PaginationEnum.DEFAULT_PAGE_SIZE,
+            };
+            this.criteria.set(fresh);
+        }
+        this.search();
+    }
+    /**
+     * 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, ….
+     */
+    restoreFilterUiFromCriteria(cached) {
+        this.searchQuery.set(cached['searchText'] ?? '');
+        const next = {};
+        for (const f of this.advancedFilters) {
+            const value = cached[f.key];
+            if (value !== undefined && value !== null)
+                next[f.key] = value;
+        }
+        const activationKey = this.activationFilterKey;
+        if (activationKey && typeof cached[activationKey] === 'boolean') {
+            next[activationKey] = cached[activationKey];
+        }
+        if (Object.keys(next).length) {
+            this.advancedValues.update((cur) => ({ ...cur, ...next }));
+        }
+    }
+    /**
+     * 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() {
+        this.loading.set(true);
+        this.errorMsg.set(null);
+        // Stale responses are dropped so the latest issued search always
+        // wins, even if an earlier in-flight search resolves later.
+        const seq = ++this.searchSeq;
+        this.serviceInstance.search(this.criteria()).subscribe({
+            next: (result) => {
+                if (seq !== this.searchSeq)
+                    return;
+                this.items.set((result?.items ?? []));
+                this.totalCount.set(result?.totalCount ?? 0);
+                this.cacheService.setCache(this.screenStateKey, this.criteria());
+                this.loading.set(false);
+            },
+            error: (err) => {
+                if (seq !== this.searchSeq)
+                    return;
+                console.error('Search failed', err);
+                this.errorMsg.set(err?.message ?? 'Erreur de chargement');
+                this.loading.set(false);
+            },
+        });
+    }
+    /* ── Convenience criteria mutators ───────────────────────────── */
+    setSearchText(text) {
+        this.criteria.update((c) => this.cloneCriteria(c, { searchText: text || undefined, page: 1 }));
+        this.search();
+    }
+    setPage(pageNumber, pageSize) {
+        this.criteria.update((c) => this.cloneCriteria(c, {
+            page: pageNumber,
+            pageSize: pageSize ?? c.pagination.pageSize,
+        }));
+        this.search();
+    }
+    setSort(field, direction = SortDirectionEnum.DESC) {
+        // Normalize `'asc' | 'desc'` (ef-data-card emits these) to the
+        // backend's legacy `'Ascending' | 'Descending'` strings, so
+        // subclasses don't need to override `setSort` just for that.
+        const normalized = (direction || '').toLowerCase().startsWith('asc')
+            ? 'Ascending'
+            : 'Descending';
+        this.criteria.update((c) => this.cloneCriteria(c, { sort: [{ field, sortDirection: normalized }] }));
+        this.search();
+    }
+    setDateRange(start, end) {
+        this.criteria.update((c) => this.cloneCriteria(c, { start, end, page: 1 }));
+        this.search();
+    }
+    /** Patch arbitrary extra fields onto the criteria (for module-specific filters). */
+    patchCriteria(patch) {
+        this.criteria.update((c) => this.cloneCriteria(c, { extra: patch, page: 1 }));
+        this.search();
+    }
+    /** 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() {
+        const cfg = this.getConfig();
+        const fresh = new SearchEntity({});
+        if (cfg?.DEFAULT_SORT) {
+            fresh.sort = [
+                {
+                    field: cfg.DEFAULT_SORT.field,
+                    sortDirection: cfg.DEFAULT_SORT.direction,
+                },
+            ];
+        }
+        this.criteria.set(fresh);
+        // Reset all the shared filter-bar / selection signals so
+        // subclasses don't have to track each one individually.
+        this.searchQuery.set('');
+        this.statusFilter.set('all');
+        this.drawerOpen.set(false);
+        this.activeFilters.set([]);
+        this.advancedValues.set({});
+        this.selected.set(new Set());
+        this.resetDateRange();
+        this.cacheService.setCache(this.screenStateKey, fresh);
+        this.search();
+    }
+    cloneCriteria(c, patch) {
+        const next = new SearchEntity({});
+        Object.assign(next, c);
+        if ('searchText' in patch)
+            next.searchText = patch.searchText;
+        if (patch.page !== undefined || patch.pageSize !== undefined) {
+            next.pagination = {
+                pageNumber: patch.page ?? c.pagination.pageNumber,
+                pageSize: patch.pageSize ?? c.pagination.pageSize,
+            };
+        }
+        if (patch.sort !== undefined)
+            next.sort = patch.sort;
+        if (patch.start !== undefined)
+            next.start = patch.start;
+        if (patch.end !== undefined)
+            next.end = patch.end;
+        if (patch.extra)
+            Object.assign(next, patch.extra);
+        return next;
+    }
+    /* ── Navigation helpers ─────────────────────────────────────────
+         V2 routing convention (matches v1):
+           /<list>/details        → AbstractDetailScreenV2 in create mode
+           /<list>/details/:id    → AbstractDetailScreenV2 in edit mode
+           /<list>/details/:id?mode=duplicate → duplicate-as-template
+  
+         `currentUrl` cached on `AbstractScreenComponent.ngOnInit` is
+         not reliable (Router.url isn't committed yet during route
+         activation, so it holds the previous URL). Read `router.url`
+         at call time via `resolveListUrl()` instead. */
+    /** Resolve the list-screen URL at call time. Drops query / fragment
+     *  and strips a trailing slash. */
+    resolveListUrl() {
+        let url = this.router.url || this.currentUrl || '';
+        const q = url.indexOf('?');
+        if (q >= 0)
+            url = url.slice(0, q);
+        const h = url.indexOf('#');
+        if (h >= 0)
+            url = url.slice(0, h);
+        return url.replace(/\/$/, '');
+    }
+    navigateToDetails(id) {
+        const base = `${this.resolveListUrl()}/details`;
+        if (id == null && id !== 0) {
+            this.router.navigate([base]);
+            return;
+        }
+        this.router.navigate([base, id]);
+    }
+    /** Open the create form. */
+    add() {
+        this.router.navigate([`${this.resolveListUrl()}/details`]);
+    }
+    edit(id) {
+        if (!id) {
+            this.toastService.showError('Item [id] is undefined !');
+            return;
+        }
+        this.router.navigate([`${this.resolveListUrl()}/details`, id]);
+    }
+    delete(id) {
+        if (!id) {
+            this.toastService.showError('Item [id] is undefined!');
+            return;
+        }
+        this.confirmDialogService.confirm('Êtes-vous sûr de vouloir supprimer ?', () => this.serviceInstance.delete(id).subscribe({
+            next: (result) => {
+                if (result?.errors?.length) {
+                    this.handleErrors(result.errors);
+                }
+                else {
+                    this.search();
+                    this.toastService.showSuccess();
+                }
+            },
+            // The HTTP error interceptor surfaces the message (toast). Swallow
+            // here so a rejected delete (e.g. a 422 business-rule violation)
+            // doesn't bubble up as an unhandled error.
+            error: () => undefined,
+        }), () => undefined);
+    }
+    duplicate(id) {
+        if (!id) {
+            this.toastService.showError('Item [id] is undefined !');
+            return;
+        }
+        this.router.navigate([`${this.resolveListUrl()}/details`, id], {
+            queryParams: { mode: 'duplicate' },
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractSearchScreenV2, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.11", type: AbstractSearchScreenV2, isStandalone: true, selector: "ng-component", usesInheritance: true, ngImport: i0, template: '', isInline: true });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractSearchScreenV2, decorators: [{
+            type: Component,
+            args: [{ template: '', standalone: true }]
+        }] });
+
+/**
+ * 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.
+ */
+const AUDIT_HISTORY_SERVICE = new InjectionToken('AUDIT_HISTORY_SERVICE');
+
+/**
+ * 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;
+ *   }
+ * }
+ * ```
+ */
+class AbstractDetailScreenV2 extends AbstractScreenComponent {
+    screenState = ScreenStateEnum.DETAIL;
+    injector = inject(Injector);
+    location = inject(Location);
+    destroyRef = inject(DestroyRef);
+    auditHistoryService = inject(AUDIT_HISTORY_SERVICE, { optional: true });
+    serviceInstance;
+    /**
+     * 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()" />`.
+     */
+    auditEntries = signal([], ...(ngDevMode ? [{ debugName: "auditEntries" }] : /* istanbul ignore next */ []));
+    /** Loaded entity. Empty object when on `/details` (create mode). */
+    entity = signal({}, ...(ngDevMode ? [{ debugName: "entity" }] : /* istanbul ignore next */ []));
+    /** PK from the route param, or `null` on `/details` (new). */
+    entityId = signal(null, ...(ngDevMode ? [{ debugName: "entityId" }] : /* istanbul ignore next */ []));
+    /** Edit-mode flag — true when an id is present and we're not duplicating. */
+    editionState = signal(false, ...(ngDevMode ? [{ debugName: "editionState" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    duplicateMode = signal(false, ...(ngDevMode ? [{ debugName: "duplicateMode" }] : /* istanbul ignore next */ []));
+    /** True while service.get / create / update / delete is in flight. */
+    loading = signal(false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
+    /** Last load / save error message — empty string when none. */
+    errorMsg = signal(null, ...(ngDevMode ? [{ debugName: "errorMsg" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    customActions = computed(() => this.getCustomActions(), ...(ngDevMode ? [{ debugName: "customActions" }] : /* istanbul ignore next */ []));
+    /**
+     * Builder for `customActions`. Override per screen to add or
+     * replace the defaults. Pure function — reads other signals
+     * freely, returns a fresh array each call.
+     */
+    getCustomActions() {
+        // Edit mode: standard right-side group is enough; let subclass
+        // append Preview / Print PDF / etc. by overriding this method.
+        if (this.editionState())
+            return [];
+        // Create / duplicate mode: a Cancel button. See cancel().
+        return [
+            {
+                id: 'cancel',
+                labelKey: 'common_cancel',
+                icon: 'pi pi-times',
+                severity: 'ghost',
+                command: () => this.cancel(),
+            },
+        ];
+    }
+    ngOnInit() {
+        super.ngOnInit();
+        this.serviceInstance = this.injector.get(this.getConfig().SERVICE);
+        // Reference / static lists for the detail context (different
+        // set than the search screen's — `DETAILS_*` not `SEARCH_*`).
+        const cfg = this.getConfig();
+        if (cfg) {
+            const hasDynamicRefs = (cfg.DETAILS_REFERENTIALS_KEYS?.length ?? 0) > 0;
+            const hasStaticLists = (cfg.DETAILS_STATIC_LISTS?.length ?? 0) > 0;
+            if (hasDynamicRefs)
+                this.initializeReferenceKeys(cfg.DETAILS_REFERENTIALS_KEYS);
+            if (hasStaticLists)
+                this.initializeStaticLists(cfg.DETAILS_STATIC_LISTS);
+            if (hasDynamicRefs || hasStaticLists)
+                this.loadReferenceData(cfg.REF_DATA_OPTIONS);
+        }
+        // Wire route params → load (or reset to empty on /details).
+        combineLatest([this.route.paramMap, this.route.queryParamMap])
+            .pipe(takeUntilDestroyed(this.destroyRef))
+            .subscribe(([params, queryParams]) => {
+            const id = params.get('id');
+            const isDuplicate = queryParams.get('mode') === 'duplicate';
+            this.entityId.set(id);
+            this.duplicateMode.set(isDuplicate);
+            this.context.duplicateMode = isDuplicate;
+            this.editionState.set(!!id && !isDuplicate);
+            if (id) {
+                this.loadData();
+            }
+            else {
+                // New mode — reset to a fresh empty entity, no history yet.
+                this.entity.set({});
+                this.auditEntries.set([]);
+                this.afterLoad();
+            }
+        });
+    }
+    /**
+     * 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) {
+        this.entity.update(current => ({ ...current, ...patch }));
+    }
+    /** Fetch the entity from the backend and populate `entity`. */
+    loadData() {
+        const id = this.entityId();
+        if (!id)
+            return;
+        this.loading.set(true);
+        this.errorMsg.set(null);
+        this.serviceInstance.get(id).subscribe({
+            next: (result) => {
+                const vm = new ViewModelEntity(result);
+                vm.id = id;
+                this.entity.set(vm);
+                this.loading.set(false);
+                this.afterLoad();
+                this.loadAuditHistory();
+            },
+            error: (err) => {
+                console.error('AbstractDetailScreenV2.loadData failed', err);
+                this.errorMsg.set(err?.message ?? 'Erreur de chargement');
+                this.loading.set(false);
+            },
+        });
+    }
+    /**
+     * 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() {
+        const proceed = this.beforeSave();
+        if (proceed === false)
+            return;
+        this.clearServerErrors();
+        const isCreate = !this.editionState() || this.duplicateMode();
+        const payload = this.duplicateMode()
+            ? this.prepareEntityForDuplication()
+            : this.entity();
+        this.loading.set(true);
+        const op = isCreate
+            ? this.serviceInstance.create(payload)
+            : this.serviceInstance.update(this.entityId(), payload);
+        op.subscribe({
+            next: (response) => {
+                this.loading.set(false);
+                if (response?.errors?.length) {
+                    this.handleErrors(response.errors);
+                    return;
+                }
+                this.toastService.showSuccess();
+                this.afterSave(response);
+            },
+            error: (response) => {
+                this.loading.set(false);
+                if (response?.errors) {
+                    this.setServerErrors(response.errors);
+                    this.setFormErrors(response.errors);
+                    this.onSaveError(response.errors);
+                }
+            },
+        });
+    }
+    /**
+     * Soft-delete-then-navigate-back. Confirms with the user first.
+     */
+    delete() {
+        const id = this.entityId();
+        if (!id) {
+            this.toastService.showError('Item [id] is undefined!');
+            return;
+        }
+        this.confirmDialogService.confirm('Êtes-vous sûr de vouloir supprimer ?', () => this.serviceInstance.delete(id).subscribe({
+            next: (result) => {
+                if (result?.errors?.length) {
+                    this.handleErrors(result.errors);
+                }
+                else {
+                    this.toastService.showSuccess();
+                    this.navigateBack();
+                }
+            },
+            // The HTTP error interceptor surfaces the message (toast).
+            // Swallow here so a rejected delete (e.g. a 422 business-rule
+            // violation) doesn't bubble up as an unhandled error.
+            error: () => undefined,
+        }), () => undefined);
+    }
+    /** 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() {
+        const id = this.entityId();
+        const base = this.detailsBaseUrl();
+        if (id == null) {
+            // No source record (already on /details with no id) —
+            // just open the create form.
+            this.router.navigate([base]);
+            return;
+        }
+        this.router.navigate([base, id], {
+            queryParams: { mode: 'duplicate' },
+        });
+    }
+    /**
+     * 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() {
+        if (this.duplicateMode() && this.entityId() != null) {
+            this.router.navigate([this.detailsBaseUrl(), this.entityId()]);
+            return;
+        }
+        this.navigateBack();
+    }
+    /** Navigate back to the list (strip `/details` and any id). */
+    navigateBack() {
+        const url = (this.router.url || '').split('?')[0];
+        const idx = url.indexOf('/details');
+        if (idx !== -1) {
+            this.router.navigate([url.substring(0, idx)]);
+        }
+        else {
+            this.location.back();
+        }
+    }
+    /** Subclass print hook — no-op default. */
+    print() { }
+    /**
+     * 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.
+     */
+    loadAuditHistory() {
+        this.auditEntries.set([]);
+        const entityType = this.getConfig()?.AUDIT_ENTITY_TYPE;
+        const id = this.entityId();
+        // No service provided, screen not opted in, or no id yet → empty box.
+        if (!this.auditHistoryService || !entityType || !id) {
+            return;
+        }
+        // Fully defensive: a missing/misconfigured audit client (no provider,
+        // wrong shape, get() throwing, or an HTTP failure) must never break the
+        // detail screen — it just leaves the history empty.
+        try {
+            const result$ = this.auditHistoryService.get(entityType, id);
+            if (!result$ || typeof result$.subscribe !== 'function') {
+                return;
+            }
+            result$.subscribe({
+                next: (entries) => this.auditEntries.set(entries ?? []),
+                error: () => this.auditEntries.set([]),
+            });
+        }
+        catch {
+            this.auditEntries.set([]);
+        }
+    }
+    /* ── Override hooks ─────────────────────────────────────────── */
+    /**
+     * Called right before `save()` dispatches to the backend. Return
+     * `false` to cancel (e.g., form validation failed). Default: no-op.
+     */
+    beforeSave() {
+        return true;
+    }
+    /** Override to post-process the loaded `entity` (or to refresh
+     *  derived signals). Default: no-op. */
+    afterLoad() { }
+    /**
+     * 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
+     */
+    afterSave(result) {
+        const cfg = this.getConfig();
+        if (cfg?.INVALIDATE_KEYS_ON_SAVE) {
+            this.invalidateReferences(cfg.INVALIDATE_KEYS_ON_SAVE);
+            if (cfg.REFRESH_ON_SAVE) {
+                this.refreshReferenceData(cfg.INVALIDATE_KEYS_ON_SAVE);
+            }
+        }
+        const isCreate = !this.editionState() || this.duplicateMode();
+        if (isCreate) {
+            const newId = typeof result === 'object' ? (result?.id ?? result) : result;
+            this.router.navigate([this.detailsBaseUrl(), newId]);
+        }
+        else {
+            // Update succeeded in place — refresh the change-history so the new
+            // entry shows without a manual reload.
+            this.loadAuditHistory();
+        }
+    }
+    /** Override to surface form-level validation errors after a 4xx
+     *  response. Default: no-op (errors are already on `serverErrors`). */
+    onSaveError(_errors) { }
+    /** Strip id (if present) from the entity before a duplicate save. */
+    prepareEntityForDuplication() {
+        const dup = { ...this.entity() };
+        delete dup.id;
+        delete dup.Id;
+        return this.customizeDuplicatedEntity(dup);
+    }
+    /** Override to clear additional fields (codes, slugs, refs)
+     *  before saving a duplicated entity. */
+    customizeDuplicatedEntity(entity) {
+        return entity;
+    }
+    /* ── Internals ──────────────────────────────────────────────── */
+    /** Resolve the bare `/<resource>/details` base URL — strips a
+     *  trailing `:id`, query string, fragment, trailing slash. */
+    detailsBaseUrl() {
+        let url = this.router.url || '';
+        const q = url.indexOf('?');
+        if (q >= 0)
+            url = url.slice(0, q);
+        const h = url.indexOf('#');
+        if (h >= 0)
+            url = url.slice(0, h);
+        // If we're on /…/details/<id>, drop <id>; if on /…/details, leave it.
+        const m = url.match(/^(.*?\/details)(?:\/[^/]+)?\/?$/);
+        return m ? m[1] : url;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractDetailScreenV2, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.11", type: AbstractDetailScreenV2, isStandalone: true, selector: "ng-component", usesInheritance: true, ngImport: i0, template: '', isInline: true });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractDetailScreenV2, decorators: [{
+            type: Component,
+            args: [{ template: '', standalone: true }]
+        }] });
+
+/**
+ * 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.
+ */
+class AbstractReportScreenV2 extends AbstractScreenComponent {
+    screenState = ScreenStateEnum.REPORT;
+    injector = inject(Injector);
+    /** NSwag reports client resolved from `ScreenConfig.SERVICE` — expose a
+     *  typed getter in the screen: `get client() { return this.reportsService as XClient; }` */
+    reportsService;
+    registeredWidgets = [];
+    /** Active period. Bound to `ef-datepicker-advanced`; every widget loader
+     *  receives its UTC-normalized start/end. */
+    dateRange = signal(this.buildDefaultDateRange(), ...(ngDevMode ? [{ debugName: "dateRange" }] : /* istanbul ignore next */ []));
+    ngOnInit() {
+        super.ngOnInit();
+        this.reportsService = this.injector.get(this.getConfig().SERVICE);
+        const lists = this.getConfig()?.REPORT_STATIC_LISTS ?? [];
+        if (lists.length > 0) {
+            this.initializeStaticLists(lists);
+            this.loadReferenceData(this.getConfig()?.REF_DATA_OPTIONS);
+            this.refDataLoaded$.pipe(take(1)).subscribe(() => this.loadAll());
+        }
+        else {
+            this.loadAll();
+        }
+    }
+    /* ── Period ─────────────────────────────────────────────────── */
+    /** Wired to `<ef-datepicker-advanced (rangeChange)>`. */
+    onDateRangeChange(range) {
+        this.dateRange.set(range);
+        this.loadAll();
+    }
+    /** Default period from the config's `DEFAULT_PERIOD` preset. */
+    buildDefaultDateRange() {
+        return this.rangeFromPreset(this.getConfig()?.DEFAULT_PERIOD ?? 'last_30_days');
+    }
+    /**
+     * 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).
+     */
+    rangeFromPreset(key) {
+        const KNOWN = [
+            'today', 'this_week', 'this_month', 'last_30_days',
+            'last_90_days', 'this_quarter', 'this_year',
+        ];
+        const k = KNOWN.includes(key) ? key : 'last_30_days';
+        const today = this.startOfToday();
+        const end = new Date(today);
+        let start = new Date(today);
+        switch (k) {
+            case 'today':
+                break;
+            case 'this_week': {
+                const dow = (today.getDay() + 6) % 7;
+                start.setDate(today.getDate() - dow);
+                break;
+            }
+            case 'this_month':
+                start = new Date(today.getFullYear(), today.getMonth(), 1);
+                break;
+            case 'last_90_days':
+                start.setDate(today.getDate() - 89);
+                break;
+            case 'this_quarter':
+                start = new Date(today.getFullYear(), Math.floor(today.getMonth() / 3) * 3, 1);
+                break;
+            case 'this_year':
+                start = new Date(today.getFullYear(), 0, 1);
+                break;
+            case 'last_30_days':
+            default:
+                start.setDate(today.getDate() - 29);
+                break;
+        }
+        return { start, end, presetKey: k, labelKey: `date_preset_${k}`, label: '' };
+    }
+    startOfToday() {
+        const d = new Date();
+        return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+    }
+    /**
+     * 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.
+     */
+    toUtcDate(d) {
+        return new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+    }
+    /* ── Widgets ────────────────────────────────────────────────── */
+    /**
+     * 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.
+     */
+    widget(loader) {
+        const data = signal(null, ...(ngDevMode ? [{ debugName: "data" }] : /* istanbul ignore next */ []));
+        const status = signal('loading', ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
+        const handle = {
+            data: data.asReadonly(),
+            status: status.asReadonly(),
+            reload: () => {
+                const { start, end } = this.dateRange();
+                status.set('loading');
+                loader(this.toUtcDate(start), this.toUtcDate(end)).subscribe({
+                    next: (value) => {
+                        data.set(value);
+                        status.set('ready');
+                    },
+                    error: () => status.set('error'),
+                });
+            },
+        };
+        this.registeredWidgets.push(handle);
+        return handle;
+    }
+    /** Reload every registered widget against the current period. */
+    loadAll() {
+        for (const w of this.registeredWidgets)
+            w.reload();
+    }
+    /* ── Grants + export ────────────────────────────────────────── */
+    /** Export grant (ADR-011) on this screen's own code. Grants are loaded
+     *  once by `processGrants()` in ngOnInit — safe to call from templates. */
+    canExport() {
+        return this.context?.isGranted(Permissions.Export) ?? false;
+    }
+    /** CSV download gated by the Export grant — silently no-ops without it. */
+    exportCsv(filename, rows, columns) {
+        if (!this.canExport())
+            return;
+        // `CsvColumn<T>['key']` is `keyof T & string`, which is `never` for the
+        // bare `object` type — widen to `Record<string, unknown>` so the
+        // generic infers a `string`-keyed column, matching `columns` as declared.
+        CsvUtils.download(filename, CsvUtils.toCsv(rows, columns));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractReportScreenV2, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.11", type: AbstractReportScreenV2, isStandalone: true, selector: "ng-component", usesInheritance: true, ngImport: i0, template: '', isInline: true });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractReportScreenV2, decorators: [{
+            type: Component,
+            args: [{ template: '', standalone: true }]
+        }] });
+
 class AbstractSubScreenComponent extends AbstractScreenComponent {
     screenState = null;
     ngOnInit() {
@@ -821,6 +2084,76 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImpo
                 }]
         }] });
 
+/**
+ * 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.
+ */
+class AbstractSubScreenV2 extends AbstractScreenComponent {
+    screenState = null;
+    injector = inject(Injector);
+    /** NSwag client resolved from `ScreenConfig.SERVICE` (null-safe: a
+     *  sub-screen fed entirely by inputs may omit SERVICE). */
+    serviceInstance;
+    /**
+     * 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.
+     */
+    collapsed = signal(true, ...(ngDevMode ? [{ debugName: "collapsed" }] : /* istanbul ignore next */ []));
+    toggleCollapsed() {
+        this.collapsed.update((c) => !c);
+    }
+    /** Read grant on the config's `SCREEN` — gate the whole fragment on
+     *  this so an unauthorized user gets nothing (not an erroring card). */
+    canRead() {
+        return this.context?.isGranted(Permissions.Read) ?? false;
+    }
+    ngOnInit() {
+        super.ngOnInit();
+        const cfg = this.getConfig();
+        if (cfg?.SERVICE) {
+            this.serviceInstance = this.injector.get(cfg.SERVICE);
+        }
+        const hasDynamicRefs = (cfg?.SEARCH_REFERENTIALS_KEYS?.length ?? 0) > 0;
+        const hasStaticLists = (cfg?.SEARCH_STATIC_LISTS?.length ?? 0) > 0;
+        if (hasDynamicRefs)
+            this.initializeReferenceKeys(cfg.SEARCH_REFERENTIALS_KEYS);
+        if (hasStaticLists)
+            this.initializeStaticLists(cfg.SEARCH_STATIC_LISTS);
+        // No refs declared → no load, and (matching AbstractSearchScreenV2)
+        // no refDataLoaded$ emission — don't wait on it in that case.
+        if (hasDynamicRefs || hasStaticLists) {
+            this.loadReferenceData(cfg.REF_DATA_OPTIONS);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractSubScreenV2, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.11", type: AbstractSubScreenV2, isStandalone: true, selector: "ng-component", usesInheritance: true, ngImport: i0, template: '', isInline: true });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.11", ngImport: i0, type: AbstractSubScreenV2, decorators: [{
+            type: Component,
+            args: [{ template: '', standalone: true }]
+        }] });
+
 class ScreenConfig {
     SCREEN;
     SERVICE;
@@ -832,6 +2165,24 @@ class ScreenConfig {
     REFRESH_ON_SAVE;
     REF_DATA_OPTIONS;
     DEFAULT_SORT;
+    /**
+     * 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;
+    /**
+     * Report screens (AbstractReportScreenV2): starting period preset for the
+     * screen's ef-datepicker-advanced. Unset → 'last_30_days'.
+     */
+    DEFAULT_PERIOD;
+    /**
+     * Report screens: translatable static lists preloaded before the first
+     * loadAll() — same mechanism as SEARCH_STATIC_LISTS on list screens.
+     */
+    REPORT_STATIC_LISTS;
 }
 
 // Abstract base classes
@@ -840,5 +2191,5 @@ class ScreenConfig {
  * Generated bundle index. Do not edit.
  */
 
-export { AbstractComponent, AbstractDetailScreenComponent, AbstractEntity, AbstractScreenComponent, AbstractSearchScreenComponent, AbstractSubScreenComponent, PaginationEnum, SCREEN_REF_DATA_SERVICE, ScreenConfig, ScreenContext, ScreenStateEnum, SearchEntity, SortDirectionEnum, StateUtilsEnum, ViewModelEntity };
+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 };
 //# sourceMappingURL=elasticias-screens.mjs.map