@object-ui/collaboration 5.1.1 → 5.2.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @object-ui/collaboration
 
+## 5.2.1
+
+### Patch Changes
+
+- @object-ui/types@5.2.1
+
+## 5.2.0
+
+### Minor Changes
+
+- a4a0e1d: Add `<PresenceProvider>` abstraction with `useTenantPresence()` and
+  `useRecordPresence(objectName, recordId)` hooks. The default source is a
+  no-op so hooks return `[]` until a host app wires in a realtime
+  transport (WebSocket / SSE). Replaces the two architectural TODOs in
+  `AppHeader` (tenant scope) and `RecordDetailView` (record scope) that
+  were waiting on this abstraction.
+
+  `AppHeader` now falls back to `useTenantPresence()` when the
+  `presenceUsers` prop is omitted, and `RecordDetailView` renders
+  `<PresenceAvatars>` next to the lifecycle badge when other users are
+  viewing the same record. Both code paths render exactly as before when
+  no provider is mounted, so this change is non-visual for existing
+  consumers.
+
+### Patch Changes
+
+- Updated dependencies [de0c5e6]
+- Updated dependencies [9997cae]
+- Updated dependencies [70b5570]
+  - @object-ui/types@5.2.0
+
 ## 5.1.1
 
 ### Patch Changes

