wiki-formant 0.43.0 → 0.44.1

package/README.md

@@ -312,6 +312,8 @@ const { ref, onScroll, at, step, go } = useSnapRow();
 
 `useClickOutside` is fifteen lines and was in all three. Only one had the `offsetParent` check, and without it a container hidden at the current breakpoint still answers outside-clicks — so on a phone, a tap anywhere dismisses the popover the reader is looking at, because the hidden desktop copy got there first.
 
+`useUnsavedChanges(dirty)` asks before an edit with unsaved changes is left: the browser's own prompt on a reload or a closed tab, and the `confirmLeave()` it returns for a Back link or Cancel, which a client-side navigation never sends through `beforeunload`. If a save leaves by a full page load, pass false once it has landed, or the save's own exit asks. `useSaveShortcut(save)` binds ⌘S and Ctrl+S, reading `save` when the key is pressed.
+
 ### The listbox contract
 
 `useTypeahead` shared the state machine across five surfaces and left the ARIA
@@ -625,6 +627,14 @@ The ones that take config take it because that is exactly where the two copies d
 
 `TOOLBAR_ACTIONS` are the formatting commands with the labels a screen reader announces — two toolbars titled buttons with the internal key, so one said "codeBlock". Pick yours in order with `toolbarActions([...])`, render each through `ToolbarButton` (named, and `aria-pressed`, since these are toggles), and run a table command with `runTableAction`. Upload and embed stay with the caller; they are the parts that differ.
 
+`useUrlPrompt(editor, { resolveMapUrl })` is the link and embed address field under a toolbar, in place of a `window.prompt` that blocks the page and cannot show the link the cursor is in. Three editors had written it and one still used the prompt; only one copy both opened a link field on the current address and unlinked on an emptied one. The hook carries both, closes the field when the editor it serves changes (a toolbar shared between blocks would otherwise apply it to the wrong one), and leaves the markup to you. `applyUrlPrompt` is what it runs, exported for a toolbar that keeps its own state.
+
+```tsx
+const url = useUrlPrompt(editor, { resolveMapUrl });
+<ToolbarButton label="Link" pressed={url.kind === 'link'} onPress={() => url.toggle('link')}>…</ToolbarButton>
+{url.kind && <input autoFocus value={url.value} onChange={e => url.setValue(e.target.value)} onKeyDown={url.onKeyDown} />}
+```
+
 A link is stored as its `href` and the `link` class, nothing else (`wikiLink`). Stock Tiptap writes `target="_blank" rel="noopener noreferrer nofollow"` onto every link, internal ones included, which on a site throws away its own link equity and opens in-site navigation in new tabs. Whether a link is external depends on the host serving the page, so `normaliseLinks` decides it at render time. A legacy link loses both attributes the next time its page is saved.
 
 The redirect resolves through the wiki's own route, because the editor cannot read it cross-origin. `resolveMapUrl` is the client half and `resolveMapHandler` the whole route: exact shortener hosts, one hop, an allowlisted landing host, a timeout, and your sign-in check as `authorize`. One of the two copies it replaced matched `goo.gl` as a substring and followed every redirect for anyone who asked.

package/dist/editor.d.ts

@@ -1,5 +1,5 @@
 import type { AnyExtension, Editor } from '@tiptap/core';
