@true-tech-team/react-components 0.0.3 → 0.0.5

package/lib/components/overlays/LoadingOverlay/LoadingOverlay.d.ts

@@ -0,0 +1,101 @@
+import { default as React, ReactNode } from 'react';
+import { BaseComponentProps, ExtendedComponentSize } from '../../../types/component.types';
+import { SpinnerSpeed, SpinnerStyle, SpinnerVariant } from '../../display/Spinner';
+/**
+ * Loading overlay mode
+ */
+export type LoadingOverlayMode = 'container' | 'fullscreen';
+/**
+ * Props for the LoadingOverlay component
+ */
+export interface LoadingOverlayProps extends BaseComponentProps {
+    /**
+     * Whether the overlay is visible
+     * @default true
+     */
+    visible?: boolean;
+    /**
+     * Mode: cover parent container or full screen
+     * @default 'container'
+     */
+    mode?: LoadingOverlayMode;
+    /**
+     * Spinner style to use
+     * @default 'circular'
+     */
+    spinnerStyle?: SpinnerStyle;
+    /**
+     * Spinner size
+     * @default 'lg'
+     */
+    spinnerSize?: ExtendedComponentSize;
+    /**
+     * Spinner color variant
+     * @default 'primary'
+     */
+    spinnerVariant?: SpinnerVariant;
+    /**
+     * Spinner animation speed
+     * @default 'normal'
+     */
+    spinnerSpeed?: SpinnerSpeed;
+    /**
+     * Optional message to display below spinner
+     */
+    message?: ReactNode;
+    /**
+     * Enable backdrop blur effect
+     * @default false
+     */
+    blur?: boolean;
+    /**
+     * Backdrop opacity (0-1)
+     * @default 0.7
+     */
+    backdropOpacity?: number;
+    /**
+     * Custom z-index for the overlay
+     */
+    zIndex?: number;
+    /**
+     * Transition duration in milliseconds
+     * @default 200
+     */
+    transitionDuration?: number;
+    /**
+     * Custom spinner element (overrides spinnerStyle, spinnerSize, spinnerVariant)
+     */
+    customSpinner?: ReactNode;
+    /**
+     * Border radius for the overlay to match child content
+     * Accepts any valid CSS border-radius value
+     */
+    borderRadius?: string | number;
+}
+/**
+ * LoadingOverlay - Overlay component for showing loading state over content
+ *
+ * @example
+ * ```tsx
+ * // Container mode - wraps content
+ * <LoadingOverlay visible={isLoading}>
+ *   <div>Content to overlay</div>
+ * </LoadingOverlay>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Fullscreen mode
+ * <LoadingOverlay visible={isLoading} mode="fullscreen" message="Loading..." />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With blur effect
+ * <LoadingOverlay visible={isLoading} blur backdropOpacity={0.5}>
+ *   <div>Blurred content</div>
+ * </LoadingOverlay>
+ * ```
+ */
+export declare const LoadingOverlay: React.ForwardRefExoticComponent<LoadingOverlayProps & React.RefAttributes<HTMLDivElement>>;
+export default LoadingOverlay;

package/lib/components/overlays/LoadingOverlay/index.d.ts

@@ -0,0 +1,3 @@
+export { LoadingOverlay } from './LoadingOverlay';
+export type { LoadingOverlayProps, LoadingOverlayMode } from './LoadingOverlay';
+export { default } from './LoadingOverlay';

package/lib/components/overlays/Toast/Toast.d.ts

