@maxal_studio/kratosjs-react 1.0.0

package/src/components/widgets/WidgetShell.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import { Icon } from '../utils/Icon';
+import { cn } from '../../utils/classNames';
+
+export interface WidgetShellProps {
+	label?: string;
+	icon?: string;
+	className?: string;
+	children: React.ReactNode;
+}
+
+/** Shared card shell for dashboard/table widgets. */
+export function WidgetShell({ label, icon, className, children }: WidgetShellProps) {
+	return (
+		<div
+			className={cn(
+				'flex min-h-[8.5rem] flex-col rounded-xl border border-border bg-surface p-4 transition-colors hover:bg-hover/20',
+				className,
+			)}>
+			{(label || icon) && (
+				<div className="mb-3 flex items-start justify-between gap-2">
+					{label ? (
+						<p className="text-[11px] font-medium uppercase tracking-wider text-fg-muted">{label}</p>
+					) : (
+						<span />
+					)}
+					{icon && (
+						<div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-raised text-fg-secondary shadow-soft-sm">
+							<Icon name={icon} className="h-4 w-4" />
+						</div>
+					)}
+				</div>
+			)}
+			<div className="flex min-h-0 flex-1 flex-col">{children}</div>
+		</div>
+	);
+}

package/src/contexts/AuthChallengeRegistryContext.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { AuthChallengeComponent } from '../auth/types';
+import { createRegistryContext } from './createRegistryContext';
+
+export type AuthChallengeRegistry = Record<string, AuthChallengeComponent>;
+
+// No built-in challenge UIs: challenge components are entirely plugin-provided
+// (e.g. the 2FA plugin registers a '2fa-totp' component).
+const registry = createRegistryContext<AuthChallengeComponent>('AuthChallengeRegistry', {});
+
+export const AuthChallengeRegistryContext = registry.Context;
+export const useAuthChallengeRegistry = registry.useRegistry;
+
+export interface AuthChallengeRegistryProviderProps {
+	customAuthChallenges?: AuthChallengeRegistry;
+	children: React.ReactNode;
+}
+
+/**
+ * Provider for challenge UI components keyed by challenge `type`. Lives above the auth gate
+ * so the LoginPage (rendered when there is no user) can look up the component for a pending
+ * challenge.
+ */
+export function AuthChallengeRegistryProvider({
+	customAuthChallenges = {},
+	children,
+}: AuthChallengeRegistryProviderProps) {
+	return <registry.Provider registry={customAuthChallenges}>{children}</registry.Provider>;
+}

package/src/contexts/BlockRegistryContext.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { createRegistryContext } from './createRegistryContext';
+
+export interface CustomBlockComponentProps {
+	block: any;
+	blockData?: Record<string, any>;
+	apiBaseUrl?: string;
+}
+
+export type CustomBlockComponent = React.ComponentType<CustomBlockComponentProps>;
+
+export interface BlockRegistry {
+	[key: string]: CustomBlockComponent;
+}
+
+const registry = createRegistryContext<CustomBlockComponent>('BlockRegistry', {});
+
+interface BlockRegistryProviderProps {
+	children: React.ReactNode;
+	customBlocks?: BlockRegistry;
+}
+
+export function BlockRegistryProvider({ children, customBlocks }: BlockRegistryProviderProps) {
+	return <registry.Provider registry={customBlocks}>{children}</registry.Provider>;
+}
+
+/** Returns the flat block registry (custom page blocks keyed by type). */
+export const useBlockRegistry = registry.useRegistry;

