zs3-ui-components 1.1.8 → 1.1.10

package/README.md

@@ -5,7 +5,7 @@
 | | |
 |------------|----------------------------------------------|
 | **Paquet** | `zs3-ui-components` |
-| **Versio** | 1.1.8 |
+| **Versio** | 1.1.9 |
 | **Llicencia** | ISC |
 | **Autor** | Manuel Candeal |
 | **Repositori** | [github.com/manuelcandeal/zs3-ui-components](https://github.com/manuelcandeal/zs3-ui-components) |
@@ -23,6 +23,7 @@
   - [$Debug (debug)](#debug-debug)
   - [$Storage (storage)](#storage-storage)
   - [$Store](#store)
+  - [HttpClient](#httpclient)
 - [Sistema de Temes (ThemeManager)](#sistema-de-temes-thememanager)
   - [CSS Variables](#css-variables)
 - [Internacionalitzacio ($I18n)](#internacionalitzacio-i18n)
@@ -166,19 +167,23 @@ La classe `ZS3` proporciona una API similar a jQuery per a la manipulacio d'elem
 ```typescript
 // Seleccionar elements amb la funcio $
 const element = $('selector')            // Retorna ZS3 | null (cerca des de document)
-const element = $('selector', rootEl)    // Cerca dins d'un HTMLElement concret
+const element = $('selector', rootEl)    // Cerca dins d'un HTMLElement, Document o ShadowRoot
 const element = new ZS3('selector')      // Constructor directe (cerca des de document)
-const element = new ZS3('selector', rootEl) // Constructor amb element arrel
+const element = new ZS3('selector', rootEl) // Constructor amb element arrel (HTMLElement, Document o ShadowRoot)
 
 // Crear ZS3 des d'un HTMLElement
 const zs3 = ZS3.fromElement(htmlElement)
 ```
 
-El segon parametre (`root`) es opcional i per defecte es `document`. Permet limitar el `querySelectorAll` a un subarbre del DOM concret, util per exemple dins de Shadow DOM o components:
+El segon parametre (`root`) es opcional i per defecte es `document`. Accepta `Document`, `HTMLElement` o `ShadowRoot`, la qual cosa permet limitar la cerca a un subarbre del DOM concret, incloent shadow roots de Web Components:
 
 ```typescript
 const container = document.getElementById('app')
 const buttons = $('button', container) // Nomes els botons dins de #app
+
+// Dins d'un Web Component (shadow DOM)
+const btn = $('button', this.root)  // this.root pot ser ShadowRoot o HTMLElement
+btn?.addEvent('click', handler)
 ```
 
 ### Propietats
@@ -375,8 +380,8 @@ El mateix parell `selector:eventType` pot estar actiu en múltiples roots simult
 
 | Metode | Signatura | Descripcio |
 |--------|-----------|------------|
-| `start()` | `(selector: string, eventType: keyof HTMLElementEventMap, root?: Document \| HTMLElement) => void` | Inicia el debug. Es poden registrar múltiples roots per al mateix selector+event. |
-| `stop()` | `(selector: string, eventType: keyof HTMLElementEventMap, root?: Document \| HTMLElement) => void` | Atura el debug per al root indicat. Si hi ha més roots actius per al mateix selector+event, els altres continuen. |
+| `start()` | `(selector: string, eventType: keyof HTMLElementEventMap, root?: Document \| HTMLElement \| ShadowRoot) => void` | Inicia el debug. Es poden registrar múltiples roots per al mateix selector+event. |
+| `stop()` | `(selector: string, eventType: keyof HTMLElementEventMap, root?: Document \| HTMLElement \| ShadowRoot) => void` | Atura el debug per al root indicat. Si hi ha més roots actius per al mateix selector+event, els altres continuen. |
 | `stopAll()` | `() => void` | Atura tot el debugging, per a tots els selectors, events i roots actius. |
 | `list()` | `() => string[]` | Llista tots els debugs actius en format `selector:eventType`. Si hi ha múltiples roots per al mateix parell, apareix una entrada per cada root. |
 
@@ -585,6 +590,146 @@ store.subscribe('*', (state) => {
 
 ---
 
+## HttpClient
+
+Client HTTP basat en `fetch` amb suport per a interceptors, reintentos automàtics i timeout. Cada instància té la seva pròpia configuració, per la qual cosa no s'exposa com a singleton global.
+
+```typescript
+import { HttpClient, HttpError } from 'zs3-ui-components'
+import type { HttpClientConfig, HttpResponse } from 'zs3-ui-components'
+```
+
+### Configuració
+
+```typescript
+const api = new HttpClient({
+    baseUrl: 'https://api.exemple.com',  // Base de totes les URLs relatives
+    timeout: 10_000,                      // ms abans de cancel·lar (per defecte 10000)
+    retries: 2,                           // Reintentos automàtics en errors 5xx/timeout
+    retryDelay: 1_000,                    // ms entre reintent (es duplica cada vegada)
+    headers: {                            // Capçaleres per defecte (Content-Type i Accept: application/json ja inclosos)
+        Authorization: 'Bearer token',
+    },
+})
+```
+
+### Metodes
+
+| Metode | Signatura | Descripcio |
+|--------|-----------|------------|
+| `get()` | `<T>(url: string, params?: Record<string, string>) => Promise<HttpResponse<T>>` | Peticio GET. Els `params` s'afegeixen com a query string. |
+| `post()` | `<T>(url: string, body?: unknown) => Promise<HttpResponse<T>>` | Peticio POST amb body JSON. |
+| `put()` | `<T>(url: string, body?: unknown) => Promise<HttpResponse<T>>` | Peticio PUT. |
+| `patch()` | `<T>(url: string, body?: unknown) => Promise<HttpResponse<T>>` | Peticio PATCH. |
+| `delete()` | `<T>(url: string) => Promise<HttpResponse<T>>` | Peticio DELETE. |
+| `request()` | `<T>(config: HttpRequestConfig) => Promise<HttpResponse<T>>` | Peticio completament configurable. |
+
+### Resposta
+
+Tots els metodes retornen `Promise<HttpResponse<T>>`:
+
+```typescript
+interface HttpResponse<T> {
+    data: T        // Cos de la resposta (parseig JSON automatic)
+    status: number
+    statusText: string
+    headers: Headers
+    config: HttpRequestConfig
+}
+```
+
+### Interceptors
+
+Els interceptors permeten modificar totes les peticions o respostes de forma centralitzada. Retornen una funció per cancel·lar-los.
+
+```typescript
+// Interceptor de peticio: afegir token a totes les crides
+const removeAuth = api.onRequest(config => ({
+    ...config,
+    headers: { ...config.headers, Authorization: `Bearer ${getToken()}` },
+}))
+
+// Interceptor de resposta: transformar dades
+api.onResponse(response => ({
+    ...response,
+    data: transform(response.data),
+}))
+
+// Interceptor d'error: gestio centralitzada
+api.onError(async error => {
+    if (error.isUnauthorized) {
+        await refreshToken()
+        // Si es retorna un HttpResponse, la peticio es considera recuperada
+    }
+    throw error  // Si es relanca, l'error arriba al catch del cridant
+})
+
+// Cancel·lar un interceptor
+removeAuth()
+```
+
+### Gestio d'errors
+
+Els errors HTTP (4xx, 5xx) i de xarxa es llancen com a `HttpError`:
+
+```typescript
+try {
+    const { data } = await api.get<Post[]>('/posts')
+} catch (error) {
+    if (error instanceof HttpError) {
+        console.log(error.status)        // 404, 500...
+        console.log(error.isNotFound)    // true si 404
+        console.log(error.isUnauthorized) // true si 401
+        console.log(error.isServerError)  // true si 5xx
+        console.log(error.isTimeout)      // true si timeout
+    }
+}
+```
+
+### Exemple complet
+
+```typescript
+import { HttpClient, HttpError } from 'zs3-ui-components'
+import { $ } from 'zs3-ui-components'
+
+interface Post { id: number; title: string; body: string }
+
+const api = new HttpClient({
+    baseUrl: 'https://jsonplaceholder.typicode.com',
+    timeout: 8_000,
+    retries: 1,
+})
+
+// GET amb parametres de query
+const { data: posts } = await api.get<Post[]>('/posts', { _limit: '5' })
+
+// POST
+const { data: nou, status } = await api.post<Post>('/posts', {
+    title: 'Nou post',
+    body: 'Contingut',
+    userId: 1,
+})
+
+// PATCH (modificacio parcial)
+await api.patch(`/posts/${nou.id}`, { title: 'Titol modificat' })
+
+// DELETE
+await api.delete(`/posts/${nou.id}`)
+
+// Integrat amb ZS3
+$('#btn-load')?.addEvent('click', async () => {
+    try {
+        const { data } = await api.get<Post[]>('/posts', { _limit: '3' })
+        const html = data.map(p => `<li>${p.title}</li>`).join('')
+        $('ul#llista')?.html(html)
+    } catch (e) {
+        if (e instanceof HttpError) $('p#error')?.html(`Error ${e.status}`)
+    }
+})
+```
+
+---
+
 ## Sistema de Temes (ThemeManager)
 
 El sistema de temes permet canviar l'aparenca visual de tota l'aplicacio.
@@ -1932,7 +2077,7 @@ ZS3 suporta handlers d'events inline directament als atributs HTML dels componen
 
 | Variable | Tipus | Descripcio |
 |----------|-------|------------|
-| `$` | `(selector: string, root?: Document \| HTMLElement) => ZS3 \| null` | Funcio de seleccio d'elements. El segon parametre opcional limita la cerca a un element arrel. |
+| `$` | `(selector: string, root?: Document \| HTMLElement \| ShadowRoot) => ZS3 \| null` | Funcio de seleccio d'elements. El segon parametre opcional limita la cerca a un element arrel. |
 | `log` | `$Log` | Sistema de logging. |
 | `debug` | `$Debug` | Utilitat de debugging. |
 | `params` | `$Parameters` | Gestio de parametres d'URL. |

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { $I18n, i18n } from './i18n';
 export type { I18nConfig } from './i18n';
 export { defaultTranslations, DEFAULT_LOCALE, DEFAULT_FALLBACK_LOCALE, } from './i18n/defaults';
 export type { FrameworkTranslations } from './i18n/defaults';
+export { HttpClient, HttpError } from './http';
+export type { HttpMethod, HttpRequestConfig, HttpResponse, HttpClientConfig, RequestInterceptor, ResponseInterceptor, ErrorInterceptor, } from './http';
 export type { EventDescription } from './types';
 export { $BaseComponent } from './components/zs3-BaseComponent';
 export type { BaseComponentOptions, AttributeChangeCallback } from './components/zs3-BaseComponent';