birdclaw 0.8.1 → 0.8.3

package/src/components/network-map-model.ts

@@ -0,0 +1,255 @@
+import type * as GeoJSON from "geojson";
+import Supercluster from "supercluster";
+import type { NetworkMapKind, NetworkMapResponse } from "#/lib/network-map";
+
+export type ReactMapboxModule = typeof import("react-map-gl/mapbox");
+export type MapFeature = NetworkMapResponse["features"][number];
+export type MapBounds = [number, number, number, number];
+
+export interface ClusterPointProperties {
+	featureIndex: number;
+	handle: string;
+	name: string;
+	avatarUrl: string | null;
+	relationship: MapFeature["properties"]["relationship"];
+	followersCount: number;
+}
+
+export interface ClusterAggregateProperties {
+	followers: number;
+	following: number;
+	mutual: number;
+}
+
+export interface ClusterFeatureProperties extends ClusterAggregateProperties {
+	cluster: true;
+	cluster_id: number;
+	point_count: number;
+	point_count_abbreviated: string | number;
+}
+
+export type ClusterPointFeature = GeoJSON.Feature<
+	GeoJSON.Point,
+	ClusterPointProperties
+>;
+export type ClusterFeature = GeoJSON.Feature<
+	GeoJSON.Point,
+	ClusterFeatureProperties
+>;
+export type ClusterResult = ClusterPointFeature | ClusterFeature;
+export type MapViewport = { bounds: MapBounds; zoom: number };
+export type MapTarget = {
+	getBounds: () => {
+		getWest: () => number;
+		getSouth: () => number;
+		getEast: () => number;
+		getNorth: () => number;
+	};
+	getZoom: () => number;
+};
+
+export type SelectedOverlay =
+	| { kind: "profile"; feature: MapFeature }
+	| {
+			kind: "cluster";
+			coordinates: [number, number];
+			count: number;
+			features: MapFeature[];
+			stats: ClusterAggregateProperties;
+	  };
+
+export const CLUSTER_LEAF_SAMPLE_SIZE = 48;
+
+export const MAP_TYPES: Array<{ value: NetworkMapKind; label: string }> = [
+	{ value: "all", label: "All" },
+	{ value: "followers", label: "Followers" },
+	{ value: "following", label: "Following" },
+	{ value: "mutual", label: "Mutual" },
+];
+
+export const WORLD_BOUNDS: MapBounds = [-180, -85, 180, 85];
+export const WORLD_VIEWPORT: MapViewport = { bounds: WORLD_BOUNDS, zoom: 1.15 };
+
+export async function fetchMap(
+	type: NetworkMapKind,
+	refresh: boolean,
+	accountId?: string,
+	signal?: AbortSignal,
+) {
+	const url = new URL("/api/network-map", window.location.origin);
+	url.searchParams.set("type", type);
+	url.searchParams.set("limit", "50000");
+	url.searchParams.set("geocodeLimit", refresh ? "80" : "12");
+	if (accountId) url.searchParams.set("account", accountId);
+	if (refresh) url.searchParams.set("refresh", "true");
+	const response = await fetch(url, { signal });
+	if (!response.ok) {
+		throw new Error(`Map request failed (${String(response.status)})`);
+	}
+	return (await response.json()) as NetworkMapResponse;
+}
+
+export function formatNumber(value: number) {
+	return new Intl.NumberFormat().format(value);
+}
+
+export function formatRelationship(
+	value: MapFeature["properties"]["relationship"],
+) {
+	if (value === "mutual") return "mutual";
+	if (value === "following") return "following";
+	return "follower";
+}
+
+export function relationshipColor(
+	relationship: MapFeature["properties"]["relationship"],
+) {
+	if (relationship === "mutual") return "#22c55e";
+	if (relationship === "following") return "#f59e0b";
+	return "#1d9bf0";
+}
+
+export function avatarInitial(feature: MapFeature) {
+	return (feature.properties.name || feature.properties.handle || "?")
+		.slice(0, 1)
+		.toUpperCase();
+}
+
+export function avatarPath(feature: MapFeature) {
+	if (!feature.properties.avatarUrl) return null;
+	const query = new URLSearchParams({
+		profileId: feature.properties.profileId,
+		v: feature.properties.avatarUrl,
+	});
+	return `/api/avatar?${query.toString()}`;
+}
+
+export function clusterGradient(stats: ClusterAggregateProperties) {
+	const total = Math.max(1, stats.followers + stats.following + stats.mutual);
+	const mutual = (stats.mutual / total) * 100;
+	const following = mutual + (stats.following / total) * 100;
+	return `conic-gradient(#22c55e 0 ${mutual}%, #f59e0b ${mutual}% ${following}%, #1d9bf0 ${following}% 100%)`;
+}
+
+export function buildClusterIndex(features: MapFeature[]) {
+	const points: ClusterPointFeature[] = features.map(
+		(feature, featureIndex) => ({
+			type: "Feature",
+			geometry: feature.geometry,
+			properties: {
+				featureIndex,
+				handle: feature.properties.handle,
+				name: feature.properties.name,
+				avatarUrl: feature.properties.avatarUrl,
+				relationship: feature.properties.relationship,
+				followersCount: feature.properties.followersCount,
+			},
+		}),
+	);
+	return new Supercluster<ClusterPointProperties, ClusterAggregateProperties>({
+		maxZoom: 18,
+		minPoints: 2,
+		radius: 64,
+		map: (props) => ({
+			followers: props.relationship === "followers" ? 1 : 0,
+			following: props.relationship === "following" ? 1 : 0,
+			mutual: props.relationship === "mutual" ? 1 : 0,
+		}),
+		reduce: (accumulated, props) => {
+			accumulated.followers += props.followers;
+			accumulated.following += props.following;
+			accumulated.mutual += props.mutual;
+		},
+	}).load(points);
+}
+
+export function isCluster(item: ClusterResult): item is ClusterFeature {
+	return "cluster" in item.properties && item.properties.cluster === true;
+}
+
+export function compareClusterFeatures(a: MapFeature, b: MapFeature) {
+	return (
+		b.properties.followersCount - a.properties.followersCount ||
+		a.properties.handle.localeCompare(b.properties.handle)
+	);
+}
+
+export function getClusterDisplayAnchor(
+	features: MapFeature[],
+	fallback: [number, number],
+): [number, number] {
+	const buckets = new Map<
+		string,
+		{ coordinates: [number, number]; count: number; followers: number }
+	>();
+	for (const feature of features) {
+		const [lng, lat] = feature.geometry.coordinates;
+		const key = `${lng.toFixed(4)},${lat.toFixed(4)}`;
+		const existing = buckets.get(key);
+		if (existing) {
+			existing.count += 1;
+			existing.followers += feature.properties.followersCount;
+		} else {
+			buckets.set(key, {
+				coordinates: [lng, lat],
+				count: 1,
+				followers: feature.properties.followersCount,
+			});
+		}
+	}
+	const best = [...buckets.values()].sort(
+		(a, b) => b.count - a.count || b.followers - a.followers,
+	)[0];
+	return best?.coordinates ?? fallback;
+}
+
+export function readViewport(target: unknown): MapViewport | null {
+	if (!target || typeof target !== "object") return null;
+	const map = target as Partial<MapTarget>;
+	if (
+		typeof map.getBounds !== "function" ||
+		typeof map.getZoom !== "function"
+	) {
+		return null;
+	}
+	const bounds = map.getBounds();
+	return {
+		bounds: [
+			bounds.getWest(),
+			bounds.getSouth(),
+			bounds.getEast(),
+			bounds.getNorth(),
+		],
+		zoom: map.getZoom(),
+	};
+}
+
+export function boundsContainFeature(bounds: MapBounds, feature: MapFeature) {
+	const [west, south, east, north] = bounds;
+	const [lng, lat] = feature.geometry.coordinates;
+	const normalizedWest = ((west + 540) % 360) - 180;
+	const normalizedEast = ((east + 540) % 360) - 180;
+	const inLatitude = lat >= Math.max(-85, south) && lat <= Math.min(85, north);
+	const inLongitude =
+		east - west >= 360
+			? true
+			: normalizedWest <= normalizedEast
+				? lng >= normalizedWest && lng <= normalizedEast
+				: lng >= normalizedWest || lng <= normalizedEast;
+	return inLatitude && inLongitude;
+}
+
+export function featureMatchesSearch(feature: MapFeature, search: string) {
+	const needle = search.trim().toLowerCase();
+	if (!needle) return true;
+	return [
+		feature.properties.name,
+		feature.properties.handle,
+		feature.properties.location,
+		feature.properties.resolvedLocation ?? "",
+		formatRelationship(feature.properties.relationship),
+	]
+		.join(" ")
+		.toLowerCase()
+		.includes(needle);
+}

