scitex-ui 0.3.1

Shared frontend UI components for the SciTeX ecosystem

SciTeX UI (scitex-ui)

Shared frontend UI components for the SciTeX ecosystem

Full Documentation · pip install scitex-ui

---

Problem

The SciTeX ecosystem comprises multiple web applications (cloud dashboard, documentation hub, workspace editor) that share common frontend patterns — navigation sidebars, package browsers, status indicators. Without a shared component library, each application re-implements these patterns independently, leading to visual inconsistency and duplicated effort.

Solution

SciTeX UI provides a library of reusable TypeScript + CSS components designed for SciTeX web applications. Components are packaged as a Django app with static assets discoverable via AppDirectoriesFinder, and a Python registry for component metadata.

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

Architecture

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

Category	Component	Prefix	Description
Shell	ThemeProvider	stx-shell-	Light/dark theme manager with semantic color tokens
Shell	AppShell	stx-shell-	Workspace layout with collapsible sidebar and accent colors
Shell	StatusBar	stx-shell-	Bottom status bar with left/center/right sections
App	FileBrowser	stx-app-	Tree view for navigating file hierarchies
App	PackageDocsSidebar	stx-app-	Navigable sidebar for Python package documentation

_{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

Python API

Function	Description
list_components()	List all registered component names
get_component(name)	Get metadata for a registered component
register_component(name, metadata)	Register a new component

CLI Commands (planned)

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

MCP Server (planned)

MCP (Model Context Protocol) tools for AI agents to discover and query available UI components.

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. When used within the SciTeX ecosystem, components automatically integrate with the SciTeX cloud dashboard and documentation hub.

The SciTeX ecosystem follows the Four Freedoms for researchers, inspired by the Free Software Definition:

• Freedom 0 — Run the software for any research purpose.
• Freedom 1 — Study how the software works and adapt it to your needs.
• Freedom 2 — Redistribute copies to help fellow researchers.
• Freedom 3 — Distribute modified versions so the community benefits.

---