@tensor_1/react 2.38.0 → 2.40.0

package/dist/components/InsightCard.js

@@ -0,0 +1,118 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "../cx.js";
+import { CircleCheckIcon, CircleQuestionMarkIcon, OctagonAlertIcon, TriangleAlertIcon } from "../icons/components.js";
+const defaultNumber = new Intl.NumberFormat("en", { maximumFractionDigits: 1 });
+const DEFAULT_INSIGHT_CARD_LABELS = {
+  coverage: (covered, total, percent, note) => /* @__PURE__ */ jsxs(Fragment, { children: [
+    covered,
+    " of ",
+    total,
+    " ",
+    note,
+    " (",
+    percent,
+    "%)"
+  ] }),
+  bullet: (actual, target) => `${actual} against a target of ${target}`,
+  source: "Source",
+  updated: "Updated",
+  kpis: "Key figures",
+  formatNumber: (value) => defaultNumber.format(value)
+};
+const STATUS_ICON = {
+  ok: CircleCheckIcon,
+  warning: TriangleAlertIcon,
+  critical: OctagonAlertIcon,
+  unknown: CircleQuestionMarkIcon
+};
+function InsightCard({
+  eyebrow,
+  headline,
+  sowhat,
+  status,
+  kpis,
+  coverage,
+  actions,
+  source,
+  updated,
+  layout = "stack",
+  variant = "card",
+  aside,
+  headingLevel = 3,
+  labels: labelOverrides,
+  className,
+  children,
+  ...props
+}) {
+  const labels = { ...DEFAULT_INSIGHT_CARD_LABELS, ...labelOverrides };
+  const Heading = `h${headingLevel}`;
+  const StatusIcon = status ? STATUS_ICON[status.tone] : null;
+  const percent = coverage && coverage.total > 0 ? Math.round(coverage.covered / coverage.total * 100) : null;
+  const hasFooter = coverage != null || source != null || updated != null || actions != null;
+  return /* @__PURE__ */ jsxs("article", { className: cx("uix-insight", variant === "plain" && "uix-insight--plain", className), "data-layout": layout, ...props, children: [
+    /* @__PURE__ */ jsxs("header", { className: "uix-insight__header", children: [
+      /* @__PURE__ */ jsxs("div", { className: "uix-insight__heading", children: [
+        eyebrow != null ? /* @__PURE__ */ jsx("div", { className: "uix-insight__eyebrow", children: eyebrow }) : null,
+        /* @__PURE__ */ jsx(Heading, { className: "uix-insight__headline", children: headline }),
+        sowhat != null ? /* @__PURE__ */ jsx("p", { className: "uix-insight__sowhat", children: sowhat }) : null
+      ] }),
+      status && StatusIcon ? /* @__PURE__ */ jsxs("span", { className: "uix-insight__status", "data-tone": status.tone, children: [
+        /* @__PURE__ */ jsx(StatusIcon, { size: "sm", "aria-hidden": "true" }),
+        /* @__PURE__ */ jsx("span", { children: status.label })
+      ] }) : null
+    ] }),
+    kpis?.length ? /* @__PURE__ */ jsx("dl", { className: "uix-insight__kpis", "aria-label": labels.kpis, children: kpis.map((kpi, index) => /* @__PURE__ */ jsxs("div", { className: "uix-insight__kpi", children: [
+      /* @__PURE__ */ jsx("dt", { className: "uix-insight__kpi-label", children: kpi.label }),
+      /* @__PURE__ */ jsx("dd", { className: "uix-insight__kpi-value", children: kpi.value }),
+      kpi.comparison ? /* @__PURE__ */ jsx("dd", { className: "uix-insight__kpi-comparison", "data-tone": kpi.comparison.tone ?? "neutral", children: kpi.comparison.text }) : null,
+      kpi.target ? /* @__PURE__ */ jsx("dd", { className: "uix-insight__kpi-target", children: /* @__PURE__ */ jsx(Bullet, { ...kpi.target, label: labels.bullet(labels.formatNumber(kpi.target.actual), labels.formatNumber(kpi.target.target)) }) }) : null
+    ] }, index)) }) : null,
+    children != null || aside != null ? /* @__PURE__ */ jsxs("div", { className: "uix-insight__body", children: [
+      children != null ? /* @__PURE__ */ jsx("div", { className: "uix-insight__main", children }) : null,
+      aside != null ? /* @__PURE__ */ jsx("div", { className: "uix-insight__aside", children: aside }) : null
+    ] }) : null,
+    hasFooter ? /* @__PURE__ */ jsxs("footer", { className: "uix-insight__footer", children: [
+      /* @__PURE__ */ jsxs("div", { className: "uix-insight__meta", children: [
+        coverage && percent != null ? /* @__PURE__ */ jsxs("p", { className: "uix-insight__coverage", children: [
+          labels.coverage(coverage.covered, coverage.total, percent, coverage.note),
+          coverage.partialPeriod != null ? /* @__PURE__ */ jsx("span", { className: "uix-insight__partial", children: coverage.partialPeriod }) : null
+        ] }) : null,
+        source != null || updated != null ? /* @__PURE__ */ jsxs("p", { className: "uix-insight__source", children: [
+          source != null ? /* @__PURE__ */ jsxs("span", { children: [
+            labels.source,
+            ": ",
+            source
+          ] }) : null,
+          updated != null ? /* @__PURE__ */ jsxs("span", { children: [
+            labels.updated,
+            ": ",
+            updated
+          ] }) : null
+        ] }) : null
+      ] }),
+      actions != null ? /* @__PURE__ */ jsx("div", { className: "uix-insight__actions", children: actions }) : null
+    ] }) : null
+  ] });
+}
+function Bullet({ actual, target, ranges, max, label, className, style, ...props }) {
+  const end = Math.max(max ?? 0, ...(ranges ?? []).map((r) => r[1]), actual, target, 0) * (max ? 1 : 1.1) || 1;
+  const pct = (value) => `${Math.max(0, Math.min(100, value / end * 100))}%`;
+  return /* @__PURE__ */ jsxs("div", { className: cx("uix-bullet", className), role: "img", "aria-label": label, style, ...props, children: [
+    (ranges ?? []).map(([from, to], index) => /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: "uix-bullet__range",
+        "data-band": Math.min(index, 2),
+        style: { left: pct(from), width: `calc(${pct(to)} - ${pct(from)})` }
+      },
+      index
+    )),
+    /* @__PURE__ */ jsx("span", { className: "uix-bullet__bar", style: { width: pct(actual) } }),
+    /* @__PURE__ */ jsx("span", { className: "uix-bullet__target", style: { left: pct(target) } })
+  ] });
+}
+export {
+  Bullet,
+  DEFAULT_INSIGHT_CARD_LABELS,
+  InsightCard
+};

