@workerdeck/ui 0.6.0

package/src/components/prompt-area/prompt-area.tsx

@@ -0,0 +1,375 @@
+'use client'
+
+import { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react'
+import { cn } from '../../lib/utils.ts'
+import type { PromptAreaProps, PromptAreaHandle } from './types.ts'
+import { usePromptArea } from './use-prompt-area.ts'
+import { BLUR_DELAY_MS } from './use-prompt-area-events.ts'
+import { TriggerPopover } from './trigger-popover.tsx'
+import { AnimatedPlaceholder } from './animated-placeholder.tsx'
+import { ImageStrip } from './image-strip.tsx'
+import { FileStrip } from './file-strip.tsx'
+
+/**
+ * PromptArea - A lightweight rich text input with trigger support.
+ *
+ * Uses contentEditable to support inline chips (immutable pills) for
+ * mentions, commands, and other triggered tokens. Each trigger character
+ * can be configured to show a dropdown or fire a callback.
+ *
+ * @example
+ * ```tsx
+ * const [segments, setSegments] = useState<Segment[]>([])
+ *
+ * <PromptArea
+ *   value={segments}
+ *   onChange={setSegments}
+ *   triggers={[
+ *     { char: '@', position: 'any', mode: 'dropdown', onSearch: searchUsers },
+ *     { char: '/', position: 'start', mode: 'dropdown', onSearch: searchCommands },
+ *     { char: '#', position: 'any', mode: 'dropdown', onSearch: searchTags },
+ *   ]}
+ *   placeholder="Type a message..."
+ *   onSubmit={handleSubmit}
+ *   autoGrow
+ * />
+ * ```
+ */
+export function PromptArea({
+  value,
+  onChange,
+  triggers,
+  placeholder,
+  className,
+  disabled = false,
+  markdown,
+  normalizeBullets,
+  onSubmit,
+  onEscape,
+  onChipClick,
+  onChipAdd,
+  onChipDelete,
+  onLinkClick,
+  onPaste,
+  onUndo,
+  onRedo,
+  minHeight = 80,
+  maxHeight,
+  autoFocus = false,
+  autoGrow = false,
+  'aria-label': ariaLabel,
+  'data-test-id': dataTestId,
+  images = [],
+  imagePosition = 'above',
+  onImagePaste,
+  onImageRemove,
+  onImageClick,
+  files = [],
+  filePosition = 'above',
+  onFileRemove,
+  onFileClick,
+  onKeyDown,
+  onBlur,
+  onRawPaste,
+  submitOnEnter,
+  spellCheck,
+  maxLength,
+  'aria-describedby': ariaDescribedBy,
+  ref,
+}: PromptAreaProps & { ref?: React.Ref<PromptAreaHandle> }) {
+  const {
+    editorRef,
+    activeTrigger,
+    suggestions,
+    suggestionsLoading,
+    suggestionsError,
+    selectedSuggestionIndex,
+    handleInput,
+    handleKeyDown,
+    handleClick,
+    handleMouseDown,
+    selectSuggestion,
+    dismissTrigger,
+    handle,
+    triggerRect,
+    eventHandlers,
+  } = usePromptArea({
+    value,
+    onChange,
+    triggers,
+    disabled,
+    onSubmit,
+    onEscape,
+    onChipClick,
+    onChipAdd,
+    onChipDelete,
+    onLinkClick,
+    onPaste,
+    onRawPaste,
+    onUndo,
+    onRedo,
+    onImagePaste,
+    markdown,
+    normalizeBullets,
+    submitOnEnter,
+    maxLength,
+  })
+
+  // Expose imperative handle via ref
+  useImperativeHandle(ref, () => handle, [handle])
+
+  // Auto-focus on mount
+  useEffect(() => {
+    if (autoFocus) {
+      editorRef.current?.focus()
+    }
+  }, [autoFocus, editorRef])
+
+  // -----------------------------------------------------------------------
+  // Auto-grow: expand on focus/input, shrink on blur
+  // -----------------------------------------------------------------------
+
+  const [isFocused, setIsFocused] = useState(false)
+  const [editorHeight, setEditorHeight] = useState<number | undefined>(undefined)
+
+  const syncHeight = useCallback(() => {
+    const el = editorRef.current
+    if (!el) return
+    // Temporarily set height to auto so scrollHeight reflects true content height
+    el.style.height = 'auto'
+    const contentHeight = el.scrollHeight
+    el.style.height = `${contentHeight}px`
+    setEditorHeight(contentHeight)
+  }, [editorRef])
+
+  const handleFocus = useCallback(() => {
+    if (!autoGrow) return
+    setIsFocused(true)
+    syncHeight()
+  }, [autoGrow, syncHeight])
+
+  const handleBlurWithShrink = useCallback(() => {
+    eventHandlers.onBlur()
+    if (!autoGrow) return
+    setTimeout(() => {
+      const editor = editorRef.current
+      if (!editor) return
+      // Only shrink if focus truly left the component
+      const activeEl = document.activeElement
+      if (activeEl && editor.parentElement?.contains(activeEl)) return
+      setIsFocused(false)
+      setEditorHeight(undefined)
+    }, BLUR_DELAY_MS)
+  }, [eventHandlers, autoGrow, editorRef])
+
+  const handleInputWithGrow = useCallback(() => {
+    handleInput()
+    if (autoGrow && isFocused) {
+      syncHeight()
+    }
+  }, [handleInput, autoGrow, isFocused, syncHeight])
+
+  // Re-measure on value changes (chip insertion, undo/redo, programmatic updates)
+  useEffect(() => {
+    if (autoGrow && isFocused) {
+      requestAnimationFrame(() => syncHeight())
+    }
+  }, [value, autoGrow, isFocused, syncHeight])
+
+  // -----------------------------------------------------------------------
+  // Overflow indicator: detect when collapsed content is clipped
+  // -----------------------------------------------------------------------
+
+  const [hasOverflow, setHasOverflow] = useState(false)
+  const overflowTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (!autoGrow) return
+
+    const checkOverflow = () => {
+      if (isFocused) {
+        setHasOverflow(false)
+        return
+      }
+      const el = editorRef.current
+      if (!el) return
+      setHasOverflow(el.scrollHeight > el.clientHeight)
+    }
+
+    // Delay the check so the CSS height transition (150ms) finishes first;
+    // on initial mount there is no transition so the check still runs quickly.
+    const delay = isFocused ? 0 : 160
+    overflowTimerRef.current = setTimeout(checkOverflow, delay)
+    return () => {
+      if (overflowTimerRef.current !== null) {
+        clearTimeout(overflowTimerRef.current)
+      }
+    }
+  }, [autoGrow, isFocused, value, editorRef])
+
+  // -----------------------------------------------------------------------
+  // Compute editor style
+  // -----------------------------------------------------------------------
+
+  const editorStyle = useMemo((): React.CSSProperties => {
+    if (!autoGrow) {
+      const style: React.CSSProperties = { minHeight: `${minHeight}px` }
+      if (maxHeight) {
+        style.maxHeight = `${maxHeight}px`
+        style.overflowY = 'auto'
+      }
+      return style
+    }
+    return {
+      height: isFocused && editorHeight ? `${editorHeight}px` : `${minHeight}px`,
+      minHeight: `${minHeight}px`,
+      // Respect an explicit maxHeight; otherwise fall back to a viewport-relative
+      // cap so the editor never grows past the screen.
+      maxHeight: maxHeight ? `${maxHeight}px` : '70dvh',
+      overflowY: isFocused ? 'auto' : 'hidden',
+      // `min-height` is eased so consumers that animate it (e.g. the compact
+      // prompt area's collapse/expand) morph smoothly instead of snapping.
+      transition: 'height 150ms ease-out, min-height 240ms cubic-bezier(0.33, 1, 0.68, 1)',
+    }
+  }, [autoGrow, minHeight, maxHeight, isFocused, editorHeight])
+
+  // Run a consumer's onKeyDown first; if it calls preventDefault, skip all of
+  // PromptArea's built-in key handling (submit, trigger nav, etc.).
+  const handleKeyDownCombined = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      onKeyDown?.(e)
+      if (e.defaultPrevented) return
+      handleKeyDown(e)
+    },
+    [onKeyDown, handleKeyDown],
+  )
+
+  // Forward blur to the consumer (with relatedTarget) alongside the internal
+  // trigger-dismiss / auto-grow-shrink handling.
+  const handleBlurCombined = useCallback(
+    (e: React.FocusEvent<HTMLDivElement>) => {
+      onBlur?.(e)
+      // handleBlurWithShrink already calls eventHandlers.onBlur() and only
+      // shrinks when autoGrow is on, so it covers both modes.
+      handleBlurWithShrink()
+    },
+    [onBlur, handleBlurWithShrink],
+  )
+
+  const isEmpty =
+    value.length === 0 || (value.length === 1 && value[0].type === 'text' && value[0].text === '')
+
+  const imageStrip =
+    images.length > 0 ? (
+      <ImageStrip
+        images={images}
+        onRemove={onImageRemove}
+        onClick={onImageClick}
+        className={imagePosition === 'above' ? 'pb-2' : 'pt-2'}
+      />
+    ) : null
+
+  const fileStrip =
+    files.length > 0 ? (
+      <FileStrip
+        files={files}
+        onRemove={onFileRemove}
+        onClick={onFileClick}
+        className={filePosition === 'above' ? 'pb-2' : 'pt-2'}
+      />
+    ) : null
+
+  // Typography (font-size/line-height) lives on the container, not the editor, so
+  // it cascades to the editor AND the placeholder overlays — and a consumer can
+  // override all three at once via `className` (e.g. `text-base leading-6`).
+  return (
+    <div className={cn('prompt-area-container relative text-sm leading-relaxed', className)}>
+      {imagePosition === 'above' && imageStrip}
+      {filePosition === 'above' && fileStrip}
+
+      {/* Editor + placeholder wrapper */}
+      <div className="relative">
+        <div
+          ref={editorRef}
+          contentEditable={!disabled}
+          suppressContentEditableWarning
+          role="textbox"
+          aria-label={ariaLabel ?? 'Text input'}
+          aria-multiline="true"
+          aria-disabled={disabled || undefined}
+          aria-describedby={ariaDescribedBy}
+          data-test-id={dataTestId}
+          spellCheck={spellCheck}
+          className={cn(
+            'prompt-area-editor',
+            'w-full min-w-0 break-words whitespace-pre-wrap outline-none',
+            disabled && 'cursor-not-allowed opacity-50',
+          )}
+          style={editorStyle}
+          onFocus={handleFocus}
+          onInput={autoGrow ? handleInputWithGrow : handleInput}
+          onKeyDown={handleKeyDownCombined}
+          onMouseDown={handleMouseDown}
+          onClick={handleClick}
+          onPaste={eventHandlers.onPaste}
+          onCopy={eventHandlers.onCopy}
+          onCut={eventHandlers.onCut}
+          onDrop={eventHandlers.onDrop}
+          onDragOver={eventHandlers.onDragOver}
+          onCompositionStart={eventHandlers.onCompositionStart}
+          onCompositionEnd={eventHandlers.onCompositionEnd}
+          onBlur={handleBlurCombined}
+        />
+
+        {/* Overflow gradient indicator – visible when auto-grow is collapsed and content is clipped */}
+        {autoGrow && hasOverflow && !isFocused && (
+          <div
+            aria-hidden="true"
+            className="pointer-events-auto absolute right-0 bottom-0 left-0 cursor-pointer"
+            style={{ height: '32px' }}
+            onClick={() => editorRef.current?.focus()}>
+            <div
+              className="h-full w-full"
+              style={{
+                background:
+                  'linear-gradient(to bottom, transparent, color-mix(in srgb, var(--prompt-area-surface, var(--background)) 80%, transparent), var(--prompt-area-surface, var(--background)))',
+              }}
+            />
+          </div>
+        )}
+
+        {/* Placeholder overlay */}
+        {isEmpty &&
+          placeholder &&
+          (Array.isArray(placeholder) ? (
+            <AnimatedPlaceholder texts={placeholder} />
+          ) : (
+            <div
+              className="pointer-events-none absolute top-0 left-0 select-none"
+              style={{ color: 'var(--prompt-area-placeholder, var(--muted-foreground))' }}
+              aria-hidden="true">
+              {placeholder}
+            </div>
+          ))}
+      </div>
+
+      {filePosition === 'below' && fileStrip}
+      {imagePosition === 'below' && imageStrip}
+
+      {/* Trigger suggestion popover */}
+      {activeTrigger && activeTrigger.config.mode === 'dropdown' && (
+        <TriggerPopover
+          suggestions={suggestions}
+          loading={suggestionsLoading}
+          error={suggestionsError}
+          emptyMessage={activeTrigger.config.emptyMessage}
+          selectedIndex={selectedSuggestionIndex}
+          onSelect={selectSuggestion}
+          onDismiss={dismissTrigger}
+          triggerRect={triggerRect}
+          triggerChar={activeTrigger.config.char}
+        />
+      )}
+    </div>
+  )
+}

