wiki-formant 0.42.0 → 0.44.0

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.
@@ -775,8 +785,8 @@ monthly.
 ```
 
 A price point may carry `open`, `high` and `low` (its `value` is the close)
-and `volume`. Points that carry the candle get a Line/Candles toggle, opening on
-candles with `candles`; points that carry volume get a volume pane under the
+and `volume`. Points that carry the candle get a candles switch, a candlestick icon
+pressed while they show, opening on candles with `candles`; points that carry volume get a volume pane under the
 price, a fifth of the height. Candles take `--chart-up` and `--chart-down` from
 the canvas box, else its `color`. A week of candles opens on its first, closes
 on its last, spans the highest high and lowest low, and sums its volume. A point

package/dist/base.css

@@ -191,8 +191,10 @@ pre:hover > .code-copy-btn,
 }
 .chart-controls > div { display: flex; gap: 2px; }
 .chart-controls :is(button, a) { font: inherit; color: inherit; text-decoration: none; background: none; cursor: pointer; opacity: 0.6; }
+/* An icon sits on the text's line, so an icon button is as tall as a labelled one. */
+.chart-icon { display: inline-block; width: 1em; height: 1em; vertical-align: -0.125em; }
 /* A button is pressed; a link (a stats page's window) is the page shown. */
-.chart-controls :is([aria-pressed='true'], [aria-current]) { opacity: 1; }
+.chart-controls :is(button, a):is([aria-pressed='true'], [aria-current]) { opacity: 1; }
 
 /* ---- Stats ----------------------------------------------------------------
    `--share` is a row's value over the largest in its list, 0 to 1. Bars take

package/dist/chart.d.ts

@@ -49,7 +49,7 @@ export interface TimeChartProps {
     fromZero?: boolean;
     /** The value axis and crosshair label. Read on every draw, so it need not be stable. */
     format?: (n: number) => string;
-    /** Open on candles, where the points carry them. A Line/Candles toggle shows either way. */
+    /** Open on candles, where the points carry them. A candles toggle shows either way. */
     candles?: boolean;
     /** In pixels. Otherwise the stylesheet's `--chart-height`, else 15rem. */
     height?: number;

package/dist/chart.js

@@ -261,5 +261,5 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         c.api.timeScale().fitContent();
     }, [ready, source, view, candles]);
     const status = source && 'error' in source ? source.error : points && !view?.shown.length ? 'No data in this range' : null;
-    return (_jsxs("figure", { className: className ? `chart ${className}` : 'chart', children: [_jsx("div", { ref: box, className: "chart-canvas", role: "img", "aria-label": label, style: height ? { height } : undefined }), (!ready || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (controls || ranges.length > 1 || (view && (view.steps.length > 1 || view.ohlc))) && (_jsxs("div", { className: "chart-controls", children: [controls, ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => { setRange(r); setStep(null); }, children: RANGE[r].label }, r))) })), view && view.steps.length > 1 && (_jsx("div", { role: "group", "aria-label": "Step", children: view.steps.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view.step, onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) })), view?.ohlc && (_jsxs("div", { role: "group", "aria-label": "Style", children: [_jsx("button", { type: "button", "aria-pressed": !candles, onClick: () => setCandles(false), children: "Line" }), _jsx("button", { type: "button", "aria-pressed": candles, onClick: () => setCandles(true), children: "Candles" })] }))] }))] }));
+    return (_jsxs("figure", { className: className ? `chart ${className}` : 'chart', children: [_jsx("div", { ref: box, className: "chart-canvas", role: "img", "aria-label": label, style: height ? { height } : undefined }), (!ready || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (controls || ranges.length > 1 || (view && (view.steps.length > 1 || view.ohlc))) && (_jsxs("div", { className: "chart-controls", children: [controls, ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => { setRange(r); setStep(null); }, children: RANGE[r].label }, r))) })), view && view.steps.length > 1 && (_jsx("div", { role: "group", "aria-label": "Step", children: view.steps.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view.step, onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) })), view?.ohlc && (_jsx("div", { children: _jsx("button", { type: "button", "aria-pressed": candles, "aria-label": "Candles", title: "Candles", onClick: () => setCandles(c => !c), children: _jsxs("svg", { className: "chart-icon", viewBox: "0 0 12 12", "aria-hidden": true, children: [_jsx("path", { d: "M3.5 1v2M3.5 9v2M8.5 2v3M8.5 9v1", stroke: "currentColor" }), _jsx("rect", { x: "2", y: "3", width: "3", height: "6", rx: "0.5", fill: "currentColor" }), _jsx("rect", { x: "7", y: "5", width: "3", height: "4", rx: "0.5", fill: "currentColor" })] }) }) }))] }))] }));
 }

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

@@ -212,6 +212,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 }`

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.42.0",
+  "version": "0.44.0",
   "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",