@maxal_studio/kratosjs-react 1.0.0

package/src/components/utils/layoutHelpers.ts

@@ -0,0 +1,267 @@
+/**
+ * Layout helper utilities for column span, column start, and grid classes.
+ *
+ * IMPORTANT: every Tailwind class must appear as a full literal string here.
+ * Tailwind v4 only generates utilities it can see while scanning the source —
+ * template-built class names (`grid-cols-${n}`) silently produce no CSS.
+ */
+
+const GRID_COLS: Record<string, Record<number, string>> = {
+	base: {
+		1: 'grid-cols-1',
+		2: 'grid-cols-2',
+		3: 'grid-cols-3',
+		4: 'grid-cols-4',
+		5: 'grid-cols-5',
+		6: 'grid-cols-6',
+	},
+	sm: {
+		1: 'sm:grid-cols-1',
+		2: 'sm:grid-cols-2',
+		3: 'sm:grid-cols-3',
+		4: 'sm:grid-cols-4',
+		5: 'sm:grid-cols-5',
+		6: 'sm:grid-cols-6',
+	},
+	md: {
+		1: 'md:grid-cols-1',
+		2: 'md:grid-cols-2',
+		3: 'md:grid-cols-3',
+		4: 'md:grid-cols-4',
+		5: 'md:grid-cols-5',
+		6: 'md:grid-cols-6',
+	},
+	lg: {
+		1: 'lg:grid-cols-1',
+		2: 'lg:grid-cols-2',
+		3: 'lg:grid-cols-3',
+		4: 'lg:grid-cols-4',
+		5: 'lg:grid-cols-5',
+		6: 'lg:grid-cols-6',
+	},
+	xl: {
+		1: 'xl:grid-cols-1',
+		2: 'xl:grid-cols-2',
+		3: 'xl:grid-cols-3',
+		4: 'xl:grid-cols-4',
+		5: 'xl:grid-cols-5',
+		6: 'xl:grid-cols-6',
+	},
+	'2xl': {
+		1: '2xl:grid-cols-1',
+		2: '2xl:grid-cols-2',
+		3: '2xl:grid-cols-3',
+		4: '2xl:grid-cols-4',
+		5: '2xl:grid-cols-5',
+		6: '2xl:grid-cols-6',
+	},
+};
+
+const COL_SPAN: Record<string, Record<number | 'full', string>> = {
+	base: {
+		1: 'col-span-1',
+		2: 'col-span-2',
+		3: 'col-span-3',
+		4: 'col-span-4',
+		5: 'col-span-5',
+		6: 'col-span-6',
+		full: 'col-span-full',
+	},
+	sm: {
+		1: 'sm:col-span-1',
+		2: 'sm:col-span-2',
+		3: 'sm:col-span-3',
+		4: 'sm:col-span-4',
+		5: 'sm:col-span-5',
+		6: 'sm:col-span-6',
+		full: 'sm:col-span-full',
+	},
+	md: {
+		1: 'md:col-span-1',
+		2: 'md:col-span-2',
+		3: 'md:col-span-3',
+		4: 'md:col-span-4',
+		5: 'md:col-span-5',
+		6: 'md:col-span-6',
+		full: 'md:col-span-full',
+	},
+	lg: {
+		1: 'lg:col-span-1',
+		2: 'lg:col-span-2',
+		3: 'lg:col-span-3',
+		4: 'lg:col-span-4',
+		5: 'lg:col-span-5',
+		6: 'lg:col-span-6',
+		full: 'lg:col-span-full',
+	},
+	xl: {
+		1: 'xl:col-span-1',
+		2: 'xl:col-span-2',
+		3: 'xl:col-span-3',
+		4: 'xl:col-span-4',
+		5: 'xl:col-span-5',
+		6: 'xl:col-span-6',
+		full: 'xl:col-span-full',
+	},
+	'2xl': {
+		1: '2xl:col-span-1',
+		2: '2xl:col-span-2',
+		3: '2xl:col-span-3',
+		4: '2xl:col-span-4',
+		5: '2xl:col-span-5',
+		6: '2xl:col-span-6',
+		full: '2xl:col-span-full',
+	},
+};
+
+const COL_START: Record<string, Record<number, string>> = {
+	base: {
+		1: 'col-start-1',
+		2: 'col-start-2',
+		3: 'col-start-3',
+		4: 'col-start-4',
+		5: 'col-start-5',
+		6: 'col-start-6',
+		7: 'col-start-7',
+	},
+	sm: {
+		1: 'sm:col-start-1',
+		2: 'sm:col-start-2',
+		3: 'sm:col-start-3',
+		4: 'sm:col-start-4',
+		5: 'sm:col-start-5',
+		6: 'sm:col-start-6',
+		7: 'sm:col-start-7',
+	},
+	md: {
+		1: 'md:col-start-1',
+		2: 'md:col-start-2',
+		3: 'md:col-start-3',
+		4: 'md:col-start-4',
+		5: 'md:col-start-5',
+		6: 'md:col-start-6',
+		7: 'md:col-start-7',
+	},
+	lg: {
+		1: 'lg:col-start-1',
+		2: 'lg:col-start-2',
+		3: 'lg:col-start-3',
+		4: 'lg:col-start-4',
+		5: 'lg:col-start-5',
+		6: 'lg:col-start-6',
+		7: 'lg:col-start-7',
+	},
+	xl: {
+		1: 'xl:col-start-1',
+		2: 'xl:col-start-2',
+		3: 'xl:col-start-3',
+		4: 'xl:col-start-4',
+		5: 'xl:col-start-5',
+		6: 'xl:col-start-6',
+		7: 'xl:col-start-7',
+	},
+	'2xl': {
+		1: '2xl:col-start-1',
+		2: '2xl:col-start-2',
+		3: '2xl:col-start-3',
+		4: '2xl:col-start-4',
+		5: '2xl:col-start-5',
+		6: '2xl:col-start-6',
+		7: '2xl:col-start-7',
+	},
+};
+
+const BREAKPOINTS = ['sm', 'md', 'lg', 'xl', '2xl'] as const;
+
+function spanClass(breakpoint: string, value: number | string): string | undefined {
+	const key = value === 'full' ? 'full' : Number(value);
+	return COL_SPAN[breakpoint]?.[key as number | 'full'];
+}
+
+/**
+ * Get Tailwind CSS classes for column span and column start.
+ * Supports both simple values and responsive objects.
+ */
+export function getColumnClasses(
+	columnSpan?: number | string | Record<string, number | string>,
+	columnStart?: number | Record<string, number>,
+): string {
+	const classes: string[] = [];
+
+	if (columnSpan) {
+		if (typeof columnSpan === 'number' || typeof columnSpan === 'string') {
+			const cls = spanClass('base', columnSpan);
+			if (cls) classes.push(cls);
+		} else if (typeof columnSpan === 'object') {
+			const span = columnSpan as Record<string, number | string>;
+			if (span.default) {
+				const cls = spanClass('base', span.default);
+				if (cls) classes.push(cls);
+			}
+			for (const bp of BREAKPOINTS) {
+				if (span[bp]) {
+					const cls = spanClass(bp, span[bp]);
+					if (cls) classes.push(cls);
+				}
+			}
+		}
+	}
+
+	if (columnStart) {
+		if (typeof columnStart === 'number') {
+			const cls = COL_START.base[columnStart];
+			if (cls) classes.push(cls);
+		} else if (typeof columnStart === 'object') {
+			const start = columnStart as Record<string, number>;
+			if (start.default) {
+				const cls = COL_START.base[start.default];
+				if (cls) classes.push(cls);
+			}
+			for (const bp of BREAKPOINTS) {
+				if (start[bp]) {
+					const cls = COL_START[bp]?.[start[bp]];
+					if (cls) classes.push(cls);
+				}
+			}
+		}
+	}
+
+	return classes.join(' ');
+}
+
+/**
+ * Get Tailwind CSS grid classes based on columns configuration.
+ * Supports both simple numbers (applied from lg up) and responsive objects.
+ */
+export function getGridClasses(columns?: number | Record<string, number>, gapX: string = 'gap-x-4'): string {
+	if (!columns || columns === 1) {
+		return `grid grid-cols-1 ${gapX}`;
+	}
+
+	if (typeof columns === 'number') {
+		const cls = GRID_COLS.lg[columns];
+		return cls ? `grid grid-cols-1 ${cls} ${gapX}` : `grid grid-cols-1 ${gapX}`;
+	}
+
+	const classes = ['grid', gapX];
+	const cols = columns as Record<string, number>;
+
+	classes.push(cols.default ? GRID_COLS.base[cols.default] || 'grid-cols-1' : 'grid-cols-1');
+
+	for (const bp of BREAKPOINTS) {
+		if (cols[bp]) {
+			const cls = GRID_COLS[bp]?.[cols[bp]];
+			if (cls) classes.push(cls);
+		}
+	}
+
+	return classes.join(' ');
+}
+
+/** Vertical rhythm for stacked form fields (single column) or grid rows (multi-column). */
+export function getFieldLayoutClasses(columns?: number | Record<string, number>): string {
+	if (!columns || columns === 1) {
+		return 'flex flex-col gap-4';
+	}
+	return `${getGridClasses(columns)} gap-y-4`;
+}

