@betterstart/cli 0.1.3 → 0.1.4

package/templates/tiptap/hooks/use-composed-ref.ts

@@ -0,0 +1,43 @@
+'use client'
+
+import { useCallback, useRef } from 'react'
+
+// basically Exclude<React.ClassAttributes<T>["ref"], string>
+type UserRef<T> = ((instance: T | null) => void) | React.RefObject<T | null> | null | undefined
+
+const updateRef = <T>(ref: NonNullable<UserRef<T>>, value: T | null) => {
+  if (typeof ref === 'function') {
+    ref(value)
+  } else if (ref && typeof ref === 'object' && 'current' in ref) {
+    // Safe assignment without MutableRefObject
+    ;(ref as { current: T | null }).current = value
+  }
+}
+
+export const useComposedRef = <T extends HTMLElement>(
+  libRef: React.RefObject<T | null>,
+  userRef: UserRef<T>
+) => {
+  const prevUserRef = useRef<UserRef<T>>(null)
+
+  return useCallback(
+    (instance: T | null) => {
+      if (libRef && 'current' in libRef) {
+        ;(libRef as { current: T | null }).current = instance
+      }
+
+      if (prevUserRef.current) {
+        updateRef(prevUserRef.current, null)
+      }
+
+      prevUserRef.current = userRef
+
+      if (userRef) {
+        updateRef(userRef, instance)
+      }
+    },
+    [libRef, userRef]
+  )
+}
+
+export default useComposedRef

package/templates/tiptap/hooks/use-cursor-visibility.ts

@@ -0,0 +1,68 @@
+'use client'
+
+import type { Editor } from '@tiptap/react'
+import { useEffect } from 'react'
+import { useBodyRect } from './use-element-rect'
+import { useWindowSize } from './use-window-size'
+
+export interface CursorVisibilityOptions {
+  /**
+   * The Tiptap editor instance
+   */
+  editor?: Editor | null
+  /**
+   * Reference to the toolbar element that may obscure the cursor
+   */
+  overlayHeight?: number
+}
+
+/**
+ * Custom hook that ensures the cursor remains visible when typing in a Tiptap editor.
+ * Automatically scrolls the window when the cursor would be hidden by the toolbar.
+ *
+ * @param options.editor The Tiptap editor instance
+ * @param options.overlayHeight Toolbar height to account for
+ * @returns The bounding rect of the body
+ */
+export function useCursorVisibility({ editor, overlayHeight = 0 }: CursorVisibilityOptions) {
+  const { height: windowHeight } = useWindowSize()
+  const rect = useBodyRect({
+    enabled: true,
+    throttleMs: 100,
+    useResizeObserver: true
+  })
+
+  useEffect(() => {
+    const ensureCursorVisibility = () => {
+      if (!editor) return
+
+      const { state, view } = editor
+      if (!view.hasFocus()) return
+
+      // Get current cursor position coordinates
+      const { from } = state.selection
+      const cursorCoords = view.coordsAtPos(from)
+
+      if (windowHeight < rect.height && cursorCoords) {
+        const availableSpace = windowHeight - cursorCoords.top
+
+        // If the cursor is hidden behind the overlay or offscreen, scroll it into view
+        if (availableSpace < overlayHeight) {
+          const targetCursorY = Math.max(windowHeight / 2, overlayHeight)
+          const currentScrollY = window.scrollY
+          const cursorAbsoluteY = cursorCoords.top + currentScrollY
+          const newScrollY = cursorAbsoluteY - targetCursorY
+
+          window.scrollTo({
+            top: Math.max(0, newScrollY),
+            behavior: 'smooth'
+          })
+        }
+      }
+    }
+
+    ensureCursorVisibility()
+  }, [editor, overlayHeight, windowHeight, rect.height])
+
+  return rect
+}

package/templates/tiptap/hooks/use-element-rect.ts

