@pacem/pacem-core 2.0.0-chebyshev → 2.0.0-euler

package/dist/docs/pacem-core.json

@@ -19282,7 +19282,7 @@
             },
             {
               "kind": "Content",
-              "text": "{\n    tagName: string;\n    options?: {\n        extends: string;\n    };\n    template?: string;\n    templateUrl?: string;\n    shadow?: boolean;\n}"
+              "text": "{\n    tagName: string;\n    options?: {\n        extends: string;\n    };\n    template?: string;\n    templateUrl?: string;\n    shadow?: boolean;\n    modifiers?: string[];\n}"
             },
             {
               "kind": "Content",
@@ -39939,7 +39939,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@pacem/pacem-core!ViewChild:function(1)",
-          "docComment": "/**\n * Property decorator that turns a class field into a lazily-resolved, cached reference to a descendant element matching `selector`. Resolution happens on first read (via `shadowRoot.querySelectorAll` when available, falling back to the element itself), and only nodes whose `INSTANCE_HOST_VAR` points back at `this` are considered — this keeps the lookup scoped to the current element's own template output, skipping over descendants that belong to a nested custom element's own template. The cache is reset whenever the host element reconnects to the DOM (`connectedCallback`, see the {@link CustomElement} decorator).\n *\n * @param selector - CSS selector identifying the child element to bind to.\n *\n * @returns A property decorator to apply to the view-child field (read-only; no setter is defined).\n */\n",
+          "docComment": "/**\n * Property decorator that turns a class field into a lazily-resolved, cached reference to a descendant element matching `selector`. Resolution happens on first read (via `shadowRoot.querySelectorAll` when available, falling back to the element itself), and only nodes whose `INSTANCE_HOST_VAR` points back at `this` are considered — this keeps the lookup scoped to the current element's own template output, skipping over descendants that belong to a nested custom element's own template. The cache is reset whenever the host element reconnects to the DOM (`connectedCallback`, see the {@link CustomElement} decorator).\n *\n * @param selector - CSS selector identifying the child element to bind to.\n *\n * @param face - Helps identifying actual surface for theming purposes.\n *\n * @param content - Helps identifying actual surface content for theming purposes, if different from face.\n *\n * @returns A property decorator to apply to the view-child field (read-only; no setter is defined).\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -39949,22 +39949,99 @@
               "kind": "Content",
               "text": "string"
             },
+            {
+              "kind": "Content",
+              "text": ", face?: "
+            },
+            {
+              "kind": "Content",
+              "text": "string | boolean"
+            },
+            {
+              "kind": "Content",
+              "text": ", content?: "
+            },
+            {
+              "kind": "Content",
+              "text": "string | boolean"
+            },
             {
               "kind": "Content",
               "text": "): "
             },
             {
               "kind": "Content",
-              "text": "(target: any, prop: string, descriptor?: "
+              "text": "any"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/types/decorators.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 7,
+            "endIndex": 8
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "selector",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "face",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "isOptional": true
+            },
+            {
+              "parameterName": "content",
+              "parameterTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "isOptional": true
+            }
+          ],
+          "name": "ViewChild"
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@pacem/pacem-core!ViewChild:function(2)",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function ViewChild(selector: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ", config?: "
             },
             {
               "kind": "Reference",
-              "text": "PropertyDescriptor",
-              "canonicalReference": "!PropertyDescriptor:interface"
+              "text": "ViewChildConfig",
+              "canonicalReference": "@pacem/pacem-core!~ViewChildConfig:type"
             },
             {
               "kind": "Content",
-              "text": ") => void"
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "any"
             },
             {
               "kind": "Content",
@@ -39973,11 +40050,11 @@
           ],
           "fileUrlPath": "dist/types/decorators.d.ts",
           "returnTypeTokenRange": {
-            "startIndex": 3,
+            "startIndex": 5,
             "endIndex": 6
           },
           "releaseTag": "Public",
-          "overloadIndex": 1,
+          "overloadIndex": 2,
           "parameters": [
             {
               "parameterName": "selector",
@@ -39986,6 +40063,14 @@
                 "endIndex": 2
               },
               "isOptional": false
+            },
+            {
+              "parameterName": "config",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "isOptional": true
             }
           ],
           "name": "ViewChild"

package/dist/esm/adapter.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/binding-parser.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/command.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/comparers.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/converters.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/decorators-next.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/decorators.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -23,12 +23,19 @@ const WATCH_VERS_PROP = 'pacem:version';
 const WATCH_BIND_PREFIX = 'pacem:binding:';
 //const WATCH_THROTTLE_PREFIX: string = 'pacem:throttle:';
 const INSTANCE_CHILDREN_VAR = 'pacem:view-children';
