@particle-academy/react-fancy 5.64.1 → 5.65.0

package/CHANGELOG.md

@@ -11,6 +11,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.65.0] - 2026-10-27
+
+### Added
+
+- **`PromptInput`: controlled state and draft save/restore** (genie#1261).
+  Before this, nothing outside the composer could read or set what had been
+  typed, so a host could not keep a draft across a restart. That also broke the
+  component contract, which requires controlled state.
+  - `value` / `defaultValue` / `onChange(text)` cover the simple case. With
+    paste pills on, `value` carries a `pasteMarker(id)` for each pill, the same
+    as `Composer`'s `value`.
+  - `draft` / `defaultDraft` / `onDraftChange(draft)` cover the whole draft.
+    A `PromptDraft` is plain JSON:
+    `{ v: 1, text, pills: [{ kind: "text", id, text } | { kind: "image", id, label, file }], attachments: [{ id, name, type, bytes, ref? }] }`.
+  - A `ref` now resolves to a `PromptInputHandle`: `getDraft()`,
+    `setDraft(draft, { focus?: false })` and `focus()`.
+  - **Restoring a draft never moves focus or a caret** (genie#1235). This holds
+    when nothing is focused and when another input is. Pass `{ focus: true }`
+    to focus the composer.
+  - `setDraft` does **not** call `onChange` / `onDraftChange`. The host set the
+    draft and already has it, and firing the callbacks would make a restore
+    look like typing (a dirty flag, a typing indicator, a save over what was
+    just loaded). This is the same as assigning `input.value` in the DOM.
+  - The file bytes are not in the draft. `persistAttachment(file, entry)`
+    stores each attached or pasted file wherever the host chooses and returns
+    a handle, which becomes the entry's `ref`. It can be sync or async.
+    `restoreAttachment(entry)` gets the File back on restore. To keep the bytes
+    inline, use the new `promptFileToDataUrl` / `promptDataUrlToFile` helpers.
+    A restored entry with no File still shows its chip or pill, and reaches
+    `onSubmit` with its `ref` and `file: undefined`.
+  - `PromptAttachment` gains an optional `ref`. Each attachment chip gets a
+    stable `data-react-fancy-prompt-input-attachment="<id>"` handle.
+  - A draft whose `v` is unknown is refused with a console warning rather than
+    guessed at. Pills restored into a composer with no pills turned on are
+    expanded in place, and image pills become attachments, so no raw markers
+    show.
+
+  **What you must do: nothing, unless you opt in.** Existing usage renders the
+  same markup as 5.64.1, checked against a snapshot written by 5.64.1 itself.
+  Two edge cases. `ref`, `onChange` and `defaultValue` used to fall through
+  `...rest` to the root `<div>`, but none of them was in the props type, so a
+  TypeScript consumer could not have passed them. If you passed one anyway
+  (an untyped `onChange` that listened for DOM change events bubbling to the
+  root), it now means the new prop.
+
 ## [5.64.1] - 2026-10-27
 
 ### Fixed

package/dist/{chunk-Z6LYBL5L.cjs → chunk-C463C4MM.cjs}

@@ -8,6 +8,95 @@ var chunkZU5Q77OT_cjs = require('./chunk-ZU5Q77OT.cjs');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
+// src/components/PromptInput/prompt-draft.ts
+var EMPTY_DRAFT = { v: 1, text: "", pills: [], attachments: [] };
+function readFile(raw, id) {
+  if (!raw || typeof raw !== "object") return null;
+  const f = raw;
+  const fileId = id ?? f.id;
+  if (typeof fileId !== "string" || typeof f.name !== "string") return null;
+  const out = {
+    id: fileId,
+    name: f.name,
+    type: typeof f.type === "string" ? f.type : "",
+    bytes: typeof f.bytes === "number" && Number.isFinite(f.bytes) ? f.bytes : 0
+  };
+  if (typeof f.ref === "string") out.ref = f.ref;
+  return out;
+}
+function readPill(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const p = raw;
+  if (typeof p.id !== "string") return null;
+  if (p.kind === "text" && typeof p.text === "string") {
+    return { kind: "text", id: p.id, text: p.text };
+  }
+  if (p.kind === "image" && typeof p.label === "string") {
+    const file = readFile(p.file, p.id);
+    return file ? { kind: "image", id: p.id, label: p.label, file } : null;
+  }
+  return null;
+}
+function readPromptDraft(raw, inline) {
+  if (!raw || typeof raw !== "object" || raw.v !== 1) return null;
+  const d = raw;
+  let text = typeof d.text === "string" ? d.text : "";
+  let pills = (Array.isArray(d.pills) ? d.pills : []).map(readPill).filter((p) => p !== null);
+  let attachments = (Array.isArray(d.attachments) ? d.attachments : []).map((a) => readFile(a)).filter((a) => a !== null);
+  const marked = new Set(chunkQNQNGARW_cjs.markedIds(text));
+  pills = pills.filter((p) => marked.has(p.id));
+  if (!inline && pills.length > 0) {
+    const texts = pills.flatMap((p) => p.kind === "text" ? [{ id: p.id, text: p.text }] : []);
+    const images = pills.flatMap((p) => p.kind === "image" ? [p] : []);
+    text = chunkQNQNGARW_cjs.expandMarkers(
+      text,
+      texts,
+      images.map((p) => ({ id: p.id, label: p.label }))
+    );
+    attachments = [...attachments, ...images.map((p) => p.file)];
+    pills = [];
+  }
+  return { v: 1, text, pills, attachments };
+}
+function clonePromptDraft(draft) {
+  return JSON.parse(JSON.stringify(draft));
+}
+function promptDraftFiles(draft) {
+  return [
+    ...draft.attachments,
+    ...draft.pills.flatMap((p) => p.kind === "image" ? [p.file] : [])
+  ];
+}
+function promptFileToDataUrl(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(file);
+  });
+}
+function promptDataUrlToFile(dataUrl, name, type) {
+  if (!dataUrl.startsWith("data:")) return void 0;
+  const comma = dataUrl.indexOf(",");
+  if (comma < 0) return void 0;
+  const meta = dataUrl.slice(5, comma);
+  const body = dataUrl.slice(comma + 1);
+  const mime = type || meta.split(";")[0] || "application/octet-stream";
+  try {
+    let bytes;
+    if (meta.endsWith(";base64")) {
+      const bin = atob(body);
+      bytes = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    } else {
+      bytes = new TextEncoder().encode(decodeURIComponent(body));
+    }
+    return new File([bytes], name, { type: mime });
+  } catch {
+    return void 0;
+  }
+}
+
 // src/utils/platform.ts
 var APPLE_UA_DATA_PLATFORMS = /* @__PURE__ */ new Set(["macos", "ios", "ipados"]);
 var APPLE_FREE_TEXT = /\b(mac|macintosh|iphone|ipad|ipod|darwin)/i;
