wj-elements 0.2.0-alpha.8 → 0.3.0

package/dist/wje-element.js

@@ -15,201 +15,8 @@ import { Permissions } from "./permissions.js";
 import { WjElementUtils } from "./element-utils.js";
 import { event } from "./event.js";
 import { store, defaultStoreActions } from "./wje-store.js";
-const skeletonCss = `/*
-[ Skeleton ]
-*/
-
-@keyframes wje-skeleton-shimmer {
-  from {
-    transform: translateX(-100%);
-  }
-  to {
-    transform: translateX(100%);
-  }
-}
-
-.wje-skeleton {
-  cursor: progress;
-  user-select: none;
-}
-
-.wje-skeleton-overlay {
-  display: grid;
-}
-
-.wje-skeleton-overlay-content,
-.wje-skeleton-overlay-skeleton {
-  grid-area: 1 / 1;
-}
-
-.wje-skeleton-overlay-skeleton {
-  display: none;            /* shown in loading state */
-  pointer-events: none;     /* skeleton should not be interactive */
-  align-self: stretch;
-  justify-self: stretch;
-}
-
-.wje-skeleton-overlay-skeleton > .wje-skeleton {
-  width: 100%;
-  height: 100%;
-  box-sizing: border-box;
-}
-
-/* Base "shape" primitives */
-.wje-skeleton-line,
-.wje-skeleton-head,
-.wje-skeleton-circle,
-.wje-skeleton-square {
-  position: relative;
-  overflow: hidden;
-  background-color: var(--wje-skeleton-bg);
-}
-
-.wje-skeleton-line {
-  display: block;
-  height: var(--wje-skeleton-height);
-  border-radius: var(--wje-skeleton-radius);
-  width: 100%;
-  flex: 0 0 auto;
-}
-
-.wje-skeleton-flex-row {
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: var(--wje-skeleton-gap);
-}
-
-.wje-skeleton-flex-column {
-  display: flex;
-  flex-direction: column;
-  gap: var(--wje-skeleton-gap);
-}
-
-.wje-skeleton-line + .wje-skeleton-line,
-.wje-skeleton-line + .wje-skeleton-head,
-.wje-skeleton-head + .wje-skeleton-line,
-.wje-skeleton-head + .wje-skeleton-head,
-.wje-skeleton-circle + .wje-skeleton-line,
-.wje-skeleton-line + .wje-skeleton-circle {
-  /*margin-top: var(--wje-skeleton-gap);*/
-}
-
-.wje-skeleton-head {
-  display: block;
-  height: var(--wje-skeleton-head-height);
-  border-radius: var(--wje-skeleton-radius);
-  width: 100%;
-}
-
-.wje-skeleton-circle {
-  display: block;
-  /* Take remaining width in flex row (e.g. 40% if sibling is w-60) */
-  flex: 1 1 0;
-  max-width: 100%;
-  aspect-ratio: 1 / 1;
-  border-radius: 50%;
-}
-
-.wje-skeleton-square {
-  display: block;
-  width: 100%;
-  height: 150px;
-  border-radius: 8px;
-}
-
-/* Shimmer layer */
-.wje-skeleton-line::after,
-.wje-skeleton-head::after,
-.wje-skeleton-circle::after,
-.wje-skeleton-square::after {
-  content: '';
-  position: absolute;
-  inset: 0;
-  transform: translateX(-100%);
-  animation: wje-skeleton-shimmer var(--wje-skeleton-duration) infinite;
-  background: linear-gradient(90deg, transparent, var(--wje-skeleton-highlight), transparent);
-}
-
-/* "Stronger" variant */
-.wje-skeleton-strong .wje-skeleton-line,
-.wje-skeleton-strong .wje-skeleton-head,
-.wje-skeleton-strong .wje-skeleton-circle,
-.wje-skeleton-strong .wje-skeleton-square {
-  background-color: var(--wje-skeleton-bg-strong);
-}
-
-/* Simple layout helpers (opt-in) */
-.wje-skeleton .flex { display: flex; }
-.wje-skeleton .inline-flex { display: inline-flex; }
-.wje-skeleton .align-center { align-items: center; }
-.wje-skeleton .align-start { align-items: flex-start; }
-.wje-skeleton .align-end { align-items: flex-end; }
-.wje-skeleton .justify-start { justify-content: flex-start; }
-.wje-skeleton .justify-end { justify-content: flex-end; }
-.wje-skeleton .justify-between { justify-content: space-between; }
-.wje-skeleton .justify-center { justify-content: center; }
-.wje-skeleton .justify-around { justify-content: space-around; }
-
-.wje-skeleton .gap { gap: var(--wje-skeleton-gap); }
-
-.wje-skeleton .w-5 { width: 5%; }
-.wje-skeleton .w-10 { width: 10%; }
-.wje-skeleton .w-15 { width: 15%; }
-.wje-skeleton .w-20 { width: 20%; }
-.wje-skeleton .w-25 { width: 25%; }
-.wje-skeleton .w-30 { width: 30%; }
-.wje-skeleton .w-35 { width: 35%; }
-.wje-skeleton .w-40 { width: 40%; }
-.wje-skeleton .w-45 { width: 45%; }
-.wje-skeleton .w-50 { width: 50%; }
-.wje-skeleton .w-55 { width: 55%; }
-.wje-skeleton .w-60 { width: 60%; }
-.wje-skeleton .w-65 { width: 65%; }
-.wje-skeleton .w-70 { width: 70%; }
-.wje-skeleton .w-75 { width: 75%; }
-.wje-skeleton .w-80 { width: 80%; }
-.wje-skeleton .w-85 { width: 85%; }
-.wje-skeleton .w-90 { width: 90%; }
-.wje-skeleton .w-95 { width: 95%; }
-.wje-skeleton .w-100 { width: 100%; }
-
-.wje-skeleton .mb { margin-bottom: 16px; }
-.wje-skeleton .mt { margin-top: 16px; }
-.wje-skeleton .mr { margin-right: 16px; }
-.wje-skeleton .ml { margin-left: 16px; }
-.wje-skeleton .mbs { margin-bottom: 8px; }
-.wje-skeleton .mts { margin-top: 8px; }
-.wje-skeleton .mrs { margin-right: 8px; }
-.wje-skeleton .mls { margin-left: 8px; }
-
-/* Optional state helpers */
-.wje-skeleton-loading .wje-skeleton-overlay-content {
-  visibility: hidden;
-  pointer-events: none;
-}
-
-.wje-skeleton-loading .wje-skeleton-overlay-skeleton {
-  display: block;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .wje-skeleton-line::after,
-  .wje-skeleton-head::after,
-  .wje-skeleton-circle::after,
-  .wje-skeleton-square::after {
-    animation: none;
-    transform: none;
-    opacity: 0.35;
-  }
-}`;
 const template = document.createElement("template");
 template.innerHTML = ``;
