rift-ds 1.6.0 → 1.7.0

package/README.md

@@ -13,13 +13,11 @@ An open source React design system built for AI products and coding agents: comp
 
 ## Why Rift DS
 
-- **One package, zero dependencies.** React is the only required peer dependency; recharts is optional and only for the charts entry. No configuration API, no providers, no build-tool integration: theming is plain CSS custom properties, so it works in any bundler, in any stack, beside anything you already use.
-- **Free, open source, consumed your way.** MIT end to end, no pro tier, no paywalled components. Install the npm package, pull single components as source through the shadcn CLI, or clone the repo and own every line; all three are first-class paths.
-- **A few primitives re-theme everything.** Every semantic token chains to a primitive, so a handful of overrides cascade through every component, the charts, and the ambient background, in both colour modes. Your brand is a short CSS block, not a fork.
-- **The shipped themes prove it.** Each one is the same system under different primitives, saved as a complete look: colour modes, a type pairing with self-hosted fonts, type weight and tracking, icon weight, radius, density, motion, elevation, the chart palette. Setting `data-brand` on the root element applies all of it with zero runtime JavaScript, the build holds every theme's action colours to WCAG AA in both modes, and the playground builds yours the same way.
-- **The AI product set is in the box.** Composer, streaming chat thread, tool calls, reasoning, thread panel and tabs: the components an assistant UI needs, the same set this repo's own site chat is built from.
-- **Legible to coding agents.** One command installs the agent skill and prints the MCP connect line, and the MCP tools and per-component markdown are generated from the same JSDoc that builds the shipped `.d.ts`: an agent reads the exact contract npm ships, no key, no account.
-- **Docs that cannot lie.** Every count, list, and prop table is generated from source registries and build-validated; CI fails on drift, and every component story ships through an accessibility audit. What the docs say is what ships.
+- **<!-- component-count -->150<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. React is the only required peer dependency.
+- **AI patterns and templates, ready to use.** Composer, streaming chat thread, tool calls, reasoning and thread panel are in the box, and the docs site has complete template screens built from them.
+- **Fully themeable.** The shipped themes are complete looks to start from, each in light and dark. One `data-brand` attribute applies a theme, and a few CSS overrides make your own.
+- **Ready for coding agents.** One command installs the agent skills, and a public MCP endpoint serves every component's props, so your agent builds with the library as it actually is. No key, no account.
+- **Free, consumed your way.** MIT, with no pro tier. Install the npm package, pull single components as source through the shadcn CLI, or clone the repo.
 
 ## Documentation
 
@@ -42,7 +40,7 @@ React 19+ is a peer dependency. The package is ESM-only and resolved via `export
 
 ## Set up your agent
 
-One command teaches a coding agent the system: it installs the generated agent skill into your project and prints the MCP connect line.
+One command teaches a coding agent the system: it installs the generated agent skills into your project and prints the MCP connect line.
 
 ```bash
 npx rift-ds init
@@ -73,13 +71,13 @@ import 'rift-ds/tokens/presets/presets.css';
 
 ## Components
 
-<!-- component-count -->149<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->150<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>

package/bin/rift-ds.mjs

