@maxal_studio/kratosjs-react 1.0.0

package/src/api/resourceApi.ts

@@ -0,0 +1,88 @@
+import { apiGet, apiPost } from './http';
+
+/**
+ * Typed endpoints for the panel's resource API.
+ * All functions take the panel apiBaseUrl (e.g. http://host/kratosjs/api) and a resource slug.
+ */
+
+export interface RecordEnvelope<T = any> {
+	data: T;
+	metadata?: { recordTitle?: string; refreshBadges?: boolean; [key: string]: any };
+}
+
+/** Normalize bare-record responses into the `{ data, metadata }` envelope. */
+function toEnvelope<T = any>(result: any): RecordEnvelope<T> {
+	if (result && typeof result === 'object' && 'data' in result) {
+		return result as RecordEnvelope<T>;
+	}
+	return { data: result as T };
+}
+
+/** GET /:slug/:id */
+export async function getRecord(apiBaseUrl: string, slug: string, id: string | number): Promise<RecordEnvelope> {
+	return toEnvelope(await apiGet(`${apiBaseUrl}/${slug}/${id}`, apiBaseUrl));
+}
+
+/** POST /:slug */
+export async function createRecord(apiBaseUrl: string, slug: string, payload: any): Promise<RecordEnvelope> {
+	return toEnvelope(await apiPost(`${apiBaseUrl}/${slug}`, payload, apiBaseUrl));
+}
+
+/** POST /:slug/update/:id */
+export async function updateRecord(
+	apiBaseUrl: string,
+	slug: string,
+	id: string | number,
+	payload: any,
+): Promise<RecordEnvelope> {
+	return toEnvelope(await apiPost(`${apiBaseUrl}/${slug}/update/${id}`, payload, apiBaseUrl));
+}
+
+/** POST /:slug/bulk-delete */
+export function bulkDelete(
+	apiBaseUrl: string,
+	slug: string,
+	ids: any[],
+): Promise<{ deleted?: any[]; metadata?: { refreshBadges?: boolean }; [key: string]: any }> {
+	return apiPost(`${apiBaseUrl}/${slug}/bulk-delete`, { ids }, apiBaseUrl);
+}
+
+/** GET /:slug/schema/form — returns the serialized form schema */
+export async function getFormSchema(apiBaseUrl: string, slug: string): Promise<any> {
+	const result = await apiGet<any>(`${apiBaseUrl}/${slug}/schema/form`, apiBaseUrl);
+	return result?.schema || result;
+}
+
+/**
+ * GET /:slug/schema/table — returns the serialized table schema with
+ * the resource capability flags merged in (as TableRenderer expects).
+ */
+export async function getTableSchema(apiBaseUrl: string, slug: string): Promise<any> {
+	const result = await apiGet<any>(`${apiBaseUrl}/${slug}/schema/table`, apiBaseUrl);
+	return {
+		...(result?.schema || result),
+		canCreate: result?.canCreate,
+		canEdit: result?.canEdit,
+		canDelete: result?.canDelete,
+		canView: result?.canView,
+	};
+}
+
+/** GET /:slug/relations — relation metadata for the view modal */
+export async function getRelations(apiBaseUrl: string, slug: string): Promise<any[]> {
+	const result = await apiGet<any>(`${apiBaseUrl}/${slug}/relations`, apiBaseUrl);
+	return result?.relations || [];
+}
+
+/** POST /:parentSlug/:parentId/relations/:relationName */
+export async function createRelationRecord(
+	apiBaseUrl: string,
+	parentSlug: string,
+	parentId: string | number,
+	relationName: string,
+	payload: any,
+): Promise<RecordEnvelope> {
+	return toEnvelope(
+		await apiPost(`${apiBaseUrl}/${parentSlug}/${parentId}/relations/${relationName}`, payload, apiBaseUrl),
+	);
+}

