@atelic-action/ui 0.7.2 → 0.9.0

package/src/components/StarRating.tsx

@@ -0,0 +1,153 @@
+import { Star } from "lucide-react";
+import { type CSSProperties, type KeyboardEvent, useState } from "react";
+
+const STEP = 0.5;
+
+export interface StarRatingProps {
+	/** The rating, in half star steps from 0.5 up to `max`; null is unrated. */
+	value: number | null;
+	/** Called with the new rating, or null to clear it. Leave it out for a read only row. */
+	onChange?: (value: number | null) => void;
+	/** How many stars the scale runs to. */
+	max?: number;
+	/** The side of one star, in pixels. */
+	size?: number;
+	/** The color of a filled star: any CSS color. Defaults to the text color around it. */
+	fillColor?: string;
+	/** The color of a star's outline: any CSS color. Defaults to a faint tint of the text color. */
+	outlineColor?: string;
+	/** What a screen reader calls the row. */
+	label?: string;
+	className?: string;
+}
+
+/** "4.5 stars", "1 star", "Not rated": the rating as a person would say it. */
+export function describeStarRating(value: number | null): string {
+	if (value === null) return "Not rated";
+	return `${value} ${value === 1 ? "star" : "stars"}`;
+}
+
+/**
+ * A row of stars that shows a rating in half star steps and, given `onChange`,
+ * takes one. Each star is two hit targets, its left half and its right, so a
+ * pointer lands on 3.5 or 4 without a second control. Picking the rating
+ * already set clears it, which is the only way back to unrated and needs no
+ * button of its own.
+ *
+ * To a keyboard and a screen reader an editable row is one slider: the arrows
+ * move half a star, Home clears, End is the top of the scale. The halves stay
+ * out of the tab order, so the row is one stop rather than ten. Without
+ * `onChange` it is a picture with the rating as its name.
+ *
+ * The two colors are the `--star-fill` and `--star-outline` custom properties.
+ * `fillColor` and `outlineColor` set them on this row; a site may also set
+ * them in its own CSS for every row at once.
+ */
+export function StarRating({
+	value,
+	onChange,
+	max = 5,
+	size = 24,
+	fillColor,
+	outlineColor,
+	label = "Rating",
+	className,
+}: StarRatingProps) {
+	const [hover, setHover] = useState<number | null>(null);
+	const shown = hover ?? value ?? 0;
+
+	const style = {
+		"--star-size": `${size}px`,
+		...(fillColor ? { "--star-fill": fillColor } : {}),
+		...(outlineColor ? { "--star-outline": outlineColor } : {}),
+	} as CSSProperties;
+	const classes = ["star-rating", className].filter(Boolean).join(" ");
+
+	const stars = Array.from({ length: max }, (_, i) => i + 1).map((star) => {
+		const fill = shown >= star ? "100%" : shown >= star - STEP ? "50%" : "0%";
+		return (
+			<span key={star} className="star-rating-star">
+				<Star aria-hidden="true" size={size} className="star-rating-outline" />
+				<span aria-hidden="true" className="star-rating-fill" style={{ width: fill }}>
+					<Star size={size} />
+				</span>
+				{onChange &&
+					[star - STEP, star].map((rating, half) => (
+						<button
+							key={rating}
+							type="button"
+							tabIndex={-1}
+							aria-label={describeStarRating(rating)}
+							className={`star-rating-hit ${half === 0 ? "is-left" : "is-right"}`}
+							onMouseEnter={() => setHover(rating)}
+							onClick={() => {
+								// Drop the preview with the pick: the pointer is still on this
+								// half, and a preview left up would hide a clear behind the
+								// very stars it just emptied.
+								setHover(null);
+								onChange(rating === value ? null : rating);
+							}}
+						/>
+					))}
+			</span>
+		);
+	});
+
+	if (!onChange) {
+		return (
+			<span
+				role="img"
+				aria-label={`${label}: ${describeStarRating(value)}`}
+				className={classes}
+				style={style}
+			>
+				{stars}
+			</span>
+		);
+	}
+
+	const set = (next: number | null) => {
+		if (next !== value) onChange(next);
+	};
+
+	const onKeyDown = (event: KeyboardEvent) => {
+		const current = value ?? 0;
+		switch (event.key) {
+			case "ArrowRight":
+			case "ArrowUp":
+				set(Math.min(max, current + STEP));
+				break;
+			case "ArrowLeft":
+			case "ArrowDown":
+				set(current - STEP > 0 ? current - STEP : null);
+				break;
+			case "Home":
+				set(null);
+				break;
+			case "End":
+				set(max);
+				break;
+			default:
+				return;
+		}
+		event.preventDefault();
+	};
+
+	return (
+		<span
+			role="slider"
+			tabIndex={0}
+			aria-label={label}
+			aria-valuemin={0}
+			aria-valuemax={max}
+			aria-valuenow={value ?? 0}
+			aria-valuetext={describeStarRating(value)}
+			className={`${classes} is-editable`}
+			style={style}
+			onKeyDown={onKeyDown}
+			onMouseLeave={() => setHover(null)}
+		>
+			{stars}
+		</span>
+	);
+}

