@maxal_studio/kratosjs-react 1.0.0

package/src/table/hooks/useTableQuery.ts

@@ -0,0 +1,172 @@
+import { useEffect, useMemo, useState } from 'react';
+import { SerializedTable } from '@maxal_studio/kratosjs';
+import { QueryParams } from '../../api/tableApi';
+
+export interface TableQueryState {
+	searchQuery: string;
+	sortColumn: string | undefined;
+	sortDirection: 'asc' | 'desc';
+	filters: Record<string, any>;
+	queryBuilders: Record<string, any[]>;
+	activeTab: string | null;
+	currentPage: number;
+	perPage: number;
+}
+
+export interface TableQueryApi extends TableQueryState {
+	handleSearch: (query: string) => void;
+	handleSort: (column: string) => void;
+	handleFilterChange: (name: string, value: any, isQueryBuilder?: boolean) => void;
+	handleTabClick: (tabKey: string | null) => void;
+	handleClearFilters: () => void;
+	handlePageChange: (page: number) => void;
+	handlePageSizeChange: (size: number) => void;
+	/** Request payload for TableApiClient.fetchData, with tab rules merged in */
+	queryParams: QueryParams;
+}
+
+/**
+ * All list-query state for a table: search, sort, filters, query builders,
+ * tabs, and pagination — plus the handlers that keep them consistent
+ * (changing any criterion resets to page 1; manual filtering clears the tab).
+ */
+export function useTableQuery(schema: SerializedTable): TableQueryApi {
+	// Filter defaults come from the schema
+	const initialFilters = useMemo(() => {
+		const defaults: Record<string, any> = {};
+		schema.filters?.forEach(filter => {
+			if (filter.default !== undefined && filter.type !== 'queryBuilder') {
+				defaults[filter.name] = filter.default;
+			}
+		});
+		return defaults;
+	}, [schema.filters]);
+
+	const initialQueryBuilders = useMemo(() => {
+		const defaults: Record<string, any[]> = {};
+		schema.filters?.forEach(filter => {
+			if (filter.type === 'queryBuilder' && Array.isArray(filter.default)) {
+				defaults[filter.name] = filter.default;
+			}
+		});
+		return defaults;
+	}, [schema.filters]);
+
+	const [searchQuery, setSearchQuery] = useState('');
+	const [sortColumn, setSortColumn] = useState<string | undefined>(schema.defaultSort?.column);
+	const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>(schema.defaultSort?.direction || 'asc');
+	const [filters, setFilters] = useState<Record<string, any>>(initialFilters);
+	const [queryBuilders, setQueryBuilders] = useState<Record<string, any[]>>(initialQueryBuilders);
+	const [activeTab, setActiveTab] = useState<string | null>(() => {
+		const tabs = schema.tabs as Array<{ default?: boolean; key: string }> | undefined;
+		return tabs?.find(tab => tab.default === true)?.key ?? null;
+	});
+	const [currentPage, setCurrentPage] = useState(1);
+	const [perPage, setPerPage] = useState(schema.recordsPerPage || 10);
+
+	// Reset filters to defaults when the schema changes
+	useEffect(() => {
+		setFilters(initialFilters);
+		setQueryBuilders(initialQueryBuilders);
+	}, [initialFilters, initialQueryBuilders]);
+
+	const handleSearch = (query: string) => {
+		setSearchQuery(query);
+		setCurrentPage(1);
+	};
+
+	const handleSort = (column: string) => {
+		setSortDirection(sortColumn === column && sortDirection === 'asc' ? 'desc' : 'asc');
+		setSortColumn(column);
+		setCurrentPage(1);
+	};
+
+	const handleFilterChange = (name: string, value: any, isQueryBuilder: boolean = false) => {
+		// Manual filtering clears the active tab
+		setActiveTab(null);
+
+		if (isQueryBuilder) {
+			setQueryBuilders(prev => {
+				const next = { ...prev };
+				if (value === undefined || (Array.isArray(value) && value.length === 0)) {
+					delete next[name];
+				} else {
+					next[name] = value;
+				}
+				return next;
+			});
+		} else {
+			setFilters(prev => {
+				const next = { ...prev };
+				if (value === '' || value === undefined) {
+					delete next[name];
+				} else {
+					next[name] = value;
+				}
+				return next;
+			});
+		}
+		setCurrentPage(1);
+	};
+
+	const handleTabClick = (tabKey: string | null) => {
+		setActiveTab(tabKey);
+		setCurrentPage(1);
+	};
+
+	const handleClearFilters = () => {
+		setFilters(initialFilters);
+		setQueryBuilders(initialQueryBuilders);
+		setCurrentPage(1);
+	};
+
+	const handlePageChange = (page: number) => {
+		setCurrentPage(page);
+	};
+
+	const handlePageSizeChange = (size: number) => {
+		setPerPage(size);
+		setCurrentPage(1);
+	};
+
+	const queryParams = useMemo<QueryParams>(() => {
+		// Merge the active tab's query-builder rules into the request
+		const finalQueryBuilders = { ...queryBuilders };
+		const tabs = schema.tabs as Array<{ key: string; queryBuilder?: any[] }> | undefined;
+		if (activeTab && tabs) {
+			const selectedTab = tabs.find(tab => tab.key === activeTab);
+			if (selectedTab?.queryBuilder && selectedTab.queryBuilder.length > 0) {
+				finalQueryBuilders.__activeTab = selectedTab.queryBuilder;
+			}
+		}
+
+		return {
+			page: currentPage,
+			perPage,
+			search: searchQuery || undefined,
+			sort: sortColumn,
+			sortDirection,
+			filters,
+			queryBuilders: Object.keys(finalQueryBuilders).length > 0 ? finalQueryBuilders : undefined,
+		};
+	}, [queryBuilders, schema.tabs, activeTab, currentPage, perPage, searchQuery, sortColumn, sortDirection, filters]);
+
+	return {
+		searchQuery,
+		sortColumn,
+		sortDirection,
+		filters,
+		queryBuilders,
+		activeTab,
+		currentPage,
+		perPage,
+		handleSearch,
+		handleSort,
+		handleFilterChange,
+		handleTabClick,
+		handleClearFilters,
+		handlePageChange,
+		handlePageSizeChange,
+		queryParams,
+	};
+}

