@chelone/vue 0.0.0-stage → 0.1.0

package/dist/maps-draw.js

@@ -0,0 +1,28 @@
+import { BBoxInput } from "./components/maps-draw/bbox-input.js";
+import { default as default2 } from "./components/maps-draw/draw-toolbar.vue.js";
+import { cutFeatures, simplifyGeo } from "./components/maps-draw/geometry-ops.js";
+import { default as default3 } from "./components/maps-draw/shape-input.vue.js";
+import { FeatureCollectionInput, FeatureInput, GeoJsonInput, GeometryCollectionInput, LineStringInput, MultiLineStringInput, MultiPointInput, MultiPolygonInput, PointInput, PolygonInput, toolsForShapes } from "./components/maps-draw/shape-inputs.js";
+import { default as default4 } from "./components/maps-draw/simplify-input.vue.js";
+import { toolMode, useTerraDraw } from "./components/maps-draw/use-terra-draw.js";
+export {
+  BBoxInput,
+  default2 as DrawToolbar,
+  FeatureCollectionInput,
+  FeatureInput,
+  GeoJsonInput,
+  GeometryCollectionInput,
+  LineStringInput,
+  MultiLineStringInput,
+  MultiPointInput,
+  MultiPolygonInput,
+  PointInput,
+  PolygonInput,
+  default3 as ShapeInput,
+  default4 as SimplifyInput,
+  cutFeatures,
+  simplifyGeo,
+  toolMode,
+  toolsForShapes,
+  useTerraDraw
+};

package/dist/maps-osm.d.ts

@@ -0,0 +1,10 @@
+export { default as GeocodingInput, type GeocodingInputProps, } from "./components/maps-osm/geocoding-input.vue.js";
+export { default as MapWithSearch, type MapWithSearchProps, } from "./components/maps-osm/map-with-search.vue.js";
+export { default as OsmFeatureOperator, type OsmFeatureOperatorProps, } from "./components/maps-osm/osm-feature-operator.vue.js";
+export { OsmFeatureAdd, type OsmFeatureAddProps, OsmFeatureSubtract, type OsmFeatureSubtractProps, } from "./components/maps-osm/osm-feature-operators.js";
+export { type FetchOsmFeaturesOptions, fetchOsmFeatures, osmToPolygons, } from "./components/maps-osm/osm-features.js";
+export { subtractMask, unionAll } from "./components/maps-osm/osm-geometry-ops.js";
+export { default as ReverseGeocodeField, type ReverseGeocodeFieldProps, } from "./components/maps-osm/reverse-geocode-field.vue.js";
+export { type UseGeocodeOptions, useGeocode, } from "./components/maps-osm/use-geocode.js";
+export { type UseOsmFeaturesOptions, useOsmFeatures, } from "./components/maps-osm/use-osm-features.js";
+export { type UseReverseGeocodeOptions, useReverseGeocode, } from "./components/maps-osm/use-reverse-geocode.js";

package/dist/maps-osm.js

@@ -0,0 +1,25 @@
+import { default as default2 } from "./components/maps-osm/geocoding-input.vue.js";
+import { default as default3 } from "./components/maps-osm/map-with-search.vue.js";
+import { default as default4 } from "./components/maps-osm/osm-feature-operator.vue.js";
+import { OsmFeatureAdd, OsmFeatureSubtract } from "./components/maps-osm/osm-feature-operators.js";
+import { fetchOsmFeatures, osmToPolygons } from "./components/maps-osm/osm-features.js";
+import { subtractMask, unionAll } from "./components/maps-osm/osm-geometry-ops.js";
+import { default as default5 } from "./components/maps-osm/reverse-geocode-field.vue.js";
+import { useGeocode } from "./components/maps-osm/use-geocode.js";
+import { useOsmFeatures } from "./components/maps-osm/use-osm-features.js";
+import { useReverseGeocode } from "./components/maps-osm/use-reverse-geocode.js";
+export {
+  default2 as GeocodingInput,
+  default3 as MapWithSearch,
+  OsmFeatureAdd,
+  default4 as OsmFeatureOperator,
+  OsmFeatureSubtract,
+  default5 as ReverseGeocodeField,
+  fetchOsmFeatures,
+  osmToPolygons,
+  subtractMask,
+  unionAll,
+  useGeocode,
+  useOsmFeatures,
+  useReverseGeocode
+};