@@ -0,0 +1,103 @@
+import { default as React, ReactNode } from 'react';
+import { IconName } from '../../display/Icon/icons';
+import { BaseComponentProps } from '../../../types';
+/**
+ * Toast position options
+ */
+export type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/**
+ * Toast variant types
+ */
+export type ToastVariant = 'info' | 'success' | 'warning' | 'error' | 'loading';
+/**
+ * Toast animation state
+ */
+export type ToastAnimationState = 'entering' | 'entered' | 'exiting' | 'exited';
+/**
+ * Single toast props
+ */
+export interface ToastProps extends BaseComponentProps {
+    /**
+     * Unique toast ID
+     */
+    id: string;
+    /**
+     * Toast variant
+     * @default 'info'
+     */
+    variant?: ToastVariant;
+    /**
+     * Toast title
+     */
+    title?: ReactNode;
+    /**
+     * Toast message/description
+     */
+    message?: ReactNode;
+    /**
+     * Custom icon (overrides variant default)
+     */
+    icon?: IconName | ReactNode;
+    /**
+     * Hide the icon
+     * @default false
+     */
+    hideIcon?: boolean;
+    /**
+     * Duration in milliseconds (0 for persistent)
+     * @default 5000
+     */
+    duration?: number;
+    /**
+     * Whether toast can be dismissed by user
+     * @default true
+     */
+    dismissible?: boolean;
+    /**
+     * Action button configuration
+     */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    /**
+     * Callback when toast is dismissed
+     */
+    onDismiss?: () => void;
+    /**
+     * Whether to show progress bar for duration
+     * @default false
+     */
+    showProgress?: boolean;
+    /**
+     * Whether to pause duration on hover
+     * @default true
+     */
+    pauseOnHover?: boolean;
+    /**
+     * Custom render function for toast content
+     */
+    render?: (props: {
+        toast: ToastProps;
+        dismiss: () => void;
+    }) => ReactNode;
+    /**
+     * Animation state (managed by container)
+     */
+    animationState?: ToastAnimationState;
+    /**
+     * Animation duration in ms
+     * @default 200
+     */
+    animationDuration?: number;
+    /**
+     * Position (for animation direction)
+     */
+    position?: ToastPosition;
+}
+/**
+ * Toast component
+ * Single toast notification with auto-dismiss and actions
+ */
+export declare const Toast: React.FC<ToastProps>;
+export default Toast;

package/lib/components/overlays/Toast/ToastContainer.d.ts

@@ -0,0 +1,37 @@
+import { default as React, ReactNode } from 'react';
+import { BaseComponentProps } from '../../../types';
+import { ToastPosition } from './Toast';
+/**
+ * Toast container props
+ */
+export interface ToastContainerProps extends BaseComponentProps {
+    /**
+     * Position for toasts
+     * @default 'top-right'
+     */
+    position?: ToastPosition;
+    /**
+     * Gap between toasts in pixels
+     * @default 12
+     */
+    gap?: number;
+    /**
+     * Offset from viewport edge
+     * @default 16
+     */
+    offset?: number;
+    /**
+     * Custom z-index
+     */
+    zIndex?: number;
+    /**
+     * Children (toast elements)
+     */
+    children?: ReactNode;
+}
+/**
+ * Toast container component
+ * Positions and stacks toast notifications
+ */
+export declare const ToastContainer: React.FC<ToastContainerProps>;
+export default ToastContainer;

package/lib/components/overlays/Toast/ToastContext.d.ts

@@ -0,0 +1,126 @@
+import { ToastProps, ToastPosition } from './Toast';
+/**
+ * Toast data for creating new toasts
+ */
+export interface ToastData extends Omit<ToastProps, 'id' | 'animationState' | 'onDismiss'> {
+    /**
+     * Optional ID (auto-generated if not provided)
+     */
+    id?: string;
+}
+/**
+ * Toast instance with full props and internal state
+ */
+export interface ToastInstance extends ToastProps {
+    /**
+     * Timestamp when toast was created
+     */
+    createdAt: number;
+    /**
+     * Timestamp when toast was paused (if paused)
+     */
+    pausedAt?: number;
+    /**
+     * Remaining duration when paused
+     */
+    remainingDuration?: number;
+}
+/**
+ * Promise toast options
+ */
+export interface PromiseToastOptions<T> {
+    /**
+     * Message or data to show while loading
+     */
+    loading: string | Partial<ToastData>;
+    /**
+     * Message or data to show on success
+     * Can be a function that receives the result
+     */
+    success: string | Partial<ToastData> | ((data: T) => string | Partial<ToastData>);
+    /**
+     * Message or data to show on error
+     * Can be a function that receives the error
+     */
+    error: string | Partial<ToastData> | ((error: Error) => string | Partial<ToastData>);
+}
+/**
+ * Toast context value
+ */
+export interface ToastContextValue {
+    /**
+     * Current toast instances
+     */
+    toasts: ToastInstance[];
+    /**
+     * Add a new toast
+     * @returns Toast ID
+     */
+    addToast: (data: ToastData) => string;
+    /**
+     * Remove a toast by ID
+     */
+    removeToast: (id: string) => void;
+    /**
+     * Update a toast
+     */
+    updateToast: (id: string, data: Partial<ToastData>) => void;
+    /**
+     * Remove all toasts
+     */
+    removeAllToasts: () => void;
+    /**
+     * Pause a toast's timer
+     */
+    pauseToast: (id: string) => void;
+    /**
+     * Resume a toast's timer
+     */
+    resumeToast: (id: string) => void;
+    /**
+     * Show a success toast
+     */
+    success: (message: string, options?: Partial<ToastData>) => string;
+    /**
+     * Show an error toast
+     */
+    error: (message: string, options?: Partial<ToastData>) => string;
+    /**
+     * Show a warning toast
+     */
+    warning: (message: string, options?: Partial<ToastData>) => string;
+    /**
+     * Show an info toast
+     */
+    info: (message: string, options?: Partial<ToastData>) => string;
+    /**
+     * Show a loading toast
+     */
+    loading: (message: string, options?: Partial<ToastData>) => string;
+    /**
+     * Promise-based toast that shows loading, then success/error
+     * @returns Original promise result
+     */
+    promise: <T>(promise: Promise<T>, options: PromiseToastOptions<T>) => Promise<T>;
+    /**
+     * Container position
+     */
+    position: ToastPosition;
+    /**
+     * Maximum visible toasts
+     */
+    maxVisible: number;
+}
+/**
+ * Toast context
+ */
+export declare const ToastContext: import('react').Context<ToastContextValue | null>;
+/**
+ * Hook to access toast context (returns null if not in provider)
+ */
+export declare function useToastContext(): ToastContextValue | null;
+/**
+ * Hook to access toast context (throws if not in provider)
+ * @throws Error if used outside of ToastProvider
+ */
+export declare function useToastContextStrict(): ToastContextValue;

