Add nightwatch75/todo 0.0.7 — prioritised to-do list (bar widget + panel) (#18)

* Add nightwatch75/todo 0.0.6 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * To Do 0.0.7: make priority sort a view; never rewrite the manual order Review fix: switching to priority mode used to sort the items array and persist it, destroying the manual ordering. items and the on-disk tasks array now always hold the manual order; priority mode stable-sorts a copy at render time only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Massimiliano <m.angei@iotron.it> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-15 19:42:00 -04:00
parent c50b326223
commit 138e991a8e
6 changed files with 895 additions and 0 deletions
@@ -0,0 +1,106 @@
+# To Do
+
+A [noctalia](https://github.com/noctalia-dev/noctalia) v5 bar plugin: a
+prioritised to-do list. Click the bar glyph to toggle a panel of task rows —
+add tasks with **+**, tick them off (the text is struck through), delete them,
+and set each task's priority. The list is kept sorted by priority and stored as
+a single JSON file; no external commands are run.
+
+| Action                       | Effect                                              |
+|-------------------------------|-----------------------------------------------------|
+| Left click (bar glyph)        | Open/close the To Do panel                          |
+| **+** (panel header)          | Add a new task and start typing it                  |
+| Sort toggle (panel header)    | Switch ordering between **Priority** and **Manual** |
+| Colour chip (row)             | Cycle the task's priority: important → medium → low |
+| ☰ grip (row, manual only)     | Pick the row up / drop the held row here (reorder)  |
+| Click the text, or ✎ (pencil) | Edit the task's text                                |
+| **Enter**, or ✓ (row)         | Commit the edit — the row goes back to a static line |
+| ☐ / ☑ button (row)            | Toggle done/to-do (done tasks are struck through)   |
+| 🗑 button (row)                | Delete the task                                     |
+
+## Priorities
+
+Each task carries a priority, shown at the start of the row as a small coloured
+square. Click the square to cycle it. A legend at the foot of the panel maps
+each colour to its category:
+
+| Priority  | Colour |
+|-----------|--------|
+| Important | red    |
+| Medium    | amber  |
+| Low       | green  |
+
+## Ordering
+
+The panel header carries a toggle that switches between two ordering modes; the
+choice is remembered.
+
+- **Priority** (default) — rows are sorted by priority: important first, then
+  medium, then low. Changing a task's priority moves it into its new group but
+  keeps its position relative to its peers; equal-priority rows are never
+  reshuffled. No grips are shown.
+- **Manual** — rows keep the order you give them. Each row grows a ☰ grip on the
+  left; here changing a priority only recolours the chip and never moves the row.
+
+Priority mode is only a view: the stored order is always the manual one, so
+switching between the two modes (as often as you like) never loses your custom
+ordering.
+
+### Reordering in manual mode
+
+The noctalia plugin UI exposes no drag callbacks (only clicks), so the ☰ grip
+reorders with two clicks instead of a drag:
+
+1. Click a row's ☰ grip — it lights up; that row is now "held".
+2. Click another row's ☰ grip — the held row drops in just above it.
+3. Click the held row's own grip again to cancel.
+
+## Editing
+
+Rows are static lines by default. Click a task's text (or its ✎ pencil button)
+to edit it; press **Enter** or the ✓ button to commit back to a static line. A
+new task (**+**) opens straight into edit mode — committing it while still empty
+simply discards it. Edits are also autosaved after a short idle pause and on
+close.
+
+Tick a task (☐ → ☑) to complete it — its text is struck through until you
+un-tick it. The bar glyph's tooltip shows how many tasks are still to do.
+
+## Storage
+
+Tasks live in one file, `todo.json`, inside the configured **To Do folder**
+(default `~/Documents/Todo`). It is a small JSON object,
+`{ "version": 2, "sort": "priority" | "manual", "tasks": [ … ] }`, where `tasks`
+is the array of `{ id, text, priority, done }` objects (in manual order) — easy
+to read, hand-edit, sync, or back up. An older plain-array file is still read
+automatically. The plugin runs no external programs.
+
+## Settings
+
+| Setting      | What it does                                             |
+|--------------|----------------------------------------------------------|
+| To Do folder | Where `todo.json` is stored (default `~/Documents/Todo`).|
+| Bar glyph    | The glyph shown for the widget on the bar.               |
+
+## Install
+
+Install **To Do** from Noctalia's plugin store (*Settings → Plugins*), then add
+the widget to a bar from *Settings → Bar*. Plugin options live in
+*Settings → Plugins*.
+
+For local development, add your working copy as a path source instead
+(`.luau` edits hot-reload):
+
+```sh
+noctalia msg plugins source add dev path /path/to/plugins
+noctalia msg plugins enable nightwatch75/todo
+```
+
+## Requirements
+
+- noctalia ≥ 5.0.0
+- No external dependencies
+
+## License
+
+MIT.