@llmnative/react 1.19.1 → 1.19.2

package/llms-full.txt

@@ -0,0 +1,1140 @@
+# @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>
+<Modal.YesNo title="Sicuro?" onClose={() => {}} onYes={async () => true} />
+<Modal.Ok title="Completato!" onClose={() => {}} />
+```
+`size`: `'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'fullscreen'`
+`position`: `'center' | 'top' | 'left' | 'right' | 'bottom'`
+
+| 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` |
+| `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
+<Tab defaultIndex={0} layout="top">
+  <Tab.Item label="Generale">{content1}</Tab.Item>
+  <Tab.Item label="SEO">{content2}</Tab.Item>
+</Tab>
+```
+`layout`: `'default' | 'top' | 'left' | 'right' | 'bottom'`
+
+### 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 />                               // spinner
+<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/` |