@olympusoss/canvas 2.6.19

package/src/components/charts/sparkline.tsx

@@ -0,0 +1,52 @@
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+
+export interface SparklineProps extends React.HTMLAttributes<HTMLDivElement> {
+	/** Values to plot. Each entry maps to a bar. */
+	data: number[];
+	/** Pixel height of the chart. */
+	height?: number;
+	/**
+	 * CSS variable name (without leading `--`) used for the bar fill. Default
+	 * `chart-1`. The variable should resolve to an HSL triplet for `hsl()`.
+	 */
+	colorVar?: string;
+	/** Pixel gap between bars. */
+	gap?: number;
+	/** Caption rendered below the bars. */
+	caption?: React.ReactNode;
+}
+
+/**
+ * Pure-CSS mini bar chart for inline embedding in `<StatCard>` /
+ * `<SectionCard>`. Decorative — for live data, use a `<BarChart>` from the
+ * charts tier with proper axes and tooltips.
+ */
+export const Sparkline = React.forwardRef<HTMLDivElement, SparklineProps>(
+	({ data, height = 160, colorVar = "chart-1", gap = 4, caption, className, ...props }, ref) => {
+		const max = Math.max(1, ...data);
+		return (
+			<div ref={ref} className={cn("w-full", className)} {...props}>
+				<div className="flex w-full items-end" style={{ height, gap }}>
+					{data.map((value, i) => {
+						const pct = Math.max(0, Math.min(100, (value / max) * 100));
+						return (
+							<div
+								key={`bar-${i}-${value}`}
+								className="flex-1 rounded-sm"
+								style={{
+									height: `${pct}%`,
+									background: `hsl(var(--${colorVar}))`,
+								}}
+								aria-hidden
+							/>
+						);
+					})}
+				</div>
+				{caption && <p className="mt-3 text-xs text-muted-foreground">{caption}</p>}
+			</div>
+		);
+	},
+);
+Sparkline.displayName = "Sparkline";

package/src/components/charts/stacked-bar.tsx

@@ -0,0 +1,104 @@
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+
+export interface StackedBarSegment {
+	/** Label shown in the legend. Used as the React key. */
+	label: string;
+	/** Numeric value (raw count or percentage). Segments size proportionally to the sum. */
+	value: number;
+	/**
+	 * CSS variable name (without leading `--`) used for the segment fill. Default
+	 * `chart-1`. Each segment can override; unspecified segments fall through
+	 * to the wrapper's `defaultColorVar`.
+	 */
+	colorVar?: string;
+}
+
+export interface StackedBarProps extends React.HTMLAttributes<HTMLDivElement> {
+	/** Segments rendered left-to-right with width proportional to `value`. */
+	segments: StackedBarSegment[];
+	/**
+	 * Fallback CSS variable name for segments that omit `colorVar`. Default
+	 * `chart-1`.
+	 */
+	defaultColorVar?: string;
+	/** Pixel height of the bar pill. Default `10`. */
+	height?: number;
+	/** Show the legend list below the bar. Default `true`. */
+	showLegend?: boolean;
+	/** Format the per-segment value in the legend. Default `(v) => `${v}%``. */
+	valueFormatter?: (value: number) => string;
+	/** Caption rendered below the legend. */
+	caption?: React.ReactNode;
+}
+
+/**
+ * Horizontal stacked-percent bar with an optional swatch legend below. Segments
+ * are sized proportionally to their value's share of the total — pass raw
+ * counts or pre-computed percentages, the rendering is the same.
+ */
+export const StackedBar = React.forwardRef<HTMLDivElement, StackedBarProps>(
+	(
+		{
+			segments,
+			defaultColorVar = "chart-1",
+			height = 10,
+			showLegend = true,
+			valueFormatter = (v) => `${v}%`,
+			caption,
+			className,
+			...props
+		},
+		ref,
+	) => {
+		const total = segments.reduce((sum, s) => sum + s.value, 0) || 1;
+		return (
+			<div ref={ref} className={cn("w-full", className)} {...props}>
+				<div
+					className="flex w-full overflow-hidden rounded-full bg-muted"
+					style={{ height }}
+					role="presentation"
+				>
+					{segments.map((seg) => {
+						const pct = (seg.value / total) * 100;
+						const colorVar = seg.colorVar ?? defaultColorVar;
+						return (
+							<div
+								key={seg.label}
+								style={{
+									width: `${pct}%`,
+									background: `hsl(var(--${colorVar}))`,
+								}}
+								title={`${seg.label}: ${valueFormatter(seg.value)}`}
+								aria-hidden
+							/>
+						);
+					})}
+				</div>
+				{showLegend && (
+					<ul className="mt-3 flex flex-col gap-2">
+						{segments.map((seg) => {
+							const colorVar = seg.colorVar ?? defaultColorVar;
+							return (
+								<li key={seg.label} className="flex items-center gap-2.5 text-[13px]">
+									<span
+										className="size-2 shrink-0 rounded-full"
+										style={{ background: `hsl(var(--${colorVar}))` }}
+										aria-hidden
+									/>
+									<span className="flex-1">{seg.label}</span>
+									<span className="font-mono text-xs text-muted-foreground">
+										{valueFormatter(seg.value)}
+									</span>
+								</li>
+							);
+						})}
+					</ul>
+				)}
+				{caption && <p className="mt-3 text-xs text-muted-foreground">{caption}</p>}
+			</div>
+		);
+	},
+);
+StackedBar.displayName = "StackedBar";

