@abloatai/humans 0.62.0 → 0.63.1

package/src/react/usePresence.ts

@@ -0,0 +1,88 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { PresenceSession } from '@abloatai/transaction/presence';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import {
+  getModelClientMeta,
+  type ModelOperations,
+} from '../local/client/createModelOperations.js';
+import type { AbloClient as Ablo } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import { useAbloClientImpl } from './useAblo.js';
+
+type DefaultModels = ResolveSchema extends { models: infer M }
+  ? M extends SchemaRecord
+    ? M
+    : SchemaRecord
+  : SchemaRecord;
+
+export type PresenceModelSelector<R extends SchemaRecord, T, C> =
+  (ablo: Ablo<R>) => ModelOperations<T, C>;
+
+/**
+ * Declare that this component is reading one row and return every live session
+ * reading or otherwise acting on that row. Ablo owns the lease, refresh,
+ * reconnect, and cleanup mechanics for the component's lifetime.
+ */
+export function usePresence<T, C>(
+  modelClient: ModelOperations<T, C>,
+  recordId: string,
+): readonly PresenceSession[];
+export function usePresence<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  select: PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[];
+export function usePresence<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[] {
+  const engine = useAbloClientImpl<R>(null);
+  return usePresenceImpl(engine, modelOrSelect, recordId);
+}
+
+/** @internal Shared by the global hook and schema-bound React factory. */
+export function usePresenceImpl<R extends SchemaRecord, T, C>(
+  engine: Ablo<R> | null,
+  modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[] {
+  if (recordId.length === 0) {
+    throw new AbloValidationError(
+      'usePresence requires a non-empty record id.',
+      { code: 'invalid_request', param: 'recordId' },
+    );
+  }
+  const modelClient = typeof modelOrSelect === 'function'
+    ? engine
+      ? modelOrSelect(engine)
+      : null
+    : modelOrSelect;
+  const presence = modelClient ? getModelClientMeta(modelClient)?.presence : undefined;
+  if (modelClient !== null && presence === undefined) {
+    throw new AbloValidationError(
+      'usePresence requires a model from the reactive Ablo client.',
+      { code: 'invalid_request', param: 'modelClient' },
+    );
+  }
+
+  const [, render] = useState(0);
+
+  useEffect(
+    () => presence?.subscribe(() => { render((version) => version + 1); }),
+    [presence],
+  );
+
+  useEffect(() => presence?.read(recordId), [presence, recordId]);
+
+  return presence?.get(recordId) ?? [];
+}

package/src/react/useSyncStatus.ts

@@ -1,10 +1,12 @@
 'use client';
 
-import { useCallback } from 'react';
+import { useCallback, useContext } from 'react';
 import {
-  useSyncContext,
+  SyncContext,
   type SyncStoreContract,
 } from './context.js';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useReactive } from '../useReactive.js';
 
 export type SyncStatusSnapshot =
@@ -17,7 +19,16 @@ export type SyncStatusSnapshot =
 
 /** Reactively exposes the local store's connection and confirmation status. */
 export function useSyncStatus(): SyncStatusSnapshot {
-  const { store } = useSyncContext();
+  const provider = useContext(AbloInternalContext);
+  const sync = useContext(SyncContext);
+  // Status does not require authenticated row scope. The client exists before
+  // ready() resolves, including inside passthrough children and custom fallbacks.
+  const store = provider?.engine?._store ?? sync?.store;
+  if (!store) {
+    throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
+      code: 'sync_context_missing_provider',
+    });
+  }
   const compute = useCallback(() => deriveStatus(store), [store]);
   return useReactive(compute, sameSnapshot);
 }

package/src/react.ts

@@ -3,6 +3,10 @@ export { useReactive } from './useReactive.js';
 export { useCurrentUserId } from './react/useCurrentUserId.js';
 export { useErrorListener } from './react/useErrorListener.js';
 export { useSyncStatus, type SyncStatusSnapshot } from './react/useSyncStatus.js';
+export {
+  usePresence,
+  type PresenceModelSelector,
+} from './react/usePresence.js';
 export {
   useMutationFailureListener,
   type MutationFailurePayload,

package/src/surface.ts

@@ -38,6 +38,7 @@ export const PUBLIC_MODEL_VERBS = [
   'listAll',
   'local',
   'presence',
+  'events',
   'create',
   'update',
   'delete',

package/src/useReactive.ts

@@ -16,7 +16,6 @@ export function useReactive<T>(
   const computeRef = useRef(compute);
   const equalsRef = useRef(equals);
   const snapshotRef = useRef<{ value: T } | null>(null);
-  const versionRef = useRef(0);
 
   equalsRef.current = equals;
   if (snapshotRef.current === null) {
@@ -25,7 +24,6 @@ export function useReactive<T>(
     const next = compute();
     if (!equals(snapshotRef.current.value, next)) {
       snapshotRef.current = { value: next };
-      versionRef.current++;
     }
   }
   computeRef.current = compute;
@@ -39,7 +37,7 @@ export function useReactive<T>(
         onChange();
       }
     },
-  ), [versionRef.current]);
+  ), [compute]);
   const getSnapshot = useCallback(() => snapshotRef.current!.value, []);
   return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }