@ahmd-sh/hntui 0.3.0

package/src/components/HelpOverlay.tsx

@@ -0,0 +1,133 @@
+import { TextAttributes } from "@opentui/core"
+import { selectionColors, useTheme } from "../theme"
+
+interface Binding {
+  keys: string
+  desc: string
+}
+
+interface Group {
+  title: string
+  bindings: Binding[]
+}
+
+const NAVIGATION: Binding[] = [
+  { keys: "j k  ↑ ↓", desc: "move down / up" },
+  { keys: "g g / G", desc: "jump to top / bottom" },
+  { keys: "Ctrl+d / Ctrl+u", desc: "half-page down / up" },
+]
+
+const LIST_GROUPS: Group[] = [
+  {
+    title: "Navigation",
+    bindings: [
+      ...NAVIGATION,
+      { keys: "h / l", desc: "previous / next category" },
+      { keys: "Tab / ⇧Tab", desc: "cycle categories" },
+      { keys: "1 – 6", desc: "jump to category" },
+    ],
+  },
+  {
+    title: "Actions",
+    bindings: [
+      { keys: "c / ⏎", desc: "open comments" },
+      { keys: "o", desc: "open post link in browser" },
+      { keys: "y", desc: "open HN page in browser" },
+      { keys: "s", desc: "save / unsave" },
+      { keys: "r", desc: "refresh feed" },
+      { keys: "x", desc: "clear history (History view)" },
+    ],
+  },
+]
+
+const DETAIL_GROUPS: Group[] = [
+  {
+    title: "Navigation",
+    bindings: NAVIGATION,
+  },
+  {
+    title: "Actions",
+    bindings: [
+      { keys: "space", desc: "collapse / expand" },
+      { keys: "⏎", desc: "comment links (HN posts open in-app)" },
+      { keys: "o", desc: "open post link in browser" },
+      { keys: "y", desc: "open HN page in browser" },
+      { keys: "s", desc: "save / unsave" },
+      { keys: "h / esc", desc: "go back" },
+    ],
+  },
+]
+
+const GENERAL: Group = {
+  title: "General",
+  bindings: [
+    { keys: "S", desc: "saved posts" },
+    { keys: "H", desc: "view history" },
+    { keys: "t", desc: "toggle theme" },
+    { keys: "?", desc: "toggle this help" },
+    { keys: "q", desc: "quit" },
+  ],
+}
+
+interface Props {
+  view: "list" | "detail"
+  onClose: () => void
+}
+
+export function HelpOverlay({ view, onClose }: Props) {
+  const t = useTheme()
+  const groups = [...(view === "list" ? LIST_GROUPS : DETAIL_GROUPS), GENERAL]
+  const keyWidth = groups.reduce(
+    (w, g) => g.bindings.reduce((m, b) => Math.max(m, b.keys.length), w),
+    0,
+  )
+
+  return (
+    <box
+      position="absolute"
+      top={0}
+      left={0}
+      width="100%"
+      height="100%"
+      alignItems="center"
+      justifyContent="center"
+      zIndex={150}
+      backgroundColor="#00000088"
+      onMouseDown={onClose}
+    >
+      <box
+        flexDirection="column"
+        width="60%"
+        backgroundColor={t.body}
+        border={true}
+        borderStyle="rounded"
+        borderColor={t.accent}
+        paddingTop={1}
+        paddingBottom={1}
+        paddingLeft={2}
+        paddingRight={2}
+        title=" Keyboard shortcuts "
+        onMouseDown={(ev) => ev.stopPropagation()}
+      >
+        {groups.map((group, gi) => (
+          <box key={group.title} flexDirection="column" marginTop={gi === 0 ? 0 : 1}>
+            <text fg={t.accent} {...selectionColors(t)} attributes={TextAttributes.BOLD}>
+              {group.title}
+            </text>
+            {group.bindings.map((b, bi) => (
+              <text key={bi} {...selectionColors(t)}>
+                <span fg={t.text}>{`  ${b.keys.padEnd(keyWidth)}`}</span>
+                <span fg={t.textMuted}>{`   ${b.desc}`}</span>
+              </text>
+            ))}
+          </box>
+        ))}
+        <box marginTop={1}>
+          <text fg={t.statusHint} {...selectionColors(t)}>
+            esc / ? close
+          </text>
+        </box>
+      </box>
+    </box>
+  )
+}

package/src/components/LinksPopup.tsx

