@exegia/corpora-ui 0.16.0 → 0.18.0

package/src/components/blocks/scaffold/use-scaffold.ts

@@ -0,0 +1,48 @@
+"use client"
+
+import { useCallback, useMemo, useState } from "react"
+
+import type { ScaffoldControls, UseScaffoldOptions } from "./type"
+
+/**
+ * Owns the scaffold's inspector state for UI living outside the scaffold
+ * (title-bar buttons, command palette, shortcuts). Spread the returned
+ * `providerProps` onto `Scaffold.Root`; without this hook the root manages
+ * the same state internally via `defaultInspectorOpen`.
+ */
+export function useScaffold({
+  defaultInspectorOpen,
+  onInspectorChange,
+}: UseScaffoldOptions = {}): ScaffoldControls {
+  const [inspectorOpen, setOpenState] = useState(defaultInspectorOpen ?? false)
+
+  const setInspectorOpen = useCallback(
+    (open: boolean) => {
+      setOpenState((prev) => {
+        if (prev !== open) onInspectorChange?.(open)
+        return open
+      })
+    },
+    [onInspectorChange]
+  )
+
+  const toggleInspector = useCallback(
+    () => setInspectorOpen(!inspectorOpen),
+    [inspectorOpen, setInspectorOpen]
+  )
+
+  const providerProps = useMemo(
+    () => ({
+      inspectorOpen,
+      onInspectorOpenChange: setInspectorOpen,
+    }),
+    [inspectorOpen, setInspectorOpen]
+  )
+
+  return {
+    inspectorOpen,
+    setInspectorOpen,
+    toggleInspector,
+    providerProps,
+  }
+}

package/src/components/blocks/scaffold/utils.ts

@@ -0,0 +1,30 @@
+import type { ClassNameValue } from "tailwind-merge"
+import type { TSubPanelVariant } from "@/components/blocks/scaffold/type.ts"
+
+/** Desktop backdrop the whole scaffold sits on — a soft warm-gray wash. */
+export const scaffoldBackgroundClass: ClassNameValue =
+  "bg-linear-to-tr/increasing from-neutral-400 via-stone-200 to-neutral-300 dark:from-neutral-900 dark:via-neutral-950 dark:to-stone-950"
+
+/** Card surface shared by a panel's primary area and secondary strip. */
+export const panelSurfaceClass: ClassNameValue =
+  "rounded-2xl bg-slate-100 inset-ring-1 inset-ring-white/60 dark:bg-neutral-900 dark:inset-ring-white/5"
+
+/** Floating icon button hovering over a panel (close, swap). */
+export const floatingButtonClass: ClassNameValue =
+  "transition-[opacity,scale,box-shadow] duration-200 ease-smooth-out hover:text-neutral-900 hover:shadow-md active:scale-97 dark:bg-neutral-800/95 dark:text-neutral-300 dark:inset-ring-white/10 dark:hover:text-white motion-reduce:transition-none motion-reduce:active:scale-100 z-20"
+
+/** Hidden until the pointer rests on the panel (always shown for touch and
+ * while focused) — the affordances stay quiet until the panel is engaged. */
+export const revealOnPanelHoverClass: ClassNameValue =
+  "opacity-0 scale-95 group-hover/panel:opacity-100 group-hover/panel:scale-100 focus-visible:opacity-100 focus-visible:scale-100 pointer-coarse:opacity-100 pointer-coarse:scale-100"
+
+/** Pill segment inside the actions cluster (Add, browse). */
+export const actionSegmentClass: ClassNameValue =
+  "flex h-[30px] items-center rounded-full text-neutral-700 transition-[background-color,color,scale,box-shadow] duration-150 ease-smooth-out hover:bg-white hover:text-neutral-900 hover:shadow-xs active:scale-97 dark:text-neutral-300 dark:hover:bg-neutral-700 dark:hover:text-white motion-reduce:transition-none motion-reduce:active:scale-100"
+
+/** Map of sub-panel variants to their corresponding side. */
+export const subPanelVariant: Record<TSubPanelVariant, ClassNameValue> = {
+  card: "bg-neutral-50 dark:bg-neutral-900 rounded-md border-t border-b border-t-white dark:border-t-neutral-700/50 border-b-neutral-900/10 dark:border-b-black/70 shadow-sm shadow-neutral-900/10 dark:shadow-black/50 inset-shadow-sm inset-shadow-white dark:inset-shadow-neutral-800",
+  subtle: "bg-neutral-100 dark:bg-neutral-800",
+  inset: "bg-neutral-200 dark:bg-neutral-700",
+} as const

package/src/components/blocks/shell/__tests__/shell-layout.test.tsx

@@ -92,12 +92,12 @@ describe("ShellLayout", () => {
     expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
   })
 
-  test("a panel's own open flag seeds its side's initial state", () => {
+  test("a panel's own defaultOpen flag seeds its side's initial state", () => {
     render(
       <ShellLayout
         panels={{
           ...PANELS,
-          right: { ...PANELS.right!, open: true },
+          right: { ...PANELS.right!, defaultOpen: true },
         }}
         variant="web"
       />
@@ -112,7 +112,7 @@ describe("ShellLayout", () => {
         defaultOpen={{ left: false, right: false }}
         panels={{
           ...PANELS,
-          right: { ...PANELS.right!, open: true },
+          right: { ...PANELS.right!, defaultOpen: true },
         }}
         variant="web"
       />

package/src/components/blocks/shell/animated-panel-inset.tsx

@@ -0,0 +1,23 @@
+import { forwardRef } from "react"
+import { motion } from "motion/react"
+import { cn } from "@/lib/utils.ts"
+import type { AnimatedSidebarInsetProps } from "./type"
+
+export const AnimatedPanelInset = forwardRef<
+  HTMLElement,
+  AnimatedSidebarInsetProps
+>(function AnimatedSidebarInset({ className, ...props }, forwardedRef) {
+  return (
+    <motion.main
+      {...props}
+      ref={forwardedRef}
+      data-slot="sidebar-inset"
+      className={cn(
+        "relative flex min-w-0 flex-1 flex-col bg-neutral-50 dark:bg-neutral-900",
+        "outline-offset-0.5 overflow-hidden border-t-3 border-white outline-neutral-100 dark:border-neutral-800 dark:inset-ring-black",
+        "rounded-lg shadow-md shadow-neutral-200 dark:shadow-neutral-950",
+        className
+      )}
+    />
+  )
+})

package/src/components/blocks/shell/animated-panel-provider.tsx

@@ -0,0 +1,155 @@
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
+import { useReducedMotion } from "motion/react"
+import { cn } from "@/lib/utils.ts"
+import type {
+  AnimatedSidebarProviderProps,
+  SidebarSide,
+} from "./type"
+import {
+  AnimatedSidebarContext,
+  SIDEBAR_KEYBOARD_SHORTCUT,
+  useIsMobile,
+} from "./utils"
+
+export function AnimatedPanelProvider({
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+  openMobile,
+  defaultOpenMobile,
+  onOpenMobileChange,
+  className,
+  style,
+  ...props
+}: AnimatedSidebarProviderProps) {
+  const [internalOpen, setInternalOpen] = useState<
+    Record<SidebarSide, boolean>
+  >(() => ({
+    left: defaultOpen?.left ?? true,
+    right: defaultOpen?.right ?? false,
+  }))
+  const [internalOpenMobile, setInternalOpenMobile] = useState<
+    Record<SidebarSide, boolean>
+  >(() => ({
+    left: defaultOpenMobile?.left ?? false,
+    right: defaultOpenMobile?.right ?? false,
+  }))
+  const isMobile = useIsMobile()
+  const reduce = useReducedMotion() ?? false
+  const generatedId = useId()
+  const leftTriggerRef = useRef<HTMLButtonElement>(null)
+  const rightTriggerRef = useRef<HTMLButtonElement>(null)
+
+  // Per-side controlled/uncontrolled merge — a side is controlled exactly
+  // when its key is present on the controlled record.
+  const controlledLeft = open?.left
+  const controlledRight = open?.right
+  const controlledMobileLeft = openMobile?.left
+  const controlledMobileRight = openMobile?.right
+
+  const openState = useMemo<Record<SidebarSide, boolean>>(
+    () => ({
+      left: controlledLeft ?? internalOpen.left,
+      right: controlledRight ?? internalOpen.right,
+    }),
+    [controlledLeft, controlledRight, internalOpen]
+  )
+  const openMobileState = useMemo<Record<SidebarSide, boolean>>(
+    () => ({
+      left: controlledMobileLeft ?? internalOpenMobile.left,
+      right: controlledMobileRight ?? internalOpenMobile.right,
+    }),
+    [controlledMobileLeft, controlledMobileRight, internalOpenMobile]
+  )
+
+  const setOpen = useCallback(
+    (nextOpen: boolean, side: SidebarSide) => {
+      const controlled = side === "left" ? controlledLeft : controlledRight
+      if (controlled === undefined) {
+        setInternalOpen((prev) =>
+          prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
+        )
+      }
+      onOpenChange?.(nextOpen, side)
+    },
+    [controlledLeft, controlledRight, onOpenChange]
+  )
+
+  const setOpenMobile = useCallback(
+    (nextOpen: boolean, side: SidebarSide) => {
+      const controlled =
+        side === "left" ? controlledMobileLeft : controlledMobileRight
+      if (controlled === undefined) {
+        setInternalOpenMobile((prev) =>
+          prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
+        )
+      }
+      onOpenMobileChange?.(nextOpen, side)
+    },
+    [controlledMobileLeft, controlledMobileRight, onOpenMobileChange]
+  )
+
+  const toggleSidebar = useCallback(
+    (side: SidebarSide) => {
+      if (isMobile) setOpenMobile(!openMobileState[side], side)
+      else setOpen(!openState[side], side)
+    },
+    [isMobile, openMobileState, openState, setOpen, setOpenMobile]
+  )
+
+  const triggerRefs = useMemo(
+    () => ({ left: leftTriggerRef, right: rightTriggerRef }),
+    []
+  )
+
+  useEffect(() => {
+    const handleShortcut = (event: KeyboardEvent) => {
+      if (
+        event.key.toLowerCase() === SIDEBAR_KEYBOARD_SHORTCUT &&
+        (event.metaKey || event.ctrlKey)
+      ) {
+        event.preventDefault()
+        toggleSidebar("left")
+      }
+    }
+
+    window.addEventListener("keydown", handleShortcut)
+    return () => window.removeEventListener("keydown", handleShortcut)
+  }, [toggleSidebar])
+
+  return (
+    <AnimatedSidebarContext.Provider
+      value={{
+        isMobile,
+        layoutId: `${generatedId}-active`,
+        open: openState,
+        openMobile: openMobileState,
+        reduce,
+        setOpen,
+        setOpenMobile,
+        toggleSidebar,
+        triggerRefs,
+      }}
+    >
+      <div
+        {...props}
+        data-slot="sidebar-wrapper"
+        data-state-left={openState.left ? "expanded" : "collapsed"}
+        data-state-right={openState.right ? "expanded" : "collapsed"}
+        style={{
+          "--sidebar-width": "19rem",
+          "--sidebar-width-icon": "4.25rem",
+          "--sidebar-width-mobile": "18rem",
+          ...style,
+        }}
+        className={cn(
+          "group/sidebar-wrapper flex w-full min-w-0 gap-x-2",
+          className
+        )}
+      >
+        {children}
+      </div>
+    </AnimatedSidebarContext.Provider>
+  )
+}

package/src/components/blocks/shell/animated-panel-trigger.tsx

@@ -0,0 +1,42 @@
+import { forwardRef } from "react"
+import { Button } from "@/components/ui/button"
+import { useAnimatedSidebar } from "./utils"
+import type { AnimatedSidebarTriggerProps } from "./type"
+
+export const AnimatedPanelTrigger = forwardRef<
+  HTMLButtonElement,
+  AnimatedSidebarTriggerProps
+>(function AnimatedSidebarTrigger(
+  { onClick, side = "left", type = "button", ...props },
+  forwardedRef
+) {
+  const context = useAnimatedSidebar()
+  const expanded = context.isMobile
+    ? context.openMobile[side]
+    : context.open[side]
+  const triggerRef = context.triggerRefs[side]
+
+  return (
+    <Button
+      {...props}
+      ref={(node) => {
+        triggerRef.current = node
+        if (typeof forwardedRef === "function") forwardedRef(node)
+        else if (forwardedRef) forwardedRef.current = node
+      }}
+      type={type}
+      variant="ghost"
+      size="icon-xl"
+      aria-label={props["aria-label"] ?? "Toggle sidebar"}
+      aria-expanded={expanded}
+      data-slot="sidebar-trigger"
+      data-side={side}
+      data-state={expanded ? "expanded" : "collapsed"}
+      onClick={(event) => {
+        onClick?.(event)
+        if (event.defaultPrevented) return
+        context.toggleSidebar(side)
+      }}
+    />
+  )
+})

package/src/components/blocks/shell/animated-panel.tsx

@@ -0,0 +1,135 @@
+"use client"
+// beui.dev/components/motion/animated-sidebar
+
+import { motion } from "motion/react"
+import { EASE_OUT } from "@/lib/ease.ts"
+import { cn } from "@/lib/utils"
+import type { AnimatedSidebarProps } from "./type"
+import {
+  AnimatedSidebarPanelContext,
+  SIDEBAR_MORPH_TRANSITION,
+  PANEL_TRANSITION,
+  REDUCED_TRANSITION,
+  useAnimatedSidebar
+} from "./utils"
+
+export function AnimatedPanel({
+  side = "left",
+  variant = "sidebar",
+  collapsible = "icon",
+  ariaLabel = "Sidebar",
+  children,
+  className,
+  panelClassName,
+  style,
+  ref,
+  ...props
+}: AnimatedSidebarProps) {
+  const context = useAnimatedSidebar()
+  const sideOpen = context.open[side]
+  const collapsed = collapsible !== "none" && !sideOpen
+  const offcanvas = collapsed && collapsible === "offcanvas"
+  const width = offcanvas
+    ? "0px"
+    : collapsed
+      ? "var(--sidebar-width-icon)"
+      : "var(--sidebar-width)"
+
+  if (context.isMobile) return <div>TODO: Create Mobile nav experience</div>
+
+  return (
+    <motion.aside
+      {...props}
+      ref={ref}
+      initial={false}
+      aria-label={ariaLabel}
+      data-slot="sidebar"
+      data-state={collapsed ? "collapsed" : "expanded"}
+      data-collapsible={collapsible}
+      data-variant={variant}
+      data-side={side}
+      animate={{
+        width,
+        // Swallow the shell's gap-x-2 column gap while off canvas so the
+        // shell edge keeps a constant spacing-2 inset whether the panel is
+        // open (gap + panel + margin) or collapsed (gap + this).
+        ...(side === "right"
+          ? { marginLeft: offcanvas ? "-0.5rem" : "0rem" }
+          : { marginRight: offcanvas ? "-0.5rem" : "0rem" }),
+      }}
+      transition={context.reduce ? { duration: 0 } : SIDEBAR_MORPH_TRANSITION}
+      style={style}
+      className={cn(
+        "group/sidebar relative hidden h-full shrink-0 will-change-[width] md:block",
+        "peer flex!",
+        side === "right" && "order-last",
+        className
+      )}
+    >
+      {side === "right" && !collapsed && (
+        // The handle occupies the shell's gap-x-2 column gap. It must stay
+        // outside the clipping mask below or the gap would never receive
+        // hover — clipping cuts hit-testing, not just painting.
+        <motion.div
+          className="absolute inset-y-0 -left-2 z-10 w-2 cursor-col-resize"
+          initial="idle"
+          whileHover="hover"
+        >
+          <motion.div
+            variants={{ idle: { scaleY: 0 }, hover: { scaleY: 1 } }}
+            transition={
+              context.reduce
+                ? { duration: 0 }
+                : { duration: 0.2, ease: EASE_OUT }
+            }
+            className="h-full w-full bg-radial/decreasing from-amber-300/70 to-amber-500/0 to-40%"
+          />
+        </motion.div>
+      )}
+      {/* The off canvas panel keeps its full width and slides out of the
+          zero-width rail, so mask it to the aside's box here instead of
+          clipping the aside itself — the aside must stay unclipped for the
+          gap handle above to be hoverable. */}
+      <div
+        className={
+          collapsible === "offcanvas"
+            ? "absolute inset-0 overflow-hidden rounded-[inherit]"
+            : "contents"
+        }
+      >
+        <motion.div
+          initial={false}
+          animate={{
+            opacity: offcanvas ? 0 : 1,
+            x: offcanvas ? (side === "left" ? "-100%" : "100%") : "0%",
+          }}
+          transition={context.reduce ? REDUCED_TRANSITION : PANEL_TRANSITION}
+          className={cn(
+            "sticky top-0 flex flex-col overflow-hidden",
+         //   collapsible === "offcanvas" && "w-(--sidebar-width)",
+            // Pin the right panel to the aside's trailing edge so the width
+            // animation expands the panel out of it instead of revealing a
+            // detached strip.
+            side === "right" && "ml-auto",
+
+            // Panels fill the shell's container, not the viewport — the shell
+            // owns its own scrolling, so a bounded host (docs demo, split
+            // view) must bound the panels too. Full-page apps size the shell
+            // itself (e.g., h-svh). The bottom gap comes from the shell
+            // container's padding, so panels only carry their top offset.
+            variant === "floating" && "mx-2 mt-2 h-[calc(100%-0.5rem)]",
+            variant === "inset" && "mt-2 h-[calc(100%-0.5rem)]",
+
+            panelClassName
+          )}
+        >
+          <AnimatedSidebarPanelContext.Provider
+            value={{ collapsed, collapsible, side }}
+          >
+            {children}
+          </AnimatedSidebarPanelContext.Provider>
+        </motion.div>
+      </div>
+    </motion.aside>
+  )
+}

package/src/components/blocks/shell/animated-sidebar-content.tsx

@@ -0,0 +1,19 @@
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "@/lib/utils"
+
+export const AnimatedSidebarContent = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function AnimatedSidebarContent({ className, ...props }, forwardedRef) {
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      data-slot="sidebar-content"
+      className={cn(
+        "flex min-h-0 flex-1 flex-col gap-2 overflow-x-hidden overflow-y-auto overscroll-contain px-2 py-2",
+        className
+      )}
+    />
+  )
+})

package/src/components/blocks/shell/animated-sidebar-footer.tsx

@@ -0,0 +1,19 @@
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "@/lib/utils"
+
+export const AnimatedSidebarFooter = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function AnimatedSidebarFooter({ className, ...props }, forwardedRef) {
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      data-slot="sidebar-footer"
+      className={cn(
+        "flex shrink-0 flex-col gap-2 border-t border-border p-3 pb-[max(0.75rem,env(safe-area-inset-bottom))]",
+        className
+      )}
+    />
+  )
+})

package/src/components/blocks/shell/animated-sidebar-group-content.tsx

@@ -0,0 +1,16 @@
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "@/lib/utils"
+
+export const AnimatedSidebarGroupContent = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function AnimatedSidebarGroupContent({ className, ...props }, forwardedRef) {
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      data-slot="sidebar-group-content"
+      className={cn("w-full min-w-0", className)}
+    />
+  )
+})

package/src/components/blocks/shell/animated-sidebar-group-label.tsx

@@ -0,0 +1,29 @@
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "@/lib/utils"
+import { useAnimatedSidebarPanel } from "./utils"
+
+export const AnimatedSidebarGroupLabel = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function AnimatedSidebarGroupLabel(
+  { children, className, ...props },
+  forwardedRef
+) {
+  const { collapsed } = useAnimatedSidebarPanel()
+
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      aria-hidden={collapsed}
+      data-slot="sidebar-group-label"
+      className={cn(
+        "mb-1 h-7 overflow-hidden px-2 text-[10px] font-medium tracking-[0.14em] text-muted-foreground uppercase transition-opacity",
+        collapsed ? "opacity-0" : "opacity-100",
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+})

package/src/components/blocks/shell/animated-sidebar-group.tsx

@@ -0,0 +1,16 @@
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "@/lib/utils"
+
+export const AnimatedSidebarGroup = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function AnimatedSidebarGroup({ className, ...props }, forwardedRef) {
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      data-slot="sidebar-group"
+      className={cn("flex w-full min-w-0 flex-col px-1 py-1.5", className)}
+    />
+  )
+})

package/src/components/blocks/shell/animated-sidebar-header.tsx

@@ -0,0 +1,16 @@
+import { forwardRef, type HTMLAttributes } from "react"
+import { cn } from "@/lib/utils"
+
+export const AnimatedSidebarHeader = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function AnimatedSidebarHeader({ className, ...props }, forwardedRef) {
+  return (
+    <div
+      {...props}
+      ref={forwardedRef}
+      data-slot="sidebar-header"
+      className={cn("flex shrink-0 flex-col gap-2 p-3", className)}
+    />
+  )
+})