@danxbot/ui 7.6.0 → 7.7.1

package/dist/types/lib/markdown/image-pipeline.d.ts

@@ -0,0 +1,153 @@
+import { type LocalImageState } from "./image-decoration";
+import { type SourceSelection } from "./position";
+import type { MarkdownSurface } from "./surface";
+/**
+ * Stores one image and says where it now lives.
+ *
+ * `signal` aborts when the editor unmounts; an uploader that ignores it still
+ * works, its result is simply discarded. The returned `url` must be one an
+ * `<img>` may load (`http(s)`, a relative URL, or `data:image/*` —
+ * `sanitizeImageSrc`) and never another `blob:`; anything else is reported
+ * as a failed upload rather than written into the document.
+ */
+export type ImageUploader = (file: File, options: {
+    signal: AbortSignal;
+}) => Promise<{
+    url: string;
+}>;
+/**
+ * What the consumer needs to decide whether it may save (PLN-10 R-1).
+ *
+ * Counts IMAGES IN THE CURRENT DOCUMENT, one per construct — the same unit
+ * `findUnstoredImages` returns, so `unstored === findUnstoredImages(value).length`
+ * always. `uploading` are being stored, `failed` cannot be stored without the
+ * author acting (a rejected upload, or a `blob:` this editor did not mint), and
+ * `unstored` is every image not stored yet — `uploading + failed` plus those
+ * with no storage configured. `unstored > 0` means the value must not be saved.
+ */
+export interface ImageUploadState {
+    uploading: number;
+    failed: number;
+    unstored: number;
+}
+/** The editor's own view: the public counts, plus what its chrome needs. */
+export interface ImagePipelineSnapshot extends ImageUploadState {
+    /** Images that cannot be stored because there is no uploader. */
+    local: number;
+    /** Failed images this editor still holds the File for, so Retry can work. */
+    retryable: number;
+}
+/**
+ * The browser facilities the pipeline touches, injectable so a test never
+ * needs a real object URL or a real network.
+ */
+export interface ImagePipelineEnvironment {
+    createObjectURL: (file: File) => string;
+    revokeObjectURL: (url: string) => void;
+    /**
+     * Settles once `url` has loaded or failed to. The swap waits for it so the
+     * stored picture is already in the cache when it replaces the local one —
+     * otherwise the image blinks empty for as long as the download takes.
+     */
+    preload: (url: string) => Promise<unknown>;
+    /**
+     * The longest the swap waits for `preload`. A stored URL whose download
+     * stalls would otherwise hold an image that IS stored in "uploading" for
+     * ever — save disabled, page-leave guarded — for want of a cache warm-up.
+     */
+    preloadTimeoutMs: number;
+}
+export interface ImagePipelineOptions {
+    /** The uploader in force right now, or null when there is no storage. */
+    uploader: () => ImageUploader | null;
+    /** Called whenever the snapshot changes, and once when attached. */
+    onChange: (snapshot: ImagePipelineSnapshot) => void;
+    environment?: Partial<ImagePipelineEnvironment>;
+}
+export declare class ImagePipeline {
+    private readonly options;
+    private surface;
+    private readonly entries;
+    private readonly env;
+    private last;
+    private disposed;
+    constructor(options: ImagePipelineOptions);
+    /**
+     * The surface's `ImageResolver`: the state of an object URL this editor
+     * minted, or null for anything else. An arrow property so it can be handed
+     * to the surface before the surface exists.
+     */
+    readonly resolve: (src: string) => LocalImageState | null;
+    /** Connects the surface this pipeline edits, and reports the first snapshot. */
+    attach(surface: MarkdownSurface): void;
+    /**
+     * Binds the overlay buttons' Retry and Remove. Returns the unbind function.
+     *
+     * ONE DELEGATED LISTENER on the root, because the buttons live inside
+     * decorations the reconciler rebuilds whenever an image's state changes — a
+     * listener on a button would be thrown away with it.
+     */
+    bind(): () => void;
+    /**
+     * THE pipeline: every image file that enters the editor comes through here —
+     * paste, drop and the file picker alike.
+     *
+     * `at` is where the images go: the caret for a paste or a pick, the drop
+     * point for a drop. With none (an editor that was never focused), they go at
+     * the end of the document — never at offset 0 in front of whatever the
+     * author wrote first. Non-image files are ignored; the picker's `accept`
+     * is a hint the user can override, not a guarantee.
+     *
+     * Returns the object URLs it inserted, in order.
+     */
+    insert(files: readonly File[], at: SourceSelection | null): string[];
+    /**
+     * Uploads a failed image again, with the SAME File it was inserted with.
+     *
+     * With no uploader configured any more, the image becomes local-only rather
+     * than staying "failed" — the honest state for something nothing can store.
+     */
+    retry(src: string): void;
+    /** Retries every failed image still in the document. */
+    retryFailed(): void;
+    /**
+     * Starts uploading every local-only image once an uploader exists.
+     *
+     * The component calls this when its uploader changes: an image pasted
+     * before an app's storage provider mounted should not stay unsaveable when
+     * the storage it needed arrives a moment later.
+     */
+    uploaderChanged(): void;
+    /**
+     * Recomputes the snapshot from the CURRENT document, and releases object
+     * URLs nothing can reach any more. Called after every change to the source.
+     *
+     * THE COUNTS COME FROM `findUnstoredImages`, the same exported function a
+     * consumer's save path calls — one detection source, never a second opinion
+     * the two could disagree on (DX-3134).
+     *
+     * AN OBJECT URL IS RELEASED WHEN ITS IMAGE IS GONE AND SETTLED: not in the
+     * document, not in any undo or redo entry (Ctrl+Z could bring it back), and
+     * not mid-upload (the upload will swap it wherever it still is). Revoking one
+     * any earlier turns an undo into a broken image; never revoking leaks the
+     * file's bytes for the life of the page.
+     */
+    sync(): void;
+    /**
+     * Stops everything: aborts every upload in flight and releases every object
+     * URL. The editor is going away, so nothing it minted can be drawn anywhere
+     * again — no other editor will render another's `blob:`.
+     */
+    dispose(): void;
+    private upload;
+    /**
+     * Resolves when `work` settles, `preloadTimeoutMs` passes, or `signal`
+     * aborts — never rejects. Every timer and listener is cleaned up.
+     */
+    private settled;
+    private release;
+    /** An image's state moved: redraw its decoration and re-report. */
+    private changed;
+    private removeImage;
+    private requireSurface;
+}