package/src/components/widgets/ChartWidget.tsx

@@ -0,0 +1,247 @@
+import React, { useMemo } from 'react';
+import {
+	Chart as ChartJS,
+	CategoryScale,
+	LinearScale,
+	PointElement,
+	LineElement,
+	BarElement,
+	ArcElement,
+	Title,
+	Tooltip,
+	Legend,
+	ChartOptions,
+} from 'chart.js';
+import { Line, Bar, Pie } from 'react-chartjs-2';
+import { cn } from '../../utils/classNames';
+import { WidgetShell } from './WidgetShell';
+import { translate } from '../../i18n/activeLocale';
+
+ChartJS.register(CategoryScale, LinearScale, PointElement, LineElement, BarElement, ArcElement, Title, Tooltip, Legend);
+
+export interface ChartWidgetProps {
+	widget: {
+		name: string;
+		label?: string;
+		icon?: string;
+		color?: string;
+		chartType: 'line' | 'bar' | 'pie';
+		showLegend?: boolean;
+	};
+	data: Array<{ label: string; value: number }> | null;
+}
+
+function readThemeColor(cssVar: string, fallback: string): string {
+	if (typeof document === 'undefined') return fallback;
+	const value = getComputedStyle(document.documentElement).getPropertyValue(cssVar).trim();
+	return value || fallback;
+}
+
+function getThemeColors() {
+	const fallbackAccent = '59, 130, 246';
+	const defaultPalette = ['#2563eb', '#059669', '#d97706', '#dc2626', '#52525b'];
+	const defaultPaletteSoft = ['#dbeafe', '#d1fae5', '#fef3c7', '#fee2e2', '#f3f4f6'];
+
+	if (typeof window === 'undefined' || typeof document === 'undefined') {
+		return {
+			accent: `rgb(${fallbackAccent})`,
+			accentSoft: `rgba(${fallbackAccent}, 0.35)`,
+			accentFaint: `rgba(${fallbackAccent}, 0.12)`,
+			grid: 'rgba(148, 163, 184, 0.2)',
+			tick: 'rgba(148, 163, 184, 0.85)',
+			tooltipBg: 'rgba(15, 23, 42, 0.92)',
+			palette: defaultPalette,
+			paletteSoft: defaultPaletteSoft,
+		};
+	}
+
+	const accent = readThemeColor('--kratos-accent', '#2563eb');
+	const fgMuted = readThemeColor('--kratos-fg-muted', '#9ca3af');
+	const surface = readThemeColor('--kratos-surface', '#151517');
+
+	const palette = [
+		readThemeColor('--kratos-accent', '#2563eb'),
+		readThemeColor('--kratos-success', '#059669'),
+		readThemeColor('--kratos-warning', '#d97706'),
+		readThemeColor('--kratos-danger', '#dc2626'),
+		readThemeColor('--kratos-fg-secondary', '#52525b'),
+	];
+
+	const paletteSoft = [
+		readThemeColor('--kratos-accent-soft', '#dbeafe'),
+		readThemeColor('--kratos-success-soft', '#d1fae5'),
+		readThemeColor('--kratos-warning-soft', '#fef3c7'),
+		readThemeColor('--kratos-danger-soft', '#fee2e2'),
+		readThemeColor('--kratos-muted', '#f3f4f6'),
+	];
+
+	return {
+		accent,
+		accentSoft: readThemeColor('--kratos-accent-soft', '#dbeafe'),
+		accentFaint: readThemeColor('--kratos-accent-soft', '#dbeafe'),
+		grid: fgMuted,
+		tick: fgMuted,
+		tooltipBg: surface,
+		palette,
+		paletteSoft,
+	};
+}
+
+function colorForIndex(theme: ReturnType<typeof getThemeColors>, index: number, soft = false): string {
+	const colors = soft ? theme.paletteSoft : theme.palette;
+	return colors[index % colors.length] ?? colors[0];
+}
+
+/** Prefer stable semantic colors for common labels (e.g. admin/editor roles). */
+function colorForLabel(theme: ReturnType<typeof getThemeColors>, label: string, index: number, soft = false): string {
+	const semanticIndex: Record<string, number> = {
+		admin: 3,
+		editor: 0,
+		active: 1,
+		inactive: 4,
+		published: 1,
+		draft: 4,
+	};
+	const mapped = semanticIndex[label.toLowerCase()];
+	return colorForIndex(theme, mapped ?? index, soft);
+}
+
+export function ChartWidget({ widget, data }: ChartWidgetProps) {
+	const theme = useMemo(() => getThemeColors(), []);
+
+	const chartData = useMemo(() => {
+		if (!data || data.length === 0) {
+			return { labels: [], datasets: [] };
+		}
+
+		if (widget.chartType === 'pie') {
+			return {
+				labels: data.map(item => item.label),
+				datasets: [
+					{
+						data: data.map(item => item.value),
+						backgroundColor: data.map((item, index) => colorForLabel(theme, item.label, index)),
+						borderColor: 'transparent',
+						borderWidth: 0,
+					},
+				],
+			};
+		}
+
+		if (widget.chartType === 'bar') {
+			return {
+				labels: data.map(item => item.label),
+				datasets: [
+					{
+						label: widget.label || translate('core:widget.data_label'),
+						data: data.map(item => item.value),
+						backgroundColor: data.map((item, index) => colorForLabel(theme, item.label, index, true)),
+						borderColor: data.map((item, index) => colorForLabel(theme, item.label, index)),
+						borderWidth: 2,
+						borderRadius: 6,
+					},
+				],
+			};
+		}
+
+		return {
+			labels: data.map(item => item.label),
+			datasets: [
+				{
+					label: widget.label || translate('core:widget.data_label'),
+					data: data.map(item => item.value),
+					backgroundColor: theme.accentFaint,
+					borderColor: theme.accent,
+					borderWidth: 2,
+					fill: true,
+					tension: 0.35,
+					pointRadius: 3,
+					pointHoverRadius: 4,
+					pointBackgroundColor: theme.accent,
+				},
+			],
+		};
+	}, [data, widget.label, widget.chartType, theme]);
+
+	const options: ChartOptions<'line' | 'bar' | 'pie'> = useMemo(() => {
+		const showLegend = widget.showLegend ?? false;
+
+		if (widget.chartType === 'pie') {
+			return {
+				responsive: true,
+				maintainAspectRatio: false,
+				plugins: {
+					legend: {
+						display: showLegend,
+						position: 'bottom',
+						labels: {
+							padding: 12,
+							usePointStyle: true,
+							boxWidth: 8,
+							color: theme.tick,
+							font: { size: 11 },
+						},
+					},
+					tooltip: {
+						backgroundColor: theme.tooltipBg,
+						titleColor: theme.tick,
+						bodyColor: theme.tick,
+						borderColor: theme.grid,
+						borderWidth: 1,
+						padding: 10,
+					},
+				},
+			};
+		}
+
+		return {
+			responsive: true,
+			maintainAspectRatio: false,
+			plugins: {
+				legend: { display: showLegend, labels: { color: theme.tick, boxWidth: 8 } },
+				tooltip: {
+					backgroundColor: theme.tooltipBg,
+					titleColor: theme.tick,
+					bodyColor: theme.tick,
+					borderColor: theme.grid,
+					borderWidth: 1,
+					padding: 10,
+					displayColors: false,
+				},
+			},
+			scales: {
+				x: {
+					display: false,
+					grid: { display: false },
+					ticks: { display: false },
+				},
+				y: {
+					beginAtZero: true,
+					grid: { color: `${theme.grid}33` },
+					ticks: { color: theme.tick, maxTicksLimit: 4, font: { size: 10 } },
+					border: { display: false },
+				},
+			},
+		};
+	}, [widget.chartType, widget.showLegend, theme]);
+
+	const ChartComponent = widget.chartType === 'line' ? Line : widget.chartType === 'bar' ? Bar : Pie;
+
+	if (!data || data.length === 0) {
+		return (
+			<WidgetShell label={widget.label} icon={widget.icon} className={widget.color}>
+				<div className="flex flex-1 items-center justify-center rounded-lg border border-dashed border-border/70 bg-base/40 px-3 py-6">
+					<p className="text-sm text-fg-muted">{translate('core:state.no_data')}</p>
+				</div>
+			</WidgetShell>
+		);
+	}
+
+	return (
+		<WidgetShell label={widget.label} icon={widget.icon} className={cn('min-h-[11rem]', widget.color)}>
+			<div className="min-h-[7.5rem] flex-1">
+				<ChartComponent data={chartData} options={options as any} />
+			</div>
+		</WidgetShell>
+	);
+}

