termcast 1.3.9

package/src/examples/internal/descendants-filtering.tsx

@@ -0,0 +1,223 @@
+// This example shows how to filter descendants by passing search query via context
+// Items conditionally render null when they don't match the search
+import { useKeyboard } from '@opentui/react'
+import { createDescendants } from 'termcast/src/descendants'
+import { createContext, useContext, useState } from 'react'
+import { renderWithProviders } from '../../utils'
+import { logger } from 'termcast/src/logger'
+
+const { DescendantsProvider, useDescendants, useDescendant } =
+  createDescendants<{
+    title?: string
+    filtered?: boolean
+  }>()
+
+const itemsPerPage = 6
+
+const MenuContext = createContext<{
+  focusedIndex: number
+  offset: number
+  itemsPerPage: number
+  selectedIds: Set<string>
+  searchQuery: string
+}>({
+  focusedIndex: 0,
+  offset: 0,
+  itemsPerPage,
+  selectedIds: new Set(),
+  searchQuery: '',
+})
+
+// Menu component with integrated search input
+const Menu = ({ children }: { children: React.ReactNode }) => {
+  const descendantsContext = useDescendants()
+  const [focusedIndex, setFocusedIndex] = useState(0)
+  const [offset, setOffset] = useState(0)
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
+  const [selectedTitles, setSelectedTitles] = useState<string[]>([])
+  const [searchQuery, setSearchQuery] = useState('')
+
+  useKeyboard((evt) => {
+    const items = Object.values(descendantsContext.map.current).filter(
+      (item) => item.index !== -1 && item.props?.filtered === true,
+    )
+    const itemCount = items.length
+
+    if (itemCount === 0) return
+
+    if (evt.name === 'down') {
+      setFocusedIndex((prev) => {
+        const nextIndex = (prev + 1) % itemCount
+
+        // Update offset only when the focused item is at the last position and there are more items
+        const visibleEnd = offset + itemsPerPage - 1
+        if (prev === visibleEnd && nextIndex < itemCount && nextIndex > prev) {
+          // Scroll down by one when at the last visible item
+          setOffset(offset + 1)
+        } else if (nextIndex < prev) {
+          // Wrapped to beginning
+          setOffset(0)
+        }
+
+        return nextIndex
+      })
+    } else if (evt.name === 'up') {
+      setFocusedIndex((prev) => {
+        const nextIndex = (prev - 1 + itemCount) % itemCount
+
+        // Update offset if we're going above the visible range
+        if (nextIndex < offset) {
+          setOffset(Math.max(0, nextIndex))
+        } else if (nextIndex >= offset + itemsPerPage) {
+          // Wrapped to end
+          setOffset(Math.max(0, itemCount - itemsPerPage))
+        }
+
+        return nextIndex
+      })
+    } else if (evt.name === 'return') {
+      // Toggle selection of current focused item
+      const entries = Object.entries(descendantsContext.map.current)
+      const sortedEntries = entries
+        .filter(
+          ([_, item]) => item.index !== -1 && item.props?.filtered === true,
+        )
+        .sort((a, b) => a[1].index - b[1].index)
+
+      const focusedId = sortedEntries[focusedIndex]?.[0]
+
+      if (focusedId) {
+        setSelectedIds((prev) => {
+          const newSet = new Set(prev)
+          if (newSet.has(focusedId)) {
+            newSet.delete(focusedId)
+          } else {
+            newSet.add(focusedId)
+          }
+
+          // Update selected titles state
+          const titles = Array.from(newSet)
+            .map((id) => descendantsContext.map.current[id]?.props?.title)
+            .filter(Boolean) as string[]
+
+          setSelectedTitles(titles)
+
+          return newSet
+        })
+      }
+    } else if (evt.ctrl && evt.name === 'return') {
+      // Log selected titles
+      logger.log('Selected filtered items:', selectedTitles)
+    }
+  })
+
+  return (
+    <MenuContext.Provider
+      value={{
+        focusedIndex,
+        offset,
+        itemsPerPage,
+        selectedIds,
+        searchQuery,
+      }}
+    >
+      <DescendantsProvider value={descendantsContext}>
+        <box flexDirection='column'>
+          <box flexDirection='column' borderStyle='single' padding={1}>
+            <text marginBottom={1}>Filter Menu</text>
+            <input
+              value={searchQuery}
+              onInput={(value) => {
+                setSearchQuery(value)
+                // Reset focus to first item when search changes
+                setFocusedIndex(0)
+                setOffset(0)
+              }}
+              focused
+              placeholder='Type to filter items...'
+              marginBottom={1}
+            />
+            <box flexDirection='column'>{children}</box>
+          </box>
+          {selectedTitles.length > 0 && (
+            <box
+              flexDirection='column'
+              marginTop={1}
+              borderStyle='single'
+              padding={1}
+            >
+              <text>Selected items ({selectedTitles.length}):</text>
+              {selectedTitles.map((title, index) => (
+                <text key={index} fg='green'>
+                  • {title}
+                </text>
+              ))}
+            </box>
+          )}
+        </box>
+      </DescendantsProvider>
+    </MenuContext.Provider>
+  )
+}
+
+const Item = ({ title }: { title: string; key?: any }) => {
+  const { focusedIndex, offset, itemsPerPage, selectedIds, searchQuery } =
+    useContext(MenuContext)
+
+  // Determine if item matches filter
+  const isFiltered = title.toLowerCase().includes(searchQuery.toLowerCase())
+
+  // Register with descendants with the filtered state
+  const descendant = useDescendant({ title, filtered: isFiltered })
+
+  // Filter items based on search query from context
+  if (!isFiltered) {
+    return null
+  }
+
+  // Hide items that are outside the visible range
+  if (descendant.index < offset || descendant.index >= offset + itemsPerPage) {
+    return null
+  }
+
+  const isFocused = descendant.index === focusedIndex
+  const isSelected = selectedIds.has(descendant.descendantId)
+
+  return (
+    <text fg={isFocused ? 'blue' : 'white'}>
+      {isSelected ? '✓ ' : '▭ '}
+      {title}
+    </text>
+  )
+}
+
+const Example = () => {
+  const allItems = [
+    'Apple Pie',
+    'Banana Bread',
+    'Chocolate Cake',
+    'Apple Tart',
+    'Blueberry Muffin',
+    'Cherry Pie',
+    'Apple Crumble',
+    'Date Pudding',
+    'Elderberry Jam',
+    'Fig Newton',
+    'Grape Jelly',
+    'Honey Cake',
+    'Ice Cream Sandwich',
+    'Jelly Donut',
+    'Key Lime Pie',
+    'Lemon Tart',
+  ]
+
+  return (
+    <Menu>
+      {allItems.map((title) => (
+        <Item key={title} title={title} />
+      ))}
+    </Menu>
+  )
+}
+
+renderWithProviders(<Example />)

