Modern Web Components library with built-in theming system and CSS variables support
npm install zs3-ui-componentsBiblioteca 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 |
---
- 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
---
``bash`
npm install zs3-ui-components
Importa tot el paquet (registra automaticament tots els custom elements):
`typescript`
import 'zs3-ui-components'
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'
`
---
)La classe ZS3 proporciona una API similar a jQuery per a la manipulacio d'elements DOM.
`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)
`
| Propietat | Tipus | Descripcio |
|-----------|-------|------------|
| $ | HTMLElement | Primer element seleccionat |$$
| | HTMLElement[] | Tots els elements seleccionats |
#### 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 | 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. |
| 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. |
Retorna informacio de l'entorn d'execucio:
`typescript`
const env = $env()
// { userAgent: '...', language: 'ca', platform: 'Win32', ZS3: '1.0.6' }
---
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() // { ... }
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
`
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()
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()
| | | 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()
`
---
El sistema de temes permet canviar l'aparenca visual de tota l'aplicacio.
`typescript`
import { themeManager } from 'zs3-ui-components'
| 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. |
| 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. |
Quan canvia el tema, s'emet un event global:
`typescript`
window.addEventListener('zs3-theme-change', (e: CustomEvent) => {
console.log('Nou tema:', e.detail.theme)
})
`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' })
`
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() { / ... / }
}
`
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
Light
`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;
}
Light Blue
`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;
}
Dark
`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;
}
Elegant
`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;
}
Modern
`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;
}
High Contrast
`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;
}
System
Utilitza els mateixos valors que light per defecte, i canvia automaticament a valors de dark quan prefers-color-scheme: dark esta actiu.
---
Sistema complet d'internacionalitzacio amb interpolacio de parametres i actualitzacio automatica del DOM.
`typescript`
import { i18n } from 'zs3-ui-components'
| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| init() | (config?: Partial | Inicialitza el sistema i18n. Carrega l'idioma guardat si existeix. |load()
| | (locale: string, translations: Record | Carrega traduccions per un idioma. |loadMultiple()
| | (locales: Record | Carrega multiples idiomes alhora. |t()
| | (key: string, params?: Record | 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. |
Utilitzeu atributs data-i18n i data-i18n-attr per a traduccions automatiques:
`htmlTitol per defecte
`
Quan canvieu l'idioma amb setLocale(), tots els elements amb data-i18n i data-i18n-attr s'actualitzen automaticament.
`typescript`
window.addEventListener('zs3-locale-change', (e: CustomEvent) => {
console.log('Nou idioma:', e.detail.locale)
console.log('Idioma anterior:', e.detail.previousLocale)
})
`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!'
`
---
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
`
---
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 | 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', '
---
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
`
---
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 | 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`
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,
})
`
---
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 400pxmedium
- : max-width 600pxlarge
- : max-width 900pxfullscreen
- : 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 | Actualitza la configuracio. |
#### Exemples
` Contingut del modalhtml
Titol del Modal
`
---
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 | 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`
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()
`
---
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
` Contingut de la finestra. Arrossega la barra de titol!html`
---
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 | 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 | 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 | Crea i mostra un formulari. Retorna els valors o null si es cancella. |
#### Exemples
`html
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);
}
`
---
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`
show-register
zs3-form-submit="log.info('Login:', event.detail.values)"
zs3-login-register="window.location = '/register'"
>
---
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`
i18n-title="app.register.title"
show-cancel
zs3-form-submit="handleRegistration(event.detail.values)"
zs3-form-cancel="window.location = '/login'"
>
---
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`
i18n-title="app.recover.title"
show-cancel
zs3-form-submit="sendRecoveryEmail(event.detail.values.email)"
>
---
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
`
---
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`
---
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. |
`html
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-click="
$('#myDialog').$.showDialog().then(function(action) {
$('#output').$.textContent = 'Resultat: ' + action;
log.info('Dialog: ' + action)
})
"
>Obrir dialog
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`
zs3-float-show-start="log.info('Toolbar apareixent')"
zs3-float-hide-end="log.info('Toolbar amagat')"
>
---
``
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)
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
}
`
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' })
`
#### Queries al DOM intern
| Metode | Signatura | Descripcio |
|--------|-----------|------------|
| qs() | | querySelector dins del root (shadow o element). |qsAll()
| | | 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()
| | | Emet un CustomEvent. Executa inline handlers si existeixen. Bloquejat si disabled/loading. |emitLifecycleEvent()
| | (eventName: string, detail?: Record | 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()
| | | 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. |
---
Registra el custom element amb customElements.define().
`typescript`
@Component('zs3-my-component')
export class $MyComponent extends $BaseComponent { ... }
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.
Configura el selector de l'element target per l'efecte float.
`typescript`
@Float('button') // Selector dins del shadow DOM
@Float('.toolbar') // Classe CSS interna
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
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
`
`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('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
Contingut de la targeta
`---
Efecte Float
L'efecte float posiciona un element parcialment amagat fora del seu contenidor, i el mostra completament quan el ratoli passa per sobre.
$3
`typescript
import { float } from 'zs3-ui-components'// Us basic (nomes necessita l'atribut
float` al component)// Amb configuracio personalitzada
float(component, {
visibleRatio: 0.2, // 20% visible (defecte: 0.15)
offset: