termcast 1.4.1 → 1.6.0

package/src/components/horizontal-bar-graph.tsx

@@ -0,0 +1,279 @@
+/**
+ * HorizontalBarGraph renders multi-series horizontal stacked bars.
+ *
+ * Each row is one category, usually a time bucket. The left chart area grows to
+ * fill available space while the right legend uses only the width needed for
+ * colored series rows and percentages.
+ */
+
+import React, { ReactNode, useMemo } from 'react'
+import { BoxProps } from '@opentui/react'
+import { Color, resolveColor } from 'termcast/src/colors'
+import { getThemePalette, useTheme } from 'termcast/src/theme'
+
+export interface HorizontalBarGraphSeriesProps {
+  /** One value per row/category position. */
+  data: number[]
+  /** Series label shown in the legend. */
+  title?: string
+  /** Override the auto-assigned color. */
+  color?: Color.ColorLike
+}
+
+export interface HorizontalBarGraphProps extends BoxProps {
+  /** Row labels, one per bar position. Usually time buckets. */
+  labels?: string[]
+  /** Maximum chart rows to render. Defaults to all rows. */
+  height?: number
+  /** Character used for bar cells. Matches Histogram by default. */
+  barCharacter?: string
+  /** Show header row. Default true. */
+  showHeader?: boolean
+  /** Show right-side legend. Default true when any series has a title. */
+  showLegend?: boolean
+  /** Max display width for labels; longer labels are truncated. Default 16. */
+  maxLabelWidth?: number
+  /** Header text for the category column. Default "category". */
+  categoryTitle?: string
+  /** Header text for the bar column. Default "distribution". */
+  distributionTitle?: string
+  /** Header text for the legend column. Default "legend". */
+  legendTitle?: string
+  /** HorizontalBarGraph.Series children. */
+  children: ReactNode
+}
+
+interface HorizontalBarGraphType {
+  (props: HorizontalBarGraphProps): any
+  Series: (props: HorizontalBarGraphSeriesProps) => any
+}
+
+function truncateLabel(label: string, maxLabelWidth: number): string {
+  if (label.length <= maxLabelWidth) {
+    return label
+  }
+  return label.slice(0, maxLabelWidth - 1) + '…'
+}
+
+function padRight(value: string, width: number): string {
+  if (value.length >= width) {
+    return value
+  }
+  return value + ' '.repeat(width - value.length)
+}
+
+function padLeft(value: string, width: number): string {
+  if (value.length >= width) {
+    return value
+  }
+  return ' '.repeat(width - value.length) + value
+}
+
+function formatPercentage(value: number, total: number): string {
+  if (total <= 0) {
+    return '0%'
+  }
+  return `${Math.round((value / total) * 100)}%`
+}
+
+const HorizontalBarGraphSeries = (_props: HorizontalBarGraphSeriesProps): any => {
+  return null
+}
+
+const HorizontalBarGraph: HorizontalBarGraphType = (props) => {
+  const theme = useTheme()
+  const {
+    labels = [],
+    height,
+    barCharacter = '╻',
+    showHeader = true,
+    showLegend,
+    maxLabelWidth = 16,
+    categoryTitle = 'category',
+    distributionTitle = 'distribution',
+    legendTitle = 'legend',
+    children,
+    ...rest
+  } = props
+
+  const palette = getThemePalette(theme)
+
+  const seriesList = useMemo<Array<{ data: number[]; color: string; title?: string }>>(() => {
+    const childArray = React.Children.toArray(children)
+    return childArray
+      .filter(React.isValidElement)
+      .map((child, index) => {
+        const childProps = child.props as HorizontalBarGraphSeriesProps
+        return {
+          data: childProps.data,
+          title: childProps.title,
+          color: resolveColor(childProps.color) || palette[index % palette.length]!,
+        }
+      })
+      .filter((series) => {
+        return Array.isArray(series.data)
+      })
+  }, [children, palette])
+
+  const rowCount = useMemo(() => {
+    return Math.max(labels.length, ...seriesList.map((series) => series.data.length), 0)
+  }, [labels, seriesList])
+
+  const rows = useMemo<Array<{ label: string; total: number; values: number[] }>>(() => {
+    return Array.from({ length: rowCount }, (_, rowIndex) => {
+      const values = seriesList.map((series) => {
+        return series.data[rowIndex] || 0
+      })
+      const total = values.reduce((sum, value) => {
+        return sum + value
+      }, 0)
+      return {
+        label: labels[rowIndex] ?? String(rowIndex + 1),
+        total,
+        values,
+      }
+    })
+  }, [labels, rowCount, seriesList])
+
+  const visibleRows = useMemo(() => {
+    return rows.slice(0, height ?? rows.length)
+  }, [height, rows])
+
+  const maxTotal = useMemo(() => {
+    return Math.max(0, ...rows.map((row) => row.total))
+  }, [rows])
+
+  const legendRows = useMemo<Array<{ title: string; color: string; percentage: string; total: number }>>(() => {
+    const grandTotal = rows.reduce((sum, row) => {
+      return sum + row.total
+    }, 0)
+    return seriesList
+      .map((series, seriesIndex) => {
+        const seriesTotal = series.data.reduce((sum, value) => {
+          return sum + value
+        }, 0)
+        return {
+          title: series.title ?? `Series ${seriesIndex + 1}`,
+          color: series.color,
+          percentage: formatPercentage(seriesTotal, grandTotal),
+          total: seriesTotal,
+        }
+      })
+      .filter((row) => {
+        return row.title.length > 0
+      })
+      .sort((a, b) => {
+        return b.total - a.total
+      })
+  }, [rows, seriesList])
+
+  const legendVisible = showLegend ?? seriesList.some((series) => {
+    return Boolean(series.title)
+  })
+
+  if (seriesList.length === 0 || visibleRows.length === 0 || maxTotal === 0) {
+    return null
+  }
+
+  const displayLabels = visibleRows.map((row) => {
+    return truncateLabel(row.label, maxLabelWidth)
+  })
+  const displayCategoryTitle = truncateLabel(categoryTitle, maxLabelWidth)
+  const labelWidth = Math.max(5, displayCategoryTitle.length, ...displayLabels.map((label) => label.length))
+
+  const legendGap = 2
+  const legendTitleWidth = Math.max(6, ...legendRows.map((row) => row.title.length))
+  const legendPercentageWidth = Math.max(3, ...legendRows.map((row) => row.percentage.length))
+  const legendWidth = legendVisible ? legendGap + 2 + legendTitleWidth + 2 + legendPercentageWidth : 0
+  const headerHeight = showHeader ? 2 : 0
+  const chartHeight = headerHeight + visibleRows.length
+
+  return (
+    <box flexDirection="column" width="100%" flexShrink={0} {...rest}>
+      {showHeader && (
+        <>
+          <box flexDirection="row" height={1} flexShrink={0}>
+            <box width={labelWidth + 2} flexShrink={0} overflow="hidden">
+              <text fg={theme.textMuted} wrapMode="none">{padRight(displayCategoryTitle, labelWidth)}  </text>
+            </box>
+            <box flexGrow={1} flexShrink={1} overflow="hidden">
+              <text fg={theme.textMuted} wrapMode="none">{distributionTitle}</text>
+            </box>
+            {legendVisible && (
+              <box width={legendWidth} flexShrink={0} overflow="hidden">
+                <text fg={theme.textMuted} wrapMode="none">{' '.repeat(legendGap)}{legendTitle}</text>
+              </box>
+            )}
+          </box>
+          <box flexDirection="row" height={1} flexShrink={0}>
+            <box width={labelWidth + 2} flexShrink={0} overflow="hidden">
+              <text fg={theme.borderSubtle} wrapMode="none">{'─'.repeat(labelWidth)}  </text>
+            </box>
+            <box flexGrow={1} flexShrink={1} overflow="hidden">
+              <text fg={theme.borderSubtle} wrapMode="none">{'─'.repeat(200)}</text>
+            </box>
+            {legendVisible && (
+              <box width={legendWidth} flexShrink={0} overflow="hidden">
+                <text fg={theme.borderSubtle} wrapMode="none">{' '.repeat(legendGap)}{'─'.repeat(legendWidth - legendGap)}</text>
+              </box>
+            )}
+          </box>
+        </>
+      )}
+
+      <box flexDirection="row" height={chartHeight - headerHeight} flexShrink={0}>
+        <box flexDirection="column" flexGrow={1} flexShrink={1} overflow="hidden">
+          {visibleRows.map((row, rowIndex) => {
+            return (
+              <box key={row.label} flexDirection="row" height={1} flexShrink={0} overflow="hidden">
+                <box width={labelWidth + 2} flexShrink={0} overflow="hidden">
+                  <text fg={theme.text} wrapMode="none">
+                    {padRight(displayLabels[rowIndex]!, labelWidth)}  
+                  </text>
+                </box>
+                <box flexDirection="row" flexGrow={1} flexShrink={1} overflow="hidden">
+                  {row.values.map((value, seriesIndex) => {
+                    if (value <= 0) {
+                      return null
+                    }
+                    const series = seriesList[seriesIndex]!
+                    return (
+                      <box key={seriesIndex} flexGrow={value} flexBasis={0} flexShrink={1} overflow="hidden">
+                        <box position="absolute" width="100%" height="100%" overflow="hidden">
+                          <text fg={series.color} wrapMode="none">{barCharacter.repeat(200)}</text>
+                        </box>
+                      </box>
+                    )
+                  })}
+                  {maxTotal > row.total && (
+                    <box flexGrow={maxTotal - row.total} flexBasis={0} flexShrink={1} />
+                  )}
+                </box>
+              </box>
+            )
+          })}
+        </box>
+
+        {legendVisible && (
+          <box flexDirection="column" width={legendWidth} flexShrink={0} overflow="hidden">
+            {legendRows.map((row) => {
+              return (
+                <box key={row.title} height={1} flexShrink={0} flexDirection="row" overflow="hidden">
+                  <box width={legendGap} flexShrink={0} />
+                  <text fg={row.color} wrapMode="none">● </text>
+                  <text fg={theme.textMuted} wrapMode="none">
+                    {padRight(row.title, legendTitleWidth)}  {padLeft(row.percentage, legendPercentageWidth)}
+                  </text>
+                </box>
+              )
+            })}
+          </box>
+        )}
+      </box>
+    </box>
+  )
+}
+
+HorizontalBarGraph.Series = HorizontalBarGraphSeries
+
+export { HorizontalBarGraph }

