betterstart-cli 0.0.1

package/dist/assets/adapters/next/templates/init/hooks/content-editor/use-menu-navigation.ts

@@ -0,0 +1,221 @@
+'use client'
+
+import type { Editor } from '@tiptap/react'
+import { useCallback, useEffect, useState } from 'react'
+
+type Orientation = 'horizontal' | 'vertical' | 'both'
+type SelectedIndexUpdater = number | ((currentIndex: number) => number)
+
+interface SelectionState {
+  autoSelectFirstItem: boolean
+  query: string | undefined
+  selectedIndex: number
+}
+
+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 initialSelectedIndex = autoSelectFirstItem ? 0 : -1
+  const [selection, setSelection] = useState<SelectionState>(() => ({
+    autoSelectFirstItem,
+    query,
+    selectedIndex: initialSelectedIndex
+  }))
+  const didTrackedInputChange =
+    selection.query !== query || selection.autoSelectFirstItem !== autoSelectFirstItem
+  const nextSelectedIndex = query ? initialSelectedIndex : selection.selectedIndex
+
+  if (didTrackedInputChange) {
+    // Restart render immediately so query changes reset before paint without an effect.
+    setSelection({
+      autoSelectFirstItem,
+      query,
+      selectedIndex: nextSelectedIndex
+    })
+  }
+
+  const selectedIndex = didTrackedInputChange ? nextSelectedIndex : selection.selectedIndex
+  const setSelectedIndex = useCallback(
+    (value: SelectedIndexUpdater) => {
+      setSelection((currentSelection) => {
+        const didCurrentInputChange =
+          currentSelection.query !== query ||
+          currentSelection.autoSelectFirstItem !== autoSelectFirstItem
+        const currentSelectedIndex =
+          didCurrentInputChange && query ? initialSelectedIndex : currentSelection.selectedIndex
+        const nextSelectedIndex = typeof value === 'function' ? value(currentSelectedIndex) : value
+
+        return {
+          autoSelectFirstItem,
+          query,
+          selectedIndex: nextSelectedIndex
+        }
+      })
+    },
+    [autoSelectFirstItem, initialSelectedIndex, query]
+  )
+
+  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, setSelectedIndex, onSelect, onClose, orientation])
+
+  return {
+    selectedIndex: items.length ? selectedIndex : undefined,
+    setSelectedIndex
+  }
+}

package/dist/assets/adapters/next/templates/init/hooks/content-editor/use-tiptap-editor.ts

@@ -0,0 +1,46 @@
+'use client'
+
+import type { Editor } from '@tiptap/react'
+import { useCurrentEditor, useEditorState } from '@tiptap/react'
+import { useMemo } from 'react'
+
+/**
+ * Hook that provides access to a Tiptap editor instance.
+ *
+ * Accepts an optional editor instance directly, or falls back to retrieving
+ * the editor from the Tiptap context if available. This allows components
+ * to work both when given an editor directly and when used within a Tiptap
+ * editor context.
+ *
+ * @param providedEditor - Optional editor instance to use instead of the context editor
+ * @returns The provided editor or the editor from context, whichever is available
+ */
+export function useTiptapEditor(providedEditor?: Editor | null): {
+  editor: Editor | null
+  editorState?: Editor['state']
+  canCommand?: Editor['can']
+} {
+  const { editor: coreEditor } = useCurrentEditor()
+  const mainEditor = useMemo(() => providedEditor || coreEditor, [providedEditor, coreEditor])
+
+  const editorState = useEditorState({
+    editor: mainEditor,
+    selector(context) {
+      if (!context.editor) {
+        return {
+          editor: null,
+          editorState: undefined,
+          canCommand: undefined
+        }
+      }
+
+      return {
+        editor: context.editor,
+        editorState: context.editor.state,
+        canCommand: context.editor.can
+      }
+    }
+  })
+
+  return editorState || { editor: null }
+}

package/dist/assets/adapters/next/templates/init/hooks/content-editor/use-undo-redo.ts

@@ -0,0 +1,169 @@
+'use client'
+
+// --- Hooks ---
+import { useTiptapEditor } from '@admin/hooks/content-editor/use-tiptap-editor'
+// --- Lib ---
+import { isNodeTypeSelected } from '@admin/utils/editor/tiptap'
+import type { Editor } from '@tiptap/react'
+// --- Icons ---
+import { Redo2Icon, Undo2Icon } from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+
+export type UndoRedoAction = 'undo' | 'redo'
+
+/**
+ * Configuration for the history functionality
+ */
+export interface UseUndoRedoConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * The history action to perform (undo or redo).
+   */
+  action: UndoRedoAction
+  /**
+   * Whether the button should hide when action is not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called after a successful action execution.
+   */
+  onExecuted?: () => void
+}
+
+export const UNDO_REDO_SHORTCUT_KEYS: Record<UndoRedoAction, string> = {
+  undo: 'mod+z',
+  redo: 'mod+shift+z'
+}
+
+export const historyActionLabels: Record<UndoRedoAction, string> = {
+  undo: 'Undo',
+  redo: 'Redo'
+}
+
+export const historyIcons = {
+  undo: Undo2Icon,
+  redo: Redo2Icon
+}
+
+/**
+ * Checks if a history action can be executed
+ */
+export function canExecuteUndoRedoAction(editor: Editor | null, action: UndoRedoAction): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (isNodeTypeSelected(editor, ['image'])) return false
+
+  return action === 'undo' ? editor.can().undo() : editor.can().redo()
+}
+
+/**
+ * Executes a history action on the editor
+ */
+export function executeUndoRedoAction(editor: Editor | null, action: UndoRedoAction): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!canExecuteUndoRedoAction(editor, action)) return false
+
+  const chain = editor.chain().focus()
+  return action === 'undo' ? chain.undo().run() : chain.redo().run()
+}
+
+/**
+ * Determines if the history button should be shown
+ */
+export function shouldShowButton(props: {
+  editor: Editor | null
+  hideWhenUnavailable: boolean
+  action: UndoRedoAction
+}): boolean {
+  const { editor, hideWhenUnavailable, action } = props
+
+  if (!editor || !editor.isEditable) return false
+
+  if (hideWhenUnavailable && !editor.isActive('code')) {
+    return canExecuteUndoRedoAction(editor, action)
+  }
+
+  return true
+}
+
+/**
+ * Custom hook that provides history functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * function MySimpleUndoButton() {
+ *   const { isVisible, handleAction } = useHistory({ action: "undo" })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return <button onClick={handleAction}>Undo</button>
+ * }
+ *
+ * // Advanced usage with configuration
+ * function MyAdvancedRedoButton() {
+ *   const { isVisible, handleAction, label } = useHistory({
+ *     editor: myEditor,
+ *     action: "redo",
+ *     hideWhenUnavailable: true,
+ *     onExecuted: () => console.log('Action executed!')
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       onClick={handleAction}
+ *       aria-label={label}
+ *     >
+ *       Redo
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+export function useUndoRedo(config: UseUndoRedoConfig) {
+  const { editor: providedEditor, action, hideWhenUnavailable = false, onExecuted } = config
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const [isVisible, setIsVisible] = useState<boolean>(true)
+  const canExecute = canExecuteUndoRedoAction(editor, action)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleUpdate = () => {
+      setIsVisible(shouldShowButton({ editor, hideWhenUnavailable, action }))
+    }
+
+    handleUpdate()
+
+    editor.on('transaction', handleUpdate)
+
+    return () => {
+      editor.off('transaction', handleUpdate)
+    }
+  }, [editor, hideWhenUnavailable, action])
+
+  const handleAction = useCallback(() => {
+    if (!editor) return false
+
+    const success = executeUndoRedoAction(editor, action)
+    if (success) {
+      onExecuted?.()
+    }
+    return success
+  }, [editor, action, onExecuted])
+
+  return {
+    isVisible,
+    handleAction,
+    canExecute,
+    label: historyActionLabels[action],
+    shortcutKeys: UNDO_REDO_SHORTCUT_KEYS[action],
+    Icon: historyIcons[action]
+  }
+}

package/dist/assets/adapters/next/templates/init/hooks/use-admin-theme.tsx

@@ -0,0 +1,74 @@
+'use client'
+
+import { getSystemTheme, type ResolvedTheme } from '@admin/utils/theme/system'
+import * as React from 'react'
+
+type Theme = 'light' | 'dark' | 'system'
+
+interface ThemeContext {
+  theme: Theme
+  setTheme: (theme: Theme) => void
+  resolvedTheme: ResolvedTheme
+}
+
+const AdminThemeContext = React.createContext<ThemeContext | undefined>(undefined)
+
+const STORAGE_KEY = 'admin-theme'
+
+export function AdminThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setThemeState] = React.useState<Theme>('system')
+  const [resolved, setResolved] = React.useState<ResolvedTheme>('light')
+
+  // Read from localStorage on mount
+  React.useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY) as Theme | null
+    if (stored && ['light', 'dark', 'system'].includes(stored)) {
+      setThemeState(stored)
+    }
+  }, [])
+
+  // Resolve theme and apply .dark class to .admin-root
+  React.useEffect(() => {
+    const actual = theme === 'system' ? getSystemTheme() : theme
+    setResolved(actual)
+
+    const root = document.querySelector('.admin-root')
+    if (root) {
+      root.classList.toggle('dark', actual === 'dark')
+    }
+  }, [theme])
+
+  // Listen for system theme changes
+  React.useEffect(() => {
+    if (theme !== 'system') return
+    const mq = window.matchMedia('(prefers-color-scheme: dark)')
+    const handler = () => {
+      const actual = getSystemTheme()
+      setResolved(actual)
+      const root = document.querySelector('.admin-root')
+      if (root) {
+        root.classList.toggle('dark', actual === 'dark')
+      }
+    }
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [theme])
+
+  const setTheme = React.useCallback((t: Theme) => {
+    setThemeState(t)
+    localStorage.setItem(STORAGE_KEY, t)
+  }, [])
+
+  const value = React.useMemo(
+    () => ({ theme, setTheme, resolvedTheme: resolved }),
+    [theme, setTheme, resolved]
+  )
+
+  return <AdminThemeContext.Provider value={value}>{children}</AdminThemeContext.Provider>
+}
+
+export function useTheme(): ThemeContext {
+  const ctx = React.use(AdminThemeContext)
+  if (!ctx) throw new Error('useTheme must be used within AdminThemeProvider')
+  return ctx
+}

package/dist/assets/adapters/next/templates/init/hooks/use-copy-to-clipboard.ts

@@ -0,0 +1,48 @@
+'use client'
+
+import * as React from 'react'
+
+type CopyFn = (text: string) => Promise<boolean>
+
+export function useCopyToClipboard(delay = 2000): [CopyFn, boolean] {
+  const [isCopied, setIsCopied] = React.useState(false)
+  const resetTimerRef = React.useRef<number | null>(null)
+
+  const clearResetTimer = React.useCallback(() => {
+    if (resetTimerRef.current === null) {
+      return
+    }
+
+    window.clearTimeout(resetTimerRef.current)
+    resetTimerRef.current = null
+  }, [])
+
+  const copy: CopyFn = React.useCallback(
+    async (text) => {
+      clearResetTimer()
+
+      if (typeof navigator === 'undefined' || !navigator.clipboard) {
+        console.warn('Clipboard not supported')
+        setIsCopied(false)
+        return false
+      }
+
+      try {
+        await navigator.clipboard.writeText(text)
+        setIsCopied(true)
+        resetTimerRef.current = window.setTimeout(() => {
+          setIsCopied(false)
+          resetTimerRef.current = null
+        }, delay)
+        return true
+      } catch (error) {
+        console.warn('Copy failed', error)
+        setIsCopied(false)
+        return false
+      }
+    },
+    [clearResetTimer, delay]
+  )
+
+  return [copy, isCopied]
+}

package/dist/assets/adapters/next/templates/init/hooks/use-dev-mode-integration.ts

@@ -0,0 +1,43 @@
+'use client'
+
+import type {
+  DevModeIntegration,
+  DevModeIntegrationLoader
+} from '@admin/components/shared/dev-mode/dev-mode-types'
+import * as React from 'react'
+
+export function useDevModeIntegration(loadIntegration: DevModeIntegrationLoader) {
+  const [integration, setIntegration] = React.useState<DevModeIntegration | null>(null)
+  const [loadError, setLoadError] = React.useState<string | null>(null)
+  const [isPending, startTransition] = React.useTransition()
+  const integrationPromiseRef = React.useRef<Promise<DevModeIntegration> | null>(null)
+
+  const handleOpenChange = React.useCallback(
+    (open: boolean) => {
+      if (!open || integration || integrationPromiseRef.current) {
+        return
+      }
+
+      startTransition(async () => {
+        try {
+          integrationPromiseRef.current = loadIntegration()
+          const nextIntegration = await integrationPromiseRef.current
+          setIntegration(nextIntegration)
+          setLoadError(null)
+        } catch (error) {
+          integrationPromiseRef.current = null
+          console.error(error)
+          setLoadError('Integration details could not be loaded.')
+        }
+      })
+    },
+    [integration, loadIntegration]
+  )
+
+  return {
+    integration,
+    isPending,
+    loadError,
+    handleOpenChange
+  }
+}

package/dist/assets/adapters/next/templates/init/hooks/use-entity-versions.ts

@@ -0,0 +1,32 @@
+'use client'
+
+import type { EntityVersionWithAuthor } from '@admin/actions/entity-versions'
+import * as React from 'react'
+import { toast } from 'sonner'
+
+interface UseEntityVersionsOptions {
+  entityId: string
+  getVersionsAction: (entityId: string) => Promise<EntityVersionWithAuthor[]>
+}
+
+export function useEntityVersions({ entityId, getVersionsAction }: UseEntityVersionsOptions) {
+  const [versions, setVersions] = React.useState<EntityVersionWithAuthor[]>([])
+  const [isPending, startTransition] = React.useTransition()
+
+  const load = React.useCallback(() => {
+    startTransition(async () => {
+      try {
+        const nextVersions = await getVersionsAction(entityId)
+        setVersions(nextVersions)
+      } catch (error) {
+        toast.error(error instanceof Error ? error.message : 'Failed to load versions')
+      }
+    })
+  }, [entityId, getVersionsAction])
+
+  return {
+    versions,
+    isPending,
+    load
+  }
+}

package/dist/assets/adapters/next/templates/init/hooks/use-failed-image-url.ts

@@ -0,0 +1,21 @@
+'use client'
+
+import * as React from 'react'
+
+interface FailedImageUrlState {
+  hasImageFailed: boolean
+  markImageFailed: () => void
+}
+
+export function useFailedImageUrl(imageUrl: string): FailedImageUrlState {
+  const [failedImageUrl, setFailedImageUrl] = React.useState<string | null>(null)
+
+  const markImageFailed = React.useCallback(() => {
+    setFailedImageUrl(imageUrl)
+  }, [imageUrl])
+
+  return {
+    hasImageFailed: failedImageUrl === imageUrl,
+    markImageFailed
+  }
+}

package/dist/assets/adapters/next/templates/init/hooks/use-local-storage.ts

@@ -0,0 +1,46 @@
+import * as React from 'react'
+
+const ADMIN_STORAGE_PREFIX = 'admin-'
+
+/** Type-safe wrapper for localStorage operations with admin- prefix. */
+export function useLocalStorage<T>(key: string) {
+  const prefixedKey = ADMIN_STORAGE_PREFIX + key
+
+  const setItem = React.useCallback(
+    (value: T) => {
+      try {
+        localStorage.setItem(prefixedKey, JSON.stringify(value))
+      } catch {
+        // Silent failure for localStorage access errors
+      }
+    },
+    [prefixedKey]
+  )
+
+  const getItem = React.useCallback((): T | null => {
+    try {
+      const stored = localStorage.getItem(prefixedKey)
+      return stored ? JSON.parse(stored) : null
+    } catch {
+      return null
+    }
+  }, [prefixedKey])
+
+  const removeItem = React.useCallback(() => {
+    try {
+      localStorage.removeItem(prefixedKey)
+    } catch {
+      // Silent failure for localStorage access errors
+    }
+  }, [prefixedKey])
+
+  const hasItem = React.useCallback((): boolean => {
+    try {
+      return localStorage.getItem(prefixedKey) !== null
+    } catch {
+      return false
+    }
+  }, [prefixedKey])
+
+  return { setItem, getItem, removeItem, hasItem }
+}