package/dist/components/Markdown.d.ts

@@ -19,6 +19,12 @@ interface MarkdownProps {
      * (`#` → `<h3>` by default, as in TENSOR's original renderer). Capped at `<h6>`.
      */
     headingOffset?: number;
+    /**
+     * The name to show for a mention (`@[Name](mention:<id>)`), e.g. the person's current
+     * or masked name. Return `undefined` to show the name stored in the text. Without it
+     * every mention shows its stored name.
+     */
+    resolveMention?: (id: string, storedLabel: string) => string | undefined;
 }
 /**
  * Safe markdown viewer over `.uix-prose`. It never produces an HTML string and never
@@ -28,9 +34,10 @@ interface MarkdownProps {
  * Supports headings, paragraphs (single newline = line break), bold, italic,
  * strikethrough, inline and fenced code, links and bare http(s) URLs, blockquotes,
  * horizontal rules, nested bulleted/numbered lists, read-only task lists, GFM tables
- * (in a keyboard-scrollable wrapper) and images gated by `resolveImageSrc`.
+ * (in a keyboard-scrollable wrapper), images gated by `resolveImageSrc` and mentions
+ * (`@[Name](mention:<id>)`, drawn as `.uix-mention`, named by `resolveMention`).
  * Server-component safe.
  */
-declare function Markdown({ children, className, isSafeUrl, resolveImageSrc, headingOffset }: MarkdownProps): react.JSX.Element | null;
+declare function Markdown({ children, className, isSafeUrl, resolveImageSrc, headingOffset, resolveMention, }: MarkdownProps): react.JSX.Element | null;
 
 export { Markdown, type MarkdownProps, defaultMarkdownIsSafeUrl };

package/dist/components/Markdown.js

@@ -33,6 +33,13 @@ function renderInlines(nodes, policy) {
           i
         );
       }
