# ABUI

> A shadcn/ui-compatible registry of reusable React components, blocks, and Tailwind CSS utilities by Antonio Brandao. Install any item with npx shadcn add @abui/<name>.

ABUI is a public, open-source component registry that follows the shadcn/ui registry specification and Vercel's components.build taxonomy. Every item is a copy-and-own file: installing it writes TypeScript/React source into your project rather than adding a package dependency. Items are styled with Tailwind CSS v4 and shadcn/ui design tokens (background, foreground, primary, muted, border, etc.), so they adopt the host project's theme.

## Installation

ABUI is listed in the shadcn registry directory, so the `@abui` namespace resolves without configuration:

```bash
npx shadcn@latest add @abui/<name>
```

To pin the registry manually, add this to `components.json`:

```json
{ "registries": { "@abui": "https://www.abui.io/r/{name}.json" } }
```

Requirements: a React project initialised with shadcn/ui (`npx shadcn@latest init`), Tailwind CSS v4, and the `@/lib/utils` `cn` helper.


## Blocks

### Timeline

A Gantt-chart style timeline with draggable time slots.

- Docs: https://www.abui.io/blocks/timeline
- Registry item: https://www.abui.io/r/timeline.json
- Type: registry:block
- Install: `npx shadcn@latest add @abui/timeline`
- npm dependencies: @radix-ui/react-slot, @dnd-kit/core, tunnel-rat

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/timeline.tsx

```tsx
"use client"

import * as React from "react"
import { useState, useRef, useEffect, createContext, useContext, useMemo } from "react"
import { Slot } from "@radix-ui/react-slot"
import {
  DndContext,
  DragOverlay,
  useSensor,
  useSensors,
  PointerSensor,
  closestCenter,
  useDraggable,
  useDroppable,
} from "@dnd-kit/core"
import tunnel from "tunnel-rat"
import { cn } from "@/lib/utils"

/* ============================================================================
 * TYPES & INTERFACES
 * ========================================================================== */

export interface TimelineSlotData {
  id: string
  rowId: string
  startTime: string // "14:30"
  duration: number // minutes
  [key: string]: any // Additional custom data
}

export interface TimelineRowData {
  id: string
  label: string
  [key: string]: any // Additional custom data
}

export interface TimelineConfig {
  startHour: number
  endHour: number
  snapIntervalMinutes?: number
  columnWidth?: number
}

/* ============================================================================
 * CONTEXT
 * ========================================================================== */

type TimelineContextValue = {
  // Configuration
  config: TimelineConfig
  pixelsPerMinute: number
  timelineWidth: number

  // Refs
  timelineRef: React.RefObject<HTMLDivElement | null>
  columnRef: React.RefObject<HTMLDivElement | null>

  // Tunnel for drag preview
  dragPreviewTunnel: ReturnType<typeof tunnel>

  // Callbacks
  onSlotPositionChange?: (slotId: string, newTime: string, newRowId: string) => Promise<boolean>
  onValidateDrop?: (slotId: string, newTime: string, newRowId: string) => boolean
  onSlotClick?: (slotId: string) => void
}

const TimelineContext = createContext<TimelineContextValue | null>(null)

function useTimeline() {
  const context = useContext(TimelineContext)
  if (!context) {
    throw new Error("Timeline components must be used within TimelineProvider")
  }
  return context
}

/* ============================================================================
 * UTILITIES
 * ========================================================================== */

export const timeToMinutes = (time: string): number => {
  const [hours, minutes] = time.split(":").map(Number)
  return hours * 60 + minutes
}

export const minutesToTime = (minutes: number): string => {
  const hours = Math.floor(minutes / 60)
  const mins = minutes % 60
  return `${hours.toString().padStart(2, "0")}:${mins.toString().padStart(2, "0")}`
}

/* ============================================================================
 * TIMELINE PROVIDER
 * ========================================================================== */

interface TimelineProviderProps {
  children: React.ReactNode
  config: TimelineConfig
  percentageInView?: number
  onSlotPositionChange?: (slotId: string, newTime: string, newRowId: string) => Promise<boolean>
  onValidateDrop?: (slotId: string, newTime: string, newRowId: string) => boolean
  onSlotClick?: (slotId: string) => void
  style?: React.CSSProperties
  className?: string
}

export function TimelineProvider({
  children,
  config,
  percentageInView = 100,
  onSlotPositionChange,
  onValidateDrop,
  onSlotClick,
  style,
  className,
}: TimelineProviderProps) {
  const [viewportWidth, setViewportWidth] = useState(0)

  const timelineRef = useRef<HTMLDivElement>(null)
  const columnRef = useRef<HTMLDivElement>(null)

  // Create tunnel for drag preview (stable across renders)
  const dragPreviewTunnel = useMemo(() => tunnel(), [])

  const columnWidth = config.columnWidth || 112

  // Measure viewport
  useEffect(() => {
    const measure = () => {
      if (timelineRef.current) {
        setViewportWidth(timelineRef.current.clientWidth - columnWidth)
      }
    }

    measure()
    window.addEventListener("resize", measure)
    const timeout = setTimeout(measure, 100)

    return () => {
      window.removeEventListener("resize", measure)
      clearTimeout(timeout)
    }
  }, [columnWidth])

  // Calculate timeline dimensions
  const totalMinutes = (config.endHour - config.startHour) * 60
  const basePixelsPerMinute = viewportWidth > 0 ? viewportWidth / totalMinutes : 10
  const pixelsPerMinute = basePixelsPerMinute * (100 / percentageInView)
  const timelineWidth = totalMinutes * pixelsPerMinute

  const contextValue: TimelineContextValue = {
    config,
    pixelsPerMinute,
    timelineWidth,
    timelineRef,
    columnRef,
    dragPreviewTunnel,
    onSlotPositionChange,
    onValidateDrop,
    onSlotClick,
  }

  return (
    <TimelineContext.Provider value={contextValue}>
      <div
        data-slot="timeline-wrapper"
        style={
          {
            "--timeline-column-width": `${columnWidth}px`,
            "--timeline-width": `${timelineWidth}px`,
            "--timeline-pixels-per-minute": pixelsPerMinute,
            ...style,
          } as React.CSSProperties
        }
        className={cn("relative w-full", className)}
      >
        {children}
      </div>
    </TimelineContext.Provider>
  )
}

/* ============================================================================
 * TIMELINE (Main Container with DnD)
 * ========================================================================== */

interface TimelineProps {
  slots: TimelineSlotData[]
  rows: TimelineRowData[]
  children: React.ReactNode
  className?: string
}

export function Timeline({ slots, rows, children, className }: TimelineProps) {
  const { config, pixelsPerMinute, timelineRef, dragPreviewTunnel, onSlotPositionChange, onValidateDrop } =
    useTimeline()

  const [mousePosition, setMousePosition] = useState<{ x: number; y: number } | null>(null)

  const sensors = useSensors(
    useSensor(PointerSensor, {
      activationConstraint: { distance: 8 },
    }),
  )

  const snapInterval = config.snapIntervalMinutes || 15
  const columnWidth = config.columnWidth || 112

  // Snapping utilities
  const snapToInterval = (minutes: number): number => {
    return Math.round(minutes / snapInterval) * snapInterval
  }

  const getSnappedDelta = (deltaX: number): number => {
    const deltaMinutes = deltaX / pixelsPerMinute
    const snappedDeltaMinutes = Math.round(deltaMinutes / snapInterval) * snapInterval
    return snappedDeltaMinutes * pixelsPerMinute
  }

  const calculateNewTime = (originalTime: string, deltaX: number): string => {
    const originalMinutes = timeToMinutes(originalTime)
    const deltaMinutes = Math.round(deltaX / pixelsPerMinute)
    const newMinutes = originalMinutes + deltaMinutes
    const snappedMinutes = snapToInterval(newMinutes)
    const clampedMinutes = Math.max(config.startHour * 60, Math.min((config.endHour - 1) * 60, snappedMinutes))
    return minutesToTime(clampedMinutes)
  }

  // Mouse handlers
  const handleMouseMove = (e: React.MouseEvent) => {
    if (timelineRef.current) {
      const rect = timelineRef.current.getBoundingClientRect()
      setMousePosition({
        x: e.clientX - rect.left + timelineRef.current.scrollLeft,
        y: e.clientY - rect.top,
      })
    }
  }

  const handleMouseLeave = () => {
    setMousePosition(null)
  }

  // Calculate mouse time
  const mouseTime = mousePosition
    ? minutesToTime(Math.floor((mousePosition.x - columnWidth) / pixelsPerMinute) + config.startHour * 60)
    : null

  // Drag handlers
  const [localActiveSlot, setLocalActiveSlot] = useState<string | null>(null)
  const [localOverRow, setLocalOverRow] = useState<string | null>(null)
  const [localDraggedTime, setLocalDraggedTime] = useState<string | null>(null)
  const [isValid, setIsValid] = useState(true)

  const handleDragStart = (event: any) => {
    setLocalActiveSlot(event.active.id)
  }

  const handleDragOver = (event: any) => {
    if (event.over) {
      setLocalOverRow(event.over.id)
    } else {
      setLocalOverRow(null)
      setLocalDraggedTime(null)
    }
  }

  const handleDragMove = (event: any) => {
    const { over, active, delta } = event

    if (over) {
      const slot = slots.find((s: TimelineSlotData) => s.id === active.id)
      if (slot) {
        const newTime = calculateNewTime(slot.startTime, delta.x)
        setLocalDraggedTime(newTime)

        // Validate with host
        const valid = onValidateDrop ? onValidateDrop(active.id, newTime, over.id) : true
        setIsValid(valid)
      }
    }
  }

  const handleDragCancel = () => {
    // Clean up all drag state when drag is cancelled (e.g., ESC key)
    setLocalActiveSlot(null)
    setLocalOverRow(null)
    setLocalDraggedTime(null)
    setIsValid(true)
  }

  const handleDragEnd = async (event: any) => {
    const { active, over, delta } = event

    setLocalActiveSlot(null)
    setLocalOverRow(null)
    setLocalDraggedTime(null)
    setIsValid(true)

    if (over) {
      const slot = slots.find((s: TimelineSlotData) => s.id === active.id)
      if (!slot) return

      const newTime = calculateNewTime(slot.startTime, delta.x)
      const newRowId = over.id

      // Validate
      if (onValidateDrop && !onValidateDrop(active.id, newTime, newRowId)) {
        return
      }

      // Check if anything changed
      if (slot.rowId === newRowId && slot.startTime === newTime) {
        return
      }

      // Call position change handler
      if (onSlotPositionChange) {
        await onSlotPositionChange(active.id, newTime, newRowId)
      }
    }
  }

  return (
    <DndContext
      sensors={sensors}
      collisionDetection={closestCenter}
      onDragStart={handleDragStart}
      onDragOver={handleDragOver}
      onDragMove={handleDragMove}
      onDragEnd={handleDragEnd}
      onDragCancel={handleDragCancel}
    >
      <div className="relative w-full">
        {/* Mouse time indicator */}
        {mousePosition && mouseTime && !localActiveSlot && (
          <TimelineMouseIndicator mouseX={mousePosition.x} time={mouseTime} />
        )}

        <div
          ref={timelineRef}
          data-slot="timeline-grid"
          className={cn("relative overflow-auto border bg-background", className)}
          onMouseMove={handleMouseMove}
          onMouseLeave={handleMouseLeave}
        >
          {React.Children.map(children, child => {
            if (React.isValidElement(child)) {
              return React.cloneElement(child as React.ReactElement<any>, {
                slots,
                rows,
                activeSlotId: localActiveSlot,
                overRowId: localOverRow,
                draggedNewTime: localDraggedTime,
                isValidDrop: isValid,
                getSnappedDelta,
                _showDropRegion: !!(localActiveSlot && localDraggedTime),
                _dropRegionTime: localDraggedTime,
              })
            }
            return child
          })}
        </div>

        {/* Drag overlay - receives content from tunnel */}
        <DragOverlay dropAnimation={null}>
          {localActiveSlot &&
            (() => {
              const activeSlot = slots.find((s: TimelineSlotData) => s.id === localActiveSlot)
              if (!activeSlot) return null

              console.log("📺 DragOverlay rendering for slot:", activeSlot.id)

              return (
                <div
                  data-slot="timeline-drag-overlay"
                  style={{
                    width: `${Math.max(activeSlot.duration * pixelsPerMinute, 60)}px`,
                    height: "54px",
                    position: "relative",
                  }}
                >
                  {/* Receive tunneled content from the active slot */}
                  <dragPreviewTunnel.Out />
                </div>
              )
            })()}
        </DragOverlay>
      </div>
    </DndContext>
  )
}

/* ============================================================================
 * TIMELINE HEADER
 * ========================================================================== */

interface TimelineHeaderProps {
  className?: string
  columnLabel?: React.ReactNode
}

export function TimelineHeader({ className, columnLabel = "Row" }: TimelineHeaderProps) {
  const { config, pixelsPerMinute, columnRef } = useTimeline()

  // Generate hour markers
  const hourMarkers = []
  for (let hour = config.startHour; hour < config.endHour; hour++) {
    hourMarkers.push({
      hour,
      label: `${hour}:00`,
      position: (hour - config.startHour) * 60 * pixelsPerMinute,
    })
  }

  return (
    <div data-slot="timeline-header" className={cn("sticky top-0 z-10 bg-background border-b", className)}>
      <div className="flex h-12">
        <div
          ref={columnRef}
          data-slot="timeline-header-column"
          className="sticky left-0 w-[var(--timeline-column-width)] bg-background border-r flex items-center px-4 font-semibold text-sm z-1"
        >
          {columnLabel}
        </div>
        <div data-slot="timeline-header-markers" className="relative flex-1">
          {hourMarkers.map(marker => (
            <div
              key={marker.hour}
              data-slot="timeline-hour-marker"
              className="absolute top-0 bottom-0 flex items-center pl-2 text-xs text-muted-foreground"
              style={{ left: `${marker.position}px` }}
            >
              {marker.label}
            </div>
          ))}
        </div>
      </div>
    </div>
  )
}

/* ============================================================================
 * TIMELINE ROW
 * ========================================================================== */

interface TimelineRowProps {
  row: TimelineRowData
  slots: TimelineSlotData[]
  children: (slot: TimelineSlotData) => React.ReactNode
  renderRowHeader?: (row: TimelineRowData) => React.ReactNode
  renderDropGhost?: (slot: TimelineSlotData, newTime: string, isValid: boolean) => React.ReactNode
  className?: string
  asChild?: boolean
}

export function TimelineRow({
  row,
  slots,
  children,
  renderRowHeader,
  className,
  asChild,
  ...props
}: TimelineRowProps & any) {
  const { config, pixelsPerMinute, timelineWidth } = useTimeline()
  const Comp = asChild ? Slot : "div"

  const { setNodeRef, isOver } = useDroppable({
    id: row.id,
  })

  const rowSlots = slots.filter((s: TimelineSlotData) => s.rowId === row.id)

  // Check if this row has invalid drop (from props passed by Timeline)
  const isValidDrop = props.isValidDrop !== false
  const isHovered = isOver || props.overRowId === row.id // Try BOTH

  // Generate grid markers
  const hourMarkers = []
  for (let hour = config.startHour; hour <= config.endHour; hour++) {
    hourMarkers.push({
      hour,
      position: (hour - config.startHour) * 60 * pixelsPerMinute,
    })
  }

  const quarterHourMarkers = []
  const totalMinutes = (config.endHour - config.startHour) * 60
  for (let minutes = 15; minutes < totalMinutes; minutes += 15) {
    if (minutes % 60 !== 0) {
      quarterHourMarkers.push({
        position: minutes * pixelsPerMinute,
      })
    }
  }

  return (
    <Comp
      ref={setNodeRef}
      data-slot="timeline-row"
      data-state={isHovered ? (isValidDrop ? "hover-valid" : "hover-invalid") : "idle"}
      className={cn(
        "flex border-b h-12",
        isHovered && isValidDrop && "ring-2 ring-inset ring-blue-500",
        isHovered && !isValidDrop && "ring-2 ring-inset ring-red-500",
        className,
      )}
    >
      {/* Row label column */}
      <div
        data-slot="timeline-row-label"
        className="sticky left-0 w-[var(--timeline-column-width)] bg-inherit border-r flex items-center px-0 z-[5]"
      >
        {renderRowHeader ? renderRowHeader(row) : row.label}
      </div>

      {/* Timeline grid */}
      <div data-slot="timeline-row-grid" className="relative flex-1" style={{ width: `${timelineWidth}px` }}>
        {/* Grid lines */}
        {quarterHourMarkers.map((marker, idx) => (
          <div
            key={`quarter-${idx}`}
            data-slot="timeline-grid-line-quarter"
            className="absolute top-0 bottom-0 w-px bg-border/30"
            style={{ left: `${marker.position}px` }}
          />
        ))}
        {hourMarkers.map(marker => (
          <div
            key={marker.hour}
            data-slot="timeline-grid-line-hour"
            className="absolute top-0 bottom-0 w-px bg-border"
            style={{ left: `${marker.position}px` }}
          />
        ))}

        {/* Slots */}
        {rowSlots.map((slot: TimelineSlotData) => {
          const slotElement = children(slot)
          // Clone the element to inject activeSlotId prop
          return (
            <React.Fragment key={slot.id}>
              {React.isValidElement(slotElement)
                ? React.cloneElement(slotElement, { activeSlotId: props.activeSlotId } as any)
                : slotElement}
            </React.Fragment>
          )
        })}

        {/* Drop ghost - shows where slot will land if dropped in this row */}
        {isHovered && props.draggedNewTime && props.activeSlotId && (
          <TimelineDropGhost
            activeSlotId={props.activeSlotId}
            allSlots={slots}
            newTime={props.draggedNewTime}
            isValid={isValidDrop}
            pixelsPerMinute={pixelsPerMinute}
            config={config}
          />
        )}
      </div>
    </Comp>
  )
}

/* ============================================================================
 * TIMELINE SLOT (Draggable)
 * ========================================================================== */

interface TimelineSlotProps {
  slot: TimelineSlotData
  children: React.ReactNode
  className?: string
  asChild?: boolean
}

export function TimelineSlot({ slot, children, className, asChild, ...props }: TimelineSlotProps & any) {
  const timeline = useTimeline()
  const { config, pixelsPerMinute, onSlotClick, dragPreviewTunnel } = timeline
  const Comp = asChild ? Slot : "div"

  const { attributes, listeners, setNodeRef, isDragging, transform } = useDraggable({
    id: slot.id,
  })

  const startMinutes = timeToMinutes(slot.startTime)
  const left = (startMinutes - config.startHour * 60) * pixelsPerMinute
  const width = slot.duration * pixelsPerMinute

  // Get activeSlotId from Timeline component via props (passed through TimelineRow)
  const activeSlotIdFromTimeline = props.activeSlotId
  const isActiveSlot = activeSlotIdFromTimeline === slot.id

  // When dragging, show slot at its snapped target position (not at cursor)
  // The DragOverlay will show what you're dragging at cursor position
  const style =
    transform && props.getSnappedDelta
      ? {
          left: `${left}px`,
          width: `${Math.max(width, 60)}px`,
          top: 0,
          bottom: 0,
          transform: `translate3d(${props.getSnappedDelta(transform.x)}px, ${transform.y}px, 0)`,
        }
      : {
          left: `${left}px`,
          width: `${Math.max(width, 60)}px`,
          top: 0,
          bottom: 0,
        }

  const slotContent = (
    <Comp
      data-slot="timeline-slot"
      data-state={isDragging ? "dragging" : "idle"}
      data-active={isActiveSlot}
      className={cn(
        "absolute inset-1 rounded cursor-move transition-all overflow-hidden",
        isDragging ? "opacity-40 shadow-sm ring-2 ring-foreground/50" : "shadow-md",
        onSlotClick && "cursor-pointer hover:ring-2 hover:ring-foreground/30",
        className,
      )}
      onClick={(e: React.MouseEvent) => {
        if (onSlotClick && !isDragging) {
          e.stopPropagation()
          onSlotClick(slot.id)
        }
      }}
      style={
        {
          "--slot-start-time": slot.startTime,
          "--slot-duration": `${slot.duration}min`,
        } as React.CSSProperties
      }
    >
      {children}
    </Comp>
  )

  return (
    <div ref={setNodeRef} {...listeners} {...attributes} className="absolute" style={style}>
      {/* Always render slot content normally */}
      {slotContent}

      {/* When active and dragging, ALSO send content through tunnel for DragOverlay */}
      {isActiveSlot && isDragging && (
        <>
          {console.log("🚇 Sending content through tunnel for slot:", slot.id)}
          <dragPreviewTunnel.In>
            <Comp
              data-slot="timeline-slot-preview"
              className={cn(
                "rounded cursor-move overflow-hidden shadow-lg",
                "h-full w-full", // Ensure it fills container
                className,
              )}
              style={
                {
                  "--slot-start-time": slot.startTime,
                  "--slot-duration": `${slot.duration}min`,
                } as React.CSSProperties
              }
            >
              {children}
            </Comp>
          </dragPreviewTunnel.In>
        </>
      )}
    </div>
  )
}

/* ============================================================================
 * TIMELINE SLOT PRIMITIVES (for content composition)
 * ========================================================================== */

interface TimelineSlotLabelProps extends React.ComponentProps<"div"> {
  asChild?: boolean
}

export function TimelineSlotLabel({ asChild, className, ...props }: TimelineSlotLabelProps) {
  const Comp = asChild ? Slot : "div"
  return <Comp data-slot="timeline-slot-label" className={cn("font-medium truncate text-xs", className)} {...props} />
}

interface TimelineSlotContentProps extends React.ComponentProps<"div"> {
  asChild?: boolean
}

export function TimelineSlotContent({ asChild, className, ...props }: TimelineSlotContentProps) {
  const Comp = asChild ? Slot : "div"
  return <Comp data-slot="timeline-slot-content" className={cn("text-xs", className)} {...props} />
}

/* ============================================================================
 * TIMELINE INDICATORS
 * ========================================================================== */

function TimelineMouseIndicator({ mouseX, time }: { mouseX: number; time: string }) {
  return (
    <div
      data-slot="timeline-mouse-indicator"
      className="absolute top-0 bottom-0 pointer-events-none z-20"
      style={{ left: `${mouseX}px` }}
    >
      <div className="absolute top-0 bottom-0 w-px bg-accent left-0" />
      <div className="absolute top-0 left-1/2 -translate-x-1/2 bg-accent text-accent-foreground px-2 py-1 rounded text-xs font-semibold whitespace-nowrap shadow-md">
        {time}
      </div>
    </div>
  )
}

interface TimelineDropRegionProps {
  startTime: string
  duration: number
}

export function TimelineDropRegion({ startTime, duration }: TimelineDropRegionProps) {
  const { config, pixelsPerMinute } = useTimeline()
  const columnWidth = config.columnWidth || 112

  const startMinutes = timeToMinutes(startTime)
  const endMinutes = startMinutes + duration
  const endTime = minutesToTime(endMinutes)

  const startPosition = (startMinutes - config.startHour * 60) * pixelsPerMinute + columnWidth
  const endPosition = (endMinutes - config.startHour * 60) * pixelsPerMinute + columnWidth
  const width = endPosition - startPosition

  return (
    <div
      data-slot="timeline-drop-region"
      className="absolute top-0 bottom-0 pointer-events-none z-[12]"
      style={{ left: `${startPosition}px`, width: `${width}px` }}
    >
      <div className="absolute top-2 left-1/2 -translate-x-1/2 bg-accent text-accent-foreground px-3 py-1.5 rounded text-sm font-semibold whitespace-nowrap shadow-md">
        {startTime} - {endTime}
      </div>
      <div className="absolute top-0 bottom-0 left-0 w-0.5 bg-accent" />
      <div className="absolute top-0 bottom-0 right-0 w-0.5 bg-accent" />
      <div className="absolute inset-0 bg-accent/[0.07]" />
    </div>
  )
}

interface TimelineCurrentTimeProps {
  className?: string
  nowLabel?: string
}

export function TimelineCurrentTime({ className, nowLabel = "Now" }: TimelineCurrentTimeProps) {
  const { config, pixelsPerMinute } = useTimeline()
  const columnWidth = config.columnWidth || 112

  const [now, setNow] = useState(new Date())

  useEffect(() => {
    const interval = setInterval(() => setNow(new Date()), 60000) // Update every minute
    return () => clearInterval(interval)
  }, [])

  const currentMinutes = now.getHours() * 60 + now.getMinutes()
  const position = (currentMinutes - config.startHour * 60) * pixelsPerMinute + columnWidth

  // Only show if within timeline range
  if (currentMinutes < config.startHour * 60 || currentMinutes > config.endHour * 60) {
    return null
  }

  return (
    <div
      data-slot="timeline-current-time"
      className={cn("absolute top-0 bottom-0 w-0.5 bg-secondary pointer-events-none z-[15]", className)}
      style={{ left: `${position}px` }}
    >
      <div className="absolute top-0 left-1/2 -translate-x-1/2 bg-secondary text-foreground px-2 py-1 rounded text-xs font-medium whitespace-nowrap shadow-md z-50">
        {nowLabel}: {minutesToTime(currentMinutes)}
      </div>
    </div>
  )
}

/* ============================================================================
 * TIMELINE GRID (for custom layouts)
 * ========================================================================== */

interface TimelineGridProps {
  children: React.ReactNode
  className?: string
}

export function TimelineGrid({ children, className, ...props }: TimelineGridProps & any) {
  const { timelineWidth } = useTimeline()

  // Get active slot data for drop region and ghost preview
  const activeSlot =
    props._showDropRegion && props.slots ? props.slots.find((s: TimelineSlotData) => s.id === props.activeSlotId) : null

  return (
    <div
      data-slot="timeline-grid-container"
      className={cn("relative", className)}
      style={{ minWidth: `${timelineWidth + 200}px` }}
    >
      {React.Children.map(children, child => {
        if (React.isValidElement(child)) {
          return React.cloneElement(child as React.ReactElement<any>, props)
        }
        return child
      })}

      {/* Drop region highlight */}
      {props._showDropRegion && props._dropRegionTime && activeSlot && (
        <TimelineDropRegion startTime={props._dropRegionTime} duration={activeSlot.duration} />
      )}
    </div>
  )
}

/* ============================================================================
 * DROP GHOST (Shows where slot will land)
 * ========================================================================== */

function TimelineDropGhost({
  activeSlotId,
  allSlots,
  newTime,
  isValid,
  config,
  pixelsPerMinute,
}: {
  activeSlotId: string
  allSlots: TimelineSlotData[]
  newTime: string
  isValid: boolean
  config: TimelineConfig
  pixelsPerMinute: number
}) {
  const slot = allSlots.find(s => s.id === activeSlotId)
  if (!slot) return null

  const startMinutes = timeToMinutes(newTime)
  const left = (startMinutes - config.startHour * 60) * pixelsPerMinute
  const width = slot.duration * pixelsPerMinute

  if (!isValid) return null

  return (
    <div
      data-slot="timeline-drop-ghost"
      className={cn("absolute rounded-md pointer-events-none", "bg-foreground/20")}
      style={{
        left: `${left}px`,
        width: `${Math.max(width, 60)}px`,
        top: "2px",
        bottom: "2px",
        zIndex: 100,
      }}
    />
  )
}

/* ============================================================================
 * EXPORTS
 * ========================================================================== */

export { useTimeline, TimelineMouseIndicator }
```

