@pacem/pacem 1.0.0-bessel → 1.0.0-binet

package/dist/browser/pacem-numerical.min.js

@@ -1,5 +1,5 @@
 /*!
- * @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
  */

package/dist/browser/pacem-plus.js

@@ -1,5 +1,5 @@
 /*!
- * @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
  */
@@ -12,15 +12,24 @@
         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;
     };
+    /**
+     * Base class shared by {@link PacemDataCellElement} and {@link PacemHeadCellElement}: both are bound to the
+     * same `metadata`/`state`/`gridState` triple describing their column, both position themselves within the
+     * grid's CSS-grid layout according to `gridState.orderedColumns`, and both toggle their own visibility from
+     * `state.hidden`. Concrete subclasses only need to implement {@link updateLayout} to (re)build their own
+     * content whenever `metadata` changes.
+     */
     class PacemBaseCellElement extends pacemCore.Components.PacemSafeContentElement {
         viewActivatedCallback() {
             super.viewActivatedCallback();
             this.updateColumnPosition();
             this.updateLayout(this.metadata);
         }
+        /** Positions this cell within the grid's CSS-grid layout according to `gridState.orderedColumns`. */
         updateColumnPosition(metadata = this.metadata, state = this.gridState) {
             this.style.gridColumn = (state.orderedColumns.indexOf(metadata.prop) + 1).toString();
         }
+        /** Shows/hides this cell according to `state.hidden`. */
         updateVisibility(state = this.state) {
             this.hide = !!state.hidden;
         }
@@ -68,6 +77,7 @@
             return null;
         }
     };
+    /** Namespaced helpers for working with {@link PacemDataGridElement} column metadata, e.g. localization. */
     class DataGrids {
         /**
          * Localizes the metadata of a data grid **in place** using a translation dictionary.
@@ -117,10 +127,16 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     const UI$5 = pacemUi.Components.UI;
-    /** @deprecated*/
+    /**
+     * @deprecated Superseded by composing a `${P}-repeater`/`${P}-slideshow` pair directly (see the template this
+     * element generates below for reference). Renders a `datasource` of {@link CarouselDataItem}s as a full-bleed,
+     * auto-advancing slideshow with a per-slide image, title and caption, applying 'previous'/'next'/'focus' CSS
+     * classes to neighbouring slides so they can be animated in/out as the current slide changes.
+     */
     let PacemCarouselElement = class PacemCarouselElement extends UI$5.PacemAdaptedIterativeElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the interval (in milliseconds) between automatic slide transitions. Default: `4000`. */
             this.interval = 4000;
         }
     };
@@ -171,6 +187,13 @@
     };
     const UI$4 = pacemUi.Components.UI;
     //namespace Pacem.Components.Plus {
+    /**
+     * Base class for the items registered within a {@link PacemContextMenuElement}: either a command button
+     * ({@link PacemContextMenuItemCommandElement}) or a separator ({@link PacemContextMenuItemSeparatorElement}).
+     * Subclasses only need to implement {@link createMenuItemElement} to produce the actual DOM element rendered
+     * inside the menu's balloon; this base class takes care of the `pacem-context-menuitem` CSS class and of
+     * notifying the owning {@link PacemContextMenuElement} (via `refresh()`) whenever one of its properties changes.
+     */
     class PacemContextMenuItemElement extends pacemCore.Components.PacemItemElement {
         connectedCallback() {
             super.connectedCallback();
@@ -184,6 +207,7 @@
             }
         }
     }
