@mizen-labs/ui 0.0.0-stage → 0.1.0

package/src/components/heatmap/heatmap.tsx

@@ -0,0 +1,402 @@
+"use client";
+
+import { create, props } from "@stylexjs/stylex";
+import { cell, defineChart } from "@tanstack/charts";
+import type { ChartTooltipBodyRenderContext } from "@tanstack/charts/react/tooltip";
+import { scaleBand } from "@tanstack/charts/scales/band";
+import { tooltip as tooltipFeature } from "@tanstack/charts/tooltip";
+import type { ComponentPropsWithRef } from "react";
+import { useMemo } from "react";
+import type { Closed } from "../../closed";
+import { typeRoles } from "../../styles/typography.styles";
+import { type ChartSeriesTone, chartColors } from "../chart-frame/chart-colors";
+import { ChartDataTable } from "../chart-frame/chart-data-table";
+import { ChartFrame } from "../chart-frame/chart-frame";
+import { ChartTooltip } from "../chart-tooltip/chart-tooltip";
+import {
+	Table,
+	TableBody,
+	TableCaption,
+	TableCell,
+	TableContainer,
+	TableHead,
+	TableHeader,
+	TableRow,
+} from "../table/table";
+import {
+	COLOR_DOMAIN,
+	colorRange,
+	getBucket,
+	HeatmapLegend,
+} from "./heatmap-scale";
+
+export interface HeatmapRow {
+	label: string;
+	values: readonly (number | null)[];
+}
+
+export type HeatmapProps = Omit<
+	Closed<ComponentPropsWithRef<"div">>,
+	"aria-label" | "children" | "data-slot" | "role"
+> & {
+	"aria-label": string;
+	columns: readonly string[];
+	formatValue?: (value: number) => string;
+	max?: number;
+	rows: readonly HeatmapRow[];
+	tone?: ChartSeriesTone;
+	valueLabel?: string;
+};
+
+interface HeatmapCell {
+	colorKey: "missing" | number;
+	column: string;
+	row: string;
+	value: number | null;
+}
+
+const styles = create({
+	// Cells stay compact: each column gets at most 2.25rem, plus room for row labels.
+	plot: (columnCount: number) => ({
+		maxInlineSize: `calc(${columnCount} * 2.25rem + 6rem)`,
+	}),
+	root: { minWidth: 0 },
+});
+
+function requireLabel(label: string, name: string, seen: Set<string>) {
+	if (typeof label !== "string" || !label.trim()) {
+		throw new TypeError(`Heatmap ${name} labels must be non-empty strings.`);
+	}
+	if (seen.has(label)) {
+		throw new RangeError(`Heatmap ${name} labels must be unique.`);
+	}
+	seen.add(label);
+}
+
+function assertUniqueLabels(labels: readonly string[], name: string) {
+	const seen = new Set<string>();
+	for (const label of labels) {
+		requireLabel(label, name, seen);
+	}
+}
+
+function isArray(value: unknown): boolean {
+	return Array.isArray(value);
+}
+
+function assertRows(rows: readonly HeatmapRow[], columnCount: number) {
+	const seen = new Set<string>();
+	for (const row of rows) {
+		requireLabel(row?.label, "row", seen);
+		if (!isArray(row.values) || row.values.length !== columnCount) {
+			throw new RangeError("Heatmap rows must match the column count.");
+		}
+	}
+}
+
+function assertValues(rows: readonly HeatmapRow[]) {
+	let maximum = 0;
+	for (const row of rows) {
+		for (const value of row.values) {
+			if (value === null) {
+				continue;
+			}
+			if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+				throw new RangeError(
+					"Heatmap values must be finite non-negative numbers or null."
+				);
+			}
+			maximum = Math.max(maximum, value);
+		}
+	}
+	return maximum;
+}
+
+function assertMaximum(max: number | undefined) {
+	if (
+		max !== undefined &&
+		(typeof max !== "number" || !Number.isFinite(max) || max < 0)
+	) {
+		throw new RangeError("Heatmap max must be a finite non-negative number.");
+	}
+}
+
+function prepareCells(
+	columns: readonly string[],
+	rows: readonly HeatmapRow[],
+	max: number | undefined
+) {
+	if (!(isArray(columns) && isArray(rows))) {
+		throw new TypeError("Heatmap columns and rows must be arrays.");
+	}
+	assertMaximum(max);
+	assertUniqueLabels(columns, "column");
+	assertRows(rows, columns.length);
+	const observedMax = assertValues(rows);
+	const maximum = max ?? observedMax;
+	if (max === 0 && observedMax > 0) {
+		throw new RangeError(
+			"Heatmap max must be greater than zero when values are positive."
+		);
+	}
+	return {
+		cells: rows.flatMap(({ label, values }) =>
+			values.map((value, index) => {
+				const colorKey: HeatmapCell["colorKey"] =
+					value === null ? "missing" : getBucket(value, maximum);
+				return { colorKey, column: columns[index], row: label, value };
+			})
+		),
+		maximum,
+	};
+}
+
+function formatValue(
+	value: number,
+	formatter: ((value: number) => string) | undefined
+) {
+	const formatted = formatter ? formatter(value) : String(value);
+	if (typeof formatted !== "string") {
+		throw new TypeError("Heatmap formatValue must return a string.");
+	}
+	return formatted;
+}
+
+function assertProps(
+	ariaLabel: string,
+	valueLabel: string,
+	formatter: ((value: number) => string) | undefined,
+	tone: ChartSeriesTone
+) {
+	if (
+		typeof ariaLabel !== "string" ||
+		!ariaLabel.trim() ||
+		typeof valueLabel !== "string" ||
+		!valueLabel.trim()
+	) {
+		throw new TypeError(
+			"Heatmap requires non-empty aria-label and valueLabel strings."
+		);
+	}
+	if (formatter !== undefined && typeof formatter !== "function") {
+		throw new TypeError("Heatmap formatValue must be a function.");
+	}
+	if (!Object.hasOwn(chartColors, tone)) {
+		throw new RangeError("Heatmap tone is not supported.");
+	}
+}
+
+function stripReservedProps(attributes: Record<string, unknown>) {
+	for (const name of [
+		"aria-label",
+		"children",
+		"className",
+		"data-slot",
+		"role",
+		"style",
+	]) {
+		Reflect.deleteProperty(attributes, name);
+	}
+}
+
+function renderTooltip(
+	context: ChartTooltipBodyRenderContext<HeatmapCell, string, string>,
+	valueLabel: string,
+	tone: ChartSeriesTone,
+	formatter: ((value: number) => string) | undefined
+) {
+	const point = context.primaryPoint ?? context.points[0];
+	if (!point) {
+		return null;
+	}
+	const { column, row, value } = point.datum;
+	return (
+		<ChartTooltip
+			items={[
+				{
+					id: "heatmap-value",
+					label: valueLabel,
+					tone,
+					value: value === null ? "No data" : formatValue(value, formatter),
+				},
+			]}
+			label={`${row} · ${column}`}
+		/>
+	);
+}
+
+function HeatmapTable({
+	"aria-label": ariaLabel,
+	columns,
+	formatValue: formatter,
+	rows,
+}: Pick<HeatmapProps, "aria-label" | "columns" | "formatValue" | "rows">) {
+	return (
+		<ChartDataTable>
+			<TableContainer aria-label={`${ariaLabel} data`}>
+				<Table>
+					<TableCaption>{ariaLabel} values</TableCaption>
+					<TableHeader sticky={false}>
+						<TableRow>
+							<TableHead scope="col">Row</TableHead>
+							{columns.map((column) => (
+								<TableHead key={column}>{column}</TableHead>
+							))}
+						</TableRow>
+					</TableHeader>
+					<TableBody>
+						{rows.map(({ label, values }) => (
+							<TableRow key={label}>
+								<TableHead scope="row">{label}</TableHead>
+								{values.map((value, index) => (
+									<TableCell key={columns[index]} numeric>
+										{value === null ? (
+											"No data"
+										) : (
+											<data value={value}>{formatValue(value, formatter)}</data>
+										)}
+									</TableCell>
+								))}
+							</TableRow>
+						))}
+					</TableBody>
+				</Table>
+			</TableContainer>
+		</ChartDataTable>
+	);
+}
+
+function HeatmapChart({
+	"aria-label": ariaLabel,
+	columns,
+	cells,
+	formatValue: formatter,
+	maximum,
+	rows,
+	tone,
+	valueLabel,
+}: {
+	"aria-label": string;
+	columns: readonly string[];
+	cells: readonly HeatmapCell[];
+	formatValue?: (value: number) => string;
+	maximum: number;
+	rows: readonly HeatmapRow[];
+	tone: ChartSeriesTone;
+	valueLabel: string;
+}) {
+	const definition = useMemo(
+		() =>
+			defineChart(
+				{
+					color: { domain: COLOR_DOMAIN, range: colorRange(tone) },
+					marks: [
+						cell(cells, {
+							color: "colorKey",
+							id: "heatmap-cells",
+							inset: 1.5,
+							key: ({ row, column }) => JSON.stringify([row, column]),
+							radius: 4,
+							x: "column",
+							y: "row",
+						}),
+					],
+					scales: {
+						x: {
+							scale: scaleBand<string>()
+								.domain(columns)
+								.paddingInner(0.1)
+								.paddingOuter(0),
+						},
+						y: {
+							scale: scaleBand<string>()
+								.domain(rows.map(({ label }) => label))
+								.paddingInner(0.1)
+								.paddingOuter(0),
+						},
+					},
+				},
+				{ tooltip: tooltipFeature }
+			),
+		[cells, columns, rows, tone]
+	);
+	const renderTooltipBody = useMemo(
+		() =>
+			(context: ChartTooltipBodyRenderContext<HeatmapCell, string, string>) =>
+				renderTooltip(context, valueLabel, tone, formatter),
+		[formatter, tone, valueLabel]
+	);
+
+	return (
+		<div {...props(styles.plot(columns.length))}>
+			<ChartFrame
+				aria-label={ariaLabel}
+				definition={definition}
+				height={rows.length * 30 + 40}
+				renderTooltipBody={renderTooltipBody}
+				tabIndex={0}
+			/>
+			<HeatmapLegend
+				high={formatValue(maximum, formatter)}
+				tone={tone}
+				valueLabel={valueLabel}
+			/>
+		</div>
+	);
+}
+
+export function Heatmap({
+	"aria-label": ariaLabel,
+	columns,
+	formatValue: formatter,
+	max,
+	ref: forwardedRef,
+	rows,
+	tone = "series1",
+	valueLabel = "Value",
+	...rest
+}: HeatmapProps) {
+	assertProps(ariaLabel, valueLabel, formatter, tone);
+	const { cells, maximum } = useMemo(
+		() => prepareCells(columns, rows, max),
+		[columns, max, rows]
+	);
+	stripReservedProps(rest);
+
+	return (
+		<div
+			{...rest}
+			data-slot="heatmap"
+			ref={forwardedRef}
+			{...props(styles.root)}
+		>
+			{rows.length === 0 || columns.length === 0 ? (
+				// biome-ignore lint/a11y/useSemanticElements: Names an empty chart, not a form group; the status keeps its own text.
+				<div aria-label={ariaLabel} role="group">
+					<p role="status" {...props(typeRoles.body)}>
+						No data available.
+					</p>
+				</div>
+			) : (
+				<>
+					<HeatmapChart
+						aria-label={ariaLabel}
+						cells={cells}
+						columns={columns}
+						formatValue={formatter}
+						maximum={maximum}
+						rows={rows}
+						tone={tone}
+						valueLabel={valueLabel}
+					/>
+					<HeatmapTable
+						aria-label={ariaLabel}
+						columns={columns}
+						formatValue={formatter}
+						rows={rows}
+					/>
+				</>
+			)}
+		</div>
+	);
+}

