pict-section-recordset 1.10.0 → 1.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pict-section-recordset",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Pict dynamic record set management views",
   "main": "source/Pict-Section-RecordSet.js",
   "files": [
@@ -37,7 +37,7 @@
     "browser-env": "^3.3.0",
     "eslint": "^9.28.0",
     "jquery": "^3.7.1",
-    "pict": "^1.0.374",
+    "pict": "^1.0.384",
     "pict-application": "^1.0.34",
     "pict-docuserve": "^1.4.19",
     "pict-service-commandlineutility": "^1.0.19",

package/source/providers/RecordSet-RecordProvider-Base.js

@@ -316,6 +316,12 @@ class RecordSetProviderBase extends libPictProvider
 		tmpClause = JSON.parse(JSON.stringify(tmpClause));
 		tmpClause.Hash = `${pFilterKey}-${pClauseKey}-${this.pict.getUUID()}`;
 		tmpClause.Label = tmpClause.Label || tmpClause.DisplayName;
+		// Stamp the owning recordset so per-clause re-renders (which rebuild the render record
+		// from the live clause alone) can still resolve their provider and remove control.
+		if (!tmpClause.RecordSet && this.options.RecordSet)
+		{
+			tmpClause.RecordSet = this.options.RecordSet;
+		}
 		const tmpClauses = this.getFilterClauses();
 		tmpClauses.push(tmpClause);
 	}
