From fc44891ab5a0acb244618cf3c5c92f77a6460b7c Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Tue, 18 Aug 2026 22:49:04 +0200
Subject: [PATCH] swarm-ui: compact refresh-interval picker, moved into the
 panel header

Per mara's review on this PR: the labelled SelectField-based picker
read as way too heavy for a passive-until-touched setting - a full
label+bordered-control form field row above the table. Replace it with
a compact inline "clock icon - value - chevron" control (a native
<select> still drives the interaction, just stripped of SelectField/
FormField's chrome), quiet until hovered/focused the same way
LinksMenu's header button is.

Also move it out of the panel body entirely: Panel gains an `actions`
slot in its title row (right-aligned via margin-left: auto), so the
picker sits next to the "hives" heading instead of taking its own row
and pushing the table down - per the design guide's own "a control
belongs next to the thing it affects" rule.

Verified with headless chromium screenshots (full page + a tight
close-up crop) against the built bundle: the picker now reads as
"(clock) 30s (chevron)" inline with the panel title, no extra vertical
space taken from the table. Added a Panel "with actions" demo to
ComponentsPage.
---
 .../swarm-ui/src/pages/ComponentsPage.tsx     |  8 +++
 .../packages/swarm-ui/src/pages/HivesPage.tsx |  6 +-
 .../packages/swarm-ui/src/ui/panel/Panel.css  | 18 +++++-
 .../packages/swarm-ui/src/ui/panel/Panel.tsx  | 26 +++++++-
 .../ui/refresh-interval/RefreshInterval.css   | 42 +++++++++++++
 .../ui/refresh-interval/RefreshInterval.tsx   | 60 ++++++++++++++-----
 6 files changed, 139 insertions(+), 21 deletions(-)
 create mode 100644 frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.css

diff --git a/frontend/packages/swarm-ui/src/pages/ComponentsPage.tsx b/frontend/packages/swarm-ui/src/pages/ComponentsPage.tsx
index 94cec45f..0bdca539 100644
--- a/frontend/packages/swarm-ui/src/pages/ComponentsPage.tsx
+++ b/frontend/packages/swarm-ui/src/pages/ComponentsPage.tsx
@@ -101,6 +101,14 @@ export function ComponentsPage() {
         <Sample label="without title">
           <Panel>panel body content, no title</Panel>
         </Sample>
+        <Sample label="with actions (e.g. HivesPage's refresh picker)">
+          <Panel
+            title="example title"
+            actions={<RefreshIntervalPicker id="sample-panel-actions" value={30_000} onChange={() => {}} />}
+          >
+            panel body content
+          </Panel>
+        </Sample>
       </Section>
 
       <Section title="StatusChip">
diff --git a/frontend/packages/swarm-ui/src/pages/HivesPage.tsx b/frontend/packages/swarm-ui/src/pages/HivesPage.tsx
index 5df35f72..7149e62f 100644
--- a/frontend/packages/swarm-ui/src/pages/HivesPage.tsx
+++ b/frontend/packages/swarm-ui/src/pages/HivesPage.tsx
@@ -113,8 +113,10 @@ export function HivesPage() {
   });
 
   return (
-    <Panel title="hives">
-      <RefreshIntervalPicker id="hives-refresh" value={intervalMs} onChange={setIntervalMs} />
+    <Panel
+      title="hives"
+      actions={<RefreshIntervalPicker id="hives-refresh" value={intervalMs} onChange={setIntervalMs} />}
+    >
       {error ? <ApiErrorPanel context="failed to load the hive roster" problem={error} /> : null}
       {!error && hives === null ? <p>loading…</p> : null}
       {hives ? <Table columns={COLUMNS} rows={hives} rowKey={(h) => h.name} /> : null}
diff --git a/frontend/packages/swarm-ui/src/ui/panel/Panel.css b/frontend/packages/swarm-ui/src/ui/panel/Panel.css
index 23a40980..0132d514 100644
--- a/frontend/packages/swarm-ui/src/ui/panel/Panel.css
+++ b/frontend/packages/swarm-ui/src/ui/panel/Panel.css
@@ -3,12 +3,26 @@
   border-radius: 0.5em;
   background: var(--bg-elev);
 }
+.ui-panel-header {
+  display: flex;
+  align-items: center;
+  gap: 1em;
+  padding: 0.75em 1em;
+  border-bottom: 1px solid var(--border);
+}
 .ui-panel-title {
   margin: 0;
-  padding: 0.75em 1em;
   font-size: 1em;
   font-weight: 600;
-  border-bottom: 1px solid var(--border);
+}
+/* `margin-left: auto` (not `justify-content: space-between` on the
+   header) so actions still land at the right edge even on the rare
+   panel that has actions but no title. */
+.ui-panel-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5em;
+  margin-left: auto;
 }
 .ui-panel-body {
   padding: 1em;
diff --git a/frontend/packages/swarm-ui/src/ui/panel/Panel.tsx b/frontend/packages/swarm-ui/src/ui/panel/Panel.tsx
index de8f88db..eea69b56 100644
--- a/frontend/packages/swarm-ui/src/ui/panel/Panel.tsx
+++ b/frontend/packages/swarm-ui/src/ui/panel/Panel.tsx
@@ -2,13 +2,35 @@
 // bordered surface with an optional title, no other opinions. Not a
 // card-with-actions/footer/whatever kit — those get added the first
 // time a real page actually needs one, not speculatively ahead of it.
+//
+// `actions` is that one addition: a slot in the title row, right-
+// aligned, for a control that belongs next to the panel's own heading
+// rather than its own row inside the body (design guide: "a control
+// belongs next to the thing it affects, not tucked into a catch-all
+// menu" — and per mara's review on the refresh-interval PR, not a
+// dedicated row stealing vertical space from the panel's actual
+// content either). `HivesPage`'s refresh-interval picker is the
+// motivating caller.
 import type { ComponentChildren } from 'preact';
 import './Panel.css';
 
-export function Panel({ title, children }: { title?: string; children: ComponentChildren }) {
+export function Panel({
+  title,
+  actions,
+  children,
+}: {
+  title?: string;
+  actions?: ComponentChildren;
+  children: ComponentChildren;
+}) {
   return (
     <section class="ui-panel">
-      {title ? <h2 class="ui-panel-title">{title}</h2> : null}
+      {title || actions ? (
+        <div class="ui-panel-header">
+          {title ? <h2 class="ui-panel-title">{title}</h2> : null}
+          {actions ? <div class="ui-panel-actions">{actions}</div> : null}
+        </div>
+      ) : null}
       <div class="ui-panel-body">{children}</div>
     </section>
   );
diff --git a/frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.css b/frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.css
new file mode 100644
index 00000000..0e1a134d
--- /dev/null
+++ b/frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.css
@@ -0,0 +1,42 @@
+/* Compact "clock icon · value · chevron" control — see RefreshInterval.tsx
+   for why this isn't `SelectField`'s label+bordered-control chrome. Quiet
+   until interacted with (no border/fill at rest), matching LinksMenu's
+   header-button treatment so it reads as chrome, not a form. */
+.ui-refresh-picker {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35em;
+  min-height: 2.75em;
+  padding: 0 0.6em;
+  border: 1px solid transparent;
+  border-radius: 0.4em;
+  color: var(--muted);
+  font-size: 0.9em;
+  cursor: pointer;
+}
+.ui-refresh-picker:hover,
+.ui-refresh-picker:focus-within {
+  border-color: var(--border);
+  background: var(--bg);
+  color: var(--fg);
+}
+/* The select drives the interaction (native listbox, keyboard, a11y) but
+   contributes no chrome of its own — its own box is invisible, sized to
+   just its selected option's text, and its default arrow is stripped
+   since the chevron span stands in for it. */
+.ui-refresh-picker-select {
+  appearance: none;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+  padding: 0;
+  margin: 0;
+  cursor: pointer;
+}
+.ui-refresh-picker-icon,
+.ui-refresh-picker-chevron {
+  font-size: 0.85em;
+  line-height: 1;
+}
diff --git a/frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.tsx b/frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.tsx
index ca98dac1..5a0979bd 100644
--- a/frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.tsx
+++ b/frontend/packages/swarm-ui/src/ui/refresh-interval/RefreshInterval.tsx
@@ -8,12 +8,25 @@
 // file since neither is useful without the other and splitting them
 // would be two files for one concern.
 //
+// The picker itself is a compact "clock icon · value · chevron" inline
+// control, not a labelled `SelectField` — per mara's review, a full
+// label+bordered-control form field reads as way too heavy for a
+// passive-until-touched setting that lives in a panel's title row
+// (`Panel`'s `actions` slot), not a form. Visually quiet (no border/
+// fill until hovered/focused) the same way `LinksMenu`'s header button
+// is, so it reads as chrome rather than another input to fill in. A
+// native `<select>` still drives it (no custom dropdown/listbox to
+// reinvent) — `appearance: none` strips its default arrow so the
+// chevron span can stand in for it, and the visible "value" text is
+// just whichever `<option>` the browser is already rendering as
+// selected, not a second copy of the label kept in sync by hand.
+//
 // The hook, not the picker, owns re-fetch safety: a caller passes its
 // own fetch callback, and it's the CALLER's job to make sure that
 // callback doesn't clobber an input the operator is mid-edit on — this
 // hook only decides *when* to call it.
 import { useEffect, useRef } from 'preact/hooks';
-import { SelectField, type SelectOption } from '../select-field/SelectField.js';
+import './RefreshInterval.css';
 
 // `null` means "off" throughout this module — no separate boolean, so
 // there's exactly one way to represent "not polling".
@@ -26,10 +39,6 @@ const PRESETS: { value: RefreshIntervalMs; label: string }[] = [
   { value: 60_000, label: '1m' },
 ];
 
-// `SelectField` only speaks strings, so presets round-trip through the
-// label side of `PRESETS` rather than a second parallel list.
-const OPTIONS: SelectOption[] = PRESETS.map((p) => ({ value: p.label, label: p.label }));
-
 export function RefreshIntervalPicker({
   id,
   value,
@@ -41,16 +50,37 @@ export function RefreshIntervalPicker({
 }) {
   const current = PRESETS.find((p) => p.value === value) ?? PRESETS[0];
   return (
-    <SelectField
-      id={id}
-      label="refresh"
-      value={current.label}
-      onChange={(label) => {
-        const preset = PRESETS.find((p) => p.label === label);
-        if (preset) onChange(preset.value);
-      }}
-      options={OPTIONS}
-    />
+    // A `<label>` wrapper (not a bare `<span>`) so the icon/chevron
+    // padding is part of the click/tap target too, not just the native
+    // select box itself — same touch-target-floor reasoning as the rest
+    // of the kit, just without a visible label string to hang it off
+    // of (hence the `aria-label` on the `<select>` for the accessible
+    // name a sighted-only icon+chevron can't supply).
+    <label class="ui-refresh-picker" for={id}>
+      <span class="ui-refresh-picker-icon" aria-hidden="true">
+        🕐
+      </span>
+      <select
+        id={id}
+        class="ui-refresh-picker-select"
+        aria-label="refresh interval"
+        value={current.label}
+        onChange={(e) => {
+          const label = (e.target as HTMLSelectElement).value;
+          const preset = PRESETS.find((p) => p.label === label);
+          if (preset) onChange(preset.value);
+        }}
+      >
+        {PRESETS.map((p) => (
+          <option key={p.label} value={p.label}>
+            {p.label}
+          </option>
+        ))}
+      </select>
+      <span class="ui-refresh-picker-chevron" aria-hidden="true">
+        ⌄
+      </span>
+    </label>
   );
 }