package/src/examples/internal/descendants.tsx

@@ -0,0 +1,208 @@
+// read src/descendants.tsx to understand the core hooks that make this example possible
+//
+import { useKeyboard } from '@opentui/react'
+import { createDescendants } from 'termcast/src/descendants'
+import { useIsInFocus } from 'termcast/src/internal/focus-context'
+import { createContext, useContext, useState } from 'react'
+import { renderWithProviders } from '../../utils'
+import { logger } from 'termcast/src/logger'
+
+const { DescendantsProvider, useDescendants, useDescendant } =
+  createDescendants<{
+    title?: string
+  }>()
+
+const itemsPerPage = 4
+
+const FocusContext = createContext<{
+  focusedIndex: number
+  offset: number
+  itemsPerPage: number
+  selectedIds: Set<string>
+}>({
+  focusedIndex: 0,
+  offset: 0,
+  itemsPerPage,
+  selectedIds: new Set(),
+})
+
+// IMPORTANT! Notice that we only use descendantsContext.map.current only inside hooks or event handlers. it MUST not be used in render scope
+// instead each item renders its own content, descendantsContext must be used only for event handlers like useKeyboard or onMouseDown, or when user updates a search query to filter the filteredIndexes state
+// to do conditional rendering instead add additional state, here we used offset to track the current page offset of displayed items, selectedIndexes, focusedIndex. Other examples could be searchQuery
+const Menu = ({ children }: { children: React.ReactNode }) => {
+  const descendantsContext = useDescendants()
+  const [focusedIndex, setFocusedIndex] = useState(0)
+  const [offset, setOffset] = useState(0)
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
+  const [selectedTitles, setSelectedTitles] = useState<string[]>([])
+  const inFocus = useIsInFocus()
+
+  useKeyboard((evt) => {
+    if (!inFocus) return
+
+    const items = Object.values(descendantsContext.map.current).filter(
+      (item) => item.index !== -1,
+    )
+    const itemCount = items.length
+
+    if (itemCount === 0) return
+
+    if (evt.name === 'down') {
+      setFocusedIndex((prev) => {
+        const nextIndex = (prev + 1) % itemCount
+
+        // Update offset only when the focused item is at the last position and there are more items
+        const visibleEnd = offset + itemsPerPage - 1
+        if (prev === visibleEnd && nextIndex < itemCount && nextIndex > prev) {
+          // Scroll down by one when at the last visible item
+          setOffset(offset + 1)
+        } else if (nextIndex < prev) {
+          // Wrapped to beginning
+          setOffset(0)
+        }
+
+        return nextIndex
+      })
+    } else if (evt.name === 'up') {
+      setFocusedIndex((prev) => {
+        const nextIndex = (prev - 1 + itemCount) % itemCount
+
+        // Update offset if we're going above the visible range
+        if (nextIndex < offset) {
+          setOffset(Math.max(0, nextIndex))
+        } else if (nextIndex >= offset + itemsPerPage) {
+          // Wrapped to end
+          setOffset(Math.max(0, itemCount - itemsPerPage))
+        }
+
+        return nextIndex
+      })
+    } else if (evt.name === 'return') {
+      // Toggle selection of current focused item
+      const entries = Object.entries(descendantsContext.map.current)
+      const sortedEntries = entries
+        .filter(([_, item]) => item.index !== -1)
+        .sort((a, b) => a[1].index - b[1].index)
+
+      const focusedId = sortedEntries[focusedIndex]?.[0]
+
+      if (focusedId) {
+        setSelectedIds((prev) => {
+          const newSet = new Set(prev)
+          if (newSet.has(focusedId)) {
+            newSet.delete(focusedId)
+          } else {
+            newSet.add(focusedId)
+          }
+
+          // Update selected titles state
+          const titles = Array.from(newSet)
+            .map((id) => descendantsContext.map.current[id]?.props?.title)
+            .filter(Boolean) as string[]
+
+          setSelectedTitles(titles)
+
+          return newSet
+        })
+      }
+    } else if (evt.ctrl && evt.name === 'return') {
+      // Log selected titles
+      logger.log('Selected items:', selectedTitles)
+    }
+  })
+
+  return (
+    <FocusContext.Provider
+      value={{
+        focusedIndex,
+        offset,
+        itemsPerPage: itemsPerPage,
+        selectedIds,
+      }}
+    >
+      <DescendantsProvider value={descendantsContext}>
+        <box flexDirection='column'>
+          <box>{children}</box>
+          {selectedTitles.length > 0 && (
+            <box
+              flexDirection='column'
+              marginTop={1}
+              borderStyle='single'
+              padding={1}
+            >
+              <text>Selected items ({selectedTitles.length}):</text>
+              {selectedTitles.map((title, index) => (
+                <text key={index} fg='green'>
+                  • {title}
+                </text>
+              ))}
+            </box>
+          )}
+        </box>
+      </DescendantsProvider>
+    </FocusContext.Provider>
+  )
+}
+
+const Item = ({ title }: { title: string; key?: any }) => {
+  const descendant = useDescendant({ title })
+  const { focusedIndex, offset, itemsPerPage, selectedIds } =
+    useContext(FocusContext)
+
+  // Hide items that are outside the visible range
+  if (descendant.index < offset || descendant.index >= offset + itemsPerPage) {
+    return null
+  }
+
+  const isFocused = descendant.index === focusedIndex
+  const isSelected = selectedIds.has(descendant.descendantId)
+
+  return (
+    <text fg={isFocused ? 'blue' : 'white'}>
+      {isSelected ? '✓ ' : '▭ '}
+      {title}
+    </text>
+  )
+}
+
+const Example = () => {
+  const [searchQuery, setSearchQuery] = useState('')
+  const allItems = [
+    'First Item',
+    'Second Item',
+    'Third Item',
+    'Fourth Item',
+    'Fifth Item',
+    'Sixth Item',
+    'Seventh Item',
+    'Eighth Item',
+    'Ninth Item',
+    'Tenth Item',
+    'Eleventh Item',
+    'Twelfth Item',
+  ]
+
+  // Filter items based on search query
+  const filteredItems = allItems.filter((title) =>
+    title.toLowerCase().includes(searchQuery.toLowerCase()),
+  )
+
+  return (
+    <box flexDirection='column'>
+      <input
+        value={searchQuery}
+        onInput={setSearchQuery}
+        focused
+        placeholder='Search items...'
+        marginBottom={1}
+      />
+      <Menu>
+        {filteredItems.map((title) => (
+          <Item key={title} title={title} />
+        ))}
+      </Menu>
+    </box>
+  )
+}
+
+renderWithProviders(<Example />)

