@drakkar.software/octospaces-sdk 0.1.0 → 0.4.3

package/src/utils/live-sync-bus.ts

@@ -0,0 +1,71 @@
+/**
+ * Single dispatch point for live-sync events from a global SSE connection.
+ *
+ * When a server-sent event arrives, the unread/notification layer calls
+ * `dispatchDocChange(docPath)`:
+ *   - if a hook has registered a pull for that path → call it (the user is
+ *     actively viewing that doc) and return `true` — the caller skips the
+ *     unread bump.
+ *   - otherwise return `false` → the caller bumps unread.
+ *
+ * Hooks register/unregister via `registerPull`. SSE connection health is
+ * broadcast via `emitSseStatus` so hooks can gate their fallback polling.
+ *
+ * Call `clearLiveSyncBus()` on account switch to flush all registrations.
+ */
+
+type PullFn = () => void;
+type StatusListener = (up: boolean) => void;
+
+const pullRegistry = new Map<string, PullFn>();
+const statusListeners = new Set<StatusListener>();
+let sseUp = false;
+
+/**
+ * Register a pull function keyed by `docPath`. Returns an unsubscribe
+ * function — call it when the hook unmounts.
+ */
+export function registerPull(docPath: string, fn: PullFn): () => void {
+  pullRegistry.set(docPath, fn);
+  return () => {
+    if (pullRegistry.get(docPath) === fn) pullRegistry.delete(docPath);
+  };
+}
+
+/**
+ * Dispatch a doc-change event. If a pull is registered for `docPath`, calls
+ * it and returns `true`. Returns `false` if no listener is registered
+ * (the caller should bump unread).
+ */
+export function dispatchDocChange(docPath: string): boolean {
+  const pull = pullRegistry.get(docPath);
+  if (!pull) return false;
+  pull();
+  return true;
+}
+
+/** Broadcast the current SSE health to all subscribers. */
+export function emitSseStatus(up: boolean): void {
+  sseUp = up;
+  for (const l of statusListeners) l(up);
+}
+
+/**
+ * Subscribe to SSE health changes. Fires immediately with the current state.
+ * Returns an unsubscribe function.
+ */
+export function onSseStatus(cb: StatusListener): () => void {
+  statusListeners.add(cb);
+  cb(sseUp);
+  return () => statusListeners.delete(cb);
+}
+
+/**
+ * Flush all registered doc pulls and reset SSE health. Call on account
+ * switch. `statusListeners` are React subscriptions that self-unsubscribe on
+ * unmount and are intentionally left intact.
+ */
+export function clearLiveSyncBus(): void {
+  pullRegistry.clear();
+  sseUp = false;
+}

