@llmnative/react 1.47.0 → 2.0.0

package/dist/types/src/I18n.d.ts

@@ -33,6 +33,7 @@ export interface I18nDict {
         requiredField: string;
         requiredFieldGeneric: string;
         saveSuccess: string;
+        saveError: string;
         deleteSuccess: string;
         noticeRequiredFields: string;
         noChangesToSave?: string;

package/dist/types/src/components/index.d.ts

@@ -66,7 +66,7 @@ export type { SortableListProps, SortableListCard, SortableListReorderMeta } fro
 export { default as SideNav } from './blocks/SideNav';
 export type { SideNavProps, SideNavItemDef } from './blocks/SideNav';
 export { default as Form, useFormContext } from './widgets/Form';
-export type { FieldLabel, FormFieldProps, FormProps, FormDeleteArgs, FormDeleteHandler, FormFinallyArgs, FormFinallyHandler, FormSaveArgs, FormSaveHandler, ChangeHandler, FieldOnChange } from './widgets/Form';
+export type { FieldLabel, FormFieldProps, FormProps, FormDeleteArgs, FormDeleteHandler, FormFinallyArgs, FormFinallyHandler, FormSaveArgs, FormSaveHandler, FormSaveProps, FormSubmitArgs, FormSubmitHandler, FormSubmitProps, ChangeHandler, FieldOnChange } from './widgets/Form';
 export { FormControllerContext, useFormActions, useFormController } from './widgets/form-controller';
 export type { FormActionEvent, FormController, FormControllerActions, FormControllerState, FormDraftStatus } from './widgets/form-controller';
 export { default as Grid } from './widgets/Grid';

package/dist/types/src/components/ui/fields/Input.d.ts

@@ -17,6 +17,14 @@ interface BaseInputProps extends FormFieldProps {
     validator?: (value: FieldValue) => string | undefined | Promise<string | undefined>;
     /** Content rendered as an absolute overlay inside the input (right side). No addon border/bg. */
     afterInset?: React.ReactNode;
+    /** The keyboard a phone shows (e.g. `"numeric"` for a code of digits). */
+    inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode'];
+    /** At most this many characters can be typed. */
+    maxLength?: number;
+    /** A regular expression the value must match, for the browser (e.g. `"[0-9]{6}"`); `validator` for the Form's own check. */
+    pattern?: string;
+    /** What the browser may fill in (e.g. `"one-time-code"` for a code received by email or SMS, `"tel"`, `"email"`). */
+    autoComplete?: string;
 }
 interface LabelProps {
     /** A text or a React node, drawn inside the `<label>` before the required mark. */
@@ -73,10 +81,12 @@ export declare const fieldAddonClass = "inline-flex shrink-0 items-center border
 export declare const FieldError: ({ message }: {
     message: string;
 }) => React.JSX.Element;
-export declare const Input: ({ name, onChange, defaultValue, placeholder, label, type, required, readOnlyAfterSet, disabled, before, after, afterInset, feedback, min, max, step, id, labelClassName, inheritWrapperClassName, wrapperClassName, className, validator, labelMode, }: BaseInputProps) => React.JSX.Element;
+export declare const Input: ({ name, onChange, defaultValue, placeholder, label, type, required, readOnlyAfterSet, disabled, before, after, afterInset, feedback, min, max, step, id, labelClassName, inheritWrapperClassName, wrapperClassName, className, validator, labelMode, inputMode, maxLength, pattern, autoComplete, }: BaseInputProps) => React.JSX.Element;
 export declare const String: (props: InputProps) => React.JSX.Element;
 export declare const Number: (props: InputProps) => React.JSX.Element;
 export declare const Email: (props: InputProps) => React.JSX.Element;
+/** A phone number: the phone shows its number keyboard. */
+export declare const Tel: (props: InputProps) => React.JSX.Element;
 export declare const Password: (props: InputProps) => React.JSX.Element;
 export declare const Color: ({ className, ...props }: InputProps) => React.JSX.Element;
 export declare const Date: (props: InputProps) => React.JSX.Element;

package/dist/types/src/components/widgets/Form.d.ts

@@ -17,7 +17,7 @@ export type FieldOnChange = (params: {
     record: RecordProps;
     onChange: FormHandleChange;
 }) => void;
-export type InputType = "text" | "number" | "email" | "password" | "color" | "date" | "time" | "datetime-local" | "week" | "month" | "range" | "checkbox" | "radio" | "url";
+export type InputType = "text" | "number" | "email" | "tel" | "password" | "color" | "date" | "time" | "datetime-local" | "week" | "month" | "range" | "checkbox" | "radio" | "url";
 export type LabelMode = "default" | "floating";
 interface FormContextProps {
     name: string;
@@ -96,13 +96,28 @@ export type FormDeleteArgs = {
 };
 export type FormFinallyArgs = {
     record?: RecordProps;
-    action: 'create' | 'update' | 'delete';
+    /** `submit` after `onSubmit` (action form); the others after a save or a delete. */
+    action: 'create' | 'update' | 'delete' | 'submit';
 };
-export type FormSaveHandler = (args: FormSaveArgs) => Promise<string | undefined>;
+/** What `onSubmit` receives: the record of the fields, as typed. */
+export type FormSubmitArgs = {
+    record: RecordProps;
+};
+/**
+ * Called on save. Return a provider path to write the record there, `undefined` to write it at the
+ * Form's `path` (nothing written without a `path`), `false` when it failed and the page already says
+ * why (nothing written, no notice, `save()` resolves `false`). Throwing shows its message in the Form's notice.
+ */
+export type FormSaveHandler = (args: FormSaveArgs) => Promise<string | undefined | false>;
 export type FormDeleteHandler = (args: FormDeleteArgs) => Promise<string | undefined>;
 export type FormFinallyHandler = (args: FormFinallyArgs) => Promise<boolean>;
-/** Core props shared by all Form variants. */
-interface BaseFormProps {
+/**
+ * The action of an action form. Throwing shows its message in the Form's notice; returning `false` means it
+ * failed and the page already says why (no notice, no `onComplete`, `save()` resolves `false`).
+ */
+export type FormSubmitHandler = (args: FormSubmitArgs) => Promise<void | false> | void | false;
+/** Props shared by both kinds of Form: the one that saves a record and the one that runs an action. */
+interface FormCommonProps {
     /** Visual wrapper: `"card"` adds a card shell; `"empty"` renders bare. */
     appearance?: "card" | "empty";
     /** Shared controller for external actions, custom save buttons and draft state. */
@@ -111,32 +126,16 @@ interface BaseFormProps {
     header?: React.ReactNode;
     /** Custom content rendered in the form footer area. */
     footer?: React.ReactNode;
-    /** Provider path for data load and save. Omit for a pure local form. */
-    path?: string;
-    /** Generate a custom primary key for new records instead of auto-push. */
-    keyGenerator?: (record: RecordProps) => string;
     /** Transform the record after loading from the provider. */
     onLoad?: (record: RecordProps) => void;
     /** Called on every field change with the current record state. */
     onRecordChange?: (record: RecordProps) => void;
-    /** Transform the record before saving. Return the final record or a custom path. */
-    onSave?: FormSaveHandler;
-    /** Called before deletion. Return a path override or `undefined`. */
-    onDelete?: FormDeleteHandler;
-    /** Called after save or delete. Return `false` to suppress default navigation. */
+    /** Called after a save, a delete or a submit that worked. Return `false` to suppress default navigation. */
     onComplete?: FormFinallyHandler;
     /** Log field-change events to the console (dev helper). */
     log?: boolean;
-    /** Show the inline save/delete notice banner. Defaults to `true`. */
+    /** Show the inline notice banner (saved, deleted, required fields, errors). Defaults to `true`; `false` lets an error of `onSave`/`onSubmit` reject `save()` instead. */
     showNotice?: boolean;
-    /**
-     * Whether saving needs a changed field. Defaults to `true`: an unchanged form says "No changes
-     * to save" and its save is disabled. `false` makes it an action form (CR-117), whose initial
-     * values are already a valid submission (e.g. start a release with the proposed version):
-     * `save()` validates and calls `onSave` even when nothing changed. `isDirty` still tells
-     * whether something did.
-     */
-    requireChanges?: boolean;
     /**
      * Stable bucket that isolates this form's local draft. Omit to disable draft persistence.
      * The Form appends its own path/route identity, so one bucket safely serves many forms.
@@ -163,32 +162,61 @@ interface BaseFormProps {
      * `[&>form]:` child selector on `wrapperClassName`.
      */
     formClassName?: string;
-}
-interface FormDefaultProps extends BaseFormProps {
-    children: React.ReactNode | ((fields: FormTree) => React.ReactNode) | ((args: {
+    /** Field elements, a render-prop receiving the field tree, or a record-aware function. */
+    children?: React.ReactNode | ((fields: FormTree) => React.ReactNode) | ((args: {
         record?: RecordProps;
     }) => React.ReactNode);
+    /** Initial field values (a new record, or the proposed values of an action). */
     defaultValues?: RecordProps;
 }
-interface FormDatabaseProps extends FormDefaultProps {
-    path: string;
+/** What a Form that saves a record takes: where, how and what it writes. */
+interface FormSaveOptions {
+    /** Provider path the record is read from and written to. Omitted: read from the route hash if any, else nothing read; nothing written unless `onSave` returns a path. */
+    path?: string;
+    /** Generate a custom primary key for new records instead of auto-push. */
+    keyGenerator?: (record: RecordProps) => string;
+    /**
+     * Called on save, after the fields are valid and only when one changed. Return a provider path to
+     * write the record there, `undefined` to write it at `path`. To run an action instead (call a
+     * command, send a code) use `onSubmit`.
+     */
+    onSave?: FormSaveHandler;
+    /** Called before deletion. Return a path override or `undefined`. */
+    onDelete?: FormDeleteHandler;
 }
-interface FormModelProps extends BaseFormProps {
-    model: ModelProps;
-    children?: ((fields: FormTree) => React.ReactNode);
+/**
+ * A Form that saves a record: it reads it from `path`, writes it there (or where `onSave` says),
+ * shows "Saved", and saves only when a field changed. It shows its own Save button in the card.
+ */
+export interface FormSaveProps extends FormCommonProps, FormSaveOptions {
+    onSubmit?: never;
 }
 /**
- * Public props for `<Form>`.
- * When `path` points to an existing record the form loads its data automatically.
- * When `keyGenerator` or `defaultValues` is set the form operates in create-only mode.
+ * An action form: it saves nothing. On submit (Enter in a field, or `useFormController().save()` from
+ * your own button) it checks the fields and calls `onSubmit({ record })`, changed or not. No Save
+ * button, no "Saved": the button and what follows are yours; an error of `onSubmit` shows in its
+ * notice. It takes no `path`, `onSave`, `onDelete` or `keyGenerator`.
  */
-export interface FormProps extends BaseFormProps {
-    /** Field elements, a render-prop receiving the field tree, or a record-aware function. */
-    children?: React.ReactNode | ((fields: FormTree) => React.ReactNode) | ((args: {
-        record?: RecordProps;
-    }) => React.ReactNode);
-    /** Initial field values for a new record. */
-    defaultValues?: RecordProps;
+export interface FormSubmitProps extends FormCommonProps {
+    /** The action: e.g. `({ record }) => call('requestLoginCode', record)`. */
+    onSubmit: FormSubmitHandler;
+    path?: never;
+    keyGenerator?: never;
+    onSave?: never;
+    onDelete?: never;
+}
+/** Public props for `<Form>`: a Form that saves a record (`FormSaveProps`) or an action form (`FormSubmitProps`, with `onSubmit`). */
+export type FormProps = FormSaveProps | FormSubmitProps;
+/** What the inner Form takes: either kind, checked by `Form`. */
+interface FormDataProps extends FormCommonProps, FormSaveOptions {
+    onSubmit?: FormSubmitHandler;
+}
+interface FormDatabaseProps extends FormDataProps {
+    path: string;
+}
+interface FormModelProps extends Omit<FormCommonProps, 'children'>, FormSaveOptions {
+    model: ModelProps;
+    children?: ((fields: FormTree) => React.ReactNode);
 }
 declare function Form(props: FormProps): React.JSX.Element;
 export declare const FormDatabase: (props: FormDatabaseProps) => React.JSX.Element;

package/llms-full.txt

@@ -305,7 +305,7 @@ export class RestDataProvider implements DataProviderAdapter {
 | `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`) |
-| `requireChanges` | `boolean` | Default `true`: senza un campo cambiato il salvataggio dice "No changes to save" ed è disabilitato. `false` = form d'azione (CR-117): i valori iniziali sono già un invio valido (es. avviare una release con la versione proposta), `save()` valida e chiama `onSave` anche senza modifiche; `isDirty` dice comunque se qualcosa è cambiato |
+| `onSubmit` | `FormSubmitHandler` | `async ({ record }) => void`. **Form d'azione** (CR-125): non legge e non scrive nulla; invia anche senza modifiche e con Invio in un campo; niente pulsante Salva né "Salvato" (il pulsante è tuo: `useFormController().save()`); l'errore lanciato appare nel suo avviso; restituire `false` = è fallito e la pagina dice già perché (nessun avviso né `onComplete`). Esclude `path`, `onSave`, `onDelete`, `keyGenerator` (errore di tipo e a runtime). Sostituisce `requireChanges={false}` della 1.x |
 | `children` | `ReactNode \| ((fields) => ReactNode) \| (({ record }) => ReactNode)` | Contenuto form |
 | `header` | `ReactNode` | Contenuto header custom |
 | `footer` | `ReactNode` | Contenuto footer custom |
@@ -316,9 +316,9 @@ export class RestDataProvider implements DataProviderAdapter {
 | `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` |
+| `onSave` | `FormSaveHandler` | `async ({ record, prevRecord?, storagePath?, action }) => string \| undefined`. Form che **salva un record**, solo se un campo è cambiato: restituisce il path dove scriverlo, `undefined` = il `path` del Form (senza `path` non scrive), `false` = è fallito e la pagina dice già perché (non scrive, nessun avviso, `save()` dà `false`). Per un'azione (chiamare un comando) usa `onSubmit`. L'errore lanciato appare nell'avviso del Form |
 | `onDelete` | `FormDeleteHandler` | `async ({ record }) => string \| undefined` |
-| `onComplete` | `FormFinallyHandler` | `async ({ record, action }) => boolean` |
+| `onComplete` | `FormFinallyHandler` | `async ({ record, action }) => boolean`; `action` è `'create' \| 'update' \| 'delete' \| 'submit'` |
 
 **Form controller** — stato e azioni native del form accessibili da qualsiasi punto della pagina.
 
@@ -337,15 +337,18 @@ const form = useFormController();
 <Form controller={form} draftBucket="workspace/acme" onSave={...} />
 ```
 
-Esempio — form d'azione, i valori proposti si inviano anche senza modificarli (CR-117):
+Esempio — form d'azione: chiama un comando, non salva nulla (CR-125):
 ```tsx
 const form = useFormController();
 
-<LoadingButton label="Avvia la release" onClick={() => form.save()} />
-<Form controller={form} appearance="empty" requireChanges={false} defaultValues={{ version: '1.4.0', notes }} onSave={async ({ record }) => { await start(record); return undefined; }}>
-  <Input name="version" label="Versione" required />
+<Form controller={form} appearance="empty" onSubmit={({ record }) => call('verifyLoginCode', record)}>
+  <Input name="email" type="email" label="Email" required />
+  <Input name="code" label="Codice" required inputMode="numeric" maxLength={6} pattern="[0-9]{6}" autoComplete="one-time-code" />
 </Form>
+<LoadingButton label="Entra con il codice" loading={form.isSaving} onClick={() => form.save()} />
 ```
+Con valori proposti (avviare una release con la versione proposta) si inviano anche senza modificarli:
+`<Form controller={form} appearance="empty" defaultValues={{ version: '1.4.0' }} onSubmit={({ record }) => start(record)}>`.
 
 Esempio — uso dentro il form (senza passare controller):
 ```tsx
@@ -368,6 +371,8 @@ Azioni: `save()`, `delete()`, `reset()`, `restoreDraft()`, `discardDraft()`.
 <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="phone" type="tel" autoComplete="tel" />                 // o <Tel name="phone" />
+<Input name="code" inputMode="numeric" maxLength={6} pattern="[0-9]{6}" autoComplete="one-time-code" />  // un codice monouso
 <Input name="pwd"   type="password" />
 <Input name="date"  type="date" />
 <Input name="color" type="color" />
@@ -375,8 +380,8 @@ Azioni: `save()`, `delete()`, `reset()`, `restoreDraft()`, `discardDraft()`.
 <Checkbox name="active" valueChecked="yes" />
 <Switch name="gate" label="Passa dalla CI" disabled title="L'agente non committa" />   // CR-116: disabled (non cambia né con il clic né da tastiera), title anche sull'etichetta: il motivo al passaggio del mouse
 ```
-`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'`
+`Input` props: `name`(req) `label` `type` `required` `disabled` `placeholder` `min` `max` `step` `inputMode` `maxLength` `pattern` `autoComplete` `validator:(v)=>string|undefined`
+`type`: `'text' | 'number' | 'email' | 'tel' | '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.
 
@@ -1191,6 +1196,8 @@ const registry = createAIProviderRegistry(definitions)
 // Azioni di Chatbot (CR-107): con `content` aprono un menu; senza, sono pulsanti con `onClick`.
 // <Chatbot actions={[{ key: 'finish', icon: 'git-pull-request', label: 'Concludi', showLabel: true,
 //   disabled: running, onClick: finish }]} … />
+// Allegati di Chatbot (`attachments`): file scelti, trascinati o incollati con Ctrl+V (uno screenshot diventa
+// `pasted-<data>.png`, CR-124); il testo incollato resta testo. Arrivano in `onSubmit` come `files`.
 // Comandi "/" di Chatbot: `commands` (EditorCommand[]) + `commandsTrigger` (default "/").
 // Il menu mostra `/name` e sotto la `description`; il filtro cerca in entrambi (CR-111).
 // Senza `handler` la scelta inserisce "/name " e l'invio manda il testo così com'è.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnative/react",
-  "version": "1.47.0",
+  "version": "2.0.0",
   "description": "LLM-native React framework for deterministic UI generation. Data-driven by default, schema-driven optional. Ultra-low token consumption — built for AI agents, not just humans.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",