package/src/test/mockFetch.ts

@@ -0,0 +1,67 @@
+import { vi } from 'vitest';
+
+export interface MockRoute {
+	/** Substring or RegExp matched against the request URL */
+	match: string | RegExp;
+	/** Optional HTTP method filter (defaults to any) */
+	method?: string;
+	status?: number;
+	headers?: Record<string, string>;
+	/** JSON body to respond with, or a function of (url, init) */
+	body: unknown | ((url: string, init?: RequestInit) => unknown);
+}
+
+export interface RecordedRequest {
+	url: string;
+	method: string;
+	body: unknown;
+}
+
+/**
+ * Stub global fetch with a small route table. Returns the list of recorded
+ * requests so tests can assert on payloads. Routes are matched in order;
+ * unmatched requests resolve with 404 to surface mistakes loudly.
+ */
+export function mockFetch(routes: MockRoute[]): RecordedRequest[] {
+	const requests: RecordedRequest[] = [];
+
+	vi.stubGlobal(
+		'fetch',
+		vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+			const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+			const method = (init?.method || 'GET').toUpperCase();
+			let parsedBody: unknown = undefined;
+			if (typeof init?.body === 'string') {
+				try {
+					parsedBody = JSON.parse(init.body);
+				} catch {
+					parsedBody = init.body;
+				}
+			}
+			requests.push({ url, method, body: parsedBody });
+
+			for (const route of routes) {
+				const urlMatches = typeof route.match === 'string' ? url.includes(route.match) : route.match.test(url);
+				const methodMatches = !route.method || route.method.toUpperCase() === method;
+				if (urlMatches && methodMatches) {
+					const body = typeof route.body === 'function' ? route.body(url, init) : route.body;
+					return new Response(JSON.stringify(body), {
+						status: route.status ?? 200,
+						headers: { 'Content-Type': 'application/json', ...route.headers },
+					});
+				}
+			}
+
+			return new Response(JSON.stringify({ message: `No mock route for ${method} ${url}` }), {
+				status: 404,
+				headers: { 'Content-Type': 'application/json' },
+			});
+		}),
+	);
+
+	return requests;
+}
+
+export function restoreFetch(): void {
+	vi.unstubAllGlobals();
+}