package/src/components/widgets/StatsWidget.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { WidgetShell } from './WidgetShell';
+
+export interface StatsWidgetProps {
+	widget: {
+		name: string;
+		label?: string;
+		icon?: string;
+		color?: string;
+		format?: 'number' | 'currency' | 'percentage';
+		currency?: string;
+		precision?: number;
+		suffix?: string;
+		prefix?: string;
+	};
+	data: number | null;
+}
+
+export function StatsWidget({ widget, data }: StatsWidgetProps) {
+	const formatValue = (value: number | null): string => {
+		if (value === null || value === undefined) {
+			return '—';
+		}
+
+		const { format, currency, precision = 0, prefix, suffix } = widget;
+
+		let formatted: string;
+
+		switch (format) {
+			case 'currency':
+				formatted = new Intl.NumberFormat(undefined, {
+					style: 'currency',
+					currency: currency || 'USD',
+					minimumFractionDigits: precision,
+					maximumFractionDigits: precision,
+				}).format(value);
+				break;
+
+			case 'percentage':
+				formatted = `${value.toFixed(precision)}%`;
+				break;
+
+			case 'number':
+			default:
+				formatted = new Intl.NumberFormat(undefined, {
+					minimumFractionDigits: precision,
+					maximumFractionDigits: precision,
+				}).format(value);
+				break;
+		}
+
+		if (prefix && format !== 'currency') {
+			formatted = `${prefix}${formatted}`;
+		}
+
+		if (suffix) {
+			formatted = `${formatted} ${suffix}`;
+		}
+
+		return formatted;
+	};
+
+	return (
+		<WidgetShell label={widget.label} icon={widget.icon} className={widget.color}>
+			<div className="mt-auto">
+				<p className="text-2xl font-semibold leading-tight tracking-tight text-fg sm:text-3xl">
+					{formatValue(data)}
+				</p>
+			</div>
+		</WidgetShell>
+	);
+}

