@dxos/ui-editor 0.10.0 → 0.11.0

package/src/extensions/structure/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './blocks';
+export * from './folding';
+export * from './outliner';

package/src/extensions/structure/outliner/DESIGN.md

@@ -0,0 +1,183 @@
+# Outliner rebuilt on `blocks` — DESIGN
+
+## Motivation
+
+`blocks` (`../blocks`) is the precise, tested foundation for the gutter drag grip,
+whole-block selection, the selection highlight, and block clipboard. The outliner
+predates it and still carries its **own** selection (`selection.ts`,
+`selectionFacet`), drag wiring (`outlinerDnd`), and selection decorations
+(`outliner.ts` `decorations()`). Those now duplicate and fight `blocks`:
+
+- **Two disconnected selection models** — `selectionFacet` (item indices; keyboard
+  commands; `.cm-list-item` border) vs `blockSelectionField` (anchors; grip
+  click/drag; `RectangleMarker` highlight). They never sync, so grip selection and
+  keyboard selection are invisible to each other, and `Cmd+A` then `Cmd+C` copies
+  nothing (clipboard reads the empty block selection).
+- **Redundant, misaligned highlight** — `outlinerDnd` layers
+  `createBlockSelectionHighlight` on top of the outliner's own border with different
+  geometry → the highlight sits off the row.
+- **Grip above the checkbox** — the grip anchors to the line-block top, but the
+  outliner row adds `paddingTop`/`marginTop`, pushing the checkbox down ~6px.
+
+**Plan:** rebuild the outliner as _structure + editing on top of `blocks`_.
+`blocks` owns selection, drag, highlight, and clipboard; the outliner keeps only
+what is genuinely hierarchy/markdown-specific.
+
+## Goals
+
+- One selection model: `blockSelectionField`.
+- The grip centers on the checkbox.
+- Selecting or dragging an item covers its **whole subtree**.
+- A **subtle** current-item (caret) indicator, distinct from the accent selection.
+- Preserve outliner structure/editing: tree parsing, edit constraints, commands, menu.
+
+## Non-goals
+
+- Rewriting `tree.ts` parsing or the `editor.ts` edit constraints.
+- Cross-document drag, virtualization, multi-select rectangle.
+
+## Block model (the crux)
+
+Subtree-as-block and per-item grips pull in opposite directions: subtree ranges
+**overlap** (a parent contains its children), but the gutter/drag ordering needs
+**non-overlapping** ranges. Resolve by separating the two:
+
+- **`getBlocks`** (gutter grips + drag ordering) = each item's **own lines**,
+  non-overlapping, one grip per item.
+  `from = item.lineRange.from`; `to = firstChild ? firstChild.lineRange.from − 1 : item.lineRange.to`.
+- **Block extent** (selection highlight, drag collapse/preview, clipboard) = the
+  item's **subtree**: `getRange(tree, item) = [item.lineRange.from, lastDescendant.lineRange.to]`.
+  Overlap between a selected parent and a selected child is acceptable — the
+  highlight just draws overlapping boxes.
+
+### `blocks` change: extent hook
+
+Add an optional `getBlockExtent(state, block) => { from, to }` to the `blocks`
+core, defaulting to the block's own range. It is consulted by:
+
+- `createBlockSelectionHighlight` — the marker for a selected block spans its extent.
+- `createBlockDrag` — the collapse decoration, floating preview, and placeholder
+  size use the extent (so dragging a parent visually moves the whole subtree).
+
+Markdown blocks pass no hook (extent = own range, unchanged). The outliner passes
+the subtree mapper. This keeps `blocks` generic and leaves markdown behavior
+byte-for-byte identical.
+
+## Drag reindent — drop level rules
+
+Dragging an item moves its whole subtree (`getExtent`). On drop the subtree is
+**re-indented** to a target level; the drag preview shows that level live so the
+drop is predictable. The subtlety is at a **branch boundary** — dropping into the
+gap before an item that is _shallower_ than the item above the gap. Example:
+
+```
+- A
+  - B
+  - C
+- D
+```
+
+Dropping `B` into the gap between `C` and `D` is ambiguous:
+
+- **(i)** `B` stays a child of `A` (a sibling of `C`), or
+- **(ii)** `B` becomes a sibling of `A` (aligned with `D`).
+
+### Rule
+
+For a drop into the slot before `target` (the item at the drop index), let
+`above` be the last item before the slot that is not part of the dragged subtree,
+and `unit = getIndentUnit`. Working in leading-space counts:
+
+- `min = indent(target)` — shallowest: a sibling of `target` (leave the branch).
+- `max = indent(above) + unit` — deepest: a child of `above`.
+- **default (i)** `stay = clamp(indent(source), min, max)` — the dragged item keeps
+  its **own** level (staying in its branch), clamped so it is at most a child of
+  `above` and at least a sibling of `target`.
+- **(ii)** applies only at a real branch boundary (`min < stay`) **and** only while
+  the pointer is vertically **over the `target` row** (`pointerY ≥ target.top`);
+  then the level drops to `min` (a sibling of `target`).
+
+So the default is always (i) — the dragged item keeps its place in the current
+branch — and it outdents to (ii) only when the pointer moves down onto the
+shallower next item (`D`). At the end of the document, or with no `target`, the
+level stays at `above`'s branch.
+
+### Preview + wiring
+
+`blocks/drag.ts` stays hierarchy-agnostic. The outliner supplies an optional
+`getDropIndent(view, sourceIndices, dropIndex, pointerY)` hook returning
+`{ indent, offset }` — the target leading-space count and the horizontal pixel
+offset for the preview (`(indent − sourceIndent) / unit × bulletListIndentationWidth`).
+The drag plugin shifts the floating preview by `offset` each pointer move and, on
+drop, passes `indent` to `moveBlocks` so the committed re-indent matches the
+preview. Markdown blocks pass no hook (no reindent, preview unshifted).
+
+## Selection (single model)
+
+- `blockSelectionField` is the only selection state.
+- Grip click / shift-click / drag populate it (unchanged `blocks` behavior).
+- Outliner `selectAll` / `selectUp` / `selectDown` are retargeted to
+  `blockSelectionField` (tree traversal → block anchors), replacing the
+  `selectionFacet` versions. `selectUp`/`selectDown` (today no-op stubs) get real
+  implementations: extend the block selection to the previous/next item.
+- Clipboard (cut/copy/paste) via `createBlockSelection` with the outliner
+  `BlockOps` (subtree-aware `serialize`/`replaceBlocks`).
+- **Remove** `selection.ts` (`selectionFacet`, `selectionCompartment`,
+  `selectAll/None/Up/Down`) and the selection branch of `outliner.ts`
+  `decorations()`.
+
+## Current-item indicator
+
+- A subtle border on the caret item's **subtree extent**, visually distinct from
+  the accent selection highlight (e.g. `--color-focus-ring-subtle`).
+- Rendered by a minimal outliner layer/decoration driven by `tree.find(caretPos)`
+  → subtree extent. This is the one piece of the old `decorations()` we keep, but
+  scoped to the current item only (no selection role).
+
+## Grip ↔ checkbox alignment
+
+Generalize in `blocks` (per the decision), kept cheap:
+
+- The grip currently top-anchors and sizes to the first row height. Offset it down
+  by the first line's rendered top padding so it centers on the row content.
+- Preferred: derive the offset without per-frame layout reads (no `coordsAtPos`
+  during update). If a clean generic measurement proves costly, fall back to a
+  `gripInsetTop?: number` option on `createBlockDrag` that the outliner sets to its
+  known row padding. Decide during implementation; do not regress markdown
+  centering (heading vs body).
+
+## Module changes
+
+| Module                                  | Action                                                                                                                                                              |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tree.ts`                               | keep                                                                                                                                                                |
+| `editor.ts`                             | keep (constraints + `initialize`; add teardown for the `setTimeout` in `initialize`)                                                                                |
+| `commands.ts`                           | keep; retarget select commands to `blockSelectionField`                                                                                                             |
+| `menu.ts`                               | keep                                                                                                                                                                |
+| `dnd.ts`                                | keep the `BlockOps` adapter (subtree move + reindent, serialize, replace); add the subtree `getBlockExtent`; **drop** the `outlinerDnd` highlight/selection wrapper |
+| `selection.ts`                          | **remove**                                                                                                                                                          |
+| `outliner.ts`                           | compose `blocks()` (drag + selection + highlight + clipboard) + tree + editor + commands + menu + current-item indicator; **drop** the selection decorations        |
+| `blocks/drag.ts`, `blocks/selection.ts` | add `getBlockExtent` hook; generalize grip alignment                                                                                                                |
+
+### Incidental cleanups (in scope)
+
+- Dead theme tokens in `drag.ts`: `--dx-description`, `--dx-base-surface` → real
+  `--color-*` tokens (or drop the fallback).
+- `editor.ts` `initialize()` `setTimeout` — guard against dispatch on a destroyed view.
+
+## Risks / open questions
+
+- Overlapping subtree highlights when a parent and descendant are both selected —
+  accepted as visually fine; confirm on review.
+- Grip-alignment generalization must not add a per-line layout read on the hot path.
+- Interaction of `editor.ts` edit constraints with subtree moves (re-indent) —
+  covered by existing move logic but needs a test.
+
+## Test plan
+
+- Reuse `tree.test.ts`, `editor.test.ts`, `outliner.test.ts`.
+- Add headless tests: subtree `getBlockExtent`; `selectAll/Up/Down` populate
+  `blockSelectionField`; clipboard cut/copy/paste over a subtree; single-item drag
+  relocates the subtree and keeps it selected.
+- Storybook (`Outliner.stories.tsx`): grip centered on the checkbox; selecting an
+  item highlights its subtree; current-item border distinct from selection.

package/src/extensions/structure/outliner/SPEC.mdl

@@ -0,0 +1,305 @@
+---
+id: org.dxos.ui-editor.outliner
+name: Outliner
+version: 0.1.0
+---
+
+The outliner is a CodeMirror extension (`outliner()`) that turns a plain markdown
+task/bullet list into a structured, hierarchical outline editor. The document is
+always valid markdown — nesting is leading-whitespace indentation, items are
+`- [ ] ` tasks or `- ` bullets — so the same text round-trips through any markdown
+tool and syncs as ordinary text.
+
+It is built **on top of `../blocks`**, which owns whole-block selection, the gutter
+drag grip, the selection highlight, and the clipboard. The outliner contributes only
+what is hierarchy/markdown-specific: tree parsing, edit constraints, structural
+commands, the drag re-indent rule, and the item menu. See `DESIGN.md` for the
+rebuild rationale and the drag-reindent derivation; this spec is the normative
+behavior.
+
+## Extensions
+
+The following extension dialects are used in this document.
+
+| Term     | URI                       |
+| -------- | ------------------------- |
+| `module` | `org.dxos.mdl.module@1.0` |
+| `feat`   | `org.dxos.mdl.feat@1.0`   |
+| `test`   | `org.dxos.mdl.test@1.0`   |
+
+## Modules
+
+`outliner()` composes these modules (source files under `src/extensions/structure/outliner/`);
+selection, drag, highlight, and clipboard come from `../blocks`.
+
+```mdl
+module tree
+  desc: |
+    Parses the markdown list into an item Tree, recomputed as a facet on doc change. Items expose
+    lineRange (own lines), contentRange (text after the marker), level, type, and child/sibling links.
+  api:
+    Item: interface                         # { type: 'task'|'bullet'; level; lineRange; contentRange; children; ... }.
+    Tree: interface                         # find(pos) | traverse(item?, cb) | prev/next | siblings | lastDescendant.
+    treeFacet: Facet<Tree>                  # the current parse, read by every other module.
+    getRange: (tree, item) => [from, to]    # the item's whole subtree span (item + descendants).
+    outlinerTree: () => Extension           # installs the parser + facet.
+```
+
+```mdl
+module editor
+  desc: |
+    A transactionFilter constraining edits to a valid outline: snaps the caret out of the marker into
+    the content range, allows whole-line deletes, and guards marker/continuation edits. Seeds an empty
+    document with a first item.
+  api:
+    editor: () => Extension
+```
+
+```mdl
+module commands
+  desc: |
+    Keymap + exported structural commands. Indent/outdent and move operate on the whole subtree;
+    delete/toggle operate on the action scope (see feat F-6).
+  api:
+    indentItemMore / indentItemLess: Command   # Tab / Shift-Tab — re-indent the caret item + descendants.
+    moveItemUp / moveItemDown: Command         # swap the item (with its subtree) past a sibling.
+    deleteItem: Command                        # delete the action scope's subtree(s); clears selection.
+    toggleTask: Command                        # toggle the action scope between task and bullet.
+    getActionScope: (state) => Item[]          # the block selection (subtrees), else the caret item.
+    commands: () => Extension                  # the outliner keymap.
+```
+
+```mdl
+module dnd
+  desc: |
+    Adapts `../blocks` drag/selection to the outline: per-item grips, subtree extent, subtree move with
+    re-indent, and the drop-level rule. Also the selection commands over blockSelectionField.
+  api:
+    getBlocks: (state) => Block[]              # per-item own-lines (non-overlapping) for grips/ordering.
+    getExtent: (state, block) => Block         # the block's whole subtree (selection/collapse/preview).
+    moveBlocks: (view, sources, dropIndex, indent?) => void   # subtree move + re-indent to indent.
+    replaceBlocks: (view, indices, text|null) => void         # clipboard cut/paste over item lines.
+    getDropIndent: (view, sources, dropIndex, pointerY) => { indent, offset } | null  # feat F-5 rule.
+    selectAllItems / selectNoneItems / selectUp / selectDown: Command  # over blockSelectionField.
+    outlinerDnd: () => Extension
+```
+
+```mdl
+module menu
+  desc: |
+    A floating per-item trigger (⋮) pinned in the right margin, hidden while dragging. Activating it
+    opens the host popover; its actions run over the action scope (feat F-6).
+  api:
+    menu: (options?) => Extension
+```
+
+## Features
+
+```mdl
+feat F-1: Document model
+
+  req F-1.1:
+    when: text is a markdown list of `- [ ] ` tasks and `- ` bullets, nested by 2-space indentation
+    then: it parses to a Tree of items, each with a level, type, own line range, and subtree
+
+  req F-1.2:
+    when: the document changes
+    then: the Tree is recomputed and exposed via treeFacet; the document stays valid markdown text
+
+  req F-1.3:
+    when: the document is empty
+    then: a first item (`- [ ] `) is seeded and the caret placed in its content
+```
+
+```mdl
+feat F-2: Editing constraints
+
+  req F-2.1:
+    when: the caret is moved into an item's marker (before its content start)
+    then: it snaps to a valid position — content start when moving down/into, content end when moving
+          up, the previous line end when moving left across the marker
+
+  req F-2.2:
+    when: a whole item line is deleted
+    then: the edit is allowed; marker-internal edits that would break the item are constrained
+
+  req F-2.3:
+    when: task-marker atomicity is required (backspace removing a whole marker, continuation indent)
+    then: it is enforced by the markdown keymap that shapes the change, not by raw edits
+```
+
+```mdl
+feat F-3: Selection (single model, subtree unit)
+
+  req F-3.1:
+    when: an item is selected via grip click / shift-click / keyboard
+    then: the sole selection state is blockSelectionField (anchors); there is no second model
+
+  req F-3.2:
+    when: an item is selected or dragged
+    then: its visual/operational extent is its whole subtree (getExtent = getRange), so a parent
+          covers its descendants
+
+  req F-3.3:
+    when: the caret sits in an item and nothing is selected
+    then: a subtle current-item border marks that item's subtree, distinct from the selection accent
+```
+
+```mdl
+feat F-4: Structural commands
+
+  req F-4.1:
+    when: Tab / Shift-Tab is pressed on an item
+    then: the item AND all its descendants re-indent together (the subtree moves with its parent); Tab
+          is a no-op with no shallower-or-equal previous item to nest under
+
+  req F-4.2:
+    when: an item is moved up/down
+    then: it swaps with the adjacent sibling as whole subtrees
+
+  req F-4.3:
+    when: toggleTask runs
+    then: every item in the action scope flips uniformly between task and bullet, preserving indent
+```
+
+```mdl
+feat F-5: Drag and drop re-indent
+
+  req F-5.1:
+    when: an item is dragged
+    then: its whole subtree lifts (collapsed out) and a floating preview follows the pointer; the
+          static grip is hidden and the preview carries its own grip; the menu is hidden
+
+  req F-5.2:
+    when: the pointer hovers a drop slot (before target T, with A the item above the slot)
+    then: the target level defaults to the dragged item's own level, clamped to
+          [sibling-of-T, child-of-A] — it stays in its branch (i)
+
+  req F-5.3:
+    when: the slot is a branch boundary (T shallower than the default) AND the pointer is over T's row
+    then: the level drops to a sibling of T — it outdents to leave the branch (ii)
+
+  req F-5.4:
+    when: the target level differs from the source level
+    then: the preview shifts horizontally to preview it, and on drop the subtree re-roots to exactly
+          that level (preview and result agree)
+```
+
+```mdl
+feat F-6: Menu / action scope
+
+  req F-6.1:
+    when: a menu command runs with a block selection
+    then: it acts over every selected item's whole subtree (the action scope)
+
+  req F-6.2:
+    when: a menu command runs with no selection
+    then: it acts over the caret item's subtree
+
+  req F-6.3:
+    when: delete runs
+    then: each scope subtree (with its trailing separator) is removed, overlapping ranges merged, and
+          the selection cleared — generalizing to any scope-based command
+```
+
+## Acceptance
+
+```mdl
+test T-indent-subtree
+  given: |
+    - [ ] A
+      - [ ] B
+    - [ ] C
+      - [ ] D
+  when: Tab on "C"
+  then: |
+    - [ ] A
+      - [ ] B
+      - [ ] C
+        - [ ] D
+  tags: [F-4.1]
+```
+
+```mdl
+test T-drop-stays-in-branch
+  given: |
+    - A
+      - B
+      - C
+    - D
+  when: B is dragged into the slot before D with the pointer above D's row
+  then: |
+    - A
+      - C
+      - B
+    - D
+  tags: [F-5.2]
+```
+
+```mdl
+test T-drop-outdents-over-target
+  given: |
+    - A
+      - B
+      - C
+    - D
+  when: B is dragged into the slot before D with the pointer over D's row
+  then: |
+    - A
+      - C
+    - B
+    - D
+  tags: [F-5.3]
+```
+
+```mdl
+test T-delete-subtree
+  given: |
+    - [ ] 1
+    - [ ] 2
+      - [ ] 2.1
+      - [ ] 2.2
+    - [ ] 3
+  when: deleteItem with "2" selected (or the caret in it)
+  then: |
+    - [ ] 1
+    - [ ] 3
+  tags: [F-6.1, F-6.3]
+```
+
+---
+
+## Appendix: Extension Definitions
+
+```mdl
+ext module
+  uri: org.dxos.mdl.module@1.0
+  desc: |
+    A source module of the outliner extension (a file under src/extensions/structure/outliner/). The
+    file path is inferred from the block name (`commands` -> `commands.ts`). Members are the module's
+    public exports.
+  fields:
+    desc?: Prose
+    api: ApiMap         # public exports (name: TypeExpr # comment)
+```
+
+```mdl
+ext feat
+  uri: org.dxos.mdl.feat@1.0
+  desc: A named feature grouping one or more requirements.
+  fields:
+    desc?: Prose
+    req: RequirementList
+  nesting: self
+```
+
+```mdl
+ext test
+  uri: org.dxos.mdl.test@1.0
+  desc: An acceptance scenario expressed as given / when / then steps.
+  fields:
+    given?: Step | Step[]
+    when?: Step | Step[]
+    then: Step | Step[]
+    tags?: TagList
+```