@vitavision/ui 0.13.0 → 0.14.0

package/README.md

@@ -126,13 +126,13 @@ keep independent preferences.
 `DialogClose` · `Disclosure` · `DropdownMenu`, `MenuItem`, `MenuCheckboxItem`, `MenuLabel`,
 `MenuSeparator` (a non-modal command and toggle menu) · `Callout`, `Empty`, `ErrorBox`,
 `Skeleton`, `SkeletonRows` · `Progress` (a count out of a total, or indeterminate; `ProgressBar` is
-deprecated) · `Field` · `Input`, `NumberInput` (with an optional
+deprecated) · `Breakdown`, `breakdownText` (counts by verdict as one thin stacked bar) · `Field` · `Input`, `NumberInput` (with an optional
 `unit` written in the field; number-valued with `onValueChange`), `Textarea` (optionally growing
 with its content between `minRows` and `maxRows`) · `HighlightedText`, `findSpans` (a string
 with its placeholders, tags and terms marked, never parsed as HTML) · `VectorInput`,
 `PoseInput` · `Kbd` · `Listbox` (single choice among options that render their own content) ·
 `PageHeader`, `Panel`, `ReadoutStrip`, `Section` · `Popover`, `PopoverClose` ·
-`SegmentedControl` · `Select` · `Slider` · `Table` (with `windowed` for thousands of rows) ·
+`SegmentedControl` · `Select` · `Slider` · `Table` (with `windowed` for thousands of rows, and `selectionFollowsFocus` for keyboard selection) ·
 `Checkbox`, `Switch` · `ToggleChip` · `Toaster`, `toast()` (notifications from anywhere; mount one `<Toaster />` near the root) ·
 `InfoHint`, `Tooltip`, `TooltipProvider` ·
 `ThemeToggle` · plus `cn`, `focusRing`, `focusRingInset`, and `formatNumber` / `parseNumber`

package/dist/index.d.ts

