@openleaf-editor/ui 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/toolbar.d.ts

@@ -13,13 +13,16 @@
  *
  * Two details that are easy to get wrong and both matter:
  *
- * 1. **Arrow-key roving is applied only to `<button>` elements.** The block-type
- *    control is a native `<select>`, and when focus is on it, Left/Right have two
- *    competing owners -- the roving handler wants to move to the next item, the
- *    select natively wants to change its value. Intercepting those keys breaks
- *    the select; not intercepting them breaks the toolbar contract. The
- *    resolution is that the select owns all of its own key events and is a
- *    genuine second tab stop rather than part of the roving scheme.
+ * 1. **Arrow-key roving covers the `<select>` controls too.** The default bar has
+ *    four of them -- paragraph style, font family, font size, line height -- and
+ *    when focus is on one, Left/Right have two competing owners: the roving
+ *    handler wants to move to the next item, the select natively wants to change
+ *    its value. Leaving them out was the earlier resolution, and it cost more
+ *    than it saved: ArrowRight from Redo jumped past four controls to Bold, and
+ *    each select became its own tab stop, making the default bar five tab stops
+ *    instead of one. The APG resolution is the one used here -- the toolbar takes
+ *    Left/Right, and Up/Down, Home/End and typeahead are left to the select, so
+ *    it is still fully operable and Alt+Down still opens its list.
  *
  * 2. **Escape returns focus and the selection to the content.** Preventing mouse
  *    clicks from stealing focus solves the mouse case and leaves the keyboard
@@ -28,6 +31,7 @@
  *    is blind-Tabbing through the rest of the host's form. `Alt+F10` enters,
  *    Escape leaves, matching TinyMCE and CKEditor 5 so muscle memory transfers.
  */
