@afurgeri/crud-vue 0.1.0

package/src/composables/useCrud.ts

@@ -0,0 +1,328 @@
+import { ref, computed, onUnmounted, type Ref, type ComputedRef } from 'vue';
+import { router } from '@inertiajs/vue3';
+import type { CrudFilter, FilterDocument, UseCrudOptions } from '../types/crud';
+
+export interface UseCrudReturn {
+    search: Ref<string>;
+    activeFilters: Ref<Record<string, unknown>>;
+    sortField: Ref<string>;
+    sortDirection: Ref<'asc' | 'desc'>;
+    hasActiveFilters: ComputedRef<boolean>;
+    filtersVisible: Ref<boolean>;
+    onSearchInput: (value: string) => void;
+    onFilterChange: (field: string, value: unknown) => void;
+    onSortToggle: (field: string) => void;
+    applyFilters: () => void;
+    clearFilters: () => void;
+    toggleFilters: () => void;
+    getSortParam: () => string;
+}
+
+export function buildFilters(state: Record<string, unknown>, config: CrudFilter[]): FilterDocument {
+    const result: FilterDocument = {};
+
+    for (const filter of config) {
+        const value = state[filter.field];
+        if (value === undefined || value === null || value === '') continue;
+
+        switch (filter.type) {
+            case 'text':
+                result['like'] = { ...(result['like'] as Record<string, unknown> ?? {}), [filter.field]: value };
+                break;
+            case 'select':
+                result['eq'] = { ...(result['eq'] as Record<string, unknown> ?? {}), [filter.field]: value };
+                break;
+            case 'number': {
+                const numValue = value as { min?: number; max?: number };
+                if (numValue.min !== undefined && numValue.min !== null && numValue.min !== '') {
+                    result['gte'] = { ...(result['gte'] as Record<string, unknown> ?? {}), [filter.field]: Number(numValue.min) };
+                }
+                if (numValue.max !== undefined && numValue.max !== null && numValue.max !== '') {
+                    result['lte'] = { ...(result['lte'] as Record<string, unknown> ?? {}), [filter.field]: Number(numValue.max) };
+                }
+                break;
+            }
+            case 'date': {
+                const dateValue = value as { from?: string; to?: string };
+                if (dateValue.from) {
+                    result['date_gte'] = { ...(result['date_gte'] as Record<string, unknown> ?? {}), [filter.field]: dateValue.from };
+                }
+                if (dateValue.to) {
+                    result['date_lte'] = { ...(result['date_lte'] as Record<string, unknown> ?? {}), [filter.field]: dateValue.to };
+                }
+                break;
+            }
+        }
+    }
+
+    return result;
+}
+
+function hasAnyFilterValue(state: Record<string, unknown>): boolean {
+    return Object.values(state).some((v) => {
+        if (v === undefined || v === null || v === '') return false;
+        if (typeof v === 'object' && !Array.isArray(v)) {
+            return Object.values(v as Record<string, unknown>).some(
+                (inner) => inner !== undefined && inner !== null && inner !== '',
+            );
+        }
+        return true;
+    });
+}
+
+export function useCrud(
+    filterConfig: CrudFilter[],
+    searchFields: string[],
+    itemsPropName?: string,
+    defaultSort?: string,
+    options?: UseCrudOptions,
+): UseCrudReturn {
+    const search = ref('');
+    const activeFilters = ref<Record<string, unknown>>({});
+    const sortField = ref('');
+    const sortDirection = ref<'asc' | 'desc'>('asc');
+    const filtersVisible = ref(false);
+    let searchTimeout: ReturnType<typeof setTimeout>;
+    let isDisposed = false;
+
+    const debounceMs = options?.searchDebounce ?? 300;
+
+    // Initialize from URL on mount
+    function initFromUrl() {
+        const params = new URLSearchParams(window.location.search);
+
+        search.value = params.get('search') || '';
+
+        const filtersParam = params.get('filters');
+        if (filtersParam) {
+            try {
+                const parsed = JSON.parse(decodeURIComponent(filtersParam));
+                // Reconstruct active filter state from the structured filters
+                for (const filter of filterConfig) {
+                    let value: unknown = undefined;
+
+                    switch (filter.type) {
+                        case 'text':
+                            value = parsed['like']?.[filter.field] ?? '';
+                            break;
+                        case 'select':
+                            value = parsed['eq']?.[filter.field] ?? '';
+                            break;
+                        case 'number':
+                            value = {
+                                min: parsed['gte']?.[filter.field] ?? '',
+                                max: parsed['lte']?.[filter.field] ?? '',
+                            };
+                            if (!(value as { min: unknown; max: unknown }).min && !(value as { min: unknown; max: unknown }).max) {
+                                value = undefined;
+                            }
+                            break;
+                        case 'date':
+                            value = {
+                                from: parsed['date_gte']?.[filter.field] ?? '',
+                                to: parsed['date_lte']?.[filter.field] ?? '',
+                            };
+                            if (!(value as { from: unknown; to: unknown }).from && !(value as { from: unknown; to: unknown }).to) {
+                                value = undefined;
+                            }
+                            break;
+                    }
+
+                    if (value !== undefined) {
+                        activeFilters.value[filter.field] = value;
+                    }
+                }
+            } catch (e) {
+                // Call onError hook if provided
+                options?.onError?.(e);
+            }
+        }
+
+        const sortParam = params.get('sort');
+        if (sortParam) {
+            if (sortParam.startsWith('-')) {
+                sortField.value = sortParam.slice(1);
+                sortDirection.value = 'desc';
+            } else {
+                sortField.value = sortParam;
+                sortDirection.value = 'asc';
+            }
+        } else if (defaultSort) {
+            if (defaultSort.startsWith('-')) {
+                sortField.value = defaultSort.slice(1);
+                sortDirection.value = 'desc';
+            } else {
+                sortField.value = defaultSort;
+                sortDirection.value = 'asc';
+            }
+        }
+    }
+
+    async function reloadWithParams(replace = true) {
+        if (isDisposed) return;
+
+        const url = new URL(window.location.href);
+
+        // Search
+        if (search.value) {
+            url.searchParams.set('search', search.value);
+        } else {
+            url.searchParams.delete('search');
+        }
+
+        // Filters
+        const filterBuilder = options?.buildCustomFilters ?? buildFilters;
+        const filters = filterBuilder(activeFilters.value, filterConfig);
+        if (Object.keys(filters).length > 0) {
+            url.searchParams.set('filters', encodeURIComponent(JSON.stringify(filters)));
+        } else {
+            url.searchParams.delete('filters');
+        }
+
+        // Sort
+        if (sortField.value) {
+            url.searchParams.set('sort', getSortParam());
+        } else {
+            url.searchParams.delete('sort');
+        }
+
+        // Reset to page 1 when filters/search/sort changes
+        url.searchParams.delete('page');
+
+        // onBeforeReload hook
+        if (options?.onBeforeReload) {
+            const hookResult = options.onBeforeReload(url.searchParams);
+
+            // Handle Promise (async) case
+            const resolved = hookResult instanceof Promise ? await hookResult : hookResult;
+
+            // Cancel navigation if hook returns false
+            if (resolved === false) return;
+
+            // If hook returns a DIFFERENT URLSearchParams object, replace the URL's params.
+            // (When the hook mutates url.searchParams in-place and returns the same reference,
+            // the mutations are already applied — no copy needed.)
+            if (resolved instanceof URLSearchParams && resolved !== url.searchParams) {
+                for (const key of [...url.searchParams.keys()]) {
+                    url.searchParams.delete(key);
+                }
+                resolved.forEach((value, key) => {
+                    url.searchParams.set(key, value);
+                });
+            }
+        }
+
+        const routerOptions: Record<string, unknown> = {
+            preserveState: true,
+            preserveScroll: false,
+            replace,
+        };
+
+        if (itemsPropName) {
+            routerOptions['only'] = [itemsPropName];
+        }
+
+        router.get(url.pathname + url.search, {}, routerOptions);
+    }
+
+    function onSearchInput(value: string) {
+        search.value = value;
+        clearTimeout(searchTimeout);
+        if (!isDisposed) {
+            if (debounceMs === 0) {
+                reloadWithParams();
+            } else {
+                searchTimeout = setTimeout(() => reloadWithParams(), debounceMs);
+            }
+        }
+    }
+
+    function onFilterChange(field: string, value: unknown) {
+        activeFilters.value[field] = value;
+    }
+
+    function onSortToggle(field: string) {
+        if (sortField.value === field) {
+            if (sortDirection.value === 'asc') {
+                sortDirection.value = 'desc';
+            } else {
+                sortField.value = '';
+                sortDirection.value = 'asc';
+            }
+        } else {
+            sortField.value = field;
+            sortDirection.value = 'asc';
+        }
+        reloadWithParams();
+    }
+
+    function applyFilters() {
+        reloadWithParams();
+    }
+
+    function clearFilters() {
+        search.value = '';
+        activeFilters.value = {};
+        sortField.value = '';
+        sortDirection.value = 'asc';
+        filtersVisible.value = false;
+
+        const url = new URL(window.location.href);
+        url.search = '';
+
+        const routerOptions: Record<string, unknown> = {
+            preserveState: true,
+            preserveScroll: false,
+            replace: true,
+        };
+
+        if (itemsPropName) {
+            routerOptions['only'] = [itemsPropName];
+        }
+
+        router.get(url.pathname, {}, routerOptions);
+    }
+
+    function toggleFilters() {
+        filtersVisible.value = !filtersVisible.value;
+    }
+
+    function getSortParam(): string {
+        if (!sortField.value) return '';
+        return sortDirection.value === 'desc' ? `-${sortField.value}` : sortField.value;
+    }
+
+    const hasActiveFilters = computed(() => {
+        return search.value !== '' || hasAnyFilterValue(activeFilters.value);
+    });
+
+    // Init
+    initFromUrl();
+
+    // If defaultSort was applied (not from URL), sync it to the URL on first load
+    if (defaultSort && !new URLSearchParams(window.location.search).get('sort')) {
+        // Delay to avoid blocking initial render
+        setTimeout(() => reloadWithParams(true), 0);
+    }
+
+    onUnmounted(() => {
+        isDisposed = true;
+        clearTimeout(searchTimeout);
+    });
+
+    return {
+        search,
+        activeFilters,
+        sortField,
+        sortDirection,
+        hasActiveFilters,
+        filtersVisible,
+        onSearchInput,
+        onFilterChange,
+        onSortToggle,
+        applyFilters,
+        clearFilters,
+        toggleFilters,
+        getSortParam,
+    };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export { default as CrudPage } from './components/CrudPage.vue';
+export { default as CrudTable } from './components/CrudTable.vue';
+export { default as CrudCards } from './components/CrudCards.vue';
+export { default as CrudFilters } from './components/CrudFilters.vue';
+export { default as CrudPagination } from './components/CrudPagination.vue';
+export { default as CrudSearch } from './components/CrudSearch.vue';
+export { default as CrudDeleteDialog } from './components/CrudDeleteDialog.vue';
+export { default as CrudEmptyState } from './components/CrudEmptyState.vue';
+export { default as CrudToolbar } from './components/CrudToolbar.vue';
+export { default as CrudForm } from './components/CrudForm.vue';
+export { default as CrudShow } from './components/CrudShow.vue';
+
+export { useCrud, buildFilters } from './composables/useCrud';
+export type { UseCrudReturn } from './composables/useCrud';
+
+export type {
+    CrudColumn,
+    CrudFilter,
+    CrudFeatures,
+    CrudFeatureCreate,
+    CrudFeatureSearch,
+    CrudCardConfig,
+    CrudCardMeta,
+    CrudPageProps,
+    CrudFormField,
+    CrudShowField,
+    CrudShowSection,
+    CrudShowSidebarItem,
+    Paginator,
+    PaginatorLink,
+    FilterDocument,
+    UseCrudOptions,
+} from './types/crud';

package/src/lib/utils.ts

@@ -0,0 +1,18 @@
+import { InertiaLinkProps } from '@inertiajs/vue3';
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+}
+
+export function urlIsActive(
+    urlToCheck: NonNullable<InertiaLinkProps['href']>,
+    currentUrl: string,
+) {
+    return toUrl(urlToCheck) === currentUrl;
+}
+
+export function toUrl(href: NonNullable<InertiaLinkProps['href']>) {
+    return typeof href === 'string' ? href : href?.url;
+}

