@mizen-labs/ui 0.0.0-stage → 0.1.0

package/src/components/part-to-whole/part-to-whole.tsx

@@ -0,0 +1,329 @@
+"use client";
+
+import { props } from "@stylexjs/stylex";
+import { defineChart } from "@tanstack/charts";
+import { focusGroupAngle, pie, polar, radialArc } from "@tanstack/charts/polar";
+import type { ChartTooltipBodyRenderContext } from "@tanstack/charts/react/tooltip";
+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 { ChartFrame } from "../chart-frame/chart-frame";
+import {
+	ChartLegend,
+	type ChartLegendItem,
+} from "../chart-legend/chart-legend";
+import { ChartTooltip } from "../chart-tooltip/chart-tooltip";
+import { partToWholeStyles } from "./part-to-whole.styles";
+
+export interface PartToWholePart {
+	id: string;
+	label: string;
+	value: number;
+}
+
+export type PartToWholeProps = Omit<
+	Closed<ComponentPropsWithRef<"div">>,
+	"aria-label" | "children" | "data-slot" | "role"
+> & {
+	"aria-description"?: string;
+	"aria-label": string;
+	formatValue?: (value: number) => string;
+	locale?: string;
+	/** Up to six parts; fold the rest into "Other". */
+	parts: readonly PartToWholePart[];
+	/** Caption under the total in the donut's center. */
+	totalLabel?: string;
+};
+
+interface PreparedPart extends PartToWholePart {
+	rawValue: number;
+	share: number;
+	tone: ChartSeriesTone;
+}
+
+interface PartToWholeChartProps {
+	"aria-description"?: string;
+	"aria-label": string;
+	formatValue: (value: number) => string;
+	legendItems: readonly ChartLegendItem[];
+	parts: readonly PreparedPart[];
+	shareFormat: Intl.NumberFormat;
+	totalLabel: string;
+}
+
+function validatePart(part: PartToWholePart, ids: Set<string>) {
+	if (
+		typeof part.id !== "string" ||
+		!part.id.trim() ||
+		typeof part.label !== "string" ||
+		!part.label.trim()
+	) {
+		throw new TypeError("PartToWhole parts require non-empty ids and labels.");
+	}
+	if (ids.has(part.id)) {
+		throw new RangeError("PartToWhole part ids must be unique.");
+	}
+	if (
+		typeof part.value !== "number" ||
+		!Number.isFinite(part.value) ||
+		part.value < 0
+	) {
+		throw new RangeError("PartToWhole values must be finite and non-negative.");
+	}
+	ids.add(part.id);
+}
+
+function prepareParts(parts: readonly PartToWholePart[]): PreparedPart[] {
+	if (!Array.isArray(parts)) {
+		throw new TypeError("PartToWhole parts must be an array.");
+	}
+	if (parts.length > 6) {
+		throw new RangeError(
+			'PartToWhole supports up to six parts; fold the rest into "Other".'
+		);
+	}
+	const ids = new Set<string>();
+	let maximum = 0;
+	for (const part of parts) {
+		validatePart(part, ids);
+		maximum = Math.max(maximum, part.value);
+	}
+	const scaledTotal =
+		maximum === 0
+			? 0
+			: parts.reduce((sum, part) => sum + part.value / maximum, 0);
+	return parts.map((part, index) => ({
+		...part,
+		rawValue: part.value,
+		share: scaledTotal === 0 ? 0 : part.value / maximum / scaledTotal,
+		tone: `series${index + 1}` as ChartSeriesTone,
+	}));
+}
+
+function assertProps(
+	ariaLabel: string,
+	locale: string,
+	formatValue: PartToWholeProps["formatValue"]
+) {
+	if (typeof ariaLabel !== "string" || !ariaLabel.trim()) {
+		throw new TypeError("PartToWhole requires a non-empty aria-label.");
+	}
+	if (typeof locale !== "string" || !locale.trim()) {
+		throw new TypeError("PartToWhole locale must be a non-empty string.");
+	}
+	if (formatValue !== undefined && typeof formatValue !== "function") {
+		throw new TypeError("PartToWhole formatValue must be a function.");
+	}
+}
+
+function formatNumber(value: number, formatValue: (value: number) => string) {
+	const formatted = formatValue(value);
+	if (typeof formatted !== "string") {
+		throw new TypeError("PartToWhole formatValue must return a string.");
+	}
+	return formatted;
+}
+
+function renderTooltip(
+	context: ChartTooltipBodyRenderContext<PreparedPart, number, number>,
+	formatValue: (value: number) => string,
+	shareFormat: Intl.NumberFormat
+) {
+	const point = context.primaryPoint ?? context.points[0];
+	if (!point) {
+		return null;
+	}
+	return (
+		<ChartTooltip
+			items={[
+				{
+					id: `part-${point.datum.id}`,
+					label: point.datum.label,
+					tone: point.datum.tone,
+					value: `${formatNumber(point.datum.rawValue, formatValue)} · ${shareFormat.format(point.datum.share)}`,
+				},
+			]}
+		/>
+	);
+}
+
+function PartToWholeChart({
+	"aria-description": ariaDescription,
+	"aria-label": ariaLabel,
+	formatValue,
+	legendItems,
+	shareFormat,
+	parts,
+	totalLabel,
+}: PartToWholeChartProps) {
+	const definition = useMemo(() => {
+		const positiveParts = parts.filter(({ value }) => value > 0);
+		const arcs = pie(positiveParts, { value: "share" });
+		return defineChart(
+			{
+				marks: [
+					polar({
+						inset: 12,
+						marks: [
+							radialArc(arcs, {
+								cornerRadius: 4,
+								fill: ({ tone }) => chartColors[tone],
+								id: "part-to-whole-arcs",
+								innerRadius: ({ radius }) => radius * 0.74,
+								key: ({ id }) => id,
+								// A thin surface gap separates neighboring segments.
+								padAngle: () => (positiveParts.length > 1 ? 0.03 : 0),
+							}),
+						],
+						scales: { angle: null, radius: null },
+					}),
+				],
+				scales: { x: null, y: null },
+			},
+			{ focus: focusGroupAngle, tooltip: tooltipFeature }
+		);
+	}, [parts]);
+	const renderTooltipBody = useMemo(
+		() =>
+			(context: ChartTooltipBodyRenderContext<PreparedPart, number, number>) =>
+				renderTooltip(context, formatValue, shareFormat),
+		[formatValue, shareFormat]
+	);
+	const total = parts.reduce((sum, { rawValue }) => sum + rawValue, 0);
+	return (
+		<div data-slot="part-to-whole-chart" {...props(partToWholeStyles.chart)}>
+			<div {...props(partToWholeStyles.plot)}>
+				<ChartFrame
+					aria-description={ariaDescription}
+					aria-label={ariaLabel}
+					definition={definition}
+					height={240}
+					renderTooltipBody={renderTooltipBody}
+					tabIndex={0}
+				/>
+				<div
+					aria-hidden="true"
+					data-slot="part-to-whole-total"
+					{...props(partToWholeStyles.total)}
+				>
+					<span {...props(typeRoles.numeric)}>
+						{formatNumber(total, formatValue)}
+					</span>
+					<span {...props(typeRoles.caption, partToWholeStyles.share)}>
+						{totalLabel}
+					</span>
+				</div>
+			</div>
+			<div
+				data-slot="part-to-whole-legend"
+				{...props(partToWholeStyles.legend)}
+			>
+				<ChartLegend aria-label={`${ariaLabel} parts`} items={legendItems} />
+			</div>
+		</div>
+	);
+}
+
+export function PartToWhole({
+	"aria-description": ariaDescription,
+	"aria-label": ariaLabel,
+	formatValue: formatValueProp,
+	locale = "en-US",
+	parts: inputParts,
+	ref: forwardedRef,
+	totalLabel = "Total",
+	...rest
+}: PartToWholeProps) {
+	assertProps(ariaLabel, locale, formatValueProp);
+	const numberFormat = useMemo(
+		() => new Intl.NumberFormat(locale, { maximumSignificantDigits: 21 }),
+		[locale]
+	);
+	const formatValue = useMemo(
+		() => formatValueProp ?? numberFormat.format,
+		[formatValueProp, numberFormat]
+	);
+	const parts = useMemo(() => prepareParts(inputParts), [inputParts]);
+	const hasPositivePart = parts.some(({ value }) => value > 0);
+	const shareFormat = useMemo(
+		() =>
+			new Intl.NumberFormat(locale, {
+				maximumSignificantDigits: 3,
+				style: "percent",
+			}),
+		[locale]
+	);
+	const legendItems = useMemo(
+		() =>
+			parts.map(({ id, label, share, tone, value }) => ({
+				id: `part-${id}`,
+				label: (
+					<span {...props(partToWholeStyles.label)}>
+						<span>{label}</span>{" "}
+						<span>
+							<span {...props(partToWholeStyles.value)}>
+								{formatNumber(value, formatValue)}
+							</span>{" "}
+							<span {...props(partToWholeStyles.share)}>
+								{shareFormat.format(share)}
+							</span>
+						</span>
+					</span>
+				),
+				tone,
+			})),
+		[formatValue, parts, shareFormat]
+	);
+	for (const name of [
+		"aria-label",
+		"children",
+		"className",
+		"data-slot",
+		"role",
+		"style",
+	]) {
+		Reflect.deleteProperty(rest, name);
+	}
+
+	return (
+		<div
+			{...rest}
+			data-slot="part-to-whole"
+			ref={forwardedRef}
+			{...props(partToWholeStyles.root)}
+		>
+			{parts.length === 0 || !hasPositivePart ? (
+				<>
+					<p
+						aria-label={ariaLabel}
+						role="status"
+						{...props(typeRoles.body, partToWholeStyles.empty)}
+					>
+						{parts.length === 0
+							? "No parts available."
+							: "All parts have a value of zero."}
+					</p>
+					{parts.length > 0 ? (
+						<ChartLegend
+							aria-label={`${ariaLabel} parts`}
+							items={legendItems}
+						/>
+					) : null}
+				</>
+			) : (
+				<PartToWholeChart
+					aria-description={ariaDescription}
+					aria-label={ariaLabel}
+					formatValue={formatValue}
+					legendItems={legendItems}
+					parts={parts}
+					shareFormat={shareFormat}
+					totalLabel={totalLabel}
+				/>
+			)}
+		</div>
+	);
+}

