gloomberb 0.18.0 → 0.18.2

package/src/portfolio/cost-fx.ts

@@ -0,0 +1,61 @@
+import { fxLegForCurrency } from "../market-data/coordinator/fx-legs";
+import { fxCloseOnDate, type FxHistoryClient } from "../market-data/fx-closes";
+import { heldCurrencyUnit } from "../utils/currency-units";
+
+/** Reads a pair's daily bars; `apiClient` in the app, a fake in tests. */
+export type CostFxHistoryClient = FxHistoryClient;
+
+/** The rate a lot's cost was bought at: one unit of its currency in the portfolio's, at a dated daily close. */
+export interface CostFxReading {
+  rate: number;
+  /** The UTC day of the FX close it was read from: the purchase date, or the last trading day before it. */
+  date: string;
+}
+
+/** Why no rate could be read for a purchase date; the command says to give one with --cost-fx instead. */
+export class CostFxError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CostFxError";
+  }
+}
+
+/**
+ * USD per unit of an ISO currency at its last completed daily close on or
+ * before `date`, looking back a week at most (`fxCloseOnDate`, as `fx --date`
+ * reads it). Null when the pair has no close in that week.
+ */
+async function usdPerUnitOn(code: string, date: string, client: CostFxHistoryClient, now: Date): Promise<CostFxReading | null> {
+  if (code === "USD") return { rate: 1, date };
+  const leg = fxLegForCurrency(code);
+  if (!leg) throw new CostFxError(`No daily FX history is served for ${code}`);
+  return fxCloseOnDate(leg, date, client, now);
+}
+
+/**
+ * What one unit of `from` (a lot's currency, GBp counting pence and USX cents) cost in
+ * `into` (the portfolio's) at the daily FX closes of `date`, each pair's last
+ * close on or before it, crossed through USD as every converted value is.
+ * Throws `CostFxError` when a pair is not served or has no close in the week
+ * before the date.
+ */
+export async function loadCostFxRate(
+  from: string,
+  into: string,
+  date: string,
+  client: CostFxHistoryClient,
+  now = new Date(),
+): Promise<CostFxReading> {
+  const fromUnit = heldCurrencyUnit(from);
+  const intoUnit = heldCurrencyUnit(into);
+  const [fromUsd, intoUsd] = await Promise.all([
+    usdPerUnitOn(fromUnit.currency, date, client, now),
+    usdPerUnitOn(intoUnit.currency, date, client, now),
+  ]);
+  const missing = [fromUsd ? null : fromUnit.currency, intoUsd ? null : intoUnit.currency].filter(Boolean);
+  if (!fromUsd || !intoUsd) throw new CostFxError(`No ${missing.join(" or ")} FX close in the week up to ${date}`);
+  const rate = (fromUsd.rate / fromUnit.divisor) / (intoUsd.rate / intoUnit.divisor);
+  if (!Number.isFinite(rate) || rate <= 0) throw new CostFxError(`No usable ${fromUnit.currency}/${intoUnit.currency} rate for ${date}`);
+  // A pair that did not trade that day (its holiday) dates the cross by its own last close.
+  return { rate, date: fromUsd.date < intoUsd.date ? fromUsd.date : intoUsd.date };
+}

package/src/portfolio/mutations.ts

@@ -39,6 +39,13 @@ export interface SetManualPortfolioPositionInput {
    * read does not unsize it.
    */
   multiplier?: number;
+  /** The purchase date, YYYY-MM-DD. Left out, a single manual lot keeps the one it had. */
+  dateAcquired?: string;
+  /**
+   * The rate the cost was bought at: one unit of `currency` in `costFx.currency`.
+   * Null clears it; left out, a single manual lot in the same currency keeps the one it had.
+   */
+  costFx?: { rate: number; currency: string } | null;
 }
 
 /** What a position's size counts, as its field and messages name it. */