package/src/contexts/ColumnRegistryContext.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+import { createRegistryContext } from './createRegistryContext';
+import { TextColumnComponent } from '../components/columns/TextColumnComponent';
+import { IconColumnComponent } from '../components/columns/IconColumnComponent';
+import { ImageColumnComponent } from '../components/columns/ImageColumnComponent';
+import { VideoColumnComponent } from '../components/columns/VideoColumnComponent';
+import { MediaColumnComponent } from '../components/columns/MediaColumnComponent';
+import { ColorColumnComponent } from '../components/columns/ColorColumnComponent';
+import { TagsColumnComponent } from '../components/columns/TagsColumnComponent';
+import { ViewColumnComponent } from '../components/columns/ViewColumnComponent';
+import { CheckboxColumnComponent } from '../components/columns/CheckboxColumnComponent';
+import { ToggleColumnComponent } from '../components/columns/ToggleColumnComponent';
+import { SelectColumnComponent } from '../components/columns/SelectColumnComponent';
+import { TextInputColumnComponent } from '../components/columns/TextInputColumnComponent';
+
+export type ColumnComponent = React.ComponentType<any>;
+
+export type ColumnRegistry = Record<string, ColumnComponent>;
+
+const defaultColumns: ColumnRegistry = {
+	text: TextColumnComponent,
+	icon: IconColumnComponent,
+	image: ImageColumnComponent,
+	video: VideoColumnComponent,
+	media: MediaColumnComponent,
+	color: ColorColumnComponent,
+	tags: TagsColumnComponent,
+	view: ViewColumnComponent,
+	checkbox: CheckboxColumnComponent,
+	toggle: ToggleColumnComponent,
+	select: SelectColumnComponent,
+	textinput: TextInputColumnComponent,
+};
+
+const registry = createRegistryContext<ColumnComponent>('ColumnRegistry', defaultColumns);
+
+export const ColumnRegistryProvider = registry.Provider;
+export const useColumnRegistry = registry.useRegistry;

package/src/contexts/FieldRegistryContext.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { FieldRegistry } from '../types';
+import { createRegistryContext } from './createRegistryContext';
+import { TextInputField } from '../components/TextInputField';
+import { SelectField } from '../components/SelectField';
+import { TextareaField } from '../components/TextareaField';
+import { CheckboxField } from '../components/CheckboxField';
+import { ToggleField } from '../components/ToggleField';
+import { RadioField } from '../components/RadioField';
+import { DateTimePickerField } from '../components/DateTimePickerField';
+import { ColorPickerField } from '../components/ColorPickerField';
+import { RepeaterField } from '../components/RepeaterField';
+import { TagsInputField } from '../components/TagsInputField';
+import { HiddenField } from '../components/HiddenField';
+import { FileUploadField } from '../components/FileUploadField';
+import { RichEditorField } from '../components/RichEditorField';
+import { SectionField } from '../components/SectionField';
+import { GroupField } from '../components/GroupField';
+import { TabsField } from '../components/TabsField';
+
+const defaultFields: FieldRegistry = {
+	'text-input': TextInputField,
+	select: SelectField,
+	textarea: TextareaField,
+	checkbox: CheckboxField,
+	toggle: ToggleField,
+	radio: RadioField,
+	'date-time-picker': DateTimePickerField,
+	'color-picker': ColorPickerField,
+	repeater: RepeaterField,
+	'tags-input': TagsInputField,
+	hidden: HiddenField,
+	fileUpload: FileUploadField,
+	richEditor: RichEditorField,
+	section: SectionField,
+	group: GroupField,
+	tabs: TabsField,
+};
+
+const registry = createRegistryContext('FieldRegistry', defaultFields);
+
+export const FieldRegistryContext = registry.Context;
+export const useFieldRegistry = registry.useRegistry;
+
+export interface FieldRegistryProviderProps {
+	customFields?: FieldRegistry;
+	children: React.ReactNode;
+}
+
+/**
+ * Provider component that manages the field registry.
+ * Custom field components (e.g. from plugins) override the built-ins.
+ */
+export function FieldRegistryProvider({ customFields = {}, children }: FieldRegistryProviderProps) {
+	return <registry.Provider registry={customFields}>{children}</registry.Provider>;
+}