package/dist/types/lib/markdown/images.d.ts

@@ -0,0 +1,68 @@
+/** An image whose picture exists only in this page's memory. */
+export interface UnstoredImage {
+    /** The `blob:` URL exactly as the source spells it. */
+    src: string;
+    alt: string;
+    /** The whole `![alt](src)` construct, as source offsets. */
+    start: number;
+    end: number;
+}
+/** Whether an image src names a picture that has not been stored anywhere. */
+export declare function isUnstoredImageSrc(src: string): boolean;
+/**
+ * Every image in `markdown` whose src is a `blob:` URL, in source order.
+ *
+ * THE SINGLE DETECTION SOURCE. The editor's own warning strip, its
+ * `onImageUploadStateChange` counts and its `beforeunload` guard all read this
+ * function, and it is exported so a consumer's save path can re-check the
+ * exact value it is about to persist with the same answer (DX-3134, PLN-10
+ * "Pending-state event").
+ *
+ * Read from the PARSER, not with a regex, for the reason `constructAt` gives:
+ * the parser has already decided what is an image, including the cases a
+ * pattern gets wrong — a `![x](blob:…)` inside a code span is prose, not a
+ * picture, and saving it loses nothing.
+ */
+export declare function findUnstoredImages(markdown: string): UnstoredImage[];
+/**
+ * A URL written so the destination parses as exactly that URL.
+ *
+ * Whitespace ends a destination, an unbalanced parenthesis ends the construct,
+ * and a backslash before punctuation is an escape markdown would consume — so
+ * all of them are percent-encoded, which is the same URL to every server and
+ * the only spelling that survives being written into markdown.
+ */
+export declare function markdownDestination(url: string): string;
+/** `![alt](src)`, with both halves escaped so they read back as themselves. */
+export declare function imageMarkdown(src: string, alt: string): string;
+/**
+ * The alt text a file brings with it: its name without the extension.
+ *
+ * A pasted screenshot is called `image.png` by every browser, so the result is
+ * "image" — not a description, but an honest placeholder the author can see
+ * and replace, which is better than the empty alt that makes an image
+ * invisible to a screen reader.
+ */
+export declare function altFromFileName(name: string): string;
+/** The result of replacing every occurrence of one string with another. */
+export interface Substitution {
+    source: string;
+    /** Carries an offset in the old source to the same place in the new one. */
+    map: (offset: number) => number;
+}
+/**
+ * Replaces EVERY occurrence of `from` in `source` with `to`, or returns null
+ * when there is none.
+ *
+ * A PLAIN TEXT REPLACEMENT, deliberately, and only safe because of what `from`
+ * is: an object URL this editor minted, which embeds a random UUID and was
+ * never typed by anyone. Every occurrence of it is that image, whatever
+ * construct holds it now — including one the author has since turned into a
+ * link, which a parser-driven swap would leave pointing at a dead handle in
+ * the saved value (DX-3134).
+ *
+ * `map` is what lets the caret survive the swap: offsets before an occurrence
+ * stay, offsets after one shift by the length change, and an offset that was
+ * INSIDE a replaced URL lands at the end of its replacement.
+ */
+export declare function substituteAll(source: string, from: string, to: string): Substitution | null;

