@workerdeck/ui 0.6.0

package/src/components/prompt-area/use-prompt-area-events.ts

@@ -0,0 +1,470 @@
+'use client'
+
+import { useCallback, useRef } from 'react'
+import type { Segment, ChipSegment, TriggerConfig } from './types.ts'
+import { resolveTriggersInSegments } from './prompt-area-engine.ts'
+import { normalizeEditorDOM, safeJsonStringify, getSelectionRange } from './dom-helpers.ts'
+import {
+  serializeFragmentToPlainText,
+  serializeFragmentToSegments,
+  parseSegmentsFromClipboard,
+  insertSegmentsAtCursor,
+} from './clipboard-helpers.ts'
+import { htmlToMarkdown } from './html-to-markdown.ts'
+import {
+  normalizeListPrefixText,
+  renumberOrderedListLines,
+  hasOrderedListRun,
+} from './prompt-area-list-ops.ts'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type EventHandlerDeps = {
+  editorRef: React.RefObject<HTMLDivElement | null>
+  readSegmentsFromDOM: () => Segment[]
+  onChange: (segments: Segment[]) => void
+  renderSegmentsToDOM: (segments: Segment[]) => void
+  runTriggerDetection: () => void
+  dismissTrigger: () => void
+  triggers: TriggerConfig[]
+  /** When true, rich `text/html` on the clipboard is converted to markdown. */
+  markdownEnabled: boolean
+  /** When true, pasted list markers ("- ") are normalized to the "•" glyph. */
+  normalizeBullets: boolean
+  onPaste?: (data: { segments: Segment[]; source: 'internal' | 'external' }) => void
+  onUndo?: (segments: Segment[]) => void
+  onRedo?: (segments: Segment[]) => void
+  onChipAdd?: (chip: ChipSegment) => void
+  onImagePaste?: (file: File) => void
+  onRawPaste?: (e: React.ClipboardEvent<HTMLDivElement>) => void
+}
+
+type PromptAreaEventHandlers = {
+  handlePaste: (e: React.ClipboardEvent<HTMLDivElement>) => void
+  handleCopy: (e: React.ClipboardEvent<HTMLDivElement>) => void
+  handleCut: (e: React.ClipboardEvent<HTMLDivElement>) => void
+  handleDrop: (e: React.DragEvent<HTMLDivElement>) => void
+  handleDragOver: (e: React.DragEvent<HTMLDivElement>) => void
+  handleCompositionStart: () => void
+  handleCompositionEnd: () => void
+  handleBlur: () => void
+  handleKeyDownForUndoRedo: (e: React.KeyboardEvent<HTMLDivElement>) => boolean
+  pushUndo: (segments: Segment[]) => void
+  resetUndoHistory: () => void
+  isComposing: React.RefObject<boolean>
+}
+
+// ---------------------------------------------------------------------------
+// Undo/Redo Stack
+// ---------------------------------------------------------------------------
+
+const MAX_UNDO_HISTORY = 100
+
+/** Delay before dismissing trigger on blur, so popover clicks register first */
+export const BLUR_DELAY_MS = 150
+
+type UndoState = {
+  undoStack: Segment[][]
+  redoStack: Segment[][]
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Encapsulates all edge-case event handlers for the prompt area component:
+ * paste, copy, cut, drag/drop, IME composition, blur, and undo/redo.
+ */
+export function usePromptAreaEvents(deps: EventHandlerDeps): PromptAreaEventHandlers {
+  const {
+    editorRef,
+    readSegmentsFromDOM,
+    onChange,
+    renderSegmentsToDOM,
+    runTriggerDetection,
+    dismissTrigger,
+    triggers,
+    markdownEnabled,
+    normalizeBullets,
+    onPaste: onPasteCallback,
+    onUndo,
+    onRedo,
+    onChipAdd,
+    onImagePaste,
+    onRawPaste,
+  } = deps
+
+  const isComposing = useRef(false)
+
+  // -----------------------------------------------------------------------
+  // Undo/redo stack (MAX_UNDO_HISTORY entries; clears redo on new push).
+  // Invariants: stacks live in refs (not useState) so pushUndo /
+  // resetUndoHistory / handleKeyDownForUndoRedo keep stable identity.
+  // Destabilizing this would re-create handleInput / handleKeyDown /
+  // imperative handle on every render and silently regress IME + debounced
+  // undo in the parent hook.
+  // -----------------------------------------------------------------------
+  const undoState = useRef<UndoState>({ undoStack: [], redoStack: [] })
+
+  const pushUndo = useCallback((segments: Segment[]) => {
+    const state = undoState.current
+    state.undoStack.push(segments)
+    if (state.undoStack.length > MAX_UNDO_HISTORY) {
+      state.undoStack.shift()
+    }
+    // Clear redo stack on new change
+    state.redoStack = []
+  }, [])
+
+  const resetUndoHistory = useCallback(() => {
+    undoState.current = { undoStack: [], redoStack: [] }
+  }, [])
+
+  // -----------------------------------------------------------------------
+  // Paste: strip HTML, insert plain text only
+  // -----------------------------------------------------------------------
+
+  const handlePaste = useCallback(
+    (e: React.ClipboardEvent<HTMLDivElement>) => {
+      // Let a consumer take over the paste entirely (e.g. divert large text or
+      // arbitrary files to an upload pipeline) by calling preventDefault().
+      onRawPaste?.(e)
+      if (e.defaultPrevented) return
+      e.preventDefault()
+
+      const editor = editorRef.current
+      if (!editor) return
+
+      // Check for image files in clipboard before processing text
+      // Some browsers/OSes provide pasted images via `items` instead of `files` (e.g. screenshots)
+      const imageFile =
+        Array.from(e.clipboardData.files).find((f) => f.type.startsWith('image/')) ??
+        (() => {
+          const item = Array.from(e.clipboardData.items).find((i) => i.type.startsWith('image/'))
+          return item?.getAsFile() ?? null
+        })()
+      if (imageFile) {
+        onImagePaste?.(imageFile)
+        return
+      }
+
+      // Record undo snapshot
+      const currentSegments = readSegmentsFromDOM()
+      pushUndo(currentSegments)
+
+      // Check for internal segment data (copy/paste within the editor)
+      const segmentJson = e.clipboardData.getData('text/prompt-area-segments')
+      if (segmentJson) {
+        const parsed = parseSegmentsFromClipboard(segmentJson)
+        if (parsed && parsed.length > 0) {
+          // Insert the copied segments at cursor position
+          const range = getSelectionRange()
+          if (!range) return
+
+          range.deleteContents()
+
+          // Merge pasted segments into current segments at cursor position
+          const beforePaste = readSegmentsFromDOM()
+          const merged = insertSegmentsAtCursor(beforePaste, parsed, editor)
+          onChange(merged)
+          renderSegmentsToDOM(merged)
+
+          // Notify: internal paste with chip data preserved
+          onPasteCallback?.({ segments: merged, source: 'internal' })
+          for (const seg of parsed) {
+            if (seg.type === 'chip') {
+              onChipAdd?.(seg)
+            }
+          }
+
+          runTriggerDetection()
+          return
+        }
+      }
+
+      // When markdown mode is on, prefer the richest clipboard flavor:
+      //   1. text/markdown — some apps (e.g. Slack) hand out markdown directly,
+      //      preserving nested lists that their text/plain flattens.
+      //   2. text/html     — convert web/Notion/Docs/GitHub HTML to markdown.
+      // Otherwise (markdown off, or neither present) fall back to plain text.
+      let text = ''
+      if (markdownEnabled) {
+        text = e.clipboardData.getData('text/markdown')
+        if (text) {
+          // Slack over-escapes inert punctuation (e.g. `\(` `\)`); unescape
+          // parentheses so the source reads cleanly. They carry no markdown
+          // meaning, unlike `\*` / `\.` / `\-` which are left intact.
+          text = text.replace(/\\([()])/g, '$1')
+        } else {
+          const html = e.clipboardData.getData('text/html')
+          // A converter failure (e.g. stack overflow on pathologically deep
+          // nesting) must not drop the paste — leave text empty so the
+          // text/plain fallback below still runs.
+          if (html) {
+            try {
+              text = htmlToMarkdown(html)
+            } catch {
+              text = ''
+            }
+          }
+        }
+      }
+      if (!text) text = e.clipboardData.getData('text/plain')
+      if (!text) return
+
+      // Normalize pasted list markers ("- " → "•") so pasted bullets match
+      // typed input. Applies to both the HTML→markdown and plain-text paths.
+      if (markdownEnabled && normalizeBullets) {
+        text = normalizeListPrefixText(text, true)
+      }
+
+      // Rebuild ordered-list numbering in the pasted block so a copied list with
+      // stale numbers lands sequential. Gated on `hasOrderedListRun` so incidental
+      // numeric-leading prose (e.g. `1985. Born / 2020. Died`) is left untouched.
+      // Done at the raw-string level (the caret collapses to end-of-content after
+      // insertion, so no offset remap needed).
+      if (markdownEnabled && hasOrderedListRun(text)) {
+        text = renumberOrderedListLines(text).text
+      }
+
+      // Insert plain text at cursor position using Selection API
+      const range = getSelectionRange()
+      if (!range) return
+
+      range.deleteContents()
+
+      // Handle multi-line paste: split into lines with BR elements
+      const lines = text.split('\n')
+      const fragment = document.createDocumentFragment()
+
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i]) {
+          fragment.appendChild(document.createTextNode(lines[i]))
+        }
+        if (i < lines.length - 1) {
+          fragment.appendChild(document.createElement('br'))
+        }
+      }
+
+      range.insertNode(fragment)
+
+      // Move cursor to end of pasted content
+      range.collapse(false)
+      const sel = window.getSelection()
+      sel?.removeAllRanges()
+      sel?.addRange(range)
+
+      // Normalize DOM, sync model, detect triggers
+      normalizeEditorDOM(editor)
+      const newSegments = readSegmentsFromDOM()
+
+      // Auto-resolve trigger patterns in pasted text (e.g., #readme -> chip)
+      const resolvedSegments = resolveTriggersInSegments(newSegments, triggers)
+
+      if (resolvedSegments !== newSegments) {
+        onChange(resolvedSegments)
+        renderSegmentsToDOM(resolvedSegments)
+
+        // Notify about auto-resolved chips from pasted text
+        for (const seg of resolvedSegments) {
+          if (
+            seg.type === 'chip' &&
+            !newSegments.some(
+              (s) =>
+                s.type === 'chip' &&
+                s.trigger === seg.trigger &&
+                s.value === seg.value &&
+                s.displayText === seg.displayText,
+            )
+          ) {
+            onChipAdd?.(seg)
+          }
+        }
+      } else {
+        onChange(newSegments)
+      }
+
+      onPasteCallback?.({ segments: resolvedSegments, source: 'external' })
+      runTriggerDetection()
+    },
+    [
+      editorRef,
+      readSegmentsFromDOM,
+      onChange,
+      pushUndo,
+      runTriggerDetection,
+      renderSegmentsToDOM,
+      triggers,
+      markdownEnabled,
+      normalizeBullets,
+      onPasteCallback,
+      onChipAdd,
+      onImagePaste,
+      onRawPaste,
+    ],
+  )
+
+  // -----------------------------------------------------------------------
+  // Copy: serialize chips into plain text
+  // -----------------------------------------------------------------------
+
+  const handleCopy = useCallback((e: React.ClipboardEvent<HTMLDivElement>) => {
+    e.preventDefault()
+
+    const range = getSelectionRange()
+    if (!range) return
+
+    const fragment = range.cloneContents()
+
+    // Walk fragment and serialize, converting chips to their text representation
+    const plainText = serializeFragmentToPlainText(fragment)
+    e.clipboardData.setData('text/plain', plainText)
+
+    // Also serialize chip segments as JSON for internal paste
+    const fragmentSegments = serializeFragmentToSegments(fragment)
+    const hasChips = fragmentSegments.some((s) => s.type === 'chip')
+    if (hasChips) {
+      const json = safeJsonStringify(fragmentSegments)
+      if (json) {
+        e.clipboardData.setData('text/prompt-area-segments', json)
+      }
+    }
+  }, [])
+
+  // -----------------------------------------------------------------------
+  // Cut: copy + delete
+  // -----------------------------------------------------------------------
+
+  const handleCut = useCallback(
+    (e: React.ClipboardEvent<HTMLDivElement>) => {
+      // First, do the copy
+      handleCopy(e)
+
+      // Then delete the selection
+      const range = getSelectionRange()
+      if (!range) return
+
+      const currentSegments = readSegmentsFromDOM()
+      pushUndo(currentSegments)
+
+      range.deleteContents()
+
+      const editor = editorRef.current
+      if (editor) {
+        normalizeEditorDOM(editor)
+      }
+
+      const newSegments = readSegmentsFromDOM()
+      onChange(newSegments)
+      runTriggerDetection()
+    },
+    [handleCopy, editorRef, readSegmentsFromDOM, onChange, pushUndo, runTriggerDetection],
+  )
+
+  // -----------------------------------------------------------------------
+  // Drag & Drop: prevent to avoid unpredictable DOM mutations
+  // -----------------------------------------------------------------------
+
+  const handleDrop = useCallback((e: React.DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+  }, [])
+
+  const handleDragOver = useCallback((e: React.DragEvent<HTMLDivElement>) => {
+    e.preventDefault()
+  }, [])
+
+  // -----------------------------------------------------------------------
+  // IME Composition: track state, defer trigger detection
+  // -----------------------------------------------------------------------
+
+  const handleCompositionStart = useCallback(() => {
+    isComposing.current = true
+  }, [])
+
+  const handleCompositionEnd = useCallback(() => {
+    isComposing.current = false
+    // Run trigger detection after composition ends
+    runTriggerDetection()
+  }, [runTriggerDetection])
+
+  // -----------------------------------------------------------------------
+  // Blur: dismiss trigger dropdown with delay (so popover clicks work)
+  // -----------------------------------------------------------------------
+
+  const handleBlur = useCallback(() => {
+    setTimeout(() => {
+      const editor = editorRef.current
+      if (!editor) return
+
+      // Only dismiss if focus didn't move to an element within the editor container
+      const activeEl = document.activeElement
+      if (activeEl && editor.parentElement?.contains(activeEl)) return
+
+      dismissTrigger()
+    }, BLUR_DELAY_MS)
+  }, [editorRef, dismissTrigger])
+
+  // -----------------------------------------------------------------------
+  // Undo/Redo: intercept Ctrl+Z / Ctrl+Shift+Z
+  // -----------------------------------------------------------------------
+
+  const handleKeyDownForUndoRedo = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>): boolean => {
+      const isMeta = e.metaKey || e.ctrlKey
+
+      if (!isMeta || e.key !== 'z') return false
+
+      e.preventDefault()
+      const state = undoState.current
+
+      if (e.shiftKey) {
+        // Redo: Ctrl+Shift+Z
+        if (state.redoStack.length === 0) return true
+
+        const segments = state.redoStack.pop()
+        if (!segments) return true
+
+        const current = readSegmentsFromDOM()
+        state.undoStack.push(current)
+
+        onChange(segments)
+        renderSegmentsToDOM(segments)
+        onRedo?.(segments)
+      } else {
+        // Undo: Ctrl+Z
+        if (state.undoStack.length === 0) return true
+
+        const segments = state.undoStack.pop()
+        if (!segments) return true
+
+        const current = readSegmentsFromDOM()
+        state.redoStack.push(current)
+
+        onChange(segments)
+        renderSegmentsToDOM(segments)
+        onUndo?.(segments)
+      }
+
+      return true
+    },
+    [readSegmentsFromDOM, onChange, renderSegmentsToDOM, onUndo, onRedo],
+  )
+
+  return {
+    handlePaste,
+    handleCopy,
+    handleCut,
+    handleDrop,
+    handleDragOver,
+    handleCompositionStart,
+    handleCompositionEnd,
+    handleBlur,
+    handleKeyDownForUndoRedo,
+    pushUndo,
+    resetUndoHistory,
+    isComposing,
+  }
+}

