Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

spaces: show the tracker, keep the page list open, refuse a non-title (#244)

nyblnet7d9d9efde0fe
diff --git a/scripts/test-spaces-agent.ts b/scripts/test-spaces-agent.ts
index 5504048d..2ec0507a 100644
--- a/scripts/test-spaces-agent.ts
+++ b/scripts/test-spaces-agent.ts
@@ -108,6 +108,72 @@ console.log('bento/spaces agent surface\n')
'a 500-page space raises no errors')
}
+// ---- the starter space SHOWS the tracker ----------------------------------
+// A feature nothing in the starter demonstrates is a feature nobody finds. The
+// tracker shipped invisible: a fresh space opened on the notes tour, and the
+// board, the fields and ⌘⇧I existed only for someone who already knew to look.
+// Asserted structurally, because the way this regresses is silent — a starter
+// edited for prose, with the demo quietly dropped.
+{
+ const starter = starterDoc() as unknown as SpacesDoc
+ const issues = starter.pages.filter((pg) => isIssue(pg as never))
+ const boards = starter.pages.flatMap((pg) => pg.blocks.filter((bl) => bl.type === 'view'))
+
+ ok(boards.length >= 1, `the starter carries a board (${boards.length} view block(s))`)
+ ok(issues.length >= 3, `…with issues on it (${issues.length})`)
+ ok(new Set(issues.map((pg) => String(valuesOf(pg as never).get('status')))).size >= 3,
+ 'the demo issues span several columns — a one-column board demonstrates nothing')
+
+ // every value on them has to be one the schema declares: a starter issue
+ // carrying a status no option matches renders an empty pill and teaches the
+ // format wrong on the one document everybody reads first
+ const opts = new Map(DEFAULT_FIELDS.map((f) => [f.key, new Set((f.options ?? []).map((o) => o.id))]))
+ const strays = issues.flatMap((pg) => [...valuesOf(pg as never)]
+ .filter(([k, v]) => opts.get(k)?.size && v !== '' && !opts.get(k)!.has(String(v)))
+ .map(([k, v]) => `${pg.title}: ${k}=${String(v)}`))
+ ok(strays.length === 0, `every starter value is in the schema (${strays.join('; ') || 'all good'})`)
+
+ // and the readable `html` matches the value — the pairing the whole format
+ // degrades through, generated here rather than typed out
+ const mismatched = issues.flatMap((pg) => pg.blocks
+ .filter((bl) => bl.type === 'prop')
+ .filter((bl) => {
+ const f = DEFAULT_FIELDS.find((x) => x.key === (bl as { key?: string }).key)
+ return !f || bl.html !== propHtml(f, (bl as { value?: unknown }).value)
+ })
+ .map((bl) => `${pg.title}/${(bl as { key?: string }).key}`))
+ ok(mismatched.length === 0, `every starter prop's html matches its value (${mismatched.join(', ') || 'all good'})`)
+
+ // an issue is REACHABLE — a card opens the page, and the sidebar shows it
+ // where the board says it is
+ ok(issues.every((pg) => !!pg.parent && starter.pages.some((q) => q.id === pg.parent)),
+ 'every starter issue is nested under a page that exists')
+}
+
+// ---- a title has to BE a title --------------------------------------------
+// `{ title: 'Tracker' }` is the object shape every other verb here takes, so it
+// is the mistake a caller actually makes — and coercion answered it with a page
+// called "[object Object]" and an ok result.
+{
+ const doc = load([p('p1', [b('b1')])])
+ const bad: unknown[] = [{ title: 'x' }, ['x'], 42, true]
+ for (const t of bad) {
+ const made = planNewIssue(doc, { title: t })
+ const set = planUpdatePage(doc, 'p1', { title: t })
+ ok(made.ok === false && (made as { err?: string }).err === 'bad-title',
+ `newIssue refuses a title of type ${Array.isArray(t) ? 'array' : typeof t}`)
+ ok(set.ok === false && (set as { err?: string }).err === 'bad-title',
+ `updatePage refuses a title of type ${Array.isArray(t) ? 'array' : typeof t}`)
+ }
+
+ // …and still accepts the things that ARE titles, including none
+ ok(planNewIssue(doc, { title: 'A real one' }).ok, 'a string title is accepted')
+ ok(planNewIssue(doc, {}).ok, 'no title at all is accepted — it has a default')
+ ok(planNewIssue(doc, { title: null }).ok, 'an explicitly empty title is accepted')
+ ok(planUpdatePage(doc, 'p1', { title: '<b>markup</b> is still flattened' }).ok,
+ 'updatePage still takes a string and strips its markup')
+}
+
// ---- …and specific on documents that are broken ---------------------------
{
const broken = load([
diff --git a/spaces/CHANGELOG.md b/spaces/CHANGELOG.md
index c77858d8..90e1aea2 100644
--- a/spaces/CHANGELOG.md
+++ b/spaces/CHANGELOG.md
@@ -70,6 +70,25 @@ Versions follow `0.MINOR.PATCH` while pre-1.0.
the API cannot put anything in a file that the app itself could not have
written.
+- **A new space opens with a tracker in it.** The starter space gains a
+ **Tracker** page — a board, and five issues nested under it that explain
+ themselves: open a card and you are in an ordinary page with fields along the
+ top. The tracker shipped invisible last round, findable only by someone who
+ already knew ⌘⇧I existed. The demo issues are meant to be deleted, and say so.
+
+- **Fixed: the page list closed every time you clicked a page.** Following a
+ link in the sidebar dismissed it — right on a phone, where the drawer covers
+ the page you just asked for, and wrong on every larger screen, where it
+ collapsed the column and remembered the collapse. The list stayed shut on the
+ next open, and the one after that. The phone drawer still closes; nothing else
+ does.
+
+- **Fixed: `newPage` accepted things that were not titles.** It takes a string
+ where the verbs beside it take an object, so `bento.newPage({ title: 'x' })`
+ is the mistake a caller actually makes — and it made a page called
+ `[object Object]` and reported success. It now refuses, as does `newIssue` and
+ `updatePage` for the same argument.
+
## [0.1.0] — 2026-08-03
First release.
diff --git a/spaces/src/agent.ts b/spaces/src/agent.ts
index 53a0b498..ab9841fb 100644
--- a/spaces/src/agent.ts
+++ b/spaces/src/agent.ts
@@ -129,6 +129,23 @@ export function normalizeHtml(html: string, type: string): string {
/** A page title renders as TEXT, so markup in one would show literally. */
export const plainTitle = (v: unknown): string => textOf(String(v ?? ''))
+/**
+ * A title has to BE a string.
+ *
+ * `plainTitle` coerces, and that is right for what it was written for: markup
+ * pasted into a title, a number someone used for a heading. But coercion
+ * applied to the wrong TYPE is not forgiveness, it is a lie —
+ * `newPage({ title: 'Tracker' })`, written in the object shape every other verb
+ * on this surface takes, made a page called "[object Object]" and reported
+ * success. Every other verb here refuses input it cannot honour, and a title is
+ * a poor place to start guessing: the page is created either way, so the caller
+ * finds out by reading the sidebar.
+ *
+ * `null`/absent stays legal — that is "no title", and each caller has its own
+ * default for it.
+ */
+export const badTitle = (v: unknown): boolean => v != null && typeof v !== 'string'
+
// ---------------------------------------------------------------------------
// validate()
// ---------------------------------------------------------------------------
@@ -929,6 +946,7 @@ export function planUpdatePage(doc: SpacesDoc, id: string, patch: unknown): Plan
const { sets, dels } = split
if ('title' in sets) {
+ if (badTitle(sets.title)) return fail('bad-title', 'title must be a string')
// the title renders as textContent, so markup in it would show literally
sets.title = plainTitle(sets.title)
}
@@ -1275,6 +1293,7 @@ export interface NewIssueResult {
export function planNewIssue(doc: SpacesDoc, spec: unknown): Plan<NewIssueResult> {
if (spec !== undefined && !isPatch(spec)) return fail('bad-patch', 'pass { title?, parent?, ...fieldValues }')
const src = (spec ?? {}) as Record<string, unknown>
+ if (badTitle(src.title)) return fail('bad-title', 'title must be a string')
const parent = src.parent == null ? '' : String(src.parent)
if (parent && !doc.pages.some((p) => p.id === parent)) return fail('no-such-page', `parent "${parent}"`)
diff --git a/spaces/src/editor.ts b/spaces/src/editor.ts
index 9e6e8a65..77d656ba 100644
--- a/spaces/src/editor.ts
+++ b/spaces/src/editor.ts
@@ -437,6 +437,23 @@ export class Editor {
return window.matchMedia('(max-width: 820px)').matches
}
+ /**
+ * Dismiss the PHONE DRAWER after navigating. On anything wider this does
+ * nothing, deliberately.
+ *
+ * Following a page link used to call `toggleSidebar(false)` directly, which
+ * reads as "close the sidebar" and is right on a phone — the drawer covers
+ * the page you just asked for. But above the drawer breakpoint
+ * `toggleSidebar` delegates to `togglePane`, so on a desktop it collapsed the
+ * page-list COLUMN on every click, and `togglePane` persists that to
+ * localStorage: the list stayed shut on the next open, and on every open
+ * after it. The column is not in the way of anything, and a list you have to
+ * reopen to use twice is not a list.
+ */
+ private closeDrawer(): void {
+ if (this.isDrawer()) this.toggleSidebar(false)
+ }
+
private toggleSidebar(force?: boolean): void {
// Below the drawer breakpoint the panel is an overlay, not a column: the
// page needs the whole width, so collapsing to a 0px column would leave
@@ -486,7 +503,7 @@ export class Editor {
label.textContent = page.title || t('Untitled')
a.append(ico, label)
a.draggable = true
- a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(page.id); this.toggleSidebar(false) })
+ a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(page.id); this.closeDrawer() })
a.addEventListener('dragstart', (e) => e.dataTransfer?.setData('text/bento-page', page.id))
a.addEventListener('dragover', (e) => {
// a sidebar row accepts PAGES; a card dragged over it lit up and
@@ -536,7 +553,7 @@ export class Editor {
const label = document.createElement('span')
label.textContent = page.title || t('Untitled')
a.append(ico, label)
- a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(page.id); this.toggleSidebar(false) })
+ a.addEventListener('click', (e) => { e.preventDefault(); s.goToPage(page.id); this.closeDrawer() })
const un = document.createElement('button')
un.className = 'sp-rowmore'
un.type = 'button'
diff --git a/spaces/src/main.ts b/spaces/src/main.ts
index 36d04a87..057d6b77 100644
--- a/spaces/src/main.ts
+++ b/spaces/src/main.ts
@@ -20,7 +20,7 @@ import {
validateDoc, outlineDoc, statsDoc,
planInsertBlocks, planUpdateBlock, planRemoveBlocks, planMoveBlock, planUpdatePage, planRemovePage,
fieldsReport, issuesReport, planSetField, planNewIssue,
- plainTitle,
+ plainTitle, badTitle,
type Plan, type PlanError, type IssueQuery,
} from './agent'
import { starterDoc } from './starter'
@@ -356,6 +356,12 @@ function boot(doc: SpacesDoc, repaired: string[], frozen?: 'policy' | 'version')
*/
newPage: (title: string, parent?: string) => {
if (store.readOnly) return null
+ // A TITLE, not something that stringifies into one. This takes a string
+ // where the verbs beside it take an object, so `newPage({ title: 'x' })`
+ // is the natural mistake — and it used to make a page called
+ // "[object Object]" and hand back its id, which is the exact failure the
+ // rest of this surface exists to avoid.
+ if (badTitle(title)) return null
// a parent that names nothing would silently make this a ROOT page; say
// no instead, so the caller finds out now rather than in the sidebar
if (parent && !store.doc.pages.some((p) => p.id === parent)) return null
diff --git a/spaces/src/starter.ts b/spaces/src/starter.ts
index 7d9a05a7..d6c7e04b 100644
--- a/spaces/src/starter.ts
+++ b/spaces/src/starter.ts
@@ -7,14 +7,43 @@
// the page that describes links CONTAINS a link, the page about sharing is
// reachable only through one, and the limits page says the awkward things out
// loud rather than letting them be discovered.
+//
+// Which is why the TRACKER is here. It shipped with none of this: a fresh space
+// opened on the notes tour, and the board, the fields and ⌘⇧I existed only for
+// someone who already knew to look for them. A feature the starter does not
+// demonstrate is a feature the starter denies.
+
+import { FORMAT, FORMAT_VERSION, defaultTheme, type SpacesDoc, type Block, type Page } from './model.ts'
+import { DEFAULT_FIELDS, ISSUE_FIELDS, propBlock } from './fields.ts'
-import { FORMAT, FORMAT_VERSION, defaultTheme, type SpacesDoc, type Block } from './model.ts'
+const nextId = (): string => `sd-${(seq++).toString(36)}`
const b = (type: string, html = '', extra: Partial<Block> = {}): Block =>
- ({ id: `sd-${(seq++).toString(36)}`, type, html, ...extra })
+ ({ id: nextId(), type, html, ...extra })
let seq = 0
+/**
+ * A starter ISSUE — a page whose first blocks are its fields.
+ *
+ * Built through `propBlock` and `DEFAULT_FIELDS` rather than written out as
+ * literal blocks, for one reason: `value` and the readable `html` beside it
+ * have to agree, and hand-written starter blocks are exactly the copy that
+ * silently stops agreeing the first time an option is renamed. The starter is
+ * the one document every new space is judged by; it should be generated by the
+ * same rule the app enforces at runtime.
+ *
+ * Seeded from `ISSUE_FIELDS`, so a starter issue carries the same fields as one
+ * made with ⌘⇧I or `bento.newIssue()` — an issue here missing `assignee` would
+ * be an issue with nowhere to put one.
+ */
+function issue(title: string, parent: string, values: Record<string, string>, body: string): Page {
+ const props = DEFAULT_FIELDS
+ .filter((f) => ISSUE_FIELDS.includes(f.key))
+ .map((f) => propBlock(f, values[f.key] ?? f.def ?? '', nextId()))
+ return { id: nextId(), title, parent, blocks: [...props, b('p', body)] }
+}
+
/** Deterministic ids: a generator must emit the same document twice. */
export function starterDoc(): SpacesDoc {
seq = 0
@@ -23,6 +52,7 @@ export function starterDoc(): SpacesDoc {
links: 'sd-links',
writing: 'sd-writing',
limits: 'sd-limits',
+ tracker: 'sd-tracker',
inbox: 'sd-inbox',
}
@@ -52,9 +82,10 @@ export function starterDoc(): SpacesDoc {
b('todo', 'Press <code>⌘K</code> to search every page at once', { done: false }),
b('p', 'Then press <code>⌘S</code>. The file on your disk now contains everything you just wrote.'),
b('h2', 'What is here'),
- b('p', 'Three pages, and each one demonstrates the thing it describes:'),
+ b('p', 'Four pages, and each one demonstrates the thing it describes:'),
b('bullet', '<a href="#p/sd-links">Pages and links</a> — how a space holds more than one page'),
b('bullet', '<a href="#p/sd-writing">Writing</a> — the blocks you can make'),
+ b('bullet', '<a href="#p/sd-tracker">Tracker</a> — the same pages, on a board'),
b('bullet', '<a href="#p/sd-limits">Sharing &amp; limits</a> — what this file can and cannot do'),
b('p', 'The sidebar holds the whole tree. Drag a page onto another to nest it.'),
],
@@ -121,6 +152,36 @@ export function starterDoc(): SpacesDoc {
b('p', 'Text is essentially free — hundreds of pages of prose stay a small file. Images are what make it big, because they travel inside it.'),
],
},
+ {
+ id: P.tracker,
+ title: 'Tracker',
+ icon: 'board',
+ blocks: [
+ b('p', 'An <b>issue is a page</b>. The cards below are the pages nested under this one — open one and you are in a document you can write anything in, with its fields along the top.'),
+ b('p', 'Nothing here is a second kind of thing: issues search, link, print, export and back-link like every other page. A page becomes an issue when it has a status, and stops being one when it does not.'),
+ b('view', 'Issues', { layout: 'board', groupBy: 'status' }),
+ b('h2', 'Making them'),
+ b('p', '<code>⌘⇧I</code> makes an issue. The tag button in the toolbar turns the page you are already on into one — useful when a note turns out to be work.'),
+ b('p', 'Drag a card to another column to change its status. <b>Open only</b> hides what is done; <b>Filter</b> narrows by any field.'),
+ ],
+ },
+ ...[
+ issue('Open this card — it is an ordinary page', P.tracker,
+ { status: 'doing', priority: 'high' },
+ 'You are in it. The row above is fields; everything from here down is a page — write notes, paste an image, nest a toggle. That is the whole trick: the tracker did not invent a new thing to hold work in, it put fields on the thing you already had.'),
+ issue('Drag me to another column', P.tracker,
+ { status: 'todo', priority: 'medium' },
+ 'Dragging a card writes the new status onto this page. Go the other way too: change the field at the top and watch the card move on the board.'),
+ issue('Press ⌘⇧I to make your own', P.tracker,
+ { status: 'todo', priority: 'urgent' },
+ 'A new issue arrives with status, priority, assignee and estimate already on it, and the caret in the body waiting for you.'),
+ issue('Delete all of this once you have seen it', P.tracker,
+ { status: 'backlog' },
+ 'These five are a demonstration, not a template. Delete them and the board is empty and yours — it shows whatever pages in this space have a status, wherever they live in the tree.'),
+ issue('This one is finished', P.tracker,
+ { status: 'done' },
+ 'Done and cancelled are <i>phases</i>, not just names, which is what lets <b>Open only</b> mean something without anyone configuring a filter.'),
+ ],
{
id: P.inbox,
title: 'Inbox',