import type * as React from 'react';
import type { FormValidityHandle } from '../utils/formControl.js';
import type { MentionToken } from '../utils/mentions.js';
import type { PassThroughProps } from '../utils/passThrough.js';
import type { PopperContentProps } from '../utils/popper.js';
import type { PortalProps } from '../utils/portal.js';
import type { PrimitivePropsWithRef } from '../utils/primitive.js';
import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
import type { OptionEntry } from '../utils/useOptionCollection.js';
/** One mentionable entry for the {@link MentionsProps.options} recipe prop, rendered as a `MentionsItem`. */
export interface MentionsOptionData {
    /** Identifier carried on the value-change detail when this entry is inserted. */
    value: string;
    /**
     * Text the filter matches and the default `serialize` writes into the field.
     * @default undefined — falls back to `value`.
     */
    label?: string | undefined;
    /**
     * Trigger character this entry belongs to, so one field addresses several collections.
     * @default undefined — the first configured trigger.
     */
    trigger?: string | undefined;
    /**
     * Excludes this entry from insertion and from pointer or keyboard highlight.
     * @default false
     */
    disabled?: boolean | undefined;
}
/**
 * Narrows Items against the active query — the substring between the trigger
 * character and the caret, never the whole field value. `'manual'` filters
 * nothing; a predicate filters, and a number both filters and ranks (`0`
 * excludes, positive keeps and orders by score descending).
 */
export type MentionsFilter = 'manual' | ((itemText: string, query: string) => boolean | number);
/** What drove a {@link Mentions} value change: a user gesture, or the application. */
export type MentionsValueChangeReason = 'keyboard' | 'pointer' | 'programmatic';
/** The mention just inserted and the range of field text it replaced. */
export interface MentionsInsertedMention {
    /** Trigger character of the token that was replaced. */
    trigger: string;
    /** The chosen Item's `value`, which is not what was written into the text. */
    value: string;
    /** The text `serialize` produced and the field now contains. */
    text: string;
    /** Offset of the replaced trigger character in the previous value. */
    start: number;
    /** Offset just past the replaced query in the previous value. */
    end: number;
}
/** The payload `onValueChange` receives; `mention` is null for an ordinary keystroke. */
export interface MentionsValueChangeDetail {
    /** The field's whole new text, never the inserted mention alone. */
    value: string;
    /** The field's text before this change, or null when there was none. */
    previousValue: string | null;
    /** What drove the change. */
    reason: MentionsValueChangeReason;
    /** The entry just inserted, or null for ordinary typing. */
    mention: MentionsInsertedMention | null;
}
/** The active token `onQueryChange` reports: its trigger, query and offsets. */
export type MentionsQueryChangeDetail = MentionToken;
/** What moved virtual focus: a key, a pointer, or the component itself. */
export type MentionsHighlightReason = 'keyboard' | 'pointer' | 'auto';
/** The payload `onHighlightChange` receives whenever virtual focus moves. */
export interface MentionsHighlightChangeDetail {
    /** Value of the item now highlighted, or null when none is. */
    value: string | null;
    /** Value of the item highlighted before, or null when none was. */
    previousValue: string | null;
    /** What moved the highlight. */
    reason: MentionsHighlightReason;
}
/** What {@link MentionsProps.serialize} is handed for the entry being inserted. */
export interface MentionsSerializeInput {
    /** The chosen Item's identifier, as declared on the part. */
    value: string;
    /** The Item's `textValue`, or the text it rendered. */
    textValue: string;
    /** Trigger character of the token being replaced now. */
    trigger: string;
}
/** Constraint-validation handle for the {@link Mentions} ref, delegating to the real textarea. */
export type MentionsHandle = FormValidityHandle;
/** @internal Shared state distributed from {@link Mentions} to its parts via context. */
export interface MentionsContextValue {
    inputRef: React.RefObject<HTMLTextAreaElement | null>;
    contentRef: React.RefObject<HTMLDivElement | null>;
    /** Id of Content, which the Input's `aria-controls` names while open. */
    contentId: string;
    /** The field's whole text. */
    value: string;
    /** Writes the field's text for an ordinary keystroke, tagged `'keyboard'`. */
    onValueChange: (value: string) => void;
    /** The token under the caret, or null when no mention is being typed. */
    token: MentionToken | null;
    /** Recomputes the token from the field's text and caret, and reopens or closes. */
    detect: (field: HTMLTextAreaElement) => void;
    /** Replaces the active token with the serialized entry and moves the caret past it. */
    insertItem: (value: string, text: string, reason: MentionsValueChangeReason) => void;
    /** Closes the popup and suppresses the current token until it is abandoned. */
    dismiss: () => void;
    open: boolean;
    onOpenChange: (open: boolean) => void;
    activeId: string | null;
    /** CSS `order` for score-ranked Items when `filter` ranks; null leaves order untouched. */
    itemOrder: ReadonlyMap<string, number> | null;
    /** Moves virtual focus and tags the move with a reason. */
    setActiveId: (id: string | null, reason?: MentionsHighlightReason) => void;
    /** Moves the highlight one item forward or back, wrapping when `loop`. */
    moveActive: (direction: 1 | -1) => string | null;
    itemCount: number;
    registerItem: (id: string, entry: OptionEntry) => void;
    unregisterItem: (id: string) => void;
    getItem: (id: string) => OptionEntry | undefined;
    /** Whether an item's text survives the current `filter` and query. */
    matchesFilter: (itemText: string) => boolean;
    /** Trigger character an Item with no `trigger` prop belongs to. */
    defaultTrigger: string;
    autoResize: boolean;
    minRows: number;
    maxRows: number | undefined;
    disabled: boolean;
    readOnly: boolean;
    invalid: boolean;
    loading: boolean;
    required: boolean;
    name: string | undefined;
    form: string | undefined;
}
/**
 * Props for the {@link Mentions} root. Standard attributes ({@link
 * PassThroughProps}) land on the derived Input, the underlying `<textarea>`.
 */
