@exegia/corpora-ui 0.17.0 → 0.19.0

package/src/components/blocks/scaffold/panel-menu-button.tsx

@@ -0,0 +1,218 @@
+"use client"
+
+import * as React from "react"
+
+import { More } from "iconsax-reactjs"
+import { LucideArrowUpDown, LucideChevronDown, LucideX } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+import type { PanelMenuButtonProps } from "./type"
+import { floatingButtonClass, revealOnPanelHoverClass } from "./utils"
+import { Button } from "@/components/ui/button"
+import { GlassButtonGroup } from "@/components/ui/glasscn/glass-button-group.tsx"
+import { useHoverCapable } from "@/lib/hooks/use-hover-capable"
+import { SCAFFOLD_MENU_COLLAPSE_DELAY } from "./constants"
+
+/** One side of the seam menu. Both sides stay mounted; the pill morphs by
+ * collapsing one side's grid column to 0fr while the other grows — pure
+ * CSS, driven by `data-expanded` on the group. The hidden side is inert
+ * and aria-hidden so it can't be clicked, focused or found by queries. */
+const menuCellClass =
+  "grid transition-[grid-template-columns,opacity] duration-300 ease-smooth-out motion-reduce:transition-none"
+
+/**
+ * Floating menu affordance centered on the seam between a panel's primary
+ * surface and its secondary strip: a compact ⋯ toggle that morphs into the
+ * Expand | Swap (| Close) actions.
+ */
+export function PanelMenuButton({
+  onClick,
+  onExpand,
+  onCloseSecondary,
+  secondaryExpanded = false,
+  swapped = false,
+  label,
+  sound = true,
+  className,
+}: PanelMenuButtonProps): React.ReactElement {
+  const canHover = useHoverCapable()
+  const actionsId = React.useId()
+  const groupRef = React.useRef<HTMLDivElement>(null)
+  const actionsRef = React.useRef<HTMLDivElement>(null)
+  const [expanded, setExpanded] = React.useState(false);
+
+  const collapseTimerRef = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+  const suppressHoverOpenUntilRef = React.useRef(0)
+  const focusActionsOnOpenRef = React.useRef(false)
+
+  React.useEffect(() => () => clearTimeout(collapseTimerRef.current), [])
+
+  const cancelCollapse = React.useCallback(() => {
+    clearTimeout(collapseTimerRef.current)
+  }, [])
+
+  // Arms when the pointer stops hovering the group: the menu lingers for the
+  // grace period, then collapses — unless the pointer (or focus) came back.
+  const armCollapse = React.useCallback(() => {
+    if (!canHover) return
+    clearTimeout(collapseTimerRef.current)
+    collapseTimerRef.current = setTimeout(() => {
+      // Focus keeps the menu open — don't collapse under the keyboard.
+      if (groupRef.current?.contains(document.activeElement)) return
+      setExpanded(false)
+    }, SCAFFOLD_MENU_COLLAPSE_DELAY)
+  }, [canHover])
+
+  // The grace period must keep counting when the pointer leaves the whole
+  // app — leaving the window can skip the group's own pointerleave, so arm
+  // on viewport exit and window blur as well.
+  React.useEffect(() => {
+    if (!expanded || !canHover) return
+    const root = document.documentElement
+    root.addEventListener("pointerleave", armCollapse)
+    window.addEventListener("blur", armCollapse)
+    return () => {
+      root.removeEventListener("pointerleave", armCollapse)
+      window.removeEventListener("blur", armCollapse)
+    }
+  }, [expanded, canHover, armCollapse])
+
+  // Click-opens replace the toggle with the actions — hand focus over so
+  // keyboard users aren't dropped onto an inert control.
+  React.useEffect(() => {
+    if (!expanded || !focusActionsOnOpenRef.current) return
+    focusActionsOnOpenRef.current = false
+    actionsRef.current?.querySelector<HTMLButtonElement>("button")?.focus()
+  }, [expanded])
+
+  const collapse = () => {
+    // The shrinking toggle can glide under a resting cursor and hover-reopen
+    // the menu it just closed — ignore hover-opens until it has settled.
+    suppressHoverOpenUntilRef.current = Date.now() + 600
+    setExpanded(false)
+  }
+
+  // Acting collapses the menu — the pill returns to the compact toggle.
+  const handleAction = (action?: () => void) => {
+    action?.()
+    collapse()
+  }
+
+  // Click open — the touch and keyboard path.
+  const handleOnExpand = () => {
+    if (groupRef.current?.contains(document.activeElement)) {
+      focusActionsOnOpenRef.current = true
+    }
+    setExpanded(true)
+  }
+
+  // Hover on the toggle opens the menu (hover-capable devices only — touch
+  // and keyboard go through the click toggle).
+  const handleToggleHover = () => {
+    if (!canHover || Date.now() < suppressHoverOpenUntilRef.current) return
+    cancelCollapse()
+    setExpanded(true)
+  }
+
+  return (
+    <GlassButtonGroup
+      ref={groupRef}
+      onPointerEnter={cancelCollapse}
+      onPointerLeave={armCollapse}
+      glassVariant="subtle"
+      data-expanded={expanded ? "" : undefined}
+      className={cn(
+        floatingButtonClass,
+        revealOnPanelHoverClass,
+        "group/menu absolute top-1/2 z-10 -translate-y-1/2",
+        className
+      )}
+    >
+      <div
+        aria-hidden={expanded || undefined}
+        inert={expanded || undefined}
+        className={cn(
+          menuCellClass,
+          "grid-cols-[1fr] opacity-100 group-data-expanded/menu:grid-cols-[0fr] group-data-expanded/menu:opacity-0"
+        )}
+      >
+        <div className="flex min-w-0 overflow-hidden">
+          <Button
+            id="scaffold-panel-menu-toggle-button"
+            aria-label={label}
+            aria-expanded={expanded}
+            aria-controls={actionsId}
+            size="icon-sm"
+            variant="ghost"
+            sound={sound}
+            data-slot="scaffold-panel-menu-toggle"
+            onClick={handleOnExpand}
+            onPointerEnter={handleToggleHover}
+          >
+            <More size={16} />
+          </Button>
+        </div>
+      </div>
+      <div
+        id={actionsId}
+        ref={actionsRef}
+        aria-hidden={!expanded || undefined}
+        inert={!expanded || undefined}
+        className={cn(
+          menuCellClass,
+          "grid-cols-[0fr] opacity-0 group-data-expanded/menu:grid-cols-[1fr] group-data-expanded/menu:opacity-100"
+        )}
+      >
+        <div className="flex min-w-0 overflow-hidden">
+          <Button
+            id="scaffold-panel-menu-expand"
+            size="sm"
+            variant="ghost"
+            sound={sound}
+            data-slot="scaffold-panel-menu-expand"
+            className="rounded-r-none"
+            onClick={() => handleAction(onExpand)}
+          >
+            {/* Points at the sub-panel that grows next, in VISUAL space —
+                a swapped panel is column-reverse, so the direction mirrors.
+                Button's [&_svg]:transition-transform eases the flip. */}
+            <LucideChevronDown
+              size={16}
+              className={cn(secondaryExpanded !== swapped && "rotate-180")}
+            />
+            Expand
+          </Button>
+          <Button
+            id="scaffold-panel-menu-swap"
+            size="sm"
+            variant="ghost"
+            sound={sound}
+            data-slot="scaffold-panel-menu-swap"
+            className={cn(
+              "border-l-0",
+              onCloseSecondary ? "rounded-none" : "rounded-l-none"
+            )}
+            onClick={() => handleAction(onClick)}
+          >
+            <LucideArrowUpDown size={16} />
+            Swap
+          </Button>
+          {onCloseSecondary && (
+            <Button
+              id="scaffold-panel-menu-close"
+              size="sm"
+              variant="ghost"
+              sound={sound}
+              data-slot="scaffold-panel-menu-close"
+              className="rounded-l-none border-l-0"
+              onClick={() => handleAction(onCloseSecondary)}
+            >
+              <LucideX size={16} />
+              Close
+            </Button>
+          )}
+        </div>
+      </div>
+    </GlassButtonGroup>
+  )
+}

package/src/components/blocks/scaffold/scaffold-actions.tsx

@@ -0,0 +1,88 @@
+"use client"
+
+import { AnimatePresence, motion, useReducedMotion } from "motion/react"
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { SCAFFOLD_EASE, SCAFFOLD_EDGE_GUTTER, SCAFFOLD_MORPH_DURATION } from "./constants"
+import { useScaffoldContext } from "./scaffold-context"
+import type { ScaffoldActionsProps } from "./type"
+import { segmentVariants } from "./utils"
+import { Button } from "@/components/ui/button"
+import { SPRING_LAYOUT } from "@/lib/ease.ts"
+import { LucidePlus } from "lucide-react"
+
+/**
+ * The floating pill cluster in the main region's top-right corner — the
+ * design's "Panel Context Menu": one tab per open panel (`Scaffold.Tab`
+ * children) plus an Add segment. Add renders only while `onAdd` is
+ * present — omit it once the canvas holds `SCAFFOLD_PANEL_CAPACITY`
+ * panels. Slides left in step with the inspector opening.
+ */
+export function ScaffoldActions({
+  onAdd,
+  addLabel = "Panel",
+  addIcon,
+  sound = true,
+  className,
+  children,
+  ...rest
+}: ScaffoldActionsProps): React.ReactElement {
+  const { inspectorOpen, inspectorWidth } = useScaffoldContext()
+  const reducedMotion = useReducedMotion()
+  const transition = reducedMotion ? { duration: 0 } : SPRING_LAYOUT
+
+  return (
+    <motion.div
+      id="scaffold-actions"
+      animate={{
+        x: inspectorOpen ? -(inspectorWidth + SCAFFOLD_EDGE_GUTTER) : 0,
+      }}
+      className={cn(
+        "sticky inline-flex h-12 items-center gap-0.5",
+        "justify-end",
+        className
+      )}
+      data-slot="scaffold-actions"
+      initial={false}
+      transition={{
+        duration: reducedMotion ? 0 : SCAFFOLD_MORPH_DURATION,
+        ease: SCAFFOLD_EASE,
+      }}
+      {...rest}
+    >
+      <motion.div
+        layout
+        transition={transition}
+        className="flex items-center gap-1.5"
+      >
+        <AnimatePresence mode="popLayout" initial={false}>
+          {onAdd && (
+            <motion.div
+              key="scaffold-add"
+              layout
+              animate={reducedMotion ? { opacity: 1 } : "visible"}
+              className="flex shrink-0"
+              exit={reducedMotion ? { opacity: 0 } : "exit"}
+              initial={reducedMotion ? { opacity: 0 } : "hidden"}
+              transition={transition}
+              variants={segmentVariants}
+            >
+              <Button
+                onClick={onAdd}
+                size="sm"
+                sound={sound}
+                variant="ghost"
+                className="h-full gap-2 rounded-sm py-1.5 pr-3 pl-2"
+              >
+                {addIcon ?? <LucidePlus className="stroke-2" />}
+                {addLabel}
+              </Button>
+            </motion.div>
+          )}
+          {children}
+        </AnimatePresence>
+      </motion.div>
+    </motion.div>
+  )
+}

package/src/components/blocks/scaffold/scaffold-canvas.tsx

@@ -0,0 +1,29 @@
+"use client"
+
+import { AnimatePresence } from "motion/react"
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import type { ScaffoldCanvasProps } from "./type"
+
+/**
+ * The panel row below the action cluster: 8px gutters, 8px gaps, panels
+ * side by side. Key each `Scaffold.Panel` child so closes animate out.
+ */
+export function ScaffoldCanvas({
+  className,
+  children,
+  ...rest
+}: ScaffoldCanvasProps): React.ReactElement {
+  return (
+    <div
+      className={cn("relative flex w-full flex-1 gap-2", className)}
+      data-slot="scaffold-canvas"
+      {...rest}
+    >
+      <AnimatePresence initial={false} mode="popLayout">
+        {children}
+      </AnimatePresence>
+    </div>
+  )
+}

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

@@ -0,0 +1,18 @@
+"use client"
+
+import * as React from "react"
+
+import type { ScaffoldContextValue } from "./type"
+
+export const ScaffoldContext = React.createContext<ScaffoldContextValue | null>(
+  null
+)
+
+/** Read the scaffold's shared state; must run under `Scaffold.Root`. */
+export function useScaffoldContext(): ScaffoldContextValue {
+  const context = React.useContext(ScaffoldContext)
+  if (!context) {
+    throw new Error("useScaffoldContext must be used within <Scaffold.Root>")
+  }
+  return context
+}

package/src/components/blocks/scaffold/scaffold-inspector.tsx

@@ -0,0 +1,80 @@
+"use client"
+
+import { motion, useReducedMotion } from "motion/react"
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { SCAFFOLD_EASE, SCAFFOLD_EDGE_GUTTER, SCAFFOLD_MORPH_DURATION } from "./constants"
+import { useScaffoldContext } from "./scaffold-context"
+import type { ScaffoldInspectorProps } from "./type"
+import { GlassContainer } from "@/components/ui/glasscn/glass-container.tsx"
+import { Button } from "@/components/ui/button"
+import { LucideX } from "lucide-react"
+
+/**
+ * The right-hand drawer: a brighter card that slides in over the canvas,
+ * inset from the viewport edges. Open state lives on `Scaffold.Root` (or
+ * `useScaffold().providerProps`); the drawer stays mounted so it can slide
+ * back out.
+ */
+export function ScaffoldInspector({
+  children,
+  name = "Inspector",
+  className,
+  ...rest
+}: ScaffoldInspectorProps): React.ReactElement {
+  const { inspectorOpen, inspectorWidth, toggleInspector } =
+    useScaffoldContext()
+  const reducedMotion = useReducedMotion()
+
+  // Slide fully past the edge gutter and the drop shadow's blur radius.
+  const offcanvasX = inspectorWidth + SCAFFOLD_EDGE_GUTTER + 12
+
+  return (
+    <motion.aside
+      id="scaffold-inspector"
+      animate={{ x: inspectorOpen ? 0 : offcanvasX }}
+      aria-hidden={inspectorOpen ? undefined : true}
+      aria-label={name}
+      className={cn(
+        "absolute right-0 z-20 my-2 flex h-full max-h-[calc(100%-0.5rem)] w-96 flex-col",
+        !inspectorOpen && "pointer-events-none",
+        className
+      )}
+      data-slot="scaffold-inspector"
+      inert={inspectorOpen ? undefined : true}
+      initial={false}
+      role="complementary"
+      style={{ width: inspectorWidth }}
+      transition={{
+        duration: reducedMotion ? 0 : SCAFFOLD_MORPH_DURATION,
+        ease: SCAFFOLD_EASE,
+      }}
+      {...rest}
+    >
+      <GlassContainer
+        className="flex flex-1 flex-col rounded-md border-t border-white bg-neutral-50/10 shadow-inner shadow-md dark:border-neutral-800 dark:bg-black/5"
+        glassVariant="subtle"
+      >
+        <div
+          id="scaffold-inspector-header"
+          className="flex h-12 items-center justify-between gap-2 border-b pr-3 pl-4"
+        >
+          <span className="text-base font-normal text-card-foreground/70">
+            {name}
+          </span>
+          <Button
+            size="icon-xs"
+            variant="secondary"
+            className="scale-85"
+            aria-label="Close inspector"
+            onClick={toggleInspector}
+          >
+            <LucideX className="stroke-3" />
+          </Button>
+        </div>
+        {children}
+      </GlassContainer>
+    </motion.aside>
+  )
+}

