create-starlight-cms 0.9.0

package/template/src/admin/components/tiptap-ui/color-highlight-popover/color-highlight-popover.tsx

@@ -0,0 +1,231 @@
+import { forwardRef, useMemo, useRef, useState } from "react"
+import { type Editor } from "@tiptap/react"
+
+// --- Hooks ---
+import { useMenuNavigation } from "@/hooks/use-menu-navigation"
+import { useIsBreakpoint } from "@/hooks/use-is-breakpoint"
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Icons ---
+import { BanIcon } from "@/components/tiptap-icons/ban-icon"
+import { HighlighterIcon } from "@/components/tiptap-icons/highlighter-icon"
+
+// --- UI Primitives ---
+import type { ButtonProps } from "@/components/tiptap-ui-primitive/button"
+import { Button } from "@/components/tiptap-ui-primitive/button"
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+} from "@/components/tiptap-ui-primitive/popover"
+import { Separator } from "@/components/tiptap-ui-primitive/separator"
+import {
+  Card,
+  CardBody,
+  CardItemGroup,
+} from "@/components/tiptap-ui-primitive/card"
+
+// --- Tiptap UI ---
+import type {
+  HighlightColor,
+  UseColorHighlightConfig,
+} from "@/components/tiptap-ui/color-highlight-button"
+import {
+  ColorHighlightButton,
+  pickHighlightColorsByValue,
+  useColorHighlight,
+} from "@/components/tiptap-ui/color-highlight-button"
+import { ButtonGroup } from "@/components/tiptap-ui-primitive/button-group"
+
+export interface ColorHighlightPopoverContentProps {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor?: Editor | null
+  /**
+   * Optional colors to use in the highlight popover.
+   * If not provided, defaults to a predefined set of colors.
+   */
+  colors?: HighlightColor[]
+  /**
+   * When true, uses the actual color value (colorValue) instead of CSS variable (value).
+   * @default false
+   */
+  useColorValue?: boolean
+}
+
+export interface ColorHighlightPopoverProps
+  extends
+    Omit<ButtonProps, "type">,
+    Pick<
+      UseColorHighlightConfig,
+      "editor" | "hideWhenUnavailable" | "onApplied"
+    > {
+  /**
+   * Optional colors to use in the highlight popover.
+   * If not provided, defaults to a predefined set of colors.
+   */
+  colors?: HighlightColor[]
+  /**
+   * When true, uses the actual color value (colorValue) instead of CSS variable (value).
+   * @default false
+   */
+  useColorValue?: boolean
+}
+
+export const ColorHighlightPopoverButton = forwardRef<
+  HTMLButtonElement,
+  ButtonProps
+>(({ className, children, ...props }, ref) => (
+  <Button
+    type="button"
+    className={className}
+    variant="ghost"
+    data-appearance="default"
+    role="button"
+    tabIndex={-1}
+    aria-label="Highlight text"
+    tooltip="Highlight"
+    ref={ref}
+    {...props}
+  >
+    {children ?? <HighlighterIcon className="tiptap-button-icon" />}
+  </Button>
+))
+
+ColorHighlightPopoverButton.displayName = "ColorHighlightPopoverButton"
+
+export function ColorHighlightPopoverContent({
+  editor,
+  colors = pickHighlightColorsByValue([
+    "var(--tt-color-highlight-green)",
+    "var(--tt-color-highlight-blue)",
+    "var(--tt-color-highlight-red)",
+    "var(--tt-color-highlight-purple)",
+    "var(--tt-color-highlight-yellow)",
+  ]),
+  useColorValue = false,
+}: ColorHighlightPopoverContentProps) {
+  const { handleRemoveHighlight } = useColorHighlight({ editor })
+  const isMobile = useIsBreakpoint()
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const menuItems = useMemo(
+    () => [...colors, { label: "Remove highlight", value: "none" }],
+    [colors]
+  )
+
+  const { selectedIndex } = useMenuNavigation({
+    containerRef,
+    items: menuItems,
+    orientation: "both",
+    onSelect: (item) => {
+      if (!containerRef.current) return false
+      const highlightedElement = containerRef.current.querySelector(
+        '[data-highlighted="true"]'
+      ) as HTMLElement
+      if (highlightedElement) highlightedElement.click()
+      if (item.value === "none") handleRemoveHighlight()
+      return true
+    },
+    autoSelectFirstItem: false,
+  })
+
+  return (
+    <Card
+      ref={containerRef}
+      tabIndex={0}
+      style={isMobile ? { boxShadow: "none", border: 0 } : {}}
+    >
+      <CardBody style={isMobile ? { padding: 0 } : {}}>
+        <CardItemGroup orientation="horizontal">
+          <ButtonGroup>
+            {colors.map((color, index) => (
+              <ButtonGroup key={color.value}>
+                <ColorHighlightButton
+                  editor={editor}
+                  highlightColor={
+                    useColorValue ? color.colorValue : color.value
+                  }
+                  tooltip={color.label}
+                  aria-label={`${color.label} highlight color`}
+                  tabIndex={index === selectedIndex ? 0 : -1}
+                  data-highlighted={selectedIndex === index}
+                  useColorValue={useColorValue}
+                />
+              </ButtonGroup>
+            ))}
+          </ButtonGroup>
+          <Separator />
+          <ButtonGroup>
+            <Button
+              onClick={handleRemoveHighlight}
+              aria-label="Remove highlight"
+              tooltip="Remove highlight"
+              tabIndex={selectedIndex === colors.length ? 0 : -1}
+              type="button"
+              role="menuitem"
+              variant="ghost"
+              data-highlighted={selectedIndex === colors.length}
+            >
+              <BanIcon className="tiptap-button-icon" />
+            </Button>
+          </ButtonGroup>
+        </CardItemGroup>
+      </CardBody>
+    </Card>
+  )
+}
+
+export function ColorHighlightPopover({
+  editor: providedEditor,
+  colors = pickHighlightColorsByValue([
+    "var(--tt-color-highlight-green)",
+    "var(--tt-color-highlight-blue)",
+    "var(--tt-color-highlight-red)",
+    "var(--tt-color-highlight-purple)",
+    "var(--tt-color-highlight-yellow)",
+  ]),
+  hideWhenUnavailable = false,
+  useColorValue = false,
+  onApplied,
+  ...props
+}: ColorHighlightPopoverProps) {
+  const { editor } = useTiptapEditor(providedEditor)
+  const [isOpen, setIsOpen] = useState(false)
+  const { isVisible, canColorHighlight, isActive, label, Icon } =
+    useColorHighlight({
+      editor,
+      hideWhenUnavailable,
+      onApplied,
+    })
+
+  if (!isVisible) return null
+
+  return (
+    <Popover open={isOpen} onOpenChange={setIsOpen}>
+      <PopoverTrigger asChild>
+        <ColorHighlightPopoverButton
+          disabled={!canColorHighlight}
+          data-active-state={isActive ? "on" : "off"}
+          data-disabled={!canColorHighlight}
+          aria-pressed={isActive}
+          aria-label={label}
+          tooltip={label}
+          {...props}
+        >
+          <Icon className="tiptap-button-icon" />
+        </ColorHighlightPopoverButton>
+      </PopoverTrigger>
+      <PopoverContent aria-label="Highlight colors">
+        <ColorHighlightPopoverContent
+          editor={editor}
+          colors={colors}
+          useColorValue={useColorValue}
+        />
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export default ColorHighlightPopover

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

@@ -0,0 +1 @@
+export * from "./color-highlight-popover"

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

@@ -0,0 +1,124 @@
+import { forwardRef, useCallback } from "react"
+
+// --- Lib ---
+import { parseShortcutKeys } from "@/lib/tiptap-utils"
+
+// --- Tiptap UI ---
+import type {
+  Level,
+  UseHeadingConfig,
+} from "@/components/tiptap-ui/heading-button"
+import {
+  HEADING_SHORTCUT_KEYS,
+  useHeading,
+} from "@/components/tiptap-ui/heading-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"
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+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/template/src/admin/components/tiptap-ui/heading-button/index.tsx

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

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

@@ -0,0 +1,348 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { type Editor } from "@tiptap/react"
+import { NodeSelection, TextSelection } from "@tiptap/pm/state"
+
+// --- Hooks ---
+import { useTiptapEditor } from "@/hooks/use-tiptap-editor"
+
+// --- Lib ---
+import {
+  findNodePosition,
+  getSelectedBlockNodes,
+  isNodeInSchema,
+  isNodeTypeSelected,
+  isValidPosition,
+  selectionWithinConvertibleTypes,
+} from "@/lib/tiptap-utils"
+
+// --- Icons ---
+import { HeadingOneIcon } from "@/components/tiptap-icons/heading-one-icon"
+import { HeadingTwoIcon } from "@/components/tiptap-icons/heading-two-icon"
+import { HeadingThreeIcon } from "@/components/tiptap-icons/heading-three-icon"
+import { HeadingFourIcon } from "@/components/tiptap-icons/heading-four-icon"
+import { HeadingFiveIcon } from "@/components/tiptap-icons/heading-five-icon"
+import { HeadingSixIcon } from "@/components/tiptap-icons/heading-six-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 node 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) return false
+
+  if (!hideWhenUnavailable) {
+    return true
+  }
+
+  if (!editor.isEditable) return false
+
+  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],
+  }
+}