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

package/dist/esm/index-iife.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
  */

package/dist/esm/index.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
  */

package/dist/esm/index.components.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
  */

package/dist/esm/index.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
  */

package/dist/esm/types.js

@@ -1,21 +1,29 @@
 /*!
- * @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
  */
 import { Utils } from '@pacem/pacem-core';
 export const PermissionEditEventName = 'permissionedit';
+/** Dispatched to request permission-editing UI for the given {@link Permissible} resource. */
 export 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. */
 export 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 (Utils.isNullOrEmpty(claims) || Utils.isNull(resource)) {
             return false;

package/package.json

@@ -4,6 +4,7 @@
     "dist/browser/*.*",
     "dist/bundle/*.*",
     "dist/esm/*.*",
+    "dist/docs/*.*",
     "typings/*.*",
     "README.md",
     "LICENSE",
@@ -28,7 +29,7 @@
       "types": "./typings/index.d.ts"
     }
   },
-  "version": "1.0.0-bessel",
+  "version": "1.0.0-dirac",
   "author": {
     "name": "Pacem",
     "url": "https://pacem.it"

package/typings/index.d.ts

@@ -10,8 +10,14 @@ import { Storage as Storage_2 } from '@pacem/pacem-core';
 
 declare const ACCESS_TOKEN_METADATA: Scaffolding.PropertyMetadata;
 
+/**
+ * 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.
+ */
 declare function buildWidgetMetadata(metadata?: Scaffolding.TypeMetadata): Scaffolding.TypeMetadata;
 
+/** Maps a claim type to the set of claim values held by the current user/context. */
 declare type Claims = {
     [name: string]: string[];
 };
@@ -75,12 +81,14 @@ export declare namespace Components {
     }
 }
 
+/** Contract for a container of {@link PacemUiWidgetElement} items, backed by the `Element` (`itemsElement`) their DOM nodes are appended to. */
 declare interface CompositeWidget extends ItemsContainer<PacemUiWidgetElement> {
     readonly itemsElement: Element;
     register(item: PacemUiWidgetElement): boolean;
     unregister(item: PacemUiWidgetElement): boolean;
 }
 
