@nivaro/react 0.1.89 → 0.1.91

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CascadeFilterRule } from '@nivaro/sdk';
+import { Context } from 'react';
 import { default as default_2 } from 'react';
 import { FieldDependencyConfig } from '@nivaro/sdk';
 import { ImportParseResponse } from '@nivaro/sdk';
@@ -617,6 +618,20 @@ export declare function CollectionImportPanel({ initialJobId, onJobOpen }: {
     onJobOpen?: (id: string | null) => void;
 }): JSX.Element;
 
+/**
+ * Realtime sprint client contract. A HOST (admin, efp-new) owns the actual
+ * Socket.io connection and provides this to shared components; components
+ * that render without it degrade to polling exactly as before — the context
+ * is always optional.
+ */
+export declare interface CollectionUpdateEvent {
+    collection: string;
+    item: string | number;
+    action?: 'create' | 'update' | 'delete';
+    changed_fields?: string[];
+    _seq?: number;
+}
+
 export declare interface Column<T = Record<string, unknown>> {
     key: string;
     header: React_2.ReactNode;
@@ -681,6 +696,8 @@ export declare function ConformanceView({ className }: {
     className?: string;
 }): JSX.Element;
 
+export declare function createLeaderSocket(key: string, cbs: LeaderCallbacks): LeaderSocketHandle;
+
 export declare function DataTable<T = Record<string, unknown>>({ columns, rows, rowKey, total, page, limit, isLoading, isError, errorMessage, sort, onSortChange, onPageChange, onRowClick, onRowContextMenu, searchValue, onSearchChange, searchPlaceholder, filterDefs, filterValues, onFilterChange, toolbarRight, emptyMessage, minBodyHeight, fillHeight, hideFilterRow, nowrapCells, density, pinFirstColumn, columnPins, onColumnPinChange, columnFilterRow, hScrollProxy, selectedIds, onSelectionChange, rowClassName, rowGroups, collapsedGroups, onToggleGroup }: DataTableProps<T>): React_2.JSX.Element;
 
 export declare interface DataTableProps<T = Record<string, unknown>> {
@@ -1608,11 +1625,13 @@ export declare type ItemLinkTarget = {
     layoutSlug?: string | null;
 };
 
-export declare function ItemLockBanner({ lockHolder, onTakeOver, takingOver, isAdmin }: {
+export declare function ItemLockBanner({ lockHolder, onTakeOver, takingOver, isAdmin, onRequestLock, requesting }: {
     lockHolder: LockHolder | null;
     onTakeOver: () => void;
     takingOver: boolean;
     isAdmin?: boolean;
+    onRequestLock?: () => void;
+    requesting?: boolean;
 }): JSX.Element | null;
 
 export declare function JsonMapEditor({ config, scope }: {
@@ -1749,6 +1768,35 @@ declare interface LayoutGroup {
 
 export declare type LayoutItem = FormGroupDescriptor | '__ungrouped__';
 
+declare interface LeaderCallbacks {
+    /** Called when this tab becomes leader — create the real socket, wire onAny → deliver. */
+    becomeLeader(deliver: (event: string, payload: any) => void, emit: {
+        current: (event: string, payload: any) => void;
+    }): void;
+    /** Called when this tab loses/abdicates leadership — tear the socket down. */
+    resignLeader(): void;
+}
+
+/**
+ * Tab leader election (#277): with many tabs open, only ONE holds the real
+ * Socket.io connection; the rest ride a BroadcastChannel. Halves server socket
+ * load and keeps events consistent across tabs.
+ *
+ * Election: localStorage heartbeat lock (`nvr-sock-leader:<key>` = "id:ts").
+ * The leader refreshes its claim every 2s; followers watch for staleness
+ * (>6s) and race to claim it. BroadcastChannel carries events leader→followers
+ * and emit requests follower→leader. No BroadcastChannel (old browser,
+ * cross-origin iframe) → every tab is its own leader, the historic behaviour.
+ */
+export declare interface LeaderSocketHandle {
+    isLeader(): boolean;
+    /** Fires on every inbound socket event (leader: direct; follower: relayed). */
+    onEvent(cb: (event: string, payload: any) => void): () => void;
+    /** Emit toward the server (follower forwards to the leader). */
+    emit(event: string, payload?: any): void;
+    destroy(): void;
+}
+
 declare interface LockHolder {
     locked_by: string;
     locked_by_name: string | null;
@@ -2541,6 +2589,17 @@ export declare interface ReadViewLayout {
     assignments: LayoutAssignment[];
 }
 
+export declare interface RealtimeAdapter {
+    /** Subscribe to collection:update for the named collections. Returns unsubscribe. */
+    subscribeCollections(collections: string[], cb: (ev: CollectionUpdateEvent) => void): () => void;
+    /** Listen to an arbitrary socket event (lock:requested, record:uploading…). */
+    on(event: string, cb: (payload: any) => void): () => void;
+    /** Emit an event to the server (record:uploading, record:join…). */
+    emit(event: string, payload?: any): void;
+}
+
+export declare const RealtimeContext: Context<RealtimeAdapter | null>;
+
 export declare function RecordChatActions({ collection, itemDraft }: {
     collection: string;
     itemDraft: Record<string, unknown>;
@@ -3147,6 +3206,8 @@ export declare function useItemLock(collection: string | undefined, item: string
     takeOver: () => Promise<void>;
     takingOver: boolean;
     isAdmin: boolean;
+    requestLock: () => Promise<void>;
+    requesting: boolean;
 };
 
 /** Resolved item-link helpers honoring the host's itemUrl/openItem overrides. */
@@ -3237,8 +3298,17 @@ export declare type UseNivaroFormReturn = {
     gridFlushersRef: default_2.MutableRefObject<Map<string, () => Promise<void>>>;
 };
 
+/**
+ * Online-user set for presence dots in user pickers (#284). One shared
+ * 30s-polled query per app (react-query dedupes); consumers get a Set of
+ * user ids. Fails to an empty set — a picker must never break on presence.
+ */
+export declare function useOnlineUsers(enabled?: boolean): Set<string>;
+
 export declare function useOptionalNivaroClient(): NivaroClient | null;
 
+export declare function useOptionalRealtime(): RealtimeAdapter | null;
+
 export declare function useOrderedLayout(form: UseNivaroFormReturn): {
     items: LayoutItem[];
     hasTabs: boolean;