@kbve/droid 0.0.6 → 0.1.2

package/src/lib/state/sync-bus.ts

@@ -0,0 +1,109 @@
+import {
+	clearProfileCache,
+	setProfileCache,
+	type DroidProfile,
+} from './profile';
+import { clearStaffPermsCache, setStaffPermsCache } from './staff';
+
+const CHANNEL_NAME = 'kbve-droid-sync';
+
+export type SyncBusMessage =
+	| { type: 'profile-refresh'; profile: DroidProfile }
+	| { type: 'profile-clear' }
+	| {
+			type: 'staff-refresh';
+			user_id: string;
+			bitmask: number;
+	  }
+	| { type: 'staff-clear' };
+
+let channel: BroadcastChannel | null = null;
+let installed = false;
+
+function getChannel(): BroadcastChannel | null {
+	if (typeof BroadcastChannel === 'undefined') return null;
+	if (!channel) {
+		try {
+			channel = new BroadcastChannel(CHANNEL_NAME);
+		} catch {
+			channel = null;
+		}
+	}
+	return channel;
+}
+
+/**
+ * Subscribe to cross-context cache refresh messages. The service
+ * worker / shared worker / other tabs can post `SyncBusMessage`
+ * values to update the persistent stores. localStorage `storage`
+ * events already handle cross-tab sync for the persistentAtom
+ * itself; this bus exists so workers (which have no localStorage)
+ * can drive writes through.
+ */
+const noop = (): void => {
+	/* no-op cleanup */
+};
+
+export function installSyncBusListener(): () => void {
+	if (installed) return noop;
+	const bc = getChannel();
+	if (!bc) return noop;
+	installed = true;
+
+	const onMessage = (event: MessageEvent<SyncBusMessage>) => {
+		const msg = event.data;
+		if (!msg || typeof msg !== 'object') return;
+		switch (msg.type) {
+			case 'profile-refresh':
+				if (msg.profile?.user_id) setProfileCache(msg.profile);
+				break;
+			case 'profile-clear':
+				clearProfileCache();
+				break;
+			case 'staff-refresh':
+				if (msg.user_id && typeof msg.bitmask === 'number') {
+					setStaffPermsCache(msg.user_id, msg.bitmask);
+				}
+				break;
+			case 'staff-clear':
+				clearStaffPermsCache();
+				break;
+		}
+	};
+
+	bc.addEventListener('message', onMessage);
+
+	return () => {
+		bc.removeEventListener('message', onMessage);
+		installed = false;
+	};
+}
+
+export function broadcastProfileRefresh(profile: DroidProfile): void {
+	if (!profile?.user_id) return;
+	getChannel()?.postMessage({
+		type: 'profile-refresh',
+		profile,
+	} satisfies SyncBusMessage);
+}
+
+export function broadcastProfileClear(): void {
+	getChannel()?.postMessage({
+		type: 'profile-clear',
+	} satisfies SyncBusMessage);
+}
+
+export function broadcastStaffRefresh(userId: string, bitmask: number): void {
+	if (!userId) return;
+	getChannel()?.postMessage({
+		type: 'staff-refresh',
+		user_id: userId,
+		bitmask,
+	} satisfies SyncBusMessage);
+}
+
+export function broadcastStaffClear(): void {
+	getChannel()?.postMessage({
+		type: 'staff-clear',
+	} satisfies SyncBusMessage);
+}

package/src/lib/state/theme-sync.ts