-import { type ChangeEvent, type ReactNode, type RefObject } from 'react';
+import { type ChangeEvent, type KeyboardEvent, type ReactNode, type RefObject } from 'react';
 /**
  * Re-exported so the COMMAND AUGMENTATIONS reach consumers.
  *
@@ -91,6 +91,43 @@ export declare function ToolbarButton({ label, pressed, onPress, className, chil
     className?: string;
     children: ReactNode;
 }): import("react").JSX.Element;
+export type UrlPromptKind = 'link' | 'embed';
+/**
+ * What a link or embed field does with its address. A link sets or replaces
+ * the link the cursor is in, across the whole link rather than the collapsed
+ * selection, and an emptied address takes it off while keeping the text. An
+ * embed with no address does nothing.
+ */
+export declare function applyUrlPrompt(editor: Editor, kind: UrlPromptKind, url: string, { resolveMapUrl }: {
+    resolveMapUrl: (url: string) => Promise<string | null>;
+}): void;
+export interface UrlPromptState {
+    /** The open field, or null. */
+    kind: UrlPromptKind | null;
+    value: string;
+    setValue: (value: string) => void;
+    /** Open the field, or close it when it is already open on this kind. */
+    toggle: (kind: UrlPromptKind) => void;
+    close: () => void;
+    /** `applyUrlPrompt` with the field's address, then close. */
+    apply: () => void;
+    /** Enter applies and Escape closes: the field's `onKeyDown`. */
+    onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
+}
+/**
+ * The state of a link or embed address field under a toolbar, in place of a
+ * `window.prompt`, which blocks the page and cannot show the link the cursor is
+ * already in. Three editors had written this, and only one had both of what it
+ * needs: a link field that opens on the current address, and an emptied one
+ * that unlinks. The field closes when the editor it serves changes, since a
+ * toolbar shared between blocks would otherwise apply it to the wrong one.
+ *
+ * The markup stays with the caller: an input bound to `value`, `setValue` and
+ * `onKeyDown`, and buttons calling `apply` and `close`.
+ */
+export declare function useUrlPrompt(editor: Editor | null, options: {
+    resolveMapUrl: (url: string) => Promise<string | null>;
+}): UrlPromptState;
 /**
  * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
  * back. Two editors carried it character for character, `alert` included.

package/dist/editor.js

@@ -15,6 +15,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 //   2. Blur flushes the pending debounce. The change is debounced 150ms, and
 //      clicking Save blurs the editor before the click lands, so without the
 //      flush the final keystroke of an edit that ends in a click is dropped.
+//      It flushes only an edit still pending: Tiptap rewrites stored HTML into
+//      its own form, so reporting every blur told a page that had only been
+//      clicked through it had unsaved changes.
 //
 // Every @tiptap package here is an OPTIONAL PEER. A consumer that only wants
 // the taxonomy or the MCP transport installs none of them.
@@ -212,6 +215,67 @@ export function toolbarActions(keys) {
 export function ToolbarButton({ label, pressed, onPress, className, children, }) {
     return (_jsx("button", { type: "button", title: label, "aria-label": label, "aria-pressed": pressed, className: className, onClick: onPress, children: children }));
 }
+/**
+ * What a link or embed field does with its address. A link sets or replaces
+ * the link the cursor is in, across the whole link rather than the collapsed
+ * selection, and an emptied address takes it off while keeping the text. An
+ * embed with no address does nothing.
+ */
+export function applyUrlPrompt(editor, kind, url, { resolveMapUrl }) {
+    const href = url.trim();
+    if (kind === 'embed') {
+        if (href)
+            insertEmbed(editor, href, { resolveMapUrl });
+        return;
+    }
+    const chain = editor.chain().focus().extendMarkRange('link');
+    (href ? chain.setLink({ href }) : chain.unsetLink()).run();
+}
+/**
+ * The state of a link or embed address field under a toolbar, in place of a
+ * `window.prompt`, which blocks the page and cannot show the link the cursor is
+ * already in. Three editors had written this, and only one had both of what it
+ * needs: a link field that opens on the current address, and an emptied one
+ * that unlinks. The field closes when the editor it serves changes, since a
+ * toolbar shared between blocks would otherwise apply it to the wrong one.
+ *
+ * The markup stays with the caller: an input bound to `value`, `setValue` and
+ * `onKeyDown`, and buttons calling `apply` and `close`.
+ */
+export function useUrlPrompt(editor, options) {
+    const [state, setState] = useState(null);
+    const latest = useRef({ editor, state, options });
+    useEffect(() => {
+        latest.current = { editor, state, options };
+    });
+    useEffect(() => setState(null), [editor]);
+    const toggle = useCallback((kind) => {
+        const { editor, state } = latest.current;
+        if (state?.kind === kind)
+            return setState(null);
+        const href = kind === 'link' ? editor?.getAttributes('link').href : undefined;
+        setState({ kind, value: href ?? '' });
+    }, []);
+    const close = useCallback(() => setState(null), []);
+    const setValue = useCallback((value) => setState(s => (s ? { ...s, value } : s)), []);
+    const apply = useCallback(() => {
+        const { editor, state, options } = latest.current;
+        if (editor && state)
+            applyUrlPrompt(editor, state.kind, state.value, options);
+        setState(null);
+    }, []);
+    const onKeyDown = useCallback((e) => {
+        if (e.key === 'Enter') {
+            e.preventDefault();
+            apply();
+        }
+        else if (e.key === 'Escape') {
+            e.preventDefault();
+            close();
+        }
+    }, [apply, close]);
+    return { kind: state?.kind ?? null, value: state?.value ?? '', setValue, toggle, close, apply, onKeyDown };
+}
 // ---- the editor -------------------------------------------------------------
 /**
  * An `uploadImage` that POSTs the file as `file` form data and reads `{ url }`
@@ -250,6 +314,9 @@ export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], p
     const initialValueRef = useRef(value);
     const onChangeRef = useRef(onChange);
     const debounceRef = useRef(undefined);
+    // An edit made and not yet reported. `onUpdate` fires for edits only, never
+    // for the `setContent` that loads the stored value.
+    const pendingRef = useRef(false);
     // Written AFTER render, not during: a ref mutated mid-render can tear under
     // concurrent rendering. Only read from events and timeouts, which run later.
     useEffect(() => {
@@ -267,12 +334,20 @@ export function useWikiEditor({ value, onChange, placeholder = '', nodes = [], p
         },
         onUpdate: ({ editor }) => {
             clearTimeout(debounceRef.current);
-            debounceRef.current = setTimeout(() => onChangeRef.current(editor.getHTML()), debounceMs);
+            pendingRef.current = true;
+            debounceRef.current = setTimeout(() => {
+                pendingRef.current = false;
+                onChangeRef.current(editor.getHTML());
+            }, debounceMs);
         },
-        // Flush the pending debounce on blur, so a quick Save — which blurs the
-        // editor before the click fires — never drops the final keystroke.
+        // Flush a pending edit on blur, so a quick Save — which blurs the editor
+        // before the click fires — never drops the final keystroke. A blur with no
+        // edit reports nothing.
         onBlur: ({ editor }) => {
             clearTimeout(debounceRef.current);
+            if (!pendingRef.current)
+                return;
+            pendingRef.current = false;
             onChangeRef.current(editor.getHTML());
         },
         immediatelyRender: false,

package/dist/react.d.ts

@@ -315,6 +315,21 @@ export interface BlockActionsProps {
  * for a bar without it.
  */
 export declare function BlockActions({ index, total, ops, icons, className, buttonClassName, blockLabel }: BlockActionsProps): import("react").JSX.Element;
