@maxal_studio/kratosjs-react 1.0.0

package/README.md

@@ -0,0 +1,44 @@
+# @maxal_studio/kratosjs-react
+
+React components for KratosJs. Render dynamic forms and tables from JSON schemas with React Hook Form and Tailwind CSS.
+
+## Documentation
+
+📚 **[View Documentation](./docs/README.md)**
+
+### Key Topics
+
+- [Getting Started](./docs/getting-started.md)
+
+### Related Documentation
+
+- [Forms Documentation](../docs/forms/overview.md) - Form fields and components
+- [Custom Fields](../docs/forms/custom-fields.md) - Creating custom form fields
+- [Tables Documentation](../docs/tables/overview.md) - Table columns and features
+- [Custom Columns](../docs/tables/custom-columns.md) - Creating custom table columns
+- [Custom Widgets](../docs/resources/custom-widgets.md) - Creating custom widgets
+
+## Installation
+
+```bash
+npm install @maxal_studio/kratosjs-react react-hook-form
+```
+
+**Peer Dependencies:**
+
+- `react` ^18.0.0
+- `react-dom` ^18.0.0
+- `react-hook-form` ^7.0.0
+
+**Styling:**
+
+Import the pre-built styles in your app:
+
+```js
+// In your main.tsx or App.tsx
+import '@maxal_studio/kratosjs-react/styles.css';
+```
+
+## License
+
+ISC

package/dist/FieldRenderer.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { FieldRendererProps } from './types';
+/**
+ * FieldRenderer component
+ * Dynamically renders the correct field component based on type
+ */
+export declare function FieldRenderer({ field, apiBaseUrl, resource, operation, mode, value, }: FieldRendererProps & {
+    apiBaseUrl?: string;
+    resource?: string;
+    operation?: 'create' | 'edit' | 'view';
+    mode?: 'edit' | 'view';
+    value?: any;
+}): React.JSX.Element;

package/dist/FieldRenderer.js

@@ -0,0 +1,62 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useWatch, useFormContext } from 'react-hook-form';
+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, }) {
+    const registry = useFieldRegistry();
+    const FieldComponent = registry[field.type];
+    // In view mode, we don't need form context
+    let formState = {};
+    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.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 (_jsx("div", { className: "mb-4 p-4 bg-yellow-50 border border-yellow-200 rounded-lg", children: _jsxs("p", { className: "text-sm text-yellow-800", children: [_jsxs("strong", { children: [translate('core:common.warning'), ":"] }), ' ', translate('core:state.unknown_field', { type: field.type, name: field.name })] }) }));
+    }
+    // Evaluate conditional hidden state — hiddenWhen is the structured-AST form
+    // (no code execution), hiddenFn the serialized-function form.
+    const isHidden = evaluateCondition(field.hiddenWhen ?? field.hiddenFn ?? field.hidden, formState, operation);
+    // Evaluate conditional disabled state
+    const isDisabled = evaluateCondition(field.disabledWhen ?? field.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 (_jsx("div", { className: columnClasses, children: _jsx(FieldComponent, { ...fieldWithEvaluatedProps }) }));
+    }
+    return _jsx(FieldComponent, { ...fieldWithEvaluatedProps });
+}

package/dist/FormRenderer.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+import { FormRendererProps } from './types';
+/**
+ * FormRenderer component
+ * Main component that accepts JSON schema and renders the form
+ */
+export declare function FormRenderer({ schema, onSubmit, defaultValues, className, apiBaseUrl, resource, operation, children, }: FormRendererProps): React.JSX.Element;

package/dist/FormRenderer.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { useForm, FormProvider } from 'react-hook-form';
+import { FieldRenderer } from './FieldRenderer';
+import { cn } from './utils/classNames';
+import { getGridClasses } from './components/utils/layoutHelpers';
+import { Button } from './components/ui/Button';
+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) {
+    const defaults = {};
+    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.minItems === 'number' && component.minItems > 0
+                    ? component.minItems
+                    : 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, }) {
+    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) => {
+        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 (_jsxs(FormProvider, { ...methods, children: [children, _jsxs("form", { onSubmit: methods.handleSubmit(handleSubmit), className: cn(className), noValidate: true, children: [_jsx(Slot, { name: "form.header", context: { resourceSlug: resource, record: defaultValues, schema }, as: "div", className: "mb-4 space-y-3 empty:hidden" }), _jsx("div", { className: formGridClasses, children: schema.components.map((field, index) => (_jsx(FieldRenderer, { field: field, apiBaseUrl: apiBaseUrl, resource: resource, operation: operation, mode: "edit" }, field.name || index))) }), _jsxs("div", { className: "flex flex-wrap items-center justify-end gap-3 pt-6", children: [_jsx(Slot, { name: "form.footer", context: { resourceSlug: resource, record: defaultValues, schema }, as: "div", className: "mr-auto flex flex-wrap items-center gap-2 empty:hidden" }), _jsx(Button, { variant: "secondary", onClick: () => methods.reset(), children: t('core:common.reset') }), _jsx(Button, { type: "submit", loading: methods.formState.isSubmitting, children: methods.formState.isSubmitting ? t('core:common.submitting') : t('core:common.submit') })] })] })] }));
+}

