@maxal_studio/kratosjs-react 1.0.0

package/src/FormRenderer.test.tsx

@@ -0,0 +1,174 @@
+import { describe, expect, it, vi } from 'vitest';
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FormRenderer } from './FormRenderer';
+import { FieldRegistryProvider } from './contexts/FieldRegistryContext';
+
+function renderForm(schema: any, onSubmit = vi.fn(), defaultValues?: Record<string, any>) {
+	render(
+		<FieldRegistryProvider>
+			<FormRenderer schema={schema} onSubmit={onSubmit} defaultValues={defaultValues} />
+		</FieldRegistryProvider>,
+	);
+	return onSubmit;
+}
+
+describe('FormRenderer', () => {
+	it('renders basic field types', () => {
+		renderForm({
+			type: 'form',
+			components: [
+				{ type: 'text-input', name: 'name', label: 'Name' },
+				{ type: 'textarea', name: 'bio', label: 'Bio' },
+				{ type: 'checkbox', name: 'agree', label: 'Agree' },
+				{ type: 'hidden', name: 'secret', default: 'x' },
+			],
+		});
+
+		expect(screen.getByLabelText(/name/i)).toBeInTheDocument();
+		expect(screen.getByLabelText(/bio/i)).toBeInTheDocument();
+		expect(screen.getByText('Agree')).toBeInTheDocument();
+		expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument();
+	});
+
+	it('shows a warning box for unknown field types', () => {
+		renderForm({ type: 'form', components: [{ type: 'does-not-exist', name: 'x' }] });
+		expect(screen.getByText(/unknown field type "does-not-exist"/i)).toBeInTheDocument();
+	});
+
+	it('submits values including schema defaults', async () => {
+		const user = userEvent.setup();
+		const onSubmit = renderForm({
+			type: 'form',
+			components: [
+				{ type: 'text-input', name: 'name', label: 'Name' },
+				{ type: 'hidden', name: 'kind', default: 'admin' },
+			],
+		});
+
+		await user.type(screen.getByLabelText(/name/i), 'Jane');
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0]).toMatchObject({ name: 'Jane', kind: 'admin' });
+	});
+
+	it('extracts nested defaults from sections and groups', async () => {
+		const user = userEvent.setup();
+		const onSubmit = renderForm({
+			type: 'form',
+			components: [
+				{
+					type: 'section',
+					name: 'main',
+					heading: 'Main',
+					isLayout: true,
+					childScope: 'inherit',
+					schema: [{ type: 'text-input', name: 'inner', label: 'Inner', default: 'preset' }],
+				},
+			],
+		});
+
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0]).toMatchObject({ inner: 'preset' });
+	});
+
+	it('seeds repeater rows from minItems', async () => {
+		const user = userEvent.setup();
+		const onSubmit = renderForm({
+			type: 'form',
+			components: [
+				{
+					type: 'repeater',
+					name: 'items',
+					label: 'Items',
+					minItems: 2,
+					childScope: 'array',
+					schema: [{ type: 'text-input', name: 'title', label: 'Title', default: 't' }],
+				},
+			],
+		});
+
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0].items).toEqual([{ title: 't' }, { title: 't' }]);
+	});
+
+	it('extracts defaults from a custom (plugin) container via the declarative contract', async () => {
+		const user = userEvent.setup();
+		// The core has no renderer for 'custom-fieldset', so FieldRenderer warns and falls back;
+		// the default-extraction contract under test still runs.
+		const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+		const onSubmit = renderForm({
+			type: 'form',
+			components: [
+				{
+					// A container type the core does not know about — discovered purely via metadata.
+					type: 'custom-fieldset',
+					isLayout: true,
+					childScope: 'inherit',
+					schema: [{ type: 'text-input', name: 'pluginValue', default: 'from-plugin' }],
+				},
+			],
+		});
+
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0]).toMatchObject({ pluginValue: 'from-plugin' });
+		expect(warnSpy).toHaveBeenCalledWith('Unknown field type: custom-fieldset');
+		warnSpy.mockRestore();
+	});
+
+	it('accepts decimals and negatives for numeric fields', async () => {
+		const user = userEvent.setup();
+		const onSubmit = renderForm({
+			type: 'form',
+			components: [
+				{ type: 'text-input', name: 'price', label: 'Price', validation: { rules: [{ rule: 'numeric' }] } },
+			],
+		});
+
+		await user.type(screen.getByLabelText('Price'), '10.50');
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+
+		// Submission would be blocked if the numeric rule rejected the decimal.
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0]).toMatchObject({ price: '10.50' });
+	});
+
+	it('hides fields via a structured hiddenWhen condition', () => {
+		renderForm({
+			type: 'form',
+			components: [
+				{ type: 'text-input', name: 'status', label: 'Status', default: 'draft' },
+				{
+					type: 'text-input',
+					name: 'publishedAt',
+					label: 'Published at',
+					hiddenWhen: { op: 'eq', field: 'status', value: 'draft' },
+				},
+			],
+		});
+
+		expect(screen.getByLabelText(/status/i)).toBeInTheDocument();
+		expect(screen.queryByLabelText(/published at/i)).not.toBeInTheDocument();
+	});
+
+	it('user-provided defaultValues override schema defaults', async () => {
+		const user = userEvent.setup();
+		const onSubmit = renderForm(
+			{
+				type: 'form',
+				components: [{ type: 'text-input', name: 'name', label: 'Name', default: 'schema-default' }],
+			},
+			vi.fn(),
+			{ name: 'record-value' },
+		);
+
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0]).toMatchObject({ name: 'record-value' });
+	});
+});

