xfeed 0.1.0

package/src/modals/README.md

@@ -0,0 +1,171 @@
+# Modal System
+
+Type-safe modal management using React Context with discriminated unions.
+
+## Usage
+
+### Opening a Modal
+
+```typescript
+import { useModal } from "@/contexts/ModalContext";
+
+function MyComponent() {
+  const { openModal, closeModal } = useModal();
+
+  const handleClick = () => {
+    openModal("exit-confirmation", {
+      onConfirm: () => console.log("Confirmed!"),
+      onCancel: closeModal,
+    });
+  };
+}
+```
+
+### Available Modal Types
+
+| Type                       | Props                                            | Description                    |
+| -------------------------- | ------------------------------------------------ | ------------------------------ |
+| `folder-picker`            | `client`, `tweet`, `onSelect`, `onClose`         | Move bookmark to folder        |
+| `bookmark-folder-selector` | `client`, `currentFolder`, `onSelect`, `onClose` | Select folder to view          |
+| `exit-confirmation`        | `onConfirm`, `onCancel`                          | Confirm app exit               |
+| `session-expired`          | none                                             | Terminal session expired state |
+
+### Context Values
+
+```typescript
+const {
+  openModal,      // Open a modal with type-safe props
+  closeModal,     // Close current modal (no-op for session-expired)
+  isModalOpen,    // Boolean for keyboard gating
+  activeModal,    // Current modal state (for advanced use)
+} = useModal();
+```
+
+## Adding a New Modal
+
+### 1. Create the modal component
+
+```typescript
+// src/modals/MyNewModal.tsx
+import { useKeyboard } from "@opentui/react";
+
+interface MyNewModalProps {
+  someData: string;
+  onConfirm: () => void;
+  onClose: () => void;
+  focused?: boolean;
+}
+
+export function MyNewModal({ someData, onConfirm, onClose, focused = true }: MyNewModalProps) {
+  useKeyboard((key) => {
+    if (!focused) return;  // Always guard with focused
+
+    if (key.name === "escape") onClose();
+    if (key.name === "return") onConfirm();
+  });
+
+  return (
+    <box style={{ /* modal styling */ }}>
+      {/* Modal content */}
+    </box>
+  );
+}
+```
+
+### 2. Add types to ModalContext
+
+```typescript
+// src/contexts/ModalContext.tsx
+
+// Add props interface
+export interface MyNewModalProps {
+  someData: string;
+  onConfirm: () => void;
+  onClose: () => void;
+}
+
+// Add to ModalType union
+export type ModalType =
+  | "folder-picker"
+  | "bookmark-folder-selector"
+  | "exit-confirmation"
+  | "session-expired"
+  | "my-new-modal";  // Add here
+
+// Add to ModalPropsMap
+export interface ModalPropsMap {
+  // ... existing entries
+  "my-new-modal": MyNewModalProps;
+}
+
+// Add to ModalState union
+export type ModalState =
+  // ... existing entries
+  | { type: "my-new-modal"; props: MyNewModalProps }
+  | null;
+```
+
+### 3. Add to ModalRenderer switch
+
+```typescript
+// In ModalRenderer component
+case "my-new-modal":
+  return (
+    <ModalWrapper>
+      <MyNewModal {...activeModal.props} focused={true} />
+    </ModalWrapper>
+  );
+```
+
+### 4. Export from index
+
+```typescript
+// src/modals/index.ts
+export { MyNewModal } from "./MyNewModal";
+```
+
+## Important Patterns
+
+### Keyboard Gating
+
+Screens must include `!isModalOpen` in their `focused` prop to prevent keyboard events from propagating when modals are open:
+
+```typescript
+<TimelineScreen
+  focused={currentView === "timeline" && !showSplash && !isModalOpen}
+/>
+```
+
+### Callback Closures
+
+Callbacks passed to `openModal` capture state at call time. This is intentional - the modal operates on the data that was current when it opened:
+
+```typescript
+openModal("folder-picker", {
+  tweet: selectedPost,  // Captured value
+  onSelect: async (folderId) => {
+    // selectedPost here is the captured value
+    await client.moveBookmarkToFolder(selectedPost.id, folderId);
+    closeModal();
+  },
+});
+```
+
+### Terminal Modals
+
+`session-expired` is a terminal modal - `closeModal()` is a no-op when it's active. The only way out is to exit the app.
+
+## File Structure
+
+```
+src/
+├── contexts/
+│   └── ModalContext.tsx      # Context, Provider, useModal, ModalRenderer
+├── modals/
+│   ├── README.md             # This file
+│   ├── index.ts              # Re-exports
+│   ├── FolderPicker.tsx
+│   ├── BookmarkFolderSelector.tsx
+│   ├── ExitConfirmationModal.tsx
+│   └── SessionExpiredModal.tsx
+```