@@ -0,0 +1,75 @@
+import type { Remote } from 'comlink';
+import type { LocalStorageAPI } from '../workers/db-worker';
+
+const THEME_VARS = [
+	'accent',
+	'accent-low',
+	'accent-high',
+	'bg',
+	'bg-accent',
+	'text',
+	'text-accent',
+	'border',
+	'white',
+	'black',
+] as const;
+
+/**
+ * Read resolved CSS custom property values from the document root
+ * and persist them to Dexie so workers can access theme colors.
+ */
+export async function syncThemeToDexie(
+	api: Remote<LocalStorageAPI>,
+): Promise<void> {
+	const root = document.documentElement;
+	const styles = getComputedStyle(root);
+	const mode = root.dataset['theme'] ?? 'dark';
+
+	await api.dbSet('theme:mode', mode);
+
+	for (const name of THEME_VARS) {
+		const value = styles.getPropertyValue(`--sl-color-${name}`).trim();
+		if (value) {
+			await api.dbSet(`theme:${name}`, value);
+		}
+	}
+}
+
+/**
+ * Broadcast a theme-sync event so workers re-read colors from Dexie.
+ */
+export function broadcastThemeChange(): void {
+	try {
+		const bc = new BroadcastChannel('kbve_theme');
+		bc.postMessage({ type: 'theme-sync', timestamp: Date.now() });
+		bc.close();
+	} catch {
+		// BroadcastChannel not available — workers won't get live updates
+	}
+}
+
+/**
+ * Observe theme attribute changes and auto-sync.
+ * Call once from main() after Dexie is initialized.
+ */
+export function observeThemeChanges(api: Remote<LocalStorageAPI>): void {
+	const observer = new MutationObserver(async (mutations) => {
+		for (const mutation of mutations) {
+			if (
+				mutation.type === 'attributes' &&
+				mutation.attributeName === 'data-theme'
+			) {
+				await syncThemeToDexie(api);
+				broadcastThemeChange();
+			}
+		}
+	});
+
+	observer.observe(document.documentElement, {
+		attributes: true,
+		attributeFilter: ['data-theme'],
+	});
+
+	// Initial sync
+	void syncThemeToDexie(api);
+}

package/src/lib/state/toasts.spec.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { $toasts, addToast, removeToast } from './toasts';
+import { DroidEvents } from '../workers/events';
+import type { ToastPayload } from '../types/ui-event-types';
+
+beforeEach(() => {
+	$toasts.set({});
+	// Reset the toast queue
+	(window as Record<string, unknown>).__kbveToastQueue = undefined;
+});
+
+const makeToast = (
+	id: string,
+	overrides?: Partial<ToastPayload>,
+): ToastPayload => ({
+	id,
+	message: `Toast ${id}`,
+	severity: 'info',
+	...overrides,
+});
+
+describe('addToast', () => {
+	it('adds toast to the nanostore', () => {
+		addToast(makeToast('t1'));
+		expect($toasts.get()).toHaveProperty('t1');
+		expect($toasts.get()['t1'].message).toBe('Toast t1');
+	});
+
+	it('adds multiple toasts', () => {
+		addToast(makeToast('t1'));
+		addToast(makeToast('t2', { severity: 'error' }));
+
+		const state = $toasts.get();
+		expect(Object.keys(state)).toHaveLength(2);
+		expect(state['t2'].severity).toBe('error');
+	});
+
+	it('emits toast-added event', () => {
+		const handler = vi.fn();
+		DroidEvents.on('toast-added', handler);
+
+		const toast = makeToast('t1');
+		addToast(toast);
+
+		expect(handler).toHaveBeenCalledWith(toast);
+		DroidEvents.off('toast-added', handler);
+	});
+
+	it('pushes to the pre-mount queue', () => {
+		addToast(makeToast('t1'));
+
+		const queue = (window as Record<string, unknown>)
+			.__kbveToastQueue as ToastPayload[];
+		expect(queue).toHaveLength(1);
+		expect(queue[0].id).toBe('t1');
+	});
+
+	it('does not push to queue when queue is drained (null)', () => {
+		(window as Record<string, unknown>).__kbveToastQueue = null;
+
+		addToast(makeToast('t1'));
+
+		expect((window as Record<string, unknown>).__kbveToastQueue).toBeNull();
+		// But the nanostore should still have it
+		expect($toasts.get()).toHaveProperty('t1');
+	});
+});
+
+describe('removeToast', () => {
+	it('removes toast from the nanostore', () => {
+		addToast(makeToast('t1'));
+		addToast(makeToast('t2'));
+
+		removeToast('t1');
+
+		expect($toasts.get()).not.toHaveProperty('t1');
+		expect($toasts.get()).toHaveProperty('t2');
+	});
+
+	it('emits toast-removed event', () => {
+		const handler = vi.fn();
+		DroidEvents.on('toast-removed', handler);
+
+		addToast(makeToast('t1'));
+		removeToast('t1');
+
+		expect(handler).toHaveBeenCalledWith({ id: 't1' });
+		DroidEvents.off('toast-removed', handler);
+	});
+
+	it('removes toast from the pre-mount queue', () => {
+		addToast(makeToast('t1'));
+		addToast(makeToast('t2'));
+
+		removeToast('t1');
+
+		const queue = (window as Record<string, unknown>)
+			.__kbveToastQueue as ToastPayload[];
+		expect(queue).toHaveLength(1);
+		expect(queue[0].id).toBe('t2');
+	});
+
+	it('handles removing a non-existent toast gracefully', () => {
+		expect(() => removeToast('non-existent')).not.toThrow();
+	});
+});

