Skip to content

Editor workspace

The page around a writing surface, with Write, Split and Preview layouts and a sandboxed preview.

  <p class="cap-muted">Choose a layout with the arrow keys; it is remembered in this browser. Type in the text and the chrome steps back; move the mouse and it returns. Ctrl or Cmd + S saves in place.</p>
  <div class="cap-workspace" data-cap="editor-workspace" data-key="cap-specimen-layout" id="ws-html">
    <div data-cap-layout="">
      <fieldset class="cap-seg">
        <legend class="cap-sr-only">Layout</legend>
        <div class="cap-seg-options" data-size="sm">
          <label><input type="radio" name="ws-layout" value="write" /> Write</label>
          <label><input type="radio" name="ws-layout" value="split" checked /> Split</label>
          <label><input type="radio" name="ws-layout" value="preview" /> Preview</label>
        </div>
      </fieldset>
    </div>
    <div class="cap-workspace-body" data-layout="split">
      <section class="cap-workspace-pane" data-pane="write" id="ws-write" aria-label="Write">
        <div class="cap-field">
          <label class="cap-field-label" for="ws-text">Post</label>
          <textarea class="cap-input" id="ws-text" rows="10" data-cap-typing-surface>## Spring update

What changed this spring, and what to do next.</textarea>
        </div>
        <p class="cap-muted" id="ws-saved" role="status">Not saved yet.</p>
      </section>
      <section class="cap-preview-pane" data-pane="preview" aria-label="Preview">
        <iframe title="Preview of Spring update as example.com renders it" sandbox="" src="data:text/html;charset=utf-8,%3C%21doctype%20html%3E%3Chtml%20lang%3D%22en%22%3E%3Ctitle%3ESpring%20update%3C%2Ftitle%3E%3Cmain%3E%3Ch1%3ESpring%20update%3C%2Fh1%3E%3Cp%3EWhat%20changed%20this%20spring%2C%20and%20what%20to%20do%20next.%3C%2Fp%3E%3C%2Fmain%3E%3C%2Fhtml%3E"></iframe>
      </section>
    </div>
  </div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/editor-workspace.css";
import { enhance } from "capsomer/behavior/editor-workspace";

enhance();

Usage

<div class="cap-workspace" data-cap="editor-workspace" data-key="desk-editor-layout">
  <div data-cap-layout="">
    <fieldset class="cap-seg">
      <legend class="cap-sr-only">Layout</legend>
      <div class="cap-seg-options" data-size="sm">
        <label><input type="radio" name="layout" value="write" checked /> Write</label>
        <label><input type="radio" name="layout" value="split" /> Split</label>
        <label><input type="radio" name="layout" value="preview" /> Preview</label>
      </div>
    </fieldset>
  </div>
  <div class="cap-workspace-body" data-layout="write">
    <section class="cap-workspace-pane" data-pane="write" id="write" aria-label="Write">…the editor…</section>
    <section class="cap-preview-pane" data-pane="preview" aria-label="Preview" hidden>
      <iframe title="Preview of Spring update as example.com renders it" src="/preview?at=1" sandbox=""></iframe>
    </section>
  </div>
</div>
import { enhance, onSaveKey, typingRecede } from "capsomer/behavior/editor-workspace";

enhance();
typingRecede();
onSaveKey(() => form.requestSubmit());
import {
  EditorWorkspace, LayoutSwitch, PreviewPane, previewUrl,
  usePausedStamp, useSaveShortcut, useTypingRecede, useWorkspaceLayout,
} from "capsomer/react/editor-workspace";

const [layout, choose] = useWorkspaceLayout("desk-editor-layout");
const stamp = usePausedStamp(source, 2000, baseVersion);
useSaveShortcut(() => maySave && save());
useTypingRecede();

<PageHead title={title} actions={<LayoutSwitch value={layout} onChange={choose} />} />
<EditorWorkspace
  layout={layout}
  write={<MarkdownEditor label="Post" value={body} onChange={setBody} />}
  preview={<PreviewPane src={previewUrl(previewBase, stamp)} title={`Preview of ${title} as ${site} renders it`} />}
/>;

Examples

In React: the switch, the panes and the preview's refresh once typing pauses

<div data-mount="react"></div>

API reference

