rift-ds 1.6.0 → 1.7.0

package/components/Composer/Composer.js

@@ -1,11 +1,13 @@
 "use client";
 import { jsxs, jsx, Fragment } from "react/jsx-runtime";
-import React, { useRef, useState, useLayoutEffect, useEffect } from "react";
+import React, { useRef, useState, useId, useLayoutEffect, useEffect } from "react";
 import { AttachmentTile } from "../Attachment/AttachmentTile.js";
 import { formatBytes } from "../Attachment/fileTypes.js";
 import { CircularButton } from "../CircularButton/CircularButton.js";
+import { MentionText, MentionMenu } from "../Mention/Mention.js";
 import "../../fonts/material-symbols.css";
 import "./Composer.css";
+import { getMentionQuery, filterMentionItems, mentionOptionId, mentionListboxId, insertMention } from "../Mention/mentions.js";
 const defaultFileAnnouncement = ({
   type,
   names
@@ -15,6 +17,11 @@ const defaultFileAnnouncement = ({
   if (type === "removed") return `Removed ${list}`;
   return `Could not attach ${list}`;
 };
+const defaultMentionAnnouncement = (count) => count === 1 ? "1 suggestion" : `${count} suggestions`;
+const replaceRange = (node, text, start, end) => {
+  node.setRangeText(text, start, end, "end");
+  node.dispatchEvent(new Event("input", { bubbles: true }));
+};
 const dragCarriesFiles = (event) => Array.from(event.dataTransfer?.types ?? []).includes("Files");
 const Composer = React.forwardRef(
   ({
@@ -43,6 +50,10 @@ const Composer = React.forwardRef(
     filesLabel = "Attachments",
     formatFileAnnouncement = defaultFileAnnouncement,
     attachments,
+    mentions,
+    onMentionSelect,
+    mentionPlacement = "top",
+    formatMentionAnnouncement = defaultMentionAnnouncement,
     actions,
     trailingActions,
     sendLabel = "Send message",
@@ -51,6 +62,10 @@ const Composer = React.forwardRef(
     onChange,
     onKeyDown,
     onPaste,
+    onSelect,
+    onFocus,
+    onBlur,
+    onScroll,
     ...rest
   }, ref) => {
     const baseClass = "ds-composer";
@@ -71,6 +86,27 @@ const Composer = React.forwardRef(
     const [dragging, setDragging] = useState(false);
     const dragDepth = useRef(0);
     const [announcement, setAnnouncement] = useState("");
+    const mentionSources = mentions ?? [];
+    const mentionsArmed = mentionSources.length > 0;
+    const mentionMenuId = useId();
+    const backdropTextRef = useRef(null);
+    const shellRef = useRef(null);
+    const mentionMenuRef = useRef(null);
+    const [caret, setCaret] = useState(null);
+    const [focused, setFocused] = useState(false);
+    const [activeMention, setActiveMention] = useState(0);
+    const [dismissedAt, setDismissedAt] = useState(null);
+    const pendingCaret = useRef(null);
+    const mentionQuery = mentionsArmed && focused && !disabled && caret !== null ? getMentionQuery(
+      currentValue,
+      caret,
+      mentionSources.map((source) => source.trigger)
+    ) : null;
+    const mentionSource = mentionQuery ? mentionSources.find((source) => source.trigger === mentionQuery.trigger) : void 0;
+    const mentionMatches = mentionQuery && mentionSource ? filterMentionItems(mentionSource.items, mentionQuery.query) : [];
+    const choosable = mentionMatches.filter((item) => !item.disabled);
+    const mentionOpen = mentionQuery !== null && choosable.length > 0 && dismissedAt !== mentionQuery.start;
+    const activeItem = mentionOpen ? choosable[Math.min(activeMention, choosable.length - 1)] : void 0;
     const setTextareaRef = (node) => {
       textareaRef.current = node;
       if (typeof ref === "function") ref(node);
@@ -89,10 +125,59 @@ const Composer = React.forwardRef(
       if (!node || !content) return;
       const observer = new ResizeObserver(() => {
         content.style.setProperty("--ds-composer-text-height", `${node.offsetHeight}px`);
+        content.style.setProperty("--ds-composer-text-width", `${node.clientWidth}px`);
       });
       observer.observe(node);
       return () => observer.disconnect();
     }, []);
+    useLayoutEffect(() => {
+      const node = textareaRef.current;
+      if (!node) return;
+      if (pendingCaret.current !== null) {
+        const next = pendingCaret.current;
+        pendingCaret.current = null;
+        node.setSelectionRange(next, next);
+        setCaret(next);
+      }
+      if (!mentionsArmed) return;
+      contentRef.current?.style.setProperty("--ds-composer-text-width", `${node.clientWidth}px`);
+      if (backdropTextRef.current) {
+        backdropTextRef.current.style.transform = `translateY(${-node.scrollTop}px)`;
+      }
+    }, [currentValue, mentionsArmed]);
+    const mentionStart = mentionOpen && mentionQuery ? mentionQuery.start : null;
+    useLayoutEffect(() => {
+      const menu = mentionMenuRef.current;
+      const shell2 = shellRef.current;
+      const overlay = backdropTextRef.current;
+      if (mentionStart === null || !menu || !shell2 || !overlay) return;
+      const walker = document.createTreeWalker(overlay, NodeFilter.SHOW_TEXT);
+      let remaining = mentionStart;
+      let node = walker.nextNode();
+      while (node && remaining >= (node.textContent ?? "").length) {
+        remaining -= (node.textContent ?? "").length;
+        node = walker.nextNode();
+      }
+      if (!node) return;
+      const range = document.createRange();
+      range.setStart(node, remaining);
+      range.setEnd(node, remaining + 1);
+      const triggerBox = range.getBoundingClientRect();
+      const triggerLeft = triggerBox.left;
+      const shellBox = shell2.getBoundingClientRect();
+      const menuBox = menu.getBoundingClientRect();
+      const firstCell = menu.querySelector('[role="option"] > *');
+      const inset = firstCell ? firstCell.getBoundingClientRect().left - menuBox.left : 0;
+      const room = Math.max(0, shell2.clientWidth - menu.offsetWidth);
+      const left = Math.min(Math.max(0, triggerLeft - shellBox.left - shell2.clientLeft - inset), room);
+      menu.style.left = `${left}px`;
+      const origin = shellBox.top + shell2.clientTop;
+      menu.style.setProperty("--ds-composer-mention-line-top", `${triggerBox.top - origin}px`);
+      menu.style.setProperty(
+        "--ds-composer-mention-line-bottom",
+        `${triggerBox.bottom - origin}px`
+      );
+    }, [mentionStart, currentValue]);
     const previousFiles = useRef(queued);
     const announceRef = useRef(formatFileAnnouncement);
     announceRef.current = formatFileAnnouncement;
@@ -183,13 +268,81 @@ const Composer = React.forwardRef(
       if (streaming || !canSend) return;
       onSubmit?.(currentValue);
     };
+    const readCaret = (node) => node.selectionStart === node.selectionEnd ? node.selectionStart : null;
     const handleChange = (e) => {
       if (!isControlled) setUncontrolledValue(e.target.value);
+      if (mentionsArmed) {
+        setCaret(readCaret(e.target));
+        setActiveMention(0);
+      }
       onChange?.(e);
       onValueChange?.(e.target.value);
     };
+    const handleSelect = (e) => {
+      onSelect?.(e);
+      if (!mentionsArmed) return;
+      const next = readCaret(e.currentTarget);
+      setCaret(next);
+      if (dismissedAt !== null && next !== null) {
+        const query = getMentionQuery(
+          e.currentTarget.value,
+          next,
+          mentionSources.map((source) => source.trigger)
+        );
+        if (query?.start !== dismissedAt) setDismissedAt(null);
+      }
+    };
+    const handleFocus = (e) => {
+      onFocus?.(e);
+      setFocused(true);
+      if (mentionsArmed) setCaret(readCaret(e.currentTarget));
+    };
+    const handleBlur = (e) => {
+      onBlur?.(e);
+      setFocused(false);
+    };
+    const handleScroll = (e) => {
+      onScroll?.(e);
+      if (backdropTextRef.current) {
+        backdropTextRef.current.style.transform = `translateY(${-e.currentTarget.scrollTop}px)`;
+      }
+    };
+    const chooseMention = (item) => {
+      const node = textareaRef.current;
+      if (!node || !mentionQuery) return;
+      const next = insertMention(currentValue, mentionQuery, item);
+      pendingCaret.current = next.caret;
+      const tail = currentValue.length - mentionQuery.end;
+      replaceRange(
+        node,
+        next.value.slice(mentionQuery.start, next.value.length - tail),
+        mentionQuery.start,
+        mentionQuery.end
+      );
+      onMentionSelect?.(item, mentionQuery.trigger);
+    };
     const handleKeyDown = (e) => {
       onKeyDown?.(e);
+      if (mentionOpen && activeItem && mentionQuery && !e.nativeEvent.isComposing) {
+        const at = choosable.indexOf(activeItem);
+        if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+          e.preventDefault();
+          const step = e.key === "ArrowDown" ? 1 : -1;
+          setActiveMention((at + step + choosable.length) % choosable.length);
+          return;
+        }
+        if (e.key === "Enter" && !e.shiftKey || e.key === "Tab") {
+          e.preventDefault();
+          chooseMention(activeItem);
+          return;
+        }
+        if (e.key === "Escape") {
+          e.preventDefault();
+          e.stopPropagation();
+          setDismissedAt(mentionQuery.start);
+          return;
+        }
+      }
       if (e.key === "Enter" && !e.shiftKey) {
         e.preventDefault();
         submit();
@@ -206,6 +359,7 @@ const Composer = React.forwardRef(
       streaming ? `${baseClass}--streaming` : "",
       disabled ? `${baseClass}--disabled` : "",
       dragging ? `${baseClass}--dragging` : "",
+      mentionsArmed ? `${baseClass}--mentions` : "",
       // The above placement moves the text onto the chip's rail; the shell
       // needs to know, since the chip is no longer inside it.
       context && contextPlacement === "above" ? `${baseClass}--context-above` : "",
@@ -227,6 +381,7 @@ const Composer = React.forwardRef(
     const shell = /* @__PURE__ */ jsxs(
       "div",
       {
+        ref: shellRef,
         className: classes,
         style: { "--ds-composer-max-rows": maxRows },
         onClick: handleShellClick,
@@ -253,20 +408,48 @@ const Composer = React.forwardRef(
             }
           ) }, file.id)) }),
           attachments && /* @__PURE__ */ jsx("div", { className: `${baseClass}__attachments`, children: attachments }),
-          /* @__PURE__ */ jsx("div", { className: `${baseClass}__content`, ref: contentRef, children: /* @__PURE__ */ jsx(
-            "textarea",
+          /* @__PURE__ */ jsxs("div", { className: `${baseClass}__content`, ref: contentRef, children: [
+            /* @__PURE__ */ jsx(
+              "textarea",
+              {
+                ...rest,
+                ref: setTextareaRef,
+                className: `${baseClass}__textarea`,
+                rows: 1,
+                value: currentValue,
+                "aria-label": ariaLabel,
+                "aria-autocomplete": mentionsArmed ? "list" : void 0,
+                "aria-controls": mentionOpen ? mentionListboxId(mentionMenuId) : void 0,
+                "aria-activedescendant": activeItem ? mentionOptionId(mentionMenuId, activeItem.id) : void 0,
+                onChange: handleChange,
+                onKeyDown: handleKeyDown,
+                onPaste: handlePaste,
+                onSelect: handleSelect,
+                onFocus: handleFocus,
+                onBlur: handleBlur,
+                onScroll: handleScroll
+              }
+            ),
+            mentionsArmed && /* The words a person sees. The textarea beneath keeps the caret,
+            the selection and every keystroke, with its own text
+            transparent; this copy of the same string is where a mention
+            gets its colour. Decorative: the textarea is the control. */
+            /* @__PURE__ */ jsx("div", { className: `${baseClass}__backdrop`, "aria-hidden": "true", children: /* @__PURE__ */ jsx("div", { className: `${baseClass}__backdrop-text`, ref: backdropTextRef, children: /* @__PURE__ */ jsx(MentionText, { text: currentValue, sources: mentionSources }) }) })
+          ] }),
+          mentionOpen && activeItem && mentionQuery && /* @__PURE__ */ jsx(
+            MentionMenu,
             {
-              ...rest,
-              ref: setTextareaRef,
-              className: `${baseClass}__textarea`,
-              rows: 1,
-              value: currentValue,
-              "aria-label": ariaLabel,
-              onChange: handleChange,
-              onKeyDown: handleKeyDown,
-              onPaste: handlePaste
+              ref: mentionMenuRef,
+              id: mentionMenuId,
+              className: `${baseClass}__mention-menu ${baseClass}__mention-menu--${mentionPlacement}`,
+              items: mentionMatches,
+              activeId: activeItem.id,
+              query: mentionQuery.query,
+              label: mentionSource?.label,
+              onActiveChange: (id) => setActiveMention(Math.max(0, choosable.findIndex((item) => item.id === id))),
+              onSelect: chooseMention
             }
-          ) }),
+          ),
           /* @__PURE__ */ jsxs("div", { className: `${baseClass}__footer`, children: [
             (actions || armed && attachButton) && /* @__PURE__ */ jsxs("div", { className: `${baseClass}__actions`, children: [
               armed && attachButton && /* @__PURE__ */ jsx(
@@ -320,7 +503,9 @@ const Composer = React.forwardRef(
             ),
             /* @__PURE__ */ jsx("div", { className: `${baseClass}__drop-hint`, "aria-hidden": "true", children: dropLabel })
           ] }),
-          (armed || hasFiles) && /* @__PURE__ */ jsx("span", { className: `${baseClass}__sr-only`, role: "status", children: announcement })
+          (armed || hasFiles) && /* @__PURE__ */ jsx("span", { className: `${baseClass}__sr-only`, role: "status", children: announcement }),
+          mentionsArmed && /* The menu opens without moving focus, so its arrival is said here */
+          /* @__PURE__ */ jsx("span", { className: `${baseClass}__sr-only`, role: "status", children: mentionOpen ? formatMentionAnnouncement(choosable.length) : "" })
         ]
       }
     );

package/components/Mention/Mention.css

@@ -0,0 +1,195 @@
+/* ============================================
+   MENTION COMPONENT
+   A reference written into a sentence, and the menu a trigger opens:
+   `@` for entities, `/` for skills.
+   ============================================ */
+
+/* ============================================
+   TAG
+   Composer lays this exact tag over the text of its textarea, so nothing
+   here may move a glyph off its advance: no weight, no spacing, and a
+   chip whose padding is paid back in margin.
+   ============================================ */
+
+.ds-mention {
+  /* How far the chip's fill reaches past the glyphs on each side. Padding
+     out, margin back in: the box grows and the text does not move. */
+  --ds-mention-bleed: var(--padding-050);
+  margin: 0 calc(-1 * var(--ds-mention-bleed));
+  padding: 0 var(--ds-mention-bleed);
+  /* The theme's action colour in its text form, the tone a tertiary button
+     writes its label in. A mention is the one word in a sentence that was
+     chosen from a menu and points at something, so it wears the colour that
+     means "this does something", and it moves with the theme where a fixed
+     hue blended into the themes built near it. Behind it, a wash of the
+     same tone, barely there: enough to give the tag an edge, never enough
+     to read as a chip sitting on the line. The wash carries the tag in a
+     theme whose action colour is a neutral. */
+  background-color: var(
+    --ds-mention-bg,
+    color-mix(in srgb, var(--color-action-primary-text-tertiary) 10%, transparent)
+  );
+  border-radius: var(--radius-100);
+  /* A name that wraps keeps its fill and corners on both lines */
+  box-decoration-break: clone;
+  /* Two parts in five of the body colour are mixed in. A button label is
+     large and bold enough to carry an action colour that sits near the
+     page; a name set in running text is not, and unmixed it fell under
+     3:1 in the themes whose action colour is closest to their surface.
+     At this ratio it clears 4.5:1 on the page in every shipped theme and
+     both modes, and still reads as the action colour. */
+  color: var(
+    --ds-mention-color,
+    color-mix(in srgb, var(--color-action-primary-text-tertiary) 60%, var(--color-text-primary))
+  );
+}
+
+/* The trigger is punctuation; the name is the word */
+.ds-mention__trigger {
+  opacity: 0.64;
+}
+
+/* ============================================
+   MENU
+   The floating-surface recipe the chat set's other menus use.
+   ============================================ */
+
+.ds-mention-menu {
+  box-sizing: border-box;
+  /* Consumer hooks: how wide the menu is, and how many rows show before
+     the list scrolls */
+  width: var(--ds-mention-menu-width, 320px);
+  max-width: 100%;
+  /* Page background, not container: the container fill is semi-transparent
+     in dark mode, and a floating panel must not show text through itself */
+  background-color: var(--color-bg-page-primary);
+  border: var(--border-025) solid var(--color-bg-container-border);
+  border-radius: var(--radius-300);
+  box-shadow: var(--shadow-floating);
+  overflow: hidden;
+  animation: ds-mention-menu-appear var(--motion-duration-fast) var(--motion-ease-entrance);
+}
+
+@keyframes ds-mention-menu-appear {
+  from {
+    opacity: 0;
+  }
+}
+
+.ds-mention-menu__list {
+  /* Anchors each row's offsetTop, which is how the highlighted row is kept
+     in view */
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap-050);
+  padding: var(--padding-100);
+  /* Rows × (one line, its block padding, and the gap under it), plus half a
+     row more, so a longer list is cut mid-row and reads as scrollable */
+  max-height: calc(
+    (var(--ds-mention-menu-max-rows, 8) + 0.5) *
+      (var(--font-paragraph-sm-line-height) + 2 * var(--padding-150) + var(--gap-050)) +
+      var(--padding-100)
+  );
+  overflow-y: auto;
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-bg-container-secondary) transparent;
+}
+
+.ds-mention-menu__list:focus-visible {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: -2px;
+  border-radius: var(--radius-300);
+}
+
+/* ============================================
+   OPTION
+   ============================================ */
+
+.ds-mention-menu__option {
+  display: flex;
+  align-items: center;
+  flex: none;
+  gap: var(--gap-200);
+  padding: var(--padding-150) var(--padding-200);
+  border-radius: var(--radius-200);
+  cursor: pointer;
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  font-weight: var(--font-paragraph-sm-weight);
+  line-height: var(--font-paragraph-sm-line-height);
+  letter-spacing: var(--font-paragraph-sm-letter-spacing);
+  color: var(--color-text-primary);
+}
+
+/* One highlight, shared by the pointer and the arrow keys: the pointer
+   moves it rather than drawing a second one. DropdownMenu's focused wash,
+   a translucent neutral, because it is the only sign of where Enter will
+   land and an opaque surface step can equal the panel's own fill in a
+   theme that flattens the two. */
+.ds-mention-menu__option--active {
+  background-color: var(--color-action-passive-bg-hover);
+}
+
+.ds-mention-menu__option--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.ds-mention-menu__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  /* The row's own line box, so an icon never makes its row taller than a
+     row without one */
+  height: var(--font-paragraph-sm-line-height);
+  color: var(--color-icon-secondary);
+}
+
+.ds-mention-menu__icon .material-symbols-rounded {
+  --icon-size: var(--icon-size-500);
+}
+
+.ds-mention-menu__label {
+  flex: none;
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* While a query narrows the list, the typed part of each name holds full
+   strength and the rest steps back. Colour carries it as well as weight,
+   because a theme may set both paragraph weights the same. */
+.ds-mention-menu--filtered .ds-mention-menu__label {
+  color: var(--color-text-secondary);
+}
+
+.ds-mention-menu__match {
+  font-weight: var(--font-paragraph-sm-emphasis-weight);
+  color: var(--color-text-primary);
+}
+
+.ds-mention-menu__description {
+  flex: 1 1 0;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--color-text-tertiary);
+}
+
+/* ============================================
+   EMPTY
+   ============================================ */
+
+.ds-mention-menu__empty {
+  padding: var(--padding-300) var(--padding-400);
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  font-weight: var(--font-paragraph-sm-weight);
+  line-height: var(--font-paragraph-sm-line-height);
+  letter-spacing: var(--font-paragraph-sm-letter-spacing);
+  color: var(--color-text-tertiary);
+}

package/components/Mention/Mention.d.ts

@@ -0,0 +1,68 @@
+import { default as React } from 'react';
+import { MentionItem, MentionSource } from './mentions';
+export * from './mentions';
+type MentionOwnProps = {
+    /** The character that opened the mention, drawn a step quieter than the name. */
+    trigger?: string;
+    /** Additional CSS classes */
+    className?: string;
+    /** The name: a person, a file, a skill. */
+    children?: React.ReactNode;
+};
+export interface MentionProps extends MentionOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof MentionOwnProps> {
+}
+/**
+ * Mention is a reference written into a sentence: `@` and a name for an
+ * entity, `/` and a name for a skill. It is colour and nothing else, with
+ * no padding, fill or weight of its own, so the same tag reads correctly
+ * inside a message and can be laid exactly over the text of an input while
+ * it is being typed.
+ */
+export declare const Mention: React.ForwardRefExoticComponent<MentionProps & React.RefAttributes<HTMLSpanElement>>;
+type MentionTextOwnProps = {
+    /** The plain text, exactly as it was typed or sent. */
+    text: string;
+    /** The sources whose items count as mentions in this text. */
+    sources: MentionSource[];
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface MentionTextProps extends MentionTextOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof MentionTextOwnProps | 'children'> {
+}
+/**
+ * MentionText draws a plain string with every mention in it as a Mention
+ * tag: the sent half of the pattern, for a message that was typed with
+ * mentions in it. The text is the only record. Nothing else needs storing.
+ */
+export declare const MentionText: React.ForwardRefExoticComponent<MentionTextProps & React.RefAttributes<HTMLSpanElement>>;
+type MentionMenuOwnProps = {
+    /** The items to list, already filtered and ordered. */
+    items: MentionItem[];
+    /** The `id` of the highlighted item: the one Enter would choose. */
+    activeId?: string;
+    /** Fires with an item's `id` when the pointer moves onto it. */
+    onActiveChange?: (id: string) => void;
+    /** Fires with the item a person chose. */
+    onSelect?: (item: MentionItem) => void;
+    /** The text typed so far. The part of each label that matches it is drawn stronger. */
+    query?: string;
+    /** Accessible name for the list. */
+    label?: string;
+    /** Shown in place of the list when `items` is empty. Without it an empty menu renders nothing. */
+    emptyText?: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface MentionMenuProps extends MentionMenuOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof MentionMenuOwnProps | 'children'> {
+}
+/**
+ * MentionMenu is the list a trigger character opens. It never takes focus:
+ * the caret stays in the field the person is typing in, which owns the
+ * arrow keys and points `aria-activedescendant` at the highlighted row
+ * (`mentionOptionId` builds the id). The menu draws the rows, follows the
+ * pointer, and reports a choice.
+ *
+ * Composer wires all of this itself through its `mentions` prop. Reach for
+ * MentionMenu directly to build the pattern on another field.
+ */
+export declare const MentionMenu: React.ForwardRefExoticComponent<MentionMenuProps & React.RefAttributes<HTMLDivElement>>;