package/src/contexts/PanelMetadataContext.tsx

@@ -0,0 +1,60 @@
+import React, { createContext, useContext, ReactNode } from 'react';
+import type { ResourceMetadata } from '../components/layout/Sidebar';
+
+export interface PageMetadata {
+	slug: string;
+	label: string;
+	icon?: string;
+	navigationGroup?: string;
+	navigationSort?: number;
+	hidden?: boolean;
+	badge?: string | number | null;
+	badgeColor?: string;
+}
+
+interface PanelMetadataContextType {
+	resources: ResourceMetadata[];
+	pages: PageMetadata[];
+	getResourceLabel: (slug: string) => string | undefined;
+	getPageLabel: (slug: string) => string | undefined;
+}
+
+const PanelMetadataContext = createContext<PanelMetadataContextType | undefined>(undefined);
+
+export interface PanelMetadataProviderProps {
+	children: ReactNode;
+	resources: ResourceMetadata[];
+	pages: PageMetadata[];
+}
+
+export function PanelMetadataProvider({ children, resources, pages }: PanelMetadataProviderProps) {
+	const getResourceLabel = (slug: string): string | undefined => {
+		const resource = resources.find(r => r.slug === slug);
+		return resource?.label;
+	};
+
+	const getPageLabel = (slug: string): string | undefined => {
+		const page = pages.find(p => p.slug === slug);
+		return page?.label;
+	};
+
+	return (
+		<PanelMetadataContext.Provider
+			value={{
+				resources,
+				pages,
+				getResourceLabel,
+				getPageLabel,
+			}}>
+			{children}
+		</PanelMetadataContext.Provider>
+	);
+}
+
+export function usePanelMetadata() {
+	const context = useContext(PanelMetadataContext);
+	if (!context) {
+		throw new Error('usePanelMetadata must be used within PanelMetadataProvider');
+	}
+	return context;
+}

package/src/contexts/PanelProviders.tsx

@@ -0,0 +1,85 @@
+import React from 'react';
+import { AuthProvider } from '../auth/AuthContext';
+import { ProtectedRoute } from '../auth/ProtectedRoute';
+import { ResourceModalProvider } from './ResourceModalContext';
+import { TableRefreshProvider } from './TableRefreshContext';
+import { BlockRegistryProvider, BlockRegistry } from './BlockRegistryContext';
+import { WidgetRegistryProvider, WidgetRegistry } from './WidgetRegistryContext';
+import { FieldRegistryProvider } from './FieldRegistryContext';
+import { ColumnRegistryProvider, ColumnRegistry } from './ColumnRegistryContext';
+import { AuthChallengeRegistryProvider, AuthChallengeRegistry } from './AuthChallengeRegistryContext';
+import { SlotRegistryProvider } from './SlotRegistryContext';
+import type { ResolvedSlots } from '../slots/types';
+import { ToastProvider } from '../components/ui/Toast';
+import { ConfirmProvider } from '../components/ui/ConfirmDialog';
+import { I18nProvider } from '../i18n/I18nProvider';
+import type { ClientI18nConfig } from '../i18n/buildClientI18n';
+import { FieldRegistry } from '../types';
+
+export interface PanelProvidersProps {
+	apiBaseUrl: string;
+	customFields?: FieldRegistry;
+	customColumns?: ColumnRegistry;
+	customWidgets?: WidgetRegistry;
+	customBlocks?: BlockRegistry;
+	customAuthChallenges?: AuthChallengeRegistry;
+	customSlots?: ResolvedSlots;
+	i18nConfig?: ClientI18nConfig;
+	children: React.ReactNode;
+}
+
+/**
+ * Composes the auth gate and every panel-level provider (modal stack,
+ * table refresh, and the component registries) in one place.
+ *
+ * The auth-challenge registry wraps the auth gate so the LoginPage — rendered by
+ * ProtectedRoute when there is no user — can resolve the component for a pending challenge.
+ */
+export function PanelProviders({
+	apiBaseUrl,
+	customFields,
+	customColumns,
+	customWidgets,
+	customBlocks,
+	customAuthChallenges,
+	customSlots,
+	i18nConfig,
+	children,
+}: PanelProvidersProps) {
+	return (
+		<I18nProvider config={i18nConfig}>
+			<ToastProvider>
+				<ConfirmProvider>
+					<AuthProvider apiBaseUrl={apiBaseUrl}>
+						<AuthChallengeRegistryProvider customAuthChallenges={customAuthChallenges}>
+							{/*
+							 * SlotRegistryProvider wraps ProtectedRoute so the LoginPage —
+							 * rendered as ProtectedRoute's unauthenticated fallback — can
+							 * resolve the `login.belowForm` slot. It only supplies the slot
+							 * map; contributions render at their <Slot> call site and inherit
+							 * whatever providers sit above that location.
+							 */}
+							<SlotRegistryProvider slots={customSlots}>
+								<ProtectedRoute apiBaseUrl={apiBaseUrl}>
+									<ResourceModalProvider>
+										<TableRefreshProvider>
+											<BlockRegistryProvider customBlocks={customBlocks}>
+												<WidgetRegistryProvider customWidgets={customWidgets}>
+													<FieldRegistryProvider customFields={customFields}>
+														<ColumnRegistryProvider registry={customColumns}>
+															{children}
+														</ColumnRegistryProvider>
+													</FieldRegistryProvider>
+												</WidgetRegistryProvider>
+											</BlockRegistryProvider>
+										</TableRefreshProvider>
+									</ResourceModalProvider>
+								</ProtectedRoute>
+							</SlotRegistryProvider>
+						</AuthChallengeRegistryProvider>
+					</AuthProvider>
+				</ConfirmProvider>
+			</ToastProvider>
+		</I18nProvider>
+	);
+}

