@streamsai/ui 0.0.0-stage → 0.1.0

package/dist/components/ui/rich-text-editor.d.ts

@@ -0,0 +1,447 @@
+import * as React from 'react';
+import type { LexicalCommand, SerializedEditorState, SerializedLexicalNode } from 'lexical';
+import { type NodeKey, type EditorConfig, DecoratorNode } from 'lexical';
+import { type AgentPicture } from './agent-avatar.js';
+import { type ProviderMarkType } from '../../icons/index.js';
+/** Person/agent row for the `@` typeahead. */
+export type UserMentionCandidate = {
+    userId: string;
+    displayName: string;
+    avatarUrl?: string | null;
+    /** Distinguishes humans from agents in the picker (agent rows use a bot glyph). */
+    kind?: 'human' | 'agent';
+    /** An agent's Pingo or other resolved picture; wins over `avatarUrl` for agent rows. */
+    agentPicture?: AgentPicture | null;
+    /** The provider mark (and its accessible name) hung on an agent row's picture. */
+    providerBadge?: {
+        type: ProviderMarkType;
+        label: string;
+    } | null;
+    /** An agent's role, shown muted after its name. Humans carry none. */
+    role?: string | null;
+    /**
+     * When true the row stays visible but cannot be inserted (e.g. interactPolicy owner_only).
+     * Hosts set `disabledReason` for the muted subtitle.
+     */
+    disabled?: boolean;
+    /** Shown under the name when `disabled` (e.g. “Only Ada can interact with this agent”). */
+    disabledReason?: string;
+    /**
+     * Muted line under the name when the row is selectable (e.g. “Not in this stream”).
+     * Ignored when `disabled` — `disabledReason` wins.
+     */
+    subtitle?: string;
+};
+/**
+ * Synthetic `@all` row — everyone (human) in the current stream. Discriminated so hosts never
+ * invent a fake `userId` sentinel.
+ */
+export type AllMentionCandidate = {
+    kind: 'all';
+    displayName: string;
+    subtitle?: string;
+};
+export type MentionCandidate = UserMentionCandidate | AllMentionCandidate;
+export declare const isAllMentionCandidate: (candidate: MentionCandidate) => candidate is AllMentionCandidate;
+/** Page request for the `@` typeahead. `offset` counts user rows only (not `@all`). */
+export type MentionSearchOptions = {
+    offset: number;
+    limit: number;
+};
+/** One page of `@` candidates. Hosts set `hasMore` when further pages exist. */
+export type MentionSearchResult = {
+    items: MentionCandidate[];
+    hasMore: boolean;
+    /**
+     * The complete first page from the slower source (the server), replacing `items` when it
+     * arrives. `items` are what the host holds locally and show at once. Only meaningful on the first
+     * page (`offset` 0). A rejection keeps `items`.
+     */
+    refresh?: Promise<MentionSearchResult>;
+};
+/** Default page size for the mention picker (first paint + each scroll fetch). */
+export declare const MENTION_PAGE_SIZE = 10;
+/** Host-supplied slash command for the composer typeahead (cycle triggers today). */
+export type SlashCommandCandidate = {
+    /** Host identity when `name` is not unique (two streams can have the same cycle name). */
+    key?: string;
+    name: string;
+    description: string;
+    /** Inserts a `CycleTriggerNode` via the same path as host `insertCycleTrigger`. */
+    cycleTriggerName?: string;
+    /** Plain insert when `cycleTriggerName` is absent; `null` means no text insert. */
+    insertText?: string | null;
+    /** Menu section; the menu lists `cycles` before `commands`. Ungrouped candidates show under one title. */
+    group?: 'cycles' | 'commands';
+    /** Draws a soft sweeping highlight behind the row, to point a first-time user at it. */
+    emphasis?: boolean;
+};
+/** Host-supplied emoji for the `:` shortcode typeahead (Slack-style `:smile:`). */
+export type EmojiCandidate = {
+    /** Native emoji glyph inserted into the message (empty for account custom emoji). */
+    char: string;
+    /** Shortcode without colons (e.g. `smile`, `+1`). */
+    shortcode: string;
+    /** Optional display name shown beside the shortcode. */
+    name?: string;
+    /** When set, selecting inserts a `CustomEmojiNode` (image) instead of `char`. */
+    imageUrl?: string;
+};
+/**
+ * One emoji the person chose from the `:` menu or typed as a complete `:shortcode:`, reported once
+ * after it is in the document. Paste, drop, undo/redo, draft restore and programmatic inserts
+ * never report.
+ */
+export type EmojiUse = {
+    source: 'typeahead' | 'typed_shortcode';
+    kind: 'unicode' | 'custom';
+    /** The native glyph, or the shortcode name of a custom emoji (the host resolves aliases). */
+    emoji: string;
+};
+/** Default page size for the emoji shortcode typeahead. */
+export declare const EMOJI_TYPEAHEAD_LIMIT = 24;
+/** Host-supplied stream for the `#` typeahead; chips display as `~title`. */
+export type StreamCandidate = {
+    streamId: string;
+    title: string;
+    /** Drives the private lock affordance in the typeahead and inserted chip. */
+    visibility: 'public' | 'private';
+};
+/** Default page size for the stream chip typeahead. */
+export declare const STREAM_TYPEAHEAD_LIMIT = 10;
+interface MentionNodePayload {
+    userId?: string;
+    displayName?: string;
+    all?: boolean;
+}
+/** Custom node that round-trips with contracts/chat/adapters/lexical.ts */
+export declare class MentionNode extends DecoratorNode<React.JSX.Element> {
+    __userId: string | undefined;
+    __displayName: string | undefined;
+    __all: boolean | undefined;
+    static getType(): string;
+    static clone(node: MentionNode): MentionNode;
+    constructor(payload: MentionNodePayload, key?: NodeKey);
+    createDOM(_config: EditorConfig): HTMLElement;
+    updateDOM(): false;
+    static importJSON(serialized: any): MentionNode;
+    exportJSON(): SerializedLexicalNode & MentionNodePayload;
+    decorate(): React.JSX.Element;
+    isInline(): boolean;
+}
+export declare const $isMentionNode: (node: unknown) => node is MentionNode;
+interface CycleTriggerNodePayload {
+    triggerName: string;
+}
+/** Custom node that round-trips with contracts/chat/adapters/lexical.ts */
+export declare class CycleTriggerNode extends DecoratorNode<React.JSX.Element> {
+    __triggerName: string;
+    static getType(): string;
+    static clone(node: CycleTriggerNode): CycleTriggerNode;
+    constructor(payload: CycleTriggerNodePayload, key?: NodeKey);
+    createDOM(_config: EditorConfig): HTMLElement;
+    updateDOM(): false;
+    static importJSON(serialized: any): CycleTriggerNode;
+    exportJSON(): SerializedLexicalNode & CycleTriggerNodePayload;
+    decorate(): React.JSX.Element;
+    isInline(): boolean;
+}
+export declare const $createCycleTriggerNode: (triggerName: string) => CycleTriggerNode;
+export declare const $isCycleTriggerNode: (node: unknown) => node is CycleTriggerNode;
+interface StreamChipNodePayload {
+    streamId: string;
+    title: string;
+    visibility?: 'public' | 'private';
+}
+/** Custom node that round-trips with contracts/chat/adapters/lexical.ts (`type: 'stream-chip'`). */
+export declare class StreamChipNode extends DecoratorNode<React.JSX.Element> {
+    __streamId: string;
+    __title: string;
+    __visibility?: 'public' | 'private';
+    static getType(): string;
+    static clone(node: StreamChipNode): StreamChipNode;
+    constructor(payload: StreamChipNodePayload, key?: NodeKey);
+    createDOM(_config: EditorConfig): HTMLElement;
+    updateDOM(): false;
+    static importJSON(serialized: any): StreamChipNode;
+    exportJSON(): SerializedLexicalNode & StreamChipNodePayload;
+    decorate(): React.JSX.Element;
+    isInline(): boolean;
+}
+export declare const $createStreamChipNode: (streamId: string, title: string, visibility?: "public" | "private") => StreamChipNode;
+export declare const $isStreamChipNode: (node: unknown) => node is StreamChipNode;
+interface CustomEmojiNodePayload {
+    name: string;
+    imageUrl: string;
+}
+/**
+ * Account custom emoji in the composer — renders the image; serializes as `custom-emoji` and the
+ * lexical adapter stores `:name:` text in MessageContent.
+ */
+export declare class CustomEmojiNode extends DecoratorNode<React.JSX.Element> {
+    __name: string;
+    __imageUrl: string;
+    static getType(): string;
+    static clone(node: CustomEmojiNode): CustomEmojiNode;
+    constructor(payload: CustomEmojiNodePayload, key?: NodeKey);
+    createDOM(_config: EditorConfig): HTMLElement;
+    updateDOM(): false;
+    static importJSON(serialized: any): CustomEmojiNode;
+    exportJSON(): SerializedLexicalNode & CustomEmojiNodePayload;
+    decorate(): React.JSX.Element;
+    isInline(): boolean;
+    getTextContent(): string;
+}
+export declare const $createCustomEmojiNode: (name: string, imageUrl: string) => CustomEmojiNode;
+export declare const $isCustomEmojiNode: (node: unknown) => node is CustomEmojiNode;
+/**
+ * Replaces the `/query` text at the start of the first paragraph with a `CycleTriggerNode` and a
+ * space. Refused (no-op) while the editor already holds a trigger: one `/trigger` per message.
+ */
+export declare const INSERT_CYCLE_TRIGGER_COMMAND: LexicalCommand<{
+    triggerName: string;
+    /** Swap an existing trigger for this one instead of refusing. */
+    replace?: boolean;
+}>;
+/** Inserts a `CustomEmojiNode` at the caret (picker / host-driven). */
+export declare const INSERT_CUSTOM_EMOJI_COMMAND: LexicalCommand<{
+    name: string;
+    imageUrl: string;
+}>;
+export type CycleTriggerRequest = {
+    triggerName: string;
+    /** Swap the trigger already in the message (a picker choosing another cycle). */
+    replace?: boolean;
+    /** Changes on every request so the same trigger can be inserted again after a clear. */
+    nonce: number;
+};
+export type CustomEmojiRequest = {
+    name: string;
+    imageUrl: string;
+    /** Changes on every request so the same emoji can be inserted again. */
+    nonce: number;
+};
+/** Closing-colon expand may return a native glyph or a custom emoji image. */
+export type EmojiShortcodeResolve = string | {
+    name: string;
+    imageUrl: string;
+};
+/** Host-driven text insertion at the caret (composer `@` / `/` buttons). */
+export type InsertTextRequest = {
+    text: string;
+    /** Changes on every request so the same text can be inserted again. */
+    nonce: number;
+};
+/**
+ * The part of the layout viewport the user sees, in layout-viewport Y (the menu is `position:
+ * fixed`, so everything here shares the coordinates of `getBoundingClientRect`). The visual
+ * viewport is a window into the layout viewport, so it can neither start below nor end past it.
+ * Inside the iOS app `offsetTop` has been seen to stay at the keyboard pan after the page was
+ * resized to sit above the keyboard: taken as is, it moved the top limit below the composer and
+ * left the list two rows tall. The clamp makes that report harmless.
+ */
+export declare function visibleArea({ layoutHeight, offsetTop, height, }: {
+    layoutHeight: number;
+    offsetTop?: number;
+    height?: number;
+}): {
+    topY: number;
+    bottomY: number;
+};
+/**
+ * Where the list's bottom edge goes and how tall it may be, in layout-viewport Y. The list sits
+ * above `preferredBottomY` (the composer footer top, or the caret line without a footer) and below
+ * the chrome, and never leaves `[visibleTopY, visibleBottomY]`. Its height is the room between
+ * them, up to 240px; a cramped screen shows fewer rows rather than rows under the native bar.
+ * Only a mobile composer footer (`coverDraftWhenCramped`) has a last resort: when under one row
+ * fits above the composer (landscape with the keyboard up), the list takes the top of the safe
+ * area and covers the draft, because a list nobody can reach is worse. Without a footer (desktop,
+ * inline edit) the bottom edge stays on the caret line so the typed text is never covered.
+ */
+export declare function placeTypeahead({ preferredBottomY, visibleTopY, visibleBottomY, topChromePx: chromePx, coverDraftWhenCramped, }: {
+    /** Bottom edge that keeps the list clear of the composer (footer top or caret line). */
+    preferredBottomY: number;
+    visibleTopY: number;
+    visibleBottomY: number;
+    /** Safe-area inset plus the native bar; 0 when the page has none. */
+    topChromePx: number;
+    coverDraftWhenCramped?: boolean;
+}): {
+    bottomY: number;
+    maxHeight: number;
+};
+/** Accessible names for the document-mode controls; English defaults, override for i18n. */
+export type DocumentModeLabels = {
+    heading2: string;
+    heading3: string;
+    image: string;
+    imageAlt: string;
+    imageAltPlaceholder: string;
+    imageAltRequired: string;
+    imageRemove: string;
+    imageUnavailable: string;
+    uploading: string;
+};
+export type DocumentImageReject = 'type' | 'limit';
+/**
+ * Opts the editor into document mode (the stream About): heading buttons, block images, a
+ * markdown shortcut set without code fences or strikethrough. Uploading stays with the host.
+ */
+export type DocumentModeOptions = {
+    /** Content types the picker, paste and drop accept; anything else goes to `onReject`. */
+    acceptedImageTypes: readonly string[];
+    /** Stores one picked, pasted or dropped file; resolve to the asset id, or null when it failed (the host reports it). */
+    uploadImage: (file: File) => Promise<string | null>;
+    /** Preview URL for an image block; null while it is still being resolved. */
+    resolveImageUrl: (assetId: string) => string | null;
+    /** Most images the document may hold; further files go to `onReject('limit')`. */
+    maxImages?: number;
+    onReject?: (file: File, reason: DocumentImageReject) => void;
+    onUploadingChange?: (uploading: boolean) => void;
+    labels?: Partial<DocumentModeLabels>;
+};
+/** Block image that round-trips with contracts/streams/about-lexical.ts (`type: 'about-image'`). */
+export declare class DocumentImageNode extends DecoratorNode<React.JSX.Element> {
+    __assetId: string;
+    __alt: string;
+    static getType(): string;
+    static clone(node: DocumentImageNode): DocumentImageNode;
+    constructor(assetId: string, alt: string, key?: NodeKey);
+    createDOM(_config: EditorConfig): HTMLElement;
+    updateDOM(): false;
+    static importJSON(serialized: any): DocumentImageNode;
+    exportJSON(): SerializedLexicalNode & {
+        assetId: string;
+        alt: string;
+    };
+    getAssetId(): string;
+    getAlt(): string;
+    setAlt(alt: string): this;
+    isInline(): boolean;
+    decorate(): React.JSX.Element;
+}
+export declare const $isDocumentImageNode: (node: unknown) => node is DocumentImageNode;
+export type RichTextEditorLabels = {
+    toolbar: string;
+    bold: string;
+    italic: string;
+    strikethrough: string;
+    code: string;
+    bulletList: string;
+    numberedList: string;
+    link: string;
+    linkDialogTitle: string;
+    linkDialogDescription: string;
+    linkUrl: string;
+    linkUrlPlaceholder: string;
+    linkText: string;
+    linkTextPlaceholder: string;
+    linkInvalid: string;
+    linkRemove: string;
+    linkInsert: string;
+    cancel: string;
+    slashTitle: string;
+    slashEmpty: string;
+    slashCyclesTitle: string;
+    slashCommandsTitle: string;
+    emojiEmpty: string;
+    streamEmpty: string;
+    streamPrivate: string;
+    streamPublic: string;
+    /** What a chip reads while its stream's name is unknown (`~stream`). */
+    streamFallback: string;
+};
+/** Test-only: reset module-scoped remembered direction between cases. */
+declare function __resetLastRememberedDirectionForTests(): void;
+export type RichTextEditorProps = {
+    /** Serialized Lexical state; `null` for empty. Controlled. */
+    value: SerializedEditorState | null;
+    onChange: (state: SerializedEditorState) => void;
+    placeholder?: string;
+    /** Called with the text after `@`; return a page of candidates for the popover. */
+    searchMentions?: (query: string, options: MentionSearchOptions) => Promise<MentionSearchResult>;
+    /**
+     * Fires after a mention is inserted from the typeahead (not for disabled rows).
+     * Hosts use this for analytics (e.g. selecting a "Not in this stream" person).
+     */
+    onMentionSelect?: (candidate: MentionCandidate) => void;
+    /**
+     * Leading `/query` typeahead (cycle triggers). Host filters; return sync or Promise.
+     * Mounts the slash plugin when provided (pass a function that returns `[]` for the empty state).
+     */
+    searchSlashCommands?: (query: string) => SlashCommandCandidate[] | Promise<SlashCommandCandidate[]>;
+    /** Fires when a row of the slash menu is chosen, before the editor inserts it. */
+    onSlashCommandSelect?: (candidate: SlashCommandCandidate) => void;
+    /**
+     * A leading `/` (or `/query`, e.g. pasted) arrived. The editor removes that text and skips the
+     * inline menu, receiving the query so the host can open its own picker with it prefilled. Needs
+     * `searchSlashCommands` (the plugin mounts with it).
+     */
+    onSlashTyped?: (query: string) => void;
+    /**
+     * `:` shortcode typeahead (Slack-style `:smile:`). Host filters; return sync or Promise.
+     * Mounts the emoji plugin when provided.
+     */
+    searchEmojis?: (query: string) => EmojiCandidate[] | Promise<EmojiCandidate[]>;
+    /**
+     * Resolve a completed `:shortcode:` (closing colon typed) to a native glyph or custom emoji.
+     * When set with `searchEmojis`, typing `:thumbsup:` / `:ship-it:` expands without a menu pick.
+     */
+    resolveEmojiShortcode?: (shortcode: string) => EmojiShortcodeResolve | undefined;
+    /**
+     * Called once when an emoji enters the document by a menu pick or a typed complete `:shortcode:`
+     * (see `EmojiUse`). The editor makes no network calls itself; the host decides what to do.
+     */
+    onEmojiUsed?: (use: EmojiUse) => void;
+    /**
+     * `#` stream chip typeahead (Slack-style channel chips). Host filters; return sync or Promise.
+     * Mounts the stream plugin when provided.
+     */
+    searchStreams?: (query: string) => StreamCandidate[] | Promise<StreamCandidate[]>;
+    /** Called when the user presses Enter without Shift (and `sendOnEnter` is not `false`). */
+    onSubmit?: () => void;
+    /** Plain Enter submits when true (default). When false, plain Enter behaves like Shift+Enter (new line/list item) — for mobile, where only the send button submits. */
+    sendOnEnter?: boolean;
+    /** Host-driven `/trigger` insertion; dispatched once per `nonce` through `INSERT_CYCLE_TRIGGER_COMMAND`. */
+    insertCycleTrigger?: CycleTriggerRequest | null;
+    /** Host-driven custom emoji insertion; dispatched once per `nonce` through `INSERT_CUSTOM_EMOJI_COMMAND`. */
+    insertCustomEmoji?: CustomEmojiRequest | null;
+    /** Names (no slash) of plain-text commands whose leading `/name` is painted as a chip. */
+    chipSlashCommands?: readonly string[];
+    /** Why a `/trigger` chip cannot run, or null; a non-null answer adds an error icon with it on hover. */
+    cycleTriggerIssue?: (triggerName: string) => string | null;
+    onCycleTriggerInserted?: (nonce: number) => void;
+    onCustomEmojiInserted?: (nonce: number) => void;
+    /** Host-driven text insertion at the caret (composer `@` / `/` buttons). */
+    insertTextAtCaret?: InsertTextRequest | null;
+    /** Clear `insertTextAtCaret` after apply so a later editor remount (e.g. send) cannot re-insert it. */
+    onInsertTextAtCaret?: (nonce: number) => void;
+    disabled?: boolean;
+    /** Focus the editor, caret at the end, when it mounts. */
+    autoFocus?: boolean;
+    /** Show the formatting toolbar above the editable area. Defaults to `true`. */
+    toolbar?: boolean;
+    /**
+     * When true (default), stamp paragraph/list direction with word-vote detection
+     * (HAC DirectionPlugin). Set false to leave Lexical native / no explicit dir
+     * (Labs `chat_rtl_support` kill switch).
+     */
+    detectContentDirection?: boolean;
+    /** Accessible names and dialog copy; English defaults, override for i18n. */
+    labels?: Partial<RichTextEditorLabels>;
+    /** Opts into the document flavour (headings, block images, no strikethrough or code fences). */
+    documentMode?: DocumentModeOptions;
+    'aria-label': string;
+    className?: string;
+};
+/**
+ * Controlled rich-text editor built on Lexical.
+ *
+ * Registered nodes: `HeadingNode`, `QuoteNode`, `ListNode`, `ListItemNode`,
+ * `LinkNode`, `AutoLinkNode`, `CodeNode`, `MentionNode` (`type: 'mention'`),
+ * `CycleTriggerNode` (`type: 'cycle-trigger'`), `StreamChipNode` (`type: 'stream-chip'`),
+ * `CustomEmojiNode` (`type: 'custom-emoji'`), `DocumentImageNode` (`type: 'about-image'`) — compatible with the
+ * `contracts/chat/adapters/lexical.ts` round-trip contract.
+ */
+declare function RichTextEditor(props: RichTextEditorProps): React.JSX.Element;
+export { RichTextEditor, __resetLastRememberedDirectionForTests };