@abloatai/humans 0.63.1 → 0.64.0

package/src/react.ts

@@ -1,69 +1,7 @@
-/** React bindings for the optional human-facing local-state package. */
-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,
-} from './react/useMutationFailureListener.js';
-
-export {
-  AbloProvider,
-  usePeers,
-  useSync,
-  useSyncStore,
-  type AbloProviderProps,
-  type GroupScope,
-} from './react/AbloProvider.js';
-
-export {
-  ClientSideSuspense,
-  type ClientSideSuspenseProps,
-} from './react/ClientSideSuspense.js';
-
-export { DefaultFallback } from './react/DefaultFallback.js';
-
-export {
-  createAbloReact,
-  type AbloReactBinding,
-} from './react/createAbloReact.js';
-
-export {
-  useAblo,
-  type UseAbloHydratedModelResult,
-  type UseAbloModelOptions,
-  type UseAbloModelResult,
-} from './react/useAblo.js';
-
-export {
-  useMutators,
-  type InvokerFor,
-  type MutatorInvokers,
-  type UseMutatorsOptions,
-} from './react/useMutators.js';
-
-export {
-  useUndoScope,
-  type UseUndoScopeResult,
-} from './react/useUndoScope.js';
-
-export type {
-  DefaultSyncShape,
-  ResolveSchema,
-  ResolveUserMeta,
-  ResolveClaimMeta,
-  ResolveModelKey,
-} from '@abloatai/transaction/types/global';
-
-export { ModelScope } from '@abloatai/transaction/types';
-export type { SyncStoreContract } from './react/context.js';
-export type { MutateActions } from './local/mutators/mutateActions.js';
-export type {
-  ReaderActions,
-  ReaderFindOptions,
-} from './local/mutators/readerActions.js';
+/** React owns context, subscriptions and component lifetimes over core Ablo. */
+export { AbloProvider } from './react/AbloProvider.js';
+export { createAbloReact } from './react/createAbloReact.js';
+export { useAblo } from './react/useAblo.js';
+export { usePresence } from './react/usePresence.js';
+export { useMutators } from './react/useMutators.js';
+export { useUndoScope } from './react/useUndoScope.js';

package/dist/react/ClientSideSuspense.d.ts

@@ -1,36 +0,0 @@
-import { type ReactNode } from 'react';
-/**
- * Nested bootstrap gate for a subtree. `<AbloProvider>` already ships
- * its own built-in gate (via its `fallback` prop) that handles the
- * common "wait for first bootstrap" case. Use `ClientSideSuspense`
- * only when you need a SEPARATE gate inside an already-ready provider —
- * for example, rendering app chrome immediately while gating a single
- * heavy product surface on its own query resolving.
- *
- * Like the provider-level gate, this component latches open on the
- * first `connected` / `reconnecting` / `disconnected` transition and
- * stays open. Subsequent transient `connecting` states (hard reconnect
- * after offline) do NOT re-show the fallback — the app has already
- * rendered once and its own reconnect UI should take over.
- *
- * v0.3.x implementation is non-Suspense: reads `useSyncStatus()` and
- * conditionally renders. v0.3.x+ will ship a
- * the React suspense entry point where `useQuery` / `useOne`
- * actually throw Promises; this component becomes a thin wrapper around
- * React's real `<Suspense>` at that point.
- *
- * @example
- * <AbloProvider fallback={<AppSkeleton />}>
- *   <AppChrome />
- *   <ClientSideSuspense fallback={<CanvasSkeleton />}>
- *     <HeavyCanvas />
- *   </ClientSideSuspense>
- * </AbloProvider>
- */
-export interface ClientSideSuspenseProps {
-    /** What to render while the nested subtree is waiting for first bootstrap. */
-    fallback: ReactNode;
-    /** What to render once the subtree is cleared to render. */
-    children: ReactNode;
-}
-export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react").JSX.Element;

package/dist/react/ClientSideSuspense.js

@@ -1,17 +0,0 @@
-'use client';
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
-import { useSyncStatus } from './useSyncStatus.js';
-export function ClientSideSuspense({ fallback, children }) {
-    const status = useSyncStatus();
-    const [everConnected, setEverConnected] = useState(false);
-    useEffect(() => {
-        if (status.name === 'connected' ||
-            status.name === 'reconnecting' ||
-            status.name === 'disconnected') {
-            setEverConnected(true);
-        }
-    }, [status.name]);
-    const showFallback = !everConnected && status.name === 'connecting';
-    return _jsx(_Fragment, { children: showFallback ? fallback : children });
-}

package/dist/react/useCurrentUserId.d.ts

@@ -1,2 +0,0 @@
-/** Returns the application user id supplied to the nearest AbloProvider. */
-export declare function useCurrentUserId(): string | null;

package/dist/react/useCurrentUserId.js

