@gperezmz/bb-plugin-thread-glance 0.2.3 → 0.3.0

package/features/thread-list/components/controller.ts

@@ -6,9 +6,9 @@ import type { PluginSidebarSection, PluginSidebarThread } from "@get-bb/plugin-s
 import type { Stamps } from "@/shared/contract";
 import type { HarnessIcon, OrganizationMode } from "@/shared/preferences";
 import type { ThreadNotes } from "@/shared/contract";
-import type { Family } from "../model/families";
+import type { ThreadTree } from "../model/trees";
 import type { RowMenuAction } from "../model/menu";
-import type { OlderRow, ThreadRow } from "../model/view";
+import type { OlderRow, SettledRow, ThreadRow } from "../model/view";
 import type { ProviderDisplay } from "./ProviderBadge";
 
 export interface ModelInfo {
@@ -21,11 +21,7 @@ export interface RowController {
   compact: boolean;
   comfortable: boolean;
   setEditingId(id: string | null): void;
-  showPullRequests: boolean;
   harnessIcon: HarnessIcon;
-  /** Undefined while unknown; the lookup starts on first ask. */
-  defaultBranchOf(thread: PluginSidebarThread): string | null | undefined;
-  multiHost: boolean;
   /** One object per harness, the same one on every call. */
   provider(providerId: string): ProviderDisplay;
   sections: readonly PluginSidebarSection[];
@@ -33,8 +29,7 @@ export interface RowController {
   onNavigate(): void;
   onToggleChip(row: ThreadRow): void;
   onToggleOlder(row: OlderRow): void;
-  /** Opens a family's children from its "+N more" line in Needs attention. */
-  onOpenChildren(rootId: string): void;
+  onToggleSettled(row: SettledRow): void;
   onToggleEnvironment(environmentId: string): void;
   onMenuAction(action: RowMenuAction, thread: PluginSidebarThread, sectionId?: string | null): void;
   onRename(threadId: string, title: string): Promise<void>;
@@ -54,12 +49,12 @@ export interface ListLive {
   now: number;
   stamps: Stamps;
   notes: Readonly<Record<string, ThreadNotes>>;
-  familyOf(threadId: string): Family | undefined;
+  treeOf(threadId: string): ThreadTree | undefined;
 }
 
 export const ListLiveContext = createContext<ListLive>({
   now: 0,
   stamps: { startedAt: {}, finishedAt: {}, pendingAt: {}, seenAt: {} },
   notes: {},
-  familyOf: () => undefined,
+  treeOf: () => undefined,
 });

package/features/thread-list/components/glyphs.tsx

@@ -1,11 +1,11 @@
-// State glyphs, chip glyphs and header counters. They draw what the model
+// State glyphs, the child dot and header counters. They draw what the model
 // decided; tone and animation come from host token classes only.
 import { experimental_Icon as Icon } from "@get-bb/plugin-sdk/app";
 import type { PluginSidebarThreadRowStatus } from "@get-bb/plugin-sdk/app";
 import { cn } from "@/lib/utils";
 import type { Counters } from "../model/counters";
 import type { RowNote } from "../model/notes";
-import { FLAG_GLYPHS, type ChipTone, type Flag, type Glyph, type Tone } from "../model/state";
+import { dotTone, FLAG_GLYPHS, type DotTone, type Flag, type Glyph, type Tone } from "../model/state";
 
 export const TONE_CLASS: Record<Tone, string> = {
   attention: "text-attention",
@@ -18,19 +18,32 @@ export const TONE_CLASS: Record<Tone, string> = {
   none: "",
 };
 
-// The tone colour is one of bb's tokens, mixed toward the foreground for the
-// text so it clears 4.5:1 on the sidebar in both themes; the border and fill
-// are the same colour, thinned. Written out in full so the class scan sees them.
-export const CHIP_TONE_CLASS: Record<ChipTone, string> = {
-  attention:
-    "border-[color:color-mix(in_oklch,var(--attention)_45%,transparent)] bg-[color-mix(in_oklch,var(--attention)_10%,transparent)] text-[color:color-mix(in_oklch,var(--attention),var(--foreground)_55%)] hover:bg-[color-mix(in_oklch,var(--attention)_20%,transparent)]",
-  destructive:
-    "border-[color:color-mix(in_oklch,var(--destructive-text)_45%,transparent)] bg-[color-mix(in_oklch,var(--destructive-text)_10%,transparent)] text-[color:color-mix(in_oklch,var(--destructive-text),var(--foreground)_55%)] hover:bg-[color-mix(in_oklch,var(--destructive-text)_20%,transparent)]",
-  working:
-    "border-[color:color-mix(in_oklch,var(--timeline-accent)_45%,transparent)] bg-[color-mix(in_oklch,var(--timeline-accent)_10%,transparent)] text-[color:color-mix(in_oklch,var(--timeline-accent),var(--foreground)_55%)] hover:bg-[color-mix(in_oklch,var(--timeline-accent)_20%,transparent)]",
-  neutral: "border-border/70 text-muted-foreground hover:bg-state-hover hover:text-foreground",
+// The child dot's colours: the tone of the state it stands for, and the
+// unread dot's accent for unread.
+const DOT_TONE_CLASS: Record<DotTone, string> = {
+  attention: "bg-attention",
+  destructive: "bg-destructive",
+  working: "bg-[var(--timeline-accent)]",
+  unread: "bg-[var(--timeline-accent)]",
 };
 
+/**
+ * The child dot on a parent's status glyph, at its lower right corner. A
+ * ring of the sidebar's colour keeps it apart from the glyph under it.
+ */
+export function ChildDot({ flag }: { flag: Flag }) {
+  return (
+    <span
+      aria-hidden
+      data-child-dot={flag}
+      className={cn(
+        "pointer-events-none absolute -right-0.5 -bottom-0.5 size-[7px] rounded-full ring-[1.5px] ring-sidebar",
+        DOT_TONE_CLASS[dotTone(flag)],
+      )}
+    />
+  );
+}
+
 const SHINE = "animate-shine-icon motion-reduce:animate-none";
 const SPIN = "animate-spin motion-reduce:animate-none";
 
@@ -47,6 +60,18 @@ export function UnreadDot({ label, className }: { label?: string; className?: st
   );
 }
 
+// The Idle state's ring: uncoloured, smaller than the column and thinned, so
+// it reads as status yet stays fainter than the unread dot and the draft
+// pencil. Screen readers skip it, so an Idle row announces what it did before.
+export function IdleRing({ className }: { className?: string }) {
+  return (
+    <span
+      aria-hidden
+      className={cn("inline-block size-2.5 shrink-0 rounded-full border-[1.5px] border-current opacity-50", className)}
+    />
+  );
+}
+
 export function GlyphIcon({
   glyph,
   label,
@@ -56,7 +81,7 @@ export function GlyphIcon({
   label?: string;
   className?: string;
 }) {
-  if (glyph.icon === null) return null;
+  if (glyph.icon === "ring") return <IdleRing className={TONE_CLASS[glyph.tone]} />;
   if (glyph.icon === "dot") return <UnreadDot label={label} />;
   return (
     <Icon

package/features/thread-list/data/same-window.ts

@@ -0,0 +1,34 @@
+// The list and the settings panel mount apart, each with its own copy of the
+// preferences. A change made in one reaches the other here, in the same
+// window, at once; the server and localStorage stay what other windows read.
+import { useCallback, useEffect } from "react";
+
+type Apply<Patch> = (patch: Patch) => void;
+
+export function sameWindow<Patch>(): Set<Apply<Patch>> {
+  return new Set();
+}
+
+/**
+ * Joins this copy to `copies` for as long as it is mounted.
+ *
+ * Returns the call that hands a patch this copy made to every other copy.
+ */
+export function useSameWindow<State extends object>(
+  copies: Set<Apply<Partial<State>>>,
+  setState: (update: (current: State) => State) => void,
+): Apply<Partial<State>> {
+  const apply = useCallback((patch: Partial<State>) => setState((current) => ({ ...current, ...patch })), [setState]);
+  useEffect(() => {
+    copies.add(apply);
+    return () => {
+      copies.delete(apply);
+    };
+  }, [copies, apply]);
+  return useCallback(
+    (patch: Partial<State>) => {
+      for (const other of copies) if (other !== apply) other(patch);
+    },
+    [copies, apply],
+  );
+}

package/features/thread-list/data/useAutoExpand.ts

@@ -1,7 +1,7 @@
 // Transient auto-expansion. Transitions are diffed against the previous
 // render, as bb does; nothing here is persisted.
 import { useCallback, useRef, useState } from "react";
-import type { Forest } from "../model/families";
+import type { Forest } from "../model/trees";
 import {
   detectTransitions,
   mergeTargets,

package/features/thread-list/data/useClientPreferences.ts

@@ -5,16 +5,24 @@ import {
   parseClientPreferences,
   type ClientPreferences,
 } from "@/shared/preferences";
+import { sameWindow, useSameWindow } from "./same-window";
 import { readJson, writeJson } from "./storage";
 
+const copies = sameWindow<Partial<ClientPreferences>>();
+
 export function useClientPreferences(): [ClientPreferences, (patch: Partial<ClientPreferences>) => void] {
   const [value, setValue] = useState(() => parseClientPreferences(readJson(CLIENT_PREFERENCES_STORAGE_KEY)));
-  const update = useCallback((patch: Partial<ClientPreferences>) => {
-    setValue((current) => {
-      const next = { ...current, ...patch };
-      writeJson(CLIENT_PREFERENCES_STORAGE_KEY, next);
-      return next;
-    });
-  }, []);
+  const tellOthers = useSameWindow(copies, setValue);
+  const update = useCallback(
+    (patch: Partial<ClientPreferences>) => {
+      setValue((current) => {
+        const next = { ...current, ...patch };
+        writeJson(CLIENT_PREFERENCES_STORAGE_KEY, next);
+        return next;
+      });
+      tellOthers(patch);
+    },
+    [tellOthers],
+  );
   return [value, update];
 }

package/features/thread-list/data/useDefaultBranches.ts

@@ -0,0 +1,35 @@
+// Each project's default branch, looked up once per list through the
+// machine of the project's default source.
+//
+// Debt: the answers are kept in component state, with no refresh, because
+// the SDK offers no cached query for a project's branches. It clears when
+// the SDK does, or when a default branch changing mid-session matters.
+import { useEffect, useRef, useState } from "react";
+import { useSdk } from "@get-bb/plugin-sdk/app";
+import { defaultSourceHostId } from "../model/branches";
+
+/** Project id → default branch; undefined while unknown, null when the lookup found none. */
+export type DefaultBranches = ReadonlyMap<string, string | null>;
+
+export function useDefaultBranches(projectIds: readonly string[]): DefaultBranches {
+  const sdk = useSdk();
+  const [branches, setBranches] = useState<DefaultBranches>(() => new Map());
+  const requested = useRef(new Set<string>());
+  useEffect(() => {
+    for (const projectId of projectIds) {
+      if (requested.current.has(projectId)) continue;
+      requested.current.add(projectId);
+      const settle = (branch: string | null) => setBranches((current) => new Map(current).set(projectId, branch));
+      sdk.projects
+        .get({ projectId })
+        .then(async (project) => {
+          const hostId = defaultSourceHostId(project.sources);
+          if (hostId === null) return null;
+          const result = await sdk.projects.branches({ projectId, hostId, limit: "1" });
+          return result.defaultBranch ?? null;
+        })
+        .then(settle, () => settle(null));
+    }
+  }, [projectIds, sdk]);
+  return branches;
+}

package/features/thread-list/data/usePreferences.ts

@@ -14,10 +14,16 @@ import {
   type PreferenceKey,
   type Preferences,
 } from "@/shared/preferences";
+import { sameWindow, useSameWindow } from "./same-window";
 import { readJson, writeJson } from "./storage";
 
 const WRITE_DEBOUNCE_MS = 150;
 
+const copies = sameWindow<Partial<Preferences>>();
+// Writes not yet sent, whichever copy made them: a reload or an echo in any
+// copy must not put back the value one of them replaced.
+const pending = new Map<PreferenceKey, unknown>();
+
 export interface PreferencesState {
   prefs: Preferences;
   /** The server's values have arrived (or failed; the mirror stands in). */
@@ -31,7 +37,6 @@ export function usePreferences(): PreferencesState {
     coercePreferences(readJson(PREFERENCES_MIRROR_STORAGE_KEY)),
   );
   const [hydrated, setHydrated] = useState(false);
-  const pending = useRef(new Map<PreferenceKey, unknown>());
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const connection = useRealtimeConnectionState();
   const wasConnected = useRef(false);
@@ -41,7 +46,7 @@ export function usePreferences(): PreferencesState {
       const { preferences } = await rpc.call("listPreferences", null);
       const next = coercePreferences(preferences);
       // Keys with a write in flight keep the local value.
-      for (const [key, value] of pending.current) (next as Record<string, unknown>)[key] = value;
+      for (const [key, value] of pending) (next as Record<string, unknown>)[key] = value;
       setPrefs(next);
       writeJson(PREFERENCES_MIRROR_STORAGE_KEY, next);
     } finally {
@@ -73,7 +78,7 @@ export function usePreferences(): PreferencesState {
 
   useRealtime(CHANNELS.preferences, (payload) => {
     const signal = payload as PreferenceSignal;
-    if (!isPreferenceKey(signal?.key) || pending.current.has(signal.key)) return;
+    if (!isPreferenceKey(signal?.key) || pending.has(signal.key)) return;
     const parsed = parsePreference(signal.key, signal.value);
     if (!parsed.success) return;
     setPrefs((current) => {
@@ -84,8 +89,8 @@ export function usePreferences(): PreferencesState {
   });
 
   const flush = useCallback(() => {
-    const writes = [...pending.current];
-    pending.current.clear();
+    const writes = [...pending];
+    pending.clear();
     for (const [key, value] of writes) {
       rpc.call("setPreference", { key, value }).catch((error: unknown) => {
         toast.error(`Couldn't save the ${key} setting`, {
@@ -103,6 +108,9 @@ export function usePreferences(): PreferencesState {
     [flush],
   );
 
+  // Another copy's change arrives already mirrored and on its way to the server.
+  const tellOthers = useSameWindow(copies, setPrefs);
+
   const update = useCallback(
     (patch: Partial<Preferences>) => {
       setPrefs((current) => {
@@ -110,8 +118,9 @@ export function usePreferences(): PreferencesState {
         writeJson(PREFERENCES_MIRROR_STORAGE_KEY, next);
         return next;
       });
+      tellOthers(patch);
       for (const [key, value] of Object.entries(patch)) {
-        if (isPreferenceKey(key)) pending.current.set(key, value);
+        if (isPreferenceKey(key)) pending.set(key, value);
       }
       if (timer.current !== null) clearTimeout(timer.current);
       timer.current = setTimeout(() => {
@@ -119,7 +128,7 @@ export function usePreferences(): PreferencesState {
         flush();
       }, WRITE_DEBOUNCE_MS);
     },
-    [flush],
+    [flush, tellOthers],
   );
 
   return { prefs, hydrated, update };

package/features/thread-list/data/usePullRequestAnswers.ts

@@ -0,0 +1,36 @@
+// The pull request lookups that answered, by thread id. Answers arriving in
+// one burst (a list's worth of lookups on load) land in one state update.
+//
+// Debt: this copies server state the host's per-row pull request hook owns,
+// because settling reads every thread's pull request at once and the SDK
+// offers no query over many threads. It clears when the SDK does.
+import { useCallback, useRef, useState } from "react";
+import type { PullRequestState } from "../model/settled";
+
+export type PullRequestAnswers = ReadonlyMap<string, PullRequestState | null>;
+
+export function usePullRequestAnswers(): [PullRequestAnswers, (threadId: string, state: PullRequestState | null) => void] {
+  const [answers, setAnswers] = useState<PullRequestAnswers>(() => new Map());
+  const pending = useRef(new Map<string, PullRequestState | null>());
+  const scheduled = useRef(false);
+  const onAnswer = useCallback((threadId: string, state: PullRequestState | null) => {
+    pending.current.set(threadId, state);
+    if (scheduled.current) return;
+    scheduled.current = true;
+    setTimeout(() => {
+      scheduled.current = false;
+      const batch = pending.current;
+      pending.current = new Map();
+      setAnswers((current) => {
+        let next: Map<string, PullRequestState | null> | null = null;
+        for (const [id, value] of batch) {
+          if (current.has(id) && current.get(id) === value) continue;
+          next ??= new Map(current);
+          next.set(id, value);
+        }
+        return next ?? current;
+      });
+    }, 0);
+  }, []);
+  return [answers, onAnswer];
+}

package/features/thread-list/data/useSystemFacts.ts

@@ -0,0 +1,52 @@
+// What Thread Glance reads of bb's own configuration: its default harness
+// and its primary machine. Asked once per list; null until answered.
+import { useEffect, useState } from "react";
+import { useSdk } from "@get-bb/plugin-sdk/app";
+
+export interface SystemFacts {
+  /** The harness a new thread starts with, when bb says. */
+  defaultProviderId: string | null;
+  /** The machine bb itself runs on, when one is connected. */
+  primaryHostId: string | null;
+}
+
+export const UNKNOWN_SYSTEM: SystemFacts = { defaultProviderId: null, primaryHostId: null };
+
+interface SystemConfig {
+  primaryHostId: string | null;
+  generalSettings: { defaultProviderId: string | null };
+  serverAccess: { defaultProviderId: string };
+}
+
+/**
+ * The facts in `system.config()`'s answer. The default harness is the one
+ * the user chose in bb's settings, else the one bb falls back to.
+ */
+export function readSystemFacts(config: SystemConfig): SystemFacts {
+  return {
+    defaultProviderId: config.generalSettings.defaultProviderId ?? config.serverAccess.defaultProviderId ?? null,
+    primaryHostId: config.primaryHostId,
+  };
+}
+
+export function useSystemFacts(): SystemFacts {
+  const sdk = useSdk();
+  const [facts, setFacts] = useState<SystemFacts>(UNKNOWN_SYSTEM);
+  useEffect(() => {
+    let cancelled = false;
+    // Called inside the chain, so a host that throws for an area it lacks
+    // lands in the rejection handler and leaves the facts unknown.
+    Promise.resolve()
+      .then(() => sdk.system.config())
+      .then(
+        (config) => {
+          if (!cancelled) setFacts(readSystemFacts(config));
+        },
+        () => undefined,
+      );
+    return () => {
+      cancelled = true;
+    };
+  }, [sdk]);
+  return facts;
+}

package/features/thread-list/icons.ts

@@ -24,8 +24,8 @@ export const ICONS = {
   moveUp: "ChevronUp",
   newThread: "Plus",
   newSection: "SectionAdd",
-  settings: "Settings",
   customize: "SlidersHorizontal",
+  settings: "SlidersHorizontal",
   check: "Check",
   pullRequest: "GitPullRequest",
   branch: "GitBranch",

package/features/thread-list/model/attention.ts

@@ -1,9 +1,8 @@
-// What needs attention, thread by thread. The Needs attention section, the header
-// counters, the section's order and auto-reveal all read the set this
+// What needs attention, thread by thread. Collapsed groups, the header
+// counters, the need-you filter and auto-reveal all read the set this
 // builds. Pure.
 import type { PluginSidebarThread } from "@get-bb/plugin-sdk/app";
 import type { ChildAttention } from "@/shared/preferences";
-import type { Family, Forest } from "./families";
 import { type Flag, type StateKind, type ThreadState } from "./state";
 
 /** The flags that count for a root thread. Working is not one. */
@@ -88,66 +87,3 @@ export function revealsOn(attention: ReadonlySet<Flag>, isRoot: boolean): boolea
   if (attention.has("waits-on-you") || attention.has("unread-failed")) return true;
   return !isRoot && attention.has("queue-failed");
 }
-
-/** What the section reads of a family. */
-export type SectionFamily = Pick<Family, "root" | "attentionFlags" | "latestAttentionAt">;
-
-/** What Needs attention remembers between renders: the family it holds, and the family that was open. */
-export interface AttentionHold {
-  /**
-   * The family held in the section, if any, as it was when opened. The section
-   * orders it by this, so nothing that happens inside it moves it.
-   */
-  held: SectionFamily | null;
-  /** The root of the family the open thread belonged to at the last render, if any. */
-  openRootId: string | null;
-}
-
-export const NO_HOLD: AttentionHold = { held: null, openRootId: null };
-
-/**
- * Whether a family is in the Needs attention section: it is the held family, or one
- * of its threads needs attention and none of them is open. Nothing moves while you
- * are inside a family, so the open family only enters by being judged when
- * opened (see `holdAttention`).
- */
-export function inAttention(family: SectionFamily, heldRootId: string | null, openRootId: string | null): boolean {
-  const rootId = family.root.thread.id;
-  if (rootId === heldRootId) return true;
-  return family.attentionFlags.size > 0 && rootId !== openRootId;
-}
-
-/**
- * Whether a family is attended: held in the section with nothing in it needing
- * attention any more. It keeps its place and draws and counts as in its home group.
- */
-export function isAttended(family: SectionFamily, heldRootId: string | null): boolean {
-  return family.root.thread.id === heldRootId && family.attentionFlags.size === 0;
-}
-
-/**
- * The hold after a render. A family is judged when a thread in it is opened
- * from outside it: it is held if something in it needs attention then, and it stays
- * held while one of its threads is open, after nothing in it needs attention any
- * more, until none of its threads is open. An attended family whose open thread
- * is archived counts as closed. A family that does not need attention
- * when opened is not pulled in later, whatever happens in it; nor is one
- * that never needed attention. Opening another thread of the open family judges
- * nothing again.
- */
-export function holdAttention(
-  previous: AttentionHold,
-  forest: Pick<Forest, "infos" | "familyOf">,
-  activeThreadId: string | null,
-): AttentionHold {
-  if (activeThreadId === null) return NO_HOLD;
-  const openFamily = forest.familyOf.get(activeThreadId);
-  if (openFamily === undefined) return NO_HOLD;
-  const openRootId = openFamily.root.thread.id;
-  if (openRootId === previous.openRootId) {
-    const archived = forest.infos.get(activeThreadId)?.thread.isArchived ?? false;
-    const held = previous.held?.root.thread.id === openRootId && !(archived && openFamily.attentionFlags.size === 0);
-    return held ? previous : { held: null, openRootId };
-  }
-  return { held: openFamily.attentionFlags.size > 0 ? openFamily : null, openRootId };
-}

package/features/thread-list/model/branches.ts

@@ -0,0 +1,27 @@
+// The project's default branch, and whether a thread's branch is another
+// one. Pure.
+
+/** A project source as `projects.get` returns it, narrowed to what the lookup reads. */
+export interface ProjectSourceRef {
+  hostId: string;
+  isDefault: boolean;
+}
+
+/**
+ * The machine to ask for a project's default branch: its default source's,
+ * else its first source's. Null when the project has no source, as a
+ * personal project may not. A thread's own machine may have no source for
+ * the project, and bb answers 404 there.
+ */
+export function defaultSourceHostId(sources: readonly ProjectSourceRef[]): string | null {
+  return (sources.find((source) => source.isDefault) ?? sources[0])?.hostId ?? null;
+}
+
+/**
+ * Whether a thread's branch is known to differ from its project's default:
+ * `defaultBranch` is undefined while the lookup runs and null when it found
+ * none, and in both cases the branch is not known to differ.
+ */
+export function isOffDefaultBranch(branch: string | null, defaultBranch: string | null | undefined): branch is string {
+  return branch !== null && typeof defaultBranch === "string" && branch !== defaultBranch;
+}

package/features/thread-list/model/counters.ts

@@ -1,5 +1,5 @@
 // Group header counters. Pure.
-import type { Family } from "./families";
+import type { ThreadTree } from "./trees";
 
 export interface Counters {
   waitsOnYou: number;
@@ -13,16 +13,16 @@ export interface Counters {
 export const EMPTY_COUNTERS: Counters = { waitsOnYou: 0, failed: 0, offline: 0, working: 0, unread: 0 };
 
 /**
- * Counts the threads in the families. A thread counts what its Needs attention
+ * Counts the threads in the trees. A thread counts what its Needs attention
  * flags say, so a child adds to waits-on-you, failed, offline and unread only
  * as "Needs attention counts every child" lets it; working counts every thread that
  * runs. Hidden threads carry only waits-on-you and unread-failed flags
  * already; archived threads never count.
  */
-export function countFamilies(families: readonly Family[]): Counters {
+export function countTrees(trees: readonly ThreadTree[]): Counters {
   const counters = { ...EMPTY_COUNTERS };
-  for (const family of families) {
-    for (const info of [family.root, ...family.descendants]) {
+  for (const tree of trees) {
+    for (const info of [tree.root, ...tree.descendants]) {
       if (info.thread.isArchived) continue;
       const flags = info.attentionFlags;
       if (flags.has("waits-on-you")) counters.waitsOnYou += 1;

package/features/thread-list/model/details.ts

@@ -1,5 +1,5 @@
 // Hover card and details drawer content. Pure.
-import type { Family, ThreadInfo } from "./families";
+import type { ThreadTree, ThreadInfo } from "./trees";
 import type { StateKind } from "./state";
 
 const SUMMARY_ORDER: readonly [StateKind, string][] = [
@@ -29,13 +29,13 @@ export function childSummary(descendants: readonly ThreadInfo[]): string | null
   return parts.length > 0 ? parts.join(", ") : null;
 }
 
-/** Descendants of `id` inside its family, for the card of any row. */
-export function descendantsOf(family: Family | undefined, id: string): ThreadInfo[] {
-  if (family === undefined) return [];
-  if (family.root.thread.id === id) return family.descendants;
+/** Descendants of `id` inside its tree, for the card of any row. */
+export function descendantsOf(tree: ThreadTree | undefined, id: string): ThreadInfo[] {
+  if (tree === undefined) return [];
+  if (tree.root.thread.id === id) return tree.descendants;
   const result: ThreadInfo[] = [];
   const within = new Set([id]);
-  for (const info of family.descendants) {
+  for (const info of tree.descendants) {
     if (info.parentId !== null && within.has(info.parentId)) {
       within.add(info.thread.id);
       result.push(info);

package/features/thread-list/model/expansion.ts

@@ -1,13 +1,13 @@
 // Auto-expansion: transitions found by diffing snapshots, and the
 // transient targets they leave behind. Pure.
 import { revealsOn } from "./attention";
-import type { Forest } from "./families";
+import type { Forest } from "./trees";
 
 /**
- * `reveal` targets open their group, their `N older` fold and the parent
- * chips on their path. `open` targets (a thread that newly became unread)
- * open the group and the fold only, so finished children don't expand
- * their parent's chip.
+ * `reveal` targets open the parent chips on their path. `open` targets (a
+ * thread that newly became unread) open no chip, so finished children don't
+ * expand their parent's. The open thread's target, of either kind, also
+ * opens its collapsed group. No target opens a settled fold.
  */
 export type TargetKind = "reveal" | "open";
 export type Targets = ReadonlyMap<string, TargetKind>;

package/features/thread-list/model/groups.ts

@@ -1,4 +1,4 @@
-// Top-level groups: which group a family lands in, and the order
+// Top-level groups: which group a tree lands in, and the order
 // groups appear in. Pure.
 import type {
   PluginSidebarProject,
@@ -43,7 +43,7 @@ export function personalProject(
 }
 
 /**
- * The group a family root belongs to. Pinned roots go to Pinned. A root
+ * The group a tree root belongs to. Pinned roots go to Pinned. A root
  * whose project, section or machine isn't known goes to the loose Threads
  * bucket, except an unknown section, which gets a placeholder group as in
  * bb.