package/src/utils/search-match.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { matchTitle, rankResults, fold, isWordStart } from './search-match.js';
+
+// ── fold ──────────────────────────────────────────────────────────────────────
+
+describe('fold', () => {
+  it('lowercases ASCII', () => expect(fold('Hello World')).toBe('hello world'));
+  it('strips diacritics (é → e, ñ → n)', () => {
+    expect(fold('café')).toBe('cafe');
+    expect(fold('mañana')).toBe('manana');
+  });
+  it('preserves string length after stripping diacritics', () => {
+    const s = 'crêpe';
+    expect(fold(s).length).toBe(s.length);
+  });
+  it('passes through surrogate pairs unchanged', () => {
+    const emoji = '🐙notes';
+    expect(fold(emoji).length).toBe(emoji.length);
+  });
+});
+
+// ── isWordStart ───────────────────────────────────────────────────────────────
+
+describe('isWordStart', () => {
+  it('position 0 is always a word start', () => expect(isWordStart('hello', 0)).toBe(true));
+  it('letter after a space is a word start', () => expect(isWordStart('hello world', 6)).toBe(true));
+  it('letter after another letter is not', () => expect(isWordStart('hello', 2)).toBe(false));
+  it('letter after a dash is a word start', () => expect(isWordStart('hello-world', 6)).toBe(true));
+});
+
+// ── matchTitle tiers ──────────────────────────────────────────────────────────
+
+describe('matchTitle', () => {
+  it('returns null for empty query', () => expect(matchTitle('', 'Notes')).toBeNull());
+  it('returns null on a miss', () => expect(matchTitle('xyz', 'Notes')).toBeNull());
+
+  it('PREFIX tier — title starts with query', () => {
+    const m = matchTitle('not', 'Notes');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(3900);
+    expect(m!.ranges).toEqual([{ start: 0, end: 3 }]);
+  });
+
+  it('WORD tier — query matches at a word boundary', () => {
+    const m = matchTitle('pa', 'New page');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(2900);
+    expect(m!.score).toBeLessThan(4000);
+    expect(m!.ranges[0]!.start).toBe(4); // 'p' in "page"
+  });
+
+  it('SUBSTRING tier — query appears mid-word', () => {
+    const m = matchTitle('page', 'Homepage');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(1900);
+    expect(m!.score).toBeLessThan(3000);
+  });
+
+  it('FUZZY tier — query is a subsequence', () => {
+    const m = matchTitle('rdm', 'Roadmap');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(900);
+    expect(m!.score).toBeLessThan(2000);
+  });
+
+  it('PREFIX beats WORD beats SUBSTRING beats FUZZY', () => {
+    const prefix = matchTitle('no', 'Notes')!.score;
+    const word = matchTitle('pa', 'New page')!.score;
+    const substr = matchTitle('age', 'Homepage')!.score;
+    const fuzzy = matchTitle('rdm', 'Roadmap')!.score;
+    expect(prefix).toBeGreaterThan(word);
+    expect(word).toBeGreaterThan(substr);
+    expect(substr).toBeGreaterThan(fuzzy);
+  });
+
+  it('match is case-insensitive', () => {
+    expect(matchTitle('NOTE', 'notes')).not.toBeNull();
+    expect(matchTitle('note', 'NOTES')).not.toBeNull();
+  });
+
+  it('match is diacritic-insensitive', () => {
+    expect(matchTitle('cafe', 'café au lait')).not.toBeNull();
+    expect(matchTitle('creme', 'crème brûlée')).not.toBeNull();
+  });
+
+  it('fuzzy: spaces in query are ignored', () => {
+    expect(matchTitle('new pg', 'New page')).not.toBeNull();
+  });
+
+  it('fuzzy: adjacent hits merge into one range', () => {
+    const m = matchTitle('ab', 'xaby');
+    expect(m).not.toBeNull();
+    // 'ab' appears at position 1 as a substring; but if it fell through to fuzzy
+    // the two chars 'a' and 'b' at positions 1 and 2 would be one merged range.
+    expect(m!.ranges.length).toBe(1);
+  });
+
+  it('range spans index into original title (not folded)', () => {
+    const title = 'New Page';
+    const m = matchTitle('pa', title);
+    expect(m).not.toBeNull();
+    const { start, end } = m!.ranges[0]!;
+    expect(title.slice(start, end).toLowerCase()).toBe('pa');
+  });
+});
+
+// ── rankResults ───────────────────────────────────────────────────────────────
+
+const NOW = 1_700_000_000_000;
+
+function item(title: string, updatedAt = NOW) {
+  return { title, updatedAt };
+}
+
+describe('rankResults', () => {
+  it('returns empty array for empty list', () => {
+    expect(rankResults('test', [])).toEqual([]);
+  });
+
+  it('drops items that do not match', () => {
+    const results = rankResults('xyz', [item('Notes'), item('Roadmap')]);
+    expect(results).toHaveLength(0);
+  });
+
+  it('higher-tier match comes first', () => {
+    // "Notes" is a prefix match for "not"; "Homepage" is only a substring match
+    const results = rankResults('not', [item('Homepage notation'), item('Notes')]);
+    expect(results[0]!.item.title).toBe('Notes');
+  });
+
+  it('recency breaks score ties', () => {
+    const old = item('Notes', NOW - 10_000);
+    const recent = item('Notes', NOW);
+    const results = rankResults('not', [old, recent]);
+    expect(results[0]!.item).toBe(recent);
+  });
+
+  it('respects limit', () => {
+    const items = Array.from({ length: 10 }, (_, i) => item(`note ${i}`));
+    const results = rankResults('note', items, 3);
+    expect(results).toHaveLength(3);
+  });
+
+  it('each result carries score and ranges', () => {
+    const results = rankResults('note', [item('Notes')]);
+    expect(results[0]!.score).toBeGreaterThan(0);
+    expect(results[0]!.ranges.length).toBeGreaterThan(0);
+  });
+});

package/src/utils/search-match.ts

