pict-section-recordset 1.9.6 → 1.10.0

package/README.md

@@ -43,6 +43,44 @@ The control type is inferred from the field's clause (text for a string match, a
 
 **Turning it off.** A single record set opts out with `QuickFilters: false`. To make quick filters **opt-in** across a whole app — only record sets with an explicit `QuickFilters` array show the bar — set the filter view's flag once: `pict.views['PRSP-Filters'].quickFiltersAutoDefault = false`.
 
+## Column Chooser
+
+An opt-in, per-record-set "Columns" button above the list table that lets the user show/hide columns. Three tiers of candidates:
+
+- **Curated** — the columns the host declared (manifest `Descriptors` or `RecordSetListColumns`), in declared order. Default visible; a column or descriptor can ship hidden-by-default with `DefaultHidden: true` (proper display name + cell template, one click away).
+- **Schema** — every remaining scalar column on the entity (identity/audit fields and blob `Text`/`JSON` columns excluded), listed under "More columns", default hidden, rendered with the generic `{~ProcessCell~}` template (entity-reference `ID*` columns resolve names automatically).
+- **Audit** — the identity pair and audit stamps with friendly labels (ID, GUID, Created, Created by, Updated, Updated by, Deleted, Deleted on, Deleted by), listed under "Audit columns", default hidden. The user-reference stamps resolve to user names like any entity column.
+
+```javascript
+{
+    "RecordSet": "Book",
+    "RecordSetListColumnChooser": true,
+    "RecordSetListColumns":
+    [
+        { "Key": "Title" },
+        { "Key": "Genre" },
+        { "Key": "ISBN", "DefaultHidden": true }
+    ]
+}
+```
+
+Toggling a column repaints only the rows + pagination (the filter bar and its state are never re-rendered). Under `RecordSetListLiteFetch`, showing a schema-tier column whose data wasn't fetched triggers exactly one refetch with the projection widened to include it.
+
+**Persistence.** Choices persist per browser in localStorage (`Column_Meta_{RecordSet}_List`), with a session mirror at `pict.Bundle._ActiveColumnState`. To persist somewhere else (e.g. a per-user server preference), register your own provider as `ColumnDataProvider` **before** `PictSectionRecordSet.initialize()` — the section only registers the built-in one when none exists. The class is exported as `PictSectionRecordSet.ColumnDataProvider` for subclassing.
+
+**Host hook note.** `onBeforeRenderList` is (re-)invoked on every paint, including column-visibility repaints. `TableCells` is rebuilt from pristine candidates each paint so cell-level mutations apply exactly once — but record decoration done in the hook must be idempotent. Cells the hook appends are unmanaged by the chooser: they always render and never appear in the chooser list.
+
+## Show Deleted
+
+Meadow soft-deletes: lists normally return only `Deleted = 0` rows. Set `RecordSetListShowDeletedFilter: true` on a record set to add a **"Show deleted"** checkbox to the filter drawer's footer (next to Clear / Reset / Apply). The switch is a **real clause** — a `RawFilter` referencing the Deleted column (`FBL~Deleted~INN~0,1`), which takes over FoxHound's automatic delete tracking so active and deleted rows enumerate together. Because it's a clause:
+
+- It **serializes into the route URL** (the FilterExperience segment) — reloads and shared links keep it.
+- Toggling applies through the normal search flow (the URL always changes, so the fetch always fires).
+- **Clear** drops it like any other clause; the drawer's clause list skips it (the checkbox is its face).
+- Records and counts stay in sync (both flow through the same clause assembly).
+
+Deleted rows render at reduced opacity (`prsp-row-deleted`), and their default **View** link routes to `/PSRS/:RecordSet/ViewDeleted/:GUID` — a read route whose lookup explicitly includes soft-deleted records (a plain View would find nothing) and which renders a "This record has been deleted" banner above the record. Pair with the audit tier's *Deleted / Deleted on / Deleted by* columns in the column chooser.
+
 ## Related Packages
 
 - [pict](https://github.com/fable-retold/pict) - MVC application framework

package/package.json

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

package/source/Pict-Section-RecordSet.js

@@ -10,3 +10,4 @@ module.exports.PictRecordSetApplication = require('./application/Pict-Applicatio
 // Export the providers
 module.exports.RecordSetProviderBase = require('./providers/RecordSet-RecordProvider-Base.js');
 module.exports.RecordSetProviderMeadowEndpoints = require('./providers/RecordSet-RecordProvider-MeadowEndpoints.js');
+module.exports.ColumnDataProvider = require('./providers/Column-Data-Provider.js');

package/source/providers/Column-Data-Provider.js

@@ -0,0 +1,219 @@
+const libPictProvider = require('pict-provider');
+
+const _DEFAULT_PROVIDER_CONFIGURATION =
+{
+	ProviderIdentifier: 'ColumnDataProvider',
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0,
+};
+
+/** Terminology for Column Data Provider (to avoid confusion):
+ * A "Record Set" is a collection of records rendered as a list with columns.
+ * A "Column Visibility Override" is a per-column user choice (true = show, false = hide)
+ *   that overrides the column's default visibility (visible unless DefaultHidden).
+ * Columns with no override entry render at their default visibility.
+
+ * Behavior Summary:
+ * - Save the per-recordset override map to LocalStorage under a key derived from
+ *   Record Set and View Context.
+ * - Mirror the override map into pict.Bundle._ActiveColumnState[RecordSet] so reads
+ *   are synchronous and consistent within a session (the Meadow record provider reads
+ *   this at fetch time to widen Lite projections before the list view composes columns).
+ * - Clear both on "Reset to defaults".
+
+ * Storage Key Structure:
+ * - Column_Meta_{RecordSet}_{ViewContext} : stores the Column Meta JSON.
+
+ * Object Shape for Column Meta:
+ * {
+ *   RecordSet: string, (auto-filled on save)
+ *   ViewContext: string, (auto-filled on save; 'List' for the list view)
+ *   Overrides: { [ColumnKey: string]: boolean },
+ *   LastModifiedDate: string (ISO date) (auto-filled on save)
+ * }
+
+ * Host override contract:
+ * - To persist column choices somewhere other than LocalStorage (e.g. a per-user
+ *   server-side preference), register your own provider AS 'ColumnDataProvider'
+ *   BEFORE PictSectionRecordSet.initialize() runs — the section only registers this
+ *   one when no provider with that hash exists yet. Load remote prefs at app start
+ *   and seed them through setColumnVisibilityOverride (or write the Bundle mirror
+ *   directly); the read methods here must stay synchronous.
+*/
+
+class ColumnDataProvider extends libPictProvider
+{
+	/**
+	 * @param {import('pict')} pFable - The Fable instance
+	 * @param {Record<string, any>} [pOptions] - The options for the provider
+	 * @param {string} [pServiceHash] - The service hash for the provider
+	 */
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, _DEFAULT_PROVIDER_CONFIGURATION, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		// This allows unit tests to run
+		this.storageProvider = this;
+		this.keyCache = {};
+		if ((typeof(window) === 'object') && (typeof(window.localStorage) === 'object'))
+		{
+			this.storageProvider = window.localStorage;
+		}
+	}
+
+	/**
+	 * Resolve the LocalStorage key for a record set's column visibility overrides.
+	 *
+	 * @param {string} pRecordSet - The record set the overrides belong to
+	 * @param {string} [pViewContext] - The view context (defaults to 'List')
+	 * @return {string} The storage key for the column meta record.
+	 */
+	getColumnStorageKey(pRecordSet, pViewContext)
+	{
+		return `Column_Meta_${pRecordSet}_${pViewContext || 'List'}`;
+	}
+
+	/**
+	 * Get the column visibility override map for a record set.
+	 *
+	 * Bundle-first: the session mirror in pict.Bundle._ActiveColumnState wins; on a
+	 * miss the stored meta is read and seeded into the Bundle so every later read
+	 * (including the Meadow provider's fetch-time read) is synchronous and consistent.
+	 *
+	 * @param {string} pRecordSet - The record set to get overrides for
+	 * @param {string} [pViewContext] - The view context (defaults to 'List')
+	 * @return {Record<string, boolean>} The override map (empty object when none).
+	 */
+	getColumnVisibilityOverrides(pRecordSet, pViewContext)
+	{
+		if (!pRecordSet)
+		{
+			return {};
+		}
+		const tmpActiveColumnState = this.pict.Bundle._ActiveColumnState;
+		if (tmpActiveColumnState && tmpActiveColumnState[pRecordSet] && tmpActiveColumnState[pRecordSet].Overrides)
+		{
+			return tmpActiveColumnState[pRecordSet].Overrides;
+		}
+		/** @type {Record<string, boolean>} */
+		let tmpOverrides = {};
+		const tmpColumnMetaJSON = this.storageProvider.getItem(this.getColumnStorageKey(pRecordSet, pViewContext));
+		if (tmpColumnMetaJSON)
+		{
+			try
+			{
+				const tmpColumnMeta = JSON.parse(tmpColumnMetaJSON);
+				if (tmpColumnMeta && typeof(tmpColumnMeta.Overrides) === 'object' && tmpColumnMeta.Overrides !== null)
+				{
+					tmpOverrides = tmpColumnMeta.Overrides;
+				}
+			}
+			catch (pError)
+			{
+				this.pict.log.warn(`ColumnDataProvider: could not parse stored column meta for [${pRecordSet}]: ${pError.message}`);
+			}
+		}
+		this._seedBundleColumnState(pRecordSet, tmpOverrides);
+		return tmpOverrides;
+	}
+
+	/**
+	 * Set (and persist) a single column visibility override for a record set.
+	 *
+	 * @param {string} pRecordSet - The record set the column belongs to
+	 * @param {string} pViewContext - The view context ('List' for the list view; falsy defaults to 'List')
+	 * @param {string} pKey - The column key
+	 * @param {boolean} pVisible - Whether the column should be visible
+	 * @return {Record<string, boolean>} The updated override map.
+	 */
+	setColumnVisibilityOverride(pRecordSet, pViewContext, pKey, pVisible)
+	{
+		const tmpOverrides = this.getColumnVisibilityOverrides(pRecordSet, pViewContext);
+		tmpOverrides[pKey] = (pVisible === true);
+		this._seedBundleColumnState(pRecordSet, tmpOverrides);
+		const tmpColumnMeta =
+		{
+			RecordSet: pRecordSet,
+			ViewContext: pViewContext || 'List',
+			Overrides: tmpOverrides,
+			LastModifiedDate: new Date().toISOString(),
+		};
+		this.storageProvider.setItem(this.getColumnStorageKey(pRecordSet, pViewContext), JSON.stringify(tmpColumnMeta));
+		return tmpOverrides;
+	}
+
+	/**
+	 * Clear all column visibility overrides for a record set (Reset to defaults).
+	 *
+	 * @param {string} pRecordSet - The record set to clear overrides for
+	 * @param {string} [pViewContext] - The view context (defaults to 'List')
+	 * @return {boolean} True when the overrides have been cleared.
+	 */
+	clearColumnVisibilityOverrides(pRecordSet, pViewContext)
+	{
+		this.storageProvider.removeItem(this.getColumnStorageKey(pRecordSet, pViewContext));
+		if (this.pict.Bundle._ActiveColumnState && this.pict.Bundle._ActiveColumnState[pRecordSet])
+		{
+			delete this.pict.Bundle._ActiveColumnState[pRecordSet];
+		}
+		return true;
+	}
+
+	/**
+	 * Write the session mirror of a record set's override map into the Bundle.
+	 *
+	 * @param {string} pRecordSet - The record set the overrides belong to
+	 * @param {Record<string, boolean>} pOverrides - The override map to mirror
+	 */
+	_seedBundleColumnState(pRecordSet, pOverrides)
+	{
+		if (!this.pict.Bundle._ActiveColumnState)
+		{
+			this.pict.Bundle._ActiveColumnState = {};
+		}
+		this.pict.Bundle._ActiveColumnState[pRecordSet] = { Overrides: pOverrides };
+	}
+
+	/** ===== SIMPLE KEY-VALUE CACHE ============= */
+
+	/**
+	 * @param {string} pKey - The key to get from the cache
+	 * @return {any} - The value associated with the key, or null if not found
+	 */
+	getItem(pKey)
+	{
+		if (pKey in this.keyCache)
+		{
+			return this.keyCache[pKey];
+		}
+		return null;
+	}
+
+	/**
+	 * @param {string} pKey - The key to set in the cache
+	 * @param {any} pValue - The value to associate with the key
+	 */
+	setItem(pKey, pValue)
+	{
+		this.keyCache[pKey] = pValue;
+		return true;
+	}
+
+	/**
+	 * @param {string} pKey - The key to remove from the cache
+	 * @return {boolean} - True if the item was removed, false if it was not found
+	 */
+	removeItem(pKey)
+	{
+		if (pKey in this.keyCache)
+		{
+			delete this.keyCache[pKey];
+			return true;
+		}
+		return false;
+	}
+}
+
+module.exports = ColumnDataProvider;
+module.exports.default_configuration = _DEFAULT_PROVIDER_CONFIGURATION;

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

@@ -490,6 +490,57 @@ class RecordSetProviderBase extends libPictProvider
 		}
 	}
 