package/src/types/crud.ts

@@ -0,0 +1,133 @@
+export interface CrudColumn {
+    key: string;
+    title: string;
+    sortable?: boolean;
+    visible?: boolean;
+    width?: string;
+    align?: 'left' | 'center' | 'right';
+}
+
+export interface CrudFilter {
+    field: string;
+    label: string;
+    type: 'text' | 'select' | 'number' | 'date';
+    operator?: string;
+    options?: { label: string; value: string | number }[];
+    placeholder?: string;
+}
+
+export interface CrudFeatureCreate {
+    url: string;
+    label?: string;
+}
+
+export interface CrudFeatureSearch {
+    fields: string[];
+    placeholder?: string;
+}
+
+export interface CrudFeatures {
+    create?: boolean | CrudFeatureCreate;
+    show?: boolean;
+    edit?: boolean;
+    delete?: boolean;
+    search?: boolean | CrudFeatureSearch;
+    filters?: boolean | CrudFilter[];
+    sort?: boolean;
+    pagination?: boolean;
+    defaultSort?: string;
+}
+
+export interface CrudCardMeta {
+    label: string;
+    value: (item: Record<string, unknown>) => string;
+}
+
+export interface CrudCardConfig {
+    title: (item: Record<string, unknown>) => string;
+    subtitle?: (item: Record<string, unknown>) => string;
+    meta?: CrudCardMeta[];
+}
+
+export interface PaginatorLink {
+    url: string | null;
+    label: string;
+    active: boolean;
+}
+
+export interface Paginator<T = Record<string, unknown>> {
+    data: T[];
+    links: PaginatorLink[];
+    from: number | null;
+    to: number | null;
+    total: number;
+    current_page: number;
+    last_page: number;
+    per_page: number;
+}
+
+export interface CrudPageProps {
+    title: string;
+    description?: string;
+    items: Paginator;
+    columns: CrudColumn[];
+    features?: CrudFeatures;
+    card?: CrudCardConfig;
+    itemsPropName?: string;
+}
+
+export interface CrudFormField {
+    name: string;
+    label: string;
+    type: 'text' | 'email' | 'tel' | 'number' | 'select' | 'combobox' | 'textarea' | 'switch' | 'date' | 'password';
+    placeholder?: string;
+    required?: boolean;
+    options?: { label: string; value: string | number }[];
+    span?: 1 | 2;
+    tabindex?: number;
+    disabled?: boolean;
+}
+
+export interface CrudShowField {
+    label: string;
+    key?: string;
+    value?: unknown;
+    type?: 'text' | 'badge' | 'money' | 'email' | 'phone';
+    badgeClass?: string;
+    fallback?: string;
+}
+
+export interface CrudShowSection {
+    title: string;
+    icon?: string;
+    fields: CrudShowField[];
+    cols?: 1 | 2;
+}
+
+export interface CrudShowSidebarItem {
+    label: string;
+    key?: string;
+    value?: unknown;
+    type?: 'text' | 'badge';
+    badgeClass?: string;
+}
+
+export interface FilterDocument {
+    [operator: string]: Record<string, unknown>;
+}
+
+export interface UseCrudOptions {
+    onBeforeReload?: (
+        params: URLSearchParams,
+    ) =>
+        | URLSearchParams
+        | false
+        | void
+        | Promise<URLSearchParams | false | void>;
+    onError?: (error: unknown) => void;
+    buildCustomFilters?: (
+        state: Record<string, unknown>,
+        config: CrudFilter[],
+    ) => FilterDocument;
+    searchDebounce?: number;
+}