boltdocs 2.6.2 → 2.7.0

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

@@ -1,54 +1,52 @@
-import { Link } from './link'
+import {
+  type ReactNode,
+  useRef,
+  useLayoutEffect,
+  useEffect,
+  useState,
+} from 'react'
 import * as RAC from 'react-aria-components'
-import { ChevronRight } from 'lucide-react'
 import { cn } from '../../utils/cn'
+import { useUI } from '../../app/ui-context'
+import { Link } from './link'
+import { ChevronRight } from 'lucide-react'
 import type { ComponentBase } from './types'
 import type { ComponentRoute } from '../../types'
+import { useSidebar } from '../../hooks/use-sidebar'
+import { useLocalizedTo } from '../../hooks/use-localized-to'
+import * as LucideIcons from 'lucide-react'
+import virtualIcons from 'virtual:boltdocs-icons'
 
-export interface SidebarGroupProps extends ComponentBase {
-  title?: string
-  icon?: React.ElementType
-}
+// Persistent scroll position across navigation (SPA)
+let sidebarScrollPos = 0
 
-export interface SidebarSubGroupProps extends SidebarLinkProps {
-  isOpen?: boolean
-  onToggle?: () => void
-  children?: React.ReactNode
-}
-
-export interface SidebarLinkProps extends ComponentBase {
-  label: string
-  href: string
-  active?: boolean
-  icon?: React.ElementType
-  badge?: ComponentRoute['badge']
+function getIcon(iconName?: string): React.ElementType | undefined {
+  if (!iconName) return undefined
+  const icons = { ...LucideIcons, ...virtualIcons } as unknown as Record<
+    string,
+    React.ElementType
+  >
+  const IconComponent = icons[iconName] || icons[iconName + 'Icon']
+  return IconComponent || undefined
 }
 
+/**
+ * Internal Badge component for links
+ */
 const Badge = ({ badge }: { badge: ComponentRoute['badge'] }) => {
   const colors = {
-    new: 'bg-primary-500/20 text-primary-500',
-    updated: 'bg-gray-500/20 text-gray-500',
-    deprecated: 'bg-red-500/20 text-red-500',
-  }
-
-  // Expire Badge
-  if (typeof badge === 'object' && badge?.expires) {
-    const expireDate = new Date(badge.expires)
-    const today = new Date()
-    const diffTime = expireDate.getTime() - today.getTime()
-    const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24))
-
-    if (diffDays === 0) {
-      return null
-    }
+    new: 'bg-primary-500/10 text-primary-500 border border-primary-500/20',
+    updated: 'bg-emerald-500/10 text-emerald-500 border border-emerald-500/20',
+    deprecated: 'bg-danger-500/10 text-danger-500 border border-danger-500/20',
   }
 
   const text = typeof badge === 'string' ? badge : badge?.text
+  if (!text) return null
 
   return (
     <span
       className={cn(
-        'ml-auto flex h-4.5 items-center rounded-full text-[9px] font-medium px-1.5 py-0.5 text-center whitespace-nowrap',
+        'ml-auto flex h-5 items-center rounded-md text-[10px] font-bold px-1.5 py-0.5 uppercase tracking-wider',
         colors[text as keyof typeof colors] || colors.new,
       )}
     >
@@ -57,53 +55,140 @@ const Badge = ({ badge }: { badge: ComponentRoute['badge'] }) => {
   )
 }
 
