wj-elements 0.1.255 → 0.2.0-alpha.10

package/dist/wje-element.js

@@ -15,8 +15,201 @@ 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.
@@ -44,10 +237,18 @@ const _WJElement = class _WJElement extends HTMLElement {
         }
         this.setUpAccessors();
         __privateSet(this, _drawingStatus, this.drawingStatuses.START);
-        await this.display(force);
         const sheet = new CSSStyleSheet();
         sheet.replaceSync(this.constructor.cssStyleSheet);
-        this.context.adoptedStyleSheets = [sheet];
+        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;
+        }
+        await this.display(force);
         resolve();
       });
     });
@@ -223,8 +424,9 @@ const _WJElement = class _WJElement extends HTMLElement {
    * Defines component dependencies by registering custom elements.
    */
   defineDependencies() {
-    if (this.dependencies)
-      Object.entries(this.dependencies).forEach((name, component) => _WJElement.define(name, component));
+    if (this.dependencies) {
+      Object.entries(this.dependencies).forEach(([name, component]) => _WJElement.define(name, component));
+    }
   }
   /**
    * Hook for extending behavior before drawing the component.
@@ -263,6 +465,81 @@ const _WJElement = class _WJElement extends HTMLElement {
    */
   afterDraw(context, appStoreObj, params) {
   }
+  /**
+   * Optional hook: return skeleton markup used while async draw is in progress.
+   * Prefer declarative skeleton via `<div slot="skeleton">...</div>`.
+   * Return: string | Node | DocumentFragment | null | Promise of those.
+   */
+  renderSkeleton(params) {
+    return null;
+  }
+  /**
+   * 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.
+   * 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;
+    const v = this.getAttribute("skeleton-delay");
+    const n = v == null ? NaN : Number(v);
+    if (Number.isFinite(n)) return n;
+    if (Number.isFinite(this.skeletonDelayMs)) return this.skeletonDelayMs;
+    return 150;
+  }
+  /**
+   * Retrieves the minimum duration for the skeleton animation.
+   * The method checks for an internally stored finite value. If unavailable,
+   * it retrieves the value from the 'skeleton-min-duration' attribute,
+   * converts it to a number if possible, and uses it. If neither is valid,
+   * a default duration of 300 is returned.
+   * @returns {number} The minimum duration for the skeleton animation in milliseconds.
+   */
+  get skeletonMinDuration() {
+    if (Number.isFinite(this._wjSkeletonSlotClone)) return this._wjSkeletonSlotClone;
+    const v = this.getAttribute("skeleton-min-duration");
+    const n = v == null ? NaN : Number(v);
+    if (Number.isFinite(n)) return n;
+    return 300;
+  }
+  set skeletonMinDuration(value) {
+    if (value === null || value === void 0 || value === "") {
+      delete this._wjSkeletonSlotClone;
+      this.removeAttribute("skeleton-min-duration");
+      return;
+    }
+    const n = Number(value);
+    if (Number.isFinite(n)) {
+      this._wjSkeletonSlotClone = n;
+      this.setAttribute("skeleton-min-duration", String(n));
+    }
+  }
+  // Public API: property-based control
+  set skeleton(value) {
+    if (value) this.setAttribute("skeleton", "");
+    else this.removeAttribute("skeleton");
+  }
+  get skeleton() {
+    return this.hasAttribute("skeleton");
+  }
+  set skeletonDelay(value) {
+    if (value === null || value === void 0 || value === "") {
+      delete this._wjSkeletonSlotClone;
+      this.removeAttribute("skeleton-delay");
+      return;
+    }
+    const n = Number(value);
+    if (Number.isFinite(n)) {
+      this._wjSkeletonSlotClone = n;
+      this.setAttribute("skeleton-delay", String(n));
+    }
+  }
+  get skeletonDelayValue() {
+    return this.skeletonDelay;
+  }
   /**
    * Lifecycle method invoked when the component is connected to the DOM.
    */
@@ -386,22 +663,157 @@ const _WJElement = class _WJElement extends HTMLElement {
    */
   display(force = false) {
     this.template = this.constructor.customTemplate || document.createElement("template");
-    if (force) {
-      [...this.context.childNodes].forEach(this.context.removeChild.bind(this.context));
-    }
-    this.context.append(this.template.content.cloneNode(true));
+    const nextContext = document.createDocumentFragment();
+    nextContext.append(this.template.content.cloneNode(true));
     if (this.noShow || this.isPermissionCheck && !Permissions.isPermissionFulfilled(this.permission)) {
       this.remove();
       return Promise.resolve();
     }
-    return __privateMethod(this, _WJElement_instances, resolveRender_fn).call(this);
+    let skeletonTimer = null;
+    let renderFinished = false;
+    let skeletonShownAt = null;
+    const clearSkeletonTimer = () => {
+      if (skeletonTimer) {
+        clearTimeout(skeletonTimer);
+        skeletonTimer = null;
+      }
+    };
+    const buildSkeletonFragment = async () => {
+      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) {
+        const frag2 = document.createDocumentFragment();
+        frag2.append(this._wjSkeletonSlotClone.cloneNode(true));
+        return frag2;
+      }
+      const frag = document.createDocumentFragment();
+      let skel = (_a = this.renderSkeleton) == null ? void 0 : _a.call(this, WjElementUtils.getAttributes(this));
+      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;
+      let node;
+      if (skel instanceof HTMLElement || skel instanceof DocumentFragment) {
+        node = skel;
+      } else {
+        const t = document.createElement("template");
+        t.innerHTML = skel;
+        node = t.content.cloneNode(true);
+      }
+      frag.append(node);
+      return frag;
+    };
+    const showSkeleton = async () => {
+      if (renderFinished) return;
+      if (!this.hasAttribute("skeleton")) return;
+      const frag = await buildSkeletonFragment();
+      if (!frag) return;
+      try {
+        const cs = getComputedStyle(this);
+        if (cs.display === "inline") this.style.display = "block";
+        if (cs.width === "0px") this.style.width = "100%";
+      } 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);
+      }
+      skeletonShownAt = performance.now();
+      this.dispatchEvent(new CustomEvent("wj:skeleton:show", {
+        detail: { delay: this.skeletonDelay },
+        bubbles: true,
+        composed: true
+      }));
+      if (this.hasAttribute("debug-skeleton")) {
+        debugger;
+      }
+    };
+    if (this.hasAttribute("skeleton") && this.style.visibility === "hidden") {
+      this.style.visibility = __privateGet(this, _originalVisibility) ?? "visible";
+    }
+    let skeletonPlannedAt;
+    if (this.hasAttribute("skeleton")) {
+      skeletonPlannedAt = performance.now();
+      skeletonTimer = setTimeout(() => {
+        showSkeleton();
+      }, this.skeletonDelay);
+    }
+    return __privateMethod(this, _WJElement_instances, resolveRender_fn).call(this, nextContext, { skipAfterDraw: true }).then(async () => {
+      var _a;
+      renderFinished = true;
+      clearSkeletonTimer();
+      if (skeletonShownAt === null) {
+        const elapsed = skeletonPlannedAt ? performance.now() - skeletonPlannedAt : 0;
+        this.dispatchEvent(new CustomEvent("wj:skeleton:skip", {
+          detail: { reason: "render-finished-fast", elapsedMs: elapsed, delay: this.skeletonDelay },
+          bubbles: true,
+          composed: true
+        }));
+      } else {
+        const now = performance.now();
+        const visibleFor = now - skeletonShownAt;
+        const remaining = this.skeletonMinDuration - visibleFor;
+        if (remaining > 0) {
+          await new Promise((r) => setTimeout(r, remaining));
+        }
+      }
+      if (this.hasShadowRoot) {
+        this.shadowRoot.replaceChildren(nextContext);
+      } else {
+        this.replaceChildren(nextContext);
+      }
+      if (skeletonShownAt !== null) {
+        this.dispatchEvent(new CustomEvent("wj:skeleton:hide", {
+          detail: {
+            reason: "render-finished",
+            visibleMs: Math.max(this.skeletonMinDuration, performance.now() - skeletonShownAt),
+            delay: this.skeletonDelay,
+            minDuration: this.skeletonMinDuration
+          },
+          bubbles: true,
+          composed: true
+        }));
+      }
+      const liveContext = this.hasShadowRoot ? this.shadowRoot : this;
+      const _afterDraw = (_a = this.afterDraw) == null ? void 0 : _a.call(this, liveContext, this.store, WjElementUtils.getAttributes(this));
+      if (_afterDraw instanceof Promise || (_afterDraw == null ? void 0 : _afterDraw.constructor.name) === "Promise") {
+        await _afterDraw;
+      }
+    }).finally(() => {
+      renderFinished = true;
+      clearSkeletonTimer();
+      if (!__privateGet(this, _isRendering)) {
+        this.dispatchEvent(new CustomEvent("wj:skeleton:hide", {
+          detail: { reason: "finally" },
+          bubbles: true,
+          composed: true
+        }));
+      }
+    });
   }
   /**
-   * Renders the component's content.
+   * Renders the content into the provided target context.
+   * This method handles asynchronous rendering, processes the output from the `draw` method,
+   * and appends the resulting content to the specified target context.
+   * @returns {Promise<void>} A promise that resolves once the render operation is complete and the content is appended to the target context.
+   * @param targetContext
    */