+    /** A {@link PacemContextMenuElement} item rendered as a clickable command button ({@link UI.PacemButtonElement}). */
     let PacemContextMenuItemCommandElement = class PacemContextMenuItemCommandElement extends PacemContextMenuItemElement {
         createMenuItemElement() {
             const retval = new UI$4.PacemButtonElement();
@@ -226,6 +250,7 @@
     PacemContextMenuItemCommandElement = __decorate$9([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-context-menuitem-command' })
     ], PacemContextMenuItemCommandElement);
+    /** A {@link PacemContextMenuElement} item rendered as a non-interactive `<hr>` separator between commands. */
     let PacemContextMenuItemSeparatorElement = class PacemContextMenuItemSeparatorElement extends PacemContextMenuItemElement {
         createMenuItemElement() {
             const retval = document.createElement('hr');
@@ -237,6 +262,13 @@
         pacemCore.CustomElement({ tagName: pacemCore.P + '-context-menuitem-separator' })
     ], PacemContextMenuItemSeparatorElement);
     // <${P}-button class="button-flat ${PCSS}-margin margin-0"><${P}-icon icon="{{ :host.icon || 'more_horiz' }}"></${P}-icon></${P}-button>
+    /**
+     * A button that pops out a floating balloon menu built from its {@link PacemContextMenuItemElement} children
+     * (commands and separators). If a `slot="button"` element is provided by the consumer it's used as the trigger;
+     * otherwise a default icon button is generated. Menu items are rendered lazily into a {@link UI.PacemBalloonElement}
+     * appended to the nearest shell, and kept in sync with the registered items whenever they (or their attributes)
+     * change - see `refresh`.
+     */
     let PacemContextMenuElement = class PacemContextMenuElement extends pacemCore.Components.PacemItemsContainerElement {
         constructor() {
             super(...arguments);
@@ -255,6 +287,7 @@
                 }
             };
         }
+        /** Only accepts {@link PacemContextMenuItemElement} instances (commands or separators) as registrable items. */
         validate(item) {
             return item instanceof PacemContextMenuItemElement;
         }
@@ -309,6 +342,7 @@
             shell.appendChild(balloon);
             return this.#balloon = balloon;
         }
+        /** Registers a menu item, wiring its attribute-change notifications and rebuilding the rendered menu. */
         register(item) {
             const retval = super.register(item);
             if (retval) {
@@ -317,6 +351,7 @@
             }
             return retval;
         }
