@gnwebsoft/ui 3.0.1 → 3.0.4

package/dist/components/index.d.ts

@@ -1,103 +1,752 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SxProps, ButtonTypeMap } from '@mui/material';
-import { PropsWithChildren, ReactNode } from 'react';
-import { OverrideProps } from '@mui/material/OverridableComponent';
+import { SxProps, ButtonProps } from '@mui/material';
+import React$1, { PropsWithChildren, ReactNode } from 'react';
 
-type ClearButtonProps = {
+/**
+ * Props for the ClearButton component.
+ *
+ * @public
+ */
+interface ClearButtonProps {
+    /**
+     * Indicates if a form or operation is currently being submitted.
+     * When true, the button is disabled to prevent multiple clear actions.
+     */
     isSubmitting: boolean;
+    /**
+     * Callback function executed when the clear button is clicked.
+     * Should handle the clearing logic (e.g., form reset, data clearing).
+     */
     handleClear: () => void;
+    /**
+     * Optional MUI sx prop for custom styling.
+     * @example { mt: 2, color: 'warning.main' }
+     */
     sx?: SxProps;
+    /**
+     * Optional localStorage key to remove when clearing.
+     * If provided, the corresponding localStorage item will be removed on click.
+     * @example "user-preferences" or "form-data"
+     */
     storeKey?: string;
-};
+}
+/**
+ * Standardized clear button component with localStorage integration.
+ *
+ * This component provides a consistent clear button implementation that handles
+ * both callback execution and optional localStorage cleanup. It automatically
+ * disables during form submissions and can clear stored data when needed.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <ClearButton
+ *   isSubmitting={isLoading}
+ *   handleClear={() => form.reset()}
+ * />
+ * ```
+ *
+ * @example
+ * With localStorage cleanup:
+ * ```tsx
+ * <ClearButton
+ *   isSubmitting={form.formState.isSubmitting}
+ *   handleClear={() => setFilters({})}
+ *   storeKey="user-filters"
+ * />
+ * ```
+ *
+ * @param props - Component props for clear button configuration
+ * @returns MUI Button component configured as a clear button
+ *
+ * @public
+ */
 declare const ClearButton: ({ isSubmitting, handleClear, sx, storeKey, }: ClearButtonProps) => react_jsx_runtime.JSX.Element;
 
