create-starlight-cms 0.9.0

package/template/src/admin/components/tiptap-ui/text-align-button/use-text-align.ts

@@ -0,0 +1,237 @@
+import { useCallback, useEffect, useState } from "react"
+import type { ChainedCommands } from "@tiptap/react"
+import { type Editor } from "@tiptap/react"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Lib ---
+import {
+  isExtensionAvailable,
+  isNodeTypeSelected,
+} from "@/lib/tiptap-utils"
+
+// --- Icons ---
+import { AlignCenterIcon } from "@/components/tiptap-icons/align-center-icon"
+import { AlignJustifyIcon } from "@/components/tiptap-icons/align-justify-icon"
+import { AlignLeftIcon } from "@/components/tiptap-icons/align-left-icon"
+import { AlignRightIcon } from "@/components/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.isDestroyed || !editor.isEditable) return false
+  if (
+    !isExtensionAvailable(editor, "textAlign") ||
+    isNodeTypeSelected(editor, ["image", "horizontalRule"])
+  )
+    return false
+
+  try {
+    return editor.can().setTextAlign(align)
+  } catch {
+    return false
+  }
+}
+
+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.isDestroyed || !editor.isEditable) return false
+  if (!canSetTextAlign(editor, align)) return false
+
+  try {
+    const chain = editor.chain().focus()
+    if (hasSetTextAlign(chain)) {
+      return chain.setTextAlign(align).run()
+    }
+  } catch {
+    return false
+  }
+
+  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) return false
+
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  if (!editor.isEditable) return false
+
+  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/template/src/admin/components/tiptap-ui/undo-redo-button/index.tsx

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

package/template/src/admin/components/tiptap-ui/undo-redo-button/undo-redo-button.tsx

@@ -0,0 +1,125 @@
+"use client"
+
+import { forwardRef, useCallback } from "react"
+
+// --- Lib ---
+import { parseShortcutKeys } from "@/lib/tiptap-utils"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Tiptap UI ---
+import type {
+  UndoRedoAction,
+  UseUndoRedoConfig,
+} from "@/components/tiptap-ui/undo-redo-button"
+import {
+  UNDO_REDO_SHORTCUT_KEYS,
+  useUndoRedo,
+} from "@/components/tiptap-ui/undo-redo-button"
+
+// --- UI Primitives ---
+import type { ButtonProps } from "@/components/tiptap-ui-primitive/button"
+import { Button } from "@/components/tiptap-ui-primitive/button"
+import { Badge } from "@/components/tiptap-ui-primitive/badge"
+
+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/template/src/admin/components/tiptap-ui/undo-redo-button/use-undo-redo.ts

@@ -0,0 +1,200 @@
+import { useCallback, useEffect, useState } from "react"
+import { type Editor } from "@tiptap/react"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Lib ---
+import { isNodeTypeSelected } from "@/lib/tiptap-utils"
+
+// --- Icons ---
+import { Redo2Icon } from "@/components/tiptap-icons/redo2-icon"
+import { Undo2Icon } from "@/components/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.isDestroyed || !editor.isEditable) return false
+
+  try {
+    if (isNodeTypeSelected(editor, ["image"])) return false
+
+    const commands = editor.can()
+    const command = action === "undo" ? commands.undo : commands.redo
+
+    return typeof command === "function" ? command() : false
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Executes a history action on the editor
+ */
+export function executeUndoRedoAction(
+  editor: Editor | null,
+  action: UndoRedoAction
+): boolean {
+  if (!editor || editor.isDestroyed || !editor.isEditable) return false
+  if (!canExecuteUndoRedoAction(editor, action)) return false
+
+  try {
+    const chain = editor.chain().focus()
+    return action === "undo" ? chain.undo().run() : chain.redo().run()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 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) return false
+
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  if (!editor.isEditable) return false
+
+  if (!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],
+  }
+}