gloomberb 0.18.2 → 0.18.4

package/src/components/chart/composite/use-composite-chart-keyboard.ts

@@ -59,6 +59,31 @@ export interface KeyboardToolDrag {
   end: ChartDrawingPoint;
 }
 
+/** The chart's own layout: its tool bar, its legend and its panels' heights. */
+export interface CompositeChartLayoutControls {
+  /** The bar is saved hidden; it still opens while a tool is in hand. */
+  toolbarHidden: boolean;
+  toggleToolbar: () => void;
+  /** The legend has more than one series, so it can fold to its first. */
+  legendCollapsible: boolean;
+  legendCollapsed: boolean;
+  toggleLegend: () => void;
+  /** Two or more panels share the plot, so the keys can move the line between them. */
+  panelsResizable: boolean;
+  stepTopPanel: (direction: 1 | -1) => void;
+  /** Heights were set by hand. */
+  panelHeightsSet: boolean;
+  resetPanelHeights: () => void;
+  /** A panel has the whole plot. */
+  panelMaximized: boolean;
+  restorePanels: () => void;
+}
+
+/** Shift with one of the arrows, and no other modifier. */
+function isShiftedArrow(event: { name?: string; shift?: boolean; ctrl?: boolean; meta?: boolean; alt?: boolean }, ...names: string[]): boolean {
+  return event.shift === true && !event.ctrl && !event.meta && !event.alt && names.includes(event.name ?? "");
+}
+
 /** Shift and a letter, whether or not the terminal reports the shift itself. */
 function isShiftedLetter(event: { name?: string; shift?: boolean; ctrl?: boolean; meta?: boolean; alt?: boolean }, letter: string): boolean {
   if (event.ctrl || event.meta || event.alt) return false;
@@ -76,6 +101,7 @@ export function useCompositeChartKeyboard({
   pin,
   onActivate,
   timePick,
+  pricePick,
   levels,
   visibleLegendSeries,
   visibleSeriesIds,
@@ -83,6 +109,7 @@ export function useCompositeChartKeyboard({
   isSeriesToggleable,
   navigationFrame,
   activeUserViewport,
+  scaledByHand,
   panViewportByRatio,
   zoomViewport,
   setViewportRange,
@@ -94,6 +121,7 @@ export function useCompositeChartKeyboard({
   addDrawing,
   removeDrawing,
   pickDrawColor,
+  layout,
 }: {
   focused: boolean;
   interactive: boolean;
@@ -106,6 +134,7 @@ export function useCompositeChartKeyboard({
   pin: { pinned: boolean; toggle: () => void } | null;
   onActivate: CompositeChartProps["onActivate"];
   timePick: CompositeChartProps["timePick"];
+  pricePick: CompositeChartProps["pricePick"];
   levels: CompositeChartProps["levels"];
   visibleLegendSeries: ResolvedSeries[];
   visibleSeriesIds: ReadonlySet<string>;
@@ -113,6 +142,8 @@ export function useCompositeChartKeyboard({
   isSeriesToggleable: CompositeChartProps["isSeriesToggleable"];
   navigationFrame: CompositeNavigationFrame | null;
   activeUserViewport: CompositeViewportRange | null;
+  /** A value axis was stretched or squeezed by hand, which `resetViewport` also fits again. */
+  scaledByHand: boolean;
   panViewportByRatio: (shiftRatio: number) => void;
   zoomViewport: (zoomFactor: number, anchorRatio?: number) => void;
   setViewportRange: (range: CompositeViewportRange) => void;
@@ -124,6 +155,7 @@ export function useCompositeChartKeyboard({
   addDrawing: (drawing: ChartDrawing) => void;
   removeDrawing: () => void;
   pickDrawColor: (color: string) => void;
+  layout: CompositeChartLayoutControls;
 }) {
   const [legendKeyboardIndex, setLegendKeyboardIndex] = useState<number | null>(null);
   const [armedTool, setArmedTool] = useState<ChartToolKind | null>(null);
@@ -187,8 +219,8 @@ export function useCompositeChartKeyboard({
     if (wasFocusedRef.current && !focused) setEntered(false);
     wasFocusedRef.current = focused;
   }, [focused]);
-  // A time is picked with the arrows and Enter.
-  const picking = !!timePick;
+  // A time or a price is picked with the arrows and Enter.
+  const picking = !!timePick || !!pricePick;
   useEffect(() => {
     if (picking) setEntered(true);
   }, [picking]);
@@ -287,6 +319,8 @@ export function useCompositeChartKeyboard({
   };
   const stepLegend = (direction: -1 | 1) => {
     onActivate?.();
+    // The series stepped to must be on screen.
+    if (layout.legendCollapsed) layout.toggleLegend();
     setLegendKeyboardIndex((current) => (
       current === null
         ? direction > 0 ? 0 : visibleLegendSeries.length - 1
@@ -298,9 +332,9 @@ export function useCompositeChartKeyboard({
     onActivate?.();
     onToggleSeries?.(legendEntry.id);
   };
-  /** A level at the keyboard cursor's price, or the last price without a cursor. */
-  const addLevelAtCursor = () => {
-    if (!levels?.onEdit || !levelHost || !scene) return;
+  /** The levels' series price at the keyboard cursor, or the last price without a cursor. */
+  const priceAtCursor = (): number | null => {
+    if (!levels || !levelHost || !scene) return null;
     const { panel, domain } = levelHost;
     const date = keyboardCursorDateRef.current ?? scene.dates.at(-1) ?? null;
     // The levels' own series, not whichever one the panel lists first.
@@ -308,8 +342,13 @@ export function useCompositeChartKeyboard({
     const value = (date ? resolveMeasureValueAt(pricePanel, date.getTime()) : null)
       ?? (panel.lastPrice?.seriesId === levels.seriesId ? panel.lastPrice.value : null)
       ?? unprojectCompositeValue(0.5, domain);
-    if (value === null) return;
-    const rounded = roundLevelValue(value, domain);
+    return value === null ? null : roundLevelValue(value, domain);
+  };
+  /** A level at the keyboard cursor's price, or the last price without a cursor. */
+  const addLevelAtCursor = () => {
+    if (!levels?.onEdit) return;
+    const rounded = priceAtCursor();
+    if (rounded === null) return;
     onActivate?.();
     // Enter again at the same cursor picks the level already there.
     const existing = levelItems.find((level) => level.editable && level.value === rounded);
@@ -342,7 +381,8 @@ export function useCompositeChartKeyboard({
     setSelectedLevelId(ordered[next]!.id);
   };
   const removeSelectedLevel = () => {
-    if (!selectedLevel?.editable) return;
+    // An order's line moves here; it is cancelled where the order is.
+    if (!selectedLevel?.editable || selectedLevel.draggable) return;
     levels?.onEdit?.({ kind: "remove", id: selectedLevel.id });
     setSelectedLevelId(null);
   };
@@ -403,6 +443,13 @@ export function useCompositeChartKeyboard({
       else chartActionsRef.current.pick();
       return;
     }
+    // Esc ends a price pick even with nothing drawn yet; Enter needs a price at the cursor.
+    if (pricePick && (scene || isPlainKey(event, "escape")) && isPlainKey(event, "return", "enter", "escape")) {
+      consume();
+      if (event.name === "escape") pricePick.onCancel();
+      else chartActionsRef.current.pickPrice();
+      return;
+    }
     if (zoned && !entered && isPlainKey(event, "down", "return", "enter")) {
       consume();
       enterChart();
@@ -424,7 +471,7 @@ export function useCompositeChartKeyboard({
       stepLevel(event.name === "[" ? -1 : 1);
       return;
     }
-    if (toolsActive && selectedLevel?.editable && levelsEditable && isPlainKey(event, "backspace")) {
+    if (toolsActive && selectedLevel?.editable && !selectedLevel.draggable && levelsEditable && isPlainKey(event, "backspace", "delete")) {
       consume();
       removeSelectedLevel();
       return;
@@ -453,6 +500,21 @@ export function useCompositeChartKeyboard({
       setKeyboardPlacement((current) => current && moveKeyboardPlacement(current, { level }));
       return;
     }
+    if (toolsActive && isShiftedLetter(event, "t")) {
+      consume();
+      layout.toggleToolbar();
+      return;
+    }
+    if (legendKeysActive && layout.legendCollapsible && isShiftedLetter(event, "l")) {
+      consume();
+      layout.toggleLegend();
+      return;
+    }
+    if (toolsActive && layout.panelsResizable && isShiftedArrow(event, "up", "down")) {
+      consume();
+      layout.stepTopPanel(event.name === "up" ? 1 : -1);
+      return;
+    }
     if (isPlainKey(event, "[", "]") && (drawingKeysActive || legendKeysActive)) {
       consume();
       const direction = event.name === "[" ? -1 : 1;
@@ -579,6 +641,10 @@ export function useCompositeChartKeyboard({
       const date = keyboardCursorDateRef.current ?? scene?.dates.at(-1) ?? null;
       if (date) timePick?.onPick(date);
     },
+    pickPrice: () => {
+      const value = priceAtCursor();
+      if (value !== null) pricePick?.onPick(value);
+    },
     start: armedTool === "level" ? addLevelAtCursor : startKeyboardPlacement,
     finish: finishKeyboardPlacement,
     stepLevel,
@@ -596,6 +662,7 @@ export function useCompositeChartKeyboard({
     },
     leave: leaveChart,
     togglePin: () => pin?.toggle(),
+    layout,
   };
   const chartActionsRef = useRef(chartActions);
   chartActionsRef.current = chartActions;
@@ -608,17 +675,27 @@ export function useCompositeChartKeyboard({
   const armedHints = armedTool ? KEYBOARD_TOOL_HINTS[armedTool] : null;
   const placing = !!keyboardPlacement;
   const legendEntryVisible = !!legendEntry && visibleSeriesIds.has(legendEntry.id);
-  const resettable = !!activeUserViewport;
-  const timePickLabel = timePick?.label ?? null;
+  const resettable = !!activeUserViewport || scaledByHand;
+  const timePickLabel = timePick?.label ?? (levelHost ? pricePick?.label : null) ?? null;
+  const pickingPrice = !timePick && !!pricePick;
   const levelActionHint = selectedLevel?.actionable && levels?.action ? levels.action : null;
   const levelToolKeys = toolsActive && armedTool === "level" && levelsEditable;
-  const canDeleteLevel = toolsActive && levelsEditable && !!selectedLevel?.editable;
+  const canDeleteLevel = toolsActive && levelsEditable && !!selectedLevel?.editable && !selectedLevel.draggable;
   const pinState = pin ? pin.pinned : null;
+  // Hidden as it shows: a saved hidden bar is open while a tool is in hand.
+  const toolbarHidden = layout.toolbarHidden && armedTool === null;
+  const {
+    legendCollapsible,
+    legendCollapsed,
+    panelsResizable,
+    panelHeightsSet,
+    panelMaximized,
+  } = layout;
   usePaneFooter(keyboardId, () => {
     if (!keyboardActive || !scene) return null;
     const hints: PaneHint[] = [];
     if (timePickLabel) {
-      hints.push({ id: "chart-pick", key: "Enter", label: timePickLabel, onPress: () => chartActionsRef.current.pick() });
+      hints.push({ id: "chart-pick", key: "Enter", label: timePickLabel, onPress: () => pickingPrice ? chartActionsRef.current.pickPrice() : chartActionsRef.current.pick() });
     } else if (toolsActive && armedHints) {
       hints.push(placing
         ? { id: "chart-tool", key: "Enter", label: armedHints.finish, title: armedHints.finishTitle, onPress: () => chartActionsRef.current.finish() }
@@ -686,6 +763,29 @@ export function useCompositeChartKeyboard({
         });
       }
       if (resettable) menu.push({ id: "chart-reset", label: "Reset Zoom", accelerator: "0", onSelect: () => chartActionsRef.current.reset() });
+      menu.push({
+        id: "chart-toolbar",
+        label: toolbarHidden ? "Show Drawing Tools" : "Hide Drawing Tools",
+        accelerator: "Shift+T",
+        onSelect: () => chartActionsRef.current.layout.toggleToolbar(),
+      });
+      if (panelsResizable) {
+        menu.push({ id: "chart-panel-taller", label: "Taller Top Panel", accelerator: "Shift+Up", onSelect: () => chartActionsRef.current.layout.stepTopPanel(1) });
+        menu.push({ id: "chart-panel-shorter", label: "Shorter Top Panel", accelerator: "Shift+Down", onSelect: () => chartActionsRef.current.layout.stepTopPanel(-1) });
+      }
+      if (panelMaximized) {
+        menu.push({ id: "chart-panels-restore", label: "Show All Panels", onSelect: () => chartActionsRef.current.layout.restorePanels() });
+      } else if (panelHeightsSet) {
+        menu.push({ id: "chart-panels-reset", label: "Reset Panel Heights", onSelect: () => chartActionsRef.current.layout.resetPanelHeights() });
+      }
+    }
+    if (legendKeysActive && legendCollapsible) {
+      menu.push({
+        id: "chart-legend",
+        label: legendCollapsed ? "Expand Legend" : "Collapse Legend",
+        accelerator: "Shift+L",
+        onSelect: () => chartActionsRef.current.layout.toggleLegend(),
+      });
     }
     if (legendKeysActive && anyLegendToggleable && !drawingKeysActive) {
       menu.push({ id: "chart-series-next", label: "Next Series", accelerator: "]", onSelect: () => chartActionsRef.current.stepLegend(1) });
@@ -706,6 +806,7 @@ export function useCompositeChartKeyboard({
     !!scene,
     selectedDrawingId,
     timePickLabel,
+    pickingPrice,
     levelActionHint,
     levelToolKeys,
     levelItems.length,
@@ -713,6 +814,12 @@ export function useCompositeChartKeyboard({
     levelsEditable,
     toolsActive,
     pinState,
+    toolbarHidden,
+    legendCollapsible,
+    legendCollapsed,
+    panelsResizable,
+    panelHeightsSet,
+    panelMaximized,
   ]);
 
   return {

package/src/components/chart/composite/use-composite-value-scales.ts

@@ -0,0 +1,44 @@
+import { useCallback, useRef, useState } from "react";
+import type { CompositeAxisSide } from "./types";
+import { NO_VALUE_SCALES, valueScaleSlot, type CompositeValueRange, type CompositeValueScales } from "./value-scale";
+
+/**
+ * The chart's manual value scales: set by a drag or the wheel on an axis, or
+ * a drag on the plot of a panel already scaled by hand; cleared per panel or
+ * all at once, and whenever `resetKey` changes (in the same render, so a new
+ * view never draws in the old one's scale).
+ */
+export function useCompositeValueScales(resetKey: unknown) {
+  const [state, setState] = useState<{ resetKey: unknown; scales: CompositeValueScales }>(() => ({ resetKey, scales: NO_VALUE_SCALES }));
+  const resetKeyRef = useRef(resetKey);
+  resetKeyRef.current = resetKey;
+  const scales = Object.is(state.resetKey, resetKey) ? state.scales : NO_VALUE_SCALES;
+  const update = useCallback((change: (scales: CompositeValueScales) => CompositeValueScales) => {
+    setState((current) => {
+      const key = resetKeyRef.current;
+      const fresh = Object.is(current.resetKey, key);
+      const base = fresh ? current.scales : NO_VALUE_SCALES;
+      const next = change(base);
+      return fresh && next === base ? current : { resetKey: key, scales: next };
+    });
+  }, []);
+  const setValueScale = useCallback((panelId: string, side: CompositeAxisSide, key: string, range: CompositeValueRange) => {
+    const slot = valueScaleSlot(panelId, side);
+    update((current) => {
+      const previous = current[slot];
+      if (previous && previous.key === key && previous.min === range.min && previous.max === range.max) return current;
+      return { ...current, [slot]: { key, min: range.min, max: range.max } };
+    });
+  }, [update]);
+  const resetPanelValueScale = useCallback((panelId: string) => {
+    update((current) => {
+      const slots = (["left", "right"] as const).map((side) => valueScaleSlot(panelId, side)).filter((slot) => slot in current);
+      if (slots.length === 0) return current;
+      const next = { ...current };
+      for (const slot of slots) delete next[slot];
+      return Object.keys(next).length === 0 ? NO_VALUE_SCALES : next;
+    });
+  }, [update]);
+  const resetValueScales = useCallback(() => update(() => NO_VALUE_SCALES), [update]);
+  return { valueScales: scales, setValueScale, resetPanelValueScale, resetValueScales };
+}

package/src/components/chart/composite/use-composite-viewport.ts

@@ -99,9 +99,13 @@ export function useCompositeViewport({
     );
   }, [onViewportChange, userViewportEnd, userViewportStart]);
 
+  // Counts authored views, so what belongs to one (values scaled by hand) can
+  // go with it; `authoredViewportChanged` covers the render before it counts.
+  const [authoredGeneration, setAuthoredGeneration] = useState(0);
   useEffect(() => {
     previousAuthoredViewportRef.current = viewport ?? null;
     previousViewportResetKeyRef.current = viewportResetKey;
+    if (authoredViewportChanged) setAuthoredGeneration((generation) => generation + 1);
     if (authoredViewportChanged && userViewport) {
       viewportInteractionRef.current = "reset";
       setUserViewport(null);
@@ -154,8 +158,13 @@ export function useCompositeViewport({
     if (!positions) return;
     panViewport(shiftRatio * Math.max(positions.end - positions.start, Number.EPSILON));
   }, [effectiveViewport, navigationFrame, panViewport]);
-  const zoomViewport = useCallback((zoomFactor: number, anchorRatio = 1) => {
-    navigate("zoom", (base, frame) => zoomCompositeViewport(frame, base, zoomFactor, anchorRatio));
+  /** A gesture (a drag on the time axis) zooms from the view and frame it started in, by its whole travel so far. */
+  const zoomViewport = useCallback((
+    zoomFactor: number,
+    anchorRatio = 1,
+    gesture?: { frame: CompositeNavigationFrame; from: CompositeViewportRange },
+  ) => {
+    navigate("zoom", (base, frame) => zoomCompositeViewport(frame, base, zoomFactor, anchorRatio), gesture);
   }, [navigate]);
   const setViewportRange = useCallback((range: CompositeViewportRange) => {
     navigate("zoom", (_base, frame) => fitCompositeViewport(frame, range));
@@ -165,7 +174,7 @@ export function useCompositeViewport({
     setUserViewport(null);
   }, []);
   return {
-    navigationFrame, activeUserViewport, effectiveViewport,
+    navigationFrame, activeUserViewport, effectiveViewport, authoredViewportChanged, authoredGeneration,
     panViewport, panViewportByRatio, zoomViewport, setViewportRange, resetViewport,
   };
 }

package/src/components/chart/composite/value-scale.ts

@@ -0,0 +1,149 @@
+import type { PanelScale, ResolvedSeries } from "../../../time-series/types";
+import type { CompositeAxisSide } from "./types";
+import { clamp } from "../../../utils/math";
+
+/** What a value axis shows, in its own values. */
+export interface CompositeValueRange {
+  min: number;
+  max: number;
+}
+
+/**
+ * A value axis stretched or squeezed by hand, and what it plots: a range set
+ * for one listing's prices means nothing for another's, so it holds only
+ * while the axis plots the same series in the same unit and scale.
+ */
+export interface CompositeManualValueScale extends CompositeValueRange {
+  key: string;
+}
+
+/** Manual value scales by panel and side (`valueScaleSlot`). */
+export type CompositeValueScales = Readonly<Record<string, CompositeManualValueScale>>;
+
+export const NO_VALUE_SCALES: CompositeValueScales = Object.freeze({});
+
+export function valueScaleSlot(panelId: string, side: CompositeAxisSide): string {
+  return `${panelId}\u0000${side}`;
+}
+
+/** Identifies what an axis plots, for `CompositeManualValueScale.key`. */
+export function valueScaleKey(scale: PanelScale, axisSeries: readonly ResolvedSeries[]): string {
+  return [
+    scale,
+    ...axisSeries.map((entry) => [entry.id, entry.label, entry.unit, entry.listing?.symbol ?? ""].join("\u0001")),
+  ].join("\u0000");
+}
+
+/** Pixels of drag along an axis that stretch or squeeze it by a factor of e. */
+const AXIS_DRAG_PIXELS_PER_E = 200;
+/** The finest and coarsest a linear axis may get, against the size of the values it shows. */
+const MIN_LINEAR_SPAN_RATIO = 1e-9;
+const MAX_LINEAR_SPAN = 1e15;
+/** The same for a log axis, in natural-log units. */
+const MIN_LOG_SPAN = 1e-9;
+const MAX_LOG_SPAN = 60;
+
+/**
+ * How much a drag of `deltaPx` along an axis multiplies the span it shows.
+ * Down a value axis or right along the time axis shows more (a factor above
+ * one), the other way less, and the way back undoes it exactly.
+ */
+export function resolveAxisDragSpanFactor(deltaPx: number): number {
+  return Number.isFinite(deltaPx) ? Math.exp(deltaPx / AXIS_DRAG_PIXELS_PER_E) : 1;
+}
+
+function toAxis(value: number, scale: PanelScale): number {
+  return scale === "log" ? Math.log(value) : value;
+}
+
+function fromAxis(value: number, scale: PanelScale): number {
+  return scale === "log" ? Math.exp(value) : value;
+}
+
+/** The range as top and bottom in the axis's own space: values, or their logs. */
+function axisEnds(range: CompositeValueRange, scale: PanelScale): { top: number; bottom: number } | null {
+  if (scale === "log" && (range.min <= 0 || range.max <= 0)) return null;
+  const top = toAxis(range.max, scale);
+  const bottom = toAxis(range.min, scale);
+  return Number.isFinite(top) && Number.isFinite(bottom) && top > bottom ? { top, bottom } : null;
+}
+
+function rangeFromEnds(top: number, bottom: number, scale: PanelScale): CompositeValueRange {
+  return { min: fromAxis(bottom, scale), max: fromAxis(top, scale) };
+}
+
+/**
+ * The range after multiplying its span by `spanFactor` (above one shows more)
+ * around the value at `anchorRatio`, 0 the top of the panel and 1 the bottom,
+ * which stays where it is. A log axis stretches in its own, logarithmic space.
+ */
+export function zoomValueRange(
+  range: CompositeValueRange,
+  scale: PanelScale,
+  spanFactor: number,
+  anchorRatio: number,
+): CompositeValueRange {
+  const ends = axisEnds(range, scale);
+  if (!ends || !(spanFactor > 0) || !Number.isFinite(spanFactor)) return range;
+  const ratio = clamp(Number.isFinite(anchorRatio) ? anchorRatio : 0.5, 0, 1);
+  const span = ends.top - ends.bottom;
+  const anchor = ends.top - span * ratio;
+  const nextSpan = scale === "log"
+    ? clamp(span * spanFactor, MIN_LOG_SPAN, MAX_LOG_SPAN)
+    : clamp(span * spanFactor, Math.max(Math.abs(anchor), Number.MIN_VALUE) * MIN_LINEAR_SPAN_RATIO, MAX_LINEAR_SPAN);
+  const top = anchor + nextSpan * ratio;
+  return rangeFromEnds(top, top - nextSpan, scale);
+}
+
+/**
+ * The range moved with a drag of `deltaRatio` of the panel's height, positive
+ * downward: what was under the pointer stays under it.
+ */
+export function panValueRange(
+  range: CompositeValueRange,
+  scale: PanelScale,
+  deltaRatio: number,
+): CompositeValueRange {
+  const ends = axisEnds(range, scale);
+  if (!ends || !Number.isFinite(deltaRatio) || deltaRatio === 0) return range;
+  const shift = (ends.top - ends.bottom) * deltaRatio;
+  return rangeFromEnds(ends.top + shift, ends.bottom + shift, scale);
+}
+
+/** A manual range holds while some of the data is in it; pushed clear of the data it fits the data again. */
+export function manualValueRangeApplies(
+  manual: CompositeValueRange,
+  data: CompositeValueRange,
+  scale: PanelScale,
+): boolean {
+  const ends = axisEnds(manual, scale);
+  return !!ends && manual.max > data.min && manual.min < data.max;
+}
+
+/**
+ * Keeps an end of a segment that leaves the band from `minY` to `maxY` on the
+ * band's edge, along the segment: what is drawn of it inside stays exact and
+ * nothing is drawn far outside. Null when it misses the band.
+ */
+export function clipSegmentToBand(
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number,
+  minY: number,
+  maxY: number,
+): [number, number, number, number] | null {
+  if ((y0 < minY && y1 < minY) || (y0 > maxY && y1 > maxY)) return null;
+  if (y0 >= minY && y0 <= maxY && y1 >= minY && y1 <= maxY) return [x0, y0, x1, y1];
+  const at = (y: number) => {
+    const t = (y - y0) / (y1 - y0);
+    return x0 + (x1 - x0) * t;
+  };
+  let startX = x0;
+  let startY = y0;
+  let endX = x1;
+  let endY = y1;
+  if (startY < minY) { startX = at(minY); startY = minY; } else if (startY > maxY) { startX = at(maxY); startY = maxY; }
+  if (endY < minY) { endX = at(minY); endY = minY; } else if (endY > maxY) { endX = at(maxY); endY = maxY; }
+  return [startX, startY, endX, endY];
+}

package/src/components/chart/composite/volume-profile-paint.ts

@@ -27,7 +27,8 @@ export function paintVolumeProfile(
     row.volume > (profile.rows[best]?.volume ?? -1) ? index : best
   ), 0);
   profile.rows.forEach((row, index) => {
-    if (row.volume <= 0) return;
+    // Rows a hand-scaled axis leaves off the panel are not piled on its edge.
+    if (row.volume <= 0 || row.highRatio > 1 || row.lowRatio < 0) return;
     const top = Math.round(clamp(row.highRatio, 0, 1) * maxY);
     const edge = Math.round(clamp(row.lowRatio, 0, 1) * maxY);
     // A pixel between rows keeps tall bars apart; thin ones would vanish.
@@ -36,7 +37,8 @@ export function paintVolumeProfile(
     const opacity = index === pocRow ? POC_OPACITY : row.valueArea ? VALUE_AREA_OPACITY : OUTSIDE_OPACITY;
     fillRect(data, width, height, width - length, top, width - 1, bottom, color, opacity);
   });
-  const y = Math.round(clamp(profile.pocRatio, 0, 1) * maxY);
+  if (profile.pocRatio < 0 || profile.pocRatio > 1) return;
+  const y = Math.round(profile.pocRatio * maxY);
   for (let x = 0; x < width; x += 5) {
     fillRect(data, width, height, x, y, Math.min(x + 1, width - 1), y, color, 0.7);
   }
@@ -57,13 +59,14 @@ export function writeVolumeProfileText(
   const volumes = new Array<number>(height).fill(0);
   const valueArea = new Array<boolean>(height).fill(false);
   for (const row of profile.rows) {
+    if (row.highRatio > 1 || row.lowRatio < 0) continue;
     const line = clamp(Math.round(((row.highRatio + row.lowRatio) / 2) * (height - 1)), 0, height - 1);
     volumes[line]! += row.volume;
     if (row.valueArea) valueArea[line] = true;
   }
   const peak = Math.max(...volumes);
   if (peak <= 0) return;
-  const pocLine = clamp(Math.round(profile.pocRatio * (height - 1)), 0, height - 1);
+  const pocLine = profile.pocRatio < 0 || profile.pocRatio > 1 ? -1 : Math.round(profile.pocRatio * (height - 1));
   const maxLength = Math.max(1, Math.floor(width * PROFILE_WIDTH_RATIO));
   volumes.forEach((volume, line) => {
     if (volume <= 0) return;

package/src/components/chart/core/pointer.ts

@@ -21,6 +21,8 @@ export interface ChartMouseEvent {
   y: number;
   /** DOM target on the desktop host; absent in the terminal. */
   target?: { closest?: (selector: string) => unknown } | null;
+  /** The press's click count on the desktop host (2 on a double click); absent in the terminal. */
+  detail?: number;
   preciseX?: number;
   preciseY?: number;
   pixelX?: number;

package/src/components/chart-table/index.ts

@@ -6,6 +6,8 @@ export {
   fitChartTableColumns,
 } from "./layout";
 export type { ChartBandMode, ChartTableLayout } from "./layout";
+export { ChartRead, useChartReadRows } from "./read";
+export type { ChartReadProps } from "./read";
 export { useChartTableSelection } from "./selection";
 export type { ChartTableSelection } from "./selection";
 export { formatBpAxis, formatCompactAxis, formatPercentAxis, spanAxisFormatter, spanDigits } from "./axis";

package/src/components/chart-table/read.tsx

@@ -0,0 +1,74 @@
+import { useThemeColors } from "../../theme/theme-context";
+import { Box, Text, useUiCapabilities } from "../../ui";
+import { displayWidth, truncateToDisplayWidth } from "../../utils/format";
+import { wrapTextLines } from "../../utils/text-wrap";
+import { ClippedText } from "../ui/display";
+
+/** The terminal wraps a read onto at most this many rows; a longer one ends in an ellipsis on the last. */
+export const CHART_READ_MAX_ROWS = 3;
+/** The read's inset on each side, as on the query bar and the legend above it. */
+const READ_INSET = 1;
+
+/**
+ * The terminal's lines for a read under a chart at a pane `width`: the whole
+ * sentence on one row when it fits, otherwise wrapped at words onto up to
+ * `CHART_READ_MAX_ROWS` rows. None when there is no read or no room for one.
+ */
+export function chartReadLines(text: string | null | undefined, width: number): string[] {
+  const room = Math.floor(width) - 2 * READ_INSET;
+  const read = text?.trim();
+  if (!read || room <= 0) return [];
+  if (displayWidth(read) <= room) return [read];
+  const lines = wrapTextLines(read, room);
+  if (lines.length <= CHART_READ_MAX_ROWS) return lines;
+  return [
+    ...lines.slice(0, CHART_READ_MAX_ROWS - 1),
+    truncateToDisplayWidth(lines.slice(CHART_READ_MAX_ROWS - 1).join(" "), room),
+  ];
+}
+
+/**
+ * The rows the longest of these reads needs under a chart at a pane `width`
+ * (none when none has one). A pane puts it in `minRows` so the band does not
+ * flip between a chart and a strip as the selection moves between a short
+ * read and a long one. The desktop and the web cut a read by CSS on one row.
+ */
+export function useChartReadRows(texts: ReadonlyArray<string | null | undefined>, width: number): number {
+  const { nativePaneChrome } = useUiCapabilities();
+  let rows = 0;
+  for (const text of texts) {
+    const lines = chartReadLines(text, width).length;
+    rows = Math.max(rows, nativePaneChrome ? Math.min(1, lines) : lines);
+  }
+  return rows;
+}
+
+export interface ChartReadProps {
+  /** The plain sentence worked out from the numbers, as the server wrote it. */
+  text: string | null | undefined;
+  /** The pane's width: the read sits one cell in from each edge. */
+  width: number;
+}
+
+/**
+ * The plain read under a chart's axis. In the terminal the whole sentence is
+ * wrapped onto up to `CHART_READ_MAX_ROWS` rows (take its rows from the chart
+ * with `useChartReadRows`); the desktop and the web keep one row and cut it
+ * by CSS where its box ends.
+ */
+export function ChartRead({ text, width }: ChartReadProps) {
+  const colors = useThemeColors();
+  const { nativePaneChrome } = useUiCapabilities();
+  const lines = chartReadLines(text, width);
+  if (lines.length === 0) return null;
+  if (nativePaneChrome) {
+    return <Box height={1} paddingX={READ_INSET}><ClippedText fg={colors.textMuted} text={text!.trim()} width={width - 2 * READ_INSET} /></Box>;
+  }
+  return (
+    <Box flexDirection="column" height={lines.length} flexShrink={0}>
+      {lines.map((line, index) => (
+        <Box key={index} height={1} paddingX={READ_INSET}><Text fg={colors.textMuted}>{line}</Text></Box>
+      ))}
+    </Box>
+  );
+}