diff --git a/docs/4-implementation/web-ui/swarm-ui.md b/docs/4-implementation/web-ui/swarm-ui.md
index 546babe9e..319cf90ca 100644
--- a/docs/4-implementation/web-ui/swarm-ui.md
+++ b/docs/4-implementation/web-ui/swarm-ui.md
@@ -37,6 +37,10 @@ inside it and ends on its backdrop, so selecting text can't close it by accident
dashboard's side panel is inert while shut, takes the focus when it opens and gives
it back when it closes.
+A badge's popover opens under the badge. When it doesn't fit there, it opens
+over the badge, and when it fits neither way it takes the roomier side and scrolls
+inside itself, so it stays on the page.
+
A dialog grows to fit its content, up to 64em or nine tenths of the window, whichever is
smaller; short confirm dialogs stay short.
@@ -913,19 +917,20 @@ to each agent. The controller tries an agent whose account the forge refuses aga
every five minutes.
The **ssh** row is whether the agent may get SSH certificates from the swarm: a
-badge reading on or off, off by default. Selecting it opens an explainer, a
-checkbox that does a `PUT` of `ssh` with the stored permissions beside it, and
-a folded **on the target** section. That section reads `GET /api/ssh/ca` and
+badge reading on or off, off by default. Selecting it opens a warning, a
+checkbox that does a `PUT` of `ssh` with the stored permissions, and folded
+sections: **how it works**, **on the target** and **connections**. The **on the target** section reads `GET /api/ssh/ca` and
shows the swarm's CA key and the agent's name as the lines for a NixOS machine,
a home-manager user and a plain `authorized_keys` file, with a copy button; the
card builds the text in `frontend/packages/swarm-ui/src/agent/detail/ssh.ts`. Above the checkbox the card shows a warning (SSH access to an
-unconstrained machine leaves the agent with no limits there), the explainer with the delays,
-and how to forget a host key that changed. The card says the change takes seconds, and why: the controller rewrites the role
+unconstrained machine leaves the agent with no limits there). The **how it works**
+section holds the explainer with the delays and how to forget a host key that
+changed. The card says the change takes seconds, and why: the controller rewrites the role
when the field changes and the agent signs on its next `ssh`. A `PUT`
that leaves `ssh` out, and the `DELETE` of **use the default**, keep it. The
controller attaches the signing policy to the agent's login role at once; see [the SSH CA](../swarm/ssh-ca.md#the-switch-and-the-signing-policy).
-Below the checkbox, a folded **connections** section holds the agent's named SSH
+The folded **connections** section holds the agent's named SSH
connections. Each is a `name; user; host; port` entry that becomes `ssh ` in
the agent's ssh config, and its hive lets the agent reach that host and port. A
connection only takes effect while **ssh** is on, and the section says so when the
diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx
index 54305445c..d79af3ee6 100644
--- a/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx
+++ b/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx
@@ -1,7 +1,8 @@
// — one agent's SSH access in an opened agent card: a badge that
-// opens an explainer, the switch, a folded "on the target" section with the text
-// a machine needs to trust the agent's certificates, and a folded "connections"
-// section for the agent's named connections (`AgentSshConnections`).
+// opens a warning and the switch, then three folded sections: "how it works"
+// (the explainer), "on the target" (the text a machine needs to trust the
+// agent's certificates) and "connections" (the agent's named connections, in
+// `AgentSshConnections`).
//
// The switch is the `ssh` field of `GET/PUT /api/agents/{name}/permissions`,
// shared with the other grant controls through `useGrant`. The CA key comes
@@ -86,22 +87,6 @@ export function AgentSsh({ agent, g }: { agent: string; g: GrantState }) {
sandbox stops it doing, it can do on a machine it can log in to. Only
allow this for machines you would let {agent} control completely.
-
- Lets {agent} log in over SSH to machines that trust the swarm's SSH
- certificate authority. With this on, {agent} signs its own key for a
- certificate that names it, on its first ssh after the
- swarm has updated its login, which takes seconds. The certificate
- lasts one hour, and the key lives in memory only. Switching off stops
- new certificates within seconds; one already signed stays valid until
- it expires, an hour after signing. A machine has to trust the
- authority before anything works: see "on the target" below.
-
-
- {agent} accepts the key a machine shows on the first connection and
- refuses a changed one afterwards (trust on first use). If a host's key
- really changed, check the new key out of band, then forget the old one
- with {forgetHostKeyCommand(agent)} on the hive host.
-
) : null}
+
+ how it works
+
+ Lets {agent} log in over SSH to machines that trust the swarm's SSH
+ certificate authority. With this on, {agent} signs its own key for a
+ certificate that names it, on its first ssh after the
+ swarm has updated its login, which takes seconds. The certificate
+ lasts one hour, and the key lives in memory only. Switching off
+ stops new certificates within seconds; one already signed stays
+ valid until it expires, an hour after signing. A machine has to
+ trust the authority before anything works: see "on the target"
+ below.
+
+
+ {agent} accepts the key a machine shows on the first connection and
+ refuses a changed one afterwards (trust on first use). If a host's
+ key really changed, check the new key out of band, then forget the
+ old one with {forgetHostKeyCommand(agent)} on the hive
+ host.
+
+
on the target
{snippet === null ? (
diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css b/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css
index 3c293c0ce..5e3067a25 100644
--- a/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css
+++ b/frontend/packages/swarm-ui/src/agent/detail/AgentSshConnections.css
@@ -1,6 +1,13 @@
/* The named SSH connections of an agent card: a table that scrolls on its own on
a narrow screen rather than breaking the popover. */
+/* The sections of the ssh popover never grow past it: a wide table scrolls in its
+ own box instead of giving the popover a sideways scroll. */
+.ui-agent-ssh-target {
+ max-width: 100%;
+}
.ui-agent-ssh-connections {
+ min-width: 0;
+ max-width: 100%;
display: flex;
flex-direction: column;
gap: 0.75em;
diff --git a/frontend/packages/swarm-ui/src/ui/popover/Popover.tsx b/frontend/packages/swarm-ui/src/ui/popover/Popover.tsx
index af8b70b35..456a861c9 100644
--- a/frontend/packages/swarm-ui/src/ui/popover/Popover.tsx
+++ b/frontend/packages/swarm-ui/src/ui/popover/Popover.tsx
@@ -28,7 +28,7 @@ import {
import { createPortal } from "preact/compat";
import type { ComponentChildren, RefObject } from "preact";
import { useDismiss } from "@hive/shared/use-dismiss.js";
-import { clampLeft } from "../table/popover-position.js";
+import { clampLeft, placeVertically } from "../table/popover-position.js";
import { focusInto, restoreFocus, triggerOf } from "./focus.js";
import "./Popover.css";
@@ -52,7 +52,11 @@ export function Popover({
children: ComponentChildren;
}) {
const ref = useRef(null);
- const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
+ const [pos, setPos] = useState<{
+ top: number;
+ left: number;
+ maxHeight: number;
+ } | null>(null);
const id = useId();
const wasOpen = useRef(false);
@@ -97,20 +101,42 @@ export function Popover({
if (!anchor) return;
const r = anchor.getBoundingClientRect();
const width = ref.current?.offsetWidth ?? 0;
- const top = r.bottom + GAP_PX;
+ // The content's own height, not the box's: the box is already cut to the
+ // room it was given, and measuring that would keep it cut.
+ const content = (ref.current?.scrollHeight ?? 0) + 2;
+ const { top, maxHeight } = placeVertically(
+ r.top,
+ r.bottom,
+ content,
+ window.innerHeight,
+ GAP_PX,
+ );
const left = clampLeft(r.left, width, window.innerWidth);
// Scrolling anywhere (the streaming terminal included) calls this; keep
// the old object when nothing moved so the subtree does not re-render.
setPos((prev) =>
- prev && prev.top === top && prev.left === left ? prev : { top, left },
+ prev &&
+ prev.top === top &&
+ prev.left === left &&
+ prev.maxHeight === maxHeight
+ ? prev
+ : { top, left, maxHeight },
);
}
place();
window.addEventListener("scroll", place, true);
window.addEventListener("resize", place);
+ // The content can change size while the box is open (a folded section
+ // opens), and the box then needs another place.
+ const watch =
+ typeof ResizeObserver === "undefined" || !ref.current
+ ? null
+ : new ResizeObserver(place);
+ if (watch && ref.current) watch.observe(ref.current);
return () => {
window.removeEventListener("scroll", place, true);
window.removeEventListener("resize", place);
+ watch?.disconnect();
};
}, [open, anchorRef]);
@@ -129,7 +155,11 @@ export function Popover({
ref={ref}
style={
pos
- ? { top: `${pos.top}px`, left: `${pos.left}px` }
+ ? {
+ top: `${pos.top}px`,
+ left: `${pos.left}px`,
+ maxHeight: `${pos.maxHeight}px`,
+ }
: { visibility: "hidden" }
}
>
diff --git a/frontend/packages/swarm-ui/src/ui/table/popover-position.ts b/frontend/packages/swarm-ui/src/ui/table/popover-position.ts
index e2c0e4bfe..719c5364b 100644
--- a/frontend/packages/swarm-ui/src/ui/table/popover-position.ts
+++ b/frontend/packages/swarm-ui/src/ui/table/popover-position.ts
@@ -1,4 +1,4 @@
-// Where a table's filter popover sits, without a DOM.
+// Where a floating popover sits, without a DOM.
// Space kept between a floating box and the viewport's edge.
const POPOVER_EDGE_PX = 8;
@@ -17,3 +17,27 @@ export function clampLeft(
const maxLeft = viewportWidth - width - POPOVER_EDGE_PX;
return Math.max(POPOVER_EDGE_PX, Math.min(left, maxLeft));
}
+
+/**
+ * The top edge and the tallest height for a popover of `height` that hangs
+ * from an anchor spanning `anchorTop` to `anchorBottom`: under the anchor when
+ * it fits there, over it when it does not and there is more room above, and
+ * otherwise under it again with the height cut to the room left, so it scrolls
+ * inside itself. A popover under a badge near the foot of the window would
+ * otherwise run off the page.
+ */
+export function placeVertically(
+ anchorTop: number,
+ anchorBottom: number,
+ height: number,
+ viewportHeight: number,
+ gap: number,
+): { top: number; maxHeight: number } {
+ const below = viewportHeight - anchorBottom - gap - POPOVER_EDGE_PX;
+ const above = anchorTop - gap - POPOVER_EDGE_PX;
+ if (height <= below || above <= below) {
+ return { top: anchorBottom + gap, maxHeight: Math.max(below, 0) };
+ }
+ const h = Math.min(height, above);
+ return { top: anchorTop - gap - h, maxHeight: above };
+}
diff --git a/frontend/packages/swarm-ui/test/popover-position.test.mjs b/frontend/packages/swarm-ui/test/popover-position.test.mjs
index 4fa69d46d..1ae8c9e6c 100644
--- a/frontend/packages/swarm-ui/test/popover-position.test.mjs
+++ b/frontend/packages/swarm-ui/test/popover-position.test.mjs
@@ -3,7 +3,10 @@
// imported as it is.
import assert from "node:assert/strict";
import { test } from "node:test";
-import { clampLeft } from "../src/ui/table/popover-position.ts";
+import {
+ clampLeft,
+ placeVertically,
+} from "../src/ui/table/popover-position.ts";
test("a popover near the right edge is pulled back on screen", () => {
// 300 wide in a 1000 wide window: the right edge may reach 992.
@@ -15,3 +18,32 @@ test("a popover never goes past the left edge", () => {
assert.equal(clampLeft(5, 300, 1000), 8);
assert.equal(clampLeft(50, 2000, 1000), 8);
});
+
+// A 600 tall window, a badge from 300 to 330, a gap of 4 and an edge of 8:
+// 258 is free under it and 288 over it.
+test("a popover that fits under its anchor goes there", () => {
+ assert.deepEqual(placeVertically(300, 330, 200, 600, 4), {
+ top: 334,
+ maxHeight: 258,
+ });
+});
+
+test("one that does not fit under goes over when there is more room there", () => {
+ assert.deepEqual(placeVertically(300, 330, 280, 600, 4), {
+ top: 16,
+ maxHeight: 288,
+ });
+});
+
+test("one taller than either side is cut to the roomier side and scrolls", () => {
+ // Over the anchor: 288 free, so it is 288 tall and ends 4 above it.
+ assert.deepEqual(placeVertically(300, 330, 900, 600, 4), {
+ top: 8,
+ maxHeight: 288,
+ });
+ // Near the top there is more room under it: it stays there, cut short.
+ assert.deepEqual(placeVertically(20, 50, 900, 600, 4), {
+ top: 54,
+ maxHeight: 538,
+ });
+});