Skip to content
Edit on GitHub

AI UI

The AI controls of BlockEditor — command bar, Improve, ghost text, proofreading toolbar and status — and the AiCommandPalette and AiToolbar components of @gotipe/ai-ui.

@gotipe/block-editor@gotipe/ai-uiCommercial

BlockEditor has AI controls built in: a command bar, an Improve button over selected text, ghost text at the caret, a proofreading toolbar and a status line. They emit and listen to the events of @gotipe/ai, so they work once the AI extensions and a provider are installed. @gotipe/ai-ui adds a command palette and an action toolbar for your own layouts. @gotipe/block-editor and @gotipe/ai-ui are commercial; @gotipe/ai is MIT.

Live editorDemo providerPause, then Tab
Loading the editor…

Install

npm install @gotipe/ai @gotipe/block-editor
npm install @gotipe/ai-ui

The second command is needed only for AiCommandPalette, AiToolbar and the controlled AiGhostText. @gotipe/ai-ui takes @gotipe/react as a peer: the palette and the toolbar say their words in the language of GoTipeI18nProvider (ai.* keys of @gotipe/i18n, English without a provider).

BlockEditor props

Option Type Default Description
showAiCommandBar boolean true Shows the command bar, the Improve button, ghost text and the status line where an AI extension answers them; false hides them all.
onAiCommand (prompt: string) => void | Promise<void> — Handles a command bar prompt yourself instead of the built-in freeText command.
suggestions ToolbarSuggestion[] — Proofreading suggestions for the toolbar.
onSuggestionAccept, onSuggestionReject (suggestion) => void — Required, with suggestions, for the toolbar to appear.
onSuggestionAcceptAll, onSuggestionRejectAll () => void — Accept All and Reject All.

Which controls show

