pict-section-recordset 1.9.3 → 1.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pict-section-recordset",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "Pict dynamic record set management views",
   "main": "source/Pict-Section-RecordSet.js",
   "files": [

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

@@ -66,6 +66,40 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 		return this._EntityProvider;
 	}
 
+	/**
+	 * 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.
+	 *
+	 * @param {string} pColumn @param {(pError: Error|null, pValues: Array<any>) => void} fCallback
+	 */
+	getRecordSetColumnDistinct(pColumn, fCallback)
+	{
+		this._scopeDistinctCache = this._scopeDistinctCache || {};
+		if (Array.isArray(this._scopeDistinctCache[pColumn]))
+		{
+			return fCallback(null, this._scopeDistinctCache[pColumn]);
+		}
+		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).'), []);
+		}
+		const tmpURL = `${this.options.URLPrefix || ''}${this.options.Entity}s/Distinct/${pColumn}`;
+		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'), []);
+			}
+			const tmpValues = [ ...new Set(pBody.map((pRecord) => pRecord && pRecord[pColumn]).filter((pValue) => pValue != null)) ];
+			this._scopeDistinctCache[pColumn] = tmpValues;
+			return fCallback(null, tmpValues);
+		});
+	}
+
 	/**
 	 * @return {Array<string>} - The fields to ignore for filter availability.
 	 */

package/source/views/RecordSet-Filters.js

@@ -674,6 +674,23 @@ class ViewRecordSetSUBSETFilters extends libPictView
 		const tmpDescriptor = tmpProvider.getFilterClauseSchemaForKey(pMount.Field)?.AvailableClauses?.find?.((pClause) => pClause.ClauseKey === pMount.ClauseKey);
 		if (!tmpDescriptor || !tmpDescriptor.RemoteTable) { return; }
 		const tmpSearchFields = Array.isArray(tmpDescriptor.ExternalFilterByColumns) && tmpDescriptor.ExternalFilterByColumns.length > 0 ? tmpDescriptor.ExternalFilterByColumns : [ 'Name' ];
+		// ScopeToRecordSet knob: limit the picker to the values present in this recordset's data
+		// (FBL~<col>~INN~<distinct>) so it doesn't list the whole remote table. Pre-fetch the
+		// distinct set, then re-mount once it resolves so the first open is already scoped.
+		let tmpScopeBaseFilter = undefined;
+		if (tmpDescriptor.ScopeToRecordSet && tmpDescriptor.FilterByColumn && typeof tmpProvider.getRecordSetColumnDistinct === 'function')
+		{
+			const tmpScopeColumn = tmpDescriptor.FilterByColumn;
+			if (!tmpProvider._scopeDistinctCache || !Array.isArray(tmpProvider._scopeDistinctCache[tmpScopeColumn]))
+			{
+				tmpProvider.getRecordSetColumnDistinct(tmpScopeColumn, () => this._mountQuickFilterEntity(pRecordSet, pViewContext, pMount));
+			}
+			tmpScopeBaseFilter = () =>
+			{
+				const tmpVals = (tmpProvider._scopeDistinctCache || {})[tmpScopeColumn];
+				return (Array.isArray(tmpVals) && tmpVals.length > 0) ? `FBL~${tmpScopeColumn}~INN~${tmpVals.join(',')}` : '';
+			};
+		}
 		const tmpView = tmpPickerProvider.createEntityPicker(`Quick-Picker-${pRecordSet}-${pMount.Field}`,
 		{
 			DestinationAddress: `#${pMount.HostID}`,
@@ -688,6 +705,7 @@ class ViewRecordSetSUBSETFilters extends libPictView
 			TextTemplate: tmpDescriptor.EntityListEntryTemplate || undefined,
 			Placeholder: `Select ${pMount.Label}…`,
 			OnChange: (pValue) => this.applyQuickFilterEntity(pRecordSet, pViewContext, pMount.Field, pMount.ClauseKey, pValue),
+			BaseFilter: tmpScopeBaseFilter,
 		});
 		if (!tmpView) { return; }
 		tmpView.render();
@@ -709,12 +727,18 @@ class ViewRecordSetSUBSETFilters extends libPictView
 		{
 			tmpProvider.upsertQuickFilterClauseValue(pField, pClauseKey, (pValue === undefined || pValue === null) ? '' : String(pValue).trim());
 		}
