@bysages/react 0.4.4 → 0.6.0

package/dist/generative/index.mjs

@@ -1,4 +1,4 @@
-import { r as iconNode } from "../icon-Cri0-7-x.mjs";
+import { r as iconNode } from "../icon-C9udWCyz.mjs";
 import { Button } from "../components/button/index.mjs";
 import { Alert } from "../components/alert/index.mjs";
 import { Avatar } from "../components/avatar/index.mjs";
@@ -7,12 +7,12 @@ import { Banner } from "../components/banner/index.mjs";
 import { Spinner } from "../components/spinner/index.mjs";
 import { Breadcrumb } from "../components/breadcrumb/index.mjs";
 import { Card } from "../components/card/index.mjs";
-import { t as Input } from "../input-BDpQ0e6G.mjs";
+import { t as Input } from "../input-YRjehBhU.mjs";
 import { Checkbox } from "../components/checkbox/index.mjs";
 import { FloatButton } from "../components/float-button/index.mjs";
 import { Progress } from "../components/progress/index.mjs";
 import { RadioGroup } from "../components/radio-group/index.mjs";
-import { t as Select } from "../select-D_soVdWK.mjs";
+import { t as Select } from "../select-BLFqfeVw.mjs";
 import { Separator } from "../components/separator/index.mjs";
 import { Slider } from "../components/slider/index.mjs";
 import { Stack } from "../components/stack/index.mjs";
@@ -26,7 +26,7 @@ import { z } from "zod";
 import { defineRegistry, useBoundProp } from "@json-render/react";
 import { defineCatalog } from "@json-render/core";
 import { schema } from "@json-render/react/schema";
-//#region \0rolldown/runtime.js
+// \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -37,8 +37,7 @@ var __exportAll = (all, no_symbols) => {
 	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
-//#endregion
-//#region src/generative/faces.generated.ts
+// src/generative/faces.generated.ts
 /** Name the faces a family contributes; the identity keeps inference
 * honest at the call site. */
 function defineFace(faces) {
@@ -351,8 +350,7 @@ const faces$1 = defineFace({
 		description: "A multi-line field for prose-length answers."
 	}
 });