package/src/FormRenderer.tsx

@@ -0,0 +1,140 @@
+import React, { useMemo } from 'react';
+import { useForm, FormProvider } from 'react-hook-form';
+import { FormRendererProps } from './types';
+import { FieldRenderer } from './FieldRenderer';
+import { cn } from './utils/classNames';
+import { getGridClasses } from './components/utils/layoutHelpers';
+import { Button } from './components/ui/Button';
+import { SerializedComponent } from '@maxal_studio/kratosjs';
+import { getChildComponents, isArrayScope, isLayout } from './runtime/formTraversal';
+import { useTranslation } from './i18n/useTranslation';
+import { Slot } from './slots/Slot';
+
+/**
+ * Extract default values from a schema using the declarative children contract.
+ * Layout containers are transparent (recurse into children); array-scope
+ * containers (repeaters) seed their own array value from the item template; leaf
+ * fields contribute their `default`.
+ */
+function extractDefaultValues(components: SerializedComponent[]): Record<string, any> {
+	const defaults: Record<string, any> = {};
+
+	components.forEach(component => {
+		// Array-scope container (Repeater): seed the array value, never leak item fields.
+		if (isArrayScope(component)) {
+			if (!component.name) return;
+			const template = getChildComponents(component);
+
+			if (component.default !== undefined && Array.isArray(component.default)) {
+				defaults[component.name] = component.default;
+				return;
+			}
+
+			const count =
+				typeof component.defaultItems === 'number' && component.defaultItems > 0
+					? component.defaultItems
+					: typeof (component as any).minItems === 'number' && (component as any).minItems > 0
+						? ((component as any).minItems as number)
+						: 0;
+
+			if (count > 0 && template.length > 0) {
+				const itemDefaults = extractDefaultValues(template);
+				defaults[component.name] = Array.from({ length: count }, () => ({ ...itemDefaults }));
+			}
+			return;
+		}
+
+		// Layout container: transparent, recurse into children.
+		if (isLayout(component)) {
+			Object.assign(defaults, extractDefaultValues(getChildComponents(component)));
+			return;
+		}
+
+		// Leaf field with a default value.
+		if (component.name && component.default !== undefined) {
+			defaults[component.name] = component.default;
+		}
+	});
+
+	return defaults;
+}
+
+/**
+ * FormRenderer component
+ * Main component that accepts JSON schema and renders the form
+ */
+export function FormRenderer({
+	schema,
+	onSubmit,
+	defaultValues = {},
+	className,
+	apiBaseUrl,
+	resource,
+	operation,
+	children,
+}: FormRendererProps) {
+	const { t } = useTranslation();
+	// Extract default values from schema and merge with user-provided defaults
+	const mergedDefaults = useMemo(() => {
+		const schemaDefaults = extractDefaultValues(schema.components);
+		return { ...schemaDefaults, ...defaultValues };
+	}, [schema.components, defaultValues]);
+
+	const methods = useForm({
+		defaultValues: mergedDefaults,
+		mode: 'onChange', // Validate and re-validate on change
+	});
+
+	const handleSubmit = async (data: any) => {
+		try {
+			await onSubmit(data);
+		} catch (error) {
+			console.error('Form submission error:', error);
+		}
+	};
+
+	// Calculate grid classes based on the columns prop (static class maps — purge-safe)
+	const formGridClasses =
+		!schema.columns || schema.columns === 1 ? 'space-y-6' : `${getGridClasses(schema.columns)} gap-y-4`;
+
+	return (
+		<FormProvider {...methods}>
+			{children}
+			<form onSubmit={methods.handleSubmit(handleSubmit)} className={cn(className)} noValidate>
+				<Slot
+					name="form.header"
+					context={{ resourceSlug: resource, record: defaultValues, schema }}
+					as="div"
+					className="mb-4 space-y-3 empty:hidden"
+				/>
+				<div className={formGridClasses}>
+					{schema.components.map((field, index) => (
+						<FieldRenderer
+							key={field.name || index}
+							field={field}
+							apiBaseUrl={apiBaseUrl}
+							resource={resource}
+							operation={operation}
+							mode="edit"
+						/>
+					))}
+				</div>
+
+				<div className="flex flex-wrap items-center justify-end gap-3 pt-6">
+					<Slot
+						name="form.footer"
+						context={{ resourceSlug: resource, record: defaultValues, schema }}
+						as="div"
+						className="mr-auto flex flex-wrap items-center gap-2 empty:hidden"
+					/>
+					<Button variant="secondary" onClick={() => methods.reset()}>
+						{t('core:common.reset')}
+					</Button>
+					<Button type="submit" loading={methods.formState.isSubmitting}>
+						{methods.formState.isSubmitting ? t('core:common.submitting') : t('core:common.submit')}
+					</Button>
+				</div>
+			</form>
+		</FormProvider>
+	);
+}

