@chelone/core 0.5.0 → 0.7.0

package/dist/notification/notification-store.js

@@ -1,47 +1,43 @@
+// src/notification/notification-store.ts
 function createNotificationStore() {
-  let notifications = [];
-  let nextId = 1;
-  const subscribers = /* @__PURE__ */ new Set();
-  const emit = () => {
-    for (const cb of subscribers) cb();
-  };
-  return {
-    notify(message, options = {}) {
-      const id = nextId++;
-      notifications = [
-        ...notifications,
-        {
-          id,
-          message,
-          type: options.type ?? "info",
-          messageArgs: options.messageArgs,
-          undoable: options.undoable,
-          autoHideDuration: options.autoHideDuration,
-          undo: options.undo,
-          onClose: options.onClose
-        }
-      ];
-      emit();
-      return id;
-    },
-    dismiss(id) {
-      const next = notifications.filter((n) => n.id !== id);
-      if (next.length === notifications.length) return;
-      notifications = next;
-      emit();
-    },
-    clear() {
-      if (notifications.length === 0) return;
-      notifications = [];
-      emit();
-    },
-    getSnapshot: () => notifications,
-    subscribe(callback) {
-      subscribers.add(callback);
-      return () => void subscribers.delete(callback);
-    }
-  };
+	let notifications = [];
+	let nextId = 1;
+	const subscribers = /* @__PURE__ */ new Set();
+	const emit = () => {
+		for (const cb of subscribers) cb();
+	};
+	return {
+		notify(message, options = {}) {
+			const id = nextId++;
+			notifications = [...notifications, {
+				id,
+				message,
+				type: options.type ?? "info",
+				messageArgs: options.messageArgs,
+				undoable: options.undoable,
+				autoHideDuration: options.autoHideDuration,
+				undo: options.undo,
+				onClose: options.onClose
+			}];
+			emit();
+			return id;
+		},
+		dismiss(id) {
+			const next = notifications.filter((n) => n.id !== id);
+			if (next.length === notifications.length) return;
+			notifications = next;
+			emit();
+		},
+		clear() {
+			if (notifications.length === 0) return;
+			notifications = [];
+			emit();
+		},
+		getSnapshot: () => notifications,
+		subscribe(callback) {
+			subscribers.add(callback);
+			return () => void subscribers.delete(callback);
+		}
+	};
 }
-export {
-  createNotificationStore
-};
+export { createNotificationStore };

package/dist/onboarding-tour/placement.d.ts

