@mizen-labs/ui 0.0.0-stage → 0.1.0

package/src/components/message-scroller/message-scroller.tsx

@@ -0,0 +1,417 @@
+"use client";
+
+import { ScrollArea as BaseScrollArea } from "@base-ui/react/scroll-area";
+import { props } from "@stylexjs/stylex";
+import { domAnimation, LazyMotion, MotionConfig, m } from "motion/react";
+import {
+	type ComponentPropsWithRef,
+	createContext,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useState,
+	useSyncExternalStore,
+} from "react";
+import type { Closed } from "../../closed";
+import { IconArrowDown } from "../../icons";
+import { buttonStyles } from "../button/button.styles";
+import { scrollAreaStyles } from "../scroll-area/scroll-area.styles";
+import {
+	Tooltip,
+	TooltipCreateHandle,
+	TooltipPrimitive,
+	TooltipTrigger,
+} from "../tooltip/tooltip";
+import { tooltipStyles } from "../tooltip/tooltip.styles";
+import { messageScrollerStyles as styles } from "./message-scroller.styles";
+import {
+	type MessageScrollerAnchor,
+	type MessageScrollerSnapshot,
+	MessageScrollerStore,
+} from "./message-scroller-store";
+
+export type {
+	MessageScrollerAnchor,
+	MessageScrollerSnapshot,
+} from "./message-scroller-store";
+
+const StoreContext = createContext<MessageScrollerStore | null>(null);
+
+function useStore() {
+	const store = useContext(StoreContext);
+	if (!store) {
+		throw new Error("MessageScroller parts must sit inside MessageScroller.");
+	}
+	return store;
+}
+
+/** The scroller's state: whether the view is at the end, and the turns. */
+export function useMessageScrollerState(): MessageScrollerSnapshot {
+	const store = useStore();
+	return useSyncExternalStore(
+		store.subscribe,
+		store.getSnapshot,
+		store.getSnapshot
+	);
+}
+
+/** Commands for custom controls: jump to the end, or to a message. */
+export function useMessageScroller() {
+	const store = useStore();
+	return {
+		scrollToEnd: store.scrollToEnd,
+		scrollToMessage: store.scrollToMessage,
+	};
+}
+
+type Part<Element extends "div" | "button"> = Omit<
+	Closed<ComponentPropsWithRef<Element>>,
+	"data-slot"
+>;
+
+export type MessageScrollerProps = Part<"div"> & { children: ReactNode };
+
+/**
+ * A scrolling transcript. It opens at the end and follows new content while
+ * the reader is there; a turn the person sends settles near the top with the
+ * reply growing under it; and the reader's place holds when older messages
+ * load above. It fills a parent with a bounded height.
+ */
+export function MessageScroller({ children, ...rest }: MessageScrollerProps) {
+	const [store] = useState(() => new MessageScrollerStore());
+	return (
+		<StoreContext.Provider value={store}>
+			<LazyMotion features={domAnimation} strict>
+				<MotionConfig reducedMotion="user">
+					<div {...rest} data-slot="message-scroller" {...props(styles.root)}>
+						{children}
+					</div>
+				</MotionConfig>
+			</LazyMotion>
+		</StoreContext.Provider>
+	);
+}
+
+export type MessageScrollerViewportProps = Part<"div"> & {
+	/** Names the scrolling region. */
+	"aria-label"?: string;
+	children: ReactNode;
+};
+
+// Base UI sizes the content to fit its widest row; a transcript wraps
+// instead, so its minimum width is cleared as Scroll Area does.
+const scrolled = props(scrollAreaStyles.content, styles.scrollContent);
+const contentProps = {
+	...scrolled,
+	style: { ...scrolled.style, minWidth: 0 },
+};
+
+/**
+ * The scrolling region, a Scroll Area: a thin thumb shows on hover and
+ * while scrolling, and the edges fade where more waits. It is focusable,
+ * so the keyboard can scroll it.
+ */
+export function MessageScrollerViewport({
+	"aria-label": ariaLabel = "Messages",
+	children,
+	...rest
+}: MessageScrollerViewportProps) {
+	const { attachViewport } = useStore();
+	return (
+		<BaseScrollArea.Root {...props(scrollAreaStyles.root, styles.area)}>
+			<BaseScrollArea.Viewport
+				{...rest}
+				aria-label={ariaLabel}
+				data-slot="message-scroller-viewport"
+				ref={attachViewport}
+				role="region"
+				tabIndex={0}
+				{...props(
+					scrollAreaStyles.viewport,
+					scrollAreaStyles.viewportFade,
+					styles.viewport
+				)}
+			>
+				<BaseScrollArea.Content {...contentProps}>
+					{children}
+				</BaseScrollArea.Content>
+			</BaseScrollArea.Viewport>
+			<BaseScrollArea.Scrollbar
+				orientation="vertical"
+				{...props(
+					scrollAreaStyles.scrollbar,
+					scrollAreaStyles.scrollbarVertical
+				)}
+			>
+				<BaseScrollArea.Thumb {...props(scrollAreaStyles.thumb)} />
+			</BaseScrollArea.Scrollbar>
+		</BaseScrollArea.Root>
+	);
+}
+
+export type MessageScrollerContentProps = Part<"div"> & {
+	/** True while a reply streams, so assistive tech waits for it. */
+	busy?: boolean;
+	children: ReactNode;
+};
+
+/**
+ * The transcript itself, a live log that announces new turns. Every direct
+ * child is a MessageScrollerItem.
+ */
+export function MessageScrollerContent({
+	busy = false,
+	children,
+	...rest
+}: MessageScrollerContentProps) {
+	const { attachLog, attachSpacer } = useStore();
+	return (
+		<>
+			<div
+				{...rest}
+				aria-busy={busy || undefined}
+				aria-relevant="additions"
+				data-slot="message-scroller-content"
+				ref={attachLog}
+				role="log"
+				{...props(styles.content)}
+			>
+				{children}
+			</div>
+			{/* Room under a short reply, so its turn can sit near the top. */}
+			<div aria-hidden="true" ref={attachSpacer} />
+		</>
+	);
+}
+
+export type MessageScrollerItemProps = Part<"div"> & {
+	children: ReactNode;
+	/** A stable id, for jumping to it and for holding the reader's place. */
+	messageId: string;
+	/**
+	 * Marks a turn boundary, usually the person's message: once sent, it
+	 * settles near the top, and a navigation rail lists it. `auto` anchors
+	 * the item when it holds the reader's own Message (from the user,
+	 * aligned to the end).
+	 */
+	scrollAnchor?: boolean | "auto";
+};
+
+// A new row fades in and rises 8px: duration.overlayEnter with
+// easing.expoOut. Rows from the first load stay still.
+const ARRIVAL = {
+	animate: { opacity: 1, y: 0 },
+	initial: { opacity: 0, y: 8 },
+	transition: { duration: 0.28, ease: [0.16, 1, 0.3, 1] },
+} as const;
+
+export function MessageScrollerItem({
+	children,
+	messageId,
+	scrollAnchor = false,
+	...rest
+}: MessageScrollerItemProps) {
+	const { isLive } = useStore();
+	// Decided once, when the row first renders.
+	const [arriving] = useState(isLive);
+	return (
+		<div
+			{...rest}
+			data-message-id={messageId}
+			data-scroll-anchor={String(scrollAnchor)}
+			data-slot="message-scroller-item"
+		>
+			<m.div
+				animate={ARRIVAL.animate}
+				initial={arriving ? ARRIVAL.initial : false}
+				transition={ARRIVAL.transition}
+			>
+				{children}
+			</m.div>
+		</div>
+	);
+}
+
+export type MessageScrollerButtonProps = Omit<
+	Part<"button">,
+	"children" | "onClick" | "type"
+> & {
+	/** Read by screen readers; the button shows an arrow. */
+	"aria-label"?: string;
+};
+
+/**
+ * A round arrow that jumps to the newest content. It fades in when there is
+ * something below the view and leaves the tab order when there is not.
+ */
+export function MessageScrollerButton({
+	"aria-label": ariaLabel = "Jump to latest",
+	...rest
+}: MessageScrollerButtonProps) {
+	const store = useStore();
+	const { atEnd } = useMessageScrollerState();
+	const jump = useCallback(() => store.scrollToEnd(), [store]);
+	return (
+		<button
+			{...rest}
+			aria-label={ariaLabel}
+			data-active={atEnd ? undefined : ""}
+			data-slot="message-scroller-button"
+			inert={atEnd}
+			onClick={jump}
+			type="button"
+			{...props(
+				buttonStyles.base,
+				buttonStyles["icon-sm"],
+				buttonStyles.press,
+				buttonStyles.interactionGhost,
+				styles.button
+			)}
+		>
+			<IconArrowDown aria-hidden="true" size={16} />
+		</button>
+	);
+}
+
+// How far a tick is from the one in focus, for its length: the focused
+// tick is full length and its neighbors step down, like a dock.
+function nearness(index: number, focus: number) {
+	return String(Math.min(Math.abs(index - focus), 3));
+}
+
+type Preview = MessageScrollerAnchor;
+
+function NavigationTick({
+	anchor,
+	current,
+	handle,
+	index,
+	near,
+	onFocusTick,
+	onLeaveTick,
+	total,
+}: {
+	anchor: MessageScrollerAnchor;
+	current: boolean;
+	handle: ReturnType<typeof TooltipCreateHandle<Preview>>;
+	index: number;
+	near: string;
+	onFocusTick: (index: number) => void;
+	onLeaveTick: () => void;
+	total: number;
+}) {
+	const { scrollToMessage } = useStore();
+	const jump = useCallback(
+		() => scrollToMessage(anchor.id),
+		[anchor.id, scrollToMessage]
+	);
+	const focusTick = useCallback(() => onFocusTick(index), [index, onFocusTick]);
+	return (
+		<li>
+			<TooltipTrigger
+				delay={0}
+				handle={handle}
+				payload={anchor}
+				render={
+					<button
+						aria-current={current ? "true" : undefined}
+						aria-label={`Turn ${index + 1} of ${total}: ${anchor.label}`}
+						data-near={near}
+						onBlur={onLeaveTick}
+						onClick={jump}
+						onFocus={focusTick}
+						onPointerEnter={focusTick}
+						onPointerLeave={onLeaveTick}
+						type="button"
+						{...props(styles.tick)}
+					/>
+				}
+			>
+				<span aria-hidden="true" {...props(styles.tickLine)} />
+			</TooltipTrigger>
+		</li>
+	);
+}
+
+// A tooltip surface that shows and moves at once: the rail's ticks carry
+// the motion, so the preview only follows them.
+function NavigationPreview({ payload }: { payload: Preview | undefined }) {
+	return (
+		<TooltipPrimitive.Portal>
+			<TooltipPrimitive.Positioner
+				side="left"
+				sideOffset={8}
+				{...props(tooltipStyles.positioner, styles.still)}
+			>
+				<TooltipPrimitive.Popup
+					data-slot="tooltip-popup"
+					{...props(tooltipStyles.popup, styles.still)}
+				>
+					{payload ? (
+						<span {...props(styles.preview)}>
+							<span {...props(styles.previewTitle)}>{payload.label}</span>
+							{payload.reply ? (
+								<span {...props(styles.previewReply)}>{payload.reply}</span>
+							) : null}
+						</span>
+					) : null}
+				</TooltipPrimitive.Popup>
+			</TooltipPrimitive.Positioner>
+		</TooltipPrimitive.Portal>
+	);
+}
+
+export interface MessageScrollerNavigationProps {
+	/** Names the rail for assistive tech. */
+	"aria-label"?: string;
+}
+
+/**
+ * A rail of ticks along the end edge, one per turn boundary. Hover or focus
+ * a tick to preview the turn and the start of its reply; press it to jump
+ * there. It shows from two turns, and floats over the nearest positioned
+ * box, so keep the thread's end edge clear of it.
+ */
+export function MessageScrollerNavigation({
+	"aria-label": ariaLabel = "Turns",
+}: MessageScrollerNavigationProps) {
+	const { anchors, current } = useMessageScrollerState();
+	const [handle] = useState(() => TooltipCreateHandle<Preview>());
+	const [pointed, setPointed] = useState<number | null>(null);
+	const leave = useCallback(() => setPointed(null), []);
+	if (anchors.length < 2) {
+		return null;
+	}
+	const focus =
+		pointed ??
+		Math.max(
+			0,
+			anchors.findIndex((anchor) => anchor.id === current)
+		);
+	return (
+		<nav
+			aria-label={ariaLabel}
+			data-slot="message-scroller-navigation"
+			{...props(styles.navigation)}
+		>
+			<ol {...props(styles.ticks)}>
+				{anchors.map((anchor, index) => (
+					<NavigationTick
+						anchor={anchor}
+						current={anchor.id === current}
+						handle={handle}
+						index={index}
+						key={anchor.id}
+						near={nearness(index, focus)}
+						onFocusTick={setPointed}
+						onLeaveTick={leave}
+						total={anchors.length}
+					/>
+				))}
+			</ol>
+			<Tooltip handle={handle}>
+				{({ payload }) => <NavigationPreview payload={payload} />}
+			</Tooltip>
+		</nav>
+	);
+}

