Choose your editor interface

<div id="toolbar"></div>
<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

// Built-in: SuperDoc renders the chrome.
//
// Surfaces you say nothing about keep their historical defaults. The toolbar is
// the one that needs a mount target, because SuperDoc cannot guess where in
// your layout it belongs.
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  ui: {
    toolbar: { container: '#toolbar' },
    // The default toolbar renders a Search button regardless, and it opens
    // the shared find/replace surface. Leaving `search` off gives a control
    // that is visible, enabled, and does nothing when clicked.
    search: true,
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

<div id="toolbar"></div>

<aside aria-labelledby="comments-heading">
  <h2 id="comments-heading">Comments</h2>
  <div id="comments-panel"></div>
  <label for="comment-text">New comment</label>
  <textarea id="comment-text" rows="3"></textarea>
  <button id="add-comment" type="button" disabled>Add comment</button>
</aside>

<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

import { SuperDoc } from 'superdoc';
import type { BorrowedSuperDocUI, CommentsSlice, SelectionCapture, SelectionSlice } from 'superdoc/ui';
import 'superdoc/style.css';

const panelElement = document.querySelector<HTMLElement>('#comments-panel');
const composerText = document.querySelector<HTMLTextAreaElement>('#comment-text');
const composerSubmit = document.querySelector<HTMLButtonElement>('#add-comment');

if (!panelElement || !composerText || !composerSubmit) {
  throw new Error('The comments panel is missing.');
}

const panel = panelElement;
const commentText = composerText;
const addComment = composerSubmit;

// The capture taken while text was selected. Creating a comment needs a
// document address rather than a live DOM range, so it is taken when the
// selection exists and used later when the composer is submitted.
let capturedSelection: SelectionCapture | null = null;

/**
 * The application's own comments surface, in place of the built-in one.
 *
 * Clicking a row focuses that comment and scrolls the document to it, which
 * is the behavior the built-in panel provided before `ui.comments: false`
 * turned it off.
 *
 * The observer fires on every change, including the one a click here causes,
 * so the rows are rebuilt underneath the button the user just pressed. Each
 * row carries its comment id and focus is restored afterwards; without that,
 * keyboard and screen-reader users are returned to the top of the document
 * after every activation.
 */
function renderCommentPanel(ui: BorrowedSuperDocUI, slice: CommentsSlice) {
  const focusedId =
    document.activeElement instanceof HTMLElement && panel.contains(document.activeElement)
      ? document.activeElement.dataset.commentId
      : undefined;

  panel.replaceChildren(
    ...slice.items.map((comment) => {
      const row = document.createElement('button');
      row.type = 'button';
      row.dataset.commentId = comment.id;
      // A comment can carry no text. Falling back to an empty string would
      // leave a focusable control that assistive technology cannot name.
      row.textContent = comment.text || 'Comment without text';
      row.addEventListener('click', () => {
        ui.comments.setActive(comment.id);
        void ui.comments.scrollTo(comment.id);
      });
      return row;
    }),
  );

  if (focusedId) {
    panel.querySelector<HTMLButtonElement>(`[data-comment-id="${CSS.escape(focusedId)}"]`)?.focus();
  }
}

// Hybrid: SuperDoc and the application split the chrome.
//
// Three keys are named here and every other surface keeps its default. The
// application renders its own comments panel, so the built-in one is turned
// off; the toolbar is given a mount target; and search is opted into, because
// it is off by default and the toolbar's Search button needs it. `ui` keys are
// independent, so naming these three says nothing about the rest.
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  ui: {
    toolbar: { container: '#toolbar' },
    comments: false,
    // The default toolbar's Search button opens this surface. Without it the
    // control still renders and clicking it does nothing.
    search: true,
  },
  // Rendering and permission are separate decisions. Turning off the built-in
  // comments interface does not stop this panel from writing, so the policy is
  // stated rather than inferred from `ui`. `readOnly: false` is the default;
  // it is written out because the point of the pair is that `ui` never
  // decides it. `allowResolve: false` permits replies while forbidding resolve.
  //
  // `readOnly: true` is deliberately not the example here: it refuses tracked
  // change accept and reject as well as comment writes, so it takes the review
  // workflow with it. Reach for it when the whole surface should not mutate
  // the document, not to make one panel non-writing.
  interaction: { comments: { readOnly: false, allowResolve: true } },
  onReady: ({ superdoc: readySuperDoc }) => {
    // The controller stays available for the surfaces the application owns.
    const ui = readySuperDoc.ui;

    // Capture while the selection exists; the composer is submitted later,
    // after focus has moved to the textarea and the selection is gone.
    //
    // Submit needs both halves: something to attach the comment to, and
    // something to say. Gating on the capture alone leaves an enabled button
    // whose click returns silently, which reads as a broken control.
    const syncComposer = () => {
      addComment.disabled = !capturedSelection || commentText.value.trim().length === 0;
    };

    const trackSelection = (selection: SelectionSlice) => {
      if (!selection.empty) capturedSelection = ui.selection.capture();
      syncComposer();
    };

    commentText.addEventListener('input', syncComposer);

    addComment.addEventListener('click', async () => {
      if (!capturedSelection || !commentText.value.trim()) return;
      const receipt = await ui.comments.createFromCapture(capturedSelection, { text: commentText.value.trim() });
      if (!receipt.success) return;
      commentText.value = '';
      capturedSelection = null;
      syncComposer();
    });

    trackSelection(ui.selection.getSnapshot());
    ui.selection.observe(trackSelection);
    renderCommentPanel(ui, ui.comments.getSnapshot());
    ui.comments.observe((slice) => renderCommentPanel(ui, slice));
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

<style>
  /* The application owns every control here, so it owns their states too. */
  #bold[aria-pressed='true'] {
    background: #1a1a1a;
    color: #fff;
  }
  #bold:disabled {
    opacity: 0.5;
  }
</style>

<div role="toolbar" aria-label="Formatting">
  <!-- Disabled until `onReady` attaches the handler and the first command
       state arrives. A DOCX can take a moment to load, or fail to, and an
       enabled button in that window swallows clicks silently. -->
  <button id="bold" type="button" aria-pressed="false" disabled>Bold</button>
</div>

<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

import { SuperDoc } from 'superdoc';
import type { CommandState } from 'superdoc/ui';
import 'superdoc/style.css';

const boldButton = document.querySelector<HTMLButtonElement>('#bold')!;

// Fully custom: the application renders every control.
//
// `ui: false` turns off all built-in chrome at once. It removes presentation
// only: editing, the Document API, `interaction`, `surfaces`, and
// `superdoc.ui` all keep working, which is what makes this viable without
// giving up the editor underneath.
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  ui: false,
  // Still enforced with no built-in UI to enforce it in. Policy is not a
  // property of the chrome that happens to render it.
  interaction: { comments: { readOnly: true } },
  onReady: ({ superdoc: readySuperDoc }) => {
    const bold = readySuperDoc.ui.commands.get('bold');

    const render = (state: CommandState) => {
      boldButton.disabled = !state.enabled;
      // A toggle's pressed state has to reach assistive technology, not only
      // a class name. `aria-pressed` announces it and drives the styling in
      // the markup beside this file, so there is one source of truth.
      boldButton.setAttribute('aria-pressed', String(state.active));
    };

    render(bold.getState());
    bold.observe(render);
    boldButton.addEventListener('click', () => bold.execute());
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());