Creating a New View in Wave Terminal

This guide explains how to implement a new view type in Wave Terminal. Views are the core content components displayed within blocks in the terminal interface.

Architecture Overview

Wave Terminal uses a Model-View architecture where:

ViewModel - Contains all state, logic, and UI configuration as Jotai atoms
ViewComponent - Pure React component that renders the UI using the model
BlockFrame - Wraps views with a header, connection management, and standard controls

The separation between model and component ensures:

Models can update state without React hooks
Components remain pure and testable
State is centralized in Jotai atoms for easy access

ViewModel Interface

Every view must implement the ViewModel interface defined in frontend/types/custom.d.ts:

interface ViewModel {
    // Required: The type identifier for this view (e.g., "term", "web", "preview")
    viewType: string;

    // Required: The React component that renders this view
    viewComponent: ViewComponent<ViewModel>;

    // Optional: Icon shown in block header (FontAwesome icon name or IconButtonDecl)
    viewIcon?: jotai.Atom<string | IconButtonDecl>;

    // Optional: Display name shown in block header (e.g., "Terminal", "Web", "Preview")
    viewName?: jotai.Atom<string>;

    // Optional: Additional header elements (text, buttons, inputs) shown after the name
    viewText?: jotai.Atom<string | HeaderElem[]>;

    // Optional: Icon button shown before the view name in header
    preIconButton?: jotai.Atom<IconButtonDecl>;

    // Optional: Icon buttons shown at the end of the header (before settings/close)
    endIconButtons?: jotai.Atom<IconButtonDecl[]>;

    // Optional: Custom background styling for the block
    blockBg?: jotai.Atom<MetaType>;

    // Optional: If true, completely hides the block header
    noHeader?: jotai.Atom<boolean>;

    // Optional: If true, shows connection picker in header for remote connections
    manageConnection?: jotai.Atom<boolean>;

    // Optional: If true, filters out 'nowsh' connections from connection picker
    filterOutNowsh?: jotai.Atom<boolean>;

    // Optional: If true, shows S3 connections in connection picker
    showS3?: jotai.Atom<boolean>;

    // Optional: If true, removes default padding from content area
    noPadding?: jotai.Atom<boolean>;

    // Optional: Atoms for managing in-block search functionality
    searchAtoms?: SearchAtoms;

    // Optional: Returns whether this is a basic terminal (for multi-input feature)
    isBasicTerm?: (getFn: jotai.Getter) => boolean;

    // Optional: Returns context menu items for the settings dropdown
    getSettingsMenuItems?: () => ContextMenuItem[];

    // Optional: Focuses the view when called, returns true if successful
    giveFocus?: () => boolean;

    // Optional: Handles keyboard events, returns true if handled
    keyDownHandler?: (e: WaveKeyboardEvent) => boolean;

    // Optional: Cleanup when block is closed
    dispose?: () => void;
}

Key Concepts

Atoms: All UI-related properties must be Jotai atoms. This enables:

Reactive updates when state changes
Access from anywhere via globalStore.get()/globalStore.set()
Derived atoms that compute values from other atoms

ViewComponent: The React component receives these props:

type ViewComponentProps<T extends ViewModel> = {
    blockId: string;                              // Unique ID for this block
    blockRef: React.RefObject<HTMLDivElement>;    // Ref to block container
    contentRef: React.RefObject<HTMLDivElement>;  // Ref to content area
    model: T;                                      // Your ViewModel instance
};

Step-by-Step Guide

1. Create the View Model Class

Create a new file for your view model (e.g., frontend/app/view/myview/myview-model.ts):

import { BlockNodeModel } from "@/app/block/blocktypes";
import { WOS, globalStore, useBlockAtom } from "@/store/global";
import * as jotai from "jotai";
import { MyView } from "./myview";

export class MyViewModel implements ViewModel {
    viewType: string;
    blockId: string;
    nodeModel: BlockNodeModel;
    blockAtom: jotai.Atom<Block>;
    
