Teksilo Documentation

Teksilo is a pure-Rust GUI framework for serious desktop applications: a retained widget tree with SwiftUI-style layout, AccessKit accessibility, and a wgpu renderer.

This site has two layers:

• Widget Catalog — a per-widget discovery page for every shipped widget (its abilities, an example, and a deep link to the full rustdoc API). Start here if you are exploring what Teksilo can draw.
• Reference & design docs — the focused subsystem documents below (layout, styling, events, accessibility, data, …). Start here if you are building.

The catalog pages are generated from the widget source by python3 tools/extract_widget_api.py --md-dir docs/widgets; the same tool prints any widget's API to the terminal (python3 tools/extract_widget_api.py Button).

Architecture & roadmap

• architecture.md — framework-internals reference: scrolling, arena, Canvas API, rendering pipeline, HiDPI, threading, testability, crate dependency graph, design comparisons, open questions. Per-subsystem APIs live in the focused docs below.
• teksilo-milestones.md — the demo-driven milestone roadmap; each milestone produces a runnable example exercising one slice of the architecture.

Widget catalog

• widgets-overview.md — every shipped widget categorized (layout / visual / containers / buttons / inputs / text family / menus / overlays / data-driven / charts / animations / settings) with a one-line description and source-file link. Pair with python3 tools/extract_widget_api.py <Widget…> for the full API surface of any widget.

Authoring widgets

• layout-primitives.md — HStack / VStack / ZStack, Grid, Wrap, MasonryLayout, FormLayout, Switcher, and the size wrappers (Expand, FixedSize, MinSize, MaxSize, AspectRatio, Center, Padding, Spacer, Divider).
• events-and-gestures.md — preview/bubble dispatch, attached handlers (.on_tap, .on_hover, …), on_key_preview, focus_within / hover_within, FocusScope Tab-traversal scopes, gesture recognizers.
• styling-system.md — the four-tier styling ladder (tokens → variants → recipes → style protocols); Theme aggregator, ThemeAppearance, per-widget *Variant enums and *Style traits, per-call vs theme-wide style installation, writing a custom preset.
• reactive-theme.md — Signal<Theme>, role-driven colors (ColorProp, TextStyleProp), reactive switching without rebuild.
• animation.md — Signal<f32>::animate_to, MotionTokens, AnimationSpec builder, the animated wrapper widgets (Fade, Pulse, Crossfade, Scale, Blur, …).
• idle-and-animation.md — the zero-frame rule; how next_timer_deadline() keeps the event loop asleep when nothing is moving.
• accessibility-overrides.md — builder-level .access_* modifiers (label, description, subtree merge/exclude, custom actions, shortcut binding) for the cases widget-emitted a11y misses.
• text-scale.md — the global "grow all text" accessibility setting: the TextScaleControl widget, persistence + startup restore, the effective_theme blanket mechanism, ctx.text_scale / text_scale_signal, the per-engine font_scale for editable text, and the follow_text_scale opt-in/opt-out surfaces (icons, RichTextEditor, scene text).

teksu! DSL & formatting

• teksu-macro-reference.md — user-facing reference for the teksu! block-DSL (parse → IR → builder calls).
• teksu-language-spec-v3.md — design spec with full grammar, structural forms, and worked translations of catalog examples.
• teksilo-fmt.md — cargo teksilo-fmt, the formatter for teksu! blocks (rustfmt skips macro bodies).
• teksilo-fmt-vscode.md — wiring teksilo-fmt-lsp into VS Code for in-editor formatting.

Input, navigation, chrome