package/src/components/meter/meter.styles.ts

@@ -0,0 +1,48 @@
+import { create } from "@stylexjs/stylex";
+import { colors } from "../../styles/colors.stylex";
+import { conditions } from "../../styles/conditions.stylex";
+import { duration, easing } from "../../styles/motion.stylex";
+import { space } from "../../styles/spacing.stylex";
+import { fontWeight } from "../../styles/typography.stylex";
+
+export const meterStyles = create({
+	indicator: {
+		backgroundColor: colors.primary,
+		borderRadius: "9999px",
+		boxSizing: "border-box",
+		display: "block",
+		height: "inherit",
+		transitionDuration: {
+			[conditions.reducedMotion]: duration.instant,
+			default: duration.disclosure,
+		},
+		transitionProperty: "width",
+		transitionTimingFunction: easing.expoOut,
+	},
+	label: {
+		color: colors.content,
+		fontWeight: fontWeight.medium,
+	},
+	root: {
+		boxSizing: "border-box",
+		display: "flex",
+		flexDirection: "column",
+		gap: space["1"],
+		width: "100%",
+	},
+	track: {
+		// A translucent tint, like Progress, so the track shows on any surface.
+		backgroundColor: colors.border,
+		borderRadius: "9999px",
+		boxSizing: "border-box",
+		display: "block",
+		height: "0.5rem",
+		overflow: "hidden",
+		position: "relative",
+		width: "100%",
+	},
+	value: {
+		color: colors.content,
+		fontVariantNumeric: "tabular-nums",
+	},
+});

