pict-section-picker 1.0.0 → 1.2.0

package/README.md

@@ -117,6 +117,37 @@ Entity-source configuration:
 
 The lower-level builders are also exposed: `createEntityDataProvider(cfg)` and `createEntityResolveValue(cfg)` return the raw functions if you want to wire them yourself.
 
+## Joined display (parent-entity context)
+
+Sometimes a searched entity is ambiguous on its own — a `LineItem` only makes sense next to its `Project`, a `Review` next to its `Book`. Set `JoinEntity` and the picker renders a **compound** label by joining each searched row to a parent entity through a foreign key the row carries:
+
+```javascript
+tmpPicker.createEntityPicker('ReviewPicker',
+{
+    Entity: 'Review',
+    SearchFields: [ 'Summary' ],
+    JoinEntity: 'Book',                 // the parent entity to join
+    JoinField: 'IDBook',                // the FK on the Review row -> Book
+    JoinEntityDisplayField: 'Title',    // the Book field to show
+    DestinationAddress: '#ReviewPicker',
+    ValueAddress: 'AppData.Form.IDReview',
+});
+// options render as "Neuromancer - Loved it"; the Value is still IDReview.
+```
+
+Meadow can't join in a single read, so this is **fetch-then-merge**: after each search page the picker collects the rows' unique FK ids and issues **one** `FBL~ID{JoinEntity}~INN~<ids>` request, then stitches the joined display onto every row (also exposed as `Record.JoinName` / `Record.JoinRecord` for `MapRecord` / templates). The same join resolves a pre-bound value's label on first render.
+
+| Option | Default | Purpose |
+|---|---|---|
+| `JoinEntity` | — | Parent entity to join for the compound display. Setting it enables the feature. |
+| `JoinField` | `ID<JoinEntity>` | The FK column **on the searched row** pointing at `JoinEntity`. |
+| `JoinEntityValueField` | `ID<JoinEntity>` | The PK column on `JoinEntity` to match (the `INN` column). |
+| `JoinEntityDisplayField` | `'Name'` | The `JoinEntity` field shown in the compound label. |
+| `JoinEntityFirst` | `true` | `true` → `Parent - Row`; `false` → `Row - Parent`. |
+| `JoinSeparator` | `' - '` | Separator between the two parts. |
+
+The same options ride through the form-input adapter (`PictForm.JoinEntity`, …) and the pict-section-recordset entity filters (set `JoinEntity` on the clause) — so an entity filter can show parent context for its options with no host code, layered on top of either the 1:1 (direct-FK / `InternalJoin`) or 1:many (junction / `ExternalJoin`) filter relationship.
+
 ## Categories
 
 Give option rows an optional `Group` field and the list renders headered sections (preserving order; rows without a `Group` fall into a leading unlabeled section):
@@ -162,6 +193,24 @@ OnCreate: (pTerm) =>
 | `OnCreate` | — | `(term) => {Value, Text}` to enable creatable entries. |
 | `OnChange` | — | Called after a selection: single → `(value, record)`, multi → `(values, records)`. |
 
+## View methods
+
+Call these on the picker view instance — `this.pict.views['<hash>']`:
+
+| Method | Description |
+|--------|-------------|
+| `render()` | Paint (or repaint) the control into its destination. |
+| `getValue()` | The current selection — a scalar in single mode, an array of values in multi mode. |
+| `setValue(pValue)` | Set the selection programmatically — the supported counterpart to `getValue()`. Single mode takes a scalar; multi mode takes an array (or a csv string). Writes through to the bound address(es), resolves the display label of any unknown value (from the loaded options, else via `ResolveValue` in async mode), and repaints. Does **not** fire `OnChange` — it is a programmatic set (e.g. a host marshaling a form value into the control), not a user pick. Returns the view for chaining. |
+| `getSelectedRecords()` | (multi) The full `{Value, Text}` record list for the current selection. |
+
+```javascript
+const tmpPicker = this.pict.views['AuthorPicker'];
+tmpPicker.setValue(141);            // single: select author 141 (label resolves via ResolveValue if async)
+tmpPicker.setValue([ 2, 10, 141 ]); // multi: select these values (array or "2,10,141" csv both accepted)
+const tmpSelected = tmpPicker.getValue();
+```
+
 ## Theming
 
 The widget paints from `--theme-color-*` tokens with sensible hex fallbacks, so it inherits the host app's theme. Relevant tokens: `--theme-color-brand-primary`, `--theme-color-text-primary`, `--theme-color-text-muted`, `--theme-color-border-default`, `--theme-color-border-light`, `--theme-color-border-strong`, `--theme-color-background-primary`, `--theme-color-background-panel`, `--theme-color-background-tertiary`.

package/form.js

@@ -0,0 +1,5 @@
+// Sub-path entry: `require('pict-section-picker/form')`.
+//
+// The pict-section-form input-type adapter — kept off the package's main entry so the picker core
+// stays usable without pict-section-form (which is an OPTIONAL peer dependency, required only here).
+module.exports = require('./source/form/Pict-Section-Picker-FormInput.js');

package/package.json