package/dist/maps.d.ts

@@ -0,0 +1,10 @@
+export { type BBoxFieldProps, default as BBoxField, } from "./components/maps/bbox-field.vue.js";
+export { default as GeoJsonField, type GeoJsonFieldProps, } from "./components/maps/geo-json-field.vue.js";
+export { default as GeoJsonLayers, type GeoJsonLayersProps, } from "./components/maps/geo-json-layers.vue.js";
+export { default as GeoJsonView, type GeoJsonViewProps, } from "./components/maps/geo-json-view.vue.js";
+export { default as LatLngField, type LatLngFieldProps, } from "./components/maps/lat-lng-field.vue.js";
+export { default as LatLngInput, type LatLngInputProps, } from "./components/maps/lat-lng-input.vue.js";
+export { default as MapCanvas, type MapCanvasProps, } from "./components/maps/map-canvas.vue.js";
+export { FeatureCollectionField, FeatureField, GeometryCollectionField, LineStringField, MultiLineStringField, MultiPointField, MultiPolygonField, PointField, PolygonField, } from "./components/maps/shape-fields.js";
+export { useGeoJsonSource } from "./components/maps/use-geo-json-source.js";
+export { MapMarker, type MapMarkerOptions, type MapMarkerProps, type MapsConfig, MapsProvider, type MapsProviderProps, useMap, useMapMarker, useMapsConfig, } from "./components/maps/use-map.js";

package/dist/maps.js

@@ -0,0 +1,34 @@
+import { default as default2 } from "./components/maps/bbox-field.vue.js";
+import { default as default3 } from "./components/maps/geo-json-field.vue.js";
+import { default as default4 } from "./components/maps/geo-json-layers.vue.js";
+import { default as default5 } from "./components/maps/geo-json-view.vue.js";
+import { default as default6 } from "./components/maps/lat-lng-field.vue.js";
+import { default as default7 } from "./components/maps/lat-lng-input.vue.js";
+import { default as default8 } from "./components/maps/map-canvas.vue.js";
+import { FeatureCollectionField, FeatureField, GeometryCollectionField, LineStringField, MultiLineStringField, MultiPointField, MultiPolygonField, PointField, PolygonField } from "./components/maps/shape-fields.js";
+import { useGeoJsonSource } from "./components/maps/use-geo-json-source.js";
+import { MapMarker, MapsProvider, useMap, useMapMarker, useMapsConfig } from "./components/maps/use-map.js";
+export {
+  default2 as BBoxField,
+  FeatureCollectionField,
+  FeatureField,
+  default3 as GeoJsonField,
+  default4 as GeoJsonLayers,
+  default5 as GeoJsonView,
+  GeometryCollectionField,
+  default6 as LatLngField,
+  default7 as LatLngInput,
+  LineStringField,
+  default8 as MapCanvas,
+  MapMarker,
+  MapsProvider,
+  MultiLineStringField,
+  MultiPointField,
+  MultiPolygonField,
+  PointField,
+  PolygonField,
+  useGeoJsonSource,
+  useMap,
+  useMapMarker,
+  useMapsConfig
+};

package/dist/mdx-editor.d.ts

@@ -0,0 +1,2 @@
+export { default as MdxField, type MdxFieldProps, } from "./components/mdx-editor/mdx-field.vue.js";
+export { default as MdxInput, type MdxInputProps, } from "./components/mdx-editor/mdx-input.vue.js";

package/dist/mdx-editor.js

@@ -0,0 +1,6 @@
+import { default as default2 } from "./components/mdx-editor/mdx-field.vue.js";
+import { default as default3 } from "./components/mdx-editor/mdx-input.vue.js";
+export {
+  default2 as MdxField,
+  default3 as MdxInput
+};

