@pacem/pacem 1.0.0-bessel → 1.0.0-binet

package/dist/browser/pacem-scaffolding.js

@@ -1,12 +1,14 @@
 /*!
- * @pacem/pacem v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 (function (pacemFoundation, pacemCore, pacemUi, pacemMaps) {
     'use strict';
 
+    /** Event type name (`'change'`) dispatched as a {@link FieldChangeEvent}. */
     const FieldChangeEventName = 'change';
+    /** Dispatched by a scaffolding field (see `PacemBaseElement.changeHandler` in `types-components.ts`) whenever its `value` actually changes as a result of user interaction; bubbles so an ancestor {@link PacemFormElement}/`PacemFormFieldElement` can react to it. */
     class FieldChangeEvent extends pacemCore.CustomTypedEvent {
         constructor(args) {
             super(FieldChangeEventName, args, { bubbles: true, cancelable: false });
@@ -14,6 +16,7 @@
     }
     //}
 
+    /** The primitive kinds an {@link ApiParameter} (or {@link DataField}) can be translated to, used to choose the appropriate auto-generated form field editor. */
     var ApiParameterType;
     (function (ApiParameterType) {
         ApiParameterType["String"] = "string";
@@ -23,7 +26,14 @@
         ApiParameterType["Binary"] = "binary";
         ApiParameterType["Object"] = "object";
     })(ApiParameterType || (ApiParameterType = {}));
+    /** Shared base for the OpenAPI/Swagger parsers: implements the common fetch-then-parse {@link ApiParser.load} flow, leaving the actual schema-to-{@link ApiManifest} translation to derived classes' `parse` implementation. */
     class ApiParserBase {
+        /**
+         * Fetches the API description document from `url` and parses it into an {@link ApiManifest}.
+         * @param url Url the API description (OpenAPI/Swagger document) is fetched from.
+         * @param headers Optional request headers (e.g. for authentication) sent along with the fetch.
+         * @returns The parsed manifest, or `null` if the response could not be retrieved/parsed as JSON.
+         */
         async load(url, headers) {
             let resp = await fetch(url, {
                 mode: 'cors', credentials: 'omit', headers: headers
@@ -38,6 +48,12 @@
         }
     }
     const $refPattern = /^#\/(definitions|components\/schemas)\/(.+)$/;
+    /**
+     * Resolves a `$ref` pointer (e.g. `#/definitions/Foo` or `#/components/schemas/Foo`) against an {@link ApiManifest}'s `definitions` map.
+     * @param manifest Manifest whose `definitions` are searched.
+     * @param $ref The `$ref` pointer to resolve.
+     * @returns The referenced definition's name and schema, or `null` if `$ref` doesn't match the expected pattern.
+     */
     function getOpenApiDefinition(manifest, $ref) {
         var rec = $refPattern.exec($ref);
         if (rec && rec.length > 2) {
@@ -49,6 +65,7 @@
 
     //namespace Pacem.Scaffolding.OpenApi {
     const ApiMethod = pacemCore.Net.HttpMethod;
+    /** Parses a Swagger (OpenAPI 2.0) document into a format-agnostic {@link ApiManifest}, translating its `paths`/`definitions` into endpoints, resolved schema definitions and parameter types used to auto-generate form fields. */
     class SwaggerParser extends ApiParserBase {
         _findDefinitionName(definitionHashTag) {
             var pattern = /#\/definitions\/(.+)/;
@@ -57,6 +74,12 @@
                 return definitionHashTag;
             return arr[1];
         }
+        /**
+         * Parses a Swagger (OpenAPI 2.0) document into an {@link ApiManifest}.
+         * @param content The Swagger document, either as a parsed object or as a JSON string.
+         * @param url Base url of the API, used to derive `baseUrl` when the document doesn't specify `host`/`schemes`.
+         * @returns The parsed manifest, with endpoints and resolved schema definitions.
+         */
         parse(content, url) {
             let j = content;
             if (typeof j === 'string') {
@@ -176,7 +199,14 @@
         }
     }
 
+    /** Parses an OpenAPI 3.x document into a format-agnostic {@link ApiManifest}, translating its `paths`/`components.schemas` into endpoints, resolved schema definitions and parameter types used to auto-generate form fields. */
     class OpenApi3Parser extends ApiParserBase {
+        /**
+         * Parses an OpenAPI 3.x document into an {@link ApiManifest}.
+         * @param content The OpenAPI 3.x document, either as a parsed object or as a JSON string.
+         * @param url Base url of the API, used as the manifest's `baseUrl`.
+         * @returns The parsed manifest, with endpoints and resolved schema definitions.
+         */
         parse(content, url) {
             let j = content;
             if (typeof j === 'string') {
@@ -289,12 +319,19 @@
     }
 
     //namespace Pacem.Scaffolding.OpenApi {
+    /** Format-detecting facade parser: inspects an API description document and delegates to {@link OpenApi3Parser} or {@link SwaggerParser} accordingly, producing a unified {@link ApiManifest} used to auto-generate form fields regardless of the source spec version. */
     class OpenApiParser extends ApiParserBase {
         constructor(_openApi3 = new OpenApi3Parser(), _swagger = new SwaggerParser()) {
             super();
             this._openApi3 = _openApi3;
             this._swagger = _swagger;
         }
+        /**
+         * Parses `content` as either an OpenAPI 3.x or a Swagger (OpenAPI 2.0) document, dispatching on the presence of an `openapi` property.
+         * @param content The API description, either as a parsed object or as a JSON string.
+         * @param url Base url of the API, forwarded to the delegate parser to resolve/derive the manifest's `baseUrl`.
+         * @returns The parsed manifest.
+         */
         parse(content, url) {
             let j = content;
             if (typeof j === 'string') {
@@ -330,6 +367,7 @@
         validator: (validatorType, validatorTypeIndex, prop, dictionary) => dictionary['validator_' + validatorType + '_' + prop] ?? dictionary['validator_' + validatorType + validatorTypeIndex + '_' + prop],
         commandTooltip: (commandName, dictionary) => dictionary['command_tooltip_' + commandName]
     };
+    /** Namespace-like static helper for localizing form {@link TypeMetadata} (labels, watermarks, descriptions, validator error messages, command tooltips) against a translation dictionary. */
     class Forms {
         /**
          * Localizes the metadata of a form **in place** using a translation dictionary.
@@ -404,20 +442,37 @@
         else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
+    /** Event type name (`'submit'`) dispatched as a {@link FormSubmitEvent}. */
     const FormSubmitEventName = 'submit';
+    /** Event type name (`'reset'`) dispatched as a {@link FormResetEvent}. */
     const FormResetEventName = 'reset';
+    /**
+     * Dispatched by {@link PacemFormElement} right before a submission is actually sent to the server, once all
+     * fields have validated successfully. Cancelable: calling `preventDefault()` (or handling the event and
+     * returning `false`) aborts the submission before any request is made - useful to inject/transform
+     * {@link FormSubmitEventArgs#parameters} or veto the submit outright.
+     */
     class FormSubmitEvent extends pacemCore.CustomTypedEvent {
         constructor(args) {
             super(FormSubmitEventName, args, { bubbles: true, cancelable: true });
         }
     }
+    /** Dispatched by {@link PacemFormElement} when the form is about to be reset (programmatically or via its generated reset button). Cancelable: calling `preventDefault()` aborts the reset, leaving fields as they were. */
     class FormResetEvent extends Event {
         constructor() {
             super(FormResetEventName, { bubbles: true, cancelable: true });
         }
     }
+    /** Event types re-dispatched/handled on behalf of a {@link PacemFormElement} by its {@link FormEventEmitter}: upload `download` events, field {@link FieldChangeEventName} changes, and item `command` events (see {@link Components.CommandEvent}). */
     const EMITTABLE_EVENT_TYPES = ['download' /* < dedicated, for the upload custom element */, FieldChangeEventName /* expose */, pacemCore.CommandEventName];
+    /** Sentinel value used to reject a submission's promise when it was canceled via {@link FormSubmitEvent#preventDefault}, as opposed to a genuine fetch failure. */
     const SUBMIT_CANCELLATION_TOKEN = false;
+    /**
+     * Listens on a {@link PacemEventTarget} (typically a {@link PacemFormElement}) for the events listed in
+     * {@link EMITTABLE_EVENT_TYPES} and pipes each through the target's `handle` method, additionally
+     * re-dispatching `command` events as a synthesized `'item' + commandName`-named `CustomEvent` (e.g.
+     * `itemdelete`, `itemselect`) so listeners can subscribe to the specific command they care about.
+     */
     class FormEventEmitter {
         constructor(_element) {
             this._element = _element;
@@ -431,13 +486,16 @@
                 }
             };
         }
+        /** Starts listening for {@link EMITTABLE_EVENT_TYPES} on the target element. */
         start() {
             EMITTABLE_EVENT_TYPES.forEach(t => this._element.addEventListener(t, this._itemEmitHandler, false));
         }
+        /** Stops listening for {@link EMITTABLE_EVENT_TYPES} on the target element. */
         stop() {
             EMITTABLE_EVENT_TYPES.forEach(t => this._element.removeEventListener(t, this._itemEmitHandler, false));
         }
     }
+    /** Base class for elements that need a reference to their closest ancestor {@link PacemFormElement} (form fields, validators): resolves and exposes it as {@link form} on activation. */
     class PacemFormRelevantElement extends pacemCore.Components.PacemElement {
         viewActivatedCallback() {
             super.viewActivatedCallback();
@@ -447,9 +505,18 @@
     __decorate$J([
         pacemCore.Watch({ converter: pacemCore.PropertyConverters.Element })
     ], PacemFormRelevantElement.prototype, "form", void 0);
+    /**
+     * `<p-form>`: the scaffolding package's central form element. Aggregates the validity/dirty state of its
+     * registered fields ({@link registerField}) and validators ({@link registerValidator}), of any nested
+     * sub-forms ({@link registerSubForm} - e.g. from a {@link Pacem.Components.Scaffolding.PacemChildFormElement}
+     * in `childform.ts`), drives submission ({@link submit}) and reset ({@link reset}), and - when `autogenerate`
+     * is `true` and `metadata` is provided - builds its own field markup from a {@link TypeMetadata}/
+     * {@link PropertyMetadata} description instead of requiring hand-authored markup.
+     */
     let PacemFormElement = class PacemFormElement extends PacemFormRelevantElement {
         constructor() {
             super('form');
+            /** Gets or sets the HTTP method used by the auto-generated fetcher. Defaults to `POST`. */
             this.method = pacemCore.Net.HttpMethod.Post;
             this._emitter = null;
             this._buttons = { submit: undefined, reset: undefined };
@@ -608,6 +675,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             return this._buttons;
         }
         #fetching;
+        /** @readonly Gets whether a submission is currently in flight; also reflected as the `pacem-fetching` CSS class. */
         get fetching() {
             return this.#fetching;
         }
@@ -789,6 +857,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             return Promise.resolve(false);
         }
+        /**
+         * Validates a single named field, or - when `name` is omitted - every field of this form and its
+         * sub-forms, running each field's registered validators and updating their `valid`/`invalid` state.
+         * @param name Optional name of a single field to validate; validates the whole form (recursively) when omitted.
+         */
         // @Concurrent()
         validate(name) {
             if (!pacemCore.Utils.isNullOrEmpty(name)) {
@@ -887,6 +960,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             this.valid = valid;
         }
         ;
+        /**
+         * Registers a nested {@link PacemFormElement} (e.g. rendered by a `PacemChildFormElement`, see
+         * `childform.ts`) so its fields' validity/dirtyness roll up into this form's own {@link valid}/{@link dirty}.
+         * @param form Sub-form to enroll
+         */
         registerSubForm(form) {
             let arr = this._subForms;
             if (arr.indexOf(form) == -1) {
@@ -896,6 +974,10 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 this._checkDirtyness();
             }
         }
+        /**
+         * Removes a previously-registered nested form; its fields no longer influence this form's {@link valid}/{@link dirty}.
+         * @param form Sub-form to remove
+         */
         unregisterSubForm(form) {
             let arr = this._subForms, ndx = arr.indexOf(form);
             if (ndx >= 0) {
@@ -905,6 +987,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 this._checkDirtyness();
             }
         }
+        /**
+         * Registers a field's {@link PacemModel} under `name`, so it is included in submission ({@link FormSubmitEventArgs#fields}), validation, dirty/valid roll-up and reset. Typically called by the field itself (see `PacemModelElement._registerFieldConditionally` in `types-components.ts`) rather than directly.
+         * @param name Field name to register under
+         * @param model Field implementing {@link PacemModel}
+         */
         registerField(name, model) {
             var container = this._fields;
             if (container[name] != model) {
@@ -918,6 +1005,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 this._checkDirtyness();
             }
         }
+        /**
+         * Removes a previously-registered field.
+         * @param name Field name to remove
+         * @param check Whether to re-check the form's overall validity/dirtyness afterwards (default `true`)
+         */
         unregisterField(name, check = true) {
             var container = this._fields, current = container[name];
             if (current instanceof HTMLElement) {
@@ -929,6 +1021,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 this._checkDirtyness();
             }
         }
+        /**
+         * Registers a {@link Validator} (typically a {@link PacemBaseValidatorElement}) against the named field, so it participates in that field's validation. Typically called by the validator itself rather than directly.
+         * @param name Name of the field being validated
+         * @param validator Validator to enroll
+         */
         registerValidator(name, validator) {
             var container = this._validators[name] = this._validators[name] || [], index = container.indexOf(validator);
             if (index == -1) {
@@ -941,6 +1038,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 this._checkFieldValidity(name);
             }
         }
+        /**
+         * Removes a previously-registered validator from the named field.
+         * @param name Name of the field the validator was registered against
+         * @param validator Validator to remove
+         */
         unregisterValidator(name, validator) {
             this._unregisterValidator(name, validator, true);
         }
@@ -1024,7 +1126,17 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
+    /** Attached-property key used to stash a field's pristine value on the element itself (see {@link PacemModelElement.originalValue}). */
     const ORIGINAL_VALUE_FIELD = 'pacem:model:original-value';
+    /**
+     * Base class for any element that behaves as a bindable, form-aware model value: it registers itself by
+     * `name` with the ancestor {@link PacemFormElement} (found via {@link PacemFormRelevantElement}), tracks
+     * `dirty`/`valid` state (reflected as `pacem-dirty`/`pacem-invalid` CSS classes), and remembers the value it
+     * had when activated/set-pristine so {@link reset} can restore it.
+     *
+     * Concrete input/selection fields don't extend this directly - see {@link PacemBaseElement}, the abstract
+     * subclass that adds readonly/required/focus/keyboard handling on top of it.
+     */
     class PacemModelElement extends PacemFormRelevantElement {
         viewActivatedCallback() {
             super.viewActivatedCallback();
@@ -1090,22 +1202,26 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 form.unregisterField(name);
             super.disconnectedCallback();
         }
+        /** @readonly The `value` this element had the last time it was activated or explicitly marked pristine (via {@link setPristine}); what {@link reset} restores. */
         get originalValue() {
             return pacemCore.CustomElementUtils.getAttachedPropertyValue(this, ORIGINAL_VALUE_FIELD);
         }
         _setAsOriginalValue(v) {
             pacemCore.CustomElementUtils.setAttachedPropertyValue(this, ORIGINAL_VALUE_FIELD, v);
         }
+        /** Restores {@link value} to {@link originalValue} and clears {@link dirty}. */
         reset() {
             this.value = this.originalValue;
             // then
             this.dirty = false;
         }
+        /** Marks the current `value` as the new baseline for {@link reset}/{@link originalValue} and clears {@link dirty}. */
         setPristine() {
             this._setAsOriginalValue(this.value);
             //
             this.dirty = false;
         }
+        /** Marks this field as `dirty`. */
         setDirty() {
             this.dirty = true;
         }
@@ -1135,6 +1251,16 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
     __decorate$I([
         pacemCore.Watch({ converter: pacemCore.PropertyConverters.String })
     ], PacemModelElement.prototype, "name", void 0);
+    /**
+     * Base class for editable form fields: it adds `required`/`autofocus`/`readonly`/`placeholder` state, focus
+     * and keyboard handling (Esc to revert, Enter submit prevention), and the plumbing that wires the
+     * `focus`/`blur`/`change`/`keydown`/`keyup` handlers onto whichever native {@link inputFields} a derived
+     * class exposes.
+     *
+     * Not extended directly by concrete fields either - see {@link PacemBaseInputElement} (in `input.ts`) for
+     * `<input>`/`<textarea>`-backed fields, and {@link PacemDataSourceElement} for datasource-driven ones
+     * (lists, selects, radio groups, ...).
+     */
     class PacemBaseElement extends PacemModelElement {
         constructor() {
             super(...arguments);
@@ -1205,6 +1331,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         compareValuePropertyValues(old, val) {
             return pacemCore.DefaultComparer(old, val);
         }
+        /** @overridable Whether pressing Enter within this field should be prevented from submitting an ancestor form. Defaults to `false`. */
         get preventKeyboardSubmit() {
             return false;
         }
@@ -1338,12 +1465,18 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
     __decorate$I([
         pacemCore.Watch({ converter: pacemCore.PropertyConverters.String })
     ], PacemBaseElement.prototype, "placeholder", void 0);
+    /**
+     * Scaffolding-specific counterpart of `@pacem/pacem-ui`'s `PacemItemElement`: a base class for elements that
+     * register themselves against an ancestor {@link PacemItemsContainerBaseElement} (found via
+     * {@link findContainer}) on activation, and unregister on disconnect. Extended by {@link PacemDataItemElement}.
+     */
     class PacemItemElement extends pacemCore.Components.PacemElement {
         #container;
-        /** @overridable */
+        /** @overridable Locates the ancestor items-container this item registers against. Defaults to the nearest {@link PacemItemsContainerBaseElement}. */
         findContainer() {
             return pacemCore.CustomElementUtils.findAncestor(this, n => n instanceof PacemItemsContainerBaseElement);
         }
+        /** @readonly Gets the items-container this item is currently registered with, if any. */
         get container() {
             return this.#container;
         }
@@ -1361,6 +1494,12 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             super.disconnectedCallback();
         }
     }
+    /**
+     * Base class for form fields that also act as a registry of {@link PacemItemElement} children (e.g. a
+     * datasource-backed selection field whose options are declared, not just databound). Combines
+     * {@link PacemBaseElement}'s field behavior with `ItemsContainer<TItem>`'s registration API.
+     * See {@link PacemDataSourceElement} for the concrete specialization holding {@link PacemDataItemElement}s.
+     */
     class PacemItemsContainerBaseElement extends PacemBaseElement {
         /**
          * Registers a new item among the items.
@@ -1395,6 +1534,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
     __decorate$I([
         pacemCore.Watch( /* can only be databound or assigned at runtime */)
     ], PacemItemsContainerBaseElement.prototype, "items", void 0);
+    /** A single, declaratively-authored option (`<p-data-item>`) of a {@link PacemDataSourceElement}, as an alternative to a databound `datasource` array. */
     let PacemDataItemElement = class PacemDataItemElement extends PacemItemElement {
     };
     __decorate$I([
@@ -1429,6 +1569,13 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
     PacemDataItemElement = __decorate$I([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-data-item' })
     ], PacemDataItemElement);
+    /**
+     * Base class for datasource-driven selection fields (lists, dropdowns, radio/checkbox groups, autocomplete,
+     * ...): adapts a raw `datasource` (an array of arbitrary entities, or declared {@link PacemDataItemElement}
+     * children registered via {@link PacemItemsContainerBaseElement}) into a normalized {@link DataSource}, and
+     * provides the value/view-value mapping and selection-matching logic (single or, when `multipleChoice` is
+     * `true`, multi-select) that concrete subclasses build their UI on top of.
+     */
     class PacemDataSourceElement extends PacemItemsContainerBaseElement {
         constructor(multipleChoice = false) {
             super();
@@ -1459,9 +1606,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             return flag;
         }
+        /** @overridable Maps a raw `datasource` array into its {@link DataSource} representation via {@link mapEntityToItem}. */
         buildAdaptedDatasource(ds = this.datasource) {
             return ds && ds.map(i => this.mapEntityToItem(i));
         }
+        /** Recomputes {@link adaptedDatasource} and, if the current `value` no longer matches any item, calls {@link handleDatasourceMismatch}. Debounced. */
         databind(datasource = this.buildAdaptedDatasource(this.datasource)) {
             if (pacemCore.Utils.isNull(datasource) && pacemCore.Utils.isNull(this.adaptedDatasource))
                 return;
@@ -1470,6 +1619,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             if (pacemCore.Utils.isNullOrEmpty(ds.filter(i => this.isDataSourceItemSelected(i))))
                 this.handleDatasourceMismatch(ds);
         }
+        /** @overridable Called by {@link databind} when the current `value` matches none of the adapted `datasource` items. Defaults to clearing `value`. */
         handleDatasourceMismatch(datasource) {
             this.value = undefined;
         }
@@ -1519,6 +1669,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 return false;
             }
         }
+        /** @overridable Extracts the selectable `value` out of a raw datasource entity (via {@link valueProperty}, or `entity.value` for a {@link PacemDataItemElement}). */
         mapEntityToValue(entity) {
             if (entity == null) {
                 throw 'entity cannot be null';
@@ -1534,6 +1685,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             return value;
         }
+        /** @overridable Extracts the display text out of a raw datasource entity (via {@link textProperty}, or `entity.label`/`entity.value` for a {@link PacemDataItemElement}). */
         mapEntityToViewValue(entity) {
             if (entity == null)
                 throw 'entity cannot be null';
@@ -1548,6 +1700,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             return viewValue;
         }
+        /** @overridable Adapts a raw datasource entity into its normalized {@link DataSourceItem} shape, using {@link mapEntityToValue}, {@link mapEntityToViewValue} and {@link disabledProperty}. */
         mapEntityToItem(entity) {
             if (entity == null) {
                 throw 'entity cannot be null';
@@ -1631,7 +1784,9 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Markup fragment for a `pacem-char-count` companion element, meant to be spliced into a `@CustomElement` template so a text field can display its own character counter. */
     const CHAR_COUNTER_CHILD = `<${pacemCore.P}-char-count hide="{{ :host.readonly || !(:host.minlength > 0 || :host.maxlength > 0) }}" minlength="{{ :host.minlength }}" maxlength="{{ :host.maxlength }}" string="{{ :host.value }}"></${pacemCore.P}-char-count>`;
+    /** Displays how many characters {@link string} contains, relative to {@link minlength}/{@link maxlength}, flagging validity via CSS class. */
     let PacemCharCountElement = class PacemCharCountElement extends pacemCore.Components.PacemElement {
         _isValid(v) {
             const l = this._length(v);
@@ -1680,6 +1835,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             super('contenteditablechange', { html: html });
         }
     }
+    /** Base class for {@link PacemContenteditableElement} toolbar/command items, registered as {@link PacemItemElement} children of the editor. */
     class PacemContenteditableCommandElement extends PacemItemElement {
         constructor() {
             super(...arguments);
@@ -1736,6 +1892,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
     function isElement(node) {
         return node?.nodeType == Node.ELEMENT_NODE;
     }
+    /** Rich-text (`contenteditable`) field, hosting {@link PacemContenteditableCommandElement} toolbar commands and tracking an undo/redo {@link history}. */
     let PacemContenteditableElement = class PacemContenteditableElement extends PacemItemsContainerBaseElement {
         constructor() {
             super('rich text editor');
@@ -1816,6 +1973,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             //this._workspace = document.createElement('div');
         }
         #history;
+        /** @readonly Gets the undo/redo history service tracking this editor's HTML content. */
         get history() {
             return this.#history;
         }
@@ -1995,6 +2153,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Base class for the toolbar button-shaped contenteditable commands (bold, align, link, wrap, ...), sharing icon/shortcut/tooltip/active-state behavior. */
     class PacemContenteditableButtonCommandElement extends PacemContenteditableCommandElement {
         cleanUp(_) {
             // do nothing
@@ -2036,6 +2195,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Toolbar button undoing or redoing the last change tracked by the contenteditable host's history. */
     let PacemContenteditableHistoryCommandElement = class PacemContenteditableHistoryCommandElement extends PacemContenteditableButtonCommandElement {
         exec() {
             return new Promise((resolve, _) => {
@@ -2099,6 +2259,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Toolbar button creating or removing a hyperlink (`<a>`) around the current selection. */
     let PacemContenteditableLinkCommandElement = class PacemContenteditableLinkCommandElement extends PacemContenteditableButtonCommandElement {
         isRelevant(range) {
             return !pacemCore.Utils.isNull(ContenteditableUtils.findSurroundingNode(range, HTMLAnchorElement));
@@ -2189,6 +2350,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             });
         });
     }
+    /** Toolbar button inserting a (rescalable) picture into the contenteditable host, either by file picker or by pasted/dropped image file. */
     let PacemContenteditableImageCommandElement = class PacemContenteditableImageCommandElement extends PacemContenteditableButtonCommandElement {
         constructor() {
             super(...arguments);
@@ -2368,6 +2530,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Well-known `document.execCommand` commands supported out-of-the-box by {@link PacemContenteditableExecCommandElement}. */
     var KnownExecCommand;
     (function (KnownExecCommand) {
         KnownExecCommand["Bold"] = "bold";
@@ -2443,6 +2606,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
                 return ['none'];
         }
     }
+    /** Toolbar button applying a native `document.execCommand`-backed formatting command (bold, italic, lists, ...) to the contenteditable host. */
     let PacemContenteditableExecCommandElement = class PacemContenteditableExecCommandElement extends PacemContenteditableButtonCommandElement {
         _matchRelevance(range, arg) {
             const found = (typeof arg === 'object') ?
@@ -2528,7 +2692,14 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             && element.hasAttribute('role')
             && element.attributes['role'].value === 'presenter';
     }
+    /** Watches a contenteditable host for insertion/removal of elements matching a given selector (e.g. inert `[contenteditable=false]` islands), notifying a callback for each match, recursively. */
     class ContenteditableDOMObserver {
+        /**
+         * Initializes the observer, immediately scanning the given container and then watching it for further mutations.
+         * @param contentElement The contenteditable container to observe.
+         * @param mutationCallback Invoked for each matching node found, added or removed.
+         * @param selector CSS selector used to filter relevant nodes.
+         */
         constructor(contentElement, mutationCallback, selector = '*[contenteditable=false]') {
             this.#callback = mutationCallback;
             this.#selector = selector;
@@ -2564,6 +2735,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             contentElement.querySelectorAll(this.#selector).forEach(el => this.#callback(el, true));
         }
+        /** Stops observing and notifies the callback, as a removal, for every currently matching node. */
         dispose() {
             this._disposeContainer(this.#contentElement);
         }
@@ -2572,7 +2744,9 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         #contentElement;
         #mutationObserver;
     }
+    /** Collection of static DOM/Range helper methods shared by the contenteditable command elements. */
     class ContenteditableUtils {
+        /** Builds the default toolbar dashboard (undo/redo, formatting, alignment, link and image commands) as a detached fragment. */
         static getDefaultDashboard() {
             const frag = new DocumentFragment();
             const toolbar0 = document.createElement('div');
@@ -2637,9 +2811,17 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             return node;
         }
+        /**
+         * Seeks for the nearest surrounding block-level element of a given Selection's range.
+         * @param range
+         */
         static findSurroundingBlockElement(range) {
             return this.findSurroundingNode(range, ContenteditableUtils.isBlockElement);
         }
+        /**
+         * Retrieves the sibling block-level elements (e.g. paragraphs) touched by a given Selection's range.
+         * @param range
+         */
         static findSurroundingSiblingBlockElements(range) {
             let output = [];
             if (isRoot(range.startContainer)) {
@@ -2679,6 +2861,10 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             return started ? output : (root instanceof Element && !isRoot(root) ? [root] : []);
         }
+        /**
+         * Retrieves the top-level (direct children of the contenteditable root) elements spanned by a given Selection's range.
+         * @param range
+         */
         static findContainingRootElements(range) {
             const range1 = range.cloneRange(), range2 = range.cloneRange();
             range1.collapse(true);
@@ -2690,9 +2876,18 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             }
             return retval;
         }
+        /**
+         * Checks whether the given node is an `Element` with a block-level (non-`inline*`) computed display.
+         * @param node
+         */
         static isBlockElement(node) {
             return node instanceof Element && !getComputedStyle(node).display.startsWith('inline');
         }
+        /**
+         * Selects a node (or its contents, when `inside` is `true`) and applies the resulting range to the current document Selection.
+         * @param node
+         * @param inside
+         */
         static select(node, inside = false) {
             const range = document.createRange();
             if (!inside) {
@@ -2708,6 +2903,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             selection.addRange(range);
             return range;
         }
+        /**
+         * Copies all attributes from one element onto another.
+         * @param to
+         * @param from
+         */
         static copyAttributes(to, from) {
             const attrs = from.attributes;
             for (let j = 0; j < attrs.length; j++) {
@@ -2741,6 +2941,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
     function getAlignIcon(align) {
         return 'format_align_' + align;
     }
+    /** Toolbar button applying a text-alignment (left/center/right/justify) style to the block(s) touched by the current selection. */
     let PacemContenteditableAlignCommandElement = class PacemContenteditableAlignCommandElement extends PacemContenteditableButtonCommandElement {
         isRelevant(range) {
             const els = ContenteditableUtils.findSurroundingSiblingBlockElements(range);
@@ -2819,6 +3020,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         }
         return { result: false };
     }
+    /** Dropdown command inserting an inert (`contenteditable=false`) placeholder token, picked from a suggestable datasource, into the contenteditable host. */
     let PacemContenteditablePlaceholderElement = class PacemContenteditablePlaceholderElement extends PacemContenteditableCommandElement {
         constructor() {
             super(...arguments);
@@ -2955,6 +3157,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Toolbar button wrapping (or, if already applied, unwrapping) the block(s) touched by the current selection with a given tag (e.g. `blockquote`, `h1`). */
     let PacemContenteditableWrapCommandElement = class PacemContenteditableWrapCommandElement extends PacemContenteditableButtonCommandElement {
         isRelevant(range) {
             return !pacemCore.Utils.isNull(ContenteditableUtils.findSurroundingNode(range, this.tagname));
@@ -3065,6 +3268,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         }
         return header;
     }
+    /** Utility 12-month grid picker, used internally by {@link PacemCalendarPickerElement} to pick a month within {@link viewYear}. */
     let PacemCalendarMonthPickerElement = class PacemCalendarMonthPickerElement extends pacemCore.Components.PacemElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -3113,6 +3317,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
             template: `<div class="${pacemCore.PCSS}-month-picker">${buildMonthGrid()}</div>`
         })
     ], PacemCalendarMonthPickerElement);
+    /** Dispatched by {@link PacemCalendarPickerElement} when its clear button is used to unselect the current date. */
     class CalendarDateUnselectEvent extends pacemUi.Components.UI.DateSelectEvent {
         constructor() {
             super(void 0);
@@ -3132,6 +3337,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         const mod = y % 10;
         return y - mod;
     }
+    /** Utility grid picker of {@link YEARS_IN_RANGE} years, used internally by {@link PacemCalendarPickerElement} to pick a year within the range containing {@link viewYear}. */
     let PacemCalendarYearPickerElement = class PacemCalendarYearPickerElement extends pacemCore.Components.PacemElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -3187,9 +3393,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         }
         return `<${pacemCore.P}-panel hide="{{ :host.viewmode !== 'calendar' }}" class="calendar-header">${header}</${pacemCore.P}-panel>`;
     }
+    /** {@link PacemBaseInputElement}-alike field that pops up a `pacem-calendar` (with month/year zoom levels) to pick a `Date` value. */
     let PacemCalendarPickerElement = class PacemCalendarPickerElement extends PacemBaseElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets which picker is currently shown in the dropdown: the day calendar, the month grid, or the year grid. */
             this.viewmode = 'calendar';
             this.#locked = false;
             this._swipeHandler = (e) => {
@@ -3522,9 +3730,11 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         convert: (attr) => attr === 'true' ? true : (attr === 'false' ? false : attr),
         convertBack: (prop) => prop.toString()
     };
+    /** {@link PacemBaseElement}-based single checkbox field, mapping its checked state to {@link trueValue}/{@link falseValue}. */
     let PacemCheckboxElement = class PacemCheckboxElement extends PacemBaseElement {
         constructor() {
             super('checkbox');
+            /** Gets or sets the label displayed next to the checkbox (and used as the read-only view value when checked). */
             this.caption = '';
             this._key = '_' + pacemCore.Utils.uniqueCode();
         }
@@ -3628,6 +3838,7 @@ disabled="{{ (#${uid}.suddenValidation && (!(#${uid}.valid && #${uid}.dirty))) |
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Renders {@link PacemDataSourceElement#datasource} as a list of `pacem-checkbox` items, producing an array `value` of the checked items' mapped values. */
     let PacemCheckboxListElement = class PacemCheckboxListElement extends PacemDataSourceElement {
         acceptValue(val) {
             // no need to implement
@@ -3950,17 +4161,24 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     //        super('datetimechange', { date: date });
     //    }
     //}
+    /** {@link PacemBaseElement}-based field composing a set of `pacem-select` dropdowns (year/month/day and, depending on {@link precision}, time) into a single `Date` value. */
     let PacemDatetimePickerElement = class PacemDatetimePickerElement extends PacemBaseElement {
         constructor() {
             super();
+            /** Gets or sets the granularity of the picker: date only, or including hours/minutes ('minute') or hours/minutes/seconds ('second'). */
             this.precision = 'day';
             this._months = [];
+            /** Internal: datasource of selectable days for the current {@link year}/{@link month}. */
             this._dates = [];
             this._a24 = [];
             this._a60 = [];
+            /** Internal: datasource of selectable years, computed from {@link min}/{@link max}. */
             this._years = [];
+            /** Internal: the hours select's current value. */
             this.hours = '00';
+            /** Internal: the minutes select's current value. */
             this.minutes = '00';
+            /** Internal: the seconds select's current value. */
             this.seconds = '00';
         }
         get inputFields() {
@@ -4240,6 +4458,13 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     // TODO: add warning state
+    /**
+     * Base class for all `p-*-validator` elements: registers/unregisters itself against the ancestor
+     * {@link PacemFormElement} field named by `watch`, and turns the abstract {@link evaluate} logic into the
+     * `Validator` contract's `validate` (short-circuiting to valid when `disabled`). Concrete validators only
+     * need to implement {@link evaluate}; the field's own error UI reads `invalid`/`errorMessage` off the
+     * element (see {@link BASIC_VALIDATOR_TEMPLATE}).
+     */
     class PacemBaseValidatorElement extends PacemFormRelevantElement {
         constructor() {
             super();
@@ -4273,6 +4498,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
             }
         }
         #easer;
+        /** Asks the owning {@link PacemFormElement} to re-validate the watched field on the next animation frame; call after a configuration property (e.g. `min`/`max`/`pattern`) changes so the field re-evaluates against the new rule. */
         triggerFormFieldValidation() {
             const form = this.form, watch = this.watch;
             if (!pacemCore.Utils.isNull(form) && !pacemCore.Utils.isNullOrEmpty(watch)) {
@@ -4282,6 +4508,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
                 });
             }
         }
+        /** Validates `val` against this validator's rule; always resolves `true` (skips {@link evaluate}) when the validator is `disabled`. */
         validate(val) {
             if (this.disabled) {
                 return pacemCore.Utils.fromResult(true);
@@ -4298,11 +4525,13 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     __decorate$s([
         pacemCore.Watch({ emit: false, reflectBack: true, converter: pacemCore.PropertyConverters.String })
     ], PacemBaseValidatorElement.prototype, "watch", void 0);
+    /** Default shadow-DOM template shared by every built-in `p-*-validator`: a `<p-span>` (exposed as the `error-message` part) shown only while `invalid`, displaying `errorMessage`. */
     const BASIC_VALIDATOR_TEMPLATE = `<${pacemCore.P}-span part="error-message" hide="{{ !:host.invalid  }}" text="{{ :host.errorMessage }}"></${pacemCore.P}-span>`;
     // #region TEXTUAL
     function isValueEmpty(val) {
         return pacemCore.Utils.isNullOrEmpty(val);
     }
+    /** Validates that a field's value is not empty (`p-required-validator`). */
     let PacemRequiredValidatorElement = class PacemRequiredValidatorElement extends PacemBaseValidatorElement {
         evaluate(val) {
             let retval = !isValueEmpty(val);
@@ -4312,6 +4541,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     PacemRequiredValidatorElement = __decorate$s([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-required-validator', template: BASIC_VALIDATOR_TEMPLATE, shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemRequiredValidatorElement);
+    /** Validates that a field's (non-empty) value matches a regular expression (`p-regex-validator`). */
     let PacemRegexValidatorElement = class PacemRegexValidatorElement extends PacemBaseValidatorElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -4333,6 +4563,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     PacemRegexValidatorElement = __decorate$s([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-regex-validator', template: BASIC_VALIDATOR_TEMPLATE, shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemRegexValidatorElement);
+    /** Validates that a field's (non-empty) value's string length falls within `[min, max]` (`p-length-validator`). */
     let PacemLengthValidatorElement = class PacemLengthValidatorElement extends PacemBaseValidatorElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -4363,6 +4594,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     ], PacemLengthValidatorElement);
     // #endregion
     // #region NUMERIC/ORDINAL
+    /** Validates that a field's (non-empty) numeric or date value falls within `[min, max]` (`p-range-validator`); dates (parsed via `Utils.parseDate`) are compared by their timestamp. */
     let PacemRangeValidatorElement = class PacemRangeValidatorElement extends PacemBaseValidatorElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -4402,6 +4634,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     ], PacemRangeValidatorElement);
     // #endregion
     // #region COMPLEX
+    /** Validates a field's (non-empty) value against another (non-empty) value `to`, using the given comparison `operator` (`p-compare-validator`); dates are compared by their timestamp. */
     let PacemCompareValidatorElement = class PacemCompareValidatorElement extends PacemBaseValidatorElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -4456,6 +4689,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
         pacemCore.CustomElement({ tagName: pacemCore.P + '-compare-validator', template: BASIC_VALIDATOR_TEMPLATE, shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemCompareValidatorElement);
     // #endregion
+    /** Validates a {@link BinaryValue}/file-name (non-empty) upload against an optional filename `pattern` and/or `maxSize` in bytes (`p-binary-validator`). */
     let PacemBinaryValidatorElement = class PacemBinaryValidatorElement extends PacemBaseValidatorElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -4489,6 +4723,13 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     PacemBinaryValidatorElement = __decorate$s([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-binary-validator', template: BASIC_VALIDATOR_TEMPLATE, shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemBinaryValidatorElement);
+    /**
+     * Validates a field's (non-empty) value by calling a remote `url` (`p-async-validator`), sending it - along
+     * with any extra `parameters` - as a request parameter named after {@link PacemBaseValidatorElement#watch}.
+     * The response is considered valid when it is the literal text `'true'`, or a fetched JSON payload whose API
+     * result (see `Utils.getApiResult`) is truthy; anything else (including a failed fetch) is invalid.
+     * Debounces requests by 1 second and memoizes the last request/result to avoid redundant round-trips.
+     */
     let PacemAsyncValidatorElement = class PacemAsyncValidatorElement extends PacemBaseValidatorElement {
         constructor() {
             super(...arguments);
@@ -4608,6 +4849,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
             template: BASIC_VALIDATOR_TEMPLATE + `<${pacemCore.P}-fetch autofetch="false" throttle="true" credentials="{{ :host.fetchCredentials }}" headers="{{ :host.fetchHeaders }}"></${pacemCore.P}-fetch>`, shadow: pacemCore.Defaults.USE_SHADOW_ROOT
         })
     ], PacemAsyncValidatorElement);
+    /** Validates a field's (non-empty) value by deferring entirely to the externally-controlled {@link isValid} flag (`p-custom-validator`), for validation logic that doesn't fit the other built-in validators. */
     let PacemCustomValidatorElement = class PacemCustomValidatorElement extends PacemBaseValidatorElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -4650,6 +4892,11 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     function isValidatorFactory(v) {
         return 'attributes' in v && typeof v.attributes === 'function';
     }
+    /**
+     * Renders a single editing field (label, input, validators, tooltip) for {@link entity}'s property described by {@link metadata},
+     * dynamically choosing and building up the concrete input element (e.g. `pacem-input-text`, `pacem-select`, `pacem-checkbox`, ...)
+     * based on the metadata's `dataType`/`ui` hints. Used internally by `pacem-form` for autogenerated forms.
+     */
     let PacemFormFieldElement = class PacemFormFieldElement extends PacemFormRelevantElement {
         constructor(_md = new pacemUi.Components.UI.MarkdownService()) {
             super();
@@ -4663,12 +4910,15 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
             };
             this._key = '_' + pacemCore.Utils.uniqueCode();
         }
+        /** @readonly Gets this field's unique key, used to derive DOM ids for the label/input/fetcher. */
         get key() {
             return this._key;
         }
+        /** @readonly Gets the inner `pacem-fetch` element used to retrieve remotely-sourced datasources for this field. */
         get fetcher() {
             return this._fetcher;
         }
+        /** @readonly Gets the concrete input element built for this field (e.g. `pacem-input-text`, `pacem-select`, ...). */
         get field() {
             return this._field;
         }
@@ -5697,6 +5947,7 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     const MIN_LENGTH = 3;
+    /** {@link PacemBaseElement}-based field pairing an address `pacem-suggest` (forward geocoding) with a draggable map marker (reverse geocoding) to pick an {@link Address}. */
     let PacemGeolocateElement = class PacemGeolocateElement extends PacemBaseElement {
         constructor() {
             super(...arguments);
@@ -5906,6 +6157,10 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
     const HIERARCHYITEM_MOVE_CSSCLASS = 'item-move';
     const HIERARCHYITEM_MOVE_ICON = 'drag_indicator';
     const DEFAULT_PARENTSPROPERTY = 'parents';
+    /**
+     * {@link PacemBaseElement}-based field for editing a DAG-like parent/child hierarchy over {@link datasource}: items are
+     * arranged level-by-level and linked/unlinked via drag-drop, producing an array `value` of `{ [valueProperty]: any, parents: any[] }`.
+     */
     let PacemHierarchyElement = class PacemHierarchyElement extends PacemBaseElement {
         getViewValue(value) {
             return '';
@@ -5917,6 +6172,7 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
             super();
             this.#bindings = new Map();
             this.#dropTargets = new Map();
+            /** Gets or sets the caption of the balloon button used to unlink a parent/child relation. */
             this.unlinkCaption = 'Delete';
             this._binderClickHandler = (evt) => {
                 const origType = evt.originalEvent.type;
@@ -6396,16 +6652,30 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** When a {@link PacemBaseInputElement} propagates its native input's value to the `value` property: on every keystroke (`Input`), or only once the field loses focus (`Blur`). */
     var ChangePolicy;
     (function (ChangePolicy) {
         ChangePolicy["Input"] = "input";
         ChangePolicy["Blur"] = "blur";
     })(ChangePolicy || (ChangePolicy = {}));
+    /** Attached-property key used to mark a native `<input>`/`<textarea>` as already wired up, so re-registration doesn't double-attach listeners (see {@link PacemBaseInputElement#registerInputFields}). */
     const INPUT_FIELD_ACTIVATED_PROP = 'pacem:scaffolding:input_field';
+    /**
+     * Base class for fields backed by one or more native `<input>`/`<textarea>` elements ({@link inputField}):
+     * wires `input`/`focus` listeners onto them, applies `changePolicy`/`debounce` to decide when the native
+     * value is read back into {@link PacemModelElement#value} (via {@link getValue}), and optionally
+     * auto-selects the field's content on focus.
+     *
+     * Extended by {@link PacemOrdinalInputElement} (numeric/date-like inputs) and
+     * {@link PacemTextualInputElement} (text-like inputs); further specialized by the concrete `input-*.ts`
+     * elements in this package (e.g. text, number, date, password, ...).
+     */
     class PacemBaseInputElement extends PacemBaseElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets how long to wait, after the native input changes, before propagating the value: `false` (default, propagate on the next animation frame), `true` (propagate via `requestAnimationFrame`), or a number of milliseconds to debounce by. */
             this.debounce = false;
+            /** Gets or sets when the native input's value gets read back into {@link PacemModelElement#value}: on every `input` event, or only on `blur`. Defaults to {@link ChangePolicy.Input}. */
             this.changePolicy = ChangePolicy.Input;
             this._focusHandler = (evt) => {
                 if (!this.autoselect) {
@@ -6436,6 +6706,7 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
                 this.inputField.value = pacemCore.Utils.isNullOrEmpty(val) ? '' : val;
             }
         }
+        /** @readonly Gets the first (usually only) native input element among {@link PacemBaseElement#inputFields}. */
         get inputField() {
             return this.inputFields[0];
         }
@@ -6540,6 +6811,11 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
     __decorate$o([
         pacemCore.Watch({ emit: false, converter: pacemCore.PropertyConverters.Boolean })
     ], PacemBaseInputElement.prototype, "autoselect", void 0);
+    /**
+     * Base class for numeric/ordinal native inputs (e.g. `number`, `range`, `date`-like fields): adds
+     * `min`/`max`/`step`, mirrored onto the native input's own attributes, and parses its `value` attribute as
+     * a float.
+     */
     class PacemOrdinalInputElement extends PacemBaseInputElement {
         convertValueAttributeToProperty(attr) {
             return parseFloat(attr);
@@ -6572,6 +6848,11 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
             }
         })
     ], PacemOrdinalInputElement.prototype, "step", void 0);
+    /**
+     * Base class for text-like native inputs (e.g. `text`, `password`, `textarea` fields): adds
+     * `pattern`/`minlength`/`maxlength`, mirrored onto the native input's own attributes, and treats an empty
+     * string `value` as `null`.
+     */
     class PacemTextualInputElement extends PacemBaseInputElement {
         convertValueAttributeToProperty(attr) {
             return attr;
@@ -6610,10 +6891,13 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** {@link PacemBaseInputElement} rendering one single-character `<input>` per position (e.g. OTP/verification codes), joining them into a single string `value`. */
     let PacemCharsInputElement = class PacemCharsInputElement extends PacemBaseInputElement {
         constructor() {
             super();
+            /** Gets or sets how many single-character inputs to render. */
             this.charCount = 6;
+            /** Gets or sets how the entered characters are transformed/displayed: as-is, forced to a case, or masked like a password. */
             this.inputTransform = 'none';
             this._itemCreateHandler = (e) => {
                 const { dom, index } = e.detail;
@@ -6792,6 +7076,7 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** {@link PacemBaseElement}-based field pairing a native color picker with an alpha (0-100) slider, producing a hex/rgba color string `value`. */
     let PacemColorInputElement = class PacemColorInputElement extends PacemBaseElement {
         acceptValue(val) {
             const parsed = this._parseValue(val);
@@ -6836,7 +7121,7 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
             return value;
         }
         get inputFields() {
-            return [this._tint, this._alpha];
+            return [this._tint, this._alpha].filter(e => !pacemCore.Utils.isNull(e));
         }
     };
     __decorate$m([
@@ -6869,21 +7154,27 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** {@link PacemTextualInputElement} for an `<input type="email">`, whose read-only view renders as a `mailto:` link. */
     let PacemEmailInputElement = class PacemEmailInputElement extends PacemTextualInputElement {
         toggleReadonlyView(readonly) {
-            this.input.hidden = readonly;
-            this.anchor.hidden = !readonly;
+            const input = this._input, anchor = this._anchor;
+            if (!pacemCore.Utils.isNull(input))
+                input.hidden = readonly;
+            if (!pacemCore.Utils.isNull(anchor))
+                anchor.hidden = !readonly;
         }
         get inputFields() {
-            return [this.input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
     };
     __decorate$l([
         pacemCore.ViewChild('input[type=email]')
-    ], PacemEmailInputElement.prototype, "input", void 0);
+    ], PacemEmailInputElement.prototype, "_input", void 0);
     __decorate$l([
         pacemCore.ViewChild(pacemCore.P + '-a')
-    ], PacemEmailInputElement.prototype, "anchor", void 0);
+    ], PacemEmailInputElement.prototype, "_anchor", void 0);
     PacemEmailInputElement = __decorate$l([
         pacemCore.CustomElement({
             tagName: pacemCore.P + '-input-email',
@@ -6897,18 +7188,22 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
+    /** Name of the {@link FileUploadEvent} dispatched by {@link PacemUploadElement} while/after a chunked upload progresses. */
     const FileUploadEventName = 'fileupload';
+    /** Name of the {@link FileChangeEvent} dispatched by {@link PacemUploadElement} whenever the selected file(s)/directory change. */
     const FileChangeEventName = 'filechange';
     class StoragePickEvent extends pacemCore.CustomTypedEvent {
         constructor(file) {
             super('pick', file);
         }
     }
+    /** Dispatched by {@link PacemUploadElement} to report chunked-upload progress/completion. */
     class FileUploadEvent extends pacemCore.CustomTypedEvent {
         constructor(file) {
             super(FileUploadEventName, file);
         }
     }
+    /** Dispatched by {@link PacemUploadElement} whenever the user picks (or clears) file(s)/a directory. */
     class FileChangeEvent extends pacemCore.CustomTypedEvent {
         constructor(file) {
             super(FileChangeEventName, file);
@@ -6939,20 +7234,30 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         return stats;
     }
     /**
-     * PacemUploader Component
+     * PacemUploader Component: {@link PacemBaseElement}-based field to pick and (optionally chunk-)upload file(s)/a directory to {@link url},
+     * or defer to the File System Access API pickers depending on {@link selectMode}.
      */
     let PacemUploadElement = class PacemUploadElement extends PacemBaseElement {
         constructor(_tweener = new pacemCore.Animations.TweenService()) {
             super();
             this._tweener = _tweener;
+            /** Gets or sets the caption of the "undo" button, shown while an upload with {@link url} set is in progress. */
             this.undoCaption = 'undo';
+            /** Gets or sets the caption of the "retry" button, shown after a {@link failed} upload. */
             this.retryCaption = 'retry';
+            /** Gets or sets the caption of the "clear" button. */
             this.clearCaption = 'clear';
+            /** @readonly Gets whether an upload is currently in progress. */
             this.uploading = false;
+            /** @readonly Gets the total size (in bytes) of the file(s) currently being uploaded. */
             this.size = 0;
+            /** @readonly Gets the current upload progress, from 0 to 100. */
             this.percentage = .0;
+            /** @readonly Gets whether the current upload has completed. */
             this.complete = false;
+            /** @readonly Gets whether the current upload chunk request failed (enabling the retry button). */
             this.failed = false;
+            /** @readonly Gets whether the selected file failed {@link pattern}/{@link maxSize} validation. */
             this.invalidFile = false;
             this._fields = {
                 'parallelism': 3,
@@ -7012,11 +7317,14 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
             }
             return 'filter_none';
         }
+        /** @readonly Gets the raw blob currently being (or last) uploaded. */
         get blob() {
             return this._fields.blob;
         }
         get inputFields() {
-            return [this._fileupload];
+            return pacemCore.Utils.isNull(this._fileupload)
+                ? []
+                : [this._fileupload];
         }
         getViewValue(val) {
             const value = this._localValue || val;
@@ -7587,18 +7895,21 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** {@link PacemTextualInputElement} wrapping an `<input type="hidden">`, for values that must round-trip without a visible UI. */
     let PacemHiddenInputElement = class PacemHiddenInputElement extends PacemTextualInputElement {
         constructor() {
             super();
         }
         toggleReadonlyView(readonly) { }
         get inputFields() {
-            return [this.input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
     };
     __decorate$j([
         pacemCore.ViewChild('input[type=hidden]')
-    ], PacemHiddenInputElement.prototype, "input", void 0);
+    ], PacemHiddenInputElement.prototype, "_input", void 0);
     PacemHiddenInputElement = __decorate$j([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-input-hidden', template: '<input type="hidden" />', shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemHiddenInputElement);
@@ -7611,6 +7922,7 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
     };
     //namespace Pacem.Components.Scaffolding {
     const getUserMediaFunctions = pacemCore.Utils.getUserMediaFunctions();
+    /** The current stage of {@link PacemSnapshotElement}'s capture workflow: idle/upload-or-camera choice, live webcam preview, or reviewing the captured image before confirming. */
     var SnapshotStep;
     (function (SnapshotStep) {
         SnapshotStep["Start"] = "start";
@@ -7622,14 +7934,17 @@ css-class="{{ {'${pacemCore.PCSS}-fetching': ::_fetcher.fetching, '${pacemCore.P
             super('confirmsnapshot', { buffer });
         }
     }
+    /** A `<p-snapshot>` field: a {@link PacemBaseElement} image-capture control that lets the user upload a file or, when a webcam is available, take a live snapshot (with an optional 3s timer); its `value` is the resulting data-URL string. */
     let PacemSnapshotElement = class PacemSnapshotElement extends PacemBaseElement {
         constructor() {
             super(...arguments);
             this._resizeHandler = (evt) => {
                 this._renderValue();
             };
+            /** Gets or sets the current step of the capture workflow. Defaults to {@link SnapshotStep.Start}. */
             this.step = SnapshotStep.Start;
             /*const*/ this._canUseWebcam = getUserMediaFunctions.length > 0;
+            /** Seconds left before the timed shutter fires; `0` outside of a timed countdown. */
             this._countdown = 0;
             this._webcamInitialized = false;
             this._grabberChangeHandler = (e) => {
@@ -7933,18 +8248,26 @@ css-class="{{ {
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A single image entry (full-size and thumbnail sources) offered as a pick candidate by {@link PacemEditImageElement}. */
     class Picture {
     }
+    /** Name of the {@link ImageFetchRequestEvent} dispatched by {@link PacemEditImageElement}/{@link PacemImageInputElement} to request a page of pictures. */
     const ImageFetchRequestEventName = 'imagefetchrequest';
+    /** Dispatched to request a page of {@link Picture}s (e.g. on scroll, or when the search hint changes); handlers are expected to respond by setting `imageSet`. */
     class ImageFetchRequestEvent extends pacemCore.CustomTypedEvent {
         constructor(args) {
             super(ImageFetchRequestEventName, args, { bubbles: true /*, scoped: false */ });
         }
     }
+    /**
+     * Picture-picker panel: lets the user search/browse a fetched {@link imageSet}, upload a new full-size/thumbnail pair, or take a
+     * snapshot, resolving `value` to the chosen picture's source. Hosted inside a dialog by {@link PacemImageInputElement}.
+     */
     let PacemEditImageElement = class PacemEditImageElement extends pacemCore.Components.PacemElement {
         constructor() {
             super(...arguments);
             this._index = 0;
+            /** Gets or sets the search hint typed by the user, triggering a fresh {@link ImageFetchRequestEvent} when it changes. */
             this.hint = '';
         }
         _uploaderPropertyChangedCallback(evt) {
@@ -8115,6 +8438,10 @@ css-class="{{ {
     </${pacemCore.P}-panel>`
         })
     ], PacemEditImageElement);
+    /**
+     * {@link PacemBaseElement}-based field showing an image preview with edit/clear buttons; editing opens a dialog hosting a
+     * {@link PacemEditImageElement} to pick/upload/snapshot a new picture, while `value` also accepts a directly-typed URL.
+     */
     let PacemImageInputElement = class PacemImageInputElement extends PacemBaseElement {
         constructor() {
             super(...arguments);
@@ -8318,13 +8645,16 @@ css-class="{{ {
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** {@link PacemOrdinalInputElement} for an `<input type="number">`, formatting its read-only view value via {@link format}. */
     let PacemNumberInputElement = class PacemNumberInputElement extends PacemOrdinalInputElement {
         toggleReadonlyView(readonly) {
             this._span.hidden = !readonly;
             this._input.hidden = readonly;
         }
         get inputFields() {
-            return [this._input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
         getViewValue(val) {
             return this.value != null ? this._format(this.value) : undefined;
@@ -8374,6 +8704,7 @@ css-class="{{ {
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** {@link PacemTextualInputElement} for an `<input type="password">`, with a toggle to reveal/hide the entered text and a masked read-only view. */
     let PacemPasswordInputElement = class PacemPasswordInputElement extends PacemTextualInputElement {
         constructor() {
             super();
@@ -8385,7 +8716,9 @@ css-class="{{ {
             };
         }
         get inputFields() {
-            return [this._input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
         viewActivatedCallback() {
             super.viewActivatedCallback();
@@ -8401,6 +8734,7 @@ css-class="{{ {
                 this._toggler.removeEventListener('mousedown', this._togglerMousedownHandler, false);
             }
         }
+        /** Toggles the native input between `password` (masked) and `text` (revealed) type. */
         toggleVisibility() {
             const current = this._input.type;
             this._input.type = current === 'password' ? 'text' : 'password';
@@ -8442,12 +8776,15 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-input-search>` field: a {@link PacemTextualInputElement} backed by a native `<input type="search">`. */
     let PacemSearchInputElement = class PacemSearchInputElement extends PacemTextualInputElement {
         constructor() {
             super();
         }
         get inputFields() {
-            return [this.input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
         toggleReadonlyView(readonly) {
             // no readonly view provided.
@@ -8455,7 +8792,7 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
     };
     __decorate$e([
         pacemCore.ViewChild('input[type=search]')
-    ], PacemSearchInputElement.prototype, "input", void 0);
+    ], PacemSearchInputElement.prototype, "_input", void 0);
     PacemSearchInputElement = __decorate$e([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-input-search', template: '<input type="search" class="' + pacemCore.PCSS + '-input" />', shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemSearchInputElement);
@@ -8467,24 +8804,30 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-input-tel>` field: a {@link PacemTextualInputElement} backed by a native `<input type="tel">`, whose readonly view renders as a clickable `tel:` link. */
     let PacemTelInputElement = class PacemTelInputElement extends PacemTextualInputElement {
         constructor() {
             super();
         }
         toggleReadonlyView(readonly) {
-            this.input.hidden = readonly;
-            this.anchor.hidden = !readonly;
+            const input = this._input, anchor = this._anchor;
+            if (!pacemCore.Utils.isNull(input))
+                input.hidden = readonly;
+            if (!pacemCore.Utils.isNull(anchor))
+                anchor.hidden = !readonly;
         }
         get inputFields() {
-            return [this.input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
     };
     __decorate$d([
         pacemCore.ViewChild('input[type=tel]')
-    ], PacemTelInputElement.prototype, "input", void 0);
+    ], PacemTelInputElement.prototype, "_input", void 0);
     __decorate$d([
         pacemCore.ViewChild(pacemCore.P + '-a')
-    ], PacemTelInputElement.prototype, "anchor", void 0);
+    ], PacemTelInputElement.prototype, "_anchor", void 0);
     PacemTelInputElement = __decorate$d([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-input-tel', template: `<input type="tel" class="${pacemCore.PCSS}-input" /><${pacemCore.P}-a class="${pacemCore.PCSS}-readonly" disabled="{{ $pacem.isNullOrEmpty(:host.value) }}" href="{{ 'tel:'+ :host.value }}"><${pacemCore.P}-text text="{{ :host.viewValue }}"></${pacemCore.P}-text></${pacemCore.P}-a>`, shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemTelInputElement);
@@ -8496,6 +8839,7 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-input-text>` field: a {@link PacemTextualInputElement} backed by a native `<input type="text">`, with an optional character counter. */
     let PacemTextInputElement = class PacemTextInputElement extends PacemTextualInputElement {
         constructor() {
             super();
@@ -8505,7 +8849,9 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
             this._input.hidden = readonly;
         }
         get inputFields() {
-            return [this._input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
     };
     __decorate$c([
@@ -8529,24 +8875,30 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-input-url>` field: a {@link PacemTextualInputElement} backed by a native `<input type="url">`, whose readonly view renders as a clickable link opening in a new tab. */
     let PacemUrlInputElement = class PacemUrlInputElement extends PacemTextualInputElement {
         constructor() {
             super();
         }
         toggleReadonlyView(readonly) {
-            this.input.hidden = readonly;
-            this.anchor.hidden = !readonly;
+            const input = this._input, anchor = this._anchor;
+            if (!pacemCore.Utils.isNull(input))
+                input.hidden = readonly;
+            if (!pacemCore.Utils.isNull(anchor))
+                anchor.hidden = !readonly;
         }
         get inputFields() {
-            return [this.input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
     };
     __decorate$b([
         pacemCore.ViewChild('input[type=url]')
-    ], PacemUrlInputElement.prototype, "input", void 0);
+    ], PacemUrlInputElement.prototype, "_input", void 0);
     __decorate$b([
         pacemCore.ViewChild(pacemCore.P + '-a')
-    ], PacemUrlInputElement.prototype, "anchor", void 0);
+    ], PacemUrlInputElement.prototype, "_anchor", void 0);
     PacemUrlInputElement = __decorate$b([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-input-url', template: `<input type="url" class="${pacemCore.PCSS}-input" />${CHAR_COUNTER_CHILD}<${pacemCore.P}-a class="${pacemCore.PCSS}-readonly" disabled="{{ $pacem.isNullOrEmpty(:host.value) }}" href="{{ :host.value }}" target="_blank"><${pacemCore.P}-text text="{{ :host.viewValue }}"></${pacemCore.P}-text></${pacemCore.P}-a>`, shadow: pacemCore.Defaults.USE_SHADOW_ROOT })
     ], PacemUrlInputElement);
@@ -8558,11 +8910,14 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** Default tile-layer URL template used by {@link PacemLatLngElement} when {@link LatLngOptions.tiles} isn't set (currently empty, i.e. the map adapter's own default applies). */
     const DEFAULT_TILES = "";
+    /** Default map attribution string used by {@link PacemLatLngElement} when {@link LatLngOptions.attribution} isn't set (currently empty, i.e. the map adapter's own default applies). */
     const DEFAULT_ATTRIBUTION = "";
     //const TILES = `//api.mapbox.com/styles/v1/cmerighi/ciwz1gib7002l2prvgpi724nk/tiles/256/{z}/{x}/{y}?access_token=pk.eyJ1IjoiY21lcmlnaGkiLCJhIjoiY2lsZHIxdGJmMDAxOHc4bHowamxpZ2Z2OCJ9.7I7ndF-rAkx_1Sqi0bw3Ew`;
     //const ATTRIBUTION = `Map data &copy; <a href="http://openstreetmap.org">OpenStreetMap</a> contributors, <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>, Imagery © <a href="http://mapbox.com">Mapbox</a>`
     const REVERSE_GEOCODE_URL = 'https://nominatim.openstreetmap.org/reverse';
+    /** A `<p-latlng>` field: a {@link PacemBaseElement} coordinate picker combining paired lat/lng number inputs with an interactive, draggable-marker map (Leaflet/OSM, Azure Maps or Google Maps) and reverse-geocoded address preview. */
     let PacemLatLngElement = class PacemLatLngElement extends PacemBaseElement {
         convertValueAttributeToProperty(attr) {
             const regexArray = /^\s*([+-]?\d+\.?\d+)[,\s]\s*([+-]?\d+\.?\d+)\s*$/.exec(attr);
@@ -8740,10 +9095,12 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
     function pullEmpty() {
         return { name: '', value: '' };
     }
+    /** A `<p-namevalue-list>` field: a {@link PacemBaseElement} editor for a repeatable list of name/value string pairs, whose `value` is either an array of {@link NameValuePair}s or, when {@link PacemNameValueListElement#dictionary} is set, a plain `{ [name]: value }` object. */
     let PacemNameValueListElement = class PacemNameValueListElement extends PacemBaseElement {
         constructor() {
             super(...arguments);
             this.inputFields = [];
+            /** Internal editable rows, mirrored to/from `value` depending on {@link dictionary}. */
             this._bag = [];
         }
         toggleReadonlyView(readonly) {
@@ -8869,6 +9226,7 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-property-picker>` field: a {@link PacemBaseElement} wrapping a {@link PacemSelectElement} whose datasource is auto-populated with the (recursively flattened) watched property names of a `target` element. */
     let PacemPropertyPickerElement = class PacemPropertyPickerElement extends PacemBaseElement {
         get inputFields() {
             return [this._select];
@@ -8951,6 +9309,7 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-radio>` field: a {@link PacemBaseElement} wrapping a single native `<input type="radio">` with a caption label; its `value` is the radio's native value when {@link selected}, otherwise `undefined`. Used standalone or as the item template driven by {@link PacemRadioListElement}. */
     let PacemRadioElement = class PacemRadioElement extends PacemBaseElement {
         convertValueAttributeToProperty(attr) {
             return attr;
@@ -9028,6 +9387,7 @@ ${CHAR_COUNTER_CHILD}<span class="${pacemCore.PCSS}-readonly"><${pacemCore.P}-te
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-radio-list>` field: a {@link PacemDataSourceElement} rendering the datasource as a group of mutually-exclusive `<p-radio>` buttons. */
     let PacemRadioListElement = class PacemRadioListElement extends PacemDataSourceElement {
         acceptValue(val) {
             // no need to implement
@@ -9096,9 +9456,11 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-select>` field: a {@link PacemDataSourceElement} rendering the datasource as a native `<select>` dropdown. */
     let PacemSelectElement = class PacemSelectElement extends PacemDataSourceElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets whether an extra, empty/placeholder `<option>` is prepended to the rendered choices. Defaults to `true`. */
             this.emptyOption = true;
         }
         toggleReadonlyView(readonly) {
@@ -9108,7 +9470,9 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
         // no actual need to be idem-potent...
         // (take care in future)
         get inputFields() {
-            return [this._select];
+            return pacemCore.Utils.isNull(this._select)
+                ? []
+                : [this._select];
         }
         _manageDom(evt) {
             const args = evt.detail, item = args.item;
@@ -9221,6 +9585,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     };
     //namespace Pacem.Components.Scaffolding {
     // TODO: exploit 202x features like https://developer.mozilla.org/en-US/docs/Web/CSS/offset-path or https://developer.chrome.com/blog/anchor-positioning-api
+    /** A `<p-slider>` field: a {@link PacemBaseElement} numeric range control with a draggable thumb, keyboard support, and an optional tooltip-style thumb label; its `value` is a number between `min` and `max`. */
     let PacemSliderElement = class PacemSliderElement extends PacemBaseElement {
         constructor() {
             super(...arguments);
@@ -9508,6 +9873,7 @@ on-${pacemCore.PropertyChangeEventName}=":host._selectionChanged($event, ^index,
     }
     const BALLOON_POPUP_DELAY = 100;
     const BALLOON_POPOUT_DELAY = 0;
+    /** A `<p-suggest>` field: a {@link PacemDataSourceElement} autocomplete/typeahead text input, backed by a native `<input type="text">` and a dropdown balloon of filtered, highlighted suggestions; optionally accepts free-typed values not present in the datasource. */
     let PacemSuggestElement = class PacemSuggestElement extends PacemDataSourceElement {
         constructor() {
             super(...arguments);
@@ -10053,6 +10419,7 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
             super('tagadd', { value: value });
         }
     }
+    /** A single `<p-tag>` chip: displays a label and a remove button, dispatching a `remove` event (after an out-transition) when dismissed. Rendered by {@link PacemTagsElement} for each item in its `value`. */
     let PacemTagElement = class PacemTagElement extends pacemCore.Components.PacemElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -10091,6 +10458,7 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
                 <${pacemCore.P}-button on-click=":host._remove()"></${pacemCore.P}-button>`
         })
     ], PacemTagElement);
+    /** A `<p-tags>` field: a {@link PacemDataSourceElement} editor rendering `value` as a list of removable {@link PacemTagElement} chips, plus a {@link PacemSuggestElement} for picking (or, when {@link allowNew} is set, typing) new tags to add. */
     let PacemTagsElement = class PacemTagsElement extends PacemDataSourceElement {
         constructor() {
             super(true);
@@ -10214,10 +10582,13 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-textarea>` field: a {@link PacemTextualInputElement} backed by a native `<textarea>`, with an optional character counter. */
     let PacemTextAreaElement = class PacemTextAreaElement extends PacemTextualInputElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the native `<textarea>`'s `rows` attribute. Defaults to `5`. */
             this.rows = 5;
+            /** Gets or sets the native `<textarea>`'s `cols` attribute. Defaults to `50`. */
             this.cols = 50;
         }
         /** @override */
@@ -10225,11 +10596,16 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
             return true;
         }
         toggleReadonlyView(readonly) {
-            this._span.hidden = !readonly;
-            this._input.hidden = readonly;
+            const input = this._input, span = this._span;
+            if (!pacemCore.Utils.isNull(input))
+                input.hidden = readonly;
+            if (!pacemCore.Utils.isNull(span))
+                span.hidden = !readonly;
         }
         get inputFields() {
-            return [this._input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -10262,15 +10638,18 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Scaffolding {
+    /** A `<p-textarea-markdown>` field: a {@link PacemTextualInputElement} backed by a native `<textarea>` for editing Markdown text, whose readonly view renders the value as HTML via {@link Components.UI.MarkdownService}. */
     let PacemMarkdownTextAreaElement = class PacemMarkdownTextAreaElement extends PacemTextualInputElement {
         constructor(_md = new pacemUi.Components.UI.MarkdownService()) {
             super();
             this._md = _md;
+            /** Gets or sets the native `<textarea>`'s `rows` attribute. Defaults to `5`. */
             this.rows = 5;
+            /** Gets or sets the native `<textarea>`'s `cols` attribute. Defaults to `50`. */
             this.cols = 50;
             this._keydownHandler = (evt) => {
                 if (evt.keyCode === 9 /* tab */) {
-                    const input = this.input, value = input.value;
+                    const input = this._input, value = input.value;
                     var ndx = input.selectionStart;
                     input.value = value.substr(0, ndx) + '    ' + value.substr(ndx);
                     pacemCore.preventDefaultHandler(evt);
@@ -10278,14 +10657,17 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
             };
         }
         toggleReadonlyView(readonly) {
-            this.input.hidden = readonly;
+            if (!pacemCore.Utils.isNull(this._input))
+                this._input.hidden = readonly;
         }
         /** @override */
         get preventKeyboardSubmit() {
             return true;
         }
         get inputFields() {
-            return [this.input];
+            return pacemCore.Utils.isNull(this._input)
+                ? []
+                : [this._input];
         }
         getViewValue(val) {
             return this._md.toHtml(val);
@@ -10302,11 +10684,11 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
         }
         viewActivatedCallback() {
             super.viewActivatedCallback();
-            this.input.addEventListener("keydown", this._keydownHandler, false);
+            this._input.addEventListener("keydown", this._keydownHandler, false);
         }
         disconnectedCallback() {
-            this.input &&
-                this.input.removeEventListener("keydown", this._keydownHandler, false);
+            this._input &&
+                this._input.removeEventListener("keydown", this._keydownHandler, false);
             super.disconnectedCallback();
         }
     };
@@ -10318,7 +10700,7 @@ class="button-flat icon-rotate ${pacemCore.PCSS}-anim anim-pop anim-sudden anim-
     ], PacemMarkdownTextAreaElement.prototype, "cols", void 0);
     __decorate([
         pacemCore.ViewChild('textarea')
-    ], PacemMarkdownTextAreaElement.prototype, "input", void 0);
+    ], PacemMarkdownTextAreaElement.prototype, "_input", void 0);
     __decorate([
         pacemCore.ViewChild(`div.${pacemCore.PCSS}-readonly`)
     ], PacemMarkdownTextAreaElement.prototype, "_markdown", void 0);