xfeed 0.1.0

package/src/contexts/ModalContext.tsx

@@ -0,0 +1,227 @@
+/**
+ * ModalContext - Centralized modal management with type-safe discriminated unions
+ *
+ * Provides:
+ * - ModalProvider: Wraps app, manages state, renders modals at root level
+ * - useModal: Hook to open/close modals from any component
+ *
+ * Usage:
+ *   const { openModal, closeModal } = useModal();
+ *   openModal("folder-picker", { client, tweet, onSelect, onClose });
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useState,
+  type ReactNode,
+} from "react";
+
+import type { XClient } from "@/api/client";
+import type { BookmarkFolder, TweetData } from "@/api/types";
+
+import { BookmarkFolderSelector } from "@/modals/BookmarkFolderSelector";
+import { ExitConfirmationModal } from "@/modals/ExitConfirmationModal";
+import { FolderPicker } from "@/modals/FolderPicker";
+import { SessionExpiredModal } from "@/modals/SessionExpiredModal";
+
+// ============================================================================
+// Modal Type Definitions
+// ============================================================================
+
+/** Modal type identifiers */
+export type ModalType =
+  | "folder-picker"
+  | "bookmark-folder-selector"
+  | "exit-confirmation"
+  | "session-expired";
+
+/** Props for FolderPicker modal */
+export interface FolderPickerModalProps {
+  client: XClient;
+  tweet: TweetData;
+  onSelect: (folderId: string, folderName: string) => Promise<void>;
+  onClose: () => void;
+}
+
+/** Props for BookmarkFolderSelector modal */
+export interface BookmarkFolderSelectorModalProps {
+  client: XClient;
+  currentFolder: BookmarkFolder | null;
+  onSelect: (folder: BookmarkFolder | null) => void;
+  onClose: () => void;
+}
+
+/** Props for ExitConfirmationModal */
+export interface ExitConfirmationModalProps {
+  onLogout: () => void;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+/** Props for SessionExpiredModal (terminal - no props needed) */
+export interface SessionExpiredModalProps {}
+
+/** Map of modal type to its props type for type inference */
+export interface ModalPropsMap {
+  "folder-picker": FolderPickerModalProps;
+  "bookmark-folder-selector": BookmarkFolderSelectorModalProps;
+  "exit-confirmation": ExitConfirmationModalProps;
+  "session-expired": SessionExpiredModalProps;
+}
+
+/** Discriminated union of all possible modal states */
+export type ModalState =
+  | { type: "folder-picker"; props: FolderPickerModalProps }
+  | {
+      type: "bookmark-folder-selector";
+      props: BookmarkFolderSelectorModalProps;
+    }
+  | { type: "exit-confirmation"; props: ExitConfirmationModalProps }
+  | { type: "session-expired"; props: SessionExpiredModalProps }
+  | null;
+
+// ============================================================================
+// Context Definition
+// ============================================================================
+
+/** Context value exposed to consumers */
+export interface ModalContextValue {
+  /** Currently active modal state (null if no modal open) */
+  activeModal: ModalState;
+
+  /** Open a modal with type-safe props */
+  openModal: <T extends ModalType>(type: T, props: ModalPropsMap[T]) => void;
+
+  /** Close the current modal (no-op if session-expired is showing) */
+  closeModal: () => void;
+
+  /** Whether any modal is currently open (for keyboard gating) */
+  isModalOpen: boolean;
+
+  /** Whether the session-expired modal is showing (terminal state) */
+  isSessionExpired: boolean;
+}
+
+const ModalContext = createContext<ModalContextValue | null>(null);
+
+// ============================================================================
+// ModalRenderer Component
+// ============================================================================
+
+interface ModalRendererProps {
+  activeModal: ModalState;
+}
+
+function ModalRenderer({ activeModal }: ModalRendererProps) {
+  if (!activeModal) {
+    return null;
+  }
+
+  // Absolute positioning wrapper - consistent for all modals
+  const ModalWrapper = ({ children }: { children: ReactNode }) => (
+    <box
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+      }}
+    >
+      {children}
+    </box>
+  );
+
+  switch (activeModal.type) {
+    case "folder-picker":
+      return (
+        <ModalWrapper>
+          <FolderPicker {...activeModal.props} focused={true} />
+        </ModalWrapper>
+      );
+
+    case "bookmark-folder-selector":
+      return (
+        <ModalWrapper>
+          <BookmarkFolderSelector {...activeModal.props} focused={true} />
+        </ModalWrapper>
+      );
+
+    case "exit-confirmation":
+      return (
+        <ModalWrapper>
+          <ExitConfirmationModal {...activeModal.props} focused={true} />
+        </ModalWrapper>
+      );
+
+    case "session-expired":
+      // SessionExpiredModal includes its own absolute positioning
+      return <SessionExpiredModal />;
+  }
+}
+
+// ============================================================================
+// ModalProvider Component
+// ============================================================================
+
+interface ModalProviderProps {
+  children: ReactNode;
+}
+
+export function ModalProvider({ children }: ModalProviderProps) {
+  const [activeModal, setActiveModal] = useState<ModalState>(null);
+
+  const openModal = useCallback(
+    <T extends ModalType>(type: T, props: ModalPropsMap[T]) => {
+      // Type assertion needed due to discriminated union mapping
+      setActiveModal({ type, props } as ModalState);
+    },
+    []
+  );
+
+  const closeModal = useCallback(() => {
+    setActiveModal((current) => {
+      // Don't allow closing session-expired modal (terminal state)
+      if (current?.type === "session-expired") {
+        return current;
+      }
+      return null;
+    });
+  }, []);
+
+  const isModalOpen = activeModal !== null;
+  const isSessionExpired = activeModal?.type === "session-expired";
+
+  const contextValue: ModalContextValue = {
+    activeModal,
+    openModal,
+    closeModal,
+    isModalOpen,
+    isSessionExpired,
+  };
+
+  return (
+    <ModalContext.Provider value={contextValue}>
+      {children}
+      <ModalRenderer activeModal={activeModal} />
+    </ModalContext.Provider>
+  );
+}
+
+// ============================================================================
+// useModal Hook
+// ============================================================================
+
+/**
+ * Hook to access modal context
+ * @throws Error if used outside ModalProvider
+ */
+export function useModal(): ModalContextValue {
+  const context = useContext(ModalContext);
+  if (!context) {
+    throw new Error("useModal must be used within a ModalProvider");
+  }
+  return context;
+}