package/dist/monaco.d.ts

@@ -0,0 +1,2 @@
+export { default as MonacoJsonField, type MonacoJsonFieldProps, } from "./components/monaco/monaco-json-field.vue.js";
+export { default as MonacoJsonInput, type MonacoJsonInputProps, } from "./components/monaco/monaco-json-input.vue.js";

package/dist/monaco.js

@@ -0,0 +1,6 @@
+import { default as default2 } from "./components/monaco/monaco-json-field.vue.js";
+import { default as default3 } from "./components/monaco/monaco-json-input.vue.js";
+export {
+  default2 as MonacoJsonField,
+  default3 as MonacoJsonInput
+};

package/dist/notification-hooks.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Notification composables — the Vue twin of `@chelone/react`'s
+ * `notification-hooks.ts` (`useNotifications` / `useNotify`). React reads the
+ * store with `useSyncExternalStore`; Vue bridges the same
+ * `subscribe`/`getSnapshot` seam into a `shallowRef` released on scope disposal
+ * (the pattern established by `store/use-micro-store.ts`).
+ *
+ * Both adapters degrade `useNotifications` to an empty snapshot without a store
+ * (so `<Notification>` renders nothing) and throw from `useNotify`: pushing a
+ * notification with no store is a wiring error.
+ */
+import type { Notification, NotificationStore } from "@chelone/core";
+import { type Ref } from "vue";
+/**
+ * Reactive snapshot of the pending notification queue (i18n keys — translate in
+ * the UI). Degrades to a stable empty list when no store was provided.
+ */
+export declare function useNotifications(): Readonly<Ref<readonly Notification[]>>;
+/** Stable `notify` action off the shared store — throws when none was provided. */
+export declare function useNotify(): NotificationStore["notify"];

package/dist/notification-hooks.js

@@ -0,0 +1,27 @@
+import { computed, shallowRef, onScopeDispose } from "vue";
+import { useCheloneNotifications } from "./context.js";
+function useNotifications() {
+  const store = useCheloneNotifications();
+  if (!store) {
+    return computed(() => []);
+  }
+  const snapshot = shallowRef(store.getSnapshot());
+  const unsubscribe = store.subscribe(() => {
+    snapshot.value = store.getSnapshot();
+  });
+  onScopeDispose(unsubscribe);
+  return computed(() => snapshot.value);
+}
+function useNotify() {
+  const store = useCheloneNotifications();
+  if (!store) {
+    throw new Error(
+      "useNotify: pass a notification store to <Admin notifications={createNotificationStore()}>."
+    );
+  }
+  return store.notify;
+}
+export {
+  useNotifications,
+  useNotify
+};

package/dist/realtime/live.d.ts

@@ -0,0 +1,13 @@
+import { type GetListParams, type GetManyParams, type GetOneParams, type ResourceMap } from "@chelone/core";
+import { type MaybeRefOrGetter } from "vue";
+interface LiveReadOptions {
+    /** Gates the subscription as well as the fetch. */
+    enabled?: MaybeRefOrGetter<boolean>;
+}
+/** `useGetList`, kept fresh: refetches when the resource changes or the connection comes back. */
+export declare function useGetListLive<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(resource: MaybeRefOrGetter<TName>, params?: MaybeRefOrGetter<GetListParams>, options?: LiveReadOptions): import("@tanstack/vue-query").UseQueryReturnType<import("@chelone/core").GetListResult<import("@chelone/core").RecordOf<TResources, TName>>, Error>;
+/** `useGetOne`, kept fresh: refetches when the record changes or the connection comes back. */
+export declare function useGetOneLive<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(resource: TName, params: MaybeRefOrGetter<GetOneParams>, options?: LiveReadOptions): import("@tanstack/vue-query").UseQueryReturnType<import("@chelone/core").RecordOf<TResources, TName>, Error>;
+/** `useGetMany`, kept fresh: refetches when any listed record changes or the connection comes back. */
+export declare function useGetManyLive<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(resource: TName, params: MaybeRefOrGetter<GetManyParams>, options?: LiveReadOptions): import("@tanstack/vue-query").UseQueryReturnType<import("@chelone/core").RecordOf<TResources, TName>[], Error>;
+export {};

