@maxal_studio/kratosjs-react 1.0.0

package/dist/utils/layoutStorage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Layout storage utilities for managing table/grid layout preferences in localStorage
+ */
+export declare const layoutStorage: {
+    /**
+     * Get layout preference for a resource
+     * @param resourceKey Unique identifier for the resource (e.g., 'users', 'posts')
+     * @param defaultLayout Default layout to return if no preference is stored
+     * @returns 'table' or 'grid'
+     */
+    getLayout(resourceKey: string, defaultLayout?: "table" | "grid"): "table" | "grid";
+    /**
+     * Set layout preference for a resource
+     * @param resourceKey Unique identifier for the resource
+     * @param layout Layout mode - 'table' or 'grid'
+     */
+    setLayout(resourceKey: string, layout: "table" | "grid"): void;
+    /**
+     * Clear stored layout preference for a resource
+     * @param resourceKey Unique identifier for the resource
+     */
+    clearLayout(resourceKey: string): void;
+};

package/dist/utils/layoutStorage.js

@@ -0,0 +1,53 @@
+/**
+ * Layout storage utilities for managing table/grid layout preferences in localStorage
+ */
+export const layoutStorage = {
+    /**
+     * Get layout preference for a resource
+     * @param resourceKey Unique identifier for the resource (e.g., 'users', 'posts')
+     * @param defaultLayout Default layout to return if no preference is stored
+     * @returns 'table' or 'grid'
+     */
+    getLayout(resourceKey, defaultLayout = 'table') {
+        try {
+            const key = `kratosjs_layout_${resourceKey}`;
+            const stored = localStorage.getItem(key);
+            if (stored === 'table' || stored === 'grid') {
+                return stored;
+            }
+            return defaultLayout;
+        }
+        catch (error) {
+            console.warn('Failed to read layout preference from localStorage:', error);
+            return defaultLayout;
+        }
+    },
+    /**
+     * Set layout preference for a resource
+     * @param resourceKey Unique identifier for the resource
+     * @param layout Layout mode - 'table' or 'grid'
+     */
+    setLayout(resourceKey, layout) {
+        try {
+            const key = `kratosjs_layout_${resourceKey}`;
+            localStorage.setItem(key, layout);
+        }
+        catch (error) {
+            // Handle quota exceeded or other localStorage errors
+            if (error instanceof Error && error.name === 'QuotaExceededError') {
+                console.warn('localStorage quota exceeded, layout preference not saved');
+            }
+            else {
+                console.warn('Failed to save layout preference to localStorage:', error);
+            }
+        }
+    },
+    /**
+     * Clear stored layout preference for a resource
+     * @param resourceKey Unique identifier for the resource
+     */
+    clearLayout(resourceKey) {
+        const key = `kratosjs_layout_${resourceKey}`;
+        localStorage.removeItem(key);
+    },
+};

package/dist/utils/redirectHandler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Handle redirect from API response
+ * @param responseData - Response data from API
+ * @param navigate - React Router navigate function
+ * @returns true if redirect was handled, false otherwise
+ */
+export declare function handleRedirect(responseData: any, navigate: (path: string) => void): boolean;

package/dist/utils/redirectHandler.js

@@ -0,0 +1,25 @@
+/**
+ * Handle redirect from API response
+ * @param responseData - Response data from API
+ * @param navigate - React Router navigate function
+ * @returns true if redirect was handled, false otherwise
+ */
+export function handleRedirect(responseData, navigate) {
+    if (responseData?.redirect) {
+        const redirectPath = responseData.redirect;
+        // Handle relative paths (client-side navigation)
+        if (redirectPath.startsWith('/')) {
+            navigate(redirectPath);
+            return true;
+        }
+        // Handle absolute URLs (external redirects)
+        if (redirectPath.startsWith('http://') || redirectPath.startsWith('https://')) {
+            window.location.href = redirectPath;
+            return true;
+        }
+        // Invalid redirect path
+        console.warn('Invalid redirect path:', redirectPath);
+        return false;
+    }
+    return false;
+}

package/dist/utils/tableFormatters.d.ts

@@ -0,0 +1,14 @@
+import { SerializedColumn } from '@maxal_studio/kratosjs';
+/**
+ * Format a value based on column configuration
+ * @param value - The cell value
+ * @param column - The column configuration
+ * @param row - The entire row data (optional, used by formatStateUsing function)
+ */
+export declare function formatValue(value: any, column: SerializedColumn, row?: Record<string, any>): any;
+/**
+ * Strip HTML tags from a string
+ * @param html - The HTML string to strip
+ * @returns Plain text with HTML tags removed
+ */
+export declare function stripHtml(html: string): string;