### Availability

A weekly availability designer with draggable and resizable time slots.

- Docs: https://www.abui.io/blocks/availability
- Registry item: https://www.abui.io/r/availability.json
- Type: registry:block
- Install: `npx shadcn@latest add @abui/availability`
- npm dependencies: lucide-react
- Registry dependencies: button

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/availability.tsx

```tsx
"use client"

import * as React from "react"
import { Clock, Settings, X } from "lucide-react"
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
import {
  DndContext,
  DragOverlay,
  useSensor,
  useSensors,
  PointerSensor,
  useDraggable,
  useDroppable,
  DragStartEvent,
  DragEndEvent,
  DragMoveEvent,
  DragOverEvent,
} from "@dnd-kit/core"
import tunnel from "tunnel-rat"
import { nanoid } from "nanoid"

// --- Types ---

export interface TimeSpan {
  active?: boolean
  id: string
  week_day: number // 0-6 - Sunday-Saturday
  start_time: string // "HH:mm"
  end_time: string // "HH:mm"
}

interface AvailabilityProps {
  value?: TimeSpan[]
  onValueChange?: (value: TimeSpan[]) => void
  disabled?: TimeSpan[] // Disabled regions where no events can exist
  days?: number[] // 0-6
  showAllDays?: boolean // If true, renders all 7 days, but disables interactions on days not in 'days' array
  timeIncrements?: number // minutes, default 30
  startTime?: number // hour 0-23, default 7
  endTime?: number // hour 0-23, default 23
  useAmPm?: boolean
  mergeAdjacent?: boolean // default true - merge spans that touch end-to-end
  slotClassName?: string // className for time slot items (default: "bg-muted")
  className?: string
}

// --- Utils ---

const timeToMinutes = (time: string) => {
  const [h, m] = time.split(":").map(Number)
  return h * 60 + m
}

const minutesToTime = (minutes: number) => {
  const h = Math.floor(minutes / 60)
  const m = minutes % 60
  return `${h.toString().padStart(2, "0")}:${m.toString().padStart(2, "0")}`
}

const formatDisplayTime = (time: string, useAmPm: boolean) => {
  if (!useAmPm) return time
  const [h, m] = time.split(":").map(Number)
  const ampm = h >= 12 ? "PM" : "AM"
  const h12 = h % 12 || 12
  return `${h12}:${m.toString().padStart(2, "0")} ${ampm}`
}

// Helper to generate a simple unique ID (not crypto secure but sufficient for UI)
const generateId = () => nanoid()

const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]

/**
 * Merges adjacent (contiguous) time spans on the same day.
 * Adjacent means one span's end_time equals another's start_time.
 * The merged span keeps the id of the earliest span.
 */
const mergeAdjacentSpans = (spans: TimeSpan[]): TimeSpan[] => {
  if (spans.length === 0) return spans

  // Group by day
  const byDay = new Map<number, TimeSpan[]>()
  spans.forEach(span => {
    const daySpans = byDay.get(span.week_day) || []
    daySpans.push(span)
    byDay.set(span.week_day, daySpans)
  })

  const merged: TimeSpan[] = []

  // Process each day
  byDay.forEach(daySpans => {
    // Sort by start time
    const sorted = [...daySpans].sort((a, b) => timeToMinutes(a.start_time) - timeToMinutes(b.start_time))

    let current = sorted[0]

    for (let i = 1; i < sorted.length; i++) {
      const next = sorted[i]

      // Check if current and next are adjacent (touching)
      if (current.end_time === next.start_time) {
        // Merge: extend current to include next
        current = {
          ...current,
          end_time: next.end_time,
          // Keep the earliest span's id (current is already earlier due to sorting)
        }
      } else {
        // Not adjacent, push current and move to next
        merged.push(current)
        current = next
      }
    }

    // Push the last span
    merged.push(current)
  })

  return merged
}

// --- Hooks ---

/**
 * Hook to handle creation dragging logic on a day column.
 */
function useCalendarCreation({
  containerRef,
  timeIncrements,
  startTime,
  endTime,
  events,
  disabledEvents = [],
  onCreate,
  colIndex,
  isDayDisabled = false,
}: {
  containerRef: React.RefObject<HTMLDivElement | null>
  timeIncrements: number
  startTime: number
  endTime: number
  events: TimeSpan[]
  disabledEvents?: TimeSpan[]
  onCreate: (dayIndex: number, start: number, end: number) => void
  colIndex: number
  isDayDisabled?: boolean
}) {
  const [isCreating, setIsCreating] = React.useState(false)
  const [creationStart, setCreationStart] = React.useState<number | null>(null)
  const [currentMouseY, setCurrentMouseY] = React.useState<number | null>(null)

  const totalMinutes = (endTime - startTime) * 60
  const startOffset = startTime * 60

  // Combine events and disabled regions for constraints
  // Sort all items by start time to determine safe zones
  const sortedConstraints = React.useMemo(() => {
    return [...events, ...disabledEvents].sort((a, b) => timeToMinutes(a.start_time) - timeToMinutes(b.start_time))
  }, [events, disabledEvents])

  const getMinutesFromY = (y: number) => {
    if (!containerRef.current) return 0
    const rect = containerRef.current.getBoundingClientRect()
    const relativeY = y - rect.top
    const percentage = Math.max(0, Math.min(1, relativeY / rect.height))
    const minutes = percentage * totalMinutes + startOffset
    return Math.round(minutes / timeIncrements) * timeIncrements
  }

  const handlePointerDown = (e: React.PointerEvent) => {
    if (isDayDisabled) return // No interaction if day is fully disabled
    if (e.target !== e.currentTarget) return // Only trigger on empty space
    // Prevent default drag behavior and text selection, but allow touch scrolling if not handled
    e.preventDefault()

    // Capture pointer to track movement even if it leaves the element
    containerRef.current?.setPointerCapture(e.pointerId)

    const startMins = getMinutesFromY(e.clientY)

    // Check strict overlap at start point (cannot start creation inside an event or disabled region)
    const isOverlapping = sortedConstraints.some(ev => {
      const s = timeToMinutes(ev.start_time)
      const e = timeToMinutes(ev.end_time)
      return startMins >= s && startMins < e
    })
    if (isOverlapping) return

    // Find constraints
    const prevEvent = sortedConstraints.filter(ev => timeToMinutes(ev.end_time) <= startMins).pop()
    const nextEvent = sortedConstraints.find(ev => timeToMinutes(ev.start_time) >= startMins)

    const minStartMins = prevEvent ? timeToMinutes(prevEvent.end_time) : startOffset
    const maxEndMins = nextEvent ? timeToMinutes(nextEvent.start_time) : endTime * 60

    setCreationStart(startMins)
    setCurrentMouseY(startMins)
    setIsCreating(true)

    const handlePointerMove = (ev: PointerEvent) => {
      const currentMins = getMinutesFromY(ev.clientY)
      // Clamp to constraints
      const clampedMins = Math.max(minStartMins, Math.min(currentMins, maxEndMins))
      setCurrentMouseY(clampedMins)
    }

    const handlePointerUp = (ev: PointerEvent) => {
      const currentMins = getMinutesFromY(ev.clientY)

      let finalStart = Math.min(startMins, currentMins)
      let finalEnd = Math.max(startMins, currentMins)

      // Clamp to constraints
      finalStart = Math.max(minStartMins, finalStart)
      finalEnd = Math.min(maxEndMins, finalEnd)

      // Ensure minimum size
      if (finalEnd - finalStart < timeIncrements) {
        finalEnd = Math.min(finalStart + timeIncrements, maxEndMins)
      }

      // Click-to-create logic (if essentially no drag occurred, try to make a 1-hour slot)
      if (finalEnd - finalStart <= timeIncrements) {
        const oneHourEnd = finalStart + 60
        finalEnd = Math.min(oneHourEnd, maxEndMins)
      }

      if (finalEnd > finalStart) {
        onCreate(colIndex, finalStart, finalEnd)
      }

      setIsCreating(false)
      setCreationStart(null)
      setCurrentMouseY(null)

      // Release pointer capture
      containerRef.current?.releasePointerCapture(ev.pointerId)

      // Cleanup listeners (though using setPointerCapture implicitly handles some of this, explicit cleanup is safe)
      window.removeEventListener("pointermove", handlePointerMove)
      window.removeEventListener("pointerup", handlePointerUp)
    }

    window.addEventListener("pointermove", handlePointerMove)
    window.addEventListener("pointerup", handlePointerUp)
  }

  return {
    isCreating,
    creationStart,
    currentMouseY,
    totalMinutes,
    startOffset,
    sortedConstraints,
    handlePointerDown,
  }
}

// --- Components ---

// Context to share dragging state across components
const AvailabilityDragContext = React.createContext<{
  dragPreviewTunnel: ReturnType<typeof tunnel>
  activeId: string | null
  activeSpan: TimeSpan | null
  overDayIndex: number | null
  deltaY: number
  timeIncrements: number
  isDropValid: boolean
} | null>(null)

export function Availability({
  value = [],
  onValueChange,
  disabled = [],
  days = [0, 1, 2, 3, 4, 5, 6],
  showAllDays = true,
  timeIncrements = 30,
  startTime = 7,
  endTime = 23,
  useAmPm = false,
  mergeAdjacent = true,
  slotClassName = "bg-muted",
  className,
}: AvailabilityProps) {
  const [internalValue, setInternalValue] = React.useState<TimeSpan[]>(value)

  // Drag state
  const dragPreviewTunnel = React.useMemo(() => tunnel(), [])
  const [activeId, setActiveId] = React.useState<string | null>(null)
  const [overDayIndex, setOverDayIndex] = React.useState<number | null>(null)
  const [deltaY, setDeltaY] = React.useState(0)
  const [isDropValid, setIsDropValid] = React.useState(true)

  const mainContainerRef = React.useRef<HTMLDivElement>(null)

  // Determine which days to render
  const renderedDays = React.useMemo(() => {
    if (showAllDays) {
      return [0, 1, 2, 3, 4, 5, 6]
    }
    return days
  }, [days, showAllDays])

  React.useEffect(() => {
    setInternalValue(value)
  }, [value])

  const updateValue = (newValue: TimeSpan[], shouldMerge = false) => {
    const finalValue = shouldMerge && mergeAdjacent ? mergeAdjacentSpans(newValue) : newValue
    setInternalValue(finalValue)
    onValueChange?.(finalValue)
  }

  const handleResize = (id: string, newStart: string, newEnd: string, isComplete = false) => {
    const newValue = internalValue.map(span => {
      if (span.id === id) {
        return { ...span, start_time: newStart, end_time: newEnd }
      }
      return span
    })
    updateValue(newValue, isComplete)
  }

  const handleCreate = (dayIndex: number, startMinutes: number, endMinutes: number) => {
    const newSpan: TimeSpan = {
      id: generateId(),
      week_day: dayIndex, // Directly use the dayIndex (0-6)
      start_time: minutesToTime(startMinutes),
      end_time: minutesToTime(endMinutes),
      active: true,
    }
    updateValue([...internalValue, newSpan], true)
  }

  const handleDelete = (id: string) => {
    updateValue(
      internalValue.filter(s => s.id !== id),
      true,
    )
  }

  const handleMove = (id: string, newStart: string, newEnd: string, newDayIndex: number) => {
    const newValue = internalValue.map(span => {
      if (span.id === id) {
        return { ...span, start_time: newStart, end_time: newEnd, week_day: newDayIndex }
      }
      return span
    })
    updateValue(newValue, true)
  }

  // Validation helper
  const validatePlacement = (
    span: TimeSpan,
    targetDayIndex: number,
    deltaY: number,
    containerHeight: number,
  ): { isValid: boolean; newStart: number; duration: number } => {
    const totalMinutes = (endTime - startTime) * 60
    const pixelsPerMinute = containerHeight / totalMinutes
    const deltaMinutesRaw = deltaY / pixelsPerMinute
    const deltaMinutes = Math.round(deltaMinutesRaw / timeIncrements) * timeIncrements

    const originalStart = timeToMinutes(span.start_time)
    const duration = timeToMinutes(span.end_time) - originalStart

    const newStart = originalStart + deltaMinutes
    const newEnd = newStart + duration

    // Check bounds
    const dayStartMins = startTime * 60
    const dayEndMins = endTime * 60

    if (newStart < dayStartMins || newEnd > dayEndMins) {
      return { isValid: false, newStart, duration }
    }

    // Check if day is active (in allowed days list)
    if (!days.includes(targetDayIndex)) {
      return { isValid: false, newStart, duration }
    }

    // Check collisions with active events
    const dayEvents = internalValue.filter(e => e.week_day === targetDayIndex && e.id !== span.id)
    const hasEventOverlap = dayEvents.some(e => {
      const eStart = timeToMinutes(e.start_time)
      const eEnd = timeToMinutes(e.end_time)
      return newStart < eEnd && newEnd > eStart
    })

    if (hasEventOverlap) {
      return { isValid: false, newStart, duration }
    }

    // Check collisions with disabled regions
    const dayDisabled = disabled.filter(e => e.week_day === targetDayIndex)
    const hasDisabledOverlap = dayDisabled.some(e => {
      const eStart = timeToMinutes(e.start_time)
      const eEnd = timeToMinutes(e.end_time)
      return newStart < eEnd && newEnd > eStart
    })

    if (hasDisabledOverlap) {
      return { isValid: false, newStart, duration }
    }

    return { isValid: true, newStart, duration }
  }

  // DnD Handlers
  const sensors = useSensors(
    useSensor(PointerSensor, {
      activationConstraint: {
        distance: 8,
      },
    }),
  )

  const handleDragStart = (event: DragStartEvent) => {
    setActiveId(event.active.id as string)
    setDeltaY(0)
    setOverDayIndex(null)
    setIsDropValid(true)
  }

  const handleDragMove = (event: DragMoveEvent) => {
    setDeltaY(event.delta.y)
    checkValidity(event.active.id as string, event.over?.id, event.delta.y)
  }

  const handleDragOver = (event: DragOverEvent) => {
    if (event.over) {
      const dayIndex = parseInt(event.over.id.toString().replace("day-", ""), 10)
      if (!isNaN(dayIndex)) {
        setOverDayIndex(dayIndex)
      }
    } else {
      setOverDayIndex(null)
    }
    checkValidity(event.active.id as string, event.over?.id, event.delta.y)
  }

  const checkValidity = (activeId: string, overId: string | number | undefined, currentDeltaY: number) => {
    if (!mainContainerRef.current || !overId) {
      setIsDropValid(false)
      return
    }

    const span = internalValue.find(s => s.id === activeId)
    if (!span) return

    const targetDayIndex = parseInt(overId.toString().replace("day-", ""), 10)
    if (isNaN(targetDayIndex)) {
      setIsDropValid(false)
      return
    }

    const result = validatePlacement(span, targetDayIndex, currentDeltaY, mainContainerRef.current.clientHeight)
    setIsDropValid(result.isValid)
  }

  const handleDragCancel = () => {
    setActiveId(null)
    setOverDayIndex(null)
    setDeltaY(0)
    setIsDropValid(true)
  }

  const handleDragEnd = (event: DragEndEvent) => {
    const { active, delta, over } = event
    setActiveId(null)
    setOverDayIndex(null)
    setDeltaY(0)
    setIsDropValid(true)

    const span = internalValue.find(s => s.id === active.id)
    if (!span || !mainContainerRef.current || !over) return

    const targetDayIndex = parseInt(over.id.toString().replace("day-", ""), 10)
    if (isNaN(targetDayIndex)) return

    // Final validation before commit
    const { isValid, newStart, duration } = validatePlacement(
      span,
      targetDayIndex,
      delta.y,
      mainContainerRef.current.clientHeight,
    )

    if (!isValid) {
      // Invalid drop, do nothing (snaps back)
      return
    }

    const newEndVal = newStart + duration
    handleMove(span.id, minutesToTime(newStart), minutesToTime(newEndVal), targetDayIndex)
  }

  const activeSpan = React.useMemo(() => internalValue.find(s => s.id === activeId) || null, [activeId, internalValue])

  return (
    <DndContext
      sensors={sensors}
      onDragStart={handleDragStart}
      onDragMove={handleDragMove}
      onDragOver={handleDragOver}
      onDragEnd={handleDragEnd}
      onDragCancel={handleDragCancel}
    >
      <AvailabilityDragContext.Provider
        value={{
          dragPreviewTunnel,
          activeId,
          activeSpan,
          overDayIndex,
          deltaY,
          timeIncrements,
          isDropValid,
        }}
      >
        <div
          suppressHydrationWarning
          className={cn(
            "flex h-[600px] w-full flex-col overflow-hidden rounded-md border bg-background select-none touch-none",
            className,
          )}
        >
          {/* Header */}
          <div className="flex w-full border-b bg-muted/40">
            <div className="w-16 flex-shrink-0 border-r p-2 text-xs font-medium text-muted-foreground" />
            <div className="flex flex-1">
              {renderedDays.map(dayIndex => {
                const isActive = days.includes(dayIndex)
                return (
                  <div
                    key={dayIndex}
                    className={cn(
                      "flex-1 border-r px-2 py-3 text-center text-sm font-medium last:border-r-0",
                      !isActive && "bg-muted/30 text-muted-foreground",
                    )}
                  >
                    {DAYS[dayIndex]}
                  </div>
                )
              })}
            </div>
          </div>

          {/* Body */}
          <div className="flex flex-1 overflow-y-auto relative" ref={mainContainerRef}>
            {/* Time Labels */}
            <div className="w-16 flex-shrink-0 border-r bg-muted/10 flex flex-col">
              {Array.from({ length: endTime - startTime }).map((_, i) => {
                const hour = startTime + i
                return (
                  <div
                    key={hour}
                    className="flex-1 border-b border-dashed border-muted-foreground/20 relative flex items-center justify-start pl-3"
                  >
                    <span className="text-xs text-muted-foreground">{formatDisplayTime(`${hour}:00`, useAmPm)}</span>
                  </div>
                )
              })}
            </div>

            {/* Days Grid */}
            <div className="flex flex-1 relative">
              <div className="absolute inset-0 pointer-events-none flex flex-col">
                {Array.from({ length: endTime - startTime }).map((_, i) => (
                  <div
                    key={i}
                    className="flex-1 border-b border-dashed border-foreground/10 dark:border-muted/60 w-full relative"
                  />
                ))}
              </div>

              {renderedDays.map((dayIndex, i) => {
                // Check if this day is in the active list
                const isActive = days.includes(dayIndex)

                return (
                  <DayColumn
                    key={dayIndex}
                    dayIndex={dayIndex}
                    colIndex={i}
                    startTime={startTime}
                    endTime={endTime}
                    timeIncrements={timeIncrements}
                    events={internalValue.filter(e => e.week_day === dayIndex)}
                    disabledEvents={disabled.filter(e => e.week_day === dayIndex)}
                    onCreate={handleCreate}
                    onResize={handleResize}
                    onDelete={handleDelete}
                    useAmPm={useAmPm}
                    isDayDisabled={!isActive}
                    slotClassName={slotClassName}
                  />
                )
              })}
            </div>
          </div>

          {/* Drag Overlay */}
          <DragOverlay>
            {activeSpan && (
              <div className="w-full h-full cursor-grabbing relative opacity-80">
                <dragPreviewTunnel.Out />
              </div>
            )}
          </DragOverlay>
        </div>
      </AvailabilityDragContext.Provider>
    </DndContext>
  )
}

interface DayColumnProps {
  dayIndex: number
  colIndex: number
  startTime: number
  endTime: number
  timeIncrements: number
  events: TimeSpan[]
  disabledEvents?: TimeSpan[]
  onCreate: (dayIndex: number, start: number, end: number) => void
  onResize: (id: string, start: string, end: string, isComplete?: boolean) => void
  onDelete: (id: string) => void
  useAmPm: boolean
  isDayDisabled?: boolean
  slotClassName?: string
}

function DayColumn({
  dayIndex,
  colIndex,
  startTime,
  endTime,
  timeIncrements,
  events,
  disabledEvents = [],
  onCreate,
  onResize,
  onDelete,
  useAmPm,
  isDayDisabled = false,
  slotClassName = "bg-muted",
}: DayColumnProps) {
  const containerRef = React.useRef<HTMLDivElement>(null)

  const context = React.useContext(AvailabilityDragContext)

  // Make the column a droppable zone for day detection
  // Only droppable if not disabled
  const { setNodeRef } = useDroppable({
    id: `day-${dayIndex}`,
    disabled: isDayDisabled,
  })

  const mergedRef = (node: HTMLDivElement | null) => {
    containerRef.current = node
    setNodeRef(node)
  }

  const { isCreating, creationStart, currentMouseY, totalMinutes, startOffset, sortedConstraints, handlePointerDown } =
    useCalendarCreation({
      containerRef,
      timeIncrements,
      startTime,
      endTime,
      events,
      disabledEvents,
      onCreate,
      colIndex,
      isDayDisabled,
    })

  // Calculate ghost position
  const showGhost = context?.activeId && context.overDayIndex === dayIndex && containerRef.current && !isDayDisabled

  const ghostStyle = React.useMemo(() => {
    if (!showGhost || !context?.activeSpan || !containerRef.current) return null

    const span = context.activeSpan
    const containerHeight = containerRef.current.clientHeight
    const pixelsPerMinute = containerHeight / totalMinutes

    const deltaMinutesRaw = context.deltaY / pixelsPerMinute
    const deltaMinutes = Math.round(deltaMinutesRaw / timeIncrements) * timeIncrements

    const originalStart = timeToMinutes(span.start_time)
    const duration = timeToMinutes(span.end_time) - originalStart

    // Calculate proposed start
    const newStart = originalStart + deltaMinutes

    // Determine visual feedback based on validity
    // If we are here, context.isDropValid has already determined if this position is valid
    // We just need to render the ghost at the proposed position (not clamped, so user sees why it fails)

    return {
      top: `${((newStart - startOffset) / totalMinutes) * 100}%`,
      height: `${(duration / totalMinutes) * 100}%`,
    }
  }, [
    context?.activeId,
    context?.deltaY,
    context?.activeSpan,
    context?.overDayIndex,
    timeIncrements,
    totalMinutes,
    startOffset,
    showGhost,
  ])

  return (
    <div
      ref={mergedRef}
      className={cn(
        "flex-1 relative border-r last:border-r-0 min-w-[100px] touch-none",
        isDayDisabled && "bg-muted/30",
        context?.activeId && "z-10", // Ensure z-index when dragging
      )}
      onPointerDown={handlePointerDown}
    >
      {/* Full Day Disabled Overlay */}
      {isDayDisabled && (
        <div
          className="absolute inset-0 bg-muted/10 pointer-events-none z-20"
          style={{
            backgroundImage: `repeating-linear-gradient(45deg, transparent, transparent 5px, rgba(128,128,128,0.15) 5px, rgba(128,128,128,0.15) 10px)`,
          }}
        />
      )}

      {/* Disabled Regions */}
      {disabledEvents.map((disabled, i) => {
        const startMins = timeToMinutes(disabled.start_time)
        const endMins = timeToMinutes(disabled.end_time)
        const duration = endMins - startMins

        return (
          <div
            key={`disabled-${i}`}
            className="absolute left-0 right-0 bg-muted/40 bg-stripes-muted pointer-events-none z-0"
            style={{
              top: `${((startMins - startOffset) / totalMinutes) * 100}%`,
              height: `${(duration / totalMinutes) * 100}%`,
              // Striped pattern using CSS gradient
              backgroundImage: `repeating-linear-gradient(45deg, transparent, transparent 5px, rgba(128,128,128,0.15) 5px, rgba(128,128,128,0.15) 10px)`,
            }}
          />
        )
      })}

      {/* Ghost Element */}
      {ghostStyle && (
        <div
          className={cn(
            "absolute left-1 right-1 rounded-md border z-0 pointer-events-none transition-all duration-100 ease-out",
            context?.isDropValid ? "bg-foreground/20 border-foreground/30" : "bg-destructive/20 border-destructive/50",
          )}
          style={ghostStyle}
        />
      )}

      {events.map((event, i) => {
        // Calculate neighbors considering BOTH events and disabled regions for resizing constraints
        // sortedConstraints contains both. We just need to find neighbors relative to THIS event in that list.

        // We need a clean list of constraints excluding the event itself
        const otherConstraints = sortedConstraints.filter(e => e.id !== event.id)

        const eventStart = timeToMinutes(event.start_time)
        const eventEnd = timeToMinutes(event.end_time)

        const prevItem = otherConstraints.filter(e => timeToMinutes(e.end_time) <= eventStart).pop()
        const nextItem = otherConstraints.find(e => timeToMinutes(e.start_time) >= eventEnd)

        const minStart = prevItem ? timeToMinutes(prevItem.end_time) : startOffset
        const maxEnd = nextItem ? timeToMinutes(nextItem.start_time) : endTime * 60

        const isDragging = context?.activeId === event.id

        return (
          <DraggableTimeSpan
            key={event.id}
            span={event}
            startTime={startTime}
            endTime={endTime}
            minStart={minStart}
            maxEnd={maxEnd}
            onResize={onResize}
            onDelete={onDelete}
            useAmPm={useAmPm}
            timeIncrements={timeIncrements}
            containerRef={containerRef}
            isDragging={isDragging}
            isLocked={isDayDisabled} // Pass lock state if day is disabled
            slotClassName={slotClassName}
          />
        )
      })}

      {isCreating && creationStart !== null && currentMouseY !== null && (
        <div
          className="absolute left-0 right-0 mx-1 rounded bg-primary/30 border border-primary z-20 pointer-events-none"
          style={{
            top: `${((Math.min(creationStart, currentMouseY) - startOffset) / totalMinutes) * 100}%`,
            height: `${(Math.abs(currentMouseY - creationStart) / totalMinutes) * 100}%`,
          }}
        />
      )}
    </div>
  )
}

interface DraggableTimeSpanProps {
  span: TimeSpan
  startTime: number
  endTime: number
  minStart: number
  maxEnd: number
  onResize: (id: string, start: string, end: string, isComplete?: boolean) => void
  onDelete: (id: string) => void
  useAmPm: boolean
  timeIncrements: number
  containerRef: React.RefObject<HTMLDivElement | null>
  isDragging?: boolean
  isLocked?: boolean
  slotClassName?: string
}

function DraggableTimeSpan({
  span,
  startTime,
  endTime,
  minStart,
  maxEnd,
  onResize,
  onDelete,
  useAmPm,
  timeIncrements,
  containerRef,
  isDragging,
  isLocked = false,
  slotClassName = "bg-muted",
}: DraggableTimeSpanProps) {
  const context = React.useContext(AvailabilityDragContext)
  const { attributes, listeners, setNodeRef } = useDraggable({
    id: span.id,
    data: span,
    disabled: isLocked, // Disable drag if locked
  })

  const startMinutes = timeToMinutes(span.start_time)
  const endMinutes = timeToMinutes(span.end_time)
  const totalMinutes = (endTime - startTime) * 60
  const startOffset = startTime * 60
  const durationMinutes = endMinutes - startMinutes

  // Apply transform if dragging
  const style: React.CSSProperties = {
    top: `${((startMinutes - startOffset) / totalMinutes) * 100}%`,
    height: `${(durationMinutes / totalMinutes) * 100}%`,
    // We hide the original element when dragging, but we render the tunnel content
    opacity: isDragging ? 0 : isLocked ? 0.6 : 1, // Fade if locked
  }

  const handleResizeStart = (e: React.PointerEvent, edge: "top" | "bottom") => {
    if (isLocked) return
    e.stopPropagation()
    e.preventDefault()

    // Capture pointer for resize drag
    const target = e.target as HTMLElement
    target.setPointerCapture(e.pointerId)

    const initialY = e.clientY
    const initialStart = startMinutes
    const initialEnd = endMinutes

    // Re-calculate local constraints for resize (using passed props or logic)
    // We can trust the parent passed correct minStart/maxEnd for neighbors

    const handlePointerMove = (ev: PointerEvent) => {
      if (!containerRef.current) return

      const containerHeight = containerRef.current.clientHeight
      const pixelsPerMinute = containerHeight / totalMinutes
      const deltaY = ev.clientY - initialY
      const deltaMinutes = Math.round(deltaY / pixelsPerMinute / timeIncrements) * timeIncrements

      if (deltaMinutes === 0) return

      let newStart = initialStart
      let newEnd = initialEnd

      if (edge === "top") {
        newStart += deltaMinutes
        // For resize we still want clamping to neighbors
        if (newStart < minStart) newStart = minStart
        if (newStart >= newEnd - timeIncrements) newStart = newEnd - timeIncrements
      } else {
        newEnd += deltaMinutes
        if (newEnd > maxEnd) newEnd = maxEnd
        if (newEnd <= newStart + timeIncrements) newEnd = newStart + timeIncrements
      }

      // During drag: don't merge (isComplete = false)
      onResize(span.id, minutesToTime(newStart), minutesToTime(newEnd), false)
    }

    const handlePointerUp = (ev: PointerEvent) => {
      target.releasePointerCapture(ev.pointerId)

      // Final commit with clamping logic repeated
      if (containerRef.current) {
        const containerHeight = containerRef.current.clientHeight
        const pixelsPerMinute = containerHeight / totalMinutes
        const deltaY = ev.clientY - initialY
        const deltaMinutes = Math.round(deltaY / pixelsPerMinute / timeIncrements) * timeIncrements

        let newStart = initialStart
        let newEnd = initialEnd

        if (edge === "top") {
          newStart += deltaMinutes
          if (newStart < minStart) newStart = minStart
          if (newStart >= newEnd - timeIncrements) newStart = newEnd - timeIncrements
        } else {
          newEnd += deltaMinutes
          if (newEnd > maxEnd) newEnd = maxEnd
          if (newEnd <= newStart + timeIncrements) newEnd = newStart + timeIncrements
        }

        onResize(span.id, minutesToTime(newStart), minutesToTime(newEnd), true)
      }

      window.removeEventListener("pointermove", handlePointerMove)
      window.removeEventListener("pointerup", handlePointerUp)
    }

    window.addEventListener("pointermove", handlePointerMove)
    window.addEventListener("pointerup", handlePointerUp)
  }

  const canResize = !isLocked

  const content = (
    <>
      {/* Resize Handle Top - Increased hit area */}
      {canResize && (
        <div
          className="absolute top-0 left-0 right-0 h-4 -mt-2 cursor-row-resize z-10"
          onPointerDown={e => handleResizeStart(e, "top")}
        />
      )}
      {/* Visual Top Handle */}
      <div className="absolute top-0 left-1 right-1 h-1 bg-transparent group-hover:bg-foreground/20 rounded-t-sm" />

      {/* Drag Handle Area (middle) - Use dnd-kit listeners here */}
      <div
        className={cn(
          "absolute inset-0 top-2 bottom-2 z-0",
          canResize ? "cursor-grab active:cursor-grabbing" : "cursor-default",
        )}
        {...listeners}
        {...attributes}
      />

      <TimeSpanCard
        span={span}
        useAmPm={useAmPm}
        duration={durationMinutes / 60}
        onDelete={canResize ? () => onDelete(span.id) : undefined}
      />

      {/* Resize Handle Bottom - Increased hit area */}
      {canResize && (
        <div
          className="absolute bottom-0 left-0 right-0 h-4 -mb-2 cursor-row-resize z-10"
          onPointerDown={e => handleResizeStart(e, "bottom")}
        />
      )}
      {/* Visual Bottom Handle */}
      <div className="absolute bottom-0 left-1 right-1 h-1 bg-transparent group-hover:bg-foreground/20 rounded-b-sm" />
    </>
  )

  return (
    <>
      <div
        ref={setNodeRef}
        style={style}
        className={cn(
          "absolute left-1 right-1 rounded border p-3 shadow-sm text-xs group overflow-hidden touch-none",
          slotClassName,
          isDragging && "opacity-0", // Hide original while dragging
          isLocked && "border-dashed opacity-60 cursor-default bg-muted/50",
        )}
      >
        {content}
      </div>

      {/* Tunnel visual content to overlay if dragging */}
      {isDragging && context && (
        <context.dragPreviewTunnel.In>
          <div
            className={cn(
              "absolute left-0 right-0 rounded-md border p-3 shadow-lg text-xs overflow-hidden h-full w-full",
              context.isDropValid ? "border-foreground/50 bg-foreground/10" : "border-destructive/50 bg-destructive/20",
            )}
          >
            {/* Render content without interactive handlers for the preview */}
            <div className="absolute top-0 left-1 right-1 h-1 bg-transparent group-hover:bg-foreground/20 rounded-t-sm" />
            <TimeSpanCard
              span={span}
              useAmPm={useAmPm}
              duration={durationMinutes / 60}
              // No delete button in preview
            />
            <div className="absolute bottom-0 left-1 right-1 h-1 bg-transparent group-hover:bg-foreground/20 rounded-b-sm" />
          </div>
        </context.dragPreviewTunnel.In>
      )}
    </>
  )
}

function TimeSpanCard({
  span,
  useAmPm,
  duration,
  onDelete,
}: {
  span: TimeSpan
  useAmPm: boolean
  duration?: number
  onDelete?: () => void
}) {
  const calculatedDuration = duration || (timeToMinutes(span.end_time) - timeToMinutes(span.start_time)) / 60

  return (
    <div className="h-full flex flex-col relative items-between text-foreground timespan-inner-area pointer-events-none">
      <div className="flex flex-col gap-0.5 text-inherit">
        <p className="font-semibold leading-none">{formatDisplayTime(span.start_time, useAmPm)}</p>
        <div className="flex items-center gap-0.5">
          <Clock className="h-2 w-2" />{" "}
          <p className="text-[10px] opacity-80">{calculatedDuration.toFixed(1).replace(".0", "")}h</p>
        </div>
      </div>
      {onDelete && (
        <Button
          variant="ghost"
          size="icon"
          className="h-5 w-5 hover:bg-foreground/5 dark:hover:bg-foreground/10 -mt-1 -mr-1 absolute top-0 right-0 z-20 pointer-events-auto"
          onPointerDown={e => {
            e.stopPropagation() // Prevent drag/resize from card
          }}
          onClick={e => {
            e.stopPropagation()
            onDelete()
          }}
        >
          <X className="h-3 w-3" />
        </Button>
      )}
      <div className="flex flex-col gap-1 mt-auto text-inherit">
        {!onDelete && <Settings className="h-3 w-3 opacity-50" />}
        <p className="font-semibold leading-none !text-inherit">{formatDisplayTime(span.end_time, useAmPm)}</p>
      </div>
    </div>
  )
}
```

