@llmnative/react 1.48.0 → 2.0.1

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;