components

Imported from prince-io/Librarian-AI (frontend/src/components/AGENTS.md). Install upstream with npx skills add prince-io/Librarian-AI --skill components. Copyright stays with the author.

frontend/src/components/

Purpose

Reusable UI components for landing page and app screens. Built with daisyUI 5 class names and Tailwind CSS 4 utilities, following the themeable design system (default clay claymorphism).

Ownership

• Layout.jsx — App shell: daisyUI collapsible drawer (lg:drawer-open + daisyUI is-drawer-open/is-drawer-close variants). Sidebar container is w-14 is-drawer-open:w-64 lg:is-drawer-open:w-80 — desktop expands to w-80 (mobile open stays w-64) and collapses to a w-14 icon rail when the toggle is unchecked (starts expanded; a chevron button — IconChevronsLeft, rotated 180° when collapsed — at the sidebar's top-right toggles it) and mobile is an overlay drawer (hidden when closed). The container is flex h-dvh flex-col overflow-hidden so the footer stays pinned and only the conversation list scrolls. The toggle checkbox is controlled (checked from drawerOpen state; initial value = matchMedia("(min-width: 1024px)") so desktop starts expanded, mobile closed). A fixed top-left hamburger (IconMenu, lg:hidden) opens the mobile drawer and is hidden while it's open. The sidebar's header row (px-3 py-3, justify-between expanded / justify-center in the rail) holds the "Librarian" title alongside the action button — the desktop chevron (IconChevronsLeft, lg:inline-flex) and the mobile close (IconClose w-6, lg:hidden) — so the close affordance sits beside the heading in both modes. closeDrawer() only closes on mobile (desktop keeps the rail state). The ready-view header keeps pl-14 on mobile (clears the fixed hamburger) and lg:pl-6 on desktop
• Sidebar.jsx — iOS-style conversation list (rounded rows, active = bg-primary/10), single + Ingest New Repo primary pill button, footer nav with Settings and Sign Out side by side (grid-cols-2) as solid buttons matching the Ingest button size — Settings = btn-neutral, Sign Out = btn-error (destructive; btn-block). Accepts a collapsed prop (from Layout's drawerOpen): when collapsed it renders an icon rail — default-size circle IconAdd (new chat), conversation list hidden, and default-size circle IconSettings (btn-neutral)/IconExit (btn-error) with native title tooltips (collapsed wrappers cancel the footer px-3 so the circles fit the w-14 rail and match the expanded button height); when expanded it renders the full list + labeled buttons. The "Librarian" heading lives in Layout's header row, not here. flex-1 min-h-0 root + flex-1 overflow-y-auto list mean the footer stays pinned and the list scrolls
• SymbolGraphView.jsx — Repo symbol graph (2D only — the 3D view was removed): renders SymbolGraph2DView plus the shared detail panel (glass aside, collapsible — a chevron button IconChevronsLeft rotated 180° (pointing right, toward the close direction) sits to the left of the kind/file name in the panel header and closes it; the panel opens only via node click — no reopen button). Responsive panel: on mobile (<lg) the aside is a full-screen overlay within the main area (absolute inset-0 z-40 on the graph's relative flex container — stays below the header, draws over the graph, legend, and filter) and on desktop it's a static w-96 side panel beside the graph. Clicking a file node fetches all its chunks (getFileChunks(repoHash, file) → /repositories/{hash}/chunks?file_path=) and reassembles the complete file source via assembleFileCode (line-coverage merge that drops nested AST symbol overlap), rendered in a "Complete code" section below the "Entities in this file" chips (entities list shows only when the file actually contains entities); clicking an entity node shows its code snippet directly. The heading now carries kind + label + an Explain button (path moved to the body as a truncated file:start-end breadcrumb) — Explain POSTs the node's code (full file source / entity snippet) + metadata to /repositories/{hash}/explain (SSE via consumeSSE, Clerk token) and streams a markdown explanation into the panel with loading/error states (non-SSE failures incl. the usage-cap 429 parse via readError from src/api/sse.js, rendered as a QuotaNotice in the panel); repoHash prop is the commit hash of the loaded graph — the graph JSON's repo field is a display name, not a route identifier; background click clears the panel. All node/reset/loading/error/empty states handled here
• SymbolGraph2DView.jsx — 2D graph via @xyflow/react (React Flow) + elkjs, mirroring the Understand-Anything dashboard design: kind-coded card nodes (colors from useGraphTheme() → --ds-graph-* tokens: file blue, class purple, interface sky, impl gold, method pink, function green, entity slate) with a colored left bar + mono label + kind tag; nested file-group layout (P3): each file is a React Flow parent node (FileGroup container: filename header + border, target/source handles on top/bottom so imports file→file and used_in/cross-file edges attach at the box edges instead of being buried under the container) with its entities rendered as children inside it (parentId + extent: "parent"), so each file is a compact ~column instead of one giant shared rank; layout is two-pass ELK: per-file layered runs (ELK_FILE_OPTIONS, direction DOWN, aspectRatio 0.4 → tall narrow columns; intra-file structural edges = uses) then a root layered run (ELK_OPTIONS, direction DOWN, aspectRatio 1.0) arranging the file groups (imports file→file edges); entity position is relative to its file (FILE_PADDING + FILE_HEADER_HEIGHT offset); positions are cached in localStorage (ua-layout:v6:{repo}:{fingerprint}) so repeat loads skip elk.layout() entirely (capped at LAYOUT_CACHE_MAX_NODES); bump the v6 segment whenever layout options/node dimensions change; only entity→entity (uses/used_in) + file→file imports edges are drawn (there is no defines/contains edge type — file membership and containment are the nested file-group itself); step edges colored by edge type (--ds-graph-edge-* tokens via useGraphTheme: imports yellow, used_in teal, uses green) with uniform width/opacity and MarkerType.ArrowClosed arrowheads (same color); selection focus dims unrelated nodes to opacity-20 and unrelated edges to EDGE_OPACITY_DIM + a neutral grey stroke while highlighting the selected node's incident edges (thicker EDGE_HIGHLIGHT_WIDTH, full opacity) and keeping direct neighbors at opacity-80 — neighbors resolve via a precomputed Set (selectedNeighbors memo) so selection is O(1) per node, and a selected entity's file container stays active (not dimmed); selection fade — selected node gets a primary ring + .glow, neighbors a thin ring; legend overlay (top-left, w-70 md:w-80, collapsible — a "Legend" button with IconChevronsLeft rotated 90° (open) / -90° (closed) toggles the Edges + Nodes lists; on mobile the legend and filter menu are mutually exclusive — opening one closes the other, since they overlap on narrow screens) with Edges (imports/used_in/uses colors) + Nodes sections, React Flow colorMode driven by --ds-graph-color-mode, MiniMap + zoom controls (Controls fit button animated via onFitView → rf.fitView({ duration: 400 }), same as the load-time fitView), fitView on load, canvas surface = .graph-surface; performance: onlyRenderVisibleElements + fixed node width/height so pan/zoom only renders viewport-visible nodes/edges, nodesConnectable={false} + edgesFocusable={false}. Node click → onSelect (file group or entity → shared detail panel), pane click clears. NOTE: custom node data carries the raw backend node so the shared panel works unchanged; graph filter menu — top-right funnel (details.dropdown, controlled open state + closes on outside click) opens a panel (w-[17.5rem] phone, md:w-80 ≥768px) with a multi-select Node type checkbox group (grid-cols-2 gap-x-3 gap-y-1.5) (kinds present in the loaded graph, color-dotted) + a single-select Directory control (every unique directory path prefix from node files — e.g. src and src/tests, root-level files grouped as (root); custom button + inline list with no nesting indentation, selected value and each option truncate so long paths can't overflow the bar; chevron IconChevronsLeft rotated up/down; selecting a parent dir includes all nested children because matching is prefix-based); groups combine AND, kinds OR. Matches = entities passing both groups plus their parent file containers (a file shows only when ≥1 of its entities matches); the layout effect re-runs the two-pass ELK on a filteredBase subgraph so non-matching nodes are hidden and the graph is re-laid out per filter; filtered layouts are not cached (only the unfiltered one stays in ua-layout:v6). A count badge on the funnel shows active filters; a Clear All (✕) pill next to it restores the full graph from the layout cache; zero matches show a centered "No nodes match the current filters" overlay (non-interactive pointer-events-none; the filter/reset buttons sit at z-30 above the z-20 overlays so they stay clickable); filters reset when graph.repo changes
• MessageContent.jsx — Markdown-rendered assistant messages vs plain user messages; assistant content wrapped in prose prose-invert prose-sm max-w-none (Tailwind typography plugin) for readable paragraphs/headings/lists/code/tables. Renders [C1] citation markers as clickable clay chips (DOM-walk of the sanitized HTML, skipping pre/code/a/button) and reports clicks via onCitationClick(citation, rect) for markers that exist in the message's citations map; unmatched markers stay plain text
• QuotaNotice.jsx — Usage-cap 429 notice (daisyUI alert alert-warning alert-soft): warning-triangle icon, "Daily limit reached" title, per-group copy ("You've used N of L daily messages/ingests. More free up at "), a badge badge-warning badge-outline used / limit, and an optional dismiss (×) button. Props { quota: {group, used, limit, resets_at}, onDismiss }; renders null without quota. Fed by readError from src/api/sse.js in AppPage (start + ready views) and SymbolGraphView (explain panel)
• CitationCard.jsx — Fixed-position clay popover anchored to a clicked citation (flips above/below to fit the viewport, clamped horizontally; no anchor arrow/tail). Closes on outside click/Escape/window resize/chat scroll; scroll routing is cursor-driven — a native wheel listener (passive: false) on the card intercepts wheel events and redirects them to the code block (preRef.scrollTop += deltaY) so hovering the card scrolls the code instead of the chat behind it, while the scroll capture listener ignores events originating inside the card (e.g. dragging the code scrollbar) and only collapses the card on real chat scrolls. Self-fetches the chunk via getChunk(citation.repo_hash, citation.chunk_id) on mount (the citation JSON carries repo_hash; the route identifier is the commit hash, not a repo name/URL); shows file path + line span, symbol/language chips, and the chunk content in a scrollable pre, with loading/error states
• RepoInput.jsx — GitHub URL input in a glass composer pill (.glass-composer, rounded-full) with a primary Process button
• ProgressBar.jsx — Pipeline progress bar + step indicators (stages: ingest → scan → chunk → embed → ready)
• ChatMessages.jsx — Scrollable message list rendered in a flex flex-col-reverse scroll container (the reversed flex itself is the scroller, so the browser's default scrollTop 0 IS the bottom — opening a chat lands on the newest messages with no scroll JS, immune to async markdown, and streaming stays pinned automatically). Messages render newest-first; the sync-boundary divider is inserted during the reversed pass (trailing-divider case is unshifted to the visual bottom). AppPage keys it by activeConvId (remount) and the loading prop renders chat-aligned skeleton rows while history loads. Empty state (centered "Ready to chat" label, flex-1 filler). daisyUI chat bubbles: user = chat-bubble-primary (right tail, chat-end), assistant = bg-base-200 text-base-content (left tail, chat-start). The daisyUI mask tail stays seamless — the tail-corner radius is owned by .chat-bubble (set to 0 on the tail side), so bubbles must NOT add rounded-* utilities that touch that corner. Typing/loading indicator renders inside the empty assistant placeholder bubble (no separate loading bubble). Sync-boundary divider: takes the conversation's current repoHash prop and renders a daisyUI divider ("Repo synced — messages above reference an older commit, below reference the latest commit") after the last message whose repo_hash differs from the current commit — so it appears immediately after a sync (even before a new-commit message exists, as a trailing divider) and persists across refresh (it's derived from server data, not a session marker). Local streaming messages are stamped with the active repo_hash by AppPage, so the in-session list matches server truth
• LandingHero.jsx — Full-viewport claymorphism hero: GSAP entrance timeline (badge → title → subtitle → CTA), clay pill badge, puffy clay-press CTA buttons, sprinkled infinitely-animating ClayShapes
• LandingFeatures.jsx — Feature bento grid (2 wide + 2 narrow) of puffy .clay white cards (colored icon chips) with GSAP scroll-reveal and background ClayShapes
• LandingHowItWorks.jsx — 3-step workflow of puffy .clay white cards (clay number chips, middle card offset for asymmetry), GSAP scroll-reveal, background ClayShapes
• LandingFooter.jsx — Footer with GSAP fade-in on scroll
• ClayShapes.jsx — Decorative animated 3D clay geometric shapes (circle/ring/square/squircle/blob/egg/pill — all soft/rounded, no sharp points) scattered absolutely across a section. Each shape gets one seamless infinite GSAP timeline (ref-based, repeat: -1): rotation uses relative +=/-= so it keeps accumulating without snapping, and the bob toggles y (0 → float → 0). Uses a plain prefers-reduced-motion guard (NOT gsap.matchMedia, which ScrollTrigger.refresh() re-runs and would kill/recreate the loops). Colors are Tailwind text-color classes rendered as currentColor so shapes adapt to the active theme

Local Contracts

• All components use daisyUI class names (btn, input, chat, menu, drawer, etc.) — no hand-written CSS
• Theme/chrome follows the design system: colors via daisyUI semantic classes or --ds-* tokens; border-2/rounded-none utilities are tokenized in src/styles/design-system.css (--border / --radius-box) so they adapt per theme — do NOT hardcode border-width overrides; explicit radius utilities (rounded-full/rounded-3xl) are allowed
• Clay surfaces use .clay/.clay-press (shadows only, compose with Tailwind bg classes); glass surfaces use .glass-* — never inline backdrop-blur/alpha values
• GSAP animations registered via ScrollTrigger.create() in useLayoutEffect with StrictMode guard; ambient loops (marquee, floating shapes) use gsap.matchMedia() with a (prefers-reduced-motion: no-preference) branch so motion is disabled for reduced-motion users
• Landing page components accept no props — self-contained with Clerk hooks and GSAP timelines
• App components (Layout, Sidebar, ChatMessages, etc.) receive data via props from AppPage

Work Guidance

• New shared UI elements go here, not in pages/
• Use daisyUI component classes first, Tailwind utilities for overrides, ! suffix only as last resort
• Scroll-triggered animations use gsap.context() + ctx.revert() for proper StrictMode cleanup
• Keep components focused — if a component needs significant state, consider extracting to a hook

Verification

• All components rendered on either / (Landing) or /app (App) routes
• Build verified with npm run build