@llmnative/react 1.32.0 → 1.34.0

package/llms-full.txt

@@ -1,1306 +1,1364 @@
-# @llmnative/react — Riferimento completo
-
-Framework React AI-first per generazione deterministica di UI. Data-driven di default, schema-driven opzionale.
-Versione 1.0.0 — Apache-2.0
-
-```bash
-npm install @llmnative/react
-import '@llmnative/react/dist/index.css'
-```
-
----
-
-## Regole fondamentali
-
-- Tutti gli import da `'@llmnative/react'` — mai da sottodirectory
-- I provider sono iniettati via `<App providers={...}>` — mai importati direttamente nei componenti
-- Usare `useDataProvider()`, `useAuthProvider()`, ecc. nei componenti, non istanze dirette
-- TypeScript strict: no `any` — usare `unknown`, `Record<string, unknown>`, tipi specifici
-- Naming props: `view` (presentazione contenuto), `appearance` (guscio visuale), `layout` (disposizione spaziale), `mode` (comportamento operativo), `variant` (tono semantico), `position` (ancoraggio), `size` (scala)
-
----
-
-## App — Entry point
-
-```tsx
-<App
-  providers={{
-    firebase: {                        // FirebaseConfig — tutte le chiavi flat
-      apiKey, authDomain, databaseURL, projectId,
-      storageBucket, messagingSenderId, appId,
-    },
-    supabase: { url, anonKey },
-    google: { clientId, scope },       // flat — NON { oAuth2: { clientId } }
-    dropbox: { clientId },             // DropboxConfig
-    mock: { data: mockData },
-    ai: {                              // AIConfig — NON una prop separata di <App>
-      openaiApiKey, geminiApiKey, anthropicApiKey,
-      deepSeekApiKey, mistralApiKey, openRouterApiKey,
-      groqApiKey,
-      cloudflare: { apiToken, accountId }, // Cloudflare Workers AI
-    },
-    proxy: { enable: true, route: '/api/proxy' },
-    custom: { data: { myAdapter: new MyDataProvider() } },
-    services: {
-      data:        'dbRealtime',      // DataDriverName
-      storage:     'firestorage',     // StorageDriverName | null
-      auth:        'googleAuth',      // AuthDriverName | null
-      email:       'gmail',           // EmailDriverName | null
-      ai:          'openai',          // AIDriverName | null
-      credentials: 'googleServiceAccount',
-    },
-  }}
-  iconProvider="lucide"              // 'lucide' | 'phosphor' | AppIconProviderConfig
-  themeProvider="default"            // 'default' | 'flat' | 'cyber' | AppThemeProviderConfig
-  menuConfig={menuConfig}
-  importPage={(path) => import(path)}
-  LayoutDefault={MyLayout}           // layout wrapper custom (opzionale)
-  appName="MyApp"                    // nome app (opzionale)
-  i18n={{ locale: 'it', translations: { ... } }}
-  contextProviders={MyContextProvider}
-  errorReportUrl="/api/errors"
-  debug={import.meta.env.DEV}
-/>
-```
-
-### AppThemeProviderConfig
-```ts
-{
-  mode?: 'light' | 'dark' | 'system';
-  theme: string;
-  themes?: Record<string, {
-    preset?: { colors?: ColorScale; radius?: number; font?: string };
-    motion?: MotionRegistry;
-    components?: Record<string, Partial<ThemeComponent>>;
-  }>;
-  themeOverride?: Record<string, Partial<ThemeComponent>>;
-}
-```
-
-Built-in themes: `default`, `flat`, `cyber`, `vscode-dark-modern`, `vscode-light-modern`, `vscode-dark-plus`, `vscode-light-plus`, `tokyo-night`, `tokyo-night-light`.
-The VS Code and Tokyo Night themes are compiled from the original VS Code theme JSON (`scripts/themes/vscode`), filling the keys a theme does not list with VS Code's color registry defaults; each one has both modes (`vscode-dark-*` starts dark, `vscode-light-*` light). Status colors (destructive/success/warning/info) stay the framework's.
-
-`ColorScale` tokens: `background`, `foreground`, `canvas` (page floor behind cards and panels, `bg-canvas`; falls back to `background`), `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info` (each with its `*Foreground`), `border`, `input` (border of form fields), `ring`. A consumer bridging the tokens in its own `@theme inline` adds `--color-canvas: hsl(var(--rf-canvas, var(--rf-background)));`.
-
----
-
-## Provider System
-
-### Matrix completa
-
-| Servizio | Interfaccia | Driver | Config key | Obbligatorio |
-|---|---|---|---|---|
-| data | `DataProviderAdapter` | `mock`, `dbRealtime`, `firestoreDb`, `supabaseDb` | `providers.mock/firebase/supabase` | sì (fallback: mock) |
-| storage | `StorageProviderAdapter` | `firestorage`, `supabaseStorage` | `providers.firebase/supabase` | no |
-| auth | `AuthProviderAdapter` | `googleAuth`, `firebaseAuth`, `supabaseAuth`, `dropboxAuth`, `githubAuth` | `providers.google/firebase/supabase/dropbox/github` | sì (fallback: googleAuth) |
-| email | `EmailProviderAdapter` | `gmail` | `providers.google` | no |
-| ai | `AIProviderAdapter` | `openai`, `gemini`, `anthropic`, `deepseek`, `mistral`, `openrouter`, `opencode`, `cloudflare`, `groq` | `Config.tsx AIConfig` | no |
-| credentials | `CredentialsAdapter` | `googleServiceAccount` | `providers.google.serviceAccount` | no |
-
-### Hooks
-
-```ts
-const data    = useDataProvider()           // DataProviderAdapter | null
-const storage = useStorageProvider()        // StorageProviderAdapter | null
-const auth    = useAuthProvider()           // AuthProviderAdapter | null
-const email   = useEmailProvider()          // EmailProviderAdapter | null
-const ai      = useAIProvider()             // AIProviderAdapter | null
-const creds   = useCredentialsProvider()    // CredentialsAdapter | null
-
-// Named provider (multi-provider setup)
-const supabase = useDataProvider('supabase')
-```
-
-### GitHub (`githubAuth`, sessione sul server dell'app)
-
-GitHub richiede il client secret per scambiare il codice: scambio, token e sessione stanno sul server
-dell'app, il browser vede solo il profilo. Config `providers.github = { sessionUrl: '/api/auth/github' }`,
-driver `auth: 'githubAuth'`; funziona con `AuthButton` (pulsante e `aspect="avatar"`) e
-`useAuthProvider('githubAuth')`. Il server espone sotto `sessionUrl`:
-
-| Rotta | Risposta |
-|---|---|
-| `GET /login?returnTo=<path>[&scope=…]` | redirect a GitHub, poi di nuovo a `<path>` |
-| `GET /me` | `{ login, name, avatarUrl, email }`, 401 senza sessione |
-| `POST /logout` | chiude la sessione |
-
-Lato server, da `@llmnative/react/server`:
-
-```ts
-const oauth = createGitHubOAuth({ clientId, clientSecret, scopes: ['read:org'] })
-oauth.authorizeUrl({ state, redirectUri, codeChallenge })   // PKCE S256
-const { accessToken } = await oauth.exchangeCode({ code, redirectUri, codeVerifier })  // GitHubOAuthError se rifiutato
-await oauth.getUser(accessToken)            // { login, name, avatarUrl, email }
-await oauth.getOrganizations(accessToken)   // [{ login, avatarUrl, role: 'admin' | 'member' }]
-```
-
-### Interfacce principali
-
-```ts
-// DataProviderAdapter
-read(path, options?) / set(path, data) / update(path, data) / remove(path)
-subscribe(path, callback: (records: RecordArray) => void): () => void
-count?(path, where?): Promise<number>
-
-// StorageProviderAdapter
-upload(file, path): Promise<string|undefined>
-getURL(path) / download(path): Promise<Blob|undefined> / delete(path): Promise<boolean>
-
-// AuthProviderAdapter
-signIn(intent?, options?) / signOut() / getUser(): UserProfile|null
-onAuthChange(callback) / getAccessToken(): Promise<string|null>
-```
-
-### Auth sign-in methods
-
-| method | Firebase | Supabase | Google |
-|---|---|---|---|
-| `password` | ✅ | ✅ | — |
-| `anonymous` | ✅ | ✅ | — |
-| `magic_link` | — | ✅ | — |
-| `oauth` (github, apple…) | ✅ | ✅ | — |
-| GIS + scoped token | — | — | ✅ |
-
-```ts
-await auth.signIn({ method: 'password', email: '...', password: '...' })
-await auth.signIn({ method: 'oauth', provider: 'github' })
-// Google: token per API scope
-const token = await auth.getAccessToken('https://www.googleapis.com/auth/gmail.send')
-```
-
-### CredentialsAdapter (Google Service Account)
-```tsx
-// Chiama Google APIs lato browser senza Node.js
-<App providers={{ google: { serviceAccount: { clientEmail, privateKey } }, services: { credentials: 'googleServiceAccount' } }} />
-
-const creds = useCredentialsProvider()
-const token = await creds.getToken('https://www.googleapis.com/auth/solar')
-```
-
-### Provider custom
-```ts
-import { DataProviderAdapter, RecordArray } from '@llmnative/react'
-
-export class RestDataProvider implements DataProviderAdapter {
-  async read(path: string): Promise<unknown> { ... }
-  async set(path: string, data: object): Promise<void> { ... }
-  async update(path: string, data: object): Promise<void> { ... }
-  async remove(path: string): Promise<void> { ... }
-  subscribe(path: string | undefined, callback: (records: RecordArray) => void): () => void {
-    return () => undefined
-  }
-}
-```
-
----
-
-## Grid — CRUD table/gallery
-
-```tsx
-<Grid
-  path="/users"               // DataProvider-backed — oppure records={array} per in-memory
-  columns={[
-    { key: 'name',  label: 'Nome',   sortable: true },
-    { key: 'email', label: 'Email' },
-    { key: 'role',  label: 'Ruolo',  render: ({ value }) => <Badge>{value}</Badge> },
-    { key: 'date',  label: 'Data',   render: 'date' },
-  ]}
-  actions={['add', 'edit', 'delete']}   // oppure Record<string, GridAction>
-  view="table"                          // 'table' | 'gallery'
-  pagination={{ limit: 20 }}
-  groupBy="status"
-  sortable={{ field: 'name', dir: 'asc' }}
-  form={<FormFields />}
-  onSave={async ({ record, action }) => record._key}
-  onComplete={async ({ record, action }) => true}
-  selection={{ mode: 'multiple', onChange: (sel) => {} }}
-  reorderable
-  onReorder={(records, meta) => {}}
-  header={(ctx) => <div>{ctx.title}</div>}
-  footer={(ctx) => <div>{ctx.records.length} records</div>}
-/>
-```
-
-| Prop | Tipo | Note |
-|---|---|---|---|
-| `path` | `string \| "fromUrl"` | Path provider-backed |
-| `records` | `RecordArray` | Dati in memoria (alternativa a path) |
-| `columns` | `GridColumn[]` | `{ key, label, sortable?, render?, className? }` |
-| `actions` | `Array<'add'\|'edit'\|'delete'> \| Record<string, GridAction>` | |
-| `view` | `'table' \| 'gallery'` | |
-| `groupBy` | `string \| string[]` | |
-| `pagination` | `PaginationParams` | `{ limit, page?, maxPageButtons?, align?, sticky? }` |
-| `sortable` | `boolean \| OrderConfig` | |
-| `selection` | `false \| 'single' \| 'multiple' \| GridSelectionConfig` | |
-| `form` | `ReactElement \| ((ctx) => ReactNode)` | Form condiviso per CRUD |
-| `onSave` | `GridMutationSaveHandler` | `async ({ record, action }) => string` |
-| `onDelete` | `GridMutationDeleteHandler` | `async ({ record }) => string` |
-| `onComplete` | `GridAfterActionHandler` | `async ({ record, action }) => boolean` |
-| `onRowClick` | `(record) => void` | |
-| `reorderable` | `boolean` | Abilita drag & drop righe |
-| `onReorder` | `GridReorderHandler` | `(records, meta) => void` |
-| `onLoad` | `(records) => TRecord[]` | Trasforma records dopo il fetch |
-| `editDeepLink` | `boolean` | Sincronizza modal edit con URL |
-| `audit` | `boolean` | Logga mutazioni |
-| `sticky` | `'top' \| 'bottom'` | Header/footer sticky |
-| `wrapperClassName` | `string` | CSS wrapper esterno |
-| `loading` | `boolean` | Stato loading override |
-| `title` | `ReactNode` | Titolo header grid |
-| `before` / `after` | `ReactNode` | Slot prima/dopo il contenuto |
-| `header` / `footer` | `ReactNode \| ((ctx) => ReactNode)` | Header/footer custom |
-| `searchable` | `boolean \| GridSearchConfig` | Search box nell'header default — `{ fields?, placeholder? }` |
-| `filters` | `GridFilterConfig[]` | Checkbox toggle nell'header default, applicati PRIMA di `searchable` — `{ key, label, defaultValue?, predicate(record, value) }` |
-
-**GridAction kind:** `'modal'` (default), `'route'`, `'external'`, `'inline'`, `'delete'`
-
----
-
-## Form — form CRUD con lifecycle
-
-```tsx
-<Form
-  path="/products"
-  appearance="card"           // 'card' | 'empty'
-  showBack
-  defaultValues={{ status: 'draft' }}
-  keyGenerator={() => `prod_${Date.now()}`}
-  onLoad={(data) => { /* side-effect hook, non trasforma */ }}
-  onSave={async ({ record, action }) => { /* return storagePath or undefined */ }}
-  onDelete={async ({ record }) => { /* confirm */ }}
-  onComplete={async ({ action }) => { if (action === 'save') navigate('/products') }}
->
-  <Input name="title" label="Titolo" required />
-  <Input name="price" label="Prezzo" type="number" />
-  <Input name="address.city" label="Città" />      {/* oggetto annidato */}
-  <Repeat name="tags" defaultLength={1}>
-    {(i) => <Input name={`tags.${i}`} label={`Tag ${i+1}`} />}
-  </Repeat>
-</Form>
-```
-
-| Prop | Tipo | Note |
-|---|---|---|---|
-| `path` | `string` | Path provider-backed |
-| `appearance` | `'card' \| 'empty'` | Guscio visuale |
-| `controller` | `FormController` | Controller condiviso per bottoni custom esterni |
-| `showBack` | `boolean` | Pulsante Back nel footer |
-| `defaultValues` | `RecordProps` | Valori iniziali per nuovo record |
-| `keyGenerator` | `(record) => string` | Generatore chiave primaria custom |
-| `draftBucket` | `string` | Bucket stabile che isola la bozza locale; omettilo per disabilitare la persistenza |
-| `noticeAnchorRef` | `React.RefObject<HTMLElement>` | Ancoraggio sticky per notifiche |
-| `showNotice` | `boolean` | Mostra notifiche save/delete (default `true`) |
-| `children` | `ReactNode \| ((fields) => ReactNode) \| (({ record }) => ReactNode)` | Contenuto form |
-| `header` | `ReactNode` | Contenuto header custom |
-| `footer` | `ReactNode` | Contenuto footer custom |
-| `wrapperClassName` | `string` | CSS wrapper esterno |
-| `headerClassName` | `string` | CSS header |
-| `className` | `string` | CSS body form |
-| `footerClassName` | `string` | CSS footer |
-| `log` | `boolean` | Logga ogni modifica su console |
-| `onLoad` | `(record) => void` | Side-effect dopo il caricamento (non trasforma) |
-| `onRecordChange` | `(record) => void` | Cambio campo in tempo reale |
-| `onSave` | `FormSaveHandler` | `async ({ record, prevRecord?, storagePath?, action }) => string \| undefined` |
-| `onDelete` | `FormDeleteHandler` | `async ({ record }) => string \| undefined` |
-| `onComplete` | `FormFinallyHandler` | `async ({ record, action }) => boolean` |
-
-**Form controller** — stato e azioni native del form accessibili da qualsiasi punto della pagina.
-
-Due hook:
-
-| Hook | Dove usarlo | Cosa restituisce |
-|---|---|---|
-| `useFormController(controller?)` | Ovunque (anche fuori dal form) | Crea o si aggancia a un `FormController`. Senza argomenti ne crea uno locale stabile. Con un `controller` esistente ci si aggancia. |
-| `useFormActions()` | Solo dentro `<Form>` (legge dal context) | Restituisce lo stesso `FormController` del form genitore. Lancia errore se usato fuori. |
-
-Esempio — bottone custom fuori dal form:
-```tsx
-const form = useFormController();
-
-<ActionButton disabled={form.saveDisabled} onClick={() => { void form.save(); }} />
-<Form controller={form} draftBucket="workspace/acme" onSave={...} />
-```
-
-Esempio — uso dentro il form (senza passare controller):
-```tsx
-function MySaveButton() {
-  const form = useFormActions();
-  return <LoadingButton disabled={form.saveDisabled} loading={form.isSaving} onClick={form.save} />;
-}
-```
-
-Stato esposto dal controller: `record`, `isNewRecord`, `isDirty`, `canSave`, `canDelete`, `isSaving`, `isDeleting`, `saveDisabled`, `deleteDisabled`, `hasDraft`, `draftStatus`, `errors`, `hasErrors`.
-
-Azioni: `save()`, `delete()`, `reset()`, `restoreDraft()`, `discardDraft()`.
-
----
-
-## Campi form
-
-### Input
-```tsx
-<Input name="x" label="..." required />                          // text (default)
-<Input name="price" type="number" min={0} max={100} step={0.01} />
-<Input name="email" type="email" />
-<Input name="pwd"   type="password" />
-<Input name="date"  type="date" />
-<Input name="color" type="color" />
-<TextArea name="bio" minHeight={96} />
-<Checkbox name="active" valueChecked="yes" />
-```
-`Input` props: `name`(req) `label` `type` `required` `disabled` `placeholder` `min` `max` `step` `validator:(v)=>string|undefined`
-`type`: `'text' | 'number' | 'email' | 'password' | 'color' | 'date' | 'time' | 'datetime-local' | 'week' | 'month' | 'range' | 'checkbox' | 'radio' | 'url'`
-
-**NOTA**: il tipo HTML si passa con `type`. `inputType` e i sotto-componenti `Input.Number`/`Input.Email`/`Input.Date` non esistono.
-
-**Label come nodo**: `label` di tutti i campi di inserimento (`Input`, `TextArea`, `Checkbox`, `Select`, `Autocomplete`, `Checklist`, `Upload*`, `ImageField`, `CodeEditor`, `RichText`, `AddressAutocomplete`, `UploadCSV`, `Prompt`) accetta una stringa o un nodo React (tipo `FieldLabel`), disegnato dentro la `<label>` prima dell'asterisco di obbligatorio. Dove serve un testo (messaggio "obbligatorio", `aria-label`) si usa il testo del nodo, ricavabile anche con `labelText(node)`.
-```tsx
-<Select name="skill" required options={skills} label={<>Skill <ActionButton icon="info" ariaLabel="Apri la skill" variant="link" onClick={openSkill} /></>} />
-```
-
-### Select / Autocomplete / Checklist
-```tsx
-<Select name="role" options={[{ label: 'Admin', value: 'admin' }]} />
-<Select name="categoryId" optionsSource={{ path: '/categories', labelField: 'name', valueField: '_key' }} />
-<Autocomplete name="userId" optionsSource={{ path: '/users', labelField: 'email' }} maxItems={1} />
-<Checklist name="tags" options={['a', 'b', 'c']} />
-```
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `options` | `Option[] \| string[] \| number[]` | |
-| `optionsSource` | `{ path, labelField, valueField?, where?, order?, fieldMap?, onLoad? }` | Carica da provider |
-| `order` | `{ field: 'label' \| 'value', dir: 'asc' \| 'desc' }` | |
-| `placeholderOption` | `Option` | Solo Select |
-| `placeholder` | `string` | Solo Autocomplete |
-| `creatable` | `boolean` | Solo Autocomplete — crea nuovi valori |
-| `onCreate` | `(value) => void \| boolean \| Promise<void \| boolean>` | Solo Autocomplete — restituire `false` per non selezionare il valore creato (es. aprire un modulo di creazione) |
-| `listClassName` / `optionClassName` | `string` | Solo Autocomplete — classi della lista e delle voci (anche da tema `Autocomplete.listClassName` / `optionClassName`) |
-| `minItems` / `maxItems` | `number` | Solo Autocomplete |
-| `itemClassName` | `string` | Solo Checklist |
-| `validator` | `(value) => string \| undefined` | Tutte le varianti |
-| `readOnlyAfterSet` | `boolean` | readonly dopo primo valore |
-| `disabled` | `boolean` | |
-| `title` | `string` | |
-| `feedback` | `string` | Messaggio di errore/suggerimento |
-
-`Autocomplete` è una combobox accessibile: la lista (in un portal, larga quanto il campo, stile popover del tema) mostra solo le label e filtra per label/value senza distinzione di maiuscole e accenti; i chip mostrano la label; tastiera: frecce, Invio, Esc (chiude solo la lista, non il `Modal`), Tab, Backspace su campo vuoto rimuove l'ultimo valore. Con `creatable` compare la voce "Crea «testo»". Il valore salvato è sempre l'array dei `value`. `Autocomplete` e `Checklist` sono export nominati: `Select.Autocomplete`/`Select.Checklist` non esistono.
-
-### UploadImage / UploadDocument / UploadCSV
-```tsx
-<UploadImage name="cover" label="Copertina" />    {/* con crop editor */}
-<UploadDocument name="pdf" label="PDF" />
-<UploadCSV name="data" label="Importa CSV" />      {/* con preview tabellare */}
-```
-
-**UploadImageProps** (eredita FormFieldProps):
-| Prop | Tipo | Note |
-|---|---|---|
-| `name` | `string` (required) | |
-| `uploadPath` | `string` | Path storage per upload automatico |
-| `accept` | `string` | MIME types accettati |
-| `editable` | `boolean` | Abilita crop editor |
-| `multiple` | `boolean` | Multipla selezione |
-| `max` | `number` | Numero massimo file |
-| `feedback` | `string` | Testo placeholder drop zone |
-| `srcsetWidths` | `number[]` | Larghezze varianti responsive |
-| `previewHeight` / `previewWidth` | `number` | Dimensioni preview |
-
-**UploadDocumentProps** (eredita FormFieldProps): `name`, `uploadPath`, `accept`, `editable`, `multiple`, `max`
-
-### UploadCSV
-```tsx
-<UploadCSV name="data" label="Importa CSV" />
-```
-| Prop | Tipo |
-|---|---|
-| `name` | `string` (required) |
-| `onDataLoaded` | `(data: UploadCSVData) => void` |
-| `onParseField` | `([key, value]) => [key, value] \| undefined` |
-| `normalizeKeys` | `boolean` |
-| `removeEmptyFields` | `boolean` |
-| `delimiter` | `string` |
-| `label` / `icon` | Opzionali |
-
-### ImageField
-```tsx
-<ImageField
-  name="hero"
-  label="Hero image"
-  defaultValue={{ src: 'https://example.com/hero.jpg', alt: 'Hero shot' }}
-  srcsetWidths={[400, 800]}
-  uploadPath="/content/images"
-/>
-```
-
-Gestisce un oggetto `{ src, alt, srcset?, sizes? }`, preview inline, crop editor e generazione opzionale di varianti responsive.
-
-### CropImage
-```tsx
-<CropImage img={imageObj} title="Ritaglia" scales={{ '1:1': 1, '4:3': 1.33 }} />
-```
-Componente di ritaglio indipendente. `img` ha tipo `{ fileName, variants }` dove ogni variante è `{ fileName, type, scale, top, left, width, height, base64? }`. Usato internamente da `UploadImage` e `ImageField`, ma esportato pubblicamente per uso standalone.
-
-### CodeEditor
-```tsx
-<CodeEditor
-  name="code"
-  label="Template"
-  language="html"
-  placeholder="Scrivi HTML..."
-  minHeight={200}
-  maxHeight={600}
-  disabled={false}
-  required
-  validateSyntax
-  commands={[{ name: 'wrap-section', handler: ({ value }) => `<section>\n${value}\n</section>` }]}
-  commandsTrigger="/"
-/>
-```
-Editor basato su CodeMirror con syntax highlighting e validazione. Linguaggi: `liquid`, `html`, `json`, `js`, `ts`, `css`.
-Quando `commands` e presente, `CodeEditor` apre internamente `ContextMenu` sul trigger configurato.
-
-| Prop extra | Tipo |
-|---|---|
-| `language` | `CodeEditorLanguage` |
-| `placeholder` | `string` |
-| `minHeight` / `maxHeight` | `number` |
-| `validateSyntax` | `boolean` |
-| `validator` | `(value) => string \| undefined \| Promise<string \| undefined>` |
-| `extensions` | `unknown[]` |
-
-### RichText
-```tsx
-<RichText
-  name="body"
-  label="Article body"
-  placeholder="Scrivi..."
-  toolbar="fixed"                    // 'fixed' | 'floating' | false
-  toolbarCommands={['bold', 'italic', 'heading1', '|', 'bulletList', 'link']}
-  outputFormat="html"                // 'html' | 'json' | 'text'
-  statusBar={{ tagBreadcrumb: true, wordCount: true }}
-  minHeight={200}
-  maxHeight={800}
-  imageUpload={{ path: '/content/images', srcsetWidths: [400, 800] }}
-  commands={[{ name: 'summary', icon: 'sparkles' }]}
-  commandsTrigger="/"
-/>
-```
-
-| Prop extra | Tipo |
-|---|---|
-| `placeholder` | `string` |
-| `disabled` | `boolean` |
-| `feedback` | `string` |
-| `toolbar` | `'fixed' \| 'floating' \| false` |
-| `toolbarCommands` | `ToolbarCommand[]` |
-| `outputFormat` | `'html' \| 'json' \| 'text'` |
-| `statusBar` | `boolean \| StatusBarConfig` |
-| `minHeight` / `maxHeight` | `number` |
-| `imageUpload` | `RichTextImageUploadConfig` |
-| `documentUpload` | `RichTextDocumentUploadConfig` |
-| `validator` | `(value) => string \| undefined` |
-
-### Repeat — array dinamici
-```tsx
-<Repeat name="items" defaultLength={3} minItems={1} maxItems={10} label="Elementi" layout="vertical" readOnly>
-  {({ index, record, records, remove }) => (
-    <>
-      <Input name={`items.${index}.name`} label="Nome" />
-      <UploadImage name={`items.${index}.photo`} label="Foto" />
-    </>
-  )}
-</Repeat>
-```
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `name` | `string` (required) | |
-| `children` | `ReactNode \| ((args) => ReactNode)` | Render prop con `{ index, record, records, remove }` |
-| `defaultLength` | `number` | Righe iniziali |
-| `minItems` / `maxItems` | `number` | Min/max righe |
-| `layout` | `'vertical' \| 'horizontal' \| 'inline'` | |
-| `label` | `string` | Etichetta gruppo |
-| `labelPosition` | `'top' \| 'bottom'` | |
-| `hideRemoveButton` | `boolean` | Nascondi rimozione |
-| `readOnly` | `boolean` | Sola lettura |
-| `onChange` | `FieldOnChange` | |
-| `onAdd` / `onRemove` | `(records) => void` | Callback aggiunta/rimozione |
-
-### Prompt — campo AI-potenziato
-```tsx
-<Prompt
-  name="summary"
-  mode="run"                  // 'edit' | 'run'
-  onRunPrompt={async (prompt, options) => AI.fetch(prompt)}
-  commands={[{ name: 'translate', icon: 'languages', handler: (v) => `Translate:\n${v}` }]}
-  commandsTrigger="/"         // default automatico quando commands e presente
-  attachments
-  statusItems={['tokensIn', 'tokensOut', 'contextPercent', 'duration']}
-/>
-```
-
-Quando `commands` e presente in `mode="run"`, `Prompt` monta internamente `ContextMenu` sulla textarea del risultato. Il trigger di default e `"/"`; `commandsTrigger` permette di cambiarlo. Il menu diventa searchable automaticamente sopra una soglia interna di comandi.
-
-`renderFallback`: quando l'AI non e configurata, `Prompt` monta un fallback testuale; passa `renderFallback` per personalizzarlo (riceve `{ name, label, required, onChange }`).
-
----
-
-## UI Primitives
-
-### Alert
-```tsx
-<Alert variant="success">Salvato!</Alert>
-<Alert variant="warning" icon placement="fixed" timeout={3000}>Attenzione</Alert>
-```
-`variant`: `'info' | 'success' | 'warning' | 'danger' | 'primary' | 'secondary' | 'light' | 'dark'`
-`appearance`: `'default' | 'text'`
-`placement`: `'inline' | 'fixed'`
-
-### Badge
-```tsx
-<Badge variant="success">Attivo</Badge>
-```
-`variant`: stessi valori di Alert
-
-### Button variants
-```tsx
-<ActionButton variant="primary" label="Salva" icon="save" onClick={handleSave} />
-<LoadingButton variant="primary" label="Invia" onClick={async (e, setMsg) => { await save(); setMsg('Salvato!') }} />
-<BackLink label="Indietro" />
-<GoSite href="https://..." label="Visita" />
-```
-
-**IButton props:** `variant`, `label`, `icon`, `badge`, `disabled`, `ariaLabel`, `title`, `iconClassName`, `onClick`
-**LoadingButton aggiunge:** `loading`, `loadingLabel` — `onClick` riceve `(e, setMessage?) => Promise<unknown>`
-
-### Card
-```tsx
-<Card title="Titolo" header={<Actions />} footer={<Pagination />} loading={isLoading}>
-  {children}
-</Card>
-```
-
-### Modal
-```tsx
-<Modal title="Conferma" size="md" position="center" onClose={() => {}} onSave={handleSave} onDelete={handleDelete} motion="fade" allowFullscreen stackedBehind>
-  {content}
-</Modal>
-<ModalYesNo title="Sicuro?" onClose={() => {}} onYes={async () => true}>Eliminare il record?</ModalYesNo>
-<ModalOk title="Completato!" onClose={() => {}}>Salvato.</ModalOk>
-```
-`size`: `'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'fullscreen'`
-`position`: `'center' | 'top' | 'left' | 'right' | 'bottom'`
-`ModalYesNo` e `ModalOk` sono export separati: `Modal.YesNo` e `Modal.Ok` non esistono.
-Tastiera: Esc chiude il modal in cima alla pila (`closeOnEscape`, default `true`).
-Accessibilità: il dialog ha `role="dialog"`, `aria-modal="true"` (non con `stackedBehind`) e `aria-labelledby` verso `title` (o `header` stringa) — nei test si trova con `getByRole('dialog', { name })`.
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `children` | `ReactNode` (required) | |
-| `title` | `ReactNode` | |
-| `header` / `footer` | `ReactNode \| false` | Custom header/footer |
-| `size` / `position` | Come sopra | |
-| `onClose` | `() => void` | |
-| `onSave` / `onDelete` | `(e) => Promise<boolean>` | |
-| `allowFullscreen` | `boolean` | Toggle fullscreen |
-| `showCancel` | `boolean` | Default `true` |
-| `stackedBehind` | `boolean` | Modale sotto un'altra (stile Google Tag Manager): un velo la scurisce, il suo backdrop resta com'è (quello della modale sopra entra sopra, così la pagina si scurisce di un gradino per modale) e non riceve il puntatore. I pannelli laterali aperti sullo stesso lato si impilano da soli: quello in cima prende la larghezza con cui si è aperto il primo, ognuno sotto è largo il 10% in più di quello sopra (100%, 110%, 121%…), così ne sporge una striscia. Solo la larghezza cambia, con la transizione dello slide, in entrata e in uscita |
-| `closeOnBackdrop` | `boolean` | Default `true` |
-| `closeOnEscape` | `boolean` | Default `true` — solo il modal in cima reagisce |
-| `zIndex` | `number` | |
-| `motion` | `MotionReference` | Preset animazione |
-| Classi CSS header/title/subtitle/body/footer | `string` | |
-
-### Table
-```tsx
-<Table
-  columns={[{ key: 'name', label: 'Nome', sort: true }]}
-  records={records}
-  onRowClick={(record) => {}}
-  selection="multiple"
-  sortable={{ field: 'name', dir: 'asc' }}
-  pagination={{ limit: 20 }}
-  onReorder={(records, meta) => {}}
-  onSelectionChange={(sel) => {}}
-  groupBy="status"
-  renderCell={(record, key, index) => <CustomCell />}
-/>
-```
-
-| Prop | Tipo |
-|---|---|
-| `columns` | `TableHeaderProp[]` |
-| `records` | `RecordArray` |
-| `sortable` | `boolean \| OrderConfig` |
-| `pagination` | `PaginationParams` |
-| `selection` | `'single' \| 'multiple'` |
-| `onRowClick` | `(record) => void` |
-| `onReorder` | `(records, meta) => void` |
-| `onSelectionChange` | `(selection) => void` |
-| `renderCell` | `(record, key, index) => ReactNode` |
-| `groupBy` | `string \| string[]` |
-| `activeKey` | `string \| null` |
-| `selectedKeys` | `string[]` |
-| `header` / `footer` | `ReactNode` |
-| `headerClassName` / `bodyClassName` / `footerClassName` / `scrollClassName` / `selectedClassName` / `heightClassName` | `string` |
-
-### Gallery
-```tsx
-<Gallery
-  records={records}
-  overlays={[{ position: 'topRight', badge: { variant: 'success', children: 'New' } }]}
-  columns={3}
-  gap={2}
-  sortable={{ field: 'name', dir: 'asc' }}
-  pagination={{ limit: 20 }}
-  onRowClick={(record) => {}}
-  onSelectionChange={(sel) => {}}
-  header="Titolo"
-  groupBy="status"
-/>
-```
-
-`position`: `'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'middleLeft' | 'middleRight'`
-
-| Prop | Tipo |
-|---|---|
-| `records` | `GalleryRecord[]` (`{ img?, thumbnail?, name?, width?, height? }`) |
-| `columns` | `1 \| 2 \| 3 \| 4 \| 6` |
-| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` |
-| `overlays` | `GalleryOverlay[]` |
-| `sortable` | `boolean \| OrderConfig` |
-| `pagination` | `PaginationParams` |
-| `onRowClick` | `(record) => void` |
-| `onSelectionChange` | `(selection) => void` |
-| `groupBy` | `string \| string[]` |
-| `selectedKeys` | `string[]` |
-| `header` / `footer` | `ReactNode` |
-| Classi CSS: `headerClassName`, `bodyClassName`, `footerClassName`, `scrollClassName`, `selectedClassName` | `string` |
-
-### Tab
-```tsx
-import { Tab, TabItem } from '@llmnative/react'
-
-<Tab defaultIndex={0} layout="top">
-  <TabItem label="Generale">{content1}</TabItem>
-  <TabItem label="SEO">{content2}</TabItem>
-</Tab>
-```
-`layout`: `'default' | 'top' | 'left' | 'right' | 'bottom'`
-Le schede sono `<TabItem>`, export separato: `Tab.Item` non esiste.
-
-### Image
-```tsx
-<Image src="..." fit="cover" position="center" width={400} height={300} />
-```
-`fit`: `'cover' | 'contain' | 'fill' | 'scale-down' | 'none'`
-
-### Pagination (standalone)
-```tsx
-<Pagination records={items} limit={20}>
-  {(pageRecords, offset) => pageRecords.map(r => <Row key={r._key} record={r} />)}
-</Pagination>
-```
-
-### Percentage
-```tsx
-<Percentage value={75} appearance="bar" variant="success" showText />
-<Percentage value={0.75} appearance="circle" size={60} />
-```
-
-| Prop | Tipo | Default |
-|---|---|---|
-| `value` | `number` | — |
-| `max` | `number` | `100` |
-| `min` | `number` | — |
-| `appearance` | `'bar' \| 'circle'` | `'bar'` |
-| `variant` | `ColorType` | — |
-| `trackVariant` | `ColorType` | — |
-| `thickness` | `number` | — (px) |
-| `showText` | `boolean` | — |
-| `size` | `number` | Diametro in modalità `'circle'` (px) |
-| `fontSize` | `number` | — |
-| `label` | `string` | — |
-
-### DescriptionList
-Coppie etichetta → valore in sola lettura (profilo, dati di un record, riepiloghi), rese come `<dl>`/`<dt>`/`<dd>`. Da usare al posto di markup `<dl>` scritto a mano; per dati modificabili usare i campi di `<Form>`, per molti record `<Table>`/`<Grid>`.
-```tsx
-<DescriptionList items={[{ label: 'Email', value: 'a@b.it' }, { label: 'Telefono', value: null }]} />
-<DescriptionList layout="stacked" columns={4} truncate items={[{ label: 'Stato', value: <Badge variant="success">Spedito</Badge> }]} />
-```
-
-| Prop | Tipo | Default |
-|---|---|---|
-| `items` | `DescriptionListItem[]` — `{ key?, label, value?, title? }` | — |
-| `layout` | `'horizontal' \| 'stacked'` | `'horizontal'` (etichette a sinistra, impilate su mobile) |
-| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` (solo `stacked`, dal breakpoint `lg`) |
-| `labelWidth` | `string` (lunghezza CSS) | `'12rem'` (solo `horizontal`) |
-| `emptyValue` | `ReactNode` | `'—'` per `null` / `undefined` / `''` (lo `0` resta) |
-| `truncate` | `boolean` | `false`; un valore testuale diventa il suo `title` |
-| Classi | `wrapperClassName`, `className`, `itemClassName`, `labelClassName`, `valueClassName` | tema `DescriptionList` |
-
-### Tree
-Albero accessibile di nodi (cartelle e file, gerarchie): pattern WAI-ARIA tree, un solo tab stop, frecce per muoversi, → / ← per aprire e chiudere, Invio o Spazio per selezionare. Le cartelle si aprono al click, le foglie si selezionano.
-```tsx
-<Tree nodes={treeFromPaths(paths)} defaultExpanded selectedId={path} onSelect={(node) => setPath(node.id)} ariaLabel="File" />
-<Tree nodes={[{ id: 'a', label: 'Docs', children: [{ id: 'a/1', label: 'README.md', badge: <Badge>new</Badge> }] }]} />
-```
-| Prop | Tipo | Note |
-|---|---|---|
-| `nodes` | `TreeNode[]` — `{ id, label, icon?, badge?, description?, children?, disabled? }` | `id` unico; con `children` è una cartella |
-| `selectedId` + `onSelect` / `defaultSelectedId` | `string \| null` | selezione controllata o no |
-| `expanded` + `onExpandedChange` / `defaultExpanded` | `string[]`; `defaultExpanded` anche `true` (tutto aperto) | apertura controllata o no |
-| `selectableBranches` | `boolean` (default `false`) | anche le cartelle si selezionano |
-| `ariaLabel` | `string` | nome accessibile |
-| Classi | `wrapperClassName`, `className`, `itemClassName`, `selectedClassName` | tema `Tree` |
-
-`treeFromPaths(paths, leaf?)` costruisce l'albero da percorsi `a/b/c`: cartelle prima dei file, ordinati; l'id di un file è il percorso, quello di una cartella `percorso/`; `leaf(path)` decora le foglie (label, icona, descrizione…).
-
-### Dropdown
-```tsx
-<Dropdown trigger={<Icon name="menu" />} position="end">
-  <DropdownItem label="Modifica" icon="edit" onClick={() => {}} />
-  <DropdownItem label="Elimina" icon="trash" variant="danger" />
-  <DropdownDivider />
-  <DropdownHeader label="Azioni rapide" />
-</Dropdown>
-```
-
-Azioni secondarie di una voce (CR-107): `actions` mostra icone in fondo alla riga, al passaggio
-del mouse o al focus (sempre sui dispositivi touch). Non selezionano la voce e lasciano il menu aperto
-salvo `closeOnClick`.
-
-```tsx
-<DropdownItem icon="messages-square" onClick={() => open(chat)}
-  actions={[{ icon: 'archive', label: 'Archivia', onClick: () => archive(chat) }]}>
-  {chat.title}
-</DropdownItem>
-```
-
-Per elenchi caricati dinamicamente usare `AsyncDropdown`: gestisce ricerca con debounce,
-cancellazione delle richieste precedenti tramite `AbortSignal` e stati loading/empty/error.
-
-```tsx
-<AsyncDropdown
-  trigger={<ActionButton label="Select user" />}
-  loadItems={(query, signal) => users.search(query, { signal })}
-  getItemId={user => user.id}
-  renderItem={user => user.name}
-  onSelect={user => setUser(user)}
-  selectedId={user?.id}
-/>
-```
-
-### ContextMenu
-```tsx
-<ContextMenu trigger="/" searchable>
-  <ContextMenu.Heading>Comandi</ContextMenu.Heading>
-  <ContextMenu.Item label="Titolo" value="# " icon="heading" />
-  <ContextMenu.Separator />
-  <ContextMenu.Item label="Bold" value="**bold**" icon="bold" />
-</ContextMenu>
-```
-Funziona su qualsiasi `<textarea>` / `<input>` figlio. Trigger custom (`/`, `@`, `{`), filtro searchable, navigazione tastiera, floating positioning.
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `trigger` | `string` (required) | Es. `"/"`, `"@"`, `"{"` |
-| `searchable` | `boolean` | Filtro testuale |
-| `controlled` | `ContextMenuControlledState` | Stato controllato esterno |
-| `onSelect` | `(item, context) => void` | |
-
-**EditorCommand** (usato da `commands` prop su `RichText`, `CodeEditor`, `Prompt`):
-```ts
-{
-  name: string;
-  description?: string;
-  icon?: string;
-  group?: string;
-  consumeSuffix?: string;
-  handler?: (context: TextCommandContext) => string | Promise<string>;
-}
-```
-
-`consumeSuffix` elimina una chiusura automatica adiacente durante la sostituzione del trigger,
-utile quando un comando cambia famiglia sintattica (per esempio da `{{ ... }}` a `{% ... %}`).
-
-### Altre primitive
-```tsx
-<Icon name="user" size={20} />           // usa provider icone configurato
-<ImageAvatar src="..." title="Mario" alt="Mario" width={40} height={40} />
-<Identicon value="acme/app" size={32} title="acme/app" />   // icona generata dal valore, stile GitHub
-<Loader show={isLoading}>{content}</Loader> // indicatore al posto dei figli finché show è true
-<Loader show>{null}</Loader>             // solo indicatore (es. pagina in caricamento)
-<Code language="tsx">{snippet}</Code>   // syntax highlight
-<GridSystem.Row><GridSystem.Col xs={12} md={6}>...</GridSystem.Col></GridSystem.Row>
-<LocaleSwitcher locales={[{ code: 'it', label: 'Italiano' }]} />
-<ThemeSwitcher />
-<ProviderSwitcher />
-<LayoutBuilder components={...} />
-```
-
----
-
-## Blocks
-
-```tsx
-<Breadcrumbs trail={[{ label: 'Home', href: '/' }, { label: 'Utenti' }]} separator="/" jsonLd />
-<Brand url="/" label="MyApp" logo="/logo.svg" width={120} />
-<Search onQueryChange={(e) => setQ(e.target.value)} />
-<Notifications items={[...]} seeAllUrl="/notifications" onMarkAllRead={() => {}} onItemClick={(item) => markRead(item.id)} />
-<Notifications items={[{ id: 'a', title: 'Fonte senza Action', description: 'crm · sources/notes/a.md', url: '/projects/crm', time: 'ora', icon: 'file', actions: [{ label: "Apri l'Action", icon: 'play', onClick: openAction, variant: 'primary' }] }]} />
-<Carousel images={[...]} />
-<Toolbar items={[...]}>
-  {children}
-</Toolbar>
-<SideNav />
-<ListCard records={records} onRowClick={(r) => {}} />
-```
-
-**Brand:**
-| Prop | Tipo |
-|---|---|
-| `url` | `string` |
-| `label` | `string` |
-| `logo` | `string` |
-| `width` / `height` | `number` |
-| `wrapperClassName` / `className` / `logoClassName` / `labelClassName` | `string` |
-
-**SideNav:**
-| Prop | Tipo |
-|---|---|
-| `items` | `SideNavItemDef[]` (in alternativa a `menuKey`) |
-| `menuKey` | `string` — voci dal menu registrato in `<App>` |
-| `bottomItems` | `SideNavItemDef[]` — voci fissate in fondo, sopra il footer e fuori dalla lista scorrevole (es. Impostazioni) |
-| `header` / `footer` | `ReactNode` |
-| `collapsed` + `onCollapsedChange` / `defaultCollapsed` | `boolean` — compressione controllata o no |
-| `showIcons` / `showCollapseButton` | `boolean` (default `true`) |
-| `embedded` | `boolean` — solo le voci, senza guscio (drawer, pannelli); `bottomItems` seguono le voci principali |
-
-`SideNavItemDef`: `{ path, title?, icon?, group?, end?, badge?, children? }`. La voce attiva ha
-`aria-current="page"`.
-
-```tsx
-<SideNav
-  items={[{ path: '/dashboard', title: 'Dashboard', icon: 'home' }]}
-  bottomItems={[{ path: '/settings', title: 'Impostazioni', icon: 'settings' }]}
-/>
-```
-
-**ImageAvatar:**
-| Prop | Tipo |
-|---|---|
-| `src` | `string` (obbligatoria) |
-| `width` / `height` | `number` |
-| `title` / `alt` | `string` |
-| `fit` | `AvatarFit` |
-| `badge` | `BadgeDescriptor` |
-| `feedback` | `ReactNode` |
-
-**Identicon:** l'icona di un'entità senza immagine (repository, tenant, utente senza foto), come quelle di
-GitHub: griglia 5×5 simmetrica, celle e tinta da un hash di `value`. Lo stesso valore dà sempre la stessa
-icona; niente rete né storage. Default: `rounded-md bg-muted` (tema `Identicon.className`).
-`identiconPattern(value)` restituisce celle e tinta, per chi la disegna altrove.
-| Prop | Tipo |
-|---|---|
-| `value` | `string` (obbligatoria) |
-| `size` | `number` (px, default 40) |
-| `title` | `string`: nome accessibile (`role="img"`); senza, `aria-hidden` |
-| `before` / `after` / `className` / `wrapperClassName` | come le altre primitive |
-
-**Search:**
-| Prop | Tipo |
-|---|---|
-| `onQueryChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` |
-
-**Notifications:**
-| Prop | Tipo |
-|---|---|
-| `items` | `NotificationItem[]` |
-| `badge` | `BadgeProps` |
-| `seeAllUrl` | `string` |
-| `onMarkAllRead` | `() => void` |
-| `onItemClick` | `(item, index) => void` — una voce aperta (es. per segnarla letta); il menu si chiude |
-| `motion` | `MotionReference` |
-
-`NotificationItem`: `{ id?, title, description?, url?, external?, time, icon, read?, actions? }`. `description` è la
-riga sotto il titolo; senza `url` la voce si mostra e basta; con `external` l'`url` è un indirizzo aperto
-in una nuova scheda (`<a target="_blank">`), altrimenti una rotta (`Link`). `actions`
-(`NotificationAction[]`: `{ label, icon?, onClick, variant?: 'primary' | 'default', closeOnClick? }`) sono
-pulsanti sotto la voce: non la aprono, mostrano il caricamento finché la promessa di `onClick` è in corso
-e lasciano il menu aperto salvo `closeOnClick`.
-
-**ListCard:**
-| Prop | Tipo |
-|---|---|
-| `title` / `description` / `meta` | `ReactNode` |
-| `badge` | `ReactNode` |
-| `icon` | `string \| ReactNode` |
-| `trailing` / `footer` / `children` | `ReactNode` |
-| `href` | `string` |
-| `external` / `active` / `disabled` / `dashed` / `compact` | `boolean` |
-| `align` | `'start' \| 'center'` |
-| `onClick` | `(e) => void` |
-| Classi CSS: `titleClassName`, `descriptionClassName`, `metaClassName`, `badgeClassName`, `leadingClassName`, `bodyClassName`, `headerClassName`, `trailingClassName`, `footerClassName` | `string` |
-
-**Dropdown:**
-| Prop | Tipo |
-|---|---|
-| `trigger` | `string \| ReactNode \| DropdownTogglerProps` |
-| `badge` | `BadgeProps` |
-| `header` / `footer` | `ReactNode` |
-| `defaultOpen` / `open` | `boolean` |
-| `onOpenChange` | `(open) => void` |
-| `position` | `'start' \| 'end'` |
-| `placement` | `'auto' \| 'top' \| 'bottom'` |
-| `strategy` | `'fixed' \| 'absolute'` |
-
-// Menu — renderizza una sezione del menuConfig passato ad <App>
-<Menu menuKey="main" />            // 'main' o qualsiasi chiave definita in MenuConfig
-<Menu menuKey="topbar" className="nav flex-row gap-2" />
-// NON usare context= — la prop si chiama menuKey
-
-// AuthButton — login/logout con il provider auth configurato
-<AuthButton />
-```
-
----
-
-## Widgets
-
-### MarkdownReader
-```tsx
-<MarkdownReader
-  content={markdownString}
-  onInternalLinkClick={(href, e) => { e.preventDefault(); navigate(href) }}
-  wrapperClassName="prose"
-/>
-```
-
-### ImageEditor
-```tsx
-<ImageEditor src="..." onSave={(dataUrl) => save(dataUrl)} />
-```
-
-`ImageEditor` e un singolo componente pubblico. La libreria pesante `tui-image-editor` viene importata lazy a runtime dentro il componente, quindi non viene scaricata finche l'editor non viene effettivamente montato.
-
-### TabDynamic
-Tab con lazy loading dei contenuti — gestione dinamica aggiunta/rimozione tab.
-
----
-
-## AI Integration
-
-```ts
-import { useAIProvider, getAIModelCatalog, createAIProviderRegistry } from '@llmnative/react'
-
-// Hooks
-const provider  = useAIProvider()           // provider di default
-const registry  = useAIProviderRegistry()   // tutti i provider AI registrati
-const catalog   = getAIModelCatalog()       // modelli disponibili
-// ogni modello: { id, provider, model, label, pricing? } — pricing in USD per 1M token
-// { input, output, currency: 'USD', source: 'provider' | 'models.dev' }; assente = prezzo
-// non trovato (il modello resta in lista). isFreeAIModel(m) → input e output a 0.
-// Il model picker di Prompt/Chatbot mostra "$in / $out", evidenzia i free, segnala i mancanti,
-// e raggruppa per provider (ChatbotModelOption.group = providerLabel) con header sticky.
-
-// Provider adapter restituito da useAIProvider()
-const text  = await provider.fetch("Scrivi un titolo per: {keyword}", { keyword: "React" })
-const json  = await provider.json("Lista di 5 categorie per blog tech")
-const arr   = await provider.array("5 tag per: machine learning")
-
-// Provider custom
-class MyAIProvider implements AIProviderAdapter {
-  async fetch(prompt: string, options?: AIRequestOptions): Promise<string> { ... }
-  async json<T>(prompt: string, options?: AIRequestOptions): Promise<T> { ... }
-  async array(prompt: string, options?: AIRequestOptions): Promise<string[]> { ... }
-}
-
-// Factory per registri esterni
-const registry = createAIProviderRegistry(definitions)
-// Azioni di Chatbot (CR-107): con `content` aprono un menu; senza, sono pulsanti con `onClick`.
-// <Chatbot actions={[{ key: 'finish', icon: 'git-pull-request', label: 'Concludi', showLabel: true,
-//   disabled: running, onClick: finish }]} … />
-```
-
-### Identità dei modelli indipendente dal provider (CR-103)
-
-```ts
-const index = await loadModelIdentityIndex()          // models.dev, un fetch per sessione
-canonicalModelName('DeepSeek V4.1 Flash (Alibaba Cloud)')   // 'deepseek v4.1 flash'
-index.models['deepseek v4.1 flash']                   // { key, name, family?, providers: { openrouter: [{ id, name }], … } }
-resolveModel(index, 'DeepSeek V4.1 Flash', ['openrouter', 'deepseek'])
-// → { provider: 'openrouter', model: 'deepseek/deepseek-v4.1-flash', ref: 'openrouter/deepseek/deepseek-v4.1-flash' }
-```
-
-Il nome canonico toglie data, Free, Latest e host o regione tra parentesi; una modalità
-("(Thinking)", "(Reasoning)", "(Fast)") resta. Per ogni provider l'id preferito è quello stabile (non
-alias `~`, non free tier, non datato). I provider sono le chiavi di models.dev, le stesse di opencode.
-Puro: anche da `@llmnative/react/server`.
-
-### Chiavi tenute dal server (CR-102)
-
-Per un'app che non mette mai le chiavi dei provider nel browser. Il browser conosce solo quali
-provider sono collegati; il proxy dell'app mette la chiave.
-
-```ts
-// Browser: gli stessi adapter, con un segnaposto dove andrebbe la chiave. Serve il proxy attivo.
-const registry = createServerCredentialAIRegistry(
-  [{ id: 'anthropic' }, { id: 'cloudflare', accountId }, { id: 'openai-compatible', baseUrl }],
-  { scope: companyId },   // lettere, cifre, - e _
-)
-Object.entries(registry).forEach(([id, adapter]) => setProvider('ai', id, adapter))
-
-// Server (Node, nessuna dipendenza da React): nel proxy, prima di inoltrare.
-import { resolveServerCredentials } from '@llmnative/react/server'
-const resolved = await resolveServerCredentials({ url: target, headers },
-  (scope, provider) => keysOf(scope)[provider])   // { id, apiKey, accountId?, baseUrl? } | undefined
-if (!resolved.ok) return reply(resolved.status, resolved.error)   // 404 non collegato, 403 host estraneo
-await fetch(resolved.url, { headers: resolved.headers, ... })
-```
-
-La chiave va solo agli host del provider (`AI_PROVIDER_HOSTS`, il `baseUrl` di openai-compatible,
-l'account di Cloudflare): una destinazione diversa è rifiutata. `createProxyPlugin(route, log,
-lookup)` fa lo stesso nel proxy di sviluppo di Vite. Senza proxy, `proxyFetch` rifiuta di inviare
-un segnaposto. `createAIProviderRegistry` (chiavi nel browser) resta com'è.
-
-Configurazione API key in `Config.tsx`: `geminiApiKey`, `openaiApiKey`, `anthropicApiKey`, `deepSeekApiKey`, `mistralApiKey`, `openRouterApiKey`, `groqApiKey`, `cloudflare: { apiToken, accountId }` (Cloudflare Workers AI: l'account id fa parte dell'URL; discovery via `ai/models/search`, modelli Workers Paid esclusi salvo `includePaidModels`).
-
----
-
-## Theme e icone
-
-```tsx
-const theme = useThemeController()
-theme.applyTheme('flat')     // BuiltInThemeId ('default' | 'flat' | 'cyber' | 'vscode-dark-modern' | …) | custom
-theme.setMode('dark')        // 'light' | 'dark' | 'system'
-
-const icons = useIconController()
-icons.setProvider('phosphor')   // 'lucide' | 'phosphor' | custom
-```
-
----
-
-## Head (SEO)
-
-```ts
-useHead({
-  title: 'Pagina',
-  description: '...',
-  robots: 'noindex',
-  canonical: 'https://...',
-  og: { title: '...', image: '...' }
-})
-```
-
----
-
-## Global state (localStorage)
-
-```ts
-const vars = useGlobalVars()
-getGlobalVars('key')
-setGlobalVars({ key: 'value' })
-removeGlobalVars('key')
-```
-
----
-
-## Hooks completi
-
-| Hook | Ritorna |
-|---|---|
-| `useDataProvider(name?)` | `DataProviderAdapter \| null` |
-| `useStorageProvider(name?)` | `StorageProviderAdapter \| null` |
-| `useAuthProvider(name?)` | `AuthProviderAdapter \| null` |
-| `useEmailProvider(name?)` | `EmailProviderAdapter \| null` |
-| `useAIProvider(name?)` | `AIProviderAdapter \| null` |
-| `useAIProviderRegistry()` | `Record<string, AIProviderAdapter>` |
-| `useCredentialsProvider()` | `CredentialsAdapter \| null` |
-| `useTheme()` | `Theme \| undefined` |
-| `useThemeController()` | `ThemeController` |
-| `useIconController()` | `IconController` |
-| `useAccessToken(clientID, renew?)` | `boolean` | Ottiene token per servizio esterno (true = ok) |
-| `useGlobalVars()` | `Record<string, unknown>` |
-| `useHead()` | `HeadController` |
-| `useDocumentHead()` | `HeadController` |
-| `useAssetsHead(title?)` | `void` |
-| `useLanguageHead(lang?)` | `void` |
-| `useSocialHead(config)` | `void` |
-| `usePaginationHead(config)` | `void` |
-| `usePwaHead(config)` | `void` |
-| `useSchemaOrgHead(config)` | `void` |
-| `useHeadLinks(links)` | `void` |
-| `useProxy()` | `(url, init?) => Promise<Response>` |
-| `useImage()` | `UseImageResult` |
-| `useI18n()` | `I18nController` |
-| `useMenu()` | Menu hook |
-| `useFormController(controller?)` | `FormController` |
-| `useFormActions()` | `FormController` |
-| `useApiProvider(pathname?)` | `ApiProviderAdapter \| null` |
-| `useSetProvider(service, driver?)` | `void` |
-| `useProvider(name)` | `ProviderConfigurationState` |
-| `useProviderSession()` | `ProviderSession` |
-| `useDropBoxConnect(config?)` | `DropBoxConnectResult` |
-| `useEnterMotion(baseStyle?, ref?, fallback?)` | `CSSProperties` |
-| `useMotionState(active, ref?, fallback?, baseStyle?)` | `CSSProperties` |
-| `useMotionEffect(ref?, fallback?)` | `ResolvedMotionEffect` |
-| `usePressMotion(hovered, baseStyle?, ref?, fallback?)` | `{ style, pressHandlers }` |
-| `useIconProvider()` | `IconProvider` |
-
----
-
-## Tipi chiave
-
-```ts
-type RecordProps  = Record<string, FieldValue>
-type FieldValue   = string | number | boolean | null | undefined | Record<string, unknown> | unknown[]
-type RecordArray  = RecordProps[]
-
-type OrderConfig  = { field: string; dir: 'asc' | 'desc' }
-type WhereClause  = { field: string; op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any'; value: unknown }
-
-interface UIProps {
-  before?: React.ReactNode
-  after?: React.ReactNode
-  wrapperClassName?: string
-  className?: string
-}
-
-type UserProfile = { uid?: string; email?: string; displayName?: string; photoURL?: string; [key: string]: unknown }
-```
-
----
-
-## Utilities
-
-```ts
-import { cn, converter, Sanitizer, Order, path, fetchJson, fetchRest, fetchWithRetry } from '@llmnative/react'
-import { getKeywordIdeas, getGoogleTrendsData, getGoogleTrendsRelated } from '@llmnative/react'
-
-cn('base', condition && 'extra', className)     // tailwind-merge classname
-new Sanitizer().sanitize(html)                  // XSS sanitizer (non usare dangerouslySetInnerHTML)
-new Order().order(records, { field: 'name', dir: 'asc' })  // ordina record array
-fetchJson(url, init?)                           // fetch + JSON parse + error handling
-fetchRest(path, init?)                          // fetch REST con auth
-getKeywordIdeas(keyword)                        // Google Ads Keyword Ideas
-getGoogleTrendsData(keyword)                    // Google Trends interest over time
-getGoogleTrendsRelated(keyword)                 // Google Trends related queries
-```
-
----
-
-## Scaffold (npx create)
-
-```bash
-npx @llmnative/react create
-npx @llmnative/react create --yes --provider=mock --template=admin
-```
-
-Flag disponibili: `--name` `--provider=firebase|supabase|mock|custom` `--ai-provider` `--icon-provider` `--theme` `--template=blank|admin|crm|inventory|project`
-
-**5 template disponibili:**
-| Template | Pagine incluse | Uso tipico |
-|---|---|---|
-| `blank` | home | App vuota — massima libertà |
-| `admin` | home, users, roles, settings | Dashboard admin/backoffice |
-| `crm` | home, companies, contacts, deals | CRM |
-| `inventory` | home + gestione inventario | Magazzino |
-| `project` | home + gestione progetti | PM tool |
-
-**Struttura generata in-place nella current directory:**
-```
-src/
-  index.tsx          ← App entry
-  vite-env.d.ts
-  conf/
-    app.ts           ← providers config letta da .env (VITE_PROVIDER, VITE_AI_PROVIDER...)
-    menu.ts          ← MenuConfig con path, title, icon, page (layout opzionale: c'è LayoutDefault)
-  data/
-    mockData.ts      ← dati fake per MockDataProvider
-  layouts/
-    Default.tsx      ← layout wrapper (header + sidebar + main + footer)
-  sections/
-    Header.tsx / Sidebar.tsx / PageHeader.tsx / Footer.tsx   ← solo componenti pubblici (SideNav, AuthButton, ActionButton, Brand, Breadcrumbs)
-  pages/
-    home/HomePage.tsx
-    [altre pagine dal template scelto]
-  styles/
-    globals.css      ← @import '@llmnative/react/dist/index.css' + Tailwind override
-.env                 ← VITE_PROVIDER, VITE_THEME, chiavi API (non committare)
-.env.example         ← stessa struttura, valori vuoti (committare)
-vite.config.ts / tsconfig.json / postcss.config.js / index.html
-```
-
-**Pattern conf/app.ts** (auto-generato, leggere per capire come funziona):
-```ts
-import type { AppProvidersConfig } from '@llmnative/react'
-import { mockData } from '../data/mockData'
-const env = import.meta.env
-
-export const providers: AppProvidersConfig = {
-  mock: { data: mockData },
-  ai: { openaiApiKey: env.VITE_OPENAI_API_KEY ?? '' },  // AI dentro providers, non prop <App>
-  services: { data: 'mock', auth: 'googleAuth' },
-}
-```
-
-Driver per `VITE_PROVIDER`: `firebase` → `firestoreDb` + `firestorage` + `firebaseAuth`; `supabase` → `supabaseDb` + `supabaseStorage` + `supabaseAuth`; `mock` → `mock` + `googleAuth`. `index.tsx` passa `LayoutDefault={Default}` ad `<App>`.
-
----
-
-## Gotchas — pitfall frequenti
-
-| Errore | Causa | Fix |
-|---|---|---|
-| `aiConfig` prop non esiste su `<App>` | La config AI va dentro `providers.ai`, NON come prop separata | `providers={{ ai: { openaiApiKey } }}` |
-| `inputType` o `Input.Number`/`Input.Email` non esistono | Il tipo HTML è la prop `type` | `<Input type="number">`, `<Input type="email">`, `<Input type="date">` |
-| `Menu context=` non esiste | La prop si chiama `menuKey` | `<Menu menuKey="main" />` |
-| `SignInButton` non esiste | Rinominato | `<AuthButton />` |
-| `firebase: { config: ... }` errato | FirebaseConfig è flat | `firebase: { apiKey, authDomain, databaseURL, ... }` |
-| `google: { oAuth2: { clientId } }` errato | GoogleProviderConfig è flat | `google: { clientId, scope }` |
-| `children` su `Grid` | Grid non accetta children | Usa `form={<Fields />}` per il form inline |
-| `recordId` su `Form` | Prop non esiste | La chiave del record viene da URL automaticamente |
-| `MenuConfig` non importabile | Era type interno | Ora esportato: `import type { MenuConfig } from '@llmnative/react'` |
-| `GridCellContext` non importabile | Mancava dall'index | Ora esportato: `import type { GridCellContext } from '@llmnative/react'` |
-
----
-
-## Dove cercare nel codice sorgente
-
-| Cosa | File |
-|---|---|
-| Form | `src/components/widgets/Form.tsx` |
-| Grid | `src/components/widgets/Grid.tsx` |
-| Prompt | `src/components/widgets/Prompt.tsx` |
-| Campi form | `src/components/ui/fields/` |
-| Blocks (Menu, Toolbar, Notifications, Dropdown…) | `src/components/blocks/` |
-| Provider data Firebase (RTDB) | `src/providers/data/firebase.ts` |
-| Provider data Firestore | `src/providers/data/firestore.ts` |
-| Provider data Supabase | `src/providers/data/supabase.ts` |
-| Provider storage Firebase | `src/providers/storage/firebase.ts` |
-| Provider storage Supabase | `src/providers/storage/supabase.ts` |
-| Provider auth Firebase | `src/providers/auth/firebase/FirebaseAuthProvider.ts` |
-| Provider auth Supabase | `src/providers/auth/supabase/` |
-| Provider auth Google | `src/providers/auth/google/` |
-| Provider auth Dropbox | `src/providers/auth/dropbox/` |
-| Provider email Gmail | `src/providers/email/google/GmailEmailProvider.ts` |
-| Provider AI definitions | `src/providers/ai/` |
-| Provider credenziali | `src/providers/credentials/` |
-| Provider session | `src/providers/ProviderSession.ts` |
-| Proxy CORS | `src/providers/proxy.ts` |
-| Motion system | `src/motion.ts` |
-| I18n | `src/I18n.tsx` |
-| Dropbox integration | `src/providers/dropbox/` |
-| Interfaccia DataProvider | `src/providers/data/DataProvider.ts` |
-| Interfaccia StorageProvider | `src/providers/storage/StorageProvider.ts` |
-| Interfaccia AuthProvider | `src/providers/auth/AuthProvider.ts` |
-| Interfaccia EmailProvider | `src/providers/email/EmailProvider.ts` |
-| Interfaccia AIProvider | `src/providers/ai/AIProvider.ts` |
-| Registry provider | `src/providers/manifest.ts` |
-| Config provider | `src/providers/ProviderConfiguration.ts` |
-| SEO / Google Trends | `src/providers/seo/google/` |
-| Sistema tema | `src/Theme.tsx` |
-| Config runtime | `src/Config.tsx` |
-| Tipi TypeScript | `src/types/` |
-| Utilities pure | `src/libs/` |
+# @llmnative/react — Riferimento completo
+
+Framework React AI-first per generazione deterministica di UI. Data-driven di default, schema-driven opzionale.
+Versione 1.0.0 — Apache-2.0
+
+```bash
+npm install @llmnative/react
+import '@llmnative/react/dist/index.css'
+```
+
+---
+
+## Regole fondamentali
+
+- Tutti gli import da `'@llmnative/react'` — mai da sottodirectory
+- I provider sono iniettati via `<App providers={...}>` — mai importati direttamente nei componenti
+- Usare `useDataProvider()`, `useAuthProvider()`, ecc. nei componenti, non istanze dirette
+- TypeScript strict: no `any` — usare `unknown`, `Record<string, unknown>`, tipi specifici
+- Naming props: `view` (presentazione contenuto), `appearance` (guscio visuale), `layout` (disposizione spaziale), `mode` (comportamento operativo), `variant` (tono semantico), `position` (ancoraggio), `size` (scala)
+
+---
+
+## App — Entry point
+
+```tsx
+<App
+  providers={{
+    firebase: {                        // FirebaseConfig — tutte le chiavi flat
+      apiKey, authDomain, databaseURL, projectId,
+      storageBucket, messagingSenderId, appId,
+    },
+    supabase: { url, anonKey },
+    google: { clientId, scope },       // flat — NON { oAuth2: { clientId } }
+    dropbox: { clientId },             // DropboxConfig
+    mock: { data: mockData },
+    ai: {                              // AIConfig — NON una prop separata di <App>
+      openaiApiKey, geminiApiKey, anthropicApiKey,
+      deepSeekApiKey, mistralApiKey, openRouterApiKey,
+      groqApiKey,
+      cloudflare: { apiToken, accountId }, // Cloudflare Workers AI
+    },
+    proxy: { enable: true, route: '/api/proxy' },
+    custom: { data: { myAdapter: new MyDataProvider() } },
+    services: {
+      data:        'dbRealtime',      // DataDriverName
+      storage:     'firestorage',     // StorageDriverName | null
+      auth:        'googleAuth',      // AuthDriverName | null
+      email:       'gmail',           // EmailDriverName | null
+      ai:          'openai',          // AIDriverName | null
+      credentials: 'googleServiceAccount',
+    },
+  }}
+  iconProvider="lucide"              // 'lucide' | 'phosphor' | AppIconProviderConfig
+  themeProvider="default"            // 'default' | 'flat' | 'cyber' | AppThemeProviderConfig
+  menuConfig={menuConfig}
+  importPage={(path) => import(path)}
+  LayoutDefault={MyLayout}           // layout wrapper custom (opzionale)
+  appName="MyApp"                    // nome app (opzionale)
+  i18n={{ locale: 'it', translations: { ... } }}
+  contextProviders={MyContextProvider}
+  errorReportUrl="/api/errors"
+  debug={import.meta.env.DEV}
+/>
+```
+
+### Testi dei componenti (i18n)
+
+I testi fissi dei componenti vengono da `I18nDict` e seguono `i18n.locale` (en, it, de, ru, ar, zh
+inclusi): un testo si cambia con `i18n.translations`, non nel codice. Namespace dei componenti:
+`notifications` (`markAllRead`, `empty`, `emptyHint`), `errorBoundary` (schermata d'errore; fuori da
+`<I18nProvider>`, come l'`ErrorBoundary` radice di `<App>`, resta in inglese), `themeSwitcher`,
+`imageField` (anche i dialoghi immagine di `RichText`), `richText`, `tabDynamic` (`addTab`),
+`breadcrumbs` (`label`, l'`aria-label` del `nav`), `grid` (`tableView`, `galleryView`, `columns`,
+`fields`), `prompt` (anche `Chatbot`: `role`, `language`, `voice`, `style`, `temperature`, `stop`),
+`chat` (`ChatReasoning` e `ChatQuestions`: `reasoning`, `reasoningFor`, `other`, `review`, `submit`, …;
+il codice di `ChatMarkdown` usa `code`).
+
+```tsx
+<App i18n={{ locale: 'it', translations: { it: { notifications: { emptyHint: 'Niente di nuovo' } } } }} />
+```
+
+### AppThemeProviderConfig
+```ts
+{
+  mode?: 'light' | 'dark' | 'system';
+  theme: string;
+  themes?: Record<string, {
+    preset?: { colors?: ColorScale; radius?: number; font?: string };
+    motion?: MotionRegistry;
+    components?: Record<string, Partial<ThemeComponent>>;
+  }>;
+  themeOverride?: Record<string, Partial<ThemeComponent>>;
+}
+```
+
+Built-in themes: `default`, `flat`, `cyber`, `vscode-dark-modern`, `vscode-light-modern`, `vscode-dark-plus`, `vscode-light-plus`, `tokyo-night`, `tokyo-night-light`.
+The VS Code and Tokyo Night themes are compiled from the original VS Code theme JSON (`scripts/themes/vscode`), filling the keys a theme does not list with VS Code's color registry defaults; each one has both modes (`vscode-dark-*` starts dark, `vscode-light-*` light). Status colors (destructive/success/warning/info) stay the framework's.
+
+`ColorScale` tokens: `background`, `foreground`, `canvas` (page floor behind cards and panels, `bg-canvas`; falls back to `background`), `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info` (each with its `*Foreground`), `border`, `input` (border of form fields), `ring`. A consumer bridging the tokens in its own `@theme inline` adds `--color-canvas: hsl(var(--rf-canvas, var(--rf-background)));`.
+
+---
+
+## Provider System
+
+### Matrix completa
+
+| Servizio | Interfaccia | Driver | Config key | Obbligatorio |
+|---|---|---|---|---|
+| data | `DataProviderAdapter` | `mock`, `dbRealtime`, `firestoreDb`, `supabaseDb` | `providers.mock/firebase/supabase` | sì (fallback: mock) |
+| storage | `StorageProviderAdapter` | `firestorage`, `supabaseStorage` | `providers.firebase/supabase` | no |
+| auth | `AuthProviderAdapter` | `googleAuth`, `firebaseAuth`, `supabaseAuth`, `dropboxAuth`, `githubAuth` | `providers.google/firebase/supabase/dropbox/github` | sì (fallback: googleAuth) |
+| email | `EmailProviderAdapter` | `gmail` | `providers.google` | no |
+| ai | `AIProviderAdapter` | `openai`, `gemini`, `anthropic`, `deepseek`, `mistral`, `openrouter`, `opencode`, `cloudflare`, `groq` | `Config.tsx AIConfig` | no |
+| credentials | `CredentialsAdapter` | `googleServiceAccount` | `providers.google.serviceAccount` | no |
+
+### Hooks
+
+```ts
+const data    = useDataProvider()           // DataProviderAdapter | null
+const storage = useStorageProvider()        // StorageProviderAdapter | null
+const auth    = useAuthProvider()           // AuthProviderAdapter | null
+const email   = useEmailProvider()          // EmailProviderAdapter | null
+const ai      = useAIProvider()             // AIProviderAdapter | null
+const creds   = useCredentialsProvider()    // CredentialsAdapter | null
+
+// Named provider (multi-provider setup)
+const supabase = useDataProvider('supabase')
+```
+
+### GitHub (`githubAuth`, sessione sul server dell'app)
+
+GitHub richiede il client secret per scambiare il codice: scambio, token e sessione stanno sul server
+dell'app, il browser vede solo il profilo. Config `providers.github = { sessionUrl: '/api/auth/github' }`,
+driver `auth: 'githubAuth'`; funziona con `AuthButton` (pulsante e `aspect="avatar"`) e
+`useAuthProvider('githubAuth')`. Il server espone sotto `sessionUrl`:
+
+| Rotta | Risposta |
+|---|---|
+| `GET /login?returnTo=<path>[&scope=…]` | redirect a GitHub, poi di nuovo a `<path>` |
+| `GET /me` | `{ login, name, avatarUrl, email }`, 401 senza sessione |
+| `POST /logout` | chiude la sessione |
+
+Lato server, da `@llmnative/react/server`:
+
+```ts
+const oauth = createGitHubOAuth({ clientId, clientSecret, scopes: ['read:org'] })
+oauth.authorizeUrl({ state, redirectUri, codeChallenge })   // PKCE S256
+const { accessToken } = await oauth.exchangeCode({ code, redirectUri, codeVerifier })  // GitHubOAuthError se rifiutato
+await oauth.getUser(accessToken)            // { login, name, avatarUrl, email }
+await oauth.getOrganizations(accessToken)   // [{ login, avatarUrl, role: 'admin' | 'member' }]
+```
+
+### Interfacce principali
+
+```ts
+// DataProviderAdapter
+read(path, options?) / set(path, data) / update(path, data) / remove(path)
+subscribe(path, callback: (records: RecordArray) => void): () => void
+count?(path, where?): Promise<number>
+
+// StorageProviderAdapter
+upload(file, path): Promise<string|undefined>
+getURL(path) / download(path): Promise<Blob|undefined> / delete(path): Promise<boolean>
+
+// AuthProviderAdapter
+signIn(intent?, options?) / signOut() / getUser(): UserProfile|null
+onAuthChange(callback) / getAccessToken(): Promise<string|null>
+```
+
+### Auth sign-in methods
+
+| method | Firebase | Supabase | Google |
+|---|---|---|---|
+| `password` | ✅ | ✅ | — |
+| `anonymous` | ✅ | ✅ | — |
+| `magic_link` | — | ✅ | — |
+| `oauth` (github, apple…) | ✅ | ✅ | — |
+| GIS + scoped token | — | — | ✅ |
+
+```ts
+await auth.signIn({ method: 'password', email: '...', password: '...' })
+await auth.signIn({ method: 'oauth', provider: 'github' })
+// Google: token per API scope
+const token = await auth.getAccessToken('https://www.googleapis.com/auth/gmail.send')
+```
+
+### CredentialsAdapter (Google Service Account)
+```tsx
+// Chiama Google APIs lato browser senza Node.js
+<App providers={{ google: { serviceAccount: { clientEmail, privateKey } }, services: { credentials: 'googleServiceAccount' } }} />
+
+const creds = useCredentialsProvider()
+const token = await creds.getToken('https://www.googleapis.com/auth/solar')
+```
+
+### Provider custom
+```ts
+import { DataProviderAdapter, RecordArray } from '@llmnative/react'
+
+export class RestDataProvider implements DataProviderAdapter {
+  async read(path: string): Promise<unknown> { ... }
+  async set(path: string, data: object): Promise<void> { ... }
+  async update(path: string, data: object): Promise<void> { ... }
+  async remove(path: string): Promise<void> { ... }
+  subscribe(path: string | undefined, callback: (records: RecordArray) => void): () => void {
+    return () => undefined
+  }
+}
+```
+
+---
+
+## Grid — CRUD table/gallery
+
+```tsx
+<Grid
+  path="/users"               // DataProvider-backed — oppure records={array} per in-memory
+  columns={[
+    { key: 'name',  label: 'Nome',   sortable: true },
+    { key: 'email', label: 'Email' },
+    { key: 'role',  label: 'Ruolo',  render: ({ value }) => <Badge>{value}</Badge> },
+    { key: 'date',  label: 'Data',   render: 'date' },
+  ]}
+  actions={['add', 'edit', 'delete']}   // oppure Record<string, GridAction>
+  view="table"                          // 'table' | 'gallery'
+  pagination={{ limit: 20 }}
+  groupBy="status"
+  sortable={{ field: 'name', dir: 'asc' }}
+  form={<FormFields />}
+  onSave={async ({ record, action }) => record._key}
+  onComplete={async ({ record, action }) => true}
+  selection={{ mode: 'multiple', onChange: (sel) => {} }}
+  reorderable
+  onReorder={(records, meta) => {}}
+  header={(ctx) => <div>{ctx.title}</div>}
+  footer={(ctx) => <div>{ctx.records.length} records</div>}
+/>
+```
+
+| Prop | Tipo | Note |
+|---|---|---|---|
+| `path` | `string \| "fromUrl"` | Path provider-backed |
+| `records` | `RecordArray` | Dati in memoria (alternativa a path) |
+| `columns` | `GridColumn[]` | `{ key, label, sortable?, render?, className? }` |
+| `actions` | `Array<'add'\|'edit'\|'delete'> \| Record<string, GridAction>` | |
+| `view` | `'table' \| 'gallery'` | |
+| `groupBy` | `string \| string[]` | |
+| `pagination` | `PaginationParams` | `{ limit, page?, maxPageButtons?, align?, sticky? }` |
+| `sortable` | `boolean \| OrderConfig` | |
+| `selection` | `false \| 'single' \| 'multiple' \| GridSelectionConfig` | |
+| `form` | `ReactElement \| ((ctx) => ReactNode)` | Form condiviso per CRUD |
+| `onSave` | `GridMutationSaveHandler` | `async ({ record, action }) => string` |
+| `onDelete` | `GridMutationDeleteHandler` | `async ({ record }) => string` |
+| `onComplete` | `GridAfterActionHandler` | `async ({ record, action }) => boolean` |
+| `onRowClick` | `(record) => void` | |
+| `reorderable` | `boolean` | Abilita drag & drop righe |
+| `onReorder` | `GridReorderHandler` | `(records, meta) => void` |
+| `onLoad` | `(records) => TRecord[]` | Trasforma records dopo il fetch |
+| `editDeepLink` | `boolean` | Sincronizza modal edit con URL |
+| `audit` | `boolean` | Logga mutazioni |
+| `sticky` | `'top' \| 'bottom'` | Header/footer sticky |
+| `wrapperClassName` | `string` | CSS wrapper esterno |
+| `loading` | `boolean` | Stato loading override |
+| `title` | `ReactNode` | Titolo header grid |
+| `before` / `after` | `ReactNode` | Slot prima/dopo il contenuto |
+| `header` / `footer` | `ReactNode \| ((ctx) => ReactNode)` | Header/footer custom |
+| `searchable` | `boolean \| GridSearchConfig` | Search box nell'header default — `{ fields?, placeholder? }` |
+| `filters` | `GridFilterConfig[]` | Checkbox toggle nell'header default, applicati PRIMA di `searchable` — `{ key, label, defaultValue?, predicate(record, value) }` |
+
+**GridAction kind:** `'modal'` (default), `'route'`, `'external'`, `'inline'`, `'delete'`
+
+---
+
+## Form — form CRUD con lifecycle
+
+```tsx
+<Form
+  path="/products"
+  appearance="card"           // 'card' | 'empty'
+  showBack
+  defaultValues={{ status: 'draft' }}
+  keyGenerator={() => `prod_${Date.now()}`}
+  onLoad={(data) => { /* side-effect hook, non trasforma */ }}
+  onSave={async ({ record, action }) => { /* return storagePath or undefined */ }}
+  onDelete={async ({ record }) => { /* confirm */ }}
+  onComplete={async ({ action }) => { if (action === 'save') navigate('/products') }}
+>
+  <Input name="title" label="Titolo" required />
+  <Input name="price" label="Prezzo" type="number" />
+  <Input name="address.city" label="Città" />      {/* oggetto annidato */}
+  <Repeat name="tags" defaultLength={1}>
+    {(i) => <Input name={`tags.${i}`} label={`Tag ${i+1}`} />}
+  </Repeat>
+</Form>
+```
+
+| Prop | Tipo | Note |
+|---|---|---|---|
+| `path` | `string` | Path provider-backed |
+| `appearance` | `'card' \| 'empty'` | Guscio visuale |
+| `controller` | `FormController` | Controller condiviso per bottoni custom esterni |
+| `showBack` | `boolean` | Pulsante Back nel footer |
+| `defaultValues` | `RecordProps` | Valori iniziali per nuovo record |
+| `keyGenerator` | `(record) => string` | Generatore chiave primaria custom |
+| `draftBucket` | `string` | Bucket stabile che isola la bozza locale; omettilo per disabilitare la persistenza |
+| `noticeAnchorRef` | `React.RefObject<HTMLElement>` | Ancoraggio sticky per notifiche |
+| `showNotice` | `boolean` | Mostra notifiche save/delete (default `true`) |
+| `children` | `ReactNode \| ((fields) => ReactNode) \| (({ record }) => ReactNode)` | Contenuto form |
+| `header` | `ReactNode` | Contenuto header custom |
+| `footer` | `ReactNode` | Contenuto footer custom |
+| `wrapperClassName` | `string` | CSS wrapper esterno |
+| `headerClassName` | `string` | CSS header |
+| `className` | `string` | CSS body form |
+| `footerClassName` | `string` | CSS footer |
+| `log` | `boolean` | Logga ogni modifica su console |
+| `onLoad` | `(record) => void` | Side-effect dopo il caricamento (non trasforma) |
+| `onRecordChange` | `(record) => void` | Cambio campo in tempo reale |
+| `onSave` | `FormSaveHandler` | `async ({ record, prevRecord?, storagePath?, action }) => string \| undefined` |
+| `onDelete` | `FormDeleteHandler` | `async ({ record }) => string \| undefined` |
+| `onComplete` | `FormFinallyHandler` | `async ({ record, action }) => boolean` |
+
+**Form controller** — stato e azioni native del form accessibili da qualsiasi punto della pagina.
+
+Due hook:
+
+| Hook | Dove usarlo | Cosa restituisce |
+|---|---|---|
+| `useFormController(controller?)` | Ovunque (anche fuori dal form) | Crea o si aggancia a un `FormController`. Senza argomenti ne crea uno locale stabile. Con un `controller` esistente ci si aggancia. |
+| `useFormActions()` | Solo dentro `<Form>` (legge dal context) | Restituisce lo stesso `FormController` del form genitore. Lancia errore se usato fuori. |
+
+Esempio — bottone custom fuori dal form:
+```tsx
+const form = useFormController();
+
+<ActionButton disabled={form.saveDisabled} onClick={() => { void form.save(); }} />
+<Form controller={form} draftBucket="workspace/acme" onSave={...} />
+```
+
+Esempio — uso dentro il form (senza passare controller):
+```tsx
+function MySaveButton() {
+  const form = useFormActions();
+  return <LoadingButton disabled={form.saveDisabled} loading={form.isSaving} onClick={form.save} />;
+}
+```
+
+Stato esposto dal controller: `record`, `isNewRecord`, `isDirty`, `canSave`, `canDelete`, `isSaving`, `isDeleting`, `saveDisabled`, `deleteDisabled`, `hasDraft`, `draftStatus`, `errors`, `hasErrors`.
+
+Azioni: `save()`, `delete()`, `reset()`, `restoreDraft()`, `discardDraft()`.
+
+---
+
+## Campi form
+
+### Input
+```tsx
+<Input name="x" label="..." required />                          // text (default)
+<Input name="price" type="number" min={0} max={100} step={0.01} />
+<Input name="email" type="email" />
+<Input name="pwd"   type="password" />
+<Input name="date"  type="date" />
+<Input name="color" type="color" />
+<TextArea name="bio" minHeight={96} />
+<Checkbox name="active" valueChecked="yes" />
+```
+`Input` props: `name`(req) `label` `type` `required` `disabled` `placeholder` `min` `max` `step` `validator:(v)=>string|undefined`
+`type`: `'text' | 'number' | 'email' | 'password' | 'color' | 'date' | 'time' | 'datetime-local' | 'week' | 'month' | 'range' | 'checkbox' | 'radio' | 'url'`
+
+**NOTA**: il tipo HTML si passa con `type`. `inputType` e i sotto-componenti `Input.Number`/`Input.Email`/`Input.Date` non esistono.
+
+**Label come nodo**: `label` di tutti i campi di inserimento (`Input`, `TextArea`, `Checkbox`, `Select`, `Autocomplete`, `Checklist`, `Upload*`, `ImageField`, `CodeEditor`, `RichText`, `AddressAutocomplete`, `UploadCSV`, `Prompt`) accetta una stringa o un nodo React (tipo `FieldLabel`), disegnato dentro la `<label>` prima dell'asterisco di obbligatorio. Dove serve un testo (messaggio "obbligatorio", `aria-label`) si usa il testo del nodo, ricavabile anche con `labelText(node)`.
+```tsx
+<Select name="skill" required options={skills} label={<>Skill <ActionButton icon="info" ariaLabel="Apri la skill" variant="link" onClick={openSkill} /></>} />
+```
+
+### Select / Autocomplete / Checklist
+```tsx
+<Select name="role" options={[{ label: 'Admin', value: 'admin' }]} />
+<Select name="categoryId" optionsSource={{ path: '/categories', labelField: 'name', valueField: '_key' }} />
+<Autocomplete name="userId" optionsSource={{ path: '/users', labelField: 'email' }} maxItems={1} />
+<Checklist name="tags" options={['a', 'b', 'c']} />
+```
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `options` | `Option[] \| string[] \| number[]` | |
+| `optionsSource` | `{ path, labelField, valueField?, where?, order?, fieldMap?, onLoad? }` | Carica da provider |
+| `order` | `{ field: 'label' \| 'value', dir: 'asc' \| 'desc' }` | |
+| `placeholderOption` | `Option` | Solo Select |
+| `placeholder` | `string` | Solo Autocomplete |
+| `creatable` | `boolean` | Solo Autocomplete — crea nuovi valori |
+| `onCreate` | `(value) => void \| boolean \| Promise<void \| boolean>` | Solo Autocomplete — restituire `false` per non selezionare il valore creato (es. aprire un modulo di creazione) |
+| `listClassName` / `optionClassName` | `string` | Solo Autocomplete — classi della lista e delle voci (anche da tema `Autocomplete.listClassName` / `optionClassName`) |
+| `minItems` / `maxItems` | `number` | Solo Autocomplete |
+| `itemClassName` | `string` | Solo Checklist |
+| `validator` | `(value) => string \| undefined` | Tutte le varianti |
+| `readOnlyAfterSet` | `boolean` | readonly dopo primo valore |
+| `disabled` | `boolean` | |
+| `title` | `string` | |
+| `feedback` | `string` | Messaggio di errore/suggerimento |
+
+`Autocomplete` è una combobox accessibile: la lista (in un portal, larga quanto il campo, stile popover del tema) mostra solo le label e filtra per label/value senza distinzione di maiuscole e accenti; i chip mostrano la label; tastiera: frecce, Invio, Esc (chiude solo la lista, non il `Modal`), Tab, Backspace su campo vuoto rimuove l'ultimo valore. Con `creatable` compare la voce "Crea «testo»". Il valore salvato è sempre l'array dei `value`. `Autocomplete` e `Checklist` sono export nominati: `Select.Autocomplete`/`Select.Checklist` non esistono.
+
+### UploadImage / UploadDocument / UploadCSV
+```tsx
+<UploadImage name="cover" label="Copertina" />    {/* con crop editor */}
+<UploadDocument name="pdf" label="PDF" />
+<UploadCSV name="data" label="Importa CSV" />      {/* con preview tabellare */}
+```
+
+**UploadImageProps** (eredita FormFieldProps):
+| Prop | Tipo | Note |
+|---|---|---|
+| `name` | `string` (required) | |
+| `uploadPath` | `string` | Path storage per upload automatico |
+| `accept` | `string` | MIME types accettati |
+| `editable` | `boolean` | Abilita crop editor |
+| `multiple` | `boolean` | Multipla selezione |
+| `max` | `number` | Numero massimo file |
+| `feedback` | `string` | Testo placeholder drop zone |
+| `srcsetWidths` | `number[]` | Larghezze varianti responsive |
+| `previewHeight` / `previewWidth` | `number` | Dimensioni preview |
+
+**UploadDocumentProps** (eredita FormFieldProps): `name`, `uploadPath`, `accept`, `editable`, `multiple`, `max`
+
+### UploadCSV
+```tsx
+<UploadCSV name="data" label="Importa CSV" />
+```
+| Prop | Tipo |
+|---|---|
+| `name` | `string` (required) |
+| `onDataLoaded` | `(data: UploadCSVData) => void` |
+| `onParseField` | `([key, value]) => [key, value] \| undefined` |
+| `normalizeKeys` | `boolean` |
+| `removeEmptyFields` | `boolean` |
+| `delimiter` | `string` |
+| `label` / `icon` | Opzionali |
+
+### ImageField
+```tsx
+<ImageField
+  name="hero"
+  label="Hero image"
+  defaultValue={{ src: 'https://example.com/hero.jpg', alt: 'Hero shot' }}
+  srcsetWidths={[400, 800]}
+  uploadPath="/content/images"
+/>
+```
+
+Gestisce un oggetto `{ src, alt, srcset?, sizes? }`, preview inline, crop editor e generazione opzionale di varianti responsive.
+
+### CropImage
+```tsx
+<CropImage img={imageObj} title="Ritaglia" scales={{ '1:1': 1, '4:3': 1.33 }} />
+```
+Componente di ritaglio indipendente. `img` ha tipo `{ fileName, variants }` dove ogni variante è `{ fileName, type, scale, top, left, width, height, base64? }`. Usato internamente da `UploadImage` e `ImageField`, ma esportato pubblicamente per uso standalone.
+
+### CodeEditor
+```tsx
+<CodeEditor
+  name="code"
+  label="Template"
+  language="html"
+  placeholder="Scrivi HTML..."
+  minHeight={200}
+  maxHeight={600}
+  disabled={false}
+  required
+  validateSyntax
+  commands={[{ name: 'wrap-section', handler: ({ value }) => `<section>\n${value}\n</section>` }]}
+  commandsTrigger="/"
+/>
+```
+Editor basato su CodeMirror con syntax highlighting e validazione. Linguaggi: `liquid`, `html`, `json`, `js`, `ts`, `css`.
+Quando `commands` e presente, `CodeEditor` apre internamente `ContextMenu` sul trigger configurato.
+
+| Prop extra | Tipo |
+|---|---|
+| `language` | `CodeEditorLanguage` |
+| `placeholder` | `string` |
+| `minHeight` / `maxHeight` | `number` |
+| `validateSyntax` | `boolean` |
+| `validator` | `(value) => string \| undefined \| Promise<string \| undefined>` |
+| `extensions` | `unknown[]` |
+
+### RichText
+```tsx
+<RichText
+  name="body"
+  label="Article body"
+  placeholder="Scrivi..."
+  toolbar="fixed"                    // 'fixed' | 'floating' | false
+  toolbarCommands={['bold', 'italic', 'heading1', '|', 'bulletList', 'link']}
+  outputFormat="html"                // 'html' | 'json' | 'text'
+  statusBar={{ tagBreadcrumb: true, wordCount: true }}
+  minHeight={200}
+  maxHeight={800}
+  imageUpload={{ path: '/content/images', srcsetWidths: [400, 800] }}
+  commands={[{ name: 'summary', icon: 'sparkles' }]}
+  commandsTrigger="/"
+/>
+```
+
+| Prop extra | Tipo |
+|---|---|
+| `placeholder` | `string` |
+| `disabled` | `boolean` |
+| `feedback` | `string` |
+| `toolbar` | `'fixed' \| 'floating' \| false` |
+| `toolbarCommands` | `ToolbarCommand[]` |
+| `outputFormat` | `'html' \| 'json' \| 'text'` |
+| `statusBar` | `boolean \| StatusBarConfig` |
+| `minHeight` / `maxHeight` | `number` |
+| `imageUpload` | `RichTextImageUploadConfig` |
+| `documentUpload` | `RichTextDocumentUploadConfig` |
+| `validator` | `(value) => string \| undefined` |
+
+### Repeat — array dinamici
+```tsx
+<Repeat name="items" defaultLength={3} minItems={1} maxItems={10} label="Elementi" layout="vertical" readOnly>
+  {({ index, record, records, remove }) => (
+    <>
+      <Input name={`items.${index}.name`} label="Nome" />
+      <UploadImage name={`items.${index}.photo`} label="Foto" />
+    </>
+  )}
+</Repeat>
+```
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `name` | `string` (required) | |
+| `children` | `ReactNode \| ((args) => ReactNode)` | Render prop con `{ index, record, records, remove }` |
+| `defaultLength` | `number` | Righe iniziali |
+| `minItems` / `maxItems` | `number` | Min/max righe |
+| `layout` | `'vertical' \| 'horizontal' \| 'inline'` | |
+| `label` | `string` | Etichetta gruppo |
+| `labelPosition` | `'top' \| 'bottom'` | |
+| `hideRemoveButton` | `boolean` | Nascondi rimozione |
+| `readOnly` | `boolean` | Sola lettura |
+| `onChange` | `FieldOnChange` | |
+| `onAdd` / `onRemove` | `(records) => void` | Callback aggiunta/rimozione |
+
+### Prompt — campo AI-potenziato
+```tsx
+<Prompt
+  name="summary"
+  mode="run"                  // 'edit' | 'run'
+  onRunPrompt={async (prompt, options) => AI.fetch(prompt)}
+  commands={[{ name: 'translate', icon: 'languages', handler: (v) => `Translate:\n${v}` }]}
+  commandsTrigger="/"         // default automatico quando commands e presente
+  attachments
+  statusItems={['tokensIn', 'tokensOut', 'contextPercent', 'duration']}
+/>
+```
+
+Quando `commands` e presente in `mode="run"`, `Prompt` monta internamente `ContextMenu` sulla textarea del risultato. Il trigger di default e `"/"`; `commandsTrigger` permette di cambiarlo. Il menu diventa searchable automaticamente sopra una soglia interna di comandi.
+
+`renderFallback`: quando l'AI non e configurata, `Prompt` monta un fallback testuale; passa `renderFallback` per personalizzarlo (riceve `{ name, label, required, onChange }`).
+
+---
+
+## UI Primitives
+
+### Alert
+```tsx
+<Alert variant="success">Salvato!</Alert>
+<Alert variant="warning" icon placement="fixed" timeout={3000}>Attenzione</Alert>
+```
+`variant`: `'info' | 'success' | 'warning' | 'danger' | 'primary' | 'secondary' | 'light' | 'dark'`
+`appearance`: `'default' | 'text'`
+`placement`: `'inline' | 'fixed'`
+
+### Badge
+```tsx
+<Badge variant="success">Attivo</Badge>
+```
+`variant`: stessi valori di Alert
+
+### Button variants
+```tsx
+<ActionButton variant="primary" label="Salva" icon="save" onClick={handleSave} />
+<LoadingButton variant="primary" label="Invia" onClick={async (e, setMsg) => { await save(); setMsg('Salvato!') }} />
+<BackLink label="Indietro" />
+<GoSite href="https://..." label="Visita" />
+```
+
+**IButton props:** `variant`, `label`, `icon`, `badge`, `disabled`, `ariaLabel`, `title`, `iconClassName`, `onClick`
+**LoadingButton aggiunge:** `loading`, `loadingLabel` — `onClick` riceve `(e, setMessage?) => Promise<unknown>`
+
+### Card
+```tsx
+<Card title="Titolo" header={<Actions />} footer={<Pagination />} loading={isLoading}>
+  {children}
+</Card>
+```
+
+### Modal
+```tsx
+<Modal title="Conferma" size="md" position="center" onClose={() => {}} onSave={handleSave} onDelete={handleDelete} motion="fade" allowFullscreen stackedBehind>
+  {content}
+</Modal>
+<ModalYesNo title="Sicuro?" onClose={() => {}} onYes={async () => true}>Eliminare il record?</ModalYesNo>
+<ModalOk title="Completato!" onClose={() => {}}>Salvato.</ModalOk>
+```
+`size`: `'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'fullscreen'`
+`position`: `'center' | 'top' | 'left' | 'right' | 'bottom'`
+`ModalYesNo` e `ModalOk` sono export separati: `Modal.YesNo` e `Modal.Ok` non esistono.
+Tastiera: Esc chiude il modal in cima alla pila (`closeOnEscape`, default `true`).
+Accessibilità: il dialog ha `role="dialog"`, `aria-modal="true"` (non con `stackedBehind`) e `aria-labelledby` verso `title` (o `header` stringa) — nei test si trova con `getByRole('dialog', { name })`.
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `children` | `ReactNode` (required) | |
+| `title` | `ReactNode` | |
+| `header` / `footer` | `ReactNode \| false` | Custom header/footer |
+| `size` / `position` | Come sopra | |
+| `onClose` | `() => void` | |
+| `onSave` / `onDelete` | `(e) => Promise<boolean>` | |
+| `allowFullscreen` | `boolean` | Toggle fullscreen |
+| `showCancel` | `boolean` | Default `true` |
+| `stackedBehind` | `boolean` | Modale sotto un'altra (stile Google Tag Manager): un velo la scurisce, il suo backdrop resta com'è (quello della modale sopra entra sopra, così la pagina si scurisce di un gradino per modale) e non riceve il puntatore. I pannelli laterali aperti sullo stesso lato si impilano da soli: quello in cima prende la larghezza con cui si è aperto il primo, ognuno sotto è largo il 10% in più di quello sopra (100%, 110%, 121%…), così ne sporge una striscia. Solo la larghezza cambia, con la transizione dello slide, in entrata e in uscita |
+| `closeOnBackdrop` | `boolean` | Default `true` |
+| `closeOnEscape` | `boolean` | Default `true` — solo il modal in cima reagisce |
+| `zIndex` | `number` | |
+| `motion` | `MotionReference` | Preset animazione |
+| Classi CSS header/title/subtitle/body/footer | `string` | |
+
+### Table
+```tsx
+<Table
+  columns={[{ key: 'name', label: 'Nome', sort: true }]}
+  records={records}
+  onRowClick={(record) => {}}
+  selection="multiple"
+  sortable={{ field: 'name', dir: 'asc' }}
+  pagination={{ limit: 20 }}
+  onReorder={(records, meta) => {}}
+  onSelectionChange={(sel) => {}}
+  groupBy="status"
+  renderCell={(record, key, index) => <CustomCell />}
+/>
+```
+
+| Prop | Tipo |
+|---|---|
+| `columns` | `TableHeaderProp[]` |
+| `records` | `RecordArray` |
+| `sortable` | `boolean \| OrderConfig` |
+| `pagination` | `PaginationParams` |
+| `selection` | `'single' \| 'multiple'` |
+| `onRowClick` | `(record) => void` |
+| `onReorder` | `(records, meta) => void` |
+| `onSelectionChange` | `(selection) => void` |
+| `renderCell` | `(record, key, index) => ReactNode` |
+| `groupBy` | `string \| string[]` |
+| `activeKey` | `string \| null` |
+| `selectedKeys` | `string[]` |
+| `header` / `footer` | `ReactNode` |
+| `headerClassName` / `bodyClassName` / `footerClassName` / `scrollClassName` / `selectedClassName` / `heightClassName` | `string` |
+
+### Gallery
+```tsx
+<Gallery
+  records={records}
+  overlays={[{ position: 'topRight', badge: { variant: 'success', children: 'New' } }]}
+  columns={3}
+  gap={2}
+  sortable={{ field: 'name', dir: 'asc' }}
+  pagination={{ limit: 20 }}
+  onRowClick={(record) => {}}
+  onSelectionChange={(sel) => {}}
+  header="Titolo"
+  groupBy="status"
+/>
+```
+
+`position`: `'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'middleLeft' | 'middleRight'`
+
+| Prop | Tipo |
+|---|---|
+| `records` | `GalleryRecord[]` (`{ img?, thumbnail?, name?, width?, height? }`) |
+| `columns` | `1 \| 2 \| 3 \| 4 \| 6` |
+| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` |
+| `overlays` | `GalleryOverlay[]` |
+| `sortable` | `boolean \| OrderConfig` |
+| `pagination` | `PaginationParams` |
+| `onRowClick` | `(record) => void` |
+| `onSelectionChange` | `(selection) => void` |
+| `groupBy` | `string \| string[]` |
+| `selectedKeys` | `string[]` |
+| `header` / `footer` | `ReactNode` |
+| Classi CSS: `headerClassName`, `bodyClassName`, `footerClassName`, `scrollClassName`, `selectedClassName` | `string` |
+
+### Tab
+```tsx
+import { Tab, TabItem } from '@llmnative/react'
+
+<Tab defaultIndex={0} layout="top">
+  <TabItem label="Generale">{content1}</TabItem>
+  <TabItem label="SEO">{content2}</TabItem>
+</Tab>
+```
+`layout`: `'default' | 'top' | 'left' | 'right' | 'bottom'`
+Le schede sono `<TabItem>`, export separato: `Tab.Item` non esiste.
+
+### Image
+```tsx
+<Image src="..." fit="cover" position="center" width={400} height={300} />
+```
+`fit`: `'cover' | 'contain' | 'fill' | 'scale-down' | 'none'`
+
+### Pagination (standalone)
+```tsx
+<Pagination records={items} limit={20}>
+  {(pageRecords, offset) => pageRecords.map(r => <Row key={r._key} record={r} />)}
+</Pagination>
+```
+
+### Percentage
+```tsx
+<Percentage value={75} appearance="bar" variant="success" showText />
+<Percentage value={0.75} appearance="circle" size={60} />
+```
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `value` | `number` | — |
+| `max` | `number` | `100` |
+| `min` | `number` | — |
+| `appearance` | `'bar' \| 'circle'` | `'bar'` |
+| `variant` | `ColorType` | — |
+| `trackVariant` | `ColorType` | — |
+| `thickness` | `number` | — (px) |
+| `showText` | `boolean` | — |
+| `size` | `number` | Diametro in modalità `'circle'` (px) |
+| `fontSize` | `number` | — |
+| `label` | `string` | — |
+
+### DescriptionList
+Coppie etichetta → valore in sola lettura (profilo, dati di un record, riepiloghi), rese come `<dl>`/`<dt>`/`<dd>`. Da usare al posto di markup `<dl>` scritto a mano; per dati modificabili usare i campi di `<Form>`, per molti record `<Table>`/`<Grid>`.
+```tsx
+<DescriptionList items={[{ label: 'Email', value: 'a@b.it' }, { label: 'Telefono', value: null }]} />
+<DescriptionList layout="stacked" columns={4} truncate items={[{ label: 'Stato', value: <Badge variant="success">Spedito</Badge> }]} />
+```
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `items` | `DescriptionListItem[]` — `{ key?, label, value?, title? }` | — |
+| `layout` | `'horizontal' \| 'stacked'` | `'horizontal'` (etichette a sinistra, impilate su mobile) |
+| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` (solo `stacked`, dal breakpoint `lg`) |
+| `labelWidth` | `string` (lunghezza CSS) | `'12rem'` (solo `horizontal`) |
+| `emptyValue` | `ReactNode` | `'—'` per `null` / `undefined` / `''` (lo `0` resta) |
+| `truncate` | `boolean` | `false`; un valore testuale diventa il suo `title` |
+| Classi | `wrapperClassName`, `className`, `itemClassName`, `labelClassName`, `valueClassName` | tema `DescriptionList` |
+
+### Tree
+Albero accessibile di nodi (cartelle e file, gerarchie): pattern WAI-ARIA tree, un solo tab stop, frecce per muoversi, → / ← per aprire e chiudere, Invio o Spazio per selezionare. Le cartelle si aprono al click, le foglie si selezionano.
+```tsx
+<Tree nodes={treeFromPaths(paths)} defaultExpanded selectedId={path} onSelect={(node) => setPath(node.id)} ariaLabel="File" />
+<Tree nodes={[{ id: 'a', label: 'Docs', children: [{ id: 'a/1', label: 'README.md', badge: <Badge>new</Badge> }] }]} />
+```
+| Prop | Tipo | Note |
+|---|---|---|
+| `nodes` | `TreeNode[]` — `{ id, label, icon?, badge?, description?, children?, disabled? }` | `id` unico; con `children` è una cartella |
+| `selectedId` + `onSelect` / `defaultSelectedId` | `string \| null` | selezione controllata o no |
+| `expanded` + `onExpandedChange` / `defaultExpanded` | `string[]`; `defaultExpanded` anche `true` (tutto aperto) | apertura controllata o no |
+| `selectableBranches` | `boolean` (default `false`) | anche le cartelle si selezionano |
+| `ariaLabel` | `string` | nome accessibile |
+| Classi | `wrapperClassName`, `className`, `itemClassName`, `selectedClassName` | tema `Tree` |
+
+`treeFromPaths(paths, leaf?)` costruisce l'albero da percorsi `a/b/c`: cartelle prima dei file, ordinati; l'id di un file è il percorso, quello di una cartella `percorso/`; `leaf(path)` decora le foglie (label, icona, descrizione…).
+
+### Dropdown
+```tsx
+<Dropdown trigger={<Icon name="menu" />} position="end">
+  <DropdownItem label="Modifica" icon="edit" onClick={() => {}} />
+  <DropdownItem label="Elimina" icon="trash" variant="danger" />
+  <DropdownDivider />
+  <DropdownHeader label="Azioni rapide" />
+</Dropdown>
+```
+
+Azioni secondarie di una voce (CR-107): `actions` mostra icone in fondo alla riga, al passaggio
+del mouse o al focus (sempre sui dispositivi touch). Non selezionano la voce e lasciano il menu aperto
+salvo `closeOnClick`.
+
+```tsx
+<DropdownItem icon="messages-square" onClick={() => open(chat)}
+  actions={[{ icon: 'archive', label: 'Archivia', onClick: () => archive(chat) }]}>
+  {chat.title}
+</DropdownItem>
+```
+
+Per elenchi caricati dinamicamente usare `AsyncDropdown`: gestisce ricerca con debounce,
+cancellazione delle richieste precedenti tramite `AbortSignal` e stati loading/empty/error.
+
+```tsx
+<AsyncDropdown
+  trigger={<ActionButton label="Select user" />}
+  loadItems={(query, signal) => users.search(query, { signal })}
+  getItemId={user => user.id}
+  renderItem={user => user.name}
+  onSelect={user => setUser(user)}
+  selectedId={user?.id}
+/>
+```
+
+### ContextMenu
+```tsx
+<ContextMenu trigger="/" searchable>
+  <ContextMenu.Heading>Comandi</ContextMenu.Heading>
+  <ContextMenu.Item label="Titolo" value="# " icon="heading" />
+  <ContextMenu.Separator />
+  <ContextMenu.Item label="Bold" value="**bold**" icon="bold" />
+</ContextMenu>
+```
+Funziona su qualsiasi `<textarea>` / `<input>` figlio. Trigger custom (`/`, `@`, `{`), filtro searchable, navigazione tastiera, floating positioning.
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `trigger` | `string` (required) | Es. `"/"`, `"@"`, `"{"` |
+| `searchable` | `boolean` | Filtro testuale |
+| `controlled` | `ContextMenuControlledState` | Stato controllato esterno |
+| `onSelect` | `(item, context) => void` | |
+
+**EditorCommand** (usato da `commands` prop su `RichText`, `CodeEditor`, `Prompt`):
+```ts
+{
+  name: string;
+  description?: string;
+  icon?: string;
+  group?: string;
+  consumeSuffix?: string;
+  handler?: (context: TextCommandContext) => string | Promise<string>;
+}
+```
+
+`consumeSuffix` elimina una chiusura automatica adiacente durante la sostituzione del trigger,
+utile quando un comando cambia famiglia sintattica (per esempio da `{{ ... }}` a `{% ... %}`).
+
+### Altre primitive
+```tsx
+<Icon name="user" size={20} />           // usa provider icone configurato
+<ImageAvatar src="..." title="Mario" alt="Mario" width={40} height={40} />
+<Identicon value="acme/app" size={32} title="acme/app" />   // icona generata dal valore, stile GitHub
+<Loader show={isLoading}>{content}</Loader> // indicatore al posto dei figli finché show è true
+<Loader show>{null}</Loader>             // solo indicatore (es. pagina in caricamento)
+<Code language="tsx">{snippet}</Code>   // syntax highlight
+<GridSystem.Row><GridSystem.Col xs={12} md={6}>...</GridSystem.Col></GridSystem.Row>
+<LocaleSwitcher locales={[{ code: 'it', label: 'Italiano' }]} />
+<ThemeSwitcher />
+<ProviderSwitcher />
+<LayoutBuilder components={...} />
+```
+
+---
+
+## Blocks
+
+```tsx
+<Breadcrumbs trail={[{ label: 'Home', href: '/' }, { label: 'Utenti' }]} separator="/" jsonLd />
+<Brand url="/" label="MyApp" logo="/logo.svg" width={120} />
+<Search onQueryChange={(e) => setQ(e.target.value)} />
+<Notifications items={[...]} seeAllUrl="/notifications" onMarkAllRead={() => {}} onItemClick={(item) => markRead(item.id)} />
+<Notifications items={[{ id: 'a', title: 'Fonte senza Action', description: 'crm · sources/notes/a.md', url: '/projects/crm', time: 'ora', icon: 'file', actions: [{ label: "Apri l'Action", icon: 'play', onClick: openAction, variant: 'primary' }] }]} />
+<Carousel images={[...]} />
+<Toolbar items={[...]}>
+  {children}
+</Toolbar>
+<SideNav />
+<ListCard records={records} onRowClick={(r) => {}} />
+```
+
+**Brand:**
+| Prop | Tipo |
+|---|---|
+| `url` | `string` |
+| `label` | `string` |
+| `logo` | `string` |
+| `width` / `height` | `number` |
+| `wrapperClassName` / `className` / `logoClassName` / `labelClassName` | `string` |
+
+**SideNav:**
+| Prop | Tipo |
+|---|---|
+| `items` | `SideNavItemDef[]` (in alternativa a `menuKey`) |
+| `menuKey` | `string` — voci dal menu registrato in `<App>` |
+| `bottomItems` | `SideNavItemDef[]` — voci fissate in fondo, sopra il footer e fuori dalla lista scorrevole (es. Impostazioni) |
+| `header` / `footer` | `ReactNode` |
+| `collapsed` + `onCollapsedChange` / `defaultCollapsed` | `boolean` — compressione controllata o no |
+| `showIcons` / `showCollapseButton` | `boolean` (default `true`) |
+| `embedded` | `boolean` — solo le voci, senza guscio (drawer, pannelli); `bottomItems` seguono le voci principali |
+
+`SideNavItemDef`: `{ path, title?, icon?, group?, end?, badge?, children? }`. La voce attiva ha
+`aria-current="page"`.
+
+```tsx
+<SideNav
+  items={[{ path: '/dashboard', title: 'Dashboard', icon: 'home' }]}
+  bottomItems={[{ path: '/settings', title: 'Impostazioni', icon: 'settings' }]}
+/>
+```
+
+**ImageAvatar:**
+| Prop | Tipo |
+|---|---|
+| `src` | `string` (obbligatoria) |
+| `width` / `height` | `number` |
+| `title` / `alt` | `string` |
+| `fit` | `AvatarFit` |
+| `badge` | `BadgeDescriptor` |
+| `feedback` | `ReactNode` |
+
+**Identicon:** l'icona di un'entità senza immagine (repository, tenant, utente senza foto), come quelle di
+GitHub: griglia 5×5 simmetrica, celle e tinta da un hash di `value`. Lo stesso valore dà sempre la stessa
+icona; niente rete né storage. Default: `rounded-md bg-muted` (tema `Identicon.className`).
+`identiconPattern(value)` restituisce celle e tinta, per chi la disegna altrove.
+| Prop | Tipo |
+|---|---|
+| `value` | `string` (obbligatoria) |
+| `size` | `number` (px, default 40) |
+| `title` | `string`: nome accessibile (`role="img"`); senza, `aria-hidden` |
+| `before` / `after` / `className` / `wrapperClassName` | come le altre primitive |
+
+**Search:**
+| Prop | Tipo |
+|---|---|
+| `onQueryChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` |
+
+**Notifications:**
+| Prop | Tipo |
+|---|---|
+| `items` | `NotificationItem[]` |
+| `badge` | `BadgeProps` |
+| `seeAllUrl` | `string` |
+| `onMarkAllRead` | `() => void` |
+| `onItemClick` | `(item, index) => void` — una voce aperta (es. per segnarla letta); il menu si chiude |
+| `motion` | `MotionReference` |
+
+`NotificationItem`: `{ id?, title, description?, url?, external?, time, icon, read?, actions? }`. `description` è la
+riga sotto il titolo; senza `url` la voce si mostra e basta; con `external` l'`url` è un indirizzo aperto
+in una nuova scheda (`<a target="_blank">`), altrimenti una rotta (`Link`). `actions`
+(`NotificationAction[]`: `{ label, icon?, onClick, variant?: 'primary' | 'default', closeOnClick? }`) sono
+pulsanti sotto la voce: non la aprono, mostrano il caricamento finché la promessa di `onClick` è in corso
+e lasciano il menu aperto salvo `closeOnClick`.
+
+**ListCard:**
+| Prop | Tipo |
+|---|---|
+| `title` / `description` / `meta` | `ReactNode` |
+| `badge` | `ReactNode` |
+| `icon` | `string \| ReactNode` |
+| `trailing` / `footer` / `children` | `ReactNode` |
+| `href` | `string` |
+| `external` / `active` / `disabled` / `dashed` / `compact` | `boolean` |
+| `align` | `'start' \| 'center'` |
+| `onClick` | `(e) => void` |
+| Classi CSS: `titleClassName`, `descriptionClassName`, `metaClassName`, `badgeClassName`, `leadingClassName`, `bodyClassName`, `headerClassName`, `trailingClassName`, `footerClassName` | `string` |
+
+**Dropdown:**
+| Prop | Tipo |
+|---|---|
+| `trigger` | `string \| ReactNode \| DropdownTogglerProps` |
+| `badge` | `BadgeProps` |
+| `header` / `footer` | `ReactNode` |
+| `defaultOpen` / `open` | `boolean` |
+| `onOpenChange` | `(open) => void` |
+| `position` | `'start' \| 'end'` |
+| `placement` | `'auto' \| 'top' \| 'bottom'` |
+| `strategy` | `'fixed' \| 'absolute'` |
+
+// Menu — renderizza una sezione del menuConfig passato ad <App>
+<Menu menuKey="main" />            // 'main' o qualsiasi chiave definita in MenuConfig
+<Menu menuKey="topbar" className="nav flex-row gap-2" />
+// NON usare context= — la prop si chiama menuKey
+
+// AuthButton — login/logout con il provider auth configurato
+<AuthButton />
+```
+
+---
+
+## Widgets
+
+### MarkdownReader
+```tsx
+<MarkdownReader
+  content={markdownString}
+  onInternalLinkClick={(href, e) => { e.preventDefault(); navigate(href) }}
+  wrapperClassName="prose"
+/>
+```
+
+### Messaggi di chat: ChatMarkdown, ChatReasoning, ChatQuestions (CR-109)
+
+Parti di un messaggio di un modello, da comporre nel proprio thread (anche accanto a `Chatbot`).
+
+```tsx
+// Markdown GFM del messaggio: tabelle (scorrono dentro di sé in un pannello stretto), elenchi,
+// titoli, citazioni, task list, codice con evidenziazione (Prism, lazy) e pulsante Copia, link a
+// indirizzi in una nuova scheda (noopener). Sanitizzato: niente HTML grezzo, niente javascript:.
+// streaming: chiude ciò che la fine del testo lascia aperto (fence, intestazione di tabella,
+// **grassetto**, `codice`, link) così il layout non salta mentre arriva. Off per un messaggio finito.
+<ChatMarkdown content={text} streaming={running} onLinkClick={(href) => navigate(href)} />
+// tone="muted", highlight={false}, components (come react-markdown), className,
+// classNames={{ root, paragraph, heading, list, blockquote, tableWrapper, table, th, td, codeBlock, codeHeader, code, inlineCode, link }}
+// repairStreamingMarkdown(text) è la stessa riparazione, pura.
+
+// Ragionamento: chiuso dietro "Ragionamento" / "Ha ragionato per 12 s"; aperto mentre arriva
+// (se l'utente non lo chiude) e richiuso alla fine. Contenuto con ChatMarkdown, tono attenuato.
+<ChatReasoning content={reasoning} streaming={thinking} duration={12} />
+// defaultOpen, open + onOpenChange (controllato), label, icon ('brain'), className, classNames={{ root, trigger, content }}
+
+// Domande interattive (formato dello strumento `question` di opencode / elicitation MCP):
+<ChatQuestions
+  questions={[
+    { id: 'db', header: 'Database', question: 'Quale database?', recommended: 0,
+      options: [{ label: 'Postgres', description: 'Relazionale' }, { label: 'SQLite' }] },
+    { id: 'features', header: 'Funzioni', question: 'Quali funzioni?', multiple: true,
+      options: [{ label: 'Auth' }, { label: 'Ricerca' }] },
+  ]}
+  onSubmit={async (answers) => send(answers)}   // [{ id, header, values: string[] }] in ordine
+/>
+// Una scheda per domanda (header) + Riepilogo e un solo Invia; opzioni numerate 1-2-3 o A-B-C
+// (numbering, altrimenti dedotto da etichette "A) …" / "1. …", che vengono tolte); consigliata
+// (recommended: indice da 0 o etichetta; anche il suffisso "(Recommended)"); multiple; "Altro" con
+// testo libero (allowOther, default true; per domanda `custom`); senza options è a testo libero.
+// Tastiera: numeri (o lettere con A-B-C) scelgono, frecce sinistra/destra tra le schede, su/giù tra
+// le opzioni, Spazio seleziona, Invio prosegue o invia (su una scelta singola prima la sceglie).
+// Ruoli tablist/tab/tabpanel, radiogroup/radio o group/checkbox.
+// Scelta singola: il click sceglie e passa alla domanda dopo. onSubmit che rifiuta lascia il form.
+// answers={[…]} mostra un insieme già risposto (sola lettura); disabled, autoFocus, submitLabel,
+// classNames={{ root, tabs, tab, panel, question, option, optionSelected, footer, summary }}
+```
+
+### ImageEditor
+```tsx
+<ImageEditor src="..." onSave={(dataUrl) => save(dataUrl)} />
+```
+
+`ImageEditor` e un singolo componente pubblico. La libreria pesante `tui-image-editor` viene importata lazy a runtime dentro il componente, quindi non viene scaricata finche l'editor non viene effettivamente montato.
+
+### TabDynamic
+Tab con lazy loading dei contenuti — gestione dinamica aggiunta/rimozione tab.
+
+---
+
+## AI Integration
+
+```ts
+import { useAIProvider, getAIModelCatalog, createAIProviderRegistry } from '@llmnative/react'
+
+// Hooks
+const provider  = useAIProvider()           // provider di default
+const registry  = useAIProviderRegistry()   // tutti i provider AI registrati
+const catalog   = getAIModelCatalog()       // modelli disponibili
+// ogni modello: { id, provider, model, label, pricing? } — pricing in USD per 1M token
+// { input, output, currency: 'USD', source: 'provider' | 'models.dev' }; assente = prezzo
+// non trovato (il modello resta in lista). isFreeAIModel(m) → input e output a 0.
+// Il model picker di Prompt/Chatbot mostra "$in / $out", evidenzia i free, segnala i mancanti,
+// e raggruppa per provider (ChatbotModelOption.group = providerLabel) con header sticky.
+
+// Provider adapter restituito da useAIProvider()
+const text  = await provider.fetch("Scrivi un titolo per: {keyword}", { keyword: "React" })
+const json  = await provider.json("Lista di 5 categorie per blog tech")
+const arr   = await provider.array("5 tag per: machine learning")
+
+// Provider custom
+class MyAIProvider implements AIProviderAdapter {
+  async fetch(prompt: string, options?: AIRequestOptions): Promise<string> { ... }
+  async json<T>(prompt: string, options?: AIRequestOptions): Promise<T> { ... }
+  async array(prompt: string, options?: AIRequestOptions): Promise<string[]> { ... }
+}
+
+// Factory per registri esterni
+const registry = createAIProviderRegistry(definitions)
+// Azioni di Chatbot (CR-107): con `content` aprono un menu; senza, sono pulsanti con `onClick`.
+// <Chatbot actions={[{ key: 'finish', icon: 'git-pull-request', label: 'Concludi', showLabel: true,
+//   disabled: running, onClick: finish }]} … />
+```
+
+### Identità dei modelli indipendente dal provider (CR-103)
+
+```ts
+const index = await loadModelIdentityIndex()          // models.dev, un fetch per sessione
+canonicalModelName('DeepSeek V4.1 Flash (Alibaba Cloud)')   // 'deepseek v4.1 flash'
+index.models['deepseek v4.1 flash']                   // { key, name, family?, providers: { openrouter: [{ id, name }], … } }
+resolveModel(index, 'DeepSeek V4.1 Flash', ['openrouter', 'deepseek'])
+// → { provider: 'openrouter', model: 'deepseek/deepseek-v4.1-flash', ref: 'openrouter/deepseek/deepseek-v4.1-flash' }
+```
+
+Il nome canonico toglie data, Free, Latest e host o regione tra parentesi; una modalità
+("(Thinking)", "(Reasoning)", "(Fast)") resta. Per ogni provider l'id preferito è quello stabile (non
+alias `~`, non free tier, non datato). I provider sono le chiavi di models.dev, le stesse di opencode.
+Puro: anche da `@llmnative/react/server`.
+
+### Chiavi tenute dal server (CR-102)
+
+Per un'app che non mette mai le chiavi dei provider nel browser. Il browser conosce solo quali
+provider sono collegati; il proxy dell'app mette la chiave.
+
+```ts
+// Browser: gli stessi adapter, con un segnaposto dove andrebbe la chiave. Serve il proxy attivo.
+const registry = createServerCredentialAIRegistry(
+  [{ id: 'anthropic' }, { id: 'cloudflare', accountId }, { id: 'openai-compatible', baseUrl }],
+  { scope: companyId },   // lettere, cifre, - e _
+)
+Object.entries(registry).forEach(([id, adapter]) => setProvider('ai', id, adapter))
+
+// Server (Node, nessuna dipendenza da React): nel proxy, prima di inoltrare.
+import { resolveServerCredentials } from '@llmnative/react/server'
+const resolved = await resolveServerCredentials({ url: target, headers },
+  (scope, provider) => keysOf(scope)[provider])   // { id, apiKey, accountId?, baseUrl? } | undefined
+if (!resolved.ok) return reply(resolved.status, resolved.error)   // 404 non collegato, 403 host estraneo
+await fetch(resolved.url, { headers: resolved.headers, ... })
+```
+
+La chiave va solo agli host del provider (`AI_PROVIDER_HOSTS`, il `baseUrl` di openai-compatible,
+l'account di Cloudflare): una destinazione diversa è rifiutata. `createProxyPlugin(route, log,
+lookup)` fa lo stesso nel proxy di sviluppo di Vite. Senza proxy, `proxyFetch` rifiuta di inviare
+un segnaposto. `createAIProviderRegistry` (chiavi nel browser) resta com'è.
+
+Configurazione API key in `Config.tsx`: `geminiApiKey`, `openaiApiKey`, `anthropicApiKey`, `deepSeekApiKey`, `mistralApiKey`, `openRouterApiKey`, `groqApiKey`, `cloudflare: { apiToken, accountId }` (Cloudflare Workers AI: l'account id fa parte dell'URL; discovery via `ai/models/search`, modelli Workers Paid esclusi salvo `includePaidModels`).
+
+---
+
+## Theme e icone
+
+```tsx
+const theme = useThemeController()
+theme.applyTheme('flat')     // BuiltInThemeId ('default' | 'flat' | 'cyber' | 'vscode-dark-modern' | …) | custom
+theme.setMode('dark')        // 'light' | 'dark' | 'system'
+
+const icons = useIconController()
+icons.setProvider('phosphor')   // 'lucide' | 'phosphor' | custom
+```
+
+---
+
+## Head (SEO)
+
+```ts
+useHead({
+  title: 'Pagina',
+  description: '...',
+  robots: 'noindex',
+  canonical: 'https://...',
+  og: { title: '...', image: '...' }
+})
+```
+
+---
+
+## Global state (localStorage)
+
+```ts
+const vars = useGlobalVars()
+getGlobalVars('key')
+setGlobalVars({ key: 'value' })
+removeGlobalVars('key')
+```
+
+---
+
+## Hooks completi
+
+| Hook | Ritorna |
+|---|---|
+| `useDataProvider(name?)` | `DataProviderAdapter \| null` |
+| `useStorageProvider(name?)` | `StorageProviderAdapter \| null` |
+| `useAuthProvider(name?)` | `AuthProviderAdapter \| null` |
+| `useEmailProvider(name?)` | `EmailProviderAdapter \| null` |
+| `useAIProvider(name?)` | `AIProviderAdapter \| null` |
+| `useAIProviderRegistry()` | `Record<string, AIProviderAdapter>` |
+| `useCredentialsProvider()` | `CredentialsAdapter \| null` |
+| `useTheme()` | `Theme \| undefined` |
+| `useThemeController()` | `ThemeController` |
+| `useIconController()` | `IconController` |
+| `useAccessToken(clientID, renew?)` | `boolean` | Ottiene token per servizio esterno (true = ok) |
+| `useGlobalVars()` | `Record<string, unknown>` |
+| `useHead()` | `HeadController` |
+| `useDocumentHead()` | `HeadController` |
+| `useAssetsHead(title?)` | `void` |
+| `useLanguageHead(lang?)` | `void` |
+| `useSocialHead(config)` | `void` |
+| `usePaginationHead(config)` | `void` |
+| `usePwaHead(config)` | `void` |
+| `useSchemaOrgHead(config)` | `void` |
+| `useHeadLinks(links)` | `void` |
+| `useProxy()` | `(url, init?) => Promise<Response>` |
+| `useImage()` | `UseImageResult` |
+| `useI18n()` | `I18nController` |
+| `useMenu()` | Menu hook |
+| `useFormController(controller?)` | `FormController` |
+| `useFormActions()` | `FormController` |
+| `useApiProvider(pathname?)` | `ApiProviderAdapter \| null` |
+| `useSetProvider(service, driver?)` | `void` |
+| `useProvider(name)` | `ProviderConfigurationState` |
+| `useProviderSession()` | `ProviderSession` |
+| `useDropBoxConnect(config?)` | `DropBoxConnectResult` |
+| `useEnterMotion(baseStyle?, ref?, fallback?)` | `CSSProperties` |
+| `useMotionState(active, ref?, fallback?, baseStyle?)` | `CSSProperties` |
+| `useMotionEffect(ref?, fallback?)` | `ResolvedMotionEffect` |
+| `usePressMotion(hovered, baseStyle?, ref?, fallback?)` | `{ style, pressHandlers }` |
+| `useIconProvider()` | `IconProvider` |
+
+---
+
+## Tipi chiave
+
+```ts
+type RecordProps  = Record<string, FieldValue>
+type FieldValue   = string | number | boolean | null | undefined | Record<string, unknown> | unknown[]
+type RecordArray  = RecordProps[]
+
+type OrderConfig  = { field: string; dir: 'asc' | 'desc' }
+type WhereClause  = { field: string; op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any'; value: unknown }
+
+interface UIProps {
+  before?: React.ReactNode
+  after?: React.ReactNode
+  wrapperClassName?: string
+  className?: string
+}
+
+type UserProfile = { uid?: string; email?: string; displayName?: string; photoURL?: string; [key: string]: unknown }
+```
+
+---
+
+## Utilities
+
+```ts
+import { cn, converter, Sanitizer, Order, path, fetchJson, fetchRest, fetchWithRetry } from '@llmnative/react'
+import { getKeywordIdeas, getGoogleTrendsData, getGoogleTrendsRelated } from '@llmnative/react'
+
+cn('base', condition && 'extra', className)     // tailwind-merge classname
+new Sanitizer().sanitize(html)                  // XSS sanitizer (non usare dangerouslySetInnerHTML)
+new Order().order(records, { field: 'name', dir: 'asc' })  // ordina record array
+fetchJson(url, init?)                           // fetch + JSON parse + error handling
+fetchRest(path, init?)                          // fetch REST con auth
+getKeywordIdeas(keyword)                        // Google Ads Keyword Ideas
+getGoogleTrendsData(keyword)                    // Google Trends interest over time
+getGoogleTrendsRelated(keyword)                 // Google Trends related queries
+```
+
+---
+
+## Scaffold (npx create)
+
+```bash
+npx @llmnative/react create
+npx @llmnative/react create --yes --provider=mock --template=admin
+```
+
+Flag disponibili: `--name` `--provider=firebase|supabase|mock|custom` `--ai-provider` `--icon-provider` `--theme` `--template=blank|admin|crm|inventory|project`
+
+**5 template disponibili:**
+| Template | Pagine incluse | Uso tipico |
+|---|---|---|
+| `blank` | home | App vuota — massima libertà |
+| `admin` | home, users, roles, settings | Dashboard admin/backoffice |
+| `crm` | home, companies, contacts, deals | CRM |
+| `inventory` | home + gestione inventario | Magazzino |
+| `project` | home + gestione progetti | PM tool |
+
+**Struttura generata in-place nella current directory:**
+```
+src/
+  index.tsx          ← App entry
+  vite-env.d.ts
+  conf/
+    app.ts           ← providers config letta da .env (VITE_PROVIDER, VITE_AI_PROVIDER...)
+    menu.ts          ← MenuConfig con path, title, icon, page (layout opzionale: c'è LayoutDefault)
+  data/
+    mockData.ts      ← dati fake per MockDataProvider
+  layouts/
+    Default.tsx      ← layout wrapper (header + sidebar + main + footer)
+  sections/
+    Header.tsx / Sidebar.tsx / PageHeader.tsx / Footer.tsx   ← solo componenti pubblici (SideNav, AuthButton, ActionButton, Brand, Breadcrumbs)
+  pages/
+    home/HomePage.tsx
+    [altre pagine dal template scelto]
+  styles/
+    globals.css      ← @import '@llmnative/react/dist/index.css' + Tailwind override
+.env                 ← VITE_PROVIDER, VITE_THEME, chiavi API (non committare)
+.env.example         ← stessa struttura, valori vuoti (committare)
+vite.config.ts / tsconfig.json / postcss.config.js / index.html
+```
+
+**Pattern conf/app.ts** (auto-generato, leggere per capire come funziona):
+```ts
+import type { AppProvidersConfig } from '@llmnative/react'
+import { mockData } from '../data/mockData'
+const env = import.meta.env
+
+export const providers: AppProvidersConfig = {
+  mock: { data: mockData },
+  ai: { openaiApiKey: env.VITE_OPENAI_API_KEY ?? '' },  // AI dentro providers, non prop <App>
+  services: { data: 'mock', auth: 'googleAuth' },
+}
+```
+
+Driver per `VITE_PROVIDER`: `firebase` → `firestoreDb` + `firestorage` + `firebaseAuth`; `supabase` → `supabaseDb` + `supabaseStorage` + `supabaseAuth`; `mock` → `mock` + `googleAuth`. `index.tsx` passa `LayoutDefault={Default}` ad `<App>`.
+
+---
+
+## Gotchas — pitfall frequenti
+
+| Errore | Causa | Fix |
+|---|---|---|
+| `aiConfig` prop non esiste su `<App>` | La config AI va dentro `providers.ai`, NON come prop separata | `providers={{ ai: { openaiApiKey } }}` |
+| `inputType` o `Input.Number`/`Input.Email` non esistono | Il tipo HTML è la prop `type` | `<Input type="number">`, `<Input type="email">`, `<Input type="date">` |
+| `Menu context=` non esiste | La prop si chiama `menuKey` | `<Menu menuKey="main" />` |
+| `SignInButton` non esiste | Rinominato | `<AuthButton />` |
+| `firebase: { config: ... }` errato | FirebaseConfig è flat | `firebase: { apiKey, authDomain, databaseURL, ... }` |
+| `google: { oAuth2: { clientId } }` errato | GoogleProviderConfig è flat | `google: { clientId, scope }` |
+| `children` su `Grid` | Grid non accetta children | Usa `form={<Fields />}` per il form inline |
+| `recordId` su `Form` | Prop non esiste | La chiave del record viene da URL automaticamente |
+| `MenuConfig` non importabile | Era type interno | Ora esportato: `import type { MenuConfig } from '@llmnative/react'` |
+| `GridCellContext` non importabile | Mancava dall'index | Ora esportato: `import type { GridCellContext } from '@llmnative/react'` |
+
+---
+
+## Dove cercare nel codice sorgente
+
+| Cosa | File |
+|---|---|
+| Form | `src/components/widgets/Form.tsx` |
+| Grid | `src/components/widgets/Grid.tsx` |
+| Prompt | `src/components/widgets/Prompt.tsx` |
+| Campi form | `src/components/ui/fields/` |
+| Blocks (Menu, Toolbar, Notifications, Dropdown…) | `src/components/blocks/` |
+| Provider data Firebase (RTDB) | `src/providers/data/firebase.ts` |
+| Provider data Firestore | `src/providers/data/firestore.ts` |
+| Provider data Supabase | `src/providers/data/supabase.ts` |
+| Provider storage Firebase | `src/providers/storage/firebase.ts` |
+| Provider storage Supabase | `src/providers/storage/supabase.ts` |
+| Provider auth Firebase | `src/providers/auth/firebase/FirebaseAuthProvider.ts` |
+| Provider auth Supabase | `src/providers/auth/supabase/` |
+| Provider auth Google | `src/providers/auth/google/` |
+| Provider auth Dropbox | `src/providers/auth/dropbox/` |
+| Provider email Gmail | `src/providers/email/google/GmailEmailProvider.ts` |
+| Provider AI definitions | `src/providers/ai/` |
+| Provider credenziali | `src/providers/credentials/` |
+| Provider session | `src/providers/ProviderSession.ts` |
+| Proxy CORS | `src/providers/proxy.ts` |
+| Motion system | `src/motion.ts` |
+| I18n | `src/I18n.tsx` |
+| Dropbox integration | `src/providers/dropbox/` |
+| Interfaccia DataProvider | `src/providers/data/DataProvider.ts` |
+| Interfaccia StorageProvider | `src/providers/storage/StorageProvider.ts` |
+| Interfaccia AuthProvider | `src/providers/auth/AuthProvider.ts` |
+| Interfaccia EmailProvider | `src/providers/email/EmailProvider.ts` |
+| Interfaccia AIProvider | `src/providers/ai/AIProvider.ts` |
+| Registry provider | `src/providers/manifest.ts` |
+| Config provider | `src/providers/ProviderConfiguration.ts` |
+| SEO / Google Trends | `src/providers/seo/google/` |
+| Sistema tema | `src/Theme.tsx` |
+| Config runtime | `src/Config.tsx` |
+| Tipi TypeScript | `src/types/` |
+| Utilities pure | `src/libs/` |