• shortcut-intent-action.md — Shortcut / Intent / Action pipeline, #[derive(IntentKind)], rebindable keystrokes via ShortcutRegistry.
• tooltips.md — plain TooltipWidget, registry-driven RichTooltipWidget, sticky-on-dwell promotion, focus-driven a11y promotion, attach helpers.
• toast.md — Toast floating notifications (info / success / warning / error / loading severities, link + button actions, Toast::id update-in-place) + ToastHost queue + persistent NotificationArchiveModel + NotificationLog / bell NotificationCenterButton / NotificationLogDialog UI; TeksiloAppBuilder::install_toast_default() one-line install.
• native-menu.md — declarative MenuModel shared by the in-window MenuBar and the macOS native menu bar (NSMenu); MenuBar::from_model(..).native_on_macos(..), TeksiloAppBuilder::install_native_menu(), reactive checks, ⌘ key equivalents, focus-follows-window.
• web-view.md — embeddable WebView widget (native OS subview on top of wgpu), pluggable WebViewBackend (wry default / Servo additive for Wayland / headless), the dormancy→set_visible activation bridge, JS↔Rust IPC, install_web_view_default().
• drag-and-drop.md — drag payloads, drop targets, hit testing, the three user stories that share the underlying machinery.
• multi-window.md — WindowConfig, signal-driven multi-window orchestration, modal dialogs, restore-from-state.
• title-bar.md — custom widget-level title bar plus the per-OS PlatformTitleBarHost for drag / zoom / close / inset.
• toolbar.md — Toolbar command bar with automatic overflow: actions (priority / always_overflow / toggle), pinned + collapsible custom widgets (overflow_as menu row, overflow_widget live embedded control, the ToolbarOverflow trait), the MenuList-backed chevron menu, display modes / orientation, and the ARIA roving-tabindex pattern.

Data, persistence, telemetry

• data-models.md — ListModel, TreeModel, SelectionModel, CheckedModel / TreeCheckedModel (per-row checkbox state with optional descendant→ancestor tristate aggregation), sort/filter projections; the model layer that sits above the widget tree.
• data-source.md — the ListDataSource / TreeDataSource read-and-command interface every data view talks to: the capability protocol (identity, DnD validation via can_accept/accept_drop, lazy/windowed loading), keyed selection, and how an external source of truth drives a view without a mirror model.
• settings.md — reactive end-to-end persistence: SettingsStore, SettingsFile<T>, MruList<T>, window-state auto save/restore.
• telemetry.md — consent-gated event reporting, the teksilo-collector / Plausible / OTLP adapters, the events.yaml schema pipeline.

Async & concurrency

• async.md — the optional main-thread async executor (teksilo-async): install_async(), ctx.spawn_local(...) / spawn_local_with, spawn_blocking, the async-agnostic on_loop_tick hook, and the teksilo-tokio / teksilo-async-std reactor adapters for awaiting native runtime futures. Off by default; complements the reactive subscribe_event data path.

Specialized widgets

• splitter.md — N-pane Splitter with draggable, collapsible dividers, per-pane stretch, animated collapse (four triggers), a shared serializable SplitterModel, and a Tier-3 SplitterStyle. The building block for DockingLayout.
• docking.md — VS Code-style DockingLayout: a centre slot + four collapsible/splittable/draggable side regions, per-corner ownership, an activity rail, drag-to-dock five-zone overlay, and a cloneable serializable DockingModel with export_state/import_state.
• table-view.md — virtualized TableView and TreeTableView (multi-column, sort/filter, drag-resize, drag-reorder, full keyboard navigation).
• tab-widget.md — TabBar<T> and TabWidget (static + dynamic tabs, Signal<Option<TabId>> selection, pinned tabs, drag reorder, overflow dropdown, horizontal + vertical orientations).
• charts.md — BarChart / LineChart / PieChart (shared axis / palette / legend / tooltip infrastructure).
• teksilo-scene.md — the pannable, zoomable scene viewport (canvases, board layouts, diagram editors), including magnetism (typed snap-and-connect between item anchors).
• teksilo-scene-a11y.md — shaping the accessibility tree of a teksilo-scene viewport, including synthetic magnet nodes and the roving active_descendant keyboard connect flow.

Visuals & resources

• icons-and-resources.md — res!()-embedded SVG / PNG / WebP icons with theme-aware tinting.

Tooling

• inspector.md — teksilo-inspector, the in-app debug surface (Tree / Properties / Accessibility / Theme / Models tabs; picker + bounds overlay; debug-only).