    // Define your atoms (simple field initializers)
    viewIcon = jotai.atom<string>("circle");
    viewName = jotai.atom<string>("My View");
    noPadding = jotai.atom<boolean>(true);
    
    // Derived atom (created in constructor)
    viewText!: jotai.Atom<HeaderElem[]>;

    constructor(blockId: string, nodeModel: BlockNodeModel) {
        this.viewType = "myview";
        this.blockId = blockId;
        this.nodeModel = nodeModel;
        this.blockAtom = WOS.getWaveObjectAtom<Block>(`block:${blockId}`);
        
        // Create derived atoms that depend on block data or other atoms
        this.viewText = jotai.atom((get) => {
            const blockData = get(this.blockAtom);
            const rtn: HeaderElem[] = [];
            
            // Add header buttons/text based on state
            rtn.push({
                elemtype: "iconbutton",
                icon: "refresh",
                title: "Refresh",
                click: () => this.refresh(),
            });
            
            return rtn;
        });
    }

    get viewComponent(): ViewComponent {
        return MyView;
    }

    refresh() {
        // Update state using globalStore
        // Never use React hooks in model methods
        console.log("refreshing...");
    }

    giveFocus(): boolean {
        // Focus your view component
        return true;
    }

    dispose() {
        // Cleanup resources (unsubscribe from events, etc.)
    }
}

2. Create the View Component

Create your React component (e.g., frontend/app/view/myview/myview.tsx):

import { ViewComponentProps } from "@/app/block/blocktypes";
import { MyViewModel } from "./myview-model";
import { useAtomValue } from "jotai";
import "./myview.scss";

export const MyView: React.FC<ViewComponentProps<MyViewModel>> = ({ 
    blockId, 
    model, 
    contentRef 
}) => {
    // Use atoms from the model (these are React hooks - call at top level!)
    const blockData = useAtomValue(model.blockAtom);
    
    return (
        <div className="myview-container" ref={contentRef}>
            <div>Block ID: {blockId}</div>
            <div>View: {model.viewType}</div>
            {/* Your view content here */}
        </div>
    );
};

3. Register the View

Add your view to the BlockRegistry in frontend/app/block/block.tsx:

const BlockRegistry: Map<string, ViewModelClass> = new Map();
BlockRegistry.set("term", TermViewModel);
BlockRegistry.set("preview", PreviewModel);
BlockRegistry.set("web", WebViewModel);
// ... existing registrations ...
BlockRegistry.set("myview", MyViewModel);  // Add your view here

The registry key (e.g., "myview") becomes the view type used in block metadata.

4. Create Blocks with Your View

Users can create blocks with your view type:

Via CLI: wsh view myview
Via RPC: Use the block's meta.view field set to "myview"

Real-World Examples

Example 1: Terminal View (`term-model.ts`)

The terminal view demonstrates:

Connection management via manageConnection atom
Dynamic header buttons showing shell status (play/restart)
Mode switching between terminal and vdom views
Custom keyboard handling for terminal-specific shortcuts
Focus management to focus the xterm.js instance
Shell integration status showing AI capability indicators

Key features:

this.manageConnection = jotai.atom((get) => {
    const termMode = get(this.termMode);
    if (termMode == "vdom") return false;
    return true;  // Show connection picker for regular terminal mode
});

this.endIconButtons = jotai.atom((get) => {
    const shellProcStatus = get(this.shellProcStatus);
    const buttons: IconButtonDecl[] = [];
    
    if (shellProcStatus == "running") {
        buttons.push({
            elemtype: "iconbutton",
            icon: "refresh",
            title: "Restart Shell",
            click: this.forceRestartController.bind(this),
        });
    }
    return buttons;
});

Example 2: Web View (`webview.tsx`)

The web view shows:

