@particle-academy/react-fancy 3.0.1 → 3.1.0

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,69 @@
+# 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. |
+
+## 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.1.0",
   "description": "React UI component library — React port of the fancy-flux Blade component library",
   "repository": {
     "type": "git",