ZS3 UI Components

Biblioteca de components web moderna amb sistema de temes, internacionalitzacio i suport per CSS variables.

| | |
|------------|----------------------------------------------|
| Paquet | zs3-ui-components |
| Versio | 1.0.10 |
| Llicencia | ISC |
| Autor | Manuel Candeal |
| Repositori | github.com/manuelcandeal/zs3-ui-components |
| Tipus | ES Module |

---

Taula de continguts

- Installacio i importacions
- Classe ZS3 ($)
- Utilitats
- $Parameters (params)
- $Log (log)
- $Debug (debug)
- $Storage (storage)
- Sistema de Temes (ThemeManager)
- CSS Variables
- Internacionalitzacio ($I18n)
- Components
- zs3-button
- zs3-icon
- zs3-toolbar
- zs3-notification
- zs3-modal
- zs3-modal-dialog
- zs3-window
- zs3-form
- zs3-login-form
- zs3-register-form
- zs3-recover-password-form
- zs3-select-theme
- zs3-select-locale
- Inline Event Handlers
- Guia de desenvolupament de nous components
- $BaseComponent
- Cicle de vida
- Metodes disponibles
- Decoradors
- Efecte Float
- Efecte Move
- Exemples complets
- Estructura del projecte
- Suport i llicencia

---

Installacio i importacions

$3

``bash
npm install zs3-ui-components
`

$3

Importa tot el paquet (registra automaticament tots els custom elements):

`typescript
import 'zs3-ui-components'
`

$3

Importa nomes el que necessitis:

`typescript
// Utilitats
import { $, params, log, debug, storage, $env } from 'zs3-ui-components'

// Sistema de temes
import { themeManager, getCSSVariable, setCSSVariable, initThemeSystem } from 'zs3-ui-components'

// Internacionalitzacio
import { i18n } 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'
`

---

Classe ZS3 ($)

La classe ZS3 proporciona una API similar a jQuery per a la manipulacio d'elements DOM.

$3

`typescript
// Seleccionar elements amb la funcio $
const element = $('selector') // Retorna ZS3 | null
const element = new ZS3('selector') // Constructor directe

// Crear ZS3 des d'un HTMLElement
const zs3 = ZS3.fromElement(htmlElement)
`

$3

| Propietat | Tipus | Descripcio |
|-----------|-------|------------|
| $ | HTMLElement | Primer element seleccionat |
| $$ | HTMLElement[] | Tots els elements seleccionats |

$3

#### Contingut

| 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. |

#### Visibilitat i estat

| 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. |

#### Classes CSS

| 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. |

#### Events

| 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. |

#### Valors i dimensions

| 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. |

#### 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). |

#### Atributs i dades

| 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). |

#### Estils

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| style() | (styles: Record \| string, value?: string) => ZS3 \| string | Get/set estils CSS. Accepta objecte d'estils, clau+valor, o clau sola (getter). |

#### Navegacio

| 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. |

#### Col-leccio

| 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 | Fa ZS3 iterable amb for...of i spread operator. |

$3

| 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. |

$3

Retorna informacio de l'entorn d'execucio:

`typescript
const env = $env()
// { userAgent: '...', language: 'ca', platform: 'Win32', ZS3: '1.0.6' }
`

---

Utilitats

$3

Gestio de parametres d'URL.

`typescript
import { params } from 'zs3-ui-components'
`

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| getAll() | () => Record | Obte tots els parametres d'URL com a objecte. |
| get() | (key: string) => string \| Record | 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. |

Exemple:

`typescript
params.set('page', '2')
const page = params.get('page') // '2'
params.has('page') // true
params.delete('page')
const all = params.getAll() // { ... }
`

$3

Sistema de logging amb nivells, timestamps i colors a la consola.

`typescript
import { log } from 'zs3-ui-components'
`

| 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. |

Exemple:

`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')

