@mast-ai/react-ui 0.1.0

package/dist/mentions/MentionPicker.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import type { MentionItem } from './types';
+/**
+ * Props accepted by {@link MentionPicker}. Exported for consumers building
+ * a bespoke compound input on top of {@link useMentions}.
+ */
+export interface MentionPickerProps<T = unknown> {
+    /** Items to render. Empty list hides the picker entirely. */
+    items: MentionItem<T>[];
+    /** Index of the keyboard-active row. */
+    activeIndex: number;
+    /** Called when the user clicks a row. */
+    onSelect: (item: MentionItem<T>) => void;
+    /**
+     * Stable id prefix used to build the per-option DOM id. Consumers that
+     * wire `aria-activedescendant` on a textarea should pass the same prefix
+     * and read the active id as `${idPrefix}-${activeIndex}`.
+     */
+    idPrefix: string;
+    /** Renders a custom row body. Default: a `<div>` showing `item.label`. */
+    renderItem?: (item: MentionItem<T>, isActive: boolean) => ReactNode;
+}
+/**
+ * Floating popover rendered above {@link import('../components/ChatInput').ChatInput}
+ * when an in-progress mention has at least one filtered item.
+ *
+ * Uses `role="listbox"` with `role="option"` rows so screen readers announce
+ * the active row when the textarea's `aria-activedescendant` updates.
+ */
+export declare function MentionPicker<T = unknown>({ items, activeIndex, onSelect, idPrefix, renderItem, }: MentionPickerProps<T>): import("react/jsx-runtime").JSX.Element | null;

package/dist/mentions/index.d.ts

@@ -0,0 +1,6 @@
+export type { MentionItem, MentionSegment, MentionsConfig } from './types';
+export { buildInlineMentionPrompt, extractMentionQuery, removeMentionTrigger } from './utils';
+export { useMentions } from './useMentions';
+export type { UseMentionsReturn } from './useMentions';
+export { MentionPicker } from './MentionPicker';
+export type { MentionPickerProps } from './MentionPicker';

package/dist/mentions/types.d.ts

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+/**
+ * A single picker entry. Generic over `T` so consumers can attach arbitrary
+ * payloads (document records, file paths, skill descriptors, …) without the
+ * library knowing the domain shape.
+ */
+export interface MentionItem<T = unknown> {
+    /** Stable key. Used as the React key in the picker and the chip identifier. */
+    id: string;
+    /** Shown in the picker row and rendered as the chip text after the trigger. */
+    label: string;
+    /** Optional secondary text rendered alongside `label` in the picker. */
+    description?: string;
+    /** Arbitrary payload accessible from `buildPrompt`, `renderItem`, `renderChip`. */
+    data?: T;
+}
+/**
+ * The committed compound input is `MentionSegment<T>[]` followed by a free-form
+ * trailing string. Each segment is the plain text immediately preceding a chip
+ * plus the mentioned item itself; selecting a new item from the picker
+ * appends a segment and starts a fresh trailing region.
+ */
+export interface MentionSegment<T = unknown> {
+    /** Plain text preceding the chip. */
+    text: string;
+    /** The mentioned item that terminates this segment. */
+    item: MentionItem<T>;
+}
+/**
+ * Configuration object accepted by `<ChatInput mentions={...}>`,
+ * `<ConversationPanel mentions={...}>`, and `useMentions`. Every field except
+ * one of `items` / `onSearch` is optional.
+ */
+export interface MentionsConfig<T = unknown> {
+    /** Trigger character. Default: `'@'`. Must be a single character. */
+    trigger?: string;
+    /**
+     * Static item list. The picker filters by case-insensitive substring on
+     * `label`. Mutually exclusive with `onSearch`; if both are provided
+     * `onSearch` wins.
+     */
+    items?: MentionItem<T>[];
+    /**
+     * Async or sync search function. Called with the current query each time it
+     * changes. The latest result wins — stale resolutions are discarded so
+     * out-of-order responses cannot replace newer matches.
+     */
+    onSearch?: (query: string) => MentionItem<T>[] | Promise<MentionItem<T>[]>;
+    /** Renders a custom row in the picker. Default: `<div>{item.label}</div>`. */
+    renderItem?: (item: MentionItem<T>, isActive: boolean) => ReactNode;
+    /**
+     * Renders the chip that replaces the in-progress `@<query>` once selected.
+     * Default: the library renders `@<label>` followed by an `x` remove button.
+     */
+    renderChip?: (item: MentionItem<T>, onRemove: () => void) => ReactNode;
+    /**
+     * Builds the prompt sent to the LLM from the segment list and trailing
+     * text. Default: returns the inline display form (segments joined as
+     * `<text>@<label>...<trailing>`). Override this to inject context
+     * (document IDs, file paths, …) around or before the inline text.
+     */
+    buildPrompt?: (segments: MentionSegment<T>[], trailing: string) => string;
+}