@@ -467,7 +473,8 @@ class RecordSetProviderBase extends libPictProvider
 	 */
 	_pickQuickClause(pAvailableClauses)
 	{
-		return pAvailableClauses.find((pClause) => pClause.Type === 'InternalJoinSelectedValue' || pClause.Type === 'InternalJoinSelectedValueList')
+		return pAvailableClauses.find((pClause) => pClause.Type === 'DistinctSelectedValueList')
+			|| pAvailableClauses.find((pClause) => pClause.Type === 'InternalJoinSelectedValue' || pClause.Type === 'InternalJoinSelectedValueList')
 			|| pAvailableClauses.find((pClause) => pClause.Type === 'StringMatch' && pClause.ExactMatch === false)
 			|| pAvailableClauses.find((pClause) => pClause.Type === 'DateRange')
 			|| pAvailableClauses.find((pClause) => pClause.Type === 'NumericRange')
@@ -484,6 +491,7 @@ class RecordSetProviderBase extends libPictProvider
 		{
 			case 'StringMatch': return 'text';
 			case 'DateRange': return 'daterange';
+			case 'DistinctSelectedValueList': return 'distinct';
 			case 'InternalJoinSelectedValue':
 			case 'InternalJoinSelectedValueList': return 'entity';
 			default: return null;
@@ -668,6 +676,10 @@ class RecordSetProviderBase extends libPictProvider
 		tmpClause.Label = tmpClause.Label || tmpClause.DisplayName;
 		tmpClause.QuickFilter = true;
 		tmpClause.QuickFilterKey = pQuickFilterKey;
+		if (!tmpClause.RecordSet && this.options.RecordSet)
+		{
+			tmpClause.RecordSet = this.options.RecordSet;
+		}
 		return tmpClause;
 	}
 

package/source/providers/RecordSet-RecordProvider-MeadowEndpoints.js

@@ -68,35 +68,50 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 
 	/**
 	 * Fetch (and cache) the DISTINCT values of a column present in this recordset's data, via
-	 * Meadow's `<Entity>s/Distinct/<Column>` endpoint. Drives the `ScopeToRecordSet` filter knob:
-	 * an entity picker can be limited to `FBL~<Column>~INN~<these values>` so it only lists the
-	 * entities the data actually references, not the whole remote table. Cached per column.
+	 * Meadow's `<Entity>s/Distinct/<Column>` endpoint. Drives the `ScopeToRecordSet` filter knob
+	 * (an entity picker limited to `FBL~<Column>~INN~<these values>`) and the
+	 * `DistinctSelectedValueList` filter type (a dropdown whose options ARE these values).
+	 * Cached per column; the cache is cleared on create/update/delete through this provider.
 	 *
-	 * @param {string} pColumn @param {(pError: Error|null, pValues: Array<any>) => void} fCallback
+	 * @param {string} pColumn
+	 * @param {{ Filter?: string } | ((pError: Error|null, pValues: Array<any>) => void)} [pOptions] - Optional; `Filter` is a FoxHound stanza appended as `/FilteredTo/<Filter>` on the distinct query.
+	 * @param {(pError: Error|null, pValues: Array<any>) => void} [fCallback]
 	 */
-	getRecordSetColumnDistinct(pColumn, fCallback)
+	getRecordSetColumnDistinct(pColumn, pOptions, fCallback)
 	{
+		// Back-compat: (pColumn, fCallback)
+		let tmpOptions = pOptions;
+		let tmpCallback = fCallback;
+		if (typeof tmpOptions === 'function')
+		{
+			tmpCallback = tmpOptions;
+			tmpOptions = {};
+		}
+		tmpOptions = tmpOptions || {};
+		// Unfiltered fetches keep the bare-column key (synchronous peeks elsewhere read it);
+		// filtered fetches get their own key so the two never cross-pollinate.
+		const tmpCacheKey = tmpOptions.Filter ? `${pColumn}::${tmpOptions.Filter}` : pColumn;
 		this._scopeDistinctCache = this._scopeDistinctCache || {};
-		if (Array.isArray(this._scopeDistinctCache[pColumn]))
+		if (Array.isArray(this._scopeDistinctCache[tmpCacheKey]))
 		{
-			return fCallback(null, this._scopeDistinctCache[pColumn]);
+			return tmpCallback(null, this._scopeDistinctCache[tmpCacheKey]);
 		}
 		if (!this.options.Entity || !this.entityProvider || !this.entityProvider.restClient)
 		{
-			return fCallback(new Error('RecordSet provider cannot resolve a distinct request (missing Entity or rest client).'), []);
+			return tmpCallback(new Error('RecordSet provider cannot resolve a distinct request (missing Entity or rest client).'), []);
 		}
-		const tmpURL = `${this.options.URLPrefix || ''}${this.options.Entity}s/Distinct/${pColumn}`;
+		const tmpURL = `${this.options.URLPrefix || ''}${this.options.Entity}s/Distinct/${pColumn}${tmpOptions.Filter ? `/FilteredTo/${tmpOptions.Filter}` : ''}`;
 		this.entityProvider.restClient.getJSON(tmpURL, (pError, pResponse, pBody) =>
 		{
 			if (pError || (pResponse && pResponse.statusCode > 299) || !Array.isArray(pBody))
 			{
 				this.pict.log.warn(`RecordSet [${this.options.RecordSet || this.options.Entity}] distinct fetch for [${pColumn}] failed; the scoped filter falls back to unscoped.`, { Error: pError && pError.message, URL: tmpURL });
-				this._scopeDistinctCache[pColumn] = [];
-				return fCallback(pError || new Error('distinct fetch returned a non-array'), []);
+				this._scopeDistinctCache[tmpCacheKey] = [];
+				return tmpCallback(pError || new Error('distinct fetch returned a non-array'), []);
 			}
 			const tmpValues = [ ...new Set(pBody.map((pRecord) => pRecord && pRecord[pColumn]).filter((pValue) => pValue != null)) ];
-			this._scopeDistinctCache[pColumn] = tmpValues;
-			return fCallback(null, tmpValues);
+			this._scopeDistinctCache[tmpCacheKey] = tmpValues;
+			return tmpCallback(null, tmpValues);
 		});
 	}
 
@@ -547,6 +562,9 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 				}
 				// A new record changes the total; drop the cached count so the next render re-counts.
 				this._RecordSetCountCache = null;
