@siteping/widget 0.10.2 → 0.10.4

package/dist/react.d.cts

@@ -0,0 +1,59 @@
+import { SitepingConfig, SitepingInstance } from './siteping-core.cjs';
+
+/**
+ * React helper for `@siteping/widget`.
+ *
+ * `useSiteping` initialises the widget once for the lifetime of the component
+ * tree, even under React.StrictMode's double-invoke effect dance. Returns the
+ * `SitepingInstance` so consumers can drive `open()` / `close()` / `refresh()`
+ * programmatically from anywhere in their tree.
+ *
+ * Why a dedicated entry instead of a snippet in the README:
+ * - StrictMode mounts every effect twice in dev, which the obvious
+ *   `useEffect(() => { const i = initSiteping(...); return i.destroy }, [])`
+ *   handles fine for *re-mount*, but not for the brief window where the
+ *   second mount sees a still-alive widget (the widget's own singleton guard
+ *   logs an info message and returns the existing instance — surprising
+ *   noise for developers).
+ * - The hook also captures the latest `config` in a ref so callbacks (e.g.
+ *   `onFeedbackSent`) read closure values without re-initialising the widget.
+ *
+ * Peer dep on react ≥ 18 (declared as optional in package.json), so projects
+ * that never import `@siteping/widget/react` don't need React installed.
+ */
+
+/**
+ * Initialise the SitePing widget for the lifetime of the calling component.
+ *
+ * Safe to call from a Server Component file as long as the component itself
+ * is marked `"use client"` — the hook bails out cleanly on the server because
+ * `useEffect` never runs there.
+ *
+ * @example Next.js App Router
+ * ```tsx
+ * "use client"
+ * import { useSiteping } from "@siteping/widget/react"
+ *
+ * export function FeedbackProvider({ children }: { children: React.ReactNode }) {
+ *   useSiteping({
+ *     endpoint: "/api/siteping",
+ *     projectName: "my-app",
+ *   })
+ *   return <>{children}</>
+ * }
+ * ```
+ *
+ * @example Driving the panel programmatically
+ * ```tsx
+ * "use client"
+ * import { useSiteping } from "@siteping/widget/react"
+ *
+ * export function HelpButton() {
+ *   const widget = useSiteping({ endpoint: "/api/siteping", projectName: "my-app" })
+ *   return <button onClick={() => widget?.open()}>Need help?</button>
+ * }
+ * ```
+ */
+declare function useSiteping(config: SitepingConfig): SitepingInstance | null;
+
+export { useSiteping };