@maxal_studio/kratosjs-react 1.0.0

package/src/runtime/conditions.ts

@@ -0,0 +1,148 @@
+import { compileSerializedFunction } from './serializedFunctions';
+
+/**
+ * Conditional visibility / disabled-state evaluation.
+ *
+ * Three condition forms are supported, in priority order:
+ *  1. `boolean` — static.
+ *  2. Structured condition object (preferred) — a small declarative AST that
+ *     is interpreted without executing any code, so it works under a strict
+ *     CSP and cannot do anything besides read form values.
+ *  3. Serialized function string — `({ get, operation }) => boolean`,
+ *     compiled via the serialized-function runtime (see its trust-boundary
+ *     notes).
+ */
+
+export type ConditionOperator =
+	| 'eq'
+	| 'ne'
+	| 'in'
+	| 'nin'
+	| 'truthy'
+	| 'falsy'
+	| 'gt'
+	| 'gte'
+	| 'lt'
+	| 'lte'
+	| 'operation';
+
+export type ConditionAst =
+	| { all: ConditionAst[] }
+	| { any: ConditionAst[] }
+	| { not: ConditionAst }
+	| { op: ConditionOperator; field?: string; value?: any };
+
+export type Condition = boolean | string | ConditionAst | undefined;
+
+export type FormOperation = 'create' | 'edit' | 'view';
+
+/** Read a (possibly dot-separated) field path from the form state. */
+function getFieldValue(formState: Record<string, any>, fieldName: string): any {
+	let value: any = formState;
+	for (const key of fieldName.split('.')) {
+		if (value === undefined || value === null) {
+			return undefined;
+		}
+		value = value[key];
+	}
+	return value;
+}
+
+function isConditionAst(condition: unknown): condition is ConditionAst {
+	if (!condition || typeof condition !== 'object' || Array.isArray(condition)) {
+		return false;
+	}
+	const c = condition as Record<string, unknown>;
+	return Array.isArray(c.all) || Array.isArray(c.any) || typeof c.not === 'object' || typeof c.op === 'string';
+}
+
+/**
+ * Pure interpreter for structured conditions — no code execution.
+ */
+export function evaluateConditionAst(
+	ast: ConditionAst,
+	formState: Record<string, any>,
+	operation?: FormOperation,
+): boolean {
+	if ('all' in ast && Array.isArray(ast.all)) {
+		return ast.all.every(child => evaluateConditionAst(child, formState, operation));
+	}
+	if ('any' in ast && Array.isArray(ast.any)) {
+		return ast.any.some(child => evaluateConditionAst(child, formState, operation));
+	}
+	if ('not' in ast && ast.not) {
+		return !evaluateConditionAst(ast.not as ConditionAst, formState, operation);
+	}
+
+	const { op, field, value } = ast as { op: ConditionOperator; field?: string; value?: any };
+	const actual = op === 'operation' ? operation : field !== undefined ? getFieldValue(formState, field) : undefined;
+
+	switch (op) {
+		case 'eq':
+			return actual === value;
+		case 'ne':
+			return actual !== value;
+		case 'in':
+			return Array.isArray(value) && value.includes(actual);
+		case 'nin':
+			return Array.isArray(value) && !value.includes(actual);
+		case 'truthy':
+			return Boolean(actual);
+		case 'falsy':
+			return !actual;
+		case 'gt':
+			return actual > value;
+		case 'gte':
+			return actual >= value;
+		case 'lt':
+			return actual < value;
+		case 'lte':
+			return actual <= value;
+		case 'operation':
+			return operation === value;
+		default:
+			console.warn('Unknown condition operator:', op);
+			return false;
+	}
+}
+
+/**
+ * Evaluate a hidden/disabled condition against the current form state.
+ * Returns false (not hidden / not disabled) for undefined or invalid input.
+ */
+export function evaluateCondition(
+	condition: Condition,
+	formState: Record<string, any>,
+	operation?: FormOperation,
+): boolean {
+	if (condition === undefined || condition === null) {
+		return false;
+	}
+
+	if (typeof condition === 'boolean') {
+		return condition;
+	}
+
+	if (isConditionAst(condition)) {
+		try {
+			return evaluateConditionAst(condition, formState, operation);
+		} catch (error) {
+			console.error('Error evaluating condition AST:', condition, error);
+			return false;
+		}
+	}
+
+	if (typeof condition === 'string') {
+		try {
+			const fn = compileSerializedFunction(condition);
+			if (!fn) return false;
+			const get = (fieldName: string) => getFieldValue(formState, fieldName);
+			return Boolean(fn({ get, operation }));
+		} catch (error) {
+			console.error('Error evaluating condition:', condition, error);
+			return false;
+		}
+	}
+
+	return false;
+}