@@ -1,12 +0,0 @@
-'use client';
-import { useContext } from 'react';
-import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '@abloatai/transaction/errors';
-/** Returns the application user id supplied to the nearest AbloProvider. */
-export function useCurrentUserId() {
-    const context = useContext(AbloInternalContext);
-    if (!context) {
-        throw new AbloValidationError('useCurrentUserId: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
-    }
-    return context.currentUserId;
-}

package/dist/react/useErrorListener.d.ts

@@ -1,2 +0,0 @@
-/** Subscribe to provider-level errors without causing component re-renders. */
-export declare function useErrorListener(listener: (error: Error) => void): void;

package/dist/react/useErrorListener.js

@@ -1,14 +0,0 @@
-'use client';
-import { useContext, useEffect, useRef } from 'react';
-import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '@abloatai/transaction/errors';
-/** Subscribe to provider-level errors without causing component re-renders. */
-export function useErrorListener(listener) {
-    const context = useContext(AbloInternalContext);
-    if (!context) {
-        throw new AbloValidationError('useErrorListener: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
-    }
-    const listenerRef = useRef(listener);
-    listenerRef.current = listener;
-    useEffect(() => context.subscribeError((error) => { listenerRef.current(error); }), [context]);
-}

package/dist/react/useMutationFailureListener.d.ts

@@ -1,8 +0,0 @@
-import { type QueuedMutation } from '../reactRuntime.js';
-export interface MutationFailurePayload {
-    transaction: QueuedMutation;
-    error: Error;
-    permanent?: boolean;
-}
-/** Subscribe to optimistic mutation rollbacks and permanent write failures. */
-export declare function useMutationFailureListener(listener: (payload: MutationFailurePayload) => void): void;

package/dist/react/useMutationFailureListener.js

@@ -1,19 +0,0 @@
-'use client';
-import { useContext, useEffect, useRef } from 'react';
-import { AbloInternalContext, } from '../reactRuntime.js';
-import { AbloValidationError } from '@abloatai/transaction/errors';
-/** Subscribe to optimistic mutation rollbacks and permanent write failures. */
-export function useMutationFailureListener(listener) {
-    const context = useContext(AbloInternalContext);
-    if (!context) {
-        throw new AbloValidationError('useMutationFailureListener: no <AbloProvider> mounted above this component.', { code: 'no_ablo_provider' });
-    }
-    const listenerRef = useRef(listener);
-    listenerRef.current = listener;
-    useEffect(() => {
-        const engine = context.engine;
-        if (!engine)
-            return;
-        return engine.onMutationFailure((payload) => { listenerRef.current(payload); });
-    }, [context, context.engine]);
-}

package/dist/react/useSyncStatus.js

@@ -1,48 +0,0 @@
-'use client';
-import { useCallback, useContext } from 'react';
-import { SyncContext, } from './context.js';
-import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '@abloatai/transaction/errors';
-import { useReactive } from '../useReactive.js';
-/** Reactively exposes the local store's connection and confirmation status. */
-export function useSyncStatus() {
-    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);
-}
-function deriveStatus(store) {
-    const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
-    if (isSessionError)
-        return { name: 'needs-auth' };
-    if (state === 'reconnecting')
-        return { name: 'reconnecting', reason: error?.message };
-    if (state === 'offline')
-        return { name: 'disconnected', reason: 'offline' };
-    if (state === 'error')
-        return { name: 'disconnected', reason: error?.message };
-    if (store.isReady)
-        return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
-    if (state === 'idle' || state === 'syncing')
-        return { name: 'connecting', progress };
-    return { name: 'initial' };
-}
-function sameSnapshot(a, b) {
-    if (a.name !== b.name)
-        return false;
-    if (a.name === 'initial' || a.name === 'needs-auth')
-        return true;
-    if (a.name === 'connecting')
-        return b.name === 'connecting' && a.progress === b.progress;
-    if (a.name === 'connected')
-        return b.name === 'connected' && a.hasUnsyncedChanges === b.hasUnsyncedChanges;
-    return (b.name === 'reconnecting' || b.name === 'disconnected') && a.reason === b.reason;
-}

package/dist/useReactive.d.ts

@@ -1,6 +0,0 @@
-/**
- * Subscribe a React component to a MobX computation with a cached snapshot.
- * This is the framework-level reactive primitive owned by @abloatai/humans;
- * store/model hooks are layered above it.
- */
-export declare function useReactive<T>(compute: () => T, equals?: (a: T, b: T) => boolean): T;

package/dist/useReactive.js

@@ -1,41 +0,0 @@
-'use client';
-import { useCallback, useRef } from 'react';
-import { useSyncExternalStore } from 'react';
-import { reaction } from 'mobx';
-/**
- * Subscribe a React component to a MobX computation with a cached snapshot.
- * This is the framework-level reactive primitive owned by @abloatai/humans;
- * store/model hooks are layered above it.
- */
-export function useReactive(compute, equals = defaultEquals) {
-    const computeRef = useRef(compute);
-    const equalsRef = useRef(equals);
-    const snapshotRef = useRef(null);
-    equalsRef.current = equals;
-    if (snapshotRef.current === null) {
-        snapshotRef.current = { value: compute() };
-    }
-    else if (computeRef.current !== compute) {
-        const next = compute();
-        if (!equals(snapshotRef.current.value, next)) {
-            snapshotRef.current = { value: next };
-        }
-    }
-    computeRef.current = compute;
-    const subscribe = useCallback((onChange) => reaction(() => computeRef.current(), (next) => {
-        const current = snapshotRef.current.value;
-        if (!equalsRef.current(current, next)) {
-            snapshotRef.current = { value: next };
-            onChange();
-        }
-    }), [compute]);
-    const getSnapshot = useCallback(() => snapshotRef.current.value, []);
-    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-}
-function defaultEquals(a, b) {
-    if (Object.is(a, b))
-        return true;
-    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
-        return false;
-    return a.every((value, index) => Object.is(value, b[index]));
-}

package/src/react/ClientSideSuspense.tsx

@@ -1,57 +0,0 @@
-'use client';
-
-import { useEffect, useState, type ReactNode } from 'react';
-import { useSyncStatus } from './useSyncStatus.js';
-
-/**
- * Nested bootstrap gate for a subtree. `<AbloProvider>` already ships
- * its own built-in gate (via its `fallback` prop) that handles the
- * common "wait for first bootstrap" case. Use `ClientSideSuspense`
- * only when you need a SEPARATE gate inside an already-ready provider —
- * for example, rendering app chrome immediately while gating a single
- * heavy product surface on its own query resolving.
- *
- * Like the provider-level gate, this component latches open on the
- * first `connected` / `reconnecting` / `disconnected` transition and
- * stays open. Subsequent transient `connecting` states (hard reconnect
- * after offline) do NOT re-show the fallback — the app has already
- * rendered once and its own reconnect UI should take over.
- *
- * v0.3.x implementation is non-Suspense: reads `useSyncStatus()` and
- * conditionally renders. v0.3.x+ will ship a
- * the React suspense entry point where `useQuery` / `useOne`
- * actually throw Promises; this component becomes a thin wrapper around
- * React's real `<Suspense>` at that point.
- *
- * @example
- * <AbloProvider fallback={<AppSkeleton />}>
- *   <AppChrome />
- *   <ClientSideSuspense fallback={<CanvasSkeleton />}>
- *     <HeavyCanvas />
- *   </ClientSideSuspense>
- * </AbloProvider>
- */
-export interface ClientSideSuspenseProps {
-  /** What to render while the nested subtree is waiting for first bootstrap. */
-  fallback: ReactNode;
-  /** What to render once the subtree is cleared to render. */
-  children: ReactNode;
-}
-
-export function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps) {
-  const status = useSyncStatus();
-  const [everConnected, setEverConnected] = useState(false);
-
-  useEffect(() => {
-    if (
-      status.name === 'connected' ||
-      status.name === 'reconnecting' ||
-      status.name === 'disconnected'
-    ) {
-      setEverConnected(true);
-    }
-  }, [status.name]);
-
-  const showFallback = !everConnected && status.name === 'connecting';
-  return <>{showFallback ? fallback : children}</>;
-}

