Storm Terminal UI Framework

Storm uses a multi-stage pipeline to transform React element trees into minimal ANSI terminal updates. The process follows these steps:

1. React commit: The reconciler (reconciler/host.ts) mutates the element tree.
2. FrameScheduler: Throttles updates to a maximum FPS, coalesces rapid commits, and detects render loops.
3. RenderPipeline.fullPaint(): Orchestrates the rendering process:
   • Runs beforeRender plugins.
   • Runs runLayout middleware.
   • Executes paint(): Runs computeLayout() and writes cells into a ScreenBuffer.
   • Runs runPaint middleware (post-processing).
   • Calls Screen.flush() to hand the buffer to the DiffRenderer.
   • DiffRenderer.render(): Diffs the previous and next buffers to emit minimal ANSI sequences.
4. Incremental repaint: Triggered by requestRender(). This bypasses the React commit phase and is used for high-performance updates like animations or scrolling.

A Locale object defines the linguistic and formatting rules for a language. It includes the ISO 639-1 code, text direction (ltr or rtl), number formatting rules, month and weekday names, and a dictionary of translatable strings. You can also optionally provide a pluralRule.

import { EN, PLURAL_FR, type Locale } from "@orchetron/storm";

const FR: Locale = {
  code: "fr",
  direction: "ltr",
  pluralRule: PLURAL_FR,
  numbers: { decimal: ",", thousands: " ", grouping: 3 },
  months: [
    "janvier", "fevrier", "mars", "avril", "mai", "juin",
    "juillet", "aout", "septembre", "octobre", "novembre", "decembre",
  ],
  monthsShort: [
    "janv.", "fevr.", "mars", "avr.", "mai", "juin",
    "juil.", "aout", "sept.", "oct.", "nov.", "dec.",
  ],
  weekdays: [
    "dimanche", "lundi", "mardi", "mercredi",
    "jeudi", "vendredi", "samedi",
  ],
  weekdaysShort: ["dim.", "lun.", "mar.", "mer.", "jeu.", "ven.", "sam."],
  strings: {
    "greeting": "Bonjour, {name} !",
    "items.one": "{count} element",
    "items.other": "{count} elements",
  },
};

When building with Storm widgets, keep these architectural patterns in mind:

• Imperative Animation Pattern: Animated widgets (like BlinkDot, ShimmerText, StreamingText, and OperationTree) use ref mutation and requestRender() instead of React state. This is necessary because Storm's custom React reconciler does not flush state updates like React DOM.
• Plugin System: Every widget wraps its props through usePluginProps("WidgetName", rawProps), allowing plugins to intercept and modify widget properties globally.
• Personality System: Animated widgets derive timing defaults (e.g., durationFast, durationSlow) from the usePersonality() hook.
• Automatic Cleanup: All timer-based widgets use useCleanup() to prevent memory leaks or interval errors when components unmount.
• Performance: All widgets are wrapped in React.memo() to minimize re-renders within the Storm reconciler.

Storm TUI provides two primary animation paradigms depending on your use case:

1. Imperative (useAnimation): Best for continuous, frame-based animations like spinners or progress bars. It provides direct control over frame updates and avoids React reconciliation overhead by using a global AnimationScheduler.
2. Declarative (useTransition, <Transition>, <AnimatePresence>): Best for UI state changes, such as showing/hiding elements, enter/exit patterns, and animating numeric values. These are simpler to use for common UI transitions.

Decision Guide:

• Use useAnimation for frame-based patterns (e.g., cycling through text frames).
• Use useTransition for numeric interpolation (e.g., animating opacity or position) with fine control (delay, spring easing).
• Use <Transition> for simple show/hide patterns.
• Use <AnimatePresence> for dynamic lists where items need to play an exit animation before unmounting.

There are two ways to manage component properties via plugins:

1. componentDefaults (Declarative): A record of default props for specific components. These are applied BEFORE user-provided props. If multiple plugins define defaults, they are merged in registration order.
2. onComponentProps (Imperative): A callback that runs for every component render. It receives the component name and current props (after defaults are applied). Return the modified props object to apply changes, or undefined to pass through.

Processing Order:

1. Merge componentDefaults from all plugins.
2. Apply user-provided props (user props always win).
3. Run onComponentProps from each plugin in registration order.

// Example of componentDefaults
const compactPlugin: StormPlugin = {
  name: "compact-layout",
  componentDefaults: {
    Box: { paddingX: 0, paddingY: 0 },
    Text: { wrap: "truncate" },
    Select: { maxVisible: 5 },
  },
};

// Example of onComponentProps
const highContrastPlugin: StormPlugin = {
  name: "high-contrast",
  onComponentProps(componentName, props) {
    if (componentName === "Text") {
      return { ...props, bold: true };
    }
    return undefined;
  },
};