create-starlight-cms 0.9.0

package/template/src/admin/components/tiptap-ui/heading-dropdown-menu/heading-dropdown-menu.tsx

@@ -0,0 +1,128 @@
+import { forwardRef, useCallback, useState } from "react"
+
+// --- Icons ---
+import { ChevronDownIcon } from "@/components/tiptap-icons/chevron-down-icon"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Tiptap UI ---
+import { HeadingButton } from "@/components/tiptap-ui/heading-button"
+import type { UseHeadingDropdownMenuConfig } from "@/components/tiptap-ui/heading-dropdown-menu"
+import { useHeadingDropdownMenu } from "@/components/tiptap-ui/heading-dropdown-menu"
+
+// --- UI Primitives ---
+import type { ButtonProps } from "@/components/tiptap-ui-primitive/button"
+import { Button } from "@/components/tiptap-ui-primitive/button"
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuGroup,
+} from "@/components/tiptap-ui-primitive/dropdown-menu"
+
+export interface HeadingDropdownMenuProps
+  extends Omit<ButtonProps, "type">, UseHeadingDropdownMenuConfig {
+  /**
+   * Callback for when the dropdown opens or closes
+   */
+  onOpenChange?: (isOpen: boolean) => void
+  /**
+   * Whether the dropdown should use a modal
+   */
+  modal?: boolean
+}
+
+/**
+ * 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 = [1, 2, 3, 4, 5, 6],
+      hideWhenUnavailable = false,
+      onOpenChange,
+      children,
+      modal = true,
+      ...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 modal={modal} 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}
+          >
+            {children ? (
+              children
+            ) : (
+              <>
+                <Icon className="tiptap-button-icon" />
+                <ChevronDownIcon className="tiptap-button-dropdown-small" />
+              </>
+            )}
+          </Button>
+        </DropdownMenuTrigger>
+
+        <DropdownMenuContent align="start">
+          <DropdownMenuGroup>
+            {levels.map((level) => (
+              <DropdownMenuItem key={`heading-${level}`} asChild>
+                <HeadingButton
+                  editor={editor}
+                  level={level}
+                  text={`Heading ${level}`}
+                  showTooltip={false}
+                />
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuGroup>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    )
+  }
+)
+
+HeadingDropdownMenu.displayName = "HeadingDropdownMenu"
+
+export default HeadingDropdownMenu

package/template/src/admin/components/tiptap-ui/heading-dropdown-menu/index.tsx

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

package/template/src/admin/components/tiptap-ui/heading-dropdown-menu/use-heading-dropdown-menu.ts

@@ -0,0 +1,132 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import type { Editor } from "@tiptap/react"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Icons ---
+import { HeadingIcon } from "@/components/tiptap-icons/heading-icon"
+
+// --- Tiptap UI ---
+import {
+  headingIcons,
+  type Level,
+  isHeadingActive,
+  canToggle,
+  shouldShowButton,
+} from "@/components/tiptap-ui/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,
+  }
+}

package/template/src/admin/components/tiptap-ui/image-upload-button/image-upload-button.tsx

@@ -0,0 +1,130 @@
+import { forwardRef, useCallback } from "react"
+
+// --- Lib ---
+import { parseShortcutKeys } from "@/lib/tiptap-utils"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Tiptap UI ---
+import type { UseImageUploadConfig } from "@/components/tiptap-ui/image-upload-button"
+import {
+  IMAGE_UPLOAD_SHORTCUT_KEY,
+  useImageUpload,
+} from "@/components/tiptap-ui/image-upload-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"
+
+type IconProps = React.SVGProps<SVGSVGElement>
+type IconComponent = ({ className, ...props }: IconProps) => React.ReactElement
+
+export interface ImageUploadButtonProps
+  extends Omit<ButtonProps, "type">, UseImageUploadConfig {
+  /**
+   * 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 ImageShortcutBadge({
+  shortcutKeys = IMAGE_UPLOAD_SHORTCUT_KEY,
+}: {
+  shortcutKeys?: string
+}) {
+  return <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>
+}
+
+/**
+ * Button component for uploading/inserting images in a Tiptap editor.
+ *
+ * For custom button implementations, use the `useImage` hook instead.
+ */
+export const ImageUploadButton = forwardRef<
+  HTMLButtonElement,
+  ImageUploadButtonProps
+>(
+  (
+    {
+      editor: providedEditor,
+      text,
+      hideWhenUnavailable = false,
+      onInserted,
+      showShortcut = false,
+      onClick,
+      icon: CustomIcon,
+      children,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const { editor } = useTiptapEditor(providedEditor)
+    const {
+      isVisible,
+      canInsert,
+      handleImage,
+      label,
+      isActive,
+      shortcutKeys,
+      Icon,
+    } = useImageUpload({
+      editor,
+      hideWhenUnavailable,
+      onInserted,
+    })
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event)
+        if (event.defaultPrevented) return
+        handleImage()
+      },
+      [handleImage, onClick]
+    )
+
+    if (!isVisible) {
+      return null
+    }
+
+    const RenderIcon = CustomIcon ?? Icon
+
+    return (
+      <Button
+        type="button"
+        variant="ghost"
+        data-active-state={isActive ? "on" : "off"}
+        role="button"
+        tabIndex={-1}
+        disabled={!canInsert}
+        data-disabled={!canInsert}
+        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 && <ImageShortcutBadge shortcutKeys={shortcutKeys} />}
+          </>
+        )}
+      </Button>
+    )
+  }
+)
+
+ImageUploadButton.displayName = "ImageUploadButton"

package/template/src/admin/components/tiptap-ui/image-upload-button/index.tsx

@@ -0,0 +1,2 @@
+export * from "./image-upload-button"
+export * from "./use-image-upload"

