@mieweb/ui 0.6.1-dev.148 → 0.6.1-dev.150

package/dist/components/SuperChat/plugins/index.d.ts

@@ -0,0 +1,253 @@
+import { a as SuperChatRenderPlugin, e as GenUIRegistry } from '../../../types-BFFgW6qy.js';
+export { f as GenUIWidgetEntry, g as GenUIWidgetProps } from '../../../types-BFFgW6qy.js';
+import 'react';
+import '../../../types-BzeY_kYO.js';
+
+/**
+ * SuperChat code plugin (opt-in).
+ *
+ * Syntax-highlights fenced code blocks with `rehype-highlight` (emits `.hljs-*`
+ * classes that map to `--mieweb-*` theme tokens for light/dark), and adds a copy
+ * button. `shiki` is reserved as an upgrade path if highlight fidelity disappoints.
+ */
+
+/** Create the syntax-highlighting + copy-button render plugin. */
+declare function createCodePlugin(): SuperChatRenderPlugin;
+
+/**
+ * SuperChat math plugin (opt-in).
+ *
+ * Renders `$…$` (inline) and `$$…$$` (block) math with `remark-math` +
+ * `rehype-katex` (KaTeX). Consumers must also load KaTeX's stylesheet:
+ *
+ * ```ts
+ * import 'katex/dist/katex.min.css';
+ * ```
+ *
+ * The sanitize allow-list is extended so KaTeX's HTML + MathML output survives
+ * the untrusted-content sanitizer.
+ */
+
+/** Create the math (KaTeX) render plugin. */
+declare function createMathPlugin(): SuperChatRenderPlugin;
+
+/**
+ * SuperChat GenUI plugin (opt-in).
+ *
+ * Interactive widgets expressed as fenced ```genui JSON blocks:
+ *
+ * ````md
+ * ```genui
+ * { "widget": "math_block", "version": 2, "prefetch": "eager", "props": { "content": "a^2+b^2=c^2" } }
+ * ```
+ * ````
+ *
+ * Widgets are **host-registered, lazy, and schema-validated**. Unknown widgets
+ * degrade to an inert code block. Prefetch is split into component (code) vs.
+ * data, with `eager` / `visible` / `idle` policies; the **registry policy
+ * overrides the wire hint**. Mount + data fetch are gated on `streaming` and a
+ * complete/valid payload (a `MCPToolCall`-style pending card shows until then).
+ */
+
+declare const GENUI_TAG = "genui-widget";
+/** Create the GenUI render plugin from a host widget registry. */
+declare function createGenUIPlugin(registry: GenUIRegistry): SuperChatRenderPlugin;
+
+/**
+ * SuperChat Mermaid plugin (opt-in).
+ *
+ * Renders fenced ```mermaid blocks as diagrams via the lazily-loaded `mermaid`
+ * library:
+ *
+ * ````md
+ * ```mermaid
+ * graph TD; A-->B; A-->C;
+ * ```
+ * ````
+ *
+ * `mermaid` is heavy, so it loads on first render (never in the SuperChat base
+ * bundle). Rendering is gated on `streaming` — partial diagram source mid-stream
+ * shows a pending card and only renders once the message settles. Diagrams are
+ * rendered with mermaid's `securityLevel: 'strict'`, which sanitizes labels and
+ * strips scripts; the resulting SVG is inserted directly (it bypasses
+ * `rehype-sanitize`, so strict mode is the trust boundary here).
+ */
+
+declare const MERMAID_TAG = "mermaid-diagram";
+/** Create the Mermaid diagram render plugin. */
+declare function createMermaidPlugin(): SuperChatRenderPlugin;
+
+/**
+ * SuperChat image plugin (opt-in).
+ *
+ * Makes inline Markdown images (`![alt](url)`) click-to-zoom, reusing the
+ * Messaging module's full-screen {@link LightboxModal}. The image `src`/`alt`
+ * come from (untrusted) Markdown and are already protocol-restricted by
+ * `rehype-sanitize`; this plugin only adds the zoom affordance.
+ */
+
+/** Create the image (click-to-zoom lightbox) render plugin. */
+declare function createImagePlugin(): SuperChatRenderPlugin;
+
+/**
+ * SuperChat NITRO table plugin (opt-in).
+ *
+ * Renders GFM tables through **NITRO DataVis** (sortable / filterable /
+ * resizable) instead of a static `<table>`. The heavy grid is `React.lazy`-loaded
+ * only when a table appears, and if the `datavis` engine can't load (e.g. the
+ * submodule isn't installed) it **degrades gracefully** to the themed HTML table.
+ *
+ * @example
+ * import { createNitroTablePlugin } from '@mieweb/ui/components/SuperChat/plugins';
+ * const render = createMarkdownRenderer({ plugins: [createNitroTablePlugin()] });
+ */
+
+/** Create the NITRO DataVis table render plugin. */
+declare function createNitroTablePlugin(): SuperChatRenderPlugin;
+
+/**
+ * SuperChat attachment plugin (opt-in, offline-first).
+ *
+ * Renders file attachments (image / video / audio / pdf / generic) inline in a
+ * message via a fenced ` ```superchat-attachment ` block whose body is a small
+ * JSON descriptor:
+ *
+ * ````md
+ * ```superchat-attachment
+ * { "id": "att-1", "type": "video/mp4", "name": "clip.mp4" }
+ * ```
+ * ````
+ *
+ * Use {@link attachmentMarkdown} to build the block. The descriptor carries an
+ * attachment **id**; the player resolves a `blob:` URL from the
+ * {@link attachmentCache} (IndexedDB) at render time, so previously sent media
+ * keeps rendering offline without storing base64 in the conversation. An
+ * optional inline `src` (`data:` URL) is used as a fallback when the cache is
+ * empty or unavailable, and is opportunistically persisted for next time.
+ *
+ * Mirrors the GenUI plugin's fence→custom-element rehype transform so the
+ * payload never travels through `urlTransform` / raw-HTML, keeping the pipeline
+ * robust under `rehype-sanitize`.
+ */
+
+/** Custom element the fenced block is rewritten to before sanitization. */
+declare const ATTACHMENT_TAG = "superchat-attachment";
+/** Fenced-code language that marks an attachment block. */
+declare const ATTACHMENT_FENCE = "superchat-attachment";
+/** JSON payload carried by a ` ```superchat-attachment ` block. */
+interface AttachmentBlockPayload {
+    /** Attachment id used as the {@link attachmentCache} key. */
+    id?: string;
+    /** MIME type, e.g. `video/mp4`. */
+    type: string;
+    /** File name (shown as a label / download name). */
+    name: string;
+    /** Optional inline `data:` URL fallback when the cache has no entry. */
+    src?: string;
+}
+/**
+ * Build the Markdown for an attachment block. Embed the result in a message so
+ * the attachment plugin renders it.
+ *
+ * @example
+ * const md = attachmentMarkdown({ id: att.id, type: att.type, name: att.name });
+ */
+declare function attachmentMarkdown(payload: AttachmentBlockPayload): string;
+type AttachmentUrlStatus = 'idle' | 'loading' | 'ready' | 'missing';
+/**
+ * Resolve a displayable URL for an attachment. Prefers a cached `blob:` URL
+ * (offline), falling back to the inline `data:` URL when the cache is empty or
+ * unavailable. The returned object URL is revoked automatically on unmount /
+ * id change.
+ */
+declare function useAttachmentUrl(id?: string, fallbackSrc?: string): {
+    url?: string;
+    status: AttachmentUrlStatus;
+};
+/**
+ * Create the attachment render plugin: renders ` ```superchat-attachment `
+ * blocks as inline image/video/audio/pdf players backed by the offline
+ * {@link attachmentCache}.
+ */
+declare function createAttachmentPlugin(): SuperChatRenderPlugin;
+
+/**
+ * SuperChat attachment cache (opt-in, offline-first).
+ *
+ * A tiny IndexedDB-backed blob store keyed by **attachment id**. Hosts persist
+ * a composer attachment's bytes here once (e.g. on send), embed only the id in
+ * the message, and the attachment render plugin resolves a fresh `blob:` URL
+ * from the cache at render time — so previously sent media keeps rendering
+ * while offline without bloating the stored conversation with base64.
+ *
+ * Everything degrades gracefully: when IndexedDB is unavailable (SSR, private
+ * mode, older browsers) the methods resolve to safe no-op values and callers
+ * fall back to any inline `src` they were given.
+ */
+/** A blob persisted in the cache, plus its descriptive metadata. */
+interface CachedAttachment {
+    /** Stable attachment id (the object-store key). */
+    id: string;
+    /** Original file name. */
+    name: string;
+    /** MIME type, e.g. `video/mp4`. */
+    type: string;
+    /** The raw file bytes. */
+    blob: Blob;
+    /** Byte length of {@link blob}. */
+    size: number;
+    /** Epoch ms the entry was written. */
+    cachedAt: number;
+    /** Epoch ms of the last read (drives LRU eviction). */
+    lastAccessed: number;
+}
+/** Input accepted by {@link AttachmentCache.put}. Provide `blob` or `dataUrl`. */
+interface PutAttachmentInput {
+    id: string;
+    name: string;
+    type: string;
+    blob?: Blob;
+    /** Base64 (or URL-encoded) `data:` URL; converted to a Blob before storage. */
+    dataUrl?: string;
+}
+declare function hasIndexedDB(): boolean;
+/**
+ * Offline blob store for SuperChat attachments. All methods are safe to call in
+ * any environment; without IndexedDB they resolve to no-ops / `undefined`.
+ */
+declare const attachmentCache: {
+    /** Whether a persistent IndexedDB store is available in this environment. */
+    isAvailable: typeof hasIndexedDB;
+    /**
+     * Tune the cache. `maxBytes` is the eviction budget (default 100 MB); when a
+     * `put` pushes the total past it, least-recently-used entries are dropped
+     * until it fits. Set `Infinity` to disable eviction.
+     */
+    configure(options: {
+        maxBytes?: number;
+    }): void;
+    /** Total bytes currently held by the cache (0 when unavailable). */
+    usage(): Promise<number>;
+    /**
+     * Persist an attachment's bytes by id. Pass a `blob` or a `dataUrl`. Resolves
+     * to `true` when stored, `false` if unavailable or the input was unusable.
+     * Writing past the configured `maxBytes` evicts least-recently-used entries.
+     */
+    put(input: PutAttachmentInput): Promise<boolean>;
+    /** Read a cached attachment (blob + metadata) by id, or `undefined`. */
+    get(id: string): Promise<CachedAttachment | undefined>;
+    /**
+     * Resolve a fresh `blob:` object URL for a cached attachment, or `undefined`
+     * if it isn't cached. **The caller owns the URL** and must
+     * `URL.revokeObjectURL` it when done (the {@link useAttachmentUrl} hook does
+     * this automatically).
+     */
+    getObjectURL(id: string): Promise<string | undefined>;
+    /** Remove a cached attachment by id. */
+    delete(id: string): Promise<void>;
+    /** Drop every cached attachment. */
+    clear(): Promise<void>;
+};
+type AttachmentCache = typeof attachmentCache;
+
+export { ATTACHMENT_FENCE, ATTACHMENT_TAG, type AttachmentBlockPayload, type AttachmentCache, type CachedAttachment, GENUI_TAG, GenUIRegistry, MERMAID_TAG, type PutAttachmentInput, attachmentCache, attachmentMarkdown, createAttachmentPlugin, createCodePlugin, createGenUIPlugin, createImagePlugin, createMathPlugin, createMermaidPlugin, createNitroTablePlugin, useAttachmentUrl };