@thomasfosterau/prosekit-svelte 0.0.0-stage → 0.1.0

package/dist/toolbar/LinkDialog.svelte

@@ -0,0 +1,113 @@
+<!-- @component The link prompt as a bits-ui modal; the URL is checked with `isSafeHref` before it submits. -->
+
+<!--
+  LinkDialog — the link prompt, as a modal.
+
+  It replaces a `window.prompt` chain. A prompt cannot be styled, cannot be
+  validated before it closes, cannot be cancelled halfway through a
+  two-question sequence without leaving the first answer applied, and is
+  blocked outright in some embedding contexts. The dialog also gives the
+  href somewhere to be checked: `isSafeHref` runs on submit and the failure
+  is announced in a `role="alert"` rather than silently swallowed.
+
+  ARIA contract: bits-ui's. `role="dialog"`, `aria-modal`, the
+  `aria-labelledby` wiring to `Dialog.Title`, the focus trap, Escape, the
+  scroll lock and the focus return to whatever opened it are all its. What is
+  local: the fields, the validity check, the `aria-describedby` from the URL
+  input to the alert, and a `<form>` — so Enter in either input submits,
+  which is what anyone typing a URL expects.
+-->
+<script lang="ts">import { isSafeHref } from "@thomasfosterau/prosekit-utilities";
+import { Dialog } from "bits-ui";
+import { getEditorMessages } from "../messages.svelte.js";
+const messages = getEditorMessages();
+let { open = $bindable(false), href = "", title = "", onSubmit, onRemove, titleLabel = messages.linkDialogTitle, hrefLabel = messages.linkHrefLabel, linkTitleLabel = messages.linkTitleLabel, submitLabel = messages.linkSubmitLabel, removeLabel = messages.linkRemoveLabel, cancelLabel = messages.linkCancelLabel, closeLabel = messages.linkCloseLabel, invalidHrefMessage = messages.linkInvalidHrefMessage, class: className, id, ...rest } = $props();
+const uid = $props.id();
+const hrefId = `${uid}-href`;
+const titleId = `${uid}-title`;
+const errorId = `${uid}-error`;
+let hrefValue = $state("");
+let titleValue = $state("");
+let invalid = $state(false);
+// Seeded on every open, from whatever the caller last set: the toolbar
+// reads the selection's link mark before it opens the dialog, so the form
+// edits the existing link rather than starting blank over the top of one.
+$effect(() => {
+	if (!open) return;
+	hrefValue = href;
+	titleValue = title;
+	invalid = false;
+});
+function submit(event) {
+	event.preventDefault();
+	const candidate = hrefValue.trim();
+	if (!isSafeHref(candidate)) {
+		invalid = true;
+		return;
+	}
+	const trimmedTitle = titleValue.trim();
+	onSubmit({
+		href: candidate,
+		title: trimmedTitle.length > 0 ? trimmedTitle : null
+	});
+	open = false;
+}
+function remove() {
+	onRemove?.();
+	open = false;
+}
+</script>
+
+<Dialog.Root bind:open>
+  <Dialog.Portal>
+    <Dialog.Overlay class="bg-base-300/60 fixed inset-0 z-40" />
+    <Dialog.Content
+      {...rest}
+      {...(id === undefined ? {} : { id })}
+      class={[
+        'modal-box fixed left-1/2 top-1/2 z-50 w-[calc(100vw-2rem)] max-w-md -translate-x-1/2 -translate-y-1/2',
+        className,
+      ]}
+    >
+      <div class="flex items-start justify-between gap-4">
+        <Dialog.Title class="text-lg font-semibold">{titleLabel}</Dialog.Title>
+        <Dialog.Close class="btn btn-sm btn-ghost -mr-1 -mt-1">{closeLabel}</Dialog.Close>
+      </div>
+
+      <form class="mt-4 flex flex-col gap-3" onsubmit={submit}>
+        <label class="flex flex-col gap-1 text-sm" for={hrefId}>
+          {hrefLabel}
+          <input
+            id={hrefId}
+            class="input input-bordered w-full"
+            type="text"
+            bind:value={hrefValue}
+            aria-invalid={invalid ? 'true' : undefined}
+            aria-describedby={invalid ? errorId : undefined}
+          />
+        </label>
+
+        <label class="flex flex-col gap-1 text-sm" for={titleId}>
+          {linkTitleLabel}
+          <input id={titleId} class="input input-bordered w-full" type="text" bind:value={titleValue} />
+        </label>
+
+        {#if invalid}
+          <p id={errorId} role="alert" class="text-error text-sm">{invalidHrefMessage}</p>
+        {/if}
+
+        <div class="modal-action">
+          {#if onRemove}
+            <button type="button" class="btn btn-sm btn-ghost" onclick={remove}>
+              {removeLabel}
+            </button>
+          {/if}
+          <button type="button" class="btn btn-sm btn-ghost" onclick={() => (open = false)}>
+            {cancelLabel}
+          </button>
+          <button type="submit" class="btn btn-sm btn-primary">{submitLabel}</button>
+        </div>
+      </form>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>

package/dist/toolbar/LinkDialog.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'id' | 'title'> {
+    /** The dialog element's `id`. */
+    id?: string | undefined;
+    /** Whether the dialog is shown. Bindable. */
+    open?: boolean | undefined;
+    /** The URL the form opens with — the selection's link, when there is one. */
+    href?: string | undefined;
+    /** The title the form opens with. */
+    title?: string | undefined;
+    /** Called with the accepted attributes when the form is submitted. */
+    onSubmit: (attrs: {
+        href: string;
+        title: string | null;
+    }) => void;
+    /** Called when the remove button is used. Omitted, no remove button. */
+    onRemove?: (() => void) | undefined;
+    /** The dialog's heading, and its accessible name. */
+    titleLabel?: string | undefined;
+    /** Label of the URL field. */
+    hrefLabel?: string | undefined;
+    /** Label of the optional title field. */
+    linkTitleLabel?: string | undefined;
+    /** The submit button. */
+    submitLabel?: string | undefined;
+    /** The remove button. */
+    removeLabel?: string | undefined;
+    /** The cancel button. */
+    cancelLabel?: string | undefined;
+    /** Accessible name of the corner close button. */
+    closeLabel?: string | undefined;
+    /** Announced when the URL is rejected. */
+    invalidHrefMessage?: string | undefined;
+    /** Extra classes on the dialog box. */
+    class?: string | undefined;
+}
+/** The link prompt as a bits-ui modal; the URL is checked with `isSafeHref` before it submits. */
+declare const LinkDialog: import("svelte").Component<Props, {}, "open">;
+type LinkDialog = ReturnType<typeof LinkDialog>;
+export default LinkDialog;

package/dist/toolbar/SlashMenu.svelte

@@ -0,0 +1,112 @@
+<!-- @component The insert menu: a bits-ui `DropdownMenu` of `SlashCommand` entries. `BlockToolbar` renders it; a custom toolbar can too. -->
+
+<!--
+  SlashMenu — the insert menu, on bits-ui's `DropdownMenu`.
+
+  "Slash" is the name the applications this package was extracted from used.
+  There is no `/` trigger inside the document: this is a button that opens a
+  menu of block insertions.
+
+  ARIA contract: bits-ui's. `aria-haspopup="menu"` and `aria-expanded` on the
+  trigger, `role="menu"` on the content, `role="menuitem"` on each entry,
+  arrow-key roving focus, typeahead, Escape to close and focus return. The
+  applications' version was a `role="listbox"` of plain `<button>`s — an
+  invalid parent/child pairing — with no `aria-expanded`, no focus
+  management and no Escape, which is the whole reason this is a bits-ui
+  primitive and not a `{#if}`.
+
+  The daisyUI `menu` styling goes on a `<ul>` INSIDE the content, and that
+  list and its `<li>` wrappers carry `role="none"` so the presentation layer
+  never comes between `role="menu"` and its items in the accessibility tree.
+
+  `BlockToolbar` renders this with its own `Toolbar.Button` as the trigger,
+  so the insert button is a toolbar item like any other. Exported for a
+  custom toolbar that wants the same menu.
+-->
+<script lang="ts">import { DropdownMenu } from "bits-ui";
+import { useEditor } from "prosekit/svelte";
+import { getEditorMessages } from "../messages.svelte.js";
+const messages = getEditorMessages();
+let { commands, open = $bindable(false), label = messages.insertLabel, menuLabel = messages.insertMenuLabel, labelledBy, dialogs, class: className, trigger, id, ...rest } = $props();
+// `update: true` so the store re-emits on every editor state change; the
+// commands are read at the moment they run, not captured. ProseKit hands
+// the editor in as a Svelte store — that is its contract, and the one
+// place this package touches one.
+const editorStore = useEditor({ update: true });
+// Set by `select`, read by `onCloseAutoFocus` below. Closing is what moves
+// focus, and it happens after the handler returns.
+let returnFocusToEditor = false;
+function select(command) {
+	let opening = false;
+	command.run({
+		editor: $editorStore,
+		dialogs: {
+			link: () => {
+				opening = true;
+				dialogs?.link();
+			},
+			image: () => {
+				opening = true;
+				dialogs?.image();
+			}
+		}
+	});
+	// Pulling focus back into the document is right after an insertion and
+	// wrong when a dialog is opening: it would take focus off the dialog
+	// before its trap is set up.
+	returnFocusToEditor = !opening;
+}
+/**
+* Redirects bits-ui's focus return.
+*
+* On close it puts focus back on the trigger, which is right for Escape
+* and wrong after an insertion — the caret belongs where the block just
+* landed. Preventing the default and focusing the document is the
+* primitive's own seam for exactly this.
+*/
+function closeAutoFocus(event) {
+	if (!returnFocusToEditor) return;
+	returnFocusToEditor = false;
+	event.preventDefault();
+	$editorStore.focus();
+}
+</script>
+
+<DropdownMenu.Root bind:open>
+  <DropdownMenu.Trigger>
+    {#snippet child({ props })}
+      {#if trigger}
+        {@render trigger({ props })}
+      {:else}
+        <button {...props} type="button" class="btn btn-sm btn-ghost border-base-300 border">
+          {label}
+        </button>
+      {/if}
+    {/snippet}
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Portal>
+    <DropdownMenu.Content
+      {...rest}
+      {...(id === undefined ? {} : { id })}
+      side="bottom"
+      align="start"
+      sideOffset={6}
+      aria-label={menuLabel}
+      aria-labelledby={labelledBy || undefined}
+      onCloseAutoFocus={closeAutoFocus}
+      class="z-50"
+    >
+      <ul role="none" class={['menu bg-base-100 rounded-box w-56 p-2 shadow-md', className]}>
+        {#each commands as command (command.id)}
+          <li role="none">
+            <DropdownMenu.Item onSelect={() => select(command)}>
+              {#snippet child({ props })}
+                <button {...props} type="button">{command.label}</button>
+              {/snippet}
+            </DropdownMenu.Item>
+          </li>
+        {/each}
+      </ul>
+    </DropdownMenu.Content>
+  </DropdownMenu.Portal>
+</DropdownMenu.Root>

package/dist/toolbar/SlashMenu.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { SlashCommand, ToolbarRunContext } from './items.ts';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'id' | 'dir' | 'aria-label' | 'aria-labelledby'> {
+    /** The menu element's `id`. */
+    id?: string | undefined;
+    /** The entries. */
+    commands: ReadonlyArray<SlashCommand>;
+    /** Whether the menu is open. Bindable. */
+    open?: boolean | undefined;
+    /** Visible text and accessible name of the trigger. */
+    label?: string | undefined;
+    /** Accessible name of the open menu. */
+    menuLabel?: string | undefined;
+    /**
+     * The `id` (or space-separated `id`s) of the visible element that names
+     * the open menu, rendered as `aria-labelledby`. Wins over `menuLabel`,
+     * which stays the fallback name if no element has the id.
+     */
+    labelledBy?: string | undefined;
+    /**
+     * The dialogs a command may ask for. Omitted — a menu mounted outside a
+     * toolbar — `dialogs.link()` / `dialogs.image()` do nothing, and a
+     * command that calls one is inert rather than broken.
+     */
+    dialogs?: ToolbarRunContext['dialogs'] | undefined;
+    /** Extra classes on the `<ul class="menu">`. */
+    class?: string | undefined;
+    /** The opening control — the caller's own element, spreading `props`. */
+    trigger?: Snippet<[{
+        props: Record<string, unknown>;
+    }]> | undefined;
+}
+/** The insert menu: a bits-ui `DropdownMenu` of `SlashCommand` entries. `BlockToolbar` renders it; a custom toolbar can too. */
+declare const SlashMenu: import("svelte").Component<Props, {}, "open">;
+type SlashMenu = ReturnType<typeof SlashMenu>;
+export default SlashMenu;

package/dist/toolbar/items.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The toolbar's data model, and the default sets built from it.
+ *
+ * `BlockToolbar` renders a list rather than a hard-coded row of buttons.
+ * The applications this package was extracted from hard-coded theirs, and
+ * the cost showed: one of them carried five buttons for node types its
+ * grammar no longer had, and neither could add an item without editing the
+ * component. Here an item is a value — an application appends its own,
+ * reorders, drops one, or passes a list of its own making.
+ *
+ * An item's `run` receives a {@link ToolbarRunContext} rather than the
+ * editor alone, because two of the default items open a dialog the toolbar
+ * owns. `dialogs.link()` / `dialogs.image()` are how an item asks for one
+ * without importing it.
+ *
+ * @module
+ */
+import type { CommandAction, Editor, MarkAction, NodeAction } from 'prosekit/core';
+import { type EditorMessages } from '../messages.svelte.ts';
+/**
+ * The editor as a toolbar item sees it: any grammar, with `commands`,
+ * `nodes` and `marks` read by name.
+ *
+ * `Editor` (whose extension type defaults to `any`) cannot be used directly. ProseKit derives those three from
+ * the extension's own typing, and the derivation collapses to `never` for
+ * `any` — so `editor.commands.toggleBold()` in an application's own item
+ * would not compile at all. Widening the three back to records is what makes
+ * a set of items generic over the grammar writable; a real `Editor<E>` is
+ * assignable to it, and an item that names a command the grammar lacks gets
+ * `undefined` rather than a type error, which is the honest outcome.
+ */
+export type ToolbarEditor = Omit<Editor, 'commands' | 'marks' | 'nodes'> & {
+    readonly commands: Record<string, CommandAction>;
+    readonly marks: Record<string, MarkAction>;
+    readonly nodes: Record<string, NodeAction>;
+};
+/**
+ * What a toolbar item's `run` is handed.
+ *
+ * `editor` is the live editor from the enclosing `<ProseKit>`; `dialogs`
+ * opens one of the toolbar's own dialogs. Calling a dialog opener also tells
+ * the toolbar not to pull focus back into the document, which would take it
+ * straight off the dialog that is about to open.
+ */
+export interface ToolbarRunContext {
+    /** The editor the toolbar is attached to. */
+    readonly editor: ToolbarEditor;
+    /** The dialogs the toolbar renders, for items that need one. */
+    readonly dialogs: {
+        /** Opens the link dialog, seeded from the selection's link mark. */
+        readonly link: () => void;
+        /** Opens the image dialog. */
+        readonly image: () => void;
+    };
+}
+/**
+ * One button of {@link BlockToolbar}.
+ *
+ * `kind: 'toggle'` is what makes the button carry `aria-pressed`; an action
+ * (insert a rule, open a dialog, undo) has no pressed state and must not
+ * claim one. `isActive` is read on every editor update, so it must be cheap
+ * and must not throw when the schema lacks the node or mark it asks about.
+ */
+export interface ToolbarItem {
+    /** Stable key for the `{#each}` and for an application replacing an item. */
+    readonly id: string;
+    /** Visible text and accessible name. */
+    readonly label: string;
+    /** `'toggle'` renders `aria-pressed`; `'action'` (the default) does not. */
+    readonly kind?: ('toggle' | 'action') | undefined;
+    /** Whether the item's state is on. Only read for `kind: 'toggle'`. */
+    readonly isActive?: ((editor: ToolbarEditor) => boolean) | undefined;
+    /** Whether the item can be used. `false` renders a `disabled` button. */
+    readonly isEnabled?: ((editor: ToolbarEditor) => boolean) | undefined;
+    /** What the button does. */
+    readonly run: (context: ToolbarRunContext) => void;
+}
+/**
+ * A divider between groups of items, allowed anywhere in `items`.
+ *
+ * It renders as `role="separator"` and is skipped by the toolbar's arrow-key
+ * navigation — a separator is a landmark for the eye, not a stop for the
+ * keyboard.
+ */
+export interface ToolbarSeparator {
+    /** Stable key for the `{#each}`. */
+    readonly id: string;
+    /** The discriminant. */
+    readonly separator: true;
+}
+/** One entry of the insert menu. */
+export interface SlashCommand {
+    /** Stable key for the `{#each}`. */
+    readonly id: string;
+    /** Visible text and accessible name. */
+    readonly label: string;
+    /** What choosing the entry does. */
+    readonly run: (context: ToolbarRunContext) => void;
+}
+/** Narrows an `items` entry to the separator arm. */
+export declare function isToolbarSeparator(entry: ToolbarItem | ToolbarSeparator): entry is ToolbarSeparator;
+/**
+ * The default toolbar: the nineteen items the applications shipped, in their
+ * order, with two separators marking the mark / block / history groups.
+ *
+ * The twentieth control those toolbars carried was a button that toggled an
+ * ad-hoc "slash" panel; it is the insert menu now, and `BlockToolbar`
+ * renders it itself from {@link createDefaultSlashCommands}.
+ *
+ * Every `run` goes through the editor's own `commands`, `marks` and `nodes`,
+ * so the set works against any extension that registers those node and mark
+ * types and quietly does nothing against one that does not.
+ *
+ * @param messages - Labels to use instead of the English defaults. A partial
+ *   record; unlisted keys keep their default.
+ */
+export declare function createDefaultToolbarItems(messages?: Partial<EditorMessages>): ReadonlyArray<ToolbarItem | ToolbarSeparator>;
+/**
+ * The default insert menu: the ten entries the applications shipped, in
+ * their order.
+ *
+ * @param messages - Labels to use instead of the English defaults. A partial
+ *   record; unlisted keys keep their default.
+ */
+export declare function createDefaultSlashCommands(messages?: Partial<EditorMessages>): ReadonlyArray<SlashCommand>;