@@ -406,8 +413,14 @@ export function setManualPortfolioPosition(
   const replacedPositionCount = replacedPositions.length;
   // Editing a single snapshot (for example after a split) does not change its
   // acquisition date. A consolidated replacement of several lots has no one date.
-  const dateAcquired = replacedPositions.length === 1 && replacedPositions[0]?.broker === "manual"
-    ? replacedPositions[0].dateAcquired : undefined;
+  const single = replacedPositions.length === 1 && replacedPositions[0]?.broker === "manual" ? replacedPositions[0] : null;
+  const dateAcquired = input.dateAcquired ?? single?.dateAcquired;
+  // The rate the cost was bought at goes with its cost: a lot kept in its currency keeps it unless it is replaced or cleared.
+  const keptCostFx = single && single.currency?.trim().toUpperCase() === nextCurrency
+    && typeof single.costFxRate === "number" && single.costFxCurrency
+    ? { rate: single.costFxRate, currency: single.costFxCurrency } : null;
+  const costFx = input.costFx === undefined ? keptCostFx : input.costFx;
+  if (costFx && !(Number.isFinite(costFx.rate) && costFx.rate > 0)) throw new Error("The cost FX rate must be a positive number.");
   // A contract's size does not change with the count held; one the lots agree on carries over.
   const keptMultipliers = new Set(replacedPositions.map((position) => position.multiplier));
   const keptMultiplier = keptMultipliers.size === 1 ? [...keptMultipliers][0] : undefined;
@@ -422,6 +435,7 @@ export function setManualPortfolioPosition(
     currency: nextCurrency,
     broker: "manual",
     ...(dateAcquired ? { dateAcquired } : {}),
+    ...(costFx ? { costFxRate: costFx.rate, costFxCurrency: costFx.currency.trim().toUpperCase() } : {}),
     ...(multiplier !== undefined ? { multiplier } : {}),
   });
 

package/src/portfolio/position-metrics.ts

@@ -3,7 +3,7 @@ import type { Quote } from "../types/financials";
 import type { PriceBasis } from "../types/instrument";
 import { resolvePriceBasis } from "../market-data/market/price-basis";
 import { getActiveQuoteDisplay, type ActiveQuoteDisplay } from "../market-data/market/status";
