@cloudsignal/collaborate 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,409 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, RefObject, MutableRefObject } from 'react';
+
+/** A user present in a collaborative space */
+interface SpaceUser {
+    userId: string;
+    name: string;
+    color: string;
+    avatar?: string;
+    data?: Record<string, unknown>;
+    joinedAt: number;
+    lastSeen: number;
+}
+/** How to connect to CloudSignal — supports credentials, token, or external IdP */
+interface SpaceConnectionConfig {
+    /** WebSocket URL (e.g. wss://connect.cloudsignal.app:18885/) */
+    host: string;
+    /** Direct credential auth */
+    username?: string;
+    password?: string;
+    /** Token-based auth */
+    organizationId?: string;
+    secretKey?: string;
+    /** External IdP token (Supabase, Clerk, etc.) */
+    externalToken?: string;
+    /** Token service URL for V2 auth */
+    tokenServiceUrl?: string;
+}
+interface SpaceProps {
+    /** Unique space identifier — used as MQTT topic namespace */
+    id: string;
+    /** Connection configuration */
+    connection: SpaceConnectionConfig;
+    /** Display name for the local user */
+    userName: string;
+    /** Hex color for the local user (auto-assigned if omitted) */
+    userColor?: string;
+    /** Optional avatar URL */
+    userAvatar?: string;
+    /** Arbitrary metadata attached to the user's presence */
+    userData?: Record<string, unknown>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Presence heartbeat interval in ms (default: 10000) */
+    presenceHeartbeatMs?: number;
+    /** Time before a user is considered offline in ms (default: 30000) */
+    presenceTimeoutMs?: number;
+    /** Connection status change callback */
+    onConnectionChange?: (connected: boolean) => void;
+    children: ReactNode;
+}
+type TopicHandler = (subtopic: string, payload: unknown) => void;
+interface SpaceContextValue {
+    spaceId: string;
+    self: SpaceUser;
+    isConnected: boolean;
+    isConnecting: boolean;
+    error: Error | null;
+    /** Time before a user is considered offline in ms */
+    presenceTimeoutMs: number;
+    /** Publish a message to a space topic (automatically prefixed) */
+    publish: (subtopic: string, payload: unknown, options?: PublishOptions) => void;
+    /** Register a handler for a topic segment — returns unsubscribe function */
+    addTopicHandler: (segment: string, handler: TopicHandler) => () => void;
+}
+interface PublishOptions {
+    qos?: 0 | 1 | 2;
+    retain?: boolean;
+}
+interface CursorData {
+    userId: string;
+    name: string;
+    x: number;
+    y: number;
+    color: string;
+    ts: number;
+    lastSeen: number;
+}
+interface UseCursorsOptions {
+    /** Throttle publish rate in ms (default: 30 → ~33Hz) */
+    throttleMs?: number;
+    /** Time before a cursor fades out in ms (default: 3000) */
+    staleMs?: number;
+}
+interface UseCursorsReturn {
+    /** Ref-based cursor map for imperative rendering (no re-renders) */
+    cursorsRef: RefObject<Map<string, CursorData>>;
+    /** Callback ref — set by CursorOverlay to sync DOM on each message */
+    onUpdateRef: MutableRefObject<(() => void) | null>;
+    /** State snapshot of cursors, updated at 1Hz for display purposes */
+    cursors: CursorData[];
+    /** Publish the local user's cursor position (normalized 0–1) */
+    publishCursor: (x: number, y: number) => void;
+}
+interface UsePresenceReturn {
+    /** All users currently in the space (including self) */
+    members: SpaceUser[];
+    /** Number of members */
+    count: number;
+    /** The local user */
+    self: SpaceUser;
+    /** Register a callback for when a user joins */
+    onJoin: (callback: (user: SpaceUser) => void) => () => void;
+    /** Register a callback for when a user leaves */
+    onLeave: (callback: (user: SpaceUser) => void) => () => void;
+}
+interface UseLockReturn {
+    /** Whether this component is currently locked */
+    isLocked: boolean;
+    /** The user who holds the lock (null if unlocked) */
+    lockedBy: SpaceUser | null;
+    /** Whether the local user holds the lock */
+    isLockedByMe: boolean;
+    /** Acquire the lock */
+    lock: () => void;
+    /** Release the lock */
+    unlock: () => void;
+}
+interface UseTypingIndicatorReturn {
+    /** Users currently typing */
+    typingUsers: SpaceUser[];
+    /** Signal that the local user started typing */
+    startTyping: () => void;
+    /** Signal that the local user stopped typing */
+    stopTyping: () => void;
+    /** Whether the local user is currently marked as typing */
+    isTyping: boolean;
+}
+interface Reaction {
+    id: string;
+    userId: string;
+    name: string;
+    emoji: string;
+    color: string;
+    ts: number;
+    /** Horizontal position for float animation (0–100), assigned on creation */
+    x?: number;
+}
+interface UseReactionsOptions {
+    /** Max visible reactions at once (default: 20) */
+    maxVisible?: number;
+    /** How long a reaction stays visible in ms (default: 3000) */
+    durationMs?: number;
+}
+interface UseReactionsReturn {
+    /** Currently visible reactions */
+    reactions: Reaction[];
+    /** Send an emoji reaction */
+    sendReaction: (emoji: string) => void;
+}
+interface UseBroadcastReturn<T = unknown> {
+    /** Send a broadcast message */
+    broadcast: (data: T) => void;
+    /** Last received message */
+    lastMessage: T | null;
+    /** Register a callback for incoming broadcasts */
+    onMessage: (callback: (data: T) => void) => () => void;
+}
+type UseSharedStateReturn<T> = [
+    /** Current value */
+    T,
+    /** Update the value (last-write-wins across clients) */
+    (value: T) => void
+];
+interface AvatarStackProps {
+    /** Max avatars before showing "+N" (default: 5) */
+    max?: number;
+    /** Avatar size in pixels (default: 32) */
+    size?: number;
+    className?: string;
+}
+interface CursorOverlayProps {
+    /** Throttle publish rate in ms (default: 30) */
+    throttleMs?: number;
+    /** Cursor stale timeout in ms (default: 3000) */
+    staleMs?: number;
+    className?: string;
+    children?: ReactNode;
+}
+interface TypingIndicatorProps {
+    /** Optional input ID to scope typing to */
+    inputId?: string;
+    className?: string;
+}
+interface LockIndicatorProps {
+    /** ID of the component being locked */
+    componentId: string;
+    className?: string;
+    children?: ReactNode;
+}
+interface ReactionBarProps {
+    /** Emoji options to show (default: common set) */
+    emojis?: string[];
+    className?: string;
+}
+interface PresenceBorderProps {
+    /** Component ID for lock tracking */
+    componentId: string;
+    /** Border width in pixels (default: 2) */
+    borderWidth?: number;
+    className?: string;
+    children?: ReactNode;
+}
+
+declare function Space({ id, connection, userName, userColor, userAvatar, userData, debug, presenceHeartbeatMs, presenceTimeoutMs, onConnectionChange, children, }: SpaceProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the current Space context.
+ * Must be used within a `<Space>` provider.
+ */
+declare function useSpace(): SpaceContextValue;
+
+/**
+ * Track who's in the space.
+ * Presence heartbeats are managed by the Space provider —
+ * this hook only reads and exposes the member list.
+ */
+declare function usePresence(): UsePresenceReturn;
+
+/**
+ * Live cursor tracking.
+ *
+ * Performance: Cursor data is stored in refs (not state) to avoid
+ * re-renders on every MQTT message (~33 messages/sec per user).
+ * The `onUpdateRef` callback lets CursorOverlay sync DOM imperatively.
+ * A 1Hz state snapshot is provided for non-critical display (e.g. online count).
+ */
+declare function useCursors(options?: UseCursorsOptions): UseCursorsReturn;
+
+/**
+ * Component locking — "I'm editing this."
+ *
+ * Only one user can hold a lock at a time.
+ * Automatically unlocks when the component unmounts.
+ */
+declare function useLock(componentId: string): UseLockReturn;
+
+/**
+ * Typing indicator — "Alice is typing..."
+ *
+ * Auto-resets after 3s of inactivity. Throttled to max 1 publish per 2s.
+ * Users not seen typing in 4s are cleaned from the list.
+ */
+declare function useTypingIndicator(inputId?: string): UseTypingIndicatorReturn;
+
+/**
+ * Emoji reactions — floating emojis that auto-expire.
+ */
+declare function useReactions(options?: UseReactionsOptions): UseReactionsReturn;
+
+/**
+ * Generic pub/sub for custom events.
+ *
+ * If `event` is provided, scopes to that event name.
+ * Otherwise, receives all broadcast messages.
+ *
+ * @example
+ * // Scoped to "chat" events
+ * const { broadcast, onMessage } = useBroadcast<ChatMessage>('chat')
+ * broadcast({ text: 'Hello!' })
+ *
+ * @example
+ * // All broadcast events
+ * const { onMessage } = useBroadcast()
+ */
+declare function useBroadcast<T = unknown>(event?: string): UseBroadcastReturn<T>;
+
+/**
+ * Synced key-value state across all users in the space.
+ *
+ * Uses Last-Write-Wins (LWW) merge — the update with the newest
+ * timestamp wins. Retained messages ensure new joiners get current state.
+ *
+ * @example
+ * const [count, setCount] = useSharedState('counter', 0)
+ * <button onClick={() => setCount(count + 1)}>Count: {count}</button>
+ */
+declare function useSharedState<T>(key: string, initialValue: T): UseSharedStateReturn<T>;
+
+/**
+ * Shows who's online — overlapping avatars with a "+N" overflow badge.
+ *
+ * @example
+ * <AvatarStack max={4} size={36} className="absolute top-4 right-4" />
+ */
+declare function AvatarStack({ max, size, className }: AvatarStackProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Drop-in cursor overlay — wraps children and renders live cursors.
+ *
+ * Mouse tracking and cursor rendering are handled automatically.
+ * Uses imperative DOM manipulation for sub-frame performance.
+ *
+ * @example
+ * <CursorOverlay>
+ *   <div style={{ width: '100%', height: '400px' }}>
+ *     Your collaborative content here
+ *   </div>
+ * </CursorOverlay>
+ */
+declare function CursorOverlay({ throttleMs, staleMs, className, children, }: CursorOverlayProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Displays who's currently typing.
+ *
+ * Renders nothing if nobody is typing.
+ * Automatically formats: "Alice is typing...", "Alice and Bob are typing...",
+ * "3 people are typing..."
+ *
+ * @example
+ * <TypingIndicator className="text-sm text-gray-500 h-5" />
+ */
+declare function TypingIndicator({ inputId, className }: TypingIndicatorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shows lock status for a component and renders a colored border
+ * when locked by another user.
+ *
+ * @example
+ * <LockIndicator componentId="title-field">
+ *   <input
+ *     onFocus={() => lock()}
+ *     onBlur={() => unlock()}
+ *     disabled={isLocked && !isLockedByMe}
+ *   />
+ * </LockIndicator>
+ *
+ * Or use the hook directly for more control:
+ * const { isLocked, lockedBy, lock, unlock } = useLock('title-field')
+ */
+declare function LockIndicator({ componentId, className, children }: LockIndicatorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Emoji reaction bar with floating animations.
+ *
+ * Renders a row of emoji buttons + floating reactions from all users.
+ *
+ * @example
+ * <ReactionBar emojis={['👍', '❤️', '🎉']} className="fixed bottom-4 right-4" />
+ */
+declare function ReactionBar({ emojis, className }: ReactionBarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Wraps a component with a colored border showing who's focused on it.
+ * Automatically locks/unlocks on focus/blur of child interactive elements.
+ *
+ * @example
+ * <PresenceBorder componentId="description-field">
+ *   <textarea placeholder="Description..." />
+ * </PresenceBorder>
+ */
+declare function PresenceBorder({ componentId, borderWidth, className, children, }: PresenceBorderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Deterministic color assignment based on userId.
+ * Same user always gets the same color across sessions.
+ */
+declare function getColorForUser(userId: string): string;
+/**
+ * Get user initials from display name (for avatars).
+ * "Alice Smith" → "AS", "bob" → "B"
+ */
+declare function getInitials(name: string): string;
+
+/** MQTT topic prefix for all space collaboration messages */
+declare const TOPIC_PREFIX = "$spaces";
+/** Topic segments for each collaboration primitive */
+declare const TOPICS: {
+    readonly PRESENCE: "presence";
+    readonly CURSORS: "cursors";
+    readonly LOCKS: "locks";
+    readonly TYPING: "typing";
+    readonly REACTIONS: "reactions";
+    readonly BROADCAST: "broadcast";
+    readonly STATE: "state";
+};
+/** Default timing constants */
+declare const DEFAULTS: {
+    /** Presence heartbeat interval (ms) */
+    readonly PRESENCE_HEARTBEAT_MS: 10000;
+    /** Time before a user is considered offline (ms) */
+    readonly PRESENCE_TIMEOUT_MS: 30000;
+    /** Cursor publish throttle (ms) — ~33Hz */
+    readonly CURSOR_THROTTLE_MS: 30;
+    /** Time before a cursor fades out (ms) */
+    readonly CURSOR_STALE_MS: 3000;
+    /** Typing indicator auto-reset (ms) */
+    readonly TYPING_TIMEOUT_MS: 3000;
+    /** Minimum interval between typing publishes (ms) */
+    readonly TYPING_THROTTLE_MS: 2000;
+    /** Time before a typing user is cleaned from the list (ms) */
+    readonly TYPING_STALE_MS: 4000;
+    /** How long a reaction stays visible (ms) */
+    readonly REACTION_DURATION_MS: 3000;
+    /** Max visible reactions at once */
+    readonly REACTION_MAX_VISIBLE: 20;
+    /** Stats sync interval (ms) — for cursor count etc. */
+    readonly STATS_TICK_MS: 1000;
+    /** Opacity fade-out sync interval (ms) */
+    readonly FADE_TICK_MS: 200;
+};
+/** Build a full MQTT topic for a space */
+declare function spaceTopic(spaceId: string, segment: string): string;
+/** Build the wildcard subscription for a space */
+declare function spaceWildcard(spaceId: string): string;
+
+declare const VERSION = "0.1.0";
+
+export { AvatarStack, type AvatarStackProps, Space as CloudSignalSpace, type CursorData, CursorOverlay, type CursorOverlayProps, DEFAULTS, LockIndicator, type LockIndicatorProps, PresenceBorder, type PresenceBorderProps, type PublishOptions, type Reaction, ReactionBar, type ReactionBarProps, Space, type SpaceConnectionConfig, type SpaceContextValue, type SpaceProps, type SpaceUser, TOPICS, TOPIC_PREFIX, TypingIndicator, type TypingIndicatorProps, type UseBroadcastReturn, type UseCursorsOptions, type UseCursorsReturn, type UseLockReturn, type UsePresenceReturn, type UseReactionsOptions, type UseReactionsReturn, type UseSharedStateReturn, type UseTypingIndicatorReturn, VERSION, getColorForUser, getInitials, spaceTopic, spaceWildcard, useBroadcast, useCursors, useLock, usePresence, useReactions, useSharedState, useSpace, useTypingIndicator };