log.setLevel('warn') // Nomes mostra warn i error
log.setEnabled(false) // Desactiva tot el logging
`

$3

Utilitat per a debugging d'esdeveniments DOM en temps real.

`typescript
import { debug } from 'zs3-ui-components'
`

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| start() | (selector: string, eventType: keyof HTMLElementEventMap) => void | Inicia el debug d'un event sobre un selector. |
| stop() | (selector: string, eventType: keyof HTMLElementEventMap) => void | Atura el debug d'un event. |
| stopAll() | () => void | Atura tot el debugging. |
| list() | () => string[] | Llista tots els debugs actius (format selector:eventType). |

Exemple:

`typescript
debug.start('#myButton', 'click') // Mostra per consola cada click a #myButton
debug.start('.container', 'mousemove')
debug.list() // ['#myButton:click', '.container:mousemove']
debug.stop('#myButton', 'click')
debug.stopAll()
`

$3

Wrapper per localStorage amb serialitzacio JSON automatica.

`typescript
import { storage } from 'zs3-ui-components'
`

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| set() | (key: string, value: unknown) => void | Guarda un valor (serialitzat amb JSON.stringify). |
| get() | (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. |

Exemple:

`typescript
storage.set('user', { name: 'Joan', role: 'admin' })
const user = storage.get<{ name: string; role: string }>('user')
// { name: 'Joan', role: 'admin' }

storage.has('user') // true
storage.keys() // ['user', 'zs3-theme', 'zs3-locale', ...]
storage.remove('user')
storage.clear()
`

---

Sistema de Temes (ThemeManager)

El sistema de temes permet canviar l'aparenca visual de tota l'aplicacio.

`typescript
import { themeManager } from 'zs3-ui-components'
`

$3

| 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. |

$3

| 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. |

$3

Quan canvia el tema, s'emet un event global:

`typescript
window.addEventListener('zs3-theme-change', (e: CustomEvent) => {
console.log('Nou tema:', e.detail.theme)
})
`

$3

`typescript
import { getCSSVariable, setCSSVariable, initThemeSystem } from 'zs3-ui-components'

// Llegir una CSS variable (sense el prefix --)
getCSSVariable('zs3-primary-color') // '#3b82f6'

// Establir una CSS variable globalment
setCSSVariable('zs3-primary-color', '#ff0000')

// Inicialitzar el sistema de temes amb opcions
initThemeSystem({ defaultTheme: 'dark' })
`

$3

Per afegir suport de temes a un component personalitzat que no hereti de $BaseComponent:

`typescript
import { withThemeSupport } from 'zs3-ui-components'

class MyElement extends withThemeSupport(HTMLElement) {
render() { / ... / }
}
`

$3

Totes les variables utilitzen el prefix zs3-.

#### Variables globals (compartides per tots els temes)

`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;
}
`

#### 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

---

Internacionalitzacio ($I18n)

Sistema complet d'internacionalitzacio amb interpolacio de parametres i actualitzacio automatica del DOM.

`typescript
import { i18n } from 'zs3-ui-components'
`

$3

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| init() | (config?: Partial) => void | Inicialitza el sistema i18n. Carrega l'idioma guardat si existeix. |
| load() | (locale: string, translations: Record) => void | Carrega traduccions per un idioma. |
| loadMultiple() | (locales: Record>) => void | Carrega multiples idiomes alhora. |
| t() | (key: string, params?: Record) => 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 | Obte totes les traduccions d'un idioma. |

$3

Utilitzeu atributs data-i18n i data-i18n-attr per a traduccions automatiques:

`html



Titol per defecte



`

Quan canvieu l'idioma amb setLocale(), tots els elements amb data-i18n i data-i18n-attr s'actualitzen automaticament.

$3

`typescript
window.addEventListener('zs3-locale-change', (e: CustomEvent) => {
console.log('Nou idioma:', e.detail.locale)
console.log('Idioma anterior:', e.detail.previousLocale)
})
`

$3

`typescript
import { i18n } from 'zs3-ui-components'

// 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' },
})

// Inicialitzar
i18n.init({ locale: 'ca', fallbackLocale: 'en' })

// Traduir amb interpolacio
i18n.t('hello', { name: 'Joan' }) // 'Hola Joan!'

// Canviar idioma
i18n.setLocale('en')
i18n.t('hello', { name: 'Joan' }) // 'Hello Joan!'
`

---

Components

$3

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

| 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. |

#### CSS Variables del boto

`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);
}
`

#### Exemples

`html

Clic


Desar


Eliminar


Processant...