package/dist/types/lib/markdown/input.d.ts

@@ -1,3 +1,5 @@
+import { type SourceSelection } from "./position";
+import { type EditorRequest } from "./hotkeys";
 import type { MarkdownSurface } from "./surface";
 export interface InputOptions {
     /**
@@ -8,8 +10,25 @@ export interface InputOptions {
      * broken, and this is how that gets noticed before a user reports it.
      */
     onUnhandled?: (inputType: string) => void;
+    /**
+     * Receives the image files of a paste or a drop, and where they go (DX-3134).
+     *
+     * `at` is the caret for a paste and the drop point for a drop, already on a
+     * caret stop. Without this option files are not handled here at all, and a
+     * paste or drop behaves exactly as it always did.
+     */
+    onImageFiles?: (files: File[], at: SourceSelection | null) => void;
+    /**
+     * Receives a hotkey that asks the EDITOR to do something rather than making
+     * an edit — the Insert-image chord opening a file picker (DX-3134). A
+     * request with no receiver lets the key fall through, like a command that
+     * declined.
+     */
+    onRequest?: (request: EditorRequest) => void;
 }
 /**
  * Binds the input layer to a surface. Returns the unbind function.
  */
 export declare function attachInput(surface: MarkdownSurface, options?: InputOptions): () => void;
+/** Marks the surface while image files are dragged over it, for the affordance. */
+export declare const DROP_TARGET_ATTR = "data-md-drop-target";

package/dist/types/lib/markdown/reconcile.d.ts

@@ -1,4 +1,5 @@
 import type { PNode } from "./project";
+import type { ImageResolver } from "./image-decoration";
 /**
  * Thrown when a patch would have had to disturb the node the browser is
  * composing into.
@@ -17,6 +18,11 @@ export interface PatchOptions {
      * removed; a patch that would need to do any of those throws.
      */
     protect?: Text | null;