package/src/components/useDebouncedValue.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react";
+
+export function useDebouncedValue<T>(value: T, delayMs: number) {
+	const [debouncedValue, setDebouncedValue] = useState(value);
+
+	useEffect(() => {
+		const timeout = window.setTimeout(() => setDebouncedValue(value), delayMs);
+		return () => window.clearTimeout(timeout);
+	}, [delayMs, value]);
+
+	return debouncedValue;
+}

package/src/components/useTimelineRouteData.ts

@@ -1,18 +1,22 @@
-import { useEffect, useRef, useState } from "react";
-import type {
-	QueryEnvelope,
-	ReplyFilter,
-	ResourceKind,
-	TimelineItem,
-} from "#/lib/types";
+import {
+	useInfiniteQuery,
+	useMutation,
+	useQuery,
+	useQueryClient,
+} from "@tanstack/react-query";
+import { useMemo } from "react";
 import {
 	fetchQueryEnvelope,
 	fetchQueryResponse,
 	postAction,
 } from "#/lib/api-client";
+import { queryKeys } from "#/lib/query-client";
+import type { ReplyFilter, ResourceKind, TimelineItem } from "#/lib/types";
 import { useSelectedAccountId } from "./account-selection";
+import { useDebouncedValue } from "./useDebouncedValue";
 
 const PAGE_SIZE = 50;
