npm - @llmnative/react - Versions diffs - 1.20.0 → 1.22.0 - Mend

@llmnative/react 1.20.0 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/index.css +1 -1
package/dist/index.js +15 -15
package/dist/index.js.map +1 -1
package/dist/index.mjs +1453 -1324
package/dist/index.mjs.map +1 -1
package/dist/types/src/I18n.d.ts +6 -0
package/dist/types/src/Theme.d.ts +3 -0
package/dist/types/src/components/blocks/SideNav.d.ts +7 -1
package/dist/types/src/components/ui/fields/Select.d.ts +11 -2
package/llms-full.txt +1182 -1148
package/package.json +1 -1
package/themes/cyber.ts +3 -0
package/themes/default.ts +3 -0
package/themes/flat.ts +3 -0

package/llms-full.txt CHANGED Viewed

@@ -1,1148 +1,1182 @@
-# @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`.
----
-## 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` | `providers.google/firebase/supabase/dropbox` | 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')
-```
-### 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.
-### Select / Autocomplete / Checklist
-```tsx
-<Select name="role" options={[{ label: 'Admin', value: 'admin' }]} />
-<Select name="categoryId" optionsSource={{ path: '/categories', labelField: 'name', valueField: '_key' }} />
-<Select.Autocomplete name="userId" optionsSource={{ path: '/users', labelField: 'email' }} />
-<Select.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) => Promise<void>` | Solo Autocomplete |
-| `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 |
-### 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` | Modal seconda in pila |
-| `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` |
-### 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>
-```
-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="..." label="Mario" size={40} />
-<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={() => {}} />
-<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` |
-**Search:**
-| Prop | Tipo |
-|---|---|
-| `onQueryChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` |
-**Notifications:**
-| Prop | Tipo |
-|---|---|
-| `items` | `NotificationItem[]` |
-| `badge` | `BadgeProps` |
-| `seeAllUrl` | `string` |
-| `onMarkAllRead` | `() => void` |
-| `motion` | `MotionReference` |
-**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)
-```
-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')     // 'default' | 'flat' | 'cyber' | 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}
+/>
+```
+### 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`.
+---
+## 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` | `providers.google/firebase/supabase/dropbox` | 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')
+```
+### 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.
+### 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` | Modal seconda in pila |
+| `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` |
+### 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>
+```
+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} />
+<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={() => {}} />
+<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` |
+**Search:**
+| Prop | Tipo |
+|---|---|
+| `onQueryChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` |
+**Notifications:**
+| Prop | Tipo |
+|---|---|
+| `items` | `NotificationItem[]` |
+| `badge` | `BadgeProps` |
+| `seeAllUrl` | `string` |
+| `onMarkAllRead` | `() => void` |
+| `motion` | `MotionReference` |
+**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)
+```
+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')     // 'default' | 'flat' | 'cyber' | 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/` |