@octane-xplat/richtext 0.9.0 → 0.11.0

package/types/types.d.ts

@@ -1,29 +1,73 @@
-/** Supported on Android today (WordPress Aztec); iOS is stubbed until the
- *  Swift-facade bring-up. Web/macOS/Windows route through the tiptap facade
- *  instead of this leaf. */
+import type { Octane } from 'octane/jsx-runtime';
+/** Android uses WordPress Aztec; iOS uses AztecEditor-iOS; AppKit uses
+ * StarterKit in WKWebView. Web/Windows use the tiptap facade instead of
+ * this leaf. */
 export type RichTextFormat = 'bold' | 'italic' | 'underline' | 'strikethrough' | 'code' | 'blockquote' | 'bulletList' | 'orderedList' | 'taskList' | 'codeBlock' | 'horizontalRule' | 'highlight' | 'subscript' | 'superscript' | 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading5' | 'heading6' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'link';
 export interface RichTextEditorHandle {
     /** Serialized document HTML (Aztec's "plain" HTML — no contenteditable
      *  markup). */
+    /** AppKit: returns the latest WebKit snapshot; commands are asynchronous. */
     getHTML(): string;
-    /** Replace the document; resets Aztec's undo history. */
+    /** Replace the document. Android resets Aztec history; the iOS
+     *  `setHTML` variant is likewise non-undoable; AppKit uses engine
+     *  history. */
     setHTML(html: string): void;
     /** Toggle a format at the current selection. `link` needs
-     *  `linkTo(url, anchor)` instead. */
+     *  `linkTo(url, anchor)` instead. iOS has no taskList or text-alignment
+     *  engine support — those calls report a console warning and do not
+     *  change the document. */
     apply(format: RichTextFormat): void;
     /** Insert or re-target a link over the current selection. */
     linkTo(url: string, anchor?: string): void;
     removeLink(): void;
-    /** Formats active at the selection — powers toolbar highlight state. */
+    /** Formats active at the selection — powers toolbar highlight state.
+     *  iOS always reports false for taskList and the align* formats (no
+     *  engine support). */
     isActive(format: RichTextFormat): boolean;
     /** Android: Aztec's history batches keyboard input only — format
-     *  toggles and programmatic edits do not register. */
+     *  toggles and programmatic edits do not register. iOS: the engine
+     *  undoManager covers format toggles and keyboard input; `setHTML` and
+     *  split/join edits sit outside it. */
     undo(): void;
     redo(): void;
+    /** Split the block at the caret into two siblings — the Enter-key
+     *  semantic (a non-collapsed selection is deleted first). Android: a
+     *  real block break through Aztec's watcher pipeline — a caret inside
+     *  a list item produces a sibling `<li>`. iOS routes through Aztec's
+     *  `insertText` newline handling for the same semantics. Inside hidden
+     *  block markup Aztec does not understand (`<div data-*>` wrappers),
+     *  this is a line break, not a new node — it serializes as `<br>`.
+     *  Returns false when
+     *  there is no valid selection. AppKit: returns false — the engine
+     *  transport is asynchronous and cannot report application. */
+    split(): boolean;
+    /** Merge the block at the caret into the previous block — the
+     *  Backspace-at-block-start semantic. Returns false unless the
+     *  selection is a collapsed caret directly after a block boundary. */
+    join(): boolean;
+    /** Demote the block(s) in the selection. Aztec semantics: a list item
+     *  nests under its previous sibling; a plain paragraph, heading,
+     *  quote, or preformat line gains a literal `\t` indent. Hidden
+     *  `<div data-*>` nodes are opaque to Aztec and cannot be demoted.
+     *  iOS: `increaseIndent` acts on list/quote depth and falls back to a
+     *  `\t` insert on plain blocks. Returns false when Aztec reports no
+     *  indentable selection (iOS: when the view is not editable). */
+    indent(): boolean;
+    /** Promote the block(s) in the selection one level — the inverse of
+     *  `indent()`. iOS has no plain-block outdent, so this applies only to
+     *  list items and blockquotes. Returns false when Aztec reports no
+     *  outdentable selection. */
+    outdent(): boolean;
+    /** Whether `indent()` can apply to the current selection. */
+    canIndent(): boolean;
+    /** Whether `outdent()` can apply to the current selection. */
+    canOutdent(): boolean;
     focus(): void;
     blur(): void;
     isFocused(): boolean;
-    /** The platform surface — `AztecText` on Android. */
+    /** The platform surface — `AztecText` on Android, the
+     *  `XplatAztecEditorView` facade on iOS. */
+    /** AppKit: the XplatEditorHost transport, not the browser engine instance. */
     native: any;
 }
 export interface RichTextSelectionChange {
@@ -49,7 +93,7 @@ export interface RichTextEditorProps {
     onFocus?: () => void;
     onBlur?: () => void;
     /** Imperative handle — fires once when the native editor exists. */
-    bind?: (handle: RichTextEditorHandle) => void;
+    ref?: Octane.Ref<RichTextEditorHandle>;
     /** Per-platform escape bag — properties are assigned onto the native
      *  `AztecText` after the leaf's own props. */
     android?: Record<string, any>;