### Calendar Year

A calendar year component.

- Docs: https://www.abui.io/blocks/calendar-year
- Registry item: https://www.abui.io/r/calendar-year.json
- Type: registry:block
- Install: `npx shadcn@latest add @abui/calendar-year`
- npm dependencies: dayjs
- Registry dependencies: button, tooltip

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/calendar-year.tsx

```tsx
"use client"

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"
import { cn } from "@/lib/utils"
import dayjs from "dayjs"
import timezone from "dayjs/plugin/timezone"
import utc from "dayjs/plugin/utc"
dayjs.extend(timezone)
dayjs.extend(utc)
// ============================================================================
// Types
// ============================================================================

/**
 * State of a calendar day
 */
export type DayState = "blocked" | "disabled"

/**
 * Day data structure
 */
export interface CalendarDay {
  date: string // YYYY-MM-DD format
  state?: DayState
  disabled?: boolean
  tooltip?: string
}

/**
 * Month structure with rows of days
 */
export interface CalendarMonth {
  name: string
  monthIndex: number
  weekdayLabels: string[]
  rows: (CalendarDay | null)[][]
}

// ============================================================================
// Variants
// ============================================================================

const calendarYearDayVariants = cva(
  "cursor-pointer inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-full text-sm font-semibold transition-all disabled:pointer-events-none disabled:opacity-50 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive relative h-9 w-9 p-0",
  {
    variants: {
      variant: {
        default: "bg-foreground text-background dark:text-background hover:bg-foreground/90 border border-foreground",
        "default-success":
          "bg-green-500 text-background hover:bg-green-600 hover:border-green-600 dark:hover:bg-green-400 dark:hover:border-green-400 border border-green-500",
        accent: "bg-accent text-background dark:text-background hover:bg-accent/90 border border-accent",
        destructive:
          "bg-destructive hover:!bg-destructive text-background focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 border border-destructive",
        outline:
          "border bg-background shadow-xs hover:bg-muted hover:text-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
        "outline-destructive": "border border-destructive bg-transparent shadow-xs text-destructive bg-transparent",
        "outline-accent": "border border-accent bg-transparent shadow-xs text-accent bg-transparent",
        "outline-success": "border border-green-500 bg-transparent shadow-xs text-green-500 bg-transparent",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80 border border-secondary",
        ghost:
          "bg-transparent text-muted-foreground hover:bg-secondary hover:text-foreground border border-transparent",
      },
    },
    defaultVariants: {
      variant: "outline",
    },
  },
)

// ============================================================================
// Utility Functions
// ============================================================================

/**
 * Generate calendar structure for a year
 * Uses dayjs locale for month and weekday names
 *
 * @param year - Year to generate calendar for
 * @param timezone - Timezone for date calculations (default: "Europe/Lisbon")
 * @returns Array of months with rows of days (dates only, no state)
 */
export function generateYearCalendar(year: number, timezone: string = "Europe/Lisbon"): CalendarMonth[] {
  const months: CalendarMonth[] = []

  // Get weekday labels (Monday to Sunday) using dayjs locale
  const weekdayLabels: string[] = []
  const weekDaysIndexes = [1, 2, 3, 4, 5, 6, 0] // Mon-Sun
  for (const dayIndex of weekDaysIndexes) {
    // Create a date that falls on this weekday
    const sampleDate = dayjs().tz(timezone).day(dayIndex)
    const dayName = sampleDate.format("dddd")
    // Capitalize first letter
    weekdayLabels.push(dayName.charAt(0).toUpperCase() + dayName.slice(1))
  }

  for (let monthIndex = 0; monthIndex < 12; monthIndex++) {
    const firstDayOfMonth = dayjs().tz(timezone).year(year).month(monthIndex).date(1)
    const monthName = firstDayOfMonth.format("MMMM")
    // Capitalize first letter
    const capitalizedMonthName = monthName.charAt(0).toUpperCase() + monthName.slice(1)
    const daysInMonth = firstDayOfMonth.daysInMonth()
    const monthDays: CalendarDay[] = []

    // Generate all days for this month (just dates, no business logic)
    for (let day = 1; day <= daysInMonth; day++) {
      const date = dayjs().tz(timezone).year(year).month(monthIndex).date(day).format("YYYY-MM-DD")

      monthDays.push({
        date,
        state: undefined,
        disabled: false,
        tooltip: undefined,
      })
    }

    // Organize days into rows (weeks)
    const rows: (CalendarDay | null)[][] = []
    const monthDaysClone = [...monthDays]

    while (monthDaysClone.length > 0) {
      const newRow: (CalendarDay | null)[] = []
      for (const dayIndex of weekDaysIndexes) {
        const testingDay = monthDaysClone[0]
        if (testingDay && dayjs(testingDay.date).tz(timezone).day() === dayIndex) {
          newRow.push(testingDay)
          monthDaysClone.shift()
        } else {
          newRow.push(null)
        }
      }
      rows.push(newRow)
    }

    months.push({
      name: capitalizedMonthName,
      monthIndex,
      weekdayLabels,
      rows,
    })
  }

  return months
}

/**
 * Check if a date is today
 */
const isDateToday = (date: string, timezone: string): boolean => {
  return dayjs(date).tz(timezone).isSame(dayjs().tz(timezone), "day")
}

// ============================================================================
// Root Component (Container)
// ============================================================================

function CalendarYear({ className, children, ...props }: React.ComponentProps<"div">) {
  return (
    <div data-slot="calendar-year" className={cn("flex h-full w-full flex-col", className)} {...props}>
      {children}
    </div>
  )
}

// ============================================================================
// Content Component (Scrollable Container)
// ============================================================================

interface CalendarYearContentProps extends React.ComponentProps<"div"> {
  scrollToCurrentMonth?: boolean
  timezone?: string
}

function CalendarYearContent({
  scrollToCurrentMonth = false,
  timezone = "Europe/Lisbon",
  className,
  children,
  ...props
}: CalendarYearContentProps) {
  const scrollContainerRef = React.useRef<HTMLDivElement>(null)
  const [hasScrolled, setHasScrolled] = React.useState(false)

  React.useEffect(() => {
    if (scrollToCurrentMonth && !hasScrolled && scrollContainerRef.current) {
      const currentMonth = dayjs().tz(timezone).month()
      const monthClass = `calendar-month-${currentMonth}`
      const element = scrollContainerRef.current.querySelector(`.${monthClass}`)

      if (element) {
        element.scrollIntoView({ behavior: "instant", block: "start" })
        setHasScrolled(true)
      }
    }
  }, [scrollToCurrentMonth, hasScrolled, timezone])

  return (
    <div
      ref={scrollContainerRef}
      data-slot="calendar-year-content"
      className={cn(
        "flex flex-col gap-12 overflow-y-auto",
        "transition-opacity duration-300",
        scrollToCurrentMonth && !hasScrolled && "opacity-0",
        className,
      )}
      {...props}
    >
      {children}
    </div>
  )
}

// ============================================================================
// Month Component
// ============================================================================

interface CalendarYearMonthProps extends React.ComponentProps<"div"> {
  name: string
  monthIndex: number
}

function CalendarYearMonth({ name, monthIndex, className, children, ...props }: CalendarYearMonthProps) {
  return (
    <div
      data-slot="calendar-month"
      className={cn(`calendar-month-${monthIndex} flex flex-col gap-3`, className)}
      {...props}
    >
      <h3 className="text-lg font-semibold">{name}</h3>
      {children}
    </div>
  )
}

// ============================================================================
// Weekday Header Component
// ============================================================================

interface CalendarYearWeekdayHeaderProps extends Omit<React.ComponentProps<"div">, "children"> {
  labels: string[]
}

function CalendarYearWeekdayHeader({ labels, className, ...props }: CalendarYearWeekdayHeaderProps) {
  return (
    <div
      data-slot="calendar-weekday-header"
      className={cn("grid grid-cols-7 gap-2 border-b pb-2 mb-2 border-border", className)}
      {...props}
    >
      {labels.map((label, i) => (
        <p key={i} className="text-sm text-muted-foreground text-left truncate">
          {label}
        </p>
      ))}
    </div>
  )
}

// ============================================================================
// Week Component
// ============================================================================

function CalendarYearWeek({ className, children, ...props }: React.ComponentProps<"div">) {
  return (
    <div data-slot="calendar-week" className={cn("grid grid-cols-7 gap-2", className)} {...props}>
      {children}
    </div>
  )
}

// ============================================================================
// Day Component
// ============================================================================

interface CalendarYearDayProps extends Omit<React.ComponentProps<"button">, "children"> {
  date: string
  state?: DayState
  variant?: VariantProps<typeof calendarYearDayVariants>["variant"]
  disabled?: boolean
  tooltip?: string
  timezone?: string
  asChild?: boolean
}

const CalendarYearDay = React.forwardRef<HTMLButtonElement, CalendarYearDayProps>(
  (
    {
      date,
      state,
      variant = "outline",
      disabled = false,
      tooltip,
      timezone = "Europe/Lisbon",
      className,
      asChild = false,
      ...props
    },
    ref,
  ) => {
    const dayNumber = dayjs(date).tz(timezone).format("DD")
    const isToday = isDateToday(date, timezone)
    const Comp = asChild ? Slot : "button"

    // Handle blocked state (not disabled but not clickable)
    const isBlocked = state === "blocked"
    const isDisabled = disabled || state === "disabled"

    const buttonContent = (
      <Comp
        ref={ref}
        data-slot="calendar-day"
        data-state={state}
        data-today={isToday}
        data-disabled={isDisabled}
        data-blocked={isBlocked}
        type="button"
        disabled={isDisabled}
        className={cn(
          calendarYearDayVariants({ variant, className }),

          // Blocked state (red) - not-allowed cursor, no hover effects
          // "data-[blocked=true]:!bg-background data-[blocked=true]:!text-destructive data-[blocked=true]:!border-destructive",
          "data-[blocked=true]:!cursor-not-allowed",

          // Today indicator
          "data-[today=true]:ring-4 data-[today=true]:ring-accent data-[today=true]:ring-offset-[0.5px]",
        )}
        {...props}
      >
        {dayNumber}
      </Comp>
    )

    if (!isDisabled && !isBlocked && tooltip) {
      return (
        <TooltipProvider delayDuration={200}>
          <Tooltip>
            <TooltipTrigger asChild>{buttonContent}</TooltipTrigger>
            <TooltipContent>
              <p>{tooltip}</p>
            </TooltipContent>
          </Tooltip>
        </TooltipProvider>
      )
    }

    return buttonContent
  },
)
CalendarYearDay.displayName = "CalendarYearDay"

// ============================================================================
// Exports
// ============================================================================

export {
  CalendarYear,
  CalendarYearContent,
  CalendarYearMonth,
  CalendarYearWeekdayHeader,
  CalendarYearWeek,
  CalendarYearDay,
  calendarYearDayVariants,
}
```

### Scroll Reveal Content A

A block that shows 3 parts of content with a specific image for each part, and a fancy line grow expand during scroll.

- Docs: https://www.abui.io/blocks/scroll-reveal-content-a
- Registry item: https://www.abui.io/r/scroll-reveal-content-a.json
- Type: registry:block
- Install: `npx shadcn@latest add @abui/scroll-reveal-content-a`
- npm dependencies: motion@12

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/marketing/scroll-reveal-content-a.tsx

```tsx
"use client"

import React from "react"
import { useRef } from "react"
import { cn } from "@/lib/utils"
import Image from "next/image"
import { useMotionValueEvent, useScroll } from "motion/react"

export const centralColumnStyle = "w-[90%] max-w-[1340px] mx-auto"
export const pageYPadding = "py-10 md:py-12 lg:py-20 xl:py-30 2xl:py-40"
const defaultTitleClass = "text-2xl md:text-3xl font-semibold mb-2 text-foreground"
const defaultDescriptionClass = "text-base md:text-lg font-medium mb-2 text-foreground max-w-[400px] leading-[130%]"
const imageClass =
  "absolute top-0 right-0 ml-auto w-auto h-full object-cover rounded-2xl transition-opacity duration-300"

export interface ItemContent {
  title: string
  description: string
  image: {
    url: string
    width: number
    height: number
    alt: string
  }
}

interface Props extends React.ComponentProps<"div"> {
  contentA: ItemContent
  contentB: ItemContent
  contentC: ItemContent
  titleClass?: string
  descriptionClass?: string
}

const ScrollRevealContentA = ({
  contentA,
  contentB,
  contentC,
  titleClass = defaultTitleClass,
  descriptionClass = defaultDescriptionClass,
  className,
  ...props
}: Props) => {
  const [scrollProgress, setScrollProgress] = React.useState(0)
  const ref0 = useRef(null)

  const { scrollYProgress } = useScroll({
    target: ref0,
  })
  useMotionValueEvent(scrollYProgress, "change", () => {
    // @ts-ignore
    setScrollProgress(scrollYProgress.current)
  })

  return (
    <div className={cn("bg-background", className)} ref={ref0} {...props}>
      <div className="max-w-[90vw] mx-auto">
        <div className="flex w-full mx-auto relative z-20">
          <div
            className={cn(centralColumnStyle, "sticky top-0 flex flex-col w-full items-start justify-center h-[100vh]")}
          >
            <div className="flex flex-row gap-16 md:gap-24 lg:gap-32 xl:gap-40 2xl:gap-48 w-full h-full">
              <div className="lg:!w-[50vw] !w-full h-auto flex flex-col justify-center gap-10 md:gap-auto">
                <PointItem
                  active={true}
                  number="01"
                  title={contentA.title}
                  description={contentA.description}
                  thresholdStart={0}
                  thresholdEnd={0.33}
                  scrollProgress={scrollProgress}
                />
                <PointItem
                  active={true}
                  number="02"
                  title={contentB.title}
                  description={contentB.description}
                  thresholdStart={0.33}
                  thresholdEnd={0.66}
                  scrollProgress={scrollProgress}
                />
                <PointItem
                  active={true}
                  number="03"
                  title={contentC.title}
                  description={contentC.description}
                  thresholdStart={0.66}
                  thresholdEnd={1}
                  scrollProgress={scrollProgress}
                />
              </div>
              <div className="hidden lg:flex flex-col justify-center items-center !w-[50vw] relative h-full">
                <Image
                  width={contentA.image.width}
                  height={contentA.image.height}
                  src={contentA.image.url}
                  alt={contentA.image.alt}
                  className={cn(imageClass, scrollProgress > -1 ? "opacity-100" : "opacity-0")}
                />
                <Image
                  width={contentB.image.width}
                  height={contentB.image.height}
                  src={contentB.image.url}
                  alt={contentB.image.alt}
                  className={cn(imageClass, scrollProgress > 0.33 ? "opacity-100" : "opacity-0")}
                />
                <Image
                  width={contentC.image.width}
                  height={contentC.image.height}
                  src={contentC.image.url}
                  alt={contentC.image.alt}
                  className={cn(imageClass, scrollProgress > 0.66 ? "opacity-100" : "opacity-0")}
                />
              </div>
            </div>
          </div>
          <div className="h-[300vh]" />
        </div>
      </div>
    </div>
  )
}

export default ScrollRevealContentA

const getBarPercentageHeight = (scrollProgress: number, thresholdStart: number, thresholdEnd: number) => {
  if (scrollProgress < thresholdStart) {
    return 0
  }
  if (scrollProgress > thresholdEnd) {
    return 100
  }
  return ((scrollProgress - thresholdStart) / (thresholdEnd - thresholdStart)) * 100
}

const PointItem = ({
  active,
  number,
  title,
  description,
  thresholdStart,
  thresholdEnd,
  scrollProgress,
}: {
  active: boolean
  number: string
  title: string
  description: string
  thresholdStart: number
  thresholdEnd: number
  scrollProgress: number
}) => {
  const barHeightPercentage = getBarPercentageHeight(scrollProgress, thresholdStart, thresholdEnd)
  const isActive = barHeightPercentage > 0
  return (
    <div className={cn("flex flex-col interactive w-full", active ? "opacity-100" : "opacity-50")}>
      <div className="w-full">
        <h3 className={cn(defaultTitleClass, "mb-4 ml-5", isActive ? "opacity-100" : "opacity-50")}>{number}</h3>
      </div>
      <div className="w-full flex relative left-[16px]">
        <div className="w-[70px] flex items-start justify-center relative">
          <div className="h-full w-[2px] bg-foreground/10 absolute top-0 left-[50%] -translate-x-1/2" />
          <div
            className="h-full w-[2px] bg-foreground absolute top-0 left-[50%] -translate-x-1/2"
            style={{ height: `${barHeightPercentage}%` }}
          />
        </div>
        <div className="w-[calc(100% - 40px)] pl-4">
          <div className="flex flex-col gap-1">
            <h3 className={cn(defaultTitleClass, isActive ? "opacity-100" : "opacity-50")}>{title}</h3>
            <p className={cn(defaultDescriptionClass, isActive ? "opacity-100" : "opacity-50")}>{description}</p>
          </div>
        </div>
      </div>
    </div>
  )
}
```