package/src/examples/internal/scrollbox-demo.tsx

@@ -0,0 +1,149 @@
+import React, { useState, useRef, useEffect } from 'react'
+import { renderWithProviders } from 'termcast'
+import { useKeyboard } from '@opentui/react'
+import { fg, bold } from '@opentui/core'
+
+function ScrollBoxListDemo(): any {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const scrollBoxRef = useRef<any>(null)
+  const itemRefs = useRef<Map<number, any>>(new Map())
+
+  const items = Array.from({ length: 50 }, (_, i) => ({
+    id: i,
+    title: `Item ${i + 1}`,
+    description: `Description for item ${i + 1}`,
+  }))
+
+  useEffect(() => {
+    // Small delay to ensure layout is complete
+    const timeoutId = setTimeout(() => {
+      const scrollBox = scrollBoxRef.current
+      const selectedItem = itemRefs.current.get(selectedIndex)
+
+      if (scrollBox && selectedItem) {
+        // Get the actual item height including padding and margins
+        const itemHeight = selectedItem.height
+
+        // Calculate item position in the content
+        // We need the absolute position of the item within the scrollable content
+        const itemRelativeTop = selectedItem.y - scrollBox.content.y
+        const itemRelativeBottom = itemRelativeTop + itemHeight
+
+        // Get viewport info
+        const viewportHeight = scrollBox.viewport.height
+        const currentScrollTop = scrollBox.scrollTop || 0
+
+        // Define safe zone with padding
+        const safePadding = 2
+
+        // Calculate if item is fully visible
+        const itemVisibleTop = itemRelativeTop - currentScrollTop
+        const itemVisibleBottom = itemRelativeBottom - currentScrollTop
+
+        // Check if we need to scroll
+        if (itemVisibleTop < safePadding) {
+          // Item is too close to top or above viewport
+          const newScrollTop = Math.max(0, itemRelativeTop - safePadding)
+          scrollBox.scrollTo(newScrollTop)
+        } else if (itemVisibleBottom > viewportHeight - safePadding) {
+          // Item is too close to bottom or below viewport
+          // Calculate scroll position to show item at bottom with padding
+          const newScrollTop = Math.max(
+            0,
+            itemRelativeBottom - viewportHeight + safePadding,
+          )
+          scrollBox.scrollTo(newScrollTop)
+        }
+      }
+    }, 20) // Give enough time for layout
+
+    return () => clearTimeout(timeoutId)
+  }, [selectedIndex])
+
+  useKeyboard((evt) => {
+    if (evt.name === 'up') {
+      setSelectedIndex((prev) => Math.max(0, prev - 1))
+    } else if (evt.name === 'down') {
+      setSelectedIndex((prev) => Math.min(items.length - 1, prev + 1))
+    } else if (evt.name === 'pageup') {
+      setSelectedIndex((prev) => Math.max(0, prev - 10))
+    } else if (evt.name === 'pagedown') {
+      setSelectedIndex((prev) => Math.min(items.length - 1, prev + 10))
+    } else if (evt.name === 'home') {
+      setSelectedIndex(0)
+    } else if (evt.name === 'end') {
+      setSelectedIndex(items.length - 1)
+    } else if (evt.name === 'q' || evt.name === 'escape') {
+      process.exit(0)
+    }
+  })
+
+  return (
+    <box flexDirection='column' width='100%' height='100%'>
+      <box padding={1} backgroundColor='#2e3440'>
+        <text>{bold(fg('#88c0d0')('ScrollBox Demo'))}</text>
+        <text fg='#d8dee9'>
+          ↑↓ Navigate | PgUp/PgDn Jump | Home/End First/Last
+        </text>
+      </box>
+
+      <scrollbox
+        ref={scrollBoxRef}
+        flexGrow={1}
+        flexShrink={1}
+        style={{
+          rootOptions: {
+            maxHeight: '100%',
+            overflow: 'hidden',
+          },
+          viewportOptions: {
+            flexGrow: 1,
+            flexShrink: 1,
+          },
+          contentOptions: {
+            padding: 1,
+            flexShrink: 0,
+          },
+          scrollbarOptions: {
+            visible: true,
+            showArrows: true,
+          },
+        }}
+      >
+        {items.map((item, index) => {
+          const isSelected = index === selectedIndex
+          return (
+            <box
+              key={item.id}
+              ref={(el) => {
+                if (el) itemRefs.current.set(index, el)
+              }}
+              padding={1}
+              backgroundColor={isSelected ? '#5e81ac' : '#3b4252'}
+              marginBottom={0.5}
+            >
+              <text>
+                {isSelected
+                  ? bold(fg('#eceff4')(`▶ ${item.title}`))
+                  : fg('#d8dee9')(`  ${item.title}`)}
+              </text>
+              <text fg={isSelected ? '#e5e9f0' : '#81a1c1'}>
+                {item.description}
+              </text>
+            </box>
+          )
+        })}
+      </scrollbox>
+
+      <box padding={1} backgroundColor='#2e3440'>
+        <text fg='#81a1c1'>
+          Selected: {selectedIndex + 1}/{items.length} | Press [q] to quit
+        </text>
+      </box>
+    </box>
+  )
+}
+
+if (import.meta.main) {
+  renderWithProviders(<ScrollBoxListDemo />)
+}