package/dist/utils/tableFormatters.js

@@ -0,0 +1,93 @@
+import { getActiveLocale } from '../i18n/activeLocale';
+/**
+ * Format a value based on column configuration
+ * @param value - The cell value
+ * @param column - The column configuration
+ * @param row - The entire row data (optional, used by formatStateUsing function)
+ */
+export function formatValue(value, column, row) {
+    // Only apply placeholder for null/undefined when there's no formatter
+    if (value === null || value === undefined) {
+        return null;
+    }
+    // Date formatting
+    if (column.dateFormat) {
+        const date = new Date(value);
+        if (isNaN(date.getTime()))
+            return value;
+        const locale = getActiveLocale();
+        switch (column.dateFormat) {
+            case 'date':
+                return date.toLocaleDateString(locale);
+            case 'dateTime':
+                return date.toLocaleString(locale);
+            case 'time':
+                return date.toLocaleTimeString(locale);
+            case 'since':
+            case 'until':
+                return getRelativeTime(date);
+            default:
+                return date.toLocaleDateString(locale);
+        }
+    }
+    // Money formatting
+    if (column.moneyFormat) {
+        const numValue = typeof value === 'number' ? value : parseFloat(value);
+        if (isNaN(numValue))
+            return value;
+        return new Intl.NumberFormat(getActiveLocale(), {
+            style: 'currency',
+            currency: column.moneyFormat || 'USD',
+        }).format(numValue);
+    }
+    // Strip HTML by default; only skip when stripHtml is explicitly false.
+    // column.stripHtml is true (default), false (explicit), or undefined (treated as true).
+    const shouldStripHtml = column.stripHtml !== false;
+    if (shouldStripHtml) {
+        if (typeof value === 'string') {
+            return stripHtml(value);
+        }
+        // Handle arrays - strip HTML from each string item
+        if (Array.isArray(value)) {
+            return value.map(item => (typeof item === 'string' ? stripHtml(item) : item));
+        }
+    }
+    return value;
+}
+/**
+ * Strip HTML tags from a string
+ * @param html - The HTML string to strip
+ * @returns Plain text with HTML tags removed
+ */
+export function stripHtml(html) {
+    if (typeof html !== 'string') {
+        return html;
+    }
+    // Create a temporary DOM element to parse HTML
+    const tmp = document.createElement('div');
+    tmp.innerHTML = html;
+    return tmp.textContent || tmp.innerText || '';
+}
+/**
+ * Locale-aware relative time (e.g. "2 hours ago", "in 3 days"), using the active
+ * locale via `Intl.RelativeTimeFormat`. The true signed delta (date − now) drives
+ * direction, so past dates read "ago" and future dates read "in …".
+ */
+function getRelativeTime(date) {
+    const deltaSec = Math.round((date.getTime() - Date.now()) / 1000);
+    const abs = Math.abs(deltaSec);
+    const rtf = new Intl.RelativeTimeFormat(getActiveLocale(), { numeric: 'auto' });
+    const units = [
+        ['year', 31536000],
+        ['month', 2592000],
+        ['week', 604800],
+        ['day', 86400],
+        ['hour', 3600],
+        ['minute', 60],
+    ];
+    for (const [unit, secs] of units) {
+        if (abs >= secs)
+            return rtf.format(Math.round(deltaSec / secs), unit);
+    }
+    return rtf.format(0, 'second');
+}

package/dist/utils/widgetVisibilityStorage.d.ts

@@ -0,0 +1,11 @@
+/** Default when no preference stored: desktop expanded, mobile collapsed */
+export declare function getDefaultWidgetsExpanded(): boolean;
+/**
+ * Storage for widgets expanded/collapsed state.
+ * When no value is stored, mobile should be collapsed and desktop expanded (handled in component via media query).
+ */
+export declare const widgetVisibilityStorage: {
+    get(): boolean | null;
+    set(expanded: boolean): void;
+    clear(): void;
+};

package/dist/utils/widgetVisibilityStorage.js

