zs3-ui-components 1.2.2 → 1.2.3

package/README.md

@@ -1,6 +1,6 @@
 # ZS3 UI Components
 
-**v1.2.2** · Modern Web Components library with built-in theming, i18n, reactive state, HTTP client, and more.
+**v1.2.3** · 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.2' })
+log.info('Aplicació iniciada', { version: '1.2.3' })
 log.warn('Configuració incompleta', { missing: 'api-key' })
 log.error('Error en la petició', { code: 500, url: '/api/users' })
 log.success('Operació completada!')
@@ -2096,6 +2096,30 @@ class MyComponent extends $BaseComponent {
 > **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`.
 
+#### `this.$$` — Selecció múltiple scope-aware dins de components
+
+Tots els components que extenen `$BaseComponent` també disposen de `this.$$`, que retorna un array
+de tots els elements que coincideixen amb el selector, limitat al **shadow DOM del component**.
+
+```ts
+class MyComponent extends $BaseComponent {
+    render(): void {
+        this.setHTML(`
+            <button class="item">A</button>
+            <button class="item">B</button>
+        `)
+    }
+
+    protected afterMount(): void {
+        // Selecciona tots els elements .item dins del shadow DOM
+        this.$$('.item')?.forEach(el => el.classList.add('active'))
+        this.$$('input')?.forEach(input => (input as HTMLInputElement).disabled = true)
+    }
+}
+```
+
+> **Nota:** `this.$$` és equivalent a `$(selector, this.shadowRoot).$$`.
+
 #### HTML inline (index2.html)
 
 ```html
@@ -2174,7 +2198,6 @@ class MyComponent extends $BaseComponent {
     }
 
     // Es crida automàticament quan canvia l'idioma
-    // render() s'invoca automàticament després
     protected onLocaleChange(): void {
         // lògica addicional si cal
     }

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

@@ -123,6 +123,24 @@ export declare abstract class $BaseComponent extends HTMLElement {
      * this.$('.title')?.text(this.t('my.title.key'))
      */
     $: (selector: string) => ZS3 | null;
+    /**
+     * Helper DOM scope-aware que retorna múltiples elements dins del shadow DOM del component.
+     *
+     * Equivalent a `$(selector, root).$$` 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 tots els elements interns que coincideixen amb el selector, de forma segura
+     * sense accedir al `document` global.
+     *
+     * @param selector - Selector CSS per cercar dins del shadow DOM del component.
+     * @returns Array d'elements `HTMLElement` que coincideixen, o `null` si no en troba cap.
+     *
+     * @example
+     * // Dins d'un mètode del component:
+     * this.$$('.item')?.forEach(el => el.classList.add('active'))
+     * this.$$('input')?.forEach(input => (input as HTMLInputElement).disabled = true)
+     */
+    $$: (selector: string) => Array<HTMLElement> | null;
     /**
      * Initializes the base component
      * @param options - Configuration options for the component
@@ -137,18 +155,6 @@ export declare abstract class $BaseComponent extends HTMLElement {
      * Get the root element (shadow root or element itself)
      */
     protected get root(): ShadowRoot | HTMLElement;
-    /**
-     * Query selector within the component's root
-     * @param selector - CSS selector to query
-     * @returns Found element or null
-     */
-    protected qs<T extends HTMLElement = HTMLElement>(selector: string): T | null;
-    /**
-     * Query all matching elements within the component's root
-     * @param selector - CSS selector to query
-     * @returns NodeList of found elements
-     */
-    protected qsAll<T extends HTMLElement = HTMLElement>(selector: string): NodeListOf<T>;
     /**
      * Register an attribute change handler
      * @param attributeName - Name of the attribute to observe