package/src/components/meter/meter.tsx

@@ -0,0 +1,176 @@
+"use client";
+
+import { Meter as BaseMeter } from "@base-ui/react/meter";
+import { props } from "@stylexjs/stylex";
+import type { ComponentPropsWithRef } from "react";
+import type { Closed } from "../../closed";
+import { protectRenderSlot } from "../../render-utils";
+import { typeRoles } from "../../styles/typography.styles";
+import { meterStyles } from "./meter.styles";
+
+type RootProps = ComponentPropsWithRef<typeof BaseMeter.Root>;
+type TrackProps = ComponentPropsWithRef<typeof BaseMeter.Track>;
+type IndicatorProps = ComponentPropsWithRef<typeof BaseMeter.Indicator>;
+type LabelProps = ComponentPropsWithRef<typeof BaseMeter.Label>;
+type ValueProps = ComponentPropsWithRef<typeof BaseMeter.Value>;
+
+type Part<T> = Omit<Closed<T>, "data-slot" | "role">;
+
+export type MeterProps = Omit<
+	Part<RootProps>,
+	"aria-valuemax" | "aria-valuemin" | "aria-valuenow"
+> & { ref?: RootProps["ref"] };
+export type MeterTrackProps = Part<TrackProps> & { ref?: TrackProps["ref"] };
+export type MeterIndicatorProps = Part<IndicatorProps> & {
+	ref?: IndicatorProps["ref"];
+};
+export type MeterLabelProps = Part<LabelProps> & { ref?: LabelProps["ref"] };
+export type MeterValueProps = Part<ValueProps> & { ref?: ValueProps["ref"] };
+
+function stripReservedProps(rest: Record<string, unknown>) {
+	for (const name of ["className", "data-slot", "role", "style"]) {
+		Reflect.deleteProperty(rest, name);
+	}
+}
+
+function stripRangeProps(rest: Record<string, unknown>) {
+	for (const name of ["aria-valuemax", "aria-valuemin", "aria-valuenow"]) {
+		Reflect.deleteProperty(rest, name);
+	}
+}
+
+function validateRange(value: number, min: number, max: number) {
+	if (
+		!(Number.isFinite(value) && Number.isFinite(min) && Number.isFinite(max))
+	) {
+		throw new TypeError("Meter value, min, and max must be finite numbers.");
+	}
+	if (min >= max) {
+		throw new RangeError("Meter min must be less than max.");
+	}
+}
+
+// Without children there is no MeterLabel, so the root must carry the name.
+function validateName(rest: MeterProps, hasChildren: boolean) {
+	const name = rest["aria-label"] ?? rest["aria-labelledby"] ?? "";
+	if (!(hasChildren || name.trim())) {
+		throw new TypeError(
+			"Meter requires a MeterLabel child, aria-label, or aria-labelledby."
+		);
+	}
+}
+
+export function Meter({
+	children,
+	locale = "en",
+	max = 100,
+	min = 0,
+	ref: forwardedRef,
+	render,
+	value,
+	...rest
+}: MeterProps) {
+	stripReservedProps(rest);
+	stripRangeProps(rest);
+	validateRange(value, min, max);
+	validateName(rest as MeterProps, children !== undefined);
+	return (
+		<BaseMeter.Root
+			{...rest}
+			data-slot="meter"
+			locale={locale}
+			max={max}
+			min={min}
+			ref={forwardedRef}
+			render={protectRenderSlot("meter", render, { role: "meter" })}
+			value={value}
+			{...props(meterStyles.root, typeRoles.body)}
+		>
+			{children ?? (
+				<MeterTrack>
+					<MeterIndicator />
+				</MeterTrack>
+			)}
+		</BaseMeter.Root>
+	);
+}
+
+export function MeterTrack({
+	children,
+	ref: forwardedRef,
+	render,
+	...rest
+}: MeterTrackProps) {
+	stripReservedProps(rest);
+	return (
+		<BaseMeter.Track
+			{...rest}
+			data-slot="meter-track"
+			ref={forwardedRef}
+			render={protectRenderSlot("meter-track", render)}
+			{...props(meterStyles.track)}
+		>
+			{children}
+		</BaseMeter.Track>
+	);
+}
+
+export function MeterIndicator({
+	children,
+	ref: forwardedRef,
+	render,
+	...rest
+}: MeterIndicatorProps) {
+	stripReservedProps(rest);
+	return (
+		<BaseMeter.Indicator
+			{...rest}
+			data-slot="meter-indicator"
+			ref={forwardedRef}
+			render={protectRenderSlot("meter-indicator", render)}
+			{...props(meterStyles.indicator)}
+		>
+			{children}
+		</BaseMeter.Indicator>
+	);
+}
+
+export function MeterLabel({
+	children,
+	ref: forwardedRef,
+	render,
+	...rest
+}: MeterLabelProps) {
+	stripReservedProps(rest);
+	return (
+		<BaseMeter.Label
+			{...rest}
+			data-slot="meter-label"
+			ref={forwardedRef}
+			render={protectRenderSlot("meter-label", render)}
+			{...props(meterStyles.label)}
+		>
+			{children}
+		</BaseMeter.Label>
+	);
+}
+
+export function MeterValue({
+	children,
+	ref: forwardedRef,
+	render,
+	...rest
+}: MeterValueProps) {
+	stripReservedProps(rest);
+	return (
+		<BaseMeter.Value
+			{...rest}
+			data-slot="meter-value"
+			ref={forwardedRef}
+			render={protectRenderSlot("meter-value", render)}
+			{...props(meterStyles.value)}
+		>
+			{children}
+		</BaseMeter.Value>
+	);
+}

