/**
 * Headless UI Types
 *
 * Type definitions for all headless hooks and composables.
 *
 * ⚠️ AUTO-GENERATED BY PRISM - DO NOT EDIT
 */

// ============================================================================
// Pagination Types
// ============================================================================

/** Options for initializing pagination */
export interface PaginationOptions {
  /** Initial page number (1-indexed) */
  initialPage?: number;
  /** Initial page size */
  initialPageSize?: number;
  /** Available page size options */
  pageSizeOptions?: number[];
  /** Total number of items (for calculating total pages) */
  totalItems?: number;
}

/** State returned by usePagination */
export interface PaginationState {
  /** Current page number (1-indexed) */
  page: number;
  /** Current page size */
  pageSize: number;
  /** Total number of items */
  totalItems: number;
  /** Total number of pages */
  totalPages: number;
  /** Whether there is a previous page */
  hasPreviousPage: boolean;
  /** Whether there is a next page */
  hasNextPage: boolean;
  /** Index of first item on current page (0-indexed) */
  startIndex: number;
  /** Index of last item on current page (0-indexed) */
  endIndex: number;
}

/** Actions returned by usePagination */
export interface PaginationActions {
  /** Go to a specific page */
  setPage: (page: number) => void;
  /** Go to next page */
  nextPage: () => void;
  /** Go to previous page */
  previousPage: () => void;
  /** Go to first page */
  firstPage: () => void;
  /** Go to last page */
  lastPage: () => void;
  /** Change page size (resets to page 1) */
  setPageSize: (size: number) => void;
  /** Update total items count */
  setTotalItems: (total: number) => void;
  /** Reset to initial state */
  reset: () => void;
}

/** Combined pagination hook result */
export type UsePaginationResult = PaginationState & PaginationActions & {
  /** Available page size options */
  pageSizeOptions: number[];
};

// ============================================================================
// Selection Types
// ============================================================================

/** Options for initializing selection */
export interface SelectionOptions<T> {
  /** Initial selected items */
  initialSelected?: T[];
  /** Key extractor for identifying items */
  keyExtractor?: (item: T) => string | number;
  /** Maximum number of selections (undefined = unlimited) */
  maxSelections?: number;
}

/** State returned by useSelection */
export interface SelectionState<T> {
  /** Currently selected items */
  selected: T[];
  /** Set of selected keys for fast lookup */
  selectedKeys: Set<string | number>;
  /** Number of selected items */
  count: number;
  /** Whether selection is empty */
  isEmpty: boolean;
  /** Whether all items are selected */
  isAllSelected: boolean;
  /** Whether some (but not all) items are selected */
  isIndeterminate: boolean;
}

/** Actions returned by useSelection */
export interface SelectionActions<T> {
  /** Select a single item */
  select: (item: T) => void;
  /** Deselect a single item */
  deselect: (item: T) => void;
  /** Toggle selection of an item */
  toggle: (item: T) => void;
  /** Select all items in the provided list */
  selectAll: (items: T[]) => void;
  /** Deselect all items */
  deselectAll: () => void;
  /** Toggle all items in the provided list */
  toggleAll: (items: T[]) => void;
  /** Check if an item is selected */
  isSelected: (item: T) => boolean;
  /** Select a range of items (for shift+click) */
  selectRange: (items: T[], start: T, end: T) => void;
  /** Reset to initial selection */
  reset: () => void;
}

/** Combined selection hook result */
export type UseSelectionResult<T> = SelectionState<T> & SelectionActions<T>;

// ============================================================================
// Sorting Types
// ============================================================================

/** Sort direction */
export type SortDirection = 'asc' | 'desc';

/** Options for initializing sorting */
export interface SortingOptions<TField = string> {
  /** Initial sort field */
  initialField?: TField;
  /** Initial sort direction */
  initialDirection?: SortDirection;
  /** Whether to allow multi-column sorting */
  multiSort?: boolean;
}

/** Single sort entry */
export interface SortEntry<TField = string> {
  /** Field to sort by */
  field: TField;
  /** Sort direction */
  direction: SortDirection;
}

/** State returned by useSorting */
export interface SortingState<TField = string> {
  /** Current sort field (single sort mode) */
  field: TField | null;
  /** Current sort direction (single sort mode) */
  direction: SortDirection;
  /** All sort entries (multi-sort mode) */
  sorts: SortEntry<TField>[];
  /** Whether sorting is active */
  isSorted: boolean;
}

/** Actions returned by useSorting */
export interface SortingActions<TField = string> {
  /** Sort by a field (toggles direction if already sorted by this field) */
  sortBy: (field: TField) => void;
  /** Set sort field and direction explicitly */
  setSort: (field: TField, direction: SortDirection) => void;
  /** Clear all sorting */
  clearSort: () => void;
  /** Get sort direction for a specific field */
  getSortDirection: (field: TField) => SortDirection | null;
  /** Reset to initial state */
  reset: () => void;
}

