app/lib/writing/binder.ts

Functions

Imports

It imports app/lib/kind-words.ts, app/lib/novels/layout.ts. Imported by app/components/writing/binder.tsx, app/lib/binder.server.ts, app/routes/book.corkboard.tsx, app/routes/book.file.tsx, app/routes/book.tsx, app/routes/editor.tsx.

Source

1// The binder (design 4.1, ruling point 7): a book as one tree, and what a reorder in it means in Git.
2// Order lives in the NN- prefix of each chapter folder and scene file, so moving a scene or a chapter
3// is renaming: every chapter and scene after the drop point is renumbered, and all the renames go in
4// one commit. Pure, so the browser, the server and the tests share it.
5
6import { kindPlural } from "~/lib/kind-words";
7import { chapterOf, kindOf, readingOrder, titleFromSegment, type Meta } from "~/lib/novels/layout";
8
9/** A row of the binder as the loader sends it; the page turns `meta` into the row's muted note. */
10export type BinderNode = { id: string; label: string; href?: string; meta?: string; children?: BinderNode[] };
11
12/** One chapter in a desired order: its folder as it is now, and its scenes' paths as they are now. */
13export type ChapterOrder = { chapter: string; scenes: string[] };
14
15export type Rename = { from: string; to: string };
16
17const NUMBERED = /^(\d{2,3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
18
19export const ROOT = { chapters: "group:chapters", bible: "group:bible", outline: "group:outline", notes: "group:notes" } as const;
20const chapterId = (slug: string) => `ch:${slug}`;
21export const fileId = (path: string) => `f:${path}`;
22const pathOf = (id: string) => (id.startsWith("f:") ? id.slice(2) : null);
23const chapterOfId = (id: string) => (id.startsWith("ch:") ? id.slice(3) : null);
24
25type IndexedLike = { path: string; words: number; meta: Meta };
26
27const entryName = (meta: Meta) => (meta.kind === "character" || meta.kind === "place" || meta.kind === "rule" ? meta.entry.name : "");
28
29const fileName = (path: string) => path.split("/").pop()!.replace(/\.md$/, "");
30const words = (n: number) => `${n.toLocaleString("en-US")} word${n === 1 ? "" : "s"}`;
31
32/** The book as the binder shows it: title page, chapters and their scenes, bible, outline, notes. */
33export function binderTree(files: IndexedLike[], base: string): BinderNode[] {
34  const href = (path: string) => `${base}/f/${path}`;
35  const nodes: BinderNode[] = [];
36  if (files.some((f) => f.path === "book.md")) nodes.push({ id: fileId("book.md"), label: "Title page", href: href("book.md") });
37
38  const chapters: BinderNode[] = [];
39  for (const scene of readingOrder(files)) {
40    const slug = chapterOf(scene.path)!;
41    let chapter = chapters.at(-1);
42    if (!chapter || chapter.id !== chapterId(slug)) {
43      chapter = { id: chapterId(slug), label: titleFromSegment(slug), href: `${base}/c/${slug}`, children: [] };
44      chapters.push(chapter);
45    }
46    // An index row from before the status key has no status until it is read again.
47    const status = scene.meta.kind === "scene" ? (scene.meta.header.status ?? "") : "";
48    chapter.children!.push({ id: fileId(scene.path), label: titleFromSegment(fileName(scene.path)), href: href(scene.path), meta: [status, words(scene.words)].filter(Boolean).join(", ") });
49  }
50  for (const c of chapters) {
51    const total = files.filter((f) => chapterOf(f.path) === chapterOfId(c.id)).reduce((n, f) => n + f.words, 0);
52    c.meta = words(total);
53  }
54  nodes.push({ id: ROOT.chapters, label: "Chapters", children: chapters });
55
56  const bible = (folder: string, label: string): BinderNode => ({
57    id: `group:bible-${folder}`,
58    label,
59    children: files
60      .filter((f) => f.path.startsWith(`bible/${folder}/`))
61      .map((f) => ({ id: fileId(f.path), label: entryName(f.meta) || titleFromSegment(fileName(f.path)), href: href(f.path) })),
62  });
63  nodes.push({ id: ROOT.bible, label: "Bible", children: [bible("characters", "Characters"), bible("places", "Places"), bible("rules", "World rules")] });
64  const flat = (top: "outline" | "notes", id: string, label: string): BinderNode => ({
65    id,
66    label,
67    children: files.filter((f) => f.path.startsWith(`${top}/`)).map((f) => ({ id: fileId(f.path), label: titleFromSegment(fileName(f.path)), href: href(f.path) })),
68  });
69  nodes.push(flat("outline", ROOT.outline, "Outline"));
70  nodes.push(flat("notes", ROOT.notes, "Notes"));
71  return nodes;
72}
73
74/** Only scenes and chapters move: a scene into any chapter, a chapter among the chapters. */
75export function canMoveTo(id: string, parent: string | null): boolean {
76  const path = pathOf(id);
77  if (path && kindOf(path) === "scene") return parent !== null && parent.startsWith("ch:");
78  if (chapterOfId(id)) return parent === ROOT.chapters;
79  return false;
80}
81
82/** The order a binder tree shows, read back as chapters and their scenes. */
83export function orderFromTree(nodes: readonly BinderNode[]): ChapterOrder[] {
84  const chapters = nodes.find((n) => n.id === ROOT.chapters)?.children ?? [];
85  return chapters.map((c) => ({ chapter: chapterOfId(c.id) ?? "", scenes: (c.children ?? []).map((s) => pathOf(s.id) ?? "") }));
86}
87
88/** The order the index holds now. */
89export function currentOrder(paths: string[]): ChapterOrder[] {
90  const out: ChapterOrder[] = [];
91  for (const scene of readingOrder(paths.map((path) => ({ path })))) {
92    const chapter = chapterOf(scene.path)!;
93    if (out.at(-1)?.chapter !== chapter) out.push({ chapter, scenes: [] });
94    out.at(-1)!.scenes.push(scene.path);
95  }
96  return out;
97}
98
99const numbered = (i: number, width: number, name: string) => `${String(i + 1).padStart(width, "0")}-${name}`;
100const nameOf = (segment: string) => NUMBERED.exec(segment)?.[2] ?? segment;
101
102/**
103 * The renames that turn the book's current order into `desired`. The desired order must hold exactly
104 * the chapters and scenes there are now, each once; anything else means the page was out of date.
105 * Chapters and scenes are numbered from 01 in their new order, keeping their names; a chapter left
106 * with no scenes has no folder in Git, so it drops out and the rest close up.
107 */
108export function planRenames(paths: string[], desired: ChapterOrder[]): { ok: true; renames: Rename[] } | { ok: false; error: string } {
109  const now = currentOrder(paths);
110  const chapters = new Set(now.map((c) => c.chapter));
111  const scenes = new Set(now.flatMap((c) => c.scenes));
112  const stale = { ok: false as const, error: "The book changed since this page was loaded. Reload it and move again." };
113
114  const seenChapters = new Set<string>();
115  const seenScenes = new Set<string>();
116  for (const c of desired) {
117    if (!chapters.has(c.chapter) || seenChapters.has(c.chapter)) return stale;
118    seenChapters.add(c.chapter);
119    for (const s of c.scenes) {
120      if (!scenes.has(s) || seenScenes.has(s)) return stale;
121      seenScenes.add(s);
122    }
123  }
124  if (seenChapters.size !== chapters.size || seenScenes.size !== scenes.size) return stale;
125
126  const kept = desired.filter((c) => c.scenes.length > 0);
127  const chapterWidth = Math.max(2, String(kept.length).length);
128  const renames: Rename[] = [];
129  kept.forEach((c, i) => {
130    const folder = numbered(i, chapterWidth, nameOf(c.chapter));
131    const sceneWidth = Math.max(2, String(c.scenes.length).length);
132    c.scenes.forEach((from, j) => {
133      const to = `chapters/${folder}/${numbered(j, sceneWidth, nameOf(fileName(from)))}.md`;
134      if (to !== from) renames.push({ from, to });
135    });
136  });
137  return { ok: true, renames };
138}
139
140/** The desired order with one chapter's scenes put in `order` (the corkboard's move). */
141export function withChapterOrder(paths: string[], chapter: string, order: string[]): ChapterOrder[] {
142  return currentOrder(paths).map((c) => (c.chapter === chapter ? { chapter, scenes: order } : c));
143}
144
145/** The first sentence of a scene's text, for a card with no summary: at most 160 characters. */
146export function firstSentence(body: string): string {
147  const text = body.replace(/^#+\s.*$/gm, "").replace(/\s+/g, " ").trim();
148  const sentence = /^.+?[.!?](?=\s|$)/.exec(text)?.[0] ?? text;
149  return sentence.length > 160 ? `${sentence.slice(0, 159).trimEnd()}...` : sentence;
150}
151
152/** The order a form posted as JSON, or null when it is not a list of chapters with scene paths. */
153export function parseOrder(raw: string): ChapterOrder[] | null {
154  let value: unknown;
155  try {
156    value = JSON.parse(raw);
157  } catch {
158    return null;
159  }
160  if (!Array.isArray(value) || value.length > 500) return null;
161  const out: ChapterOrder[] = [];
162  for (const c of value) {
163    if (!c || typeof c !== "object") return null;
164    const { chapter, scenes } = c as Record<string, unknown>;
165    if (typeof chapter !== "string" || !Array.isArray(scenes) || !scenes.every((s) => typeof s === "string")) return null;
166    out.push({ chapter, scenes: scenes as string[] });
167  }
168  return out;
169}
170
171/**
172 * A site project's binder: its writing grouped by kind (posts, pages and the rest), newest first, each
173 * with its state. Series join it when the site-api contract carries them (ruling point 5, build step
174 * 7); until then there is nothing to order, so a site's binder only finds and opens.
175 */
176export function siteBinderTree(items: { itemId: string; kind: string; title: string; status: string }[], base: string): BinderNode[] {
177  const kinds = [...new Set(items.map((i) => i.kind))].sort((a, b) => (a === "post" ? -1 : b === "post" ? 1 : a < b ? -1 : 1));
178  return kinds.map((kind) => ({
179    id: `kind:${kind}`,
180    label: kindPlural(kind),
181    children: items
182      .filter((i) => i.kind === kind)
183      .map((i) => ({ id: `item:${i.itemId}`, label: i.title || i.itemId, href: `${base}/e/${encodeURIComponent(i.itemId)}`, meta: i.status.charAt(0).toUpperCase() + i.status.slice(1) })),
184  }));
185}