feat(ui): the viewer's screens as @colbymchenry/codegraph-ui, behind one adapter (CG-61)
`ui/src` now builds two ways from one tree: the static app `codegraph ui` serves, and — via `svelte-package` — a Svelte library the Pro app imports. A forked component would be a second answer to the same question about the same graph, so there is no fork. Everything a screen knows arrives through a `GraphAdapter`: eleven methods answering the wire shapes verbatim, with `createHttpAdapter()` (the loopback JSON API) as the default and a host's in-process engine reads as the point. `lib/api.ts` became a one-line-per-call facade over it, which is why no call site in the views changed. The payload types moved to `lib/wire.ts` — no imports, no runtime — so a host can depend on the vocabulary alone. Two more seams and one guard: - `lib/navigation.ts` holds the href builders behind a `NavigationDriver`, so a host addresses its own URL space. The app's half — the hash parser and the live route, which attach window listeners at module scope — stays in `router.svelte.ts` and is pruned out of the package: rendering a Symbol view must not install a hash router in somebody else's application. - `lib/theme.css` carries the design tokens and maps Svelte Flow's `--xy-*` variables onto them, so a host never sees library defaults. Dark now also answers to a bare `[data-theme]`, which is how `<CodegraphUi theme>` themes a container rather than the document. - `scripts/check-ui-package.mjs` prunes the app's shell, resolves the extensionless specifiers svelte-package leaves behind, and asserts that nothing but `lib/adapter.js` reaches the network. The search box, its keyboard and its panel are one component now (`SearchPalette`), because splitting them is what breaks a palette. `__tests__/ui-package.test.ts` mounts the three screens from the package entry against a mock adapter in jsdom; it runs as a second vitest project so the `browser` resolve condition it needs cannot reach the engine's suites. Versioned with the engine. Prepared, not published: `private: true` is the guard and `pack-npm.sh` only packs a tarball under CODEGRAPH_PACK_UI=1.
This commit is contained in:
Colby McHenry
+221
@@ -0,0 +1,221 @@
|
||||
/**
|
||||
* `@colbymchenry/codegraph-ui` — the CodeGraph reader as Svelte components.
|
||||
*
|
||||
* The same Symbol view, Flow strip and Map that `codegraph ui` serves, behind
|
||||
* one seam: a {@link GraphAdapter}. The CLI's viewer runs them on
|
||||
* {@link createHttpAdapter} (the read-only JSON API over loopback); a host that
|
||||
* already holds the index — CodeGraph Pro, which opens it in-process — installs
|
||||
* its own adapter and renders the identical components over its own reads.
|
||||
* Nothing is forked, so the two can never draw different answers from the same
|
||||
* graph.
|
||||
*
|
||||
* ```svelte
|
||||
* <script>
|
||||
* import { CodegraphUi, SymbolView, FlowStrip, ArchitectureMap }
|
||||
* from '@colbymchenry/codegraph-ui';
|
||||
* import '@colbymchenry/codegraph-ui/theme.css';
|
||||
* </script>
|
||||
*
|
||||
* <CodegraphUi adapter={myAdapter} nav={myNavigation}>
|
||||
* <SymbolView id={symbolId} line={null} />
|
||||
* </CodegraphUi>
|
||||
* ```
|
||||
*
|
||||
* Three things a host has to know, all of them in the docs and repeated here
|
||||
* because they are the ones that bite:
|
||||
*
|
||||
* 1. **Import `theme.css` once.** Every component paints from the design
|
||||
* tokens; without them the screens render as unstyled ink on white. Override
|
||||
* any variable on a narrower selector.
|
||||
* 2. **The adapter is module-level, not context.** The pure model modules are
|
||||
* plain TypeScript and cannot read a component's context, so one page reads
|
||||
* one project. `<CodegraphUi>` installs it during initialisation.
|
||||
* 3. **Geometry is not themable.** 34px rail rows, 300/320px rails, the 20px
|
||||
* code line: the Symbol view measures these against each other to put a
|
||||
* callee row beside the line that calls it. Colour and type are yours.
|
||||
*/
|
||||
|
||||
/* ------------------------------------------------------------ the seams -- */
|
||||
|
||||
export { default as CodegraphUi } from './components/CodegraphUi.svelte';
|
||||
|
||||
export {
|
||||
ApiFailure,
|
||||
createHttpAdapter,
|
||||
getGraphAdapter,
|
||||
setGraphAdapter,
|
||||
} from './lib/adapter';
|
||||
export type {
|
||||
EntryPointsRequest,
|
||||
FlowRequest,
|
||||
GraphAdapter,
|
||||
HttpAdapterOptions,
|
||||
LiveHandlers,
|
||||
MapRequest,
|
||||
RoutesRequest,
|
||||
SearchRequest,
|
||||
SourceRequest,
|
||||
} from './lib/adapter';
|
||||
|
||||
export {
|
||||
back,
|
||||
entryHref,
|
||||
fileHref,
|
||||
flowHref,
|
||||
getNavigationDriver,
|
||||
hashNavigation,
|
||||
mapHref,
|
||||
navigate,
|
||||
setNavigationDriver,
|
||||
symbolHref,
|
||||
} from './lib/navigation';
|
||||
export type {
|
||||
FileHrefOptions,
|
||||
FlowHrefOptions,
|
||||
MapHrefOptions,
|
||||
NavigationDriver,
|
||||
SymbolHrefOptions,
|
||||
} from './lib/navigation';
|
||||
|
||||
/** The wire vocabulary an adapter answers in. Types only — no runtime. */
|
||||
export * from './lib/wire';
|
||||
|
||||
/* ----------------------------------------------------------- the screens -- */
|
||||
|
||||
/** Callers | verbatim source with gutter ports | line-anchored callee rail. */
|
||||
export { default as SymbolView } from './views/SymbolView.svelte';
|
||||
/** How one symbol reaches another, one card per hop, opened at the call line. */
|
||||
export { default as FlowStrip } from './views/FlowView.svelte';
|
||||
/** The repository at module granularity, layered so dependencies point down. */
|
||||
export { default as ArchitectureMap } from './views/MapView.svelte';
|
||||
/** One file: the outline in source order between two dependency rails. */
|
||||
export { default as FileView } from './views/FileView.svelte';
|
||||
/** One file's whole source, with gutter ports and intra-file call arcs. */
|
||||
export { default as FileSourceView } from './views/FileCodeView.svelte';
|
||||
/** Where a reader starts: routes, files that run something, tests, hubs. */
|
||||
export { default as EntryPointsView } from './views/EntryView.svelte';
|
||||
|
||||
/* -------------------------------------------------------- the furniture -- */
|
||||
|
||||
/** The path walked, with its arrows and its "read as flow". */
|
||||
export { default as TrailBar } from './components/TrailBar.svelte';
|
||||
/** The search box, its keyboard and its results panel — one component. */
|
||||
export { default as SearchPalette } from './components/SearchPalette.svelte';
|
||||
/** The results panel alone, for a host that owns the input. */
|
||||
export { default as PalettePanel } from './components/PalettePanel.svelte';
|
||||
/** The rows inside the panel, for a host that owns the whole shell. */
|
||||
export { default as PaletteRows } from './components/PaletteRows.svelte';
|
||||
/** "This file changed on disk since it was indexed." */
|
||||
export { default as DriftBanner } from './components/DriftBanner.svelte';
|
||||
/** The one-letter square that stands for a symbol's kind. */
|
||||
export { default as KindGlyph } from './components/KindGlyph.svelte';
|
||||
/** Copy image / download SVG for a Flow strip or a Map layout. */
|
||||
export { default as ExportButtons } from './components/ExportButtons.svelte';
|
||||
|
||||
/* ------------------------------------------------------------- the state -- */
|
||||
|
||||
export { trail, resolveTrailNames } from './lib/trail.svelte';
|
||||
export { encodeTrail, decodeTrail, hopLabel } from './lib/trail-codec';
|
||||
export type { HopDirection, TrailHop } from './lib/trail-codec';
|
||||
export { live, liveRefresh, touchesFile } from './lib/live.svelte';
|
||||
export type { LiveChanged, LiveHello, LiveIndexEvent, LiveIndexRevision } from './lib/live.svelte';
|
||||
export { project } from './lib/project.svelte';
|
||||
export { hot, railFocus } from './lib/focus.svelte';
|
||||
export type { RailSide } from './lib/focus.svelte';
|
||||
export { palette } from './lib/palette.svelte';
|
||||
export { toast } from './lib/toast.svelte';
|
||||
export { walkTo, arrivedFrom, openEntryTarget } from './lib/walk';
|
||||
export type { WalkTarget } from './lib/walk';
|
||||
|
||||
/* ------------------------------------------------------------ the models --
|
||||
Pure functions: no DOM, no fetch, no state. A host that wants a different
|
||||
screen over the same answers builds it out of these rather than out of the
|
||||
payloads, so its arithmetic is the arithmetic the shipped screens use. */
|
||||
|
||||
export { decodeLine, plainLine, tokenClass, tokensByLine } from './lib/highlight';
|
||||
export type { Token, TokenClass, WireHighlight, WireToken } from './lib/highlight';
|
||||
|
||||
export {
|
||||
assignRefs,
|
||||
basename,
|
||||
buildCalleeRail,
|
||||
buildCallerRail,
|
||||
buildCodeBlock,
|
||||
buildOutline,
|
||||
edgeWord,
|
||||
graphCallLines,
|
||||
kindPhrase,
|
||||
lastSegment,
|
||||
refsByLine,
|
||||
relationWords,
|
||||
showsBody,
|
||||
synthesizedBy,
|
||||
} from './lib/symbol-model';
|
||||
export type {
|
||||
CalleeRailModel,
|
||||
CalleeRow,
|
||||
CallerFileGroup,
|
||||
CallerRailModel,
|
||||
CallerRow,
|
||||
CodeBlock,
|
||||
Connector,
|
||||
LineRef,
|
||||
OutlineRow,
|
||||
SourceWindow,
|
||||
} from './lib/symbol-model';
|
||||
|
||||
export { buildFlowLayout, cardHeight, endCapHeight, endCapText } from './lib/flow-model';
|
||||
export type {
|
||||
EndCapSite,
|
||||
EndCapText,
|
||||
FlowCardLayout,
|
||||
FlowEndCapLayout,
|
||||
FlowLayout,
|
||||
FlowLinkLayout,
|
||||
} from './lib/flow-model';
|
||||
|
||||
export { buildMapLayout, isEdgeVisible, moduleMetaLabel } from './lib/map-model';
|
||||
export type {
|
||||
MapEdgeLayout,
|
||||
MapLayerLayout,
|
||||
MapLayout,
|
||||
MapLayoutOptions,
|
||||
MapNodeLayout,
|
||||
} from './lib/map-model';
|
||||
|
||||
export { buildFileOutline, buildFileRail, fileMetaLine, fileTitle } from './lib/file-model';
|
||||
export type { FileRailModel, FileRailRow, OutlineEntryRow } from './lib/file-model';
|
||||
|
||||
export {
|
||||
buildFileArcs,
|
||||
buildFileCallRows,
|
||||
buildFileRefs,
|
||||
documentHeight,
|
||||
lineCentre,
|
||||
lineTop,
|
||||
pageFor,
|
||||
visibleLines,
|
||||
} from './lib/filecode-model';
|
||||
export type { FileArc, FileCallRow, SourcePage } from './lib/filecode-model';
|
||||
|
||||
export { buildEntryPanel, flowPair, matchEntries } from './lib/entry-model';
|
||||
export type {
|
||||
EntryGroup,
|
||||
EntryPanel,
|
||||
EntryRow,
|
||||
EntrySection,
|
||||
EntryTarget,
|
||||
} from './lib/entry-model';
|
||||
|
||||
export {
|
||||
buildEntryPalette,
|
||||
buildSearchPalette,
|
||||
moveSelection,
|
||||
parseFlowQuery,
|
||||
} from './lib/search-model';
|
||||
export type { FlowQuery, Palette, PaletteItem, PaletteSection } from './lib/search-model';
|
||||
|
||||
export { exportFilename, flowSvg, mapSvg } from './lib/export-svg';
|
||||
export type { ExportOptions, FlowExportOptions, MapExportOptions } from './lib/export-svg';
|
||||
export { copyPngToClipboard, downloadSvg, svgToPng } from './lib/export-image';
|
||||
export { kindLetter, kindWord } from './lib/kinds';
|
||||
Reference in New Issue
Block a user