cic-kit 0.0.30 → 0.0.32

package/docs/ContainerSideTabs.md

@@ -0,0 +1,131 @@
+#### ContainerSideTabs
+
+Layout con sidebar tab desktop + menu offcanvas mobile, pensato per cambiare contenuto per sezione.
+
+Componenti collegati:
+- `ContainerSideTabs.vue`: orchestratore (stato tab selezionato, sync route, contenuto)
+- `SideTabs.ts`: tipi (`SideTabComponent`, `SideTabGroup`, `SideTabs`)
+- `SideTabsList.vue`: render lista tab e gruppi
+- `SideTabCmp.vue`: singolo item tab cliccabile
+
+| prop | default | type | utilizzo |
+| --- | --- | --- | --- |
+| `tabs` | `-` | `SideTabs` | lista tab o gruppi (obbligatoria) |
+| `modelValue` | `""` | `string` | nome tab attivo (`v-model`) |
+| `color` | `-` | `string` | colore icona tab attivo |
+| `hoverBgOpacity` | `5` | `number` | opacita hover/active background con `color-mix` |
+| `contentClass` | `"px-3"` | `string` | classi area contenuto |
+| `scrollToTopOnSelect` | `true` | `boolean` | scroll top area contenuto al cambio tab |
+| `scrollToTopSmooth` | `true` | `boolean` | scroll top smooth o instant |
+| `trackRoute` | `true` | `boolean` | sincronizza tab con query route |
+| `routeQueryKey` | `"tab"` | `string` | chiave query usata per tab (`?tab=...`) |
+| `routeUseReplace` | `false` | `boolean` | usa `router.replace` invece di `push` |
+| `sidebarMinWidth` | `-` | `number` | larghezza minima sidebar desktop (px) |
+
+| evento | payload | quando |
+| --- | --- | --- |
+| `update:modelValue` | `string` | quando selezioni tab o cambia query route |
+| `select` | `SideTabComponent` | quando utente seleziona un tab |
+
+### Tipi (`SideTabs.ts`)
+
+```ts
+export interface SideTabComponent {
+  name: string;
+  icon?: string;
+  label?: string | Component;
+  component?: Component;
+}
+
+export interface SideTabGroup {
+  icon?: string;
+  label: string | Component;
+  subTabs: SideTabComponent[];
+}
+
+export type SideTabs = (SideTabGroup | SideTabComponent)[];
+```
+
+Regole pratiche:
+- `name` deve essere univoco in tutta la struttura
+- se un tab non ha `component`, il container mostra fallback "Nessun componente disponibile"
+- puoi usare `label` stringa o componente Vue custom
+
+### Come funziona internamente
+
+- Desktop (`lg+`): sidebar fissa con `SideTabsList`
+- Mobile (`<lg`): bottone menu + `Offcanvas` con la stessa lista tab
+- Se `trackRoute = true`, legge `route.query[routeQueryKey]` e aggiorna `modelValue`
+- Quando selezioni tab aggiorna query con `push` o `replace`
+- Dopo selezione, se attivo, fa scroll top del contenuto interno
+
+### Uso consigliato con file dedicato (tabs config)
+
+#### 1) Crea file config tab
+
+`src/defaultViews/settings/settingsTabs.ts`
+
+```ts
+import type { SideTabs } from "cic-kit";
+import GeneralTab from "./tabs/GeneralTab.vue";
+import SecurityTab from "./tabs/SecurityTab.vue";
+import ProfileTab from "./tabs/ProfileTab.vue";
+
+export const settingsTabs: SideTabs = [
+  {
+    icon: "settings",
+    label: "Impostazioni",
+    subTabs: [
+      { name: "general", label: "Generali", icon: "tune", component: GeneralTab },
+      { name: "security", label: "Sicurezza", icon: "lock", component: SecurityTab },
+    ],
+  },
+  { name: "profile", label: "Profilo", icon: "person", component: ProfileTab },
+];
+```
+
+#### 2) Usalo nella view
+
+`src/defaultViews/settings/SettingsView.vue`
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ContainerSideTabs } from "cic-kit";
+import { settingsTabs } from "./settingsTabs";
+
+const activeTab = ref("general");
+</script>
+
+<template>
+  <ContainerSideTabs
+    v-model="activeTab"
+    :tabs="settingsTabs"
+    color="#0ea5e9"
+    :sidebar-min-width="260"
+    route-query-key="section"
+  />
+</template>
+```
+
+Con `trackRoute=true` (default) l'URL diventa, ad esempio:
+- `...?section=general`
+- `...?section=security`
+
+### Uso con slot (contenuto custom)
+
+Se passi lo slot di default, gestisci tu il contenuto e il render automatico `selectedTab.component` non viene usato.
+
+```vue
+<ContainerSideTabs v-model="activeTab" :tabs="settingsTabs">
+  <div v-if="activeTab === 'general'">...</div>
+  <div v-else-if="activeTab === 'security'">...</div>
+</ContainerSideTabs>
+```
+
+### Note utili
+
+- Se `modelValue` e vuoto e non c'e query valida, nessun tab e selezionato.
+- Per apertura diretta da URL, usa query coerente col `name` del tab.
+- Se non vuoi sporcare history browser ad ogni click tab, imposta `routeUseReplace`.
+- Per disattivare del tutto sync route, imposta `trackRoute=false`.

package/docs/FieldColorTag.md

@@ -0,0 +1,122 @@
+#### FieldColorTag
+
+Campo tag colorati integrato con `vee-validate` (`useField`) e output array via `v-model`.
+
+Tipi principali:
+- `ColorTag`: `{ label: string; color: string }`
+- `OnChangeColorTag`: `"add" | "edit" | "delete"`
+
+| prop | default | type | utilizzo |
+| --- | --- | --- | --- |
+| `name` | `-` | `string` | nome campo `vee-validate` |
+| `modelValue` | `[]` | `ColorTag[]` | valore controllato |
+| `suggestions` | `[]` | `ColorTag[]` | lista suggerimenti filtrabile |
+| `label` | `false` | `string \| boolean \| Component` | etichetta (`true` usa `name`) o componente custom |
+| `placeholder` | `"Aggiungi tag..."` | `string` | placeholder input |
+| `showErrors` | `true` | `boolean` | mostra errore validazione |
+| `allowDuplicates` | `false` | `boolean` | consente tag con stesso `label` |
+| `caseSensitive` | `false` | `boolean` | confronto duplicati/suggerimenti case-sensitive |
+| `maxTags` | `null` | `number \| null` | massimo numero tag inseribili |
+| `defaultColor` | `"#1985a1"` | `string` | colore default per nuovi tag |
+| `class` | `-` | `any` | classi extra wrapper input |
+| `style` | `-` | `any` | style inline wrapper input |
+| `classLabel` | `-` | `any` | classi extra label |
+| `required` | `false` | `boolean` | mostra asterisco nel label |
+
+| evento | payload | quando |
+| --- | --- | --- |
+| `update:modelValue` | `ColorTag[]` | a ogni modifica valore |
+| `change` | `(type: OnChangeColorTag, changedTag: ColorTag, value: ColorTag[])` | add/edit/delete |
+| `add` | `ColorTag` | quando aggiungi un tag |
+| `remove` | `ColorTag` | quando rimuovi un tag |
+| `newSuggestion` | `ColorTag` | quando aggiungi un tag non presente in `suggestions` |
+| `deleteSuggestion` | `ColorTag` | click su elimina suggerimento |
+
+Comportamento valore:
+- normalizza sempre con `toColorTagArray`
+- ogni colore viene validato con `normalizeColorTagColor`
+- se il colore non e valido, usa `COLOR_TAG_DEFAULT_COLOR` (`#1985a1`)
+- confronto duplicati su `label` (trim), con o senza case-sensitive in base a `caseSensitive`
+
+Comportamento input/tastiera:
+- `Enter`, `,`, `Tab`: aggiunge tag corrente (o suggestion evidenziata)
+- `ArrowDown` / `ArrowUp`: naviga suggerimenti
+- `Escape`: chiude dropdown
+- `Backspace` su input vuoto: rimuove ultimo tag
+- `blur`: se c'e testo residuo, prova ad aggiungerlo automaticamente
+
+Suggerimenti:
+- dropdown visibile solo se input in focus, query non vuota e risultati presenti
+- filtro per `includes` sul `label`
+- se `allowDuplicates = false`, esclude suggestion gia presenti
+- il bottone `x` per eliminare suggestion appare solo se ascolti `@deleteSuggestion`
+
+Limite tag:
+- con `maxTags`, oltre soglia blocca nuove aggiunte
+- mostra messaggio: `Hai raggiunto il numero massimo di tag (...)`
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FieldColorTag, type ColorTag } from "cic-kit";
+
+const tags = ref<ColorTag[]>([
+  { label: "Urgente", color: "#ef4444" },
+]);
+</script>
+
+<template>
+  <FieldColorTag
+    name="tags"
+    v-model="tags"
+    label="Tag"
+    placeholder="Scrivi e premi invio..."
+  />
+</template>
+```
+
+Esempio con suggerimenti, deduplica e limite:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FieldColorTag, type ColorTag } from "cic-kit";
+
+const tags = ref<ColorTag[]>([]);
+const suggestions = ref<ColorTag[]>([
+  { label: "Backend", color: "#0ea5e9" },
+  { label: "Frontend", color: "#8b5cf6" },
+  { label: "Bug", color: "#ef4444" },
+]);
+
+function onNewSuggestion(tag: ColorTag) {
+  // opzionale: persisti subito il nuovo suggerimento
+  suggestions.value.push(tag);
+}
+
+function onDeleteSuggestion(tag: ColorTag) {
+  suggestions.value = suggestions.value.filter((s) => s.label !== tag.label);
+}
+</script>
+
+<template>
+  <FieldColorTag
+    name="tags"
+    v-model="tags"
+    :suggestions="suggestions"
+    :allow-duplicates="false"
+    :case-sensitive="false"
+    :max-tags="8"
+    @newSuggestion="onNewSuggestion"
+    @deleteSuggestion="onDeleteSuggestion"
+  />
+</template>
+```
+
+Utility collegate (export da `cic-kit`):
+- `toColorTag(value)`
+- `toColorTagArray(value)`
+- `normalizeColorTagColor(value)`
+- `normalizeColorTagLabel(value)`
+- `isSameColorTagArray(a, b)`
+- `COLOR_TAG_DEFAULT_COLOR`

