@trendr/core 0.2.0 → 0.2.2

package/README.md

@@ -6,14 +6,18 @@
 </pre>
 
 
-JSX components, signals, per-cell diffing and flexbox without React and Yoga. Terminals are character grids, not DOM trees. Why reconcile a virtual DOM to write escape sequences?
+JSX components, signals, per-cell diffing and flexbox without React and [Yoga](https://github.com/facebook/yoga/issues/1859). Terminals are character grids, not DOM trees. Why reconcile a virtual DOM to write escape sequences?
 
 4-16x faster frame times and 580x less I/O per render than popular TUI frameworks. No dependencies. [benchmarks](bench/README.md)
 
-https://github.com/user-attachments/assets/70c91ab3-659a-4bb0-939a-961dcfbaba61
+https://github.com/user-attachments/assets/6e84bb4b-a99e-46f2-a235-1ee4be62c0ae
 
 ## Usage
 
+```bash
+npm i @trendr/core
+```
+
 Requires esbuild (or similar) for JSX transformation.
 
 ```json
@@ -208,10 +212,11 @@ useHotkey('alt+enter', () => submit(), { when: () => isFocused })
 
 ### useLayout
 
-Returns the component's computed layout rectangle.
+Returns a live reference to the component's computed layout rectangle. Values update in-place each frame, including after terminal resize.
 
 ```jsx
-const { x, y, width, height } = useLayout()
+const layout = useLayout()
+// layout.x, layout.y, layout.width, layout.height, layout.contentHeight
 ```
 
 ### useResize
@@ -286,12 +291,14 @@ const stream = useStdout() // the output stream (process.stdout or custom)
 Forces a full repaint. Useful after spawning an external process (e.g. `$EDITOR`).
 
 ```jsx
+import { useRepaint, useStdout, exitAltScreen, showCursor, altScreen, hideCursor } from '@trendr/core'
+
 const repaint = useRepaint()
+const stdout = useStdout()
 
-// leave alt screen, spawn editor, re-enter, repaint
-stdout.write('\x1b[?1049l\x1b[?25h')
+stdout.write(exitAltScreen + showCursor)
 execSync(`${process.env.EDITOR} ${file}`, { stdio: 'inherit' })
-stdout.write('\x1b[?1049h\x1b[?25l')
+stdout.write(altScreen + hideCursor)
 repaint()
 ```
 
@@ -437,6 +444,8 @@ Scrollable list with keyboard navigation.
   onSelect={setIndex}
   focused={fm.is('list')}
   scrollbar={true}          // default false
+  scrolloff={2}             // items of margin from edges when scrolling (default 2)
+  interactive={true}        // handle keyboard input (default: same as focused)
   header={<text>title</text>}
   headerHeight={1}          // default 1, rows the header occupies
   renderItem={(item, { selected, index, focused }) => (
@@ -463,6 +472,47 @@ Scrollable list with keyboard navigation.
 
 Keys: j/k or up/down, g/G for top/bottom, ctrl-d/u half page, ctrl-f/b full page, pageup/pagedown.
 
+### PickList
+
+Used in [pick-list](examples/pick-list.jsx)
+
+Filterable list with live search. Text input at the top filters a scrollable list below. Navigate the list with up/down or ctrl-n/ctrl-p while typing.
+
+```jsx
+<PickList
+  items={data}
+  focused={fm.is('search')}
+  placeholder="search..."
+  onSelect={item => {}}       // Enter on highlighted item
+  onCancel={() => {}}          // Escape
+  onChange={query => {}}       // every keystroke in the filter
+  clearOnSelect={false}        // reset filter on select (default false)
+  scrollbar={true}             // default false
+  scrolloff={2}                // items of margin from edges (default 2, inherited from List)
+  gap={1}                      // space between input and list (default 0)
+  filter={(query, item) => {}} // custom filter (default: case-insensitive includes)
+/>
+```
+
+Multi-row items with `renderItem`, `itemHeight`, and `itemGap`:
+
+```jsx
+<PickList
+  items={packages}
+  itemHeight={3}
+  itemGap={1}
+  renderItem={(pkg, { selected, focused }) => (
+    <box style={{ flexDirection: 'column', bg: selected ? accent : null, paddingX: 1 }}>
+      <text style={{ bold: true }}>{pkg.name}</text>
+      <text style={{ color: 'gray' }}>{pkg.desc}</text>
+      <text style={{ color: 'yellow' }}>{pkg.downloads}</text>
+    </box>
+  )}
+/>
+```
+
+Keys: type to filter, up/down or ctrl-n/ctrl-p to navigate, enter to select, escape to cancel. All bash-style editing keys work (ctrl-a/e/u/k/w).
+
 ### Table
 
 Used in [components](examples/components.jsx), [custom-table](examples/custom-table.jsx)

package/index.js

@@ -16,6 +16,7 @@ export { Modal } from './src/modal.js'
 export { Radio } from './src/radio.js'
 export { Button } from './src/button.js'
 export { ScrollableText } from './src/scrollable-text.js'
+export { PickList } from './src/pick-list.js'
 export { ScrollBox } from './src/scroll-box.js'
 export { SplitPane } from './src/split-pane.js'
 export { Task } from './src/task.js'
@@ -24,5 +25,6 @@ export { useFocus } from './src/focus.js'
 export { useHotkey } from './src/hotkey.js'
 export { useToast } from './src/toast.js'
 export { Fragment } from './src/element.js'
+export { altScreen, exitAltScreen, showCursor, hideCursor, clearScreen, clearLine } from './src/ansi.js'
 export { animated, useAnimated, spring, ease, decay } from './src/animation.js'
 export { linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeOutElastic, easeOutBounce } from './src/animation.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trendr/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "direct-mode TUI renderer with JSX, signals, and per-cell diffing",
   "license": "MIT",
   "type": "module",
@@ -43,6 +43,8 @@
     "progress": "node esbuild.config.js && node dist/progress.js",
     "shimmer": "node esbuild.config.js && node dist/shimmer.js",
     "spinner": "node esbuild.config.js && node dist/spinner.js",
+    "pick-list": "node esbuild.config.js && node dist/pick-list.js",
+    "table-demo": "node esbuild.config.js && node dist/table-demo.js",
     "demo": "node esbuild.config.js && node demo/server.js",
     "demo:build": "node esbuild.config.js"
   },

package/src/list.js

@@ -2,9 +2,10 @@ import { jsx, jsxs } from '../jsx-runtime.js'
 import { createSignal } from './signal.js'
 import { useInput, useMouse, useLayout, useTheme, useScrollDrag } from './hooks.js'
 
-export function List({ items, selected: selectedProp, onSelect, renderItem, header, headerHeight = 1, focused = true, itemHeight = 1, scrollbar = false, stickyHeader = false, gap = 0 }) {
+export function List({ items, selected: selectedProp, onSelect, renderItem, header, headerHeight = 1, focused = true, interactive = focused, itemHeight = 1, scrollbar = false, stickyHeader = false, gap = 0, scrolloff = 2 }) {
   const { accent = 'cyan' } = useTheme()
   const [selectedInternal, setSelectedInternal] = createSignal(0)
+  const [scrollState, setScrollState] = createSignal(0)
   const layout = useLayout()
 
   const selected = selectedProp ?? selectedInternal()
@@ -29,7 +30,7 @@ export function List({ items, selected: selectedProp, onSelect, renderItem, head
   const maxOffset = Math.max(0, scrollContentH - scrollViewH)
 
   useInput(({ key, ctrl }) => {
-    if (!focused) return
+    if (!interactive) return
 
     const len = items.length
     if (len === 0) return
@@ -93,11 +94,12 @@ export function List({ items, selected: selectedProp, onSelect, renderItem, head
 
   let scrollOffset = 0
   if (scrollViewH > 0 && scrollContentH > scrollViewH) {
-    const centered = itemTop - Math.floor((scrollViewH - avgH) / 2)
-    scrollOffset = Math.max(0, Math.min(maxOffset, centered))
-    if (itemTop < scrollOffset) scrollOffset = itemTop
-    if (itemBottom > scrollOffset + scrollViewH) scrollOffset = itemBottom - scrollViewH
+    const margin = scrolloff * avgH
+    scrollOffset = scrollState()
+    if (itemTop - margin < scrollOffset) scrollOffset = itemTop - margin
+    if (itemBottom + margin > scrollOffset + scrollViewH) scrollOffset = itemBottom + margin - scrollViewH
     scrollOffset = Math.max(0, Math.min(maxOffset, Math.round(scrollOffset)))
+    if (scrollOffset !== scrollState()) setScrollState(scrollOffset)
   }
 
   const scrollChildren = []

package/src/modal.js

@@ -2,7 +2,7 @@ import { jsx } from '../jsx-runtime.js'
 import { useInput, useTheme } from './hooks.js'
 import { registerOverlay } from './renderer.js'
 
-export function Modal({ open, onClose, title, children, width: w = 40 }) {
+export function Modal({ open, onClose, title, children, width: w = 40, border = 'round' }) {
   const { accent = 'cyan' } = useTheme()
 
   useInput((event) => {
@@ -18,7 +18,7 @@ export function Modal({ open, onClose, title, children, width: w = 40 }) {
   const content = jsx('box', {
     style: {
       width: w,
-      border: 'round',
+      border,
       borderColor: accent,
       flexDirection: 'column',
       paddingX: 1,

package/src/pick-list.js

@@ -0,0 +1,204 @@
+import { jsx, jsxs } from '../jsx-runtime.js'
+import { createSignal } from './signal.js'
+import { useInput, useLayout, useTheme, useCursor } from './hooks.js'
+import { List } from './list.js'
+
+export function PickList({ items, onSelect, onCancel, onChange, focused = true, placeholder = 'search...', filter: filterFn, renderItem, maxVisible = 10, scrollbar = false, scrolloff = 0, itemHeight = 1, itemGap = 0, gap = 0, clearOnSelect = false, style: userStyle, cursor: cursorProp }) {
+  const { accent = 'cyan' } = useTheme()
+  const defaults = {
+    borderColor: accent,
+    cursorBg: accent,
+    cursorTextColor: 'black',
+    color: null,
+  }
+  const s = { ...defaults, ...userStyle }
+
+  const [query, setQuery] = createSignal('')
+  const [textCursor, setTextCursor] = createSignal(0)
+  const [listCursor, setListCursor] = createSignal(0)
+  const layout = useLayout()
+  const { cursorStyle, reset: resetBlink } = useCursor(cursorProp, focused)
+
+  const defaultFilter = (q, item) => {
+    const label = typeof item === 'string' ? item : (item.label ?? item.name ?? '')
+    return label.toLowerCase().includes(q.toLowerCase())
+  }
+
+  const match = filterFn ?? defaultFilter
+
+  const q = query()
+  const filtered = q ? items.filter(item => match(q, item)) : items
+
+  let cursor = listCursor()
+  if (cursor >= filtered.length) cursor = Math.max(0, filtered.length - 1)
+  if (cursor !== listCursor()) setListCursor(cursor)
+
+  function updateText(v, c) {
+    setQuery(v)
+    setTextCursor(c)
+    setListCursor(0)
+    if (onChange) onChange(v)
+  }
+
+  useInput((event) => {
+    if (!focused) return
+
+    const { key, raw, ctrl } = event
+    const len = filtered.length
+
+    if (key === 'up' || (ctrl && raw === '\x10')) {
+      if (len > 0) setListCursor(c => Math.max(0, c - 1))
+      event.stopPropagation()
+      return
+    }
+    if (key === 'down' || (ctrl && raw === '\x0e')) {
+      if (len > 0) setListCursor(c => Math.min(len - 1, c + 1))
+      event.stopPropagation()
+      return
+    }
+    if (ctrl && key === 'u') { if (len > 0) setListCursor(c => Math.max(0, c - 5)); event.stopPropagation(); return }
+    if (ctrl && key === 'd') { if (len > 0) setListCursor(c => Math.min(len - 1, c + 5)); event.stopPropagation(); return }
+    if (ctrl && key === 'b') { if (len > 0) setListCursor(c => Math.max(0, c - 10)); event.stopPropagation(); return }
+    if (ctrl && key === 'f') { if (len > 0) setListCursor(c => Math.min(len - 1, c + 10)); event.stopPropagation(); return }
+    if (key === 'pageup') { if (len > 0) setListCursor(c => Math.max(0, c - 10)); event.stopPropagation(); return }
+    if (key === 'pagedown') { if (len > 0) setListCursor(c => Math.min(len - 1, c + 10)); event.stopPropagation(); return }
+
+    if (key === 'return') {
+      if (filtered.length > 0 && onSelect) {
+        onSelect(filtered[cursor])
+        if (clearOnSelect) updateText('', 0)
+        event.stopPropagation()
+      }
+      return
+    }
+
+    if (key === 'escape') {
+      if (onCancel) {
+        onCancel()
+        event.stopPropagation()
+      }
+      return
+    }
+
+    resetBlink()
+    const v = query()
+    const c = textCursor()
+
+    if (key === 'backspace') {
+      if (c > 0) updateText(v.slice(0, c - 1) + v.slice(c), c - 1)
+      event.stopPropagation()
+      return
+    }
+
+    if (key === 'delete') {
+      if (c < v.length) updateText(v.slice(0, c) + v.slice(c + 1), c)
+      event.stopPropagation()
+      return
+    }
+
+    if (key === 'left') { setTextCursor(Math.max(0, c - 1)); event.stopPropagation(); return }
+    if (key === 'right') { setTextCursor(Math.min(v.length, c + 1)); event.stopPropagation(); return }
+
+    if (key === 'home' || (ctrl && raw === '\x01')) { setTextCursor(0); event.stopPropagation(); return }
+    if (key === 'end' || (ctrl && raw === '\x05')) { setTextCursor(v.length); event.stopPropagation(); return }
+
+    if (ctrl && raw === '\x15') { updateText(v.slice(c), 0); event.stopPropagation(); return }
+    if (ctrl && raw === '\x0b') { updateText(v.slice(0, c), c); event.stopPropagation(); return }
+
+    if (ctrl && raw === '\x17') {
+      const before = v.slice(0, c)
+      const after = v.slice(c)
+      const trimmed = before.replace(/\S+\s*$/, '')
+      updateText(trimmed + after, trimmed.length)
+      event.stopPropagation()
+      return
+    }
+
+    if (!ctrl && raw.length === 1 && raw >= ' ') {
+      updateText(v.slice(0, c) + raw + v.slice(c), c + raw.length)
+      event.stopPropagation()
+    }
+  })
+
+  // text input rendering
+  const v = query()
+  const tc = textCursor()
+  const w = layout.width || 0
+  const cs = cursorStyle()
+
+  let inputEl
+  if (!v && placeholder && !focused) {
+    inputEl = jsx('text', { style: { color: 'gray' }, children: placeholder })
+  } else if (!v && placeholder && focused) {
+    inputEl = jsxs('box', {
+      style: { flexDirection: 'row', height: 1, minHeight: 1 },
+      children: [
+        jsx('text', { style: cs ? { ...cs, color: cs.color ?? 'gray' } : { inverse: true, color: 'gray' }, children: placeholder[0] }),
+        placeholder.length > 1 && jsx('text', { style: { color: 'gray' }, children: placeholder.slice(1) }),
+      ],
+    })
+  } else {
+    const contentWidth = v.length + 1
+    const needsScroll = w > 0 && contentWidth > w
+
+    if (!needsScroll) {
+      const cursorChar = v[tc] || ' '
+      inputEl = jsxs('box', {
+        style: { flexDirection: 'row', height: 1, minHeight: 1 },
+        children: [
+          v.slice(0, tc) && jsx('text', { children: v.slice(0, tc) }),
+          jsx('text', { style: cs ?? {}, children: cursorChar }),
+          v.slice(tc + 1) && jsx('text', { children: v.slice(tc + 1) }),
+        ],
+      })
+    } else {
+      let scrollStart = 0
+      if (tc >= w) scrollStart = tc - w + 1
+      const visible = v.slice(scrollStart, scrollStart + w)
+      const cursorInView = tc - scrollStart
+      const before = visible.slice(0, cursorInView)
+      const cursorChar = visible[cursorInView] || ' '
+      const after = visible.slice(cursorInView + 1)
+
+      inputEl = jsxs('box', {
+        style: { flexDirection: 'row', height: 1, minHeight: 1 },
+        children: [
+          before && jsx('text', { children: before }),
+          jsx('text', { style: cs ?? {}, children: cursorChar }),
+          after && jsx('text', { children: after }),
+        ],
+      })
+    }
+  }
+
+  const defaultRenderItem = (item, { selected: isCursor, focused: isFocused }) => {
+    const label = typeof item === 'string' ? item : (item.label ?? item.name ?? String(item))
+    return jsx('box', {
+      style: { bg: isCursor ? (isFocused ? s.cursorBg : 'gray') : null },
+      children: jsx('text', {
+        style: { color: isCursor ? s.cursorTextColor : s.color },
+        children: ` ${label}`,
+      }),
+    })
+  }
+
+  const listRenderItem = renderItem ?? defaultRenderItem
+
+  const list = jsx(List, {
+    items: filtered,
+    selected: cursor,
+    onSelect: setListCursor,
+    focused,
+    interactive: false,
+    itemHeight,
+    gap: itemGap,
+    scrollbar,
+    scrolloff,
+    renderItem: listRenderItem,
+  })
+
+  return jsxs('box', {
+    style: { flexDirection: 'column', flexGrow: 1, gap },
+    children: [inputEl, list],
+  })
+}

package/src/renderer.js

@@ -336,16 +336,39 @@ function paintTree(node, buf, clip, offset, prevBuf) {
   }
 }
 
-function extractText(node) {
+function extractText(node, parentCtx) {
   if (node == null || node === true || node === false) return ''
   if (typeof node === 'string') return node
   if (typeof node === 'number') return String(node)
+
   const children = node.props?.children
   if (children == null || children === true || children === false) return ''
-  if (typeof children === 'string') return children
-  if (typeof children === 'number') return String(children)
-  if (Array.isArray(children)) return children.map(c => extractText(c)).join('')
-  return ''
+  if (typeof children === 'string' && !node.props?.style) return children
+  if (typeof children === 'number' && !node.props?.style) return String(children)
+
+  const style = node.props?.style
+  const ownAttrs = style ? resolveAttrs(style) : 0
+  const hasOwnStyle = style && (style.color != null || style.bg != null || ownAttrs)
+
+  const myCtx = hasOwnStyle ? {
+    fg: style.color ?? parentCtx?.fg ?? null,
+    bg: style.bg ?? parentCtx?.bg ?? null,
+    attrs: ownAttrs || parentCtx?.attrs || 0,
+  } : (parentCtx || null)
+
+  let inner
+  if (typeof children === 'string') inner = children
+  else if (typeof children === 'number') inner = String(children)
+  else if (Array.isArray(children)) inner = children.map(c => extractText(c, myCtx)).join('')
+  else inner = ''
+
+  if (parentCtx !== undefined && hasOwnStyle) {
+    const prefix = ansi.sgr(myCtx.fg, myCtx.bg, myCtx.attrs)
+    const suffix = parentCtx ? ansi.sgr(parentCtx.fg, parentCtx.bg, parentCtx.attrs) : ansi.sgrReset
+    return prefix + inner + suffix
+  }
+
+  return inner
 }
 
 function flattenChildren(children) {
@@ -747,5 +770,5 @@ export function mount(rootComponent, { stream, stdin, title, theme, onExit: onEx
 
   ctx.repaint = repaint
 
-  return { unmount, repaint }
+  return { unmount, repaint, getBuffer: () => prev }
 }

package/src/table.js

@@ -4,7 +4,7 @@ import { List } from './list.js'
 
 const DEFAULT_SEP = { left: '', fill: '\u2500', right: '' }
 
-export function Table({ columns, data, selected, onSelect, focused = true, separator = false, separatorChars, renderItem, scrollbar, stickyHeader = false }) {
+export function Table({ columns, data, selected, onSelect, focused = true, separator = false, separatorChars, renderItem, scrollbar, stickyHeader = false, gap = 0, itemHeight = 1, scrolloff = 2 }) {
   const { accent = 'cyan' } = useTheme()
 
   const headerRow = jsxs('box', {
@@ -15,9 +15,7 @@ export function Table({ columns, data, selected, onSelect, focused = true, separ
         style: {
           width: col.width,
           flexGrow: col.flexGrow,
-          color: 'gray',
           dim: true,
-          bold: true,
           overflow: 'truncate',
           paddingX: col.paddingX ?? 1,
         },
@@ -26,24 +24,22 @@ export function Table({ columns, data, selected, onSelect, focused = true, separ
     ),
   })
 
+  const sepRow = separator
+    ? (() => {
+        const s = { ...DEFAULT_SEP, ...separatorChars }
+        return jsxs('box', {
+          style: { flexDirection: 'row' },
+          children: [
+            jsx('text', { style: { dim: true }, children: s.left }),
+            jsx('text', { style: { dim: true, flexGrow: 1, overflow: 'nowrap' }, children: s.fill.repeat(1000) }),
+            jsx('text', { style: { dim: true }, children: s.right }),
+          ],
+        })
+      })()
+    : null
+
   const header = separator
-    ? jsxs('box', {
-        style: { flexDirection: 'column' },
-        children: [
-          headerRow,
-          (() => {
-            const s = { ...DEFAULT_SEP, ...separatorChars }
-            return jsxs('box', {
-              style: { flexDirection: 'row' },
-              children: [
-                jsx('text', { style: { color: 'gray', dim: true }, children: s.left }),
-                jsx('text', { style: { color: 'gray', dim: true, flexGrow: 1, overflow: 'nowrap' }, children: s.fill.repeat(200) }),
-                jsx('text', { style: { color: 'gray', dim: true }, children: s.right }),
-              ],
-            })
-          })(),
-        ],
-      })
+    ? jsxs('box', { style: { flexDirection: 'column' }, children: [headerRow, sepRow] })
     : headerRow
 
   const defaultRenderItem = (row, { selected: isSel }) =>
@@ -64,15 +60,37 @@ export function Table({ columns, data, selected, onSelect, focused = true, separ
       ),
     })
 
-  return jsx(List, {
+  const list = jsx(List, {
     items: data,
     selected,
     onSelect,
     focused,
-    header,
-    headerHeight: separator ? 2 : 1,
     scrollbar,
-    stickyHeader,
+    gap,
+    itemHeight,
+    scrolloff,
     renderItem: renderItem || defaultRenderItem,
   })
+
+  if (!stickyHeader) {
+    return jsx(List, {
+      items: data,
+      selected,
+      onSelect,
+      focused,
+      header,
+      headerHeight: separator ? 2 : 1,
+      scrollbar,
+      stickyHeader: true,
+      gap,
+      itemHeight,
+      scrolloff,
+      renderItem: renderItem || defaultRenderItem,
+    })
+  }
+
+  return jsxs('box', {
+    style: { flexDirection: 'column', flexGrow: 1 },
+    children: [header, list],
+  })
 }

package/src/tabs.js

@@ -1,7 +1,9 @@
 import { jsx, jsxs } from '../jsx-runtime.js'
-import { useInput } from './hooks.js'
+import { useInput, useTheme } from './hooks.js'
 
 export function Tabs({ items, selected, onSelect, focused = true }) {
+  const { accent = 'cyan' } = useTheme()
+
   useInput(({ key }) => {
     if (!focused) return
 
@@ -17,10 +19,15 @@ export function Tabs({ items, selected, onSelect, focused = true }) {
 
   const children = items.map(item => {
     const isSelected = item === selected
-    return jsx('text', {
-      style: isSelected ? { inverse: true, bold: true } : { color: 'gray' },
-      children: ` ${item} `,
-    })
+    let style
+    if (isSelected && focused) {
+      style = { bg: accent, color: 'black', bold: true }
+    } else if (isSelected) {
+      style = { inverse: true, bold: true }
+    } else {
+      style = { color: 'gray' }
+    }
+    return jsx('text', { style, children: ` ${item} ` })
   })
 
   return jsxs('box', {