-  async render() {
+  async render(targetContext = this.context) {
     __privateSet(this, _drawingStatus, this.drawingStatuses.DRAWING);
-    let _draw = this.draw(this.context, this.store, WjElementUtils.getAttributes(this));
+    let _draw = this.draw(targetContext, this.store, WjElementUtils.getAttributes(this));
     if (_draw instanceof Promise || (_draw == null ? void 0 : _draw.constructor.name) === "Promise") {
       _draw = await _draw;
     }
@@ -415,7 +827,7 @@ const _WJElement = class _WJElement extends HTMLElement {
       element = inputTemplate.content.cloneNode(true);
     }
     let rendered = element;
-    this.context.appendChild(rendered);
+    targetContext.appendChild(rendered);
   }
   /**
    * Sanitizes a given name by converting it from kebab-case to camelCase.
@@ -524,22 +936,25 @@ refresh_fn = async function() {
   }
 };
 /**
- * Resolves the rendering process of the component.
+ * Resolves the rendering process of the component, using the given target context.
+ * @param {HTMLElement|ShadowRoot|DocumentFragment} targetContext Target for rendering (defaults to this.context)
  * @returns A promise that resolves when rendering is complete.
  * @private
  */
-resolveRender_fn = function() {
+resolveRender_fn = function(targetContext = this.context, { skipAfterDraw = false } = {}) {
   this.params = WjElementUtils.getAttributes(this);
   return new Promise(async (resolve, reject) => {
     var _a;
-    const __beforeDraw = this.beforeDraw(this.context, this.store, WjElementUtils.getAttributes(this));
-    if (__beforeDraw instanceof Promise || (__beforeDraw == null ? void 0 : __beforeDraw.constructor.name) === "Promise") {
-      await __beforeDraw;
+    const _beforeDraw = this.beforeDraw(targetContext, this.store, WjElementUtils.getAttributes(this));
+    if (_beforeDraw instanceof Promise || (_beforeDraw == null ? void 0 : _beforeDraw.constructor.name) === "Promise") {
+      await _beforeDraw;
     }
-    await this.render();
-    const __afterDraw = (_a = this.afterDraw) == null ? void 0 : _a.call(this, this.context, this.store, WjElementUtils.getAttributes(this));
-    if (__afterDraw instanceof Promise || (__afterDraw == null ? void 0 : __afterDraw.constructor.name) === "Promise") {
-      await __afterDraw;
+    await this.render(targetContext);
+    if (!skipAfterDraw) {
+      const _afterDraw = (_a = this.afterDraw) == null ? void 0 : _a.call(this, targetContext, this.store, WjElementUtils.getAttributes(this));
+      if (_afterDraw instanceof Promise || (_afterDraw == null ? void 0 : _afterDraw.constructor.name) === "Promise") {
+        await _afterDraw;
+      }
     }
     __privateSet(this, _isRendering, false);
     __privateSet(this, _isAttached, true);