+const VIEWCHILD_SURFACES_VAR = 'pacem:view-children:surface';
 const HAS_BIND_PREFIX = 'pacem:has-binding:';
 const HAS_TEMPLATE_VAR = 'pacem:custom-element:has-template';
 const HASBEEN_TEMPLATED_VAR = 'pacem:custom-element:has-templated';
 const INSTANCE_PROMISE_VAR = 'pacem:custom-element:promise';
 const INSTANCE_READY_VAR = 'pacem:custom-element:ready';
 const INSTANCE_ONREADY_VAR = 'pacem:custom-element:startup';
+const SURFACETHEME_FACE_ATTR = 'surface-face';
+const SURFACETHEME_CONTENT_ATTR = 'surface-content';
+const SURFACETHEME_MODIFIER_ATTR = 'surface-modifier';
+/** the modifier of a host that is its own face */
+const SURFACETHEME_FACE_MODIFIER = 'face';
+const SURFACETHEME_CONTENT_MODIFIER = 'content';
 //const TYPE_OPTIONS_VAR = 'pacem:custom-element:options';
 function processBinding(element, property, binding) {
     var _this = element;
@@ -69,8 +76,8 @@ function processBinding(element, property, binding) {
                             //cancelAnimationFrame(_this[handleName]);
                             //_this[handleName] = requestAnimationFrame(() => {
                             _this[prop] = value.evaluate /*Async*/() /*.then(val => {
-                                _this[prop] = val;
-                            })*/;
+                                    _this[prop] = val;
+                                })*/;
                             //});
                         }
                     }