package/src/components/metric/metric.styles.ts

@@ -0,0 +1,64 @@
+import { create } from "@stylexjs/stylex";
+import { colors } from "../../styles/colors.stylex";
+import { shape } from "../../styles/shape.stylex";
+import { space } from "../../styles/spacing.stylex";
+import {
+	fontSize,
+	fontWeight,
+	lineHeight,
+} from "../../styles/typography.stylex";
+
+export const metricStyles = create({
+	// A rounded rectangle, not a pill, so it reads as data beside the value.
+	delta: {
+		borderRadius: shape.inlineRadius,
+		display: "inline-flex",
+		flexShrink: 0,
+		fontVariantNumeric: "tabular-nums",
+		paddingBlock: space.px,
+		paddingInline: `calc(${space["1"]} + ${space.px})`,
+		whiteSpace: "nowrap",
+		// Keeps the chip its own size when Metric stacks it in a column.
+		width: "fit-content",
+	},
+	deltaBetter: {
+		backgroundColor: colors.success,
+		color: colors.successContent,
+	},
+	deltaFlat: { backgroundColor: colors.secondary, color: colors.mutedContent },
+	deltaWorse: {
+		backgroundColor: colors.destructiveSubtle,
+		color: colors.destructiveText,
+	},
+	description: {
+		color: colors.mutedContent,
+		fontSize: fontSize["14"],
+		fontWeight: fontWeight.regular,
+		lineHeight: lineHeight["20"],
+		margin: 0,
+		minWidth: 0,
+		overflowWrap: "break-word",
+	},
+	label: {
+		color: colors.mutedContent,
+		fontSize: fontSize["14"],
+		fontWeight: fontWeight.medium,
+		lineHeight: lineHeight["20"],
+		margin: 0,
+		minWidth: 0,
+		overflowWrap: "break-word",
+	},
+	root: {
+		display: "flex",
+		flexDirection: "column",
+		gap: space["1"],
+		margin: 0,
+		minWidth: 0,
+	},
+	value: {
+		color: colors.content,
+		margin: 0,
+		minWidth: 0,
+		overflowWrap: "anywhere",
+	},
+});