@particle-academy/react-fancy 3.1.0 → 3.2.0

package/docs/ChatDrawer.md

@@ -0,0 +1,75 @@
+# ChatDrawer
+
+A tabbed, collapsible drawer that mounts in `PromptInput`'s `aboveInput` slot so the drawer and composer share one rounded shell. Each tab gets a numbered chip and a content panel; only one panel renders at a time. Slot-driven — you decide what each tab shows.
+
+Added in `3.2.0`.
+
+## Import
+
+```tsx
+import { ChatDrawer, PromptInput } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+const [tab, setTab] = useState("tools");
+const [open, setOpen] = useState(true);
+
+<PromptInput
+  budgetTokens={200_000}
+  placeholder={tab === "deal" ? "Ask about this deal…" : "Type a message…"}
+  onSubmit={send}
+  aboveInput={
+    <ChatDrawer
+      tabs={[
+        { id: "files",   label: "Files" },
+        { id: "tools",   label: "Chat Tools" },
+        { id: "prompts", label: "Chat Prompts" },
+        { id: "deal",    label: "IBM Analytics Platform", number: null },
+      ]}
+      activeTabId={tab}
+      onTabChange={setTab}
+      open={open}
+      onToggle={setOpen}
+    >
+      {tab === "files"   && <FilesPanel />}
+      {tab === "tools"   && <ToolsGrid />}
+      {tab === "prompts" && <PromptsList />}
+      {tab === "deal"    && <DealContext />}
+    </ChatDrawer>
+  }
+/>
+```
+
+## Props
+
+| Prop            | Type                       | Default      | Description                                            |
+| --------------- | -------------------------- | ------------ | ------------------------------------------------------ |
+| `tabs`          | `ChatDrawerTab[]`          | —            | Ordered list of tabs.                                  |
+| `activeTabId`   | `string`                   | —            | Currently selected tab.                                |
+| `onTabChange`   | `(id: string) => void`     | —            | Fires when a chip is clicked.                          |
+| `open`          | `boolean`                  | `true`       | Body visibility.                                       |
+| `onToggle`      | `(open: boolean) => void`  | —            | Fires when the chevron is clicked.                     |
+| `children`      | `ReactNode`                | —            | Body content for the active tab.                       |
+| `minBodyHeight` | `number`                   | `140`        | Min height of the body (px) when open.                 |
+| `className`     | `string`                   | —            | Extra class on the outer container.                    |
+
+### Tab
+
+```ts
+type ChatDrawerTab = {
+  id: string;
+  label: string;
+  /** Override the numbered chip. `null` hides the number entirely
+   *  (handy for context-specific tabs like "IBM Analytics Platform"). */
+  number?: number | null;
+};
+```
+
+By default tabs are numbered by position (1, 2, 3, …). Pass `number: null` to suppress.
+
+## See Also
+
+- [PromptInput](./PromptInput.md) — pairs via the `aboveInput` slot so they share one rounded panel
+- [InputTag](./InputTag.md) — drop into the same composer to add `/` and `@` autocomplete

package/docs/InputTag.md