package/src/components/blocks/scaffold/scaffold-main.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import type { ScaffoldMainProps } from "./type"
+
+/**
+ * The region right of the rail. Hosts `Scaffold.Actions` (top-right),
+ * `Scaffold.Canvas` and the `Scaffold.Inspector` overlay — all positioned
+ * against this box.
+ */
+export function ScaffoldMain({
+  className,
+  children,
+  ...rest
+}: ScaffoldMainProps): React.ReactElement {
+  return (
+    <div
+      id="scaffold-main"
+      className={cn("relative flex h-full min-w-0 flex-1 flex-col", className)}
+      data-slot="scaffold-main"
+      {...rest}
+    >
+      {children}
+    </div>
+  )
+}

package/src/components/blocks/scaffold/scaffold-panel.tsx

@@ -0,0 +1,88 @@
+"use client"
+
+import { motion, useReducedMotion } from "motion/react"
+import * as React from "react"
+import { useState } from "react"
+
+import { cn } from "@/lib/utils"
+import { SCAFFOLD_EASE, SCAFFOLD_MORPH_DURATION } from "./constants"
+import { PanelMenuButton } from "./panel-menu-button.tsx"
+import type { ScaffoldPanelProps, TSubPanelPosition } from "./type"
+import { ScaffoldSubPanel } from "@/components/blocks/scaffold/scaffold-sub-panel.tsx"
+
+/**
+ * A canvas panel: a primary card plus an optional secondary strip below it,
+ * separated by a slice of the desktop backdrop. Floating close and swap
+ * buttons reveal on hover when their callbacks are provided. Swapping trades
+ * the two cards with a layout morph — the strip glides up and grows into the
+ * primary slot while the primary card shrinks down into the strip.
+ */
+export function ScaffoldPanel({
+  children,
+  SecondaryPanel,
+  onSwap,
+  onCloseSecondary,
+  name,
+  swapLabel = "Swap panel content",
+  sound = true,
+  className,
+}: ScaffoldPanelProps): React.ReactElement {
+  const reducedMotion = useReducedMotion()
+
+  const transition = {
+    duration: reducedMotion ? 0 : SCAFFOLD_MORPH_DURATION,
+    ease: SCAFFOLD_EASE,
+  }
+
+  const [subPanelPosition, setSubPanelPosition] =
+    useState<TSubPanelPosition>("top")
+  const [isSwapped, setIsSwapped] = useState<boolean>(false)
+  const handleSwap = () => {
+    setIsSwapped((prev) => !prev)
+    onSwap?.()
+  }
+
+  // Trades which sub-panel holds the flexible slot — the collapsed card grows
+  // into `flex-1` while the expanded one shrinks to the `min-h-14` strip.
+  const handleExpand = () => {
+    setSubPanelPosition((prev) => (prev === "top" ? "bottom" : "top"))
+  }
+
+  return (
+    <motion.section
+      id="scaffold-panel"
+      animate={{ flexDirection: isSwapped ? "column-reverse" : "column" }}
+      aria-label={name}
+      className={cn(
+        "group/panel relative flex min-w-80 flex-1 flex-col",
+        className
+      )}
+      layout
+      data-slot="scaffold-panel"
+      data-swapped={isSwapped ? "" : undefined}
+      transition={transition}
+    >
+      <ScaffoldSubPanel id="top" expanded={subPanelPosition === "top"} primary>
+        {children}
+      </ScaffoldSubPanel>
+      {(onSwap || onCloseSecondary) && SecondaryPanel && (
+        <div className="relative flex h-2 items-center justify-center">
+          <PanelMenuButton
+            label={swapLabel}
+            onClick={handleSwap}
+            onExpand={handleExpand}
+            onCloseSecondary={onCloseSecondary}
+            secondaryExpanded={subPanelPosition === "bottom"}
+            swapped={isSwapped}
+            sound={sound}
+          />
+        </div>
+      )}
+      {SecondaryPanel && (
+        <ScaffoldSubPanel id="bottom" expanded={subPanelPosition === "bottom"}>
+          {SecondaryPanel}
+        </ScaffoldSubPanel>
+      )}
+    </motion.section>
+  )
+}