package/src/lib/state/toasts.ts

@@ -0,0 +1,34 @@
+import { map } from 'nanostores';
+import { DroidEvents } from '../workers/events';
+import type { ToastPayload } from '../types/ui-event-types';
+
+export const $toasts = map<Record<string, ToastPayload>>({});
+
+// Returns the pre-mount toast buffer, or null if the ToastContainer
+// has already mounted and drained it (future toasts reach the
+// container via nanostores + the CustomEvent bridge instead).
+function getToastQueue(): ToastPayload[] | null {
+	if (window.__kbveToastQueue === null) return null;
+	if (!window.__kbveToastQueue) window.__kbveToastQueue = [];
+	return window.__kbveToastQueue;
+}
+
+export function addToast(payload: ToastPayload): void {
+	$toasts.set({ ...$toasts.get(), [payload.id]: payload });
+	getToastQueue()?.push(payload);
+	DroidEvents.emit('toast-added', payload);
+}
+
+export function removeToast(id: string): void {
+	const current = { ...$toasts.get() };
+	delete current[id];
+	$toasts.set(current);
+
+	const q = getToastQueue();
+	if (q) {
+		const idx = q.findIndex((t) => t.id === id);
+		if (idx !== -1) q.splice(idx, 1);
+	}
+
+	DroidEvents.emit('toast-removed', { id });
+}

package/src/lib/state/ui.spec.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	$activeTooltip,
+	$drawerOpen,
+	$modalId,
+	openTooltip,
+	closeTooltip,
+	openDrawer,
+	closeDrawer,
+	openModal,
+	closeModal,
+} from './ui';
+import { DroidEvents } from '../workers/events';
+
+beforeEach(() => {
+	$activeTooltip.set(null);
+	$drawerOpen.set(false);
+	$modalId.set(null);
+});
+
+describe('Tooltip state', () => {
+	it('openTooltip sets the active tooltip', () => {
+		openTooltip('tip-1');
+		expect($activeTooltip.get()).toBe('tip-1');
+	});
+
+	it('openTooltip emits tooltip-opened event', () => {
+		const handler = vi.fn();
+		DroidEvents.on('tooltip-opened', handler);
+
+		openTooltip('tip-2');
+
+		expect(handler).toHaveBeenCalledWith({ id: 'tip-2' });
+		DroidEvents.off('tooltip-opened', handler);
+	});
+
+	it('closeTooltip clears the active tooltip', () => {
+		openTooltip('tip-1');
+		closeTooltip();
+		expect($activeTooltip.get()).toBeNull();
+	});
+
+	it('closeTooltip emits tooltip-closed event', () => {
+		const handler = vi.fn();
+		DroidEvents.on('tooltip-closed', handler);
+
+		openTooltip('tip-1');
+		closeTooltip();
+
+		expect(handler).toHaveBeenCalledWith({ id: 'tip-1' });
+		DroidEvents.off('tooltip-closed', handler);
+	});
+
+	it('closeTooltip with mismatched id does nothing', () => {
+		openTooltip('tip-1');
+		closeTooltip('tip-2');
+		expect($activeTooltip.get()).toBe('tip-1');
+	});
+
+	it('closeTooltip with matching id clears tooltip', () => {
+		openTooltip('tip-1');
+		closeTooltip('tip-1');
+		expect($activeTooltip.get()).toBeNull();
+	});
+
+	it('closeTooltip does not emit when no tooltip is active', () => {
+		const handler = vi.fn();
+		DroidEvents.on('tooltip-closed', handler);
+
+		closeTooltip();
+
+		expect(handler).not.toHaveBeenCalled();
+		DroidEvents.off('tooltip-closed', handler);
+	});
+});
+
+describe('Drawer state', () => {
+	it('openDrawer sets drawer open and clears tooltip', () => {
+		openTooltip('tip-1');
+		openDrawer();
+		expect($drawerOpen.get()).toBe(true);
+		expect($activeTooltip.get()).toBeNull();
+	});
+
+	it('closeDrawer sets drawer closed', () => {
+		openDrawer();
+		closeDrawer();
+		expect($drawerOpen.get()).toBe(false);
+	});
+});
+
+describe('Modal state', () => {
+	it('openModal sets the modal id', () => {
+		openModal('modal-1');
+		expect($modalId.get()).toBe('modal-1');
+	});
+
+	it('openModal closes drawer and tooltip', () => {
+		openDrawer();
+		openTooltip('tip-1');
+		openModal('modal-1');
+		expect($drawerOpen.get()).toBe(false);
+		expect($activeTooltip.get()).toBeNull();
+	});
+
+	it('openModal emits modal-opened event', () => {
+		const handler = vi.fn();
+		DroidEvents.on('modal-opened', handler);
+
+		openModal('modal-1');
+
+		expect(handler).toHaveBeenCalledWith({ id: 'modal-1' });
+		DroidEvents.off('modal-opened', handler);
+	});
+
+	it('closeModal clears the modal id', () => {
+		openModal('modal-1');
+		closeModal();
+		expect($modalId.get()).toBeNull();
+	});
+
+	it('closeModal emits modal-closed event', () => {
+		const handler = vi.fn();
+		DroidEvents.on('modal-closed', handler);
+
+		openModal('modal-1');
+		closeModal();
+
+		expect(handler).toHaveBeenCalledWith({ id: 'modal-1' });
+		DroidEvents.off('modal-closed', handler);
+	});
+
+	it('closeModal with mismatched id does nothing', () => {
+		openModal('modal-1');
+		closeModal('modal-2');
+		expect($modalId.get()).toBe('modal-1');
+	});
+
+	it('closeModal does not emit when no modal is active', () => {
+		const handler = vi.fn();
+		DroidEvents.on('modal-closed', handler);
+
+		closeModal();
+
+		expect(handler).not.toHaveBeenCalled();
+		DroidEvents.off('modal-closed', handler);
+	});
+});

