Display and layout improvements

[sarg3nt]

1. When we choose a box, its gears show up in the nav bar, but after selecting a gear they go away. They should persist.
2. When I click the all boxes button in the top left, the search and picker shows up, but I cannot click on the one and only box, as nothing happens, that should at least close the dialogue, but also, of course, select the box. I'm not sure if it's doing that because it won't let me do anything and only have one box in the system at this point.
3. The box search dialogue that opens up has the tab key that is supposed to view all the boxes, but it does not do that. It navigates through the interface. I am on a mackintosh, but I do not have the accessibility keyboard navigation settings turned on, so this should not be happening.
4. Pressing enter in the same dialogue does not do anything.
5. I want to add a keyboard shortcut to get to that dialogue. Please come up with one that will work on Windows, Linux and PC, i.e. not be taken by something by default. I'm also thinking of adding a command palette, later, so that would typically be command shift P on the Mac or control shift P on the PC.
6. Once we do add a shortcut to the dialogue of above, it would be helpful to have a shortcut help dialogue. Typically, you would get to that by pressing shift slash, which is question mark. So that should show a dialogue with all of our keyboard shortcuts.
   It would be nice if it's the type of dialogue that is frameless and just has a black background that is very transparent, so it looks all kind of smoked glass.
7. In the upper left hand corner to the right of that button that opens up, the box picker, we have the title of the plug-in that we are on, followed by a colon, followed by the name of the box. This is taking up a lot of horizontal screenville estate, especially on smaller displays.
   It is also very large and very bold. I think the 1st thing we should try is making it much smaller. And a better mnemonic might be the name of the box slash the gear name. So it would be light dash hugger slash logs for example.
   Anyway, make that a lot smaller and so that does not take up as much space.
8. On smaller displays, we have layout issues, the left hand navigation will not scroll vertically, and so things end up getting cut off, so it does need to do that, but I want it to be intelligent, and especially we do not want giant scroll bars to pop up.
   So either very small scroll bars or no scroll bars at all, and just have it be intelligent somehow. Maybe up and down arrows. I don't know. Look at what best in class navigation for this type of a situation is and replicate that
9. The edit navigation and toggle sidebar icons are really great. However, when you are on a smaller display, and the sidebar is filled up with gears, it can, they can end up taking a lot of space. I want you to find out what a best-in-class solution for this might be.
   Maybe we need to move them somewhere else, but do some searching on the internet and then give me some options.
10. Right now, the box's grid looks great, but is quite rudimentary. We need to add the ability to filter. For the boxes and sort. Many of the other plug-ins already have grids that can do this. So take a look at those and see if we can replicate that. I don't want it to be ugly though. So make sure it's one of the nice ones and that we don't reuse code.
11. Let's go ahead and get started on that command palette that I talked about earlier as well. So if the user presses control shift P, it'll bring up the command palette. Inside of the command palette, they can start typing, and the one thing I thought about was that it could bring up any of the plug-ins that we currently have installed for that machine.
    So for example, if they wanted to go to logs really quickly, they could hit control shift P, start typing in logs, and impress enter. The command pellet should list things as they type. Just like it does in visual studio code. So definitely search the internet on this and see if you can find the best in-class solution. The command palette should also be able to select a machine. So maybe you would load the PX search interface with it. And then that would pop up and then you'd be able to type in the machine names. Or, if you don't think it's too big of a struggle, we just have the command palette be able to search for machines or boxes directly in the palette itself.

[sarg3nt]

Discovery & Detailed Plan

I want to one-shot all of these changes into one larger PR so we don't split out efforts and can have maximum synergy.

Note

Throughout this plan I reference current files: header / sidebar / chip / palette live in gearbox/internal/framework/templates/layouts/base.templ; the box-switcher JS is gearbox/static/js/common/box-switcher.js; the box grid is gearbox/internal/gears/bx/pages.templ; the existing enhanced-table primitives are in gearbox/internal/framework/ui/table.templ and Tabulator is already loaded and styled (see the dark .tabulator block in base.templ, used by the OS Updates package grid).

---

1. Sidebar gears disappear after clicking a gear (bug)