+				// Mutations can introduce/retire column values; drop the distinct cache so
+				// ScopeToRecordSet scoping and DistinctSelectedValueList dropdowns refresh.
+				this._scopeDistinctCache = null;
 				// Drop this list's scoped cache too, so the next render re-fetches fresh.
 				if (typeof this.pict.EntityProvider.clearScope === 'function')
 				{
@@ -581,6 +599,9 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 				}
 				// An edit can move a record in or out of the active filter; drop the cached count to be safe.
 				this._RecordSetCountCache = null;
+				// Mutations can introduce/retire column values; drop the distinct cache so
+				// ScopeToRecordSet scoping and DistinctSelectedValueList dropdowns refresh.
+				this._scopeDistinctCache = null;
 				// Drop this list's scoped cache too, so the next render re-fetches fresh.
 				if (typeof this.pict.EntityProvider.clearScope === 'function')
 				{
@@ -615,6 +636,9 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 				}
 				// A delete changes the total; drop the cached count so the next render re-counts.
 				this._RecordSetCountCache = null;
+				// Mutations can introduce/retire column values; drop the distinct cache so
+				// ScopeToRecordSet scoping and DistinctSelectedValueList dropdowns refresh.
+				this._scopeDistinctCache = null;
 				// Drop this list's scoped cache too, so the next render re-fetches fresh.
 				if (typeof this.pict.EntityProvider.clearScope === 'function')
 				{

package/source/views/RecordSet-Filters.js

@@ -293,6 +293,7 @@ const _DEFAULT_CONFIGURATION_SUBSET_Filter =
 			{~TS:PRSP-QuickFilter-Text:Record.TextSlot~}
 			{~TS:PRSP-QuickFilter-Date:Record.DateSlot~}
 			{~TS:PRSP-QuickFilter-Entity:Record.EntitySlot~}
+			{~TS:PRSP-QuickFilter-Distinct:Record.DistinctSlot~}
 		</div>
 `
 		},
@@ -325,6 +326,14 @@ const _DEFAULT_CONFIGURATION_SUBSET_Filter =
 			Hash: 'PRSP-QuickFilter-Entity',
 			Template: /*html*/`
 		<span class="prsp-quickfilter-entityhost" id="{~D:Record.HostID~}"></span>
+`
+		},
+		{
+			// Distinct-values control — a multi-select pict-section-picker mounts into this host
+			// (post-render, in _mountQuickFilterDistinct), its options the column's distinct values.
+			Hash: 'PRSP-QuickFilter-Distinct',
+			Template: /*html*/`
+		<span class="prsp-quickfilter-entityhost" id="{~D:Record.HostID~}"></span>
 `
 		},
 	],
@@ -637,10 +646,11 @@ class ViewRecordSetSUBSETFilters extends libPictView
 		// `quickFiltersAutoDefault` (host-settable, default on) gates the clever schema defaults: a host
 		// can set it false to make quick filters opt-in (only record sets with an explicit config show).
 		const tmpEntityMounts = [];
+		const tmpDistinctMounts = [];
 		const tmpItems = tmpProvider.getQuickFilterDefinitions(this.quickFiltersAutoDefault).map((pDefinition) =>
 		{
 			const tmpBase = { Field: pDefinition.Field, ClauseKey: pDefinition.ClauseKey, Label: pDefinition.Label, RecordSet: pRecordSet, ViewContext: pViewContext };
-			const tmpItem = { Label: pDefinition.Label, TextSlot: [], DateSlot: [], EntitySlot: [] };
+			const tmpItem = { Label: pDefinition.Label, TextSlot: [], DateSlot: [], EntitySlot: [], DistinctSlot: [] };
 			if (pDefinition.Control === 'text')
 			{
 				tmpItem.TextSlot = [ Object.assign({}, tmpBase, { Value: tmpProvider.getQuickFilterClauseValue(pDefinition.Field), Placeholder: `Search ${pDefinition.Label}…` }) ];
@@ -656,12 +666,19 @@ class ViewRecordSetSUBSETFilters extends libPictView
 				tmpItem.EntitySlot = [ Object.assign({}, tmpBase, { HostID: tmpHostID }) ];
 				tmpEntityMounts.push(Object.assign({}, tmpBase, { HostID: tmpHostID }));
 			}
+			else if (pDefinition.Control === 'distinct')
+			{
+				const tmpHostID = `PRSP_QuickDistinct_${pRecordSet}_${pDefinition.Field}`;
+				tmpItem.DistinctSlot = [ Object.assign({}, tmpBase, { HostID: tmpHostID }) ];
+				tmpDistinctMounts.push(Object.assign({}, tmpBase, { HostID: tmpHostID }));
+			}
 			return tmpItem;
 		});
 		const tmpHTML = (tmpItems.length > 0) ? this.pict.parseTemplateByHash('PRSP-QuickFilters-Bar', { Filters: tmpItems }) : '';
 		this.pict.ContentAssignment.assignContent('#PRSP_QuickFilters', tmpHTML);
-		// Entity controls: mount (or re-mount) a picker into each host after the wholesale re-render.
+		// Entity / distinct controls: mount (or re-mount) a picker into each host after the wholesale re-render.
 		tmpEntityMounts.forEach((pMount) => this._mountQuickFilterEntity(pRecordSet, pViewContext, pMount));
+		tmpDistinctMounts.forEach((pMount) => this._mountQuickFilterDistinct(pRecordSet, pViewContext, pMount));
 	}
 
 	/**
@@ -711,6 +728,10 @@ class ViewRecordSetSUBSETFilters extends libPictView
 			// TextField when the entity has no list-entry template.
 			TextTemplate: tmpDescriptor.EntityListEntryTemplate || undefined,
 			Placeholder: `Select ${pMount.Label}…`,
+			// A filter's natural zero state is "Any" — the pinned clear row / inline × empty the
+			// selection, OnChange(null) flows through the upsert, and the clause is removed.
+			AllowClear: true,
+			ClearLabel: 'Any',
 			OnChange: (pValue) => this.applyQuickFilterEntity(pRecordSet, pViewContext, pMount.Field, pMount.ClauseKey, pValue),
 			BaseFilter: tmpScopeBaseFilter,
 		});
@@ -720,6 +741,56 @@ class ViewRecordSetSUBSETFilters extends libPictView
 		tmpView.setValue((Array.isArray(tmpCurrent) && tmpCurrent.length > 0) ? tmpCurrent[0] : '');
 	}
 
+	/**
+	 * Mount (idempotently) a multi-select pict-section-picker into a quick-filter distinct host,
+	 * its options the clause's static `Options` or the column's distinct values (fetched + cached
+	 * on the recordset provider; re-mounted once the fetch resolves so the options fill in). The
+	 * picker substring-filters static options client-side, so search works without a server trip.
+	 * On change it STAGES the clause (Values array) — Apply / Search commits. No-op if the picker
+	 * module isn't registered.
+	 *
+	 * @param {string} pRecordSet @param {string} pViewContext @param {Record<string, any>} pMount
+	 */
+	_mountQuickFilterDistinct(pRecordSet, pViewContext, pMount)
+	{
+		if (!document.getElementById(pMount.HostID)) { return; }
+		const tmpPickerProvider = this.pict.providers['Pict-Section-Picker'];
+		const tmpProvider = this.pict.providers['RSP-Provider-' + pRecordSet];
+		if (!tmpPickerProvider || typeof tmpPickerProvider.createPicker !== 'function' || !tmpProvider) { return; }
+		const tmpDescriptor = tmpProvider.getFilterClauseSchemaForKey(pMount.Field)?.AvailableClauses?.find?.((pClause) => pClause.ClauseKey === pMount.ClauseKey);
+		if (!tmpDescriptor || !tmpDescriptor.FilterByColumn) { return; }
+		let tmpValues;
+		if (Array.isArray(tmpDescriptor.Options) && tmpDescriptor.Options.length > 0)
+		{
+			tmpValues = tmpDescriptor.Options;
+		}
+		else
+		{
+			const tmpCacheKey = tmpDescriptor.DistinctFilter ? `${tmpDescriptor.FilterByColumn}::${tmpDescriptor.DistinctFilter}` : tmpDescriptor.FilterByColumn;
+			tmpValues = (tmpProvider._scopeDistinctCache || {})[tmpCacheKey];
+			if (!Array.isArray(tmpValues) && typeof tmpProvider.getRecordSetColumnDistinct === 'function')
+			{
+				tmpProvider.getRecordSetColumnDistinct(tmpDescriptor.FilterByColumn, { Filter: tmpDescriptor.DistinctFilter },
+					() => this._mountQuickFilterDistinct(pRecordSet, pViewContext, pMount));
+				tmpValues = [];
+			}
+		}
+		const tmpOptions = (Array.isArray(tmpValues) ? tmpValues : []).map((pValue) => ({ Value: pValue, Text: String(pValue) }));
+		const tmpView = tmpPickerProvider.createPicker(`Quick-Distinct-${pRecordSet}-${pMount.Field}`,
+		{
+			DestinationAddress: `#${pMount.HostID}`,
+			// Multi-select: "any of the checked values" is the natural distinct-filter semantic.
+			Mode: 'multi',
+			Options: tmpOptions,
+			Placeholder: `Select ${pMount.Label}…`,
+			OnChange: (pValuesArray) => this.applyQuickFilterDistinct(pRecordSet, pViewContext, pMount.Field, pMount.ClauseKey, pValuesArray),
+		});
+		if (!tmpView) { return; }
+		tmpView.render();
+		const tmpCurrent = (typeof tmpProvider.getQuickFilterEntityValue === 'function') ? tmpProvider.getQuickFilterEntityValue(pMount.Field) : [];
+		tmpView.setValue(Array.isArray(tmpCurrent) ? tmpCurrent : []);
+	}
+
 	/**
 	 * Apply a text quick filter: upsert (or clear) its tagged clause, then run the standard search +
 	 * serialize path. Commits on blur / Enter (not per-keystroke) so the re-render never steals focus.
@@ -820,6 +891,23 @@ class ViewRecordSetSUBSETFilters extends libPictView
 		}
 	}
 
+	/**
+	 * Stage a field's distinct quick-filter selection (the Values array of its
+	 * DistinctSelectedValueList clause). Doesn't fire the search — commit happens
+	 * on Apply / Search.
+	 *
+	 * @param {string} pRecordSet @param {string} pViewContext @param {string} pField @param {string} pClauseKey @param {Array<any>} pValues
+	 */
+	applyQuickFilterDistinct(pRecordSet, pViewContext, pField, pClauseKey, pValues)
+	{
+		this.bumpRenderEpoch();
+		const tmpProvider = this.pict.providers['RSP-Provider-' + pRecordSet];
+		if (tmpProvider && typeof tmpProvider.upsertQuickFilterEntity === 'function')
+		{
+			tmpProvider.upsertQuickFilterEntity(pField, pClauseKey, pValues);
+		}
+	}
+
 	/**
 	 * @param {Event} pEvent - The DOM event that triggered the search
 	 * @param {string} pRecordSet - The record set being filtered

package/source/views/filters/RecordSet-Filter-DistinctSelectedValueList.js

@@ -0,0 +1,233 @@
+const ViewRecordSetSUBSETFilterBase = require('./RecordSet-Filter-Base');
+
+/**
+ * DistinctSelectedValueList — a dropdown/checkbox filter whose options ARE the distinct
+ * values of a column on the CORE entity (no join), fetched from Meadow's
+ * `<Entity>s/Distinct/<Column>` endpoint through the recordset provider's cached
+ * `getRecordSetColumnDistinct()`. The clause's `Values` array holds the selection; pict's
+ * Filter.js compiles it to an OR-chain of `FBVOR~<col>~EQ~<value>` stanzas inside one
+ * paren group.
+ *
+ * Clause config:
+ *   - FilterByColumn {string} - the core-entity column the options come from / filter on.
+ *   - Options {Array<any>} - optional STATIC option list; when present the distinct fetch is skipped.
+ *   - DistinctFilter {string} - optional FoxHound stanza appended as `/FilteredTo/<...>` on the
+ *     distinct query (e.g. `FBV~Deleted~EQ~0` to keep soft-deleted rows' values out of the list).
+ *
+ * Selected values missing from the option list (e.g. restored from a saved filter experience
+ * whose value no longer appears in the data) are unioned in so they stay visible and
+ * un-checkable. Selection toggles by option INDEX, never by value — values can contain
+ * quotes that would break inline onclick attributes.
+ *
+ * Staging only: toggling checkboxes mutates the live clause but does NOT fire a search —
+ * the user commits with Apply / Search (the stage-then-Apply contract).
+ */
+const _DEFAULT_CONFIGURATION_Filter_DistinctSelectedValueList =
+{
+	ViewIdentifier: 'PRSP-FilterType-DistinctSelectedValueList',
+
+	CSS: /*css*/`
+.prsp-filter-distinct { min-width: 12rem; }
+.prsp-filter-distinct-options { display: flex; flex-direction: column; gap: 0.15rem; max-height: 11rem; overflow-y: auto;
+	padding: 0.35rem 0.5rem; border-radius: 8px; border: 1px solid var(--theme-color-border-default, #d7dce3);
+	background: var(--theme-color-background-primary, #fff); }
+.prsp-filter-distinct-option { display: flex; align-items: center; gap: 0.45rem; cursor: pointer;
+	font-size: 0.92rem; color: var(--theme-color-text-primary, #1f2733); margin: 0; }
+.prsp-filter-distinct-option input[type="checkbox"] { width: auto; margin: 0; cursor: pointer; }
+.prsp-filter-distinct-note { font-size: 0.82rem; color: var(--theme-color-text-muted, #6b7686); padding: 0.15rem 0; }
+`,
+
+	Templates:
+	[
+		{
+			Hash: 'PRSP-Filter-DistinctSelectedValueList-Template',
+			Template: /*html*/`
+	<!-- DefaultPackage pict view template: [PRSP-Filter-DistinctSelectedValueList-Template] -->
+	<div class="prsp-filter-distinct">
+		<label>{~D:Record.Label~}</label>
+		<div class="prsp-filter-distinct-options">
+			{~TS:PRSP-Filter-Distinct-Loading:Record.DistinctLoading~}
+			{~TS:PRSP-Filter-Distinct-Empty:Record.DistinctEmpty~}
+			{~TSWP:PRSP-Filter-Distinct-Option:Record.DistinctOptions:Record~}
+		</div>
+	</div>
+	<!-- DefaultPackage end view template: [PRSP-Filter-DistinctSelectedValueList-Template] -->
+`
+		},
+		{
+			Hash: 'PRSP-Filter-Distinct-Option',
+			Template: /*html*/`
+	<label class="prsp-filter-distinct-option">
+		<input type="checkbox" {~D:Record.Data.CheckedAttribute~}
+			onchange="_Pict.views['PRSP-FilterType-DistinctSelectedValueList'].toggleOption(event, '{~D:Record.Payload.ClauseAddress~}', '{~D:Record.Payload.Hash~}', {~D:Record.Data.OptionIndex~})">
+		<span>{~D:Record.Data.Text~}</span>
+	</label>
+`
+		},
+		{
+			Hash: 'PRSP-Filter-Distinct-Loading',
+			Template: /*html*/`
+	<span class="prsp-filter-distinct-note">Loading values…</span>
+`
+		},
+		{
+			Hash: 'PRSP-Filter-Distinct-Empty',
+			Template: /*html*/`
+	<span class="prsp-filter-distinct-note">No values available.</span>
+`
+		},
+	],
+};
+
+class ViewRecordSetSUBSETFilterDistinctSelectedValueList extends ViewRecordSetSUBSETFilterBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+	}
+
+	getFilterFormTemplate()
+	{
+		return 'PRSP-Filter-DistinctSelectedValueList-Template';
+	}
+
+	/**
+	 * The ordered raw option values for a clause: the static `Options` list when configured,
+	 * else the provider's cached distinct values, with any selected values missing from the
+	 * list unioned onto the end.
+	 *
+	 * @param {Record<string, any>} pClause
+	 * @param {Record<string, any>} pProvider - The recordset provider (`RSP-Provider-<RecordSet>`).
+	 * @return {Array<any>}
+	 */
+	_optionValues(pClause, pProvider)
+	{
+		let tmpValues = Array.isArray(pClause.Options) ? pClause.Options.slice() : null;
+		if (!tmpValues)
+		{
+			const tmpCacheKey = pClause.DistinctFilter ? `${pClause.FilterByColumn}::${pClause.DistinctFilter}` : pClause.FilterByColumn;
+			const tmpCached = (pProvider && pProvider._scopeDistinctCache) ? pProvider._scopeDistinctCache[tmpCacheKey] : null;
+			tmpValues = Array.isArray(tmpCached) ? tmpCached.slice() : [];
+		}
+		if (Array.isArray(pClause.Values))
+		{
+			for (const tmpSelected of pClause.Values)
+			{
+				if (!tmpValues.some((pValue) => pValue === tmpSelected))
+				{
+					tmpValues.push(tmpSelected);
+				}
+			}
+		}
+		return tmpValues;
+	}
+
+	/**
+	 * Map the option values to render rows ({ Text, OptionIndex, CheckedAttribute }).
+	 *
+	 * @param {Record<string, any>} pClause
+	 * @param {Record<string, any>} pProvider
+	 * @return {Array<{ Text: string, OptionIndex: number, CheckedAttribute: string }>}
+	 */
+	_composeOptionList(pClause, pProvider)
+	{
+		const tmpSelected = Array.isArray(pClause.Values) ? pClause.Values : [];
+		return this._optionValues(pClause, pProvider).map((pValue, pIndex) => (
+		{
+			Text: String(pValue),
+			OptionIndex: pIndex,
+			CheckedAttribute: tmpSelected.some((pSelectedValue) => pSelectedValue === pValue) ? 'checked' : '',
+		}));
+	}
+
+	/**
+	 * @param {Record<string, any>} pRecord
+	 */
+	prepareRecord(pRecord)
+	{
+		super.prepareRecord(pRecord);
+
+		const tmpProvider = this.pict.providers['RSP-Provider-' + pRecord.RecordSet];
+		pRecord.DistinctLoading = [];
+		// No static Options: make sure the distinct values are fetched (cached on the provider),
+		// re-rendering just this clause's container once they resolve. Errored fetches cache []
+		// so this can't loop.
+		if (!Array.isArray(pRecord.Options) && pRecord.FilterByColumn
+			&& tmpProvider && typeof tmpProvider.getRecordSetColumnDistinct === 'function')
+		{
+			const tmpCacheKey = pRecord.DistinctFilter ? `${pRecord.FilterByColumn}::${pRecord.DistinctFilter}` : pRecord.FilterByColumn;
+			if (!tmpProvider._scopeDistinctCache || !Array.isArray(tmpProvider._scopeDistinctCache[tmpCacheKey]))
+			{
+				pRecord.DistinctLoading = [ {} ];
+				const tmpClauseAddress = pRecord.ClauseAddress;
+				const tmpClauseHash = pRecord.Hash;
+				tmpProvider.getRecordSetColumnDistinct(pRecord.FilterByColumn, { Filter: pRecord.DistinctFilter },
+					() => this._reRenderClause(tmpClauseAddress, tmpClauseHash));
+			}
+		}
+		pRecord.DistinctOptions = this._composeOptionList(pRecord, tmpProvider);
+		pRecord.DistinctEmpty = (pRecord.DistinctLoading.length === 0 && pRecord.DistinctOptions.length === 0) ? [ {} ] : [];
+	}
+
+	/**
+	 * Toggle an option's membership in the live clause's `Values` by option index. Staging
+	 * only — the search fires on Apply / Search, not here.
+	 *
+	 * @param {Event} pEvent
+	 * @param {string} pClauseInformaryAddress
+	 * @param {string} pClauseHash
+	 * @param {number} pOptionIndex
+	 */
+	toggleOption(pEvent, pClauseInformaryAddress, pClauseHash, pOptionIndex)
+	{
+		const tmpClause = this.getInformaryScopedValue(pClauseInformaryAddress);
+		if (!tmpClause)
+		{
+			this.pict.log.error(`[Filter-DistinctSelectedValueList] No clause found for address: ${pClauseInformaryAddress}`);
+			return;
+		}
+		const tmpProvider = this.pict.providers['RSP-Provider-' + tmpClause.RecordSet];
+		const tmpOptionValues = this._optionValues(tmpClause, tmpProvider);
+		if (pOptionIndex < 0 || pOptionIndex >= tmpOptionValues.length)
+		{
+			return;
+		}
+		const tmpValue = tmpOptionValues[pOptionIndex];
+		if (!Array.isArray(tmpClause.Values))
+		{
+			tmpClause.Values = [];
+		}
+		const tmpSelectedIndex = tmpClause.Values.findIndex((pSelectedValue) => pSelectedValue === tmpValue);
+		if (tmpSelectedIndex >= 0)
+		{
+			tmpClause.Values.splice(tmpSelectedIndex, 1);
+		}
+		else
+		{
+			tmpClause.Values.push(tmpValue);
+		}
+		this._reRenderClause(pClauseInformaryAddress, pClauseHash);
+	}
+
+	/**
+	 * Re-render this clause's container (the checkbox list repaints on toggle / fetch resolve).
+	 *
+	 * @param {string} pClauseInformaryAddress
+	 * @param {string} pClauseHash
+	 */
+	_reRenderClause(pClauseInformaryAddress, pClauseHash)
+	{
+		const tmpClause = this.getInformaryScopedValue(pClauseInformaryAddress);
+		if (!tmpClause)
+		{
+			return;
+		}
+		const tmpRecord = Object.assign({ ClauseAddress: pClauseInformaryAddress }, tmpClause);
+		this.prepareRecord(tmpRecord);
+		this.render(null, `#PRSP_Filter_Container_${pClauseHash}`, tmpRecord);
+	}
+}
+
+module.exports = ViewRecordSetSUBSETFilterDistinctSelectedValueList;
+
+module.exports.default_configuration = Object.assign({}, ViewRecordSetSUBSETFilterBase.default_configuration, _DEFAULT_CONFIGURATION_Filter_DistinctSelectedValueList);

package/source/views/filters/index.js

@@ -10,6 +10,8 @@ module.exports =
 	StringMatch: require('./RecordSet-Filter-StringMatch.js'),
 	StringRange: require('./RecordSet-Filter-StringRange.js'),
 
+	DistinctSelectedValueList: require('./RecordSet-Filter-DistinctSelectedValueList.js'),
+
 	InternalJoinDateMatch: require('./RecordSet-Filter-InternalJoinDateMatch.js'),
 	InternalJoinDateRange: require('./RecordSet-Filter-InternalJoinDateRange.js'),
 	InternalJoinNumericMatch: require('./RecordSet-Filter-InternalJoinNumericMatch.js'),