boltdocs 1.10.2 → 1.11.0

package/src/client/components/primitives/button.tsx

@@ -0,0 +1,145 @@
+import * as RAC from 'react-aria-components'
+import { cn } from '@client/utils/cn'
+import { cva } from 'class-variance-authority'
+import type { VariantProps } from 'class-variance-authority'
+
+export const buttonVariants = cva(
+  'flex flex-row items-center justify-center w-auto font-semibold tracking-tight no-underline whitespace-nowrap select-none outline-none transition-all duration-200 cursor-pointer pressed:scale-[0.97] hover:-translate-y-px leading-none',
+  {
+    variants: {
+      variant: {
+        primary:
+          'bg-primary-500 text-white shadow-md hover:brightness-110 hover:shadow-lg',
+        secondary:
+          'bg-bg-surface text-text-main border border-border-subtle hover:bg-bg-muted hover:border-border-strong',
+        outline:
+          'bg-transparent text-text-main border border-border-strong hover:bg-bg-surface hover:border-primary-500',
+        ghost:
+          'bg-transparent text-text-muted hover:bg-bg-surface hover:text-text-main',
+        danger:
+          'bg-[var(--color-danger-500)]/10 text-[var(--color-danger-500)] border border-[var(--color-danger-500)]/20 hover:bg-[var(--color-danger-500)]/15',
+        success:
+          'bg-[var(--color-success-500)]/10 text-[var(--color-success-500)] border border-[var(--color-success-500)]/20 hover:bg-[var(--color-success-500)]/15',
+        warning:
+          'bg-[var(--color-warning-500)]/10 text-[var(--color-warning-500)] border border-[var(--color-warning-500)]/20 hover:bg-[var(--color-warning-500)]/15',
+        info: 'bg-[var(--color-info-500)]/10 text-[var(--color-info-500)] border border-[var(--color-info-500)]/20 hover:bg-[var(--color-info-500)]/15',
+        subtle: 'bg-primary-500/10 text-primary-500 hover:bg-primary-500/20',
+        link: 'bg-transparent text-primary-500 !p-0 !min-h-0 hover:underline',
+      },
+      size: {
+        sm: 'min-h-8 px-3.5 text-[0.8125rem] gap-1.5',
+        md: 'min-h-10 px-5 text-[0.9375rem] gap-2',
+        lg: 'min-h-12 px-7 text-[1.05rem] gap-2.5',
+      },
+      rounded: {
+        none: 'rounded-none',
+        sm: 'rounded-sm',
+        md: 'rounded-md',
+        lg: 'rounded-lg',
+        full: 'rounded-full',
+      },
+      iconSize: {
+        sm: 'w-8 h-8 p-0',
+        md: 'w-10 h-10 p-0',
+        lg: 'w-12 h-12 p-0',
+      },
+      disabled: {
+        true: 'opacity-50 cursor-not-allowed pointer-events-none',
+        false: null,
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+      rounded: 'md',
+    },
+  },
+)
+type ButtonVariantType = VariantProps<typeof buttonVariants>
+
+export interface ButtonProps
+  extends Omit<RAC.ButtonProps, 'children' | 'className'>,
+    ButtonVariantType {
+  icon?: React.ReactNode
+  iconPosition?: 'left' | 'right'
+  href?: string
+  children?: React.ReactNode
+  className?: string
+  isIconOnly?: boolean
+}
+
+export const Button = ({
+  href,
+  icon,
+  iconPosition = 'left',
+  isIconOnly,
+  children,
+  className,
+  variant,
+  size,
+  rounded,
+  iconSize,
+  disabled,
+  ...props
+}: ButtonProps) => {
+  const isOnlyIcon = isIconOnly || (!children && !!icon)
+
+  const content = isOnlyIcon ? (
+    <span className="inline-flex items-center justify-center [&>svg]:w-[1.2rem] [&>svg]:h-[1.2rem]">
+      {icon}
+    </span>
+  ) : (
+    <>
+      {icon && iconPosition === 'left' && (
+        <span className="inline-flex items-center shrink-0 [&>svg]:w-[1.1rem] [&>svg]:h-[1.1rem]">
+          {icon}
+        </span>
+      )}
+      <span className="flex items-center">{children}</span>
+      {icon && iconPosition === 'right' && (
+        <span className="inline-flex items-center shrink-0 [&>svg]:w-[1.1rem] [&>svg]:h-[1.1rem]">
+          {icon}
+        </span>
+      )}
+    </>
+  )
+
+  if (href) {
+    return (
+      <RAC.Link
+        href={href}
+        className={cn(
+          buttonVariants({
+            variant,
+            size,
+            rounded,
+            iconSize: isOnlyIcon ? iconSize : undefined,
+            disabled,
+          }),
+          className,
+        )}
+        {...(props as RAC.LinkProps)}
+      >
+        {content}
+      </RAC.Link>
+    )
+  }
+
+  return (
+    <RAC.Button
+      className={cn(
+        buttonVariants({
+          variant,
+          size,
+          rounded,
+          iconSize: isOnlyIcon ? iconSize : undefined,
+          disabled,
+        }),
+        className,
+      )}
+      {...(props as RAC.ButtonProps)}
+    >
+      {content}
+    </RAC.Button>
+  )
+}

package/src/client/components/primitives/helpers/observer.ts

@@ -0,0 +1,120 @@
+import type { TOCItemInfo, TOCItemType } from '../on-this-page'
+
+export function getItemId(url: string) {
+  if (url.startsWith('#')) return url.slice(1)
+  return null
+}
+
+export class Observer {
+  items: TOCItemInfo[] = []
+  single = false
+  private observer: IntersectionObserver | null = null
+  onChange?: () => void
+
+  private callback(entries: IntersectionObserverEntry[]) {
+    if (entries.length === 0) return
+
+    let hasActive = false
+    this.items = this.items.map((item) => {
+      const entry = entries.find((entry) => entry.target.id === item.id)
+      let active = entry ? entry.isIntersecting : item.active && !item.fallback
+      if (this.single && hasActive) active = false
+
+      if (item.active !== active) {
+        item = {
+          ...item,
+          t: Date.now(),
+          active,
+          fallback: false,
+        }
+      }
+
+      if (active) hasActive = true
+      return item
+    })
+
+    if (!hasActive && entries[0].rootBounds) {
+      const viewTop = entries[0].rootBounds.top
+      let min = Number.MAX_VALUE
+      let fallbackIdx = -1
+
+      for (let i = 0; i < this.items.length; i++) {
+        const element = document.getElementById(this.items[i].id)
+        if (!element) continue
+
+        const d = Math.abs(viewTop - element.getBoundingClientRect().top)
+        if (d < min) {
+          fallbackIdx = i
+          min = d
+        }
+      }
+
+      if (fallbackIdx !== -1) {
+        this.items[fallbackIdx] = {
+          ...this.items[fallbackIdx],
+          active: true,
+          fallback: true,
+          t: Date.now(),
+        }
+      }
+    }
+
+    this.onChange?.()
+  }
+
+  setItems(newItems: TOCItemType[]) {
+    const observer = this.observer
+    if (observer) {
+      for (const item of this.items) {
+        const element = document.getElementById(item.id)
+        if (!element) continue
+        observer.unobserve(element)
+      }
+    }
+
+    this.items = []
+    for (const item of newItems) {
+      const id = getItemId(item.url)
+      if (!id) continue
+
+      this.items.push({
+        id,
+        active: false,
+        fallback: false,
+        t: 0,
+        original: item,
+      })
+    }
+    this.watchItems()
+
+    // In an SPA, the TOC might update before the MDX content is in the DOM.
+    // We perform a few delayed scans to ensure we catch those elements.
+    if (typeof window !== 'undefined') {
+      setTimeout(() => this.watchItems(), 100)
+      setTimeout(() => this.watchItems(), 500)
+      setTimeout(() => this.watchItems(), 1000)
+    }
+
+    this.onChange?.()
+  }
+
+  watch(options?: IntersectionObserverInit) {
+    if (this.observer) return
+    this.observer = new IntersectionObserver(this.callback.bind(this), options)
+    this.watchItems()
+  }
+
+  private watchItems() {
+    if (!this.observer) return
+    for (const item of this.items) {
+      const element = document.getElementById(item.id)
+      if (!element) continue
+      this.observer.observe(element)
+    }
+  }
+
+  unwatch() {
+    this.observer?.disconnect()
+    this.observer = null
+  }
+}

package/src/client/components/primitives/index.ts

@@ -0,0 +1,17 @@
+export * from './navbar'
+export * from './navigation-menu'
+export * from './search-dialog'
+export * from './on-this-page'
+export * from './page-nav'
+export * from './tabs'
+export * from './sidebar'
+export * from './breadcrumbs'
+export * from './button'
+export * from './button-group'
+export * from './menu'
+export * from './popover'
+export * from './tooltip'
+export * from './link'
+export { Separator, ToggleButton } from 'react-aria-components'
+
+export { cn } from '../../utils/cn'

package/src/client/components/primitives/link.tsx

@@ -0,0 +1,122 @@
+import React from 'react'
+import {
+  Link as RACLink,
+  type LinkProps as RACLinkProps,
+} from 'react-aria-components'
+import { useLocation } from 'react-router-dom'
+import { useLocalizedTo } from '@hooks/use-localized-to'
+import { usePreload } from '@client/app/preload'
+import { cn } from '@client/utils/cn'
+
+export interface LinkProps extends RACLinkProps {
+  /** Should prefetch the page on hover? Default 'hover' */
+  prefetch?: 'hover' | 'none'
+}
+
+/**
+ * A primitive Link component that wraps React Aria Components' Link
+ * and adds framework-specific logic for path localization and preloading.
+ *
+ * It uses the global navigation configuration from BoltdocsRouterProvider
+ * to handle seamless client-side transitions.
+ */
+export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
+  (props, ref) => {
+    const { href, prefetch = 'hover', onMouseEnter, onFocus, ...rest } = props
+
+    const localizedHref = useLocalizedTo(href ?? '')
+    const { preload } = usePreload()
+
+    const handleMouseEnter = (e: React.MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(e)
+      if (
+        prefetch === 'hover' &&
+        typeof localizedHref === 'string' &&
+        localizedHref.startsWith('/')
+      ) {
+        preload(localizedHref)
+      }
+    }
+
+    const handleFocus = (e: React.FocusEvent) => {
+      onFocus?.(e as any)
+      if (
+        prefetch === 'hover' &&
+        typeof localizedHref === 'string' &&
+        localizedHref.startsWith('/')
+      ) {
+        preload(localizedHref)
+      }
+    }
+
+    return (
+      <RACLink
+        {...rest}
+        ref={ref}
+        href={localizedHref as string}
+        onMouseEnter={handleMouseEnter}
+        onFocus={handleFocus as any}
+      />
+    )
+  },
+)
+Link.displayName = 'Link'
+
+/**
+ * Props for the NavLink component, extending standard Link props.
+ */
+export interface NavLinkProps
+  extends Omit<LinkProps, 'className' | 'children'> {
+  /**
+   * When true, the active state will only be applied if the paths match exactly.
+   * Default is false.
+   */
+  end?: boolean
+  /**
+   * Provides access to the active state for conditional children rendering.
+   */
+  children?:
+    | React.ReactNode
+    | ((props: { isActive: boolean }) => React.ReactNode)
+  /**
+   * Provides access to the active state for conditional styling.
+   */
+  className?: string | ((props: { isActive: boolean }) => string)
+}
+
+/**
+ * A primitive NavLink component that provides active state detection.
+ *
+ * It combines the Link primitive with path matching logic to determine
+ * if the link is currently active based on the browser's location.
+ */
+export const NavLink = React.forwardRef<HTMLAnchorElement, NavLinkProps>(
+  (props, ref) => {
+    const { href, end = false, className, children, ...rest } = props
+    const location = useLocation()
+    const localizedHref = useLocalizedTo(href ?? '')
+
+    const isActive = end
+      ? location.pathname === localizedHref
+      : location.pathname.startsWith(localizedHref as string)
+
+    const resolvedClassName =
+      typeof className === 'function'
+        ? className({ isActive })
+        : cn(className, isActive && 'active')
+    const resolvedChildren =
+      typeof children === 'function' ? children({ isActive }) : children
+
+    return (
+      <Link
+        {...rest}
+        ref={ref}
+        href={href}
+        className={resolvedClassName as any}
+      >
+        {resolvedChildren as any}
+      </Link>
+    )
+  },
+)
+NavLink.displayName = 'NavLink'

