@betterstart/cli 0.1.3 → 0.1.5

package/templates/tiptap/tiptap-ui/heading-button/heading-button.tsx

@@ -0,0 +1,107 @@
+'use client'
+
+import { forwardRef, useCallback } from 'react'
+import { useTiptapEditor } from '../../hooks/use-tiptap-editor'
+// --- Lib ---
+import { parseShortcutKeys } from '../../lib/tiptap-utils'
+import { Badge } from '../../tiptap-ui-primitive/badge'
+
+// --- UI Primitives ---
+import type { ButtonProps } from '../../tiptap-ui-primitive/button'
+import { Button } from '../../tiptap-ui-primitive/button'
+// --- Tiptap UI ---
+import type { Level, UseHeadingConfig } from '.'
+import { HEADING_SHORTCUT_KEYS, useHeading } from '.'
+
+export interface HeadingButtonProps extends Omit<ButtonProps, 'type'>, UseHeadingConfig {
+  /**
+   * Optional text to display alongside the icon.
+   */
+  text?: string
+  /**
+   * Optional show shortcut keys in the button.
+   * @default false
+   */
+  showShortcut?: boolean
+}
+
+export function HeadingShortcutBadge({
+  level,
+  shortcutKeys = HEADING_SHORTCUT_KEYS[level]
+}: {
+  level: Level
+  shortcutKeys?: string
+}) {
+  return <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>
+}
+
+/**
+ * Button component for toggling heading in a Tiptap editor.
+ *
+ * For custom button implementations, use the `useHeading` hook instead.
+ */
+export const HeadingButton = forwardRef<HTMLButtonElement, HeadingButtonProps>(
+  (
+    {
+      editor: providedEditor,
+      level,
+      text,
+      hideWhenUnavailable = false,
+      onToggled,
+      showShortcut = false,
+      onClick,
+      children,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const { editor } = useTiptapEditor(providedEditor)
+    const { isVisible, canToggle, isActive, handleToggle, label, Icon, shortcutKeys } = useHeading({
+      editor,
+      level,
+      hideWhenUnavailable,
+      onToggled
+    })
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event)
+        if (event.defaultPrevented) return
+        handleToggle()
+      },
+      [handleToggle, onClick]
+    )
+
+    if (!isVisible) {
+      return null
+    }
+
+    return (
+      <Button
+        type="button"
+        variant="ghost"
+        data-active-state={isActive ? 'on' : 'off'}
+        role="button"
+        tabIndex={-1}
+        disabled={!canToggle}
+        data-disabled={!canToggle}
+        aria-label={label}
+        aria-pressed={isActive}
+        tooltip={label}
+        onClick={handleClick}
+        {...buttonProps}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <Icon className="tiptap-button-icon" />
+            {text && <span className="tiptap-button-text">{text}</span>}
+            {showShortcut && <HeadingShortcutBadge level={level} shortcutKeys={shortcutKeys} />}
+          </>
+        )}
+      </Button>
+    )
+  }
+)
+
+HeadingButton.displayName = 'HeadingButton'

package/templates/tiptap/tiptap-ui/heading-button/index.tsx

@@ -0,0 +1,2 @@
+export * from './heading-button'
+export * from './use-heading'

package/templates/tiptap/tiptap-ui/heading-button/use-heading.ts