package/src/components/widgets/WidgetRenderer.tsx

@@ -0,0 +1,108 @@
+import React, { useState, useEffect } from 'react';
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import { useWidgetRegistry } from '../../contexts/WidgetRegistryContext';
+import { ErrorBoundary } from '../errors/ErrorBoundary';
+import { Slot } from '../../slots/Slot';
+import { cn } from '../../utils/classNames';
+import { widgetVisibilityStorage, getDefaultWidgetsExpanded } from '../../utils/widgetVisibilityStorage';
+import { PillButton } from '../ui/PillButton';
+import { translate } from '../../i18n/activeLocale';
+
+export interface WidgetRendererProps {
+	widgets?: any[];
+	widgetData?: Record<string, any>;
+	className?: string;
+	/** When set, controlled mode: no internal toggle, use this value and callback */
+	expanded?: boolean;
+	onExpandedChange?: (expanded: boolean) => void;
+}
+
+export function WidgetRenderer({
+	widgets,
+	widgetData,
+	className,
+	expanded: controlledExpanded,
+	onExpandedChange,
+}: WidgetRendererProps) {
+	const widgetRegistry = useWidgetRegistry();
+	const [internalExpanded, setInternalExpanded] = useState(false);
+
+	const isControlled = controlledExpanded !== undefined && onExpandedChange !== undefined;
+	const expanded = isControlled ? controlledExpanded : internalExpanded;
+
+	useEffect(() => {
+		if (isControlled) return;
+		const stored = widgetVisibilityStorage.get();
+		if (stored !== null) {
+			setInternalExpanded(stored);
+		} else {
+			setInternalExpanded(getDefaultWidgetsExpanded());
+		}
+	}, [isControlled]);
+
+	const toggleExpanded = () => {
+		const next = !expanded;
+		if (isControlled) {
+			widgetVisibilityStorage.set(next);
+			onExpandedChange(next);
+		} else {
+			setInternalExpanded(next);
+			widgetVisibilityStorage.set(next);
+		}
+	};
+
+	if (!widgets || widgets.length === 0) {
+		return null;
+	}
+
+	return (
+		<div className={cn('mb-4', className)}>
+			{!isControlled && (
+				<div className="mb-2 flex justify-end">
+					<PillButton
+						variant="default"
+						onClick={toggleExpanded}
+						aria-expanded={expanded}
+						aria-controls="widgets-content"
+						id="widgets-toggle"
+						icon={expanded ? <ChevronUp className="h-4 w-4" /> : <ChevronDown className="h-4 w-4" />}>
+						{translate('core:common.widgets')}
+					</PillButton>
+				</div>
+			)}
+
+			<div
+				id="widgets-content"
+				role="region"
+				aria-labelledby="widgets-toggle"
+				className={cn(
+					'overflow-hidden transition-[grid-template-rows] duration-200 ease-out',
+					expanded ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+				)}
+				style={{ display: 'grid' }}>
+				<div className="min-h-0">
+					<div className="grid grid-cols-1 gap-3 sm:grid-cols-2 xl:grid-cols-3 2xl:grid-cols-4">
+						{widgets.map(widget => {
+							const WidgetComponent = widgetRegistry[widget.type];
+							if (!WidgetComponent) {
+								console.warn(`Widget type "${widget.type}" not registered`);
+								return null;
+							}
+
+							const data = widgetData?.[widget.name] ?? null;
+
+							return (
+								<div key={widget.name} className="min-w-0">
+									<ErrorBoundary label={`widget "${widget.name}"`}>
+										<WidgetComponent widget={widget} data={data} />
+									</ErrorBoundary>
+								</div>
+							);
+						})}
+						<Slot name="widgets.append" />
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}