From 774e2c4d33035f7d897fd2e42d688e2762d26861 Mon Sep 17 00:00:00 2001
From: sandwich <dskvr@users.noreply.github.com>
Date: Sat, 11 Oct 2025 11:27:33 +0200
Subject: [PATCH] enhance: Conslidate README.md and consistent formatting

---
 hyprexpo/README.md | 174 ++++++++++++++++++++-------------------------
 1 file changed, 78 insertions(+), 96 deletions(-)

diff --git a/hyprexpo/README.md b/hyprexpo/README.md
index 9dc4a74..b362592 100644
--- a/hyprexpo/README.md
+++ b/hyprexpo/README.md
@@ -80,21 +80,21 @@ plugin {
 }
 ```
 
-### Configuration
+## Configuration
 
-#### Layout & Display
+### Layout & Display
 
 | key | type | description | default |
 | --- | --- | --- | --- |
 | `plugin:hyprexpo:columns` | int | how many desktops per row | `3` |
-| `plugin:hyprexpo:gaps_in` | int | inner gaps between tiles (px) | `5` |
-| `plugin:hyprexpo:gaps_out` | int | outer margin around the grid (px) | `0` |
+| `plugin:hyprexpo:gaps_in` | int | inner spacing between tiles (px) | `5` |
+| `plugin:hyprexpo:gaps_out` | int | outer margin around grid (px), animated during open/close | `0` |
 | `plugin:hyprexpo:bg_col` | color | grid background color | `rgb(111111)` |
 | `plugin:hyprexpo:workspace_method` | string | placement: `center current` or `first <ws>` | `center current` |
-| `plugin:hyprexpo:skip_empty` | bool (int) | skip empty workspaces (`1`) or not (`0`) | `0` |
+| `plugin:hyprexpo:skip_empty` | bool (int) | skip empty workspaces using selector `m` (`1`) or show all with `r` (`0`) | `0` |
 | `plugin:hyprexpo:gesture_distance` | int | swipe distance considered "max" (px) | `200` |
 
-#### Tile Appearance
+### Tile Appearance
 
 | key | type | description | default |
 | --- | --- | --- | --- |
@@ -102,55 +102,55 @@ plugin {
 | `plugin:hyprexpo:tile_rounding_power` | float | rounding power (curve exponent) | `2.0` |
 | `plugin:hyprexpo:tile_rounding_focus` | int | focus tile radius (`-1` = inherit) | `-1` |
 | `plugin:hyprexpo:tile_rounding_current` | int | current tile radius (`-1` = inherit) | `-1` |
-| `plugin:hyprexpo:border_style` | string | `simple` \| `hypr` \| `hyprland` | `simple` |
+| `plugin:hyprexpo:border_style` | string | border rendering: `simple` (solid), `hypr` (3-layer), `hyprland` (2-color gradient) | `simple` |
 | `plugin:hyprexpo:border_width` | int | border thickness (px) | `2` |
-| `plugin:hyprexpo:border_color_current` | color | color for current tile border (fallback) | `rgb(66ccff)` |
-| `plugin:hyprexpo:border_color_focus` | color | color for focus tile border (fallback) | `rgb(ffcc66)` |
-| `plugin:hyprexpo:border_grad_current` | string | hyprland gradient for current, e.g. `rgba(33ccffee) rgba(00ff99ee) 45deg` | empty |
-| `plugin:hyprexpo:border_grad_focus` | string | hyprland gradient for focus | empty |
+| `plugin:hyprexpo:border_color_current` | color | current tile border color | `rgb(66ccff)` |
+| `plugin:hyprexpo:border_color_focus` | color | focused tile border color | `rgb(ffcc66)` |
+| `plugin:hyprexpo:border_grad_current` | string | gradient for current tile (hyprland style only), e.g. `rgba(33ccffee) rgba(00ff99ee) 45deg` | empty |
+| `plugin:hyprexpo:border_grad_focus` | string | gradient for focused tile (hyprland style only) | empty |
 
-#### Labels
+### Workspace Labels
 
 | key | type | description | default |
 | --- | --- | --- | --- |
-| `plugin:hyprexpo:label_enable` | bool (int) | enable labels | `1` |
-| `plugin:hyprexpo:label_text_mode` | string | `token` | `index` | `id` | `token` |
-| `plugin:hyprexpo:label_token_map` | string | override up to 50 tokens (comma‑sep). Empty entries skip | empty |
-| `plugin:hyprexpo:label_font_size` | int | base font size (px) | `16` |
-| `plugin:hyprexpo:label_position` | string | `top-left` | `top-right` | `bottom-left` | `bottom-right` | `center` | `center` |
-| `plugin:hyprexpo:label_offset_x` | int | offset from position anchor (px) | `0` |
-| `plugin:hyprexpo:label_offset_y` | int | offset from position anchor (px) | `0` |
-| `plugin:hyprexpo:label_show` | string | `always` | `hover` | `focus` | `hover+focus` | `current+focus` | `never` | `always` |
-| `plugin:hyprexpo:label_color_default` | color | default label color | `rgb(ffffff)` |
-| `plugin:hyprexpo:label_color_hover` | color | hover label color | `rgb(eeeeee)` |
-| `plugin:hyprexpo:label_color_focus` | color | focus label color | `rgb(ffcc66)` |
-| `plugin:hyprexpo:label_color_current` | color | current label color | `rgb(66ccff)` |
+| `plugin:hyprexpo:label_enable` | bool (int) | enable workspace labels | `1` |
+| `plugin:hyprexpo:label_text_mode` | string | content: `token` (1,2..9,0,a-z), `index` (visual order), `id` (workspace ID) | `token` |
+| `plugin:hyprexpo:label_token_map` | string | override up to 50 tokens (comma-sep), e.g. `1,2,3,,,6` (empty entries skip) | empty |
+| `plugin:hyprexpo:label_position` | string | anchor: `top-left` \| `top-right` \| `bottom-left` \| `bottom-right` \| `center` | `center` |
+| `plugin:hyprexpo:label_offset_x` | int | horizontal offset from anchor (px) | `0` |
+| `plugin:hyprexpo:label_offset_y` | int | vertical offset from anchor (px) | `0` |
+| `plugin:hyprexpo:label_show` | string | visibility: `always` \| `hover` \| `focus` \| `hover+focus` \| `current+focus` \| `never` | `always` |
+| `plugin:hyprexpo:label_color_default` | color | default state text color | `rgb(ffffff)` |
+| `plugin:hyprexpo:label_color_hover` | color | hover state text color | `rgb(eeeeee)` |
+| `plugin:hyprexpo:label_color_focus` | color | focus state text color | `rgb(ffcc66)` |
+| `plugin:hyprexpo:label_color_current` | color | current workspace text color | `rgb(66ccff)` |
 | `plugin:hyprexpo:label_scale_hover` | float | scale multiplier on hover | `1.0` |
 | `plugin:hyprexpo:label_scale_focus` | float | scale multiplier on focus | `1.0` |
-| `plugin:hyprexpo:label_bg_enable` | bool (int) | draw background “bubble” | `1` |
-| `plugin:hyprexpo:label_bg_shape` | string | `circle` | `square` | `rounded` | `circle` |
-| `plugin:hyprexpo:label_bg_rounding` | int | radius for `rounded` shape (px) | `8` |
-| `plugin:hyprexpo:label_bg_color` | color | bubble color | `rgba(00000088)` |
-| `plugin:hyprexpo:label_padding` | int | bubble padding (px) | `8` |
+| `plugin:hyprexpo:label_font_size` | int | base font size (px) | `16` |
 | `plugin:hyprexpo:label_font_family` | string | Pango font family | `Sans` |
-| `plugin:hyprexpo:label_font_bold` | bool (int) | bold | `0` |
-| `plugin:hyprexpo:label_font_italic` | bool (int) | italic | `0` |
-| `plugin:hyprexpo:label_text_underline` | bool (int) | underline | `0` |
-| `plugin:hyprexpo:label_text_strikethrough` | bool (int) | strikethrough | `0` |
-| `plugin:hyprexpo:label_pixel_snap` | bool (int) | snap to integer pixels | `1` |
+| `plugin:hyprexpo:label_font_bold` | bool (int) | bold text | `0` |
+| `plugin:hyprexpo:label_font_italic` | bool (int) | italic text | `0` |
+| `plugin:hyprexpo:label_text_underline` | bool (int) | underline text | `0` |
+| `plugin:hyprexpo:label_text_strikethrough` | bool (int) | strikethrough text | `0` |
+| `plugin:hyprexpo:label_pixel_snap` | bool (int) | snap positions to integer pixels for sharper text | `1` |
 | `plugin:hyprexpo:label_center_adjust_x` | int | manual center nudge X (px) | `0` |
 | `plugin:hyprexpo:label_center_adjust_y` | int | manual center nudge Y (px) | `0` |
+| `plugin:hyprexpo:label_bg_enable` | bool (int) | draw background bubble behind text | `1` |
+| `plugin:hyprexpo:label_bg_shape` | string | bubble shape: `circle` \| `square` \| `rounded` | `circle` |
+| `plugin:hyprexpo:label_bg_rounding` | int | radius for `rounded` shape (px) | `8` |
+| `plugin:hyprexpo:label_bg_color` | color | bubble background color | `rgba(00000088)` |
+| `plugin:hyprexpo:label_padding` | int | bubble padding around text (px) | `8` |
 
-#### Keyboard Navigation
+### Keyboard Navigation
 
 | key | type | description | default |
 | --- | --- | --- | --- |
-| `plugin:hyprexpo:keynav_enable` | bool (int) | enable keynav + auto submap | `1` |
-| `plugin:hyprexpo:keynav_wrap_h` | bool (int) | wrap horizontally | `1` |
-| `plugin:hyprexpo:keynav_wrap_v` | bool (int) | wrap vertically | `1` |
-| `plugin:hyprexpo:keynav_reading_order` | bool (int) | use row‑major for horizontal moves | `0` |
+| `plugin:hyprexpo:keynav_enable` | bool (int) | enable keyboard navigation + auto submap | `1` |
+| `plugin:hyprexpo:keynav_wrap_h` | bool (int) | wrap horizontally at row edges | `1` |
+| `plugin:hyprexpo:keynav_wrap_v` | bool (int) | wrap vertically at column edges | `1` |
+| `plugin:hyprexpo:keynav_reading_order` | bool (int) | row-major horizontal moves (wrap at ends if both h+v wrap enabled) | `0` |
 
-#### Scrolling Overview (Layout-Specific)
+### Scrolling Overview (Layout-Specific)
 
 When using Hyprland's scrolling layout, HyprExpo automatically switches to a vertical scrolling overview mode.
 
@@ -159,34 +159,51 @@ When using Hyprland's scrolling layout, HyprExpo automatically switches to a ver
 | `plugin:hyprexpo:scrolling:scroll_moves_up_down` | bool (int) | if enabled, mouse wheel scrolls through workspaces; if disabled, mouse wheel zooms | `1` |
 | `plugin:hyprexpo:scrolling:default_zoom` | float | default zoom level on overview open (0.1 - 0.9) | `0.5` |
 
-**Note:** Scrolling overview mode does not support keyboard navigation. Mouse/trackpad interaction is the primary input method.
+**Note:** Scrolling overview mode does not support keyboard navigation. Mouse/trackpad interaction is the primary input method for this layout.
 
-### Keywords
+## Usage
 
-| name | description | arguments |
-| -- | -- | -- | 
-| hyprexpo-gesture | same as gesture, but for hyprexpo gestures. Supports: `expo`. | Same as gesture |
+### Dispatchers
+
+**Main expo dispatcher:**
 
-### Binding
 ```bash