package/src/components/blocks/scaffold/scaffold-root.tsx

@@ -0,0 +1,68 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { SCAFFOLD_INSPECTOR_WIDTH } from "./constants"
+import { ScaffoldContext } from "./scaffold-context"
+import type { ScaffoldContextValue, ScaffoldRootProps } from "./type"
+import type { ClassNameValue } from "tailwind-merge"
+
+/**
+ * The scaffold's viewport: desktop backdrop + horizontal row of rail and
+ * main region, and the provider for the shared inspector state. Fills its
+ * container — size it from the outside (e.g. `h-svh` for a full page).
+ */
+export function ScaffoldRoot({
+  inspectorOpen: inspectorOpenProp,
+  defaultInspectorOpen,
+  onInspectorOpenChange,
+  inspectorWidth = SCAFFOLD_INSPECTOR_WIDTH,
+  className,
+  children,
+  ...rest
+}: ScaffoldRootProps): React.ReactElement {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(
+    defaultInspectorOpen ?? false
+  )
+  const inspectorOpen = inspectorOpenProp ?? uncontrolledOpen
+  const background: ClassNameValue = `bg-linear-to-tr/increasing from-neutral-200 via-neutral-100 to-stone-200 dark:from-neutral-900 dark:via-neutral-950 dark:to-stone-950`
+
+  const setInspectorOpen = React.useCallback(
+    (open: boolean) => {
+      if (inspectorOpenProp === undefined) setUncontrolledOpen(open)
+      onInspectorOpenChange?.(open)
+    },
+    [inspectorOpenProp, onInspectorOpenChange]
+  )
+
+  const toggleInspector = React.useCallback(
+    () => setInspectorOpen(!inspectorOpen),
+    [inspectorOpen, setInspectorOpen]
+  )
+
+  const value = React.useMemo<ScaffoldContextValue>(
+    () => ({ inspectorOpen, inspectorWidth, setInspectorOpen, toggleInspector }),
+    [inspectorOpen, inspectorWidth, setInspectorOpen, toggleInspector]
+  )
+
+  return (
+    <ScaffoldContext.Provider value={value}>
+      <div
+        id={"scaffold-root"}
+        className={cn(
+          // `clip`, not `hidden`: the off canvas inspector extends the
+          // scrollable overflow, and focus/scrollIntoView would scroll a
+          // hidden-overflow root sideways to reveal it.
+          "relative isolate flex h-full w-full flex-1 overflow-clip pr-2 pb-2",
+          background,
+          className
+        )}
+        data-slot="scaffold"
+        {...rest}
+      >
+        {children}
+      </div>
+    </ScaffoldContext.Provider>
+  )
+}

package/src/components/blocks/scaffold/scaffold-sidebar.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import type { ScaffoldSidebarProps } from "./type"
+
+/**
+ * The 64px icon rail on the left edge. Transparent — it sits directly on
+ * the desktop backdrop; fill it with icon buttons.
+ */
+export function ScaffoldSidebar({
+  className,
+  children,
+  ...rest
+}: ScaffoldSidebarProps): React.ReactElement {
+  return (
+    <nav
+      id="scaffold-sidebar"
+      aria-label="Primary"
+      className={cn(
+        "flex min-w-12 shrink-0 flex-col items-center gap-1 pt-10 pb-2",
+        className
+      )}
+      data-slot="scaffold-sidebar"
+      {...rest}
+    >
+      {children}
+    </nav>
+  )
+}