@opentui/react 0.1.25 → 0.1.27

package/README.md

@@ -188,6 +188,58 @@ function App() {
 
 **Returns:** An object with `width` and `height` properties representing the current terminal dimensions.
 
+#### `useTimeline(options?)`
+
+Create and manage animations using OpenTUI's timeline system. This hook automatically registers and unregisters the timeline with the animation engine.
+
+```tsx
+import { render, useTimeline } from "@opentui/react"
+import { useEffect, useState } from "react"
+
+function App() {
+  const [width, setWidth] = useState(0)
+
+  const timeline = useTimeline({
+    duration: 2000,
+    loop: false,
+  })
+
+  useEffect(() => {
+    timeline.add(
+      {
+        width,
+      },
+      {
+        width: 50,
+        duration: 2000,
+        ease: "linear",
+        onUpdate: (animation) => {
+          setWidth(animation.targets[0].width)
+        },
+      },
+    )
+  }, [])
+
+  return <box style={{ width, backgroundColor: "#6a5acd" }} />
+}
+```
+
+**Parameters:**
+
+- `options?`: Optional `TimelineOptions` object with properties:
+  - `duration?`: Animation duration in milliseconds (default: 1000)
+  - `loop?`: Whether the timeline should loop (default: false)
+  - `autoplay?`: Whether to automatically start the timeline (default: true)
+  - `onComplete?`: Callback when timeline completes
+  - `onPause?`: Callback when timeline is paused
+
+**Returns:** A `Timeline` instance with methods:
+
+- `add(target, properties, startTime)`: Add animation to timeline
+- `play()`: Start the timeline
+- `pause()`: Pause the timeline
+- `restart()`: Restart the timeline from beginning
+
 ## Components
 
 ### Text Component
@@ -504,6 +556,89 @@ function App() {
 render(<App />)
 ```
 
+### System Monitor Animation
+
+```tsx
+import { TextAttributes } from "@opentui/core"
+import { render, useTimeline } from "@opentui/react"
+import { useEffect, useState } from "react"
+
+type Stats = {
+  cpu: number
+  memory: number
+  network: number
+  disk: number
+}
+
+export const App = () => {
+  const [stats, setAnimatedStats] = useState<Stats>({
+    cpu: 0,
+    memory: 0,
+    network: 0,
+    disk: 0,
+  })
+
+  const timeline = useTimeline({
+    duration: 3000,
+    loop: false,
+  })
+
+  useEffect(() => {
+    timeline.add(
+      stats,
+      {
+        cpu: 85,
+        memory: 70,
+        network: 95,
+        disk: 60,
+        duration: 3000,
+        ease: "linear",
+        onUpdate: (values) => {
+          setAnimatedStats({ ...values.targets[0] })
+        },
+      },
+      0,
+    )
+  }, [])
+
+  const statsMap = [
+    { name: "CPU", key: "cpu", color: "#6a5acd" },
+    { name: "Memory", key: "memory", color: "#4682b4" },
+    { name: "Network", key: "network", color: "#20b2aa" },
+    { name: "Disk", key: "disk", color: "#daa520" },
+  ]
+
+  return (
+    <box
+      title="System Monitor"
+      style={{
+        margin: 1,
+        padding: 1,
+        border: true,
+        marginLeft: 2,
+        marginRight: 2,
+        borderStyle: "single",
+        borderColor: "#4a4a4a",
+      }}
+    >
+      {statsMap.map((stat) => (
+        <box key={stat.key}>
+          <box flexDirection="row" justifyContent="space-between">
+            <text>{stat.name}</text>
+            <text attributes={TextAttributes.DIM}>{Math.round(stats[stat.key as keyof Stats])}%</text>
+          </box>
+          <box style={{ backgroundColor: "#333333" }}>
+            <box style={{ width: `${stats[stat.key as keyof Stats]}%`, height: 1, backgroundColor: stat.color }} />
+          </box>
+        </box>
+      ))}
+    </box>
+  )
+}
+
+render(<App />)
+```
+
 ### Styled Text Showcase
 
 ```tsx

package/index.js

@@ -97,12 +97,12 @@ var AppContext = createContext({
 var useAppContext = () => {
   return useContext(AppContext);
 };
-// src/hooks/use-keyboard.tsx
+// src/hooks/use-keyboard.ts
 import { useEffect } from "react";
 
-// src/hooks/use-event.tsx
+// src/hooks/use-event.ts
 import { useCallback, useLayoutEffect, useRef } from "react";
-function useEvent(handler) {
+function useEffectEvent(handler) {
   const handlerRef = useRef(handler);
   useLayoutEffect(() => {
     handlerRef.current = handler;
@@ -113,18 +113,18 @@ function useEvent(handler) {
   }, []);
 }
 
-// src/hooks/use-keyboard.tsx
+// src/hooks/use-keyboard.ts
 var useKeyboard = (handler) => {
   const { keyHandler } = useAppContext();
-  const stableHandler = useEvent(handler);
+  const stableHandler = useEffectEvent(handler);
   useEffect(() => {
     keyHandler?.on("keypress", stableHandler);
     return () => {
       keyHandler?.off("keypress", stableHandler);
     };
-  }, [keyHandler, stableHandler]);
+  }, [keyHandler]);
 };
-// src/hooks/use-renderer.tsx
+// src/hooks/use-renderer.ts
 var useRenderer = () => {
   const { renderer } = useAppContext();
   if (!renderer) {
@@ -132,19 +132,20 @@ var useRenderer = () => {
   }
   return renderer;
 };
-// src/hooks/use-resize.tsx
+// src/hooks/use-resize.ts
 import { useEffect as useEffect2 } from "react";
 var useOnResize = (callback) => {
   const renderer = useRenderer();
+  const stableCallback = useEffectEvent(callback);
   useEffect2(() => {
-    renderer.on("resize", callback);
+    renderer.on("resize", stableCallback);
     return () => {
-      renderer.off("resize", callback);
+      renderer.off("resize", stableCallback);
     };
-  }, [renderer, callback]);
+  }, [renderer]);
   return renderer;
 };
-// src/hooks/use-terminal-dimensions.tsx
+// src/hooks/use-terminal-dimensions.ts
 import { useState } from "react";
 var useTerminalDimensions = () => {
   const renderer = useRenderer();
@@ -158,9 +159,26 @@ var useTerminalDimensions = () => {
   useOnResize(cb);
   return dimensions;
 };
+// src/hooks/use-timeline.ts
+import { engine, Timeline } from "@opentui/core";
+import { useEffect as useEffect3 } from "react";
+var useTimeline = (options = {}) => {
+  const timeline = new Timeline(options);
+  useEffect3(() => {
+    if (!options.autoplay) {
+      timeline.play();
+    }
+    engine.register(timeline);
+    return () => {
+      timeline.pause();
+      engine.unregister(timeline);
+    };
+  }, []);
+  return timeline;
+};
 // src/reconciler/renderer.ts
-import { createCliRenderer } from "@opentui/core";
-import React from "react";
+import { createCliRenderer, engine as engine2 } from "@opentui/core";
+import React2 from "react";
 
 // src/reconciler/reconciler.ts
 import ReactReconciler from "react-reconciler";
@@ -455,12 +473,43 @@ function _render(element, root) {
   reconciler.updateContainer(element, container, null, () => {});
 }
 
+// src/components/error-boundary.tsx
+import React from "react";
+
+// jsx-dev-runtime.js
+import { Fragment, jsxDEV } from "react/jsx-dev-runtime";
+
+// src/components/error-boundary.tsx
+class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+  render() {
+    if (this.state.hasError && this.state.error) {
+      return /* @__PURE__ */ jsxDEV("box", {
+        style: { flexDirection: "column", padding: 2 },
+        children: /* @__PURE__ */ jsxDEV("text", {
+          fg: "red",
+          children: this.state.error.stack || this.state.error.message
+        }, undefined, false, undefined, this)
+      }, undefined, false, undefined, this);
+    }
+    return this.props.children;
+  }
+}
+
 // src/reconciler/renderer.ts
 async function render(node, rendererConfig = {}) {
   const renderer = await createCliRenderer(rendererConfig);
-  _render(React.createElement(AppContext.Provider, { value: { keyHandler: renderer.keyInput, renderer } }, node), renderer.root);
+  engine2.attach(renderer);
+  _render(React2.createElement(AppContext.Provider, { value: { keyHandler: renderer.keyInput, renderer } }, React2.createElement(ErrorBoundary, null, node)), renderer.root);
 }
 export {
+  useTimeline,
   useTerminalDimensions,
   useRenderer,
   useOnResize,

package/package.json

@@ -4,7 +4,7 @@
   "main": "index.js",
   "types": "src/index.d.ts",
   "type": "module",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "React renderer for building terminal user interfaces using OpenTUI core",
   "license": "MIT",
   "repository": {
@@ -35,11 +35,13 @@
     }
   },
   "dependencies": {
-    "@opentui/core": "0.1.25",
+    "@opentui/core": "0.1.27",
     "react-reconciler": "^0.32.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/node": "latest",
+    "@types/react": "^19.0.0",
     "@types/react-reconciler": "^0.32.0",
     "typescript": "^5"
   },

package/src/components/error-boundary.d.ts

@@ -0,0 +1,16 @@
+import React from "react";
+export declare class ErrorBoundary extends React.Component<{
+    children: React.ReactNode;
+}, {
+    hasError: boolean;
+    error: Error | null;
+}> {
+    constructor(props: {
+        children: React.ReactNode;
+    });
+    static getDerivedStateFromError(error: Error): {
+        hasError: boolean;
+        error: Error;
+    };
+    render(): any;
+}

package/src/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./use-keyboard";
+export * from "./use-renderer";
+export * from "./use-resize";
+export * from "./use-terminal-dimensions";
+export * from "./use-timeline";

package/src/hooks/use-event.d.ts

@@ -6,4 +6,4 @@
  * Useful for event handlers that need to be passed to effects with empty dependency arrays
  * or memoized child components.
  */
-export declare function useEvent<T extends (...args: any[]) => any>(handler: T): T;
+export declare function useEffectEvent<T extends (...args: any[]) => any>(handler: T): T;

package/src/hooks/use-keyboard.d.ts

@@ -1,2 +1,2 @@
-import type { ParsedKey } from "@opentui/core";
-export declare const useKeyboard: (handler: (key: ParsedKey) => void) => void;
+import type { KeyEvent } from "@opentui/core";
+export declare const useKeyboard: (handler: (key: KeyEvent) => void) => void;

package/src/hooks/use-timeline.d.ts

@@ -0,0 +1,2 @@
+import { Timeline, type TimelineOptions } from "@opentui/core";
+export declare const useTimeline: (options?: TimelineOptions) => Timeline;

package/src/index.d.ts

@@ -1,8 +1,5 @@
 export * from "./components";
 export * from "./components/app";
-export * from "./hooks/use-keyboard";
-export * from "./hooks/use-renderer";
-export * from "./hooks/use-resize";
-export * from "./hooks/use-terminal-dimensions";
+export * from "./hooks";
 export * from "./reconciler/renderer";
 export * from "./types/components";

package/src/reconciler/renderer.js

@@ -1,7 +1,7 @@
 // @bun
 // src/reconciler/renderer.ts
-import { createCliRenderer } from "@opentui/core";
-import React from "react";
+import { createCliRenderer, engine } from "@opentui/core";
+import React2 from "react";
 
 // src/components/app.tsx
 import { createContext, useContext } from "react";
@@ -390,10 +390,40 @@ function _render(element, root) {
   reconciler.updateContainer(element, container, null, () => {});
 }
 
+// src/components/error-boundary.tsx
+import React from "react";
+
+// jsx-dev-runtime.js
+import { Fragment, jsxDEV } from "react/jsx-dev-runtime";
+
+// src/components/error-boundary.tsx
+class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+  render() {
+    if (this.state.hasError && this.state.error) {
+      return /* @__PURE__ */ jsxDEV("box", {
+        style: { flexDirection: "column", padding: 2 },
+        children: /* @__PURE__ */ jsxDEV("text", {
+          fg: "red",
+          children: this.state.error.stack || this.state.error.message
+        }, undefined, false, undefined, this)
+      }, undefined, false, undefined, this);
+    }
+    return this.props.children;
+  }
+}
+
 // src/reconciler/renderer.ts
 async function render(node, rendererConfig = {}) {
   const renderer = await createCliRenderer(rendererConfig);
-  _render(React.createElement(AppContext.Provider, { value: { keyHandler: renderer.keyInput, renderer } }, node), renderer.root);
+  engine.attach(renderer);
+  _render(React2.createElement(AppContext.Provider, { value: { keyHandler: renderer.keyInput, renderer } }, React2.createElement(ErrorBoundary, null, node)), renderer.root);
 }
 export {
   render