package/src/runtime/formTraversal.ts

@@ -0,0 +1,41 @@
+import { SerializedComponent } from '@maxal_studio/kratosjs';
+
+/**
+ * Frontend implementation of the declarative children contract (mirrors
+ * `src/utils/formSchemaTraversal`). The core package's
+ * barrel pulls Node-only deps, so we share the *contract* (the serialized
+ * shape), not the module:
+ *   - children live under `schema`
+ *   - `isLayout` marks pure layout containers (no value of their own)
+ *   - `childScope: 'array'` marks item-template containers (Repeater)
+ *
+ * Any component (core or plugin) that follows the contract is traversed
+ * correctly with no type-specific code.
+ */
+
+/** Direct child components of a node. */
+export function getChildComponents(node: SerializedComponent): SerializedComponent[] {
+	const schema = (node as any).schema;
+	return Array.isArray(schema) ? (schema as SerializedComponent[]) : [];
+}
+
+/** A pure layout container (inherits parent value scope, holds no value of its own). */
+export function isLayout(node: SerializedComponent): boolean {
+	return (node as any).isLayout === true;
+}
+
+/** Children form an item template whose value lives under the node's own name (Repeater). */
+export function isArrayScope(node: SerializedComponent): boolean {
+	return (node as any).childScope === 'array';
+}
+
+/**
+ * Depth-first predicate over a node and all of its descendants. Recursion stops
+ * descending past array-scope containers (their item template is a separate
+ * value scope) — the predicate still sees the container node itself.
+ */
+export function someComponent(node: SerializedComponent, predicate: (node: SerializedComponent) => boolean): boolean {
+	if (predicate(node)) return true;
+	if (isArrayScope(node)) return false;
+	return getChildComponents(node).some(child => someComponent(child, predicate));
+}

package/src/runtime/serializedFunctions.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from 'vitest';
+import { executeSerializedFunction } from '../runtime/serializedFunctions';
+
+describe('executeSerializedFunction', () => {
+	it('returns undefined for empty input', () => {
+		expect(executeSerializedFunction(undefined)).toBeUndefined();
+		expect(executeSerializedFunction('')).toBeUndefined();
+	});
+
+	it('executes arrow functions with expression bodies', () => {
+		expect(executeSerializedFunction('(value) => value * 2', 5)).toBe(10);
+	});
+
+	it('executes arrow functions with block bodies', () => {
+		expect(
+			executeSerializedFunction('(value, record) => { return value + record.suffix; }', 'a', { suffix: 'b' }),
+		).toBe('ab');
+	});
+
+	it('executes single-param arrow functions without parens', () => {
+		expect(executeSerializedFunction('value => value.toUpperCase()', 'hi')).toBe('HI');
+	});
+
+	it('executes function expressions', () => {
+		expect(executeSerializedFunction('function (value) { return value * 3; }', 3)).toBe(9);
+	});
+
+	it('returns the compiled function when no args are given', () => {
+		const fn = executeSerializedFunction('(value) => value + 1');
+		expect(typeof fn).toBe('function');
+		expect(fn(1)).toBe(2);
+	});
+
+	it('strips a __name() wrapper added by TS toolchains', () => {
+		const wrapped = '__name((value) => value * 2, "double")';
+		expect(executeSerializedFunction(wrapped, 4)).toBe(8);
+	});
+
+	it('strips nested __name() wrappers in block bodies', () => {
+		const wrapped = '__name((value) => { const inc = __name((x) => x + 1, "inc"); return inc(value); }, "outer")';
+		expect(executeSerializedFunction(wrapped, 1)).toBe(2);
+	});
+
+	it('does not mangle string literals containing __name-like text', () => {
+		expect(executeSerializedFunction('(value) => "__name is fine" + value', '!')).toBe('__name is fine!');
+	});
+
+	it('returns undefined when the function throws', () => {
+		// The function intentionally throws; the runtime catches it, logs, and returns undefined.
+		const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+		expect(executeSerializedFunction('(value) => { throw new Error("boom"); }', 1)).toBeUndefined();
+		expect(errorSpy).toHaveBeenCalled();
+		errorSpy.mockRestore();
+	});
+
+	it('handles default parameter values', () => {
+		expect(executeSerializedFunction('(value, factor = 2) => value * factor', 5, 3)).toBe(15);
+	});
+});