@@ -0,0 +1,166 @@
+'use client'
+
+import { useCallback, useEffect, useState } from 'react'
+import { useThrottledCallback } from './use-throttled-callback'
+
+export type RectState = Omit<DOMRect, 'toJSON'>
+
+export interface ElementRectOptions {
+  /**
+   * The element to track. Can be an Element, ref, or selector string.
+   * Defaults to document.body if not provided.
+   */
+  element?: Element | React.RefObject<Element> | string | null
+  /**
+   * Whether to enable rect tracking
+   */
+  enabled?: boolean
+  /**
+   * Throttle delay in milliseconds for rect updates
+   */
+  throttleMs?: number
+  /**
+   * Whether to use ResizeObserver for more accurate tracking
+   */
+  useResizeObserver?: boolean
+}
+
+const initialRect: RectState = {
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0
+}
+
+const isSSR = typeof window === 'undefined'
+const hasResizeObserver = !isSSR && typeof ResizeObserver !== 'undefined'
+
+/**
+ * Helper function to check if code is running on client side
+ */
+const isClientSide = (): boolean => !isSSR
+
+/**
+ * Custom hook that tracks an element's bounding rectangle and updates on resize, scroll, etc.
+ *
+ * @param options Configuration options for element rect tracking
+ * @returns The current bounding rectangle of the element
+ */
+export function useElementRect({
+  element,
+  enabled = true,
+  throttleMs = 100,
+  useResizeObserver = true
+}: ElementRectOptions = {}): RectState {
+  const [rect, setRect] = useState<RectState>(initialRect)
+
+  const getTargetElement = useCallback((): Element | null => {
+    if (!enabled || !isClientSide()) return null
+
+    if (!element) {
+      return document.body
+    }
+
+    if (typeof element === 'string') {
+      return document.querySelector(element)
+    }
+
+    if ('current' in element) {
+      return element.current
+    }
+
+    return element
+  }, [element, enabled])
+
+  const updateRect = useThrottledCallback(
+    () => {
+      if (!enabled || !isClientSide()) return
+
+      const targetElement = getTargetElement()
+      if (!targetElement) {
+        setRect(initialRect)
+        return
+      }
+
+      const newRect = targetElement.getBoundingClientRect()
+      setRect({
+        x: newRect.x,
+        y: newRect.y,
+        width: newRect.width,
+        height: newRect.height,
+        top: newRect.top,
+        right: newRect.right,
+        bottom: newRect.bottom,
+        left: newRect.left
+      })
+    },
+    throttleMs,
+    [enabled, getTargetElement],
+    { leading: true, trailing: true }
+  )
+
+  useEffect(() => {
+    if (!enabled || !isClientSide()) {
+      setRect(initialRect)
+      return
+    }
+
+    const targetElement = getTargetElement()
+    if (!targetElement) return
+
+    updateRect()
+
+    const cleanup: (() => void)[] = []
+
+    if (useResizeObserver && hasResizeObserver) {
+      const resizeObserver = new ResizeObserver(() => {
+        window.requestAnimationFrame(updateRect)
+      })
+      resizeObserver.observe(targetElement)
+      cleanup.push(() => resizeObserver.disconnect())
+    }
+
+    const handleUpdate = () => updateRect()
+
+    window.addEventListener('scroll', handleUpdate, true)
+    window.addEventListener('resize', handleUpdate, true)
+
+    cleanup.push(() => {
+      window.removeEventListener('scroll', handleUpdate)
+      window.removeEventListener('resize', handleUpdate)
+    })
+
+    return () => {
+      cleanup.forEach((fn) => {
+        fn()
+      })
+      setRect(initialRect)
+    }
+  }, [enabled, getTargetElement, updateRect, useResizeObserver])
+
+  return rect
+}
+
+/**
+ * Convenience hook for tracking document.body rect
+ */
+export function useBodyRect(options: Omit<ElementRectOptions, 'element'> = {}): RectState {
+  return useElementRect({
+    ...options,
+    element: isClientSide() ? document.body : null
+  })
+}
+
+/**
+ * Convenience hook for tracking a ref element's rect
+ */
+export function useRefRect<T extends Element>(
+  ref: React.RefObject<T>,
+  options: Omit<ElementRectOptions, 'element'> = {}
+): RectState {
+  return useElementRect({ ...options, element: ref })
+}

package/templates/tiptap/hooks/use-is-breakpoint.ts

