feat(studio): give a book its first and its last page (#2317)

A new book was a cover, a spread and a back cover, so it opened straight
onto pages 2 and 3. A bound book does not: the inside of the cover is
blank, and the first thing facing the reader is a single right-hand page,
page 1. The same at the end, where a single left-hand page sits before the
back cover. Both are laid down now, empty, in a new book and in a laid-out
one, and they are fixed the way the covers are: an inner spread only ever
goes between them.

The page numbers follow. They were counted from a spread's position in the
array, which assumed the spread after the cover was the first, and three
places did that sum on their own. One function now counts along the book,
one page for a single leaf and two for a spread, so the sheet on screen and
the label in the print view and the folio on the page all say the same
number. A book with a first page starts at 1; a book from before the first
page existed has none and keeps the numbers it always had.

client/src/components/Studio/BookSheetsView.tsx

@@ -1,6 +1,6 @@
 import type { BookDocument } from '@trek/shared'
 import { SpreadView } from './SpreadView'
-import { MARK_LENGTH, MARK_WEIGHT, sheetBox, sheetsFor, type Sheet, type SheetMode } from './bookSheets'
+import { MARK_LENGTH, MARK_WEIGHT, sheetBox, sheetsFor, type Sheet, type SheetMode, foliosOf } from './bookSheets'
 
 /**
  * The book laid out for a press.
@@ -107,7 +107,7 @@ function SheetView({
           <SpreadView
             spread={sheet.spread}
             page={doc.page}
-            spreadIndex={sheet.spreadIndex}
+            folios={foliosOf(doc.spreads, sheet.spreadIndex, doc.page.pageNumbers.startAt)}
             big
             print
           />

client/src/components/Studio/PageNumbers.tsx

@@ -1,6 +1,7 @@
 import type { BookPageSetup, BookSpread } from '@trek/shared'
 import { fontStack } from './bookFonts'
 import { folioInk } from './folioColour'
+import { isNumbered } from './bookSheets'
 
 /**
  * The folios.
@@ -17,33 +18,46 @@ import { folioInk } from './folioColour'
  * not the ones that get printed.
  *
  * The cover and the back cover carry none. A folio on a cover is a mistake in
- * every book ever bound.
+ * every book ever bound. The single first and last pages carry one each, on
+ * the side of the book they are bound on (#2317).
  */
 export function PageNumbers({
-  spread, page, spreadIndex,
+  spread, page, folios,
 }: {
   spread: BookSpread
   page: BookPageSetup
-  /** Position in the document, cover included. */
-  spreadIndex: number
+  /**
+   * The numbers this spread carries, from foliosOf: two for a spread, one for
+   * a first or last page, none for a cover. Counted by the caller, which has
+   * the whole book — a spread on its own does not know how many pages sit
+   * before it.
+   */
+  folios: readonly number[]
 }) {
   const cfg = page.pageNumbers
-  if (!cfg?.show || spread.role !== 'inner') return null
+  if (!cfg?.show || !isNumbered(spread.role) || folios.length === 0) return null
 
   /*
-   * The cover is one sheet with a front and a back, so the first inner spread
-   * opens on `startAt` — 2 by default, the page you see when you open a book
-   * whose cover is page 1. `spreadIndex` counts the cover, hence the -1.
+   * Which page of the sheet each number sits on. A spread numbers both; the
+   * first page is a right-hand leaf and the last a left-hand one, and each
+   * carries its one number on the side it actually is.
    */
-  const left = cfg.startAt + (spreadIndex - 1) * 2
-  const right = left + 1
+  const sides: Array<['left' | 'right', number]> = spread.role === 'inner'
+    ? [['left', folios[0]], ['right', folios[1]]]
+    : [[spread.role === 'first' ? 'right' : 'left', folios[0]]]
 
   const size = cfg.size
   const y = page.pageHeight - cfg.margin
 
-  /** Where the number sits on each page, given which edge it hangs from. */
+  /**
+   * Where the number sits on each page, given which edge it hangs from.
+   *
+   * A single page is one page wide, so its number sits at x 0 whichever
+   * side of the book it is bound on; the side only decides which edge is
+   * the outer one.
+   */
   const place = (side: 'left' | 'right') => {
-    const pageX = side === 'left' ? 0 : page.pageWidth
+    const pageX = side === 'left' || spread.role !== 'inner' ? 0 : page.pageWidth
     if (cfg.position === 'centre') {
       return { x: pageX, w: page.pageWidth, align: 'center' as const }
     }
@@ -58,7 +72,7 @@ export function PageNumbers({
 
   return (
     <>
-      {([['left', left], ['right', right]] as const).map(([side, number]) => {
+      {sides.map(([side, number]) => {
         const at = place(side)
         /*
          * Sampled at the middle of the number's own box, which is where the

client/src/components/Studio/SpreadView.tsx

@@ -427,7 +427,7 @@ export function ElementView({
 export function SpreadView({
   spread,
   page,
-  spreadIndex = 0,
+  folios = [],
   big = false,
   showGuides = false,
   print = false,
@@ -436,11 +436,12 @@ export function SpreadView({
   spread: BookSpread
   page: BookPageSetup
   /**
-   * Where this spread sits in the book. Only the folios need it — a page
-   * number is the one thing on the page that is a function of position rather
-   * than of the document.
+   * The page numbers this spread carries, from foliosOf. Only PageNumbers
+   * needs them — a page number is the one thing on the page that is a
+   * function of position in the book rather than of the spread itself, and
+   * the caller is the one holding the book.
    */
-  spreadIndex?: number
+  folios?: readonly number[]
   big?: boolean
   showGuides?: boolean
   /** The print renderer passes this: no guides, no placeholders, no chrome. */
@@ -470,7 +471,7 @@ export function SpreadView({
         <ElementView key={el.id} el={el} big={big} print={print} dropLabel={dropLabel} />
       ))}
 
-      <PageNumbers spread={spread} page={page} spreadIndex={spreadIndex} />
+      <PageNumbers spread={spread} page={page} folios={folios} />
 
       {showGuides && (
         <>

client/src/components/Studio/StudioCanvas.tsx

@@ -59,6 +59,7 @@ const HANDLE_POS: Record<HandleId, { left: string; top: string; cursor: string }
 export function StudioCanvas({
   spread,
   spreadIndex,
+  folios = [],
   page,
   zoom,
   pxPerMm,
@@ -71,6 +72,8 @@ export function StudioCanvas({
 }: {
   spread: BookSpread | null
   spreadIndex: number
+  /** The page numbers this spread carries, from foliosOf. */
+  folios?: readonly number[]
   page: BookPageSetup
   zoom: number
   pxPerMm: number
@@ -256,7 +259,7 @@ export function StudioCanvas({
         }}
         onPointerDown={() => select([])}
       >
-        <SpreadView spread={spread} page={page} spreadIndex={spreadIndex} big={zoom > 0.34} showGuides dropLabel={dropLabel} />
+        <SpreadView spread={spread} page={page} folios={folios} big={zoom > 0.34} showGuides dropLabel={dropLabel} />
 
         {cursors && cursors.length > 0 && (
           <PeerCursors cursors={cursors} spreadIndex={spreadIndex} zoom={zoom} />

client/src/components/Studio/StudioShell.tsx

@@ -7,6 +7,7 @@ import {
 } from 'lucide-react'
 import { useJourneyStudio } from '../../pages/journeyStudio/useJourneyStudio'
 import { PAGE_PRESET_ORDER, PAGE_PRESETS } from './pagePresets'
+import { foliosOf } from './bookSheets'
 import { StudioSidebar } from './StudioSidebar'
 import { StudioCanvas } from './StudioCanvas'
 import { StudioInspector } from './StudioInspector'
@@ -427,6 +428,7 @@ function Workbench({ s, bookView }: { s: Studio; bookView: boolean }) {
         <StudioCanvas
           spread={s.spread}
           spreadIndex={s.activeSpread}
+          folios={s.doc ? foliosOf(s.doc.spreads, s.activeSpread, s.page.pageNumbers.startAt) : []}
           page={s.page}
           zoom={s.zoom}
           pxPerMm={s.pxPerMm}

client/src/components/Studio/StudioSidebar.tsx

@@ -9,6 +9,7 @@ import { useStudioStore } from '../../store/studioStore'
 import { formatDate } from '../../utils/formatters'
 import { useToast } from '../shared/Toast'
 import { SpreadFold, SpreadView } from './SpreadView'
+import { folioLabel, foliosOf } from './bookSheets'
 import { photoSrc } from './bookRender'
 import { elementId as uid } from './bookIds'
 import { formatBookCoords, formatBookDate, type CoordFormat } from './entryText'
@@ -200,14 +201,14 @@ function PagesPanel({
                         transform: `scale(${scale})`, transformOrigin: 'top left',
                       }}
                     >
-                      <SpreadView spread={sp} page={page} spreadIndex={i} />
+                      <SpreadView spread={sp} page={page} folios={foliosOf(spreads, i, page.pageNumbers.startAt)} />
                     </div>
                     {bookView && !single && <SpreadFold page={page} scaled={pxPerMm * scale} />}
                   </div>
                   <span className="st-thumb-label">
                     {sp.role === 'cover' ? t('journey.studio.cover')
                       : sp.role === 'back' ? t('journey.studio.backCover')
-                      : `${i * 2} – ${i * 2 + 1}`}
+                      : folioLabel(foliosOf(spreads, i, page.pageNumbers.startAt))}
                   </span>
                 </button>
 

client/src/components/Studio/autoLayout.ts

@@ -1531,7 +1531,7 @@ function backSpread(input: AutoInput): BookSpread {
 }
 
 export function buildBook(input: AutoInput): BookDocument {
-  const spreads: BookSpread[] = [coverSpread(input)]
+  const spreads: BookSpread[] = [coverSpread(input), blankSpread('first')]
 
   /*
    * The summary and the countries open the book, before the entries.
@@ -1572,15 +1572,41 @@ export function buildBook(input: AutoInput): BookDocument {
     }
   }
   flushRun()
-  spreads.push(backSpread(input))
+  spreads.push(blankSpread('last'), backSpread(input))
   return {
     version: 1,
     title: input.title.slice(0, MAX_BOOK_TITLE),
-    page: input.page,
+    page: withFirstPage(input.page),
     spreads: spreads.slice(0, MAX_SPREADS),
   }
 }
 
+/**
+ * A page with nothing on it, of the given kind.
+ *
+ * The first and the last page of a book are laid down empty on purpose: the
+ * first is where a title page or a dedication goes, the last where a colophon
+ * does, and neither is something a layout should decide for a person.
+ */
+function blankSpread(role: BookSpread['role']): BookSpread {
+  return { id: uid('sp'), role, background: null, elements: [], parked: [], entryId: null }
+}
+
+/**
+ * The page setup for a book that opens on a single page.
+ *
+ * `startAt` numbers the first page inside the covers. A book from before the
+ * single first page existed opened straight onto a spread and started at 2,
+ * so that its left-hand page read as the second page of the object. With a
+ * first page in front of that spread the first page is page 1 — so a book laid
+ * out with one starts there, whatever the setup it inherited said (#2317).
+ * Nothing else of the setup is touched: the format and the folio styling are
+ * the person's, only the count moved with the page that moved.
+ */
+function withFirstPage(page: BookPageSetup): BookPageSetup {
+  return { ...page, pageNumbers: { ...page.pageNumbers, startAt: 1 } }
+}
+
 /**
  * A book nobody has laid out yet.
  *
@@ -1592,17 +1618,15 @@ export function buildBook(input: AutoInput): BookDocument {
  *
  * The covers are here rather than left out because a book has them and there is
  * no other way to add one: the pages rail only inserts inner spreads, between
- * the two. Empty, though, in the same way the page between them is.
+ * the two. The single first and last pages likewise (#2317). Empty, though, in
+ * the same way the spread between them is.
  */
 export function emptyBook(input: AutoInput): BookDocument {
-  const blank = (role: BookSpread['role']): BookSpread => ({
-    id: uid('sp'), role, background: null, elements: [], parked: [], entryId: null,
-  })
   return {
     version: 1,
     title: input.title.slice(0, MAX_BOOK_TITLE),
-    page: input.page,
-    spreads: [blank('cover'), blank('inner'), blank('back')],
+    page: withFirstPage(input.page),
+    spreads: [blankSpread('cover'), blankSpread('first'), blankSpread('inner'), blankSpread('last'), blankSpread('back')],
   }
 }
 

client/src/components/Studio/bookSheets.ts

@@ -110,6 +110,7 @@ export function sheetsFor(doc: BookDocument, mode: SheetMode): Sheet[] {
   doc.spreads.forEach((spread, spreadIndex) => {
     const single = spread.role !== 'inner'
     const spreadWidth = single ? pageWidth : pageWidth * 2
+    const folios = foliosOf(doc.spreads, spreadIndex, pageNumbers.startAt)
 
     if (single || mode === 'spreads') {
       out.push({
@@ -120,7 +121,7 @@ export function sheetsFor(doc: BookDocument, mode: SheetMode): Sheet[] {
         height: pageHeight,
         spreadWidth,
         single,
-        label: single ? '' : folioRange(spreadIndex, pageNumbers.startAt),
+        label: folioLabel(folios),
       })
       return;
     }
@@ -134,7 +135,7 @@ export function sheetsFor(doc: BookDocument, mode: SheetMode): Sheet[] {
         height: pageHeight,
         spreadWidth,
         single: true,
-        label: String(folio(spreadIndex, pageNumbers.startAt) + half),
+        label: String(folios[half]),
       })
     }
   })
@@ -142,18 +143,40 @@ export function sheetsFor(doc: BookDocument, mode: SheetMode): Sheet[] {
   return out
 }
 
-/**
- * The number the left-hand page of a spread carries.
- *
- * Mirrors PageNumbers.tsx: the first inner spread opens at `startAt`, and the
- * cover is a separate sheet, which is why the index is offset rather than used
- * raw. It is only ever a label here — nothing is printed from it.
- */
-function folio(spreadIndex: number, startAt: number): number {
-  return startAt + (spreadIndex - 1) * 2
+/** Which of a book's leaves carry a page number: everything inside the covers. */
+export function isNumbered(role: BookSpread['role']): boolean {
+  return role !== 'cover' && role !== 'back'
 }
 
-function folioRange(spreadIndex: number, startAt: number): string {
-  const left = folio(spreadIndex, startAt)
-  return `${left} – ${left + 1}`
+/**
+ * The page numbers a spread carries, in reading order.
+ *
+ * Counted along the book rather than from the index: the covers carry none,
+ * a first or last page carries one, an inner spread two, and the first
+ * numbered page is `startAt`. A book from before the single first page
+ * existed has `startAt` 2 and no such page, so its first spread still reads
+ * 2 – 3; a book laid out since has a first page and starts at 1, so that page
+ * is 1 and the same spread behind it is 2 – 3 (#2317). Either way the number
+ * follows what is in the book, not where the spread sits in the array.
+ *
+ * The renderer and the print labels both come through here, so a number seen
+ * on screen is the one that is printed.
+ *
+ * Empty for a cover, and for an index past the end.
+ */
+export function foliosOf(spreads: readonly BookSpread[], spreadIndex: number, startAt: number): number[] {
+  const spread = spreads[spreadIndex]
+  if (!spread || !isNumbered(spread.role)) return []
+  let next = startAt
+  for (let i = 0; i < spreadIndex; i++) {
+    const role = spreads[i].role
+    if (!isNumbered(role)) continue
+    next += role === 'inner' ? 2 : 1
+  }
+  return spread.role === 'inner' ? [next, next + 1] : [next]
+}
+
+/** "3", or "2 – 3" for a spread; nothing for a cover. */
+export function folioLabel(folios: readonly number[]): string {
+  return folios.length === 2 ? `${folios[0]} – ${folios[1]}` : folios.length === 1 ? String(folios[0]) : ''
 }