@queuezero/react 0.1.3

package/README.md

@@ -0,0 +1,214 @@
+# @queuezero/react
+
+React components and hooks for QueueZero viral waitlists.
+
+## Installation
+
+```bash
+npm install @queuezero/react
+```
+
+## Quick Start
+
+```tsx
+import { WaitlistProvider, WaitlistForm, WaitlistStatus, ReferralShare } from '@queuezero/react';
+
+function App() {
+  // Get referral code from URL if present
+  const referrerCode = new URLSearchParams(window.location.search).get('ref');
+
+  return (
+    <WaitlistProvider 
+      campaign="my-campaign"
+      config={{ apiUrl: 'https://api.queuezero.io' }}
+    >
+      <WaitlistForm 
+        referrerCode={referrerCode || undefined}
+        onSuccess={(res) => console.log('Joined at position:', res.position)}
+      />
+      <WaitlistStatus />
+      <ReferralShare showSocialButtons />
+    </WaitlistProvider>
+  );
+}
+```
+
+## Components
+
+### WaitlistProvider
+
+Wraps your app to provide waitlist context to all child components.
+
+```tsx
+<WaitlistProvider 
+  campaign="my-campaign"
+  config={{ 
+    apiUrl: 'https://api.queuezero.io',
+    baseUrl: 'https://myapp.com' 
+  }}
+>
+  {children}
+</WaitlistProvider>
+```
+
+### WaitlistForm
+
+A ready-to-use signup form.
+
+```tsx
+// Basic
+<WaitlistForm />
+
+// With options
+<WaitlistForm
+  referrerCode="ABC123"
+  metadata={{ role: 'Developer' }}
+  placeholder="Enter your work email"
+  buttonText="Get Early Access"
+  onSuccess={(response) => console.log(response)}
+  onError={(error) => console.error(error)}
+/>
+
+// Custom render
+<WaitlistForm>
+  {({ email, setEmail, submit, loading, error }) => (
+    <div>
+      <input value={email} onChange={(e) => setEmail(e.target.value)} />
+      <button onClick={submit}>{loading ? '...' : 'Join'}</button>
+    </div>
+  )}
+</WaitlistForm>
+```
+
+### WaitlistStatus
+
+Displays position, score, and referral count.
+
+```tsx
+// Basic
+<WaitlistStatus />
+
+// With options
+<WaitlistStatus
+  showScore
+  showReferrals
+  positionLabel="Your position:"
+/>
+
+// Custom render
+<WaitlistStatus>
+  {(status) => (
+    <div>
+      <h2>#{status.position}</h2>
+      <p>{status.priority_score} points</p>
+    </div>
+  )}
+</WaitlistStatus>
+```
+
+### ReferralShare
+
+Share referral link with copy and social buttons.
+
+```tsx
+// Basic
+<ReferralShare />
+
+// With social buttons
+<ReferralShare 
+  showSocialButtons 
+  shareMessage="Join me on this awesome waitlist!"
+/>
+
+// Custom render
+<ReferralShare>
+  {({ link, code, copy, copied }) => (
+    <div>
+      <code>{code}</code>
+      <button onClick={copy}>{copied ? 'Copied!' : 'Copy'}</button>
+    </div>
+  )}
+</ReferralShare>
+```
+
+## Hooks
+
+### useWaitlistContext
+
+Access waitlist state inside the provider.
+
+```tsx
+import { useWaitlistContext } from '@queuezero/react';
+
+function MyComponent() {
+  const { status, loading, join, getReferralLink } = useWaitlistContext();
+  
+  if (loading) return <div>Loading...</div>;
+  if (!status) return <button onClick={() => join('user@example.com')}>Join</button>;
+  
+  return (
+    <div>
+      <p>Position: #{status.position}</p>
+      <p>Share: {getReferralLink()}</p>
+    </div>
+  );
+}
+```
+
+### useWaitlist
+
+Standalone hook (without provider) for simpler use cases.
+
+```tsx
+import { useWaitlist } from '@queuezero/react';
+
+function WaitlistPage() {
+  const { status, join, loading, getReferralLink } = useWaitlist('my-campaign', {
+    apiUrl: 'https://api.queuezero.io',
+  });
+  
+  // ...
+}
+```
+
+## Styling
+
+Components use `qz-*` class names for easy styling:
+
+```css
+/* Form */
+.qz-form { }
+.qz-form-row { display: flex; gap: 8px; }
+.qz-form-input { flex: 1; padding: 12px; }
+.qz-form-button { padding: 12px 24px; }
+.qz-form-error { color: red; margin-top: 8px; }
+
+/* Status */
+.qz-status { display: flex; gap: 16px; }
+.qz-status-item { }
+.qz-status-label { font-size: 12px; color: #666; }
+.qz-status-value { font-size: 24px; font-weight: bold; }
+
+/* Share */
+.qz-share { }
+.qz-share-input { flex: 1; padding: 8px; }
+.qz-share-copy-button { padding: 8px 16px; }
+.qz-share-social { display: flex; gap: 8px; margin-top: 8px; }
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type { 
+  WaitlistProviderProps,
+  WaitlistFormProps,
+  UserStatus,
+  SubmitResponse 
+} from '@queuezero/react';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,283 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { QueueZeroConfig, UserStatus, UserMetadata, SubmitResponse, PublicCampaignConfig } from 'queuezero';
+export { BrandingConfig, FeatureFlags, FormField, InMemoryStorageAdapter, LeadStatus, LocalStorageAdapter, QueueZeroClient, QueueZeroConfig, SubmitResponse, UserMetadata, UserStatus } from 'queuezero';
+
+/**
+ * @queuezero/react - Types
+ *
+ * TypeScript type definitions for React components and hooks.
+ */
+
+/**
+ * Props for WaitlistProvider
+ */
+interface WaitlistProviderProps {
+    /** Campaign slug/identifier */
+    campaign: string;
+    /** API configuration */
+    config?: QueueZeroConfig;
+    /** Children components */
+    children: React.ReactNode;
+}
+/**
+ * Waitlist context value
+ */
+interface WaitlistContextValue {
+    /** Current loading state */
+    loading: boolean;
+    /** Current user status (if joined) */
+    status: UserStatus | null;
+    /** Last error (if any) */
+    error: Error | null;
+    /** Whether the user has joined */
+    isJoined: boolean;
+    /** Campaign slug */
+    campaign: string;
+    /** Join the waitlist */
+    join: (email: string, metadata?: UserMetadata, referrerCode?: string) => Promise<SubmitResponse | null>;
+    /** Refresh status */
+    refresh: () => Promise<UserStatus | null>;
+    /** Get referral link */
+    getReferralLink: () => string | null;
+    /** Get referral code */
+    getReferralCode: () => string | null;
+    /** Reset/logout */
+    reset: () => void;
+    /** Public configuration fetched from the API */
+    config: PublicConfig | null;
+    /** Whether the config is loading */
+    configLoading: boolean;
+}
+
+type PublicConfig = PublicCampaignConfig;
+/**
+ * Props for WaitlistForm component
+ */
+interface WaitlistFormProps {
+    /** Called on successful submission */
+    onSuccess?: (response: SubmitResponse) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Referral code (if from a referral link) */
+    referrerCode?: string;
+    /** Additional metadata to include */
+    metadata?: UserMetadata;
+    /** Custom class name */
+    className?: string;
+    /** Custom placeholder text */
+    placeholder?: string;
+    /** Custom button text */
+    buttonText?: string;
+    /** Custom loading text */
+    loadingText?: string;
+    /** Show labels */
+    showLabel?: boolean;
+    /** Label text */
+    labelText?: string;
+    /** Children for custom rendering */
+    children?: React.ReactNode;
+}
+/**
+ * Props for WaitlistStatus component
+ */
+interface WaitlistStatusProps {
+    /** Custom class name */
+    className?: string;
+    /** Show referral stats */
+    showReferrals?: boolean;
+    /** Show score */
+    showScore?: boolean;
+    /** Custom position label */
+    positionLabel?: string;
+    /** Custom score label */
+    scoreLabel?: string;
+    /** Custom referrals label */
+    referralsLabel?: string;
+    /** Children for custom rendering */
+    children?: (status: UserStatus) => React.ReactNode;
+}
+/**
+ * Props for ReferralShare component
+ */
+interface ReferralShareProps {
+    /** Custom class name */
+    className?: string;
+    /** Text to display before the link */
+    label?: string;
+    /** Button text for copy action */
+    copyButtonText?: string;
+    /** Text shown after copying */
+    copiedText?: string;
+    /** Called when link is copied */
+    onCopy?: (link: string) => void;
+    /** Custom message for sharing */
+    shareMessage?: string;
+    /** Show social share buttons */
+    showSocialButtons?: boolean;
+    /** Children for custom rendering */
+    children?: (props: {
+        link: string;
+        code: string;
+        copy: () => void;
+        copied: boolean;
+    }) => React.ReactNode;
+}
+
+/**
+ * WaitlistProvider - Provides waitlist functionality to all child components
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <WaitlistProvider campaign="my-campaign" config={{ apiUrl: 'https://api.example.com' }}>
+ *       <WaitlistForm />
+ *       <WaitlistStatus />
+ *     </WaitlistProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function WaitlistProvider({ campaign, config, children }: WaitlistProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * useWaitlistContext - Access the waitlist context
+ *
+ * @throws Error if used outside of WaitlistProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { status, join, loading } = useWaitlistContext();
+ *   // ...
+ * }
+ * ```
+ */
+declare function useWaitlistContext(): WaitlistContextValue;
+/**
+ * useWaitlist - Standalone hook (without provider)
+ *
+ * For simple use cases where you don't need to share state across components.
+ *
+ * @example
+ * ```tsx
+ * function WaitlistPage() {
+ *   const { status, join, loading } = useWaitlist('my-campaign');
+ *   // ...
+ * }
+ * ```
+ */
+declare function useWaitlist(campaign: string, config?: WaitlistProviderProps['config']): {
+    loading: boolean;
+    status: UserStatus | null;
+    error: Error | null;
+    isJoined: boolean;
+    campaign: string;
+    join: (email: string, metadata?: UserMetadata, referrerCode?: string) => Promise<SubmitResponse | null>;
+    refresh: () => Promise<UserStatus | null>;
+    getReferralLink: () => string | null;
+    getReferralCode: () => string | null;
+    reset: () => void;
+};
+
+/**
+ * @queuezero/react - WaitlistForm Component
+ *
+ * A pre-built form component for joining the waitlist.
+ */
+
+/**
+ * WaitlistForm - Ready-to-use form for waitlist signup
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <WaitlistForm onSuccess={(res) => console.log('Joined!', res)} />
+ *
+ * // With referral code from URL
+ * const referrerCode = new URLSearchParams(window.location.search).get('ref');
+ * <WaitlistForm referrerCode={referrerCode || undefined} />
+ *
+ * // With custom styling
+ * <WaitlistForm
+ *   className="my-form"
+ *   placeholder="Enter your work email"
+ *   buttonText="Get Early Access"
+ * />
+ *
+ * // With custom rendering
+ * <WaitlistForm>
+ *   {({ email, setEmail, submit, loading, error }) => (
+ *     <div>
+ *       <input value={email} onChange={(e) => setEmail(e.target.value)} />
+ *       <button onClick={submit} disabled={loading}>Join</button>
+ *       {error && <span>{error.message}</span>}
+ *     </div>
+ *   )}
+ * </WaitlistForm>
+ * ```
+ */
+declare function WaitlistForm({ onSuccess, onError, referrerCode, metadata, className, placeholder, buttonText, loadingText, showLabel, labelText, children, }: WaitlistFormProps): any;
+
+/**
+ * WaitlistStatus - Shows current position, score, and referral count
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <WaitlistStatus />
+ *
+ * // With custom labels
+ * <WaitlistStatus
+ *   positionLabel="You're #"
+ *   scoreLabel="Points:"
+ *   referralsLabel="Friends referred:"
+ * />
+ *
+ * // Hide certain stats
+ * <WaitlistStatus showScore={false} />
+ *
+ * // With custom rendering
+ * <WaitlistStatus>
+ *   {(status) => (
+ *     <div className="custom-status">
+ *       <h2>#{status.position}</h2>
+ *       <p>{status.priority_score} pts</p>
+ *     </div>
+ *   )}
+ * </WaitlistStatus>
+ * ```
+ */
+declare function WaitlistStatus({ className, showReferrals, showScore, positionLabel, scoreLabel, referralsLabel, children, }: WaitlistStatusProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * ReferralShare - Share referral link with copy and social buttons
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ReferralShare />
+ *
+ * // With custom text
+ * <ReferralShare
+ *   label="Share your link:"
+ *   copyButtonText="Copy Link"
+ *   copiedText="Copied!"
+ * />
+ *
+ * // With social sharing
+ * <ReferralShare showSocialButtons />
+ *
+ * // With custom rendering
+ * <ReferralShare>
+ *   {({ link, code, copy, copied }) => (
+ *     <div>
+ *       <code>{code}</code>
+ *       <button onClick={copy}>{copied ? '✓' : 'Copy'}</button>
+ *     </div>
+ *   )}
+ * </ReferralShare>
+ * ```
+ */
+declare function ReferralShare({ className, label, copyButtonText, copiedText, onCopy, shareMessage, showSocialButtons, children, }: ReferralShareProps): react_jsx_runtime.JSX.Element | null;
+
+export { type PublicConfig, ReferralShare, type ReferralShareProps, type WaitlistContextValue, WaitlistForm, type WaitlistFormProps, WaitlistProvider, type WaitlistProviderProps, WaitlistStatus, type WaitlistStatusProps, useWaitlist, useWaitlistContext };