@@ -0,0 +1,314 @@
+'use client'
+
+import { NodeSelection, TextSelection } from '@tiptap/pm/state'
+import type { Editor } from '@tiptap/react'
+import { useCallback, useEffect, useState } from 'react'
+
+// --- Hooks ---
+import { useTiptapEditor } from '../../hooks/use-tiptap-editor'
+
+// --- Lib ---
+import {
+  findNodePosition,
+  getSelectedBlockNodes,
+  isNodeInSchema,
+  isNodeTypeSelected,
+  isValidPosition,
+  selectionWithinConvertibleTypes
+} from '../../lib/tiptap-utils'
+import { HeadingFiveIcon } from '../../tiptap-icons/heading-five-icon'
+import { HeadingFourIcon } from '../../tiptap-icons/heading-four-icon'
+// --- Icons ---
+import { HeadingOneIcon } from '../../tiptap-icons/heading-one-icon'
+import { HeadingSixIcon } from '../../tiptap-icons/heading-six-icon'
+import { HeadingThreeIcon } from '../../tiptap-icons/heading-three-icon'
+import { HeadingTwoIcon } from '../../tiptap-icons/heading-two-icon'
+
+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
+}
+
+/**
+ * Custom hook that provides heading functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * function MySimpleHeadingButton() {
+ *   const { isVisible, isActive, handleToggle, Icon } = useHeading({ level: 1 })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <button
+ *       onClick={handleToggle}
+ *       aria-pressed={isActive}
+ *     >
+ *       <Icon />
+ *       Heading 1
+ *     </button>
+ *   )
+ * }
+ *
+ * // Advanced usage with configuration
+ * function MyAdvancedHeadingButton() {
+ *   const { isVisible, isActive, handleToggle, label, Icon } = useHeading({
+ *     level: 2,
+ *     editor: myEditor,
+ *     hideWhenUnavailable: true,
+ *     onToggled: (isActive) => console.log('Heading toggled:', isActive)
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       onClick={handleToggle}
+ *       aria-label={label}
+ *       aria-pressed={isActive}
+ *     >
+ *       <Icon />
+ *       Toggle Heading 2
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+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/templates/tiptap/tiptap-ui/heading-dropdown-menu/heading-dropdown-menu.tsx

@@ -0,0 +1,131 @@
+'use client'
+
+import { forwardRef, useCallback, useState } from 'react'
+// --- Hooks ---
+import { useTiptapEditor } from '../../hooks/use-tiptap-editor'
+// --- Icons ---
+import { ChevronDownIcon } from '../../tiptap-icons/chevron-down-icon'
+// --- UI Primitives ---
+import type { ButtonProps } from '../../tiptap-ui-primitive/button'
+import { Button, ButtonGroup } from '../../tiptap-ui-primitive/button'
+import { Card, CardBody } from '../../tiptap-ui-primitive/card'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger
+} from '../../tiptap-ui-primitive/dropdown-menu'
+// --- Tiptap UI ---
+import { HeadingButton } from '../heading-button'
+import type { UseHeadingDropdownMenuConfig } from '.'
+import { useHeadingDropdownMenu } from '.'
+
+export interface HeadingDropdownMenuProps
+  extends Omit<ButtonProps, 'type'>,
+    UseHeadingDropdownMenuConfig {
+  /**
+   * Whether to render the dropdown menu in a portal
+   * @default false
+   */
+  portal?: boolean
+  /**
+   * Callback for when the dropdown opens or closes
+   */
+  onOpenChange?: (isOpen: boolean) => void
+}
+
+/**
+ * Dropdown menu component for selecting heading levels in a Tiptap editor.
+ *
+ * For custom dropdown implementations, use the `useHeadingDropdownMenu` hook instead.
+ */
+export const HeadingDropdownMenu = forwardRef<HTMLButtonElement, HeadingDropdownMenuProps>(
+  (
+    {
+      editor: providedEditor,
+      levels = [2, 3, 4, 5, 6],
+      hideWhenUnavailable = false,
+      portal = false,
+      onOpenChange,
+      children,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const { editor } = useTiptapEditor(providedEditor)
+    const [isOpen, setIsOpen] = useState<boolean>(false)
+    const { isVisible, isActive, canToggle, Icon } = useHeadingDropdownMenu({
+      editor,
+      levels,
+      hideWhenUnavailable
+    })
+
+    const handleOpenChange = useCallback(
+      (open: boolean) => {
+        if (!editor || !canToggle) return
+        setIsOpen(open)
+        onOpenChange?.(open)
+      },
+      [canToggle, editor, onOpenChange]
+    )
+
+    if (!isVisible) {
+      return null
+    }
+
+    return (
+      <DropdownMenu open={isOpen} onOpenChange={handleOpenChange}>
+        <DropdownMenuTrigger asChild>
+          <Button
+            type="button"
+            variant="ghost"
+            data-active-state={isActive ? 'on' : 'off'}
+            role="button"
+            tabIndex={-1}
+            disabled={!canToggle}
+            data-disabled={!canToggle}
+            aria-label="Format text as heading"
+            aria-pressed={isActive}
+            tooltip="Heading"
+            {...buttonProps}
+            ref={ref}
+            onPointerDown={(e) => e.preventDefault()}
+            onClick={() => handleOpenChange(!isOpen)}
+          >
+            {children ? (
+              children
+            ) : (
+              <>
+                <Icon className="tiptap-button-icon" />
+                <ChevronDownIcon className="tiptap-button-dropdown-small" />
+              </>
+            )}
+          </Button>
+        </DropdownMenuTrigger>
+
+        <DropdownMenuContent align="start" portal={portal}>
+          <Card>
+            <CardBody>
+              <ButtonGroup>
+                {levels.map((level) => (
+                  <DropdownMenuItem key={`heading-${level}`} asChild>
+                    <HeadingButton
+                      editor={editor}
+                      level={level}
+                      text={`Heading ${level}`}
+                      showTooltip={false}
+                    />
+                  </DropdownMenuItem>
+                ))}
+              </ButtonGroup>
+            </CardBody>
+          </Card>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    )
+  }
+)
+
+HeadingDropdownMenu.displayName = 'HeadingDropdownMenu'
+
+export default HeadingDropdownMenu

package/templates/tiptap/tiptap-ui/heading-dropdown-menu/index.tsx

@@ -0,0 +1,2 @@
+export * from './heading-dropdown-menu'
+export * from './use-heading-dropdown-menu'

package/templates/tiptap/tiptap-ui/heading-dropdown-menu/use-heading-dropdown-menu.ts

@@ -0,0 +1,130 @@
+'use client'
+
+import type { Editor } from '@tiptap/react'
+import { useEffect, useState } from 'react'
+
+// --- Hooks ---
+import { useTiptapEditor } from '../../hooks/use-tiptap-editor'
+
+// --- Icons ---
+import { HeadingIcon } from '../../tiptap-icons/heading-icon'
+
+// --- Tiptap UI ---
+import {
+  canToggle,
+  headingIcons,
+  isHeadingActive,
+  type Level,
+  shouldShowButton
+} from '../heading-button'
+
+/**
+ * Configuration for the heading dropdown menu functionality
+ */
+export interface UseHeadingDropdownMenuConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * Available heading levels to show in the dropdown
+   * @default [1, 2, 3, 4, 5, 6]
+   */
+  levels?: Level[]
+  /**
+   * Whether the dropdown should hide when headings are not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+}
+
+/**
+ * Gets the currently active heading level from the available levels
+ */
+export function getActiveHeadingLevel(
+  editor: Editor | null,
+  levels: Level[] = [1, 2, 3, 4, 5, 6]
+): Level | undefined {
+  if (!editor || !editor.isEditable) return undefined
+  return levels.find((level) => isHeadingActive(editor, level))
+}
+
+/**
+ * Custom hook that provides heading dropdown menu functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * function MyHeadingDropdown() {
+ *   const {
+ *     isVisible,
+ *     activeLevel,
+ *     isAnyHeadingActive,
+ *     canToggle,
+ *     levels,
+ *   } = useHeadingDropdownMenu()
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <DropdownMenu>
+ *       // dropdown content
+ *     </DropdownMenu>
+ *   )
+ * }
+ *
+ * // Advanced usage with configuration
+ * function MyAdvancedHeadingDropdown() {
+ *   const {
+ *     isVisible,
+ *     activeLevel,
+ *   } = useHeadingDropdownMenu({
+ *     editor: myEditor,
+ *     levels: [1, 2, 3],
+ *     hideWhenUnavailable: true,
+ *   })
+ *
+ *   // component implementation
+ * }
+ * ```
+ */
+export function useHeadingDropdownMenu(config?: UseHeadingDropdownMenuConfig) {
+  const {
+    editor: providedEditor,
+    levels = [1, 2, 3, 4, 5, 6],
+    hideWhenUnavailable = false
+  } = config || {}
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const [isVisible, setIsVisible] = useState(true)
+
+  const activeLevel = getActiveHeadingLevel(editor, levels)
+  const isActive = isHeadingActive(editor)
+  const canToggleState = canToggle(editor)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(shouldShowButton({ editor, hideWhenUnavailable, level: levels }))
+    }
+
+    handleSelectionUpdate()
+
+    editor.on('selectionUpdate', handleSelectionUpdate)
+
+    return () => {
+      editor.off('selectionUpdate', handleSelectionUpdate)
+    }
+  }, [editor, hideWhenUnavailable, levels])
+
+  return {
+    isVisible,
+    activeLevel,
+    isActive,
+    canToggle: canToggleState,
+    levels,
+    label: 'Heading',
+    Icon: activeLevel ? headingIcons[activeLevel] : HeadingIcon
+  }
+}