package/src/api/tableApi.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { TableApiClient } from './tableApi';
+import { mockFetch, restoreFetch } from '../test/mockFetch';
+
+const API = 'http://api.test/admin';
+const LIST_URL = `${API}/users`;
+
+describe('TableApiClient', () => {
+	afterEach(() => {
+		restoreFetch();
+	});
+
+	it('posts query params to baseUrl + fetchPath and returns the result', async () => {
+		const result = {
+			data: [{ id: 1 }],
+			pagination: { page: 1, limit: 25, total: 1, pages: 1, hasNext: false, hasPrev: false },
+		};
+		const requests = mockFetch([{ match: '/users/list', body: result }]);
+
+		const client = new TableApiClient(API, LIST_URL, '/list');
+		const data = await client.fetchData({ page: 1, perPage: 25, search: 'jane' });
+
+		expect(data).toEqual(result);
+		expect(requests[0].method).toBe('POST');
+		expect(requests[0].body).toEqual({ page: 1, perPage: 25, search: 'jane' });
+	});
+
+	it('sends credentials:include and no Authorization header on requests', async () => {
+		mockFetch([{ match: '/users/list', body: { data: [], pagination: {} } }]);
+
+		const client = new TableApiClient(API, LIST_URL, '/list');
+		await client.fetchData({});
+
+		const fetchMock = globalThis.fetch as unknown as { mock: { calls: [string, RequestInit][] } };
+		const init = fetchMock.mock.calls[0][1];
+		expect(init?.credentials).toBe('include');
+		expect(new Headers(init?.headers).get('Authorization')).toBeNull();
+	});
+
+	it('throws an unauthorized error on 401 when refresh is not possible', async () => {
+		mockFetch([{ match: '/users/list', status: 401, body: { message: 'nope' } }]);
+
+		const client = new TableApiClient(API, LIST_URL, '/list');
+		await expect(client.fetchData({})).rejects.toThrow(/Unauthorized/);
+	});
+
+	it('calls the refresh endpoint and retries on 401', async () => {
+		const calls: { url: string; init?: RequestInit }[] = [];
+		let listCallCount = 0;
+
+		vi.stubGlobal('fetch', (async (input: RequestInfo | URL, init?: RequestInit) => {
+			const url = String(input);
+			calls.push({ url, init });
+
+			if (url.includes('/auth/refresh')) {
+				return new Response(JSON.stringify({ tokens: { expiresIn: 900 } }), {
+					status: 200,
+					headers: { 'Content-Type': 'application/json' },
+				});
+			}
+
+			listCallCount++;
+			if (listCallCount === 1) {
+				return new Response(JSON.stringify({ message: 'expired' }), {
+					status: 401,
+					headers: { 'Content-Type': 'application/json' },
+				});
+			}
+			return new Response(JSON.stringify({ data: [{ id: 7 }], pagination: {} }), {
+				status: 200,
+				headers: { 'Content-Type': 'application/json' },
+			});
+		}) as typeof fetch);
+
+		const client = new TableApiClient(API, LIST_URL, '/list');
+		const result = await client.fetchData({});
+
+		expect(result.data).toEqual([{ id: 7 }]);
+		expect(calls.some(c => c.url.includes('/auth/refresh'))).toBe(true);
+		// Retry must also use credentials:include — no localStorage involved
+		const retryCall = calls.find(c => c.url.includes('/users/list') && calls.indexOf(c) > 0);
+		expect(retryCall?.init?.credentials).toBe('include');
+	});
+
+	it('unwraps { data } from updateRecord responses', async () => {
+		mockFetch([{ match: '/users/update/5', body: { data: { id: 5, name: 'x' }, metadata: {} } }]);
+
+		const client = new TableApiClient(API, LIST_URL, '/list');
+		const updated = await client.updateRecord(5, { name: 'x' });
+		expect(updated).toEqual({ id: 5, name: 'x' });
+	});
+
+	it('returns the full body from deleteRecords', async () => {
+		const body = { deleted: [1, 2], metadata: { refreshBadges: true } };
+		const requests = mockFetch([{ match: '/users/bulk-delete', body }]);
+
+		const client = new TableApiClient(API, LIST_URL, '/list');
+		const result = await client.deleteRecords([1, 2]);
+
+		expect(result).toEqual(body);
+		expect(requests[0].body).toEqual({ ids: [1, 2] });
+	});
+
+	it('strips trailing slashes from the base url', () => {
+		const client = new TableApiClient(API, `${LIST_URL}/`, '/list');
+		expect(client.getBaseUrl()).toBe(LIST_URL);
+	});
+});

