@opentui/react 0.0.0-20250926-77b41db5 → 0.0.0-20250929-69eb6c87

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,10 +97,10 @@ 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) {
   const handlerRef = useRef(handler);
@@ -113,7 +113,7 @@ function useEvent(handler) {
   }, []);
 }
 
-// src/hooks/use-keyboard.tsx
+// src/hooks/use-keyboard.ts
 var useKeyboard = (handler) => {
   const { keyHandler } = useAppContext();
   const stableHandler = useEvent(handler);
@@ -124,7 +124,7 @@ var useKeyboard = (handler) => {
     };
   }, [keyHandler, stableHandler]);
 };
-// src/hooks/use-renderer.tsx
+// src/hooks/use-renderer.ts
 var useRenderer = () => {
   const { renderer } = useAppContext();
   if (!renderer) {
@@ -132,7 +132,7 @@ 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();
@@ -144,7 +144,7 @@ var useOnResize = (callback) => {
   }, [renderer, callback]);
   return renderer;
 };
-// src/hooks/use-terminal-dimensions.tsx
+// src/hooks/use-terminal-dimensions.ts
 import { useState } from "react";
 var useTerminalDimensions = () => {
   const renderer = useRenderer();
@@ -158,8 +158,25 @@ 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 { createCliRenderer, engine as engine2 } from "@opentui/core";
 import React from "react";
 
 // src/reconciler/reconciler.ts
@@ -458,9 +475,11 @@ function _render(element, root) {
 // src/reconciler/renderer.ts
 async function render(node, rendererConfig = {}) {
   const renderer = await createCliRenderer(rendererConfig);
+  engine2.attach(renderer);
   _render(React.createElement(AppContext.Provider, { value: { keyHandler: renderer.keyInput, renderer } }, 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.0.0-20250926-77b41db5",
+  "version": "0.0.0-20250929-69eb6c87",
   "description": "React renderer for building terminal user interfaces using OpenTUI core",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     }
   },
   "dependencies": {
-    "@opentui/core": "0.0.0-20250926-77b41db5",
+    "@opentui/core": "0.0.0-20250929-69eb6c87",
     "react-reconciler": "^0.32.0"
   },
   "devDependencies": {

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-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,6 +1,6 @@
 // @bun
 // src/reconciler/renderer.ts
-import { createCliRenderer } from "@opentui/core";
+import { createCliRenderer, engine } from "@opentui/core";
 import React from "react";
 
 // src/components/app.tsx
@@ -393,6 +393,7 @@ function _render(element, root) {
 // src/reconciler/renderer.ts
 async function render(node, rendererConfig = {}) {
   const renderer = await createCliRenderer(rendererConfig);
+  engine.attach(renderer);
   _render(React.createElement(AppContext.Provider, { value: { keyHandler: renderer.keyInput, renderer } }, node), renderer.root);
 }
 export {