package/src/experiments/TimelineScreenExperimental.tsx

@@ -0,0 +1,202 @@
+/**
+ * TimelineScreenExperimental - TanStack Query version of TimelineScreen
+ *
+ * Features:
+ * - Uses useTimelineQuery for data fetching
+ * - Shows "Refresh for new posts" banner after 5 minutes
+ */
+
+import { useKeyboard } from "@opentui/react";
+import { useEffect } from "react";
+
+import type { XClient } from "@/api/client";
+import type { TweetData } from "@/api/types";
+import type { TweetActionState } from "@/hooks/useActions";
+
+import { ErrorBanner } from "@/components/ErrorBanner";
+import { PostList } from "@/components/PostList";
+import { colors } from "@/lib/colors";
+
+import { type TimelineTab, useTimelineQuery } from "./use-timeline-query";
+
+interface TimelineScreenExperimentalProps {
+  client: XClient;
+  focused?: boolean;
+  onPostCountChange?: (count: number) => void;
+  onPostSelect?: (post: TweetData) => void;
+  onLike?: (post: TweetData) => void;
+  onBookmark?: (post: TweetData) => void;
+  getActionState?: (tweetId: string) => TweetActionState;
+  initActionState?: (
+    tweetId: string,
+    liked: boolean,
+    bookmarked: boolean
+  ) => void;
+}
+
+interface TabBarProps {
+  activeTab: TimelineTab;
+  isRefetching: boolean;
+}
+
+function TabBar({ activeTab, isRefetching }: TabBarProps) {
+  return (
+    <box
+      style={{
+        flexShrink: 0,
+        paddingLeft: 1,
+        paddingRight: 1,
+        paddingBottom: 1,
+        flexDirection: "row",
+        justifyContent: "space-between",
+      }}
+    >
+      <box style={{ flexDirection: "row" }}>
+        <text fg={activeTab === "for_you" ? colors.primary : colors.dim}>
+          {activeTab === "for_you" ? <b>[1] For You</b> : " 1  For You"}
+        </text>
+        <text fg={colors.dim}> | </text>
+        <text fg={activeTab === "following" ? colors.primary : colors.dim}>
+          {activeTab === "following" ? <b>[2] Following</b> : " 2  Following"}
+        </text>
+      </box>
+
+      {/* Sync indicator */}
+      {isRefetching && (
+        <text fg={colors.muted}>
+          <i>syncing...</i>
+        </text>
+      )}
+    </box>
+  );
+}
+
+function RefreshBanner() {
+  return (
+    <box
+      style={{
+        flexShrink: 0,
+        paddingLeft: 1,
+        paddingRight: 1,
+        paddingTop: 0,
+        paddingBottom: 1,
+      }}
+    >
+      <box
+        style={{
+          backgroundColor: colors.primary,
+          paddingLeft: 2,
+          paddingRight: 2,
+        }}
+      >
+        <text fg="#000000">
+          <b>Refresh for new posts — Press r</b>
+        </text>
+      </box>
+    </box>
+  );
+}
+
+export function TimelineScreenExperimental({
+  client,
+  focused = false,
+  onPostCountChange,
+  onPostSelect,
+  onLike,
+  onBookmark,
+  getActionState,
+  initActionState,
+}: TimelineScreenExperimentalProps) {
+  const {
+    tab,
+    setTab,
+    posts,
+    isLoading,
+    isFetchingNextPage,
+    hasNextPage,
+    error,
+    fetchNextPage,
+    refresh,
+    showRefreshBanner,
+    isRefetching,
+  } = useTimelineQuery({
+    client,
+  });
+
+  // Report post count to parent
+  useEffect(() => {
+    onPostCountChange?.(posts.length);
+  }, [posts.length, onPostCountChange]);
+
+  // Handle keyboard shortcuts
+  useKeyboard((key) => {
+    if (!focused) return;
+
+    switch (key.name) {
+      case "1":
+        setTab("for_you");
+        break;
+      case "2":
+        setTab("following");
+        break;
+      case "r":
+        refresh();
+        break;
+    }
+  });
+
+  if (isLoading) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        {focused && <TabBar activeTab={tab} isRefetching={isRefetching} />}
+        <box style={{ padding: 2, flexGrow: 1 }}>
+          <text fg={colors.muted}>Loading timeline...</text>
+        </box>
+      </box>
+    );
+  }
+
+  if (error) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        {focused && <TabBar activeTab={tab} isRefetching={isRefetching} />}
+        <ErrorBanner error={error} onRetry={refresh} retryDisabled={false} />
+      </box>
+    );
+  }
+
+  if (posts.length === 0) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        {focused && <TabBar activeTab={tab} isRefetching={isRefetching} />}
+        <box style={{ padding: 2, flexGrow: 1 }}>
+          <text fg={colors.muted}>
+            No posts to display. Press r to refresh.
+          </text>
+        </box>
+      </box>
+    );
+  }
+
+  return (
+    <box style={{ flexDirection: "column", height: "100%" }}>
+      {focused && <TabBar activeTab={tab} isRefetching={isRefetching} />}
+
+      {/* Refresh banner */}
+      {showRefreshBanner && <RefreshBanner />}
+
+      <PostList
+        posts={posts}
+        focused={focused}
+        onPostSelect={onPostSelect}
+        onLike={onLike}
+        onBookmark={onBookmark}
+        getActionState={getActionState}
+        initActionState={initActionState}
+        onLoadMore={fetchNextPage}
+        loadingMore={isFetchingNextPage}
+        hasMore={hasNextPage}
+      />
+    </box>
+  );
+}