@@ -1,12 +1,13 @@
 {
 	"name": "pict-section-picker",
-	"version": "1.0.0",
+	"version": "1.2.0",
 	"description": "Pict-native themeable searchable select / combobox — single & multi select, server pagination, categorized groups and creatable entries, driven by a host-agnostic async DataProvider (with a built-in Meadow EntityProvider adapter). A jQuery/select2-free replacement.",
 	"main": "source/Pict-Section-Picker.js",
 	"types": "types/Pict-Section-Picker.d.ts",
 	"files": [
 		"source",
-		"types"
+		"types",
+		"form.js"
 	],
 	"scripts": {
 		"test": "npx mocha -u tdd -R spec",
@@ -48,11 +49,20 @@
 		"pict-provider": "^1.0.13",
 		"pict-view": "^1.0.68"
 	},
+	"peerDependencies": {
+		"pict-section-form": ">=1.0.0"
+	},
+	"peerDependenciesMeta": {
+		"pict-section-form": {
+			"optional": true
+		}
+	},
 	"devDependencies": {
 		"@types/mocha": "^10.0.10",
 		"@types/node": "^16.18.126",
 		"browser-env": "^3.3.0",
 		"pict": "^1.0.372",
+		"pict-section-form": "^1.0.0",
 		"quackage": "^1.3.0",
 		"typescript": "^5.9.3"
 	}

package/source/form/Pict-Section-Picker-FormInput.js

@@ -0,0 +1,307 @@
+/**
+ * pict-section-form input-type adapter for pict-section-picker.
+ *
+ * Renders a picker widget into a dynamic-form cell — the host-agnostic replacement for a select2
+ * entity input. Registered as a pict-section-form InputType (default name `Picker`); a host opts a
+ * field in with `PictForm.InputType: 'Picker'` (+ Entity / SearchFields / Multiple / …). Used by the
+ * pict-section-recordset entity filters and by document forms alike.
+ *
+ * Contextual scoping (project / spec-year / tenant / …) stays host configuration: the descriptor may
+ * carry a `PictForm.GetContextScopeFilter()` hook, OR a host subclass overrides
+ * `getContextualSearchFilters(pInput)`. Either way the module never learns what the context means.
+ *
+ * Requires `pict-section-form` (an OPTIONAL peer dependency — only loaded when you require this file)
+ * and the `Pict-Section-Picker` provider registered on the pict instance.
+ */
+const libPictInputExtension = require('pict-section-form').PictInputExtensionProvider;
+
+/** @type {Record<string, any>} */
+const _DEFAULT_CONFIGURATION =
+{
+	ProviderIdentifier: 'Pict-Input-Picker',
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0,
+	AutoSolveWithApp: false,
+};
+
+/**
+ * Build the InputType metatemplate entries (a hidden informary input + a host element the picker
+ * renders into) for a given InputType name + provider hash. Injected via injectTemplateSet.
+ *
+ * @param {string} pInputTypeName - e.g. 'Picker'.
+ * @param {string} pProviderHash - the input-extension provider service hash to auto-attach.
+ * @return {Array<Record<string, any>>}
+ */
+const buildPickerInputTemplates = (pInputTypeName, pProviderHash) =>
+[
+	{
+		// Mirror the host's DEFAULT input metatemplate structure exactly — a label span + the control
+		// where the <input>/<select> would be — so the picker inherits the host's filter/form chrome
+		// (label style, spacing, and the row's flex-end trash alignment) instead of inventing its own.
+		HashPostfix: `-Template-Input-InputType-${pInputTypeName}`,
+		DefaultInputExtensions: [ pProviderHash ],
+		Template: /*html*/`
+			<!-- InputType ${pInputTypeName} {~D:Record.Hash~} {~D:Record.DataType~} -->
+			<input type="hidden" id="{~D:Record.Macro.RawHTMLID~}" tabindex="-1" {~D:Record.Macro.InputFullProperties~} {~D:Record.Macro.InputChangeHandler~} value="" />
+			<span>{~D:Record.Name~}:</span> <div class="pps-form-host" id="PICKER-FOR-{~D:Record.Macro.RawHTMLID~}"></div>`,
+	},
+	{
+		HashPostfix: `-VerticalTemplate-Input-InputType-${pInputTypeName}`,
+		DefaultInputExtensions: [ pProviderHash ],
+		Template: /*html*/`
+			<!-- InputType ${pInputTypeName} {~D:Record.Hash~} {~D:Record.DataType~} -->
+			<input type="hidden" id="{~D:Record.Macro.RawHTMLID~}" tabindex="-1" {~D:Record.Macro.InputFullProperties~} {~D:Record.Macro.InputChangeHandler~} value="" />
+			<span>{~D:Record.Name~}:</span> <div class="pps-form-host" id="PICKER-FOR-{~D:Record.Macro.RawHTMLID~}"></div>`,
+	},
+	{
+		HashPostfix: `-TabularTemplate-Begin-Input-InputType-${pInputTypeName}`,
+		DefaultInputExtensions: [ pProviderHash ],
+		Template: /*html*/`
+			<input type="hidden" id="PICKER-TABULAR-DATA-{~D:Record.Macro.RawHTMLID~}-{~D:Context[2].Key~}" tabindex="-1" {~D:Record.Macro.InformaryTabular~} `,
+	},
+	{
+		HashPostfix: `-TabularTemplate-End-Input-InputType-${pInputTypeName}`,
+		DefaultInputExtensions: [ pProviderHash ],
+		Template: /*html*/`
+			value="" />
+			<div class="pps-form-host" id="PICKER-TABULAR-{~D:Record.Macro.RawHTMLID~}-{~D:Context[2].Key~}"></div>`,
+	},
+];
+
+class PictInputTypePicker extends libPictInputExtension
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({}, _DEFAULT_CONFIGURATION, pOptions), pServiceHash);
+		/** @type {any} */
+		this.pict;
+	}
+
+	// Visible host + picker-view-hash ids. Must match the metatemplate element ids above.
+	getPickerHostID(pRawHTMLID) { return `#PICKER-FOR-${pRawHTMLID}`; }
+	getPickerHash(pRawHTMLID) { return `Picker-${pRawHTMLID}`; }
+	getTabularPickerHostID(pRawHTMLID, pRowIndex) { return `#PICKER-TABULAR-${pRawHTMLID}-${pRowIndex}`; }
+	getTabularPickerHash(pRawHTMLID, pRowIndex) { return `Picker-${pRawHTMLID}-${pRowIndex}`; }
+	getTabularHiddenID(pRawHTMLID, pRowIndex) { return `#PICKER-TABULAR-DATA-${pRawHTMLID}-${pRowIndex}`; }
+
+	/**
+	 * Overridable: extra FoxHound scope stanza(s) AND-applied to the entity search. Default reads the
+	 * descriptor's `GetContextScopeFilter()` hook (set by the host / recordset filter base), else its
+	 * static `BaseFilter`. Host subclasses override this to read app state (project / spec-year / …).
+	 *
+	 * @param {Record<string, any>} pInput @return {string|Array<string>}
+	 */
+	getContextualSearchFilters(pInput)
+	{
+		const tmpHook = pInput && pInput.PictForm && pInput.PictForm.GetContextScopeFilter;
+		if (typeof tmpHook === 'function')
+		{
+			try { return tmpHook() || ''; }
+			catch (pError) { this.pict.log.warn(`Pict-Input-Picker: GetContextScopeFilter threw.`, pError); return ''; }
+		}
+		return (pInput && pInput.PictForm && pInput.PictForm.BaseFilter) || '';
+	}
+
+	/** Build the picker config from a form input descriptor. */
+	_buildPickerConfig(pInput, pHostSelector, fOnChange)
+	{
+		const tmpPF = pInput.PictForm || {};
+		return {
+			DestinationAddress: pHostSelector,
+			Mode: tmpPF.Multiple ? 'multi' : 'single',
+			Placeholder: tmpPF.Placeholder || (tmpPF.Entity ? `Select ${tmpPF.Entity}…` : 'Select…'),
+			Searchable: (tmpPF.Searchable !== false),
+			Entity: tmpPF.Entity,
+			SearchFields: tmpPF.SearchFields,
+			ValueField: tmpPF.ValueField,
+			TextField: tmpPF.TextField,
+			PageSize: tmpPF.PageSize || 20,
+			Options: tmpPF.Options || [],
+			// JoinEntity compound display (1:1 / 1:many parent-entity context) — passed straight through
+			// to the picker's entity adapter, which fetch-then-merges the join. No-op when JoinEntity unset.
+			JoinEntity: tmpPF.JoinEntity,
+			JoinField: tmpPF.JoinField,
+			JoinEntityValueField: tmpPF.JoinEntityValueField,
+			JoinEntityDisplayField: tmpPF.JoinEntityDisplayField,
+			JoinEntityFirst: tmpPF.JoinEntityFirst,
+			JoinSeparator: tmpPF.JoinSeparator,
+			// Per-search contextual scope — the generic hook the host fills.
+			BaseFilter: () => this.getContextualSearchFilters(pInput),
+			OnChange: fOnChange,
+		};
+	}
+
+	/** Instantiate (or reuse) the picker view for a config — entity-backed when Entity is set. */
+	_instantiatePicker(pPickerHash, pConfig)
+	{
+		const tmpProvider = this.pict.providers['Pict-Section-Picker'];
+		if (!tmpProvider)
+		{
+			this.pict.log.warn('Pict-Input-Picker: the Pict-Section-Picker provider is not registered.');
+			return null;
+		}
+		return pConfig.Entity
+			? tmpProvider.createEntityPicker(pPickerHash, pConfig)
+			: tmpProvider.createPicker(pPickerHash, pConfig);
+	}
+
+	/**
+	 * Write a picker value into the form: csv to the hidden informary input (+ dataChanged), plus the
+	 * raw array to `PictForm.ValueArrayAddress` when set (the recordset filter reads Values as an
+	 * array). The csv-vs-array bridge lives HERE (generic) instead of in each host.
+	 */
+	_commit(pView, pInput, pValue, pHTMLSelector)
+	{
+		const tmpCSV = Array.isArray(pValue) ? pValue.join(',') : (pValue === undefined || pValue === null ? '' : pValue);
+		this.pict.ContentAssignment.assignContent(pHTMLSelector, tmpCSV);
+		if (pInput.PictForm && pInput.PictForm.ValueArrayAddress && pView.Bundle)
+		{
+			const tmpArray = Array.isArray(pValue) ? pValue : (tmpCSV === '' ? [] : String(tmpCSV).split(','));
+			this.pict.manifest.setValueAtAddress(pView.Bundle, pInput.PictForm.ValueArrayAddress, tmpArray);
+		}
+		pView.dataChanged(pInput.Hash);
+	}
+
+	_commitTabular(pView, pInput, pValue, pHiddenID, pRowIndex)
+	{
+		const tmpCSV = Array.isArray(pValue) ? pValue.join(',') : (pValue === undefined || pValue === null ? '' : pValue);
+		this.pict.ContentAssignment.assignContent(pHiddenID, tmpCSV);
+		pView.dataChangedTabular(pInput.PictForm.GroupIndex, pInput.PictForm.InputIndex, pRowIndex);
+	}
+
+	/**
+	 * Idempotently mount (or reuse) the picker into its host element + seed its value. Called from both
+	 * onInputInitialize and onDataMarshalToForm because, in the async-virtual filter render, the host
+	 * element only exists in the real DOM by the marshal pass — whichever hook fires post-DOM wins, and
+	 * re-calls are harmless (the picker view is reused by hash).
+	 * @return {boolean} true if the picker is mounted.
+	 */
+	_mountPicker(pView, pInput, pValue, pHostSelector, pPickerHash, fOnChange)
+	{
+		if (!this.pict.ContentAssignment.getElement(pHostSelector)?.[0]) { return false; }
+		const tmpView = this._instantiatePicker(pPickerHash, this._buildPickerConfig(pInput, pHostSelector, fOnChange));
+		if (!tmpView) { return false; }
+		tmpView.render();
+		tmpView.setValue(pValue);
+		return true;
+	}
+
+	// --- non-tabular lifecycle ---
+
+	onInputInitialize(pView, pGroup, pRow, pInput, pValue, pHTMLSelector, pTransactionGUID)
+	{
+		const tmpRaw = pInput.Macro.RawHTMLID;
+		this._mountPicker(pView, pInput, pValue, this.getPickerHostID(tmpRaw), this.getPickerHash(tmpRaw),
+			(pNewValue) => this._commit(pView, pInput, pNewValue, pInput.Macro.HTMLSelector));
+		return super.onInputInitialize(pView, pGroup, pRow, pInput, pValue, pHTMLSelector, pTransactionGUID);
+	}
+
+	onDataMarshalToForm(pView, pGroup, pRow, pInput, pValue, pHTMLSelector, pTransactionGUID)
+	{
+		const tmpRaw = pInput.Macro.RawHTMLID;
+		const tmpPickerHash = this.getPickerHash(tmpRaw);
+		// Mount if it isn't already (post-DOM hook), else just re-seed the value.
+		if (!this._mountPicker(pView, pInput, pValue, this.getPickerHostID(tmpRaw), tmpPickerHash,
+			(pNewValue) => this._commit(pView, pInput, pNewValue, pInput.Macro.HTMLSelector)))
+		{
+			const tmpView = this.pict.views[tmpPickerHash];
+			if (tmpView) { tmpView.setValue(pValue); }
+		}
+		return super.onDataMarshalToForm(pView, pGroup, pRow, pInput, pValue, pHTMLSelector, pTransactionGUID);
+	}
+
+	onDataRequest(pView, pInput, pValue, pHTMLSelector)
+	{
+		const tmpView = this.pict.views[this.getPickerHash(pInput.Macro.RawHTMLID)];
+		const tmpVal = tmpView ? tmpView.getValue() : pValue;
+		this._commit(pView, pInput, tmpVal, pHTMLSelector);
+		return super.onDataRequest(pView, pInput, tmpVal, pHTMLSelector);
+	}
+
+	// --- tabular lifecycle (one picker view instance per (input, row)) ---
+
+	/** Idempotent tabular mount (see _mountPicker). @return {boolean} */
+	_mountPickerTabular(pView, pInput, pValue, pRowIndex)
+	{
+		const tmpRaw = pInput.Macro.RawHTMLID;
+		const tmpHostSelector = this.getTabularPickerHostID(tmpRaw, pRowIndex);
+		if (!this.pict.ContentAssignment.getElement(tmpHostSelector)?.[0]) { return false; }
+		const tmpHiddenID = this.getTabularHiddenID(tmpRaw, pRowIndex);
+		const tmpView = this._instantiatePicker(this.getTabularPickerHash(tmpRaw, pRowIndex),
+			this._buildPickerConfig(pInput, tmpHostSelector, (pNewValue) => this._commitTabular(pView, pInput, pNewValue, tmpHiddenID, pRowIndex)));
+		if (!tmpView) { return false; }
+		tmpView.render();
+		tmpView.setValue(pValue);
+		return true;
+	}
+
+	onInputInitializeTabular(pView, pGroup, pInput, pValue, pHTMLSelector, pRowIndex, pTransactionGUID)
+	{
+		this._mountPickerTabular(pView, pInput, pValue, pRowIndex);
+		return super.onInputInitializeTabular(pView, pGroup, pInput, pValue, pHTMLSelector, pRowIndex, pTransactionGUID);
+	}
+
+	onDataMarshalToFormTabular(pView, pGroup, pInput, pValue, pHTMLSelector, pRowIndex, pTransactionGUID)
+	{
+		if (!this._mountPickerTabular(pView, pInput, pValue, pRowIndex))
+		{
+			const tmpView = this.pict.views[this.getTabularPickerHash(pInput.Macro.RawHTMLID, pRowIndex)];
+			if (tmpView) { tmpView.setValue(pValue); }
+		}
+		return super.onDataMarshalToFormTabular(pView, pGroup, pInput, pValue, pHTMLSelector, pRowIndex, pTransactionGUID);
+	}
+
+	onDataRequestTabular(pView, pInput, pValue, pHTMLSelector, pRowIndex)
+	{
+		const tmpView = this.pict.views[this.getTabularPickerHash(pInput.Macro.RawHTMLID, pRowIndex)];
+		const tmpVal = tmpView ? tmpView.getValue() : pValue;
+		this._commitTabular(pView, pInput, tmpVal, this.getTabularHiddenID(pInput.Macro.RawHTMLID, pRowIndex), pRowIndex);
+		return super.onDataRequestTabular(pView, pInput, tmpVal, pHTMLSelector, pRowIndex);
+	}
+}
+
+/**
+ * Register the Picker InputType on a pict instance: the input-extension provider + its metatemplate(s).
+ * Idempotent. Requires `pict-section-form` loaded (PictFormSectionDefaultTemplateProvider present) and
+ * the `Pict-Section-Picker` provider registered.
+ *
+ * @param {any} pPict - the pict instance.
+ * @param {Record<string, any>} [pOptions]
+ *   - InputTypeName {string} - the InputType string (default 'Picker').
+ *   - ProviderHash {string} - the input-extension provider service hash (default 'Pict-Input-Picker').
+ *   - ProviderClass {Function} - provider class to register (default PictInputTypePicker; a host
+ *     passes a subclass that overrides getContextualSearchFilters for its scoping).
+ *   - TemplatePrefix {string|Array<string>} - the form template prefix(es) to inject the metatemplate
+ *     under (default 'Pict-MT-Base'; Headlight uses its theme prefixes).
+ * @return {boolean} true if registered.
+ */
+const registerPickerInputType = (pPict, pOptions) =>
+{
+	const tmpOptions = pOptions || {};
+	const tmpInputTypeName = tmpOptions.InputTypeName || 'Picker';
+	const tmpProviderHash = tmpOptions.ProviderHash || 'Pict-Input-Picker';
+	const tmpProviderClass = tmpOptions.ProviderClass || PictInputTypePicker;
+	const tmpPrefixes = Array.isArray(tmpOptions.TemplatePrefix) ? tmpOptions.TemplatePrefix : [ tmpOptions.TemplatePrefix || 'Pict-MT-Base' ];
+
+	if (!pPict.providers[tmpProviderHash])
+	{
+		pPict.addProvider(tmpProviderHash, Object.assign({}, _DEFAULT_CONFIGURATION, { ProviderIdentifier: tmpProviderHash }), tmpProviderClass);
+	}
+
+	const tmpTemplateProvider = pPict.providers.PictFormSectionDefaultTemplateProvider;
+	if (!tmpTemplateProvider || typeof tmpTemplateProvider.injectTemplateSet !== 'function')
+	{
+		pPict.log.warn('Pict-Input-Picker: PictFormSectionDefaultTemplateProvider not available; cannot register the Picker metatemplate (is pict-section-form loaded?).');
+		return false;
+	}
+	const tmpTemplates = buildPickerInputTemplates(tmpInputTypeName, tmpProviderHash);
+	tmpPrefixes.forEach((pPrefix) => tmpTemplateProvider.injectTemplateSet({ TemplatePrefix: pPrefix, Templates: tmpTemplates }));
+	return true;
+};
+
+module.exports = PictInputTypePicker;
+
+module.exports.PictInputTypePicker = PictInputTypePicker;
+module.exports.registerPickerInputType = registerPickerInputType;
+module.exports.buildPickerInputTemplates = buildPickerInputTemplates;
+module.exports.default_configuration = _DEFAULT_CONFIGURATION;