package/src/contexts/ResourceModalContext.tsx

@@ -0,0 +1,137 @@
+import React, { createContext, useContext, useState, useCallback, ReactNode } from 'react';
+
+export interface ModalState {
+	resource: string;
+	recordId?: string; // Optional for create mode
+	mode: 'view' | 'edit' | 'create' | 'action';
+	depth: number;
+	// For action modals
+	actionName?: string;
+	actionLabel?: string;
+	// Set by cross-resource deeplinks: the URL that was active before pushState was
+	// called to show this modal's URL.  Used to restore the URL on close without
+	// touching React Router's internal location.
+	originUrl?: string;
+}
+
+interface ResourceModalContextType {
+	modalStack: ModalState[];
+	modalTitles: Record<string, string>;
+	openModal: (
+		resource: string,
+		mode: 'view' | 'edit' | 'create' | 'action',
+		recordId?: string,
+		actionName?: string,
+		actionLabel?: string,
+		originUrl?: string,
+	) => void;
+	closeModal: () => void; // Closes top modal (pop from stack)
+	closeAllModals: () => void;
+	clearModalsForResource: (resource: string) => void; // Clear modals for specific resource when navigating away
+	setModalTitle: (key: string, title: string) => void;
+	removeModalTitle: (key: string) => void;
+	clearModalTitles: () => void;
+}
+
+const ResourceModalContext = createContext<ResourceModalContextType | undefined>(undefined);
+
+export function ResourceModalProvider({ children }: { children: ReactNode }) {
+	const [modalStack, setModalStack] = useState<ModalState[]>([]);
+	const [modalTitles, setModalTitles] = useState<Record<string, string>>({});
+
+	const openModal = useCallback(
+		(
+			resource: string,
+			mode: 'view' | 'edit' | 'create' | 'action',
+			recordId?: string,
+			actionName?: string,
+			actionLabel?: string,
+			originUrl?: string,
+		) => {
+			setModalStack(prev => {
+				// Check if this exact modal is already at the top of the stack (prevent duplicates)
+				const topModal = prev[prev.length - 1];
+				if (
+					topModal &&
+					topModal.resource === resource &&
+					topModal.recordId === recordId &&
+					topModal.mode === mode &&
+					topModal.actionName === actionName
+				) {
+					// Same modal already at top, don't add duplicate
+					return prev;
+				}
+
+				// Add new modal to stack with auto-calculated depth
+				const newModal: ModalState = {
+					resource,
+					recordId,
+					mode,
+					depth: prev.length, // depth = current stack length
+					actionName,
+					actionLabel,
+					originUrl,
+				};
+
+				return [...prev, newModal];
+			});
+		},
+		[],
+	);
+
+	const closeModal = useCallback(() => {
+		setModalStack(prev => {
+			if (prev.length === 0) return prev;
+			// Remove last modal from stack (pop)
+			return prev.slice(0, -1);
+		});
+	}, []);
+
+	const closeAllModals = useCallback(() => {
+		setModalStack([]);
+	}, []);
+
+	const clearModalsForResource = useCallback((resource: string) => {
+		setModalStack(prev => prev.filter(modal => modal.resource !== resource));
+	}, []);
+
+	const setModalTitle = useCallback((key: string, title: string) => {
+		setModalTitles(prev => ({ ...prev, [key]: title }));
+	}, []);
+
+	const removeModalTitle = useCallback((key: string) => {
+		setModalTitles(prev => {
+			const { [key]: _, ...rest } = prev;
+			return rest;
+		});
+	}, []);
+
+	const clearModalTitles = useCallback(() => {
+		setModalTitles({});
+	}, []);
+
+	return (
+		<ResourceModalContext.Provider
+			value={{
+				modalStack,
+				modalTitles,
+				openModal,
+				closeModal,
+				closeAllModals,
+				clearModalsForResource,
+				setModalTitle,
+				removeModalTitle,
+				clearModalTitles,
+			}}>
+			{children}
+		</ResourceModalContext.Provider>
+	);
+}
+
+export function useResourceModal() {
+	const context = useContext(ResourceModalContext);
+	if (!context) {
+		throw new Error('useResourceModal must be used within ResourceModalProvider');
+	}
+	return context;
+}