Menu
`

---

$3

Component d'icona SVG amb suport per transformacions, colors i interactivitat.

#### Atributs

| Atribut | Tipus | Per defecte | Descripcio |
|---------|-------|-------------|------------|
| name | string | - | Nom de la icona (obligatori). |
| size | 'small' \| 'medium' \| 'large' \| number | 'medium' | Mida: small=18px, 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. |

#### Events

| Event | Detail | Descripcio |
|-------|--------|------------|
| zs3-icon-click | { icon, name, originalEvent } | Icona clicada (si clickable). |

#### Metodes estatics

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| $Icon.addIcon() | (name: string, path: string) => void | Afegeix una icona personalitzada (SVG path). |
| $Icon.addIcons() | (icons: Record) => void | Afegeix multiples icones. |
| $Icon.getAvailableIcons() | () => string[] | Llista totes les icones disponibles. |

#### Icones disponibles

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

#### Exemples

`html





`

`typescript
// Afegir icona personalitzada
$Icon.addIcon('custom', '')
`

---

$3

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


Desar
Editar
Eliminar




Menu

`

---

$3

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) => 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
type="success"
title="Desat!"
message="Els canvis s'han guardat correctament"
auto-show
show-progress
>
`

`typescript
// Crear programaticament
$Notification.success('Operacio completada!', { duration: 3000 })
$Notification.error('Error de connexio', { position: 'bottom-right' })

// Amb i18n
$Notification.create({
type: 'info',
i18nTitle: 'notif.info.title',
i18nMessage: 'notif.info.msg',
showProgress: true,
})
`

---

$3

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. |

Mides:
- small: max-width 400px
- medium: max-width 600px
- large: max-width 900px
- fullscreen: 100% pantalla

#### 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) => void | Actualitza la configuracio. |

#### Exemples

`html



Titol del Modal


`

---

$3

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: 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 | Mostra el dialog i retorna una Promise que es resol amb l'accio ('accept', 'cancel' o 'close'). |
| updateDialog() | (config: Partial) => void | Actualitza el contingut del dialog. |

#### Factory estatics

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| $ModalDialog.confirm() | (message: string, title?: string) => Promise | Dialog de confirmacio. Retorna true si accepta. |
| $ModalDialog.confirmI18n() | (config) => Promise | Dialog de confirmacio amb i18n. |
| $ModalDialog.alert() | (message: string, title?: string) => Promise | Dialog d'alerta. |
| $ModalDialog.alertI18n() | (config) => Promise | Dialog d'alerta amb i18n. |
| $ModalDialog.prompt() | (title: string, content: HTMLElement) => Promise | Dialog amb contingut personalitzat via slot. |
| $ModalDialog.confirmDelete() | (itemName: string) => Promise | Dialog de confirmacio d'eliminacio. |
| $ModalDialog.confirmDeleteI18n() | (config) => Promise | Dialog d'eliminacio amb i18n. |
| $ModalDialog.create() | (config: ModalDialogConfig) => $ModalDialog | Crea un dialog des de configuracio completa. |

#### Exemples

`html

id="dlg"
title="Confirmar"
message="Estas segur?"
show-accept
show-cancel
accept-variant="primary"
size="small"
>
`

`typescript
// Factory estatic
const result = await $ModalDialog.confirm('Estas segur?', 'Confirmar')
if (result) { / acceptat / }

// 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',
})
document.body.appendChild(dialog)
const action = await dialog.showDialog()
dialog.remove()
`

---

$3

Component de finestra arrossegable amb barra de titol i controls.

#### Atributs

| 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. |

#### 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

| 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). |

#### Exemple

`html



Contingut de la finestra. Arrossega la barra de titol!

| 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 | 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) => 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 | 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
}

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
}

interface FormFieldOption {
value: string
label: string
i18nLabel?: string
}
`

#### Factory estatics

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| $Form.create() | (config: FormConfig) => $Form | Crea un formulari des de configuracio. |
| $Form.prompt() | (config: FormConfig) => Promise \| null> | Crea i mostra un formulari. Retorna els valors o null si es cancella. |

#### Exemples

`html

id="contactForm"
title="Contacte"
i18n-title="form.contact.title"
show-cancel
>


`

`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);
}
`

---

$3

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. |

Tambe hereta tots els atributs de zs3-form.

#### Events

| Event | Detail | Descripcio |
|-------|--------|------------|
| zs3-form-submit | { values: { email, password }, isValid } | Formulari enviat. |
| zs3-login-register | { form } | Boto de registre clicat. |

#### Camps predefinits

- email: Camp d'email obligatori
- password: Camp de contrasenya obligatori (minim 6 caracters)

#### Exemple

`html
i18n-title="app.login.title"
show-register
zs3-form-submit="log.info('Login:', event.detail.values)"
zs3-login-register="window.location = '/register'"
>
`

---

$3

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.

#### 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
title="Crear compte"
i18n-title="app.register.title"
show-cancel
zs3-form-submit="handleRegistration(event.detail.values)"
zs3-form-cancel="window.location = '/login'"
>
`

