DocsFrontend

Pages

A Notion-style editor any app can mount: blocks, folders, boards, forms and sign-ups.

Pages is a plugin. To use it, install it with sluurp plugin add pages, add the components it draws with (Components), then set it up once and draw its screen:

main.tsx
import { configurePages, PagesScreen, PagesToolbar } from "@sluurp-plugins/pages/client/index.ts";

configurePages({ client, me, t, href, detail, notify, complain });

<PagesToolbar />
<PagesScreen />

Features include:

  • Blocks: text, headings, lists, to-dos, quotes, code, tables, images, embeds, charts, boards, figures, pull quotes, and nested pages.
  • Inline Markdown, Typora-style: **bold**, *italic*, `code`, ~~strike~~, ==highlight== and [text](url) are formatted as you type; the markers show faintly on the current line and hide when you leave it. Ctrl+B / I / E, Ctrl+Shift+X / H and Ctrl+K (link) toggle formatting on the selection, and so do the buttons that appear over selected words. Lines are stored as Markdown.
  • Links, people, topics and math in a line: @ offers pages and people to link to, # offers the topics already in use (#pricing), and $x^2$ is drawn as a formula. A topic links to a list of every page that has it.
  • Pictures are resized by dragging their corner, or with the arrow keys; double-click the corner to go back to the default width.
  • Simple tables show a + on the line between two columns or two rows: point at it to see where the new one will go, and click to add it there.
  • Reading mode, a books view, and a graph of links between pages.
  • Version history in the core change log (who, when, why), with restore.
  • Ask AI, or chat about a page, when a model is set up.

Try a page

This one is editable: type / for the block menu, drag blocks by their handle, and select text to format it. In an app, pages are saved with history; this demo only lives in this tab.

Magazines and articles

A folder can be shown as a magazine front page: the newest article large, the rest as cards. Any page can use the article layout: the folder’s name as a kicker, a large serif headline, the description as a deck, a byline with reading time, a cover image, a narrow column with a drop cap, and figures (with caption and credit) at column, wide or full width, or floated left or right, rectangular or round.

In reading mode, articles are typeset line by line with Pretext:

  • Text wraps around floated and round figures and the drop cap, following a round image’s curve.
  • Paragraphs are justified with Knuth–Plass: all the line breaks of a paragraph are chosen together to keep spaces even, so a loose line never follows a tight one. Rivers (spaces over 1.5× normal) and over-squeezed spaces (under ⅔) are avoided when possible.
  • Hyphenation uses TeX’s Liang patterns for English, French, German and Romanian, with a penalty per hyphen and a bigger one for hyphens on lines in a row. The last line is ragged.
  • Bold, italic, code, links and topics are kept, and inline formulas are drawn as formulas. Lines are real text, so selection, copy, Comment and Ask work, and screen readers still get paragraphs.
  • Tables, boards and charts are drawn normally between typeset runs.

An article’s PDF uses the same layout on A4, embedding Source Serif 4 (the font the lines were measured with), so text wraps around round images on paper too. Colour emoji are drawn as images; elsewhere in PDFs they use Noto Emoji.

Boards

A board is a FigJam-style whiteboard inside a page: sticky notes (with their author), text, shapes (rectangles, circles, stars, and speech bubbles whose tail you drag) and sections.

  • The wheel moves the board, Shift and the wheel move it sideways, and a pinch or Ctrl and the wheel zoom; Space and a drag pan too.
  • Select, move, resize, recolour, duplicate, undo and redo; double-click a note or a shape to edit its words.
  • Connectors (C, or drag the link handle, which follows the pointer round what is selected, so a line can start from any side) join items with arrows, labelled if you like, so a board can become a concept map.
  • Everyone on the page sees changes and each other’s cursors live.

Multiplayer

Multiplayer works like Figma’s:

  • A change carries only the fields it touched, and the server merges them. Two people editing different fields of the same note (one moves it, one recolours it) both keep their change; for the same field, the last write to reach the server wins.
  • The server orders every change and broadcasts it, so all clients apply changes in the same order. While your own change is on its way, others’ changes to that field are held back, so values don’t flicker.
  • A client that reconnects loads the board again and replays its changes that weren’t acknowledged.
  • Undo reverts only your own changes, worked out against the board as it is now, so redo never overwrites someone else’s edit.
  • Changes are appended to a journal. Every 50 changes, the board is compacted into its page and the journal trimmed, so busy boards don’t rewrite the page on every drag. Reads apply newer journal rows on top.
  • Layer order uses fractional indexes, so two people bringing items to the front at once don’t collide.

Board tools

  • Timer (1, 3, 5 or 10 minutes, +1 minute, pause, stop), in step across screens, with a soft chime.
  • Voting stamps (B): click again to take a vote back. Stamps stay on top of their note, move with it and can be resized; sections show vote totals (“2 votes”), and “Clear votes” resets them.
  • Pen (P) with smoothing, six inks and three widths, and an eraser (E).
  • Laser pointer (K): a trail everyone sees, which keeps up with a fast hand and fades into sparks. It isn’t saved.
  • Images from the toolbar or by pasting. Large ones are scaled down, stored with the page, and count toward quotas.
  • Mind maps (M): Tab adds a child and Enter a sibling, laid out to the right with a colour per first-level branch and curved links. Ideas asks the AI model for branches to keep, edit or delete. Mind maps are ordinary notes and links, so they can grow into a concept map.
  • One style panel for everything selected: colour, shape, text (size, bold, italic, alignment), stroke and fill (hatched, cross-hatched, solid), stroke width and style, sloppiness (neat, hand-drawn or scribbled, via rough.js), corners, arrowheads, opacity and layer order. Drag it by its title, or close it. Several notes selected together take a colour at once. Sketches are seeded by id, so they look the same everywhere.
  • Board text is indexed for search.

