Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(web): one detail header layout that folds its actions instead of wrapping (#18746)

Der Gerät0659e55045dc
diff --git a/web/src/components/HeaderActionButton.tsx b/web/src/components/HeaderActionButton.tsx
index c5646fa431..90181e243b 100644
--- a/web/src/components/HeaderActionButton.tsx
+++ b/web/src/components/HeaderActionButton.tsx
@@ -2,6 +2,7 @@ import * as React from "react";
import { type KeyboardKey } from "@/src/components/design-system/KeyboardShortcut/KeyboardShortcut";
import { Tooltip } from "@/src/components/design-system/Tooltip/Tooltip";
+import { ActionButtonCountBadge } from "@/src/components/ui/ActionButtonCountBadge";
import { Button, type ButtonProps } from "@/src/components/ui/button";
import { cn } from "@/src/utils/tailwind";
@@ -13,13 +14,15 @@ type HeaderActionButtonProps = Omit<
icon: React.ReactNode;
shortcut?: KeyboardKey;
active?: boolean;
+ /** Count shown on the button, the same badge the labelled action uses. */
+ count?: number;
};
export const HeaderActionButton = React.forwardRef<
HTMLButtonElement,
HeaderActionButtonProps
>(function HeaderActionButton(
- { label, icon, shortcut, active = false, ...props },
+ { label, icon, shortcut, active = false, count, ...props },
ref,
) {
return (
@@ -34,12 +37,20 @@ export const HeaderActionButton = React.forwardRef<
size="icon"
aria-label={label}
className={cn(
- "text-foreground-secondary hover:text-foreground-secondary h-7 w-7",
+ "text-foreground-secondary hover:text-foreground-secondary relative h-7 w-7 overflow-visible",
active && "bg-accent/60 ring-primary/20 ring-2",
)}
{...props}
>
{icon}
+ {count != null && count > 0 ? (
+ <span
+ aria-hidden
+ className="pointer-events-none absolute top-0 right-0 origin-top-right scale-75"
+ >
+ <ActionButtonCountBadge count={count} />
+ </span>
+ ) : null}
</Button>
)}
</Tooltip>
diff --git a/web/src/features/traces/components/DetailViewHeaderShell.tsx b/web/src/features/traces/components/DetailViewHeaderShell.tsx
index 49cf95e303..5bbaed4871 100644
--- a/web/src/features/traces/components/DetailViewHeaderShell.tsx
+++ b/web/src/features/traces/components/DetailViewHeaderShell.tsx
@@ -2,9 +2,5 @@ import { type ReactNode } from "react";
/** Padded container shared by the trace, observation and prompt detail headers. */
export function DetailViewHeaderShell({ children }: { children: ReactNode }) {
- return (
- <div className="@container shrink-0 space-y-1.5 px-4 pt-3 pb-2">
- {children}
- </div>
- );
+ return <div className="shrink-0 space-y-1.5 px-4 pt-3 pb-2">{children}</div>;
}
diff --git a/web/src/features/traces/components/DetailViewHeaderTitleRow.tsx b/web/src/features/traces/components/DetailViewHeaderTitleRow.tsx
new file mode 100644
index 0000000000..840271c6f3
--- /dev/null
+++ b/web/src/features/traces/components/DetailViewHeaderTitleRow.tsx
@@ -0,0 +1,278 @@
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { cn } from "@/src/utils/tailwind";
+import { useElementSize } from "@/src/hooks/useElementSize";
+import {
+ planDetailViewHeaderActions,
+ type DetailViewHeaderActionsPlacement,
+} from "@/src/features/traces/components/detailViewHeaderLayout";
+
+// Tuned by eye: the width the title keeps before the actions move off its row,
+// and the `gap-2` between the two while they share one.
+const MIN_TITLE_PX = 160;
+const TITLE_ACTIONS_GAP_PX = 8;
+
+const FOCUSABLE_SELECTOR =
+ 'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])';
+
+type DetailViewHeaderFocusFollow =
+ | { to: "menu" }
+ | { to: "cluster"; index: number };
+
+function focusableElements(root: ParentNode): HTMLElement[] {
+ return [...root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)];
+}
+
+function indexOfFocusable(root: HTMLElement, active: Element): number {
+ return focusableElements(root).findIndex(
+ (element) => element === active || element.contains(active),
+ );
+}
+
+/**
+ * Where keyboard focus should go when the row is about to hide the cluster
+ * that holds it. Folding unmounts both clusters; switching between the
+ * labelled and icon-only clusters hides one in place. Either way the focused
+ * button becomes unfocusable and the browser drops focus to `document.body`.
+ */
+function detailViewHeaderFocusFollow({
+ next,
+ placement,
+ active,
+ labelledCluster,
+ iconOnlyCluster,
+}: {
+ next: DetailViewHeaderActionsPlacement;
+ placement: DetailViewHeaderActionsPlacement;
+ active: Element | null;
+ labelledCluster: HTMLElement | null;
+ iconOnlyCluster: HTMLElement | null;
+}): DetailViewHeaderFocusFollow | null {
+ if (!active) return null;
+
+ if (next === "folded" && placement !== "folded") {
+ const inCluster =
+ (labelledCluster?.contains(active) ?? false) ||
+ (iconOnlyCluster?.contains(active) ?? false);
+ return inCluster ? { to: "menu" } : null;
+ }
+
+ if (
+ next === "icon-only" &&
+ placement !== "icon-only" &&
+ labelledCluster?.contains(active)
+ ) {
+ const index = indexOfFocusable(labelledCluster, active);
+ return index >= 0 ? { to: "cluster", index } : null;
+ }
+
+ if (
+ next !== "icon-only" &&
+ next !== "folded" &&
+ placement === "icon-only" &&
+ iconOnlyCluster?.contains(active)
+ ) {
+ const index = indexOfFocusable(iconOnlyCluster, active);
+ return index >= 0 ? { to: "cluster", index } : null;
+ }
+
+ return null;
+}
+
+export type DetailViewHeaderTitleRowProps = {
+ /** The entity title. */
+ title: ReactNode;
+ /** Sits beside the title while the actions have a place of their own. */
+ options: ReactNode;
+ /** Takes the place of `options` once the actions fold, and holds them. */
+ foldedActions: ReactNode;
+ /**
+ * The inline action cluster (full labels). Mounted only while it is not
+ * folded, so it holds triggers only: a dialog or drawer an action opens is
+ * owned above the row, where folding cannot unmount it.
+ */
+ actions: ReactNode;
+ /**
+ * Icon-only variant of the action cluster (icons with tooltips, no labels).
+ * When provided the planner inserts an intermediate `"icon-only"` step
+ * between `"below"` and `"folded"`, so the header degrades progressively:
+ * full labels → icon-only → ellipsis menu.
+ */
+ iconOnlyActions?: ReactNode;
+ /**
+ * Changes whenever the cluster's content changes width — a comment count, a
+ * hidden Annotate, a different entity. A folded cluster is unmounted and so
+ * cannot be measured, so this is the only way the row learns that a narrower
+ * cluster now deserves a second look.
+ */
+ actionsKey: string;
+ /** Fold whatever the width — the handheld presentation. */
+ alwaysFold: boolean;
+};
+
+/**
+ * Title row shared by the trace and observation detail headers: the entity
+ * title, and the action cluster placed from the header's own measured width —
+ * beside the title, below it, icon-only, or folded into the title row's
+ * overflow menu.
+ *
+ * See {@link planDetailViewHeaderActions}. The cluster never wraps, so a
+ * trailing button can never end up on a row of its own.
+ */
+export function DetailViewHeaderTitleRow({
+ title,
+ options,
+ foldedActions,
+ actions,
+ iconOnlyActions,
+ actionsKey,
+ alwaysFold,
+}: DetailViewHeaderTitleRowProps) {
+ // The row's width is the pane's, so a resize of either re-renders and replans.
+ const [rowRef, rowSize] = useElementSize<HTMLDivElement>();
+ const actionsRef = useRef<HTMLDivElement>(null);
+ const iconOnlyActionsRef = useRef<HTMLDivElement>(null);
+ // A folded cluster has no element to measure, so its last natural width is
+ // kept here and goes on feeding the planner until it is back on screen.
+ const actionsWidthRef = useRef<number | undefined>(undefined);
+ const iconOnlyActionsWidthRef = useRef<number | undefined>(undefined);
+ const followFocusRef = useRef<DetailViewHeaderFocusFollow | null>(null);
+ const [placement, setPlacement] =
+ useState<DetailViewHeaderActionsPlacement>("beside");
+
+ // New content, so the cached width is about the old content: show the cluster
+ // again, which both re-mounts it for measurement and settles on the right
+ // placement in the same pre-paint pass.
+ const [measuredKey, setMeasuredKey] = useState(actionsKey);
+ if (measuredKey !== actionsKey) {
+ setMeasuredKey(actionsKey);
+ actionsWidthRef.current = undefined;
+ iconOnlyActionsWidthRef.current = undefined;
+ setPlacement("beside");
+ }
+
+ // Measure and plan before paint: `useElementSize`'s state lands after it,
+ // which would show the un-adapted header for a frame. `actions` is a
+ // dependency because the cluster's width is its content — a comment count
+ // arriving or annotation mode hiding Annotate changes it with no resize.
+ useLayoutEffect(() => {
+ if (alwaysFold) return;
+ if (placement !== "folded") {
+ if (actionsRef.current) {
+ actionsWidthRef.current = actionsRef.current.offsetWidth;
+ }
+ if (iconOnlyActionsRef.current) {
+ iconOnlyActionsWidthRef.current =
+ iconOnlyActionsRef.current.offsetWidth;
+ }
+ }
+ const headerWidth =
+ rowRef.current?.getBoundingClientRect().width ?? rowSize?.width;
+ const actionsWidth = actionsWidthRef.current;
+ if (!headerWidth || !actionsWidth) return;
+
+ const next = planDetailViewHeaderActions({
+ headerWidth,
+ actionsWidth,
+ iconOnlyActionsWidth: iconOnlyActionsWidthRef.current,
+ minTitleWidth: MIN_TITLE_PX,
+ gap: TITLE_ACTIONS_GAP_PX,
+ });
+ // Record the target while the focused button is still connected. The
+ // placement commit hides it, and the effect below moves focus once the
+ // visible control exists.
+ if (next !== placement) {
+ followFocusRef.current = detailViewHeaderFocusFollow({
+ next,
+ placement,
+ active: document.activeElement,
+ labelledCluster: actionsRef.current,
+ iconOnlyCluster: iconOnlyActionsRef.current,
+ });
+ }
+ setPlacement((previous) => (previous === next ? previous : next));
+ }, [actions, iconOnlyActions, alwaysFold, placement, rowRef, rowSize?.width]);
+
+ useLayoutEffect(() => {
+ const follow = followFocusRef.current;
+ if (!follow) return;
+ followFocusRef.current = null;
+
+ if (follow.to === "menu") {
+ // The folded presentation ends in the overflow-menu trigger, so the
+ // row's last focusable element is it.
+ const focusable = rowRef.current ? focusableElements(rowRef.current) : [];
+ focusable[focusable.length - 1]?.focus({ preventScroll: true });
+ return;
+ }
+
+ const cluster =
+ placement === "icon-only"
+ ? iconOnlyActionsRef.current
+ : actionsRef.current;
+ if (!cluster) return;
+ const focusable = focusableElements(cluster);
+ (focusable[follow.index] ?? focusable[focusable.length - 1])?.focus({
+ preventScroll: true,
+ });
+ }, [placement, rowRef]);
+
+ const actionsFolded = alwaysFold || placement === "folded";
+ const actionsBeside = !actionsFolded && placement === "beside";
+ const actionsIconOnly = !actionsFolded && placement === "icon-only";
+
+ return (
+ <div
+ ref={rowRef}
+ className={cn(
+ "grid w-full items-center gap-2",
+ actionsBeside ? "grid-cols-[minmax(0,1fr)_auto]" : "grid-cols-1",
+ )}
+ >
+ {/* `min-h-7` is the height of the icon buttons that sit in this row, so a
+ header keeps its height while it is still loading skeletons. */}
+ <div className="flex min-h-7 w-full min-w-0 flex-row items-center gap-2">
+ {title}
+ {actionsFolded ? foldedActions : options}
+ </div>
+ {!actionsFolded && (
+ <div
+ className={cn(
+ "relative flex items-center",
+ actionsBeside ? "justify-end" : "justify-start",
+ )}
+ >
+ {/* Full-label cluster — shrink-to-fit and never wrapping, so
+ `offsetWidth` above is the cluster's natural width whichever row
+ it is on. Hidden (but still in the DOM for measurement) while the
+ icon-only cluster is active. */}
+ <div
+ ref={actionsRef}
+ className={cn(
+ "flex shrink-0 flex-nowrap items-center gap-1",
+ actionsIconOnly && "invisible absolute",
+ )}
+ aria-hidden={actionsIconOnly || undefined}
+ >
+ {actions}
+ </div>
+ {/* Icon-only cluster — shown instead of the full cluster once the
+ header is too narrow for labeled buttons but wide enough for icons.
+ Hidden (but still in the DOM for measurement) while the full
+ cluster is active. */}
+ {iconOnlyActions != null && (
+ <div
+ ref={iconOnlyActionsRef}
+ className={cn(
+ "flex shrink-0 flex-nowrap items-center gap-1",
+ !actionsIconOnly && "invisible absolute",
+ )}
+ aria-hidden={!actionsIconOnly || undefined}
+ >
+ {iconOnlyActions}
+ </div>
+ )}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx b/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx
index 599330dd53..8a8634fdc6 100644
--- a/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx
+++ b/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx
@@ -23,6 +23,7 @@ import {
import { type ObservationReturnTypeWithMetadata } from "@/src/server/api/routers/traces";
import { EntityTitle } from "@/src/components/EntityTitle";
import { DetailViewHeaderShell } from "@/src/features/traces/components/DetailViewHeaderShell";
+import { DetailViewHeaderTitleRow } from "@/src/features/traces/components/DetailViewHeaderTitleRow";
import { AnnotateDrawerController } from "@/src/features/scores/components/AnnotateDrawerController";
import { ConnectedTraceObservationAddToDropdownMenuController } from "@/src/features/traces/components/ConnectedTraceObservationAddToDropdownMenuController";
import { Badge } from "@/src/components/design-system/Badge/Badge";
@@ -221,269 +222,326 @@ export const ObservationDetailViewHeader = memo(
return (
<DetailViewHeaderShell>
- {/* Title row with actions */}
- <div className="grid w-full grid-cols-1 items-center gap-2 @md:grid-cols-[minmax(0,1fr)_auto]">
- <div className="flex w-full min-w-0 flex-row items-center gap-2">
- <EntityTitle
- as="span"
- type={observation.type as ObservationType}
- title={observation.name || observation.id}
- level={observation.level}
- />
- {isMobile && (
- <ConnectedTraceObservationAddToDropdownMenuController
- analyticsData={{ source: "TraceDetail", isV4: isV4Enabled }}
- projectId={projectId}
- traceId={traceId}
- variant="observation"
- observationId={observation.id}
- input={observationWithIO?.input ?? null}
- output={observationWithIO?.output ?? null}
- metadata={observationWithIO?.metadata ?? null}
- generation={
- observationWithIO && isGenerationLike(observationWithIO.type)
- ? observationWithIO
- : undefined
- }
- renderMenu={(addToItems) => (
- <AnnotateDrawerController projectId={projectId}>
- {({ disabled: annotationDisabled, openDrawer }) => (
- <ConnectedDetailHeaderActionsMenuController
- idItems={[
- { id: traceId, name: "Trace ID" },
- { id: observation.id, name: "Observation ID" },
- ]}
- observationType={observation.type}
- projectId={projectId}
- observation={
- isV4Enabled
- ? {
- id: observation.id,
- traceId,
- startTime: observation.startTime,
- }
- : undefined
- }
- spanName={observation.name ?? ""}
- webCallout={{
- traceId,
- observationId: observation.id,
- sessionId: observation.sessionId ?? null,
- }}
- renderMenu={(utilityItems) => (
- <DropdownMenu
- placement="bottom-end"
- maxHeight="min(24rem, calc(100dvh - 2rem))"
- items={[
- ...(!isAnnotationMode
- ? [
- {
- type: "item" as const,
- id: "annotate",
- title: "Annotate",
- icon: annotationDisabled
- ? LockIcon
- : SquarePen,
- disabled: annotationDisabled
- ? {
- reason:
- "You don't have permission to annotate.",
- }
- : undefined,
- onClick: () => {
- mobileActionsTriggerRef.current?.focus({
- preventScroll: true,
- });
- openDrawer({
- ...prepareTraceAnnotation({
- traceId,
- projectId,
- environment:
- observation.environment,
- observationId: observation.id,
- scores: observationScores,
- isV4: isV4Enabled,
- }),
- companionTrace,
- });
- },
- },
- ]
- : []),
- {
- type: "item",
- id: "comments",
- title: mobileCommentActionLabel,
- icon: commentDrawerControl.disabled
- ? MessageSquareOff
- : MessageSquare,
- disabled: commentDrawerControl.disabled
- ? {
- reason:
- "You don't have permission to comment.",
- }
- : undefined,
- onClick: () => {
- mobileActionsTriggerRef.current?.focus({
- preventScroll: true,
- });
- commentDrawerControl.openDrawer();
- },
- },
- ...(observationWithIO
- ? [
- {
- type: "submenu" as const,
- id: "add-to",
- title: "Add to",
- icon: PlusIcon,
- items: addToItems,
+ <ConnectedTraceObservationAddToDropdownMenuController
+ key={observation.id}
+ analyticsData={{ source: "TraceDetail", isV4: isV4Enabled }}
+ projectId={projectId}
+ traceId={traceId}
+ variant="observation"
+ observationId={observation.id}
+ input={observationWithIO?.input ?? null}
+ output={observationWithIO?.output ?? null}
+ metadata={observationWithIO?.metadata ?? null}
+ generation={
+ observationWithIO && isGenerationLike(observationWithIO.type)
+ ? observationWithIO
+ : undefined
+ }
+ renderMenu={(addToItems) => (
+ <AnnotateDrawerController projectId={projectId}>
+ {({ disabled: annotationDisabled, openDrawer }) => (
+ <DetailViewHeaderTitleRow
+ alwaysFold={isMobile}
+ actionsKey={`${observation.id}|${commentCount ?? 0}|${commentDrawerControl.disabled}|${isAnnotationMode}|${Boolean(observationWithIO)}`}
+ title={
+ <EntityTitle
+ as="span"
+ type={observation.type as ObservationType}
+ title={observation.name || observation.id}
+ level={observation.level}
+ />
+ }
+ options={
+ <ConnectedDetailHeaderActionsMenuController
+ idItems={[
+ { id: traceId, name: "Trace ID" },
+ { id: observation.id, name: "Observation ID" },
+ ]}
+ observationType={observation.type}
+ projectId={projectId}
+ observation={
+ isV4Enabled
+ ? {
+ id: observation.id,
+ traceId,
+ startTime: observation.startTime,
+ }
+ : undefined
+ }
+ spanName={observation.name ?? ""}
+ webCallout={{
+ traceId,
+ observationId: observation.id,
+ sessionId: observation.sessionId ?? null,
+ }}
+ >
+ {({ getTriggerProps }) => (
+ <HeaderActionButton
+ label="Options"
+ icon={
+ <EllipsisVertical size="base" color="default" />
+ }
+ {...getTriggerProps()}
+ />
+ )}
+ </ConnectedDetailHeaderActionsMenuController>
+ }
+ foldedActions={
+ <ConnectedDetailHeaderActionsMenuController
+ idItems={[
+ { id: traceId, name: "Trace ID" },
+ { id: observation.id, name: "Observation ID" },
+ ]}
+ observationType={observation.type}
+ projectId={projectId}
+ observation={
+ isV4Enabled
+ ? {
+ id: observation.id,
+ traceId,
+ startTime: observation.startTime,
+ }
+ : undefined
+ }
+ spanName={observation.name ?? ""}
+ webCallout={{
+ traceId,
+ observationId: observation.id,
+ sessionId: observation.sessionId ?? null,
+ }}
+ renderMenu={(utilityItems) => (
+ <DropdownMenu
+ placement="bottom-end"
+ maxHeight="min(24rem, calc(100dvh - 2rem))"
+ items={[
+ ...(!isAnnotationMode
+ ? [
+ {
+ type: "item" as const,
+ id: "annotate",
+ title: "Annotate",
+ icon: annotationDisabled
+ ? LockIcon
+ : SquarePen,
+ disabled: annotationDisabled
+ ? {
+ reason:
+ "You don't have permission to annotate.",
+ }
+ : undefined,
+ onClick: () => {
+ mobileActionsTriggerRef.current?.focus({
+ preventScroll: true,
+ });
+ openDrawer({
+ ...prepareTraceAnnotation({
+ traceId,
+ projectId,
+ environment: observation.environment,
+ observationId: observation.id,
+ scores: observationScores,
+ isV4: isV4Enabled,
+ }),
+ companionTrace,
+ });
},
- ]
- : []),
- {
- id: "review-actions-separator",
- type: "separator",
+ },
+ ]
+ : []),
+ {
+ type: "item",
+ id: "comments",
+ title: mobileCommentActionLabel,
+ icon: commentDrawerControl.disabled
+ ? MessageSquareOff
+ : MessageSquare,
+ disabled: commentDrawerControl.disabled
+ ? {
+ reason:
+ "You don't have permission to comment.",
+ }
+ : undefined,
+ onClick: () => {
+ mobileActionsTriggerRef.current?.focus({
+ preventScroll: true,
+ });
+ commentDrawerControl.openDrawer();
},
- ...utilityItems,
- ]}
- >
- {({ getTriggerProps }) => (
- <Button
- variant="outline"
- size="icon"
- aria-label="More actions"
- className="ml-auto shrink-0"
- {...getTriggerProps({
- ref: mobileActionsTriggerRef,
- })}
- >
- <EllipsisVertical size="base" color="default" />
- </Button>
- )}
- </DropdownMenu>
- )}
- />
- )}
- </AnnotateDrawerController>
- )}
- />
- )}
- </div>
- {/* Action buttons (desktop inline cluster) */}
- {!isMobile && (
- <div className="flex flex-wrap content-start items-center justify-start gap-1 @md:justify-end">
- {observationWithIO ? (
- <ConnectedTraceObservationAddToDropdownMenuController
- analyticsData={{ source: "TraceDetail", isV4: isV4Enabled }}
- projectId={projectId}
- key={observation.id}
- traceId={traceId}
- variant="observation"
- observationId={observation.id}
- input={observationWithIO.input}
- output={observationWithIO.output}
- metadata={observationWithIO.metadata}
- generation={
- isGenerationLike(observationWithIO.type)
- ? observationWithIO
- : undefined
+ },
+ ...(observationWithIO
+ ? [
+ {
+ type: "submenu" as const,
+ id: "add-to",
+ title: "Add to",
+ icon: PlusIcon,
+ items: addToItems,
+ },
+ ]
+ : []),
+ {
+ id: "review-actions-separator",
+ type: "separator",
+ },
+ ...utilityItems,
+ ]}
+ >
+ {({ getTriggerProps }) => (
+ <Button
+ variant="outline"
+ size="icon"
+ aria-label="More actions"
+ className="ml-auto shrink-0"
+ {...getTriggerProps({
+ ref: mobileActionsTriggerRef,
+ })}
+ >
+ <EllipsisVertical size="base" color="default" />
+ </Button>
+ )}
+ </DropdownMenu>
+ )}
+ />
}
- >
- {({ getTriggerProps }) =>
- renderAddToButton(getTriggerProps())
+ actions={
+ <>
+ {observationWithIO ? (
+ <DropdownMenu
+ items={addToItems}
+ maxHeight="24rem"
+ placement="bottom-start"
+ >
+ {({ getTriggerProps }) =>
+ renderAddToButton(getTriggerProps())
+ }
+ </DropdownMenu>
+ ) : (
+ renderAddToButton({ disabled: true })
+ )}
+ {/* Hide annotation buttons in annotation mode (panel shown separately) */}
+ {!isAnnotationMode && (
+ <Button
+ variant="ghost"
+ size="sm"
+ className={headerActionClassName}
+ disabled={annotationDisabled}
+ onClick={() =>
+ openDrawer({
+ ...prepareTraceAnnotation({
+ traceId,
+ projectId,
+ environment: observation.environment,
+ observationId: observation.id,
+ scores: observationScores,
+ isV4: isV4Enabled,
+ }),
+ companionTrace,
+ })
+ }
+ >
+ {annotationDisabled ? (
+ <LockIcon size="base" color="default" />
+ ) : (
+ <SquarePen size="base" color="default" />
+ )}
+ <span>Annotate</span>
+ </Button>
+ )}
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ disabled={commentDrawerControl.disabled}
+ onClick={commentDrawerControl.openDrawer}
+ className={headerActionClassName}
+ >
+ {commentDrawerControl.disabled ? (
+ <MessageSquareOff size="base" color="muted" />
+ ) : (
+ <>
+ <MessageSquare size="base" color="default" />
+ <span>{commentActionLabel}</span>
+ {!!commentCount ? (
+ <ActionButtonCountBadge count={commentCount} />
+ ) : null}
+ </>
+ )}
+ </Button>
+ </>
}
- </ConnectedTraceObservationAddToDropdownMenuController>
- ) : (
- renderAddToButton({ disabled: true })
- )}
- {/* Hide annotation buttons in annotation mode (panel shown separately) */}
- {!isAnnotationMode && (
- <AnnotateDrawerController projectId={projectId}>
- {({ disabled, openDrawer }) => (
- <Button
- variant="ghost"
- size="sm"
- className={headerActionClassName}
- disabled={disabled}
- onClick={() =>
- openDrawer({
- ...prepareTraceAnnotation({
- traceId,
- projectId,
- environment: observation.environment,
- observationId: observation.id,
- scores: observationScores,
- isV4: isV4Enabled,
- }),
- companionTrace,
- })
- }
- >
- {disabled ? (
- <LockIcon size="base" color="default" />
+ iconOnlyActions={
+ <>
+ {observationWithIO ? (
+ <DropdownMenu
+ items={addToItems}
+ maxHeight="24rem"
+ placement="bottom-start"
+ >
+ {({ getTriggerProps }) => (
+ <HeaderActionButton
+ label="Add to"
+ icon={<PlusIcon size="base" />}
+ {...getTriggerProps()}
+ />
+ )}
+ </DropdownMenu>
) : (
- <SquarePen size="base" color="default" />
+ <HeaderActionButton
+ label="Add to"
+ icon={<PlusIcon size="base" />}
+ disabled
+ />
+ )}
+ {!isAnnotationMode && (
+ <HeaderActionButton
+ label="Annotate"
+ icon={
+ annotationDisabled ? (
+ <LockIcon size="base" />
+ ) : (
+ <SquarePen size="base" />
+ )
+ }
+ disabled={annotationDisabled}
+ onClick={() =>
+ openDrawer({
+ ...prepareTraceAnnotation({
+ traceId,
+ projectId,
+ environment: observation.environment,
+ observationId: observation.id,
+ scores: observationScores,
+ isV4: isV4Enabled,
+ }),
+ companionTrace,
+ })
+ }
+ />
)}
- <span>Annotate</span>
- </Button>
- )}
- </AnnotateDrawerController>
+ <HeaderActionButton
+ label={mobileCommentActionLabel}
+ count={
+ commentDrawerControl.disabled
+ ? undefined
+ : commentCount
+ }
+ icon={
+ commentDrawerControl.disabled ? (
+ <MessageSquareOff size="base" />
+ ) : (
+ <MessageSquare size="base" />
+ )
+ }
+ disabled={commentDrawerControl.disabled}
+ onClick={commentDrawerControl.openDrawer}
+ />
+ </>
+ }
+ />
)}
- <Button
- type="button"
- variant="ghost"
- size="sm"
- disabled={commentDrawerControl.disabled}
- onClick={commentDrawerControl.openDrawer}
- className={headerActionClassName}
- >
- {commentDrawerControl.disabled ? (
- <MessageSquareOff size="base" color="muted" />
- ) : (
- <>
- <MessageSquare size="base" color="default" />
- <span>{commentActionLabel}</span>
- {!!commentCount ? (
- <ActionButtonCountBadge count={commentCount} />
- ) : null}
- </>
- )}
- </Button>
- <ConnectedDetailHeaderActionsMenuController
- idItems={[
- { id: traceId, name: "Trace ID" },
- { id: observation.id, name: "Observation ID" },
- ]}
- observationType={observation.type}
- projectId={projectId}
- observation={
- isV4Enabled
- ? {
- id: observation.id,
- traceId,
- startTime: observation.startTime,
- }
- : undefined
- }
- spanName={observation.name ?? ""}
- webCallout={{
- traceId,
- observationId: observation.id,
- sessionId: observation.sessionId ?? null,
- }}
- >
- {({ getTriggerProps }) => (
- <HeaderActionButton
- label="Options"
- icon={<EllipsisVertical size="base" color="default" />}
- {...getTriggerProps()}
- />
- )}
- </ConnectedDetailHeaderActionsMenuController>
- </div>
+ </AnnotateDrawerController>
)}
- </div>
+ />
{/* Metadata line */}
{isAnnotationMode ? (
diff --git a/web/src/features/traces/components/TraceDetailView/components/TraceDetailViewHeader.tsx b/web/src/features/traces/components/TraceDetailView/components/TraceDetailViewHeader.tsx
index 047d7f383a..61eb0030d9 100644
--- a/web/src/features/traces/components/TraceDetailView/components/TraceDetailViewHeader.tsx
+++ b/web/src/features/traces/components/TraceDetailView/components/TraceDetailViewHeader.tsx
@@ -23,6 +23,7 @@ import {
import { type WithStringifiedMetadata } from "@/src/utils/clientSideDomainTypes";
import { EntityTitle } from "@/src/components/EntityTitle";
import { DetailViewHeaderShell } from "@/src/features/traces/components/DetailViewHeaderShell";
+import { DetailViewHeaderTitleRow } from "@/src/features/traces/components/DetailViewHeaderTitleRow";
import { Badge, BadgeShell } from "@/src/components/design-system/Badge/Badge";
import { Skeleton } from "@/src/components/ui/skeleton";
import { cn } from "@/src/utils/tailwind";
@@ -70,12 +71,6 @@ export interface TraceDetailViewHeaderProps {
};
}
-const titleRowClassName =
- "grid w-full grid-cols-1 items-center gap-2 @md:grid-cols-[minmax(0,1fr)_auto]";
-const titleClassName = "flex w-full min-w-0 flex-row items-center gap-2";
-const actionsClassName =
- "flex flex-wrap content-start items-center justify-start gap-1 @md:justify-end";
-
const LOADING_BADGE_WIDTHS = ["w-36", "w-24", "w-32", "w-32"];
export const TraceDetailViewHeader = memo(function TraceDetailViewHeader(
@@ -89,20 +84,27 @@ function TraceDetailViewHeaderLoading() {
const isMobile = useIsMobile();
return (
<DetailViewHeaderShell>
- <div className={titleRowClassName}>
- <div className={cn(titleClassName, "min-h-7")}>
- <Skeleton className="size-6 rounded-sm" />
- <Skeleton className="h-4 w-48" />
- {isMobile && <Skeleton className="ml-auto size-8 rounded-md" />}
- </div>
- {!isMobile && (
- <div className={actionsClassName}>
- <Skeleton className="h-6 w-20 rounded-md" />
+ <DetailViewHeaderTitleRow
+ alwaysFold={isMobile}
+ title={
+ <>
+ <Skeleton className="size-6 rounded-sm" />
+ <Skeleton className="h-4 w-48" />
+ </>
+ }
+ options={null}
+ foldedActions={<Skeleton className="ml-auto size-8 rounded-md" />}
+ actionsKey="loading"
+ actions={
+ // Sized to the loaded cluster (Add to · Annotate · Comment), so the
+ // header does not change its row count when the data lands.
+ <>
<Skeleton className="h-6 w-24 rounded-md" />
+ <Skeleton className="h-6 w-28 rounded-md" />
<Skeleton className="h-6 w-24 rounded-md" />
- </div>
- )}
- </div>
+ </>
+ }
+ />
<div className="flex flex-col gap-2">
<CollapsibleBadgeRow>
{LOADING_BADGE_WIDTHS.map((width, index) => (
@@ -154,219 +156,271 @@ function LoadedTraceDetailViewHeader({
return (
<DetailViewHeaderShell>
- {/* Title row with actions */}
- <div className={titleRowClassName}>
- <div className={titleClassName}>
- <EntityTitle as="span" type="TRACE" title={trace.name || trace.id} />
- {!isMobile && (
- <ConnectedDetailHeaderActionsMenuController
- idItems={[{ id: trace.id, name: "Trace ID" }]}
- projectId={projectId}
- webCallout={{
- traceId: trace.id,
- sessionId: trace.sessionId ?? null,
- }}
- >
- {({ getTriggerProps }) => (
- <HeaderActionButton
- label="Options"
- icon={<EllipsisVertical size="base" color="default" />}
- {...getTriggerProps()}
- />
- )}
- </ConnectedDetailHeaderActionsMenuController>
- )}
- {isMobile && (
- <ConnectedTraceObservationAddToDropdownMenuController
- analyticsData={{ source: "TraceDetail", isV4 }}
- projectId={projectId}
- traceId={trace.id}
- variant="trace"
- input={trace.input}
- output={trace.output}
- metadata={trace.metadata}
- renderMenu={(addToItems) => (
- <AnnotateDrawerController projectId={projectId}>
- {({ disabled: annotationDisabled, openDrawer }) => (
- <ConnectedDetailHeaderActionsMenuController
- idItems={[{ id: trace.id, name: "Trace ID" }]}
- projectId={projectId}
- webCallout={{
- traceId: trace.id,
- sessionId: trace.sessionId ?? null,
- }}
- renderMenu={(utilityItems) => (
- <DropdownMenu
- placement="bottom-end"
- maxHeight="min(24rem, calc(100dvh - 2rem))"
- items={[
- ...(!isAnnotationMode
- ? [
- {
- type: "item" as const,
- id: "annotate",
- title: "Annotate",
- icon: annotationDisabled
- ? LockIcon
- : SquarePen,
- disabled: annotationDisabled
- ? {
- reason:
- "You don't have permission to annotate.",
- }
- : undefined,
- onClick: () => {
- mobileActionsTriggerRef.current?.focus({
- preventScroll: true,
- });
- openDrawer(
- prepareTraceAnnotation({
- traceId: trace.id,
- projectId,
- environment: trace.environment,
- scores: traceScores,
- isV4,
- }),
- );
- },
+ <ConnectedTraceObservationAddToDropdownMenuController
+ analyticsData={{ source: "TraceDetail", isV4 }}
+ projectId={projectId}
+ traceId={trace.id}
+ variant="trace"
+ input={trace.input}
+ output={trace.output}
+ metadata={trace.metadata}
+ renderMenu={(addToItems) => (
+ <AnnotateDrawerController projectId={projectId}>
+ {({ disabled: annotationDisabled, openDrawer }) => (
+ <DetailViewHeaderTitleRow
+ alwaysFold={isMobile}
+ actionsKey={`${trace.id}|${commentCount ?? 0}|${commentDrawerControl.disabled}|${isAnnotationMode}`}
+ title={
+ <EntityTitle
+ as="span"
+ type="TRACE"
+ title={trace.name || trace.id}
+ />
+ }
+ options={
+ <ConnectedDetailHeaderActionsMenuController
+ idItems={[{ id: trace.id, name: "Trace ID" }]}
+ projectId={projectId}
+ webCallout={{
+ traceId: trace.id,
+ sessionId: trace.sessionId ?? null,
+ }}
+ >
+ {({ getTriggerProps }) => (
+ <HeaderActionButton
+ label="Options"
+ icon={<EllipsisVertical size="base" color="default" />}
+ {...getTriggerProps()}
+ />
+ )}
+ </ConnectedDetailHeaderActionsMenuController>
+ }
+ foldedActions={
+ <ConnectedDetailHeaderActionsMenuController
+ idItems={[{ id: trace.id, name: "Trace ID" }]}
+ projectId={projectId}
+ webCallout={{
+ traceId: trace.id,
+ sessionId: trace.sessionId ?? null,
+ }}
+ renderMenu={(utilityItems) => (
+ <DropdownMenu
+ placement="bottom-end"
+ maxHeight="min(24rem, calc(100dvh - 2rem))"
+ items={[
+ ...(!isAnnotationMode
+ ? [
+ {
+ type: "item" as const,
+ id: "annotate",
+ title: "Annotate",
+ icon: annotationDisabled
+ ? LockIcon
+ : SquarePen,
+ disabled: annotationDisabled
+ ? {
+ reason:
+ "You don't have permission to annotate.",
+ }
+ : undefined,
+ onClick: () => {
+ mobileActionsTriggerRef.current?.focus({
+ preventScroll: true,
+ });
+ openDrawer(
+ prepareTraceAnnotation({
+ traceId: trace.id,
+ projectId,
+ environment: trace.environment,
+ scores: traceScores,
+ isV4,
+ }),
+ );
},
- ]
- : []),
- {
- type: "item",
- id: "comments",
- title: mobileCommentActionLabel,
- icon: commentDrawerControl.disabled
- ? MessageSquareOff
- : MessageSquare,
- disabled: commentDrawerControl.disabled
- ? {
- reason:
- "You don't have permission to comment.",
- }
- : undefined,
- onClick: () => {
- mobileActionsTriggerRef.current?.focus({
- preventScroll: true,
- });
- commentDrawerControl.openDrawer();
- },
- },
- {
- type: "submenu" as const,
- id: "add-to",
- title: "Add to",
- icon: PlusIcon,
- items: addToItems,
+ },
+ ]
+ : []),
+ {
+ type: "item",
+ id: "comments",
+ title: mobileCommentActionLabel,
+ icon: commentDrawerControl.disabled
+ ? MessageSquareOff
+ : MessageSquare,
+ disabled: commentDrawerControl.disabled
+ ? {
+ reason:
+ "You don't have permission to comment.",
+ }
+ : undefined,
+ onClick: () => {
+ mobileActionsTriggerRef.current?.focus({
+ preventScroll: true,
+ });
+ commentDrawerControl.openDrawer();
},
- {
- id: "review-actions-separator",
- type: "separator",
- },
- ...utilityItems,
- ]}
+ },
+ {
+ type: "submenu" as const,
+ id: "add-to",
+ title: "Add to",
+ icon: PlusIcon,
+ items: addToItems,
+ },
+ {
+ id: "review-actions-separator",
+ type: "separator",
+ },
+ ...utilityItems,
+ ]}
+ >
+ {({ getTriggerProps }) => (
+ <Button
+ variant="outline"
+ size="icon"
+ aria-label="More actions"
+ className="ml-auto shrink-0"
+ {...getTriggerProps({
+ ref: mobileActionsTriggerRef,
+ })}
+ >
+ <EllipsisVertical size="base" color="default" />
+ </Button>
+ )}
+ </DropdownMenu>
+ )}
+ />
+ }
+ actions={
+ <>
+ <DropdownMenu
+ items={addToItems}
+ maxHeight="24rem"
+ placement="bottom-start"
+ >
+ {({ getTriggerProps }) => (
+ <Button
+ variant="ghost"
+ size="sm"
+ className={headerActionClassName}
+ {...getTriggerProps()}
>
- {({ getTriggerProps }) => (
- <Button
- variant="outline"
- size="icon"
- aria-label="More actions"
- className="ml-auto shrink-0"
- {...getTriggerProps({
- ref: mobileActionsTriggerRef,
- })}
- >
- <EllipsisVertical size="base" color="default" />
- </Button>
- )}
- </DropdownMenu>
+ <PlusIcon size="base" color="default" />
+ <span>Add to</span>
+ <DropdownIndicator size="sm" nudge />
+ </Button>
)}
- />
- )}
- </AnnotateDrawerController>
- )}
- />
- )}
- </div>
- {/* Action buttons (desktop inline cluster) */}
- {!isMobile && (
- <div className={actionsClassName}>
- <ConnectedTraceObservationAddToDropdownMenuController
- analyticsData={{ source: "TraceDetail", isV4 }}
- projectId={projectId}
- traceId={trace.id}
- variant="trace"
- input={trace.input}
- output={trace.output}
- metadata={trace.metadata}
- >
- {({ getTriggerProps }) => (
- <Button
- variant="ghost"
- size="sm"
- className={headerActionClassName}
- {...getTriggerProps()}
- >
- <PlusIcon size="base" color="default" />
- <span>Add to</span>
- <DropdownIndicator size="sm" nudge />
- </Button>
- )}
- </ConnectedTraceObservationAddToDropdownMenuController>
- {/* Hide annotation buttons in annotation mode (panel shown separately) */}
- {!isAnnotationMode && (
- <AnnotateDrawerController projectId={projectId}>
- {({ disabled, openDrawer }) => (
- <Button
- variant="ghost"
- size="sm"
- className={headerActionClassName}
- disabled={disabled}
- onClick={() =>
- openDrawer(
- prepareTraceAnnotation({
- traceId: trace.id,
- projectId,
- environment: trace.environment,
- scores: traceScores,
- isV4,
- }),
- )
- }
- >
- {disabled ? (
- <LockIcon size="base" color="default" />
- ) : (
- <SquarePen size="base" color="default" />
+ </DropdownMenu>
+ {/* Hide annotation buttons in annotation mode (panel shown separately) */}
+ {!isAnnotationMode && (
+ <Button
+ variant="ghost"
+ size="sm"
+ className={headerActionClassName}
+ disabled={annotationDisabled}
+ onClick={() =>
+ openDrawer(
+ prepareTraceAnnotation({
+ traceId: trace.id,
+ projectId,
+ environment: trace.environment,
+ scores: traceScores,
+ isV4,
+ }),
+ )
+ }
+ >
+ {annotationDisabled ? (
+ <LockIcon size="base" color="default" />
+ ) : (
+ <SquarePen size="base" color="default" />
+ )}
+ <span>Annotate</span>
+ </Button>
+ )}
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ disabled={commentDrawerControl.disabled}
+ onClick={commentDrawerControl.openDrawer}
+ className={headerActionClassName}
+ >
+ {commentDrawerControl.disabled ? (
+ <MessageSquareOff size="base" color="muted" />
+ ) : (
+ <>
+ <MessageSquare size="base" color="default" />
+ <span>{commentActionLabel}</span>
+ {!!commentCount ? (
+ <ActionButtonCountBadge count={commentCount} />
+ ) : null}
+ </>
+ )}
+ </Button>
+ </>
+ }
+ iconOnlyActions={
+ <>
+ <DropdownMenu
+ items={addToItems}
+ maxHeight="24rem"
+ placement="bottom-start"
+ >
+ {({ getTriggerProps }) => (
+ <HeaderActionButton
+ label="Add to"
+ icon={<PlusIcon size="base" />}
+ {...getTriggerProps()}
+ />
+ )}
+ </DropdownMenu>
+ {!isAnnotationMode && (
+ <HeaderActionButton
+ label="Annotate"
+ icon={
+ annotationDisabled ? (
+ <LockIcon size="base" />
+ ) : (
+ <SquarePen size="base" />
+ )
+ }
+ disabled={annotationDisabled}
+ onClick={() =>
+ openDrawer(
+ prepareTraceAnnotation({
+ traceId: trace.id,
+ projectId,
+ environment: trace.environment,
+ scores: traceScores,
+ isV4,
+ }),
+ )
+ }
+ />
)}
- <span>Annotate</span>
- </Button>
- )}
- </AnnotateDrawerController>
+ <HeaderActionButton
+ label={mobileCommentActionLabel}
+ count={
+ commentDrawerControl.disabled ? undefined : commentCount
+ }
+ icon={
+ commentDrawerControl.disabled ? (
+ <MessageSquareOff size="base" />
+ ) : (
+ <MessageSquare size="base" />
+ )
+ }
+ disabled={commentDrawerControl.disabled}
+ onClick={commentDrawerControl.openDrawer}
+ />
+ </>
+ }
+ />
)}
- <Button
- type="button"
- variant="ghost"
- size="sm"
- disabled={commentDrawerControl.disabled}
- onClick={commentDrawerControl.openDrawer}
- className={headerActionClassName}
- >
- {commentDrawerControl.disabled ? (
- <MessageSquareOff size="base" color="muted" />
- ) : (
- <>
- <MessageSquare size="base" color="default" />
- <span>{commentActionLabel}</span>
- {!!commentCount ? (
- <ActionButtonCountBadge count={commentCount} />
- ) : null}
- </>
- )}
- </Button>
- </div>
+ </AnnotateDrawerController>
)}
- </div>
+ />
{/* Metadata badges */}
<div className="flex flex-col gap-2">
diff --git a/web/src/features/traces/components/detailViewHeaderLayout.clienttest.ts b/web/src/features/traces/components/detailViewHeaderLayout.clienttest.ts
new file mode 100644
index 0000000000..609cc6f80a
--- /dev/null
+++ b/web/src/features/traces/components/detailViewHeaderLayout.clienttest.ts
@@ -0,0 +1,82 @@
+// @vitest-environment node
+
+import { describe, expect, it } from "vitest";
+
+import { planDetailViewHeaderActions } from "@/src/features/traces/components/detailViewHeaderLayout";
+
+// The detail pane's 360px floor leaves 328px of header once the shell's
+// `px-4` is taken off. `Add to · Annotate · Comment` measures 312px; the
+// icon-only cluster is about 100px.
+const PANE_FLOOR_HEADER_WIDTH = 328;
+const LABELLED_CLUSTER_PX = 312;
+const ICON_ONLY_CLUSTER_PX = 100;
+
+const base = {
+ minTitleWidth: 160,
+ gap: 8,
+ iconOnlyActionsWidth: ICON_ONLY_CLUSTER_PX,
+};
+
+describe("planDetailViewHeaderActions", () => {
+ it("puts the actions beside the title while the title keeps its width", () => {
+ // 480 - 312 - 8 = 160, the title's floor.
+ expect(
+ planDetailViewHeaderActions({
+ ...base,
+ headerWidth: 480,
+ actionsWidth: LABELLED_CLUSTER_PX,
+ }),
+ ).toBe("beside");
+ });
+
+ it("drops the actions below the title once that floor is crossed", () => {
+ expect(
+ planDetailViewHeaderActions({
+ ...base,
+ headerWidth: 479,
+ actionsWidth: LABELLED_CLUSTER_PX,
+ }),
+ ).toBe("below");
+ });
+
+ it("switches to icon-only once the labelled cluster no longer fits a row", () => {
+ expect(
+ planDetailViewHeaderActions({
+ ...base,
+ headerWidth: PANE_FLOOR_HEADER_WIDTH,
+ actionsWidth: LABELLED_CLUSTER_PX + 32,
+ }),
+ ).toBe("icon-only");
+ });
+
+ it("folds once the icon-only cluster does not fit either", () => {
+ expect(
+ planDetailViewHeaderActions({
+ ...base,
+ headerWidth: ICON_ONLY_CLUSTER_PX - 1,
+ actionsWidth: LABELLED_CLUSTER_PX + 32,
+ }),
+ ).toBe("folded");
+ });
+
+ it("folds when the buttons grow past the row, at the same header width", () => {
+ // No icon-only cluster: a comment count that widens the labels is enough.
+ const headerWidth = PANE_FLOOR_HEADER_WIDTH;
+ expect(
+ planDetailViewHeaderActions({
+ minTitleWidth: base.minTitleWidth,
+ gap: base.gap,
+ headerWidth,
+ actionsWidth: LABELLED_CLUSTER_PX,
+ }),
+ ).toBe("below");
+ expect(
+ planDetailViewHeaderActions({
+ minTitleWidth: base.minTitleWidth,
+ gap: base.gap,
+ headerWidth,
+ actionsWidth: LABELLED_CLUSTER_PX + 40,
+ }),
+ ).toBe("folded");
+ });
+});
diff --git a/web/src/features/traces/components/detailViewHeaderLayout.ts b/web/src/features/traces/components/detailViewHeaderLayout.ts
new file mode 100644
index 0000000000..7588726ebb
--- /dev/null
+++ b/web/src/features/traces/components/detailViewHeaderLayout.ts
@@ -0,0 +1,56 @@
+/**
+ * Layout planner for the trace and observation detail headers. Pure +
+ * framework-free so the adaptive behaviour can be unit-tested without a DOM.
+ *
+ * These headers sit in a resizable pane, so the width that decides the layout
+ * is the header's own, not the screen's. Given that width and the action
+ * cluster's natural width, the cluster goes:
+ *
+ * beside — on the title row, the title taking the rest,
+ * below — on a full-width row of its own, once the title would be left
+ * under `minTitleWidth` beside it,
+ * icon-only — icon buttons with tooltips (no labels), when the full cluster
+ * no longer fits on a row of its own but icon-only buttons do,
+ * folded — into the title row's overflow menu, once even icon-only buttons
+ * no longer fit on a row of their own.
+ *
+ * `folded` is what keeps the cluster on one line: it collapses before it would
+ * have to wrap, so no button is ever orphaned onto a row by itself.
+ */
+
+export type DetailViewHeaderActionsPlacement =
+ | "beside"
+ | "below"
+ | "icon-only"
+ | "folded";
+
+export type PlanDetailViewHeaderActionsArgs = {
+ /** The header row's measured width, px (the detail pane minus its padding). */
+ headerWidth: number;
+ /** The action cluster's natural, unwrapped width, px. */
+ actionsWidth: number;
+ /**
+ * The icon-only cluster's natural width, px. When provided, the planner will
+ * prefer `"icon-only"` over `"folded"` when the full cluster overflows but
+ * the icon-only version still fits.
+ */
+ iconOnlyActionsWidth?: number;
+ /** Width the title keeps before the cluster moves off its row, px. */
+ minTitleWidth: number;
+ /** Gap between the title and the cluster while they share a row, px. */
+ gap: number;
+};
+
+export function planDetailViewHeaderActions({
+ headerWidth,
+ actionsWidth,
+ iconOnlyActionsWidth,
+ minTitleWidth,
+ gap,
+}: PlanDetailViewHeaderActionsArgs): DetailViewHeaderActionsPlacement {
+ if (headerWidth - actionsWidth - gap >= minTitleWidth) return "beside";
+ if (actionsWidth <= headerWidth) return "below";
+ if (iconOnlyActionsWidth !== undefined && iconOnlyActionsWidth <= headerWidth)
+ return "icon-only";
+ return "folded";
+}