Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
@repowise-dev/ui — Component Contracts
This document is the public-facing prop contract for components in
@repowise-dev/ui. Each section lists the prop interface, with types
sourced from @repowise-dev/types where the prop carries an engine
artifact. Components are presentational: they accept canonical data
via props, manage only UI-local state internally, and emit user
intent via callbacks. Data fetching, mutation, and routing live in
the consumer.
The contract is the package's public API. Breaking changes here should be deliberate and called out in PR titles.
ui/* — Radix-CVA primitives
Standard shadcn-style primitives wrapping Radix UI: Badge, Button,
Card (+ CardHeader/CardTitle/CardDescription/CardContent/
CardFooter), ConfirmDialog, Dialog (+ all Dialog* parts),
Input, Label, Progress, ScrollArea, Select (+ Select*
parts), Separator, Sheet (+ Sheet* parts), Skeleton, Slider,
Switch, Tabs (+ Tabs* parts), Tooltip (+ Tooltip* parts).
Props mirror the underlying Radix primitive plus a className prop
merged via cn (tailwind-merge + clsx). Button and Badge
expose CVA variant and size unions documented inline at the
component definition.
shared/api-error — ApiError
Renders an inline error card with retry affordance.
| Prop | Type | Required | Notes |
|---|---|---|---|
title |
string |
no | Defaults to "Failed to load". |
message |
string |
no | Defaults to a generic fetch-error line. |
onRetry |
() => void |
no | When provided, a "Retry" button is rendered. |
shared/responsive-table — ResponsiveTable<T>
The shared table primitive with a column-priority API. Priority 1
columns are always visible, priority 2 hide below md, priority 3
hide below lg; the wrapper always provides overflow-x-auto, and
stacked additionally collapses to a card list below sm/md.
| Prop | Type | Required | Notes |
|---|---|---|---|
columns |
ResponsiveColumn<T>[] |
yes | { key, header, render, priority?, align?, sortable?, mobileLabel?, mobileRender?, hideInCard?, headerClassName?, cellClassName? }. |
rows |
T[] |
yes | |
rowKey |
(row: T) => string |
yes | |
onRowClick |
(row: T) => void |
no | Rows get pointer affordance plus keyboard activation (tabIndex, Enter/Space) when set. |
selectedKey |
string | null |
no | Highlights the matching row. |
sortField / sortOrder / onSort |
string / "asc" | "desc" / (key) => void |
no | Controlled sorting; sortable headers render as real buttons with aria-sort on the active column. |
empty |
ReactNode |
no | Rendered instead of the table when rows is empty (pass EmptyState). |
caption |
string |
no | Screen-reader-only <caption> describing the table. |
stacked |
"sm" | "md" |
no | Collapse to stacked cards below the breakpoint. |
bare |
boolean |
no | Omit the rounded border + surface background (for card-embedded tables). |
The module also exports clickableRowProps(activate) and
CLICKABLE_ROW_CLS so tables that own their <tr> markup (for example
VirtualizedTable consumers) can give clickable rows the same keyboard
activation and focus treatment.
shared/adaptive-panel — AdaptivePanel
One overlay surface: right-side slide-in panel on md+, bottom sheet
with drag-handle swipe-dismiss on mobile. Radix Dialog under the hood.
| Prop | Type | Required | Notes |
|---|---|---|---|
open / onOpenChange |
boolean / (open) => void |
yes | Controlled. |
title |
ReactNode |
yes | Accessible name; rendered in the header unless hideHeader. |
eyebrow |
ReactNode |
no | Small uppercase label above the title. |
widthClassName |
string |
no | Desktop width; default md:max-w-[520px]. |
sheetHeightClassName |
string |
no | Mobile max height; default max-h-[85dvh]. |
hideHeader |
boolean |
no | Title goes sr-only; render your own header. |
modal |
boolean |
no | Default true. false keeps the page interactive behind the panel on desktop (chat artifact panel). |
shared/toast — Toaster, toast
Token-themed sonner toaster (--z-toast, surface/border/text tokens).
Mount Toaster once at the app shell; fire toasts via the re-exported
toast. Framework-neutral: the host passes the resolved theme.
| Prop | Type | Required | Notes |
|---|---|---|---|
theme |
"light" | "dark" |
no | Default dark. |
position |
sonner position union | no | Default bottom-right. |
shared/error-boundary — ErrorBoundary
Class-component boundary; default fallback renders ApiError with a
retry that re-mounts the subtree.
| Prop | Type | Required | Notes |
|---|---|---|---|
children |
ReactNode |
yes | |
fallback |
(error, reset) => ReactNode |
no | Replaces the default ApiError fallback. |
title |
string |
no | Forwarded to the default fallback. |
onError |
(error, info) => void |
no | Reporting hook. |
shared/empty-state — EmptyState
Empty-list placeholder with optional icon and CTA.
| Prop | Type | Required | Notes |
|---|---|---|---|
title |
string |
yes | Heading text. |
description |
string |
no | Sub-line; shown below the title. |
icon |
React.ReactNode |
no | Rendered above the title. |
action |
{ label: string; onClick: () => void } |
no | Renders a primary Button when supplied. |
className |
string |
no | Forwarded to the outer container. |
shared/metric-card — MetricCard
The canonical single-stat display tile.
| Prop | Type | Required | Notes |
|---|---|---|---|
label |
string |
yes | Uppercase label above the value. |
value |
React.ReactNode |
yes | Rendered tabular-nums. |
description |
string |
no | Caption under the value. |
delta |
{ value: string; positive: boolean; neutral?: boolean } |
no | Signed change; positive drives good/bad colour, neutral renders uncoloured. |
sparkline |
React.ReactNode |
no | Rendered beneath the value. |
distBar |
React.ReactNode |
no | Distribution bar beneath the value. |
icon |
React.ReactNode |
no | Right-aligned glyph. |
href |
string |
no | Wraps the card in a link; hover affordance follows. |
LinkComponent |
React.ElementType |
no | Link element used with href; defaults to "a". |
className |
string |
no | Forwarded to the outer Card. |
coverage/coverage-donut — CoverageDonut
Recharts donut visualising fresh/stale/outdated counts with a centred percentage label for the fresh slice.
| Prop | Type | Required | Notes |
|---|---|---|---|
fresh |
number |
yes | Count of fresh pages. |
stale |
number |
yes | Count of stale pages. |
outdated |
number |
yes | Count of outdated pages. |
Behaviour: zero-value slices are filtered before render; if all three
are zero the donut renders empty and the centre text shows 0%.
decisions/decision-health-widget — DecisionHealthWidget
Three-card summary tile for active / proposed / stale counts.
| Prop | Type | Required | Notes |
|---|---|---|---|
health |
DecisionHealth | undefined (@repowise-dev/types/decisions) |
yes | Renders nothing while undefined; useful for the "loading or absent" state. |
decisions/decisions-table — DecisionsTable
Filterable table of DecisionRecord rows with status + source dropdowns.
| Prop | Type | Required | Notes |
|---|---|---|---|
decisions |
DecisionRecord[] | undefined (@repowise-dev/types/decisions) |
yes | Filtered list as resolved by the caller. |
filters |
DecisionsTableFilters |
yes | Controlled. Caller mirrors these into fetch keys so filter changes drive a re-fetch. |
onFiltersChange |
(filters: DecisionsTableFilters) => void |
yes | Fires on every dropdown change. |
repoId |
string |
yes | Used to build the /repos/{repoId}/decisions/{id} link target for each row. |
linkPrefix |
string |
no | Overrides the /repos/{repoId} URL prefix. |
LinkComponent |
ElementType<{ href; className?; children }> |
no | Plug a router <Link>; defaults to <a>. |
error |
unknown |
no | Truthy on a failed fetch; renders an inline retry message. |
isLoading |
boolean |
no | Suppresses the "no decisions found" empty-state during the first fetch. |
onRetry |
() => void |
no | Wired to the inline retry button when error is truthy. |
Filter unions:
DecisionStatusFilter=DecisionStatus \| "all"DecisionSourceFilter=DecisionSource \| "all"
dead-code/dead-code-view - DeadCodeView
The whole Dead Code page: a lede (reclaimable lines and one posture sentence), the safe-to-delete list, and the findings table. Owns the optimistic patch + undo toast, bulk resolve, the AI cleanup prompt modal, Re-analyze, and the status control that switches which slice the table shows.
| Prop | Type | Required | Notes |
|---|---|---|---|
adapter |
DeadCodeAdapter |
yes | Everything host-specific: fetching, mutation, links, navigation. |
Behaviour worth knowing:
- Two fetches. The open slice feeds the list and the table; a second, conditional fetch backs the status filter when it is not "open". Both are capped at 500 rows. The open slice has a repo-wide total to compare against, so its hint says "Showing N of M"; a non-open status has no server-side total, so its hint can only say "First N".
- A failed fetch with nothing to show renders a retry card and nothing else: it must never fall through to an empty state, which would read as a clean repository. A failed refresh over rows already in hand keeps the table and puts the card above it.
- Optimistic row state lives here, not in the table, so resolving a row moves the list with it and undo can put it back.
- Zero open findings: with
summary.analyzed_atset, the lede reads "0 lines" with a positive all-clear and no sections; with itnull(no run recorded), a neutral "Not analysed yet" with a run button. With the field absent (a host that does not report runs), the all-clear shows without an "Analysed" time; such a host should also setanalyzeDisabledReason.
dead-code/dead-code-adapter - DeadCodeAdapter
The host injection point. Hosted consumes this, so treat it as public API: adding a required member is a breaking change for every consumer.
| Member | Type | Required | Notes |
|---|---|---|---|
cacheKey |
string |
yes | Seeds the view's SWR keys. Keep stable per repo/snapshot. |
repoId |
string |
yes | Repo identity for hosts that need it. Nothing in this package reads it today; links come from fileHref / graphHref. |
getSummary |
() => Promise<DeadCodeSummary> |
yes | |
listFindings |
(opts?: { limit?: number; status?: DeadCodeStatus }) => Promise<DeadCodeFinding[]> |
yes | status defaults to "open" server-side. |
analyze |
() => Promise<{ job_id?: string } | void> |
yes | Returning a job_id lets the view wait and refresh itself. |
waitForAnalysis |
(jobId: string) => Promise<void> |
no | Without it the view cannot know when to refetch, and says so in its toast. |
analyzeDisabledReason |
string |
no | Renders Re-analyze disabled with this sentence beside it. |
patchFinding |
(id: string, patch: DeadCodePatchInput) => Promise<DeadCodeFinding> |
yes | Must return the updated finding; the view stores it as the optimistic override. |
fileHref |
(path: string) => string |
yes | Makes the path a link and the row clickable. |
graphHref |
(path: string) => string |
no | Omit and the per-row Graph action disappears, which keeps app routes out of this package. |
navigate |
(href: string) => void |
yes | Host router push. |
dead-code/findings-table - FindingsTable
The findings table: kind tabs driven by the data, a search box, sortable
columns, one confidence control (All / High only), bulk resolve, and per-row
status actions. Built on shared/responsive-table with
stacked="sm" and windowed rows.
| Prop | Type | Required | Notes |
|---|---|---|---|
findings |
DeadCodeFinding[] |
yes | One status slice; the table filters it by kind / confidence / search client-side. |
onPatch |
(id, { status }) => Promise<DeadCodeFinding> |
yes | Host owns the API call and the undo toast. |
onBulkResolve |
(ids: string[]) => Promise<string[]> |
no | Must return the ids that actually resolved, not the ids it was given. The table reconciles against that, never against position. |
fileHref |
(path: string) => string |
no | |
onNavigate |
(href: string) => void |
no | Needed alongside fileHref for client-side row clicks. |
graphHref |
(path: string) => string |
no | |
onGeneratePrompt |
(ids: string[]) => void |
no | Drives both the per-row icon button and "AI prompt for N selected". |
status |
DeadCodeStatus |
no | Which slice is on screen. Defaults to "open"; bulk resolve only appears there. |
isLoading |
boolean |
no | Shows a skeleton instead of an empty state during the first fetch. |
Selection is always intersected with the rows currently visible, so narrowing the confidence filter after selecting cannot resolve rows the user can no longer see.
dead-code/finding-cells - cell renderers
FindingIdentity, FindingConfidence, FindingSafety and
FindingRowActions back the table's columns. FindingSafety renders nothing
on a deletion-ready row and "Review first" plus the reason on the rest. FindingRowActions is separate
because it owns per-row pending/confirm state that a plain render(row)
closure cannot hold; it offers resolve/ack/FP on an open finding and Reopen
on anything already actioned. DEAD_CODE_STATUS_LABELS is the shared label
map for the status filter.
dead-code/safe-to-delete-pile - SafeToDeletePile
The "what do I delete" punchline: per-file rollup of the cleanup-ready findings with the AI cleanup CTA.
| Prop | Type | Required | Notes |
|---|---|---|---|
findings |
SafeToDeletePileFinding[] |
yes | Caller passes the safe slice; structural subset of DeadCodeFinding. |
onPropose |
(ids: string[]) => void |
no | Opens the AI prompt modal; omit and the CTA disappears. |
onSelect |
(finding: DeadCodeFinding) => void |
no | Row click. |
docs/docs-tree — DocsTree
Filterable, collapsible directory tree of DocPage entries. Special
pages (repo_overview, architecture_diagram) appear at the top
level; module pages become directories with their page attached;
file pages nest under their parent directory.
| Prop | Type | Required | Notes |
|---|---|---|---|
pages |
DocPage[] (@repowise-dev/types/docs) |
yes | Caller fetches; tree builds the directory hierarchy each render. |
selectedPageId |
string | null |
yes | Currently-active page id; the matching node is highlighted. |
onSelectPage |
(page: DocPage) => void |
yes | Fires on leaf-page or module-page click. |
className |
string |
no | Forwarded to the outer container. |
Behaviour: built-in search, type filter (all / file_page /
module_page / symbol_spotlight / repo_overview), and freshness
filter (all / fresh / stale / outdated). Filter state is
UI-local — there's no fetch coupling.
coverage/freshness-table — FreshnessTable
Filterable table of DocPage rows with per-row regenerate action.
| Prop | Type | Required | Notes |
|---|---|---|---|
pages |
DocPage[] (@repowise-dev/types/docs) |
yes | Caller fetches the list. The table does not mutate. |
onRegenerate |
(pageId: string) => Promise<void> |
no | Caller wires to a mutation API. The table tracks per-row pending state internally and disables the row's button while in flight. Omit to hide the regenerate column. |
Behaviour:
- Filter tabs (
All,Fresh,Stale,Outdated) are UI-local state; the canonicalfreshness_statusfield onDocPageis the filter predicate. - Confidence column is colour-graded against the same thresholds as
lib/confidence.scoreToStatus. - Empty state (
EmptyState) appears when the filtered set is empty.
git/* — Hotspot, ownership, and contributor visualisations
All twelve components are presentational and accept canonical engine
artifacts via props (Hotspot, OwnershipEntry from @repowise-dev/types/git,
or anonymous shapes for partner / owner / category records). None reach
out to data hooks or mutation APIs — fetching belongs to the caller.
git/churn-bar — ChurnBar
Inline horizontal bar shaded green/yellow/red against thresholds at 50% / 75% percentile.
| Prop | Type | Required |
|---|---|---|
percentile |
number (0–100, clamped) |
yes |
className |
string |
no |
git/co-change-list — CoChangeList
Top-5 co-change partners with relative-magnitude bars.
| Prop | Type | Required |
|---|---|---|
partners |
Array<{ file_path: string; co_change_count: number }> |
yes |
git/churn-histogram — ChurnHistogram
Recharts bar chart binning hotspots into 10-percentile buckets.
| Prop | Type | Required |
|---|---|---|
hotspots |
Hotspot[] (@repowise-dev/types/git) |
yes |
git/commit-category-donut — CommitCategoryDonut
Recharts donut with centred dominant-category label. Returns null
when the total is zero.
| Prop | Type | Required |
|---|---|---|
categories |
Record<string, number> |
yes |
git/commit-category-sparkline — CommitCategorySparkline
Single-row stacked bar sized by category counts; each segment wears a
tooltip. Returns null when the total is zero.
| Prop | Type | Required |
|---|---|---|
categories |
Record<string, number> |
yes |
git/contributor-bar — ContributorBar
Top-5 horizontal bar of files-by-owner.
| Prop | Type | Required |
|---|---|---|
owners |
Array<{ name; email?; file_count; pct }> |
yes |
git/contributor-network — ContributorNetwork
Force-directed (d3-force) co-ownership graph. Computes nodes/links
from hotspots[].primary_owner and shared-file overlap; top-20
contributors only.
| Prop | Type | Required |
|---|---|---|
hotspots |
Hotspot[] (@repowise-dev/types/git) |
yes |
git/hotspot-table — HotspotTable
Server-driven table of hotspots: the host owns search, filter, sort and
paging (the table debounces the search box and reports settled values).
Chips (all / bus_factor_1 / accelerating / bug_magnet) show the
server's facets as "N of total"; sortable columns (score / commits /
fixes / churn) render only with onSortChange. One quiet per-row agent
prompt and a header "Copy prompt for these N".
| Prop | Type | Required |
|---|---|---|
hotspots |
Hotspot[] (@repowise-dev/types/git) |
yes |
total, facets |
number, HotspotFacets |
no |
query / filter / sort and their on*Change |
controlled state | no |
onGeneratePrompt, onGenerateBatchPrompt |
callbacks | no |
git/ownership-table — OwnershipTable
Search + silo filter over module ownership rows.
| Prop | Type | Required |
|---|---|---|
entries |
OwnershipEntry[] (@repowise-dev/types/git) |
yes |
git/ownership-treemap — OwnershipTreemap
Treemap (d3-hierarchy) with file-count area, owner-hash colour, and
silo highlight stroke. Hover tooltips computed against the container's
bounding rect.
| Prop | Type | Required |
|---|---|---|
entries |
OwnershipEntry[] (@repowise-dev/types/git) |
yes |
git/risk-distribution-chart — RiskDistributionChart
Top-30 risk-scored vertical bar chart with average reference line.
Score = 0.4·churn + 0.35·busFactor + 0.25·trend, all normalised to
0–100.
| Prop | Type | Required |
|---|---|---|
hotspots |
Hotspot[] (@repowise-dev/types/git) |
yes |
git/bus-factor-panel — BusFactorPanel
Stacked bar of safe / warning / risk counts plus a top-5 highest-risk files list.
| Prop | Type | Required |
|---|---|---|
hotspots |
Hotspot[] (@repowise-dev/types/git) |
yes |
coupling/* — Change-coupling visualisation
Renders the repo-wide change-coupling graph (files that change together).
Pure presentation over @repowise-dev/types/coupling; fetching belongs to
the caller. Co-change is a temporal hint, not a verified dependency, and
strength is a decay-weighted count (never a percentage or a trend).
coupling/coupling-graph — CouplingGraph
Hierarchical edge-bundling diagram (d3-hierarchy radial cluster +
d3-shape curveBundle). Files sit on a ring grouped by their directory
hierarchy; bundled arcs link files that change together. Dots are colored by
health band and sized by lines + coupling degree. Hovering a file peeks its
couplings (colored by the partner's health band) and dims the rest; clicking a
file pins a sticky selection (persistent accent ring) and clicking empty canvas
clears it. The effective focus (focusedPath = hover ?? pinned) is controlled
for cross-highlight with a table, and falls back to internal hover/pin state.
| Prop | Type | Required |
|---|---|---|
nodes |
CouplingNode[] (@repowise-dev/types/coupling) |
yes |
edges |
CouplingEdge[] (@repowise-dev/types/coupling) |
yes |
totalEdges |
number (pre-cap count, for the "showing N of M" line) |
no |
focusedPath |
string | null (effective focus: hover ?? pinned) |
no |
pinnedPath |
string | null (sticky selection; draws the ring) |
no |
onHover |
(path: string | null) => void (transient peek) |
no |
onPinToggle |
(path: string | null) => void (click a dot / empty canvas) |
no |
size |
number (square viewBox edge, default 760) |
no |
coupling/coupling-table — CouplingTable
The precise, ranked companion to the diagram: one row per coupling with a
strength bar and last-shared-commit date, sortable by Strength or Last. File
names are links (when linkForPath is set); clicking a row pins its source
file, and hovering a row (or a name) peeks that file. Uses
shared/responsive-table.
| Prop | Type | Required |
|---|---|---|
edges |
CouplingEdge[] (@repowise-dev/types/coupling) |
yes |
focusedPath |
string | null (effective focus) |
no |
pinnedPath |
string | null (drives the selected-row style) |
no |
onHover |
(path: string | null) => void |
no |
onPinToggle |
(path: string | null) => void |
no |
onGeneratePrompt |
(edge: CouplingEdge) => void (shows the AI decouple action) |
no |
linkForPath |
(path: string) => string (makes file names links) |
no |
LinkComponent |
link component for file links (defaults to <a>) |
no |
coupling/coupling-explorer — CouplingExplorer
The full change-coupling surface: the diagram over a sortable/filterable table, sharing one focus model, plus the AI-decouple modal and a default pin on the most-coupled hub. Lives in the shared package so OSS and hosted share the interaction; the host supplies only the link prefix and optional URL sync.
| Prop | Type | Required |
|---|---|---|
data |
CouplingGraphResponse (@repowise-dev/types/coupling) |
yes |
repoLinkPrefix |
string (e.g. /repos/abc; makes file names links) |
no |
LinkComponent |
link component for file links (defaults to <a>) |
no |
initialFocus |
string | null (seed pin, e.g. from a ?focus= deep link) |
no |
onFocusChange |
(path: string | null) => void (reflect the pin to the URL) |
no |
dashboard/coupling-mini-card — CouplingMiniCard
Overview front-door for the (sidebar-less) change-coupling view: previews the top few coupled pairs with strength bars and links to the full page. Fully presentational.
| Prop | Type | Required |
|---|---|---|
edges |
CouplingEdge[] (top couplings, strongest-first) |
yes |
href |
string (link to the full coupling view) |
yes |
LinkComponent |
link component (defaults to <a>) |
no |
jobs/job-log — JobLog
Auto-scrolling fixed-height log viewer for streaming job progress entries.
| Prop | Type | Required | Notes |
|---|---|---|---|
entries |
Array<{ text: string; level?: number }> |
yes | Caller accumulates from SSE / poll. |
maxLines |
number |
no | Tail length; default 6. |
jobs/generation-progress — GenerationProgress
Status header, progress bar, live cost, summary tiles, and embedded
JobLog for a documentation-generation job. Presentational — the
caller polls / streams the job and forwards the snapshot via props.
| Prop | Type | Required | Notes |
|---|---|---|---|
job |
GenerationProgressJob | undefined |
yes | Local subset of the engine Job shape (id, status, total/completed_pages, current_level, started_at, error_message, config). |
log |
Array<{ text: string }> |
yes | Caller accumulates SSE log events. |
elapsed |
number |
yes | Wall-clock elapsed in ms. Caller owns the interval. |
actualCost |
number | null |
yes | Live USD cost; null until the first cost-bearing event. |
stuckPending |
boolean |
yes | Caller decides — typically pending && !started_at && elapsed > threshold. |
cancelling |
boolean |
yes | Disables the Cancel button while in flight. |
onCancel |
() => void |
yes | Caller wires to the cancel mutation; toasts/error handling live there. |
symbols/symbol-graph-panel — SymbolGraphPanel
Right-column graph-intelligence panel for a focused symbol: pagerank / betweenness percentile bars, in/out degree, community label, optional entry-point score, callers/callees, and heritage (extends/implements). Presentational.
| Prop | Type | Required | Notes |
|---|---|---|---|
metrics |
GraphMetrics | undefined (@repowise-dev/types/graph) |
yes | |
metricsLoading |
boolean |
yes | |
callData |
CallersCallees | undefined (@repowise-dev/types/graph) |
yes | |
callsLoading |
boolean |
yes | |
heritageData |
CallersCallees | undefined |
no | When omitted or empty, the heritage section is hidden. |
symbols/symbol-drawer — SymbolDrawer
Modal dialog over a focused symbol: signature, docstring, parent, plus an optional right-column slot for the graph-intelligence panel.
| Prop | Type | Required | Notes |
|---|---|---|---|
symbol |
CodeSymbol | null (@repowise-dev/types/symbols) |
yes | null closes the dialog. |
onClose |
() => void |
yes | |
graphPanel |
ReactNode |
no | Caller passes a data-coupled <SymbolGraphPanelWrapper>; omit to hide the column. |
symbols/symbol-table — SymbolTable, SymbolTableProps, SortCol, SortDir
Filterable, sortable table of symbols with importance bars and a
configurable drawer slot. Server-driven filters (q, kind,
language) are controlled props because they affect fetch keys; sort
state is UI-local.
| Prop | Type | Required | Notes |
|---|---|---|---|
items |
CodeSymbol[] |
yes | Caller fetches; flattened across pages. |
importanceScores |
Map<string, number> |
yes | Normalised 0–1, indexed by symbol.id. Caller computes from pagerank × log(complexity). |
isLoading / isValidating |
boolean |
yes | First-load skeleton vs. load-more spinner. |
hasMore |
boolean |
yes | Renders the Load-more button. |
q / onQChange |
string / (v) => void |
yes | Search query. Caller debounces before driving the fetch. |
kind / onKindChange |
string / (v) => void |
yes | Filter union; "all" is the off state. |
language / onLanguageChange |
string / (v) => void |
yes | Same as kind. |
onLoadMore |
() => void |
yes | Wired to the SWR setSize increment. |
onSelect |
(sym: CodeSymbol) => void |
yes | Caller drives the drawer state. |
drawer |
ReactNode |
no | Caller renders <SymbolDrawer> with its own data wiring. |
wiki/code-block — CodeBlock
Server-rendered fenced code block. The caller passes pre-highlighted HTML (e.g. from Shiki) plus the raw code for copy-to-clipboard.
| Prop | Type | Required | Notes |
|---|---|---|---|
code |
string |
yes | Raw text used for the copy action. |
language |
string |
no | Shown in the header bar. |
html |
string |
yes | Trusted HTML, set via dangerouslySetInnerHTML. |
wiki/confidence-badge — ConfidenceBadge
Coloured pill showing freshness status (fresh / stale / outdated).
Computes status from score unless status is supplied. When stale
with staleSince, wraps in a tooltip exposing the date and confidence.
| Prop | Type | Required |
|---|---|---|
score |
number (0–1) |
yes |
status |
string |
no |
showScore |
boolean |
no |
staleSince |
string | null |
no |
className |
string |
no |
wiki/backlinks-panel — BacklinksPanel
Sidebar panel listing pages that link into the current page. Renders nothing when the backlink list is empty.
| Prop | Type | Required | Notes |
|---|---|---|---|
backlinks |
Backlink[] (wiki/wiki-links-types) |
yes | From page.metadata.backlinks. |
repoId |
string |
yes | |
limit |
number |
no | Default 6; remainder collapses to "+N more". |
buildHref |
(repoId, pageId) => string |
no | Default /repos/{id}/wiki/{pageId}. |
renderLink |
({ href, className, title, children }) => ReactNode |
no | Plug a router link; defaults to <a>. |
wiki/git-history-panel — GitHistoryPanel
Sidebar panel summarising file lifecycle, fix history, commit categories, top authors with bars, co-change partners, and recent commits.
The Age row needs at least one recorded commit before it will render a zero
age, because formatAgeDays(0) reads "< 1 day" and age_days is stored NOT
NULL with a 0 default — so a file whose git indexing never completed is
otherwise indistinguishable from one created today. Author shares fall back to
commit_count / commit_count_total when a row carries no pct, which is what
the file-detail endpoint serves.
| Prop | Type | Required |
|---|---|---|
git |
GitMetadata (@repowise-dev/types/git) |
yes |
wiki/mermaid-diagram — MermaidDiagram
Client-side mermaid renderer with dynamic import to avoid SSR. Uses a dark theme matched to the design tokens. Failures render an inline error card.
| Prop | Type | Required |
|---|---|---|
chart |
string |
yes |
wiki/table-of-contents — TableOfContents
Extracts #/##/### headings from a markdown string and renders an
anchor list. An IntersectionObserver highlights the active heading.
Returns null when fewer than two headings are found.
| Prop | Type | Required |
|---|---|---|
content |
string |
yes |
graph/* — Graph layout, presentation, and chrome
Presentational graph pieces — chrome (toolbar/legend/sidebar/menu),
ELK layout primitives, and @xyflow/react node/edge components.
State reaches the canvas as props; there is no graph context.
graph-flow and the panels (graph-doc-panel, graph-community-panel,
path-finder-panel) live HERE as presentational shells; packages/web
hosts thin wrappers that orchestrate the useGraph* SWR hooks and pass
the datasets in. The canvas renders via Sigma (graph/sigma/), not
@xyflow/react (the xyflow node/edge components remain for the module
browser and embedded views).
graph/context — Signal
Shared graph vocabulary. Signal is the overlay-toggle union
("dead" | "hot" | "architecture" | "hideTests").
This module used to export a GraphContext / GraphProvider /
useGraphContext / GraphContextValue trio mirroring ~18 fields of
graph-flow's state. It had no consumers — every field already reaches
the canvas as a prop, and Sigma owns hover and highlight itself — so the
provider only re-rendered the shell and rebuilt an 18-key object on every
interaction. Removed rather than kept "just in case": a second path to
the same state would only drift from the props.
graph/elk-layout and graph/use-elk-layout
Pure layout primitives. Functions: layoutFileGraph,
layoutModuleGraph, groupNodesAsModules. Hooks:
useFileElkLayout, useModuleElkLayout. Operate on canonical
@repowise-dev/types/graph shapes (GraphNode, GraphLink,
ModuleNode, ModuleEdge) and produce @xyflow/react Node[] /
Edge[]. No data fetching.
graph/nodes/*, graph/edges/*
FileNode, ModuleGroupNode, DependencyEdge — @xyflow/react
node/edge renderers. Receive selection / path-highlight state as props.
Wear FileNodeData / ModuleNodeData / DependencyEdgeData types from
graph/elk-layout.
There is no React tooltip component. The hover card users see on the
Sigma canvas is painted by defaultDrawNodeHover in
graph/sigma/use-sigma.ts, not rendered as DOM.
graph/graph-context-menu — GraphContextMenu
Floating right-click menu rendered at (x, y). Pure UI; the host
wires the four action callbacks.
| Prop | Type | Required |
|---|---|---|
x, y |
number |
yes |
nodeId |
string |
yes |
isModule |
boolean |
yes |
onViewDocs / onExplore / onPathFrom / onPathTo |
() => void |
yes |
graph/graph-toolbar — GraphToolbar
Top-right toolbar exposing view mode, color mode, hide-tests toggle,
fit-view, path-finder toggle, flows toggle, and a search input. Also
exports the ColorMode (language / community / risk) and
ViewMode (module / full / architecture / dead / hotfiles)
unions consumed by GraphLegend and the host.
| Prop | Type | Required |
|---|---|---|
viewMode / onViewChange |
ViewMode / (v) => void |
yes |
colorMode / onColorModeChange |
ColorMode / (v) => void |
yes |
hideTests / onHideTestsChange |
boolean / (v) => void |
yes |
onFitView |
() => void |
yes |
showPathFinder / onTogglePathFinder |
boolean / () => void |
yes |
showFlows / onToggleFlows |
boolean / () => void |
yes |
searchQuery / onSearchChange |
string / (q) => void |
yes |
graph/graph-legend — GraphLegend
Collapsible legend that picks a key per colorMode. Imports the
ColorMode and ViewMode types from graph-toolbar.
| Prop | Type | Required |
|---|---|---|
nodeCount / edgeCount |
number |
yes |
colorMode |
ColorMode |
yes |
viewMode |
ViewMode |
yes |
communityLabels |
Map<number, string> |
no |
workspace/* — Multi-repo workspace views
Five presentational components that consume the canonical workspace
shapes from @repowise-dev/types/workspace.
workspace/contract-type-badge — ContractTypeBadge, RoleBadge
Inline pill badges for contract type (http, grpc, topic, …) and
role (provider / consumer).
| Component | Prop | Type |
|---|---|---|
ContractTypeBadge |
type |
string |
RoleBadge |
role |
string |
workspace/repo-card — RepoCard
Tile linking to /repos/{id}/overview with file count, doc confidence,
hotspot count, and a primary indicator.
| Prop | Type | Required |
|---|---|---|
repoId |
string |
yes |
alias |
string |
yes |
name |
string |
yes |
path |
string |
yes |
isPrimary |
boolean |
yes |
stats |
RepoStats | null (@repowise-dev/types/workspace) |
yes |
gitSummary |
GitSummary | null (@repowise-dev/types/git) |
yes |
workspace/co-change-table — CoChangeTable
Sortable cross-repo co-change table.
| Prop | Type | Required | Notes |
|---|---|---|---|
coChanges |
WorkspaceCoChangeEntry[] |
yes | |
compact |
boolean |
no | Drops the frequency and last-date columns. |
workspace/contract-links-table — ContractLinksTable
Provider/consumer table for matched contract links with confidence bars colour-graded against the freshness thresholds.
| Prop | Type | Required |
|---|---|---|
links |
WorkspaceContractLinkEntry[] |
yes |
workspace/cross-repo-summary — CrossRepoSummary
Four-tile summary header (MetricCard × 4) for co-change pairs, package
deps, contract links, and contract count.
| Prop | Type | Required |
|---|---|---|
crossRepo |
WorkspaceCrossRepoSummary | null |
yes |
contracts |
WorkspaceContractSummary | null |
yes |
dashboard/* — Repo overview tiles
Presentational tiles that consume canonical engine artifacts. The
formerly data-coupled trio (active-job-banner, quick-actions,
community-summary-grid) now lives here as shells (documented under
"Phase 2C" below); their SWR wrappers live in packages/web.
UX-overhaul additions: dashboard/health-score-badge
(HealthScoreBadge — compact header twin of HealthScoreRing: score
chip + code-health trend sparkline + click-toggled breakdown),
dashboard/where-to-start (WhereToStartCard — onboarding targets,
rows link to the canonical file pages), and dashboard/commits-mini
(CommitsMini — recent-commits feed for the Overview Pulse tab; rows
link to /commits?commit=). SavingsMini accepts the structural
SavingsMiniData slice (the overview-summary savings headline fits);
DecisionsTimeline accepts the structural DecisionsTimelineItem.
files/* — File entity page
The canonical "everything about this file" page used by
/repos/[id]/files/<path>. symbols/symbol-page (SymbolPage) is the
symbol-page sibling fed by SymbolDetailResponse.
The page is four pieces, not one component, and the split is the
hydration boundary. A host composes them; it does not hand a
FileDetailResponse to a client component.
| Piece | Where it runs | Job |
|---|---|---|
FilePageHeader |
server | Eyebrow, path as identity, the PageLede figure, the marker row, the StatRibbon. |
fileTabsFor(data) |
server | The tab row as FileTabDef[] — label, blurb, badge. resolveFileTab narrows a ?tab= value against it. |
buildFilePanels({...}) |
server | Renders the six pure tab bodies and returns them keyed by tab id. Takes healthPanel as an already-wrapped node. |
FilePage |
client | The shell: header slot, ViewTabs, active panel. Imports ViewTabs and nothing else from the slice. |
FilePage used to be "use client" and import all seven tab bodies, so
the whole slice plus a twice-serialised FileDetailResponse reached the
browser to render one tab. file-health-tab is now the only file in
files/* carrying "use client" — it owns triage state, two virtualised
lists and a measured trend. Because its triage callback and href builders
are functions, a host wraps it itself and passes the result in as
healthPanel; that wrapper is the page's only client boundary besides
the shell.
Two consequences a host must honour:
- Key the shell on the file path. Tab clicks are a shallow
history.replaceState, so a soft navigation from one file page to another keeps React's state at the same tree position and strands the active tab out of sync with the URL. Every cross-file link in the tab bodies is a plain<a>today, which hides this; converting one to a router link without the key surfaces it. fields=slimis the default fetch. Only Documentation, Health and Coverage read the four unbounded blocks the aggregate can drop, so the route fetches slim unless the requested tab is one of those, and tells the shell throughrefetchTabswhich tabs need a round trip on first click. A tab with nothing behind it is left out of that list rather than buying a trip to be shown the same empty state.
Bands come from bandForScore (@repowise-dev/types/health), never from a
threshold of the page's own — this page sits one click from the treemap and
the health map, and all three paint the same five bands.
The doors, and who owns each end. The page had thirty surfaces linking into it and almost nothing linking out, and the docs surface — the one that knows a page documents this exact path — linked to it zero times.
FilePageHeadertakeswikiHref. It used to live in the Doc tab, which made the only link to the wiki reachable only from the tab that already renders the wiki. Pass it only when a page exists — this route already knows, and the reader's missing-page reply is for someone who typed the id, not for a link the product offered. It reads "Read in Docs", naming the surface the nav names: "Documentation" is the tab forty pixels below it, and two controls with near enough one name, one staying and one leaving, is the two-verbs-one-subject problem relocated rather than fixed.DocsReadertakesbuildFileHref, and renders the door only for afile_page.page.target_pathis the repo-relative path the file route takes, so nothing parses an id. Optional, so a host with no file route (the VS Code webview) renders no door rather than a broken one.buildFilePanelsforwardsLinkComponentto Overview, History, Decisions and Dependencies. This does not move the hydration boundary: anext/linkelement rendered from a server component is still server markup. AnonClickwould not be — that is what would drag a body back into the client bundle.- Because those cross-file links are soft navigations now, the shell's
keyon the file path is load-bearing rather than defensive. Without it a file → file click keeps React's tab state at the same tree position and strands the active tab out of sync with the URL.
Route builders are fileEntityPath, symbolEntityPath, filePageId and
docsPagePath from shared/entity. filePageId exists because the
"file_page:<path>" id has to agree with a backend primary key and was
spelled out at five call sites; pageHref derives its parse prefix from the
builder so the two cannot drift. The docs surface reads ?page=, never
?file= — three surfaces shipped a ?file= link that nothing read, which
meant they silently opened the repo overview and looked like they had worked.
Repointing them at ?page= puts real traffic on ids that resolve to nothing,
because page selection is budgeted and most files have no page. So
DocsReader takes missingPageId and answers by naming the page that is
missing, instead of the "Select a page, choose one from the tree" prompt meant
for a reader who asked for nothing. docs-explorer sets it only once the
fetch has settled, or the line flashes over a request about to succeed. It
deliberately does not fall back to the overview: a reader who asked about
one file must not silently land in another file's prose.
dashboard/attention-panel — AttentionPanel
Categorised list of items needing developer attention. Re-exports the
AttentionItem type so packages/web's health-score.ts can derive
items without recomputing the shape.
| Prop | Type | Required |
|---|---|---|
items |
AttentionItem[] |
yes |
repoId |
string |
yes |
dashboard/decisions-timeline — DecisionsTimeline
Top-6 most recent decisions with status dots and a "view all" link.
| Prop | Type | Required |
|---|---|---|
decisions |
DecisionRecord[] (@repowise-dev/types/decisions) |
yes |
repoId |
string |
yes |
dashboard/dependency-heatmap — DependencyHeatmap
20×20 canvas heatmap of module-to-module edge counts. Modules sorted
by avg_pagerank. Returns null when fewer than two modules are
available.
| Prop | Type | Required |
|---|---|---|
moduleGraph |
ModuleGraph (@repowise-dev/types/graph) |
yes |
dashboard/execution-flows-panel — ExecutionFlowsPanel
Top-8 execution flows with collapsible call traces. repoId is
accepted for parity with other dashboard tiles but currently unused.
| Prop | Type | Required |
|---|---|---|
flows |
ExecutionFlowEntry[] (@repowise-dev/types/graph) |
yes |
repoId |
string |
yes |
dashboard/health-score-ring — HealthScoreRing
Animated framer-motion SVG ring showing 0–100 score with text label.
| Prop | Type | Required |
|---|---|---|
score |
number (0–100) |
yes |
size |
number |
no, default 160 |
dashboard/hotspots-mini — HotspotsMini
Top-5 hotspots tile.
| Prop | Type | Required |
|---|---|---|
hotspots |
Hotspot[] (@repowise-dev/types/git) |
yes |
repoId |
string |
yes |
dashboard/language-donut — LanguageDonut
Top-6 languages-by-file-count donut with grouped "other" bucket.
| Prop | Type | Required |
|---|---|---|
distribution |
Record<string, number> |
yes |
dashboard/module-minimap — ModuleMinimap
Force-directed module graph using d3-force. Doc-coverage colours
the nodes. The simulation runs synchronously for small graphs (≤150
ticks) and re-renders once the layout converges.
| Prop | Type | Required |
|---|---|---|
nodes |
ModuleNode[] (@repowise-dev/types/graph) |
yes |
edges |
ModuleEdge[] (@repowise-dev/types/graph) |
yes |
repoId |
string |
yes |
dashboard/ownership-treemap — OwnershipTreemap
d3-hierarchy treemap colouring rectangles by primary owner; silos
render at lower opacity. Distinct from git/ownership-treemap —
this variant is the dashboard tile (Card-wrapped, fixed height,
legend below).
| Prop | Type | Required |
|---|---|---|
entries |
OwnershipEntry[] (@repowise-dev/types/git) |
yes |
chat/* — Conversation rendering primitives
The chat UI types are sourced from @repowise-dev/types/chat —
ChatUIMessage and ChatUIToolCall are the post-streaming flattened
shapes consumed by these components. The wire types (ChatMessage,
ChatToolCall) live in the same module; consumers are expected to
keep the SSE merge in their own data layer.
chat/chat-markdown — ChatMarkdown
Compact markdown renderer (react-markdown + remark-gfm) tuned for
chat density. Code fences are inline <pre><code> blocks — no copy
affordance.
| Prop | Type | Required |
|---|---|---|
content |
string |
yes |
chat/tool-call-block — ToolCallBlock
Collapsible card showing a single tool invocation. Friendly labels for
known tool names; falls back to the raw name. Shows a "View" button
that fires onViewArtifact when an artifact is attached.
| Prop | Type | Required |
|---|---|---|
toolCall |
ChatUIToolCall (@repowise-dev/types/chat) |
yes |
onViewArtifact |
() => void |
no |
chat/source-citations — SourceCitations
Renders an inline list of source-page links extracted from
tool_calls[]. Also exports extractSources(toolCalls, repoId) for
callers that need the same shape outside of rendering. Uses plain
<a> (no Next-only Link) so the package stays framework-neutral —
consumers wire prefetching at the parent level if needed.
| Prop | Type | Required |
|---|---|---|
toolCalls |
ChatUIToolCall[] |
yes |
repoId |
string |
yes |
chat/chat-message — ChatMessage
Renders one user or assistant turn: avatar, message bubble for user,
tool-call cards + markdown + citations for assistant. Streaming
indicator shows when message.isStreaming and there's no text yet.
| Prop | Type | Required | Notes |
|---|---|---|---|
message |
ChatUIMessage |
yes | |
repoId |
string |
yes | Forwarded to SourceCitations for link targets. |
onViewArtifact |
(artifact: { type; data }) => void |
no | Wired through to ToolCallBlock when an artifact is attached. |
assistantAvatarSrc |
string |
no | Defaults to /repowise-logo.png. Override in consumers that don't host that asset. |
chat/artifact-panel — ArtifactPanel
Right-edge slide-over panel. Switches on artifact.type to pick a
renderer: markdown for overview / wiki_page, mermaid (via
@repowise-dev/ui/wiki/mermaid-diagram) for diagram, list for
search_results, JSON pretty-print fallback otherwise.
| Prop | Type | Required |
|---|---|---|
artifacts |
Artifact[] (locally-defined wrapper: { type; title; data }) |
yes |
open |
boolean |
yes |
onClose |
() => void |
yes |
wiki/wiki-markdown — WikiMarkdown
Client-side markdown renderer (react-markdown + remark-gfm) with
slugged heading anchors, copy-on-hover code blocks, and inline
MermaidDiagram for \``mermaid` fences.
| Prop | Type | Required |
|---|---|---|
content |
string |
yes |
blast-radius/* — PR impact analysis shells
Pure presentational shells for the blast-radius view. Data fetching,
input form, and SWR hotspot suggestions stay in the consumer page;
these components only render BlastRadiusResponse (from
@repowise-dev/types/blast-radius).
blast-radius/risk-score-card — RiskScoreCard
Structural-impact gauge. The server-owned band is broad, moderate, or
localized; the value is an uncalibrated 0–10 heuristic, not a probability.
| Prop | Type | Required |
|---|---|---|
score |
number (0–10) |
yes |
band |
"localized" | "moderate" | "broad" |
no |
blast-radius/table-section — TableSection
Card wrapper with title and "empty" placeholder.
| Prop | Type | Required |
|---|---|---|
title |
string |
yes |
empty |
boolean |
yes |
emptyLabel |
string (defaults to "None") |
no |
children |
ReactNode |
yes |
blast-radius/direct-risks-table — DirectRisksTable
Renders DirectRiskEntry[]. structural_score is the raw, unbounded
pagerank-weighted-hotspot heuristic and is displayed in those units. Bars use
within-change relative share only; they do not invent a 0–10 scale.
| Prop | Type | Required |
|---|---|---|
rows |
DirectRiskEntry[] |
yes |
blast-radius/transitive-table — TransitiveTable
Two-column path + dependency depth.
| Prop | Type | Required |
|---|---|---|
rows |
TransitiveEntry[] |
yes |
blast-radius/cochange-table — CochangeTable
Three-column changed file / missing partner / score.
| Prop | Type | Required |
|---|---|---|
rows |
CochangeWarning[] |
yes |
blast-radius/reviewers-table — ReviewersTable
Email + files-owned + percent ownership. ownership_pct is 0–1.
| Prop | Type | Required |
|---|---|---|
rows |
ReviewerEntry[] |
yes |
blast-radius/test-gaps-list — TestGapsList
Compatibility list of file-level test gaps. It is not a measured-coverage
claim; consumers use result.test_impact for typed recommendations, evidence
basis, and coverage availability.
| Prop | Type | Required |
|---|---|---|
gaps |
string[] |
yes |
blast-radius/blast-radius-summary — BlastRadiusSummary
Four-stat card sitting beside RiskScoreCard (Direct Risks /
Transitive Files / Co-change Warnings / Test Gaps).
| Prop | Type | Required |
|---|---|---|
result |
BlastRadiusResponse |
yes |
blast-radius/blast-radius-results — BlastRadiusResults
Composes the full results stack: gauge, summary, impact map, typed test
recommendations with measured/inferred basis, explicit unavailable-analysis
copy, and the compatibility tables. test_impact is optional in the shared
TypeScript contract so the component remains compatible with older servers.
| Prop | Type | Required |
|---|---|---|
result |
BlastRadiusResponse |
yes |
Phase 2C — dashboard wrappers + settings shells
dashboard/active-job-banner — ActiveJobBanner
Slim status strip for the latest indexing/generation job. Wrapper owns SWR polling + freshness window; the shell is given a snapshot.
| Prop | Type | Required |
|---|---|---|
job |
Job | null |
yes |
detailsHref |
string |
no |
Job is canonical (@repowise-dev/types/jobs). When job is null
or pending, the banner renders nothing — the wrapper is responsible
for filtering out terminal states older than its freshness window.
dashboard/quick-actions — QuickActions
Three-button action bar (sync / full-resync / dead-code) with confirm dialog and inline cost estimate. Pure presentational — mutations are a callback bag.
| Prop | Type | Required |
|---|---|---|
onAction |
(key: QuickActionKey) => Promise<void> | void |
yes |
actions |
QuickActionDef[] |
no (defaults to the three baked-in) |
loadingKey |
QuickActionKey | null |
no |
lastSyncAt |
string | null |
no |
lastResyncAt |
string | null |
no |
pageCount |
number |
no |
modelName |
string |
no |
activeJobSlot |
ReactNode |
no — when set, replaces the buttons |
dashboard/community-summary-grid — CommunitySummaryGrid
Architecture-community list with expandable detail panel. The wrapper
owns useCommunityDetail; the shell receives resolved details keyed by
community_id.
| Prop | Type | Required |
|---|---|---|
communities |
CommunitySummaryItem[] |
yes |
details |
Record<number, CommunityDetail | null> |
no |
loadingDetailId |
number | null |
no |
onExpand |
(communityId: number) => void |
no |
CommunitySummaryItem and CommunityDetail are canonical types in
@repowise-dev/types/graph.
settings/general-form — GeneralForm
Universal repo-settings editor (name, default branch, exclude
patterns). Read-only when onSubmit is omitted — used by hosted, where
multi-tenant settings persistence is deferred to Phase 5 RBAC.
| Prop | Type | Required |
|---|---|---|
value |
RepoSettingsValue |
yes |
onSubmit |
(next: RepoSettingsValue) => Promise<void> |
no |
autosave |
boolean (saves each field on commit, rolls back when onSubmit rejects) |
no |
localPath |
string |
no |
remoteUrl |
string |
no |
disabledHint |
string |
no |
RepoSettingsValue lives in @repowise-dev/types/settings.
chat/conversation-history — ConversationHistory
Dropdown listing prior conversations for a repo with select / delete /
new-conversation affordances. The wrapper owns the SWR fetch
(listConversations) and the delete mutation; the shell only renders
the popover surface and emits intents.
| Prop | Type | Required | Notes |
|---|---|---|---|
conversations |
Conversation[] | undefined |
yes | undefined while loading. |
isLoading |
boolean |
no | Renders a "Loading…" placeholder when no list is yet available. |
selectedId |
string | null |
no | Highlights the matching row. |
onSelect |
(id: string) => void |
yes | Fires when a row is clicked. |
onDelete |
(id: string) => void | Promise<void> |
yes | Fires when a row's trash icon is clicked. |
onNew |
() => void |
yes | Fires when "New conversation" is clicked. |
className |
string |
no | Forwarded to the outer container. |
Conversation is canonical (@repowise-dev/types/chat).
chat/chat-interface — ChatInterface
Top-level chat surface. Renders empty-state suggestion chips when
messages is empty, otherwise a scrollable transcript above a
textarea composer. Owns the artifact-panel state internally; transport
(SSE / federated / mock), history dropdown, and model selector are
wired by the wrapper as opaque slots.
| Prop | Type | Required | Notes |
|---|---|---|---|
repoId |
string |
yes | Forwarded to ChatMessage for citation hrefs. |
repoName |
string |
no | Used in the empty-state heading. |
messages |
ChatUIMessage[] |
yes | UI-flattened transcript. |
isStreaming |
boolean |
yes | Toggles Send → Stop in the composer. |
error |
string | null |
no | Inline banner above the transcript. |
onSend |
(text: string) => void | Promise<void> |
yes | Fires when the user submits. |
onCancel |
() => void |
yes | Fires when the user clicks Stop; also used as "reset" in the wrapper. |
modelSelectorSlot |
ReactNode |
no | Rendered in the header bar AND empty-state composer. |
historySlot |
ReactNode |
no | Rendered in the header bar AND empty-state composer. |
assistantAvatarSrc |
string |
no | Forwarded to ChatMessage. |
buildCitationHref |
(source: SourceReference) => string |
no | Forwarded to ChatMessage → SourceCitations. |
emptyStateLogoSrc |
string |
no | Defaults to /repowise-logo.png. |
suggestions |
string[] |
no | Override default empty-state chip set. |
ChatUIMessage is canonical (@repowise-dev/types/chat). Downstream
consumers can wire a different transport (e.g. a multi-repo fan-out
streaming endpoint) into the same shell by substituting the wrapper —
that swap validates the data/presentation split.
wiki/security-panel — SecurityPanel
Renders a list of security findings (or an empty-state message) for a
single file. Wrapper owns the useSWR(["security", repoId, filePath], …)
fetch from listSecurityFindings.
| Prop | Type | Required | Notes |
|---|---|---|---|
findings |
SecurityFinding[] | undefined |
yes | Empty / undefined → "No security signals." |
isLoading |
boolean |
no | While loading the shell renders nothing. |
SecurityFinding is canonical (@repowise-dev/types/security).
wiki/regenerate-button — RegenerateButton
Per-page regenerate affordance: a ghost button + a dialog that hosts a
job-progress widget. Wrapper owns regeneratePage, sonner toasts,
SWR cache invalidation, and the in-flight job id.
| Prop | Type | Required | Notes |
|---|---|---|---|
onRegenerate |
() => void |
yes | Fires when the user clicks regenerate. |
isLoading |
boolean |
no | Spinner + disabled while the request is in flight. |
isInProgress |
boolean |
no | When true, the progress dialog is open. |
onDialogClose |
() => void |
no | Fires when the dialog requests to close. |
jobSlot |
ReactNode |
no | Rendered inside the dialog — typically a job-progress widget. |
wiki/version-history — VersionHistory
Collapsible per-page version-history panel with an inline LCS-based
diff view. Wrapper owns the usePageVersions(pageId) SWR hook; the
shell owns expand / select / show-diff UI state and the computeLineDiff
helpers.
| Prop | Type | Required | Notes |
|---|---|---|---|
versions |
DocPageVersion[] |
yes | Archived prior versions, newest-first. |
currentVersion |
number |
yes | Version number of the currently-rendered page. |
currentContent |
string |
yes | Content used as the "new" side of the diff view. |
isLoading |
boolean |
no | While loading or empty the shell renders nothing. |
DocPageVersion is canonical (@repowise-dev/types/docs).
graph/graph-doc-panel — GraphDocPanel
Side-panel that renders a wiki page for a graph node. Presentational —
the consumer fetches the DocPage and supplies routing hrefs.
| Prop | Type | Required | Notes |
|---|---|---|---|
nodeId |
string |
yes | Used in the header subtitle when no page.title is available. |
page |
DocPage | null | undefined |
yes | Pre-fetched wiki page. |
isLoading |
boolean |
yes | Drives the spinner state. |
error |
unknown |
no | Truthy renders the empty state. |
fullPageHref |
string |
no | When provided, renders the "open full page" external-link icon. |
browseDocsHref |
string |
no | Fallback link inside the empty state. |
onClose |
() => void |
yes | Close affordance handler. |
DocPage is canonical (@repowise-dev/types/docs).
graph/graph-community-panel — GraphCommunityPanel
Side-panel that lists a Leiden community's members + neighboring communities. Presentational — consumer fetches the detail.
| Prop | Type | Required | Notes |
|---|---|---|---|
communityId |
number |
yes | Surfaced in the header fallback when community is null. |
community |
CommunityDetail | null | undefined |
yes | Pre-fetched detail; null while loading or missing. |
isLoading |
boolean |
yes | Drives the skeleton state. |
onClose |
() => void |
yes | Close affordance handler. |
CommunityDetail is canonical (@repowise-dev/types/graph).
graph/path-finder-panel — PathFinderPanel
Floating panel for picking two nodes and asking the engine for a path
between them. Presentational — the consumer injects the search and
path-find callbacks; the shell owns input + dropdown state and uses
the useDebounce presentational hook for autocomplete.
| Prop | Type | Required | Notes |
|---|---|---|---|
searchNodes |
(query: string, limit: number) => Promise<NodeSearchResult[]> |
yes | Backs the autocomplete dropdown. |
findPath |
(from: string, to: string) => Promise<GraphPath> |
yes | Resolves the highlighted path. |
onPathFound |
(pathNodes: string[]) => void |
yes | Handed the resolved node ids. |
onClear |
() => void |
yes | Called when the user clears prior results. |
onClose |
() => void |
yes | Close affordance handler. |
initialFrom |
string |
no | Pre-fill from a parent context-menu. |
initialTo |
string |
no | Pre-fill from a parent context-menu. |
NodeSearchResult and GraphPath are canonical (@repowise-dev/types/graph).
graph/code-graph-tree — CodeGraphTree
The dependency graph as a collapsible outline. Presentational: it takes
one file-level GraphExport payload and owns nothing but which rows
are open. Directories are derived from the node paths, external: and
framework: nodes are skipped as rows (no page behind them) but kept as
import targets, and each file row opens in place to list the types it
imports and the file each one comes from, read straight off the payload's
imported_names.
Only file-to-file edges count: the module's
CODE_GRAPH_DEPENDENCY_EDGE_TYPES mirrors the engine's
FILE_DEPENDENCY_EDGE_TYPES, so a co_changes row (history, not code)
never appears as an import.
| Prop | Type | Required | Notes |
|---|---|---|---|
graph |
GraphExport | null | undefined |
yes | undefined while the first fetch is in flight. |
isLoading |
boolean |
no | Renders the skeleton instead of the empty state. |
fileHref |
(path: string) => string |
no | File entity page href. Rows and targets render no link without it. |
LinkComponent |
ElementType |
no | Router link; defaults to <a>. |
className |
string |
no |
Also exported: buildCodeGraphTree(nodes, links) (the pure builder),
collectDirectoryIds, summarizeFileImports, and the
CodeGraphTreeItem / CodeGraphFile / CodeGraphImport types.
graph/graph-flow — GraphFlow
The full graph canvas. Presentational shell over Sigma that handles
view-mode, drill-down, search, hover/selection, context menu,
execution-flow highlighting, constellation hubs, and layout. The
consumer supplies every dataset (one per view mode) and renders the
data-coupled child panels (path-finder, community-panel) via slot
render props. The component does NOT read window.location — initial
URL-derived state arrives via initialViewMode / initialColorMode /
initialSelectedNode.
| Prop | Type | Required | Notes |
|---|---|---|---|
moduleGraph |
ModuleGraph | undefined |
yes | Top-level module rollup; only required for module view at root. |
isLoadingModuleGraph |
boolean |
yes | Drives the skeleton when in module view. |
fullGraph |
GraphExport | undefined |
yes | File-level graph — needed for drill-down and full view. |
isLoadingFullGraph |
boolean |
yes | |
architectureGraph |
GraphExport | undefined |
yes | Entry-point / architecture view. |
isLoadingArchitectureGraph |
boolean |
yes | |
deadCodeGraph |
GraphExport | undefined |
yes | Dead-code-only graph. |
isLoadingDeadCodeGraph |
boolean |
yes | |
hotFilesGraph |
GraphExport | undefined |
yes | Hot-files-only graph. |
isLoadingHotFilesGraph |
boolean |
yes | |
communities |
CommunitySummaryItem[] |
no | Used for the legend's community labels. |
executionFlows |
ExecutionFlows |
no | Backs the flows side panel + trace highlighting. |
constellationGraph / constellationSlices / onExpandedHubsChange |
see types | no | Radial Knowledge-Graph scope: community super-graph, expanded-hub member slices, and the fetch trigger. |
initialViewMode |
ViewMode |
no | Initial scope (incl. dead / hotfiles / unified, which seed the signal overlays). |
initialColorMode |
ColorMode |
no | Initial node color mode; hosts derive it from their URL state. |
initialSelectedNode |
string | null |
no | Pre-selected node (e.g. ?node=). |
onViewModeChange |
(mode: ViewMode) => void |
no | Fires when the user changes view; consumer uses this to toggle data fetches. |
onModulePathChange |
(path: string[]) => void |
no | Fires on drill-down navigation. |
onNodeClick |
(nodeId, nodeType) => void | Promise<void> |
no | File click handler. |
onNodeViewDocs |
(nodeId: string) => void |
no | "View docs" intent — surface a side panel. |
renderPathFinder |
(props) => ReactNode |
no | Render slot for the path-finder sub-panel; the shell only owns when to mount it. |
renderCommunityPanel |
(props) => ReactNode |
no | Render slot for the community detail sub-panel. |
All graph datasets are canonical (@repowise-dev/types/graph).