Root cause. The sidebar gear list is rendered conditionally on whether a box is active in the request context — see OrderedIntegrationLinks (base.templ:1813) and isBoxScopedIntegration (base.templ:1790). The "active box" is resolved from ?box_id=<id> in the URL by InjectIntegrationStatus middleware (gearbox/internal/framework/handler/handler.go:248).

The bug: SidebarLinkDraggable (base.templ:1597) renders its <a href> as the bare gear path, e.g. /haproxy. So clicking a gear link navigates away from /home?box_id=X to /haproxy with no query string, the middleware sees no active box, and the gear list collapses to only the box-agnostic entries (Bx + Home).

Fix (preferred). Make the active-box selection persistent server-side via a cookie/session value, so it survives navigation. Specifically:

1. When the middleware sees ?box_id=<id> in the URL, also write it to a gearbox.active_box HttpOnly, SameSite=Lax cookie.
2. When ?box_id is absent, fall back to the cookie value (still subject to "must be an enabled box you can see").
3. Clearing the cookie happens implicitly when the user navigates to /bx (the fleet view) or explicitly via a "Clear box" action in the chip menu.

This also removes the ?box_id= URL churn entirely once a box is picked — the URL stays clean (/haproxy) but the gears stick. The legacy ?box_id= parameter remains supported for share-links and existing handler code so this is non-breaking.

---

2-4. Box picker dialog: single-box click, Tab, Enter all misbehave

The dialog is boxSwitcherPalette (base.templ:1961) + box-switcher.js. Three discrete bugs:

(2) Clicking the only box does nothing. Likely cause: the user is already on /bx and the only box is already the active selection. pick() (box-switcher.js:197) calls window.switchBox(id, '/home') which navigates to /home?box_id=<id>, but if the cookie/URL already implies that box, the page might not visually change. Also — even if nothing else happens, the dialog should still close as a basic UX guarantee. Today it stays open with no visible feedback.

Fix. (a) Always close the dialog on any pick (success or no-op). (b) If the picked box is already active and we're on the box's "preferred landing" path, just close — don't reload. (c) If the picked box matches the active box but we're on /bx, navigate to /home?box_id=<id> (the existing behaviour, but make sure the action runs even if the URL ends up identical, using replace not assign to avoid a junk history entry).

(3) Tab cycles the underlying page instead of the dialog. The modal has no focus trap. aria-modal="true" is set on #box-switcher-overlay (good) but no JS prevents Tab from escaping to the page chrome.

Fix. Implement a focus-trap inside the dialog:

• On open: focus the search input.
• On Tab / Shift+Tab: cycle focus among the three logical focusable elements — search input, list items (treated as one tab-stop with an internal roving tabindex), and the "View all → Bx" footer link.
• On Escape: close (already works).

The user's wording ("Tab key is supposed to view all the boxes") suggests they expect Tab to jump straight to the "View all → Bx" footer link. That's a reasonable interpretation — let's do the proper trap and document the order in the footer hint (↑↓ navigate · ↵ select · Tab footer).

(4) Enter does nothing. Enter is wired (box-switcher.js:68) so likely the failure is the same as (2) — pick() is called but the URL ends up identical and the page doesn't visibly do anything. Same fix: always close the dialog on Enter+pick, and use a replace navigation that always re-fires.

---

5. Keyboard shortcut to open the box picker

Constraints from the user: cross-platform (Mac/Win/Linux), avoid taken-by-default combos.

Findings from research:

• Ctrl+Shift+P conflicts with Firefox's "private window" on all OSes, and with Chrome's print on Windows.
• Cmd+K / Ctrl+K is the de-facto standard for app command palettes (Linear, Slack, Vercel, Discord, GitHub). Firefox treats it as "focus search bar" but apps can preventDefault() and override.
• The current g b (mnemonic = "go box") two-key sequence is already wired (box-switcher.js:84) and works well — keep it.

Recommendation. Keep g b as the two-key mnemonic, and add a single-keystroke shortcut. Two patterns to choose between:

