import * as react from 'react';
import { ReactNode, CSSProperties, RefObject } from 'react';

/**
 * InputTag — attach a `/`-style or `@`-style autocomplete picker to *any*
 * text surface (a `<textarea>`, an `<input>`, a `contenteditable`, a code
 * editor, a sheet cell editor, a whiteboard sticky note…) via an adapter
 * that abstracts the surface's read/write/caret API.
 *
 * The component is "headless" in the sense that it has no input of its
 * own — it floats a small picker menu near the surface and writes back
 * through the adapter when the user picks an item.
 *
 *   <textarea ref={ref} value={text} onChange={...} />
 *   <InputTag
 *     adapter={textareaAdapter(ref)}
 *     triggers={{
 *       "/": { items: commands, insert: (c) => `${c.name} ` },
 *       "@": { items: mentions, insert: (m) => `@${m.name} ` },
 *     }}
 *   />
 *
 * For non-DOM surfaces, write a small adapter that conforms to
 * {@link InputTagAdapter}. Adapters typically run 20–40 lines.
 */
/** What the surface tells the picker on every text/caret change. */
type InputTagAdapterState = {
    text: string;
    caretIndex: number;
};
/**
 * The contract every input surface implements. The picker subscribes to
 * state changes, anchors itself using `getAnchorRect`, intercepts
 * navigation keys via `onKey`, and writes the selected item back through
 * `replaceRange`.
 */
type InputTagAdapter = {
    /** Push current state whenever text or caret changes. Returns an unsubscribe. */
    subscribe: (fn: (state: InputTagAdapterState) => void) => () => void;
    /** Replace text in `[start, end)` with `replacement`. The adapter is
     *  responsible for moving the caret to the end of the inserted text. */
    replaceRange: (start: number, end: number, replacement: string) => void;
    /** Screen-space rect to anchor the picker against. Usually the surface's
     *  bounding rect; for editors that can compute caret-precise coordinates,
     *  return a small rect there instead. */
    getAnchorRect: () => DOMRect | null;
    /** Subscribe to keydown events on the surface. The handler may return
     *  `true` to consume the event (the adapter then calls
     *  `preventDefault` / `stopPropagation`). Returns an unsubscribe. */
    onKey: (handler: (e: KeyboardEvent) => boolean) => () => void;
};
/**
 * Per-trigger configuration. `T` is the item shape — typically a
 * `{ id, name, ... }` object, but any shape works as long as `keyOf` /
 * `insert` know how to handle it.
 */
type InputTagTrigger<T> = {
    /** The pool the picker filters against. */
    items: T[];
    /** Text inserted in place of `<triggerChar><query>`. */
    insert: (item: T, query: string) => string;
    /** Custom filter. Default: case-insensitive prefix match against
     *  `String(keyOf(item))`. Pass `() => true` to disable filtering and
     *  rely on `items` being pre-filtered (e.g. from an async source). */
    filter?: (item: T, query: string) => boolean;
    /** How to render each row. Default renders the result of `keyOf(item)`. */
    render?: (item: T, active: boolean) => ReactNode;
    /** How to derive a stable key + default label for each item. Default
     *  reads `item.name` then `item.id` then `String(item)`. */
    keyOf?: (item: T) => string;
    /** Optional header label shown above the list. */
    label?: string;
};
type InputTagTriggers = Record<string, InputTagTrigger<any>>;
interface InputTagProps {
    adapter: InputTagAdapter;
    triggers: InputTagTriggers;
    /** Max rows shown. Default 8. */
    maxItems?: number;
    /** Where the picker anchors relative to the surface. Default `"bottom-left"`. */
    placement?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
    /** Custom class for the popover container. */
    className?: string;
    /** Inline style for the popover container. */
    style?: CSSProperties;
    /** Fires whenever an item is picked. */
    onPick?: (info: {
        triggerChar: string;
        query: string;
        item: unknown;
    }) => void;
}
declare function InputTag({ adapter, triggers, maxItems, placement, className, style, onPick, }: InputTagProps): react.JSX.Element | null;

/**
 * Adapter for a DOM `<textarea>`. Works whether the consumer manages
 * `value` via React state (controlled) or lets the DOM hold it
 * (uncontrolled) — `replaceRange` uses React's native value setter and
 * dispatches a native `input` event so the upstream onChange fires.
 */
declare function textareaAdapter(ref: RefObject<HTMLTextAreaElement | null>): InputTagAdapter;
/** Adapter for a DOM `<input type="text|search|...">`. */
declare function inputAdapter(ref: RefObject<HTMLInputElement | null>): InputTagAdapter;
/**
 * Adapter for any `contenteditable` element. Operates on the element's
 * `textContent`; rich-text editors with their own internal model should
 * write a custom adapter that talks to that model instead.
 */
declare function contentEditableAdapter(ref: RefObject<HTMLElement | null>): InputTagAdapter;
/**
 * Adapter for hosts that fully control the text state themselves. Use
 * this when you can't (or don't want to) let the DOM be the source of
 * truth — for code editors with internal state, sheet cell editors, or
 * any host that already has `value` + `onChange` and wants to reach the
 * picker programmatically.
 *
 * The host calls `notify({ text, caretIndex })` after every text or
 * caret change. `<InputTag>` calls `onReplaceRange` to write back.
 */
type ControlledAdapterHandle = InputTagAdapter & {
    /** Push the latest text + caret to the picker. */
    notify: (state: {
        text: string;
        caretIndex: number;
    }) => void;
};
declare function controlledAdapter(opts: {
    /** Element used as anchor + key target. Usually the visible input. */
    anchorRef: RefObject<HTMLElement | null>;
    /** Called when the picker writes back an insertion. */
    onReplaceRange: (start: number, end: number, replacement: string) => void;
}): ControlledAdapterHandle;

export { type ControlledAdapterHandle, InputTag, type InputTagAdapter, type InputTagAdapterState, type InputTagProps, type InputTagTrigger, type InputTagTriggers, contentEditableAdapter, controlledAdapter, inputAdapter, textareaAdapter };