-type FilterButtonProps = {
+/**
+ * Props for the FilterButton component.
+ *
+ * @public
+ */
+interface FilterButtonProps {
+    /**
+     * Indicates if a filter operation is currently being processed.
+     * When true, shows loading spinner and disables the button.
+     */
     isSubmitting: boolean;
+    /**
+     * Controls button visibility and enabled state.
+     * When false, the button is disabled.
+     * @defaultValue true
+     */
     show?: boolean;
+    /**
+     * Custom text to display on the button.
+     * @defaultValue "Filter"
+     * @example "Apply Filters" or "Search"
+     */
     title?: string;
+    /**
+     * Custom icon to display instead of the default filter icon.
+     * @example <SearchIcon />
+     */
     icon?: React.ReactNode;
+    /**
+     * Optional MUI sx prop for custom button styling.
+     * @example { mt: 2, minWidth: 120 }
+     */
     sx?: SxProps;
+    /**
+     * Optional MUI sx prop for custom icon styling.
+     * @example { color: 'primary.main', fontSize: 18 }
+     */
     iconSx?: SxProps;
-};
+}
+/**
+ * Filter button component with loading states and customizable appearance.
+ *
+ * This component provides a standardized filter/submit button with integrated loading
+ * states, icon support, and badge styling. It's designed for use in filter forms
+ * and search interfaces where users need to apply filtering criteria.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <FilterButton
+ *   isSubmitting={isLoading}
+ *   show={hasFilters}
+ * />
+ * ```
+ *
+ * @example
+ * Custom title and icon:
+ * ```tsx
+ * <FilterButton
+ *   isSubmitting={form.formState.isSubmitting}
+ *   title="Apply Search"
+ *   icon={<SearchIcon />}
+ *   show={true}
+ * />
+ * ```
+ *
+ * @example
+ * With custom styling:
+ * ```tsx
+ * <FilterButton
+ *   isSubmitting={isProcessing}
+ *   title="Filter Results"
+ *   sx={{ minWidth: 150, mt: 2 }}
+ *   iconSx={{ fontSize: 20 }}
+ * />
+ * ```
+ *
+ * @param props - Component props for filter button configuration
+ * @returns MUI LoadingButton component configured as a filter button
+ *
+ * @public
+ */
 declare const FilterButton: ({ isSubmitting, show, title, icon, sx, iconSx, }: FilterButtonProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Props for the FilterWrapper component.
+ *
+ * @public
+ */
 type FilterWrapperProps = PropsWithChildren<{
+    /**
+     * Title text displayed in the card header.
+     * @defaultValue "Filter"
+     * @example "Search Criteria" or "Advanced Filters"
+     */
     title?: string;
+    /**
+     * Number of active filters to display in the header.
+     * Only shown when showCount is true.
+     * @example 3 for "Filter (3)"
+     */
     filterCount?: number;
+    /**
+     * Optional MUI sx prop for custom card styling.
+     * @example { mt: 2, boxShadow: 2 }
+     */
     cardSx?: SxProps;
+    /**
+     * Optional MUI sx prop for custom title text styling.
+     * @example { fontSize: 18, fontWeight: 'bold' }
+     */
     textSx?: SxProps;
+    /**
+     * Custom icon to display instead of the default search icon.
+     * @example <FilterListIcon />
+     */
     icon?: ReactNode;
+    /**
+     * Optional MUI sx prop for custom icon styling.
+     * @example { color: 'secondary.main', fontSize: 24 }
+     */
     iconSx?: SxProps;
+    /**
+     * Whether to display the filter count in the header.
+     * @defaultValue false
+     */
     showCount?: boolean;
 }>;
+/**
+ * Card-based wrapper component for organizing filter controls and form elements.
+ *
+ * This component provides a consistent layout for filter interfaces with a header,
+ * optional filter count display, and a grid-based content area. It's designed to
+ * contain form controls and filter elements in a visually organized manner.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <FilterWrapper>
+ *   <Grid item xs={12} md={6}>
+ *     <TextField label="Search" />
+ *   </Grid>
+ *   <Grid item xs={12} md={6}>
+ *     <Select label="Category" />
+ *   </Grid>
+ * </FilterWrapper>
+ * ```
+ *
+ * @example
+ * With custom title and count:
+ * ```tsx
+ * <FilterWrapper
+ *   title="Advanced Search"
+ *   filterCount={activeFilters.length}
+ *   showCount={true}
+ * >
+ *   {filterControls}
+ * </FilterWrapper>
+ * ```
+ *
+ * @example
+ * With custom styling:
+ * ```tsx
+ * <FilterWrapper
+ *   title="Product Filters"
+ *   icon={<FilterListIcon />}
+ *   cardSx={{ mt: 3, borderRadius: 2 }}
+ *   textSx={{ color: 'secondary.main' }}
+ * >
+ *   {children}
+ * </FilterWrapper>
+ * ```
+ *
+ * @param props - Component props including children and styling options
+ * @returns MUI Card component with structured filter layout
+ *
+ * @public
+ */
 declare const FilterWrapper: ({ children, title, filterCount, cardSx, textSx, icon, iconSx, showCount, }: FilterWrapperProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Props for the FormWrapper component.
+ *
+ * @public
+ */
 type FormWrapper = PropsWithChildren<{
+    /**
+     * Title text displayed in the form header.
+     * @example "Create User" or "Edit Profile"
+     */
     title: string;
+    /**
+     * Indicates if the form is in edit mode (currently unused in implementation).
+     * @deprecated This prop is defined but not used in the component logic
+     */
     editMode?: boolean;
+    /**
+     * Custom icon to display in the header next to the title.
+     * @example <PersonIcon /> or <EditIcon />
+     */
     icon?: ReactNode;
+    /**
+     * Optional MUI sx prop for custom card styling.
+     * @example { mt: 2, maxWidth: 600 }
+     */
     cardSx?: SxProps;
+    /**
+     * Optional MUI sx prop for custom title text styling.
+     * @example { fontSize: 20, fontWeight: 'bold' }
+     */
     textSx?: SxProps;
+    /**
+     * Action button or element to display in the header (e.g., save, close).
+     * @example <Button>Save</Button> or <IconButton><CloseIcon /></IconButton>
+     */
     actionButton?: ReactNode;
 }>;
+/**
+ * Card-based wrapper component for organizing form elements with header and actions.
+ *
+ * This component provides a structured layout for forms with a title header,
+ * optional icon, action buttons, and a grid-based content area. It creates
+ * a consistent visual structure for form interfaces throughout the application.
+ *
+ * @example
+ * Basic form wrapper:
+ * ```tsx
+ * <FormWrapper title="User Information">
+ *   <Grid item xs={12} md={6}>
+ *     <TextField label="First Name" />
+ *   </Grid>
+ *   <Grid item xs={12} md={6}>
+ *     <TextField label="Last Name" />
+ *   </Grid>
+ * </FormWrapper>
+ * ```
+ *
+ * @example
+ * With icon and action button:
+ * ```tsx
+ * <FormWrapper
+ *   title="Edit Profile"
+ *   icon={<PersonIcon />}
+ *   actionButton={
+ *     <Button variant="contained" type="submit">
+ *       Save Changes
+ *     </Button>
+ *   }
+ * >
+ *   {formFields}
+ * </FormWrapper>
+ * ```
+ *
+ * @param props - Component props including children and layout options
+ * @returns MUI Card component with structured form layout
+ *
+ * @public
+ */
 declare const FormWrapper: ({ children, title, editMode, cardSx, textSx, icon, actionButton, }: FormWrapper) => react_jsx_runtime.JSX.Element;
 
-type LabelTextProps = {
+/**
+ * Props for the LabelText component.
+ *
+ * @public
+ */
+interface LabelTextProps {
+    /**
+     * Label text to display on the left side.
+     * @example "Name" or "Email Address"
+     */
     label: string;
+    /**
+     * Value content to display on the right side.
+     * Can be text, numbers, or React elements.
+     * @example "John Doe" or <Link>View Details</Link>
+     */
     value: React.ReactNode;
+    /**
+     * Custom grid sizing for label and value sections.
+     * @defaultValue { labelSize: { xs: 6, sm: 6, md: 6 }, valueSize: { xs: 12, sm: 6, md: 6 } }
+     */
     gridSize?: {
+        /** Grid size configuration for the label section */
         labelSize: {
             xs: number;
             sm: number;
             md: number;
         };
+        /** Grid size configuration for the value section */
         valueSize: {
             xs: number;
             sm: number;
             md: number;
         };
     };
+    /**
+     * Grid size configuration for the entire container.
+     * @defaultValue { xs: 12, sm: 6, md: 6 }
+     */
     containerSize?: {
         xs: number;
         sm: number;
         md: number;
     };
+    /**
+     * Optional MUI sx prop for custom label styling.
+     * @example { fontWeight: 'bold', color: 'primary.main' }
+     */
     labelSx?: SxProps;
+    /**
+     * Optional MUI sx prop for custom value styling.
+     * @example { color: 'text.secondary', fontStyle: 'italic' }
+     */
     valueSx?: SxProps;
-};
+}
+/**
+ * Responsive label-value display component with hover effects and text truncation.
+ *
+ * This component creates a consistent label-value pair layout that adapts to different
+ * screen sizes. It includes hover effects, text truncation with tooltips, and
+ * customizable grid sizing for flexible layouts.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <LabelText
+ *   label="Full Name"
+ *   value="John Doe"
+ * />
+ * ```
+ *
+ * @example
+ * With React element value:
+ * ```tsx
+ * <LabelText
+ *   label="Profile"
+ *   value={<Link href="/profile">View Profile</Link>}
+ * />
+ * ```
+ *
+ * @example
+ * Custom grid sizing:
+ * ```tsx
+ * <LabelText
+ *   label="Description"
+ *   value={longDescription}
+ *   gridSize={{
+ *     labelSize: { xs: 12, sm: 3, md: 2 },
+ *     valueSize: { xs: 12, sm: 9, md: 10 }
+ *   }}
+ *   containerSize={{ xs: 12, sm: 12, md: 12 }}
+ * />
+ * ```
+ *
+ * @param props - Component props for label-value configuration
+ * @returns Grid-based layout with label and value sections
+ *
+ * @public
+ */
 declare const LabelText: ({ label, value, gridSize, containerSize, labelSx, valueSx, }: LabelTextProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Props for the ListWrapper component.
+ *
+ * @public
+ */
 type ListWrapperProps = PropsWithChildren<{
+    /**
+     * Title text displayed in the card header.
+     * @defaultValue "List"
+     * @example "User List" or "Product Catalog"
+     */
     title?: string;
+    /**
+     * Number of items to display in the header count.
+     * Only shown when showCount is true.
+     * @example 25 for "List (25)"
+     */
     count?: number;
+    /**
+     * Controls whether the entire component is rendered.
+     * When false, returns an empty fragment.
+     * @defaultValue true
+     */
     show?: boolean;
+    /**
+     * Action button or element to display in the header (e.g., add, export).
+     * @example <Button>Add New</Button> or <IconButton><MoreVertIcon /></IconButton>
+     */
     actionButton?: ReactNode;
+    /**
+     * Optional MUI sx prop for custom card styling.
+     * @example { mt: 2, boxShadow: 3 }
+     */
     cardSx?: SxProps;
+    /**
+     * Optional MUI sx prop for custom title text styling.
+     * @example { fontSize: 18, color: 'secondary.main' }
+     */
     textSx?: SxProps;
+    /**
+     * Custom icon to display instead of the default search icon.
+     * @example <ListIcon /> or <TableRowsIcon />
+     */
     icon?: ReactNode;
+    /**
+     * Whether to display the count in the header.
+     * @defaultValue true
+     */
     showCount?: boolean;
+    /**
+     * Optional MUI sx prop for custom icon styling.
+     * @example { color: 'primary.main', fontSize: 28 }
+     */
     iconSx?: SxProps;
 }>;
+/**
+ * Card-based wrapper component for organizing list content with header and actions.
+ *
+ * This component provides a structured layout for displaying lists of data with
+ * a title header, optional item count, action buttons, and a grid-based content area.
+ * It includes conditional rendering and consistent styling across list interfaces.
+ *
+ * @example
+ * Basic list wrapper:
+ * ```tsx
+ * <ListWrapper title="Users" count={users.length}>
+ *   <Grid item xs={12}>
+ *     <DataGrid rows={users} columns={columns} />
+ *   </Grid>
+ * </ListWrapper>
+ * ```
+ *
+ * @example
+ * With action button and custom icon:
+ * ```tsx
+ * <ListWrapper
+ *   title="Products"
+ *   count={products.length}
+ *   icon={<InventoryIcon />}
+ *   actionButton={
+ *     <Button variant="contained" onClick={addProduct}>
+ *       Add Product
+ *     </Button>
+ *   }
+ * >
+ *   {productList}
+ * </ListWrapper>
+ * ```
+ *
+ * @example
+ * Conditional rendering:
+ * ```tsx
+ * <ListWrapper
+ *   title="Search Results"
+ *   count={searchResults.length}
+ *   show={hasSearched}
+ *   showCount={searchResults.length > 0}
+ * >
+ *   {searchResultItems}
+ * </ListWrapper>
+ * ```
+ *
+ * @param props - Component props including children and layout options
+ * @returns MUI Card component with structured list layout, or empty fragment if show is false
+ *
+ * @public
+ */
 declare const ListWrapper: ({ children, title, count, show, actionButton, cardSx, textSx, icon, iconSx, showCount, }: ListWrapperProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Pre-configured toolbar component for MUI DataGrid with essential tools.
+ *
+ * This component provides a ready-to-use toolbar for MUI DataGrid components
+ * that includes quick filtering, column management, advanced filtering, and
+ * data export capabilities. The quick filter input is styled with custom
+ * border radius and padding for a polished appearance.
+ *
+ * Features included:
+ * - Quick filter search input (left-aligned)
+ * - Column visibility toggle button
+ * - Advanced filter button
+ * - Data export button (CSV, Excel, etc.)
+ *
+ * @example
+ * Basic usage with DataGrid:
+ * ```tsx
+ * <DataGrid
+ *   rows={data}
+ *   columns={columns}
+ *   slots={{
+ *     toolbar: SimpleToolbar
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * In a custom grid setup:
+ * ```tsx
+ * <Box>
+ *   <SimpleToolbar />
+ *   <DataGrid
+ *     rows={filteredData}
+ *     columns={visibleColumns}
+ *     hideFooter
+ *   />
+ * </Box>
+ * ```
+ *
+ * @returns GridToolbarContainer with pre-configured toolbar elements
+ *
+ * @public
+ */
 declare const SimpleToolbar: () => react_jsx_runtime.JSX.Element;
 
-type SimpleButtonProps<RootComponent extends React.ElementType = ButtonTypeMap["defaultComponent"], AdditionalProps = {}> = OverrideProps<ButtonTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
-    component?: React.ElementType;
+/**
+ * Props for the SimpleButton component.
+ *
+ * @public
+ */
+interface SimpleButtonProps extends ButtonProps {
+    /**
+     * Controls button visibility. When false, the component returns null.
+     * @defaultValue true
+     */
     show?: boolean;
-};
-declare const SimpleButton: (props: SimpleButtonProps) => react_jsx_runtime.JSX.Element;
+    /**
+     * Loading state with spinner. When true, shows a loading spinner and disables the button.
+     * @defaultValue false
+     */
+    loading?: boolean;
+    /**
+     * Test identifier for testing frameworks.
+     * @example "submit-button"
+     */
+    'data-testid'?: string;
+    /**
+     * Custom text to display when loading is true. If not provided, original children are shown.
+     * @example "Saving..."
+     */
+    loadingText?: string;
+}
+/**
+ * Enhanced MUI Button component with loading states and conditional rendering.
+ *
+ * This component extends the standard MUI Button with additional features:
+ * - Loading state with spinner
+ * - Conditional rendering based on show prop
+ * - Automatic disabling during loading
+ * - Custom loading text support
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <SimpleButton variant="contained" color="primary">
+ *   Click Me
+ * </SimpleButton>
+ * ```
+ *
+ * @example
+ * With loading state:
+ * ```tsx
+ * <SimpleButton
+ *   loading={isSubmitting}
+ *   loadingText="Saving..."
+ *   variant="contained"
+ * >
+ *   Save Changes
+ * </SimpleButton>
+ * ```
+ *
+ * @example
+ * Conditional rendering:
+ * ```tsx
+ * <SimpleButton
+ *   show={hasPermission}
+ *   variant="outlined"
+ * >
+ *   Admin Action
+ * </SimpleButton>
+ * ```
+ *
+ * @param props - Component props extending MUI ButtonProps
+ * @param ref - Forwarded ref to the underlying button element
+ * @returns JSX element or null if show is false
+ *
+ * @public
+ */
+declare const SimpleButton: React$1.NamedExoticComponent<Omit<SimpleButtonProps, "ref"> & React$1.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * Props for the AuthorizedView component.
+ *
+ * @public
+ */
 type AuthorizedViewProps = PropsWithChildren & {
+    /**
+     * Controls whether the children should be rendered. When false, nothing is rendered.
+     * @example true - Show content, false - Hide content
+     */
     show: boolean;
 };
+/**
+ * Conditional rendering component that shows or hides content based on authorization state.
+ *
+ * This component provides a simple way to conditionally render child components
+ * based on a boolean flag, typically used for authorization or permission-based rendering.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * <AuthorizedView show={hasPermission}>
+ *   <AdminPanel />
+ * </AuthorizedView>
+ * ```
+ *
+ * @example
+ * With user roles:
+ * ```tsx
+ * <AuthorizedView show={user.role === 'admin'}>
+ *   <DeleteButton />
+ * </AuthorizedView>
+ * ```
+ *
+ * @param props - Component props including children and show flag
+ * @returns JSX children if show is true, empty fragment if false
+ *
+ * @public
+ */
 declare const AuthorizedView: ({ children, show }: AuthorizedViewProps) => react_jsx_runtime.JSX.Element;
 
-type CancelButtonProps = {
+/**
+ * Props for the CancelButton component.
+ *
+ * @public
+ */
+interface CancelButtonProps {
+    /**
+     * Indicates if a form or operation is currently being submitted.
+     * When true, the button is disabled to prevent multiple cancel actions.
+     */
     isSubmitting: boolean;
+    /**
+     * Callback function executed when the cancel button is clicked.
+     * Should handle the cancellation logic (e.g., form reset, navigation, etc.).
+     */
     handleCancel: () => void;
+    /**
+     * Optional MUI sx prop for custom styling.
+     * @example { mt: 2, bgcolor: 'error.main' }
+     */
     sx?: SxProps;
-};
+}
+/**
+ * Standardized cancel button component with submission state handling.
+ *
+ * This component provides a consistent cancel button implementation that automatically
+ * handles disabled states during form submissions. It's designed to be used in forms
+ * and dialogs where users need to cancel operations.
+ *
+ * @example
+ * Basic usage in a form:
+ * ```tsx
+ * <CancelButton
+ *   isSubmitting={isLoading}
+ *   handleCancel={() => navigate('/previous-page')}
+ * />
+ * ```
+ *
+ * @example
+ * With custom styling:
+ * ```tsx
+ * <CancelButton
+ *   isSubmitting={form.formState.isSubmitting}
+ *   handleCancel={form.reset}
+ *   sx={{ mt: 2, color: 'error.main' }}
+ * />
+ * ```
+ *
+ * @param props - Component props for cancel button configuration
+ * @returns MUI Button component configured as a cancel button
+ *
+ * @public
+ */
 declare const CancelButton: ({ isSubmitting, handleCancel, sx, }: CancelButtonProps) => react_jsx_runtime.JSX.Element;
 
 export { AuthorizedView, CancelButton, ClearButton, FilterButton, FilterWrapper, FormWrapper, LabelText, ListWrapper, SimpleButton, SimpleToolbar };