package/src/runtime/serializedFunctions.ts

@@ -0,0 +1,284 @@
+/**
+ * Runtime for executing functions serialized by the KratosJs backend.
+ *
+ * ## Trust boundary
+ *
+ * The strings executed here are NOT user input. They are functions written by
+ * the panel developer in resource/column definitions (kratosjs core
+ * serializes them with `.toString()`) and served by the developer's own server
+ * over the authenticated metadata API. They carry exactly the same trust as
+ * the application JS bundle itself: if an attacker can tamper with the
+ * metadata endpoint, they already control the panel.
+ *
+ * Implementation notes:
+ * - Compilation uses `new Function` (never `eval`), so serialized code cannot
+ *   capture local scope from this module.
+ * - Compiled functions are cached by source string — schemas re-render often
+ *   and re-parsing on every render is wasted work.
+ * - Deploying a CSP without `'unsafe-eval'` requires avoiding serialized
+ *   functions entirely (use structured conditions instead, see conditions.ts).
+ */
+
+const compileCache = new Map<string, ((...args: any[]) => any) | undefined>();
+
+/**
+ * Strip TypeScript/esbuild helper wrappers from serialized code.
+ * Toolchains wrap named function expressions as `__name(fn, "fnName")`;
+ * this extracts the first argument and drops the name, iterating until
+ * no `__name(` wrappers remain (handles nesting in block bodies).
+ */
+export function stripTypeScriptHelpers(code: string): string {
+	let cleaned = code;
+	let changed = true;
+	let iterations = 0;
+	const maxIterations = 100; // Safety limit to prevent infinite loops
+
+	while (changed && iterations < maxIterations) {
+		iterations++;
+		const before = cleaned;
+		let result = '';
+		let i = 0;
+
+		while (i < cleaned.length) {
+			// Check if we're at __name(
+			if (cleaned.substring(i, i + 6) === '__name' && (cleaned[i + 6] === '(' || /\s/.test(cleaned[i + 6]))) {
+				// Skip '__name' and any whitespace, find the opening parenthesis
+				let j = i + 6;
+				while (j < cleaned.length && /\s/.test(cleaned[j])) j++;
+				if (j >= cleaned.length || cleaned[j] !== '(') {
+					// Not a __name( call, add it back and continue
+					result += cleaned[i];
+					i++;
+					continue;
+				}
+
+				// Skip '('
+				j++;
+
+				// Find the first argument (the function expression),
+				// matching balanced parens/brackets/braces outside strings
+				let depth = 0;
+				const start = j;
+				let inString = false;
+				let stringChar = '';
+				let inTemplate = false;
+
+				while (j < cleaned.length) {
+					const char = cleaned[j];
+					const prevChar = j > 0 ? cleaned[j - 1] : '';
+
+					if (!inString && !inTemplate) {
+						if (char === '`') {
+							inTemplate = true;
+						} else if (char === '"' || char === "'") {
+							inString = true;
+							stringChar = char;
+						}
+					} else if (inString && char === stringChar && prevChar !== '\\') {
+						inString = false;
+					} else if (inTemplate && char === '`' && prevChar !== '\\') {
+						inTemplate = false;
+					}
+
+					if (!inString && !inTemplate) {
+						if (char === '(' || char === '[' || char === '{') {
+							depth++;
+						} else if (char === ')' || char === ']' || char === '}') {
+							depth--;
+						}
+
+						// A comma at depth 0 ends the first argument
+						if (char === ',' && depth === 0) {
+							break;
+						}
+					}
+
+					j++;
+				}
+
+				const functionExpr = cleaned.substring(start, j);
+				result += functionExpr;
+
+				// Skip the comma
+				if (cleaned[j] === ',') j++;
+
+				// Skip whitespace
+				while (j < cleaned.length && /\s/.test(cleaned[j])) j++;
+
+				// Skip the string argument ("functionName")
+				if (cleaned[j] === '"' || cleaned[j] === "'") {
+					const quote = cleaned[j];
+					j++;
+					while (j < cleaned.length && cleaned[j] !== quote) {
+						if (cleaned[j] === '\\') j++; // Skip escaped characters
+						j++;
+					}
+					if (cleaned[j] === quote) j++; // Skip closing quote
+				}
+
+				// Skip whitespace and closing paren
+				while (j < cleaned.length && (/\s/.test(cleaned[j]) || cleaned[j] === ')')) j++;
+
+				i = j;
+			} else {
+				result += cleaned[i];
+				i++;
+			}
+		}
+
+		cleaned = result;
+		changed = before !== cleaned;
+	}
+
+	return cleaned;
+}
+
+/**
+ * Extract parameter names from a function parameter list.
+ * Handles: (a, b), (a,b), a, (a = 1, b), etc.
+ */
+function extractParameters(paramString: string): string[] {
+	if (!paramString) return [];
+
+	const cleaned = paramString.replace(/^\(|\)$/g, '').trim();
+	if (!cleaned) return [];
+
+	const params: string[] = [];
+	let current = '';
+	let depth = 0;
+
+	for (let i = 0; i < cleaned.length; i++) {
+		const char = cleaned[i];
+
+		if (char === '(' || char === '[' || char === '{') {
+			depth++;
+			current += char;
+		} else if (char === ')' || char === ']' || char === '}') {
+			depth--;
+			current += char;
+		} else if (char === ',' && depth === 0) {
+			const paramName = current.trim().split('=')[0].trim();
+			if (paramName) {
+				params.push(paramName);
+			}
+			current = '';
+		} else {
+			current += char;
+		}
+	}
+
+	if (current.trim()) {
+		const paramName = current.trim().split('=')[0].trim();
+		if (paramName) {
+			params.push(paramName);
+		}
+	}
+
+	return params.length > 0 ? params : ['value', 'record']; // Default fallback
+}
+
+function compile(functionString: string): ((...args: any[]) => any) | undefined {
+	const trimmed = stripTypeScriptHelpers(functionString).trim();
+
+	if (trimmed.includes('=>')) {
+		const arrowIndex = trimmed.indexOf('=>');
+		const afterArrow = trimmed.substring(arrowIndex + 2).trim();
+		const beforeArrow = trimmed.substring(0, arrowIndex).trim();
+		const params = extractParameters(beforeArrow);
+
+		if (afterArrow.startsWith('{')) {
+			// Block body — extract content between balanced braces
+			let braceCount = 0;
+			let startIndex = 0;
+			let endIndex = afterArrow.length;
+
+			for (let i = 0; i < afterArrow.length; i++) {
+				if (afterArrow[i] === '{') {
+					if (braceCount === 0) startIndex = i + 1;
+					braceCount++;
+				} else if (afterArrow[i] === '}') {
+					braceCount--;
+					if (braceCount === 0) {
+						endIndex = i;
+						break;
+					}
+				}
+			}
+
+			const functionBody = afterArrow.substring(startIndex, endIndex).trim();
+			return new Function(...params, functionBody) as (...args: any[]) => any;
+		}
+
+		// Expression body — wrap in a return statement
+		return new Function(...params, `return ${afterArrow}`) as (...args: any[]) => any;
+	}
+
+	if (trimmed.startsWith('function')) {
+		return new Function(`return ${trimmed}`)() as (...args: any[]) => any;
+	}
+
+	// Bare function body, or an unrecognized wrapping
+	try {
+		return new Function('value', 'record', trimmed) as (...args: any[]) => any;
+	} catch {
+		// Last resort: treat the string as an expression evaluating to a function
+		const fn = new Function(`return (${trimmed})`)();
+		if (typeof fn === 'function') {
+			return fn as (...args: any[]) => any;
+		}
+		throw new Error('Serialized string is not a valid function');
+	}
+}
+
+/**
+ * Compile a serialized function string into a callable, with caching.
+ * Returns undefined (and logs) when the string cannot be compiled.
+ */
+export function compileSerializedFunction(functionString: string | undefined): ((...args: any[]) => any) | undefined {
+	if (!functionString) {
+		return undefined;
+	}
+
+	if (compileCache.has(functionString)) {
+		return compileCache.get(functionString);
+	}
+
+	let compiled: ((...args: any[]) => any) | undefined;
+	try {
+		compiled = compile(functionString);
+	} catch (error: any) {
+		console.error('Error compiling serialized function:', error);
+		console.error('Function string (first 500 chars):', functionString.substring(0, 500));
+		compiled = undefined;
+	}
+
+	compileCache.set(functionString, compiled);
+	return compiled;
+}
+
+/**
+ * Execute a serialized function with the given arguments.
+ * Without arguments, returns the compiled function itself.
+ * Returns undefined on compile or runtime errors.
+ *
+ * @example
+ * executeSerializedFunction('(value, record) => value.toUpperCase()', 'hello', {});
+ */
+export function executeSerializedFunction(functionString: string | undefined, ...args: any[]): any {
+	const fn = compileSerializedFunction(functionString);
+	if (!fn) {
+		return undefined;
+	}
+
+	if (args.length === 0) {
+		return fn;
+	}
+
+	try {
+		return fn(...args);
+	} catch (error: any) {
+		console.error('Error executing serialized function:', error);
+		console.error('Function string (first 500 chars):', functionString?.substring(0, 500));
+		return undefined;
+	}
+}

