@maxal_studio/kratosjs-react 1.0.0

package/src/table/components/TableToolbar.tsx

@@ -0,0 +1,153 @@
+import React, { useState } from 'react';
+import { SerializedTable } from '@maxal_studio/kratosjs';
+import { Columns3Cog, LayoutDashboard } from 'lucide-react';
+import { TableSearchBar } from '../../components/table/TableSearchBar';
+import { LayoutToggle } from '../../components/table/LayoutToggle';
+import { ColumnTogglePopup } from '../../components/table/ColumnTogglePopup';
+import { Icon } from '../../components/utils/Icon';
+import { FiltersPanel } from './FiltersPanel';
+import { TableQueryApi } from '../hooks/useTableQuery';
+import { cn } from '../../utils/classNames';
+import { TableToolbarButton, TableToolbarIconButton } from './TableToolbarButton';
+import { translate } from '../../i18n/activeLocale';
+import { SlotCluster } from '../../slots/SlotCluster';
+
+export interface TableToolbarProps {
+	schema: SerializedTable;
+	query: TableQueryApi;
+	/** Layout switching (undefined hides the toggle) */
+	layout?: 'table' | 'grid';
+	onLayoutChange?: (layout: 'table' | 'grid') => void;
+	/** Column visibility */
+	visibleColumnNames: Set<string>;
+	onColumnToggle: (columnName: string, visible: boolean) => void;
+	/** Create button */
+	showCreateButton: boolean;
+	onCreateClick?: () => void;
+	onCreateModalOpen?: () => void;
+	/** Header actions (e.g. Export), rendered as buttons in the toolbar */
+	onHeaderAction?: (actionName: string) => void;
+	/** Widgets panel toggle (icon-only, sits with other toolbar controls) */
+	showWidgetsToggle?: boolean;
+	widgetsExpanded?: boolean;
+	onWidgetsToggle?: () => void;
+}
+
+/**
+ * The row of list controls above the table: search + create, filter
+ * trigger (dropdown layout), layout switch and column settings.
+ */
+export function TableToolbar({
+	schema,
+	query,
+	layout,
+	onLayoutChange,
+	visibleColumnNames,
+	onColumnToggle,
+	showCreateButton,
+	onCreateClick,
+	onCreateModalOpen,
+	onHeaderAction,
+	showWidgetsToggle,
+	widgetsExpanded,
+	onWidgetsToggle,
+}: TableToolbarProps) {
+	const [isColumnToggleOpen, setIsColumnToggleOpen] = useState(false);
+	const filtersLayout = schema.filtersLayout || 'inline';
+	const hasFilters = !!schema.filters && schema.filters.length > 0;
+	const headerActions = schema.headerActions || [];
+
+	return (
+		<div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-end sm:gap-3">
+			<div className="w-full min-w-0 sm:flex-1">
+				<TableSearchBar
+					searchable={schema.searchable || false}
+					searchQuery={query.searchQuery}
+					onSearchChange={query.handleSearch}
+					onCreateClick={onCreateClick}
+					onCreateModalOpen={onCreateModalOpen}
+					showCreateButton={showCreateButton}
+				/>
+			</div>
+
+			<div className="flex flex-wrap items-center justify-end gap-1 sm:gap-1.5">
+				<SlotCluster name="table.toolbar" context={{ schema }} />
+
+				{headerActions.map(action => (
+					<TableToolbarButton
+						key={action.name}
+						onClick={() => onHeaderAction?.(action.name)}
+						icon={action.icon ? <Icon name={action.icon} size={16} /> : undefined}>
+						{action.label || action.name}
+					</TableToolbarButton>
+				))}
+
+				{hasFilters && filtersLayout === 'dropdown' && (
+					<FiltersPanel
+						filters={schema.filters!}
+						values={query.filters}
+						queryBuilderValues={query.queryBuilders}
+						onChange={query.handleFilterChange}
+						onClear={query.handleClearFilters}
+						layout="dropdown"
+					/>
+				)}
+
+				{showWidgetsToggle && onWidgetsToggle && (
+					<TableToolbarIconButton
+						id="widgets-toggle"
+						className={cn(
+							'relative',
+							widgetsExpanded && 'bg-raised text-accent shadow-soft-sm ring-1 ring-accent/30',
+						)}
+						onClick={onWidgetsToggle}
+						aria-expanded={widgetsExpanded}
+						aria-pressed={widgetsExpanded}
+						aria-controls="widgets-content"
+						title={
+							widgetsExpanded
+								? translate('core:table.hide_widgets')
+								: translate('core:table.show_widgets')
+						}
+						aria-label={
+							widgetsExpanded
+								? translate('core:table.hide_widgets')
+								: translate('core:table.show_widgets')
+						}>
+						<LayoutDashboard className="h-4 w-4" />
+						{widgetsExpanded && (
+							<span
+								className="absolute right-1 top-1 h-1.5 w-1.5 rounded-full bg-accent ring-2 ring-base"
+								aria-hidden
+							/>
+						)}
+					</TableToolbarIconButton>
+				)}
+
+				{schema.allowLayoutSwitch && layout && onLayoutChange && (
+					<LayoutToggle layout={layout} onLayoutChange={onLayoutChange} />
+				)}
+
+				{schema.showColumnSettings !== false && (
+					<div className="relative">
+						<TableToolbarIconButton
+							className={cn(isColumnToggleOpen && 'bg-raised text-fg shadow-soft-sm')}
+							aria-label={translate('core:table.column_settings')}
+							title={translate('core:table.column_settings')}
+							aria-expanded={isColumnToggleOpen}
+							onClick={() => setIsColumnToggleOpen(!isColumnToggleOpen)}>
+							<Columns3Cog className="h-4 w-4" />
+						</TableToolbarIconButton>
+						<ColumnTogglePopup
+							columns={schema.columns}
+							visibleColumnNames={visibleColumnNames}
+							onToggle={onColumnToggle}
+							isOpen={isColumnToggleOpen}
+							onClose={() => setIsColumnToggleOpen(false)}
+						/>
+					</div>
+				)}
+			</div>
+		</div>
+	);
+}