+const TIMELINE_STALE_TIME_MS = 5 * 60_000;
 
 interface UseTimelineRouteDataOptions {
 	resource: Exclude<ResourceKind, "dms">;
@@ -23,6 +27,49 @@ interface UseTimelineRouteDataOptions {
 	bookmarkedOnly?: boolean;
 }
 
+interface TimelinePageParam {
+	until: string;
+	untilId: string;
+}
+
+function buildTimelineQueryUrl({
+	resource,
+	search,
+	replyFilter,
+	likedOnly,
+	bookmarkedOnly,
+	selectedAccountId,
+	pageParam,
+}: {
+	resource: Exclude<ResourceKind, "dms">;
+	search: string;
+	replyFilter?: ReplyFilter;
+	likedOnly: boolean;
+	bookmarkedOnly: boolean;
+	selectedAccountId?: string;
+	pageParam?: TimelinePageParam;
+}) {
+	const params = new URLSearchParams({
+		resource,
+		limit: String(PAGE_SIZE),
+	});
+	if (selectedAccountId) params.set("account", selectedAccountId);
+	if (replyFilter) params.set("replyFilter", replyFilter);
+	if (likedOnly) params.set("liked", "true");
+	if (bookmarkedOnly) params.set("bookmarked", "true");
+	if (search.trim()) params.set("search", search.trim());
+	if (pageParam) {
+		params.set("until", pageParam.until);
+		params.set("untilId", pageParam.untilId);
+	}
+	params.sort();
+	const base =
+		typeof window === "undefined"
+			? "http://birdclaw.local"
+			: window.location.origin;
+	return new URL(`/api/query?${params.toString()}`, base).toString();
+}
+
 export function useTimelineRouteData({
 	resource,
 	search,
@@ -31,191 +78,116 @@ export function useTimelineRouteData({
 	likedOnly = false,
 	bookmarkedOnly = false,
 }: UseTimelineRouteDataOptions) {
-	const [meta, setMeta] = useState<QueryEnvelope | null>(null);
-	const [items, setItems] = useState<TimelineItem[]>([]);
-	const [loading, setLoading] = useState(true);
-	const [error, setError] = useState<string | null>(null);
-	const [replyError, setReplyError] = useState<string | null>(null);
-	const [refreshTick, setRefreshTick] = useState(0);
-	const [hasMore, setHasMore] = useState(false);
-	const [loadingMore, setLoadingMore] = useState(false);
+	const queryClient = useQueryClient();
+	const statusQuery = useQuery({
+		queryKey: queryKeys.status,
+		queryFn: ({ signal }) => fetchQueryEnvelope({ signal }),
+	});
+	const meta = statusQuery.data ?? null;
 	const selectedAccountId = useSelectedAccountId(meta?.accounts);
-	// Bumped whenever the active filters change. A `loadMore` request that
-	// resolves against a stale generation is discarded so its older page is
-	// never appended to a freshly loaded feed.
-	const generationRef = useRef(0);
-	const loadMoreControllerRef = useRef<AbortController | null>(null);
-
-	async function loadStatus() {
-		setMeta(await fetchQueryEnvelope());
-	}
-
-	useEffect(() => {
-		void loadStatus();
-	}, []);
-
-	// Build the /api/query URL for the current filters. Passing the last item's
-	// (createdAt, id) requests the next (older) page via the server's keyset
-	// cursor, which is deterministic across duplicate timestamps.
-	function buildQueryUrl(until?: string, untilId?: string) {
-		const url = new URL("/api/query", window.location.origin);
-		url.searchParams.set("resource", resource);
-		url.searchParams.set("refresh", String(refreshTick));
-		url.searchParams.set("limit", String(PAGE_SIZE));
-		if (selectedAccountId) {
-			url.searchParams.set("account", selectedAccountId);
-		}
-		if (replyFilter) {
-			url.searchParams.set("replyFilter", replyFilter);
-		}
-		if (likedOnly) {
-			url.searchParams.set("liked", "true");
-		}
-		if (bookmarkedOnly) {
-			url.searchParams.set("bookmarked", "true");
-		}
-		if (search.trim()) {
-			url.searchParams.set("search", search.trim());
-		}
-		if (until) {
-			url.searchParams.set("until", until);
-		}
-		if (untilId) {
-			url.searchParams.set("untilId", untilId);
-		}
-		return url;
-	}
-
-	useEffect(() => {
-		generationRef.current += 1;
-		loadMoreControllerRef.current?.abort();
-		const controller = new AbortController();
-		let active = true;
-		setError(null);
-		setLoading(true);
-		setLoadingMore(false);
-		fetchQueryResponse(buildQueryUrl(), { signal: controller.signal })
-			.then((data) => {
-				if (!active) return;
-				const next = data.items as TimelineItem[];
-				setItems(next);
-				setHasMore(next.length >= PAGE_SIZE);
-			})
-			.catch((fetchError: unknown) => {
-				if (
-					fetchError instanceof DOMException &&
-					fetchError.name === "AbortError"
-				) {
-					return;
-				}
-				if (!active) return;
-				setError(
-					fetchError instanceof Error ? fetchError.message : errorFallback,
-				);
-				setItems([]);
-				setHasMore(false);
-			})
-			.finally(() => {
-				if (active) {
-					setLoading(false);
-				}
-			});
-
-		return () => {
-			active = false;
-			controller.abort();
-		};
-	}, [
-		bookmarkedOnly,
-		errorFallback,
-		likedOnly,
-		refreshTick,
-		replyFilter,
-		resource,
-		search,
-		selectedAccountId,
-	]);
-
-	async function loadMore() {
-		if (loading || loadingMore || !hasMore || items.length === 0) return;
-		const lastItem = items[items.length - 1];
-		const until = lastItem?.createdAt;
-		const untilId = lastItem?.id;
-		if (!until || !untilId) return;
-		const generation = generationRef.current;
-		const controller = new AbortController();
-		loadMoreControllerRef.current = controller;
-		setLoadingMore(true);
-		try {
-			const data = await fetchQueryResponse(buildQueryUrl(until, untilId), {
-				signal: controller.signal,
-			});
-			// Discard if the filters changed (new generation) while in flight.
-			if (generation !== generationRef.current) return;
-			const page = data.items as TimelineItem[];
-			setItems((prev) => {
-				const seen = new Set(prev.map((item) => item.id));
-				return [...prev, ...page.filter((item) => !seen.has(item.id))];
-			});
-			setHasMore(page.length >= PAGE_SIZE);
-		} catch (loadError) {
-			if (
-				loadError instanceof DOMException &&
-				loadError.name === "AbortError"
-			) {
-				return;
-			}
-			if (generation !== generationRef.current) return;
-			setError(loadError instanceof Error ? loadError.message : errorFallback);
-		} finally {
-			if (generation === generationRef.current) {
-				setLoadingMore(false);
+	const debouncedSearch = useDebouncedValue(search, 180);
+	const timelineQueryKey = [
+		...queryKeys.timelines,
+		{
+			resource,
+			search: debouncedSearch,
+			replyFilter: replyFilter ?? "all",
+			likedOnly,
+			bookmarkedOnly,
+			selectedAccountId: selectedAccountId ?? null,
+		},
+	] as const;
+	const timelineQuery = useInfiniteQuery({
+		queryKey: timelineQueryKey,
+		initialPageParam: undefined as TimelinePageParam | undefined,
+		queryFn: ({ pageParam, signal }) =>
+			fetchQueryResponse(
+				buildTimelineQueryUrl({
+					resource,
+					search: debouncedSearch,
+					replyFilter,
+					likedOnly,
+					bookmarkedOnly,
+					selectedAccountId,
+					pageParam,
+				}),
+				{ signal },
+			),
+		getNextPageParam: (lastPage) => {
+			const items = lastPage.items as TimelineItem[];
+			const lastItem = items.at(-1);
+			return items.length >= PAGE_SIZE && lastItem
+				? { until: lastItem.createdAt, untilId: lastItem.id }
+				: undefined;
+		},
+		staleTime: TIMELINE_STALE_TIME_MS,
+	});
+	const items = useMemo(() => {
+		const seen = new Set<string>();
+		const merged: TimelineItem[] = [];
+		for (const page of timelineQuery.data?.pages ?? []) {
+			for (const item of page.items as TimelineItem[]) {
+				if (seen.has(item.id)) continue;
+				seen.add(item.id);
+				merged.push(item);
 			}
 		}
-	}
+		return merged;
+	}, [timelineQuery.data]);
+	const replyMutation = useMutation({
+		mutationFn: ({ tweetId, text }: { tweetId: string; text: string }) =>
+			postAction({
+				kind: "replyTweet",
+				accountId: selectedAccountId ?? "acct_primary",
+				tweetId,
+				text,
+			}),
+		onSuccess: () =>
+			queryClient.invalidateQueries({ queryKey: timelineQueryKey }),
+	});
 
 	function retry() {
-		setRefreshTick((value) => value + 1);
+		void timelineQuery.refetch();
 	}
 
 	function refreshLocalView() {
-		setRefreshTick((value) => value + 1);
-		void loadStatus();
+		void Promise.all([
+			queryClient.invalidateQueries({ queryKey: queryKeys.timelines }),
+			queryClient.invalidateQueries({ queryKey: queryKeys.status }),
+		]);
 	}
 
 	async function replyToTweet(tweetId: string) {
 		const text = window.prompt("Reply text");
 		if (!text?.trim()) return;
-
-		setReplyError(null);
-		try {
-			await postAction({
-				kind: "replyTweet",
-				accountId: selectedAccountId ?? "acct_primary",
-				tweetId,
-				text,
+		await replyMutation
+			.mutateAsync({ tweetId, text: text.trim() })
+			.catch(() => {
+				// The mutation error is exposed below for the route frame.
 			});
-
-			retry();
-		} catch (replyError) {
-			setReplyError(
-				replyError instanceof Error ? replyError.message : "Reply failed",
-			);
-		}
 	}
 
+	const queryError = timelineQuery.error;
 	return {
 		meta,
 		items,
-		loading,
-		error,
-		replyError,
+		loading: timelineQuery.isPending,
+		error: queryError
+			? queryError instanceof Error
+				? queryError.message
+				: errorFallback
+			: null,
+		replyError: replyMutation.error
+			? replyMutation.error instanceof Error
+				? replyMutation.error.message
+				: "Reply failed"
+			: null,
 		retry,
 		refreshLocalView,
 		replyToTweet,
 		selectedAccountId,
-		hasMore,
-		loadingMore,
-		loadMore,
+		hasMore: timelineQuery.hasNextPage,
+		loadingMore: timelineQuery.isFetchingNextPage,
+		loadMore: () => timelineQuery.fetchNextPage().then(() => undefined),
 	};
 }