kayg/calternal

Watch

Fork 0

Notes UI (v0.0.1): editor, Today, journal, composer, file-explorer sidebar, backlinks #38

New issue

Open

opened 2026-09-24 14:45:17 +00:00 by kayg · 4 comments

kayg commented

2026-09-24 14:45:17 +00:00

Owner

The v0.0.1 notes UI on the vendored editor package (packages/editor, pinned to calternal.js 118ece3d via scripts/sync-editor.sh) and the notes + collab backends on main.
Owner decisions:

Notes mode sub-views in the top bar capsule: Today · Journal · All · Tags (DESIGN §25). The app opens to Today.
Opening notes: the sidebar renders a file explorer (reuse the Files browser component scoped to Notes/), not a separate notes navigator (round 13, N1).
Backlinks below the note as in calternal.js: collapsible linked and unlinked mention cards (N2).
Today layout: pending the calendar/day layout research the owner is reviewing; until then port calternal.js's Today (date strip + log entry feed + note body).
Composer (⌘↩ one-line capture → log entry) imported from calternal.js and expanded (DESIGN §18).
Live collaboration: y-sync WebSocket to /api/v1/collab/notes/<id>, cursors and names via awareness; agent presence later.
Host seams the editor needs (from the editor team): shortcut binder, image node view, wikilink resolver/formatter, host CSS variables.
Editor bugs go to the calternal.js session as "Editor: …" issues on kayg/calternal.js.

Design: DESIGN §9, §17, §18, §19, §25, §28.

Context for the owning job

Repo: kayg/calternal (~/Developer/calternal). Read CLAUDE.md, CONTEXT.md and docs/DESIGN.md first; this issue's section is cited below.
Owner rules that always apply: file over app (plain files are the truth, the DB is an index); the server is the single writer; data loss is unacceptable; performance first, never at the cost of finesse; UI is the calternal.js design system (copy components verbatim, compare side by side with calternal.js reference screenshots; Claude does visual review); never ship sample/mock data; atomic commits; adversarial testing after API work; good enough, not perfect (merge blockers: crash/DoS, data loss, security, sync collisions).
Comment on this issue when you start (branch, base SHA), on each finding, when blocked, and when finished (head SHA + gate output). Never close it.

The v0.0.1 notes UI on the vendored editor package (`packages/editor`, pinned to calternal.js 118ece3d via scripts/sync-editor.sh) and the notes + collab backends on main. Owner decisions: - Notes mode sub-views in the top bar capsule: Today · Journal · All · Tags (DESIGN §25). The app opens to Today. - **Opening notes: the sidebar renders a file explorer** (reuse the Files browser component scoped to `Notes/`), not a separate notes navigator (round 13, N1). - **Backlinks below the note** as in calternal.js: collapsible linked and unlinked mention cards (N2). - Today layout: pending the calendar/day layout research the owner is reviewing; until then port calternal.js's Today (date strip + log entry feed + note body). - Composer (⌘↩ one-line capture → log entry) imported from calternal.js and expanded (DESIGN §18). - Live collaboration: y-sync WebSocket to `/api/v1/collab/notes/<id>`, cursors and names via awareness; agent presence later. - Host seams the editor needs (from the editor team): shortcut binder, image node view, wikilink resolver/formatter, host CSS variables. - Editor bugs go to the calternal.js session as "Editor: …" issues on kayg/calternal.js. Design: DESIGN §9, §17, §18, §19, §25, §28. ## Context for the owning job - Repo: kayg/calternal (~/Developer/calternal). Read CLAUDE.md, CONTEXT.md and docs/DESIGN.md first; this issue's section is cited below. - Owner rules that always apply: file over app (plain files are the truth, the DB is an index); the server is the single writer; data loss is unacceptable; performance first, never at the cost of finesse; UI is the calternal.js design system (copy components verbatim, compare side by side with calternal.js reference screenshots; Claude does visual review); never ship sample/mock data; atomic commits; adversarial testing after API work; good enough, not perfect (merge blockers: crash/DoS, data loss, security, sync collisions). - Comment on this issue when you start (branch, base SHA), on each finding, when blocked, and when finished (head SHA + gate output). Never close it.

