@mintplayer/ng-spark 22.4.0 → 22.6.0

package/types/mintplayer-ng-spark-models.d.ts

@@ -144,6 +144,13 @@ interface EntityAttributeDefinition {
     referenceDisplayType?: EReferenceDisplayType;
     /** For array AsDetail attributes: when true, rows can be drag-reordered (order = array position) */
     isSortable?: boolean;
+    /**
+     * When true, changing this attribute's value posts the in-progress object to
+     * `/spark/po/{objectTypeId}/refresh` and applies the reshaped result as an overlay.
+     * Schema-only by design — it never travels on a PersistentObjectAttribute, so a client
+     * cannot claim a trigger the model did not declare.
+     */
+    triggersRefresh?: boolean;
     /** For LookupReference attributes, specifies the lookup reference type name */
     lookupReferenceType?: string;
     /**
@@ -234,9 +241,21 @@ interface ProgramUnit {
     id: string;
     name: TranslatedString;
     icon?: string;
+    /**
+     * Canonical unit type, exact-cased by the server's loader: 'query' | 'persistentObject' | 'url'.
+     * Kept as string rather than a union so an older client tolerates a newer server.
+     */
     type: string;
     queryId?: string;
     persistentObjectId?: string;
+    /**
+     * For a persistentObject unit: the specific object to open — the menu entry deep-links to
+     * `/po/{type}/{objectId}`. Absent means the type's default list. For a composed page this is
+     * whatever stable string the app declared; the server's Actions class may ignore it.
+     */
+    objectId?: string;
+    /** For a url unit: the external address, rendered as a plain anchor (never a router link). */
+    url?: string;
     order: number;
     alias?: string;
 }
@@ -446,5 +465,90 @@ type SparkSelectionMode = 'none' | 'single' | 'multiple';
  */
 declare function selectionModeFor(actions: CustomActionDefinition[]): SparkSelectionMode;
 
-export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, currentLanguage, dictToNestedPo, filterQueryActions, hasShowedOnFlag, nestedPoToDict, nestedPoToDisplayRow, parseSelectionRule, resolveTranslation, selectionModeFor, selfBreadcrumb };
-export type { AttributeGroup, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryResult, RetryActionPayload, RetryActionResult, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };
+/**
+ * One selectable value, as replaced by a refresh hook. Mirrors the server's
+ * `PersistentObjectAttributeOption`.
+ */
+interface RefreshedOption {
+    key: string;
+    label?: Record<string, string>;
+}
+/**
+ * What a refresh changed about one attribute's *presentation*.
+ *
+ * Kept separate from `EntityType` on purpose. The form's option loading hangs off a single effect
+ * keyed on `entityType` identity, and `SparkService` caches nothing — so applying a refresh by
+ * setting a new `EntityType` re-issues every reference query, every lookup fetch, a full
+ * `getEntityTypes()` and a `getPermissions()` per array-AsDetail attribute, on every refresh.
+ * Mutating the existing object instead is inert, because the rendering computed would not re-run.
+ * An overlay is the only shape that is both reactive and free.
+ */
+interface AttributeOverlay {
+    isRequired?: boolean;
+    isReadOnly?: boolean;
+    isVisible?: boolean;
+    rules?: ValidationRule[];
+    query?: string;
+    /** `undefined` means the hook did not touch the options; an empty array means there are none. */
+    options?: RefreshedOption[];
+}
+type RefreshOverlay = Record<string, AttributeOverlay>;
+/** Applies an overlay to one attribute definition, returning a new object when anything changed. */
+declare function applyOverlay(attr: EntityAttributeDefinition, overlay: AttributeOverlay | undefined): EntityAttributeDefinition;
+/**
+ * Reads a refresh response into an overlay.
+ *
+ * Everything here is presentation the server owns outright, so it is taken verbatim — there is no
+ * merging to do on this half, only on values.
+ */
+declare function overlayFromResponse(response: PersistentObject): RefreshOverlay;
+/**
+ * Merges a refresh response's values into the live form.
+ *
+ * The rule, and the reason for it: a refresh is not instant, and the user keeps typing during it —
+ * the form is deliberately never frozen. So for each attribute we ask whether the *server* changed
+ * it, by comparing the response against the values that were **sent**, not against what is on
+ * screen now.
+ *
+ * - server value equals what we sent → the hook did not touch it, so whatever is in the form now
+ *   wins, including anything typed while the request was in flight;
+ * - server value differs → the hook deliberately changed it, and it wins over a concurrent edit.
+ *
+ * Comparing against the displayed value instead is the classic "refresh eats my typing" bug;
+ * refusing to overwrite anything the user touched is the equally wrong opposite, where a dependent
+ * field the hook computed never appears.
+ *
+ * @param sent      values as they were POSTed, captured before the request left
+ * @param current   values as they are now, which may have moved on
+ * @param response  the reshaped object
+ */
+declare function mergeRefreshValues(sent: Record<string, any>, current: Record<string, any>, response: PersistentObject): Record<string, any>;
+
+/** One rule failure, in the shape the form already renders per field. */
+interface RuleFailure {
+    attributeName: string;
+    ruleType: string;
+    message: string;
+}
+interface EvaluableAttribute {
+    name: string;
+    label?: TranslatedString;
+    isRequired?: boolean;
+    rules?: ValidationRule[];
+}
+/**
+ * Evaluates an attribute's rules against a value, mirroring the server's `ValidationService`.
+ *
+ * ⚠️ **Parity with the server is the point, and disagreement is worse than silence.** A client that
+ * rejects something the server would accept blocks legitimate work with no recourse; one that
+ * accepts something the server rejects merely defers the error to the round-trip, which is where it
+ * used to live anyway. So the rule set here is deliberately limited to the types the server
+ * implements, and an unrecognised rule type is ignored rather than guessed at.
+ *
+ * This exists because a refresh hook that imposes a rule needs it to bite before Save — previously
+ * `rules` was carried on the wire and never evaluated in the browser at all.
+ */
+declare function evaluateRules(attr: EvaluableAttribute, value: any): RuleFailure[];
+
+export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, applyOverlay, currentLanguage, dictToNestedPo, evaluateRules, filterQueryActions, hasShowedOnFlag, mergeRefreshValues, nestedPoToDict, nestedPoToDisplayRow, overlayFromResponse, parseSelectionRule, resolveTranslation, selectionModeFor, selfBreadcrumb };
+export type { AttributeGroup, AttributeOverlay, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, EvaluableAttribute, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryResult, RefreshOverlay, RefreshedOption, RetryActionPayload, RetryActionResult, RuleFailure, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };

