@juv/codego-react-ui 3.3.0 → 3.3.3

package/dist/index.d.ts

@@ -194,11 +194,19 @@ interface NotificationBannerProps {
 }
 declare function NotificationBanner({ variant, title, description, icon, closable, onClose, action, className, }: NotificationBannerProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Represents a single pagination link in server-side pagination
+ * @interface ServerPaginationLink
+ */
 interface ServerPaginationLink {
     page: number;
     url: string;
     active: boolean;
 }
+/**
+ * Server-side pagination metadata returned from the API
+ * @interface ServerPagination
+ */
 interface ServerPagination {
     first_page_url: string;
     last_page_url: string;
@@ -209,11 +217,20 @@ interface ServerPagination {
     total: number;
     links: ServerPaginationLink[];
 }
+/**
+ * Response structure from server-side table API
+ * @template T - The data type for table rows
+ * @extends ServerPagination
+ */
 interface ServerTableResponse<T> extends ServerPagination {
     current_page: number;
     data: T[];
     pagination?: ServerPagination;
 }
+/**
+ * Options for the useServerTable hook
+ * @interface UseServerTableOptions
+ */
 interface UseServerTableOptions {
     /** Base URL — page param appended automatically: `url?page=N` */
     url: string;
@@ -232,6 +249,11 @@ interface UseServerTableOptions {
      */
     columnOverrides?: Record<string, Partial<Column<any>>>;
 }
+/**
+ * Return type from the useServerTable hook
+ * @template T - The data type for table rows
+ * @interface UseServerTableReturn
+ */
 interface UseServerTableReturn<T> {
     data: T[];
     columns: Column<T>[];
@@ -243,24 +265,52 @@ interface UseServerTableReturn<T> {
     goToPage: (page: number) => void;
     reload: () => void;
 }
+/**
+ * Server-side pagination prop passed to the Table component
+ * @interface ServerPaginationProp
+ */
 interface ServerPaginationProp {
     pagination: ServerPagination;
     currentPage: number;
     goToPage: (page: number) => void;
 }
+/**
+ * Custom hook for fetching and managing server-side paginated table data.
+ * Supports Laravel encryption, auto-column derivation, and flexible pagination.
+ *
+ * @template T - The data type for table rows
+ * @param options - Configuration options for the server table
+ * @returns Object with data, columns, pagination state, loading, error, and control functions
+ *
+ * @example
+ * ```tsx
+ * const { data, columns, serverPagination, loading } = useServerTable({
+ *   url: "/api/users",
+ *   params: { sort: "name" },
+ * })
+ * ```
+ */
 declare function useServerTable<T extends Record<string, any>>({ url, params, encrypt, key, decryptPayloadLog, columnOverrides }: UseServerTableOptions): UseServerTableReturn<T>;
+/**
+ * Available field types for action forms (edit/view modals)
+ * @type {ActionFieldType}
+ */
 type ActionFieldType = "input" | "password" | "textarea" | "checkbox" | "toggle" | "select" | "radio" | "slider" | "tag-input" | "otp" | "combobox" | "color-picker" | "date-range" | "rich-text" | "file-upload" | "repeater";
+/**
+ * Configuration for a single field in action forms (edit/view modals)
+ * @interface ActionField
+ */
 interface ActionField {
     key: string;
     label: string;
     type?: ActionFieldType;
     /** HTML input type for type="input" (e.g. "email", "number", "password") */
     inputType?: string;
-    /** Options for type="select", "radio", "combobox" — string[] or { label, value }[] */
+    /** Options for type="select", "radio", "combobox" — string[], { label, value }[], or [label, value][] */
     options?: string[] | {
         label: string;
         value: string;
-    }[];
+    }[] | [string, string][];
     placeholder?: string;
     required?: boolean;
     /** Min value for type="slider" */
@@ -282,7 +332,10 @@ interface ActionField {
     /** Custom render — overrides built-in field renderer */
     render?: (value: any, onChange: (v: any) => void) => React.ReactNode;
 }
-/** Controls appearance of a default action button (view / edit / delete) */
+/**
+ * Configuration for customizing the appearance of action buttons (View/Edit/Delete)
+ * @interface ActionButtonConfig
+ */
 interface ActionButtonConfig {
     /** Button variant. Defaults: view→"outline", edit→"outline", delete→"danger" */
     variant?: "primary" | "secondary" | "outline" | "ghost" | "link" | "danger" | "success" | "destructive";
@@ -304,7 +357,11 @@ interface ActionButtonConfig {
     displayMode?: "icon" | "text" | "icon-text";
     className?: string;
 }
-/** Extra action button appended alongside the default view/edit/delete buttons */
+/**
+ * Configuration for extra custom action buttons added alongside default actions
+ * @template T - The data type for table rows
+ * @interface ExtraActionConfig
+ */
 interface ExtraActionConfig<T> {
     /** Unique key */
     key: string;
@@ -328,6 +385,11 @@ interface ExtraActionConfig<T> {
     className?: string;
     onClick: (item: T) => void;
 }
+/**
+ * Configuration for default View/Edit/Delete actions on table rows
+ * @template T - The data type for table rows
+ * @interface DefaultActionsConfig
+ */
 interface DefaultActionsConfig<T> {
     /**
      * Base URL used to build PUT and DELETE requests.
@@ -362,6 +424,10 @@ interface DefaultActionsConfig<T> {
     /** Extra action buttons rendered alongside view/edit/delete */
     extraActions?: ExtraActionConfig<T>[];
 }
+/**
+ * Configuration for success notifications after edit/delete operations
+ * @interface ActionSuccessNotif
+ */
 interface ActionSuccessNotif {
     /** "toast" uses the ToastProvider. "notification" renders an inline banner. Default "toast". */
     type?: "toast" | "notification";
@@ -382,6 +448,22 @@ interface ActionSuccessNotif {
     /** Extra action element rendered inside the notification */
     action?: React.ReactNode;
 }
+/**
+ * Predefined modal width options for View/Edit/Delete modals
+ * @constant {Object} MODAL_WIDTH
+ * @property {string} sm - Small: max-w-sm (384px)
+ * @property {string} md - Medium: max-w-md (448px)
+ * @property {string} lg - Large: max-w-lg (512px)
+ * @property {string} xl - Extra Large: max-w-xl (576px)
+ * @property {string} 2xl - 2X Large: max-w-2xl (672px)
+ * @property {string} 3xl - 3X Large: max-w-3xl (768px)
+ * @property {string} 4xl - 4X Large: max-w-4xl (896px)
+ * @property {string} 5xl - 5X Large: max-w-5xl (1024px)
+ * @property {string} 6xl - 6X Large: max-w-6xl (1152px)
+ * @property {string} 7xl - 7X Large: max-w-7xl (1280px)
+ * @property {string} screen - Screen width: max-w-screen-xl (1280px)
+ * @property {string} full - Full width: max-w-full
+ */
 declare const MODAL_WIDTH: {
     readonly sm: "max-w-sm";
     readonly md: "max-w-md";
@@ -397,6 +479,11 @@ declare const MODAL_WIDTH: {
     readonly full: "max-w-full";
 };
 type ModalWidth = keyof typeof MODAL_WIDTH;
+/**
+ * Column definition for the Table component
+ * @template T - The data type for table rows
+ * @interface Column
+ */
 interface Column<T> {
     key: keyof T | string;
     title: string;
@@ -414,6 +501,11 @@ interface Column<T> {
     /** Called when a cell value changes (select, toggle, color, checkbox) */
     onChange?: (item: T, value: any) => void;
 }
+/**
+ * Props for the Table component
+ * @template T - The data type for table rows
+ * @interface TableProps
+ */
 interface TableProps<T> {
     data: T[];
     columns: Column<T>[];
@@ -430,6 +522,33 @@ interface TableProps<T> {
     serverPagination?: ServerPaginationProp | null;
     className?: string;
 }
+/**
+ * Data table component with sorting, filtering, pagination, and CRUD actions
+ *
+ * @template T - The data type for table rows (must be a record with string keys)
+ * @param props - Table configuration including data, columns, and options
+ * @returns Rendered table with toolbar, pagination, and optional action modals
+ *
+ * @example
+ * ```tsx
+ * <Table
+ *   data={users}
+ *   columns={[
+ *     { key: "name", title: "Name", sortable: true },
+ *     { key: "status", type: "badge" },
+ *     { key: "active", type: "toggle", onChange: handleToggle },
+ *   ]}
+ *   searchable
+ *   pagination
+ *   selectable
+ *   onBulkDelete={handleBulkDelete}
+ *   defaultActions={{
+ *     baseUrl: "/api/users",
+ *     editForm: [{ key: "name", label: "Name", required: true }],
+ *   }}
+ * />
+ * ```
+ */
 declare function Table<T extends Record<string, any>>({ data, columns, searchable, searchPlaceholder, pagination, itemsPerPage, selectable, onBulkDelete, idKey, defaultActions, serverPagination, className, }: TableProps<T>): react_jsx_runtime.JSX.Element;
 
 type BulletinPriority = "low" | "medium" | "high" | "urgent";
@@ -844,13 +963,26 @@ interface MetricRowProps {
 }
 declare function MetricRow({ items, divided, className }: MetricRowProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Props for server-side pagination in DataGrid.
+ * Used when DataGrid is controlled by server-side data fetching.
+ */
 interface ServerDataGridProp {
+    /** Server pagination metadata from Laravel/API */
     pagination: ServerPagination;
+    /** Current active page number (1-based) */
     currentPage: number;
+    /** Function to navigate to a specific page */
     goToPage: (page: number) => void;
 }
+/**
+ * Options for the useServerDataGrid hook.
+ * Provides server-side data fetching with optional Laravel payload decryption.
+ */
 interface UseServerDataGridOptions {
+    /** API endpoint URL to fetch data from */
     url: string;
+    /** Query parameters to include in the request */
     params?: Record<string, string | number>;
     /** If true, the response is expected to be a Laravel-encrypted payload */
     encrypt?: boolean;
@@ -865,45 +997,142 @@ interface UseServerDataGridOptions {
      */
     columnOverrides?: Record<string, Partial<DataGridColumn<any>>>;
 }
+/**
+ * Return type for the useServerDataGrid hook.
+ * Contains all data and state needed to render a server-side DataGrid.
+ * @template T - The data item type
+ */
 interface UseServerDataGridReturn<T> {
+    /** Array of data items for the current page */
     data: T[];
+    /** Auto-derived column definitions from first data row */
     columns: DataGridColumn<T>[];
+    /** Current active page number */
     currentPage: number;
+    /** Server pagination metadata or null if not available */
     pagination: ServerPagination | null;
+    /** Formatted pagination prop for DataGrid component */
     serverPagination: ServerDataGridProp | null | undefined;
+    /** Whether data is currently being fetched */
     loading: boolean;
+    /** Error message if request failed, null otherwise */
     error: string | null;
+    /** Function to navigate to a specific page */
     goToPage: (page: number) => void;
+    /** Function to force reload current page data */
     reload: () => void;
 }
+/**
+ * Custom hook for server-side data fetching with DataGrid.
+ * Handles pagination, sorting, filtering, and optional Laravel payload decryption.
+ *
+ * @param options - Configuration options for the server data grid
+ * @returns Object containing data, columns, pagination state, and control functions
+ *
+ * @example
+ * ```tsx
+ * const { data, columns, loading, pagination, goToPage, reload } = useServerDataGrid<User>({
+ *   url: "/api/users",
+ *   params: { status: "active" },
+ *   encrypt: true,
+ *   key: import.meta.env["VITE_LARAVEL_KEY"],
+ * });
+ * ```
+ */
 declare function useServerDataGrid<T extends Record<string, any>>({ url, params, encrypt, key, decryptPayloadLog, columnOverrides }: UseServerDataGridOptions): UseServerDataGridReturn<T>;
+/**
+ * Sort direction for DataGrid columns.
+ * - "asc" - Ascending order
+ * - "desc" - Descending order
+ * - null - No sorting applied
+ */
 type SortDir = "asc" | "desc" | null;
+/**
+ * Column definition for DataGrid component.
+ * @template T - The data item type
+ */
 interface DataGridColumn<T> {
+    /** Unique key identifying this column (must match a property in T) */
     key: keyof T | string;
+    /** Column header display text or React node */
     header: React.ReactNode;
+    /** Custom render function for cell content */
     render?: (row: T, idx: number) => React.ReactNode;
+    /** Whether this column is sortable */
     sortable?: boolean;
+    /** Column width (e.g., "100px", "20%") */
     width?: string;
+    /** Text alignment within the column */
     align?: "left" | "center" | "right";
 }
+/**
+ * Props for the DataGrid component.
+ * @template T - The data item type
+ */
 interface DataGridProps<T> {
+    /** Column definitions for the grid */
     columns: DataGridColumn<T>[];
+    /** Array of data items to display */
     data: T[];
+    /** Property name or function to get unique row identifier */
     rowKey: keyof T | ((row: T) => string);
+    /** Array of column keys that should have filter inputs */
     filterable?: string[];
+    /** Whether rows can be selected via checkboxes */
     selectable?: boolean;
+    /** Controlled selected row keys (used with onSelectChange) */
     selected?: string[];
+    /** Callback when selection changes */
     onSelectChange?: (keys: string[]) => void;
+    /** Number of items per page (default: 10) */
     pageSize?: number;
+    /** Whether to show pagination controls */
     showPagination?: boolean;
+    /** Whether to show column visibility toggle */
     showColumnToggle?: boolean;
+    /** Whether to show loading skeleton */
     loading?: boolean;
+    /** Message shown when no data is available */
     emptyMessage?: string;
+    /** Additional CSS classes for the container */
     className?: string;
+    /** Callback when a row is clicked */
     onRowClick?: (row: T) => void;
+    /** Configuration for default row actions (view/edit/delete) */
     defaultActions?: DefaultActionsConfig<T>;
+    /** Server-side pagination prop (for controlled/server-fetched pagination) */
     serverPagination?: ServerDataGridProp | null;
 }
+/**
+ * DataGrid component - A powerful data table with sorting, filtering, pagination, and built-in actions.
+ *
+ * Supports both client-side and server-side pagination, column visibility toggling,
+ * row selection, and default CRUD actions (view/edit/delete) with modal forms.
+ *
+ * @param props - DataGridProps<T> containing columns, data, and configuration options
+ * @returns A fully-featured data grid React component
+ *
+ * @example
+ * ```tsx
+ * <DataGrid
+ *   columns={[
+ *     { key: "id", header: "ID", sortable: true },
+ *     { key: "name", header: "Name", sortable: true },
+ *     { key: "email", header: "Email" },
+ *   ]}
+ *   data={users}
+ *   rowKey="id"
+ *   filterable={["name", "email"]}
+ *   selectable
+ *   pageSize={25}
+ *   onRowClick={(row) => console.log(row)}
+ *   defaultActions={{
+ *     baseUrl: "/api/users",
+ *     viewForm: [{ key: "name", label: "Name" }, { key: "email", label: "Email" }],
+ *   }}
+ * />
+ * ```
+ */
 declare function DataGrid<T extends Record<string, unknown>>({ columns, data, rowKey, filterable, selectable, selected: controlledSelected, onSelectChange, pageSize, showPagination, showColumnToggle, loading, emptyMessage, className, onRowClick, defaultActions, serverPagination, }: DataGridProps<T>): react_jsx_runtime.JSX.Element;
 
 interface DatePickerProps {
@@ -1463,45 +1692,58 @@ interface PaginationProps {
 declare function Pagination({ page, total, pageSize, siblingCount, showFirstLast, showPageSize, pageSizeOptions, onPageChange, onPageSizeChange, className, }: PaginationProps): react_jsx_runtime.JSX.Element;
 
 interface PanelBrand {
-    /** Image URL shown as the project logo */
     image?: string;
-    /** Fallback icon when no image — any React element */
     icon?: React.ReactNode;
-    /** Project / app title shown when expanded */
     title?: React.ReactNode;
-    /** Extra content rendered to the right of title when expanded */
     trailing?: React.ReactNode;
 }
 interface PanelProfile {
-    /** Avatar image URL */
     image?: string;
-    /** Fallback icon when no image — any React element */
     icon?: React.ReactNode;
-    /** Full profile content rendered when expanded */
     content?: React.ReactNode;
 }
 interface PanelProps {
     sidebar?: React.ReactNode;
-    /** Structured brand header: shows image+title when expanded, image/icon only when collapsed */
     sidebarBrand?: PanelBrand;
-    /** Structured profile footer: shows full content when expanded, image/icon only when collapsed */
     sidebarProfile?: PanelProfile;
-    /** @deprecated use sidebarBrand */
     sidebarHeader?: React.ReactNode;
-    /** @deprecated use sidebarProfile */
     sidebarFooter?: React.ReactNode;
     sidebarWidth?: string;
     topbar?: React.ReactNode;
     topbarTrailing?: React.ReactNode;
     defaultCollapsed?: boolean;
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
     collapsible?: boolean;
     showThemeToggle?: boolean;
     defaultPage?: string;
+    currentPage?: string;
+    onPageChange?: (page: string) => void;
     height?: string;
     children?: React.ReactNode;
     className?: string;
-}
-declare function Panel({ sidebar, sidebarBrand, sidebarProfile, sidebarHeader, sidebarFooter, sidebarWidth, topbar, topbarTrailing, defaultCollapsed, collapsible, showThemeToggle, defaultPage, height, children, className, }: PanelProps): react_jsx_runtime.JSX.Element;
+    loading?: boolean;
+    emptyState?: React.ReactNode;
+    error?: string | null;
+    showGroupDividers?: boolean;
+    expandedGroups?: string[];
+    onGroupToggle?: (groupTitle: string, expanded: boolean) => void;
+    theme?: "light" | "dark" | "auto";
+    collapseIcon?: React.ReactNode;
+    expandIcon?: React.ReactNode;
+    meta?: Record<string, any>;
+    actions?: Record<string, () => void>;
+    keyboardNavigation?: boolean;
+    draggable?: boolean;
+    onSidebarReorder?: (items: React.ReactNode[]) => void;
+    animationDuration?: number;
+    animationEasing?: string;
+    sidebarTooltip?: (item: React.ReactNode) => React.ReactNode;
+    mobileBreakpoint?: number;
+    mobileCollapsed?: boolean;
+    onMobileCollapseChange?: (collapsed: boolean) => void;
+}
+declare function Panel({ sidebar, sidebarBrand, sidebarProfile, sidebarHeader, sidebarFooter, sidebarWidth, topbar, topbarTrailing, defaultCollapsed, collapsed: controlledCollapsed, onCollapsedChange, collapsible, showThemeToggle, defaultPage, currentPage: controlledPage, onPageChange, height, children, className, loading, emptyState, error, showGroupDividers, expandedGroups: controlledExpandedGroups, onGroupToggle, theme: themeProp, collapseIcon, expandIcon, meta, actions, keyboardNavigation, draggable, onSidebarReorder, animationDuration, animationEasing, sidebarTooltip, mobileBreakpoint, mobileCollapsed: controlledMobileCollapsed, onMobileCollapseChange, }: PanelProps): react_jsx_runtime.JSX.Element;
 declare function PanelSidebarItem({ icon: Icon, label, active, onClick, }: {
     icon?: React.ElementType;
     label: string;