feat(shared): a laid page knows which decorated template it is

matchDecoratedTemplate reads a page's elements by kind and frame, rounded
to the millimetre, and compares them with every template laid on the same
page format: a template is the page's when nearly all of its design is
there and it explains most of the page, and of those the one explaining the
most wins. A page rearranged by hand reads as none. The auto layout's
"this spread" uses it to offer a template other than the one on screen.
This commit is contained in:
Maurice
2026-10-24 19:34:00 +02:00
parent 6254510e0f
commit d51b9de2b0
2 changed files with 170 additions and 0 deletions
@@ -0,0 +1,79 @@
import { bookPageSetupForPreset } from '../book-pages';
import { bookPhotoElementSchema, type BookSpread } from '../book.schema';
import { bookThemeOf } from '../theme/book-theme';
import { applyDecoratedTemplate } from './template-apply';
import { BOOK_DECORATED_TEMPLATES } from './template-catalogue';
import { matchDecoratedTemplate } from './template-match';
import { describe, expect, it } from 'vitest';
/** A laid page knows which decorated template it is. */
const words = {
title: { text: 'Portugal' },
subtitle: { text: 'Lisbon to the Algarve' },
date: { text: '2026', binding: { source: 'entry.date' as const, entryId: 7, value: '2026-05-14' } },
body: { text: 'We took the early train out of Lisbon and walked up through the fog to the palace.' },
caption: { text: 'Pena Palace in the fog' },
};
const photo = (id: string, photoId: number) =>
bookPhotoElementSchema.parse({ id, kind: 'photo', frame: { x: 0, y: 0, w: 10, h: 10 }, photoId });
const page = (role: BookSpread['role'], photos: number): BookSpread => ({
id: 'sp',
role,
background: null,
elements: Array.from({ length: photos }, (_, i) => photo(`p${i}`, i + 1)),
parked: [],
entryId: null,
});
let n = 0;
const newId = (p: string) => `${p}-${++n}`;
describe('matchDecoratedTemplate', () => {
it('TPLMATCH-001: recognises every shipped template laid on every page format', () => {
for (const preset of ['square-210', 'a4-landscape', 'a4-portrait', 'a5-landscape'] as const) {
const format = bookPageSetupForPreset(preset);
for (const tpl of BOOK_DECORATED_TEMPLATES) {
const laid = applyDecoratedTemplate(page(tpl.kind === 'single' ? 'cover' : 'inner', 8), tpl, format, {
words,
newId,
});
expect(matchDecoratedTemplate(laid, format)?.id, `${tpl.id} on ${preset}`).toBe(tpl.id);
}
}
});
it("TPLMATCH-002: recognises it in a theme's colours and with fewer words and photos than it takes", () => {
const format = bookPageSetupForPreset('square-210');
const theme = bookThemeOf('midnight');
for (const tpl of BOOK_DECORATED_TEMPLATES) {
const laid = applyDecoratedTemplate(page(tpl.kind === 'single' ? 'cover' : 'inner', 1), tpl, format, {
theme,
words: { title: words.title },
newId,
});
expect(matchDecoratedTemplate(laid, format)?.id, tpl.id).toBe(tpl.id);
}
});
it('TPLMATCH-003: a page rearranged by hand is no template', () => {
const format = bookPageSetupForPreset('square-210');
const tpl = BOOK_DECORATED_TEMPLATES.find((t) => t.id === 'stamp-row');
if (!tpl) throw new Error('stamp-row is shipped');
const laid = applyDecoratedTemplate(page('inner', 4), tpl, format, { words, newId });
const moved = { ...laid, elements: laid.elements.map((e) => ({ ...e, frame: { ...e.frame, x: e.frame.x + 9 } })) };
expect(matchDecoratedTemplate(moved, format)).toBeUndefined();
expect(matchDecoratedTemplate({ ...laid, elements: [] }, format)).toBeUndefined();
});
it('TPLMATCH-004: a cover is matched among the covers, a spread among the spreads', () => {
const format = bookPageSetupForPreset('square-210');
for (const tpl of BOOK_DECORATED_TEMPLATES) {
const laid = applyDecoratedTemplate(page(tpl.kind === 'single' ? 'back' : 'inner', 3), tpl, format, { newId });
expect(matchDecoratedTemplate(laid, format)?.kind ?? tpl.kind).toBe(tpl.kind);
}
});
});
@@ -0,0 +1,91 @@
import type { BookElement, BookPageSetup, BookSpread } from '../book.schema';
import { layDecoratedTemplate } from './template-apply';
import { BOOK_DECORATED_TEMPLATES } from './template-catalogue';
import type { BookDecoratedTemplate } from './template-format';
/**
* Which decorated template a laid page is, read from the page alone.
*
* A template keeps its frames where it pours: the photo frames, the role
* texts and the design (panels, shapes, lines, stickers) all land where the
* template put them on this page's format. So a page is fingerprinted by its
* elements' kinds and frames, rounded to the millimetre, and compared with
* every template laid on the same format: a template is the page's when
* nearly all of its design is there, and of those the one that explains the
* most of the page wins. A page somebody rearranged by hand matches none.
*
* Nothing depends on the answer being right: the auto layout's "this spread"
* uses it to offer another template than the one on screen, and at worst
* offers that one again.
*/
/** The share of a template's design elements a page must hold to be that template. */
const DESIGN_SHARE = 0.8;
/** The share of the page's own elements the template must explain: a template of little design is no excuse. */
const PAGE_SHARE = 0.6;
/** A photo frame, and a map laid as one when it had nothing to draw, read alike. */
const kindKey = (kind: BookElement['kind']) => (kind === 'map' ? 'photo' : kind);
const keyOf = (el: BookElement) => {
const f = el.frame;
return [kindKey(el.kind), Math.round(f.x), Math.round(f.y), Math.round(f.w), Math.round(f.h)].join(':');
};
interface Fingerprint {
/** Every laid element, its role's ones included. */
all: string[];
/** The design alone: what no page's content changes. */
design: string[];
}
const laidPrints = new Map<string, Fingerprint>();
/** A template's fingerprint on a page format, laid once per format. */
function printOf(tpl: BookDecoratedTemplate, page: BookPageSetup): Fingerprint {
const key = `${tpl.id}|${page.pageWidth}x${page.pageHeight}|${page.bleed}`;
const known = laidPrints.get(key);
if (known) return known;
let n = 0;
const laid = layDecoratedTemplate(tpl, page, null, (p) => `${p}${++n}`);
const print = { all: laid.map((l) => keyOf(l.el)), design: laid.filter((l) => !l.role).map((l) => keyOf(l.el)) };
laidPrints.set(key, print);
return print;
}
/** How many of `want` the multiset `have` holds. */
function held(want: readonly string[], have: ReadonlyMap<string, number>): number {
const left = new Map(have);
let found = 0;
for (const k of want) {
const n = left.get(k) ?? 0;
if (n > 0) {
left.set(k, n - 1);
found++;
}
}
return found;
}
/** The decorated template a page was laid on, or undefined when it reads as none. */
export function matchDecoratedTemplate(spread: BookSpread, page: BookPageSetup): BookDecoratedTemplate | undefined {
const own = spread.elements.filter((e) => !e.locked);
if (!own.length) return undefined;
const have = new Map<string, number>();
for (const el of own) have.set(keyOf(el), (have.get(keyOf(el)) ?? 0) + 1);
const kind = spread.role === 'inner' ? 'inner' : 'single';
let best: { tpl: BookDecoratedTemplate; explained: number; found: number } | undefined;
for (const tpl of BOOK_DECORATED_TEMPLATES) {
if (tpl.kind !== kind) continue;
const print = printOf(tpl, page);
const design = held(print.design, have);
if (design < print.design.length * DESIGN_SHARE) continue;
const found = held(print.all, have);
const explained = found / own.length;
if (explained < PAGE_SHARE) continue;
if (!best || explained > best.explained || (explained === best.explained && found > best.found)) {
best = { tpl, explained, found };
}
}
return best?.tpl;
}