package/src/components/charts/text.tsx

@@ -0,0 +1,10 @@
+"use client";
+
+/**
+ * Text-rendering primitives. `Label` is aliased to `ChartLabel` to avoid
+ * collision with canvas's form `Label` atom.
+ *
+ * Re-exported via `export { … }` so TypeScript doesn't have to name internal
+ * Recharts prop types in the d.ts emit.
+ */
+export { Label as ChartLabel, LabelList, Text } from "recharts";

package/src/components/charts/world-heat-map-inner.tsx

@@ -0,0 +1,317 @@
+"use client";
+
+/* c8 ignore file -- Leaflet imports require real DOM measurements and are
+ * jsdom-incompatible. This file is covered structurally via the lazy
+ * boundary + loading shell + error-fallback in world-heat-map.test.tsx;
+ * the rendered Leaflet tree is verified visually in the docs. */
+
+import * as React from "react";
+import { CircleMarker, MapContainer, TileLayer, Tooltip } from "react-leaflet";
+
+import { cn } from "../../lib/utils";
+import { useTheme } from "../organisms/theme-provider";
+import type { WorldHeatMapPoint, WorldHeatMapProps } from "./world-heat-map";
+
+/**
+ * Client-only Leaflet tree. Loaded via `React.lazy()` from the orchestrator
+ * `world-heat-map.tsx` so neither `leaflet` nor `react-leaflet` lands in the
+ * main canvas bundle. SSR / loading / error are handled by the orchestrator —
+ * this file assumes a browser environment.
+ *
+ * Visual identity matches the deployed admin spec extracted from
+ * `https://admin.ciam.nannier.com/dashboard`:
+ *   - CartoDB Basemaps (`dark_all` / `light_all`, `@2x` retina)
+ *   - Hidden controls (zoomControl, attributionControl)
+ *   - Triple-layered CircleMarker per point (glow / main / centre)
+ *   - Log-scaled radius (`log(1+count) / log(1+maxCount)`)
+ *
+ * Consumers must import `@olympusoss/canvas/styles/leaflet.css` once at app
+ * entry — Leaflet's base stylesheet doesn't ship with this component.
+ */
+
+const SCOPED_CSS = `
+.world-heat-map .leaflet-container {
+	border-radius: inherit;
+	background: transparent;
+	font: inherit;
+	touch-action: none;
+}
+.world-heat-map .leaflet-control-attribution {
+	display: none;
+}
+.world-heat-map.world-heat-map--no-controls .leaflet-control-zoom {
+	display: none;
+}
+.world-heat-map .leaflet-control-zoom {
+	border: 1px solid hsl(var(--border) / 0.5) !important;
+	border-radius: 0.5rem !important;
+	overflow: hidden;
+	box-shadow: 0 2px 8px rgb(0 0 0 / 0.1) !important;
+}
+.world-heat-map .leaflet-control-zoom a {
+	background: hsl(var(--popover)) !important;
+	color: hsl(var(--popover-foreground)) !important;
+	border-bottom-color: hsl(var(--border) / 0.3) !important;
+	width: 32px !important;
+	height: 32px !important;
+	line-height: 32px !important;
+	font-size: 16px !important;
+}
+.world-heat-map .leaflet-control-zoom a:hover {
+	background: hsl(var(--accent)) !important;
+	color: hsl(var(--accent-foreground)) !important;
+}
+.whm-tooltip-popup {
+	background: hsl(var(--popover)) !important;
+	color: hsl(var(--popover-foreground)) !important;
+	border: 1px solid hsl(var(--border) / 0.5) !important;
+	border-radius: 0.5rem !important;
+	padding: 0.5rem 0.75rem !important;
+	font-size: 0.75rem !important;
+	font-family: inherit !important;
+	box-shadow: 0 4px 12px rgb(0 0 0 / 0.15) !important;
+}
+.whm-tooltip-popup::before {
+	border-top-color: hsl(var(--popover)) !important;
+}
+.whm-tooltip-label {
+	font-weight: 600;
+	font-size: 13px;
+	line-height: 1.2;
+}
+.whm-tooltip-count {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	margin-top: 2px;
+	color: hsl(var(--muted-foreground));
+	font-variant-numeric: tabular-nums;
+	font-size: 12px;
+}
+.whm-tooltip-dot {
+	display: inline-block;
+	height: 8px;
+	width: 8px;
+	border-radius: 50%;
+}
+`;
+
+const TILE_URL_DARK = "https://basemaps.cartocdn.com/dark_all/{z}/{x}/{y}@2x.png";
+const TILE_URL_LIGHT = "https://basemaps.cartocdn.com/light_all/{z}/{x}/{y}@2x.png";
+
+const ATTRIBUTION =
+	'&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> &copy; <a href="https://carto.com/attributions">CARTO</a>';
+
+function resolveHeight(height: number | string | undefined): string {
+	if (height === undefined) return "100%";
+	return typeof height === "number" ? `${height}px` : height;
+}
+
+interface MarkerLayers {
+	glowRadius: number;
+	mainRadius: number;
+	centreRadius: number;
+	mainOpacity: number;
+	glowOpacity: number;
+}
+
+function deriveMarker(
+	count: number,
+	maxCount: number,
+	[rMin, rMax]: [number, number],
+): MarkerLayers {
+	const t = maxCount > 0 ? Math.log(1 + count) / Math.log(1 + maxCount) : 0;
+	const r = rMin + t * (rMax - rMin);
+	const opacity = 0.4 + t * 0.55;
+	return {
+		glowRadius: r * 1.8,
+		mainRadius: r,
+		centreRadius: Math.max(r * 0.35, 1.5),
+		mainOpacity: opacity,
+		glowOpacity: opacity * 0.15,
+	};
+}
+
+export default function WorldHeatMapInner({
+	points,
+	height,
+	center = [20, 0],
+	zoom = 3,
+	tileTheme = "auto",
+	showControls = false,
+	markerColor = "hsl(var(--chart-1))",
+	markerRadiusRange = [4, 20],
+	onMarkerClick,
+	showLegend = true,
+	title,
+	emptyState,
+	className,
+}: WorldHeatMapProps) {
+	const { resolvedTheme } = useTheme();
+	const isDark = tileTheme === "dark" || (tileTheme === "auto" && resolvedTheme === "dark");
+	const tileUrl = isDark ? TILE_URL_DARK : TILE_URL_LIGHT;
+
+	const heightStr = resolveHeight(height);
+	const maxCount = React.useMemo(
+		() => points.reduce((acc, p) => Math.max(acc, p.count), 1),
+		[points],
+	);
+	const hasData = points.length > 0;
+
+	return (
+		<div
+			className={cn(
+				"relative overflow-hidden rounded-xl world-heat-map",
+				!showControls && "world-heat-map--no-controls",
+				className,
+			)}
+			style={{ height: heightStr }}
+		>
+			<style dangerouslySetInnerHTML={{ __html: SCOPED_CSS }} />
+
+			<MapContainer
+				center={center}
+				zoom={zoom}
+				minZoom={2}
+				maxZoom={19}
+				zoomControl={showControls}
+				attributionControl={showControls}
+				worldCopyJump={false}
+				maxBounds={[
+					[-85, -180],
+					[85, 180],
+				]}
+				maxBoundsViscosity={1}
+				className="h-full w-full"
+			>
+				<TileLayer key={tileUrl} url={tileUrl} attribution={ATTRIBUTION} />
+
+				{points.map((point) => (
+					<MarkerGroup
+						key={`${point.lat},${point.lng},${point.label}`}
+						point={point}
+						maxCount={maxCount}
+						markerColor={markerColor}
+						markerRadiusRange={markerRadiusRange}
+						onMarkerClick={onMarkerClick}
+					/>
+				))}
+			</MapContainer>
+
+			{title && (
+				<div className="pointer-events-none absolute left-4 top-4 z-[1000] text-sm font-semibold tracking-tight text-foreground">
+					{title}
+				</div>
+			)}
+
+			{showLegend && hasData && (
+				<div className="pointer-events-none absolute bottom-3 left-4 z-[1000] flex items-center gap-2.5 text-[10px] text-muted-foreground">
+					<div className="flex items-center gap-1">
+						<svg width="8" height="8" aria-hidden="true">
+							<title>Smaller marker</title>
+							<circle cx="4" cy="4" r="2.5" fill={markerColor} fillOpacity={0.5} />
+						</svg>
+						<span>Fewer</span>
+					</div>
+					<div className="flex items-center gap-1">
+						<svg width="14" height="14" aria-hidden="true">
+							<title>Larger marker</title>
+							<circle cx="7" cy="7" r="5" fill={markerColor} fillOpacity={0.9} />
+						</svg>
+						<span>More</span>
+					</div>
+				</div>
+			)}
+
+			{!hasData && (
+				<div className="pointer-events-none absolute inset-0 z-[1000] flex items-center justify-center">
+					{emptyState ?? (
+						<div className="rounded-lg bg-card px-4 py-2 text-xs text-muted-foreground shadow">
+							No geographic data available
+						</div>
+					)}
+				</div>
+			)}
+
+			{/* CartoDB attribution — always visible per TOS, even when controls are hidden */}
+			{!showControls && (
+				<div
+					className="pointer-events-auto absolute bottom-1 right-1 z-[1000] text-[9px] text-muted-foreground/60"
+					dangerouslySetInnerHTML={{ __html: ATTRIBUTION }}
+				/>
+			)}
+		</div>
+	);
+}
+
+/**
+ * Three concentric `<CircleMarker>`s per data point: outer glow, main dot
+ * (interactive + tooltip), bright centre. Pulled into its own component so the
+ * tooltip's stable `<Tooltip>` child slot lives next to the marker that owns
+ * it (react-leaflet attaches by parent identity).
+ */
+function MarkerGroup({
+	point,
+	maxCount,
+	markerColor,
+	markerRadiusRange,
+	onMarkerClick,
+}: {
+	point: WorldHeatMapPoint;
+	maxCount: number;
+	markerColor: string;
+	markerRadiusRange: [number, number];
+	onMarkerClick?: (point: WorldHeatMapPoint) => void;
+}) {
+	const layers = deriveMarker(point.count, maxCount, markerRadiusRange);
+	const handlers = React.useMemo(
+		() => (onMarkerClick ? { click: () => onMarkerClick(point) } : undefined),
+		[onMarkerClick, point],
+	);
+
+	return (
+		<>
+			<CircleMarker
+				center={[point.lat, point.lng]}
+				radius={layers.glowRadius}
+				pathOptions={{
+					fillColor: markerColor,
+					fillOpacity: layers.glowOpacity,
+					stroke: false,
+					interactive: false,
+				}}
+			/>
+			<CircleMarker
+				center={[point.lat, point.lng]}
+				radius={layers.mainRadius}
+				pathOptions={{
+					fillColor: markerColor,
+					fillOpacity: layers.mainOpacity,
+					color: markerColor,
+					weight: 1,
+					opacity: 0.8,
+				}}
+				eventHandlers={handlers}
+			>
+				<Tooltip direction="top" offset={[0, -layers.mainRadius]} className="whm-tooltip-popup">
+					<div className="whm-tooltip-label">{point.label}</div>
+					<div className="whm-tooltip-count">
+						<span className="whm-tooltip-dot" style={{ background: markerColor }} />
+						{point.count.toLocaleString()} session
+						{point.count !== 1 ? "s" : ""}
+					</div>
+				</Tooltip>
+			</CircleMarker>
+			<CircleMarker
+				center={[point.lat, point.lng]}
+				radius={layers.centreRadius}
+				pathOptions={{
+					fillColor: markerColor,
+					fillOpacity: 0.95,
+					stroke: false,
+					interactive: false,
+				}}
+			/>
+		</>
+	);
+}

