@pacem/pacem-cms 1.0.0-bessel → 1.0.0-dirac

package/dist/browser/pacem-cms.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-cms v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-cms v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -33,7 +33,14 @@
             }
         }
     };
-    /** Default metadata ('expression' field) 'type' factory. */
+    /**
+     * Default metadata ('expression' field) 'type' factory: renders a `${P}-expression` field bound to the
+     * given entity's `prop` attribute (or, for plain objects, the property itself), relaying value changes back
+     * through {@link Functions.handleExpressionValueChange} and honoring the field's `extra.selector`/`filter`/`labeler`.
+     * @param host The form field element requesting the markup.
+     * @param hostRef Binding-expression reference to `host` (defaults to `:host`).
+     * @param hostEntityRef Binding-expression reference to `host.entity` (defaults to `:host.entity`).
+     */
     const EXPRESSION_METADATA_TYPE = (host, hostRef = ':host', hostEntityRef = ':host.entity') => {
         const attrs = {}, meta = host.metadata, fns = Functions, fnKeys = [];
         attrs['value'] = `{{ ${hostEntityRef} instanceof HTMLElement && ${hostEntityRef}.getAttribute('${pacemCore.CustomElementUtils.camelToKebab(meta.prop)}') }}`;
@@ -82,6 +89,11 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Cms {
+    /**
+     * Base class for form fields that let the user pick an `Element` from the current document, filtered by
+     * `selector`/`filter` and displayed through `labeler`. See {@link PacemElementPickerElement} for the concrete
+     * `${P}-select`-backed implementation.
+     */
     class PacemElementPickerElementBase extends pacemScaffolding.Components.Scaffolding.PacemBaseElement {
     }
     __decorate$e([
@@ -93,6 +105,7 @@
     __decorate$e([
         pacemCore.Watch({ converter: pacemCore.PropertyConverters.Eval })
     ], PacemElementPickerElementBase.prototype, "labeler", void 0);
+    /** Form field for picking an `Element` (identified by its `id`) among those matching `selector`/`filter`, listed in a `${P}-select`. */
     let PacemElementPickerElement = class PacemElementPickerElement extends PacemElementPickerElementBase {
         get inputFields() {
             return [this._select];
@@ -169,12 +182,18 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Cms {
+    /** The kind of value a {@link PacemExpressionElement} is currently editing, as picked in its source selector. */
     var ExpressionSource;
     (function (ExpressionSource) {
         ExpressionSource["Constant"] = "const";
         ExpressionSource["PropertyReference"] = "property";
         ExpressionSource["Expression"] = "expr";
     })(ExpressionSource || (ExpressionSource = {}));
+    /**
+     * Form field for building a Pacem binding-expression string, either as a plain constant, a picked
+     * element/property reference (via {@link PacemElementPickerElementBase}), or a free-hand expression typed
+     * into an inner `${P}-textarea`; a live preview of the evaluated `value` is shown alongside the field.
+     */
     let PacemExpressionElement = class PacemExpressionElement extends PacemElementPickerElementBase {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -401,6 +420,12 @@
         const css = p.display.cssClass = pacemCore.Utils.isArray(p.display.cssClass) && p.display.cssClass || [];
         css.push(pacemCore.PCSS + '-cell');
     }
+    /**
+     * Adds the `${PCSS}-cell`/grid CSS classes to `metadata`'s display and to each of its properties' display,
+     * so that a generated form lays its fields out as grid cells (used for the datacolumns/fetch-parameters
+     * sub-grids editors, as opposed to {@link buildWidgetMetadata} which is used for a widget's own root metadata).
+     * @param metadata The metadata to adapt; defaults to an empty `{ props: [] }`-like metadata when omitted.
+     */
     function gridifyMetadata(metadata) {
         var props = metadata && metadata.props || [];
         var display = metadata && metadata.display || { name: 'Element' };
@@ -411,6 +436,11 @@
         props.forEach(cellifyMetadata);
         return { display: display, props: props };
     }
+    /**
+     * Merges `metadata` on top of {@link DEFAULT_METADATA} (the common `tag` property/display), cellifying every
+     * resulting property's display (see `cellifyMetadata`); used by widget constructors to build their `metadata`.
+     * @param metadata Widget-specific metadata to merge on top of the defaults.
+     */
     function buildWidgetMetadata(metadata) {
         var display = pacemCore.Utils.extend({}, DEFAULT_METADATA.display, metadata && metadata.display || {});
         var props = pacemCore.Utils.clone(DEFAULT_METADATA.props);
@@ -434,6 +464,7 @@
             return (e.metadata && e.metadata.display && e.metadata.display.name || '') + '#' + e.id;
         }
     };
+    /** Static lookup helper for {@link PacemWidgetElement} instances in the current document. */
     class Widget {
         /**
          * Utility method for widget gathering.
@@ -443,6 +474,7 @@
             return pacemCore.CustomElementUtils.findAll('.' + WIDGET_CSS_CLASS, (widget) => widget instanceof PacemWidgetElement && !pacemCore.Utils.isNullOrEmpty(widget.id) && (pacemCore.Utils.isNull(predicate) || predicate(widget)));
         }
     }
+    /** Floating toolbar (edit/permissions/remove buttons), shown by a {@link PacemWidgetElement}'s balloon while `editing`, that opens the widget's core/permissions edit forms. */
     let PacemWidgetToolbarElement = class PacemWidgetToolbarElement extends pacemCore.Components.PacemElement {
         /** Gets the toolbar's edit button. */
         get editButton() {
@@ -512,9 +544,16 @@
 </${pacemCore.P}-shell-proxy>`
         })
     ], PacemWidgetToolbarElement);
+    /**
+     * Base class for CMS widgets: assigns each instance a stable `id`, exposes an `editing`/`editable` toggle
+     * backed by a hover-triggered {@link PacemWidgetToolbarElement} balloon (edit/permissions/remove actions),
+     * and carries the `metadata`/`permissionMetadata`/`permissions` used to scaffold its editing forms. See
+     * {@link PacemUiWidgetElement} and {@link PacemBearerWidgetElement} for further specialized bases.
+     */
     class PacemWidgetElement extends pacemCore.Components.PacemElement {
         constructor(metadata, role = 'widget') {
             super(role);
+            /** Gets or sets the scaffolding metadata describing the widget's permission-editing form. */
             this.permissionMetadata = DEFAULT_PERMISSION_METADATA;
             this.metadata = metadata;
         }
@@ -619,6 +658,7 @@
             }
         ]
     };
+    /** Non-visual helper widget exposing an arbitrary `model` object, typically referenced as a data source by other widgets/expressions. */
     let PacemWidgetDataElement = class PacemWidgetDataElement extends PacemWidgetElement {
         constructor() {
             super(buildWidgetMetadata(DATA_METADATA$1));
@@ -681,6 +721,7 @@
         ]
     };
     const PARAMETER_TAGNAME = pacemCore.P + '-widget-fetch-parameter';
+    /** A single, named fetch parameter nested under a {@link PacemWidgetFetchElement}; setting `value` re-triggers the owning fetcher's `fetch()`. */
     let PacemWidgetFetchParameterElement = class PacemWidgetFetchParameterElement extends pacemCore.PacemEventTarget {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val.first);
@@ -708,6 +749,11 @@
     PacemWidgetFetchParameterElement = __decorate$a([
         pacemCore.CustomElement({ tagName: PARAMETER_TAGNAME })
     ], PacemWidgetFetchParameterElement);
+    /**
+     * Non-visual helper widget that fetches data from a REST endpoint chosen from a {@link PacemWidgetApiManifestElement}
+     * `manifest`, using its nested {@link PacemWidgetFetchParameterElement} children (see `_parameters`) as request
+     * parameters; the response is exposed as `result`.
+     */
     let PacemWidgetFetchElement = class PacemWidgetFetchElement extends PacemBearerWidgetElement {
         constructor() {
             super(buildWidgetMetadata(FETCH_METADATA));
@@ -724,6 +770,7 @@
         get _parameters() {
             return Array.from(this._itemsElement.children).filter(e => e.localName === PARAMETER_TAGNAME);
         }
+        /** Triggers the request against `endpoint`/`url`, provided all of the endpoint's required parameters are attached and populated; otherwise does nothing. */
         fetch() {
             const fetcher = this._fetcher, parameters = this._parameters || [], endpoint = this.endpoint;
             if (!pacemCore.Utils.isNull(endpoint)) {
@@ -860,9 +907,15 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
         prop: 'accessToken', type: EXPRESSION_METADATA_TYPE, display: { name: 'Access Token' },
         extra: pacemCore.Utils.extend({}, EXPRESSION_WIDGET_METADATA_EXTRA, { filter: (e) => e instanceof PacemWidgetDataElement || e instanceof PacemWidgetFetchElement })
     };
+    /**
+     * Base class for widgets that authenticate their own fetch requests with a bearer `accessToken` (turned into
+     * an `Authorization: Bearer ...` header on `fetchHeaders`). See {@link PacemWidgetApiManifestElement} and
+     * {@link PacemWidgetFetchElement} for the concrete implementations.
+     */
     class PacemBearerWidgetElement extends PacemWidgetElement {
         constructor() {
             super(...arguments);
+            /** Gets or sets the `credentials` mode used for the widget's fetch requests. */
             this.fetchCredentials = 'same-origin';
         }
         propertyChangedCallback(name, old, val, first) {
@@ -897,6 +950,7 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Cms {
+    /** Non-visual helper widget, reserved for translation-related composition (no widget-specific behavior beyond {@link PacemWidgetElement}). */
     let PacemWidgetTranslatorElement = class PacemWidgetTranslatorElement extends PacemWidgetElement {
     };
     PacemWidgetTranslatorElement = __decorate$8([
@@ -927,9 +981,11 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
             }
         ]
     };
+    /** Non-visual helper widget exposing the current timestamp (`time`), refreshed every `interval` milliseconds by an internal `${P}-timer`. */
     let PacemWidgetClockElement = class PacemWidgetClockElement extends PacemWidgetElement {
         constructor() {
             super(buildWidgetMetadata(DATA_METADATA));
+            /** Gets or sets the tick interval, in milliseconds, at which `time` is refreshed. */
             this.interval = 0;
         }
     };
@@ -948,11 +1004,23 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
     /// <reference path="./swagger-types.d.ts" />
     //namespace Pacem.Cms.OpenApi {
     const BAG = 'pacem:metadatabag';
+    /**
+     * Loads an OpenApi manifest (via the underlying {@link Scaffolding.OpenApi.OpenApiParser}) and eagerly
+     * enriches every endpoint's request/response schemas into scaffolding-ready {@link Scaffolding.OpenApi.DataField}
+     * metadata (fetched from each schema's absolute-url definition key, recursively for nested `$ref`s), optionally
+     * caching the per-url metadata fetches through `cache`.
+     */
     class SwaggerCmsParser {
         constructor(_openApi = new pacemScaffolding.Scaffolding.OpenApi.OpenApiParser()) {
             this._openApi = _openApi;
             this._cachedMetadataUrls = [];
         }
+        /**
+         * Loads the OpenApi manifest at `url` and enriches every endpoint's request/response schemas with their
+         * fetched field metadata (see `_enrichSchemas`).
+         * @param url The OpenApi (swagger) json configuration's url.
+         * @param headers Optional HTTP headers for both the manifest and the per-schema metadata fetches.
+         */
         async load(url, headers) {
             let api = await this._openApi.load(url, headers);
             if (api != null) {
@@ -978,6 +1046,7 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
                 }
             }
         }
+        /** Removes from `cache` every metadata entry fetched by this parser so far. */
         clearCache() {
             const cache = this.cache, keys = this._cachedMetadataUrls;
             if (cache) {
@@ -1096,6 +1165,7 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
             ACCESS_TOKEN_METADATA
         ]
     };
+    /** Non-visual helper widget that parses an OpenApi document at `url` (via {@link SwaggerCmsParser}) into a `manifest`, typically referenced by a {@link PacemWidgetFetchElement}. */
     let PacemWidgetApiManifestElement = class PacemWidgetApiManifestElement extends PacemBearerWidgetElement {
         constructor(_openapi = new SwaggerCmsParser(), _cache = new pacemCore.Storage()) {
             super(buildWidgetMetadata(APIMANIFEST_METADATA));
@@ -1154,6 +1224,10 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Cms {
+    /**
+     * Base class for widgets that occupy a cell of a CSS grid-based layout (`column`/`row`/`colspan`/`rowspan`),
+     * self-registering into the nearest ancestor {@link PacemCompositeWidgetElement} container (see `findContainer`).
+     */
     class PacemUiWidgetElement extends PacemWidgetElement {
         constructor(metadata, colspan = 1, role) {
             super(metadata, role);
@@ -1234,20 +1308,25 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
     const WidgetRegisterEventName = "widgetregister";
     const WidgetUnregisterEventName = "widgetunregister";
     const LayoutChangeEventName = "layoutchange";
+    /** Dispatched by a {@link PacemCompositeWidgetElement} right after a child widget is successfully registered into it. */
     class WidgetRegisterEvent extends CustomEvent {
         constructor(item, eventInit) {
             super(WidgetRegisterEventName, pacemCore.Utils.extend(eventInit || {}, { detail: item }));
         }
     }
+    /** Dispatched by a {@link PacemCompositeWidgetElement} right after a child widget is unregistered from it. */
     class WidgetUnregisterEvent extends CustomEvent {
         constructor(item, eventInit) {
             super(WidgetUnregisterEventName, pacemCore.Utils.extend(eventInit || {}, { detail: item }));
         }
     }
+    /** Base class for widgets that act as a container ({@link CompositeWidget}) for other {@link PacemUiWidgetElement} widgets. See {@link PacemGridWidgetElement} and `PacemWidgetPickerElement` for concrete implementations. */
     class PacemCompositeWidgetElement extends PacemUiWidgetElement {
+        /** Gets the `Element` new items are appended to; defaults to this widget itself. */
         get itemsElement() {
             return this;
         }
+        /** Gets whether `item` is an acceptable child of this container; overridable by subclasses to narrow the accepted item type. */
         validate(item) {
             return item instanceof PacemUiWidgetElement;
         }
@@ -1319,6 +1398,7 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
                 prop: 'text', type: EXPRESSION_METADATA_TYPE, display: { name: 'Text' }, extra: EXPRESSION_WIDGET_METADATA_EXTRA
             }]
     });
+    /** UI widget rendering a plain (optionally expression-bound) piece of text via an inner `${P}-text`. */
     let PacemWidgetTextElement = class PacemWidgetTextElement extends PacemUiWidgetElement {
         constructor() {
             super(TEXT_METADATA);
@@ -1441,6 +1521,12 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
             }
         ]
     };
+    /**
+     * Composition widget that lays out child {@link PacemUiWidgetElement} widgets in a CSS grid: on `register`
+     * it finds a free spot (or grows the grid) for the new item's `column`/`row`/`colspan`/`rowspan`, and while
+     * `editing` it enables drag-move/resize behaviors (backed by internal `${P}-drag-drop`/`${P}-rescale`
+     * elements) plus an overlay of selectable grid-cell boxes.
+     */
     let PacemGridWidgetElement = class PacemGridWidgetElement extends PacemCompositeWidgetElement {
         constructor() {
             super(buildWidgetMetadata(GRID_METADATA), FALLBACK_COLUMNS, "grid");
@@ -1757,7 +1843,14 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Cms {
-    /** Default metadata ('expression' field) 'type' factory. */
+    /**
+     * Default metadata ('expression' field) 'type' factory: renders a `${P}-datacolumns` field bound to the
+     * given entity's `prop` (via `extra.properties`, either a property name or a factory function), used to
+     * edit the field's underlying {@link DataColumn}[] value.
+     * @param host The form field element requesting the markup.
+     * @param hostRef Binding-expression reference to `host` (defaults to `:host`).
+     * @param hostEntityRef Binding-expression reference to `host.entity` (defaults to `:host.entity`).
+     */
     const DATACOLUMNS_METADATA_TYPE = (host, hostRef = ':host', hostEntityRef = ':host.entity') => {
         const attrs = {}, meta = host.metadata, fns = Functions, fnKeys = [];
         attrs['properties'] = `{{ Pacem.CustomElementUtils.getWatchedProperty(${hostEntityRef}, '${meta.prop}').config.converter }}`;
@@ -1794,6 +1887,7 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
             }
         ]
     };
+    /** Single-column editor (header/content) used by {@link PacemDataColumnsElement}, self-scaffolding its inner `${P}-form` against `DATACOLUMN_METADATA`. */
     let PacemDataColumnElement = class PacemDataColumnElement extends pacemCore.Components.PacemElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -1830,6 +1924,10 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
             template: `<${pacemCore.P}-form class="panel-body" autogenerate="true"></${pacemCore.P}-form>`
         })
     ], PacemDataColumnElement);
+    /**
+     * Form field for authoring a list of {@link DataColumn}s (`value`) by drag-dropping entries from the
+     * available `properties` onto the columns strip, each rendered/edited through a nested {@link PacemDataColumnElement}.
+     */
     let PacemDataColumnsElement = class PacemDataColumnsElement extends pacemScaffolding.Components.Scaffolding.PacemBaseElement {
         constructor() {
             super(...arguments);
@@ -2026,11 +2124,20 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
     <template>${body0.innerHTML}</template>
 </div></${pacemCore.P}-repeater>`;
     }
+    /**
+     * UI widget rendering `datasource` as a CSS-grid-based data table: one `${P}-repeater`-driven row per item,
+     * one head/data cell pair per `columns` entry, with `datarowMetadata` auto-extracted from the first bound
+     * item (see `_extractMetadataJustInCase`) whenever it isn't supplied. Its markup is entirely (re)generated
+     * as plain `innerHTML` (see `datagridInnerHTML`) whenever `columns` changes.
+     */
     let PacemWidgetDataGridElement = class PacemWidgetDataGridElement extends PacemUiWidgetElement {
         constructor() {
             super(DATAGRID_METADATA);
+            /** Gets or sets the rendered columns (header + per-row content expression); reassigning rebuilds the widget's markup. */
             this.columns = [];
+            /** Gets or sets the rows rendered by the grid. */
             this.datasource = [];
+            /** Gets or sets the field metadata describing a `datasource` row; auto-extracted from the first bound item when left unset. */
             this.datarowMetadata = [];
             this._builtUponDatasource = false;
         }
@@ -2166,17 +2273,25 @@ on-${pacemCore.Net.FetchResultEventName}=":host._onresult($event)" on-${pacemCor
     });
 
     const PermissionEditEventName = 'permissionedit';
+    /** Dispatched to request permission-editing UI for the given {@link Permissible} resource. */
     class PermissionEditEvent extends CustomEvent {
         constructor(permissible) {
             super(PermissionEditEventName, { detail: permissible, cancelable: false, bubbles: true });
         }
     }
+    /** Static, claim-based authorization checks (edit/read/add/delete/translate) against a {@link Permissible} resource's {@link Permission} list. */
     class Permissible {
+        /** Gets whether `claims` grants edit (update) permission on `resource`. */
         static canEdit(claims, resource) { return this._canDoSomethingToResource(claims, resource, p => p.update); }
+        /** Gets whether `claims` grants read permission on `resource`. */
         static canRead(claims, resource) { return this._canDoSomethingToResource(claims, resource, p => p.read); }
+        /** Gets whether `claims` grants add (create) permission on `resource`. */
         static canAdd(claims, resource) { return this._canDoSomethingToResource(claims, resource, p => p.create); }
+        /** Gets whether `claims` grants delete permission on `resource`. */
         static canDelete(claims, resource) { return this._canDoSomethingToResource(claims, resource, p => p.delete); }
+        /** Gets whether `claims` grants translate permission on `resource`. */
         static canTranslate(claims, resource) { return this._canDoSomethingToResource(claims, resource, p => p.translate); }
+        /** Returns whether `claims` satisfies `predicate` for at least one of `resource.permissions`; when `resource.permissions` is empty, access is unrestricted (returns `true`). */
         static _canDoSomethingToResource(claims, resource, predicate) {
             if (pacemCore.Utils.isNullOrEmpty(claims) || pacemCore.Utils.isNull(resource)) {
                 return false;