/** Combined sorting hook result */
export type UseSortingResult<TField = string> = SortingState<TField> & SortingActions<TField>;

// ============================================================================
// Filtering Types
// ============================================================================

/** Filter operator type */
export type FilterOperator =
  | 'eq'      // equals
  | 'neq'     // not equals
  | 'gt'      // greater than
  | 'gte'     // greater than or equal
  | 'lt'      // less than
  | 'lte'     // less than or equal
  | 'contains'
  | 'startsWith'
  | 'endsWith'
  | 'in'      // in array
  | 'notIn'   // not in array
  | 'between'
  | 'isNull'
  | 'isNotNull';

/** Single filter entry */
export interface FilterEntry<TField = string, TValue = unknown> {
  /** Field to filter by */
  field: TField;
  /** Filter operator */
  operator: FilterOperator;
  /** Filter value(s) */
  value: TValue;
}

/** Options for initializing filtering */
export interface FilteringOptions<TField = string> {
  /** Initial filters */
  initialFilters?: FilterEntry<TField>[];
}

/** State returned by useFiltering */
export interface FilteringState<TField = string> {
  /** Current active filters */
  filters: FilterEntry<TField>[];
  /** Number of active filters */
  count: number;
  /** Whether any filters are active */
  hasFilters: boolean;
}

/** Actions returned by useFiltering */
export interface FilteringActions<TField = string> {
  /** Add or update a filter */
  setFilter: <TValue>(field: TField, operator: FilterOperator, value: TValue) => void;
  /** Remove a filter by field */
  removeFilter: (field: TField) => void;
  /** Clear all filters */
  clearFilters: () => void;
  /** Get filter value for a field */
  getFilterValue: <TValue = unknown>(field: TField) => TValue | undefined;
  /** Check if a field has an active filter */
  hasFilter: (field: TField) => boolean;
  /** Reset to initial filters */
  reset: () => void;
}

/** Combined filtering hook result */
export type UseFilteringResult<TField = string> = FilteringState<TField> & FilteringActions<TField>;

// ============================================================================
// Search Types
// ============================================================================

/** Options for initializing search */
export interface SearchOptions {
  /** Initial search query */
  initialQuery?: string;
  /** Debounce delay in milliseconds */
  debounceMs?: number;
  /** Minimum query length before searching */
  minLength?: number;
}

/** State returned by useSearch */
export interface SearchState {
  /** Current search query (immediate) */
  query: string;
  /** Debounced search query (for API calls) */
  debouncedQuery: string;
  /** Whether search is active (has query) */
  isSearching: boolean;
  /** Whether debounce is pending */
  isPending: boolean;
}

/** Actions returned by useSearch */
export interface SearchActions {
  /** Set the search query */
  setQuery: (query: string) => void;
  /** Clear the search query */
  clear: () => void;
  /** Reset to initial state */
  reset: () => void;
}

/** Combined search hook result */
export type UseSearchResult = SearchState & SearchActions;

// ============================================================================
// Modal Types
// ============================================================================

/** Options for initializing modal */
export interface ModalOptions<T = undefined> {
  /** Initial open state */
  initialOpen?: boolean;
  /** Initial data */
  initialData?: T;
  /** Callback when modal opens */
  onOpen?: (data?: T) => void;
  /** Callback when modal closes */
  onClose?: () => void;
}

/** State returned by useModal */
export interface ModalState<T = undefined> {
  /** Whether modal is open */
  isOpen: boolean;
  /** Data passed to the modal */
  data: T | undefined;
}

/** Actions returned by useModal */
export interface ModalActions<T = undefined> {
  /** Open the modal with optional data */
  open: (data?: T) => void;
  /** Close the modal */
  close: () => void;
  /** Toggle modal open state */
  toggle: () => void;
  /** Update modal data without changing open state */
  setData: (data: T) => void;
}

/** Combined modal hook result */
export type UseModalResult<T = undefined> = ModalState<T> & ModalActions<T>;

// ============================================================================
// Confirmation Types
// ============================================================================

/** Confirmation dialog variant */
export type ConfirmationVariant = 'default' | 'danger' | 'warning' | 'info';

/** Options for a confirmation dialog */
export interface ConfirmationOptions {
  /** Dialog title */
  title: string;
  /** Dialog message/description */
  message: string;
  /** Visual variant */
  variant?: ConfirmationVariant;
  /** Confirm button text */
  confirmText?: string;
  /** Cancel button text */
  cancelText?: string;
  /** Whether to show a loading state on confirm */
  showLoading?: boolean;
}

/** State of the confirmation dialog */
export interface ConfirmationState {
  /** Whether the dialog is open */
  isOpen: boolean;
  /** Whether the dialog is in loading state */
  isLoading: boolean;
  /** Current dialog options */
  options: ConfirmationOptions | null;
}

