@aganzefelicite/responsekit-react 0.1.0 → 0.2.0

package/README.md

@@ -15,21 +15,16 @@ components — safely, and without ever crashing on unknown or invalid data.
 
 ## Install
 
-Not published to npm yet — install from a local build of this repo (`@responsekit/schema`
-is bundled in, so it's a single tarball):
-
 ```bash
-# in the repo root
-pnpm pack:local
-# in your app
-pnpm add /ABS/PATH/responsekit-react-0.0.0.tgz react react-dom
+pnpm add @aganzefelicite/responsekit-react react react-dom
 ```
 
 ```ts
 import "@aganzefelicite/responsekit-react/styles.css"; // optional default styling
 ```
 
-See [docs/INTEGRATION.md](../../docs/INTEGRATION.md) for `pnpm link` and publishing options.
+The response-contract package (types + zod validators + SSE reducer) is bundled in and
+re-exported, so there's nothing else to install. `react`/`react-dom` are peer deps (>=18).
 
 ## Quick start
 
@@ -52,8 +47,9 @@ backend). The message endpoint is POST + `text/event-stream`; the SDK drives
 
 ## API
 
-**Components** — `AiRenderer`, `AiStream`
+**Components** — `AiRenderer`, `AiStream`, `AiWidget` (draggable/resizable pop-up)
 **Hooks** — `useAiStream`, `useChat`
+**Actions** — `withDefaultActions`, `runDefaultAction`, `performDownload`, `performOpenLink`, `triggerDownload`
 **Registry** — `registerBlock`, `unregisterBlock`, `resolveBlockComponent`
 **Default blocks** — `TextBlock`, `KpiBlock`, `ChartBlock`, `TableBlock`, `InsightBlock`,
 `RecommendationBlock`, `FilterBlock`, `FallbackBlock`, `defaultBlockComponents`
@@ -77,10 +73,32 @@ registerBlock({ type: "MAP", component: RwandaMap });
 Resolution order per block type: `components` prop → globally registered → built-in default
 → graceful fallback.
 
+## Floating widget
+
+Wrap any content in a draggable, resizable pop-up with a launcher button:
+
+```tsx
+import { AiWidget } from "@aganzefelicite/responsekit-react";
+
+<AiWidget title="Assistant" defaultOpen>
+  {/* useChat + AiRenderer, a single AiRenderer, or your own chat UI */}
+</AiWidget>;
+```
+
+Drag by the header, resize from the bottom-right corner, toggle via the launcher (or
+control `open`/`onOpenChange`). Chrome only — it never touches your data flow.
+
 ## Actions
 
 Blocks emit intent through one `onAction(action)` callback (`DOWNLOAD`, `OPEN_LINK`,
-`REFRESH`, `CUSTOM`, or host-defined). The SDK never runs business logic.
+`REFRESH`, `CUSTOM`, or host-defined). The SDK never runs business logic — but for the two
+actions with an obvious browser behavior it ships a default. Wrap your handler with
+`withDefaultActions` and CSV/JSON/Blob downloads and link-opens work out of the box:
+
+```tsx
+import { withDefaultActions } from "@aganzefelicite/responsekit-react";
+<AiRenderer response={r} onAction={withDefaultActions((a) => track(a))} />;
+```
 
 ## License
 

package/dist/index.cjs

@@ -4981,9 +4981,259 @@ function useChat(options) {
   react.useEffect(() => () => abortRef.current?.abort(), []);
   return { conversationId, turns, isStreaming, error, send, stop, reset, newConversation };
 }