@@ -0,0 +1,101 @@
+import { TextAttributes } from "@opentui/core"
+import type { Link } from "../utils/format"
+import { selectionColors, useTheme } from "../theme"
+
+interface Props {
+  links: Link[]
+  cursor: number
+  onSelect: (idx: number) => void
+  onActivate: (idx: number) => void
+  onClose: () => void
+}
+
+export function LinksPopup({ links, cursor, onSelect, onActivate, onClose }: Props) {
+  const t = useTheme()
+
+  return (
+    <box
+      position="absolute"
+      top={0}
+      left={0}
+      width="100%"
+      height="100%"
+      alignItems="center"
+      justifyContent="center"
+      zIndex={100}
+      backgroundColor="#00000088"
+      onMouseDown={onClose}
+    >
+      <box
+        flexDirection="column"
+        width="70%"
+        backgroundColor={t.body}
+        border={true}
+        borderStyle="rounded"
+        borderColor={t.accent}
+        paddingTop={1}
+        paddingBottom={1}
+        paddingLeft={2}
+        paddingRight={2}
+        title={` Links (${links.length}) `}
+        onMouseDown={(ev) => ev.stopPropagation()}
+      >
+        {links.map((link, idx) => (
+          <LinkRow
+            key={`${idx}-${link.url}`}
+            link={link}
+            index={idx}
+            selected={idx === cursor}
+            isFirst={idx === 0}
+            onSelect={() => onSelect(idx)}
+            onActivate={() => onActivate(idx)}
+          />
+        ))}
+        <box marginTop={1}>
+          <text fg={t.statusHint} {...selectionColors(t)}>j/k move · ⏎ open · o browser · esc close</text>
+        </box>
+      </box>
+    </box>
+  )
+}
+
+interface RowProps {
+  link: Link
+  index: number
+  selected: boolean
+  isFirst: boolean
+  onSelect: () => void
+  onActivate: () => void
+}
+
+function LinkRow({ link, index, selected, isFirst, onSelect, onActivate }: RowProps) {
+  const t = useTheme()
+  let lastClick = 0
+  const handleClick = () => {
+    const now = Date.now()
+    if (selected || now - lastClick < 400) {
+      onActivate()
+    } else {
+      onSelect()
+    }
+    lastClick = now
+  }
+  return (
+    <box
+      flexDirection="column"
+      marginTop={isFirst ? 0 : 1}
+      backgroundColor={selected ? t.rowHighlight : undefined}
+      paddingLeft={1}
+      paddingRight={1}
+      onMouseDown={handleClick}
+    >
+      <text {...selectionColors(t)}>
+        <span fg={selected ? t.accent : t.textDim}>{selected ? "▶ " : "  "}</span>
+        <span fg={t.text} attributes={selected ? TextAttributes.BOLD : TextAttributes.NONE}>
+          {`${index + 1}. ${link.text}`}
+        </span>
+      </text>
+      <text fg={t.link} {...selectionColors(t)}>{`    ${link.url}`}</text>
+    </box>
+  )
+}

package/src/components/Loader.tsx

@@ -0,0 +1,30 @@
+import { RGBA } from "@opentui/core"
+import { createColors, createFrames } from "../spinner"
+
+const HN_ORANGE_RAMP = [
+  RGBA.fromHex("#ff6600"),
+  RGBA.fromHex("#ffaa66"),
+  RGBA.fromHex("#dd5500"),
+  RGBA.fromHex("#aa4400"),
+  RGBA.fromHex("#773300"),
+  RGBA.fromHex("#442200"),
+]
+
+const HN_INACTIVE = RGBA.fromHex("#2a1500")
+
+const OPTIONS = {
+  style: "blocks" as const,
+  colors: HN_ORANGE_RAMP,
+  defaultColor: HN_INACTIVE,
+}
+
+const FRAMES = createFrames(OPTIONS)
+const COLOR = createColors(OPTIONS)
+
+interface Props {
+  interval?: number
+}
+
+export function Loader({ interval = 40 }: Props) {
+  return <spinner frames={FRAMES} color={COLOR} interval={interval} />
+}

package/src/components/StatusBar.tsx

