pict-section-picker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 - 2026 Steven Velozo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# pict-section-picker
+
+A Pict-native, themeable searchable **select / combobox** — a jQuery/`select2`-free replacement for entity pickers and tag inputs in [Pict](https://github.com/fable-retold/pict) applications.
+
+- **Single & multi select** — scalar value, or an array of values rendered as removable chips.
+- **Search** with keyboard navigation (↑/↓ + Enter), click-outside to close.
+- **Server pagination** — drive options from an async `DataProvider(searchTerm, page)`; "Load more" / infinite scroll.
+- **Categorized options** — group rows under headers.
+- **Creatable** — let users mint new entries from the search term via `OnCreate`.
+- **Built-in Meadow adapter** — point it at a Meadow entity and it builds the server `DataProvider` (FoxHound `LIKE` search + paging) and the pre-bound-value resolver for you.
+- **Themeable** via `--theme-color-*` tokens. No jQuery, no `select2`, no `addEventListener` — pure Pict conventions.
+
+## Install
+
+```bash
+npm install pict-section-picker
+```
+
+## Quick start
+
+Register the provider, then create pickers through it. Each picker renders into a host DOM element and reads/writes its selection from an AppData address.
+
+```javascript
+const libPictSectionPicker = require('pict-section-picker');
+
+// In your application's onAfterInitializeAsync:
+this.pict.addProvider('Pict-Section-Picker', libPictSectionPicker.default_configuration, libPictSectionPicker);
+const tmpPicker = this.pict.providers['Pict-Section-Picker'];
+
+// A simple static single-select.
+tmpPicker.createPicker('CountryPicker',
+{
+    DestinationAddress: '#CountryPicker',     // where to render
+    ValueAddress: 'AppData.Form.Country',     // selection is read from / written to here
+    Placeholder: 'Select a country…',
+    Options: [ { Value: 'us', Text: 'United States' }, { Value: 'ca', Text: 'Canada' } ],
+    OnChange: (pValue, pRecord) => { /* … */ },
+});
+this.pict.views['CountryPicker'].render();
+```
+
+The control renders into `#CountryPicker`; `AppData.Form.Country` holds the selected value.
+
+## Picker modes
+
+### Single (default)
+
+`Mode: 'single'` — `ValueAddress` holds the scalar value. Selecting closes the dropdown.
+
+### Multi
+
+`Mode: 'multi'` — `ValueAddress` holds an **array** of values, rendered as chips with × buttons. Selecting toggles membership and keeps the dropdown open for rapid multi-pick. Two optional mirror bindings (the `EntitySelectorMultiple` contract):
+
+| Option | Holds |
+|---|---|
+| `ValueAddress` | the array of values, e.g. `[2, 10, 141]` |
+| `StringArrayValueAddress` | a csv string, e.g. `"2,10,141"` |
+| `SelectedValuesAddress` | the full record list, e.g. `[{Value, Text}, …]` |
+
+```javascript
+tmpPicker.createPicker('TagsPicker',
+{
+    Mode: 'multi',
+    DestinationAddress: '#TagsPicker',
+    ValueAddress: 'AppData.Form.Tags',
+    Placeholder: 'Add tags…',
+    Options: [ { Value: 'urgent', Text: 'urgent' }, { Value: 'review', Text: 'review' } ],
+});
+```
+
+## Async data (server search + pagination)
+
+Pass a `DataProvider` instead of (or in addition to) static `Options`. It is called with the current search term and a zero-based page index, and resolves a page of results plus whether more remain:
+
+```javascript
+DataProvider: (pSearchTerm, pPage) => Promise.resolve(
+{
+    results: [ { Value: 1, Text: 'First' }, /* … up to PageSize … */ ],
+    hasMore: true,   // show a "Load more" button
+})
+```
+
+Searches are debounced; "Load more" appends the next page. For a value that is already bound when the picker mounts (e.g. an ID with no text yet), supply `ResolveValue(value) => Promise<{Value, Text}>` so the control can show its label.
+
+## Meadow entity pickers
+
+For the common case — picking a [Meadow](https://github.com/fable-retold/meadow) entity over the REST API — use `createEntityPicker`. It builds the server `DataProvider` (FoxHound `LIKE` search across your fields, offset/limit paging) and the `ResolveValue` resolver from `pict.EntityProvider` automatically.
+
+```javascript
+tmpPicker.createEntityPicker('AuthorPicker',
+{
+    Entity: 'Author',                 // the Meadow entity
+    SearchFields: [ 'Name' ],         // fields to LIKE-search (default ['Name'])
+    ValueField: 'IDAuthor',           // option Value (default 'ID<Entity>')
+    TextField: 'Name',                // option Text  (default 'Name')
+    PageSize: 20,
+    DestinationAddress: '#AuthorPicker',
+    ValueAddress: 'AppData.Form.IDAuthor',
+    Placeholder: 'Search authors…',
+    // Works in multi mode too — add Mode: 'multi'.
+});
+this.pict.views['AuthorPicker'].render();
+```
+
+Entity-source configuration:
+
+| Option | Default | Purpose |
+|---|---|---|
+| `Entity` | — (required) | The Meadow entity name. |
+| `SearchFields` | `['Name']` | Fields OR'd together in the `LIKE` search. |
+| `ValueField` | `ID<Entity>` | Record field used as the option `Value`. |
+| `TextField` | `'Name'` | Record field used as the option `Text`. |
+| `PageSize` | `20` | Records per page. |
+| `Sort` | — | Field to sort ascending (`FSF~<field>~ASC~0`). |
+| `BaseFilter` | — | An always-applied FoxHound filter (AND), e.g. `FBV~IDCustomer~EQ~1`. |
+| `MapRecord` | — | `(record) => {Value, Text}` mapper, overriding `Value`/`TextField`. |
+
+The lower-level builders are also exposed: `createEntityDataProvider(cfg)` and `createEntityResolveValue(cfg)` return the raw functions if you want to wire them yourself.
+
+## 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):
+
+```javascript
+Options:
+[
+    { Value: 'us', Text: 'United States', Group: 'Americas' },
+    { Value: 'gb', Text: 'United Kingdom', Group: 'Europe' },
+    { Value: 'jp', Text: 'Japan',          Group: 'Asia' },
+]
+```
+
+Async sources can return `Group` on each result row too.
+
+## Creatable
+
+Set `OnCreate(searchTerm) => {Value, Text} | Promise<{Value, Text}>`. When the search term is non-empty and doesn't exactly match an existing row, a **"Create …"** row appears (also triggerable with Enter). The returned record is selected (single) or added as a chip (multi):
+
+```javascript
+OnCreate: (pTerm) =>
+{
+    // A real app would POST the new entity and return the saved row (sync or async).
+    return { Value: slugify(pTerm), Text: pTerm };
+}
+```
+
+## Configuration reference
+
+| Option | Default | Purpose |
+|---|---|---|
+| `DestinationAddress` | `#<hash>` | CSS selector to render the control into. |
+| `ValueAddress` | — | AppData address the selection is read from / written to. |
+| `Mode` | `'single'` | `'single'` (scalar) or `'multi'` (array + chips). |
+| `Placeholder` | `'Select…'` | Text shown when nothing is selected. |
+| `Searchable` | `true` | Show the search box. |
+| `Options` | `[]` | Static option list (`{Value, Text, Group?}`). |
+| `DataProvider` | — | Async source `(term, page) => Promise<{results, hasMore}>`. |
+| `PageSize` | `20` | Page size for async sources. |
+| `ResolveValue` | — | `(value) => Promise<{Value, Text}>` to label a pre-bound value. |
+| `StringArrayValueAddress` | — | (multi) mirror the value array as a csv string. |
+| `SelectedValuesAddress` | — | (multi) mirror the selection as a record array. |
+| `OnCreate` | — | `(term) => {Value, Text}` to enable creatable entries. |
+| `OnChange` | — | Called after a selection: single → `(value, record)`, multi → `(values, records)`. |
+
+## 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`.
+
+## Example application
+
+`example_applications/picker_demo` exercises every mode (static / async / entity, single / multi, categorized, creatable). Build it with `npm run build` in that folder and open `dist/index.html`. The entity pickers in the demo talk to a live Meadow harness.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "pict-section-picker",
+	"version": "1.0.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"
+	],
+	"scripts": {
+		"test": "npx mocha -u tdd -R spec",
+		"tests": "npx mocha -u tdd -R spec -g",
+		"start": "node source/Pict-Section-Picker.js",
+		"coverage": "./node_modules/.bin/nyc --reporter=lcov --reporter=text-lcov ./node_modules/mocha/bin/_mocha -- -u tdd -R spec",
+		"build": "npx quack build",
+		"types": "tsc -p tsconfig.build.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fable-retold/pict-section-picker.git"
+	},
+	"author": "steven velozo <steven@velozo.com>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/fable-retold/pict-section-picker/issues"
+	},
+	"homepage": "https://github.com/fable-retold/pict-section-picker#readme",
+	"mocha": {
+		"diff": true,
+		"extension": [
+			"js"
+		],
+		"package": "./package.json",
+		"reporter": "spec",
+		"slow": "75",
+		"timeout": "5000",
+		"ui": "tdd",
+		"watch-files": [
+			"source/**/*.js",
+			"test/**/*.js"
+		],
+		"watch-ignore": [
+			"lib/vendor"
+		]
+	},
+	"dependencies": {
+		"pict-provider": "^1.0.13",
+		"pict-view": "^1.0.68"
+	},
+	"devDependencies": {
+		"@types/mocha": "^10.0.10",
+		"@types/node": "^16.18.126",
+		"browser-env": "^3.3.0",
+		"pict": "^1.0.372",
+		"quackage": "^1.3.0",
+		"typescript": "^5.9.3"
+	}
+}