package/dist/realtime/live.js

@@ -0,0 +1,44 @@
+import { subscribeLiveResource, subscribeLiveRecords, subscribeLiveRecord } from "@chelone/core";
+import { watchEffect, toValue, computed } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useGetList, useGetMany, useGetOne } from "../data/queries.js";
+const isEnabled = (enabled) => enabled === void 0 || toValue(enabled);
+function useGetListLive(resource, params = {}, options = {}) {
+  const ctx = useCheloneContext();
+  const query = useGetList(resource, params, options);
+  watchEffect((onCleanup) => {
+    if (!isEnabled(options.enabled)) return;
+    onCleanup(subscribeLiveResource(ctx, toValue(resource)).stop);
+  });
+  return query;
+}
+function useGetOneLive(resource, params, options = {}) {
+  const ctx = useCheloneContext();
+  const query = useGetOne(resource, params, options);
+  watchEffect((onCleanup) => {
+    if (!isEnabled(options.enabled)) return;
+    onCleanup(subscribeLiveRecord(ctx, resource, toValue(params).id).stop);
+  });
+  return query;
+}
+function useGetManyLive(resource, params, options = {}) {
+  const ctx = useCheloneContext();
+  const query = useGetMany(resource, params, options);
+  let previous;
+  const ids = computed(() => {
+    const next = toValue(params).ids;
+    const key = JSON.stringify(next.map(String).sort());
+    if (previous?.key !== key) previous = { key, ids: next };
+    return previous.ids;
+  });
+  watchEffect((onCleanup) => {
+    if (!isEnabled(options.enabled)) return;
+    onCleanup(subscribeLiveRecords(ctx, resource, ids.value).stop);
+  });
+  return query;
+}
+export {
+  useGetListLive,
+  useGetManyLive,
+  useGetOneLive
+};

package/dist/realtime/locks.d.ts

@@ -0,0 +1,55 @@
+import { type GetLockParams, type Identifier, type Lock, type ResourceMap } from "@chelone/core";
+import { type MaybeRefOrGetter } from "vue";
+interface LockCallParams {
+    id: Identifier;
+    /** Defaults to the auth provider's identity. */
+    identity?: Identifier;
+    meta?: Record<string, unknown>;
+}
+interface LockReadOptions {
+    /** Gates the fetch, and the subscription of the live variants. */
+    enabled?: MaybeRefOrGetter<boolean>;
+}
+/** Takes a record's lock. Rejects, and stores the error, when another identity holds it. */
+export declare function useLock(): {
+    lock: (resource: string, params: LockCallParams) => Promise<Lock>;
+    isLoading: import("vue").ComputedRef<boolean>;
+    error: import("vue").ComputedRef<Error | null>;
+};
+/** Releases a record's lock. Rejects, and stores the error, when another identity holds it. */
+export declare function useUnlock(): {
+    unlock: (resource: string, params: LockCallParams) => Promise<Lock>;
+    isLoading: import("vue").ComputedRef<boolean>;
+    error: import("vue").ComputedRef<Error | null>;
+};
+/** One record's lock, or `null` when it is free. */
+export declare function useGetLock<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(resource: TName, params: MaybeRefOrGetter<GetLockParams>, options?: LockReadOptions): import("@tanstack/vue-query").UseQueryReturnType<Lock | null, Error>;
+/** Every lock held on a resource. */
+export declare function useGetLocks<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(resource: TName, options?: LockReadOptions): import("@tanstack/vue-query").UseQueryReturnType<Lock[], Error>;
+/** `useGetLock`, kept fresh: refetches when the lock is taken or released, or the connection comes back. */
+export declare function useGetLockLive<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(resource: TName, params: MaybeRefOrGetter<GetLockParams>, options?: LockReadOptions): import("@tanstack/vue-query").UseQueryReturnType<Lock | null, Error>;
+/** `useGetLocks`, kept fresh: refetches when any lock of the resource changes, or the connection comes back. */
+export declare function useGetLocksLive<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(resource: TName, options?: LockReadOptions): import("@tanstack/vue-query").UseQueryReturnType<Lock[], Error>;
+export interface UseLockOnMountOptions {
+    /** Defaults to the ambient resource. */
+    resource?: MaybeRefOrGetter<string | undefined>;
+    /** Defaults to the id of the ambient record. */
+    id?: MaybeRefOrGetter<Identifier | null | undefined>;
+    /** Defaults to the auth provider's identity. */
+    identity?: MaybeRefOrGetter<Identifier | undefined>;
+    meta?: Record<string, unknown>;
+    /** Called with a failed lock or release. */
+    onLockError?: (error: Error) => void;
+}
+/**
+ * Holds a record's lock for as long as the component lives. A changing
+ * resource, id or identity releases the old lock and takes the new one. With
+ * no resource, id or identity (explicit, or from the auth provider) it takes
+ * nothing and reports no error.
+ */
+export declare function useLockOnMount({ resource, id, identity, meta, onLockError, }?: UseLockOnMountOptions): {
+    lock: import("vue").ComputedRef<Lock | null>;
+    isLocking: import("vue").ComputedRef<boolean>;
+    lockError: import("vue").ComputedRef<Error | null>;
+};
+export {};