/** Confirmation hook result */
export interface UseConfirmationResult {
  /** Current state */
  state: ConfirmationState;
  /** Show confirmation and await user response (returns true if confirmed) */
  confirm: (options: ConfirmationOptions) => Promise<boolean>;
  /** Programmatically close the dialog (resolves as cancelled) */
  cancel: () => void;
}

// ============================================================================
// Toast Types
// ============================================================================

/** Toast notification type */
export type ToastType = 'success' | 'error' | 'warning' | 'info';

/** Toast notification entry */
export interface ToastEntry {
  /** Unique toast ID */
  id: string;
  /** Toast type */
  type: ToastType;
  /** Toast title */
  title: string;
  /** Toast description/message */
  description?: string;
  /** Duration in milliseconds (undefined = persistent) */
  duration?: number;
  /** Whether toast can be dismissed */
  dismissible?: boolean;
  /** Optional action button */
  action?: {
    label: string;
    onClick: () => void;
  };
}

/** Options for creating a toast */
export interface ToastOptions {
  /** Toast title */
  title: string;
  /** Toast description */
  description?: string;
  /** Duration in milliseconds (default: 5000, 0 = persistent) */
  duration?: number;
  /** Whether toast can be dismissed (default: true) */
  dismissible?: boolean;
  /** Optional action button */
  action?: {
    label: string;
    onClick: () => void;
  };
}

/** State returned by useToast */
export interface ToastState {
  /** List of active toasts */
  toasts: ToastEntry[];
}

/** Actions returned by useToast */
export interface ToastActions {
  /** Show a success toast */
  success: (titleOrOptions: string | ToastOptions) => string;
  /** Show an error toast */
  error: (titleOrOptions: string | ToastOptions) => string;
  /** Show a warning toast */
  warning: (titleOrOptions: string | ToastOptions) => string;
  /** Show an info toast */
  info: (titleOrOptions: string | ToastOptions) => string;
  /** Dismiss a specific toast by ID */
  dismiss: (id: string) => void;
  /** Dismiss all toasts */
  dismissAll: () => void;
}

/** Combined toast hook result */
export type UseToastResult = ToastState & ToastActions;

// ============================================================================
// Drawer Types
// ============================================================================

/** Drawer position */
export type DrawerPosition = 'left' | 'right' | 'top' | 'bottom';

/** Options for initializing drawer */
export interface DrawerOptions<T = undefined> {
  /** Initial open state */
  initialOpen?: boolean;
  /** Initial data */
  initialData?: T;
  /** Drawer position */
  position?: DrawerPosition;
  /** Callback when drawer opens */
  onOpen?: (data?: T) => void;
  /** Callback when drawer closes */
  onClose?: () => void;
}

/** State returned by useDrawer */
export interface DrawerState<T = undefined> {
  /** Whether drawer is open */
  isOpen: boolean;
  /** Data passed to the drawer */
  data: T | undefined;
  /** Drawer position */
  position: DrawerPosition;
}

/** Actions returned by useDrawer */
export interface DrawerActions<T = undefined> {
  /** Open the drawer with optional data */
  open: (data?: T) => void;
  /** Close the drawer */
  close: () => void;
  /** Toggle drawer open state */
  toggle: () => void;
  /** Update drawer data without changing open state */
  setData: (data: T) => void;
}

/** Combined drawer hook result */
export type UseDrawerResult<T = undefined> = DrawerState<T> & DrawerActions<T>;

// ============================================================================
// Utility Types
// ============================================================================

/** Generic item with ID for selection */
export interface Identifiable {
  id: string | number;
}

/** Export format type */
export type ExportFormat = 'csv' | 'json';

/** Export options */
export interface ExportOptions<T> {
  /** Data to export */
  data: T[];
  /** Filename (without extension) */
  filename: string;
  /** Export format */
  format: ExportFormat;
  /** Columns to include (all if not specified) */
  columns?: (keyof T)[];
  /** Custom column headers */
  headers?: Partial<Record<keyof T, string>>;
}

/** Transform options for client-side data manipulation */
export interface TransformOptions<T, TField = keyof T> {
  /** Data to transform */
  data: T[];
  /** Search query to filter by */
  search?: {
    query: string;
    fields: TField[];
  };
  /** Filters to apply */
  filters?: FilterEntry<TField>[];
  /** Sort configuration */
  sort?: SortEntry<TField>[];
  /** Pagination configuration */
  pagination?: {
    page: number;
    pageSize: number;
  };
}

/** Transform result */
export interface TransformResult<T> {
  /** Transformed data (paginated slice) */
  data: T[];
  /** Total count after filtering (before pagination) */
  totalCount: number;
  /** Total pages based on page size */
  totalPages: number;
}
