stilo-editor 0.0.0-stage → 0.2.0

package/dist/ui/components/character-picker.d.ts

@@ -0,0 +1,22 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** Options of {@link createCharacterPicker}. */
+export interface CharacterPickerOptions {
+    /** The toolbar button that opens the picker. */
+    anchor: HTMLElement;
+    /** The element the picker scrolls with: the toolbar. */
+    container: HTMLElement;
+    messages: Messages;
+}
+/** The special characters and emoji picker; it stays open after each insertion. */
+export interface CharacterPicker {
+    readonly isOpen: boolean;
+    /** Opens the picker, loading its data the first time; the focus goes to the search field. */
+    open(): Promise<void>;
+    /** Closes the picker and gives the focus back to the editor. */
+    close(): void;
+    toggle(): void;
+    destroy(): void;
+}
+/** Creates the character picker (closed), anchored to the toolbar button. */
+export declare function createCharacterPicker(editor: Editor, options: CharacterPickerOptions): CharacterPicker;

package/dist/ui/components/characters.d.ts

@@ -0,0 +1,10 @@
+import type { MessageKey } from '../i18n/types';
+/** A category of the character picker: its label and its characters with their names. */
+export interface CharacterCategory {
+    labelKey: MessageKey;
+    characters: ReadonlyArray<readonly [character: string, name: string]>;
+}
+/** Special characters, by category. */
+export declare const SYMBOLS: readonly CharacterCategory[];
+/** Emoji, by category. */
+export declare const EMOJI: readonly CharacterCategory[];

package/dist/ui/components/color-button.d.ts

@@ -0,0 +1,23 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+import type { ToolbarColorButton } from '../toolbar/types';
+/** Options of {@link createColorButton}. */
+export interface ColorButtonOptions {
+    /** The element the popover scrolls with: the toolbar. */
+    container: HTMLElement;
+    messages: Messages;
+}
+/** A color split button and its popover (T-026). */
+export interface ColorButton {
+    /** The wrapper of the two parts. */
+    readonly element: HTMLElement;
+    /** Applies the last used color. */
+    readonly main: HTMLButtonElement;
+    /** Opens the popover. */
+    readonly arrow: HTMLButtonElement;
+    /** Refreshes the enabled and pressed states. */
+    update(): void;
+    destroy(): void;
+}
+/** Creates the split button of `item` and its popover (closed), mounted in `container`. */
+export declare function createColorButton(editor: Editor, item: ToolbarColorButton, options: ColorButtonOptions): ColorButton;

package/dist/ui/components/dropdown.d.ts

@@ -0,0 +1,34 @@
+import { type IconNode } from 'lucide';
+/** One option as displayed: label and shortcut already resolved and formatted. */
+export interface DropdownOptionView {
+    id: string;
+    label: string;
+    shortcut?: string;
+    /** The label is drawn in this font family. */
+    fontFamily?: string;
+    /** An action (`menuitem`), never checked; otherwise a `menuitemradio`. */
+    action?: boolean;
+}
+export interface DropdownOptions {
+    /** Accessible name of the trigger and of the menu; shown when no option is active. */
+    label: string;
+    options: DropdownOptionView[];
+    /** Shown by the trigger instead of the value; the value stays in its accessible name. */
+    icon?: IconNode;
+    /** The popover container (the toolbar element). */
+    container: HTMLElement;
+    onSelect(id: string): void;
+}
+export interface DropdownState {
+    activeId: string | null;
+    disabledIds: ReadonlySet<string>;
+    /** Shown by the trigger when no option is active; default: the dropdown label. */
+    valueLabel?: string | null;
+}
+export interface Dropdown {
+    /** The trigger button; the toolbar inserts it in its group. */
+    readonly trigger: HTMLButtonElement;
+    update(state: DropdownState): void;
+    destroy(): void;
+}
+export declare function createDropdown(options: DropdownOptions): Dropdown;

package/dist/ui/components/find-bar.d.ts

