edytor 1.0.0-rc.3 → 2.0.0

package/dist/plugins/media/empty.svelte.d.ts

@@ -1,75 +1,76 @@
 import type { Attachment } from 'svelte/attachments';
 import type { Block } from '../../block/block.svelte.js';
-import type { MediaKindLabels, MediaLabels } from '../../labels.js';
 import type { MediaKind } from './media.js';
-import { type FileUpload, type Uploader } from '../uploads.svelte.js';
-/** Why the last link or upload was not embedded. */
-export type MediaEmptyFailure = 'invalid' | 'upload';
+import { type FileUpload } from '../uploads.svelte.js';
+/** Each media kind's icon (the image's too): its menu row, its empty block, its paste offer. */
+export declare const MEDIA_ICONS: Record<MediaKind | 'image', string>;
 /**
- * An empty media block's state (an embed, a bookmark, a file, a video, an
- * audio track: the image's pattern, Notion's): the panel's `open` state,
- * the link field's `draft`, why the last link or upload was not embedded
- * (`failed`), and the upload of a pasted or dropped file (`pending`);
- * `embed` and `upload` set the source. What a media plugin's `empty`
- * snippet receives (one per empty block shown).
+ * Why the last link or upload was not embedded: no source the kind takes
+ * (`invalid`), an inline image over the cap (`inline`), a failed upload.
+ */
+export type MediaEmptyFailure = 'invalid' | 'inline' | 'upload';
+/** What an empty block reads of its kind in a view: how it stores a source. */
+export type EmptyView = {
+    /** Store a link (or the URL an upload of `file` answered) on `block`: why it did not, or `null`. */
+    store: (block: Block, value: string, file?: File) => MediaEmptyFailure | null;
+};
+/**
+ * An empty image or media block's state (an image, an embed, a bookmark, a
+ * file, a video, an audio track: Notion's "Add …"): the panel's `open`
+ * state, the link field's `draft`, why the last link or upload was not
+ * embedded (`failed`), and the upload of a pasted or dropped file
+ * (`pending`); `embed` and `upload` set the source. What an image or media
+ * plugin's `empty` snippet receives (one per empty block shown).
  */
 export declare class MediaEmptyController {
+    #private;
     /** The empty block; none in a suggestion's preview. */
     readonly block: Block | undefined;
-    /** Which media kind it is: whose words it shows. */
-    readonly kind: MediaKind;
-    /** The kind's icon (an emoji). */
-    readonly icon: string;
-    private words;
-    private options;
+    /** Which kind it is (your words for it: its button, placeholder, errors). */
+    readonly kind: MediaKind | 'image';
+    /** The kind in the block's view. */
+    private view;
     /** The link panel is open. */
     open: boolean;
     /** The link field's text. */
     draft: string;
-    /** Why the last link or upload was not embedded (`false`: it was, or none was tried). */
-    failed: false | MediaEmptyFailure;
+    /** Why the last link or upload was not embedded (`null`: it was, or none was tried). */
+    failed: MediaEmptyFailure | null;
     constructor(
     /** The empty block; none in a suggestion's preview. */
     block: Block | undefined, 
-    /** Which media kind it is: whose words it shows. */
-    kind: MediaKind, 
+    /** Which kind it is (your words for it: its button, placeholder, errors). */
+    kind: MediaKind | 'image', 
+    /** The kind in the block's view. */
+    view: EmptyView | undefined);
     /** The kind's icon (an emoji). */
-    icon: string, words: () => MediaLabels, options: {
-        /** The file picker's `accept`. */
-        accept?: string;
-        upload?: Uploader;
-        /** Store a link; answers whether the block took it. */
-        link: (value: string) => boolean;
-        /** Store an uploaded file's URL; answers whether the block took it. */
-        file?: (file: File, src: string) => boolean;
-    });
-    /** The words of the view rendering it (a suggestion's preview included). */
-    get labels(): MediaLabels;
-    /** The kind's own words (its button, placeholder, submit and invalid link text). */
-    get kindLabels(): MediaKindLabels & {
-        addOrUpload?: string;
-    };
-    /** The button and placeholder text ("Embed a link"; the file's names its upload). */
-    get label(): string;
-    /** The file picker's `accept`. */
+    get icon(): string;
+    /** The file picker's `accept`: `image/*`, `video/*`, `audio/*`, else any file. */
     get accept(): string | undefined;
     /**
      * No control may write: a readonly view, or a suggestion's preview (no
      * block). Show a passive placeholder then.
      */
     get readonly(): boolean;