package/src/client/components/primitives/menu.tsx

@@ -0,0 +1,159 @@
+'use client'
+
+import { Check, ChevronRight, Dot } from 'lucide-react'
+import React from 'react'
+import * as RAC from 'react-aria-components'
+import { Popover, type PopoverProps } from './popover'
+import { cn } from '@client/utils/cn'
+
+/**
+ * MenuTrigger wraps a trigger (usually a Button) and a Menu.
+ */
+export interface MenuTriggerProps extends RAC.MenuTriggerProps {
+  placement?: PopoverProps['placement']
+}
+
+export function MenuTrigger(props: MenuTriggerProps) {
+  const [trigger, menu] = (
+    React.Children.toArray(props.children) as React.ReactElement[]
+  ).slice(0, 2)
+  return (
+    <RAC.MenuTrigger {...props}>
+      {trigger as any}
+      <Popover placement={props.placement} className="min-w-[200px]">
+        {menu as any}
+      </Popover>
+    </RAC.MenuTrigger>
+  )
+}
+
+/**
+ * SubmenuTrigger for nested menus.
+ */
+export function SubmenuTrigger(props: RAC.SubmenuTriggerProps) {
+  const [trigger, menu] = (
+    React.Children.toArray(props.children) as React.ReactElement[]
+  ).slice(0, 2)
+  return (
+    <RAC.SubmenuTrigger {...props}>
+      {trigger as any}
+      <Popover offset={-4} crossOffset={-4}>
+        {menu as any}
+      </Popover>
+    </RAC.SubmenuTrigger>
+  )
+}
+
+/**
+ * The Menu container.
+ */
+export function Menu<T extends object>(props: RAC.MenuProps<T>) {
+  return (
+    <RAC.Menu
+      {...props}
+      className={RAC.composeRenderProps(props.className, (className) =>
+        cn('p-1.5 outline-none max-h-[inherit] overflow-auto', className),
+      )}
+    />
+  )
+}
+
+/**
+ * MenuItem with support for selection states and submenus.
+ */
+export function MenuItem(props: RAC.MenuItemProps) {
+  const textValue =
+    props.textValue ||
+    (typeof props.children === 'string' ? props.children : undefined)
+
+  return (
+    <RAC.MenuItem
+      {...props}
+      textValue={textValue}
+      className={RAC.composeRenderProps(
+        props.className,
+        (className, { isFocused, isPressed, isDisabled }) =>
+          cn(
+            'group relative flex flex-row items-center gap-2.5 px-3 py-1.5 rounded-lg outline-none cursor-default transition-all duration-200',
+            'text-text-main text-[0.8125rem]',
+            isFocused && 'bg-primary-500/10 text-primary-600 shadow-sm',
+            isPressed && 'scale-[0.98] bg-primary-500/15',
+            isDisabled && 'opacity-40 grayscale pointer-events-none',
+            className,
+          ),
+      )}
+    >
+      {RAC.composeRenderProps(
+        props.children,
+        (children, { selectionMode, isSelected, hasSubmenu }) => (
+          <>
+            {selectionMode !== 'none' && (
+              <span className="flex items-center w-4 h-4 shrink-0 justify-center">
+                {isSelected && selectionMode === 'multiple' && (
+                  <Check className="w-3.5 h-3.5 stroke-[2.5px] text-primary-500 animate-in zoom-in-50 duration-200" />
+                )}
+                {isSelected && selectionMode === 'single' && (
+                  <Dot className="w-6 h-6 text-primary-500 animate-in zoom-in-50 duration-200" />
+                )}
+              </span>
+            )}
+            <div className="flex-1 flex flex-row items-center gap-2.5 truncate font-medium">
+              {children}
+            </div>
+            {hasSubmenu && (
+              <ChevronRight className="w-4 h-4 ml-auto text-text-muted group-focused:text-primary-500/70 transition-colors" />
+            )}
+          </>
+        ),
+      )}
+    </RAC.MenuItem>
+  )
+}
+
+/**
+ * MenuSection for grouping items with an optional header.
+ */
+export interface MenuSectionProps<T> extends RAC.MenuSectionProps<T> {
+  title?: string
+}
+
+export function MenuSection<T extends object>({
+  title,
+  ...props
+}: MenuSectionProps<T>) {
+  return (
+    <RAC.MenuSection
+      {...props}
+      className={cn('flex flex-col gap-0.5', props.className)}
+    >
+      {title && (
+        <RAC.Header className="px-3 py-2 text-[10px] font-bold uppercase tracking-[0.075em] text-text-muted/50 select-none">
+          {title}
+        </RAC.Header>
+      )}
+      <RAC.Collection items={props.items}>{props.children}</RAC.Collection>
+    </RAC.MenuSection>
+  )
+}
+
+/**
+ * MenuSeparator for visual division.
+ */
+export function MenuSeparator(props: RAC.SeparatorProps) {
+  return (
+    <RAC.Separator
+      {...props}
+      className="mx-2 my-1.5 border-t border-border-subtle/50"
+    />
+  )
+}
+
+// Default export for convenience
+export default {
+  Root: Menu,
+  Item: MenuItem,
+  Trigger: MenuTrigger,
+  SubTrigger: SubmenuTrigger,
+  Section: MenuSection,
+  Separator: MenuSeparator,
+}