@@ -0,0 +1,40 @@
+import { Loader } from "./Loader"
+import type { Category } from "../api/types"
+import { selectionColors, useTheme } from "../theme"
+
+interface Props {
+  view: "list" | "detail"
+  category?: Category
+  loading?: boolean
+  message?: string
+}
+
+export function StatusBar({ view, category, loading, message }: Props) {
+  const t = useTheme()
+  const hints =
+    view === "list"
+      ? category === "history"
+        ? "j/k move · c/⏎ open · x clear history · q quit"
+        : "j/k move · c/⏎ open · s save · q quit"
+      : "j/k move · space collapse · ⏎ links · h/esc back"
+  return (
+    <box
+      flexDirection="row"
+      flexShrink={0}
+      height={2}
+      paddingLeft={1}
+      paddingRight={1}
+      gap={1}
+      alignItems="center"
+      backgroundColor={t.strip}
+      border={["top"]}
+      borderStyle="single"
+      borderColor={t.border}
+    >
+      {loading ? <Loader /> : null}
+      <text fg={t.statusHint} {...selectionColors(t)}>{message ?? hints}</text>
+      <box flexGrow={1} />
+      <text fg={t.statusHint} {...selectionColors(t)}>? help</text>
+    </box>
+  )
+}

package/src/components/StoryRow.tsx

@@ -0,0 +1,76 @@
+import type { MouseEvent } from "@opentui/core"
+import { TextAttributes } from "@opentui/core"
+import type { Item } from "../api/types"
+import { hostname, relativeTime } from "../utils/format"
+import { selectionColors, useTheme } from "../theme"
+
+interface Props {
+  rank: number
+  item: Item
+  selected: boolean
+  saved?: boolean
+  visited?: boolean
+  onSelect: () => void
+  onActivate: () => void
+  onContextMenu?: (ev: MouseEvent) => void
+}
+
+export function StoryRow({ rank, item, selected, saved, visited, onSelect, onActivate, onContextMenu }: Props) {
+  const t = useTheme()
+  const host = hostname(item.url)
+  const title = item.title ?? "(untitled)"
+  const score = item.score ?? 0
+  const author = item.by ?? "?"
+  const age = relativeTime(item.time)
+  const comments = item.descendants ?? 0
+  const bg = selected ? t.rowHighlight : undefined
+  const titleFg = visited ? t.textVisited : selected ? t.text : t.textBody
+  const rankFg = visited ? t.textVisited : selected ? t.accent : t.textDim
+  const voteFg = visited ? t.textVisited : t.accent
+  const dimFg = visited ? t.textVisited : t.textDim
+  const mutedFg = visited ? t.textVisited : t.textMuted
+
+  let lastClick = 0
+  const handleClick = (ev: MouseEvent) => {
+    if (ev.button === 2) {
+      onSelect()
+      onContextMenu?.(ev)
+      return
+    }
+    const now = Date.now()
+    if (selected || now - lastClick < 400) {
+      onActivate()
+    } else {
+      onSelect()
+    }
+    lastClick = now
+  }
+
+  return (
+    <box
+      id={`row-${rank}`}
+      flexDirection="column"
+      paddingLeft={1}
+      paddingRight={1}
+      backgroundColor={bg}
+      onMouseDown={handleClick}
+    >
+      <text {...selectionColors(t)}>
+        <span fg={rankFg}>{`${String(rank).padStart(3, " ")}. `}</span>
+        {saved ? <span fg={t.accent}>{"★ "}</span> : null}
+        <span fg={titleFg} attributes={selected ? TextAttributes.BOLD : TextAttributes.NONE}>
+          {title}
+        </span>
+        {host ? <span fg={dimFg}>{` (${host})`}</span> : null}
+      </text>
+      <text {...selectionColors(t)}>
+        <span fg={t.textDim}>     </span>
+        <span fg={voteFg}>▲ {score}</span>
+        <span fg={dimFg}>{`  by `}</span>
+        <span fg={mutedFg}>{author}</span>
+        <span fg={dimFg}>{`  ${age}  | `}</span>
+        <span fg={mutedFg}>{`${comments} comment${comments === 1 ? "" : "s"}`}</span>
+      </text>
+    </box>
+  )
+}

package/src/hooks/useCommentTree.ts