package/src/experiments/index.tsx

@@ -0,0 +1,43 @@
+/**
+ * TanStack Query Experiment Entry Point
+ *
+ * This file provides the QueryClientProvider wrapper for the experimental
+ * TanStack Query-based timeline.
+ */
+
+import { QueryClientProvider } from "@tanstack/react-query";
+import { type ReactNode, useState } from "react";
+
+import { createQueryClient } from "./query-client";
+
+// Singleton query client (create once per app lifecycle)
+let queryClientInstance: ReturnType<typeof createQueryClient> | null = null;
+
+function getQueryClient() {
+  if (!queryClientInstance) {
+    queryClientInstance = createQueryClient();
+  }
+  return queryClientInstance;
+}
+
+/**
+ * Provider wrapper for TanStack Query
+ * Wrap your app root with this to enable TanStack Query hooks
+ */
+export function QueryProvider({ children }: { children: ReactNode }) {
+  // Use state to ensure stable reference across re-renders
+  const [queryClient] = useState(() => getQueryClient());
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+// Re-export components for external use
+export { TimelineScreenExperimental } from "./TimelineScreenExperimental";
+export { useTimelineQuery } from "./use-timeline-query";
+export { useProfileQuery } from "./use-profile-query";
+export { usePostDetailQuery } from "./use-post-detail-query";
+export { useBookmarksQuery } from "./use-bookmarks-query";
+export { useBookmarkMutation } from "./use-bookmark-mutation";
+export { createQueryClient, queryKeys } from "./query-client";

package/src/experiments/query-client.ts

@@ -0,0 +1,132 @@
+/**
+ * TanStack Query client configuration for terminal environment
+ *
+ * Key considerations:
+ * - No window focus events in terminal, so disable refetchOnWindowFocus
+ * - Custom retry logic for X API rate limits
+ * - Stale time configured for timeline freshness
+ */
+
+import { QueryClient } from "@tanstack/react-query";
+
+import type { ApiError } from "@/api/types";
+
+/**
+ * Custom retry function that respects X API rate limits
+ */
+function shouldRetry(failureCount: number, error: unknown): boolean {
+  // Type guard for ApiError
+  const apiError = error as ApiError | undefined;
+
+  // Don't retry rate limits - let the UI handle countdown
+  if (apiError?.type === "rate_limit") {
+    return false;
+  }
+
+  // Don't retry auth errors - need user intervention
+  if (apiError?.type === "auth_expired") {
+    return false;
+  }
+
+  // Don't retry not found - permanent error
+  if (apiError?.type === "not_found") {
+    return false;
+  }
+
+  // Retry network errors up to 3 times
+  if (apiError?.type === "network_error") {
+    return failureCount < 3;
+  }
+
+  // Default: retry up to 2 times for unknown errors
+  return failureCount < 2;
+}
+
+/**
+ * Calculate retry delay with exponential backoff
+ */
+function getRetryDelay(attemptIndex: number, error: unknown): number {
+  const apiError = error as ApiError | undefined;
+
+  // Use rate limit retry-after if available
+  if (apiError?.type === "rate_limit" && apiError.retryAfter) {
+    return apiError.retryAfter * 1000;
+  }
+
+  // Exponential backoff: 1s, 2s, 4s...
+  return Math.min(1000 * 2 ** attemptIndex, 30000);
+}
+
+/**
+ * Create a QueryClient configured for the terminal environment
+ */
+export function createQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        // Terminal has no window focus, disable this
+        refetchOnWindowFocus: false,
+
+        // Don't refetch when component remounts (preserve scroll position)
+        refetchOnMount: false,
+
+        // Keep data in cache for 5 minutes after last subscriber
+        gcTime: 5 * 60 * 1000,
+
+        // Consider data stale after 30 seconds
+        // This enables background refetch on next access
+        staleTime: 30 * 1000,
+
+        // Custom retry logic for X API
+        retry: shouldRetry,
+        retryDelay: getRetryDelay,
+
+        // Don't throw errors to error boundaries
+        throwOnError: false,
+      },
+      mutations: {
+        // Don't retry mutations by default
+        retry: false,
+      },
+    },
+  });
+}
+
+/**
+ * Query key factory for consistent cache keys
+ */
+export const queryKeys = {
+  timeline: {
+    all: ["timeline"] as const,
+    forYou: () => [...queryKeys.timeline.all, "for_you"] as const,
+    following: () => [...queryKeys.timeline.all, "following"] as const,
+    byTab: (tab: "for_you" | "following") =>
+      [...queryKeys.timeline.all, tab] as const,
+  },
+  bookmarks: {
+    all: ["bookmarks"] as const,
+    list: (folderId?: string) =>
+      folderId
+        ? ([...queryKeys.bookmarks.all, "folder", folderId] as const)
+        : ([...queryKeys.bookmarks.all, "list"] as const),
+    folders: () => [...queryKeys.bookmarks.all, "folders"] as const,
+  },
+  notifications: {
+    all: ["notifications"] as const,
+    list: () => [...queryKeys.notifications.all, "list"] as const,
+    poll: () => [...queryKeys.notifications.all, "poll"] as const,
+  },
+  tweet: {
+    all: ["tweet"] as const,
+    detail: (id: string) => [...queryKeys.tweet.all, id] as const,
+    replies: (id: string) => [...queryKeys.tweet.all, id, "replies"] as const,
+  },
+  user: {
+    all: ["user"] as const,
+    profile: (username: string) =>
+      [...queryKeys.user.all, username, "profile"] as const,
+    tweets: (userId: string) =>
+      [...queryKeys.user.all, userId, "tweets"] as const,
+    likes: () => [...queryKeys.user.all, "likes"] as const,
+  },
+} as const;