@betterstart/cli 0.1.2 → 0.1.4

package/templates/tiptap/tiptap-ui/text-align-button/text-align-button.tsx

@@ -0,0 +1,118 @@
+'use client'
+
+import { forwardRef, useCallback } from 'react'
+// --- Hooks ---
+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 { TextAlign, UseTextAlignConfig } from '.'
+import { TEXT_ALIGN_SHORTCUT_KEYS, useTextAlign } from '.'
+
+type IconProps = React.SVGProps<SVGSVGElement>
+type IconComponent = ({ className, ...props }: IconProps) => React.ReactElement
+
+export interface TextAlignButtonProps extends Omit<ButtonProps, 'type'>, UseTextAlignConfig {
+  /**
+   * Optional text to display alongside the icon.
+   */
+  text?: string
+  /**
+   * Optional show shortcut keys in the button.
+   * @default false
+   */
+  showShortcut?: boolean
+  /**
+   * Optional custom icon component to render instead of the default.
+   */
+  icon?: React.MemoExoticComponent<IconComponent> | React.FC<IconProps>
+}
+
+export function TextAlignShortcutBadge({
+  align,
+  shortcutKeys = TEXT_ALIGN_SHORTCUT_KEYS[align]
+}: {
+  align: TextAlign
+  shortcutKeys?: string
+}) {
+  return <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>
+}
+
+/**
+ * Button component for setting text alignment in a Tiptap editor.
+ *
+ * For custom button implementations, use the `useTextAlign` hook instead.
+ */
+export const TextAlignButton = forwardRef<HTMLButtonElement, TextAlignButtonProps>(
+  (
+    {
+      editor: providedEditor,
+      align,
+      text,
+      hideWhenUnavailable = false,
+      onAligned,
+      showShortcut = false,
+      onClick,
+      icon: CustomIcon,
+      children,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const { editor } = useTiptapEditor(providedEditor)
+    const { isVisible, handleTextAlign, label, canAlign, isActive, Icon, shortcutKeys } =
+      useTextAlign({
+        editor,
+        align,
+        hideWhenUnavailable,
+        onAligned
+      })
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event)
+        if (event.defaultPrevented) return
+        handleTextAlign()
+      },
+      [handleTextAlign, onClick]
+    )
+
+    if (!isVisible) {
+      return null
+    }
+
+    const RenderIcon = CustomIcon ?? Icon
+
+    return (
+      <Button
+        type="button"
+        disabled={!canAlign}
+        variant="ghost"
+        data-active-state={isActive ? 'on' : 'off'}
+        data-disabled={!canAlign}
+        role="button"
+        tabIndex={-1}
+        aria-label={label}
+        aria-pressed={isActive}
+        tooltip={label}
+        onClick={handleClick}
+        {...buttonProps}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <RenderIcon className="tiptap-button-icon" />
+            {text && <span className="tiptap-button-text">{text}</span>}
+            {showShortcut && <TextAlignShortcutBadge align={align} shortcutKeys={shortcutKeys} />}
+          </>
+        )}
+      </Button>
+    )
+  }
+)
+
+TextAlignButton.displayName = 'TextAlignButton'

package/templates/tiptap/tiptap-ui/text-align-button/use-text-align.ts