@@ -34,7 +123,15 @@ var DEFAULT_MENTION_COLOR = {
   file: "#10b981",
   person: "#3b82f6"
 };
-function PromptInput({
+var PromptInput = react.forwardRef(function PromptInput2({
+  value: controlledValue,
+  defaultValue,
+  onChange,
+  draft: controlledDraft,
+  defaultDraft,
+  onDraftChange,
+  persistAttachment,
+  restoreAttachment,
   budgetTokens,
   commands = [],
   mentions = [],
@@ -60,9 +157,146 @@ function PromptInput({
   meterShowAt = 0.75,
   meterWarnAt = 0.9,
   ...rest
-}) {
-  const [text, setText] = react.useState("");
+}, ref) {
   const inline = pasteThreshold !== void 0 || pasteImages;
+  const draftControlled = controlledDraft !== void 0;
+  const [innerDraft, setInnerDraft] = react.useState(
+    () => defaultDraft && readPromptDraft(defaultDraft, inline) || {
+      ...EMPTY_DRAFT,
+      text: defaultValue ?? ""
+    }
+  );
+  const baseDraft = draftControlled ? controlledDraft : innerDraft;
+  const model = !draftControlled && controlledValue !== void 0 && controlledValue !== baseDraft.text ? { ...baseDraft, text: controlledValue } : baseDraft;
+  const modelRef = react.useRef(model);
+  modelRef.current = model;
+  const text = model.text;
+  const onChangeRef = react.useRef(onChange);
+  onChangeRef.current = onChange;
+  const onDraftChangeRef = react.useRef(onDraftChange);
+  onDraftChangeRef.current = onDraftChange;
+  const persistRef = react.useRef(persistAttachment);
+  persistRef.current = persistAttachment;
+  const commit = react.useCallback(
+    (update, notify = true) => {
+      const prev = modelRef.current;
+      const next = update(prev);
+      if (next === prev) return;
+      modelRef.current = next;
+      setInnerDraft(next);
+      if (!notify) return;
+      if (next.text !== prev.text) onChangeRef.current?.(next.text);
+      onDraftChangeRef.current?.(next);
+    },
+    []
+  );
+  const filesRef = react.useRef(/* @__PURE__ */ new Map());
+  const placeholdersRef = react.useRef(/* @__PURE__ */ new Map());
+  const requestedRef = react.useRef(/* @__PURE__ */ new Set());
+  const [filesVersion, bumpFiles] = react.useReducer((n) => n + 1, 0);
+  const setFileRef = react.useCallback(
+    (id, fileRef2) => commit((m) => {
+      const withRef = (f) => f.id === id ? { ...f, ref: fileRef2 } : f;
+      if (!promptDraftFiles(m).some((f) => f.id === id)) return m;
+      return {
+        ...m,
+        attachments: m.attachments.map(withRef),
+        pills: m.pills.map((p) => p.kind === "image" ? { ...p, file: withRef(p.file) } : p)
+      };
+    }),
+    [commit]
+  );
+  const persist = react.useCallback(
+    (file, entry) => {
+      const store = persistRef.current;
+      if (!store) return void 0;
+      let out;
+      try {
+        out = store(file, entry);
+      } catch (error) {
+        console.error("PromptInput: persistAttachment threw", error);
+        return void 0;
+      }
+      if (typeof out === "string") return out;
+      if (out && typeof out.then === "function") {
+        out.then(
+          (fileRef2) => {
+            if (typeof fileRef2 === "string") setFileRef(entry.id, fileRef2);
+          },
+          (error) => console.error("PromptInput: persistAttachment rejected", error)
+        );
+      }
+      return void 0;
+    },
+    [setFileRef]
+  );
+  const fileMeta = (id, file) => ({
+    id,
+    name: file.name,
+    type: file.type,
+    bytes: file.size
+  });
+  const fileFor = react.useCallback((entry) => {
+    const real = filesRef.current.get(entry.id);
+    if (real) return real;
+    let stand = placeholdersRef.current.get(entry.id);
+    if (!stand) {
+      stand = new File([], entry.name, { type: entry.type });
+      placeholdersRef.current.set(entry.id, stand);
+    }
+    return stand;
+  }, []);
+  const heldPastes = react.useMemo(
+    () => model.pills.flatMap((p) => p.kind === "text" ? [{ id: p.id, text: p.text }] : []),
+    [model.pills]
+  );
+  const heldImages = react.useMemo(
+    () => model.pills.flatMap(
+      (p) => p.kind === "image" ? [{ id: p.id, label: p.label, file: fileFor(p.file) }] : []
+    ),
+    // filesVersion: a restored File arrived, so the stand-in can be swapped out.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [model.pills, fileFor, filesVersion]
+  );
+  const onHeldPastesChange = react.useCallback(
+    (next) => commit((m) => {
+      const current = m.pills.filter((p) => p.kind === "text");
+      if (current.length === next.length && current.every((p, i) => p.id === next[i].id && p.kind === "text" && p.text === next[i].text)) {
+        return m;
+      }
+      return {
+        ...m,
+        pills: [
+          ...next.map((p) => ({ kind: "text", id: p.id, text: p.text })),
+          ...m.pills.filter((p) => p.kind === "image")
+        ]
+      };
+    }),
+    [commit]
+  );
+  const onHeldImagesChange = react.useCallback(
+    (next) => commit((m) => {
+      const before = new Map(
+        m.pills.flatMap((p) => p.kind === "image" ? [[p.id, p]] : [])
+      );
+      if (before.size === next.length && next.every((i) => before.has(i.id))) return m;
+      const images = next.map((image) => {
+        const known = before.get(image.id);
+        if (known && known.kind === "image") return known;
+        filesRef.current.set(image.id, image.file);
+        const entry = fileMeta(image.id, image.file);
+        const fileRef2 = persist(image.file, entry);
+        return {
+          kind: "image",
+          id: image.id,
+          label: image.label,
+          file: fileRef2 === void 0 ? entry : { ...entry, ref: fileRef2 }
+        };
+      });
+      return { ...m, pills: [...m.pills.filter((p) => p.kind === "text"), ...images] };
+    }),
+    [commit, persist]
+  );
   const editorRef = react.useRef(null);
   const paste = chunkQNQNGARW_cjs.useInlinePaste({
     pasteThreshold,
@@ -71,9 +305,55 @@ function PromptInput({
     renderPastePreview,
     classNames: pasteClassNames,
     disabled: false,
+    heldPastes,
+    onHeldPastesChange,
+    heldImages,
+    onHeldImagesChange,
     editorRef
   });
-  const [attachments, setAttachments] = react.useState([]);
+  const attachments = react.useMemo(
+    () => model.attachments.map((a) => ({
+      id: a.id,
+      name: a.name,
+      bytes: a.bytes,
+      file: filesRef.current.get(a.id),
+      type: a.type,
+      ...a.ref !== void 0 ? { ref: a.ref } : {}
+    })),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [model.attachments, filesVersion]
+  );
+  const restoreRef = react.useRef(restoreAttachment);
+  restoreRef.current = restoreAttachment;
+  react.useEffect(() => {
+    const restore = restoreRef.current;
+    if (!restore) return;
+    for (const entry of promptDraftFiles(model)) {
+      if (filesRef.current.has(entry.id) || requestedRef.current.has(entry.id)) continue;
+      requestedRef.current.add(entry.id);
+      const accept = (file) => {
+        if (!(file instanceof Blob)) return;
+        filesRef.current.set(entry.id, file);
+        bumpFiles();
+      };
+      let out;
+      try {
+        out = restore(entry);
+      } catch (error) {
+        console.error("PromptInput: restoreAttachment threw", error);
+        continue;
+      }
+      if (out && typeof out.then === "function") {
+        out.then(
+          accept,
+          (error) => console.error("PromptInput: restoreAttachment rejected", error)
+        );
+      } else {
+        accept(out);
+      }
+    }
+  }, [model]);
+  const setText = (next) => commit((m) => m.text === next ? m : { ...m, text: next });
   const [picker, setPicker] = react.useState(null);
   const taRef = react.useRef(null);
   const fileRef = react.useRef(null);
@@ -162,22 +442,68 @@ function PromptInput({
   const submit = () => {
     if (!text.trim() && attachments.length === 0) return;
     if (inline) {
-      const pastedImages = paste.imagesIn(text).map((image) => ({
-        id: image.id,
-        name: image.file.name,
-        bytes: image.file.size,
-        file: image.file,
-        type: image.file.type
-      }));
+      const pastedImages = paste.imagesIn(text).map((image) => {
+        const entry = model.pills.find((p) => p.id === image.id);
+        const meta = entry?.kind === "image" ? entry.file : fileMeta(image.id, image.file);
+        return {
+          id: image.id,
+          name: meta.name,
+          bytes: meta.bytes,
+          file: filesRef.current.get(image.id),
+          type: meta.type,
+          ...meta.ref !== void 0 ? { ref: meta.ref } : {}
+        };
+      });
       onSubmit(paste.expand(text), [...attachments, ...pastedImages]);
-      paste.clear();
     } else {
       onSubmit(text, attachments);
     }
-    setText("");
-    setAttachments([]);
+    commit(() => EMPTY_DRAFT);
+    filesRef.current.clear();
+    placeholdersRef.current.clear();
+    requestedRef.current.clear();
     setPicker(null);
   };
+  const pendingFocus = react.useRef(false);
+  const focusInput = react.useCallback(() => {
+    if (inline) {
+      editorRef.current?.focus();
+      return;
+    }
+    const ta = taRef.current;
+    if (!ta) return;
+    ta.focus();
+    ta.setSelectionRange(ta.value.length, ta.value.length);
+  }, [inline]);
+  react.useLayoutEffect(() => {
+    if (!pendingFocus.current) return;
+    pendingFocus.current = false;
+    focusInput();
+  });
+  react.useImperativeHandle(
+    ref,
+    () => ({
+      getDraft: () => clonePromptDraft(modelRef.current),
+      setDraft(next, options) {
+        const read = readPromptDraft(next, inline);
+        if (!read) {
+          console.warn(
+            "PromptInput: setDraft ignored a draft it does not recognise (expected { v: 1, ... }).",
+            next
+          );
+          return;
+        }
+        for (const entry of promptDraftFiles(read)) {
+          if (!filesRef.current.has(entry.id)) requestedRef.current.delete(entry.id);
+        }
+        setPicker(null);
+        commit(() => read, false);
+        if (options?.focus) pendingFocus.current = true;
+      },
+      focus: focusInput
+    }),
+    [inline, commit, focusInput]
+  );
   const onKeyDown = (e) => {
     if (picker) {
       if (e.key === "ArrowDown") {
@@ -211,16 +537,14 @@ function PromptInput({
   const attach = (list) => {
     const files = Array.from(list ?? []);
     if (files.length === 0) return;
-    setAttachments((cur) => [
-      ...cur,
-      ...files.map((f) => ({
-        id: crypto.randomUUID(),
-        name: f.name,
-        bytes: f.size,
-        file: f,
-        type: f.type
-      }))
-    ]);
+    const added = files.map((f) => {
+      const id = crypto.randomUUID();
+      filesRef.current.set(id, f);
+      const entry = fileMeta(id, f);
+      const fileRef2 = persist(f, entry);
+      return fileRef2 === void 0 ? entry : { ...entry, ref: fileRef2 };
+    });
+    commit((m) => ({ ...m, attachments: [...m.attachments, ...added] }));
   };
   const onDrop = (e) => {
     e.preventDefault();
@@ -256,6 +580,7 @@ function PromptInput({
         attachments.length > 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex flex-wrap gap-1.5 border-b border-zinc-200 px-3 py-2 dark:border-zinc-800", children: attachments.map((a) => /* @__PURE__ */ jsxRuntime.jsxs(
           "span",
           {
+            "data-react-fancy-prompt-input-attachment": a.id,
             className: "inline-flex items-center gap-1.5 rounded-md bg-[color:var(--fancy-surface-muted,var(--color-zinc-100))] px-2 py-0.5 text-[11px] dark:bg-[color:var(--fancy-surface-muted-dark,var(--color-zinc-800))]",
             children: [
               /* @__PURE__ */ jsxRuntime.jsx(chunkMXWR3T3N_cjs.Icon, { name: "paperclip", size: "xs", className: "text-zinc-400" }),
@@ -264,7 +589,10 @@ function PromptInput({
               /* @__PURE__ */ jsxRuntime.jsx(
                 "button",
                 {
-                  onClick: () => setAttachments((cur) => cur.filter((x) => x.id !== a.id)),
+                  onClick: () => commit((m) => ({
+                    ...m,
+                    attachments: m.attachments.filter((x) => x.id !== a.id)
+                  })),
                   className: "opacity-50 hover:opacity-100",
                   "aria-label": "Remove attachment",
                   children: "\xD7"
@@ -306,7 +634,7 @@ function PromptInput({
               chunkQNQNGARW_cjs.PastedFilesInput,
               {
                 name: pasteFilesName,
-                files: paste.imagesIn(text).map((i) => i.file)
+                files: paste.imagesIn(text).flatMap((i) => filesRef.current.has(i.id) ? [i.file] : [])
               }
             )
           ] }) : /* @__PURE__ */ jsxRuntime.jsx(
@@ -471,7 +799,7 @@ function PromptInput({
       ]
     }
   );
-}
+});
 function fmtTokens(n) {
   if (n < 1e3) return `${n}`;
   return `${(n / 1e3).toFixed(1)}k`;
@@ -486,5 +814,7 @@ exports.PromptInput = PromptInput;
 exports.browserPlatformHints = browserPlatformHints;
 exports.detectPlatform = detectPlatform;
 exports.modifierKeyLabel = modifierKeyLabel;
-//# sourceMappingURL=chunk-Z6LYBL5L.cjs.map
-//# sourceMappingURL=chunk-Z6LYBL5L.cjs.map
+exports.promptDataUrlToFile = promptDataUrlToFile;
+exports.promptFileToDataUrl = promptFileToDataUrl;
+//# sourceMappingURL=chunk-C463C4MM.cjs.map
+//# sourceMappingURL=chunk-C463C4MM.cjs.map