@@ -0,0 +1,32 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+type BreakpointMode = 'min' | 'max'
+
+/**
+ * Hook to detect whether the current viewport matches a given breakpoint rule.
+ * Example:
+ *   useIsBreakpoint("max", 768)   // true when width < 768
+ *   useIsBreakpoint("min", 1024)  // true when width >= 1024
+ */
+export function useIsBreakpoint(mode: BreakpointMode = 'max', breakpoint = 768) {
+  const [matches, setMatches] = useState<boolean | undefined>(undefined)
+
+  useEffect(() => {
+    const query =
+      mode === 'min' ? `(min-width: ${breakpoint}px)` : `(max-width: ${breakpoint - 1}px)`
+
+    const mql = window.matchMedia(query)
+    const onChange = (e: MediaQueryListEvent) => setMatches(e.matches)
+
+    // Set initial value
+    setMatches(mql.matches)
+
+    // Add listener
+    mql.addEventListener('change', onChange)
+    return () => mql.removeEventListener('change', onChange)
+  }, [mode, breakpoint])
+
+  return !!matches
+}

package/templates/tiptap/hooks/use-menu-navigation.ts

@@ -0,0 +1,182 @@
+'use client'
+
+import type { Editor } from '@tiptap/react'
+import { useEffect, useState } from 'react'
+
+type Orientation = 'horizontal' | 'vertical' | 'both'
+
+interface MenuNavigationOptions<T> {
+  /**
+   * The Tiptap editor instance, if using with a Tiptap editor.
+   */
+  editor?: Editor | null
+  /**
+   * Reference to the container element for handling keyboard events.
+   */
+  containerRef?: React.RefObject<HTMLElement | null>
+  /**
+   * Search query that affects the selected item.
+   */
+  query?: string
+  /**
+   * Array of items to navigate through.
+   */
+  items: T[]
+  /**
+   * Callback fired when an item is selected.
+   */
+  onSelect?: (item: T) => void
+  /**
+   * Callback fired when the menu should close.
+   */
+  onClose?: () => void
+  /**
+   * The navigation orientation of the menu.
+   * @default "vertical"
+   */
+  orientation?: Orientation
+  /**
+   * Whether to automatically select the first item when the menu opens.
+   * @default true
+   */
+  autoSelectFirstItem?: boolean
+}
+
+/**
+ * Hook that implements keyboard navigation for dropdown menus and command palettes.
+ *
+ * Handles arrow keys, tab, home/end, enter for selection, and escape to close.
+ * Works with both Tiptap editors and regular DOM elements.
+ *
+ * @param options - Configuration options for the menu navigation
+ * @returns Object containing the selected index and a setter function
+ */
+export function useMenuNavigation<T>({
+  editor,
+  containerRef,
+  query,
+  items,
+  onSelect,
+  onClose,
+  orientation = 'vertical',
+  autoSelectFirstItem = true
+}: MenuNavigationOptions<T>) {
+  const [selectedIndex, setSelectedIndex] = useState<number>(autoSelectFirstItem ? 0 : -1)
+
+  useEffect(() => {
+    const handleKeyboardNavigation = (event: KeyboardEvent) => {
+      if (!items.length) return false
+
+      const moveNext = () =>
+        setSelectedIndex((currentIndex) => {
+          if (currentIndex === -1) return 0
+          return (currentIndex + 1) % items.length
+        })
+
+      const movePrev = () =>
+        setSelectedIndex((currentIndex) => {
+          if (currentIndex === -1) return items.length - 1
+          return (currentIndex - 1 + items.length) % items.length
+        })
+
+      switch (event.key) {
+        case 'ArrowUp': {
+          if (orientation === 'horizontal') return false
+          event.preventDefault()
+          movePrev()
+          return true
+        }
+
+        case 'ArrowDown': {
+          if (orientation === 'horizontal') return false
+          event.preventDefault()
+          moveNext()
+          return true
+        }
+
+        case 'ArrowLeft': {
+          if (orientation === 'vertical') return false
+          event.preventDefault()
+          movePrev()
+          return true
+        }
+
+        case 'ArrowRight': {
+          if (orientation === 'vertical') return false
+          event.preventDefault()
+          moveNext()
+          return true
+        }
+
+        case 'Tab': {
+          event.preventDefault()
+          if (event.shiftKey) {
+            movePrev()
+          } else {
+            moveNext()
+          }
+          return true
+        }
+
+        case 'Home': {
+          event.preventDefault()
+          setSelectedIndex(0)
+          return true
+        }
+
+        case 'End': {
+          event.preventDefault()
+          setSelectedIndex(items.length - 1)
+          return true
+        }
+
+        case 'Enter': {
+          if (event.isComposing) return false
+          event.preventDefault()
+          if (selectedIndex !== -1 && items[selectedIndex]) {
+            onSelect?.(items[selectedIndex])
+          }
+          return true
+        }
+
+        case 'Escape': {
+          event.preventDefault()
+          onClose?.()
+          return true
+        }
+
+        default:
+          return false
+      }
+    }
+
+    let targetElement: HTMLElement | null = null
+
+    if (editor) {
+      targetElement = editor.view.dom
+    } else if (containerRef?.current) {
+      targetElement = containerRef.current
+    }
+
+    if (targetElement) {
+      targetElement.addEventListener('keydown', handleKeyboardNavigation, true)
+
+      return () => {
+        targetElement?.removeEventListener('keydown', handleKeyboardNavigation, true)
+      }
+    }
+
+    return undefined
+  }, [editor, containerRef, items, selectedIndex, onSelect, onClose, orientation])
+
+  useEffect(() => {
+    if (query) {
+      setSelectedIndex(autoSelectFirstItem ? 0 : -1)
+    }
+  }, [query, autoSelectFirstItem])
+
+  return {
+    selectedIndex: items.length ? selectedIndex : undefined,
+    setSelectedIndex
+  }
+}

