@lexibase/rdx-ui 3.0.0 → 3.2.0

package/THIRD_PARTY_NOTICES.md

@@ -2,14 +2,15 @@
 
 ## shadcn/ui
 
-Table and Kbd use the official base-nova registry components. Dialog, Code Block,
+Table, Kbd and Sheet use the official base-nova registry components. Dialog, Code Block,
 useHighlightedCode, and highlighter are installed in full from that registry,
 with project imports, icons, localization and clipboard failure feedback wired
 to RDX. The official shadcn 4.22.1 tailwind.css is included as styles/shadcn.css.
 https://ui.shadcn.com/docs/components/base/table and
 https://ui.shadcn.com/docs/components/base/kbd and
 https://ui.shadcn.com/docs/components/base/code-block and
-https://ui.shadcn.com/docs/components/base/dialog.
+https://ui.shadcn.com/docs/components/base/dialog and
+https://ui.shadcn.com/docs/components/base/sheet.
 
 MIT License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/rdx-ui",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "engines": {
     "node": "^22.18.0 || ^24.11.0"
@@ -29,13 +29,15 @@
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "lucide-react": "^0.577.0",
+    "mermaid": "^12.2.0",
+    "motion": "^12.43.0",
     "next-themes": "^0.4.6",
     "postcss": "^8.5.31",
     "shiki": "^4.5.0",
     "tailwind-merge": "^3.7.0",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