-# hyprland.conf
-bind = MODIFIER, KEY, hyprexpo:expo, OPTION
+bind = SUPER, g, hyprexpo:expo, <option>
 ```
 
-Example:
+| option | description |
+| --- | --- |
+| `toggle` | show overview if hidden, hide if shown |
+| `on` / `enable` | show overview |
+| `off` / `disable` | hide overview |
+| `select` | select the hovered workspace |
+
+**Keyboard navigation dispatchers** (active during overview):
+
+| dispatcher | argument | description |
+| --- | --- | --- |
+| `hyprexpo:kb_focus` | `left` \| `right` \| `up` \| `down` | move focus across tiles |
+| `hyprexpo:kb_confirm` | none | select the focused tile |
+| `hyprexpo:kb_selecti` | `<index>` | select by 1-based visual index (1-46) |
+| `hyprexpo:kb_selectn` | `<id>` | select by workspace ID (legacy, 0→10) |
+| `hyprexpo:kb_select` | `<token>` | select by single token (1-9, 0, a-z) |
+
+### Example Bindings
+
 ```bash
-# This will toggle HyprExpo when SUPER+g is pressed
+# Toggle overview
 bind = SUPER, g, hyprexpo:expo, toggle
 
-# Optional submap for keyboard selection when Hyprexpo is active (index-based, 1..46)
+# Keyboard navigation submap (optional)
 submap = hyprexpo
