tests/working-copy.test.ts

1import { test } from "node:test";
2import assert from "node:assert/strict";
3import {
4  declaration,
5  example,
6  Stack,
7  Shelf,
8  Switcher,
9  type Composition,
10} from "../documentation/components/source/composition.ts";
11import { atPath } from "../documentation/components/source/grouping.ts";
12import { chooseMember } from "../documentation/components/source/composition-editing.ts";
13import {
14  addText,
15  beginTextEdit,
16  cancelTextEdit,
17  commitEdit,
18  editsFor,
19  editText,
20  finishTextEdit,
21  newText,
22  releaseGroup,
23  removeMember,
24  restoreWorkingCopy,
25  restoreWorkingTree,
26  startWorkingCopy,
27  typeText,
28  undoEdit,
29  workingCopyLimits,
30  wrapMembers,
31  type WorkingCopy,
32} from "../documentation/components/source/working-copy.ts";
33
34const stored = (value: unknown): unknown => JSON.parse(JSON.stringify(value));
35const text = (value: string): Composition => ({ kind: "Text", text: value });
36const heading = (value: string): Composition => ({
37  kind: "Heading",
38  text: value,
39});
40const [a, b, c, d] = ["a", "b", "c", "d"].map(text) as [
41  Composition,
42  Composition,
43  Composition,
44  Composition,
45];
46/** A saved group as storage holds it: no promise that it is a composition. */
47const group = (kind: string, ...children: unknown[]) => ({ kind, children });
48function at(tree: Composition, path: string): Composition {
49  const node = atPath(tree, path);
50  if (!node) throw new Error(`Nothing at ${path}`);
51  return node;
52}
53const printed = (tree: Composition) =>
54  declaration(tree)
55    .map((line) => line.tokens.map((token) => token.text).join(""))
56    .join("\n");
57/** A chain of `levels` groups, the innermost empty. */
58const nested = (levels: number): Composition =>
59  levels === 1 ? Stack() : Stack(nested(levels - 1));
60
61test("a working copy may hold any text, any number of members and any arrangement", () => {
62  const tree = Stack(
63    heading("Mine"),
64    Switcher(),
65    Shelf(text("only member")),
66    Stack(Switcher(text(""), text("two")), Stack()),
67  );
68  assert.deepEqual(restoreWorkingTree(stored(tree)), tree);
69  assert.deepEqual(restoreWorkingTree(stored(Stack())), Stack(), "empty root");
70  // Nothing but the composition survives: the result is built afresh.
71  assert.deepEqual(
72    restoreWorkingTree({
73      kind: "Shelf",
74      text: "ignored",
75      extra: true,
76      children: [{ kind: "Meta", text: "m", children: [], onclick: "x" }],
77    }),
78    Shelf({ kind: "Meta", text: "m" }),
79  );
80});
81
82test("a saved working copy is rejected unless it is a bounded composition under a root group", () => {
83  for (const [saved, why] of [
84    [null, "nothing saved"],
85    ["Stack()", "a string"],
86    [[text("a")], "an array"],
87    [text("a"), "the root is content"],
88    [group("Grid", a), "an unknown arrangement"],
89    [group("Stack", { kind: "Image", text: "a" }), "an unknown kind"],
90    [group("Stack", { kind: "Text", text: 7 }), "text that is not a string"],
91    [group("Stack", { kind: "Text" }), "content without text"],
92    [{ kind: "Stack" }, "a group without members"],
93    [{ kind: "Stack", children: { 0: a, length: 1 } }, "members not a list"],
94    [group("Stack", a, null), "a missing member"],
95    [nested(workingCopyLimits.ancestors + 2), "nesting past the limit"],
96    [
97      Stack(...Array.from({ length: workingCopyLimits.nodes }, () => a)),
98      "more nodes than the limit",
99    ],
100  ] as const)
101    assert.equal(restoreWorkingTree(stored(saved)), undefined, why);
102  assert.ok(restoreWorkingTree(nested(workingCopyLimits.ancestors + 1)));
103  assert.ok(
104    restoreWorkingTree(
105      Stack(...Array.from({ length: workingCopyLimits.nodes - 1 }, () => a)),
106    ),
107  );
108});
109
110test("a saved working copy restores its composition, selection and history, each validated", () => {
111  const model = Stack(Switcher(a, b), c);
112  const earlier = Stack(a, b, c);
113  const saved = stored({
114    model,
115    chosen: ["0.0"],
116    undo: [
117      { model: earlier, chosen: ["0.0", "0.1"] },
118      { model: group("Grid", a), chosen: [] },
119      { model: earlier, chosen: ["0.0", "0.2"] },
120      "not an entry",
121    ],
122    width: 480,
123  });
124  assert.deepEqual(restoreWorkingCopy(saved), {
125    model,
126    chosen: ["0.0"],
127    undo: [
128      { model: earlier, chosen: ["0.0", "0.1"] },
129      // Members that are not neighbors are no selection in that composition.
130      { model: earlier, chosen: [] },
131    ],
132  });
133  assert.equal(restoreWorkingCopy(stored({ model: a, undo: [] })), undefined);
134  assert.equal(restoreWorkingCopy(null), undefined);
135  assert.deepEqual(
136    restoreWorkingCopy(stored({ model, chosen: ["0.9"], undo: "none" })),
137    { model, chosen: [], undo: [] },
138    "a stale selection and an unreadable history restore as none",
139  );
140  const long = Array.from(
141    { length: workingCopyLimits.history + 5 },
142    (_, i) => ({
143      model: Stack(text(`${i}`)),
144      chosen: [],
145    }),
146  );
147  const restored = restoreWorkingCopy(stored({ model, undo: long }))!;
148  assert.equal(restored.undo.length, workingCopyLimits.history);
149  assert.deepEqual(restored.undo.at(-1), long.at(-1), "the latest are kept");
150});
151
152test("the selection decides which edits are offered", () => {
153  const tree = Stack(heading("h"), Switcher(a, b), Shelf(), c);
154  const offered = (chosen: readonly string[]) => {
155    const edits = editsFor(tree, chosen);
156    return {
157      text: edits.text?.path,
158      arrange: edits.arrange?.path,
159      inside: edits.inside && [edits.inside.parent, edits.inside.index],
160      after: edits.after && [edits.after.parent, edits.after.index],
161      wrap: edits.wrap,
162      release: edits.release,
163      remove: edits.remove,
164    };
165  };
166  const none = {
167    text: undefined,
168    arrange: undefined,
169    inside: undefined,
170    after: undefined,
171    wrap: undefined,
172    release: undefined,
173    remove: undefined,
174  };
175  assert.deepEqual(
176    offered([]),
177    { ...none, inside: ["0", 4] },
178    "with nothing selected, new text joins the whole composition",
179  );
180  assert.deepEqual(
181    offered(["0"]),
182    { ...none, arrange: "0", inside: ["0", 4] },
183    "the root can be arranged and added to, never wrapped, released or removed",
184  );
185  assert.deepEqual(offered(["0.0"]), {
186    ...none,
187    text: "0.0",
188    after: ["0", 1],
189    wrap: ["0.0"],
190    remove: "0.0",
191  });
192  assert.deepEqual(
193    offered(["0.1"]),
194    {
195      ...none,
196      arrange: "0.1",
197      inside: ["0.1", 2],
198      after: ["0", 2],
199      wrap: ["0.1"],
200      release: "0.1",
201      remove: "0.1",
202    },
203    "an inner group is both a group and a member",
204  );
205  assert.deepEqual(
206    offered(["0.2"]),
207    {
208      ...none,
209      arrange: "0.2",
210      inside: ["0.2", 0],
211      after: ["0", 3],
212      wrap: ["0.2"],
213      release: "0.2",
214      remove: "0.2",
215    },
216    "an empty group offers everything a full one does",
217  );
218  assert.deepEqual(
219    offered(["0.2", "0.1"]),
220    { ...none, after: ["0", 3], wrap: ["0.1", "0.2"] },
221    "a run is wrapped in reading order and added after its last member",
222  );
223  assert.deepEqual(
224    offered(["0.1.0", "0.1.1"]),
225    { ...none, after: ["0.1", 2], wrap: ["0.1.0", "0.1.1"] },
226    "every member of a group may be wrapped together",
227  );
228  assert.deepEqual(
229    offered(["0.9"]),
230    offered([]),
231    "a stale path selects nothing",
232  );
233  assert.equal(editsFor(tree, ["0.1"]).full, false);
234});
235
236test("edits that would pass the limits are withheld, and the reason is known", () => {
237  const crowded = Stack(
238    Stack(a),
239    ...Array.from({ length: workingCopyLimits.nodes - 3 }, () => b),
240  );
241  const edits = editsFor(crowded, ["0.0"]);
242  assert.equal(edits.inside, undefined);
243  assert.equal(edits.after, undefined);
244  assert.equal(edits.wrap, undefined);
245  assert.equal(edits.full, true);
246  assert.equal(edits.remove, "0.0", "removing is how room is made");
247  assert.equal(editsFor(crowded, ["0"]).full, true);
248
249  // The innermost group sits at the deepest level a working copy allows.
250  const deep = nested(workingCopyLimits.ancestors + 1);
251  const innermost = `0${".0".repeat(workingCopyLimits.ancestors)}`;
252  assert.deepEqual(at(deep, innermost), Stack());
253  assert.equal(editsFor(deep, [innermost]).inside, undefined);
254  assert.equal(editsFor(deep, [innermost]).wrap, undefined);
255  assert.equal(editsFor(deep, [innermost]).full, true);
256  assert.ok(editsFor(deep, [innermost]).after, "a sibling adds no level");
257  assert.equal(
258    editsFor(deep, ["0.0"]).wrap,
259    undefined,
260    "its subtree is too deep",
261  );
262  const shallower = nested(workingCopyLimits.ancestors);
263  const edited = addText(
264    shallower,
265    editsFor(shallower, [`0${".0".repeat(workingCopyLimits.ancestors - 1)}`])
266      .inside!,
267  );
268  assert.ok(restoreWorkingTree(stored(edited.tree)));
269});
270
271test("rewording keeps the kind, the place and everything else", () => {
272  const tree = Stack(heading("Before"), Switcher(a, b));
273  const next = editText(tree, "0.0", "After");
274  assert.deepEqual(next, Stack(heading("After"), Switcher(a, b)));
275  assert.equal(at(next, "0.1"), at(tree, "0.1"), "untouched groups are shared");
276  assert.equal(editText(tree, "0.0", "Before"), tree, "nothing changed");
277  assert.deepEqual(at(editText(tree, "0.1.1", ""), "0.1.1"), text(""));
278  assert.throws(() => editText(tree, "0.1", "group"));
279  assert.throws(() => editText(tree, "0.7", "missing"));
280});
281
282test("new text joins a group, even an empty one, or follows a member, and is selected", () => {
283  const tree = Stack(Switcher(), a, Shelf(b, c));
284  const inside = addText(tree, editsFor(tree, ["0.0"]).inside!);
285  assert.deepEqual(inside.tree, Stack(Switcher(text(newText)), a, Shelf(b, c)));
286  assert.deepEqual(inside.chosen, ["0.0.0"]);
287
288  const after = addText(tree, editsFor(tree, ["0.1"]).after!, "next");
289  assert.deepEqual(after.tree, Stack(Switcher(), a, text("next"), Shelf(b, c)));
290  assert.deepEqual(after.chosen, ["0.2"]);
291  assert.equal(
292    at(after.tree, "0.3"),
293    at(tree, "0.2"),
294    "later members move along",
295  );
296
297  // After a group, as its sibling: between it and whatever follows.
298  const beside = addText(tree, editsFor(tree, ["0.0"]).after!);
299  assert.deepEqual(
300    beside.tree,
301    Stack(Switcher(), text(newText), a, Shelf(b, c)),
302  );
303  const end = addText(tree, editsFor(tree, []).inside!);
304  assert.deepEqual(end.chosen, ["0.3"]);
305  assert.deepEqual(
306    addText(Stack(), editsFor(Stack(), []).inside!).tree,
307    Stack(text(newText)),
308    "an empty composition can be added to",
309  );
310  assert.throws(() => addText(tree, { parent: "0.1", index: 0 }));
311  assert.throws(() => addText(tree, { parent: "0.0", index: 2 }));
312});
313
314test("removing a member never dissolves its group", () => {
315  const tree = Stack(Switcher(a, b), Shelf(c), d);
316  const one = removeMember(tree, "0.0.1");
317  assert.deepEqual(one.tree, Stack(Switcher(a), Shelf(c), d));
318  assert.deepEqual(one.chosen, ["0.0.0"], "the member before, at the end");
319
320  const none = removeMember(one.tree, "0.0.0");
321  assert.deepEqual(none.tree, Stack(Switcher(), Shelf(c), d));
322  assert.deepEqual(none.chosen, ["0.0"], "the emptied group");
323
324  const first = removeMember(tree, "0.0.0");
325  assert.deepEqual(first.chosen, ["0.0.0"], "the member now in that place");
326  assert.deepEqual(at(first.tree, "0.0.0"), b);
327
328  // A group goes with everything in it; its own parent stays.
329  const whole = removeMember(tree, "0.0");
330  assert.deepEqual(whole.tree, Stack(Shelf(c), d));
331  let tree2 = whole.tree;
332  for (const path of ["0.1", "0.0"]) tree2 = removeMember(tree2, path).tree;
333  assert.deepEqual(tree2, Stack(), "the root may be emptied");
334  assert.deepEqual(removeMember(Stack(a), "0.0").chosen, ["0"]);
335  assert.throws(() => removeMember(tree, "0"), "the root is not a member");
336  assert.throws(() => removeMember(tree, "0.5"));
337});
338
339test("grouping wraps one member, a run, or every member, in place", () => {
340  const tree = Stack(a, Switcher(b, c), d);
341  const single = wrapMembers(tree, ["0.0"]);
342  assert.deepEqual(single.tree, Stack(Stack(a), Switcher(b, c), d));
343  assert.deepEqual(single.chosen, ["0.0"]);
344
345  const run = wrapMembers(tree, ["0.2", "0.1"]);
346  assert.deepEqual(run.tree, Stack(a, Stack(Switcher(b, c), d)));
347  assert.deepEqual(run.chosen, ["0.1"]);
348  assert.equal(
349    at(run.tree, "0.1.0"),
350    at(tree, "0.1"),
351    "members are not copied",
352  );
353
354  const all = wrapMembers(tree, ["0.1.0", "0.1.1"]);
355  assert.deepEqual(all.tree, Stack(a, Switcher(Stack(b, c)), d));
356  assert.equal(
357    at(all.tree, "0.1").kind,
358    "Switcher",
359    "the parent's arrangement stays",
360  );
361
362  assert.throws(
363    () => wrapMembers(tree, ["0"]),
364    "the root has no group to join",
365  );
366  assert.throws(() => wrapMembers(tree, ["0.0", "0.2"]), "not neighbors");
367  assert.throws(() => wrapMembers(tree, []));
368});
369
370test("ungrouping returns members to the parent; an empty group simply goes", () => {
371  const tree = Stack(a, Switcher(b, c), Shelf(), d);
372  const released = releaseGroup(tree, "0.1");
373  assert.deepEqual(released.tree, Stack(a, b, c, Shelf(), d));
374  assert.deepEqual(released.chosen, ["0.1", "0.2"]);
375  const empty = releaseGroup(tree, "0.2");
376  assert.deepEqual(empty.tree, Stack(a, Switcher(b, c), d));
377  assert.deepEqual(empty.chosen, ["0"]);
378  assert.throws(() => releaseGroup(tree, "0"));
379  assert.throws(() => releaseGroup(tree, "0.0"), "content has no members");
380});
381
382test("each edit is one step for Undo, which also restores the selection", () => {
383  let copy = startWorkingCopy(Stack(a, b));
384  assert.equal(undoEdit(copy), undefined);
385  copy = { ...copy, chosen: chooseMember(copy.model, copy.chosen, "0.1") };
386  const removed = removeMember(copy.model, "0.1");
387  copy = commitEdit(copy, removed.tree, removed.chosen);
388  const wrapped = wrapMembers(copy.model, ["0.0"]);
389  copy = commitEdit(copy, wrapped.tree, wrapped.chosen);
390  assert.deepEqual(copy.model, Stack(Stack(a)));
391  assert.equal(copy.undo.length, 2);
392
393  copy = undoEdit(copy)!;
394  assert.deepEqual(copy.model, Stack(a));
395  assert.deepEqual(copy.chosen, ["0.0"]);
396  copy = undoEdit(copy)!;
397  assert.deepEqual(copy.model, Stack(a, b), "the removed member is back");
398  assert.deepEqual(copy.chosen, ["0.1"], "and selected, as it was");
399  assert.equal(undoEdit(copy), undefined);
400
401  // Replacing the whole composition is an edit like any other.
402  const mine = commitEdit(copy, Stack(text("mine")), []);
403  const replaced = commitEdit(mine, example("investigation"), []);
404  assert.deepEqual(undoEdit(replaced)!.model, Stack(text("mine")));
405
406  let long = startWorkingCopy(Stack());
407  for (let i = 0; i <= workingCopyLimits.history; i++)
408    long = commitEdit(long, Stack(text(`${i}`)), []);
409  assert.equal(long.undo.length, workingCopyLimits.history);
410  assert.deepEqual(
411    long.undo[0]!.model,
412    Stack(text("0")),
413    "the oldest is dropped",
414  );
415});
416
417test("one rewording, however many keystrokes, is one step for Undo", () => {
418  const start: WorkingCopy = {
419    ...startWorkingCopy(Stack(heading("Title"), a)),
420    chosen: ["0.0"],
421  };
422  const edit = beginTextEdit(start, "0.0");
423  let copy = start;
424  for (const typed of ["T", "Th", "The", "The title"]) {
425    copy = typeText(copy, edit, typed);
426    assert.deepEqual(at(copy.model, "0.0"), heading(typed), "shown as typed");
427    assert.equal(copy.undo.length, 0, "history waits");
428  }
429  copy = finishTextEdit(copy, edit);
430  assert.equal(copy.undo.length, 1);
431  const undone = undoEdit(copy)!;
432  assert.deepEqual(undone.model, start.model);
433  assert.deepEqual(undone.chosen, ["0.0"]);
434
435  // Typing back to the original wording leaves nothing to undo.
436  let same = typeText(start, edit, "Titles");
437  same = finishTextEdit(typeText(same, edit, "Title"), edit);
438  assert.equal(same.undo.length, 0);
439  assert.equal(finishTextEdit(start, edit), start);
440
441  // Escape: the text from before the edit, and earlier history untouched.
442  const earlier = commitEdit(start, start.model, ["0.0"]);
443  const during = typeText(earlier, beginTextEdit(earlier, "0.0"), "Abandoned");
444  const cancelled = cancelTextEdit(during, beginTextEdit(earlier, "0.0"));
445  assert.equal(cancelled.model, earlier.model);
446  assert.deepEqual(cancelled.chosen, ["0.0"]);
447  assert.equal(cancelled.undo, earlier.undo);
448  assert.throws(() => beginTextEdit(start, "0"), "a group has no text");
449});
450
451test("every state an author reaches can be saved and reopened", () => {
452  let copy = startWorkingCopy(restoreWorkingTree(example("investigation"))!);
453  const step = (
454    chosen: readonly string[],
455    edit: (tree: Composition) => {
456      tree: Composition;
457      chosen: readonly string[];
458    },
459  ) => {
460    copy = { ...copy, chosen };
461    const edited = edit(copy.model);
462    copy = commitEdit(copy, edited.tree, edited.chosen);
463    assert.deepEqual(
464      restoreWorkingCopy(stored(copy)),
465      copy,
466      printed(copy.model),
467    );
468  };
469  step(["0.1", "0.2"], (tree) => wrapMembers(tree, ["0.1", "0.2"]));
470  step(["0.1"], (tree) => addText(tree, editsFor(tree, ["0.1"]).inside!));
471  for (let i = 0; i < 3; i++)
472    step(["0.1.0"], (tree) => removeMember(tree, "0.1.0"));
473  assert.deepEqual(at(copy.model, "0.1"), Stack(), "emptied, and still there");
474  step(["0.1"], (tree) => wrapMembers(tree, ["0.1"]));
475  step(["0.1.0"], (tree) => addText(tree, editsFor(tree, ["0.1.0"]).inside!));
476  for (const path of ["0.4", "0.3", "0.2", "0.1", "0.0"])
477    step([path], (tree) => removeMember(tree, path));
478  assert.deepEqual(copy.model, Stack());
479  assert.equal(copy.undo.length, 12);
480});
481
482test("the declaration names every group, including one with no members", () => {
483  assert.equal(printed(Stack()), "Stack()");
484  assert.equal(
485    printed(Stack(Switcher(), Shelf(text("one")))),
486    'Stack(\n  Switcher(),\n  Shelf(Text("one"))\n)',
487  );
488  const names = declaration(Stack(Switcher(), a)).flatMap((line) =>
489    line.tokens.filter((token) => token.kind).map((token) => token.path),
490  );
491  assert.deepEqual(names, ["0", "0.0", "0.1"], "each has a name to select");
492});