@@ -0,0 +1,24 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** Options of {@link createFindBar}. */
+export interface FindBarOptions {
+    /** The find bar is appended inside it, after the toolbar. */
+    container: HTMLElement;
+    messages: Messages;
+    /** The toolbar button that toggles the bar: it gets `aria-expanded`. */
+    button?: HTMLElement | null;
+}
+/** The find and replace bar (T-043). */
+export interface FindBar {
+    readonly element: HTMLElement;
+    readonly isOpen: boolean;
+    /** Shows the bar and focuses the find field, prefilled with the selected text. */
+    open(): void;
+    /** Hides the bar, clears the search and gives the focus back to the editor. */
+    close(): void;
+    /** Closes the bar when it is open, otherwise opens it. */
+    toggle(): void;
+    destroy(): void;
+}
+/** Creates the find bar (hidden). */
+export declare function createFindBar(editor: Editor, options: FindBarOptions): FindBar;

package/dist/ui/components/font-size-input.d.ts

@@ -0,0 +1,21 @@
+import { type Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+import type { ToolbarFontSizeInput } from '../toolbar/types';
+/** Options of {@link createFontSizeInput}. */
+export interface CreateFontSizeInputOptions {
+    /** The element the list scrolls with: the toolbar. */
+    container: HTMLElement;
+    messages: Messages;
+}
+/** The font size control and its list (T-038). */
+export interface FontSizeInput {
+    /** The wrapper of the three parts. */
+    readonly element: HTMLElement;
+    /** The toolbar items, in order: decrease, field, increase. */
+    readonly parts: readonly HTMLElement[];
+    /** Shows the size at the selection and refreshes the enabled state. */
+    update(): void;
+    destroy(): void;
+}
+/** Creates the font size control of `item` (list closed); the list is mounted in `container`. */
+export declare function createFontSizeInput(editor: Editor, item: ToolbarFontSizeInput, options: CreateFontSizeInputOptions): FontSizeInput;

package/dist/ui/components/icon-menu.d.ts

@@ -0,0 +1,20 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+import type { ToolbarIconMenu } from '../toolbar/types';
+/** Options of {@link createIconMenu}. */
+export interface IconMenuOptions {
+    /** The element the menu scrolls with: the toolbar. */
+    container: HTMLElement;
+    messages: Messages;
+    /** Whether shortcuts are shown with Mac symbols. */
+    mac: boolean;
+}
+/** A button that shows the icon of the active option and opens the options in a row (T-039). */
+export interface IconMenu {
+    readonly trigger: HTMLButtonElement;
+    /** Shows the active option and refreshes the enabled states. */
+    update(): void;
+    destroy(): void;
+}
+/** Creates the trigger of `item` and its menu (closed), mounted in `container`. */
+export declare function createIconMenu(editor: Editor, item: ToolbarIconMenu, options: IconMenuOptions): IconMenu;

package/dist/ui/components/icon.d.ts

@@ -0,0 +1,3 @@
+import type { IconNode } from 'lucide';
+/** An SVG element for a lucide icon, with class `stilo-icon` and `aria-hidden="true"`. */
+export declare function createIcon(icon: IconNode): SVGElement;

package/dist/ui/components/link-bubble.d.ts

@@ -0,0 +1,19 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** Options of {@link createLinkBubble}. */
+export interface LinkBubbleOptions {
+    /** The element the bubble scrolls with: the parent of the editable element. */
+    container: HTMLElement;
+    messages: Messages;
+    /** Called by the edit button (the toolbar opens the link popover). */
+    onEdit(): void;
+}
+/** The link bubble: shown under the link at the cursor while the editor has the focus. */
+export interface LinkBubble {
+    readonly isOpen: boolean;
+    /** Shows, moves or hides the bubble after the selection or the focus changed. */
+    update(): void;
+    destroy(): void;
+}
+/** Creates the link bubble, which follows the editor on its own. */
+export declare function createLinkBubble(editor: Editor, options: LinkBubbleOptions): LinkBubble;

package/dist/ui/components/link-popover.d.ts

@@ -0,0 +1,20 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** Options of {@link createLinkPopover}. */
+export interface LinkPopoverOptions {
+    /** The element the popover scrolls with: the parent of the editable element. */
+    container: HTMLElement;
+    messages: Messages;
+}
+/** The link popover: adds, edits or removes the link of the selection. */
+export interface LinkPopover {
+    readonly isOpen: boolean;
+    /** Opens the popover under the selection; does nothing when {@link canEditLink} is false. */
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+/** Whether the selection is in a link or can be linked (a cursor outside a link cannot). */
+export declare function canEditLink(editor: Editor): boolean;
+/** Creates the link popover (closed), anchored to the selection of `editor`. */
+export declare function createLinkPopover(editor: Editor, options: LinkPopoverOptions): LinkPopover;

package/dist/ui/components/popover.d.ts

@@ -0,0 +1,27 @@
+import type { Placement, VirtualElement } from '@floating-ui/dom';
+/** Why a popover closed. `api` = `close()` or `destroy()` was called. */
+export type PopoverCloseReason = 'escape' | 'outside' | 'api';
+export interface PopoverOptions {
+    /** What the popover is anchored to: an element, or a rectangle (e.g. the selection). */
+    anchor: Element | VirtualElement;
+    /** The floating element; the popover appends it to `container`. */
+    content: HTMLElement;
+    /**
+     * The element the popover scrolls with: it gets the class `stilo-popover-host`
+     * (`position: relative`), so the browser moves the popover with it on scroll.
+     */
+    container: HTMLElement;
+    /** Default: 'bottom-start'. */
+    placement?: Placement;
+    /** Distance from the anchor in px. Default: 4. */
+    offset?: number;
+    /** Called on every open → closed transition. */
+    onClose?(reason: PopoverCloseReason): void;
+}
+export interface Popover {
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+export declare function createPopover(options: PopoverOptions): Popover;

package/dist/ui/components/shortcut.d.ts

@@ -0,0 +1,11 @@
+/** Whether the platform shows Mac shortcuts. */
+export declare function isMacPlatform(): boolean;
+/**
+ * Formats a keymap shortcut for display.
+ *
+ * Off Mac: `Mod` means `Ctrl`; modifiers in the order `Ctrl`, `Alt`, `Shift`, then the key,
+ * joined with `+`. On Mac: `Ctrl` → `⌃`, `Alt` → `⌥`, `Shift` → `⇧`, `Mod` → `⌘`, in the
+ * order `⌃⌥⇧⌘`, then the key, no separator. A single-character key is uppercased; longer
+ * keys stay as written.
+ */
+export declare function formatShortcut(shortcut: string, mac: boolean): string;

package/dist/ui/components/status-bar.d.ts

@@ -0,0 +1,19 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** Options of {@link createStatusBar}. */
+export interface StatusBarOptions {
+    /** The status bar element is appended inside it. */
+    container: HTMLElement;
+    /** UI strings. Default: `en`. */
+    messages?: Messages;
+}
+/** A status bar created by {@link createStatusBar}. */
+export interface StatusBar {
+    readonly element: HTMLElement;
+    /** Counts again now (it also counts 500 ms after the last change). */
+    update(): void;
+    /** Removes the status bar and every listener. Calling it twice is a no-op. */
+    destroy(): void;
+}
+/** Creates a status bar with the word and character count of the document (F-901). */
+export declare function createStatusBar(editor: Editor, options: StatusBarOptions): StatusBar;

package/dist/ui/components/table-actions.d.ts

@@ -0,0 +1,25 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** A table operation: the command of the same name, `toggleHeader*` for the header toggles. */
+export type TableAction = 'addRowBefore' | 'addRowAfter' | 'deleteRow' | 'addColumnBefore' | 'addColumnAfter' | 'deleteColumn' | 'mergeCells' | 'splitCell' | 'toggleHeaderRow' | 'toggleHeaderColumn' | 'deleteTable';
+/** Options of {@link createTableActions}. */
+export interface TableActionsOptions {
+    /** The operations, in groups divided by a separator. */
+    groups: ReadonlyArray<ReadonlyArray<TableAction>>;
+    /** The accessible name of the menu. */
+    label: string;
+    messages: Messages;
+    /** Closes the popover holding the menu (`Tab`, and before an operation runs). */
+    close(): void;
+}
+/** A `role="menu"` of table operations, for a popover. */
+export interface TableActions {
+    readonly element: HTMLElement;
+    /** Enables the items whose command can run and checks the header toggles. */
+    refresh(): void;
+    /** Focuses the first enabled item. */
+    focusFirst(): void;
+    destroy(): void;
+}
+/** Creates a menu of table operations; an item runs its command on the selection. */
+export declare function createTableActions(editor: Editor, options: TableActionsOptions): TableActions;

package/dist/ui/components/table-handles.d.ts

@@ -0,0 +1,16 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** Options of {@link createTableHandles}. */
+export interface TableHandlesOptions {
+    /** The element the handles scroll with: the parent of the editable element. */
+    container: HTMLElement;
+    messages: Messages;
+}
+/** The handles of the row, the column and the table of the cell under the mouse or the cursor. */
+export interface TableHandles {
+    /** Shows, moves or hides the handles after the selection, the focus or the mouse changed. */
+    update(): void;
+    destroy(): void;
+}
+/** Creates the table handles, which follow the editor on their own. */
+export declare function createTableHandles(editor: Editor, options: TableHandlesOptions): TableHandles;

package/dist/ui/components/table-menu.d.ts

@@ -0,0 +1,21 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+/** Options of {@link createTableMenu}. */
+export interface TableMenuOptions {
+    /** The toolbar button that opens the menu. */
+    anchor: HTMLElement;
+    /** The element the menu scrolls with: the toolbar. */
+    container: HTMLElement;
+    messages: Messages;
+}
+/** The table menu: the insert grid outside a table, the table operations inside one. */
+export interface TableMenu {
+    readonly isOpen: boolean;
+    open(): void;
+    /** Closes the menu and gives the focus back to the editor. */
+    close(): void;
+    toggle(): void;
+    destroy(): void;
+}
+/** Creates the table menu (closed), anchored to the toolbar button. */
+export declare function createTableMenu(editor: Editor, options: TableMenuOptions): TableMenu;

package/dist/ui/i18n/en.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from './types';
+/** English UI strings. */
+export declare const en: Messages;

package/dist/ui/i18n/it.d.ts

@@ -0,0 +1,3 @@
+import type { Messages } from './types';
+/** Italian UI strings. */
+export declare const it: Messages;

package/dist/ui/i18n/types.d.ts

@@ -0,0 +1,4 @@
+/** Keys of the built-in UI strings (dot.case). */
+export type MessageKey = 'toolbar.label' | 'toolbar.undo' | 'toolbar.redo' | 'toolbar.bold' | 'toolbar.italic' | 'toolbar.underline' | 'toolbar.strike' | 'toolbar.subscript' | 'toolbar.superscript' | 'toolbar.code' | 'toolbar.clearFormatting' | 'toolbar.textCase' | 'toolbar.bulletList' | 'toolbar.orderedList' | 'toolbar.taskList' | 'toolbar.blockquote' | 'toolbar.codeBlock' | 'toolbar.horizontalRule' | 'toolbar.link' | 'toolbar.heading' | 'toolbar.fontFamily' | 'toolbar.fontSize' | 'fontSize.decrease' | 'fontSize.increase' | 'toolbar.textAlign' | 'align.left' | 'align.center' | 'align.right' | 'align.justify' | 'toolbar.lineHeight' | 'lineHeight.default' | 'textCase.upper' | 'textCase.lower' | 'textCase.title' | 'textCase.sentence' | 'textCase.toggle' | 'font.default' | 'font.sansSerif' | 'font.serif' | 'font.monospace' | 'heading.paragraph' | 'heading.h1' | 'heading.h2' | 'heading.h3' | 'heading.h4' | 'heading.h5' | 'heading.h6' | 'link.url' | 'link.newTab' | 'link.apply' | 'link.remove' | 'link.edit' | 'link.open' | 'toolbar.characters' | 'characters.search' | 'characters.noResults' | 'characters.symbols' | 'characters.emoji' | 'characters.punctuation' | 'characters.currency' | 'characters.math' | 'characters.arrows' | 'characters.greek' | 'characters.latin' | 'characters.signs' | 'characters.smileys' | 'characters.people' | 'characters.nature' | 'characters.food' | 'characters.travel' | 'characters.activities' | 'characters.objects' | 'characters.emojiSymbols' | 'toolbar.textColor' | 'toolbar.highlight' | 'color.more' | 'color.default' | 'color.none' | 'color.pick' | 'color.custom' | 'color.apply' | 'color.black' | 'color.darkGray2' | 'color.darkGray1' | 'color.gray' | 'color.lightGray1' | 'color.lightGray2' | 'color.lightGray3' | 'color.white' | 'color.red' | 'color.orange' | 'color.yellow' | 'color.green' | 'color.cyan' | 'color.blue' | 'color.purple' | 'color.pink' | 'color.lightRed' | 'color.lightOrange' | 'color.lightYellow' | 'color.lightGreen' | 'color.lightCyan' | 'color.lightBlue' | 'color.lightPurple' | 'color.lightPink' | 'color.darkRed' | 'color.darkOrange' | 'color.darkYellow' | 'color.darkGreen' | 'color.darkCyan' | 'color.darkBlue' | 'color.darkPurple' | 'color.darkPink' | 'toolbar.table' | 'table.insert' | 'table.size' | 'table.row' | 'table.column' | 'table.headerRow' | 'table.headerColumn' | 'table.addRowBefore' | 'table.addRowAfter' | 'table.deleteRow' | 'table.addColumnBefore' | 'table.addColumnAfter' | 'table.deleteColumn' | 'table.mergeCells' | 'table.splitCell' | 'table.deleteTable' | 'toolbar.find' | 'find.find' | 'find.replace' | 'find.previous' | 'find.next' | 'find.matchCase' | 'find.wholeWord' | 'find.replaceOne' | 'find.replaceAll' | 'find.close' | 'find.position' | 'find.results' | 'find.noResults' | 'status.words' | 'status.characters';
+/** UI strings: every {@link MessageKey}, plus the label keys of custom toolbar items. */
+export type Messages = Readonly<Record<MessageKey, string>> & Readonly<Record<string, string>>;

package/dist/ui/index.d.ts

@@ -0,0 +1,23 @@
+/** Public API of the Stilo default UI. */
+/** Dropdown component. */
+export type { Dropdown, DropdownOptions, DropdownOptionView, DropdownState, } from './components/dropdown';
+/** Shortcut formatting utilities. */
+export { formatShortcut } from './components/shortcut';
+/** Status bar with the word and character count. */
+export { createStatusBar, type StatusBar, type StatusBarOptions, } from './components/status-bar';
+/** English UI strings. */
+export { en } from './i18n/en';
+/** Italian UI strings. */
+export { it } from './i18n/it';
+/** i18n types. */
+export type { MessageKey, Messages } from './i18n/types';
+/** Default lists of the font dropdowns. */
+export { DEFAULT_FONT_SIZES, DEFAULT_FONTS } from './toolbar/fonts';
+/** Default toolbar items and layout. */
+export { DEFAULT_ITEMS, DEFAULT_TOOLBAR, type FontSizeInputOptions, fontFamilyDropdown, fontSizeInput, headingDropdown, highlightButton, lineHeightDropdown, textAlignMenu, textColorButton, } from './toolbar/items';
+/** Default palette of the color buttons. */
+export { DEFAULT_PALETTE } from './toolbar/palette';
+/** Toolbar element and creation function. */
+export { createToolbar, type Toolbar, type ToolbarOptions } from './toolbar/toolbar';
+/** Toolbar item types. */
+export type { ToolbarButton, ToolbarColor, ToolbarColorButton, ToolbarContext, ToolbarDropdown, ToolbarDropdownOption, ToolbarFont, ToolbarFontSizeInput, ToolbarIconMenu, ToolbarIconMenuOption, ToolbarItem, } from './toolbar/types';

package/dist/ui/toolbar/fonts.d.ts

@@ -0,0 +1,8 @@
+import type { ToolbarFont } from './types';
+/**
+ * The default fonts of the font family dropdown: the three generic families, which every system
+ * resolves, then common fonts with fallbacks for the systems that lack them.
+ */
+export declare const DEFAULT_FONTS: readonly ToolbarFont[];
+/** The default sizes of the font size list, by unit (`rem` uses the px list). */
+export declare const DEFAULT_FONT_SIZES: Readonly<Record<'pt' | 'px', readonly number[]>>;

package/dist/ui/toolbar/items.d.ts

@@ -0,0 +1,33 @@
+import type { FontSizeUnit, HeadingLevel } from '../../index';
+import type { ToolbarColor, ToolbarColorButton, ToolbarDropdown, ToolbarFont, ToolbarFontSizeInput, ToolbarIconMenu, ToolbarItem } from './types';
+/** Default toolbar item IDs for the `items` configuration. */
+export declare const DEFAULT_TOOLBAR: ReadonlyArray<ReadonlyArray<string>>;
+/** The default toolbar items, by ID. */
+export declare const DEFAULT_ITEMS: Readonly<Record<string, ToolbarItem>>;
+/** The text color split button (`TextStyle` extension), default color black. */
+export declare function textColorButton(palette?: readonly ToolbarColor[]): ToolbarColorButton;
+/** The highlight split button (`Highlight` extension), default a plain `<mark>`. */
+export declare function highlightButton(palette?: readonly ToolbarColor[]): ToolbarColorButton;
+/**
+ * The font family dropdown (`TextStyle` extension): "Default" removes the font family, then one
+ * option per font, drawn in that font. A font that is not in the list is shown by its first name.
+ */
+export declare function fontFamilyDropdown(fonts?: readonly ToolbarFont[]): ToolbarDropdown;
+/** Options of {@link fontSizeInput}. */
+export interface FontSizeInputOptions {
+    /** The unit the field shows and writes. Default: `pt`. */
+    unit?: FontSizeUnit;
+    /** The sizes of the list, in `unit` (px for `rem`). Default: `DEFAULT_FONT_SIZES` of the unit. */
+    sizes?: readonly number[];
+}
+/** The font size control (`TextStyle` extension): −, a field with a list of sizes, +. */
+export declare function fontSizeInput(options?: FontSizeInputOptions): ToolbarFontSizeInput;
+/** The text alignment menu (`TextAlign` extension): left, center, right, justify. */
+export declare function textAlignMenu(): ToolbarIconMenu;
+/**
+ * The line spacing dropdown (`LineHeight` extension): "Default" (no line height of its own) and
+ * the `values`, shown as numbers.
+ */
+export declare function lineHeightDropdown(values?: readonly number[]): ToolbarDropdown;
+/** A heading dropdown toolbar item. */
+export declare function headingDropdown(levels?: HeadingLevel[]): ToolbarDropdown;

package/dist/ui/toolbar/palette.d.ts

@@ -0,0 +1,6 @@
+import type { ToolbarColor } from './types';
+/**
+ * The default palette of the color buttons, 8 columns: grays, then 8 hues in their vivid, light
+ * and dark shades.
+ */
+export declare const DEFAULT_PALETTE: readonly ToolbarColor[];

package/dist/ui/toolbar/toolbar.d.ts

@@ -0,0 +1,28 @@
+import type { Editor } from '../../index';
+import type { Messages } from '../i18n/types';
+import type { ToolbarItem } from './types';
+/** Options of {@link createToolbar}. */
+export interface ToolbarOptions {
+    /** The toolbar element is appended inside it. */
+    container: HTMLElement;
+    /** Groups of items: an ID of DEFAULT_ITEMS or a custom item. Default: DEFAULT_TOOLBAR. */
+    items?: ReadonlyArray<ReadonlyArray<string | ToolbarItem>>;
+    /** UI strings. Default: `en`. */
+    messages?: Messages;
+    /**
+     * Keeps the toolbar visible at the top of the scrolling area: `container` gets the class
+     * `stilo-toolbar-host` (`position: sticky`). Default: `true`.
+     */
+    sticky?: boolean;
+}
+/** A toolbar created by {@link createToolbar}. */
+export interface Toolbar {
+    /** The `role="toolbar"` element. */
+    readonly element: HTMLElement;
+    /** Refreshes active/enabled states now (they also refresh on every transaction). */
+    update(): void;
+    /** Removes the toolbar and every listener. Calling it twice is a no-op. */
+    destroy(): void;
+}
+/** Creates the toolbar element and buttons, and registers event handlers. */
+export declare function createToolbar(editor: Editor, options: ToolbarOptions): Toolbar;

package/dist/ui/toolbar/types.d.ts

@@ -0,0 +1,150 @@
+import type { IconNode } from 'lucide';
+import type { Editor, FontSizeUnit } from '../../index';
+/** A toolbar button. */
+export interface ToolbarButton {
+    /** Unique within the toolbar; written as `data-item`. */
+    id: string;
+    kind: 'button';
+    icon: IconNode;
+    /** Key of the label in `messages`; a missing key is shown as is. */
+    labelKey: string;
+    /** Keymap notation shown in the tooltip, e.g. 'Mod-b'. */
+    shortcut?: string;
+    /** Runs on click, after the editor got the focus back. */
+    run(editor: Editor, context: ToolbarContext): void;
+    /** Present = toggle button (`aria-pressed`). */
+    isActive?(editor: Editor): boolean;
+    /** Default: always enabled. */
+    isEnabled?(editor: Editor): boolean;
+    /** False = not rendered (e.g. its extension is disabled). Default: available. */
+    isAvailable?(editor: Editor): boolean;
+}
+/** UI services the toolbar offers to {@link ToolbarButton.run}. */
+export interface ToolbarContext {
+    /** Opens the link popover under the selection (no-op without the `Link` extension). */
+    openLinkPopover(): void;
+    /** Opens or closes the character picker (no-op without the `characters` item). */
+    toggleCharacterPicker(): void;
+    /** Opens or closes the find bar (no-op without the `Search` extension). */
+    toggleFindBar(): void;
+    /** Opens or closes the table menu (no-op without the `table` item). T-045. */
+    toggleTableMenu(): void;
+}
+/** A dropdown of mutually exclusive options, or of actions (T-048) (T-014). */
+export interface ToolbarDropdown {
+    id: string;
+    kind: 'dropdown';
+    /** Key of the accessible name of the trigger and of the menu. */
+    labelKey: string;
+    /** Shown by the trigger instead of the active option (T-040); default: the option label. */
+    icon?: IconNode;
+    options: ToolbarDropdownOption[];
+    /**
+     * The text of the trigger when no option is active, e.g. a font size that is not in the list;
+     * `null` (or no function) shows the dropdown label.
+     */
+    getValueLabel?(editor: Editor): string | null;
+    isAvailable?(editor: Editor): boolean;
+}
+/** An option of a {@link ToolbarDropdown}. */
+export interface ToolbarDropdownOption {
+    /** Unique within the dropdown; used in the class `stilo-dropdown__option--<id>`. */
+    id: string;
+    labelKey: string;
+    shortcut?: string;
+    /** Shows the option label in this font family (a CSS `font-family` list). */
+    fontFamily?: string;
+    run(editor: Editor): void;
+    /** Without it the option is an action (`role="menuitem"`), never checked. T-048. */
+    isActive?(editor: Editor): boolean;
+    /** Default: always enabled. */
+    isEnabled?(editor: Editor): boolean;
+}
+/** A color of a {@link ToolbarColorButton} palette. */
+export interface ToolbarColor {
+    /** A CSS color, written as the editor stores it (e.g. lowercase `#rrggbb`). */
+    color: string;
+    /** Key of the color name in `messages`; a missing key is shown as is. */
+    labelKey: string;
+}
+/**
+ * A split button that applies a color (T-026): the main part applies the last used color (or
+ * removes it when the whole selection has it), the arrow opens a popover with the palette.
+ */
+export interface ToolbarColorButton {
+    /** Unique within the toolbar; written as `data-item` on both parts. */
+    id: string;
+    kind: 'color';
+    icon: IconNode;
+    labelKey: string;
+    palette: readonly ToolbarColor[];
+    /** The color the main part applies until one is picked (`null`: the mark without a color). */
+    defaultColor: string | null;
+    /**
+     * Shows a "Default" choice next to "No color" that applies the color `null`; its label is
+     * drawn inside a `<mark>`, the browser's look of a highlight without a color.
+     */
+    defaultChoice?: boolean;
+    /** Applies `color` to the selection; `false` when the color is refused. */
+    setColor(editor: Editor, color: string | null): boolean;
+    /** Removes the color from the selection. */
+    unsetColor(editor: Editor): void;
+    /** Whether the whole selection has `color`. */
+    hasColor(editor: Editor, color: string | null): boolean;
+    /** The color at the selection, `null` when there is none. */
+    getColor(editor: Editor): string | null;
+    /** Default: always enabled. */
+    isEnabled?(editor: Editor): boolean;
+    isAvailable?(editor: Editor): boolean;
+}
+/** A font of the `fontFamilyDropdown` list. */
+export interface ToolbarFont {
+    /** A CSS `font-family` list, written as the editor stores it (`'Times New Roman', serif`). */
+    fontFamily: string;
+    /** Key of the font name in `messages`; a missing key is shown as is. */
+    labelKey: string;
+}
+/**
+ * The font size control (T-038): a decrease button, a field that shows the size at the selection,
+ * takes a typed size and opens a list of sizes, and an increase button.
+ */
+export interface ToolbarFontSizeInput {
+    /** Unique within the toolbar; written as `data-item` on the three parts. */
+    id: string;
+    kind: 'fontSize';
+    /** Key of the accessible name of the field and of the list. */
+    labelKey: string;
+    /** The unit the field shows and writes; `rem` shows px and writes rem. */
+    unit: FontSizeUnit;
+    /** The sizes of the list, in `unit` (px for `rem`). */
+    sizes: readonly number[];
+    isAvailable?(editor: Editor): boolean;
+}
+/**
+ * A button that shows the icon of the active option (of the first one when none is active) and
+ * opens the options as icons in a row (T-039).
+ */
+export interface ToolbarIconMenu {
+    /** Unique within the toolbar; written as `data-item`. */
+    id: string;
+    kind: 'iconMenu';
+    /** Key of the accessible name of the trigger and of the menu. */
+    labelKey: string;
+    options: ToolbarIconMenuOption[];
+    isAvailable?(editor: Editor): boolean;
+}
+/** An option of a {@link ToolbarIconMenu}. */
+export interface ToolbarIconMenuOption {
+    /** Unique within the menu; used in the class `stilo-icon-menu__option--<id>`. */
+    id: string;
+    icon: IconNode;
+    labelKey: string;
+    /** Keymap notation shown in the tooltip. */
+    shortcut?: string;
+    run(editor: Editor): void;
+    isActive(editor: Editor): boolean;
+    /** Default: always enabled. */
+    isEnabled?(editor: Editor): boolean;
+}
+/** A single item in the toolbar. */
+export type ToolbarItem = ToolbarButton | ToolbarDropdown | ToolbarColorButton | ToolbarFontSizeInput | ToolbarIconMenu;