@exegia/corpora-ui 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {

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

@@ -114,6 +114,46 @@ describe("ShellLayout", () => {
     expect(rightDrawer("Inspector")).toBeDefined()
   })
 
+  test("trailing actions stay in the right cluster without a header", () => {
+    render(
+      <ShellLayout
+        panels={PANELS}
+        trailing={<button type="button">Upload</button>}
+        variant="web"
+      />
+    )
+
+    const upload = screen.getByRole("button", { name: "Upload" })
+    const cluster = upload.parentElement
+    // Pinned by margin, not by flex-filling: the cluster hugs the right edge
+    // even with nothing beside it to push against.
+    expect(cluster?.className).toContain("ml-auto")
+    // The right panel's trigger sits after the actions, at the far edge.
+    expect(
+      cluster?.contains(screen.getByRole("button", { name: "Toggle panel" }))
+    ).toBe(true)
+  })
+
+  test("trailing renders the cluster even with no right panel", () => {
+    render(
+      <ShellLayout trailing={<button type="button">Upload</button>} variant="web" />
+    )
+
+    expect(screen.getByRole("button", { name: "Upload" })).toBeDefined()
+    expect(screen.queryByRole("button", { name: "Toggle panel" })).toBeNull()
+  })
+
+  test("panelComponents renders a side with no static panels entry", () => {
+    render(
+      <ShellLayout
+        panelComponents={{ right: <div>Dynamic body</div> }}
+        variant="web"
+      />
+    )
+
+    expect(rightDrawer("Secondary panel").textContent).toContain("Dynamic body")
+  })
+
   test("the header triggers toggle their own side", async () => {
     const user = userEvent.setup()
     render(<ShellLayout panels={PANELS} variant="web" />)
@@ -268,6 +308,12 @@ function HookedShell({
       <button onClick={() => panels.toggle("right")} type="button">
         External toggle
       </button>
+      <button
+        onClick={() => panels.openPanel("right", <div>Details body</div>)}
+        type="button"
+      >
+        Open details
+      </button>
       {panels.isNarrow && <p>No room for the inspector</p>}
     </ShellLayout>
   )
@@ -301,6 +347,25 @@ describe("useShellPanels", () => {
     expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
   })
 
+  test("openPanel opens the side with the content it was handed", async () => {
+    const user = userEvent.setup()
+    render(<HookedShell />)
+
+    expect(rightDrawer().getAttribute("data-state")).toBe("collapsed")
+
+    await user.click(screen.getByRole("button", { name: "Open details" }))
+    expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+    // The dynamic content replaces the static panels entry for that side…
+    expect(rightDrawer().textContent).toContain("Details body")
+    expect(rightDrawer().textContent).not.toContain("Inspector body")
+
+    // …and sticks across a close/reopen instead of reverting.
+    await user.click(screen.getByRole("button", { name: "External toggle" }))
+    await user.click(screen.getByRole("button", { name: "External toggle" }))
+    expect(rightDrawer().getAttribute("data-state")).toBe("expanded")
+    expect(rightDrawer().textContent).toContain("Details body")
+  })
+
   test("mirrors the shell's too-narrow verdict back into the hook", () => {
     const restore = shellViewport(800)
     try {

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

@@ -21,6 +21,8 @@ export function AnimatedPanelProvider({
   defaultOpenMobile,
   onOpenMobileChange,
   onNarrowChange,
+  // ShellLayout renders this; the bare provider only keeps it off the DOM.
+  panelComponents: _panelComponents,
   className,
   style,
   ...props

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

@@ -18,11 +18,18 @@ export function ShellLayout({
   panels,
   className,
   header,
+  trailing,
   defaultOpen,
+  panelComponents,
   ...panelControlProps
 }: ShellLayoutProps): React.ReactElement {
   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`
 
+  // Content pushed through `openPanel(side, component)` wins over the static
+  // `panels` entry; a side renders its panel when either supplies content.
+  const leftContent = panelComponents?.left ?? panels?.left?.component
+  const rightContent = panelComponents?.right ?? panels?.right?.component
+
   // Each panel seeds its own side's initial state (`defaultOpen ?? open`);
   // an explicit `defaultOpen` record — usually from useShellPanels — wins
   // per side.
@@ -50,20 +57,20 @@ export function ShellLayout({
         paddingTop: variant === "desktop" ? TITLE_BAR_HEIGHT : 0,
       }}
     >
-      {panels?.left?.component && (
+      {leftContent && (
         <AnimatedPanel
           ariaLabel="Primary navigation"
           collapsible="icon"
           role="navigation"
           variant="inset"
         >
-          {panels?.left?.component}
+          {leftContent}
         </AnimatedPanel>
       )}
 
       <AnimatedPanelInset>
         <header className="flex h-12 flex-row! items-center justify-between gap-2 border-b px-2">
-          {panels?.left?.component && (
+          {leftContent && (
             <div className="flex min-w-0 shrink-0 items-center justify-start gap-2">
               <AnimatedPanelTrigger side="left">
                 <MotionIcon name="PanelLeft" size={24} animation="press" />
@@ -71,26 +78,31 @@ export function ShellLayout({
             </div>
           )}
           {header && (
-            <div className="flex w-full flex-1 items-center">{header}</div>
+            <div className="flex min-w-0 flex-1 items-center">{header}</div>
           )}
-          {panels?.right?.component && (
-            <div className="flex w-full shrink items-center justify-end gap-2">
-              <AnimatedPanelTrigger aria-label="Toggle panel" side="right">
-                <MotionIcon
-                  className="opacity-70"
-                  name="PanelRight"
-                  size={24}
-                />
-              </AnimatedPanelTrigger>
+          {(trailing || rightContent) && (
+            // ml-auto, not flex-fill: the cluster hugs the trailing edge even
+            // when there is no header (or left trigger) to push against.
+            <div className="ml-auto flex shrink-0 items-center justify-end gap-2">
+              {trailing}
+              {rightContent && (
+                <AnimatedPanelTrigger aria-label="Toggle panel" side="right">
+                  <MotionIcon
+                    className="opacity-70"
+                    name="PanelRight"
+                    size={24}
+                  />
+                </AnimatedPanelTrigger>
+              )}
             </div>
           )}
         </header>
         <div className="min-h-24 flex-1 overflow-auto">{children}</div>
       </AnimatedPanelInset>
 
-      {panels?.right?.component && (
+      {rightContent && (
         <AnimatedPanel
-          ariaLabel={panels.right.name ?? "Secondary panel"}
+          ariaLabel={panels?.right?.name ?? "Secondary panel"}
           // Below md the panel is portal led over the page, so it carries the
           // surface itself; the desktop rail keeps it on the inner panel.
           className={cn(
@@ -103,7 +115,7 @@ export function ShellLayout({
           side="right"
           variant="inset"
         >
-          {panels.right.component}
+          {rightContent}
         </AnimatedPanel>
       )}
     </AnimatedPanelProvider>

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

@@ -125,6 +125,11 @@ export type TPanelMap<Side extends TPanelSide = TPanelSide> = Partial<
   Record<Side, IPanel>
 >
 
+/** Dynamic panel content keyed by side — filled by
+ * `useShellPanels().openPanel(side, component)` and read by ShellLayout,
+ * where a side's entry wins over the static `panels` map's `component`. */
+export type SidebarComponentMap = Partial<Record<SidebarSide, ReactNode>>
+
 /** The open/close surface of the shell's panels, lifted straight from
  * AnimatedPanelProvider — every prop is keyed by side, there are no
  * explicit per-side props. `useShellPanels` produces the controlled subset
@@ -139,6 +144,7 @@ export type ShellPanelControlProps = Pick<
   | "onOpenMobileChange"
   | "shellId"
   | "defaultPanelWidth"
+  | "panelComponents"
 >
 
 export interface UseShellPanelsOptions {
@@ -189,6 +195,13 @@ export interface ShellPanelControls {
    * mobile state themselves when the viewport is narrow. Carries the same
    * `isNarrow` refusal as `setOpen`. */
   toggle: (side: SidebarSide) => void
+  /** Open a side's panel and, when given, swap in the content it shows.
+   * The component travels through `providerProps.panelComponents` into
+   * ShellLayout, where it wins over the static `panels` entry for that
+   * side, and sticks until the next `openPanel(side, component)` replaces
+   * it — closing the panel leaves it in place for the exit animation and
+   * the next open. Carries the same `isNarrow` refusal as `setOpen`. */
+  openPanel: (side: SidebarSide, component?: ReactNode) => void
   /** Spread onto ShellLayout (or AnimatedPanelProvider directly). */
   providerProps: ShellPanelControlProps
 }
@@ -199,6 +212,10 @@ export interface ShellLayoutProps extends ShellPanelControlProps {
    * the `left` rail and the `right` drawer; other sides are reserved. */
   panels?: TPanelMap
   header?: ReactNode
+  /** Actions pinned to the header's right edge, rendered just before the
+   * right panel's trigger. The cluster hugs the trailing edge no matter
+   * which of `header` / the left rail / the right panel are present. */
+  trailing?: ReactNode
   className?: string
   variant?: "web" | "desktop"
 }
@@ -249,6 +266,11 @@ export interface AnimatedSidebarProviderProps extends HTMLAttributes<HTMLDivElem
   /** Initial mobile overlay state — every side starts closed. */
   defaultOpenMobile?: SidebarOpenState
   onOpenMobileChange?: (open: boolean, side: SidebarSide) => void
+  /** Content pushed into a side's panel by `useShellPanels().openPanel`. It
+   * rides along in `providerProps` so the record can be spread on either
+   * surface: ShellLayout renders it in that side's panel; the bare provider
+   * renders no panels, so it only swallows the prop to keep it off the DOM. */
+  panelComponents?: SidebarComponentMap
   /** Fires when the shell crosses the width a secondary panel needs (rail +
    * body + panel at their floors). An imperative escape hatch for a consumer
    * that mounts the provider on its own; anything under `ExegiaProvider` can

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

@@ -1,6 +1,7 @@
 "use client"
 
 import { useCallback, useEffect, useId, useMemo, useState } from "react"
+import type { ReactNode } from "react"
 import { useAtomValue, useSetAtom } from "jotai"
 
 import {
@@ -12,6 +13,7 @@ import {
 import type {
   ShellPanelControlProps,
   ShellPanelControls,
+  SidebarComponentMap,
   SidebarSide,
   UseShellPanelsOptions,
 } from "./type"
@@ -104,6 +106,23 @@ export function useShellPanels({
     [open, setOpen]
   )
 
+  // The content sticks even when the open is refused (too narrow): it is
+  // what the panel shows whenever it next gets to open, not a one-shot.
+  const [panelComponents, setPanelComponents] = useState<SidebarComponentMap>(
+    {}
+  )
+  const openPanel = useCallback(
+    (side: SidebarSide, component?: ReactNode) => {
+      if (component !== undefined) {
+        setPanelComponents((prev) =>
+          prev[side] === component ? prev : { ...prev, [side]: component }
+        )
+      }
+      setOpen(true, side)
+    },
+    [setOpen]
+  )
+
   const providerProps = useMemo<ShellPanelControlProps>(
     () => ({
       shellId,
@@ -112,8 +131,17 @@ export function useShellPanels({
       onOpenChange: setOpen,
       openMobile,
       onOpenMobileChange: setOpenMobile,
+      panelComponents,
     }),
-    [shellId, defaultPanelWidth, open, openMobile, setOpen, setOpenMobile]
+    [
+      shellId,
+      defaultPanelWidth,
+      open,
+      openMobile,
+      setOpen,
+      setOpenMobile,
+      panelComponents,
+    ]
   )
 
   return {
@@ -126,6 +154,7 @@ export function useShellPanels({
     setOpen,
     setOpenMobile,
     toggle,
+    openPanel,
     providerProps,
   }
 }

package/src/components/icons/README.md

@@ -0,0 +1,91 @@
+# Corpora file icons
+
+Fourteen React SVG components covering seven file formats in two visual families.
+Every icon carries **both** a light and a dark artwork layer and picks one with
+Tailwind's `dark` variant — no props, no context, no JavaScript.
+
+Generated from `exegia-prod.sketch` → page `icons`, then simplified (dead defs
+removed, light/dark-identical defs shared, ids stripped). Do not hand-edit the
+`.tsx` files; regenerate them from Sketch instead (see
+[Regenerating](#regenerating)).
+
+## Usage
+
+```tsx
+import { FileBadgeTei, FileWordmarkPdf } from '@/components/icons';
+
+<FileBadgeTei />                        // 64×64, follows the app's dark class
+<FileBadgeTei size={128} />             // any size
+<FileWordmarkPdf title={null} />        // decorative: aria-hidden, no accessible name
+<FileBadgeTei title="TEI source file" /> // custom accessible name
+<FileBadgeTei className="shrink-0" />   // merged with the internal class
+```
+
+All remaining props are forwarded to the root `<svg>`.
+
+## Components
+
+| Format | Badge | Wordmark |
+| --- | --- | --- |
+| TEI | `FileBadgeTei` | `FileWordmarkTei` |
+| XML | `FileBadgeXml` | `FileWordmarkXml` |
+| TXT | `FileBadgeTxt` | `FileWordmarkTxt` |
+| TF | `FileBadgeTf` | `FileWordmarkTf` |
+| CFM | `FileBadgeCfm` | `FileWordmarkCfm` |
+| PDF | `FileBadgePdf` | `FileWordmarkPdf` |
+| Corpus | `FileBadgeCorpus` | `FileWordmarkCorpus` |
+
+**Badge** — colour-coded pill overlapping the left edge of the sheet.
+**Wordmark** — `.EXT` set along the bottom of the sheet.
+
+## Theming
+
+Each icon renders two `<g data-theme-layer>` groups and shows exactly one via
+Tailwind's `dark` variant: the light layer is `dark:hidden`, the dark layer
+`hidden dark:inline`. Whatever drives `dark:` in the app drives the icons —
+here that is `@custom-variant dark (&:is(.dark *))` in `index.css`, so the
+icons follow the `.dark` class exactly like every other component, with no
+inline stylesheet and no media query of their own.
+
+To force a theme on one subtree, scope the class:
+
+```tsx
+<div className="dark">
+  <FileBadgeTei />   {/* dark artwork regardless of the app theme */}
+</div>
+```
+
+Because the switch is pure CSS it is SSR-safe and cannot flash the wrong theme
+on hydration. The `data-theme-layer` attributes stay on the groups as styling
+and test hooks.
+
+## Notes
+
+- **Text is outlined.** Labels are vector paths, not live `<text>`, so the
+  icons do not depend on *TikTok Sans Display* being installed.
+- **IDs are namespaced** per component and per theme layer (`tei-badge-l-…`),
+  so gradients and filters never collide when several icons share a page.
+  Only referenced defs carry ids; decorative group ids were stripped.
+- **Both layers ship in every component,** but defs that are identical in
+  both themes (sheet geometry, badge plates, label glyphs) exist once and are
+  referenced from both layers — a `<defs>` entry resolves regardless of which
+  layer it sits in, hidden or not. Theme-specific gradients and filters stay
+  per layer, so the two themes remain pixel-faithful to Sketch.
+- **Filter regions were widened** to the SVG default (`-50% / 200%`). Sketch
+  exports tight regions such as `height="76.2%"` that clip real geometry in
+  spec-compliant renderers — the third sheet line disappears without this.
+
+## Regenerating
+
+1. In Sketch, edit the symbols on the `icons` page of `exegia-prod`.
+2. Re-export each symbol to SVG, and export each label inside an exact-size
+   bounding box to PDF (the PDF round-trip is what outlines the type).
+3. Run the generator, which splices the outlined labels into the SVG, namespaces
+   the IDs, widens the filter regions and emits the `.tsx` files.
+4. Run `bun scripts/simplify-icons.mjs` (from `react/`), which swaps the layer
+   switching onto Tailwind's `dark` variant, drops dead and duplicated defs,
+   strips unreferenced ids and default-value attributes, and verifies that
+   every remaining `url(#…)` / `href="#…"` reference resolves.
+
+Colours are driven by the `file/*` swatches in the Sketch document, so a palette
+change there propagates to every symbol before export.

package/src/components/icons/__tests__/icons.test.tsx

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test"
+import { render } from "@testing-library/react"
+
+import * as icons from ".."
+
+const components = Object.entries(icons).filter(
+  ([name]) => name.startsWith("FileBadge") || name.startsWith("FileWordmark")
+) as [string, (props: Record<string, unknown>) => React.ReactElement][]
+
+describe("file icons", () => {
+  test("exports all fourteen components", () => {
+    expect(components).toHaveLength(14)
+  })
+
+  for (const [name, Icon] of components) {
+    test(`${name} renders both theme layers on Tailwind's dark variant`, () => {
+      const { container } = render(<Icon />)
+      const svg = container.querySelector("svg")
+      expect(svg?.getAttribute("width")).toBe("64")
+      expect(svg?.getAttribute("role")).toBe("img")
+
+      const light = svg?.querySelector('[data-theme-layer="light"]')
+      const dark = svg?.querySelector('[data-theme-layer="dark"]')
+      expect(light?.getAttribute("class")).toBe("dark:hidden")
+      expect(dark?.getAttribute("class")).toBe("hidden dark:inline")
+      // No inline stylesheet — switching belongs to the app's Tailwind build.
+      expect(svg?.querySelector("style")).toBeNull()
+    })
+
+    test(`${name}'s internal references all resolve`, () => {
+      const { container } = render(<Icon />)
+      const svg = container.querySelector("svg")!
+      const ids = new Set(
+        [...svg.querySelectorAll("[id]")].map((el) => el.getAttribute("id"))
+      )
+      const refs = [
+        ...[...svg.querySelectorAll("use")].map((el) =>
+          el.getAttribute("href")?.slice(1)
+        ),
+        ...[...svg.outerHTML.matchAll(/url\(#([^)]+)\)/g)].map((m) => m[1]),
+      ]
+      expect(refs.length).toBeGreaterThan(0)
+      for (const ref of refs) expect(ids.has(ref ?? "")).toBe(true)
+    })
+  }
+
+  test("title becomes the accessible name; null marks decorative", () => {
+    const named = render(<icons.FileBadgeTei title="TEI source" />)
+    expect(
+      named.container.querySelector("svg")?.getAttribute("aria-label")
+    ).toBe("TEI source")
+
+    const decorative = render(<icons.FileWordmarkPdf title={null} />)
+    const svg = decorative.container.querySelector("svg")
+    expect(svg?.getAttribute("role")).toBe("presentation")
+    expect(svg?.getAttribute("aria-hidden")).toBe("true")
+  })
+})