@genesislcap/grid-pro 15.21.1 → 15.22.1

package/dist/grid-pro.d.ts

@@ -95,6 +95,11 @@ import { ICellRendererComp } from '@ag-grid-community/core';
 import { ICellRendererFunc } from '@ag-grid-community/core';
 import { ICellRendererParams } from '@ag-grid-community/core';
 import type { IDatasource } from 'ag-grid-community';
+import type { IDoesFilterPassParams } from 'ag-grid-community';
+import type { IFilterComp } from 'ag-grid-community';
+import type { IFilterParams } from 'ag-grid-community';
+import type { IFloatingFilterComp } from 'ag-grid-community';
+import type { IFloatingFilterParams } from 'ag-grid-community';
 import type { IGetRowsParams } from 'ag-grid-community';
 import { ILoadingCellRendererSelectorFunc } from 'ag-grid-community';
 import { IndexDetail } from '@genesislcap/foundation-comms';
@@ -726,6 +731,15 @@ export declare const convertToKebabCase: (value: string) => string;
  */
 export declare function copyAttributesToGridOptions(gridOptions: any, component: Record<string, any>): any;
 
+/**
+ * Builds the value-to-label formatter for an enum filter, honouring `valueFormatter` from the
+ * filter params and labelling `null` (blanks) consistently.
+ * @remarks Shared by {@link EnumColumnFilter} and the floating filter so both render the same
+ * labels from `ColDef.filterParams` alone.
+ * @public
+ */
+export declare function createEnumValueLabelFormatter(params: (Pick<EnumColumnFilterParams, 'valueFormatter'> & Partial<Pick<EnumColumnFilterValueFormatterParams, 'api' | 'colDef' | 'column' | 'context'>>) | undefined): (value: string | null) => string;
+
 /**
  * Builds the class rules that flash rows matching `criteria`, together with the context menu
  * that lets a user recolor, retime, or narrow that flash to a single cell.
@@ -1091,6 +1105,212 @@ export declare class EditableRenderer extends FoundationElement implements ICell
  */
 export declare const EDITED_COLUMN_FIELD = "__editedColumn";
 