package/src/table/components/TableToolbarButton.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { cn } from '../../utils/classNames';
+import { PillButton, PillIconButton } from '../../components/ui/PillButton';
+
+export type TableToolbarButtonProps = React.ComponentProps<typeof PillButton>;
+export type TableToolbarIconButtonProps = React.ComponentProps<typeof PillIconButton>;
+
+export function TableToolbarButton(props: TableToolbarButtonProps) {
+	return <PillButton {...props} />;
+}
+
+export function TableToolbarIconButton({ className, ...props }: TableToolbarIconButtonProps) {
+	return <PillIconButton className={cn('text-fg-secondary hover:text-fg', className)} {...props} />;
+}

package/src/table/components/TableView.tsx

@@ -0,0 +1,106 @@
+import React from 'react';
+import { TableHeader } from '../../components/table/TableHeader';
+import { TableRow } from '../../components/table/TableRow';
+import { Spinner } from '../../components/ui/Spinner';
+import { EmptyState } from '../../components/ui/EmptyState';
+import { ErrorAlert } from '../../components/ui/ErrorAlert';
+import { useTableContext } from '../TableContext';
+import { TableQueryApi } from '../hooks/useTableQuery';
+import { cn } from '../../utils/classNames';
+import { translate } from '../../i18n/activeLocale';
+
+export interface TableViewProps {
+	query: TableQueryApi;
+	/** When true, outer card wrapper is omitted (parent provides the surface). */
+	embedded?: boolean;
+}
+
+/**
+ * The classic table layout: header, rows, loading/empty states.
+ * All row state and handlers come from TableContext.
+ */
+export function TableView({ query, embedded = false }: TableViewProps) {
+	const {
+		schema,
+		visibleColumns,
+		visibleActions,
+		data,
+		isLoading,
+		error,
+		setError,
+		selectedRows,
+		changedRows,
+		openActionsRowId,
+		onToggleActions,
+		onRowSelect,
+		onSelectAll,
+		onCellChange,
+		onRowAction,
+		onSaveRow,
+		onResetRow,
+	} = useTableContext();
+
+	const colSpan = visibleColumns.length + (schema.bulkActions?.length ? 1 : 0) + 1;
+
+	return (
+		<div className={cn(!embedded && 'overflow-hidden rounded-xl border border-border bg-surface')}>
+			<div className="w-full overflow-x-auto">
+				{error ? <ErrorAlert className="m-4" message={error} onDismiss={() => setError(null)} /> : null}
+				<table className="w-full min-w-full" style={{ tableLayout: 'auto' }}>
+					<TableHeader
+						schema={schema}
+						visibleColumns={visibleColumns}
+						sortColumn={query.sortColumn}
+						sortDirection={query.sortDirection}
+						onSort={query.handleSort}
+						selectedRowsCount={selectedRows.size}
+						totalRows={data.length}
+						onSelectAll={onSelectAll}
+					/>
+					<tbody>
+						{isLoading ? (
+							<tr>
+								<td colSpan={colSpan} className="px-4 py-12 text-center">
+									<Spinner label={translate('core:common.loading_ellipsis')} />
+								</td>
+							</tr>
+						) : data.length === 0 ? (
+							<tr>
+								<td colSpan={colSpan}>
+									<EmptyState
+										title={translate('core:table.no_records')}
+										description={translate('core:table.no_records_hint')}
+									/>
+								</td>
+							</tr>
+						) : (
+							data.map((row, rowIndex) => {
+								const rowId = row.id || row._id || rowIndex;
+								return (
+									<TableRow
+										key={rowId}
+										schema={{ ...schema, actions: visibleActions }}
+										row={row}
+										rowIndex={rowIndex}
+										totalRows={data.length}
+										rowId={rowId}
+										visibleColumns={visibleColumns}
+										isSelected={selectedRows.has(rowId)}
+										hasChanges={changedRows.has(rowId)}
+										openActionsRowId={openActionsRowId}
+										onRowSelect={onRowSelect}
+										onCellChange={onCellChange}
+										onRowAction={onRowAction}
+										onSaveRow={onSaveRow}
+										onResetRow={onResetRow}
+										onToggleActions={onToggleActions}
+									/>
+								);
+							})
+						)}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	);
+}

