Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// model → DOM. ONE renderer for the editor, the reader, print and (later) the
// file-manager preview, so those surfaces can never disagree about what a
// document looks like.
//
// The renderer emits REAL SEMANTIC TAGS — h1..h3, ul/ol/li, blockquote,
// pre>code, figure — never divs with classes. That buys the screen-reader
// story, native ⌘F, print fidelity and lossless markdown export at once, from
// one decision.
import { type SpacesDoc, type Page, type Block, loadsRemotely, assetValue, tableOf, linkCard, coverSrc } from './model'
import { proceduralCoverSvg, proceduralCoverFor } from './procedural'
import { sanitizeInline, inertBody, esc } from './sanitize'
import { decorateTags } from './tags.ts'
import { tokenize } from './highlight'
import { t, locale } from './i18n'
import { TAG_OF, LIST_OF, SPEC, TONE, mediaPlayback } from './blocks'
import {
fieldByKey, fieldsOf, optionOf, viewRows, headerLength, propBlockOf,
passesFilter, filterCount, unknownFilterKeys, unknownSourceKeys,
sortRows, unknownSortKeys, sortDirOf, layoutOf, nextLayout,
type ViewSort, type FieldSpec, type ViewLayout, type IssueRow,
} from './fields'
import { ganttModel } from './gantt.ts'
import { workloadModel, workloadOption, bucketField } from './workload.ts'
import { todayISO } from './journal.ts'
// THE SHARED CHART ENGINE, from the kernel and not from this app. dash already
// imports it from outside slides, so this is a settled cross-app path rather
// than a new one — and it is read-only: kernel/src is a serialized zone.
import { chartSnapshotSvg } from '../../kernel/src/charts.ts'
import { renderCalendar, spanOf, nextSpan, spanButton } from './calendar.ts'
import { unknownFilterOps } from './query.ts'
import { answer, feed, freshContext, type CalcCtx } from './calc.ts'
import { ICONS, type IconName } from './icons'
import { applyDesign, resolvePageDesign, type Resolved } from './designs.ts'
import { renderCanvasHead, placeCard } from './canvas.ts'
import { viewEmbed, anchorOf } from './embed.ts'
import { markRefs, notesOnPage, noteOf, noteId, refId, type PageNotes } from './footnotes.ts'
import { renderChartBlock } from './charts.ts'
export interface RenderOpts {
/** editable per-block hosts (the editor); false for reader/print */
editable?: boolean
/** resolve a page id to its title, for link chips and pagelink blocks */
titleOf?: (pageId: string) => string | undefined
/**
* This READER's preferred width for a page that does not state one.
*
* Viewer-scoped, like locale and the pane width — never a document field. It
* is a fact about the screen somebody is sitting at, so two people opening
* one space each get their own answer, and neither writes it into the file.
*/
readerWidth?: 'wide' | 'full'
/** collapsed toggles render OPEN — print always passes this */
forceOpen?: boolean
/** rendering to paper: no controls, because paper has no buttons */
printing?: boolean
/**
* Has the READER agreed to load this remote url?
*
* A VIEWER-scoped decision, never a document field — the same rule as locale
* and reduced motion. Putting consent in the file would mean the author
* decides whether the reader phones home, which is precisely backwards, and
* it would travel to the next person the file is mailed to.
*/
allowRemote?: (src: string) => boolean
/**
* The pages already open above this render, host page first — the embed
* cycle and depth guard (embed.ts `viewEmbed`).
*
* NOT a document field and not module state: it is a fact about one render
* pass, and two surfaces render at once (the editor canvas and the still
* preview), so a shared counter between them would be a race that only shows
* up in a saved thumbnail. `renderBlocks` seeds it with the page it was
* given, so nothing outside this file ever has to pass it.
*/
embedChain?: readonly string[]
/**
* DERIVED, and set by `renderBlocks` for its own descent — never by a caller.
*
* Footnote numbering is a fact about a whole PAGE (order of appearance), and
* `renderBlock` draws one block, so the numbering has to arrive from above.
* It rides in the options rather than as a fifth parameter for the same
* reason `calc` does not: every intermediate would have to thread it.
*/
footnotes?: PageNotes
/** the page whose numbering `footnotes` is — DOM ids are document-global and
* print draws every page at once, so a label's ids are scoped by page */
footnoteScope?: string
/**
* The design the PAGE ROOT carries (renderPage only). Absent = this page's
* own resolved design (designs.ts resolvePageDesign); `null` = none, for a
* caller that styles the result itself (the static preview's inline rules).
*
* Only a page ROOT ever carries one. Everything rendered INSIDE a page — a
* gallery card, a view's rows, a page card, a transclusion embed — is built
* by renderBlocks under the host's root and so wears the HOST's design: the
* design is the page you are on, not the page a card points at.
*/
design?: Resolved | null
}
// The tag and list maps come from the block registry (blocks.ts), so a new
// block type declares its element once instead of being added here, to the /
// menu, to the autoformat table and to the markdown exporter separately.
/**
* Render one page's blocks.
*
* Nesting is `Block.parent`, and the array is pre-order, so a child always
* follows its parent. That is what lets a single forward pass build the tree
* without a lookup table.
*/
export function renderBlocks(page: Page, doc: SpacesDoc, opts: RenderOpts = {}): DocumentFragment {
const frag = document.createDocumentFragment()
// The embed guard starts here, with the page being drawn, so an embed of the
// page you are ON is a cycle at depth zero. Seeded rather than mutated: the
// caller's opts object is not ours to write to.
if (!opts.embedChain) opts = { ...opts, embedChain: [page.id] }
// FOOTNOTE NUMBERING IS COMPUTED ONCE, HERE. It is order-of-appearance over
// the whole page, so no block can work it out on its own — and it is derived
// every paint rather than stored, so inserting a reference renumbers
// everything after it with nothing to keep in step (src/footnotes.ts).
const fnotes = notesOnPage(doc, page)
if (fnotes.order.length) opts = { ...opts, footnotes: fnotes, footnoteScope: page.id }
// MAGIC NOTES' CONTEXT, accumulated as the pass goes. A name is defined by a
// line and usable by the lines BELOW it — the same direction a person reads
// in, and the reason this needs no second pass and cannot cycle.
const calc: CalcCtx = freshContext()
// stack of open containers, innermost last: [blockId, element, type]
//
// The TYPE is on the stack because a canvas's children are POSITIONED and
// nothing else's are. A block cannot know that on its own — `x` and `y` mean
// "where on the surface" only inside a surface — so the placement decision
// belongs here, where the open container is known, rather than to a test on
// the child that would also fire on a stray `x` anywhere else in a document.
const stack: Array<[string, HTMLElement, string]> = []
let list: { el: HTMLElement; kind: 'ul' | 'ol'; under: string } | null = null
const hostFor = (parent: string | undefined): HTMLElement | DocumentFragment => {
while (stack.length && stack[stack.length - 1][0] !== parent) stack.pop()
return stack.length ? stack[stack.length - 1][1] : frag
}
// FIELDS AT THE TOP ARE A HEADER STRIP — by position, not by a flag.
//
// `prop` blocks that precede the first non-prop block are drawn as one
// compact row under the title; the same blocks further down render inline.
// Nothing in the format says "this is a header", so a build that predates all
// of this shows exactly the same values in exactly the same order, just
// stacked — which is the whole reason the header is a convention rather than
// a container.
const head = headerLength(page)
let strip: HTMLElement | null = null
if (head > 0) {
strip = document.createElement('div')
strip.className = 'sp-props'
frag.appendChild(strip)
}
page.blocks.forEach((b, i) => {
// MAGIC NOTES' CONTEXT IS FED AFTER THE BLOCK IS DRAWN, not before, and the
// order is the whole difference between `sum above` working and reading 0:
// an answering line ENDS the run of figures it summarises, so feeding it
// first cleared the very run its own answer needed. After means a line sees
// exactly what is above it and nothing of itself — which is also what makes
// a name usable by the lines below and by none above.
const takeIn = () => feed(calc, textFromHtml(b.html))
if (strip && i < head) {
strip.appendChild(renderBlock(b, doc, opts, calc))
takeIn()
return
}
const host = hostFor(b.parent)
const kind = LIST_OF[b.type]
// adjacent same-kind list items share one <ul>/<ol>
if (kind) {
if (!list || list.kind !== kind || list.under !== (b.parent ?? '')) {
const el: HTMLElement = document.createElement(kind)
el.className = 'sp-list'
host.appendChild(el)
list = { el, kind, under: b.parent ?? '' }
}
} else {
list = null
}
const node = renderBlock(b, doc, opts, calc)
takeIn()
const into = kind && list ? list.el : host
into.appendChild(node)
// A CARD IS PLACED AFTER IT IS APPENDED: its index among its siblings is
// the fallback position for a card that has never been dragged, and the
// index is a fact about the parent, not about the block.
if (stack.length && stack[stack.length - 1][0] === b.parent && stack[stack.length - 1][2] === 'canvas') {
placeCard(node, b)
}
// A CONTAINER owns the blocks whose parent is its id. Which types those are
// is registry data (blocks.ts `container`), not a name test here — the
// second container type is what turned `b.type === 'toggle'` from a fact
// into a bug waiting for the third one.
const container = SPEC.get(b.type)?.container
if (container) {
const body = document.createElement('div')
body.className = `sp-${b.type}-body`
if (container === 'fold' && !(opts.forceOpen || b.open)) body.hidden = true
node.appendChild(body)
stack.push([b.id, body, b.type])
list = null
} else if (kind) {
// A LIST ITEM OWNS ITS INDENTED CHILDREN.
//
// Tab already wrote `parent` (editor.indent), and nothing rendered it:
// only registry containers opened a body, so an indented bullet came out
// flat and Tab was a key that did nothing you could see. The <li> IS the
// host — that is what HTML nesting is — so a child list starts inside it
// and `list.under` changing is what makes the grouping open a fresh
// <ul>/<ol> at the deeper level.
//
// Not `container: true` in the registry: a list item does not take a body
// div, it takes children directly, and the gutter/inline-host rules that
// `container` implies are wrong for it.
stack.push([b.id, node, b.type])
}
})
return frag
}
export function renderBlock(b: Block, doc: SpacesDoc, opts: RenderOpts = {}, calc: CalcCtx = {}): HTMLElement {
const type = b.type
const el = document.createElement(TAG_OF[type] ?? 'div')
el.dataset.blockId = b.id
el.dataset.type = type
el.className = `sp-b sp-b-${type}`
switch (type) {
case 'divider':
el.className = 'sp-b sp-b-divider'
el.appendChild(document.createElement('hr'))
return el
case 'code': {
const pre = document.createElement('pre')
const code = document.createElement('code')
// `language-xx` is the convention every markdown pipeline already reads,
// and it carries the author's raw tag even when this build cannot
// highlight it. esc() because it lands in a class attribute.
if (b.lang) code.className = `language-${esc(String(b.lang))}`
if (opts.editable) { code.contentEditable = 'true'; code.dataset.edit = b.id }
paintCode(code, textFromHtml(b.html), b.lang)
pre.appendChild(code)
el.appendChild(pre)
return el
}
case 'image': {
const fig = document.createElement('figure')
const rawSrc = String(b.src ?? '')
// A REMOTE image is not loaded until the reader asks for it.
//
// Measured: a space carrying <img src="https://…/pixel.png"> requests it
// on open. In a format whose whole point is that you can mail it, that is
// a tracking pixel — the recipient's IP and the moment they opened your
// document, delivered to whoever wrote the file. It also breaks PLATFORM
// §1: no network is required to open a document.
//
// This costs authors nothing, because the editor never writes a remote
// src: picked images are downscaled, interned by content hash and stored
// as `asset:`. Only hand- or agent-authored documents carry URLs, and for
// those the reader gets a placeholder naming the host and a button. One
// click, per image, informed — the model every mail client settled on.
if (loadsRemotely(rawSrc, doc) && !opts.allowRemote?.(rawSrc)) {
fig.appendChild(remotePlaceholder(rawSrc, b, opts,
t('Image from {host}', { host: remoteHost(resolveSrc(rawSrc, doc)) }), t('Load this image')))
if (b.caption) {
const cap = document.createElement('figcaption')
cap.innerHTML = sanitizeInline(String(b.caption))
fig.appendChild(cap)
}
el.appendChild(fig)
return el
}
const img = document.createElement('img')
img.src = resolveSrc(rawSrc, doc)
img.alt = String(b.alt ?? '')
if (b.width) img.style.width = `${Math.max(10, Math.min(100, Number(b.width)))}%`
// intrinsic size holds the aspect box while the image decodes, so the
// page does not reflow under the reader's cursor
if (b.w && b.h) { img.width = Number(b.w); img.height = Number(b.h) }
fig.appendChild(img)
if (b.caption) {
const cap = document.createElement('figcaption')
cap.innerHTML = sanitizeInline(String(b.caption))
fig.appendChild(cap)
}
el.appendChild(fig)
return el
}
case 'table': {
el.appendChild(renderTable(b, opts))
return el
}
case 'media': {
const fig = document.createElement('figure')
const play = mediaPlayback(b)
const rawSrc = String(b.src ?? '')
el.dataset.kind = play.kind
const done = () => {
if (b.caption) {
const cap = document.createElement('figcaption')
cap.innerHTML = sanitizeInline(String(b.caption))
fig.appendChild(cap)
}
el.appendChild(fig)
return el
}
// NO SOURCE YET. Inserting the block and choosing the file are two
// gestures — a picker can be cancelled, and a link has to be typed
// somewhere — so the empty state is part of the block rather than a
// failure of it. The editor wires these two buttons; a reader, a
// printout and a still see the same box saying what is missing, which is
// more honest than a gap.
if (!rawSrc) {
const box = document.createElement('div')
box.className = 'sp-media-empty'
const line = document.createElement('div')
line.className = 'sp-remote-line'
line.textContent = play.kind === 'audio' ? t('Audio') : t('Video')
box.appendChild(line)
if (opts.editable && !opts.printing) {
const pick = document.createElement('button')
pick.type = 'button'
pick.className = 'sp-btn sp-remote-load'
pick.textContent = t('Choose a file…')
pick.dataset.pickMedia = b.id
const link = document.createElement('button')
link.type = 'button'
link.className = 'sp-btn sp-remote-load'
link.textContent = t('Use a link…')
link.dataset.linkMedia = b.id
const row = document.createElement('div')
row.className = 'sp-media-actions'
row.append(pick, link)
box.appendChild(row)
}
fig.appendChild(box)
return done()
}
// THE SAME CONSENT GATE AS AN IMAGE, and it matters MORE here. A remote
// <video> asks its host for byte ranges the moment the element is
// parsed, so an autoplaying tracker is not even needed: opening the
// space is the ping. Same rule, same host named, different words.
if (loadsRemotely(rawSrc, doc) && !opts.allowRemote?.(rawSrc)) {
const host = remoteHost(rawSrc)
fig.appendChild(remotePlaceholder(rawSrc, b, opts,
play.kind === 'audio' ? t('Audio from {host}', { host }) : t('Video from {host}', { host }),
play.kind === 'audio' ? t('Load this audio') : t('Load this video')))
return done()
}
// PAPER AND THUMBNAILS GET A STILL, NEVER A PLAYER.
//
// `printing` is the flag both of those surfaces already pass (print, and
// preview.ts's file-manager render), and it is the honest test: it means
// "this output cannot be interacted with". A <video> on paper prints as
// a black rectangle; in a file-manager preview it would be an element
// that decodes, buffers and — with scripting off, where nothing can stop
// it — sits there holding a source open. preview.ts also BANS the tags
// outright, which is defence in depth rather than the mechanism: by the
// time it runs there is nothing to ban.
if (opts.printing) {
fig.appendChild(mediaStill(b, doc, opts, play.kind))
return done()
}
const m = document.createElement(play.kind === 'audio' ? 'audio' : 'video') as
HTMLVideoElement | HTMLAudioElement
m.className = 'sp-media'
m.src = resolveSrc(rawSrc, doc)
// metadata, not auto: enough to draw the first frame and a duration, and
// no more. `auto` on a linked clip downloads the whole thing to display a
// page nobody has pressed play on.
m.preload = 'metadata'
// A block with controls off is a rectangle you cannot use, which is fine
// for a reader looking at a caption-and-poster figure and useless to the
// author who has to click it to change it. So the editor always has them.
m.controls = play.controls || opts.editable === true
m.loop = play.loop
// NOTHING SETS `m.autoplay`. mediaPlayback() cannot return true for it,
// and this is the surface that would have obeyed it — see blocks.ts.
if (play.kind === 'video') {
const v = m as HTMLVideoElement
// iOS otherwise takes the clip fullscreen on play, which throws the
// reader out of the page they were reading
v.playsInline = true
// muted is a VIDEO choice: a silent audio block is a block that does
// nothing, so the editor does not offer it and neither does this
v.muted = play.muted
const poster = String(b.poster ?? '')
// a remote poster is the same tracking pixel as a remote image, so it
// goes through the same consent
if (poster && !(loadsRemotely(poster, doc) && !opts.allowRemote?.(poster))) {
const resolved = resolveSrc(poster, doc)
if (resolved) v.poster = resolved
}
if (b.w && b.h) { v.width = Number(b.w); v.height = Number(b.h) }
if (b.width) v.style.width = `${Math.max(10, Math.min(100, Number(b.width)))}%`
}
fig.appendChild(m)
return done()
}
case 'pagelink': {
const a = document.createElement('a')
const target = String(b.page ?? '')
a.href = `#p/${target}`
a.className = 'sp-pagecard'
const title = opts.titleOf?.(target)
a.textContent = title ?? '(missing page)'
if (!title) a.classList.add('sp-dead')
el.appendChild(a)
return el
}
case 'embed': {
renderEmbed(el, b, doc, opts)
return el
}
case 'link': {
// A CARD DRAWN ENTIRELY FROM THE FILE.
//
// There is no fetch here and there is no deferred one either. Every value
// was typed by the author and stored; the only thing derived at render
// time is the site name, and that is `new URL(url).host` — parsing, not a
// request. PLATFORM §1 and the 2026-08-03 decision both land on this
// line, so the negative test in scripts/test-spaces-model.ts pins it.
const c = linkCard(b)
el.classList.add('sp-link')
// AN ANCHOR ONLY WHEN THERE IS SOMEWHERE TO GO. A card whose url is
// empty, or is a `javascript:`/`data:` string out of a mailed file, is a
// <div>: `linkCard` returns '' for all three, and an <a> with no href is
// a link a keyboard can focus and a screen reader will announce, leading
// nowhere.
const card = document.createElement(c.url ? 'a' : 'div')
card.className = 'sp-linkcard'
if (c.url) {
const a = card as HTMLAnchorElement
a.href = c.url
// the same treatment sanitizeInline gives an external link: this leaves
// the document, so it must not be able to reach back through opener
a.rel = 'noopener noreferrer'
a.target = '_blank'
} else {
card.classList.add('sp-dead')
}
// THE THUMBNAIL IS LOCAL OR IT IS ABSENT. `linkCard` drops one that was
// WRITTEN remote, and that is as far as it can see: it takes a block, not
// a document, so it cannot know what an `asset:` key resolves to. The
// asset table is exactly where a remote URL hid, so the resolved check has
// to happen at the one place that holds both the src and the document —
// here, which is also the only place that loads anything.
if (c.image && !loadsRemotely(c.image, doc)) {
const img = document.createElement('img')
img.src = resolveSrc(c.image, doc)
img.alt = ''
img.className = 'sp-linkcard-img'
card.appendChild(img)
}
const body = document.createElement('span')
body.className = 'sp-linkcard-body'
const title = document.createElement('span')
title.className = 'sp-linkcard-title'
// an empty card is not an empty box: it says what it is and, in the
// editor, offers the way to fill it in
title.textContent = c.title || t('A link with nothing in it yet')
body.appendChild(title)
if (c.desc) {
const desc = document.createElement('span')
desc.className = 'sp-linkcard-desc'
desc.textContent = c.desc
body.appendChild(desc)
}
const foot = document.createElement('span')
foot.className = 'sp-linkcard-site'
if (c.icon) {
const mark = document.createElement('span')
mark.className = 'sp-linkcard-mark'
// textContent, never innerHTML: this is one field out of a mailed file
mark.textContent = c.icon
foot.appendChild(mark)
}
const site = document.createElement('span')
site.textContent = c.site || c.url
foot.appendChild(site)
if (c.site || c.url || c.icon) body.appendChild(foot)
card.appendChild(body)
el.appendChild(card)
// The card itself opens the link, so editing needs its own control — and
// only where there is an editor. Reading view, print and a locked space
// must not paint a button that does nothing (the callout chip's rule).
if (opts.editable) {
const edit = document.createElement('button')
edit.type = 'button'
edit.className = 'sp-linkcard-edit'
edit.dataset.editLink = b.id
edit.title = t('Edit this link card')
edit.textContent = c.url ? t('Edit') : t('Add a link')
el.appendChild(edit)
}
return el
}
case 'todo': {
const box = document.createElement('input')
box.type = 'checkbox'
box.checked = !!b.done
box.className = 'sp-check'
// the checkbox is a control, not text: it must not be inside the
// editable host or typing would land in it
el.appendChild(box)
hostAndAnswer(el, b, opts, calc)
if (b.done) el.classList.add('sp-done')
return el
}
case 'prop': {
// A FIELD VALUE. The chip is built from the schema, but the block's own
// `html` is what a build that does not know this type shows — so the two
// must always say the same thing, and fields.ts keeps them in step.
const key = String((b as { key?: unknown }).key ?? '')
const f = fieldByKey(doc, key)
const value = (b as { value?: unknown }).value
el.classList.add('sp-prop')
el.dataset.field = key
const label = document.createElement('span')
label.className = 'sp-prop-key'
label.textContent = f?.label ?? key
el.appendChild(label)
const val = document.createElement(opts.editable ? 'button' : 'span')
val.className = 'sp-prop-val'
if (opts.editable) {
;(val as HTMLButtonElement).type = 'button'
val.dataset.editField = key
}
const opt = f && optionOf(f, value)
if (opt) {
const dot = document.createElement('span')
dot.className = 'sp-prop-dot'
// colour is a HINT, never the meaning — the label is always present, so
// this reads correctly in monochrome and without colour vision
if (opt.color) dot.style.background = opt.color
val.appendChild(dot)
}
const text = document.createElement('span')
text.textContent = shownValue(f, value)
val.appendChild(text)
el.appendChild(val)
return el
}
case 'canvas': {
// The BODY is opened by renderBlocks (registry `container`), which is
// also what puts the cards in it — so this draws the chrome and nothing
// else. `cards` is only needed for the empty-state line, and counting
// here rather than after the fact keeps renderBlock a pure function of
// one block.
const cards = doc.pages
.find((p) => p.blocks.some((x) => x.id === b.id))?.blocks
.filter((x) => x.parent === b.id).length ?? 0
renderCanvasHead(el, b, opts.editable === true, cards)
return el
}
case 'view': {
el.classList.add('sp-view')
renderView(el, b, doc, opts)
return el
}
case 'chart': {
// A CHART OF THE TRAIL, not of the pages — see blocks.ts and charts.ts
// for why that makes it a block rather than a view layout. `todayISO()`
// is the reader's own wall-clock day: the today point is DERIVED from
// live state, every earlier day is read from the record.
el.classList.add('sp-chart')
renderChartBlock(el, b, doc, todayISO(), { editable: opts.editable === true })
return el
}
case 'callout': {
const raw = String(b.tone ?? 'note')
const known = TONE.has(raw) ? raw : 'note'
// Only a KNOWN tone reaches the class name. An unrecognised one keeps the
// neutral treatment (and its own word as the label) — and a class built
// from an arbitrary string out of a mailed file is a thing not to have.
el.className = `sp-b sp-b-callout sp-tone-${known}`
// The chip is the tone control when there is an editor to change it in,
// and a plain label otherwise — reading view, print and a locked space
// must not paint a button that does nothing.
const chip = document.createElement(opts.editable ? 'button' : 'span')
chip.className = 'sp-callout-chip'
if (chip instanceof HTMLButtonElement) {
chip.type = 'button'
chip.title = t('Change the kind of callout')
}
const mark = document.createElement('span')
mark.className = 'sp-callout-mark'
calloutMark(mark, b, known)
const label = document.createElement('span')
label.className = 'sp-callout-label'
// NOT aria-hidden and never a ::before: the tone is content the way a
// "Warning:" printed on a page is content. A screen reader reading this
// page linearly must hear it, and a printout must carry it.
label.textContent = toneLabel(raw)
chip.append(mark, label)
el.appendChild(chip)
hostAndAnswer(el, b, opts, calc)
return el
}
case 'toggle': {
const twist = document.createElement('button')
twist.className = 'sp-twist'
twist.type = 'button'
twist.setAttribute('aria-expanded', String(!!(opts.forceOpen || b.open)))
twist.setAttribute('aria-label', t('Toggle section'))
twist.textContent = '▸'
el.appendChild(twist)
hostAndAnswer(el, b, opts, calc)
return el
}
default:
hostAndAnswer(el, b, opts, calc)
return el
}
}
/**
* A table — the same DOM in the editor, the reading view, print and the still
* preview, because there is one renderer.
*
* REAL `<table>`, `<thead>`, `<th>`, exactly as this renderer emits real
* headings and real list items: that is what buys the screen-reader story
* (row and column announcement), native ⌘F, print fidelity and a lossless
* markdown export, all from one decision. A grid of divs would need four
* separate answers.
*
* The widths are a `<colgroup>` over `table-layout: fixed` — the one layout
* mode in which a column's width is what the document SAYS rather than what
* this reader's font measured, so a table looks the same to everyone the file
* is mailed to. Percentages, never px: `cols` holds fractions (model.ts) and
* the text column is a theme concern.
*
* Cells are editable HOSTS in the editor and inert `<td>`s everywhere else, and
* the editable one is the cell itself rather than a span inside it — a cell is
* a box you click into, and a nested host makes a 1px strip around its edge
* that swallows the click.
*/
function renderTable(b: Block, opts: RenderOpts): HTMLElement {
const t = tableOf(b)
const wrap = document.createElement('div')
// A wide table SCROLLS rather than widening the prose column: the measure is
// the document's, and a five-column table must not push the paragraph above
// it off the screen on a phone.
wrap.className = 'sp-tb-wrap'
const table = document.createElement('table')
table.className = 'sp-tb'
const total = t.cols.reduce((s, n) => s + n, 0) || t.w
const group = document.createElement('colgroup')
for (const w of t.cols) {
const col = document.createElement('col')
col.style.width = `${((w / total) * 100).toFixed(3)}%`
group.appendChild(col)
}
table.appendChild(group)
const body = document.createElement('tbody')
t.rows.forEach((row, r) => {
const head = t.header && r === 0
const tr = document.createElement('tr')
row.forEach((cell, c) => {
const td = document.createElement(head ? 'th' : 'td')
td.className = 'sp-tb-cell'
td.dataset.r = String(r)
td.dataset.c = String(c)
if (head) td.setAttribute('scope', 'col')
if (t.colAlign[c]) td.style.textAlign = t.colAlign[c]
// per cell, for the reason text blocks carry it: a table of Arabic terms
// beside English ones must lay each column out by what is IN it
td.dir = 'auto'
if (opts.editable) {
td.contentEditable = 'true'
// NOT `data-edit`: that name means "this element's html IS the block's
// html", and the editor's generic input handler would write one cell
// over the whole table. A cell says which block AND which cell it is.
td.dataset.cell = b.id
}
// the same either/or as inlineHost, for the same reason — a cell is an
// editable host too
const cleanCell = sanitizeInline(cell)
td.innerHTML = opts.editable || !opts.footnotes
? cleanCell
: markRefs(cleanCell, opts.footnotes, opts.footnoteScope ?? '')
decorateTags(td)
tr.appendChild(td)
})
if (head) {
const thead = document.createElement('thead')
thead.appendChild(tr)
table.appendChild(thead)
} else body.appendChild(tr)
})
table.appendChild(body)
wrap.appendChild(table)
return wrap
}
/**
* An embed: the source page's own blocks, drawn here.
*
* THREE THINGS THIS DOES THAT ARE NOT DECORATION.
*
* It is ATTRIBUTED and clickable. A block of someone else's page dropped into
* yours with no seam is a lie about where the words live, and the reader who
* wants to fix a typo has nowhere to go. The header names the source page and
* links to it, and the section when there is one.
*
* It is NEVER EDITABLE, whatever the host surface is. The blocks belong to
* another page; an editable host here would write a keystroke into `html` on a
* block the editor is not showing, and the change would appear to happen
* nowhere. `editable: false` on the nested render is the whole of that.
*
* And it carries NO `data-block-id`. The editor's paint sweeps every
* `[data-block-id]` under the page and hangs a drag gutter, a checkbox
* handler, a language chip on each — all keyed to `store.block(id)`, which
* resolves ANY id in the document. A checkbox ticked inside an embed would
* have committed to the source page from a surface that was not showing it.
* Stripping the hook is one line and closes the whole class.
*/
function renderEmbed(el: HTMLElement, b: Block, doc: SpacesDoc, opts: RenderOpts): void {
const box = document.createElement('div')
box.className = 'sp-embed'
const view = viewEmbed(b, doc, opts.embedChain ?? [])
const head = document.createElement(view.page ? 'a' : 'div')
head.className = 'sp-embed-src'
const anchor = anchorOf(b)
if (view.page) {
;(head as HTMLAnchorElement).href = `#p/${view.page.id}`
head.textContent = anchor ? `${view.page.title} › ${anchor}` : view.page.title
head.setAttribute('aria-label', t('Embedded from {page}', { page: view.page.title }))
} else {
head.textContent = anchor ? `[[?#${anchor}]]` : '[[?]]'
head.classList.add('sp-dead')
}
box.appendChild(head)
if (!view.ok) {
const note = document.createElement('p')
note.className = 'sp-embed-note'
note.textContent =
view.why === 'cycle' ? t('This embed is inside itself — the loop stops here.')
: view.why === 'depth' ? t('Embeds are not followed deeper than this.')
: view.why === 'no-section' ? t('No section named {name} on this page.', { name: view.anchor ?? '' })
: t('This embed points at a page that is not here.')
box.appendChild(note)
el.appendChild(box)
return
}
const body = document.createElement('div')
body.className = 'sp-embed-body'
body.appendChild(renderBlocks({ ...view.page, blocks: view.blocks }, doc, {
...opts,
editable: false,
embedChain: [...(opts.embedChain ?? []), view.page.id],
}))
for (const node of body.querySelectorAll<HTMLElement>('[data-block-id]')) {
delete node.dataset.blockId
}
box.appendChild(body)
el.appendChild(box)
}
/**
* A callout tone's name, in the reader's language.
*
* Written out as t() calls rather than read from a table in blocks.ts: the i18n
* sweep (scripts/build-spaces-i18n.mjs) collects t() calls with a LITERAL
* STRING out of the source, so a name held as data would ship English to all
* eight locales. A tone with no case here fails scripts/test-spaces-model.ts.
*
* (The sweep reads comments too, so do not write an example call in one.)
*
* An UNRECOGNISED tone returns its own word. A file from a future build that
* says `success` should say "success", not "Note" — the label is the one place
* that can tell the reader the truth about a tone we cannot draw.
*/
export function toneLabel(tone: string): string {
switch (tone) {
case 'note': return t('Note')
case 'tip': return t('Tip')
case 'important': return t('Important')
case 'warning': return t('Warning')
case 'caution': return t('Caution')
default: return tone
}
}
/**
* Fill a callout's mark: the author's override if there is one, else the tone's
* own shape.
*
* The override follows the same rule as a page icon (editor.ts pageIcon) — a
* name from the icon set, or any other string as literal TEXT, which is how an
* emoji works. textContent, never innerHTML: this string came out of a file
* someone sent you.
*
* `Object.hasOwn`, not `in`: ICONS is an object literal, so `'toString' in
* ICONS` is TRUE and the lookup hands back a function, which would then be
* stringified into the page as markup.
*/
function calloutMark(host: HTMLElement, b: Block, known: string): void {
const custom = typeof b.icon === 'string' ? b.icon : ''
if (custom) {
if (Object.hasOwn(ICONS, custom)) host.innerHTML = ICONS[custom as IconName]
else host.textContent = custom
return
}
host.innerHTML = ICONS[(TONE.get(known) ?? TONE.get('note')!).icon]
}
/**
* The editable host, plus the ANSWER when the line asks for one.
*
* The answer is a SIBLING of the editable span, never inside it. Inside, it
* would be part of what contentEditable hands back on the next keystroke, and
* the derived answer would be committed into `html` — which is exactly the
* frozen-result design this feature exists to avoid. It is also
* contenteditable=false and aria-hidden: it is output, not text, and a screen
* reader should hear the line once.
*/
function hostAndAnswer(el: HTMLElement, b: Block, opts: RenderOpts, ctx: CalcCtx): void {
el.appendChild(inlineHost(b, opts))
const ans = answer(textFromHtml(b.html), ctx, locale())
if (ans === null) return
const out = document.createElement('span')
out.className = 'sp-ans'
out.contentEditable = 'false'
out.setAttribute('aria-hidden', 'true')
out.textContent = ans
el.appendChild(out)
}
/** The editable text host. Per-block, never one big editable container — that
* is what keeps Selection block-scoped and stops a merge re-minting ids. */
function inlineHost(b: Block, opts: RenderOpts): HTMLElement {
const inner = document.createElement('span')
inner.className = 'sp-text'
inner.dataset.edit = b.id
// direction is per-block from the CONTENT, inside a container pinned by the
// document's theme.dir — PLATFORM §8's two-layer rule
inner.dir = 'auto'
if (opts.editable) inner.contentEditable = 'true'
// MARKERS ARE DRAWN ONLY WHERE THEY CANNOT BE TYPED INTO. `host.innerHTML`
// is written straight to `Block.html` on every `input` event, so a `<sup>`
// injected into an editable host is one keystroke from being committed to the
// document — and the reference `[^1]` it replaced would be gone. While a
// block is editable the author sees and edits the token, exactly as they see
// and edit `budget * 0.3 =` (calc.ts). Reading view, print and the
// file-manager still are all `editable: false` and get the superscript.
const clean = sanitizeInline(b.html ?? '')
inner.innerHTML = opts.editable || !opts.footnotes
? clean
: markRefs(clean, opts.footnotes, opts.footnoteScope ?? '')
// TAG CHIPS GO ON AFTER the footnote either/or above, never before: that
// `innerHTML =` replaces the host's children, so chips drawn first were
// wiped (the September integration bug). Chips skip <a>, so a footnote
// marker is never decorated, and tags.ts readInline strips chips back out
// of whatever an editable host commits.
decorateTags(inner)
if (!b.html) inner.dataset.empty = '1'
return inner
}
// Untrusted html — parse INERT. A detached div still loads what it creates,
// so `<img src="404" onerror>` in a code block would run its handler here.
// See sanitize.ts inertBody().
const textFromHtml = (html: string | undefined): string => {
if (!html) return ''
return inertBody(html).textContent ?? ''
}
/**
* Paint highlighted code into a `<code>` element — the ONE place colour is
* applied, so the editor, the reader and print can never disagree.
*
* NOTHING IS BUILT AS A STRING. `tokenize` returns ranges into `text`, and
* every node here comes from `createTextNode`/`textContent`. Code is text
* someone mailed you; the model never gains markup and neither does the DOM.
*
* IT RECONCILES RATHER THAN REPLACING, and that is the whole answer to
* highlighting a live contenteditable. On `input` the browser has ALREADY
* applied the keystroke to the DOM, so re-tokenising the same text usually
* yields byte-identical nodes: typing inside a string, a comment or an
* identifier changes that token's text and nothing else, the existing text node
* already holds the new value, and this function performs ZERO mutations. The
* caret is not restored because it was never disturbed.
*
* Only a keystroke that moves a token BOUNDARY — opening a quote, completing a
* keyword — restructures anything, and then `changed` is true and the caller
* puts the caret back by character offset. Assigning `Text.data` wholesale is
* specified to collapse a live range inside it to offset 0, so a restore is
* genuinely required there; it is just rare.
*
* Returns whether the DOM changed.
*/
export function paintCode(code: HTMLElement, text: string, lang?: unknown): boolean {
let changed = false
let node: ChildNode | null = code.firstChild
for (const tk of tokenize(text, lang)) {
const s = text.slice(tk.a, tk.b)
if (tk.k) {
const cls = `sp-t-${tk.k}`
const fit = node?.nodeType === 1 && (node as HTMLElement).className === cls &&
node.firstChild?.nodeType === 3 && !node.firstChild.nextSibling
if (fit) {
if (node!.firstChild!.nodeValue !== s) { (node!.firstChild as Text).data = s; changed = true }
} else {
const span = document.createElement('span')
span.className = cls
span.textContent = s
code.insertBefore(span, node)
changed = true
continue // `node` still has to be matched against the NEXT token
}
} else if (node?.nodeType === 3) {
if (node.nodeValue !== s) { (node as Text).data = s; changed = true }
} else {
code.insertBefore(document.createTextNode(s), node)
changed = true
continue
}
node = node!.nextSibling
}
while (node) { const next = node.nextSibling; node.remove(); node = next; changed = true }
return changed
}
/** What this src loads. One implementation, in model.ts, beside the predicate
* that decides whether loading it leaves the machine. */
export function resolveSrc(src: string, doc: SpacesDoc): string {
return assetValue(src, doc)
}
/** The host a reader is being asked to trust, or the raw src if it will not parse. */
function remoteHost(src: string): string {
try { return new URL(src, 'https://x.invalid').host || src } catch { return src }
}
/**
* What stands in for an unloaded remote resource: what it is, WHERE it would
* come from, and a button. Naming the host is the point — "load images" with no
* indication of who is being contacted is not consent.
*
* `line` and `action` are passed rather than derived from the block, because a
* video and an audio clip are the same gate with different words, and the
* strings have to be LITERAL t() calls somewhere for the i18n sweep to find
* them (scripts/build-spaces-i18n.mjs reads the source). Their call sites say
* them; this says the part that is identical.
*/
function remotePlaceholder(
src: string, b: Block, opts: RenderOpts, line0: string, action: string,
): HTMLElement {
const box = document.createElement('div')
box.className = 'sp-remote'
box.dataset.remoteSrc = src
const line = document.createElement('div')
line.className = 'sp-remote-line'
line.textContent = line0
box.appendChild(line)
const why = document.createElement('div')
why.className = 'sp-remote-why'
why.textContent = t('Not loaded — opening it would tell that site you opened this space.')
box.appendChild(why)
const alt = String(b.alt ?? '')
if (alt) {
const a = document.createElement('div')
a.className = 'sp-remote-alt'
a.textContent = alt
box.appendChild(a)
}
// `allowRemote` is passed by print too, so this clause was always truthy there
// and paper carried a live "Load this image" button. Print asks for it
// explicitly instead.
if (opts.printing !== true && (opts.editable !== false || opts.allowRemote)) {
const btn = document.createElement('button')
btn.type = 'button'
btn.className = 'sp-btn sp-remote-load'
btn.textContent = action
btn.dataset.loadRemote = src
box.appendChild(btn)
}
return box
}
/**
* What a clip looks like where nothing can play it: paper, and a file-manager
* thumbnail.
*
* The POSTER if there is one — that is the frame the author chose, and it is
* the whole reason the field is worth having — and otherwise a quiet box that
* says what is there. Not nothing: a printed handbook that silently omits the
* paragraph where the demo video was is the same class of bug as a toggle that
* prints shut.
*
* A remote poster is skipped rather than fetched. preview.ts passes no
* `allowRemote` at all, so a still built for a file manager can never make a
* request — which is the point, because nobody is there to consent.
*/
function mediaStill(b: Block, doc: SpacesDoc, opts: RenderOpts, kind: 'video' | 'audio'): HTMLElement {
const box = document.createElement('div')
box.className = 'sp-media-still'
const poster = String(b.poster ?? '')
if (poster && !(loadsRemotely(poster, doc) && !opts.allowRemote?.(poster))) {
const resolved = resolveSrc(poster, doc)
if (resolved) {
const img = document.createElement('img')
img.src = resolved
img.alt = String(b.alt ?? '')
box.appendChild(img)
box.classList.add('sp-has-poster')
}
}
const badge = document.createElement('span')
badge.className = 'sp-media-badge'
// the triangle is the universal mark and needs no font; the word beside it
// is what makes it readable aloud and in monochrome
badge.textContent = `\u25B8 ${kind === 'audio' ? t('Audio') : t('Video')}`
box.appendChild(badge)
return box
}
/**
* A whole page, including its title. The OUTER wrapper stays ltr — scrollLeft
* and every coordinate calculation change meaning under rtl — and the INNER
* container carries the document's declared base direction.
*/
export function renderPage(page: Page, doc: SpacesDoc, opts: RenderOpts = {}): HTMLElement {
const art = document.createElement('article')
art.className = 'sp-page'
art.style.direction = 'ltr'
// EACH PAGE ROOT CARRIES ITS OWN RESOLVED DESIGN. Print puts every page of a
// space side by side under one root that carries none, so each keeps its
// own; the editor's surface carries the SAME resolved design as the page it
// shows, so the two can never disagree. designs.css matches ancestors by
// attribute, so two roots with DIFFERENT designs must never nest — which is
// why nothing inside a page is ever rendered through here.
applyDesign(art, doc, opts.design !== undefined ? opts.design : resolvePageDesign(doc, page.id))
const inner = document.createElement('div')
inner.className = 'sp-page-inner'
inner.dir = doc.theme.dir ?? 'ltr'
// THE MEASURE IS FOR PROSE. A line of text has a comfortable width and that
// is what `theme.measure` is for — but a board is not a line of text, and
// squeezing one into 720px shows two and a half columns of a six-column
// board. A page carrying a view gets the room instead; a page of writing
// keeps its measure.
// The page decides; a board is only the DEFAULT for a page that has not.
// `width` absent on a board page keeps the room it always had, and an
// unknown value from a newer build falls back to the measure rather than to
// no width at all.
const auto: 'wide' | undefined = page.blocks.some((b) => b.type === 'view') ? 'wide' : undefined
// PRECEDENCE: what the PAGE says, then what this READER prefers, then the
// board default, then the measure.
//
// The reader's preference is the piece this was missing. A per-page control
// answers "this page needs the room"; it does not answer "I have a 27-inch
// monitor", which is a fact about the person and not about any document —
// and making them set it page by page is the wrong shape of work. It lives
// in localStorage beside the language and the pane width, never in the file,
// for the reason PLATFORM §8 gives about locale: two people opening one
// space on different screens should each get their own answer.
const width = page.width === 'wide' || page.width === 'full' ? page.width
: page.width === undefined ? (opts.readerWidth ?? auto)
: undefined
if (width === 'full') inner.style.maxWidth = 'none'
// WIDE IS A PROPORTION, not a number. It was a flat 1500px, which is wider
// than the reading area of any laptop — so it clamped to the container and
// came out identical to Full. Measured at a 1440px viewport: column 720,
// wide 1130, full 1130. Two of the three choices did the same thing, and the
// one screen where they differed was a 27-inch monitor.
//
// 80% keeps a visible step at every size, and the 1500px cap keeps Wide from
// becoming an unreadable line on a very large screen — at which point Full is
// the thing to pick, deliberately.
// …WITH A FLOOR, because a proportion has nothing to be a proportion OF on a
// phone. 80% of a 354px page is 283px, and the 26px the gutter takes there
// leaves a 257px column on a 390px screen — a third of the display given to
// margin on the setting whose entire purpose is "room for a board or a
// table", and reachable in one tap ("Use this width for every page" is a
// per-screen preference). `max(80%, 680px)` is the same 80% wherever 80% is
// at least 680px (a container of 850px and up) and the whole container below
// that, since a max-width wider than the box does nothing. Measured at 390px:
// column 257 → 328, the page's left margin 79 → 26.
else if (width === 'wide') inner.style.maxWidth = 'min(1500px, max(80%, 680px))'
else if (doc.theme.measure) {
// AND THE DEFAULT ITSELF GROWS. 720px is ~88 characters at 16px, which is
// already at the long end — so this does not widen the line much; what it
// does is stop a 2560px screen showing a 720px ribbon using 31% of it.
// Capped, because past ~95 characters a line is harder to read, not easier.
// THE CAP IS IN CHARACTERS, not pixels — that is the whole point.
// A px cap does not hold a line length: capped at measure x 1.25 = 900px,
// a 5120px screen rendered 110 characters, past the range anyone reads
// comfortably, while the comment above it claimed ~95 was the limit.
//
// 75ch, not 90ch: `ch` is the width of the digit ZERO, and prose averages
// narrower than that — measured here, 9.77px against 8.16px — so 75ch
// renders about 90 real characters and 90ch would render 108. The unit
// flatters itself by about a fifth.
//
// And because `ch` scales with --sp-read, the column grows in PIXELS on a
// large screen while holding the same character count. That is what the
// extra pixels are for: bigger type at a longer viewing distance, not a
// longer line.
const m = doc.theme.measure
inner.style.maxWidth = `min(75ch, max(${m}px, 42vw))`
}
if (width) inner.classList.add('sp-wide')
// THE COVER, above everything, and FULL-BLEED rather than inside the column.
// That is what makes it read as a cover instead of as the first image in the
// page: it belongs to the page, not to the prose, so it ignores the measure
// the way a book's jacket ignores the type area. It escapes the reading
// column's padding with negative margins off `--sp-pad-x/y`, which is why
// that padding is written as variables — a hard-coded -44px would be wrong on
// a phone, wrong in reading mode and wrong in print, all silently.
//
// `resolveSrc` is the same lookup an image block goes through, and `coverSrc`
// is what refuses a remote one — so a cover can never make opening a document
// a network request (PLATFORM §1).
const cover = resolveSrc(coverSrc(page), doc)
if (cover) {
art.classList.add('sp-has-cover')
const wrap = document.createElement('div')
wrap.className = 'sp-cover'
const img = document.createElement('img')
img.className = 'sp-cover-img'
img.src = cover
// DECORATIVE, deliberately. The page's own title is right underneath it and
// says the same thing; a screen reader announcing "cover image" before every
// title is noise, and there is nowhere to write alt text for it anyway.
img.alt = ''
img.setAttribute('aria-hidden', 'true')
wrap.appendChild(img)
art.appendChild(wrap)
} else {
// NO COVER: the HOME page gets a procedural one — a figure seeded from its
// id, never written to the document. The home page only, and never on
// paper or in the thumbnail; procedural.ts decides and argues both. A page
// whose cover is removed lands here again, which is the "gets it back" half.
const gen = proceduralCoverFor(page, doc, opts.printing === true)
if (gen) {
art.classList.add('sp-has-cover')
const wrap = document.createElement('div')
wrap.className = 'sp-cover sp-cover-gen'
wrap.innerHTML = gen
art.appendChild(wrap)
}
}
const h = document.createElement('h1')
h.className = 'sp-title'
h.dataset.pageTitle = page.id
h.dir = 'auto'
if (opts.editable) h.contentEditable = 'true'
h.textContent = page.title
inner.appendChild(h)
inner.appendChild(renderBlocks(page, doc, opts))
const feet = renderFootnotes(page, doc, opts)
if (feet) inner.appendChild(feet)
art.appendChild(inner)
return art
}
/**
* The notes at the foot of the page, or null when the page has none.
*
* DERIVED, LIKE THE NUMBERS. Nothing in the document says "put a footnote
* section here" — the section IS the page's references, in the order they
* appear, so deleting the last reference removes the section and no cleanup
* has to remember to.
*
* A REFERENCE WITH NO NOTE STILL GETS A ROW, and that is the whole authoring
* gesture: type `[^1]` in a sentence and an empty numbered slot appears down
* here to write the note into. It is also why a dangling reference cannot be
* silently lost — what validate() reports is the same thing the author is
* already looking at.
*
* In the editor the note body is an editable host; in reading view, print and
* the file-manager still it is inert. `data-edit-note`, deliberately NOT
* `data-edit`: that name means "this element's html IS a BLOCK's html", and the
* editor's generic input handler would write a note over a block.
*/
function renderFootnotes(page: Page, doc: SpacesDoc, opts: RenderOpts): HTMLElement | null {
const notes = notesOnPage(doc, page)
if (!notes.order.length) return null
const sec = document.createElement('section')
sec.className = 'sp-fnotes'
// A real landmark with a real name: on paper it is the block at the foot of
// the page, and to a screen reader it is the region the superscripts point at.
sec.setAttribute('aria-label', t('Footnotes'))
const ol = document.createElement('ol')
ol.className = 'sp-fnlist'
for (const label of notes.order) {
const li = document.createElement('li')
li.className = 'sp-fnote'
li.id = noteId(page.id, label)
// BACK TO THE SENTENCE. A footnote you cannot get back from costs the
// reader their place; in print the anchor is inert and harmless, so it is
// hidden by the stylesheet rather than conditioned on the surface here.
const back = document.createElement('a')
back.className = 'sp-fnback'
back.href = `#${refId(page.id, label)}`
back.textContent = '\u21A9'
back.setAttribute('aria-label', t('Back to the text'))
li.appendChild(back)
const body = document.createElement('span')
body.className = 'sp-fnbody'
body.dir = 'auto'
// The note came out of a file somebody mailed you, exactly like a block's
// html, and goes through the same allowlist.
body.innerHTML = sanitizeInline(noteOf(doc, label) ?? '')
if (opts.editable) {
body.contentEditable = 'true'
body.dataset.editNote = label
// `:empty::before`, the same idiom the canvas title uses — no companion
// `data-empty` flag to keep in step with what the author has typed
body.dataset.ph = t('Write the note')
}
li.appendChild(body)
ol.appendChild(li)
}
sec.appendChild(ol)
return sec
}
/** What a value reads as. Mirrors fields.ts propHtml, which writes the same
* text into the block so an older build shows it too. */
function shownValue(f: FieldSpec | undefined, value: unknown): string {
if (value === undefined || value === null || value === '') return '—'
if (f?.vt === 'select') return optionOf(f, value)?.label ?? String(value)
if (f?.vt === 'labels') return Array.isArray(value) ? value.join(', ') : String(value)
return String(value)
}
/**
* What a coverless card shows: the page's icon, else the first character of
* its title.
*
* The same rule `calloutMark` follows and for the same reasons — a name from
* the icon set is markup we wrote, anything else is TEXT out of a file someone
* sent you, and `Object.hasOwn` keeps `toString` from resolving to a function.
*/
function pageMark(host: HTMLElement, page: Page): void {
const icon = typeof page.icon === 'string' ? page.icon : ''
if (icon) {
if (Object.hasOwn(ICONS, icon)) { host.innerHTML = ICONS[icon as IconName]; host.classList.add('sp-gcard-ico') }
else host.textContent = icon
return
}
// [...str][0], not str[0]: an emoji or a CJK title is not one UTF-16 unit,
// and slicing one in half renders a replacement character.
host.textContent = [...(page.title || '?').trim()][0] ?? '?'
}
/**
* A BOARD or a LIST of the issues in this space.
*
* Derived, never stored: the view holds a query, and the issues are wherever
* they are. Storing membership would mean a card could disagree with the page
* it stands for — the mistake every "database" makes when it keeps its own copy
* of the rows.
*/
function renderView(host: HTMLElement, b: Block, doc: SpacesDoc, opts: RenderOpts): void {
const layout = String((b as { layout?: unknown }).layout ?? 'board')
const calSpan = (b as { span?: unknown }).span
const groupKey = String((b as { groupBy?: unknown }).groupBy ?? 'status')
const field = fieldByKey(doc, groupKey)
const filter = (b as { filter?: unknown }).filter
const sort = (b as { sort?: unknown }).sort
const all = viewRows(doc, (b as { source?: unknown }).source)
const rows = sortRows(doc, all.filter((r) => passesFilter(doc, r.values, filter, r.page)), sort)
const head = document.createElement('div')
head.className = 'sp-view-head'
const title = document.createElement('span')
title.className = 'sp-view-title'
title.textContent = String(b.html || t('Issues'))
const count = document.createElement('span')
count.className = 'sp-view-count'
count.textContent = String(rows.length)
head.append(title, count)
// The controls belong to the EDITOR, like the callout chip and the language
// chip: a reader, a printout and a locked space get the view, not the buttons
// that change what it holds.
if (opts.editable) {
const btn = (attr: string, label: string, title: string, on = false): HTMLButtonElement => {
const el2 = document.createElement('button')
el2.type = 'button'
el2.className = 'sp-btn sp-view-btn' + (on ? ' sp-on' : '')
el2.dataset[attr] = '1'
el2.textContent = label
el2.title = title
el2.setAttribute('aria-label', title)
return el2
}
// LAYOUT. Both shapes have always rendered; only the board was reachable,
// so a view block could hold `layout:'list'` that nothing in the app could
// produce or undo. One button, because there are two of them and a menu to
// choose between two things is a menu too many.
// THREE shapes now, so the button says what you are looking at and the
// click moves to the next one. A menu to choose between three is still a
// menu too many; a cycle is one control and one word.
// `layoutOf`, not a lookup in a local map: the cycle is ONE fact and it now
// lives in fields.ts, because it used to live here AND in editor.ts and the
// two drifted. A view block hand-authored with layout:"toString" — plain
// JSON, in a file someone sent you — made the truthiness test here pass on
// a native function, and the button's label rendered as
// `function toString() { [native code] }`. The editor's copy had been
// hardened and its comment said the label was safe; the label is rendered
// here, and this half had not been.
const here = layoutOf(layout)
// WHICH SHAPES HAVE BUCKETS. A list, a table and a gallery have no columns,
// so "the field the columns come from" is not a question they can be asked.
// A workload chart's BARS are buckets — it is the same question with the
// same key and the same answer, which is the whole reason it is a layout
// here rather than a block with a vocabulary of its own.
const grouped = here === 'board' || here === 'workload'
// Three WHOLE sentences rather than one with the shape interpolated into
// it. "Show as a {what}" reads fine in English and breaks in half the
// catalogs, where the article and the adjective agree with the noun's
// gender — der Tafel / die Liste, un tableau / une liste. Two of these
// three keys already existed for the same reason.
// THE EXTRACTOR SWEEPS LITERALS. `t(WORD[here])` compiles, runs, and is
// never translated by anybody: no catalog ever learns the string exists,
// and the packer still reports 100% because it builds coverage from the
// keys it swept. Measured on main: "Board", "List" and "Show as a list"
// were present in de.ts and ABSENT from packed.ts — translations already
// written, dropped on the floor, while the button read English in all eight
// locales. So the words are chosen HERE, as literals the sweep can see;
// fields.ts answers "which shape is this" and "what comes next".
const LAYOUT_LABEL: Record<ViewLayout, string> = {
board: t('Board'), list: t('List'), table: t('Table'), gallery: t('Gallery'),
calendar: t('Calendar'), gantt: t('Timeline'), workload: t('Workload'),
}
const NEXT_LABEL: Record<ViewLayout, string> = {
board: t('Show as a list'), list: t('Show as a table'),
table: t('Show as a gallery'), gallery: t('Show as a calendar'),
calendar: t('Show as a timeline'), gantt: t('Show as a workload chart'),
workload: t('Show as a board'),
}
const layoutB = btn('viewLayout', LAYOUT_LABEL[here], NEXT_LABEL[here])
layoutB.dataset.next = nextLayout(here)
// THE CALENDAR'S SECOND SHAPE, on the pattern `groupBy` already set: a
// parameter of ONE layout gets its own control, shown only while that
// layout is on, rather than a sixth entry in a cycle everybody has to click
// through. Whole sentences again, for the reason three lines up.
// The words come from calendar.ts `spanButton`: the second shape is
// "Agenda" on screen and `span: 'timeline'` in the file, because "Timeline"
// is the gantt layout's name (LAYOUT_LABEL above) and the stored value is
// format.
const spanWords = spanButton(calSpan)
const spanB = here === 'calendar'
? btn('viewSpan', spanWords.label, spanWords.title)
: undefined
if (spanB) spanB.dataset.next = nextSpan(calSpan)
// GROUP BY. Only fields with declared options: a board's columns ARE the
// option list, so grouping by a free-text field would make one column per
// distinct string and call it a board.
// The button must name the field the view is ACTUALLY bucketed by, which
// for a workload chart with no stored `groupBy` is the person field and not
// `status` — saying "Group · Status" over a chart of people would be the
// control and the picture disagreeing, which is worse than no control.
const shown = here === 'workload' && !Object.hasOwn(b as object, 'groupBy')
? bucketField(doc) : field
const groupB = btn('viewGroup', shown ? `${t('Group')} · ${shown.label}` : t('Group'),
here === 'workload'
? t('Choose the field the bars come from')
: t('Choose the field the columns come from'))
groupB.dataset.shape = here
const sortKey = (Array.isArray(sort) ? sort : [])[0] as ViewSort | undefined
const sortField = sortKey && fieldByKey(doc, sortKey.key)
const sortB = btn('viewSort',
sortField ? `${t('Sort')} · ${sortField.label}` : t('Sort'),
t('Choose the order'), !!sortField)
const on = !!(filter as { open?: unknown } | undefined)?.open
const openB = btn('viewOpen', t('Open only'), t('Open only'), on)
openB.setAttribute('aria-pressed', String(on))
const n = filterCount(filter)
// the count rather than a list of chips: what matters is that the view is
// narrowed at all, and the popover says by what
const filterB = btn('viewFilter', n ? `${t('Filter')} · ${n}` : t('Filter'), t('Filter'), !!n)
// a LIST has no columns, so the field the columns would come from is not a
// question it can be asked
// WHICH PAGES. Named after what it answers rather than "Source", because
// the question in the reader's head is "what is in this?" — and it says the
// answer, not the word, when there is one.
const src = (b as { source?: { has?: unknown; under?: unknown; tag?: unknown } }).source
const hasKey = typeof src?.has === 'string' ? src.has : ''
const underId = typeof src?.under === 'string' ? src.under : ''
const tagKey = typeof src?.tag === 'string' ? src.tag : ''
const srcLabel = hasKey ? (fieldByKey(doc, hasKey)?.label ?? hasKey)
: underId ? (doc.pages.find((p) => p.id === underId)?.title || t('Untitled'))
// the tag SAYS ITSELF — no lookup, and the hash is what makes it read
// as a tag rather than as a page somebody happened to call "recipe"
: tagKey ? '#' + tagKey
: t('Issues')
const sourceB = btn('viewSource', `${t('Pages')} · ${srcLabel}`,
t('Choose which pages this view holds'), !!(hasKey || underId || tagKey))
head.append(layoutB, ...(spanB ? [spanB] : []), sourceB,
...(grouped ? [groupB] : []), sortB, openB, filterB)
}
host.appendChild(head)
// A SOURCE this build cannot evaluate is the WORST of the three, and it had
// no warning at all until now — `unknownSourceKeys` existed in fields.ts and
// nothing called it. An unreadable filter over-shows; an unreadable SOURCE
// means the view silently falls back to the backlog and shows a completely
// different set of pages, with the header still naming the source it cannot
// apply. Measured against a build of `main`: a view sourced on a tag renders
// as Issues there, and says nothing.
//
// That build is already shipped and cannot be told. What this fixes is
// forward: the FOURTH selector, whenever somebody adds one, degrades loudly.
const unknownSrc = unknownSourceKeys((b as { source?: unknown }).source)
if (unknownSrc.length) {
const note = document.createElement('p')
note.className = 'sp-view-empty'
note.textContent = t('This view chooses its pages in a way this build does not understand, so it is showing the backlog instead.')
host.appendChild(note)
}
// A rule this build cannot evaluate means the view shows MORE than its author
// asked for. Additivity keeps the rule; honesty says so.
// ...and the same rule one level down: an OPERATOR from a newer build is a
// rule that was not applied, which is the same superset with the same banner.
const unknown = [...unknownFilterKeys(filter), ...unknownFilterOps(filter)]
if (unknown.length) {
const note = document.createElement('p')
note.className = 'sp-view-empty'
note.textContent = t('A filter here is newer than this build and was not applied.')
host.appendChild(note)
}
// Same rule, same honesty: a sort key naming a field this build has no schema
// for is skipped, and the order you are looking at is not the one the author
// asked for. Silently showing a different order is the failure additivity
// trades for.
if (unknownSortKeys(doc, sort).length) {
const note = document.createElement('p')
note.className = 'sp-view-empty'
note.textContent = t('A sort here is newer than this build and was not applied.')
host.appendChild(note)
}
if (!rows.length) {
const empty = document.createElement('p')
empty.className = 'sp-view-empty'
// says how to fix it, because an empty board with no explanation reads as
// broken rather than as empty — and an empty board with issues behind a
// filter is a DIFFERENT thing to fix
empty.textContent = all.length
? t('No issues match this filter.')
: t('No issues yet. Add a status field to any page and it appears here.')
host.appendChild(empty)
return
}
const card = (page: Page, values: Map<string, unknown>): HTMLElement => {
// A DIV holding a link, not a link holding controls: the card carries a
// BUTTON now (the status picker, which is the only way to change a status
// with a finger), and interactive content inside an <a> is invalid and
// unreachable from the keyboard. The whole card is still one click target —
// the title's ::after stretches over it (styles.css).
const a = document.createElement('div')
a.className = 'sp-issue'
a.dataset.issue = page.id
const t1 = document.createElement(opts.editable === false ? 'span' : 'a')
t1.className = 'sp-issue-title'
if (t1 instanceof HTMLAnchorElement) t1.href = `#p/${page.id}`
t1.textContent = page.title
a.appendChild(t1)
const meta = document.createElement('span')
meta.className = 'sp-issue-meta'
// THE STATUS IS A CONTROL, because a phone cannot drag. It is the same
// picker and the same writer the issue's own header strip uses — one path,
// so `value` and `html` can never fall out of step.
const own = opts.editable && field && propBlockOf(page, groupKey)
if (own) {
const set = document.createElement('button')
set.type = 'button'
set.className = 'sp-issue-chip sp-issue-set'
set.dataset.setField = own.id
set.title = t('Change {field}', { field: field!.label })
set.setAttribute('aria-label', t('Change {field}', { field: field!.label }))
const cur = optionOf(field, values.get(groupKey))
const d = document.createElement('span')
d.className = 'sp-prop-dot'
if (cur?.color) d.style.background = cur.color
set.append(d, document.createTextNode(shownValue(field, values.get(groupKey))))
meta.appendChild(set)
}
for (const k of ['priority', 'assignee', 'estimate']) {
const v = values.get(k)
if (v === undefined || v === '' || v === null) continue
const f2 = fieldByKey(doc, k)
const chip = document.createElement('span')
chip.className = 'sp-issue-chip'
const o = f2 && optionOf(f2, v)
if (o?.color) {
const d = document.createElement('span')
d.className = 'sp-prop-dot'
d.style.background = o.color
chip.appendChild(d)
}
chip.append(document.createTextNode(shownValue(f2, v)))
meta.appendChild(chip)
}
if (meta.childElementCount) a.appendChild(meta)
return a
}
// GANTT — one bar per page, from its start to its due date. A layout and not
// a `chart` block; the argument is in gantt.ts.
//
// `layoutOf`, not the raw string: a `layout` out of a mailed file can be
// anything, and this branch must never be entered by a value that only looks
// like one of ours.
if (layoutOf(layout) === 'gantt') {
renderGantt(host, doc, rows, groupKey)
return
}
// WORKLOAD — the same rows, added up per bucket. The only shape here whose
// marks are not pages, which is exactly the objection gantt.ts answers.
if (layoutOf(layout) === 'workload') {
// `groupBy` ABSENT falls through to workload.ts's own default (the person
// field), because absent has always meant "the sensible default for this
// shape" and a board's default is not a chart's. A block that STORES a
// groupBy gets what it stored, in every layout.
renderWorkload(host, doc, rows,
Object.hasOwn(b as object, 'groupBy') ? groupKey : undefined)
return
}
// GALLERY — the shape that makes a reading list look like a reading list. A
// board answers "what state is this in" and a table answers "what does it
// say"; a gallery answers "which one is it", which for books, films, recipes
// and people is the question actually being asked, and is why the covers
// exist at all.
//
// A card without a cover is not a hole. It gets a tinted panel carrying the
// page's own icon (or its first letter), on a hue derived from the page id —
// so a gallery of pages nobody has given a picture to still reads as a set of
// distinct things rather than as a grid of grey rectangles.
if (layout === 'gallery') {
const grid = document.createElement('div')
grid.className = 'sp-gallery'
for (const r of rows) {
const cardEl = document.createElement('div')
cardEl.className = 'sp-gcard'
cardEl.dataset.issue = r.page.id
const shot = document.createElement('div')
shot.className = 'sp-gcard-shot'
const src = resolveSrc(coverSrc(r.page), doc)
if (src) {
const img = document.createElement('img')
img.src = src
img.alt = ''
img.setAttribute('aria-hidden', 'true')
// A gallery is many pictures at once — the one place in this app where
// decoding them all up front is a real cost, and the one place the
// browser can be told not to.
img.loading = 'lazy'
img.decoding = 'async'
shot.appendChild(img)
} else {
shot.classList.add('sp-gcard-bare')
// deterministic, so a page keeps its cover across reloads, readers and
// machines — the same reason ids are repaired from the id and never
// from Math.random. The figure is procedural.ts's; the mark rides on it.
shot.innerHTML = proceduralCoverSvg(r.page.id, 'card')
const mark = document.createElement('span')
mark.className = 'sp-gcard-mark'
pageMark(mark, r.page)
shot.appendChild(mark)
}
cardEl.appendChild(shot)
const body = document.createElement('div')
body.className = 'sp-gcard-body'
const t1 = document.createElement(opts.editable === false ? 'span' : 'a')
t1.className = 'sp-issue-title'
if (t1 instanceof HTMLAnchorElement) t1.href = `#p/${r.page.id}`
t1.textContent = r.page.title || t('Untitled')
body.appendChild(t1)
// EVERY field the page carries, not the tracker's four. A gallery of
// books whose cards showed Priority and Estimate and not the Author would
// be the board wearing a different shape.
const meta = document.createElement('span')
meta.className = 'sp-issue-meta'
for (const f of fieldsOf(doc)) {
const v = r.values.get(f.key)
if (v === undefined || v === null || v === '' || (Array.isArray(v) && !v.length)) continue
const chip = document.createElement('span')
chip.className = 'sp-issue-chip'
const o = optionOf(f, v)
if (o?.color) {
const d = document.createElement('span')
d.className = 'sp-prop-dot'
d.style.background = o.color
chip.appendChild(d)
}
chip.append(document.createTextNode(shownValue(f, v)))
meta.appendChild(chip)
}
if (meta.childElementCount) body.appendChild(meta)
cardEl.appendChild(body)
grid.appendChild(cardEl)
}
host.appendChild(grid)
return
}
// TABLE — the shape a base is usually looked at in, and the one this app did
// not have. Columns are the fields the ROWS ACTUALLY CARRY, in the schema's
// declared order: a table of books should not carry an Estimate column
// because the vocabulary happens to contain one, and a page that has a field
// the others lack should not be the reason everyone gets an empty column.
if (layout === 'table') {
const keys = fieldsOf(doc).map((f) => f.key).filter((k) => rows.some((r) => r.values.has(k)))
const wrap = document.createElement('div')
// its own scroller: a wide table must not make the PAGE scroll sideways
wrap.className = 'sp-view-tablewrap'
const table = document.createElement('table')
table.className = 'sp-view-table'
const thead = document.createElement('thead')
const hr = document.createElement('tr')
const th0 = document.createElement('th')
// THE PAGE COLUMN DOES NOT SORT, and it says so by being a plain heading
// rather than a dead button. A view's `sort` names a FIELD: sortRows looks
// each key up in the schema and skips what it cannot find, so ordering by
// title would need a second ordering mechanism living beside the first —
// and one order stored in two shapes is the thing that later disagrees with
// itself. A pseudo-key like `title` is worse still: every build that ships
// today would report it through unknownSortKeys as "newer than this build"
// and then not apply it. Better a column that plainly does not sort.
th0.textContent = t('Page')
hr.appendChild(th0)
for (const k of keys) {
const th = document.createElement('th')
const label = fieldByKey(doc, k)?.label ?? k
const dir = sortDirOf(sort, k)
// The state lives on the TH as aria-sort, the attribute a screen reader
// already announces; the arrow is what a sighted reader reads. Two
// renderings of ONE fact — the view's own `sort` — so there is no second
// place the arrow could come from and no way for it to disagree with the
// order the rows are actually in.
th.setAttribute('aria-sort', dir === 'asc' ? 'ascending' : dir === 'desc' ? 'descending' : 'none')
// A READER GETS THE HEADING, not the control — the rule the card chip and
// every view button already follow: a printout and a locked space show
// the view, never the things that change it.
if (opts.editable) {
const sortB = document.createElement('button')
sortB.type = 'button'
sortB.className = 'sp-view-sort' + (dir ? ' sp-on' : '')
sortB.dataset.sortCol = k
sortB.title = t('Sort by {field}', { field: label })
sortB.setAttribute('aria-label', t('Sort by {field}', { field: label }))
const arrow = document.createElement('span')
arrow.className = 'sp-sortdir'
arrow.setAttribute('aria-hidden', 'true')
arrow.textContent = dir === 'asc' ? '\u2191' : dir === 'desc' ? '\u2193' : ''
sortB.append(document.createTextNode(label), arrow)
th.appendChild(sortB)
} else {
th.textContent = label
}
hr.appendChild(th)
}
thead.appendChild(hr)
table.appendChild(thead)
// What a cell SHOWS. THROUGH THE OPTION, so a select shows its label and
// its colour rather than the id the model stores — the same thing propHtml
// does for the header strip, and for the same reason: the id is not for
// reading. An unset value is an em dash, so an empty cell is still a place
// you can aim at.
const fill = (into: HTMLElement, f: FieldSpec | undefined, v: unknown): void => {
const opt = optionOf(f, v)
if (opt) {
const chip = document.createElement('span')
chip.className = 'sp-prop-chip'
const dot = document.createElement('span')
dot.className = 'sp-prop-dot'
if (opt.color) dot.style.background = opt.color
chip.append(dot, document.createTextNode(opt.label))
into.appendChild(chip)
} else if (v !== undefined && v !== null && String(v) !== '') {
into.appendChild(document.createTextNode(shownValue(f, v)))
} else {
into.classList.add('sp-view-empty')
into.appendChild(document.createTextNode('\u2014'))
}
}
const tb = document.createElement('tbody')
for (const r of rows) {
const tr = document.createElement('tr')
const td0 = document.createElement('td')
// the page itself, reached the same way a card reaches it
const a = document.createElement('a')
a.className = 'sp-view-cellink'
a.href = `#p/${r.page.id}`
a.dataset.page = r.page.id
a.textContent = r.page.title || t('Untitled')
td0.appendChild(a)
tr.appendChild(td0)
for (const k of keys) {
const td = document.createElement('td')
const f = fieldByKey(doc, k)
const v = r.values.get(k)
// A CELL IS A CONTROL where there is an editor — a real <button>, so it
// is in the tab order and answers Enter and Space without a key handler
// of its own. It is emitted even for a page carrying no such prop block:
// an empty cell is how the field gets ONTO that page, exactly as
// dropping a card into a column is.
if (opts.editable && f) {
const cell = document.createElement('button')
cell.type = 'button'
cell.className = 'sp-view-cell'
cell.dataset.cellPage = r.page.id
cell.dataset.cellField = k
cell.title = t('Change {field}', { field: f.label })
cell.setAttribute('aria-label', t('Change {field}', { field: f.label }))
fill(cell, f, v)
td.appendChild(cell)
} else {
fill(td, f, v)
}
tr.appendChild(td)
}
tb.appendChild(tr)
}
table.appendChild(tb)
wrap.appendChild(table)
host.appendChild(wrap)
return
}
// CALENDAR — the shape that answers "when". Its own file: the arithmetic is
// the part of this app most likely to be wrong east of UTC, and it wanted a
// rig that can import it without a DOM. `layoutOf`, not the raw string, so a
// block claiming `layout:"toString"` cannot reach this branch and everything
// a newer build might name falls through to the board.
if (layoutOf(layout) === 'calendar') {
renderCalendar(host, {
doc,
rows,
blockId: b.id,
span: spanOf(calSpan),
locale: locale(),
editable: opts.editable,
card: (r) => card(r.page, r.values),
})
return
}
if (layout === 'list') {
const ul = document.createElement('ul')
ul.className = 'sp-view-list'
for (const r of rows) {
const li = document.createElement('li')
li.appendChild(card(r.page, r.values))
ul.appendChild(li)
}
host.appendChild(ul)
return
}
// BOARD, in the schema's declared order — not alphabetical, and not the order
// issues happen to be in. A status list has a direction, and a board that
// does not follow it is a board you have to read rather than glance at.
const board = document.createElement('div')
board.className = 'sp-board'
const cols = field?.options ?? []
const seen = new Set<string>()
for (const opt of cols) {
const mine = rows.filter((r) => String(r.values.get(groupKey) ?? '') === opt.id)
mine.forEach((r) => seen.add(r.page.id))
const col = document.createElement('div')
col.className = 'sp-col'
col.dataset.group = opt.id
const ch = document.createElement('div')
ch.className = 'sp-col-head'
const dot = document.createElement('span')
dot.className = 'sp-prop-dot'
if (opt.color) dot.style.background = opt.color
ch.append(dot, document.createTextNode(opt.label))
const n = document.createElement('span')
n.className = 'sp-col-count'
n.textContent = String(mine.length)
ch.appendChild(n)
col.appendChild(ch)
for (const r of mine) col.appendChild(card(r.page, r.values))
board.appendChild(col)
}
// An issue whose status this build does not know still has to appear, or the
// board silently loses work written by a newer build. It carries NO
// `data-group`, which is also what makes it a place you can drag OUT of and
// not INTO: "Other" is not a value, so there is nothing a drop here could
// write, and inventing one would overwrite a newer build's status with a
// guess. Dragging a card from here to a real column is how you correct it,
// deliberately.
const orphans = rows.filter((r) => !seen.has(r.page.id))
if (orphans.length) {
const col = document.createElement('div')
col.className = 'sp-col'
const ch = document.createElement('div')
ch.className = 'sp-col-head'
ch.textContent = t('Other')
col.appendChild(ch)
for (const r of orphans) col.appendChild(card(r.page, r.values))
board.appendChild(col)
}
host.appendChild(board)
}
// --- charts ------------------------------------------------------------------
//
// TWO SHAPES, ONE HOST. Both `gantt` and `workload` are `view` LAYOUTS rather
// than a new block type; the argument is in gantt.ts and is not repeated here.
// What belongs here is how they are PAINTED, and the one rule both follow:
//
// THE PICTURE IS SVG WITH PRESENTATION ATTRIBUTES, NOT CSS CLASSES.
//
// Not a style preference. This app draws the same block on four surfaces — the
// editor, the reading view, PAPER, and the file-manager still (preview.ts) —
// and the still carries its OWN small stylesheet, deliberately, because
// QuickLook's renderer is a conservative one. A bar coloured by a `.sp-gt-bar`
// rule in styles.css is a bar that is invisible in a thumbnail and, on paper,
// is at the mercy of the browser's "do not print backgrounds" default. Colour,
// geometry and size travel INSIDE the element, so the four surfaces cannot
// disagree, and `@media print` has nothing left to get wrong.
/** A colour a `fill=` attribute will certainly accept, or nothing. Same test
* preview.ts makes, and for the same reason: the theme comes out of a file. */
const flatColor = (v: unknown): string | null => {
const s = typeof v === 'string' ? v.trim() : ''
return /^#[0-9a-f]{3,8}$/i.test(s) || /^rgb/i.test(s) ? s : null
}
const svgEl = (name: string, attrs: Record<string, string | number>): SVGElement => {
const el = document.createElementNS('http://www.w3.org/2000/svg', name)
for (const k of Object.keys(attrs)) el.setAttribute(k, String(attrs[k]))
return el
}
const GRID = '#E3E8EF'
const MUTED = '#5B6472'
const DANGER = '#E5484D'
const INK = '#1E2A3A'
/** Logical drawing size. The svg scales to its container through the viewBox,
* so these are proportions, not pixels on anybody's screen. */
const GT = { w: 960, name: 210, padR: 14, head: 28, row: 26, bar: 12 }
/** As many characters as fit the name column at 12px. Measuring is not
* available here (the block is painted before layout) and a `<title>` child
* carries the whole name anyway, so a cheap cut with an ellipsis beats a
* clipPath that silently swallows half a word. */
const cut = (s: string, n = 28): string => (s.length <= n ? s : `${s.slice(0, n - 1)}…`)
function renderGantt(host: HTMLElement, doc: SpacesDoc, rows: IssueRow[], groupKey: string): void {
const m = ganttModel(doc, rows, todayISO(), groupKey)
if (m.noDateField) {
const p = document.createElement('p')
p.className = 'sp-view-empty'
p.textContent = t('A timeline needs a date field. Add one and it appears here.')
host.appendChild(p)
return
}
if (!m.bars.length) {
const p = document.createElement('p')
p.className = 'sp-view-empty'
p.textContent = m.undated
? t('No page here has a date yet.')
: t('No issues match this filter.')
host.appendChild(p)
return
}
const accent = flatColor((doc.theme as { accent?: unknown } | undefined)?.accent) ?? '#5B8DEF'
const x0 = GT.name
const tw = GT.w - GT.name - GT.padR
const h = GT.head + m.bars.length * GT.row + 10
const wrap = document.createElement('div')
// its own scroller, exactly as the table layout has: a schedule with thirty
// rows is tall, never wide, but a phone is 320px and the name column plus a
// month of track does not fit in it. The PAGE must not scroll sideways.
wrap.className = 'sp-gt-wrap'
const svg = svgEl('svg', {
viewBox: `0 0 ${GT.w} ${h}`, width: GT.w, height: h,
role: 'img', 'aria-label': t('Timeline'),
})
svg.setAttribute('style', `width:100%;height:auto;display:block;min-width:${Math.round(GT.w / 1.5)}px`)
// gridlines and their labels
for (const tick of m.ticks) {
const x = x0 + tick.x * tw
svg.appendChild(svgEl('line', { x1: x, y1: GT.head - 8, x2: x, y2: h - 6, stroke: GRID, 'stroke-width': 1 }))
const lab = svgEl('text', { x: x + 3, y: GT.head - 12, fill: MUTED, 'font-size': 11 })
lab.textContent = tick.label
svg.appendChild(lab)
}
// TODAY. Only when it is inside the span — gantt.ts refuses to stretch the
// chart to reach it, and a marker clamped to the edge would read as "today is
// the last day of this project". When it is outside, the note below says so
// in words, which is a thing a line cannot say.
if (m.todayX !== null) {
const x = x0 + m.todayX * tw
svg.appendChild(svgEl('line', {
x1: x, y1: GT.head - 10, x2: x, y2: h - 6,
stroke: INK, 'stroke-width': 1.5, opacity: 0.45,
}))
const lab = svgEl('text', { x: x + 4, y: h - 1, fill: INK, opacity: 0.55, 'font-size': 10 })
lab.textContent = t('Today')
svg.appendChild(lab)
}
m.bars.forEach((b, i) => {
const cy = GT.head + i * GT.row + GT.row / 2
const fill = flatColor(b.color) ?? accent
// The NAME is a link, and it is an svg <a>, so the whole picture is one
// element on every surface. The editor's delegated handler matches on
// closest('a') + an href starting `#p/`, which an SVGAElement satisfies;
// the preview strips href along with every other runtime attribute, so the
// still shows the same words without being clickable, which is correct.
const a = svgEl('a', { href: `#p/${b.pageId}` })
const name = svgEl('text', { x: 0, y: cy + 4, fill: INK, 'font-size': 12 })
name.textContent = cut(b.title || t('Untitled'))
const full = svgEl('title', {})
full.textContent = b.title || t('Untitled')
name.appendChild(full)
a.appendChild(name)
svg.appendChild(a)
// the row's own track, so a bar in the middle of a wide span still reads as
// a position on a line rather than as a rectangle floating in space
svg.appendChild(svgEl('line', {
x1: x0, y1: cy, x2: x0 + tw, y2: cy, stroke: GRID, 'stroke-width': 1, opacity: 0.7,
}))
let mark: SVGElement
if (b.milestone) {
// A DIAMOND, because a date with no duration is not a bar. This is what
// every issue written before `start` existed looks like — see the field
// comment in fields.ts; it is the installed base, not an edge case.
const cx = x0 + b.x * tw
const r = 6
mark = svgEl('path', {
d: `M${cx} ${cy - r}L${cx + r} ${cy}L${cx} ${cy + r}L${cx - r} ${cy}Z`,
fill, stroke: b.overdue ? DANGER : 'none', 'stroke-width': b.overdue ? 1.5 : 0,
})
} else {
mark = svgEl('rect', {
x: x0 + b.x * tw, y: cy - GT.bar / 2,
// a one-day task is one day wide, never zero — but a one-day task in a
// ten-year span rounds to a third of a pixel, so the floor is the one
// place the model's fraction is overridden and it is a VISIBILITY floor
width: Math.max(3, b.w * tw), height: GT.bar, rx: 3,
fill,
stroke: b.invalid || b.overdue ? DANGER : 'none',
'stroke-width': b.invalid || b.overdue ? 1.5 : 0,
'stroke-dasharray': b.invalid ? '3 2' : '',
})
}
const why = svgEl('title', {})
// The dates as the FILE holds them — ISO, unambiguous in every locale, and
// the thing somebody fixing a wrong row needs to see. The axis is localized
// because it is a label; this is a value.
why.textContent = b.invalid
? t('{a} to {b} — the end is before the start', { a: b.to, b: b.from })
: b.milestone ? `${b.title} · ${b.from}` : `${b.title} · ${b.from} → ${b.to}`
mark.appendChild(why)
svg.appendChild(mark)
})
wrap.appendChild(svg)
host.appendChild(wrap)
// WHAT THE PICTURE COULD NOT SAY. Every one of these is a count that would
// otherwise be a silent difference between the chart and the document, which
// is the whole failure mode of drawing a picture of somebody else's numbers.
const notes: string[] = []
if (m.dropped) notes.push(t('{n} more not shown', { n: String(m.dropped) }))
if (m.undated) notes.push(t('{n} with no date', { n: String(m.undated) }))
if (m.todayX === null) notes.push(t('Today is outside this range'))
// "{n} end before they start" reads wrong at n=1 in English and needs a
// plural rule in half the catalogs; t() has no plural machinery and should
// not grow one for a footnote. A noun phrase is correct at every n in every
// one of the eight languages, which is the cheaper answer.
const bad = m.bars.filter((b) => b.invalid).length
if (bad) notes.push(t('{n} with the end before the start', { n: String(bad) }))
if (notes.length) {
const p = document.createElement('p')
p.className = 'sp-view-empty sp-gt-note'
p.textContent = notes.join(' · ')
host.appendChild(p)
}
}
function renderWorkload(host: HTMLElement, doc: SpacesDoc, rows: IssueRow[], groupKey?: string): void {
const m = workloadModel(doc, rows, groupKey, t('Unassigned'),
(n) => t('Other ({n})', { n: String(n) }))
if (!m.sum) {
const p = document.createElement('p')
p.className = 'sp-view-empty'
p.textContent = t('A workload chart adds up a number field. This space has none.')
host.appendChild(p)
return
}
if (!m.bars.length) {
const p = document.createElement('p')
p.className = 'sp-view-empty'
p.textContent = t('No issues match this filter.')
host.appendChild(p)
return
}
const accent = flatColor((doc.theme as { accent?: unknown } | undefined)?.accent) ?? '#5B8DEF'
const wrap = document.createElement('div')
wrap.className = 'sp-wl-wrap'
// THE SHARED ENGINE, kernel/src/charts.ts — this app draws no chart of its
// own. `chartSnapshotSvg` and not `mountChart`: the live path exists for
// slides' present mode, where a chart is hovered and zoomed; here the same
// markup has to survive being printed and being handed to a thumbnailer that
// runs no script, and a still does that by being a still.
wrap.innerHTML = chartSnapshotSvg({ w: 720, h: 320, option: workloadOption(m, accent) })
const svg = wrap.querySelector('svg')
// the engine asks for height:100% (it is sized by its host in slides); in a
// flowing column that is zero, so the aspect comes from the viewBox instead
if (svg) svg.setAttribute('style', 'width:100%;height:auto;display:block;min-width:420px')
host.appendChild(wrap)
// THE NUMBERS, IN WORDS, BESIDE THE PICTURE. Three jobs at once and it is the
// cheapest way to do any of them: the axis labels are truncated to fit, a
// chart is unreadable to a screen reader, and a bar's height is not a value
// anybody can quote. Rendered from the SAME model the chart is, so the two
// can never disagree.
const list = document.createElement('p')
list.className = 'sp-wl-legend'
for (const b of m.bars) {
const chip = document.createElement('span')
chip.className = 'sp-issue-chip'
const dot = document.createElement('span')
dot.className = 'sp-prop-dot'
dot.style.background = flatColor(b.color) ?? accent
chip.append(dot, document.createTextNode(`${b.label} · ${b.total}`))
list.appendChild(chip)
}
host.appendChild(list)
const notes: string[] = []
if (m.folded) notes.push(t('{n} more grouped as Other', { n: String(m.folded) }))
if (m.ignored) notes.push(t('{n} left out: not a number', { n: String(m.ignored) }))
const blank = m.bars.reduce((s, b) => s + b.blank, 0)
if (blank) notes.push(t('{n} with no estimate', { n: String(blank) }))
if (notes.length) {
const p = document.createElement('p')
p.className = 'sp-view-empty sp-gt-note'
p.textContent = notes.join(' · ')
host.appendChild(p)
}
}