@@ -2,18 +2,28 @@
 /**
  * The package's one command: `npx rift-ds init`.
  *
- * Fetches the generated agent skill (SKILL.md + references/components.md)
- * from the live site into the project's .claude/skills/ folder, then prints
- * the MCP connect line. The files are fetched rather than bundled because
- * they regenerate with every site deploy, while the package moves only on a
- * release — a bundled copy would always be the staler one. Re-running the
- * command overwrites the pair; that is the refresh story.
+ * Fetches the generated agent skills from the live site into the
+ * project's .claude/skills/ folder, one folder per skill, then prints the
+ * MCP connect line. Which skills exist and which files each holds comes
+ * from the site's /skill/manifest.json, never from a list in this file:
+ * the skills regenerate with every site deploy while the package moves
+ * only on a release, so a bundled list (or a bundled copy of the files)
+ * would always be the staler one, and a skill added to the site reaches
+ * this command with no new version of the package. Re-running overwrites
+ * what is there; that is the refresh story.
+ *
+ * The manifest is data from the network that decides where this command
+ * writes, so every name and path in it is checked before anything touches
+ * the disk: a skill name is one kebab-case folder, a file is a plain
+ * relative path, and nothing may climb out of the target folder.
  *
  * Zero dependencies by design: global fetch plus node:fs, so npx never
  * installs anything beyond the package itself. SITE_ORIGIN, SKILL_NAME
  * and MCP_SERVER_NAME are stamped by build-package.mjs from
  * scripts/brand.mjs (the one home for brand facts); running this file
  * straight from source fails fast rather than guessing a domain.
+ * SKILL_NAME is the library skill, kept only for --out without --skill,
+ * which has always meant that one.
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -21,46 +31,100 @@ import { dirname, join, resolve } from 'node:path';
 const SITE_ORIGIN = 'https://rift-ds.com';
 const SKILL_NAME = 'rift-design-system';
 const MCP_SERVER_NAME = 'rift-ds';
-const SKILL_FILES = ['SKILL.md', 'references/components.md'];
-const DEFAULT_OUT = join('.claude', 'skills', SKILL_NAME);
+const MANIFEST_URL = `${SITE_ORIGIN}/skill/manifest.json`;
+const DEFAULT_DIR = join('.claude', 'skills');
 
-const USAGE = `Usage: npx rift-ds init [--out <dir>]
+const USAGE = `Usage: npx rift-ds init [--skill <name>] [--dir <dir>]
 
-Fetches the agent skill for this package from ${SITE_ORIGIN} into
-${DEFAULT_OUT}/ so a skill-capable coding agent carries the
-library's install, theming and catalogue rules into every session.
-Re-run any time to refresh; the files regenerate with every site deploy.
+Fetches the agent skills for this package from ${SITE_ORIGIN} into
+${DEFAULT_DIR}/, one folder per skill, so a skill-capable coding agent
+carries the library's install, theming and catalogue rules into every
+session. Re-run any time to refresh; the files regenerate with every
+site deploy.
 
 Options:
-  --out <dir>   Write the skill somewhere else (default: ${DEFAULT_OUT})
-  --help        Show this message`;
+  --skill <name>  Install one skill instead of all of them
+  --dir <dir>     Folder that receives one folder per skill (default: ${DEFAULT_DIR})
+  --out <dir>     Deprecated: write one skill's files straight into <dir>
+                  (${SKILL_NAME} unless --skill names another). Use --dir.
+  --help          Show this message
+
+The list of skills is at ${MANIFEST_URL}`;
 
 function fail(message) {
   console.error(`✗ ${message}`);
   process.exit(1);
 }
 
-async function init(outDir) {
+async function get(url) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    fail(`could not reach ${url} (${error?.message ?? error}). Check your network and retry.`);
+  }
+  if (!response.ok) {
+    fail(`${url} answered ${response.status}. The site may be mid-deploy; retry in a minute.`);
+  }
+  return response.text();
+}
+
+/** The manifest's skills, with every name and path checked before use. */
+async function readManifest() {
+  let manifest;
+  try {
+    manifest = JSON.parse(await get(MANIFEST_URL));
+  } catch {
+    fail(`${MANIFEST_URL} is not valid JSON. The site may be mid-deploy; retry in a minute.`);
+  }
+  const skills = manifest?.skills;
+  if (!Array.isArray(skills) || skills.length === 0) {
+    fail(`${MANIFEST_URL} lists no skills. Update the package (npm install rift-ds@latest) and retry.`);
+  }
+  const segment = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+  for (const skill of skills) {
+    const filesOk =
+      Array.isArray(skill?.files) &&
+      skill.files.length > 0 &&
+      skill.files.every(
+        (file) => typeof file === 'string' && file.split('/').every((part) => segment.test(part))
+      );
+    if (typeof skill?.name !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(skill.name) || !filesOk) {
+      fail(`${MANIFEST_URL} holds an entry this command will not write to disk. Nothing was installed.`);
+    }
+  }
+  return skills;
+}
+
+async function init({ only, dir, out }) {
   if (SITE_ORIGIN.startsWith('__')) {
     fail('this copy was not built: run the published bin (npx rift-ds init).');
   }
-  for (const file of SKILL_FILES) {
-    const url = `${SITE_ORIGIN}/skill/${SKILL_NAME}/${file}`;
-    let response;
-    try {
-      response = await fetch(url);
-    } catch (error) {
-      fail(`could not reach ${url} (${error?.message ?? error}). Check your network and retry.`);
-    }
-    if (!response.ok) {
-      fail(`${url} answered ${response.status}. The site may be mid-deploy; retry in a minute.`);
+  const skills = await readManifest();
+  const wanted = only ?? (out ? SKILL_NAME : null);
+  const selected = wanted ? skills.filter((skill) => skill.name === wanted) : skills;
+  if (selected.length === 0) {
+    fail(`no skill named "${wanted}". Available: ${skills.map((skill) => skill.name).join(', ')}.`);
+  }
+  for (const skill of selected) {
+    const target = out ?? join(dir, skill.name);
+    for (const file of skill.files) {
+      const text = await get(`${SITE_ORIGIN}/skill/${skill.name}/${file}`);
+      const path = join(target, ...file.split('/'));
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, text);
+      console.log(`▸ ${path}`);
     }
-    const target = join(outDir, file);
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, await response.text());
-    console.log(`▸ ${target}`);
   }
-  console.log(`✓ Agent skill installed. Skill-capable agents load it automatically.`);
+  const names = selected.map((skill) => skill.name).join(', ');
+  console.log(
+    selected.length === 1
+      ? `✓ Agent skill installed: ${names}. Skill-capable agents load it automatically.`
+      : `✓ ${selected.length} agent skills installed: ${names}. Skill-capable agents load them automatically.`
+  );
+  if (out) {
+    console.log(`\n--out is deprecated. Use --dir to choose the folder that holds the skill folders.`);
+  }
   console.log(`\nFor on-demand lookups too, connect the MCP endpoint:`);
   console.log(`  claude mcp add --transport http ${MCP_SERVER_NAME} ${SITE_ORIGIN}/api/mcp`);
 }