-		this.handleSearch(null, pRecordSet, pViewContext);
+		// Stage the clause into the active filter state but DON'T fetch — the
+		// user explicitly clicks Apply / Search to commit. Avoids two URL fetches
+		// (one stale, one not) when adjacent inputs change in quick succession
+		// (e.g. the From / To dates of a DateRange both fire `change` events
+		// within ~50ms — the GE-only fetch finishes after the GE+LE fetch and
+		// overwrites the recordset state with stale data).
 	}
 
 	/**
-	 * Apply a date-range quick filter: set one bound (`start`/`end`) of the field's DateRange clause
-	 * (removed when both bounds clear), then run the search.
+	 * Stage one bound (`start`/`end`) of a field's DateRange quick-filter clause.
+	 * Doesn't fire the search — that waits for the user to click Apply / Search,
+	 * so the From and To inputs change once each without racing the fetch.
 	 *
 	 * @param {string} pRecordSet @param {string} pViewContext @param {string} pField @param {string} pClauseKey @param {'start'|'end'} pWhich @param {string} pValue
 	 */
@@ -726,12 +750,11 @@ class ViewRecordSetSUBSETFilters extends libPictView
 		{
 			tmpProvider.upsertQuickFilterDateRange(pField, pClauseKey, pWhich, (pValue === undefined || pValue === null) ? '' : pValue);
 		}
-		this.handleSearch(null, pRecordSet, pViewContext);
 	}
 
 	/**
-	 * Apply an entity quick filter: set the field's entity clause to the picked value (removed when
-	 * cleared), then run the search. Called from the quick-bar picker's OnChange.
+	 * Stage a field's entity quick-filter selection. Doesn't fire the search —
+	 * commit happens on Apply / Search.
 	 *
 	 * @param {string} pRecordSet @param {string} pViewContext @param {string} pField @param {string} pClauseKey @param {any} pValue
 	 */
@@ -743,7 +766,6 @@ class ViewRecordSetSUBSETFilters extends libPictView
 		{
 			tmpProvider.upsertQuickFilterEntity(pField, pClauseKey, pValue);
 		}
-		this.handleSearch(null, pRecordSet, pViewContext);
 	}
 
 	/**

package/source/views/filters/RecordSet-Filter-EntityReference-Base.js

@@ -127,6 +127,25 @@ class ViewRecordSetSUBSETFilterEntityReferenceBase extends ViewRecordSetSUBSETFi
 	 */
 	getContextScopeFilter(pClause)
 	{
+		// ScopeToRecordSet knob: scope the entity search to the values present in the recordset's
+		// data (FBL~<col>~INN~<distinct>), fetched + cached on the recordset provider. The first
+		// search may be unscoped until the fetch resolves; subsequent searches are scoped.
+		if (pClause && pClause.ScopeToRecordSet && pClause.FilterByColumn)
+		{
+			const tmpProvider = this.pict.providers['RSP-Provider-' + pClause.RecordSet];
+			if (tmpProvider && typeof tmpProvider.getRecordSetColumnDistinct === 'function')
+			{
+				if (!tmpProvider._scopeDistinctCache || !Array.isArray(tmpProvider._scopeDistinctCache[pClause.FilterByColumn]))
+				{
+					tmpProvider.getRecordSetColumnDistinct(pClause.FilterByColumn, () => {});
+				}
+				const tmpVals = (tmpProvider._scopeDistinctCache || {})[pClause.FilterByColumn];
+				if (Array.isArray(tmpVals) && tmpVals.length > 0)
+				{
+					return `FBL~${pClause.FilterByColumn}~INN~${tmpVals.join(',')}`;
+				}
+			}
+		}
 		return pClause.ContextScopeFilter || '';
 	}
 

package/source/views/list/RecordSet-List.js