package/templates/tiptap/hooks/use-scrolling.ts

@@ -0,0 +1,64 @@
+import type { RefObject } from 'react'
+import { useEffect, useState } from 'react'
+
+type ScrollTarget = RefObject<HTMLElement> | Window | null | undefined
+type EventTargetWithScroll = Window | HTMLElement | Document
+
+interface UseScrollingOptions {
+  debounce?: number
+  fallbackToDocument?: boolean
+}
+
+export function useScrolling(target?: ScrollTarget, options: UseScrollingOptions = {}): boolean {
+  const { debounce = 150, fallbackToDocument = true } = options
+  const [isScrolling, setIsScrolling] = useState(false)
+
+  useEffect(() => {
+    // Resolve element or window
+    const element: EventTargetWithScroll =
+      target && typeof Window !== 'undefined' && target instanceof Window
+        ? target
+        : ((target as RefObject<HTMLElement>)?.current ?? window)
+
+    // Mobile: fallback to document when using window
+    const eventTarget: EventTargetWithScroll =
+      fallbackToDocument && element === window && typeof document !== 'undefined'
+        ? document
+        : element
+
+    const on = (el: EventTargetWithScroll, event: string, handler: EventListener) =>
+      el.addEventListener(event, handler, true)
+
+    const off = (el: EventTargetWithScroll, event: string, handler: EventListener) =>
+      el.removeEventListener(event, handler)
+
+    let timeout: ReturnType<typeof setTimeout>
+    const supportsScrollEnd = element === window && 'onscrollend' in window
+
+    const handleScroll: EventListener = () => {
+      if (!isScrolling) setIsScrolling(true)
+
+      if (!supportsScrollEnd) {
+        clearTimeout(timeout)
+        timeout = setTimeout(() => setIsScrolling(false), debounce)
+      }
+    }
+
+    const handleScrollEnd: EventListener = () => setIsScrolling(false)
+
+    on(eventTarget, 'scroll', handleScroll)
+    if (supportsScrollEnd) {
+      on(eventTarget, 'scrollend', handleScrollEnd)
+    }
+
+    return () => {
+      off(eventTarget, 'scroll', handleScroll)
+      if (supportsScrollEnd) {
+        off(eventTarget, 'scrollend', handleScrollEnd)
+      }
+      clearTimeout(timeout)
+    }
+  }, [target, debounce, fallbackToDocument, isScrolling])
+
+  return isScrolling
+}

package/templates/tiptap/hooks/use-throttled-callback.ts

@@ -0,0 +1,146 @@
+import { useMemo } from 'react'
+import { useUnmount } from './use-unmount'
+
+interface ThrottleSettings {
+  leading?: boolean | undefined
+  trailing?: boolean | undefined
+}
+
+const defaultOptions: ThrottleSettings = {
+  leading: false,
+  trailing: true
+}
+
+type ThrottledFunction<T extends (...args: any[]) => any> = {
+  (this: ThisParameterType<T>, ...args: Parameters<T>): ReturnType<T> | undefined
+  cancel: () => void
+  flush: () => void
+}
+
+function throttle<T extends (...args: any[]) => any>(
+  fn: T,
+  wait: number,
+  options: ThrottleSettings = {}
+): ThrottledFunction<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null
+  let lastArgs: Parameters<T> | null = null
+  let lastThis: ThisParameterType<T> | null = null
+  let lastCallTime: number | undefined
+  let result: ReturnType<T> | undefined
+
+  const leading = options.leading ?? true
+  const trailing = options.trailing ?? true
+
+  function invokeFunc(): ReturnType<T> | undefined {
+    const args = lastArgs!
+    const thisArg = lastThis!
+    lastArgs = lastThis = null
+    result = fn.apply(thisArg, args)
+    return result
+  }
+
+  function startTimer(pendingFunc: () => void, remainingWait: number) {
+    timeoutId = setTimeout(pendingFunc, remainingWait)
+  }
+
+  function remainingWait(time: number): number {
+    const timeSinceLastCall = time - (lastCallTime ?? 0)
+    return Math.max(0, wait - timeSinceLastCall)
+  }
+
+  function shouldInvoke(time: number): boolean {
+    if (lastCallTime === undefined) return true
+    const timeSinceLastCall = time - lastCallTime
+    return timeSinceLastCall >= wait || timeSinceLastCall < 0
+  }
+
+  function trailingEdge() {
+    timeoutId = null
+    if (trailing && lastArgs) {
+      return invokeFunc()
+    }
+    lastArgs = lastThis = null
+    return result
+  }
+
+  function timerExpired() {
+    const time = Date.now()
+    if (shouldInvoke(time)) {
+      return trailingEdge()
+    }
+    startTimer(timerExpired, remainingWait(time))
+  }
+
+  function leadingEdge(): ReturnType<T> | undefined {
+    startTimer(timerExpired, wait)
+    return leading ? invokeFunc() : result
+  }
+
+  const throttled = function (
+    this: ThisParameterType<T>,
+    ...args: Parameters<T>
+  ): ReturnType<T> | undefined {
+    const time = Date.now()
+    const isInvoking = shouldInvoke(time)
+
+    lastArgs = args
+    lastThis = this
+    lastCallTime = time
+
+    if (isInvoking) {
+      if (timeoutId === null) {
+        return leadingEdge()
+      }
+      // Handle invocations in a tight loop
+      if (trailing) {
+        startTimer(timerExpired, wait)
+        return invokeFunc()
+      }
+    }
+    if (timeoutId === null) {
+      startTimer(timerExpired, wait)
+    }
+    return result
+  } as ThrottledFunction<T>
+
+  throttled.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId)
+    }
+    lastArgs = lastThis = null
+    lastCallTime = undefined
+    timeoutId = null
+  }
+
+  throttled.flush = () => {
+    if (timeoutId === null) return result
+    return trailingEdge()
+  }
+
+  return throttled
+}
+
+/**
+ * A hook that returns a throttled callback function.
+ *
+ * @param fn The function to throttle
+ * @param wait The time in ms to wait before calling the function
+ * @param dependencies The dependencies to watch for changes
+ * @param options The throttle options
+ */
+export function useThrottledCallback<T extends (...args: any[]) => any>(
+  fn: T,
+  wait = 250,
+  dependencies: React.DependencyList = [],
+  options: ThrottleSettings = defaultOptions
+): ThrottledFunction<T> {
+  const handler = useMemo(() => throttle<T>(fn, wait, options), dependencies)
+
+  useUnmount(() => {
+    handler.cancel()
+  })
+
+  return handler
+}
+
+export default useThrottledCallback