package/types/mintplayer-ng-spark-pipes.d.ts

@@ -70,8 +70,16 @@ declare class ReferenceChipsPipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<ReferenceChipsPipe, "referenceChips", true>;
 }
 
+/**
+ * Maps a program unit to the router commands that open it. Type comparisons are exact: the
+ * server's loader canonicalizes `type` casing, so tolerating variants here would only mask a
+ * server that stopped doing so.
+ *
+ * Returns null for a `url` unit — an external address is an `<a href>`, not a router link; the
+ * component rendering the menu owns that branch.
+ */
 declare class RouterLinkPipe implements PipeTransform {
-    transform(unit: ProgramUnit): string[];
+    transform(unit: ProgramUnit): string[] | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<RouterLinkPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<RouterLinkPipe, "routerLink", true>;
 }

package/types/mintplayer-ng-spark-po-form.d.ts

@@ -4,10 +4,58 @@ import { CdkDragDrop } from '@angular/cdk/drag-drop';
 import { Color } from '@mintplayer/ng-bootstrap';
 import { InMemoryTreeSelectProvider, TreeNode } from '@mintplayer/ng-bootstrap/tree-select';
 import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
-import { EntityType, ValidationError, PersistentObject, LookupReference, EntityAttributeDefinition, EntityPermissions, ELookupDisplayType, EReferenceDisplayType, AttributeTab, AttributeGroup, LookupReferenceValue } from '@mintplayer/ng-spark/models';
+import { PersistentObject, EntityType, ValidationError, RefreshOverlay, LookupReference, EntityAttributeDefinition, EntityPermissions, ELookupDisplayType, EReferenceDisplayType, AttributeTab, AttributeGroup, LookupReferenceValue, RuleFailure } from '@mintplayer/ng-spark/models';
 import { DatatableSettings } from '@mintplayer/ng-bootstrap/datatable';
 import { PaginationResponse } from '@mintplayer/pagination';
 