### Animated Chart

An animated column chart with spring physics, viewport-triggered animations, and support for dynamic data transitions.

- Docs: https://www.abui.io/blocks/animated-chart
- Registry item: https://www.abui.io/r/animated-chart.json
- Type: registry:block
- Install: `npx shadcn@latest add @abui/animated-chart`
- npm dependencies: motion@12

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/marketing/animated-chart.tsx

```tsx
"use client"

import * as React from "react"
import { useRef, useEffect, useMemo } from "react"
import { motion, useInView, useAnimationControls } from "motion/react"

import { cn } from "@/lib/utils"

interface ColumnData {
  title: string
  value: number
  /** String to prepend before the value (e.g., "$") */
  prependString?: string
  /** String to append after the value (e.g., "%") */
  appendString?: string
  /** Animation duration in seconds */
  animationDuration?: number
  /** Animation delay in seconds */
  animationDelay?: number
  /** ClassName applied to the animated column bar element */
  className?: string
  /** ClassName applied to the column's top border */
  topBorderClassName?: string
  /** ClassName applied to this column's title (overrides global titleClassName) */
  titleClassName?: string
  /** ClassName applied to this column's value (overrides global valueClassName) */
  valueClassName?: string
}

interface AnimatedChartProps extends React.ComponentPropsWithoutRef<"div"> {
  columns: ColumnData[]
  maxValue: number
  /** ClassName applied to all column titles */
  titleClassName?: string
  /** ClassName applied to all column values */
  valueClassName?: string
  /** When true, columns animate from zero whenever data changes. Default: false */
  restartOnDataChange?: boolean
}

interface AnimatedChartColumnProps extends React.ComponentPropsWithoutRef<"div"> {
  title: string
  value: number
  maxValue: number
  prependString?: string
  appendString?: string
  animationDuration: number
  animationDelay: number
  columnClassName?: string
  topBorderClassName?: string
  /** Global titleClassName from parent */
  globalTitleClassName?: string
  /** Global valueClassName from parent */
  globalValueClassName?: string
  /** Column-specific titleClassName (overrides global) */
  columnTitleClassName?: string
  /** Column-specific valueClassName (overrides global) */
  columnValueClassName?: string
  isInView: boolean
  isLast: boolean
  restartTrigger: number
}

function AnimatedChartColumn({
  title,
  value,
  maxValue,
  prependString,
  appendString,
  animationDuration,
  animationDelay,
  columnClassName,
  topBorderClassName,
  globalTitleClassName,
  globalValueClassName,
  columnTitleClassName,
  columnValueClassName,
  isInView,
  isLast,
  restartTrigger,
  className,
  ...props
}: AnimatedChartColumnProps) {
  const heightPercentage = (value / maxValue) * 100
  const heightPercentageRef = useRef(heightPercentage)
  heightPercentageRef.current = heightPercentage

  const barControls = useAnimationControls()
  const valueControls = useAnimationControls()

  // Handle animation when in view or when restart is triggered
  useEffect(() => {
    const animateFromZero = async () => {
      // Stop any running animations first
      barControls.stop()
      valueControls.stop()

      // Reset to zero instantly
      barControls.set({ height: 0 })
      valueControls.set({ opacity: 0 })

      // Small delay to ensure the reset is rendered before animating
      await new Promise(resolve => requestAnimationFrame(resolve))

      // Animate to target values
      if (isInView) {
        barControls.start({
          height: `${heightPercentageRef.current}%`,
          transition: {
            type: "spring",
            damping: 25,
            stiffness: 50,
            delay: animationDelay,
          },
        })

        valueControls.start({
          opacity: 1,
          transition: {
            delay: animationDelay + animationDuration * 0.5,
            duration: 0.3,
          },
        })
      }
    }

    animateFromZero()
  }, [restartTrigger, isInView, animationDelay, animationDuration, barControls, valueControls])

  return (
    <div
      data-slot="animated-charts-column"
      className={cn("relative flex-1 flex flex-col", !isLast && "border-r", className)}
      {...props}
    >
      {/* Title wrapper - fixed position at top of column */}
      <div data-slot="animated-charts-column-title-wrapper" className="absolute top-0 left-0 right-0 p-2 px-3">
        <span
          data-slot="animated-charts-column-title"
          className={cn("text-base font-normal text-foreground/50", globalTitleClassName, columnTitleClassName)}
        >
          {title}
        </span>
      </div>

      {/* Bar container - takes remaining space and aligns bar to bottom */}
      <div className="relative flex-1 flex flex-col justify-end border-t border-border/10">
        {/* Column bar */}
        <motion.div
          data-slot="animated-charts-column-bar"
          className={cn("relative w-full border-t-2 border-border/30 bg-muted/20", columnClassName, topBorderClassName)}
          initial={{ height: 0 }}
          animate={barControls}
        >
          {/* Value positioned at top-left inside the bar */}
          <motion.span
            data-slot="animated-charts-column-value"
            className={cn(
              "absolute top-2 left-3 text-base font-normal text-foreground",
              globalValueClassName,
              columnValueClassName,
            )}
            initial={{ opacity: 0 }}
            animate={valueControls}
          >
            {prependString && `${prependString} `}
            {value}
            {appendString && ` ${appendString}`}
          </motion.span>
        </motion.div>
      </div>
    </div>
  )
}

function AnimatedChart({
  columns,
  maxValue,
  titleClassName,
  valueClassName,
  restartOnDataChange = false,
  className,
  ...props
}: AnimatedChartProps) {
  const ref = useRef<HTMLDivElement>(null)
  const isInView = useInView(ref, { once: true, amount: 0.5 })

  // Generate a data signature to detect changes
  const dataSignature = useMemo(() => {
    return JSON.stringify(columns.map(c => ({ title: c.title, value: c.value })))
  }, [columns])

  // Track restart trigger - increments when data changes (if restartOnDataChange is true)
  const restartTriggerRef = useRef(0)
  const prevDataSignatureRef = useRef(dataSignature)

  if (restartOnDataChange && prevDataSignatureRef.current !== dataSignature) {
    restartTriggerRef.current += 1
    prevDataSignatureRef.current = dataSignature
  }

  return (
    <div ref={ref} data-slot="animated-charts" className={cn("flex w-full gap-0 border", className)} {...props}>
      {columns.map((column, index) => (
        <AnimatedChartColumn
          key={index}
          title={column.title}
          value={column.value}
          maxValue={maxValue}
          prependString={column.prependString}
          appendString={column.appendString}
          animationDuration={column.animationDuration ?? 1}
          animationDelay={column.animationDelay ?? 0}
          columnClassName={column.className}
          topBorderClassName={column.topBorderClassName}
          globalTitleClassName={titleClassName}
          globalValueClassName={valueClassName}
          columnTitleClassName={column.titleClassName}
          columnValueClassName={column.valueClassName}
          isInView={isInView}
          isLast={index === columns.length - 1}
          restartTrigger={restartTriggerRef.current}
        />
      ))}
    </div>
  )
}

export { AnimatedChart, AnimatedChartColumn }
export type { AnimatedChartProps, AnimatedChartColumnProps, ColumnData }
```

### Squeeze Carousel

A canvas-driven news carousel: one wide active card with squeezed companions that stretch on hover and slide into place, with keyboard and screen-reader support and a scroll-snap mobile layout.

- Docs: https://www.abui.io/blocks/squeeze-carousel
- Registry item: https://www.abui.io/r/squeeze-carousel.json
- Type: registry:block
- Install: `npx shadcn@latest add @abui/squeeze-carousel`
- npm dependencies: @radix-ui/react-slot, @radix-ui/react-use-controllable-state, lucide-react
- Registry dependencies: button

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/marketing/squeeze-carousel.tsx