+        /** Unregisters a menu item and rebuilds the rendered menu. */
         unregister(item) {
             const retval = super.unregister(item);
             if (retval) {
@@ -374,6 +409,7 @@
             this._disposeBalloon();
             super.disconnectedCallback();
         }
+        /** Forces the balloon's menu items to be rebuilt from the currently registered items. */
         refresh() {
             this._refreshMenuItems();
         }
@@ -459,13 +495,25 @@
     const UI$3 = pacemUi.Components.UI;
     const Scaffolding = pacemScaffolding.Components.Scaffolding;
     //namespace Pacem.Components.Plus {
+    /** The kind of inline content a {@link PacemEditElement} edits, and the editor UI it swaps in accordingly. */
     var EditMode;
     (function (EditMode) {
+        /** Plain text, edited via a `${P}-textarea`. */
         EditMode["Text"] = "text";
+        /** Rich HTML, edited via a `${P}-contenteditable`. */
         EditMode["Html"] = "html";
+        /** An image URL, edited via a `${P}-edit-image` (with optional upload/snapshot support). */
         EditMode["Image"] = "image";
+        /** Markdown source, edited via a `${P}-textarea` and rendered back through the markdown service. */
         EditMode["Markdown"] = "markdown";
     })(EditMode || (EditMode = {}));
+    /**
+     * Makes an arbitrary piece of content (`target`, or this element's first child when unset) inline-editable:
+     * overlays an edit button that, on click, opens a modal `${P}-dialog` hosting the editor matching `type`
+     * (text, HTML, markdown or image - see {@link EditMode}), and writes the result back into the target element
+     * once confirmed. The dialog and its editors (textarea/contenteditable/edit-image) are created once, lazily,
+     * on connect, and shown/hidden according to `type` rather than being recreated on every edit.
+     */
     let PacemEditElement = class PacemEditElement extends pacemCore.Components.PacemElement {
         constructor(_markdown = new UI$3.MarkdownService()) {
             super();
@@ -725,6 +773,11 @@
                     break;
             }
         }
+        /**
+         * Opens the modal editor over `target`'s current content. On 'Ok' the edited value is written back into
+         * `target` and a `commit` event is dispatched with `{ value }`; on 'Cancel' the target's original content
+         * is restored.
+         */
         edit(evt) {
             pacemCore.avoidHandler(evt);
             var cnt = this._target;
@@ -791,6 +844,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     const UI$2 = pacemUi.Components.UI;
+    /** Builds the markup for a single `${P}-slide`, embedding `captionTemplate`'s markup and reading the image from `imageProperty`. */
     function getGallerySlideShowTemplate(captionTemplate = getDefaultCaptionTemplate(), imageProperty = 'image') {
         return `<${pacemCore.P}-slide class="${pacemCore.PCSS}-gallery-item"
 css-class="{{ { '${pacemCore.PCSS}-gallery-previous': :host.isPrevious(^index, ::_slideshow.index), '${pacemCore.PCSS}-gallery-next': :host.isNext(^index, ::_slideshow.index), '${pacemCore.PCSS}-gallery-focus': ^index === ::_slideshow.index } }}"
@@ -802,11 +856,19 @@ ${captionTemplate}
 
             </${pacemCore.P}-slide>`;
     }
+    /** Default caption markup: a simple panel bound to `captionProperty`, hidden when the value is empty. */
     function getDefaultCaptionTemplate(captionProperty = 'caption') {
         return `<${pacemCore.P}-panel hide="{{ $pacem.isNullOrEmpty(^item.${captionProperty}) }}" class="${pacemCore.PCSS}-gallery-caption gallery-caption-default">
         <${pacemCore.P}-span class="paragraph" text="{{ ^item.${captionProperty} }}"></${pacemCore.P}-span>
     </${pacemCore.P}-panel>`;
     }
+    /**
+     * A lightbox photo gallery: renders `datasource` (a list of {@link GalleryDataItem}, or any shape when a custom
+     * `captionTemplate`/`imageProperty`/`captionProperty` is supplied) as a `${P}-lightbox`-hosted `${P}-slideshow`,
+     * opened via {@link open} with an optional 'hero' image-morph transition animating from the triggering thumbnail
+     * into the lightbox. The per-slide markup (image + caption) is generated dynamically from `captionTemplate`
+     * (or a default caption panel) so consumers can customize the caption's content without overriding the whole slide.
+     */
     let PacemGalleryElement = class PacemGalleryElement extends UI$2.PacemAdaptedIterativeElement {
         constructor() {
             super(...arguments);
@@ -880,6 +942,7 @@ ${captionTemplate}
                 rep.datasource = this.datasource;
             }
         }
+        /** @readonly Gets the `${P}-adapter` driving the gallery's slideshow. */
         get adapter() {
             return this._adapter;
         }
@@ -911,6 +974,13 @@ ${captionTemplate}
                 pImg.remove();
             }
         }