package/src/contexts/SlotRegistryContext.tsx

@@ -0,0 +1,35 @@
+import React, { createContext, useContext, useMemo } from 'react';
+import type { SlotContribution, ResolvedSlots, SlotName } from '../slots/types';
+import { sortSlots } from '../slots/mergeSlots';
+
+const SlotRegistryContext = createContext<ResolvedSlots>({});
+SlotRegistryContext.displayName = 'SlotRegistry';
+
+export interface SlotRegistryProviderProps {
+	/** Resolved slot map (already merged across plugins + app). */
+	slots?: ResolvedSlots;
+	children: React.ReactNode;
+}
+
+/**
+ * Provides the merged slot map to the tree. Slots differ from the component
+ * registries (`createRegistryContext`): they are 1:many and concatenated rather
+ * than overridden, so this provider keeps a sorted array per slot name.
+ */
+export function SlotRegistryProvider({ slots = {}, children }: SlotRegistryProviderProps) {
+	const value = useMemo(() => sortSlots({ ...slots }), [slots]);
+	return <SlotRegistryContext.Provider value={value}>{children}</SlotRegistryContext.Provider>;
+}
+
+/** Full resolved slot map (for introspection/tests). */
+export function useSlotRegistry(): ResolvedSlots {
+	return useContext(SlotRegistryContext);
+}
+
+/** The sorted contributions for a single slot, or an empty array. */
+export function useSlot(name: SlotName): SlotContribution[] {
+	const registry = useContext(SlotRegistryContext);
+	return registry[name] ?? [];
+}
+
+export { SlotRegistryContext };

package/src/contexts/TableRefreshContext.tsx

