@vitavision/ui 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitavision/ui",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "The vitavision instrument design system: Tailwind v4 tokens, theme, and React primitives.",
   "license": "MIT OR Apache-2.0",
   "repository": {

package/src/components/ui/Breakdown.tsx

@@ -0,0 +1,139 @@
+/*
+ * Counts by category, as one thin stacked bar.
+ *
+ * The segments may use the verdict colours because each one counts things the app has already
+ * judged: strings it passed, strings it flagged, strings that failed a check. That is the only
+ * licence. A share of a continuous quantity, or one series beside another, is not a verdict and
+ * belongs on a chart.
+ *
+ * It is a `role="img"`: the bar is one picture whose meaning is its name. `progressbar` and
+ * `meter` carry a single value, and a `list` of segments would make a reader step through
+ * parts of a glyph that is meant to be taken in at once. The name is the counts in words, so
+ * colour is never the only cue.
+ *
+ * Widths are flex grow factors rather than percentages, so the one-pixel gaps that keep two
+ * neighbouring colours apart come out of the bar and not off its end. The layout is inline
+ * rather than classes, so the shares and the 2 px floor hold under any stylesheet.
+ */
+
+import type { ComponentProps } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { cn } from "./cn";
+
+/** Counts written the same on the server and in every browser: `2,556`, `0.5`. */
+const count = new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 });
+
+/**
+ * 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).
+ */
+export type BreakdownTone = "normal" | "warn" | "defect" | "neutral";
+
+/** One category of a `Breakdown`: how many, in which colour, and what a reader calls them. */
+export 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. */
+export 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;
+}
+
+const TONE_CLASSES: Record<BreakdownTone, string> = {
+  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) => (Number.isFinite(value) && value > 0 ? value : 0);
+
+/** The segments that are drawn, the whole, and the rest of it. */
+function measure(segments: readonly BreakdownSegment[], total: number | undefined) {
+  const shown = segments.filter((segment) => amount(segment.value) > 0);
+  const sum = shown.reduce((acc, segment) => acc + amount(segment.value), 0);
+  const whole = total !== undefined && 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.
+ */
+export function breakdownText(segments: readonly BreakdownSegment[], options: BreakdownTextOptions = {}): string {
+  const { shown, whole, rest } = measure(segments, options.total);
+  const parts = shown.map((segment) => `${count.format(amount(segment.value))} ${segment.label}`);
+  if (options.remainderLabel !== undefined && rest > 0) parts.push(`${count.format(rest)} ${options.remainderLabel}`);
+  return `${parts.length > 0 ? parts.join(", ") : "0"} of ${count.format(whole)}`;
+}
+
+/** Props of `Breakdown`: the segments and their total, plus the `<div>` props. */
+export 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 function Breakdown({ segments, total, remainderLabel, className, "aria-label": ariaLabel, ...rest }: BreakdownProps) {
+  const density = useDensity();
+  const { shown, sum, rest: remainder } = measure(segments, total);
+  const name = ariaLabel ?? (rest["aria-labelledby"] ? undefined : breakdownText(segments, { total, remainderLabel }));
+  return (
+    <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 }}
+    >
+      {shown.map((segment) => (
+        <div
+          key={segment.label}
+          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 }}
+        />
+      ))}
+      {remainder > 0 && <div className="h-full transition-[flex-grow] duration-300" style={{ flex: `${remainder} 0 0` }} />}
+    </div>
+  );
+}

package/src/components/ui/Table.tsx

@@ -102,7 +102,8 @@ const SORT_ICONS = { ascending: ArrowUp, descending: ArrowDown, none: ArrowUpDow
  * 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.
  */
@@ -121,6 +122,7 @@ export function Table<Row>({
   onSortChange,
   manualSort = false,
   windowed,
+  selectionFollowsFocus = false,
 }: {
   /** The columns, in order. */
   columns: Column<Row>[];
@@ -170,6 +172,15 @@ export function Table<Row>({
    * 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;
 }) {
   const density = useDensity();
   const [ownSort, setOwnSort] = useState<TableSort | null>(defaultSort);
@@ -202,18 +213,25 @@ export function Table<Row>({
     : { start: 0, end: order.length, before: 0, after: 0 };
 
   const isWindowed = windowed !== undefined;
+  // With no rows the scroll area is replaced by the `empty` message: measure the new one when
+  // the rows come back, rather than keep observing the one that went away.
+  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 = () => {
+      // A detached element measures 0, which would shrink the window to a row or two.
+      if (!scroller.isConnected) return;
       const next = { viewport: scroller.clientHeight, header: headRef.current?.offsetHeight ?? 0 };
       setMeasured((last) => (last?.viewport === next.viewport && last.header === next.header ? last : next));
     };
     measure();
+    // A new scroll area starts at the top, whatever the last one was scrolled to.
+    setScrollTop(scroller.scrollTop);
     const observer = new ResizeObserver(measure);
     observer.observe(scroller);
     return () => observer.disconnect();
-  }, [isWindowed]);
+  }, [isWindowed, hasRows]);
 
   useLayoutEffect(() => {
     const target = pendingFocus.current;
@@ -224,11 +242,18 @@ export function Table<Row>({
     row.focus({ preventScroll: isWindowed });
   });
 
-  /** Moves focus from the row at `position` for a navigation key; `true` when the key was one. */
-  const moveFocus = (key: string, position: number): boolean => {
+  /**
+   * 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: KeyboardEvent<HTMLTableRowElement>, position: number): boolean => {
     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) {
@@ -237,10 +262,12 @@ export function Table<Row>({
       // Render the target's window now rather than on the scroll event, so it can take focus.
       setScrollTop(scroller.scrollTop);
     }
+    // A row already in the DOM takes focus now: when nothing scrolled, nothing re-renders, and
+    // the pending focus would wait for a render that never comes.
     const row = bodyRef.current?.querySelector<HTMLElement>(`tr[data-position="${target}"]`);
-    if (row && !windowed) {
+    if (row) {
       pendingFocus.current = null;
-      row.focus();
+      row.focus({ preventScroll: windowed !== undefined });
     }
     return true;
   };
@@ -375,7 +402,7 @@ export function Table<Row>({
                           event.preventDefault();
                           onRowClick(row, index, event);
                           // Navigation keys belong to a control inside the row while it has focus.
-                        } else if (event.target === event.currentTarget && moveFocus(event.key, position)) event.preventDefault();
+                        } else if (event.target === event.currentTarget && moveFocus(event, position)) event.preventDefault();
                       }
                     : undefined
                 }

package/src/components/ui/index.ts

@@ -8,6 +8,14 @@
 export { cn, focusRing, focusRingInset } from "./cn";
 
 export { Badge, CountRun, StatusDot, type Tone } from "./Badge";
+export {
+  Breakdown,
+  breakdownText,
+  type BreakdownProps,
+  type BreakdownSegment,
+  type BreakdownTextOptions,
+  type BreakdownTone,
+} from "./Breakdown";
 export { Button, ButtonLink, buttonClasses, type ButtonSize, type ButtonVariant } from "./Button";
 export { DensityProvider, byDensity, useDensity, type Density } from "./Density";
 export { ConfirmDialog, Dialog, DialogClose } from "./Dialog";