@@ -51,9 +51,9 @@ const _DEFAULT_CONFIGURATION__List = (
 		<section id="PRSP_Filters_Container">
 			{~FV:PRSP-Filters:List~}
 		</section>
-		{~V:PRSP-List-PaginationTop~}
-		{~V:PRSP-List-RecordList~}
-		{~V:PRSP-List-PaginationBottom~}
+		<div id="PRSP_PaginationTop_Container">{~V:PRSP-List-PaginationTop~}</div>
+		<div id="PRSP_RecordList_Container">{~V:PRSP-List-RecordList~}</div>
+		<div id="PRSP_PaginationBottom_Container">{~V:PRSP-List-PaginationBottom~}</div>
 	</section>
 	<!-- DefaultPackage end view template:  [PRSP-List-Template] -->
 	`
@@ -106,6 +106,11 @@ class viewRecordSetList extends libPictRecordSetRecordView
 			recordListEntry: null,
 			paginationBottom: null
 		};
+
+		// Identity (`RecordSet::FilterString::FilterExperience`) of the list currently painted into the DOM.
+		// When a route only changes the page (Offset/PageSize) and this still matches, we re-render just the
+		// rows + pagination instead of the whole view — see handleRecordSetListRoute / _paintRecordList.
+		this._renderedListIdentity = null;
 	}
 
 	handleRecordSetListRoute(pRoutePayload)
@@ -131,7 +136,17 @@ class viewRecordSetList extends libPictRecordSetRecordView
 		const tmpOffset = pRoutePayload.data.Offset ? pRoutePayload.data.Offset : 0;
 		const tmpPageSize = pRoutePayload.data.PageSize ? pRoutePayload.data.PageSize : 100;
 
-		return this.renderList(tmpProviderConfiguration, tmpProviderHash, tmpFilterString, tmpFilterExperience, tmpOffset, tmpPageSize);
+		// Surgical page render: when only the page changed (same RecordSet, FilterString, and
+		// FilterExperience), re-render just the rows + pagination rather than the whole list view. A full
+		// re-render rebuilds the filter view — including all of its picker/control state — which is by far
+		// the most expensive part of a list paint and entirely wasted when only paging. Requires the list to
+		// already be in the DOM (its rows container exists); otherwise we fall through to a full render.
+		const tmpListIdentity = `${pRoutePayload.data.RecordSet}::${tmpFilterString}::${tmpFilterExperience}`;
+		const tmpRenderBodyOnly = (this._renderedListIdentity === tmpListIdentity)
+			&& (this.pict.ContentAssignment.getElement('#PRSP_RecordList_Container').length > 0);
+		this._renderedListIdentity = tmpListIdentity;
+
+		return this.renderList(tmpProviderConfiguration, tmpProviderHash, tmpFilterString, tmpFilterExperience, tmpOffset, tmpPageSize, tmpRenderBodyOnly);
 	}
 
 	addRoutes(pPictRouter)
@@ -174,8 +189,13 @@ class viewRecordSetList extends libPictRecordSetRecordView
 			{
 				return;
 			}
+			// When the list is already on screen, scope the spinner to just the rows area so the title,
+			// filters, and pagination stay put (and the expensive filter view isn't disturbed). On the first
+			// render the rows container doesn't exist yet, so fall back to the whole list destination.
+			const tmpRowsContainerPresent = this.pict.ContentAssignment.getElement('#PRSP_RecordList_Container').length > 0;
+			const tmpDestination = tmpRowsContainerPresent ? '#PRSP_RecordList_Container' : pRecordListData.RenderDestination;
 			this.pict.CSSMap.injectCSS();
-			this.pict.ContentAssignment.assignContent(pRecordListData.RenderDestination, this.pict.parseTemplateByHash('PRSP-List-LoadingShell', pRecordListData));
+			this.pict.ContentAssignment.assignContent(tmpDestination, this.pict.parseTemplateByHash('PRSP-List-LoadingShell', pRecordListData));
 		}
 		catch (pError)
 		{
@@ -230,10 +250,11 @@ class viewRecordSetList extends libPictRecordSetRecordView
 	 * @param {string} pSerializedFilterExperience
 	 * @param {number} pOffset
 	 * @param {number} pPageSize
+	 * @param {boolean} [pBodyOnly] - When true, re-render only the rows + pagination (page change), leaving the filter view intact.
 	 *
 	 * @return {Promise<void>}
 	 */
-	async renderList(pRecordSetConfiguration, pProviderHash, pFilterString, pSerializedFilterExperience, pOffset, pPageSize)
+	async renderList(pRecordSetConfiguration, pProviderHash, pFilterString, pSerializedFilterExperience, pOffset, pPageSize, pBodyOnly)
 	{
 		// Get the records
 		if (!(pProviderHash in this.pict.providers))
@@ -252,7 +273,7 @@ class viewRecordSetList extends libPictRecordSetRecordView
 			}
 			else
 			{
-				return this.renderListFromManifest(tmpManifest, pRecordSetConfiguration, pProviderHash, pFilterString, pSerializedFilterExperience, pOffset, pPageSize);
+				return this.renderListFromManifest(tmpManifest, pRecordSetConfiguration, pProviderHash, pFilterString, pSerializedFilterExperience, pOffset, pPageSize, pBodyOnly);
 			}
 		}
 
@@ -471,25 +492,7 @@ class viewRecordSetList extends libPictRecordSetRecordView
 		}
 		tmpRecordListData = this.onBeforeRenderList(tmpRecordListData);
 
-		this.renderAsync('PRSP_Renderable_List', tmpRecordListData.RenderDestination, tmpRecordListData,
-			function (pError)
-			{
-				if (pError)
-				{
-					this.pict.log.error(`RecordSetList: Error rendering list ${pError}`, tmpRecordListData);
-					return false;
-				}
-
-				if (this.pict.LogNoisiness > 0)
-				{
-					this.pict.log.info(`RecordSetList: Rendered list ${tmpRecordListData.RecordSet} with ${tmpRecordListData.Records.Records.length} records.`, tmpRecordListData);
-				}
-				else
-				{
-					this.pict.log.info(`RecordSetList: Rendered list ${tmpRecordListData.RecordSet} with ${tmpRecordListData.Records.Records.length} records.`);
-				}
-				return true;
-			}.bind(this));
+		this._paintRecordList(tmpRecordListData, pBodyOnly);
 	}
 
 	/**
@@ -500,10 +503,11 @@ class viewRecordSetList extends libPictRecordSetRecordView
 	 * @param {string} pSerializedFilterExperience
 	 * @param {number} pOffset
 	 * @param {number} pPageSize
+	 * @param {boolean} [pBodyOnly] - When true, re-render only the rows + pagination (page change), leaving the filter view intact.
 	 *
 	 * @return {Promise<void>}
 	 */
-	async renderListFromManifest(pManifest, pRecordSetConfiguration, pProviderHash, pFilterString, pSerializedFilterExperience, pOffset, pPageSize)
+	async renderListFromManifest(pManifest, pRecordSetConfiguration, pProviderHash, pFilterString, pSerializedFilterExperience, pOffset, pPageSize, pBodyOnly)
 	{
 		if (!pRecordSetConfiguration)
 		{
@@ -738,24 +742,54 @@ class viewRecordSetList extends libPictRecordSetRecordView
 
 		this.pict.providers.DynamicRecordsetSolver.solveDashboard(pManifest, tmpRecordListData.Records.Records);
 
-		this.renderAsync('PRSP_Renderable_List', tmpRecordListData.RenderDestination, tmpRecordListData,
-			function (pError)
+		this._paintRecordList(tmpRecordListData, pBodyOnly);
+	}
+
+	/**
+	 * Paint the computed record-list data into the DOM.
+	 *
+	 * Full render (pBodyOnly falsy): render the whole `PRSP_Renderable_List` (title, header, filters,
+	 * pagination, rows) into the list destination — the original behavior.
+	 *
+	 * Body-only render (pBodyOnly true): only the page changed, so re-render just the rows and the two
+	 * pagination strips into their stable containers, leaving the filter view (and its picker/control state)
+	 * completely untouched. Each child is rendered with the freshly-computed record passed as an object, so
+	 * it produces exactly what the inline `{~V:~}` render would have.
+	 *
+	 * @param {Record<string, any>} pRecordListData - The fully-computed list data (records, pagination, cells).
+	 * @param {boolean} [pBodyOnly] - When true, surgically re-render only rows + pagination.
+	 * @return {void}
+	 */
+	_paintRecordList(pRecordListData, pBodyOnly)
+	{
+		const fLogRendered = function (pError)
+		{
+			if (pError)
 			{
-				if (pError)
-				{
-					this.pict.log.error(`RecordSetList: Error rendering list ${pError}`, tmpRecordListData);
-					return;
-				}
+				this.pict.log.error(`RecordSetList: Error rendering list ${pError}`, pRecordListData);
+				return;
+			}
+			if (this.pict.LogNoisiness > 0)
+			{
+				this.pict.log.info(`RecordSetList: Rendered list ${pRecordListData.RecordSet} with ${pRecordListData.Records.Records.length} records.`, pRecordListData);
+			}
+			else
+			{
+				this.pict.log.info(`RecordSetList: Rendered list ${pRecordListData.RecordSet} with ${pRecordListData.Records.Records.length} records.`);
+			}
+		}.bind(this);
 
-				if (this.pict.LogNoisiness > 0)
-				{
-					this.pict.log.info(`RecordSetList: Rendered list ${tmpRecordListData.RecordSet} with ${tmpRecordListData.Records.Records.length} records.`, tmpRecordListData);
-				}
-				else
-				{
-					this.pict.log.info(`RecordSetList: Rendered list ${tmpRecordListData.RecordSet} with ${tmpRecordListData.Records.Records.length} records.`);
-				}
-			}.bind(this));
+		if (!pBodyOnly)
+		{
+			this.renderAsync('PRSP_Renderable_List', pRecordListData.RenderDestination, pRecordListData, fLogRendered);
+			return;
+		}
+
+		// Page-only change: re-render the two pagination strips (current page + "showing X of Y") and the
+		// rows, each into its own stable container. The filter view, title, and header list are left as-is.
+		this.childViews.paginationTop.renderAsync('PRSP_Renderable_PaginationTop', '#PRSP_PaginationTop_Container', pRecordListData, null, () => { });
+		this.childViews.paginationBottom.renderAsync('PRSP_Renderable_PaginationBottom', '#PRSP_PaginationBottom_Container', pRecordListData, null, () => { });
+		this.childViews.recordList.renderAsync('PRSP_Renderable_RecordList', '#PRSP_RecordList_Container', pRecordListData, null, fLogRendered);
 	}
 
 	onInitialize()