@stackwright-pro/pulse 0.1.0

package/dist/index.mjs

@@ -0,0 +1,329 @@
+// src/components/Pulse.tsx
+import { useState as useState2, useEffect as useEffect2 } from "react";
+
+// src/hooks/usePulse.ts
+import { useState, useCallback, useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+function usePulse(options) {
+  const {
+    fetcher,
+    interval = 5e3,
+    schema,
+    enabled = true,
+    refetchOnWindowFocus = true,
+    retryCount = 3
+  } = options;
+  const [lastSuccess, setLastSuccess] = useState(null);
+  const [errorCount, setErrorCount] = useState(0);
+  const validatedFetcher = useCallback(async () => {
+    const data2 = await fetcher();
+    if (schema) {
+      return schema.parse(data2);
+    }
+    return data2;
+  }, [fetcher, schema]);
+  const queryKey = ["pulse", fetcher.toString()];
+  const { data, isLoading, isFetching, isSuccess, isError, error, refetch } = useQuery({
+    queryKey,
+    queryFn: validatedFetcher,
+    refetchInterval: enabled ? Math.max(interval, 1e3) : false,
+    refetchOnWindowFocus,
+    retry: retryCount,
+    retryDelay: (attemptIndex) => Math.min(1e3 * 2 ** attemptIndex, 1e4),
+    staleTime: interval / 2,
+    throwOnError: false
+  });
+  useEffect(() => {
+    if (isSuccess && data !== void 0) {
+      setLastSuccess(/* @__PURE__ */ new Date());
+      setErrorCount(0);
+    }
+  }, [isSuccess, data]);
+  useEffect(() => {
+    if (isError) {
+      setErrorCount((c) => c + 1);
+    }
+  }, [isError]);
+  let state = "loading";
+  if (isLoading && data === void 0) {
+    state = "loading";
+  } else if (error && data === void 0) {
+    state = "error";
+  } else if (isFetching) {
+    state = "stale";
+  } else {
+    state = "live";
+  }
+  const meta = {
+    lastUpdated: lastSuccess ?? /* @__PURE__ */ new Date(0),
+    isStale: state === "stale" || state === "error",
+    isError: state === "error",
+    isLoading: isFetching && data === void 0,
+    errorCount,
+    refetch,
+    state
+  };
+  return {
+    data,
+    meta,
+    state,
+    error
+  };
+}
+
+// src/components/Pulse.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function Pulse({
+  fetcher,
+  interval,
+  staleThreshold,
+  maxStaleAge,
+  schema,
+  enabled,
+  refetchOnWindowFocus,
+  retryCount,
+  children,
+  loadingState,
+  errorState,
+  emptyState,
+  showStaleDataOnError = true
+}) {
+  const { data, meta, state } = usePulse({
+    fetcher,
+    interval,
+    staleThreshold,
+    maxStaleAge,
+    schema,
+    enabled,
+    refetchOnWindowFocus,
+    retryCount
+  });
+  if (state === "loading" && data === void 0) {
+    return /* @__PURE__ */ jsx(Fragment, { children: loadingState ?? /* @__PURE__ */ jsx(DefaultLoading, {}) });
+  }
+  if (state === "error") {
+    const errorUi = typeof errorState === "function" ? errorState(meta) : errorState ?? /* @__PURE__ */ jsx(DefaultError, { meta });
+    if (showStaleDataOnError && data !== void 0) {
+      return /* @__PURE__ */ jsxs(Fragment, { children: [
+        errorUi,
+        children(data, meta)
+      ] });
+    }
+    return /* @__PURE__ */ jsx(Fragment, { children: errorUi });
+  }
+  if (data === null || data === void 0 || Array.isArray(data) && data.length === 0) {
+    return /* @__PURE__ */ jsx(Fragment, { children: emptyState ?? /* @__PURE__ */ jsx(DefaultEmpty, {}) });
+  }
+  return /* @__PURE__ */ jsx(Fragment, { children: children(data, meta) });
+}
+function useSecondsAgo(lastUpdated) {
+  const [secondsAgo, setSecondsAgo] = useState2(
+    () => Math.round((Date.now() - lastUpdated.getTime()) / 1e3)
+  );
+  useEffect2(() => {
+    const interval = setInterval(() => {
+      setSecondsAgo(Math.round((Date.now() - lastUpdated.getTime()) / 1e3));
+    }, 1e3);
+    return () => clearInterval(interval);
+  }, [lastUpdated]);
+  return secondsAgo;
+}
+function DefaultLoading() {
+  return /* @__PURE__ */ jsxs("div", { className: "pulse--loading", role: "status", "aria-live": "polite", "aria-atomic": "true", children: [
+    /* @__PURE__ */ jsx("span", { className: "pulse--spinner", "aria-hidden": "true" }),
+    /* @__PURE__ */ jsx("span", { className: "pulse--loading-text", children: "Loading..." })
+  ] });
+}
+function DefaultError({ meta }) {
+  const secondsAgo = useSecondsAgo(meta.lastUpdated);
+  return /* @__PURE__ */ jsxs("div", { className: "pulse--error", role: "alert", "aria-live": "assertive", "aria-atomic": "true", children: [
+    "\u26A0\uFE0F Connection lost. Last updated: ",
+    secondsAgo,
+    "s ago"
+  ] });
+}
+function DefaultEmpty() {
+  return /* @__PURE__ */ jsx("div", { className: "pulse--empty", children: "No data available" });
+}
+
+// src/components/PulseIndicator.tsx
+import { useState as useState3, useEffect as useEffect3 } from "react";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function PulseIndicator({
+  meta,
+  showSeconds = true,
+  className,
+  labels = {}
+}) {
+  const [secondsAgo, setSecondsAgo] = useState3(
+    () => Math.round((Date.now() - meta.lastUpdated.getTime()) / 1e3)
+  );
+  useEffect3(() => {
+    const interval = setInterval(() => {
+      setSecondsAgo(Math.round((Date.now() - meta.lastUpdated.getTime()) / 1e3));
+    }, 1e3);
+    return () => clearInterval(interval);
+  }, [meta.lastUpdated]);
+  let status;
+  let label;
+  let dotClass;
+  if (meta.isLoading) {
+    status = "syncing";
+    label = labels.syncing ?? "Syncing...";
+    dotClass = "dot--syncing";
+  } else if (meta.isError) {
+    status = "error";
+    label = labels.error ?? `Offline${showSeconds ? ` \u2022 ${formatSeconds(secondsAgo)}` : ""}`;
+    dotClass = "dot--error";
+  } else if (meta.isStale) {
+    status = "stale";
+    label = labels.stale ?? `Stale${showSeconds ? ` \u2022 ${formatSeconds(secondsAgo)}` : ""}`;
+    dotClass = "dot--stale";
+  } else {
+    status = "live";
+    label = showSeconds ? labels.live ?? `Live \u2022 ${formatSeconds(secondsAgo)}` : labels.live ?? "Live";
+    dotClass = "dot--live";
+  }
+  return /* @__PURE__ */ jsxs2(
+    "div",
+    {
+      className: `pulse-indicator ${status} ${className ?? ""}`,
+      "data-status": status,
+      role: "status",
+      "aria-live": "polite",
+      "aria-atomic": "true",
+      children: [
+        /* @__PURE__ */ jsx2("span", { className: `pulse-indicator__dot ${dotClass}`, "aria-hidden": "true" }),
+        /* @__PURE__ */ jsx2("span", { className: "pulse-indicator__label", children: label })
+      ]
+    }
+  );
+}
+function formatSeconds(seconds) {
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ago`;
+}
+
+// src/components/PulseStates.tsx
+import { useState as useState4, useEffect as useEffect4 } from "react";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function PulseLoadingState({
+  className,
+  text = "Loading..."
+}) {
+  return /* @__PURE__ */ jsxs3("div", { className: `pulse--loading ${className ?? ""}`, role: "status", "aria-live": "polite", children: [
+    /* @__PURE__ */ jsx3("span", { className: "pulse--spinner", "aria-hidden": "true" }),
+    /* @__PURE__ */ jsx3("span", { className: "pulse--loading-text", children: text })
+  ] });
+}
+function useSecondsAgo2(lastUpdated) {
+  const [secondsAgo, setSecondsAgo] = useState4(
+    () => Math.round((Date.now() - lastUpdated.getTime()) / 1e3)
+  );
+  useEffect4(() => {
+    const interval = setInterval(() => {
+      setSecondsAgo(Math.round((Date.now() - lastUpdated.getTime()) / 1e3));
+    }, 1e3);
+    return () => clearInterval(interval);
+  }, [lastUpdated]);
+  return secondsAgo;
+}
+function PulseErrorState({
+  meta,
+  className,
+  customMessage
+}) {
+  const secondsAgo = useSecondsAgo2(meta.lastUpdated);
+  return /* @__PURE__ */ jsxs3("div", { className: `pulse--error ${className ?? ""}`, role: "alert", children: [
+    "\u26A0\uFE0F ",
+    customMessage ?? `Connection lost. Last updated: ${secondsAgo}s ago`
+  ] });
+}
+function PulseEmptyState({
+  className,
+  text = "No data available"
+}) {
+  return /* @__PURE__ */ jsx3("div", { className: `pulse--empty ${className ?? ""}`, children: text });
+}
+function PulseStaleState({
+  meta,
+  className,
+  customMessage
+}) {
+  const secondsAgo = useSecondsAgo2(meta.lastUpdated);
+  return /* @__PURE__ */ jsxs3("div", { className: `pulse--stale ${className ?? ""}`, role: "status", children: [
+    "\u23F1\uFE0F ",
+    customMessage ?? `Data may be outdated. Last updated: ${secondsAgo}s ago`
+  ] });
+}
+function PulseSyncingState({
+  className,
+  text = "Syncing..."
+}) {
+  return /* @__PURE__ */ jsxs3("div", { className: `pulse--syncing ${className ?? ""}`, role: "status", "aria-live": "polite", children: [
+    /* @__PURE__ */ jsx3("span", { className: "pulse--spinner", "aria-hidden": "true" }),
+    /* @__PURE__ */ jsx3("span", { className: "pulse--syncing-text", children: text })
+  ] });
+}
+
+// src/hooks/useStreaming.ts
+function useStreaming(_options) {
+  return {
+    data: null,
+    isConnected: false,
+    isConnecting: false,
+    error: null
+  };
+}
+
+// src/validation/pulseValidator.ts
+function createPulseValidator(schema) {
+  return {
+    /**
+     * Validates data, throwing on failure
+     */
+    parse: (data) => {
+      return schema.parse(data);
+    },
+    /**
+     * Safe parse - returns null on failure
+     */
+    safeParse: (data) => {
+      const result = schema.safeParse(data);
+      return result.success ? result.data : null;
+    }
+  };
+}
+var PulseValidationError = class extends Error {
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+    this.name = "PulseValidationError";
+  }
+  /**
+   * Get formatted error messages
+   */
+  getFormattedErrors() {
+    return this.issues.map((issue) => ({
+      path: issue.path.join("."),
+      message: issue.message,
+      code: issue.code
+    }));
+  }
+};
+export {
+  Pulse,
+  PulseEmptyState,
+  PulseErrorState,
+  PulseIndicator,
+  PulseLoadingState,
+  PulseStaleState,
+  PulseSyncingState,
+  PulseValidationError,
+  createPulseValidator,
+  usePulse,
+  useStreaming
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@stackwright-pro/pulse",
+  "version": "0.1.0",
+  "description": "Source-agnostic real-time data polling for Stackwright Pro",
+  "license": "PROPRIETARY",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@testing-library/react": "^16.0.0",
+    "jsdom": "^25.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest"
+  }
+}