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

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/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';

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

@@ -0,0 +1,93 @@
+import { UseToastReturn } from '../useToast';
+import { ToastData } from '../../components/overlays/Toast';
+/**
+ * Async toast configuration
+ */
+export interface AsyncToastConfig<TData, TError = Error> {
+    /**
+     * 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: TData) => string | Partial<ToastData>);
+    /**
+     * Message or data to show on error
+     * Can be a function that receives the error
+     */
+    error: string | Partial<ToastData> | ((error: TError) => string | Partial<ToastData>);
+    /**
+     * Duration for success toast (default: 5000)
+     */
+    successDuration?: number;
+    /**
+     * Duration for error toast (default: 5000)
+     */
+    errorDuration?: number;
+}
+/**
+ * Hook return type
+ */
+export interface UseAsyncToastReturn {
+    /**
+     * Wrap an async function with toast notifications
+     * Returns a function that when called, shows loading toast,
+     * then success/error based on result
+     */
+    wrap: <TArgs extends unknown[], TData, TError = Error>(fn: (...args: TArgs) => Promise<TData>, config: AsyncToastConfig<TData, TError>) => (...args: TArgs) => Promise<TData>;
+    /**
+     * Execute a promise with toast notifications
+     */
+    execute: <TData, TError = Error>(promise: Promise<TData>, config: AsyncToastConfig<TData, TError>) => Promise<TData>;
+    /**
+     * Access to underlying toast methods
+     */
+    toast: UseToastReturn;
+}
+/**
+ * Hook for API endpoint toasts with loading -> success/error flow
+ *
+ * @example
+ * ```tsx
+ * function UserForm() {
+ *   const { wrap, execute } = useAsyncToast();
+ *
+ *   // Method 1: Wrap an existing function
+ *   const saveUser = wrap(
+ *     async (data: UserData) => api.saveUser(data),
+ *     {
+ *       loading: 'Saving user...',
+ *       success: (user) => `User ${user.name} saved successfully`,
+ *       error: (err) => `Failed to save: ${err.message}`,
+ *     }
+ *   );
+ *
+ *   // Method 2: Execute a one-off promise
+ *   const handleFetch = async () => {
+ *     try {
+ *       const data = await execute(
+ *         fetch('/api/data').then(r => r.json()),
+ *         {
+ *           loading: { message: 'Fetching data...', title: 'Loading' },
+ *           success: 'Data loaded!',
+ *           error: 'Failed to load data',
+ *         }
+ *       );
+ *       // Use data...
+ *     } catch (err) {
+ *       // Handle error if needed
+ *     }
+ *   };
+ *
+ *   const handleSubmit = async (formData: UserData) => {
+ *     const user = await saveUser(formData);
+ *     // user is typed as the return value of api.saveUser
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+export declare function useAsyncToast(): UseAsyncToastReturn;

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

@@ -0,0 +1,2 @@
+export { useDialog } from './useDialog';
+export type { UseDialogOptions, UseDialogReturn } from './useDialog';

package/lib/hooks/useDialog/useDialog.d.ts

@@ -0,0 +1,58 @@
+import { DialogContextValue, DialogProps } from '../../components/overlays/Dialog';
+/**
+ * Hook options
+ */
+export interface UseDialogOptions {
+    /**
+     * Default props to apply to all dialogs
+     */
+    defaultProps?: Partial<DialogProps>;
+}
+/**
+ * Hook return type
+ */
+export interface UseDialogReturn extends Pick<DialogContextValue, 'closeDialog' | 'closeTopDialog' | 'closeAllDialogs' | 'isDialogOpen' | 'dialogCount'> {
+    /**
+     * Open a dialog with optional default props merged
+     * @returns Promise that resolves when dialog closes
+     */
+    open: <T = void>(props: Omit<DialogProps, 'isOpen'>) => Promise<T>;
+    /**
+     * Update props of an open dialog
+     */
+    update: (id: string, props: Partial<DialogProps>) => void;
+}
+/**
+ * Hook for programmatically creating and managing dialogs
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const dialog = useDialog();
+ *
+ *   const handleClick = async () => {
+ *     const result = await dialog.open({
+ *       title: 'Confirm Action',
+ *       children: 'Are you sure you want to proceed?',
+ *       actions: (
+ *         <>
+ *           <Button variant="ghost" onClick={() => dialog.closeTopDialog(false)}>
+ *             Cancel
+ *           </Button>
+ *           <Button onClick={() => dialog.closeTopDialog(true)}>
+ *             Confirm
+ *           </Button>
+ *         </>
+ *       ),
+ *     });
+ *
+ *     if (result) {
+ *       // User confirmed
+ *     }
+ *   };
+ *
+ *   return <Button onClick={handleClick}>Open Dialog</Button>;
+ * }
+ * ```
+ */
+export declare function useDialog(options?: UseDialogOptions): UseDialogReturn;

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

@@ -0,0 +1,2 @@
+export { useResizeObserver } from './useResizeObserver';
+export type { UseResizeObserverOptions, UseResizeObserverReturn } from './useResizeObserver';