package/src/components/list.tsx

@@ -6,7 +6,7 @@ import {
   TextareaRenderable,
 } from '@opentui/core'
 import type { MouseEvent as OpenTUIMouseEvent } from '@opentui/core'
-import { useKeyboard, flushSync } from '@opentui/react'
+import { useKeyboard, flushSync, useTerminalDimensions } from '@opentui/react'
 import React, {
     ReactElement,
     ReactNode,
@@ -225,8 +225,17 @@ function CurrentItemDetail(props: {
 }): any {
   const theme = useTheme()
   const descendantsMap = useListDescendantsRerender()
-
-  if (!props.isShowingDetail) return null
+  const boxRef = React.useRef<BoxRenderable>(null)
+  // Grow-only height ratchet: once the detail panel reaches a certain height,
+  // it never shrinks below that. This prevents the footer from jumping up
+  // when navigating from a tall detail to a short one.
+  const maxHeightRef = React.useRef(0)
+
+  if (!props.isShowingDetail) {
+    // Reset ratchet when detail is hidden so next show starts fresh
+    maxHeightRef.current = 0
+    return null
+  }
 
   const currentItem = Object.values(descendantsMap)
     .find((item) => item.index === props.selectedIndex)
@@ -236,6 +245,14 @@ function CurrentItemDetail(props: {
 
   return (
     <box
+      ref={boxRef}
+      minHeight={maxHeightRef.current || undefined}
+      onSizeChange={() => {
+        const h = boxRef.current?.height ?? 0
+        if (h > maxHeightRef.current) {
+          maxHeightRef.current = h
+        }
+      }}
       style={{
         width: '50%',
         paddingLeft: 1,
@@ -374,6 +391,8 @@ export interface DropdownProps extends SearchBarInterface, CommonProps {
   storeValue?: boolean
   value?: string
   defaultValue?: string
+  /** Override the text shown in the search bar for the active selection. When set, this is displayed instead of the selected item's title. Useful for managed state where the display label doesn't match any dropdown item. */
+  displayValue?: string
   onChange?: (newValue: string) => void
   children?: ReactNode
 }
@@ -404,6 +423,13 @@ export interface ListProps
   searchBarPlaceholder?: string
   selectedItemId?: string
   isShowingDetail?: boolean
+  /**
+   * Minimum terminal width in columns required to show the detail panel.
+   * When the terminal is narrower than this value, the detail panel is
+   * automatically hidden even if `isShowingDetail` is true.
+   * @default 80
+   */
+  detailMinWidth?: number
   /**
     * Controls the vertical spacing of list items.
     * - 'default': Single-line items with title and subtitle on same row
@@ -946,9 +972,9 @@ function ListItemRow(props: {
             <text flexShrink={0} fg={active ? theme.background : theme.text} attributes={active ? TextAttributes.BOLD : undefined} selectable={false} wrapMode="none">{active ? '›' : ' '}</text>
             {icon && <text flexShrink={0} fg={active ? theme.background : iconColor || theme.text} selectable={false} wrapMode="none">{getIconEmoji(icon)} </text>}
             <text
-              flexShrink={0}
+              flexShrink={1}
+              truncate
               fg={active ? theme.background : theme.text}
-
               attributes={TextAttributes.BOLD}
               selectable={false}
               wrapMode="none"
@@ -969,9 +995,10 @@ function ListItemRow(props: {
         </box>
         {/* Line 2: subtitle indented to align with title */}
         {subtitle && (
-          <box style={{ paddingLeft: subtitleIndent }}>
+          <box style={{ paddingLeft: subtitleIndent, overflow: 'hidden' }}>
             <text
-              flexShrink={0}
+              flexShrink={1}
+              truncate
               fg={active ? theme.background : theme.text}
               selectable={false}
               wrapMode="none"
@@ -1006,11 +1033,12 @@ function ListItemRow(props: {
       onMouseDown={handleMouseDown}
     >
       <box style={{ flexDirection: 'row', flexGrow: 1, flexShrink: 1, overflow: 'hidden', gap: 1 }}>
-        <box style={{ flexDirection: 'row', flexShrink: 0 }}>
+        <box style={{ flexDirection: 'row', flexShrink: 1, overflow: 'hidden' }}>
           <text flexShrink={0} fg={active ? theme.background : theme.text} attributes={active ? TextAttributes.BOLD : undefined} selectable={false} wrapMode="none">{active ? '›' : ' '}</text>
           {icon && <text flexShrink={0} fg={active ? theme.background : iconColor || theme.text} selectable={false} wrapMode="none">{getIconEmoji(icon)} </text>}
           <text
-            flexShrink={0}
+            flexShrink={1}
+            truncate
             fg={active ? theme.background : theme.text}
             attributes={active ? TextAttributes.BOLD : undefined}
             selectable={false}
@@ -1021,7 +1049,8 @@ function ListItemRow(props: {
         </box>
         {subtitle && (
           <text
-            flexShrink={0}
+            flexShrink={3}
+            truncate
             fg={active ? theme.background : theme.textMuted}
             selectable={false}
             wrapMode="none"
@@ -1055,6 +1084,7 @@ export const List: ListType = (props) => {
     isLoading,
     navigationTitle,
     isShowingDetail,
+    detailMinWidth = 80,
     selectedItemId,
     searchBarAccessory,
     logo,
@@ -1065,6 +1095,9 @@ export const List: ListType = (props) => {
   } = props
 
   const theme = useTheme()
+  const { width: terminalWidth } = useTerminalDimensions()
+  const effectiveIsShowingDetail = isShowingDetail && terminalWidth >= detailMinWidth
+
   const currentStackSelectedListIndex = useStore((state) => {
     const stack = state.navigationStack
     const currentItem = stack[stack.length - 1]
@@ -1257,14 +1290,14 @@ export const List: ListType = (props) => {
       setSelectedIndex: setSelectedIndexWithPersistence,
       searchText,
       isFiltering: isFilteringEnabled,
-      isShowingDetail,
+      isShowingDetail: effectiveIsShowingDetail,
       customEmptyViewRef,
       isLoading,
       hasDropdown: !!searchBarAccessory,
       spacingMode,
       accessoryTagWidths: accessoryTagsLayout,
     }),
-    [isDropdownOpen, selectedIndex, searchText, isFilteringEnabled, isShowingDetail, isLoading, searchBarAccessory, spacingMode, accessoryTagsLayout],
+    [isDropdownOpen, selectedIndex, searchText, isFilteringEnabled, effectiveIsShowingDetail, isLoading, searchBarAccessory, spacingMode, accessoryTagsLayout],
   )
 
   // Handle selectedItemId prop changes (before paint to avoid flash)
@@ -1351,6 +1384,46 @@ export const List: ListType = (props) => {
     }
   }
 
+  // Trigger pagination when the user mouse-scrolls near the bottom of the list.
+  // Only fires on scroll-down so scrolling up near the bottom doesn't spuriously
+  // re-trigger onLoadMore. Uses queueMicrotask because opentui calls onMouseScroll
+  // before ScrollBox.onMouseEvent updates scrollTop in the same call stack;
+  // a microtask runs after the synchronous handler chain finishes.
+  const checkScrollPagination = (event: OpenTUIMouseEvent) => {
+    if (event.scroll?.direction !== 'down') return
+
+    queueMicrotask(() => {
+      const scrollBox = scrollBoxRef.current
+      if (!scrollBox || !props.pagination?.hasMore) return
+
+      // Reset pagination lock when new items arrive (same logic as in move())
+      const items = Object.values(descendantsContext.map.current)
+        .filter((item) => item.index !== -1 && item.props?.visible !== false)
+      if (items.length !== prevItemCountRef.current) {
+        prevItemCountRef.current = items.length
+        paginationCalledRef.current = false
+      }
+
+      if (paginationCalledRef.current) return
+
+      const scrollTop = scrollBox.scrollTop || 0
+      const viewportHeight = scrollBox.viewport?.height || 0
+      const contentHeight = scrollBox.scrollHeight || 0
+
+      // Nothing to paginate if content fits in viewport
+      if (contentHeight <= viewportHeight) return
+
+      // Trigger when within 20% of the bottom (or 3 rows, whichever is larger)
+      const threshold = Math.max(3, Math.floor(viewportHeight * 0.2))
+      const distanceFromBottom = contentHeight - (scrollTop + viewportHeight)
+
+      if (distanceFromBottom <= threshold) {
+        paginationCalledRef.current = true
+        props.pagination.onLoadMore()
+      }
+    })
+  }
+
   const move = (direction: -1 | 1) => {
     // Get all visible items
     const items = Object.values(descendantsContext.map.current)
@@ -1607,7 +1680,8 @@ export const List: ListType = (props) => {
         return
       }
 
-      // Ctrl+d for half-page down, Ctrl+u for half-page up
+      // Ctrl+d / Ctrl+u for half-page down/up
+      // Ctrl+f / Ctrl+b for full-page down/up
       if (evt.ctrl && evt.name === 'd') {
         const viewportHeight = scrollBoxRef.current?.viewport?.height || 20
         moveByN(Math.floor(viewportHeight / 2))
@@ -1620,6 +1694,18 @@ export const List: ListType = (props) => {
         evt.stopPropagation()
         return
       }
+      if (evt.ctrl && evt.name === 'f') {
+        const viewportHeight = scrollBoxRef.current?.viewport?.height || 20
+        moveByN(viewportHeight)
+        evt.stopPropagation()
+        return
+      }
+      if (evt.ctrl && evt.name === 'b') {
+        const viewportHeight = scrollBoxRef.current?.viewport?.height || 20
+        moveByN(-viewportHeight)
+        evt.stopPropagation()
+        return
+      }
 
       // / to enter search mode
       if (evt.sequence === '/' && !evt.ctrl && !evt.meta) {
@@ -1794,14 +1880,15 @@ export const List: ListType = (props) => {
           {/* Main content area with optional detail view */}
           <box style={{ flexDirection: 'row', flexGrow: 1, flexShrink: 1 }}>
             {/* List content - render children which will register themselves */}
-            <box style={{ width: isShowingDetail ? '50%' : '100%', flexGrow: 1, flexShrink: 1, flexDirection: 'column' }}>
+            <box style={{ width: effectiveIsShowingDetail ? '50%' : '100%', flexGrow: 1, flexShrink: 1, flexDirection: 'column' }}>
               {/* Scrollable list items */}
               <ScrollBox
                 ref={scrollBoxRef}
                 focused={false}
                 flexGrow={1}
                 flexShrink={1}
-                minHeight={6}
+                minHeight={10}
+                onMouseScroll={checkScrollPagination}
                 style={{
                   rootOptions: {
                     backgroundColor: undefined,
@@ -1831,7 +1918,7 @@ export const List: ListType = (props) => {
             {/* Detail panel on the right */}
             <CurrentItemDetail
               selectedIndex={selectedIndex}
-              isShowingDetail={isShowingDetail}
+              isShowingDetail={effectiveIsShowingDetail}
             />
           </box>
         </box>
@@ -1985,8 +2072,7 @@ const ListItem: ListItemType = (props) => {
     }
   }
 
-  // Don't show accessories if we're showing detail
-  const showAccessories = !props.detail && props.accessories
+  const showAccessories = Boolean(props.accessories)
 
   // Get icon string and color from props.icon (can be string or object with value/tintColor)
   const { iconValue, iconColor } = (() => {
@@ -2127,9 +2213,9 @@ const ListDropdown: ListDropdownType = (props) => {
 
   const { isDropdownOpen, setIsDropdownOpen } = listContext
 
-  const setDropdownSelection = (props: { value: string; title: string }) => {
-    setDropdownState({ value: props.value, title: props.title })
-    useStore.setState({ dropdownFooterLabel: props.title || 'dropdown' })
+  const setDropdownSelection = (selectionProps: { value: string; title: string }) => {
+    setDropdownState({ value: selectionProps.value, title: selectionProps.title })
+    useStore.setState({ dropdownFooterLabel: props.displayValue ?? (selectionProps.title || 'dropdown') })
   }
   // Store both value and title together
   const [dropdownState, setDropdownState] = useState<{
@@ -2168,7 +2254,7 @@ const ListDropdown: ListDropdownType = (props) => {
 
     if (!valueToUse) {
       useStore.setState({
-        dropdownFooterLabel: dropdownState.title || 'dropdown',
+        dropdownFooterLabel: props.displayValue ?? (dropdownState.title || 'dropdown'),
       })
       return
     }
@@ -2189,8 +2275,8 @@ const ListDropdown: ListDropdownType = (props) => {
       return
     }
 
-    useStore.setState({ dropdownFooterLabel: title || 'dropdown' })
-  }, [props.value]) // Run when props.value changes and on mount
+    useStore.setState({ dropdownFooterLabel: props.displayValue ?? (title || 'dropdown') })
+  }, [props.value, props.displayValue]) // Run when props.value or displayValue changes and on mount
 
   const dropdownContextValue = useMemo<DropdownContextValue>(
     () => ({
@@ -2242,8 +2328,8 @@ const ListDropdown: ListDropdownType = (props) => {
     }
   }, [isDropdownOpen, props.children])
 
-  // Display the title from our state
-  const displayValue = dropdownState.title || 'All'
+  // Display the title from our state, or use the caller's override
+  const displayValue = props.displayValue ?? (dropdownState.title || 'All')
   const openDropdownIfClosed = () => {
     if (!isDropdownOpen) {
       listContext.openDropdown()