+import { type FormatSpec } from '@openleaf-editor/core';
 import type { EditorState, Transaction } from 'prosemirror-state';
 import type { EditorView } from 'prosemirror-view';
 export interface ToolbarOptions {
@@ -35,23 +39,98 @@ export interface ToolbarOptions {
     label?: string;
     /** Space-separated item ids, `|` for a separator. */
     layout?: string;
+    /**
+     * Collapse groups that do not fit into a More menu. Off by default: wrapping
+     * keeps every control visible, which is the safer accessibility default.
+     */
+    overflow?: boolean;
+    /** Extra block formats, typically classes from the host's content CSS. */
+    formats?: readonly FormatSpec[];
+    /**
+     * Language for this toolbar's labels, independent of every other editor's.
+     * Absent means the document-wide locale.
+     */
+    locale?: string | null;
+}
+/**
+ * What a host or a plugin actually needs from a toolbar.
+ *
+ * Published instead of the `Toolbar` class itself. The documented need is
+ * `setItemState` -- pushing state no predicate can derive, such as an upload in
+ * flight -- and the keyboard entry point; exposing the class froze its whole
+ * surface, private fields and rendering internals included, into the public API
+ * before 1.0.
+ */
+export interface ToolbarHandle {
+    /** Force a control's state, overriding its `isActive`/`isEnabled` predicate. */
+    setItemState(id: string, state: {
+        active?: boolean;
+        enabled?: boolean;
+    }): void;
+    /** Move focus into the bar, as Alt+F10 does. */
+    focusToolbar(): void;
 }
 export declare class Toolbar {
     #private;
     readonly el: HTMLDivElement;
     constructor(host: HTMLElement, doc: Document, options?: ToolbarOptions);
+    /**
+     * Change this toolbar's language and rebuild its labels.
+     *
+     * Per toolbar rather than per document, so one editor switching language does
+     * not relabel every other editor on the page.
+     */
+    setLocale(next: string | null): void;
+    /**
+     * Enter or leave source view.
+     *
+     * Every control except the one that leaves again goes unavailable. In source
+     * mode a formatting command ran against the hidden document and the textarea
+     * was then reparsed over the top of it, so pressing Bold silently discarded
+     * the edit -- a button that does nothing is better than a button that
+     * destroys work, and a button that says it is unavailable is better still.
+     */
+    setSourceMode(active: boolean): void;
     /** Attach to a view and build the controls. */
     mount(view: EditorView): void;
+    /**
+     * Detach the toolbar AND take its DOM with it.
+     *
+     * Removing the nodes is part of the contract, not tidiness. The host appends
+     * `el` into the editor element and reads that element's
+     * `innerHTML` back as document content when it rebuilds -- so a toolbar left
+     * behind by `destroy()` becomes the author's document on the next build, and
+     * then gets posted to the server.
+     *
+     * Idempotent: `.remove()` on a detached node is a no-op.
+     */
     destroy(): void;
-    /** The live region element, which the host mounts once. */
+    /**
+     * The editor's live region.
+     *
+     * One per host, shared by every bar on it, and already mounted -- so a host
+     * that appends this is moving a node it already owns rather than adopting a
+     * detached one. Kept on the class because integrations reach for it.
+     */
     get liveRegion(): HTMLDivElement;
     /**
      * Reflect the editor state onto the controls.
      *
-     * Deliberately synchronous, not batched into an animation frame. Twenty cheap
-     * predicates plus a diffed attribute write is sub-millisecond work, and
-     * batching would trade a perceptible frame of lag between pressing Bold and
-     * the button lighting up for a performance problem that does not exist.
+     * Deliberately synchronous, not batched into an animation frame: batching
+     * would put a perceptible frame of lag between pressing Bold and the button
+     * lighting up.
+     *
+     * This used to claim the predicates were "sub-millisecond work" and that the
+     * performance problem "does not exist". It did. Every control without an
+     * `isEnabled` is probed by dry-running its command, each of which walks the
+     * selection, and a page routinely carries four bars over one editor -- so a
+     * Select-All on a hundred-page document measured 1.4 ms per bar and about
+     * 3 ms per pointermove during a selection drag, inside `dispatchTransaction`.
+     * What makes synchronous affordable is the three guards below it: skipping
+     * transactions that cannot have changed an answer, caching each answer per
+     * state so the four bars share one computation, and giving the alignment items
+     * an explicit `isEnabled` so they stop dry-running a command that walks the
+     * selection twice.
      *
      * `tr` is passed so announcements can be gated on a real formatting change.
      */

package/dist/toolbar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolbar.d.ts","sourceRoot":"","sources":["../src/toolbar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAWlD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAuDD,qBAAa,OAAO;;IAClB,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;gBAgBf,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,GAAE,cAAmB;IA8B1E,+CAA+C;IAC/C,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAM7B,OAAO,IAAI,IAAI;IA6Bf,2DAA2D;IAC3D,IAAI,UAAU,IAAI,cAAc,CAE/B;IAiSD;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI;IAgElD;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IA8F9E,iEAAiE;IACjE,YAAY,IAAI,IAAI;IAYpB,mEAAmE;IACnE,oBAAoB,IAAI,IAAI;CAG7B"}
+{"version":3,"file":"toolbar.d.ts","sourceRoot":"","sources":["../src/toolbar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAclD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IAC9E,gDAAgD;IAChD,YAAY,IAAI,IAAI,CAAA;CACrB;AAmHD,qBAAa,OAAO;;IAClB,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;gBAmCf,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,GAAE,cAAmB;IAoC1E;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAOpC;;;;;;;;OAQG;IACH,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAMpC,+CAA+C;IAC/C,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAc7B;;;;;;;;;;OAUG;IACH,OAAO,IAAI,IAAI;IA+Bf;;;;;;OAMG;IACH,IAAI,UAAU,IAAI,cAAc,CAE/B;IAyTD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI;IAgOlD;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IA0G9E,iEAAiE;IACjE,YAAY,IAAI,IAAI;IAYpB,mEAAmE;IACnE,oBAAoB,IAAI,IAAI;CAG7B"}