joplin-plugin-gtd-calendar/DRAG_DROP.md

# Drag-and-drop v2.0.0 — next-session handoff

Use this document as the opening prompt and state record for the next development
session. The planning source of truth is `SLICE14.md`, followed by `SLIDE15.md`.

## Current repository state

- v1.0.0 is released and published to npm.
- Release commit: `7a02834 Release-v1.0.0` on `master`.
- At the time this handoff was written, the repository had no pre-existing
  uncommitted changes before these three planning files were added.
- The v1 production artifact is
  `publish/com.victorwiebe.joplin.plugin.gtd-calendar.jpl`.
- v1 automated validation recorded 251 Jest tests across 16 suites, plus
  TypeScript, webview syntax, build, package inspection, whitespace, and
  prohibited-reference checks.
- The user manually accepted the v1 kanban/matrix behavior and card styling.
- Do not describe old v1 validation as proof that new v2 mutation behavior works.

## Confirmed v2 decisions

- Drag and drop is technically feasible because cards are DOM elements in the
  Joplin desktop rendered-note webview, not an HTML canvas.
- v2.0.0 begins with writable workflow views because persisted mutation,
  concurrency, recovery, and accessibility are a material behavior change.
- Every existing block remains read-only by default.
- Mutation requires the exact opt-in `editable: yes`.
- Pointer drag and keyboard **Move to…** are both required.
- The webview sends constrained semantic intent; only the main plugin process
  fetches fresh state and derives Joplin data/tag mutations.
- Kanban moves persist note workflow tags or native to-do completion according
  to `SLICE14.md`.
- Eisenhower moves persist urgent/important tag combinations according to
  `SLIDE15.md`.
- Completion wins over in-progress in normal collection. An intentional kanban
  move canonicalizes conflicting workflow tags.
- Eisenhower keeps urgent/important axes but adopts Skeleton quadrant names:
  Do Next, Scheduled, On Deck, and Backlog. “Eliminate” must disappear.
- Skeleton remains supported and read-only for v2.0.0; do not remove it.
- No free-form card ordering or cross-notebook dragging is included.

## Required order of work

1. Read every repository `*.md` file before implementation, with special
   attention to `SPEC.md`, `TASKS.md`, `SLICE11.md`, `SLICE12.md`, `SLICE13.md`,
   `SLICE14.md`, and `SLIDE15.md`.
2. Inspect `git status --short`, the latest commit, all package/manifest versions,
   and the current test scripts. Preserve unrelated user changes.
3. Execute `SLICE14.md` phase by phase. Update its checkboxes and Status after
   each completed phase and whenever pausing.
4. Keep implementation, focused automation, full automation, JPL packaging, and
   manual Joplin acceptance as separate boundaries.
5. Stop for the user's explicit SLICE 14 manual Joplin sign-off before marking
   its manual phase complete or beginning SLICE 15, unless the user explicitly
   asks to continue without that checkpoint.
6. Execute `SLIDE15.md` only after the SLICE 14 foundation is accepted. Update it
   with the same state discipline.
7. After both slices pass automation and explicit manual acceptance, complete
   consolidated v2.0.0 documentation/version/release preparation. Do not publish
   or push unless the user asks.

## Opening prompt for the next session

Copy the following request into the next session:

> Please read all Markdown files in the repository, then use `DRAG_DROP.md` as
> the handoff and begin `SLICE14.md` Phase 1. Work phase by phase, update the
> slice file after every completed phase and whenever you pause, and keep
> implementation, automated validation, packaging, and manual Joplin acceptance
> separate. Do not begin `SLIDE15.md` until SLICE 14 has passed its required
> acceptance boundary.

## Baseline files to inspect before editing

- `src/index.ts` — content-script message registration and Joplin data adapter.
- `src/Gtd/types.ts` — configs, cards, boards, layouts, and adapter types.
- `src/Gtd/parseKanbanConfig.ts` and `src/Gtd/parseMatrixConfig.ts` — option
  parsing and warnings.
- `src/Gtd/collectKanban.ts` and `src/Gtd/collectMatrix.ts` — eligibility,
  completion, tags, grouping, sorting, warnings, and counts.
- `src/Gtd/buildKanbanCard.ts` — shared note/to-do card normalization.
- `src/Gtd/matrixLabels.ts` — canonical matrix labels.
- `src/gtd-calendar-webview.js` — DOM rendering, click handling, pagination, and
  the future pointer/keyboard interaction layer.
- `src/event-calendar.css` — shared kanban/matrix card and quadrant styling.
- `src/tests/Gtd/kanban.test.ts`, `matrix.test.ts`, parser tests, grouping tests,
  field-hint tests, and webview/render checks.

## Implementation cautions

- Current collection uses tag titles only. Writable behavior needs stable tag
  identities and narrowly scoped mutation operations without weakening the
  read-only collector abstraction.
- Do not trust `isTodo`, tag names, source quadrant, scope, or desired field
  patches supplied by the webview. Reparse config and refetch the item/tags.
- Joplin tag and note writes are separate calls. Prefer minimal idempotent writes
  and canonical refetch over a stale compensating rollback.
- Multiple blocks can exist in one rendered note. Every request and response
  must target one stable view instance and reject stale async responses.
- A click must continue opening a card. Use a pointer movement threshold and an
  explicit drag affordance so click and drag are not confused.
- Pagination is derived after sorting. A moved card may legitimately disappear
  beyond the visible batch after refresh.
- Grouped views use exact notebook ownership. Cross-group movement is out of
  scope and must not accidentally patch `parent_id`.
- Completing a recurring to-do can activate the Repeating To-Dos plugin. Always
  refresh canonical state and manually test the integration.
- Matrix completion remains excluded. If an item becomes complete while a move
  is pending, reject the stale move and refresh.
- Equal normalized Eisenhower axis tags cannot represent four states. Editable
  mode must warn and disable mutation for that block.

## Expected verification and reporting

For each slice, report these separately:

- implemented source/documentation changes;
- focused automated checks and exact counts;
- full automated checks and exact counts;
- JPL build and archive inspection;
- manual Joplin tests still pending;
- explicit user acceptance when received;
- Git commit/push/publish state.

Do not mark a manual checklist item complete from unit tests or code inspection.
Do not mark the slice complete while required manual acceptance remains pending.

## v2.0.0 release boundary

After SLICE 14 and SLICE 15 are accepted:

- update README.md and SPEC.md to describe opt-in editing and both keyboard and
  pointer workflows;
- ensure no current documentation still calls all kanban/matrix cards read-only;
- record the Eisenhower label migration and writable-view behavior in
  CHANGELOG.md;
- bump `src/manifest.json`, `package.json`, and `package-lock.json` together to
  `2.0.0` only at the agreed release phase;
- run the complete validation and build a fresh production JPL;
- inspect the embedded manifest/version and record its SHA-256;
- obtain explicit final manual acceptance;
- commit, push, and publish only when the user requests those external actions.