package/src/components/prompt-area/remove-button.tsx

@@ -0,0 +1,37 @@
+import { cn } from '../../lib/utils.ts'
+
+type RemoveButtonProps = {
+  onClick: () => void
+  label: string
+  className?: string
+}
+
+export function RemoveButton({ onClick, label, className }: RemoveButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.stopPropagation()
+        onClick()
+      }}
+      className={cn(
+        'absolute top-0.5 right-0.5 grid h-3.5 w-3.5 cursor-pointer place-items-center',
+        'rounded-full bg-black/60 text-white hover:bg-black/80 dark:bg-white/60 dark:text-black dark:hover:bg-white/80',
+        'transition-colors',
+        className,
+      )}
+      aria-label={label}>
+      <svg
+        width="8"
+        height="8"
+        viewBox="0 0 10 10"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round">
+        <line x1="2.75" y1="2.75" x2="7.25" y2="7.25" />
+        <line x1="7.25" y1="2.75" x2="2.75" y2="7.25" />
+      </svg>
+    </button>
+  )
+}

package/src/components/prompt-area/segment-helpers.ts

@@ -0,0 +1,62 @@
+/**
+ * Convenience helpers for creating and inspecting Segments.
+ *
+ * These reduce boilerplate when building AI chat UIs that work with the
+ * PromptArea document model.
+ *
+ * @example
+ * ```ts
+ * import { text, chip, isSegmentsEmpty, segmentsToPlainText } from './segment-helpers.ts'
+ *
+ * const greeting = [text('Hello '), chip({ trigger: '@', value: 'u1', displayText: 'Alice' })]
+ * isSegmentsEmpty(greeting) // false
+ * segmentsToPlainText(greeting) // "Hello @Alice"
+ * ```
+ */
+
+import type { Segment, TextSegment, ChipSegment } from './types.ts'
+import { segmentsToPlainText, plainTextToSegments } from './prompt-area-engine.ts'
+
+// Re-export serialization utilities so consumers have a single import.
+export { segmentsToPlainText, plainTextToSegments }
+
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+
+/** Create a text segment. */
+export function text(value: string): TextSegment {
+  return { type: 'text', text: value }
+}
+
+/** Create a chip segment. */
+export function chip(opts: Omit<ChipSegment, 'type'>): ChipSegment {
+  return { type: 'chip', ...opts }
+}
+
+// ---------------------------------------------------------------------------
+// Predicates
+// ---------------------------------------------------------------------------
+
+/** Returns `true` when the segment array is empty or contains only whitespace text. */
+export function isSegmentsEmpty(segments: Segment[]): boolean {
+  if (segments.length === 0) return true
+  return segments.every((seg) => seg.type === 'text' && seg.text.trim() === '')
+}
+
+/** Returns `true` when the segment array contains at least one chip. */
+export function hasChips(segments: Segment[]): boolean {
+  return segments.some((seg) => seg.type === 'chip')
+}
+
+/** Extracts all chip segments from a segment array. */
+export function getChips(segments: Segment[]): ChipSegment[] {
+  return segments.filter((seg): seg is ChipSegment => seg.type === 'chip')
+}
+
+/** Extracts chips matching a specific trigger character. */
+export function getChipsByTrigger(segments: Segment[], trigger: string): ChipSegment[] {
+  return segments.filter(
+    (seg): seg is ChipSegment => seg.type === 'chip' && seg.trigger === trigger,
+  )
+}