+/**
+ * An Excel AutoFilter-inspired set filter for enum columns, built on AG Grid Community only.
+ * @remarks
+ * Renders a searchable checkbox list of the column's enum options (from `filterParams.values`,
+ * fed by the resource field metadata or a values getter — the option list is defined by the enum,
+ * never scanned from row data) with a tri-state "(Select All)" toggle scoped to the search
+ * results, a `(Blanks)` entry shown by default, human-readable labels, and arrow-key navigation —
+ * applying on every change. Emits the same `{ filterType: 'set', values }` model as the
+ * enterprise `agSetColumnFilter`, so it is a drop-in replacement for filter-model persistence and
+ * the Genesis server-side criteria building — without requiring the enterprise `SetFilterModule`.
+ * @public
+ */
+export declare class EnumColumnFilter implements IFilterComp {
+    protected params: IFilterParams & EnumColumnFilterParams;
+    private eGui;
+    /** The GUI's shadow root — hosts the content and the shared FAST stylesheet. */
+    private eRoot;
+    private eSearch;
+    private eSelectAll;
+    private eList;
+    /** Rendered value checkboxes keyed by value; `null` keys the blanks entry. */
+    private itemInputs;
+    /** All selectable values, in the order the metadata/getter provided them. */
+    private allValues;
+    /** Whether the `(Blanks)` entry is offered — on unless `filterParams.blanks` is `false`. */
+    private includeBlanks;
+    /** Guards async values resolution against out-of-date responses and use after destroy. */
+    private valuesRequestId;
+    private loading;
+    /** Whether this instance installed the header tooltip getter (so destroy removes only its own). */
+    private ownsHeaderTooltip;
+    private formatLabel;
+    /**
+     * `null` while inactive (everything passes); otherwise the selected values, with `null`
+     * standing for blanks. May contain values absent from `allValues` (e.g. a restored model
+     * referencing rows not loaded yet) — those are preserved and rendered as extra list entries
+     * so restoring a persisted model never silently narrows it, while still letting the user
+     * deselect them.
+     */
+    private model;
+    private searchTerm;
+    init(params: IFilterParams & EnumColumnFilterParams): void;
+    getGui(): HTMLElement;
+    isFilterActive(): boolean;
+    doesFilterPass(params: IDoesFilterPassParams): boolean;
+    getModel(): EnumColumnFilterModel | null;
+    setModel(model: EnumColumnFilterModel | null): void;
+    getModelAsString(model: EnumColumnFilterModel | null): string;
+    /** Clears the filter back to inactive and notifies the grid; used by the floating filter. */
+    clear(): void;
+    /**
+     * Surfaces the active selection in the column's header tooltip (alongside AG's native header
+     * filter icon), so the filter state is inspectable from the header without the layout-changing
+     * floating filter row. Installed as a `headerTooltipValueGetter`, which AG evaluates lazily on
+     * hover — no header refresh needed when the model changes. While inactive it returns
+     * `undefined`, which falls back to the consumer's own `headerTooltip`; when active, that
+     * tooltip is kept as the prefix. A consumer-provided getter is left untouched.
+     */
+    private installHeaderTooltip;
+    afterGuiAttached(params?: {
+        suppressFocus?: boolean;
+    }): void;
+    refresh(params: IFilterParams & EnumColumnFilterParams): boolean;
+    destroy(): void;
+    /** Resolves the option list (values array or getter) and re-renders. */
+    private resolveState;
+    private loadAsyncValues;
+    /** The raw field read covers params without `getValue` (e.g. stripped-down test params). */
+    private getCellValue;
+    /** Model values that are not in the option list, e.g. from a restored persisted model. */
+    private extraModelValues;
+    /**
+     * All offered entry keys: the option list, then any off-list model values (rendered so they can
+     * be deselected rather than being stuck in the model forever), then `null` (blanks) last like
+     * Excel. The blanks entry is also offered whenever the model references it, so a restored
+     * blanks selection stays visible and removable even before blank rows are detected.
+     */
+    private allKeys;
+    private isSelected;
+    private visibleKeys;
+    /**
+     * Applies a new selection. Collapses back to the inactive (`null`) model when every offered
+     * entry is selected, so a fully re-selected filter reports inactive exactly like the
+     * enterprise set filter. Selected values beyond the offered keys don't restrict anything an
+     * inactive filter would pass, so a superset selection collapses too.
+     */
+    private updateSelection;
+    private currentSelection;
+    private toggleValue;
+    /** Select-all acts on the searched subset only, mirroring Excel's AutoFilter. */
+    private toggleAllVisible;
+    private createGui;
+    private createItem;
+    /** Rebuilds the value list; used when the values or the search term change. */
+    private renderList;
+    /** Refreshes checkbox states in place, preserving DOM (and keyboard focus) on toggles. */
+    private syncCheckedStates;
+    private focusables;
+    /**
+     * Arrow keys walk search box, "(Select All)" and the visible entries; Enter toggles the
+     * focused entry (Space is the checkbox's native toggle). Tab wraps within the popup: AG's own
+     * popup focus trap collects focusable elements with `querySelectorAll`, which does not pierce
+     * the shadow root, so the trap must live here.
+     */
+    private handleKeyDown;
+}
+
+/**
+ * The filter model produced by {@link EnumColumnFilter}.
+ * @remarks Shape-compatible with AG Grid's `agSetColumnFilter` model — including `null` standing
+ * for blanks — so persisted filter models and the datasource `CRITERIA_MATCH` translation treat
+ * both filters identically.
+ * @public
+ */
+export declare interface EnumColumnFilterModel {
+    filterType: 'set';
+    values: (string | null)[];
+}
+
+/**
+ * Parameters used to configure {@link EnumColumnFilter}.
+ * @remarks Provided via `ColDef.filterParams`. The option list is defined by the enum — the
+ * field metadata's `enumOptions`, a plain array, or a getter — never derived from row data;
+ * omitting `values` logs a warning and offers only the `(Blanks)` entry.
+ * @public
+ */
+export declare interface EnumColumnFilterParams {
+    /**
+     * The selectable values — typically the `enumOptions` from the field metadata — or a function
+     * resolving them at runtime (see {@link EnumColumnFilterValuesGetter}).
+     */
+    values?: string[] | EnumColumnFilterValuesGetter;
+    /**
+     * Formats a raw value into the label shown in the list, the floating filter, and the filter
+     * summary. Receives `value` plus `api`/`colDef`/`column`/`context`, so an `agSetColumnFilter`
+     * formatter that reads those keeps working when the column is downgraded — but never `node` or
+     * `data`, since these labels are not row-bound. Defaults to capital case (`PENDING_APPROVAL`
+     * becomes `Pending Approval`).
+     */
+    valueFormatter?: (params: EnumColumnFilterValueFormatterParams) => string;
+    /**
+     * Whether to show the `(Blanks)` entry, which matches rows with a `null`/empty cell value.
+     * Shown by default, so a nullable enum column's blank rows are always filterable; set `false`
+     * to hide it (e.g. on a field that can never be blank).
+     */
+    blanks?: boolean;
+}
+
+/**
+ * Parameters passed to {@link EnumColumnFilterParams.valueFormatter} — the subset of AG's
+ * `ValueFormatterParams` that is available in every context the formatter runs in (the filter
+ * list, the floating filter summary, and the header tooltip). Row-specific fields (`node`,
+ * `data`) are never provided, since these labels are not tied to a row.
+ * @public
+ */
+export declare interface EnumColumnFilterValueFormatterParams {
+    value: string;
+    api?: IFilterParams['api'];
+    colDef?: IFilterParams['colDef'];
+    column?: IFilterParams['column'];
+    context?: unknown;
+}
+
+/**
+ * Resolves the selectable values at runtime, e.g. from a request-reply resource: return them
+ * (directly or as a promise), or call `params.success` with them, AG set-filter style.
+ * @public
+ */
+export declare type EnumColumnFilterValuesGetter = (params: EnumColumnFilterValuesGetterParams) => string[] | Promise<string[]> | void;
+
+/**
+ * Parameters handed to an {@link EnumColumnFilterValuesGetter}.
+ * @public
+ */
+export declare interface EnumColumnFilterValuesGetterParams {
+    colDef: IFilterParams['colDef'];
+    api: IFilterParams['api'];
+    /**
+     * Resolves the values via callback instead of a return value — the contract of AG Grid's
+     * `SetFilterValuesFunc`, so an `agSetColumnFilter` values function keeps working when the
+     * column is downgraded to this filter.
+     */
+    success: (values: string[]) => void;
+}
+
+/**
+ * Floating filter companion for {@link EnumColumnFilter}: shows the current selection as a
+ * compact summary (e.g. `(2) Active, Pending`), opens the parent filter on click, and offers a
+ * one-click clear. Set via `ColDef.floatingFilterComponent` (see
+ * {@link GridProFilterTypes.enumFloatingFilter}); shown when the column enables `floatingFilter`.
+ * @public
+ */
+export declare class EnumColumnFloatingFilter implements IFloatingFilterComp {
+    private params;
+    private eGui;
+    /** The GUI's shadow root — hosts the content and the shared FAST stylesheet. */
+    private eRoot;
+    private eSummary;
+    private eClear;
+    private formatLabel;
+    init(params: IFloatingFilterParams): void;
+    getGui(): HTMLElement;
+    onParentModelChanged(model: EnumColumnFilterModel | null): void;
+    destroy(): void;
+}
+
 /**
  * Key used to store error details (column, message) when inline edit fails sync with server side data
  * @public
@@ -1133,6 +1353,12 @@ export declare const foregroundSwatch: SwatchRGB;
  */
 export declare function formatDateExtra(epoch: number): string;
 