package/src/test/setup.ts

@@ -0,0 +1,25 @@
+import '@testing-library/jest-dom/vitest';
+import { afterEach } from 'vitest';
+import { cleanup } from '@testing-library/react';
+
+// Without vitest globals, React Testing Library cannot auto-register its
+// cleanup — do it explicitly so trees don't leak between tests.
+afterEach(() => {
+	cleanup();
+});
+
+// jsdom does not implement matchMedia; several components consult it for
+// responsive defaults (widgets expanded, dark-mode preference).
+if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') {
+	window.matchMedia = (query: string) =>
+		({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: () => {},
+			removeListener: () => {},
+			addEventListener: () => {},
+			removeEventListener: () => {},
+			dispatchEvent: () => false,
+		}) as MediaQueryList;
+}

package/src/types/index.ts

@@ -0,0 +1,228 @@
+import { SerializedForm, ValidationRules as KratosJsValidationRules } from '@maxal_studio/kratosjs';
+import { ColumnRegistry } from '../contexts/ColumnRegistryContext';
+import { WidgetComponent } from '../contexts/WidgetRegistryContext';
+import type { CustomBlockComponent } from '../contexts/BlockRegistryContext';
+import type { AuthChallengeRegistry } from '../contexts/AuthChallengeRegistryContext';
+import type { ClientI18nConfig } from '../i18n/buildClientI18n';
+import type { ResolvedSlots } from '../slots/types';
+
+/**
+ * Props passed to all field components
+ */
+export interface FieldProps {
+	type: string;
+	name: string;
+	label?: string;
+	statePath?: string;
+	default?: any;
+	hidden?: boolean;
+	disabled?: boolean;
+	mode?: 'edit' | 'view';
+	value?: any;
+	extraAttributes?: Record<string, any>;
+	validation?: KratosJsValidationRules;
+	helperText?: string;
+	hint?: string;
+	hintIcon?: string;
+	hintColor?: string;
+	autofocus?: boolean;
+	placeholder?: string;
+	readOnly?: boolean;
+	/** When true, view mode displays the value as HTML (TextInput, Textarea, TagsInput) */
+	renderHtml?: boolean;
+	inputType?: string;
+	minLength?: number;
+	maxLength?: number;
+	min?: number;
+	max?: number;
+	step?: number;
+	mask?: string;
+	prefix?: string;
+	suffix?: string;
+	options?: Record<string | number, string>;
+	multiple?: boolean;
+	isMultiple?: boolean;
+	searchable?: boolean;
+	creatable?: boolean;
+	// Relationship-based select properties
+	relationship?: {
+		name: string;
+		titleAttribute: string;
+		resource?: string;
+	};
+	createOptionForm?: any[]; // Form schema for creating new related records
+	createOptionModalHeading?: string;
+	optionLabelFormatter?: string; // Serialized function for formatting option labels
+	// TagsInput-specific properties
+	tags?: string[];
+	separator?: string;
+	suggestions?: string[];
+	/** When true, view mode shows tags in a popup (e.g. "N tags" click to open) */
+	showInPopup?: boolean;
+	selectablePlaceholder?: boolean;
+	rows?: number;
+	cols?: number;
+	format?: string;
+	displayFormat?: string;
+	minDate?: string;
+	maxDate?: string;
+	enableTime?: boolean;
+	onColor?: string;
+	offColor?: string;
+	onIcon?: string;
+	offIcon?: string;
+	// Repeater-specific properties
+	schema?: FieldProps[]; // Schema for Repeater and Group
+	defaultItems?: number;
+	minItems?: number;
+	maxItems?: number;
+	addable?: boolean;
+	deletable?: boolean;
+	reorderable?: boolean;
+	itemLabel?: string;
+	// FileUpload-specific properties
+	acceptedFileTypes?: string[];
+	maxSize?: number;
+	minSize?: number;
+	maxFiles?: number;
+	disk?: string;
+	directory?: string;
+	visibility?: 'public' | 'private';
+	// RichEditor-specific properties
+	toolbarButtons?: string[];
+	fileAttachments?: boolean;
+	embeds?: boolean;
+	htmlSource?: boolean;
+	extensions?: string[];
+	// Section-specific properties
+	heading?: string;
+	icon?: string;
+	collapsible?: boolean; // For both Repeater and Section
+	collapsed?: boolean;
+	compact?: boolean;
+	aside?: boolean;
+	// Column layout properties
+	columns?: number | Record<string, number>;
+	columnSpan?: number | string | Record<string, number | string>;
+	columnStart?: number | Record<string, number>;
+	required?: boolean;
+	/** Operation for conditional visibility (e.g. hidden(context => context.operation === 'view')) */
+	operation?: 'create' | 'edit' | 'view';
+	[key: string]: any;
+}
+
+/**
+ * Field component type
+ */
+export type FieldComponent = React.ComponentType<FieldProps>;
+
+/**
+ * Field registry mapping field types to components
+ */
+export type FieldRegistry = Record<string, FieldComponent>;
+
+/**
+ * Props for FormRenderer component
+ */
+export interface FormRendererProps {
+	schema: SerializedForm;
+	onSubmit: (data: any) => void | Promise<void>;
+	defaultValues?: Record<string, any>;
+	className?: string;
+	/** Base URL for API requests (e.g., 'http://localhost:3001/kratosjs/api') */
+	apiBaseUrl?: string;
+	/** Resource slug for media endpoints (e.g., 'users') */
+	resource?: string;
+	/** Operation type for conditional field visibility (e.g., 'create' | 'edit' | 'view') */
+	operation?: 'create' | 'edit' | 'view';
+	/** Children to render inside FormProvider (for watching form values) */
+	children?: React.ReactNode;
+}
+
+/**
+ * Props for FieldRenderer component
+ */
+export interface FieldRendererProps {
+	field: FieldProps;
+}
+
+/**
+ * Validation rules from React Hook Form (converted format)
+ */
+export interface RHFValidationRules {
+	required?: string | { value: boolean; message: string };
+	pattern?: { value: RegExp; message: string };
+	minLength?: { value: number; message: string };
+	maxLength?: { value: number; message: string };
+	min?: { value: number; message: string };
+	max?: { value: number; message: string };
+	validate?: Record<string, (value: any, formValues?: any) => boolean | string>;
+}
+
+/**
+ * Redirect response from API
+ */
+export interface RedirectResponse {
+	redirect: string;
+	message?: string;
+	[key: string]: any;
+}
+
+/**
+ * Type guard to check if response is a redirect response
+ */
+export function isRedirectResponse(data: any): data is RedirectResponse {
+	return typeof data === 'object' && data !== null && typeof data.redirect === 'string';
+}
+
+/**
+ * Relation metadata served by GET /:slug/relations, consumed by the view modal
+ */
+export interface SerializedRelation {
+	name: string;
+	type: 'hasMany';
+	canCreate?: boolean;
+	canEdit?: boolean;
+	canDelete?: boolean;
+	canView?: boolean;
+	resourceSlug: string;
+	/** Full API URL for the related resource */
+	resourceApiUrl?: string;
+	label: string;
+	pluralLabel: string;
+	icon?: string;
+	localKey: string;
+	foreignKey: string;
+	relatedKey: string;
+	// Optional grouping metadata (when backend RelationConfig defines a group)
+	groupKey?: string;
+	groupLabel?: string;
+	groupIcon?: string;
+}
+
+/**
+ * Widget registry mapping widget types to components
+ */
+export type WidgetRegistry = Record<string, WidgetComponent>;
+
+/**
+ * Block registry mapping custom block types to components
+ */
+export type BlockRegistry = Record<string, CustomBlockComponent>;
+
+/**
+ * Props for AdminPanel component
+ */
+export interface AdminPanelProps {
+	apiBaseUrl: string;
+	panelId?: string;
+	customFields?: FieldRegistry;
+	customColumns?: ColumnRegistry;
+	customWidgets?: WidgetRegistry;
+	customBlocks?: BlockRegistry;
+	customAuthChallenges?: AuthChallengeRegistry;
+	/** Merged, resolved slot contributions keyed by slot name. */
+	customSlots?: ResolvedSlots;
+	/** i18n config for UI chrome + app frontend strings (server-injected). */
+	i18nConfig?: ClientI18nConfig;
+}