package/src/modals/SessionExpiredModal.tsx

@@ -0,0 +1,47 @@
+import { useKeyboard, useRenderer } from "@opentui/react";
+
+import { colors } from "@/lib/colors";
+
+export function SessionExpiredModal() {
+  const renderer = useRenderer();
+
+  useKeyboard((key) => {
+    if (key.name === "return" || key.name === "q" || key.name === "escape") {
+      renderer.destroy();
+    }
+  });
+
+  return (
+    <box
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+        justifyContent: "center",
+        alignItems: "center",
+      }}
+    >
+      <box
+        style={{
+          borderStyle: "single",
+          padding: 2,
+          flexDirection: "column",
+          alignItems: "center",
+          gap: 1,
+        }}
+        backgroundColor={colors.selectedBg}
+        borderColor={colors.error}
+      >
+        <text fg={colors.error}>Session Expired</text>
+        <text fg="#a8a8a8">Your tokens are no longer valid.</text>
+        <box style={{ marginTop: 1, flexDirection: "row" }}>
+          <text fg="#6b6b6b">Press </text>
+          <text fg="#ffffff">Enter</text>
+          <text fg="#6b6b6b"> to quit</text>
+        </box>
+      </box>
+    </box>
+  );
+}

package/src/modals/index.ts

@@ -0,0 +1,4 @@
+export { BookmarkFolderSelector } from "./BookmarkFolderSelector";
+export { ExitConfirmationModal } from "./ExitConfirmationModal";
+export { FolderPicker } from "./FolderPicker";
+export { SessionExpiredModal } from "./SessionExpiredModal";

package/src/screens/BookmarksScreen.tsx

