@llmnative/react 0.1.1 → 1.1.0

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 {};

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

@@ -1,31 +1,99 @@
 import React from 'react';
-import { AIFetchConfig } from '../../providers/ai';
 import { PromptVariables } from '../../conf/Prompt';
+import { type AIProviderAdapter, type AIRequestOptions, type AIAttachment } from '../../providers/ai/AIProvider';
+import { RecordProps } from '../../providers/data/DataProvider';
+import { type EditorCommand } from '../ui/fields/ContextMenu';
 import { FormFieldProps } from './Form';
 export declare enum PromptMode {
-    EDITOR = "editor",
-    LIVE = "live"
+    EDIT = "edit",
+    RUN = "run"
 }
-type PromptOptions = AIFetchConfig & {
+export type PromptAction = {
+    key: string;
+    icon: string;
+    label?: string;
+    content?: React.ReactNode;
+};
+export type PromptStatusItem = 'tokensIn' | 'tokensOut' | 'contextPercent' | 'model' | 'duration' | {
+    key: string;
+    render: (stats: PromptRunStats) => React.ReactNode;
+};
+export type PromptRunStats = {
+    tokensIn: number;
+    tokensOut: number;
+    contextPercent: number | null;
+    model: string;
+    durationMs: number;
+    estimatedCost: number | null;
+};
+type PromptOptions = AIRequestOptions & {
     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;
+type PromptConfig = Partial<PromptOptions> & {
+    enabled?: boolean;
+};
+type OnRunPrompt = (prompt: string, options: AIRequestOptions, data?: PromptVariables) => Promise<string>;
+type PromptDefaultValue = {
+    value?: string;
+    enabled?: boolean;
+    role?: string;
+    language?: string;
+    voice?: string;
+    style?: string;
+    model?: string;
+    temperature?: number;
+};
+type RenderPlainFallback = (props: Omit<FormFieldProps, "defaultValue">) => React.ReactNode;
+type RenderAIUnavailable = (props: {
+    mode: PromptMode;
+    providerId?: string | null;
+    reason?: string;
+    configured: boolean;
+}) => React.ReactNode;
+interface PromptFieldBase {
+    name: string;
+    label?: string;
+    required?: boolean;
+    onChange?: FormFieldProps["onChange"];
+    before?: React.ReactNode;
+    after?: React.ReactNode;
+    wrapperClassName?: string;
+    className?: string;
+    minHeight?: number;
+    maxHeight?: number;
+}
+interface PromptWithAI extends PromptFieldBase {
+    defaultValue?: PromptDefaultValue;
+    renderAIUnavailable?: RenderAIUnavailable;
+}
+interface PromptEditorProps extends PromptWithAI {
+    value?: RecordProps & {
+        prompt?: PromptConfig;
+    };
+}
+interface PromptRunProps extends PromptWithAI {
+    value?: RecordProps & {
+        prompt?: PromptConfig;
     };
+    variables?: PromptVariables;
+    onRunPrompt?: OnRunPrompt;
+    renderFallback?: RenderPlainFallback;
+    commands?: EditorCommand[];
+    commandsTrigger?: string;
+    attachments?: boolean;
+    actions?: PromptAction[];
+    statusItems?: PromptStatusItem[];
 }
-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 {};
+type PromptEditBranch = PromptEditorProps & {
+    mode?: PromptMode.EDIT;
+};
+type PromptRunBranch = PromptRunProps & {
+    mode: PromptMode.RUN;
+};
+export type PromptProps = PromptEditBranch | PromptRunBranch;
+export declare const Prompt: ({ mode, ...props }: PromptProps) => React.JSX.Element;
+export declare const runPrompt: (options: PromptOptions, data?: PromptVariables, onRunPrompt?: OnRunPrompt, provider?: AIProviderAdapter, attachments?: AIAttachment[], messages?: {
+    noProvider?: string;
+    noResponse?: string;
+}) => Promise<string>;
+export default Prompt;

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

@@ -1,13 +1,14 @@
 import React from 'react';
 import { TabPosition } from '../ui/Tab';
 import { FieldOnChange } from './Form';
+import { RecordProps } from '../../providers/data/DataProvider';
 interface TabDynamicProps {
-    children: React.ReactNode | ((record: any) => React.ReactNode);
+    children: React.ReactNode | ((record: RecordProps) => React.ReactNode);
     name: string;
     onChange?: FieldOnChange;
-    onAdd?: (value: any[]) => void;
+    onAdd?: (value: RecordProps[]) => void;
     onRemove?: (index: number) => void;
-    value?: any[];
+    value?: RecordProps[];
     label?: string;
     min?: number;
     max?: number;

package/dist/types/src/components/widgets/form-controller.d.ts

@@ -0,0 +1,42 @@
+import React from 'react';
+import type { RecordProps } from '../../providers/data/DataProvider';
+export type FormDraftStatus = 'restore' | 'restored' | null;
+export type FormActionEvent = {
+    preventDefault?: () => void;
+};
+export type FormControllerState = {
+    record?: RecordProps;
+    isNewRecord: boolean;
+    isDirty: boolean;
+    canSave: boolean;
+    canDelete: boolean;
+    isSaving: boolean;
+    isDeleting: boolean;
+    saveDisabled: boolean;
+    deleteDisabled: boolean;
+    hasDraft: boolean;
+    draftStatus: FormDraftStatus;
+    errors: Record<string, string>;
+    hasErrors: boolean;
+};
+export type FormControllerActions = {
+    save: (event?: FormActionEvent) => Promise<boolean>;
+    delete: (event?: FormActionEvent) => Promise<boolean>;
+    reset: () => void;
+    restoreDraft: () => void;
+    discardDraft: () => void;
+};
+export type FormController = FormControllerState & FormControllerActions;
+type FormControllerStore = {
+    bindActions: (actions: Partial<FormControllerActions>) => void;
+    getControllerSnapshot: () => FormController;
+    getState: () => FormControllerState;
+    setState: (nextState: Partial<FormControllerState>) => void;
+    subscribe: (listener: () => void) => () => void;
+};
+export declare function getFormControllerStore(controller: FormController): FormControllerStore;
+export declare function resetFormController(controller: FormController): void;
+export declare const FormControllerContext: React.Context<FormController | null>;
+export declare function useFormController(controller?: FormController): FormController;
+export declare function useFormActions(): FormController;
+export {};

package/dist/types/src/components/widgets/grid-core/GridCore.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
 import { type RecordProps } from "../../../providers/data/DataProvider";
 import { type GridCoreProps } from "./types";
-declare function GridCore<TRecord extends RecordProps>({ records, recordId, sourcePath, columns, actions, form, routeSync, header, footer, layout, sticky, wrapClass, loading, title, sortable, pagination, selection, selectedKeys, defaultSelectedKeys, onSelectionChange, onClickRow, reorderable, onReorder, groupBy, onSave, onDelete, onAfterAction, createRecordKey, audit, transformRecords, }: GridCoreProps<TRecord>): React.JSX.Element;
+declare function GridCore<TRecord extends RecordProps>({ records, recordId, sourcePath, columns, actions, form, editDeepLink, header, footer, view, sticky, wrapperClassName, loading, title, before, after, sortable, pagination, selection, onRowClick, reorderable, onReorder, groupBy, onSave, onDelete, onComplete, audit, onLoad, }: GridCoreProps<TRecord>): React.JSX.Element;
 export default GridCore;

package/dist/types/src/components/widgets/grid-core/GridDB.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
 import { type RecordProps } from "../../../providers/data/DataProvider";
 import { type GridDBProps } from "./types";
-declare function GridDB<TRecord extends RecordProps = RecordProps>({ path, where, order, fieldMap, onLoad, recordId, ...rest }: GridDBProps<TRecord>): React.JSX.Element;
+declare function GridDB<TRecord extends RecordProps = RecordProps>({ path, fromUrl, where, order, fieldMap, recordId, ...rest }: GridDBProps<TRecord>): React.JSX.Element;
 export default GridDB;

package/dist/types/src/components/widgets/grid-core/GridGalleryView.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
 import { type RecordProps } from "../../../providers/data/DataProvider";
 import { type GridGalleryViewProps } from "./types";
-declare function GridGalleryView<TRecord extends RecordProps>({ records, recordId, sortable, pagination, selection, selectedKeys, onSelectionChange, onClickRow, groupBy, wrapClass, }: GridGalleryViewProps<TRecord>): React.JSX.Element;
+declare function GridGalleryView<TRecord extends RecordProps>({ records, recordId, sortable, pagination, selection, selectedKeys, onSelectionChange, onRowClick, groupBy, wrapperClassName, before, after, }: GridGalleryViewProps<TRecord>): React.JSX.Element;
 export default GridGalleryView;

package/dist/types/src/components/widgets/grid-core/GridTableView.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
 import { type RecordProps } from "../../../providers/data/DataProvider";
 import { type GridTableViewProps } from "./types";
-declare function GridTableView<TRecord extends RecordProps>({ records, recordId, columns, runAction, sortable, pagination, selection, selectedKeys, onSelectionChange, onClickRow, reorderable, onReorder, activeKey, wrapClass, }: GridTableViewProps<TRecord>): React.JSX.Element;
+declare function GridTableView<TRecord extends RecordProps>({ records, recordId, columns, runAction, sortable, pagination, selection, selectedKeys, onSelectionChange, onRowClick, reorderable, onReorder, activeKey, groupBy, wrapperClassName, before, after, }: GridTableViewProps<TRecord>): React.JSX.Element;
 export default GridTableView;

package/dist/types/src/components/widgets/grid-core/types.d.ts

@@ -14,11 +14,21 @@ export type GridCellContext<TRecord> = {
     rowIndex: number;
     runAction: (actionKey: string) => void;
 };
+/**
+ * Column definition for `<Grid>` / `<Table>`.
+ * `render` accepts a built-in format string ("date", "badge", …) or a custom
+ * render function that receives the full cell context.
+ */
 export type GridColumn<TRecord> = {
+    /** Record field to read. Accepts dot-notation strings for nested fields. */
     key: keyof TRecord | string;
+    /** Column header label. */
     label: string;
+    /** Enable click-to-sort on this column. */
     sortable?: boolean;
+    /** Extra CSS classes on the `<td>` / cell wrapper. */
     className?: string;
+    /** Built-in format name or custom render function. */
     render?: GridFormat | ((ctx: GridCellContext<TRecord>) => React.ReactNode);
 };
 export type GridSelectionState<TRecord> = {
@@ -28,6 +38,11 @@ export type GridSelectionState<TRecord> = {
     clear: () => void;
 };
 export type GridSelectionChangeHandler<TRecord> = (selection: GridSelectionState<TRecord>) => void;
+export type GridSelectionConfig<TRecord> = {
+    mode: "single" | "multiple";
+    defaultKeys?: string[];
+    onChange?: GridSelectionChangeHandler<TRecord>;
+};
 export type GridReorderMeta<TRecord> = {
     fromIndex: number;
     toIndex: number;
@@ -60,7 +75,7 @@ export type GridModalAction<TRecord> = {
     title?: React.ReactNode | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
     size?: "sm" | "md" | "lg" | "xl" | "fullscreen";
     position?: "center" | "top" | "left" | "right" | "bottom";
-    buttonFullscreen?: boolean;
+    allowFullscreen?: boolean;
     header?: React.ReactNode | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
     body?: React.ReactNode | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
     footer?: React.ReactNode | false | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
@@ -98,7 +113,7 @@ export type GridDeleteAction<TRecord> = {
     title?: React.ReactNode | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
     size?: "sm" | "md" | "lg" | "xl" | "fullscreen";
     position?: "center" | "top" | "left" | "right" | "bottom";
-    buttonFullscreen?: boolean;
+    allowFullscreen?: boolean;
     header?: React.ReactNode | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
     body?: React.ReactNode | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
     footer?: React.ReactNode | false | ((ctx: GridModalActionContext<TRecord>) => React.ReactNode);
@@ -134,44 +149,69 @@ export type GridAfterActionArgs<TRecord> = {
     action: "create" | "update" | "delete";
 };
 export type GridAfterActionHandler<TRecord> = (args: GridAfterActionArgs<TRecord>) => Promise<boolean>;
-export type GridRouteSync = {
-    edit?: boolean;
-};
+/** Visual / layout props for `<Grid>`. */
 export type GridPresentation = {
-    layout?: GridLayout;
+    /** Display mode: `"table"` (default) or `"gallery"` card layout. */
+    view?: GridLayout;
+    /** Stick the header (`"top"`) or footer (`"bottom"`) while scrolling. */
     sticky?: GridSticky;
-    wrapClass?: string;
+    /** CSS classes on the outermost wrapper element. */
+    wrapperClassName?: string;
+    /** Show a loading skeleton instead of rows. */
     loading?: boolean;
+    /** Title rendered in the Grid header area. */
     title?: React.ReactNode;
+    /** Content rendered before the Grid. */
+    before?: React.ReactNode;
+    /** Content rendered after the Grid. */
+    after?: React.ReactNode;
 };
+/** Interaction / behaviour props for `<Grid>`. */
 export type GridBehavior<TRecord> = {
+    /** Enable global sorting. Pass an `OrderConfig` to set a default sort. */
     sortable?: boolean | OrderConfig;
+    /** Pagination config. `{ limit: 20 }` is the common form. */
     pagination?: PaginationParams;
-    selection?: GridSelectionMode;
-    selectedKeys?: string[];
-    defaultSelectedKeys?: string[];
-    onSelectionChange?: GridSelectionChangeHandler<TRecord>;
-    onClickRow?: (record: TRecord) => void;
+    /** Row selection: `false` (off), `"single"`, `"multiple"`, or a full `GridSelectionConfig`. */
+    selection?: false | "single" | "multiple" | GridSelectionConfig<TRecord>;
+    /** Called when the user clicks a row (outside an action button). */
+    onRowClick?: (record: TRecord) => void;
+    /** Allow drag-and-drop row reordering. */
     reorderable?: boolean;
+    /** Called after a drag reorder with the new record order and move metadata. */
     onReorder?: GridReorderHandler<TRecord>;
+    /** Group rows by a field or array of fields. */
     groupBy?: keyof TRecord | string | Array<keyof TRecord | string>;
 };
+/** Data-mutation hooks for `<Grid>`. */
 export type GridPersistence<TRecord> = {
+    /** Called before saving a record. Return a custom storage path or `undefined`. */
     onSave?: GridMutationSaveHandler<TRecord>;
+    /** Called before deleting a record. Return a path override or `undefined`. */
     onDelete?: GridMutationDeleteHandler<TRecord>;
-    onAfterAction?: GridAfterActionHandler<TRecord>;
-    createRecordKey?: (record: TRecord) => string;
+    /** Called after create/update/delete. Return `false` to suppress default navigation. */
+    onComplete?: GridAfterActionHandler<TRecord>;
+    /** Automatically write `createdAt` / `updatedAt` timestamps on every mutation. */
     audit?: boolean;
 };
-export type GridTransform<TRecord> = {
-    transformRecords?: (records: TRecord[]) => TRecord[] | Promise<TRecord[]>;
-};
-export type GridBaseProps<TRecord> = GridPresentation & GridBehavior<TRecord> & GridPersistence<TRecord> & GridTransform<TRecord> & {
+/**
+ * Full prop surface shared by all `<Grid>` variants.
+ * Combines presentation, behaviour, and persistence with a few top-level hooks.
+ */
+export type GridBaseProps<TRecord> = GridPresentation & GridBehavior<TRecord> & GridPersistence<TRecord> & {
+    /** Transform the record array after loading (filter, sort, enrich). */
+    onLoad?: (records: TRecord[]) => TRecord[] | Promise<TRecord[]>;
+    /** Column definitions. Omit to auto-generate from record keys. */
     columns?: GridColumn<TRecord>[];
+    /** Enable built-in `"add"/"edit"/"delete"` shortcuts, or provide custom `GridAction` objects. */
     actions?: GridActions<TRecord>;
+    /** Form element or factory rendered inside the add/edit modal. */
     form?: React.ReactElement | ((ctx: GridFormContext<TRecord>) => React.ReactNode);
-    routeSync?: GridRouteSync;
+    /** Sync the edit modal state to the URL hash (enables direct links). */
+    editDeepLink?: boolean;
+    /** Content rendered in the Grid header bar. Receives selection context. */
     header?: React.ReactNode | ((ctx: GridHeaderContext<TRecord>) => React.ReactNode);
+    /** Content rendered in the Grid footer bar. Receives selection context. */
     footer?: React.ReactNode | ((ctx: GridFooterContext<TRecord>) => React.ReactNode);
 };
 export type GridCoreProps<TRecord extends RecordProps> = GridBaseProps<TRecord> & {
@@ -183,12 +223,17 @@ export type GridArrayProps<TRecord extends RecordProps> = GridBaseProps<TRecord>
     records: TRecord[];
     recordId: GridRecordKey<TRecord>;
 };
-export type GridDBQuery = Pick<DatabaseOptions, "where" | "order" | "fieldMap" | "onLoad">;
-export type GridDBPath = string | "fromUrl";
-export type GridDBProps<TRecord extends RecordProps = RecordProps> = GridBaseProps<TRecord> & GridDBQuery & {
+export type GridDBQuery = Pick<DatabaseOptions, "where" | "order" | "fieldMap">;
+export type GridDBPath = string;
+export type GridDBProps<TRecord extends RecordProps = RecordProps> = GridBaseProps<TRecord> & GridDBQuery & ({
+    fromUrl: true;
+    path?: never;
+    recordId?: GridRecordKey<TRecord>;
+} | {
+    fromUrl?: false;
     path: GridDBPath;
     recordId?: GridRecordKey<TRecord>;
-};
+});
 export type GridGatewayArrayProps<TRecord extends RecordProps> = GridArrayProps<TRecord> & {
     path?: never;
 };
@@ -206,11 +251,14 @@ export type GridTableViewProps<TRecord extends RecordProps> = {
     selection?: GridSelectionMode;
     selectedKeys?: string[];
     onSelectionChange?: GridSelectionChangeHandler<TRecord>;
-    onClickRow?: (record: TRecord) => void;
+    onRowClick?: (record: TRecord) => void;
     reorderable?: boolean;
     onReorder?: GridReorderHandler<TRecord>;
     activeKey?: string | null;
-    wrapClass?: string;
+    groupBy?: keyof TRecord | string | Array<keyof TRecord | string>;
+    wrapperClassName?: string;
+    before?: React.ReactNode;
+    after?: React.ReactNode;
 };
 export type GridGalleryViewProps<TRecord extends RecordProps> = {
     records: TRecord[];
@@ -220,8 +268,10 @@ export type GridGalleryViewProps<TRecord extends RecordProps> = {
     selection?: GridSelectionMode;
     selectedKeys?: string[];
     onSelectionChange?: GridSelectionChangeHandler<TRecord>;
-    onClickRow?: (record: TRecord) => void;
+    onRowClick?: (record: TRecord) => void;
     groupBy?: keyof TRecord | string | Array<keyof TRecord | string>;
-    wrapClass?: string;
+    wrapperClassName?: string;
+    before?: React.ReactNode;
+    after?: React.ReactNode;
 };
 export {};