@@ -154,6 +154,69 @@ export declare function CountRun({ counts, className }: {
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/Breakdown.d.ts
+/**
+ * The colour of a `Breakdown` segment: a verdict (`normal`, `warn`, `defect`) for things the app
+ * has judged, or `neutral` for a category that is no verdict (skipped, not applicable).
+ */
+type BreakdownTone = "normal" | "warn" | "defect" | "neutral";
+/** One category of a `Breakdown`: how many, in which colour, and what a reader calls them. */
+interface BreakdownSegment {
+  /** How many. Negative and non-finite values count as 0, and a segment of 0 is left out. */
+  value: number;
+  /** The colour, by meaning. */
+  tone: BreakdownTone;
+  /** What the count is, as it reads after the number: `"done"` gives "412 done". Unique among the segments. */
+  label: string;
+}
+/** Options of `breakdownText`, the same as the `Breakdown` props of the same names. */
+interface BreakdownTextOptions {
+  /** The whole. Defaults to the sum of the segments; a total below the sum counts as the sum. */
+  total?: number | undefined;
+  /** What the rest of the total is, as it reads after the number: `"to do"` gives "131 to do". */
+  remainderLabel?: string | undefined;
+}
+/**
+ * The counts of a breakdown in words: `"412 done, 20 to check, 3 problems, 131 to do of 566"`.
+ *
+ * It is the default accessible name of `Breakdown`, and the text for a tooltip or a label printed
+ * beside the bar. Segments of 0 are left out; the rest of the total is named only with a
+ * `remainderLabel`. With nothing to count it reads `"0 of 566"`.
+ *
+ * @param segments - The categories, in order.
+ * @param options - The `total` and the `remainderLabel`.
+ * @returns The text.
+ */
+export declare function breakdownText(segments: readonly BreakdownSegment[], options?: BreakdownTextOptions): string;
+/** Props of `Breakdown`: the segments and their total, plus the `<div>` props. */
+type BreakdownProps = Omit<ComponentProps<"div">, "children" | "role"> & {
+  /** The categories, drawn left to right in this order, each as wide as its share of the total. */
+  segments: readonly BreakdownSegment[];
+  /**
+   * The whole. Defaults to the sum of the segments; the rest is drawn as empty track. A total
+   * below the sum counts as the sum.
+   */
+  total?: number | undefined;
+  /** What the empty track counts, for the accessible name: `"to do"` gives "131 to do". */
+  remainderLabel?: string | undefined;
+};
+/**
+ * A thin bar of counts by category: 412 done, 20 to check and 3 problems out of 566, with the
+ * rest as empty track. Segments are drawn in the order given, each as wide as its share of the
+ * total (a non-zero count is never narrower than 2 px); segments of 0 are left out.
+ *
+ * Its colours are verdicts, so use it only for things the app has judged — never for a share of
+ * a continuous quantity or for series side by side (use `Progress` or a chart).
+ *
+ * A `role="img"` whose name lists every non-zero count, as `breakdownText` writes it: "412 done,
+ * 20 to check, 3 problems, 131 to do of 566". `aria-label` or `aria-labelledby` replaces it. The track
+ * matches `Progress` and follows the density in force. State is exposed as `data-state`
+ * (`"empty"` with nothing counted, `"partial"`, or `"complete"` when the segments fill the
+ * total), and each segment's tone as its `data-tone`. Width changes ease over 300 ms, and not at
+ * all with reduced motion.
+ */
+export declare function Breakdown({ segments, total, remainderLabel, className, "aria-label": ariaLabel, ...rest }: BreakdownProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Button.d.ts
 /**
  * A button's look, by what the action is: `primary` for the one action a screen is for,
@@ -1198,11 +1261,12 @@ interface TableWindowing {
  * show it and the rows render as given. Row callbacks always receive a row's index in `rows`,
  * whatever the order on screen.
  *
- * Activatable rows also move focus with the arrow keys, Page Up / Page Down and Home / End.
+ * Activatable rows also move focus with the arrow keys, Page Up / Page Down and Home / End;
+ * with `selectionFollowsFocus` each of those moves also activates the row it lands on.
  * With `windowed` the table scrolls itself (vertically, under a sticky header), renders only the
  * rows in view, and uses a fixed layout: give columns a `width` where the content needs it.
  */
-export declare function Table<Row>({ columns, rows, rowKey, empty, caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort, onSortChange, manualSort, windowed }: {
+export declare function Table<Row>({ columns, rows, rowKey, empty, caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort, onSortChange, manualSort, windowed, selectionFollowsFocus }: {
   /** The columns, in order. */
   columns: Column<Row>[];
   /** The rows, in their own order: the order shown while the table is not sorted. */
@@ -1251,6 +1315,15 @@ export declare function Table<Row>({ columns, rows, rowKey, empty, caption, clas
    * callbacks and keyboard navigation work as without it.
    */
   windowed?: TableWindowing | undefined;
+  /**
+   * Activate a row as soon as the keyboard moves to it: each arrow key, Page Up / Page Down,
+   * Home or End that lands on another row also calls `onRowClick` for that row, with the key
+   * press as the event — selection follows focus, as in a list where the selected item shows
+   * its detail beside the list. Clicks, Enter and Space work as without it. Leave it off when
+   * activating a row is costly or navigates away: then a reader can move through the rows and
+   * choose one. Needs `onRowClick`.
+   */
+  selectionFollowsFocus?: boolean | undefined;
 }): import("react").JSX.Element;
 //#endregion
 //#region src/components/ui/Textarea.d.ts
@@ -1586,5 +1659,5 @@ export declare function Tabs<Id extends string>({ items, active, onSelect, label
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
-export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, DropdownMenuProps, HighlightKind, HighlightRule, HighlightSpan, HighlightedTextProps, ListboxOption, ListboxOptionState, ListboxProps, MeasureTone, MenuCheckboxItemProps, MenuItemProps, NumberInputProps, PopoverProps, PoseInputProps, PoseValue, ProgressProps, Quaternion, ReadoutItem, RotationView, SelectOption, SortDirection, TabItem, TableSort, TableWindowing, TextareaProps, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
+export type { BackLink, BreakdownProps, BreakdownSegment, BreakdownTextOptions, BreakdownTone, ButtonSize, ButtonVariant, CalloutTone, Column, Density, DropdownMenuProps, HighlightKind, HighlightRule, HighlightSpan, HighlightedTextProps, ListboxOption, ListboxOptionState, ListboxProps, MeasureTone, MenuCheckboxItemProps, MenuItemProps, NumberInputProps, PopoverProps, PoseInputProps, PoseValue, ProgressProps, Quaternion, ReadoutItem, RotationView, SelectOption, SortDirection, TabItem, TableSort, TableWindowing, TextareaProps, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -246,7 +246,7 @@ function ThemeToggle({ storageKey = DEFAULT_THEME_STORAGE_KEY, className }) {
 }
 //#endregion
 //#region src/components/ui/Badge.tsx
-const TONE_CLASSES = {
+const TONE_CLASSES$1 = {
 	neutral: "bg-raised text-fg-muted ring-line",
 	normal: "bg-normal/12 text-normal ring-normal/25",
 	defect: "bg-defect/12 text-defect ring-defect/25",
@@ -271,7 +271,7 @@ const DOT_CLASSES = {
 function Badge({ tone = "neutral", className, children }) {
 	return /* @__PURE__ */ jsx("span", {
 		"data-tone": tone,
-		className: cn("inline-flex items-center gap-1 rounded-control px-1.5 py-0.5 text-xs font-medium ring-1 ring-inset", TONE_CLASSES[tone], className),
+		className: cn("inline-flex items-center gap-1 rounded-control px-1.5 py-0.5 text-xs font-medium ring-1 ring-inset", TONE_CLASSES$1[tone], className),
 		children
 	});
 }
@@ -346,6 +346,93 @@ function DensityProvider({ value, children }) {
 	});
 }
 //#endregion
+//#region src/components/ui/Breakdown.tsx
+/** Counts written the same on the server and in every browser: `2,556`, `0.5`. */
+const count$1 = new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 });
+const TONE_CLASSES = {
+	normal: "bg-normal",
+	warn: "bg-warn",
+	defect: "bg-defect",
+	neutral: "bg-fg-subtle"
+};
+/** A count as drawn: 0 for anything that is not a finite, positive number. */
+const amount = (value) => Number.isFinite(value) && value > 0 ? value : 0;
+/** The segments that are drawn, the whole, and the rest of it. */
+function measure(segments, total) {
+	const shown = segments.filter((segment) => amount(segment.value) > 0);
+	const sum = shown.reduce((acc, segment) => acc + amount(segment.value), 0);
+	const whole = total !== void 0 && Number.isFinite(total) && total > sum ? total : sum;
+	return {
+		shown,
+		sum,
+		whole,
+		rest: whole - sum
+	};
+}
+/**
+* The counts of a breakdown in words: `"412 done, 20 to check, 3 problems, 131 to do of 566"`.
+*
+* It is the default accessible name of `Breakdown`, and the text for a tooltip or a label printed
+* beside the bar. Segments of 0 are left out; the rest of the total is named only with a
+* `remainderLabel`. With nothing to count it reads `"0 of 566"`.
+*
+* @param segments - The categories, in order.
+* @param options - The `total` and the `remainderLabel`.
+* @returns The text.
+*/
+function breakdownText(segments, options = {}) {
+	const { shown, whole, rest } = measure(segments, options.total);
+	const parts = shown.map((segment) => `${count$1.format(amount(segment.value))} ${segment.label}`);
+	if (options.remainderLabel !== void 0 && rest > 0) parts.push(`${count$1.format(rest)} ${options.remainderLabel}`);
+	return `${parts.length > 0 ? parts.join(", ") : "0"} of ${count$1.format(whole)}`;
+}
+/**
+* A thin bar of counts by category: 412 done, 20 to check and 3 problems out of 566, with the
+* rest as empty track. Segments are drawn in the order given, each as wide as its share of the
+* total (a non-zero count is never narrower than 2 px); segments of 0 are left out.
+*
+* Its colours are verdicts, so use it only for things the app has judged — never for a share of
+* a continuous quantity or for series side by side (use `Progress` or a chart).
+*
+* A `role="img"` whose name lists every non-zero count, as `breakdownText` writes it: "412 done,
+* 20 to check, 3 problems, 131 to do of 566". `aria-label` or `aria-labelledby` replaces it. The track
+* matches `Progress` and follows the density in force. State is exposed as `data-state`
+* (`"empty"` with nothing counted, `"partial"`, or `"complete"` when the segments fill the
+* total), and each segment's tone as its `data-tone`. Width changes ease over 300 ms, and not at
+* all with reduced motion.
+*/
+function Breakdown({ segments, total, remainderLabel, className, "aria-label": ariaLabel, ...rest }) {
+	const density = useDensity();
+	const { shown, sum, rest: remainder } = measure(segments, total);
+	const name = ariaLabel ?? (rest["aria-labelledby"] ? void 0 : breakdownText(segments, {
+		total,
+		remainderLabel
+	}));
+	return /* @__PURE__ */ jsxs("div", {
+		role: "img",
+		"aria-label": name,
+		"data-state": sum === 0 ? "empty" : remainder > 0 ? "partial" : "complete",
+		...rest,
+		className: cn("w-full overflow-hidden rounded-full bg-line", byDensity(density, "h-1.5", "h-1"), className),
+		style: {
+			display: "flex",
+			gap: 1,
+			...rest.style
+		},
+		children: [shown.map((segment) => /* @__PURE__ */ jsx("div", {
+			"data-tone": segment.tone,
+			className: cn("h-full transition-[flex-grow] duration-300", TONE_CLASSES[segment.tone]),
+			style: {
+				flex: `${amount(segment.value)} 0 0`,
+				minWidth: 2
+			}
+		}, segment.label)), remainder > 0 && /* @__PURE__ */ jsx("div", {
+			className: "h-full transition-[flex-grow] duration-300",
+			style: { flex: `${remainder} 0 0` }
+		})]
+	});
+}
+//#endregion
 //#region src/components/ui/Button.tsx
 const VARIANT_CLASSES = {
 	primary: "bg-signal text-signal-fg hover:bg-signal-strong",
@@ -2100,11 +2187,12 @@ const SORT_ICONS = {
 * show it and the rows render as given. Row callbacks always receive a row's index in `rows`,
 * whatever the order on screen.
 *
-* Activatable rows also move focus with the arrow keys, Page Up / Page Down and Home / End.
+* Activatable rows also move focus with the arrow keys, Page Up / Page Down and Home / End;
+* with `selectionFollowsFocus` each of those moves also activates the row it lands on.
 * With `windowed` the table scrolls itself (vertically, under a sticky header), renders only the
 * rows in view, and uses a fixed layout: give columns a `width` where the content needs it.
 */
-function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort = null, onSortChange, manualSort = false, windowed }) {
+function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort = null, onSortChange, manualSort = false, windowed, selectionFollowsFocus = false }) {
 	const density = useDensity();
 	const [ownSort, setOwnSort] = useState(defaultSort);
 	const controlled = controlledSort !== void 0;
@@ -2143,10 +2231,12 @@ function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, classN
 		after: 0
 	};
 	const isWindowed = windowed !== void 0;
+	const hasRows = rows.length > 0;
 	useLayoutEffect(() => {
 		const scroller = scrollRef.current;
-		if (!isWindowed || !scroller || typeof ResizeObserver === "undefined") return;
+		if (!isWindowed || !hasRows || !scroller || typeof ResizeObserver === "undefined") return;
 		const measure = () => {
+			if (!scroller.isConnected) return;
 			const next = {
 				viewport: scroller.clientHeight,
 				header: headRef.current?.offsetHeight ?? 0
@@ -2154,10 +2244,11 @@ function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, classN
 			setMeasured((last) => last?.viewport === next.viewport && last.header === next.header ? last : next);
 		};
 		measure();
+		setScrollTop(scroller.scrollTop);
 		const observer = new ResizeObserver(measure);
 		observer.observe(scroller);
 		return () => observer.disconnect();
-	}, [isWindowed]);
+	}, [isWindowed, hasRows]);
 	useLayoutEffect(() => {
 		const target = pendingFocus.current;
 		if (target === null) return;
@@ -2166,11 +2257,18 @@ function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, classN
 		pendingFocus.current = null;
 		row.focus({ preventScroll: isWindowed });
 	});
-	/** Moves focus from the row at `position` for a navigation key; `true` when the key was one. */
-	const moveFocus = (key, position) => {
+	/**
+	* Moves focus from the row at `position` for a navigation key, activating the new row when
+	* selection follows focus; `true` when the key was one.
+	*/
+	const moveFocus = (event, position) => {
 		const page = windowed ? Math.floor((viewportHeight - headerHeight) / rowHeight) : 10;
-		const target = navigate(key, position, order.length, page);
+		const target = navigate(event.key, position, order.length, page);
 		if (target === null) return false;
+		if (selectionFollowsFocus && onRowClick && target !== position) {
+			const index = order[target];
+			onRowClick(rows[index], index, event);
+		}
 		pendingFocus.current = target;
 		const scroller = scrollRef.current;
 		if (windowed && scroller) {
@@ -2183,9 +2281,9 @@ function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, classN
 			setScrollTop(scroller.scrollTop);
 		}
 		const row = bodyRef.current?.querySelector(`tr[data-position="${target}"]`);
-		if (row && !windowed) {
+		if (row) {
 			pendingFocus.current = null;
-			row.focus();
+			row.focus({ preventScroll: windowed !== void 0 });
 		}
 		return true;
 	};
@@ -2278,7 +2376,7 @@ function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, classN
 									if (event.key === "Enter" || event.key === " ") {
 										event.preventDefault();
 										onRowClick(row, index, event);
-									} else if (event.target === event.currentTarget && moveFocus(event.key, position)) event.preventDefault();
+									} else if (event.target === event.currentTarget && moveFocus(event, position)) event.preventDefault();
 								} : void 0,
 								onPointerEnter: onRowHover ? () => onRowHover(row, index) : void 0,
 								onPointerLeave: onRowHover ? () => onRowHover(null, null) : void 0,
@@ -2754,6 +2852,6 @@ function Tabs({ items, active, onSelect, label, idPrefix, className }) {
 	});
 }
 //#endregion
-export { Badge, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, DropdownMenu, Empty, ErrorBox, Field, HighlightedText, InfoHint, Input, Kbd, Listbox, MenuCheckboxItem, MenuItem, MenuLabel, MenuSeparator, NumberInput, PageHeader, Panel, Popover, PopoverClose, PoseInput, Progress, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, Toaster, ToggleChip, Tooltip, TooltipProvider, VectorInput, buttonClasses, byDensity, cn, controlClasses, createToastStore, defaultToastStore, findSpans, focusRing, focusRingInset, formatNumber, initTheme, inputClasses, parseNumber, progressText, readThemeChoice, resolveTheme, setThemeChoice, sortRows, toast, toneColor, useControlHeight, useDensity };
+export { Badge, Breakdown, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, DropdownMenu, Empty, ErrorBox, Field, HighlightedText, InfoHint, Input, Kbd, Listbox, MenuCheckboxItem, MenuItem, MenuLabel, MenuSeparator, NumberInput, PageHeader, Panel, Popover, PopoverClose, PoseInput, Progress, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, Toaster, ToggleChip, Tooltip, TooltipProvider, VectorInput, breakdownText, buttonClasses, byDensity, cn, controlClasses, createToastStore, defaultToastStore, findSpans, focusRing, focusRingInset, formatNumber, initTheme, inputClasses, parseNumber, progressText, readThemeChoice, resolveTheme, setThemeChoice, sortRows, toast, toneColor, useControlHeight, useDensity };
 
 //# sourceMappingURL=index.js.map