package/src/api/tableApi.ts

@@ -0,0 +1,107 @@
+import { apiPost } from './http';
+
+/**
+ * Query parameters for table API requests
+ */
+export interface QueryParams {
+	page?: number;
+	perPage?: number;
+	search?: string;
+	sort?: string;
+	sortDirection?: 'asc' | 'desc';
+	filters?: Record<string, any>;
+	queryBuilders?: Record<string, any[]>;
+}
+
+/**
+ * Standard pagination metadata
+ */
+export interface PaginationMeta {
+	/** Current page number (1-indexed) */
+	page: number;
+	/** Number of items per page */
+	limit: number;
+	/** Total number of items across all pages */
+	total: number;
+	/** Total number of pages */
+	pages: number;
+	/** Whether there's a next page */
+	hasNext: boolean;
+	/** Whether there's a previous page */
+	hasPrev: boolean;
+}
+
+/**
+ * Result structure for table API responses
+ */
+export interface QueryResult {
+	data: any[];
+	pagination: PaginationMeta;
+	widgets?: Record<string, any>;
+}
+
+/**
+ * API client for communicating with the table backend
+ */
+export class TableApiClient {
+	private baseUrl: string;
+	private apiBaseUrl: string;
+	private fetchPath: string;
+
+	/**
+	 * @param apiBaseUrl - Base URL for the panel API (used for token refresh)
+	 * @param baseUrl - Base URL of the resource endpoint (e.g. 'http://localhost:3001/api/users')
+	 * @param fetchPath - Path appended for list queries ('/list' for resources, '' for custom endpoints)
+	 */
+	constructor(apiBaseUrl: string, baseUrl: string, fetchPath: string = '') {
+		this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+		this.fetchPath = fetchPath;
+		this.apiBaseUrl = apiBaseUrl;
+	}
+
+	/**
+	 * Fetch table data with filtering, sorting, and pagination
+	 */
+	async fetchData(params: QueryParams): Promise<QueryResult> {
+		return apiPost<QueryResult>(this.baseUrl + this.fetchPath, params, this.apiBaseUrl);
+	}
+
+	/**
+	 * Update a single record. Unwraps the `{ data, metadata }` envelope.
+	 */
+	async updateRecord(id: any, data: any): Promise<any> {
+		const result = await apiPost<any>(`${this.baseUrl}/update/${id}`, data, this.apiBaseUrl);
+		return result?.data || result;
+	}
+
+	/**
+	 * Delete records (bulk or single).
+	 * Returns the full response body (including metadata e.g. refreshBadges) so callers can react to it.
+	 */
+	async deleteRecords(
+		ids: any[],
+	): Promise<{ deleted?: any[]; metadata?: { refreshBadges?: boolean }; [key: string]: any }> {
+		return apiPost(`${this.baseUrl}/bulk-delete`, { ids }, this.apiBaseUrl);
+	}
+
+	/**
+	 * Bulk delete records (alias for deleteRecords)
+	 */
+	async bulkDelete(
+		ids: any[],
+	): Promise<{ deleted?: any[]; metadata?: { refreshBadges?: boolean }; [key: string]: any }> {
+		return this.deleteRecords(ids);
+	}
+
+	getBaseUrl(): string {
+		return this.baseUrl;
+	}
+
+	getFetchPath(): string {
+		return this.fetchPath;
+	}
+
+	getApiBaseUrl(): string {
+		return this.apiBaseUrl;
+	}
+}

package/src/api/urls.ts

