@mintplayer/ng-spark 22.18.0 → 22.20.0

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

@@ -1,4 +1,4 @@
-import { DatatableSettings, BsDatatableFetch } from '@mintplayer/ng-bootstrap/datatable';
+import { DatatableSettings, BsDatatableFetch, DatatableDistincts, FilterChangeDetail } from '@mintplayer/ng-bootstrap/datatable';
 import * as _mintplayer_ng_spark_models from '@mintplayer/ng-spark/models';
 import { SparkQuery, EntityType, EntityAttributeDefinition, SparkCellColumn, QueryResultItem, QueryColumn, LookupReference, CustomActionDefinition, PersistentObject } from '@mintplayer/ng-spark/models';
 import * as _angular_core from '@angular/core';
@@ -46,6 +46,8 @@ declare class SparkGridRenderers {
     private readonly sparkService;
     /** The registered column component for a column, or null to fall back to the default cell. */
     columnComponentFor(column: SparkCellColumn): Type<any> | null;
+    /** The registered filter-label function for a column, or null to use the server-computed text. */
+    filterLabelFor(column: SparkCellColumn): ((value: unknown) => string) | null;
     /**
      * Inputs for a query-grid cell renderer, filtered to what the component actually declares —
      * `NgComponentOutlet` throws on an input the target does not have, which is what lets every
@@ -371,6 +373,66 @@ declare class SparkQueryGridComponent {
      */
     reload(): void;
     private onSearchChanged;
+    /**
+     * Replaces the fetched columns only when they actually differ.
+     *
+     * Columns ship **once per result**, so every page fetch returns an identical set. Assigning it
+     * unconditionally wrote a new array of new objects into the signal each time, re-rendering every
+     * header and re-evaluating every `*bsDatatableColumn` input for no change in content.
+     *
+     * Compared by serialized value rather than by reference: the objects are freshly deserialized from
+     * JSON on every response, so reference equality is always false and would defeat the check. A
+     * dozen small objects per fetch is nothing beside the request that produced them.
+     *
+     * ⚠️ This was written believing it fixed a panel-teardown bug (#431 F7). Measured in a browser: it
+     * does not. The columns were already identical on every fetch, so the guard hits every time and the
+     * teardown had another cause entirely. Kept because avoiding a pointless re-render of every header
+     * on every page is worth having on its own — but it is an optimization, not a fix, and the F7
+     * question remains open.
+     */
+    private setFetchedColumns;
+    /**
+     * The per-column filters currently applied (#431).
+     *
+     * Read inside `makeFetch`'s closure, like `search`, so a change refetches by producing a new fetch
+     * identity rather than by being captured.
+     */
+    private readonly filters;
+    /**
+     * The value source behind every column's panel.
+     *
+     * ⚠️ **Referentially stable, and that is the whole point.** It reads `filters()` when the datatable
+     * *calls* it, not when it is built — so it always sees the current filters while never changing
+     * identity.
+     *
+     * This was a `computed` first, on the reasoning that it had to close over the current filters
+     * because `DistinctsRequest` carries only `{ column, search, signal }`. That was wrong, and the way
+     * it was wrong is worth keeping: a new identity reassigns `[distincts]` on the element, and the
+     * component aborts the in-flight request and bumps a generation counter — so a response already on
+     * its way is discarded as stale and the list renders empty over a perfectly good answer.
+     *
+     * Reading the signal at call time removes the race entirely and is simpler besides.
+     *
+     * The asked-for column's own filter is excluded: a panel must offer the values you could still
+     * pick, not only the ones you already picked.
+     */
+    protected readonly distinctsFn: DatatableDistincts;
+    /**
+     * Translates one filter change into the wire shape and refetches.
+     *
+     * The event always arrives as the `'values'` shape because the panel only ever calls
+     * `ctx.apply(...)`; comparison mode is never declared. `inverse` is a flag on the event and two
+     * arrays on the wire — the translation is this method's whole job.
+     */
+    protected onFilterChange(detail: FilterChangeDetail): void;
+    /**
+     * Back to page 1 and a fresh fetch identity, exactly as a new search term does.
+     *
+     * Both halves matter: the old page number means nothing against a different result set, and the
+     * datatable dedupes reloads by `(page, perPage, sort)` — none of which a filter changes — so
+     * without a new fetch identity the request is silently never made.
+     */
+    private onFilterChanged;
     onCustomAction(action: CustomActionDefinition): Promise<void>;
     private reportError;
     /**
@@ -403,6 +465,8 @@ declare class SparkQueryGridComponent {
      */
     rendererValueFor(item: QueryResultItem, column: QueryColumn): unknown;
     getColumnRendererComponent(column: QueryColumn): Type<any> | null;
+    /** The renderer's optional filter-label override for this column, or null for the server text. */
+    filterLabelFor(column: QueryColumn): ((value: unknown) => string) | null;
     getColumnRendererInputs(component: Type<any>, item: QueryResultItem, column: QueryColumn): Record<string, any>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkQueryGridComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkQueryGridComponent, "spark-query-grid", never, { "queryId": { "alias": "queryId"; "required": true; "isSignal": true; }; "parentId": { "alias": "parentId"; "required": false; "isSignal": true; }; "parentType": { "alias": "parentType"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "search": { "alias": "search"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": false; "isSignal": true; }; "reloadToken": { "alias": "reloadToken"; "required": false; "isSignal": true; }; "settings": { "alias": "settings"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "rowRoute": { "alias": "rowRoute"; "required": false; "isSignal": true; }; }, { "settings": "settingsChange"; "selection": "selectionChange"; "error": "error"; "rowClicked": "rowClicked"; "customActionExecuted": "customActionExecuted"; }, never, never, true, never>;

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-po-edit.d.ts

@@ -28,6 +28,22 @@ declare class SparkPoEditComponent {
     constructor();
     private onParamsChange;
     initFormData(): void;
+    /**
+     * Resolves a nested AsDetail type by CLR name, for rebuilding the nested PO wire shape on save.
+     *
+     * ⚠️ <b>`detailTypes` first, catalogue second.</b> The catalogue from `/spark/types` is
+     * <b>Query-gated</b>, and an AsDetail row type usually has no rights of its own — nobody grants
+     * `Query/GateSettings`, because a gate is edited through the Repository that owns it. So the
+     * catalogue does not contain it, the resolver returned undefined, and the save quietly took the
+     * scalar branch: the attribute went out as a raw dict under `value` instead of a nested PO under
+     * `object`, the server could not map it, and `EntityMapper`'s conversion `catch` swallowed the
+     * failure. The save reported success and wrote nothing.
+     * <para>
+     * `detailTypes` is the parent's own copy of its row types, carried on the type definition for
+     * exactly this reason (#385 fixed the rendering half; this is the save half). It is gated on the
+     * parent's right, which is the right that governs editing the row anyway.
+     * </para>
+     */
     private resolveEntityType;
     /**
      * The attributes this page will read values from when it builds the save.

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

@@ -56,6 +56,17 @@ declare class RefreshCoordinator {
     trigger(attributeName: string): Promise<void>;
 }
 
+/**
+ * A refresh a form embedded in another form is asking its host to issue on its behalf.
+ *
+ * `immediate` mirrors the distinction the host's own editors make: a discrete editor fires on
+ * change, free text only marks itself pending and fires on blur.
+ */
+interface NestedTriggerRequest {
+    /** The full path the server addresses, e.g. `Gate.ProjectMode`. */
+    path: string;
+    immediate: boolean;
+}
 declare class SparkPoFormComponent {
     private readonly sparkService;
     private readonly translations;
@@ -76,6 +87,18 @@ declare class SparkPoFormComponent {
     objectTypeId: _angular_core.InputSignal<string | undefined>;
     /** The id of the object being edited; absent for a create. */
     objectId: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Set when this form renders a single embedded AsDetail object inside a host form: the name of
+     * the attribute holding it, e.g. `"Gate"`. Presence of a prefix switches the form from issuing
+     * its own refreshes to reporting them upward, because an embedded object is not something the
+     * server can be asked about on its own — the request must describe, and be authorized against,
+     * the object that owns it.
+     */
+    triggerPathPrefix: _angular_core.InputSignal<string | null>;
+    /** Raised instead of self-issuing when {@link triggerPathPrefix} is set. */
+    nestedTriggerRequested: _angular_core.OutputEmitterRef<NestedTriggerRequest>;
+    /** Blur counterpart, flushing a trigger the host only marked pending. */
+    nestedTriggerBlurred: _angular_core.OutputEmitterRef<string>;
     /**
      * What the last refresh changed about each attribute's presentation, keyed by attribute name.
      *
@@ -176,9 +199,8 @@ declare class SparkPoFormComponent {
     /**
      * 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.
+     * `attr` is optional because some editors have nothing useful to say about which attribute moved.
+     * A caller that knows should always say so — without it no refresh can fire.
      */
     onFieldChange(attr?: EntityAttributeDefinition): void;
     /**
@@ -187,8 +209,27 @@ declare class SparkPoFormComponent {
      * 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. */
+    /**
+     * Which embedded target the in-flight refresh belongs to, if any.
+     *
+     * ⚠️ Tagged, not a nullable `rowIndex`. The two arms write to different places — a row inside
+     * `formData`, versus the modal's working copy in `asDetailFormData` — and an index that happens
+     * to be absent is not the same statement as "this attribute holds one object". With a nullable
+     * index, a row refresh carrying a bad index would fall silently into the object arm.
+     */
     private pendingNestedTrigger;
+    /**
+     * A trigger inside a single embedded AsDetail object, raised by the modal's recursive form.
+     *
+     * The child form does not issue the request itself, for two reasons that both bite. Its
+     * `entityType` is the embedded type, so a payload built there describes `GateSettings` while the
+     * request must describe the Repository that owns it. And nested AsDetail types carry no rights of
+     * their own — the server authorizes a nested refresh on the OWNING type — so a child-issued
+     * request would be asking the wrong question of security.json.
+     */
+    onEmbeddedTrigger(attributeName: string, event: NestedTriggerRequest): void;
+    /** Blur counterpart of {@link onEmbeddedTrigger}, for the child's free-text editors. */
+    onEmbeddedTriggerBlur(path: string): void;
     /**
      * Applies a refresh that ran against a detail row: the row's own values, and the column metadata
      * for the grid it lives in.
@@ -204,6 +245,8 @@ declare class SparkPoFormComponent {
     /** Blur handler for free-text editors — sends the refresh their keystrokes only marked pending. */
     onFieldBlur(attr: EntityAttributeDefinition): void;
     private noteChange;
+    /** `Gate.ProjectMode` — the index-free counterpart of the inline grid's `Jobs[1].Kind`. */
+    private nestedTriggerPath;
     private canRefresh;
     /**
      * Per-instance, never a service: the retry-action modal renders its own `spark-po-form`, and a
@@ -212,6 +255,16 @@ declare class SparkPoFormComponent {
      */
     protected readonly refreshCoordinator: RefreshCoordinator;
     private buildRefreshPayload;
+    /**
+     * The values to post, with the open modal's working copy substituted for the attribute it edits.
+     *
+     * ⚠️ Without this the server receives the embedded object as it was when the modal opened — `{}`
+     * for a gate that has never been set — and the hook decides against values the user cannot see it
+     * ignoring. `formData` deliberately does not hold the in-progress edit (cancelling the modal has
+     * to discard it), so the refresh has to reach into `asDetailFormData` instead. Only the attribute
+     * under edit is substituted; everything else is the form's own state.
+     */
+    private embeddedValues;
     /**
      * Folds replaced option lists into the signals the editors already read, so a refreshed dropdown
      * renders through the same path as a loaded one.
@@ -278,7 +331,7 @@ declare class SparkPoFormComponent {
     removeArrayItem(attr: EntityAttributeDefinition, index: number): Promise<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; }; "objectTypeId": { "alias": "objectTypeId"; "required": false; "isSignal": true; }; "objectId": { "alias": "objectId"; "required": false; "isSignal": true; }; "refreshOverlay": { "alias": "refreshOverlay"; "required": false; "isSignal": true; }; }, { "formData": "formDataChange"; "save": "save"; "cancel": "cancel"; "refreshOverlay": "refreshOverlayChange"; }, 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; }; "triggerPathPrefix": { "alias": "triggerPathPrefix"; "required": false; "isSignal": true; }; "refreshOverlay": { "alias": "refreshOverlay"; "required": false; "isSignal": true; }; }, { "formData": "formDataChange"; "save": "save"; "cancel": "cancel"; "nestedTriggerRequested": "nestedTriggerRequested"; "nestedTriggerBlurred": "nestedTriggerBlurred"; "refreshOverlay": "refreshOverlayChange"; }, never, never, true, never>;
 }
 
 /**
@@ -357,3 +410,4 @@ declare class SparkLookupPickerComponent {
 }
 
 export { SparkLookupPickerComponent, SparkPoFormComponent, SparkReferencePickerComponent };
+export type { NestedTriggerRequest };

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 };