@exegia/corpora-ui 0.17.0 → 0.18.0

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

@@ -0,0 +1,97 @@
+"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 { ScaffoldActionsProps } from "./type"
+import { actionSegmentClass } from "./utils"
+import { GroupSeparator } from "@/components/ui/group"
+import { GlassButtonGroup } from "@/components/ui/glasscn/glass-button-group"
+import { Button } from "@/components/ui/button";
+import { LucidePlus } from "lucide-react"
+
+/**
+ * The floating pill cluster in the main region's top-right corner — the
+ * design's "Panel Context Menu": an Add segment plus an overflow segment
+ * whose badge counts the non-visible panels. Slides left in step with the
+ * inspector opening.
+ */
+export function ScaffoldActions({
+  onAdd,
+  addLabel = "Panel",
+  addIcon,
+  overflowCount,
+  onBrowse,
+  browseLabel = "Browse panels",
+  sound = true,
+  className,
+  children,
+  ...rest
+}: ScaffoldActionsProps): React.ReactElement {
+  const { inspectorOpen, inspectorWidth } = useScaffoldContext()
+  const reducedMotion = useReducedMotion()
+
+  const soundProps = {
+    "data-cuelume-press": sound ? "" : undefined,
+    "data-cuelume-release": sound ? "" : undefined,
+  }
+  const showBrowse = overflowCount !== undefined || onBrowse !== undefined
+
+  return (
+    <motion.div
+      id="scaffold-actions"
+      animate={{
+        x: inspectorOpen ? -(inspectorWidth + SCAFFOLD_EDGE_GUTTER) : 0,
+      }}
+      className={cn(
+        "sticky inline-flex items-center gap-0.5 h-12",
+        "justify-end",
+        className
+      )}
+      data-slot="scaffold-actions"
+      initial={false}
+      transition={{
+        duration: reducedMotion ? 0 : SCAFFOLD_MORPH_DURATION,
+        ease: SCAFFOLD_EASE,
+      }}
+      {...rest}
+    >
+      {children}
+      <GlassButtonGroup glassVariant="liquid-refract" className="rounded-md">
+        <Button
+          onClick={onAdd}
+          size="sm"
+          variant="ghost"
+        >
+          {addIcon ?? <LucidePlus className="stroke-3" />}
+          {addLabel}
+        </Button>
+        {!showBrowse && <GroupSeparator />}
+        {showBrowse && (
+            <button
+              aria-label={browseLabel}
+              className={cn(actionSegmentClass, "gap-0.5 px-2")}
+              onClick={onBrowse}
+              type="button"
+              {...soundProps}
+            >
+              <span className="relative">
+
+                {overflowCount !== undefined && overflowCount > 0 && (
+                  <span className="absolute -top-1.5 -right-1.5 flex size-3.5 items-center justify-center rounded-full bg-neutral-700 text-[9px] font-semibold text-white dark:bg-neutral-200 dark:text-neutral-900">
+                    {overflowCount}
+                  </span>
+                )}
+              </span>
+
+            </button>
+        )}
+
+        {children}
+      </GlassButtonGroup>
+    </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,57 @@
+"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"
+
+/**
+ * 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 } = 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 w-80 z-20 my-2 flex h-full max-h-[calc(100%-1rem)] 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-col shadow-inner shadow-md rounded-md flex-1 border-t border-white dark:border-neutral-900 bg-neutral-50/10 dark:bg-black/10" glassVariant="subtle">
+        {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,98 @@
+"use client"
+
+import { motion, useReducedMotion } from "motion/react"
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { SCAFFOLD_EASE, SCAFFOLD_MORPH_DURATION } from "./constants"
+import { PanelCloseButton } from "./panel-close-button"
+import { PanelMenuButton } from "./panel-menu-button.tsx"
+import type { ScaffoldPanelProps, TSubPanelPosition } from "./type"
+import { ScaffoldSubPanel } from "@/components/blocks/scaffold/scaffold-sub-panel.tsx"
+import { useState } from "react"
+
+/**
+ * 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,
+  onClose,
+  onSwap,
+  name,
+  closeLabel = "Close panel",
+  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 && SecondaryPanel && (
+        <div className="relative flex items-center justify-center h-2">
+          <PanelMenuButton
+            label={swapLabel}
+            onClick={handleSwap}
+            onExpand={handleExpand}
+            secondaryExpanded={subPanelPosition === "bottom"}
+            sound={sound}
+          />
+        </div>
+      )}
+      {SecondaryPanel && (
+        <ScaffoldSubPanel
+          id="bottom"
+          expanded={subPanelPosition === "bottom"}
+        >
+          {SecondaryPanel}
+        </ScaffoldSubPanel>
+      )}
+      {onClose && (
+        <PanelCloseButton label={closeLabel} onClick={onClose} sound={sound} />
+      )}
+    </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-20 shrink-0 flex-col items-center gap-1 pt-8 pb-2",
+        className
+      )}
+      data-slot="scaffold-sidebar"
+      {...rest}
+    >
+      {children}
+    </nav>
+  )
+}

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/type.ts

@@ -0,0 +1,171 @@
+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. */
+  onAdd?: () => void
+  /** Label of the Add segment. */
+  addLabel?: ReactNode
+  /** Replaces the default add icon. */
+  addIcon?: ReactNode
+  /** Number of non-visible panels tucked into the overflow dropdown —
+   * the badge on the browse segment. The segment renders when this or
+   * `onBrowse` is present; the badge only when > 0. Per the design
+   * comments the dropdown menu itself is a later iteration; for now the
+   * segment just keeps the count. */
+  overflowCount?: number
+  /** Called when the overflow (stacked-panels) segment is pressed. */
+  onBrowse?: () => void
+  /** Accessible name of the overflow segment. */
+  browseLabel?: string
+  /** Extra segments appended after the built-in ones. */
+  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
+  /** Renders the floating close button in the panel's top-right corner. */
+  onClose?: () => void
+  /** Renders the floating swap button over the primary/secondary gap.
+   * Only shown when `secondary` is present. Clicking it 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
+  /** Controlled swap state — while true the strip's card sits in the
+   * primary slot. Omit letting the panel toggle it on swap clicks. */
+  swapped?: boolean
+  /** Initial swap state when uncontrolled. */
+  defaultSwapped?: boolean
+  /** Fixed width in px; omitted, the panel flexes to share the canvas. */
+  width?: number
+  /** Accessible name of the panel region. */
+  name?: string
+  /** Emit interaction-sound attributes on the floating buttons. */
+  sound?: boolean
+  /** Accessible name of the close button. */
+  closeLabel?: string
+  /** Accessible name of the swap button. */
+  swapLabel?: string
+  /** Extra class names for the panel's root element. */
+  className?: string
+}
+
+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
+  /** Whether the secondary strip currently holds the flexible slot —
+   * flips the Expand chevron between down and up. */
+  secondaryExpanded?: 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"
+  >
+}