-    "@lexibase/rdx-types": "1.1.1"
+    "@lexibase/rdx-types": "1.2.0"
   },
   "peerDependencies": {
     "next": "^16.4.2",

package/src/components/docs-page-transition.tsx

@@ -0,0 +1,178 @@
+'use client'
+
+import { useEffect, ViewTransition, type ReactNode } from 'react'
+import { usePathname, useRouter } from 'next/navigation'
+
+const directions = {
+  'rdx-doc-forward': 'rdx-doc-forward',
+  'rdx-doc-back': 'rdx-doc-back',
+  default: 'none',
+}
+
+const interactive = [
+  'a',
+  'button',
+  'input',
+  'textarea',
+  'select',
+  'label',
+  'summary',
+  'dialog',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[role="button"]',
+  '[role="slider"]',
+  '[role="textbox"]',
+  '[role="combobox"]',
+  '[draggable="true"]',
+  'pre',
+  'table',
+  'img',
+  'video',
+  'audio',
+  'canvas',
+  'iframe',
+  '[data-rdx-code-block]',
+  '[data-slot="table-container"]',
+  '[data-slot="tabs"]',
+  '[data-rdx-mermaid-preview]',
+].join(',')
+
+/** Let the router retain ownership of navigation, focus and history. */
+export function DocsPageTransition({
+  children,
+  previousHref,
+  nextHref,
+}: {
+  children: ReactNode
+  previousHref?: string
+  nextHref?: string
+}) {
+  const router = useRouter()
+  const pathname = usePathname()
+
+  useEffect(() => {
+    const scroller = document.querySelector<HTMLElement>(
+      '[data-rdx-docs-scroll]'
+    )
+    if (!scroller) return
+    let gesture: {
+      id: number
+      x: number
+      y: number
+      top: number
+      time: number
+    } | null = null
+    let navigationAt = -Infinity
+    const selected = () => window.getSelection()?.isCollapsed === false
+    const cancel = () => {
+      gesture = null
+    }
+    const start = (event: TouchEvent) => {
+      cancel()
+      if (
+        event.defaultPrevented ||
+        window.innerWidth >= 768 ||
+        event.touches.length !== 1 ||
+        selected()
+      )
+        return
+      const target = event.target
+      if (!(target instanceof Element) || target.closest(interactive)) return
+      // Leave nested horizontal scrollers to their own gestures, including custom MDX.
+      for (
+        let element: Element | null = target;
+        element && element !== scroller;
+        element = element.parentElement
+      ) {
+        if (
+          element.scrollWidth > element.clientWidth + 1 &&
+          /auto|scroll/.test(getComputedStyle(element).overflowX)
+        )
+          return
+      }
+      const touch = event.touches[0]!
+      // Keep browser/system edge gestures available.
+      if (touch.clientX < 32 || touch.clientX > window.innerWidth - 32) return
+      gesture = {
+        id: touch.identifier,
+        x: touch.clientX,
+        y: touch.clientY,
+        top: scroller.scrollTop,
+        time: performance.now(),
+      }
+    }
+    const move = (event: TouchEvent) => {
+      if (event.defaultPrevented) return cancel()
+      if (!gesture) return
+      const touch = event.touches[0]
+      if (
+        event.touches.length !== 1 ||
+        !touch ||
+        touch.identifier !== gesture.id
+      )
+        return cancel()
+      const dx = Math.abs(touch.clientX - gesture.x)
+      const dy = Math.abs(touch.clientY - gesture.y)
+      if (dy > 12 && dy >= dx) cancel()
+    }
+    const end = (event: TouchEvent) => {
+      const current = gesture
+      cancel()
+      if (
+        !current ||
+        event.touches.length ||
+        selected() ||
+        window.innerWidth >= 768
+      )
+        return
+      const touch = Array.from(event.changedTouches).find(
+        (entry) => entry.identifier === current.id
+      )
+      if (!touch) return
+      const dx = touch.clientX - current.x
+      const dy = touch.clientY - current.y
+      const now = performance.now()
+      if (
+        now - current.time > 1000 ||
+        now - navigationAt < 450 ||
+        Math.abs(scroller.scrollTop - current.top) > 8
+      )
+        return
+      if (
+        Math.abs(dx) < Math.min(120, Math.max(64, window.innerWidth * 0.18)) ||
+        Math.abs(dx) < Math.abs(dy) * 1.5
+      )
+        return
+      const href = dx < 0 ? nextHref : previousHref
+      if (!href) return
+      navigationAt = now
+      router.push(href, {
+        transitionTypes: [dx < 0 ? 'rdx-doc-forward' : 'rdx-doc-back'],
+      })
+    }
+    // Passive listeners never take scrolling, zooming or selection away from the browser.
+    scroller.addEventListener('touchstart', start, { passive: true })
+    scroller.addEventListener('touchmove', move, { passive: true })
+    scroller.addEventListener('touchend', end, { passive: true })
+    scroller.addEventListener('touchcancel', cancel, { passive: true })
+    return () => {
+      scroller.removeEventListener('touchstart', start)
+      scroller.removeEventListener('touchmove', move)
+      scroller.removeEventListener('touchend', end)
+      scroller.removeEventListener('touchcancel', cancel)
+    }
+  }, [pathname, previousHref, nextHref, router])
+
+  return (
+    <ViewTransition
+      name="rdx-document"
+      default="none"
+      enter={directions}
+      exit={directions}
+      update={directions}
+      share={directions}
+    >
+      {children}
+    </ViewTransition>
+  )
+}

package/src/components/docs-sidebar.tsx

@@ -4,9 +4,17 @@ import { useMessages } from '../providers/locale-provider'
 
 import { useEffect, useRef, useState } from 'react'
 import { SidebarClose, SidebarOpen } from 'lucide-react'
+import { AnimatePresence, motion, useReducedMotion } from 'motion/react'
 
 import { Button } from './button'
 import { Separator } from './separator'
+import {
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetTitle,
+  SheetTrigger,
+} from './sheet'
 
 export type SidebarCategory = {
   title: string
@@ -21,21 +29,42 @@ export function DocsSidebar({
   pathname: string
 }) {
   const messages = useMessages()
-  const [openPath, setOpenPath] = useState<string | null>(null)
-  const isOpen = openPath === pathname
-  const dialog = useRef<HTMLDialogElement>(null)
+  const [isOpen, setOpen] = useState(false)
+  const open = useRef(false)
+  const actions = useRef<{ close: () => void; unmount: () => void } | null>(
+    null
+  )
+  const previousPath = useRef(pathname)
+  const reducedMotion = useReducedMotion()
+  const pageOrder = new Map(
+    categories
+      .flatMap((category) => category.links)
+      .map((page, index) => [page.href, index])
+  )
+  const currentIndex = pageOrder.get(pathname) ?? -1
+
+  // Route changes (including browser history) must use the same closing phase
+  // as Escape and the close button, keeping the content mounted until exit ends.
   useEffect(() => {
-    if (isOpen && !dialog.current?.open) dialog.current?.showModal()
-    if (!isOpen && dialog.current?.open) dialog.current?.close()
-  }, [isOpen])
+    if (previousPath.current !== pathname) actions.current?.close()
+    previousPath.current = pathname
+  }, [pathname])
+  useEffect(() => {
+    const desktop = window.matchMedia('(min-width: 768px)')
+    const closeOnDesktop = () => {
+      if (desktop.matches) actions.current?.close()
+    }
+    desktop.addEventListener('change', closeOnDesktop)
+    return () => desktop.removeEventListener('change', closeOnDesktop)
+  }, [])
   const content = (
     <nav aria-label={messages.documentationPages}>
       {categories.map((category, index) => (
         <div
           key={`${index}:${category.title}`}
-          className="flex flex-col gap-0.5 mb-3 first:mt-4"
+          className="flex min-w-0 flex-col gap-0.5 mb-3 first:mt-4"
         >
-          <p className="text-xs text-ring font-semibold uppercase mb-1">
+          <p className="text-xs text-ring font-semibold uppercase mb-1 [overflow-wrap:anywhere]">
             {category.title}
           </p>
           {category.links.map((link) => (
@@ -46,9 +75,18 @@ export function DocsSidebar({
               active={pathname === link.href}
               aria-label={link.label}
               href={link.href}
-              onClick={() => setOpenPath(null)}
+              transitionTypes={
+                currentIndex < 0 || link.href === pathname
+                  ? undefined
+                  : [
+                      pageOrder.get(link.href)! < currentIndex
+                        ? 'rdx-doc-back'
+                        : 'rdx-doc-forward',
+                    ]
+              }
+              onClick={() => actions.current?.close()}
               aria-current={pathname === link.href ? 'page' : undefined}
-              className="justify-start text-sm text-primary"
+              className={`h-auto min-h-8 w-full min-w-0 justify-start whitespace-normal py-1.5 text-left text-sm [overflow-wrap:anywhere] ${pathname === link.href ? 'text-accent-foreground' : 'text-primary'}`}
             >
               {link.label}
             </Button>
@@ -59,15 +97,22 @@ export function DocsSidebar({
     </nav>
   )
   return (
-    <>
+    <Sheet
+      open={isOpen}
+      actionsRef={actions}
+      onOpenChange={(nextOpen, details) => {
+        if (!nextOpen) details.preventUnmountOnClose()
+        open.current = nextOpen
+        setOpen(nextOpen)
+      }}
+    >
       <div className="md:hidden absolute top-2 left-4 z-30">
-        <Button
-          variant="ghost"
-          onClick={() => setOpenPath(pathname)}
+        <SheetTrigger
+          render={<Button variant="ghost" />}
           aria-label={messages.openSidebar}
         >
           <SidebarOpen className="size-4" />
-        </Button>
+        </SheetTrigger>
       </div>
       <aside
         data-rdx-sidebar
@@ -75,23 +120,51 @@ export function DocsSidebar({
       >
         {content}
       </aside>
-      <dialog
-        ref={dialog}
-        aria-label={messages.documentationNavigation}
-        onClose={() => setOpenPath(null)}
-        className="fixed inset-0 m-0 h-dvh max-h-none w-full max-w-none bg-background text-foreground border-0 p-4 backdrop:bg-black/40"
-      >
-        <div className="flex justify-end mb-4">
-          <Button
-            variant="ghost"
-            onClick={() => setOpenPath(null)}
-            aria-label={messages.closeSidebar}
+      <AnimatePresence>
+        {isOpen && (
+          <SheetContent
+            key="mobile-sidebar"
+            side="left"
+            showCloseButton={false}
+            portalProps={{ keepMounted: true }}
+            data-rdx-mobile-sidebar
+            className="md:hidden w-full! max-w-none! h-dvh border-0 bg-background text-foreground gap-0 p-4 overflow-y-auto translate-none! opacity-100! transition-none!"
+            render={
+              <motion.div
+                initial="closed"
+                animate="open"
+                exit="closed"
+                variants={{
+                  closed: { x: reducedMotion ? 0 : '-100%' },
+                  open: { x: 0 },
+                }}
+                transition={
+                  reducedMotion
+                    ? { duration: 0 }
+                    : { type: 'spring', stiffness: 300, damping: 30 }
+                }
+                onAnimationComplete={(phase) => {
+                  if (phase === 'closed' && !open.current)
+                    actions.current?.unmount()
+                }}
+              />
+            }
           >
-            <SidebarClose className="size-4" />
-          </Button>
-        </div>
-        {isOpen && content}
-      </dialog>
-    </>
+            <SheetTitle className="sr-only">
+              {messages.documentationNavigation}
+            </SheetTitle>
+            <div className="flex justify-end mb-4">
+              <SheetClose
+                render={<Button variant="ghost" />}
+                aria-label={messages.closeSidebar}
+              >
+                <SidebarClose className="size-4" />
+              </SheetClose>
+            </div>
+            {content}
+          </SheetContent>
+        )}
+      </AnimatePresence>
+    </Sheet>
   )
 }

package/src/components/docs-toc.tsx

@@ -54,7 +54,7 @@ function HeadingLinks({
             className={cn(
               'block rounded-md py-1.5 pr-2 text-xs leading-5 text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
               heading.id === activeId &&
-                'bg-accent/60 font-medium text-foreground'
+                'bg-accent/60 font-medium text-rdx-selected'
             )}
           >
             {heading.title}
@@ -98,12 +98,12 @@ function PageToc({ contentId }: { contentId: string }) {
     }
     const scrollTarget = scrollRoot ?? window
     // Keep native fragment links/history; smooth the actual document scroller.
-    // Tailwind's motion-safe variant leaves reduced-motion navigation instant.
+    // Match the TOC's xl visibility and leave reduced-motion navigation instant.
     const scrollElement = scrollRoot ?? document.documentElement
     const alreadySmooth = scrollElement.classList.contains(
-      'motion-safe:scroll-smooth'
+      'xl:motion-safe:scroll-smooth'
     )
-    scrollElement.classList.add('motion-safe:scroll-smooth')
+    scrollElement.classList.add('xl:motion-safe:scroll-smooth')
     function updateActive() {
       frame = 0
       const top = (scrollRoot?.getBoundingClientRect().top ?? 0) + 96
@@ -172,7 +172,7 @@ function PageToc({ contentId }: { contentId: string }) {
       cancelAnimationFrame(frame)
       cancelAnimationFrame(initialFrame)
       if (!alreadySmooth)
-        scrollElement.classList.remove('motion-safe:scroll-smooth')
+        scrollElement.classList.remove('xl:motion-safe:scroll-smooth')
     }
   }, [contentId])
 
@@ -197,7 +197,7 @@ function PageToc({ contentId }: { contentId: string }) {
               className={cn(
                 'h-0.5 shrink-0 rounded-full bg-current transition-colors',
                 heading.depth === baseDepth ? 'w-5' : 'w-3',
-                heading.id === activeId && 'text-foreground'
+                heading.id === activeId && 'text-rdx-selected'
               )}
             />
           ))}

package/src/components/kbd.tsx

@@ -16,10 +16,17 @@ function Kbd({ className, ...props }: ComponentProps<'kbd'>) {
   )
 }
 
-function KbdGroup({ className, ...props }: ComponentProps<'div'>) {
+function KbdGroup({ className, role, ...props }: ComponentProps<'div'>) {
   return (
     <kbd
       data-slot="kbd-group"
+      role={
+        role ??
+        (props['aria-label'] !== undefined ||
+        props['aria-labelledby'] !== undefined
+          ? 'group'
+          : undefined)
+      }
       className={cn('inline-flex items-center gap-1', className)}
       {...props}
     />

package/src/components/mdx-code-block-view.tsx

@@ -1,7 +1,16 @@
 'use client'
 
-import { useState, type ComponentProps, type ReactNode } from 'react'
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react'
 import { CodeXml, FolderTree, GitCompareArrows, WrapText } from 'lucide-react'
+import { motion } from 'motion/react'
 
 import { useMessages } from '../providers/locale-provider'
 import { Button } from './button'
@@ -12,24 +21,100 @@ import {
   CodeBlockCopyButton,
   CodeBlockHeader,
   CodeBlockTitle,
+  CodeBlockFooter,
 } from './code-block'
 
+// Keep native pre events separate from Motion's gesture event props.
+const AnimatedCodeBlockContent = motion.create(function PreviewContent({
+  preProps,
+  ...props
+}: ComponentProps<typeof CodeBlockContent> & {
+  preProps: ComponentProps<'pre'>
+}) {
+  return <CodeBlockContent {...preProps} {...props} />
+})
+
 /** The wrap action follows shadcn's stateful Code Block composition. */
 export function MdxCodeBlockView({
   label,
   mode,
   value,
+  lineNumbers,
+  startLine,
   preProps,
   children,
 }: {
   label: string
   mode?: 'folder' | 'diff'
   value: string
+  lineNumbers?: boolean
+  startLine?: number
   preProps: ComponentProps<'pre'>
   children: ReactNode
 }) {
   const [wrap, setWrap] = useState(false)
+  const [expanded, setExpanded] = useState(false)
+  const [previewHeight, setPreviewHeight] = useState<number | null>(null)
+  const [fullHeight, setFullHeight] = useState(0)
+  const [animateSize, setAnimateSize] = useState(false)
+  const blockRef = useRef<HTMLDivElement>(null)
+  const generatedId = useId()
+  const contentId = preProps.id ?? generatedId
+  const collapsed = previewHeight !== null && !expanded
+  const contentStyle: CSSProperties = {
+    ...preProps.style,
+    ...(previewHeight !== null && {
+      height: 'var(--rdx-code-preview-height)',
+    }),
+  }
   const messages = useMessages()
+
+  useEffect(() => {
+    const pre = blockRef.current?.querySelector<HTMLElement>(
+      '[data-slot="code-block-content"]'
+    )
+    const code = pre?.querySelector('code')
+    if (!pre || !code) return
+    const desktop = window.matchMedia('(min-width: 768px)')
+    let frame = 0
+    let observer: ResizeObserver | undefined
+    const measure = () => {
+      if (desktop.matches) return
+      const style = getComputedStyle(pre)
+      const lineHeight = parseFloat(style.lineHeight)
+      const padding =
+        parseFloat(style.paddingTop) + parseFloat(style.paddingBottom)
+      if (!Number.isFinite(lineHeight)) return
+      const limit = lineHeight * 12 + padding
+      const height = code.getBoundingClientRect().height + padding
+      setFullHeight(height)
+      setPreviewHeight(height > limit + 1 ? limit : null)
+    }
+    const schedule = () => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(measure)
+    }
+    const updateViewport = () => {
+      setAnimateSize(false)
+      observer?.disconnect()
+      cancelAnimationFrame(frame)
+      if (desktop.matches) {
+        setPreviewHeight(null)
+        return
+      }
+      observer = new ResizeObserver(schedule)
+      observer.observe(code)
+      observer.observe(pre)
+      schedule()
+    }
+    updateViewport()
+    desktop.addEventListener('change', updateViewport)
+    return () => {
+      observer?.disconnect()
+      cancelAnimationFrame(frame)
+      desktop.removeEventListener('change', updateViewport)
+    }
+  }, [value])
   const Icon =
     mode === 'folder'
       ? FolderTree
@@ -39,13 +124,15 @@ export function MdxCodeBlockView({
   return (
     <CodeBlock
       size="sm"
+      ref={blockRef}
       data-rdx-code-block
       data-rdx-code-mode={mode}
       data-rdx-code-value={value}
+      data-rdx-code-collapsed={collapsed || undefined}
       className="my-4 max-w-full"
     >
       <CodeBlockHeader>
-        <CodeBlockTitle>
+        <CodeBlockTitle title={label}>
           <Icon aria-hidden="true" /> {label}
         </CodeBlockTitle>
         <CodeBlockActions>
@@ -56,22 +143,61 @@ export function MdxCodeBlockView({
             aria-label={messages.wrapCode}
             title={messages.wrapCode}
             aria-pressed={wrap}
-            onClick={() => setWrap(!wrap)}
+            onClick={() => {
+              setAnimateSize(false)
+              setWrap(!wrap)
+            }}
           >
             <WrapText aria-hidden="true" />
           </Button>
           <CodeBlockCopyButton value={value} />
         </CodeBlockActions>
       </CodeBlockHeader>
-      <CodeBlockContent
-        {...preProps}
+      <AnimatedCodeBlockContent
+        preProps={preProps}
+        initial={false}
+        animate={{
+          '--rdx-code-preview-height': `${previewHeight === null ? 0 : expanded ? fullHeight : previewHeight}px`,
+        }}
+        transition={{
+          duration: animateSize ? 0.28 : 0,
+          ease: [0.22, 1, 0.36, 1],
+        }}
+        id={contentId}
+        style={contentStyle}
         wrap={wrap}
-        className={[preProps.className, 'data-wrap:wrap-anywhere']
+        lineNumbers={lineNumbers}
+        startLine={startLine}
+        className={[
+          preProps.className,
+          'data-wrap:wrap-anywhere',
+          previewHeight !== null && 'overflow-y-hidden',
+          collapsed && 'scroll-fade-y',
+        ]
           .filter(Boolean)
           .join(' ')}
       >
         {children}
-      </CodeBlockContent>
+      </AnimatedCodeBlockContent>
+      {previewHeight !== null && (
+        <CodeBlockFooter className="justify-center md:hidden">
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-6 px-2 text-xs"
+            aria-expanded={expanded}
+            aria-controls={contentId}
+            onClick={() => {
+              setAnimateSize(
+                !window.matchMedia('(prefers-reduced-motion: reduce)').matches
+              )
+              setExpanded(!expanded)
+            }}
+          >
+            {expanded ? messages.showLess : messages.showMore}
+          </Button>
+        </CodeBlockFooter>
+      )}
     </CodeBlock>
   )
 }