package/src/components/prompt-area/trigger-popover.tsx

@@ -0,0 +1,139 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import { cn } from '../../lib/utils.ts'
+import type { TriggerSuggestion } from './types.ts'
+
+type TriggerPopoverProps = {
+  suggestions: TriggerSuggestion[]
+  loading: boolean
+  error?: string | null
+  emptyMessage?: string
+  selectedIndex: number
+  onSelect: (suggestion: TriggerSuggestion) => void
+  onDismiss: () => void
+  triggerRect: DOMRect | null
+  triggerChar: string
+}
+
+// Single source of truth for the popover height: drives both the flip-above
+// calculation and the maxHeight style.
+const POPOVER_MAX_HEIGHT = 240
+
+/**
+ * Floating popover that displays trigger suggestions.
+ * Positioned relative to the trigger character location in the editor.
+ */
+export function TriggerPopover({
+  suggestions,
+  loading,
+  error,
+  emptyMessage,
+  selectedIndex,
+  onSelect,
+  onDismiss,
+  triggerRect,
+  triggerChar,
+}: TriggerPopoverProps) {
+  const popoverRef = useRef<HTMLDivElement>(null)
+  const selectedRef = useRef<HTMLButtonElement>(null)
+
+  // Scroll selected item into view
+  useEffect(() => {
+    selectedRef.current?.scrollIntoView({ block: 'nearest' })
+  }, [selectedIndex])
+
+  // Click outside to dismiss
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      const target = e.target
+      if (popoverRef.current && target instanceof Node && !popoverRef.current.contains(target)) {
+        onDismiss()
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [onDismiss])
+
+  if (!triggerRect) return null
+  if (suggestions.length === 0 && !loading && !error && !emptyMessage) return null
+
+  // Position the popover relative to the trigger character, clamped to the
+  // viewport. Flip above the trigger when there isn't enough room below, so the
+  // suggestion list stays on-screen near the bottom edge.
+  const popoverMaxWidth = Math.min(320, window.innerWidth - 16)
+  const left = Math.min(triggerRect.left, window.innerWidth - popoverMaxWidth - 8)
+  const spaceBelow = window.innerHeight - triggerRect.bottom
+  const positionAbove = spaceBelow < POPOVER_MAX_HEIGHT && triggerRect.top > spaceBelow
+  const style: React.CSSProperties = {
+    position: 'fixed',
+    left: `${Math.max(8, left)}px`,
+    zIndex: 50,
+    maxWidth: `${popoverMaxWidth}px`,
+    maxHeight: `${POPOVER_MAX_HEIGHT}px`,
+    ...(positionAbove
+      ? { bottom: `${window.innerHeight - triggerRect.top + 4}px` }
+      : { top: `${triggerRect.bottom + 4}px` }),
+  }
+
+  return (
+    <div
+      ref={popoverRef}
+      className={cn(
+        'min-w-[200px] overflow-y-auto',
+        'bg-surface rounded-xl border p-2 shadow-md',
+        'animate-in fade-in-0 zoom-in-95',
+      )}
+      style={style}
+      role="listbox"
+      aria-label={`${triggerChar} suggestions`}>
+      {loading ? (
+        <div
+          role="option"
+          aria-selected={false}
+          className="text-muted-foreground px-3 py-2 text-sm">
+          Loading suggestions...
+        </div>
+      ) : error ? (
+        <div role="option" aria-selected={false} className="text-destructive px-3 py-2 text-sm">
+          {error}
+        </div>
+      ) : suggestions.length === 0 && emptyMessage ? (
+        <div
+          role="option"
+          aria-selected={false}
+          className="text-muted-foreground px-3 py-2 text-sm">
+          {emptyMessage}
+        </div>
+      ) : (
+        suggestions.map((suggestion, index) => (
+          <button
+            key={suggestion.value}
+            ref={index === selectedIndex ? selectedRef : undefined}
+            type="button"
+            role="option"
+            aria-selected={index === selectedIndex}
+            className={cn(
+              'text-foreground flex w-full items-start gap-2 rounded-lg px-3 py-2 text-left text-sm',
+              'hover:bg-surface-hover cursor-pointer transition-colors',
+              index === selectedIndex && 'bg-surface-hover',
+            )}
+            onMouseDown={(e) => {
+              e.preventDefault() // Prevent blur on the editor
+              onSelect(suggestion)
+            }}>
+            {suggestion.icon && <span className="mt-0.5 shrink-0">{suggestion.icon}</span>}
+            <div className="min-w-0 flex-1">
+              <div className="truncate font-medium">{suggestion.label}</div>
+              {suggestion.description && (
+                <div className="text-muted-foreground truncate text-xs">
+                  {suggestion.description}
+                </div>
+              )}
+            </div>
+          </button>
+        ))
+      )}
+    </div>
+  )
+}