@mdxui/terminal 2.0.0

package/src/renderers/interactive/cursor-manager.ts

@@ -0,0 +1,147 @@
+/**
+ * @mdxui/terminal Cursor Manager
+ *
+ * Handles cursor position, visibility, style, and blinking
+ * for the interactive renderer.
+ *
+ * @packageDocumentation
+ */
+
+import type { CursorManagerState, FocusManagerState } from './types'
+
+/**
+ * Creates the cursor manager state
+ */
+export function createCursorManagerState(): CursorManagerState {
+  return {
+    cursorPosition: { x: 0, y: 0 },
+    cursorVisible: true,
+    cursorStyle: 'block',
+    cursorBlinking: false,
+  }
+}
+
+/**
+ * Set cursor position
+ */
+export function setCursorPosition(
+  cursorState: CursorManagerState,
+  x: number,
+  y: number,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  cursorState.cursorPosition = { x, y }
+}
+
+/**
+ * Get cursor position
+ */
+export function getCursorPosition(
+  cursorState: CursorManagerState,
+  destroyed?: boolean
+): { x: number; y: number } {
+  if (destroyed) return { x: 0, y: 0 }
+  return { ...cursorState.cursorPosition }
+}
+
+/**
+ * Show the cursor
+ */
+export function showCursor(
+  cursorState: CursorManagerState,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  cursorState.cursorVisible = true
+}
+
+/**
+ * Hide the cursor
+ */
+export function hideCursor(
+  cursorState: CursorManagerState,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  cursorState.cursorVisible = false
+}
+
+/**
+ * Check if cursor is visible
+ */
+export function isCursorVisible(
+  cursorState: CursorManagerState,
+  destroyed?: boolean
+): boolean {
+  if (destroyed) return false
+  return cursorState.cursorVisible
+}
+
+/**
+ * Set cursor style
+ */
+export function setCursorStyle(
+  cursorState: CursorManagerState,
+  style: 'block' | 'underline' | 'bar',
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  cursorState.cursorStyle = style
+}
+
+/**
+ * Get cursor style
+ */
+export function getCursorStyle(
+  cursorState: CursorManagerState,
+  destroyed?: boolean
+): string {
+  if (destroyed) return 'block'
+  return cursorState.cursorStyle
+}
+
+/**
+ * Set cursor blink state
+ */
+export function setCursorBlink(
+  cursorState: CursorManagerState,
+  blink: boolean,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  cursorState.cursorBlinking = blink
+}
+
+/**
+ * Check if cursor is blinking
+ */
+export function isCursorBlinking(
+  cursorState: CursorManagerState,
+  destroyed?: boolean
+): boolean {
+  if (destroyed) return false
+  return cursorState.cursorBlinking
+}
+
+/**
+ * Update cursor position for a focusable element
+ */
+export function updateCursorPosition(
+  cursorState: CursorManagerState,
+  focusState: FocusManagerState,
+  id: string,
+  position: { x: number; y: number },
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  // Update focusable's cursor position
+  const entry = focusState.focusables.get(id)
+  if (entry) {
+    entry.options.cursorPosition = position
+  }
+  // If this is the focused element, update cursor
+  if (focusState.focusedId === id) {
+    cursorState.cursorPosition = { ...position }
+  }
+}

package/src/renderers/interactive/focus-manager.ts