+      case "mention": {
+        const name = policy.resolveMention?.(node.id, node.label) ?? node.label;
+        return /* @__PURE__ */ jsxs("span", { className: "uix-mention", "data-mention-id": node.id, children: [
+          "@",
+          name
+        ] }, i);
+      }
       case "image": {
         const resolved = policy.resolveImageSrc?.(node.src) ?? null;
         if (resolved) {
@@ -91,10 +98,17 @@ function renderBlock(block, policy, headingOffset, key) {
       );
   }
 }
-function Markdown({ children, className, isSafeUrl = defaultMarkdownIsSafeUrl, resolveImageSrc, headingOffset = 2 }) {
+function Markdown({
+  children,
+  className,
+  isSafeUrl = defaultMarkdownIsSafeUrl,
+  resolveImageSrc,
+  headingOffset = 2,
+  resolveMention
+}) {
   const source = typeof children === "string" ? children : "";
   if (source.trim() === "") return null;
-  const policy = { isSafeUrl, resolveImageSrc };
+  const policy = { isSafeUrl, resolveImageSrc, resolveMention };
   const blocks = parseMarkdown(source);
   return /* @__PURE__ */ jsx("div", { className: cx("uix-prose", "uix-markdown", className), "data-component": "markdown", children: blocks.map((block, i) => renderBlock(block, policy, headingOffset, i)) });
 }

package/dist/components/RichTextEditor.d.ts

@@ -2,7 +2,9 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { EmojiItem } from '@tiptap/extension-emoji';
 import { EmojiLocale } from '../emoji-model.js';
+import { MentionCandidate } from '../rich-text/mention.js';
 import { EmojiPickerLabels } from './EmojiPicker.js';
+import '@tiptap/core';
 import '../overlay-position.js';
 
 type RichTextFeatures = 'full' | 'comment' | 'template';
@@ -44,6 +46,14 @@ interface RichTextLabels {
     emoji: string;
     /** Accessible name of the `:shortcode` suggestion list. */
     emojiSuggestions: string;
+    /** Accessible name of the `@` people list. */
+    mentionSuggestions: string;
+    /** Shown while `onMentionSearch` has not answered. */
+    mentionSearching: string;
+    /** Shown when `onMentionSearch` found nobody. */
+    mentionEmpty: string;
+    /** Shown when `onMentionSearch` failed. */
+    mentionFailed: string;
     undo: string;
     redo: string;
     /** Toggle to markdown source. */
@@ -86,6 +96,13 @@ interface RichTextEditorProps {
     onSubmitShortcut?: () => void;
     /** Emoji button and `:shortcode` suggestions. Default `true`. */
     emoji?: boolean;
+    /**
+     * People for the `@` list: called with the text typed after `@` (possibly empty) and
+     * answering the candidates to offer. The product owns the query and who may be
+     * mentioned; UIx never fetches. A picked person is inserted as one token, stored as
+     * `@[Name](mention:<id>)`. Without it, typing `@` does nothing special.
+     */
+    onMentionSearch?: (query: string) => Promise<ReadonlyArray<MentionCandidate>> | ReadonlyArray<MentionCandidate>;
     /**
      * Same-origin folder of fallback emoji PNGs for devices without a colour emoji font
      * (e.g. `/static/emoji`). Emoji the device cannot draw show as

package/dist/components/RichTextEditor.js

@@ -24,6 +24,7 @@ import {
   readMarkdown,
   writeMarkdown
 } from "../rich-text/pipeline.js";
+import { isMentionId } from "../markdown-model.js";
 import { Composer, ComposerBar } from "./Composer.js";
 import { EditorIcon } from "./EditorIcons.js";
 import { EmojiPicker } from "./EmojiPicker.js";
@@ -62,6 +63,10 @@ const DEFAULT_RICH_TEXT_LABELS = {
   imagesUnsupported: "Images can't be added here.",
   emoji: "Emoji",
   emojiSuggestions: "Emoji suggestions",
+  mentionSuggestions: "People",
+  mentionSearching: "Searching\u2026",
+  mentionEmpty: "No matching people",
+  mentionFailed: "People could not be loaded.",
   undo: "Undo",
   redo: "Redo",
   sourceMode: "Show markdown",
@@ -92,6 +97,8 @@ function suggestEmoji(query, limit = 8) {
   }
   return [...starts, ...tagged].slice(0, limit);
 }
+const mentionSuggestionKey = new PluginKey("uixMentionSuggestion");
+const usableCandidates = (items) => items.filter((c) => isMentionId(c.id) && c.label.trim() !== "").slice(0, 20);
 const htmlAttr = (value) => value === void 0 || value === false || value === "" ? void 0 : String(value);
 const popoverOpen = (el) => {
   try {
@@ -190,8 +197,10 @@ function RichTextEditor(props) {
     className,
     onBlur,
     emojiImageBaseUrl,
-    imagesUnavailableReason
+    imagesUnavailableReason,
+    onMentionSearch
   } = props;
+  const mentionsOn = typeof onMentionSearch === "function";
   const emojiBase = useMemo(() => normalizeEmojiImageBaseUrl(emojiImageBaseUrl), [emojiImageBaseUrl]);
   const renderEmoji = useEmojiRenderer(emojiImageBaseUrl);
   const labels = useMemo(() => ({ ...DEFAULT_RICH_TEXT_LABELS, ...labelOverrides }), [labelOverrides]);
@@ -199,10 +208,11 @@ function RichTextEditor(props) {
   const counterId = `${uid}-counter`;
   const statusId = `${uid}-status`;
   const suggestId = `${uid}-emoji`;
+  const mentionId = `${uid}-people`;
   const linkPopoverId = `${uid}-link`;
   const controls = PRESETS[features];
   const has = (control) => controls.has(control) && (control !== "emoji" || emoji) && (control !== "image" || !!onUploadImage);
-  const latest = useRef({ onChange, onSubmitShortcut, onBlur, isSafeUrl, resolveImageSrc, onUploadImage, placeholder, imagesOn: false, imagesOffText: "" });
+  const latest = useRef({ onChange, onSubmitShortcut, onBlur, isSafeUrl, resolveImageSrc, onUploadImage, onMentionSearch, placeholder, imagesOn: false, imagesOffText: "" });
   latest.current = {
     onChange,
     onSubmitShortcut,
@@ -210,6 +220,7 @@ function RichTextEditor(props) {
     isSafeUrl,
     resolveImageSrc,
     onUploadImage,
+    onMentionSearch,
     placeholder,
     imagesOn: controls.has("image") && !!onUploadImage,
     imagesOffText: imagesUnavailableReason?.trim() || labels.imagesUnsupported
@@ -264,6 +275,59 @@ function RichTextEditor(props) {
       return false;
     }
   };
+  const [mention, setMention] = useState(null);
+  const [mentionIndex, setMentionIndex] = useState(0);
+  const mentionState = useRef({ mention, mentionIndex });
+  mentionState.current = { mention, mentionIndex };
+  const mentionSeq = useRef(0);
+  const mentionBridge = useRef({ update: () => {
+  }, keyDown: () => false });
+  mentionBridge.current = {
+    update: (p) => {
+      const seq = ++mentionSeq.current;
+      const search = latest.current.onMentionSearch;
+      if (!p || !search) {
+        setMention(null);
+        return;
+      }
+      const rect = p.clientRect?.() ?? null;
+      const base = { query: p.query, command: p.command, rect };
+      setMention((prev) => ({ ...base, status: "loading", items: prev?.query && p.query.startsWith(prev.query) ? prev.items : [] }));
+      setMentionIndex(0);
+      Promise.resolve().then(() => search(p.query)).then(
+        (found) => {
+          if (seq !== mentionSeq.current) return;
+          setMention({ ...base, status: "ready", items: usableCandidates(found ?? []) });
+        },
+        () => {
+          if (seq !== mentionSeq.current) return;
+          setMention({ ...base, status: "error", items: [] });
+        }
+      );
+    },
+    keyDown: ({ event }) => {
+      const { mention: open, mentionIndex: index } = mentionState.current;
+      if (!open) return false;
+      if (event.key === "Escape") {
+        mentionSeq.current += 1;
+        setMention(null);
+        return true;
+      }
+      const picks = open.status === "ready" ? open.items : [];
+      if (picks.length === 0) return false;
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        const delta = event.key === "ArrowDown" ? 1 : -1;
+        setMentionIndex((index + delta + picks.length) % picks.length);
+        return true;
+      }
+      if (event.key === "Enter" || event.key === "Tab") {
+        const item = picks[Math.min(index, picks.length - 1)];
+        if (item) open.command(item);
+        return true;
+      }
+      return false;
+    }
+  };
   const headingKey = [...headingLevels].sort().join(",");
   const extensions = useMemo(() => {
     const image = Image.extend({
@@ -386,6 +450,30 @@ function RichTextEditor(props) {
         })];
       }
     });
+    const mentionSuggest = Extension.create({
+      name: "uixMentionSuggestion",
+      addProseMirrorPlugins() {
+        return [Suggestion({
+          editor: this.editor,
+          char: "@",
+          pluginKey: mentionSuggestionKey,
+          items: () => [],
+          command: ({ editor: ed, range, props: item }) => {
+            ed.chain().focus().insertContentAt(range, [
+              { type: "mention", attrs: { id: item.id, label: item.label.replace(/\s+/gu, " ").trim() } },
+              { type: "text", text: " " }
+            ]).run();
+          },
+          allow: ({ state: state2, range }) => !state2.doc.resolve(range.from).parent.type.spec.code,
+          render: () => ({
+            onStart: (p) => mentionBridge.current.update(p),
+            onUpdate: (p) => mentionBridge.current.update(p),
+            onExit: () => mentionBridge.current.update(null),
+            onKeyDown: (p) => mentionBridge.current.keyDown(p)
+          })
+        })];
+      }
+    });
     return [
       ...createSchemaExtensions({
         headingLevels: headingKey.split(",").map(Number),
@@ -396,9 +484,10 @@ function RichTextEditor(props) {
       Placeholder.configure({ placeholder: () => latest.current.placeholder ?? "" }),
       shortcuts,
       ...emoji ? [unicodeEmoji] : [],
-      ...emojiBase ? [emojiImages] : []
+      ...emojiBase ? [emojiImages] : [],
+      ...mentionsOn ? [mentionSuggest] : []
     ];
-  }, [headingKey, emoji, emojiBase]);
+  }, [headingKey, emoji, emojiBase, mentionsOn]);
   const managerOf = (ed) => {
     const manager = ed.markdown ?? ed.storage.markdown.manager;
     return patchManager(manager);
@@ -480,6 +569,8 @@ function RichTextEditor(props) {
   const invalid = props["aria-invalid"] || over;
   const describedBy = [props["aria-describedby"], maxLength !== void 0 ? counterId : void 0, status ? statusId : void 0].filter(Boolean).join(" ") || void 0;
   const suggestOpen = !!suggest && mode === "rich";
+  const mentionOpen = !suggestOpen && !!mention && mode === "rich";
+  const mentionActive = mentionOpen && mention?.status === "ready" && mention.items.length > 0 ? `${mentionId}-${Math.min(mentionIndex, mention.items.length - 1)}` : void 0;
   const rows = minRows ?? (variant === "composer" ? 3 : 4);
   useEffect(() => {
     if (!editor || editor.isDestroyed) return;
@@ -497,9 +588,9 @@ function RichTextEditor(props) {
           "aria-required": htmlAttr(props["aria-required"]),
           "aria-disabled": htmlAttr(disabled),
           "aria-readonly": htmlAttr(readOnly),
-          "aria-autocomplete": emoji ? "list" : void 0,
-          "aria-controls": suggestOpen ? suggestId : void 0,
-          "aria-activedescendant": suggestOpen ? `${suggestId}-${suggestIndex}` : void 0,
+          "aria-autocomplete": emoji || mentionsOn ? "list" : void 0,
+          "aria-controls": suggestOpen ? suggestId : mentionOpen ? mentionId : void 0,
+          "aria-activedescendant": suggestOpen ? `${suggestId}-${suggestIndex}` : mentionActive,
           class: "uix-rich-text__content uix-prose",
           style: `min-height: calc(${rows} * 1lh + 2 * var(--uix-space-3))`
         }).filter(([, v]) => v !== void 0))
@@ -520,7 +611,11 @@ function RichTextEditor(props) {
     suggestOpen,
     suggestId,
     suggestIndex,
-    rows
+    rows,
+    mentionsOn,
+    mentionOpen,
+    mentionId,
+    mentionActive
   ]);
   const state = useEditorState({
     editor,
@@ -874,6 +969,16 @@ function RichTextEditor(props) {
         onPick: (item) => suggest.command(item),
         renderEmoji
       }
+    ) : null,
+    mentionOpen && mention ? /* @__PURE__ */ jsx(
+      MentionSuggestions,
+      {
+        id: mentionId,
+        labels,
+        state: mention,
+        active: Math.min(mentionIndex, Math.max(mention.items.length - 1, 0)),
+        onPick: (item) => mention.command(item)
+      }
     ) : null
   ] });
   const counter = maxLength !== void 0 ? /* @__PURE__ */ jsx("span", { id: counterId, className: "uix-rich-text__counter", "data-over": over || void 0, children: formatLabel(labels.characterCount, { count: markdown.length, max: maxLength }) }) : null;