package/source/providers/Pict-Provider-Picker.js

@@ -31,9 +31,15 @@ const _PickerCSS = /*css*/`
 .pps-chip-x { flex: 0 0 auto; display: inline-flex; align-items: center; cursor: pointer; font-size: 0.78rem; border-radius: 4px; padding: 0.1rem; opacity: 0.7; }
 .pps-chip-x:hover { opacity: 1; background: color-mix(in srgb, var(--theme-color-brand-primary, #156dd1) 22%, transparent); }
 
-/* Transparent full-viewport backdrop: closes on outside click (no document listener). */
-.pps-backdrop { position: fixed; inset: 0; z-index: 0; }
-.pps-pop { position: absolute; z-index: 40; top: calc(100% + 0.3rem); left: 0; right: 0; min-width: 200px; display: none; }
+/* Transparent full-viewport backdrop: closes on outside click (no document listener). Only present
+   while OPEN — otherwise a fixed full-viewport layer would swallow every click on the page. When open,
+   the control is raised above it so its chips/× stay clickable; the dropdown sits above both. */
+.pps-backdrop { position: fixed; inset: 0; z-index: 0; display: none; }
+.pps.pps-open .pps-backdrop { display: block; }
+.pps.pps-open .pps-control { position: relative; z-index: 1; }
+/* Fixed (viewport-anchored) + JS-positioned in open(), so no ancestor's overflow:hidden — a card, a
+   slide-out drawer, a scroll pane — can ever clip the dropdown, whatever the host's layout. */
+.pps-pop { position: fixed; z-index: 40; min-width: 200px; display: none; }
 .pps.pps-open .pps-pop { display: block; }
 .pps-panel { position: relative; z-index: 1; display: flex; flex-direction: column; max-height: min(60vh, 360px);
 	background: var(--theme-color-background-panel, #fff); border: 1px solid var(--theme-color-border-default, #d7dce3);
@@ -60,6 +66,10 @@ const _PickerCSS = /*css*/`
 	padding: 0.45rem 0.6rem; border: none; border-radius: 6px; background: transparent; color: var(--theme-color-brand-primary, #156dd1); font-weight: 600; }
 .pps-create:hover { background: var(--theme-color-background-tertiary, #eceef2); }
 .pps-create-ic { flex: 0 0 auto; display: inline-flex; }
+
+/* Form-input adapter (pict-section-picker/form): the picker host fills its row like the host's
+   native inputs (width:100% forces it to wrap below the label span + fill, matching a scalar input). */
+.pps-form-host { flex: 1 1 100%; min-width: 0; width: 100%; }
 `;
 
 /** @type {Record<string, any>} */
@@ -159,8 +169,22 @@ class PictProviderPicker extends libPictProvider
 	 *   - TextField {string} - record field used as the option Text (default `Name`).
 	 *   - PageSize {number} - records per page (default 20).
 	 *   - Sort {string} - optional field to sort ascending (adds `FSF~<field>~ASC~0`).
-	 *   - BaseFilter {string} - optional always-applied FoxHound filter (AND), e.g. `FBV~IDCustomer~EQ~1`.
+	 *   - BaseFilter {string|Array<string>|function} - optional always-applied FoxHound filter (AND),
+	 *     e.g. `FBV~IDCustomer~EQ~1`. May be a **function** `(searchTerm, page) => string|string[]`
+	 *     evaluated on every search — the generic hook for host-injected CONTEXTUAL scoping (project,
+	 *     tenant, spec-year, …). The module stays agnostic; the host supplies the closure.
 	 *   - MapRecord {function} - optional `(record) => {Value, Text}` mapper (overrides Value/TextField).
+	 *   - JoinEntity {string} - optional second entity to JOIN for a compound display (e.g. a `LineItem`
+	 *     shown with its `Project`). Each searched row must carry the FK (`JoinField`). Because Meadow
+	 *     can't join in one read, this is fetch-then-merge: after the primary page resolves, the unique
+	 *     FK ids drive ONE `FBL~ID{JoinEntity}~INN~<ids>` request, and the joined display field is
+	 *     stitched onto each row (as `Record.JoinName` / `Record.JoinRecord`) + composed into the Text.
+	 *   - JoinField {string} - the FK column ON THE SEARCHED ROW pointing at JoinEntity (default `ID{JoinEntity}`).
+	 *   - JoinEntityValueField {string} - the PK column on JoinEntity to match (default `ID{JoinEntity}`).
+	 *   - JoinEntityDisplayField {string} - the JoinEntity field to display (default `Name`).
+	 *   - JoinEntityFirst {boolean} - put the joined value first in the compound (default `true`):
+	 *     `JoinName - baseText`; when `false`, `baseText - JoinName`.
+	 *   - JoinSeparator {string} - the compound separator (default `' - '`).
 	 * @return {(pSearchTerm: string, pPage: number) => Promise<{results: Array<any>, hasMore: boolean}>}
 	 */
 	createEntityDataProvider(pConfig)
@@ -171,8 +195,9 @@ class PictProviderPicker extends libPictProvider
 		const tmpTextField = pConfig.TextField || 'Name';
 		const tmpPageSize = pConfig.PageSize || 20;
 		const tmpSort = pConfig.Sort || false;
-		const tmpBaseFilter = pConfig.BaseFilter || '';
+		const tmpBaseFilterConfig = pConfig.BaseFilter || '';
 		const tmpMapRecord = (typeof pConfig.MapRecord === 'function') ? pConfig.MapRecord : false;
+		const tmpJoinConfig = this._resolveJoinConfig(pConfig);
 
 		return (pSearchTerm, pPage) => new Promise((resolve, reject) =>
 		{
@@ -181,6 +206,17 @@ class PictProviderPicker extends libPictProvider
 				return reject(new Error('Pict-Section-Picker: pict.EntityProvider is not available for entity-backed pickers.'));
 			}
 
+			// Resolve the base filter at SEARCH time. A function form lets the host inject contextual
+			// scoping (e.g. "only this project's line items") without the module knowing the context;
+			// it can return a single stanza, an array of stanzas, or nothing.
+			let tmpBaseFilter = tmpBaseFilterConfig;
+			if (typeof tmpBaseFilterConfig === 'function')
+			{
+				try { tmpBaseFilter = tmpBaseFilterConfig(pSearchTerm, pPage); }
+				catch (pScopeError) { this.pict.log.warn(`Pict-Section-Picker [${tmpEntity}] BaseFilter() threw; ignoring contextual scope.`, pScopeError); tmpBaseFilter = ''; }
+			}
+			if (Array.isArray(tmpBaseFilter)) { tmpBaseFilter = tmpBaseFilter.filter(Boolean).join('~'); }
+
 			const tmpStanzas = [];
 			if (tmpBaseFilter) { tmpStanzas.push(tmpBaseFilter); }
 			if (pSearchTerm) { tmpStanzas.push(this.buildSearchFilter(tmpSearchFields, pSearchTerm)); }
@@ -193,11 +229,103 @@ class PictProviderPicker extends libPictProvider
 				{
 					if (pError) { return reject(pError); }
 					const tmpList = Array.isArray(pRecords) ? pRecords : [];
-					const tmpResults = tmpList.map((pRecord) => tmpMapRecord
-						? tmpMapRecord(pRecord)
-						: { Value: pRecord[tmpValueField], Text: pRecord[tmpTextField], Record: pRecord });
-					// hasMore: a full page came back, so there is (probably) another. Avoids a Count round-trip.
-					return resolve({ results: tmpResults, hasMore: (tmpList.length >= tmpPageSize) });
+					// JoinEntity (when configured): one INN fetch for the joined rows, stitched onto each
+					// searched row, before mapping — so the option Text can show the compound display.
+					this._decorateRecordsWithJoin(tmpList, tmpJoinConfig).then((pDecorated) =>
+					{
+						const tmpResults = pDecorated.map((pRecord) =>
+						{
+							if (tmpMapRecord) { return tmpMapRecord(pRecord); }
+							const tmpText = tmpJoinConfig
+								? this._composeJoinedText(pRecord[tmpTextField], pRecord.JoinName, tmpJoinConfig.First, tmpJoinConfig.Separator)
+								: pRecord[tmpTextField];
+							return { Value: pRecord[tmpValueField], Text: tmpText, Record: pRecord };
+						});
+						// hasMore: a full page came back, so there is (probably) another. Avoids a Count round-trip.
+						return resolve({ results: tmpResults, hasMore: (tmpList.length >= tmpPageSize) });
+					});
+				});
+		});
+	}
+
+	/**
+	 * Resolve the JoinEntity options off an entity-source config into a normalized internal shape, or
+	 * `false` when no JoinEntity is configured. Centralizes the defaults so the DataProvider and the
+	 * ResolveValue builders agree.
+	 *
+	 * @param {Record<string, any>} pConfig
+	 * @return {false | {Entity:string, FKColumn:string, PKColumn:string, DisplayField:string, First:boolean, Separator:string}}
+	 */
+	_resolveJoinConfig(pConfig)
+	{
+		if (!pConfig || !pConfig.JoinEntity) { return false; }
+		return {
+			Entity: pConfig.JoinEntity,
+			// The FK on the SEARCHED row, and the PK it points at on the join entity (the INN column).
+			FKColumn: pConfig.JoinField || `ID${pConfig.JoinEntity}`,
+			PKColumn: pConfig.JoinEntityValueField || `ID${pConfig.JoinEntity}`,
+			DisplayField: pConfig.JoinEntityDisplayField || 'Name',
+			// Default join-first (mirrors the documented select2 EntitySelector default).
+			First: (pConfig.JoinEntityFirst !== false),
+			Separator: (typeof pConfig.JoinSeparator === 'string') ? pConfig.JoinSeparator : ' - ',
+		};
+	}
+
+	/**
+	 * Compose a compound display from a base text + a joined value, honoring ordering + separator.
+	 * Falls back to just the base text when there is no joined value.
+	 *
+	 * @param {any} pBaseText @param {any} pJoinText @param {boolean} pFirst @param {string} pSeparator
+	 * @return {any}
+	 */
+	_composeJoinedText(pBaseText, pJoinText, pFirst, pSeparator)
+	{
+		if (pJoinText === undefined || pJoinText === null || pJoinText === '') { return pBaseText; }
+		const tmpBase = (pBaseText === undefined || pBaseText === null) ? '' : pBaseText;
+		return pFirst ? `${pJoinText}${pSeparator}${tmpBase}` : `${tmpBase}${pSeparator}${pJoinText}`;
+	}
+
+	/**
+	 * Fetch-then-merge the join entity for a page of searched records. Collects the unique FK ids the
+	 * rows carry (`JoinConfig.FKColumn`), issues ONE `FBL~{PKColumn}~INN~<ids>` request against the join
+	 * entity, and stitches `JoinRecord` + `JoinName` onto each searched row. Resolves the (mutated) same
+	 * array; on any error or when there's nothing to join, resolves the records un-decorated (the Text
+	 * gracefully degrades to the base field).
+	 *
+	 * @param {Array<any>} pRecords @param {false | Record<string, any>} pJoinConfig
+	 * @return {Promise<Array<any>>}
+	 */
+	_decorateRecordsWithJoin(pRecords, pJoinConfig)
+	{
+		return new Promise((resolve) =>
+		{
+			if (!pJoinConfig || !Array.isArray(pRecords) || pRecords.length < 1 || !this.pict.EntityProvider) { return resolve(pRecords); }
+			const tmpIDs = [];
+			const tmpSeen = {};
+			for (let i = 0; i < pRecords.length; i++)
+			{
+				const tmpID = pRecords[i][pJoinConfig.FKColumn];
+				if (tmpID !== undefined && tmpID !== null && tmpID !== '' && !tmpSeen[tmpID]) { tmpSeen[tmpID] = true; tmpIDs.push(tmpID); }
+			}
+			if (tmpIDs.length < 1) { return resolve(pRecords); }
+			const tmpFilter = `FBL~${pJoinConfig.PKColumn}~INN~${tmpIDs.join(',')}`;
+			this.pict.EntityProvider.getEntitySetPage(pJoinConfig.Entity, tmpFilter, 0, tmpIDs.length,
+				(pError, pJoinRecords) =>
+				{
+					if (pError)
+					{
+						this.pict.log.warn(`Pict-Section-Picker [${pJoinConfig.Entity}] join fetch failed; showing un-joined text.`, pError);
+						return resolve(pRecords);
+					}
+					const tmpMap = {};
+					const tmpJoinList = Array.isArray(pJoinRecords) ? pJoinRecords : [];
+					for (let i = 0; i < tmpJoinList.length; i++) { tmpMap[tmpJoinList[i][pJoinConfig.PKColumn]] = tmpJoinList[i]; }
+					for (let i = 0; i < pRecords.length; i++)
+					{
+						const tmpJoinRecord = tmpMap[pRecords[i][pJoinConfig.FKColumn]];
+						if (tmpJoinRecord) { pRecords[i].JoinRecord = tmpJoinRecord; pRecords[i].JoinName = tmpJoinRecord[pJoinConfig.DisplayField]; }
+					}
+					return resolve(pRecords);
 				});
 		});
 	}
@@ -215,6 +343,7 @@ class PictProviderPicker extends libPictProvider
 		const tmpValueField = pConfig.ValueField || `ID${tmpEntity}`;
 		const tmpTextField = pConfig.TextField || 'Name';
 		const tmpMapRecord = (typeof pConfig.MapRecord === 'function') ? pConfig.MapRecord : false;
+		const tmpJoinConfig = this._resolveJoinConfig(pConfig);
 
 		return (pValue) => new Promise((resolve) =>
 		{
@@ -226,7 +355,23 @@ class PictProviderPicker extends libPictProvider
 				(pError, pRecord) =>
 				{
 					if (pError || !pRecord) { return resolve(null); }
-					return resolve(tmpMapRecord ? tmpMapRecord(pRecord) : { Value: pRecord[tmpValueField], Text: pRecord[tmpTextField], Record: pRecord });
+					const fFinish = () =>
+					{
+						if (tmpMapRecord) { return resolve(tmpMapRecord(pRecord)); }
+						const tmpText = tmpJoinConfig
+							? this._composeJoinedText(pRecord[tmpTextField], pRecord.JoinName, tmpJoinConfig.First, tmpJoinConfig.Separator)
+							: pRecord[tmpTextField];
+						return resolve({ Value: pRecord[tmpValueField], Text: tmpText, Record: pRecord });
+					};
+					// JoinEntity: resolve the single joined record (cached getEntity) for the compound label.
+					const tmpFK = tmpJoinConfig ? pRecord[tmpJoinConfig.FKColumn] : null;
+					if (!tmpJoinConfig || tmpFK === undefined || tmpFK === null || tmpFK === '') { return fFinish(); }
+					this.pict.EntityProvider.getEntity(tmpJoinConfig.Entity, tmpFK,
+						(pJoinError, pJoinRecord) =>
+						{
+							if (!pJoinError && pJoinRecord) { pRecord.JoinRecord = pJoinRecord; pRecord.JoinName = pJoinRecord[tmpJoinConfig.DisplayField]; }
+							return fFinish();
+						});
 				});
 		});
 	}

package/source/views/PictView-Picker.js

@@ -324,6 +324,65 @@ class PictViewPicker extends libPictView
 		}
 	}
 
+	/**
+	 * Public: set the picker's value programmatically (e.g. when a host form marshals data into it).
+	 * Accepts a scalar (single mode) or an array / csv string (multi mode), seeds display text for any
+	 * unknown values (from the source rows, else async ResolveValue), then repaints.
+	 * @param {any} pValue
+	 * @return {PictViewPicker} this
+	 */
+	setValue(pValue)
+	{
+		if (this._isMulti())
+		{
+			let tmpArray = pValue;
+			if (tmpArray === undefined || tmpArray === null || tmpArray === '') { tmpArray = []; }
+			else if (typeof tmpArray === 'string') { tmpArray = tmpArray.split(',').filter((pPart) => pPart !== ''); }
+			else if (!Array.isArray(tmpArray)) { tmpArray = [ tmpArray ]; }
+			this._setValue(tmpArray);
+			this._seedSelectedRecords(tmpArray);
+		}
+		else
+		{
+			this._setValue(pValue);
+			this._selectedText = null;
+			this._seedSelectedRecords((pValue === undefined || pValue === null || pValue === '') ? [] : [ pValue ]);
+		}
+		this.render();
+		return this;
+	}
+
+	/**
+	 * Ensure each value has a {Value,Text} in _selectedRecords — from the current source rows when
+	 * present, else (async mode) fetched via ResolveValue and painted in when it resolves.
+	 * @param {Array<any>} pValues
+	 */
+	_seedSelectedRecords(pValues)
+	{
+		pValues.forEach((pVal) =>
+		{
+			if (pVal === undefined || pVal === null || pVal === '' || this._selectedRecords[String(pVal)]) { return; }
+			const tmpRow = this._sourceRows().find((pRow) => String(pRow.Value) === String(pVal));
+			if (tmpRow)
+			{
+				this._selectedRecords[String(pVal)] = { Value: tmpRow.Value, Text: tmpRow.Text };
+				return;
+			}
+			if (this._isAsync() && typeof this.options.ResolveValue === 'function')
+			{
+				Promise.resolve(this.options.ResolveValue(pVal)).then((pResolved) =>
+				{
+					if (pResolved && pResolved.Text)
+					{
+						this._selectedRecords[String(pVal)] = { Value: pResolved.Value !== undefined ? pResolved.Value : pVal, Text: pResolved.Text };
+						if (!this._isMulti()) { this._selectedText = pResolved.Text; }
+						this._renderValue();
+					}
+				}).catch(() => { /* leave the raw value showing */ });
+			}
+		});
+	}
+
 	/** @return {Array<{Value:any, Text:string}>} The current option source rows (async results or static Options). */
 	_sourceRows()
 	{
@@ -516,11 +575,51 @@ class PictViewPicker extends libPictView
 		this._open = true;
 		this._highlight = -1;
 		this._paintOpen();
+		this._positionPop();
 		if (this._isAsync() && !this._loaded) { this._loadPage(0, false); }
 		const tmpSearch = /** @type {HTMLInputElement} */ (document.getElementById(`PPS_Search_${this.options.PickerHash}`));
 		if (tmpSearch) { tmpSearch.focus(); tmpSearch.select(); }
 	}
 
+	/**
+	 * Position the (fixed) dropdown against the control, flipping above when there's more room there.
+	 * Because the popover is position:fixed (viewport-anchored), no ancestor overflow can clip it; the
+	 * trade-off is we set its top/left/width ourselves from the control's rect on open.
+	 */
+	_positionPop()
+	{
+		const tmpRoot = document.getElementById(`PPS_${this.options.PickerHash}`);
+		if (!tmpRoot) { return; }
+		const tmpControl = tmpRoot.querySelector('.pps-control');
+		const tmpPop = /** @type {HTMLElement} */ (tmpRoot.querySelector('.pps-pop'));
+		const tmpPanel = /** @type {HTMLElement} */ (tmpRoot.querySelector('.pps-panel'));
+		if (!tmpControl || !tmpPop) { return; }
+		const tmpRect = tmpControl.getBoundingClientRect();
+		const tmpGap = 5;
+		const tmpMargin = 8;
+		const tmpVH = window.innerHeight;
+		const tmpVW = window.innerWidth;
+		const tmpWidth = Math.max(200, Math.round(tmpRect.width));
+		tmpPop.style.width = `${tmpWidth}px`;
+		tmpPop.style.left = `${Math.round(Math.max(tmpMargin, Math.min(tmpRect.left, tmpVW - tmpWidth - tmpMargin)))}px`;
+		tmpPop.style.right = 'auto';
+		const tmpSpaceBelow = tmpVH - tmpRect.bottom - tmpGap - tmpMargin;
+		const tmpSpaceAbove = tmpRect.top - tmpGap - tmpMargin;
+		// Prefer the natural downward direction; only flip above when the room below is genuinely cramped.
+		if (tmpSpaceBelow >= 200 || tmpSpaceBelow >= tmpSpaceAbove)
+		{
+			tmpPop.style.top = `${Math.round(tmpRect.bottom + tmpGap)}px`;
+			tmpPop.style.bottom = 'auto';
+			if (tmpPanel) { tmpPanel.style.maxHeight = `${Math.max(140, Math.min(tmpSpaceBelow, 360))}px`; }
+		}
+		else
+		{
+			tmpPop.style.top = 'auto';
+			tmpPop.style.bottom = `${Math.round(tmpVH - tmpRect.top + tmpGap)}px`;
+			if (tmpPanel) { tmpPanel.style.maxHeight = `${Math.max(140, Math.min(tmpSpaceAbove, 360))}px`; }
+		}
+	}
+
 	/** Async mode: load + append the next page of results. */
 	loadMore()
 	{

package/types/form/Pict-Section-Picker-FormInput.d.ts

@@ -0,0 +1,95 @@
+export = PictInputTypePicker;
+declare const PictInputTypePicker_base: typeof import("pict-section-form/types/source/providers/Pict-Provider-InputExtension");
+declare class PictInputTypePicker extends PictInputTypePicker_base {
+    constructor(pFable: any, pOptions: any, pServiceHash: any);
+    getPickerHostID(pRawHTMLID: any): string;
+    getPickerHash(pRawHTMLID: any): string;
+    getTabularPickerHostID(pRawHTMLID: any, pRowIndex: any): string;
+    getTabularPickerHash(pRawHTMLID: any, pRowIndex: any): string;
+    getTabularHiddenID(pRawHTMLID: any, pRowIndex: any): string;
+    /**
+     * Overridable: extra FoxHound scope stanza(s) AND-applied to the entity search. Default reads the
+     * descriptor's `GetContextScopeFilter()` hook (set by the host / recordset filter base), else its
+     * static `BaseFilter`. Host subclasses override this to read app state (project / spec-year / …).
+     *
+     * @param {Record<string, any>} pInput @return {string|Array<string>}
+     */
+    getContextualSearchFilters(pInput: Record<string, any>): string | Array<string>;
+    /** Build the picker config from a form input descriptor. */
+    _buildPickerConfig(pInput: any, pHostSelector: any, fOnChange: any): {
+        DestinationAddress: any;
+        Mode: string;
+        Placeholder: any;
+        Searchable: boolean;
+        Entity: any;
+        SearchFields: any;
+        ValueField: any;
+        TextField: any;
+        PageSize: any;
+        Options: any;
+        JoinEntity: any;
+        JoinField: any;
+        JoinEntityValueField: any;
+        JoinEntityDisplayField: any;
+        JoinEntityFirst: any;
+        JoinSeparator: any;
+        BaseFilter: () => string | string[];
+        OnChange: any;
+    };
+    /** Instantiate (or reuse) the picker view for a config — entity-backed when Entity is set. */
+    _instantiatePicker(pPickerHash: any, pConfig: any): any;
+    /**
+     * Write a picker value into the form: csv to the hidden informary input (+ dataChanged), plus the
+     * raw array to `PictForm.ValueArrayAddress` when set (the recordset filter reads Values as an
+     * array). The csv-vs-array bridge lives HERE (generic) instead of in each host.
+     */
+    _commit(pView: any, pInput: any, pValue: any, pHTMLSelector: any): void;
+    _commitTabular(pView: any, pInput: any, pValue: any, pHiddenID: any, pRowIndex: any): void;
+    /**
+     * Idempotently mount (or reuse) the picker into its host element + seed its value. Called from both
+     * onInputInitialize and onDataMarshalToForm because, in the async-virtual filter render, the host
+     * element only exists in the real DOM by the marshal pass — whichever hook fires post-DOM wins, and
+     * re-calls are harmless (the picker view is reused by hash).
+     * @return {boolean} true if the picker is mounted.
+     */
+    _mountPicker(pView: any, pInput: any, pValue: any, pHostSelector: any, pPickerHash: any, fOnChange: any): boolean;
+    onInputInitialize(pView: any, pGroup: any, pRow: any, pInput: any, pValue: any, pHTMLSelector: any, pTransactionGUID: any): boolean;
+    onDataMarshalToForm(pView: any, pGroup: any, pRow: any, pInput: any, pValue: any, pHTMLSelector: any, pTransactionGUID: any): boolean;
+    onDataRequest(pView: any, pInput: any, pValue: any, pHTMLSelector: any): boolean;
+    /** Idempotent tabular mount (see _mountPicker). @return {boolean} */
+    _mountPickerTabular(pView: any, pInput: any, pValue: any, pRowIndex: any): boolean;
+    onInputInitializeTabular(pView: any, pGroup: any, pInput: any, pValue: any, pHTMLSelector: any, pRowIndex: any, pTransactionGUID: any): boolean;
+    onDataMarshalToFormTabular(pView: any, pGroup: any, pInput: any, pValue: any, pHTMLSelector: any, pRowIndex: any, pTransactionGUID: any): boolean;
+    onDataRequestTabular(pView: any, pInput: any, pValue: any, pHTMLSelector: any, pRowIndex: any): boolean;
+}
+declare namespace PictInputTypePicker {
+    export { PictInputTypePicker, registerPickerInputType, buildPickerInputTemplates, _DEFAULT_CONFIGURATION as default_configuration };
+}
+/**
+ * Register the Picker InputType on a pict instance: the input-extension provider + its metatemplate(s).
+ * Idempotent. Requires `pict-section-form` loaded (PictFormSectionDefaultTemplateProvider present) and
+ * the `Pict-Section-Picker` provider registered.
+ *
+ * @param {any} pPict - the pict instance.
+ * @param {Record<string, any>} [pOptions]
+ *   - InputTypeName {string} - the InputType string (default 'Picker').
+ *   - ProviderHash {string} - the input-extension provider service hash (default 'Pict-Input-Picker').
+ *   - ProviderClass {Function} - provider class to register (default PictInputTypePicker; a host
+ *     passes a subclass that overrides getContextualSearchFilters for its scoping).
+ *   - TemplatePrefix {string|Array<string>} - the form template prefix(es) to inject the metatemplate
+ *     under (default 'Pict-MT-Base'; Headlight uses its theme prefixes).
+ * @return {boolean} true if registered.
+ */
+declare function registerPickerInputType(pPict: any, pOptions?: Record<string, any>): boolean;
+/**
+ * Build the InputType metatemplate entries (a hidden informary input + a host element the picker
+ * renders into) for a given InputType name + provider hash. Injected via injectTemplateSet.
+ *
+ * @param {string} pInputTypeName - e.g. 'Picker'.
+ * @param {string} pProviderHash - the input-extension provider service hash to auto-attach.
+ * @return {Array<Record<string, any>>}
+ */
+declare function buildPickerInputTemplates(pInputTypeName: string, pProviderHash: string): Array<Record<string, any>>;
+/** @type {Record<string, any>} */
+declare const _DEFAULT_CONFIGURATION: Record<string, any>;
+//# sourceMappingURL=Pict-Section-Picker-FormInput.d.ts.map

package/types/form/Pict-Section-Picker-FormInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pict-Section-Picker-FormInput.d.ts","sourceRoot":"","sources":["../../source/form/Pict-Section-Picker-FormInput.js"],"names":[],"mappings":";;AAsEA;IAEC,2DAKC;IAGD,yCAAmE;IACnE,uCAA4D;IAC5D,gEAAsG;IACtG,8DAA2F;IAC3F,4DAAuG;IAEvG;;;;;;OAMG;IACH,mCAFW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAkB,MAAM,GAAC,KAAK,CAAC,MAAM,CAAC,CAWnE;IAED,4DAA4D;IAC5D;;;;;;;;;;;;;;;;;;;MA0BC;IAED,8FAA8F;IAC9F,wDAWC;IAED;;;;OAIG;IACH,wEAUC;IAED,2FAKC;IAED;;;;;;OAMG;IACH,0GAFY,OAAO,CAUlB;IAID,oIAMC;IAED,sIAYC;IAED,iFAMC;IAID,qEAAqE;IACrE,2EAD0D,OAAO,CAahE;IAED,gJAIC;IAED,kJAQC;IAED,wGAMC;CACD;;;;AAED;;;;;;;;;;;;;;GAcG;AACH,gDAVW,GAAG,aACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAOlB,OAAO,CAwBlB;AAjRD;;;;;;;GAOG;AACH,2DAJW,MAAM,iBACN,MAAM,GACL,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAoCrC;AAnDD,kCAAkC;AAClC,sCADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAO5B"}

package/types/providers/Pict-Provider-Picker.d.ts

@@ -46,14 +46,63 @@ declare class PictProviderPicker extends libPictProvider {
      *   - TextField {string} - record field used as the option Text (default `Name`).
      *   - PageSize {number} - records per page (default 20).
      *   - Sort {string} - optional field to sort ascending (adds `FSF~<field>~ASC~0`).
-     *   - BaseFilter {string} - optional always-applied FoxHound filter (AND), e.g. `FBV~IDCustomer~EQ~1`.
+     *   - BaseFilter {string|Array<string>|function} - optional always-applied FoxHound filter (AND),
+     *     e.g. `FBV~IDCustomer~EQ~1`. May be a **function** `(searchTerm, page) => string|string[]`
+     *     evaluated on every search — the generic hook for host-injected CONTEXTUAL scoping (project,
+     *     tenant, spec-year, …). The module stays agnostic; the host supplies the closure.
      *   - MapRecord {function} - optional `(record) => {Value, Text}` mapper (overrides Value/TextField).
+     *   - JoinEntity {string} - optional second entity to JOIN for a compound display (e.g. a `LineItem`
+     *     shown with its `Project`). Each searched row must carry the FK (`JoinField`). Because Meadow
+     *     can't join in one read, this is fetch-then-merge: after the primary page resolves, the unique
+     *     FK ids drive ONE `FBL~ID{JoinEntity}~INN~<ids>` request, and the joined display field is
+     *     stitched onto each row (as `Record.JoinName` / `Record.JoinRecord`) + composed into the Text.
+     *   - JoinField {string} - the FK column ON THE SEARCHED ROW pointing at JoinEntity (default `ID{JoinEntity}`).
+     *   - JoinEntityValueField {string} - the PK column on JoinEntity to match (default `ID{JoinEntity}`).
+     *   - JoinEntityDisplayField {string} - the JoinEntity field to display (default `Name`).
+     *   - JoinEntityFirst {boolean} - put the joined value first in the compound (default `true`):
+     *     `JoinName - baseText`; when `false`, `baseText - JoinName`.
+     *   - JoinSeparator {string} - the compound separator (default `' - '`).
      * @return {(pSearchTerm: string, pPage: number) => Promise<{results: Array<any>, hasMore: boolean}>}
      */
     createEntityDataProvider(pConfig: Record<string, any>): (pSearchTerm: string, pPage: number) => Promise<{
         results: Array<any>;
         hasMore: boolean;
     }>;
+    /**
+     * Resolve the JoinEntity options off an entity-source config into a normalized internal shape, or
+     * `false` when no JoinEntity is configured. Centralizes the defaults so the DataProvider and the
+     * ResolveValue builders agree.
+     *
+     * @param {Record<string, any>} pConfig
+     * @return {false | {Entity:string, FKColumn:string, PKColumn:string, DisplayField:string, First:boolean, Separator:string}}
+     */
+    _resolveJoinConfig(pConfig: Record<string, any>): false | {
+        Entity: string;
+        FKColumn: string;
+        PKColumn: string;
+        DisplayField: string;
+        First: boolean;
+        Separator: string;
+    };
+    /**
+     * Compose a compound display from a base text + a joined value, honoring ordering + separator.
+     * Falls back to just the base text when there is no joined value.
+     *
+     * @param {any} pBaseText @param {any} pJoinText @param {boolean} pFirst @param {string} pSeparator
+     * @return {any}
+     */
+    _composeJoinedText(pBaseText: any, pJoinText: any, pFirst: boolean, pSeparator: string): any;
+    /**
+     * Fetch-then-merge the join entity for a page of searched records. Collects the unique FK ids the
+     * rows carry (`JoinConfig.FKColumn`), issues ONE `FBL~{PKColumn}~INN~<ids>` request against the join
+     * entity, and stitches `JoinRecord` + `JoinName` onto each searched row. Resolves the (mutated) same
+     * array; on any error or when there's nothing to join, resolves the records un-decorated (the Text
+     * gracefully degrades to the base field).
+     *
+     * @param {Array<any>} pRecords @param {false | Record<string, any>} pJoinConfig
+     * @return {Promise<Array<any>>}
+     */
+    _decorateRecordsWithJoin(pRecords: Array<any>, pJoinConfig: false | Record<string, any>): Promise<Array<any>>;
     /**
      * Build a `ResolveValue(value) => Promise<{Value,Text}>` for an entity-backed picker, so a
      * pre-bound ID resolves to its display text on first render (fetched + cached by `getEntity`).

package/types/providers/Pict-Provider-Picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Pict-Provider-Picker.d.ts","sourceRoot":"","sources":["../../source/providers/Pict-Provider-Picker.js"],"names":[],"mappings":";AAyEA;;;GAGG;AACH;IAEC,2DASC;IAED;;;;;;;;;;;;;;OAcG;IACH,0BAZW,MAAM,WAEN,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAQlB,GAAG,CAqBd;IAED;;;;;;;;;;;OAWG;IACH,iCAJW,KAAK,CAAC,MAAM,CAAC,SACb,MAAM,GACL,MAAM,CAWjB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kCAXW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GASlB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,CAAC,CAuCnG;IAED;;;;;;OAMG;IACH,kCAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAClB,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAsBxC;IAED;;;;;;;;;OASG;IACH,gCAJW,MAAM,WACN,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAClB,GAAG,CAQd;CACD;;;;;AA1LD,kCAAkC;AAClC,sCADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAO5B"}
+{"version":3,"file":"Pict-Provider-Picker.d.ts","sourceRoot":"","sources":["../../source/providers/Pict-Provider-Picker.js"],"names":[],"mappings":";AAmFA;;;GAGG;AACH;IAEC,2DASC;IAED;;;;;;;;;;;;;;OAcG;IACH,0BAZW,MAAM,WAEN,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAQlB,GAAG,CAqBd;IAED;;;;;;;;;;;OAWG;IACH,iCAJW,KAAK,CAAC,MAAM,CAAC,SACb,MAAM,GACL,MAAM,CAWjB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,kCAzBW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAuBlB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,CAAC,CA6DnG;IAED;;;;;;;OAOG;IACH,4BAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAClB,KAAK,GAAG;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAC,YAAY,EAAC,MAAM,CAAC;QAAC,KAAK,EAAC,OAAO,CAAC;QAAC,SAAS,EAAC,MAAM,CAAA;KAAC,CAe1H;IAED;;;;;;OAMG;IACH,8BAHW,GAAG,aAAoB,GAAG,UAAoB,OAAO,cAAiB,MAAM,GAC3E,GAAG,CAOd;IAED;;;;;;;;;OASG;IACH,mCAHW,KAAK,CAAC,GAAG,CAAC,eAAmB,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACvD,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAmC9B;IAED;;;;;;OAMG;IACH,kCAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAClB,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAuCxC;IAED;;;;;;;;;OASG;IACH,gCAJW,MAAM,WACN,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAClB,GAAG,CAQd;CACD;;;;;AAjUD,kCAAkC;AAClC,sCADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAO5B"}

package/types/views/PictView-Picker.d.ts

@@ -34,6 +34,20 @@ declare class PictViewPicker extends libPictView {
      */
     _setValue(pValue: any): void;
     _value: any;
+    /**
+     * Public: set the picker's value programmatically (e.g. when a host form marshals data into it).
+     * Accepts a scalar (single mode) or an array / csv string (multi mode), seeds display text for any
+     * unknown values (from the source rows, else async ResolveValue), then repaints.
+     * @param {any} pValue
+     * @return {PictViewPicker} this
+     */
+    setValue(pValue: any): PictViewPicker;
+    /**
+     * Ensure each value has a {Value,Text} in _selectedRecords — from the current source rows when
+     * present, else (async mode) fetched via ResolveValue and painted in when it resolves.
+     * @param {Array<any>} pValues
+     */
+    _seedSelectedRecords(pValues: Array<any>): void;
     /** @return {Array<{Value:any, Text:string}>} The current option source rows (async results or static Options). */
     _sourceRows(): Array<{
         Value: any;
@@ -66,6 +80,12 @@ declare class PictViewPicker extends libPictView {
     onControlKey(pEvent: any): void;
     /** Open the dropdown and focus the search box. */
     open(): void;
+    /**
+     * Position the (fixed) dropdown against the control, flipping above when there's more room there.
+     * Because the popover is position:fixed (viewport-anchored), no ancestor overflow can clip it; the
+     * trade-off is we set its top/left/width ourselves from the control's rect on open.
+     */
+    _positionPop(): void;
     /** Async mode: load + append the next page of results. */
     loadMore(): void;
     /** Close the dropdown. */

package/types/views/PictView-Picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PictView-Picker.d.ts","sourceRoot":"","sources":["../../source/views/PictView-Picker.js"],"names":[],"mappings":";AA6KA;IAEC,2DA0CC;IAlCA,sBAA2E;IAQ3E,eAAkB;IAClB,gBAAiB;IACjB,mBAAoB;IAEpB,sBAAwB;IACxB,cAAc;IACd,kBAAqB;IACrB,kBAAqB;IACrB,iBAAoB;IACpB,6BAAwB;IACxB,mBAAyB;IAGzB,eAAiB;IACjB,qBAA0B;IAc3B,6FAA6F;IAC7F,YADa,OAAO,CAInB;IAED,8EAA8E;IAC9E,YADa,OAAO,CAInB;IAED,4EAA4E;IAC5E,UADa,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAM/B;IAED,qGAAqG;IACrG,8BA+BC;IAED;;;OAGG;IACH,YAHY,GAAG,CAgBd;IAED;;;;OAIG;IACH,kBAFW,GAAG,QA6Bb;IAvBC,YAAoB;IAyBtB,kHAAkH;IAClH,eADa,KAAK,CAAC;QAAC,KAAK,EAAC,GAAG,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,CAAC,CAK3C;IAED;;;OAGG;IACH,mCAgGC;IAED;;;;;OAKG;IACH,sBAHW,GAAG,GACF;QAAC,KAAK,EAAC,GAAG,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,GAAC,IAAI,CAQxC;IAED;;;;OAIG;IACH,iBAHW,MAAM,WACN,OAAO,QA4BjB;IAWD,uCAAuC;IACvC,0BAIC;IAED,+EAA+E;IAC/E,gCAWC;IAED,kDAAkD;IAClD,aAQC;IAED,0DAA0D;IAC1D,iBAMC;IAED,0BAA0B;IAC1B,cAKC;IAED,6DAA6D;IAC7D,mBAIC;IAED,kFAAkF;IAClF,oBAKC;IAED;sGACkG;IAClG,qBAKC;IAED,2EAA2E;IAC3E,eADY,MAAM,QAejB;IAED,iGAAiG;IACjG,+BAgCC;IAED;;;;OAIG;IACH,kBAFW,MAAM,QA4ChB;IAED,sGAAsG;IACtG,sBADa,KAAK,CAAC;QAAC,KAAK,EAAC,GAAG,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,CAAC,CAI3C;IAED;;;;OAIG;IACH,yBA6CC;IAED,oFAAoF;IACpF,iCAWC;CAWD;;;;;AAxuBD,kCAAkC;AAClC,sCADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAyK5B"}
+{"version":3,"file":"PictView-Picker.d.ts","sourceRoot":"","sources":["../../source/views/PictView-Picker.js"],"names":[],"mappings":";AA6KA;IAEC,2DA0CC;IAlCA,sBAA2E;IAQ3E,eAAkB;IAClB,gBAAiB;IACjB,mBAAoB;IAEpB,sBAAwB;IACxB,cAAc;IACd,kBAAqB;IACrB,kBAAqB;IACrB,iBAAoB;IACpB,6BAAwB;IACxB,mBAAyB;IAGzB,eAAiB;IACjB,qBAA0B;IAc3B,6FAA6F;IAC7F,YADa,OAAO,CAInB;IAED,8EAA8E;IAC9E,YADa,OAAO,CAInB;IAED,4EAA4E;IAC5E,UADa,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAM/B;IAED,qGAAqG;IACrG,8BA+BC;IAED;;;OAGG;IACH,YAHY,GAAG,CAgBd;IAED;;;;OAIG;IACH,kBAFW,GAAG,QA6Bb;IAvBC,YAAoB;IAyBtB;;;;;;OAMG;IACH,iBAHW,GAAG,GACF,cAAc,CAqBzB;IAED;;;;OAIG;IACH,8BAFW,KAAK,CAAC,GAAG,CAAC,QA0BpB;IAED,kHAAkH;IAClH,eADa,KAAK,CAAC;QAAC,KAAK,EAAC,GAAG,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,CAAC,CAK3C;IAED;;;OAGG;IACH,mCAgGC;IAED;;;;;OAKG;IACH,sBAHW,GAAG,GACF;QAAC,KAAK,EAAC,GAAG,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,GAAC,IAAI,CAQxC;IAED;;;;OAIG;IACH,iBAHW,MAAM,WACN,OAAO,QA4BjB;IAWD,uCAAuC;IACvC,0BAIC;IAED,+EAA+E;IAC/E,gCAWC;IAED,kDAAkD;IAClD,aASC;IAED;;;;OAIG;IACH,qBAgCC;IAED,0DAA0D;IAC1D,iBAMC;IAED,0BAA0B;IAC1B,cAKC;IAED,6DAA6D;IAC7D,mBAIC;IAED,kFAAkF;IAClF,oBAKC;IAED;sGACkG;IAClG,qBAKC;IAED,2EAA2E;IAC3E,eADY,MAAM,QAejB;IAED,iGAAiG;IACjG,+BAgCC;IAED;;;;OAIG;IACH,kBAFW,MAAM,QA4ChB;IAED,sGAAsG;IACtG,sBADa,KAAK,CAAC;QAAC,KAAK,EAAC,GAAG,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,CAAC,CAI3C;IAED;;;;OAIG;IACH,yBA6CC;IAED,oFAAoF;IACpF,iCAWC;CAWD;;;;;AA30BD,kCAAkC;AAClC,sCADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAyK5B"}