treetime
Auf dieser Seite

Apps

How the TypeScript apps sit on the Rust core, and the interface components they share.

Diese Seite ist noch nicht übersetzt
Sie wird auf Englisch angezeigt. Einstellungstexte, Hilfetexte und die Befehlszeilenreferenz bleiben auf allen Seiten englisch.

The TypeScript apps (app-ui, app-web, app-web2, app-desktop, and the docs site app-docs) are a user interface around the Rust core. Algorithms, file parsers, readers and writers, configuration handling, and domain rules live in Rust and are tested there. The apps render what the Rust operations return and keep only presentation logic: layout, interaction state, and formatting for display. One implementation of each rule keeps the CLI, the web app, and the desktop app from diverging, and one test suite covers it.

  • CLI knowledge: flags, value syntax, setting groups, defaults, the equivalent command line, and the YAML config come from clap and the config types. The setting catalog (packages/app-contracts/setting-catalog.json, generated by just gen catalog and imported from @neherlab/app-contracts/catalog) describes every command and setting: titles, main settings, and the settings that act as one choice. check-config reports which option of each choice a configuration selects, and run-config and check-config render the command line and YAML
  • Checks: check-config classifies configuration problems and input facts into checks that block the run, warn, or advise, with the settings that fix them
  • Types: every value that crosses from Rust to TypeScript is a Rust type with a derived schema in the OpenAPI document; the apps read it through the generated types and zod schemas in app-contracts, never through hand-written ones

Interface components

The interface is built from shadcn/ui components in the base-vega style, which run on Base UI. The components are vendored into the design package, packages/design/src/ui/ (@neherlab/design/ui/<name>), one file per component, and the app composes them; it does not style raw elements. The project owns the vendored files: they pass the same lint rules as the rest of the source and keep only the parts the apps use. packages/design/src/ui/UPSTREAM.md records their source, the rewrites that turn a registry file into a component, and the local changes to re-apply when a component is refreshed.

The theme comes from the design package @neherlab/design (packages/design), which the design language page shows. Its token source, packages/design/src/tokens/tokens.ts, defines every color as a pair of OKLCH values for the light and the dark theme, and just gen design writes from it the CSS custom properties (packages/design/src/css/tokens.css), the Tailwind theme (packages/design/src/css/tailwind-theme.css), the matplotlib style, and the chart palette of treetime-charts. Surfaces, lines, and text are greys without hue; one blue marks actions, links, focus, and selection; IBM Plex Sans sets the interface and IBM Plex Mono the code. packages/app-ui/src/theme.css, the stylesheet of the app, imports @neherlab/design/tailwind.css and adds the rules of the Auspice view. packages/design/src/ui/shadcn.css is the stylesheet of the shadcn npm package that defines the variants the components use.

Icons come from Iconify sets. unplugin-icons compiles each imported icon into an inline SVG React component at build time, so the bundle holds only the icons in use and the apps load nothing from an icon host at runtime. An icon is a default import from the virtual ~icons/<set>/<name> module:

import XIcon from "~icons/lucide/x";
<XIcon aria-hidden className="size-4" />;

Lucide is the base set and matches the stroke style of the shadcn components. When Lucide has no fitting icon, add the Iconify set that has one: install its @iconify-json/<set> package as a pinned devDependency of packages/app-ui and import from ~icons/<set>/<name>; the plugin configuration in packages/app-ui/build/icons-vite.ts needs no change. Icons render at 24 by 24 pixels unless a class or a parent sets their size. A decorative icon takes aria-hidden, and an icon that carries meaning on its own takes an aria-label. lucide-react is banned by the lint rules because its components duplicate the compiled icons.

Library hooks cover the behavior around the components: @tanstack/react-hotkeys for keyboard shortcuts and their platform labels, react-dropzone for file drops and the file dialog, use-stick-to-bottom for the following log, @tanstack/react-table for sortable tables, @tanstack/react-pacer for debouncing, Base UI Autocomplete for the command palette, and @mantine/hooks for the clipboard, the size of the Auspice panel, and the mobile media query.