@@ -0,0 +1,50 @@
+/**
+ * URL derivation helpers shared by the table, modals and API clients.
+ */
+
+/**
+ * Derive the panel API base URL from a resource API URL.
+ *
+ * - `.../api/users` -> `.../api`
+ * - `.../api/users/1/relations/posts` -> `.../api`
+ */
+export function deriveApiBaseUrl(apiUrl: string): string {
+	if (apiUrl.includes('/relations/')) {
+		const baseUrl = apiUrl.substring(0, apiUrl.indexOf('/relations/'));
+		// Remove the record id segment to get back to the api base
+		return baseUrl.substring(0, baseUrl.lastIndexOf('/'));
+	}
+	return apiUrl.substring(0, apiUrl.lastIndexOf('/'));
+}
+
+/** Last path segment of a resource API URL (the resource slug). */
+export function resourceSlugFromUrl(apiUrl: string): string {
+	return apiUrl.split('/').filter(Boolean).pop() || '';
+}
+
+/** Deterministic, short, filesystem/localStorage-safe hash of a string. */
+export function hashString(str: string): string {
+	let hash = 0;
+	for (let i = 0; i < str.length; i++) {
+		const char = str.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash; // Convert to 32-bit integer
+	}
+	return Math.abs(hash).toString(36);
+}
+
+/**
+ * Stable key for per-resource localStorage entries (column visibility, layout).
+ * Non-resource tables hash the URL; relation tables use the relation slug.
+ */
+export function resourceStorageKey(apiUrl: string, isResource: boolean, relatedResourceSlug?: string): string {
+	if (!isResource) {
+		return hashString(apiUrl);
+	}
+	if (relatedResourceSlug) {
+		return relatedResourceSlug.replace(/[^a-zA-Z0-9_]/g, '_');
+	}
+	const segments = apiUrl.split('/').filter(Boolean);
+	const lastSegment = segments[segments.length - 1] || segments[segments.length - 2] || 'resource';
+	return lastSegment.replace(/[^a-zA-Z0-9_]/g, '_');
+}

package/src/app.test.tsx

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { resolveRegistries } from './app';
+import { definePluginClient } from './plugin';
+
+// Minimal stand-in components — resolveRegistries only moves references around.
+const AppField = () => null;
+const PluginField = () => null;
+const AppColumn = () => null;
+const AppWidget = () => null;
+const AppBlock = () => null;
+
+describe('resolveRegistries (mountAdminPanel direct registration)', () => {
+	it('exposes app-level fields/columns/widgets/blocks without a plugin', () => {
+		const registries = resolveRegistries({
+			fields: { 'star-rating': AppField },
+			columns: { 'star-rating': AppColumn },
+			widgets: { card: AppWidget },
+			blocks: { 'lives-page': AppBlock },
+		});
+
+		expect(registries.fields['star-rating']).toBe(AppField);
+		expect(registries.columns['star-rating']).toBe(AppColumn);
+		expect(registries.widgets.card).toBe(AppWidget);
+		expect(registries.blocks['lives-page']).toBe(AppBlock);
+	});
+
+	it('lets app registrations win over a plugin on the same key', () => {
+		const plugin = definePluginClient({
+			name: 'star-rating',
+			fields: { 'star-rating': PluginField },
+		});
+
+		const registries = resolveRegistries({
+			plugins: [plugin],
+			fields: { 'star-rating': AppField },
+		});
+
+		expect(registries.fields['star-rating']).toBe(AppField);
+	});
+
+	it('keeps plugin entries that the app does not override', () => {
+		const plugin = definePluginClient({ fields: { 'plugin-only': PluginField } });
+
+		const registries = resolveRegistries({
+			plugins: [plugin],
+			fields: { 'star-rating': AppField },
+		});
+
+		expect(registries.fields['plugin-only']).toBe(PluginField);
+		expect(registries.fields['star-rating']).toBe(AppField);
+	});
+
+	it('flows app-level validation rules into the merged rule map', () => {
+		const phoneRule = { name: 'phone', validate: () => true } as any;
+		const registries = resolveRegistries({ rules: { phone: phoneRule } });
+		expect(registries.rules.phone).toBe(phoneRule);
+	});
+
+	it('returns empty registries when given no options', () => {
+		const registries = resolveRegistries();
+		expect(registries.fields).toEqual({});
+		expect(registries.columns).toEqual({});
+		expect(registries.widgets).toEqual({});
+		expect(registries.blocks).toEqual({});
+		expect(registries.rules).toEqual({});
+	});
+});