```tsx
"use client"

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { useControllableState } from "@radix-ui/react-use-controllable-state"
import { ArrowLeft, ArrowRight } from "lucide-react"

import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"

/**
 * SqueezeCarousel
 *
 * A "what's happening" style news carousel: one wide active card followed by progressively
 * narrower companions that stretch on hover and slide into place when you navigate.
 *
 * Desktop (>= sm): the image strip is a single <canvas>. Every card is clipped to a rounded
 * rectangle and its image is cover-fitted into a fixed 16:9 box centred on the card, so a
 * card looks squeezed rather than scaled. Card widths come from flex fractions of the width
 * left over after the primary 16:9 card, and every width, gap and offset is tweened with an
 * ease-out-expo curve when the active index changes.
 *
 * Mobile (< sm): a native scroll-snap list of cards with scale, parallax and fade driven by
 * scroll progress through CSS custom properties.
 *
 * Composition:
 *
 *   <SqueezeCarousel items={items}>
 *     <SqueezeCarouselHeader>
 *       <SqueezeCarouselHeading>
 *         <SqueezeCarouselTitle>What's happening</SqueezeCarouselTitle>
 *         <SqueezeCarouselDescription>See the latest from us.</SqueezeCarouselDescription>
 *       </SqueezeCarouselHeading>
 *       <SqueezeCarouselControls>
 *         <SqueezeCarouselPrevious />
 *         <SqueezeCarouselNext />
 *       </SqueezeCarouselControls>
 *     </SqueezeCarouselHeader>
 *     <SqueezeCarouselCanvas />
 *     <SqueezeCarouselDetails>{renderCopy}</SqueezeCarouselDetails>
 *     <SqueezeCarouselMobileList>{renderCopy}</SqueezeCarouselMobileList>
 *   </SqueezeCarousel>
 */

/* -------------------------------------------------------------------------------------------------
 * Types
 * -----------------------------------------------------------------------------------------------*/

export interface SqueezeCarouselItem {
  /** Stable identifier, used as the React key. */
  id: string
  /**
   * Plain-text name of the item. Announced to screen readers ("Item 2 of 8: …") and used as
   * the default `alt` text of the mobile image.
   */
  title: string
  /** Image drawn on the desktop canvas. A 16:9 image of at least 1632×918 is recommended. */
  src: string
  /** Image used by the mobile card list. Defaults to `src`. A 336:350 crop is recommended. */
  mobileSrc?: string
  /** Alternative text for the mobile image. Defaults to `title`. Pass "" for decorative images. */
  alt?: string
  /**
   * Horizontal offset in CSS pixels applied to the image while its card is collapsed. Use it
   * to keep the focal point of the image inside the narrow column. Positive values move the
   * image to the left. Default: 0.
   */
  collapsedOffsetX?: number
  /**
   * Link opened when the primary (fully revealed) card is clicked and no
   * `SqueezeCarouselDetailAction` is registered for the item. When an action exists, clicking
   * the card activates that action instead, so router links and analytics keep working.
   */
  href?: string
}

export type SqueezeCarouselCrossOrigin = "anonymous" | "use-credentials"

export interface SqueezeCarouselNavigateOptions {
  /** Move keyboard focus to the newly active item's action once it becomes active. */
  focus?: boolean
}

export type SqueezeCarouselRenderItem = (item: SqueezeCarouselItem, index: number) => React.ReactNode

/* -------------------------------------------------------------------------------------------------
 * Canvas engine
 *
 * Framework-agnostic class that owns the <canvas>. It keeps a list of "cards" (one per visible
 * column), lays them out from a set of flex fractions, and tweens every card between layouts.
 * -----------------------------------------------------------------------------------------------*/

const SQUEEZE = {
  /** Gap before a collapsed 8px sliver. */
  smallCardGap: 8,
  /** Gap before one of the four main columns. */
  largeCardGap: 16,
  /** Width of a collapsed sliver. */
  smallCardWidth: 8,
  /** Extra width given to a hovered sliver. */
  smallCardHoverOffset: 3,
  /** Share of the leftover width taken by columns 0..3 at rest. Column 0 adds this to its 16:9 base. */
  flex: [-0.06, 0.61, 0.3, 0.15],
  /** Shares used for the columns that are not hovered while another one is. */
  flexSqueezed: [-0.12, 0.59, 0.28, 0.13],
  /** Shares used for the hovered column. */
  flexStretched: [0, 0.71, 0.4, 0.25],
  /** Tween duration in ms. */
  duration: 1000,
  /** Tween duration in ms when the user prefers reduced motion. */
  reducedMotionDuration: 200,
  /** Default corner radius of every card. */
  borderRadius: 6,
  /** The primary column is sized from the canvas height at this ratio; images are cover-fitted into it. */
  primaryAspectRatio: 16 / 9,
  /** Cap on the share of the canvas width the primary column may take, so tall canvases keep companions. */
  maxPrimaryShare: 0.75,
  /** Maximum device pixel ratio used for the backing store. */
  maxPixelRatio: 2,
} as const

const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max)
const lerp = (from: number, to: number, t: number) => from + (to - from) * t
const easeOutExpo = (t: number) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t))
const mod = (value: number, length: number) => ((value % length) + length) % length

interface EngineCard {
  itemIndex: number
  image: HTMLImageElement
  x: number
  width: number
  leftGap: number
  collapsedOffsetX: number
  columnIndex: number
  startWidth?: number
  targetWidth?: number
  startLeftGap?: number
  targetLeftGap?: number
  startCollapsedOffsetX?: number
  targetCollapsedOffsetX?: number
}

interface SqueezeCanvasEngineOptions {
  canvas: HTMLCanvasElement
  items: SqueezeCarouselItem[]
  /** Item shown in the primary column on first paint. */
  initialIndex?: number
  /** Called when a non-primary column is clicked, with the number of steps to advance. */
  onColumnClick: (steps: number) => void
  /** Called when the primary (fully revealed) column is clicked. */
  onPrimaryClick?: (event: MouseEvent) => void
  prefersReducedMotion?: boolean
  borderRadius?: number
  crossOrigin?: SqueezeCarouselCrossOrigin
}

export class SqueezeCanvasEngine {
  /** Index of the item currently (or about to be) shown in the primary column. */
  activeIndex: number

  private readonly canvas: HTMLCanvasElement
  private readonly ctx: CanvasRenderingContext2D
  private readonly dpr: number
  private readonly items: SqueezeCarouselItem[]
  private readonly images: HTMLImageElement[]
  private readonly collapsedOffsets: number[]
  private readonly onColumnClick: (steps: number) => void
  private readonly onPrimaryClick?: (event: MouseEvent) => void
  private readonly prefersReducedMotion: boolean
  private readonly borderRadius: number
  private readonly animationDuration: number
  private readonly resizeObserver: ResizeObserver | null

  private cards: EngineCard[] = []
  private numSmallCards = 3
  private visibleCardsCount = 7
  private totalGap = 0

  private canvasWidth = 0
  private canvasHeight = 0
  private primaryBaseWidth = 0
  private totalFlexWidth = 0
  private imageWidth = 0

  private flex: number[] = [...SQUEEZE.flex]
  private hoveredColumn = -1
  private columnIndexOffset = 0

  private cardsOffsetX = 0
  private startCardsOffsetX = 0
  private targetCardsOffsetX = 0
  private flexWidthOffset = 0
  private startFlexWidthOffset = 0
  private targetFlexWidthOffset = 0

  private animationStartAt = 0
  private animationFrame = 0
  private resizeFrame = 0
  private disposed = false

  constructor({
    canvas,
    items,
    initialIndex = 0,
    onColumnClick,
    onPrimaryClick,
    prefersReducedMotion = false,
    borderRadius = SQUEEZE.borderRadius,
    crossOrigin,
  }: SqueezeCanvasEngineOptions) {
    const ctx = canvas.getContext("2d")
    if (!ctx) throw new Error("SqueezeCanvasEngine: 2D canvas context is not available")

    this.canvas = canvas
    this.ctx = ctx
    this.dpr = Math.min(window.devicePixelRatio || 1, SQUEEZE.maxPixelRatio)
    this.items = items
    this.onColumnClick = onColumnClick
    this.onPrimaryClick = onPrimaryClick
    this.prefersReducedMotion = prefersReducedMotion
    this.borderRadius = borderRadius
    this.animationDuration = prefersReducedMotion ? SQUEEZE.reducedMotionDuration : SQUEEZE.duration
    this.activeIndex = items.length ? mod(initialIndex, items.length) : 0

    this.collapsedOffsets = items.map(item => item.collapsedOffsetX ?? 0)
    this.images = items.map(item => {
      const image = new Image()
      if (crossOrigin) image.crossOrigin = crossOrigin
      image.decoding = "async"
      image.src = item.src
      image.onload = this.render
      return image
    })

    this.numSmallCards = clamp(items.length - 4, 1, 3)
    this.visibleCardsCount = 4 + this.numSmallCards
    this.totalGap = SQUEEZE.smallCardGap * this.numSmallCards + 3 * SQUEEZE.largeCardGap

    this.canvas.addEventListener("pointermove", this.handlePointerMove)
    this.canvas.addEventListener("pointerleave", this.handlePointerLeave)
    this.canvas.addEventListener("click", this.handleClick)
    document.addEventListener("visibilitychange", this.render)

    this.resizeObserver =
      typeof ResizeObserver === "undefined"
        ? null
        : new ResizeObserver(() => {
            cancelAnimationFrame(this.resizeFrame)
            this.resizeFrame = requestAnimationFrame(this.resize)
          })
    this.resizeObserver?.observe(this.canvas)

    this.measure()
    this.cards = Array.from({ length: this.visibleCardsCount }, (_, column) => {
      const itemIndex = mod(this.activeIndex + column, Math.max(items.length, 1))
      return {
        itemIndex,
        image: this.images[itemIndex],
        x: 0,
        width: this.getCardWidth(column),
        leftGap: column < 4 ? SQUEEZE.largeCardGap : SQUEEZE.smallCardGap,
        collapsedOffsetX: column === 0 ? 0 : this.collapsedOffsets[itemIndex],
        columnIndex: column,
      }
    })
    this.render()
  }

  /** Advance by `delta` columns (negative values go backwards). */
  navigate = (delta: number) => {
    if (this.disposed || !this.items.length || delta === 0) return
    this.activeIndex = mod(this.activeIndex + delta, this.items.length)
    if (delta > 0) this.goToNext(delta)
    else this.goToPrevious(-delta)
  }

  /** Jump to an item, taking the shortest direction around the loop. */
  setActiveIndex = (index: number) => {
    if (!this.items.length) return
    const target = mod(index, this.items.length)
    const forward = mod(target - this.activeIndex, this.items.length)
    const backward = mod(this.activeIndex - target, this.items.length)
    if (forward === 0) return
    this.navigate(forward <= backward ? forward : -backward)
  }

  dispose = () => {
    this.disposed = true
    cancelAnimationFrame(this.animationFrame)
    cancelAnimationFrame(this.resizeFrame)
    this.resizeObserver?.disconnect()
    this.canvas.removeEventListener("pointermove", this.handlePointerMove)
    this.canvas.removeEventListener("pointerleave", this.handlePointerLeave)
    this.canvas.removeEventListener("click", this.handleClick)
    document.removeEventListener("visibilitychange", this.render)
    this.images.forEach(image => {
      image.onload = null
      image.src = ""
    })
    this.ctx.clearRect(0, 0, this.canvasWidth, this.canvasHeight)
    this.canvas.width = 0
    this.canvas.height = 0
    this.canvas.style.removeProperty("cursor")
  }

  /* ---- layout ---------------------------------------------------------------------------------- */

  private measure() {
    const { width, height } = this.canvas.getBoundingClientRect()
    this.canvas.width = Math.round(width * this.dpr)
    this.canvas.height = Math.round(height * this.dpr)
    this.ctx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0)
    this.canvasWidth = width
    this.canvasHeight = height
    const fixedWidth = this.totalGap + SQUEEZE.smallCardWidth * this.numSmallCards
    this.primaryBaseWidth = Math.min(
      height * SQUEEZE.primaryAspectRatio,
      Math.max(0, (width - fixedWidth) * SQUEEZE.maxPrimaryShare),
    )
    this.totalFlexWidth = width - this.primaryBaseWidth - this.totalGap - SQUEEZE.smallCardWidth * this.numSmallCards
    this.imageWidth = this.primaryBaseWidth + this.totalFlexWidth * SQUEEZE.flexStretched[0]
  }

  private resize = () => {
    if (this.disposed) return
    this.measure()
    cancelAnimationFrame(this.animationFrame)
    for (const card of this.cards) {
      card.width = this.getCardWidth(card.columnIndex)
      card.leftGap = card.columnIndex < 4 ? SQUEEZE.largeCardGap : SQUEEZE.smallCardGap
    }
    this.hoveredColumn = -1
    this.updateFlex()
  }

  private getCardWidth(column: number) {
    if (column < 0 || column > 3) {
      const hoverOffset = this.hoveredColumn === column ? this.targetFlexWidthOffset : 0
      return SQUEEZE.smallCardWidth + hoverOffset
    }
    const available = this.totalFlexWidth - this.targetFlexWidthOffset
    if (column === 0) return this.primaryBaseWidth + available * this.flex[0]
    return available * this.flex[column]
  }

  private updateFlex() {
    const hovered = this.hoveredColumn
    if (hovered >= 0 && hovered <= 3 && !this.prefersReducedMotion) {
      this.flex = SQUEEZE.flex.map((_, column) =>
        column === hovered ? SQUEEZE.flexStretched[column] : SQUEEZE.flexSqueezed[column],
      )
    } else {
      this.flex = [...SQUEEZE.flex]
    }
    const clickable = hovered > 0 || (hovered === 0 && !!this.onPrimaryClick)
    this.canvas.style.cursor = clickable ? "pointer" : ""
    this.startAnimation()
  }

  /* ---- navigation ------------------------------------------------------------------------------ */

  private goToPrevious(steps: number) {
    for (let i = 0; i < steps; i += 1) {
      const itemIndex = mod(this.cards[0].itemIndex - 1, this.items.length)
      this.cards.unshift({
        itemIndex,
        image: this.images[itemIndex],
        x: 0,
        width: SQUEEZE.smallCardWidth,
        leftGap: SQUEEZE.largeCardGap,
        collapsedOffsetX: 0,
        columnIndex: 0,
      })
    }
    this.cards.forEach((card, index) => {
      card.columnIndex = index + this.columnIndexOffset
    })
    this.startAnimation(steps)
  }

  private goToNext(steps: number) {
    for (let i = 0; i < steps; i += 1) {
      const itemIndex = mod(this.cards[this.cards.length - 1].itemIndex + 1, this.items.length)
      this.cards.push({
        itemIndex,
        image: this.images[itemIndex],
        x: 0,
        width: SQUEEZE.smallCardWidth,
        leftGap: SQUEEZE.smallCardGap,
        collapsedOffsetX: this.collapsedOffsets[itemIndex],
        columnIndex: 0,
      })
    }
    this.columnIndexOffset -= steps
    this.cards.forEach((card, index) => {
      card.columnIndex = index + this.columnIndexOffset
    })
    this.startAnimation()
  }

  /* ---- animation ------------------------------------------------------------------------------- */

  private startAnimation(prependedCards = 0) {
    const slot = SQUEEZE.smallCardWidth + SQUEEZE.largeCardGap
    this.startCardsOffsetX = this.cardsOffsetX - prependedCards * slot
    this.targetCardsOffsetX = this.columnIndexOffset * slot
    this.startFlexWidthOffset = this.flexWidthOffset
    this.targetFlexWidthOffset = !this.prefersReducedMotion && this.hoveredColumn > 3 ? SQUEEZE.smallCardHoverOffset : 0

    for (const card of this.cards) {
      const column = card.columnIndex
      card.startCollapsedOffsetX = card.collapsedOffsetX
      card.targetCollapsedOffsetX = column === 0 ? 0 : this.collapsedOffsets[card.itemIndex]
      card.startWidth = card.width
      card.targetWidth = this.getCardWidth(column)
      card.startLeftGap = card.leftGap
      card.targetLeftGap = column < 4 ? SQUEEZE.largeCardGap : SQUEEZE.smallCardGap
    }

    this.animationStartAt = performance.now()
    cancelAnimationFrame(this.animationFrame)
    this.animationFrame = requestAnimationFrame(this.animate)
  }

  private animate = (now: number) => {
    const progress = Math.min((now - this.animationStartAt) / this.animationDuration, 1)
    const eased = easeOutExpo(progress)

    this.cardsOffsetX = lerp(this.startCardsOffsetX, this.targetCardsOffsetX, eased)
    this.flexWidthOffset = lerp(this.startFlexWidthOffset, this.targetFlexWidthOffset, eased)
    for (const card of this.cards) {
      card.collapsedOffsetX = lerp(
        card.startCollapsedOffsetX ?? card.collapsedOffsetX,
        card.targetCollapsedOffsetX ?? card.collapsedOffsetX,
        eased,
      )
      card.width = lerp(card.startWidth ?? card.width, card.targetWidth ?? card.width, eased)
      card.leftGap = lerp(card.startLeftGap ?? card.leftGap, card.targetLeftGap ?? card.leftGap, eased)
    }

    this.render()

    if (eased < 1) {
      this.animationFrame = requestAnimationFrame(this.animate)
    } else {
      this.finishAnimation()
    }
  }

  private finishAnimation() {
    const first = this.cards.findIndex(card => card.columnIndex === 0)
    this.cards = this.cards.slice(Math.max(first, 0), Math.max(first, 0) + this.visibleCardsCount)
    this.columnIndexOffset = 0
    this.cardsOffsetX = 0
    this.render()
  }

  /* ---- rendering ------------------------------------------------------------------------------- */

  private render = () => {
    if (this.disposed) return
    this.cards.forEach((card, index) => {
      card.x = index === 0 ? this.cardsOffsetX : this.cards[index - 1].x + this.cards[index - 1].width + card.leftGap
    })
    this.ctx.clearRect(0, 0, this.canvasWidth, this.canvasHeight)
    for (const card of this.cards) {
      if (card.x + card.width < 0 || card.x > this.canvasWidth) continue
      this.renderCard(card)
    }
  }

  private renderCard({ image, width, x, collapsedOffsetX }: EngineCard) {
    if (!image.complete || image.naturalWidth === 0 || width <= 0) return

    const { ctx, canvasHeight, imageWidth } = this
    ctx.save()
    this.clipRoundedColumn(x, width)

    // Cover-fit the image into the fixed image box, then centre that box on the card.
    const imageRatio = image.naturalWidth / image.naturalHeight
    let drawWidth: number
    let drawHeight: number
    let boxOffsetX: number
    let boxOffsetY: number
    if (imageRatio > imageWidth / canvasHeight) {
      drawHeight = canvasHeight
      drawWidth = canvasHeight * imageRatio
      boxOffsetX = (imageWidth - drawWidth) / 2
      boxOffsetY = 0
    } else {
      drawWidth = imageWidth
      drawHeight = imageWidth / imageRatio
      boxOffsetX = 0
      boxOffsetY = (canvasHeight - drawHeight) / 2
    }
    const drawX = boxOffsetX + (x + width / 2 - drawWidth / 2) - collapsedOffsetX
    ctx.drawImage(image, drawX, boxOffsetY, drawWidth, drawHeight)
    ctx.restore()
  }

  private clipRoundedColumn(x: number, width: number) {
    const height = this.canvasHeight
    const radius = clamp(this.borderRadius, 0, Math.min(width, height) / 2)
    const path = new Path2D()
    path.moveTo(x + radius, 0)
    path.lineTo(x + width - radius, 0)
    path.arcTo(x + width, 0, x + width, radius, radius)
    path.lineTo(x + width, height - radius)
    path.arcTo(x + width, height, x + width - radius, height, radius)
    path.lineTo(x + radius, height)
    path.arcTo(x, height, x, height - radius, radius)
    path.lineTo(x, radius)
    path.arcTo(x, 0, x + radius, 0, radius)
    path.closePath()
    this.ctx.clip(path)
  }

  /* ---- pointer --------------------------------------------------------------------------------- */

  private columnAt(offsetX: number) {
    return this.cards.find(card => card.x <= offsetX && offsetX <= card.x + card.width)?.columnIndex ?? -1
  }

  private handlePointerMove = (event: PointerEvent) => {
    if (event.pointerType === "touch") return
    const column = this.columnAt(event.offsetX)
    if (column >= 0 && column !== this.hoveredColumn) {
      this.hoveredColumn = column
      this.updateFlex()
    }
  }

  private handlePointerLeave = () => {
    if (this.hoveredColumn === -1) return
    this.hoveredColumn = -1
    this.updateFlex()
  }

  private handleClick = (event: MouseEvent) => {
    const column = this.columnAt(event.offsetX)
    if (column > 0) this.onColumnClick(column)
    else if (column === 0) this.onPrimaryClick?.(event)
  }
}

/* -------------------------------------------------------------------------------------------------
 * Hooks
 * -----------------------------------------------------------------------------------------------*/

function usePrefersReducedMotion() {
  return React.useSyncExternalStore(
    onChange => {
      const query = window.matchMedia("(prefers-reduced-motion: reduce)")
      query.addEventListener("change", onChange)
      return () => query.removeEventListener("change", onChange)
    },
    () => window.matchMedia("(prefers-reduced-motion: reduce)").matches,
    () => false,
  )
}

/** True once the element has come within `rootMargin` of the viewport. Never goes back to false. */
function useNearViewport<T extends Element>(ref: React.RefObject<T | null>, rootMargin = "3000px 0px") {
  const [isNear, setIsNear] = React.useState(false)
  React.useEffect(() => {
    const element = ref.current
    if (!element || isNear) return
    if (typeof IntersectionObserver === "undefined") {
      setIsNear(true)
      return
    }
    const observer = new IntersectionObserver(
      entries => {
        if (entries.some(entry => entry.isIntersecting)) {
          setIsNear(true)
          observer.disconnect()
        }
      },
      { rootMargin },
    )
    observer.observe(element)
    return () => observer.disconnect()
  }, [ref, rootMargin, isNear])
  return isNear
}

function composeRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T> {
  return node => {
    for (const ref of refs) {
      if (typeof ref === "function") ref(node)
      else if (ref) (ref as React.MutableRefObject<T | null>).current = node
    }
  }
}

/* -------------------------------------------------------------------------------------------------
 * Context
 * -----------------------------------------------------------------------------------------------*/

interface SqueezeCarouselContextValue {
  items: SqueezeCarouselItem[]
  count: number
  activeIndex: number
  activeIndexRef: React.MutableRefObject<number>
  goTo: (index: number, options?: SqueezeCarouselNavigateOptions) => void
  goToNext: (steps?: number, options?: SqueezeCarouselNavigateOptions) => void
  goToPrevious: (steps?: number, options?: SqueezeCarouselNavigateOptions) => void
  engineRef: React.MutableRefObject<SqueezeCanvasEngine | null>
  actionRefs: React.MutableRefObject<Map<number, HTMLElement>>
  titleId: string
  borderRadius: number
  imageHeight?: number
  crossOrigin?: SqueezeCarouselCrossOrigin
  prefersReducedMotion: boolean
  onPrimaryClick: (event: MouseEvent) => void
}

const SqueezeCarouselContext = React.createContext<SqueezeCarouselContextValue | null>(null)

export function useSqueezeCarousel() {
  const context = React.useContext(SqueezeCarouselContext)
  if (!context) throw new Error("SqueezeCarousel components must be used within <SqueezeCarousel>")
  return context
}

interface SqueezeCarouselItemContextValue {
  item: SqueezeCarouselItem
  index: number
  /** Which list this item is rendered in. Only the desktop details take part in focus management. */
  surface: "details" | "mobile"
}

const SqueezeCarouselItemContext = React.createContext<SqueezeCarouselItemContextValue | null>(null)

export function useSqueezeCarouselItem() {
  const context = React.useContext(SqueezeCarouselItemContext)
  if (!context) {
    throw new Error(
      "SqueezeCarousel item components must be used within <SqueezeCarouselDetail> or <SqueezeCarouselMobileItem>",
    )
  }
  return context
}

/* -------------------------------------------------------------------------------------------------
 * Root
 * -----------------------------------------------------------------------------------------------*/

export interface SqueezeCarouselProps extends React.ComponentProps<"section"> {
  /** Items to show. Keep the array reference stable (module scope or useMemo) to avoid re-creating the canvas. */
  items: SqueezeCarouselItem[]
  /** Controlled active item index. */
  activeIndex?: number
  /** Initial active item index for uncontrolled usage. @default 0 */
  defaultActiveIndex?: number
  /** Called whenever the active index changes, in both controlled and uncontrolled mode. */
  onActiveIndexChange?: (index: number) => void
  /** Corner radius of the cards in CSS pixels. Also exposed as `--squeeze-carousel-radius`. @default 6 */
  borderRadius?: number
  /**
   * Height of the images as a percentage of the small viewport height (`svh`), for both the
   * desktop canvas and the mobile cards. For example `50` makes the images exactly 50svh tall.
   * When omitted the canvas keeps a 1232:460 aspect ratio and mobile cards 336:350.
   */
  imageHeight?: number
  /**
   * Called when the primary (fully revealed) card is clicked. Defaults to activating the item's
   * `SqueezeCarouselDetailAction` (or opening `item.href`), with modifier keys opening a new tab.
   */
  onActiveItemClick?: (item: SqueezeCarouselItem, index: number, event: MouseEvent) => void
  /** `crossOrigin` used when loading canvas images. Only needed if you read the canvas pixels back. */
  crossOrigin?: SqueezeCarouselCrossOrigin
  /** Text announced to screen readers when the active item changes. */
  announce?: (item: SqueezeCarouselItem, index: number, count: number) => string
}

const defaultAnnounce = (item: SqueezeCarouselItem, index: number, count: number) =>
  `Item ${index + 1} of ${count}: ${item.title}`

function SqueezeCarousel({
  items,
  activeIndex: activeIndexProp,
  defaultActiveIndex = 0,
  onActiveIndexChange,
  borderRadius = SQUEEZE.borderRadius,
  imageHeight,
  onActiveItemClick,
  crossOrigin,
  announce = defaultAnnounce,
  className,
  style,
  children,
  ...props
}: SqueezeCarouselProps) {
  const count = items.length
  const [activeIndexState, setActiveIndexState] = useControllableState({
    prop: activeIndexProp,
    defaultProp: defaultActiveIndex,
    onChange: onActiveIndexChange,
    caller: "SqueezeCarousel",
  })
  const activeIndex = count ? mod(activeIndexState, count) : 0

  const titleId = React.useId()
  const engineRef = React.useRef<SqueezeCanvasEngine | null>(null)
  const actionRefs = React.useRef(new Map<number, HTMLElement>())
  const activeIndexRef = React.useRef(activeIndex)
  activeIndexRef.current = activeIndex
  const prefersReducedMotion = usePrefersReducedMotion()
  const [focusRequest, setFocusRequest] = React.useState(0)

  const navigateBy = React.useCallback(
    (delta: number, options?: SqueezeCarouselNavigateOptions) => {
      if (!count) return
      if (delta !== 0) {
        engineRef.current?.navigate(delta)
        setActiveIndexState(previous => mod((previous ?? 0) + delta, count))
      }
      if (options?.focus) setFocusRequest(request => request + 1)
    },
    [count, setActiveIndexState],
  )

  const goToNext = React.useCallback(
    (steps = 1, options?: SqueezeCarouselNavigateOptions) => navigateBy(Math.abs(steps), options),
    [navigateBy],
  )
  const goToPrevious = React.useCallback(
    (steps = 1, options?: SqueezeCarouselNavigateOptions) => navigateBy(-Math.abs(steps), options),
    [navigateBy],
  )
  const goTo = React.useCallback(
    (index: number, options?: SqueezeCarouselNavigateOptions) => {
      if (!count) return
      const target = mod(index, count)
      const current = activeIndexRef.current
      const forward = mod(target - current, count)
      const backward = mod(current - target, count)
      navigateBy(forward <= backward ? forward : -backward, options)
    },
    [count, navigateBy],
  )

  // Keep the canvas in sync with controlled updates coming from outside.
  React.useEffect(() => {
    const engine = engineRef.current
    if (engine && engine.activeIndex !== activeIndex) engine.setActiveIndex(activeIndex)
  }, [activeIndex])

  // Move focus to the active action after keyboard navigation.
  React.useEffect(() => {
    if (focusRequest === 0) return
    actionRefs.current.get(activeIndex)?.focus()
  }, [focusRequest, activeIndex])

  // Clicking the primary card behaves like clicking the item's action.
  const onActiveItemClickRef = React.useRef(onActiveItemClick)
  onActiveItemClickRef.current = onActiveItemClick
  const onPrimaryClick = React.useCallback(
    (event: MouseEvent) => {
      const index = activeIndexRef.current
      const item = items[index]
      if (!item) return
      if (onActiveItemClickRef.current) {
        onActiveItemClickRef.current(item, index, event)
        return
      }
      const action = actionRefs.current.get(index)
      const href = action?.getAttribute("href") ?? item.href
      if (event.metaKey || event.ctrlKey || event.shiftKey) {
        if (href) window.open(href, "_blank", "noopener")
        return
      }
      if (action) action.click()
      else if (href) window.location.assign(href)
    },
    [items],
  )

  const value = React.useMemo<SqueezeCarouselContextValue>(
    () => ({
      items,
      count,
      activeIndex,
      activeIndexRef,
      goTo,
      goToNext,
      goToPrevious,
      engineRef,
      actionRefs,
      titleId,
      borderRadius,
      imageHeight,
      crossOrigin,
      prefersReducedMotion,
      onPrimaryClick,
    }),
    [
      items,
      count,
      activeIndex,
      goTo,
      goToNext,
      goToPrevious,
      titleId,
      borderRadius,
      imageHeight,
      crossOrigin,
      prefersReducedMotion,
      onPrimaryClick,
    ],
  )

  const activeItem = items[activeIndex]

  return (
    <SqueezeCarouselContext.Provider value={value}>
      <section
        data-slot="squeeze-carousel"
        data-active-index={activeIndex}
        aria-roledescription="carousel"
        aria-labelledby={titleId}
        className={cn("flex w-full flex-col gap-8", className)}
        style={
          {
            "--squeeze-carousel-radius": `${borderRadius}px`,
            ...(imageHeight !== undefined && { "--squeeze-carousel-image-height": `${imageHeight}svh` }),
            ...style,
          } as React.CSSProperties
        }
        {...props}
      >
        {children}
        <div data-slot="squeeze-carousel-status" aria-live="polite" aria-atomic="true" className="sr-only">
          {activeItem ? announce(activeItem, activeIndex, count) : null}
        </div>
      </section>
    </SqueezeCarouselContext.Provider>
  )
}

/* -------------------------------------------------------------------------------------------------
 * Header
 * -----------------------------------------------------------------------------------------------*/

export type SqueezeCarouselHeaderProps = React.ComponentProps<"header">

function SqueezeCarouselHeader({ className, ...props }: SqueezeCarouselHeaderProps) {
  return (
    <header
      data-slot="squeeze-carousel-header"
      className={cn("mb-2 flex items-end justify-between gap-16 lg:mb-0", className)}
      {...props}
    />
  )
}

export type SqueezeCarouselHeadingProps = React.ComponentProps<"div">

function SqueezeCarouselHeading({ className, ...props }: SqueezeCarouselHeadingProps) {
  return (
    <div data-slot="squeeze-carousel-heading" className={cn("flex flex-col sm:mb-2 lg:mb-8", className)} {...props} />
  )
}

export interface SqueezeCarouselTitleProps extends React.ComponentProps<"h2"> {
  asChild?: boolean
}

const headingLgClassName =
  "max-w-[43ch] text-pretty text-[1.375rem] font-light leading-[1.2] tracking-[-0.01em] sm:text-[1.75rem] sm:leading-[1.1] lg:text-[2rem] lg:leading-[1.07] lg:tracking-[-0.02em]"

function SqueezeCarouselTitle({ asChild, className, ...props }: SqueezeCarouselTitleProps) {
  const { titleId } = useSqueezeCarousel()
  const Comp = asChild ? Slot : "h2"
  return (
    <Comp
      id={titleId}
      data-slot="squeeze-carousel-title"
      className={cn(headingLgClassName, "text-foreground", className)}
      {...props}
    />
  )
}

export interface SqueezeCarouselDescriptionProps extends React.ComponentProps<"p"> {
  asChild?: boolean
}

function SqueezeCarouselDescription({ asChild, className, ...props }: SqueezeCarouselDescriptionProps) {
  const Comp = asChild ? Slot : "p"
  return (
    <Comp
      data-slot="squeeze-carousel-description"
      className={cn(headingLgClassName, "text-muted-foreground", className)}
      {...props}
    />
  )
}

/* -------------------------------------------------------------------------------------------------
 * Controls
 * -----------------------------------------------------------------------------------------------*/

export type SqueezeCarouselControlsProps = React.ComponentProps<"div">

function SqueezeCarouselControls({ className, ...props }: SqueezeCarouselControlsProps) {
  return (
    <div
      role="group"
      aria-label="Carousel navigation"
      data-slot="squeeze-carousel-controls"
      className={cn("hidden shrink-0 gap-2 sm:flex", className)}
      {...props}
    />
  )
}

export type SqueezeCarouselNavButtonProps = React.ComponentProps<typeof Button>

function useNavKeyDown(onKeyDown?: React.KeyboardEventHandler<HTMLButtonElement>) {
  const { goToNext, goToPrevious } = useSqueezeCarousel()
  return React.useCallback(
    (event: React.KeyboardEvent<HTMLButtonElement>) => {
      onKeyDown?.(event)
      if (event.defaultPrevented) return
      if (event.key === "ArrowLeft") {
        event.preventDefault()
        goToPrevious()
      } else if (event.key === "ArrowRight") {
        event.preventDefault()
        goToNext()
      }
    },
    [onKeyDown, goToNext, goToPrevious],
  )
}

const navButtonClassName = "size-10 rounded-md [&_svg]:size-4"

function SqueezeCarouselPrevious({ className, children, onClick, onKeyDown, ...props }: SqueezeCarouselNavButtonProps) {
  const { goToPrevious } = useSqueezeCarousel()
  const handleKeyDown = useNavKeyDown(onKeyDown)
  return (
    <Button
      type="button"
      variant="secondary"
      size="icon"
      aria-label="Previous slide"
      data-slot="squeeze-carousel-previous"
      className={cn(navButtonClassName, className)}
      onClick={event => {
        onClick?.(event)
        if (!event.defaultPrevented) goToPrevious()
      }}
      onKeyDown={handleKeyDown}
      {...props}
    >
      {children ?? <ArrowLeft aria-hidden="true" />}
    </Button>
  )
}

function SqueezeCarouselNext({ className, children, onClick, onKeyDown, ...props }: SqueezeCarouselNavButtonProps) {
  const { goToNext } = useSqueezeCarousel()
  const handleKeyDown = useNavKeyDown(onKeyDown)
  return (
    <Button
      type="button"
      variant="secondary"
      size="icon"
      aria-label="Next slide"
      data-slot="squeeze-carousel-next"
      className={cn(navButtonClassName, className)}
      onClick={event => {
        onClick?.(event)
        if (!event.defaultPrevented) goToNext()
      }}
      onKeyDown={handleKeyDown}
      {...props}
    >
      {children ?? <ArrowRight aria-hidden="true" />}
    </Button>
  )
}

/* -------------------------------------------------------------------------------------------------
 * Canvas (desktop image strip)
 * -----------------------------------------------------------------------------------------------*/

export type SqueezeCarouselCanvasProps = React.ComponentProps<"canvas">

function SqueezeCarouselCanvas({ className, ref, ...props }: SqueezeCarouselCanvasProps) {
  const {
    items,
    engineRef,
    activeIndexRef,
    goToNext,
    borderRadius,
    imageHeight,
    crossOrigin,
    prefersReducedMotion,
    onPrimaryClick,
  } = useSqueezeCarousel()
  const canvasRef = React.useRef<HTMLCanvasElement | null>(null)
  const isNear = useNearViewport(canvasRef)
  const goToNextRef = React.useRef(goToNext)
  goToNextRef.current = goToNext
  const onPrimaryClickRef = React.useRef(onPrimaryClick)
  onPrimaryClickRef.current = onPrimaryClick

  React.useEffect(() => {
    const canvas = canvasRef.current
    if (!canvas || !isNear || items.length === 0) return
    const engine = new SqueezeCanvasEngine({
      canvas,
      items,
      initialIndex: activeIndexRef.current,
      onColumnClick: steps => goToNextRef.current(steps),
      onPrimaryClick: event => onPrimaryClickRef.current(event),
      prefersReducedMotion,
      borderRadius,
      crossOrigin,
    })
    engineRef.current = engine
    return () => {
      engine.dispose()
      if (engineRef.current === engine) engineRef.current = null
    }
  }, [items, isNear, prefersReducedMotion, borderRadius, crossOrigin, engineRef, activeIndexRef])

  return (
    <canvas
      ref={composeRefs(canvasRef, ref)}
      data-slot="squeeze-carousel-canvas"
      aria-hidden="true"
      className={cn(
        "hidden w-full sm:block",
        imageHeight === undefined ? "aspect-[1232/460]" : "h-[var(--squeeze-carousel-image-height)]",
        className,
      )}
      {...props}
    />
  )
}

/* -------------------------------------------------------------------------------------------------
 * Details (desktop copy under the canvas)
 * -----------------------------------------------------------------------------------------------*/

export interface SqueezeCarouselDetailsProps extends Omit<React.ComponentProps<"div">, "children"> {
  /** Either static children or a render function called once per item. */
  children?: React.ReactNode | SqueezeCarouselRenderItem
}

function SqueezeCarouselDetails({ className, children, ...props }: SqueezeCarouselDetailsProps) {
  const { items } = useSqueezeCarousel()
  return (
    <div data-slot="squeeze-carousel-details" className={cn("hidden min-w-0 sm:flex", className)} {...props}>
      {typeof children === "function"
        ? items.map((item, index) => <React.Fragment key={item.id}>{children(item, index)}</React.Fragment>)
        : children}
    </div>
  )
}

export interface SqueezeCarouselDetailProps extends React.ComponentProps<"div"> {
  /** Index of the item this detail belongs to. */
  index: number
}

function SqueezeCarouselDetail({ index, className, style, ...props }: SqueezeCarouselDetailProps) {
  const { items, activeIndex, count } = useSqueezeCarousel()
  const item = items[index]
  const active = index === activeIndex
  const value = React.useMemo<SqueezeCarouselItemContextValue>(
    () => ({ item, index, surface: "details" }),
    [item, index],
  )
  if (!item) return null
  return (
    <SqueezeCarouselItemContext.Provider value={value}>
      <div
        role="group"
        aria-roledescription="slide"
        aria-label={`${index + 1} of ${count}`}
        aria-hidden={!active}
        data-slot="squeeze-carousel-detail"
        data-state={active ? "active" : "inactive"}
        data-index={index}
        className={cn(
          "grid w-full shrink-0 content-start items-start justify-between gap-8 transition-opacity duration-[120ms] ease-linear motion-reduce:transition-none lg:grid-cols-[1fr_auto]",
          "data-[state=inactive]:pointer-events-none data-[state=inactive]:opacity-0",
          className,
        )}
        style={{ transform: `translateX(${-100 * index}%)`, ...style }}
        {...props}
      />
    </SqueezeCarouselItemContext.Provider>
  )
}

/* -------------------------------------------------------------------------------------------------
 * Item copy (shared by details and mobile cards)
 * -----------------------------------------------------------------------------------------------*/

const fadeWithScrollStyle: React.CSSProperties = { opacity: "calc(1 - var(--squeeze-item-distance, 0))" }

export type SqueezeCarouselDetailCopyProps = React.ComponentProps<"div">

function SqueezeCarouselDetailCopy({ className, style, ...props }: SqueezeCarouselDetailCopyProps) {
  const { surface } = useSqueezeCarouselItem()
  const { prefersReducedMotion } = useSqueezeCarousel()
  const mobile = surface === "mobile"
  return (
    <div
      data-slot="squeeze-carousel-detail-copy"
      className={cn(!mobile && "pr-28 lg:max-w-[calc(460px*16/9)] lg:pr-0", className)}
      style={mobile && !prefersReducedMotion ? { ...fadeWithScrollStyle, ...style } : style}
      {...props}
    />
  )
}

const headingSmClassName =
  "inline text-[1.125rem] font-light leading-[1.25] tracking-[-0.01em] sm:text-[1.25rem] sm:leading-[1.12] lg:text-[1.375rem] lg:leading-[1.1]"

export interface SqueezeCarouselDetailTitleProps extends React.ComponentProps<"h3"> {
  asChild?: boolean
}

function SqueezeCarouselDetailTitle({ asChild, className, ...props }: SqueezeCarouselDetailTitleProps) {
  const Comp = asChild ? Slot : "h3"
  return (
    <Comp
      data-slot="squeeze-carousel-detail-title"
      className={cn(headingSmClassName, "text-foreground after:content-['_']", className)}
      {...props}
    />
  )
}

export interface SqueezeCarouselDetailDescriptionProps extends React.ComponentProps<"p"> {
  asChild?: boolean
}

function SqueezeCarouselDetailDescription({ asChild, className, ...props }: SqueezeCarouselDetailDescriptionProps) {
  const Comp = asChild ? Slot : "p"
  return (
    <Comp
      data-slot="squeeze-carousel-detail-description"
      className={cn(headingSmClassName, "text-muted-foreground", className)}
      {...props}
    />
  )
}

export type SqueezeCarouselDetailActionProps = React.ComponentProps<typeof Button>

function SqueezeCarouselDetailAction({
  className,
  style,
  onFocus,
  onKeyDown,
  ref,
  ...props
}: SqueezeCarouselDetailActionProps) {
  const { index, surface } = useSqueezeCarouselItem()
  const { activeIndex, count, goTo, goToNext, goToPrevious, actionRefs, prefersReducedMotion } = useSqueezeCarousel()
  const mobile = surface === "mobile"
  const active = index === activeIndex

  const registerRef = React.useCallback(
    (node: HTMLButtonElement | null) => {
      if (mobile) return
      if (node) actionRefs.current.set(index, node)
      else actionRefs.current.delete(index)
    },
    [actionRefs, index, mobile],
  )

  return (
    <Button
      ref={composeRefs(registerRef, ref)}
      variant="outline"
      data-slot="squeeze-carousel-detail-action"
      data-state={mobile ? undefined : active ? "active" : "inactive"}
      tabIndex={mobile ? undefined : active ? 0 : -1}
      className={cn(
        "group h-12 gap-2 rounded-md px-5 text-base font-medium",
        mobile && "mt-auto self-start",
        className,
      )}
      style={mobile && !prefersReducedMotion ? { ...fadeWithScrollStyle, ...style } : style}
      onFocus={event => {
        onFocus?.(event)
        if (!mobile && !event.defaultPrevented && !active) goTo(index)
      }}
      onKeyDown={event => {
        onKeyDown?.(event)
        if (mobile || event.defaultPrevented) return
        switch (event.key) {
          case "ArrowLeft":
            event.preventDefault()
            goToPrevious(1, { focus: true })
            break
          case "ArrowRight":
            event.preventDefault()
            goToNext(1, { focus: true })
            break
          case "Home":
            event.preventDefault()
            goTo(0, { focus: true })
            break
          case "End":
            event.preventDefault()
            goTo(count - 1, { focus: true })
            break
        }
      }}
      {...props}
    />
  )
}

export type SqueezeCarouselActionIconProps = React.ComponentProps<"svg">

/** Arrow whose shaft grows in when the parent `.group` is hovered. */
function SqueezeCarouselActionIcon({ className, ...props }: SqueezeCarouselActionIconProps) {
  const clipId = React.useId()
  return (
    <svg
      data-slot="squeeze-carousel-action-icon"
      width="5"
      height="8"
      viewBox="0 0.5 5 8"
      fill="none"
      aria-hidden="true"
      className={cn("inline size-auto shrink-0 overflow-visible", className)}
      {...props}
    >
      <defs>
        <clipPath id={clipId}>
          <rect x="0" y="0" width="12" height="9" />
        </clipPath>
      </defs>
      <g clipPath={`url(#${clipId})`}>
        <g className="transition-transform duration-300 ease-[cubic-bezier(.25,1,.5,1)] group-hover:translate-x-1.5 motion-reduce:transition-none">
          <rect
            className="opacity-0 transition-opacity duration-300 ease-[cubic-bezier(.25,1,.5,1)] group-hover:opacity-100 motion-reduce:transition-none"
            x="-10"
            y="3.375"
            width="13"
            height="1.75"
            fill="currentColor"
          />
          <path
            d="M4.84766 3.63379L5.45898 4.25L4.84766 4.86621L1.24219 8.49902L0 7.2666L2.99316 4.24902L0 1.23242L1.24219 0L4.84766 3.63379Z"
            fill="currentColor"
          />
        </g>
      </g>
    </svg>
  )
}