package/src/components/popover/popover.styles.ts

@@ -0,0 +1,177 @@
+import { create } from "@stylexjs/stylex";
+import { colors } from "../../styles/colors.stylex";
+import { conditions } from "../../styles/conditions.stylex";
+import { borderWidth } from "../../styles/interaction.stylex";
+import { duration, easing } from "../../styles/motion.stylex";
+import { shadows } from "../../styles/shadows.stylex";
+import { shape } from "../../styles/shape.stylex";
+import { space } from "../../styles/spacing.stylex";
+import {
+	fontSize,
+	fontWeight,
+	letterSpacing,
+	lineHeight,
+} from "../../styles/typography.stylex";
+
+export const popoverStyles = create({
+	description: {
+		color: colors.mutedContent,
+		fontSize: fontSize["14"],
+		fontWeight: fontWeight.regular,
+		lineHeight: lineHeight["20"],
+		marginBlockEnd: 0,
+		// A description right after its title sits 4px below it, not at the
+		// 16px content gap.
+		marginBlockStart: {
+			":is([data-slot='popover-title'] + *)": `calc(${space["1"]} - ${space["4"]})`,
+			default: 0,
+		},
+		overflowWrap: "anywhere",
+	},
+	popup: {
+		backgroundColor: colors.floatingSurface,
+		borderColor: {
+			[conditions.moreContrast]: colors.controlBorderStrong,
+			default: colors.border,
+		},
+		borderRadius: shape.floatingRadius,
+		borderStyle: "solid",
+		borderWidth: borderWidth.thin,
+		boxShadow: shadows.floating,
+		boxSizing: "border-box",
+		color: colors.content,
+		display: "flex",
+		flexDirection: "column",
+		height: "var(--popup-height, auto)",
+		maxWidth: "min(var(--available-width), calc(100vw - 2rem))",
+		opacity: {
+			"[data-ending-style]": 0,
+			"[data-starting-style]": 0,
+			default: 1,
+		},
+		outline: "none",
+		position: "relative",
+		transform: {
+			"[data-ending-style][data-side='bottom']":
+				"translateY(-0.25rem) scale(0.98)",
+			"[data-ending-style][data-side='inline-end']":
+				"translateX(-0.25rem) scale(0.98)",
+			"[data-ending-style][data-side='inline-start']":
+				"translateX(0.25rem) scale(0.98)",
+			"[data-ending-style][data-side='left']":
+				"translateX(0.25rem) scale(0.98)",
+			"[data-ending-style][data-side='right']":
+				"translateX(-0.25rem) scale(0.98)",
+			"[data-ending-style][data-side='top']": "translateY(0.25rem) scale(0.98)",
+			"[data-starting-style][data-side='bottom']":
+				"translateY(-0.25rem) scale(0.98)",
+			"[data-starting-style][data-side='inline-end']":
+				"translateX(-0.25rem) scale(0.98)",
+			"[data-starting-style][data-side='inline-start']":
+				"translateX(0.25rem) scale(0.98)",
+			"[data-starting-style][data-side='left']":
+				"translateX(0.25rem) scale(0.98)",
+			"[data-starting-style][data-side='right']":
+				"translateX(-0.25rem) scale(0.98)",
+			"[data-starting-style][data-side='top']":
+				"translateY(0.25rem) scale(0.98)",
+			default: "none",
+		},
+		transformOrigin: "var(--transform-origin)",
+		transitionDuration: {
+			[conditions.reducedMotion]: duration.instant,
+			"[data-ending-style]": duration.overlayExit,
+			"[data-instant]": duration.instant,
+			default: duration.overlayEnter,
+		},
+		transitionProperty: "width, height, opacity, transform",
+		transitionTimingFunction: easing.expoOut,
+		width: "var(--popup-width, 18rem)",
+	},
+	popupBare: {
+		backgroundColor: "transparent",
+		borderColor: "transparent",
+		borderStyle: "none",
+		borderWidth: 0,
+		boxShadow: "none",
+		gap: space["0"],
+		padding: space["0"],
+	},
+	popupTooltip: {
+		borderRadius: shape.controlRadius,
+		fontSize: fontSize["12"],
+		width: "var(--popup-width, max-content)",
+	},
+	positioner: {
+		height: "var(--positioner-height)",
+		maxWidth: "min(var(--available-width), calc(100vw - 2rem))",
+		transitionDuration: {
+			[conditions.reducedMotion]: duration.instant,
+			"[data-instant]": duration.instant,
+			default: duration.overlayEnter,
+		},
+		transitionProperty: "top, left, right, bottom, transform",
+		transitionTimingFunction: easing.expoOut,
+		width: "var(--positioner-width)",
+		zIndex: 50,
+	},
+	positionerBare: {
+		width: "auto",
+	},
+	title: {
+		color: colors.content,
+		fontSize: fontSize["16"],
+		fontWeight: fontWeight.semibold,
+		letterSpacing: letterSpacing.subheading,
+		lineHeight: lineHeight["24"],
+		marginBlock: 0,
+		overflowWrap: "anywhere",
+	},
+	viewport: {
+		boxSizing: "border-box",
+		display: "flex",
+		flexDirection: "column",
+		gap: space["4"],
+		height: "100%",
+		maxHeight: "var(--available-height)",
+		overflowX: "clip",
+		overflowY: { "[data-transitioning]": "clip", default: "auto" },
+		overscrollBehavior: "contain",
+		// Compact floating surface: 16px inset, subheading title.
+		padding: space["4"],
+		position: "relative",
+		width: "100%",
+	},
+	viewportBare: { gap: 0, padding: 0 },
+	viewportContent: {
+		display: { ":is(*) > :is([data-current], [data-previous])": "flex" },
+		flexDirection: {
+			":is(*) > :is([data-current], [data-previous])": "column",
+		},
+		gap: { ":is(*) > :is([data-current], [data-previous])": space["4"] },
+		opacity: {
+			":is(*) > :is([data-current], [data-previous])": 1,
+			":is(*) > :is([data-current], [data-previous]):is([data-starting-style], [data-ending-style])": 0,
+		},
+		transitionDuration: {
+			[conditions.reducedMotion]: {
+				":is(*) > :is([data-current], [data-previous])": duration.instant,
+			},
+			":is(*) > :is([data-current], [data-previous])": duration.overlayEnter,
+		},
+		transitionProperty: {
+			":is(*) > :is([data-current], [data-previous])": "opacity",
+		},
+	},
+	viewportContentBare: {
+		gap: { ":is(*) > :is([data-current], [data-previous])": 0 },
+	},
+	viewportContentTooltip: {
+		gap: { ":is(*) > :is([data-current], [data-previous])": space["1"] },
+	},
+	viewportTooltip: {
+		gap: space["1"],
+		paddingBlock: space["1"],
+		paddingInline: space["3"],
+	},
+});