@@ -0,0 +1,44 @@
+import React, { createContext, useContext, useCallback, ReactNode } from 'react';
+
+interface TableRefreshContextType {
+	refreshTable: (resourceSlug: string) => void;
+	registerRefresh: (resourceSlug: string, callback: () => void) => () => void;
+}
+
+const TableRefreshContext = createContext<TableRefreshContextType | undefined>(undefined);
+
+export function TableRefreshProvider({ children }: { children: ReactNode }) {
+	const refreshCallbacks = React.useRef<Map<string, () => void>>(new Map());
+
+	const refreshTable = useCallback((resourceSlug: string) => {
+		const callback = refreshCallbacks.current.get(resourceSlug);
+		if (callback) {
+			callback();
+		}
+	}, []);
+
+	const registerRefresh = useCallback((resourceSlug: string, callback: () => void) => {
+		refreshCallbacks.current.set(resourceSlug, callback);
+		return () => {
+			refreshCallbacks.current.delete(resourceSlug);
+		};
+	}, []);
+
+	return (
+		<TableRefreshContext.Provider value={{ refreshTable, registerRefresh }}>
+			{children}
+		</TableRefreshContext.Provider>
+	);
+}
+
+export function useTableRefresh() {
+	const context = useContext(TableRefreshContext);
+	if (!context) {
+		// Return no-op functions if context is not available
+		return {
+			refreshTable: () => {},
+			registerRefresh: () => () => {},
+		};
+	}
+	return context;
+}

package/src/contexts/WidgetRegistryContext.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import { createRegistryContext } from './createRegistryContext';
+import { StatsWidget } from '../components/widgets/StatsWidget';
+import { ChartWidget } from '../components/widgets/ChartWidget';
+
+export interface WidgetComponentProps {
+	widget: any;
+	data: any;
+}
+
+export type WidgetComponent = React.ComponentType<WidgetComponentProps>;
+
+export interface WidgetRegistry {
+	[key: string]: WidgetComponent;
+}
+
+const builtInWidgets: WidgetRegistry = {
+	stats: StatsWidget,
+	chart: ChartWidget,
+};
+
+const registry = createRegistryContext<WidgetComponent>('WidgetRegistry', builtInWidgets);
+
+interface WidgetRegistryProviderProps {
+	children: React.ReactNode;
+	customWidgets?: WidgetRegistry;
+}
+
+export function WidgetRegistryProvider({ children, customWidgets }: WidgetRegistryProviderProps) {
+	return <registry.Provider registry={customWidgets}>{children}</registry.Provider>;
+}
+
+/** Returns the flat widget registry (built-ins merged with custom widgets). */
+export const useWidgetRegistry = registry.useRegistry;

package/src/contexts/createRegistryContext.tsx

@@ -0,0 +1,29 @@
+import React, { createContext, useContext, useMemo } from 'react';
+
+export interface RegistryProviderProps<T> {
+	/** Custom entries; merged over the defaults, custom entries win */
+	registry?: Record<string, T>;
+	children: React.ReactNode;
+}
+
+/**
+ * Factory for component registries (fields, columns, widgets, blocks).
+ * All registries share one pattern: a flat `Record<string, Component>` of
+ * defaults that custom (plugin) entries can extend or override.
+ */
+export function createRegistryContext<T>(displayName: string, defaults: Record<string, T>) {
+	const Context = createContext<Record<string, T>>(defaults);
+	Context.displayName = displayName;
+
+	function Provider({ registry = {}, children }: RegistryProviderProps<T>) {
+		const merged = useMemo(() => ({ ...defaults, ...registry }), [registry]);
+		return <Context.Provider value={merged}>{children}</Context.Provider>;
+	}
+	Provider.displayName = `${displayName}Provider`;
+
+	function useRegistry(): Record<string, T> {
+		return useContext(Context);
+	}
+
+	return { Context, Provider, useRegistry };
+}