@@ -0,0 +1,39 @@
+const WIDGET_VISIBILITY_KEY = 'kratosjs_widgets_expanded';
+/** Default when no preference stored: desktop expanded, mobile collapsed */
+export function getDefaultWidgetsExpanded() {
+    if (typeof window === 'undefined')
+        return true;
+    return window.matchMedia('(min-width: 768px)').matches;
+}
+/**
+ * Storage for widgets expanded/collapsed state.
+ * When no value is stored, mobile should be collapsed and desktop expanded (handled in component via media query).
+ */
+export const widgetVisibilityStorage = {
+    get() {
+        try {
+            const stored = localStorage.getItem(WIDGET_VISIBILITY_KEY);
+            if (stored === 'true')
+                return true;
+            if (stored === 'false')
+                return false;
+            return null;
+        }
+        catch {
+            return null;
+        }
+    },
+    set(expanded) {
+        try {
+            localStorage.setItem(WIDGET_VISIBILITY_KEY, String(expanded));
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'QuotaExceededError') {
+                console.warn('localStorage quota exceeded, widgets visibility not saved');
+            }
+        }
+    },
+    clear() {
+        localStorage.removeItem(WIDGET_VISIBILITY_KEY);
+    },
+};

package/package.json

@@ -0,0 +1,101 @@
+{
+	"name": "@maxal_studio/kratosjs-react",
+	"version": "1.0.0",
+	"description": "React components for KratosJs form builder",
+	"type": "module",
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"sideEffects": [
+		"**/*.css"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./app": {
+			"types": "./dist/app.d.ts",
+			"import": "./dist/app.js"
+		},
+		"./plugin": {
+			"types": "./dist/plugin.d.ts",
+			"import": "./dist/plugin.js"
+		},
+		"./styles.css": "./dist/styles.css",
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"src",
+		"vite.config.ts",
+		"tailwind.config.js",
+		"README.md"
+	],
+	"scripts": {
+		"build": "npm run clean && tsc && vite build",
+		"clean": "rm -rf dist",
+		"dev": "tsc --watch",
+		"lint": "eslint ./src",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	"keywords": [
+		"react",
+		"forms",
+		"form-builder",
+		"kratosjs",
+		"tailwind"
+	],
+	"author": "MaxAl",
+	"email": "info@max.al",
+	"website": "https://max.al",
+	"license": "ISC",
+	"peerDependencies": {
+		"@maxal_studio/kratosjs": "^1.0.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"react-hook-form": "^7.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@maxal_studio/kratosjs": {
+			"optional": true
+		}
+	},
+	"dependencies": {
+		"@tiptap/extension-color": "^3.26.1",
+		"@tiptap/extension-highlight": "^3.26.1",
+		"@tiptap/extension-image": "^3.26.1",
+		"@tiptap/extension-link": "^3.26.1",
+		"@tiptap/extension-placeholder": "^3.26.1",
+		"@tiptap/extension-subscript": "^3.26.1",
+		"@tiptap/extension-superscript": "^3.26.1",
+		"@tiptap/extension-text-align": "^3.26.1",
+		"@tiptap/extension-text-style": "^3.26.1",
+		"@tiptap/extension-underline": "^3.26.1",
+		"@tiptap/react": "^3.26.1",
+		"@tiptap/starter-kit": "^3.26.1",
+		"chart.js": "^4.5.1",
+		"clsx": "^2.1.1",
+		"lucide-react": "^1.18.0",
+		"react-chartjs-2": "^5.3.1",
+		"react-dropzone": "^15.0.0",
+		"react-router-dom": "^7.17.0"
+	},
+	"devDependencies": {
+		"@maxal_studio/kratosjs": "file:../..",
+		"@tailwindcss/vite": "^4.3.1",
+		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
+		"react": "^19.2.7",
+		"react-dom": "^19.2.7",
+		"react-hook-form": "^7.79.0",
+		"eslint": "^9.39.4",
+		"jsdom": "^29.1.1",
+		"typescript-eslint": "^8.61.0",
+		"typescript": "^5.9.3",
+		"vite": "^7.3.5",
+		"vitest": "^4.1.8"
+	}
+}

package/src/FieldRenderer.test.tsx

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { FormRenderer } from './FormRenderer';
+import { FieldRegistryProvider } from './contexts/FieldRegistryContext';
+import type { FieldProps } from './types';
+
+// A custom field component an app registers without a plugin. In production this
+// is wired via mountAdminPanel({ fields: { 'star-rating': StarRatingField } });
+// here we feed it straight into the registry provider, which is the same path.
+function StarRatingField(props: FieldProps) {
+	return <div data-testid="star-rating">{props.label} stars</div>;
+}
+
+describe('FieldRenderer custom component registration', () => {
+	it('renders a custom field registered via the field registry', () => {
+		render(
+			<FieldRegistryProvider customFields={{ 'star-rating': StarRatingField }}>
+				<FormRenderer
+					schema={{
+						type: 'form',
+						components: [{ type: 'star-rating', name: 'rating', label: 'Rating' }],
+					}}
+					onSubmit={vi.fn()}
+				/>
+			</FieldRegistryProvider>,
+		);
+
+		expect(screen.getByTestId('star-rating')).toBeInTheDocument();
+		expect(screen.getByText(/rating stars/i)).toBeInTheDocument();
+	});
+
+	it('still warns for a field type that is not registered', () => {
+		render(
+			<FieldRegistryProvider customFields={{ 'star-rating': StarRatingField }}>
+				<FormRenderer
+					schema={{ type: 'form', components: [{ type: 'mystery', name: 'x' }] }}
+					onSubmit={vi.fn()}
+				/>
+			</FieldRegistryProvider>,
+		);
+
+		expect(screen.getByText(/unknown field type "mystery"/i)).toBeInTheDocument();
+	});
+});