@@ -0,0 +1,95 @@
+import { useEffect, useState } from "react"
+import { Effect, Fiber } from "effect"
+import { AppRuntime } from "../runtime"
+import { fetchItem } from "../api/hn"
+import type { HnApi } from "../api/hn"
+import type { Item } from "../api/types"
+
+export interface CommentNode {
+  item: Item
+  children: CommentNode[]
+}
+
+export interface FlatComment {
+  node: CommentNode
+  depth: number
+  hiddenChildren: number
+}
+
+const loadTree = (
+  id: number,
+  depth: number,
+  maxDepth: number,
+): Effect.Effect<CommentNode | null, never, HnApi> =>
+  Effect.gen(function* () {
+    // a comment that fails to load is simply omitted, like before
+    const item = yield* fetchItem(id).pipe(Effect.orElseSucceed(() => null))
+    if (!item || item.deleted || item.dead) return null
+    const kidIds = item.kids ?? []
+    let children: CommentNode[] = []
+    if (depth < maxDepth && kidIds.length > 0) {
+      const loaded = yield* Effect.forEach(
+        kidIds,
+        (kid) => loadTree(kid, depth + 1, maxDepth),
+        { concurrency: "unbounded" },
+      )
+      children = loaded.filter((x): x is CommentNode => x !== null)
+    }
+    return { item, children }
+  })
+
+export function useCommentTree(rootIds: number[] | undefined, maxDepth = 8, refreshKey = 0) {
+  const idsKey = rootIds && rootIds.length > 0 ? rootIds.join(",") : ""
+  // refreshKey re-runs the load for the same story: failed fetches were
+  // evicted from the item cache, so a retry actually refetches them
+  const key = idsKey === "" ? "" : `${refreshKey}|${idsKey}`
+  // The tree is tagged with the key it was loaded for, so switching stories
+  // DERIVES empty+loading state on the very same render
+  const [result, setResult] = useState<{ key: string; tree: CommentNode[] }>({
+    key: "",
+    tree: [],
+  })
+
+  useEffect(() => {
+    if (key === "") return
+    const ids = key.slice(key.indexOf("|") + 1).split(",").map(Number)
+    const fiber = AppRuntime.runFork(
+      Effect.forEach(ids, (id) => loadTree(id, 0, maxDepth), {
+        concurrency: "unbounded",
+      }).pipe(
+        Effect.andThen((nodes) =>
+          Effect.sync(() => {
+            setResult({ key, tree: nodes.filter((x): x is CommentNode => x !== null) })
+          }),
+        ),
+      ),
+    )
+    return () => {
+      // interrupts the ENTIRE tree of pending comment fetches at once
+      AppRuntime.runFork(Fiber.interrupt(fiber))
+    }
+  }, [key, maxDepth])
+
+  const fresh = key !== "" && result.key === key
+  return { tree: fresh ? result.tree : [], loading: key !== "" && !fresh }
+}
+
+export function flattenTree(tree: CommentNode[], collapsed: Set<number>): FlatComment[] {
+  const out: FlatComment[] = []
+  const walk = (nodes: CommentNode[], depth: number) => {
+    for (const node of nodes) {
+      const isCollapsed = collapsed.has(node.item.id)
+      const hidden = isCollapsed ? countAll(node) : 0
+      out.push({ node, depth, hiddenChildren: hidden })
+      if (!isCollapsed) walk(node.children, depth + 1)
+    }
+  }
+  walk(tree, 0)
+  return out
+}
+
+function countAll(node: CommentNode): number {
+  let n = node.children.length
+  for (const c of node.children) n += countAll(c)
+  return n
+}

package/src/hooks/useHistory.ts

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import type { HistoryEntry } from "../utils/historyStore"
+import { HISTORY_CAP, loadHistory, persistHistory } from "../utils/historyStore"
+
+export function useHistory() {
+  const [entries, setEntries] = useState<HistoryEntry[]>([])
+  const [loaded, setLoaded] = useState(false)
+  const firstLoad = useRef(true)
+
+  useEffect(() => {
+    loadHistory().then((data) => {
+      setEntries(data)
+      setLoaded(true)
+    })
+  }, [])
+
+  useEffect(() => {
+    if (firstLoad.current) {
+      firstLoad.current = false
+      return
+    }
+    if (loaded) void persistHistory(entries)
+  }, [entries, loaded])
+
+  const idSet = useMemo(() => new Set(entries.map((e) => e.id)), [entries])
+
+  const isViewed = useCallback((id: number) => idSet.has(id), [idSet])
+
+  // Move the post to the front (most recent) and evict the oldest beyond the cap.
+  const markViewed = useCallback((id: number) => {
+    setEntries((prev) => {
+      const rest = prev.filter((e) => e.id !== id)
+      return [{ id, viewedAt: Date.now() }, ...rest].slice(0, HISTORY_CAP)
+    })
+  }, [])
+
+  const clear = useCallback(() => setEntries([]), [])
+
+  return { entries, idSet, isViewed, markViewed, clear, loaded }
+}