Each control appears only when an extension answers it, so an editor without defineAi has no AI controls at all: no Improve, no ⌘J (the key stays the browser's), no ghost text and no status line.

Control Shown when the editor has
Improve defineAi and defineAiContext
Command bar and ⌘J defineAi with defineAiAgent or defineAiContext, or defineAi and your onAiCommand
Ghost text, status line defineAi

AiPreset has all three. BlockEditor asks editor.hasExtension(name), so the answer is fixed when the editor is created. PageEditor shows no AI controls.

Command bar

⌘J or Ctrl+J toggles the bar while the focus is in the editor or the bar; the physical J key works on any keyboard layout. The Ask AI slash item opens it too. Enter sends the prompt; Escape, the close button or a click outside closes the bar and cancels a running request. The shortcut does nothing in read-only mode.

Without onAiCommand, the bar runs freeText of defineAiAgent: proofread, proofread document or check grammar start proofreading, review, review document or check document start a review, and any other prompt adds a paragraph after the current block. With defineAiContext but no agent it runs askAi, and every prompt adds a paragraph. The bar shows "Processing..." and the error message of a failed request, and closes once the result has arrived. To rewrite the selection by an instruction, handle the prompt yourself:

instruction-bar.tsx
import { defineAi, defineAiContext, getAiManager } from "@gotipe/ai";
import { BlockEditor } from "@gotipe/block-editor";
import { createId } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
import { useEditor } from "@gotipe/react";
import { backendProvider } from "./ai-provider";

export function InstructionEditor() {
  const editor = useEditor({
    extensions: [DefaultPreset, defineAi.configure({ provider: backendProvider }), defineAiContext],
  });

  return (
    <BlockEditor
      editor={editor}
      onAiCommand={async (prompt) => {
        // The manager of defineAi: closing the bar (cancelAi) cancels this request too.
        const ai = editor && getAiManager(editor);
        if (!ai) return;
        const target = ai.captureTarget();
        const content = await ai.executeCommand(prompt);
        ai.applySuggestion({ id: createId(), type: "rewrite", content, confidence: 1 }, target);
      }}
    />
  );
}

An error thrown by onAiCommand appears in the bar.

Improve

Selecting text opens the formatting bar with an Improve button first. It runs the rewrite command: the provider's streamRewrite rewrites the selection, and the result replaces it in one undoable change. It needs defineAiContext.

Ghost text

With enableAutoComplete: true on defineAi, BlockEditor shows the suggested continuation in muted text after the caret, clipped to the line and kept in place on scroll and resize. Tab accepts it and Escape dismisses it; the ghost text rules say when it appears.

Proofreading

aiProofreadChange fires when proofreading finishes and after each accept or reject. Pass the suggestions to BlockEditor; their shape fits the suggestions prop as it is.

proofread-editor.tsx
import {
  type AiProofreadSuggestion,
  acceptAllProofreadSuggestions,
  acceptProofreadSuggestion,
  defineAi,
  defineAiAgent,
  defineAiContext,
  getProofreadSuggestions,
  rejectAllProofreadSuggestions,
  rejectProofreadSuggestion,
} from "@gotipe/ai";
import { BlockEditor } from "@gotipe/block-editor";
import { DefaultPreset } from "@gotipe/core/presets";
import { useEditor } from "@gotipe/react";
import { useEffect, useState } from "react";
import { backendProvider } from "./ai-provider";

export function ProofreadEditor() {
  const editor = useEditor({
    extensions: [
      DefaultPreset,
      defineAi.configure({ provider: backendProvider }),
      defineAiContext,
      defineAiAgent,
    ],
  });
  const [items, setItems] = useState<AiProofreadSuggestion[]>([]);
  const [error, setError] = useState("");

  useEffect(() => {
    if (!editor) return;
    return editor.on("aiProofreadChange", () => setItems(getProofreadSuggestions(editor)));
  }, [editor]);

  // Accepting a stale suggestion throws; proofread again in that case.
  const run = (action: () => void) => {
    try {
      action();
      setError("");
    } catch (failure) {
      setError(failure instanceof Error ? failure.message : String(failure));
    }
  };

  return (
    <>
      <button
        type="button"
        onClick={() => editor?.emit("executeAiCommand", { commandId: "proofread" })}
      >
        Proofread
      </button>
      {error && <p role="alert">{error}</p>}
      <BlockEditor
        editor={editor}
        suggestions={items}
        onSuggestionAccept={(s) => editor && run(() => acceptProofreadSuggestion(editor, s.id))}
        onSuggestionReject={(s) => editor && run(() => rejectProofreadSuggestion(editor, s.id))}
        onSuggestionAcceptAll={() => editor && run(() => acceptAllProofreadSuggestions(editor))}
        onSuggestionRejectAll={() => editor && run(() => rejectAllProofreadSuggestions(editor))}
      />
    </>
  );
}

The toolbar shows the position, Previous and Next, accept and reject for the current suggestion, and Accept All and Reject All. Accept All is one undo step. After an accept, the other suggestions of that block move with the text.

Status

The status line shows a spinner and what the request does, in the interface's language, while a request runs: it turns the event's task into the keys ai.status.* (in Russian «Модель проверяет правописание…», in English "Proofreading..."). It reads aiStatusChange; use the same event for a status of your own. A status without a task the line knows shows its label as it is, and a status without either says ai.processing.

Components

@gotipe/block-editor exports each control for an editor surface of your own. Every one takes editor and draws nothing for an editor without the extensions it needs (see which controls show).

Component Props Description
AiCommandBar editor, onSubmit? The command bar with its shortcut. onSubmit works like onAiCommand.
BlockEditorBubbleMenu editor, enableAI? The formatting bar; enableAI adds Improve when the editor has defineAi and defineAiContext.
GhostText editor The ghost text overlay.
AiStatusIndicator editor The status line.
SuggestionToolbar see Suggestions The proofreading toolbar.

@gotipe/ai-ui

AiCommandPalette

A dialog that lists your commands, filters them as you type and runs one with Enter or a click. A command returns AiSuggestion[]; clicking one replaces the selection that was current when the palette opened. When the document changed meanwhile, the palette shows an error instead. Escape and the Close button call onClose; unmounting the palette aborts a running command.

ai-palette.tsx
import type { AiCommand } from "@gotipe/ai";
import { AiCommandPalette } from "@gotipe/ai-ui";
import { type GoTipeEditor, createId } from "@gotipe/core";
import { backendProvider } from "./ai-provider";

const commands: AiCommand[] = [
  {
    name: "Summarize",
    description: "Replace the selection with a summary",
    async execute(_editor, context) {
      const content = await backendProvider.executeCommand("summarize", context);
      return [{ id: createId(), type: "summarize", content, confidence: 1 }];
    },
  },
];

export function Palette(props: { editor: GoTipeEditor; onClose: () => void }) {
  return <AiCommandPalette editor={props.editor} commands={commands} onClose={props.onClose} />;
}

The palette calls execute directly with the context and an AbortSignal. The manager's PII check and status events do not apply to it.

AiToolbar

Buttons for Rewrite, Summarize, Expand, Fix grammar and Translate. A click calls onCommand with rewrite, summarize, expand, fixGrammar or translate; running the command is up to you, for example with AiManager.executeCommand() and applySuggestion() as in the command bar example. The buttons are disabled while the editor is read-only or an AI request is running.

AiGhostText

A controlled ghost text. It takes editor, text, onAccept and onDismiss, and renders text as a span. Tab in the editor calls onAccept; any other key except a modifier calls onDismiss. Use it with your own completion state; GhostText of @gotipe/block-editor reads the editor's events instead. The earlier name GhostText of @gotipe/ai-ui still works and is deprecated.

Limitations

  • Without onAiCommand, a command bar prompt never rewrites the selection: it adds a paragraph, proofreads or reviews.
  • Errors of Improve and of slash commands reach host.onError and the error event, but BlockEditor's error toast does not show them: EXTENSION_ERROR stays out of the toast by design (errors); the command bar shows its own.
  • @gotipe/theme has no styles for AiCommandPalette and AiToolbar; style .gotipe-ai-command-palette and .gotipe-ai-toolbar yourself. A command's own name and description are shown as you wrote them.