stilo-editor 0.0.0-stage → 0.1.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,25 @@
+/** One option as displayed: label and shortcut already resolved and formatted. */
+export interface DropdownOptionView {
+    id: string;
+    label: string;
+    shortcut?: string;
+}
+export interface DropdownOptions {
+    /** Accessible name of the trigger and of the menu; shown when no option is active. */
+    label: string;
+    options: DropdownOptionView[];
+    /** The popover container (the toolbar element). */
+    container: HTMLElement;
+    onSelect(id: string): void;
+}
+export interface DropdownState {
+    activeId: string | null;
+    disabledIds: ReadonlySet<string>;
+}
+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/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/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.bulletList' | 'toolbar.orderedList' | 'toolbar.blockquote' | 'toolbar.horizontalRule' | 'toolbar.link' | 'toolbar.heading' | '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';
+/** 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,19 @@
+/** 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';
+/** 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 toolbar items and layout. */
+export { DEFAULT_ITEMS, DEFAULT_TOOLBAR, headingDropdown, highlightButton, 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, ToolbarItem, } from './toolbar/types';

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

@@ -0,0 +1,12 @@
+import type { HeadingLevel } from '../../index';
+import type { ToolbarColor, ToolbarColorButton, ToolbarDropdown, 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;
+/** 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,87 @@
+import type { IconNode } from 'lucide';
+import type { Editor } 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;
+}
+/** A dropdown of mutually exclusive options (T-014). */
+export interface ToolbarDropdown {
+    id: string;
+    kind: 'dropdown';
+    /** Key of the accessible name of the trigger and of the menu. */
+    labelKey: string;
+    options: ToolbarDropdownOption[];
+    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;
+    run(editor: Editor): void;
+    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 single item in the toolbar. */
+export type ToolbarItem = ToolbarButton | ToolbarDropdown | ToolbarColorButton;