GrRichText

There is no separate sanitiser in the package, and that is not an omission. ProseMirror parses the input by the schema: a node or a mark that is not in it is discarded during the parsing, and on the way out the document is serialised from that same tree. <script>, <iframe> and <img> do not survive a paste — proven by a test rather than promised.

Hence a consequence worth knowing: what is not in the schema will not be in the value either. If an article with pictures was pasted into a field with the minimal schema, the text remains. That is a deliberate trade: a field accepting arbitrary markup breaks the layout of the page it will later be shown on.

minimal is the style, a link, a list. article adds structure: headings, a quote, a code block.

Neither gives a first-level heading. There is one h1 on a page and it belongs to the page rather than to an input field inside it; an editor that lets a second one be inserted breaks the structure of the document for someone who was simply typing text.

The buttons are built from the list of actions of the schema itself. Write them by hand and the very first edit of the schema would diverge from the panel silently: the button remained, and the command behind it is no longer there.

The panel wraps by whole groups rather than button by button. A flex-wrap over individual buttons would tear the row where the room ran out and would separate buttons of one meaning: “Heading” on one line, “Subheading” on another, and without a separator between them. The wrapper of a group does not allow that — in a narrow field the lines read as the same blocks as one row.

The toolbar is a role="toolbar" with one Tab stop: inside, the arrows do the walking. Otherwise reaching the text itself would take a dozen presses — “article” has ten buttons. The active format is announced with aria-pressed rather than only by the highlighting: the highlighting does not exist for a screen reader.

toolbar="bubble" puts the panel at the selection, "both" both above and at the selection.

The bubble lives exactly while there is a non-empty selection and focus in the field: the loss of focus is enough for it to go out. Hence two non-obvious consequences, and both sit in the code:

• the panel does not take the focus on opening — otherwise it would put itself out in the same frame in which it opened;
• a button of the bubble cancels mousedown. Without that the focus would go to the button and the bubble would disappear under the cursor after the very first format — there would be nothing to apply a second one with. The panel above does not need that: it does not depend on the focus.

The buttons of the bubble are always of the smallest step, regardless of the size of the field. The panel above lives in the frame of the field and grows with it, while the bubble hangs over the text that is being read, and there the smallest area that gives a press target of 28×28 is appropriate — above the twenty-four required by WCAG 2.2. There is an arithmetic reason as well: the panel of a popover is limited in width, and a dozen buttons of the size of the field did not fit into it.

Esc closes the bubble, and a click outside does not: click would have to be listened for, and it is exactly what a drag of the selection ends with, so the panel would close at the very moment it is supposed to appear.

The anchor of the bubble is the rectangle of the selection in viewport coordinates, and scrolling with the wheel does not change the selection. So while the bubble is on, the anchor is recalculated on scroll and resize — scroll is listened for in the capture phase on window, so as to catch the scrolling of a nested area as well, not only of the page. When the selection leaves the visible part of the field or the page, the bubble hides rather than being left hanging over someone else’s content; once it is back, the bubble is beside it again. Scrolling does not bring back a bubble closed with Esc.

The visible part is also cut by the scroll-padding of every scroll area, the page included: that is how a site declares its sticky header (html { scroll-padding-top: 80px }). A selection under the header hides the bubble; right at its edge, where there is no room above the selection, the bubble sits below it rather than on the header. The side is chosen by the field — GrPopover knows nothing of scroll-padding and keeps clear of the viewport edge only.

Whether to show and on which side are two different questions with two different areas. Whether the selection is visible is decided by all clipping ancestors, the field included: a selection that has left the edge of its own scroll hides the bubble. The room for the bubble, though, is the page outside the field: the bubble lives in the top layer, and the field does not clip it. The field’s own scroll (.ProseMirror with overflow-y: auto) and its frame do not count — the bubble lies over the toolbar and the field above the first line, and goes below only when there is no room above the selection on the page, for example at a sticky header. Otherwise it would cover the next line, the one being read.

The keyboard path to the formats in this mode is the hotkeys: the panel at the selection is not a Tab stop. If both roads are needed — toolbar="both".