+/**
+ * Renders an enum filter model as a short summary, e.g. `(2) Active, Pending`.
+ * @public
+ */
+export declare function formatEnumFilterModelAsString(model: EnumColumnFilterModel | null, formatLabel: (value: string | null) => string): string;
+
 /**
  * A function that returns a Foundation Boolean Renderer registration for configuring the component with a DesignSystem.
  *
@@ -3648,6 +3874,20 @@ export declare class GridProBeta extends GridProBeta_base {
      * @internal
      */
     private processSchemaUpdate;
+    /**
+     * Downgrades enterprise filters in metadata-generated colDefs when their modules are not
+     * registered — from v35 AG Grid throws on unregistered filters instead of falling back.
+     * Enum columns (recognised by their metadata-sourced set-filter values) keep those values by
+     * falling back to the community `EnumColumnFilter` instead of a plain text filter.
+     *
+     * The enum floating filter is only wired as the column's component, not enabled: AG's floating
+     * filter is a full-width header row, so enabling it for one column changes the layout of every
+     * column. Active-filter state is surfaced instead by AG's native header filter icon plus the
+     * header tooltip the enum filter maintains; consumers wanting the floating row opt in with
+     * `floatingFilter: true`.
+     * @internal
+     */
+    private applyCommunityFilterFallbacks;
     /**
      * Handles data clearing from datasource
      * @internal
@@ -4118,21 +4358,7 @@ declare const GridProBeta_base: (new (...args: any[]) => {
     removeAttributeNS(namespace: string | null, localName: string): void;
     removeAttributeNode(attr: Attr): Attr;
     requestFullscreen(options?: FullscreenOptions): Promise<void>;
-    requestPointerLock(options
-    /**
-    * Enables or disables the grid status bar.
-    * @remarks
-    * Default is false.
-    * When disabled, no status bar will be displayed regardless of statusBarConfig.
-    * This requires AG Grid Enterprise module to be available for the status bar to be displayed when enabled.
-    */
-    ? /**
-    * Enables or disables the grid status bar.
-    * @remarks
-    * Default is false.
-    * When disabled, no status bar will be displayed regardless of statusBarConfig.
-    * This requires AG Grid Enterprise module to be available for the status bar to be displayed when enabled.
-    */: PointerLockOptions): Promise<void>;
+    requestPointerLock(options?: PointerLockOptions): Promise<void>;
     scroll(options?: ScrollToOptions): void;
     scroll(x: number, y: number): void;
     scrollBy(options?: ScrollToOptions): void;