package/source/Pict-Section-Picker.js

@@ -0,0 +1,20 @@
+// The container for all the Pict-Section-Picker related code.
+//
+// pict-section-picker is a themeable, pict-native searchable select / combobox: a jQuery- and
+// select2-free widget supporting single & multi select, search, server pagination, categorized
+// groups and creatable entries. It is driven by a host-agnostic async DataProvider, and ships a
+// built-in adapter for the pict EntityProvider (Meadow entities) for the common case.
+
+// The picker provider (primary API surface — registers the widget view + CSS, and exposes
+// createPicker() / data-source adapters).
+const PictProviderPicker = require('./providers/Pict-Provider-Picker.js');
+
+// The widget view (also auto-registered by the provider).
+const PictViewPicker = require('./views/PictView-Picker.js');
+
+module.exports = PictProviderPicker;
+
+module.exports.PictProviderPicker = PictProviderPicker;
+module.exports.PictViewPicker = PictViewPicker;
+
+module.exports.default_configuration = PictProviderPicker.default_configuration;

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

@@ -0,0 +1,255 @@
+const libPictProvider = require('pict-provider');
+
+const libPictViewPicker = require('../views/PictView-Picker.js');
+
+// Themeable widget CSS. Registered once (by hash) regardless of how many picker instances exist.
+// Host apps brand by defining the --theme-color-* tokens; the hardcoded values are fallbacks.
+const _PickerCSS = /*css*/`
+.pps { position: relative; width: 100%; box-sizing: border-box; }
+.pps *, .pps *::before, .pps *::after { box-sizing: border-box; }
+.pps-control { display: flex; align-items: center; gap: 0.5rem; width: 100%; cursor: pointer; font: inherit; font-size: 0.92rem;
+	padding: 0.45rem 0.7rem; border-radius: 8px; border: 1px solid var(--theme-color-border-default, #d7dce3);
+	background: var(--theme-color-background-primary, #fff); color: var(--theme-color-text-primary, #1f2733); text-align: left; }
+.pps-control:hover { border-color: var(--theme-color-border-strong, #c2c9d2); }
+.pps.pps-open .pps-control { border-color: var(--theme-color-brand-primary, #156dd1);
+	box-shadow: 0 0 0 3px color-mix(in srgb, var(--theme-color-brand-primary, #156dd1) 16%, transparent); }
+.pps-valuearea { flex: 1 1 auto; min-width: 0; }
+.pps-value { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pps-value.pps-placeholder { color: var(--theme-color-text-muted, #6b7686); }
+.pps-chevron { flex: 0 0 auto; display: inline-flex; color: var(--theme-color-text-muted, #6b7686); font-size: 0.8rem; transition: transform 0.15s ease; }
+.pps.pps-open .pps-chevron { transform: rotate(180deg); }
+
+/* Multi-select chips. The control hosts a wrapping row of removable tags + a muted placeholder. */
+.pps-multi .pps-control { align-items: flex-start; }
+.pps-chips { display: flex; flex-wrap: wrap; align-items: center; gap: 0.3rem; min-width: 0; }
+.pps-chips-ph { color: var(--theme-color-text-muted, #6b7686); }
+.pps-chip { display: inline-flex; align-items: center; gap: 0.3rem; max-width: 100%; font-size: 0.82rem; line-height: 1.4;
+	padding: 0.1rem 0.2rem 0.1rem 0.5rem; border-radius: 6px;
+	background: color-mix(in srgb, var(--theme-color-brand-primary, #156dd1) 12%, transparent);
+	color: var(--theme-color-brand-primary, #156dd1); }
+.pps-chip-text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.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; }
+.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);
+	border-radius: 10px; box-shadow: 0 10px 28px rgba(17, 24, 39, 0.14); overflow: hidden; }
+.pps-search { flex: 0 0 auto; display: flex; align-items: center; gap: 0.4rem; padding: 0.5rem 0.7rem; border-bottom: 1px solid var(--theme-color-border-light, #e8ebf0); }
+.pps-search-ic { display: inline-flex; color: var(--theme-color-text-muted, #6b7686); font-size: 0.9rem; }
+.pps-search input { flex: 1 1 auto; min-width: 0; font: inherit; font-size: 0.9rem; border: none; outline: none; background: transparent; color: var(--theme-color-text-primary, #1f2733); }
+.pps-list { flex: 1 1 auto; overflow-y: auto; padding: 0.25rem; }
+.pps-option { display: flex; align-items: center; gap: 0.5rem; width: 100%; text-align: left; cursor: pointer; font: inherit; font-size: 0.9rem;
+	padding: 0.45rem 0.6rem; border: none; border-radius: 6px; background: transparent; color: var(--theme-color-text-primary, #1f2733); }
+.pps-option:hover, .pps-option.pps-highlight { background: var(--theme-color-background-tertiary, #eceef2); }
+.pps-option.pps-selected { color: var(--theme-color-brand-primary, #156dd1); font-weight: 600; }
+.pps-option-check { flex: 0 0 auto; display: inline-flex; width: 1em; color: var(--theme-color-brand-primary, #156dd1); }
+.pps-option-check.pps-hidden { visibility: hidden; }
+.pps-empty { padding: 0.7rem 0.6rem; color: var(--theme-color-text-muted, #6b7686); font-size: 0.86rem; text-align: center; }
+.pps-loading { padding: 0.6rem; text-align: center; color: var(--theme-color-text-muted, #6b7686); font-size: 0.85rem; }
+.pps-more { display: block; width: calc(100% - 0.5rem); margin: 0.25rem; padding: 0.4rem; cursor: pointer; font: inherit; font-size: 0.85rem;
+	border: 1px solid var(--theme-color-border-light, #e8ebf0); border-radius: 6px; background: transparent; color: var(--theme-color-brand-primary, #156dd1); }
+.pps-more:hover { background: var(--theme-color-background-tertiary, #eceef2); }
+
+/* Category header (groups) + creatable "Create …" row. */
+.pps-group { padding: 0.45rem 0.6rem 0.2rem; font-size: 0.72rem; font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; color: var(--theme-color-text-muted, #6b7686); }
+.pps-create { display: flex; align-items: center; gap: 0.5rem; width: 100%; text-align: left; cursor: pointer; font: inherit; font-size: 0.9rem;
+	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; }
+`;
+
+/** @type {Record<string, any>} */
+const _DEFAULT_CONFIGURATION =
+{
+	ProviderIdentifier: 'Pict-Section-Picker',
+
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0,
+};
+
+/**
+ * The pict-section-picker provider — the primary API surface. Registers the widget CSS once and
+ * creates/manages picker view instances.
+ */
+class PictProviderPicker extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, _DEFAULT_CONFIGURATION, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		if (this.pict && this.pict.CSSMap && typeof this.pict.CSSMap.addCSS === 'function')
+		{
+			this.pict.CSSMap.addCSS('Pict-Section-Picker-CSS', _PickerCSS, 500);
+		}
+	}
+
+	/**
+	 * Create (or reconfigure + reuse) a picker widget instance.
+	 *
+	 * @param {string} pPickerHash - A unique hash/id for this picker; the widget renders its control
+	 *   into the DOM element `#<pPickerHash>` unless a DestinationAddress is given.
+	 * @param {Record<string, any>} pConfig - Picker configuration:
+	 *   - DestinationAddress {string} - CSS selector to render into (default `#<pPickerHash>`).
+	 *   - ValueAddress {string} - AppData address the selection is read from / written to.
+	 *   - Mode {'single'} - selection mode (multi/categories/creatable land in later phases).
+	 *   - Placeholder {string} - text shown when nothing is selected.
+	 *   - Searchable {boolean} - show the search box (default true).
+	 *   - Options {Array<{Value:any, Text:string}>} - static option list.
+	 *   - OnChange {function} - optional callback invoked with the new value after a selection.
+	 * @return {any} The picker view instance.
+	 */
+	createPicker(pPickerHash, pConfig)
+	{
+		const tmpConfig = Object.assign(
+			{
+				DestinationAddress: `#${pPickerHash}`,
+				Mode: 'single',
+				Searchable: true,
+				Placeholder: 'Select…',
+				Options: [],
+			},
+			pConfig || {},
+			{ PickerHash: pPickerHash });
+
+		if (this.pict.views[pPickerHash])
+		{
+			Object.assign(this.pict.views[pPickerHash].options, tmpConfig);
+			return this.pict.views[pPickerHash];
+		}
+		return this.pict.addView(pPickerHash, tmpConfig, libPictViewPicker);
+	}
+
+	/**
+	 * Build the Meadow FoxHound filter for a search term across one or more fields.
+	 *
+	 * Single field → a clean AND-connected `FBV~Field~LK~%term%`. Multiple fields → the LIKEs are
+	 * OR'd together inside a paren group (`FOP…FCP`) so the OR can't bleed into a sibling AND base
+	 * filter. The term is `encodeURIComponent`-wrapped exactly as pict-section-recordset does, so the
+	 * structural `~` separators stay literal in the URL path while the value is escaped.
+	 *
+	 * @param {Array<string>} pSearchFields - The entity fields to LIKE-match.
+	 * @param {string} pTerm - The (raw) search term.
+	 * @return {string} The FoxHound filter stanza(s).
+	 */
+	buildSearchFilter(pSearchFields, pTerm)
+	{
+		const tmpEncoded = encodeURIComponent(`%${pTerm}%`);
+		if (pSearchFields.length === 1)
+		{
+			return `FBV~${pSearchFields[0]}~LK~${tmpEncoded}`;
+		}
+		const tmpInner = pSearchFields.map((pField, pIndex) => `${pIndex === 0 ? 'FBV' : 'FBVOR'}~${pField}~LK~${tmpEncoded}`).join('~');
+		return `FOP~0~(~0~${tmpInner}~FCP~0~)~0`;
+	}
+
+	/**
+	 * Build an async picker DataProvider backed by a Meadow entity (via `pict.EntityProvider`).
+	 * Returns a `(searchTerm, page) => Promise<{ results:[{Value,Text,Record}], hasMore }>` function —
+	 * the exact contract PictViewPicker consumes for server search + pagination.
+	 *
+	 * @param {Record<string, any>} pConfig - Entity source configuration:
+	 *   - Entity {string} (required) - the Meadow entity name (e.g. `Author`).
+	 *   - SearchFields {Array<string>} - fields to LIKE-search (default `['Name']`).
+	 *   - ValueField {string} - record field used as the option Value (default `ID<Entity>`).
+	 *   - 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`.
+	 *   - MapRecord {function} - optional `(record) => {Value, Text}` mapper (overrides Value/TextField).
+	 * @return {(pSearchTerm: string, pPage: number) => Promise<{results: Array<any>, hasMore: boolean}>}
+	 */
+	createEntityDataProvider(pConfig)
+	{
+		const tmpEntity = pConfig.Entity;
+		const tmpSearchFields = (Array.isArray(pConfig.SearchFields) && pConfig.SearchFields.length > 0) ? pConfig.SearchFields : [ 'Name' ];
+		const tmpValueField = pConfig.ValueField || `ID${tmpEntity}`;
+		const tmpTextField = pConfig.TextField || 'Name';
+		const tmpPageSize = pConfig.PageSize || 20;
+		const tmpSort = pConfig.Sort || false;
+		const tmpBaseFilter = pConfig.BaseFilter || '';
+		const tmpMapRecord = (typeof pConfig.MapRecord === 'function') ? pConfig.MapRecord : false;
+
+		return (pSearchTerm, pPage) => new Promise((resolve, reject) =>
+		{
+			if (!this.pict.EntityProvider || typeof this.pict.EntityProvider.getEntitySetPage !== 'function')
+			{
+				return reject(new Error('Pict-Section-Picker: pict.EntityProvider is not available for entity-backed pickers.'));
+			}
+
+			const tmpStanzas = [];
+			if (tmpBaseFilter) { tmpStanzas.push(tmpBaseFilter); }
+			if (pSearchTerm) { tmpStanzas.push(this.buildSearchFilter(tmpSearchFields, pSearchTerm)); }
+			if (tmpSort) { tmpStanzas.push(`FSF~${tmpSort}~ASC~0`); }
+			const tmpFilter = tmpStanzas.filter(Boolean).join('~');
+
+			const tmpCursor = (pPage || 0) * tmpPageSize;
+			this.pict.EntityProvider.getEntitySetPage(tmpEntity, tmpFilter, tmpCursor, tmpPageSize,
+				(pError, pRecords) =>
+				{
+					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) });
+				});
+		});
+	}
+
+	/**
+	 * 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`).
+	 *
+	 * @param {Record<string, any>} pConfig - Same shape as {@link createEntityDataProvider}.
+	 * @return {(pValue: any) => Promise<any>}
+	 */
+	createEntityResolveValue(pConfig)
+	{
+		const tmpEntity = pConfig.Entity;
+		const tmpValueField = pConfig.ValueField || `ID${tmpEntity}`;
+		const tmpTextField = pConfig.TextField || 'Name';
+		const tmpMapRecord = (typeof pConfig.MapRecord === 'function') ? pConfig.MapRecord : false;
+
+		return (pValue) => new Promise((resolve) =>
+		{
+			if (pValue === undefined || pValue === null || pValue === '' || !this.pict.EntityProvider)
+			{
+				return resolve(null);
+			}
+			this.pict.EntityProvider.getEntity(tmpEntity, pValue,
+				(pError, pRecord) =>
+				{
+					if (pError || !pRecord) { return resolve(null); }
+					return resolve(tmpMapRecord ? tmpMapRecord(pRecord) : { Value: pRecord[tmpValueField], Text: pRecord[tmpTextField], Record: pRecord });
+				});
+		});
+	}
+
+	/**
+	 * Create a picker backed by a Meadow entity — the high-level entry point for the real
+	 * lims/config/bridge entity pickers. Wires a server DataProvider + ResolveValue from `pConfig`
+	 * and delegates to {@link createPicker}. Any picker option (DestinationAddress, ValueAddress,
+	 * Placeholder, OnChange, …) may also be supplied and is passed through.
+	 *
+	 * @param {string} pPickerHash - Unique hash/id for this picker.
+	 * @param {Record<string, any>} pConfig - {@link createEntityDataProvider} config + picker options.
+	 * @return {any} The picker view instance.
+	 */
+	createEntityPicker(pPickerHash, pConfig)
+	{
+		const tmpConfig = Object.assign({}, pConfig);
+		tmpConfig.DataProvider = this.createEntityDataProvider(pConfig);
+		if (!tmpConfig.ResolveValue) { tmpConfig.ResolveValue = this.createEntityResolveValue(pConfig); }
+		return this.createPicker(pPickerHash, tmpConfig);
+	}
+}
+
+module.exports = PictProviderPicker;
+
+module.exports.default_configuration = _DEFAULT_CONFIGURATION;