+	/**
+	 * The entity's soft-delete column name. Subclasses with schema access override this
+	 * (the Meadow provider resolves the column whose Type is 'Deleted').
+	 * @return {string}
+	 */
+	getDeletedField()
+	{
+		return 'Deleted';
+	}
+
+	/** @return {boolean} Whether the show-deleted clause is currently active for this record set. */
+	getShowDeletedFilterValue()
+	{
+		return this.getFilterClauses().some((pClause) => pClause.ShowDeletedKey === 'ShowDeleted');
+	}
+
+	/**
+	 * Toggle the show-deleted clause: a RawFilter stanza that references the Deleted column
+	 * explicitly, which suppresses the automatic `Deleted = 0` delete tracking so soft-deleted
+	 * rows enumerate. It is a real clause in the active filter state, so it serializes into the
+	 * filter experience (and the route URL) and clears with Clear like any other clause. The
+	 * clause list UI skips it (no filter view for RawFilter) — the drawer checkbox is its face.
+	 *
+	 * @param {boolean} pOn - Whether deleted records should be included.
+	 * @return {boolean} The resulting state.
+	 */
+	setShowDeletedFilterValue(pOn)
+	{
+		const tmpClauses = this.getFilterClauses();
+		const tmpIndex = tmpClauses.findIndex((pClause) => pClause.ShowDeletedKey === 'ShowDeleted');
+		if (pOn === true)
+		{
+			if (tmpIndex < 0)
+			{
+				tmpClauses.push(
+					{
+						Type: 'RawFilter',
+						ShowDeletedKey: 'ShowDeleted',
+						Label: 'Show deleted',
+						Value: `FBL~${this.getDeletedField()}~INN~0,1`,
+					});
+			}
+			return true;
+		}
+		if (tmpIndex >= 0)
+		{
+			tmpClauses.splice(tmpIndex, 1);
+		}
+		return false;
+	}
+
 	/** @param {string} pField @return {any} The current value of a field's quick-filter clause, or ''. */
 	getQuickFilterClauseValue(pField)
 	{

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

@@ -161,7 +161,7 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 	}
 
 	getIDField()