@@ -73,10 +137,20 @@ if (args.includes('--help') || args.includes('-h') || args.length === 0) {
 if (args[0] !== 'init') {
   fail(`unknown command "${args[0]}"\n\n${USAGE}`);
 }
-const outFlag = args.indexOf('--out');
-let outDir = DEFAULT_OUT;
-if (outFlag !== -1) {
-  if (!args[outFlag + 1]) fail('--out needs a directory');
-  outDir = resolve(args[outFlag + 1]);
+/** The value after a flag, or undefined when the flag is absent. */
+function option(flag, what) {
+  const at = args.indexOf(flag);
+  if (at === -1) return undefined;
+  const value = args[at + 1];
+  if (!value || value.startsWith('--')) fail(`${flag} needs ${what}`);
+  return value;
 }
-await init(outDir);
+const only = option('--skill', 'a skill name');
+const dirFlag = option('--dir', 'a directory');
+const outFlag = option('--out', 'a directory');
+if (dirFlag && outFlag) fail('use --dir or --out, not both');
+await init({
+  only,
+  dir: dirFlag ? resolve(dirFlag) : DEFAULT_DIR,
+  out: outFlag ? resolve(outFlag) : undefined,
+});

package/components/AgentRail/AgentRail.css

@@ -189,8 +189,8 @@
   color: var(--color-text-secondary);
 }
 
-/* ThreadPanel's unread dot, restated at the same size: the gap scale,
-   because no icon token is that small. */
+/* StatusDot's `xs` mark restated at the same size: the gap scale, because
+   no icon token is that small. */
 .ds-agent-rail__status-dot {
   width: var(--gap-200);
   height: var(--gap-200);

package/components/Attachment/Attachment.css

@@ -674,6 +674,20 @@ button.ds-attachment-group__single:hover {
   height: auto;
 }
 
+/* With its dimensions known the picture holds its final box from the first
+   frame: its own width, or the width the height cap allows at its ratio,
+   whichever is smaller. The ratio cap sits in the width rather than beside
+   the row's percentage in max-width, because a percentage there drops out
+   of the frame's shrink-to-fit measure and the frame would size to the
+   uncapped width. The height follows from the ratio the width and height
+   attributes carry, so nothing moves when the pixels arrive. */
+.ds-attachment-group__single-image--sized {
+  width: min(
+    var(--ds-attachment-single-width, 100%),
+    calc(var(--ds-attachment-single-max-height, 320px) * var(--ds-attachment-single-ratio, 1))
+  );
+}
+
 .ds-attachment-group__more:focus-visible,
 .ds-attachment-group__less:focus-visible,
 button.ds-attachment-group__single:focus-visible {

package/components/Attachment/AttachmentGroup.d.ts

@@ -1,7 +1,5 @@
 import { default as React } from 'react';
 import { AttachmentItem } from './fileTypes';
-export { revokeAttachmentUrls, useAttachments } from './useAttachments';
-export type { AttachmentRejection, AttachmentRejectionReason, AttachmentUploadContext, UseAttachmentsOptions, UseAttachmentsResult, } from './useAttachments';
 /** Props owned by AttachmentGroup itself — everything else falls through to the root element. */
 type AttachmentGroupOwnProps = {
     /** The files on the message, in order. */
@@ -58,3 +56,5 @@ export interface AttachmentGroupProps extends AttachmentGroupOwnProps, Omit<Reac
  * a record and opens nothing.
  */
 export declare const AttachmentGroup: React.ForwardRefExoticComponent<AttachmentGroupProps & React.RefAttributes<HTMLDivElement>>;
+export { revokeAttachmentUrls, useAttachments } from './useAttachments';
+export type { AttachmentRejection, AttachmentRejectionReason, AttachmentUploadContext, UseAttachmentsOptions, UseAttachmentsResult, } from './useAttachments';

package/components/Attachment/AttachmentGroup.js

@@ -63,14 +63,19 @@ const AttachmentGroup = React.forwardRef(
     let layout;
     if (single) {
       const onClick = clickHandler(single);
+      const sized = Boolean(single.width && single.height);
       const image = /* @__PURE__ */ jsx(
         "img",
         {
-          className: `${baseClass}__single-image`,
+          className: [`${baseClass}__single-image`, sized && `${baseClass}__single-image--sized`].filter(Boolean).join(" "),
           src: single.previewSrc,
           alt: single.previewAlt ?? single.name,
           width: single.width,
-          height: single.height
+          height: single.height,
+          style: sized ? {
+            "--ds-attachment-single-width": `${single.width}px`,
+            "--ds-attachment-single-ratio": single.width / single.height
+          } : void 0
         }
       );
       const badge = /* @__PURE__ */ jsx("span", { className: `${baseClass}__single-mark`, "aria-hidden": "true", children: renderTypeMark(single.name, single.kind, { form: "badge" }) });

package/components/Composer/Composer.css

@@ -41,6 +41,9 @@
   background-color: var(--color-input-bg-primary);
   border: var(--border-025) solid var(--color-input-border-primary);
   border-radius: var(--ds-composer-radius);
+  /* Where the typed text starts and ends. One value, because the mention
+     overlay has to sit on exactly the rail the textarea does. */
+  --ds-composer-text-inset: var(--padding-500);
   box-shadow: var(--shadow-floating);
   transition: border-color var(--motion-duration-fast) var(--motion-ease-standard);
   /* The whole shell is the input affordance — clicking anywhere that is
@@ -304,9 +307,12 @@
   margin-left: calc(-1 * var(--ds-composer-context-icon-bearing, var(--icon-size-500) * 4 / 24));
 }
 
-.ds-composer--context-above .ds-composer__attachments,
-.ds-composer--context-above .ds-composer__content {
-  padding-inline: calc(var(--padding-200) + var(--padding-400));
+.ds-composer--context-above {
+  --ds-composer-text-inset: calc(var(--padding-200) + var(--padding-400));
+}
+
+.ds-composer--context-above .ds-composer__attachments {
+  padding-inline: var(--ds-composer-text-inset);
 }
 
 /* The text owns the truncation: one line, ellipsized only when the note
@@ -439,7 +445,7 @@
   align-items: flex-start;
   box-sizing: border-box;
   width: 100%;
-  padding: var(--padding-400) var(--padding-500) var(--padding-200);
+  padding: var(--padding-400) var(--ds-composer-text-inset) var(--padding-200);
   /* Growing and shrinking is animated, which needs two pixel heights to run
      between — `auto` has nothing to interpolate. So the zone states its own
      height: the measured textarea (published as --ds-composer-text-height on
@@ -507,6 +513,76 @@
   }
 }
 
+/* ============================================
+   MENTIONS — armed by the `mentions` prop
+   A textarea cannot colour part of its own text, so the words are drawn
+   twice: the textarea keeps the caret, the selection and the keystrokes
+   with its text transparent, and an overlay of the same string, in the
+   same type on the same rail, is what a person reads. Only colour differs
+   between the two, so they can never drift apart by a glyph.
+   ============================================ */
+
+.ds-composer--mentions .ds-composer__content {
+  position: relative;
+}
+
+.ds-composer--mentions .ds-composer__textarea {
+  /* Above the overlay: a tag carries a fill, and the caret and the
+     selection highlight must never be painted under it */
+  position: relative;
+  z-index: 1;
+  color: transparent;
+  caret-color: var(--color-input-text-primary);
+}
+
+.ds-composer__backdrop {
+  position: absolute;
+  top: var(--padding-400);
+  left: var(--ds-composer-text-inset);
+  /* The textarea's measured box: its height, and its client width, which
+     is what its text wraps at once a scrollbar takes its share */
+  width: var(
+    --ds-composer-text-width,
+    calc(100% - 2 * var(--ds-composer-text-inset))
+  );
+  height: var(--ds-composer-text-height, var(--font-paragraph-line-height));
+  overflow: hidden;
+  pointer-events: none;
+}
+
+.ds-composer__backdrop-text {
+  font-family: var(--font-paragraph-family);
+  font-size: var(--font-paragraph-size);
+  font-weight: var(--font-paragraph-weight);
+  line-height: var(--font-paragraph-line-height);
+  letter-spacing: var(--font-paragraph-letter-spacing);
+  color: var(--color-input-text-primary);
+  /* A textarea's own wrapping rules */
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}
+
+/* The menu a trigger opens. It grows out of the line the trigger is on:
+   `left` and the two line offsets are set inline from where the trigger
+   character sits, and the menu rests a hair clear of that line, over the
+   text before it (top) or after it (bottom). Until the first measurement
+   the fallbacks seat it against the shell's edge. */
+.ds-composer__mention-menu {
+  position: absolute;
+  left: 0;
+  z-index: 10;
+  /* A list, not a text field */
+  cursor: default;
+}
+
+.ds-composer__mention-menu--top {
+  bottom: calc(100% - var(--ds-composer-mention-line-top, 0px) + var(--gap-100));
+}
+
+.ds-composer__mention-menu--bottom {
+  top: calc(var(--ds-composer-mention-line-bottom, 100%) + var(--gap-100));
+}
+
 /* ============================================
    FOOTER ROW
    ============================================ */
@@ -560,3 +636,11 @@
   cursor: not-allowed;
   color: var(--color-input-text-disabled);
 }
+
+.ds-composer--disabled .ds-composer__backdrop-text {
+  color: var(--color-input-text-disabled);
+}
+
+.ds-composer--disabled.ds-composer--mentions .ds-composer__textarea {
+  color: transparent;
+}

package/components/Composer/Composer.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { AttachmentItem } from '../Attachment/fileTypes';
+import { MentionItem, MentionSource } from '../Mention/Mention';
 /** Props owned by Composer itself — everything else falls through to the <textarea>. */
 type ComposerOwnProps = {
     /** Current value for controlled use. Pair with `onValueChange`. */
@@ -116,6 +117,26 @@ type ComposerOwnProps = {
      * @deprecated Use `files` with `onFilesSelected` and `onFileRemove`, which draw the queue as tiles.
      */
     attachments?: React.ReactNode;
+    /**
+     * What a person can reference while typing, one source per trigger
+     * character: `@` for entities, `/` for skills. Typing a trigger at the
+     * start of a word opens a menu of that source's items, filtered as the
+     * word grows. Arrows move through it, Enter or Tab writes the choice into
+     * the text, Escape closes it. A mention is drawn in the tag colour
+     * wherever its exact name stands in the text; the value stays a plain
+     * string.
+     */
+    mentions?: MentionSource[];
+    /** Fires with the item a person chose from the mention menu, and the trigger that opened it. */
+    onMentionSelect?: (item: MentionItem, trigger: string) => void;
+    /**
+     * Which side of the trigger's line the mention menu opens on: `top` lays
+     * it over the text above, `bottom` over the text below. `top` suits a
+     * composer at the foot of a view.
+     */
+    mentionPlacement?: 'top' | 'bottom';
+    /** Builds the sentence announced to assistive technology when the mention menu opens or its matches change. */
+    formatMentionAnnouncement?: (count: number) => string;
     /** Leading actions on the left of the action bar, after the attach button (a model picker). */
     actions?: React.ReactNode;
     /**