+var MARGIN = 24;
+var clamp = (v, lo, hi) => Math.min(Math.max(v, lo), hi);
+var viewport = () => ({
+  w: typeof window === "undefined" ? 1024 : window.innerWidth,
+  h: typeof window === "undefined" ? 768 : window.innerHeight
+});
+function AiWidget({
+  children,
+  title = "Assistant",
+  headerActions,
+  defaultOpen = false,
+  open: openProp,
+  onOpenChange,
+  initialPosition,
+  initialSize = { width: 384, height: 560 },
+  minWidth = 300,
+  minHeight = 360,
+  showLauncher = true,
+  launcher,
+  className
+}) {
+  const isControlled = openProp !== void 0;
+  const [openState, setOpenState] = react.useState(defaultOpen);
+  const open = isControlled ? openProp : openState;
+  const setOpen = react.useCallback(
+    (next) => {
+      if (!isControlled) setOpenState(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange]
+  );
+  const [size, setSize] = react.useState(initialSize);
+  const [pos, setPos] = react.useState(initialPosition ?? null);
+  react.useEffect(() => {
+    if (pos) return;
+    const { w, h } = viewport();
+    setPos({
+      x: Math.max(MARGIN, w - size.width - MARGIN),
+      y: Math.max(MARGIN, h - size.height - MARGIN)
+    });
+  }, [pos]);
+  react.useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onResize = () => {
+      setPos((p) => {
+        if (!p) return p;
+        const { w, h } = viewport();
+        return {
+          x: clamp(p.x, 0, Math.max(0, w - size.width)),
+          y: clamp(p.y, 0, Math.max(0, h - size.height))
+        };
+      });
+    };
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [size.width, size.height]);
+  const dragRef = react.useRef(null);
+  const onHeaderPointerDown = (e) => {
+    if (e.button !== 0 || !pos) return;
+    if (e.target.closest("button, a, input, select")) return;
+    dragRef.current = { px: e.clientX, py: e.clientY, ox: pos.x, oy: pos.y };
+    e.currentTarget.setPointerCapture(e.pointerId);
+  };
+  const onHeaderPointerMove = (e) => {
+    const d = dragRef.current;
+    if (!d) return;
+    const { w, h } = viewport();
+    setPos({
+      x: clamp(d.ox + (e.clientX - d.px), 0, Math.max(0, w - size.width)),
+      y: clamp(d.oy + (e.clientY - d.py), 0, Math.max(0, h - size.height))
+    });
+  };
+  const endHeaderPointer = (e) => {
+    dragRef.current = null;
+    if (e.currentTarget.hasPointerCapture?.(e.pointerId)) {
+      e.currentTarget.releasePointerCapture(e.pointerId);
+    }
+  };
+  const resizeRef = react.useRef(null);
+  const onResizePointerDown = (e) => {
+    if (e.button !== 0) return;
+    e.stopPropagation();
+    resizeRef.current = { px: e.clientX, py: e.clientY, ow: size.width, oh: size.height };
+    e.currentTarget.setPointerCapture(e.pointerId);
+  };
+  const onResizePointerMove = (e) => {
+    const r = resizeRef.current;
+    if (!r || !pos) return;
+    const { w, h } = viewport();
+    setSize({
+      width: clamp(r.ow + (e.clientX - r.px), minWidth, w - pos.x - MARGIN / 2),
+      height: clamp(r.oh + (e.clientY - r.py), minHeight, h - pos.y - MARGIN / 2)
+    });
+  };
+  const endResizePointer = (e) => {
+    resizeRef.current = null;
+    if (e.currentTarget.hasPointerCapture?.(e.pointerId)) {
+      e.currentTarget.releasePointerCapture(e.pointerId);
+    }
+  };
+  if (!open) {
+    if (!showLauncher) return null;
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        type: "button",
+        className: "rk-widget-launcher",
+        onClick: () => setOpen(true),
+        "aria-label": `Open ${title}`,
+        children: launcher ?? /* @__PURE__ */ jsxRuntime.jsx(LauncherIcon, {})
+      }
+    );
+  }
+  const panelStyle = pos ? {
+    left: pos.x,
+    top: pos.y,
+    width: size.width,
+    height: size.height
+  } : { visibility: "hidden" };
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      className: `rk-widget${className ? ` ${className}` : ""}`,
+      style: panelStyle,
+      role: "dialog",
+      "aria-label": title,
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsxs(
+          "div",
+          {
+            className: "rk-widget-header",
+            onPointerDown: onHeaderPointerDown,
+            onPointerMove: onHeaderPointerMove,
+            onPointerUp: endHeaderPointer,
+            onPointerCancel: endHeaderPointer,
+            children: [
+              /* @__PURE__ */ jsxRuntime.jsx("span", { className: "rk-widget-title", children: title }),
+              /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "rk-widget-header-actions", children: [
+                headerActions,
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    className: "rk-widget-close",
+                    onClick: () => setOpen(false),
+                    "aria-label": `Close ${title}`,
+                    children: "\xD7"
+                  }
+                )
+              ] })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "rk-widget-body", children }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            className: "rk-widget-resize",
+            onPointerDown: onResizePointerDown,
+            onPointerMove: onResizePointerMove,
+            onPointerUp: endResizePointer,
+            onPointerCancel: endResizePointer,
+            role: "separator",
+            "aria-label": "Resize",
+            "aria-orientation": "horizontal"
+          }
+        )
+      ]
+    }
+  );
+}
+function LauncherIcon() {
+  return /* @__PURE__ */ jsxRuntime.jsx("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", "aria-hidden": "true", children: /* @__PURE__ */ jsxRuntime.jsx(
+    "path",
+    {
+      d: "M21 11.5a8.38 8.38 0 0 1-8.5 8.5 9.3 9.3 0 0 1-4-.9L3 21l1.9-5.5a8.38 8.38 0 0 1-.9-4A8.5 8.5 0 0 1 12.5 3 8.38 8.38 0 0 1 21 11.5Z",
+      stroke: "currentColor",
+      strokeWidth: "1.8",
+      strokeLinecap: "round",
+      strokeLinejoin: "round"
+    }
+  ) });
+}
+
+// src/download.ts
+var MIME = {
+  CSV: "text/csv",
+  JSON: "application/json",
+  TXT: "text/plain"
+};
+function inBrowser() {
+  return typeof document !== "undefined" && typeof URL !== "undefined";
+}
+function triggerDownload(blob, filename) {
+  if (!inBrowser()) return;
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.rel = "noopener";
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+function performDownload(action) {
+  if (!inBrowser()) return false;
+  const { data, format, filename } = action;
+  if (data === null || data === void 0) return false;
+  const fmt = typeof format === "string" ? format.toUpperCase() : void 0;
+  let blob;
+  let name = filename;
+  if (data instanceof Blob) {
+    blob = data;
+    name ?? (name = "download");
+  } else if (typeof data === "string") {
+    const mime = fmt && MIME[fmt] || "text/plain";
+    blob = new Blob([data], { type: `${mime};charset=utf-8` });
+    name ?? (name = `download.${(fmt ?? "TXT").toLowerCase()}`);
+  } else {
+    blob = new Blob([JSON.stringify(data, null, 2)], {
+      type: "application/json;charset=utf-8"
+    });
+    name ?? (name = "download.json");
+  }
+  triggerDownload(blob, name);
+  return true;
+}
+function performOpenLink(action) {
+  if (typeof window === "undefined" || !action.href) return false;
+  window.open(action.href, action.target ?? "_blank", "noopener,noreferrer");
+  return true;
+}
+function runDefaultAction(action) {
+  switch (action.type) {
+    case "DOWNLOAD":
+      return performDownload(action);
+    case "OPEN_LINK":
+      return performOpenLink(action);
+    default:
+      return false;
+  }
+}
+function withDefaultActions(onAction) {
+  return (action) => {
+    runDefaultAction(action);
+    onAction?.(action);
+  };
+}
 
 exports.AiRenderer = AiRenderer;
 exports.AiStream = AiStream;
+exports.AiWidget = AiWidget;
 exports.ChartBlock = ChartBlock;
 exports.ErrorBoundary = ErrorBoundary;
 exports.ErrorView = ErrorView;
@@ -5024,6 +5274,8 @@ exports.noopAction = noopAction;
 exports.parseAiResponse = parseAiResponse;
 exports.parseBlock = parseBlock;
 exports.parseSseEvent = parseSseEvent;
+exports.performDownload = performDownload;
+exports.performOpenLink = performOpenLink;
 exports.progressEventSchema = progressEventSchema;
 exports.progressPhaseSchema = progressPhaseSchema;
 exports.recommendationBlockSchema = recommendationBlockSchema;
@@ -5036,6 +5288,7 @@ exports.responseEndSchema = responseEndSchema;
 exports.responseMetadataSchema = responseMetadataSchema;
 exports.responseStartSchema = responseStartSchema;
 exports.responseTypeSchema = responseTypeSchema;
+exports.runDefaultAction = runDefaultAction;
 exports.safeParseAiResponse = safeParseAiResponse;
 exports.severitySchema = severitySchema;
 exports.streamMessage = streamMessage;
@@ -5046,8 +5299,10 @@ exports.textBlockSchema = textBlockSchema;
 exports.textFormatSchema = textFormatSchema;
 exports.textResponseSchema = textResponseSchema;
 exports.trendSchema = trendSchema;
+exports.triggerDownload = triggerDownload;
 exports.unregisterBlock = unregisterBlock;
 exports.useAiStream = useAiStream;
 exports.useChat = useChat;
+exports.withDefaultActions = withDefaultActions;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map