-	{ 
+	{
 		if (this._Schema?.MeadowSchema?.Schema?.length)
 		{
 			for (let field of this._Schema.MeadowSchema.Schema)
@@ -175,12 +175,29 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 		return `ID${ this.options.Entity }`;
 	}
 
+	getDeletedField()
+	{
+		if (this._Schema?.MeadowSchema?.Schema?.length)
+		{
+			for (let field of this._Schema.MeadowSchema.Schema)
+			{
+				if (field.Type == 'Deleted')
+				{
+					return field.Column;
+				}
+			}
+		}
+		return 'Deleted';
+	}
+
 	/**
 	 * Get a record by its ID or GUID.
 	 *
 	 * @param {string|number} pGuid - The ID or GUID of the record.
+	 * @param {boolean} [pIncludeDeleted] - When true, also match soft-deleted records (the explicit
+	 *                                      Deleted filter suppresses the automatic `Deleted = 0`).
 	 */
-	async getRecordByGUID(pGuid)
+	async getRecordByGUID(pGuid, pIncludeDeleted)
 	{
 		if (!this.options.Entity)
 		{
@@ -190,9 +207,14 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 		{
 			this.pict.log.info(`Reading ${this.options.Entity} record by GUID`, { GUID: pGuid });
 		}
+		let tmpFilterString = `FBV~${ this.getGUIDField() }~EQ~${encodeURIComponent(pGuid)}`;
+		if (pIncludeDeleted === true)
+		{
+			tmpFilterString += `~FBL~${ this.getDeletedField() }~INN~0,1`;
+		}
 		return new Promise((resolve, reject) =>
 		{
-			this.entityProvider.getEntitySet(this.options.Entity, `FBV~${ this.getGUIDField() }~EQ~${encodeURIComponent(pGuid)}`, (pError, pResult) =>
+			this.entityProvider.getEntitySet(this.options.Entity, tmpFilterString, (pError, pResult) =>
 			{
 				if (pError)
 				{
@@ -223,6 +245,9 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 		{
 			tmpClauses.push({ Type: 'RawFilter', Value: pOptions.FilterString });
 		}
+		// (The show-deleted switch needs no special handling here: it is a real RawFilter clause in
+		// the active filter state — see setShowDeletedFilterValue on the base provider — so it rides
+		// the FilterClauses concat above into both the records and count fetches.)
 		return [ tmpClauses, tmpExperience ];
 	}
 
@@ -280,6 +305,33 @@ class MeadowEndpointsRecordSetProvider extends libRecordSetProviderBase
 				tmpColumns.push(tmpKey);
 			}
 		}
+		// Column chooser: union in user-shown schema-tier columns so a toggled-on column's data is
+		// actually fetched. Same gauntlet as the descriptors; gated on the config flag so stale
+		// stored overrides can never widen queries for lists that don't use the chooser.
+		if (tmpConfig && tmpConfig.RecordSetListColumnChooser === true && this.pict.providers.ColumnDataProvider)
+		{
+			const tmpRecordSet = (pOptions && pOptions.RecordSet) || tmpConfig.RecordSet || pEntity;
+			const tmpOverrides = this.pict.providers.ColumnDataProvider.getColumnVisibilityOverrides(tmpRecordSet, 'List');
+			for (const tmpKey of Object.keys(tmpOverrides))
+			{
+				if (tmpOverrides[tmpKey] !== true)
+				{
+					continue;
+				}
+				if (tmpKey.startsWith('ID') || tmpKey.startsWith('GUID') || tmpKey === 'CreatingIDUser' || tmpKey === 'UpdateDate')
+				{
+					continue;
+				}
+				if (!(tmpKey in tmpColumnType) || tmpBlobTypes[tmpColumnType[tmpKey]])
+				{
+					continue;
+				}
+				if (!tmpColumns.includes(tmpKey))
+				{
+					tmpColumns.push(tmpKey);
+				}
+			}
+		}
 		return tmpColumns;
 	}
 

package/source/services/RecordsSet-MetaController.js

@@ -11,6 +11,7 @@ const ProviderBase = require('../providers/RecordSet-RecordProvider-Base.js');
 const ProviderMeadowEndpoints = require('../providers/RecordSet-RecordProvider-MeadowEndpoints.js');
 
 const ProviderLinkManager = require('../providers/RecordSet-Link-Manager.js');
+const libProviderColumnData = require('../providers/Column-Data-Provider.js');
 
 const ProviderRouter = require('../providers/RecordSet-Router.js');
 
@@ -101,9 +102,20 @@ class RecordSetMetacontroller extends libFableServiceProviderBase
 							resolve(pResult);
 						});
 					});
+					// A dangling reference (the target row no longer exists — e.g. a system user id that
+					// was never seeded) comes back as the endpoint's error body rather than an entity.
+					// Render the raw id, unlinked: it carries more information than a blank cell, and
+					// matches how a found-but-nameless entity already renders.
+					if (!entity || (entity.Error && entity.StatusCode))
+					{
+						return fCallback(null, value);
+					}
 					if (remote === 'User')
 					{
-						value = `${ entity.NameFirst } ${ entity.NameLast }`;
+						// Compose what the user record actually has; fall back through the common
+						// name fields rather than printing "undefined undefined".
+						const tmpUserName = [ entity.NameFirst, entity.NameLast ].filter((pPart) => (typeof(pPart) === 'string') && pPart.trim().length > 0).join(' ');
+						value = tmpUserName || entity.FullName || entity.Name || entity.LoginID || value;
 					}
 					else if (entity?.Name)
 					{
@@ -440,6 +452,13 @@ class RecordSetMetacontroller extends libFableServiceProviderBase
 
 		this.fable.addProvider('RecordSetLinkManager', {}, ProviderLinkManager);
 
+		// Column visibility persistence — only register the built-in localStorage provider when the
+		// host hasn't supplied its own (the documented seam for server-side per-user persistence).
+		if (!('ColumnDataProvider' in this.fable.providers))
+		{
+			this.fable.addProvider('ColumnDataProvider', libProviderColumnData.default_configuration, libProviderColumnData);
+		}
+
 		// Add the subviews internally and externally
 		this.pict.addTemplate(require('../templates/Pict-Template-FilterView.js'));
 		this.pict.addTemplate(require('../templates/Pict-Template-FilterInstanceViews.js'));
@@ -583,6 +602,9 @@ class RecordSetMetacontroller extends libFableServiceProviderBase
 				DisplayName: descriptor.Name || key,
 				ManifestHash: pManifest.Scope,
 				PictDashboard: tmpPictDashboard,
+				// Column-chooser default visibility: a descriptor can ship hidden-by-default and be
+				// turned on by the user (when the recordset enables RecordSetListColumnChooser).
+				DefaultHidden: (descriptor.DefaultHidden === true),
 			};
 		});
 		pManifest.TableCells = tmpTableCells;