package/src/app.tsx

@@ -0,0 +1,181 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { AdminPanel } from './components/AdminPanel';
+import { mergePluginClients } from './plugin';
+import type { KratosPluginClient, MergedPluginRegistries } from './plugin';
+import type { FieldRegistry, WidgetRegistry, BlockRegistry } from './types';
+import type { ColumnRegistry } from './contexts/ColumnRegistryContext';
+import type { AuthChallengeRegistry } from './contexts/AuthChallengeRegistryContext';
+import type { RuleDefinition } from '@maxal_studio/kratosjs';
+import { ValidationEngine } from '@maxal_studio/kratosjs/dist/validation';
+import type { ClientI18nConfig } from './i18n/buildClientI18n';
+import type { SlotMap } from './slots/types';
+
+export interface MountAdminPanelOptions {
+	/** Client manifests of the plugins used by this panel */
+	plugins?: KratosPluginClient[];
+	/**
+	 * Custom field components keyed by field type (e.g. `'star-rating'`).
+	 * Registered directly by the app — no plugin required. The key must match the
+	 * `componentType` emitted by the backend builder. App entries override plugins.
+	 */
+	fields?: FieldRegistry;
+	/** Custom table column components keyed by column type. App entries override plugins. */
+	columns?: ColumnRegistry;
+	/** Custom widget components keyed by widget type. App entries override plugins. */
+	widgets?: WidgetRegistry;
+	/** Custom page block components keyed by block type. App entries override plugins. */
+	blocks?: BlockRegistry;
+	/** Challenge UI components keyed by challenge type. App entries override plugins. */
+	authChallenges?: AuthChallengeRegistry;
+	/**
+	 * Custom validation rules keyed by rule name. Authored once and shared with the
+	 * server (via `panel.registerValidationRule`) so they validate identically on
+	 * both sides. App entries override plugins.
+	 */
+	rules?: Record<string, RuleDefinition>;
+	/**
+	 * UI slot contributions keyed by slot name (e.g. `'header.right'`). Slots are
+	 * 1:many — app contributions stack alongside any from plugins. A value is a
+	 * single `SlotContribution` or an array.
+	 *
+	 * @example
+	 * mountAdminPanel({
+	 *   slots: { 'header.right': { id: 'help', render: () => <HelpButton /> } },
+	 * });
+	 */
+	slots?: SlotMap;
+	/**
+	 * API base URL. Defaults to the base path injected by the KratosJs server
+	 * (window.__VALAJS_API_BASE_PATH__) on the current origin.
+	 */
+	apiBaseUrl?: string;
+	/**
+	 * Optional i18n override. Locales and every app/plugin catalog are authored once
+	 * on the server and injected into the page (`window.__VALAJS_I18N__`) — you rarely
+	 * need this. Use it only to override built-in `core:` chrome or add React-only
+	 * strings; `translations` keys may target any namespace via a `ns:` prefix
+	 * (e.g. `core:common.save`), unprefixed keys → `app`. It layers over the injected config.
+	 *
+	 * @example
+	 * mountAdminPanel({ i18n: { translations: { en: { 'core:common.save': 'Store' } } } });
+	 */
+	i18n?: ClientI18nConfig;
+	/** Panel id when serving multiple panels */
+	panelId?: string;
+	/** DOM element id to mount into (default: 'root') */
+	rootElementId?: string;
+	/**
+	 * Accent color override (any CSS color). Sets the --kratos-accent tokens
+	 * on the document root; hover/soft shades are derived automatically.
+	 */
+	accentColor?: string;
+}
+
+/**
+ * Resolve the merged component/rule registries from mount options.
+ *
+ * Plugin manifests are merged first, then the app's own direct registrations
+ * (`fields`/`columns`/`widgets`/`blocks`/`rules`) are applied last so an app
+ * always wins over a plugin on a key collision.
+ */
+export function resolveRegistries(options: MountAdminPanelOptions = {}): MergedPluginRegistries {
+	const appManifest: KratosPluginClient = {
+		name: 'app',
+		fields: options.fields,
+		columns: options.columns,
+		widgets: options.widgets,
+		blocks: options.blocks,
+		authChallenges: options.authChallenges,
+		rules: options.rules,
+		slots: options.slots,
+	};
+	return mergePluginClients([...(options.plugins ?? []), appManifest]);
+}
+
+function applyAccentColor(accentColor: string): void {
+	const root = document.documentElement;
+	root.style.setProperty('--kratos-accent', accentColor);
+	root.style.setProperty('--kratos-accent-hover', `color-mix(in srgb, ${accentColor} 85%, black)`);
+	root.style.setProperty('--kratos-accent-soft', `color-mix(in srgb, ${accentColor} 15%, transparent)`);
+}
+
+function resolveApiBaseUrl(): string {
+	const basePath = (window as any).__VALAJS_API_BASE_PATH__ || '/api';
+	return `${window.location.origin}${basePath}`;
+}
+
+/**
+ * The i18n config the KratosJs server injects into the admin HTML
+ * (`window.__VALAJS_I18N__`). This is the source of truth for locales and every
+ * app/plugin catalog — authored once on the server.
+ */
+function resolveInjectedI18n(): ClientI18nConfig {
+	return ((window as any).__VALAJS_I18N__ as ClientI18nConfig | undefined) ?? {};
+}
+
+/**
+ * Mount the KratosJs admin panel into the DOM.
+ *
+ * This is the entry point apps use in their admin client bundle:
+ *
+ * @example
+ * ```typescript
+ * // src/admin/main.tsx — register custom components directly, no plugin needed
+ * import { mountAdminPanel } from '@maxal_studio/kratosjs-react';
+ * import '@maxal_studio/kratosjs-react/styles.css';
+ * import StarRatingField from './components/StarRatingField';
+ *
+ * mountAdminPanel({
+ *   fields: { 'star-rating': StarRatingField },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Packaged plugins still work, and can be combined with app registrations:
+ * import starRating from '@maxal_studio/kratosjs-plugin-star-rating/client';
+ *
+ * mountAdminPanel({ plugins: [starRating] });
+ * ```
+ */
+export function mountAdminPanel(options: MountAdminPanelOptions = {}): void {
+	const rootElement = document.getElementById(options.rootElementId ?? 'root');
+	if (!rootElement) {
+		throw new Error(`Root element "#${options.rootElementId ?? 'root'}" not found`);
+	}
+
+	const registries = resolveRegistries(options);
+
+	// Register plugin-provided validation rules into the shared engine so the
+	// client validates them exactly as the server does.
+	for (const definition of Object.values(registries.rules)) {
+		ValidationEngine.register(definition);
+	}
+
+	const apiBaseUrl = options.apiBaseUrl ?? resolveApiBaseUrl();
+
+	// The server-injected config (locales + app/plugin catalogs) is the base; any
+	// explicit `options.i18n` from the mount call layers on top as an override.
+	const i18nConfig: ClientI18nConfig = { ...resolveInjectedI18n(), ...options.i18n };
+
+	if (options.accentColor) {
+		applyAccentColor(options.accentColor);
+	}
+
+	ReactDOM.createRoot(rootElement).render(
+		<React.StrictMode>
+			<AdminPanel
+				apiBaseUrl={apiBaseUrl}
+				panelId={options.panelId}
+				customFields={registries.fields}
+				customColumns={registries.columns}
+				customWidgets={registries.widgets}
+				customBlocks={registries.blocks}
+				customAuthChallenges={registries.authChallenges}
+				customSlots={registries.slots}
+				i18nConfig={i18nConfig}
+			/>
+		</React.StrictMode>,
+	);
+}