@llmnative/react 0.1.1 → 1.0.0

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

@@ -1,15 +1,22 @@
 import React from 'react';
 import { UIProps } from '../../..';
 import { FormFieldProps, InputType } from '../../widgets/Form';
+import type { FieldValue } from '../../../providers/data/DataProvider';
 interface BaseInputProps extends FormFieldProps {
     placeholder?: string;
     type?: InputType;
-    updatable?: boolean;
+    /** When `true`, the field becomes read-only (disabled) once a value has been set. */
+    readOnlyAfterSet?: boolean;
     disabled?: boolean;
     feedback?: string;
     min?: number;
     max?: number;
     step?: number;
+    id?: string;
+    labelClassName?: string;
+    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;
 }
 interface LabelProps {
     label: string;
@@ -20,15 +27,27 @@ interface LabelProps {
 export type InputProps = Omit<BaseInputProps, 'type'>;
 export interface CheckboxProps extends FormFieldProps {
     title?: string;
+    ariaLabel?: string;
     valueChecked?: string | number;
 }
+export interface HiddenProps extends FormFieldProps {
+    id?: string;
+}
 export interface TextAreaProps extends FormFieldProps {
     placeholder?: string;
-    updatable?: boolean;
+    /** When `true`, the textarea becomes read-only (disabled) once a value has been set. */
+    readOnlyAfterSet?: boolean;
     disabled?: boolean;
-    rows?: number;
+    minHeight?: number;
+    maxHeight?: number;
     feedback?: string;
-    useRef?: any;
+    textareaRef?: React.RefObject<HTMLTextAreaElement | null> | ((el: HTMLTextAreaElement | null) => void) | undefined;
+    id?: string;
+    labelClassName?: string;
+    validator?: (value: FieldValue) => string | undefined | Promise<string | undefined>;
+    onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>;
+    onClick?: React.MouseEventHandler<HTMLTextAreaElement>;
+    onBlur?: React.FocusEventHandler<HTMLTextAreaElement>;
 }
 export interface ListGroupProps extends UIProps {
     children: React.ReactNode[];
@@ -36,17 +55,26 @@ export interface ListGroupProps extends UIProps {
     label?: string;
     draggable?: boolean;
     onDrop?: (text: string) => string;
-    actives?: number[];
-    disables?: number[];
-    loaders?: number[];
-    itemClass?: string;
+    activeIndices?: number[];
+    disabledIndices?: number[];
+    loadingIndices?: number[];
+    itemClassName?: string;
 }
-export declare const Input: ({ name, onChange, defaultValue, placeholder, label, type, required, updatable, disabled, pre, post, feedback, min, max, step, wrapClass, className }: BaseInputProps) => React.JSX.Element;
+export declare const fieldLabelClass = "mb-1 block text-sm font-medium leading-5 text-foreground";
+export declare const fieldFeedbackClass = "mt-1 text-xs text-muted-foreground";
+export declare const fieldControlBaseClass = "flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50";
+export declare const fieldTextAreaBaseClass = "flex min-h-[5rem] w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50";
+export declare const fieldGroupClass = "flex w-full items-stretch";
+export declare const fieldAddonClass = "inline-flex shrink-0 items-center border border-input bg-muted px-3 py-1 text-sm text-muted-foreground";
+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 String: (props: InputProps) => React.JSX.Element;
 export declare const Number: (props: InputProps) => React.JSX.Element;
 export declare const Email: (props: InputProps) => React.JSX.Element;
 export declare const Password: (props: InputProps) => React.JSX.Element;
-export declare const Color: (props: InputProps) => React.JSX.Element;
+export declare const Color: ({ className, ...props }: InputProps) => React.JSX.Element;
 export declare const Date: (props: InputProps) => React.JSX.Element;
 export declare const Time: (props: InputProps) => React.JSX.Element;
 export declare const DateTime: (props: InputProps) => React.JSX.Element;
@@ -54,9 +82,10 @@ export declare const Week: (props: InputProps) => React.JSX.Element;
 export declare const Month: (props: InputProps) => React.JSX.Element;
 export declare const Range: (props: InputProps) => React.JSX.Element;
 export declare const Url: (props: InputProps) => React.JSX.Element;
-export declare const Checkbox: ({ name, onChange, defaultValue, label, title, required, valueChecked, pre, post, wrapClass, className }: CheckboxProps) => React.JSX.Element;
-export declare const Switch: (props: CheckboxProps) => React.JSX.Element;
+export declare const Hidden: ({ name, onChange, defaultValue, value, id, inheritWrapperClassName, wrapperClassName, }: HiddenProps) => React.JSX.Element;
+export declare const Checkbox: ({ name, onChange, defaultValue, label, title, ariaLabel, required, valueChecked, before, after, inheritWrapperClassName, wrapperClassName, className }: CheckboxProps) => React.JSX.Element;
+export declare const Switch: ({ name, onChange, defaultValue, label, title, ariaLabel, required, valueChecked, before, after, inheritWrapperClassName, wrapperClassName, className }: CheckboxProps) => React.JSX.Element;
 export declare const Label: ({ label, required, htmlFor, className }: LabelProps) => React.JSX.Element;
-export declare const TextArea: ({ name, onChange, defaultValue, placeholder, label, required, updatable, disabled, rows, useRef, pre, post, feedback, className, wrapClass }: TextAreaProps) => React.JSX.Element;
-export declare const ListGroup: ({ children, onClick, label, actives, draggable, onDrop, disables, loaders, pre, post, wrapClass, className, itemClass }: ListGroupProps) => React.JSX.Element;
+export declare const TextArea: ({ name, onChange, defaultValue, placeholder, label, required, readOnlyAfterSet, disabled, minHeight, maxHeight, textareaRef, before, after, feedback, id, labelClassName, inheritWrapperClassName, className, wrapperClassName, validator, onKeyDown, onClick, onBlur, labelMode, }: TextAreaProps) => React.JSX.Element;
+export declare const ListGroup: ({ children, onClick, label, activeIndices, draggable, onDrop, disabledIndices, loadingIndices, before, after, wrapperClassName, className, itemClassName }: ListGroupProps) => React.JSX.Element;
 export {};

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

@@ -1,31 +1,2 @@
-import React from 'react';
-import { AIFetchConfig } from '../../../providers/ai';
-import { PromptVariables } from '../../../conf/Prompt';
-import { FormFieldProps } from '../../widgets/Form';
-export declare enum PromptMode {
-    EDITOR = "editor",
-    LIVE = "live"
-}
-type PromptOptions = AIFetchConfig & {
-    value: string;
-};
-type OnRunPrompt = (prompt: string, config: AIFetchConfig, data?: PromptVariables) => Promise<string>;
-export interface PromptProps extends FormFieldProps {
-    mode?: PromptMode;
-    onRunPrompt?: OnRunPrompt;
-    renderPromptDisabled?: (props: Omit<FormFieldProps, "defaultValue">) => React.ReactNode;
-    rows?: number;
-    defaultValue?: {
-        value?: string;
-        enabled?: boolean;
-        role?: string;
-        language?: string;
-        voice?: string;
-        style?: string;
-        model?: string;
-        temperature?: number;
-    };
-}
-export declare const Prompt: ({ mode, onRunPrompt, renderPromptDisabled, ...props }: PromptProps) => React.JSX.Element;
-export declare const runPrompt: (options: PromptOptions, data?: PromptVariables, onRunPrompt?: OnRunPrompt) => Promise<string>;
-export {};
+export { default, Prompt, PromptMode, runPrompt } from '../../widgets/Prompt';
+export type { PromptProps } from '../../widgets/Prompt';

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

@@ -0,0 +1,86 @@
+import React from 'react';
+import { FormFieldProps } from '../../widgets/Form';
+import type { FieldValue } from '../../../providers/data/DataProvider';
+export type ToolbarCommand = 'bold' | 'italic' | 'underline' | 'strike' | 'headings' | 'heading1' | 'heading2' | 'heading3' | 'bulletList' | 'orderedList' | 'blockquote' | 'code' | 'codeBlock' | 'link' | 'table' | 'imageUpload' | 'documentUpload' | 'sourceCode' | 'undo' | 'redo' | 'clearFormat' | '|';
+export interface StatusBarConfig {
+    /** Show the DOM ancestor tag breadcrumb at the cursor (e.g. p › strong). Default: true. */
+    tagBreadcrumb?: boolean;
+    /** Show the word count. Default: true. */
+    wordCount?: boolean;
+    /** Show the character count. Default: false. */
+    charCount?: boolean;
+}
+export interface RichTextImageUploadConfig {
+    /**
+     * Storage path prefix for uploaded images.
+     * Requires a StorageProvider ancestor.
+     * Example: "/content/posts/hero"
+     */
+    path?: string;
+    /**
+     * Pixel widths to generate as responsive srcset variants.
+     * Each width produces a canvas-resized copy stored as <name>_<width>w.<ext>.
+     * Pass [] to disable srcset generation entirely.
+     * Default: [400, 800]
+     */
+    srcsetWidths?: number[];
+    /**
+     * Accepted MIME types for the image file picker.
+     * Default: "image/*"
+     */
+    accept?: string;
+    /**
+     * Maximum file size in bytes.
+     * Default: 10_485_760 (10 MB)
+     */
+    maxBytes?: number;
+}
+export interface RichTextDocumentUploadConfig {
+    /**
+     * Storage path prefix for uploaded documents.
+     * Requires a StorageProvider ancestor.
+     * Example: "/content/posts/attachments"
+     */
+    path?: string;
+    /**
+     * Accepted MIME types / file extensions for the document file picker.
+     * Default: ".pdf,.doc,.docx,.txt,.csv"
+     */
+    accept?: string;
+    /**
+     * Maximum file size in bytes.
+     * Default: 20_971_520 (20 MB)
+     */
+    maxBytes?: number;
+}
+export interface RichTextProps extends FormFieldProps {
+    placeholder?: string;
+    disabled?: boolean;
+    feedback?: string;
+    /** Position of the formatting toolbar. false hides it entirely. Default: 'fixed'. */
+    toolbar?: 'fixed' | 'floating' | false;
+    /** Ordered list of toolbar commands to show. Defaults to all commands. */
+    toolbarCommands?: ToolbarCommand[];
+    /** Format used to read/write the field value. Default: 'html'. */
+    outputFormat?: 'html' | 'json' | 'text';
+    /** Show the status bar below the editor. Pass true for defaults or a config object. Default: false. */
+    statusBar?: boolean | StatusBarConfig;
+    /** Minimum editor height in px. Default: 120. */
+    minHeight?: number;
+    /** Maximum editor height in px; content scrolls beyond this. */
+    maxHeight?: number;
+    /**
+     * Image upload behaviour for the imageUpload toolbar command.
+     * Pass an object to enable uploads; omit to keep images as base64 data URIs.
+     */
+    imageUpload?: RichTextImageUploadConfig;
+    /**
+     * Document upload behaviour for the documentUpload toolbar command.
+     * Pass an object to enable cloud storage uploads; omit to use data URI fallback.
+     */
+    documentUpload?: RichTextDocumentUploadConfig;
+    labelClassName?: string;
+    validator?: (value: FieldValue) => string | undefined;
+}
+export declare const RichText: ({ name, onChange, defaultValue, label, required, placeholder, disabled, feedback, toolbar, toolbarCommands, outputFormat, statusBar, minHeight, maxHeight, imageUpload, documentUpload, labelClassName, inheritWrapperClassName, wrapperClassName, className, before, after, validator, }: RichTextProps) => React.JSX.Element;
+export default RichText;

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

@@ -1,38 +1,41 @@
 import React from 'react';
 import { type OrderConfig } from "../../../libs/order";
-import { DBConfig, RecordProps } from "../../../providers/data/DataProvider";
+import { DBConfig, FieldValue, RecordProps } from "../../../providers/data/DataProvider";
 import { FormFieldProps } from '../../widgets/Form';
 interface Option extends RecordProps {
     label: string;
     value: string;
+    group?: string;
 }
 type OptionOrderConfig = OrderConfig & {
     field: 'label' | 'value';
 };
 interface BaseProps extends FormFieldProps {
-    updatable?: boolean;
+    /** When `true`, the select becomes read-only (disabled) once a value has been set. */
+    readOnlyAfterSet?: boolean;
     disabled?: boolean;
     title?: string;
     feedback?: string;
     options?: Option[] | string[] | number[];
-    db?: DBConfig;
+    optionsSource?: DBConfig;
     order?: OptionOrderConfig;
+    validator?: (value: FieldValue) => string | undefined;
 }
 export interface SelectProps extends BaseProps {
-    optionEmpty?: Option;
+    placeholderOption?: Option;
     value?: string | number;
 }
 export interface AutocompleteProps extends BaseProps {
-    min?: number;
-    max?: number;
+    minItems?: number;
+    maxItems?: number;
     placeholder?: string;
     creatable?: boolean;
     onCreate?: (value: string) => Promise<void> | void;
 }
 export interface ChecklistProps extends BaseProps {
-    checkClass?: string;
+    itemClassName?: string;
 }
-export declare const Select: ({ name, onChange, defaultValue, required, updatable, disabled, optionEmpty, label, title, pre, post, feedback, options, db, order, wrapClass, className, }: SelectProps) => React.JSX.Element;
-export declare const Autocomplete: ({ name, defaultValue, min, max, onChange, required, updatable, disabled, label, title, placeholder, pre, post, feedback, options, db, order, wrapClass, className, creatable, onCreate, }: AutocompleteProps) => React.JSX.Element;
-export declare const Checklist: ({ name, defaultValue, onChange, required, updatable, disabled, label, title, pre, post, feedback, options, db, order, wrapClass, className, checkClass, }: ChecklistProps) => React.JSX.Element;
+export declare const Select: ({ name, onChange, defaultValue, required, readOnlyAfterSet, disabled, placeholderOption, label, title, before, after, feedback, options, optionsSource, order, inheritWrapperClassName, wrapperClassName, className, validator, }: SelectProps) => React.JSX.Element;
+export declare const Autocomplete: ({ name, defaultValue, minItems, maxItems, onChange, required, readOnlyAfterSet, disabled, label, title, placeholder, before, after, feedback, options, optionsSource, order, inheritWrapperClassName, wrapperClassName, className, creatable, onCreate, }: AutocompleteProps) => React.JSX.Element;
+export declare const Checklist: ({ name, defaultValue, onChange, required, readOnlyAfterSet, disabled, label, title, before, after, feedback, options, optionsSource, order, inheritWrapperClassName, wrapperClassName, className, itemClassName, }: ChecklistProps) => React.JSX.Element;
 export {};

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

@@ -9,17 +9,52 @@ export interface FileProps {
     url: string;
     base64?: string;
     variants: Record<string, any>;
+    srcset?: string;
+    sizes?: string;
 }
+export interface UseFileUploadCoreOptions {
+    /** Called on every files state update. Use for Form sync. */
+    onFilesChange?: (files: FileProps[]) => void;
+    /** Called once when a file reaches progress 100. Use to trigger insert dialogs. */
+    onFileReady?: (file: FileProps) => void;
+    /** StorageProvider path. When set with a storage provider, files are auto-uploaded. */
+    uploadPath?: string;
+    /**
+     * Pixel widths for responsive image variants. When set with uploadPath, generates
+     * canvas-resized variants at each width and populates file.srcset / file.sizes.
+     * Each variant is stored as <name>_<width>w.<ext>. Default: undefined (no variants).
+     * Example: [400, 800] produces _400w and _800w files.
+     */
+    srcsetWidths?: number[];
+    /** Initial file list (e.g. from a form record on load). */
+    initialFiles?: FileProps[];
+}
+export declare const useFileUploadCore: ({ onFilesChange, onFileReady, uploadPath, srcsetWidths, initialFiles, }: UseFileUploadCoreOptions) => {
+    files: FileProps[];
+    setFiles: React.Dispatch<React.SetStateAction<FileProps[]>>;
+    fileInputRef: React.MutableRefObject<HTMLInputElement | null>;
+    updateFile: (key: string, updates: Partial<FileProps>) => void;
+    handleFiles: (selectedFiles: File[]) => void;
+    handleUpload: () => void | undefined;
+    handleUploadChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    handleRemove: (key: string) => void;
+};
 export interface UploadDocumentProps extends FormFieldProps {
     editable?: boolean;
     multiple?: boolean;
     accept?: string;
     max?: number;
+    /** StorageProvider path — when set, files are auto-uploaded on selection. */
+    uploadPath?: string;
 }
 export interface UploadImageProps extends UploadDocumentProps {
     previewHeight?: number;
     previewWidth?: number;
+    /** Text shown inside the empty-state drop zone, below the upload icon. */
+    feedback?: string;
+    /** Pixel widths for responsive variants. Set with uploadPath to generate <name>_400w.jpg etc. and populate srcset/sizes in the Form record. */
+    srcsetWidths?: number[];
 }
 export declare const getFileUrl: (file: FileProps, suffix?: string) => string;
-export declare const UploadDocument: ({ name, onChange, label, required, editable, multiple, max, accept, pre, post, wrapClass, className, }: UploadDocumentProps) => React.JSX.Element;
-export declare const UploadImage: ({ name, onChange, label, editable, multiple, accept, required, max, previewHeight, previewWidth, pre, post, wrapClass, className, }: UploadImageProps) => React.JSX.Element;
+export declare const UploadDocument: ({ name, onChange, label, required, editable, multiple, max, accept, uploadPath, before, after, wrapperClassName, className, }: UploadDocumentProps) => React.JSX.Element;
+export declare const UploadImage: ({ name, onChange, label, feedback, editable, multiple, accept, required, max, previewHeight, previewWidth, uploadPath, srcsetWidths, before, after, wrapperClassName, className, }: UploadImageProps) => React.JSX.Element;

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

@@ -15,12 +15,14 @@ export type UploadCSVParseFieldHandler = (field: UploadCSVParseField) => UploadC
 interface UploadCSVProps extends UIProps {
     name: string;
     onDataLoaded: UploadCSVDataLoadedHandler;
+    onClear?: () => void;
     onParseField?: UploadCSVParseFieldHandler;
     label?: string;
     icon?: string;
     delimiter?: string;
     normalizeKeys?: boolean;
     removeEmptyFields?: boolean;
+    required?: boolean;
 }
 export declare const UploadCSV: React.FC<UploadCSVProps>;
 export {};

package/dist/types/src/components/ui/useRecordSelection.d.ts

@@ -7,11 +7,10 @@ export type RecordSelectionState<TRecord> = {
 type UseRecordSelectionArgs<TRecord> = {
     records: TRecord[];
     selectedKeys?: string[];
-    legacySelectedKeys?: string[];
     onSelectionChange?: (selection: RecordSelectionState<TRecord>) => void;
     getRecordKey: (record: TRecord, index: number) => string;
 };
-export declare function useRecordSelection<TRecord>({ records, selectedKeys, legacySelectedKeys, onSelectionChange, getRecordKey, }: UseRecordSelectionArgs<TRecord>): {
+export declare function useRecordSelection<TRecord>({ records, selectedKeys, onSelectionChange, getRecordKey, }: UseRecordSelectionArgs<TRecord>): {
     activeSelectedKeys: string[];
     selectionState: RecordSelectionState<TRecord>;
     showSelection: boolean;

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

@@ -1,31 +1,34 @@
 import React from 'react';
-import { RecordProps } from "../../providers/data/DataProvider";
+import { FieldValue, RecordProps } from "../../providers/data/DataProvider";
 import { FormTree, ModelProps } from "../Component";
 import { UIProps } from '../';
-export type ChangeHandler = React.ChangeEvent<any> | {
+import { type FormController } from './form-controller';
+export type ChangeHandler = React.ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement> | {
     target: {
         name: string;
-        value?: any;
+        value?: FieldValue;
     };
 };
 type FormHandleChange = (event: ChangeHandler) => void;
 export type FieldOnChange = (params: {
     event: ChangeHandler;
     name: string;
-    value: any;
+    value: FieldValue;
     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 LabelMode = "default" | "floating";
 interface FormContextProps {
     name: string;
     onChange?: FieldOnChange;
-    wrapClass?: string;
+    wrapperClassName?: string;
     inputType?: InputType;
-    defaultValue?: any;
+    defaultValue?: FieldValue;
+    inheritWrapperClassName?: boolean;
 }
 interface FormContextResult {
-    value: any;
+    value: FieldValue;
     handleChange: FormHandleChange;
     formWrapClass?: string;
     record: RecordProps;
@@ -33,29 +36,44 @@ interface FormContextResult {
 export interface FormFieldProps extends UIProps {
     name: string;
     label?: string;
-    value?: any;
+    labelMode?: LabelMode;
+    value?: FieldValue;
     required?: boolean;
     onChange?: FieldOnChange;
-    defaultValue?: any;
+    defaultValue?: FieldValue;
+    inheritWrapperClassName?: boolean;
 }
 interface SetFormFieldsNameProps {
     children: React.ReactNode;
     parentName: string;
     parentKey?: string;
-    wrapClass?: string;
+    wrapperClassName?: string;
 }
-export declare const useFormContext: ({ name, onChange, wrapClass, inputType, defaultValue }: FormContextProps) => FormContextResult;
+interface FieldValidationConstraints {
+    required?: boolean;
+    label?: string;
+    validator?: (value: FieldValue) => string | undefined | Promise<string | undefined>;
+}
+interface FormValidationContextValue {
+    registerField: (name: string, ref: React.MutableRefObject<FieldValidationConstraints>) => void;
+    unregisterField: (name: string) => void;
+    clearFieldError: (name: string) => void;
+    errors: Record<string, string>;
+}
+export declare const FormValidationContext: React.Context<FormValidationContextValue | null>;
+/**
+ * Hook for field components to register themselves for validation and receive
+ * their error message. Call it in every field that supports `required`.
+ */
+export declare const useFieldValidation: (name: string, constraints: FieldValidationConstraints) => string | undefined;
+export declare const useFormContext: ({ name, onChange, wrapperClassName, inputType, defaultValue, inheritWrapperClassName }: FormContextProps) => FormContextResult;
 type UseHandleDropProps = {
     name: string;
-    value: string;
+    value: FieldValue;
     handleChange?: FormHandleChange;
 };
 export declare const useHandleDrop: ({ name, value, handleChange }: UseHandleDropProps) => (e: React.DragEvent<HTMLTextAreaElement | HTMLInputElement>) => void;
-export declare const setFormFieldsName: ({ children, parentName, parentKey, wrapClass }: SetFormFieldsNameProps) => React.ReactNode;
-export type SavePathProps = {
-    record: RecordProps;
-    storagePath?: string;
-};
+export declare const setFormFieldsName: ({ children, parentName, parentKey, wrapperClassName }: SetFormFieldsNameProps) => React.ReactNode;
 export type FormSaveArgs = {
     record?: RecordProps;
     prevRecord?: RecordProps;
@@ -72,26 +90,49 @@ export type FormFinallyArgs = {
 export type FormSaveHandler = (args: FormSaveArgs) => Promise<string | undefined>;
 export type FormDeleteHandler = (args: FormDeleteArgs) => Promise<string | undefined>;
 export type FormFinallyHandler = (args: FormFinallyArgs) => Promise<boolean>;
+/** Core props shared by all Form variants. */
 interface BaseFormProps {
-    aspect?: "card" | "empty";
+    /** Visual wrapper: `"card"` adds a card shell; `"empty"` renders bare. */
+    appearance?: "card" | "empty";
+    /** Shared controller for external actions, custom save buttons and draft state. */
+    controller?: FormController;
+    /** Custom content rendered in the form header area. */
     header?: React.ReactNode;
+    /** Custom content rendered in the form footer area. */
     footer?: React.ReactNode;
-    dataStoragePath?: string;
-    handlers?: FormHandlers;
-    setPrimaryKey?: (record: RecordProps) => string;
-    savePath?: (props: SavePathProps) => string | undefined;
+    /** 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;
-    onChange?: (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;
-    onFinally?: FormFinallyHandler;
+    /** Called after save or delete. 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`. */
     showNotice?: boolean;
+    /** Persist unsaved changes locally and offer restore/discard on re-entry. Defaults to `false`. */
+    persistDraft?: boolean;
+    /** When provided, the save/delete notice is rendered sticky at the top of this container
+     *  instead of inline in the form footer. Ideal for full-page forms outside a modal. */
+    noticeAnchorRef?: React.RefObject<HTMLElement>;
+    /** Render a Back navigation button in the footer. */
     showBack?: boolean;
-    wrapClass?: string;
-    headerClass?: string;
+    /** CSS classes on the outermost wrapper element. */
+    wrapperClassName?: string;
+    /** CSS classes on the header container. */
+    headerClassName?: string;
+    /** CSS classes on the form body element. */
     className?: string;
-    footerClass?: string;
+    /** CSS classes on the footer container. */
+    footerClassName?: string;
 }
 interface FormDefaultProps extends BaseFormProps {
     children: React.ReactNode | ((fields: FormTree) => React.ReactNode) | ((args: {
@@ -100,30 +141,26 @@ interface FormDefaultProps extends BaseFormProps {
     defaultValues?: RecordProps;
 }
 interface FormDatabaseProps extends FormDefaultProps {
-    dataStoragePath: string;
+    path: string;
 }
 interface FormModelProps extends BaseFormProps {
     model: ModelProps;
     children?: ((fields: FormTree) => React.ReactNode);
 }
-interface FormProps extends BaseFormProps {
+/**
+ * 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.
+ */
+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 FormRef {
-    handleSave: (e: React.MouseEvent<HTMLButtonElement>) => Promise<boolean>;
-    handleDelete: (e: React.MouseEvent<HTMLButtonElement>) => Promise<boolean>;
-    getHeader: () => React.ReactNode;
-    getRecord: () => {
-        record: RecordProps;
-        isNewRecord: boolean;
-    };
-    getFooter: () => React.ReactNode;
-}
-type FormHandlers = Partial<FormRef>;
-export declare const FormDatabase: React.ForwardRefExoticComponent<FormDatabaseProps & React.RefAttributes<FormRef>>;
+declare function Form(props: FormProps): React.JSX.Element;
+export declare const FormDatabase: (props: FormDatabaseProps) => React.JSX.Element;
 export declare function FormModel({ model, children, ...formProps }: FormModelProps): React.JSX.Element | null;
-declare const _default: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<FormRef>>;
-export default _default;
+export default Form;

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

@@ -1,14 +1,13 @@
 import React from 'react';
-import 'tui-image-editor/dist/tui-image-editor.css';
-type ImageEditorProps = {
-    imageUrl: string;
+export type ImageEditorProps = {
+    src: string;
     title?: string;
     width?: number;
     height?: number;
-    modal?: boolean;
+    mode?: "modal" | "inline";
     onImageLoad?: () => void;
     onClose?: () => void;
     onSave?: (dataUrl: string) => void;
 };
-declare const ImageEditor: ({ imageUrl, title, width, height, modal, onImageLoad, onClose, onSave }: ImageEditorProps) => React.JSX.Element;
+declare const ImageEditor: ({ src, title, width, height, mode, onImageLoad, onClose, onSave }: ImageEditorProps) => React.JSX.Element;
 export default ImageEditor;

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

@@ -6,9 +6,9 @@ export interface MarkdownReaderProps {
     content: string;
     components?: MarkdownComponents;
     className?: string;
-    wrapClass?: string;
-    head?: PageMetadataState;
-    onNavigateInternal?: (href: string, event: React.MouseEvent<HTMLAnchorElement>) => void;
+    wrapperClassName?: string;
+    metadata?: PageMetadataState;
+    onInternalLinkClick?: (href: string, event: React.MouseEvent<HTMLAnchorElement>) => void;
 }
-export default function MarkdownReader({ content, components, className, wrapClass, head, onNavigateInternal, }: MarkdownReaderProps): React.JSX.Element;
+export default function MarkdownReader({ content, components, className, wrapperClassName, metadata, onInternalLinkClick, }: MarkdownReaderProps): React.JSX.Element;
 export {};