@maxal_studio/kratosjs-react 1.0.0

package/src/table/hooks/useTableActions.ts

@@ -0,0 +1,393 @@
+import { useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { SerializedForm, SerializedTable } from '@maxal_studio/kratosjs';
+import { TableApiClient } from '../../api/tableApi';
+import { executeAction, executeBulkAction } from '../../api/actionsApi';
+import { downloadExport } from '../../api/exportApi';
+import { handleRedirect } from '../../utils/redirectHandler';
+import { useConfirm } from '../../components/ui/ConfirmDialog';
+import { useToast } from '../../components/ui/Toast';
+import { useResourceModal } from '../../contexts/ResourceModalContext';
+import { translate } from '../../i18n/activeLocale';
+
+export interface ActionFormModalState {
+	actionName: string;
+	recordIds: string[];
+	formSchema: SerializedForm;
+	isBulk?: boolean;
+	requiresConfirmation?: boolean;
+	modalDescription?: string;
+}
+
+export interface TableActionsApi {
+	selectedRows: Set<any>;
+	handleRowSelect: (id: any) => void;
+	handleSelectAll: () => void;
+	clearSelection: () => void;
+	handleRowAction: (actionName: string, rowId: any) => Promise<void>;
+	handleBulkAction: (actionName: string, selectedIds: any[]) => Promise<void>;
+	handleHeaderAction: (actionName: string) => Promise<void>;
+	actionFormModal: ActionFormModalState | null;
+	setActionFormModal: (state: ActionFormModalState | null) => void;
+}
+
+export interface UseTableActionsOptions {
+	schema: SerializedTable & { canCreate?: boolean; canEdit?: boolean; canDelete?: boolean; canView?: boolean };
+	apiClient: TableApiClient;
+	apiBaseUrl: string;
+	resourceSlug: string;
+	relatedResourceSlug?: string;
+	relatedResourceApiUrl?: string;
+	apiUrl: string;
+	canEdit: boolean;
+	canDelete: boolean;
+	canView: boolean;
+	data: any[];
+	reload: () => Promise<void>;
+	setError: (error: string | null) => void;
+	setIsLoading: (loading: boolean) => void;
+	/** Current table query (search/filters/sort), used by header exports. */
+	getQueryParams?: () => Record<string, any>;
+	onRowAction?: (action: string, rowId: any) => Promise<void> | void;
+	onBulkAction?: (action: string, selectedIds: any[]) => Promise<void> | void;
+	onEditClick?: (rowId: any) => void;
+	onViewClick?: (rowId: any) => void;
+}
+
+/**
+ * Row selection plus the row/bulk action pipeline: view/edit modal routing,
+ * delete with confirmation, handler actions (with optional form modal or
+ * confirmation), redirects and toasts.
+ */
+export function useTableActions(options: UseTableActionsOptions): TableActionsApi {
+	const {
+		schema,
+		apiClient,
+		apiBaseUrl,
+		resourceSlug,
+		relatedResourceSlug,
+		relatedResourceApiUrl,
+		apiUrl,
+		canEdit,
+		canDelete,
+		canView,
+		data,
+		reload,
+		setError,
+		setIsLoading,
+		getQueryParams,
+		onRowAction,
+		onBulkAction,
+		onEditClick,
+		onViewClick,
+	} = options;
+
+	const navigate = useNavigate();
+	const confirm = useConfirm();
+	const toast = useToast();
+	const { openModal } = useResourceModal();
+
+	const [selectedRows, setSelectedRows] = useState<Set<any>>(new Set());
+	const [actionFormModal, setActionFormModal] = useState<ActionFormModalState | null>(null);
+
+	const handleRowSelect = (id: any) => {
+		setSelectedRows(prev => {
+			const next = new Set(prev);
+			if (next.has(id)) {
+				next.delete(id);
+			} else {
+				next.add(id);
+			}
+			return next;
+		});
+	};
+
+	const handleSelectAll = () => {
+		setSelectedRows(prev =>
+			prev.size === data.length && data.length > 0 ? new Set() : new Set(data.map(row => row.id || row._id)),
+		);
+	};
+
+	const clearSelection = () => setSelectedRows(new Set());
+
+	/** For relation tables, mutations go to the related resource's own endpoint */
+	const clientForMutations = () => {
+		if (relatedResourceSlug && apiBaseUrl) {
+			const url = relatedResourceApiUrl || `${apiBaseUrl}/${relatedResourceSlug}`;
+			return new TableApiClient(apiBaseUrl, url, '/list');
+		}
+		return apiClient;
+	};
+
+	const actionApiUrl = () =>
+		relatedResourceSlug && apiBaseUrl ? `${apiBaseUrl}/${relatedResourceSlug}` : relatedResourceApiUrl || apiUrl;
+
+	/** Run an export (download) action, optionally scoped to selected record ids. */
+	const runExport = async (format: string, actionName: string, recordIds?: any[]) => {
+		setIsLoading(true);
+		setError(null);
+		try {
+			await downloadExport(actionApiUrl(), apiBaseUrl, {
+				format,
+				action: actionName,
+				query: recordIds && recordIds.length > 0 ? undefined : getQueryParams?.() || {},
+				recordIds,
+			});
+		} catch (err: any) {
+			setError(err.message || translate('core:error.export_failed'));
+			console.error('Error exporting:', err);
+		} finally {
+			setIsLoading(false);
+		}
+	};
+
+	const deleteRecords = async (ids: any[]) => {
+		setIsLoading(true);
+		setError(null);
+		try {
+			await clientForMutations().deleteRecords(ids);
+			toast.success(ids.length === 1 ? 'Item deleted successfully' : `${ids.length} items deleted successfully`);
+		} catch (err: any) {
+			setError(err.message || translate('core:error.delete_failed'));
+			console.error('Error deleting:', err);
+		} finally {
+			await reload();
+			setIsLoading(false);
+		}
+	};
+
+	const handleRowAction = async (actionName: string, rowId: any) => {
+		const actionConfig = schema.actions?.find(a => a.name === actionName);
+
+		if (actionName === 'view') {
+			if (!canView) return;
+			if (onViewClick) {
+				onViewClick(rowId);
+				return;
+			}
+			openModal(resourceSlug, 'view', rowId);
+			return;
+		}
+
+		if (actionName === 'edit') {
+			if (!canEdit) return;
+			if (onEditClick) {
+				onEditClick(rowId);
+				return;
+			}
+			openModal(resourceSlug, 'edit', rowId);
+			return;
+		}
+
+		if (actionName === 'delete') {
+			if (!canDelete) return;
+			const confirmed = await confirm({
+				title: translate('core:confirm.delete_item_title'),
+				message: translate('core:confirm.delete_item_message'),
+				confirmLabel: translate('core:common.delete'),
+				danger: true,
+			});
+			if (!confirmed) return;
+			await deleteRecords([rowId]);
+			return;
+		}
+
+		if (actionConfig?.hasHandler) {
+			if (actionConfig.form) {
+				setActionFormModal({
+					actionName,
+					recordIds: [rowId],
+					formSchema: actionConfig.form,
+					isBulk: false,
+					requiresConfirmation: actionConfig.requiresConfirmation,
+					modalDescription: actionConfig.modalDescription,
+				});
+				openModal(resourceSlug, 'action', rowId, actionName, actionConfig.label);
+				return;
+			}
+
+			if (actionConfig.requiresConfirmation) {
+				const confirmed = await confirm({
+					title: actionConfig.label || actionName,
+					message:
+						actionConfig.modalDescription ||
+						translate('core:confirm.action_single', { action: actionName }),
+				});
+				if (!confirmed) return;
+			}
+
+			setIsLoading(true);
+			setError(null);
+			try {
+				const result = await executeAction(actionApiUrl(), actionName, rowId, {});
+
+				if (handleRedirect(result, navigate) || (result.data && handleRedirect(result.data, navigate))) {
+					return;
+				}
+
+				if (result.success) {
+					if (result.message) {
+						toast.success(result.message);
+					}
+				} else {
+					setError(result.message || translate('core:form.action_failed'));
+				}
+			} catch (err: any) {
+				setError(err.message || translate('core:error.action_failed'));
+				console.error('Error executing action:', err);
+			} finally {
+				await reload();
+				setIsLoading(false);
+			}
+			return;
+		}
+
+		if (onRowAction) {
+			await onRowAction(actionName, rowId);
+		}
+	};
+
+	const handleBulkAction = async (actionName: string, selectedIds: any[]) => {
+		const actionConfig = schema.bulkActions?.find(a => a.name === actionName);
+
+		if (actionName === 'delete' || actionName === 'bulkDelete') {
+			if (!canDelete) return;
+			const confirmed = await confirm({
+				title: translate('core:confirm.delete_items_title'),
+				message: translate('core:confirm.delete_items_message', { count: selectedIds.length }),
+				confirmLabel: translate('core:common.delete'),
+				danger: true,
+			});
+			if (!confirmed) return;
+			clearSelection();
+			await deleteRecords(selectedIds);
+			return;
+		}
+
+		const exportFormat = (actionConfig as any)?.export as string | undefined;
+		if (exportFormat) {
+			await runExport(exportFormat, actionName, selectedIds);
+			return;
+		}
+
+		if (actionConfig?.hasHandler) {
+			if (actionConfig.form) {
+				setActionFormModal({
+					actionName,
+					recordIds: selectedIds,
+					formSchema: actionConfig.form,
+					isBulk: true,
+					requiresConfirmation: actionConfig.requiresConfirmation,
+					modalDescription: actionConfig.modalDescription,
+				});
+				openModal(resourceSlug, 'action', undefined, actionName, actionConfig.label);
+				return;
+			}
+
+			if (actionConfig.requiresConfirmation) {
+				const confirmed = await confirm({
+					title: actionConfig.label || actionName,
+					message:
+						actionConfig.modalDescription ||
+						translate('core:form.confirm_bulk', { action: actionName, count: selectedIds.length }),
+				});
+				if (!confirmed) return;
+			}
+
+			setIsLoading(true);
+			setError(null);
+			try {
+				const result = await executeBulkAction(actionApiUrl(), actionName, selectedIds, {});
+
+				if (result.success) {
+					if (result.message) {
+						toast.success(result.message);
+					}
+					if (actionConfig.deselectAfterCompletion !== false) {
+						clearSelection();
+					}
+				} else {
+					setError(result.message || translate('core:error.bulk_action_failed'));
+				}
+			} catch (err: any) {
+				setError(err.message || translate('core:error.action_failed_bulk'));
+				console.error('Error executing bulk action:', err);
+			} finally {
+				await reload();
+				setIsLoading(false);
+			}
+			return;
+		}
+
+		if (onBulkAction) {
+			await onBulkAction(actionName, selectedIds);
+			await reload();
+		}
+	};
+
+	const handleHeaderAction = async (actionName: string) => {
+		const actionConfig = (schema.headerActions as any[])?.find(a => a.name === actionName);
+		if (!actionConfig) return;
+
+		const exportFormat = actionConfig.export as string | undefined;
+		if (exportFormat) {
+			await runExport(exportFormat, actionName);
+			return;
+		}
+
+		// Handler-based header action (operates on no specific records).
+		if (actionConfig.hasHandler) {
+			if (actionConfig.form) {
+				setActionFormModal({
+					actionName,
+					recordIds: [],
+					formSchema: actionConfig.form,
+					isBulk: true,
+					requiresConfirmation: actionConfig.requiresConfirmation,
+					modalDescription: actionConfig.modalDescription,
+				});
+				openModal(resourceSlug, 'action', undefined, actionName, actionConfig.label);
+				return;
+			}
+
+			if (actionConfig.requiresConfirmation) {
+				const confirmed = await confirm({
+					title: actionConfig.label || actionName,
+					message:
+						actionConfig.modalDescription ||
+						translate('core:confirm.action_generic', { action: actionName }),
+				});
+				if (!confirmed) return;
+			}
+
+			setIsLoading(true);
+			setError(null);
+			try {
+				const result = await executeBulkAction(actionApiUrl(), actionName, [], {});
+				if (result.success) {
+					if (result.message) toast.success(result.message);
+				} else {
+					setError(result.message || translate('core:form.action_failed'));
+				}
+			} catch (err: any) {
+				setError(err.message || translate('core:error.action_failed'));
+				console.error('Error executing header action:', err);
+			} finally {
+				await reload();
+				setIsLoading(false);
+			}
+		}
+	};
+
+	return {
+		selectedRows,
+		handleRowSelect,
+		handleSelectAll,
+		clearSelection,
+		handleRowAction,
+		handleBulkAction,
+		handleHeaderAction,
+		actionFormModal,
+		setActionFormModal,
+	};
+}

package/src/table/hooks/useTableData.ts

@@ -0,0 +1,89 @@
+import React, { useEffect, useState } from 'react';
+import { QueryParams, TableApiClient } from '../../api/tableApi';
+import { translate } from '../../i18n/activeLocale';
+
+export interface TableDataApi {
+	data: any[];
+	setData: React.Dispatch<React.SetStateAction<any[]>>;
+	isLoading: boolean;
+	setIsLoading: (loading: boolean) => void;
+	error: string | null;
+	setError: (error: string | null) => void;
+	widgetData: Record<string, any>;
+	totalRecords: number;
+	/** Re-fetch with the current params */
+	reload: () => Promise<void>;
+}
+
+export interface UseTableDataOptions {
+	apiClient: TableApiClient;
+	queryParams: QueryParams;
+	/** Increment to force a refresh from outside */
+	refreshKey?: number;
+	/** Called with the fresh rows after every successful load */
+	onLoaded?: (rows: any[]) => void;
+}
+
+/**
+ * Fetches table rows whenever the query parameters (or refreshKey) change.
+ * Tolerates StrictMode double-effects: loads are idempotent and stale
+ * responses are dropped.
+ */
+export function useTableData({ apiClient, queryParams, refreshKey, onLoaded }: UseTableDataOptions): TableDataApi {
+	const [data, setData] = useState<any[]>([]);
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+	const [widgetData, setWidgetData] = useState<Record<string, any>>({});
+	const [totalRecords, setTotalRecords] = useState(0);
+	// Bumped by reload() so imperative refreshes re-run the effect
+	const [reloadCounter, setReloadCounter] = useState(0);
+
+	const onLoadedRef = React.useRef(onLoaded);
+	onLoadedRef.current = onLoaded;
+
+	useEffect(() => {
+		let cancelled = false;
+
+		const load = async () => {
+			setIsLoading(true);
+			try {
+				const result = await apiClient.fetchData(queryParams);
+				if (cancelled) return;
+				setData(result.data);
+				setTotalRecords(result.pagination.total);
+				setWidgetData(result.widgets || {});
+				setError(null);
+				onLoadedRef.current?.(result.data);
+			} catch (err) {
+				if (cancelled) return;
+				setError(err instanceof Error ? err.message : translate('core:error.load_data'));
+				console.error('Error loading table data:', err);
+			} finally {
+				if (!cancelled) {
+					setIsLoading(false);
+				}
+			}
+		};
+
+		load();
+		return () => {
+			cancelled = true;
+		};
+	}, [apiClient, queryParams, refreshKey, reloadCounter]);
+
+	const reload = async () => {
+		setReloadCounter(prev => prev + 1);
+	};
+
+	return {
+		data,
+		setData,
+		isLoading,
+		setIsLoading,
+		error,
+		setError,
+		widgetData,
+		totalRecords,
+		reload,
+	};
+}

package/src/table/hooks/useTableLayout.ts

@@ -0,0 +1,45 @@
+import { useEffect, useState } from 'react';
+import { SerializedTable } from '@maxal_studio/kratosjs';
+import { layoutStorage } from '../../utils/layoutStorage';
+import { widgetVisibilityStorage, getDefaultWidgetsExpanded } from '../../utils/widgetVisibilityStorage';
+
+export interface TableLayoutApi {
+	layout: 'table' | 'grid';
+	setLayout: (layout: 'table' | 'grid') => void;
+	widgetsExpanded: boolean;
+	setWidgetsExpanded: (expanded: boolean) => void;
+}
+
+/**
+ * Persisted presentation state: table-vs-grid layout (per resource) and
+ * the widgets expanded/collapsed preference (global).
+ */
+export function useTableLayout(schema: SerializedTable, resourceSlug: string): TableLayoutApi {
+	const [layout, setLayoutState] = useState<'table' | 'grid'>(() => {
+		const defaultLayout: 'table' | 'grid' = schema.defaultLayout === 'grid' ? 'grid' : 'table';
+		if (schema.allowLayoutSwitch) {
+			return layoutStorage.getLayout(resourceSlug, defaultLayout);
+		}
+		return defaultLayout;
+	});
+
+	const [widgetsExpanded, setWidgetsExpandedState] = useState(false);
+
+	// Hydrate widgets-expanded from localStorage (desktop default expanded)
+	useEffect(() => {
+		const stored = widgetVisibilityStorage.get();
+		setWidgetsExpandedState(stored !== null ? stored : getDefaultWidgetsExpanded());
+	}, []);
+
+	const setLayout = (next: 'table' | 'grid') => {
+		setLayoutState(next);
+		layoutStorage.setLayout(resourceSlug, next);
+	};
+
+	const setWidgetsExpanded = (next: boolean) => {
+		widgetVisibilityStorage.set(next);
+		setWidgetsExpandedState(next);
+	};
+
+	return { layout, setLayout, widgetsExpanded, setWidgetsExpanded };
+}

package/src/table/hooks/useTableQuery.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useTableQuery } from './useTableQuery';
+
+const makeSchema = (overrides: Record<string, unknown> = {}) =>
+	({
+		columns: [],
+		recordsPerPage: 25,
+		filters: [
+			{ name: 'status', type: 'select', default: 'active' },
+			{ name: 'advanced', type: 'queryBuilder' },
+		],
+		tabs: [
+			{ key: 'all', label: 'All' },
+			{ key: 'archived', label: 'Archived', queryBuilder: [{ field: 'archived', operator: 'eq', value: true }] },
+		],
+		defaultSort: { column: 'name', direction: 'asc' },
+		...overrides,
+	}) as any;
+
+/** The schema must be referentially stable across renders, as in real usage. */
+const renderQuery = (overrides: Record<string, unknown> = {}) => {
+	const schema = makeSchema(overrides);
+	return renderHook(() => useTableQuery(schema));
+};
+
+describe('useTableQuery', () => {
+	it('initializes from the schema', () => {
+		const { result } = renderQuery();
+		expect(result.current.sortColumn).toBe('name');
+		expect(result.current.sortDirection).toBe('asc');
+		expect(result.current.perPage).toBe(25);
+		expect(result.current.filters).toEqual({ status: 'active' });
+		expect(result.current.activeTab).toBeNull();
+	});
+
+	it('selects the default tab when one is flagged', () => {
+		const { result } = renderQuery({ tabs: [{ key: 'a' }, { key: 'b', default: true }] });
+		expect(result.current.activeTab).toBe('b');
+	});
+
+	it('toggles sort direction and resets the page', () => {
+		const { result } = renderQuery();
+		act(() => result.current.handlePageChange(3));
+		expect(result.current.currentPage).toBe(3);
+
+		act(() => result.current.handleSort('name'));
+		expect(result.current.sortDirection).toBe('desc');
+		expect(result.current.currentPage).toBe(1);
+
+		act(() => result.current.handleSort('email'));
+		expect(result.current.sortColumn).toBe('email');
+		expect(result.current.sortDirection).toBe('asc');
+	});
+
+	it('search resets the page', () => {
+		const { result } = renderQuery();
+		act(() => result.current.handlePageChange(2));
+		act(() => result.current.handleSearch('jane'));
+		expect(result.current.searchQuery).toBe('jane');
+		expect(result.current.currentPage).toBe(1);
+	});
+
+	it('manual filter change clears the active tab', () => {
+		const { result } = renderQuery();
+		act(() => result.current.handleTabClick('archived'));
+		expect(result.current.activeTab).toBe('archived');
+
+		act(() => result.current.handleFilterChange('status', 'inactive'));
+		expect(result.current.activeTab).toBeNull();
+		expect(result.current.filters).toEqual({ status: 'inactive' });
+	});
+
+	it('removes filters set to empty values', () => {
+		const { result } = renderQuery();
+		act(() => result.current.handleFilterChange('status', ''));
+		expect(result.current.filters).toEqual({});
+	});
+
+	it('merges active tab rules into queryParams as __activeTab', () => {
+		const { result } = renderQuery();
+		act(() => result.current.handleTabClick('archived'));
+		expect(result.current.queryParams.queryBuilders?.__activeTab).toEqual([
+			{ field: 'archived', operator: 'eq', value: true },
+		]);
+
+		act(() => result.current.handleTabClick(null));
+		expect(result.current.queryParams.queryBuilders).toBeUndefined();
+	});
+
+	it('tracks query-builder filters separately', () => {
+		const { result } = renderQuery();
+		const rules = [{ field: 'age', operator: 'gt', value: 18 }];
+		act(() => result.current.handleFilterChange('advanced', rules, true));
+		expect(result.current.queryBuilders.advanced).toEqual(rules);
+		expect(result.current.queryParams.queryBuilders?.advanced).toEqual(rules);
+
+		act(() => result.current.handleFilterChange('advanced', [], true));
+		expect(result.current.queryBuilders.advanced).toBeUndefined();
+	});
+
+	it('clear filters restores schema defaults', () => {
+		const { result } = renderQuery();
+		act(() => result.current.handleFilterChange('status', 'x'));
+		act(() => result.current.handleClearFilters());
+		expect(result.current.filters).toEqual({ status: 'active' });
+	});
+
+	it('page size change resets to page 1', () => {
+		const { result } = renderQuery();
+		act(() => result.current.handlePageChange(4));
+		act(() => result.current.handlePageSizeChange(50));
+		expect(result.current.perPage).toBe(50);
+		expect(result.current.currentPage).toBe(1);
+	});
+});