package/src/components/popover/popover.tsx

@@ -0,0 +1,197 @@
+"use client";
+
+import {
+	Popover as BasePopover,
+	type PopoverCloseProps as BasePopoverCloseProps,
+	type PopoverDescriptionProps as BasePopoverDescriptionProps,
+	type PopoverPopupProps as BasePopoverPopupProps,
+	type PopoverPortalProps as BasePopoverPortalProps,
+	type PopoverPositionerProps as BasePopoverPositionerProps,
+	type PopoverRootProps as BasePopoverRootProps,
+	type PopoverTitleProps as BasePopoverTitleProps,
+	type PopoverTriggerProps as BasePopoverTriggerProps,
+} from "@base-ui/react/popover";
+import { props } from "@stylexjs/stylex";
+import type { ComponentPropsWithRef } from "react";
+import type { Closed } from "../../closed";
+import { protectRenderSlot } from "../../render-utils";
+import { popoverStyles } from "./popover.styles";
+
+type PopoverTriggerRef = ComponentPropsWithRef<
+	typeof BasePopover.Trigger
+>["ref"];
+type PopoverPopupRef = ComponentPropsWithRef<typeof BasePopover.Popup>["ref"];
+
+export type PopoverProps<Payload = unknown> = Closed<
+	BasePopoverRootProps<Payload>
+>;
+
+export type PopoverTriggerProps<Payload = unknown> = Closed<
+	Omit<BasePopoverTriggerProps<Payload>, "ref"> & {
+		ref?: PopoverTriggerRef;
+	}
+>;
+
+export type PopoverPopupVariant = "default" | "bare";
+
+export type PopoverPopupProps = Closed<
+	Omit<BasePopoverPopupProps, "ref"> & {
+		align?: BasePopoverPositionerProps["align"];
+		alignOffset?: BasePopoverPositionerProps["alignOffset"];
+		anchor?: BasePopoverPositionerProps["anchor"];
+		portalProps?: Closed<BasePopoverPortalProps>;
+		ref?: PopoverPopupRef;
+		side?: BasePopoverPositionerProps["side"];
+		sideOffset?: BasePopoverPositionerProps["sideOffset"];
+		tooltipStyle?: boolean;
+		variant?: PopoverPopupVariant;
+	}
+>;
+
+export type PopoverTitleProps = Closed<BasePopoverTitleProps>;
+export type PopoverDescriptionProps = Closed<BasePopoverDescriptionProps>;
+export type PopoverCloseProps = Closed<BasePopoverCloseProps>;
+
+export const PopoverCreateHandle = BasePopover.createHandle;
+
+export const Popover = BasePopover.Root;
+export const PopoverPrimitive = BasePopover;
+
+export function PopoverTrigger<Payload = unknown>({
+	ref: forwardedRef = undefined,
+	render,
+	type,
+	...rest
+}: PopoverTriggerProps<Payload>) {
+	return (
+		<BasePopover.Trigger
+			{...rest}
+			data-slot="popover-trigger"
+			ref={forwardedRef}
+			render={protectRenderSlot("popover-trigger", render)}
+			type={render ? type : (type ?? "button")}
+		/>
+	);
+}
+
+function getPopoverStyles(variant: PopoverPopupVariant, tooltipStyle: boolean) {
+	const bare = variant === "bare";
+	return {
+		popup: props(
+			popoverStyles.popup,
+			tooltipStyle && popoverStyles.popupTooltip,
+			bare && popoverStyles.popupBare
+		),
+		positioner: props(
+			popoverStyles.positioner,
+			bare && popoverStyles.positionerBare
+		),
+		viewport: props(
+			popoverStyles.viewport,
+			popoverStyles.viewportContent,
+			tooltipStyle && popoverStyles.viewportTooltip,
+			tooltipStyle && popoverStyles.viewportContentTooltip,
+			bare && popoverStyles.viewportBare,
+			bare && popoverStyles.viewportContentBare
+		),
+	};
+}
+
+export function PopoverPopup({
+	align = "center",
+	alignOffset = 0,
+	anchor,
+	children,
+	render,
+	portalProps,
+	ref: forwardedRef = undefined,
+	side = "bottom",
+	sideOffset = 4,
+	tooltipStyle = false,
+	variant = "default",
+	...rest
+}: PopoverPopupProps) {
+	const styles = getPopoverStyles(variant, tooltipStyle);
+	const Viewport = portalProps?.keepMounted ? "div" : BasePopover.Viewport;
+
+	return (
+		<BasePopover.Portal {...portalProps}>
+			<BasePopover.Positioner
+				align={align}
+				alignOffset={alignOffset}
+				anchor={anchor}
+				data-slot="popover-positioner"
+				side={side}
+				sideOffset={sideOffset}
+				{...styles.positioner}
+			>
+				<BasePopover.Popup
+					{...rest}
+					data-slot="popover-popup"
+					ref={forwardedRef}
+					render={protectRenderSlot("popover-popup", render)}
+					{...styles.popup}
+				>
+					<Viewport data-slot="popover-viewport" {...styles.viewport}>
+						{children}
+					</Viewport>
+				</BasePopover.Popup>
+			</BasePopover.Positioner>
+		</BasePopover.Portal>
+	);
+}
+
+export function PopoverTitle({
+	children,
+	render,
+	ref: forwardedRef,
+	...rest
+}: PopoverTitleProps) {
+	return (
+		<BasePopover.Title
+			{...rest}
+			data-slot="popover-title"
+			ref={forwardedRef}
+			render={protectRenderSlot("popover-title", render)}
+			{...props(popoverStyles.title)}
+		>
+			{children}
+		</BasePopover.Title>
+	);
+}
+
+export function PopoverDescription({
+	children,
+	render,
+	ref: forwardedRef,
+	...rest
+}: PopoverDescriptionProps) {
+	return (
+		<BasePopover.Description
+			{...rest}
+			data-slot="popover-description"
+			ref={forwardedRef}
+			render={protectRenderSlot("popover-description", render)}
+			{...props(popoverStyles.description)}
+		>
+			{children}
+		</BasePopover.Description>
+	);
+}
+
+export function PopoverClose({
+	ref: forwardedRef,
+	render,
+	type,
+	...rest
+}: PopoverCloseProps) {
+	return (
+		<BasePopover.Close
+			{...rest}
+			data-slot="popover-close"
+			ref={forwardedRef}
+			render={protectRenderSlot("popover-close", render)}
+			type={render ? type : (type ?? "button")}
+		/>
+	);
+}