package/src/components/prompt-area/use-prompt-area-state.ts

@@ -0,0 +1,131 @@
+/**
+ * Convenience hook that wires up all the boilerplate state for a PromptArea.
+ *
+ * Instead of manually managing `useState<Segment[]>`, `useRef<PromptAreaHandle>`,
+ * and computing derived values, call `usePromptAreaState()` once and spread
+ * `bind` into your `<PromptArea>`.
+ *
+ * @example
+ * ```tsx
+ * function ChatInput() {
+ *   const { bind, plainText, isEmpty, chips, clear, focus } = usePromptAreaState()
+ *
+ *   return (
+ *     <PromptArea
+ *       {...bind}
+ *       onSubmit={() => {
+ *         sendMessage(plainText)
+ *         clear()
+ *       }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+
+'use client'
+
+import { useCallback, useMemo, useRef, useState } from 'react'
+import type { Segment, ChipSegment, PromptAreaHandle } from './types.ts'
+import { segmentsToPlainText } from './prompt-area-engine.ts'
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export type UsePromptAreaStateOptions = {
+  /** Initial segment value. Defaults to `[]`. */
+  initialValue?: Segment[]
+}
+
+// ---------------------------------------------------------------------------
+// Return type
+// ---------------------------------------------------------------------------
+
+export type PromptAreaBind = {
+  /** Ref to attach to PromptArea — gives access to imperative methods. */
+  ref: React.RefObject<PromptAreaHandle | null>
+  /** Current segment array — pass as `value` prop. */
+  value: Segment[]
+  /** Setter — pass as `onChange` prop. */
+  onChange: (segments: Segment[]) => void
+}
+
+export type PromptAreaState = {
+  /** Props to spread directly onto `<PromptArea {...bind} />`. Contains ref, value, and onChange. */
+  bind: PromptAreaBind
+  /** Derived plain text representation of the current value. */
+  plainText: string
+  /** `true` when the value is empty or whitespace-only. */
+  isEmpty: boolean
+  /** `true` when the value contains at least one chip. */
+  hasChips: boolean
+  /** All chip segments in the current value. */
+  chips: ChipSegment[]
+  /** Clear all content (both state and the editor DOM). */
+  clear: () => void
+  /** Focus the editor. */
+  focus: () => void
+  /** Blur the editor. */
+  blur: () => void
+  /** Insert a chip at the current cursor position. */
+  insertChip: (chip: Omit<ChipSegment, 'type'>) => void
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function usePromptAreaState(options: UsePromptAreaStateOptions = {}): PromptAreaState {
+  const { initialValue = [] } = options
+
+  const [value, setValue] = useState<Segment[]>(initialValue)
+  const ref = useRef<PromptAreaHandle>(null)
+
+  // Derived
+  const plainText = useMemo(() => segmentsToPlainText(value), [value])
+
+  const isEmpty = useMemo(() => {
+    if (value.length === 0) return true
+    return value.every((seg) => seg.type === 'text' && seg.text.trim() === '')
+  }, [value])
+
+  const hasChips = useMemo(() => value.some((seg) => seg.type === 'chip'), [value])
+
+  const chips = useMemo(
+    () => value.filter((seg): seg is ChipSegment => seg.type === 'chip'),
+    [value],
+  )
+
+  // Bind object — safe to spread onto <PromptArea>
+  const bind = useMemo<PromptAreaBind>(() => ({ ref, value, onChange: setValue }), [value])
+
+  // Actions that proxy to the imperative handle
+  const clear = useCallback(() => {
+    if (ref.current) {
+      ref.current.clear()
+    } else {
+      setValue([])
+    }
+  }, [])
+
+  const focus = useCallback(() => ref.current?.focus(), [])
+  const blur = useCallback(() => ref.current?.blur(), [])
+
+  const insertChip = useCallback(
+    (chip: Omit<ChipSegment, 'type'>) => ref.current?.insertChip(chip),
+    [],
+  )
+
+  return {
+    bind,
+    plainText,
+    isEmpty,
+    hasChips,
+    chips,
+    clear,
+    focus,
+    blur,
+    insertChip,
+  }
+}