Skip to content

Latest commit

 

History

History
222 lines (168 loc) · 12.9 KB

README.md

File metadata and controls

222 lines (168 loc) · 12.9 KB

datasette-paper

PyPI Changelog Tests License

Collaborative document editor for Datasette. ProseMirror frontend, SQLite-backed storage in Datasette's internal database, real-time collaboration over SSE.

The paper editor: a rich-text document with headings, a table and a task list, a formatting toolbar, and a header showing the author, edit time and number of users online.

Rich text with tables and task lists, wiki-style links between papers, images (paste, drag-and-drop, or insert from the toolbar), and per-paper sharing:

A table in the editor with the floating action bar for adding/removing rows and columns and naming the table for the API. A task list with checkboxes; completed items are struck through.
Typing [[ opens an autocomplete popup listing other papers to link to. The share dialog showing people with access and their roles, plus general link access.
Hovering a link while editing reveals a tooltip with Edit, Open and Copy; Edit opens a small dialog with Text and URL fields to rewrite the link.

Insert an image by pasting, dropping a file, or using the toolbar's image button — which offers a paste area or a file upload with a live preview:

The insert-image dialog with the Upload tab active, showing a preview of the chosen image, an alt-text field, and an enabled Insert button.

And a paper index listing everyone's papers with author and last-edited time:

The paper index: a table of papers with name, creator and updated time, plus tabs for Active / Archive / Trash / Templates.

The link graph turns those [[wiki links]] into an interactive map of the workspace — force-directed and zoomable, with nodes colored by tag / state / kind (the legend doubles as a filter), sized by connections or recency, and a metadata panel for the selected paper. Every paper also gets a doc-centred ego view from its sidebar: just that paper's neighbourhood, sliceable to an adjustable link depth:

The link graph modal: a force-directed graph of papers colored by tag with a legend filter, search, and a metadata panel showing the selected paper's kind, state, links and tags. The doc-centred ego view: the focus paper ringed at the centre of its depth-1 neighbourhood, with a Depth selector to widen the slice.

Drop inline #tags anywhere in a paper's body — type # for an autocomplete of existing tags. Clicking a tag opens a results page listing every paper whose body mentions it:

Inline #tag pills in a paper's body, distinct from the document-level metadata tags. The tag results page: every paper whose body contains #roadmap, each with a mention count.

Drop an inline date anywhere — type /date (or press Cmd/Ctrl-;) for today, or /today / /tomorrow / /yesterday. Each renders a compact calendar chip that round-trips through markdown and can carry a time + timezone (shown in each reader's own zone). A date inside an unchecked task tints overdue (red) or due today (amber); checking the box clears it. Click a chip to edit it in plain language (next fri 3pm, 7/20) and pick a display format:

Inline date chips: a neutral date in prose, and in a task list a red overdue date, an amber due-today date, and a struck-through completed task whose date is neutral. The date chip's edit popup: a natural-language input with a live preview, and a labelled radio list of display formats (Default, ISO, Medium, Long, Weekday, Short) each showing its own rendered example, plus a custom strftime field.

Installation

Install in the same environment as Datasette:

datasette install datasette-paper

Quickstart

datasette --internal papers.db \
  -s permissions.datasette-paper-create true

Viewing and editing are granted per paper through the share dialog, not globally — see Permissions.

No user database is required — papers live in Datasette's internal database.

Pass --internal <path> to persist papers across restarts. Without it, Datasette uses an ephemeral tempfile for the internal DB that is deleted when the process exits. The plugin emits a startup warning when it detects this, so you don't lose your papers to a forgotten flag.

Permissions

One global action, set in Datasette config, plus three per-paper actions resolved by datasette-acl grants. See docs/PERMISSIONS.md for the full model.

Action Scope Resolved by
datasette-paper-create global Datasette config (-s permissions.* / permissions: block)
paper-view per-paper (PaperDocResource) datasette-acl grants
paper-edit per-paper (also-requires paper-view) datasette-acl grants, denied while the paper is locked
paper-manage per-paper (also-requires paper-view) datasette-acl grants (the Manager role)

Listing is ungated: the index and list endpoints return only the papers the actor can view. Don't grant the per-paper actions globally in config — that bypasses sharing and lets every actor read and edit every paper.

Sharing

Whoever creates a paper is its owner and gets a Manager grant on it automatically. The share dialog grants people one of three cumulative roles:

  • Viewer — can view the paper.
  • Editor — can view and edit it.
  • Manager — can also manage sharing, lock, archive, and template it.

A general access row grants a role to everyone signed in, in place of naming individuals. Access changes apply immediately, including to anyone with the paper open — a revoked collaborator's live connection is dropped.

Profile integration

When datasette-user-profiles is installed, each person's profile page grows a Papers section (registered via its datasette_user_profile_sections hook). It lists the papers that actor created plus the ones they've recently edited, newest activity first, each badged Created / Edited. The list is filtered to the papers the viewer is allowed to see — a paper you can't open never shows up on someone else's profile. The section is populated from GET /-/paper/api/profile/<actor>/docs.

A user-profiles profile page with a Papers section listing the papers that actor created or recently edited, each badged Created or Created · edited with a relative time.

The same integration adds a TODOs section listing that person's open assigned tasks (see Task assignment below), viewer-filtered the same way.

Task assignment

A @mention inside a task item assigns it to that person; a date atom inside the item is its due date. It's pure interpretation of the document — no task ids, no assignment records, no extra editor UI. Assignment inherits down a task's subtree (a sub-task with no mention of its own takes the parent's assignee), and the first date atom wins as the due date.

The dedicated /-/paper/todos page collects a person's assigned tasks across every paper the viewer can see, bucketed by due date in the viewer's timezone — Overdue / Today / This week / Later / No due date — with a status toggle for open / done / all. It's read-only: each row links into its paper, where you check the box. Both this page and the profile TODOs section are fed by GET /-/paper/api/profile/<actor>/todos, viewer-filtered so you only ever see tasks in papers you're allowed to open.

The /-/paper/todos page: a person's assigned tasks grouped into Overdue, Today, This week, Later and No due date, each row showing a checkbox, task text, assignee chips, a due-date chip tinted red (overdue) or amber (today), a section breadcrumb and the paper it lives in.

The TODOs section on a user-profiles profile page: the person's open assigned tasks, each with a checkbox, assignee chips, a due-date chip and the paper it lives in, plus an 'All TODOs' link to the full page.

Papers as data

Paper data lives in Datasette's internal database under tables prefixed with _datasette_paper_:

  • _datasette_paper_doc — one row per paper (id, name, state, kind, created_by, locked).
  • _datasette_paper_step — append-only log of ProseMirror steps.
  • _datasette_paper_snapshot — periodic full-document snapshots.
  • _datasette_paper_link — the [[wikilink]] graph between papers.
  • _datasette_paper_doc_tag / _datasette_paper_inline_tag — document tags and the index of inline #tag atoms.
  • _datasette_paper_doc_activity — per-paper, per-person last-edited rollup.
  • _datasette_paper_task_assignment — index of assigned tasks for TODOs.

Sharing grants live in datasette-acl's own tables.

Wire protocol

JSON API rooted at /-/paper/api/... — no per-database segment. List/create docs, bootstrap a paper, post step batches, stream updates over SSE, render markdown / extract tasks. Route handlers live in datasette_paper/routes/.

Frontend stack

Vite + Svelte 5 + ProseMirror. Bundle outputs to datasette_paper/static/.

Development

npm install --prefix frontend
just frontend          # build the bundle
just dev               # run datasette with the plugin + permissions granted
just dev-with-hmr      # vite dev server + watchexec restart
just shots             # regenerate docs/screenshots/*.png (used in this README)

just shots is self-contained: it builds the bundle, boots a throwaway Datasette with seeded papers, drives Playwright to capture each surface, and tears the server down. The PNGs are committed, so re-run and commit when the UI changes (the diff shows what changed). Pass shot names to regenerate a subset, e.g. just shots editor tables.

Run the test layers:

just test              # backend pytest
just test-frontend     # vitest
just test-e2e          # playwright (requires built bundle)

Always invoke Python with uv run --prerelease=allow … — datasette is on a >=1a23 pre-release pin.