@@ -908,8 +1013,7 @@ function RichTextEditor(props) {
     hidden
   ] });
 }
-function EmojiSuggestions({ id, label, items, query, active, rect, onPick, renderEmoji }) {
-  const listRef = useRef(null);
+function useCaretPosition(listRef, rect, size) {
   const [pos, setPos] = useState(null);
   useEffect(() => {
     const el = listRef.current;
@@ -922,7 +1026,71 @@ function EmojiSuggestions({ id, label, items, query, active, rect, onPick, rende
       { placement: "bottom-start", offset: 4, padding: 8 }
     );
     setPos({ x: result.x, y: result.y });
-  }, [rect, items.length]);
+  }, [listRef, rect, size]);
+  return pos;
+}
+function MentionSuggestions({ id, labels, state, active, onPick }) {
+  const listRef = useRef(null);
+  const items = state.status === "ready" ? state.items : [];
+  const pos = useCaretPosition(listRef, state.rect, `${state.status}:${items.length}`);
+  useEffect(() => {
+    document.getElementById(`${id}-${active}`)?.scrollIntoView?.({ block: "nearest" });
+  }, [active, id]);
+  const style = { left: pos?.x ?? -9999, top: pos?.y ?? -9999 };
+  if (items.length === 0) {
+    const note = state.status === "loading" ? labels.mentionSearching : state.status === "error" ? labels.mentionFailed : labels.mentionEmpty;
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref: listRef,
+        id,
+        role: "status",
+        "aria-label": labels.mentionSuggestions,
+        className: "uix-rich-text__suggest",
+        "data-mention-list": "",
+        "data-state": state.status === "ready" ? "empty" : state.status,
+        style,
+        children: /* @__PURE__ */ jsx("div", { className: "uix-rich-text__suggest-note", children: note })
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: listRef,
+      id,
+      role: "listbox",
+      "aria-label": labels.mentionSuggestions,
+      "aria-busy": state.status === "loading" || void 0,
+      className: "uix-rich-text__suggest",
+      "data-mention-list": "",
+      "data-state": "ready",
+      style,
+      children: items.map((item, i) => /* @__PURE__ */ jsxs(
+        "div",
+        {
+          id: `${id}-${i}`,
+          role: "option",
+          "aria-selected": i === active,
+          className: "uix-rich-text__suggest-item uix-rich-text__suggest-item--person",
+          "data-mention-id": item.id,
+          onMouseDown: (event) => {
+            event.preventDefault();
+            onPick(item);
+          },
+          children: [
+            /* @__PURE__ */ jsx("span", { className: "uix-rich-text__suggest-label", children: item.label }),
+            item.description ? /* @__PURE__ */ jsx("span", { className: "uix-rich-text__suggest-detail", children: item.description }) : null
+          ]
+        },
+        item.id
+      ))
+    }
+  );
+}
+function EmojiSuggestions({ id, label, items, query, active, rect, onPick, renderEmoji }) {
+  const listRef = useRef(null);
+  const pos = useCaretPosition(listRef, rect, items.length);
   useEffect(() => {
     document.getElementById(`${id}-${active}`)?.scrollIntoView?.({ block: "nearest" });
   }, [active, id]);

package/dist/components/ToggleRow.d.ts

@@ -2,12 +2,19 @@ import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
 
 interface ToggleRowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    /** The row's visible label. It is the switch's `<label>`: clicking it flips the switch, and it names the switch. */
     label: ReactNode;
+    /** Shown under the label and announced as the switch's description (`aria-describedby`). */
     description?: ReactNode;
     checked: boolean;
     onCheckedChange: (checked: boolean) => void;
     disabled?: boolean;
-    accessibleLabel: string;
+    /**
+     * The switch's name when the visible label is not text (an icon, an image).
+     * Leave it out for a text label: the label already names the switch, and a
+     * repeated `aria-label` would replace it.
+     */
+    accessibleLabel?: string;
 }
 declare function ToggleRow({ label, description, checked, onCheckedChange, disabled, accessibleLabel, className, ...props }: ToggleRowProps): react.JSX.Element;
 

