zs3-ui-components 1.1.11 → 1.2.0

package/README.md

@@ -1,35 +1,19 @@
 # ZS3 UI Components
 
-**Biblioteca de components web moderna amb sistema de temes, internacionalitzacio i suport per CSS variables.**
+**v1.2.0** · Modern Web Components library with built-in theming, i18n, reactive state, HTTP client, and more.
 
-| | |
-|------------|----------------------------------------------|
-| **Paquet** | `zs3-ui-components` |
-| **Versio** | 1.1.9 |
-| **Llicencia** | ISC |
-| **Autor** | Manuel Candeal |
-| **Repositori** | [github.com/manuelcandeal/zs3-ui-components](https://github.com/manuelcandeal/zs3-ui-components) |
-| **Tipus** | ES Module |
+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.
 
 ---
 
-## Taula de continguts
+## Table of Contents
 
-- [Installacio i importacions](#installacio-i-importacions)
-- [Classe ZS3 (`$`)](#classe-zs3-)
-- [Utilitats](#utilitats)
-  - [$Parameters (params)](#parameters-params)
-  - [$Log (log)](#log-log)
-  - [$Debug (debug)](#debug-debug)
-  - [$Storage (storage)](#storage-storage)
-  - [$Store](#store)
-  - [HttpClient](#httpclient)
-- [Sistema de Temes (ThemeManager)](#sistema-de-temes-thememanager)
-  - [CSS Variables](#css-variables)
-- [Internacionalitzacio ($I18n)](#internacionalitzacio-i18n)
-- [Bus d'Events (EventBus)](#bus-devents-eventbus)
-- [Contenidor de Dependencies (DIContainer)](#contenidor-de-dependencies-dicontainer)
-- [Router (SPA)](#router-spa)
+- [Features](#features)
+- [Installation](#installation)
+- [Dev Setup](#dev-setup)
+- [Two Usage Approaches](#two-usage-approaches)
+- [i18n — Internationalisation](#i18n--internationalisation)
+- [Theme System](#theme-system)
 - [Components](#components)
   - [zs3-button](#zs3-button)
   - [zs3-icon](#zs3-icon)
@@ -37,2749 +21,2186 @@
   - [zs3-notification](#zs3-notification)
   - [zs3-modal](#zs3-modal)
   - [zs3-modal-dialog](#zs3-modal-dialog)
-  - [zs3-window](#zs3-window)
   - [zs3-form](#zs3-form)
   - [zs3-login-form](#zs3-login-form)
   - [zs3-register-form](#zs3-register-form)
   - [zs3-recover-password-form](#zs3-recover-password-form)
-  - [zs3-select-theme](#zs3-select-theme)
+  - [zs3-window](#zs3-window)
   - [zs3-select-locale](#zs3-select-locale)
-- [Inline Event Handlers](#inline-event-handlers)
-- [Guia de desenvolupament de nous components](#guia-de-desenvolupament-de-nous-components)
-  - [$BaseComponent](#basecomponent)
-  - [Cicle de vida](#cicle-de-vida)
-  - [Metodes disponibles](#metodes-disponibles)
-- [Decoradors](#decoradors)
-- [Efecte Float](#efecte-float)
-- [Efecte Move](#efecte-move)
-- [Exemples complets](#exemples-complets)
-- [Estructura del projecte](#estructura-del-projecte)
-- [Suport i llicencia](#suport-i-llicencia)
+  - [zs3-select-theme](#zs3-select-theme)
+- [Utilities](#utilities)
+  - [$Store — Reactive State](#store--reactive-state)
+  - [EventBus](#eventbus)
+  - [$Storage — LocalStorage](#storage--localstorage)
+  - [HttpClient](#httpclient)
+  - [$Log — Logging](#log--logging)
+  - [DIContainer — Dependency Injection](#dicontainer--dependency-injection)
+  - [$ — DOM Helper](#--dom-helper)
+- [Decorators](#decorators)
+- [CSS Variables](#css-variables)
 
 ---
 
-## Installacio i importacions
+## Features
+
+- **Web Components natifs** — Shadow DOM, Custom Elements, cap dependència de framework
+- **i18n complet** — traduccions per clau, fallback, detecció de idioma del navegador, actualització automàtica de tots els components
+- **Temes** — light, dark, high-contrast, i temes personalitzats via CSS variables
+- **$Store** — gestió d'estat reactiva amb reducers i subscripcions (similar a Redux)
+- **EventBus** — comunicació desacoblada entre components
+- **HttpClient** — client HTTP amb interceptors, timeout i tipatge TypeScript
+- **DIContainer** — contenidor d'injecció de dependències
+- **$Storage** — wrapper de LocalStorage amb serialització automàtica
+- **$Log** — logging avançat amb nivells i formatació
+- **$ Helper** — selecció i manipulació del DOM
+- **Formularis** — `$Form` genèric i `$LoginForm`, `$RegisterForm`, `$RecoverPasswordForm` preconstruïts
+
+---
 
-### Installacio
+## Installation
 
 ```bash
 npm install zs3-ui-components
 ```
 
-### Importacio global
-
-Importa tot el paquet (registra automaticament tots els custom elements):
+Importa els components i el CSS:
 
-```typescript
-import 'zs3-ui-components'
+```ts
+import 'zs3-ui-components'           // registra tots els Custom Elements
+import 'zs3-ui-components/dist/zs3.css'  // variables CSS i estils base
 ```
 
-### Importacio individual
+O importa selectivament:
 
-Importa nomes el que necessitis:
-
-```typescript
-// Utilitats
-import { $, params, log, debug, storage, $env } from 'zs3-ui-components'
+```ts
+import { $Button, $Form, $ModalDialog, i18n, $Store, themeManager } from 'zs3-ui-components'
+```
 
-// Sistema de temes
-import { themeManager, getCSSVariable, setCSSVariable, initThemeSystem } from 'zs3-ui-components'
+---
 
-// Internacionalitzacio
-import { i18n } from 'zs3-ui-components'
+## Dev Setup
 
-// Store (gestió d'estat global)
-import { $Store } from 'zs3-ui-components'
-import type { Listener, Reducer } from 'zs3-ui-components'
-
-// Bus d'events i contenidor de dependencies
-import { eventBus, EventBus, diContainer, DIContainer } from 'zs3-ui-components'
-
-// Router SPA
-import { Router } from 'zs3-ui-components'
-import type { Route, RouteGuard, RouteContext } from 'zs3-ui-components'
-
-// Components (classes)
-import {
-    $Button,
-    $Icon,
-    $Toolbar,
-    $Notification,
-    $Modal,
-    $ModalDialog,
-    $Window,
-    $Form,
-    $LoginForm,
-    $RegisterForm,
-    $RecoverPasswordForm,
-    $SelectTheme,
-    $SelectLocale,
-} from 'zs3-ui-components'
-
-// Efectes
-import { float, move, disableMove, isMoveEnabled, getMoveDirection } from 'zs3-ui-components'
-
-// Base component i decoradors (per crear nous components)
-import { $BaseComponent, Component, ObservedAttributes, Float, Move, Attr } from 'zs3-ui-components'
-
-// Tipus
-import type {
-    ThemeType,
-    I18nConfig,
-    EventDescription,
-    BaseComponentOptions,
-    AttributeChangeCallback,
-    FloatPosition,
-    FloatConfig,
-    FloatEventDetail,
-    MoveDirection,
-    MoveConfig,
-    MoveBoundary,
-    MoveEventDetail,
-    ButtonConfig,
-    IconConfig,
-    ToolbarConfig,
-    NotificationConfig,
-    NotificationPosition,
-    NotificationType,
-    ModalConfig,
-    ModalSize,
-    ModalDialogConfig,
-    DialogAction,
-    WindowConfig,
-    FormFieldType,
-    FormFieldOption,
-    FormFieldValidation,
-    FormFieldConfig,
-    FormConfig,
-    ValidationResult,
-} from 'zs3-ui-components'
+```bash
+git clone https://github.com/your-org/zs3-ui-components
+cd zs3-ui-components
+npm install
+npm run dev        # servidor de dev a http://localhost:5173
+npm run build      # build de la llibreria a dist/
+npm run lint       # ESLint + stylelint
 ```
 
----
-
-## Classe ZS3 (`$`)
+El directori `dev/` conté tres pàgines de demo:
 
-La classe `ZS3` proporciona una API similar a jQuery per a la manipulacio d'elements DOM.
+| Pàgina | Descripció |
+|--------|------------|
+| `dev/index.html` | Demo original (layout amb navegació) |
+| `dev/index2.html` | **Demo completa** — HTML inline + JavaScript |
+| `dev/index3.html` | **Demo completa** — tot creat des de TypeScript |
 
-### Selectors
+---
 
-```typescript
-// Seleccionar elements amb la funcio $
-const element = $('selector')            // Retorna ZS3 | null (cerca des de document)
-const element = $('selector', rootEl)    // Cerca dins d'un HTMLElement, Document o ShadowRoot
-const element = new ZS3('selector')      // Constructor directe (cerca des de document)
-const element = new ZS3('selector', rootEl) // Constructor amb element arrel (HTMLElement, Document o ShadowRoot)
+## Two Usage Approaches
 
-// Crear ZS3 des d'un HTMLElement
-const zs3 = ZS3.fromElement(htmlElement)
-```
+ZS3 UI suporta dos estils d'ús que es poden combinar lliurement.
 
-El segon parametre (`root`) es opcional i per defecte es `document`. Accepta `Document`, `HTMLElement` o `ShadowRoot`, la qual cosa permet limitar la cerca a un subarbre del DOM concret, incloent shadow roots de Web Components:
+### Enfocament 1 — HTML Inline (`index2.html` / `index2.ts`)
 
-```typescript
-const container = document.getElementById('app')
-const buttons = $('button', container) // Nomes els botons dins de #app
+Defineix els components directament a l'HTML. Útil quan treballes amb plantilles HTML, SSR o CMS.
 
-// Dins d'un Web Component (shadow DOM)
-const btn = $('button', this.root)  // this.root pot ser ShadowRoot o HTMLElement
-btn?.addEvent('click', handler)
+**`index2.html`:**
+```html
+<!doctype html>
+<html lang="ca">
+<head>
+    <meta charset="UTF-8" />
+    <title>Demo 2 — Inline</title>
+</head>
+<body>
+    <header>
+        <zs3-select-locale zs3-position="position:relative;"></zs3-select-locale>
+        <zs3-select-theme  zs3-position="position:relative;"></zs3-select-theme>
+    </header>
+
+    <!-- Component declarat en HTML -->
+    <zs3-button variant="primary" icon="save" position="left"
+        zs3-click="document.getElementById('out').textContent = 'Clicat!'">
+        Guardar
+    </zs3-button>
+    <div id="out"></div>
+
+    <!-- Modal declarat en HTML -->
+    <zs3-modal id="my-modal" size="medium" backdrop close-on-escape>
+        <div style="padding:1.5rem">
+            <h3>Modal</h3>
+            <p>Contingut del modal.</p>
+            <zs3-button variant="primary"
+                zs3-click="document.getElementById('my-modal').$.hide()">
+                Tancar
+            </zs3-button>
+        </div>
+    </zs3-modal>
+
+    <zs3-button zs3-click="document.getElementById('my-modal').$.show()">
+        Obrir modal
+    </zs3-button>
+
+    <script type="module" src="./src/js/index2.ts"></script>
+</body>
+</html>
 ```
 
-### Propietats
+**`index2.ts`** — inicialitza i18n, $Store, HttpClient, i exposa funcions globals:
+```ts
+import '../../../src/css/zs3.css'
+import { i18n, themeManager, log, storage, eventBus,
+         $Store, HttpClient, diContainer,
+         $ModalDialog, $Notification, $Icon } from '../../../src'
+import translations from '../../i18n/i18n.json'
 
-| Propietat | Tipus | Descripcio |
-|-----------|-------|------------|
-| `$` | `HTMLElement` | Primer element seleccionat |
-| `$$` | `HTMLElement[]` | Tots els elements seleccionats |
+// Inicialitza i18n
+i18n.loadMultiple(translations)
+i18n.init({ locale: 'ca', fallbackLocale: 'en' })
 
-### Metodes
+// Exposa funcions globals per als handlers inline de l'HTML
+window.showDialogAlert = async () => {
+    await $ModalDialog.alertI18n({
+        i18nTitle: 'section.dialog.alert.title',
+        i18nMessage: 'section.dialog.alert.message',
+    })
+}
 
-#### Contingut
+window.addEventListener('DOMContentLoaded', () => {
+    log.info('Demo 2 iniciada')
+    setupIconsGrid()
+})
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `html()` | `(content?: string) => ZS3 \| string` | Get/set innerHTML. Sense argument retorna el contingut HTML; amb argument l'estableix i retorna ZS3 per encadenar. |
-| `text()` | `(content?: string) => ZS3 \| string` | Get/set innerText. |
-| `content()` | `(cont?: string) => ZS3 \| string \| null` | Get/set textContent. |
+function setupIconsGrid(): void {
+    const grid = document.getElementById('icons-grid')
+    if (!grid) return
+    $Icon.getAvailableIcons().forEach((name) => {
+        const card = document.createElement('div')
+        card.className = 'demo-icon-card'
+        card.innerHTML = `<zs3-icon name="${name}" size="medium"></zs3-icon><span>${name}</span>`
+        card.addEventListener('click', () =>
+            $Notification.info(`Icona: ${name}`, { position: 'bottom-right', duration: 2000 })
+        )
+        grid.appendChild(card)
+    })
+}
+```
 
-#### Visibilitat i estat
+### Enfocament 2 — TypeScript Programàtic (`index3.html` / `index3.ts`)
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `hide()` | `() => ZS3` | Amaga els elements (`display: none`). Guarda el display original. |
-| `show()` | `() => ZS3` | Mostra els elements. Restaura el display original. |
-| `hidden()` | `() => boolean` | Retorna `true` si el primer element esta amagat. |
-| `visible()` | `() => boolean` | Retorna `true` si el primer element es visible. |
-| `disable()` | `() => ZS3` | Desactiva els elements (disabled + aria-disabled + classe .disabled). |
-| `enable()` | `() => ZS3` | Activa els elements. |
+Crea tots els components i la interfície des de TypeScript. Ideal per SPA, aplicacions dinàmiques o quan es vol control total sense HTML preescrit.
 
-#### Classes CSS
+**`index3.html`** — mínim:
+```html
+<!doctype html>
+<html lang="ca">
+<head>
+    <meta charset="UTF-8" />
+    <title>Demo 3 — TypeScript</title>
+</head>
+<body>
+    <div id="app"></div>
+    <script type="module" src="./src/js/index3.ts"></script>
+</body>
+</html>
+```
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `addClass()` | `(className: string) => ZS3` | Afegeix una classe CSS. |
-| `removeClass()` | `(className: string) => ZS3` | Elimina una classe CSS. |
-| `toggleClass()` | `(className: string) => ZS3` | Alterna una classe CSS. |
-| `hasClass()` | `(className: string) => boolean` | Verifica si el primer element te la classe. |
+**`index3.ts`** — construeix tota la UI programàticament:
+```ts
+import '../../../src/css/zs3.css'
+import { i18n, $Button, $Icon, $Form, $ModalDialog,
+         $Notification, $Store, HttpClient, eventBus,
+         storage, log, diContainer, themeManager,
+         $Modal, $Toolbar, $LoginForm, $RegisterForm,
+         $RecoverPasswordForm, $Window, $ } from '../../../src'
+import translations from '../../i18n/i18n.json'
 
-#### Events
+i18n.loadMultiple(translations)
+i18n.init({ locale: 'ca', fallbackLocale: 'en' })
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `addEvent()` | `(event: string, callback: (e: Event) => void) => ZS3` | Afegeix un event listener (capture: true). |
-| `removeEvent()` | `(event: string, callback: (e: Event) => void) => ZS3` | Elimina un event listener. |
-| `once()` | `(event: string, callback: (e: Event) => void) => ZS3` | Afegeix un listener que s'executa nomes una vegada. |
+// Helper per crear elements HTML tipats
+function el<K extends keyof HTMLElementTagNameMap>(
+    tag: K,
+    attrs: Record<string, string> = {},
+    ...children: (Node | string)[]
+): HTMLElementTagNameMap[K] {
+    const e = document.createElement(tag)
+    for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v)
+    for (const c of children) e.append(c)
+    return e
+}
 
-#### Valors i dimensions
+// Helper per crear botons
+function btn(text: string, variant?: string, icon?: string, position?: string): $Button {
+    const b = new $Button()
+    b.textContent = text
+    if (variant) b.variant = variant as $Button['variant']
+    if (icon) b.icon = icon
+    if (position) b.position = position as 'left' | 'right'
+    return b
+}
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `value()` | `(val?: string) => ZS3 \| string` | Get/set value per a inputs. |
-| `rect()` | `(n?: number) => DOMRect \| null` | Obte el bounding rect d'un element (per index). |
-| `height()` | `(value?: string) => ZS3 \| number` | Get/set altura. Sense argument retorna pixels (number). |
-| `width()` | `(value?: string) => ZS3 \| number` | Get/set amplada. |
-| `top()` | `(value?: string) => ZS3 \| string` | Get/set propietat CSS top. |
-| `left()` | `(value?: string) => ZS3 \| string` | Get/set propietat CSS left. |
-| `scrollTop()` | `(value?: number) => ZS3 \| number` | Get/set scrollTop. |
-| `scrollLeft()` | `(value?: number) => ZS3 \| number` | Get/set scrollLeft. |
-| `scrollHeight()` | `(n?: number) => number` | Obte scrollHeight d'un element. |
-| `clientHeight()` | `(n?: number) => number` | Obte clientHeight d'un element. |
+window.addEventListener('DOMContentLoaded', () => {
+    injectStyles()
+    const app = document.getElementById('app')!
+    app.append(buildHeader())
+
+    const main = el('main', { class: 'demo-main' })
+    main.append(
+        buildButtons(),
+        buildIcons(),
+        buildToolbar(),
+        buildNotifications(),
+        buildModal(),
+        buildModalDialog(),
+        buildForm(),
+        buildAuthForms(),
+        buildWindow(),
+        buildUtilities(),
+    )
+    app.append(main)
+})
+```
 
-#### Manipulacio DOM
+---
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `append()` | `(child: HTMLElement \| string) => ZS3` | Afegeix un fill al final. Accepta HTML string o HTMLElement. |
-| `prepend()` | `(sibling: HTMLElement \| string) => ZS3` | Afegeix un element al principi. |
-| `appendChild()` | `(htmlElement: HTMLElement) => ZS3` | Afegeix un HTMLElement com a fill. |
-| `remove()` | `() => ZS3` | Elimina els elements del DOM. |
-| `blur()` | `() => ZS3` | Treu el focus dels elements. |
-| `focus()` | `() => ZS3` | Dona focus al primer element. |
-| `clone()` | `(deep?: boolean) => HTMLElement \| null` | Clona el primer element (deep per defecte). |
+## i18n — Internationalisation
+
+El sistema i18n de ZS3 UI és complet i integrat a tots els components. Gestiona traduccions per clau, locale de fallback, persistència a localStorage, detecció automàtica del navegador, i actualització automàtica de tots els components en canviar d'idioma.
+
+### Fitxer de traduccions
+
+Les traduccions s'organitzen per idioma en un fitxer JSON:
+
+```json
+{
+    "ca": {
+        "app.title": "ZS3 Components",
+        "section.auth.login": "Iniciar sessió",
+        "section.auth.register": "Registrar-se",
+        "section.auth.recover": "Recuperar contrasenya",
+        "form.title": "Formulari de registre",
+        "form.description": "Completa el formulari per registrar-te.",
+        "form.field.name": "Nom",
+        "form.field.name.placeholder": "Introdueix el teu nom",
+        "form.field.email": "Correu electrònic",
+        "form.field.country": "País",
+        "form.field.country.placeholder": "Selecciona un país",
+        "form.country.spain": "Espanya",
+        "form.country.france": "França",
+        "section.dialog.alert.title": "Títol de l'alerta",
+        "section.dialog.alert.message": "Aquest és un missatge d'alerta important."
+    },
+    "en": {
+        "app.title": "ZS3 Components",
+        "section.auth.login": "Sign in",
+        "section.auth.register": "Register",
+        "section.auth.recover": "Recover password",
+        "form.title": "Registration form",
+        "form.description": "Complete the form to register.",
+        "form.field.name": "Name",
+        "form.field.name.placeholder": "Enter your name",
+        "form.field.email": "Email",
+        "form.field.country": "Country",
+        "form.field.country.placeholder": "Select a country",
+        "form.country.spain": "Spain",
+        "form.country.france": "France",
+        "section.dialog.alert.title": "Alert title",
+        "section.dialog.alert.message": "This is an important alert message."
+    }
+}
+```
 
-#### Atributs i dades
+### Inicialització
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `attr()` | `(name: string, value?: string) => ZS3 \| string \| null` | Get/set un atribut HTML. |
-| `removeAttr()` | `(name: string) => ZS3` | Elimina un atribut. |
-| `hasAttr()` | `(name: string) => boolean` | Verifica si el primer element te un atribut. |
-| `data()` | `(key: string, value?: string) => ZS3 \| string \| null` | Get/set data attributes (`dataset`). |
+```ts
+import { i18n } from 'zs3-ui-components'
+import translations from './i18n.json'
 
-#### Estils
+// Carrega totes les traduccions d'una vegada
+i18n.loadMultiple(translations)
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `style()` | `(styles: Record<string,string> \| string, value?: string) => ZS3 \| string` | Get/set estils CSS. Accepta objecte d'estils, clau+valor, o clau sola (getter). |
+// Inicialitza amb locale per defecte i fallback
+i18n.init({
+    locale: 'ca',
+    fallbackLocale: 'en',
+})
+```
 
-#### Navegacio
+`init()` també accepta `translations` directament:
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `parent()` | `() => ZS3 \| null` | Obte l'element pare. |
-| `children()` | `() => ZS3 \| null` | Obte els fills. |
-| `find()` | `(selector: string) => ZS3 \| null` | Cerca elements dins dels seleccionats. |
+```ts
+i18n.init({
+    locale: 'ca',
+    fallbackLocale: 'en',
+    translations: {
+        ca: { 'hello': 'Hola' },
+        en: { 'hello': 'Hello' },
+    },
+})
+```
 
-#### Col-leccio
+### API de l'objecte `i18n`
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `length()` | `() => number` | Retorna el nombre d'elements seleccionats. |
-| `eq()` | `(index: number) => ZS3 \| null` | Obte un element per index com a ZS3. |
-| `forEach()` | `(callback: (element: ZS3, index: number) => void) => ZS3` | Itera elements com a instancies ZS3. |
-| `each()` | `(callback: (element: HTMLElement, index: number) => void) => ZS3` | Itera elements com a HTMLElement. |
-| `[Symbol.iterator]` | `*() => Iterator<ZS3>` | Fa ZS3 iterable amb `for...of` i spread operator. |
-
-### Metodes estatics
+| Mètode | Descripció |
+|--------|------------|
+| `i18n.init(config)` | Inicialitza amb locale, fallback i traduccions |
+| `i18n.loadMultiple(obj)` | Carrega un objecte `{ locale: { clau: valor } }` |
+| `i18n.t('clau')` | Retorna la traducció de la clau |
+| `i18n.setLocale('en')` | Canvia l'idioma i actualitza tots els components |
+| `i18n.getLocale()` | Retorna l'idioma actiu |
+| `i18n.updateElements()` | Força l'actualització de tots els elements del document |
+| `i18n.updateRoot(shadowRoot)` | Actualitza els elements dins d'un shadow root específic |
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `ZS3.version()` | `() => string` | Retorna la versio de la biblioteca. |
-| `ZS3.fromElement()` | `(element: HTMLElement) => ZS3` | Crea una instancia ZS3 des d'un HTMLElement. |
-
-### `$env()`
-
-Retorna informacio de l'entorn d'execucio:
-
-```typescript
-const env = $env()
-// { userAgent: '...', language: 'ca', platform: 'Win32', ZS3: '1.0.6' }
-```
+```ts
+// Traduir una clau
+const text = i18n.t('form.field.name')  // → "Nom"
 
----
+// Canviar idioma (actualitza tots els components automàticament)
+i18n.setLocale('en')
 
-## Utilitats
+// Obtenir l'idioma actiu
+console.log(i18n.getLocale())  // → "en"
+```
 
-### $Parameters (params)
+### Escolta el canvi d'idioma
 
-Gestio de parametres d'URL.
+```ts
+// Enfocament HTML/inline (index2.ts)
+window.addEventListener('zs3-locale-change', () => {
+    log.info(`Idioma canviat a: ${i18n.getLocale()}`)
+})
 
-```typescript
-import { params } from 'zs3-ui-components'
+// Actualitzar text de botons programàtics quan canvia l'idioma
+window.addEventListener('zs3-locale-change', () => {
+    bLogin.setText(i18n.t('section.auth.login'))
+    bRegister.setText(i18n.t('section.auth.register'))
+})
 ```
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `getAll()` | `() => Record<string, string>` | Obte tots els parametres d'URL com a objecte. |
-| `get()` | `(key: string) => string \| Record<string,string>` | Obte el valor d'un parametre. Si `key` es buit, retorna tots. |
-| `set()` | `(key: string, value: string) => void` | Estableix un parametre d'URL (pushState). |
-| `delete()` | `(key: string) => void` | Elimina un parametre d'URL. |
-| `has()` | `(key: string) => boolean` | Verifica si existeix un parametre. |
+### `data-i18n` — Traduccions en HTML
 
-**Exemple:**
+Afegeix `data-i18n="clau"` a qualsevol element i el seu `textContent` s'actualitzarà automàticament en canviar l'idioma:
 
-```typescript
-params.set('page', '2')
-const page = params.get('page') // '2'
-params.has('page')               // true
-params.delete('page')
-const all = params.getAll()      // { ... }
+```html
+<!-- El text s'actualitza sol en canviar l'idioma -->
+<h1 data-i18n="app.title">ZS3 Components</h1>
+<p  data-i18n="form.description">Text per defecte</p>
 ```
 
-### $Log (log)
+Per traduir **atributs** (aria-label, placeholder, title…):
 
-Sistema de logging amb nivells, timestamps i colors a la consola.
+```html
+<!-- Tradueix l'atribut aria-label -->
+<zs3-icon name="bell" data-i18n-attr='{"aria-label":"nav.notifications"}'></zs3-icon>
 
-```typescript
-import { log } from 'zs3-ui-components'
+<!-- Tradueix el placeholder -->
+<input data-i18n-attr='{"placeholder":"form.field.name.placeholder"}' />
 ```
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `info()` | `(message: string, obj?: unknown) => void` | Missatge informatiu (verd). |
-| `warn()` | `(message: string, obj?: unknown) => void` | Advertencia (taronja). |
-| `error()` | `(message: string, obj?: unknown) => void` | Error (vermell). |
-| `debug()` | `(message: string, obj?: unknown) => void` | Debug (blau). |
-| `success()` | `(message: string, obj?: unknown) => void` | Exit (lima). |
-| `setEnabled()` | `(enabled: boolean) => void` | Activa/desactiva el logging. |
-| `setLevel()` | `(level: 'all' \| 'info' \| 'warn' \| 'error') => void` | Estableix el nivell minim de logging. |
+Tots dos sistemes funcionen dins de **Shadow DOM** — `i18n.updateElements()` escaneja automàticament els shadow roots de tots els components registrats.
 
-**Exemple:**
+### i18n en components TypeScript
 
-```typescript
-log.info('Aplicacio iniciada')
-log.warn('Memoria alta', { used: '90%' })
-log.error('No es pot connectar')
-log.debug('Valor de x:', { x: 42 })
-log.success('Operacio completada')
+Tots els components que extenen `$BaseComponent` exposen el mètode `this.t(key)`:
 
-log.setLevel('warn') // Nomes mostra warn i error
-log.setEnabled(false) // Desactiva tot el logging
+```ts
+// Dins d'un component personalitzat
+class MyComponent extends $BaseComponent {
+    protected render(): void {
+        const label = this.t('my.label.key')  // traducció automàtica
+        this.setHTML(`<button>${label}</button>`)
+    }
+}
 ```
 
-### $Debug (debug)
+### i18n en atributs de components
 
-Utilitat per a debugging d'esdeveniments DOM en temps real.
+Tots els components accepten atributs `i18n-*` per les seves propietats de text:
 
-```typescript
-import { debug } from 'zs3-ui-components'
+```html
+<!-- HTML inline -->
+<zs3-form
+    i18n-title="form.title"
+    i18n-description="form.description"
+    i18n-accept-text="zs3.form.accept"
+    i18n-cancel-text="zs3.form.cancel">
+</zs3-form>
+
+<zs3-modal-dialog
+    i18n-title="section.dialog.confirm.title"
+    i18n-message="section.dialog.confirm.message"
+    i18n-accept-text="zs3.dialog.accept"
+    i18n-cancel-text="zs3.dialog.cancel">
+</zs3-modal-dialog>
+
+<zs3-window i18n-title="form.title"></zs3-window>
+<zs3-notification i18n-title="section.notification.success.title"
+                  i18n-message="section.notification.success.message">
+</zs3-notification>
 ```
 
-El mateix parell `selector:eventType` pot estar actiu en múltiples roots simultàniament.
+```ts
+// TypeScript programàtic (index3.ts)
+const form = new $Form()
+form.setAttribute('i18n-title', 'form.title')
+form.setAttribute('i18n-description', 'form.description')
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `start()` | `(selector: string, eventType: keyof HTMLElementEventMap, root?: Document \| HTMLElement \| ShadowRoot) => void` | Inicia el debug. Es poden registrar múltiples roots per al mateix selector+event. |
-| `stop()` | `(selector: string, eventType: keyof HTMLElementEventMap, root?: Document \| HTMLElement \| ShadowRoot) => void` | Atura el debug per al root indicat. Si hi ha més roots actius per al mateix selector+event, els altres continuen. |
-| `stopAll()` | `() => void` | Atura tot el debugging, per a tots els selectors, events i roots actius. |
-| `list()` | `() => string[]` | Llista tots els debugs actius en format `selector:eventType`. Si hi ha múltiples roots per al mateix parell, apareix una entrada per cada root. |
+const dialog = new $ModalDialog()
+dialog.setAttribute('i18n-title', 'section.dialog.confirm.title')
+dialog.setAttribute('i18n-message', 'section.dialog.confirm.message')
+dialog.setAttribute('i18n-accept-text', 'zs3.dialog.accept')
 
-**Exemple:**
+const win = new $Window()
+win.setAttribute('i18n-title', 'form.title')
+```
 
-```typescript
-const containerA = document.getElementById('sectionA')!
-const containerB = document.getElementById('sectionB')!
+### Traduccions internes del framework
 
-debug.start('.btn', 'click', containerA)   // debug de .btn dins de sectionA
-debug.start('.btn', 'click', containerB)   // debug de .btn dins de sectionB (root diferent)
-debug.start('.btn', 'click', containerA)   // ignorat, ja estava registrat
+El framework inclou traduccions per defecte per als textos interns dels components (botons, etiquetes, etc.):
 
-debug.list()   // ['.btn:click', '.btn:click']  (una entrada per root actiu)
+```ts
+import { defaultTranslations } from 'zs3-ui-components'
 
-debug.stop('.btn', 'click', containerA)    // atura nomes containerA, containerB segueix actiu
-debug.stopAll()                            // atura tot
+// Les claus internes del framework comencen per "zs3."
+// zs3.form.accept, zs3.form.cancel
+// zs3.dialog.accept, zs3.dialog.cancel, zs3.dialog.close
+// zs3.login.title, zs3.login.email, zs3.login.password, zs3.login.submit
+// zs3.register.title, zs3.register.submit
+// zs3.recover.title, zs3.recover.submit
 ```
 
-### $Storage (storage)
+Pots sobreescriure qualsevol clau interna carregant les teves pròpies traduccions amb `i18n.loadMultiple()`.
 
-Wrapper per localStorage amb serialitzacio JSON automatica.
+### Detecció automàtica del navegador
 
-```typescript
-import { storage } from 'zs3-ui-components'
+Si no s'especifica locale a `init()`, el sistema detecta l'idioma del navegador:
+
+```ts
+// Detecta automàticament: navigator.language → 'ca-ES' → 'ca'
+i18n.init({ fallbackLocale: 'en' })
 ```
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `set()` | `(key: string, value: unknown) => void` | Guarda un valor (serialitzat amb JSON.stringify). |
-| `get()` | `<T>(key: string) => T \| null` | Obte un valor (deserialitzat amb JSON.parse). |
-| `remove()` | `(key: string) => void` | Elimina un valor. |
-| `clear()` | `() => void` | Neteja tot localStorage. |
-| `has()` | `(key: string) => boolean` | Verifica si existeix una clau. |
-| `keys()` | `() => string[]` | Obte totes les claus. |
+### Selector d'idioma integrat
 
-**Exemple:**
+El component `<zs3-select-locale>` mostra un selector d'idioma que crida `i18n.setLocale()` automàticament:
 
-```typescript
-storage.set('user', { name: 'Joan', role: 'admin' })
-const user = storage.get<{ name: string; role: string }>('user')
-// { name: 'Joan', role: 'admin' }
+```html
+<!-- HTML -->
+<zs3-select-locale zs3-position="position:relative;"></zs3-select-locale>
+```
 
-storage.has('user')   // true
-storage.keys()        // ['user', 'zs3-theme', 'zs3-locale', ...]
-storage.remove('user')
-storage.clear()
+```ts
+// TypeScript (index3.ts)
+const locale = document.createElement('zs3-select-locale')
+locale.setAttribute('zs3-position', 'position:relative;')
+header.append(locale)
 ```
 
 ---
 
-## $Store
+## Theme System
+
+### Temes disponibles
 
-Sistema de gestió d'estat global inspirat en Redux, sense dependències externes. Segueix el flux `dispatch(action)` → reducer → nou estat → notificació als subscriptors.
+| Tema | Valor |
+|------|-------|
+| Clar (default) | `light` |
+| Fosc | `dark` |
+| Alt contrast | `high-contrast` |
 
-```typescript
-import { $Store } from 'zs3-ui-components'
-import type { Listener, Reducer } from 'zs3-ui-components'
+### API `themeManager`
+
+```ts
+import { themeManager } from 'zs3-ui-components'
+
+themeManager.setTheme('dark')        // canvia el tema
+themeManager.getTheme()              // → 'dark'
+themeManager.isDark()                // → true
+themeManager.toggleDark()            // alterna light/dark
 ```
 
-### Flux de dades
+### Escolta canvis de tema
+
+```ts
+// HTML/inline (index2.ts)
+window.addEventListener('zs3-theme-change', () => {
+    const theme = themeManager.getTheme()
+    const iconEl = document.querySelector('#theme-indicator zs3-icon')
+    iconEl?.setAttribute('name', themeManager.isDark() ? 'moon' : 'sun')
+})
 
+// TypeScript (index3.ts)
+window.addEventListener('zs3-theme-change', () => {
+    if (nameEl) nameEl.textContent = themeManager.getTheme()
+    if (iconEl) iconEl.setAttribute('name', themeManager.isDark() ? 'moon' : 'sun')
+})
 ```
-[Component] → dispatch(action, payload)
-                      ↓
-              [Store] executa el reducer
-                      ↓
-             estat = { ...estat, ...canvis }
-                      ↓
-         notifica listeners de l'acció + listeners '*'
-                      ↓
-           [Components subscrits] → setState() → re-render
+
+### Selector de tema integrat
+
+```html
+<zs3-select-theme zs3-position="position:relative;"></zs3-select-theme>
 ```
 
-### Inicialització
+---
 
-El patró recomanat és registrar el Store com a singleton al contenidor de dependències (DIContainer):
+## Components
 
-```typescript
-import { $Store } from 'zs3-ui-components'
-import { diContainer } from 'zs3-ui-components'
-import { registerReducers } from './actions'
+### zs3-button
 
-interface AppState {
-  theme: 'light' | 'dark'
-  user: User | null
-  loading: boolean
-}
+Botó versàtil amb variants, mides, icones, estats i events.
 
-const initialState: AppState = { theme: 'light', user: null, loading: false }
+**Atributs:**
 
-diContainer.registerSingleton('store', () => {
-  const store = new $Store<AppState>(initialState)
-  registerReducers(store) // registra tots els reducers
-  return store
-})
+| Atribut | Valors | Descripció |
+|---------|--------|------------|
+| `variant` | `primary` `secondary` `success` `danger` `warning` `info` | Color del botó |
+| `size` | `sm` `md` `lg` | Mida |
+| `icon` | nom de la icona | Icona SVG integrada |
+| `position` | `left` `right` | Posició de la icona respecte al text |
+| `disabled` | booleà | Desactiva el botó |
+| `loading` | booleà | Mostra spinner de càrrega |
+| `rounded` | booleà | Forma arrodonida (perfecta per icones soles) |
 
-// Qualsevol component el pot obtenir amb:
-const store = diContainer.resolve<$Store<AppState>>('store')
-```
+**Esdeveniments:**
 
-### Fitxer actions
+| Esdeveniment | Descripció |
+|-------------|------------|
+| `zs3-click` | Es dispara en fer clic (respecta `disabled` i `loading`) |
 
-Cal crear un fitxer `actions.ts` que centralitzi les constants d'acció i el registre de reducers:
+#### HTML inline (index2.html)
 
-```typescript
-// actions.ts
-import type { $Store } from 'zs3-ui-components'
+```html
+<!-- Variants -->
+<zs3-button>Default</zs3-button>
+<zs3-button variant="primary">Primary</zs3-button>
+<zs3-button variant="secondary">Secondary</zs3-button>
+<zs3-button variant="success">Success</zs3-button>
+<zs3-button variant="danger">Danger</zs3-button>
+<zs3-button variant="warning">Warning</zs3-button>
+<zs3-button variant="info">Info</zs3-button>
+
+<!-- Mides -->
+<zs3-button variant="primary" size="sm">Small</zs3-button>
+<zs3-button variant="primary">Medium</zs3-button>
+<zs3-button variant="primary" size="lg">Large</zs3-button>
+
+<!-- Amb icona -->
+<zs3-button icon="save" variant="primary" position="left">Guardar</zs3-button>
+<zs3-button icon="edit">Editar</zs3-button>
+<zs3-button icon="trash" variant="danger" position="left">Eliminar</zs3-button>
+<zs3-button icon="download" variant="info" position="left">Descarregar</zs3-button>
+
+<!-- Rounded (icona sola) -->
+<zs3-button icon="settings" rounded></zs3-button>
+<zs3-button icon="bell" variant="warning" rounded></zs3-button>
+<zs3-button icon="star" variant="success" size="lg" rounded>Favorit</zs3-button>
+
+<!-- Estats -->
+<zs3-button variant="primary" disabled>Disabled</zs3-button>
+<zs3-button variant="success" loading>Loading...</zs3-button>
+
+<!-- Event inline — `this` és el botó, `event` és el CustomEvent -->
+<zs3-button id="btn-toggle" variant="info"
+    zs3-click="toggleLoading(this)">
+    Toggle Loading
+</zs3-button>
+
+<!-- Event inline simple -->
+<zs3-button variant="primary" icon="plus"
+    zs3-click="document.getElementById('out').textContent = 'Clicat: ' + new Date().toLocaleTimeString()">
+    Clica'm
+</zs3-button>
+<div id="out">Clica un botó...</div>
+```
+
+#### TypeScript programàtic (index3.ts)
+
+```ts
+import { $Button } from 'zs3-ui-components'
+
+// Crear un botó
+const b = new $Button()
+b.textContent = 'Guardar'          // text (es captura a beforeMount)
+b.variant = 'primary'
+b.icon = 'save'
+b.position = 'left'
+document.body.append(b)
+
+// Mida i estat
+b.size = 'lg'
+b.disabled = true
+b.loading = true
+
+// Rounded (icona sola)
+const bRound = new $Button()
+bRound.icon = 'settings'
+bRound.rounded = true
+
+// Toggle loading programàtic
+const bToggle = new $Button()
+bToggle.textContent = 'Toggle Loading'
+bToggle.variant = 'info'
+bToggle.addEventListener('zs3-click', () => {
+    bToggle.setLoading(!bToggle.loading)
+})
 
-// Constants per evitar strings màgics escampats pel codi
-export const Actions = {
-  AUTH_LOGIN:     'auth/login',
-  AUTH_LOGOUT:    'auth/logout',
-  THEME_TOGGLE:   'theme/toggle',
-  LOADING_SET:    'loading/set',
-} as const
+// Actualitzar text després de muntar (quan el component ja és al DOM)
+bToggle.setText('Nou text')
 
-// Registre centralitzat de tots els reducers
-export function registerReducers(store: $Store<AppState>): void {
-  store.registerReducer(Actions.AUTH_LOGIN, (_state, payload) => ({
-    user: payload as User,
-    loading: false,
-  }))
+// Canviar text amb i18n (actualitza en canvi d'idioma)
+window.addEventListener('zs3-locale-change', () => {
+    bLogin.setText(i18n.t('section.auth.login'))
+})
+```
 
-  store.registerReducer(Actions.AUTH_LOGOUT, () => ({
-    user: null,
-  }))
+**API de `$Button`:**
 
-  store.registerReducer(Actions.THEME_TOGGLE, (state) => ({
-    theme: state.theme === 'light' ? 'dark' : 'light',
-  }))
+| Propietat / Mètode | Tipus | Descripció |
+|-------------------|-------|------------|
+| `variant` | string | Variant de color |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | Mida |
+| `icon` | string | Nom de la icona |
+| `position` | `'left'` \| `'right'` | Posició icona |
+| `disabled` | boolean | Desactivat |
+| `loading` | boolean | Estat de càrrega |
+| `rounded` | boolean | Forma arrodonida |
+| `setText(text)` | mètode | Actualitza el text (quan ja és al DOM) |
+| `setLoading(bool)` | mètode | Activa/desactiva l'estat loading |
 
-  store.registerReducer(Actions.LOADING_SET, (_state, payload) => ({
-    loading: payload as boolean,
-  }))
-}
-```
+---
 
-### API
+### zs3-icon
 
-| Mètode | Signatura | Descripció |
-|--------|-----------|------------|
-| `constructor` | `(initialState: T)` | Crea el store. L'estat inicial es copia en profunditat (`structuredClone`). |
-| `getState()` | `() => Readonly<T>` | Retorna una còpia immutable (frozen) de l'estat actual. |
-| `registerReducer()` | `(actionType: string, reducer: Reducer<T>) => void` | Associa un reducer a un tipus d'acció. |
-| `dispatch()` | `(actionType: string, payload?: unknown) => void` | Executa l'acció, actualitza l'estat i notifica els listeners. |
-| `subscribe()` | `(actionType: string, listener: Listener<T>) => () => void` | Subscriu un listener. Retorna la funció d'unsubscribe. |
+Icona SVG integrada amb suport de mida, color, rotació, flip i clics.
 
-### Patrons d'ús en components
+**Atributs:**
 
-**1. Llegir estat inicial en `onMount()`:**
+| Atribut | Valors | Descripció |
+|---------|--------|------------|
+| `name` | nom de la icona | Icona a mostrar |
+| `size` | `small` `medium` `large` o número en px | Mida |
+| `color` | `primary` `secondary` `success` `danger` `warning` `info` | Color |
+| `rotate` | `90` `180` `270` | Graus de rotació |
+| `flip` | `horizontal` `vertical` | Volteig |
+| `clickable` | booleà | Activa l'event `zs3-icon-click` |
+| `stroke-width` | número | Amplada del traç SVG |
+| `aria-label` | text | Label d'accessibilitat |
+| `data-i18n-attr` | JSON | Traducció de l'atribut aria-label |
 
-```typescript
-const state = this.store.getState()
-this.setState({ theme: state.theme })
-```
+**Icones disponibles:** `increase`, `decrease`, `error`, `warning`, `information`, `close`, `left-arrow`, `right-arrow`, `up-arrow`, `down-arrow`, `menu`, `accept`, `cancel`, `search`, `delete`, `dark`, `sun`, `moon`, `users`, `copy`, `trash`, `upload`, `logout`, `login`, `modal`, `save`, `edit`, `download`, `settings`, `home`, `star`, `heart`, `filter`, `refresh`, `lock`, `unlock`, `bell`, `mail`, `phone`, `calendar`, `clock`, `eye`, `eye-off`, `plus`, `minus`, `check`, `x`
 
-**2. Subscriure's a canvis específics en `onMount()`:**
+#### HTML inline (index2.html)
 
-```typescript
-// Escoltar una acció concreta
-this.addSubscription(
-  this.store.subscribe(Actions.THEME_TOGGLE, (state) => {
-    this.setState({ theme: state.theme })
-  })
-)
+```html
+<!-- Bàsica -->
+<zs3-icon name="star"></zs3-icon>
+
+<!-- Mides -->
+<zs3-icon name="star" size="small"></zs3-icon>
+<zs3-icon name="star" size="medium"></zs3-icon>
+<zs3-icon name="star" size="large"></zs3-icon>
+<zs3-icon name="star" size="48"></zs3-icon>
+
+<!-- Colors -->
+<zs3-icon name="heart" size="large" color="primary"></zs3-icon>
+<zs3-icon name="heart" size="large" color="danger"></zs3-icon>
+<zs3-icon name="heart" size="large" color="success"></zs3-icon>
+
+<!-- Rotació i flip -->
+<zs3-icon name="right-arrow" size="large" rotate="90"></zs3-icon>
+<zs3-icon name="right-arrow" size="large" rotate="180"></zs3-icon>
+<zs3-icon name="right-arrow" size="large" flip="horizontal"></zs3-icon>
+
+<!-- Clickable amb id per als event listeners de index2.ts -->
+<zs3-icon id="icon-star"  name="star"  size="large" color="warning"  clickable></zs3-icon>
+<zs3-icon id="icon-heart" name="heart" size="large" color="danger"   clickable></zs3-icon>
+<zs3-icon id="icon-bell"  name="bell"  size="large" color="info"     clickable></zs3-icon>
+<div id="icon-click-output">Clica una icona...</div>
+
+<!-- i18n en atribut aria-label -->
+<zs3-icon name="bell" data-i18n-attr='{"aria-label":"nav.notifications"}'></zs3-icon>
+```
+
+```ts
+// index2.ts — escolta events de les icones clickables
+function setupIconClickListeners(): void {
+    const output = document.getElementById('icon-click-output')
+    ;['icon-star', 'icon-heart', 'icon-bell'].forEach((id) => {
+        const el = document.getElementById(id)
+        el?.addEventListener('zs3-icon-click', (e: Event) => {
+            const name = (e.target as Element).getAttribute('name') || id
+            if (output) output.textContent = `zs3-icon-click: icona "${name}" clicada`
+        })
+    })
+}
 
-// Escoltar TOTS els canvis (canal wildcard '*')
-this.addSubscription(
-  this.store.subscribe('*', (state) => {
-    this.setState({ appState: state as AppState })
-  })
-)
+// index2.ts — genera la graella de totes les icones
+function setupIconsGrid(): void {
+    const grid = document.getElementById('icons-grid')
+    if (!grid) return
+    $Icon.getAvailableIcons().forEach((name) => {
+        const card = document.createElement('div')
+        card.className = 'demo-icon-card'
+        card.innerHTML = `<zs3-icon name="${name}" size="medium"></zs3-icon><span>${name}</span>`
+        card.addEventListener('click', () =>
+            $Notification.info(`Icona: ${name}`, { position: 'bottom-right', duration: 2000 })
+        )
+        grid.appendChild(card)
+    })
+}
 ```
 
-> **Nota:** El mètode `addSubscription()` de `$BaseComponent` s'encarrega de cridar l'unsubscribe automàticament quan el component es destrueix.
+#### TypeScript programàtic (index3.ts)
 
-**3. Disparar accions en `bindEvents()`:**
+```ts
+import { $Icon } from 'zs3-ui-components'
 
-```typescript
-this.addEvent('click', () => {
-  this.store.dispatch(Actions.THEME_TOGGLE)
-})
+// Icona bàsica
+const ic = new $Icon()
+ic.setAttribute('name', 'star')
+ic.setAttribute('size', 'large')
+ic.setAttribute('color', 'warning')
+document.body.append(ic)
 
-this.addEvent('submit', () => {
-  this.store.dispatch(Actions.AUTH_LOGIN, { id: 1, name: 'Joan' })
+// Clickable
+ic.setAttribute('clickable', '')
+ic.addEventListener('zs3-icon-click', (e) => {
+    console.log('Icona clicada:', (e as CustomEvent).detail)
 })
-```
-
-### Canal wildcard `'*'`
 
-El canal especial `'*'` rep notificacions de **qualsevol** acció que es dispari. És útil per a components de monitoratge o per reagir a qualsevol canvi d'estat:
+// Totes les icones disponibles
+const names = $Icon.getAvailableIcons()  // string[]
 
-```typescript
-store.subscribe('*', (state) => {
-  console.log('Estat actualitzat:', state)
+// Afegir icona personalitzada
+$Icon.addIcon('custom', `<path d="M12 2L2 22h20L12 2z"/>`)
+$Icon.addIcons({
+    'logo-a': '<path .../>',
+    'logo-b': '<path .../>',
 })
 ```
 
-### Tipus auxiliars
-
-| Tipus | Signatura | Descripció |
-|-------|-----------|------------|
-| `Listener<T>` | `(state: Readonly<T>) => void` | Funció que rep l'estat quan hi ha un canvi. |
-| `Reducer<T>` | `(state: T, payload?: unknown) => Partial<T>` | Funció que transforma l'estat. Retorna només els camps que canvien. |
-
 ---
 
-## HttpClient
-
-Client HTTP basat en `fetch` amb suport per a interceptors, reintentos automàtics i timeout. Cada instància té la seva pròpia configuració, per la qual cosa no s'exposa com a singleton global.
+### zs3-toolbar
 
-```typescript
-import { HttpClient, HttpError } from 'zs3-ui-components'
-import type { HttpClientConfig, HttpResponse } from 'zs3-ui-components'
-```
+Contenidor de botons amb suport per orientació, alineació, variants compactes i posicionament flotant.
 
-### Configuració
+**Atributs:**
 
-```typescript
-const api = new HttpClient({
-    baseUrl: 'https://api.exemple.com',  // Base de totes les URLs relatives
-    timeout: 10_000,                      // ms abans de cancel·lar (per defecte 10000)
-    retries: 2,                           // Reintentos automàtics en errors 5xx/timeout
-    retryDelay: 1_000,                    // ms entre reintent (es duplica cada vegada)
-    headers: {                            // Capçaleres per defecte (Content-Type i Accept: application/json ja inclosos)
-        Authorization: 'Bearer token',
-    },
-})
-```
+| Atribut | Valors | Descripció |
+|---------|--------|------------|
+| `direction` | `row` `column` | Orientació |
+| `align` | `start` `center` `end` | Alineació dels elements |
+| `variant` | `default` `compact` | Estil visual |
+| `float` | `top` `bottom` `left` `right` | Posicionament flotant |
+| `move` | `x` `y` `xy` | Permet arrossegar la toolbar |
+| `left` `top` `right` `bottom` | posició en px | Posició inicial |
 
-### Metodes
+#### HTML inline (index2.html)
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `get()` | `<T>(url: string, params?: Record<string, string>) => Promise<HttpResponse<T>>` | Peticio GET. Els `params` s'afegeixen com a query string. |
-| `post()` | `<T>(url: string, body?: unknown) => Promise<HttpResponse<T>>` | Peticio POST amb body JSON. |
-| `put()` | `<T>(url: string, body?: unknown) => Promise<HttpResponse<T>>` | Peticio PUT. |
-| `patch()` | `<T>(url: string, body?: unknown) => Promise<HttpResponse<T>>` | Peticio PATCH. |
-| `delete()` | `<T>(url: string) => Promise<HttpResponse<T>>` | Peticio DELETE. |
-| `request()` | `<T>(config: HttpRequestConfig) => Promise<HttpResponse<T>>` | Peticio completament configurable. |
+```html
+<!-- Horitzontal -->
+<zs3-toolbar direction="row">
+    <zs3-button icon="home">Inici</zs3-button>
+    <zs3-button icon="users">Usuaris</zs3-button>
+    <zs3-button icon="settings">Configuració</zs3-button>
+    <zs3-button icon="bell" variant="warning">Notificacions</zs3-button>
+    <zs3-button icon="logout" variant="danger">Sortir</zs3-button>
+</zs3-toolbar>
 
-### Resposta
+<!-- Vertical -->
+<zs3-toolbar direction="column" style="width:fit-content">
+    <zs3-button icon="edit" variant="primary" position="left" size="sm">Editar</zs3-button>
+    <zs3-button icon="copy" position="left" size="sm">Copiar</zs3-button>
+    <zs3-button icon="trash" variant="danger" position="left" size="sm">Eliminar</zs3-button>
+</zs3-toolbar>
 
-Tots els metodes retornen `Promise<HttpResponse<T>>`:
+<!-- Compact + align center (botons de navegació) -->
+<zs3-toolbar direction="row" align="center" variant="compact">
+    <zs3-button icon="left-arrow"  size="sm" rounded></zs3-button>
+    <zs3-button icon="refresh"     size="sm" rounded></zs3-button>
+    <zs3-button icon="right-arrow" size="sm" rounded></zs3-button>
+</zs3-toolbar>
 
-```typescript
-interface HttpResponse<T> {
-    data: T        // Cos de la resposta (parseig JSON automatic)
-    status: number
-    statusText: string
-    headers: Headers
-    config: HttpRequestConfig
-}
+<!-- Flotant + arrossegable horitzontalment -->
+<zs3-toolbar direction="row" float="bottom" move="x" left="80px">
+    <zs3-button icon="save"   variant="success" size="sm">Guardar</zs3-button>
+    <zs3-button icon="cancel" variant="danger"  size="sm">Cancel·lar</zs3-button>
+</zs3-toolbar>
 ```
 
-### Interceptors
+#### TypeScript programàtic (index3.ts)
 
-Els interceptors permeten modificar totes les peticions o respostes de forma centralitzada. Retornen una funció per cancel·lar-los.
+```ts
+import { $Toolbar, $Button } from 'zs3-ui-components'
 
-```typescript
-// Interceptor de peticio: afegir token a totes les crides
-const removeAuth = api.onRequest(config => ({
-    ...config,
-    headers: { ...config.headers, Authorization: `Bearer ${getToken()}` },
-}))
+// Horitzontal
+const toolbar = new $Toolbar()
+toolbar.setAttribute('direction', 'row')
 
-// Interceptor de resposta: transformar dades
-api.onResponse(response => ({
-    ...response,
-    data: transform(response.data),
-}))
+const items: Array<[string, string, string | undefined]> = [
+    ['home',   'Inici',         undefined],
+    ['users',  'Usuaris',       undefined],
+    ['bell',   'Notificacions', 'warning'],
+    ['logout', 'Sortir',        'danger'],
+]
 
-// Interceptor d'error: gestio centralitzada
-api.onError(async error => {
-    if (error.isUnauthorized) {
-        await refreshToken()
-        // Si es retorna un HttpResponse, la peticio es considera recuperada
-    }
-    throw error  // Si es relanca, l'error arriba al catch del cridant
+items.forEach(([icon, label, variant]) => {
+    const b = new $Button()
+    b.textContent = label
+    b.icon = icon
+    if (variant) b.variant = variant as $Button['variant']
+    toolbar.append(b)
+})
+document.body.append(toolbar)
+
+// Compact amb botons arrodonits
+const navToolbar = new $Toolbar()
+navToolbar.setAttribute('direction', 'row')
+navToolbar.setAttribute('align', 'center')
+navToolbar.setAttribute('variant', 'compact')
+
+;['left-arrow', 'refresh', 'right-arrow'].forEach((icon) => {
+    const b = new $Button()
+    b.icon = icon
+    b.size = 'sm'
+    b.rounded = true
+    navToolbar.append(b)
 })
 
-// Cancel·lar un interceptor
-removeAuth()
+// Flotant + movible
+const floatToolbar = new $Toolbar()
+floatToolbar.setAttribute('direction', 'row')
+floatToolbar.setAttribute('float', 'bottom')
+floatToolbar.setAttribute('move', 'x')
+floatToolbar.setAttribute('left', '80px')
 ```
 
-### Gestio d'errors
+---
+
+### zs3-notification
 
-Els errors HTTP (4xx, 5xx) i de xarxa es llancen com a `HttpError`:
+Notificació emergent (toast) amb posicions, durades, barra de progrés i estat persistent.
 
-```typescript
-try {
-    const { data } = await api.get<Post[]>('/posts')
-} catch (error) {
-    if (error instanceof HttpError) {
-        console.log(error.status)        // 404, 500...
-        console.log(error.isNotFound)    // true si 404
-        console.log(error.isUnauthorized) // true si 401
-        console.log(error.isServerError)  // true si 5xx
-        console.log(error.isTimeout)      // true si timeout
-    }
-}
-```
+**Atributs:**
 
-### Exemple complet
+| Atribut | Valors | Descripció |
+|---------|--------|------------|
+| `type` | `success` `error` `warning` `info` | Tipus/color |
+| `title` | text | Títol (opcional) |
+| `message` | text | Missatge |
+| `position` | `top-left` `top-center` `top-right` `bottom-left` `bottom-center` `bottom-right` | Posició a la pantalla |
+| `duration` | número en ms (0 = persistent) | Temps de visibilitat |
+| `show-progress` | booleà | Mostra barra de progrés |
+| `dismissible` | booleà | Mostra botó de tancament |
+| `i18n-title` | clau i18n | Títol traduït |
+| `i18n-message` | clau i18n | Missatge traduït |
 
-```typescript
-import { HttpClient, HttpError } from 'zs3-ui-components'
-import { $ } from 'zs3-ui-components'
+#### Mètodes estàtics (la manera més senzilla)
 
-interface Post { id: number; title: string; body: string }
+```ts
+import { $Notification } from 'zs3-ui-components'
 
-const api = new HttpClient({
-    baseUrl: 'https://jsonplaceholder.typicode.com',
-    timeout: 8_000,
-    retries: 1,
+$Notification.success('Operació completada!', {
+    position: 'top-right',
+    duration: 3000,
+    showProgress: true,
 })
 
-// GET amb parametres de query
-const { data: posts } = await api.get<Post[]>('/posts', { _limit: '5' })
+$Notification.error('Ha ocorregut un error.', {
+    title: 'Error crític',
+    position: 'top-right',
+    duration: 5000,
+    dismissible: true,
+})
 
-// POST
-const { data: nou, status } = await api.post<Post>('/posts', {
-    title: 'Nou post',
-    body: 'Contingut',
-    userId: 1,
+$Notification.warning('Atenció: acció irreversible!', {
+    position: 'bottom-right',
+    duration: 4000,
 })
 
-// PATCH (modificacio parcial)
-await api.patch(`/posts/${nou.id}`, { title: 'Titol modificat' })
+$Notification.info('3 nous missatges pendents.', {
+    title: 'Nous missatges',
+    position: 'top-right',
+    duration: 0,      // 0 = persistent
+    dismissible: true,
+})
+```
 
-// DELETE
-await api.delete(`/posts/${nou.id}`)
+#### HTML inline (index2.html)
 
-// Integrat amb ZS3
-$('#btn-load')?.addEvent('click', async () => {
-    try {
-        const { data } = await api.get<Post[]>('/posts', { _limit: '3' })
-        const html = data.map(p => `<li>${p.title}</li>`).join('')
-        $('ul#llista')?.html(html)
-    } catch (e) {
-        if (e instanceof HttpError) $('p#error')?.html(`Error ${e.status}`)
-    }
-})
+```html
+<!-- Mètodes estàtics des de handlers inline -->
+<zs3-button variant="success"
+    zs3-click="$Notification.success('Èxit!', { position: 'top-right', duration: 3000 })">
+    Success
+</zs3-button>
+<zs3-button variant="danger"
+    zs3-click="$Notification.error('Error!', { position: 'top-right', duration: 3000 })">
+    Error
+</zs3-button>
+
+<!-- Component inline amb show()/hide() -->
+<zs3-notification
+    id="notif-inline"
+    type="success"
+    title="Títol"
+    message="Missatge de notificació"
+    position="top-center"
+    duration="0"
+    show-progress
+    dismissible>
+</zs3-notification>
+<zs3-button zs3-click="document.getElementById('notif-inline').$.show()">show()</zs3-button>
+<zs3-button zs3-click="document.getElementById('notif-inline').$.hide()">hide()</zs3-button>
+
+<!-- i18n -->
+<zs3-notification
+    i18n-title="section.notification.success.title"
+    i18n-message="section.notification.success.message"
+    type="success"
+    position="top-right">
+</zs3-notification>
 ```
 
----
+#### TypeScript programàtic (index3.ts)
 
-## Sistema de Temes (ThemeManager)
+```ts
+// Component creat programàticament
+const notif = document.createElement('zs3-notification') as HTMLElement & {
+    show(): void
+    hide(): void
+}
+notif.setAttribute('type', 'success')
+notif.setAttribute('title', 'Notificació TypeScript')
+notif.setAttribute('message', 'Creada programàticament des de TypeScript')
+notif.setAttribute('position', 'top-center')
+notif.setAttribute('duration', '0')
+notif.setAttribute('show-progress', '')
+notif.setAttribute('dismissible', '')
+document.body.append(notif)
 
-El sistema de temes permet canviar l'aparenca visual de tota l'aplicacio.
+const bShow = new $Button()
+bShow.textContent = 'show()'
+bShow.variant = 'primary'
+bShow.addEventListener('zs3-click', () => notif.show())
 
-```typescript
-import { themeManager } from 'zs3-ui-components'
+const bHide = new $Button()
+bHide.textContent = 'hide()'
+bHide.addEventListener('zs3-click', () => notif.hide())
 ```
 
-### Temes disponibles
+---
 
-| Tema | Descripcio |
-|------|------------|
-| `light` | Tema clar per defecte. Fons blanc, text fosc. |
-| `light-blue` | Tema clar amb accents blaus. |
-| `dark` | Tema fosc. Fons `#111827`, text clar. |
-| `elegant` | Tema elegant amb tons champagne/bronze. Font serif (Georgia). |
-| `modern` | Tema modern amb colors neon i indigo. Border-radius arrodonit. |
-| `high-contrast` | Alt contrast per accessibilitat. Fons negre, text blanc. |
-| `system` | Segueix la preferencia del sistema operatiu (`prefers-color-scheme`). |
-| `custom` | Tema personalitzat definit per l'usuari. |
-
-### API
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `setTheme()` | `(theme: ThemeType) => void` | Estableix el tema actiu. Persisteix a localStorage. |
-| `getTheme()` | `() => ThemeType` | Obte el tema actual. |
-| `toggleTheme()` | `() => void` | Alterna entre `light` i `dark`. |
-| `isDark()` | `() => boolean` | Verifica si el tema actual es dark. |
-| `getAvailableThemes()` | `() => ThemeType[]` | Llista tots els temes disponibles. |
-
-### Event
-
-Quan canvia el tema, s'emet un event global:
-
-```typescript
-window.addEventListener('zs3-theme-change', (e: CustomEvent) => {
-    console.log('Nou tema:', e.detail.theme)
-})
-```
+### zs3-modal
 
-### Funcions auxiliars
+Modal genèric contenidor de contingut amb mides, backdrop, tancament per ESC/backdrop i mode scrollable.
 
-```typescript
-import { getCSSVariable, setCSSVariable, initThemeSystem } from 'zs3-ui-components'
+**Atributs:**
 
-// Llegir una CSS variable (sense el prefix --)
-getCSSVariable('zs3-primary-color') // '#3b82f6'
+| Atribut | Valors | Descripció |
+|---------|--------|------------|
+| `size` | `small` `medium` `large` `fullscreen` | Mida |
+| `backdrop` | booleà | Mostra el fons fosc |
+| `close-on-backdrop` | booleà | Tanca en clicar el backdrop |
+| `close-on-escape` | booleà | Tanca amb la tecla ESC |
+| `scrollable` | booleà | Permet scroll del contingut |
+| `centered` | booleà | Centra verticalment el modal |
 
-// Establir una CSS variable globalment
-setCSSVariable('zs3-primary-color', '#ff0000')
+**Mètodes:** `show()`, `hide()`
 
-// Inicialitzar el sistema de temes amb opcions
-initThemeSystem({ defaultTheme: 'dark' })
-```
+#### HTML inline (index2.html)
 
-### Mixin `withThemeSupport`
+```html
+<!-- Defineix el modal a qualsevol lloc del body -->
+<zs3-modal id="modal-medium" size="medium" backdrop close-on-backdrop close-on-escape>
+    <div style="padding:1.5rem">
+        <h3 style="margin-top:0">Modal Medium</h3>
+        <p>Contingut del modal.</p>
+        <zs3-button variant="primary"
+            zs3-click="document.getElementById('modal-medium').$.hide()">
+            Tancar
+        </zs3-button>
+    </div>
+</zs3-modal>
 
-Per afegir suport de temes a un component personalitzat que no hereti de `$BaseComponent`:
+<zs3-modal id="modal-fullscreen" size="fullscreen" backdrop close-on-escape>
+    <div style="padding:2rem">
+        <h2>Modal Fullscreen</h2>
+        <zs3-button variant="primary"
+            zs3-click="document.getElementById('modal-fullscreen').$.hide()">
+            Tancar
+        </zs3-button>
+    </div>
+</zs3-modal>
 
-```typescript
-import { withThemeSupport } from 'zs3-ui-components'
+<!-- Scrollable -->
+<zs3-modal id="modal-scroll" size="medium" backdrop close-on-backdrop close-on-escape scrollable>
+    <div style="padding:1.5rem">
+        <h3>Scrollable</h3>
+        <!-- molts paràgrafs... -->
+        <zs3-button variant="primary"
+            zs3-click="document.getElementById('modal-scroll').$.hide()">
+            Tancar
+        </zs3-button>
+    </div>
+</zs3-modal>
 
-class MyElement extends withThemeSupport(HTMLElement) {
-    render() { /* ... */ }
-}
+<zs3-button variant="primary"   zs3-click="document.getElementById('modal-medium').$.show()">Obrir Medium</zs3-button>
+<zs3-button variant="secondary" zs3-click="document.getElementById('modal-fullscreen').$.show()">Fullscreen</zs3-button>
+<zs3-button variant="info"      zs3-click="document.getElementById('modal-scroll').$.show()">Scrollable</zs3-button>
 ```
 
-### CSS Variables
+#### TypeScript programàtic (index3.ts)
 
-Totes les variables utilitzen el prefix `zs3-`.
+```ts
+import { $Modal, $Button } from 'zs3-ui-components'
 
-#### Variables globals (compartides per tots els temes)
+const modal = new $Modal()
+modal.setAttribute('size', 'medium')
+modal.setAttribute('backdrop', '')
+modal.setAttribute('close-on-backdrop', '')
+modal.setAttribute('close-on-escape', '')
 
-```css
-:root {
-    /* Fonts */
-    --zs3-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-    --zs3-font-family-mono: 'Courier New', Courier, monospace;
-
-    /* Mides de font */
-    --zs3-font-size-xs: 0.75rem;
-    --zs3-font-size-sm: 0.875rem;
-    --zs3-font-size-base: 1rem;
-    --zs3-font-size-lg: 1.125rem;
-    --zs3-font-size-xl: 1.25rem;
-    --zs3-font-size-2xl: 1.5rem;
-    --zs3-font-size-3xl: 1.875rem;
-
-    /* Espaiat */
-    --zs3-spacing-xs: 0.25rem;
-    --zs3-spacing-sm: 0.5rem;
-    --zs3-spacing-md: 1rem;
-    --zs3-spacing-lg: 1.5rem;
-    --zs3-spacing-xl: 2rem;
-    --zs3-spacing-2xl: 3rem;
-}
-```
+const content = document.createElement('div')
+content.style.padding = '1.5rem'
 
-#### Variables per tema
-
-Cada tema defineix les seguents variables:
-
-| Variable | Descripcio | Exemple (light) |
-|----------|------------|-----------------|
-| `--zs3-bg-color` | Color de fons | `#ffffff` |
-| `--zs3-fg-color` | Color de text | `#111827` |
-| `--zs3-primary-color` | Color primari | `#3b82f6` |
-| `--zs3-primary-hover-color` | Color primari hover | `#2563eb` |
-| `--zs3-success-color` | Color d'exit | `#10b981` |
-| `--zs3-warning-color` | Color d'advertencia | `#f59e0b` |
-| `--zs3-error-color` | Color d'error | `#ef4444` |
-| `--zs3-info-color` | Color informatiu | `#06b6d4` |
-| `--zs3-border-color` | Color de vora | `#d1d5db` |
-| `--zs3-border-radius` | Radi de vora | `0.375rem` |
-| `--zs3-shadow-sm` | Ombra petita | `0 1px 2px 0 rgba(0,0,0,0.05)` |
-| `--zs3-shadow-md` | Ombra mitjana | `0 4px 6px -1px rgba(0,0,0,0.1)` |
-| `--zs3-shadow-lg` | Ombra gran | `0 10px 15px -3px rgba(0,0,0,0.1)` |
-| `--zs3-shadow-xl` | Ombra extra gran | `0 20px 25px -5px rgba(0,0,0,0.1)` |
-| `--zs3-transition-fast` | Transicio rapida | `150ms ease-in-out` |
-| `--zs3-transition-base` | Transicio base | `250ms ease-in-out` |
-| `--zs3-transition-slow` | Transicio lenta | `500ms ease-in-out` |
-| `--zs3-overlay` | Color del backdrop | `rgba(0,0,0,0.5)` |
-
-#### Valors per cada tema
-
-<details>
-<summary><strong>Light</strong></summary>
+const closeBtn = new $Button()
+closeBtn.textContent = 'Tancar'
+closeBtn.variant = 'primary'
+closeBtn.addEventListener('zs3-click', () => modal.hide())
+content.append(closeBtn)
 
-```css
-[data-theme='light'] {
-    --zs3-bg-color: #ffffff;
-    --zs3-fg-color: #111827;
-    --zs3-primary-color: #3b82f6;
-    --zs3-primary-hover-color: #2563eb;
-    --zs3-success-color: #10b981;
-    --zs3-warning-color: #f59e0b;
-    --zs3-error-color: #ef4444;
-    --zs3-info-color: #06b6d4;
-    --zs3-border-color: #d1d5db;
-    --zs3-border-radius: 0.375rem;
-}
+modal.append(content)
+document.body.append(modal)  // els modals van al body directament
+
+const openBtn = new $Button()
+openBtn.textContent = 'Obrir Modal'
+openBtn.variant = 'primary'
+openBtn.addEventListener('zs3-click', () => modal.show())
 ```
-</details>
 
-<details>
-<summary><strong>Light Blue</strong></summary>
+---
 
-```css
-[data-theme='light-blue'] {
-    --zs3-bg-color: #ffffffe0;
-    --zs3-fg-color: #084cb1;
-    --zs3-primary-color: #3b82f6;
-    --zs3-primary-hover-color: #2563eb;
-    --zs3-border-color: #3b82f6;
-}
-```
-</details>
+### zs3-modal-dialog
 
-<details>
-<summary><strong>Dark</strong></summary>
+Diàleg modal amb títol, missatge, icona, botons d'acció configurables i mètodes estàtics per als casos d'ús comuns.
 
-```css
-[data-theme='dark'] {
-    --zs3-bg-color: #111827;
-    --zs3-fg-color: #f9fafb;
-    --zs3-primary-color: #60a5fa;
-    --zs3-primary-hover-color: #3b82f6;
-    --zs3-success-color: #34d399;
-    --zs3-warning-color: #fbbf24;
-    --zs3-error-color: #f87171;
-    --zs3-info-color: #22d3ee;
-    --zs3-border-color: #4b5563;
-}
-```
-</details>
+**Atributs:**
 
-<details>
-<summary><strong>Elegant</strong></summary>
+| Atribut | Descripció |
+|---------|------------|
+| `title` / `i18n-title` | Títol del diàleg |
+| `message` / `i18n-message` | Missatge del cos |
+| `icon` | Icona al costat del títol |
+| `size` | Mida (`small`, `medium`, `large`) |
+| `show-accept` | Mostra el botó d'acceptar |
+| `show-cancel` | Mostra el botó de cancel·lar |
+| `show-close` | Mostra el botó de tancar |
+| `accept-text` / `i18n-accept-text` | Text del botó acceptar |
+| `cancel-text` / `i18n-cancel-text` | Text del botó cancel·lar |
+| `accept-variant` | Variant del botó acceptar |
+| `backdrop` | Activa el fons fosc |
+| `close-on-escape` | Tanca amb ESC |
+
+**Esdeveniments:** `zs3-dialog-accept`, `zs3-dialog-cancel`, `zs3-dialog-close`
+
+#### Mètodes estàtics (Promises)
+
+```ts
+import { $ModalDialog, i18n } from 'zs3-ui-components'
+
+// Alert (es resol quan es tanca)
+await $ModalDialog.alert({
+    title: 'Atenció',
+    message: 'El fitxer ha estat guardat correctament.',
+})
 
-```css
-[data-theme='elegant'] {
-    --zs3-bg-color: #faf8f5;
-    --zs3-fg-color: #2d2520;
-    --zs3-font-family: 'Georgia', 'Times New Roman', serif;
-    --zs3-primary-color: #8b5a3c;
-    --zs3-primary-hover-color: #6f4830;
-    --zs3-success-color: #5d8a66;
-    --zs3-warning-color: #d4a574;
-    --zs3-error-color: #a65858;
-    --zs3-info-color: #5a7d9a;
-    --zs3-border-color: #c9baa5;
-    --zs3-border-radius: 0.5rem;
-}
-```
-</details>
+// Alert amb i18n
+await $ModalDialog.alertI18n({
+    i18nTitle: 'section.dialog.alert.title',
+    i18nMessage: 'section.dialog.alert.message',
+})
 
-<details>
-<summary><strong>Modern</strong></summary>
+// Confirm (retorna true/false)
+const confirmed = await $ModalDialog.confirm({
+    title: 'Confirmació',
+    message: 'Estàs segur que vols continuar?',
+})
 
-```css
-[data-theme='modern'] {
-    --zs3-bg-color: #fefefe;
-    --zs3-fg-color: #beb0b0;
-    --zs3-primary-color: #6366f1;
-    --zs3-primary-hover-color: #4f46e5;
-    --zs3-success-color: #14b8a6;
-    --zs3-warning-color: #f97316;
-    --zs3-error-color: #f43f5e;
-    --zs3-info-color: #0ea5e9;
-    --zs3-border-color: #e5e5e5;
-    --zs3-border-radius: 0.75rem;
-}
-```
-</details>
+// Confirm amb i18n
+const result = await $ModalDialog.confirmI18n({
+    i18nTitle: 'section.dialog.confirm.title',
+    i18nMessage: 'section.dialog.confirm.message',
+})
 
-<details>
-<summary><strong>High Contrast</strong></summary>
+// Prompt (retorna el valor introduït o null si cancel·la)
+const value = await $ModalDialog.prompt({
+    title: 'Introdueix un valor',
+    placeholder: 'Escriu aquí...',
+})
+if (value !== null) { console.log('Valor:', value) }
 
-```css
-[data-theme='high-contrast'] {
-    --zs3-bg-color: #000000;
-    --zs3-fg-color: #ffffff;
-    --zs3-primary-color: #0066ff;
-    --zs3-primary-hover-color: #0052cc;
-    --zs3-success-color: #00aa00;
-    --zs3-warning-color: #ff9900;
-    --zs3-error-color: #cc0000;
-    --zs3-info-color: #0099cc;
-    --zs3-border-color: #666666;
-    --zs3-border-radius: 0.25rem;
-}
+// Prompt amb i18n
+const val = await $ModalDialog.promptI18n({
+    i18nTitle: 'section.dialog.prompt.title',
+    placeholder: i18n.t('section.dialog.prompt.message'),
+})
+
+// Confirm Delete (diàleg especialitzat d'eliminació)
+const deleted = await $ModalDialog.confirmDelete('Element #42')
+if (deleted) { /* eliminar l'element */ }
 ```
-</details>
 
-<details>
-<summary><strong>System</strong></summary>
+#### HTML inline (index2.html)
 
-Utilitza els mateixos valors que `light` per defecte, i canvia automaticament a valors de `dark` quan `prefers-color-scheme: dark` esta actiu.
-</details>
+```html
+<!-- Diàleg personalitzat declarat en HTML -->
+<zs3-modal-dialog
+    id="custom-dialog"
+    i18n-title="section.dialog.confirm.title"
+    i18n-message="section.dialog.confirm.message"
+    icon="warning"
+    show-accept
+    show-cancel
+    accept-variant="warning"
+    i18n-accept-text="zs3.dialog.accept"
+    i18n-cancel-text="zs3.dialog.cancel"
+    backdrop
+    close-on-escape>
+</zs3-modal-dialog>
+
+<zs3-button variant="warning" icon="warning"
+    zs3-click="document.getElementById('custom-dialog').$.show()">
+    Obrir diàleg
+</zs3-button>
+
+<!-- Mètodes estàtics des de handlers inline (definits a index2.ts) -->
+<zs3-button variant="primary"   zs3-click="showDialogAlert()">Alert</zs3-button>
+<zs3-button variant="info"      zs3-click="showDialogConfirm()">Confirm</zs3-button>
+<zs3-button variant="secondary" zs3-click="showDialogPrompt()">Prompt</zs3-button>
+<zs3-button variant="danger" icon="trash" zs3-click="showDialogDelete()">Confirm Delete</zs3-button>
+<div id="dialog-output">Resultat del diàleg...</div>
+```
+
+```ts
+// index2.ts — handlers globals per als mètodes estàtics
+window.showDialogAlert = async () => {
+    await $ModalDialog.alertI18n({
+        i18nTitle: 'section.dialog.alert.title',
+        i18nMessage: 'section.dialog.alert.message',
+    })
+    setOutput('dialog-output', 'Alert tancat.')
+}
 
----
+window.showDialogConfirm = async () => {
+    const result = await $ModalDialog.confirmI18n({
+        i18nTitle: 'section.dialog.confirm.title',
+        i18nMessage: 'section.dialog.confirm.message',
+    })
+    setOutput('dialog-output', result ? '✓ Confirmat!' : '✗ Cancel·lat')
+}
 
-## Internacionalitzacio ($I18n)
+window.showDialogPrompt = async () => {
+    const value = await $ModalDialog.promptI18n({
+        i18nTitle: 'section.dialog.prompt.title',
+        placeholder: i18n.t('section.dialog.prompt.message'),
+    })
+    setOutput('dialog-output', value !== null ? `Valor: "${value}"` : 'Prompt cancel·lat')
+}
 
-Sistema complet d'internacionalitzacio amb interpolacio de parametres i actualitzacio automatica del DOM.
+window.showDialogDelete = async () => {
+    const result = await $ModalDialog.confirmDelete('Element #42')
+    setOutput('dialog-output', result ? '🗑 Element eliminat!' : '✗ Cancel·lat')
+}
 
-```typescript
-import { i18n } from 'zs3-ui-components'
+// Escolta l'event del diàleg personalitzat (HTML)
+function setupCustomDialogListener(): void {
+    const dialog = document.getElementById('custom-dialog')
+    dialog?.addEventListener('zs3-dialog-accept', () => {
+        setOutput('dialog-output', '✓ ACCEPTAT')
+        $Notification.success('Acció confirmada!', { position: 'top-right', duration: 3000 })
+    })
+    dialog?.addEventListener('zs3-dialog-cancel', () => {
+        setOutput('dialog-output', '✗ CANCEL·LAT')
+    })
+}
 ```
 
-### API
+#### TypeScript programàtic (index3.ts)
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `init()` | `(config?: Partial<I18nConfig>) => void` | Inicialitza el sistema i18n. Carrega l'idioma guardat si existeix. |
-| `load()` | `(locale: string, translations: Record<string,string>) => void` | Carrega traduccions per un idioma. |
-| `loadMultiple()` | `(locales: Record<string, Record<string,string>>) => void` | Carrega multiples idiomes alhora. |
-| `t()` | `(key: string, params?: Record<string, string\|number>) => string` | Tradueix una clau. Suporta interpolacio amb `{param}`. |
-| `setLocale()` | `(locale: string, callback?: (locale: string) => void) => void` | Estableix un nou idioma. Persisteix a localStorage. |
-| `getLocale()` | `() => string` | Obte l'idioma actual. |
-| `getSaved()` | `() => string \| null` | Obte l'idioma guardat a localStorage. |
-| `getBrowserLocale()` | `() => string` | Detecta l'idioma del navegador. |
-| `setBrowserLocale()` | `() => void` | Estableix l'idioma segons el navegador (si te traduccions). |
-| `has()` | `(key: string) => boolean` | Verifica si existeix una traduccio. |
-| `getAvailableLocales()` | `() => string[]` | Llista tots els idiomes carregats. |
-| `getTranslations()` | `(locale?: string) => Record<string,string>` | Obte totes les traduccions d'un idioma. |
+```ts
+import { $ModalDialog, $Button, $Notification } from 'zs3-ui-components'
 
-### Traduccions automatiques al DOM
+const dialog = new $ModalDialog()
+dialog.setAttribute('i18n-title', 'section.dialog.confirm.title')
+dialog.setAttribute('i18n-message', 'section.dialog.confirm.message')
+dialog.setAttribute('icon', 'warning')
+dialog.showAccept = true
+dialog.showCancel = true
+dialog.acceptVariant = 'warning'
+dialog.setAttribute('i18n-accept-text', 'zs3.dialog.accept')
+dialog.setAttribute('i18n-cancel-text', 'zs3.dialog.cancel')
+dialog.setAttribute('backdrop', '')
+dialog.setAttribute('close-on-escape', '')
+document.body.append(dialog)  // va al body directament
 
-Utilitzeu atributs `data-i18n` i `data-i18n-attr` per a traduccions automatiques:
-
-```html
-<!-- Tradueix el textContent -->
-<h1 data-i18n="page.title">Titol per defecte</h1>
+dialog.addEventListener('zs3-dialog-accept', () => {
+    $Notification.success('Acció confirmada!', { position: 'top-right', duration: 3000 })
+})
+dialog.addEventListener('zs3-dialog-cancel', () => {
+    console.log('Diàleg cancel·lat')
+})
 
-<!-- Tradueix atributs -->
-<input data-i18n-attr='{"placeholder": "input.placeholder", "aria-label": "input.label"}' />
+const openBtn = new $Button()
+openBtn.textContent = 'Obrir diàleg'
+openBtn.variant = 'warning'
+openBtn.icon = 'warning'
+openBtn.addEventListener('zs3-click', () => dialog.show())
 ```
 
-Quan canvieu l'idioma amb `setLocale()`, tots els elements amb `data-i18n` i `data-i18n-attr` s'actualitzen automaticament.
+---
 
-### Event
+### zs3-form
 
-```typescript
-window.addEventListener('zs3-locale-change', (e: CustomEvent) => {
-    console.log('Nou idioma:', e.detail.locale)
-    console.log('Idioma anterior:', e.detail.previousLocale)
-})
-```
+Formulari genèric amb camps configurables, validació, i18n complet i events de submit/cancel.
 
-### Exemple complet
+**Atributs:**
 
-```typescript
-import { i18n } from 'zs3-ui-components'
+| Atribut | Descripció |
+|---------|------------|
+| `title` / `i18n-title` | Títol del formulari |
+| `description` / `i18n-description` | Descripció |
+| `accept-text` / `i18n-accept-text` | Text del botó d'enviar |
+| `cancel-text` / `i18n-cancel-text` | Text del botó de cancel·lar |
+| `accept-variant` | Variant del botó d'enviar |
+| `show-cancel` | Mostra el botó de cancel·lar |
+
+**Tipus de camp `type`:** `text`, `email`, `password`, `number`, `tel`, `url`, `date`, `textarea`, `select`, `checkbox`
+
+**Validació per camp:** `required`, `minLength`, `maxLength`, `min`, `max`, `pattern`
+
+**Esdeveniments:** `zs3-form-submit` (amb `event.detail.values`), `zs3-form-cancel`
+
+#### TypeScript programàtic (index3.ts) — recomanat
+
+```ts
+import { $Form } from 'zs3-ui-components'
+
+const form = new $Form()
+form.setAttribute('i18n-title', 'form.title')
+form.setAttribute('i18n-description', 'form.description')
+form.showCancel = true
+form.acceptVariant = 'success'
+
+form.setFields([
+    {
+        name: 'name',
+        label: 'Nom',
+        i18nLabel: 'form.field.name',
+        type: 'text',
+        required: true,
+        placeholder: 'Nom',
+        i18nPlaceholder: 'form.field.name.placeholder',
+        validation: { minLength: 2, maxLength: 50 },
+    },
+    {
+        name: 'email',
+        label: 'Correu',
+        i18nLabel: 'form.field.email',
+        type: 'email',
+        required: true,
+        i18nPlaceholder: 'form.field.email.placeholder',
+    },
+    {
+        name: 'age',
+        label: 'Edat',
+        i18nLabel: 'form.field.age',
+        type: 'number',
+        required: true,
+        validation: { min: 18, max: 120 },
+    },
+    {
+        name: 'birthdate',
+        label: 'Data de naixement',
+        type: 'date',
+        required: false,
+    },
+    {
+        name: 'country',
+        label: 'País',
+        i18nLabel: 'form.field.country',
+        type: 'select',
+        required: true,
+        i18nPlaceholder: 'form.field.country.placeholder',
+        options: [
+            { value: 'es', label: 'Espanya',    i18nLabel: 'form.country.spain' },
+            { value: 'fr', label: 'França',     i18nLabel: 'form.country.france' },
+            { value: 'it', label: 'Itàlia',     i18nLabel: 'form.country.italy' },
+            { value: 'de', label: 'Alemanya',   i18nLabel: 'form.country.germany' },
+            { value: 'uk', label: 'Regne Unit', i18nLabel: 'form.country.uk' },
+        ],
+    },
+    {
+        name: 'bio',
+        label: 'Biografia',
+        i18nLabel: 'form.field.bio',
+        type: 'textarea',
+        required: false,
+        i18nPlaceholder: 'form.field.bio.placeholder',
+        rows: 3,
+        validation: { maxLength: 500 },
+    },
+    {
+        name: 'terms',
+        label: 'Accepto els termes i condicions',
+        i18nLabel: 'form.field.terms',
+        type: 'checkbox',
+        required: true,
+    },
+])
 
-// Carregar traduccions
-i18n.loadMultiple({
-    ca: { 'hello': 'Hola {name}!', 'btn.save': 'Desar' },
-    es: { 'hello': 'Hola {name}!', 'btn.save': 'Guardar' },
-    en: { 'hello': 'Hello {name}!', 'btn.save': 'Save' },
+form.addEventListener('zs3-form-submit', (e: Event) => {
+    const { values } = (e as CustomEvent).detail
+    console.log('Dades enviades:', values)
+    // values → { name: 'Joan', email: 'joan@mail.com', country: 'es', terms: true, ... }
 })
 
-// Inicialitzar
-i18n.init({ locale: 'ca', fallbackLocale: 'en' })
-
-// Traduir amb interpolacio
-i18n.t('hello', { name: 'Joan' }) // 'Hola Joan!'
+form.addEventListener('zs3-form-cancel', () => {
+    form.reset()
+})
 
-// Canviar idioma
-i18n.setLocale('en')
-i18n.t('hello', { name: 'Joan' }) // 'Hello Joan!'
+document.getElementById('app')!.append(form)
 ```
 
 ---
 
-## Bus d'Events (EventBus)
-
-Sistema de publicació/subscripció (pub/sub) per a la comunicació desacoblada entre components i mòduls. Inclou una instància global `eventBus` i la classe `EventBus` per crear busos addicionals independents.
-
-```typescript
-import { eventBus } from 'zs3-ui-components'
-```
+### zs3-login-form
 
-### API
+Formulari de login preconstruït amb camps d'email i contrasenya, opció de botó de registre i traduccions integrades.
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `on()` | `<T>(event: string, handler: (payload: T) => void) => () => void` | Subscriu un handler a un event. Retorna una funció per dessubscriure's. |
-| `once()` | `<T>(event: string, handler: (payload: T) => void) => void` | Subscriu un handler d'un sol ús (s'elimina automàticament en ser cridat). |
-| `emit()` | `<T>(event: string, payload?: T) => void` | Emet un event i passa el payload a tots els handlers registrats. |
-| `off()` | `(event: string) => void` | Elimina tots els handlers d'un event concret. |
-| `clear()` | `() => void` | Elimina tots els handlers de tots els events. |
+**Atributs:** `show-register`, `show-cancel`, `i18n-login-text`
 
-### Exemples
+**Esdeveniments:** `zs3-form-submit` (amb `detail.values.email` i `detail.values.password`), `zs3-login-register`
 
-```typescript
-import { eventBus } from 'zs3-ui-components'
+#### HTML inline (index2.html) — en un modal
 
-// Subscriure's a un event tipat
-const unsub = eventBus.on<{ userId: number }>('user:login', ({ userId }) => {
-  console.log('Usuari autenticat:', userId)
+```html
+<zs3-modal-dialog id="dlg-login" i18n-title="zs3.login.title" size="medium" backdrop close-on-escape>
+    <zs3-login-form
+        show-register
+        zs3-form-submit="document.getElementById('dlg-login').$.hide(); document.getElementById('auth-out').textContent = 'Login: ' + JSON.stringify(event.detail.values)"
+        zs3-login-register="document.getElementById('dlg-login').$.hide(); document.getElementById('dlg-register').$.show()">
+    </zs3-login-form>
+</zs3-modal-dialog>
+
+<zs3-button variant="primary" icon="login" position="left"
+    zs3-click="document.getElementById('dlg-login').$.show()">
+    Iniciar sessió
+</zs3-button>
+<div id="auth-out">Resultat auth...</div>
+```
+
+#### TypeScript programàtic (index3.ts)
+
+```ts
+import { $LoginForm, $ModalDialog } from 'zs3-ui-components'
+
+const loginDialog = new $ModalDialog()
+loginDialog.setAttribute('i18n-title', 'zs3.login.title')
+loginDialog.setAttribute('size', 'medium')
+loginDialog.setAttribute('backdrop', '')
+loginDialog.setAttribute('close-on-escape', '')
+document.body.append(loginDialog)
+
+const loginForm = new $LoginForm()
+loginForm.showRegister = true
+
+loginForm.addEventListener('zs3-form-submit', (e: Event) => {
+    const { values } = (e as CustomEvent).detail
+    loginDialog.hide()
+    console.log('Login:', values.email, values.password)
 })
 
-// Emetre l'event
-eventBus.emit('user:login', { userId: 42 })
+loginForm.addEventListener('zs3-login-register', () => {
+    loginDialog.hide()
+    registerDialog.show()  // mostra el diàleg de registre
+})
 
-// Dessubscriure's
-unsub()
+loginDialog.append(loginForm)
 
-// Handler d'un sol ús
-eventBus.once('app:ready', () => {
-  console.log('Inicialitzacio completada')
+// Login inline (sense modal)
+const inlineLogin = new $LoginForm()
+inlineLogin.showRegister = true
+inlineLogin.showCancel = true
+inlineLogin.addEventListener('zs3-form-submit', (e: Event) => {
+    const { values } = (e as CustomEvent).detail
+    console.log('Login inline:', values)
 })
+document.getElementById('app')!.append(inlineLogin)
+```
 
-// Eliminar tots els handlers d'un event
-eventBus.off('user:login')
+---
 
-// Netejar tots els events (util en tests)
-eventBus.clear()
-```
+### zs3-register-form
 
-### Crear un bus personalitzat
+Formulari de registre preconstruït amb camps nom, email, contrasenya i confirmació.
 
-```typescript
-import { EventBus } from 'zs3-ui-components'
+**Atributs:** `show-cancel`, `i18n-register-text`
 
-const myBus = new EventBus()
-myBus.on('custom:event', (data) => console.log(data))
-myBus.emit('custom:event', 'hola')
-```
+**Esdeveniments:** `zs3-form-submit`, `zs3-form-cancel`
 
----
-
-## Contenidor de Dependencies (DIContainer)
-
-Contenidor d'injecció de dependències lleuger. Permet registrar serveis com a **singleton** (instància compartida) o **transient** (nova instància en cada resolució), i recuperar-los per clau. Inclou una instància global `diContainer`.
-
-```typescript
-import { diContainer } from 'zs3-ui-components'
-```
-
-### API
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `registerSingleton()` | `<T>(key: string, factory: () => T) => void` | Registra un servei singleton. La fàbrica s'executa una sola vegada i la instància es reutilitza. |
-| `registerTransient()` | `<T>(key: string, factory: () => T) => void` | Registra un servei transient. La fàbrica s'executa en cada resolució retornant una nova instància. |
-| `resolve()` | `<T>(key: string) => T` | Retorna la instància del servei associat a la clau. Llança `Error` si la clau no existeix. |
-| `has()` | `(key: string) => boolean` | Comprova si un servei ha estat registrat. |
-| `clear()` | `() => void` | Elimina tots els registres (util per a tests). |
-
-### Exemples
-
-```typescript
-import { diContainer } from 'zs3-ui-components'
+#### HTML inline
 
-// Registrar un singleton
-diContainer.registerSingleton('apiClient', () => new ApiClient('https://api.example.com'))
-
-// La mateixa instancia es retorna sempre
-const api1 = diContainer.resolve<ApiClient>('apiClient')
-const api2 = diContainer.resolve<ApiClient>('apiClient')
-console.log(api1 === api2) // true
-
-// Registrar un servei transient
-diContainer.registerTransient('validator', () => new FormValidator())
-
-// Cada resolucio retorna una nova instancia
-const v1 = diContainer.resolve<FormValidator>('validator')
-const v2 = diContainer.resolve<FormValidator>('validator')
-console.log(v1 === v2) // false
-
-// Comprovar si existeix
-if (!diContainer.has('logger')) {
-  diContainer.registerSingleton('logger', () => new Logger())
-}
-
-// Netejar (util en tests)
-afterEach(() => {
-  diContainer.clear()
+```html
+<zs3-modal-dialog id="dlg-register" i18n-title="zs3.register.title" size="medium" backdrop close-on-escape>
+    <zs3-register-form
+        show-cancel
+        zs3-form-submit="document.getElementById('dlg-register').$.hide()"
+        zs3-form-cancel="document.getElementById('dlg-register').$.hide()">
+    </zs3-register-form>
+</zs3-modal-dialog>
+```
+
+#### TypeScript programàtic
+
+```ts
+import { $RegisterForm, $ModalDialog } from 'zs3-ui-components'
+
+const registerDialog = new $ModalDialog()
+registerDialog.setAttribute('i18n-title', 'zs3.register.title')
+registerDialog.setAttribute('size', 'medium')
+registerDialog.setAttribute('backdrop', '')
+registerDialog.setAttribute('close-on-escape', '')
+document.body.append(registerDialog)
+
+const registerForm = new $RegisterForm()
+registerForm.showCancel = true
+
+registerForm.addEventListener('zs3-form-submit', (e: Event) => {
+    const { values } = (e as CustomEvent).detail
+    registerDialog.hide()
+    console.log('Registre:', values)
 })
-```
-
-### Crear un contenidor personalitzat
-
-```typescript
-import { DIContainer } from 'zs3-ui-components'
-
-const container = new DIContainer()
-container.registerSingleton('config', () => ({ apiUrl: 'https://api.example.com' }))
-const config = container.resolve<{ apiUrl: string }>('config')
+registerForm.addEventListener('zs3-form-cancel', () => registerDialog.hide())
+registerDialog.append(registerForm)
 ```
 
 ---
 
-## Router (SPA)
-
-Router client-side per a aplicacions **SPA (Single Page Application)**. Gestiona la navegació basada en `history.pushState`, intercepta clicks a enllaços `<a data-link>`, resol rutes amb paràmetres dinàmics i suporta guards per protegir l'accés a pàgines.
-
-```typescript
-import { Router } from 'zs3-ui-components'
-import type { Route, RouteGuard, RouteContext } from 'zs3-ui-components'
-```
-
-### Tipus
-
-#### `Route`
-
-| Camp | Tipus | Requerit | Descripcio |
-|------|-------|----------|------------|
-| `path` | `string` | Sí | Path de la ruta. Pot contenir segments dinàmics (`:param`). Usa `'*'` per a la ruta wildcard (pàgina 404). |
-| `component` | `() => Promise<{ default: ... }>` | Sí | Funció de càrrega lazy del component de la pàgina. |
-| `title` | `string` | No | Títol que s'aplica a `document.title` en activar la ruta. |
-| `guard` | `RouteGuard` | No | Funció guard que controla l'accés a la ruta. |
-
-#### `RouteGuard`
-
-Funció executada abans de muntar el component d'una ruta. Rep un [`RouteContext`](#routecontext) i ha de retornar:
-
-- `true` — permet la navegació.
-- `false` — cancel·la la navegació sense redirigir.
-- `string` — redirigeix al path indicat.
-
-```typescript
-type RouteGuard = (context: RouteContext) => boolean | string
-```
-
-#### `RouteContext`
-
-| Camp | Tipus | Descripcio |
-|------|-------|------------|
-| `path` | `string` | Path complet de la URL actual. |
-| `params` | `Record<string, string>` | Paràmetres dinàmics extrets del path (p.ex. `{ id: '42' }`). |
-| `query` | `URLSearchParams` | Query string de la URL actual. |
-
-### API de `Router`
-
-#### Constructor
-
-```typescript
-new Router(routes: Route[], outlet: HTMLElement)
-```
-
-| Paràmetre | Tipus | Descripcio |
-|-----------|-------|------------|
-| `routes` | `Route[]` | Llista de rutes de l'aplicació. |
-| `outlet` | `HTMLElement` | Element del DOM on es muntaran els components de cada pàgina. |
-
-#### Mètodes públics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `start()` | `() => void` | Inicia el router: escolta `popstate`, intercepta clicks a `<a data-link>` i resol la URL actual. Cridar una sola vegada a l'inici. |
-| `navigate()` | `(path: string) => Promise<void>` | Navega programàticament a un path. No fa res si el path és el mateix que l'actual. |
-| `back()` | `() => void` | Navega a la pàgina anterior de l'historial del navegador. |
-
-### Exemple complet
-
-```typescript
-import { Router } from 'zs3-ui-components'
-import type { Route, RouteGuard } from 'zs3-ui-components'
-
-// Guard d'autenticacio
-const authGuard: RouteGuard = ({ path }) => {
-  return isLoggedIn() ? true : '/login'
-}
+### zs3-recover-password-form
 
-const routes: Route[] = [
-  {
-    path: '/',
-    component: () => import('./pages/HomePage'),
-    title: 'Inici',
-  },
-  {
-    path: '/users/:id',
-    component: () => import('./pages/UserPage'),
-    title: 'Usuari',
-    guard: authGuard,
-  },
-  {
-    path: '/login',
-    component: () => import('./pages/LoginPage'),
-    title: 'Iniciar sessio',
-  },
-  {
-    path: '*',
-    component: () => import('./pages/NotFoundPage'),
-    title: 'Pàgina no trobada',
-  },
-]
+Formulari de recuperació de contrasenya amb camp d'email.
 
-const router = new Router(routes, document.getElementById('app')!)
-router.start()
-```
+**Atributs:** `show-cancel`, `i18n-submit-text`, `i18n-description`
 
-### Navegació en plantilles HTML
+**Esdeveniments:** `zs3-form-submit` (amb `detail.values.email`), `zs3-form-cancel`
 
-Afegeix l'atribut `data-link` a qualsevol `<a>` perquè el router l'intercepti sense recarregar la pàgina:
+#### HTML inline
 
 ```html
-<nav>
-  <a href="/" data-link>Inici</a>
-  <a href="/users/42" data-link>Perfil</a>
-</nav>
-```
-
-### Navegació programàtica
-
-```typescript
-// Navegar a una pàgina
-await router.navigate('/users/42')
-
-// Tornar enrere
-router.back()
+<zs3-modal-dialog id="dlg-recover" i18n-title="zs3.recover.title" size="small" backdrop close-on-escape>
+    <zs3-recover-password-form
+        i18n-description="zs3.recover.description"
+        show-cancel
+        zs3-form-submit="document.getElementById('dlg-recover').$.hide()"
+        zs3-form-cancel="document.getElementById('dlg-recover').$.hide()">
+    </zs3-recover-password-form>
+</zs3-modal-dialog>
+```
+
+#### TypeScript programàtic
+
+```ts
+import { $RecoverPasswordForm, $ModalDialog } from 'zs3-ui-components'
+
+const recoverDialog = new $ModalDialog()
+recoverDialog.setAttribute('i18n-title', 'zs3.recover.title')
+recoverDialog.setAttribute('size', 'small')
+recoverDialog.setAttribute('backdrop', '')
+recoverDialog.setAttribute('close-on-escape', '')
+document.body.append(recoverDialog)
+
+const recoverForm = new $RecoverPasswordForm()
+recoverForm.setAttribute('i18n-description', 'zs3.recover.description')
+recoverForm.showCancel = true
+
+recoverForm.addEventListener('zs3-form-submit', (e: Event) => {
+    const { values } = (e as CustomEvent).detail
+    recoverDialog.hide()
+    console.log('Email per recuperar:', values.email)
+})
+recoverForm.addEventListener('zs3-form-cancel', () => recoverDialog.hide())
+recoverDialog.append(recoverForm)
 ```
 
 ---
 
-## Components
-
-### zs3-button
-
-Boto personalitzat amb suport per icones, variants, mides i efecte float.
-
-#### Atributs
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `icon` | `string` | - | Nom de la icona a mostrar. |
-| `icon-size` | `string` | - | Mida de la icona. |
-| `position` | `'left' \| 'right'` | `'right'` | Posicio de la icona. |
-| `variant` | `'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info'` | - | Variant d'estil del boto. |
-| `size` | `'sm' \| 'md' \| 'lg'` | - | Mida del boto. |
-| `rounded` | `boolean` | `false` | Boto completament arrodonit. |
-| `disabled` | `boolean` | `false` | Desactiva el boto. |
-| `loading` | `boolean` | `false` | Mostra estat de carrega (spinner). |
-| `float` | `'top' \| 'bottom' \| 'left' \| 'right'` | - | Posicio flotant. |
-| `move` | `'x' \| 'y' \| 'xy'` | - | Direccio de moviment (drag). |
-| `i18n-text` | `string` | - | Clau i18n per al text del boto. |
-| `i18n-aria-label` | `string` | - | Clau i18n per a l'aria-label. |
-
-#### Events
-
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-click` | `{ button, originalEvent }` | El boto ha estat clicat. |
-| `zs3-icon-click` | `{ button, originalEvent }` | La icona del boto ha estat clicada. |
-
-#### Metodes publics
+### zs3-window
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `setText()` | `(text: string) => void` | Estableix el text del boto. |
-| `getText()` | `() => string` | Obte el text del boto. |
-| `click()` | `() => void` | Simula un clic programatic. |
-| `setLoading()` | `(loading: boolean) => void` | Estableix l'estat de carrega. |
-| `setDisabled()` | `(disabled: boolean) => void` | Estableix l'estat desactivat. |
+Finestra draggable amb barra de títol, botons de minimitzar/maximitzar/tancar i contingut personalitzable.
 
-#### CSS Variables del boto
+**Atributs:**
 
-```css
-:host {
-    --btn-padding-sm: 0.5rem 0.75rem;
-    --btn-padding-md: 0.625rem 1rem;
-    --btn-padding-lg: 0.75rem 1.5rem;
-    --btn-font-size-sm: var(--zs3-font-size-sm);
-    --btn-font-size-md: var(--zs3-font-size-base);
-    --btn-font-size-lg: var(--zs3-font-size-lg);
-    --btn-gap: 0.5rem;
-    --btn-radius: var(--zs3-border-radius);
-    --btn-transition: all var(--zs3-transition-fast);
-}
-```
+| Atribut | Descripció |
+|---------|------------|
+| `title` / `i18n-title` | Títol de la finestra |
+| `width` | Amplada (px, %, etc.) |
+| `move` | `x` `y` `xy` — permet arrossegar |
+| `closable` | Mostra el botó de tancar |
+| `minimizable` | Mostra el botó de minimitzar |
+| `maximizable` | Mostra el botó de maximitzar |
 
-#### Exemples
+#### HTML inline (index2.html)
 
 ```html
-<!-- Boto basic -->
-<zs3-button>Clic</zs3-button>
-
-<!-- Boto amb icona a l'esquerra -->
-<zs3-button icon="save" position="left" variant="primary">Desar</zs3-button>
-
-<!-- Boto de perill arrodonit -->
-<zs3-button variant="danger" rounded icon="trash">Eliminar</zs3-button>
-
-<!-- Boto en estat de carrega -->
-<zs3-button loading variant="success">Processant...</zs3-button>
+<!-- Contenidor relatiu per delimitar el moviment -->
+<div style="position:relative;height:260px;border:1px dashed #e5e7eb;border-radius:.5rem;overflow:hidden">
+    <zs3-window
+        title="Finestra Draggable"
+        width="280px"
+        move="xy"
+        closable
+        minimizable
+        maximizable
+        style="position:absolute;top:16px;left:16px">
+        <div style="padding:.75rem">
+            <p>Contingut HTML de la finestra.</p>
+            <zs3-button variant="success" icon="save" size="sm">Guardar</zs3-button>
+        </div>
+    </zs3-window>
+
+    <zs3-window
+        i18n-title="form.title"
+        width="240px"
+        move="xy"
+        closable
+        minimizable
+        style="position:absolute;top:16px;left:320px">
+        <div style="padding:.75rem">
+            <p>Títol via i18n-title.</p>
+        </div>
+    </zs3-window>
+</div>
+```
+
+#### TypeScript programàtic (index3.ts)
+
+```ts
+import { $Window, $Toolbar, $Button, $Notification } from 'zs3-ui-components'
+
+const container = document.createElement('div')
+container.style.cssText = 'position:relative;height:260px;border:1px dashed #e5e7eb;border-radius:.5rem;overflow:hidden'
+
+const win1 = new $Window()
+win1.setAttribute('title', 'Finestra 1 — Draggable')
+win1.setAttribute('width', '280px')
+win1.setAttribute('move', 'xy')
+win1.setAttribute('closable', '')
+win1.setAttribute('minimizable', '')
+win1.setAttribute('maximizable', '')
+win1.style.cssText = 'position:absolute;top:16px;left:16px'
+
+const toolbar = new $Toolbar()
+toolbar.setAttribute('direction', 'row')
+const bSave = new $Button()
+bSave.textContent = 'Guardar'
+bSave.variant = 'success'
+bSave.icon = 'save'
+bSave.size = 'sm'
+bSave.addEventListener('zs3-click', () =>
+    $Notification.success('Guardat!', { position: 'top-right', duration: 2000 })
+)
+toolbar.append(bSave)
+win1.append(toolbar)
 
-<!-- Boto amb i18n -->
-<zs3-button i18n-text="btn.save" variant="primary"></zs3-button>
+// Finestra amb i18n al títol
+const win2 = new $Window()
+win2.setAttribute('i18n-title', 'form.title')  // traducció automàtica
+win2.setAttribute('width', '240px')
+win2.setAttribute('move', 'xy')
+win2.setAttribute('closable', '')
+win2.style.cssText = 'position:absolute;top:16px;left:320px'
 
-<!-- Boto flotant -->
-<zs3-button float="right" icon="menu">Menu</zs3-button>
+container.append(win1, win2)
+document.getElementById('app')!.append(container)
 ```
 
 ---
 
-### zs3-icon
-
-Component d'icona SVG amb suport per transformacions, colors i interactivitat.
-
-#### Atributs
+## Utilities
 
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `name` | `string` | - | Nom de la icona (obligatori). |
-| `size` | `'small' \| 'medium' \| 'large' \| number` | `'medium'` | Mida: small=12px, medium=24px, large=36px, o valor numeric. |
-| `color` | `'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info' \| 'inherit'` | - | Variant de color. |
-| `stroke-width` | `number` | `2` | Amplada del trac SVG. |
-| `rotate` | `number` | `0` | Rotacio en graus. |
-| `flip` | `'horizontal' \| 'vertical' \| 'both'` | - | Direccio de reflexio. |
-| `clickable` | `boolean` | `false` | Fa la icona interactiva amb efecte hover. |
-| `i18n-aria-label` | `string` | - | Clau i18n per a l'aria-label. |
+### $Store — Reactive State
 
-#### Events
+Gestió d'estat reactiva amb reducers i subscripcions tipades. Inspirat en Redux.
 
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-icon-click` | `{ icon, name, originalEvent }` | Icona clicada (si `clickable`). |
+```ts
+import { $Store } from 'zs3-ui-components'
 
-#### Metodes estatics
+interface CounterState { count: number }
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `$Icon.addIcon()` | `(name: string, path: string) => void` | Afegeix una icona personalitzada (SVG path). |
-| `$Icon.addIcons()` | `(icons: Record<string,string>) => void` | Afegeix multiples icones. |
-| `$Icon.getAvailableIcons()` | `() => string[]` | Llista totes les icones disponibles. |
+const counterStore = new $Store<CounterState>({ count: 0 })
 
-#### Icones disponibles
+// Registra reducers
+counterStore.registerReducer('increment', (state) => ({ count: state.count + 1 }))
+counterStore.registerReducer('decrement', (state) => ({ count: Math.max(0, state.count - 1) }))
+counterStore.registerReducer('reset',     ()       => ({ count: 0 }))
+counterStore.registerReducer('add',       (state, payload) => ({ count: state.count + (payload as number) }))
 
-`increase`, `decrease`, `error`, `warning`, `information`, `close`, `left-arrow`, `right-arrow`, `up-arrow`, `down-arrow`, `menu`, `accept`, `cancel`, `search`, `delete`, `dark`, `sun`, `users`, `copy`, `trash`, `upload`, `logout`, `login`, `moon`, `modal`, `save`, `edit`, `download`, `settings`, `home`, `star`, `heart`, `filter`, `refresh`, `lock`, `unlock`, `bell`, `mail`, `phone`, `calendar`, `clock`, `eye`, `eye-off`, `plus`, `minus`, `check`, `x`
+// Subscriu-te als canvis
+counterStore.subscribe('*', (state) => {
+    document.getElementById('counter')!.textContent = String(state.count)
+})
 
-#### Exemples
+// Subscripció per acció específica
+counterStore.subscribe('increment', (state) => {
+    console.log('Increment! Nou valor:', state.count)
+})
 
-```html
-<zs3-icon name="warning"></zs3-icon>
-<zs3-icon name="users" size="large" color="primary"></zs3-icon>
-<zs3-icon name="right-arrow" rotate="90"></zs3-icon>
-<zs3-icon name="menu" flip="horizontal" clickable></zs3-icon>
-<zs3-icon name="heart" size="48" color="danger" stroke-width="1.5"></zs3-icon>
-```
+// Dispatch
+counterStore.dispatch('increment')
+counterStore.dispatch('add', 10)
+counterStore.dispatch('reset')
 
-```typescript
-// Afegir icona personalitzada
-$Icon.addIcon('custom', '<path d="M12 2L2 22h20z"/>')
+// Llegir l'estat actual
+const current = counterStore.getState()
 ```
 
----
-
-### zs3-toolbar
-
-Contenidor per organitzar botons i elements interactius.
-
-#### Atributs
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `direction` | `'row' \| 'column'` | `'row'` | Direccio del layout. |
-| `align` | `'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around'` | - | Alineacio dels elements. |
-| `gap` | `string` | `'0.625rem'` | Espai entre elements (valor CSS). |
-| `variant` | `'default' \| 'compact' \| 'spacious'` | - | Variant d'estil. |
-| `rounded` | `boolean` | `false` | Toolbar arrodonit. |
-| `float` | `'top' \| 'bottom' \| 'left' \| 'right'` | - | Posicio flotant. |
-| `move` | `'x' \| 'y' \| 'xy'` | - | Direccio de moviment (drag). |
-| `i18n-aria-label` | `string` | - | Clau i18n per a l'aria-label. |
-
-#### Events
-
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-toolbar-click` | `{ toolbar, button, index, originalEvent }` | Un boto del toolbar ha estat clicat. |
-| `zs3-button-added` | `{ toolbar, button, count }` | S'ha afegit un boto programaticament. |
-| `zs3-button-removed` | `{ toolbar, button, index, count }` | S'ha eliminat un boto. |
-| `zs3-buttons-cleared` | `{ toolbar, removedCount }` | S'han eliminat tots els botons. |
-
-#### Metodes publics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `addButton()` | `(button: $Button) => void` | Afegeix un boto al toolbar. |
-| `removeButton()` | `(index: number) => void` | Elimina un boto per index. |
-| `removeButtonElement()` | `(button: $Button) => void` | Elimina un boto per referencia. |
-| `getButton()` | `(index: number) => $Button \| null` | Obte un boto per index. |
-| `getButtons()` | `() => $Button[]` | Obte tots els botons. |
-| `getButtonCount()` | `() => number` | Obte el nombre de botons. |
-| `clearButtons()` | `() => void` | Elimina tots els botons. |
-| `enableAllButtons()` | `() => void` | Activa tots els botons. |
-| `disableAllButtons()` | `() => void` | Desactiva tots els botons. |
-| `showAllButtons()` | `() => void` | Mostra tots els botons. |
-| `hideAllButtons()` | `() => void` | Amaga tots els botons. |
-
-#### Exemples
+#### HTML inline (index2.html) + index2.ts
 
 ```html
-<!-- Toolbar horitzontal -->
-<zs3-toolbar>
-    <zs3-button icon="save">Desar</zs3-button>
-    <zs3-button icon="edit">Editar</zs3-button>
-    <zs3-button icon="trash" variant="danger">Eliminar</zs3-button>
-</zs3-toolbar>
-
-<!-- Toolbar vertical flotant -->
-<zs3-toolbar direction="column" float="left" gap="0.5rem">
-    <zs3-button icon="home"></zs3-button>
-    <zs3-button icon="settings"></zs3-button>
-</zs3-toolbar>
-
-<!-- Toolbar arrossegable -->
-<zs3-toolbar move="xy" rounded variant="compact">
-    <zs3-button icon="menu">Menu</zs3-button>
-</zs3-toolbar>
+<div id="store-counter" style="font-size:3.5rem;font-weight:700;text-align:center">0</div>
+<div>
+    <zs3-button variant="danger"  zs3-click="storeDecrement()">-1</zs3-button>
+    <zs3-button variant="success" zs3-click="storeIncrement()">+1</zs3-button>
+    <zs3-button                   zs3-click="storeReset()">Reset</zs3-button>
+    <zs3-button variant="info"    zs3-click="storeAdd(10)">+10</zs3-button>
+</div>
+<div id="store-log"></div>
+```
+
+```ts
+// index2.ts
+window.storeIncrement = () => counterStore.dispatch('increment')
+window.storeDecrement = () => counterStore.dispatch('decrement')
+window.storeReset     = () => counterStore.dispatch('reset')
+window.storeAdd       = (n: number) => counterStore.dispatch('add', n)
+
+counterStore.subscribe('*', (state) => {
+    const el = document.getElementById('store-counter')
+    if (el) el.textContent = String(state.count)
+
+    const logEl = document.getElementById('store-log')
+    if (logEl) {
+        const entry = document.createElement('div')
+        entry.textContent = `[${new Date().toLocaleTimeString()}] count = ${state.count}`
+        logEl.prepend(entry)
+    }
+})
 ```
 
----
-
-### zs3-notification
-
-Component de notificacions toast amb diversos tipus i posicions.
-
-#### Atributs
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `type` | `'error' \| 'warning' \| 'info' \| 'success'` | `'info'` | Tipus de notificacio. |
-| `title` | `string` | `''` | Titol de la notificacio. |
-| `message` | `string` | `''` | Missatge de la notificacio. |
-| `duration` | `number` | `5000` | Durada en mil-lisegons. `0` per no amagar automaticament. |
-| `position` | `NotificationPosition` | `'top-center'` | Posicio a la pantalla. |
-| `dismissible` | `boolean` | `true` | Mostra boto de tancar. |
-| `show-icon` | `boolean` | `true` | Mostra icona del tipus. |
-| `show-progress` | `boolean` | `false` | Mostra barra de progres. |
-| `auto-show` | `boolean` | `false` | Mostra automaticament al muntar-se. |
-| `i18n-title` | `string` | - | Clau i18n per al titol. |
-| `i18n-message` | `string` | - | Clau i18n per al missatge. |
-| `i18n-close-label` | `string` | - | Clau i18n per al boto de tancar. |
-
-**Posicions disponibles:** `top-center`, `top-left`, `top-right`, `bottom-center`, `bottom-left`, `bottom-right`
-
-#### Events
-
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-notification-show` | `{ notification, type, message }` | La notificacio s'ha mostrat. |
-| `zs3-notification-hide` | `{ notification, type, message }` | La notificacio s'ha amagat. |
-| `zs3-notification-dismiss` | `{ notification, type }` | L'usuari ha tancat la notificacio. |
-| `zs3-notification-click` | `{ notification, type }` | S'ha clicat la notificacio. |
-
-#### Metodes publics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `show()` | `() => void` | Mostra la notificacio. |
-| `hide()` | `() => void` | Amaga la notificacio. |
-| `toggle()` | `() => void` | Alterna la visibilitat. |
-| `update()` | `(config: Partial<NotificationConfig>) => void` | Actualitza el contingut. |
-| `isVisible()` | `() => boolean` | Retorna si es visible. |
-
-#### Factory estatics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `$Notification.success()` | `(message: string, options?) => $Notification` | Crea i mostra una notificacio d'exit. |
-| `$Notification.error()` | `(message: string, options?) => $Notification` | Crea i mostra una notificacio d'error. |
-| `$Notification.warning()` | `(message: string, options?) => $Notification` | Crea i mostra una notificacio d'advertencia. |
-| `$Notification.info()` | `(message: string, options?) => $Notification` | Crea i mostra una notificacio informativa. |
-| `$Notification.create()` | `(config: NotificationConfig) => $Notification` | Crea una notificacio amb configuracio completa. |
-
-#### Exemples
-
-```html
-<zs3-notification
-    type="success"
-    title="Desat!"
-    message="Els canvis s'han guardat correctament"
-    auto-show
-    show-progress
-></zs3-notification>
-```
+#### TypeScript programàtic (index3.ts)
 
-```typescript
-// Crear programaticament
-$Notification.success('Operacio completada!', { duration: 3000 })
-$Notification.error('Error de connexio', { position: 'bottom-right' })
+```ts
+// Subscripció que actualitza elements creats per TypeScript
+counterStore.subscribe('*', (state) => {
+    counterEl.textContent = String(state.count)
+    const entry = el('div', {}, `[${new Date().toLocaleTimeString()}] count = ${state.count}`)
+    storeLog.prepend(entry)
+})
 
-// Amb i18n
-$Notification.create({
-    type: 'info',
-    i18nTitle: 'notif.info.title',
-    i18nMessage: 'notif.info.msg',
-    showProgress: true,
+// Botons d'acció creats programàticament
+const storeActions: Array<[string, string, () => void]> = [
+    ['-1',    'danger',  () => counterStore.dispatch('decrement')],
+    ['+1',    'success', () => counterStore.dispatch('increment')],
+    ['Reset', '',        () => counterStore.dispatch('reset')],
+    ['+10',   'info',    () => counterStore.dispatch('add', 10)],
+]
+storeActions.forEach(([label, variant, fn]) => {
+    const b = btn(label, variant || undefined)
+    b.addEventListener('zs3-click', fn)
+    storeRow.append(b)
 })
 ```
 
 ---
 
-### zs3-modal
-
-Dialog modal basic amb backdrop, suport per teclat i focus trap.
-
-#### Atributs
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `size` | `'small' \| 'medium' \| 'large' \| 'fullscreen'` | `'medium'` | Mida del modal. |
-| `backdrop` | `boolean` | `true` | Mostra backdrop. |
-| `close-on-backdrop` | `boolean` | `true` | Tanca al clicar el backdrop. |
-| `close-on-escape` | `boolean` | `true` | Tanca amb la tecla Escape. |
-| `centered` | `boolean` | `true` | Centra verticalment. |
-| `scrollable` | `boolean` | `false` | Permet scroll del contingut. |
+### EventBus
 
-**Mides:**
-- `small`: max-width 400px
-- `medium`: max-width 600px
-- `large`: max-width 900px
-- `fullscreen`: 100% pantalla
+Comunicació desacoblada entre components via events amb nom.
 
-#### Events
-
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-modal-show` | `{ modal }` | El modal s'ha obert. |
-| `zs3-modal-hide` | `{ modal }` | El modal s'ha tancat. |
-| `zs3-modal-backdrop-click` | `{ modal }` | S'ha clicat el backdrop. |
-
-#### Metodes publics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `show()` | `() => void` | Mostra el modal. Bloqueja scroll del body i trap focus. |
-| `hide()` | `() => void` | Amaga el modal. Restaura scroll i focus. |
-| `toggle()` | `() => void` | Alterna la visibilitat. |
-| `isVisible()` | `() => boolean` | Retorna si es visible. |
-| `update()` | `(config: Partial<ModalConfig>) => void` | Actualitza la configuracio. |
+```ts
+import { eventBus } from 'zs3-ui-components'
 
-#### Exemples
+// Subscripció
+eventBus.on('user:login',  (data) => console.log('Usuari ha entrat:', data))
+eventBus.on('app:error',   (data) => console.error('Error:', data))
+eventBus.on('data:update', (data) => console.log('Dades actualitzades:', data))
 
-```html
-<zs3-modal id="myModal" size="large" centered>
-    <h2>Titol del Modal</h2>
-    <p>Contingut del modal</p>
-</zs3-modal>
+// Subscripció a TOTS els events
+eventBus.on('*', (payload) => console.log('Event rebut:', payload))
 
-<script>
-    document.getElementById('myModal').show()
-</script>
+// Emissió
+eventBus.emit('user:login',  { name: 'Joan', role: 'admin' })
+eventBus.emit('app:error',   { code: 404, msg: 'Not found' })
+eventBus.emit('data:update', { items: 42 })
 ```
 
----
-
-### zs3-modal-dialog
-
-Dialog modal avancat amb titol, missatge, icona i botons d'accio. Hereta de `zs3-modal`.
-
-#### Atributs (propis)
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `title` | `string` | `''` | Titol del dialog. |
-| `message` | `string` | `''` | Missatge del dialog. |
-| `show-accept` | `boolean` | `false` | Mostra boto d'acceptar. |
-| `show-cancel` | `boolean` | `false` | Mostra boto de cancellar. |
-| `show-close` | `boolean` | `false` | Mostra boto de tancar. |
-| `accept-text` | `string` | `'Accept'` | Text del boto acceptar. |
-| `cancel-text` | `string` | `'Cancel'` | Text del boto cancellar. |
-| `close-text` | `string` | `'Close'` | Text del boto tancar. |
-| `accept-variant` | `Variant` | `'primary'` | Variant del boto acceptar. |
-| `cancel-variant` | `Variant` | `'secondary'` | Variant del boto cancellar. |
-| `icon` | `string` | - | Nom de la icona a mostrar a la capcalera. |
-| `i18n-title` | `string` | - | Clau i18n per al titol. |
-| `i18n-message` | `string` | - | Clau i18n per al missatge. |
-| `i18n-accept-text` | `string` | - | Clau i18n per al text d'acceptar. |
-| `i18n-cancel-text` | `string` | - | Clau i18n per al text de cancellar. |
-| `i18n-close-text` | `string` | - | Clau i18n per al text de tancar. |
-
-Tambe hereta tots els atributs de [`zs3-modal`](#zs3-modal): `size`, `backdrop`, `close-on-backdrop`, `close-on-escape`, `centered`, `scrollable`.
-
-#### Events
-
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-dialog-accept` | `{ dialog, action: 'accept' }` | Boto acceptar clicat. |
-| `zs3-dialog-cancel` | `{ dialog, action: 'cancel' }` | Boto cancellar clicat. |
-| `zs3-dialog-close` | `{ dialog, action: 'close' }` | Boto tancar clicat. |
-| `zs3-modal-show` | `{ modal }` | Heretat: dialog obert. |
-| `zs3-modal-hide` | `{ modal }` | Heretat: dialog tancat. |
-
-#### Metodes publics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `showDialog()` | `() => Promise<DialogAction>` | Mostra el dialog i retorna una Promise que es resol amb l'accio (`'accept'`, `'cancel'` o `'close'`). |
-| `updateDialog()` | `(config: Partial<ModalDialogConfig>) => void` | Actualitza el contingut del dialog. |
-
-#### Factory estatics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `$ModalDialog.confirm()` | `(message: string, title?: string) => Promise<boolean>` | Dialog de confirmacio. Retorna `true` si accepta. |
-| `$ModalDialog.confirmI18n()` | `(config) => Promise<boolean>` | Dialog de confirmacio amb i18n. |
-| `$ModalDialog.alert()` | `(message: string, title?: string) => Promise<void>` | Dialog d'alerta. |
-| `$ModalDialog.alertI18n()` | `(config) => Promise<void>` | Dialog d'alerta amb i18n. |
-| `$ModalDialog.prompt()` | `(title: string, content: HTMLElement) => Promise<DialogAction>` | Dialog amb contingut personalitzat via slot. |
-| `$ModalDialog.confirmDelete()` | `(itemName: string) => Promise<boolean>` | Dialog de confirmacio d'eliminacio. |
-| `$ModalDialog.confirmDeleteI18n()` | `(config) => Promise<boolean>` | Dialog d'eliminacio amb i18n. |
-| `$ModalDialog.create()` | `(config: ModalDialogConfig) => $ModalDialog` | Crea un dialog des de configuracio completa. |
-
-#### Exemples
+#### HTML inline (index2.html) + index2.ts
 
 ```html
-<!-- Dialog de confirmacio declaratiu -->
-<zs3-modal-dialog
-    id="dlg"
-    title="Confirmar"
-    message="Estas segur?"
-    show-accept
-    show-cancel
-    accept-variant="primary"
-    size="small"
-></zs3-modal-dialog>
+<div>
+    <zs3-button variant="primary" zs3-click="emitBusEvent('user:login',  { name: 'Joan', role: 'admin' })">user:login</zs3-button>
+    <zs3-button variant="warning" zs3-click="emitBusEvent('app:error',   { code: 404 })">app:error</zs3-button>
+    <zs3-button variant="info"    zs3-click="emitBusEvent('data:update', { items: 42 })">data:update</zs3-button>
+</div>
+<div id="eventbus-output"></div>
+```
+
+```ts
+// index2.ts
+window.emitBusEvent = (name: string, data: unknown) => eventBus.emit(name, data)
+
+function setupEventBusListener(): void {
+    const output = document.getElementById('eventbus-output')
+    ;['user:login', 'app:error', 'data:update'].forEach((evt) => {
+        eventBus.on(evt, (data) => {
+            if (output) {
+                const entry = document.createElement('div')
+                entry.textContent = `[${new Date().toLocaleTimeString()}] ${evt}: ${JSON.stringify(data)}`
+                output.prepend(entry)
+                if (output.children.length > 10) output.lastChild?.remove()
+            }
+        })
+    })
+}
 ```
 
-```typescript
-// Factory estatic
-const result = await $ModalDialog.confirm('Estas segur?', 'Confirmar')
-if (result) { /* acceptat */ }
+#### TypeScript programàtic (index3.ts)
 
-// Factory amb i18n
-const result = await $ModalDialog.confirmI18n({
-    i18nTitle: 'dlg.confirm.title',
-    i18nMessage: 'dlg.confirm.msg',
-    i18nAcceptText: 'btn.accept',
-    i18nCancelText: 'btn.cancel',
-})
-
-// Confirmacio d'eliminacio
-const deleted = await $ModalDialog.confirmDelete('fitxer.txt')
-
-// Dialog programatic complet
-const dialog = $ModalDialog.create({
-    title: 'Configuracio',
-    message: 'Selecciona les opcions',
-    showAccept: true,
-    showCancel: true,
-    acceptVariant: 'success',
-    icon: 'settings',
+```ts
+const busEvents: Array<[string, string, object]> = [
+    ['user:login', 'primary', { name: 'Joan', role: 'admin' }],
+    ['app:error',  'warning', { code: 404, msg: 'Not found' }],
+    ['data:update','info',    { items: 42 }],
+]
+busEvents.forEach(([evtName, variant, payload]) => {
+    eventBus.on(evtName, (data) => {
+        const entry = el('div', {}, `[${new Date().toLocaleTimeString()}] ${evtName}: ${JSON.stringify(data)}`)
+        busLog.prepend(entry)
+    })
+    const b = btn(`Emit ${evtName}`, variant)
+    b.addEventListener('zs3-click', () => eventBus.emit(evtName, payload))
+    busRow.append(b)
 })
-document.body.appendChild(dialog)
-const action = await dialog.showDialog()
-dialog.remove()
 ```
 
 ---
 
-### zs3-window
-
-Component de finestra arrossegable amb barra de titol i controls.
-
-#### Atributs
+### $Storage — LocalStorage
 
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `title` | `string` | `'Window'` | Titol de la finestra. |
-| `width` | `string` | `'300px'` | Amplada (valor CSS). |
-| `height` | `string` | `'auto'` | Altura (valor CSS). |
-| `move` | `'x' \| 'y' \| 'xy'` | - | Direccio de moviment. S'arrossega per la barra de titol. |
-| `closable` | `boolean` | `false` | Mostra boto de tancar. |
-| `minimizable` | `boolean` | `false` | Mostra boto de minimitzar. |
-| `maximizable` | `boolean` | `false` | Mostra boto de maximitzar. |
-| `i18n-title` | `string` | - | Clau i18n per al titol. |
+Wrapper de `localStorage` amb serialització JSON automàtica.
 
-#### Events
-
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-window-close` | `{ window }` | Boto tancar clicat. |
-| `zs3-window-minimize` | `{ window }` | Boto minimitzar clicat. |
-| `zs3-window-maximize` | `{ window }` | Boto maximitzar clicat. |
-| `zs3-move-start` | `MoveEventDetail` | Inici d'arrossegament. |
-| `zs3-move` | `MoveEventDetail` | Durant l'arrossegament. |
-| `zs3-move-end` | `MoveEventDetail` | Fi d'arrossegament. |
-| `zs3-move-cancel` | `MoveEventDetail` | Arrossegament cancel-lat (Escape). |
-| `zs3-move-boundary` | `MoveEventDetail` | S'ha tocat un limit. |
-
-#### Metodes publics
+```ts
+import { storage } from 'zs3-ui-components'
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `setTitle()` | `(title: string) => void` | Estableix el titol de la finestra. |
-| `close()` | `() => void` | Emet l'event `zs3-window-close` (no elimina del DOM). |
+storage.set('user.name', 'Joan')
+storage.set('user.prefs', { theme: 'dark', locale: 'ca' })
 
-#### Exemple
+const name  = storage.get('user.name')   // → 'Joan'
+const prefs = storage.get('user.prefs')  // → { theme: 'dark', locale: 'ca' }
+const miss  = storage.get('noexist')     // → null
 
-```html
-<zs3-window title="La meva finestra" move="xy" closable minimizable width="400px" height="300px">
-    <p>Contingut de la finestra. Arrossega la barra de titol!</p>
-</zs3-window>
+storage.remove('user.name')
+storage.clear()
 ```
 
----
+#### HTML inline (index2.html) + index2.ts
 
-### zs3-form
-
-Component de formulari dinamic amb validacio integrada. Permet crear formularis des de configuracio JSON o programaticament.
-
-#### Atributs
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `title` | `string` | `''` | Titol del formulari. |
-| `description` | `string` | `''` | Descripcio del formulari. |
-| `accept-text` | `string` | `'Acceptar'` | Text del boto d'acceptar. |
-| `cancel-text` | `string` | `'Cancel·lar'` | Text del boto de cancellar. |
-| `show-cancel` | `boolean` | `false` | Mostra el boto de cancellar. |
-| `accept-variant` | `Variant` | `'primary'` | Variant del boto d'acceptar. |
-| `cancel-variant` | `Variant` | `'secondary'` | Variant del boto de cancellar. |
-| `disabled` | `boolean` | `false` | Desactiva tot el formulari. |
-| `fields` | `string` | - | Camps del formulari en format JSON. |
-| `i18n-title` | `string` | - | Clau i18n per al titol. |
-| `i18n-description` | `string` | - | Clau i18n per a la descripcio. |
-| `i18n-accept-text` | `string` | - | Clau i18n per al text d'acceptar. |
-| `i18n-cancel-text` | `string` | - | Clau i18n per al text de cancellar. |
-
-#### Events
-
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-form-submit` | `{ values, isValid }` | El formulari s'ha enviat amb dades valides. |
-| `zs3-form-cancel` | `{ values }` | S'ha clicat el boto de cancellar. |
-| `zs3-form-change` | `{ name, value, isValid }` | Un camp ha canviat de valor. |
-| `zs3-form-validation` | `ValidationResult` | L'estat de validacio ha canviat. |
-
-#### Metodes publics
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `setFields()` | `(fields: FormFieldConfig[]) => void` | Estableix els camps del formulari. |
-| `getValues()` | `() => Record<string, unknown>` | Obte tots els valors actuals. |
-| `getValue()` | `(name: string) => unknown` | Obte el valor d'un camp. |
-| `setValue()` | `(name: string, value: unknown) => void` | Estableix el valor d'un camp. |
-| `setValues()` | `(values: Record<string, unknown>) => void` | Estableix multiples valors. |
-| `reset()` | `() => void` | Reinicia el formulari als valors per defecte. |
-| `validate()` | `() => ValidationResult` | Valida tots els camps i retorna el resultat. |
-| `isValid()` | `() => boolean` | Retorna si el formulari es valid. |
-| `getErrors()` | `() => Record<string, string>` | Obte els errors de validacio actuals. |
-| `appendTo()` | `(parent: string \| HTMLElement) => void` | Afegeix el formulari a un element. |
-
-#### Tipus de camp (FormFieldType)
-
-`text`, `email`, `password`, `number`, `tel`, `url`, `textarea`, `select`, `checkbox`, `date`, `time`, `datetime-local`
-
-#### Configuracio de camp (FormFieldConfig)
-
-```typescript
-interface FormFieldConfig {
-    name: string              // Nom unic del camp
-    label: string             // Etiqueta visible
-    i18nLabel?: string        // Clau i18n per l'etiqueta
-    type: FormFieldType       // Tipus de camp
-    required?: boolean        // Camp obligatori
-    placeholder?: string      // Text placeholder
-    i18nPlaceholder?: string  // Clau i18n pel placeholder
-    defaultValue?: string | number | boolean
-    options?: FormFieldOption[]  // Per a selects
-    validation?: FormFieldValidation
-    errorMessage?: string     // Missatge d'error personalitzat
-    i18nErrorMessage?: string // Clau i18n pel missatge d'error
-    disabled?: boolean
-    readonly?: boolean
-    rows?: number             // Per textareas
+```html
+<div>
+    <input id="storage-key"   type="text" placeholder="clau"  value="demo.key" />
+    <input id="storage-value" type="text" placeholder="valor" value="valor de prova" />
+    <zs3-button variant="primary" zs3-click="storageSet()"    size="sm">set()</zs3-button>
+    <zs3-button                   zs3-click="storageGet()"    size="sm">get()</zs3-button>
+    <zs3-button variant="danger"  zs3-click="storageRemove()" size="sm">remove()</zs3-button>
+</div>
+<div id="storage-output"></div>
+```
+
+```ts
+// index2.ts
+window.storageSet = () => {
+    const key = (document.getElementById('storage-key') as HTMLInputElement).value
+    const val = (document.getElementById('storage-value') as HTMLInputElement).value
+    storage.set(key, val)
+    setOutput('storage-output', `Guardat: "${key}" = "${val}"`)
 }
-
-interface FormFieldValidation {
-    pattern?: string | RegExp  // Patro regex
-    min?: number              // Valor minim (numbers)
-    max?: number              // Valor maxim (numbers)
-    minLength?: number        // Longitud minima
-    maxLength?: number        // Longitud maxima
-    custom?: (value: unknown) => boolean | string  // Validacio personalitzada
+window.storageGet = () => {
+    const key = (document.getElementById('storage-key') as HTMLInputElement).value
+    const val = storage.get(key)
+    setOutput('storage-output', val !== null
+        ? `Llegit: "${key}" = "${val}"`
+        : `Clau "${key}" no trobada`
+    )
 }
-
-interface FormFieldOption {
-    value: string
-    label: string
-    i18nLabel?: string
+window.storageRemove = () => {
+    const key = (document.getElementById('storage-key') as HTMLInputElement).value
+    storage.remove(key)
+    setOutput('storage-output', `Eliminat: "${key}"`)
 }
 ```
 
-#### Factory estatics
+#### TypeScript programàtic (index3.ts)
 
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `$Form.create()` | `(config: FormConfig) => $Form` | Crea un formulari des de configuracio. |
-| `$Form.prompt()` | `(config: FormConfig) => Promise<Record<string,unknown> \| null>` | Crea i mostra un formulari. Retorna els valors o `null` si es cancella. |
+```ts
+const bSet = btn('set()', 'primary'); bSet.size = 'sm'
+bSet.addEventListener('zs3-click', () => {
+    storage.set(keyInput.value, valInput.value)
+    setOutput('storage-out-ts', `Guardat: "${keyInput.value}" = "${valInput.value}"`)
+})
 
-#### Exemples
+const bGet = btn('get()'); bGet.size = 'sm'
+bGet.addEventListener('zs3-click', () => {
+    const v = storage.get(keyInput.value)
+    setOutput('storage-out-ts', v !== null
+        ? `Llegit: "${keyInput.value}" = "${v}"`
+        : `Clau "${keyInput.value}" no trobada`
+    )
+})
 
-```html
-<!-- Formulari declaratiu -->
-<zs3-form
-    id="contactForm"
-    title="Contacte"
-    i18n-title="form.contact.title"
-    show-cancel
-></zs3-form>
-
-<script>
-    const form = document.getElementById('contactForm');
-    form.setFields([
-        { name: 'name', label: 'Nom', type: 'text', required: true },
-        { name: 'email', label: 'Email', type: 'email', required: true },
-        { name: 'message', label: 'Missatge', type: 'textarea', rows: 5 }
-    ]);
-
-    form.addEventListener('zs3-form-submit', (e) => {
-        console.log('Valors:', e.detail.values);
-    });
-</script>
-```
-
-```typescript
-// Crear programaticament
-const form = $Form.create({
-    title: 'Nou usuari',
-    showCancel: true,
-    fields: [
-        { name: 'username', label: 'Usuari', type: 'text', required: true },
-        { name: 'role', label: 'Rol', type: 'select', options: [
-            { value: 'admin', label: 'Administrador' },
-            { value: 'user', label: 'Usuari' }
-        ]}
-    ]
-});
-document.body.appendChild(form);
-
-// Amb Promise
-const values = await $Form.prompt({
-    title: 'Introdueix dades',
-    fields: [
-        { name: 'code', label: 'Codi', type: 'text', required: true }
-    ]
-});
-if (values) {
-    console.log('Codi:', values.code);
-}
+const bRm = btn('remove()', 'danger'); bRm.size = 'sm'
+bRm.addEventListener('zs3-click', () => {
+    storage.remove(keyInput.value)
+    setOutput('storage-out-ts', `Eliminat: "${keyInput.value}"`)
+})
 ```
 
 ---
 
-### zs3-login-form
-
-Formulari de login predefinit amb camps d'email i contrasenya. Hereta de `zs3-form`.
-
-#### Atributs (propis)
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `show-register` | `boolean` | `false` | Mostra un boto per anar al registre. |
-| `login-text` | `string` | `'Iniciar sessio'` | Text del boto de login. |
-| `register-text` | `string` | `'Registrar-se'` | Text del boto de registre. |
-| `i18n-login-text` | `string` | - | Clau i18n per al text de login. |
-| `i18n-register-text` | `string` | - | Clau i18n per al text de registre. |
+### HttpClient
 
-Tambe hereta tots els atributs de [`zs3-form`](#zs3-form).
+Client HTTP amb base URL, timeout i tipatge genèric de respostes.
 
-#### Events
+```ts
+import { HttpClient } from 'zs3-ui-components'
 
-| Event | Detail | Descripcio |
-|-------|--------|------------|
-| `zs3-form-submit` | `{ values: { email, password }, isValid }` | Formulari enviat. |
-| `zs3-login-register` | `{ form }` | Boto de registre clicat. |
-
-#### Camps predefinits
+const http = new HttpClient({
+    baseUrl: 'https://api.example.com',
+    timeout: 8000,
+})
 
-- **email**: Camp d'email obligatori
-- **password**: Camp de contrasenya obligatori (minim 6 caracters)
+// GET tipat
+const res = await http.get<User[]>('/users?_limit=3')
+console.log(res.status)  // → 200
+console.log(res.data)    // → User[]
 
-#### Exemple
+// POST / PUT / PATCH / DELETE
+await http.post('/users',    { name: 'Joan', email: 'joan@example.com' })
+await http.put('/users/1',   { name: 'Joan Updated' })
+await http.patch('/users/1', { name: 'Joan' })
+await http.delete('/users/1')
 
-```html
-<zs3-login-form
-    i18n-title="app.login.title"
-    show-register
-    zs3-form-submit="log.info('Login:', event.detail.values)"
-    zs3-login-register="window.location = '/register'"
-></zs3-login-form>
+// Gestió d'errors
+try {
+    await http.get('/nonexistent')
+} catch (e: unknown) {
+    const err = e as { status?: number; message?: string }
+    console.error(`HTTP [${err.status ?? 'network'}]: ${err.message}`)
+}
 ```
 
----
-
-### zs3-register-form
-
-Formulari de registre predefinit amb camps complets i validacio de contrasenya. Hereta de `zs3-form`.
-
-#### Atributs (propis)
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `register-text` | `string` | `'Registrar-se'` | Text del boto de registre. |
-| `i18n-register-text` | `string` | - | Clau i18n per al text de registre. |
-
-Tambe hereta tots els atributs de [`zs3-form`](#zs3-form).
-
-#### Camps predefinits
-
-- **email**: Email obligatori
-- **username**: Nom d'usuari (3-20 caracters, alfanumeric + guio baix)
-- **firstName**: Nom obligatori
-- **lastName**: Cognom obligatori
-- **password**: Contrasenya (minim 8 caracters)
-- **confirmPassword**: Confirmacio de contrasenya (ha de coincidir)
-
-#### Validacio especial
-
-El formulari valida automaticament que `password` i `confirmPassword` coincideixin.
-
-#### Exemple
+#### HTML inline (index2.html) + index2.ts
 
 ```html
-<zs3-register-form
-    title="Crear compte"
-    i18n-title="app.register.title"
-    show-cancel
-    zs3-form-submit="handleRegistration(event.detail.values)"
-    zs3-form-cancel="window.location = '/login'"
-></zs3-register-form>
+<div>
+    <zs3-button variant="primary" zs3-click="httpGetUsers()">GET /users</zs3-button>
+    <zs3-button variant="success" zs3-click="httpGetPost()">GET /posts/1</zs3-button>
+    <zs3-button variant="danger"  zs3-click="httpError()">Error 404</zs3-button>
+</div>
+<div id="http-output">Fes una petició...</div>
 ```
 
----
-
-### zs3-recover-password-form
-
-Formulari de recuperacio de contrasenya amb un unic camp d'email. Hereta de `zs3-form`.
-
-#### Atributs (propis)
-
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `submit-text` | `string` | `'Recuperar contrasenya'` | Text del boto d'enviament. |
-| `i18n-submit-text` | `string` | - | Clau i18n per al text d'enviament. |
-
-Tambe hereta tots els atributs de [`zs3-form`](#zs3-form).
-
-#### Camps predefinits
-
-- **email**: Email obligatori
+```ts
+// index2.ts
+const http = new HttpClient({ baseUrl: 'https://jsonplaceholder.typicode.com', timeout: 8000 })
 
-#### Exemple
+window.httpGetUsers = async () => {
+    setOutput('http-output', 'Carregant...')
+    try {
+        const res = await http.get<{ id: number; name: string }[]>('/users?_limit=3')
+        setOutput('http-output',
+            `GET /users [${res.status}]:\n${res.data.map((u) => `  - ${u.name}`).join('\n')}`,
+        )
+    } catch (e) { setOutput('http-output', `Error: ${e}`) }
+}
 
-```html
-<zs3-recover-password-form
-    title="Has oblidat la contrasenya?"
-    i18n-title="app.recover.title"
-    show-cancel
-    zs3-form-submit="sendRecoveryEmail(event.detail.values.email)"
-></zs3-recover-password-form>
+window.httpError = async () => {
+    setOutput('http-output', 'Carregant...')
+    try {
+        await http.get('/nonexistent-endpoint-12345')
+    } catch (e: unknown) {
+        const err = e as { status?: number; message?: string }
+        setOutput('http-output', `Error HTTP [${err.status ?? 'network'}]: ${err.message ?? String(e)}`)
+    }
+}
 ```
 
----
-
-### zs3-select-theme
-
-Selector desplegable per canviar de tema. Es posiciona de forma fixa (`position: fixed`) per defecte.
-
-#### Atributs
+#### TypeScript programàtic (index3.ts)
 
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `zs3-position` | `string` | `'position: fixed; top: 1rem; right: 1rem'` | CSS de posicionament personalitzat. |
-
-#### Exemple
-
-```html
-<!-- Posicio per defecte (fixed top-right) -->
-<zs3-select-theme></zs3-select-theme>
+```ts
+const bUsers = btn('GET /users', 'primary')
+bUsers.addEventListener('zs3-click', async () => {
+    httpOutPre.textContent = 'Carregant...'
+    try {
+        const res = await http.get<{ id: number; name: string }[]>('/users?_limit=3')
+        httpOutPre.textContent =
+            `GET /users [${res.status}]:\n${res.data.map((u) => `  - ${u.name}`).join('\n')}`
+    } catch (e) { httpOutPre.textContent = `Error: ${e}` }
+})
 
-<!-- Posicio personalitzada -->
-<zs3-select-theme zs3-position="position: fixed; bottom: 1rem; left: 1rem"></zs3-select-theme>
+const bErr = btn('Error 404', 'danger')
+bErr.addEventListener('zs3-click', async () => {
+    try {
+        await http.get('/nonexistent')
+    } catch (e: unknown) {
+        const err = e as { status?: number; message?: string }
+        httpOutPre.textContent = `Error HTTP [${err.status ?? 'network'}]: ${err.message}`
+    }
+})
 ```
 
 ---
 
-### zs3-select-locale
+### $Log — Logging
 
-Selector desplegable per canviar d'idioma. Mostra els idiomes carregats al sistema i18n.
+Logger avançat amb nivells i formatació a la consola del navegador.
 
-#### Atributs
+```ts
+import { log } from 'zs3-ui-components'
 
-| Atribut | Tipus | Per defecte | Descripcio |
-|---------|-------|-------------|------------|
-| `zs3-position` | `string` | `'position: fixed; top: 1rem; right: 1rem'` | CSS de posicionament personalitzat. |
+log.info('Aplicació iniciada', { version: '1.2.0' })
+log.warn('Configuració incompleta', { missing: 'api-key' })
+log.error('Error en la petició', { code: 500, url: '/api/users' })
+log.success('Operació completada!')
+log.debug('Dades de debug', { state: counterStore.getState() })
+```
 
-#### Exemple
+```ts
+// index2.ts — exposa log globalment per a handlers inline
+window.log = log
 
-```html
-<zs3-select-locale></zs3-select-locale>
+// index3.ts — logging d'events globals
+window.addEventListener('zs3-locale-change', () => log.info(`Idioma: ${i18n.getLocale()}`))
+window.addEventListener('zs3-theme-change',  () => log.info(`Tema: ${themeManager.getTheme()}`))
 ```
 
 ---
 
-## Inline Event Handlers
+### DIContainer — Dependency Injection
 
-ZS3 suporta handlers d'events inline directament als atributs HTML dels components. Dins del codi de l'atribut, hi ha disponibles les seguents variables injectades:
+Contenidor d'injecció de dependències amb singletons i fàbriques.
 
-| Variable | Tipus | Descripcio |
-|----------|-------|------------|
-| `$` | `(selector: string, root?: Document \| HTMLElement \| ShadowRoot) => ZS3 \| null` | Funcio de seleccio d'elements. El segon parametre opcional limita la cerca a un element arrel. |
-| `log` | `$Log` | Sistema de logging. |
-| `debug` | `$Debug` | Utilitat de debugging. |
-| `params` | `$Parameters` | Gestio de parametres d'URL. |
-| `storage` | `$Storage` | Gestio de localStorage. |
-| `$env` | `() => Record<string,string>` | Informacio d'entorn. |
-| `this` | `HTMLElement` | L'element que emet l'event. |
-| `event` | `CustomEvent` | L'event emes. |
+```ts
+import { diContainer } from 'zs3-ui-components'
 
-### Exemple d'us
+// Registra
+diContainer.registerSingleton('httpClient', () => http)
+diContainer.registerSingleton('userService', () => ({
+    label: 'UserService',
+    getUser:  (id: number) => http.get(`/users/${id}`),
+    getUsers: ()           => http.get('/users'),
+}))
 
-```html
-<!-- Boto que mostra una notificacio -->
-<zs3-button
-    variant="success"
-    zs3-click="
-        const n = $('#notif').$;
-        n.setAttribute('type', 'success');
-        n.setAttribute('title', 'Exit!');
-        n.setAttribute('message', 'Operacio completada');
-        n.forceUpdate();
-        n.show();
-        log.info('Notificacio mostrada')
-    "
->Mostrar notificacio</zs3-button>
-
-<!-- Boto que obre un dialog i processa el resultat -->
-<zs3-button
-    variant="primary"
-    zs3-click="
-        $('#myDialog').$.showDialog().then(function(action) {
-            $('#output').$.textContent = 'Resultat: ' + action;
-            log.info('Dialog: ' + action)
-        })
-    "
->Obrir dialog</zs3-button>
+// Resol
+const svc = diContainer.resolve<{ label: string; getUsers: () => Promise<unknown> }>('userService')
+const users = await svc.getUsers()
 
-<!-- Boto que desa a storage -->
-<zs3-button
-    zs3-click="
-        storage.set('lastClick', new Date().toISOString());
-        log.info('Desat a storage: ' + storage.get('lastClick'))
-    "
->Desar timestamp</zs3-button>
+// Comprova
+diContainer.has('httpClient')     // → true
+diContainer.has('unknownService') // → false
 ```
 
-Els inline handlers tambe funcionen amb events de float i move:
+#### HTML inline (index2.html) + index2.ts
 
 ```html
-<zs3-toolbar
-    float="top"
-    zs3-float-show-start="log.info('Toolbar apareixent')"
-    zs3-float-hide-end="log.info('Toolbar amagat')"
->
-    <zs3-button>Boto</zs3-button>
-</zs3-toolbar>
-```
-
----
-
-## Guia de desenvolupament de nous components
-
-### Estructura de fitxers
-
-```
-src/
-  components/
-    zs3-BaseComponent.ts    # Classe base abstracta
-    zs3-Button.ts           # Component boto
-    zs3-Icon.ts             # Component icona
-    zs3-Toolbar.ts          # Component toolbar
-    zs3-Modal.ts            # Component modal
-    zs3-ModalDialog.ts      # Component dialog (hereta Modal)
-    zs3-Notification.ts     # Component notificacio
-    zs3-Window.ts           # Component finestra
-    zs3-Form.ts             # Component formulari dinamic
-    zs3-LoginForm.ts        # Formulari de login (hereta Form)
-    zs3-RegisterForm.ts     # Formulari de registre (hereta Form)
-    zs3-RecoverPasswordForm.ts  # Formulari recuperacio (hereta Form)
-    zs3-SelectTheme.ts      # Selector de tema
-    zs3-SelectLocale.ts     # Selector d'idioma
-    zs3-common.ts           # Float, Move, generateEvent
-    types.ts                # Tipus compartits (Variant)
-  decorators/
-    component.ts            # @Component
-    observedAttributes.ts   # @ObservedAttributes (amb opcio inherit)
-    float.ts                # @Float
-    move.ts                 # @Move
-    attr.ts                 # @Attr
-    index.ts                # Re-exporta tot
-  css/
-    zs3.css                 # Definicions de temes i estils base
-  i18n/
-    defaults.ts             # Traduccions per defecte dels components
-  zs3.ts                    # Classe ZS3, $, params, log, debug, storage
-  theme.ts                  # ThemeManager
-  i18n.ts                   # Sistema i18n
-  types.ts                  # EventDescription
-  index.ts                  # Entry point (exporta tot, registra components)
-```
-
-### $BaseComponent
-
-Tots els components ZS3 hereten de `$BaseComponent`, que es una classe abstracta que extén `HTMLElement`.
-
-#### Opcions del constructor
-
-```typescript
-interface BaseComponentOptions {
-    useShadowDOM?: boolean    // true per defecte
-    shadowMode?: 'open' | 'closed'  // 'open' per defecte
-    delegatesFocus?: boolean   // false per defecte
+<div>
+    <zs3-button variant="primary" zs3-click="diResolveDemo()">resolve('userService')</zs3-button>
+    <zs3-button variant="info"    zs3-click="diHasDemo()">has('httpClient')?</zs3-button>
+</div>
+<div id="di-output">Resultat DI...</div>
+```
+
+```ts
+// index2.ts
+window.diResolveDemo = () => {
+    const svc = diContainer.resolve<{ label: string }>('userService')
+    setOutput('di-output', `Resolt 'userService': ${svc.label}`)
+}
+window.diHasDemo = () => {
+    const h = diContainer.has('httpClient')
+    const u = diContainer.has('unknownService')
+    setOutput('di-output', `has('httpClient') = ${h} | has('unknownService') = ${u}`)
 }
 ```
 
-### Cicle de vida
-
-```
-constructor
-  -> initialize()           // Setup logic, configuracio de _floatTargetSelector, etc.
-  -> emitLifecycleEvent('zs3-built')
-
-connectedCallback (element inserit al DOM)
-  -> beforeMount()          // Primera vegada nomes
-  -> _mounted = true
-  -> emitLifecycleEvent('zs3-created', { phase: 'start' })
-  -> Registra listeners: zs3-theme-change, zs3-locale-change
-  -> render()               // Renderitza el component
-  -> afterMount()           // Setup event listeners, etc.
-  -> applyFloatEffect()
-  -> applyMoveEffect()
-  -> emitLifecycleEvent('zs3-created', { phase: 'end' })
-
-attributeChangedCallback (canvi d'atribut)
-  -> emitLifecycleEvent('zs3-modified', { phase: 'start' })
-  -> Handler registrat amb onAttributeChange() (si existeix)
-  -> onAttributeChanged()   // Hook per subclasses
-  -> render()               // Re-renderitza
-  -> applyFloatEffect()
-  -> applyMoveEffect()
-  -> emitLifecycleEvent('zs3-modified', { phase: 'end' })
-
-[Canvi de tema]
-  -> onThemeChange(theme)   // Hook per subclasses
-  -> render()
-
-[Canvi d'idioma]
-  -> onLocaleChange(locale) // Hook per subclasses
-  -> render()
-
-disconnectedCallback (element eliminat del DOM)
-  -> _mounted = false
-  -> emitLifecycleEvent('zs3-destroyed', { phase: 'start' })
-  -> Elimina listeners de tema/idioma
-  -> beforeUnmount()        // Cleanup
-  -> Cleanup de managed event listeners
-  -> emitLifecycleEvent('zs3-destroyed', { phase: 'end' })
-```
-
-### Metodes disponibles
-
-#### Queries al DOM intern
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `qs()` | `<T extends HTMLElement>(selector: string) => T \| null` | querySelector dins del root (shadow o element). |
-| `qsAll()` | `<T extends HTMLElement>(selector: string) => NodeListOf<T>` | querySelectorAll dins del root. |
-
-#### Gestio d'atributs
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `onAttributeChange()` | `(name: string, handler: AttributeChangeCallback) => void` | Registra un handler per un atribut especific. |
-| `getBooleanAttribute()` | `(name: string, defaultValue?: boolean) => boolean` | Obte atribut com a boolean. |
-| `getNumberAttribute()` | `(name: string, defaultValue?: number) => number` | Obte atribut com a number. |
-| `getArrayAttribute()` | `(name: string, defaultValue?: string[]) => string[]` | Obte atribut com a array (coma-separat). |
-| `setBooleanAttribute()` | `(name: string, value: boolean) => void` | Estableix atribut boolean. |
-
-#### Events
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `addManagedEventListener()` | `(element, event, handler, options?) => void` | Afegeix listener amb cleanup automatic. |
-| `emit()` | `<T>(eventName: string, detail?: T) => boolean` | Emet un CustomEvent. Executa inline handlers si existeixen. Bloquejat si disabled/loading. |
-| `emitLifecycleEvent()` | `(eventName: string, detail?: Record<string,unknown>) => void` | Emet event de cicle de vida. |
-
-#### Renderitzat
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `render()` | `() => void` | **Abstracte.** Renderitza el component. |
-| `setHTML()` | `(html: string, target?) => void` | Estableix innerHTML al root o target. |
-| `requestUpdate()` | `() => Promise<void>` | Sol-licita re-render en el proxim animation frame. |
-| `forceUpdate()` | `() => void` | Forca re-render immediat + float + move. |
-| `debounce()` | `<T>(fn: T, delay: number) => (...args) => void` | Crea una funcio debounced. |
-
-#### i18n
-
-| Metode | Signatura | Descripcio |
-|--------|-----------|------------|
-| `t()` | `(key: string, params?) => string` | Tradueix una clau. |
-| `hasTranslation()` | `(key: string) => boolean` | Verifica si existeix traduccio. |
-| `getTranslatedAttribute()` | `(attrName: string, defaultValue?) => string` | Obte el valor d'un atribut traduit (`i18n-{attrName}` o `attrName`). |
-
-#### Float/Move
-
-| Propietat | Tipus | Descripcio |
-|-----------|-------|------------|
-| `_floatTargetSelector` | `string \| null` | Selector de l'element float target. |
-| `_moveContainerSelector` | `string \| null` | Selector del container move. `':host'` per al component sencer. |
-| `_moveDragSelector` | `string \| null` | Selector del drag handle. Si no es defineix, s'usa el container. |
-
 ---
 
-## Decoradors
-
-### @Component(tagName)
+### $ — DOM Helper
 
-Registra el custom element amb `customElements.define()`.
+Helper per seleccionar i manipular elements del DOM.
 
-```typescript
-@Component('zs3-my-component')
-export class $MyComponent extends $BaseComponent { ... }
-```
-
-### @ObservedAttributes(attributes, options?)
-
-Declara els atributs observats per `attributeChangedCallback`.
-
-```typescript
-@ObservedAttributes(['size', 'variant', 'disabled'])
-export class $MyComponent extends $BaseComponent { ... }
-```
-
-#### Opcions
-
-| Opcio | Tipus | Per defecte | Descripcio |
-|-------|-------|-------------|------------|
-| `inherit` | `boolean` | `false` | Hereta els `observedAttributes` de la classe pare. |
-
-#### Herencia d'atributs
-
-Quan un component extén un altre component ZS3 i necessita observar tant els seus propis atributs com els de la classe pare, utilitza l'opcio `inherit: true`:
-
-```typescript
-// Component base amb els seus atributs
-@ObservedAttributes(['title', 'description', 'show-cancel'])
-export class $Form extends $BaseComponent { ... }
-
-// Component derivat que hereta els atributs del pare
-@ObservedAttributes(['show-register', 'login-text'], { inherit: true })
-export class $LoginForm extends $Form { ... }
-// Observa: 'title', 'description', 'show-cancel', 'show-register', 'login-text'
-```
-
-Sense `inherit: true`, el component derivat nomes observaria els seus propis atributs i perdria la reactivitat als atributs del pare.
-
-### @Float(selector)
-
-Configura el selector de l'element target per l'efecte float.
-
-```typescript
-@Float('button')    // Selector dins del shadow DOM
-@Float('.toolbar')  // Classe CSS interna
-```
-
-### @Move(containerSelector, dragSelector?)
-
-Configura el moviment drag & drop.
+```ts
+import { $ } from 'zs3-ui-components'
 
-```typescript
-@Move(':host')                        // El component sencer es mou i es drag handle
-@Move(':host', '.title-bar')          // El component es mou, drag per .title-bar
-@Move('.window', '.title-bar')        // .window es mou, drag per .title-bar
+$('#my-element')?.addClass('highlighted')
+$('#my-element')?.removeClass('highlighted')
+$('#my-element')?.toggleClass('highlighted')
+$('#my-element')?.hide()
+$('#my-element')?.show()
+$('#my-element')?.text('Nou contingut')
+$('#my-element')?.attr('aria-label', 'Descripció')
 ```
 
-### @Attr(name, options)
-
-Genera automaticament getters/setters per atributs HTML.
+#### HTML inline (index2.html)
 
-```typescript
-interface AttrOptions {
-    type: 'string' | 'boolean' | 'number'
-    default?: string | boolean | number
-}
+```html
+<div id="dollar-box" style="padding:.875rem;border:2px solid #d1d5db;border-radius:.375rem">
+    Element manipulat pel $ DOM helper
+</div>
+<div>
+    <zs3-button variant="primary" zs3-click="$('#dollar-box').addClass('highlighted')"    size="sm">addClass</zs3-button>
+    <zs3-button                   zs3-click="$('#dollar-box').removeClass('highlighted')" size="sm">removeClass</zs3-button>
+    <zs3-button variant="info"    zs3-click="$('#dollar-box').toggleClass('highlighted')" size="sm">toggleClass</zs3-button>
+    <zs3-button variant="warning" zs3-click="$('#dollar-box').hide()"                     size="sm">hide()</zs3-button>
+    <zs3-button variant="success" zs3-click="$('#dollar-box').show()"                     size="sm">show()</zs3-button>
+    <zs3-button                   zs3-click="$('#dollar-box').text('Text: ' + Date.now())" size="sm">text()</zs3-button>
+</div>
+```
+
+#### TypeScript programàtic (index3.ts)
+
+```ts
+const domActions: Array<[string, string, () => void]> = [
+    ['addClass',    'primary', () => $(`#dollar-box-ts`)?.addClass('highlighted')],
+    ['removeClass', '',        () => $(`#dollar-box-ts`)?.removeClass('highlighted')],
+    ['toggleClass', 'info',    () => $(`#dollar-box-ts`)?.toggleClass('highlighted')],
+    ['hide()',      'warning', () => $(`#dollar-box-ts`)?.hide()],
+    ['show()',      'success', () => $(`#dollar-box-ts`)?.show()],
+    ['text()',      '',        () => $(`#dollar-box-ts`)?.text(`Text: ${Date.now()}`)],
+]
+domActions.forEach(([label, variant, fn]) => {
+    const b = btn(label, variant || undefined); b.size = 'sm'
+    b.addEventListener('zs3-click', fn)
+    dollarRow.append(b)
+})
 ```
 
-**Exemples:**
-
-```typescript
-// string sense default -> string | null
-@Attr('icon', { type: 'string' })
-icon!: string | null
-
-// string amb default -> string
-@Attr('position', { type: 'string', default: 'right' })
-position!: string
+---
 
-// boolean (default false)
-@Attr('disabled', { type: 'boolean' })
-disabled!: boolean
+## Decorators
 
-// boolean amb default true
-@Attr('dismissible', { type: 'boolean', default: true })
-dismissible!: boolean
+Per crear components personalitzats que extenguin `$BaseComponent`:
 
-// number amb default
-@Attr('duration', { type: 'number', default: 5000 })
-duration!: number
-```
+```ts
+import { Component, ObservedAttributes, Attr, $BaseComponent, i18n } from 'zs3-ui-components'
 
-### Exemple complet: Creacio d'un component nou
+@Component('my-component')
+@ObservedAttributes(['title', 'count'])
+class MyComponent extends $BaseComponent {
 
-```typescript
-import { $BaseComponent } from 'zs3-ui-components'
-import { Component, ObservedAttributes, Float, Move, Attr } from 'zs3-ui-components'
+    @Attr('title', { type: 'string' })
+    title!: string | null
 
-@Component('zs3-my-card')
-@ObservedAttributes(['title', 'variant', 'collapsible', 'float', 'move'])
-@Float('.card')
-@Move(':host', '.card-header')
-export class $MyCard extends $BaseComponent {
-    constructor() {
-        super({ useShadowDOM: true, shadowMode: 'open' })
-    }
+    @Attr('count', { type: 'number', default: 0 })
+    count!: number
 
     protected initialize(): void {
-        // Setup logic
+        // Cridat un cop, abans del primer render
     }
 
-    protected afterMount(): void {
-        const header = this.qs('.card-header')
-        if (header && this.collapsible) {
-            this.addManagedEventListener(header, 'click', () => {
-                this.emit('zs3-card-toggle', { collapsed: this.collapsed })
-            })
-        }
-    }
-
-    render(): void {
-        const title = this.getTranslatedAttribute('title', 'Card')
+    protected render(): void {
+        // Accés a traduccions via this.t()
+        const label = this.t('my.label.key')
 
         this.setHTML(`
             <style>
-                :host { display: block; }
-                .card {
-                    border: 1px solid var(--zs3-border-color);
-                    border-radius: var(--zs3-border-radius);
-                    background: var(--zs3-bg-color);
-                }
-                .card-header {
-                    padding: var(--zs3-spacing-md);
-                    font-weight: 600;
-                    border-bottom: 1px solid var(--zs3-border-color);
-                    cursor: ${this.collapsible ? 'pointer' : 'default'};
-                }
-                .card-body { padding: var(--zs3-spacing-md); }
+                :host { display: block; padding: 1rem; }
             </style>
-            <div class="card">
-                <div class="card-header">${title}</div>
-                <div class="card-body"><slot></slot></div>
+            <div>
+                <h2 data-i18n="my.title.key">${this.title ?? label}</h2>
+                <span>Count: ${this.count}</span>
             </div>
         `)
     }
 
-    @Attr('title', { type: 'string', default: 'Card' })
-    cardTitle!: string
-
-    @Attr('variant', { type: 'string' })
-    variant!: string | null
-
-    @Attr('collapsible', { type: 'boolean' })
-    collapsible!: boolean
-
-    @Attr('collapsed', { type: 'boolean' })
-    collapsed!: boolean
-}
-```
-
-```html
-<zs3-my-card title="La meva targeta" collapsible>
-    <p>Contingut de la targeta</p>
-</zs3-my-card>
-```
-
----
-
-## Efecte Float
-
-L'efecte float posiciona un element parcialment amagat fora del seu contenidor, i el mostra completament quan el ratoli passa per sobre.
-
-### API
-
-```typescript
-import { float } from 'zs3-ui-components'
-
-// Us basic (nomes necessita l'atribut `float` al component)
-float(component)
-
-// Amb configuracio personalitzada
-float(component, {
-    visibleRatio: 0.2,        // 20% visible (defecte: 0.15)
-    offset: 10,               // Offset en pixels (defecte: 0)
-    transitionDuration: 0.5,  // Duracio en segons (defecte: 0.4)
-    horizontalPosition: '10px', // Per float top/bottom
-    verticalPosition: '50%',   // Per float left/right
-})
-```
-
-### Posicions
+    protected afterMount(): void {
+        // Actualitza traduccions al shadow root:
+        if (this._shadowRoot) i18n.updateRoot(this._shadowRoot)
+    }
 
-| Posicio | Descripcio |
-|---------|------------|
-| `top` | Amagat a la part superior, es mostra cap avall. |
-| `bottom` | Amagat a la part inferior, es mostra cap amunt. |
-| `left` | Amagat a l'esquerra, es mostra cap a la dreta. |
-| `right` | Amagat a la dreta, es mostra cap a l'esquerra. |
-
-### FloatConfig
-
-```typescript
-interface FloatConfig {
-    visibleRatio?: number        // 0-1, percentatge visible (defecte: 0.15)
-    offset?: number              // Pixels d'offset (defecte: 0)
-    transitionDuration?: number  // Segons (defecte: 0.4)
-    horizontalPosition?: string  // Posicio X per top/bottom (defecte: '50%')
-    verticalPosition?: string    // Posicio Y per left/right (defecte: '50%')
+    // Es crida automàticament quan canvia l'idioma
+    // render() s'invoca automàticament després
+    protected onLocaleChange(): void {
+        // lògica addicional si cal
+    }
 }
 ```
 
-### Events Float
-
-| Event | Detail (`FloatEventDetail`) | Descripcio |
-|-------|----------------------------|------------|
-| `zs3-float-show-start` | `{ position, element }` | L'element comenca a apareixer. |
-| `zs3-float-show-end` | `{ position, element }` | L'element ha acabat d'apareixer. |
-| `zs3-float-hide-start` | `{ position, element }` | L'element comenca a amagar-se. |
-| `zs3-float-hide-end` | `{ position, element }` | L'element s'ha amagat completament. |
-
 ---
 
-## Efecte Move
-
-L'efecte move permet arrossegar elements dins del seu contenidor pare amb el ratoli.
+## CSS Variables
 
-### API
-
-```typescript
-import { move, disableMove, isMoveEnabled, getMoveDirection } from 'zs3-ui-components'
-
-// Moviment lliure
-move({ container: element, direction: 'xy' })
-
-// Nomes horitzontal
-move({ container: element, direction: 'x' })
-
-// Amb drag handle separat
-move({ container: windowEl, dragHandle: titleBarEl, direction: 'xy' })
-
-// Desactivar
-disableMove(dragHandle)
-
-// Comprovar estat
-isMoveEnabled(dragHandle)    // boolean
-getMoveDirection(dragHandle)  // 'x' | 'y' | 'xy' | undefined
-```
-
-### MoveConfig
-
-```typescript
-interface MoveConfig {
-    container: HTMLElement     // Element que es moura
-    dragHandle?: HTMLElement   // Element per arrossegar (defecte: container)
-    direction?: MoveDirection  // 'x' | 'y' | 'xy' (defecte: 'xy')
-}
-```
+Tots els components utilitzen variables CSS que pots sobreescriure:
 
-### MoveDirection
-
-| Valor | Descripcio |
-|-------|------------|
-| `'x'` | Nomes moviment horitzontal. |
-| `'y'` | Nomes moviment vertical. |
-| `'xy'` | Moviment lliure en ambdues direccions. |
-
-### MoveBoundary
-
-| Valor | Descripcio |
-|-------|------------|
-| `'top'` | Limit superior del contenidor. |
-| `'bottom'` | Limit inferior del contenidor. |
-| `'left'` | Limit esquerre del contenidor. |
-| `'right'` | Limit dret del contenidor. |
-
-### Events Move
-
-| Event | Detail (`MoveEventDetail`) | Descripcio |
-|-------|----------------------------|------------|
-| `zs3-move-start` | `{ direction, element, startX, startY }` | Inici d'arrossegament. |
-| `zs3-move` | `{ direction, element, x, y, deltaX, deltaY }` | Durant l'arrossegament. |
-| `zs3-move-end` | `{ direction, element, endX, endY }` | Fi d'arrossegament. |
-| `zs3-move-cancel` | `{ direction, element }` | Arrossegament cancel-lat amb Escape. |
-| `zs3-move-boundary` | `{ direction, element, x, y, boundary }` | S'ha tocat un limit del contenidor. |
-
-### MoveEventDetail
-
-```typescript
-interface MoveEventDetail {
-    direction: MoveDirection
-    element: HTMLElement
-    x?: number
-    y?: number
-    startX?: number
-    startY?: number
-    endX?: number
-    endY?: number
-    deltaX?: number
-    deltaY?: number
-    boundary?: MoveBoundary
+```css
+:root {
+    /* Colors principals */
+    --zs3-primary-color:      #3b82f6;
+    --zs3-secondary-color:    #6b7280;
+    --zs3-success-color:      #10b981;
+    --zs3-danger-color:       #ef4444;
+    --zs3-warning-color:      #f59e0b;
+    --zs3-info-color:         #06b6d4;
+
+    /* Fons i text */
+    --zs3-bg-color:           #f9fafb;
+    --zs3-fg-color:           #111827;
+    --zs3-surface-color:      #ffffff;
+    --zs3-surface-alt-color:  #f3f4f6;
+    --zs3-border-color:       #e5e7eb;
+
+    /* Tipografia */
+    --zs3-font-family:        system-ui, sans-serif;
+    --zs3-font-size-base:     1rem;
+
+    /* Espaciat */
+    --zs3-spacing-sm:         0.5rem;
+    --zs3-spacing-md:         1rem;
+    --zs3-spacing-lg:         1.5rem;
+
+    /* Forma i efectes */
+    --zs3-border-radius:      0.375rem;
+    --zs3-shadow-sm:          0 1px 2px rgba(0,0,0,0.05);
+    --zs3-shadow-xl:          0 20px 25px -5px rgba(0,0,0,0.1);
+    --zs3-transition-base:    250ms ease-in-out;
+    --zs3-transition-fast:    150ms ease-in-out;
+
+    /* Z-index */
+    --zs3-z-index-modal:      1000;
+    --zs3-z-index-tooltip:    2000;
 }
 ```
 
----
-
-## Exemples complets
-
-### Exemple HTML amb inline handlers
-
-```html
-<!doctype html>
-<html lang="ca">
-<head>
-    <meta charset="UTF-8" />
-    <title>ZS3 Demo</title>
-</head>
-<body>
-    <!-- Notificacio reusable -->
-    <zs3-notification id="notif" dismissible show-icon show-progress duration="4000">
-    </zs3-notification>
-
-    <!-- Toolbar flotant superior -->
-    <zs3-toolbar float="top" direction="row" align="center" gap="0.5rem">
-        <zs3-button icon="error" variant="danger" size="sm"
-            zs3-click="
-                const n = $('#notif').$;
-                n.setAttribute('type', 'error');
-                n.setAttribute('title', 'Error');
-                n.setAttribute('message', 'Alguna cosa ha anat malament');
-                n.forceUpdate(); n.show();
-                log.info('Notificacio error mostrada')
-            "
-        >Error</zs3-button>
-
-        <zs3-button icon="accept" variant="success" size="sm"
-            zs3-click="
-                const n = $('#notif').$;
-                n.setAttribute('type', 'success');
-                n.setAttribute('title', 'Exit!');
-                n.setAttribute('message', 'Operacio completada');
-                n.forceUpdate(); n.show();
-            "
-        >Exit</zs3-button>
-    </zs3-toolbar>
-
-    <!-- Dialog predefinit -->
-    <zs3-modal-dialog
-        id="dlg-confirm"
-        title="Confirmar"
-        message="Estas segur?"
-        show-accept show-cancel
-        accept-variant="primary"
-        size="small"
-    ></zs3-modal-dialog>
-
-    <!-- Boto que obre el dialog -->
-    <zs3-button variant="primary"
-        zs3-click="
-            $('#dlg-confirm').$.showDialog().then(function(a) {
-                log.info('Resultat: ' + a)
-            })
-        "
-    >Obrir dialog</zs3-button>
-
-    <script type="module" src="./app.ts"></script>
-</body>
-</html>
-```
-
-### Exemple TypeScript
-
-```typescript
-import { $, log, i18n, themeManager } from 'zs3-ui-components'
-import { $Notification } from 'zs3-ui-components'
-import { $ModalDialog } from 'zs3-ui-components'
-import type { ThemeType } from 'zs3-ui-components'
-
-// Carregar traduccions
-i18n.loadMultiple({
-    ca: { 'hello': 'Hola!', 'btn.save': 'Desar' },
-    en: { 'hello': 'Hello!', 'btn.save': 'Save' },
-})
-i18n.init({ locale: 'ca', fallbackLocale: 'en' })
-
-// Setup botons de notificacio
-$('#btn-success')?.addEvent('zs3-click', () => {
-    $Notification.success('Operacio completada!', { duration: 3000 })
-})
-
-$('#btn-error')?.addEvent('zs3-click', () => {
-    $Notification.error('Error de connexio', { position: 'bottom-right' })
-})
-
-// Setup dialogs
-$('#btn-confirm')?.addEvent('zs3-click', async () => {
-    const result = await $ModalDialog.confirm('Estas segur?', 'Confirmar')
-    log.info(`Resultat: ${result ? 'acceptat' : 'cancel-lat'}`)
-})
-
-$('#btn-delete')?.addEvent('zs3-click', async () => {
-    const deleted = await $ModalDialog.confirmDelete('fitxer.txt')
-    if (deleted) log.info('Fitxer eliminat')
-})
-
-// Canviar tema
-$('#btn-dark')?.addEvent('zs3-click', () => {
-    themeManager.setTheme('dark')
-})
-
-// Canviar idioma
-$('#btn-lang-en')?.addEvent('zs3-click', () => {
-    i18n.setLocale('en')
-})
-
-// Events globals
-window.addEventListener('zs3-theme-change', (e: Event) => {
-    const detail = (e as CustomEvent).detail
-    log.info(`Tema canviat a: ${detail.theme}`)
-})
-
-window.addEventListener('zs3-locale-change', (e: Event) => {
-    const detail = (e as CustomEvent).detail
-    log.info(`Idioma canviat a: ${detail.locale}`)
-})
-```
-
----
-
-## Estructura del projecte
-
-```
-zs3-ui-components/
-├── src/                        # Codi font
-│   ├── components/             # Web Components
-│   │   ├── zs3-BaseComponent.ts
-│   │   ├── zs3-Button.ts
-│   │   ├── zs3-Icon.ts
-│   │   ├── zs3-Toolbar.ts
-│   │   ├── zs3-Modal.ts
-│   │   ├── zs3-ModalDialog.ts
-│   │   ├── zs3-Notification.ts
-│   │   ├── zs3-Window.ts
-│   │   ├── zs3-Form.ts         # Formulari dinamic
-│   │   ├── zs3-LoginForm.ts    # Login (hereta Form)
-│   │   ├── zs3-RegisterForm.ts # Registre (hereta Form)
-│   │   ├── zs3-RecoverPasswordForm.ts  # Recuperacio (hereta Form)
-│   │   ├── zs3-SelectTheme.ts
-│   │   ├── zs3-SelectLocale.ts
-│   │   ├── zs3-common.ts       # Float & Move
-│   │   └── types.ts            # Variant type
-│   ├── decorators/             # TypeScript decoradors
-│   │   ├── component.ts
-│   │   ├── observedAttributes.ts  # Suporta inherit
-│   │   ├── float.ts
-│   │   ├── move.ts
-│   │   ├── attr.ts
-│   │   └── index.ts
-│   ├── css/
-│   │   └── zs3.css             # Temes i estils base
-│   ├── i18n/
-│   │   └── defaults.ts         # Traduccions per defecte
-│   ├── zs3.ts                  # ZS3, $, params, log, debug, storage
-│   ├── theme.ts                # ThemeManager
-│   ├── i18n.ts                 # Sistema i18n
-│   ├── eventBus.ts             # Bus d'events (pub/sub)
-│   ├── diContainer.ts          # Contenidor d'injeccio de dependencies
-│   ├── types.ts                # EventDescription
-│   └── index.ts                # Entry point
-├── dist/                       # Build output
-│   ├── index.js                # ES Module compilat
-│   ├── index.css               # CSS compilat
-│   └── index.d.ts              # Declaracions TypeScript
-├── dev/                        # Demos de desenvolupament
-├── package.json
-├── tsconfig.json
-├── vite.config.ts
-└── README.md
-```
+Els temes sobreescriuen automàticament les variables corresponents quan es crida `themeManager.setTheme('dark')` o l'usuari utilitza `<zs3-select-theme>`.
 
 ---
 
-## Suport i llicencia
+## License
 
-- **Llicencia:** ISC
-- **Autor:** Manuel Candeal
-- **Repositori:** [github.com/manuelcandeal/zs3-ui-components](https://github.com/manuelcandeal/zs3-ui-components)
-- **Issues:** [github.com/manuelcandeal/zs3-ui-components/issues](https://github.com/manuelcandeal/zs3-ui-components/issues)
+Apache License 2.0 — vegeu el fitxer [LICENSE](./LICENSE).