package/src/hooks/useItems.ts

@@ -0,0 +1,34 @@
+import { useEffect, useState } from "react"
+import { Effect, Fiber } from "effect"
+import { AppRuntime } from "../runtime"
+import { fetchItems } from "../api/hn"
+import type { Item } from "../api/types"
+
+export function useItems(ids: number[]) {
+  const [items, setItems] = useState<Item[]>([])
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    if (ids.length === 0) {
+      setItems([])
+      return
+    }
+    setItems([])
+    setLoading(true)
+    const fiber = AppRuntime.runFork(
+      fetchItems(ids).pipe(
+        Effect.andThen((data) =>
+          Effect.sync(() => {
+            setItems(data)
+            setLoading(false)
+          }),
+        ),
+      ),
+    )
+    return () => {
+      AppRuntime.runFork(Fiber.interrupt(fiber))
+    }
+  }, [ids.join(",")])
+
+  return { items, loading }
+}

package/src/hooks/useSaved.ts

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import type { SavedEntry } from "../utils/savedStore"
+import { loadSaved, persistSaved } from "../utils/savedStore"
+
+export function useSaved() {
+  const [entries, setEntries] = useState<SavedEntry[]>([])
+  const [loaded, setLoaded] = useState(false)
+  const firstLoad = useRef(true)
+
+  useEffect(() => {
+    loadSaved().then((data) => {
+      setEntries(data)
+      setLoaded(true)
+    })
+  }, [])
+
+  useEffect(() => {
+    if (firstLoad.current) {
+      firstLoad.current = false
+      return
+    }
+    if (loaded) void persistSaved(entries)
+  }, [entries, loaded])
+
+  const idSet = useMemo(() => new Set(entries.map((e) => e.id)), [entries])
+
+  const isSaved = useCallback((id: number) => idSet.has(id), [idSet])
+
+  const toggle = useCallback((id: number) => {
+    setEntries((prev) => {
+      if (prev.some((e) => e.id === id)) return prev.filter((e) => e.id !== id)
+      return [{ id, savedAt: Date.now() }, ...prev]
+    })
+  }, [])
+
+  return { entries, idSet, isSaved, toggle, loaded }
+}

package/src/hooks/useStoryIds.ts

@@ -0,0 +1,38 @@
+import { useEffect, useState } from "react"
+import { Effect, Fiber } from "effect"
+import { AppRuntime } from "../runtime"
+import { fetchIds } from "../api/hn"
+import type { HnError } from "../api/hn"
+import type { FeedCategory } from "../api/types"
+
+export function useStoryIds(category: FeedCategory, refreshKey = 0) {
+  const [ids, setIds] = useState<number[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<HnError | null>(null)
+
+  useEffect(() => {
+    setIds([])
+    setLoading(true)
+    setError(null)
+    const fiber = AppRuntime.runFork(
+      fetchIds(category).pipe(
+        Effect.match({
+          onSuccess: (data) => {
+            setIds(data)
+            setLoading(false)
+          },
+          onFailure: (err) => {
+            setError(err)
+            setLoading(false)
+          },
+        }),
+      ),
+    )
+    return () => {
+      // interrupting the fiber aborts the in-flight HTTP request
+      AppRuntime.runFork(Fiber.interrupt(fiber))
+    }
+  }, [category, refreshKey])
+
+  return { ids, loading, error }
+}

package/src/index.tsx

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+import "opentui-spinner/react"
+import { App } from "./App"
+
+const renderer = await createCliRenderer({ useMouse: true })
+createRoot(renderer).render(<App />)

package/src/runtime.ts

@@ -0,0 +1,12 @@
+import { Layer, ManagedRuntime } from "effect"
+import { HnApiLive, HnTransportLive } from "./api/hn"
+import { HnTransportLinkDemo } from "./api/hnDemo"
+
+// The app's single composition point: the whole layer graph is decided here,
+// once, at the edge. Everything below runs against whatever this provides —
+// HN_DEMO=1 swaps the transport and no other file knows or cares.
+// (A real app would keep demo code out of the production bundle via separate
+// entry points; for a TUI this trade is fine.)
+const transport = process.env.HN_DEMO === "1" ? HnTransportLinkDemo : HnTransportLive
+
+export const AppRuntime = ManagedRuntime.make(HnApiLive.pipe(Layer.provide(transport)))