-//#endregion
-//#region src/generative/shared.ts
+// src/generative/shared.ts
 /** Name the entries a family contributes; the identity keeps inference
 * honest at the call site. */
 function defineEntry(entries) {
@@ -373,24 +371,21 @@ function useBound(value, path) {
 function labelled(label, control) {
 	return label ? createElement(Stack, { gap: "xs" }, createElement(Typography.Label, null, label), control) : control;
 }
-//#endregion
-//#region src/components/alert/generative.ts
+// src/components/alert/generative.ts
 var generative_exports$20 = /* @__PURE__ */ __exportAll({ default: () => generative_default$20 });
 /** A bordered notice; status picks the pigment. */
 var generative_default$20 = defineEntry({ Alert: {
 	...faces$1.Alert,
 	component: ({ props }) => createElement(Alert.Root, { status: props.status ?? "ink" }, createElement(Alert.Icon), createElement(Alert.Body, null, createElement(Alert.Title, null, props.title), props.message != null ? createElement(Alert.Description, null, props.message) : null))
 } });
-//#endregion
-//#region src/components/avatar/generative.ts
+// src/components/avatar/generative.ts
 var generative_exports$19 = /* @__PURE__ */ __exportAll({ default: () => generative_default$19 });
 /** A person's seal: image when given, initials as the fallback. */
 var generative_default$19 = defineEntry({ Avatar: {
 	...faces$1.Avatar,
 	component: ({ props }) => createElement(Avatar, { ...props })
 } });
-//#endregion
-//#region src/components/badge/generative.ts
+// src/components/badge/generative.ts
 var generative_exports$18 = /* @__PURE__ */ __exportAll({ default: () => generative_default$18 });
 /** A small status seal beside content; reads at a glance. */
 var generative_default$18 = defineEntry({ Badge: {
@@ -400,8 +395,7 @@ var generative_default$18 = defineEntry({ Badge: {
 		variant: props.variant
 	}, props.text)
 } });
-//#endregion
-//#region src/components/banner/generative.ts
+// src/components/banner/generative.ts
 var generative_exports$17 = /* @__PURE__ */ __exportAll({ default: () => generative_default$17 });
 /** A full-width notice that speaks once across the page. */
 var generative_default$17 = defineEntry({ Banner: {
@@ -411,8 +405,7 @@ var generative_default$17 = defineEntry({ Banner: {
 		dismissible: true
 	})
 } });
-//#endregion
-//#region src/components/breadcrumb/generative.ts
+// src/components/breadcrumb/generative.ts
 var generative_exports$16 = /* @__PURE__ */ __exportAll({ default: () => generative_default$16 });
 /** A trail of waymarks from home to the current page. */
 var generative_default$16 = defineEntry({ Breadcrumb: {
@@ -430,8 +423,7 @@ var generative_default$16 = defineEntry({ Breadcrumb: {
 		return createElement(Breadcrumb, { items });
 	}
 } });
-//#endregion
-//#region src/components/button/generative.ts
+// src/components/button/generative.ts
 var generative_exports$15 = /* @__PURE__ */ __exportAll({ default: () => generative_default$15 });
 /** The primary action register: solid ink for the one main action, outline, ghost, or subtle for the rest. */
 var generative_default$15 = defineEntry({ Button: {
@@ -444,8 +436,7 @@ var generative_default$15 = defineEntry({ Button: {
 		onClick: () => emit("press")
 	}, props.label)
 } });
-//#endregion
-//#region src/components/card/generative.ts
+// src/components/card/generative.ts
 var generative_exports$14 = /* @__PURE__ */ __exportAll({ default: () => generative_default$14 });
 /** Grouping vessel. Give title and description instead of hand-building a header; children render in the body; footer holds actions. */
 var generative_default$14 = defineEntry({ Card: {
@@ -456,8 +447,7 @@ var generative_default$14 = defineEntry({ Card: {
 		return createElement(Card.Root, null, header ? createElement(Card.Header, null, header) : props.title != null || props.description != null ? createElement(Card.Header, null, props.title != null ? createElement(Card.Title, null, props.title) : null, props.description != null ? createElement(Card.Description, null, props.description) : null) : null, createElement(Card.Content, null, children), footer ? createElement(Card.Footer, null, footer) : null);
 	}
 } });
-//#endregion
-//#region src/components/checkbox/generative.ts
+// src/components/checkbox/generative.ts
 var generative_exports$13 = /* @__PURE__ */ __exportAll({ default: () => generative_default$13 });
 /** One independent box with its label. */
 var generative_default$13 = defineEntry({ Checkbox: {
@@ -474,8 +464,7 @@ var generative_default$13 = defineEntry({ Checkbox: {
 		]);
 	}
 } });
-//#endregion
-//#region src/components/float-button/generative.ts
+// src/components/float-button/generative.ts
 var generative_exports$12 = /* @__PURE__ */ __exportAll({ default: () => generative_default$12 });
 /** A floating action cluster; named actions fan out from one corner. */
 var generative_default$12 = defineEntry({ FloatButton: {
@@ -492,8 +481,7 @@ var generative_default$12 = defineEntry({ FloatButton: {
 		});
 	}
 } });
-//#endregion
-//#region src/components/input/generative.ts
+// src/components/input/generative.ts
 var generative_exports$11 = /* @__PURE__ */ __exportAll({ default: () => generative_default$11 });
 /** A single-line field; rely on border, surface and the focus halo. */
 var generative_default$11 = defineEntry({ Input: {
@@ -509,8 +497,7 @@ var generative_default$11 = defineEntry({ Input: {
 		}));
 	}
 } });
-//#endregion
-//#region src/components/progress/generative.ts
+// src/components/progress/generative.ts
 var generative_exports$10 = /* @__PURE__ */ __exportAll({ default: () => generative_default$10 });
 /** A working track that fills toward done. */
 var generative_default$10 = defineEntry({ Progress: {
@@ -520,8 +507,7 @@ var generative_default$10 = defineEntry({ Progress: {
 		max: props.max
 	}, props.label != null ? createElement(Progress.Label, null, props.label) : null, createElement(Progress.Track, null, createElement(Progress.Range)))
 } });
-//#endregion
-//#region src/components/radio-group/generative.ts
+// src/components/radio-group/generative.ts
 var generative_exports$9 = /* @__PURE__ */ __exportAll({ default: () => generative_default$9 });
 /** Several boxes where exactly one may hold. */
 var generative_default$9 = defineEntry({ RadioGroup: {
@@ -538,8 +524,7 @@ var generative_default$9 = defineEntry({ RadioGroup: {
 		}, createElement(RadioGroup.ItemControl), createElement(RadioGroup.ItemText, null, value), createElement(RadioGroup.ItemHiddenInput))))));
 	}
 } });
-//#endregion
-//#region src/components/select/generative.tsx
+// src/components/select/generative.tsx
 var generative_exports$8 = /* @__PURE__ */ __exportAll({ default: () => generative_default$8 });
 /** A choice field that opens a ruled list; options carry label and value. */
 var generative_default$8 = defineEntry({ Select: {
@@ -557,8 +542,7 @@ var generative_default$8 = defineEntry({ Select: {
 		});
 	}
 } });
-//#endregion
-//#region src/components/separator/generative.ts
+// src/components/separator/generative.ts
 var generative_exports$7 = /* @__PURE__ */ __exportAll({ default: () => generative_default$7 });
 /** Hairline divider between sections. */
 var generative_default$7 = defineEntry({ Separator: {
@@ -568,8 +552,7 @@ var generative_default$7 = defineEntry({ Separator: {
 		decorative: true
 	})
 } });
-//#endregion
-//#region src/components/slider/generative.ts
+// src/components/slider/generative.ts
 var generative_exports$6 = /* @__PURE__ */ __exportAll({ default: () => generative_default$6 });
 /** A ruled track the hand slides between bounds. */
 var generative_default$6 = defineEntry({ Slider: {
@@ -584,8 +567,7 @@ var generative_default$6 = defineEntry({ Slider: {
 		key: 0
 	})])]))
 } });
-//#endregion
-//#region src/components/spinner/generative.ts
+// src/components/spinner/generative.ts
 var generative_exports$5 = /* @__PURE__ */ __exportAll({ default: () => generative_default$5 });
 /** A quiet wheel for work still settling. */
 var generative_default$5 = defineEntry({ Spinner: {
@@ -595,8 +577,7 @@ var generative_default$5 = defineEntry({ Spinner: {
 		"aria-label": props.label
 	})
 } });
-//#endregion
-//#region src/components/stack/generative.ts
+// src/components/stack/generative.ts
 var generative_exports$4 = /* @__PURE__ */ __exportAll({ default: () => generative_default$4 });
 /** Flex container for layout. direction column stacks vertically, row lays side by side. gap is a named spacing step. */
 var generative_default$4 = defineEntry({ Stack: {
@@ -609,8 +590,7 @@ var generative_default$4 = defineEntry({ Stack: {
 		wrap: props.wrap
 	}, children)
 } });
-//#endregion
-//#region src/components/stat/generative.ts
+// src/components/stat/generative.ts
 var generative_exports$3 = /* @__PURE__ */ __exportAll({ default: () => generative_default$3 });
 /** One loud figure with its quiet label and an optional delta. */
 var generative_default$3 = defineEntry({ Stat: {
@@ -621,8 +601,7 @@ var generative_default$3 = defineEntry({ Stat: {
 		props.change != null ? createElement(Stat.Delta, { direction: props.direction ?? "flat" }, props.change) : null
 	])
 } });
-//#endregion
-//#region src/components/switch/generative.ts
+// src/components/switch/generative.ts
 var generative_exports$2 = /* @__PURE__ */ __exportAll({ default: () => generative_default$2 });
 /** An instant on/off; label names what it switches. */
 var generative_default$2 = defineEntry({ Switch: {
@@ -640,8 +619,7 @@ var generative_default$2 = defineEntry({ Switch: {
 		]);
 	}
 } });
-//#endregion
-//#region src/components/textarea/generative.ts
+// src/components/textarea/generative.ts
 var generative_exports$1 = /* @__PURE__ */ __exportAll({ default: () => generative_default$1 });
 /** A multi-line field for prose-length answers. */
 var generative_default$1 = defineEntry({ Textarea: {
@@ -657,8 +635,7 @@ var generative_default$1 = defineEntry({ Textarea: {
 		}));
 	}
 } });
-//#endregion
-//#region src/components/typography/generative.ts
+// src/components/typography/generative.ts
 var generative_exports = /* @__PURE__ */ __exportAll({ default: () => generative_default });
 /** Section heading. One per view at level 1; do not skip levels. */
 var generative_default = defineEntry({
@@ -674,8 +651,7 @@ var generative_default = defineEntry({
 		}
 	}
 });
-//#endregion
-//#region src/generative/index.ts
+// src/generative/index.ts
 /** Every family writes its own generative face beside the component —
 * `components/<family>/generative.ts` — and this module is where they
 * meet: one glob picks the faces up, so a family that lands in the
@@ -731,5 +707,4 @@ const { registry } = defineRegistry(catalog, {
 * several names - Layout plus its parts, Bento plus its cell - and the
 * palette groups by provenance, never by guessing from the name. */
 const faceFamilies = Object.fromEntries(Object.entries(entries).map(([name, entry]) => [name, entry._from]));
-//#endregion
 export { catalog, faceFamilies, registry };

package/dist/{icon-Cri0-7-x.mjs → icon-C9udWCyz.mjs}

@@ -1,6 +1,6 @@
 import { getIcon } from "@bysages/core/icons";
 import { jsx } from "react/jsx-runtime";
-//#region src/internal/icon.tsx
+// src/internal/icon.tsx
 /** Render a curated registry icon as a bare svg element — the components
 * own default icons. No span shell: the part rules size the svg directly.
 * Extra body appends after the icon's own body, for composed marks. */
@@ -34,5 +34,4 @@ function iconHtml(name, attrs = {}, extraBody = "") {
 	};
 	return `<svg${Object.entries(attributes).map(([key, value]) => ` ${key}="${value}"`).join("")}>${icon.body + extraBody}</svg>`;
 }
-//#endregion
 export { iconHtml as n, iconNode as r, iconBody as t };

package/dist/{id-C37UYLwJ.mjs → id-Ctic_3o8.mjs}

@@ -1,5 +1,5 @@
 import { useId } from "react";
-//#region src/internal/id.ts
+// src/internal/id.ts
 /** Zag composes owned-part ids with separators, so React's generated id
 * is narrowed to characters that survive both markup and selectors. */
 const UNSAFE_ID_CHARACTERS = /[^a-zA-Z0-9_-]/g;
@@ -9,5 +9,4 @@ function useElementId(scope, props = {}) {
 	const explicit = props.id;
 	return typeof explicit === "string" && explicit ? explicit : `bs-${scope}-${generated.replace(UNSAFE_ID_CHARACTERS, "-")}`;
 }
-//#endregion
 export { useElementId as t };

package/dist/{image-viewer-D4FuYrk6.mjs → image-viewer-BPTApdoP.mjs}

@@ -1,15 +1,16 @@
-import { r as iconNode } from "./icon-Cri0-7-x.mjs";
-import { t as useElementId } from "./id-C37UYLwJ.mjs";
-import { n as useComponentMessages } from "./messages-1jJWtaYU.mjs";
+import { r as iconNode } from "./icon-C9udWCyz.mjs";
+import { t as useElementId } from "./id-Ctic_3o8.mjs";
+import { n as useComponentMessages } from "./messages-B6n0lVyt.mjs";
 import { Button } from "./components/button/index.mjs";
+import { t as FloatingPortal } from "./floating-CMR7cvmA.mjs";
 import { ButtonGroup } from "./components/button-group/index.mjs";
 import { Dialog as Dialog$1 } from "./components/dialog/index.mjs";
+import { createImageViewerGestures } from "@bysages/core";
 import { injectComponentStyle } from "@bysages/core/styling";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { Portal } from "@ark-ui/react/portal";
+import { useEffect, useRef, useState } from "react";
 import { Dialog } from "@ark-ui/react/dialog";
-//#region src/components/image-viewer/preview.tsx
+// src/components/image-viewer/preview.tsx
 /** The default doorway is the curated preview icon; custom content keeps
 * that icon as its hover and focus affordance. */
 function ImageViewerPreview({ label, children, "data-part": dataPart, ...rest }) {
@@ -36,10 +37,7 @@ function ImageViewerPreview({ label, children, "data-part": dataPart, ...rest })
 		})]
 	});
 }
