@elasticias/screens 1.0.48 → 1.0.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elasticias/screens",
-  "version": "1.0.48",
+  "version": "1.0.50",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",

package/types/elasticias-screens.d.ts

@@ -5,7 +5,7 @@ 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 { CacheService, ToastService, ConfirmDialogService, EfConfirmOptions } from '@elasticias/core';
 import { Table, TableLazyLoadEvent } from 'primeng/table';
 import { Location } from '@angular/common';
 
@@ -185,6 +185,24 @@ declare abstract class ScreenConfig {
      * to opt out. Must match the backend IAuditable.AuditEntityType (e.g. 'Client').
      */
     AUDIT_ENTITY_TYPE?: string;
+    /**
+     * Detail screens: business-rule codes (422 `ruleCode`) meaning "the record
+     * changed since you loaded it", e.g. ERP `['BR_SO_0123']`. A failed update
+     * with one of them offers a "reload" confirm; accepting
+     * reloads the record and drops the unsaved edits. The app must define the
+     * i18n keys `ef_stale_reload` (button), `ef_stale_reload_confirm` (message,
+     * say that unsaved edits are lost) and `ef_stale_reload_header`.
+     */
+    STALE_RULE_CODES?: string[];
+    /**
+     * Detail screens: after a successful in-place update (not a create or
+     * duplicate) refresh the record, so server-owned fields such as a
+     * concurrency revision are current for the next save. Uses the update
+     * response when it is the saved record (an object whose `id` is the
+     * screen's entity id), otherwise one `get(id)`. Change history reloads
+     * either way. Default false: the record is left as edited.
+     */
+    RELOAD_AFTER_SAVE?: boolean;
     /**
      * Report screens (AbstractReportScreenV2): starting period preset for the
      * screen's ef-datepicker-advanced. Unset → 'last_30_days'.
@@ -538,12 +556,34 @@ interface EfDataCardColumn {
      * always excluded regardless.
      */
     hideable?: boolean;
+    /**
+     * Start the column hidden. The viewer can still show it from the
+     * Columns picker, and that choice is saved per `tableKey` through
+     * `EF_PREFERENCE_STORE` like any other hidden column, so it wins on
+     * the next visit. Use it for a column a wide table can do without at
+     * first sight (a sort position, an internal code).
+     *
+     * Ignored with `hideable: false` and on `select` / `actions`: a column
+     * the picker does not list could never be shown again.
+     *
+     * A table whose preferences were saved before the column became
+     * `defaultHidden` keeps the saved list, which shows it.
+     */
+    defaultHidden?: boolean;
     /**
      * Set `false` to keep this column out of a CSV export. Use it for
      * columns that only make sense on screen — a thumbnail, a rendered
      * badge with no underlying value. Defaults to exported.
      */
     exportable?: boolean;
+    /**
+     * The value this column writes to a CSV export, given the row. Use it
+     * where the screen shows a label composed from codes (a kind plus its
+     * rule), so the file says what the screen said. It wins over the
+     * built-in reference lookup and raw value; `null`/`undefined` become an
+     * empty cell.
+     */
+    exportValue?: (row: any) => unknown;
     /** Inline CSS width (e.g. `'40px'`, `'15%'`). */
     width?: string;
     /** Extra CSS classes to apply on the `<td>` (e.g. `'num'`). */
@@ -608,6 +648,13 @@ interface EfDataCardExportRequest {
     resolveCell: (row: unknown, col: EfDataCardColumn) => unknown;
 }
 
+/**
+ * What a search screen may add to its delete confirmation: the copy, the
+ * name, the params. `accept` and `reject` stay with the base, so the
+ * delete call, the `errors` handling, the new search and the toast are
+ * the same on every screen.
+ */
+type EfDeleteConfirmOptions = Partial<Omit<EfConfirmOptions, 'accept' | 'reject' | 'intent'>>;
 /**
  * Declarative definition of an advanced-search select filter rendered in
  * the filter drawer. One `<ef-select>` is rendered per entry; the screen
@@ -662,6 +709,15 @@ interface AdvancedSelectFilter {
 declare abstract class AbstractSearchScreenV2<TItem = any> extends AbstractScreenComponent implements OnInit {
     protected readonly screenState = ScreenStateEnum.SEARCH;
     protected readonly injector: Injector;
+    private readonly destroyRef;
+    /**
+     * A delete confirm is loading or open. A second click (or the row
+     * shortcut) meanwhile is ignored, so one gesture cannot start two impact
+     * reads or stack two confirms. Cleared when the confirm is answered
+     * (PrimeNG calls reject on close and Escape too) or when the read
+     * yields no confirm.
+     */
+    private deleteConfirmBusy;
     private serviceInstance;
     /**
      * Translate lazily, through the injector.
@@ -866,6 +922,13 @@ declare abstract class AbstractSearchScreenV2<TItem = any> extends AbstractScree
      * criteria to cache on success so revisits can restore.
      */
     search(): void;
+    /**
+     * Hook for a screen whose search returns more than a page of rows (counts,
+     * facets, a summary): called with the raw response after `items` and
+     * `totalCount` are set, for the latest issued search only. A stale or
+     * failed search never reaches it.
+     */
+    protected afterSearch(_result: unknown): void;
     setSearchText(text: string): void;
     setPage(pageNumber: number, pageSize?: number): void;
     setSort(field: string, direction?: string): void;
@@ -929,7 +992,33 @@ declare abstract class AbstractSearchScreenV2<TItem = any> extends AbstractScree
      * ```
      */
     protected getDeleteConfirmName(_id: any): string | undefined;
+    /**
+     * Async details for the delete confirmation, read before it opens. Use
+     * it when the confirm has to say what the delete will take with it, such
+     * as how many products lose a collection:
+     *
+     * ```ts
+     * protected override getDeleteConfirmOptions(id: any) {
+     *   return this.collectionsClient.deleteImpact(id).pipe(
+     *     map(impact => ({
+     *       messageKey: impact.onHome ? 'x_delete_message_home' : 'x_delete_message',
+     *       messageParams: { count: impact.productCount ?? 0 },
+     *     })),
+     *   );
+     * }
+     * ```
+     *
+     * The returned options are merged over `{ intent: 'delete', name:
+     * getDeleteConfirmName(id) }`. Only the first value of an Observable is
+     * used. If the read fails (the HTTP interceptor toasts it) or completes
+     * without a value, no confirm opens and nothing is deleted. Return
+     * `undefined`, the default, to open the confirm at once. While the read
+     * is in flight or the confirm is open, another delete is ignored, and a
+     * screen destroyed during the read opens nothing.
+     */
+    protected getDeleteConfirmOptions(_id: any): Observable<EfDeleteConfirmOptions> | Promise<EfDeleteConfirmOptions> | undefined;
     delete(id: any): void;
+    private openDeleteConfirm;
     duplicate(id: any): void;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AbstractSearchScreenV2<any>, never>;
@@ -977,6 +1066,9 @@ interface EfDetailToolbarAction {
     visible?: boolean;
     /** Disable without removing. */
     disabled?: boolean;
+    /** Translation key saying why the action is disabled; shown in the
+     *  phone overflow menu under the label and as its description. */
+    disabledReasonKey?: string;
     /**
      * If set, the action is hidden unless the bound `ScreenContext`
      * grants this permission. Actions with no `permission` always
@@ -991,6 +1083,14 @@ interface EfDetailToolbarAction {
      * context with no write state (no `canWrite`) leaves the action shown.
      */
     requiresWrite?: boolean;
+    /**
+     * On a phone, when the actions overflow into the menu, this one stays
+     * inline beside Save (a screen's next step, which should never be one
+     * tap deeper). Filtering by `visible`, `permission` and `requiresWrite`
+     * still applies first. Ignored on tablet and desktop, which never
+     * overflow. Keep it to one action: each one kept takes row width.
+     */
+    keepInView?: boolean;
     /** Click handler. */
     command?: () => void;
 }
@@ -1141,6 +1241,8 @@ declare abstract class AbstractDetailScreenV2<TItem extends object = any> extend
     patchEntity(patch: Partial<TItem>): void;
     /** Fetch the entity from the backend and populate `entity`. */
     loadData(): void;
+    /** Install a fetched (or save-returned) record as the current entity. */
+    private applyLoaded;
     /**
      * Persist the entity. Routes to `service.create()` when in new
      * or duplicate mode, `service.update(id, entity)` when editing.
@@ -1151,6 +1253,23 @@ declare abstract class AbstractDetailScreenV2<TItem extends object = any> extend
      * anyway.
      */
     save(): void;
+    /**
+     * True when a failed save means the record changed since it was loaded:
+     * a refusal whose `ruleCode` is in the config's `STALE_RULE_CODES`. A bare
+     * 409 is a duplicate (e.g. a slug already taken), not a stale record, so
+     * it never offers a reload. Only a refusal
+     * the app's interceptor already toasted counts, so the user is never
+     * told twice.
+     */
+    protected isStaleSave(error: unknown): boolean;
+    /**
+     * Asks, in an accessible confirm dialog (focus trapped, Escape cancels),
+     * whether to reload the record. Accepting discards the unsaved edits,
+     * and the message says so. The refusal itself was already toasted.
+     * App keys: `ef_stale_reload` (button), `ef_stale_reload_confirm`
+     * (message) and optionally `ef_stale_reload_header`.
+     */
+    protected offerStaleReload(): void;
     /**
      * Soft-delete-then-navigate-back. Confirms with the user first.
      */
@@ -1427,4 +1546,4 @@ declare class ViewModelEntity extends AbstractEntity {
 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, EfBoundedDateRange, EfDataCardColumn, EfDataCardColumnAlign, EfDataCardColumnMobileRole, EfDataCardColumnType, EfDataCardExportRequest, EfDataCardSort, EfDataCardSortDirection, EfDatePresetKey, EfDateRange, EfDetailToolbarAction, EfReferenceColumnOpts, EfSearchToolbarAction, LoadOptions, ReferenceDataProvider, ReportWidget, ReportWidgetStatus, ScreenDatatableColumn, ScreenReferenceDataService };
+export type { ActiveFilter, AdvancedSelectFilter, AuditHistoryService, DefaultSort, EfBoundedDateRange, EfDataCardColumn, EfDataCardColumnAlign, EfDataCardColumnMobileRole, EfDataCardColumnType, EfDataCardExportRequest, EfDataCardSort, EfDataCardSortDirection, EfDatePresetKey, EfDateRange, EfDeleteConfirmOptions, EfDetailToolbarAction, EfReferenceColumnOpts, EfSearchToolbarAction, LoadOptions, ReferenceDataProvider, ReportWidget, ReportWidgetStatus, ScreenDatatableColumn, ScreenReferenceDataService };