@@ -4367,12 +4593,7 @@ declare const GridProBeta_base: (new (...args: any[]) => {
     ontouchcancel?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     ontouchend?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     ontouchmove?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
-    ontouchstart
-    /**
-    * Handles schema updates from datasource
-    * @internal
-    */
-    ?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
+    ontouchstart?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     ontransitioncancel: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null;
     ontransitionend: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null;
     ontransitionrun: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null;
@@ -4893,6 +5114,17 @@ export declare type GridProEventsAndCallbacks = OnlyFunctions<UntypeNonFunctions
  */
 export declare type GridProEventsListeners = [string, (event: Event) => void][];
 
+/**
+ * The available Grid Pro column filter component names.
+ * @remarks Register-able via the grid `components` map; `enumFilter` is usable as a
+ * `ColDef.filter` value and `enumFloatingFilter` as a `ColDef.floatingFilterComponent`.
+ * @public
+ */
+export declare enum GridProFilterTypes {
+    enumFilter = "enumColumnFilter",
+    enumFloatingFilter = "enumColumnFloatingFilter"
+}
+
 /**
  * The Genesis Datasource element, for CSRM-compatible data fetching and used exclusively by the GridPro element.
  * @remarks Only supports Client-Side Row Model.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/grid-pro",
   "description": "Genesis Foundation AG Grid",
-  "version": "15.21.1",
+  "version": "15.22.1",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -40,20 +40,20 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.21.1",
-    "@genesislcap/genx": "15.21.1",
-    "@genesislcap/rollup-builder": "15.21.1",
-    "@genesislcap/ts-builder": "15.21.1",
-    "@genesislcap/uvu-playwright-builder": "15.21.1",
-    "@genesislcap/vite-builder": "15.21.1",
-    "@genesislcap/webpack-builder": "15.21.1"
+    "@genesislcap/foundation-testing": "15.22.1",
+    "@genesislcap/genx": "15.22.1",
+    "@genesislcap/rollup-builder": "15.22.1",
+    "@genesislcap/ts-builder": "15.22.1",
+    "@genesislcap/uvu-playwright-builder": "15.22.1",
+    "@genesislcap/vite-builder": "15.22.1",
+    "@genesislcap/webpack-builder": "15.22.1"
   },
   "dependencies": {
-    "@genesislcap/foundation-comms": "15.21.1",
-    "@genesislcap/foundation-criteria": "15.21.1",
-    "@genesislcap/foundation-logger": "15.21.1",
-    "@genesislcap/foundation-ui": "15.21.1",
-    "@genesislcap/foundation-utils": "15.21.1",
+    "@genesislcap/foundation-comms": "15.22.1",
+    "@genesislcap/foundation-criteria": "15.22.1",
+    "@genesislcap/foundation-logger": "15.22.1",
+    "@genesislcap/foundation-ui": "15.22.1",
+    "@genesislcap/foundation-utils": "15.22.1",
     "@microsoft/fast-colors": "5.3.1",
     "@microsoft/fast-components": "2.30.6",
     "@microsoft/fast-element": "1.14.0",