@chelone/core 0.4.0 → 0.6.0

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

@@ -0,0 +1,58 @@
+import { createMicroStore } from "../store/micro-store.js";
+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 },
+    {
+      // The store is only watched while someone is subscribed, so an unmounted
+      // tour does not reopen when its flag is cleared.
+      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/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,15 @@
+import { lockTopic, lockResourceTopic } from "./topics.js";
+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,63 @@
+import { createTopicHub } from "./topic-hub.js";
+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";
+}
+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/in-memory-lock-provider.js

@@ -1,21 +1,10 @@
-import { lockTopic, lockResourceTopic } from "./topics.js";
+import { announceLock } from "./announce-lock.js";
 import { LockConflictError } from "./types.js";
 const storeKey = (resource, id) => JSON.stringify([resource, String(id)]);
 function inMemoryLockProvider({
   publisher
 } = {}) {
   const store = /* @__PURE__ */ new Map();
-  const announce = async (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 {
-    }
-  };
   return {
     async lock(resource, { id, identity }) {
       const key = storeKey(resource, id);
@@ -33,7 +22,7 @@ function inMemoryLockProvider({
         createdAt: (/* @__PURE__ */ new Date()).toISOString()
       };
       store.set(key, lock);
-      await announce("locked", lock);
+      await announceLock(publisher, "locked", lock);
       return lock;
     },
     async unlock(resource, { id, identity }) {
@@ -46,7 +35,7 @@ function inMemoryLockProvider({
         throw new LockConflictError(existing);
       }
       store.delete(key);
-      await announce("unlocked", existing);
+      await announceLock(publisher, "unlocked", existing);
       return existing;
     },
     async getLock(resource, { id }) {

package/dist/realtime/memory-transport.js

@@ -1,66 +1,25 @@
-const addListener = (listeners, listener) => {
-  listeners.add(listener);
-  return () => {
-    listeners.delete(listener);
-  };
-};
+import { createTopicHub } from "./topic-hub.js";
 function memoryTransport({
   delayMs,
   onError
 } = {}) {
-  const subscribers = /* @__PURE__ */ new Map();
+  const hub = createTopicHub({ onError });
   const publishedEvents = [];
-  const reconnectListeners = /* @__PURE__ */ new Set();
-  const statusListeners = /* @__PURE__ */ new Set();
-  const errorListeners = /* @__PURE__ */ new Set();
-  let status = "connected";
-  const report = (error) => {
-    for (const handler of [...onError ? [onError] : [], ...errorListeners]) {
-      try {
-        handler(error);
-      } catch {
-      }
-    }
-  };
   return {
     publishedEvents,
-    subscribe(topic, callback) {
-      const subscription = {
-        callback
-      };
-      const set = subscribers.get(topic) ?? /* @__PURE__ */ new Set();
-      set.add(subscription);
-      subscribers.set(topic, set);
-      return () => {
-        set.delete(subscription);
-      };
-    },
+    subscribe: hub.subscribe,
     async publish(topic, event) {
       const full = { topic, ...event };
       publishedEvents.push(full);
       if (delayMs) await new Promise((resolve) => setTimeout(resolve, delayMs));
-      const live = subscribers.get(topic);
-      for (const subscription of [...live ?? []]) {
-        if (!live?.has(subscription)) continue;
-        const { callback } = subscription;
-        try {
-          callback(full);
-        } catch (cause) {
-          report({ kind: "handler_threw", topic, cause, retrying: false });
-        }
-      }
-    },
-    onReconnect: (callback) => addListener(reconnectListeners, callback),
-    onStatusChange: (callback) => addListener(statusListeners, callback),
-    onError: (callback) => addListener(errorListeners, callback),
-    getStatus: () => status,
-    simulateReconnect() {
-      for (const listener of [...reconnectListeners]) listener();
+      hub.dispatch(full);
     },
-    setStatus(next) {
-      status = next;
-      for (const listener of [...statusListeners]) listener(next);
-    }
+    onReconnect: hub.onReconnect,
+    onStatusChange: hub.onStatusChange,
+    onError: hub.onError,
+    getStatus: hub.getStatus,
+    simulateReconnect: hub.reconnected,
+    setStatus: hub.setStatus
   };
 }
 export {

package/dist/realtime/reconnect-backoff.d.ts

@@ -0,0 +1,15 @@
+export interface RealtimeReconnectConfig {
+    /** Whether a dropped connection is retried. Default `true`. */
+    enabled?: boolean;
+    /** The wait before the first retry. Default 1000. */
+    initialDelayMs?: number;
+    /** The wait never grows past this. Default 30000. */
+    maxDelayMs?: number;
+    /** Retries before giving up. Default `Infinity`. */
+    maxAttempts?: number;
+    /** Share of each wait that is randomised, up or down. Default 0.3. */
+    jitter?: number;
+}
+export declare function resolveReconnectConfig(config?: RealtimeReconnectConfig): Required<RealtimeReconnectConfig>;
+/** The wait before retry number `attempt` (from 0): exponential, capped, then jittered. */
+export declare function reconnectDelay(attempt: number, config: Required<RealtimeReconnectConfig>, random?: () => number): number;

package/dist/realtime/topic-hub.d.ts

@@ -0,0 +1,24 @@
+import type { RealtimeConnectionStatus, RealtimeEvent, RealtimeTransport, RealtimeTransportError } from "./types.js";
+export interface TopicHubOptions {
+    /** Called for every reported error, like a listener from `onError()`. */
+    onError?: (error: RealtimeTransportError) => void;
+}
+/**
+ * The subscriber bookkeeping every transport needs: per-topic subscriptions,
+ * isolated dispatch, and the status, reconnect and error listeners.
+ */
+export interface TopicHub extends Required<Pick<RealtimeTransport, "subscribe" | "onReconnect" | "onStatusChange" | "getStatus" | "onError">> {
+    /** Calls the subscribers of `event.topic`; a throwing one is reported. */
+    dispatch(event: RealtimeEvent): void;
+    /** Whether any subscriber is listening on `topic`. */
+    has(topic: string): boolean;
+    /** Every topic with a subscriber, in the order each was first subscribed. */
+    topics(): string[];
+    /** Calls the `onError` option and every `onError` listener. */
+    report(error: RealtimeTransportError): void;
+    setStatus(status: RealtimeConnectionStatus): void;
+    /** Calls every `onReconnect` listener. */
+    reconnected(): void;
+}
+/** Starts `"connected"`; a transport that connects asynchronously sets its own status. */
+export declare function createTopicHub({ onError }?: TopicHubOptions): TopicHub;

package/dist/realtime/topic-hub.js

@@ -0,0 +1,75 @@
+const addListener = (listeners, listener) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+const isolate = (call) => {
+  try {
+    call();
+  } catch {
+  }
+};
+function createTopicHub({ onError } = {}) {
+  const subscribers = /* @__PURE__ */ new Map();
+  const reconnectListeners = /* @__PURE__ */ new Set();
+  const statusListeners = /* @__PURE__ */ new Set();
+  const errorListeners = /* @__PURE__ */ new Set();
+  let status = "connected";
+  const report = (error) => {
+    for (const listener of [...onError ? [onError] : [], ...errorListeners]) {
+      isolate(() => listener(error));
+    }
+  };
+  return {
+    subscribe(topic, callback) {
+      const subscription = {
+        // type-escape: the hub stores callbacks for any payload; dispatch passes the event on unchanged.
+        callback
+      };
+      const set = subscribers.get(topic) ?? /* @__PURE__ */ new Set();
+      set.add(subscription);
+      subscribers.set(topic, set);
+      return () => {
+        set.delete(subscription);
+        if (set.size === 0 && subscribers.get(topic) === set) {
+          subscribers.delete(topic);
+        }
+      };
+    },
+    dispatch(event) {
+      const live = subscribers.get(event.topic);
+      for (const subscription of [...live ?? []]) {
+        if (!live?.has(subscription)) continue;
+        try {
+          subscription.callback(event);
+        } catch (cause) {
+          report({
+            kind: "handler_threw",
+            topic: event.topic,
+            cause,
+            retrying: false
+          });
+        }
+      }
+    },
+    has: (topic) => subscribers.has(topic),
+    topics: () => [...subscribers.keys()],
+    report,
+    onReconnect: (callback) => addListener(reconnectListeners, callback),
+    onStatusChange: (callback) => addListener(statusListeners, callback),
+    onError: (callback) => addListener(errorListeners, callback),
+    getStatus: () => status,
+    setStatus(next) {
+      status = next;
+      for (const listener of [...statusListeners])
+        isolate(() => listener(next));
+    },
+    reconnected() {
+      for (const listener of [...reconnectListeners]) isolate(listener);
+    }
+  };
+}
+export {
+  createTopicHub
+};

package/dist/rich-text/rich-text.d.ts

@@ -0,0 +1,56 @@
+/** Whether a link `href` is safe to store and render in rich text. */
+export declare function isSafeLinkUrl(url: string): boolean;
+export interface IsSafeImageSrcOptions {
+    /** Allow base64 raster `data:image/*` sources. SVG is never allowed. */
+    allowDataImages?: boolean;
+}
+/** Whether an image `src` is safe to store and render in rich text. */
+export declare function isSafeImageSrc(src: string, options?: IsSafeImageSrcOptions): boolean;
+/** DOMPurify config for stored rich text HTML. Spread it into `sanitize`. */
+export declare const richTextSanitizeOptions: Readonly<{
+    FORBID_TAGS: readonly ["style", "form", "input", "button", "textarea", "select", "iframe", "object", "embed"];
+    FORBID_ATTR: readonly ["style"];
+}>;
+/**
+ * Options for tiptap's `StarterKit.configure`. `isAllowedUri` ignores tiptap's
+ * second argument, so the scheme rule is ours alone.
+ */
+export declare const richTextStarterKitOptions: Readonly<{
+    heading: Readonly<{
+        levels: readonly [1, 2, 3, 4, 5, 6];
+    }>;
+    link: Readonly<{
+        openOnClick: false;
+        autolink: true;
+        defaultProtocol: "https";
+        isAllowedUri: (url: string) => boolean;
+    }>;
+}>;
+export type RichTextToolbarItemId = "bold" | "italic" | "underline" | "strike" | "code" | "clearFormatting" | "link" | "bulletList" | "orderedList" | "blockquote" | "codeBlock" | "horizontalRule" | "undo" | "redo";
+export type RichTextToolbarGroup = "mark" | "insert" | "list" | "block" | "history";
+export interface RichTextToolbarItem {
+    id: RichTextToolbarItemId;
+    group: RichTextToolbarGroup;
+    /** Translation key, always `chelone.rich_text.<id>`. */
+    labelKey: `chelone.rich_text.${RichTextToolbarItemId}`;
+    defaultLabel: string;
+    /** A binding in the syntax of `matchesHotkey`, e.g. `"mod+b"`. */
+    shortcut?: string;
+}
+/**
+ * Every toolbar button, in display order. Adapters map each id to a tiptap
+ * command, so core names no tiptap type. A shortcut is listed only where
+ * tiptap's own keymap binds it, so the adapter wires nothing extra. Link has
+ * none: tiptap binds no key for it, and `mod+k` opens the command menu.
+ */
+export declare const richTextToolbarItems: readonly Readonly<RichTextToolbarItem>[];
+export type RichTextHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export interface RichTextBlockType {
+    id: "paragraph" | `heading${RichTextHeadingLevel}`;
+    /** Set on the heading types. */
+    level?: RichTextHeadingLevel;
+    labelKey: string;
+    defaultLabel: string;
+}
+/** What the block-type select offers: paragraph, then headings 1 to 6. */
+export declare const richTextBlockTypes: readonly Readonly<RichTextBlockType>[];

package/dist/rich-text/rich-text.js

@@ -0,0 +1,105 @@
+const CONTROL = /[\u0000-\u001f\u007f]/g;
+const SCHEME = /^([a-z][a-z0-9+.-]*):/i;
+const LINK_SCHEMES = /* @__PURE__ */ new Set([
+  "http",
+  "https",
+  "mailto",
+  "tel"
+]);
+function normalize(url) {
+  return url.replace(CONTROL, "").trimStart();
+}
+function schemeOf(normalized) {
+  return SCHEME.exec(normalized)?.[1]?.toLowerCase();
+}
+function isSafeLinkUrl(url) {
+  const scheme = schemeOf(normalize(url));
+  return scheme === void 0 || LINK_SCHEMES.has(scheme);
+}
+const IMAGE_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "blob"]);
+const RASTER_DATA_URL = /^data:image\/(?:png|jpeg|gif|webp|avif);base64,/i;
+function isSafeImageSrc(src, options = {}) {
+  const normalized = normalize(src);
+  const scheme = schemeOf(normalized);
+  if (scheme === void 0 || IMAGE_SCHEMES.has(scheme)) return true;
+  return options.allowDataImages === true && RASTER_DATA_URL.test(normalized);
+}
+const richTextSanitizeOptions = Object.freeze({
+  FORBID_TAGS: Object.freeze([
+    "style",
+    "form",
+    "input",
+    "button",
+    "textarea",
+    "select",
+    "iframe",
+    "object",
+    "embed"
+  ]),
+  FORBID_ATTR: Object.freeze(["style"])
+});
+const richTextStarterKitOptions = Object.freeze({
+  heading: Object.freeze({
+    levels: Object.freeze([1, 2, 3, 4, 5, 6])
+  }),
+  link: Object.freeze({
+    openOnClick: false,
+    autolink: true,
+    defaultProtocol: "https",
+    isAllowedUri: (url) => isSafeLinkUrl(url)
+  })
+});
+function item(id, group, defaultLabel, shortcut) {
+  return Object.freeze({
+    id,
+    group,
+    labelKey: `chelone.rich_text.${id}`,
+    defaultLabel,
+    ...shortcut ? { shortcut } : {}
+  });
+}
+const richTextToolbarItems = Object.freeze([
+  item("bold", "mark", "Bold", "mod+b"),
+  item("italic", "mark", "Italic", "mod+i"),
+  item("underline", "mark", "Underline", "mod+u"),
+  item("strike", "mark", "Strikethrough", "mod+shift+s"),
+  item("code", "mark", "Code", "mod+e"),
+  item("clearFormatting", "mark", "Clear formatting"),
+  item("link", "insert", "Link"),
+  item("bulletList", "list", "Bullet list", "mod+shift+8"),
+  item("orderedList", "list", "Ordered list", "mod+shift+7"),
+  item("blockquote", "block", "Blockquote", "mod+shift+b"),
+  item("codeBlock", "block", "Code block", "mod+alt+c"),
+  item("horizontalRule", "insert", "Horizontal rule"),
+  item("undo", "history", "Undo", "mod+z"),
+  item("redo", "history", "Redo", "mod+shift+z")
+]);
+function heading(level) {
+  return Object.freeze({
+    id: `heading${level}`,
+    level,
+    labelKey: `chelone.rich_text.heading_${level}`,
+    defaultLabel: `Heading ${level}`
+  });
+}
+const richTextBlockTypes = Object.freeze([
+  Object.freeze({
+    id: "paragraph",
+    labelKey: "chelone.rich_text.paragraph",
+    defaultLabel: "Paragraph"
+  }),
+  heading(1),
+  heading(2),
+  heading(3),
+  heading(4),
+  heading(5),
+  heading(6)
+]);
+export {
+  isSafeImageSrc,
+  isSafeLinkUrl,
+  richTextBlockTypes,
+  richTextSanitizeOptions,
+  richTextStarterKitOptions,
+  richTextToolbarItems
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chelone/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -44,12 +44,12 @@
     "zod": "^3.25.0"
   },
   "dependencies": {
-    "dot.paths": "^0.2.0"
+    "dot.paths": "^0.2.1"
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.build.json && node ../../scripts/dts-extensions.mjs dist",
     "check:pack": "publint --pack pnpm --strict && d=$(mktemp -d) && trap 'rm -rf $d' EXIT && pnpm pack --pack-destination $d && attw $d/*.tgz --profile esm-only",
     "test": "NODE_OPTIONS=--no-experimental-webstorage vitest run --typecheck",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.es2020.json"
   }
 }