@exegia/corpora-ui 0.17.0 → 0.19.0

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

@@ -0,0 +1,51 @@
+
+import * as React from "react"
+import { motion, useReducedMotion } from "framer-motion"
+import { cn } from "@/lib/utils"
+import type { ScaffoldSubPanelProps } from "./type"
+import { subPanelVariant } from "@/components/blocks/scaffold/utils.ts"
+import { SCAFFOLD_EASE, SCAFFOLD_MORPH_DURATION } from "./constants"
+
+export function ScaffoldSubPanel({
+                                   className,
+                                   children,
+                                   variant = 'card',
+                                   primary = false,
+                                   expanded,
+                                   ...rest
+                                 }: ScaffoldSubPanelProps): React.ReactElement {
+  const reduce = useReducedMotion()
+  // The primary card holds the flexible slot unless the panel says otherwise.
+  const isExpanded = expanded ?? primary
+
+  return (
+    <motion.div
+      layout={"size"}
+      id={`scaffold-sub-panel-${variant}`}
+      // Grow is animated as a style, not a class flip — a class flip rides the
+      // layout FLIP, which scales both cards into a swap-like morph. Animating
+      // flex-grow slides only the shared boundary: the collapsed card grows up
+      // (or down) while the other is squeezed and cropped in place.
+      initial={false}
+      animate={{ flexGrow: isExpanded ? 1 : 0 }}
+      transition={
+        reduce
+          ? { duration: 0 }
+          : { duration: SCAFFOLD_MORPH_DURATION, ease: SCAFFOLD_EASE }
+      }
+      className={cn(
+        "flex w-full flex-col",
+        subPanelVariant[variant],
+        // basis-14 + clip let the primary squeeze down to the strip height;
+        // the strip keeps its natural (basis-auto) height when collapsed.
+        primary ? "basis-14 min-h-14 overflow-clip" : "basis-auto min-h-14",
+        className
+      )}
+      data-slot={`scaffold-sub-panel-${variant}`}
+      data-expanded={isExpanded ? "" : undefined}
+      {...rest}
+    >
+      {children}
+    </motion.div>
+  )
+}

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

@@ -0,0 +1,66 @@
+"use client"
+
+import { useReducedMotion } from "motion/react"
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { SPRING_LAYOUT } from "@/lib/ease.ts"
+import type { ScaffoldTabProps } from "./type"
+import { segmentVariants } from "./utils"
+import { Button } from "@/components/ui/button"
+import { LucideAppWindow, LucideX } from "lucide-react"
+import { GlassButtonGroup } from "@/components/ui/glasscn/glass-button-group.tsx"
+
+/**
+ * A panel's tab inside the action cluster: its label plus a close
+ * affordance. Render one per open panel as Actions children, keyed —
+ * closes animate out of the pill. Omit `onClose` on the last remaining
+ * panel's tab; the canvas keeps at least one panel open.
+ */
+export function ScaffoldTab({
+  children,
+  onClose,
+  closeLabel = "Close panel",
+  sound = true,
+  className,
+  ...rest
+}: ScaffoldTabProps): React.ReactElement {
+  const reduce = useReducedMotion()
+  const transition = reduce ? { duration: 0 } : SPRING_LAYOUT
+
+  return (
+    <GlassButtonGroup
+      layout
+      animate={reduce ? { opacity: 1 } : "visible"}
+      data-slot="scaffold-tab"
+      exit={reduce ? { opacity: 0 } : "exit"}
+      initial={reduce ? { opacity: 0 } : "hidden"}
+      transition={transition}
+      variants={segmentVariants}
+      glassVariant="subtle"
+      className={cn("h-full rounded-sm", className)}
+      {...rest}
+    >
+      <Button
+        size="sm"
+        variant="ghost"
+        className={cn("gap-2.5 rounded-sm pl-2", onClose && "pr-2")}
+      >
+        <LucideAppWindow size={16} />
+        {children}
+      </Button>
+      {onClose && (
+        <Button
+          aria-label={closeLabel}
+          onClick={onClose}
+          size="icon-sm"
+          sound={sound}
+          variant="ghost"
+          className="rounded-none!"
+        >
+          <LucideX size={16} />
+        </Button>
+      )}
+    </GlassButtonGroup>
+  )
+}

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