package/src/table/defaultRowActions.ts

@@ -0,0 +1,43 @@
+import { SerializedAction } from '@maxal_studio/kratosjs';
+import { translate } from '../i18n/activeLocale';
+
+/**
+ * Built-in row actions are derived from the resource capability flags
+ * (canView / canEdit / canDelete). The `view` / `edit` / `delete` names are
+ * handled by name in useTableActions (delete shows its own confirmation), so
+ * these descriptors only carry the label/icon/color used to render the buttons.
+ */
+export const BUILT_IN_ACTION_NAMES = ['view', 'edit', 'delete'];
+
+/**
+ * Build the effective row actions for a table: built-in view/edit (from
+ * capabilities), then custom actions, then delete last. Any custom action that
+ * reuses a built-in name is dropped to avoid duplicates.
+ *
+ * Built-in labels are translated here (per call, at render time) so they follow
+ * the active locale instead of freezing at module load.
+ */
+export function buildRowActions(
+	customActions: SerializedAction[] | undefined,
+	caps: { canView: boolean; canEdit: boolean; canDelete: boolean },
+): SerializedAction[] {
+	const custom = (customActions || []).filter(action => !BUILT_IN_ACTION_NAMES.includes(action.name));
+	const result: SerializedAction[] = [];
+	if (caps.canView) {
+		result.push({ type: 'action', name: 'view', label: translate('core:common.view'), icon: 'Eye' });
+	}
+	if (caps.canEdit) {
+		result.push({ type: 'action', name: 'edit', label: translate('core:common.edit'), icon: 'Pencil' });
+	}
+	result.push(...custom);
+	if (caps.canDelete) {
+		result.push({
+			type: 'action',
+			name: 'delete',
+			label: translate('core:common.delete'),
+			icon: 'Trash2',
+			color: 'text-red-600',
+		});
+	}
+	return result;
+}

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

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useColumnVisibility } from './useColumnVisibility';
+
+const columns = [
+	{ name: 'id', toggleable: false },
+	{ name: 'name' },
+	{ name: 'email' },
+	{ name: 'internal', hidden: true },
+	{ name: 'notes', toggledHiddenByDefault: true },
+] as any[];
+
+describe('useColumnVisibility', () => {
+	beforeEach(() => {
+		localStorage.clear();
+	});
+
+	it('hides toggledHiddenByDefault columns on first visit and persists the default', () => {
+		const { result } = renderHook(() => useColumnVisibility(columns, 'users'));
+
+		expect(result.current.visibleColumns.map(c => c.name)).toEqual(['id', 'name', 'email']);
+		expect(JSON.parse(localStorage.getItem('kratosjs_column_visibility_users')!)).toEqual(['notes']);
+	});
+
+	it('always renders non-toggleable columns and never renders hidden ones', () => {
+		const { result } = renderHook(() => useColumnVisibility(columns, 'users'));
+		const names = result.current.visibleColumns.map(c => c.name);
+		expect(names).toContain('id');
+		expect(names).not.toContain('internal');
+	});
+
+	it('respects stored preferences', () => {
+		localStorage.setItem('kratosjs_column_visibility_users', JSON.stringify(['email']));
+		const { result } = renderHook(() => useColumnVisibility(columns, 'users'));
+		expect(result.current.visibleColumns.map(c => c.name)).toEqual(['id', 'name', 'notes']);
+	});
+
+	it('toggling persists to localStorage and updates the view', () => {
+		const { result } = renderHook(() => useColumnVisibility(columns, 'users'));
+
+		act(() => result.current.handleColumnToggle('email', false));
+		expect(result.current.visibleColumns.map(c => c.name)).toEqual(['id', 'name']);
+		expect(JSON.parse(localStorage.getItem('kratosjs_column_visibility_users')!).sort()).toEqual([
+			'email',
+			'notes',
+		]);
+
+		act(() => result.current.handleColumnToggle('notes', true));
+		expect(result.current.visibleColumns.map(c => c.name)).toEqual(['id', 'name', 'notes']);
+	});
+});