-//#endregion
-//#region src/components/image-viewer/index.tsx
-const MIN_SCALE = .5;
-const MAX_SCALE = 3;
+// src/components/image-viewer/index.tsx
 const SCALE_STEP = .25;
 const TOOL_ICONS = {
 	zoomIn: "zoom-in",
@@ -47,30 +45,28 @@ const TOOL_ICONS = {
 	rotate: "rotate-cw",
 	close: "x"
 };
-function ImageViewerImpl({ src, alt = "", open, zoomable = true, width, height, children, onOpenChange, id }) {
+function ImageViewerImpl({ portal = true, src, alt = "", open, zoomable = true, width, height, children, onOpenChange, id }) {
 	injectComponentStyle("image-viewer");
 	const hostId = useElementId("image-viewer", { id });
 	const messages = useComponentMessages();
 	const [localOpen, setLocalOpen] = useState(false);
-	const [scale, setScale] = useState(1);
-	const [rotation, setRotation] = useState(0);
+	const viewportRef = useRef(null);
+	const gesturesRef = useRef(null);
 	const isOpen = open ?? localOpen;
 	const setOpen = (value) => {
 		if (open === void 0) setLocalOpen(value);
 		onOpenChange?.(value);
 	};
 	useEffect(() => {
-		if (isOpen) {
-			setScale(1);
-			setRotation(0);
-		}
-	}, [isOpen]);
-	function zoom(step) {
-		setScale((current) => Math.min(MAX_SCALE, Math.max(MIN_SCALE, current + step)));
-	}
-	function rotate() {
-		setRotation((current) => (current + 90) % 360);
-	}
+		const node = viewportRef.current;
+		if (!node) return;
+		const gestures = createImageViewerGestures(node, { zoomable });
+		gesturesRef.current = gestures;
+		return () => {
+			gesturesRef.current = null;
+			gestures.stop();
+		};
+	}, [isOpen, zoomable]);
 	function toolButton(label, icon, onClick) {
 		return /* @__PURE__ */ jsx(Button, {
 			variant: "ghost",
@@ -104,38 +100,40 @@ function ImageViewerImpl({ src, alt = "", open, zoomable = true, width, height,
 			"data-scope": "image-viewer",
 			"data-part": "trigger",
 			children: children ?? /* @__PURE__ */ jsx(ImageViewerPreview, {})
-		}), /* @__PURE__ */ jsxs(Portal, { children: [/* @__PURE__ */ jsx(Dialog.Backdrop, { className: "bs-image-viewer-backdrop" }), /* @__PURE__ */ jsx(Dialog.Positioner, {
-			className: "bs-image-viewer-positioner",
-			children: /* @__PURE__ */ jsxs(Dialog.Content, {
-				className: "bs-image-viewer-content",
-				"aria-label": alt || "Image preview",
-				onClick: (event) => {
-					if (event.target === event.currentTarget) setOpen(false);
-				},
-				children: [/* @__PURE__ */ jsx("img", {
-					"data-scope": "image-viewer",
-					"data-part": "viewport",
-					src,
-					alt,
-					width,
-					height,
-					style: { "--bs-image-viewer-transform": `scale(${scale}) rotate(${rotation}deg)` }
-				}), /* @__PURE__ */ jsx("div", {
-					"data-scope": "image-viewer",
-					"data-part": "toolbar",
-					children: /* @__PURE__ */ jsxs(ButtonGroup, { children: [
-						zoomable ? [toolButton(messages.imageViewer.zoomIn, TOOL_ICONS.zoomIn, () => zoom(SCALE_STEP)), toolButton(messages.imageViewer.zoomOut, TOOL_ICONS.zoomOut, () => zoom(-.25))] : null,
-						toolButton(messages.imageViewer.rotate, TOOL_ICONS.rotate, rotate),
-						closeToolButton(messages.imageViewer.close, TOOL_ICONS.close)
-					] })
-				})]
-			})
-		})] })]
+		}), /* @__PURE__ */ jsxs(FloatingPortal, {
+			portal,
+			children: [/* @__PURE__ */ jsx(Dialog.Backdrop, { className: "bs-image-viewer-backdrop" }), /* @__PURE__ */ jsx(Dialog.Positioner, {
+				className: "bs-image-viewer-positioner",
+				children: /* @__PURE__ */ jsxs(Dialog.Content, {
+					className: "bs-image-viewer-content",
+					"aria-label": alt || "Image preview",
+					onClick: (event) => {
+						if (event.target === event.currentTarget) setOpen(false);
+					},
+					children: [/* @__PURE__ */ jsx("img", {
+						"data-scope": "image-viewer",
+						"data-part": "viewport",
+						src,
+						alt,
+						width,
+						height,
+						ref: viewportRef
+					}), /* @__PURE__ */ jsx("div", {
+						"data-scope": "image-viewer",
+						"data-part": "toolbar",
+						children: /* @__PURE__ */ jsxs(ButtonGroup, { children: [
+							zoomable ? [toolButton(messages.imageViewer.zoomIn, TOOL_ICONS.zoomIn, () => gesturesRef.current?.zoomBy(SCALE_STEP)), toolButton(messages.imageViewer.zoomOut, TOOL_ICONS.zoomOut, () => gesturesRef.current?.zoomBy(-.25))] : null,
+							toolButton(messages.imageViewer.rotate, TOOL_ICONS.rotate, () => gesturesRef.current?.rotate()),
+							closeToolButton(messages.imageViewer.close, TOOL_ICONS.close)
+						] })
+					})]
+				})
+			})]
+		})]
 	});
 }
 const ImageViewer = Object.assign(ImageViewerImpl, {
 	...Dialog$1,
 	Preview: ImageViewerPreview
 });