package/src/components/StatRow.tsx

@@ -0,0 +1,96 @@
+import { ArrowDown, ArrowRight, ArrowUp } from "lucide-react";
+import type { ReactNode } from "react";
+import type { Tone } from "./tone";
+
+export type StatDirection = "up" | "down" | "flat";
+
+/** One comparison under a figure: which way it moved, by how much, against what. */
+export interface StatDelta {
+	direction: StatDirection;
+	/** How far it moved, e.g. "23%". */
+	change: string;
+	/** What it is measured against, short, e.g. "YoY". */
+	basis: string;
+	/** The basis spelled out, e.g. "year over year"; read aloud and shown on hover. */
+	basisTitle?: string;
+	/** The earlier figure, e.g. "5,157". It leads the line, small, under the current one. */
+	was?: string;
+	/** Whether the move is good or bad news; a spend falling and a cost falling read differently. */
+	tone?: Tone;
+}
+
+export interface StatItem {
+	/** The big figure, e.g. "$199", "3,948", "23%"; may embed an inline glyph. */
+	value: ReactNode;
+	/** An arrow before the figure, when the figure is itself a change. */
+	trend?: StatDirection;
+	/** What the figure counts. */
+	label: ReactNode;
+	/** The period the figure covers, e.g. "2026 Q3". */
+	period?: ReactNode;
+	/** Comparisons under the figure, each an arrow, a change, and what it is against. */
+	deltas?: StatDelta[];
+	/** A small dimmed qualifier at the foot (the source, a caveat). */
+	note?: ReactNode;
+	/** How the figure itself reads; set as data-tone. */
+	tone?: Tone;
+}
+
+export interface StatRowProps {
+	stats: StatItem[];
+	className?: string;
+}
+
+const arrow = { up: ArrowUp, down: ArrowDown, flat: ArrowRight } as const;
+const spoken = { up: "Up", down: "Down", flat: "Unchanged" } as const;
+
+/**
+ * A row of large figures. Under each sit its comparisons, one a line: what
+ * the figure was, an arrow, how far it moved, and against what. The label
+ * closes the stat, with the period it covers. The row wraps to as many
+ * columns as fit, and arrows are read aloud as up or down.
+ */
+export function StatRow({ stats, className }: StatRowProps) {
+	return (
+		<div className={["stat-row", className].filter(Boolean).join(" ")}>
+			{stats.map((stat, i) => {
+				const Trend = stat.trend ? arrow[stat.trend] : null;
+				return (
+					// biome-ignore lint/suspicious/noArrayIndexKey: stats are static content in a fixed order
+					<div className="stat" key={i} data-tone={stat.tone}>
+						<div className="num">
+							{Trend && stat.trend && (
+								<Trend className="stat-trend" role="img" aria-label={spoken[stat.trend]} />
+							)}
+							{stat.value}
+						</div>
+						{stat.deltas?.map((delta) => {
+							const Icon = arrow[delta.direction];
+							return (
+								<div className="stat-delta" key={delta.basis}>
+									{delta.was && <span className="stat-delta-was">{delta.was}</span>}
+									<span className="stat-delta-change" data-tone={delta.tone ?? "muted"}>
+										<Icon size={14} role="img" aria-label={spoken[delta.direction]} />
+										{delta.change}
+									</span>
+									{delta.basisTitle ? (
+										<abbr className="stat-delta-basis" title={delta.basisTitle}>
+											{delta.basis}
+										</abbr>
+									) : (
+										<span className="stat-delta-basis">{delta.basis}</span>
+									)}
+								</div>
+							);
+						})}
+						<div className="lbl">
+							{stat.label}
+							{stat.period && <span className="stat-period">{stat.period}</span>}
+						</div>
+						{stat.note && <div className="note">{stat.note}</div>}
+					</div>
+				);
+			})}
+		</div>
+	);
+}

package/src/components/ThresholdScale.tsx