Pattern	Box picker	Command palette	Pros	Cons
A: Unified	(part of palette)	Cmd/Ctrl+K	Fewer shortcuts to learn; matches Linear/Slack/Vercel	Box switching is one extra keypress (type "b" + name)
B: Separate	Cmd/Ctrl+B	Cmd/Ctrl+Shift+P	Direct access to each	Cmd/Ctrl+B conflicts with Firefox bookmarks sidebar; Cmd/Ctrl+Shift+P conflicts with Firefox private window

We will go with Pattern A: Unifide

---

6. Shortcut-help dialog (frosted-glass, opened by ?)

? (Shift+/) is the universal convention — used by GitHub, Gmail, Trello, Figma, Notion, Linear. Adopt it.

Design. The user asked for "frameless, very transparent black background, smoked-glass." Translates to:

• Full-viewport overlay: bg-black/40 backdrop-blur-md.
• Content container: NO solid background, instead bg-white/5 backdrop-blur-xl with thin border border-white/10 and rounded-2xl — produces the "smoked glass" effect on top of the page behind it.
• White text (text-white/90 for body, text-white for headings), monospaced <kbd> chips with bg-white/10 border border-white/20.
• Two columns of shortcut rows on wide displays, one on narrow.
• Click anywhere outside the content / Esc / ? again closes it.
• a11y: role="dialog" aria-modal="true" aria-labelledby + focus trap (same util we add for the box picker in chore(deps)(deps): bump github/codeql-action from 3 to 4 in the github-actions group #3).

Shortcut list to show (initial set, expanded as we add bindings):

Keys	Action
?	Show this help
Cmd/Ctrl+K	Open command palette
g b	Open box picker
Esc	Close dialog / overlay
↑ ↓	Navigate dialog items
↵	Select highlighted item
Tab / Shift+Tab	Cycle focus within a dialog

Implementation. New templ ShortcutHelp() in base.templ, mounted once globally (like the existing ConfirmDialog/PromptDialog/AlertDialog). JS lives in a new static/js/common/shortcut-help.js and registers the ? global keydown listener using the same "ignore when in input/textarea/contentEditable" guard as box-switcher.js.

---

7. Header title is too large

Current pattern (e.g. pages/logs.templ:13-39):

[chip] Logs : [light-hugger ▾]

rendered as text-xl font-bold — eats horizontal space on small displays and the <select> dropdown duplicates the chip's purpose.

Fix. Two changes:

1. Drop the per-page <select id="server-select"> widget entirely. It's redundant with the chip, and ~20 page templates carry their own copy. The chip is now the canonical box-switching affordance.
2. Shrink the title. Render as text-sm font-medium text-gray-600 in the format <box>/<gear> (the user's suggested mnemonic: light-hugger/logs).

Since the page-header injection (static/js/common/page-header.js) is just a JS shuttle that moves a hidden div into the header slot, we can simplify each page's page-header-source to just title + controls — no server-selector. The 20-page rewrite is purely deletion and a style-class swap; it's mechanical.

Single-box installs: render just <gear-name> (no slash, no box) since there's no ambiguity.

Optional polish: make the title a breadcrumb-style clickable — clicking the <box> segment opens the box picker, clicking <gear> is a no-op (you're there). Subtle visual cue with a hover:underline only on the box segment.
Yes, I like the above, add the breadcrumb-style

---

8. Sidebar nav vertical scroll on small displays

Current state: <nav class="flex-1 py-4"> with <ul id="sidebar-nav-list" class="space-y-1"> — no overflow-y set, so on a viewport shorter than the cumulative nav height the bottom items just get clipped behind the toggle/user/settings rows.

Best-in-class patterns surveyed:

• macOS / Cockpit: overlay scrollbars — invisible until you hover/scroll, then a thin pill appears that auto-hides.
• VS Code: thin (10px) scrollbar with subtle thumb, no track.
• GitHub: thin scrollbar with scrollbar-width: thin on Firefox, custom 8px-wide WebKit styling.
• Slack / Linear: invisible until hover; no fade in/out, just appears.

Choice. Implement overlay-style thin scrollbar on <nav>:

#sidebar nav { overflow-y: auto; }
/* Firefox */
#sidebar nav { scrollbar-width: thin; scrollbar-color: transparent transparent; }
#sidebar nav:hover { scrollbar-color: rgba(148,163,184,0.5) transparent; }
/* WebKit */
#sidebar nav::-webkit-scrollbar { width: 6px; }
#sidebar nav::-webkit-scrollbar-track { background: transparent; }
#sidebar nav::-webkit-scrollbar-thumb { background: transparent; border-radius: 3px; }
#sidebar nav:hover::-webkit-scrollbar-thumb { background: rgba(148,163,184,0.5); }
.dark #sidebar nav:hover::-webkit-scrollbar-thumb { background: rgba(100,116,139,0.5); }

Additionally — and this is the bigger usability win — collapse the sidebar's footer (Edit / Toggle buttons + User row + Settings) into a single flex-shrink-0 block, so the <nav> takes whatever vertical space is actually left. Today the footer can balloon when "Edit Nav" is active and push the nav region into clip territory.

I considered the "up/down arrow" pattern the user mentioned — those are typically used for horizontal lists (e.g. macOS Finder's column view scroll indicators) or for very tall lists where overlay scrollbars don't read well. With 8 gears max + 2 system entries, overlay scrollbars are the right call. User agrees.

---

9. Edit-nav / toggle-sidebar icons crowd the sidebar footer

Currently both buttons live in #toggle-container (base.templ:1335) — a 2-column grid that becomes 1-column when sidebar is collapsed.

Survey of patterns:

• VS Code: gear icon (settings) in the activity bar, dragdrop/reorder is a context menu on items, no dedicated "edit nav" button.
• Slack: "more" kebab menu in sidebar header; sidebar mode toggle in the workspace settings.
• Linear: no edit-nav UI at all — reordering is via long-press drag on the item itself; sidebar collapse is a button at the very top.
• GitHub: sidebar customization lives in Settings → Appearance, not a button.

Recommendation. Two-pronged:

1. Move "Toggle Sidebar" to the top of the sidebar, next to the Gearbox logo (matches Linear/Notion). This is the more frequent action and benefits from a stable, predictable position.
2. Demote "Edit Navigation" out of the persistent UI entirely. Reorder gears by right-clicking a gear (context menu with "Reorder gears" → enters edit mode), OR via the new command palette (Cmd+K → "Reorder sidebar"). Edit mode itself is unchanged once entered.

This gives the footer back to the user row + settings, which is what every other dashboard does.

User: Above sounds great.

---

10. Boxes grid: add filter + sort

Tabulator is already integrated (loaded in base.templ, full dark-mode styles, used by os-updates' package grid at os-updates-page.js:2253). Re-use it for the boxes grid — that's "reuse the nice grid we already have" and avoids hand-rolling sort/filter logic.

Plan.

1. Replace boxTable() (pages.templ:139) with a <div id="bx-grid"></div> that Tabulator mounts into.
2. Server-render the row data into a <script type="application/json" id="bx-data">…</script> block (avoids a round-trip on first paint, keeps SSE-pushed updates wiring).
3. Configure Tabulator with:
   • layout: 'fitColumns', virtualDom: true, pagination: false (small dataset).
   • Columns: Status (custom formatter with the dot + tooltip), Name, Location, Agent URL, Latency, Last Checked.
   • headerFilter: 'input' on Name / Location / Agent URL (string), headerFilter: 'list' on Status (Healthy / Warning / Critical / Disabled / Unknown), headerFilter: 'number' on Latency.
   • headerSort: true on all columns; default sort by Name asc.
   • Persist column widths + sort state to localStorage under bx-grid-state (Tabulator supports this natively via persistence: { sort: true, filter: true, columns: true }).
4. Keep the existing SSE wiring in bx-page.js:85-117 but route updates through installedPkgTable.updateData() instead of direct DOM patching — Tabulator handles row replacement and re-rendering in place.
5. Click-to-navigate stays: bind rowClick to boxDefaultPath(row.getData().box_id).

Yes, reuse tabulator, we just merged in changes from a previous branch with a new skin and styling that is much nicer. You can look at the data grids in the OS Updates for reference.

---

11. Command palette (Cmd/Ctrl+K)

The destination feature. Inspired by Linear/Vercel/Slack/cmdk-js. Vanilla JS — no React.

Scope of what the palette can do (v1):

• Navigate to a gear — Logs, HAProxy, Metrics, Services, Certificates, Traffic, Alerts, OS Updates, Bx, Home, Settings. Filtered to gears available for the active box.
• Switch box — every configured box. Picking one navigates to /home?box_id=… (or the current path with ?box_id= if it's box-agnostic-compatible). Add, ctrl+enter on a box keeps command pallet open with the text focus back on the textbox input with the expectation the user will filter for a gear. Have the pallet show the list of gears by default at this point.
• Quick actions — Toggle theme (light/dark), Toggle sidebar, Reorder sidebar, Show keyboard shortcuts (?), Log out.

Results are grouped by section ("Boxes", "Gears", "Actions") with a section heading per group, like Linear. Fuzzy match across all items at once; typing log shows the Logs gear, plus any box whose name contains log.

UI.

• Same overlay/dialog pattern as the box switcher (matches existing visual language), but wider (w-[640px] max-w-[92vw]) and taller (max-h-[70vh]).
• Top: search input with magnifying-glass icon, <kbd>esc</kbd> chip.
• Body: scrollable list grouped by section; each row has icon + label + optional subtitle + optional <kbd> for its own direct shortcut.
• Footer: ↑↓ navigate · ↵ select · esc close.
• "Recent" section at top showing last 3-5 used items (stored in localStorage). Empty on first run.

Fuzzy matching. Use a tiny dependency-free fuzzy implementation (~30 lines, score by char-distance like fzf-lite). Already-installed fuse.js or similar overkill — write it inline. Reference for the algorithm: fzf scoring.

Wiring.

• New templ CommandPalette() in base.templ, mounted globally.
• New static/js/common/command-palette.js. Reuses the global keydown registry we add in Default dashboard shows Widget Error for missing alert-banner widget #6 (consolidated from box-switcher's ad-hoc handler).
• New endpoint GET /api/command-palette/items returns the JSON catalog of all available actions/boxes/gears for the current user. Same auth.GetGearOrderFromContext / GetAllBoxesFromContext source the sidebar uses; one source of truth.
• Cached client-side for the session (refresh on box-list mutation via SSE or on Cmd+K reopen after >30s).

a11y.

• role="dialog" aria-modal="true" aria-activedescendant="…" on the input, with aria-owns pointing at the result list.
• role="listbox" on the result UL, role="option" per row with aria-selected="true" on the cursor row.
• Focus trap (same util as Default dashboard shows Widget Error for missing alert-banner widget #6).

---

Sources

• Command Palette Pattern — UX Patterns for Developers
• cmdk — command menu primitives
• Maggie Appleton — Command K Bars (survey of palette implementations)
• W3C ARIA APG — Dialog (Modal) Pattern
• W3C ARIA APG — Developing a Keyboard Interface
• JupyterLab — Cmd+Shift+P conflicts with Firefox private window
• MDN — CSS scrollbar styling
• Pencil & Paper — Filter UX Design Patterns for enterprise tables
• Mannhowie — Data Table UX: 5 Rules of Thumb
• bazza/ui — Data Table Filter

[sarg3nt]

Update: revising item 10 to match the new createDataGrid skin

On the current feature/45-held-packages branch, the OS Updates page's Tabulator has been refactored to a cleaner pattern that should be the canonical "nice grid" style going forward. This changes my plan for item 10 (and answers one of my open questions).

What the new pattern looks like

The branch introduces a reusable wrapper at gearbox/static/js/common/datagrid.js paired with gearbox/static/css/components/datagrid.css:

const grid = createDataGrid('#my-table', {
    columns: [...],
    data: [...],
    searchInput: '#my-search',           // external <input> for fuzzy filtering
    searchFields: ['name', 'description'],
    // ...standard Tabulator options pass through
});

grid.setViewFilters([{field: 'status', type: '=', value: 'active'}]);  // composes with search
grid.clearViewFilters();

Key characteristics of this style (UniFi-inspired):

• No per-column header filter row — the second header row with the filter… inputs is gone. Just one clean header row.
• External search box in the page toolbar (toolbar-mounted, paired with the datagrid-search-wrap CSS for the magnifying-glass icon). One input, fuzzy-matches across every searchable field.
• Flat header — no background, no column dividers, no uppercase tracking. Lowercase, regular-weight column names.
• Hover-only sort arrows — sort indicators are invisible until you hover the column, then fade in. The active sort column gets a blue title + arrow.
• No zebra stripes — single subtle horizontal line between rows, transparent backgrounds.
• Draggable columns — movableColumns: true is on by default.
• View-filter / search composition — toggling between view states (e.g. "Updates / Held / All") sets view filters via setViewFilters() rather than setFilter(), so they AND-compose with whatever text is in the search box instead of clobbering it.

The OS Updates page already migrated to this in the working tree (see gearbox/static/js/os-updates/os-updates-page.js lines ~2140-2330) — headerFilter: 'input' is removed from every column, a #pkg-search input is added to the toolbar, and installedPkgTable.setFilter(...) calls are now installedPkgTable.setViewFilters(...).

Revised plan for item 10 (boxes grid)

Replace what was in the original comment with this:

1. Replace boxTable() in gearbox/internal/gears/bx/pages.templ:139 with a <div id="bx-grid"></div> mount point.
2. Add a toolbar row above the grid containing:
   • A datagrid-search-wrap block with <input type="search" id="bx-search" placeholder="Search boxes…"> — the one universal filter.
   • (Optional) a view-toggle dropdown (e.g. "All / Healthy / Issues / Disabled") that calls bxGrid.setViewFilters(...) on change. Mirrors the OS Updates "Updates / Held / All" pattern.
3. Server-render the row data into a <script type="application/json" id="bx-data">…</script> block.
4. Mount via createDataGrid('#bx-grid', { ... }) with:
   • Standard Tabulator column defs (no headerFilter).
   • searchInput: '#bx-search', searchFields: ['name', 'location', 'agent_url'].
   • initialSort: [{ column: 'name', dir: 'asc' }].
   • Optional persistence: { sort: true, columns: true } for per-user column-width/sort memory in localStorage.
5. The existing SSE wiring in bx-page.js:85-117 continues to push status-dot/latency/last-checked updates; route those through bxGrid.updateData() rather than direct DOM patching.
6. Click-to-navigate stays: bind rowClick to boxDefaultPath(row.getData().box_id).

This deletes the open question I had ("which grid library?") — the in-house createDataGrid wrapper is the answer. It also crisply matches the user's intent on item 10 ("nice grid, don't duplicate code, reuse what already exists").

Cross-cutting implications

Item 11 (command palette) becomes more important. With per-column filters gone, the command palette is the natural home for power-user filtering verbs that don't belong in a single text box — e.g. Cmd+K → "Show only disabled boxes", or filtering boxes by region/location/health. We won't build that in v1 of the palette, but the wider scope is now an explicit follow-up.

The toolbar-mounted search input becomes a house-wide UI pattern. Anywhere we previously considered per-column filtering (in Alerts, Services, Certificates, Traffic — all of which currently have ad-hoc filter inputs), this pattern is the migration target. Out of scope for this issue, but worth flagging so future grid work doesn't fork the style again.

Item 6 (shortcut help) should advertise the new search input. Add a row like:

Keys	Action
/ (when on a grid page)	Focus the page's grid search input

/ is the universal "start searching" key (GitHub, Linear, Slack). Implementation: a tiny global handler that, when the active page has an #…-search input registered, focuses it on / press (skipping when an input/textarea already has focus). Cheap to add.

Updated PR split

PR	Items	Scope
1	1	Persist active box via cookie + middleware fallback
2	2, 3, 4	Box-picker bug bash: always-close, focus trap, Enter/click reliability
3	7	Shrink header title, drop redundant per-page server selector
4	8, 9	Sidebar scroll + footer reorg
5	10	Migrate boxes grid to createDataGrid (no header filters; external #bx-search)
6	5, 6, 11	Command palette + shortcut help + global hotkey registry + / to focus grid search

PR 5 now blocks nothing — it's a 100-line drop-in once feature/45-held-packages lands on main, since the wrapper, CSS, and SSE adapter are already proven on OS Updates.