@@ -0,0 +1,172 @@
+import React, { type ComponentProps, type ReactElement, type ReactNode, } from "react"
+
+/** Inspector state shared by every scaffold part through ScaffoldContext. */
+export interface ScaffoldContextValue {
+  /** Whether the inspector drawer is currently shown. */
+  inspectorOpen: boolean
+  /** Drawer width in px — Actions reads it to slide out of the drawer's way. */
+  inspectorWidth: number
+  setInspectorOpen: (open: boolean) => void
+  toggleInspector: () => void
+}
+
+export interface ScaffoldRootProps extends ComponentProps<"div"> {
+  /** Controlled inspector state — pair with `onInspectorOpenChange`, or
+   * spread `useScaffold().providerProps` instead of wiring by hand. */
+  inspectorOpen?: boolean
+  /** Initial inspector state when uncontrolled. Closed by default. */
+  defaultInspectorOpen?: boolean
+  onInspectorOpenChange?: (open: boolean) => void
+  /** Drawer width in px. Also drives how far Actions slides aside. */
+  inspectorWidth?: number
+}
+
+export type ScaffoldSidebarProps = ComponentProps<"nav">
+
+export type ScaffoldMainProps = ComponentProps<"div">
+
+export type ScaffoldCanvasProps = ComponentProps<"div">
+
+/** React's drag/animation DOM handlers collide with motion's gesture props
+ * on `motion.*` elements — strip them from pass-through HTML props. */
+type MotionSafe<T> = Omit<
+  T,
+  | "onDrag"
+  | "onDragStart"
+  | "onDragEnd"
+  | "onAnimationStart"
+  | "onAnimationEnd"
+  | "onAnimationIteration"
+>
+
+export interface ScaffoldActionsProps extends MotionSafe<
+  Omit<ComponentProps<"div">, "children">
+> {
+  /** Called when the Add segment is pressed. The segment renders only
+   * while this is present — omit it to hide Add, e.g. once the canvas
+   * holds `SCAFFOLD_PANEL_CAPACITY` panels. */
+  onAdd?: () => void
+  /** Label of the Add segment. */
+  addLabel?: ReactNode
+  /** Replaces the default add icon. */
+  addIcon?: ReactNode
+  /** The panel tabs (`Scaffold.Tab`, one per open panel) and any extra
+   * segments, rendered before Add. Key each tab — closes animate out. */
+  children?: ReactNode
+  /** Emit interaction-sound attributes (inert until an app binds cuelume). */
+  sound?: boolean
+}
+
+export type TScaffoldPanelChild<
+  T extends ScaffoldSubPanelProps = ScaffoldSubPanelProps,
+> = ReactElement<T, React.JSXElementConstructor<T>>
+
+export interface ScaffoldPanelProps {
+  /** The panel's content, rendered in a card with a drop shadow. */
+  children: ReactNode
+  /** The panel's content, rendered in a card with a drop shadow. */
+  SecondaryPanel?: TScaffoldPanelChild
+  /** Reveals the Swap action in the seam menu (needs `SecondaryPanel`).
+   * Swapping trades the two cards with a layout morph — flip the slot
+   * content here so each card carries its subject to its new home. */
+  onSwap?: () => void
+  /** Reveals the Close action in the seam menu — remove `SecondaryPanel`
+   * here; the strip and the menu leave together. */
+  onCloseSecondary?: () => void
+  /** Accessible name of the panel region. */
+  name?: string
+  /** Emit interaction-sound attributes on the floating buttons. */
+  sound?: boolean
+  /** Accessible name of the seam-menu toggle. */
+  swapLabel?: string
+  /** Extra class names for the panel's root element. */
+  className?: string
+}
+
+export interface ScaffoldTabProps extends MotionSafe<
+  Omit<ComponentProps<"div">, "children">
+> {
+  /** The tab's label. */
+  children?: ReactNode
+  /** Renders the tab's close button. The button renders only while this
+   * is present — omit it to pin the tab, e.g. on the last remaining
+   * panel (the canvas keeps at least one open). */
+  onClose?: () => void
+  /** Accessible name of the close button. */
+  closeLabel?: string
+  /** Emit interaction-sound attributes on the close button. */
+  sound?: boolean
+}
+
+export type TSubPanelPosition = "bottom" | "top"
+export type TSubPanelVariant = "card" | "subtle" | "inset"
+
+export interface ScaffoldSubPanelProps extends MotionSafe<
+  Omit<ComponentProps<"div">, "children">
+> {
+  children?: ReactNode
+  /** Accessible name of the sub-panel region. */
+  name?: string
+  /** Whether this is the primary or secondary sub-panel. */
+  primary?: boolean
+  /** Whether this sub-panel holds the flexible slot. Defaults to `primary` —
+   * the panel flips it when the Expand action trades the slots. */
+  expanded?: boolean
+  /** Visual style of the sub-panel. */
+  variant?: TSubPanelVariant
+  /** Fixed width in px; omitted, the sub-panel flexes to share the canvas. */
+  width?: number
+  /** Emit interaction-sound attributes on the floating buttons. */
+  sound?: boolean
+  /** Extra class names for the sub-panel's root element. */
+  className?: string
+}
+
+export interface ScaffoldInspectorProps extends MotionSafe<
+  Omit<ComponentProps<"aside">, "children">
+> {
+  children?: ReactNode
+  /** Accessible name of the drawer region. */
+  name?: string
+}
+
+export interface PanelFloatingButtonProps {
+  onClick?: () => void
+  /** Accessible name — the button is icon-only. */
+  label: string
+  sound?: boolean
+  className?: string
+}
+
+export interface PanelMenuButtonProps extends PanelFloatingButtonProps {
+  /** Called when the Expand action is pressed — the panel trades which
+   * sub-panel holds the flexible slot. */
+  onExpand?: () => void
+  /** Renders the Close action; called when it is pressed — the consumer
+   * removes the secondary strip. */
+  onCloseSecondary?: () => void
+  /** Whether the secondary strip currently holds the flexible slot —
+   * flips the Expand chevron between down and up. */
+  secondaryExpanded?: boolean
+  /** Whether the panel is swapped (column-reverse). Mirrors the Expand
+   * chevron so it keeps pointing at the sub-panel that grows next. */
+  swapped?: boolean
+}
+
+export interface UseScaffoldOptions {
+  /** Initial inspector state. Closed by default. */
+  defaultInspectorOpen?: boolean
+  /** Fires on every inspector open/close. */
+  onInspectorChange?: (open: boolean) => void
+}
+
+export interface ScaffoldControls {
+  inspectorOpen: boolean
+  setInspectorOpen: (open: boolean) => void
+  toggleInspector: () => void
+  /** Spread onto Scaffold.Root. */
+  providerProps: Pick<
+    ScaffoldRootProps,
+    "inspectorOpen" | "onInspectorOpenChange"
+  >
+}

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,46 @@
+import type { Variants } from "motion/react"
+import type { ClassNameValue } from "tailwind-merge"
+import type { TSubPanelVariant } from "@/components/blocks/scaffold/type.ts"
+import { EASE_OUT } from "@/lib/ease.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"
+
+/** Pill segments (seam-menu actions, tabs, Add) blur/fade in place while
+ * the track morphs around them. The exit is a fast tween, not the layout
+ * spring — the track stays overflow-visible, so popped-out segments must be
+ * gone before the shrinking pill leaves them behind as a ghost. */
+export const segmentVariants: Variants = {
+  hidden: { opacity: 0, filter: "blur(4px)" },
+  visible: { opacity: 1, filter: "blur(0px)" },
+  exit: {
+    opacity: 0,
+    filter: "blur(4px)",
+    transition: { duration: 0.18, ease: EASE_OUT },
+  },
+}
+
+/** 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/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)
+      }}
+    />
+  )
+})