@mizen-labs/ui 0.0.0-stage → 0.1.0

package/src/components/chart-frame/chart-crosshair.ts

@@ -0,0 +1,129 @@
+import {
+	type ChartAxisTickLabelOpacityContext,
+	type ChartMark,
+	crosshair,
+	type SceneLabel,
+	type SceneNode,
+} from "@tanstack/charts";
+import { resolveCrosshairGuide } from "@tanstack/charts/crosshair";
+import { colors } from "../../styles/colors.stylex";
+import { mizenAxisLabels, mizenTickGap } from "./chart-frame";
+
+// Mizen's focus guides wear the brand: a wine rule whose time label sits in a
+// wine pill on the axis, and a lavender band behind the focused category.
+
+const PILL_PADDING_X = 8;
+const PILL_HEIGHT = 18;
+// Tabular digits and short month names average a bit over half an em.
+const CHARACTER_WIDTH = 0.58;
+
+function isAxisLabel(node: SceneNode): node is SceneLabel {
+	return (
+		node.kind === "label" &&
+		(node.className ?? "").includes("crosshair-label--x")
+	);
+}
+
+/** Puts a rounded wine pill behind the focused time label. */
+function withPill(node: SceneNode | undefined): SceneNode | undefined {
+	if (node?.kind !== "group") {
+		return node;
+	}
+	const children = node.children.flatMap((child): SceneNode[] => {
+		if (!isAxisLabel(child)) {
+			return [withPill(child) ?? child];
+		}
+		const fontSize = child.fontSize ?? mizenAxisLabels.fontSize;
+		const width =
+			child.text.length * fontSize * CHARACTER_WIDTH + PILL_PADDING_X * 2;
+		const center = child.y - fontSize * 0.35;
+		return [
+			{
+				height: PILL_HEIGHT,
+				key: `${child.key}:pill`,
+				kind: "rect",
+				radius: PILL_HEIGHT / 2,
+				style: { fill: colors.brandForeground },
+				width,
+				x: child.x - width / 2,
+				y: center - PILL_HEIGHT / 2,
+			},
+			{ ...child, style: { ...child.style, fill: colors.surface } },
+		];
+	});
+	return { ...node, children };
+}
+
+function pillCrosshair(mark: ChartMark<never, Date, number>) {
+	return {
+		...mark,
+		initialize: (context: Parameters<typeof mark.initialize>[0]) => {
+			const initialized = mark.initialize(context);
+			return {
+				...initialized,
+				render: (renderContext: Parameters<typeof initialized.render>[0]) => {
+					const scene = initialized.render(renderContext);
+					return {
+						...scene,
+						focusGuides: scene.focusGuides?.map((guide) => ({
+							...guide,
+							resolve: (resolveContext: Parameters<typeof guide.resolve>[0]) =>
+								withPill(resolveCrosshairGuide(resolveContext)),
+						})),
+					};
+				},
+			};
+		},
+	};
+}
+
+// A tick closer than this to the focused time would show through the pill.
+const PILL_CLEARANCE = 40;
+
+/** Tick label options that hide the ticks under the focus pill while it shows. */
+export const pillTickLabels = {
+	opacity: ({ focus, position }: ChartAxisTickLabelOpacityContext) =>
+		focus && Math.abs(position - focus.primary.x) < PILL_CLEARANCE
+			? 0
+			: undefined,
+};
+
+/** A vertical rule at the focused time, labeled in a pill on the x axis. */
+export function timeCrosshair(format: (date: Date) => string) {
+	return pillCrosshair(
+		crosshair<Date, number>({
+			x: {
+				// The pill covers the gray tick under it, so the label reads alone.
+				label: {
+					fill: colors.surface,
+					fillOpacity: 1,
+					fontSize: mizenAxisLabels.fontSize,
+					fontWeight: mizenAxisLabels.fontWeight,
+					format,
+					offset: mizenTickGap,
+					strokeWidth: 0,
+				},
+				stroke: colors.brandForeground,
+				strokeOpacity: 0.4,
+				strokeWidth: 1,
+			},
+			y: false,
+		})
+	);
+}
+
+/** A soft band behind the focused category, drawn under the bars. */
+export function bandCrosshair(axis: "x" | "y") {
+	const band = {
+		band: {
+			fill: colors.brandBackground,
+			fillOpacity: 1,
+			inset: -4,
+			radius: 8,
+		},
+		label: false,
+	};
+	return crosshair(
+		axis === "x" ? { x: band, y: false } : { x: false, y: band }
+	);
+}

