@mintplayer/ng-spark 22.19.0 → 22.21.0

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

@@ -352,7 +352,26 @@ interface SparkCellColumn {
 /** One column of a query result, sent once rather than repeated on every row. */
 interface QueryColumn extends SparkCellColumn {
     order: number;
-    isSortable?: boolean;
+    /**
+     * Whether the grid offers a sort affordance for this column. Resolved server-side from the query's
+     * override then the attribute, so it arrives already decided.
+     *
+     * This replaced an `isSortable` that carried the server's AsDetail *drag-reorder* flag — a
+     * different concept that was `false` for every scalar column while the grid hard-coded every
+     * header sortable anyway. Neither side read it. The attribute-level `isSortable` on `EntityType`
+     * is the drag-reorder flag and stays.
+     *
+     * Absent means sortable, matching `isVisible`: a server predating the field still draws arrows.
+     */
+    canSort?: boolean;
+    /** Whether the grid draws a filter cell for this column. Absent means filterable. */
+    canFilter?: boolean;
+    /**
+     * Whether this column's distinct values may be listed. When `false` and `canFilter` is true the
+     * panel offers a free-text filter instead of a value list — listing a column's values is a much
+     * stronger disclosure than filtering by one already known.
+     */
+    canListDistincts?: boolean;
     /**
      * Whether the grid draws this column. `false` means the row carries the value but no column is
      * rendered — for a renderer that needs a sibling value (a lock glyph beside a name) without
@@ -429,6 +448,49 @@ declare function valueFor(item: SparkRow | null | undefined, columnName: string)
 declare function isQueryRow(row: SparkRow | null | undefined): row is QueryResultItem;
 /** Whether this row is a full persistent object. Discriminated on elements, as above. */
 declare function isPersistentObject(row: SparkRow | null | undefined): row is PersistentObject;
+/**
+ * One column's value filter (#431): the values a caller picked, or the values they excluded.
+ *
+ * **Values, never labels.** Each entry is the raw stored value — the same `value` the distinct
+ * endpoint returned, never the `label` beside it. A reference column's values are document ids while
+ * its labels are resolved breadcrumb text, and two rows can legitimately render the same text, so
+ * matching on labels would be both wrong and ambiguous.
+ *
+ * `includes` and `excludes` are the two halves of the inverse toggle rather than a flag: the panel
+ * moves values between them. `null` is a real, selectable value meaning "no value"; an empty or
+ * absent array is the absent filter.
+ */
+interface QueryColumnFilter {
+    name: string;
+    includes?: unknown[];
+    excludes?: unknown[];
+}
+/**
+ * One selectable entry in a column's filter panel.
+ *
+ * Structurally identical to the datatable's own `DistinctValue`, deliberately — it is what lets the
+ * HTTP response be handed straight to `[distincts]` with no mapper in between.
+ */
+interface DistinctValue {
+    /** The raw stored value. `null` is a real entry meaning "no value", not an absent one. */
+    value: unknown;
+    /** What the user reads. Never matched on. */
+    label: string;
+}
+/**
+ * A column's distinct values.
+ *
+ * `remaining` is always empty from this server: the datatable snapshots the list when a selection is
+ * first made and derives both buckets itself by diffing. The server answers "what matches now".
+ *
+ * `hasMore` reports that the cap truncated the list, and the panel re-queries only when it is set or
+ * the search term widens — so a dishonest `false` strands a user typing past the cap.
+ */
+interface DistinctValuesResult {
+    matching: DistinctValue[];
+    remaining: DistinctValue[];
+    hasMore: boolean;
+}
 
 interface ProgramUnit {
     id: string;
@@ -882,4 +944,4 @@ interface EvaluableAttribute {
 declare function evaluateRules(attr: EvaluableAttribute, value: any): RuleFailure[];
 
 export { AS_DETAIL_BREADCRUMBS_KEY, AS_DETAIL_ORIGINAL_DATES_KEY, AS_DETAIL_ROW_KEY, AS_DETAIL_SELF_BREADCRUMB_KEY, ELookupDisplayType, EReferenceDisplayType, ShowedOn, applyOverlay, currentLanguage, dictToNestedPo, evaluateRules, filterQueryActions, fromDateInput, fromDateInputValue, fromDateTimeLocalInput, hasShowedOnFlag, isDateDataType, isPersistentObject, isQueryRow, isReservedAsDetailKey, mergeRefreshValues, nestedPoToDict, nestedPoToDisplayRow, overlayFromResponse, parseSelectionRule, parseWireDate, resolveTranslation, resolvedBreadcrumb, selectionModeFor, selfBreadcrumb, toDateInput, toDateInputValue, toDateTimeLocalInput, valueFor, wireDatesEqual };
-export type { AttributeGroup, AttributeOverlay, AttributeTab, CustomActionDefinition, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, EvaluableAttribute, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryColumn, QueryResult, QueryResultItem, QueryResultItemValue, RefreshOverlay, RefreshedOption, RetryActionPayload, RetryActionResult, RuleFailure, SparkCellColumn, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkRow, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };
+export type { AttributeGroup, AttributeOverlay, AttributeTab, CustomActionDefinition, DistinctValue, DistinctValuesResult, EntityAttributeDefinition, EntityPermissions, EntityType, EntityTypeResolver, EvaluableAttribute, LookupReference, LookupReferenceListItem, LookupReferenceValue, PersistentObject, PersistentObjectAttribute, PersistentObjectPermissions, ProgramUnit, ProgramUnitGroup, ProgramUnitsConfiguration, QueryColumn, QueryColumnFilter, QueryResult, QueryResultItem, QueryResultItemValue, RefreshOverlay, RefreshedOption, RetryActionPayload, RetryActionResult, RuleFailure, SparkCellColumn, SparkQuery, SparkQueryRenderMode, SparkQuerySortColumn, SparkRow, SparkSelectionMode, StreamingErrorMessage, StreamingMessage, StreamingPatchItem, StreamingPatchMessage, StreamingSnapshotMessage, TranslatedString, ValidationError, ValidationErrorResponse, ValidationRule };

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

@@ -101,6 +101,19 @@ interface SparkAttributeRendererRegistration {
     columnComponent?: Type<any> | null;
     /** Optional component for create/edit forms. Must implement SparkAttributeEditRenderer. When omitted, the default input is used. */
     editComponent?: Type<any>;
+    /**
+     * Relabels this column's values in a filter panel (#431).
+     *
+     * A renderer is a component that paints arbitrary DOM, and a distinct value has no row, so it
+     * cannot be instantiated to produce text for a filter list. The label therefore defaults to the
+     * server-computed cell text: a status rendered as a coloured pill lists `Active`, a rating
+     * rendered as stars lists `3`. This is the escape for when that is too raw — a value stored as
+     * `2` whose cell reads "High priority".
+     *
+     * ⚠️ A **pure function**: no DOM, no component instantiation, no row context. There is no row to
+     * give it, which is the whole reason the renderer itself cannot be used here.
+     */
+    filterLabel?: (value: unknown) => string;
 }
 declare const SPARK_ATTRIBUTE_RENDERERS: InjectionToken<SparkAttributeRendererRegistration[]>;
 /**

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

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { RetryActionPayload, RetryActionResult, TranslatedString, StreamingMessage, EntityType, EntityPermissions, SparkQuery, QueryResult, ProgramUnitsConfiguration, PersistentObject, CustomActionDefinition, LookupReferenceListItem, LookupReference, LookupReferenceValue } from '@mintplayer/ng-spark/models';
+import { RetryActionPayload, RetryActionResult, TranslatedString, StreamingMessage, QueryColumnFilter, EntityType, EntityPermissions, SparkQuery, QueryResult, DistinctValuesResult, ProgramUnitsConfiguration, PersistentObject, CustomActionDefinition, LookupReferenceListItem, LookupReference, LookupReferenceValue } from '@mintplayer/ng-spark/models';
 import { Observable } from 'rxjs';
 import { SortColumn } from '@mintplayer/pagination';
 import { SafeHtml } from '@angular/platform-browser';
@@ -96,14 +96,23 @@ declare class SparkService {
      * lifetime; the service is scoped to the app, so a permission change lands on the next load.
      */
     getQueryByName(name: string): Promise<SparkQuery | undefined>;
-    executeQuery(queryId: string, options?: {
-        sortColumns?: SortColumn[];
+    executeQuery(queryId: string, options?: ExecuteQueryOptions): Promise<QueryResult>;
+    /**
+     * The distinct values behind one column's filter panel (#431).
+     *
+     * `columns` carries the OTHER columns' current filters, so the values returned are the ones still
+     * reachable — offering a value that empties the grid the moment it is picked is worse than
+     * omitting it.
+     *
+     * An empty result means either "nothing matches" or "you may not enumerate this column". The two
+     * are deliberately indistinguishable, so there is nothing for a caller to branch on.
+     */
+    getDistinctValues(queryId: string, column: string, options?: {
+        search?: string;
+        columns?: QueryColumnFilter[];
         parentId?: string;
         parentType?: string;
-        skip?: number;
-        take?: number;
-        search?: string;
-    }): Promise<QueryResult>;
+    }): Promise<DistinctValuesResult>;
     /**
      * Runs a query identified by name.
      *
@@ -112,14 +121,7 @@ declare class SparkService {
      * that the list was cut. A picker that omits the option you are looking for, and says nothing, is
      * worse than one that fails.
      */
-    executeQueryByName(queryName: string, options?: {
-        parentId?: string;
-        parentType?: string;
-        skip?: number;
-        take?: number;
-        search?: string;
-        sortColumns?: SortColumn[];
-    }): Promise<QueryResult>;
+    executeQueryByName(queryName: string, options?: ExecuteQueryOptions): Promise<QueryResult>;
     getProgramUnits(): Promise<ProgramUnitsConfiguration>;
     get(type: string, id: string): Promise<PersistentObject>;
     create(type: string, data: Partial<PersistentObject>): Promise<PersistentObject>;
@@ -196,6 +198,23 @@ declare class SparkService {
     static ɵfac: i0.ɵɵFactoryDeclaration<SparkService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<SparkService>;
 }
+/**
+ * The options every query execution takes.
+ *
+ * Extracted because `executeQueryByName` forwards to `executeQuery`, and while both spelled their
+ * options as separate inline literals a field added to one silently failed to forward from the
+ * other — which is how skip/take/search were once dropped for every reference picker.
+ */
+interface ExecuteQueryOptions {
+    sortColumns?: SortColumn[];
+    parentId?: string;
+    parentType?: string;
+    skip?: number;
+    take?: number;
+    search?: string;
+    /** Per-column value filters (#431). Columns AND together; values within a column OR. */
+    columns?: QueryColumnFilter[];
+}
 
 /**
  * R2-M12: SVG icon registry. The registry no longer accepts a raw string —
@@ -319,4 +338,4 @@ declare const sparkTimezoneInterceptor: HttpInterceptorFn;
 declare function withSparkTimezone(): HttpFeature<HttpFeatureKind>[];
 
 export { RetryActionService, SPARK_TIMEZONE_HEADER, SparkIconRegistry, SparkLanguageService, SparkQueryActionsService, SparkService, SparkStreamingService, resolveBrowserTimeZone, sparkTimezoneInterceptor, withSparkTimezone };
-export type { DeleteRowOptions, NewObjectOptions };
+export type { DeleteRowOptions, ExecuteQueryOptions, NewObjectOptions };