package/src/utils/classNames.ts

@@ -0,0 +1,10 @@
+import clsx, { ClassValue } from 'clsx';
+
+/**
+ * Utility function to combine class names
+ * @param classes Class names to combine
+ * @returns Combined class name string
+ */
+export function cn(...classes: ClassValue[]): string {
+	return clsx(classes);
+}

package/src/utils/columnMediaDimensions.ts

@@ -0,0 +1,45 @@
+import type { CSSProperties } from 'react';
+
+interface ColumnMediaSizeOptions {
+	width?: number | string;
+	height?: number | string;
+	ratio?: string;
+	circular?: boolean;
+}
+
+/**
+ * Dimensions for image/media/video column thumbnails.
+ * Circular columns always render as a true square (1:1) so rounded-full clips a circle.
+ */
+export function getColumnMediaDimensions(
+	column: ColumnMediaSizeOptions,
+	defaultSize: number | string = 40,
+): CSSProperties {
+	if (column.circular) {
+		const raw = column.width ?? column.height ?? defaultSize;
+		const size = typeof raw === 'number' ? `${raw}px` : raw;
+		return {
+			width: size,
+			height: size,
+			minWidth: size,
+			minHeight: size,
+			flexShrink: 0,
+			aspectRatio: '1 / 1',
+		};
+	}
+
+	const ratio = column.ratio || '16/9';
+
+	if (column.width) {
+		const w = typeof column.width === 'number' ? `${column.width}px` : column.width;
+		return { width: w, minWidth: w, flexShrink: 0, aspectRatio: ratio };
+	}
+
+	if (column.height) {
+		const h = typeof column.height === 'number' ? `${column.height}px` : column.height;
+		return { height: h, minHeight: h, flexShrink: 0, aspectRatio: ratio };
+	}
+
+	const w = typeof defaultSize === 'number' ? `${defaultSize}px` : defaultSize;
+	return { width: w, minWidth: w, flexShrink: 0, aspectRatio: ratio };
+}

