A local-first multi-agent app development platform, built on PenguinHarness
/**
* A conversation's row in the sidebar's list, and the hover actions it shares with the other
* conversation rows.
*
* The row is the title — with an agent's avatar before it where the group does not name the
* agent — the marks of its standing arrangements, its live state and its waiting approvals, and a
* trailing slot that swaps what it shows: the compact last-active time at rest, and on hover or
* focus the direct actions and the "more" button that opens the whole set as a menu. The same
* menu opens at the pointer on a right-click, from the keyboard with Shift+F10, and on touch with
* a press-and-hold (`useRowContextMenu`, whose handlers the row spreads); a hold's replayed click
* does not also open the conversation. Both panels go through the dropdown's body portal, so the
* sidebar's scroller cannot clip them.
*
* Every mark after the title names itself, in a hint and in visually hidden text, which is what
* lets the standing ones recede to the subtle ink: the program that opened it (its source),
* pinned, relayed to a messaging channel, scheduled to run on its own, and work still running in
* the background. The live state (a turning hourglass, the compress mark, the unread dot) has one
* reserved box, kept empty when there is nothing to show, so the title never re-flows as a run
* starts, finishes and is read.
*
* The title is the caller's to draw, with the classes the row hands `renderTitle`: the row
* decides the ink and the weight, the caller its own truncation — the app's line reveals a
* clipped tail by scrolling it while the row is hovered or focused, keyed on the row's
* `data-title-reveal`. The trailing slot's width is fixed per language (`timeSlot`), so the marks
* that end the title sit at one x from row to row, and the hover actions are anchored to its right
* edge so every row's icons form one column.
*
* With a `selection` the row is a batch picker's row rather than a place to go: its checkbox takes
* the leading edge, the row's click ticks it, and the hover actions step aside for the duration.
*/
import type { DragEvent as ReactDragEvent, MouseEvent as ReactMouseEvent, ReactNode } from "react";
import { ICON_SIZE } from "../../../icon-scale";
import {
ActivityIcon,
BackgroundTasksMark,
ScheduleMark,
} from "../../icons/activity-icon/activity-icon";
import type { ActivityIconState } from "../../icons/activity-icon/activity-icon";
import { Checkbox } from "../../forms/checkbox/checkbox";
import { AgentAvatar } from "../../icons/avatars/agent-avatar";
import { GlyphIcon } from "../../icons/glyph-icon/glyph-icon";
import { ICONS } from "../../icons/icons";
import { NAV_FILL } from "../../navigation/nav-list/nav-list";
import { Dropdown } from "../../overlays/dropdown/dropdown";
import { MenuItem } from "../../overlays/menu/menu";
import type { AnchorRect } from "../../overlays/portal-panel/context-menu";
import { useRowContextMenu } from "../../overlays/portal-panel/use-row-context-menu";
/** One thing a row can do to what it stands for, as its hover button or its menu row draw it. */
export interface RowActionItem {
/** Stable within the row. */
id: string;
/** The label in the row's current state: the menu row's words, the hover button's name. */
label: string;
/** The glyph's path, from the icon registry. */
glyph: string;
/** Destructive: the danger ink on the menu row and on the hover button's hover. */
danger?: boolean;
onSelect: () => void;
}
/** A hover button's glyph: a notch under the icon-button rung, sized to the row's 24px buttons. */
export const ROW_ACTION_GLYPH = 14;
/**
* The hover buttons: the reveal is gated on pointer events exactly as on opacity, because an
* invisible button still takes taps, and on a touch screen — where `hover:` never matches — these
* are invisible for the whole session. Keyboard focus is unaffected by `pointer-events`, so Tab
* still reaches them, and revealing one re-arms its click. `focus` rather than `focus-visible`:
* the time they swap with hides on plain focus-within, and the two must agree or the slot goes
* blank. The sidebar's nav entries draw their pin toggle with the same look (sidebar-frame.tsx).
*/
export const ROW_HOVER_BUTTON =
"pointer-events-none flex h-6 w-6 shrink-0 items-center justify-center rounded-sm text-fg-subtle opacity-0 transition-[color,opacity] duration-150 focus:pointer-events-auto focus:opacity-100 group-hover:pointer-events-auto group-hover:opacity-100";
/**
* A row's hover affordance: its direct actions as icon buttons that fade in over the row's end,
* then the "more" button that opens the row's menu anchored at its own box, so every menu action
* is one visible click away rather than right-click only. Hover and focus only — desktop — since
* a touch screen reaches the same menu by holding the row. The row that holds them carries the
* `group` scope.
*/
export function RowHoverActions({
actions,
moreLabel,
onMore,
}: {
actions: readonly RowActionItem[];
/** The "more" button's name and hint. */
moreLabel: string;
/** Opens the row's menu anchored at the "more" button's own box. */
onMore: (anchor: AnchorRect) => void;
}) {
const openMore = (e: ReactMouseEvent<HTMLButtonElement>) => {
const r = e.currentTarget.getBoundingClientRect();
onMore({ top: r.top, bottom: r.bottom, left: r.left, right: r.right });
};
return (
<>
{actions.map((action) => (
<button
key={action.id}
type="button"
data-tooltip={action.label}
aria-label={action.label}
onClick={action.onSelect}
className={`${ROW_HOVER_BUTTON} ${
action.danger === true ? "hover:text-tone-danger-fg" : "hover:text-fg"
}`}
>
<GlyphIcon d={action.glyph} size={ROW_ACTION_GLYPH} />
</button>
))}
<button
type="button"
data-tooltip={moreLabel}
aria-label={moreLabel}
aria-haspopup="menu"
onClick={openMore}
className={`${ROW_HOVER_BUTTON} hover:text-fg`}
>
{/* Hairline-stroke dots vanish at this size, so the ellipsis is drawn filled: the stroke
rides on top of the fill, landing the dots at the other glyphs' weight. */}
<GlyphIcon d={ICONS.ellipsis} size={ROW_ACTION_GLYPH} filled />
</button>
</>
);
}
/** A standing arrangement's mark after the title: the glyph, its hint, and its words for a reader. */
function RowMark({ glyph, label }: { glyph: string; label: string }) {
return (
<span data-tooltip={label} className="shrink-0 text-fg-subtle">
<GlyphIcon d={glyph} size={ICON_SIZE.rowMark} />
<span className="sr-only">{label}</span>
</span>
);
}
/** The live state's box: its glyph, or the same box empty, so the title never re-flows. */
function StatusSlot({
activity,
}: {
activity: { state: ActivityIconState; label: string } | null;
}) {
if (activity === null) return <span aria-hidden="true" className="block h-3 w-3 shrink-0" />;
return <ActivityIcon activity={activity.state} label={activity.label} />;
}
export interface SessionRowProps {
/** The conversation's id, written on the row's button for tests and for the app to find it. */
sessionId: string;
/** Draws the title line with the classes the row hands over (its ink and weight). */
renderTitle: (className: string) => ReactNode;
/** The open conversation: the selected wash and the title's medium weight. */
active?: boolean;
/** Archived: the title recedes to the subtle ink. */
archived?: boolean;
/** The conversation's agent, as a small avatar before the title (where its group is not the agent). */
agent?: { id: string; name: string };
/**
* The program that opened it (an API caller, a scheduled task, a parent agent, a CLI run): the
* caller's glyph from the icon registry, named by `sourceLabel`. Drawn only when both are given.
*/
sourceGlyph?: string;
sourceLabel?: string;
/** Pinned to the top of its list: the pin mark, named by this. */
pinnedLabel?: string;
/** Relayed to a messaging channel: the paper plane, named by this (the channel's name). */
relayLabel?: string;
/** A scheduled task will run it: the alarm clock, named by this. */
scheduledLabel?: string;
/** Background work it owns is still running: the pulse, named by `label`; none at a count of 0. */
background?: { count: number; label: string };
/** Its live state; null (or omitted) keeps the box empty. */
activity?: { state: ActivityIconState; label: string } | null;
/** Approvals waiting: the count in the attention ink, its hint; none at a count of 0. */
approvals?: { count: number; label: string };
/**
* Batch picking: the row carries a checkbox before its title, named by `label`, and the whole
* row toggles the tick instead of opening the conversation — and the hover actions step aside,
* since the row is being chosen rather than acted on one at a time.
*/
selection?: { checked: boolean; label: string; onToggle: () => void };
/** The compact last-active time at rest; "" draws none. */
time: string;
/**
* The width the trailing slot reserves, fixed per language: `wide` where the longest compact
* time runs longer ("12月31日", "59 分钟前"), `narrow` otherwise ("Nov 30").
*/
timeSlot?: "narrow" | "wide";
/** The direct actions the hover reveals, before the "more" button. */
hoverActions: readonly RowActionItem[];
/** The whole set, in the menu the "more" button, a right-click, Shift+F10 or a hold opens. */
menuActions: readonly RowActionItem[];
/** The "more" button's name and hint. */
moreLabel: string;
onOpen: () => void;
/** Manual order: the row can be dragged (the caller wires the handlers). */
draggable?: boolean;
/** While another row is dragged over this one: the edge the drop would land on. */
dropEdge?: "above" | "below" | null;
onDragStart?: (e: ReactDragEvent) => void;
onDragEnd?: () => void;
onDragOver?: (e: ReactDragEvent) => void;
onDragLeave?: () => void;
onDrop?: (e: ReactDragEvent) => void;
}
export function SessionRow({
sessionId,
renderTitle,
active = false,
archived = false,
agent,
sourceGlyph,
sourceLabel,
pinnedLabel,
relayLabel,
scheduledLabel,
background,
activity = null,
approvals,
selection,
time,
timeSlot = "narrow",
hoverActions,
menuActions,
moreLabel,
onOpen,
draggable = false,
dropEdge = null,
onDragStart,
onDragEnd,
onDragOver,
onDragLeave,
onDrop,
}: SessionRowProps) {
const ctx = useRowContextMenu();
/** A hover button closes an open menu before it acts. */
const fromHover = (action: RowActionItem): RowActionItem => ({
...action,
onSelect: () => {
ctx.close();
action.onSelect();
},
});
/**
* A menu row hands focus back to the row before acting: the panel unmounts under the reader,
* and the menu is the only keyboard route to some actions, so a Shift+F10 → Enter reader would
* otherwise land on the page's body and lose their place in the list. An action that opens a
* dialog takes focus from there as usual.
*/
const fromMenu = (action: RowActionItem) => () => {
ctx.returnFocus()?.focus();
ctx.close();
action.onSelect();
};
const titleInk = active ? "font-medium text-fg" : archived ? "text-fg-subtle" : "text-fg/80";
return (
<li
className="relative"
{...(draggable
? { draggable: true, onDragStart, onDragEnd, onDragOver, onDragLeave, onDrop }
: {})}
>
{/* The drop line: a thin accent rule on the edge a dragged row would land on. */}
{dropEdge !== null && (
<div
aria-hidden
className={`pointer-events-none absolute inset-x-1 z-10 h-0.5 rounded-full bg-accent ${
dropEdge === "above" ? "-top-px" : "-bottom-px"
}`}
/>
)}
<div
data-title-reveal
ref={ctx.rowRef}
// Right-click, Shift+F10 and press-and-hold open the row's menu; the browser's own menu
// is suppressed on this row only. select-none keeps a held press from raising the text
// selection callout on touch instead of the menu.
{...ctx.rowProps}
className={`group flex select-none items-center rounded-md pr-1 transition-colors duration-150 ${
draggable ? "cursor-grab " : ""
}${active ? NAV_FILL.selected : NAV_FILL.hover}`}
>
{/* The tick stands outside the row's button: a checkbox inside it would be opened by the
same click that picks it, and a batch picker is exactly the place where that click must
mean one thing. */}
{selection !== undefined && (
<span className="flex shrink-0 items-center pl-2.5">
<Checkbox
checked={selection.checked}
onChange={selection.onToggle}
aria-label={selection.label}
/>
</span>
)}
<button
type="button"
data-testid="session-row"
data-session-id={sessionId}
// A press-and-hold that opened the menu must not also open the conversation: touch
// screens replay the held press as a click once the finger lifts.
onClick={() => {
if (ctx.consumeLongPressClick()) return;
// Picking: the row is the target, so its click ticks it — landing in the open
// conversation mid-selection would take the list away from the reader.
if (selection !== undefined) selection.onToggle();
else onOpen();
}}
className="flex min-w-0 flex-1 items-center gap-1.5 px-2.5 py-1.5 text-left"
>
{agent !== undefined && (
<span data-tooltip={agent.name} className="flex shrink-0 items-center">
<AgentAvatar
id={agent.id}
name={agent.name}
size={ICON_SIZE.rowLead}
className="rounded-sm"
/>
{/* The avatar is hidden from assistive technology and the hint serves pointers only:
the agent's name reaches everyone else as hidden text inside the row's button. */}
<span className="sr-only">{agent.name}</span>
</span>
)}
{renderTitle(`min-w-0 flex-1 font-sans text-sm ${titleInk}`)}
{sourceGlyph !== undefined && sourceLabel !== undefined && (
<RowMark glyph={sourceGlyph} label={sourceLabel} />
)}
{pinnedLabel !== undefined && <RowMark glyph={ICONS.pin} label={pinnedLabel} />}
{relayLabel !== undefined && <RowMark glyph={ICONS.paperPlane} label={relayLabel} />}
{scheduledLabel !== undefined && (
<ScheduleMark label={scheduledLabel} size={ICON_SIZE.rowMark} />
)}
{background !== undefined && background.count > 0 && (
<BackgroundTasksMark label={background.label} size={ICON_SIZE.rowMark} />
)}
<StatusSlot activity={activity} />
{/* A numeral in the attention ink, with no pill: a filled chip beside the title reads as
a second button. The numeral is a mark, so its words reach a screen reader as hidden
text and a pointer as the hint. */}
{approvals !== undefined && approvals.count > 0 && (
<span
data-tooltip={approvals.label}
className="shrink-0 text-xs font-semibold tabular-nums text-tone-attention-fg"
>
<span aria-hidden>{approvals.count}</span>
<span className="sr-only">{approvals.label}</span>
</span>
)}
</button>
{/* The trailing slot: the time at rest, the hover actions over it. Its width is fixed so
the marks before it hold one x from row to row; the actions are a constant-width
group anchored at its right edge, so their glyphs form one column; the swap is an
opacity handoff (the actions precede the time, so the peer rule can reach it). */}
<div
className={`relative flex h-6 shrink-0 items-center justify-end ${
timeSlot === "wide" ? "w-[4.5rem]" : "w-14"
}`}
>
<div className="peer absolute right-0 top-1/2 flex -translate-y-1/2 items-center">
{selection === undefined && (
<RowHoverActions
actions={hoverActions.map(fromHover)}
moreLabel={moreLabel}
onMore={ctx.openAt}
/>
)}
</div>
{time !== "" && (
<span
aria-hidden
// The time gives way to the hover actions; while picking, those are absent and the
// time is the row's only trailing reading, so it stays put.
className={`pointer-events-none whitespace-nowrap px-1 text-right text-xs tabular-nums text-fg-subtle${
selection === undefined
? " transition-opacity duration-150 group-hover:opacity-0 peer-focus-within:opacity-0"
: ""
}`}
>
{time}
</span>
)}
</div>
{/* The menu. `contents` keeps this wrapper out of the row's layout: the panel is
portaled, and its anchor is the point the gesture landed on (or the "more" button's
box), not this element. */}
<Dropdown
open={ctx.open}
setOpen={ctx.setOpen}
portal={{ direction: "down", align: "left" }}
anchorRect={ctx.anchor}
anchorOwner={ctx.anchorOwner}
returnFocus={ctx.returnFocus}
className="contents"
menuClass="w-36"
button={null}
>
{menuActions.map((action) => (
<MenuItem
key={action.id}
density="sm"
glyph={action.glyph}
label={action.label}
danger={action.danger === true}
onSelect={fromMenu(action)}
/>
))}
</Dropdown>
</div>
</li>
);
}