/* -------------------------------------------------------------------------------------------------
 * Mobile list (scroll-snap cards below the sm breakpoint)
 * -----------------------------------------------------------------------------------------------*/

export interface SqueezeCarouselMobileListProps extends Omit<React.ComponentProps<"ul">, "children"> {
  /** Either static children or a render function called once per item. */
  children?: React.ReactNode | SqueezeCarouselRenderItem
}

function SqueezeCarouselMobileList({ className, children, onScroll, ref, ...props }: SqueezeCarouselMobileListProps) {
  const { items } = useSqueezeCarousel()
  const listRef = React.useRef<HTMLUListElement | null>(null)
  const frame = React.useRef(0)

  const updateProgress = React.useCallback(() => {
    const list = listRef.current
    if (!list) return
    const first = list.firstElementChild as HTMLElement | null
    const gap = parseFloat(getComputedStyle(list).columnGap) || 0
    const step = first ? first.offsetWidth + gap : list.clientWidth
    list.style.setProperty("--squeeze-scroll-progress", step > 0 ? String(list.scrollLeft / step) : "0")
  }, [])

  React.useEffect(() => {
    updateProgress()
    const list = listRef.current
    if (!list || typeof ResizeObserver === "undefined") return
    const observer = new ResizeObserver(updateProgress)
    observer.observe(list)
    return () => {
      observer.disconnect()
      cancelAnimationFrame(frame.current)
    }
  }, [updateProgress])

  return (
    <ul
      ref={composeRefs(listRef, ref)}
      role="list"
      data-slot="squeeze-carousel-mobile-list"
      className={cn(
        "flex snap-x snap-mandatory gap-4 overflow-x-auto overscroll-x-contain [scrollbar-width:none] [&::-webkit-scrollbar]:hidden sm:hidden",
        className,
      )}
      onScroll={event => {
        onScroll?.(event)
        cancelAnimationFrame(frame.current)
        frame.current = requestAnimationFrame(updateProgress)
      }}
      {...props}
    >
      {typeof children === "function"
        ? items.map((item, index) => <React.Fragment key={item.id}>{children(item, index)}</React.Fragment>)
        : children}
    </ul>
  )
}

export interface SqueezeCarouselMobileItemProps extends React.ComponentProps<"li"> {
  /** Index of the item this card belongs to. */
  index: number
}

function SqueezeCarouselMobileItem({ index, className, style, ...props }: SqueezeCarouselMobileItemProps) {
  const { items } = useSqueezeCarousel()
  const item = items[index]
  const value = React.useMemo<SqueezeCarouselItemContextValue>(
    () => ({ item, index, surface: "mobile" }),
    [item, index],
  )
  if (!item) return null
  return (
    <SqueezeCarouselItemContext.Provider value={value}>
      <li
        data-slot="squeeze-carousel-mobile-item"
        data-index={index}
        className={cn("flex shrink-0 basis-full snap-start flex-col gap-6", className)}
        style={
          {
            "--squeeze-item-index": String(index),
            "--squeeze-item-progress":
              "clamp(-1, calc(var(--squeeze-item-index) - var(--squeeze-scroll-progress, 0)), 1)",
            "--squeeze-item-distance": "max(var(--squeeze-item-progress), calc(-1 * var(--squeeze-item-progress)))",
            ...style,
          } as React.CSSProperties
        }
        {...props}
      />
    </SqueezeCarouselItemContext.Provider>
  )
}

export type SqueezeCarouselMobileMediaProps = React.ComponentProps<"div">

/** Image area of a mobile card. Renders the item's `mobileSrc` (or `src`) unless you pass children. */
function SqueezeCarouselMobileMedia({ className, style, children, ...props }: SqueezeCarouselMobileMediaProps) {
  const { item } = useSqueezeCarouselItem()
  const { prefersReducedMotion, imageHeight } = useSqueezeCarousel()
  return (
    <div
      data-slot="squeeze-carousel-mobile-media"
      className={cn(
        "pointer-events-none relative origin-center overflow-hidden rounded-[var(--squeeze-carousel-radius)] bg-muted",
        imageHeight === undefined ? "aspect-[336/350]" : "h-[var(--squeeze-carousel-image-height)]",
        className,
      )}
      style={
        {
          "--squeeze-card-scale": "calc(1 - var(--squeeze-item-distance, 0) * 0.05)",
          "--squeeze-gap-offset":
            "calc(((1 - var(--squeeze-card-scale)) * 50% + 7px / var(--squeeze-card-scale)) * var(--squeeze-item-progress, 0) * -1)",
          transform: "translate3d(var(--squeeze-gap-offset), 0, 0) scale(var(--squeeze-card-scale))",
          ...style,
        } as React.CSSProperties
      }
      {...props}
    >
      {children ?? (
        // eslint-disable-next-line @next/next/no-img-element
        <img
          src={item.mobileSrc ?? item.src}
          alt={item.alt ?? item.title}
          loading="lazy"
          draggable={false}
          data-slot="squeeze-carousel-mobile-image"
          className="absolute top-0 left-1/2 h-full w-full max-w-none object-cover select-none"
          style={{
            transform: prefersReducedMotion
              ? "translate3d(-50%, 0, 0)"
              : "translate3d(calc(-50% + (-30px * var(--squeeze-item-progress, 0))), 0, 0)",
          }}
        />
      )}
    </div>
  )
}

/* -------------------------------------------------------------------------------------------------
 * Exports
 * -----------------------------------------------------------------------------------------------*/

export {
  SqueezeCarousel,
  SqueezeCarouselHeader,
  SqueezeCarouselHeading,
  SqueezeCarouselTitle,
  SqueezeCarouselDescription,
  SqueezeCarouselControls,
  SqueezeCarouselPrevious,
  SqueezeCarouselNext,
  SqueezeCarouselCanvas,
  SqueezeCarouselDetails,
  SqueezeCarouselDetail,
  SqueezeCarouselDetailCopy,
  SqueezeCarouselDetailTitle,
  SqueezeCarouselDetailDescription,
  SqueezeCarouselDetailAction,
  SqueezeCarouselActionIcon,
  SqueezeCarouselMobileList,
  SqueezeCarouselMobileItem,
  SqueezeCarouselMobileMedia,
}
```


## Components

### Breakpoint Display

A breakpoint display component.

- Docs: https://www.abui.io/components/breakpoint-display
- Registry item: https://www.abui.io/r/breakpoint-display.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/breakpoint-display`

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/utils/breakpoint-display.tsx

```tsx
"use client"

import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

const breakpointDisplayVariants = cva(
  "pointer-events-none select-none bg-foreground text-background px-2 py-1 z-50 rounded-b",
  {
    variants: {
      position: {
        fixed: "fixed top-0 right-[50%] translate-x-1/2",
        relative: "relative",
        absolute: "absolute top-0 right-[50%] translate-x-1/2",
      },
    },
    defaultVariants: {
      position: "fixed",
    },
  },
)

// Canonical ordering of breakpoints from smallest to largest
// This defines the semantic order - actual pixel values are defined in Tailwind config
const BREAKPOINT_ORDER = ["xxs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl"] as const

type BreakpointKey = (typeof BREAKPOINT_ORDER)[number]

// Map breakpoint keys to their display labels
const BREAKPOINT_LABELS: Record<BreakpointKey, string> = {
  xxs: "XXS",
  xs: "XS",
  sm: "SM",
  md: "MD",
  lg: "LG",
  xl: "XL",
  "2xl": "2XL",
  "3xl": "3XL",
}

// Default Tailwind breakpoints (standard v3/v4)
const DEFAULT_BREAKPOINTS: BreakpointKey[] = ["sm", "md", "lg", "xl", "2xl"]

interface BreakpointDisplayProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof breakpointDisplayVariants> {
  /**
   * Additional breakpoints to include beyond the default Tailwind breakpoints.
   * These will be automatically sorted by semantic order (xxs < xs < sm < md < lg < xl < 2xl < 3xl).
   * Actual pixel values are defined in your Tailwind configuration.
   * @example extraBreakpoints={["xxs", "xs", "3xl"]}
   */
  extraBreakpoints?: BreakpointKey[]
}

function BreakpointDisplay({ className, position, extraBreakpoints = [], ...props }: BreakpointDisplayProps) {
  // Combine default and extra breakpoints, remove duplicates, and sort by semantic order
  const activeBreakpoints = React.useMemo(() => {
    const combined = [...DEFAULT_BREAKPOINTS, ...extraBreakpoints]
    const unique = Array.from(new Set(combined))

    // Sort by their position in the canonical BREAKPOINT_ORDER array
    return unique.sort((a, b) => {
      return BREAKPOINT_ORDER.indexOf(a) - BREAKPOINT_ORDER.indexOf(b)
    })
  }, [extraBreakpoints])

  // Create a Set for O(1) lookup
  const activeSet = React.useMemo(() => new Set(activeBreakpoints), [activeBreakpoints])

  // Determine the first and last active breakpoints
  const firstBreakpoint = activeBreakpoints[0]
  const lastBreakpoint = activeBreakpoints[activeBreakpoints.length - 1]

  // Helper to check if a breakpoint is the next active one after current
  const getNextActiveBreakpoint = (current: BreakpointKey): BreakpointKey | null => {
    const currentIndex = BREAKPOINT_ORDER.indexOf(current)
    for (let i = currentIndex + 1; i < BREAKPOINT_ORDER.length; i++) {
      if (activeSet.has(BREAKPOINT_ORDER[i])) {
        return BREAKPOINT_ORDER[i]
      }
    }
    return null
  }

  return (
    <div className={cn(breakpointDisplayVariants({ position }), className)} {...props}>
      {/* Minimum - shows below the first breakpoint */}
      {firstBreakpoint === "xxs" && <p className="font-semibold block xxs:hidden">Minimum</p>}
      {firstBreakpoint === "xs" && <p className="font-semibold block xs:hidden">Minimum</p>}
      {firstBreakpoint === "sm" && <p className="font-semibold block sm:hidden">Minimum</p>}
      {firstBreakpoint === "md" && <p className="font-semibold block md:hidden">Minimum</p>}
      {firstBreakpoint === "lg" && <p className="font-semibold block lg:hidden">Minimum</p>}
      {firstBreakpoint === "xl" && <p className="font-semibold block xl:hidden">Minimum</p>}
      {firstBreakpoint === "2xl" && <p className="font-semibold block 2xl:hidden">Minimum</p>}
      {firstBreakpoint === "3xl" && <p className="font-semibold block 3xl:hidden">Minimum</p>}

      {/* XXS breakpoint */}
      {activeSet.has("xxs") && getNextActiveBreakpoint("xxs") === "xs" && (
        <p className="font-semibold hidden xxs:block xs:hidden">XXS</p>
      )}
      {activeSet.has("xxs") && getNextActiveBreakpoint("xxs") === "sm" && (
        <p className="font-semibold hidden xxs:block sm:hidden">XXS</p>
      )}
      {activeSet.has("xxs") && getNextActiveBreakpoint("xxs") === "md" && (
        <p className="font-semibold hidden xxs:block md:hidden">XXS</p>
      )}
      {activeSet.has("xxs") && getNextActiveBreakpoint("xxs") === "lg" && (
        <p className="font-semibold hidden xxs:block lg:hidden">XXS</p>
      )}
      {activeSet.has("xxs") && getNextActiveBreakpoint("xxs") === "xl" && (
        <p className="font-semibold hidden xxs:block xl:hidden">XXS</p>
      )}
      {activeSet.has("xxs") && getNextActiveBreakpoint("xxs") === "2xl" && (
        <p className="font-semibold hidden xxs:block 2xl:hidden">XXS</p>
      )}
      {activeSet.has("xxs") && getNextActiveBreakpoint("xxs") === "3xl" && (
        <p className="font-semibold hidden xxs:block 3xl:hidden">XXS</p>
      )}
      {activeSet.has("xxs") && lastBreakpoint === "xxs" && <p className="font-semibold hidden xxs:block">XXS</p>}

      {/* XS breakpoint */}
      {activeSet.has("xs") && getNextActiveBreakpoint("xs") === "sm" && (
        <p className="font-semibold hidden xs:block sm:hidden">XS</p>
      )}
      {activeSet.has("xs") && getNextActiveBreakpoint("xs") === "md" && (
        <p className="font-semibold hidden xs:block md:hidden">XS</p>
      )}
      {activeSet.has("xs") && getNextActiveBreakpoint("xs") === "lg" && (
        <p className="font-semibold hidden xs:block lg:hidden">XS</p>
      )}
      {activeSet.has("xs") && getNextActiveBreakpoint("xs") === "xl" && (
        <p className="font-semibold hidden xs:block xl:hidden">XS</p>
      )}
      {activeSet.has("xs") && getNextActiveBreakpoint("xs") === "2xl" && (
        <p className="font-semibold hidden xs:block 2xl:hidden">XS</p>
      )}
      {activeSet.has("xs") && getNextActiveBreakpoint("xs") === "3xl" && (
        <p className="font-semibold hidden xs:block 3xl:hidden">XS</p>
      )}
      {activeSet.has("xs") && lastBreakpoint === "xs" && <p className="font-semibold hidden xs:block">XS</p>}

      {/* SM breakpoint */}
      {activeSet.has("sm") && getNextActiveBreakpoint("sm") === "md" && (
        <p className="font-semibold hidden sm:block md:hidden">SM</p>
      )}
      {activeSet.has("sm") && getNextActiveBreakpoint("sm") === "lg" && (
        <p className="font-semibold hidden sm:block lg:hidden">SM</p>
      )}
      {activeSet.has("sm") && getNextActiveBreakpoint("sm") === "xl" && (
        <p className="font-semibold hidden sm:block xl:hidden">SM</p>
      )}
      {activeSet.has("sm") && getNextActiveBreakpoint("sm") === "2xl" && (
        <p className="font-semibold hidden sm:block 2xl:hidden">SM</p>
      )}
      {activeSet.has("sm") && getNextActiveBreakpoint("sm") === "3xl" && (
        <p className="font-semibold hidden sm:block 3xl:hidden">SM</p>
      )}
      {activeSet.has("sm") && lastBreakpoint === "sm" && <p className="font-semibold hidden sm:block">SM</p>}

      {/* MD breakpoint */}
      {activeSet.has("md") && getNextActiveBreakpoint("md") === "lg" && (
        <p className="font-semibold hidden md:block lg:hidden">MD</p>
      )}
      {activeSet.has("md") && getNextActiveBreakpoint("md") === "xl" && (
        <p className="font-semibold hidden md:block xl:hidden">MD</p>
      )}
      {activeSet.has("md") && getNextActiveBreakpoint("md") === "2xl" && (
        <p className="font-semibold hidden md:block 2xl:hidden">MD</p>
      )}
      {activeSet.has("md") && getNextActiveBreakpoint("md") === "3xl" && (
        <p className="font-semibold hidden md:block 3xl:hidden">MD</p>
      )}
      {activeSet.has("md") && lastBreakpoint === "md" && <p className="font-semibold hidden md:block">MD</p>}

      {/* LG breakpoint */}
      {activeSet.has("lg") && getNextActiveBreakpoint("lg") === "xl" && (
        <p className="font-semibold hidden lg:block xl:hidden">LG</p>
      )}
      {activeSet.has("lg") && getNextActiveBreakpoint("lg") === "2xl" && (
        <p className="font-semibold hidden lg:block 2xl:hidden">LG</p>
      )}
      {activeSet.has("lg") && getNextActiveBreakpoint("lg") === "3xl" && (
        <p className="font-semibold hidden lg:block 3xl:hidden">LG</p>
      )}
      {activeSet.has("lg") && lastBreakpoint === "lg" && <p className="font-semibold hidden lg:block">LG</p>}

      {/* XL breakpoint */}
      {activeSet.has("xl") && getNextActiveBreakpoint("xl") === "2xl" && (
        <p className="font-semibold hidden xl:block 2xl:hidden">XL</p>
      )}
      {activeSet.has("xl") && getNextActiveBreakpoint("xl") === "3xl" && (
        <p className="font-semibold hidden xl:block 3xl:hidden">XL</p>
      )}
      {activeSet.has("xl") && lastBreakpoint === "xl" && <p className="font-semibold hidden xl:block">XL</p>}

      {/* 2XL breakpoint */}
      {activeSet.has("2xl") && getNextActiveBreakpoint("2xl") === "3xl" && (
        <p className="font-semibold hidden 2xl:block 3xl:hidden">2XL</p>
      )}
      {activeSet.has("2xl") && lastBreakpoint === "2xl" && <p className="font-semibold hidden 2xl:block">2XL</p>}

      {/* 3XL breakpoint */}
      {activeSet.has("3xl") && lastBreakpoint === "3xl" && <p className="font-semibold hidden 3xl:block">3XL</p>}
    </div>
  )
}

export { BreakpointDisplay, breakpointDisplayVariants }
export type { BreakpointDisplayProps, BreakpointKey }
```

### Radio Tabs

A radio tabs component.

- Docs: https://www.abui.io/components/radio-tabs
- Registry item: https://www.abui.io/r/radio-tabs.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/radio-tabs`
- Registry dependencies: button

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/radio-tabs.tsx

```tsx
"use client"

import * as React from "react"
import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

type StackAtBreakpoint = "sm" | "md" | "lg" | "xl" | "2xl"

interface RadioTabsProps extends React.ComponentProps<typeof RadioGroupPrimitive.Root> {
  stackAtBreakpoint?: StackAtBreakpoint
  containerClassName?: string
}

function RadioTabs({ className, stackAtBreakpoint, containerClassName, ...props }: RadioTabsProps) {
  // Detect if any children contain descriptions to adjust container height
  const hasDescriptions = React.Children.toArray(props.children).some(child => {
    if (React.isValidElement(child) && child.props && typeof child.props === "object" && "children" in child.props) {
      const itemChildren = React.Children.toArray(child.props.children as React.ReactNode)
      return itemChildren.some(itemChild => {
        return React.isValidElement(itemChild) && itemChild.type === RadioTabsItemDescription
      })
    }
    return false
  })

  const containerStyles = cn(
    "flex gap-x-[2px] rounded-[6px] p-[2px]",
    !hasDescriptions && "h-[38px]",
    "bg-white dark:bg-zinc-900",
    "border",
    stackAtBreakpoint && getClassNamesForBreakpoint(stackAtBreakpoint),
    containerClassName,
  )

  return (
    <RadioGroupPrimitive.Root data-slot="radio-tabs" className={cn("w-full", className)} {...props}>
      <div className={containerStyles}>{props.children}</div>
    </RadioGroupPrimitive.Root>
  )
}

const radioTabsItemVariants = cva(
  [
    "group flex-1 overflow-hidden cursor-pointer",
    "px-[7px] py-[4px]",
    "select-none outline-none rounded-[4px]",
    "transition-colors",
    "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
    "disabled:cursor-not-allowed disabled:opacity-50",
  ],
  {
    variants: {
      variant: {
        default: [
          "data-[state=checked]:bg-foreground dark:data-[state=checked]:bg-foreground",
          "data-[state=checked]:border data-[state=checked]:border-foreground",
          "hover:bg-muted/50",
        ],
        outline: [
          "border border-muted-foreground/20",
          "data-[state=checked]:border-foreground data-[state=checked]:bg-foreground/5",
          "hover:border-muted-foreground/30",
        ],
        outline_highlight: [
          "data-[state=checked]:bg-blue-500/5 dark:data-[state=checked]:bg-blue-500/10",
          "data-[state=checked]:border data-[state=checked]:border-blue-500",
          "hover:bg-muted/50",
        ],
        primary: [
          "data-[state=checked]:bg-foreground",
          "data-[state=checked]:border data-[state=checked]:border-primary",
          "hover:bg-muted/50",
        ],
        highlight: [
          "data-[state=checked]:bg-blue-500 dark:data-[state=checked]:bg-blue-500",
          "data-[state=checked]:!text-white/100",
          // "data-[state=checked]:border data-[state=checked]:border-blue-500",
          "border-none",
          "hover:bg-muted/50",
        ],
        secondary: [
          "data-[state=checked]:bg-muted",
          "data-[state=checked]:border data-[state=checked]:border-muted-foreground/20",
          "hover:bg-muted/50",
        ],
      },
    },
    defaultVariants: {
      variant: "default",
    },
  },
)

interface RadioTabsItemProps
  extends React.ComponentProps<typeof RadioGroupPrimitive.Item>,
    VariantProps<typeof radioTabsItemVariants> {
  children: React.ReactNode
}

function RadioTabsItem({ className, variant = "default", children, ...props }: RadioTabsItemProps) {
  // Check if children contain only text/simple content or structured components
  const hasStructuredChildren = React.Children.toArray(children).some(child => {
    return React.isValidElement(child) && (child.type === RadioTabsItemLabel || child.type === RadioTabsItemDescription)
  })

  return (
    <RadioGroupPrimitive.Item
      data-slot="radio-tabs-item"
      className={cn(
        radioTabsItemVariants({ variant }),
        hasStructuredChildren
          ? "flex flex-col justify-center items-center text-center"
          : "flex justify-center items-center",
        hasStructuredChildren && "px-10",
        className,
      )}
      {...props}
    >
      {hasStructuredChildren ? (
        children
      ) : (
        <span
          className={cn(
            "font-medium text-sm",
            "overflow-hidden whitespace-nowrap text-ellipsis",
            // "text-muted-foreground",
            variant === "default" && "group-data-[state=checked]:text-background",
            variant === "outline" && "group-data-[state=checked]:text-foreground",
            variant === "primary" && "group-data-[state=checked]:text-primary",
            variant === "secondary" && "group-data-[state=checked]:text-foreground",
          )}
        >
          {children}
        </span>
      )}
    </RadioGroupPrimitive.Item>
  )
}

interface RadioTabsItemLabelProps extends React.HTMLAttributes<HTMLElement> {
  children: React.ReactNode
}

function RadioTabsItemLabel({ className, children, ...props }: RadioTabsItemLabelProps) {
  return (
    <span
      data-slot="radio-tabs-item-label"
      className={cn(
        "font-semibold text-base",
        "overflow-hidden whitespace-nowrap text-ellipsis",
        "w-full",
        "text-muted-foreground",
        "transition-colors duration-300",
        className,
      )}
      {...props}
    >
      {children}
    </span>
  )
}

interface RadioTabsItemDescriptionProps extends React.HTMLAttributes<HTMLElement> {
  children: React.ReactNode
}

function RadioTabsItemDescription({ className, children, ...props }: RadioTabsItemDescriptionProps) {
  return (
    <span
      data-slot="radio-tabs-item-description"
      className={cn(
        "text-sm",
        "text-muted-foreground opacity-50",
        "group-data-[state=checked]:opacity-100",
        "transition-colors duration-300",
        className,
      )}
      {...props}
    >
      {children}
    </span>
  )
}

export { RadioTabs, RadioTabsItem, RadioTabsItemLabel, RadioTabsItemDescription, radioTabsItemVariants }

const getClassNamesForBreakpoint = (breakpoint: StackAtBreakpoint): string => {
  const breakpointClasses: Record<StackAtBreakpoint, string> = {
    sm: "flex-col gap-y-[2px] h-auto sm:flex-row sm:gap-x-[2px]",
    md: "flex-col gap-y-[2px] h-auto md:flex-row md:gap-x-[2px]",
    lg: "flex-col gap-y-[2px] h-auto lg:flex-row lg:gap-x-[2px]",
    xl: "flex-col gap-y-[2px] h-auto xl:flex-row xl:gap-x-[2px]",
    "2xl": "flex-col gap-y-[2px] h-auto 2xl:flex-row 2xl:gap-x-[2px]",
  }
  return breakpointClasses[breakpoint]
}
```

