@hoardodile/sdk-react 0.0.0

package/src/use-extract-progress.test.tsx

@@ -0,0 +1,118 @@
+import { act } from "react"
+import { createRoot, type Root } from "react-dom/client"
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+import { StubPluginAPIProvider } from "./fixtures.tsx"
+import { useExtractProgress } from "./use-extract-progress.ts"
+
+function jsonResponse(payload: unknown): Response {
+	return { json: async () => payload } as Response
+}
+
+function renderHarness(progressUrl: () => string = () => "/progress") {
+	const container = document.createElement("div")
+	document.body.appendChild(container)
+	let root: Root | undefined
+	act(() => {
+		root = createRoot(container)
+		root.render(
+			<StubPluginAPIProvider api={{ extractProgressUrl: progressUrl }}>
+				<ProgressProbe />
+			</StubPluginAPIProvider>,
+		)
+	})
+	return { container, root }
+}
+
+function ProgressProbe() {
+	const progress = useExtractProgress()
+	return <div data-testid="state">{JSON.stringify(progress)}</div>
+}
+
+function stateOf(container: HTMLElement): Record<string, unknown> {
+	return JSON.parse(
+		container.querySelector("[data-testid='state']")!.textContent!,
+	)
+}
+
+describe("useExtractProgress", () => {
+	beforeEach(() => {
+		vi.useFakeTimers()
+	})
+
+	afterEach(() => {
+		vi.useRealTimers()
+		vi.unstubAllGlobals()
+		document.body.innerHTML = ""
+	})
+
+	test("starts idle and stays idle while the host reports nothing", async () => {
+		const fetchMock = vi.fn().mockResolvedValue(jsonResponse(null))
+		vi.stubGlobal("fetch", fetchMock)
+
+		const { container, root } = renderHarness()
+		await act(async () => {})
+		expect(stateOf(container)).toEqual({ state: "idle" })
+
+		await act(async () => {
+			vi.advanceTimersByTime(1000)
+		})
+		expect(stateOf(container)).toEqual({ state: "idle" })
+		root?.unmount()
+	})
+
+	test("reports in-flight materialization", async () => {
+		const fetchMock = vi
+			.fn()
+			.mockResolvedValue(jsonResponse({ done: 3, total: 10 }))
+		vi.stubGlobal("fetch", fetchMock)
+
+		const { container, root } = renderHarness()
+		await act(async () => {})
+		expect(stateOf(container)).toEqual({
+			state: "extracting",
+			done: 3,
+			total: 10,
+		})
+
+		await act(async () => {
+			vi.advanceTimersByTime(600)
+		})
+		expect(stateOf(container)).toEqual({
+			state: "extracting",
+			done: 3,
+			total: 10,
+		})
+		root?.unmount()
+	})
+
+	test("turns done once progress was seen and the record went idle", async () => {
+		const fetchMock = vi
+			.fn()
+			.mockResolvedValueOnce(jsonResponse({ done: 5, total: 10 }))
+			.mockResolvedValue(jsonResponse(null))
+		vi.stubGlobal("fetch", fetchMock)
+
+		const { container, root } = renderHarness()
+		await act(async () => {})
+		expect(stateOf(container)).toEqual({
+			state: "extracting",
+			done: 5,
+			total: 10,
+		})
+
+		await act(async () => {
+			vi.advanceTimersByTime(300)
+		})
+		expect(stateOf(container)).toEqual({ state: "done" })
+		root?.unmount()
+	})
+
+	test("treats a failed poll as idle", async () => {
+		vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network")))
+
+		const { container, root } = renderHarness()
+		await act(async () => {})
+		expect(stateOf(container)).toEqual({ state: "idle" })
+		root?.unmount()
+	})
+})

package/src/use-extract-progress.ts

@@ -0,0 +1,76 @@
+import { useEffect, useRef, useState } from "react"
+import { usePluginAPI } from "./context.tsx"
+
+/**
+ * Polling interval for {@link useExtractProgress}. The host's progress
+ * record lives in memory with a short TTL, so the poll must be tight
+ * enough to catch a row before it expires.
+ */
+const POLL_INTERVAL_MS = 300
+
+/**
+ * Materialization progress of the plugin's `extractArchive` hook:
+ * `"extracting"` while the host reports in-flight work, `"done"` once
+ * progress was seen and the record went idle again, `"idle"` when no
+ * extraction has ever been observed (or a poll failed — the host may
+ * not be serving yet).
+ */
+export type ExtractProgressState =
+	| { readonly state: "idle" }
+	| {
+			readonly state: "extracting"
+			readonly done: number
+			readonly total: number
+	  }
+	| { readonly state: "done" }
+
+/**
+ * Reactive materialization progress for the current resource. Polls
+ * `api.extractProgressUrl()` and tracks the seen-progress transition:
+ * a plugin that called `extractArchive` can show "extracting" while the
+ * host materializes, then switch to "done" when the record expires.
+ */
+export function useExtractProgress(): ExtractProgressState {
+	const api = usePluginAPI()
+	const [state, setState] = useState<ExtractProgressState>({ state: "idle" })
+	const seenProgress = useRef(false)
+
+	useEffect(
+		function pollProgress() {
+			let cancelled = false
+			seenProgress.current = false
+			setState({ state: "idle" })
+
+			async function poll(): Promise<void> {
+				let payload: unknown
+				try {
+					const response = await fetch(api.extractProgressUrl())
+					payload = await response.json()
+				} catch {
+					// A failed poll (host not serving yet) is treated as idle.
+					payload = null
+				}
+				if (cancelled) return
+				if (payload !== null && typeof payload === "object") {
+					const { done, total } = payload as Record<string, unknown>
+					if (typeof done === "number" && typeof total === "number") {
+						seenProgress.current = true
+						setState({ state: "extracting", done, total })
+						return
+					}
+				}
+				setState(seenProgress.current ? { state: "done" } : { state: "idle" })
+			}
+
+			void poll()
+			const timer = setInterval(() => void poll(), POLL_INTERVAL_MS)
+			return () => {
+				cancelled = true
+				clearInterval(timer)
+			}
+		},
+		[api],
+	)
+
+	return state
+}