zs3-ui-components 1.2.0 → 1.2.2

package/README.md

@@ -1,6 +1,6 @@
 # ZS3 UI Components
 
-**v1.2.0** · Modern Web Components library with built-in theming, i18n, reactive state, HTTP client, and more.
+**v1.2.2** · Modern Web Components library with built-in theming, i18n, reactive state, HTTP client, and more.
 
 ZS3 UI Components is a zero-dependency UI library based on native **Web Components** (Custom Elements + Shadow DOM). It provides a complete set of UI components and utilities that work in any framework or in plain HTML.
 
@@ -1984,7 +1984,7 @@ Logger avançat amb nivells i formatació a la consola del navegador.
 ```ts
 import { log } from 'zs3-ui-components'
 
-log.info('Aplicació iniciada', { version: '1.2.0' })
+log.info('Aplicació iniciada', { version: '1.2.2' })
 log.warn('Configuració incompleta', { missing: 'api-key' })
 log.error('Error en la petició', { code: 500, url: '/api/users' })
 log.success('Operació completada!')
@@ -2055,6 +2055,8 @@ window.diHasDemo = () => {
 
 Helper per seleccionar i manipular elements del DOM.
 
+#### `$` global
+
 ```ts
 import { $ } from 'zs3-ui-components'
 
@@ -2067,6 +2069,33 @@ $('#my-element')?.text('Nou contingut')
 $('#my-element')?.attr('aria-label', 'Descripció')
 ```
 
+#### `this.$` — Helper scope-aware dins de components
+
+Tots els components que extenen `$BaseComponent` disposen de la propietat `this.$`, que és
+una versió de `$` vinculada automàticament al **shadow DOM del component** (o al `_container`
+si el component s'usa com a pàgina via Router).
+
+Permet seleccionar elements interns del component sense risc de col·lisió amb altres components
+o amb el `document` global, ja que la cerca queda limitada a l'arbre intern del component.
+
+```ts
+class MyComponent extends $BaseComponent {
+    render(): void {
+        this.setHTML(`<button class="my-btn">Click</button>`)
+    }
+
+    protected afterMount(): void {
+        // Cerca limitada al shadow DOM d'aquest component
+        this.$('.my-btn')?.addClass('active')
+        this.$('input')?.value('valor inicial')
+        this.$('.title')?.text(this.t('my.title.key'))
+    }
+}
+```
+
+> **Nota:** `this.$` és equivalent a `$(selector, this.shadowRoot)`. Usar `$` global des de dins
+> d'un component amb shadow DOM **no funcionaria**, ja que el shadow DOM no és accessible des del `document`.
+
 #### HTML inline (index2.html)
 
 ```html

package/dist/components/zs3-BaseComponent.d.ts

@@ -1,3 +1,4 @@
+import { ZS3 } from '../zs3';
 /**
  * Opcions per al mètode emit
  */