+    # Arrow key navigation
     bind = , left,  hyprexpo:kb_focus, left
     bind = , right, hyprexpo:kb_focus, right
     bind = , up,    hyprexpo:kb_focus, up
     bind = , down,  hyprexpo:kb_focus, down
     bind = , return, hyprexpo:kb_confirm
 
-    # 1..10 via digits (0 -> 10)
+    # Direct selection via numbers (1-10)
     bind = , 1, hyprexpo:kb_selecti, 1
     bind = , 2, hyprexpo:kb_selecti, 2
     bind = , 3, hyprexpo:kb_selecti, 3
@@ -198,7 +215,7 @@ submap = hyprexpo
     bind = , 9, hyprexpo:kb_selecti, 9
     bind = , 0, hyprexpo:kb_selecti, 10
 
-    # 11..20 via SHIFT+digits
+    # Extended selection via SHIFT+numbers (11-20)
     bind = SHIFT, 1, hyprexpo:kb_selecti, 11
     bind = SHIFT, 2, hyprexpo:kb_selecti, 12
     bind = SHIFT, 3, hyprexpo:kb_selecti, 13
@@ -210,7 +227,7 @@ submap = hyprexpo
     bind = SHIFT, 9, hyprexpo:kb_selecti, 19
     bind = SHIFT, 0, hyprexpo:kb_selecti, 20
 