+/**
+ * Asks before an edit with unsaved changes is left. While `dirty`, a reload or
+ * a closed tab gets the browser's own prompt; an in-app exit (a Back link,
+ * Cancel) never passes through `beforeunload`, so it asks `confirmLeave()`,
+ * the function this returns, and goes only on a true.
+ *
+ * Pass false once a save has landed if the page then leaves by a full load
+ * (`location.href = …`), or the save's own exit asks the question.
+ */
+export declare function useUnsavedChanges(dirty: boolean, message?: string): () => boolean;
+/**
+ * ⌘S, or Ctrl+S, runs `save` in place of the browser saving the page as a
+ * file. `save` is read when the key is pressed, so it may close over state.
+ */
+export declare function useSaveShortcut(save: () => void): void;
 /** Resolves to an error message to show, or null on success. */
 export type RestoreRevision<Id> = (id: Id) => Promise<string | null>;
 /**

package/dist/react.js

@@ -615,6 +615,46 @@ export function BlockActions({ index, total, ops, icons, className, buttonClassN
         }, children: icon }));
     return (_jsxs("span", { className: className, children: [button(name('Move', ' up'), icons.up, () => ops.move(index, index - 1), index === 0), button(name('Move', ' down'), icons.down, () => ops.move(index, index + 1), index === total - 1), icons.duplicate !== undefined && button(name('Duplicate'), icons.duplicate, () => ops.duplicate(index)), button(name('Delete'), icons.remove, () => ops.remove(index))] }));
 }
+// ---- leaving an edit ---------------------------------------------------------
+/**
+ * Asks before an edit with unsaved changes is left. While `dirty`, a reload or
+ * a closed tab gets the browser's own prompt; an in-app exit (a Back link,
+ * Cancel) never passes through `beforeunload`, so it asks `confirmLeave()`,
+ * the function this returns, and goes only on a true.
+ *
+ * Pass false once a save has landed if the page then leaves by a full load
+ * (`location.href = …`), or the save's own exit asks the question.
+ */
+export function useUnsavedChanges(dirty, message = 'Leave without saving your changes?') {
+    useEffect(() => {
+        if (!dirty)
+            return;
+        const warn = (e) => e.preventDefault();
+        window.addEventListener('beforeunload', warn);
+        return () => window.removeEventListener('beforeunload', warn);
+    }, [dirty]);
+    return useCallback(() => !dirty || window.confirm(message), [dirty, message]);
+}
+/**
+ * ⌘S, or Ctrl+S, runs `save` in place of the browser saving the page as a
+ * file. `save` is read when the key is pressed, so it may close over state.
+ */
+export function useSaveShortcut(save) {
+    const latest = useRef(save);
+    useEffect(() => {
+        latest.current = save;
+    });
+    useEffect(() => {
+        const onKey = (e) => {
+            if ((e.metaKey || e.ctrlKey) && !e.altKey && e.key.toLowerCase() === 's') {
+                e.preventDefault();
+                latest.current();
+            }
+        };
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, []);
+}
 /**
  * POST `{ revisionId }` to `endpoint`, the transport two of the wikis use; the
  * third passes its server action instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.43.0",
+  "version": "0.44.1",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",