package/dist/realtime/locks.js

@@ -0,0 +1,163 @@
+import { createMicroStore, assertRealtimeDataProvider, createLockSession, resolveLockIdentity, getLockOptions, subscribeLiveLock, getLocksOptions, subscribeLiveLocks } from "@chelone/core";
+import { useQuery, useMutation } from "@tanstack/vue-query";
+import { inject, computed, toValue, watchEffect } from "vue";
+import { useCheloneContext } from "../context.js";
+import { RecordContextKey } from "../record/record-context.js";
+import { useResourceContext } from "../resource-context.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+const isEnabled = (enabled) => enabled === void 0 || toValue(enabled);
+function useLock() {
+  const { dataProvider, authProvider } = useCheloneContext();
+  const mutation = useMutation({
+    mutationFn: async ({
+      resource,
+      id,
+      identity,
+      meta
+    }) => {
+      assertRealtimeDataProvider(dataProvider, "useLock");
+      return dataProvider.lock(resource, {
+        id,
+        identity: await resolveLockIdentity(authProvider, identity),
+        ...meta ? { meta } : {}
+      });
+    }
+  });
+  return {
+    lock: (resource, params) => mutation.mutateAsync({ resource, ...params }),
+    isLoading: computed(() => mutation.isPending.value),
+    error: computed(() => mutation.error.value)
+  };
+}
+function useUnlock() {
+  const { dataProvider, authProvider } = useCheloneContext();
+  const mutation = useMutation({
+    mutationFn: async ({
+      resource,
+      id,
+      identity,
+      meta
+    }) => {
+      assertRealtimeDataProvider(dataProvider, "useUnlock");
+      return dataProvider.unlock(resource, {
+        id,
+        identity: await resolveLockIdentity(authProvider, identity),
+        ...meta ? { meta } : {}
+      });
+    }
+  });
+  return {
+    unlock: (resource, params) => mutation.mutateAsync({ resource, ...params }),
+    isLoading: computed(() => mutation.isPending.value),
+    error: computed(() => mutation.error.value)
+  };
+}
+function useGetLock(resource, params, options = {}) {
+  const ctx = useCheloneContext();
+  return useQuery(
+    computed(() => ({
+      ...getLockOptions(ctx, resource, toValue(params)),
+      enabled: isEnabled(options.enabled)
+    }))
+  );
+}
+function useGetLocks(resource, options = {}) {
+  const ctx = useCheloneContext();
+  return useQuery(
+    computed(() => ({
+      ...getLocksOptions(ctx, resource),
+      enabled: isEnabled(options.enabled)
+    }))
+  );
+}
+function useGetLockLive(resource, params, options = {}) {
+  const ctx = useCheloneContext();
+  const query = useGetLock(resource, params, options);
+  watchEffect((onCleanup) => {
+    if (!isEnabled(options.enabled)) return;
+    onCleanup(subscribeLiveLock(ctx, resource, toValue(params).id).stop);
+  });
+  return query;
+}
+function useGetLocksLive(resource, options = {}) {
+  const ctx = useCheloneContext();
+  const query = useGetLocks(resource, options);
+  watchEffect((onCleanup) => {
+    if (!isEnabled(options.enabled)) return;
+    onCleanup(subscribeLiveLocks(ctx, resource).stop);
+  });
+  return query;
+}
+const idleLockState = {
+  lock: null,
+  isLocking: false,
+  error: null
+};
+function useLockOnMount({
+  resource,
+  id,
+  identity,
+  meta,
+  onLockError
+} = {}) {
+  const { dataProvider, authProvider } = useCheloneContext();
+  const ambientResource = useResourceContext();
+  const ambientRecord = inject(RecordContextKey, null);
+  const resolvedResource = computed(() => toValue(resource) ?? ambientResource);
+  const resolvedId = computed(
+    () => toValue(id) ?? ambientRecord?.value?.id
+  );
+  const resolvedIdentity = computed(() => toValue(identity));
+  const mirror = createMicroStore(idleLockState);
+  const state = useMicroStore(mirror);
+  let previous = Promise.resolve();
+  watchEffect((onCleanup) => {
+    const resourceName = resolvedResource.value;
+    const recordId = resolvedId.value;
+    const holder = resolvedIdentity.value;
+    if (resourceName === void 0 || recordId == null) return;
+    if (holder === void 0 && !authProvider?.getIdentity) return;
+    assertRealtimeDataProvider(dataProvider, "useLockOnMount");
+    const session = createLockSession({
+      dataProvider,
+      resource: resourceName,
+      id: recordId,
+      getIdentity: () => resolveLockIdentity(authProvider, holder),
+      meta,
+      onError: onLockError
+    });
+    let cancelled = false;
+    let unsubscribe = () => {
+    };
+    mirror.setState({ ...idleLockState, isLocking: true });
+    const turn = previous;
+    void turn.then(() => {
+      if (cancelled) return;
+      unsubscribe = session.store.subscribe(
+        () => mirror.setState(session.store.getSnapshot())
+      );
+      void session.start();
+      mirror.setState(session.store.getSnapshot());
+    });
+    onCleanup(() => {
+      cancelled = true;
+      unsubscribe();
+      mirror.setState(idleLockState);
+      previous = turn.then(() => session.stop());
+    });
+  });
+  return {
+    lock: computed(() => state.value.lock),
+    isLocking: computed(() => state.value.isLocking),
+    lockError: computed(() => state.value.error)
+  };
+}
+export {
+  useGetLock,
+  useGetLockLive,
+  useGetLocks,
+  useGetLocksLive,
+  useLock,
+  useLockOnMount,
+  useUnlock
+};