### Radio Rows

A radio rows component.

- Docs: https://www.abui.io/components/radio-rows
- Registry item: https://www.abui.io/r/radio-rows.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/radio-rows`

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/radio-rows.tsx

```tsx
"use client"

import * as React from "react"
import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

interface RadioRowsProps extends React.ComponentProps<typeof RadioGroupPrimitive.Root> {
  containerClassName?: string
}

function RadioRows({ className, containerClassName, ...props }: RadioRowsProps) {
  const containerStyles = cn("flex flex-col gap-y-1", "h-auto items-start", containerClassName)

  return (
    <RadioGroupPrimitive.Root data-slot="radio-rows" className={cn("w-full", className)} {...props}>
      <div className={containerStyles}>{props.children}</div>
    </RadioGroupPrimitive.Root>
  )
}

const radioRowsItemVariants = cva(
  [
    "group w-full",
    "p-3 pr-4 rounded-md relative flex items-center gap-x-3 justify-between",
    "transition-all duration-300 font-medium",
    "cursor-pointer select-none outline-none",
    "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
    "disabled:cursor-not-allowed disabled:opacity-50",
  ],
  {
    variants: {
      variant: {
        default: [
          "border-2 border-muted-foreground/20",
          "bg-muted/5",
          "data-[state=checked]:bg-foreground data-[state=checked]:text-background data-[state=checked]:border-muted-foreground/20",
          "hover:border-muted-foreground/30",
        ],
        outline: [
          "border-2 border-muted-foreground/20",
          "bg-transparent",
          "data-[state=checked]:border-foreground data-[state=checked]:bg-foreground/5 data-[state=checked]:text-foreground",
          "hover:border-muted-foreground/30",
        ],
        primary: [
          "border-2 border-muted-foreground/20",
          "bg-transparent",
          "data-[state=checked]:border-primary data-[state=checked]:bg-primary/5 data-[state=checked]:text-foreground",
          "hover:border-muted-foreground/30",
        ],
        secondary: [
          "border border-muted-foreground/10",
          "bg-muted/5",
          "data-[state=checked]:bg-muted data-[state=checked]:border-muted-foreground/20 data-[state=checked]:text-foreground",
          "hover:bg-muted/10",
        ],
      },
    },
    defaultVariants: {
      variant: "default",
    },
  },
)

interface RadioRowsItemProps
  extends React.ComponentProps<typeof RadioGroupPrimitive.Item>,
    VariantProps<typeof radioRowsItemVariants> {
  children: React.ReactNode
}

function RadioRowsItem({ className, variant = "default", children, ...props }: RadioRowsItemProps) {
  return (
    <RadioGroupPrimitive.Item
      data-slot="radio-rows-item"
      className={cn(radioRowsItemVariants({ variant }), className)}
      {...props}
    >
      {/* Custom Radio Indicator */}
      <div
        className={cn(
          "w-[19px] h-[19px] rounded-xl shrink-0 grow-0",
          "border-[3px]",
          "flex justify-center items-center",
          "transition-all duration-300",
          variant === "default" && ["border-muted-foreground/40", "group-data-[state=checked]:border-background"],
          variant === "outline" && ["border-muted-foreground/30", "group-data-[state=checked]:border-foreground"],
          variant === "primary" && ["border-muted-foreground/30", "group-data-[state=checked]:border-primary"],
          variant === "secondary" && ["border-muted-foreground/30", "group-data-[state=checked]:border-foreground"],
        )}
      >
        <div
          className={cn(
            "w-[9px] h-[9px] rounded-full",
            "transition-all duration-300",
            "opacity-0 scale-0",
            "group-data-[state=checked]:opacity-100 group-data-[state=checked]:scale-100",
            variant === "default" && "group-data-[state=checked]:bg-background",
            variant === "outline" && "bg-foreground",
            variant === "primary" && "bg-primary",
            variant === "secondary" && "bg-foreground",
          )}
        />
      </div>

      {/* Content */}
      <div className="flex flex-col items-start gap-y-1 w-full">{children}</div>
    </RadioGroupPrimitive.Item>
  )
}

interface RadioRowsItemTitleProps extends React.HTMLAttributes<HTMLElement> {
  children: React.ReactNode
}

function RadioRowsItemTitle({ className, children, ...props }: RadioRowsItemTitleProps) {
  return (
    <p
      data-slot="radio-rows-item-title"
      className={cn("font-bold text-base tracking-normal leading-none", "transition-colors duration-300", className)}
      {...props}
    >
      {children}
    </p>
  )
}

interface RadioRowsItemDescriptionProps extends React.HTMLAttributes<HTMLElement> {
  children: React.ReactNode
}

function RadioRowsItemDescription({ className, children, ...props }: RadioRowsItemDescriptionProps) {
  return (
    <p
      data-slot="radio-rows-item-description"
      className={cn(
        "text-sm font-medium leading-none",
        "text-muted-foreground",
        "transition-colors duration-300",
        className,
      )}
      {...props}
    >
      {children}
    </p>
  )
}

export { RadioRows, RadioRowsItem, RadioRowsItemTitle, RadioRowsItemDescription, radioRowsItemVariants }
```

### Color Swatch Selector

A color swatch selector component.

- Docs: https://www.abui.io/components/color-swatch-selector
- Registry item: https://www.abui.io/r/color-swatch-selector.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/color-swatch-selector`

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/color-swatch-selector.tsx

```tsx
"use client"

import * as React from "react"
import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"

import { cn } from "@/lib/utils"

function ColorSwatchSelectorRoot({ className, ...props }: React.ComponentProps<typeof RadioGroupPrimitive.Root>) {
  return (
    <RadioGroupPrimitive.Root
      data-slot="color-swatch-selector-root"
      className={cn(
        "flex items-center justify-between gap-4 py-3 bg-muted dark:bg-muted/60 p-3 pl-5 rounded-full",
        className,
      )}
      {...props}
    />
  )
}

interface ColorSwatchSelectorLabelProps extends React.HTMLAttributes<HTMLDivElement> {
  value: string
}

function ColorSwatchSelectorLabel({ className, value, ...props }: ColorSwatchSelectorLabelProps) {
  return (
    <div
      data-slot="color-swatch-selector-label"
      className={cn("text-base font-normal leading-none", className)}
      {...props}
    >
      {value}
    </div>
  )
}

function ColorSwatchSelectorContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
  return (
    <div data-slot="color-swatch-selector-content" className={cn("flex items-center gap-2", className)} {...props} />
  )
}

interface ColorSwatchSelectorItemProps extends React.ComponentProps<typeof RadioGroupPrimitive.Item> {
  value: string
}

function ColorSwatchSelectorItem({ className, value, ...props }: ColorSwatchSelectorItemProps) {
  return (
    <RadioGroupPrimitive.Item
      data-slot="color-swatch-selector-item"
      value={value}
      className={cn(
        "group relative h-8 w-8 shrink-0 cursor-pointer rounded-full outline-none transition-all",
        "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
        "disabled:cursor-not-allowed disabled:opacity-50",
        className,
      )}
      style={{ backgroundColor: value, boxShadow: `1px 3px 4px 0px rgba(0, 0, 0, 0.25) inset` }}
      {...props}
    >
      {/* Selected indicator - white ring in the center */}
      <div
        className={cn(
          "absolute inset-0 flex items-center justify-center",
          "transition-all duration-200",
          "opacity-0 scale-0",
          "group-data-[state=checked]:opacity-100 group-data-[state=checked]:scale-100",
        )}
      >
        <div className="h-4 w-4 rounded-full border-[3px] bg-background" />
      </div>
    </RadioGroupPrimitive.Item>
  )
}

export const ColorSwatchSelector = {
  Root: ColorSwatchSelectorRoot,
  Label: ColorSwatchSelectorLabel,
  Content: ColorSwatchSelectorContent,
  Item: ColorSwatchSelectorItem,
}
```

### Label Selector

A text label selector component for sizes, variants, and other text-based options.

- Docs: https://www.abui.io/components/label-selector
- Registry item: https://www.abui.io/r/label-selector.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/label-selector`
- npm dependencies: @radix-ui/react-radio-group, class-variance-authority

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/label-selector.tsx

```tsx
"use client"

import * as React from "react"
import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

function LabelSelectorRoot({ className, ...props }: React.ComponentProps<typeof RadioGroupPrimitive.Root>) {
  return (
    <RadioGroupPrimitive.Root
      data-slot="label-selector-root"
      className={cn(
        "flex items-center justify-between gap-4 py-3 bg-muted dark:bg-muted/60 p-3 pl-5 rounded-full",
        className,
      )}
      {...props}
    />
  )
}

interface LabelSelectorLabelProps extends React.HTMLAttributes<HTMLDivElement> {
  value: string
}

function LabelSelectorLabel({ className, value, ...props }: LabelSelectorLabelProps) {
  return (
    <div data-slot="label-selector-label" className={cn("text-base font-normal leading-none", className)} {...props}>
      {value}
    </div>
  )
}

function LabelSelectorContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
  return <div data-slot="label-selector-content" className={cn("flex items-center gap-2", className)} {...props} />
}

const labelSelectorItemVariants = cva(
  "group relative shrink-0 cursor-pointer outline-none transition-all flex items-center justify-center disabled:cursor-not-allowed disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
  {
    variants: {
      variant: {
        default:
          "border-2 border-muted-foreground/20 bg-background hover:border-muted-foreground/40 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
        outline:
          "border-2 border-input bg-background hover:bg-accent hover:text-accent-foreground data-[state=checked]:border-primary data-[state=checked]:bg-accent data-[state=checked]:text-foreground",
        ghost:
          "hover:bg-accent hover:text-accent-foreground data-[state=checked]:bg-accent data-[state=checked]:text-foreground",
        solid:
          "bg-muted text-muted-foreground hover:bg-muted/80 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
      },
      size: {
        sm: "min-w-[2rem] h-8 px-3 text-xs",
        default: "min-w-[2.5rem] h-10 px-4 text-sm",
        lg: "min-w-[3rem] h-12 px-5 text-base",
      },
      rounded: {
        none: "rounded-none",
        sm: "rounded-sm",
        md: "rounded-md",
        lg: "rounded-lg",
        full: "rounded-full",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
      rounded: "lg",
    },
  },
)

interface LabelSelectorItemProps
  extends React.ComponentProps<typeof RadioGroupPrimitive.Item>,
    VariantProps<typeof labelSelectorItemVariants> {
  value: string
  label?: string
}

function LabelSelectorItem({ className, value, label, variant, size, rounded, ...props }: LabelSelectorItemProps) {
  return (
    <RadioGroupPrimitive.Item
      data-slot="label-selector-item"
      value={value}
      className={cn(labelSelectorItemVariants({ variant, size, rounded, className }))}
      {...props}
    >
      <span className="font-medium">{label || value}</span>
    </RadioGroupPrimitive.Item>
  )
}

export const LabelSelector = {
  Root: LabelSelectorRoot,
  Label: LabelSelectorLabel,
  Content: LabelSelectorContent,
  Item: LabelSelectorItem,
}

export { labelSelectorItemVariants }
```

### Spinner

A customizable loading spinner component with size, speed, and color variants.

- Docs: https://www.abui.io/components/spinner
- Registry item: https://www.abui.io/r/spinner.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/spinner`
- npm dependencies: class-variance-authority

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/spinner.tsx

```tsx
import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

const spinnerVariants = cva("animate-spin", {
  variants: {
    size: {
      sm: "size-4",
      default: "size-6",
      lg: "size-8",
      xl: "size-12",
    },
    speed: {
      slow: "[animation-duration:1200ms]",
      default: "[animation-duration:900ms]",
      fast: "[animation-duration:600ms]",
    },
  },
  defaultVariants: {
    size: "default",
    speed: "default",
  },
})

export interface SpinnerProps
  extends Omit<React.ComponentProps<"svg">, "size" | "speed">,
    VariantProps<typeof spinnerVariants> {
  /**
   * Stroke width of the spinner arc
   * @default 3
   */
  strokeWidth?: number
  /**
   * CSS class for the background circle
   * @default "stroke-muted-foreground/20"
   */
  bgClassName?: string
}

const Spinner = React.forwardRef<SVGSVGElement, SpinnerProps>(
  ({ className, size, speed, strokeWidth = 3, bgClassName = "stroke-muted-foreground/20", ...props }, ref) => {
    return (
      <svg
        ref={ref}
        className={cn(spinnerVariants({ size, speed }), "text-foreground", className)}
        viewBox="0 0 42 42"
        {...props}
      >
        <g fill="none" transform="translate(3 3)" strokeWidth={strokeWidth}>
          <circle className={bgClassName} cx="18" cy="18" r="18" />
          <path
            className="stroke-current"
            stroke="currentColor"
            d="M36 18c0-9.94-8.06-18-18-18"
            strokeLinecap="round"
            strokeLinejoin="round"
          />
        </g>
      </svg>
    )
  },
)

Spinner.displayName = "Spinner"

export { Spinner, spinnerVariants }
```

### Scroll Progress

A scroll progress indicator that shows reading progress as a horizontal bar at the top or bottom of the viewport.

- Docs: https://www.abui.io/components/scroll-progress
- Registry item: https://www.abui.io/r/scroll-progress.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/scroll-progress`
- npm dependencies: motion@12

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/scroll-progress.tsx

```tsx
"use client"

import { motion, useScroll } from "motion/react"
import { cn } from "@/lib/utils"

interface ScrollProgressProps extends React.ComponentProps<typeof motion.div> {
  /**
   * Height of the progress bar in pixels
   * @default 2
   */
  height?: number
  /**
   * Color of the progress bar
   * @default "bg-primary"
   */
  color?: string
  /**
   * Position of the progress bar
   * @default "top"
   */
  position?: "top" | "bottom"
  /**
   * Container element to track scroll progress for
   * If not provided, tracks the entire viewport
   */
  container?: React.RefObject<HTMLElement | null>
}

function ScrollProgress({
  height = 4,
  color = "bg-primary",
  position = "top",
  className,
  container,
  ...props
}: ScrollProgressProps) {
  const { scrollYProgress } = useScroll({
    container: container as any,
  })

  return (
    <motion.div
      data-slot="scroll-progress"
      className={cn(
        "left-0 right-0 z-50 origin-left",
        // Use fixed positioning for viewport scroll, allow override for container scroll
        !container && "fixed",
        position === "top" ? "top-0" : "bottom-0",
        color,
        className,
      )}
      style={{
        scaleX: scrollYProgress,
        height: `${height}px`,
      }}
      {...props}
    />
  )
}

export { ScrollProgress }
```

### Text Gradient

A text gradient effect component.

- Docs: https://www.abui.io/components/text-gradient
- Registry item: https://www.abui.io/r/text-gradient.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/text-gradient`

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/effects/text-gradient.tsx

```tsx
import * as React from "react"
import { cn } from "@/lib/utils"

type CSSVariableStyle = React.CSSProperties & {
  "--spread"?: string
}

interface TextGradientProps extends React.HTMLAttributes<HTMLSpanElement> {
  children: React.ReactNode
  /**
   * The spread distance for the gradient effect in pixels
   * @default 22
   */
  spread?: number
  /**
   * The background color for the gradient highlight
   * Can be a CSS variable or any valid CSS color
   * @default "hsl(var(--background))"
   */
  highlightColor?: string
  /**
   * The base text color (shows through the gradient)
   * Can be a CSS variable or any valid CSS color
   * @default "hsl(var(--muted-foreground))"
   */
  baseColor?: string
  /**
   * Animation duration in seconds
   * @default 3
   */
  duration?: number
}

const TextGradient = React.forwardRef<HTMLSpanElement, TextGradientProps>(
  (
    {
      children,
      className,
      spread = 22,
      highlightColor = "var(--background)",
      baseColor = "var(--muted-foreground)",
      duration = 2,
      style,
      ...props
    },
    ref,
  ) => {
    const inlineStyle: CSSVariableStyle = {
      "--spread": `${spread}px`,
      ...style,
      backgroundImage: `linear-gradient(90deg, transparent calc(50% - var(--spread)), ${highlightColor} 50%, transparent calc(50% + var(--spread))), linear-gradient(${baseColor}, ${baseColor})`,
      backgroundSize: "250% 100%, 100% 100%",
      animation: `text-gradient-shift ${duration}s linear infinite`,
    }

    return (
      <span
        ref={ref}
        className={cn(
          "relative inline-block bg-clip-text text-transparent",
          "[background-repeat:no-repeat,padding-box]",
          className,
        )}
        style={inlineStyle}
        {...props}
      >
        <style>
          {`
            @keyframes text-gradient-shift {
              from { background-position: 100% center; }
              to { background-position: 0% center; }
            }
          `}
        </style>
        {children}
      </span>
    )
  },
)

TextGradient.displayName = "TextGradient"

export { TextGradient }
export default TextGradient
```

### Accordion Multiselect

An accordion multiselect component with categories and services.

- Docs: https://www.abui.io/components/accordion-multiselect
- Registry item: https://www.abui.io/r/accordion-multiselect.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/accordion-multiselect`
- npm dependencies: @radix-ui/react-accordion, @radix-ui/react-checkbox, lucide-react

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/accordion-multiselect.tsx

```tsx
"use client"

import * as React from "react"
import * as AccordionPrimitive from "@radix-ui/react-accordion"
import { Check, ChevronDown } from "lucide-react"
import { cn } from "@/lib/utils"
import * as CheckboxPrimitive from "@radix-ui/react-checkbox"

// --- Architecture: Primitives (Unstyled but behaving) ---
// We are using Radix UI Accordion and Checkbox primitives directly.
// This component acts as a "Component" layer in the architecture:
// - Wraps primitives with styling
// - Supports controlled/uncontrolled usage
// - Uses data-attributes for state and slots for targeting

// --- Context ---
// We use a context to share selection state between the root and items/checkboxes
// This allows for the Compound Component pattern.
interface AccordionMultiselectContextValue {
  selectedValues: string[]
  onSelectionChange: (value: string, checked: boolean) => void
}

const AccordionMultiselectContext = React.createContext<AccordionMultiselectContextValue | null>(null)

function useAccordionMultiselect() {
  const context = React.useContext(AccordionMultiselectContext)
  if (!context) {
    throw new Error("AccordionMultiselect subcomponents must be used within AccordionMultiselect")
  }
  return context
}

// --- Components ---

// We can't directly extend AccordionPrimitive.Root because it has specific props that might conflict or be typed in a way TS doesn't like for intersection
// Instead, we'll define our props and intersect with the primitive's props, excluding what we override/don't need if necessary
type AccordionRootProps = React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root>

interface AccordionMultiselectProps
  extends Omit<AccordionRootProps, "type" | "value" | "defaultValue" | "onValueChange"> {
  value?: string[]
  onValueChange?: (value: string[]) => void
  defaultValue?: string[]
}

function AccordionMultiselect({
  value: controlledValue,
  onValueChange,
  defaultValue = [],
  className,
  children,
  ...props
}: AccordionMultiselectProps) {
  // Controlled/Uncontrolled pattern
  const [internalValue, setInternalValue] = React.useState<string[]>(defaultValue)
  const isControlled = controlledValue !== undefined
  const selectedValues = isControlled ? controlledValue : internalValue

  const handleSelectionChange = React.useCallback(
    (value: string, checked: boolean) => {
      let newValues: string[]
      if (checked) {
        newValues = [...selectedValues, value]
      } else {
        newValues = selectedValues.filter(id => id !== value)
      }

      if (!isControlled) {
        setInternalValue(newValues)
      }
      onValueChange?.(newValues)
    },
    [selectedValues, isControlled, onValueChange],
  )

  return (
    <AccordionMultiselectContext.Provider value={{ selectedValues, onSelectionChange: handleSelectionChange }}>
      <AccordionPrimitive.Root
        type="multiple"
        data-slot="accordion-multiselect-root"
        className={cn("w-full space-y-4", className)}
        {...props}
      >
        {children}
      </AccordionPrimitive.Root>
    </AccordionMultiselectContext.Provider>
  )
}

function AccordionMultiselectItem({
  className,
  ...props
}: React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>) {
  return (
    <AccordionPrimitive.Item
      data-slot="accordion-multiselect-item"
      className={cn("border-b-0", className)}
      {...props}
    />
  )
}

function AccordionMultiselectTrigger({
  className,
  children,
  ...props
}: React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>) {
  return (
    <AccordionPrimitive.Header className="flex">
      <AccordionPrimitive.Trigger
        data-slot="accordion-multiselect-trigger"
        className={cn(
          "flex flex-1 items-center justify-between py-2 font-semibold text-base transition-all hover:no-underline [&[data-state=open]>svg]:rotate-180 cursor-pointer",
          className,
        )}
        {...props}
      >
        {children}
        <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200 text-muted-foreground" />
      </AccordionPrimitive.Trigger>
    </AccordionPrimitive.Header>
  )
}

function AccordionMultiselectContent({
  className,
  children,
  ...props
}: React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Content>) {
  return (
    <AccordionPrimitive.Content
      data-slot="accordion-multiselect-content"
      className="overflow-hidden text-sm transition-all data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
      {...props}
    >
      <div className={cn("pt-2 pb-4 flex flex-col gap-2", className)}>{children}</div>
    </AccordionPrimitive.Content>
  )
}

// --- Sub-components for Item Options ---

interface AccordionMultiselectOptionProps extends React.HTMLAttributes<HTMLDivElement> {
  value: string
  showCheckbox?: boolean
  children: React.ReactNode
}

function AccordionMultiselectOption({
  value,
  showCheckbox = false,
  className,
  onClick,
  children,
  ...props
}: AccordionMultiselectOptionProps) {
  const { selectedValues, onSelectionChange } = useAccordionMultiselect()
  const isSelected = selectedValues.includes(value)

  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
    onSelectionChange(value, !isSelected)
    onClick?.(e)
  }

  return (
    <div
      data-slot="accordion-multiselect-option"
      data-state={isSelected ? "checked" : "unchecked"}
      className={cn(
        "flex items-start space-x-3 rounded-md group cursor-pointer transition-all border border-transparent",
        "hover:border-foreground/10 data-[state=checked]:bg-foreground/6",
        className,
      )}
      onClick={handleClick}
      {...props}
    >
      {showCheckbox && (
        <div className="flex items-center h-5 mt-1">
          <CheckboxPrimitive.Root
            id={value}
            checked={isSelected}
            onCheckedChange={checked => onSelectionChange(value, checked as boolean)}
            onClick={e => e.stopPropagation()}
            className={cn(
              "peer h-4 w-4 shrink-0 rounded-[3px] border border-primary ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
            )}
          >
            <CheckboxPrimitive.Indicator className={cn("flex items-center justify-center text-current")}>
              <Check className="h-4 w-4" />
            </CheckboxPrimitive.Indicator>
          </CheckboxPrimitive.Root>
        </div>
      )}
      <div className="flex-1">{children}</div>
    </div>
  )
}

export {
  AccordionMultiselect,
  AccordionMultiselectItem,
  AccordionMultiselectTrigger,
  AccordionMultiselectContent,
  AccordionMultiselectOption,
}
```

### Timeline Steps

A component for displaying chronological events, activities, or steps

- Docs: https://www.abui.io/components/timeline-steps
- Registry item: https://www.abui.io/r/timeline-steps.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/timeline-steps`
- npm dependencies: class-variance-authority

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/timeline-steps.tsx