Folders: sections made of pages

A folder is a page that holds pages and lists them as rows. That’s how a section of an app, say a catalogue of workshops or bookable rooms, is built from pages instead of custom screens.

  • Properties. The folder defines the fields each child page has (props): a day, a host, a capacity. Each page fills them in (values) under its title.
  • Formulas. A formula property is computed from the page’s values and its table: rows is the row count, consent.yes counts the rows where consent is “yes” (any field and value, in lower case), and cost.sum sums a numeric column. places - rows gives the places left, updating as people sign up.
  • New. The folder names a template; New makes the next page from it inside the folder.
  • Navigation. A folder marked nav becomes an app section for everyone who can read it, with its own icon. Only its creator or a superuser can set this.
  • Icons. An emoji, a built-in icon (icon:calendar), or your own SVG (svg:<svg…>). SVGs are cleaned down to shapes and paint: no scripts, handlers, links or styles.
migrations/V6__workshops.json
{ "pages": [
  { "id": "workshops", "name": "Workshops", "kind": "folder", "nav": true,
    "template": "page:workshoptpl",
    "props": [
      { "name": "places", "title": "Places", "type": "number" },
      { "name": "places_left", "title": "Places left", "type": "formula", "formula": "places - rows" }
    ] },
  { "id": "pottery", "name": "Pottery", "parent": "workshops",
    "values": { "places": 12 }, "fields": [{ "name": "member", "type": "relation", "relation": "users" }] }
] }

Property types are text, number, date, bool, select (with values), person and formula. Table columns can also be file; table views are table, board, timeline or gallery.

Forms

Columns are defined by their label. In the columns dialog you type the question or heading, for example “May we share your photo?”, and it gets a slug (may_we_share_your_photo) for rules and filters, with the label kept as the heading. That’s how a form’s questions become columns. Labels can be edited any time; the slug stays.

The same dialog builds the rest of a form. Yes or no makes a two-option select in one click. Required is the red star after a question: people answering see it starred, with a list of what’s still unanswered. Reorder questions by dragging the icon (it becomes a handle on hover) or with the arrow keys. This is stored per column in the page’s columns: { "may_we_share_your_photo": { "title": "May we share your photo?", "required": true } }.

A file column holds an image or a document, shown as a thumbnail in the cell. Tables with a file column can use the gallery view: a grid of images with titles. Add pictures uploads several at once, one row each. Opened images show at full size, with the arrow keys or a swipe for the next and previous.

Actions

An action block ({ "type": "action", "action": "tell" }) places a button that runs app code. The app defines the actions; pages only place them:

app.ts
configurePages({
  actions: () => ({
    tell: {
      label: (page) => (page.values?.told ? "Tell them again" : "Tell the attendees"),
      may: () => isStaff(),
      confirm: () => "Each attendee gets a message with the event and the link to answer.",
      run: async (page) => `${await writeToAttendees(page)} attendees told`,
    },
  }),
});

may decides who sees the button (by default, the page’s editors), confirm asks before running, and what run returns is shown as a toast. An event’s page might have two: tell the attendees, and bill the ones who said yes.

Panels

Apps can add side panels to any page, opened from a header button, such as a discussion thread or a checklist about the page:

app.ts
configurePages({
  panels: () => [{
    name: "discuss",
    label: () => "Discuss",
    icon: () => discussIcon,
    render: (page) => discussion(page.id),
  }],
});

render runs only when the panel opens. may decides which pages and people see it (by default, all).

Sign-ups

A page can take sign-ups: people add their own row to its table without the right to edit the page, such as a member joining a workshop, or a parent signing up their child.

"join": {
  "rule": "@request.auth.roles ~ \"member\" || @request.auth.roles ~ \"parent\"",
  "limit": "places",
  "open": "open",
  "self": { "field": "member", "via": "guardians.child.guardian" }
}
  • rule: who can join.
  • limit: the most rows, a number or the name of a page value.
  • open: a page value that must be true for sign-ups to be open.
  • label: the button’s text (“Answer” for forms; by default “Sign up”).
  • self: the field that says who a row is for, either the person joining or, with via, someone they’re responsible for. guardians.child.guardian means a guardians row whose child is the row’s person and whose guardian is the person joining.

All of this is enforced on the server, and each row’s creator is recorded in by. People who join can edit their own row’s answers but not who it’s for or who owns it, and can withdraw only their own rows. Editors can add and remove anyone. The last place can’t be taken twice by sign-ups at the same moment. In the UI, people get a Sign up button (with a name picker if they sign up someone else) and a list of their sign-ups with a button to withdraw.

Claim a slot

With "claim": true, people claim rows already there instead of adding them. Editors make the slots, such as 15-minute calls or a volunteer rota; people pick a free one under Choose a time, fill it in, and can give it back. One each, or up to limit.

They can’t add or delete rows, edit a slot they don’t hold, or take someone else’s, and two claims on one slot at once can’t both win. Editors see who holds each slot; people don’t see each other. Over the API, claim with {"by": "<user id>"} and give back with {"by": null}.

Charts in a page are chart blocks; see Charts.

View as Markdown