@@ -0,0 +1,89 @@
+import type { Tone } from "./tone";
+
+export interface ThresholdZone {
+	label: string;
+	/** Where the zone ends, in the reading's unit; the last zone runs to `max`. */
+	upTo?: number;
+	tone: Tone;
+}
+
+export interface ThresholdReading {
+	label: string;
+	value: number;
+	/** The figure as printed, e.g. "5.9 s". */
+	display: string;
+	tone: Tone;
+}
+
+export interface ThresholdScaleProps {
+	/** The far end of the scale, in the reading's unit. */
+	max: number;
+	/** Zones in order, e.g. good, slow, poor. */
+	zones: ThresholdZone[];
+	/** The lines between zones, labeled, e.g. "2.5 s" at 2.5. */
+	ticks?: Array<{ at: number; label: string }>;
+	/** One line a reading, each a pin on the scale. */
+	readings: ThresholdReading[];
+	className?: string;
+}
+
+/**
+ * A scale with zones and one line a reading: where a number sits against
+ * the lines that decide good, slow, and poor.
+ */
+export function ThresholdScale({ max, zones, ticks, readings, className }: ThresholdScaleProps) {
+	let from = 0;
+	const sized = zones.map((zone) => {
+		const to = zone.upTo ?? max;
+		const width = ((to - from) / max) * 100;
+		from = to;
+		return { ...zone, width };
+	});
+	return (
+		<div className={["threshold-scale", className].filter(Boolean).join(" ")}>
+			{readings.map((reading) => (
+				<div className="threshold-scale-row" key={reading.label}>
+					<span className="threshold-scale-label">{reading.label}</span>
+					<span
+						className="threshold-scale-track"
+						role="img"
+						aria-label={`${reading.label}: ${reading.display}`}
+					>
+						{sized.map((zone) => (
+							<span
+								className="threshold-scale-zone"
+								key={zone.label}
+								data-tone={zone.tone}
+								style={{ width: `${zone.width}%` }}
+							/>
+						))}
+						<span
+							className="threshold-scale-pin"
+							data-tone={reading.tone}
+							style={{ left: `${Math.min(reading.value / max, 1) * 100}%` }}
+						/>
+					</span>
+					<b className="threshold-scale-value" data-tone={reading.tone}>
+						{reading.display}
+					</b>
+				</div>
+			))}
+			<div className="threshold-scale-row is-axis" aria-hidden="true">
+				<span className="threshold-scale-label" />
+				<span className="threshold-scale-axis">
+					{sized.map((zone) => (
+						<span key={zone.label} data-tone={zone.tone} style={{ width: `${zone.width}%` }}>
+							{zone.label}
+						</span>
+					))}
+					{ticks?.map((tick) => (
+						<i key={tick.label} style={{ left: `${(tick.at / max) * 100}%` }}>
+							{tick.label}
+						</i>
+					))}
+				</span>
+				<span className="threshold-scale-value" />
+			</div>
+		</div>
+	);
+}

package/src/components/index.ts

@@ -1 +1,35 @@
+export { Callout, type CalloutProps } from "./Callout";
+export { Checklist, type ChecklistItem, type ChecklistProps } from "./Checklist";
+export { Collapsible, type CollapsibleProps } from "./Collapsible";
+export {
+	ColumnChart,
+	type ColumnChartBar,
+	type ColumnChartGroup,
+	type ColumnChartProps,
+} from "./ColumnChart";
+export {
+	DataTable,
+	type DataTableCell,
+	type DataTableColumn,
+	type DataTableProps,
+	type DataTableRow,
+	type DataTableValueCell,
+	type SortDirection,
+} from "./DataTable";
 export { NotFound, type NotFoundProps } from "./NotFound";
+export { StackedBar, type StackedBarProps, type StackedBarSegment } from "./StackedBar";
+export { describeStarRating, StarRating, type StarRatingProps } from "./StarRating";
+export {
+	type StatDelta,
+	type StatDirection,
+	type StatItem,
+	StatRow,
+	type StatRowProps,
+} from "./StatRow";
+export {
+	type ThresholdReading,
+	ThresholdScale,
+	type ThresholdScaleProps,
+	type ThresholdZone,
+} from "./ThresholdScale";
+export type { Tone } from "./tone";

package/src/components/tone.ts

@@ -0,0 +1,7 @@
+/**
+ * How a figure, a mark, or a bar reads: good, a warning, broken, plain
+ * information, or quiet. A component sets it as `data-tone`, and
+ * `styles/components.css` turns it into `--tone`, `--tone-fill`, and
+ * `--tone-bg` for whatever sits inside.
+ */
+export type Tone = "good" | "warn" | "bad" | "info" | "muted";