@mintplayer/ng-spark 22.6.0 → 22.9.0

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,21 @@ 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 cell is a single channel: whatever a renderer needs is already on `value` — for a single-child
+ * AsDetail column that is the nested PersistentObject itself, put there by the server so this
+ * matches what {@link rendererValue} falls through to on a detail page. There is nothing to fall
+ * back to, which is why this is deliberately not the same function: keeping them separate is what
+ * stops a renderer silently receiving `undefined` because it was written against the attribute
+ * shape's `object` / `objects` fields, which a row does not carry.
+ */
+declare function cellValue(value: QueryResultItemValue | undefined): any;
 
 /**
  * Contract for detail-page renderers (spark-po-detail).
@@ -38,21 +51,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 +114,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

@@ -50,6 +50,33 @@ declare class SparkShellTopbarEndDirective {
     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>;
@@ -160,18 +187,21 @@ declare class SparkShellComponent {
     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>;
@@ -189,7 +219,7 @@ declare class SparkShellComponent {
     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>;
+    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>;
 }
 
 /**
@@ -238,5 +268,5 @@ declare class SparkLanguageSelectorComponent {
     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 { SparkLanguageSelectorComponent, SparkProgramUnitsComponent, SparkShellComponent, SparkShellMainHeaderDirective, SparkShellSidebarFooterDirective, SparkShellSidebarHeaderDirective, SparkShellSidebarTopDirective, SparkShellTabDirective, SparkShellTopbarActionsDirective, SparkShellTopbarEndDirective, SparkShellTopbarStartDirective };
 export type { SparkSidebarTab };