package/dist/mentions/useMentions.d.ts

@@ -0,0 +1,54 @@
+import type { KeyboardEvent } from 'react';
+import type { MentionItem, MentionSegment, MentionsConfig } from './types';
+/**
+ * Return shape of {@link useMentions}.
+ *
+ * Consumers either pass the whole object to `<ChatInput mentions>` (via the
+ * `mentions` config — `<ChatInput>` calls `useMentions` internally) or wire
+ * the individual fields into a bespoke compound input.
+ */
+export interface UseMentionsReturn<T = unknown> {
+    /** Committed segments preceding the trailing-text region. */
+    segments: MentionSegment<T>[];
+    /** Free-form text after the last chip (or the whole field when no chips). */
+    trailingInput: string;
+    /** Current `@<query>` if the cursor is inside an in-progress mention. */
+    mentionQuery: string | null;
+    /** Items the picker should render right now (filtered or async-resolved). */
+    filteredItems: MentionItem<T>[];
+    /** Index of the keyboard-highlighted picker row. */
+    pickerIndex: number;
+    /** Set the trailing-text region. Recomputes `mentionQuery` and resets picker focus. */
+    setTrailingInput: (text: string) => void;
+    /**
+     * Wire to the textarea's `onKeyDown`. Returns `true` if the key was
+     * consumed by the picker so the host can suppress its own handling. Up /
+     * Down / Enter / Escape are only consumed when the picker has at least one
+     * filtered item.
+     */
+    handleKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => boolean;
+    /** Append a chip and reset the in-progress mention. */
+    selectItem: (item: MentionItem<T>) => void;
+    /** Remove a chip by id, re-merging its preceding text into the next region. */
+    removeChip: (id: string) => void;
+    /** Build `{ prompt, displayText }` for `sendMessage`. */
+    buildSubmission: () => {
+        prompt: string;
+        displayText: string;
+    };
+    /** Clear all segments and trailing text. */
+    clear: () => void;
+}
+/**
+ * Owns the segment / trailing-text / picker-index state behind the optional
+ * `<ChatInput mentions>` UI. Exported so consumers can build a bespoke input
+ * (e.g. with their own picker component or virtualisation) without giving up
+ * the segment management and async-search plumbing.
+ *
+ * - `config.items` filters by case-insensitive substring on `label`.
+ * - `config.onSearch` is called every time the query changes; the latest
+ *   resolution wins so out-of-order responses cannot replace newer matches.
+ *   Already-selected items are filtered out of the picker so the same
+ *   reference cannot be picked twice.
+ */
+export declare function useMentions<T = unknown>(config: MentionsConfig<T>): UseMentionsReturn<T>;

package/dist/mentions/utils.d.ts

@@ -0,0 +1,33 @@
+import type { MentionSegment } from './types';
+/**
+ * Returns the query suffix at the end of `input` if the user is currently
+ * typing an in-progress mention, or `null` otherwise.
+ *
+ * A mention is considered in-progress when the trigger character appears
+ * after the last whitespace and is not followed by another whitespace
+ * character. The query may be empty (just typed `@` and nothing after).
+ *
+ * @example
+ *   extractMentionQuery('hello @doc') === 'doc'
+ *   extractMentionQuery('hello @')    === ''
+ *   extractMentionQuery('hello @doc ') === null   // space ends the mention
+ *   extractMentionQuery('hello world') === null   // no trigger
+ */
+export declare function extractMentionQuery(input: string, trigger?: string): string | null;
+/**
+ * Strips a trailing `@<query>` from `input`, preserving any whitespace
+ * the user typed before the trigger. Used after the user commits a picker
+ * selection — the preserved whitespace survives into the segment text so
+ * the inline display form (`<text>@<label>`) keeps the natural space
+ * between the preceding word and the chip.
+ */
+export declare function removeMentionTrigger(input: string, trigger?: string): string;
+/**
+ * Default `buildPrompt` implementation: returns the inline form
+ * `<text1>@<label1><text2>@<label2>...<trailing>`.
+ *
+ * Apps that want to inject extra context (document IDs, file paths, …) can
+ * call this and prepend / wrap the result, or build the string from scratch
+ * using `segments` and `trailing`.
+ */
+export declare function buildInlineMentionPrompt<T>(segments: MentionSegment<T>[], trailing: string): string;