package/template/src/admin/components/tiptap-ui/image-upload-button/use-image-upload.ts

@@ -0,0 +1,197 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { useHotkeys } from "react-hotkeys-hook"
+import { type Editor } from "@tiptap/react"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+import { useIsBreakpoint } from "@/hooks/use-is-breakpoint"
+
+// --- Lib ---
+import { isExtensionAvailable } from "@/lib/tiptap-utils"
+
+// --- Icons ---
+import { ImagePlusIcon } from "@/components/tiptap-icons/image-plus-icon"
+
+export const IMAGE_UPLOAD_SHORTCUT_KEY = "mod+shift+i"
+
+/**
+ * Configuration for the image upload functionality
+ */
+export interface UseImageUploadConfig {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * Whether the button should hide when insertion is not available.
+   * @default false
+   */
+  hideWhenUnavailable?: boolean
+  /**
+   * Callback function called after a successful image insertion.
+   */
+  onInserted?: () => void
+}
+
+/**
+ * Checks if image can be inserted in the current editor state
+ */
+export function canInsertImage(editor: Editor | null): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!isExtensionAvailable(editor, "imageUpload")) return false
+
+  return editor.can().insertContent({ type: "imageUpload" })
+}
+
+/**
+ * Checks if image is currently active
+ */
+export function isImageActive(editor: Editor | null): boolean {
+  if (!editor || !editor.isEditable) return false
+  return editor.isActive("imageUpload")
+}
+
+/**
+ * Inserts an image in the editor
+ */
+export function insertImage(editor: Editor | null): boolean {
+  if (!editor || !editor.isEditable) return false
+  if (!canInsertImage(editor)) return false
+
+  try {
+    return editor
+      .chain()
+      .focus()
+      .insertContent({
+        type: "imageUpload",
+      })
+      .run()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Determines if the image button should be shown
+ */
+export function shouldShowButton(props: {
+  editor: Editor | null
+  hideWhenUnavailable: boolean
+}): boolean {
+  const { editor, hideWhenUnavailable } = props
+
+  if (!editor || !editor.isEditable) return false
+
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  if (!isExtensionAvailable(editor, "imageUpload")) return false
+
+  if (!editor.isActive("code")) {
+    return canInsertImage(editor)
+  }
+
+  return true
+}
+
+/**
+ * Custom hook that provides image functionality for Tiptap editor
+ *
+ * @example
+ * ```tsx
+ * // Simple usage - no params needed
+ * function MySimpleImageButton() {
+ *   const { isVisible, handleImage } = useImage()
+ *
+ *   if (!isVisible) return null
+ *
+ *   return <button onClick={handleImage}>Add Image</button>
+ * }
+ *
+ * // Advanced usage with configuration
+ * function MyAdvancedImageButton() {
+ *   const { isVisible, handleImage, label, isActive } = useImage({
+ *     editor: myEditor,
+ *     hideWhenUnavailable: true,
+ *     onInserted: () => console.log('Image inserted!')
+ *   })
+ *
+ *   if (!isVisible) return null
+ *
+ *   return (
+ *     <MyButton
+ *       onClick={handleImage}
+ *       aria-pressed={isActive}
+ *       aria-label={label}
+ *     >
+ *       Add Image
+ *     </MyButton>
+ *   )
+ * }
+ * ```
+ */
+export function useImageUpload(config?: UseImageUploadConfig) {
+  const {
+    editor: providedEditor,
+    hideWhenUnavailable = false,
+    onInserted,
+  } = config || {}
+
+  const { editor } = useTiptapEditor(providedEditor)
+  const isMobile = useIsBreakpoint()
+  const [isVisible, setIsVisible] = useState<boolean>(true)
+  const canInsert = canInsertImage(editor)
+  const isActive = isImageActive(editor)
+
+  useEffect(() => {
+    if (!editor) return
+
+    const handleSelectionUpdate = () => {
+      setIsVisible(shouldShowButton({ editor, hideWhenUnavailable }))
+    }
+
+    handleSelectionUpdate()
+
+    editor.on("selectionUpdate", handleSelectionUpdate)
+
+    return () => {
+      editor.off("selectionUpdate", handleSelectionUpdate)
+    }
+  }, [editor, hideWhenUnavailable])
+
+  const handleImage = useCallback(() => {
+    if (!editor) return false
+
+    const success = insertImage(editor)
+    if (success) {
+      onInserted?.()
+    }
+    return success
+  }, [editor, onInserted])
+
+  useHotkeys(
+    IMAGE_UPLOAD_SHORTCUT_KEY,
+    (event) => {
+      event.preventDefault()
+      handleImage()
+    },
+    {
+      enabled: isVisible && canInsert,
+      enableOnContentEditable: !isMobile,
+      enableOnFormTags: true,
+    }
+  )
+
+  return {
+    isVisible,
+    isActive,
+    handleImage,
+    canInsert,
+    label: "Add image",
+    shortcutKeys: IMAGE_UPLOAD_SHORTCUT_KEY,
+    Icon: ImagePlusIcon,
+  }
+}

package/template/src/admin/components/tiptap-ui/link-popover/index.tsx

@@ -0,0 +1,2 @@
+export * from "./link-popover"
+export * from "./use-link-popover"

package/template/src/admin/components/tiptap-ui/link-popover/link-popover.scss

@@ -0,0 +1,16 @@
+.tiptap-link-input {
+  font-size: 0.875rem;
+  border: none;
+
+  /* Clamp the input */
+  min-width: 12rem;
+  padding-right: 0;
+
+  text-overflow: ellipsis;
+  white-space: nowrap;
+
+  &:focus {
+    text-overflow: clip;
+    overflow: visible;
+  }
+}