@startsimpli/hooks 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,223 @@
+import { QueryKey, UseMutationResult } from '@tanstack/react-query';
+
+interface TableFilterBase {
+    page: number;
+    pageSize: number;
+    search?: string;
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+}
+type TableFilters<TFilters extends Record<string, unknown>> = TFilters & TableFilterBase;
+interface UseTableFiltersReturn<TFilters extends Record<string, unknown>> {
+    filters: TableFilters<TFilters>;
+    setFilter: <K extends keyof TFilters>(key: K, value: TFilters[K]) => void;
+    setPage: (page: number) => void;
+    setPageSize: (pageSize: number) => void;
+    setSearch: (search: string) => void;
+    setSort: (field: string, direction: 'asc' | 'desc') => void;
+    resetFilters: () => void;
+}
+declare function useTableFilters<TFilters extends Record<string, unknown>>(initial: TFilters & {
+    page?: number;
+    pageSize?: number;
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+}): UseTableFiltersReturn<TFilters>;
+
+/**
+ * Generic filter types for table/list filtering across StartSimpli apps.
+ *
+ * These types define the shape of a filter configuration that supports
+ * AND/OR logic, multiple operators, and nested groups.
+ *
+ * Domain-specific field types (e.g. FirmFilterField) extend these in each app.
+ */
+type FilterOperator = 'equals' | 'not_equals' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'is_null' | 'is_not_null' | 'between' | 'not_between' | 'fuzzy_search';
+type FilterValue = string | number | boolean | null | string[] | number[] | [number, number] | [string, string];
+interface FilterCondition {
+    field: string;
+    operator: FilterOperator;
+    value: FilterValue;
+}
+interface FilterGroup {
+    logic: 'AND' | 'OR';
+    conditions: FilterCondition[];
+    groups?: FilterGroup[];
+}
+interface FilterConfig {
+    groups: FilterGroup[];
+    globalLogic?: 'AND' | 'OR';
+    metadata?: {
+        name?: string;
+        description?: string;
+        tags?: string[];
+    };
+}
+/** URL-encoded representation of table state */
+interface EncodedFilterState {
+    f?: string;
+    s?: string;
+    d?: string;
+    p?: number;
+    l?: number;
+}
+interface FilterValidationError {
+    field?: string;
+    operator?: string;
+    value?: FilterValue;
+    message: string;
+    code: string;
+}
+interface FilterValidationResult {
+    isValid: boolean;
+    errors: FilterValidationError[];
+    warnings: string[];
+}
+
+/**
+ * URL filter encoding utilities.
+ *
+ * Provides base64 encode/decode for FilterConfig (so filter state can be
+ * stored in URL query params as compact strings) plus helpers for common
+ * filter operations.
+ *
+ * These are pure functions with no React or Next.js dependencies.
+ */
+
+/**
+ * Encode a FilterConfig to a URL-safe base64 string.
+ */
+declare function encodeFilterConfig(config: FilterConfig): string;
+/**
+ * Decode a URL-safe base64 string back to a FilterConfig.
+ * Returns null if the string is invalid or cannot be parsed.
+ */
+declare function decodeFilterConfig(encoded: string): FilterConfig | null;
+/**
+ * Parse URLSearchParams into an EncodedFilterState.
+ */
+declare function parseUrlFilters(params: URLSearchParams): EncodedFilterState;
+/**
+ * Build a single-condition FilterConfig.
+ */
+declare function createSimpleFilter(field: string, operator: FilterOperator, value: FilterValue): FilterConfig;
+/**
+ * Merge multiple FilterConfigs with AND logic.
+ */
+declare function mergeFilters(...configs: FilterConfig[]): FilterConfig;
+/**
+ * Get a human-readable description of a FilterConfig.
+ */
+declare function getFilterDescription(config: FilterConfig): string;
+
+interface UseCRUDMutationOptions<TInput, TOutput> {
+    invalidateKeys: QueryKey[];
+    onSuccess?: (data: TOutput, variables: TInput) => void;
+    onError?: (error: Error, variables: TInput) => void;
+}
+declare function useCRUDMutation<TInput, TOutput>(mutationFn: (input: TInput) => Promise<TOutput>, opts: UseCRUDMutationOptions<TInput, TOutput>): UseMutationResult<TOutput, Error, TInput>;
+
+interface SavedView {
+    id: string;
+    name: string;
+    isDefault?: boolean;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface UseSavedViewsOptions<T extends SavedView> {
+    resource: string;
+    loadFn: (resource: string) => Promise<T[]>;
+    saveFn: (resource: string, view: Omit<T, 'id' | 'createdAt'>) => Promise<T>;
+    updateFn: (resource: string, viewId: string, updates: Partial<T>) => Promise<T>;
+    deleteFn: (resource: string, viewId: string) => Promise<void>;
+}
+declare function useSavedViews<T extends SavedView>({ resource, loadFn, saveFn, updateFn, deleteFn, }: UseSavedViewsOptions<T>): {
+    views: T[];
+    currentViewId: string | null;
+    loading: boolean;
+    error: string | null;
+    saveView: (viewData: Omit<T, "id" | "createdAt">) => Promise<T>;
+    updateView: (viewId: string, updates: Partial<T>) => Promise<void>;
+    deleteView: (viewId: string) => Promise<void>;
+    loadView: (viewId: string) => void;
+    getCurrentView: () => T | null;
+    refreshViews: () => Promise<void>;
+};
+
+declare function useRecentlyViewed<T extends {
+    id: string;
+}>(storageKey: string, maxItems?: number): {
+    items: T[];
+    timestamps: {
+        id: string;
+        viewedAt: number;
+    }[];
+    trackView: (item: T) => void;
+    clear: () => void;
+};
+
+interface WizardState<TStep extends string> {
+    currentStep: TStep;
+    stepIndex: number;
+    totalSteps: number;
+    isFirstStep: boolean;
+    isLastStep: boolean;
+    canGoBack: boolean;
+    canGoNext: boolean;
+    goTo: (step: TStep) => void;
+    next: () => void;
+    prev: () => void;
+    reset: () => void;
+}
+declare function useWizard<TStep extends string>(steps: readonly TStep[], initialStep?: TStep): WizardState<TStep>;
+
+interface CSVColumnMapping {
+    csv_column: string;
+    target_field: string;
+}
+interface CSVPreviewResult<TField extends string = string> {
+    columns: string[];
+    sample_rows: Record<string, string>[];
+    suggested_mappings?: CSVColumnMapping[];
+    total_rows?: number;
+}
+interface CSVImportResult {
+    total_rows: number;
+    successful: number;
+    failed: number;
+    errors: Array<{
+        row: number;
+        message: string;
+    }>;
+}
+type CSVImportStep = 'upload' | 'mapping' | 'importing' | 'complete';
+interface UseCSVImportOptions<TField extends string = string> {
+    previewFn: (file: File) => Promise<CSVPreviewResult<TField>>;
+    importFn: (file: File, mappings: CSVColumnMapping[]) => Promise<CSVImportResult>;
+    onSuccess?: (result: CSVImportResult) => void;
+}
+interface UseCSVImportState {
+    step: CSVImportStep;
+    file: File | null;
+    preview: CSVPreviewResult | null;
+    mappings: CSVColumnMapping[];
+    result: CSVImportResult | null;
+    isLoading: boolean;
+    error: string | null;
+    handleFileSelect: (file: File) => Promise<void>;
+    updateMapping: (csvColumn: string, targetField: string) => void;
+    startImport: () => Promise<void>;
+    reset: () => void;
+    goBack: () => void;
+}
+declare function useCSVImport<TField extends string = string>({ previewFn, importFn, onSuccess, }: UseCSVImportOptions<TField>): UseCSVImportState;
+interface UseCSVExportOptions {
+    exportFn: () => Promise<Blob | string>;
+    filename?: string;
+}
+declare function useCSVExport({ exportFn, filename }: UseCSVExportOptions): {
+    exportCSV: () => Promise<void>;
+    isExporting: boolean;
+};
+
+export { type CSVColumnMapping, type CSVImportResult, type CSVImportStep, type CSVPreviewResult, type EncodedFilterState, type FilterCondition, type FilterConfig, type FilterGroup, type FilterOperator, type FilterValidationError, type FilterValidationResult, type FilterValue, type SavedView as SavedViewEntry, type UseCSVImportState, type WizardState, createSimpleFilter, decodeFilterConfig, encodeFilterConfig, getFilterDescription, mergeFilters, parseUrlFilters, useCRUDMutation, useCSVExport, useCSVImport, useRecentlyViewed, useSavedViews, useTableFilters, useWizard };

package/dist/index.d.ts

@@ -0,0 +1,223 @@
+import { QueryKey, UseMutationResult } from '@tanstack/react-query';
+
+interface TableFilterBase {
+    page: number;
+    pageSize: number;
+    search?: string;
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+}
+type TableFilters<TFilters extends Record<string, unknown>> = TFilters & TableFilterBase;
+interface UseTableFiltersReturn<TFilters extends Record<string, unknown>> {
+    filters: TableFilters<TFilters>;
+    setFilter: <K extends keyof TFilters>(key: K, value: TFilters[K]) => void;
+    setPage: (page: number) => void;
+    setPageSize: (pageSize: number) => void;
+    setSearch: (search: string) => void;
+    setSort: (field: string, direction: 'asc' | 'desc') => void;
+    resetFilters: () => void;
+}
+declare function useTableFilters<TFilters extends Record<string, unknown>>(initial: TFilters & {
+    page?: number;
+    pageSize?: number;
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+}): UseTableFiltersReturn<TFilters>;
+
+/**
+ * Generic filter types for table/list filtering across StartSimpli apps.
+ *
+ * These types define the shape of a filter configuration that supports
+ * AND/OR logic, multiple operators, and nested groups.
+ *
+ * Domain-specific field types (e.g. FirmFilterField) extend these in each app.
+ */
+type FilterOperator = 'equals' | 'not_equals' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'is_null' | 'is_not_null' | 'between' | 'not_between' | 'fuzzy_search';
+type FilterValue = string | number | boolean | null | string[] | number[] | [number, number] | [string, string];
+interface FilterCondition {
+    field: string;
+    operator: FilterOperator;
+    value: FilterValue;
+}
+interface FilterGroup {
+    logic: 'AND' | 'OR';
+    conditions: FilterCondition[];
+    groups?: FilterGroup[];
+}
+interface FilterConfig {
+    groups: FilterGroup[];
+    globalLogic?: 'AND' | 'OR';
+    metadata?: {
+        name?: string;
+        description?: string;
+        tags?: string[];
+    };
+}
+/** URL-encoded representation of table state */
+interface EncodedFilterState {
+    f?: string;
+    s?: string;
+    d?: string;
+    p?: number;
+    l?: number;
+}
+interface FilterValidationError {
+    field?: string;
+    operator?: string;
+    value?: FilterValue;
+    message: string;
+    code: string;
+}
+interface FilterValidationResult {
+    isValid: boolean;
+    errors: FilterValidationError[];
+    warnings: string[];
+}
+
+/**
+ * URL filter encoding utilities.
+ *
+ * Provides base64 encode/decode for FilterConfig (so filter state can be
+ * stored in URL query params as compact strings) plus helpers for common
+ * filter operations.
+ *
+ * These are pure functions with no React or Next.js dependencies.
+ */
+
+/**
+ * Encode a FilterConfig to a URL-safe base64 string.
+ */
+declare function encodeFilterConfig(config: FilterConfig): string;
+/**
+ * Decode a URL-safe base64 string back to a FilterConfig.
+ * Returns null if the string is invalid or cannot be parsed.
+ */
+declare function decodeFilterConfig(encoded: string): FilterConfig | null;
+/**
+ * Parse URLSearchParams into an EncodedFilterState.
+ */
+declare function parseUrlFilters(params: URLSearchParams): EncodedFilterState;
+/**
+ * Build a single-condition FilterConfig.
+ */
+declare function createSimpleFilter(field: string, operator: FilterOperator, value: FilterValue): FilterConfig;
+/**
+ * Merge multiple FilterConfigs with AND logic.
+ */
+declare function mergeFilters(...configs: FilterConfig[]): FilterConfig;
+/**
+ * Get a human-readable description of a FilterConfig.
+ */
+declare function getFilterDescription(config: FilterConfig): string;
+
+interface UseCRUDMutationOptions<TInput, TOutput> {
+    invalidateKeys: QueryKey[];
+    onSuccess?: (data: TOutput, variables: TInput) => void;
+    onError?: (error: Error, variables: TInput) => void;
+}
+declare function useCRUDMutation<TInput, TOutput>(mutationFn: (input: TInput) => Promise<TOutput>, opts: UseCRUDMutationOptions<TInput, TOutput>): UseMutationResult<TOutput, Error, TInput>;
+
+interface SavedView {
+    id: string;
+    name: string;
+    isDefault?: boolean;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface UseSavedViewsOptions<T extends SavedView> {
+    resource: string;
+    loadFn: (resource: string) => Promise<T[]>;
+    saveFn: (resource: string, view: Omit<T, 'id' | 'createdAt'>) => Promise<T>;
+    updateFn: (resource: string, viewId: string, updates: Partial<T>) => Promise<T>;
+    deleteFn: (resource: string, viewId: string) => Promise<void>;
+}
+declare function useSavedViews<T extends SavedView>({ resource, loadFn, saveFn, updateFn, deleteFn, }: UseSavedViewsOptions<T>): {
+    views: T[];
+    currentViewId: string | null;
+    loading: boolean;
+    error: string | null;
+    saveView: (viewData: Omit<T, "id" | "createdAt">) => Promise<T>;
+    updateView: (viewId: string, updates: Partial<T>) => Promise<void>;
+    deleteView: (viewId: string) => Promise<void>;
+    loadView: (viewId: string) => void;
+    getCurrentView: () => T | null;
+    refreshViews: () => Promise<void>;
+};
+
+declare function useRecentlyViewed<T extends {
+    id: string;
+}>(storageKey: string, maxItems?: number): {
+    items: T[];
+    timestamps: {
+        id: string;
+        viewedAt: number;
+    }[];
+    trackView: (item: T) => void;
+    clear: () => void;
+};
+
+interface WizardState<TStep extends string> {
+    currentStep: TStep;
+    stepIndex: number;
+    totalSteps: number;
+    isFirstStep: boolean;
+    isLastStep: boolean;
+    canGoBack: boolean;
+    canGoNext: boolean;
+    goTo: (step: TStep) => void;
+    next: () => void;
+    prev: () => void;
+    reset: () => void;
+}
+declare function useWizard<TStep extends string>(steps: readonly TStep[], initialStep?: TStep): WizardState<TStep>;
+
+interface CSVColumnMapping {
+    csv_column: string;
+    target_field: string;
+}
+interface CSVPreviewResult<TField extends string = string> {
+    columns: string[];
+    sample_rows: Record<string, string>[];
+    suggested_mappings?: CSVColumnMapping[];
+    total_rows?: number;
+}
+interface CSVImportResult {
+    total_rows: number;
+    successful: number;
+    failed: number;
+    errors: Array<{
+        row: number;
+        message: string;
+    }>;
+}
+type CSVImportStep = 'upload' | 'mapping' | 'importing' | 'complete';
+interface UseCSVImportOptions<TField extends string = string> {
+    previewFn: (file: File) => Promise<CSVPreviewResult<TField>>;
+    importFn: (file: File, mappings: CSVColumnMapping[]) => Promise<CSVImportResult>;
+    onSuccess?: (result: CSVImportResult) => void;
+}
+interface UseCSVImportState {
+    step: CSVImportStep;
+    file: File | null;
+    preview: CSVPreviewResult | null;
+    mappings: CSVColumnMapping[];
+    result: CSVImportResult | null;
+    isLoading: boolean;
+    error: string | null;
+    handleFileSelect: (file: File) => Promise<void>;
+    updateMapping: (csvColumn: string, targetField: string) => void;
+    startImport: () => Promise<void>;
+    reset: () => void;
+    goBack: () => void;
+}
+declare function useCSVImport<TField extends string = string>({ previewFn, importFn, onSuccess, }: UseCSVImportOptions<TField>): UseCSVImportState;
+interface UseCSVExportOptions {
+    exportFn: () => Promise<Blob | string>;
+    filename?: string;
+}
+declare function useCSVExport({ exportFn, filename }: UseCSVExportOptions): {
+    exportCSV: () => Promise<void>;
+    isExporting: boolean;
+};
+
+export { type CSVColumnMapping, type CSVImportResult, type CSVImportStep, type CSVPreviewResult, type EncodedFilterState, type FilterCondition, type FilterConfig, type FilterGroup, type FilterOperator, type FilterValidationError, type FilterValidationResult, type FilterValue, type SavedView as SavedViewEntry, type UseCSVImportState, type WizardState, createSimpleFilter, decodeFilterConfig, encodeFilterConfig, getFilterDescription, mergeFilters, parseUrlFilters, useCRUDMutation, useCSVExport, useCSVImport, useRecentlyViewed, useSavedViews, useTableFilters, useWizard };