@@ -101,6 +102,27 @@ export declare abstract class $BaseComponent extends HTMLElement {
      * @example this._moveDragSelector = '.title-bar' // per zs3-window
      */
     protected _moveDragSelector: string | null;
+    /**
+     * Helper DOM scope-aware basat en la funció `$` de ZS3.
+     *
+     * Equivalent a `$(selector)` però limitat al shadow DOM del component (o al `_container`
+     * si el component s'usa com a pàgina via Router sense shadow DOM).
+     *
+     * Permet seleccionar elements interns del component de forma segura sense haver d'accedir
+     * al `document` global, evitant col·lisions amb altres components o el document principal.
+     *
+     * Retorna una instància de `ZS3` amb l'API encadenada, o `null` si el selector no troba res.
+     *
+     * @param selector - Selector CSS per cercar dins del shadow DOM del component.
+     * @returns Instància `ZS3` amb l'element seleccionat, o `null` si no existeix.
+     *
+     * @example
+     * // Dins d'un mètode del component:
+     * this.$('.my-button')?.addClass('active')
+     * this.$('input')?.value('nou valor')
+     * this.$('.title')?.text(this.t('my.title.key'))
+     */
+    $: (selector: string) => ZS3 | null;
     /**
      * Initializes the base component
      * @param options - Configuration options for the component

package/dist/index.js

@@ -14,7 +14,7 @@ class T {
    * @returns {string} Library version.
    */
   static version() {
-    return "1.2.0";
+    return "1.2.2";
   }
   /**
    * Creates a ZS3 instance from an HTMLElement.
@@ -427,7 +427,7 @@ class T {
     return this.list[0]?.cloneNode(t) ?? null;
   }
 }
-const J = (e, t) => e != null && e.length > 0 ? new T(e, t) : null, $e = () => ({
+const Y = (e, t) => e != null && e.length > 0 ? new T(e, t) : null, $e = () => ({
   userAgent: navigator.userAgent,
   language: navigator.language,
   platform: navigator.platform,
@@ -453,16 +453,16 @@ class Et {
   constructor() {
     this.start = (t, s, i = document) => {
       const r = `${t}:${s}`, o = this.debugging.get(r) ?? [];
-      o.some((c) => c.root === i) || (J(t, i)?.addEvent(s, this.doDebug), o.push({ selector: t, eventType: s, root: i }), this.debugging.set(r, o));
+      o.some((c) => c.root === i) || (Y(t, i)?.addEvent(s, this.doDebug), o.push({ selector: t, eventType: s, root: i }), this.debugging.set(r, o));
     }, this.stop = (t, s, i = document) => {
       const r = `${t}:${s}`, o = this.debugging.get(r);
       if (!o) return;
       const a = o.findIndex((c) => c.root === i);
-      a !== -1 && (J(t, i)?.removeEvent(s, this.doDebug), o.splice(a, 1), o.length === 0 && this.debugging.delete(r));
+      a !== -1 && (Y(t, i)?.removeEvent(s, this.doDebug), o.splice(a, 1), o.length === 0 && this.debugging.delete(r));
     }, this.stopAll = () => {
       this.debugging.forEach((t) => {
         t.forEach(({ selector: s, eventType: i, root: r }) => {
-          J(s, r)?.removeEvent(i, this.doDebug);
+          Y(s, r)?.removeEvent(i, this.doDebug);
         });
       }), this.debugging.clear();
     }, this.doDebug = (t) => {
@@ -646,7 +646,7 @@ class Ae {
   }
 }
 const Mt = new xt(), Lt = new Et(), lt = new _t(), X = new Tt();
-typeof window < "u" && (window.$ = J, window.log = lt, window.debug = Lt, window.storage = X, window.params = Mt);
+typeof window < "u" && (window.$ = Y, window.log = lt, window.debug = Lt, window.storage = X, window.params = Mt);
 window.addEventListener("load", () => {
   lt.success("ZS3 v" + T.version() + " loaded");
 });
@@ -962,7 +962,7 @@ class At {
   }
 }
 const He = new At();
-class Oe {
+class Re {
   /**
    * Crea una nova instància del Router.
    *
@@ -1494,7 +1494,7 @@ class U extends Error {
     return this.status === 408 || this.message.includes("timeout");
   }
 }
-class Re {
+class Oe {
   constructor(t = {}) {
     this.requestInterceptors = [], this.responseInterceptors = [], this.errorInterceptors = [], this.baseUrl = (t.baseUrl ?? "").replace(/\/+$/, ""), this.defaultTimeout = t.timeout ?? 1e4, this.defaultRetries = t.retries ?? 0, this.defaultRetryDelay = t.retryDelay ?? 1e3, this.defaultHeaders = {
       "Content-Type": "application/json",
@@ -1684,7 +1684,7 @@ const Pt = (e, t = {}) => {
     }
   e.dispatchEvent(r);
 }, Ht = (e, t, s, i, r, o) => {
-  const a = Ot(t, s, i, r), c = r, l = e, m = () => {
+  const a = Rt(t, s, i, r), c = r, l = e, m = () => {
     switch (st(e, "zs3-float-show-start", t), l._floatIsShown = !0, t) {
       case "top":
         e.style.top = `${c}px`;
@@ -1722,7 +1722,7 @@ const Pt = (e, t = {}) => {
     }, o * 1e3);
   }, g = l._floatShowHandler, p = l._floatHideHandler;
   g && e.removeEventListener("mouseenter", g), p && e.removeEventListener("mouseleave", p), l._floatShowHandler = m, l._floatHideHandler = b, e.addEventListener("mouseenter", m), e.addEventListener("mouseleave", b);
-}, Ot = (e, t, s, i) => {
+}, Rt = (e, t, s, i) => {
   switch (e) {
     case "top":
     case "bottom":
@@ -1731,7 +1731,7 @@ const Pt = (e, t = {}) => {
     case "right":
       return -t.width * s + i;
   }
-}, W = (e, t, s) => {
+}, J = (e, t, s) => {
   const i = new CustomEvent(t, {
     detail: s,
     bubbles: !0,
@@ -1744,7 +1744,7 @@ const Pt = (e, t = {}) => {
       console.error(`Error executing ${t} attribute:`, o);
     }
   e.dispatchEvent(i);
-}, Rt = (e) => {
+}, Ot = (e) => {
   const { container: t, dragHandle: s = t, direction: i = "xy" } = e;
   if (!t)
     return console.warn("move: container is required"), null;
@@ -1757,7 +1757,7 @@ const Pt = (e, t = {}) => {
     if (S.button !== 0) return;
     a = !0, c = S.clientX, l = S.clientY;
     const et = window.getComputedStyle(t);
-    m = parseFloat(et.left) || 0, b = parseFloat(et.top) || 0, g = m, p = b, $.clear(), t.classList.add("zs3-dragging"), s.style.cursor = "grabbing", S.preventDefault(), W(t, "zs3-move-start", {
+    m = parseFloat(et.left) || 0, b = parseFloat(et.top) || 0, g = m, p = b, $.clear(), t.classList.add("zs3-dragging"), s.style.cursor = "grabbing", S.preventDefault(), J(t, "zs3-move-start", {
       direction: i,
       element: t,
       startX: m,
@@ -1769,14 +1769,14 @@ const Pt = (e, t = {}) => {
     let B = m + et, F = b + wt;
     const pt = ht.width - ut.width, mt = ht.height - ut.height, N = /* @__PURE__ */ new Set();
     B <= 0 && (B = 0, N.add("left")), B >= pt && (B = pt, N.add("right")), F <= 0 && (F = 0, N.add("top")), F >= mt && (F = mt, N.add("bottom")), N.forEach((ft) => {
-      $.has(ft) || W(t, "zs3-move-boundary", {
+      $.has(ft) || J(t, "zs3-move-boundary", {
         direction: i,
         element: t,
         x: B,
         y: F,
         boundary: ft
       });
-    }), $ = N, (i === "x" || i === "xy") && (t.style.left = `${B}px`, g = B), (i === "y" || i === "xy") && (t.style.top = `${F}px`, p = F), W(t, "zs3-move", {
+    }), $ = N, (i === "x" || i === "xy") && (t.style.left = `${B}px`, g = B), (i === "y" || i === "xy") && (t.style.top = `${F}px`, p = F), J(t, "zs3-move", {
       direction: i,
       element: t,
       x: g,
@@ -1785,14 +1785,14 @@ const Pt = (e, t = {}) => {
       deltaY: p - b
     });
   }, q = () => {
-    a && (a = !1, t.classList.remove("zs3-dragging"), s.style.cursor = "grab", W(t, "zs3-move-end", {
+    a && (a = !1, t.classList.remove("zs3-dragging"), s.style.cursor = "grab", J(t, "zs3-move-end", {
       direction: i,
       element: t,
       endX: g,
       endY: p
     }), document.removeEventListener("mousemove", D), document.removeEventListener("mouseup", q), document.removeEventListener("keydown", j));
   }, j = (S) => {
-    S.key === "Escape" && a && (a = !1, t.classList.remove("zs3-dragging"), s.style.cursor = "grab", (i === "x" || i === "xy") && (t.style.left = `${m}px`), (i === "y" || i === "xy") && (t.style.top = `${b}px`), W(t, "zs3-move-cancel", {
+    S.key === "Escape" && a && (a = !1, t.classList.remove("zs3-dragging"), s.style.cursor = "grab", (i === "x" || i === "xy") && (t.style.left = `${m}px`), (i === "y" || i === "xy") && (t.style.top = `${b}px`), J(t, "zs3-move-cancel", {
       direction: i,
       element: t
     }), document.removeEventListener("mousemove", D), document.removeEventListener("mouseup", q), document.removeEventListener("keydown", j));
@@ -1831,7 +1831,7 @@ class k extends HTMLElement {
       slotAssignment: this._options.slotAssignment,
       clonable: this._options.clonable,
       serializable: this._options.serializable
-    })), this.initialize(), this.emitLifecycleEvent("zs3-built", { phase: "complete" });
+    })), this.initialize(), this.emitLifecycleEvent("zs3-built", { phase: "complete" }), this.$ = (s) => Y(s, this.shadowRoot ?? this._container ?? void 0);
   }
   /**
    * Initialize component (called in constructor)
@@ -1909,7 +1909,7 @@ class k extends HTMLElement {
       "log",
       "window",
       b
-    ).call(this, l, s, J, lt, window), m;
+    ).call(this, l, s, Y, lt, window), m;
   }
   /**
    * Emit lifecycle event (internal use)
@@ -1985,7 +1985,7 @@ class k extends HTMLElement {
     const t = this.getAttribute("move"), s = this._moveContainerSelector === ":host" ? this : this.qs(this._moveContainerSelector);
     if (!s) return;
     let i;
-    this._moveDragSelector ? i = this._moveDragSelector === ":host" ? this : this.qs(this._moveDragSelector) : i = s, i && (t && ["x", "y", "xy"].includes(t) ? Rt({ container: s, dragHandle: i, direction: t }) : Bt(i));
+    this._moveDragSelector ? i = this._moveDragSelector === ":host" ? this : this.qs(this._moveDragSelector) : i = s, i && (t && ["x", "y", "xy"].includes(t) ? Ot({ container: s, dragHandle: i, direction: t }) : Bt(i));
   }
   /**
    * Request an animation frame update
@@ -2107,7 +2107,7 @@ class k extends HTMLElement {
    */
   handleLocaleChange(t) {
     const s = t;
-    this.onLocaleChange(s.detail.locale), this._mounted && (this.render(), this.applyFloatEffect(), this.applyMoveEffect());
+    this.onLocaleChange(s.detail.locale);
   }
   /**
    * Hook called when locale changes
@@ -3681,7 +3681,7 @@ u = w([
 ], u);
 customElements.get("zs3-form") || customElements.define("zs3-form", u);
 typeof window < "u" && (window.$Form = u);
-var Zt = Object.defineProperty, te = Object.getOwnPropertyDescriptor, Y = (e, t, s, i) => {
+var Zt = Object.defineProperty, te = Object.getOwnPropertyDescriptor, W = (e, t, s, i) => {
   for (var r = i > 1 ? void 0 : i ? te(t, s) : t, o = e.length - 1, a; o >= 0; o--)
     (a = e[o]) && (r = (i ? a(t, s, r) : a(r)) || r);
   return i && r && Zt(t, s, r), r;
@@ -3755,22 +3755,22 @@ let H = class extends u {
     }), e.appendChild(t), this._buttons.push(t);
   }
 };
-Y([
+W([
   n("show-register", { type: "boolean" })
 ], H.prototype, "showRegister", 2);
-Y([
+W([
   n("login-text", { type: "string" })
 ], H.prototype, "loginText", 2);
-Y([
+W([
   n("register-text", { type: "string" })
 ], H.prototype, "registerText", 2);
-Y([
+W([
   n("i18n-login-text", { type: "string" })
 ], H.prototype, "i18nLoginText", 2);
-Y([
+W([
   n("i18n-register-text", { type: "string" })
 ], H.prototype, "i18nRegisterText", 2);
-H = Y([
+H = W([
   x("zs3-login-form"),
   E(ee, { inherit: !0 })
 ], H);
@@ -5331,7 +5331,7 @@ rt = yt([
   E(xe)
 ], rt);
 typeof window < "u" && (window.$SelectTheme = rt);
-var _e = Object.defineProperty, Te = Object.getOwnPropertyDescriptor, O = (e, t, s, i) => {
+var _e = Object.defineProperty, Te = Object.getOwnPropertyDescriptor, R = (e, t, s, i) => {
   for (var r = i > 1 ? void 0 : i ? Te(t, s) : t, o = e.length - 1, a; o >= 0; o--)
     (a = e[o]) && (r = (i ? a(t, s, r) : a(r)) || r);
   return i && r && _e(t, s, r), r;
@@ -5673,28 +5673,28 @@ let L = class extends k {
     });
   }
 };
-O([
+R([
   n("direction", { type: "string", default: "row" })
 ], L.prototype, "direction", 2);
-O([
+R([
   n("float", { type: "string" })
 ], L.prototype, "float", 2);
-O([
+R([
   n("align", { type: "string" })
 ], L.prototype, "align", 2);
-O([
+R([
   n("gap", { type: "string" })
 ], L.prototype, "gap", 2);
-O([
+R([
   n("variant", { type: "string" })
 ], L.prototype, "variant", 2);
-O([
+R([
   n("rounded", { type: "boolean" })
 ], L.prototype, "rounded", 2);
-O([
+R([
   n("i18n-aria-label", { type: "string" })
 ], L.prototype, "i18nAriaLabel", 2);
-L = O([
+L = R([
   x("zs3-toolbar"),
   E(Me),
   vt(".toolbar"),
@@ -5702,7 +5702,7 @@ L = O([
 ], L);
 customElements.get("zs3-toolbar") || customElements.define("zs3-toolbar", L);
 typeof window < "u" && (window.$Toolbar = L);
-var Le = Object.defineProperty, Ce = Object.getOwnPropertyDescriptor, R = (e, t, s, i) => {
+var Le = Object.defineProperty, Ce = Object.getOwnPropertyDescriptor, O = (e, t, s, i) => {
   for (var r = i > 1 ? void 0 : i ? Ce(t, s) : t, o = e.length - 1, a; o >= 0; o--)
     (a = e[o]) && (r = (i ? a(t, s, r) : a(r)) || r);
   return i && r && Le(t, s, r), r;
@@ -5879,28 +5879,28 @@ let C = class extends k {
     this.setAttribute("title", e);
   }
 };
-R([
+O([
   n("title", { type: "string" })
 ], C.prototype, "windowTitle", 2);
-R([
+O([
   n("width", { type: "string" })
 ], C.prototype, "width", 2);
-R([
+O([
   n("height", { type: "string" })
 ], C.prototype, "height", 2);
-R([
+O([
   n("closable", { type: "boolean" })
 ], C.prototype, "closable", 2);
-R([
+O([
   n("minimizable", { type: "boolean" })
 ], C.prototype, "minimizable", 2);
-R([
+O([
   n("maximizable", { type: "boolean" })
 ], C.prototype, "maximizable", 2);
-R([
+O([
   n("i18n-title", { type: "string" })
 ], C.prototype, "i18nTitle", 2);
-C = R([
+C = O([
   x("zs3-window"),
   E([
     "title",
@@ -5922,7 +5922,7 @@ C = R([
 customElements.get("zs3-window") || customElements.define("zs3-window", C);
 typeof window < "u" && (window.$Window = C);
 export {
-  J as $,
+  Y as $,
   k as $BaseComponent,
   f as $Button,
   Et as $Debug,
@@ -5950,11 +5950,11 @@ export {
   At as DIContainer,
   $t as EventBus,
   vt as Float,
-  Re as HttpClient,
+  Oe as HttpClient,
   U as HttpError,
   Ft as Move,
   E as ObservedAttributes,
-  Oe as Router,
+  Re as Router,
   Ct as ThemeChangeEvent,
   K as ThemeManager,
   T as ZS3,
@@ -5972,7 +5972,7 @@ export {
   bt as initThemeSystem,
   Be as isMoveEnabled,
   lt as log,
-  Rt as move,
+  Ot as move,
   Mt as params,
   Pe as setCSSVariable,
   X as storage,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zs3-ui-components",
-    "version": "1.2.0",
+    "version": "1.2.2",
     "type": "module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",