package/src/utils/columnVisibilityStorage.ts

@@ -0,0 +1,55 @@
+/**
+ * Column visibility storage utilities for managing column visibility preferences in localStorage
+ */
+export const columnVisibilityStorage = {
+	/**
+	 * Get hidden columns for a resource
+	 * @param resourceKey Unique identifier for the resource (e.g., 'users', 'users_posts')
+	 * @returns Array of hidden column names, or null if not found (never been set)
+	 */
+	getHiddenColumns(resourceKey: string): string[] | null {
+		try {
+			const key = `kratosjs_column_visibility_${resourceKey}`;
+			const stored = localStorage.getItem(key);
+			if (stored === null) {
+				return null;
+			}
+			const parsed = JSON.parse(stored);
+			if (Array.isArray(parsed)) {
+				return parsed;
+			}
+			return null;
+		} catch (error) {
+			console.warn('Failed to parse column visibility from localStorage:', error);
+			return null;
+		}
+	},
+
+	/**
+	 * Set hidden columns for a resource
+	 * @param resourceKey Unique identifier for the resource
+	 * @param hiddenColumns Array of column names that should be hidden
+	 */
+	setHiddenColumns(resourceKey: string, hiddenColumns: string[]): void {
+		try {
+			const key = `kratosjs_column_visibility_${resourceKey}`;
+			localStorage.setItem(key, JSON.stringify(hiddenColumns));
+		} catch (error) {
+			// Handle quota exceeded or other localStorage errors
+			if (error instanceof Error && error.name === 'QuotaExceededError') {
+				console.warn('localStorage quota exceeded, column visibility preferences not saved');
+			} else {
+				console.warn('Failed to save column visibility to localStorage:', error);
+			}
+		}
+	},
+
+	/**
+	 * Clear stored column visibility preferences for a resource
+	 * @param resourceKey Unique identifier for the resource
+	 */
+	clearHiddenColumns(resourceKey: string): void {
+		const key = `kratosjs_column_visibility_${resourceKey}`;
+		localStorage.removeItem(key);
+	},
+};