The #header and #footer slots give strips above the input area and below it, inside the same frame:

<GrRichText v-model="value">
  <template #header>To: <strong>[email protected]</strong></template>
  <template #footer>Characters: {{ length }}</template>
</GrRichText>

There used to be exactly two zones — the toolbar and the text — so a label with a counter was put outside the frame. Visually they turned out to be a separate element: the frame outlined only the text, and the link with the field rested on proximity rather than on the markup.

The zones are marked off with a rule from the inside, like the toolbar — the line belongs to the boundary between zones rather than to a zone: at the edge of the field it would run into the rounding of the frame. They deliberately have no background: --gr-muted is laid under the toolbar because it is a control panel, while here there is the consumer’s content, and a second backdrop would argue with it.

The keyboard of the zones is the consumer’s concern: the toolbar walks the focus over its own buttons with a rover, and what has been put into the header the component does not know.

output="html" (the default) is a string of markup; output="json" is a TipTap document. The same device as valueAdapter in granularity-chrono: the shape of the value is chosen by the consumer rather than by the behaviour of the user.

Into a native form the value goes as a string in any mode: a hidden field cannot do objects.

The field is needed while the text is being edited. For showing what was saved it is not the best choice: ProseMirror requires a DOM, so on the server nothing is printed (see the next section), and in the browser an editable document with plugins, transactions and history is raised for the sake of a single paragraph.

The TipTap document is translated into markdown and given to GrMarkdown:

<script setup lang="ts">
import { computed } from 'vue'
import { markdownFromEditorDocument } from '@feugene/granularity-editor/markdown'
import GrMarkdown from '@feugene/granularity-editor/components/GrMarkdown'

const { document } = defineProps<{ document: object }>()
const source = computed(() => markdownFromEditorDocument(document))
</script>

<template>
  <GrMarkdown :source="source" />
</template>

There are no losses on this path for any of the schemas. The serialiser knows every node and every mark they are able to produce — down to the line break by Shift+Enter; it serialises a picture as well, although no schema gives one yet. When adding an extension of your own with a new node, a branch in the serialiser will have to be added along with it: what is lost silently is exactly what you added.

It is also fit for storage: output="json" holds the TipTap document, while markdownFromEditorDocument puts markdown into the database — a form that both a person and any other tool will read.

ProseMirror requires a DOM, so the editor is raised after mounting, and the server markup is a shell with data-allow-mismatch. There is no text in it, but there is room: the host holds a placeholder with the same box the input area will take — --gr-rich-text-min-height and --gr-rich-text-max-height are shared by both, in one rule. A field with min = max does not move on hydration; a value taller than min-height with an open max-height grows to fit the text after mounting — see ../ssr.md.

There is deliberately no v-html in the package: printing someone else’s markup for the sake of the first frame would mean introducing the single XSS surface exactly where the data comes from the user. A field is input rather than publication.

extensions adds TipTap extensions to the schema rather than replacing it:

<script setup lang="ts">
import { CharacterCount } from '@tiptap/extensions'
</script>

<template>
  <GrRichText v-model="text" :extensions="[CharacterCount.configure({ limit: 500 })]" />
</template>

The ready extensions are listed in the TipTap catalogue, and one of your own is written by the guide. The package does not wrap them: what was handed over is what the editor gets.

A change of the set — like a change of schema — rebuilds the editor: a ProseMirror schema is immutable, and both the document and the commands are derived from it. The text is carried over as markup and goes through the parsing again, so a node that is not in the new schema is discarded — the same rule as on a paste.

The toolbar will not show a button for an extension of your own: it is built from the schema, and a button with no command behind it would be a deception. A button of your own is put in with the #action-<key> slot or with a panel of your own over the instance from defineExpose.

• not a CMS: no pictures, no mentions, no tables in this release. A TipTap extension is added by the consumer themselves through extensions, and the instance of the editor is given away by the component through defineExpose. The toolbar will not show a button for an extension of your own: it is built from the schema rather than from the set of extensions;
• no collaborative editing: simultaneous editing by two people requires a transport and conflict resolution, and that is not the task of an input field.