package/src/TableRenderer.tsx

@@ -0,0 +1,2 @@
+export { TableRenderer } from './table/TableRenderer';
+export type { TableRendererProps } from './table/TableRenderer';

package/src/api/actionsApi.ts

@@ -0,0 +1,76 @@
+import { ApiError, apiPost } from './http';
+import { deriveApiBaseUrl } from './urls';
+import { translate } from '../i18n/activeLocale';
+
+export interface ActionResult {
+	success: boolean;
+	message?: string;
+	data?: any;
+	redirect?: string; // Redirect path if present
+	[key: string]: any; // Allow additional fields (like redirect)
+}
+
+async function runAction(
+	apiUrl: string,
+	actionName: string,
+	recordIds: string[],
+	formData: any,
+	isBulk: boolean,
+): Promise<ActionResult> {
+	try {
+		const result = await apiPost<any>(
+			`${apiUrl}/actions`,
+			{
+				action: actionName,
+				data: { recordIds, formData: formData || {} },
+				...(isBulk ? { isBulk: true } : {}),
+			},
+			deriveApiBaseUrl(apiUrl),
+		);
+		return {
+			...result,
+			success: result.success !== false,
+			message: result.message,
+			data: result.data,
+			redirect: result.redirect,
+		};
+	} catch (error: any) {
+		const fallback = isBulk ? translate('core:error.action_failed_bulk') : translate('core:error.action_failed');
+		return {
+			success: false,
+			message: error instanceof ApiError ? error.message : error?.message || fallback,
+		};
+	}
+}
+
+/**
+ * Execute a single row action
+ * @param apiUrl - The base API URL for the resource (e.g., http://localhost:3001/api/users)
+ * @param actionName - The name of the action to execute
+ * @param recordId - The record ID (backend will populate the full record)
+ * @param formData - Optional form data from the action form
+ */
+export function executeAction(
+	apiUrl: string,
+	actionName: string,
+	recordId: string,
+	formData?: any,
+): Promise<ActionResult> {
+	return runAction(apiUrl, actionName, [recordId], formData, false);
+}
+
+/**
+ * Execute a bulk action on multiple rows
+ * @param apiUrl - The base API URL for the resource (e.g., http://localhost:3001/api/users)
+ * @param actionName - The name of the action to execute
+ * @param recordIds - Array of record IDs (backend will populate the full records)
+ * @param formData - Optional form data from the action form
+ */
+export function executeBulkAction(
+	apiUrl: string,
+	actionName: string,
+	recordIds: string[],
+	formData?: any,
+): Promise<ActionResult> {
+	return runAction(apiUrl, actionName, recordIds, formData, true);
+}