package/src/slots/Slot.test.tsx

@@ -0,0 +1,89 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Slot } from './Slot';
+import { SlotRegistryProvider } from '../contexts/SlotRegistryContext';
+import type { ResolvedSlots, SlotContext } from './types';
+
+function renderSlot(slots: ResolvedSlots, context?: Omit<SlotContext, 'slot'>) {
+	return render(
+		<SlotRegistryProvider slots={slots}>
+			<Slot name="header.right" context={context} />
+		</SlotRegistryProvider>,
+	);
+}
+
+describe('Slot', () => {
+	it('renders nothing when the slot has no contributions', () => {
+		const { container } = renderSlot({});
+		expect(container).toBeEmptyDOMElement();
+	});
+
+	it('renders multiple contributions in their resolved order', () => {
+		renderSlot({
+			'header.right': [
+				{ id: 'one', render: () => <span data-testid="item">one</span> },
+				{ id: 'two', render: () => <span data-testid="item">two</span> },
+			],
+		});
+		const items = screen.getAllByTestId('item');
+		expect(items.map(el => el.textContent)).toEqual(['one', 'two']);
+	});
+
+	it('passes the slot context to a render function', () => {
+		renderSlot(
+			{
+				'header.right': [
+					{ id: 'ctx', render: ctx => <span data-testid="ctx">{String(ctx.resourceSlug)}</span> },
+				],
+			},
+			{ resourceSlug: 'posts' },
+		);
+		expect(screen.getByTestId('ctx')).toHaveTextContent('posts');
+		// slot name is injected automatically
+	});
+
+	it('passes the slot context to a component contribution', () => {
+		function Comp(ctx: SlotContext) {
+			return <span data-testid="comp">{ctx.slot}</span>;
+		}
+		renderSlot({ 'header.right': [{ id: 'comp', render: Comp }] });
+		expect(screen.getByTestId('comp')).toHaveTextContent('header.right');
+	});
+
+	it('forwards slot-specific extras via context.data', () => {
+		renderSlot(
+			{
+				'header.right': [
+					{ id: 'd', render: ctx => <span data-testid="data">{String(ctx.data?.selectedCount)}</span> },
+				],
+			},
+			{ data: { selectedCount: 3 } },
+		);
+		expect(screen.getByTestId('data')).toHaveTextContent('3');
+	});
+
+	describe('error isolation', () => {
+		beforeEach(() => {
+			// ErrorBoundary logs via console.error; silence it for these cases.
+			vi.spyOn(console, 'error').mockImplementation(() => {});
+		});
+		afterEach(() => {
+			vi.restoreAllMocks();
+		});
+
+		it('isolates a throwing contribution so siblings still render', () => {
+			function Boom(): React.ReactElement {
+				throw new Error('boom');
+			}
+			renderSlot({
+				'header.right': [
+					{ id: 'boom', render: Boom },
+					{ id: 'ok', render: () => <span data-testid="ok">ok</span> },
+				],
+			});
+			// Sibling still renders; the boundary shows its fallback for the failed one.
+			expect(screen.getByTestId('ok')).toBeInTheDocument();
+			expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();
+		});
+	});
+});

