@yorkie-js/react 0.7.8 → 0.7.10-rc

package/dist/yorkie-js-react.d.ts

@@ -63,6 +63,11 @@ declare type ChannelProviderProps = PropsWithChildren<{
      * falls back to `SyncMode.Realtime`.
      */
     isRealtime?: boolean;
+    /**
+     * `channelHeartbeatInterval` overrides the heartbeat interval (ms).
+     * Applied at attach time. Defaults: Polling=3000, Realtime=30000.
+     */
+    channelHeartbeatInterval?: number;
 }>;
 
 export { Counter }
@@ -93,11 +98,21 @@ declare type DocumentContextType<R, P extends Indexable = Indexable> = {
  * This component must be under a `YorkieProvider` component to initialize the
  * Yorkie client properly.
  */
-export declare const DocumentProvider: <R, P extends Indexable = Indexable>({ docKey, initialRoot, initialPresence, enableDevtools, children, }: {
+export declare const DocumentProvider: <R, P extends Indexable = Indexable>({ docKey, initialRoot, initialPresence, enableDevtools, syncMode, documentPollInterval, children, }: {
     docKey: string;
     initialRoot?: R;
     initialPresence?: P;
     enableDevtools?: boolean;
+    /**
+     * `syncMode` defines the synchronization mode of the document.
+     * Defaults to `SyncMode.Realtime`.
+     */
+    syncMode?: SyncMode;
+    /**
+     * `documentPollInterval` (ms) — only used when `syncMode` is `Polling`.
+     * Default: 3000. Applied at attach time.
+     */
+    documentPollInterval?: number;
     children?: default_2.ReactNode;
 }) => JSX.Element;
 
@@ -122,7 +137,8 @@ export { Tree }
  * `useChannel` is a custom hook that returns the channel state.
  * It must be used within a ChannelProvider.
  *
- * @returns An object containing sessionCount, loading, and error state
+ * @returns An object containing sessionCount, loading, error state and
+ *          a `detach` function for permanently stopping the channel.
  *
  * @example
  * ```tsx
@@ -140,6 +156,7 @@ export declare const useChannel: () => {
     sessionCount: number;
     loading: boolean;
     error: Error | undefined;
+    detach: () => Promise<void>;
 };
 
 /**
@@ -171,6 +188,92 @@ export declare const useConnection: () => StreamConnectionStatus;
  */
 export declare function useDocument<R, P extends Indexable = Indexable>(): DocumentContextType<R, P>;
 
+/**
+ * `usePeekChannel` reads a channel's current session count without joining
+ * the channel. By default it fetches once on mount; pass `pollInterval` to
+ * opt into continuous polling. The caller does not create a Session on the
+ * server, does not receive broadcasts, and does not contribute to the
+ * channel's count.
+ *
+ * Prefer this over `<ChannelProvider readOnly>` when many viewers need to
+ * display a count and only a few become real participants — e.g. a global
+ * "N people writing" badge shown on every surrounding page.
+ *
+ * @example One-shot (snapshot at entry)
+ * ```tsx
+ * function WritersBadge() {
+ *   const { sessionCount, loading } = usePeekChannel('post-writers');
+ *   if (loading) return null;
+ *   return <span>{sessionCount} writing</span>;
+ * }
+ * ```
+ *
+ * @example Continuous polling
+ * ```tsx
+ * function LiveCounter() {
+ *   const { sessionCount } = usePeekChannel('post-writers', {
+ *     pollInterval: 3000,
+ *   });
+ *   return <span>{sessionCount} writing</span>;
+ * }
+ * ```
+ *
+ * @example Imperative refetch
+ * ```tsx
+ * function WithRefresh() {
+ *   const { sessionCount, refetch } = usePeekChannel('post-writers');
+ *   return (
+ *     <button onClick={() => refetch()}>{sessionCount} (refresh)</button>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePeekChannel(channelKey: string, opts?: UsePeekChannelOptions): UsePeekChannelResult;
+
+/**
+ * `UsePeekChannelOptions` are user-settable options for `usePeekChannel`.
+ */
+export declare interface UsePeekChannelOptions {
+    /**
+     * `pollInterval` opts the hook into continuous polling at the given
+     * cadence (ms). When unset, the hook fetches once on mount and stops —
+     * this matches the common "snapshot at entry" pattern. Use polling only
+     * when the UI genuinely needs a live-updating count.
+     */
+    pollInterval?: number;
+    /**
+     * `enabled` toggles execution. When false, the hook does not fetch and
+     * holds the last value. Default: true.
+     */
+    enabled?: boolean;
+}
+
+/**
+ * `UsePeekChannelResult` is the state exposed by `usePeekChannel`.
+ */
+export declare interface UsePeekChannelResult {
+    /**
+     * `sessionCount` is the most recently fetched count. Starts at 0 before
+     * the first successful fetch; gate display on `loading` if 0-vs-unfetched
+     * matters in your UI.
+     */
+    sessionCount: number;
+    /**
+     * `loading` is true before the first successful fetch (or while a
+     * `refetch()` is in flight). Becomes false on success or error.
+     */
+    loading: boolean;
+    /**
+     * `error` holds the last error from a fetch, if any.
+     */
+    error?: Error;
+    /**
+     * `refetch` issues a peek immediately, ignoring `pollInterval`. Useful on
+     * button clicks or after user actions that may have changed the count.
+     */
+    refetch: () => Promise<void>;
+}
+
 /**
  * `usePresences` is a custom hook that returns the presences of the document.
  */
@@ -212,6 +315,8 @@ export declare function useYorkieDoc<R, P extends Indexable = Indexable>(apiKey:
     initialRoot?: R;
     initialPresence?: P;
     enableDevtools?: boolean;
+    syncMode?: SyncMode;
+    documentPollInterval?: number;
 }): {
     root: R;
     presences: Array<{
@@ -228,6 +333,21 @@ export declare function useYorkieDoc<R, P extends Indexable = Indexable>(apiKey:
  * `YorkieProvider` is a component that provides the Yorkie client to its children.
  * It initializes the Yorkie client with the given API key and RPC address.
  */
-export declare const YorkieProvider: React.FC<PropsWithChildren<ClientOptions>>;
+export declare const YorkieProvider: React.FC<PropsWithChildren<YorkieProviderProps>>;
+
+/**
+ * `YorkieProviderProps` extends `ClientOptions` with provider-level options.
+ *
+ * - `activate` (default `true`): whether to call `client.activate()` on mount
+ *   and `client.deactivate()` on unmount. Set to `false` for apps that only
+ *   use Channels — under the RefreshChannel-only lifecycle the SDK
+ *   lazy-attaches the client on the first heartbeat, so explicit activate
+ *   round trips become unnecessary. Document use cases (`useDocument`,
+ *   `useYorkieDoc`) still require activation, so leave this `true` if any
+ *   descendant attaches a document.
+ */
+declare type YorkieProviderProps = ClientOptions & {
+    activate?: boolean;
+};
 
 export { }