package/src/api/authenticatedFetch.ts

@@ -0,0 +1,40 @@
+import { AuthApiClient } from '../auth/authApiClient';
+import { getActiveLocale } from '../i18n/activeLocale';
+
+/**
+ * Fetch wrapper that automatically retries with a silent token refresh on 401.
+ * Auth tokens are carried by HTTP-only cookies — no Authorization header needed.
+ *
+ * Sends `X-KratosJs-Locale` so the server localizes labels/schemas/action
+ * messages to the admin's current UI locale.
+ */
+export async function authenticatedFetch(
+	url: string,
+	options: RequestInit = {},
+	apiBaseUrl: string,
+): Promise<Response> {
+	const headers = new Headers({
+		'Content-Type': 'application/json',
+		'X-KratosJs-Locale': getActiveLocale(),
+		...options.headers,
+	});
+
+	let response = await fetch(url, { ...options, headers, credentials: 'include' });
+
+	if (response.status === 401) {
+		const authClient = new AuthApiClient(apiBaseUrl);
+		const tokens = await authClient.refreshToken();
+
+		if (tokens) {
+			response = await fetch(url, { ...options, headers, credentials: 'include' });
+		} else {
+			return response;
+		}
+	}
+
+	if (response.ok && response.headers.get('X-KratosJs-Refresh-Badges')) {
+		window.dispatchEvent(new CustomEvent('kratosjs-refresh-badges'));
+	}
+
+	return response;
+}

package/src/api/exportApi.ts

@@ -0,0 +1,66 @@
+import { authenticatedFetch } from './authenticatedFetch';
+
+export interface ExportOptions {
+	/** Export format, e.g. 'csv'. */
+	format: string;
+	/** Originating action name (used for server-side per-action authorization). */
+	action?: string;
+	/** Current table query (search/filters/sort) — exports all matching rows. */
+	query?: Record<string, any>;
+	/** Specific record ids — exports only these (bulk "export selected"). */
+	recordIds?: any[];
+}
+
+/**
+ * POST to a resource's `/export` endpoint and trigger a browser download of the
+ * returned file. Used by header/bulk actions marked with `exportsTo(format)`.
+ *
+ * @param resourceUrl - The resource endpoint (e.g. `${apiBaseUrl}/users`)
+ * @param apiBaseUrl - Panel API base (for token refresh)
+ */
+export async function downloadExport(resourceUrl: string, apiBaseUrl: string, options: ExportOptions): Promise<void> {
+	const { format, action, query, recordIds } = options;
+	const url = `${resourceUrl.replace(/\/$/, '')}/export`;
+
+	const body: Record<string, any> = { format, ...(query || {}) };
+	if (action) {
+		body.action = action;
+	}
+	if (recordIds && recordIds.length > 0) {
+		body.recordIds = recordIds;
+	}
+
+	const response = await authenticatedFetch(url, { method: 'POST', body: JSON.stringify(body) }, apiBaseUrl);
+
+	if (!response.ok) {
+		let message = `Export failed (${response.status})`;
+		try {
+			const errorBody = await response.json();
+			message = errorBody.message || message;
+		} catch {
+			// response had no JSON body
+		}
+		throw new Error(message);
+	}
+
+	const blob = await response.blob();
+	const filename = parseContentDispositionFilename(response.headers.get('Content-Disposition')) || `export.${format}`;
+	triggerBrowserDownload(blob, filename);
+}
+
+function parseContentDispositionFilename(header: string | null): string | undefined {
+	if (!header) return undefined;
+	const match = /filename\*?=(?:UTF-8'')?["']?([^"';]+)["']?/i.exec(header);
+	return match ? decodeURIComponent(match[1]) : undefined;
+}
+
+function triggerBrowserDownload(blob: Blob, filename: string): void {
+	const objectUrl = URL.createObjectURL(blob);
+	const anchor = document.createElement('a');
+	anchor.href = objectUrl;
+	anchor.download = filename;
+	document.body.appendChild(anchor);
+	anchor.click();
+	anchor.remove();
+	URL.revokeObjectURL(objectUrl);
+}

package/src/api/http.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ApiError, apiFetch, apiGet, apiPost } from './http';
+import { mockFetch, restoreFetch } from '../test/mockFetch';
+
+const API = 'http://api.test/admin';
+
+describe('apiFetch', () => {
+	beforeEach(() => {
+		localStorage.clear();
+	});
+
+	afterEach(() => {
+		restoreFetch();
+	});
+
+	it('returns parsed JSON on success', async () => {
+		mockFetch([{ match: '/things', body: { hello: 'world' } }]);
+		const result = await apiGet<{ hello: string }>(`${API}/things`, API);
+		expect(result).toEqual({ hello: 'world' });
+	});
+
+	it('throws ApiError with the server message on failure', async () => {
+		mockFetch([{ match: '/things', status: 422, body: { message: 'Name is required' } }]);
+
+		const error = await apiPost(`${API}/things`, {}, API).catch(e => e);
+		expect(error).toBeInstanceOf(ApiError);
+		expect(error.status).toBe(422);
+		expect(error.message).toBe('Name is required');
+		expect(error.details).toEqual({ message: 'Name is required' });
+	});
+
+	it('uses a friendly message for 401s', async () => {
+		mockFetch([{ match: '/things', status: 401, body: { message: 'jwt expired' } }]);
+
+		const error = await apiGet(`${API}/things`, API).catch(e => e);
+		expect(error).toBeInstanceOf(ApiError);
+		expect(error.isUnauthorized).toBe(true);
+		expect(error.message).toBe('Unauthorized - Please login again');
+	});
+
+	it('tolerates empty response bodies', async () => {
+		mockFetch([]);
+		// Manually return empty 204-like response
+		restoreFetch();
+		const { vi } = await import('vitest');
+		vi.stubGlobal('fetch', async () => new Response('', { status: 200 }));
+
+		const result = await apiFetch(`${API}/things`, { apiBaseUrl: API });
+		expect(result).toBeNull();
+	});
+
+	it('posts JSON payloads', async () => {
+		const requests = mockFetch([{ match: '/things', body: { ok: true } }]);
+		await apiPost(`${API}/things`, { a: 1 }, API);
+		expect(requests[0].method).toBe('POST');
+		expect(requests[0].body).toEqual({ a: 1 });
+	});
+});

package/src/api/http.ts

@@ -0,0 +1,68 @@
+import { authenticatedFetch } from './authenticatedFetch';
+
+/**
+ * Typed error thrown by apiFetch for any non-2xx response.
+ * Carries the HTTP status and whatever the server put in the body so
+ * callers can map field-level validation errors or show the message.
+ */
+export class ApiError extends Error {
+	readonly status: number;
+	readonly details?: unknown;
+
+	constructor(message: string, status: number, details?: unknown) {
+		super(message);
+		this.name = 'ApiError';
+		this.status = status;
+		this.details = details;
+	}
+
+	get isUnauthorized(): boolean {
+		return this.status === 401;
+	}
+}
+
+export interface ApiFetchOptions extends RequestInit {
+	/** Base URL of the panel API, used for token refresh on 401 */
+	apiBaseUrl: string;
+}
+
+/**
+ * JSON fetch with auth + token refresh + uniform error handling.
+ * Throws ApiError on any non-ok response, preserving the server message.
+ */
+export async function apiFetch<T = unknown>(url: string, options: ApiFetchOptions): Promise<T> {
+	const { apiBaseUrl, ...init } = options;
+	const response = await authenticatedFetch(url, init, apiBaseUrl);
+
+	let body: any = null;
+	const text = await response.text();
+	if (text) {
+		try {
+			body = JSON.parse(text);
+		} catch {
+			body = text;
+		}
+	}
+
+	if (!response.ok) {
+		const message =
+			response.status === 401
+				? 'Unauthorized - Please login again'
+				: (body && typeof body === 'object' && (body.message || body.error)) ||
+					response.statusText ||
+					`Request failed with status ${response.status}`;
+		throw new ApiError(message, response.status, body);
+	}
+
+	return body as T;
+}
+
+/** Convenience JSON POST */
+export function apiPost<T = unknown>(url: string, payload: unknown, apiBaseUrl: string): Promise<T> {
+	return apiFetch<T>(url, { method: 'POST', body: JSON.stringify(payload), apiBaseUrl });
+}
+
+/** Convenience JSON GET */
+export function apiGet<T = unknown>(url: string, apiBaseUrl: string): Promise<T> {
+	return apiFetch<T>(url, { apiBaseUrl });
+}