package/src/table/hooks/useColumnVisibility.ts

@@ -0,0 +1,71 @@
+import { useEffect, useMemo, useState } from 'react';
+import { SerializedColumn } from '@maxal_studio/kratosjs';
+import { columnVisibilityStorage } from '../../utils/columnVisibilityStorage';
+
+export interface ColumnVisibilityApi {
+	/** Names of toggleable columns currently visible */
+	visibleColumnNames: Set<string>;
+	/** Columns to actually render (respects hidden/toggleable/user prefs) */
+	visibleColumns: SerializedColumn[];
+	handleColumnToggle: (columnName: string, visible: boolean) => void;
+}
+
+function toggleableOf(columns: SerializedColumn[] | undefined): SerializedColumn[] {
+	return (columns || []).filter(col => col.hidden !== true && col.toggleable !== false);
+}
+
+/**
+ * localStorage-backed column visibility, keyed per resource.
+ * On first visit, columns flagged toggledHiddenByDefault are persisted as hidden.
+ */
+export function useColumnVisibility(columns: SerializedColumn[] | undefined, resourceKey: string): ColumnVisibilityApi {
+	const [hiddenColumns, setHiddenColumns] = useState<string[]>(() => {
+		const stored = columnVisibilityStorage.getHiddenColumns(resourceKey);
+		if (stored !== null) {
+			return stored;
+		}
+		// First visit: apply schema defaults
+		return toggleableOf(columns)
+			.filter(col => col.toggledHiddenByDefault === true)
+			.map(col => col.name);
+	});
+
+	// Persist defaults on first visit, and re-sync when the resource changes
+	useEffect(() => {
+		if (!columns || columns.length === 0) return;
+		const stored = columnVisibilityStorage.getHiddenColumns(resourceKey);
+		if (stored === null) {
+			const defaults = toggleableOf(columns)
+				.filter(col => col.toggledHiddenByDefault === true)
+				.map(col => col.name);
+			columnVisibilityStorage.setHiddenColumns(resourceKey, defaults);
+			setHiddenColumns(defaults);
+		} else {
+			setHiddenColumns(stored);
+		}
+	}, [columns, resourceKey]);
+
+	const visibleColumnNames = useMemo(() => {
+		const visible = new Set<string>(toggleableOf(columns).map(col => col.name));
+		hiddenColumns.forEach(name => visible.delete(name));
+		return visible;
+	}, [columns, hiddenColumns]);
+
+	const visibleColumns = useMemo(() => {
+		return (columns || []).filter(col => {
+			if (col.hidden) return false;
+			if (col.toggleable === false) return true;
+			return visibleColumnNames.has(col.name);
+		});
+	}, [columns, visibleColumnNames]);
+
+	const handleColumnToggle = (columnName: string, visible: boolean) => {
+		setHiddenColumns(prev => {
+			const next = visible ? prev.filter(name => name !== columnName) : [...new Set([...prev, columnName])];
+			columnVisibilityStorage.setHiddenColumns(resourceKey, next);
+			return next;
+		});
+	};
+
+	return { visibleColumnNames, visibleColumns, handleColumnToggle };
+}

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

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useState } from 'react';
+import { useEditableRows } from './useEditableRows';
+
+const initialRows = [
+	{ id: 1, name: 'Jane' },
+	{ id: 2, name: 'Bob' },
+];
+
+function setup(saveRecord = vi.fn().mockResolvedValue(undefined), onSaveError?: (e: Error) => void) {
+	const hook = renderHook(() => {
+		const [data, setData] = useState(initialRows);
+		const editable = useEditableRows({ data, setData, saveRecord, onSaveError });
+		return { data, editable };
+	});
+	act(() => hook.result.current.editable.resetTracking(initialRows));
+	return hook;
+}
+
+describe('useEditableRows', () => {
+	it('tracks cell changes optimistically', () => {
+		const hook = setup();
+		act(() => hook.result.current.editable.handleCellChange(1, 'name', 'Janet'));
+
+		expect(hook.result.current.data.find(r => r.id === 1)?.name).toBe('Janet');
+		expect(hook.result.current.editable.changedRows.get(1)).toEqual({ name: 'Janet' });
+	});
+
+	it('saves only the changed cells and clears the dirty state', async () => {
+		const saveRecord = vi.fn().mockResolvedValue(undefined);
+		const hook = setup(saveRecord);
+
+		act(() => hook.result.current.editable.handleCellChange(1, 'name', 'Janet'));
+		await act(() => hook.result.current.editable.handleSaveRow(1));
+
+		expect(saveRecord).toHaveBeenCalledWith(1, { name: 'Janet' });
+		expect(hook.result.current.editable.changedRows.has(1)).toBe(false);
+	});
+
+	it('reset restores the original row values', () => {
+		const hook = setup();
+		act(() => hook.result.current.editable.handleCellChange(2, 'name', 'Robert'));
+		expect(hook.result.current.data.find(r => r.id === 2)?.name).toBe('Robert');
+
+		act(() => hook.result.current.editable.handleResetRow(2));
+		expect(hook.result.current.data.find(r => r.id === 2)?.name).toBe('Bob');
+		expect(hook.result.current.editable.changedRows.has(2)).toBe(false);
+	});
+
+	it('reports save failures and keeps the dirty state', async () => {
+		const onSaveError = vi.fn();
+		const saveRecord = vi.fn().mockRejectedValue(new Error('boom'));
+		const hook = setup(saveRecord, onSaveError);
+
+		act(() => hook.result.current.editable.handleCellChange(1, 'name', 'Janet'));
+		await act(() => hook.result.current.editable.handleSaveRow(1));
+
+		expect(onSaveError).toHaveBeenCalled();
+		expect(hook.result.current.editable.changedRows.has(1)).toBe(true);
+	});
+
+	it('does nothing when saving a row without changes', async () => {
+		const saveRecord = vi.fn();
+		const hook = setup(saveRecord);
+		await act(() => hook.result.current.editable.handleSaveRow(1));
+		expect(saveRecord).not.toHaveBeenCalled();
+	});
+});

