@particle-academy/react-fancy 3.0.1 → 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/MagicWand.md

@@ -0,0 +1,65 @@
+# MagicWand
+
+Selection-anchored floating toolbar for text inputs. When the user highlights text in the wrapped `<Textarea>`, a small pill of AI quick-actions floats above the selection. Clicking an action runs a host callback whose return value replaces the highlighted text in-place.
+
+Promoted from the dreaming sandbox on 2026-05-12.
+
+## Import
+
+```tsx
+import { MagicWand, type MagicWandAction } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+const [body, setBody] = useState("…");
+
+const actions: MagicWandAction[] = [
+  {
+    id: "rephrase",
+    label: "Rephrase",
+    hint: "same meaning, different words",
+    run: async (selection) => await ai.rephrase(selection),
+  },
+  {
+    id: "shorten",
+    label: "Shorten",
+    run: async (selection) => await ai.shorten(selection),
+  },
+];
+
+<MagicWand value={body} onValueChange={setBody} actions={actions} />;
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | — | Controlled textarea value. |
+| onValueChange | `(v: string) => void` | — | Fires on every edit. |
+| actions | `MagicWandAction[]` | — | Action list. Each invokes a callback with the selection. |
+| appearance | `"floating" \| "pill"` | `"floating"` | `"pill"` is icon-only and compact. |
+| autoHide | `boolean` | `true` | Hide the wand on click-away or scroll. |
+| rows | `number` | `6` | Textarea rows. |
+| placeholder | `string` | — | Textarea placeholder. |
+| onAction | `(action, selection, replacement) => void` | — | Fires after an action successfully runs. |
+
+## Action shape
+
+```ts
+type MagicWandAction = {
+  id: string;
+  label: string;
+  hint?: string;
+  tag?: string;
+  run: (selection: string, range: { start: number; end: number; text: string }) => Promise<string> | string;
+};
+```
+
+The string `run` returns becomes the replacement for the selected range. The wand patches `value` and emits `onAction`.
+
+## Notes
+
+- The toolbar position is computed by mirroring the textarea into a hidden div and measuring the selected substring's bounding rect — works for typical chat composers; less accurate for textareas that resize while the toolbar is open.
+- In `"pill"` mode each action shows only the first character of its label, useful when toolbar real estate is tight.

package/docs/MoodMeter.md

@@ -0,0 +1,63 @@
+# MoodMeter
+
+A 2D draggable pad that captures a value AND the confidence in that value on the same handle. The halo around the handle shrinks as confidence rises — uncertain readings literally look fuzzier.
+
+Promoted from the dreaming sandbox on 2026-05-12.
+
+## Import
+
+```tsx
+import { MoodMeter } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+const [value, setValue] = useState(60);
+const [confidence, setConfidence] = useState(0.74);
+
+<MoodMeter
+  min={30}
+  max={200}
+  value={value}
+  confidence={confidence}
+  onChange={(v, c) => {
+    setValue(v);
+    setConfidence(c);
+  }}
+  posted={{ value: 60, confidence: 0.74 }}
+  prefix="$"
+  suffix="k"
+/>
+```
+
+## Why
+
+When AIs post a number, humans immediately ask "how sure are you?". Making confidence an explicit sibling of value — and letting the user drag either independently — turns vague "AI suggestion" UX into something you can argue with precisely.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| min | `number` | — | Range minimum. |
+| max | `number` | — | Range maximum. |
+| step | `number` | `(max-min)/100` | Step for value snapping. |
+| value | `number` | — | Current value (controlled). |
+| confidence | `number` | — | Current confidence 0..1 (controlled). |
+| onChange | `(value, confidence) => void` | — | Fires on drag / pointer events. |
+| posted | `{ value, confidence }` | — | Optional agent post — renders as a dashed ghost handle. |
+| width | `number` | `320` | Pad width in pixels. |
+| height | `number` | `220` | Pad height in pixels. |
+| showGrid | `boolean` | `true` | Show the grid + axis labels. |
+| color | `string` | `"#0ea5e9"` | User handle colour. |
+| postedColor | `string` | `"#a855f7"` | Ghost handle colour. |
+| prefix | `string` | `""` | Prefix for the value label (e.g. `"$"`). |
+| suffix | `string` | `""` | Suffix for the value label (e.g. `"k"`, `"%"`). |
+| formatValue | `(v) => string` | — | Override the label formatting. |
+| className | `string` | — | Applied to the pad. |
+
+## Pad Axes
+
+- **x-axis** → value range `[min..max]`
+- **y-axis** → confidence `[0..1]` (top = sure)
+- **halo radius** → scales inversely with confidence (large halo = unsure)

package/docs/PromptInput.md

@@ -0,0 +1,70 @@
+# PromptInput
+
+The chat composer every AI app rebuilds. Auto-growing multi-line input with slash commands, @ mentions, drop-to-attach, keyboard submit, and a live token-budget meter.
+
+Promoted from the dreaming sandbox on 2026-05-12.
+
+## Import
+
+```tsx
+import { PromptInput } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<PromptInput
+  budgetTokens={32000}
+  commands={[
+    { name: "/explain", hint: "explain the selected text" },
+    { name: "/rewrite", hint: "rewrite in a different tone" },
+  ]}
+  mentions={[
+    { id: "planner", name: "Planner", kind: "agent" },
+    { id: "ada", name: "Ada", kind: "person" },
+    { id: "readme", name: "README.md", kind: "file" },
+  ]}
+  onSubmit={(text, attachments) => send(text, attachments)}
+/>
+```
+
+## Features
+
+- Auto-resizes up to `maxHeight`.
+- `/` opens a filtered command palette. ↑/↓ navigate, Enter inserts.
+- `@` opens a mention picker filtered against `mentions`.
+- Drop files anywhere on the input to attach. Chip bar shows attachments.
+- ⌘+Enter (or Ctrl+Enter) submits. Plain Enter inserts a newline.
+- Token-budget meter colours green → amber → red as headroom drops.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| budgetTokens | `number` | — | Token budget for the meter. |
+| commands | `PromptCmd[]` | `[]` | Slash commands. Names must start with `/`. |
+| mentions | `PromptMention[]` | `[]` | `{ id, name, kind }`. `kind` is free-form (`"agent"`, `"file"`, `"person"`, …). |
+| onSubmit | `(text, attachments) => void` | — | Called on ⌘/Ctrl+Enter or send button. |
+| showHint | `boolean` | `true` | Show the "⌘ + Enter to send" hint. |
+| placeholder | `string` | `"Ask anything…"` | Placeholder text. |
+| 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
+
+```ts
+type PromptCmd = { name: string; hint: string };
+type PromptMention = { id: string; name: string; kind: string };
+type PromptAttachment = { id: string; name: string; bytes: number };
+```
+
+## Defaults
+
+| Mention kind | Default colour |
+|--------------|----------------|
+| `"agent"` | violet |
+| `"file"` | emerald |
+| `"person"` | blue |
+| other | zinc |

package/docs/ReasonTag.md

@@ -0,0 +1,63 @@
+# ReasonTag
+
+Wrap any value with a small affordance that reveals the agent's reasoning, sources, and confidence on hover or click. Explainability becomes a primitive instead of an afterthought.
+
+Promoted from the dreaming sandbox on 2026-05-12.
+
+## Import
+
+```tsx
+import { ReasonTag } from "@particle-academy/react-fancy";
+```
+
+## Basic Usage
+
+```tsx
+<ReasonTag
+  value="$1.4M"
+  reason="Projected Q3 ARR after stacking renewals."
+  confidence={0.91}
+  sources={[{ label: "Q2 actuals · CRM export" }]}
+  by="Forecaster"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `ReactNode` | — | The wrapped value (number, label, short phrase). |
+| reason | `string` | — | Free-text rationale shown in the popover. |
+| confidence | `number` | `1` | 0..1 — drives the colour tier (green ≥ 0.85, amber ≥ 0.6, red below). |
+| sources | `ReasonTagSource[]` | `[]` | `{ label, href? }` list rendered in the popover. |
+| by | `string` | — | Optional author / agent name shown in the popover header. |
+| theme | `"dot" \| "underline" \| "chip"` | `"dot"` | Visual treatment for the trigger. |
+| pinned | `boolean` | `false` | When true, the reason is rendered inline as a margin annotation (no popover). |
+| onFollowUp | `() => void` | — | Optional callback for the "ask follow-up" action in the popover. |
+| className | `string` | — | Applied to the trigger element. |
+
+## Confidence Tiers
+
+| Range | Colour | Label |
+|-------|--------|-------|
+| ≥ 0.85 | emerald | high |
+| ≥ 0.6 | amber | medium |
+| < 0.6 | red | low |
+
+Quick visual scan tells you which suggestions deserve a closer look without opening any tooltips.
+
+## Examples
+
+### Three visual styles
+
+```tsx
+<ReasonTag value="42" reason="…" theme="dot" />
+<ReasonTag value="42" reason="…" theme="underline" />
+<ReasonTag value="42" reason="…" theme="chip" />
+```
+
+### Always-visible inline annotation
+
+```tsx
+<ReasonTag value="$60k" reason="Expansion uplift applied at the historical rate." pinned />
+```

package/package.json

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