-export const Sidebar = ({ children, className }: ComponentBase) => {
+/**
+ * Desktop Sidebar Container
+ */
+export function SidebarRoot({ children, className }: ComponentBase) {
   return (
     <aside
       className={cn(
-        'boltdocs-sidebar sticky top-navbar hidden lg:flex flex-col shrink-0',
-        'w-sidebar h-full',
-        'overflow-y-auto border-r border-border-subtle bg-bg-main',
-        'py-6 px-4',
+        'hidden lg:flex flex-col w-sidebar sticky top-navbar h-[calc(100vh-var(--spacing-navbar))] border-r border-subtle bg-main',
         className,
       )}
     >
-      <nav className="flex-1 space-y-6">{children}</nav>
+      {children}
     </aside>
   )
 }
 
-const SidebarGroup = ({
-  children,
+/**
+ * Mobile Sidebar Modal
+ */
+export function SidebarMobile({ children, className }: ComponentBase) {
+  const { isSidebarOpen, closeSidebar } = useUI()
+
+  return (
+    <RAC.ModalOverlay
+      isOpen={isSidebarOpen}
+      onOpenChange={(open) => !open && closeSidebar()}
+      isDismissable={true}
+      className={cn(
+        'fixed inset-0 z-50 bg-black/20 backdrop-blur-sm lg:hidden',
+        'entering:animate-in entering:fade-in exiting:animate-out exiting:fade-out duration-300',
+      )}
+    >
+      <RAC.Modal
+        className={cn(
+          'fixed top-0 left-0 bottom-0 w-80 bg-main border-r border-subtle shadow-2xl outline-none',
+          'entering:animate-in entering:slide-in-from-left exiting:animate-out exiting:slide-out-to-left duration-300',
+          className,
+        )}
+      >
+        <RAC.Dialog className="h-full focus:outline-none outline-none flex flex-col">
+          {children}
+        </RAC.Dialog>
+      </RAC.Modal>
+    </RAC.ModalOverlay>
+  )
+}
+
+/**
+ * Shared Header for Sidebar
+ */
+export function SidebarHeader({ children, className }: ComponentBase) {
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-between p-4 border-b border-subtle',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Scrollable Content Wrapper
+ */
+export function SidebarContent({ children, className }: ComponentBase) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  // Restore scroll position
+  useLayoutEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollTop = sidebarScrollPos
+    }
+  }, [])
+
+  // Save scroll position
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    const handleScroll = () => {
+      sidebarScrollPos = el.scrollTop
+    }
+    el.addEventListener('scroll', handleScroll, { passive: true })
+    return () => el.removeEventListener('scroll', handleScroll)
+  }, [])
+
+  return (
+    <div
+      ref={scrollRef}
+      className={cn(
+        'flex-1 overflow-y-auto p-4 pb-16 custom-scrollbar',
+        className,
+      )}
+    >
+      <nav className="flex flex-col gap-6">{children}</nav>
+    </div>
+  )
+}
+
+/**
+ * Navigation Group
+ */
+export const SidebarGroup = ({
   title,
   icon: Icon,
+  children,
   className,
-}: SidebarGroupProps) => {
+}: { title?: string; icon?: React.ElementType } & ComponentBase) => {
   return (
-    <div className={cn('space-y-1', className)}>
+    <div className={className}>
       {title && (
-        <div
-          className={cn(
-            'flex w-full items-center justify-between px-2 py-1.5 text-sm font-semibold',
-            'text-text-main',
-          )}
-        >
-          <div className="flex items-center gap-2">
-            {Icon && <Icon size={14} />}
-            {title}
-          </div>
-        </div>
+        <h4 className="px-2 mb-2 flex items-center gap-2 text-[11px] font-bold uppercase tracking-widest text-muted/50">
+          {Icon && <Icon size={12} />}
+          {title}
+        </h4>
       )}
-      {children && <div className="space-y-0.5">{children}</div>}
+      <div className="flex flex-col gap-0.5">{children}</div>
     </div>
   )
 }
 
