@tensor_1/react 2.39.0 → 2.40.0

package/README.md

@@ -103,6 +103,23 @@ hidden input), ARIA props, `variant` (`field` / `composer`, which renders in `Co
 work in every preset; the toolbar is one tab stop with arrow-key navigation and scrolls sideways on narrow screens.
 `RichTextEditorFallback` takes the same props and renders a plain textarea, for loading and error-boundary states.
 
+**Mentions (`onMentionSearch`).** Pass `onMentionSearch(query)` and typing `@` opens a "People" list of the
+candidates it answers (`{ id, label, description? }`, at most 20, ids of letters, digits and `_ . -` only). The
+product owns the query and who may be mentioned; UIx never fetches. Arrow keys move, Enter or Tab picks, Escape closes
+and keeps the typed text; while the answer is pending, empty or failed the list is a status line
+(`mentionSearching`, `mentionEmpty`, `mentionFailed`), never an empty listbox. A pick becomes one token (selected and
+deleted as a unit) drawn with `.uix-mention`, stored as `@[Name](mention:<id>)` with `[`, `]` and `\` in the name
+escaped. The token is part of the schema in every editor, so stored mentions survive load → edit → save byte-exact; it
+is never a link, so `isSafeUrl` neither sees nor drops it. `Markdown` draws the same token and takes
+`resolveMention(id, storedName)` for a current or masked name. `findMentions(markdown)`, `formatMention`,
+`readMention` and `isMentionId` (from `@tensor_1/react/markdown` and `/rich-text`) read and write the form on a
+server; code spans and blocks hold no mentions.
+
+```tsx
+<RichTextEditor value={md} onChange={setMd} onMentionSearch={(q) => api.people.search(q)} labels={{ mentionSuggestions: t('people') }} />
+<Markdown resolveMention={(id, stored) => nameOf(id) ?? stored}>{md}</Markdown>
+```
+
 **No network access.** The editor, picker and reaction bar make no requests. `@tiptap/extension-emoji` is configured
 with a list stripped of its CDN `fallbackImage` URLs and GitHub image emoji (`forceFallbackImages: false`), and the
 emoji dataset is a bundled dynamic-import chunk. A jsdom egress test guards this.
@@ -180,6 +197,7 @@ Radial mode still shortens long labels to fit its ring, but every node carries i
 ### Conversations, save feedback and kept tabs
 
 - **`Comment variant="system"`** marks a product event, such as a status change, apart from people. It has no speech bubble and a `systemLabel` byline (default "System").
+- **`Comment avatar={false}`** drops the avatar column (`.uix-comment--bare`), for a comment on a rail that already marks each row, such as a system event in a timeline.
 - **`Comment replyTo`** quotes the answered message above the body. Its label comes from `replyToLabel` (default "In reply to"). Mentions in a body use the `.uix-mention` class.
 - **`SaveStatus`** shows `idle`, `saving`, `saved` or `failed` for inline edits and autosave. It offers `onRetry` when a save fails, and every string comes from `labels`. The status text sits in a polite live region that stays mounted while idle, so keep one `SaveStatus` mounted and change its `state`. Mounting it only when a save starts means the first announcement is lost.
 - **`TabPanel keepMounted`** keeps an inactive panel in the DOM, `hidden` and out of the tab order, so switching back keeps its state and data. It is off by default.

package/dist/chart-analytic-model.d.ts

@@ -131,7 +131,11 @@ declare function partialPeriod(lastX: ChartX, options: {
  * or at the start of a run of nulls). `badSide` defaults to `above` (`floor` thresholds: `below`).
  */
 declare function findCrossings(values: readonly (number | null)[], threshold: Pick<ChartThreshold, 'value' | 'badSide' | 'kind'>): number[];
-/** A ringed point at each first crossing, labelled "Crossed <x>" above it. */
+/**
+ * A ringed point at each first crossing. Only the latest carries a visible "Crossed <x>" label (it is
+ * the one a headline's "since" names); earlier crossings show theirs on hover, so a series that
+ * crosses repeatedly never stacks colliding labels along the line.
+ */
 declare function crossingPoints(values: readonly (number | null)[], threshold: ChartThreshold, options: {
     x: readonly ChartX[];
     tokens: UixChartTokens;

package/dist/chart-analytic-model.js

@@ -221,22 +221,29 @@ function findCrossings(values, threshold) {
 }
 function crossingPoints(values, threshold, options) {
   const labels = { ...DEFAULT_ANALYTIC_LABELS, ...options.labels };
-  const data = findCrossings(values, threshold).map((index) => ({
-    name: labels.crossed(labels.formatX(options.x[index])),
-    coord: [options.x[index], values[index]],
-    symbol: "circle",
-    symbolSize: 10,
-    itemStyle: { color: options.tokens.surface, borderColor: options.tokens.text, borderWidth: 2 },
-    label: {
-      show: true,
-      position: "top",
-      distance: 8,
-      formatter: labels.crossed(labels.formatX(options.x[index])),
-      color: options.tokens.text,
-      fontFamily: options.tokens.fontSans,
-      fontSize: 11
-    }
-  }));
+  const crossings = findCrossings(values, threshold);
+  const label = (text, show) => ({
+    show,
+    position: "top",
+    distance: 8,
+    formatter: text,
+    color: options.tokens.text,
+    fontFamily: options.tokens.fontSans,
+    fontSize: 11
+  });
+  const data = crossings.map((index, i) => {
+    const text = labels.crossed(labels.formatX(options.x[index]));
+    const latest = i === crossings.length - 1;
+    return {
+      name: text,
+      coord: [options.x[index], values[index]],
+      symbol: "circle",
+      symbolSize: 10,
+      itemStyle: { color: options.tokens.surface, borderColor: options.tokens.text, borderWidth: 2 },
+      label: label(text, latest),
+      ...latest ? {} : { emphasis: { label: label(text, true) } }
+    };
+  });
   return data.length ? { markPoint: { animation: false, data } } : {};
 }
 export {

package/dist/chart-analytic.cjs

@@ -599,22 +599,29 @@ function findCrossings(values, threshold) {
 }
 function crossingPoints(values, threshold, options) {
   const labels = { ...DEFAULT_ANALYTIC_LABELS, ...options.labels };
-  const data = findCrossings(values, threshold).map((index) => ({
-    name: labels.crossed(labels.formatX(options.x[index])),
-    coord: [options.x[index], values[index]],
-    symbol: "circle",
-    symbolSize: 10,
-    itemStyle: { color: options.tokens.surface, borderColor: options.tokens.text, borderWidth: 2 },
-    label: {
-      show: true,
-      position: "top",
-      distance: 8,
-      formatter: labels.crossed(labels.formatX(options.x[index])),
-      color: options.tokens.text,
-      fontFamily: options.tokens.fontSans,
-      fontSize: 11
-    }
-  }));
+  const crossings = findCrossings(values, threshold);
+  const label = (text, show) => ({
+    show,
+    position: "top",
+    distance: 8,
+    formatter: text,
+    color: options.tokens.text,
+    fontFamily: options.tokens.fontSans,
+    fontSize: 11
+  });
+  const data = crossings.map((index, i) => {
+    const text = labels.crossed(labels.formatX(options.x[index]));
+    const latest = i === crossings.length - 1;
+    return {
+      name: text,
+      coord: [options.x[index], values[index]],
+      symbol: "circle",
+      symbolSize: 10,
+      itemStyle: { color: options.tokens.surface, borderColor: options.tokens.text, borderWidth: 2 },
+      label: label(text, latest),
+      ...latest ? {} : { emphasis: { label: label(text, true) } }
+    };
+  });
   return data.length ? { markPoint: { animation: false, data } } : {};
 }
 

package/dist/chart-analytic.d.cts

@@ -136,7 +136,11 @@ declare function partialPeriod(lastX: ChartX, options: {
  * or at the start of a run of nulls). `badSide` defaults to `above` (`floor` thresholds: `below`).
  */
 declare function findCrossings(values: readonly (number | null)[], threshold: Pick<ChartThreshold, 'value' | 'badSide' | 'kind'>): number[];
-/** A ringed point at each first crossing, labelled "Crossed <x>" above it. */
+/**
+ * A ringed point at each first crossing. Only the latest carries a visible "Crossed <x>" label (it is
+ * the one a headline's "since" names); earlier crossings show theirs on hover, so a series that
+ * crosses repeatedly never stacks colliding labels along the line.
+ */
 declare function crossingPoints(values: readonly (number | null)[], threshold: ChartThreshold, options: {
     x: readonly ChartX[];
     tokens: UixChartTokens;

package/dist/components/Comments.d.ts

@@ -11,7 +11,10 @@ interface CommentsProps extends HTMLAttributes<HTMLDivElement> {
  */
 declare function Comments({ children, className, ...props }: CommentsProps): react.JSX.Element;
 interface CommentProps extends HTMLAttributes<HTMLDivElement> {
-    /** Usually an `<Avatar />` (the grid reserves the leading column). */
+    /**
+     * Usually an `<Avatar />` (the grid reserves the leading column). `false` drops the
+     * column, for a comment that sits on a rail which already marks each row (a timeline).
+     */
     avatar?: ReactNode;
     author?: ReactNode;
     meta?: ReactNode;

package/dist/components/Comments.js

@@ -17,14 +17,15 @@ function Comment({
 }) {
   const system = variant === "system";
   const byline = author ?? (system ? systemLabel : void 0);
+  const bare = avatar === false;
   return /* @__PURE__ */ jsxs(
     "div",
     {
-      className: cx("uix-comment", system && "uix-comment--system", className),
+      className: cx("uix-comment", system && "uix-comment--system", bare && "uix-comment--bare", className),
       "data-variant": system ? "system" : void 0,
       ...props,
       children: [
-        avatar ?? /* @__PURE__ */ jsx("span", { "aria-hidden": "true" }),
+        bare ? null : avatar ?? /* @__PURE__ */ jsx("span", { "aria-hidden": "true" }),
         /* @__PURE__ */ jsxs("div", { className: "uix-comment__body", children: [
           (byline != null || meta != null) && /* @__PURE__ */ jsxs("div", { className: "uix-comment__meta", children: [
             byline != null && /* @__PURE__ */ jsx("span", { className: "uix-comment__author", children: byline }),

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 {