Complex header controls (back/forward/home/URL input)
State management for loading, URL, and navigation
Event handling for webview navigation events
Custom styling with noPadding for full-bleed content
Media controls showing play/pause/mute when media is active

Key features:

this.viewText = jotai.atom((get) => {
    const url = get(this.url);
    const rtn: HeaderElem[] = [];
    
    // Navigation buttons
    rtn.push({
        elemtype: "iconbutton",
        icon: "chevron-left",
        click: this.handleBack.bind(this),
        disabled: this.shouldDisableBackButton(),
    });
    
    // URL input with nested controls
    rtn.push({
        elemtype: "div",
        className: "block-frame-div-url",
        children: [
            {
                elemtype: "input",
                value: url,
                onChange: this.handleUrlChange.bind(this),
                onKeyDown: this.handleKeyDown.bind(this),
            },
            {
                elemtype: "iconbutton",
                icon: "rotate-right",
                click: this.handleRefresh.bind(this),
            }
        ],
    });
    
    return rtn;
});

Header Elements (`HeaderElem`)

The viewText atom can return an array of these element types:

// Icon button
{
    elemtype: "iconbutton",
    icon: "refresh",
    title: "Tooltip text",
    click: () => { /* handler */ },
    disabled?: boolean,
    iconColor?: string,
    iconSpin?: boolean,
    noAction?: boolean,  // Shows icon but no click action
}

// Text element
{
    elemtype: "text",
    text: "Display text",
    className?: string,
    noGrow?: boolean,
    ref?: React.RefObject<HTMLElement>,
    onClick?: (e: React.MouseEvent) => void,
}

// Text button
{
    elemtype: "textbutton",
    text: "Button text",
    className?: string,
    title: "Tooltip",
    onClick: (e: React.MouseEvent) => void,
}

// Input field
{
    elemtype: "input",
    value: string,
    className?: string,
    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void,
    onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void,
    onFocus?: (e: React.FocusEvent<HTMLInputElement>) => void,
    onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void,
    ref?: React.RefObject<HTMLInputElement>,
}

// Container with children
{
    elemtype: "div",
    className?: string,
    children: HeaderElem[],
    onMouseOver?: (e: React.MouseEvent) => void,
    onMouseOut?: (e: React.MouseEvent) => void,
}

// Menu button (dropdown)
{
    elemtype: "menubutton",
    // ... MenuButtonProps ...
}

Best Practices

Jotai Model Pattern

Follow these rules for Jotai atoms in models:

Simple atoms as field initializers:

viewIcon = jotai.atom<string>("circle");
noPadding = jotai.atom<boolean>(true);

Derived atoms in constructor (need dependency on other atoms):

constructor(blockId: string, nodeModel: BlockNodeModel) {
    this.viewText = jotai.atom((get) => {
        const blockData = get(this.blockAtom);
        return [/* computed based on blockData */];
    });
}

Models never use React hooks - Use globalStore.get()/set():

refresh() {
    const currentData = globalStore.get(this.blockAtom);
    globalStore.set(this.dataAtom, newData);
}

Components use hooks for atoms:

const data = useAtomValue(model.dataAtom);
const [value, setValue] = useAtom(model.valueAtom);

State Management

All view state should live in atoms on the model
Use useBlockAtom() helper for block-scoped atoms that persist
Use globalStore for imperative access outside React components
Subscribe to Wave events using waveEventSubscribe()

Styling

Create a .scss file for your view styles
Use Tailwind utilities where possible (v4)
Add noPadding: atom(true) for full-bleed content
Use blockBg atom to customize block background

Focus Management

Implement giveFocus() to focus your view when:

Block gains focus via keyboard navigation
User clicks the block
Return true if successfully focused, false otherwise

Keyboard Handling

Implement keyDownHandler(e: WaveKeyboardEvent) for:

View-specific keyboard shortcuts
Return true if event was handled (prevents propagation)
Use keyutil.checkKeyPressed(waveEvent, "Cmd:K") for shortcut checks

