@hoardodile/sdk-react 0.0.0

package/src/define-api.ts

@@ -0,0 +1,100 @@
+import type { PluginSchema } from "@hoardodile/sdk-types"
+import type {
+	AnchorData,
+	ReactivePluginAPI,
+	WebPluginAPI,
+} from "@hoardodile/sdk-web"
+import type { Provider } from "react"
+import { useContext, useEffect, useRef } from "react"
+import { PluginAPIContext } from "./context.tsx"
+
+/** The full API seen by React plugin components: imperative + hooks. */
+export type FullPluginAPI<TSchema extends PluginSchema> =
+	WebPluginAPI<TSchema> & ReactivePluginAPI<TSchema>
+
+export type DefinePluginAPIOptions<TSchema extends PluginSchema> = {
+	/**
+	 * Validate incoming anchor data (host → plugin) against the schema's
+	 * `anchor` slot. Anchors that fail decoding are dropped silently and
+	 * never reach the `useAnchorJump` callback. Declare this whenever the
+	 * schema declares an `anchor` type.
+	 */
+	readonly decodeAnchor?: (data: unknown) => TSchema["anchor"] | undefined
+}
+
+/**
+ * Define a typed plugin API context. The schema is declared once at module
+ * level — every consumer below gets properly typed access without repeating
+ * generics.
+ *
+ * The returned provider and hook share the same React context as the default
+ * {@link PluginAPIProvider}, so plugin roots created by `createPluginRoot`
+ * automatically satisfy typed consumers when the same provider is passed in.
+ *
+ * ```typescript
+ * interface VideoSchema { file: VideoFile; sourceMeta: VideoSourceMeta; anchor: VideoTimeAnchor }
+ * const { PluginAPIProvider, usePluginAPI, useAnchorJump } = definePluginAPI<VideoSchema>({
+ *   decodeAnchor: decodeVideoTimeAnchor,
+ * })
+ *
+ * function Viewer() {
+ *   const api = usePluginAPI()
+ *   const { data: files } = api.useFileList()
+ *   // files → readonly VideoFile[] | undefined
+ * }
+ * ```
+ */
+export function definePluginAPI<TSchema extends PluginSchema = PluginSchema>(
+	options?: DefinePluginAPIOptions<TSchema>,
+): {
+	readonly PluginAPIProvider: Provider<FullPluginAPI<TSchema> | null>
+	readonly usePluginAPI: () => FullPluginAPI<TSchema>
+	readonly useAnchorJump: (cb: (anchor: TSchema["anchor"]) => void) => void
+} {
+	const decodeAnchor = options?.decodeAnchor
+
+	function useTypedPluginAPI(): FullPluginAPI<TSchema> {
+		const api = useContext(PluginAPIContext)
+		if (api === null) {
+			throw new Error("usePluginAPI must be used within a PluginAPIProvider")
+		}
+		// SDK boundary: the shared context stores the base API; the schema
+		// slots narrow it for this plugin. Declared once here so consumers
+		// stay cast-free.
+		return api as unknown as FullPluginAPI<TSchema>
+	}
+
+	/**
+	 * Typed anchor-jump hook: incoming anchor data is decoded once at the
+	 * SDK boundary, so the callback receives the schema's anchor type
+	 * directly with no manual narrowing. The latest callback is invoked
+	 * without resubscribing on every render.
+	 */
+	function useTypedAnchorJump(cb: (anchor: TSchema["anchor"]) => void) {
+		const api = useTypedPluginAPI()
+		const cbRef = useRef(cb)
+		cbRef.current = cb
+
+		useEffect(
+			function subscribe() {
+				return api.onAnchorJump(function handle(anchor: AnchorData) {
+					if (decodeAnchor === undefined) {
+						cbRef.current(anchor.data as TSchema["anchor"])
+						return
+					}
+					const data = decodeAnchor(anchor.data)
+					if (data === undefined) return
+					cbRef.current(data)
+				})
+			},
+			[api],
+		)
+	}
+
+	return {
+		PluginAPIProvider:
+			PluginAPIContext.Provider as Provider<FullPluginAPI<TSchema> | null>,
+		usePluginAPI: useTypedPluginAPI,
+		useAnchorJump: useTypedAnchorJump,
+	}
+}

package/src/fixtures.tsx

@@ -0,0 +1,25 @@
+import { createWebPluginAPI, type DeepPartial } from "@hoardodile/sdk-web"
+import type { ReactNode } from "react"
+import { type BasePluginAPI, PluginAPIProvider } from "./context.tsx"
+
+export { createWebPluginAPI, type DeepPartial } from "@hoardodile/sdk-web"
+
+/**
+ * Wrap children with a stubbed API provider for tests. Builds the stub
+ * via `createWebPluginAPI` from `@hoardodile/sdk-web` (re-exported
+ * below) — the imperative surface plus no-op reactive hooks, overridable
+ * via `api`.
+ */
+export function StubPluginAPIProvider({
+	api,
+	children,
+}: {
+	readonly api?: DeepPartial<BasePluginAPI>
+	readonly children: ReactNode
+}) {
+	return (
+		<PluginAPIProvider value={createWebPluginAPI(api)}>
+			{children}
+		</PluginAPIProvider>
+	)
+}