package/docs/FieldTiptap.md

@@ -0,0 +1,59 @@
+#### FieldTiptap
+
+Editor rich-text Tiptap integrato con `vee-validate` (`useField`) e output HTML via `v-model`.
+
+| prop | default | type | utilizzo |
+| --- | --- | --- | --- |
+| `name` | `-` | `string` | nome campo `vee-validate` |
+| `modelValue` | `""` | `string` | contenuto HTML controllato |
+| `label` | `false` | `string \| boolean \| Component` | etichetta (`true` usa `name`) o componente custom |
+| `placeholder` | `"Scrivi qui..."` | `string` | placeholder dell'editor |
+| `toolbarStickyOn` | `false` | `FieldTiptapToolbarSticky` | toolbar sticky: `"top"`, `"bottom"` o disattivata |
+| `showErrors` | `true` | `boolean` | mostra errore validazione |
+| `required` | `false` | `boolean` | mostra asterisco nel label |
+| `class` | `-` | `any` | classi extra sul wrapper |
+| `style` | `-` | `any` | style inline sul wrapper |
+| `classLabel` | `-` | `any` | classi extra sul label |
+
+`FieldTiptapToolbarSticky`:
+- `"top" \| "bottom" \| false`
+
+| evento | payload | quando |
+| --- | --- | --- |
+| `update:modelValue` | `string` | a ogni update dell'editor |
+
+Comportamento valore:
+- il valore e normalizzato con `normalizeTiptapHtml`
+- se vuoto/null, viene convertito in `"<p></p>"`
+
+Toolbar inclusa:
+- blocco: paragrafo, `h1`, `h2`, `h3`
+- stile: bold, italic, inline code
+- liste: puntata, numerata
+- extra: code block, link, undo, redo
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Form } from "vee-validate";
+import { FieldTiptap } from "cic-kit";
+
+const bio = ref("<p>Ciao!</p>");
+</script>
+
+<template>
+  <Form>
+    <FieldTiptap
+      name="bio"
+      v-model="bio"
+      label="Bio"
+      placeholder="Scrivi una breve presentazione..."
+      :toolbar-sticky-on="'top'"
+      required
+    />
+  </Form>
+</template>
+```
+
+Utility collegata:
+- `normalizeTiptapHtml(value)` da `cic-kit`

package/docs/pushMsg.md

@@ -0,0 +1,200 @@
+#### pushMsg (Notifiche Push)
+
+Guida completa per usare le notifiche push nel progetto con `cic-kit`.
+
+`pushMsg` espone tutto il necessario per:
+- chiedere i permessi browser
+- leggere/registrare il token FCM del device
+- inviare notifiche locali
+- inviare notifiche remote tramite Cloud Function
+
+### Prerequisiti obbligatori
+
+1. Firebase inizializzato con Messaging:
+
+```ts
+import { setupFirebase } from "cic-kit";
+import { firebaseConfig, VAPID_PUBLIC_KEY } from "./firebase-config";
+
+setupFirebase(firebaseConfig, VAPID_PUBLIC_KEY);
+```
+
+Nota: in alternativa puoi assegnare manualmente:
+
+```ts
+import { pushMsg } from "cic-kit";
+pushMsg.vapidPublicKey = VAPID_PUBLIC_KEY;
+```
+
+2. Auth inizializzata (serve per salvare il token su `_Auth.user`):
+
+```ts
+import { initAuth, _CurrentUser } from "cic-kit";
+
+const Auth = initAuth(_CurrentUser);
+Auth.checkAuth();
+```
+
+3. Service Worker registrato (fondamentale per FCM token e notifiche background):
+
+```vue
+<script setup lang="ts">
+import { RegisterSW } from "cic-kit";
+import { registerSW } from "virtual:pwa-register";
+</script>
+
+<template>
+  <RegisterSW :registerSW="registerSW" />
+</template>
+```
+
+4. Per invio remoto: Cloud Function `sendUserPush` deployata (chiamata da `pushMsg.sendTo`).
+
+### API disponibile
+
+| elemento | type | cosa fa |
+| --- | --- | --- |
+| `pushMsg.permission` | `NotificationPermission` | stato permesso (`granted`, `default`, `denied`) |
+| `pushMsg.needToAskPermission` | `boolean` | `true` se devi ancora chiedere permesso |
+| `pushMsg.askPermission()` | `() => Promise<NotificationPermission>` | chiede permesso; se granted prova anche a registrare il token |
+| `pushMsg.send(content)` | `(string \| PushMsgContent) => Promise<void>` | invia notifica locale sul device corrente |
+| `pushMsg.sendTo(uid, content)` | `(uid: string, content: string \| PushMsgContent) => Promise<boolean>` | invia notifica remota a un utente (Cloud Function) |
+| `pushMsg.getCurrentFcmToken()` | `() => Promise<string \| null>` | prende token FCM del device |
+| `pushMsg.registerFcmToken()` | `() => Promise<string \| null>` | registra token su utente corrente |
+| `pushMsg.isThisDeviceTokenRegistered()` | `() => Promise<boolean>` | verifica se il token del device e gia su `_Auth.user.fcmTokens` |
+| `pushMsg.removeThisDeviceToken()` | `() => Promise<boolean>` | rimuove token da browser e utente |
+
+### Payload notifica (`PushMsgContent`)
+
+`PushMsgContent` estende `NotificationOptions` e richiede `title`.
+
+```ts
+type PushMsgContent = NotificationOptions & {
+  title: string;
+};
+```
+
+Default automatici applicati internamente:
+- `icon`: `"/img/logo/pwa.png"`
+- `tag`: `default-YYYY-MM-DD`
+- `data.url`: `"/"`
+
+Esempio:
+
+```ts
+{
+  title: "Nuovo ordine",
+  body: "Hai ricevuto un nuovo ordine",
+  icon: "/img/logo/pwa.png",
+  data: { url: "/orders/123" },
+  silent: false
+}
+```
+
+### Flusso consigliato (device corrente)
+
+```ts
+import { pushMsg } from "cic-kit";
+
+await pushMsg.askPermission();
+const token = await pushMsg.registerFcmToken();
+const registered = await pushMsg.isThisDeviceTokenRegistered();
+```
+
+Disattivazione:
+
+```ts
+await pushMsg.removeThisDeviceToken();
+```
+
+### Inviare una notifica locale
+
+```ts
+await pushMsg.send({
+  title: "Notifica locale",
+  body: "Questo e un test sul device corrente",
+  data: { url: "/demo/push" },
+});
+```
+
+Comportamento:
+- se permesso non concesso, `send()` chiama prima `askPermission()`
+- se esiste `ServiceWorkerRegistration`, usa `showNotification(...)`
+- altrimenti fallback a `new Notification(...)`
+
+### Inviare una notifica remota (a un altro utente)
+
+```ts
+const ok = await pushMsg.sendTo("UID_DESTINATARIO", {
+  title: "Notifica remota",
+  body: "Messaggio inviato dal pannello admin",
+  data: { url: "/orders" },
+});
+```
+
+`sendTo` ritorna:
+- `true`: invio richiesto con successo alla Cloud Function
+- `false`: errore (Firebase non init, funzione assente/errore, ecc.)
+
+### Esempio componente completo
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import { _Auth, pushMsg } from "cic-kit";
+
+const token = ref<string | null>(null);
+const registered = ref(false);
+const toUid = ref(_Auth?.uid ?? "");
+
+const permission = computed(() => pushMsg.permission);
+
+async function enableDevice() {
+  await pushMsg.askPermission();
+  token.value = await pushMsg.registerFcmToken();
+  registered.value = await pushMsg.isThisDeviceTokenRegistered();
+}
+
+async function disableDevice() {
+  await pushMsg.removeThisDeviceToken();
+  token.value = await pushMsg.getCurrentFcmToken();
+  registered.value = await pushMsg.isThisDeviceTokenRegistered();
+}
+
+async function sendRemote() {
+  if (!toUid.value) return;
+  await pushMsg.sendTo(toUid.value, {
+    title: "Test push",
+    body: "Ciao da cic-kit",
+    data: { url: "/" },
+  });
+}
+</script>
+```
+
+### Errori comuni e soluzione
+
+- `Firebase non inizializzato (...)`
+  - chiama `setupFirebase(...)` prima di usare `pushMsg`
+
+- `ServiceWorker non registrato`
+  - monta `<RegisterSW :registerSW="registerSW" />`
+  - verifica che la registrazione avvenga davvero in produzione/dev
+
+- `vapidPublicKey mancante`
+  - passa la VAPID key a `setupFirebase(config, vapidKey)` o `pushMsg.vapidPublicKey = ...`
+
+- permesso `denied`
+  - il browser non mostrera piu il popup: devi riabilitare dalle impostazioni sito/browser
+
+- `Devi essere loggato per attivare le notifiche su questo dispositivo`
+  - `registerFcmToken()` ha ottenuto il token ma non puo salvarlo in `fcmTokens` senza utente loggato
+
+- `Errore invio notifica` in `sendTo`
+  - controlla Cloud Function `sendUserPush`, permessi IAM/rules e token destinatario presente
+
+### Note importanti
+
+- I metodi con parametro `_legacyCurrentUser` sono mantenuti per compatibilita ma oggi ignorati.
+- Per ricezione in background e click su notifica, il Service Worker deve gestire eventi `push` e `notificationclick`.
+- La persistenza token usa i metodi utente `addFcmToken`, `removeFcmToken`, `hasFcmToken` (gia presenti in `_CurrentUser`).