From 6ee86c543054a1a6d32c27e4c66082760af4ee9f Mon Sep 17 00:00:00 2001
From: Jimmy Cozza <moatcozza@gmail.com>
Date: Wed, 14 Jan 2026 13:49:35 -0700
Subject: [PATCH] sync: port AwesomeWM #4042 - customizable modifier sorting in
 hotkeys popup

Add widget.modifier_sort_order table allowing users to customize how
modifier keys are sorted when displayed in the hotkeys popup.

Default order: Alt, Ctrl, Shift, Super (alphabetical)
Users can override in rc.lua after requiring awful.hotkeys_popup.

Upstream: https://github.com/awesomeWM/awesome/pull/4042
---
 lua/awful/hotkeys_popup/widget.lua | 38 +++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/lua/awful/hotkeys_popup/widget.lua b/lua/awful/hotkeys_popup/widget.lua
index 20fb3d7..f4e03dc 100644
--- a/lua/awful/hotkeys_popup/widget.lua
+++ b/lua/awful/hotkeys_popup/widget.lua
@@ -109,11 +109,47 @@ local widget = {
     group_rules = {},
 }
 
+--- Sort order for the hotkey modifiers
+--
+-- @tfield table awful.hotkeys_popup.widget.modifier_sort_order
+-- @tfield int Alt   Alt key priority
+-- @tfield int Ctrl  Ctrl key priority
+-- @tfield int Shift Shift key priority
+-- @tfield int Super Super key priority
+--
+-- @usage
+-- To use change the sorting order for hotkey modifiers, add the following line
+-- to your rc.lua file, after require("awful.hotkeys_popup"):
+--
+--     hotkeys_popup.widget.modifier_sort_order = {
+--         Shift = 1,
+--         Ctrl  = 2,
+--         Super = 3,
+--         Alt   = 4,
+--     }
+--
+-- Setting 2 or more modifiers to the same number will cause their relative
+-- sorting order to be undefined.
+widget.modifier_sort_order = {
+    Alt   = 1,
+    Ctrl  = 2,
+    Shift = 3,
+    Super = 4,
+}
+
 --- Don't show hotkeys without descriptions.
 -- @tfield boolean widget.hide_without_description
 -- @param boolean
 widget.hide_without_description = true
 
+local function modifier_join_plus_sort(modifiers)
+    if #modifiers<1 then return "none" end
+    table.sort(modifiers, function(a,b)
+            return widget.modifier_sort_order[a] < widget.modifier_sort_order[b]
+        end)
+    return table.concat(modifiers, '+')
+end
+
 --- Merge hotkey records into one if they have the same modifiers and
 -- description. Records with five or more keys will abbreviate them.
 --
@@ -394,7 +430,7 @@ function widget.new(args)
         for _, mod in ipairs(data.mod) do
             table.insert(readable_mods, self.labels[mod] or mod)
         end
-        local joined_mods = join_plus_sort(readable_mods)
+        local joined_mods = modifier_join_plus_sort(readable_mods)
 
         local group = data.group or "none"
         self._group_list[group] = true