package/src/examples/internal/simple-dialog.tsx

@@ -0,0 +1,124 @@
+import React, { useState } from 'react'
+import { useKeyboard } from '@opentui/react'
+import { renderWithProviders } from 'termcast'
+import {
+  useDialog,
+  type DialogPosition,
+} from 'termcast/src/internal/dialog'
+import { Theme } from 'termcast'
+import { List } from 'termcast'
+import { ActionPanel, Action } from 'termcast'
+import { Dropdown } from 'termcast'
+import { logger } from 'termcast'
+
+function DialogContent({ position }: { position: DialogPosition }): any {
+  const [selectedDrink, setSelectedDrink] = useState<string>('coffee')
+
+  const handleDrinkChange = (newValue: string) => {
+    logger.log('Selected drink:', newValue)
+    setSelectedDrink(newValue)
+  }
+
+  return (
+    <Dropdown
+      tooltip='Select Drink'
+      onChange={handleDrinkChange}
+      value={selectedDrink}
+      placeholder='Search drinks...'
+    >
+      <Dropdown.Section title='Hot Drinks'>
+        <Dropdown.Item
+          value='coffee'
+          title='Coffee'
+          icon='☕'
+          keywords={['espresso', 'latte', 'cappuccino']}
+        />
+        <Dropdown.Item
+          value='tea'
+          title='Tea'
+          icon='🍵'
+          keywords={['green', 'black', 'herbal']}
+        />
+      </Dropdown.Section>
+
+      <Dropdown.Section title='Cold Drinks'>
+        <Dropdown.Item
+          value='juice'
+          title='Juice'
+          icon='🧃'
+          keywords={['orange', 'apple', 'grape']}
+        />
+        <Dropdown.Item
+          value='water'
+          title='Water'
+          icon='💧'
+          keywords={['sparkling', 'still', 'mineral']}
+        />
+        <Dropdown.Item
+          value='cola'
+          title='Cola'
+          icon='🥤'
+          keywords={['coke', 'pepsi', 'soda']}
+        />
+      </Dropdown.Section>
+    </Dropdown>
+  )
+}
+
+function App(): any {
+  const dialog = useDialog()
+
+  const positions: {
+    title: string
+    position: DialogPosition
+    description: string
+  }[] = [
+    {
+      title: 'Center',
+      position: 'center',
+      description: 'Shows dialog in the center of the screen',
+    },
+    {
+      title: 'Top Right',
+      position: 'top-right',
+      description: 'Shows dialog in the top-right corner',
+    },
+    {
+      title: 'Bottom Right',
+      position: 'bottom-right',
+      description: 'Shows dialog in the bottom-right corner',
+    },
+  ]
+
+  return (
+    <List navigationTitle='Dialog with Dropdown Example'>
+      {positions.map((item) => (
+        <List.Item
+          title={item.title}
+          subtitle={item.description}
+          actions={
+            <ActionPanel>
+              <Action
+                title={`Open ${item.title} Dialog`}
+                onAction={() => {
+                  dialog.push(
+                    <DialogContent position={item.position} />,
+                    item.position,
+                  )
+                }}
+              />
+              <Action
+                title='Clear All Dialogs'
+                onAction={() => {
+                  dialog.clear()
+                }}
+              />
+            </ActionPanel>
+          }
+        />
+      ))}
+    </List>
+  )
+}
+
+renderWithProviders(<App />)