package/dist/TableRenderer.d.ts

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

package/dist/TableRenderer.js

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

package/dist/api/actionsApi.d.ts

@@ -0,0 +1,23 @@
+export interface ActionResult {
+    success: boolean;
+    message?: string;
+    data?: any;
+    redirect?: string;
+    [key: string]: any;
+}
+/**
+ * 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 declare function executeAction(apiUrl: string, actionName: string, recordId: string, formData?: any): Promise<ActionResult>;
+/**
+ * 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 declare function executeBulkAction(apiUrl: string, actionName: string, recordIds: string[], formData?: any): Promise<ActionResult>;

package/dist/api/actionsApi.js

@@ -0,0 +1,46 @@
+import { ApiError, apiPost } from './http';
+import { deriveApiBaseUrl } from './urls';
+import { translate } from '../i18n/activeLocale';
+async function runAction(apiUrl, actionName, recordIds, formData, isBulk) {
+    try {
+        const result = await apiPost(`${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) {
+        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, actionName, recordId, formData) {
+    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, actionName, recordIds, formData) {
+    return runAction(apiUrl, actionName, recordIds, formData, true);
+}

package/dist/api/authenticatedFetch.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function authenticatedFetch(url: string, options: RequestInit, apiBaseUrl: string): Promise<Response>;

package/dist/api/authenticatedFetch.js

@@ -0,0 +1,31 @@
+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, options = {}, apiBaseUrl) {
+    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/dist/api/exportApi.d.ts

@@ -0,0 +1,18 @@
+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 declare function downloadExport(resourceUrl: string, apiBaseUrl: string, options: ExportOptions): Promise<void>;

package/dist/api/exportApi.js

@@ -0,0 +1,50 @@
+import { authenticatedFetch } from './authenticatedFetch';
+/**
+ * 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, apiBaseUrl, options) {
+    const { format, action, query, recordIds } = options;
+    const url = `${resourceUrl.replace(/\/$/, '')}/export`;
+    const body = { 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) {
+    if (!header)
+        return undefined;
+    const match = /filename\*?=(?:UTF-8'')?["']?([^"';]+)["']?/i.exec(header);
+    return match ? decodeURIComponent(match[1]) : undefined;
+}
+function triggerBrowserDownload(blob, filename) {
+    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/dist/api/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare class ApiError extends Error {
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(message: string, status: number, details?: unknown);
+    get isUnauthorized(): boolean;
+}
+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 declare function apiFetch<T = unknown>(url: string, options: ApiFetchOptions): Promise<T>;
+/** Convenience JSON POST */
+export declare function apiPost<T = unknown>(url: string, payload: unknown, apiBaseUrl: string): Promise<T>;
+/** Convenience JSON GET */
+export declare function apiGet<T = unknown>(url: string, apiBaseUrl: string): Promise<T>;

package/dist/api/http.js

@@ -0,0 +1,52 @@
+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 {
+    constructor(message, status, details) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.details = details;
+    }
+    get isUnauthorized() {
+        return this.status === 401;
+    }
+}
+/**
+ * JSON fetch with auth + token refresh + uniform error handling.
+ * Throws ApiError on any non-ok response, preserving the server message.
+ */
+export async function apiFetch(url, options) {
+    const { apiBaseUrl, ...init } = options;
+    const response = await authenticatedFetch(url, init, apiBaseUrl);
+    let body = 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;
+}
+/** Convenience JSON POST */
+export function apiPost(url, payload, apiBaseUrl) {
+    return apiFetch(url, { method: 'POST', body: JSON.stringify(payload), apiBaseUrl });
+}
+/** Convenience JSON GET */
+export function apiGet(url, apiBaseUrl) {
+    return apiFetch(url, { apiBaseUrl });
+}