@@ -0,0 +1,155 @@
+# InputTag
+
+A trigger-driven autocomplete picker that attaches to *any* text surface via an adapter. Type a configured trigger character (`/`, `@`, `#`, `:`, anything) at a word boundary to open a filtered menu; ↑↓ to move, Enter or Tab to insert, Esc to dismiss.
+
+Added in `3.2.0`.
+
+## Import
+
+```tsx
+import {
+  InputTag,
+  textareaAdapter,
+  inputAdapter,
+  contentEditableAdapter,
+  controlledAdapter,
+} from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+import { useRef, useState } from "react";
+import { InputTag, textareaAdapter } from "@particle-academy/react-fancy";
+
+const COMMANDS = [
+  { name: "/explain", hint: "explain the selection" },
+  { name: "/rewrite", hint: "rewrite in a different tone" },
+];
+
+const MENTIONS = [
+  { id: "ada", name: "Ada", kind: "person" },
+  { id: "readme", name: "README.md", kind: "file" },
+];
+
+function ChatInput() {
+  const [text, setText] = useState("");
+  const ref = useRef<HTMLTextAreaElement>(null);
+  const adapter = useMemo(() => textareaAdapter(ref), []);
+
+  return (
+    <>
+      <textarea ref={ref} value={text} onChange={(e) => setText(e.target.value)} />
+      <InputTag
+        adapter={adapter}
+        triggers={{
+          "/": { items: COMMANDS, insert: (c) => `${c.name} ` },
+          "@": { items: MENTIONS, insert: (m) => `@${m.name} ` },
+        }}
+      />
+    </>
+  );
+}
+```
+
+The component renders nothing until a trigger is active. When the trigger fires, a floating menu anchored to the input shows filtered items. Picking inserts the configured replacement and closes the menu.
+
+## Triggers
+
+Each trigger character maps to a config:
+
+```tsx
+{
+  "/": {
+    items: COMMANDS,
+    insert: (item, query) => `${item.name} `,   // replaces "/<query>" with this
+    filter?: (item, query) => boolean,           // default: prefix match against name/id
+    render?: (item, active) => ReactNode,        // default: item.name | item.id
+    keyOf?: (item) => string,                    // default: same as render fallback
+    label?: "Commands",                          // optional header
+  }
+}
+```
+
+`insert` receives the matched item and the current query (text typed after the trigger character).
+
+`filter` defaults to a case-insensitive substring check against `keyOf(item)`. Pass `() => true` to bypass filtering — handy when `items` is being driven by an async source.
+
+`render` lets you customize each row. The second arg is `active` (current keyboard cursor).
+
+## Adapters
+
+`<InputTag>` is surface-agnostic. The component calls into an adapter for read, write, anchor positioning, and key interception. Four built-in adapters cover the DOM cases:
+
+| Adapter                              | Surface                              |
+| ------------------------------------ | ------------------------------------ |
+| `textareaAdapter(ref)`               | `<textarea>`                         |
+| `inputAdapter(ref)`                  | `<input>`                            |
+| `contentEditableAdapter(ref)`        | any `contenteditable` element        |
+| `controlledAdapter({ anchorRef, onReplaceRange })` | hosts that fully own text state |
+
+Non-DOM surfaces (code editors, sheet cell editors, whiteboard sticky notes) ship adapters from their own packages — e.g. `<CodeEditorInputTag>` from `@particle-academy/fancy-code`. For ad-hoc cases, write your own (~30 lines) against the contract:
+
+```ts
+type InputTagAdapter = {
+  subscribe: (fn: (state: { text: string; caretIndex: number }) => void) => () => void;
+  replaceRange: (start: number, end: number, replacement: string) => void;
+  getAnchorRect: () => DOMRect | null;
+  onKey: (handler: (e: KeyboardEvent) => boolean) => () => void;
+};
+```
+
+The DOM adapters use React's native value setter so the consumer's controlled `onChange` fires correctly when the picker writes back — no state-sync gotchas.
+
+## Props
+
+| Prop          | Type                          | Default          | Description                                 |
+| ------------- | ----------------------------- | ---------------- | ------------------------------------------- |
+| `adapter`     | `InputTagAdapter`             | —                | Surface adapter.                            |
+| `triggers`    | `Record<string, …>`           | —                | Per-trigger-char config (see above).        |
+| `maxItems`    | `number`                      | `8`              | Max rows shown.                             |
+| `placement`   | `"bottom-left"` \| `"bottom-right"` \| `"top-left"` \| `"top-right"` | `"bottom-left"` | Anchor position relative to surface. |
+| `className`   | `string`                      | —                | Class on the popover container.             |
+| `style`       | `CSSProperties`               | —                | Inline style on the popover container.      |
+| `onPick`      | `(info) => void`              | —                | Fires after each insertion.                 |
+
+## Trigger Detection
+
+A trigger is active when one of the configured characters appears between the caret and the nearest preceding whitespace (or start of text), with no other non-trigger / non-whitespace breaks. The "query" is everything between the trigger character and the caret.
+
+Examples:
+
+- `hello /expl|`           → query is `expl`, opens `/` picker
+- `email me at user@gma|`  → query is `gma`, opens `@` picker
+- `path/to/fi|`            → no trigger (caret is in a word that's not preceded by whitespace)
+- `#urgent #wo|nt`         → opens `#` picker with query `wo`
+
+## Custom Surfaces
+
+For non-DOM surfaces, write an adapter. Minimal `controlledAdapter` example for a host that owns text state:
+
+```tsx
+const anchorRef = useRef<HTMLDivElement>(null);
+
+const adapter = useMemo(
+  () =>
+    controlledAdapter({
+      anchorRef,
+      onReplaceRange: (start, end, replacement) => {
+        setText((cur) => cur.slice(0, start) + replacement + cur.slice(end));
+        setCaret(start + replacement.length);
+      },
+    }),
+  [],
+);
+
+// host pushes updates whenever text/caret changes
+useEffect(() => {
+  adapter.notify({ text, caretIndex: caret });
+}, [text, caret]);
+```
+
+## See Also
+
+- [PromptInput](./PromptInput.md) — uses similar trigger logic internally; use `InputTag` when you want the picker without the rest of the composer
+- [ChatDrawer](./ChatDrawer.md) — composes with `PromptInput`'s `aboveInput` slot for tabbed-tools drawer UX

package/docs/PromptInput.md

@@ -50,6 +50,7 @@ import { PromptInput } from "@particle-academy/react-fancy";
 | charsPerToken | `number` | `4` | Rough estimator for the token meter. |
 | mentionColor | `Record<string, string>` | sensible defaults | Override the chip colour per mention kind. |
 | maxHeight | `number` | `280` | Max textarea height in pixels. |
+| aboveInput | `ReactNode` | — | Rendered inside the rounded shell, above the textarea. Use this for a drawer of tools/files/prompts/etc. so the drawer and composer share one visual panel — see [ChatDrawer](./ChatDrawer.md). Added in `3.2.0`. |
 
 ## Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "React UI component library — React port of the fancy-flux Blade component library",
   "repository": {
     "type": "git",