package/lib/components/overlays/Toast/ToastProvider.d.ts

@@ -0,0 +1,71 @@
+import { ReactNode } from 'react';
+import { ToastPosition } from './Toast';
+import { ToastData } from './ToastContext';
+/**
+ * Toast provider props
+ */
+export interface ToastProviderProps {
+    /**
+     * Children to render
+     */
+    children: ReactNode;
+    /**
+     * Position for toasts
+     * @default 'top-right'
+     */
+    position?: ToastPosition;
+    /**
+     * Maximum number of visible toasts
+     * @default 5
+     */
+    maxVisible?: number;
+    /**
+     * Gap between toasts in pixels
+     * @default 12
+     */
+    gap?: number;
+    /**
+     * Offset from viewport edge
+     * @default 16
+     */
+    offset?: number;
+    /**
+     * Default duration for toasts in milliseconds
+     * @default 5000
+     */
+    defaultDuration?: number;
+    /**
+     * Animation duration in milliseconds
+     * @default 200
+     */
+    animationDuration?: number;
+    /**
+     * Default props to apply to all toasts
+     */
+    defaultToastProps?: Partial<ToastData>;
+    /**
+     * Custom z-index for toast container
+     */
+    zIndex?: number;
+}
+/**
+ * Toast provider component
+ * Manages a stack of toasts for programmatic creation
+ *
+ * @example
+ * ```tsx
+ * <ToastProvider position="top-right" maxVisible={5}>
+ *   <App />
+ * </ToastProvider>
+ *
+ * // In a component:
+ * const toast = useToast();
+ *
+ * toast.success('Changes saved successfully');
+ * toast.error('Failed to save changes');
+ * ```
+ */
+export declare function ToastProvider({ children, position, maxVisible, gap, offset, defaultDuration, animationDuration, defaultToastProps, zIndex, }: ToastProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ToastProvider {
+    var displayName: string;
+}

package/lib/components/overlays/Toast/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Toast component exports
+ */
+export { Toast } from './Toast';
+export type { ToastProps, ToastPosition, ToastVariant, ToastAnimationState, } from './Toast';
+export { ToastContainer } from './ToastContainer';
+export type { ToastContainerProps } from './ToastContainer';
+export { ToastProvider } from './ToastProvider';
+export type { ToastProviderProps } from './ToastProvider';
+export { ToastContext, useToastContext, useToastContextStrict, } from './ToastContext';
+export type { ToastContextValue, ToastData, ToastInstance, PromiseToastOptions, } from './ToastContext';

package/lib/contexts/PageMessagesContext/PageMessagesContext.d.ts

@@ -0,0 +1,91 @@
+import { ReactNode } from 'react';
+import { PageMessageStateConfig, LoadingStateConfig, PageMessagesProps } from '../../components/display/PageMessages/types';
+/**
+ * Default configurations for all page message states
+ */
+export interface PageMessagesDefaults {
+    /** Default loading configuration */
+    loading?: LoadingStateConfig;
+    /** Default error configuration */
+    error?: PageMessageStateConfig;
+    /** Default forbidden configuration */
+    forbidden?: PageMessageStateConfig;
+    /** Default not-found configuration */
+    notFound?: PageMessageStateConfig;
+    /** Default unauthorized configuration */
+    unauthorized?: PageMessageStateConfig;
+    /** Default maintenance configuration */
+    maintenance?: PageMessageStateConfig;
+    /** Default offline configuration */
+    offline?: PageMessageStateConfig;
+    /** Default timeout configuration */
+    timeout?: PageMessageStateConfig;
+    /** Default empty configuration */
+    empty?: PageMessageStateConfig;
+}
+/**
+ * Global actions that can be provided app-wide
+ */
+export interface PageMessagesGlobalActions {
+    /** Default retry handler */
+    onRetry?: () => void;
+    /** Default go back handler */
+    onGoBack?: () => void;
+    /** Default go home handler */
+    onGoHome?: () => void;
+    /** Default login handler */
+    onLogin?: () => void;
+}
+/**
+ * Context value for PageMessages
+ */
+export interface PageMessagesContextValue {
+    /** Default state configurations */
+    defaults: PageMessagesDefaults;
+    /** Global action handlers */
+    actions: PageMessagesGlobalActions;
+    /** Default component props */
+    defaultProps?: Partial<Pick<PageMessagesProps, 'size' | 'fullScreen' | 'centerVertically' | 'minHeight'>>;
+}
+export interface PageMessagesProviderProps {
+    children: ReactNode;
+    /** Default configurations for page message states */
+    defaults?: PageMessagesDefaults;
+    /** Global action handlers */
+    actions?: PageMessagesGlobalActions;
+    /** Default component props */
+    defaultProps?: PageMessagesContextValue['defaultProps'];
+}
+/**
+ * Provider for PageMessages defaults and global configuration
+ *
+ * @example
+ * ```tsx
+ * <PageMessagesProvider
+ *   defaults={{
+ *     error: {
+ *       title: 'Oops! Something went wrong',
+ *       description: 'Please try again later',
+ *       icon: 'error',
+ *     },
+ *   }}
+ *   actions={{
+ *     onGoHome: () => router.push('/'),
+ *     onLogin: () => router.push('/login'),
+ *   }}
+ * >
+ *   <App />
+ * </PageMessagesProvider>
+ * ```
+ */
+export declare function PageMessagesProvider({ children, defaults, actions, defaultProps, }: PageMessagesProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access PageMessages context
+ * Returns undefined if not within provider (uses built-in defaults)
+ */
+export declare function usePageMessages(): PageMessagesContextValue | undefined;
+/**
+ * Hook to get merged configuration (context defaults + component props)
+ * For internal use by PageMessages component
+ */
+export declare function usePageMessagesConfig(componentProps: Partial<PageMessagesProps>): PageMessagesContextValue;

package/lib/contexts/PageMessagesContext/index.d.ts

@@ -0,0 +1,2 @@
+export { PageMessagesProvider, usePageMessages, usePageMessagesConfig, } from './PageMessagesContext';
+export type { PageMessagesProviderProps, PageMessagesContextValue, PageMessagesDefaults, PageMessagesGlobalActions, } from './PageMessagesContext';

package/lib/contexts/index.d.ts

@@ -1,2 +1,4 @@
 export { ThemeProvider, useTheme } from './ThemeContext';
 export type { ThemeProviderProps } from './ThemeContext';
+export { PageMessagesProvider, usePageMessages } from './PageMessagesContext';
+export type { PageMessagesProviderProps, PageMessagesContextValue, PageMessagesDefaults, PageMessagesGlobalActions, } from './PageMessagesContext';

package/lib/hooks/index.d.ts

@@ -9,3 +9,13 @@ export type { UsePopoverPositionOptions, UsePopoverPositionReturn, } from './use
 export { useHover } from './useHover';
 export type { UseHoverOptions, UseHoverReturn, HoverProps } from './useHover';
 export { useDebounce } from './useDebounce';
+export { useDialog } from './useDialog';
+export type { UseDialogOptions, UseDialogReturn } from './useDialog';
+export { useAlert } from './useAlert';
+export type { UseAlertOptions, UseAlertReturn } from './useAlert';
+export { useToast } from './useToast';
+export type { UseToastOptions, UseToastReturn } from './useToast';
+export { useAsyncToast } from './useAsyncToast';
+export type { UseAsyncToastReturn, AsyncToastConfig } from './useAsyncToast';
+export { useResizeObserver } from './useResizeObserver';
+export type { UseResizeObserverOptions, UseResizeObserverReturn } from './useResizeObserver';

package/lib/hooks/useAlert/index.d.ts

@@ -0,0 +1,2 @@
+export { useAlert } from './useAlert';
+export type { UseAlertOptions, UseAlertReturn } from './useAlert';

package/lib/hooks/useAlert/useAlert.d.ts

@@ -0,0 +1,99 @@
+import { AlertProps } from '../../components/overlays/Alert';
+/**
+ * Hook options
+ */
+export interface UseAlertOptions {
+    /**
+     * Default props to apply to all alerts
+     */
+    defaultProps?: Partial<AlertProps>;
+}
+/**
+ * Hook return type
+ */
+export interface UseAlertReturn {
+    /**
+     * Show a custom alert
+     * @returns Promise<boolean> - true if confirmed, false if cancelled
+     */
+    alert: (props: Omit<AlertProps, 'isOpen' | 'onConfirm' | 'onCancel'>) => Promise<boolean>;
+    /**
+     * Show a confirmation dialog
+     * @param title - Alert title
+     * @param description - Alert description
+     * @param options - Additional alert options
+     * @returns Promise<boolean> - true if confirmed, false if cancelled
+     */
+    confirm: (title: string, description?: string, options?: Partial<AlertProps>) => Promise<boolean>;
+    /**
+     * Show an error alert
+     * @param title - Alert title
+     * @param description - Alert description
+     * @param options - Additional alert options
+     * @returns Promise<boolean> - true when dismissed
+     */
+    error: (title: string, description?: string, options?: Partial<AlertProps>) => Promise<boolean>;
+    /**
+     * Show a success alert
+     * @param title - Alert title
+     * @param description - Alert description
+     * @param options - Additional alert options
+     * @returns Promise<boolean> - true when dismissed
+     */
+    success: (title: string, description?: string, options?: Partial<AlertProps>) => Promise<boolean>;
+    /**
+     * Show a warning alert
+     * @param title - Alert title
+     * @param description - Alert description
+     * @param options - Additional alert options
+     * @returns Promise<boolean> - true when dismissed
+     */
+    warning: (title: string, description?: string, options?: Partial<AlertProps>) => Promise<boolean>;
+    /**
+     * Show an info alert
+     * @param title - Alert title
+     * @param description - Alert description
+     * @param options - Additional alert options
+     * @returns Promise<boolean> - true when dismissed
+     */
+    info: (title: string, description?: string, options?: Partial<AlertProps>) => Promise<boolean>;
+    /**
+     * Dismiss current alert
+     */
+    dismiss: () => void;
+}
+/**
+ * Hook for programmatically creating alerts
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const alert = useAlert();
+ *
+ *   const handleDelete = async () => {
+ *     const confirmed = await alert.confirm(
+ *       'Delete Item',
+ *       'Are you sure you want to delete this item? This action cannot be undone.',
+ *       { confirmVariant: 'danger' }
+ *     );
+ *
+ *     if (confirmed) {
+ *       // Perform deletion
+ *       await deleteItem();
+ *       alert.success('Deleted', 'Item has been deleted successfully.');
+ *     }
+ *   };
+ *
+ *   const handleError = () => {
+ *     alert.error('Operation Failed', 'Something went wrong. Please try again.');
+ *   };
+ *
+ *   return (
+ *     <Button onClick={handleDelete} variant="danger">
+ *       Delete
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAlert(options?: UseAlertOptions): UseAlertReturn;

package/lib/hooks/useAsyncToast/index.d.ts

@@ -0,0 +1,2 @@
+export { useAsyncToast } from './useAsyncToast';
+export type { UseAsyncToastReturn, AsyncToastConfig } from './useAsyncToast';