package/src/table/hooks/useEditableRows.ts

@@ -0,0 +1,89 @@
+import React, { useState } from 'react';
+
+export interface EditableRowsApi {
+	changedRows: Map<any, any>;
+	handleCellChange: (rowId: any, columnName: string, newValue: any) => void;
+	handleSaveRow: (rowId: any) => Promise<void>;
+	handleResetRow: (rowId: any) => void;
+	/** Reset change tracking after a (re)load */
+	resetTracking: (rows: any[]) => void;
+}
+
+export interface UseEditableRowsOptions {
+	data: any[];
+	setData: React.Dispatch<React.SetStateAction<any[]>>;
+	/** Persists the changed cells of one row */
+	saveRecord: (rowId: any, changes: any) => Promise<void>;
+	/** Notified when a save fails (e.g. show a toast) */
+	onSaveError?: (error: Error) => void;
+}
+
+const rowIdOf = (row: any) => row.id || row._id;
+
+/**
+ * Change tracking for inline-editable columns: per-row dirty state,
+ * optimistic cell updates, save and reset.
+ */
+export function useEditableRows({ data, setData, saveRecord, onSaveError }: UseEditableRowsOptions): EditableRowsApi {
+	const [changedRows, setChangedRows] = useState<Map<any, any>>(new Map());
+	const [originalData, setOriginalData] = useState<Map<any, any>>(new Map());
+
+	const resetTracking = (rows: any[]) => {
+		const originalMap = new Map();
+		rows.forEach(row => originalMap.set(rowIdOf(row), { ...row }));
+		setOriginalData(originalMap);
+		setChangedRows(new Map());
+	};
+
+	const handleCellChange = (rowId: any, columnName: string, newValue: any) => {
+		// Optimistic UI update
+		setData(prevData => prevData.map(row => (rowIdOf(row) === rowId ? { ...row, [columnName]: newValue } : row)));
+
+		setChangedRows(prev => {
+			const next = new Map(prev);
+			next.set(rowId, { ...(next.get(rowId) || {}), [columnName]: newValue });
+			return next;
+		});
+	};
+
+	const handleSaveRow = async (rowId: any) => {
+		const changes = changedRows.get(rowId);
+		if (!changes) return;
+
+		try {
+			await saveRecord(rowId, changes);
+
+			// The saved row becomes the new original
+			setOriginalData(prev => {
+				const next = new Map(prev);
+				const currentRow = data.find(row => rowIdOf(row) === rowId);
+				if (currentRow) {
+					next.set(rowId, { ...currentRow });
+				}
+				return next;
+			});
+			setChangedRows(prev => {
+				const next = new Map(prev);
+				next.delete(rowId);
+				return next;
+			});
+		} catch (err) {
+			console.error('Error saving row:', err);
+			onSaveError?.(err instanceof Error ? err : new Error('Failed to save changes'));
+		}
+	};
+
+	const handleResetRow = (rowId: any) => {
+		const original = originalData.get(rowId);
+		if (!original) return;
+
+		setData(prevData => prevData.map(row => (rowIdOf(row) === rowId ? { ...original } : row)));
+		setChangedRows(prev => {
+			const next = new Map(prev);
+			next.delete(rowId);
+			return next;
+		});
+	};
+
+	return { changedRows, handleCellChange, handleSaveRow, handleResetRow, resetTracking };
+}