masto/timelines: better documentation

src/masto/timelines.ts

@@ -7,6 +7,7 @@ import {
   createEffect,
   createResource,
   untrack,
+  type Resource,
   type ResourceFetcherInfo,
 } from "solid-js";
 import { createStore } from "solid-js/store";
@@ -19,7 +20,7 @@ type TimelineParamsOf<T> = T extends Timeline<infer P> ? P : never;
 
 export function createTimelineControlsForArray(
   status: () => mastodon.v1.Status[] | undefined,
-) {
+): TimelineControls {
   const lookup = new ReactiveMap<string, TreeNode<mastodon.v1.Status>>();
 
   const [threads, setThreads] = createStore([] as mastodon.v1.Status["id"][]);
@@ -84,7 +85,10 @@ export function createTimelineControlsForArray(
 
 export function createTimelineSnapshot<
   T extends Timeline<mastodon.DefaultPaginationParams>,
->(timeline: Accessor<T>, limit: Accessor<number>) {
+>(
+  timeline: Accessor<T>,
+  limit: Accessor<number>,
+): TimelineResource<mastodon.v1.Status[] | undefined> {
   const [shot, { refetch }] = createResource(
     () => [timeline(), limit()] as const,
     async ([tl, limit]) => {
@@ -198,9 +202,51 @@ function createTimelineChunk<
   );
 }
 
+export type TimelineControls = {
+  /**
+   * The threads.
+   *
+   * The identifiers here is the most-bottom toot id in the thread.
+   *
+   * @see You can use {@link TimelineControls.get} and {@link TimelineControls.getPath} to resolve them if
+   * the context is needed.
+   */
+  list: readonly mastodon.v1.Status["id"][];
+  /**
+   * Get the single node.
+   */
+  get(id: string): TreeNode<mastodon.v1.Status> | undefined;
+  /**
+   * Collect the path from the node to the most-top node.
+   */
+  getPath(id: string): TreeNode<mastodon.v1.Status>[] | undefined;
+  /**
+   * Set the node value.
+   */
+  set(id: string, value: mastodon.v1.Status): void;
+};
+
+export type TimelineResource<
+  R,
+> = [
+  TimelineControls,
+  Resource<R>,
+  { refetch(info?: TimelineFetchDirection): void },
+];
+
+/**
+ * Create auto managed timeline controls.
+ *
+ * The error from the resource is not thrown in the
+ * {@link TimelineControls.list} and {@link TimelineControls}.get*.
+ * Use the second value from {@link TimelineResource} to catch the error.
+ */
 export function createTimeline<
   T extends Timeline<mastodon.DefaultPaginationParams>,
->(timeline: Accessor<T>, params: Accessor<TimelineParamsOf<T>>) {
+>(
+  timeline: Accessor<T>,
+  params: Accessor<TimelineParamsOf<T>>,
+): TimelineResource<TimelineChunk<TimelineParamsOf<T>> | undefined> {
   const lookup = new ReactiveMap<string, TreeNode<mastodon.v1.Status>>();
   const [threads, setThreads] = createStore([] as mastodon.v1.Status["id"][]);
 

src/timelines/TootList.tsx

@@ -18,7 +18,7 @@ import { findElementActionable } from "./RegularToot";
 
 const TootList: Component<{
   ref?: Ref<HTMLDivElement>;
-  threads: string[];
+  threads: readonly string[];
   onUnknownThread: (id: string) => { value: mastodon.v1.Status }[] | undefined;
   onChangeToot: (id: string, value: mastodon.v1.Status) => void;
 }> = (props) => {

src/timelines/TrendTimelinePanel.tsx

@@ -40,7 +40,7 @@ const TrendTimelinePanel: Component<{
       <PullDownToRefresh
         linkedElement={scrollLinked()}
         loading={snapshot.loading}
-        onRefresh={() => refetchTimeline({ direction: "new" })}
+        onRefresh={() => refetchTimeline("next")}
       />
       <div
         ref={(e) =>