package/src/components/inline/inline.styles.ts

@@ -0,0 +1,13 @@
+import { create } from "@stylexjs/stylex";
+import { space } from "../../styles/spacing.stylex";
+
+export const inlineStyles = create({
+	base: {
+		alignItems: "center",
+		display: "flex",
+		flexDirection: "row",
+		flexWrap: "wrap",
+		gap: space["3"],
+		minWidth: 0,
+	},
+});

package/src/components/inline/inline.tsx

@@ -0,0 +1,22 @@
+import { props } from "@stylexjs/stylex";
+import type { ComponentPropsWithRef } from "react";
+import { inlineStyles } from "./inline.styles";
+
+type NativeDivProps = ComponentPropsWithRef<"div">;
+
+export type InlineProps = Omit<NativeDivProps, "className" | "role" | "style">;
+
+export function Inline({ children, ref: forwardedRef, ...rest }: InlineProps) {
+	Reflect.deleteProperty(rest, "role");
+
+	return (
+		<div
+			{...rest}
+			data-slot="inline"
+			ref={forwardedRef}
+			{...props(inlineStyles.base)}
+		>
+			{children}
+		</div>
+	);
+}

package/src/components/inline-citation/citation-source.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import { props } from "@stylexjs/stylex";
+import { useCallback, useState } from "react";
+import { IconFile, IconWorld } from "../../icons";
+import { inlineCitationStyles as styles } from "./inline-citation.styles";
+
+/**
+ * A cited source. With `href` it is a link labelled by its domain, and the
+ * title is optional. Without one, such as an uploaded document, it needs a
+ * title and shows as text.
+ */
+export type CitationSource = {
+	/** One line on what the source says, shown in its preview. */
+	description?: string;
+	/**
+	 * A small square image. Defaults to the site's own `/favicon.ico`; a
+	 * globe stands in when there is none.
+	 */
+	icon?: string;
+} & ({ href: string; title?: string } | { href?: undefined; title: string });
+
+const LEADING_WWW = /^www\./u;
+// Reserved for examples and tests (RFC 2606); they never serve an icon.
+const RESERVED_HOST =
+	/(?:^|\.)(?:example\.(?:com|net|org)|example|test|invalid|localhost)$/u;
+
+function sourceDomain(href: string) {
+	return URL.canParse(href)
+		? new URL(href).hostname.replace(LEADING_WWW, "")
+		: href;
+}
+
+/** What the chip shows: the domain of a link, or the title of a document. */
+export function sourceLabel(source: CitationSource) {
+	return source.href === undefined ? source.title : sourceDomain(source.href);
+}
+
+/** The fullest name available: the title, or the domain without one. */
+export function sourceName(source: CitationSource) {
+	return source.title ?? sourceLabel(source);
+}
+
+// The site's own icon, so no third-party service learns what was cited.
+function faviconOf(source: CitationSource) {
+	if (source.icon) {
+		return source.icon;
+	}
+	if (source.href === undefined || !URL.canParse(source.href)) {
+		return;
+	}
+	const url = new URL(source.href);
+	const web = url.protocol === "https:" || url.protocol === "http:";
+	return web && !RESERVED_HOST.test(url.hostname)
+		? `${url.origin}/favicon.ico`
+		: undefined;
+}
+
+export function SourceIcon({ source }: { source: CitationSource }) {
+	const src = faviconOf(source);
+	const [failed, setFailed] = useState<string | null>(null);
+	const fail = useCallback(() => setFailed(src ?? null), [src]);
+	// A server-rendered icon can fail before hydration, when no handler is
+	// attached yet; a finished image with no width has failed.
+	const check = useCallback(
+		(image: HTMLImageElement | null) => {
+			if (image?.complete && image.naturalWidth === 0) {
+				fail();
+			}
+		},
+		[fail]
+	);
+	if (source.href === undefined && !source.icon) {
+		// A document, such as a file from the person's workspace.
+		return (
+			<IconFile
+				aria-hidden="true"
+				size={12}
+				{...props(styles.faviconFallback)}
+			/>
+		);
+	}
+	if (!src || failed === src) {
+		return (
+			<IconWorld
+				aria-hidden="true"
+				size={12}
+				{...props(styles.faviconFallback)}
+			/>
+		);
+	}
+	return (
+		// biome-ignore lint/performance/noImgElement: Mizen stays framework-neutral, so it uses a native image.
+		// biome-ignore lint/correctness/useImageSize: the icon is a fixed 12px square set in styles.
+		// biome-ignore lint/a11y/noNoninteractiveElementInteractions: onError swaps in the globe when a site has no icon; it is not an interaction.
+		<img
+			alt=""
+			onError={fail}
+			ref={check}
+			referrerPolicy="no-referrer"
+			src={src}
+			{...props(styles.favicon)}
+		/>
+	);
+}