Cleanup

Implement dispose() to:

Unsubscribe from Wave events
Unregister routes/handlers
Clear timers/intervals
Release resources

Connection Management

For views that need remote connections:

this.manageConnection = jotai.atom(true);  // Show connection picker
this.filterOutNowsh = jotai.atom(true);    // Hide nowsh connections
this.showS3 = jotai.atom(true);            // Show S3 connections

Access connection status:

const connStatus = jotai.atom((get) => {
    const blockData = get(this.blockAtom);
    const connName = blockData?.meta?.connection;
    return get(getConnStatusAtom(connName));
});

Common Patterns

Reading Block Metadata

import { getBlockMetaKeyAtom } from "@/store/global";

// In constructor:
this.someFlag = getBlockMetaKeyAtom(blockId, "myview:flag");

// In component:
const flag = useAtomValue(model.someFlag);

Configuration Overrides

Wave has a hierarchical config system (global → connection → block):

import { getOverrideConfigAtom } from "@/store/global";

this.settingAtom = jotai.atom((get) => {
    // Checks block meta, then connection config, then global settings
    return get(getOverrideConfigAtom(this.blockId, "myview:setting")) ?? defaultValue;
});

Updating Block Metadata

import { RpcApi } from "@/app/store/wshclientapi";
import { TabRpcClient } from "@/app/store/wshrpcutil";
import { WOS } from "@/store/global";

await RpcApi.SetMetaCommand(TabRpcClient, {
    oref: WOS.makeORef("block", this.blockId),
    meta: { "myview:key": value },
});

Search Integration

To add in-block search:

import { useSearch } from "@/app/element/search";

// In model:
this.searchAtoms = useSearch();  // Call in component, not model!

// In component:
const searchAtoms = useSearch();
// Pass to model or use directly

Testing Your View

Build the frontend: task build:dev or task electron:dev
Create a block with your view type
Test all interactive elements (buttons, inputs, etc.)
Test keyboard shortcuts
Test focus behavior
Test cleanup (close block and check console for errors)
Test with different block configurations via metadata

Additional Resources

frontend/app/block/blockframe.tsx - Block header rendering
frontend/app/view/term/term-model.ts - Complex view example
frontend/app/view/webview/webview.tsx - Navigation UI example
frontend/types/custom.d.ts - Type definitions
Project coding rules in .roo/rules/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Creating a New View in Wave Terminal

Architecture Overview

ViewModel Interface

Key Concepts

Step-by-Step Guide

1. Create the View Model Class

2. Create the View Component

3. Register the View

4. Create Blocks with Your View

Real-World Examples

Example 1: Terminal View (`term-model.ts`)

Example 2: Web View (`webview.tsx`)

Header Elements (`HeaderElem`)

Best Practices

Jotai Model Pattern

State Management

Styling

Focus Management

Keyboard Handling

Cleanup

Connection Management

Common Patterns

Reading Block Metadata

Configuration Overrides

Updating Block Metadata

Search Integration

Testing Your View

Additional Resources

Uh oh!

FilesExpand file tree

newview.md

Latest commit

History

newview.md

File metadata and controls

Creating a New View in Wave Terminal

Architecture Overview

ViewModel Interface

Key Concepts

Step-by-Step Guide

1. Create the View Model Class

2. Create the View Component

3. Register the View

4. Create Blocks with Your View

Real-World Examples

Example 1: Terminal View (term-model.ts)

Example 2: Web View (webview.tsx)

Header Elements (HeaderElem)

Best Practices

Jotai Model Pattern

State Management

Styling

Focus Management

Keyboard Handling

Cleanup

Connection Management

Common Patterns

Reading Block Metadata

Configuration Overrides

Updating Block Metadata

Search Integration

Testing Your View

Additional Resources

Example 1: Terminal View (`term-model.ts`)

Example 2: Web View (`webview.tsx`)

Header Elements (`HeaderElem`)