@@ -0,0 +1,34 @@
+/** A box in viewport pixels. The adapters measure it; core touches no DOM. */
+export interface TourRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export type TourPlacement = "auto" | "top" | "bottom" | "left" | "right";
+type Side = Exclude<TourPlacement, "auto">;
+export interface PlaceTourCardOptions {
+    /** `null` centres the card, for a step that points at nothing. */
+    target: TourRect | null;
+    card: {
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    placement: TourPlacement;
+    /** Gap between card and target, and the least distance to a viewport edge. */
+    margin?: number;
+}
+export interface TourCardPosition {
+    /** The card's top-left corner. */
+    top: number;
+    left: number;
+    side: Side;
+}
+export declare function placeTourCard({ target, card, viewport, placement, margin, }: PlaceTourCardOptions): TourCardPosition;
+/** A CSS `clip-path` that fills the page except the target's rect. */
+export declare function tourSpotlightPath(target: TourRect): string;
+export {};

package/dist/onboarding-tour/placement.js

@@ -0,0 +1,67 @@
+// src/onboarding-tour/placement.ts
+var SIDES = [
+	"bottom",
+	"top",
+	"right",
+	"left"
+];
+var OPPOSITE = {
+	top: "bottom",
+	bottom: "top",
+	left: "right",
+	right: "left"
+};
+function placeTourCard({ target, card, viewport, placement, margin = 12 }) {
+	if (!target) return {
+		top: (viewport.height - card.height) / 2,
+		left: (viewport.width - card.width) / 2,
+		side: placement === "auto" ? "bottom" : placement
+	};
+	const room = {
+		top: target.top,
+		bottom: viewport.height - (target.top + target.height),
+		left: target.left,
+		right: viewport.width - (target.left + target.width)
+	};
+	const needed = (side) => (side === "top" || side === "bottom" ? card.height : card.width) + margin * 2;
+	const fits = (side) => room[side] >= needed(side);
+	let side;
+	if (placement === "auto") {
+		const roomiest = (candidates) => candidates.reduce((best, next) => room[next] > room[best] ? next : best);
+		const fitting = SIDES.filter(fits);
+		side = roomiest(fitting.length > 0 ? fitting : SIDES);
+	} else side = !fits(placement) && fits(OPPOSITE[placement]) ? OPPOSITE[placement] : placement;
+	const centreX = target.left + target.width / 2 - card.width / 2;
+	const centreY = target.top + target.height / 2 - card.height / 2;
+	let top;
+	let left;
+	switch (side) {
+		case "bottom":
+			top = target.top + target.height + margin;
+			left = centreX;
+			break;
+		case "top":
+			top = target.top - margin - card.height;
+			left = centreX;
+			break;
+		case "right":
+			top = centreY;
+			left = target.left + target.width + margin;
+			break;
+		case "left":
+			top = centreY;
+			left = target.left - margin - card.width;
+	}
+	return {
+		top: Math.max(margin, Math.min(top, viewport.height - card.height - margin)),
+		left: Math.max(margin, Math.min(left, viewport.width - card.width - margin)),
+		side
+	};
+}
+/** A CSS `clip-path` that fills the page except the target's rect. */
+function tourSpotlightPath(target) {
+	const right = target.left + target.width;
+	const bottom = target.top + target.height;
+	return `polygon(0% 0%, 0% 100%, ${target.left}px 100%, ${target.left}px ${target.top}px, ${right}px ${target.top}px, ${right}px ${bottom}px, ${target.left}px ${bottom}px, ${target.left}px 100%, 100% 100%, 100% 0%)`;
+}
+export { placeTourCard, tourSpotlightPath };

package/dist/onboarding-tour/tour-controller.d.ts

@@ -0,0 +1,25 @@
+import { type MicroStore } from "../store/micro-store.js";
+import type { CheloneStore } from "../store/store.js";
+/** Where the onboarding tour keeps its done flag in a `CheloneStore`. */
+export declare function onboardingTourKey(id: string): string;
+export interface TourState {
+    active: boolean;
+    index: number;
+}
+export type TourEnd = "finished" | "skipped";
+export interface TourControllerOptions {
+    id: string;
+    stepCount: number;
+    store: CheloneStore;
+    /** Open on the first subscribe while the done flag is not `true`. */
+    autoStart?: boolean;
+    onComplete?: (reason: TourEnd) => void;
+}
+export interface TourController extends MicroStore<TourState> {
+    start(): void;
+    next(): void;
+    back(): void;
+    skip(): void;
+    finish(): void;
+}
+export declare function createTourController({ id, stepCount, store, autoStart, onComplete, }: TourControllerOptions): TourController;

package/dist/onboarding-tour/tour-controller.js

@@ -0,0 +1,50 @@
+import { createMicroStore } from "../store/micro-store.js";
+// src/onboarding-tour/tour-controller.ts
+/** Where the onboarding tour keeps its done flag in a `CheloneStore`. */
+function onboardingTourKey(id) {
+	return `onboarding-tour.${id}.completed`;
+}
+function createTourController({ id, stepCount, store, autoStart = true, onComplete }) {
+	const key = onboardingTourKey(id);
+	const isDone = () => store.getItem(key) === true;
+	const micro = createMicroStore({
+		active: false,
+		index: 0
+	}, { onSubscribed() {
+		const openIfDue = () => {
+			if (autoStart && !isDone() && !micro.getSnapshot().active) start();
+		};
+		openIfDue();
+		return store.subscribe(key, openIfDue);
+	} });
+	function start() {
+		if (stepCount < 1) return;
+		micro.setState({
+			active: true,
+			index: 0
+		});
+	}
+	function end(reason) {
+		if (!micro.getSnapshot().active) return;
+		micro.setState({ active: false });
+		store.setItem(key, true);
+		onComplete?.(reason);
+	}
+	return {
+		...micro,
+		start,
+		next() {
+			const { active, index } = micro.getSnapshot();
+			if (!active) return;
+			if (index >= stepCount - 1) end("finished");
+			else micro.setState({ index: index + 1 });
+		},
+		back() {
+			const { active, index } = micro.getSnapshot();
+			if (active && index > 0) micro.setState({ index: index - 1 });
+		},
+		skip: () => end("skipped"),
+		finish: () => end("finished")
+	};
+}
+export { createTourController, onboardingTourKey };

package/dist/realtime/add-events-for-mutations.js

@@ -1,85 +1,79 @@
 import { copyMembers } from "./copy-members.js";
 import { recordTopic, resourceTopic } from "./topics.js";
+// src/realtime/add-events-for-mutations.ts
+/**
+* Publishes after each successful write, so other clients can refresh. The
+* result waits for the publishes to settle but never fails because of them;
+* a rejected publish goes to `onError`. Returns the type it was given, so a
+* `RealtimeDataProvider` stays one.
+*/
 function addEventsForMutations(base, publisher, { onError } = {}) {
-  const publishAll = async (events) => {
-    await Promise.all(
-      events.map(async ([topic, event]) => {
-        try {
-          await publisher.publish(topic, event);
-        } catch (error) {
-          try {
-            onError?.(error);
-          } catch {
-          }
-        }
-      })
-    );
-  };
-  const manyEvents = (type, resource, ids) => [
-    [resourceTopic(resource), { type, payload: { ids } }],
-    ...ids.map(
-      (id) => [
-        recordTopic(resource, id),
-        { type, payload: { id } }
-      ]
-    )
-  ];
-  const wrapped = {
-    ...copyMembers(base),
-    create: async (resource, params) => {
-      const result = await base.create(resource, params);
-      await publishAll([
-        [
-          resourceTopic(resource),
-          { type: "created", payload: { ids: [result.data.id] } }
-        ]
-      ]);
-      return result;
-    },
-    update: async (resource, params) => {
-      const result = await base.update(resource, params);
-      await publishAll([
-        [
-          recordTopic(resource, params.id),
-          { type: "updated", payload: { id: params.id, data: result.data } }
-        ],
-        [
-          resourceTopic(resource),
-          { type: "updated", payload: { ids: [params.id] } }
-        ]
-      ]);
-      return result;
-    },
-    delete: async (resource, params) => {
-      const result = await base.delete(resource, params);
-      await publishAll([
-        [
-          recordTopic(resource, params.id),
-          {
-            type: "deleted",
-            payload: { id: params.id, previousData: result.data }
-          }
-        ],
-        [
-          resourceTopic(resource),
-          { type: "deleted", payload: { ids: [params.id] } }
-        ]
-      ]);
-      return result;
-    },
-    updateMany: async (resource, params) => {
-      const result = await base.updateMany(resource, params);
-      await publishAll(manyEvents("updated", resource, result.data));
-      return result;
-    },
-    deleteMany: async (resource, params) => {
-      const result = await base.deleteMany(resource, params);
-      await publishAll(manyEvents("deleted", resource, result.data));
-      return result;
-    }
-  };
-  return wrapped;
+	const publishAll = async (events) => {
+		await Promise.all(events.map(async ([topic, event]) => {
+			try {
+				await publisher.publish(topic, event);
+			} catch (error) {
+				try {
+					onError?.(error);
+				} catch {}
+			}
+		}));
+	};
+	const manyEvents = (type, resource, ids) => [[resourceTopic(resource), {
+		type,
+		payload: { ids }
+	}], ...ids.map((id) => [recordTopic(resource, id), {
+		type,
+		payload: { id }
+	}])];
+	return {
+		...copyMembers(base),
+		create: async (resource, params) => {
+			const result = await base.create(resource, params);
+			await publishAll([[resourceTopic(resource), {
+				type: "created",
+				payload: { ids: [result.data.id] }
+			}]]);
+			return result;
+		},
+		update: async (resource, params) => {
+			const result = await base.update(resource, params);
+			await publishAll([[recordTopic(resource, params.id), {
+				type: "updated",
+				payload: {
+					id: params.id,
+					data: result.data
+				}
+			}], [resourceTopic(resource), {
+				type: "updated",
+				payload: { ids: [params.id] }
+			}]]);
+			return result;
+		},
+		delete: async (resource, params) => {
+			const result = await base.delete(resource, params);
+			await publishAll([[recordTopic(resource, params.id), {
+				type: "deleted",
+				payload: {
+					id: params.id,
+					previousData: result.data
+				}
+			}], [resourceTopic(resource), {
+				type: "deleted",
+				payload: { ids: [params.id] }
+			}]]);
+			return result;
+		},
+		updateMany: async (resource, params) => {
+			const result = await base.updateMany(resource, params);
+			await publishAll(manyEvents("updated", resource, result.data));
+			return result;
+		},
+		deleteMany: async (resource, params) => {
+			const result = await base.deleteMany(resource, params);
+			await publishAll(manyEvents("deleted", resource, result.data));
+			return result;
+		}
+	};
 }
-export {
-  addEventsForMutations
-};
+export { addEventsForMutations };

package/dist/realtime/announce-lock.d.ts

@@ -0,0 +1,7 @@
+import type { Lock, RealtimeTransport } from "./types.js";
+/**
+ * Tells a publisher of a lock or an unlock, on the record's and the
+ * resource's topic. A failed publish is swallowed: the lock is already taken
+ * or released, so a failed announcement must not report it as failed.
+ */
+export declare function announceLock(publisher: Pick<RealtimeTransport, "publish"> | undefined, type: "locked" | "unlocked", lock: Lock): Promise<void>;

package/dist/realtime/announce-lock.js

@@ -0,0 +1,18 @@
+import { lockResourceTopic, lockTopic } from "./topics.js";
+// src/realtime/announce-lock.ts
+/**
+* Tells a publisher of a lock or an unlock, on the record's and the
+* resource's topic. A failed publish is swallowed: the lock is already taken
+* or released, so a failed announcement must not report it as failed.
+*/
+async function announceLock(publisher, type, lock) {
+	if (!publisher) return;
+	const event = {
+		type,
+		payload: lock
+	};
+	try {
+		await Promise.all([publisher.publish(lockTopic(lock.resource, lock.recordId), event), publisher.publish(lockResourceTopic(lock.resource), event)]);
+	} catch {}
+}
+export { announceLock };

package/dist/realtime/broadcast-channel-transport.d.ts

@@ -0,0 +1,14 @@
+import type { RealtimeTransport, RealtimeTransportError } from "./types.js";
+export interface BroadcastChannelTransportOptions {
+    /** The channel name; every tab that uses the same name shares events. */
+    channel: string;
+    /** Called for every transport error, like a listener from `onError()`. */
+    onError?: (error: RealtimeTransportError) => void;
+}
+/** A `RealtimeTransport` with every optional member, plus `close()`. */
+export interface BroadcastChannelTransport extends Required<RealtimeTransport> {
+    /** Stops listening, closes the channel and sets `"disconnected"`. */
+    close(): void;
+}
+/** Carries realtime events between the tabs of one browser, with no server. */
+export declare function broadcastChannelTransport({ channel, onError, }: BroadcastChannelTransportOptions): BroadcastChannelTransport;

package/dist/realtime/broadcast-channel-transport.js

@@ -0,0 +1,69 @@
+import { createTopicHub } from "./topic-hub.js";
+// src/realtime/broadcast-channel-transport.ts
+function isEnvelope(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("topic" in value) || typeof value.topic !== "string") return false;
+	if (!("event" in value)) return false;
+	const { event } = value;
+	return typeof event === "object" && event !== null && "type" in event && typeof event.type === "string";
+}
+/** Carries realtime events between the tabs of one browser, with no server. */
+function broadcastChannelTransport({ channel, onError }) {
+	if (typeof BroadcastChannel === "undefined") throw new Error("broadcastChannelTransport needs the global BroadcastChannel, which this environment does not have.");
+	const hub = createTopicHub({ onError });
+	const broadcast = new BroadcastChannel(channel);
+	let closed = false;
+	const onMessage = (message) => {
+		if (!isEnvelope(message.data)) {
+			hub.report({
+				kind: "parse_failed",
+				cause: message.data,
+				retrying: false
+			});
+			return;
+		}
+		const { topic, event } = message.data;
+		hub.dispatch({
+			payload: void 0,
+			...event,
+			topic
+		});
+	};
+	broadcast.addEventListener("message", onMessage);
+	return {
+		subscribe: hub.subscribe,
+		async publish(topic, event) {
+			if (closed) throw new Error("broadcastChannelTransport is closed");
+			try {
+				broadcast.postMessage({
+					topic,
+					event
+				});
+			} catch (cause) {
+				hub.report({
+					kind: "send_failed",
+					topic,
+					cause,
+					retrying: false
+				});
+				throw cause;
+			}
+			hub.dispatch({
+				...event,
+				topic
+			});
+		},
+		onReconnect: hub.onReconnect,
+		onStatusChange: hub.onStatusChange,
+		onError: hub.onError,
+		getStatus: hub.getStatus,
+		close() {
+			if (closed) return;
+			closed = true;
+			broadcast.removeEventListener("message", onMessage);
+			broadcast.close();
+			hub.setStatus("disconnected");
+		}
+	};
+}
+export { broadcastChannelTransport };

