@elasticias/screens 1.0.39 → 1.0.41

package/package.json

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

package/types/elasticias-screens.d.ts

@@ -61,6 +61,15 @@ declare class ScreenContext extends AbstractEntity {
     entity: unknown;
     grants: string[];
     duplicateMode: boolean;
+    /**
+     * Whether the screen may write the record it shows, for its current mode.
+     * Set by `AbstractDetailScreenV2` to its own `canWrite` signal, so shared
+     * components bound to `[context]` (ef-detail-toolbar's Save and its
+     * `requiresWrite` custom actions) follow the same rule without each
+     * screen passing it again. Undefined on screens that have no write mode
+     * (search, report), where those components keep their default behaviour.
+     */
+    canWrite?: Signal<boolean>;
     constructor(state: string, group?: unknown, entity?: unknown, refDataProvider?: ReferenceDataProvider, bundles?: Map<string, Map<string, Map<string, string>>>, grants?: string[], screenName?: string, language?: string);
     setReferenceDataProvider(provider: ReferenceDataProvider): void;
     get ref(): {
@@ -224,6 +233,12 @@ declare const SCREEN_REF_DATA_SERVICE: InjectionToken<ScreenReferenceDataService
 declare abstract class AbstractScreenComponent extends AbstractComponent implements OnInit, AfterViewInit, OnDestroy {
     context: ScreenContext;
     connectedUser: any;
+    /** V1 only: the NgForm a V1 detail template declares as `#entityForm`.
+     *  V2 templates bind `[value]` / `(valueChangeEvent)` with no NgForm, so
+     *  this stays undefined there and everything below that walks it
+     *  (`disableAllControls`, `setFormErrors`, `isFormValid`) does nothing.
+     *  V2 screens use `AbstractDetailScreenV2.readOnlyMode()` bound as
+     *  `[efReadOnly]` on the form container, and `canWrite()` for saving. */
     entityForm: NgForm;
     serverErrors: _angular_core.WritableSignal<{
         [key: string]: string[];
@@ -241,6 +256,10 @@ declare abstract class AbstractScreenComponent extends AbstractComponent impleme
     get state(): string | null;
     screenStateKey: string;
     ngOnInit(): void;
+    /** The `isReadOnly()` branch below is the V1 read-only path. It never
+     *  fires usefully on a V2 screen (see `entityForm`), and its predicate
+     *  ignores the mode: Read+Create on an existing record counts as
+     *  writable. V2 detail screens rely on `readOnlyMode()` instead. */
     ngAfterViewInit(): void;
     processGrants(): void;
     isFormValid(): boolean;
@@ -319,6 +338,8 @@ declare abstract class AbstractScreenComponent extends AbstractComponent impleme
     /** JSON gives back ISO strings; hand back real `Date`s or nothing. */
     private static reviveDateRange;
     clearServerErrors(): void;
+    /** V1 only: disables the controls of `entityForm`. A no-op on V2
+     *  screens, which use `readOnlyMode()` + `[efReadOnly]`. */
     disableAllControls(): void;
     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>;
@@ -920,6 +941,14 @@ interface EfDetailToolbarAction {
      * show (subject to `visible`).
      */
     permission?: Permissions;
+    /**
+     * The action changes the record (approve, cancel, complete, ...).
+     * Hidden when the screen cannot write it in its current mode, read from
+     * the bound `ScreenContext.canWrite` (set by `AbstractDetailScreenV2`).
+     * Independent of `permission`: when both are set, both must pass. A
+     * context with no write state (no `canWrite`) leaves the action shown.
+     */
+    requiresWrite?: boolean;
     /** Click handler. */
     command?: () => void;
 }
@@ -970,6 +999,12 @@ declare abstract class AbstractDetailScreenV2<TItem extends object = any> extend
     private readonly destroyRef;
     private readonly auditHistoryService;
     private readonly shortcuts;
+    /** The in-flight entity / history requests. A newer load drops the
+     *  older one, so a slow response for an id the screen has moved off
+     *  can never overwrite the record it now shows, and destroying the
+     *  screen drops both. */
+    private loadSub?;
+    private auditSub?;
     /** Distinguishes this instance's registration from any other detail
      *  screen alive at once (the outgoing and incoming routed component
      *  can briefly coexist), the same convention ef-row-actions uses:
@@ -998,6 +1033,29 @@ declare abstract class AbstractDetailScreenV2<TItem extends object = any> extend
      * the `?mode=duplicate` query param.
      */
     readonly duplicateMode: _angular_core.WritableSignal<boolean>;
+    /**
+     * Bumped every time `processGrants()` (re)reads the user's grants.
+     * `context` is a plain object, not a signal, so without this a
+     * `canWrite()` read before the grants arrive would memoize `false`
+     * and the route subscription re-setting `editionState(false)` to the
+     * same value would never invalidate it.
+     */
+    private readonly grantsVersion;
+    /**
+     * Whether the user may write the record on screen, for the mode it is
+     * in: an existing record (edit mode, not duplicating) needs Edit; a new
+     * record or a duplicate needs Create. Read is not enough for either,
+     * which is how a Read-only user got a fully editable, savable form.
+     *
+     * Bind its negation on the form container to disable every ef-* control:
+     * `<div class="form" [efReadOnly]="readOnlyMode()">`. ef-detail-toolbar
+     * reads it through `context.canWrite` to hide Save, so screens pass
+     * nothing for that. The backend still enforces the same grants; this is
+     * the UI agreeing with it.
+     */
+    readonly canWrite: _angular_core.Signal<boolean>;
+    /** `!canWrite()`, named for the `[efReadOnly]` binding it feeds. */
+    readonly readOnlyMode: _angular_core.Signal<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. */
@@ -1024,6 +1082,7 @@ declare abstract class AbstractDetailScreenV2<TItem extends object = any> extend
      */
     protected getCustomActions(): EfDetailToolbarAction[];
     ngOnInit(): void;
+    processGrants(): void;
     /**
      * Merge a partial patch into the `entity` signal — the canonical
      * way for form inputs to write back. Spread-immutably so OnPush
@@ -1044,6 +1103,10 @@ declare abstract class AbstractDetailScreenV2<TItem extends object = any> extend
      * 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.
+     *
+     * A no-op when `canWrite()` is false, checked before `beforeSave()` so
+     * a screen's validation never toasts at a user who could not save
+     * anyway.
      */
     save(): void;
     /**
@@ -1068,7 +1131,9 @@ declare abstract class AbstractDetailScreenV2<TItem extends object = any> extend
      *  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. */
+     *  flow would fall back to creating a blank record.
+     *  Needs Create: a duplicate is saved through `service.create()`, so
+     *  opening one without Create would only lead to a read-only form. */
     duplicate(): void;
     /**
      * Cancel handler for the default toolbar action: