@mintplayer/ng-spark 22.5.0 → 22.8.0

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

@@ -1,5 +1,5 @@
 import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
-import { PersistentObject, CustomActionDefinition } from '@mintplayer/ng-spark/models';
+import { QueryResultItem, CustomActionDefinition, QueryColumn } from '@mintplayer/ng-spark/models';
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
 import { Color } from '@mintplayer/ng-bootstrap';
@@ -31,7 +31,12 @@ declare class SparkQueryListComponent {
     protected readonly lang: SparkLanguageService;
     extraActionsTemplate: _angular_core.InputSignal<TemplateRef<void> | null>;
     showCustomActions: _angular_core.InputSignal<boolean>;
-    rowClicked: _angular_core.OutputEmitterRef<PersistentObject>;
+    /**
+     * Forwarded to the grid, so a query PAGE can replace its row links — the same reason the card
+     * forwards it. Without this the escape hatch existed only for a directly-embedded grid.
+     */
+    rowRoute: _angular_core.InputSignal<((row: QueryResultItem) => unknown[] | null) | null>;
+    rowClicked: _angular_core.OutputEmitterRef<QueryResultItem>;
     createClicked: _angular_core.OutputEmitterRef<void>;
     customActionExecuted: _angular_core.OutputEmitterRef<{
         action: CustomActionDefinition;
@@ -59,6 +64,8 @@ declare class SparkQueryListComponent {
     protected isActionEnabled(action: CustomActionDefinition): boolean;
     isStreaming: _angular_core.WritableSignal<boolean>;
     private streamingSub;
+    /** Columns as sent with the stream's snapshot; empty until it arrives. */
+    protected readonly streamColumns: _angular_core.WritableSignal<QueryColumn[]>;
     private readonly allItems;
     private readonly streamItems;
     /**
@@ -67,7 +74,7 @@ declare class SparkQueryListComponent {
      * Null for a normal query — an empty array would read as "here are no rows" and suppress the
      * fetch entirely.
      */
-    protected readonly gridData: _angular_core.Signal<PersistentObject[] | null>;
+    protected readonly gridData: _angular_core.Signal<QueryResultItem[] | null>;
     constructor();
     private onParamsChange;
     /**
@@ -84,7 +91,7 @@ declare class SparkQueryListComponent {
     private handleStreamingMessage;
     private applyFilter;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryListComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryListComponent, "spark-query-list", never, { "extraActionsTemplate": { "alias": "extraActionsTemplate"; "required": false; "isSignal": true; }; "showCustomActions": { "alias": "showCustomActions"; "required": false; "isSignal": true; }; }, { "rowClicked": "rowClicked"; "createClicked": "createClicked"; "customActionExecuted": "customActionExecuted"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryListComponent, "spark-query-list", never, { "extraActionsTemplate": { "alias": "extraActionsTemplate"; "required": false; "isSignal": true; }; "showCustomActions": { "alias": "showCustomActions"; "required": false; "isSignal": true; }; "rowRoute": { "alias": "rowRoute"; "required": false; "isSignal": true; }; }, { "rowClicked": "rowClicked"; "createClicked": "createClicked"; "customActionExecuted": "customActionExecuted"; }, never, never, true, never>;
 }
 
 export { SparkQueryListComponent };

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

@@ -1,5 +1,5 @@
 import { Type, InputSignal, InjectionToken, Provider } from '@angular/core';
-import { PersistentObjectAttribute, EntityAttributeDefinition, PersistentObject } from '@mintplayer/ng-spark/models';
+import { QueryResultItemValue, PersistentObjectAttribute, SparkCellColumn, QueryResultItem, EntityAttributeDefinition, PersistentObject } from '@mintplayer/ng-spark/models';
 
 /**
  * Drops entries the component doesn't declare, so every contract member is
@@ -10,8 +10,19 @@ declare function withDeclaredInputs(component: Type<any>, inputs: Record<string,
  * The renderer-facing value of an attribute: the flat value, or for AsDetail
  * attributes (whose flat value the server nulls on purpose) the nested
  * PersistentObject (single) / PersistentObject[] (array).
+ *
+ * Used by the detail and edit paths, which still work in attributes.
  */
 declare function rendererValue(attr: PersistentObjectAttribute | undefined): any;
+/**
+ * The renderer-facing value of a query-result cell.
+ *
+ * A grid row carries no nested objects to fall back to — a projection is flat by construction —
+ * so this is deliberately not the same function as {@link rendererValue}. Keeping them separate
+ * is what stops a renderer silently receiving `undefined` because it was written against the
+ * attribute shape.
+ */
+declare function cellValue(value: QueryResultItemValue | undefined): any;
 
 /**
  * Contract for detail-page renderers (spark-po-detail).
@@ -38,21 +49,28 @@ interface SparkAttributeDetailRenderer {
  */
 interface SparkAttributeColumnRenderer {
     /**
-     * The current attribute value. For an AsDetail attribute this is the nested
-     * PersistentObject (single) / PersistentObject[] (array) in query-list and
-     * sub-query grids, and the flattened value in AsDetail sub-table cells.
+     * The cell value. For an AsDetail column this is the nested PersistentObject (single) /
+     * PersistentObject[] (array) in an AsDetail sub-table, and the projected value in a query grid.
      */
     value?: InputSignal<any>;
-    /** The attribute definition metadata */
-    attribute?: InputSignal<EntityAttributeDefinition | undefined>;
+    /**
+     * The column being rendered.
+     *
+     * A query grid supplies a {@link SparkCellColumn} from the result own column metadata; an
+     * AsDetail sub-table supplies its attribute definition, which satisfies the same shape. This
+     * replaced an `attribute` input typed as the definition: a query result no longer carries
+     * attribute metadata per row, so naming it `attribute` would promise something the grid cannot
+     * deliver.
+     */
+    column?: InputSignal<SparkCellColumn | undefined>;
     /** Renderer-specific options from rendererOptions */
     options?: InputSignal<Record<string, any> | undefined>;
     /**
-     * The row this cell belongs to: a PersistentObject in query-list/sub-query
-     * grids, a plain record (possibly including the reserved '__sparkBreadcrumbs'
-     * key) in AsDetail sub-tables. Passed only when declared.
+     * The row this cell belongs to: a {@link QueryResultItem} in a query grid, a plain record
+     * (possibly including the reserved '__sparkBreadcrumbs' key) in AsDetail sub-tables. Passed
+     * only when declared.
      */
-    item?: InputSignal<PersistentObject | Record<string, any> | undefined>;
+    item?: InputSignal<QueryResultItem | Record<string, any> | undefined>;
 }
 /**
  * Contract for edit-form renderers (spark-po-form on create/edit pages).
@@ -94,5 +112,5 @@ declare const SPARK_ATTRIBUTE_RENDERERS: InjectionToken<SparkAttributeRendererRe
  */
 declare function provideSparkAttributeRenderers(renderers: SparkAttributeRendererRegistration[]): Provider;
 
-export { SPARK_ATTRIBUTE_RENDERERS, provideSparkAttributeRenderers, rendererValue, withDeclaredInputs };
+export { SPARK_ATTRIBUTE_RENDERERS, cellValue, provideSparkAttributeRenderers, rendererValue, withDeclaredInputs };
 export type { SparkAttributeColumnRenderer, SparkAttributeDetailRenderer, SparkAttributeEditRenderer, SparkAttributeRendererRegistration };

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

@@ -83,7 +83,20 @@ declare class SparkService {
     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>;
+    /**
+     * @param parent The object of THIS type the action is operating on — the detail-page invocation.
+     * @param selectedItemIds Row ids from a query. Ids, never row objects: a row is a projection.
+     * @param queryParent When invoked from a sub-query, the object whose detail page it was rendered
+     *   on — a DIFFERENT type (the cars listed on a company's page are Cars, the page is a Company).
+     *   Sent as id + type, exactly as the query endpoint names it, and resolved server-side under its
+     *   own type with its own Read gate.
+     * @param queryId The query the selection came from, so the server can re-run it narrowed to those
+     *   ids and hand the action the rows the grid actually had -- index-computed columns included.
+     */
+    executeCustomAction(objectTypeId: string, actionName: string, parent?: PersistentObject, selectedItemIds?: string[], queryParent?: {
+        id: string;
+        type: string;
+    }, queryId?: string): Promise<void>;
     getLookupReferences(): Promise<LookupReferenceListItem[]>;
     getLookupReference(name: string): Promise<LookupReference>;
     addLookupReferenceValue(name: string, value: LookupReferenceValue): Promise<LookupReferenceValue>;
@@ -133,4 +146,60 @@ declare class SparkIconRegistry {
     static ɵprov: i0.ɵɵInjectableDeclaration<SparkIconRegistry>;
 }
 
-export { RetryActionService, SparkIconRegistry, SparkLanguageService, SparkService, SparkStreamingService };
+/**
+ * A query's custom actions, reachable **without the grid that usually renders them**.
+ *
+ * ## Why this exists
+ *
+ * A query's actions were only ever obtainable by rendering `<spark-query-grid>`, which loads the
+ * query, resolves its entity type, fetches the actions and filters them to the ones marked for a
+ * query surface — all privately. A page that wanted the same buttons somewhere else (a toolbar
+ * above the card, the shell's topbar) had three bad options: duplicate the four-step resolution
+ * and let it drift, reach into the grid's internals, or put the button in the wrong place.
+ *
+ * This exposes the resolution itself. The grid keeps rendering the default placement; a host that
+ * wants a different one asks here and renders its own control.
+ *
+ * ## What it does not do
+ *
+ * It does not authorize. `/spark/actions/{type}` returns only the actions this caller may see —
+ * the server filters against `security.json`, and executing re-checks — so nothing here is a gate,
+ * and a host must not treat "the list came back empty" as anything other than a display fact.
+ *
+ * It also does not cache. Actions depend on the caller, and a memo keyed by type id would survive
+ * a sign-out.
+ */
+declare class SparkQueryActionsService {
+    private readonly sparkService;
+    /**
+     * The custom actions of the query named by id or alias, already filtered to those that belong on
+     * a query surface.
+     *
+     * Returns an empty list — rather than throwing — when the query resolves to no entity type,
+     * because a caller rendering a toolbar wants "no buttons", not a broken page.
+     */
+    actionsFor(queryIdOrAlias: string): Promise<CustomActionDefinition[]>;
+    /**
+     * Runs one of those actions. `selectedItemIds` are row ids, exactly as the grid posts them —
+     * the server re-materializes each one through the same load path a detail page uses, so an id
+     * from anywhere is treated as caller input rather than as a verified row.
+     */
+    execute(queryIdOrAlias: string, actionName: string, options?: {
+        parent?: PersistentObject;
+        selectedItemIds?: string[];
+        /** For a sub-query: the object whose detail page it was rendered on. See SparkService. */
+        queryParent?: {
+            id: string;
+            type: string;
+        };
+    }): Promise<void>;
+    /**
+     * The query and the entity type its rows are mapped against — the two-step resolution both
+     * methods need, kept in one place so they cannot disagree about which type an action runs on.
+     */
+    private contextFor;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SparkQueryActionsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SparkQueryActionsService>;
+}
+
+export { RetryActionService, SparkIconRegistry, SparkLanguageService, SparkQueryActionsService, SparkService, SparkStreamingService };

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

@@ -0,0 +1,272 @@
+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>;
+}
+/**
+ * Topbar, trailing edge, **beside** the default chrome rather than instead of it — rendered before
+ * the language selector, which stays.
+ *
+ * ## Why this is not just `*sparkShellTopbarEnd`
+ *
+ * That slot REPLACES the region, which is right for an auth bar (a host taking over the trailing
+ * edge wholesale) and wrong for a page-level action button. A host that only wanted to add a
+ * button had to re-render the language selector itself to keep it — which means importing it,
+ * knowing it hides itself in a single-language app, and keeping that copy in step with the shell.
+ * Every host that did this got it slightly differently.
+ *
+ * Pairs with `SparkQueryActionsService`: that service resolves a query's custom actions without the
+ * grid, and this is where a page-level one goes.
+ *
+ * ```html
+ * <button *sparkShellTopbarActions class="btn btn-primary" (click)="publish()">Publish</button>
+ * ```
+ *
+ * Supplying both slots is allowed and does what it says: `topbarEnd` replaces the default chrome,
+ * and these actions still render ahead of whatever it put there.
+ */
+declare class SparkShellTopbarActionsDirective {
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkShellTopbarActionsDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SparkShellTopbarActionsDirective, "[sparkShellTopbarActions]", 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 topbarActionsTemplate: _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 topbarActionsSlot;
+    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 topbarActionsTpl: _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; }; "topbarActionsTemplate": { "alias": "topbarActionsTemplate"; "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", "topbarActionsSlot", "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, SparkShellTopbarActionsDirective, 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 };