-import { resolveCurrencyUnit } from "../utils/currency-units";
+import { heldCurrencyUnit, resolveCurrencyUnit } from "../utils/currency-units";
 import { isFuturesTicker } from "./futures-positions";
 
 export interface PortfolioPositionMetrics {
@@ -103,6 +103,42 @@ function resolvePositionCostMultiplier(position: TickerRecord["metadata"]["posit
   return withoutMultiplierError < withMultiplierError ? 1 : priceMultiplier;
 }
 
+/**
+ * The rate a lot's cost converts at when valued in `valuationCurrency`: the
+ * one it was bought at (`costFxRate`), when that rate converts into this very
+ * currency and the lot is held in another. Null otherwise, and the cost
+ * converts at today's rate as its value does.
+ */
+export function lotCostFxRate(
+  position: Pick<TickerPosition, "costFxRate" | "costFxCurrency">,
+  positionCurrency: string,
+  valuationCurrency: string,
+): number | null {
+  const rate = position.costFxRate;
+  const into = position.costFxCurrency?.trim();
+  if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0 || !into) return null;
+  return into === valuationCurrency.trim() && !sameCurrency(positionCurrency, into) ? rate : null;
+}
+
+/** Two currency codes in one currency, its minor units included: GBp is GBP, USX is USD. */
+export function sameCurrency(left: string, right: string): boolean {
+  return heldCurrencyUnit(left).currency === heldCurrencyUnit(right).currency;
+}
+
+/**
+ * Whether a lot's cost, valued in `valuationCurrency`, converts at today's
+ * rate: it is held in another currency and no rate from when it was bought
+ * applies, so its P&L leaves out the currency's move since.
+ */
+export function lotCostAtTodaysRate(
+  position: Pick<TickerPosition, "costFxRate" | "costFxCurrency">,
+  positionCurrency: string,
+  valuationCurrency: string,
+): boolean {
+  return !!positionCurrency.trim() && !sameCurrency(positionCurrency, valuationCurrency)
+    && lotCostFxRate(position, positionCurrency, valuationCurrency) === null;
+}
+
 export function getPortfolioPositionMetrics(
   ticker: TickerRecord,
   activeTab: string | undefined,
@@ -128,6 +164,11 @@ export function getPortfolioPositionMetrics(
     if (!currency) return Number.NaN;
     return valuation ? valuation.convert(value, currency) : currencies.size > 1 ? Number.NaN : value;
   };
+  // A cost converts at the rate the lot was bought at, when it has one into the valuation's currency.
+  const convertCost = (value: number, position: typeof positions[number]) => {
+    const bought = valuation ? lotCostFxRate(position, currencyFor(position), valuation.currency) : null;
+    return bought !== null ? value * bought : convert(value, position);
+  };
   const metrics: PortfolioPositionMetrics = {
     positionCurrency, positionCount: positions.length, hasShorts: false,
     totalShares: 0, totalCost: 0, hasCostBasis: positions.length > 0, priceBasis, signedCost: 0, totalCostUnits: 0,
@@ -169,8 +210,8 @@ export function getPortfolioPositionMetrics(
     metrics.unknownContractSize ||= unknownSize && !Number.isFinite(position.marketValue);
     if (Number.isFinite(contractMultiplier)) metrics.multiplierHint = Math.max(metrics.multiplierHint, contractMultiplier);
     metrics.totalShares += magnitude * direction;
-    metrics.totalCost += convert(cost, position);
-    metrics.signedCost += direction * convert(cost, position);
+    metrics.totalCost += convertCost(cost, position);
+    metrics.signedCost += direction * convertCost(cost, position);
     metrics.totalCostUnits += magnitude * costMultiplier;
     metrics.totalPriceUnits += magnitude * quoteMultiplier * direction;
     metrics.grossPriceUnits += magnitude * quoteMultiplier;
@@ -191,7 +232,7 @@ export function getPortfolioPositionMetrics(
     if (pnl == null || !Number.isFinite(pnl)) metrics.hasBrokerPnl = false;
     else metrics.brokerPnl += convert(pnl, position);
     metrics.pnlLots.push({
-      signedCost: direction * convert(cost, position),
+      signedCost: direction * convertCost(cost, position),
       priceUnits: magnitude * quoteMultiplier * direction,
       direction,
       brokerMarketValue: marketValue != null && Number.isFinite(marketValue) ? convert(marketValue, position) : null,

package/src/portfolio/position-quantity.ts

@@ -0,0 +1,43 @@
+import { resolveAssetDisplayKind } from "../market-data/market/format";
+import type { TickerRecord } from "../types/ticker";
+import { ambiguousNumberMessage, thousandsDotReadings } from "../utils/decimal-comma";
+import { isKnownNonUsListing } from "../utils/sec";
+import { isFuturesTicker } from "./futures-positions";
+import { positionQuantityLabel, type PositionQuantityLabel } from "./mutations";
+
+/** Fund units are issued in fractions wherever the fund is listed. */
+const FRACTIONAL_FUND_TYPES = new Set(["FUND", "MUTUALFUND"]);
+
+/**
+ * Whether a listing is held in whole units: a future's or an option's
+ * contracts, and shares listed outside the US, which trade in whole lots
+ * (THYAO.IS, SAP:XETRA). US shares, which brokers split into fractions,
+ * mutual funds, coins, currencies and bonds may be held in fractions.
+ */
+function tradesInWholeUnits(ticker: TickerRecord): boolean {
+  const kind = resolveAssetDisplayKind({ assetCategory: ticker.metadata.assetCategory });
+  if (isFuturesTicker(ticker) || kind === "contract") return true;
+  const category = ticker.metadata.assetCategory?.trim().toUpperCase().replace(/[\s_-]/g, "") ?? "";
+  const shares = kind === "equity" ? !FRACTIONAL_FUND_TYPES.has(category) : kind === "other" && !category;
+  return shares && isKnownNonUsListing(ticker);
+}
+
+/**
+ * Why a typed size cannot be stored as read: a dot and three digits (`1.250`)
+ * on a listing held in whole units, where it is far likelier the thousands
+ * grouping many locales write (1,250 shares) than a quarter of a share, so the
+ * command asks which, as it does for `1,250`. Null for any other size, and
+ * for a listing that may be held in fractions, where `1.250` is 1.25.
+ */
+export function wholeUnitQuantityProblem(
+  typed: string,
+  ticker: TickerRecord,
+  options: { label?: PositionQuantityLabel; listing?: string } = {},
+): string | null {
+  const reading = thousandsDotReadings(typed);
+  if (!reading || !tradesInWholeUnits(ticker)) return null;
+  const label = options.label ?? positionQuantityLabel(ticker);
+  const listing = options.listing ?? ticker.metadata.ticker;
+  const because = `${listing} trades in whole ${label === "Contracts" ? "contracts" : "shares"}`;
+  return `${label} ${ambiguousNumberMessage(typed, reading, { because })}.`;
+}

package/src/public/__snapshots__/public-api.test.ts.snap

@@ -4,6 +4,7 @@ exports[`the runtime exports of every public subpath are the reviewed ones 1`] =
 {
   ".": [],
   "./broker": [
+    "LOCAL_BROKER_MARKET_DATA",
     "PRESERVED_PASSWORD_HINT",
     "cloudBrokerLink",
     "getBrokerRemoteClient",
@@ -53,6 +54,7 @@ exports[`the runtime exports of every public subpath are the reviewed ones 1`] =
     "CompositeChart",
     "ConfirmDialog",
     "CurveSurface",
+    "DELAYED_SEGMENT",
     "DataTable",
     "DataTableStackView",
     "DataTableView",
@@ -132,6 +134,7 @@ exports[`the runtime exports of every public subpath are the reviewed ones 1`] =
     "curveSlope",
     "curveStrip",
     "curveSurfaceMinRows",
+    "delayedFooterSegment",
     "fieldFrameStyle",
     "fieldGridColumns",
     "fieldGridRows",
@@ -159,6 +162,7 @@ exports[`the runtime exports of every public subpath are the reviewed ones 1`] =
     "sortStackItems",
     "spanAxisFormatter",
     "spanDigits",
+    "splitDelayedStatus",
     "stackedSeries",
     "statGridColumns",
     "statGridRows",
@@ -201,6 +205,7 @@ exports[`the runtime exports of every public subpath are the reviewed ones 1`] =
   ],
   "./market-data": [
     "computeTickerPriceReturns",
+    "createProviderMiss",
     "currencyMinorDigits",
     "formatCompactMarketPriceWithCurrency",
     "formatMarketChangeWithCurrency",

package/src/public/broker.ts

@@ -20,6 +20,14 @@ export type { BrokerRemoteClient } from "../brokers/remote-broker-adapter";
 export type { ResourceStore } from "../data/resource-store";
 export { resolveTickerFinancialsForInstrument } from "../market-data/coordinator";
 
+/**
+ * This host's Cloud sync honors `BrokerAdapter.localMarketData`. A broker whose market data must
+ * not reach Gloom Cloud reads it to tell an older host, which would sync its quotes and where it
+ * still has to ask for Cloud to be off: `import * as broker from "gloomberb/broker"`, then
+ * `broker.LOCAL_BROKER_MARKET_DATA === true`.
+ */
+export const LOCAL_BROKER_MARKET_DATA = true;
+
 /**
  * The app's cached-resource store. Set by the host at startup and cleared on
  * teardown; null before services are constructed.

package/src/public/market-data.ts

@@ -25,6 +25,11 @@ export type {
   AssetDisplayContext, AssetDisplayKind, MarketFormatOptions, StablePriceContext,
 } from "../market-data/market/format";
 
+// How a provider says it has nothing for a symbol, as built-in sources do: the
+// router tries the next provider, does not log it as a failure, and shows the
+// reason where the data would be.
+export { createProviderMiss } from "../sources/provider-errors";
+
 // The coordinator the app loads snapshots through, so a plugin pane that shows
 // its own list of tickers warms the same cache the rest of the app reads.
 export { getSharedMarketDataCoordinator } from "../market-data/coordinator";

package/src/renderers/dom/desktop/control-styles.ts

@@ -35,9 +35,14 @@ export function controlBorderColor(focused = false, active = false, palette: The
  * casts a shadow. The icon button is `.gloom-icon-button` in styles.css.
  */
 export function buttonPalette(
-  props: Pick<ButtonProps, "variant" | "active" | "disabled">,
+  props: Pick<ButtonProps, "variant" | "active" | "disabled" | "tone">,
   palette: ThemeColors = colors,
 ) {
+  if (props.variant === "quiet") return {
+    fg: props.disabled ? palette.textMuted : props.active ? palette.textBright : palette.textDim,
+    bg: props.active ? selectedPanelFill(palette) : "transparent",
+    border: "transparent",
+  };
   if (props.variant === "plain" || props.variant === "ghost") {
     return {
       fg: props.disabled ? palette.textMuted : props.active ? palette.textBright : palette.textDim,
@@ -52,6 +57,7 @@ export function buttonPalette(
       border: controlBorderColour(palette),
     };
   }
+  if (props.tone && props.variant === "primary") return { fg: palette.bg, bg: palette[props.tone], border: props.active ? palette.textBright : palette[props.tone] };
   if (props.active) {
     return {
       fg: palette.selectedText,

package/src/renderers/dom/desktop/controls.tsx

@@ -37,6 +37,7 @@ export function WebButton({
   expanded,
   onPress,
   variant = "secondary",
+  tone,
   disabled = false,
   pending = false,
   active = false,
@@ -49,7 +50,7 @@ export function WebButton({
   title,
 }: ButtonProps) {
   const colors = useThemeColors();
-  const palette = buttonPalette({ variant, active, disabled }, colors);
+  const palette = buttonPalette({ variant, active, disabled, tone }, colors);
   const filled = active || variant === "primary" || variant === "danger";
 
   return (
@@ -261,10 +262,12 @@ const COMFORTABLE_FIELD_HEIGHT = 26;
 
 export function WebTextField({
   label,
+  accessibleLabel,
   value,
   placeholder,
   maxLength,
   focused,
+  disabled = false,
   width,
   inputRef,
   onChange,
@@ -290,6 +293,7 @@ export function WebTextField({
   const renderer = useRendererHost();
   const { nativeContextMenu } = useUiCapabilities();
   const plain = variant === "plain";
+  const well = variant === "well";
   const comfortable = size === "comfortable";
 
   return (
@@ -311,6 +315,7 @@ export function WebTextField({
         alignItems="center"
         backgroundColor={plain ? "transparent" : resolvedBackgroundColor}
         onMouseDown={() => {
+          if (disabled) return;
           onMouseDown?.();
           resolvedInputRef.current?.focus?.();
         }}
@@ -324,12 +329,16 @@ export function WebTextField({
         data-gloom-role="desktop-text-field"
         style={{
           height: comfortable ? COMFORTABLE_FIELD_HEIGHT : undefined,
-          border: plain ? "none" : `1px solid ${controlBorderColor(focused, false, colors)}`,
-          borderRadius: plain ? 0 : CONTROL_RADIUS,
+          border: plain || well ? "none" : `1px solid ${controlBorderColor(focused, false, colors)}`,
+          borderRadius: plain ? 0 : well ? "var(--gloom-radius-sm)" : CONTROL_RADIUS,
+          // A well has no border: focus is the accent along its foot.
+          boxShadow: well && focused ? "inset 0 -2px var(--gloom-accent)" : undefined,
           overflow: "hidden",
         }}
       >
         <Input
+          aria-label={accessibleLabel ?? label}
+          disabled={disabled}
           ref={resolvedInputRef as RefObject<InputRenderable | null>}
           width="100%"
           value={value}
@@ -459,15 +468,18 @@ export function WebMessageComposer({
 }
 
 export function WebSegmentedControl({
+  accessibleLabel,
   options,
   value,
   onChange,
   focused,
   width,
   wrap = false,
+  size = "default",
 }: SegmentedControlProps) {
   const colors = useThemeColors();
   const enabled = options.filter((option) => !option.disabled);
+  const large = size === "large";
   const selectAdjacent = (direction: -1 | 1) => {
     const index = enabled.findIndex((option) => option.value === value);
     const next = enabled[index < 0 ? 0 : (index + direction + enabled.length) % enabled.length];
@@ -476,26 +488,37 @@ export function WebSegmentedControl({
 
   // A segmented choice is a tab strip (the tab rule in styles.css): text, the
   // chosen one bright and bold on the accent underline. One row tall, so it
-  // never bleeds over the pane title or the table header around it.
+  // never bleeds over the pane title or the table header around it. A large
+  // one, such as an order's side, is two rows of blocks that share the width,
+  // the chosen one filled in its tone.
   return (
     <Box
       flexDirection="row"
       flexWrap={wrap ? "wrap" : "nowrap"}
       width={width}
-      height={wrap ? undefined : 1}
+      height={wrap ? undefined : large ? 2 : 1}
       alignItems="stretch"
       role="radiogroup"
+      aria-label={accessibleLabel}
       data-gloom-role="segmented-control"
+      data-size={large ? "large" : undefined}
       data-focused={focused ? "true" : undefined}
+      style={large ? {
+        borderRadius: "var(--gloom-radius-md)",
+        overflow: "hidden",
+        boxShadow: focused ? "0 0 0 2px var(--gloom-accent)" : undefined,
+      } : undefined}
     >
       {options.map((option) => {
         const active = option.value === value;
+        const tone = option.tone ? colors[option.tone] : undefined;
         return (
           <Box
             key={option.value}
             flexDirection="row"
             alignItems="center"
             justifyContent="center"
+            flexGrow={large ? 1 : undefined}
             onMouseDown={() => {
               if (!option.disabled) onChange?.(option.value);
             }}
@@ -503,7 +526,7 @@ export function WebSegmentedControl({
             // after the keyboard has moved on to another pane.
             onClick={(event: { currentTarget: unknown; detail: number }) => releasePointerFocus(event.currentTarget, event.detail)}
             data-gloom-interactive={option.disabled ? undefined : "true"}
-            data-gloom-role="tab-button"
+            data-gloom-role={large ? "segment-block" : "tab-button"}
             data-active={active ? "true" : undefined}
             role="radio"
             aria-checked={active}
@@ -521,9 +544,18 @@ export function WebSegmentedControl({
                 onChange?.(option.value);
               }
             }}
-            style={{
+            style={large ? {
+              height: "100%",
+              cursor: option.disabled ? "default" : "pointer",
+              outline: "none",
+              fontSize: "var(--gloom-type-heading)",
+              fontWeight: "var(--gloom-weight-bold)",
+              background: option.disabled ? "var(--gloom-panel)" : active ? tone ?? colors.selected : "var(--gloom-panel)",
+              color: option.disabled ? colors.textMuted : active ? tone ? colors.bg : colors.selectedText : tone ?? colors.textDim,
+            } : {
               height: wrap ? undefined : "100%",
               cursor: option.disabled ? "default" : "pointer",
+              ...(tone ? { "--tab-fg": tone, "--tab-active-fg": tone } as CSSProperties : {}),
               ...(option.disabled ? { color: colors.textMuted } : {}),
             }}
           >

package/src/renderers/dom/desktop/icons.tsx

@@ -151,6 +151,20 @@ const ICONS: Record<IconName, ReactNode> = {
       <path d="M1.5 5.3h9M4.8 2.5 4.3 5.3 6 10.1l1.7-4.8-.5-2.8" stroke="currentColor" strokeWidth=".9" strokeLinejoin="round" />
     </>
   ),
+  // A clock face at ten past: data that arrives late.
+  clock: (
+    <>
+      <circle cx="6" cy="6" r="4.4" stroke="currentColor" strokeWidth="1.2" />
+      <path d="M6 3.4V6l1.9 1.2" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" strokeLinejoin="round" />
+    </>
+  ),
+  // A pencil, for changing something in place.
+  edit: (
+    <>
+      <path d="M2.2 9.8l.5-2.3 5.4-5.4a1.1 1.1 0 0 1 1.6 0l.2.2a1.1 1.1 0 0 1 0 1.6L4.5 9.3l-2.3.5Z" stroke="currentColor" strokeWidth="1.1" strokeLinejoin="round" />
+      <path d="M7.3 2.9l1.8 1.8" stroke="currentColor" strokeWidth="1.1" />
+    </>
+  ),
   restore: (
     <>
       <rect x="2" y="4" width="6" height="6" rx="0.8" stroke="currentColor" strokeWidth="1.1" />

package/src/renderers/dom/desktop/list-view.tsx

@@ -3,6 +3,7 @@ import { useEffect, useId, useRef, useState, type CSSProperties } from "react";
 import { Box, ScrollBox, Text, type ScrollBoxRenderable } from "../../../ui";
 import { TextAttributes } from "../../../ui";
 import type { ListRowState, ListViewItem, ListViewProps } from "../../../components/ui/list-view";
+import { ListRowLines } from "../../../components/ui/list-row-lines";
 import { hoverBg, type ThemeColors } from "../../../theme/colors";
 import { useThemeColors } from "../../../theme/theme-context";
 import { WEB_CELL_HEIGHT } from "../../../theme/font-scale";
@@ -18,9 +19,12 @@ import {
 function DefaultDesktopRow({
   item,
   selected,
+  stacked,
 }: {
   item: ListViewItem;
   selected: boolean;
+  /** The description on a second line under the label (`rowDescriptions`). */
+  stacked: boolean;
 }) {
   const colors = useThemeColors();
   return (
@@ -28,28 +32,52 @@ function DefaultDesktopRow({
       flexDirection="row"
       justifyContent="space-between"
       width="100%"
+      // A two-line row is taller than its lines: they sit in its middle.
+      height={stacked ? "100%" : undefined}
       minWidth={0}
       alignItems="center"
       style={{ boxSizing: "border-box" }}
     >
-      <Box flexDirection="row" alignItems="center" minWidth={0} flexShrink={1} overflow="hidden">
-        <Text
-          fg={item.color ?? (selected ? colors.text : colors.textDim)}
-          attributes={selected ? TextAttributes.BOLD : 0}
-          style={{
-            // The base text style pins flexShrink to 0, which lets a long
-            // label run under the detail instead of shrinking to an ellipsis.
-            flexShrink: 1,
-            minWidth: 0,
-            maxWidth: "100%",
-            overflow: "hidden",
-            textOverflow: "ellipsis",
-            whiteSpace: "nowrap",
-          }}
+      {stacked ? (
+        <ListRowLines
+          label={item.label}
+          description={item.description}
+          leading={item.leading}
+          labelColor={item.color}
+          labelBold={selected}
+        />
+      ) : (
+        <Box
+          flexDirection="row"
+          alignItems="center"
+          minWidth={0}
+          flexShrink={1}
+          overflow="hidden"
+          style={item.leading !== undefined ? { gap: "var(--gloom-space-sm)" } : undefined}
         >
-          {item.label}
-        </Text>
-      </Box>
+          {item.leading !== undefined && (
+            <Box flexShrink={0} alignItems="center" aria-hidden="true" data-gloom-role="list-row-leading">
+              {item.leading}
+            </Box>
+          )}
+          <Text
+            fg={item.color ?? (selected ? colors.text : colors.textDim)}
+            attributes={selected ? TextAttributes.BOLD : 0}
+            style={{
+              // The base text style pins flexShrink to 0, which lets a long
+              // label run under the detail instead of shrinking to an ellipsis.
+              flexShrink: 1,
+              minWidth: 0,
+              maxWidth: "100%",
+              overflow: "hidden",
+              textOverflow: "ellipsis",
+              whiteSpace: "nowrap",
+            }}
+          >
+            {item.label}
+          </Text>
+        </Box>
+      )}
       {item.detail && (
         <Text fg={colors.textMuted} style={{ flexShrink: 0, marginLeft: 12 }}>
           {item.detail}
@@ -59,6 +87,9 @@ function DefaultDesktopRow({
   );
 }
 
+/** A row with its description under its label: the two lines and a quarter row above and below them. */
+const STACKED_ROW_HEIGHT = 2.5;
+
 const FRAMED_LIST_PADDING_PX = 4;
 /** What a framed list adds above and below its rows: padding and a 1px border on each side. */
 const FRAMED_LIST_CHROME_PX = 2 * (FRAMED_LIST_PADDING_PX + 1);
@@ -84,12 +115,13 @@ export function WebListView({
   renderRow,
   getRowBackgroundColor,
   showSelectedDescription = false,
+  rowDescriptions = false,
   emptyMessage = "Nothing to show.",
   bgColor,
   selectedBgColor,
   hoverBgColor,
   rowGap = 1,
-  rowHeight = 1,
+  rowHeight = rowDescriptions ? STACKED_ROW_HEIGHT : 1,
   surface,
   selection = "frame",
   height,
@@ -242,7 +274,7 @@ export function WebListView({
         >
           {renderRow
             ? renderRow(item, state, index)
-            : <DefaultDesktopRow item={item} selected={selected} />}
+            : <DefaultDesktopRow item={item} selected={selected} stacked={rowDescriptions} />}
         </Box>
       );
     });

package/src/renderers/dom/desktop/menu.tsx

@@ -1,5 +1,5 @@
 /** @jsxImportSource react */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
 import type { HostMenuItem, HostMenuProps } from "../../../ui/host";
 import { CheckboxBox } from "./controls";
 import { WebIcon } from "./icons";
@@ -10,9 +10,12 @@ function selectable(item: HostMenuItem): boolean {
   return item.kind !== "divider" && item.kind !== "heading" && !item.disabled;
 }
 
+const LEADING_STYLE: CSSProperties = { display: "inline-flex", flex: "none", alignItems: "center" };
+
 /** Desktop Menu: the one list every popover menu in the app renders. */
 export function WebMenu({ items, onSelect, selection = "none", title, label, onClose, highlightedId, onHighlight }: HostMenuProps) {
   const enabled = useMemo(() => items.filter(selectable), [items]);
+  const alignLeading = items.find((item) => item.leading !== undefined)?.leading;
   const controlled = highlightedId !== undefined;
   const [ownHighlighted, setOwnHighlighted] = useState<string | null>(
     () => items.find((item) => item.selected && selectable(item))?.id ?? enabled[0]?.id ?? null,
@@ -92,6 +95,12 @@ export function WebMenu({ items, onSelect, selection = "none", title, label, onC
             {(selection === "multi" || toggle) && (
               <CheckboxBox checked={!!item.checked} />
             )}
+            {item.leading !== undefined ? (
+              <span aria-hidden="true" style={LEADING_STYLE}>{item.leading}</span>
+            ) : alignLeading !== undefined ? (
+              // The room another item's artwork takes, so every label starts in one column.
+              <span aria-hidden="true" style={{ ...LEADING_STYLE, visibility: "hidden" }}>{alignLeading}</span>
+            ) : null}
             <span className="gloom-menu-label">
               <span className="gloom-menu-text" style={item.color ? { color: item.color } : undefined}>{item.label}</span>
               {item.description ? <span className="gloom-menu-description">{item.description}</span> : null}