@@ -0,0 +1,145 @@
+/**
+ * Pure title matcher + ranker for Quick Find / Search. No React, no I/O.
+ *
+ * Relevance is tiered the way a human reads a match, strongest first:
+ *
+ *   1. PREFIX        — the title starts with the query ("not" → "Notes").
+ *   2. WORD boundary — some word starts with the query ("pa" → "New page").
+ *   3. SUBSTRING     — the query appears mid-word ("page" → "Homepage").
+ *   4. FUZZY         — the query is a subsequence ("rdm" → "Roadmap").
+ *
+ * Within a tier, earlier and tighter matches in shorter titles score higher;
+ * tier gaps are wider than any intra-tier penalty, so a fuzzy hit can never
+ * outrank a real substring. Ties (same score) fall back to `updatedAt` DESC in
+ * {@link rankResults} — between two objects named "Notes", the one touched last
+ * is almost always the one wanted.
+ *
+ * Matching is case- and diacritic-insensitive via a per-UTF-16-unit fold that
+ * PRESERVES STRING LENGTH, so the returned ranges index straight into the
+ * ORIGINAL title for highlight rendering.
+ */
+
+/** Half-open [start, end) span into the original title. */
+export interface MatchRange {
+  start: number;
+  end: number;
+}
+
+export interface TitleMatch {
+  score: number;
+  ranges: MatchRange[];
+}
+
+// Tier bases. Gaps (1000) exceed the max intra-tier penalty (≤900), keeping
+// tiers strictly ordered no matter the inputs.
+const TIER_PREFIX = 4000;
+const TIER_WORD = 3000;
+const TIER_SUBSTRING = 2000;
+const TIER_FUZZY = 1000;
+
+/**
+ * Lowercase + strip diacritics WITHOUT changing length: each UTF-16 unit maps
+ * to exactly one folded unit (NFD base char, first lowercase unit). Surrogate
+ * halves pass through unchanged — they can't match an ASCII query, which is
+ * exactly right for emoji-bearing titles.
+ */
+export function fold(s: string): string {
+  let out = '';
+  for (let i = 0; i < s.length; i++) {
+    const base = s[i]!.normalize('NFD')[0]!;
+    const lower = base.toLowerCase();
+    // Some locale-specific lowercasings expand (e.g. 'İ' → 'i̇'); keep unit 0.
+    out += lower.length === 1 ? lower : lower[0]!;
+  }
+  return out;
+}
+
+/** A word starts where the previous folded char is not alphanumeric. */
+export function isWordStart(folded: string, i: number): boolean {
+  if (i === 0) return true;
+  return !/[a-z0-9]/.test(folded[i - 1]!);
+}
+
+const startPenalty = (i: number) => Math.min(i * 8, 600);
+const lengthPenalty = (titleLen: number, queryLen: number) => Math.min(Math.max(titleLen - queryLen, 0), 100);
+
+/**
+ * Match one title against a query. Returns `null` for an empty query or a miss.
+ * Ranges cover every highlighted span (one for contiguous tiers, several merged
+ * runs for fuzzy).
+ */
+export function matchTitle(query: string, title: string): TitleMatch | null {
+  const q = fold(query.trim());
+  if (!q) return null;
+  const t = fold(title);
+
+  let first = -1;
+  let wordAt = -1;
+  for (let i = t.indexOf(q); i !== -1; i = t.indexOf(q, i + 1)) {
+    if (first === -1) first = i;
+    if (isWordStart(t, i)) {
+      wordAt = i;
+      break;
+    }
+  }
+
+  if (first === 0) {
+    return { score: TIER_PREFIX - lengthPenalty(t.length, q.length), ranges: [{ start: 0, end: q.length }] };
+  }
+  if (wordAt !== -1) {
+    return {
+      score: TIER_WORD - startPenalty(wordAt) - lengthPenalty(t.length, q.length),
+      ranges: [{ start: wordAt, end: wordAt + q.length }],
+    };
+  }
+  if (first !== -1) {
+    return {
+      score: TIER_SUBSTRING - startPenalty(first) - lengthPenalty(t.length, q.length),
+      ranges: [{ start: first, end: first + q.length }],
+    };
+  }
+
+  // Fuzzy subsequence (greedy left-to-right). Whitespace in the query is
+  // skipped so "new pg" can still reach "New page". Adjacent hits merge into
+  // one range so the highlight reads as runs, not confetti.
+  const chars = q.replace(/\s+/g, '');
+  if (!chars) return null;
+  const ranges: MatchRange[] = [];
+  let from = 0;
+  for (let ci = 0; ci < chars.length; ci++) {
+    const at = t.indexOf(chars[ci]!, from);
+    if (at === -1) return null;
+    const last = ranges[ranges.length - 1];
+    if (last && last.end === at) last.end = at + 1;
+    else ranges.push({ start: at, end: at + 1 });
+    from = at + 1;
+  }
+  const firstHit = ranges[0]!.start;
+  const spread = ranges[ranges.length - 1]!.end - firstHit - chars.length;
+  const score = TIER_FUZZY - Math.min(spread * 8, 600) - Math.min(firstHit * 2, 200) - lengthPenalty(t.length, chars.length);
+  return { score, ranges };
+}
+
+export interface RankedResult<T> {
+  item: T;
+  score: number;
+  ranges: MatchRange[];
+}
+
+/**
+ * Rank a candidate list against a query: score every title, drop misses, sort
+ * by score DESC then `updatedAt` DESC (recency breaks ties), cap at `limit`.
+ */
+export function rankResults<T extends { title: string; updatedAt: number }>(
+  query: string,
+  items: readonly T[],
+  limit = 50,
+): RankedResult<T>[] {
+  const out: RankedResult<T>[] = [];
+  for (const item of items) {
+    const m = matchTitle(query, item.title);
+    if (m) out.push({ item, score: m.score, ranges: m.ranges });
+  }
+  out.sort((a, b) => b.score - a.score || b.item.updatedAt - a.item.updatedAt);
+  return out.slice(0, limit);
+}