@particle-academy/react-fancy 5.67.0 → 5.69.0

package/CHANGELOG.md

@@ -11,6 +11,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.69.0] - 2026-10-27
+
+### Fixed
+
+- **`PromptInput`'s `focus()` and `setDraft(draft, { focus: true })` no longer
+  scroll the page** (genie#1290). They called the element's `focus()` with no
+  options, so the browser scrolled every scrollable ancestor, up to the
+  document, to reveal the composer. In Genie's Electron window that scrolled the
+  whole window. Both now pass `{ preventScroll: true }`. To get the old
+  behaviour, pass `{ preventScroll: false }` to `focus()` or `setDraft`. The new
+  `PromptFocusOptions` type is exported. Focus that follows the person's own
+  keypress (choosing from the `/` or `@` picker) is unchanged.
+  `InlinePasteEditorHandle.focus()` now accepts optional `FocusOptions` and
+  passes them through. With no argument it behaves as before.
+- **`ContentRenderer`'s copy status region can no longer stretch the
+  document** (genie#1290, from 5.67.0). The `aria-live` region relied on the
+  host's Tailwind generating `sr-only`, and nothing around it was positioned.
+  Inside an unpositioned scroll container it escaped the scroller's clip and
+  extended the document. When the host's Tailwind never generated `sr-only`,
+  it rendered as visible text. The region now carries the sr-only clip pattern
+  inline. The root is `position: relative` while copy buttons are on, unless
+  the host's `className` already sets a position. Each copy-block wrapper is
+  `position: relative` inline as well. Nothing to do on upgrade.
+
+## [5.68.0] - 2026-10-27
+
+### Added
+
+- **`Editor` forwards `copyButtons`, `clipboardWriter` and `onCopy` to the
+  `ContentRenderer` its view mode renders through.** 5.67.0 turned copy buttons
+  on in view mode but gave a host no way to route those copies (a sandboxed
+  Electron window), observe them, or turn them off from `Editor`. Same types and
+  same defaults as on `ContentRenderer`; with the props absent nothing changes.
+  They have no effect in edit mode. Editor's docs now also document `mode`.
+- **`ContentRenderer streaming="progressive"`: an open block shows as it
+  fills.** `streaming={true}` still hides an open block until it closes. In the
+  new mode:
+  - an open tag of a registered extension whose opening tag is complete renders
+    its component with the body so far (a `markdown` extension gets it as
+    `content` and rendered, sanitised, as `children`);
+  - an open code fence renders as a code block of what has arrived, with **no
+    copy button until it closes** (hidden rather than disabled: half a block is
+    never what a copy means). Finished blocks before it keep theirs;
+  - a partial opening tag (`<result title="Do`), a partial closing tag, a fence
+    marker still arriving and a fence opener line with no newline yet are still
+    held back, so none of it flashes raw. Inside an open fence `<` is code;
+  - it closes the open fence and open tags itself and renders normally, so the
+    body is the one the final render shows once the real closes arrive.
+  - The root carries `data-streaming-mode="progressive"` as well as
+    `data-streaming="true"`.
+
+  It is a value of `streaming` rather than a new prop because it is a way of
+  streaming: a separate flag would add a combination that means nothing.
+  `streaming` is now typed `boolean | "progressive"`. Code that passes a
+  boolean is unaffected; code that READS the prop's type and assumes `boolean`
+  needs to allow the string.
+
+### Changed
+
+- **Docs: `markdown` tags are lifted only at line start and only when closed,
+  and that is now stated as deliberate.** The behaviour is unchanged.
+  Progressive streaming does not relax either rule.
+
 ## [5.67.0] - 2026-10-27
 
 ### Added

package/dist/ContentRenderer.types-RO_l7_6N.d.cts

@@ -0,0 +1,137 @@
+import { ComponentType, ReactNode } from 'react';
+
+/** Props passed to every render-extension component. */
+interface RenderExtensionProps {
+    /**
+     * The inner content of the custom tag (raw string). For an extension with
+     * `markdown: true` in markdown content this is the raw MARKDOWN body, before
+     * conversion. Either way it is untrusted: render `children` rather than
+     * injecting it.
+     */
+    content: string;
+    /**
+     * Parsed attributes from the opening tag. Event handlers (`on*`), `srcdoc`,
+     * and URL attributes with an unsafe scheme are removed (unless the renderer
+     * is `unsafe`).
+     */
+    attributes: Record<string, string>;
+    /**
+     * Only for extensions with `markdown: true`: the body, rendered by the same
+     * pipeline as the rest of the content (sanitised, nested extensions, copy
+     * buttons).
+     */
+    children?: ReactNode;
+}
+/** Registers a custom tag with a React component for rendering. */
+interface RenderExtension {
+    /** Tag name to match, e.g. "questions", "thinking". Case-insensitive. */
+    tag: string;
+    /** React component that renders the matched tag. */
+    component: ComponentType<RenderExtensionProps>;
+    /**
+     * Whether this is a block-level element.
+     * Block extensions are wrapped in a `<div>`, inline in a `<span>`.
+     * @default true
+     */
+    block?: boolean;
+    /**
+     * The tag's body is MARKDOWN. In markdown content, a tag that starts a line
+     * is lifted out of the source before conversion, so the component gets the
+     * raw markdown as `content` and the rendered, sanitised body as `children`.
+     * In HTML content the body is HTML and `children` renders it.
+     * @default false
+     */
+    markdown?: boolean;
+}
+/** A parsed segment — either raw HTML or a matched extension tag. */
+type ContentSegment = {
+    type: "html";
+    content: string;
+} | {
+    type: "extension";
+    tag: string;
+    content: string;
+    attributes: Record<string, string>;
+};
+/** Register a single render extension globally (available to all ContentRenderer and Editor instances). */
+declare function registerExtension(extension: RenderExtension): void;
+/** Register multiple render extensions globally. */
+declare function registerExtensions(extensions: RenderExtension[]): void;
+
+/** What a copy button copies. */
+type ContentCopyKind = "code" | "table";
+/** What is handed to a clipboard writer. */
+interface ContentClipboardPayload {
+    kind: ContentCopyKind;
+    /**
+     * Plain text. For code: exactly the code between the fences, with no
+     * language label and no added trailing newline. For a table: TSV (tab
+     * between cells, newline between rows, no trailing newline).
+     */
+    text: string;
+    /** The block's sanitised HTML (`<pre>…</pre>` or `<table>…</table>`), for rich paste. */
+    html: string;
+}
+/**
+ * Writes one copy to the clipboard. Throwing, rejecting, or returning `false`
+ * means the copy failed; the failure is announced, never swallowed.
+ */
+type ContentClipboardWriter = (payload: ContentClipboardPayload) => void | boolean | Promise<void | boolean>;
+/** Reported through `onCopy` after every copy attempt. */
+interface ContentCopyEvent extends ContentClipboardPayload {
+    /** Position of the button among this renderer's copy buttons, in document order. */
+    index: number;
+    /** Whether the clipboard write succeeded. */
+    ok: boolean;
+}
+interface ContentRendererProps {
+    value: string;
+    format?: "html" | "markdown" | "auto";
+    lineSpacing?: number;
+    className?: string;
+    /** Per-instance render extensions. Merged with any globally-registered extensions. */
+    extensions?: RenderExtension[];
+    /**
+     * Skip HTML sanitization. By default, rendered output is sanitized to remove
+     * `<script>`, `<iframe>`, event handlers, and `javascript:` URIs. Pass
+     * `unsafe` only when the input is fully trusted (e.g. server-rendered
+     * markdown from your own CMS).
+     * @default false
+     */
+    unsafe?: boolean;
+    /**
+     * Copy buttons on code blocks and tables. `false` turns them all off; an
+     * object turns kinds off individually (`{ table: false }`).
+     * @default true
+     */
+    copyButtons?: boolean | {
+        code?: boolean;
+        table?: boolean;
+    };
+    /** Called after every copy attempt, successful or not. */
+    onCopy?: (event: ContentCopyEvent) => void;
+    /**
+     * Host-supplied clipboard writer, for environments where
+     * `navigator.clipboard` is unreliable (e.g. a sandboxed Electron window:
+     * pass one that calls Electron's `clipboard`). The default writes
+     * text/html + text/plain via `ClipboardItem`, falling back to `writeText`.
+     */
+    clipboardWriter?: ContentClipboardWriter;
+    /**
+     * The value is still arriving. Set it back to `false` when the stream ends
+     * and everything renders.
+     *
+     * - `true` holds back an unfinished trailing custom tag (of a registered
+     *   extension) or code fence until it closes, so a partial `<result` or half
+     *   a code block never flashes as raw text.
+     * - `"progressive"` shows an open block as it fills: an open registered tag
+     *   whose opening tag is complete renders its component with the body so
+     *   far, and an open code fence renders as a code block of what has arrived
+     *   (with no copy button until it closes). A partial opening tag
+     *   (`<result title="Do`) is still held back.
+     * @default false
+     */
+    streaming?: boolean | "progressive";
+}
+
+export { type ContentClipboardPayload as C, type RenderExtension as R, type ContentClipboardWriter as a, type ContentCopyEvent as b, type ContentCopyKind as c, type ContentRendererProps as d, type RenderExtensionProps as e, registerExtensions as f, type ContentSegment as g, registerExtension as r };

package/dist/ContentRenderer.types-RO_l7_6N.d.ts

@@ -0,0 +1,137 @@
+import { ComponentType, ReactNode } from 'react';
+
+/** Props passed to every render-extension component. */
+interface RenderExtensionProps {
+    /**
+     * The inner content of the custom tag (raw string). For an extension with
+     * `markdown: true` in markdown content this is the raw MARKDOWN body, before
+     * conversion. Either way it is untrusted: render `children` rather than
+     * injecting it.
+     */
+    content: string;
+    /**
+     * Parsed attributes from the opening tag. Event handlers (`on*`), `srcdoc`,
+     * and URL attributes with an unsafe scheme are removed (unless the renderer
+     * is `unsafe`).
+     */
+    attributes: Record<string, string>;
+    /**
+     * Only for extensions with `markdown: true`: the body, rendered by the same
+     * pipeline as the rest of the content (sanitised, nested extensions, copy
+     * buttons).
+     */
+    children?: ReactNode;
+}
+/** Registers a custom tag with a React component for rendering. */
+interface RenderExtension {
+    /** Tag name to match, e.g. "questions", "thinking". Case-insensitive. */
+    tag: string;
+    /** React component that renders the matched tag. */
+    component: ComponentType<RenderExtensionProps>;
+    /**
+     * Whether this is a block-level element.
+     * Block extensions are wrapped in a `<div>`, inline in a `<span>`.
+     * @default true
+     */
+    block?: boolean;
+    /**
+     * The tag's body is MARKDOWN. In markdown content, a tag that starts a line
+     * is lifted out of the source before conversion, so the component gets the
+     * raw markdown as `content` and the rendered, sanitised body as `children`.
+     * In HTML content the body is HTML and `children` renders it.
+     * @default false
+     */
+    markdown?: boolean;
+}
+/** A parsed segment — either raw HTML or a matched extension tag. */
+type ContentSegment = {
+    type: "html";
+    content: string;
+} | {
+    type: "extension";
+    tag: string;
+    content: string;
+    attributes: Record<string, string>;
+};
+/** Register a single render extension globally (available to all ContentRenderer and Editor instances). */
+declare function registerExtension(extension: RenderExtension): void;
+/** Register multiple render extensions globally. */
+declare function registerExtensions(extensions: RenderExtension[]): void;
+
+/** What a copy button copies. */
+type ContentCopyKind = "code" | "table";
+/** What is handed to a clipboard writer. */
+interface ContentClipboardPayload {
+    kind: ContentCopyKind;
+    /**
+     * Plain text. For code: exactly the code between the fences, with no
+     * language label and no added trailing newline. For a table: TSV (tab
+     * between cells, newline between rows, no trailing newline).
+     */
+    text: string;
+    /** The block's sanitised HTML (`<pre>…</pre>` or `<table>…</table>`), for rich paste. */
+    html: string;
+}
+/**
+ * Writes one copy to the clipboard. Throwing, rejecting, or returning `false`
+ * means the copy failed; the failure is announced, never swallowed.
+ */
+type ContentClipboardWriter = (payload: ContentClipboardPayload) => void | boolean | Promise<void | boolean>;
+/** Reported through `onCopy` after every copy attempt. */
+interface ContentCopyEvent extends ContentClipboardPayload {
+    /** Position of the button among this renderer's copy buttons, in document order. */
+    index: number;
+    /** Whether the clipboard write succeeded. */
+    ok: boolean;
+}
+interface ContentRendererProps {
+    value: string;
+    format?: "html" | "markdown" | "auto";
+    lineSpacing?: number;
+    className?: string;
+    /** Per-instance render extensions. Merged with any globally-registered extensions. */
+    extensions?: RenderExtension[];
+    /**
+     * Skip HTML sanitization. By default, rendered output is sanitized to remove
+     * `<script>`, `<iframe>`, event handlers, and `javascript:` URIs. Pass
+     * `unsafe` only when the input is fully trusted (e.g. server-rendered
+     * markdown from your own CMS).
+     * @default false
+     */
+    unsafe?: boolean;
+    /**
+     * Copy buttons on code blocks and tables. `false` turns them all off; an
+     * object turns kinds off individually (`{ table: false }`).
+     * @default true
+     */
+    copyButtons?: boolean | {
+        code?: boolean;
+        table?: boolean;
+    };
+    /** Called after every copy attempt, successful or not. */
+    onCopy?: (event: ContentCopyEvent) => void;
+    /**
+     * Host-supplied clipboard writer, for environments where
+     * `navigator.clipboard` is unreliable (e.g. a sandboxed Electron window:
+     * pass one that calls Electron's `clipboard`). The default writes
+     * text/html + text/plain via `ClipboardItem`, falling back to `writeText`.
+     */
+    clipboardWriter?: ContentClipboardWriter;
+    /**
+     * The value is still arriving. Set it back to `false` when the stream ends
+     * and everything renders.
+     *
+     * - `true` holds back an unfinished trailing custom tag (of a registered
+     *   extension) or code fence until it closes, so a partial `<result` or half
+     *   a code block never flashes as raw text.
+     * - `"progressive"` shows an open block as it fills: an open registered tag
+     *   whose opening tag is complete renders its component with the body so
+     *   far, and an open code fence renders as a code block of what has arrived
+     *   (with no copy button until it closes). A partial opening tag
+     *   (`<result title="Do`) is still held back.
+     * @default false
+     */
+    streaming?: boolean | "progressive";
+}
+
+export { type ContentClipboardPayload as C, type RenderExtension as R, type ContentClipboardWriter as a, type ContentCopyEvent as b, type ContentCopyKind as c, type ContentRendererProps as d, type RenderExtensionProps as e, registerExtensions as f, type ContentSegment as g, registerExtension as r };

package/dist/{PastedFilesInput-Bt3KSTVN.d.ts → PastedFilesInput-BT5y95sb.d.ts}

@@ -10,7 +10,8 @@ interface PillToInsert {
     block: boolean;
 }
 interface InlinePasteEditorHandle {
-    focus(): void;
+    /** Focus, caret at the end. `options` go to the element's `focus()` as given. */
+    focus(options?: FocusOptions): void;
     /** Swap a pill for plain text, where it sits. */
     replacePill(id: string, text: string): void;
     /**

package/dist/{PastedFilesInput-CUQeOeOA.d.cts → PastedFilesInput-Cd4k6a38.d.cts}

@@ -10,7 +10,8 @@ interface PillToInsert {
     block: boolean;
 }
 interface InlinePasteEditorHandle {
-    focus(): void;
+    /** Focus, caret at the end. `options` go to the element's `focus()` as given. */
+    focus(options?: FocusOptions): void;
     /** Swap a pill for plain text, where it sits. */
     replacePill(id: string, text: string): void;
     /**

package/dist/{chunk-U5LKNGHU.cjs → chunk-2PSHIUM7.cjs}

@@ -2,7 +2,7 @@
 
 var chunk2O5UXH5R_cjs = require('./chunk-2O5UXH5R.cjs');
 var chunkTLRFXSPA_cjs = require('./chunk-TLRFXSPA.cjs');
-var chunk6CAXLP7D_cjs = require('./chunk-6CAXLP7D.cjs');
+var chunkJ5TFVYYM_cjs = require('./chunk-J5TFVYYM.cjs');
 var chunkWKPBCB67_cjs = require('./chunk-WKPBCB67.cjs');
 var chunkMAZEX4EZ_cjs = require('./chunk-MAZEX4EZ.cjs');
 var chunkP53432AK_cjs = require('./chunk-P53432AK.cjs');
@@ -572,7 +572,7 @@ function JsonEditorValue({ node, mode, size, readOnly, id, onCommit }) {
       );
     case "secret":
       return /* @__PURE__ */ jsxRuntime.jsx(
-        chunk6CAXLP7D_cjs.Input,
+        chunkJ5TFVYYM_cjs.Input,
         {
           ...common,
           type: "password",
@@ -587,7 +587,7 @@ function JsonEditorValue({ node, mode, size, readOnly, id, onCommit }) {
     case "string":
     default:
       return /* @__PURE__ */ jsxRuntime.jsx(
-        chunk6CAXLP7D_cjs.Input,
+        chunkJ5TFVYYM_cjs.Input,
         {
           ...common,
           type: node.type === "url" ? "url" : node.type === "email" ? "email" : "text",
@@ -639,7 +639,7 @@ function RawValueEditor({
     );
   }
   return /* @__PURE__ */ jsxRuntime.jsx(
-    chunk6CAXLP7D_cjs.Input,
+    chunkJ5TFVYYM_cjs.Input,
     {
       id,
       size,
@@ -712,7 +712,7 @@ function JsonEditorRow({ node }) {
               className: "w-1/3 min-w-0 shrink-0",
               children: [
                 renameable ? /* @__PURE__ */ jsxRuntime.jsx(
-                  chunk6CAXLP7D_cjs.Input,
+                  chunkJ5TFVYYM_cjs.Input,
                   {
                     size: ctx.size,
                     mode: "edit",
@@ -889,7 +889,7 @@ function JsonEditorAddForm({ path, kind, depth, suggestedType }) {
       style: { paddingInlineStart: depth * INDENT + 32 },
       children: [
         kind === "object" && /* @__PURE__ */ jsxRuntime.jsx(
-          chunk6CAXLP7D_cjs.Input,
+          chunkJ5TFVYYM_cjs.Input,
           {
             size: ctx.size,
             mode: "edit",
@@ -1350,5 +1350,5 @@ exports.parsePath = parsePath;
 exports.pathToString = pathToString;
 exports.resolveKeyRule = resolveKeyRule;
 exports.typeMatches = typeMatches;
-//# sourceMappingURL=chunk-U5LKNGHU.cjs.map
-//# sourceMappingURL=chunk-U5LKNGHU.cjs.map
+//# sourceMappingURL=chunk-2PSHIUM7.cjs.map
+//# sourceMappingURL=chunk-2PSHIUM7.cjs.map