@@ -0,0 +1,168 @@
+/**
+ * BookmarksScreen - Displays the user's bookmarked posts
+ * Includes error handling with ErrorBanner for rate limits, auth expiry, etc.
+ * Supports viewing all bookmarks or a specific folder.
+ */
+
+import { useKeyboard } from "@opentui/react";
+import { useEffect } from "react";
+
+import type { XClient } from "@/api/client";
+import type { BookmarkFolder, TweetData } from "@/api/types";
+import type { TweetActionState } from "@/hooks/useActions";
+
+import { ErrorBanner } from "@/components/ErrorBanner";
+import { PostList } from "@/components/PostList";
+import { useBookmarksQuery } from "@/experiments";
+import { colors } from "@/lib/colors";
+
+interface BookmarksScreenProps {
+  client: XClient;
+  focused?: boolean;
+  /** Currently selected folder (null = all bookmarks) */
+  selectedFolder?: BookmarkFolder | null;
+  /** Called when user wants to open the folder picker (press 'f') */
+  onFolderPickerOpen?: () => void;
+  onPostCountChange?: (count: number) => void;
+  onHasMoreChange?: (hasMore: boolean) => void;
+  onPostSelect?: (post: TweetData) => void;
+  /** Called when user presses 'l' to toggle like */
+  onLike?: (post: TweetData) => void;
+  /** Called when user presses 'b' to toggle bookmark */
+  onBookmark?: (post: TweetData) => void;
+  /** Get current action state for a tweet */
+  getActionState?: (tweetId: string) => TweetActionState;
+  /** Initialize action state from API data */
+  initActionState?: (
+    tweetId: string,
+    liked: boolean,
+    bookmarked: boolean
+  ) => void;
+}
+
+interface ScreenHeaderProps {
+  folderName?: string | null;
+}
+
+function ScreenHeader({ folderName }: ScreenHeaderProps) {
+  const title = folderName ?? "All Bookmarks";
+  return (
+    <box
+      style={{
+        flexShrink: 0,
+        paddingLeft: 1,
+        paddingRight: 1,
+        paddingBottom: 1,
+        flexDirection: "row",
+      }}
+    >
+      <text fg={colors.primary}>
+        <b>{title}</b>
+      </text>
+      <text fg={colors.dim}> (f to switch folders)</text>
+    </box>
+  );
+}
+
+export function BookmarksScreen({
+  client,
+  focused = false,
+  selectedFolder,
+  onFolderPickerOpen,
+  onPostCountChange,
+  onHasMoreChange,
+  onPostSelect,
+  onLike,
+  onBookmark,
+  getActionState,
+  initActionState,
+}: BookmarksScreenProps) {
+  const {
+    posts,
+    isLoading,
+    isFetchingNextPage,
+    hasNextPage,
+    error,
+    refresh,
+    fetchNextPage,
+  } = useBookmarksQuery({ client, folderId: selectedFolder?.id });
+
+  // Report post count to parent
+  useEffect(() => {
+    onPostCountChange?.(posts.length);
+  }, [posts.length, onPostCountChange]);
+
+  // Report hasMore state to parent
+  useEffect(() => {
+    onHasMoreChange?.(hasNextPage);
+  }, [hasNextPage, onHasMoreChange]);
+
+  // Handle keyboard shortcuts
+  useKeyboard((key) => {
+    if (!focused) return;
+
+    if (key.name === "r") {
+      refresh();
+    }
+
+    // Open folder picker with 'f'
+    if (key.name === "f") {
+      onFolderPickerOpen?.();
+    }
+  });
+
+  const folderName = selectedFolder?.name ?? null;
+
+  if (isLoading) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        <ScreenHeader folderName={folderName} />
+        <box style={{ padding: 2, flexGrow: 1 }}>
+          <text fg={colors.muted}>Loading bookmarks...</text>
+        </box>
+      </box>
+    );
+  }
+
+  if (error) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        <ScreenHeader folderName={folderName} />
+        <ErrorBanner error={error} onRetry={refresh} retryDisabled={false} />
+      </box>
+    );
+  }
+
+  if (posts.length === 0) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        <ScreenHeader folderName={folderName} />
+        <box style={{ padding: 2, flexGrow: 1 }}>
+          <text fg={colors.muted}>
+            {selectedFolder
+              ? "No bookmarks in this folder. Press r to refresh."
+              : "No bookmarks yet. Press r to refresh."}
+          </text>
+        </box>
+      </box>
+    );
+  }
+
+  return (
+    <box style={{ flexDirection: "column", height: "100%" }}>
+      <ScreenHeader folderName={folderName} />
+      <PostList
+        posts={posts}
+        focused={focused}
+        onPostSelect={onPostSelect}
+        onLike={onLike}
+        onBookmark={onBookmark}
+        getActionState={getActionState}
+        initActionState={initActionState}
+        onLoadMore={fetchNextPage}
+        loadingMore={isFetchingNextPage}
+        hasMore={hasNextPage}
+      />
+    </box>
+  );
+}

package/src/screens/NotificationsScreen.tsx