LayoutSwitch

PropTypeRequiredDoes
valueLayoutYes
onChange(next: Layout) => voidYes
legendstringNames the group for a screen reader; visually hidden. Default "Layout".
labelsPartial<Record<Layout, string>>

EditorWorkspace

PropTypeRequiredDoes
layoutLayoutYes
writeReactNodeYesThe writing surface; not rendered in Preview.
previewReactNodeYesThe preview, usually a PreviewPane; not rendered in Write.
writeLabelstringThe write pane's name. Default "Write".
writeIdstringThe write pane's id, for a skip link. Default "write".

PreviewPane

PropTypeRequiredDoes
srcstringYesThe site's render of the text: a preview route the app serves.
titlestringYesThe frame's title: what it shows, "Preview of Spring update as example.com renders it".
labelstringThe pane's name. Default "Preview".
namestringA form may post into the frame by this name.

Functions

FunctionSignatureDoes
useWorkspaceLayout(key?: string): [Layout, (next: Layout) => void]The layout remembered in this browser under key; Write on the server and in the render that hydrates, so they agree, then the stored one.
useSaveShortcut(save: () => void): voidCtrl or Cmd+S calls save in place of the browser's save-page; save decides whether a save may run now. The latest save is called, so it may close over fresh state.
useTypingRecede(surface?: string | undefined): voidThe chrome steps back while someone types in a writing surface (.cm-editor, or any element with data-cap-typing-surface), and returns on a mouse move or when focus enters it.
usePausedStamp(value: unknown, delay?: number, initial?: string): stringA stamp that changes delay ms after value stops changing: the preview's refresh, so the site renders the text once the typing pauses, not on every key.
readLayout(stored: string | null | undefined): LayoutA stored layout, or Write: what the server and the first paint show, so they agree.
storedLayout(key?: string): Layout | nullThe layout stored under key, or null when none is (or storage is refused).
storeLayout(layout: Layout, key?: string): voidKept through hooks.ts' storage, which tells every reader of the key; where storage is refused it lasts the page.
previewUrl(base: string, stamp: string, param?: string): stringThe preview's address with the refresh stamp in it, so a new stamp loads the frame again.
onSaveKey(save: () => void): () => voidCtrl or Cmd+S calls save in place of the browser's own save-page, through the shortcuts registry, so it is listed in the "?" sheet and steps aside while a modal dialog is open. save decides whether a save may run now. Returns the detach.
typingRecede(options?: { surface?: string | undefined; root?: HTMLElement | undefined; }): () => voidWhile someone types a character in a writing surface, data-cap-typing on the document makes the chrome step back (editor-workspace.css); a mouse move brings it back, and so does focus, which the CSS reads. A character typed in a dialog's field does not count. Returns the detach.
enhance(root?: Element | Document | DocumentFragment): () => voidWithout a framework: every [data-cap="editor-workspace"] takes its layout from the radios in its [data-cap-layout] group, remembered under its data-key (or LAYOUT_KEY), and shows only the panes ([data-pane="write"], [data-pane="preview"]) that layout holds. Without script the layout the HTML was written with stays. The root is Element | Document | DocumentFragment, not ParentNode: under @cloudflare/workers-types an HTMLFormElement does not type as a ParentNode, so a site could not pass its form.

Parts and data attributes

ClassIs
.cap-preview-paneits own class
.cap-workspacethe root
.cap-workspace-bodya part
.cap-workspace-panea part
AttributeValues
data-cap-layoutpresent or absent
data-cap-recedepresent or absent
data-cap-typingpresent or absent
data-layoutsplit
StateRead from
:focus-withinthe platform
[hidden]an attribute

Accessibility

KeyDoes
Left arrow, Right arrow (layout)Chooses Write, Split or Preview
TabMoves from the switch into the write pane, then into the preview frame
Ctrl or Cmd+SSaves in place; the browser's save-page does not open
  • The panes are regions named "Write" and "Preview"; the frame has a title that says what it shows.
  • The switch is the Segmented control (a fieldset of radios), its legend "Layout" hidden from sight, read by a screen reader.
  • The faded chrome is still in the page and in the tab order; focus inside it brings it back to full strength, and forced colors never fade it.
  • The preview's edge is --line-strong, at 3:1.