-    # 21..46 via alpha
+    # Alphabetic selection (21-46)
     bind = , a, hyprexpo:kb_selecti, 21
     bind = , b, hyprexpo:kb_selecti, 22
     bind = , c, hyprexpo:kb_selecti, 23
@@ -240,48 +257,13 @@ submap = hyprexpo
 submap = reset
 ```
 
-Here are a list of options you can use:  
-| option | description |
-| --- | --- |
-toggle | displays if hidden, hide if displayed
-select | selects the hovered desktop
-off | hides the overview
-disable | same as `off`
-on | displays the overview
-enable | same as `on`
+### Gestures
 
-Keyboard navigation dispatchers (when overview is active):
-- `hyprexpo:kb_focus, <left|right|up|down>`: moves focus across tiles (skips invalid).
-- Wrapping can be configured with `keynav_wrap_h` and `keynav_wrap_v`.
-- Reading order (row-major) for horizontal movement can be enabled with `keynav_reading_order`. At grid ends it will wrap to start/end only if both `keynav_wrap_h` and `keynav_wrap_v` are enabled.
-- `hyprexpo:kb_confirm`: selects the focused tile.
-- `hyprexpo:kb_selectn, <id>`: selects by workspace id (legacy; `0` → `10`).
-- `hyprexpo:kb_selecti, <index>`: selects by 1‑based visual index (recommended for single‑keystroke mapping).
-- `hyprexpo:kb_select, <token>`: selects by a single token (1..9, 0, a..z), mainly for symbol‑based configs.
+Custom gesture keyword for HyprExpo-specific gestures:
 
-Border styles:
-- `simple`: single-color border using `border_width`, `border_color_current`, `border_color_focus`.
-- `hypr`: layered border approximating Hyprland’s gradient borders by drawing 3 layers (lightened, base, and darkened). Uses the same base colors and splits the width across layers.
-- `hyprland`: 2-color gradient with angle. Provide gradients:
-  - `plugin:hyprexpo:border_grad_current = rgba(33ccffee) rgba(00ff99ee) 45deg`
-  - `plugin:hyprexpo:border_grad_focus   = rgba(ffdd44ee) rgba(22aaffee) 30deg`
+```ini
+# Swipe up with 4 fingers to toggle overview
+hyprexpo-gesture = swipe:4:up, hyprexpo:expo, toggle
+```
 
-Gaps:
-- `gaps_in` controls the inner spacing between tiles.
-- `gaps_out` adds an outer margin (px) around the grid (animated during open/close).
-
-Labels (numbers):
-- `label_position`, `label_offset_x`, `label_offset_y` control placement per tile.
-- `label_show` controls when labels are drawn (always/hover/focus/etc.).
-- Per-state colors: `label_color_default|hover|focus|current`.
-- Per-state scale multipliers: `label_scale_hover|focus`.
-- Optional background bubble behind text: `label_bg_*`, `label_padding`.
-- Content:
-  - `label_text_mode = token` (default) uses the token sequence (1..9,0,!,@,#,…,a..z) or `label_token_map` if provided.
-  - `label_text_mode = index` shows the 1-based visual index.
-  - `label_text_mode = id` shows the workspace ID.
-- Token overrides:
-  - `label_token_map` accepts up to 50 comma-separated entries to override tokens. Empty entries allowed (skip rendering).
-- Font & precision:
-  - `label_font_family`, `label_font_bold`, `label_font_italic`, `label_text_underline`, `label_text_strikethrough`
-  - `label_pixel_snap` (default 1) rounds positions to integer pixels for crisper text.
+Uses the same syntax as Hyprland's `gesture` keyword.