package/src/react/useCurrentUserId.ts

@@ -1,17 +0,0 @@
-'use client';
-
-import { useContext } from 'react';
-import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '@abloatai/transaction/errors';
-
-/** Returns the application user id supplied to the nearest AbloProvider. */
-export function useCurrentUserId(): string | null {
-  const context = useContext(AbloInternalContext);
-  if (!context) {
-    throw new AbloValidationError(
-      'useCurrentUserId: no <AbloProvider> mounted above this component.',
-      { code: 'no_ablo_provider' },
-    );
-  }
-  return context.currentUserId;
-}

package/src/react/useErrorListener.ts

@@ -1,22 +0,0 @@
-'use client';
-
-import { useContext, useEffect, useRef } from 'react';
-import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError } from '@abloatai/transaction/errors';
-
-/** Subscribe to provider-level errors without causing component re-renders. */
-export function useErrorListener(listener: (error: Error) => void): void {
-  const context = useContext(AbloInternalContext);
-  if (!context) {
-    throw new AbloValidationError(
-      'useErrorListener: no <AbloProvider> mounted above this component.',
-      { code: 'no_ablo_provider' },
-    );
-  }
-  const listenerRef = useRef(listener);
-  listenerRef.current = listener;
-  useEffect(
-    () => context.subscribeError((error) => { listenerRef.current(error); }),
-    [context],
-  );
-}

