feat: Add Hyprland special workspaces plugin (#116)

* feat: Add Hyprland special workspaces plugin * fix: Nest translation keys under settings object
2026-07-26 23:06:15 -04:00
parent 4d1d17f39a
commit 0d4f1277c4
6 changed files with 466 additions and 0 deletions
@@ -0,0 +1,52 @@
+# Special Workspaces
+
+Displays populated and currently active Hyprland special workspaces as compact
+chips in the Noctalia bar.
+
+## Plugin
+
+| Field | Value |
+| --- | --- |
+| ID | `jamesfeeder/special-workspaces` |
+| Entries | Bar widget: `special-workspaces`; service: `workspace-state` |
+
+## Requirements
+
+- Noctalia v5 with plugin API 3 or newer.
+- Hyprland, including its `hyprctl` utility.
+- Install `socat` on `PATH`.
+
+## Usage
+
+Enable `jamesfeeder/special-workspaces` in **Settings → Plugins**, then add
+**Special Workspaces** to the bar from **Settings → Bar**.
+
+The widget shows special workspaces in alphabetical order. Active workspaces
+remain visible when empty. Inactive workspaces appear only while populated and
+can be hidden with `hide_inactive`.
+
+## Settings
+
+| Setting | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max_label_chars` | `int` | `0` | Maximum Unicode characters shown from each workspace name. `0` shows the full name. |
+| `hide_inactive` | `bool` | `false` | Hide populated workspaces unless they are visible on a monitor. |
+| `capsule_radius` | `int` | `8` | Corner radius in logical pixels. Negative values are treated as `0`. |
+| `capsule_padding` | `int` | `5` | Space before and after the label along the bar axis, in logical pixels. Negative values are treated as `0`. |
+| `capsule_min_width` | `int` | `35` | Minimum capsule length along the bar axis, in logical pixels. Negative values are treated as `0`. |
+| `active_style` | `select` | `"fill"` | Active capsule style: `"fill"` or `"ghost"`. |
+| `inactive_style` | `select` | `"fill"` | Inactive capsule style: `"fill"` or `"ghost"`. Hidden when `hide_inactive` is enabled. |
+
+## Notes
+
+- Active means visible on any monitor, not focused.
+- Fill style uses `primary` colors for active workspaces and `secondary` colors
+  for inactive workspaces. Ghost style uses a transparent fill with `primary`
+  or `on_surface` text.
+- On vertical bars, capsules grow vertically and display one Unicode character
+  per line from top to bottom.
+- The service snapshots `hyprctl -j clients` and `hyprctl -j monitors`, then
+  listens to Hyprland's `.socket2.sock` through `socat`.
+- If the event socket disconnects, the service waits for it to return,
+  refreshes its snapshot, and reconnects. It retains the last valid state while
+  `hyprctl` is unavailable and retries failed snapshots up to twice.