@exegia/corpora-ui 0.20.0 → 0.22.0

package/src/components/blocks/shell/use-shell-fit-state.ts

@@ -0,0 +1,49 @@
+"use client"
+
+import { useMemo } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitStateAtom,
+} from "./shell-fit-atom"
+import type { ShellFitActions, ShellFitInstanceId, ShellFitState } from "./type"
+
+/**
+ * Read the fit of the shell registered under `shellId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { fits, panelWidth } = useShellFitState("app-shell")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on every
+ * measurement. A component that reads one field should subscribe to that
+ * field's atom instead: `useAtomValue(shellFitFitsAtom("app-shell"))`.
+ */
+export function useShellFitState(shellId: ShellFitInstanceId): ShellFitState {
+  return useAtomValue(shellFitStateAtom(shellId))
+}
+
+/**
+ * Drive the secondary panel of the shell registered under `shellId` from
+ * anywhere. Writes only — the caller never re-renders when the shell moves,
+ * so this is what a command palette or a keyboard shortcut should reach for.
+ *
+ * ```tsx
+ * const shell = useShellFitActions("app-shell")
+ * <Button onClick={() => shell.resizePanel(480)}>Wide inspector</Button>
+ * ```
+ */
+export function useShellFitActions(
+  shellId: ShellFitInstanceId
+): ShellFitActions {
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+  const resetPanelWidth = useSetAtom(resetShellPanelWidthAtom(shellId))
+
+  return useMemo(
+    () => ({ resizePanel, resetPanelWidth }),
+    [resizePanel, resetPanelWidth]
+  )
+}

package/src/components/blocks/shell/use-shell-fit.ts

@@ -0,0 +1,135 @@
+"use client"
+
+import { useEffect, useId, useMemo, useRef, useState } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+import { useIsomorphicLayoutEffect } from "motion/react"
+
+import {
+  measureShellFitAtom,
+  mountShellFitAtom,
+  removeShellFitInstance,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitStateAtom,
+} from "./shell-fit-atom"
+import { fitsPanel, type ShellMetrics } from "./shell-metrics"
+import type {
+  ShellFitController,
+  ShellFitSeed,
+  UseShellFitOptions,
+} from "./type"
+import { resolveLength } from "./utils"
+
+/** Read the shell's columns out of the DOM. The widths come from CSS
+ * variables; the rail's share comes from its own state, not its box, so a
+ * fold counts the moment React commits it rather than a frame later when the
+ * width animation has moved. */
+function readMetrics(host: HTMLElement, railOpen: boolean): ShellMetrics {
+  // Whether a shell has a rail at all is the caller's composition, so it is
+  // read off the DOM rather than tracked in state.
+  const rail = host.querySelector<HTMLElement>(
+    '[data-slot="sidebar"][data-side="left"]'
+  )
+  const collapsible = rail?.dataset.collapsible
+
+  const frame = getComputedStyle(host)
+  const gap = Number.parseFloat(frame.columnGap) || 0
+
+  return {
+    rail: !rail
+      ? 0
+      : railOpen || collapsible === "none"
+        ? resolveLength(host, "var(--sidebar-width)")
+        : collapsible === "offcanvas"
+          ? 0
+          : resolveLength(host, "var(--sidebar-width-icon)"),
+    insetMin: resolveLength(host, "var(--inset-min-width)"),
+    panelMin: resolveLength(host, "var(--panel-width)"),
+    viewport: window.innerWidth,
+    chrome:
+      (Number.parseFloat(frame.paddingLeft) || 0) +
+      (Number.parseFloat(frame.paddingRight) || 0) +
+      gap * Math.max(0, host.children.length - 1),
+  }
+}
+
+/**
+ * Measures the shell and decides what the secondary panel may do: whether it
+ * exists at all, and how wide it may be dragged.
+ *
+ * The three things that move the answer are all observed here — the viewport
+ * (`resize`), the rail's fold (`railOpen`, a render input) and the user's own
+ * drag (`resizePanel`) — so no caller has to re-derive it. The measurement is
+ * the only thing this hook keeps to itself: the numbers land in the shell-fit
+ * atoms keyed by `shellId`, so anything under `ExegiaProvider` can read the
+ * verdict (`useShellFitState`) or move the panel (`useShellFitActions`)
+ * without holding this controller.
+ */
+export function useShellFit({
+  shellId: explicitId,
+  hostRef,
+  railOpen,
+  defaultPanelWidth,
+  onUnfit,
+}: UseShellFitOptions): ShellFitController {
+  // A generated key isolates unnamed shells from each other; an explicit
+  // `shellId` is the app's handle on this one.
+  const generatedId = useId()
+  const shellId = explicitId ?? generatedId
+
+  // Read once: `defaultPanelWidth` describes the mount, not every render.
+  const [seed] = useState<ShellFitSeed>(() => ({
+    panelWidth: defaultPanelWidth ?? null,
+  }))
+
+  const mount = useSetAtom(mountShellFitAtom(shellId))
+  const measure = useSetAtom(measureShellFitAtom(shellId))
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+  const resetPanelWidth = useSetAtom(resetShellPanelWidthAtom(shellId))
+
+  // Before paint, and before the first measurement below, so a seeded width
+  // is in the store by the time the panel first reads its width.
+  useIsomorphicLayoutEffect(() => {
+    mount(seed)
+  }, [mount, seed])
+
+  // The listener below is bound once per fold, so the callback rides a ref
+  // rather than rebinding it whenever a consumer passes a fresh arrow.
+  const onUnfitRef = useRef(onUnfit)
+  useIsomorphicLayoutEffect(() => {
+    onUnfitRef.current = onUnfit
+  })
+
+  useIsomorphicLayoutEffect(() => {
+    const host = hostRef.current
+    if (!host) return
+
+    const takeMeasurement = () => {
+      const next = readMetrics(host, railOpen)
+      measure(next)
+      if (!fitsPanel(next)) onUnfitRef.current?.()
+    }
+
+    // Measured before paint so a shell that cannot hold the panel never
+    // flashes one, and re-measured on every fold because the rail's column is
+    // part of the room the panel needs.
+    takeMeasurement()
+    window.addEventListener("resize", takeMeasurement)
+    return () => window.removeEventListener("resize", takeMeasurement)
+  }, [hostRef, railOpen, measure])
+
+  // A shell the hook keyed is scrap once its component goes. An explicit
+  // `shellId` is the app's key and outlives the mount — that is what lets a
+  // dragged width survive a route change.
+  useEffect(() => {
+    if (explicitId !== undefined) return
+    return () => removeShellFitInstance(shellId)
+  }, [shellId, explicitId])
+
+  const state = useAtomValue(shellFitStateAtom(shellId))
+
+  return useMemo<ShellFitController>(
+    () => ({ shellId, ...state, resizePanel, resetPanelWidth }),
+    [shellId, state, resizePanel, resetPanelWidth]
+  )
+}