package/src/react/useMutationFailureListener.ts

@@ -1,34 +0,0 @@
-'use client';
-
-import { useContext, useEffect, useRef } from 'react';
-import {
-  AbloInternalContext,
-  type QueuedMutation,
-} from '../reactRuntime.js';
-import { AbloValidationError } from '@abloatai/transaction/errors';
-
-export interface MutationFailurePayload {
-  transaction: QueuedMutation;
-  error: Error;
-  permanent?: boolean;
-}
-
-/** Subscribe to optimistic mutation rollbacks and permanent write failures. */
-export function useMutationFailureListener(
-  listener: (payload: MutationFailurePayload) => void,
-): void {
-  const context = useContext(AbloInternalContext);
-  if (!context) {
-    throw new AbloValidationError(
-      'useMutationFailureListener: no <AbloProvider> mounted above this component.',
-      { code: 'no_ablo_provider' },
-    );
-  }
-  const listenerRef = useRef(listener);
-  listenerRef.current = listener;
-  useEffect(() => {
-    const engine = context.engine;
-    if (!engine) return;
-    return engine.onMutationFailure((payload) => { listenerRef.current(payload); });
-  }, [context, context.engine]);
-}

package/src/react/useSyncStatus.ts

@@ -1,53 +0,0 @@
-'use client';
-
-import { useCallback, useContext } from 'react';
-import {
-  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 =
-  | { readonly name: 'initial' }
-  | { readonly name: 'connecting'; readonly progress: number }
-  | { readonly name: 'connected'; readonly hasUnsyncedChanges: boolean }
-  | { readonly name: 'reconnecting'; readonly reason?: string }
-  | { readonly name: 'disconnected'; readonly reason?: string }
-  | { readonly name: 'needs-auth' };
-
-/** Reactively exposes the local store's connection and confirmation status. */
-export function useSyncStatus(): SyncStatusSnapshot {
-  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);
-}
-
-function deriveStatus(store: SyncStoreContract): SyncStatusSnapshot {
-  const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
-  if (isSessionError) return { name: 'needs-auth' };
-  if (state === 'reconnecting') return { name: 'reconnecting', reason: error?.message };
-  if (state === 'offline') return { name: 'disconnected', reason: 'offline' };
-  if (state === 'error') return { name: 'disconnected', reason: error?.message };
-  if (store.isReady) return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
-  if (state === 'idle' || state === 'syncing') return { name: 'connecting', progress };
-  return { name: 'initial' };
-}
-
-function sameSnapshot(a: SyncStatusSnapshot, b: SyncStatusSnapshot): boolean {
-  if (a.name !== b.name) return false;
-  if (a.name === 'initial' || a.name === 'needs-auth') return true;
-  if (a.name === 'connecting') return b.name === 'connecting' && a.progress === b.progress;
-  if (a.name === 'connected') return b.name === 'connected' && a.hasUnsyncedChanges === b.hasUnsyncedChanges;
-  return (b.name === 'reconnecting' || b.name === 'disconnected') && a.reason === b.reason;
-}

package/src/useReactive.ts

@@ -1,49 +0,0 @@
-'use client';
-
-import { useCallback, useRef } from 'react';
-import { useSyncExternalStore } from 'react';
-import { reaction } from 'mobx';
-
-/**
- * Subscribe a React component to a MobX computation with a cached snapshot.
- * This is the framework-level reactive primitive owned by @abloatai/humans;
- * store/model hooks are layered above it.
- */
-export function useReactive<T>(
-  compute: () => T,
-  equals: (a: T, b: T) => boolean = defaultEquals,
-): T {
-  const computeRef = useRef(compute);
-  const equalsRef = useRef(equals);
-  const snapshotRef = useRef<{ value: T } | null>(null);
-
-  equalsRef.current = equals;
-  if (snapshotRef.current === null) {
-    snapshotRef.current = { value: compute() };
-  } else if (computeRef.current !== compute) {
-    const next = compute();
-    if (!equals(snapshotRef.current.value, next)) {
-      snapshotRef.current = { value: next };
-    }
-  }
-  computeRef.current = compute;
-
-  const subscribe = useCallback((onChange: () => void) => reaction(
-    () => computeRef.current(),
-    (next) => {
-      const current = snapshotRef.current!.value;
-      if (!equalsRef.current(current, next)) {
-        snapshotRef.current = { value: next };
-        onChange();
-      }
-    },
-  ), [compute]);
-  const getSnapshot = useCallback(() => snapshotRef.current!.value, []);
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-}
-
-function defaultEquals<T>(a: T, b: T): boolean {
-  if (Object.is(a, b)) return true;
-  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
-  return a.every((value, index) => Object.is(value, b[index]));
-}