@yorkie-js/react 0.7.7 → 0.7.9

package/README.md

@@ -8,7 +8,7 @@ To get started using Yorkie React SDK, see: https://yorkie.dev/docs/getting-star
 
 ## Contributing
 
-See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
+See [CONTRIBUTING](../../CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
 
 ## Contributors ✨
 

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

@@ -10,6 +10,7 @@ import { Presence } from '@yorkie-js/sdk';
 import { PropsWithChildren } from 'react';
 import { RevisionSummary } from '@yorkie-js/sdk';
 import { StreamConnectionStatus } from '@yorkie-js/sdk';
+import { SyncMode } from '@yorkie-js/sdk';
 import { Text as Text_2 } from '@yorkie-js/sdk';
 import { Tree } from '@yorkie-js/sdk';
 
@@ -19,12 +20,17 @@ import { Tree } from '@yorkie-js/sdk';
  *
  * @example
  * ```tsx
+ * import { ChannelProvider, SyncMode } from '@yorkie-js/react';
+ *
  * <YorkieProvider apiKey="..." rpcAddr="...">
- *   <ChannelProvider channelKey="room-123" isRealtime={true}>
+ *   <ChannelProvider channelKey="room-123" syncMode={SyncMode.Realtime}>
  *     <ChatRoom />
  *   </ChannelProvider>
  * </YorkieProvider>
  * ```
+ *
+ * The boolean `isRealtime` prop is also accepted as a shortcut for
+ * the Realtime/Manual choice (`true` → Realtime, `false` → Manual).
  */
 export declare const ChannelProvider: React.FC<ChannelProviderProps>;
 
@@ -37,12 +43,31 @@ declare type ChannelProviderProps = PropsWithChildren<{
      */
     channelKey: string;
     /**
-     * `isRealtime` determines the synchronization mode.
-     * - true: Realtime mode (automatic updates via watch stream)
-     * - false: Manual mode (requires manual sync)
-     * @default true
+     * `syncMode` selects how the channel keeps presence in sync with the server.
+     * - `SyncMode.Realtime` (default): open a watch stream and run the
+     *   heartbeat. Required to receive broadcast events.
+     * - `SyncMode.Polling`: heartbeat-only. No watch stream is opened.
+     *   Recommended for large channels where broadcast is not needed.
+     * - `SyncMode.Manual`: no automatic activity.
+     *
+     * If `isRealtime` is also set, `syncMode` wins.
+     */
+    syncMode?: SyncMode;
+    /**
+     * `isRealtime` is a convenience prop covering only Realtime/Manual.
+     * - `true`: equivalent to `syncMode={SyncMode.Realtime}`.
+     * - `false`: equivalent to `syncMode={SyncMode.Manual}`.
+     *
+     * Use `syncMode` directly when you want `SyncMode.Polling`, which this
+     * boolean prop cannot express. When neither prop is set, the channel
+     * 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 }
@@ -73,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;
 
@@ -92,6 +127,8 @@ export { RevisionSummary }
  */
 export declare function shallowEqual<T>(valueA: T, valueB: T): boolean;
 
+export { SyncMode }
+
 export { Text_2 as Text }
 
 export { Tree }
@@ -149,6 +186,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.
  */
@@ -190,6 +313,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<{