+        /**
+         * Opens the lightbox at `startIndex`, animating a morph from `heroFrom` (typically the thumbnail that
+         * triggered the gallery) into the lightbox's hero placeholder, when provided.
+         * @param startIndex Index of the slide to open the gallery on.
+         * @param heroFrom Optional element to morph the opening transition from.
+         * @param src Optional image URL to use for the morph, when different from `heroFrom`'s own `src`.
+         */
         open(startIndex, heroFrom, src) {
             this._poppingUp = true;
             this._lightbox.show = true;
@@ -977,13 +1047,23 @@ ${captionTemplate}
     const UI$1 = pacemUi.Components.UI;
     //namespace Pacem.Components.Plus {
     // TODO: use onewaytosource as a binding mode
+    /**
+     * A modal, `${P}-lightbox`-hosted CRUD form: wraps an autogenerated `${P}-form` bound to `state`/`metadata`,
+     * relays its submit/success/fail events, and turns 'Ok' into a `${P}-fetch` request (`method`) to `action`
+     * before committing the dialog - or, when `action` is empty, commits immediately without any network call.
+     * Extends {@link UI.PacemDialogBase}, so it's opened the same way (`open(state)`) and resolves the same
+     * `{ button, state }` result once committed.
+     */
     let PacemModalFormElement = PacemModalFormElement_1 = class PacemModalFormElement extends UI$1.PacemDialogBase {
+        /** @readonly Gets the underlying `${P}-form` element. */
         get form() {
             return this._form;
         }
         constructor() {
             super();
+            /** Gets or sets whether the 'Ok' button stays disabled until the form is both valid and dirty. Default: `true`. */
             this.suddenValidation = true;
+            /** Gets or sets the HTTP method used to submit the form to `action`. Default: `Net.HttpMethod.Post`. */
             this.method = pacemCore.Net.HttpMethod.Post;
             this._keyupHandler = (evt) => {
                 if (evt.keyCode === /* Enter */ 13
@@ -1059,6 +1139,7 @@ ${captionTemplate}
             }
             return retval;
         }
+        /** Commits the dialog, then - unless `keepStateOnCommit` was requested on `open` - resets `state` to `{}` once the closing animation ends. */
         commit(btn, evt) {
             super.commit(btn, evt);
             if (!this.#keepStateOnCommit) {
@@ -1166,11 +1247,23 @@ ${captionTemplate}
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Plus {
+    /**
+     * Two-way syncs a plain `state` object with the URL hash's query-string (`#...`) through a
+     * {@link Components.PacemRouterElement}: reading the hash into `state` on navigation, and pushing `state`
+     * back into the hash (merged with `default`, minus anything already matching `default`) whenever `state`
+     * changes. Values are normalized to strings for the URL (see `normalizedState`) and denormalized back to
+     * their original type using `default` as a type mold, so booleans/numbers/dates/regexes round-trip correctly.
+     * Navigation events lock the element (`#locked`) to avoid feedback loops between the router-driven read and
+     * the state-driven write while a navigation is in flight.
+     */
     let PacemRouterHashStateElement = class PacemRouterHashStateElement extends pacemCore.PacemEventTarget {
         constructor() {
             super(...arguments);
+            /** Gets or sets the default/mold values: used both to fill in missing `state` entries and to infer each value's original type when denormalizing from the URL. */
             this.default = {};
+            /** Gets or sets the current state, kept in sync with the URL hash's query-string. */
             this.state = {};
+            /** @readonly Gets the string-normalized projection of `state` actually written to the URL hash. */
             this.normalizedState = {};
             this._routerNavigatingHandler = (_) => {
                 this.#locked = true;
@@ -1425,8 +1518,8 @@ ${captionTemplate}
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     /**
-     * Bridges a {@link Components.PacemRouterElement}'s persisted scroll position (`state.$scrollY`, populated
-     * when `PacemRouterElement.scrollRestoration` is enabled) with a {@link ComponentsUI.UI.PacemViewElement}'s
+     * Bridges a {@link Pacem.Components.PacemRouterElement}'s persisted scroll position (`state.$scrollY`, populated
+     * when `PacemRouterElement.scrollRestoration` is enabled) with a {@link Pacem.Components.UI.PacemViewElement}'s
      * content lifecycle: navigating to a new page starts at the top, navigating back restores where the user
      * left off - without either the router or the view needing to know about the other.
      *
@@ -1538,9 +1631,15 @@ ${captionTemplate}
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Plus {
+    /**
+     * A simple search box: a `${P}-input-search`'s `hint` text feeds a debounced `${P}-fetch` against `url` as
+     * the `hintParameter` query-string parameter, and the results are rendered through a `${P}-repeater`
+     * (customize the row markup via the element's default `${P}-content` slot).
+     */
     let PacemSearchElement = class PacemSearchElement extends pacemCore.Components.PacemElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the name of the query-string parameter `hint` is sent as. Default: `'q'`. */
             this.hintParameter = 'q';
         }
         propertyChangedCallback(name, old, val, first) {
@@ -1588,7 +1687,13 @@ ${captionTemplate}
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Plus {
+    /** Name of the {@link DataRowSelectChangeEvent}. */
     const DataRowSelectChangeEventName = "datarowselectchange";
+    /**
+     * Dispatched by a {@link PacemDataGridElement} whenever its row selection is about to change (e.g. a row was
+     * clicked while in 'row' select mode). Cancelable: a listener can call `preventDefault()` and instead assign
+     * its own `detail.selectedRows` to override which rows actually end up selected.
+     */
     class DataRowSelectChangeEvent extends CustomEvent {
         constructor(detail) {
             super(DataRowSelectChangeEventName, { detail, bubbles: false, cancelable: true });
@@ -1596,6 +1701,13 @@ ${captionTemplate}
     }
     const EMPTY_CSS = {};
     const EMPTY_CSSCLASS = [];
+    /**
+     * The `<td>`-like cell of a {@link PacemDataGridElement}'s body: renders `dataitem`'s `metadata.prop` value
+     * according to `metadata.dataType`/`metadata.dataCell.format` (numbers, currency, percentages, dates,
+     * booleans, ...), or through a custom `metadata.dataCell.format` function when one is supplied. Also derives
+     * the cell's CSS class(es)/inline style from `metadata.dataCell`, and reflects the grid's row-selection state
+     * (`gridState.selectedRows`) via the `datarow-selected`/`datacell-filled`/`datacell-primary` CSS classes.
+     */
     let PacemDataCellElement = class PacemDataCellElement extends PacemBaseCellElement {
         updateLayout(metadata = this.metadata) {
             this._setup(metadata);
@@ -1799,18 +1911,38 @@ ${captionTemplate}
     };
     const UI = pacemUi.Components.UI;
     //namespace Pacem.Components.Plus {
+    /** Name of the {@link DataColumnSortEvent}. */
     const DataColumnSortEventName = "datacolumnsort";
+    /**
+     * Dispatched by a {@link PacemHeadCellElement} when its sort button is clicked, and re-dispatched by the
+     * owning {@link PacemDataGridElement} after it updates its internal sort state. Cancelable: a listener can
+     * call `preventDefault()` to veto the sort, or normalize/override `detail` (e.g. fetch a re-sorted datasource)
+     * before the grid applies it.
+     */
     class DataColumnSortEvent extends CustomEvent {
         constructor(detail) {
             super(DataColumnSortEventName, { detail, bubbles: false, cancelable: true });
         }
     }
+    /** Name of the {@link DataColumnRescaleEvent}. */
     const DataColumnRescaleEventName = "datacolumnrescale";
+    /**
+     * Dispatched by a {@link PacemHeadCellElement} while its rescale handle is being dragged, and re-dispatched
+     * by the owning {@link PacemDataGridElement} after it updates the column's pixel width. Cancelable: a
+     * listener can call `preventDefault()` and override `detail.width` to clamp/snap the resulting width.
+     */
     class DataColumnRescaleEvent extends CustomEvent {
         constructor(detail) {
             super(DataColumnRescaleEventName, { detail, bubbles: false, cancelable: true });
         }
     }
+    /**
+     * The `<th>`-like cell of a {@link PacemDataGridElement}'s header row: renders `metadata.headCell.name`
+     * (falling back to `metadata.prop`), and - depending on `metadata` flags - a sort button that dispatches
+     * {@link DataColumnSortEvent}, a rescale handle (backed by a `${P}-rescale` behavior appended to the shell)
+     * that dispatches {@link DataColumnRescaleEvent}, and a description tooltip balloon rendered as plain text,
+     * HTML or Markdown according to `metadata.headCell.tooltip`.
+     */
     let PacemHeadCellElement = class PacemHeadCellElement extends PacemBaseCellElement {
         constructor(_md = new UI.MarkdownService()) {
             super();
@@ -2035,16 +2167,33 @@ ${captionTemplate}
             deleteIcon: 'delete'
         }
     };
+    /**
+     * Dispatched by a {@link PacemDataGridElement} right after its `datasource` changes and before row selection
+     * is cleared; a listener can set `detail.keepRowSelection` to `true` to preserve the current selection instead
+     * of the default reset-on-rebind behavior.
+     */
     class DataGridBindEvent extends CustomEvent {
         constructor(detail) {
             super('databind', { cancelable: false, bubbles: false, detail });
         }
     }
+    /**
+     * Dispatched by a {@link PacemDataGridElement} for every UI event bubbling up from one of its data cells
+     * (see `Components.PacemElement.emittedEventTypes`), re-typed as `'datacell' + originalType` (e.g. a cell's
+     * `click` becomes `datacellclick`) and enriched with the originating cell/item/row-index. An un-prevented
+     * `click` while in `'row'` select mode additionally toggles that row's selection.
+     */
     class DataCellUIEvent extends pacemCore.CustomUIEvent {
         constructor(type, detail, orig) {
             super(type, detail, { bubbles: false, cancelable: true }, orig);
         }
     }
+    /**
+     * Declarative, `<${P}-datacolumn>`-authored description of a {@link PacemDataGridElement} column: field
+     * binding, label, sort/resize/toggle flags and per-column CSS. Registering, unregistering or changing one of
+     * these items causes the owning grid to recompute its adapted column metadata and rebuild its rendered
+     * columns/state accordingly.
+     */
     let PacemDataColumnElement = class PacemDataColumnElement extends pacemCore.Components.PacemItemElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -2105,31 +2254,55 @@ ${captionTemplate}
     PacemDataColumnElement = __decorate([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-datacolumn' })
     ], PacemDataColumnElement);
+    /** Builds the bindable `${P}-headcell` markup for a single column, wired to relay sort/rescale requests up to the grid. */
     function headColumnHtml(c) {
         return `<${pacemCore.P}-headcell metadata="{{ :host._getColumnMetadata('${c.prop}') }}" state="{{ :host._columnState.${c.prop} }}" grid-state="{{ :host._gridState }}"
 on-${DataColumnSortEventName}=":host._broadcastSortCommand($event)"
 on-${DataColumnRescaleEventName}=":host._broadcastRescaleCommand($event)"></${pacemCore.P}-headcell>`;
     }
+    /** Builds the bindable `${P}-datacell` markup for a single column/row, appending `extra` (typically the UI event relays) to the tag. */
     function dataColumnHtml(c, extra) {
         return `<${pacemCore.P}-datacell metadata="{{ :host._getColumnMetadata('${c.prop}') }}" state="{{ :host._columnState.${c.prop} }}" grid-state="{{ :host._gridState }}"
 dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacell>`;
     }
+    /**
+     * A CSS-grid-based data table driven by an array of {@link PacemDataColumnElement} children and/or a
+     * `metadata` array (columns declared as elements are merged on top of `metadata` by matching `field`/`prop`,
+     * see `_adaptColumnMetadata`). For each bound `datasource` row, one `${P}-datacell` is generated per column,
+     * matched by a `${P}-headcell` per column in the header row; columns can independently be sortable,
+     * rescalable and togglable, coordinated through `_gridState`/`_columnState` and the head cell's
+     * {@link DataColumnSortEvent}/{@link DataColumnRescaleEvent}.
+     *
+     * The grid's markup is fully re-generated (`innerHTML` on the internal grid container, see `_buildUpGrid`)
+     * whenever the adapted column metadata changes, so adding/removing/reordering `${P}-datacolumn` children -
+     * or changing `metadata` directly - keeps the grid's markup, `grid-template-columns` and per-cell bindings
+     * in sync. Row selection is centralized here (`setRowSelection`, `_gridState.selectedRows`) and exposed both
+     * as the public, mergeable `state` and as bubbling {@link DataRowSelectChangeEvent}s/{@link DataCellUIEvent}s
+     * relayed from the individual cells.
+     */
     let PacemDataGridElement = class PacemDataGridElement extends pacemCore.Components.PacemItemsContainerElement {
         constructor(_key = pacemCore.Utils.uniqueCode()) {
             super();
             this._key = _key;
+            /** Gets or sets the grid's public state (currently just row selection); merged into, and kept in sync with, the internal `_gridState`. */
             this.state = {};
             // TODO: allow to persist states (key) on the session or location level...
+            /** @readonly Per-column runtime state (visibility, rescaled width), keyed by `prop`; fed into each cell's `state`. */
             this._columnState = {};
+            /** @readonly The grid's internal, always-consistent state (sort, selection, column order); `state` is merged from/into this. */
             this._gridState = { sort: {}, orderedColumns: [], selectedRows: [] };
+            /** A registered column's display-affecting properties changed (field/label/css/sort/resize/toggle flags): re-adapt the column metadata so the grid rebuilds. */
             this._itemDataColumnRebuildHandler = (evt) => {
                 this._adaptColumnMetadata(this.items || []);
             };
+            /** A registered column's order/hide state changed: re-adapt the column metadata so the grid rebuilds. */
             this._itemDataColumnChangeHandler = (evt) => {
                 this._adaptColumnMetadata(this.items || []);
             };
+            /** Per-column-`prop` cache of {@link DataColumnMetadata} lookups (see `_getColumnMetadata`), invalidated whenever `_adaptedColumnMetadata` is recomputed. */
             this._memoizer = {};
         }
+        /** Only accepts {@link PacemDataColumnElement} instances as registrable items. */
         validate(item) {
             return item instanceof PacemDataColumnElement;
         }
@@ -2170,6 +2343,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
                 }
             }
         }
+        /** Registers a column item, wiring its rebuild/state-change notifications so the grid re-adapts its metadata whenever the column changes. */
         register(item) {
             if (super.register(item)) {
                 // add listeners
@@ -2179,6 +2353,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
             }
             return false;
         }
+        /** Unregisters a column item and removes its rebuild/state-change listeners. */
         unregister(item) {
             if (super.unregister(item)) {
                 // remove listeners
@@ -2196,6 +2371,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
             const indices = Array.from(args);
             this._setRowSelection(indices);
         }
+        /** Dispatches a cancelable {@link DataRowSelectChangeEvent} for `indices`, then applies `event.detail.selectedRows` (possibly overridden by a listener) as the new selection - unless the event was prevented. */
         _setRowSelection(indices) {
             const args = (indices || []).map(i => { return { item: this.datasource[i], index: i }; });
             const evt = new DataRowSelectChangeEvent({ selectedRows: args });
@@ -2208,6 +2384,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
                 this._doSetRowSelection(retval.map(i => (i?.index ?? -1)).filter(i => i >= 0));
             }
         }
+        /** Merges the given `selectedRows` indices into `_gridState`/`state`. */
         _doSetRowSelection(selectedRows) {
             const selection = { selectedRows };
             this._mergeState(selection);
@@ -2224,6 +2401,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
             // does not trigger propertychange event (does not have to).
             this.state = pacemCore.Utils.extend(this.state ?? {}, newState);
         }
+        /** Recomputes `_adaptedColumnMetadata` by projecting each {@link PacemDataColumnElement} item into a {@link DataColumnMetadata} and concatenating the plain `metadata` array after it. Debounced, since several column items/attributes typically change together. */
         _adaptColumnMetadata(items = this.items, metadata = this.metadata) {
             const output = Array.prototype.concat.apply((items || []).map(i => {
                 const retval = {
@@ -2247,9 +2425,15 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
             this._memoizer = {};
             this._adaptedColumnMetadata = output;
         }
+        /** Looks up (and memoizes) a column's {@link DataColumnMetadata} by `prop`; bound from each generated head/data cell's `metadata` attribute. */
         _getColumnMetadata(prop) {
             return this._memoizer[prop] = this._memoizer[prop] || this._adaptedColumnMetadata.find(m => m.prop === prop);
         }
+        /**
+         * (Re)generates the grid's entire markup - the CSS grid-template-columns, one `${P}-headcell` and one
+         * `${P}-datacell` per column (repeated per `datasource` row via a `${P}-repeater`), plus the optional
+         * multi-select gutter column - and assigns it as `innerHTML` of the internal grid container.
+         */
         _buildUpGrid(metadata) {
             const container = this._tableContainer;
             if (pacemCore.Utils.isNull(container)) {
@@ -2290,6 +2474,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
 </${pacemCore.P}-panel>`;
             container.innerHTML = html;
         }
+        /** Patches the static `grid-template-columns` track list with any per-column overrides from `_columnState` (`auto` when hidden, a pixel width when rescaled). Bound as the grid container's `css['grid-template-columns']`. */
         _getColumnSizes(state = this._columnState, css, grid = this._gridState) {
             if (pacemCore.Utils.isNullOrEmpty(state)) {
                 return css;
@@ -2307,6 +2492,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
             }
             return split.join(' ');
         }
+        /** Computes a column's initial CSS grid-template-columns track (`auto`, a flex `fr` unit, or a `minmax()`) from its `width`/`minPixelWidth`/`maxPixelWidth`. */
         _getColumnSize(c) {
             if (c.hide) {
                 return 'auto';
@@ -2328,6 +2514,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
         }
         //#endregion
         //#region events
+        /** Relays a bubbled `CommandEvent` (e.g. from an autogenerated row-command button) as the grid's own `itemcommand`/`item<cmd>` events. */
         _onCommand(evt) {
             // DO NOT stop bubbling! Might be 'handy' in autogenerated forms...
             // Pacem.stopPropagationHandler(evt);
@@ -2338,6 +2525,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
             // custom 'item<cmd>' event fires next
             this.dispatchEvent(new pacemCore.Components.CustomItemCommandEvent(/* 'originalEvent' */ evt));
         }
+        /** Relays a UI event bubbled from a data cell as a {@link DataCellUIEvent} (`'datacell' + type`) on the grid, and toggles the row's selection on an un-prevented `click` while in `'row'` select mode. */
         _broadcastUiEvent(item, index, evt) {
             const evtType = evt.type.toLowerCase(), type = 'datacell' + evtType;
             const args = { dataitem: item, rowindex: index, datacell: evt.srcElement }, uiEvt = (evt instanceof MouseEvent || evt instanceof TouchEvent || evt instanceof KeyboardEvent) ? new DataCellUIEvent(type, args, evt) : new DataCellUIEvent(type, args);
@@ -2354,6 +2542,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
                 }
             }
         }
+        /** Relays a head cell's {@link DataColumnSortEvent} up as the grid's own event, then - unless prevented - normalizes and applies the resulting sort into `_gridState.sort`. */
         _broadcastSortCommand(evt) {
             const sort = evt.detail;
             const event = new DataColumnSortEvent(sort);
@@ -2369,6 +2558,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
                 this._gridState = pacemCore.Utils.extend({}, this._gridState, /* let it be manipulated on the "other side" */ { sort: sort2 });
             }
         }
+        /** Relays a head cell's {@link DataColumnRescaleEvent} up as the grid's own event, then - unless prevented - stores the resulting pixel width into that column's `_columnState`. */
         _broadcastRescaleCommand(evt) {
             const rescale = evt.detail;
             const event = new DataColumnRescaleEvent(rescale);
@@ -2384,6 +2574,7 @@ dataitem="{{ ^item }}" rowindex="{{ ^index }}" ${extra}></${pacemCore.P}-datacel
                 this._columnState = pacemCore.Utils.extend({}, this._columnState, newState);
             }
         }
+        /** Toggles `toggledRowIndex` in/out of the current row selection, honoring `options.allowMultiSelect`/`allowSelect` (logging a warning and doing nothing if selection isn't allowed at all), then applies it via `_setRowSelection`. */
         _broadcastSelectCommand(toggledRowIndex) {
             let actualRows = (this._gridState.selectedRows || []).slice(0);
             const ndx = actualRows.indexOf(toggledRowIndex);