streamator-react 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,94 @@
+# streamator-react
+
+Frontend primitives for displaying live log streams in React. Handles SSE connection,
+entry formatting, auto-scroll, and rendering.
+
+Pairs with [`streamator`](https://pypi.org/project/streamator/) on the backend.
+
+## Install
+
+```bash
+npm install streamator-react
+```
+
+## Usage
+
+```jsx
+import { useLogStream, LogPanel } from "streamator-react"
+import "streamator-react/log.css"
+
+const { logs, active } = useLogStream(`/api/log/${jobId}/stream`)
+
+<LogPanel logs={logs} active={active} />
+```
+
+## `useLogStream(url, options)`
+
+```js
+const { logs, active } = useLogStream(url, {
+  mode: "sse",          // "sse" (default) | "poll"
+  interval: 3000,       // poll interval ms — poll mode only
+  formatEvent: fn,      // (rawEvent) => string | null
+})
+```
+
+- `logs` — `Array<{ text, t, level }>` — ready to render
+- `active` — `true` while stream is open / polling
+- Passing `null` or `undefined` as `url` is a no-op
+
+## `LogPanel` props
+
+```jsx
+<LogPanel
+  logs={logs}
+  active={active}
+  waitingText="⏳ Starting…"           // shown while active but no logs yet
+  maxHeight="200px"                    // default: 160px
+  className="my-log"                   // appended to root class
+  style={{}}
+  renderEntry={(entry, i) => <div />}  // fully custom row renderer
+  autoScroll={true}                    // set false to disable auto-scroll
+/>
+```
+
+Returns `null` when not active and no logs. Auto-scrolls to latest entry.
+
+## `makeFormatEvent(overrides)`
+
+Map structured backend events to display strings:
+
+```js
+import { makeFormatEvent } from "streamator-react"
+
+const formatEvent = makeFormatEvent({
+  scraping: e => `🔍 Scraping ${e.url}`,
+  done:     () => `✅ Finished`,
+})
+
+const { logs } = useLogStream(url, { formatEvent })
+```
+
+Return `null` from a handler to suppress that entry entirely.
+
+## Styling
+
+Default styles via CSS custom properties — override any of them:
+
+```css
+--streamator-bg:            #f8f8f8;
+--streamator-border:        #e0e0e0;
+--streamator-color:         #444;
+--streamator-time-color:    #aaa;
+--streamator-radius:        6px;
+--streamator-font-size:     0.8rem;
+--streamator-max-height:    160px;
+--streamator-success-color: #2e7d32;
+--streamator-warning-color: #f59e0b;
+--streamator-error-color:   #c62828;
+```
+
+Migrating from old `.log` / `.log-time` / `.log-waiting` class names?
+
+```js
+import "streamator-react/log-compat.css"
+```

package/dist/index.cjs.js

@@ -85,20 +85,20 @@ function LogPanel({
   maxHeight,
   className,
   style,
-  renderEntry
+  renderEntry,
+  autoScroll = true
 }) {
-  const bottomRef = react.useRef(null);
+  const panelRef = react.useRef(null);
   react.useEffect(() => {
-    bottomRef.current?.scrollIntoView({
-      behavior: "smooth"
-    });
-  }, [logs]);
+    if (autoScroll && panelRef.current) panelRef.current.scrollTop = panelRef.current.scrollHeight;
+  }, [logs, autoScroll]);
   if (!active && logs.length === 0) return null;
   const rootStyle = maxHeight ? {
     ...style,
     "--streamator-max-height": maxHeight
   } : style;
   return /*#__PURE__*/jsxRuntime.jsxs("div", {
+    ref: panelRef,
     className: ["streamator-log", className].filter(Boolean).join(" "),
     style: rootStyle,
     children: [active && logs.length === 0 && /*#__PURE__*/jsxRuntime.jsx("div", {
@@ -112,9 +112,7 @@ function LogPanel({
       }), /*#__PURE__*/jsxRuntime.jsx("span", {
         children: entry.text
       })]
-    }, i)), /*#__PURE__*/jsxRuntime.jsx("div", {
-      ref: bottomRef
-    })]
+    }, i))]
   });
 }
 

package/dist/index.esm.js

@@ -83,20 +83,20 @@ function LogPanel({
   maxHeight,
   className,
   style,
-  renderEntry
+  renderEntry,
+  autoScroll = true
 }) {
-  const bottomRef = useRef(null);
+  const panelRef = useRef(null);
   useEffect(() => {
-    bottomRef.current?.scrollIntoView({
-      behavior: "smooth"
-    });
-  }, [logs]);
+    if (autoScroll && panelRef.current) panelRef.current.scrollTop = panelRef.current.scrollHeight;
+  }, [logs, autoScroll]);
   if (!active && logs.length === 0) return null;
   const rootStyle = maxHeight ? {
     ...style,
     "--streamator-max-height": maxHeight
   } : style;
   return /*#__PURE__*/jsxs("div", {
+    ref: panelRef,
     className: ["streamator-log", className].filter(Boolean).join(" "),
     style: rootStyle,
     children: [active && logs.length === 0 && /*#__PURE__*/jsx("div", {
@@ -110,9 +110,7 @@ function LogPanel({
       }), /*#__PURE__*/jsx("span", {
         children: entry.text
       })]
-    }, i)), /*#__PURE__*/jsx("div", {
-      ref: bottomRef
-    })]
+    }, i))]
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "streamator-react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Frontend primitives for displaying live log streams",
   "author": "Arved Klöhn <arved.kloehn@gmail.com>",
   "license": "MIT",