feat: add keybind cheatsheet plugin (#64)
* feat: add keybind cheatsheet * docs: refresh keybind cheatsheet preview * docs: use official generated keybind thumbnail * feat(keybind-cheatsheet): preload cached snapshots Move parser and cache ownership into an event-driven data service so the panel opens from a prepared last-known-good snapshot. Document the plugin's inspiration and independent v5 implementation.
This commit is contained in:
cheerfulScumbag
@@ -0,0 +1,170 @@
|
||||
# Keybind Cheatsheet
|
||||
|
||||
Keybind Cheatsheet opens a searchable Noctalia panel containing the active
|
||||
Mango, Hyprland, or Niri shortcuts. It follows split configuration files,
|
||||
formats common hardware keys, and keeps custom descriptions and hidden rows.
|
||||
|
||||
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
Keybind Cheatsheet was inspired by the original
|
||||
[Keybind Cheatsheet for Noctalia v4](https://github.com/4rmcyt/noctalia-plugins/tree/main/keybind-cheatsheet)
|
||||
created by [blackbartblues](https://github.com/blackbartblues).
|
||||
|
||||
This Noctalia v5 plugin is an independent implementation rather than a direct
|
||||
port. It has its own user interface, service and cache lifecycle, persistence
|
||||
model, tests, and integration with the current Noctalia plugin API.
|
||||
|
||||
## Plugin
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| ID | `kenn/keybind-cheatsheet` |
|
||||
| Entries | Data service: `data`; bar widget: `keybinds`; panel: `cheatsheet` |
|
||||
|
||||
`kenn` is the plugin's fixed publisher namespace, not your local Linux
|
||||
username. Copy the plugin IDs in the commands below unchanged. User-specific
|
||||
configuration paths use the portable `~/.config/...` form.
|
||||
|
||||
## Requirements
|
||||
|
||||
Install `hyprctl` on `PATH` when using a Hyprland Lua configuration. Mango,
|
||||
Niri, and classic Hyprland configurations do not spawn external commands.
|
||||
|
||||
No clipboard command is required. Color paste uses Noctalia's native clipboard
|
||||
API.
|
||||
|
||||
## Usage
|
||||
|
||||
Enable the plugin, then add the `keybinds` widget from Noctalia's bar widget
|
||||
picker. Clicking its keyboard glyph toggles the cheatsheet.
|
||||
|
||||
Open or close the panel without a bar widget:
|
||||
|
||||
```sh
|
||||
noctalia msg panel-toggle kenn/keybind-cheatsheet:cheatsheet
|
||||
```
|
||||
|
||||
Bind that command in the active compositor.
|
||||
|
||||
Mango:
|
||||
|
||||
```ini
|
||||
bind=SUPER,F1,spawn,noctalia msg panel-toggle kenn/keybind-cheatsheet:cheatsheet
|
||||
```
|
||||
|
||||
Hyprland classic configuration:
|
||||
|
||||
```ini
|
||||
bind = SUPER, F1, exec, noctalia msg panel-toggle kenn/keybind-cheatsheet:cheatsheet
|
||||
```
|
||||
|
||||
Niri:
|
||||
|
||||
```kdl
|
||||
Mod+F1 { spawn "noctalia" "msg" "panel-toggle" "kenn/keybind-cheatsheet:cheatsheet"; }
|
||||
```
|
||||
|
||||
Type in the search field to filter by key, description, action, or category.
|
||||
Use the header pencil to enter edit mode. Edit mode keeps hidden bindings
|
||||
visible with muted content while descriptions and visibility are changed with
|
||||
the row's pencil and eye buttons; leaving edit mode applies those visibility
|
||||
choices to the main keymap. The palette button opens key-color controls with
|
||||
native color picking, clipboard paste, and reset actions.
|
||||
|
||||
## Supported configuration
|
||||
|
||||
| Compositor | Default | Parsing |
|
||||
| --- | --- | --- |
|
||||
| Mango | `~/.config/mango/config.conf` | `bind`, `axisbind`, `mousebind`, `gesturebind`, `switchbind`, `source`, and `source-optional` |
|
||||
| Hyprland classic | `~/.config/hypr/hyprland.conf` | `bind*` directives, variables, and recursive `source` paths |
|
||||
| Hyprland Lua | `~/.config/hypr/hyprland.lua` | Live `hyprctl binds -j` data plus category and description scanning through `require()` files |
|
||||
| Niri | `~/.config/niri/config.kdl` | KDL `binds` blocks, action categorization, and recursive `include` paths |
|
||||
|
||||
Includes support `*`, `?`, and bracket glob components. Traversal is limited to
|
||||
32 levels and 256 files, and repeated paths are visited once to stop cycles.
|
||||
|
||||
Category comments use the same forms as the earlier Noctalia plugin:
|
||||
|
||||
```ini
|
||||
# Applications
|
||||
bind=SUPER,T,spawn,foot #"Terminal"
|
||||
```
|
||||
|
||||
```ini
|
||||
# 1. Applications
|
||||
bind = SUPER, T, exec, foot #"Terminal"
|
||||
```
|
||||
|
||||
```kdl
|
||||
// #"Applications"
|
||||
Mod+T hotkey-overlay-title="Terminal" { spawn "foot"; }
|
||||
```
|
||||
|
||||
Hyprland Lua category scanning recognizes `-- 1. Applications` headings and
|
||||
literal `description` or `desc` fields. Concatenated descriptions such as
|
||||
`"Workspace " .. i` are treated as prefixes.
|
||||
|
||||
## Settings
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `compositor` | `select` | `auto` | Detect Mango, Hyprland, or Niri, or force one parser. |
|
||||
| `mango_config` | `file` | `~/.config/mango/config.conf` | Main Mango configuration. |
|
||||
| `hyprland_config` | `file` | `~/.config/hypr/hyprland.conf` | Main classic Hyprland configuration. |
|
||||
| `hyprland_lua_config` | `file` | `~/.config/hypr/hyprland.lua` | Lua file scanned for categories. |
|
||||
| `hyprland_parser` | `select` | `auto` | Select live Lua or classic parsing. |
|
||||
| `niri_config` | `file` | `~/.config/niri/config.kdl` | Main Niri configuration. |
|
||||
| `columns` | `int` | `3` | Maximum balanced columns, from 1 to 4. |
|
||||
| `show_undescribed` | `bool` | `true` | Show bindings that have no description. |
|
||||
| `show_actions` | `bool` | `false` | Show the compositor action under descriptions. |
|
||||
| `glyph` | `glyph` | `keyboard` | Bar widget icon. |
|
||||
|
||||
Noctalia v5 owns panel dimensions and does not expose runtime auto-height.
|
||||
This plugin uses a wide 1500 x 760 panel, scrolling, and a responsive cap on
|
||||
the requested column count.
|
||||
|
||||
## IPC
|
||||
|
||||
Refresh the snapshot after editing compositor configuration:
|
||||
|
||||
```sh
|
||||
noctalia msg plugin kenn/keybind-cheatsheet:data all refresh
|
||||
```
|
||||
|
||||
The data service refreshes even when the panel is closed. Opening and reopening
|
||||
the panel only renders the prepared snapshot. The bar entry also accepts
|
||||
`toggle` and `refresh` when a widget instance exists:
|
||||
|
||||
```sh
|
||||
noctalia msg plugin kenn/keybind-cheatsheet:keybinds focused toggle
|
||||
noctalia msg plugin kenn/keybind-cheatsheet:keybinds focused refresh
|
||||
```
|
||||
|
||||
For parser development, run the fixture suite inside Noctalia:
|
||||
|
||||
```sh
|
||||
noctalia msg plugin kenn/keybind-cheatsheet:data all self-test
|
||||
```
|
||||
|
||||
The report is logged and written to the plugin's persistent data directory as
|
||||
`selftest.json`.
|
||||
|
||||
## Notes
|
||||
|
||||
One event-driven data service loads the durable binding cache and parses the
|
||||
selected compositor configuration once when Noctalia loads the plugin. It then
|
||||
remains idle until settings change or a refresh is explicitly requested. It
|
||||
uses no update interval, filesystem watcher, polling loop, network request, or
|
||||
persistent subprocess. Hyprland Lua mode runs the fixed command
|
||||
`hyprctl binds -j` asynchronously.
|
||||
|
||||
The last successful parsed snapshot is stored as `bindings-cache.json`. The
|
||||
panel reads the shared in-memory snapshot and performs no configuration I/O in
|
||||
`onOpen()`. A failed refresh keeps the previous bindings visible and reports
|
||||
the error without replacing the durable cache.
|
||||
|
||||
Custom descriptions, hidden binding identities, and color overrides are stored
|
||||
in Noctalia's per-plugin state directory as `preferences.json`. The file
|
||||
contains no command output or configuration contents.
|
||||
Reference in New Issue
Block a user