package/dist/realtime/presence.d.ts

@@ -0,0 +1,23 @@
+import { type PresenceUser } from "@chelone/core";
+import { type ComputedRef, type MaybeRefOrGetter } from "vue";
+export interface UsePresenceOptions {
+    /** Defaults to the topic of the ambient resource and record. */
+    topic?: MaybeRefOrGetter<string | undefined>;
+    /** Defaults to the auth provider's identity. */
+    user?: MaybeRefOrGetter<PresenceUser | undefined>;
+    /** How often the announce is republished. Default 15000. */
+    heartbeatMs?: MaybeRefOrGetter<number | undefined>;
+    /** A session unheard for longer than this is dropped. Default 30000. */
+    staleMs?: MaybeRefOrGetter<number | undefined>;
+    /** Announces only while true. Defaults to true. */
+    enabled?: MaybeRefOrGetter<boolean>;
+}
+/**
+ * Announces the current user on a topic for as long as the component lives
+ * and returns the other users there. A changing topic or user leaves the old
+ * topic and joins the new one. With no topic, no user or `enabled` false it
+ * announces nothing and `users` stays empty.
+ */
+export declare function usePresence({ topic, user, heartbeatMs, staleMs, enabled, }?: UsePresenceOptions): {
+    users: ComputedRef<PresenceUser[]>;
+};