package/dist/PresenceProvider.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import * as React from 'react';
+import type { PresenceUser } from './usePresence';
+/**
+ * Scope key for record-level presence ("who else is viewing this record").
+ */
+export interface RecordPresenceScope {
+    objectName: string;
+    recordId: string;
+}
+/**
+ * Transport-agnostic source of presence updates. Implementations would
+ * typically be backed by a WebSocket / SSE channel; the platform ships a
+ * no-op default so consumers can read presence hooks unconditionally and
+ * simply render nothing until a real transport is wired in.
+ *
+ * Both `subscribeTenant` and `subscribeRecord` follow the same contract:
+ *
+ *   1. Push the *current* known user list to the callback synchronously
+ *      (or as soon as it's available).
+ *   2. Push subsequent updates as users join / leave / change status.
+ *   3. Return an unsubscribe function that the hook will invoke on unmount
+ *      or when the scope changes.
+ */
+export interface PresenceSource {
+    /** Tenant-wide "who else is online in this workspace". */
+    subscribeTenant?: (cb: (users: PresenceUser[]) => void) => () => void;
+    /** Record-scoped "who else is viewing this record". */
+    subscribeRecord?: (scope: RecordPresenceScope, cb: (users: PresenceUser[]) => void) => () => void;
+}
+export interface PresenceProviderProps {
+    /**
+     * Concrete presence source. When omitted, all presence hooks resolve to
+     * an empty user list — useful for development and for environments
+     * without a realtime transport yet.
+     */
+    source?: PresenceSource;
+    children: React.ReactNode;
+}
+/**
+ * Provides a presence source to descendants. Wrap the application shell
+ * once; nested components consume the source via `useTenantPresence()`
+ * or `useRecordPresence()`.
+ *
+ * The default value is a no-op source so unwrapped trees still render
+ * correctly — the hooks simply return `[]`.
+ */
+export declare function PresenceProvider({ source, children }: PresenceProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read tenant-wide presence ("who else is in this workspace right now").
+ * Returns an empty array when no `PresenceProvider` is mounted or the
+ * source doesn't implement `subscribeTenant`.
+ */
+export declare function useTenantPresence(): PresenceUser[];
+/**
+ * Read presence for a specific record ("who else is viewing this customer
+ * detail page"). Returns an empty array when no `PresenceProvider` is
+ * mounted, the source doesn't implement `subscribeRecord`, or the scope
+ * is incomplete.
+ */
+export declare function useRecordPresence(objectName: string | undefined, recordId: string | undefined): PresenceUser[];
+/**
+ * Internal-only test helper that exposes the raw context value. Not part
+ * of the stable API; do not import from outside the package.
+ *
+ * @internal
+ */
+export declare function __unsafe_usePresenceContext(): PresenceSource;
+//# sourceMappingURL=PresenceProvider.d.ts.map

package/dist/PresenceProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PresenceProvider.d.ts","sourceRoot":"","sources":["../src/PresenceProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACtE,uDAAuD;IACvD,eAAe,CAAC,EAAE,CAChB,KAAK,EAAE,mBAAmB,EAC1B,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,IAAI,KAChC,MAAM,IAAI,CAAC;CACjB;AAMD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,qBAAqB,2CAK3E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,EAAE,CAelD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,YAAY,EAAE,CAkBhB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,cAAc,CAE5D"}

package/dist/PresenceProvider.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import * as React from 'react';
+const NOOP_SOURCE = {};
+const PresenceContext = React.createContext(NOOP_SOURCE);
+/**
+ * Provides a presence source to descendants. Wrap the application shell
+ * once; nested components consume the source via `useTenantPresence()`
+ * or `useRecordPresence()`.
+ *
+ * The default value is a no-op source so unwrapped trees still render
+ * correctly — the hooks simply return `[]`.
+ */
+export function PresenceProvider({ source, children }) {
+    const value = source ?? NOOP_SOURCE;
+    return (_jsx(PresenceContext.Provider, { value: value, children: children }));
+}
+/**
+ * Read tenant-wide presence ("who else is in this workspace right now").
+ * Returns an empty array when no `PresenceProvider` is mounted or the
+ * source doesn't implement `subscribeTenant`.
+ */
+export function useTenantPresence() {
+    const source = React.useContext(PresenceContext);
+    const [users, setUsers] = React.useState([]);
+    React.useEffect(() => {
+        if (!source.subscribeTenant) {
+            setUsers([]);
+            return;
+        }
+        return source.subscribeTenant((next) => {
+            setUsers(Array.isArray(next) ? next : []);
+        });
+    }, [source]);
+    return users;
+}
+/**
+ * Read presence for a specific record ("who else is viewing this customer
+ * detail page"). Returns an empty array when no `PresenceProvider` is
+ * mounted, the source doesn't implement `subscribeRecord`, or the scope
+ * is incomplete.
+ */
+export function useRecordPresence(objectName, recordId) {
+    const source = React.useContext(PresenceContext);
+    const [users, setUsers] = React.useState([]);
+    React.useEffect(() => {
+        if (!source.subscribeRecord || !objectName || !recordId) {
+            setUsers([]);
+            return;
+        }
+        return source.subscribeRecord({ objectName, recordId }, (next) => {
+            setUsers(Array.isArray(next) ? next : []);
+        });
+    }, [source, objectName, recordId]);
+    return users;
+}
+/**
+ * Internal-only test helper that exposes the raw context value. Not part
+ * of the stable API; do not import from outside the package.
+ *
+ * @internal
+ */
+export function __unsafe_usePresenceContext() {
+    return React.useContext(PresenceContext);
+}

package/dist/index.d.ts

@@ -26,5 +26,6 @@ export { useMentionNotifications, type MentionNotificationsConfig, type MentionN
 export { useCommentSearch, type CommentSearchConfig, type CommentSearchReturn, } from './useCommentSearch';
 export { LiveCursors, type LiveCursorsProps, } from './LiveCursors';
 export { PresenceAvatars, type PresenceAvatarsProps, } from './PresenceAvatars';
+export { PresenceProvider, useTenantPresence, useRecordPresence, type PresenceSource, type PresenceProviderProps, type RecordPresenceScope, } from './PresenceProvider';
 export type { CollaborationPresence, CollaborationOperation, CollaborationConfig, } from '@object-ui/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,GAChC,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,GAChC,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -26,3 +26,4 @@ export { useMentionNotifications, } from './useMentionNotifications';
 export { useCommentSearch, } from './useCommentSearch';
 export { LiveCursors, } from './LiveCursors';
 export { PresenceAvatars, } from './PresenceAvatars';
+export { PresenceProvider, useTenantPresence, useRecordPresence, } from './PresenceProvider';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/collaboration",
-  "version": "5.1.1",
+  "version": "5.2.1",
   "type": "module",
   "license": "MIT",
   "description": "Real-time collaboration for Object UI with presence tracking, live cursors, conflict resolution, and comment threads.",
@@ -30,7 +30,7 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@object-ui/types": "5.1.1"
+    "@object-ui/types": "5.2.1"
   },
   "devDependencies": {
     "@types/react": "19.2.14",