package/src/slots/Slot.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { ErrorBoundary } from '../components/errors/ErrorBoundary';
+import { useSlot } from '../contexts/SlotRegistryContext';
+import type { SlotContext, SlotContribution, SlotName } from './types';
+
+/**
+ * Render one contribution. Both a React component and a plain
+ * `(ctx) => ReactNode` are function components of the context, so a single
+ * `createElement` path covers both forms.
+ */
+export function renderSlot(contribution: SlotContribution, context: SlotContext): React.ReactNode {
+	return (
+		<ErrorBoundary key={contribution.id} label={`slot "${context.slot}" (${contribution.id})`}>
+			{React.createElement(contribution.render as React.ComponentType<SlotContext>, context)}
+		</ErrorBoundary>
+	);
+}
+
+export interface SlotProps {
+	/** The slot to render. */
+	name: SlotName;
+	/** Context passed to each contribution. `slot` is filled in automatically. */
+	context?: Omit<SlotContext, 'slot'>;
+	/** Optional wrapper element type. Defaults to a Fragment (no DOM). */
+	as?: React.ElementType;
+	/** className for the wrapper (ignored when `as` is omitted). */
+	className?: string;
+}
+
+/**
+ * Renders every contribution registered for `name`, in order, each isolated by
+ * an `ErrorBoundary`. Renders nothing (no wrapper DOM) when the slot is empty,
+ * so slots stay invisible until something is contributed.
+ */
+export function Slot({ name, context, as, className }: SlotProps) {
+	const contributions = useSlot(name);
+	if (contributions.length === 0) return null;
+
+	const fullContext: SlotContext = { ...context, slot: name };
+	const children = contributions.map(contribution => renderSlot(contribution, fullContext));
+
+	if (as) {
+		const Wrapper = as;
+		return <Wrapper className={className}>{children}</Wrapper>;
+	}
+	return <>{children}</>;
+}