export interface MentionsProps extends PassThroughProps {
    /**
     * The `MentionsInput` and `MentionsPortal` parts; the root renders no DOM itself.
     * @default undefined — the anatomy is derived from `options` instead.
     */
    children?: React.ReactNode | undefined;
    /**
     * The field's full text, for controlled usage; pair it with `onValueChange`.
     * @default undefined — uncontrolled, tracking its own text internally.
     */
    value?: string | undefined;
    /**
     * Initial text of the field, and the text a form reset restores.
     * @default ''
     */
    defaultValue?: string | undefined;
    /**
     * Fires with the field's whole new text, plus the mention just inserted.
     * @default undefined — no-op if omitted.
     */
    onValueChange?: ((detail: MentionsValueChangeDetail) => void) | undefined;
    /**
     * Characters that open a mention at a word boundary; a string is read one character at a time.
     * @default '@'
     */
    triggers?: string | readonly string[] | undefined;
    /**
     * Declares the mentionable collection as data, deriving one Item per entry.
     * @default undefined — nothing is derived; compose the parts yourself.
     */
    options?: MentionsOptionData[] | undefined;
    /**
     * How Items are narrowed against the query between the trigger and the caret.
     * @default 'manual' — the consumer renders only the matching Items.
     */
    filter?: MentionsFilter | undefined;
    /**
     * Builds the text that replaces the typed token when an entry is chosen.
     * @default (item) => `${item.trigger}${item.textValue}`
     */
    serialize?: ((item: MentionsSerializeInput) => string) | undefined;
    /**
     * Whether a single space follows an inserted mention so typing continues cleanly.
     * @default true
     */
    appendSpace?: boolean | undefined;
    /**
     * How many spaces a query may contain before the mention is abandoned.
     * @default 0
     */
    allowedSpaces?: number | undefined;
    /**
     * Whether a trigger opens a mention only at a word boundary, keeping email addresses silent.
     * @default true
     */
    requireWordBoundary?: boolean | undefined;
    /**
     * Fires whenever the token under the caret changes, and null once none is being typed.
     * @default undefined — no-op if omitted.
     */
    onQueryChange?: ((detail: MentionsQueryChangeDetail | null) => void) | undefined;
    /**
     * Whether the popup is open, for controlled usage; pair it with `onOpenChange`.
     * @default undefined — uncontrolled, tracking its own open state internally.
     */
    open?: boolean | undefined;
    /**
     * Initial open state of the popup, for uncontrolled usage.
     * @default false
     */
    defaultOpen?: boolean | undefined;
    /**
     * Fires with the new open state whenever the popup opens or closes.
     * @default undefined — no-op if omitted.
     */
    onOpenChange?: ((open: boolean) => void) | undefined;
    /**
     * Fires once the open or close animation has finished on screen.
     * @default undefined — no-op if omitted.
     */
    onOpenChangeComplete?: ((open: boolean) => void) | undefined;
    /**
     * Keeps the first item highlighted as the list changes, so Enter always commits.
     * @default true — the opposite of Combobox, where the draft text is itself an answer.
     */
    autoHighlight?: boolean | undefined;
    /**
     * Wraps arrow navigation around the ends of the item list.
     * @default true
     */
    loop?: boolean | undefined;
    /**
     * Fires whenever virtual focus moves; read-only, with no controlled counterpart.
     * @default undefined — no-op if omitted.
     */
    onHighlightChange?: ((detail: MentionsHighlightChangeDetail) => void) | undefined;
    /**
     * Marks items as in flight and suppresses the result-count announcement.
     * @default false
     */
    loading?: boolean | undefined;
    /**
     * Grows the field to fit its content instead of showing a scrollbar.
     * @default false
     */
    autoResize?: boolean | undefined;
    /**
     * The field's opening size, and the floor auto-resize will not shrink below.
     * @default 2
     */
    minRows?: number | undefined;
    /**
     * Caps auto-resize growth to this many rows of computed line height.
     * @default undefined — growth is uncapped.
     */
    maxRows?: number | undefined;
    /**
     * Disables the field, so no mention can ever open.
     * @default false
     */
    disabled?: boolean | undefined;
    /**
     * Makes the field read-only, suspending trigger detection while keeping it focusable.
     * @default false
     */
    readOnly?: boolean | undefined;
    /**
     * Marks the field invalid, exposed as `aria-invalid` and `data-invalid`.
     * @default false
     */
    invalid?: boolean | undefined;
    /**
     * Form field name the field's full text is submitted under.
     * @default undefined — the field submits nothing at all.
     */
    name?: string | undefined;
    /**
     * Id of the `<form>` this field submits into, for a field outside its subtree.
     * @default undefined — associates with the nearest ancestor form.
     */
    form?: string | undefined;
    /**
     * Marks the field required: `valueMissing` while its text is empty.
     * @default false
     */
    required?: boolean | undefined;
    /**
     * Formats the polite announcement of the rendered item count while open.
     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
     */
    getResultCountLabel?: ((count: number) => string) | undefined;
    /**
     * Placeholder text forwarded to the derived Input part.
     * @default undefined
     */
    placeholder?: string | undefined;
    /**
     * Customises how an `options`-derived Item renders, given its highlight state.
     * @default undefined — renders `option.label ?? option.value`.
     */
    renderOption?: ((option: MentionsOptionData, state: {
        highlighted: boolean;
    }) => React.ReactNode) | undefined;
    /**
     * Accessible name for the derived Input and for Content.
     * @default undefined — falls back to `placeholder`.
     */
    'aria-label'?: string | undefined;
    /**
     * DOM node the derived Portal renders the overlay into, so it inherits that subtree's theme and stacking context (e.g. a `[data-skdx-theme]` wrapper).
     * @default undefined — `document.body`.
     */
    portalContainer?: Element | DocumentFragment | null | undefined;
}
/** Props for {@link MentionsInput}, the textarea that keeps real DOM focus throughout. */
export interface MentionsInputProps extends Omit<PrimitivePropsWithRef<'textarea'>, 'value' | 'defaultValue'> {
}
/** Props for {@link MentionsPortal}, which teleports the popup out of clipping ancestors. */
export interface MentionsPortalProps extends PortalProps {
    /**
     * Mounts the popup even while closed, so an exit animation has something to play on.
     * @default false
     */
    forceMount?: boolean | undefined;
}
/** Props for {@link MentionsContent}, the floating listbox anchored to the caret. */
export interface MentionsContentProps extends PopperContentProps {
    /**
     * Keeps this popup mounted even while closed, instead of unmounting it.
     * @default false
     */
    forceMount?: boolean | undefined;
    /**
     * Fires on Escape while open; `preventDefault()` keeps the popup open.
     * @default undefined — no-op if omitted.
     */
    onEscapeKeyDown?: ((event: KeyboardEvent) => void) | undefined;
    /**
     * Fires on pointer-down outside the popup and the field.
     * @default undefined — no-op if omitted.
     */
    onPointerDownOutside?: ((event: PointerEvent) => void) | undefined;
    /**
     * Fires when focus moves outside the popup and the field.
     * @default undefined — no-op if omitted.
     */
    onFocusOutside?: ((event: FocusOutsideEvent) => void) | undefined;
    /**
     * Fires before either outside handler above, with the same event object.
     * @default undefined — no-op if omitted.
     */
    onInteractOutside?: ((event: InteractOutsideEvent) => void) | undefined;
}
/** Props for a single {@link MentionsItem}, one mentionable entry inside Content. */
export interface MentionsItemProps extends PrimitivePropsWithRef<'div'> {
    /** Identifier published as `data-value` and carried on the value-change detail. */
    value: string;
    /**
     * Which trigger character this entry belongs to, for a field addressing several collections.
     * @default undefined — the first configured trigger.
     */
    trigger?: string | undefined;
    /**
     * Text the filter matches and the default `serialize` writes into the field.
     * @default undefined — falls back to the entry's rendered text.
     */
    textValue?: string | undefined;
    /**
     * Excludes this entry from insertion and from pointer or keyboard highlight.
     * @default false
     */
    disabled?: boolean | undefined;
}
/** Props for {@link MentionsEmpty}, shown when the active query matches no entry. */
export interface MentionsEmptyProps extends PrimitivePropsWithRef<'div'> {
}