@maxal_studio/kratosjs-react 1.0.0

package/dist/api/tableApi.js

@@ -0,0 +1,51 @@
+import { apiPost } from './http';
+/**
+ * API client for communicating with the table backend
+ */
+export class TableApiClient {
+    /**
+     * @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, baseUrl, fetchPath = '') {
+        this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.fetchPath = fetchPath;
+        this.apiBaseUrl = apiBaseUrl;
+    }
+    /**
+     * Fetch table data with filtering, sorting, and pagination
+     */
+    async fetchData(params) {
+        return apiPost(this.baseUrl + this.fetchPath, params, this.apiBaseUrl);
+    }
+    /**
+     * Update a single record. Unwraps the `{ data, metadata }` envelope.
+     */
+    async updateRecord(id, data) {
+        const result = await apiPost(`${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) {
+        return apiPost(`${this.baseUrl}/bulk-delete`, { ids }, this.apiBaseUrl);
+    }
+    /**
+     * Bulk delete records (alias for deleteRecords)
+     */
+    async bulkDelete(ids) {
+        return this.deleteRecords(ids);
+    }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    getFetchPath() {
+        return this.fetchPath;
+    }
+    getApiBaseUrl() {
+        return this.apiBaseUrl;
+    }
+}

package/dist/api/urls.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function deriveApiBaseUrl(apiUrl: string): string;
+/** Last path segment of a resource API URL (the resource slug). */
+export declare function resourceSlugFromUrl(apiUrl: string): string;
+/** Deterministic, short, filesystem/localStorage-safe hash of a string. */
+export declare function hashString(str: string): string;
+/**
+ * Stable key for per-resource localStorage entries (column visibility, layout).
+ * Non-resource tables hash the URL; relation tables use the relation slug.
+ */
+export declare function resourceStorageKey(apiUrl: string, isResource: boolean, relatedResourceSlug?: string): string;

package/dist/api/urls.js

@@ -0,0 +1,46 @@
+/**
+ * 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) {
+    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) {
+    return apiUrl.split('/').filter(Boolean).pop() || '';
+}
+/** Deterministic, short, filesystem/localStorage-safe hash of a string. */
+export function hashString(str) {
+    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, isResource, relatedResourceSlug) {
+    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/dist/app.d.ts

@@ -0,0 +1,101 @@
+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 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 declare function resolveRegistries(options?: MountAdminPanelOptions): MergedPluginRegistries;
+/**
+ * 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 declare function mountAdminPanel(options?: MountAdminPanelOptions): void;

package/dist/app.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { AdminPanel } from './components/AdminPanel';
+import { mergePluginClients } from './plugin';
+import { ValidationEngine } from '@maxal_studio/kratosjs/dist/validation';
+/**
+ * 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 = {}) {
+    const appManifest = {
+        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) {
+    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() {
+    const basePath = window.__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() {
+    return window.__VALAJS_I18N__ ?? {};
+}
+/**
+ * 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 = {}) {
+    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 = { ...resolveInjectedI18n(), ...options.i18n };
+    if (options.accentColor) {
+        applyAccentColor(options.accentColor);
+    }
+    ReactDOM.createRoot(rootElement).render(_jsx(React.StrictMode, { children: _jsx(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 }) }));
+}

package/dist/auth/AuthContext.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { AuthUser, LoginCredentials, PendingChallenge } from './types';
+interface AuthContextValue {
+    user: AuthUser | null;
+    loading: boolean;
+    /** A challenge (e.g. 2FA) awaiting the user's response, or null. */
+    pendingChallenge: PendingChallenge | null;
+    login: (provider: string, credentials: LoginCredentials) => Promise<void>;
+    /** Submit a response to the active `pendingChallenge`. */
+    verifyChallenge: (payload: unknown) => Promise<void>;
+    /** Abandon the active challenge and return to the login form. */
+    cancelChallenge: () => void;
+    logout: () => Promise<void>;
+    refreshUser: () => Promise<void>;
+}
+interface AuthProviderProps {
+    children: React.ReactNode;
+    apiBaseUrl: string;
+}
+export declare function AuthProvider({ children, apiBaseUrl }: AuthProviderProps): React.JSX.Element;
+export declare function useAuth(): AuthContextValue;
+export {};

package/dist/auth/AuthContext.js

@@ -0,0 +1,147 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useState, useEffect, useCallback, useRef } from 'react';
+import { AuthApiClient } from './authApiClient';
+const AuthContext = createContext(null);
+export function AuthProvider({ children, apiBaseUrl }) {
+    const [user, setUser] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [pendingChallenge, setPendingChallenge] = useState(null);
+    const apiClient = useRef(new AuthApiClient(apiBaseUrl));
+    const refreshTimerRef = useRef(null);
+    const scheduleTokenRefresh = useCallback((expiresIn) => {
+        if (refreshTimerRef.current) {
+            clearTimeout(refreshTimerRef.current);
+        }
+        // Refresh 1 minute before expiry, minimum 1 minute
+        const refreshTime = Math.max((expiresIn - 60) * 1000, 60000);
+        refreshTimerRef.current = setTimeout(async () => {
+            try {
+                const tokens = await apiClient.current.refreshToken();
+                if (tokens?.expiresIn) {
+                    scheduleTokenRefresh(tokens.expiresIn);
+                }
+                else {
+                    setUser(null);
+                }
+            }
+            catch {
+                setUser(null);
+            }
+        }, refreshTime);
+    }, []);
+    /**
+     * Fetch the current user from /auth/me.
+     * On 401, attempts a silent token refresh via the cookie before giving up.
+     * Seeds the proactive refresh timer when a refresh response includes expiresIn.
+     */
+    const fetchUser = useCallback(async () => {
+        try {
+            const currentUser = await apiClient.current.getCurrentUser();
+            setUser(currentUser);
+            return currentUser;
+        }
+        catch (error) {
+            if (error?.status === 401) {
+                try {
+                    const tokens = await apiClient.current.refreshToken();
+                    if (tokens) {
+                        if (tokens.expiresIn)
+                            scheduleTokenRefresh(tokens.expiresIn);
+                        const currentUser = await apiClient.current.getCurrentUser();
+                        setUser(currentUser);
+                        return currentUser;
+                    }
+                }
+                catch {
+                    // refresh failed — fall through to null
+                }
+            }
+            setUser(null);
+            return null;
+        }
+    }, [scheduleTokenRefresh]);
+    /** Apply an `authenticated` result: set the user and seed the refresh timer. */
+    const applyAuthenticated = useCallback((authUser, expiresIn) => {
+        setPendingChallenge(null);
+        setUser(authUser);
+        if (expiresIn) {
+            scheduleTokenRefresh(expiresIn);
+        }
+    }, [scheduleTokenRefresh]);
+    const login = useCallback(async (provider, credentials) => {
+        const result = await apiClient.current.login(provider, credentials);
+        if (result.status === 'authenticated') {
+            applyAuthenticated(result.user, result.tokens?.expiresIn);
+        }
+        else {
+            // Pause here: a challenge (e.g. 2FA) must be satisfied before tokens are issued.
+            setPendingChallenge(result.challenge);
+        }
+    }, [applyAuthenticated]);
+    const verifyChallenge = useCallback(async (payload) => {
+        if (!pendingChallenge) {
+            throw new Error('No challenge in progress');
+        }
+        const result = await apiClient.current.verifyChallenge(pendingChallenge.challengeToken, pendingChallenge.type, payload);
+        if (result.status === 'authenticated') {
+            applyAuthenticated(result.user, result.tokens?.expiresIn);
+        }
+        else {
+            // Chained step: replace with the next pending challenge.
+            setPendingChallenge(result.challenge);
+        }
+    }, [pendingChallenge, applyAuthenticated]);
+    const cancelChallenge = useCallback(() => {
+        setPendingChallenge(null);
+    }, []);
+    const logout = useCallback(async () => {
+        try {
+            await apiClient.current.logout();
+        }
+        catch {
+            // ignore
+        }
+        finally {
+            setUser(null);
+            setPendingChallenge(null);
+            if (refreshTimerRef.current) {
+                clearTimeout(refreshTimerRef.current);
+                refreshTimerRef.current = null;
+            }
+        }
+    }, []);
+    const refreshUser = useCallback(async () => {
+        await fetchUser();
+    }, [fetchUser]);
+    useEffect(() => {
+        const init = async () => {
+            setLoading(true);
+            await fetchUser();
+            setLoading(false);
+        };
+        init();
+        return () => {
+            if (refreshTimerRef.current) {
+                clearTimeout(refreshTimerRef.current);
+            }
+        };
+    }, [fetchUser]);
+    const value = {
+        user,
+        loading,
+        pendingChallenge,
+        login,
+        verifyChallenge,
+        cancelChallenge,
+        logout,
+        refreshUser,
+    };
+    return _jsx(AuthContext.Provider, { value: value, children: children });
+}
+export function useAuth() {
+    const context = useContext(AuthContext);
+    if (!context) {
+        throw new Error('useAuth must be used within an AuthProvider');
+    }
+    return context;
+}

package/dist/auth/LoginPage.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+interface LoginPageProps {
+    apiBaseUrl: string;
+    onSuccess?: () => void;
+}
+/**
+ * LoginPage - Displays authentication providers and handles login
+ */
+export declare function LoginPage({ apiBaseUrl, onSuccess }: LoginPageProps): React.JSX.Element;
+export {};