package/src/components/chart-frame/chart-data-table.tsx

@@ -0,0 +1,15 @@
+import { props } from "@stylexjs/stylex";
+import type { ReactNode } from "react";
+import { visuallyHiddenStyles } from "../visually-hidden/visually-hidden.styles";
+
+/**
+ * A chart's exact values as a table for assistive technology. It stays out of
+ * sight: sighted readers get the same values from tooltips and keyboard focus.
+ */
+export function ChartDataTable({ children }: { children: ReactNode }) {
+	return (
+		<div data-slot="chart-data" {...props(visuallyHiddenStyles.root)}>
+			{children}
+		</div>
+	);
+}

package/src/components/chart-frame/chart-frame.styles.ts

@@ -0,0 +1,48 @@
+import { create } from "@stylexjs/stylex";
+import { colors } from "../../styles/colors.stylex";
+import { conditions } from "../../styles/conditions.stylex";
+import {
+	borderWidth,
+	focus,
+	focusMotion,
+} from "../../styles/interaction.stylex";
+
+export const chartFrameStyles = create({
+	customTooltip: {
+		"--ts-chart-tooltip-background": "transparent",
+		"--ts-chart-tooltip-border": "none",
+		"--ts-chart-tooltip-padding": "0",
+		"--ts-chart-tooltip-shadow": "none",
+	},
+	frame: {
+		"--ts-chart-1": colors.chartSeries1,
+		"--ts-chart-2": colors.chartSeries2,
+		"--ts-chart-3": colors.chartSeries3,
+		"--ts-chart-4": colors.chartSeries4,
+		"--ts-chart-5": colors.chartSeries5,
+		"--ts-chart-6": colors.chartSeries6,
+		// No halo: the frame inherits any parent surface, and the label redraws the
+		// tick beneath it in the same place.
+		"--ts-chart-crosshair-label-halo": "transparent",
+		"--ts-chart-tooltip-background": colors.floatingSurface,
+		"--ts-chart-tooltip-border": `1px solid ${colors.border}`,
+		"--ts-chart-tooltip-color": colors.content,
+		backgroundColor: "transparent",
+		color: colors.content,
+		fontFamily: "inherit",
+		fontVariantNumeric: "tabular-nums",
+		minWidth: 0,
+		width: "100%",
+	},
+	plot: {
+		animationDuration: { ":focus-visible": focusMotion.duration },
+		animationName: { ":focus-visible": focusMotion.ring },
+		outlineColor: {
+			default: colors.focusRing,
+			[conditions.forcedColors]: "Highlight",
+		},
+		outlineOffset: focus.offset,
+		outlineStyle: { ":focus-visible": "solid", default: "none" },
+		outlineWidth: borderWidth.focus,
+	},
+});