package/src/FieldRenderer.tsx

@@ -0,0 +1,104 @@
+import React from 'react';
+import { useWatch, useFormContext } from 'react-hook-form';
+import { FieldRendererProps } from './types';
+import { useFieldRegistry } from './contexts/FieldRegistryContext';
+import { evaluateCondition } from './runtime/conditions';
+import { useAfterStateUpdated } from './hooks/useAfterStateUpdated';
+import { getColumnClasses } from './components/utils/layoutHelpers';
+import { translate } from './i18n/activeLocale';
+
+/**
+ * FieldRenderer component
+ * Dynamically renders the correct field component based on type
+ */
+export function FieldRenderer({
+	field,
+	apiBaseUrl,
+	resource,
+	operation,
+	mode = 'edit',
+	value,
+}: FieldRendererProps & {
+	apiBaseUrl?: string;
+	resource?: string;
+	operation?: 'create' | 'edit' | 'view';
+	mode?: 'edit' | 'view';
+	value?: any;
+}) {
+	const registry = useFieldRegistry();
+	const FieldComponent = registry[field.type];
+
+	// In view mode, we don't need form context
+	let formState: Record<string, any> = {};
+	if (mode === 'edit') {
+		const { control } = useFormContext();
+		// Watch form state for conditional visibility/disabled evaluation
+		formState = useWatch({ control }) || {};
+		// Execute afterStateUpdated callback when field value changes (if provided)
+		useAfterStateUpdated(field.name, (field as any).afterStateUpdatedFn);
+	} else {
+		// In view mode, create a simple form state from the value prop for conditional evaluation
+		// This allows conditional visibility to work based on field values
+		if (field.name && value !== undefined) {
+			formState = { [field.name]: value };
+		}
+	}
+
+	// Unknown field type
+	if (!FieldComponent) {
+		console.warn(`Unknown field type: ${field.type}`);
+		return (
+			<div className="mb-4 p-4 bg-yellow-50 border border-yellow-200 rounded-lg">
+				<p className="text-sm text-yellow-800">
+					<strong>{translate('core:common.warning')}:</strong>{' '}
+					{translate('core:state.unknown_field', { type: field.type, name: field.name })}
+				</p>
+			</div>
+		);
+	}
+
+	// Evaluate conditional hidden state — hiddenWhen is the structured-AST form
+	// (no code execution), hiddenFn the serialized-function form.
+	const isHidden = evaluateCondition(
+		(field as any).hiddenWhen ?? (field as any).hiddenFn ?? field.hidden,
+		formState,
+		operation,
+	);
+
+	// Evaluate conditional disabled state
+	const isDisabled = evaluateCondition(
+		(field as any).disabledWhen ?? (field as any).disabledFn ?? field.disabled,
+		formState,
+		operation,
+	);
+
+	// Hidden field
+	if (isHidden) {
+		return null;
+	}
+
+	// Update field props with evaluated disabled state, API base URL, resource, mode, operation, and value
+	const fieldWithEvaluatedProps = {
+		...field,
+		disabled: isDisabled,
+		apiBaseUrl,
+		resource,
+		mode,
+		operation,
+		value: value !== undefined ? value : mode === 'view' ? undefined : undefined,
+	};
+
+	// Get column layout classes using shared helper
+	const columnClasses = getColumnClasses(fieldWithEvaluatedProps.columnSpan, fieldWithEvaluatedProps.columnStart);
+
+	// Render the field component
+	if (columnClasses) {
+		return (
+			<div className={columnClasses}>
+				<FieldComponent {...fieldWithEvaluatedProps} />
+			</div>
+		);
+	}
+
+	return <FieldComponent {...fieldWithEvaluatedProps} />;
+}

package/src/FormRenderer.containers.test.tsx