```tsx
import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

/* -----------------------------------------------------------------------------
 * Timeline (root container)
 * -------------------------------------------------------------------------- */

const timelineStepsVariants = cva("flex", {
  variants: {
    orientation: {
      vertical: "flex-col",
      horizontal: "flex-row overflow-x-auto",
    },
    position: {
      left: "",
      right: "",
      alternate: "",
    },
  },
  defaultVariants: {
    orientation: "vertical",
    position: "left",
  },
})

interface TimelineStepsProps extends React.ComponentProps<"div">, VariantProps<typeof timelineStepsVariants> {}

function TimelineSteps({ className, orientation, position, ...props }: TimelineStepsProps) {
  return (
    <div
      data-slot="timeline-steps"
      data-orientation={orientation}
      data-position={position}
      className={cn(timelineStepsVariants({ orientation, position }), className)}
      {...props}
    />
  )
}

/* -----------------------------------------------------------------------------
 * TimelineItem
 * -------------------------------------------------------------------------- */

const timelineStepsItemVariants = cva("relative flex flex-col", {
  variants: {
    orientation: {
      vertical: "pb-8 last:pb-0",
      horizontal: "flex-1 items-center",
    },
    status: {
      default: "",
      completed: "",
      current: "",
      upcoming: "opacity-60",
    },
  },
  defaultVariants: {
    orientation: "vertical",
    status: "default",
  },
})

interface TimelineStepsItemProps extends React.ComponentProps<"div">, VariantProps<typeof timelineStepsItemVariants> {}

function TimelineStepsItem({ className, orientation, status, ...props }: TimelineStepsItemProps) {
  return (
    <div
      data-slot="timeline-steps-item"
      data-status={status}
      className={cn(timelineStepsItemVariants({ orientation, status }), className)}
      {...props}
    />
  )
}

/* -----------------------------------------------------------------------------
 * TimelineConnector (the line connecting items)
 * -------------------------------------------------------------------------- */

const timelineStepsConnectorVariants = cva("", {
  variants: {
    orientation: {
      vertical:
        "absolute left-[calc(var(--timeline-steps-icon-size,2.5rem)/2)] top-[var(--timeline-steps-icon-size,2.5rem)] h-[calc(100%-var(--timeline-steps-icon-size,2.5rem))] w-px -translate-x-1/2",
      horizontal: "absolute top-3 left-[calc(50%+0.75rem)] h-px w-[calc(100%-1.5rem)]",
    },
    variant: {
      default: "bg-border",
      dashed: "border-l border-dashed border-border bg-transparent",
      dotted: "border-l border-dotted border-border bg-transparent",
    },
    status: {
      default: "",
      completed: "bg-primary",
      current: "bg-gradient-to-b from-primary to-border",
      upcoming: "bg-muted",
    },
  },
  defaultVariants: {
    orientation: "vertical",
    variant: "default",
    status: "default",
  },
})

interface TimelineStepsConnectorProps
  extends React.ComponentProps<"div">,
    VariantProps<typeof timelineStepsConnectorVariants> {}

function TimelineStepsConnector({ className, orientation, variant, status, ...props }: TimelineStepsConnectorProps) {
  return (
    <div
      data-slot="timeline-steps-connector"
      aria-hidden="true"
      className={cn(timelineStepsConnectorVariants({ orientation, variant, status }), className)}
      {...props}
    />
  )
}

/* -----------------------------------------------------------------------------
 * TimelineHeader (contains icon and title row)
 * -------------------------------------------------------------------------- */

function TimelineStepsHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="timeline-steps-header" className={cn("flex items-center gap-3", className)} {...props} />
}

/* -----------------------------------------------------------------------------
 * TimelineStepsIcon (the dot/icon indicator)
 * -------------------------------------------------------------------------- */

const timelineStepsIconVariants = cva(
  "relative z-10 flex shrink-0 items-center justify-center rounded-full border bg-background [--timeline-steps-icon-size:2.5rem]",
  {
    variants: {
      size: {
        sm: "size-6 [--timeline-steps-icon-size:1.5rem] [&>svg]:size-3",
        default: "size-10 [--timeline-steps-icon-size:2.5rem] [&>svg]:size-4",
        lg: "size-12 [--timeline-steps-icon-size:3rem] [&>svg]:size-5",
      },
      variant: {
        default: "border-border text-muted-foreground",
        primary: "border-primary bg-primary text-primary-foreground",
        secondary: "border-secondary bg-secondary text-secondary-foreground",
        destructive: "border-destructive bg-destructive text-destructive-foreground",
        outline: "border-border bg-background text-foreground",
      },
    },
    defaultVariants: {
      size: "default",
      variant: "default",
    },
  },
)

interface TimelineStepsIconProps extends React.ComponentProps<"div">, VariantProps<typeof timelineStepsIconVariants> {}

function TimelineStepsIcon({ className, size, variant, ...props }: TimelineStepsIconProps) {
  return (
    <div
      data-slot="timeline-steps-icon"
      className={cn(timelineStepsIconVariants({ size, variant }), className)}
      {...props}
    />
  )
}

/* -----------------------------------------------------------------------------
 * TimelineStepsContent (container for description, time, etc.)
 * -------------------------------------------------------------------------- */

function TimelineStepsContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="timeline-steps-content"
      className={cn("ms-[3.25rem] flex flex-col gap-1 pt-0.5 pb-2", className)}
      {...props}
    />
  )
}

/* -----------------------------------------------------------------------------
 * TimelineStepsTitle
 * -------------------------------------------------------------------------- */

function TimelineStepsTitle({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="timeline-steps-title"
      className={cn("text-foreground leading-none font-medium tracking-tight", className)}
      {...props}
    />
  )
}

/* -----------------------------------------------------------------------------
 * TimelineDescription
 * -------------------------------------------------------------------------- */

function TimelineStepsDescription({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div data-slot="timeline-steps-description" className={cn("text-muted-foreground text-sm", className)} {...props} />
  )
}

/* -----------------------------------------------------------------------------
 * TimelineStepsTime (timestamp display)
 * -------------------------------------------------------------------------- */

function TimelineStepsTime({ className, ...props }: React.ComponentProps<"time">) {
  return <time data-slot="timeline-steps-time" className={cn("text-muted-foreground text-xs", className)} {...props} />
}

/* -----------------------------------------------------------------------------
 * Exports
 * -------------------------------------------------------------------------- */

export {
  TimelineSteps,
  TimelineStepsItem,
  TimelineStepsConnector,
  TimelineStepsHeader,
  TimelineStepsIcon,
  TimelineStepsContent,
  TimelineStepsTitle,
  TimelineStepsDescription,
  TimelineStepsTime,
  timelineStepsVariants,
  timelineStepsItemVariants,
  timelineStepsConnectorVariants,
  timelineStepsIconVariants,
}
```

### Table of Contents

A table of contents component with active anchor tracking and depth-aware line styling. Features two variants: default (straight line) and clerk (depth-responsive line that follows hierarchy).

- Docs: https://www.abui.io/components/toc
- Registry item: https://www.abui.io/r/toc.json
- Type: registry:component
- Install: `npx shadcn@latest add @abui/toc`

Source: https://github.com/antoniobrandao/abui/blob/master/registry/abui/ui/toc.tsx

```tsx
"use client"

import * as React from "react"
import {
  createContext,
  useContext,
  useRef,
  useState,
  useEffect,
  useMemo,
  useLayoutEffect,
  type ReactNode,
  type RefObject,
  type ComponentProps,
  type HTMLAttributes,
} from "react"
import { cn } from "@/lib/utils"

// ============================================================================
// Types
// ============================================================================

export interface TOCItemType {
  title: ReactNode
  url: string
  depth: number
}

export type TableOfContents = TOCItemType[]

// ============================================================================
// Contexts
// ============================================================================

const ActiveAnchorContext = createContext<string[]>([])
const ScrollContext = createContext<RefObject<HTMLElement | null>>({ current: null })
const TOCContext = createContext<TOCItemType[]>([])

// ============================================================================
// Hooks
// ============================================================================

/**
 * The id of visible anchors
 */
export function useActiveAnchors(): string[] {
  return useContext(ActiveAnchorContext)
}

/**
 * The estimated active heading ID
 */
export function useActiveAnchor(): string | undefined {
  return useContext(ActiveAnchorContext)[0]
}

/**
 * Get TOC items from context
 */
export function useTOCItems(): TOCItemType[] {
  return useContext(TOCContext)
}

// ============================================================================
// Utility Functions
// ============================================================================

function mergeRefs<T>(...refs: (React.Ref<T> | undefined)[]): React.RefCallback<T> {
  return value => {
    refs.forEach(ref => {
      if (typeof ref === "function") {
        ref(value)
      } else if (ref != null) {
        ;(ref as React.MutableRefObject<T | null>).current = value
      }
    })
  }
}

/**
 * Find the active heading of page using IntersectionObserver
 */
function useAnchorObserver(watch: string[], single: boolean): string[] {
  const observerRef = useRef<IntersectionObserver | null>(null)
  const [activeAnchor, setActiveAnchor] = useState<string[]>([])
  const stateRef = useRef<{ visible: Set<string> } | null>(null)

  const onChange = React.useCallback(
    (entries: IntersectionObserverEntry[]) => {
      stateRef.current ??= { visible: new Set() }
      const state = stateRef.current

      for (const entry of entries) {
        if (entry.isIntersecting) {
          state.visible.add(entry.target.id)
        } else {
          state.visible.delete(entry.target.id)
        }
      }

      if (state.visible.size === 0) {
        const viewTop = entries[0]?.rootBounds?.top ?? 0
        let fallback: Element | undefined
        let min = -1

        for (const id of watch) {
          const element = document.getElementById(id)
          if (!element) continue

          const d = Math.abs(viewTop - element.getBoundingClientRect().top)
          if (min === -1 || d < min) {
            fallback = element
            min = d
          }
        }

        setActiveAnchor(fallback ? [fallback.id] : [])
      } else {
        const items = watch.filter(item => state.visible.has(item))
        setActiveAnchor(single ? items.slice(0, 1) : items)
      }
    },
    [watch, single],
  )

  useEffect(() => {
    if (observerRef.current) return
    observerRef.current = new IntersectionObserver(onChange, {
      rootMargin: "0px",
      threshold: 0.98,
    })

    return () => {
      observerRef.current?.disconnect()
      observerRef.current = null
    }
  }, [onChange])

  useEffect(() => {
    const observer = observerRef.current
    if (!observer) return
    const elements = watch.flatMap(heading => document.getElementById(heading) ?? [])

    for (const element of elements) observer.observe(element)
    return () => {
      for (const element of elements) observer.unobserve(element)
    }
  }, [watch])

  return activeAnchor
}

// ============================================================================
// TOCProvider - Main context provider
// ============================================================================

export interface TOCProviderProps {
  toc: TableOfContents
  /**
   * Only accept one active item at most
   * @defaultValue false
   */
  single?: boolean
  children?: ReactNode
}

export function TOCProvider({ toc, single = false, children }: TOCProviderProps) {
  const headings = useMemo(() => {
    return toc.map(item => item.url.split("#")[1])
  }, [toc])

  const activeAnchors = useAnchorObserver(headings, single)

  return (
    <TOCContext.Provider value={toc}>
      <ActiveAnchorContext.Provider value={activeAnchors}>{children}</ActiveAnchorContext.Provider>
    </TOCContext.Provider>
  )
}

// ============================================================================
// TOCScrollArea - Scrollable container with auto-scroll support
// ============================================================================

export function TOCScrollArea({ ref, className, ...props }: ComponentProps<"div">) {
  const viewRef = useRef<HTMLDivElement>(null)

  return (
    <div
      ref={mergeRefs(viewRef, ref)}
      className={cn(
        "relative min-h-0 text-sm ms-px overflow-auto [scrollbar-width:none] [mask-image:linear-gradient(to_bottom,transparent,white_16px,white_calc(100%-16px),transparent)] py-3",
        className,
      )}
      {...props}
    >
      <ScrollContext.Provider value={viewRef}>{props.children}</ScrollContext.Provider>
    </div>
  )
}

// ============================================================================
// TOCThumb - Active indicator that shows current position
// ============================================================================

type TocThumbValues = [top: number, height: number]

interface TocThumbProps extends HTMLAttributes<HTMLDivElement> {
  containerRef: RefObject<HTMLElement | null>
}

function calcThumb(container: HTMLElement, active: string[]): TocThumbValues {
  if (active.length === 0 || container.clientHeight === 0) {
    return [0, 0]
  }

  let upper = Number.MAX_VALUE
  let lower = 0

  for (const item of active) {
    const element = container.querySelector<HTMLElement>(`a[href="#${item}"]`)
    if (!element) continue

    const styles = getComputedStyle(element)
    upper = Math.min(upper, element.offsetTop + parseFloat(styles.paddingTop))
    lower = Math.max(lower, element.offsetTop + element.clientHeight - parseFloat(styles.paddingBottom))
  }

  return [upper, lower - upper]
}

function updateThumb(element: HTMLElement, info: TocThumbValues): void {
  element.style.setProperty("--toc-top", `${info[0]}px`)
  element.style.setProperty("--toc-height", `${info[1]}px`)
}

function TocThumb({ containerRef, ...props }: TocThumbProps) {
  const thumbRef = useRef<HTMLDivElement>(null)
  const active = useActiveAnchors()

  useEffect(() => {
    if (!containerRef.current) return
    const container = containerRef.current

    const onUpdate = () => {
      if (!thumbRef.current) return
      updateThumb(thumbRef.current, calcThumb(container, active))
    }

    const observer = new ResizeObserver(onUpdate)
    observer.observe(container)
    onUpdate()

    return () => {
      observer.disconnect()
    }
  }, [containerRef, active])

  // Initial update
  if (containerRef.current && thumbRef.current) {
    updateThumb(thumbRef.current, calcThumb(containerRef.current, active))
  }

  return <div ref={thumbRef} role="none" {...props} />
}

// ============================================================================
// TOCItem - Individual TOC link item
// ============================================================================

export interface TOCItemProps extends Omit<ComponentProps<"a">, "href"> {
  href: string
  onActiveChange?: (v: boolean) => void
}

export function TOCItem({ ref, onActiveChange, ...props }: TOCItemProps) {
  const containerRef = useContext(ScrollContext)
  const anchorRef = useRef<HTMLAnchorElement>(null)
  const activeAnchors = useActiveAnchors()
  const activeOrder = activeAnchors.indexOf(props.href.slice(1))
  const isActive = activeOrder !== -1
  const shouldScroll = activeOrder === 0

  useLayoutEffect(() => {
    const anchor = anchorRef.current
    const container = containerRef.current

    // -------------------------------------------------------------------------
    // CUSTOM SCROLL IMPLEMENTATION
    // -------------------------------------------------------------------------
    // This replaces the `scroll-into-view-if-needed` library used in fumadocs.
    //
    // LIBRARY ARCHITECTURE:
    // - `scroll-into-view-if-needed`: Options parsing, scroll execution, scroll-margin support
    // - `compute-scroll-into-view`: Core algorithm for boundary/position calculations
    //
    // The `compute-scroll-into-view` library provides sophisticated features:
    // - `alignNearest`: Algorithm that calculates minimum scroll needed (with edge cases)
    // - Scrollbar width/height handling in calculations
    // - Border width accounting for containers
    // - CSS transform scale handling
    // - Visual viewport support (for pinch-zoom)
    // - Multiple scrolling frames (scrolls all ancestors up to boundary)
    //
    // FEATURES WE DON'T IMPLEMENT (not needed for TOC use case):
    // - Shadow DOM support via isInDocument() check
    // - Custom scroll behavior callbacks (behavior: Function)
    // - Multiple scroll targets (only need single container)
    // - CSS scroll-margin-* properties (TOC items don't use these)
    // - `block: 'nearest'` alignNearest algorithm (we always center)
    // - Scrollbar width compensation (TOC uses scrollbar-width: none)
    // - Border width compensation (TOC container has no borders)
    // - CSS transform scale handling (TOC isn't scaled)
    //
    // FEATURES WE DO IMPLEMENT:
    // - Element connectivity check (isConnected)
    // - Boundary constraint (only scroll container, never page)
    // - Smooth scrolling behavior
    // - Center block alignment (block: 'center')
    // - "if-needed" scroll mode (only scroll if out of view)
    //
    // ORIGINAL FUMADOCS IMPLEMENTATION:
    // ```
    // import scrollIntoView from 'scroll-into-view-if-needed'
    //
    // scrollIntoView(anchor, {
    //   behavior: 'smooth',
    //   block: 'center',
    //   inline: 'center',
    //   scrollMode: 'always',
    //   boundary: container,
    // })
    // ```
    //
    // TO SWITCH TO THE LIBRARY:
    // 1. Install: `yarn add scroll-into-view-if-needed`
    // 2. Import: `import scrollIntoView from 'scroll-into-view-if-needed'`
    // 3. Replace the custom code below with the library call above
    //
    // Reference source code available at:
    // - reference/scroll-into-view-if-needed/
    // - reference/compute-scroll-into-view/
    // -------------------------------------------------------------------------

    // Safety check: ensure elements are connected to the DOM
    if (!container || !anchor || !shouldScroll || !anchor.isConnected) {
      return
    }

    const containerRect = container.getBoundingClientRect()
    const anchorRect = anchor.getBoundingClientRect()

    // "if-needed" check: only scroll if anchor is outside the visible area
    const isAbove = anchorRect.top < containerRect.top
    const isBelow = anchorRect.bottom > containerRect.bottom

    if (isAbove || isBelow) {
      // Calculate scroll position to center the anchor in the container
      // This mimics `block: 'center'` from the library
      const anchorCenter = anchor.offsetTop - container.offsetTop + anchor.offsetHeight / 2
      const containerCenter = container.clientHeight / 2
      const scrollTop = anchorCenter - containerCenter

      // Scroll only the container (boundary constraint), not the page
      container.scrollTo({
        top: Math.max(0, scrollTop),
        behavior: "smooth",
      })
    }
  }, [containerRef, shouldScroll])

  useEffect(() => {
    onActiveChange?.(isActive)
  }, [isActive, onActiveChange])

  return (
    <a ref={mergeRefs(anchorRef, ref)} data-active={isActive} {...props}>
      {props.children}
    </a>
  )
}

// ============================================================================
// TOCItems - Simple TOC list with straight border line
// ============================================================================

export interface TOCItemsProps extends ComponentProps<"div"> {
  /**
   * Text to display when there are no headings
   * @defaultValue "No Headings"
   */
  emptyText?: string
}

export function TOCItems({ ref, className, emptyText = "No Headings", ...props }: TOCItemsProps) {
  const containerRef = useRef<HTMLDivElement>(null)
  const items = useTOCItems()

  if (items.length === 0) {
    return <div className="rounded-lg border bg-card p-3 text-xs text-muted-foreground">{emptyText}</div>
  }

  return (
    <>
      <TocThumb
        containerRef={containerRef}
        className="absolute top-[var(--toc-top)] h-[var(--toc-height)] w-px bg-primary transition-all"
      />
      <div
        ref={mergeRefs(ref, containerRef)}
        className={cn("flex flex-col border-s border-foreground/10", className)}
        {...props}
      >
        {items.map(item => (
          <SimpleTOCItem key={item.url} item={item} />
        ))}
      </div>
    </>
  )
}

function SimpleTOCItem({ item }: { item: TOCItemType }) {
  return (
    <TOCItem
      href={item.url}
      className={cn(
        "prose py-1.5 text-sm text-muted-foreground transition-colors [overflow-wrap:anywhere] first:pt-0 last:pb-0 data-[active=true]:text-primary hover:text-accent-foreground",
        item.depth <= 2 && "ps-3",
        item.depth === 3 && "ps-6",
        item.depth >= 4 && "ps-8",
      )}
    >
      {item.title}
    </TOCItem>
  )
}

// ============================================================================
// ClerkTOCItems - TOC with depth-aware line that follows the hierarchy
// ============================================================================

function getItemOffset(depth: number): number {
  if (depth <= 2) return 14
  if (depth === 3) return 26
  return 36
}

function getLineOffset(depth: number): number {
  return depth >= 3 ? 10 : 0
}

export interface ClerkTOCItemsProps extends ComponentProps<"div"> {
  /**
   * Text to display when there are no headings
   * @defaultValue "No Headings"
   */
  emptyText?: string
}

export function ClerkTOCItems({ ref, className, emptyText = "No Headings", ...props }: ClerkTOCItemsProps) {
  const containerRef = useRef<HTMLDivElement>(null)
  const items = useTOCItems()

  const [svg, setSvg] = useState<{
    path: string
    width: number
    height: number
  }>()

  useEffect(() => {
    if (!containerRef.current) return
    const container = containerRef.current

    function onResize(): void {
      if (container.clientHeight === 0) return
      let w = 0
      let h = 0
      const d: string[] = []

      for (let i = 0; i < items.length; i++) {
        const element: HTMLElement | null = container.querySelector(`a[href="#${items[i].url.slice(1)}"]`)
        if (!element) continue

        const styles = getComputedStyle(element)
        const offset = getLineOffset(items[i].depth) + 1
        const top = element.offsetTop + parseFloat(styles.paddingTop)
        const bottom = element.offsetTop + element.clientHeight - parseFloat(styles.paddingBottom)

        w = Math.max(offset, w)
        h = Math.max(h, bottom)

        d.push(`${i === 0 ? "M" : "L"}${offset} ${top}`)
        d.push(`L${offset} ${bottom}`)
      }

      setSvg({
        path: d.join(" "),
        width: w + 1,
        height: h,
      })
    }

    const observer = new ResizeObserver(onResize)
    onResize()

    observer.observe(container)
    return () => {
      observer.disconnect()
    }
  }, [items])

  if (items.length === 0) {
    return <div className="rounded-lg border bg-card p-3 text-xs text-muted-foreground">{emptyText}</div>
  }

  return (
    <>
      {svg ? (
        <div
          className="absolute start-0 top-0 rtl:-scale-x-100"
          style={{
            width: svg.width,
            height: svg.height,
            maskImage: `url("data:image/svg+xml,${encodeURIComponent(
              `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${svg.width} ${svg.height}"><path d="${svg.path}" stroke="black" stroke-width="1" fill="none" /></svg>`,
            )}")`,
          }}
        >
          <TocThumb
            containerRef={containerRef}
            className="mt-[var(--toc-top)] h-[var(--toc-height)] bg-primary transition-all"
          />
        </div>
      ) : null}
      <div ref={mergeRefs(containerRef, ref)} className={cn("flex flex-col", className)} {...props}>
        {items.map((item, i) => (
          <ClerkTOCItemElement key={item.url} item={item} upper={items[i - 1]?.depth} lower={items[i + 1]?.depth} />
        ))}
      </div>
    </>
  )
}

function ClerkTOCItemElement({
  item,
  upper = item.depth,
  lower = item.depth,
}: {
  item: TOCItemType
  upper?: number
  lower?: number
}) {
  const offset = getLineOffset(item.depth)
  const upperOffset = getLineOffset(upper)
  const lowerOffset = getLineOffset(lower)

  return (
    <TOCItem
      href={item.url}
      style={{
        paddingInlineStart: getItemOffset(item.depth),
      }}
      className="prose relative py-1.5 text-sm text-muted-foreground hover:text-accent-foreground transition-colors [overflow-wrap:anywhere] first:pt-0 last:pb-0 data-[active=true]:text-primary"
    >
      {offset !== upperOffset ? (
        <svg
          xmlns="http://www.w3.org/2000/svg"
          viewBox="0 0 16 16"
          className="absolute -top-1.5 start-0 size-4 rtl:-scale-x-100"
        >
          <line x1={upperOffset} y1="0" x2={offset} y2="12" className="stroke-foreground/10" strokeWidth="1" />
        </svg>
      ) : null}
      <div
        className={cn(
          "absolute inset-y-0 w-px bg-foreground/10",
          offset !== upperOffset && "top-1.5",
          offset !== lowerOffset && "bottom-1.5",
        )}
        style={{
          insetInlineStart: offset,
        }}
      />
      {item.title}
    </TOCItem>
  )
}

// ============================================================================
// PageTOC & PageTOCItems - Convenience wrappers for page layout
// ============================================================================

export interface PageTOCProps extends ComponentProps<"div"> {
  children?: ReactNode
}

export function PageTOC({ className, children, ...props }: PageTOCProps) {
  return (
    <div className={cn("flex flex-col gap-3", className)} {...props}>
      {children}
    </div>
  )
}

export interface PageTOCItemsProps extends ComponentProps<"div"> {
  /**
   * TOC variant style
   * - "default": Simple straight border line
   * - "clerk": Depth-aware line that follows hierarchy
   * @defaultValue "default"
   */
  variant?: "default" | "clerk"
  /**
   * Text to display when there are no headings
   * @defaultValue "No Headings"
   */
  emptyText?: string
}

export function PageTOCItems({ variant = "default", emptyText, ...props }: PageTOCItemsProps) {
  return (
    <TOCScrollArea>
      {variant === "clerk" ? (
        <ClerkTOCItems emptyText={emptyText} {...props} />
      ) : (
        <TOCItems emptyText={emptyText} {...props} />
      )}
    </TOCScrollArea>
  )
}
```


## Utilities

### Orientation Media Queries

A set of device orientation media queries.

- Docs: https://www.abui.io/utils/orientation-media-queries
- Registry item: https://www.abui.io/r/orientation-media-queries.json
- Type: registry:style
- Install: `npx shadcn@latest add @abui/orientation-media-queries`

CSS added to your global stylesheet:

```json
{
  "@custom-variant portrait (@media (orientation: portrait))": {},
  "@custom-variant landscape (@media (orientation: landscape))": {}
}
```

### Text Utils

A set of text utility classes.

- Docs: https://www.abui.io/utils/text-utils
- Registry item: https://www.abui.io/r/text-utils.json
- Type: registry:style
- Install: `npx shadcn@latest add @abui/text-utils`

CSS added to your global stylesheet:

```json
{
  "@utility remove-text-box": {
    "text-box": "trim-both cap alphabetic"
  }
}
```

### Extra Breakpoints

Adds XS, XXS and 3XL breakpoints.

- Docs: https://www.abui.io/utils/extra-breakpoints
- Registry item: https://www.abui.io/r/extra-breakpoints.json
- Type: registry:style
- Install: `npx shadcn@latest add @abui/extra-breakpoints`

CSS variables added to your theme:

```json
{
  "theme": {
    "--breakpoint-xxs": "20rem",
    "--breakpoint-xs": "30rem",
    "--breakpoint-3xl": "116rem"
  }
}
```

### Debug Utils

A set of debug utility classes.

- Docs: https://www.abui.io/utils/debug-utils
- Registry item: https://www.abui.io/r/debug-utils.json
- Type: registry:style
- Install: `npx shadcn@latest add @abui/debug-utils`

CSS added to your global stylesheet:

```json
{
  "@utility debug-red": {
    "border": "1px dashed red"
  },
  "@utility debug-blue": {
    "border": "1px dashed blue"
  },
  "@utility debug-green": {
    "border": "1px dashed green"
  },
  "@utility debug-yellow": {
    "border": "1px dashed yellow"
  },
  "@utility debug-purple": {
    "border": "1px dashed purple"
  },
  "@utility debug-orange": {
    "border": "1px dashed orange"
  },
  "@utility debug-pink": {
    "border": "1px dashed pink"
  }
}
```