@maxal_studio/kratosjs-react 1.0.0

package/dist/table/hooks/useTableQuery.js

@@ -0,0 +1,135 @@
+import { useEffect, useMemo, useState } from 'react';
+/**
+ * All list-query state for a table: search, sort, filters, query builders,
+ * tabs, and pagination — plus the handlers that keep them consistent
+ * (changing any criterion resets to page 1; manual filtering clears the tab).
+ */
+export function useTableQuery(schema) {
+    // Filter defaults come from the schema
+    const initialFilters = useMemo(() => {
+        const defaults = {};
+        schema.filters?.forEach(filter => {
+            if (filter.default !== undefined && filter.type !== 'queryBuilder') {
+                defaults[filter.name] = filter.default;
+            }
+        });
+        return defaults;
+    }, [schema.filters]);
+    const initialQueryBuilders = useMemo(() => {
+        const defaults = {};
+        schema.filters?.forEach(filter => {
+            if (filter.type === 'queryBuilder' && Array.isArray(filter.default)) {
+                defaults[filter.name] = filter.default;
+            }
+        });
+        return defaults;
+    }, [schema.filters]);
+    const [searchQuery, setSearchQuery] = useState('');
+    const [sortColumn, setSortColumn] = useState(schema.defaultSort?.column);
+    const [sortDirection, setSortDirection] = useState(schema.defaultSort?.direction || 'asc');
+    const [filters, setFilters] = useState(initialFilters);
+    const [queryBuilders, setQueryBuilders] = useState(initialQueryBuilders);
+    const [activeTab, setActiveTab] = useState(() => {
+        const tabs = schema.tabs;
+        return tabs?.find(tab => tab.default === true)?.key ?? null;
+    });
+    const [currentPage, setCurrentPage] = useState(1);
+    const [perPage, setPerPage] = useState(schema.recordsPerPage || 10);
+    // Reset filters to defaults when the schema changes
+    useEffect(() => {
+        setFilters(initialFilters);
+        setQueryBuilders(initialQueryBuilders);
+    }, [initialFilters, initialQueryBuilders]);
+    const handleSearch = (query) => {
+        setSearchQuery(query);
+        setCurrentPage(1);
+    };
+    const handleSort = (column) => {
+        setSortDirection(sortColumn === column && sortDirection === 'asc' ? 'desc' : 'asc');
+        setSortColumn(column);
+        setCurrentPage(1);
+    };
+    const handleFilterChange = (name, value, isQueryBuilder = false) => {
+        // Manual filtering clears the active tab
+        setActiveTab(null);
+        if (isQueryBuilder) {
+            setQueryBuilders(prev => {
+                const next = { ...prev };
+                if (value === undefined || (Array.isArray(value) && value.length === 0)) {
+                    delete next[name];
+                }
+                else {
+                    next[name] = value;
+                }
+                return next;
+            });
+        }
+        else {
+            setFilters(prev => {
+                const next = { ...prev };
+                if (value === '' || value === undefined) {
+                    delete next[name];
+                }
+                else {
+                    next[name] = value;
+                }
+                return next;
+            });
+        }
+        setCurrentPage(1);
+    };
+    const handleTabClick = (tabKey) => {
+        setActiveTab(tabKey);
+        setCurrentPage(1);
+    };
+    const handleClearFilters = () => {
+        setFilters(initialFilters);
+        setQueryBuilders(initialQueryBuilders);
+        setCurrentPage(1);
+    };
+    const handlePageChange = (page) => {
+        setCurrentPage(page);
+    };
+    const handlePageSizeChange = (size) => {
+        setPerPage(size);
+        setCurrentPage(1);
+    };
+    const queryParams = useMemo(() => {
+        // Merge the active tab's query-builder rules into the request
+        const finalQueryBuilders = { ...queryBuilders };
+        const tabs = schema.tabs;
+        if (activeTab && tabs) {
+            const selectedTab = tabs.find(tab => tab.key === activeTab);
+            if (selectedTab?.queryBuilder && selectedTab.queryBuilder.length > 0) {
+                finalQueryBuilders.__activeTab = selectedTab.queryBuilder;
+            }
+        }
+        return {
+            page: currentPage,
+            perPage,
+            search: searchQuery || undefined,
+            sort: sortColumn,
+            sortDirection,
+            filters,
+            queryBuilders: Object.keys(finalQueryBuilders).length > 0 ? finalQueryBuilders : undefined,
+        };
+    }, [queryBuilders, schema.tabs, activeTab, currentPage, perPage, searchQuery, sortColumn, sortDirection, filters]);
+    return {
+        searchQuery,
+        sortColumn,
+        sortDirection,
+        filters,
+        queryBuilders,
+        activeTab,
+        currentPage,
+        perPage,
+        handleSearch,
+        handleSort,
+        handleFilterChange,
+        handleTabClick,
+        handleClearFilters,
+        handlePageChange,
+        handlePageSizeChange,
+        queryParams,
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,224 @@
+import { SerializedForm, ValidationRules as KratosJsValidationRules } from '@maxal_studio/kratosjs';
+import { ColumnRegistry } from '../contexts/ColumnRegistryContext';
+import { WidgetComponent } from '../contexts/WidgetRegistryContext';
+import type { CustomBlockComponent } from '../contexts/BlockRegistryContext';
+import type { AuthChallengeRegistry } from '../contexts/AuthChallengeRegistryContext';
+import type { ClientI18nConfig } from '../i18n/buildClientI18n';
+import type { ResolvedSlots } from '../slots/types';
+/**
+ * Props passed to all field components
+ */
+export interface FieldProps {
+    type: string;
+    name: string;
+    label?: string;
+    statePath?: string;
+    default?: any;
+    hidden?: boolean;
+    disabled?: boolean;
+    mode?: 'edit' | 'view';
+    value?: any;
+    extraAttributes?: Record<string, any>;
+    validation?: KratosJsValidationRules;
+    helperText?: string;
+    hint?: string;
+    hintIcon?: string;
+    hintColor?: string;
+    autofocus?: boolean;
+    placeholder?: string;
+    readOnly?: boolean;
+    /** When true, view mode displays the value as HTML (TextInput, Textarea, TagsInput) */
+    renderHtml?: boolean;
+    inputType?: string;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    mask?: string;
+    prefix?: string;
+    suffix?: string;
+    options?: Record<string | number, string>;
+    multiple?: boolean;
+    isMultiple?: boolean;
+    searchable?: boolean;
+    creatable?: boolean;
+    relationship?: {
+        name: string;
+        titleAttribute: string;
+        resource?: string;
+    };
+    createOptionForm?: any[];
+    createOptionModalHeading?: string;
+    optionLabelFormatter?: string;
+    tags?: string[];
+    separator?: string;
+    suggestions?: string[];
+    /** When true, view mode shows tags in a popup (e.g. "N tags" click to open) */
+    showInPopup?: boolean;
+    selectablePlaceholder?: boolean;
+    rows?: number;
+    cols?: number;
+    format?: string;
+    displayFormat?: string;
+    minDate?: string;
+    maxDate?: string;
+    enableTime?: boolean;
+    onColor?: string;
+    offColor?: string;
+    onIcon?: string;
+    offIcon?: string;
+    schema?: FieldProps[];
+    defaultItems?: number;
+    minItems?: number;
+    maxItems?: number;
+    addable?: boolean;
+    deletable?: boolean;
+    reorderable?: boolean;
+    itemLabel?: string;
+    acceptedFileTypes?: string[];
+    maxSize?: number;
+    minSize?: number;
+    maxFiles?: number;
+    disk?: string;
+    directory?: string;
+    visibility?: 'public' | 'private';
+    toolbarButtons?: string[];
+    fileAttachments?: boolean;
+    embeds?: boolean;
+    htmlSource?: boolean;
+    extensions?: string[];
+    heading?: string;
+    icon?: string;
+    collapsible?: boolean;
+    collapsed?: boolean;
+    compact?: boolean;
+    aside?: boolean;
+    columns?: number | Record<string, number>;
+    columnSpan?: number | string | Record<string, number | string>;
+    columnStart?: number | Record<string, number>;
+    required?: boolean;
+    /** Operation for conditional visibility (e.g. hidden(context => context.operation === 'view')) */
+    operation?: 'create' | 'edit' | 'view';
+    [key: string]: any;
+}
+/**
+ * Field component type
+ */
+export type FieldComponent = React.ComponentType<FieldProps>;
+/**
+ * Field registry mapping field types to components
+ */
+export type FieldRegistry = Record<string, FieldComponent>;
+/**
+ * Props for FormRenderer component
+ */
+export interface FormRendererProps {
+    schema: SerializedForm;
+    onSubmit: (data: any) => void | Promise<void>;
+    defaultValues?: Record<string, any>;
+    className?: string;
+    /** Base URL for API requests (e.g., 'http://localhost:3001/kratosjs/api') */
+    apiBaseUrl?: string;
+    /** Resource slug for media endpoints (e.g., 'users') */
+    resource?: string;
+    /** Operation type for conditional field visibility (e.g., 'create' | 'edit' | 'view') */
+    operation?: 'create' | 'edit' | 'view';
+    /** Children to render inside FormProvider (for watching form values) */
+    children?: React.ReactNode;
+}
+/**
+ * Props for FieldRenderer component
+ */
+export interface FieldRendererProps {
+    field: FieldProps;
+}
+/**
+ * Validation rules from React Hook Form (converted format)
+ */
+export interface RHFValidationRules {
+    required?: string | {
+        value: boolean;
+        message: string;
+    };
+    pattern?: {
+        value: RegExp;
+        message: string;
+    };
+    minLength?: {
+        value: number;
+        message: string;
+    };
+    maxLength?: {
+        value: number;
+        message: string;
+    };
+    min?: {
+        value: number;
+        message: string;
+    };
+    max?: {
+        value: number;
+        message: string;
+    };
+    validate?: Record<string, (value: any, formValues?: any) => boolean | string>;
+}
+/**
+ * Redirect response from API
+ */
+export interface RedirectResponse {
+    redirect: string;
+    message?: string;
+    [key: string]: any;
+}
+/**
+ * Type guard to check if response is a redirect response
+ */
+export declare function isRedirectResponse(data: any): data is RedirectResponse;
+/**
+ * Relation metadata served by GET /:slug/relations, consumed by the view modal
+ */
+export interface SerializedRelation {
+    name: string;
+    type: 'hasMany';
+    canCreate?: boolean;
+    canEdit?: boolean;
+    canDelete?: boolean;
+    canView?: boolean;
+    resourceSlug: string;
+    /** Full API URL for the related resource */
+    resourceApiUrl?: string;
+    label: string;
+    pluralLabel: string;
+    icon?: string;
+    localKey: string;
+    foreignKey: string;
+    relatedKey: string;
+    groupKey?: string;
+    groupLabel?: string;
+    groupIcon?: string;
+}
+/**
+ * Widget registry mapping widget types to components
+ */
+export type WidgetRegistry = Record<string, WidgetComponent>;
+/**
+ * Block registry mapping custom block types to components
+ */
+export type BlockRegistry = Record<string, CustomBlockComponent>;
+/**
+ * Props for AdminPanel component
+ */
+export interface AdminPanelProps {
+    apiBaseUrl: string;
+    panelId?: string;
+    customFields?: FieldRegistry;
+    customColumns?: ColumnRegistry;
+    customWidgets?: WidgetRegistry;
+    customBlocks?: BlockRegistry;
+    customAuthChallenges?: AuthChallengeRegistry;
+    /** Merged, resolved slot contributions keyed by slot name. */
+    customSlots?: ResolvedSlots;
+    /** i18n config for UI chrome + app frontend strings (server-injected). */
+    i18nConfig?: ClientI18nConfig;
+}

package/dist/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * Type guard to check if response is a redirect response
+ */
+export function isRedirectResponse(data) {
+    return typeof data === 'object' && data !== null && typeof data.redirect === 'string';
+}

package/dist/utils/classNames.d.ts

@@ -0,0 +1,7 @@
+import { ClassValue } from 'clsx';
+/**
+ * Utility function to combine class names
+ * @param classes Class names to combine
+ * @returns Combined class name string
+ */
+export declare function cn(...classes: ClassValue[]): string;

package/dist/utils/classNames.js

@@ -0,0 +1,9 @@
+import clsx from 'clsx';
+/**
+ * Utility function to combine class names
+ * @param classes Class names to combine
+ * @returns Combined class name string
+ */
+export function cn(...classes) {
+    return clsx(classes);
+}

package/dist/utils/columnMediaDimensions.d.ts

@@ -0,0 +1,13 @@
+import type { CSSProperties } from 'react';
+interface ColumnMediaSizeOptions {
+    width?: number | string;
+    height?: number | string;
+    ratio?: string;
+    circular?: boolean;
+}
+/**
+ * Dimensions for image/media/video column thumbnails.
+ * Circular columns always render as a true square (1:1) so rounded-full clips a circle.
+ */
+export declare function getColumnMediaDimensions(column: ColumnMediaSizeOptions, defaultSize?: number | string): CSSProperties;
+export {};

package/dist/utils/columnMediaDimensions.js

@@ -0,0 +1,29 @@
+/**
+ * Dimensions for image/media/video column thumbnails.
+ * Circular columns always render as a true square (1:1) so rounded-full clips a circle.
+ */
+export function getColumnMediaDimensions(column, defaultSize = 40) {
+    if (column.circular) {
+        const raw = column.width ?? column.height ?? defaultSize;
+        const size = typeof raw === 'number' ? `${raw}px` : raw;
+        return {
+            width: size,
+            height: size,
+            minWidth: size,
+            minHeight: size,
+            flexShrink: 0,
+            aspectRatio: '1 / 1',
+        };
+    }
+    const ratio = column.ratio || '16/9';
+    if (column.width) {
+        const w = typeof column.width === 'number' ? `${column.width}px` : column.width;
+        return { width: w, minWidth: w, flexShrink: 0, aspectRatio: ratio };
+    }
+    if (column.height) {
+        const h = typeof column.height === 'number' ? `${column.height}px` : column.height;
+        return { height: h, minHeight: h, flexShrink: 0, aspectRatio: ratio };
+    }
+    const w = typeof defaultSize === 'number' ? `${defaultSize}px` : defaultSize;
+    return { width: w, minWidth: w, flexShrink: 0, aspectRatio: ratio };
+}

package/dist/utils/columnVisibilityStorage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Column visibility storage utilities for managing column visibility preferences in localStorage
+ */
+export declare const columnVisibilityStorage: {
+    /**
+     * Get hidden columns for a resource
+     * @param resourceKey Unique identifier for the resource (e.g., 'users', 'users_posts')
+     * @returns Array of hidden column names, or null if not found (never been set)
+     */
+    getHiddenColumns(resourceKey: string): string[] | null;
+    /**
+     * Set hidden columns for a resource
+     * @param resourceKey Unique identifier for the resource
+     * @param hiddenColumns Array of column names that should be hidden
+     */
+    setHiddenColumns(resourceKey: string, hiddenColumns: string[]): void;
+    /**
+     * Clear stored column visibility preferences for a resource
+     * @param resourceKey Unique identifier for the resource
+     */
+    clearHiddenColumns(resourceKey: string): void;
+};

package/dist/utils/columnVisibilityStorage.js

@@ -0,0 +1,56 @@
+/**
+ * Column visibility storage utilities for managing column visibility preferences in localStorage
+ */
+export const columnVisibilityStorage = {
+    /**
+     * Get hidden columns for a resource
+     * @param resourceKey Unique identifier for the resource (e.g., 'users', 'users_posts')
+     * @returns Array of hidden column names, or null if not found (never been set)
+     */
+    getHiddenColumns(resourceKey) {
+        try {
+            const key = `kratosjs_column_visibility_${resourceKey}`;
+            const stored = localStorage.getItem(key);
+            if (stored === null) {
+                return null;
+            }
+            const parsed = JSON.parse(stored);
+            if (Array.isArray(parsed)) {
+                return parsed;
+            }
+            return null;
+        }
+        catch (error) {
+            console.warn('Failed to parse column visibility from localStorage:', error);
+            return null;
+        }
+    },
+    /**
+     * Set hidden columns for a resource
+     * @param resourceKey Unique identifier for the resource
+     * @param hiddenColumns Array of column names that should be hidden
+     */
+    setHiddenColumns(resourceKey, hiddenColumns) {
+        try {
+            const key = `kratosjs_column_visibility_${resourceKey}`;
+            localStorage.setItem(key, JSON.stringify(hiddenColumns));
+        }
+        catch (error) {
+            // Handle quota exceeded or other localStorage errors
+            if (error instanceof Error && error.name === 'QuotaExceededError') {
+                console.warn('localStorage quota exceeded, column visibility preferences not saved');
+            }
+            else {
+                console.warn('Failed to save column visibility to localStorage:', error);
+            }
+        }
+    },
+    /**
+     * Clear stored column visibility preferences for a resource
+     * @param resourceKey Unique identifier for the resource
+     */
+    clearHiddenColumns(resourceKey) {
+        const key = `kratosjs_column_visibility_${resourceKey}`;
+        localStorage.removeItem(key);
+    },
+};

package/dist/utils/fieldErrors.d.ts

@@ -0,0 +1,13 @@
+import type { FieldErrors, FieldError } from 'react-hook-form';
+/**
+ * Resolve a React Hook Form error by its (possibly nested) field-name path.
+ *
+ * RHF stores errors for nested / array fields as nested objects — e.g. a field
+ * registered as `items.0.name` lives at `errors.items[0].name`, NOT at the flat
+ * key `errors['items.0.name']`. Field components therefore can't find the error
+ * for a Repeater row (or any dotted name) with a plain `errors[name]` lookup.
+ *
+ * This walks the dot/bracket path so both flat names (`email`) and nested ones
+ * (`items.0.name`, `items[0].name`) resolve correctly.
+ */
+export declare function getFieldError(errors: FieldErrors | undefined, name: string | undefined): FieldError | undefined;

package/dist/utils/fieldErrors.js

@@ -0,0 +1,25 @@
+/**
+ * Resolve a React Hook Form error by its (possibly nested) field-name path.
+ *
+ * RHF stores errors for nested / array fields as nested objects — e.g. a field
+ * registered as `items.0.name` lives at `errors.items[0].name`, NOT at the flat
+ * key `errors['items.0.name']`. Field components therefore can't find the error
+ * for a Repeater row (or any dotted name) with a plain `errors[name]` lookup.
+ *
+ * This walks the dot/bracket path so both flat names (`email`) and nested ones
+ * (`items.0.name`, `items[0].name`) resolve correctly.
+ */
+export function getFieldError(errors, name) {
+    if (!errors || !name)
+        return undefined;
+    const segments = name.split(/[.[\]]+/).filter(Boolean);
+    let current = errors;
+    for (const segment of segments) {
+        if (current == null)
+            return undefined;
+        current = current[segment];
+    }
+    // A resolved node is an error only when it carries a `type`/`message`; nested
+    // containers (e.g. the array node `errors.items`) are not field errors.
+    return current && (current.type || current.message) ? current : undefined;
+}

package/dist/utils/formatValue.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+/**
+ * Utility functions for formatting field values in view mode
+ */
+/**
+ * Format a date value according to the specified format
+ */
+export declare function formatDate(value: any, format?: string): string;
+/**
+ * Format a number value with optional options
+ */
+export declare function formatNumber(value: any, options?: {
+    decimals?: number;
+    currency?: string;
+}): string;
+/**
+ * Format a boolean value
+ */
+export declare function formatBoolean(value: any): string;
+/**
+ * Format a select value to display option labels
+ */
+export declare function formatSelectLabel(value: any, options?: Record<string | number, string>, isMultiple?: boolean): string;
+/**
+ * Format a textarea value preserving line breaks
+ * Returns an array of React elements for rendering
+ */
+export declare function formatTextarea(value: any): React.ReactNode;

package/dist/utils/formatValue.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { getActiveLocale, translate } from '../i18n/activeLocale';
+/**
+ * Utility functions for formatting field values in view mode
+ */
+/**
+ * Format a date value according to the specified format
+ */
+export function formatDate(value, format) {
+    if (!value)
+        return '-';
+    try {
+        const date = new Date(value);
+        if (isNaN(date.getTime()))
+            return String(value);
+        if (format) {
+            // Simple format support - can be extended
+            const year = date.getFullYear();
+            const month = String(date.getMonth() + 1).padStart(2, '0');
+            const day = String(date.getDate()).padStart(2, '0');
+            const hours = String(date.getHours()).padStart(2, '0');
+            const minutes = String(date.getMinutes()).padStart(2, '0');
+            const seconds = String(date.getSeconds()).padStart(2, '0');
+            return format
+                .replace('YYYY', String(year))
+                .replace('MM', month)
+                .replace('DD', day)
+                .replace('HH', hours)
+                .replace('mm', minutes)
+                .replace('ss', seconds);
+        }
+        return date.toLocaleString(getActiveLocale());
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Format a number value with optional options
+ */
+export function formatNumber(value, options) {
+    if (value === null || value === undefined)
+        return '-';
+    const num = Number(value);
+    if (isNaN(num))
+        return String(value);
+    if (options?.currency) {
+        return new Intl.NumberFormat(getActiveLocale(), {
+            style: 'currency',
+            currency: options.currency,
+            minimumFractionDigits: options.decimals ?? 2,
+            maximumFractionDigits: options.decimals ?? 2,
+        }).format(num);
+    }
+    if (options?.decimals !== undefined) {
+        return num.toFixed(options.decimals);
+    }
+    return num.toLocaleString(getActiveLocale());
+}
+/**
+ * Format a boolean value
+ */
+export function formatBoolean(value) {
+    if (value === null || value === undefined)
+        return '-';
+    return value ? translate('core:common.yes') : translate('core:common.no');
+}
+/**
+ * Format a select value to display option labels
+ */
+export function formatSelectLabel(value, options, isMultiple) {
+    if (!value)
+        return '-';
+    if (isMultiple && Array.isArray(value)) {
+        if (value.length === 0)
+            return '-';
+        if (!options)
+            return value.join(', ');
+        return value
+            .map(v => {
+            const key = String(v);
+            return options[key] || key;
+        })
+            .join(', ');
+    }
+    if (!options)
+        return String(value);
+    const key = String(value);
+    return options[key] || key;
+}
+/**
+ * Format a textarea value preserving line breaks
+ * Returns an array of React elements for rendering
+ */
+export function formatTextarea(value) {
+    if (value === null || value === undefined)
+        return '-';
+    // If is js object, return json string
+    let text = value;
+    if (typeof value === 'object') {
+        text = JSON.stringify(value, null, 2);
+    }
+    else {
+        text = String(value);
+    }
+    const lines = text.split('\n');
+    return lines.map((line, i) => (_jsxs(React.Fragment, { children: [line, i < lines.length - 1 && _jsx("br", {})] }, i)));
+}