Repository navigation
feat(text-editor): pluggable blocks, profiles and a block library - #211
Merged
Merged
Conversation
… and drag handles
…r insert, pointer drag handle Found in the local e2e run: - '/heading 2' closed the menu at the space; Escape left the hidden menu taking Enter and arrows. - Inserting Tabs or Steps left the cursor in the last tab or step body. - The drag handle relied on HTML5 drag and drop; it now follows the pointer with a drop line and moves the block in one undoable transaction.
Contributor
Author
|
Local e2e on the full stack (API, web and sites against a fresh database):
Fixed along the way:
Not part of this PR: on a plain-http dev origin, the docs publish dialog's "Check changes" fails because |
…ploads A Vite app on the workspace @frontlit/text-editor with every library block. Its dev server stands in for a host backend (upload signature and seal), so Image, Video, Audio, PDF and File blocks upload to MediaLit over tus and store only the media ID; resolveMedia maps IDs to URLs in the editor and the renderer. Also shows unavailable, validateContent and serializeMarkdown.
The menu was placed once when it opened, while its list was still empty, so flip() saw room below the caret and never moved it once the items arrived. Re-place it with autoUpdate whenever it resizes or the page scrolls, cap its height to the space available (it scrolls past that), and keep the highlighted entry scrolled into view.
…n readers
Found in an axe and keyboard pass over the editor with every block:
- Block bar text was 4.34:1 on its background; bars now use a slightly
darker muted colour (WCAG 1.4.3).
- The editing area had no role or name; it is now a labelled textbox
(new ariaLabel prop, default "Rich text editor").
- The / menu was silent to screen readers; the editor now points
aria-controls / aria-activedescendant at it while focus stays in the text.
- Blocks could only be moved by dragging; Mod-Shift-Up/Down moves the block
at the cursor. The handle leaves the accessibility tree.
- Tab from a block's text went to the first block's controls; Alt-F10 now
focuses the current block's controls and Escape returns to its text.
- Settings popovers now take focus when opened and give it back to their
button on Escape (it fell to <body>).
- Item remove buttons say which item ("Remove tab 2").
Also adds the README section the docs page already linked to: custom blocks,
keyboard and screen reader use.
…able The highlighted entry had no colour: the menu is portaled to <body>, outside the editor's tokens, so bg-muted painted nothing in hosts without global tokens. It now uses aria-selected styles with fallbacks and a bar in the primary colour (and a system outline in forced-colours mode). Arrow keys also snapped back while the pointer rested over the menu: each step scrolled an item under it and mouseenter stole the highlight. Hover now follows mousemove, and steps read the latest index, so fast key repeats don't drop. Adds the usual list keys: Ctrl+N/P, Tab/Shift+Tab, Home/End and PageUp/PageDown; the highlight starts on the first usable entry.
The / menu now shows entries in sections (Text, Media, Layout, or a block's own insert.group, default "Blocks") with a one-line description under each label, icons in tiles, and a footer listing the keys. Library and docs blocks carry descriptions; BlockUi.insert gains an optional group. Each section is an ARIA group labelled by its heading; options are named by their label and described by their description (or the reason they are unavailable). The menu gets the editor's tokens, since it is portaled to <body>, and description text on the highlight tint is darkened to 4.5:1. Filtering still matches labels and keywords only, so short queries stay precise.
A catch-all `.ProseMirror iframe` rule (from the old YouTube embed) gave every iframe in the editor a black background, rounded corners and a 16:9 ratio. Embed frames are transparent, so their default black text was drawn on black. The video backdrop now lives on .te-video__frame only.
…s, and an agent-readable content format
Blocks (library, enabled in the documentation profile, so the API and MCP
accept them in Markdown):
- <Button label href variant>: a link styled as a button; URLs go through
the same safety checks as links.
- <WebPreview url title description image>: a link card the author or
agent fills in (no server-side fetching).
- <H5P src title height>: an H5P activity in a frame, only from allowed
hosts (h5p({ hosts }), default h5p.org and *.h5p.com).
- Callout gains a success type, and the / menu offers Warning, Tip,
Success and Danger presets (BlockUi.variants).
URL fields in the editor store a value only once the block's own check
accepts it, so autosave never sees a half-typed URL; errors are announced.
For agents:
- contentFormat() / describeContentFormat() in @frontlit/text-editor/docs
describe the format (every block, props, types, an example, limits).
- schema/content.v1.json is generated from it (schema:generate; a test fails
when stale) and served at /schema/content.v1.json on every site.
- MCP create/update tools describe their markdown field from it, so new
blocks need no tool edits; REST contract fields point to the URL.
Quick start with a complete component, a glossary of the core ideas, choosing what the editor allows (base nodes, marks, heading levels and the block library with Markdown forms and options), removing, hiding or disabling blocks (and what happens to existing content), media with pickMedia/resolveMedia, a step-by-step guide to adding a custom block, changing built-in blocks, server validation and Markdown, rendering in server components, keyboard use, agents, styling and an exports table. Every snippet was type-checked against the package.
Incomplete blocks: attributes can be requiredToPublish (Button href,
WebPreview url, H5P src). The editor still saves them empty while the
author types, but incompleteBlocks(profile, content) reports them as
INCOMPLETE_BLOCK diagnostics that block publishing, never saving. Docs
publishing now includes them, and the API refuses Markdown from REST and
MCP that holds one, so an agent can't create an invisible button. (Making
the prop required in Markdown itself would have broken autosave: drafts
round-trip through Markdown.)
Reference: blocks can document Markdown-only props (docs.props), so
<Tabs items>, <Card icon>, <TypeTable type> and <Video url> are listed;
child tags (<Tab value>, <Card>, <Accordion>, <Step>) get their own lines;
the syntax line spells out the accepted literals ("text", {42}, {true},
{["a"]}, {{ k: "v" }}, {<Icon />}); and the description tells agents to
upload files with get_media_upload_signature / register_media and use the
returned URL.
…ct updates Articles and product updates went live without any check, so a Button saved without its link (from the editor or a JSON write) published as an invisible block. Docs already blocked this. - publish_article / publish_product_update (and REST publish) refuse a draft with incomplete blocks: 422 INCOMPLETE_BLOCK with the list. - Every article and product-update response (get, list, create, update, publish; REST and MCP) carries publishable and diagnostics, as docs do, so agents see blockers on save without a separate validate call. - The article and product-update editors show the blockers in a banner and disable Publish with that reason.
…target Cross-platform images were built entirely under QEMU emulation (an arm64 image on an x86 machine took about an hour). Install and build stages now run on $BUILDPLATFORM: their output is JavaScript, identical for every target. Only the runtime stage, and the API's production install, run as the target platform. sharp is the one native module in Next's standalone output: the build stage fetches its binaries for the target (bun install --cpu/--os, at the lockfile's version) and the runtime stage places them beside each traced copy of sharp.
Tables could only grow: the insert menu (+) held "Add table row", "Add
table column" and "Remove table", and nothing deleted a row or column.
With the cursor in a table, a bar above it now inserts a row above or
below, deletes the row, inserts a column left or right, deletes the
column, toggles the header row (rich tables only: Markdown tables always
have one) and deletes the table. It's a toolbar: Alt-F10 reaches it from
the cell, arrows and Home/End move between controls, Escape returns to the
cell, and each control names what it acts on ("Delete row 3"). The old
entries leave the insert menu.
Also: export button(), webPreview() and h5p() from the main entry (they
were only on /blocks), and give the example app tables and those blocks.
…e cursor in the block Found in a browser smoke of the docs editor: - "/warning" inserted a plain info callout: the filter kept menu order, so "Callout" (keyword "warning") came before "Warning callout". Entries whose label matches now rank first; sections stay together. - After an insert the cursor could land in the block above. insertBlock only moved it when the insert left it inside the new block; it now finds the block, puts the cursor in its first text, or on the line after it for blocks without text (Button, Web preview, H5P, an empty card grid). - The scrolling / menu list failed axe scrollable-region-focusable. It is focusable now and hands focus straight back to the editor.
The handle looked for the block under a point 24px inside the editor's left edge, using posAtCoords. In the admin editors that point sits in the content padding, where no position resolves, so the handle never appeared. topLevelBlockAt now finds the block from the blocks' boxes at the pointer height; each block owns the gap below it, so the handle doesn't flicker between paragraphs.
Autolink also makes Tiptap's link mark inclusive, so text typed at the end of a link joined it and a link could not be ended by typing (not even spaces). Keep autolink; make the mark non-inclusive.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Step 1 of the lesson-pages design (CourseLit
docs/wip/lesson-pages.md, §3 and §10): pluggable blocks for@frontlit/text-editor, shipped as one release.What changes
BlockSchemaanddefineProfilein a new@frontlit/text-editor/blocksentry (no React). One profile builds the Tiptap schema/extensions, Markdown parser and serializer, validator with diagnostics, renderer map and a machine-readableformatReference.src/docs. Cards, Code group, Type table and frontmatter stay docs-only.profilestill takes"default" | "documentation"and now also a profile object.Editor unavailable={{ embed: "…" }}greys blocks out in the/menu and Insert menu.validateContent(profile, next, { previous, unavailable })refuses an increase in the count overprevious(block_unavailable, with the reason)./insert menu filtered as you type, a drag handle per block, a settings popover per block, andMediaPickerContextProvider(image/video/audio/pdf/file →{ id, previewUrl }).ImagePickerContextProviderkeeps working.TextRenderertakes profile objects, host components per block (blocks={{ quiz: LearnerQuiz }}) andresolveMedia. React elements only; Embed code runs only in asrcdociframe withsandbox="allow-scripts allow-popups allow-forms".src/coreandsrc/uinever import fromsrc/docs;src/boundary.test.tswalks the import graph and fails with the import chain.Verification
bun run --filter @frontlit/text-editor test: 196 tests (115 existing docs tests unchanged).bun run typecheck,bun run lint,bun run format:check,bun run test(api 792, web 97, sites 86, page-builder 63, text-editor 196) andbun run buildall pass.TextRenderer: identical HTML for every parsed docs page in both profiles, with and without a theme.apps/docsbuilt onorigin/mainand on this branch: all 211 prerendered pages have identical HTML apart from the client-chunk list.apps/docswith a temporary lesson-profile demo, not committed:/menu filtering, Video from a YouTube URL, Audio from the media picker, settings caption set and cleared, Embed greyed out with its reason, the availability diagnostic, and moving blocks with the drag handle. The default editor was also checked: menus, base64 upload and/table.Notes for CourseLit
option,details,summaryandsectionare CommonMark HTML block names. A one-line<Option …>text</Option>is therefore read as raw HTML and refused. Write nested tags across several lines, as the serializer does. The §4.2 example needs that.