package/src/lib/state/ui.ts

@@ -0,0 +1,45 @@
+import { atom } from 'nanostores';
+import { DroidEvents } from '../workers/events';
+
+export const $activeTooltip = atom<string | null>(null);
+export const $drawerOpen = atom(false);
+export const $modalId = atom<string | null>(null);
+
+export function openTooltip(id: string) {
+	$activeTooltip.set(id);
+	DroidEvents.emit('tooltip-opened', { id });
+}
+
+export function closeTooltip(id?: string) {
+	if (id && $activeTooltip.get() !== id) return;
+	const closedId = $activeTooltip.get();
+	$activeTooltip.set(null);
+	if (closedId) {
+		DroidEvents.emit('tooltip-closed', { id: closedId });
+	}
+}
+
+export function openDrawer() {
+	$drawerOpen.set(true);
+	$activeTooltip.set(null);
+}
+
+export function closeDrawer() {
+	$drawerOpen.set(false);
+}
+
+export function openModal(id: string) {
+	$modalId.set(id);
+	$drawerOpen.set(false);
+	$activeTooltip.set(null);
+	DroidEvents.emit('modal-opened', { id });
+}
+
+export function closeModal(id?: string) {
+	if (id && $modalId.get() !== id) return;
+	const closedId = $modalId.get();
+	$modalId.set(null);
+	if (closedId) {
+		DroidEvents.emit('modal-closed', { id: closedId });
+	}
+}