@@ -0,0 +1,212 @@
+'use client'
+
+import type { ChainedCommands, Editor } from '@tiptap/react'
+import { useCallback, useEffect, useState } from 'react'
+
+// --- Hooks ---
+import { useTiptapEditor } from '../../hooks/use-tiptap-editor'
+
+// --- Lib ---
+import { isExtensionAvailable, isNodeTypeSelected } from '../../lib/tiptap-utils'
+
+// --- Icons ---
+import { AlignCenterIcon } from '../../tiptap-icons/align-center-icon'
+import { AlignJustifyIcon } from '../../tiptap-icons/align-justify-icon'
+import { AlignLeftIcon } from '../../tiptap-icons/align-left-icon'
+import { AlignRightIcon } from '../../tiptap-icons/align-right-icon'
+
+export type TextAlign = 'left' | 'center' | 'right' | 'justify'
+
+/**
+ * Configuration for the text align functionality
+ */
+export interface UseTextAlignConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * The text alignment to apply.
+   */
+  align: TextAlign
+  /**
+   * Whether the button should hide when alignment is not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called after a successful alignment change.
+   */
+  onAligned?: () => void
+}
+
+export const TEXT_ALIGN_SHORTCUT_KEYS: Record<TextAlign, string> = {
+  left: 'mod+shift+l',
+  center: 'mod+shift+e',
+  right: 'mod+shift+r',
+  justify: 'mod+shift+j'
+}
+
+export const textAlignIcons = {
+  left: AlignLeftIcon,
+  center: AlignCenterIcon,
+  right: AlignRightIcon,
+  justify: AlignJustifyIcon
+}
+
+export const textAlignLabels: Record<TextAlign, string> = {
+  left: 'Align left',
+  center: 'Align center',
+  right: 'Align right',
+  justify: 'Align justify'
+}
+
+/**
+ * Checks if text alignment can be performed in the current editor state
+ */
+export function canSetTextAlign(editor: Editor | null, align: TextAlign): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (
+    !isExtensionAvailable(editor, 'textAlign') ||
+    isNodeTypeSelected(editor, ['image', 'horizontalRule'])
+  )
+    return false
+
+  return editor.can().setTextAlign(align)
+}
+
+export function hasSetTextAlign(commands: ChainedCommands): commands is ChainedCommands & {
+  setTextAlign: (align: TextAlign) => ChainedCommands
+} {
+  return 'setTextAlign' in commands
+}
+
+/**
+ * Checks if the text alignment is currently active
+ */
+export function isTextAlignActive(editor: Editor | null, align: TextAlign): boolean {
+  if (!editor || !editor.isEditable) return false
+  return editor.isActive({ textAlign: align })
+}
+
+/**
+ * Sets text alignment in the editor
+ */
+export function setTextAlign(editor: Editor | null, align: TextAlign): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!canSetTextAlign(editor, align)) return false
+
+  const chain = editor.chain().focus()
+  if (hasSetTextAlign(chain)) {
+    return chain.setTextAlign(align).run()
+  }
+
+  return false
+}
+
+/**
+ * Determines if the text align button should be shown
+ */
+export function shouldShowButton(props: {
+  editor: Editor | null
+  hideWhenUnavailable: boolean
+  align: TextAlign
+}): boolean {
+  const { editor, hideWhenUnavailable, align } = props
+
+  if (!editor || !editor.isEditable) return false
+
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  if (!isExtensionAvailable(editor, 'textAlign')) return false
+
+  if (!editor.isActive('code')) {
+    return canSetTextAlign(editor, align)
+  }
+
+  return true
+}
+
+/**
+ * Custom hook that provides text align functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage
+ * function MySimpleAlignButton() {
+ *   const { isVisible, handleTextAlign } = useTextAlign({ align: "center" })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return <button onClick={handleTextAlign}>Align Center</button>
+ * }
+ *
+ * // Advanced usage with configuration
+ * function MyAdvancedAlignButton() {
+ *   const { isVisible, handleTextAlign, label, isActive } = useTextAlign({
+ *     editor: myEditor,
+ *     align: "right",
+ *     hideWhenUnavailable: true,
+ *     onAligned: () => console.log('Text aligned!')
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       onClick={handleTextAlign}
+ *       aria-pressed={isActive}
+ *       aria-label={label}
+ *     >
+ *       Align Right
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+export function useTextAlign(config: UseTextAlignConfig) {
+  const { editor: providedEditor, align, hideWhenUnavailable = false, onAligned } = config
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const [isVisible, setIsVisible] = useState<boolean>(true)
+  const canAlign = canSetTextAlign(editor, align)
+  const isActive = isTextAlignActive(editor, align)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(shouldShowButton({ editor, align, hideWhenUnavailable }))
+    }
+
+    handleSelectionUpdate()
+
+    editor.on('selectionUpdate', handleSelectionUpdate)
+
+    return () => {
+      editor.off('selectionUpdate', handleSelectionUpdate)
+    }
+  }, [editor, hideWhenUnavailable, align])
+
+  const handleTextAlign = useCallback(() => {
+    if (!editor) return false
+
+    const success = setTextAlign(editor, align)
+    if (success) {
+      onAligned?.()
+    }
+    return success
+  }, [editor, align, onAligned])
+
+  return {
+    isVisible,
+    isActive,
+    handleTextAlign,
+    canAlign,
+    label: textAlignLabels[align],
+    shortcutKeys: TEXT_ALIGN_SHORTCUT_KEYS[align],
+    Icon: textAlignIcons[align]
+  }
+}

package/templates/tiptap/tiptap-ui/undo-redo-button/index.tsx

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

package/templates/tiptap/tiptap-ui/undo-redo-button/undo-redo-button.tsx

@@ -0,0 +1,105 @@
+'use client'
+
+import { forwardRef, useCallback } from 'react'
+// --- Hooks ---
+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 { UndoRedoAction, UseUndoRedoConfig } from '.'
+import { UNDO_REDO_SHORTCUT_KEYS, useUndoRedo } from '.'
+
+export interface UndoRedoButtonProps extends Omit<ButtonProps, 'type'>, UseUndoRedoConfig {
+  /**
+   * Optional text to display alongside the icon.
+   */
+  text?: string
+  /**
+   * Optional show shortcut keys in the button.
+   * @default false
+   */
+  showShortcut?: boolean
+}
+
+export function HistoryShortcutBadge({
+  action,
+  shortcutKeys = UNDO_REDO_SHORTCUT_KEYS[action]
+}: {
+  action: UndoRedoAction
+  shortcutKeys?: string
+}) {
+  return <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>
+}
+
+/**
+ * Button component for triggering undo/redo actions in a Tiptap editor.
+ *
+ * For custom button implementations, use the `useHistory` hook instead.
+ */
+export const UndoRedoButton = forwardRef<HTMLButtonElement, UndoRedoButtonProps>(
+  (
+    {
+      editor: providedEditor,
+      action,
+      text,
+      hideWhenUnavailable = false,
+      onExecuted,
+      showShortcut = false,
+      onClick,
+      children,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const { editor } = useTiptapEditor(providedEditor)
+    const { isVisible, handleAction, label, canExecute, Icon, shortcutKeys } = useUndoRedo({
+      editor,
+      action,
+      hideWhenUnavailable,
+      onExecuted
+    })
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event)
+        if (event.defaultPrevented) return
+        handleAction()
+      },
+      [handleAction, onClick]
+    )
+
+    if (!isVisible) {
+      return null
+    }
+
+    return (
+      <Button
+        type="button"
+        disabled={!canExecute}
+        variant="ghost"
+        data-disabled={!canExecute}
+        role="button"
+        tabIndex={-1}
+        aria-label={label}
+        tooltip={label}
+        onClick={handleClick}
+        {...buttonProps}
+        ref={ref}
+      >
+        {children ?? (
+          <>
+            <Icon className="tiptap-button-icon" />
+            {text && <span className="tiptap-button-text">{text}</span>}
+            {showShortcut && <HistoryShortcutBadge action={action} shortcutKeys={shortcutKeys} />}
+          </>
+        )}
+      </Button>
+    )
+  }
+)
+
+UndoRedoButton.displayName = 'UndoRedoButton'

package/templates/tiptap/tiptap-ui/undo-redo-button/use-undo-redo.ts

@@ -0,0 +1,173 @@
+'use client'
+
+import type { Editor } from '@tiptap/react'
+import { useCallback, useEffect, useState } from 'react'
+
+// --- Hooks ---
+import { useTiptapEditor } from '../../hooks/use-tiptap-editor'
+
+// --- Lib ---
+import { isNodeTypeSelected } from '../../lib/tiptap-utils'
+
+// --- Icons ---
+import { Redo2Icon } from '../../tiptap-icons/redo2-icon'
+import { Undo2Icon } from '../../tiptap-icons/undo2-icon'
+
+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]
+  }
+}