+/** What the coordinator needs from its host, so it can be tested without mounting a form. */
+interface RefreshCoordinatorHost {
+    /** POSTs the object and resolves with the reshaped one. */
+    send(triggeredBy: string): Promise<PersistentObject>;
+    /** Values as they are right now — read at dispatch time to snapshot what is being sent. */
+    currentValues(): Record<string, any>;
+    /** Applies a settled response. Not called for a superseded one. */
+    apply(response: PersistentObject, sent: Record<string, any>): void;
+    /** Surfaced so the host can show a busy affordance. Never used to disable fields. */
+    setBusy(busy: boolean): void;
+}
+/**
+ * Serializes refreshes for **one** form instance and drops superseded ones.
+ *
+ * Per-instance rather than a service, deliberately. The retry-action modal renders its own
+ * `spark-po-form`, and a refresh can carry a retry operation — so a refresh can open a modal
+ * containing a form whose own attributes may trigger refreshes. A shared coordinator would let the
+ * nested form resolve or supersede the outer form's pending request. The same applies to the
+ * recursive `spark-po-form` used for modal AsDetail editing.
+ *
+ * Cancellation is not available: the service layer is promise-based (`firstValueFrom`), so a stale
+ * response *will* arrive. It is discarded by sequence number rather than prevented.
+ */
+declare class RefreshCoordinator {
+    private readonly host;
+    private queue;
+    private sequence;
+    private settled;
+    private pending;
+    constructor(host: RefreshCoordinatorHost);
+    /** Whether a refresh is in flight. */
+    get isRefreshing(): boolean;
+    /**
+     * Marks `attributeName` as needing a refresh without sending one — for free-text editors, which
+     * would otherwise issue a request per keystroke. Flushed by {@link blur} or {@link flush}.
+     */
+    markPending(attributeName: string): void;
+    /** Sends a pending refresh for `attributeName`, if one was marked. */
+    blur(attributeName: string): Promise<void>;
+    /**
+     * Sends every refresh still marked pending. Called before save, so a value typed and never blurred
+     * — the user tabbing straight to the save button — is still reflected before the object goes.
+     */
+    flush(): Promise<void>;
+    /** Sends a refresh immediately — discrete editors, where every change is a committed one. */
+    trigger(attributeName: string): Promise<void>;
+}
+
 declare class SparkPoFormComponent {
     private readonly sparkService;
     private readonly translations;
@@ -21,6 +69,23 @@ declare class SparkPoFormComponent {
     parentType: _angular_core.InputSignal<string | undefined>;
     save: _angular_core.OutputEmitterRef<void>;
     cancel: _angular_core.OutputEmitterRef<void>;
+    /**
+     * The type id to refresh against. Absent means refresh is unavailable — the form still renders and
+     * edits normally, so a host that has not opted in loses nothing.
+     */
+    objectTypeId: _angular_core.InputSignal<string | undefined>;
+    /** The id of the object being edited; absent for a create. */
+    objectId: _angular_core.InputSignal<string | undefined>;
+    /**
+     * What the last refresh changed about each attribute's presentation, keyed by attribute name.
+     *
+     * Deliberately NOT folded back into `entityType`. All option loading hangs off one effect keyed on
+     * `entityType` identity and `SparkService` caches nothing, so re-setting it would re-issue every
+     * reference query and lookup fetch on every refresh; mutating it in place would not re-render at
+     * all.
+     */
+    refreshOverlay: _angular_core.WritableSignal<RefreshOverlay>;
+    isRefreshing: _angular_core.WritableSignal<boolean>;
     colors: typeof Color;
     referenceOptions: _angular_core.WritableSignal<Record<string, PersistentObject[]>>;
     referenceProviders: _angular_core.WritableSignal<Record<string, InMemoryTreeSelectProvider>>;
@@ -35,6 +100,15 @@ declare class SparkPoFormComponent {
     asDetailReferenceOptions: _angular_core.WritableSignal<Record<string, Record<string, PersistentObject[]>>>;
     ELookupDisplayType: typeof ELookupDisplayType;
     EReferenceDisplayType: typeof EReferenceDisplayType;
+    /**
+     * Every attribute this form could ever need option data for — including ones the model hides,
+     * because a refresh may reveal them.
+     *
+     * Read by the option-loading effect, and deliberately independent of `refreshOverlay`: the loaders
+     * read this synchronously, so an overlay dependency here would make every refresh re-issue every
+     * reference query and lookup fetch. That is the whole reason the overlay is a separate signal.
+     */
+    optionSourceAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
     editableAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
     private static readonly DEFAULT_TAB;
     ungroupedAttributes: _angular_core.Signal<EntityAttributeDefinition[]>;
@@ -66,12 +140,66 @@ declare class SparkPoFormComponent {
     /** Edit-renderer for an inline AsDetail cell (so inline editing honors `col.renderer`, not just display). */
     getAsDetailCellEditRenderer(col: EntityAttributeDefinition): Type<any> | null;
     getAsDetailCellEditRendererInputs(component: Type<any>, row: Record<string, any>, col: EntityAttributeDefinition): Record<string, any>;
+    /**
+     * Rules evaluated in the browser, against the *effective* metadata — so a rule a refresh hook
+     * imposed is visible before the round-trip rather than only after the server rejects the save.
+     */
+    clientRuleFailures: _angular_core.Signal<RuleFailure[]>;
     hasError(attrName: string): boolean;
     private inlineErrorPath;
     hasInlineError(attr: EntityAttributeDefinition, rowIndex: number, col: EntityAttributeDefinition): boolean;
     inlineErrorMessage(attr: EntityAttributeDefinition, rowIndex: number, col: EntityAttributeDefinition): string | null;
-    onFieldChange(): void;
-    onSave(): void;
+    /**
+     * The single funnel every scalar / boolean / inline-cell edit passes through.
+     *
+     * `attr` is optional only so the AsDetail modal's recursive form, which has no trigger context,
+     * can still call it. A caller that knows which attribute changed should always say so — without it
+     * no refresh can fire.
+     */
+    onFieldChange(attr?: EntityAttributeDefinition): void;
+    /**
+     * A trigger inside an AsDetail row. Addressed by the same `{attr}[{index}].{col}` path the inline
+     * validation errors already use, so the server can tell which row asked without a second
+     * addressing scheme being invented for it.
+     */
+    onInlineCellChange(attr: EntityAttributeDefinition, rowIndex: number, col: EntityAttributeDefinition): void;
+    /** Which detail row the in-flight refresh belongs to, if any. */
+    private pendingNestedTrigger;
+    /**
+     * Applies a refresh that ran against a detail row: the row's own values, and the column metadata
+     * for the grid it lives in.
+     *
+     * The column metadata comes from `asDetailTypes` — a different signal from `entityType` — which is
+     * why a nested response cannot go through the top-level overlay.
+     *
+     * ⚠️ The row array is mutated in place rather than replaced. Rows are tracked by index, so handing
+     * the template a new array destroys and rebuilds every row's DOM and takes focus with it, mid-edit.
+     */
+    private applyNestedResponse;
+    onInlineCellBlur(attr: EntityAttributeDefinition, rowIndex: number, col: EntityAttributeDefinition): void;
+    /** Blur handler for free-text editors — sends the refresh their keystrokes only marked pending. */
+    onFieldBlur(attr: EntityAttributeDefinition): void;
+    private noteChange;
+    private canRefresh;
+    /**
+     * Per-instance, never a service: the retry-action modal renders its own `spark-po-form`, and a
+     * refresh may carry a retry operation — so a refresh can open a modal containing a form that
+     * refreshes. A shared coordinator would let the nested form supersede this one's request.
+     */
+    protected readonly refreshCoordinator: RefreshCoordinator;
+    private buildRefreshPayload;
+    /**
+     * Folds replaced option lists into the signals the editors already read, so a refreshed dropdown
+     * renders through the same path as a loaded one.
+     *
+     * `undefined` means the hook did not touch this attribute's options and the loaded set stands; an
+     * empty array means it deliberately left none. Collapsing the two would blank every dropdown the
+     * hook never mentioned.
+     */
+    private applyRefreshedOptions;
+    /** Sends anything still pending, so a typed-but-never-blurred trigger is reflected before save. */
+    flushPendingRefresh(): Promise<void>;
+    onSave(): Promise<void>;
     onCancel(): void;
     openAsDetailEditor(attr: EntityAttributeDefinition): void;
     saveAsDetailObject(): void;
@@ -82,7 +210,7 @@ declare class SparkPoFormComponent {
     removeArrayItem(attr: EntityAttributeDefinition, index: number): void;
     onAsDetailReorder(attr: EntityAttributeDefinition, event: CdkDragDrop<Record<string, any>[]>): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkPoFormComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkPoFormComponent, "spark-po-form", never, { "entityType": { "alias": "entityType"; "required": false; "isSignal": true; }; "formData": { "alias": "formData"; "required": false; "isSignal": true; }; "validationErrors": { "alias": "validationErrors"; "required": false; "isSignal": true; }; "showButtons": { "alias": "showButtons"; "required": false; "isSignal": true; }; "isSaving": { "alias": "isSaving"; "required": false; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; }, { "formData": "formDataChange"; "save": "save"; "cancel": "cancel"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkPoFormComponent, "spark-po-form", never, { "entityType": { "alias": "entityType"; "required": false; "isSignal": true; }; "formData": { "alias": "formData"; "required": false; "isSignal": true; }; "validationErrors": { "alias": "validationErrors"; "required": false; "isSignal": true; }; "showButtons": { "alias": "showButtons"; "required": false; "isSignal": true; }; "isSaving": { "alias": "isSaving"; "required": false; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "objectTypeId": { "alias": "objectTypeId"; "required": false; "isSignal": true; }; "objectId": { "alias": "objectId"; "required": false; "isSignal": true; }; }, { "formData": "formDataChange"; "save": "save"; "cancel": "cancel"; }, never, never, true, never>;
 }
 
 /**

package/types/mintplayer-ng-spark-services.d.ts

@@ -71,6 +71,16 @@ declare class SparkService {
     get(type: string, id: string): Promise<PersistentObject>;
     create(type: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
     update(type: string, id: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
+    /**
+     * Asks the server to reshape an in-progress object after `triggeredBy`'s value changed.
+     *
+     * Writes nothing, but goes through the envelope like every other mutating call: a refresh may
+     * legitimately emit notifications, and may open the retry-action prompt.
+     *
+     * `triggeredBy` is the attribute's name. For a trigger inside an AsDetail row it is the same
+     * path form the inline validation errors use — `Jobs[2].ProfessionId`.
+     */
+    refresh(type: string, data: Partial<PersistentObject>, triggeredBy: string): Promise<PersistentObject>;
     delete(type: string, id: string): Promise<void>;
     getCustomActions(objectTypeId: string): Promise<CustomActionDefinition[]>;
     executeCustomAction(objectTypeId: string, actionName: string, parent?: PersistentObject, selectedItems?: PersistentObject[]): Promise<void>;

package/types/mintplayer-ng-spark-shell.d.ts

@@ -0,0 +1,242 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
+import { BsShellState } from '@mintplayer/ng-bootstrap/shell';
+import { Breakpoint } from '@mintplayer/ng-bootstrap';
+import { ShellStateChangeEventDetail } from '@mintplayer/web-components/shell';
+import { ProgramUnitGroup } from '@mintplayer/ng-spark/models';
+import { SparkLanguageService } from '@mintplayer/ng-spark/services';
+
+/**
+ * Region slots for `<spark-shell>`.
+ *
+ * Each directive marks a template that REPLACES one region of the shell chrome (or fills an
+ * empty one). An omitted slot is not an empty slot: the shell renders its default — the toggler,
+ * the language selector, the title heading — so a host that supplies nothing still gets a
+ * complete working shell, and a host that supplies one slot leaves the rest alone.
+ *
+ * The menu itself is deliberately NOT a slot. Navigation is sourced entirely from
+ * `programUnits.json` through the rights-filtered `/spark/program-units` endpoint and re-fetched
+ * on sign-in/out; a host that finds itself writing unit anchors in a slot should be adding units
+ * to `programUnits.json` instead. Slots exist for the content AROUND the menu: an auth bar, a
+ * user chip, branding, a one-off extra link, an alert strip above the routed content.
+ *
+ * Naming follows the house convention (prefix, component, slot — see `*sparkQueryIcon` in
+ * `@mintplayer/ng-spark/grid`): `sparkShell` + region. Every slot also exists as a `TemplateRef`
+ * input on `SparkShellComponent` for hosts that cannot use content projection.
+ *
+ * ```html
+ * <spark-shell title="My App">
+ *   <spark-auth-bar *sparkShellTopbarEnd />
+ *   <div *sparkShellSidebarTop>
+ *     <a routerLink="/github-projects" class="nav-link">GitHub projects</a>
+ *   </div>
+ *   <router-outlet />
+ * </spark-shell>
+ * ```
+ */
+/** Topbar, leading edge. Default: a `bs-navbar-toggler` mirroring the shell's open state. */
+declare class SparkShellTopbarStartDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellTopbarStartDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellTopbarStartDirective, "[sparkShellTopbarStart]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Topbar, trailing edge. Default: the language selector (which hides itself when the app has
+ * one language). This is where an auth bar goes — the shell cannot ship one itself, since
+ * `@mintplayer/ng-spark` does not (and must not) depend on `@mintplayer/ng-spark-auth`.
+ */
+declare class SparkShellTopbarEndDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellTopbarEndDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellTopbarEndDirective, "[sparkShellTopbarEnd]", never, {}, {}, never, never, true, never>;
+}
+/** Sidebar, above everything. Default: `<h5>{{ title }}</h5>`. */
+declare class SparkShellSidebarHeaderDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellSidebarHeaderDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellSidebarHeaderDirective, "[sparkShellSidebarHeader]", never, {}, {}, never, never, true, never>;
+}
+/** Sidebar, between the header and the program-units menu. No default. */
+declare class SparkShellSidebarTopDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellSidebarTopDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellSidebarTopDirective, "[sparkShellSidebarTop]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * An extra accordion tab in the sidebar menu, rendered after the generated program-unit groups
+ * and sharing their single-open behavior.
+ *
+ * A tab is contributed as DATA (header + body template), not as markup, and that is load-bearing:
+ * `bs-accordion` discovers its tabs with an Angular content query, which matches by declaration
+ * view, so a `<bs-accordion-tab>` written in a host's template and inserted into the library's
+ * accordion is never registered — it would land at index -1, get no hoisted header and no slot.
+ * Declaring a second `<bs-accordion>` instead is what puts the tab in its own exclusivity group:
+ * `mp-accordion` enforces single-open per element, over children it owns and over
+ * `<details name>`, whose grouping cannot cross a shadow root. So the tab element must be created
+ * by the menu itself, from what this directive carries.
+ *
+ * ```html
+ * <ng-container *sparkShellTab="'Component demos'; icon: 'palette'">
+ *   <a routerLink="/query-slots" routerLinkActive="active" class="nav-link">Query card slots</a>
+ * </ng-container>
+ * ```
+ *
+ * Navigation still belongs in `programUnits.json` — this is for pages the model cannot describe
+ * (client-side demos, external tools). For sidebar content that is NOT an accordion tab, use
+ * `*sparkShellSidebarTop` or `*sparkShellSidebarFooter`.
+ */
+declare class SparkShellTabDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    /** The tab's header label. */
+    readonly header: _angular_core.InputSignal<string>;
+    /** Bootstrap icon name for the header, as in `programUnits.json`. Defaults to a folder. */
+    readonly icon: _angular_core.InputSignal<string | undefined>;
+    /** Replaces the icon+label header entirely, for a header that needs its own markup. */
+    readonly headerTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellTabDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellTabDirective, "[sparkShellTab]", never, { "header": { "alias": "sparkShellTab"; "required": true; "isSignal": true; }; "icon": { "alias": "sparkShellTabIcon"; "required": false; "isSignal": true; }; "headerTemplate": { "alias": "sparkShellTabHeader"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * A sidebar accordion tab in the shape the menu renders it. Hosts normally contribute tabs with
+ * `*sparkShellTab`; this is the same thing as data, for a host that computes its tabs.
+ */
+interface SparkSidebarTab {
+    readonly header: string;
+    readonly icon?: string;
+    readonly headerTemplate?: TemplateRef<unknown> | null;
+    readonly content: TemplateRef<unknown>;
+}
+/** Sidebar, at the very bottom. No default. */
+declare class SparkShellSidebarFooterDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellSidebarFooterDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellSidebarFooterDirective, "[sparkShellSidebarFooter]", never, {}, {}, never, never, true, never>;
+}
+/** Main region, above the projected content (the host's `<router-outlet>`). No default. */
+declare class SparkShellMainHeaderDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellMainHeaderDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellMainHeaderDirective, "[sparkShellMainHeader]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * The application frame: topbar + sidebar + main, wrapping ng-bootstrap's `bs-shell` (whose
+ * `mp-shell` web component owns ALL responsive behavior — breakpoints, the overlay drawer,
+ * dismiss-on-navigate — in CSS; nothing here re-derives a pixel width). The sidebar renders the
+ * server-driven program-units menu; the host projects its `<router-outlet>` as the default
+ * content and customizes the chrome through the `*sparkShell*` slots (see `spark-shell-slots.ts`
+ * for the doctrine: an omitted slot renders its default, and the menu itself is never a slot).
+ *
+ * ```html
+ * <spark-shell title="My App">
+ *   <spark-auth-bar *sparkShellTopbarEnd />
+ *   <router-outlet />
+ * </spark-shell>
+ * ```
+ *
+ * The one piece of state the shell keeps is the toggler↔drawer mirror: the built-in hamburger is
+ * hidden (`::part(hamburger)`) in favor of a `bs-navbar-toggler` in the topbar, so the shell
+ * listens to `statechange` to keep the toggler's icon truthful in `auto` mode and only forces
+ * `show`/`hide` on explicit toggles.
+ *
+ * Theming: the chrome colors are CSS custom properties with the classic dark-sidebar defaults —
+ * `--spark-shell-topbar-bg`, `--spark-shell-sidebar-bg`, `--spark-shell-main-bg` — overridable on
+ * the `<spark-shell>` element. `sidebarTheme` flips the sidebar's `data-bs-theme` (which is what
+ * recolors the accordion internals across the shadow boundary) together with its default palette.
+ */
+declare class SparkShellComponent {
+    /** The sidebar heading. Ignored when a `*sparkShellSidebarHeader` slot is supplied. */
+    readonly title: _angular_core.InputSignal<string>;
+    /** Forwarded to `bs-shell`: below it the sidebar is an overlay drawer. */
+    readonly breakpoint: _angular_core.InputSignal<Breakpoint>;
+    /**
+     * `data-bs-theme` for the sidebar — what flips the accordion's shadow-DOM internals between
+     * palettes — plus the matching default background. `null` sets no theme (inherit the page's).
+     */
+    readonly sidebarTheme: _angular_core.InputSignal<"dark" | "light" | null>;
+    /** Forwarded to the menu: any changed value re-fetches the program units. */
+    readonly reloadToken: _angular_core.InputSignal<unknown>;
+    /** Extra sidebar tabs as data, for hosts that compute them; `*sparkShellTab` is the usual way. */
+    readonly sidebarTabs: _angular_core.InputSignal<readonly SparkSidebarTab[]>;
+    readonly topbarStartTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    readonly topbarEndTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    readonly sidebarHeaderTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    readonly sidebarTopTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    readonly sidebarFooterTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    readonly mainHeaderTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    private readonly topbarStartSlot;
+    private readonly topbarEndSlot;
+    private readonly sidebarHeaderSlot;
+    private readonly sidebarTopSlot;
+    private readonly sidebarFooterSlot;
+    private readonly mainHeaderSlot;
+    protected readonly topbarStartTpl: _angular_core.Signal<TemplateRef<unknown> | null>;
+    protected readonly topbarEndTpl: _angular_core.Signal<TemplateRef<unknown> | null>;
+    protected readonly sidebarHeaderTpl: _angular_core.Signal<TemplateRef<unknown> | null>;
+    protected readonly sidebarTopTpl: _angular_core.Signal<TemplateRef<unknown> | null>;
+    protected readonly sidebarFooterTpl: _angular_core.Signal<TemplateRef<unknown> | null>;
+    protected readonly mainHeaderTpl: _angular_core.Signal<TemplateRef<unknown> | null>;
+    /**
+     * Extra accordion tabs, forwarded to the menu so IT creates the `<bs-accordion-tab>` elements —
+     * the only way they share the generated groups' single-open behavior (see
+     * `SparkShellTabDirective`). Data-supplied tabs come first, then projected ones in declaration
+     * order.
+     */
+    private readonly tabSlots;
+    protected readonly tabs: _angular_core.Signal<readonly SparkSidebarTab[]>;
+    protected readonly shellState: _angular_core.WritableSignal<BsShellState>;
+    protected readonly isSidebarVisible: _angular_core.WritableSignal<boolean>;
+    protected toggleSidebar(open: boolean): void;
+    protected onShellToggle(detail: ShellStateChangeEventDetail): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkShellComponent, "spark-shell", never, { "title": { "alias": "title"; "required": false; "isSignal": true; }; "breakpoint": { "alias": "breakpoint"; "required": false; "isSignal": true; }; "sidebarTheme": { "alias": "sidebarTheme"; "required": false; "isSignal": true; }; "reloadToken": { "alias": "reloadToken"; "required": false; "isSignal": true; }; "sidebarTabs": { "alias": "sidebarTabs"; "required": false; "isSignal": true; }; "topbarStartTemplate": { "alias": "topbarStartTemplate"; "required": false; "isSignal": true; }; "topbarEndTemplate": { "alias": "topbarEndTemplate"; "required": false; "isSignal": true; }; "sidebarHeaderTemplate": { "alias": "sidebarHeaderTemplate"; "required": false; "isSignal": true; }; "sidebarTopTemplate": { "alias": "sidebarTopTemplate"; "required": false; "isSignal": true; }; "sidebarFooterTemplate": { "alias": "sidebarFooterTemplate"; "required": false; "isSignal": true; }; "mainHeaderTemplate": { "alias": "mainHeaderTemplate"; "required": false; "isSignal": true; }; }, {}, ["topbarStartSlot", "topbarEndSlot", "sidebarHeaderSlot", "sidebarTopSlot", "sidebarFooterSlot", "mainHeaderSlot", "tabSlots"], ["*"], true, never>;
+}
+
+/**
+ * The server-driven navigation menu: an accordion of program-unit groups fetched from
+ * `GET /spark/program-units`, which the server has already filtered to what the caller's rights
+ * allow. Hosts write ZERO router links for navigation — every group, unit, icon, label and link
+ * comes from `programUnits.json`; content around the menu belongs in `<spark-shell>`'s slots,
+ * and a host tempted to hand-write a unit anchor should add a unit to `programUnits.json`
+ * instead.
+ *
+ * Because the response is caller-scoped it must be re-fetched when the caller changes: the
+ * component tracks the optional `SPARK_AUTH_STATE` signal (supplied by ng-spark-auth's
+ * `provideSparkAuth()`, or by the app's own auth stack) and reloads on every change. Without a
+ * provider it fetches once. `reloadToken` is the manual escape hatch (any changed value triggers
+ * a reload), and `reload()` the imperative one.
+ *
+ * Usually rendered by `<spark-shell>`; exported standalone for hosts that own their own layout.
+ */
+declare class SparkProgramUnitsComponent {
+    private readonly sparkService;
+    private readonly authState;
+    /** Any changed value triggers a reload — for apps whose auth state isn't a provided signal. */
+    readonly reloadToken: _angular_core.InputSignal<unknown>;
+    /**
+     * Extra tabs to render after the generated groups, normally forwarded by `<spark-shell>` from
+     * its `*sparkShellTab` directives. They must be rendered by THIS template — see
+     * `SparkShellTabDirective` for why a host-declared `<bs-accordion-tab>` cannot work.
+     */
+    readonly extraTabs: _angular_core.InputSignal<readonly SparkSidebarTab[]>;
+    protected readonly groups: _angular_core.WritableSignal<ProgramUnitGroup[]>;
+    constructor();
+    /** Re-fetches the menu. The response is already rights-filtered per caller. */
+    reload(): Promise<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkProgramUnitsComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkProgramUnitsComponent, "spark-program-units", never, { "reloadToken": { "alias": "reloadToken"; "required": false; "isSignal": true; }; "extraTabs": { "alias": "extraTabs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * The culture switcher: a `bs-select` over `SparkLanguageService`'s languages, persisting the
+ * choice. Renders nothing when the app declares one language (or none), so hosts can include it
+ * unconditionally — `<spark-shell>`'s topbar does exactly that as its trailing default.
+ */
+declare class SparkLanguageSelectorComponent {
+    protected readonly lang: SparkLanguageService;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkLanguageSelectorComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkLanguageSelectorComponent, "spark-language-selector", never, {}, {}, never, never, true, never>;
+}
+
+export { SparkLanguageSelectorComponent, SparkProgramUnitsComponent, SparkShellComponent, SparkShellMainHeaderDirective, SparkShellSidebarFooterDirective, SparkShellSidebarHeaderDirective, SparkShellSidebarTopDirective, SparkShellTabDirective, SparkShellTopbarEndDirective, SparkShellTopbarStartDirective };
+export type { SparkSidebarTab };

package/types/mintplayer-ng-spark.d.ts

@@ -1,4 +1,4 @@
-import { InjectionToken, Provider } from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
 
 interface SparkConfig {
     baseUrl: string;
@@ -6,7 +6,22 @@ interface SparkConfig {
 declare const SPARK_CONFIG: InjectionToken<SparkConfig>;
 declare const defaultSparkConfig: SparkConfig;
 
+/**
+ * A signal that changes whenever the authenticated user changes — the bridge that lets ng-spark
+ * components react to sign-in/out without a dependency on `@mintplayer/ng-spark-auth` (no
+ * dependency exists between the two packages, in either direction, on purpose).
+ *
+ * `@mintplayer/ng-spark-auth`'s `provideSparkAuth()` supplies it from `SparkAuthService.user`;
+ * an app with its own auth stack provides any signal that changes on sign-in/out. Consumers
+ * inject it `{ optional: true }` — absent, auth-sensitive data (the program-units menu) is
+ * fetched once and never re-fetched.
+ *
+ * The signal's VALUE is deliberately opaque (`unknown`): consumers only track it for change,
+ * never read it — what "the user" looks like belongs to the auth package.
+ */
+declare const SPARK_AUTH_STATE: InjectionToken<Signal<unknown>>;
+
 declare function provideSpark(config?: Partial<SparkConfig>): Provider[];
 
-export { SPARK_CONFIG, defaultSparkConfig, provideSpark };
+export { SPARK_AUTH_STATE, SPARK_CONFIG, defaultSparkConfig, provideSpark };
 export type { SparkConfig };