@@ -0,0 +1,279 @@
+/**
+ * @mdxui/terminal Focus Manager
+ *
+ * Handles focus navigation, focus traps, and focus groups for the interactive renderer.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  FocusableOptions,
+  FocusableEntry,
+  FocusTrapEntry,
+  FocusManagerState,
+  CursorManagerState,
+} from './types'
+
+/**
+ * Creates the focus manager state
+ */
+export function createFocusManagerState(wrapFocus: boolean): FocusManagerState {
+  return {
+    focusables: new Map<string, FocusableEntry>(),
+    focusedId: null,
+    activeGroup: null,
+    focusTrapStack: [],
+    registrationCounter: 0,
+    wrapFocus,
+  }
+}
+
+/**
+ * Gets sorted focusable IDs based on tabIndex and registration order
+ */
+export function getSortedFocusableIds(
+  focusState: FocusManagerState,
+  destroyed: boolean
+): string[] {
+  if (destroyed) return []
+
+  const { focusables, activeGroup, focusTrapStack } = focusState
+
+  const entries = Array.from(focusables.values())
+    .filter(e => {
+      // Exclude negative tabIndex
+      if (e.options.tabIndex < 0) return false
+      // Exclude disabled
+      if (e.options.disabled) return false
+      // Filter by active group if set
+      if (activeGroup !== null && e.options.group !== activeGroup) return false
+      // If in focus trap, only include elements from that group
+      if (focusTrapStack.length > 0) {
+        const currentTrap = focusTrapStack[focusTrapStack.length - 1]
+        if (e.options.group !== currentTrap.group) return false
+      }
+      return true
+    })
+    .sort((a, b) => {
+      // Sort by tabIndex first
+      if (a.options.tabIndex !== b.options.tabIndex) {
+        return a.options.tabIndex - b.options.tabIndex
+      }
+      // Then by registration order
+      return a.registrationOrder - b.registrationOrder
+    })
+
+  return entries.map(e => e.id)
+}
+
+/**
+ * Gets the current focus index
+ */
+export function getCurrentFocusIndex(
+  focusState: FocusManagerState,
+  destroyed: boolean
+): number {
+  if (focusState.focusedId === null) return -1
+  const ids = getSortedFocusableIds(focusState, destroyed)
+  return ids.indexOf(focusState.focusedId)
+}
+
+/**
+ * Focus the next focusable element
+ */
+export function focusNext(
+  focusState: FocusManagerState,
+  cursorState: CursorManagerState,
+  destroyed: boolean
+): void {
+  if (destroyed) return
+  const ids = getSortedFocusableIds(focusState, destroyed)
+  if (ids.length === 0) return
+
+  const currentIdx = getCurrentFocusIndex(focusState, destroyed)
+
+  if (currentIdx === -1) {
+    // Nothing focused, focus first
+    focusById(focusState, cursorState, ids[0], destroyed)
+  } else if (currentIdx < ids.length - 1) {
+    // Focus next
+    focusById(focusState, cursorState, ids[currentIdx + 1], destroyed)
+  } else if (focusState.wrapFocus) {
+    // Wrap to first
+    focusById(focusState, cursorState, ids[0], destroyed)
+  }
+  // If not wrapping and at end, stay at current
+}
+
+/**
+ * Focus the previous focusable element
+ */
+export function focusPrev(
+  focusState: FocusManagerState,
+  cursorState: CursorManagerState,
+  destroyed: boolean
+): void {
+  if (destroyed) return
+  const ids = getSortedFocusableIds(focusState, destroyed)
+  if (ids.length === 0) return
+
+  const currentIdx = getCurrentFocusIndex(focusState, destroyed)
+
+  if (currentIdx === -1) {
+    // Nothing focused, focus last
+    focusById(focusState, cursorState, ids[ids.length - 1], destroyed)
+  } else if (currentIdx > 0) {
+    // Focus prev
+    focusById(focusState, cursorState, ids[currentIdx - 1], destroyed)
+  } else if (focusState.wrapFocus) {
+    // Wrap to last
+    focusById(focusState, cursorState, ids[ids.length - 1], destroyed)
+  }
+  // If not wrapping and at start, stay at current
+}
+
+/**
+ * Focus an element by ID
+ */
+export function focusById(
+  focusState: FocusManagerState,
+  cursorState: CursorManagerState,
+  id: string,
+  destroyed: boolean
+): void {
+  if (destroyed) return
+  const entry = focusState.focusables.get(id)
+  if (!entry) return
+
+  // Skip if already focused
+  if (focusState.focusedId === id) return
+
+  // Blur previous
+  if (focusState.focusedId) {
+    const prevEntry = focusState.focusables.get(focusState.focusedId)
+    if (prevEntry?.options.onBlur) {
+      prevEntry.options.onBlur({ id: focusState.focusedId })
+    }
+  }
+
+  // Focus new
+  focusState.focusedId = id
+  if (entry.options.onFocus) {
+    entry.options.onFocus({ id })
+  }
+
+  // Update cursor
+  if (entry.options.cursorPosition) {
+    cursorState.cursorPosition = { ...entry.options.cursorPosition }
+  }
+  if (entry.options.showCursor !== undefined) {
+    cursorState.cursorVisible = entry.options.showCursor
+  }
+}
+
+/**
+ * Get the currently focused ID
+ */
+export function getFocusedId(
+  focusState: FocusManagerState,
+  destroyed: boolean
+): string | null {
+  if (destroyed) return null
+  return focusState.focusedId
+}
+
+/**
+ * Get all focusable IDs
+ */
+export function getFocusableIds(
+  focusState: FocusManagerState,
+  destroyed: boolean
+): string[] {
+  return getSortedFocusableIds(focusState, destroyed)
+}
+
+/**
+ * Register a focusable element
+ */
+export function registerFocusable(
+  focusState: FocusManagerState,
+  id: string,
+  options: FocusableOptions,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  // Remove existing if present (handles re-registration)
+  focusState.focusables.delete(id)
+  focusState.focusables.set(id, {
+    id,
+    options,
+    registrationOrder: focusState.registrationCounter++,
+  })
+}
+
+/**
+ * Unregister a focusable element
+ */
+export function unregisterFocusable(
+  focusState: FocusManagerState,
+  id: string,
+  destroyed?: boolean
+): void {
+  if (destroyed) return
+  focusState.focusables.delete(id)
+  if (focusState.focusedId === id) {
+    focusState.focusedId = null
+  }
+}
+
+/**
+ * Set the active focus group
+ */
+export function setActiveGroup(
+  focusState: FocusManagerState,
+  group: string,
+  destroyed: boolean
+): void {
+  if (destroyed) return
+  focusState.activeGroup = group
+}
+
+/**
+ * Push a focus trap onto the stack
+ */
+export function pushFocusTrap(
+  focusState: FocusManagerState,
+  group: string,
+  destroyed: boolean
+): void {
+  if (destroyed) return
+  focusState.focusTrapStack.push({
+    group,
+    previousFocusId: focusState.focusedId,
+  })
+  focusState.activeGroup = group
+}
+
+/**
+ * Pop a focus trap from the stack
+ */
+export function popFocusTrap(
+  focusState: FocusManagerState,
+  cursorState: CursorManagerState,
+  destroyed: boolean
+): void {
+  if (destroyed) return
+  const trap = focusState.focusTrapStack.pop()
+  if (trap) {
+    // Restore previous focus
+    if (trap.previousFocusId) {
+      focusById(focusState, cursorState, trap.previousFocusId, destroyed)
+    }
+    // Update active group
+    if (focusState.focusTrapStack.length > 0) {
+      focusState.activeGroup = focusState.focusTrapStack[focusState.focusTrapStack.length - 1].group
+    } else {
+      focusState.activeGroup = null
+    }
+  }
+}