@jamwidgets/react 0.1.0

package/README.md

@@ -0,0 +1,288 @@
+# @jamwidgets/react
+
+> **Note:** This repo is a read-only mirror. Source lives in a private monorepo.
+> For issues/PRs, please open them here and we'll sync changes back.
+
+React hooks for [JamWidgets](https://jamwidgets.com) widgets - comments, reactions, forms, subscriptions, and more.
+
+## Installation
+
+```bash
+npm install @jamwidgets/react
+```
+
+Works with React 18+ and React 19. Compatible with Next.js, Remix, Vite, and more.
+
+## Hooks
+
+### useSubscribe
+
+Email subscription form:
+
+```tsx
+import { useSubscribe } from "@jamwidgets/react";
+
+function SubscribeForm() {
+  const [email, setEmail] = useState("");
+  const { submit, status, message, error } = useSubscribe({
+    siteKey: "your-key",
+  });
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await submit(email);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="your@email.com"
+      />
+      <button disabled={status === "loading"}>
+        {status === "loading" ? "Subscribing..." : "Subscribe"}
+      </button>
+      {status === "success" && <p>{message}</p>}
+      {status === "error" && <p>{error?.message}</p>}
+    </form>
+  );
+}
+```
+
+### useReactions
+
+Reaction buttons (like, love, clap, etc.):
+
+```tsx
+import { useReactions } from "@jamwidgets/react";
+
+function LikeButton() {
+  const { counts, userReactions, add, remove, status } = useReactions({
+    siteKey: "your-key",
+    pageId: "my-page",
+  });
+
+  const hasLiked = userReactions.includes("like");
+
+  return (
+    <button onClick={() => (hasLiked ? remove("like") : add("like"))}>
+      {hasLiked ? "Unlike" : "Like"} ({counts.like || 0})
+    </button>
+  );
+}
+```
+
+### useComments
+
+Threaded comments:
+
+```tsx
+import { useComments } from "@jamwidgets/react";
+
+function Comments() {
+  const { comments, post, status, error } = useComments({
+    siteKey: "your-key",
+    pageId: "my-page",
+  });
+
+  const handleSubmit = async (name, content) => {
+    await post(name, content);
+  };
+
+  return (
+    <div>
+      {comments.map((comment) => (
+        <div key={comment.id}>
+          <strong>{comment.authorName}</strong>
+          <p>{comment.content}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### useForm
+
+Contact forms with spam protection:
+
+```tsx
+import { useForm } from "@jamwidgets/react";
+
+function ContactForm() {
+  const { submit, status, message } = useForm({
+    siteKey: "your-key",
+    formSlug: "contact",
+  });
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    const data = Object.fromEntries(new FormData(e.target));
+    await submit(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+      {status === "success" && <p>{message}</p>}
+    </form>
+  );
+}
+```
+
+### useWaitlist
+
+Waitlist signups:
+
+```tsx
+import { useWaitlist } from "@jamwidgets/react";
+
+function WaitlistForm() {
+  const { join, status, message, position } = useWaitlist({
+    siteKey: "your-key",
+  });
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await join(email, { name, source: "homepage" });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="email" type="email" required />
+      <button type="submit">Join Waitlist</button>
+      {status === "success" && <p>{message}</p>}
+    </form>
+  );
+}
+```
+
+### useFeedback
+
+Feedback forms:
+
+```tsx
+import { useFeedback } from "@jamwidgets/react";
+
+function FeedbackWidget() {
+  const { submit, status, message } = useFeedback({
+    siteKey: "your-key",
+  });
+
+  const handleSubmit = async (type, content) => {
+    await submit(type, content, { email, pageUrl: window.location.href });
+  };
+
+  // ...
+}
+```
+
+### usePoll
+
+Polls and voting:
+
+```tsx
+import { usePoll } from "@jamwidgets/react";
+
+function Poll() {
+  const { poll, vote, hasVoted, status } = usePoll({
+    siteKey: "your-key",
+    pollId: 123,
+  });
+
+  if (!poll) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h3>{poll.question}</h3>
+      {poll.options.map((option) => (
+        <button
+          key={option.id}
+          onClick={() => vote([option.id])}
+          disabled={hasVoted}
+        >
+          {option.text} ({poll.results?.[option.id] || 0})
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### useAnnouncements
+
+Site announcements:
+
+```tsx
+import { useAnnouncements } from "@jamwidgets/react";
+
+function AnnouncementBanner() {
+  const { announcements, dismiss, status } = useAnnouncements({
+    siteKey: "your-key",
+  });
+
+  const visible = announcements.filter((a) => !a.dismissed);
+
+  return (
+    <>
+      {visible.map((announcement) => (
+        <div key={announcement.id}>
+          <p>{announcement.content}</p>
+          {announcement.isDismissible && (
+            <button onClick={() => dismiss(announcement.id)}>Dismiss</button>
+          )}
+        </div>
+      ))}
+    </>
+  );
+}
+```
+
+### useViewCounts
+
+Page view tracking:
+
+```tsx
+import { useViewCounts } from "@jamwidgets/react";
+import { useEffect } from "react";
+
+function PageViews() {
+  const { views, uniqueVisitors, record, status } = useViewCounts({
+    siteKey: "your-key",
+    pageId: "my-page",
+  });
+
+  // Record view on mount
+  useEffect(() => {
+    record();
+  }, []);
+
+  return (
+    <span>
+      {views} views ({uniqueVisitors} unique)
+    </span>
+  );
+}
+```
+
+## All Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useSubscribe` | Email subscriptions |
+| `useReactions` | Page reactions |
+| `useComments` | Threaded comments |
+| `useForm` | Form submissions |
+| `useWaitlist` | Waitlist signups |
+| `useFeedback` | Feedback forms |
+| `usePoll` | Polls and voting |
+| `useAnnouncements` | Site announcements |
+| `useViewCounts` | Page view tracking |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+/**
+ * @jamwidgets/react - React hooks for Jamwidgets
+ *
+ * @example Subscribe form
+ * ```tsx
+ * import { useSubscribe } from '@jamwidgets/react';
+ *
+ * function Newsletter() {
+ *   const { subscribe, status, error } = useSubscribe({
+ *     siteKey: 'your-site-key',
+ *   });
+ *
+ *   const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+ *     e.preventDefault();
+ *     const email = new FormData(e.currentTarget).get('email') as string;
+ *     subscribe(email);
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input type="email" name="email" required />
+ *       <button disabled={status === 'loading'}>
+ *         {status === 'loading' ? 'Subscribing...' : 'Subscribe'}
+ *       </button>
+ *       {status === 'success' && <p>Thanks for subscribing!</p>}
+ *       {status === 'error' && <p>Error: {error?.message}</p>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+import { type JamWidgetsConfig, type Comment, type Announcement, type PollWithResults, type FeedbackType, type ControllerStatus } from "@jamwidgets/core";
+export type { JamWidgetsConfig, SubscribeState, FormState, ReactionsState, CommentsState, WaitlistState, ViewCountsState, FeedbackState, PollState, AnnouncementsState, Comment, Announcement, PollWithResults, FeedbackType, ReactionCounts, JamwidgetsPost, SeriphPost, // deprecated alias
+FetchPostsOptions, FetchPostOptions, ControllerStatus, } from "@jamwidgets/core";
+export { fetchPosts, fetchPost, getConfigFromMeta, resolveConfig, DEFAULT_ENDPOINT, API_PATH, } from "@jamwidgets/core";
+type OptionalSiteKey<T extends JamWidgetsConfig> = Omit<T, "siteKey"> & {
+    /** Site key - optional if <meta name="jamwidgets-site-key"> is set */
+    siteKey?: string;
+};
+export interface UseSubscribeOptions extends OptionalSiteKey<JamWidgetsConfig> {
+}
+export interface UseSubscribeReturn {
+    status: ControllerStatus;
+    message: string | null;
+    error: Error | null;
+    subscribe: (email: string) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Hook for handling email subscriptions.
+ *
+ * @example
+ * ```tsx
+ * const { subscribe, status, message, error } = useSubscribe({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * <button onClick={() => subscribe('user@example.com')}>Subscribe</button>
+ * ```
+ */
+export declare function useSubscribe(options: UseSubscribeOptions): UseSubscribeReturn;
+export interface UseFormOptions extends OptionalSiteKey<JamWidgetsConfig> {
+    /** Form slug/identifier */
+    formSlug: string;
+}
+export interface UseFormReturn {
+    status: ControllerStatus;
+    message: string | null;
+    error: Error | null;
+    submit: (data: Record<string, unknown>) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Hook for handling form submissions.
+ *
+ * @example
+ * ```tsx
+ * const { submit, status, error } = useForm({
+ *   siteKey: 'your-site-key',
+ *   formSlug: 'contact',
+ * });
+ *
+ * const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+ *   e.preventDefault();
+ *   const formData = new FormData(e.currentTarget);
+ *   submit(Object.fromEntries(formData));
+ * };
+ * ```
+ */
+export declare function useForm(options: UseFormOptions): UseFormReturn;
+export interface UseReactionsOptions extends OptionalSiteKey<JamWidgetsConfig> {
+    /** Content identifier (e.g., post slug) */
+    contentId: string;
+    /** Auto-fetch reactions on mount (default: true) */
+    autoFetch?: boolean;
+}
+export interface UseReactionsReturn {
+    counts: Record<string, number>;
+    userReactions: string[];
+    status: ControllerStatus;
+    error: Error | null;
+    addReaction: (type: string) => Promise<void>;
+    removeReaction: (type: string) => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for handling reactions (likes, claps, etc.).
+ *
+ * @example
+ * ```tsx
+ * const { counts, userReactions, addReaction, removeReaction } = useReactions({
+ *   siteKey: 'your-site-key',
+ *   contentId: 'my-post-slug',
+ * });
+ *
+ * <button onClick={() => addReaction('like')}>
+ *   Like ({counts.like || 0})
+ * </button>
+ * ```
+ */
+export declare function useReactions(options: UseReactionsOptions): UseReactionsReturn;
+export interface UseCommentsOptions extends OptionalSiteKey<JamWidgetsConfig> {
+    /** Content identifier (e.g., post slug) */
+    contentId: string;
+    /** Auto-fetch comments on mount (default: true) */
+    autoFetch?: boolean;
+}
+export interface UseCommentsReturn {
+    comments: Comment[];
+    status: ControllerStatus;
+    error: Error | null;
+    postComment: (author: string, content: string, options?: {
+        authorEmail?: string;
+        parentId?: string;
+    }) => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for handling comments.
+ *
+ * @example
+ * ```tsx
+ * const { comments, status, postComment } = useComments({
+ *   siteKey: 'your-site-key',
+ *   contentId: 'my-post-slug',
+ * });
+ *
+ * {comments.map(comment => (
+ *   <div key={comment.id}>
+ *     <strong>{comment.authorName}</strong>: {comment.content}
+ *   </div>
+ * ))}
+ *
+ * <button onClick={() => postComment('Anonymous', 'Great post!')}>
+ *   Add Comment
+ * </button>
+ * ```
+ */
+export declare function useComments(options: UseCommentsOptions): UseCommentsReturn;
+export interface UseWaitlistOptions extends OptionalSiteKey<JamWidgetsConfig> {
+}
+export interface UseWaitlistReturn {
+    status: ControllerStatus;
+    message: string | null;
+    position: number | null;
+    error: Error | null;
+    join: (email: string, options?: {
+        name?: string;
+        source?: string;
+    }) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Hook for handling waitlist signups.
+ *
+ * @example
+ * ```tsx
+ * const { join, status, message, position } = useWaitlist({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * <button onClick={() => join('user@example.com')}>Join Waitlist</button>
+ * {status === 'success' && <p>You're #{position} on the list!</p>}
+ * ```
+ */
+export declare function useWaitlist(options: UseWaitlistOptions): UseWaitlistReturn;
+export interface UseViewsOptions extends OptionalSiteKey<JamWidgetsConfig> {
+    /** Page identifier (e.g., slug or URL path) */
+    pageId: string;
+    /** Auto-record view on mount (default: true) */
+    autoRecord?: boolean;
+}
+export interface UseViewsReturn {
+    views: number;
+    uniqueVisitors: number;
+    status: ControllerStatus;
+    error: Error | null;
+    record: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for tracking and displaying page views.
+ *
+ * @example
+ * ```tsx
+ * const { views, uniqueVisitors } = useViews({
+ *   siteKey: 'your-site-key',
+ *   pageId: '/blog/my-post',
+ * });
+ *
+ * <span>{views} views ({uniqueVisitors} unique)</span>
+ * ```
+ */
+export declare function useViews(options: UseViewsOptions): UseViewsReturn;
+export interface UseFeedbackOptions extends OptionalSiteKey<JamWidgetsConfig> {
+}
+export interface UseFeedbackReturn {
+    status: ControllerStatus;
+    message: string | null;
+    error: Error | null;
+    submit: (type: FeedbackType, content: string, options?: {
+        email?: string;
+        pageUrl?: string;
+    }) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Hook for handling feedback submissions.
+ *
+ * @example
+ * ```tsx
+ * const { submit, status } = useFeedback({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * <button onClick={() => submit('feature', 'Add dark mode!')}>
+ *   Submit Feedback
+ * </button>
+ * ```
+ */
+export declare function useFeedback(options: UseFeedbackOptions): UseFeedbackReturn;
+export interface UsePollOptions extends OptionalSiteKey<JamWidgetsConfig> {
+    /** Poll slug */
+    slug: string;
+    /** Auto-fetch poll on mount (default: true) */
+    autoFetch?: boolean;
+}
+export interface UsePollReturn {
+    poll: PollWithResults | null;
+    status: ControllerStatus;
+    error: Error | null;
+    vote: (selectedOptions: string[]) => Promise<void>;
+    hasVoted: boolean;
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for displaying and voting on polls.
+ *
+ * @example
+ * ```tsx
+ * const { poll, vote, hasVoted } = usePoll({
+ *   siteKey: 'your-site-key',
+ *   slug: 'favorite-framework',
+ * });
+ *
+ * {poll && (
+ *   <div>
+ *     <h3>{poll.question}</h3>
+ *     {poll.options.map(opt => (
+ *       <button key={opt.id} onClick={() => vote([opt.id])} disabled={hasVoted}>
+ *         {opt.text} ({poll.results[opt.id] || 0} votes)
+ *       </button>
+ *     ))}
+ *   </div>
+ * )}
+ * ```
+ */
+export declare function usePoll(options: UsePollOptions): UsePollReturn;
+export interface UseAnnouncementsOptions extends OptionalSiteKey<JamWidgetsConfig> {
+    /** Auto-fetch announcements on mount (default: true) */
+    autoFetch?: boolean;
+}
+export interface UseAnnouncementsReturn {
+    announcements: Announcement[];
+    status: ControllerStatus;
+    error: Error | null;
+    dismiss: (announcementId: number) => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for displaying site announcements.
+ *
+ * @example
+ * ```tsx
+ * const { announcements, dismiss } = useAnnouncements({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * {announcements.map(ann => (
+ *   <div key={ann.id} className={`announcement-${ann.announcementType}`}>
+ *     {ann.content}
+ *     {ann.isDismissible && (
+ *       <button onClick={() => dismiss(ann.id)}>Dismiss</button>
+ *     )}
+ *   </div>
+ * ))}
+ * ```
+ */
+export declare function useAnnouncements(options: UseAnnouncementsOptions): UseAnnouncementsReturn;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,410 @@
+/**
+ * @jamwidgets/react - React hooks for Jamwidgets
+ *
+ * @example Subscribe form
+ * ```tsx
+ * import { useSubscribe } from '@jamwidgets/react';
+ *
+ * function Newsletter() {
+ *   const { subscribe, status, error } = useSubscribe({
+ *     siteKey: 'your-site-key',
+ *   });
+ *
+ *   const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+ *     e.preventDefault();
+ *     const email = new FormData(e.currentTarget).get('email') as string;
+ *     subscribe(email);
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input type="email" name="email" required />
+ *       <button disabled={status === 'loading'}>
+ *         {status === 'loading' ? 'Subscribing...' : 'Subscribe'}
+ *       </button>
+ *       {status === 'success' && <p>Thanks for subscribing!</p>}
+ *       {status === 'error' && <p>Error: {error?.message}</p>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+import { useState, useCallback, useEffect, useRef } from "react";
+import { SubscribeController, FormController, ReactionsController, CommentsController, WaitlistController, ViewCountsController, FeedbackController, PollController, AnnouncementsController, resolveConfig, } from "@jamwidgets/core";
+// Re-export API functions and helpers from core
+export { fetchPosts, fetchPost, getConfigFromMeta, resolveConfig, DEFAULT_ENDPOINT, API_PATH, } from "@jamwidgets/core";
+/**
+ * Hook for handling email subscriptions.
+ *
+ * @example
+ * ```tsx
+ * const { subscribe, status, message, error } = useSubscribe({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * <button onClick={() => subscribe('user@example.com')}>Subscribe</button>
+ * ```
+ */
+export function useSubscribe(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        status: "idle",
+        message: null,
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new SubscribeController(config);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint]);
+    const subscribe = useCallback(async (email) => {
+        await controllerRef.current?.submit(email);
+    }, []);
+    const reset = useCallback(() => {
+        controllerRef.current?.reset();
+    }, []);
+    return { ...state, subscribe, reset };
+}
+/**
+ * Hook for handling form submissions.
+ *
+ * @example
+ * ```tsx
+ * const { submit, status, error } = useForm({
+ *   siteKey: 'your-site-key',
+ *   formSlug: 'contact',
+ * });
+ *
+ * const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+ *   e.preventDefault();
+ *   const formData = new FormData(e.currentTarget);
+ *   submit(Object.fromEntries(formData));
+ * };
+ * ```
+ */
+export function useForm(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        status: "idle",
+        message: null,
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new FormController(config, options.formSlug);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint, options.formSlug]);
+    const submit = useCallback(async (data) => {
+        await controllerRef.current?.submit(data);
+    }, []);
+    const reset = useCallback(() => {
+        controllerRef.current?.reset();
+    }, []);
+    return { ...state, submit, reset };
+}
+/**
+ * Hook for handling reactions (likes, claps, etc.).
+ *
+ * @example
+ * ```tsx
+ * const { counts, userReactions, addReaction, removeReaction } = useReactions({
+ *   siteKey: 'your-site-key',
+ *   contentId: 'my-post-slug',
+ * });
+ *
+ * <button onClick={() => addReaction('like')}>
+ *   Like ({counts.like || 0})
+ * </button>
+ * ```
+ */
+export function useReactions(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        counts: {},
+        userReactions: [],
+        status: "idle",
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new ReactionsController(config, options.contentId);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        // Auto-fetch on mount (default: true)
+        if (options.autoFetch !== false) {
+            controller.fetch();
+        }
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint, options.contentId]);
+    const addReaction = useCallback(async (type) => {
+        await controllerRef.current?.add(type);
+    }, []);
+    const removeReaction = useCallback(async (type) => {
+        await controllerRef.current?.remove(type);
+    }, []);
+    const refresh = useCallback(async () => {
+        await controllerRef.current?.fetch();
+    }, []);
+    return { ...state, addReaction, removeReaction, refresh };
+}
+/**
+ * Hook for handling comments.
+ *
+ * @example
+ * ```tsx
+ * const { comments, status, postComment } = useComments({
+ *   siteKey: 'your-site-key',
+ *   contentId: 'my-post-slug',
+ * });
+ *
+ * {comments.map(comment => (
+ *   <div key={comment.id}>
+ *     <strong>{comment.authorName}</strong>: {comment.content}
+ *   </div>
+ * ))}
+ *
+ * <button onClick={() => postComment('Anonymous', 'Great post!')}>
+ *   Add Comment
+ * </button>
+ * ```
+ */
+export function useComments(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        comments: [],
+        status: "idle",
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new CommentsController(config, options.contentId);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        // Auto-fetch on mount (default: true)
+        if (options.autoFetch !== false) {
+            controller.fetch();
+        }
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint, options.contentId]);
+    const postComment = useCallback(async (author, content, options) => {
+        await controllerRef.current?.post(author, content, options);
+    }, []);
+    const refresh = useCallback(async () => {
+        await controllerRef.current?.fetch();
+    }, []);
+    return { ...state, postComment, refresh };
+}
+/**
+ * Hook for handling waitlist signups.
+ *
+ * @example
+ * ```tsx
+ * const { join, status, message, position } = useWaitlist({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * <button onClick={() => join('user@example.com')}>Join Waitlist</button>
+ * {status === 'success' && <p>You're #{position} on the list!</p>}
+ * ```
+ */
+export function useWaitlist(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        status: "idle",
+        message: null,
+        position: null,
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new WaitlistController(config);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint]);
+    const join = useCallback(async (email, opts) => {
+        await controllerRef.current?.join(email, opts);
+    }, []);
+    const reset = useCallback(() => {
+        controllerRef.current?.reset();
+    }, []);
+    return { ...state, join, reset };
+}
+/**
+ * Hook for tracking and displaying page views.
+ *
+ * @example
+ * ```tsx
+ * const { views, uniqueVisitors } = useViews({
+ *   siteKey: 'your-site-key',
+ *   pageId: '/blog/my-post',
+ * });
+ *
+ * <span>{views} views ({uniqueVisitors} unique)</span>
+ * ```
+ */
+export function useViews(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        pageId: options.pageId,
+        views: 0,
+        uniqueVisitors: 0,
+        status: "idle",
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new ViewCountsController(config, options.pageId);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        // Auto-record view on mount (default: true)
+        if (options.autoRecord !== false) {
+            controller.record();
+        }
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint, options.pageId]);
+    const record = useCallback(async () => {
+        await controllerRef.current?.record();
+    }, []);
+    const refresh = useCallback(async () => {
+        await controllerRef.current?.fetch();
+    }, []);
+    return { views: state.views, uniqueVisitors: state.uniqueVisitors, status: state.status, error: state.error, record, refresh };
+}
+/**
+ * Hook for handling feedback submissions.
+ *
+ * @example
+ * ```tsx
+ * const { submit, status } = useFeedback({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * <button onClick={() => submit('feature', 'Add dark mode!')}>
+ *   Submit Feedback
+ * </button>
+ * ```
+ */
+export function useFeedback(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        status: "idle",
+        message: null,
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new FeedbackController(config);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint]);
+    const submit = useCallback(async (type, content, opts) => {
+        await controllerRef.current?.submit(type, content, opts);
+    }, []);
+    const reset = useCallback(() => {
+        controllerRef.current?.reset();
+    }, []);
+    return { ...state, submit, reset };
+}
+/**
+ * Hook for displaying and voting on polls.
+ *
+ * @example
+ * ```tsx
+ * const { poll, vote, hasVoted } = usePoll({
+ *   siteKey: 'your-site-key',
+ *   slug: 'favorite-framework',
+ * });
+ *
+ * {poll && (
+ *   <div>
+ *     <h3>{poll.question}</h3>
+ *     {poll.options.map(opt => (
+ *       <button key={opt.id} onClick={() => vote([opt.id])} disabled={hasVoted}>
+ *         {opt.text} ({poll.results[opt.id] || 0} votes)
+ *       </button>
+ *     ))}
+ *   </div>
+ * )}
+ * ```
+ */
+export function usePoll(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        poll: null,
+        status: "idle",
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new PollController(config, options.slug);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        // Auto-fetch on mount (default: true)
+        if (options.autoFetch !== false) {
+            controller.fetch();
+        }
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint, options.slug]);
+    const vote = useCallback(async (selectedOptions) => {
+        await controllerRef.current?.vote(selectedOptions);
+    }, []);
+    const refresh = useCallback(async () => {
+        await controllerRef.current?.fetch();
+    }, []);
+    const hasVoted = controllerRef.current?.hasVoted() ?? false;
+    return { ...state, vote, hasVoted, refresh };
+}
+/**
+ * Hook for displaying site announcements.
+ *
+ * @example
+ * ```tsx
+ * const { announcements, dismiss } = useAnnouncements({
+ *   siteKey: 'your-site-key',
+ * });
+ *
+ * {announcements.map(ann => (
+ *   <div key={ann.id} className={`announcement-${ann.announcementType}`}>
+ *     {ann.content}
+ *     {ann.isDismissible && (
+ *       <button onClick={() => dismiss(ann.id)}>Dismiss</button>
+ *     )}
+ *   </div>
+ * ))}
+ * ```
+ */
+export function useAnnouncements(options) {
+    const controllerRef = useRef(null);
+    const [state, setState] = useState({
+        announcements: [],
+        dismissed: new Set(),
+        status: "idle",
+        error: null,
+    });
+    useEffect(() => {
+        const config = resolveConfig(options);
+        const controller = new AnnouncementsController(config);
+        controllerRef.current = controller;
+        const unsubscribe = controller.subscribe(setState);
+        // Auto-fetch on mount (default: true)
+        if (options.autoFetch !== false) {
+            controller.fetch();
+        }
+        return unsubscribe;
+    }, [options.siteKey, options.endpoint]);
+    const dismiss = useCallback(async (announcementId) => {
+        await controllerRef.current?.dismiss(announcementId);
+    }, []);
+    const refresh = useCallback(async () => {
+        await controllerRef.current?.fetch();
+    }, []);
+    // Return only visible (non-dismissed) announcements
+    const visibleAnnouncements = controllerRef.current?.getVisibleAnnouncements() ?? [];
+    return { announcements: visibleAnnouncements, status: state.status, error: state.error, dismiss, refresh };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@jamwidgets/react",
+  "version": "0.1.0",
+  "description": "React hooks for Jamwidgets (forms, comments, reactions, subscriptions)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamwidgets/react.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://jamwidgets.com",
+  "author": "Tim Marks <tim@imothee.xyz>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "react",
+    "jamwidgets",
+    "forms",
+    "comments",
+    "reactions",
+    "subscribe",
+    "hooks"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@jamwidgets/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.0",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}