package/dist/realtime/presence.js

@@ -0,0 +1,65 @@
+import { presenceTopic, toPresenceUser, createMicroStore, assertRealtimeDataProvider, createPresenceSession } from "@chelone/core";
+import { inject, computed, toValue, watchEffect } from "vue";
+import { useOptionalIdentity } from "../auth/auth-hooks.js";
+import { useCheloneContext } from "../context.js";
+import { RecordContextKey } from "../record/record-context.js";
+import { useResourceContext } from "../resource-context.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+const idleState = { users: [] };
+function usePresence({
+  topic,
+  user,
+  heartbeatMs,
+  staleMs,
+  enabled
+} = {}) {
+  const { dataProvider } = useCheloneContext();
+  const ambientResource = useResourceContext();
+  const ambientRecord = inject(RecordContextKey, null);
+  const { identity } = useOptionalIdentity();
+  const resolvedTopic = computed(() => {
+    const explicit = toValue(topic);
+    if (explicit !== void 0) return explicit;
+    const id = ambientRecord?.value?.id;
+    return ambientResource !== void 0 && id != null ? presenceTopic(ambientResource, id) : void 0;
+  });
+  const resolvedUser = computed(
+    () => toValue(user) ?? (identity.value ? toPresenceUser(identity.value) : void 0)
+  );
+  const userId = computed(() => resolvedUser.value?.id);
+  const userName = computed(() => resolvedUser.value?.name);
+  const userAvatar = computed(() => resolvedUser.value?.avatar);
+  const mirror = createMicroStore(idleState);
+  const state = useMicroStore(mirror);
+  watchEffect((onCleanup) => {
+    const topicName = resolvedTopic.value;
+    const id = userId.value;
+    const name = userName.value;
+    if (enabled !== void 0 && !toValue(enabled)) return;
+    if (topicName === void 0 || id === void 0 || name === void 0)
+      return;
+    assertRealtimeDataProvider(dataProvider, "usePresence");
+    const avatar = userAvatar.value;
+    const session = createPresenceSession({
+      dataProvider,
+      topic: topicName,
+      user: { id, name, ...avatar !== void 0 ? { avatar } : {} },
+      heartbeatMs: toValue(heartbeatMs),
+      staleMs: toValue(staleMs)
+    });
+    const unsubscribe = session.store.subscribe(
+      () => mirror.setState(session.store.getSnapshot())
+    );
+    session.start();
+    mirror.setState(session.store.getSnapshot());
+    onCleanup(() => {
+      unsubscribe();
+      session.stop();
+      mirror.setState(idleState);
+    });
+  });
+  return { users: computed(() => state.value.users) };
+}
+export {
+  usePresence
+};

package/dist/realtime/subscribe.d.ts