@@ -0,0 +1,121 @@
+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 { FormBuilder, TextInput, Group, Tabs, Repeater } from '@maxal_studio/kratosjs';
+import { FormRenderer } from './FormRenderer';
+import { FieldRegistryProvider } from './contexts/FieldRegistryContext';
+
+// Front-end counterpart to the backend container validation tests: rules on
+// fields nested in containers (Group/Tabs and Repeater rows) must block submit,
+// driven by the same shared engine the server uses.
+
+function renderForm(schema: any, defaultValues?: Record<string, any>) {
+	const onSubmit = vi.fn();
+	render(
+		<FieldRegistryProvider>
+			<FormRenderer schema={schema} onSubmit={onSubmit} defaultValues={defaultValues} />
+		</FieldRegistryProvider>,
+	);
+	return onSubmit;
+}
+
+const submit = () => userEvent.setup().click(screen.getByRole('button', { name: /submit/i }));
+
+describe('FormRenderer validation in layout containers', () => {
+	it('Group: a required nested field blocks submit and shows an error', async () => {
+		const schema = FormBuilder.make()
+			.schema([Group.make('g').schema([TextInput.make('email').label('Email').required().email()])])
+			.toJSON();
+		const onSubmit = renderForm(schema);
+
+		await submit();
+
+		await waitFor(() => expect(screen.getByText(/this field is required/i)).toBeInTheDocument());
+		expect(onSubmit).not.toHaveBeenCalled();
+	});
+
+	it('Group: an invalid value on a nested field blocks submit', async () => {
+		const schema = FormBuilder.make()
+			.schema([Group.make('g').schema([TextInput.make('email').label('Email').required().email()])])
+			.toJSON();
+		const onSubmit = renderForm(schema);
+
+		const user = userEvent.setup();
+		await user.type(screen.getByLabelText(/email/i), 'not-an-email');
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+
+		await waitFor(() => expect(screen.getByText(/valid email/i)).toBeInTheDocument());
+		expect(onSubmit).not.toHaveBeenCalled();
+	});
+
+	it('Tabs: a rule on a field inside the active tab is enforced', async () => {
+		const schema = FormBuilder.make()
+			.schema([
+				Tabs.make('t').tabs([
+					{ label: 'A', schema: [TextInput.make('title').label('Title').required().min(3)] },
+				]),
+			])
+			.toJSON();
+		const onSubmit = renderForm(schema);
+
+		const user = userEvent.setup();
+		await user.type(screen.getByLabelText(/title/i), 'ab'); // below min:3
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+
+		await waitFor(() => expect(screen.getByText(/at least 3 characters/i)).toBeInTheDocument());
+		expect(onSubmit).not.toHaveBeenCalled();
+	});
+
+	it('Group: a fully valid nested field submits', async () => {
+		const schema = FormBuilder.make()
+			.schema([Group.make('g').schema([TextInput.make('email').label('Email').required().email()])])
+			.toJSON();
+		const onSubmit = renderForm(schema);
+
+		const user = userEvent.setup();
+		await user.type(screen.getByLabelText(/email/i), 'a@b.com');
+		await user.click(screen.getByRole('button', { name: /submit/i }));
+
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0]).toMatchObject({ email: 'a@b.com' });
+	});
+});
+
+describe('FormRenderer validation in a Repeater row', () => {
+	const schema = FormBuilder.make()
+		.schema([Repeater.make('items').schema([TextInput.make('name').label('Name').required().min(3)])])
+		.toJSON();
+
+	it('an invalid row (empty required) blocks submit and shows the row error', async () => {
+		// Seed one empty row so the row's fields render and register.
+		const onSubmit = renderForm(schema, { items: [{ name: '' }] });
+
+		// Row actually rendered (so the assertion is meaningful).
+		expect(screen.getByLabelText(/name/i)).toBeInTheDocument();
+
+		await submit();
+
+		// The nested-name (items.0.name) error message now resolves and renders.
+		await waitFor(() => expect(screen.getByText(/this field is required/i)).toBeInTheDocument());
+		expect(onSubmit).not.toHaveBeenCalled();
+	});
+
+	it('a too-short row value (min:3) blocks submit and shows the row error', async () => {
+		const onSubmit = renderForm(schema, { items: [{ name: 'ab' }] });
+
+		await submit();
+
+		await waitFor(() => expect(screen.getByText(/at least 3 characters/i)).toBeInTheDocument());
+		expect(onSubmit).not.toHaveBeenCalled();
+	});
+
+	it('a valid row submits', async () => {
+		const onSubmit = renderForm(schema, { items: [{ name: 'abc' }] });
+
+		await submit();
+
+		await waitFor(() => expect(onSubmit).toHaveBeenCalled());
+		expect(onSubmit.mock.calls[0][0]).toMatchObject({ items: [{ name: 'abc' }] });
+	});
+});