@particle-academy/react-fancy 5.33.0 → 5.35.0

package/dist/index-DXUAAZzE.d.ts

@@ -0,0 +1,157 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Which modifier key the user actually has.
+ *
+ * This exists because a keyboard hint is a CLAIM about the reader's hardware.
+ * `⌘ + Enter to send` on Windows or Linux names a key that is not on the
+ * keyboard, and a reader who cannot act on a hint learns to ignore hints — so
+ * the cost is not one wrong glyph, it is the credibility of every hint beside
+ * it. (Reported from a real Electron app running on Linux, where the glyph had
+ * no font behind it either and rendered as tofu.)
+ *
+ * Two deliberate choices:
+ *
+ * 1. **The platform is an ARGUMENT, never a global read.** `detectPlatform`
+ *    takes the hints; `modifierKeyLabel` takes the verdict. Both branches are
+ *    therefore reachable from one machine, which is the only way a test can
+ *    cover the platform you are not sitting at. A function that reads
+ *    `navigator` internally can only ever be tested on the developer's own OS.
+ * 2. **`generic` is the fallback, and that is not arbitrary.** Every Fancy
+ *    surface that submits on a modifier accepts `metaKey || ctrlKey`, so
+ *    `Ctrl` is a TRUE label on an Apple keyboard while `⌘` is a FALSE one
+ *    everywhere else. The honest default is the one that is pressable on all
+ *    of them.
+ */
+type FancyPlatform = "apple" | "generic";
+/**
+ * The parts of `navigator` the detection reads — nothing more, so a caller can
+ * hand it a literal (a test, an Electron main process forwarding `process.platform`,
+ * a server with a stored preference).
+ */
+interface PlatformHints {
+    /** `navigator.userAgentData` — the modern, non-spoofed answer where it exists. */
+    userAgentData?: {
+        platform?: string;
+    } | null;
+    /** `navigator.platform` — deprecated, still the most reliable legacy signal. */
+    platform?: string | null;
+    /** `navigator.userAgent` — last resort. */
+    userAgent?: string | null;
+}
+/** Resolve a platform from navigator-shaped hints. Unknown or absent ⇒ `generic`. */
+declare function detectPlatform(hints?: PlatformHints | null): FancyPlatform;
+/**
+ * The modifier key to NAME for a platform.
+ *
+ * `⌘` is emitted for `apple` and nothing else. A test enumerates the platform
+ * values and counts that no other one can produce it, because a hint that names
+ * the wrong key is worse than no hint.
+ */
+declare function modifierKeyLabel(platform: FancyPlatform): "⌘" | "Ctrl";
+/** SSR-safe read of the live browser hints. `null` off a browser. */
+declare function browserPlatformHints(): PlatformHints | null;
+
+/**
+ * PromptInput — the chat composer every AI app rebuilds. Auto-growing
+ * multi-line input with:
+ *
+ *   • slash-command picker (`/` triggers a filtered command palette,
+ *     ↑/↓ navigate, Enter inserts)
+ *   • mention picker (`@` triggers, filtered against `mentions`)
+ *   • drop-to-attach (drag files anywhere on the surface), paste-to-attach
+ *     (a pasted screenshot becomes an attachment) + chip bar
+ *   • submit on ⌘/Ctrl+Enter (plain Enter inserts a newline)
+ *   • live token-budget meter (green → amber → red as headroom drops)
+ *
+ * Wire it up:
+ *
+ *   <PromptInput
+ *     budgetTokens={32000}
+ *     commands={[{ name: "/rewrite", hint: "rewrite the selection" }]}
+ *     mentions={[{ id: "ada", name: "Ada", kind: "person" }]}
+ *     onSubmit={(text, attachments) => sendToAgent(text, attachments)}
+ *   />
+ */
+type PromptCmd = {
+    name: string;
+    hint: string;
+};
+type PromptMention = {
+    id: string;
+    name: string;
+    kind: "agent" | "file" | "person" | string;
+};
+type PromptAttachment = {
+    id: string;
+    name: string;
+    bytes: number;
+    /**
+     * The file the user actually attached.
+     *
+     * Optional because an attachment restored from a server has no File — but for
+     * anything the user dropped or picked it is always present. Without it a host
+     * can render a chip and nothing else: no POST, no FormData, no send-to-model.
+     */
+    file?: File;
+    /** MIME type. Hosts branch on this to decide whether a file can be sent as-is. */
+    type?: string;
+};
+/**
+ * `...rest` reaches the root surface, so a consumer or a bridge can tag the
+ * composer with its own `data-*` handle. The component named every prop it
+ * used and had no rest spread, which means a `data-handle` put on it was
+ * DROPPED — silently, since React discards unknown props and the component
+ * still renders perfectly. That is issue #22 all over again, and the contract
+ * calls it out: "Each interactive element has a stable identity. Agents never
+ * guess DOM."
+ */
+interface PromptInputProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSubmit" | "className"> {
+    /** Extra classes on the root surface. MERGED, never replaced. */
+    className?: string;
+    /** Token budget for the meter. */
+    budgetTokens: number;
+    /** Slash-commands. Names must start with `/`. */
+    commands?: PromptCmd[];
+    /** @-mentions. */
+    mentions?: PromptMention[];
+    /** Show the keyboard hint ("Ctrl + Enter to send", "⌘ + Enter" on a Mac). */
+    showHint?: boolean;
+    /**
+     * Which modifier the hint and the default placeholder NAME. Omit it and the
+     * component reads the platform after mount, which is the right answer for an
+     * ordinary web app.
+     *
+     * Pass it when the host knows better than `navigator` does — an Electron
+     * renderer forwarding `process.platform`, a remote session where the
+     * keyboard is not the one running the browser, or a test that needs the
+     * branch it is not sitting on. The pressed keys are unaffected either way:
+     * submit is `⌘/Ctrl+Enter` on every platform, so this only decides which
+     * true key gets named.
+     */
+    platform?: FancyPlatform;
+    /** Called on ⌘/Ctrl+Enter or send button. */
+    onSubmit: (text: string, attachments: PromptAttachment[]) => void;
+    /**
+     * Placeholder text. Defaults to a hint naming the modifier THIS platform
+     * actually has, so leaving it unset is the better option — a hardcoded
+     * placeholder is the other place a `⌘` ends up in front of a Windows user.
+     */
+    placeholder?: string;
+    /** Rough estimator: chars-per-token. Defaults to 4. */
+    charsPerToken?: number;
+    /** Color → CSS chip mapping for mention kinds. */
+    mentionColor?: Record<string, string>;
+    /** Optional max textarea height in px. Defaults to 280. */
+    maxHeight?: number;
+    /**
+     * Rendered INSIDE the rounded shell, ABOVE the attachments bar and
+     * textarea. Use this slot for a drawer of tools/files/prompts/etc. so
+     * the drawer and composer share one visual panel. See {@link ChatDrawer}.
+     */
+    aboveInput?: ReactNode;
+}
+declare function PromptInput({ budgetTokens, commands, mentions, showHint, platform, onSubmit, placeholder, charsPerToken, mentionColor, maxHeight, aboveInput, className, ...rest }: PromptInputProps): react.JSX.Element;
+
+export { type FancyPlatform as F, type PlatformHints as P, type PromptAttachment as a, type PromptCmd as b, PromptInput as c, type PromptInputProps as d, type PromptMention as e, browserPlatformHints as f, detectPlatform as g, modifierKeyLabel as m };