-    /** The plugin has an `upload`: offer Upload. */
+    /** The kind's plugin was given an `upload`: offer Upload. */
     get canUpload(): boolean;
-    /** The upload of a pasted or dropped file into this block, if any (its `status`, `progress`). */
+    /** The upload of a pasted or dropped file into this block, if any (its `status`, `progress`, `preview`). */
     get pending(): FileUpload | undefined;
-    /** Open or close the link panel. */
-    toggle: () => void;
-    /** Embed `value` (default the `draft`): the block takes the link, or `failed` says it did not. */
+    /**
+     * The file uploading into this block, shown at once: its object URL
+     * (this view's only, never stored; revoked once the upload ends), else `null`.
+     */
+    get preview(): string | null;
+    /** The share of the upload sent, `0` to `1`; `null` before a report, or with no upload. */
+    get progress(): number | null;
+    /** Embed `value` (default the `draft`): the block takes the link, or `failed` says why not. */
     embed: (value?: string) => void;
     /**
-     * Upload `file` with the plugin's `upload` and store the URL it answers,
-     * only on the block as it was picked from: still in the tree, of its kind
-     * and empty (a peer may have set a source, or deleted it, meanwhile).
+     * Upload `file` with its kind's uploader (its plugin's `upload`), the
+     * block showing it meanwhile (`pending`, `preview`, `progress`), and
+     * store the URL it answers, only on the block as it was picked from:
+     * still in the tree, of its kind and empty (a peer may have set a
+     * source, or deleted it, meanwhile).
      */
     upload: (picked: File) => Promise<void>;
     /** The link field (`{@attach empty.field}`): Enter embeds its `draft`. */

package/dist/plugins/media/empty.svelte.js

@@ -1,53 +1,51 @@
 import { fileUploads } from '../uploads.svelte.js';