package/dist/components/ToggleRow.js

@@ -1,14 +1,28 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { cx } from "../cx.js";
 import { Switch } from "./Switch.js";
 function ToggleRow({ label, description, checked, onCheckedChange, disabled, accessibleLabel, className, ...props }) {
+  const id = useId();
+  const switchId = `${id}-switch`;
+  const descriptionId = `${id}-description`;
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-toggle-row", className), ...props, children: [
     /* @__PURE__ */ jsxs("div", { className: "uix-toggle-row__copy", children: [
-      /* @__PURE__ */ jsx("div", { className: "uix-toggle-row__label", children: label }),
-      description != null && /* @__PURE__ */ jsx("div", { className: "uix-toggle-row__description", children: description })
+      /* @__PURE__ */ jsx("div", { className: "uix-toggle-row__label", children: /* @__PURE__ */ jsx("label", { htmlFor: switchId, children: label }) }),
+      description != null && /* @__PURE__ */ jsx("div", { className: "uix-toggle-row__description", id: descriptionId, children: description })
     ] }),
-    /* @__PURE__ */ jsx(Switch, { checked, disabled, "aria-label": accessibleLabel, onChange: (event) => onCheckedChange(event.currentTarget.checked) })
+    /* @__PURE__ */ jsx(
+      Switch,
+      {
+        id: switchId,
+        checked,
+        disabled,
+        ...accessibleLabel ? { "aria-label": accessibleLabel } : {},
+        ...description != null ? { "aria-describedby": descriptionId } : {},
+        onChange: (event) => onCheckedChange(event.currentTarget.checked)
+      }
+    )
   ] });
 }
 export {

package/dist/correlation-scatter-model.d.ts

@@ -0,0 +1,68 @@
+import { EChartsOption } from 'echarts';
+import { UixChartTokens } from './chart-theme.js';
+import { LinearFit } from './chart-stats.js';
+import { ChartThreshold } from './chart-analytic-model.js';
+
+interface CorrelationPoint {
+    x: number;
+    y: number;
+    label: string;
+    href?: string;
+    /** A point that matters (a breach): a status hue AND a distinct shape, never colour alone. */
+    emphasis?: 'danger' | 'warning';
+}
+interface CorrelationScatterLabels {
+    /** The stats caption. `r` is null when it is undefined (y constant). */
+    stats: (stats: {
+        r: number | null;
+        n: number;
+    }) => string;
+    notEnough: (n: number, min: number) => string;
+    percentile: (p: number) => string;
+    trend: string;
+    /** Header of the label column in the data table. */
+    point: string;
+    formatX: (x: number) => string;
+    formatY: (y: number) => string;
+}
+/** r to two decimals, truncated toward zero so an imperfect fit never reads "r = 1.00". */
+declare function formatCorrelation(r: number): string;
+declare const DEFAULT_CORRELATION_SCATTER_LABELS: CorrelationScatterLabels;
+interface CorrelationScatterSpec {
+    points: CorrelationPoint[];
+    xLabel: string;
+    yLabel: string;
+    trend?: 'linear' | 'none';
+    /** Percentile lines of y, in percent (e.g. [50, 90]). */
+    percentiles?: number[];
+    thresholds?: {
+        x?: ChartThreshold[];
+        y?: ChartThreshold[];
+    };
+    breakpoint?: {
+        x: number;
+        label: string;
+    };
+    /** Below this many points there is no trend and no stats. Default 8. */
+    minPoints?: number;
+}
+interface CorrelationScatterModel {
+    /** False below `minPoints`: render the "not enough data" state instead of a trend. */
+    enough: boolean;
+    n: number;
+    minPoints: number;
+    fit: LinearFit | null;
+    option: EChartsOption;
+    statsText: string;
+    table: {
+        headers: string[];
+        rows: Record<string, string | number>[];
+    };
+    /** Index into `points` for each data item of the hit series. */
+    hitSeriesId: string;
+}
+/** Hit target for every point, in px: above the 24 px accessible minimum (WCAG 2.5.8) with the 2 px gap around it. */
+declare const SCATTER_HIT_SIZE = 26;
+declare function correlationScatterModel(spec: CorrelationScatterSpec, tokens: UixChartTokens, labelOverrides?: Partial<CorrelationScatterLabels>): CorrelationScatterModel;
+
+export { type CorrelationPoint, type CorrelationScatterLabels, type CorrelationScatterModel, type CorrelationScatterSpec, DEFAULT_CORRELATION_SCATTER_LABELS, SCATTER_HIT_SIZE, correlationScatterModel, formatCorrelation };