@@ -0,0 +1,172 @@
+/**
+ * NotificationsScreen - Displays the user's notifications
+ * Uses TanStack Query for data fetching with background polling
+ */
+
+import { useKeyboard } from "@opentui/react";
+import { useEffect } from "react";
+
+import type { XClient } from "@/api/client";
+import type { NotificationData } from "@/api/types";
+
+import { ErrorBanner } from "@/components/ErrorBanner";
+import { NotificationList } from "@/components/NotificationList";
+import { useNotificationsQuery } from "@/experiments/use-notifications-query";
+import { colors } from "@/lib/colors";
+
+interface NotificationsScreenProps {
+  client: XClient;
+  focused?: boolean;
+  onNotificationCountChange?: (count: number) => void;
+  onUnreadCountChange?: (count: number) => void;
+  onNotificationSelect?: (notification: NotificationData) => void;
+}
+
+interface ScreenHeaderProps {
+  unreadCount: number;
+  isRefetching: boolean;
+}
+
+function ScreenHeader({ unreadCount, isRefetching }: ScreenHeaderProps) {
+  return (
+    <box
+      style={{
+        flexShrink: 0,
+        paddingLeft: 1,
+        paddingRight: 1,
+        paddingBottom: 1,
+        flexDirection: "row",
+        justifyContent: "space-between",
+      }}
+    >
+      <box style={{ flexDirection: "row" }}>
+        <text fg={colors.primary}>
+          <b>Notifications</b>
+        </text>
+        {unreadCount > 0 && <text fg={colors.error}> ({unreadCount} new)</text>}
+      </box>
+      {isRefetching && (
+        <text fg={colors.muted}>
+          <i>syncing...</i>
+        </text>
+      )}
+    </box>
+  );
+}
+
+function NewNotificationsBanner({ count }: { count: number }) {
+  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>
+            {count} new notification{count > 1 ? "s" : ""} — Press r
+          </b>
+        </text>
+      </box>
+    </box>
+  );
+}
+
+export function NotificationsScreen({
+  client,
+  focused = false,
+  onNotificationCountChange,
+  onUnreadCountChange,
+  onNotificationSelect,
+}: NotificationsScreenProps) {
+  const {
+    notifications,
+    unreadCount,
+    isLoading,
+    isFetchingNextPage,
+    hasNextPage,
+    error,
+    fetchNextPage,
+    refresh,
+    newNotificationsCount,
+    isRefetching,
+  } = useNotificationsQuery({ client });
+
+  // Report counts to parent
+  useEffect(() => {
+    onNotificationCountChange?.(notifications.length);
+  }, [notifications.length, onNotificationCountChange]);
+
+  useEffect(() => {
+    onUnreadCountChange?.(unreadCount);
+  }, [unreadCount, onUnreadCountChange]);
+
+  // Handle keyboard shortcuts for refresh
+  useKeyboard((key) => {
+    if (!focused) return;
+
+    if (key.name === "r") {
+      refresh();
+    }
+  });
+
+  if (isLoading) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        <ScreenHeader unreadCount={0} isRefetching={false} />
+        <box style={{ padding: 2, flexGrow: 1 }}>
+          <text fg={colors.muted}>Loading notifications...</text>
+        </box>
+      </box>
+    );
+  }
+
+  if (error) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        <ScreenHeader unreadCount={0} isRefetching={isRefetching} />
+        <ErrorBanner error={error} onRetry={refresh} retryDisabled={false} />
+      </box>
+    );
+  }
+
+  if (notifications.length === 0) {
+    return (
+      <box style={{ flexDirection: "column", height: "100%" }}>
+        <ScreenHeader unreadCount={0} isRefetching={isRefetching} />
+        <box style={{ padding: 2, flexGrow: 1 }}>
+          <text fg={colors.muted}>
+            No notifications yet. Press r to refresh.
+          </text>
+        </box>
+      </box>
+    );
+  }
+
+  return (
+    <box style={{ flexDirection: "column", height: "100%" }}>
+      <ScreenHeader unreadCount={unreadCount} isRefetching={isRefetching} />
+      {newNotificationsCount > 0 && (
+        <NewNotificationsBanner count={newNotificationsCount} />
+      )}
+      <NotificationList
+        notifications={notifications}
+        focused={focused}
+        onNotificationSelect={onNotificationSelect}
+        onLoadMore={fetchNextPage}
+        loadingMore={isFetchingNextPage}
+        hasMore={hasNextPage}
+      />
+    </box>
+  );
+}