+import { listen } from '../../utils/listen.js';
+/** Each media kind's icon (the image's too): its menu row, its empty block, its paste offer. */
+export const MEDIA_ICONS = {
+    image: '🖼',
+    embed: '⧉',
+    bookmark: '🔖',
+    file: '📎',
+    video: '🎬',
+    audio: '🎵'
+};
 /**
- * An empty media block's state (an embed, a bookmark, a file, a video, an
- * audio track: the image's pattern, Notion's): the panel's `open` state,
- * the link field's `draft`, why the last link or upload was not embedded
- * (`failed`), and the upload of a pasted or dropped file (`pending`);
- * `embed` and `upload` set the source. What a media plugin's `empty`
- * snippet receives (one per empty block shown).
+ * An empty image or media block's state (an image, an embed, a bookmark, a
+ * file, a video, an audio track: Notion's "Add …"): the panel's `open`
+ * state, the link field's `draft`, why the last link or upload was not
+ * embedded (`failed`), and the upload of a pasted or dropped file
+ * (`pending`); `embed` and `upload` set the source. What an image or media
+ * plugin's `empty` snippet receives (one per empty block shown).
  */
 export class MediaEmptyController {
     block;
     kind;
-    icon;
-    words;
-    options;
+    view;
     /** The link panel is open. */
     open = $state(false);
     /** The link field's text. */
     draft = $state('');
-    /** Why the last link or upload was not embedded (`false`: it was, or none was tried). */
-    failed = $state(false);
+    /** Why the last link or upload was not embedded (`null`: it was, or none was tried). */
+    failed = $state(null);
     constructor(
     /** The empty block; none in a suggestion's preview. */
     block, 
-    /** Which media kind it is: whose words it shows. */
+    /** Which kind it is (your words for it: its button, placeholder, errors). */
     kind, 
-    /** The kind's icon (an emoji). */
-    icon, words, options) {
+    /** The kind in the block's view. */
+    view) {
         this.block = block;
         this.kind = kind;
-        this.icon = icon;
-        this.words = words;
-        this.options = options;
-    }
-    /** The words of the view rendering it (a suggestion's preview included). */
-    get labels() {
-        return this.words();
+        this.view = view;
     }
-    /** The kind's own words (its button, placeholder, submit and invalid link text). */
-    get kindLabels() {
-        return this.labels[this.kind];
-    }
-    /** The button and placeholder text ("Embed a link"; the file's names its upload). */
-    get label() {
-        const words = this.kindLabels;
-        return this.options.upload && words.addOrUpload ? words.addOrUpload : words.add;
+    /** The kind's icon (an emoji). */
+    get icon() {
+        return MEDIA_ICONS[this.kind];
     }
-    /** The file picker's `accept`. */
+    /** The file picker's `accept`: `image/*`, `video/*`, `audio/*`, else any file. */
     get accept() {
-        return this.options.accept;
+        const { kind } = this;
+        return kind === 'image' || kind === 'video' || kind === 'audio' ? `${kind}/*` : undefined;
     }
     /**
      * No control may write: a readonly view, or a suggestion's preview (no
@@ -56,50 +54,60 @@ export class MediaEmptyController {
     get readonly() {
         return !this.block || this.block.edytor.readonly;
     }
-    /** The plugin has an `upload`: offer Upload. */
+    /** The kind's plugin was given an `upload`: offer Upload. */
     get canUpload() {
-        return Boolean(this.options.upload);
+        const { block } = this;
+        return Boolean(block && fileUploads(block.edytor) && block.definition.upload);
     }
-    /** The upload of a pasted or dropped file into this block, if any (its `status`, `progress`). */
+    /** The upload of a pasted or dropped file into this block, if any (its `status`, `progress`, `preview`). */
     get pending() {
         const { block } = this;
         return block ? fileUploads(block.edytor)?.of(block.id) : undefined;
     }
-    /** Open or close the link panel. */
-    toggle = () => {
-        this.open = !this.open;
-    };
-    /** Embed `value` (default the `draft`): the block takes the link, or `failed` says it did not. */
+    /**
+     * The file uploading into this block, shown at once: its object URL
+     * (this view's only, never stored; revoked once the upload ends), else `null`.
+     */
+    get preview() {
+        const { pending } = this;
+        return pending?.status === 'uploading' ? pending.preview : null;
+    }
+    /** The share of the upload sent, `0` to `1`; `null` before a report, or with no upload. */
+    get progress() {
+        const { pending } = this;
+        return pending?.status === 'uploading' ? pending.progress : null;
+    }
+    /** Store `value` on the block: why it did not take it, or `null`. */
+    #store = (value, file) => this.block && this.view ? this.view.store(this.block, value, file) : 'invalid';
+    /** Embed `value` (default the `draft`): the block takes the link, or `failed` says why not. */
     embed = (value = this.draft) => {
-        this.failed = this.options.link(value) ? false : 'invalid';
+        this.failed = this.#store(value);
         if (!this.failed && this.block)
             fileUploads(this.block.edytor)?.clear(this.block.id);
     };
     /**
-     * Upload `file` with the plugin's `upload` and store the URL it answers,
-     * only on the block as it was picked from: still in the tree, of its kind
-     * and empty (a peer may have set a source, or deleted it, meanwhile).
+     * Upload `file` with its kind's uploader (its plugin's `upload`), the
+     * block showing it meanwhile (`pending`, `preview`, `progress`), and
+     * store the URL it answers, only on the block as it was picked from:
+     * still in the tree, of its kind and empty (a peer may have set a
+     * source, or deleted it, meanwhile).
      */
     upload = async (picked) => {
         const { block } = this;
-        const { upload, file, link } = this.options;
-        if (!upload || !block || block.edytor.readonly)
+        const uploads = this.canUpload && fileUploads(block?.edytor);
+        if (!uploads || !block || block.edytor.readonly)
             return;
         const { edytor, id, type } = block;
-        let src;
-        try {
-            src = await upload(picked, { progress: () => { } });
-        }
-        catch {
+        const stored = await uploads.pick(id, picked, (src) => {
+            const live = edytor.idToBlock.get(id);
+            if (!live?.isInTree || live.type !== type || edytor.readonly)
+                return;
+            if (edytor.facade.blockDataOf(id)?.src !== undefined)
+                return;
+            this.failed = this.#store(src, picked);
+        });
+        if (!stored)
             this.failed = 'upload';
-            return;
-        }
-        const live = edytor.idToBlock.get(id);
-        if (!live?.isInTree || live.type !== type || edytor.readonly)
-            return;
-        if (edytor.facade.blockDataOf(id)?.src !== undefined)
-            return;
-        this.failed = (file ? file(picked, src) : link(src)) ? false : 'invalid';
     };
     /** The link field (`{@attach empty.field}`): Enter embeds its `draft`. */
     field = (node) => {
@@ -109,7 +117,6 @@ export class MediaEmptyController {
             event.preventDefault();
             this.embed();
         };
-        node.addEventListener('keydown', keydown);
-        return () => node.removeEventListener('keydown', keydown);
+        return listen(node, 'keydown', keydown);
     };
 }

package/dist/plugins/media/media.d.ts

@@ -1,24 +1,106 @@
 import type { Snippet } from 'svelte';
 import type { Edytor } from '../../edytor.svelte.js';
-import type { PluginOperations } from '../../plugins.js';
-import { type Uploader } from '../uploads.svelte.js';
-import { viewLabels, type PartialLabels } from '../../labels.js';
-import type { MediaEmptyController } from './empty.svelte.js';
-/** The media kinds a view shows the labels of. */
+import type { Block } from '../../block/block.svelte.js';
+import type { Attachment } from 'svelte/attachments';
+import type { BlockDefinition, Plugin, PluginDefinitions, PluginOperations } from '../../plugins.js';
+import { escapeHtml } from '../../clipboard/serializeClipboardFragment.js';
+import { MEDIA_ICONS, type EmptyView } from './empty.svelte.js';
+/** The media kinds. */
 export type MediaKind = 'embed' | 'bookmark' | 'file' | 'video' | 'audio';
+export { MEDIA_ICONS };
 /**
- * Each view's media labels, by kind: the first plugin of a kind listed in a
- * view claims them, as its kind record (first wins).
+ * A media kind in a view: the first plugin of the kind listed in it claims
+ * it, as its kind record (first wins): how a block of it stores a source,
+ * the embed's allowlist, and the app's markup for the kind's own control
+ * (the bookmark's `card`, the file's `row`, the embed's `fallback`).
  */
-export declare const mediaLabels: Record<MediaKind, ReturnType<typeof viewLabels<'media'>>>;
+export type MediaView = EmptyView & {
+    providers?: readonly EmbedProvider[];
+    card?: Snippet<[BookmarkCardPayload]>;
+    row?: Snippet<[FileRowPayload]>;
+    fallback?: Snippet<[EmbedFallbackPayload]>;
+};
+/** What a bookmark's `card` snippet receives: the page it links to, as `unfurl` described it. */
+export type BookmarkCardPayload = {
+    /** The bookmark; `undefined` in a suggestion's preview. */
+    block: Block | undefined;
+    /** The page's URL (`http(s)`). */
+    url: string;
+    /** Its title, description, cover image and icon, when `unfurl` answered them. */
+    title: string | undefined;
+    description: string | undefined;
+    image: string | undefined;
+    icon: string | undefined;
+    /**
+     * The card's link (`<a href={card.url} {@attach card.link}>`): a new tab
+     * without the opener, never dragged out of the editor.
+     */
+    link: Attachment<HTMLElement>;
+};
+/** What a file block's `row` snippet receives: the file it links to. */
+export type FileRowPayload = {
+    /** The file block; `undefined` in a suggestion's preview. */
+    block: Block | undefined;
+    /** The file's URL. */
+    src: string;
+    /** Its name: the uploaded file's, else its URL's last segment. */
+    name: string;
+    /** Its size in bytes, when it was uploaded. */
+    size: number | undefined;
+    /** That size in the view's words (`media.fileSize`), `''` without one. */
+    sizeLabel: string;
+    /**
+     * The file is uploading (then `src` is its object URL, this view's only,
+     * never stored): the row shows it at once, with `progress`.
+     */
+    uploading: boolean;
+    /** The share sent while it uploads, `0` to `1`; `null` before a report or once stored. */
+    progress: number | null;
+    /**
+     * The row's link (`<a href={row.src} {@attach row.link}>`): it downloads
+     * the file under its name, in a new tab without the opener, never dragged
+     * out of the editor.
+     */
+    link: Attachment<HTMLElement>;
+};
+/** What an embed's `fallback` snippet receives: a link no allowed provider plays. */
+export type EmbedFallbackPayload = {
+    /** The embed; `undefined` in a suggestion's preview. */
+    block: Block | undefined;
+    /** The link (`http(s)`), shown as a link, never in a frame. */
+    url: string;
+    /** Its link (`<a href={fallback.url} {@attach fallback.link}>`): a new tab without the opener. */
+    link: Attachment<HTMLElement>;
+};
+/** A media block's link opens a new tab without the opener (and tells the target nothing). */
+export declare const LINK_REL = "noopener noreferrer nofollow";
 /**
- * Each view's `empty` snippet, by kind: the first plugin of a kind listed in
- * a view claims it (with none, the built-in markup), as its kind record.
+ * A media block's link's attachment: a new tab without the opener
+ * (`target`, `rel`), and `own` (`draggable="false"`: no drag of its own; a
+ * file's `download` name). The default markup writes the same, so a server
+ * render's link is safe too; its `href` is the markup's.
  */
-export declare const mediaEmpty: {
-    claim(edytor: Edytor | undefined, kind: MediaKind, snippet?: Snippet<[MediaEmptyController]>): void;
-    of: (edytor: Edytor | undefined, kind: MediaKind) => Snippet<[MediaEmptyController]> | undefined;
-};
+export declare const mediaLink: (own?: {
+    draggable?: "false";
+    download?: string;
+}) => Attachment<HTMLElement>;
+/** The app's markup for a media kind's own control in `view`, if any. */
+export declare const mediaControl: <K extends "card" | "row" | "fallback">(kind: MediaKind, control: K) => (view: Edytor | undefined) => MediaView[K] | undefined;
+/** The view's media kind, when a plugin of it is listed there. */
+export declare const mediaView: (edytor: Edytor | undefined, kind: MediaKind) => MediaView | undefined;
+/**
+ * A media kind's plugin (Notion's): a void `figure` with an editable
+ * caption, its preset (its icon, `keywords`, its name in the view's
+ * `media` labels), and its view
+ * (`MediaView`), which the first plugin of the kind listed claims. `own`
+ * answers the kind's own parts: how it stores a source, its hooks and its
+ * record (its snippet, its export and import); `claims` says whether this
+ * plugin claimed the kind in `edytor`.
+ */
+export declare const mediaPlugin: (kind: MediaKind, keywords: string[], own: (edytor: Edytor, claims: boolean) => Pick<MediaView, "store" | "providers" | "card" | "row" | "fallback"> & {
+    hooks?: PluginOperations & PluginDefinitions;
+    record: Partial<BlockDefinition>;
+}) => Plugin;
 /**
  * A web page's URL a media block may store or render: the link sanitizer's
  * reading of it (`sanitizeLinkHref`: ASCII control characters and spaces stripped,
@@ -33,27 +115,6 @@ export declare const safeWebUrl: (value: unknown) => string | null;
  * an inline file would be stored in the document and sent in every update.
  */
 export declare const safeMediaSrc: (value: unknown) => string | null;
-/** The file, video and audio plugins' options. */
-export type MediaPluginOptions = {
-    /**
-     * Upload a file and answer its URL: the empty block's Upload button, and
-     * the pasted and dropped files the kind takes (`media.files`), each shown
-     * uploading with the progress it reports. Without it only links are
-     * embedded.
-     */
-    upload?: Uploader;
-    /** The words the block shows (its empty panel, its menu row), over the English ones. */
-    labels?: PartialLabels<'media'>;
-    /** The slash menu's keywords of its command (`block.<kind>`), which replace its own. */
-    keywords?: Partial<Record<string, string[]>>;
-    /**
-     * Replace an empty block's markup (its "Add …" button and link panel, its
-     * upload's progress, or a readonly view's placeholder): it receives the
-     * block's `MediaEmptyController` (`open`, `draft`, `failed`, `pending`,
-     * `embed`, `upload`, `readonly`).
-     */
-    empty?: Snippet<[MediaEmptyController]>;
-};
 /** One allowlisted embed provider: which links it plays, and its player. */
 export type EmbedProvider = {
     /** The provider's name: the frame's `title`. */
@@ -103,12 +164,4 @@ export declare const fileNameOf: (src: string) => string;
 export declare const claimed: (element: HTMLElement, tag: string) => HTMLElement | undefined;
 /** An imported `video`'s or `audio`'s source: its `src`, else its first `source`'s. */
 export declare const mediaSourceOf: (element: HTMLElement | undefined) => string | null;
-/** HTML-escape `value` for an attribute or text of an export. */
-export declare const escapeHtml: (value: string) => string;
-/**
- * Register `type`'s uploads on the view's (`media.files`): with an
- * `upload`, the files it takes (the file kind: any no other kind takes)
- * become its blocks. Answers the paste hook to list, or `undefined`
- * without an `upload` or a view.
- */
-export declare const mediaUploads: (edytor: Edytor | undefined, type: "video" | "audio" | "file", upload: Uploader | undefined) => PluginOperations["onPaste"];
+export { escapeHtml };