package/src/components/chart-frame/chart-frame.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+import { props } from "@stylexjs/stylex";
+import type {
+	ChartPositionScaleOptions,
+	ChartTheme,
+	ChartValue,
+	DomChartDefinition,
+} from "@tanstack/charts";
+import {
+	type ChartProps,
+	Chart as TanStackChart,
+} from "@tanstack/charts/react/tooltip";
+import { useMemo } from "react";
+import type { Closed } from "../../closed";
+import { colors } from "../../styles/colors.stylex";
+import { chartFrameStyles } from "./chart-frame.styles";
+
+type ChartSizing =
+	| { aspectRatio?: never; height?: number }
+	| { aspectRatio: number; height?: never };
+
+const mizenTheme: Partial<ChartTheme> = {
+	foreground: colors.content,
+	grid: colors.border,
+	muted: colors.mutedContent,
+};
+// TanStack chart option in px, matching the caption role.
+// eslint-disable-next-line no-restricted-syntax -- a charts API value, not CSS.
+export const mizenAxisLabels = { fontSize: 12, fontWeight: 400, opacity: 1 };
+// Gap between the plot and x tick labels, in px; overlays on a tick reuse it.
+export const mizenTickGap = 4;
+const mizenGrid = {
+	stroke: colors.controlSurface,
+	strokeDasharray: "4 4",
+	// The engine fades grids to 0.11 by default; the track color is quiet enough.
+	strokeOpacity: 1,
+	strokeWidth: 1,
+};
+
+type MizenAxisOptions = Extract<
+	NonNullable<ChartPositionScaleOptions["axis"]>,
+	object
+>;
+
+function withMizenAxisLabel(label: MizenAxisOptions["label"]) {
+	if (typeof label === "string") {
+		return { ...mizenAxisLabels, text: label };
+	}
+	return label === undefined ? undefined : { ...mizenAxisLabels, ...label };
+}
+
+export type ChartFrameProps<
+	TDatum = unknown,
+	TXValue extends ChartValue = ChartValue,
+	TYValue extends ChartValue = ChartValue,
+> = Omit<
+	Closed<ChartProps<TDatum, TXValue, TYValue>>,
+	| "ariaDescription"
+	| "ariaLabel"
+	| "aspectRatio"
+	| "height"
+	| "initialWidth"
+	| "measureText"
+	| "onRender"
+	| "renderSvg"
+	| "width"
+> &
+	ChartSizing & {
+		/** Extra context for assistive tech, after the name. */
+		"aria-description"?: string;
+		"aria-label": string;
+		initialWidth?: number;
+	};
+
+function requireChartLabel(ariaLabel: string): void {
+	if (typeof ariaLabel !== "string" || !ariaLabel.trim()) {
+		throw new TypeError("ChartFrame requires a non-empty aria-label.");
+	}
+}
+
+function requirePositiveFinite(value: number, name: string): void {
+	if (!Number.isFinite(value) || value <= 0) {
+		throw new RangeError(`${name} must be a finite number greater than zero.`);
+	}
+}
+
+function withMizenAxisDefaults(
+	scale: ChartPositionScaleOptions | null
+): ChartPositionScaleOptions | null {
+	if (scale === null) {
+		return null;
+	}
+
+	const { axis, ...scaleProps } = scale;
+	if (axis === false) {
+		return scale;
+	}
+	const { label, ticks, tickLabels, line, ...axisProps } = axis ?? {};
+
+	return {
+		...scaleProps,
+		axis: {
+			...axisProps,
+			label: withMizenAxisLabel(label),
+			line: line ?? false,
+			tickLabels:
+				tickLabels === false ? false : { ...mizenAxisLabels, ...tickLabels },
+			ticks:
+				ticks === false ? false : { padding: mizenTickGap, size: 0, ...ticks },
+		},
+		// Grid lines are quiet dashes, so they guide the eye without boxing data.
+		grid: scaleProps.grid === true ? mizenGrid : scaleProps.grid,
+	};
+}
+
+function withMizenSpec<
+	TSpec extends {
+		scales: Readonly<Record<string, ChartPositionScaleOptions | null>>;
+		theme?: Partial<ChartTheme>;
+	},
+>(spec: TSpec): TSpec {
+	// Object.fromEntries widens keys; this transform keeps every original scale key.
+	const scales = Object.fromEntries(
+		Object.entries(spec.scales).map(([name, scale]) => [
+			name,
+			withMizenAxisDefaults(scale),
+		])
+	) as TSpec["scales"];
+
+	return {
+		...spec,
+		scales,
+		theme: { ...mizenTheme, ...spec.theme },
+	};
+}
+
+function withMizenTheme<
+	TDatum,
+	TXValue extends ChartValue,
+	TYValue extends ChartValue,
+>(
+	definition: DomChartDefinition<TDatum, TXValue, TYValue>
+): DomChartDefinition<TDatum, TXValue, TYValue> {
+	if ("chart" in definition) {
+		return {
+			...definition,
+			chart: (context) => withMizenSpec(definition.chart(context)),
+		};
+	}
+
+	return withMizenSpec(definition);
+}
+
+function styleChartPlot({ svg }: { svg: SVGSVGElement }) {
+	const { className } = props(chartFrameStyles.plot);
+	if (className) {
+		svg.classList.add(...className.split(" "));
+	}
+}
+
+export function ChartFrame<
+	TDatum = unknown,
+	TXValue extends ChartValue = ChartValue,
+	TYValue extends ChartValue = ChartValue,
+>({
+	"aria-description": ariaDescription,
+	"aria-label": ariaLabel,
+	aspectRatio,
+	definition,
+	height,
+	initialWidth = 896,
+	idPrefix,
+	onFocusChange,
+	onFocusGroupChange,
+	onSelect,
+	renderTooltipBody,
+	tabIndex,
+}: ChartFrameProps<TDatum, TXValue, TYValue>) {
+	requireChartLabel(ariaLabel);
+	requirePositiveFinite(initialWidth, "initialWidth");
+	if (aspectRatio !== undefined && height !== undefined) {
+		throw new TypeError(
+			"ChartFrame accepts either height or aspectRatio, not both."
+		);
+	}
+	if (aspectRatio !== undefined) {
+		requirePositiveFinite(aspectRatio, "aspectRatio");
+	}
+	if (height !== undefined) {
+		requirePositiveFinite(height, "height");
+	}
+	const themedDefinition = useMemo(
+		() => withMizenTheme(definition),
+		[definition]
+	);
+
+	return (
+		<div
+			data-slot="chart-frame"
+			{...props(
+				chartFrameStyles.frame,
+				renderTooltipBody && chartFrameStyles.customTooltip
+			)}
+		>
+			<TanStackChart
+				ariaDescription={ariaDescription}
+				ariaLabel={ariaLabel}
+				aspectRatio={aspectRatio}
+				definition={themedDefinition}
+				height={aspectRatio === undefined ? (height ?? 320) : undefined}
+				idPrefix={idPrefix}
+				initialWidth={initialWidth}
+				onFocusChange={onFocusChange}
+				onFocusGroupChange={onFocusGroupChange}
+				onRender={styleChartPlot}
+				onSelect={onSelect}
+				renderTooltipBody={renderTooltipBody}
+				tabIndex={tabIndex}
+			/>
+		</div>
+	);
+}