+/** A single rendered column of a data-grid-like widget: its header label, its per-row content (expression, constant, ...) and an optional relative/`'auto'` width. */
 declare interface DataColumn {
     header: string;
     /** expression, constant, ... */
@@ -88,7 +96,14 @@ declare interface DataColumn {
     width?: number | 'auto';
 }
 
-/** 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`).
+ */
 declare const DATACOLUMNS_METADATA_TYPE: (host: Components_2.Scaffolding.PacemFormFieldElement, hostRef?: string, hostEntityRef?: string) => {
     tagName: string;
     attrs: {
@@ -98,7 +113,14 @@ declare const DATACOLUMNS_METADATA_TYPE: (host: Components_2.Scaffolding.PacemFo
 
 declare const DEFAULT_METADATA: Scaffolding.TypeMetadata;
 
-/** 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`).
+ */
 declare const EXPRESSION_METADATA_TYPE: (host: Components_2.Scaffolding.PacemFormFieldElement, hostRef?: string, hostEntityRef?: string) => {
     tagName: string;
     attrs: {
@@ -112,6 +134,7 @@ declare const EXPRESSION_WIDGET_METADATA_EXTRA: {
     labeler: (e: Widget) => string;
 };
 
+/** The kind of value a {@link PacemExpressionElement} is currently editing, as picked in its source selector. */
 declare enum ExpressionSource {
     Constant = "const",
     PropertyReference = "property",
@@ -127,6 +150,12 @@ declare const Functions: {
 
 declare const GRID_COLUMNS = 12;
 
+/**
+ * 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.
+ */
 declare function gridifyMetadata(metadata?: Scaffolding.TypeMetadata): Scaffolding.TypeMetadata;
 
 declare const LayoutChangeEventName = "layoutchange";
@@ -137,21 +166,34 @@ export declare namespace OpenApi {
     }
 }
 
+/**
+ * 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.
+ */
 declare abstract class PacemBearerWidgetElement extends PacemWidgetElement implements Net.OAuthFetchable {
+    /** Gets or sets the `credentials` mode used for the widget's fetch requests. */
     fetchCredentials: RequestCredentials;
+    /** Gets or sets the HTTP headers sent with the widget's fetch requests; recomputed from `accessToken` when that changes. */
     fetchHeaders: {
         [key: string]: string;
     };
+    /** Gets or sets the bearer token used to authenticate the widget's fetch requests. */
     accessToken: {
         [key: string]: string;
     };
+    /** Gets or sets whether a fetch request is currently in flight. */
     fetching: boolean;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** Base class for widgets that act as a container ({@link CompositeWidget}) for other {@link PacemUiWidgetElement} widgets. See {@link PacemGridWidgetElement} and `PacemWidgetPickerElement` for concrete implementations. */
 declare abstract class PacemCompositeWidgetElement extends PacemUiWidgetElement implements CompositeWidget {
+    /** @readonly Gets the currently registered child widgets. */
     items: PacemUiWidgetElement[];
+    /** Gets the `Element` new items are appended to; defaults to this widget itself. */
     get itemsElement(): this;
+    /** Gets whether `item` is an acceptable child of this container; overridable by subclasses to narrow the accepted item type. */
     protected validate(item: PacemUiWidgetElement): boolean;
     viewActivatedCallback(): void;
     /**
@@ -171,20 +213,29 @@ declare abstract class PacemCompositeWidgetElement extends PacemUiWidgetElement
     unregister(item: PacemUiWidgetElement): boolean;
 }
 
+/** Single-column editor (header/content) used by {@link PacemDataColumnsElement}, self-scaffolding its inner `${P}-form` against `DATACOLUMN_METADATA`. */
 declare class PacemDataColumnElement extends Components_3.PacemElement {
+    /** Gets or sets the column's header label. */
     header: string;
+    /** Gets or sets the column's content attribute, mirrored from/to `contentExpression`. */
     content: string;
+    /** Gets or sets the column's content as an expression string, mirrored from/to the `content` attribute. */
     contentExpression: string;
     private _form;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
 }
 
+/**
+ * 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}.
+ */
 declare class PacemDataColumnsElement extends Components_2.Scaffolding.PacemBaseElement {
     private _repeater;
     private _propDragger;
     private _colDragger;
     private _dropTarget;
+    /** Gets or sets the properties available to be dragged in as new columns. */
     properties: Partial<Scaffolding.PropertyMetadata>[];
     protected get inputFields(): HTMLElement[];
     protected toggleReadonlyView(readonly: boolean): void;
@@ -198,6 +249,7 @@ declare class PacemDataColumnsElement extends Components_2.Scaffolding.PacemBase
     private _columnifyMetadata;
 }
 
+/** Form field for picking an `Element` (identified by its `id`) among those matching `selector`/`filter`, listed in a `${P}-select`. */
 declare class PacemElementPickerElement extends PacemElementPickerElementBase {
     protected get inputFields(): HTMLElement[];
     protected toggleReadonlyView(readonly: boolean): void;
@@ -211,12 +263,25 @@ declare class PacemElementPickerElement extends PacemElementPickerElementBase {
     private _databind;
 }
 
+/**
+ * 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.
+ */
 declare abstract class PacemElementPickerElementBase extends Components_2.Scaffolding.PacemBaseElement {
+    /** Gets or sets the CSS selector used to query the candidate elements (defaults to `[pacem]`). */
     selector: string;
+    /** Gets or sets the predicate further restricting the candidate elements queried by `selector`. */
     filter: (e: Element) => boolean;
+    /** Gets or sets the function projecting a candidate element into its display label. */
     labeler: (e: Element) => string;
 }
 
+/**
+ * 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.
+ */
 declare class PacemExpressionElement extends PacemElementPickerElementBase {
     converter: PropertyConverter;
     private _editing;
@@ -239,19 +304,34 @@ declare class PacemExpressionElement extends PacemElementPickerElementBase {
     private _reverseStructure;
 }
 
+/**
+ * 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.
+ */
 declare class PacemGridWidgetElement extends PacemCompositeWidgetElement {
     constructor();
     register(item: PacemUiWidgetElement): boolean;
     unregister(item: PacemUiWidgetElement): boolean;
     private _widgetPropertyChange;
+    /** Gets or sets the pixel size of one layout unit (used to convert `marginTop`/`marginBottom`/`rowGap`/`columnGap` into pixels). */
     unit: number;
+    /** Gets or sets the grid's top margin, in `unit`s. */
     marginTop: number;
+    /** Gets or sets the grid's bottom margin, in `unit`s. */
     marginBottom: number;
+    /** Gets or sets the number of grid columns. */
     columns: number;
+    /** Gets or sets the number of grid rows; automatically grown when a child widget needs a new row. */
     rows: number;
+    /** Gets or sets the minimum row height (a CSS length, or a number of pixels). */
     minRowheight: number | 'string';
+    /** Gets or sets the row height (a CSS length, or a number of pixels). */
     rowheight: number | 'string';
+    /** Gets or sets the gap between rows, in `unit`s. */
     rowGap: number;
+    /** Gets or sets the gap between columns, in `unit`s. */
     columnGap: number;
     private _dragDrop;
     private _rescaler;
@@ -270,6 +350,10 @@ declare class PacemGridWidgetElement extends PacemCompositeWidgetElement {
     private _setGridLines;
 }
 
+/**
+ * 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`).
+ */
 declare abstract class PacemUiWidgetElement extends PacemWidgetElement {
     constructor(metadata: Scaffolding.TypeMetadata, colspan?: number, role?: string);
     connectedCallback(): void;
@@ -281,41 +365,65 @@ declare abstract class PacemUiWidgetElement extends PacemWidgetElement {
     viewActivatedCallback(): void;
     disconnectedCallback(): void;
     /** Default configuration (grid) */
+    /** Gets or sets the widget's 0-based starting column in the layout grid. */
     column: number;
+    /** Gets or sets the widget's 0-based starting row in the layout grid. */
     row: number;
+    /** Gets or sets how many columns the widget spans. */
     colspan: number;
+    /** Gets or sets how many rows the widget spans. */
     rowspan: number;
+    /** Gets or sets whether the widget's cell is rendered with borders. */
     borders: boolean;
+    /** Gets or sets whether the widget's cell is rendered with rounded corners. */
     corners: boolean;
 }
 
+/** Non-visual helper widget that parses an OpenApi document at `url` (via {@link SwaggerCmsParser}) into a `manifest`, typically referenced by a {@link PacemWidgetFetchElement}. */
 declare class PacemWidgetApiManifestElement extends PacemBearerWidgetElement {
     private _openapi;
     private _cache;
     constructor(_openapi?: SwaggerCmsParser, _cache?: Storage_2);
+    /** Gets or sets the url of the OpenApi (swagger) json configuration to parse. */
     url: string;
+    /** Gets or sets whether the parsed manifest is cached per-url. */
     usecache: boolean;
+    /** @readonly Gets the manifest parsed from `url`. */
     manifest: Scaffolding.OpenApi.ApiManifest;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
     private _scaffold;
 }
 
+/** Non-visual helper widget exposing the current timestamp (`time`), refreshed every `interval` milliseconds by an internal `${P}-timer`. */
 declare class PacemWidgetClockElement extends PacemWidgetElement {
     constructor();
+    /** Gets or sets the tick interval, in milliseconds, at which `time` is refreshed. */
     interval: number;
+    /** @readonly Gets the current timestamp (`Date.now()` at the last tick). */
     time: number;
 }
 
+/** Non-visual helper widget exposing an arbitrary `model` object, typically referenced as a data source by other widgets/expressions. */
 declare class PacemWidgetDataElement extends PacemWidgetElement {
     constructor();
+    /** Gets or sets the arbitrary data object exposed by this widget. */
     model: any;
 }
 
+/**
+ * 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.
+ */
 declare class PacemWidgetDataGridElement extends PacemUiWidgetElement {
     constructor();
+    /** Gets or sets the rendered columns (header + per-row content expression); reassigning rebuilds the widget's markup. */
     columns: DataColumn[];
+    /** Gets or sets the rows rendered by the grid. */
     datasource: any[];
+    /** Gets or sets the field metadata describing a `datasource` row; auto-extracted from the first bound item when left unset. */
     datarowMetadata: Partial<Scaffolding.PropertyMetadata>[];
     _datatable: HTMLElement;
     _template: HTMLTemplateElement;
@@ -328,6 +436,12 @@ declare class PacemWidgetDataGridElement extends PacemUiWidgetElement {
     private _extractMetadataJustInCase;
 }
 
+/**
+ * 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.
+ */
 declare abstract class PacemWidgetElement extends Components_3.PacemElement implements Widget {
     constructor(metadata: Scaffolding.TypeMetadata, role?: string);
     connectedCallback(): void;
@@ -340,24 +454,44 @@ declare abstract class PacemWidgetElement extends Components_3.PacemElement impl
     private _disposeBalloon;
     /** Gets or sets whether the widget is currently in editing mode. */
     editing: boolean;
+    /** Gets or sets whether the widget might be edited at all; disabling it also tears down its toolbar balloon. */
     editable: boolean;
+    /** Gets or sets the widget's display tag/name, shown by its toolbar. */
     tag: string;
+    /** Gets or sets the widget's {@link Permission} rules. */
     permissions: Permission[];
+    /** Gets or sets the scaffolding metadata describing the widget's own editable properties. */
     metadata: Scaffolding.TypeMetadata;
+    /** Gets or sets the scaffolding metadata describing the widget's permission-editing form. */
     permissionMetadata: Scaffolding.TypeMetadata;
 }
 
+/**
+ * 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`.
+ */
 declare class PacemWidgetFetchElement extends PacemBearerWidgetElement {
     constructor();
+    /** Gets or sets the OpenApi manifest describing the endpoints available to `endpoint`. */
     manifest: Scaffolding.OpenApi.ApiManifest;
+    /** Gets or sets the endpoint, picked from `manifest`, to fetch from; setting it re-derives `url`/`method`/`fields` and syncs the child parameter elements. */
     endpoint: Scaffolding.OpenApi.ApiEndpoint;
+    /** Gets or sets the fetch url, derived from `manifest.baseUrl` and `endpoint.path`. */
     url: string;
+    /** Gets or sets the HTTP method, derived from `endpoint.method`. */
     method: Net.HttpMethod;
+    /** Gets or sets the response's field metadata, derived from `endpoint.response.fields`. */
     fields: Scaffolding.TypeMetadata | Scaffolding.PropertyMetadata[];
+    /** Gets or sets the parameter values (editing-time convenience mirror of the nested {@link PacemWidgetFetchParameterElement} children). */
     parameters: any[];
+    /** @readonly Gets the last fetched result. */
     result: any[];
+    /** @readonly Gets whether a fetch request is currently in flight. */
     fetching: boolean;
+    /** @readonly Gets whether the last fetch request completed successfully. */
     success: boolean;
+    /** @readonly Gets whether the last fetch request failed. */
     failure: boolean;
     private _fetcher;
     private _itemsElement;
@@ -365,16 +499,21 @@ declare class PacemWidgetFetchElement extends PacemBearerWidgetElement {
     private _onsuccess;
     private _onresult;
     get _parameters(): PacemWidgetFetchParameterElement[];
+    /** Triggers the request against `endpoint`/`url`, provided all of the endpoint's required parameters are attached and populated; otherwise does nothing. */
     fetch(): Promise<Response>;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     private _mergeEndpoint;
 }
 
+/** A single, named fetch parameter nested under a {@link PacemWidgetFetchElement}; setting `value` re-triggers the owning fetcher's `fetch()`. */
 declare class PacemWidgetFetchParameterElement extends PacemEventTarget {
     private _fetcher;
+    /** Gets or sets whether the owning endpoint requires this parameter. */
     required: boolean;
+    /** Gets or sets the parameter's name, matched against the endpoint's declared parameters. */
     name: string;
+    /** Gets or sets the parameter's value. */
     value: any;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
@@ -388,12 +527,16 @@ declare class PacemWidgetPickerElement extends PacemCompositeWidgetElement {
     private _dragDrop;
 }
 
+/** UI widget rendering a plain (optionally expression-bound) piece of text via an inner `${P}-text`. */
 declare class PacemWidgetTextElement extends PacemUiWidgetElement {
     constructor();
+    /** Gets or sets the text displayed by the widget. */
     text: string;
 }
 
+/** Floating toolbar (edit/permissions/remove buttons), shown by a {@link PacemWidgetElement}'s balloon while `editing`, that opens the widget's core/permissions edit forms. */
 declare class PacemWidgetToolbarElement extends Components_3.PacemElement {
+    /** Gets or sets the widget this toolbar acts upon. */
     target: PacemWidgetElement;
     private _toolbar;
     private _btnEdit;
@@ -411,22 +554,32 @@ declare class PacemWidgetToolbarElement extends Components_3.PacemElement {
     private _popoutJustInCase;
 }
 
+/** Non-visual helper widget, reserved for translation-related composition (no widget-specific behavior beyond {@link PacemWidgetElement}). */
 declare class PacemWidgetTranslatorElement extends PacemWidgetElement {
 }
 
+/** A resource carrying a list of {@link Permission} rules, checkable via the {@link Permissible} static helpers. */
 declare interface Permissible {
     permissions: Permission[];
 }
 
+/** Static, claim-based authorization checks (edit/read/add/delete/translate) against a {@link Permissible} resource's {@link Permission} list. */
 declare class Permissible {
+    /** Gets whether `claims` grants edit (update) permission on `resource`. */
     static canEdit(claims: Claims, resource: Permissible): boolean;
+    /** Gets whether `claims` grants read permission on `resource`. */
     static canRead(claims: Claims, resource: Permissible): boolean;
+    /** Gets whether `claims` grants add (create) permission on `resource`. */
     static canAdd(claims: Claims, resource: Permissible): boolean;
+    /** Gets whether `claims` grants delete permission on `resource`. */
     static canDelete(claims: Claims, resource: Permissible): boolean;
+    /** Gets whether `claims` grants translate permission on `resource`. */
     static canTranslate(claims: Claims, resource: Permissible): boolean;
+    /** Returns whether `claims` satisfies `predicate` for at least one of `resource.permissions`; when `resource.permissions` is empty, access is unrestricted (returns `true`). */
     private static _canDoSomethingToResource;
 }
 
+/** A single claim-based authorization rule attached to a {@link Permissible} resource: users holding claim `claimType`/`claimValue` are granted the flagged operations. */
 declare interface Permission {
     claimType: string;
     claimValue: string;
@@ -437,6 +590,7 @@ declare interface Permission {
     delete: boolean;
 }
 
+/** Dispatched to request permission-editing UI for the given {@link Permissible} resource. */
 declare class PermissionEditEvent extends CustomEvent<Permissible> {
     constructor(permissible: Permissible);
 }
@@ -449,15 +603,29 @@ declare interface StorageCache {
     removeProperty: (name: string) => void;
 }
 
+/**
+ * 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`.
+ */
 declare class SwaggerCmsParser {
     private _openApi;
     constructor(_openApi?: Scaffolding.OpenApi.OpenApiParser);
+    /** Gets or sets the storage used to cache per-url metadata fetches; when unset, metadata is re-fetched on every `load`. */
     cache: StorageCache;
+    /**
+     * 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.
+     */
     load(url: string, headers?: {
         [name: string]: string;
     }): Promise<Scaffolding.OpenApi.ApiManifest>;
     private _enrichSchemas;
     private _cachedMetadataUrls;
+    /** Removes from `cache` every metadata entry fetched by this parser so far. */
     clearCache(): void;
     /**
      *
@@ -467,17 +635,23 @@ declare class SwaggerCmsParser {
     private _fetchMetadata;
 }
 
+/** Contract for a CMS widget: its scaffolding metadata, editing state, permissions and identity. Implemented by {@link PacemWidgetElement}. */
 declare interface Widget extends Permissible {
+    /** Gets or sets the scaffolding metadata describing the widget's own editable properties. */
     metadata: Scaffolding.TypeMetadata;
+    /** Gets or sets the scaffolding metadata describing the widget's permission-editing form. */
     permissionMetadata: Scaffolding.TypeMetadata;
     /** Gets or sets whether the widget is currently in editing mode. */
     editing: boolean;
     /** Gets or sets whether thet widget might be edited or not. */
     editable: boolean;
+    /** Gets or sets the widget's display tag/name, shown by its toolbar. */
     tag: string;
+    /** @readonly Gets the widget's DOM id. */
     readonly id: string;
 }
 
+/** Static lookup helper for {@link PacemWidgetElement} instances in the current document. */
 declare class Widget {
     /**
      * Utility method for widget gathering.
@@ -486,12 +660,14 @@ declare class Widget {
     static findAll(predicate?: (w: PacemWidgetElement) => boolean): PacemWidgetElement[];
 }
 
+/** Dispatched by a {@link PacemCompositeWidgetElement} right after a child widget is successfully registered into it. */
 declare class WidgetRegisterEvent extends CustomEvent<PacemWidgetElement> {
     constructor(item: PacemWidgetElement, eventInit?: EventInit);
 }
 
 declare const WidgetRegisterEventName = "widgetregister";
 
+/** Dispatched by a {@link PacemCompositeWidgetElement} right after a child widget is unregistered from it. */
 declare class WidgetUnregisterEvent extends CustomEvent<PacemWidgetElement> {
     constructor(item: PacemWidgetElement, eventInit?: EventInit);
 }