-const SidebarGroupItem = ({ children, className }: ComponentBase) => {
-  return <div className={cn(className)}>{children}</div>
+/**
+ * Sidebar Link
+ */
+export interface SidebarLinkProps extends ComponentBase {
+  label: string
+  href: string
+  active?: boolean
+  icon?: React.ElementType
+  badge?: ComponentRoute['badge']
 }
 
-const SidebarLink = ({
+export const SidebarLink = ({
   label,
   href,
   active,
@@ -115,13 +200,10 @@ const SidebarLink = ({
     <Link
       href={href}
       className={cn(
-        'group flex items-center gap-2.5 rounded-lg px-2.5 py-2 text-sm outline-none',
-        'transition-all duration-200 ease-in-out',
-        'focus-visible:ring-2 focus-visible:ring-primary-500/30',
-        {
-          'bg-primary-500/10 text-primary-500 font-medium': active,
-          'text-text-muted hover:bg-bg-muted hover:text-text-main': !active,
-        },
+        'group flex items-center gap-2.5 rounded-lg px-2.5 py-1.5 text-sm transition-all outline-none',
+        active
+          ? 'bg-primary-500/10 text-primary-500 font-medium shadow-sm'
+          : 'text-muted hover:bg-surface hover:text-body',
         className,
       )}
     >
@@ -129,9 +211,7 @@ const SidebarLink = ({
         <Icon
           size={16}
           className={cn(
-            active
-              ? 'text-primary-500'
-              : 'text-text-muted group-hover:text-text-main',
+            active ? 'text-primary-500' : 'text-muted group-hover:text-body',
           )}
         />
       )}
@@ -141,62 +221,54 @@ const SidebarLink = ({
   )
 }
 
-const SidebarSubGroup = ({
+/**
+ * Nested SubGroup
+ */
+export const SidebarSubGroup = ({
   label,
   href,
   active,
   icon: Icon,
   badge,
-  className,
-  isOpen = false,
+  isOpen,
   onToggle,
   children,
-}: SidebarSubGroupProps) => {
+  className,
+}: SidebarLinkProps & {
+  isOpen: boolean
+  onToggle: () => void
+  children: ReactNode
+}) => {
   return (
-    <div className="space-y-0.5">
-      <div className="flex items-center w-full">
-        <Link
+    <div className="flex flex-col gap-0.5">
+      <div className="group relative flex items-center">
+        <SidebarLink
+          label={label}
           href={href}
-          className={cn(
-            'group flex flex-1 items-center gap-2.5 rounded-lg px-2.5 py-2 text-sm outline-none',
-            'transition-all duration-200 ease-in-out',
-            'focus-visible:ring-2 focus-visible:ring-primary-500/30',
-            active
-              ? 'bg-primary-500/10 text-primary-500 font-medium'
-              : 'text-text-muted hover:bg-bg-surface hover:text-text-main hover:translate-x-1',
-            className,
-          )}
+          active={active}
+          icon={Icon}
+          badge={badge}
+          className={cn('flex-1 pr-8', className)}
+        />
+        <button
+          onClick={(e) => {
+            e.preventDefault()
+            e.stopPropagation()
+            onToggle()
+          }}
+          className="absolute right-1 p-1.5 text-muted hover:text-body transition-colors outline-none cursor-pointer"
         >
-          {Icon && (
-            <Icon
-              size={16}
-              className={cn(
-                active
-                  ? 'text-primary-500'
-                  : 'text-text-muted group-hover:text-text-main',
-              )}
-            />
-          )}
-          <span className="truncate">{label}</span>
-          {badge && <Badge badge={badge} />}
-        </Link>
-        {children && (
-          <RAC.Button
-            onPress={onToggle}
-            className="flex items-center justify-center p-1.5 ml-1 rounded-md text-text-muted hover:bg-bg-surface hover:text-text-main transition-colors outline-none focus-visible:ring-2 focus-visible:ring-primary-500/30 cursor-pointer"
-          >
-            <ChevronRight
-              size={16}
-              className={cn(
-                'transition-transform duration-200',
-                isOpen && 'rotate-90',
-              )}
-            />
-          </RAC.Button>
-        )}
+          <ChevronRight
+            size={14}
+            className={cn(
+              'transition-transform duration-200',
+              isOpen && 'rotate-90',
+            )}
+          />
+        </button>
       </div>
-      {isOpen && children && (
-        <div className="pl-4 ml-[7px] border-l border-border-subtle/50 space-y-0.5 mt-0.5">
+      {isOpen && (
+        <div className="ml-4 pl-3 border-l border-subtle/50 mt-0.5 flex flex-col gap-0.5">
           {children}
         </div>
       )}
@@ -204,8 +276,129 @@ const SidebarSubGroup = ({
   )
 }
 
-Sidebar.Root = Sidebar
-Sidebar.Group = SidebarGroup
-Sidebar.SubGroup = SidebarSubGroup
-Sidebar.GroupItem = SidebarGroupItem
-Sidebar.Link = SidebarLink
+/**
+ * Automated single-route rendering primitive
+ */
+export interface SidebarItemProps extends ComponentBase {
+  route: ComponentRoute
+  activePath: string
+}
+
+export function SidebarItem({
+  route,
+  activePath,
+  className,
+}: SidebarItemProps) {
+  const localizedHref = useLocalizedTo(route.path)
+  const isCurrent =
+    activePath ===
+    (localizedHref.endsWith('/') ? localizedHref.slice(0, -1) : localizedHref)
+  const hasChildren = !!route.routes?.length || !!route.subRoutes?.length
+  const children = route.routes || route.subRoutes
+
+  const [isOpen, setIsOpen] = useState(() =>
+    activePath.startsWith(localizedHref),
+  )
+  const [prevActivePath, setPrevActivePath] = useState(activePath)
+
+  if (activePath !== prevActivePath) {
+    setPrevActivePath(activePath)
+    if (activePath.startsWith(localizedHref)) {
+      setIsOpen(true)
+    }
+  }
+
+  if (hasChildren) {
+    return (
+      <SidebarSubGroup
+        label={route.title}
+        href={route.path}
+        active={isCurrent}
+        icon={getIcon(route.icon)}
+        badge={route.badge}
+        isOpen={isOpen}
+        onToggle={() => setIsOpen(!isOpen)}
+        className={className}
+      >
+        {children?.map((subRoute) => (
+          <SidebarItem
+            key={subRoute.path}
+            route={subRoute}
+            activePath={activePath}
+          />
+        ))}
+      </SidebarSubGroup>
+    )
+  }
+
+  return (
+    <SidebarLink
+      label={route.title}
+      href={route.path}
+      active={isCurrent}
+      icon={getIcon(route.icon)}
+      badge={route.badge}
+      className={className}
+    />
+  )
+}
+
+/**
+ * High-level automated routes data rendering primitive
+ */
+export interface SidebarItemsProps extends ComponentBase {
+  routes: ComponentRoute[]
+}
+
+export function SidebarItems({ routes, className }: SidebarItemsProps) {
+  const { groups, ungrouped, activePath } = useSidebar(routes)
+
+  return (
+    <div className={cn('flex flex-col gap-6', className)}>
+      {ungrouped.length > 0 && (
+        <SidebarGroup>
+          {ungrouped.map((route) => (
+            <SidebarItem
+              key={route.path}
+              route={route}
+              activePath={activePath}
+            />
+          ))}
+        </SidebarGroup>
+      )}
+
+      {groups.map((group) => (
+        <SidebarGroup
+          key={group.title}
+          title={group.title}
+          icon={getIcon(group.icon)}
+        >
+          {group.routes.map((route) => (
+            <SidebarItem
+              key={route.path}
+              route={route}
+              activePath={activePath}
+            />
+          ))}
+        </SidebarGroup>
+      ))}
+    </div>
+  )
+}
+
+/**
+ * Main Sidebar Export
+ */
+export const Sidebar = Object.assign(SidebarRoot, {
+  Root: SidebarRoot,
+  Mobile: SidebarMobile,
+  Header: SidebarHeader,
+  Content: SidebarContent,
+  Group: SidebarGroup,
+  Link: SidebarLink,
+  SubGroup: SidebarSubGroup,
+  Item: SidebarItem,
+  Items: SidebarItems,
+})
+
+export default Sidebar

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

@@ -16,7 +16,7 @@ export function Skeleton({
   return (
     <div
       className={cn(
-        'animate-pulse bg-bg-muted',
+        'animate-pulse bg-soft',
         variant === 'circle' ? 'rounded-full' : 'rounded-md',
         className,
       )}

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

@@ -25,10 +25,7 @@ const TabsList = ({ children, className = '' }: ComponentBase) => {
   return (
     <div
       role="tablist"
-      className={cn(
-        'relative flex flex-row items-center border-b border-border-subtle',
-        className,
-      )}
+      className={cn('relative flex flex-row items-center', className)}
     >
       {children}
     </div>
@@ -46,9 +43,9 @@ const TabsItem = ({
     <button
       role="tab"
       aria-selected={selected}
+      data-selected={selected}
       className={cn(
-        'flex items-center gap-2 px-4 py-2 text-sm font-medium transition-colors outline-none cursor-pointer bg-transparent border-none',
-        selected ? 'text-primary-500' : 'text-text-muted hover:text-text-main',
+        'outline-none cursor-pointer bg-transparent border-none',
         className,
       )}
       {...props}
@@ -59,19 +56,11 @@ const TabsItem = ({
 }
 
 const TabsContent = ({ children, className = '' }: ComponentBase) => {
-  return <div className={cn('p-4 outline-none', className)}>{children}</div>
+  return <div className={cn('outline-none', className)}>{children}</div>
 }
 
 const TabsIndicator = ({ className = '', style }: TabsIndicatorProps) => {
-  return (
-    <div
-      className={cn(
-        'absolute bottom-0 h-0.5 bg-primary-500 transition-all duration-300',
-        className,
-      )}
-      style={style}
-    />
-  )
+  return <div className={cn('absolute bottom-0', className)} style={style} />
 }
 
 Tabs.Root = Tabs

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

@@ -31,7 +31,7 @@ const TooltipContent = ({
       offset={8}
       className={(values) =>
         cn(
-          'group z-50 overflow-visible rounded-md bg-bg-surface/90 px-2.5 py-1.5 text-xs font-medium text-text-main shadow-lg backdrop-blur-md ring-1 ring-border-subtle outline-hidden select-none',
+          'group z-50 overflow-visible rounded-md bg-surface px-2.5 py-1.5 text-xs font-medium text-body ring-1 ring-subtle outline-hidden select-none',
           'data-entering:animate-in data-entering:fade-in data-entering:zoom-in-95 data-entering:duration-100',
           'data-exiting:animate-out data-exiting:fade-out data-exiting:zoom-out-95 data-exiting:duration-75',
           'data-[placement=top]:slide-in-from-bottom-1',

package/src/client/components/ui-base/banner.tsx

@@ -0,0 +1,66 @@
+import { useState, useEffect } from 'react'
+import { X } from 'lucide-react'
+
+export interface BannerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * If true, shows a close button to dismiss the banner.
+   */
+  dismissible?: boolean
+  /**
+   * Unique identifier for the banner. If provided and dismissible is true,
+   * the dismissed state will be saved in localStorage so it doesn't reappear
+   * on subsequent visits.
+   */
+  id?: string
+}
+
+export function Banner({
+  children,
+  className = '',
+  dismissible = false,
+  id = 'boltdocs-banner',
+  ...props
+}: BannerProps) {
+  const [isVisible, setIsVisible] = useState(true)
+
+  useEffect(() => {
+    if (dismissible && id) {
+      const isDismissed = localStorage.getItem(
+        `boltdocs-banner-dismissed-${id}`,
+      )
+      if (isDismissed === 'true') {
+        setIsVisible(false)
+      }
+    }
+  }, [dismissible, id])
+
+  const handleDismiss = () => {
+    setIsVisible(false)
+    if (dismissible && id) {
+      localStorage.setItem(`boltdocs-banner-dismissed-${id}`, 'true')
+    }
+  }
+
+  if (!isVisible) return null
+
+  return (
+    <div
+      className={`relative flex items-center justify-center px-4 py-2.5 text-xs font-semibold tracking-wide bg-primary-500/10 dark:bg-primary-500/15 text-primary-700 dark:text-primary-300 border-b border-primary-500/20 select-none animate-in fade-in duration-300 ${className}`}
+      {...props}
+    >
+      <div className="flex-1 text-center flex items-center justify-center gap-2">
+        {children}
+      </div>
+      {dismissible && (
+        <button
+          onClick={handleDismiss}
+          className="absolute right-3 top-1/2 -translate-y-1/2 p-1.5 opacity-70 hover:opacity-100 transition-all duration-300 rounded-xl hover:bg-primary-500/10 cursor-pointer border-none bg-transparent flex items-center justify-center outline-none"
+          aria-label="Dismiss banner"
+        >
+          <X className="w-3.5 h-3.5" />
+        </button>
+      )}
+    </div>
+  )
+}
+export default Banner