package/src/i18n.test.tsx

@@ -0,0 +1,147 @@
+import { act } from "react"
+import { createRoot, type Root } from "react-dom/client"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { createPluginTranslation } from "./i18n.ts"
+
+// The wire payload is a bare string; the legacy object shape must keep
+// working, so the mock accepts both.
+type LanguagePush = string | { language: string }
+
+const mocks = vi.hoisted(() => ({
+	contextLanguage: { value: "en" as string | undefined },
+	pushHandlers: [] as ((data: LanguagePush) => void)[],
+}))
+
+vi.mock("@hoardodile/sdk-web", () => ({
+	ensureHostBridge: () => ({
+		subscribe: (
+			_key: string,
+			handler: (data: LanguagePush) => void,
+		): (() => void) => {
+			mocks.pushHandlers.push(handler)
+			return () => {}
+		},
+	}),
+	getPluginContext: () =>
+		mocks.contextLanguage.value === undefined
+			? undefined
+			: { language: mocks.contextLanguage.value },
+}))
+
+const BUNDLES = {
+	en: { greeting: "Hello", withName: "Hi {{name}}" },
+	zh: { greeting: "你好", withName: "你好 {{name}}" },
+}
+
+function renderProbe() {
+	const container = document.createElement("div")
+	document.body.appendChild(container)
+	const { useTranslation } = createPluginTranslation(BUNDLES)
+	let root: Root | undefined
+	let translation:
+		| {
+				t: (key: string, vars?: Record<string, string | number>) => string
+				language: string
+		  }
+		| undefined
+
+	function Probe() {
+		translation = useTranslation()
+		return <div data-testid="out">{translation.t("greeting")}</div>
+	}
+
+	act(() => {
+		root = createRoot(container)
+		root.render(<Probe />)
+	})
+
+	return {
+		text: () =>
+			container.querySelector("[data-testid='out']")?.textContent ?? "",
+		current: () => translation!,
+		unmount: () => {
+			act(() => {
+				root?.unmount()
+			})
+			container.remove()
+		},
+	}
+}
+
+afterEach(() => {
+	mocks.contextLanguage.value = "en"
+	mocks.pushHandlers.length = 0
+})
+
+describe("createPluginTranslation", () => {
+	beforeEach(() => {
+		mocks.pushHandlers.length = 0
+	})
+
+	it("starts in the language from the plugin context", () => {
+		mocks.contextLanguage.value = "zh"
+		const probe = renderProbe()
+		expect(probe.text()).toBe("你好")
+		expect(probe.current().language).toBe("zh")
+		probe.unmount()
+	})
+
+	it("updates when the host pushes a language change", () => {
+		mocks.contextLanguage.value = "en"
+		const probe = renderProbe()
+		expect(probe.text()).toBe("Hello")
+
+		// The real wire payload is a bare language-code string.
+		act(() => {
+			for (const handler of mocks.pushHandlers) {
+				handler("zh")
+			}
+		})
+		expect(probe.text()).toBe("你好")
+		expect(probe.current().language).toBe("zh")
+		probe.unmount()
+	})
+
+	it("still accepts the legacy object-shaped language push", () => {
+		mocks.contextLanguage.value = "en"
+		const probe = renderProbe()
+
+		act(() => {
+			for (const handler of mocks.pushHandlers) {
+				handler({ language: "zh" })
+			}
+		})
+		expect(probe.text()).toBe("你好")
+		probe.unmount()
+	})
+
+	it("stays in the host language and falls back to English for missing bundle languages", () => {
+		mocks.contextLanguage.value = "ja"
+		const probe = renderProbe()
+		// The plugin ships en/zh only; the shared ui namespace still
+		// resolves the host language, plugin strings fall back to en.
+		expect(probe.current().language).toBe("ja")
+		expect(probe.text()).toBe("Hello")
+		probe.unmount()
+	})
+
+	it("interpolates {{var}} placeholders", () => {
+		const probe = renderProbe()
+		expect(probe.current().t("withName", { name: "A" })).toBe("Hi A")
+		probe.unmount()
+	})
+
+	it("returns the key when the message is missing", () => {
+		const probe = renderProbe()
+		expect(probe.current().t("noSuchKey")).toBe("noSuchKey")
+		probe.unmount()
+	})
+
+	it("ignores the host push when no bridge subscription ran yet", () => {
+		mocks.contextLanguage.value = "en"
+		const probe = renderProbe()
+		const before = mocks.pushHandlers.length
+		expect(before).toBeGreaterThan(0)
+		probe.unmount()
+	})
+})