package/src/components/inline-citation/inline-citation.styles.ts

@@ -0,0 +1,94 @@
+import { create } from "@stylexjs/stylex";
+import { colors } from "../../styles/colors.stylex";
+import { conditions } from "../../styles/conditions.stylex";
+import { borderWidth } from "../../styles/interaction.stylex";
+import { shape } from "../../styles/shape.stylex";
+import { space } from "../../styles/spacing.stylex";
+
+export const inlineCitationStyles = create({
+	// The preview: site, title, then one line on what it says.
+	card: {
+		display: "flex",
+		flexDirection: "column",
+		gap: space["1"],
+		inlineSize: "18rem",
+		maxInlineSize: "100%",
+	},
+	cardDescription: { color: colors.mutedContent, margin: 0 },
+	// Text sits 16px from the sides, as in a menu, and 12px from the ends.
+	cardPopup: { paddingBlock: space["3"], paddingInline: space["4"] },
+	cardSite: {
+		alignItems: "center",
+		color: colors.mutedContent,
+		display: "flex",
+		gap: space["1"],
+	},
+	cardTitle: { color: colors.content, margin: 0 },
+	// A quiet chip in the sentence: favicon and site, or the first site and
+	// a count when several sources back the same point.
+	//
+	// The visible chip is 16px, painted on ::before; the element around it is
+	// a 24px target. Negative margins take the extra 4px on each side back,
+	// so the line keeps its height and the text its spacing.
+	chip: {
+		"::before": {
+			backgroundColor: {
+				[conditions.canHover]: {
+					":hover": colors.controlSurfaceHover,
+					default: colors.controlSurface,
+				},
+				default: colors.controlSurface,
+			},
+			borderRadius: shape.inlineRadius,
+			content: '""',
+			inset: space["1"],
+			position: "absolute",
+			zIndex: -1,
+		},
+		alignItems: "center",
+		appearance: "none",
+		backgroundColor: "transparent",
+		borderRadius: `calc(${shape.inlineRadius} + ${space["1"]})`,
+		borderWidth: 0,
+		color: { ":hover": colors.content, default: colors.mutedContent },
+		cursor: "pointer",
+		display: "inline-flex",
+		fontFamily: "inherit",
+		gap: space["1"],
+		isolation: "isolate",
+		margin: `calc(-1 * ${space["1"]})`,
+		// The text after a citation brings its own space; this one is the
+		// 4px before it, net of the target's inset.
+		marginInlineStart: 0,
+		outlineColor: {
+			":focus-visible": colors.focusRing,
+			default: "transparent",
+		},
+		outlineOffset: -2,
+		outlineStyle: { ":focus-visible": "solid", default: "none" },
+		outlineWidth: borderWidth.focus,
+		padding: space["1"],
+		paddingInline: `calc(${space["1"]} * 2)`,
+		position: "relative",
+		textDecoration: "none",
+		verticalAlign: "0.1em",
+		whiteSpace: "nowrap",
+	},
+	// A document has nothing to open, so it does not invite a click.
+	chipStatic: { cursor: "default" },
+	count: { fontVariantNumeric: "tabular-nums" },
+	favicon: {
+		blockSize: 12,
+		borderRadius: 3,
+		display: "block",
+		flexShrink: 0,
+		inlineSize: 12,
+		objectFit: "cover",
+	},
+	// A globe, or a file for a document, stands in without an icon.
+	faviconFallback: { color: colors.mutedContent, flexShrink: 0 },
+	// Several sources behind one chip, listed like Sources.
+	group: { inlineSize: "22rem", maxInlineSize: "100%" },
+	// The popup's 8px inset plus each row's padding puts text 16px in.
+	listPopup: { padding: space["2"] },
+});