@bysages/react 0.2.1 → 0.2.3

package/dist/index-Uefyw7Im.d.mts

@@ -0,0 +1,108 @@
+import { HTMLAttributes } from "react";
+//#region src/components/mentions/use-mentions.d.ts
+interface UseMentionsOptions {
+  /** The candidates offered once the trigger character is typed. */
+  items: MentionEntry[];
+  /** The character that summons the candidates. */
+  trigger?: string;
+}
+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;
+}
+/** 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>>;
+  insert: (entry: MentionEntry) => void;
+  close: () => void;
+  onInput: () => void;
+  onKeydown: (event: MentionKeyEvent) => boolean;
+};
+//#endregion
+//#region src/components/mentions/index.d.ts
+interface MentionEntry {
+  label: string;
+  value: string;
+}
+interface MentionsVesselProps {
+  /** 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?: HTMLTextAreaElement | null;
+  /** 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 MentionsVessel({ size, open, matches, active, anchor, onInsert, onActiveChange, onOpenChange }: MentionsVesselProps): import("react").JSX.Element;
+/**
+ * @-mentions: a plain textarea that, when the text before the caret ends
+ * with the trigger character followed by a token, offers the matching
+ * candidates in a small anchored vessel; choosing one replaces the token
+ * with `trigger + label` and hands the whole text back through
+ * `onValueChange`. Arrows move, Enter inserts, Escape dismisses.
+ *
+ * The field is the shared `Field.Textarea` — field wiring (label ids,
+ * the invalid state, autoresize) rides on it for free — and the vessel
+ * anchors to the field as a whole (popover machinery), not to the caret
+ * coordinates; caret-precise positioning would need a second
+ * positioning system for no practical gain at typical field sizes.
+ * Composers that keep their own field anatomy (the AI prompt input)
+ * skip this shell and wire `useMentions` plus `MentionsVessel`
+ * themselves.
+ */
+interface MentionsProps extends HTMLAttributes<HTMLDivElement> {
+  /** The candidates offered once the 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;
+  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;
+}
+declare function Mentions({ items, value, trigger, placeholder, autoresize, invalid, size, onValueChange, children, ...rest }: MentionsProps): import("react").JSX.Element;
+//#endregion
+export { MentionsVesselProps as a, useMentions as c, MentionsVessel as i, Mentions as n, UseMentionsHandlers as o, MentionsProps as r, UseMentionsOptions as s, MentionEntry as t };