package/src/components/chart-frame/chart-hover.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { create, props } from "@stylexjs/stylex";
+import {
+	type PointerEvent,
+	type ReactNode,
+	useCallback,
+	useRef,
+	useState,
+} from "react";
+import { conditions } from "../../styles/conditions.stylex";
+import { duration } from "../../styles/motion.stylex";
+import { space } from "../../styles/spacing.stylex";
+import {
+	ChartTooltip,
+	type ChartTooltipItem,
+} from "../chart-tooltip/chart-tooltip";
+
+// Hover for charts drawn without the chart engine: the hovered item stays at
+// full strength while the rest recede, and a tooltip follows the pointer.
+
+export interface ChartHoverTip {
+	items: readonly ChartTooltipItem[];
+	label?: ReactNode;
+}
+
+interface HoverState {
+	flip: boolean;
+	id: string;
+	tip?: ChartHoverTip;
+	x: number;
+	y: number;
+}
+
+const styles = create({
+	// The focused item keeps full color while the rest recede, as on engine charts.
+	dim: { opacity: 0.3 },
+	host: { position: "relative" },
+	mark: {
+		transitionDuration: {
+			[conditions.reducedMotion]: duration.instant,
+			default: duration.fast,
+		},
+		transitionProperty: "opacity",
+	},
+	tip: (x: number, y: number, flip: boolean) => ({
+		insetBlockStart: y,
+		insetInlineStart: x,
+		pointerEvents: "none",
+		position: "absolute",
+		transform: flip
+			? `translate(calc(-100% - ${space["3"]}), -50%)`
+			: `translate(${space["3"]}, -50%)`,
+		// Small hosts such as rings must not squeeze the tooltip.
+		width: "max-content",
+		zIndex: 1,
+	}),
+});
+
+export function useChartHover() {
+	const hostRef = useRef<HTMLDivElement>(null);
+	const [hover, setHover] = useState<HoverState | null>(null);
+	const [linked, setLinked] = useState<string | null>(null);
+	/** Pointer handlers for a mark: hovering shows its tooltip. */
+	const markProps = useCallback(
+		(id: string, tip?: ChartHoverTip) => ({
+			onPointerLeave: () => setHover(null),
+			onPointerMove: (event: PointerEvent) => {
+				const box = hostRef.current?.getBoundingClientRect();
+				if (!box) {
+					return;
+				}
+				const x = event.clientX - box.left;
+				setHover({
+					flip: x > box.width / 2,
+					id,
+					tip,
+					x,
+					y: event.clientY - box.top,
+				});
+			},
+		}),
+		[]
+	);
+	/** Pointer handlers for a legend tile or row: hovering highlights its mark. */
+	const linkProps = useCallback(
+		(id: string) => ({
+			onPointerEnter: () => setLinked(id),
+			onPointerLeave: () => setLinked(null),
+		}),
+		[]
+	);
+	const active = hover?.id ?? linked;
+	/** StyleX styles for a mark or tile: it recedes while another item is active. */
+	const fade = useCallback(
+		(id: string) =>
+			[styles.mark, active !== null && active !== id && styles.dim] as const,
+		[active]
+	);
+	return {
+		active,
+		fade,
+		hostRef,
+		hostStyle: styles.host,
+		hover,
+		linkProps,
+		markProps,
+	};
+}
+
+export function ChartHoverTooltip({
+	hover,
+}: {
+	hover: { flip: boolean; tip?: ChartHoverTip; x: number; y: number } | null;
+}) {
+	if (!hover?.tip) {
+		return null;
+	}
+	return (
+		<div
+			aria-hidden="true"
+			{...props(styles.tip(hover.x, hover.y, hover.flip))}
+		>
+			<ChartTooltip items={hover.tip.items} label={hover.tip.label} />
+		</div>
+	);
+}