@@ -0,0 +1,28 @@
+import { type Identifier, type RealtimeConnectionStatus, type RealtimeTransportError, type SubscriptionCallback, type Unsubscribe } from "@chelone/core";
+import { type ComputedRef, type MaybeRefOrGetter } from "vue";
+export interface UseSubscribeOptions {
+    /** Subscribes only while true. Defaults to true. */
+    enabled?: MaybeRefOrGetter<boolean>;
+}
+/**
+ * Listens to `topic` for as long as the component lives and `enabled` is
+ * true. A changing topic or `enabled` resubscribes. The callback is read at
+ * subscribe time; a Vue callback closes over live refs, so it needs no
+ * latest-callback ref.
+ */
+export declare function useSubscribe<P = unknown>(topic: MaybeRefOrGetter<string>, callback: SubscriptionCallback<P>, { enabled }?: UseSubscribeOptions): void;
+/** Returns `subscribe(topic, callback)` for subscriptions made on demand; the caller owns the unsubscribe. */
+export declare function useSubscribeCallback(): <P = unknown>(topic: string, callback: SubscriptionCallback<P>) => Unsubscribe;
+/** Listens to one record's topic. Does nothing while `id` is null or undefined; `0` is an id. */
+export declare function useSubscribeToRecord<P = unknown>(resource: MaybeRefOrGetter<string>, id: MaybeRefOrGetter<Identifier | null | undefined>, callback: SubscriptionCallback<P>, { enabled }?: UseSubscribeOptions): void;
+/** Listens to a resource's topic: creates, and the ids of any write. */
+export declare function useSubscribeToRecordList<P = unknown>(resource: MaybeRefOrGetter<string>, callback: SubscriptionCallback<P>, options?: UseSubscribeOptions): void;
+/** Returns `publish(topic, event)` over the data provider. */
+export declare function usePublish(): <P = unknown>(topic: string, event: Omit<import("@chelone/core").RealtimeEvent<P>, "topic">) => Promise<void>;
+/** Calls `callback` each time the transport reconnects. Does nothing when the transport cannot tell. */
+export declare function useOnReconnect(callback: () => void): void;
+/** The connection status and the latest transport error, as refs that follow the transport. */
+export declare function useRealtimeStatus(): {
+    status: ComputedRef<RealtimeConnectionStatus>;
+    lastError: ComputedRef<RealtimeTransportError | null>;
+};

package/dist/realtime/subscribe.js

@@ -0,0 +1,58 @@
+import { assertRealtimeDataProvider, createRealtimeStatusStore, recordTopic, resourceTopic } from "@chelone/core";
+import { onScopeDispose, computed, watchEffect, toValue } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+function useSubscribe(topic, callback, { enabled } = {}) {
+  const { dataProvider } = useCheloneContext();
+  watchEffect((onCleanup) => {
+    if (enabled !== void 0 && !toValue(enabled)) return;
+    assertRealtimeDataProvider(dataProvider, "useSubscribe");
+    onCleanup(dataProvider.subscribe(toValue(topic), callback));
+  });
+}
+function useSubscribeCallback() {
+  const { dataProvider } = useCheloneContext();
+  assertRealtimeDataProvider(dataProvider, "useSubscribeCallback");
+  return (topic, callback) => dataProvider.subscribe(topic, callback);
+}
+function useSubscribeToRecord(resource, id, callback, { enabled } = {}) {
+  useSubscribe(
+    () => recordTopic(toValue(resource), toValue(id) ?? ""),
+    callback,
+    {
+      enabled: () => toValue(id) != null && (enabled === void 0 || toValue(enabled))
+    }
+  );
+}
+function useSubscribeToRecordList(resource, callback, options = {}) {
+  useSubscribe(() => resourceTopic(toValue(resource)), callback, options);
+}
+function usePublish() {
+  const { dataProvider } = useCheloneContext();
+  assertRealtimeDataProvider(dataProvider, "usePublish");
+  return dataProvider.publish.bind(dataProvider);
+}
+function useOnReconnect(callback) {
+  const { dataProvider } = useCheloneContext();
+  assertRealtimeDataProvider(dataProvider, "useOnReconnect");
+  const unsubscribe = dataProvider.onReconnect?.(callback);
+  if (unsubscribe) onScopeDispose(unsubscribe);
+}
+function useRealtimeStatus() {
+  const { dataProvider } = useCheloneContext();
+  assertRealtimeDataProvider(dataProvider, "useRealtimeStatus");
+  const state = useMicroStore(createRealtimeStatusStore(dataProvider));
+  return {
+    status: computed(() => state.value.status),
+    lastError: computed(() => state.value.lastError)
+  };
+}
+export {
+  useOnReconnect,
+  usePublish,
+  useRealtimeStatus,
+  useSubscribe,
+  useSubscribeCallback,
+  useSubscribeToRecord,
+  useSubscribeToRecordList
+};