kayg commented

2026-09-24 15:36:04 +00:00

Author

Owner

Owner decision (PKM round, K5, DESIGN §31): daily notes are gatekept. The Notes UI must not open daily notes (Notes/Journal/*-dailynote.md) in the block editor. Log entries are written through the composer, the calendar grid, CalDAV and "Log this"; longer text becomes separate linked notes, which do open in the block editor. Today (in Calendar, #39) shows the day's log entries, attached tasks/notes and activity, not an editable daily-note body. The file-explorer sidebar should hide or lock Notes/Journal/. The block editor is for every other note.

Owner decision (PKM round, K5, DESIGN §31): **daily notes are gatekept.** The Notes UI must **not** open daily notes (`Notes/Journal/*-dailynote.md`) in the block editor. Log entries are written through the composer, the calendar grid, CalDAV and "Log this"; longer text becomes separate linked notes, which **do** open in the block editor. Today (in Calendar, #39) shows the day's log entries, attached tasks/notes and activity, not an editable daily-note body. The file-explorer sidebar should hide or lock `Notes/Journal/`. The block editor is for every other note.

kayg commented

2026-09-24 17:17:56 +00:00

Author

Owner

Starting the Notes UI (#38) in worktree agent-a956f77f3d4d0b6ac, branch worktree-agent-a956f77f3d4d0b6ac, base afe8c7a.

Scope: note view on the vendored @calternal/editor with live Yjs collaboration (/api/v1/collab/notes/<id>), properties panel, linked and unlinked mention cards, Notes/ file-explorer sidebar with Notes/Journal locked, Copy link for notes, headings and blocks. Daily notes are gatekept: they never open in the block editor.

Templates (#54): no backend on main, so the UI is a gap. Tags (#52): the shared Tags plugin has not merged, so the tag page is skipped.

Starting the Notes UI (#38) in worktree `agent-a956f77f3d4d0b6ac`, branch `worktree-agent-a956f77f3d4d0b6ac`, base `afe8c7a`. Scope: note view on the vendored `@calternal/editor` with live Yjs collaboration (`/api/v1/collab/notes/<id>`), properties panel, linked and unlinked mention cards, Notes/ file-explorer sidebar with Notes/Journal locked, Copy link for notes, headings and blocks. Daily notes are gatekept: they never open in the block editor. Templates (#54): no backend on main, so the UI is a gap. Tags (#52): the shared Tags plugin has not merged, so the tag page is skipped.

kayg commented

2026-09-24 17:59:45 +00:00

Author

Owner

Notes UI finished on branch worktree-agent-a956f77f3d4d0b6ac, head deec7a0 (base afe8c7a). Not pushed or merged.

Built:

Note view at /notes/<id>; /n/<calternal-id>[#heading-slug|#^block-id] hands over with the anchor kept. The editor is the vendored @calternal/editor preset on TipTap Collaboration + CollaborationCaret, joined to /api/v1/collab/notes/<id> (y-sync + awareness, names and carets, reconnect with backoff). StarterKit UndoRedo is off in Yjs mode. Host seams wired: registry shortcut binder, image node view and resolver, wikilink resolver/formatter (input rule on ]]).
Daily notes are gatekept: a Notes/Journal/*-dailynote.md never mounts the editor or joins a room; the view links to the day in Calendar.
Properties panel above the note (tags, user keys, created and edited), written through PATCH /properties with If-Match. No YAML in the editor.
Linked and unlinked mention cards below the note (calternal.js NoteMentionsCard port).
Sidebar in note view: file explorer on /api/v1/files/entries scoped to Notes/, Notes/Journal locked.
Copy link for the note (header), headings and blocks (right-click, and the ⋯ menu for the block at the cursor; a block without an id gets ^id).
The title follows the first heading: rename after the room saved it, also when the user leaves at once.

Gates: bun run check 0 errors, bun run test 89 passed, bun run build ok, bun e2e/notes.mjs ok against a real server (two contexts editing live, retitle, anchors, gate).

Gaps and findings:

Templates (#54): no backend on main, so no UI.
Tags (#52): shared Tags plugin not merged, tag page skipped.
OpenAPI: Notes and Tasks PropertiesPatch share one component name, so the published schema for PATCH /notes/{id}/properties is the Tasks shape; GET /notes, /notes/backlinks, /notes/daily describe query params as path params.
Collab stamps last edited in UTC (collab_write uses Utc::now()), HTTP writes use the client time zone, so "Edited" can read earlier than "Created".
Day files have no calternal-id (API id path:<path>), so they cannot be linked as /n/<id>.
The collab room retries a failed last-client flush every second without end (for example after the note moves to Trash).
The day route used for daily notes is /calendar/day/<date> (DESIGN §33); it exists only when #39 lands.

Notes UI finished on branch `worktree-agent-a956f77f3d4d0b6ac`, head `deec7a0` (base `afe8c7a`). Not pushed or merged. Built: - Note view at `/notes/<id>`; `/n/<calternal-id>[#heading-slug|#^block-id]` hands over with the anchor kept. The editor is the vendored `@calternal/editor` preset on TipTap Collaboration + CollaborationCaret, joined to `/api/v1/collab/notes/<id>` (y-sync + awareness, names and carets, reconnect with backoff). StarterKit UndoRedo is off in Yjs mode. Host seams wired: registry shortcut binder, image node view and resolver, wikilink resolver/formatter (input rule on `]]`). - Daily notes are gatekept: a `Notes/Journal/*-dailynote.md` never mounts the editor or joins a room; the view links to the day in Calendar. - Properties panel above the note (tags, user keys, created and edited), written through `PATCH /properties` with If-Match. No YAML in the editor. - Linked and unlinked mention cards below the note (calternal.js NoteMentionsCard port). - Sidebar in note view: file explorer on `/api/v1/files/entries` scoped to `Notes/`, `Notes/Journal` locked. - Copy link for the note (header), headings and blocks (right-click, and the ⋯ menu for the block at the cursor; a block without an id gets `^id`). - The title follows the first heading: rename after the room saved it, also when the user leaves at once. Gates: `bun run check` 0 errors, `bun run test` 89 passed, `bun run build` ok, `bun e2e/notes.mjs` ok against a real server (two contexts editing live, retitle, anchors, gate). Gaps and findings: - Templates (#54): no backend on main, so no UI. - Tags (#52): shared Tags plugin not merged, tag page skipped. - OpenAPI: Notes and Tasks `PropertiesPatch` share one component name, so the published schema for `PATCH /notes/{id}/properties` is the Tasks shape; `GET /notes`, `/notes/backlinks`, `/notes/daily` describe query params as path params. - Collab stamps `last edited` in UTC (`collab_write` uses `Utc::now()`), HTTP writes use the client time zone, so "Edited" can read earlier than "Created". - Day files have no calternal-id (API id `path:<path>`), so they cannot be linked as `/n/<id>`. - The collab room retries a failed last-client flush every second without end (for example after the note moves to Trash). - The day route used for daily notes is `/calendar/day/<date>` (DESIGN §33); it exists only when #39 lands.

kayg referenced this issue

2026-09-24 17:59:46 +00:00

Templates for notes (not daily notes) #54

kayg referenced this issue from a commit

2026-09-24 19:29:46 +00:00

Merge Notes UI: live block editor, properties, mentions, gated daily notes (#38)

kayg commented

2026-10-01 05:12:53 +00:00

Author

Owner

Hygiene review: the final Notes UI head deec7a0a1c6f2b87340a88ce7b5e5be45e8b2c26 is not in origin/dev. The Notes UI work is still unmerged, so #38 stays open.

Hygiene review: the final Notes UI head `deec7a0a1c6f2b87340a88ce7b5e5be45e8b2c26` is not in `origin/dev`. The Notes UI work is still unmerged, so #38 stays open.

kayg referenced this issue

2026-10-03 12:56:40 +00:00

Issue hygiene sweep 2026-10-03 #1008

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/calternal#38

No description provided.

Rows
Columns