-//#endregion
 export { ImageViewer as t };

package/dist/index-CEYybyEQ.d.mts

@@ -0,0 +1,163 @@
+import { n as FloatingPortalTarget } from "./floating-BhcDRgnx.mjs";
+import { t as Popover } from "./index-j02dTkfc.mjs";
+import { HTMLAttributes } from "react";
+type MentionCommitKey = "Enter" | "Tab" | " ";
+interface UseMentionsOptions {
+  /** The candidates offered once a trigger character is typed. */
+  items: MentionEntry[];
+  /** The character that summons the candidates. */
+  trigger?: string;
+  /** One or more summoning characters; the longest token closest to the
+   * caret wins when several triggers are active. */
+  triggers?: string | string[];
+  /** Keys that choose the highlighted candidate. */
+  commitKeys?: MentionCommitKey[];
+}
+interface UseMentionsHandlers {
+  /** The text the field holds right now — read at keystroke time, never
+   * from a controlled prop that lags a render behind the caret. */
+  getText: () => string;
+  /** Writes the field's next text: a mention inserted at the token. */
+  setText: (value: string) => void;
+  /** The absolute text offset of the field caret; a rich editor supplies this.
+   * A textarea is read from its own selection when omitted. */
+  getCaret?: () => number | undefined;
+  /** Called before insertion. Return `false` to record the choice without
+   * rewriting composer text — useful for slash commands and context chips. */
+  select?: (entry: MentionEntry) => boolean | void;
+  /** Replaces default insertion so rich editors can commit their own token. */
+  commit?: (entry: MentionEntry) => void;
+}
+/** Whatever carries a key press — a native KeyboardEvent or a React
+ * synthetic one; the detector only needs the key's name and the power
+ * to hold the key back. */
+interface MentionKeyEvent {
+  key: string;
+  preventDefault: () => void;
+}
+/** The detection machinery behind a mention field: watch the caret,
+ * offer the matching candidates, and answer for the keys that drive
+ * them. The field element arrives as a getter because hosts wrap it
+ * differently (a bare textarea, a field part's ref).
+ *
+ * `onKeydown` answers whether the vessel consumed the key, so a host
+ * with its own Enter semantics — a composer that sends — can yield to
+ * the candidates first and act only when the vessel stands down. */
+declare function useMentions(options: UseMentionsOptions | (() => UseMentionsOptions), textarea: () => HTMLTextAreaElement | null, handlers: UseMentionsHandlers): {
+  open: boolean;
+  matches: MentionEntry[];
+  active: number;
+  setActive: import("react").Dispatch<import("react").SetStateAction<number>>;
+  anchorIndex: import("react").RefObject<number>;
+  caretIndex: import("react").RefObject<number>;
+  activeTrigger: import("react").RefObject<string>;
+  insert: (entry: MentionEntry) => void;
+  close: () => void;
+  onInput: () => void;
+  onKeydown: (event: MentionKeyEvent) => boolean;
+};
+interface MentionEntry {
+  /** Stable identity for tests, popups and business handlers. */
+  id?: string;
+  /** The primary words shown in the popup and inserted by default. */
+  label: string;
+  /** The semantic value reported by the field. */
+  value: string;
+  /** One line of supporting copy under the label. */
+  description?: string;
+  /** A curated core icon name. */
+  icon?: string;
+  /** Optional section heading; entries with the same heading travel together. */
+  group?: string;
+  /** The consumer's coarse entry type, such as `file`, `agent` or `command`. */
+  kind?: string;
+  /** A visible candidate the keyboard and pointer cannot choose. */
+  disabled?: boolean;
+  /** Exact composer text to insert; it bypasses `trigger + label`. */
+  insertText?: string;
+  /** Extra consumer data carried back through `onSelect`. */
+  meta?: Record<string, unknown>;
+}
+type MentionTriggers = string | string[];
+type MentionPlacement = "bottom-start" | "top-start";
+interface MentionsVesselProps {
+  /** Portal after hydration; `false` keeps the vessel inline. */
+  portal?: FloatingPortalTarget;
+  id?: string;
+  /** The host field's rung, so the rows keep the field's register. */
+  size?: "sm" | "md" | "lg";
+  /** Whether the candidates are up. */
+  open?: boolean;
+  /** The candidates on offer. */
+  matches?: MentionEntry[];
+  /** The keyboard's active row. */
+  active?: number;
+  /** The rectangle the vessel points at — the host's textarea. */
+  anchor?: HTMLElement | null;
+  /** Which side of the anchor hosts the candidates. */
+  placement?: MentionPlacement;
+  /** A candidate was chosen. */
+  onInsert?: (entry: MentionEntry) => void;
+  /** The pointer moved to a row. */
+  onActiveChange?: (index: number) => void;
+  /** The vessel was dismissed. */
+  onOpenChange?: (open: boolean) => void;
+}
+/** The vessel: the candidates themselves as a floating card. The anchor
+ * is virtual — a live rectangle off the host's field — so a host keeps
+ * its own anatomy (the textarea rides where the host puts it) and the
+ * vessel still points at the right place. Shares the detection state
+ * with the host through `useMentions`. */
+declare function MentionsVesselImpl({ portal, size, open, matches, active, anchor, placement, onInsert, onActiveChange, onOpenChange, id }: MentionsVesselProps): import("react").JSX.Element;
+declare const MentionsVessel: typeof MentionsVesselImpl & {
+  Root: typeof MentionsVesselImpl;
+};
+/**
+ * Mentions: a textarea that, when the text before the caret ends with a
+ * trigger character followed by a token, offers matching candidates in a
+ * small anchored vessel. Entries may carry descriptions, icons, groups
+ * and consumer metadata. Selecting reports the whole entry; by default it
+ * also replaces the token with `trigger + label`.
+ *
+ * The field is the shared `Field.Textarea` — field wiring (label ids,
+ * the invalid state, autoresize) rides on it for free — and the vessel
+ * anchors through the popover's own `Anchor` part wrapped around the
+ * field, so the machine, not a local rectangle, points the popup at the
+ * input. Composers that keep their own field anatomy (the AI prompt
+ * input) skip this shell and wire `useMentions` plus `MentionsVessel`
+ * themselves.
+ */
+interface MentionsProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  /** Portal after hydration; `false` keeps the vessel inline. */
+  portal?: FloatingPortalTarget;
+  /** The candidates offered once a trigger character is typed. */
+  items?: MentionEntry[];
+  /** The text held by the field. Supply it to control the field;
+   * changes are reported via `onValueChange`. */
+  value?: string;
+  /** The character that summons the candidates. */
+  trigger?: string;
+  /** One or more summoning characters, such as `@` and `/`. */
+  triggers?: MentionTriggers;
+  /** Keep composer text untouched when a candidate is selected. */
+  insertOnSelect?: boolean;
+  /** Keys that choose the highlighted candidate. */
+  commitKeys?: MentionCommitKey[];
+  /** Which side of the field hosts the candidates. */
+  placement?: MentionPlacement;
+  placeholder?: string;
+  /** Let the field grow with its text instead of holding `rows`. */
+  autoresize?: boolean;
+  /** Standing alone, the field styles itself from this flag; inside a
+   * `Field.Root` the field's own invalid state takes over. */
+  invalid?: boolean;
+  /** One rung of the control-height ladder for the resting field. */
+  size?: "sm" | "md" | "lg";
+  /** Reports the field's next text. */
+  onValueChange?: (value: string) => void;
+  /** Reports the whole selected entry. */
+  onSelect?: (entry: MentionEntry) => void;
+}
+declare function MentionsImpl({ portal, items, value, trigger, triggers, insertOnSelect, commitKeys, placement, placeholder, autoresize, invalid, size, onValueChange, onSelect, children, ...rest }: MentionsProps): import("react").JSX.Element;
+declare const Mentions: typeof MentionsImpl & typeof Popover;
+export { MentionsProps as a, MentionCommitKey as c, useMentions as d, Mentions as i, UseMentionsHandlers as l, MentionPlacement as n, MentionsVessel as o, MentionTriggers as r, MentionsVesselProps as s, MentionEntry as t, UseMentionsOptions as u };