package/src/components/charts/world-heat-map.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+
+/**
+ * `<WorldHeatMap>` — Leaflet-based geographic scatter / heat-map.
+ *
+ * Public surface lives here; the actual react-leaflet tree is in
+ * `world-heat-map-inner.tsx` and is loaded via `React.lazy()` so neither
+ * `leaflet` nor `react-leaflet` lands in canvas's main bundle. Both are
+ * declared as **peer-optional** in `package.json` — consumers who use the map
+ * install them explicitly; consumers who don't, don't pay.
+ *
+ * Consumers must also import the Leaflet base stylesheet at app entry:
+ *
+ *   import "@olympusoss/canvas/styles/leaflet.css";
+ *
+ * Visual identity matches the deployed admin dashboard reference (CartoDB
+ * tiles, hidden controls, triple-layered CircleMarker per point).
+ */
+
+// ── Public types ─────────────────────────────────────────────
+
+export interface WorldHeatMapPoint {
+	/** Latitude. */
+	lat: number;
+	/** Longitude. */
+	lng: number;
+	/** Tooltip label (e.g. "Munich, DE"). */
+	label: string;
+	/** Drives marker radius. */
+	count: number;
+}
+
+export interface WorldHeatMapProps {
+	/** Geo-located points to render. Empty array shows the empty-state overlay. */
+	points: WorldHeatMapPoint[];
+	/** Container height. Number → px, string passes through. Default `"100%"`. */
+	height?: number | string;
+	/** Initial map center `[lat, lng]`. Default `[20, 0]`. */
+	center?: [number, number];
+	/** Initial zoom. Default `3`. */
+	zoom?: number;
+	/** Tile basemap. `"auto"` follows canvas's `useTheme()`. Default `"auto"`. */
+	tileTheme?: "auto" | "dark" | "light";
+	/** Show Leaflet zoom + attribution controls. Default `false`. */
+	showControls?: boolean;
+	/** Marker fill (any CSS colour, including `hsl(var(--chart-1))`). Default `"hsl(var(--chart-1))"`. */
+	markerColor?: string;
+	/** `[min, max]` marker radius in pixels (log-scaled on `count`). Default `[4, 20]`. */
+	markerRadiusRange?: [number, number];
+	/** Per-marker click handler. */
+	onMarkerClick?: (point: WorldHeatMapPoint) => void;
+	/** Show "Fewer / More" legend overlay (bottom-left). Default `true`. */
+	showLegend?: boolean;
+	/** Optional title overlaid top-left. */
+	title?: string;
+	/** Override the empty-state node. Default: a small "No geographic data available" card. */
+	emptyState?: React.ReactNode;
+	/** Pass-through className on the outer `.world-heat-map` wrapper. */
+	className?: string;
+}
+
+// ── Lazy-loaded inner ───────────────────────────────────────
+
+const WorldHeatMapInner = React.lazy(() => import("./world-heat-map-inner"));
+
+// ── Error boundary (peer-missing or runtime-load failure) ───
+
+interface WorldHeatMapErrorBoundaryProps {
+	fallback: React.ReactNode;
+	children: React.ReactNode;
+}
+interface WorldHeatMapErrorBoundaryState {
+	hasError: boolean;
+}
+
+class WorldHeatMapErrorBoundary extends React.Component<
+	WorldHeatMapErrorBoundaryProps,
+	WorldHeatMapErrorBoundaryState
+> {
+	state: WorldHeatMapErrorBoundaryState = { hasError: false };
+
+	/* c8 ignore start -- only triggers when the lazy-loaded Leaflet inner throws (peer missing or runtime load failure); both are jsdom-incompatible to simulate */
+	static getDerivedStateFromError(): WorldHeatMapErrorBoundaryState {
+		return { hasError: true };
+	}
+
+	render(): React.ReactNode {
+		return this.state.hasError ? this.props.fallback : this.props.children;
+	}
+	/* c8 ignore stop */
+}
+
+// ── Shell (SSR / loading / error) ───────────────────────────
+
+type ShellState = "loading" | "error";
+
+interface ShellProps {
+	height?: number | string;
+	className?: string;
+	state: ShellState;
+}
+
+function resolveHeight(height: number | string | undefined): string {
+	if (height === undefined) return "100%";
+	return typeof height === "number" ? `${height}px` : height;
+}
+
+function Shell({ height, className, state }: ShellProps) {
+	const heightStr = resolveHeight(height);
+	return (
+		<div
+			className={cn(
+				"relative flex items-center justify-center overflow-hidden rounded-xl bg-muted/40 text-xs text-muted-foreground world-heat-map",
+				className,
+			)}
+			style={{ height: heightStr }}
+		>
+			{state === "loading" ? (
+				<>
+					<svg
+						width="20"
+						height="20"
+						viewBox="0 0 20 20"
+						aria-hidden="true"
+						className="mr-2 animate-spin opacity-50"
+					>
+						<title>Loading</title>
+						<circle
+							cx="10"
+							cy="10"
+							r="8"
+							fill="none"
+							stroke="currentColor"
+							strokeWidth="2"
+							strokeDasharray="40"
+							strokeLinecap="round"
+						/>
+					</svg>
+					Loading map…
+				</>
+			) : (
+				<div className="px-4 py-2 text-center">
+					Map dependencies missing — install <code>leaflet</code> and <code>react-leaflet</code>.
+				</div>
+			)}
+		</div>
+	);
+}
+
+// ── Public component ────────────────────────────────────────
+
+export function WorldHeatMap(props: WorldHeatMapProps) {
+	const [mounted, setMounted] = React.useState(false);
+
+	React.useEffect(() => {
+		setMounted(true);
+	}, []);
+
+	// SSR / hydration guard — prevents `window`/`document` access during the
+	// server pass and the first client render before hydration completes.
+	if (!mounted) {
+		return <Shell height={props.height} className={props.className} state="loading" />;
+	}
+
+	/* c8 ignore start -- post-mount tree mounts the lazy Leaflet inner; jsdom can't run Leaflet so the Suspense + ErrorBoundary tree is verified visually in the docs */
+	return (
+		<WorldHeatMapErrorBoundary
+			fallback={<Shell height={props.height} className={props.className} state="error" />}
+		>
+			<React.Suspense
+				fallback={<Shell height={props.height} className={props.className} state="loading" />}
+			>
+				<WorldHeatMapInner {...props} />
+			</React.Suspense>
+		</WorldHeatMapErrorBoundary>
+	);
+	/* c8 ignore stop */
+}
+
+WorldHeatMap.displayName = "WorldHeatMap";

package/src/components/molecules/README.md

@@ -0,0 +1,12 @@
+# Molecules
+
+Small compositions of atoms. Meaningful UI semantics. No app-state model.
+
+**Can import**: `tokens/`, `lib/utils`, `atoms/`, React.
+
+**Cannot import**: anything from `organisms/` or `templates/`.
+
+Molecules don't own interactive state more complex than a local toggle. If it
+has open/close state, selection, or form integration, it's an organism.
+
+See [CONTRIBUTING.md](../../../CONTRIBUTING.md) for the full atomic-design rules.