package/src/components/blocks/shell/use-shell-panels.ts

@@ -1,7 +1,14 @@
 "use client"
 
-import { useCallback, useMemo, useState } from "react"
+import { useCallback, useEffect, useId, useMemo, useState } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
+import {
+  removeShellFitInstance,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitPanelWidthAtom,
+} from "./shell-fit-atom"
 import type {
   ShellPanelControlProps,
   ShellPanelControls,
@@ -15,12 +22,36 @@ import type {
  * callback. Spread the returned `providerProps` onto ShellLayout; the
  * setters and `toggle` are for UI that lives outside the shell (title-bar
  * buttons, command palette, shortcuts).
+ *
+ * The way back down is the store: `providerProps` carries a `shellId`, the
+ * shell files its measurement under it, and this hook reads `isNarrow` and
+ * `panelWidth` straight out of those atoms — so outside UI stands down with
+ * the panel instead of measuring `--sidebar-width` a second time. Name the
+ * `shellId` and any component below `ExegiaProvider` can do the same with
+ * `useShellFitState(shellId)`.
+ *
+ * Call it under the same `ExegiaProvider` as the shell it drives (or under
+ * none at all, on both sides): mounted above the provider it would read
+ * Jotai's default store while the shell writes to the provider's.
  */
 export function useShellPanels({
+  shellId: explicitId,
   defaultOpen,
   defaultOpenMobile,
+  defaultPanelWidth,
   onPanelChange,
 }: UseShellPanelsOptions = {}): ShellPanelControls {
+  // The hook, not the provider, keys the shell: it renders above the provider
+  // and has to read the same atoms the provider writes. Whoever generates the
+  // key drops it — the provider treats a passed-in id as the app's and leaves
+  // it alone on unmount.
+  const generatedId = useId()
+  const shellId = explicitId ?? generatedId
+  useEffect(() => {
+    if (explicitId !== undefined) return
+    return () => removeShellFitInstance(shellId)
+  }, [shellId, explicitId])
+
   const [open, setOpenState] = useState<Record<SidebarSide, boolean>>(() => ({
     left: defaultOpen?.left ?? true,
     right: defaultOpen?.right ?? false,
@@ -32,24 +63,40 @@ export function useShellPanels({
     right: defaultOpenMobile?.right ?? false,
   }))
 
+  // Reads false until the shell has measured itself — an unmeasured shell
+  // fails open, so nothing out here stands down over a reading that has not
+  // happened yet.
+  const fits = useAtomValue(shellFitFitsAtom(shellId))
+  const isNarrow = !fits
+  const panelWidth = useAtomValue(shellFitPanelWidthAtom(shellId))
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+
+  // The shell drops the right panel when the viewport cannot hold it, so
+  // opening it from out here would only surface later as a panel nobody
+  // asked for. Closing always goes through — that is how state left over
+  // from a wider viewport clears.
   const setOpen = useCallback(
     (nextOpen: boolean, side: SidebarSide) => {
+      if (nextOpen && side === "right" && isNarrow) return
+
       setOpenState((prev) =>
         prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
       )
       onPanelChange?.(nextOpen, side)
     },
-    [onPanelChange]
+    [isNarrow, onPanelChange]
   )
 
   const setOpenMobile = useCallback(
     (nextOpen: boolean, side: SidebarSide) => {
+      if (nextOpen && side === "right" && isNarrow) return
+
       setOpenMobileState((prev) =>
         prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
       )
       onPanelChange?.(nextOpen, side)
     },
-    [onPanelChange]
+    [isNarrow, onPanelChange]
   )
 
   const toggle = useCallback(
@@ -59,15 +106,21 @@ export function useShellPanels({
 
   const providerProps = useMemo<ShellPanelControlProps>(
     () => ({
+      shellId,
+      defaultPanelWidth,
       open,
       onOpenChange: setOpen,
       openMobile,
       onOpenMobileChange: setOpenMobile,
     }),
-    [open, openMobile, setOpen, setOpenMobile]
+    [shellId, defaultPanelWidth, open, openMobile, setOpen, setOpenMobile]
   )
 
   return {
+    shellId,
+    isNarrow,
+    panelWidth,
+    resizePanel,
     open,
     openMobile,
     setOpen,

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

@@ -92,6 +92,49 @@ export const FOCUSABLE_SELECTOR = [
 export const MOBILE_QUERY = "(max-width: 767px)"
 export const SIDEBAR_KEYBOARD_SHORTCUT = "b"
 
+/**
+ * The shell's layout contract, in px. Every entry lands on the provider's
+ * wrapper as a CSS variable, so a consumer overrides a column by restyling it
+ * rather than by passing a prop:
+ *
+ * | variable               | column                                    |
+ * | ---------------------- | ----------------------------------------- |
+ * | `--sidebar-width`      | left rail, expanded                       |
+ * | `--sidebar-width-icon` | left rail, folded to icons                |
+ * | `--panel-width`        | secondary panel: its floor AND its default |
+ * | `--inset-min-width`    | the body's floor                          |
+ *
+ * These are only the defaults. Every measurement resolves the live variable,
+ * so an override wins over the value written here.
+ */
+export const SHELL_WIDTHS = {
+  "--sidebar-width": "256px",
+  "--sidebar-width-icon": "56px",
+  "--sidebar-width-mobile": "18rem",
+  "--panel-width": "320px",
+  "--inset-min-width": "360px",
+} as const
+
+/** The expanded width of a panel docked to `side`: the secondary panel opens
+ * at `--panel-width`, the primary rail at `--sidebar-width`. */
+export function expandedWidthVar(side: "left" | "right") {
+  return side === "right" ? "var(--panel-width)" : "var(--sidebar-width)"
+}
+
+/** Resolve a CSS length — `var()` included — to px inside `host`'s cascade.
+ * Custom properties inherit, so a throwaway probe mounted in `host` reads the
+ * very `--sidebar-width` the shell lays out with, including a value a
+ * consumer overrode on the provider. Returns 0 when `host` has no layout
+ * (server render, `display: none`), so callers must fail open on 0 rather
+ * than treat it as a real measurement. */
+export function resolveLength(host: HTMLElement, value: string) {
+  const probe = document.createElement("div")
+  probe.style.cssText = `position:absolute;visibility:hidden;pointer-events:none;width:${value}`
+  host.appendChild(probe)
+  const px = probe.getBoundingClientRect().width
+  probe.remove()
+  return px
+}
 
 export const AnimatedSidebarContext =
   createContext<AnimatedSidebarContextValue | null>(null)
@@ -131,13 +174,10 @@ export function useIsMobile() {
   )
 }
 
-
 export function useAnimatedSidebarPanel() {
   const context = useContext(AnimatedSidebarPanelContext)
   if (!context) {
-    throw new Error(
-      "Animated Sidebar parts must be used inside AnimatedPanel."
-    )
+    throw new Error("Animated Sidebar parts must be used inside AnimatedPanel.")
   }
   return context
 }

package/src/components/composed/__tests__/logo.test.tsx

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+
+import { Logo } from "../logo"
+
+const root = () => document.querySelector<HTMLElement>('[data-slot="logo"]')
+const wordmark = () =>
+  document.querySelector<HTMLElement>('[data-slot="logo-wordmark"]')
+const monogram = () =>
+  document.querySelector<HTMLElement>('[data-slot="logo-monogram"]')
+
+describe("Logo", () => {
+  test("defaults: monogram tile from the name, name as the wordmark", () => {
+    render(<Logo name="Corpora Codex" />)
+    expect(monogram()?.textContent).toBe("CC")
+    expect(wordmark()?.textContent).toBe("Corpora Codex")
+    expect(root()?.tagName).toBe("SPAN")
+    expect(root()?.getAttribute("data-variant")).toBe("full")
+  })
+
+  test("a custom mark wins over src; src renders a decorative image", () => {
+    const { rerender } = render(
+      <Logo name="Corpora" src="https://example.com/mark.png" />
+    )
+    expect(monogram()).toBeNull()
+    expect(document.querySelector("img")?.getAttribute("alt")).toBe("")
+    rerender(
+      <Logo
+        name="Corpora"
+        src="https://example.com/mark.png"
+        mark={<svg data-testid="mark" />}
+      />
+    )
+    expect(document.querySelector("img")).toBeNull()
+    expect(screen.getByTestId("mark")).toBeTruthy()
+  })
+
+  test("href renders a link named for AT regardless of variant", () => {
+    render(<Logo name="Corpora" href="/" variant="mark" />)
+    const link = screen.getByRole("link", { name: "Corpora" })
+    expect(link.getAttribute("href")).toBe("/")
+    expect(link.getAttribute("data-slot")).toBe("logo")
+  })
+
+  test("variant=mark folds the wordmark: hidden from AT, root keeps the name", () => {
+    const { rerender } = render(<Logo name="Corpora" variant="mark" />)
+    expect(wordmark()?.getAttribute("aria-hidden")).toBe("true")
+    expect(root()?.getAttribute("aria-label")).toBe("Corpora")
+    expect(root()?.getAttribute("data-variant")).toBe("mark")
+    // Unfolded, the visible wordmark is the name — no double label.
+    rerender(<Logo name="Corpora" variant="full" />)
+    expect(wordmark()?.getAttribute("aria-hidden")).toBeNull()
+    expect(root()?.getAttribute("aria-label")).toBeNull()
+  })
+
+  test("a custom wordmark replaces the name text", () => {
+    render(<Logo name="Corpora" wordmark={<span>corpora/ui</span>} />)
+    expect(wordmark()?.textContent).toBe("corpora/ui")
+  })
+})

package/src/components/composed/logo.tsx

@@ -0,0 +1,159 @@
+"use client"
+
+import * as React from "react"
+import { motion, useReducedMotion } from "motion/react"
+import type { Variants } from "motion/react"
+
+import { EASE_OUT } from "@/lib/ease.ts"
+import { cn } from "@/lib/utils"
+import { initialsFrom } from "@/components/user-avatar"
+
+/** `full` shows mark + wordmark; `mark` folds the wordmark away — an icon
+ * rail, a favicon-sized corner. */
+export type LogoVariant = "full" | "mark"
+
+export interface LogoProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+  /**
+   * Brand name. Labels the logo for AT (and the link, when `href` renders
+   * one), drives the default wordmark, and the monogram tile when no mark
+   * is given.
+   */
+  name: string
+  /** Custom mark — an inline SVG sized to fill its box. Wins over `src`. */
+  mark?: React.ReactNode
+  /** Image URL for the mark. Decorative — `name` labels the logo. */
+  src?: string
+  /** Wordmark content. Defaults to `name`. */
+  wordmark?: React.ReactNode
+  /** `full` (default) or `mark` — the wordmark folds away, animated. */
+  variant?: LogoVariant
+  /** Renders the logo as a link — the usual "mark goes home" affordance. */
+  href?: string
+}
+
+/** Wordmark fold/unfold — the same envelope the profile card's identity
+ * lines use, so a logo and a profile card folding in the same rail move as
+ * one. Kept local: composed components do not reach into blocks. Expressed
+ * as named variants for consistency with the profile card's fold envelope —
+ * house style for multi-property fold states, not a motion requirement. */
+const WORDMARK_VARIANTS: Variants = {
+  open: {
+    width: "auto",
+    opacity: 1,
+    x: 0,
+    transition: { duration: 0.2, delay: 0.08, ease: EASE_OUT },
+  },
+  folded: {
+    width: 0,
+    opacity: 0,
+    x: -4,
+    transition: { duration: 0.12, ease: EASE_OUT },
+  },
+}
+
+const WORDMARK_VARIANTS_REDUCED: Variants = {
+  open: { width: "auto", opacity: 1, x: 0, transition: { duration: 0.16, ease: EASE_OUT } },
+  folded: { width: 0, opacity: 0, x: 0, transition: { duration: 0.16, ease: EASE_OUT } },
+}
+
+/**
+ * Brand lockup: a mark beside a wordmark. The mark is whatever the brand
+ * has — an SVG (`mark`), an image (`src`), or, given neither, a monogram
+ * tile derived from `name`. `variant="mark"` folds the wordmark away with
+ * the same motion a collapsing rail uses, so the lockup can sit in one and
+ * follow its fold. With `href` the whole lockup is a link named by `name`.
+ *
+ * Sizing rides on the mark: it defaults to `size-8`; restyle via
+ * `[&_[data-slot=logo-mark]]:size-*` or wrap in a text-size context for the
+ * wordmark, which inherits.
+ */
+export function Logo({
+  name,
+  mark,
+  src,
+  wordmark,
+  variant = "full",
+  href,
+  className,
+  ...props
+}: LogoProps): React.ReactElement {
+  const reduce = useReducedMotion()
+  const folded = variant === "mark"
+
+  const markNode = mark ?? (
+    src !== undefined ? (
+      // Decorative: the root's `name` (visible wordmark or aria-label)
+      // already names the brand.
+      <img alt="" className="size-full object-contain" src={src} />
+    ) : (
+      <span
+        aria-hidden="true"
+        className="flex size-full items-center justify-center rounded-lg bg-foreground font-semibold text-background text-[45cqw]"
+        data-slot="logo-monogram"
+      >
+        {initialsFrom(name)}
+      </span>
+    )
+  )
+
+  const content = (
+    <>
+      <span
+        className="size-8 shrink-0 @container [&_svg]:size-full"
+        data-slot="logo-mark"
+      >
+        {markNode}
+      </span>
+      <motion.span
+        animate={folded ? "folded" : "open"}
+        variants={reduce ? WORDMARK_VARIANTS_REDUCED : WORDMARK_VARIANTS}
+        // Folded, the wordmark is gone for AT too — the root's label names
+        // the brand on its own.
+        aria-hidden={folded || undefined}
+        className={cn(
+          "min-w-0 overflow-hidden font-semibold whitespace-nowrap tracking-tight",
+          folded && "pointer-events-none",
+          // 0px wide while folded, but the flex gap before it would still
+          // offset the mark — pull it back by that gap.
+          folded && "-ml-2"
+        )}
+        data-slot="logo-wordmark"
+        initial={false}
+      >
+        {wordmark ?? name}
+      </motion.span>
+    </>
+  )
+
+  const rootClassName = cn(
+    "inline-flex shrink-0 items-center gap-2 text-foreground",
+    className
+  )
+
+  return href !== undefined ? (
+    <a
+      // Always labelled: the folded state hides the wordmark, and a link
+      // must not lose its name mid-animation.
+      aria-label={name}
+      className={rootClassName}
+      data-slot="logo"
+      data-variant={variant}
+      href={href}
+      {...props}
+    >
+      {content}
+    </a>
+  ) : (
+    <span
+      aria-label={folded ? name : undefined}
+      className={rootClassName}
+      data-slot="logo"
+      data-variant={variant}
+      role={folded ? "img" : undefined}
+      {...props}
+    >
+      {content}
+    </span>
+  )
+}