---

$3

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.

#### Camps predefinits

- email: Email obligatori

#### Exemple

`html
title="Has oblidat la contrasenya?"
i18n-title="app.recover.title"
show-cancel
zs3-form-submit="sendRecoveryEmail(event.detail.values.email)"
>
`

---

$3

Selector desplegable per canviar de tema. Es posiciona de forma fixa (position: fixed) per defecte.

#### Atributs

| Atribut | Tipus | Per defecte | Descripcio |
|---------|-------|-------------|------------|
| zs3-position | string | 'position: fixed; top: 1rem; right: 1rem' | CSS de posicionament personalitzat. |

#### Exemple

`html





`

---

$3

Selector desplegable per canviar d'idioma. Mostra els idiomes carregats al sistema i18n.

#### Atributs

| Atribut | Tipus | Per defecte | Descripcio |
|---------|-------|-------------|------------|
| zs3-position | string | 'position: fixed; top: 1rem; right: 1rem' | CSS de posicionament personalitzat. |

#### Exemple

`html

`

---

Inline Event Handlers

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:

| Variable | Tipus | Descripcio |
|----------|-------|------------|
| $ | (selector: string) => ZS3 \| null | Funcio de seleccio d'elements. |
| log | $Log | Sistema de logging. |
| debug | $Debug | Utilitat de debugging. |
| params | $Parameters | Gestio de parametres d'URL. |
| storage | $Storage | Gestio de localStorage. |
| $env | () => Record | Informacio d'entorn. |
| this | HTMLElement | L'element que emet l'event. |
| event | CustomEvent | L'event emes. |

$3

`html

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


variant="primary"
zs3-click="
$('#myDialog').$.showDialog().then(function(action) {
$('#output').$.textContent = 'Resultat: ' + action;
log.info('Dialog: ' + action)
})
"
>Obrir dialog


zs3-click="
storage.set('lastClick', new Date().toISOString());
log.info('Desat a storage: ' + storage.get('lastClick'))
"
>Desar timestamp
`

Els inline handlers tambe funcionen amb events de float i move:

`html
float="top"
zs3-float-show-start="log.info('Toolbar apareixent')"
zs3-float-hide-end="log.info('Toolbar amagat')"
>
Boto

`

---

Guia de desenvolupament de nous components

$3

`
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)
`

$3

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
delegateFocus?: boolean // false per defecte
}
`

$3

`
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' })
`

$3

#### Queries al DOM intern

| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| qs() | (selector: string) => T \| null | querySelector dins del root (shadow o element). |
| qsAll() | (selector: string) => NodeListOf | 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() | (eventName: string, detail?: T) => boolean | Emet un CustomEvent. Executa inline handlers si existeixen. Bloquejat si disabled/loading. |
| emitLifecycleEvent() | (eventName: string, detail?: Record) => 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 | Sol-licita re-render en el proxim animation frame. |
| forceUpdate() | () => void | Forca re-render immediat + float + move. |
| debounce() | (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

$3

Registra el custom element amb customElements.define().

`typescript
@Component('zs3-my-component')
export class $MyComponent extends $BaseComponent { ... }
`

$3

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.

$3

Configura el selector de l'element target per l'efecte float.

`typescript
@Float('button') // Selector dins del shadow DOM
@Float('.toolbar') // Classe CSS interna
`

$3

Configura el moviment drag & drop.

`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
`

$3

Genera automaticament getters/setters per atributs HTML.

`typescript
interface AttrOptions {
type: 'string' | 'boolean' | 'number'
default?: string | boolean | number
}
`

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

// boolean amb default true
@Attr('dismissible', { type: 'boolean', default: true })
dismissible!: boolean

// number amb default
@Attr('duration', { type: 'number', default: 5000 })
duration!: number
`

$3

`typescript
import { $BaseComponent } from 'zs3-ui-components'
import { Component, ObservedAttributes, Float, Move, Attr } from 'zs3-ui-components'

@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' })
}

protected initialize(): void {
// Setup logic
}

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')

this.setHTML(

@Attr('collapsed', { type: 'boolean' })
collapsed!: boolean
}
`

`html



Contingut de la targeta

`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: