betterstart-cli 0.0.1

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

@@ -0,0 +1,269 @@
+'use client'
+
+// --- Hooks ---
+import { useTiptapEditor } from '@admin/hooks/content-editor/use-tiptap-editor'
+// --- Lib ---
+import {
+  findNodePosition,
+  getSelectedBlockNodes,
+  isNodeInSchema,
+  isNodeTypeSelected,
+  isValidPosition,
+  selectionWithinConvertibleTypes
+} from '@admin/utils/editor/tiptap'
+import { NodeSelection, TextSelection } from '@tiptap/pm/state'
+import type { Editor } from '@tiptap/react'
+// --- Icons ---
+import {
+  Heading5Icon as HeadingFiveIcon,
+  Heading4Icon as HeadingFourIcon,
+  Heading1Icon as HeadingOneIcon,
+  Heading6Icon as HeadingSixIcon,
+  Heading3Icon as HeadingThreeIcon,
+  Heading2Icon as HeadingTwoIcon
+} from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+
+export type Level = 1 | 2 | 3 | 4 | 5 | 6
+
+/**
+ * Configuration for the heading functionality
+ */
+export interface UseHeadingConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * The heading level.
+   */
+  level: Level
+  /**
+   * Whether the button should hide when heading is not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called after a successful heading toggle.
+   */
+  onToggled?: () => void
+}
+
+export const headingIcons = {
+  1: HeadingOneIcon,
+  2: HeadingTwoIcon,
+  3: HeadingThreeIcon,
+  4: HeadingFourIcon,
+  5: HeadingFiveIcon,
+  6: HeadingSixIcon
+}
+
+export const HEADING_SHORTCUT_KEYS: Record<Level, string> = {
+  1: 'ctrl+alt+1',
+  2: 'ctrl+alt+2',
+  3: 'ctrl+alt+3',
+  4: 'ctrl+alt+4',
+  5: 'ctrl+alt+5',
+  6: 'ctrl+alt+6'
+}
+
+/**
+ * Checks if heading can be toggled in the current editor state
+ */
+export function canToggle(editor: Editor | null, level?: Level, turnInto: boolean = true): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!isNodeInSchema('heading', editor) || isNodeTypeSelected(editor, ['image'])) return false
+
+  if (!turnInto) {
+    return level ? editor.can().setNode('heading', { level }) : editor.can().setNode('heading')
+  }
+
+  // Ensure selection is in nodes we're allowed to convert
+  if (
+    !selectionWithinConvertibleTypes(editor, [
+      'paragraph',
+      'heading',
+      'bulletList',
+      'orderedList',
+      'taskList',
+      'blockquote',
+      'codeBlock'
+    ])
+  )
+    return false
+
+  // Either we can set heading directly on the selection,
+  // or we can clear formatting/nodes to arrive at a heading.
+  return level
+    ? editor.can().setNode('heading', { level }) || editor.can().clearNodes()
+    : editor.can().setNode('heading') || editor.can().clearNodes()
+}
+
+/**
+ * Checks if heading is currently active
+ */
+export function isHeadingActive(editor: Editor | null, level?: Level | Level[]): boolean {
+  if (!editor || !editor.isEditable) return false
+
+  if (Array.isArray(level)) {
+    return level.some((l) => editor.isActive('heading', { level: l }))
+  }
+
+  return level ? editor.isActive('heading', { level }) : editor.isActive('heading')
+}
+
+/**
+ * Toggles heading in the editor
+ */
+export function toggleHeading(editor: Editor | null, level: Level | Level[]): boolean {
+  if (!editor || !editor.isEditable) return false
+
+  const levels = Array.isArray(level) ? level : [level]
+  const toggleLevel = levels.find((l) => canToggle(editor, l))
+
+  if (!toggleLevel) return false
+
+  try {
+    const view = editor.view
+    let state = view.state
+    let tr = state.tr
+
+    const blocks = getSelectedBlockNodes(editor)
+
+    // In case a selection contains multiple blocks, we only allow
+    // toggling to nide if there's exactly one block selected
+    // we also dont block the canToggle since it will fall back to the bottom logic
+    const isPossibleToTurnInto =
+      selectionWithinConvertibleTypes(editor, [
+        'paragraph',
+        'heading',
+        'bulletList',
+        'orderedList',
+        'taskList',
+        'blockquote',
+        'codeBlock'
+      ]) && blocks.length === 1
+
+    // No selection, find the the cursor position
+    if (
+      (state.selection.empty || state.selection instanceof TextSelection) &&
+      isPossibleToTurnInto
+    ) {
+      const pos = findNodePosition({
+        editor,
+        node: state.selection.$anchor.node(1)
+      })?.pos
+      if (!isValidPosition(pos)) return false
+
+      tr = tr.setSelection(NodeSelection.create(state.doc, pos))
+      view.dispatch(tr)
+      state = view.state
+    }
+
+    const selection = state.selection
+    let chain = editor.chain().focus()
+
+    // Handle NodeSelection
+    if (selection instanceof NodeSelection) {
+      const firstChild = selection.node.firstChild?.firstChild
+      const lastChild = selection.node.lastChild?.lastChild
+
+      const from = firstChild ? selection.from + firstChild.nodeSize : selection.from + 1
+
+      const to = lastChild ? selection.to - lastChild.nodeSize : selection.to - 1
+
+      const resolvedFrom = state.doc.resolve(from)
+      const resolvedTo = state.doc.resolve(to)
+
+      chain = chain.setTextSelection(TextSelection.between(resolvedFrom, resolvedTo)).clearNodes()
+    }
+
+    const isActive = levels.some((l) => editor.isActive('heading', { level: l }))
+
+    const toggle = isActive
+      ? chain.setNode('paragraph')
+      : chain.setNode('heading', { level: toggleLevel })
+
+    toggle.run()
+
+    editor.chain().focus().selectTextblockEnd().run()
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Determines if the heading button should be shown
+ */
+export function shouldShowButton(props: {
+  editor: Editor | null
+  level?: Level | Level[]
+  hideWhenUnavailable: boolean
+}): boolean {
+  const { editor, level, hideWhenUnavailable } = props
+
+  if (!editor || !editor.isEditable) return false
+
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  if (!isNodeInSchema('heading', editor)) return false
+
+  if (!editor.isActive('code')) {
+    if (Array.isArray(level)) {
+      return level.some((l) => canToggle(editor, l))
+    }
+    return canToggle(editor, level)
+  }
+
+  return true
+}
+
+/** Provides heading commands for ContentEditor controls. */
+export function useHeading(config: UseHeadingConfig) {
+  const { editor: providedEditor, level, hideWhenUnavailable = false, onToggled } = config
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const [isVisible, setIsVisible] = useState<boolean>(true)
+  const canToggleState = canToggle(editor, level)
+  const isActive = isHeadingActive(editor, level)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(shouldShowButton({ editor, level, hideWhenUnavailable }))
+    }
+
+    handleSelectionUpdate()
+
+    editor.on('selectionUpdate', handleSelectionUpdate)
+
+    return () => {
+      editor.off('selectionUpdate', handleSelectionUpdate)
+    }
+  }, [editor, level, hideWhenUnavailable])
+
+  const handleToggle = useCallback(() => {
+    if (!editor) return false
+
+    const success = toggleHeading(editor, level)
+    if (success) {
+      onToggled?.()
+    }
+    return success
+  }, [editor, level, onToggled])
+
+  return {
+    isVisible,
+    isActive,
+    handleToggle,
+    canToggle: canToggleState,
+    label: `Heading ${level}`,
+    shortcutKeys: HEADING_SHORTCUT_KEYS[level],
+    Icon: headingIcons[level]
+  }
+}

package/dist/assets/adapters/next/templates/init/hooks/content-editor/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/dist/assets/adapters/next/templates/init/hooks/content-editor/use-link-popover.ts

@@ -0,0 +1,278 @@
+'use client'
+
+// --- Hooks ---
+import { useTiptapEditor } from '@admin/hooks/content-editor/use-tiptap-editor'
+// --- Lib ---
+import { isMarkInSchema, isNodeTypeSelected, sanitizeUrl } from '@admin/utils/editor/tiptap'
+import type { Editor } from '@tiptap/react'
+// --- Icons ---
+import { LinkIcon } from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+
+/**
+ * Configuration for the link popover functionality
+ */
+export interface UseLinkPopoverConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * Whether to hide the link popover when not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called when the link is set.
+   */
+  onSetLink?: () => void
+}
+
+/**
+ * Configuration for the link handler functionality
+ */
+export interface LinkHandlerProps {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor: Editor | null
+  /**
+   * Callback function called when the link is set.
+   */
+  onSetLink?: () => void
+}
+
+/**
+ * Checks if a link can be set in the current editor state
+ */
+export function canSetLink(editor: Editor | null): boolean {
+  if (!editor || !editor.isEditable) return false
+
+  // The third argument 'true' checks whether the current selection is inside an image caption, and prevents setting a link there
+  // If the selection is inside an image caption, we can't set a link
+  if (isNodeTypeSelected(editor, ['image'], true)) return false
+  try {
+    return editor.can().setMark('link')
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Checks if a link is currently active in the editor
+ */
+export function isLinkActive(editor: Editor | null): boolean {
+  if (!editor || !editor.isEditable) return false
+  return editor.isActive('link')
+}
+
+/**
+ * Determines if the link button should be shown
+ */
+export function shouldShowLinkButton(props: {
+  editor: Editor | null
+  hideWhenUnavailable: boolean
+}): boolean {
+  const { editor, hideWhenUnavailable } = props
+
+  if (!editor || !editor.isEditable) return false
+
+  const linkInSchema = isMarkInSchema('link', editor)
+
+  // If hideWhenUnavailable is false, always show the button (even if disabled)
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  // hideWhenUnavailable is true: hide if link is not in schema
+  if (!linkInSchema) {
+    return false
+  }
+
+  // hideWhenUnavailable is true: hide if we can't set a link (unless in code block)
+  if (!editor.isActive('code')) {
+    return canSetLink(editor)
+  }
+
+  return true
+}
+
+/**
+ * Custom hook for handling link operations in a Tiptap editor
+ */
+export function useLinkHandler(props: LinkHandlerProps) {
+  const { editor, onSetLink } = props
+  const [url, setUrl] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const updateLinkState = () => {
+      const { href } = editor.getAttributes('link')
+      setUrl(href || '')
+    }
+
+    updateLinkState()
+    editor.on('selectionUpdate', updateLinkState)
+    editor.on('update', updateLinkState)
+
+    return () => {
+      editor.off('selectionUpdate', updateLinkState)
+      editor.off('update', updateLinkState)
+    }
+  }, [editor])
+
+  const setLink = useCallback(() => {
+    if (!url || !editor) return
+
+    const { selection } = editor.state
+    const isEmpty = selection.empty
+
+    let chain = editor.chain().focus()
+
+    chain = chain.extendMarkRange('link').setLink({ href: url })
+
+    if (isEmpty) {
+      chain = chain.insertContent({ type: 'text', text: url })
+    }
+
+    chain.run()
+
+    setUrl(null)
+
+    onSetLink?.()
+  }, [editor, onSetLink, url])
+
+  const removeLink = useCallback(() => {
+    if (!editor) return
+    editor
+      .chain()
+      .focus()
+      .extendMarkRange('link')
+      .unsetLink()
+      .setMeta('preventAutolink', true)
+      .run()
+    setUrl('')
+  }, [editor])
+
+  const openLink = useCallback(
+    (target: string = '_blank', features: string = 'noopener,noreferrer') => {
+      if (!url) return
+
+      const safeUrl = sanitizeUrl(url, window.location.href)
+      if (safeUrl !== '#') {
+        window.open(safeUrl, target, features)
+      }
+    },
+    [url]
+  )
+
+  return {
+    url: url || '',
+    setUrl,
+    setLink,
+    removeLink,
+    openLink
+  }
+}
+
+/**
+ * Custom hook for link popover state management
+ */
+export function useLinkState(props: { editor: Editor | null; hideWhenUnavailable: boolean }) {
+  const { editor, hideWhenUnavailable = false } = props
+
+  const canSet = canSetLink(editor)
+  const isActive = isLinkActive(editor)
+
+  const [isVisible, setIsVisible] = useState(true)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(
+        shouldShowLinkButton({
+          editor,
+          hideWhenUnavailable
+        })
+      )
+    }
+
+    handleSelectionUpdate()
+
+    editor.on('selectionUpdate', handleSelectionUpdate)
+
+    return () => {
+      editor.off('selectionUpdate', handleSelectionUpdate)
+    }
+  }, [editor, hideWhenUnavailable])
+
+  return {
+    isVisible,
+    canSet,
+    isActive
+  }
+}
+
+/**
+ * Main hook that provides link popover functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * function MyLinkButton() {
+ *   const { isVisible, canSet, isActive, Icon, label } = useLinkPopover()
+ *
+ *   if (!isVisible) return null
+ *
+ *   return <button disabled={!canSet}>Link</button>
+ * }
+ *
+ * // Advanced usage with configuration
+ * function MyAdvancedLinkButton() {
+ *   const { isVisible, canSet, isActive, Icon, label } = useLinkPopover({
+ *     editor: myEditor,
+ *     hideWhenUnavailable: true,
+ *     onSetLink: () => console.log('Link set!')
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       disabled={!canSet}
+ *       aria-label={label}
+ *       aria-pressed={isActive}
+ *     >
+ *       <Icon />
+ *       {label}
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+export function useLinkPopover(config?: UseLinkPopoverConfig) {
+  const { editor: providedEditor, hideWhenUnavailable = false, onSetLink } = config || {}
+
+  const { editor } = useTiptapEditor(providedEditor)
+
+  const { isVisible, canSet, isActive } = useLinkState({
+    editor,
+    hideWhenUnavailable
+  })
+
+  const linkHandler = useLinkHandler({
+    editor,
+    onSetLink
+  })
+
+  return {
+    isVisible,
+    canSet,
+    isActive,
+    label: 'Link',
+    Icon: LinkIcon,
+    ...linkHandler
+  }
+}