package/src/i18n.ts

@@ -0,0 +1,96 @@
+import { uiCatalogFor } from "@hoardodile/i18n/catalogs/ui"
+import { isSupportedLanguage, SUPPORTED_LANGUAGES } from "@hoardodile/i18n/core"
+import { createI18n } from "@hoardodile/i18n/create-i18n"
+import { ensureHostBridge, getPluginContext } from "@hoardodile/sdk-web"
+import type { Resource } from "i18next"
+import { useEffect } from "react"
+import { setI18n, useTranslation as useReactTranslation } from "react-i18next"
+
+type RawBundle = Record<string, unknown>
+
+type InterpolationVars = Record<string, string | number>
+
+type PluginTranslation = {
+	readonly t: (key: string, vars?: InterpolationVars) => string
+	readonly language: string
+}
+
+function resolveLocale(lang: string, available: Set<string>): string {
+	if (available.has(lang)) return lang
+	const base = lang.split("-")[0]!
+	if (available.has(base)) return base
+	return "en"
+}
+
+/**
+ * Creates a `useTranslation` hook backed by the given locale bundles plus
+ * the shared `ui` catalog namespace (so `@hoardodile/ui` components
+ * render localized chrome in every supported host language).
+ *
+ * Backed by i18next/react-i18next with the same options as the host
+ * surfaces: the language follows the plugin context, updates when the
+ * host sends a `languageChanged` push, interpolates `{{var}}`
+ * placeholders, and falls back to English (via `fallbackLng`) for
+ * languages the plugin's own bundle does not ship.
+ */
+export function createPluginTranslation(bundles: Record<string, RawBundle>): {
+	readonly useTranslation: () => PluginTranslation
+} {
+	const availableLangs = new Set<string>([
+		...Object.keys(bundles),
+		...SUPPORTED_LANGUAGES,
+	])
+
+	// The small shared `ui` namespace (every supported language, so ui
+	// chrome always matches the host language) plus the plugin's own
+	// `plugin` namespace — never the full app catalog (the iframe bundle
+	// stays a fraction of the SPA's i18n payload).
+	const resources: Resource = {}
+	for (const language of availableLangs) {
+		const base = language.split("-")[0]!
+		resources[language] = {
+			...(isSupportedLanguage(base) ? { ui: uiCatalogFor(base) } : {}),
+			...(bundles[language] === undefined ? {} : { plugin: bundles[language] }),
+		}
+	}
+
+	const initial = resolveLocale(
+		getPluginContext()?.language ?? "en",
+		availableLangs,
+	)
+	const instance = createI18n({ lng: initial, resources })
+
+	// Bind as react-i18next's default instance so every `@hoardodile/ui`
+	// component rendered in this iframe resolves the same instance.
+	setI18n(instance)
+
+	let subscribed = false
+	function subscribeToLanguageChanges(): void {
+		if (subscribed) return
+		subscribed = true
+		ensureHostBridge().subscribe("languageChanged", (data) => {
+			// The wire payload is a bare language-code string (predates the
+			// typed protocol table); accept the legacy object shape too so
+			// plugins compiled against either contract keep switching.
+			const language =
+				typeof data === "string"
+					? data
+					: String((data as { language?: string }).language ?? "")
+			void instance.changeLanguage(resolveLocale(language, availableLangs))
+		})
+	}
+
+	function useTranslation(): PluginTranslation {
+		useEffect(subscribeToLanguageChanges, [])
+		const { t, i18n } = useReactTranslation("plugin", {
+			i18n: instance,
+			useSuspense: false,
+		})
+		return {
+			t: t as unknown as PluginTranslation["t"],
+			language: i18n.resolvedLanguage ?? i18n.language,
+		}
+	}
+
+	return { useTranslation }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { PluginAPIProvider, usePluginAPI } from "./context.tsx"
+export {
+	type DefinePluginAPIOptions,
+	definePluginAPI,
+	type FullPluginAPI,
+} from "./define-api.ts"
+export {
+	createWebPluginAPI,
+	type DeepPartial,
+	StubPluginAPIProvider,
+} from "./fixtures.tsx"
+export { createPluginTranslation } from "./i18n.ts"
+export { createPluginQueryAPI } from "./query.ts"
+export {
+	createPluginRoot,
+	type PluginRootConfig,
+	useVisibility,
+} from "./root.tsx"
+export { useCacheWriter } from "./use-cache-writer.ts"
+export {
+	type ExtractProgressState,
+	useExtractProgress,
+} from "./use-extract-progress.ts"