package/source/templates/Pict-Template-FilterInstanceViews.js

@@ -78,6 +78,10 @@ class PictTemplateFilterInstanceViewInstruction extends libPictTemplate
 		// not the drawer's clause list — skip them here so they aren't rendered twice. Both the sync and
 		// async render loops treat a null view as "skip this clause".
 		if (pClause && pClause.QuickFilter) { return null; }
+		// The show-deleted switch is a RawFilter clause whose face is the drawer-footer checkbox
+		// (RecordSet-Filters._renderShowDeletedControl) — without this skip it would fall through to
+		// the Base filter card, which renders a debug dump for types with no real filter view.
+		if (pClause && pClause.ShowDeletedKey) { return null; }
 		let tmpViewHash = `PRSP-FilterType-${pClause.Type}`;
 		const tmpCustomViewHash = `${tmpViewHash}-${pClause.CustomFilterViewHash}`;
 		if (tmpCustomViewHash in this.pict.views)

package/source/views/RecordSet-Filters.js

@@ -88,6 +88,12 @@ const _DEFAULT_CONFIGURATION_SUBSET_Filter =
 .prsp-quickfilter-dash { color: var(--theme-color-text-muted, #6b7686); }
 /* Entity quick control: the pict-section-picker mounts into this host (its own .pps chrome themes it). */
 .prsp-quickfilter-entityhost { display: inline-block; width: 14rem; max-width: 100%; vertical-align: middle; }
+/* Show-deleted switch (RecordSetListShowDeletedFilter): a labeled checkbox in the drawer actions row.
+   Painted post-render into the host label; :empty hides it for record sets that haven't opted in. */
+.prsp-filters-showdeleted { display: inline-flex; align-items: center; gap: 0.4rem; cursor: pointer; user-select: none;
+	font-size: 0.88rem; color: var(--theme-color-text-secondary, #45505f); margin-right: 0.35rem; }
+.prsp-filters-showdeleted:empty { display: none; }
+.prsp-filters-showdeleted-checkbox { width: 1.05rem; height: 1.05rem; cursor: pointer; accent-color: var(--theme-color-brand-primary, #156dd1); }
 
 /* Module-owned "Add filter" popover (replaces the old native <select> pickers). */
 /* Fixed (viewport-anchored) + JS-positioned on open, so no ancestor overflow:hidden — the filter card,
@@ -196,6 +202,7 @@ const _DEFAULT_CONFIGURATION_SUBSET_Filter =
 			Template: /*html*/`
 	<!-- DefaultPackage pict view template: [PRSP-SUBSET-Filters-Template-DrawerActions-Fieldset] -->
 	<div class="prsp-filters-actions">
+		<label class="prsp-filters-showdeleted" id="PRSP_ShowDeleted_Host" title="Include soft-deleted records in the results"></label>
 		<button type="button" class="prsp-filters-btn-text" id="PRSP_Filter_Button_Clear" title="Clear all filters to a blank state" onclick="_Pict.views['PRSP-Filters'].handleClear(event, '{~D:Record.RecordSet~}', '{~D:Record.ViewContext~}')">Clear</button>
 		<button type="button" class="prsp-filters-btn-text" id="PRSP_Filter_Button_Reset" title="Reset all filters to the last saved/defaulted state" onclick="_Pict.views['PRSP-Filters'].handleReset(event, '{~D:Record.RecordSet~}', '{~D:Record.ViewContext~}')">Reset</button>
 		<button type="button" class="prsp-filters-apply" id="PRSP_Filter_Button_ApplyDrawer" onclick="_Pict.views['PRSP-Filters'].handleSearch(event, '{~D:Record.RecordSet~}', '{~D:Record.ViewContext~}')">Apply</button>
@@ -719,6 +726,51 @@ class ViewRecordSetSUBSETFilters extends libPictView
 	 *
 	 * @param {string} pRecordSet @param {string} pViewContext @param {string} pField @param {string} pClauseKey @param {string} pValue
 	 */
+	/**
+	 * Flip the show-deleted switch (the drawer-footer checkbox, RecordSetListShowDeletedFilter
+	 * recordsets). The switch is a REAL clause — a RawFilter referencing the Deleted column, which
+	 * suppresses the automatic `Deleted = 0` so soft-deleted rows enumerate — upserted into the
+	 * active filter state and applied through the normal search flow. Because the clause changes
+	 * the serialized filter experience, the route URL always changes: the fetch reliably fires,
+	 * and the state survives reloads and shared links. Clear/Reset drop it like any clause.
+	 *
+	 * @param {string} pRecordSet - The record set the toggle belongs to
+	 * @param {string} pViewContext - The view context (List, Dashboard)
+	 * @param {boolean} pChecked - Whether deleted records should be included
+	 */
+	toggleShowDeletedFilter(pRecordSet, pViewContext, pChecked)
+	{
+		const tmpProvider = this.pict.providers['RSP-Provider-' + pRecordSet];
+		if (!tmpProvider || typeof tmpProvider.setShowDeletedFilterValue !== 'function')
+		{
+			return;
+		}
+		tmpProvider.setShowDeletedFilterValue(pChecked === true);
+		this.handleSearch(null, pRecordSet, pViewContext);
+	}
+
+	/**
+	 * Paint the show-deleted checkbox into its drawer-footer host (next to Clear/Reset/Apply),
+	 * seeded from the clause's presence. Painted post-render like the quick bar; empty when the
+	 * record set hasn't opted in via RecordSetListShowDeletedFilter.
+	 *
+	 * @param {string} pRecordSet @param {string} pViewContext
+	 */
+	_renderShowDeletedControl(pRecordSet, pViewContext)
+	{
+		if (!document.getElementById('PRSP_ShowDeleted_Host')) { return; }
+		const tmpRecordSetConfiguration = this.pict.PictSectionRecordSet?.recordSetProviderConfigurations?.[pRecordSet] || {};
+		if (tmpRecordSetConfiguration.RecordSetListShowDeletedFilter !== true)
+		{
+			this.pict.ContentAssignment.assignContent('#PRSP_ShowDeleted_Host', '');
+			return;
+		}
+		const tmpProvider = this.pict.providers['RSP-Provider-' + pRecordSet];
+		const tmpChecked = (tmpProvider && typeof tmpProvider.getShowDeletedFilterValue === 'function' && tmpProvider.getShowDeletedFilterValue()) ? 'checked' : '';
+		this.pict.ContentAssignment.assignContent('#PRSP_ShowDeleted_Host',
+			`<input class="prsp-filters-showdeleted-checkbox" type="checkbox" ${tmpChecked} onchange="_Pict.views['PRSP-Filters'].toggleShowDeletedFilter('${pRecordSet}', '${pViewContext}', this.checked)"> Show deleted`);
+	}
+
 	applyQuickFilterText(pRecordSet, pViewContext, pField, pClauseKey, pValue)
 	{
 		this.bumpRenderEpoch();
@@ -1162,7 +1214,8 @@ class ViewRecordSetSUBSETFilters extends libPictView
 			if (tmpFilterRecordSet)
 			{
 				this._paintFilterControls(tmpFilterRecordSet);
-					this._renderQuickFilters(tmpFilterRecordSet, tmpFilterViewContext);
+				this._renderQuickFilters(tmpFilterRecordSet, tmpFilterViewContext);
+				this._renderShowDeletedControl(tmpFilterRecordSet, tmpFilterViewContext);
 				// (Re)render the experiences dropdown only when its container is empty — i.e. on
 				// a fresh filter render — not on every sub-render (add-filter dropdown, etc.).
 				const tmpExpContainer = document.getElementById('FilterPersistenceView-Container');