package/src/utils/fieldErrors.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import type { FieldErrors } from 'react-hook-form';
+import { getFieldError } from './fieldErrors';
+
+describe('getFieldError', () => {
+	it('resolves a flat field error', () => {
+		const errors = { email: { type: 'required', message: 'Required' } } as unknown as FieldErrors;
+		expect(getFieldError(errors, 'email')?.message).toBe('Required');
+	});
+
+	it('resolves a nested array (repeater row) error by dotted path', () => {
+		const errors = {
+			items: [{ name: { type: 'required', message: 'Row name required' } }],
+		} as unknown as FieldErrors;
+		expect(getFieldError(errors, 'items.0.name')?.message).toBe('Row name required');
+		expect(getFieldError(errors, 'items[0].name')?.message).toBe('Row name required');
+	});
+
+	it('returns undefined for a missing path', () => {
+		const errors = { items: [{ name: { type: 'min', message: 'x' } }] } as unknown as FieldErrors;
+		expect(getFieldError(errors, 'items.1.name')).toBeUndefined();
+		expect(getFieldError(errors, 'missing')).toBeUndefined();
+	});
+
+	it('does not treat a container node (array/object) as a field error', () => {
+		const errors = { items: [{ name: { type: 'required', message: 'x' } }] } as unknown as FieldErrors;
+		// `items` itself is the array container, not a leaf field error
+		expect(getFieldError(errors, 'items')).toBeUndefined();
+	});
+
+	it('is safe with undefined inputs', () => {
+		expect(getFieldError(undefined, 'a')).toBeUndefined();
+		expect(getFieldError({} as FieldErrors, undefined)).toBeUndefined();
+	});
+});

package/src/utils/fieldErrors.ts

@@ -0,0 +1,27 @@
+import type { FieldErrors, FieldError } from 'react-hook-form';
+
+/**
+ * Resolve a React Hook Form error by its (possibly nested) field-name path.
+ *
+ * RHF stores errors for nested / array fields as nested objects — e.g. a field
+ * registered as `items.0.name` lives at `errors.items[0].name`, NOT at the flat
+ * key `errors['items.0.name']`. Field components therefore can't find the error
+ * for a Repeater row (or any dotted name) with a plain `errors[name]` lookup.
+ *
+ * This walks the dot/bracket path so both flat names (`email`) and nested ones
+ * (`items.0.name`, `items[0].name`) resolve correctly.
+ */
+export function getFieldError(errors: FieldErrors | undefined, name: string | undefined): FieldError | undefined {
+	if (!errors || !name) return undefined;
+
+	const segments = name.split(/[.[\]]+/).filter(Boolean);
+	let current: any = errors;
+	for (const segment of segments) {
+		if (current == null) return undefined;
+		current = current[segment];
+	}
+
+	// A resolved node is an error only when it carries a `type`/`message`; nested
+	// containers (e.g. the array node `errors.items`) are not field errors.
+	return current && (current.type || current.message) ? (current as FieldError) : undefined;
+}