package/dist/realtime/copy-members.js

@@ -1,16 +1,24 @@
+// src/realtime/copy-members.ts
+/**
+* A copy of `source` that keeps what a spread drops: methods on the prototype
+* chain of a class instance, bound to `source` so they still see its state.
+*/
 function copyMembers(source) {
-  const copy = { ...source };
-  let proto = Object.getPrototypeOf(source);
-  while (proto && proto !== Object.prototype) {
-    for (const key of Reflect.ownKeys(proto)) {
-      if (key === "constructor" || Object.hasOwn(copy, key)) continue;
-      const { value } = Object.getOwnPropertyDescriptor(proto, key) ?? {};
-      if (typeof value === "function") copy[key] = value.bind(source);
-    }
-    proto = Object.getPrototypeOf(proto);
-  }
-  return copy;
+	const copy = { ...source };
+	let proto = Object.getPrototypeOf(source);
+	while (proto && proto !== Object.prototype) {
+		for (const key of Reflect.ownKeys(proto)) {
+			if (key === "constructor" || Object.hasOwn(copy, key)) continue;
+			const { value } = Object.getOwnPropertyDescriptor(proto, key) ?? {};
+			if (typeof value === "function") Object.defineProperty(copy, key, {
+				value: value.bind(source),
+				writable: true,
+				enumerable: true,
+				configurable: true
+			});
+		}
+		proto = Object.getPrototypeOf(proto);
+	}
+	return copy;
 }
-export {
-  copyMembers
-};
+export { copyMembers };