@@ -202,6 +209,23 @@ export const CustomElement = (config) => {
                     //console.log(`${_this.localName} connected.`);
                     _this.setAttribute('pacem', '');
                     _this.setAttribute('cloak', '');
+                    const faces = GET_VAL(proto, VIEWCHILD_SURFACES_VAR) ?? [];
+                    if (!Utils.isNullOrEmpty(config.modifiers)
+                        // if any surface face gets declared then the host must be spotted as a **surface** host, even if empty in modifiers
+                        || !Utils.isNullOrEmpty(faces)) {
+                        const currentModifiers = _this.getAttribute(SURFACETHEME_MODIFIER_ATTR)?.split(/\s+/) ?? [];
+                        const ownModifiers = (config.modifiers ?? []).slice(0);
+                        if (!faces.some(f => f.face)) {
+                            // no faces declared: the host is its own face
+                            ownModifiers.push(SURFACETHEME_FACE_MODIFIER);
+                        }
+                        if (!faces.some(f => f.content)) {
+                            // no contents declared: the host is its own content
+                            ownModifiers.push(SURFACETHEME_CONTENT_MODIFIER);
+                        }
+                        const modifiers = currentModifiers.union(ownModifiers);
+                        _this.setAttribute(SURFACETHEME_MODIFIER_ATTR, modifiers.join(' ').trim().replace(/\s+/g, ' '));
+                    }
                     // reset INSTANCE_CHILDREN_VAR at connectedCallback
                     DEL_VAL(_this, INSTANCE_CHILDREN_VAR);
                     // ready to fire
@@ -324,6 +348,33 @@ export const CustomElement = (config) => {
                             if (!Utils.isNull(deferred))
                                 deferred.resolve();
                         };
+                        // apply surface face attributes
+                        for (let item of faces) {
+                            const element = _this[item.ref];
+                            if (Utils.isNull(element)) {
+                                continue;
+                            }
+                            // shadow dom
+                            if (config.shadow) {
+                                if (item.content) {
+                                    const part = typeof item.content === 'string' ? item.content : 'content';
+                                    Utils.addPart(element, part);
+                                }
+                                if (item.face) {
+                                    const part = typeof item.face === 'string' ? item.face : 'face';
+                                    Utils.addPart(element, part);
+                                }
+                            }
+                            else {
+                                // non shadow dom
+                                if (item.content) {
+                                    element.setAttribute(SURFACETHEME_CONTENT_ATTR, item.content.toString());
+                                }
+                                if (item.face) {
+                                    element.setAttribute(SURFACETHEME_FACE_ATTR, item.face.toString());
+                                }
+                            }
+                        }
                         _this.removeAttribute('cloak');
                         //...now that the document is ready:
                         // fire original viewActivatedCallback
@@ -454,7 +505,7 @@ export const CustomElement = (config) => {
                                     // put proved to have relevant attribute empty. (e.g. some widget utils like `PacemWidgetFetchParameterElement` need this)
                                     || Utils.isNullOrEmpty(attr)) {
                                     var config;
-                                    if (val === undefined || val === null) {
+                                    if (Utils.isNull(val)) {
                                         _this.removeAttribute(attrName);
                                     }
                                     else if (property && (config = property.config) && typeof config.converter.convertBack === 'function') {
@@ -637,19 +688,23 @@ export function Watch(config) {
         }
     };
 }
-/**
- * Property decorator that turns a class field into a lazily-resolved, cached reference to a descendant
- * element matching `selector`. Resolution happens on first read (via `shadowRoot.querySelectorAll` when
- * available, falling back to the element itself), and only nodes whose `INSTANCE_HOST_VAR` points back
- * at `this` are considered — this keeps the lookup scoped to the current element's own template output,
- * skipping over descendants that belong to a nested custom element's own template. The cache is reset
- * whenever the host element reconnects to the DOM (`connectedCallback`, see the {@link CustomElement} decorator).
- *
- * @param selector CSS selector identifying the child element to bind to.
- * @returns A property decorator to apply to the view-child field (read-only; no setter is defined).
- */
-export function ViewChild(selector) {
+export function ViewChild(selector, faceOrObj = false, content) {
+    let face;
+    // content falls back to face's truthy value when not provided.
+    if (typeof faceOrObj === 'object') {
+        const { face: face0, content: content0 } = faceOrObj;
+        face = face0;
+        content = content0 ?? (!!face0);
+    }
+    else {
+        face = faceOrObj;
+        content ??= (!!face);
+    }
     return (target, prop, descriptor) => {
+        if (face || content) {
+            const faces = GET_VAL(target, VIEWCHILD_SURFACES_VAR, []);
+            faces.push({ ref: prop, face, content });
+        }
         const key = `${prop}_${Utils.uniqueCode()}`;
         function findElement() {
             const _this = this, nodelist = (_this.shadowRoot || _this).querySelectorAll(selector);
@@ -665,7 +720,7 @@ export function ViewChild(selector) {
             const _this = this;
             // reset INSTANCE_CHILDREN_VAR on connectedCallback!
             const dict = GET_VAL(_this, INSTANCE_CHILDREN_VAR, {});
-            return dict[key] = dict[key] || findElement.call(_this);
+            return dict[key] ??= findElement.call(_this);
         }
         if (delete target[prop]) {
             Object.defineProperty(target, prop, {

package/dist/esm/defaults.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/events.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/eventtarget.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/expression.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index-animations.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index-behaviors.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (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-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index-iife.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index-logging.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index-net.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index-root.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index-ui.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/logger.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/prefix.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/promise.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/regex.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/storage.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/template.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/transforms.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/types.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/utils-customelement.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/utils-customevent.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/esm/utils.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-chebyshev (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-euler (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/package.json

@@ -24,7 +24,7 @@
       "types": "./typings/index.d.ts"
     }
   },
-  "version": "2.0.0-chebyshev",
+  "version": "2.0.0-euler",
   "author": {
     "name": "Pacem",
     "url": "https://pacem.it"

package/typings/index.d.ts

@@ -313,6 +313,8 @@ export declare type CustomElementConfig = {
     templateUrl?: string;
     /** if `true` and shadow DOM is natively available then the templated content is hosted in a ShadowRoot  */
     shadow?: boolean;
+    /** theme behavioral identifiers */
+    modifiers?: string[];
 };
 
 /** Minimal shape of the (native or polyfilled) `CustomElementRegistry` used by {@link Utils.customElements} to define and look up custom elements. */
@@ -1536,7 +1538,6 @@ declare class PacemElement extends PacemEventTarget implements Wai {
         [name: string]: string;
     });
     get aria(): Aria;
-    private _aria;
     static get emittedEventTypes(): Readonly<string[]>;
     connectedCallback(): void;
     viewActivatedCallback(): void;
@@ -3476,9 +3477,18 @@ export declare class Utils {
  * whenever the host element reconnects to the DOM (`connectedCallback`, see the {@link CustomElement} decorator).
  *
  * @param selector CSS selector identifying the child element to bind to.
+ * @param face Helps identifying actual surface for theming purposes.
+ * @param content Helps identifying actual surface content for theming purposes, if different from face.
  * @returns A property decorator to apply to the view-child field (read-only; no setter is defined).
  */
-export declare function ViewChild(selector: string): (target: any, prop: string, descriptor?: PropertyDescriptor) => void;
+export declare function ViewChild(selector: string, face?: string | boolean, content?: string | boolean): any;
+
+export declare function ViewChild(selector: string, config?: ViewChildConfig): any;
+
+declare type ViewChildConfig = {
+    face: string | boolean;
+    content?: string | boolean;
+};
 
 declare interface Wai {
     readonly aria: Aria;