+    /**
+     * Which image srcs the calling editor minted, and their state (DX-3134).
+     * Absent means "none" — every `blob:` is then refused, as it always was.
+     */
+    images?: ImageResolver;
 }
 export interface PatchStats {
     /** Text nodes whose `data` was assigned. */

package/dist/types/lib/markdown/surface.d.ts

@@ -2,6 +2,7 @@ import { type CaretMap } from "./caret-map";
 import { type Projection, type ProjectOptions } from "./project";
 import { type SourceSelection } from "./position";
 import { type EditKind, type HistoryOptions } from "./history";
+import type { ImageResolver } from "./image-decoration";
 export interface SurfaceOptions {
     /** Called after every committed change, with the new source. */
     onChange?: (source: string) => void;
@@ -20,6 +21,12 @@ export interface SurfaceOptions {
      * eats the user's text if it is swallowed.
      */
     onDesync?: (detail: string) => void;
+    /**
+     * Which object URLs this surface's editor minted, and what state each is in
+     * (DX-3134). Consulted on every render, so a state change only needs
+     * `refresh()`. Absent: no `blob:` src ever renders.
+     */
+    images?: ImageResolver;
 }
 export interface Splice {
     start: number;
@@ -30,6 +37,17 @@ export declare class MarkdownSurface {
     readonly root: HTMLElement;
     private source;
     private readonly options;
+    /**
+     * Upload swaps that arrived mid-composition, applied at `compositionend`.
+     *
+     * DX-3134: the composing text node carries the source range it came from,
+     * and `reconcileComposed` writes the composed text back into exactly that
+     * range. A swap applied mid-composition changes the length of the source
+     * before the node — the range would then point at the wrong characters, and
+     * the composed text would land inside a URL. So the swap waits, and runs
+     * right after the composition has been read back.
+     */
+    private pendingSubstitutions;
     /** The text node the browser is composing into, if any. */
     private composing;
     /** A projection that arrived while composing, applied at `compositionend`. */
@@ -82,6 +100,51 @@ export declare class MarkdownSurface {
      * exactly right or exactly wrong, with nothing in between.
      */
     apply(splice: Splice, select?: SourceSelection, kind?: EditKind): void;
+    /**
+     * Replaces every occurrence of `from` with `to` — in the document AND in
+     * every undo and redo entry — without recording an edit.
+     *
+     * THIS IS THE UPLOAD SWAP (DX-3134), and it is deliberately not an edit.
+     * When an image finishes uploading, its object URL is replaced by the stored
+     * URL. Recorded as an ordinary edit, Ctrl+Z would hand the object URL back —
+     * and a document holding it is a document that cannot be saved, for an image
+     * that WAS saved. Rewriting the history too means no undo, redo or later
+     * edit can resurrect a URL that no longer means anything.
+     *
+     * The caret stays where it was in the text the user can see: it is mapped
+     * through the substitution rather than moved, and only written back if it was
+     * in this surface to begin with — an upload finishing must never pull focus
+     * out of whatever the user moved on to. `onChange` fires, because the value
+     * genuinely changed and the consumer is the one who saves it.
+     *
+     * WHILE COMPOSING, the swap is queued and applied at `compositionend` — see
+     * `pendingSubstitutions`. A caller that needs to know when it has landed
+     * watches for `from` to leave the source (`onChange` fires when it does).
+     */
+    substitute(from: string, to: string): void;
+    /**
+     * The selection, but only while this surface HAS FOCUS.
+     *
+     * DX-3134: a render that is not the user's own edit — an upload finishing, an
+     * image's state moving — writes the caret back only when the author is
+     * actually in this document. The document selection can still sit inside the
+     * surface after focus has gone to a button or another field, and writing a
+     * selection into an editing host is one of the things that pulls focus back
+     * into it: an upload landing would then yank the author out of whatever they
+     * moved on to.
+     */
+    private focusedSelection;
+    /** Whether any undo or redo entry still holds `text` — see `History.includes`. */
+    remembers(text: string): boolean;
+    /**
+     * Re-renders the current document, keeping the caret.
+     *
+     * For a change the SOURCE does not show: an image's upload state lives in
+     * the resolver, so the decoration has to be redrawn when it moves (DX-3134).
+     * Unchanged text nodes are not touched, so the caret is only rewritten when
+     * this surface has focus — and then to the offsets it already had.
+     */
+    refresh(): void;
     /** Replaces the whole document, e.g. when the consumer's value prop changes. */
     setSource(source: string): void;
     get canUndo(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "7.6.0",
+  "version": "7.7.1",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",