package/dist/api/resourceApi.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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;
+    };
+}
+/** GET /:slug/:id */
+export declare function getRecord(apiBaseUrl: string, slug: string, id: string | number): Promise<RecordEnvelope>;
+/** POST /:slug */
+export declare function createRecord(apiBaseUrl: string, slug: string, payload: any): Promise<RecordEnvelope>;
+/** POST /:slug/update/:id */
+export declare function updateRecord(apiBaseUrl: string, slug: string, id: string | number, payload: any): Promise<RecordEnvelope>;
+/** POST /:slug/bulk-delete */
+export declare function bulkDelete(apiBaseUrl: string, slug: string, ids: any[]): Promise<{
+    deleted?: any[];
+    metadata?: {
+        refreshBadges?: boolean;
+    };
+    [key: string]: any;
+}>;
+/** GET /:slug/schema/form — returns the serialized form schema */
+export declare function getFormSchema(apiBaseUrl: string, slug: string): Promise<any>;
+/**
+ * GET /:slug/schema/table — returns the serialized table schema with
+ * the resource capability flags merged in (as TableRenderer expects).
+ */
+export declare function getTableSchema(apiBaseUrl: string, slug: string): Promise<any>;
+/** GET /:slug/relations — relation metadata for the view modal */
+export declare function getRelations(apiBaseUrl: string, slug: string): Promise<any[]>;
+/** POST /:parentSlug/:parentId/relations/:relationName */
+export declare function createRelationRecord(apiBaseUrl: string, parentSlug: string, parentId: string | number, relationName: string, payload: any): Promise<RecordEnvelope>;

package/dist/api/resourceApi.js

@@ -0,0 +1,52 @@
+import { apiGet, apiPost } from './http';
+/** Normalize bare-record responses into the `{ data, metadata }` envelope. */
+function toEnvelope(result) {
+    if (result && typeof result === 'object' && 'data' in result) {
+        return result;
+    }
+    return { data: result };
+}
+/** GET /:slug/:id */
+export async function getRecord(apiBaseUrl, slug, id) {
+    return toEnvelope(await apiGet(`${apiBaseUrl}/${slug}/${id}`, apiBaseUrl));
+}
+/** POST /:slug */
+export async function createRecord(apiBaseUrl, slug, payload) {
+    return toEnvelope(await apiPost(`${apiBaseUrl}/${slug}`, payload, apiBaseUrl));
+}
+/** POST /:slug/update/:id */
+export async function updateRecord(apiBaseUrl, slug, id, payload) {
+    return toEnvelope(await apiPost(`${apiBaseUrl}/${slug}/update/${id}`, payload, apiBaseUrl));
+}
+/** POST /:slug/bulk-delete */
+export function bulkDelete(apiBaseUrl, slug, ids) {
+    return apiPost(`${apiBaseUrl}/${slug}/bulk-delete`, { ids }, apiBaseUrl);
+}
+/** GET /:slug/schema/form — returns the serialized form schema */
+export async function getFormSchema(apiBaseUrl, slug) {
+    const result = await apiGet(`${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, slug) {
+    const result = await apiGet(`${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, slug) {
+    const result = await apiGet(`${apiBaseUrl}/${slug}/relations`, apiBaseUrl);
+    return result?.relations || [];
+}
+/** POST /:parentSlug/:parentId/relations/:relationName */
+export async function createRelationRecord(apiBaseUrl, parentSlug, parentId, relationName, payload) {
+    return toEnvelope(await apiPost(`${apiBaseUrl}/${parentSlug}/${parentId}/relations/${relationName}`, payload, apiBaseUrl));
+}

package/dist/api/tableApi.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 declare class TableApiClient {
+    private baseUrl;
+    private apiBaseUrl;
+    private fetchPath;
+    /**
+     * @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);
+    /**
+     * Fetch table data with filtering, sorting, and pagination
+     */
+    fetchData(params: QueryParams): Promise<QueryResult>;
+    /**
+     * Update a single record. Unwraps the `{ data, metadata }` envelope.
+     */
+    updateRecord(id: any, data: any): Promise<any>;
+    /**
+     * Delete records (bulk or single).
+     * Returns the full response body (including metadata e.g. refreshBadges) so callers can react to it.
+     */
+    deleteRecords(ids: any[]): Promise<{
+        deleted?: any[];
+        metadata?: {
+            refreshBadges?: boolean;
+        };
+        [key: string]: any;
+    }>;
+    /**
+     * Bulk delete records (alias for deleteRecords)
+     */
+    bulkDelete(ids: any[]): Promise<{
+        deleted?: any[];
+        metadata?: {
+            refreshBadges?: boolean;
+        };
+        [key: string]: any;
+    }>;
+    getBaseUrl(): string;
+    getFetchPath(): string;
+    getApiBaseUrl(): string;
+}