package/src/lib/state/welcome-toast.spec.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { showWelcomeToast } from './welcome-toast';
+import { $auth, AuthPresets, resetAuth, setAuth } from './auth';
+import { $toasts } from './toasts';
+
+const SHOWN_KEY = 'kbve:welcome-shown';
+
+beforeEach(() => {
+	sessionStorage.clear();
+	$toasts.set({});
+	$auth.set({
+		tone: 'loading',
+		flags: AuthPresets.LOADING,
+		name: '',
+		username: undefined,
+		avatar: undefined,
+		id: '',
+		error: undefined,
+	});
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+describe('showWelcomeToast', () => {
+	it('emits a "Welcome back, <name>" success toast for an authed user', () => {
+		setAuth({ tone: 'auth', name: 'Alice' });
+		showWelcomeToast();
+		const toasts = Object.values($toasts.get());
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]).toMatchObject({
+			message: 'Welcome back, Alice',
+			severity: 'success',
+		});
+		expect(sessionStorage.getItem(SHOWN_KEY)).toBe('1');
+	});
+
+	it('emits a generic info toast for an anon visitor', () => {
+		setAuth({ tone: 'anon' });
+		showWelcomeToast();
+		const toasts = Object.values($toasts.get());
+		expect(toasts[0]).toMatchObject({
+			message: 'Welcome!',
+			severity: 'info',
+		});
+	});
+
+	it('does not emit twice in the same session', () => {
+		setAuth({ tone: 'anon' });
+		showWelcomeToast();
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(1);
+	});
+
+	it('emits when auth resolves after a delay (subscription path)', () => {
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(0);
+
+		setAuth({ tone: 'auth', name: 'Bob' });
+		const toasts = Object.values($toasts.get());
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]).toMatchObject({ message: 'Welcome back, Bob' });
+	});
+
+	it('falls back to a generic toast after the 10s timeout when auth never resolves', () => {
+		vi.useFakeTimers();
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(0);
+
+		vi.advanceTimersByTime(10_000);
+		const toasts = Object.values($toasts.get());
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]).toMatchObject({
+			message: 'Welcome!',
+			severity: 'info',
+		});
+	});
+
+	it('marks shown without emitting when tone is error', () => {
+		setAuth({ tone: 'error', error: 'boom' });
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(0);
+		expect(sessionStorage.getItem(SHOWN_KEY)).toBe('1');
+	});
+
+	it('treats sessionStorage failures as not-shown without throwing', () => {
+		const original = Storage.prototype.getItem;
+		Storage.prototype.getItem = () => {
+			throw new Error('private mode');
+		};
+		try {
+			expect(() => {
+				resetAuth();
+				showWelcomeToast();
+			}).not.toThrow();
+		} finally {
+			Storage.prototype.getItem = original;
+		}
+	});
+});

package/src/lib/state/welcome-toast.ts

@@ -0,0 +1,76 @@
+import { $auth } from './auth';
+import { addToast } from './toasts';
+
+const SHOWN_KEY = 'kbve:welcome-shown';
+
+function hasShown(): boolean {
+	try {
+		return sessionStorage.getItem(SHOWN_KEY) === '1';
+	} catch {
+		return false;
+	}
+}
+
+function markShown(): void {
+	try {
+		sessionStorage.setItem(SHOWN_KEY, '1');
+	} catch {
+		/* private browsing / storage full */
+	}
+}
+
+export function showWelcomeToast(): void {
+	if (hasShown()) return;
+
+	const tryShow = (): boolean => {
+		const auth = $auth.get();
+		if (auth.tone === 'auth' && auth.name) {
+			markShown();
+			addToast({
+				id: `welcome-${Date.now()}`,
+				message: `Welcome back, ${auth.name}`,
+				severity: 'success',
+				duration: 4000,
+			});
+			return true;
+		}
+		if (auth.tone === 'anon') {
+			markShown();
+			addToast({
+				id: `welcome-${Date.now()}`,
+				message: 'Welcome!',
+				severity: 'info',
+				duration: 3000,
+			});
+			return true;
+		}
+		if (auth.tone === 'error') {
+			markShown();
+			return true;
+		}
+		return false;
+	};
+
+	if (tryShow()) return;
+
+	// Auth still loading — subscribe and wait (10s timeout)
+	const timeoutId = setTimeout(() => {
+		unsub();
+		if (!hasShown()) {
+			markShown();
+			addToast({
+				id: `welcome-${Date.now()}`,
+				message: 'Welcome!',
+				severity: 'info',
+				duration: 3000,
+			});
+		}
+	}, 10_000);
+
+	const unsub = $auth.subscribe(() => {
+		if ($auth.get().tone === 'loading') return;
+		clearTimeout(timeoutId);
+		unsub();
+		tryShow();
+	});
+}