-const wjSkeletonSheet = new CSSStyleSheet();
-try {
-  wjSkeletonSheet.replaceSync(skeletonCss);
-} catch (e) {
-}
 const _WJElement = class _WJElement extends HTMLElement {
   /**
    * Initializes a new instance of the WJElement class.
@@ -242,9 +49,6 @@ const _WJElement = class _WJElement extends HTMLElement {
         if (this.shadowRoot) {
           const existing = this.shadowRoot.adoptedStyleSheets || [];
           const next = [...existing];
-          if (!next.includes(wjSkeletonSheet) && wjSkeletonSheet.cssRules !== void 0) {
-            next.push(wjSkeletonSheet);
-          }
           if (!next.includes(sheet)) next.push(sheet);
           this.shadowRoot.adoptedStyleSheets = next;
         }
@@ -252,6 +56,9 @@ const _WJElement = class _WJElement extends HTMLElement {
         resolve();
       });
     });
+    if (typeof this.attachInternals === "function") {
+      this.internals = this.attachInternals();
+    }
     __privateSet(this, _isAttached, false);
     this.service = new UniversalService({
       store
@@ -365,6 +172,35 @@ const _WJElement = class _WJElement extends HTMLElement {
   get store() {
     return store;
   }
+  /**
+   * Returns ElementInternals when available.
+   * @returns {ElementInternals|null}
+   */
+  getInternals() {
+    return this.internals || null;
+  }
+  /**
+   * Sets ARIA state via attributes.
+   * Accepts camelCase keys without the "aria" prefix, plus "role".
+   * Example: setAriaState({ role: 'tab', selected: true, controls: 'panel-1' })
+   * @param {object} state
+   */
+  setAriaState(state = {}) {
+    if (!state || typeof state !== "object") return;
+    Object.entries(state).forEach(([key, value]) => {
+      if (value === void 0 || value === null) return;
+      if (key === "role") {
+        this.setAttribute("role", value);
+        return;
+      }
+      let attr;
+      if (key === "labelledBy") attr = "aria-labelledby";
+      else if (key === "describedBy") attr = "aria-describedby";
+      else attr = `aria-${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`;
+      const normalized = typeof value === "boolean" ? value ? "true" : "false" : value;
+      this.setAttribute(attr, normalized);
+    });
+  }
   /**
    * @typedef {object} ArrayActions
    * @property {Function} addAction - Adds an item to the array.
@@ -476,16 +312,16 @@ const _WJElement = class _WJElement extends HTMLElement {
   /**
    * Retrieves the delay duration for the skeleton display, determining the value based on a hierarchy of overrides and defaults.
    * The method prioritizes in the following order:
-   * 1. A finite number set as the `_wjSkeletonSlotClone` property.
+   * 1. A finite number set as the `_wjSkeletonDelayOverride` property.
    * 2. A valid numeric value from the `skeleton-delay` attribute.
    * 3. The `skeletonDelayMs` property, if defined with a finite number.
    * 4. A default value of 150 if none of the above are set.
    * @returns {number} The delay in milliseconds before the skeleton is displayed.
    */
   get skeletonDelay() {
-    if (Number.isFinite(this._wjSkeletonSlotClone)) return this._wjSkeletonSlotClone;
+    if (Number.isFinite(this._wjSkeletonDelayOverride)) return this._wjSkeletonDelayOverride;
     const v = this.getAttribute("skeleton-delay");
-    const n = v == null ? NaN : Number(v);
+    const n = v === null || v === void 0 ? NaN : Number(v);
     if (Number.isFinite(n)) return n;
     if (Number.isFinite(this.skeletonDelayMs)) return this.skeletonDelayMs;
     return 150;
@@ -499,44 +335,66 @@ const _WJElement = class _WJElement extends HTMLElement {
    * @returns {number} The minimum duration for the skeleton animation in milliseconds.
    */
   get skeletonMinDuration() {
-    if (Number.isFinite(this._wjSkeletonSlotClone)) return this._wjSkeletonSlotClone;
+    if (Number.isFinite(this._wjSkeletonMinDurationOverride)) return this._wjSkeletonMinDurationOverride;
     const v = this.getAttribute("skeleton-min-duration");
-    const n = v == null ? NaN : Number(v);
+    const n = v === null || v === void 0 ? NaN : Number(v);
     if (Number.isFinite(n)) return n;
     return 300;
   }
+  /**
+   * Sets the minimum duration for the skeleton state. If the provided value is null, undefined, or an empty string,
+   * the override for the minimum duration is removed.
+   * @param {string|number|null|undefined} value The minimum duration to be set for the skeleton state. It can be a numeric value, string representation of a number, or null/undefined to reset the value.
+   */
   set skeletonMinDuration(value) {
     if (value === null || value === void 0 || value === "") {
-      delete this._wjSkeletonSlotClone;
+      delete this._wjSkeletonMinDurationOverride;
       this.removeAttribute("skeleton-min-duration");
       return;
     }
     const n = Number(value);
     if (Number.isFinite(n)) {
-      this._wjSkeletonSlotClone = n;
+      this._wjSkeletonMinDurationOverride = n;
       this.setAttribute("skeleton-min-duration", String(n));
     }
   }
-  // Public API: property-based control
+  /**
+   * Sets or removes the 'skeleton' attribute based on the provided value.
+   * @param {boolean} value A boolean value indicating whether to set ('true') or remove ('false') the 'skeleton' attribute.
+   */
   set skeleton(value) {
     if (value) this.setAttribute("skeleton", "");
     else this.removeAttribute("skeleton");
   }
+  /**
+   * Checks if the 'skeleton' attribute is present on the element.
+   * @returns {boolean} True if the 'skeleton' attribute exists, false otherwise.
+   */
   get skeleton() {
     return this.hasAttribute("skeleton");
   }
+  /**
+   * Sets the delay for the skeleton loading indicator.
+   * @param {string|number|null|undefined} value The delay value to be set. Accepts a numerical value,
+   * a string that can be converted to a number, null, or undefined.
+   * If null or undefined is provided, the skeleton delay will be cleared.
+   */
   set skeletonDelay(value) {
     if (value === null || value === void 0 || value === "") {
-      delete this._wjSkeletonSlotClone;
+      delete this._wjSkeletonDelayOverride;
       this.removeAttribute("skeleton-delay");
       return;
     }
     const n = Number(value);
     if (Number.isFinite(n)) {
-      this._wjSkeletonSlotClone = n;
+      this._wjSkeletonDelayOverride = n;
       this.setAttribute("skeleton-delay", String(n));
     }
   }
+  /**
+   * Retrieves the delay value used for skeleton loading.
+   * @returns {number} The delay value for the skeleton loader.
+   */
   get skeletonDelayValue() {
     return this.skeletonDelay;
   }
@@ -621,6 +479,12 @@ const _WJElement = class _WJElement extends HTMLElement {
       __privateMethod(this, _WJElement_instances, enqueueUpdate_fn).call(this);
     }
   }
+  /**
+   * Triggers a refresh operation by initializing the update lifecycle and setting up promises
+   * to track its completion or failure status. Marks the instance as not pristine and queues
+   * an update.
+   * @returns {void} Does not return a value.
+   */
   refresh() {
     this.updateComplete = new Promise((resolve, reject) => {
       this.finisPromise = resolve;
@@ -629,33 +493,16 @@ const _WJElement = class _WJElement extends HTMLElement {
     __privateSet(this, _pristine, false);
     __privateMethod(this, _WJElement_instances, enqueueUpdate_fn).call(this);
   }
+  /**
+   * Stops the current render loop if it is running by canceling the requestAnimationFrame.
+   * @returns {void} This method does not return a value.
+   */
   stopRenderLoop() {
     if (this.rafId) {
       cancelAnimationFrame(this.rafId);
       this.rafId = null;
     }
   }
-  /**
-   * Renders the component within the provided context.
-   * @param context The rendering context, usually the element's shadow root or main DOM element.
-   * @param appStore The global application store for managing state.
-   * @param params Additional parameters or attributes for rendering the component.
-   * @returns This implementation does not render anything and returns `null`.
-   * @description
-   * The `draw` method is responsible for rendering the component's content.
-   * Override this method in subclasses to define custom rendering logic.
-   * @example
-   * class MyComponent extends WJElement {
-   *   draw(context, appStore, params) {
-   *     const div = document.createElement('div');
-   *     div.textContent = 'Hello, world!';
-   *     context.appendChild(div);
-   *   }
-   * }
-   */
-  draw(context, appStore, params) {
-    return null;
-  }
   /**
    * Displays the component's content, optionally forcing a re-render.
    * @param [force] Whether to force a re-render.
@@ -682,14 +529,15 @@ const _WJElement = class _WJElement extends HTMLElement {
       var _a, _b;
       const slotted = this.querySelector('[slot="skeleton"]');
       if (slotted) {
-        this._wjSkeletonSlotClone = slotted.cloneNode(true);
-        const frag2 = document.createDocumentFragment();
-        frag2.append(this._wjSkeletonSlotClone.cloneNode(true));
-        return frag2;
-      }
-      if (this._wjSkeletonSlotClone) {
+        if (this.hasShadowRoot) {
+          const frag3 = document.createDocumentFragment();
+          const slot = document.createElement("slot");
+          slot.name = "skeleton";
+          frag3.append(slot);
+          return frag3;
+        }
         const frag2 = document.createDocumentFragment();
-        frag2.append(this._wjSkeletonSlotClone.cloneNode(true));
+        frag2.append(slotted.cloneNode(true));
         return frag2;
       }
       const frag = document.createDocumentFragment();
@@ -697,7 +545,7 @@ const _WJElement = class _WJElement extends HTMLElement {
       if (skel instanceof Promise || ((_b = skel == null ? void 0 : skel.constructor) == null ? void 0 : _b.name) === "Promise") {
         skel = await skel;
       }
-      if (skel == null) return null;
+      if (skel === null || skel === void 0) return null;
       let node;
       if (skel instanceof HTMLElement || skel instanceof DocumentFragment) {
         node = skel;
@@ -721,12 +569,6 @@ const _WJElement = class _WJElement extends HTMLElement {
       } catch (e) {
       }
       if (this.hasShadowRoot) {
-        if (this.shadowRoot) {
-          const existing = this.shadowRoot.adoptedStyleSheets || [];
-          if (!existing.includes(wjSkeletonSheet) && wjSkeletonSheet.cssRules !== void 0) {
-            this.shadowRoot.adoptedStyleSheets = [...existing, wjSkeletonSheet];
-          }
-        }
         this.shadowRoot.replaceChildren(frag);
       } else {
         this.replaceChildren(frag);
@@ -874,7 +716,10 @@ const _WJElement = class _WJElement extends HTMLElement {
     return { hasGetter: null, hasSetter: null };
   }
   /**
-   * Sets up property accessors for the component's attributes.
+   * Sets up accessors (getter and setter) for all attributes of the current object.
+   * This method retrieves the attribute names, sanitizes them, and dynamically defines
+   * property accessors for each attribute using `Object.defineProperty`.
+   * @returns {void} This method does not return any value.
    */
   setUpAccessors() {
     let attrs = this.getAttributeNames();