package/src/components/chart-frame/chart-loading.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import { create, keyframes, props } from "@stylexjs/stylex";
+import { useState } from "react";
+import { colors } from "../../styles/colors.stylex";
+import { conditions } from "../../styles/conditions.stylex";
+import { duration, easing } from "../../styles/motion.stylex";
+import { visuallyHiddenStyles } from "../visually-hidden/visually-hidden.styles";
+
+/** Whether a chart's data is still on its way. */
+export type ChartStatus = "loading" | "ready";
+
+const pulse = keyframes({
+	"0%, 100%": { opacity: 0.45 },
+	"50%": { opacity: 1 },
+});
+
+const wipe = keyframes({
+	from: { clipPath: "inset(0 100% 0 0)" },
+	to: { clipPath: "inset(0 0 0 0)" },
+});
+
+const wipeRtl = keyframes({
+	from: { clipPath: "inset(0 0 0 100%)" },
+	to: { clipPath: "inset(0 0 0 0)" },
+});
+
+const fade = keyframes({
+	from: { opacity: 0 },
+	to: { opacity: 1 },
+});
+
+const styles = create({
+	area: { fill: colors.chartReference, fillOpacity: 0.14 },
+	frame: (height: number) => ({ blockSize: height, position: "relative" }),
+	grid: { stroke: colors.chartReference, strokeOpacity: 0.35 },
+	line: { fill: "none", stroke: colors.chartReference, strokeOpacity: 0.45 },
+	silhouette: {
+		animationDuration: "1.6s",
+		animationIterationCount: "infinite",
+		animationName: { [conditions.reducedMotion]: "none", default: pulse },
+		animationTimingFunction: easing.easeInOut,
+	},
+	svg: { blockSize: "100%", display: "block", inlineSize: "100%" },
+});
+
+/** The plot of a chart whose data replaced its loading state wipes in. */
+export const chartRevealStyles = create({
+	reveal: {
+		animationDuration: {
+			[conditions.reducedMotion]: duration.fast,
+			default: "700ms",
+		},
+		animationFillMode: "both",
+		animationName: {
+			":dir(rtl)": wipeRtl,
+			[conditions.reducedMotion]: fade,
+			default: wipe,
+		},
+		animationTimingFunction: easing.expoOut,
+	},
+});
+
+/**
+ * True once data arrives after a loading state, so the plot can reveal. A
+ * chart that starts ready shows at once. State updates during render, so no
+ * effect is needed.
+ */
+export function useLoadingReveal(status: ChartStatus): boolean {
+	const [sawLoading, setSawLoading] = useState(status === "loading");
+	if (status === "loading" && !sawLoading) {
+		setSawLoading(true);
+	}
+	return sawLoading && status === "ready";
+}
+
+// A gentle rise across the plot reads as a chart without implying values.
+const LINE = "M0 30 C15 26 25 20 40 22 S65 12 80 14 S95 8 100 9";
+const AREA = `${LINE} L100 40 L0 40 Z`;
+const GRID_ROWS = [4, 16, 28, 40];
+
+/** A placeholder at the chart's own height while its data loads. */
+export function ChartLoading({
+	grid = true,
+	height,
+}: {
+	grid?: boolean;
+	height: number;
+}) {
+	return (
+		<div
+			data-slot="chart-loading"
+			role="status"
+			{...props(styles.frame(height))}
+		>
+			<svg
+				aria-hidden="true"
+				focusable="false"
+				preserveAspectRatio="none"
+				viewBox="0 0 100 40"
+				{...props(styles.svg)}
+			>
+				{grid
+					? GRID_ROWS.map((y) => (
+							<line
+								key={y}
+								strokeDasharray="3 3"
+								vectorEffect="non-scaling-stroke"
+								x1="0"
+								x2="100"
+								y1={y}
+								y2={y}
+								{...props(styles.grid)}
+							/>
+						))
+					: null}
+				<g {...props(styles.silhouette)}>
+					<path d={AREA} {...props(styles.area)} />
+					<path
+						d={LINE}
+						strokeWidth={2}
+						vectorEffect="non-scaling-stroke"
+						{...props(styles.line)}
+					/>
+				</g>
+			</svg>
+			<span {...props(visuallyHiddenStyles.root)}>Loading chart</span>
+		</div>
+	);
+}