@atelic-action/ui 3.4.0 → 3.5.0

package/README.md

@@ -22,6 +22,7 @@ Every export, grouped by the entry it is imported from. The gallery column links
 | `Checklist` | `@atelic-action/ui/components` | A short list of checks, each passed or failed | [#checklist](https://ui.atelic.me/#checklist) |
 | `IconList` | `@atelic-action/ui/components` | A list whose bullets are icons, one for the list or one per item, each in a tone | [#icon-list](https://ui.atelic.me/#icon-list) |
 | `DataTable` | `@atelic-action/ui/components` | A table whose first column names each row, sortable, stacking on a phone | [#data-table](https://ui.atelic.me/#data-table) |
+| `Hint` | `@atelic-action/ui/components` | An info icon that opens a short explainer beside a word, or beside a table heading | [#hint](https://ui.atelic.me/#hint) |
 | `ReportCard` | `@atelic-action/ui/components` | A name, a grade, and a line per row, in labeled groups, each row a link to its section | [#report-card](https://ui.atelic.me/#report-card) |
 | `reportCardLabels`, `ReportCardLabels` | `@atelic-action/ui/components` | The words a screen reader hears around a report card's letters by default, and their type | none |
 | `Rank` | `@atelic-action/ui/components` | A figure with its badge in a tone, for a table cell: a rank, a place in an answer, or a dash | [#rank](https://ui.atelic.me/#rank) |
@@ -703,7 +704,8 @@ The blocks a page composes, each styled in `styles/components.css` inside the `a
 | `IconList` | A list whose bullets are icons | `icon` and `tone` on the list set every bullet; an item's own override them. The bullet is decoration, so a screen reader hears only the items. A dot when no icon is set; the text's color when no tone is |
 | `ReportCard` | A name, a grade, and one line on it per row, in labeled groups, each row's parts centered on it | A row with `href` is a link from edge to edge with a chevron at its end; a link inside `line` still goes where it points. `before` sets the earlier grade faded beside the grade; no `grade` draws a dash read as not graded. `legend` explains the letters beside the `title`, or under the card with `legendAt="foot"`; `labels` sets the screen reader's words. The grade is `GradeChip` |
 | `Rank` | A figure with its badge, for a table cell | `figure` is the rank, the place, or a dash for none; `tone` colors the badge and `meaning` names it for a screen reader; `href` links the figure, in a new tab with `newTab`. The figure's slot is a fixed width, so the badges line up down a column |
-| `DataTable` | A table whose first column names each row, sortable by any column marked `sortable` | A click on a heading sorts on a wide screen. On a phone each row stacks, every fact wearing its column's label, and a dropdown sorts. A cell is a node, or `{ display, sort }` when what it shows is not what it sorts by; a formatted number in a string (`"$12,047"`, `"0.24%"`) sorts as a number. It renders in `defaultSort` on the server. Every other row sits on a tinted ground; `striped={false}` turns that off. A column marked `fit` hugs its content, for a swatch or a mark beside a figure |
+| `DataTable` | A table whose first column names each row, sortable by any column marked `sortable` | A click on a heading sorts on a wide screen. On a phone each row stacks, every fact wearing its column's label, and a dropdown sorts. A cell is a node, or `{ display, sort }` when what it shows is not what it sorts by; a formatted number in a string (`"$12,047"`, `"0.24%"`) sorts as a number. It renders in `defaultSort` on the server. Every other row sits on a tinted ground; `striped={false}` turns that off. A column marked `fit` hugs its content, for a swatch or a mark beside a figure. A column with a `hint` draws a `Hint` beside its heading, before the label when the column is right aligned; on a phone the heading row is hidden, so the hint is too |
+| `Hint` | An info icon that opens a short explainer beside a word | Opens on hover or focus, stays open on a click or a tap, closes on Escape or a tap elsewhere. The bubble opens from the icon's left edge and slides left when it would run off the screen. `side="before"` puts the icon before its word, for a right aligned heading. `label` is what a screen reader calls the button; the bubble is its description. Print hides it |
 | `StatRow` | A row of large figures, each over what it counts and its `period`. `variant="quiet"` is the glance row for a working page: a light figure in the text color over a small capitalized label, hairlines between; `unit` sets a figure's unit small beside it | `trend` draws an arrow before a figure that is itself a change. `deltas` list comparisons beneath: an arrow, how far, against what (`basis`), and the earlier figure (`was`), each in its own tone, since a spend falling and a cost falling read differently |
 | `Callout` | One finding: an icon in its tone beside the title, the explainer under it | `variant="box"` sets it apart on a tinted ground, for something missing or owed |
 | `Disclosure` | A section the reader opens and closes, in two forms chosen by whether `open` is passed | Controlled (`open` and `onToggle`), it is an app's card: the caller remembers what was folded, a closed body is not rendered, the label is the toggle, `meta` (a count, a flag) sits beside it outside its name, and `headingLevel` makes the label a real heading. Uncontrolled, it is a document's fold: a native `details` with a `summary` line that carries the point and `defaultOpen`, so it works before any script loads, find in page opens it, and it prints open. `Collapsible`, the fold's old name, was folded in at 0.18.0 |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "3.4.0",
+	"version": "3.5.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, the access gate, and the app shell they install",
 	"type": "module",
 	"license": "UNLICENSED",

package/src/components/DataTable.tsx

@@ -1,5 +1,6 @@
 import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
 import { type ReactNode, useId, useMemo, useState } from "react";
+import { Hint } from "./Hint";
 
 export type SortDirection = "asc" | "desc";
 
@@ -15,6 +16,10 @@ export interface DataTableColumn {
 	firstSort?: SortDirection;
 	/** The column hugs its content (a swatch, a mark) instead of sharing the width. */
 	fit?: boolean;
+	/** A short explainer behind an info icon beside the heading, for a measure a reader may not know. */
+	hint?: ReactNode;
+	/** What a screen reader calls the hint's button; defaults to "About" and the label. */
+	hintLabel?: string;
 }
 
 /** A cell whose display is not what it sorts by, e.g. an icon over a number. */
@@ -140,9 +145,22 @@ export function DataTable({
 						{columns.map((column, index) => {
 							const active = sort?.column === index;
 							const Icon = !active ? ArrowUpDown : sort?.direction === "asc" ? ArrowUp : ArrowDown;
+							// The explainer's icon sits after the label, or before it when the
+							// column is right aligned, so the icon stays on the inside edge.
+							const before = column.align === "right";
+							const hint = column.hint ? (
+								<Hint
+									label={column.hintLabel ?? `About ${column.label}`}
+									side={before ? "before" : "after"}
+								>
+									{column.hint}
+								</Hint>
+							) : null;
 							const head = {
 								"data-align": column.align ?? "left",
 								"data-fit": column.fit || undefined,
+								// The hint button sits in the heading; the heading is still named by its label.
+								"aria-label": column.hint && column.label ? column.label : undefined,
 								"aria-sort": column.sortable
 									? active
 										? sort?.direction === "asc"
@@ -154,6 +172,7 @@ export function DataTable({
 							return (
 								// biome-ignore lint/suspicious/noArrayIndexKey: columns sit in order, and two may share a blank label
 								<th scope="col" key={index} {...head}>
+									{before && hint}
 									{column.sortable ? (
 										<button
 											type="button"
@@ -166,6 +185,7 @@ export function DataTable({
 									) : (
 										column.label
 									)}
+									{!before && hint}
 								</th>
 							);
 						})}

package/src/components/Hint.tsx

@@ -0,0 +1,138 @@
+import { Info } from "lucide-react";
+import {
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useId,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+
+export interface HintProps {
+	/** What the button is called, for a screen reader, e.g. "About First paint". */
+	label: string;
+	/** Which side of its word the icon sits on; `before` for a right aligned heading. */
+	side?: "before" | "after";
+	className?: string;
+	/** The bubble's text: a sentence or two in plain words. */
+	children: ReactNode;
+}
+
+/**
+ * An info bubble: a small icon beside a word that opens a short explainer.
+ * It opens on hover or focus and stays open on a click or a tap, so it works
+ * on a phone, and Escape or a tap elsewhere closes it. The bubble opens
+ * from the icon's left edge and flips to its right edge when it would run
+ * off the screen. It is read to a screen reader as the button's
+ * description; print hides the icon, since a printed sheet cannot be tapped.
+ */
+export function Hint({ label, side = "after", className, children }: HintProps) {
+	const [open, setOpen] = useState(false);
+	const [pinned, setPinned] = useState(false);
+	// Keyboard focus holds the bubble open until it leaves; mouse focus, which
+	// a click also gives the button, must not, or a later hover sticks open.
+	const [keyboard, setKeyboard] = useState(false);
+	const [shift, setShift] = useState(0);
+	const id = useId();
+	const root = useRef<HTMLSpanElement>(null);
+	const bubble = useRef<HTMLSpanElement>(null);
+
+	const close = useCallback(() => {
+		setOpen(false);
+		setPinned(false);
+		setKeyboard(false);
+	}, []);
+
+	useEffect(() => {
+		if (!open) return;
+		const away = (event: PointerEvent) => {
+			if (!root.current?.contains(event.target as Node)) close();
+		};
+		const key = (event: KeyboardEvent) => {
+			if (event.key === "Escape") close();
+		};
+		document.addEventListener("pointerdown", away);
+		document.addEventListener("keydown", key);
+		return () => {
+			document.removeEventListener("pointerdown", away);
+			document.removeEventListener("keydown", key);
+		};
+	}, [open, close]);
+
+	// Opens from the icon's left edge, then slides left just far enough to
+	// stay on screen, and never past the screen's left edge.
+	useLayoutEffect(() => {
+		if (!open || !bubble.current || !root.current) return;
+		const icon = root.current.getBoundingClientRect();
+		const width = bubble.current.getBoundingClientRect().width;
+		const room = document.documentElement.clientWidth - 8;
+		const slide = Math.min(0, room - (icon.left + width));
+		setShift(Math.max(slide, 8 - icon.left));
+	}, [open]);
+
+	return (
+		// biome-ignore lint/a11y/noStaticElementInteractions: focusout bubbles to the root so focus leaving the button or the bubble closes it
+		<span
+			ref={root}
+			className={["hint", className].filter(Boolean).join(" ")}
+			data-side={side}
+			data-open={open || undefined}
+			onBlur={(event) => {
+				// Focus moving between the button and the bubble is not leaving.
+				if (root.current?.contains(event.relatedTarget as Node | null)) return;
+				close();
+			}}
+			onPointerEnter={(event) => {
+				// A finger never hovers: a tap opens through the click instead.
+				if (event.pointerType !== "touch") setOpen(true);
+			}}
+			onPointerLeave={(event) => {
+				if (event.pointerType === "touch" || pinned || keyboard) return;
+				setOpen(false);
+			}}
+		>
+			<button
+				type="button"
+				aria-label={label}
+				aria-describedby={id}
+				aria-expanded={open}
+				onFocus={(event) => {
+					// :focus-visible is the browser's own word for keyboard focus; a press
+					// that focuses the button does not match it. Where the selector is
+					// unknown, focus counts as the keyboard's.
+					let visible = true;
+					try {
+						visible = event.currentTarget.matches(":focus-visible");
+					} catch {
+						visible = true;
+					}
+					if (visible) {
+						setKeyboard(true);
+						setOpen(true);
+					}
+				}}
+				onClick={() => {
+					if (pinned) close();
+					else {
+						setPinned(true);
+						setOpen(true);
+					}
+				}}
+			>
+				<Info size={14} aria-hidden="true" />
+			</button>
+			<span
+				ref={bubble}
+				role="tooltip"
+				id={id}
+				className="hint-bubble"
+				style={shift ? { left: shift } : undefined}
+				// A press on the bubble's text must not pull focus off the button.
+				onMouseDown={(event) => event.preventDefault()}
+			>
+				{children}
+			</span>
+		</span>
+	);
+}

package/src/components/index.ts

@@ -23,6 +23,7 @@ export {
 	type DisclosureProps,
 } from "./Disclosure";
 export { GateLogin, type GateLoginProps } from "./GateLogin";
+export { Hint, type HintProps } from "./Hint";
 export { IconList, type IconListItem, type IconListProps } from "./IconList";
 export { NotFound, type NotFoundProps } from "./NotFound";
 export { Rank, type RankProps } from "./Rank";

package/src/styles/components.css

@@ -899,6 +899,78 @@
 		white-space: nowrap;
 	}
 
+	/* ---- Hint: an info icon that opens a short bubble on hover, focus, or a
+	   tap, from the icon's left edge unless that runs off the screen; hidden
+	   in print ---- */
+	.atelic-ui .hint {
+		position: relative;
+		display: inline-block;
+		vertical-align: middle;
+		margin-left: 4px;
+		line-height: 0;
+	}
+	.atelic-ui .hint[data-side="before"] {
+		margin: 0 4px 0 0;
+	}
+	.atelic-ui .hint > button {
+		display: inline-grid;
+		place-items: center;
+		width: 18px;
+		height: 18px;
+		padding: 0;
+		border: 0;
+		border-radius: 999px;
+		background: transparent;
+		color: var(--neutral-500);
+		cursor: pointer;
+	}
+	.atelic-ui .hint > button:hover,
+	.atelic-ui .hint > button:focus-visible,
+	.atelic-ui .hint[data-open] > button {
+		color: var(--ink);
+	}
+	.atelic-ui .hint-bubble {
+		display: none;
+		position: absolute;
+		top: calc(100% + 6px);
+		left: 0;
+		z-index: 20;
+		width: max-content;
+		max-width: min(280px, 80vw);
+		padding: 8px 10px;
+		border: 1px solid var(--neutral-200);
+		border-radius: var(--radius-sm);
+		background: var(--ui-card, var(--card));
+		box-shadow: var(--shadow-md, 0 6px 20px rgb(0 0 0 / 0.1));
+		color: var(--ink);
+		font-family: var(--font-sans, inherit);
+		font-size: 0.8rem;
+		font-weight: 400;
+		line-height: 1.45;
+		letter-spacing: normal;
+		text-transform: none;
+		text-align: left;
+		white-space: normal;
+		text-wrap: pretty;
+	}
+	/* Bridges the gap to the icon so the pointer can cross into the bubble. */
+	.atelic-ui .hint-bubble::before {
+		content: "";
+		position: absolute;
+		left: 0;
+		right: 0;
+		top: -8px;
+		height: 8px;
+	}
+	.atelic-ui .hint[data-open] .hint-bubble {
+		display: block;
+	}
+	@media print {
+		.atelic-ui .hint {
+			display: none;
+		}
+	}
+
 	/* ---- DataTable: on a phone each row stacks, its facts wearing their
 	   column's label, and a dropdown sorts; wide, it is a table whose
 	   headings sort ---- */
@@ -1058,6 +1130,19 @@
 			flex: none;
 			opacity: 0.55;
 		}
+		/* A Hint's button is not a sort button: keep its own look against the bare heading rules. */
+		.atelic-ui .data-table thead th .hint > button {
+			display: inline-grid;
+			color: var(--neutral-500);
+		}
+		.atelic-ui .data-table thead th .hint > button:hover,
+		.atelic-ui .data-table thead th .hint > button:focus-visible,
+		.atelic-ui .data-table thead th .hint[data-open] > button {
+			color: var(--ink);
+		}
+		.atelic-ui .data-table thead th .hint > button svg {
+			opacity: 1;
+		}
 		.atelic-ui .data-table thead th button[data-active] svg {
 			opacity: 1;
 		}
@@ -1076,6 +1161,12 @@
 			border-bottom: 0;
 		}
 	}
+	/* The phone hides the heading row, so a column hint goes with it. */
+	@media screen and (width < 721px) {
+		.atelic-ui .data-table thead .hint {
+			display: none;
+		}
+	}
 	@media print {
 		.atelic-ui .data-table thead th button svg {
 			display: none;