SciTeX UI (scitex-ui)

Full Documentation · uv pip install scitex-ui[all]

Problem and Solution

Architecture

Each component ships with:

• TypeScript source — framework-agnostic, vanilla DOM API
• CSS styles — scoped via BEM-like class prefixes (stx-shell-*, stx-app-*)
• Python metadata — version, file paths, descriptions

graph TB
    subgraph shell ["Shell (stx-shell-*) — Workspace Frame"]
        theme["ThemeProvider<br/>Light/Dark + Tokens"]
        appshell["AppShell<br/>Sidebar + Content"]
        statusbar["StatusBar<br/>L | C | R Sections"]
    end

    subgraph app ["App (stx-app-*) — In-App Components"]
        filebrowser["FileBrowser<br/>Tree Navigation"]
        pkgsidebar["PackageDocsSidebar<br/>Package Browser"]
    end

    base{{"BaseComponent<br/>Container + Events + Lifecycle"}}

    appshell -->|extends| base
    statusbar -->|extends| base
    filebrowser -->|extends| base
    pkgsidebar -->|extends| base

_{Figure 1. Component architecture. Shell components provide workspace framing (theme, layout, status bar). App components are reusable in-app widgets. All extend BaseComponent for shared container resolution, event dispatch, and lifecycle management.}

Current Components

_{Table 1. Available UI components. Shell components provide workspace framing; App components are for in-app use. Each is registered in the Python metadata registry.}

Installation

Requires Python >= 3.10.

pip install scitex-ui

Quick Start

Django Setup

Add scitex_ui to your INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "scitex_ui",
]

Static assets are automatically discoverable by Django's AppDirectoriesFinder.

Python API

import scitex_ui

# List all registered components
for name in scitex_ui.list_components():
    meta = scitex_ui.get_component(name)
    print(f"{name} v{meta.version} — {meta.description}")

# Get specific component metadata
sidebar = scitex_ui.get_component("package-docs-sidebar")
print(sidebar.ts_entry)   # TypeScript entry point
print(sidebar.css_file)   # CSS stylesheet path

TypeScript Usage

// Workspace shell
import { ThemeProvider } from "scitex_ui/ts/shell/theme-provider";
import { AppShell } from "scitex_ui/ts/shell/app-shell";
import { StatusBar } from "scitex_ui/ts/shell/status-bar";

const theme = new ThemeProvider();
const shell = new AppShell({
  container: "#app",
  accent: "writer",        // Preset accent color
  collapsible: true,
});
const statusBar = new StatusBar({ container: "#status" });

// In-app components
import { FileBrowser } from "scitex_ui/ts/app/file-browser";

const browser = new FileBrowser({
  container: "#files",
  onFileSelect: (node) => console.log(node.path),
});

Three Interfaces

scitex-ui --help              # Show help
scitex-ui list-components     # List registered components
scitex-ui version             # Show version

Demo

The package ships runnable example pages under examples/ showing each component category in isolation:

flowchart LR
    subgraph Page ["Browser Page (#app)"]
        Theme[ThemeProvider<br/>tokens injected]
        Shell[AppShell<br/>sidebar + content]
        Bar[StatusBar<br/>L | C | R]
        FB[FileBrowser<br/>tree view]
    end
    Static[Django static<br/>scitex_ui/static/] --> Page
    Reg[(Python registry<br/>get_component)] --> Static
    style Theme fill:#4a90d9,stroke:#2c3e50,color:#fff
    style Shell fill:#4a90d9,stroke:#2c3e50,color:#fff
    style Bar  fill:#4a90d9,stroke:#2c3e50,color:#fff
    style FB   fill:#27ae60,stroke:#2c3e50,color:#fff

_{Figure 2. Demo. Components are discovered via the Python registry, then mounted in TypeScript against DOM containers. CSS is shipped as Django static assets.}

# List every registered component
python examples/01_list_components.py

# Run the workspace-shell example (Django dev server)
python examples/02_workspace_components.py
# → open http://localhost:8000/ to see ThemeProvider + AppShell + StatusBar

Role in SciTeX Ecosystem

scitex-ui is the shared TypeScript + CSS component library for all SciTeX web applications. It provides the visual building blocks that maintain consistency across the cloud dashboard, workspace editor, and third-party apps.

scitex (orchestrator, templates, CLI, MCP)
  |-- scitex-app              -- runtime SDK for apps
  |-- scitex-ui (this package) -- TS + CSS component library
  |     |-- Shell (stx-shell-*) -- ThemeProvider, AppShell, StatusBar
  |     |-- App (stx-app-*)     -- FileBrowser, PackageDocsSidebar
  |     +-- Design tokens        -- spacing, typography, z-index, colors
  +-- figrecipe                -- reference app (consumes scitex-ui)

What this package owns:

• Shell components (stx-shell-*): ThemeProvider, AppShell, StatusBar
• App components (stx-app-*): FileBrowser, PackageDocsSidebar
• Design token CSS: theme colors, spacing, typography, z-index primitives

What this package does NOT own:

• Backend/runtime SDK -- see scitex-app
• Orchestration, templates, CLI -- see scitex
• App-specific logic -- each app (e.g., figrecipe) owns its own views

Part of SciTeX

scitex-ui is part of SciTeX. Install via the umbrella with pip install scitex[ui] to use as scitex.ui (Python) or scitex ui ... (CLI).

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.