tests/arrangement.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 {
12  arrangeGroup,
13  arrangementTarget,
14  changedArrangements,
15  restoreArrangement,
16} from "../documentation/components/source/arrangement.ts";
17import {
18  atPath,
19  groupMembers,
20  ungroupMembers,
21  restoreGrouping,
22} from "../documentation/components/source/grouping.ts";
23
24const initial = example("grouped");
25function members(tree: Composition | undefined): readonly Composition[] {
26  if (!tree || !("children" in tree)) throw new Error("Expected a group");
27  return tree.children;
28}
29const stored = (tree: unknown): unknown => JSON.parse(JSON.stringify(tree));
30/** Every name in the declaration with its path, and every string, in order. */
31function written(tree: Composition) {
32  const tokens = declaration(tree, "0", 0, 40).flatMap((line) => line.tokens);
33  return {
34    names: tokens
35      .filter((token) => token.kind)
36      .map((token) => `${token.path} ${token.kind}`),
37    strings: tokens
38      .filter((token) => token.tone === "string")
39      .map((token) => token.text),
40  };
41}
42
43test("a new arrangement changes one name and shares every member", () => {
44  const arranged = arrangeGroup(initial, "0.0", "Shelf");
45  assert.equal(atPath(arranged, "0.0")?.kind, "Shelf");
46  // The members are the same objects at the same paths, in the same order.
47  assert.equal(
48    members(atPath(arranged, "0.0")),
49    members(atPath(initial, "0.0")),
50  );
51  for (const path of ["0.0.0", "0.0.1", "0.0.2", "0.1", "0.1.0", "0.1.1"])
52    assert.equal(atPath(arranged, path), atPath(initial, path), path);
53  // In the declaration, exactly one name differs and no string does.
54  const was = written(initial),
55    is = written(arranged);
56  assert.deepEqual(is.strings, was.strings);
57  assert.deepEqual(
58    is.names.filter((name, index) => name !== was.names[index]),
59    ["0.0 Shelf"],
60  );
61  assert.equal(is.names.length, was.names.length);
62  assert.equal(atPath(initial, "0.0")?.kind, "Stack", "the input is untouched");
63});
64
65test("the experiment's Switcher choice is the fixed Switcher example", () => {
66  assert.deepEqual(
67    arrangeGroup(initial, "0.0", "Switcher"),
68    example("switcher"),
69  );
70});
71
72test("root and nested groups are arranged independently", () => {
73  const outer = arrangeGroup(initial, "0", "Switcher");
74  assert.equal(outer.kind, "Switcher");
75  assert.equal(atPath(outer, "0.0"), atPath(initial, "0.0"));
76  const both = arrangeGroup(outer, "0.0", "Switcher");
77  const all = arrangeGroup(both, "0.1", "Shelf");
78  assert.deepEqual(
79    ["0", "0.0", "0.1"].map((path) => atPath(all, path)?.kind),
80    ["Switcher", "Switcher", "Shelf"],
81  );
82  assert.equal(atPath(all, "0.0.2"), atPath(initial, "0.0.2"));
83  assert.deepEqual(written(all).strings, written(initial).strings);
84});
85
86test("choosing the current arrangement returns the same composition", () => {
87  assert.equal(arrangeGroup(initial, "0.0", "Stack"), initial);
88  assert.equal(arrangeGroup(initial, "0", "Stack"), initial);
89  const shelf = arrangeGroup(initial, "0.0", "Shelf");
90  assert.equal(arrangeGroup(shelf, "0.0", "Shelf"), shelf);
91  assert.deepEqual(arrangeGroup(shelf, "0.0", "Stack"), initial);
92});
93
94test("a leaf, a stale path or several paths cannot be arranged", () => {
95  const snapshot = stored(initial);
96  for (const path of ["0.0.0", "0.1.1", "0.2", "0.0.3", "0.-1", "1", "", "0."])
97    assert.throws(() => arrangeGroup(initial, path, "Shelf"), /Select a group/);
98  assert.deepEqual(stored(initial), snapshot);
99
100  assert.equal(arrangementTarget(initial, []), undefined);
101  assert.equal(arrangementTarget(initial, ["0.0.0"]), undefined, "a leaf");
102  assert.equal(arrangementTarget(initial, ["0.7"]), undefined, "stale");
103  assert.equal(
104    arrangementTarget(initial, ["0.0", "0.1"]),
105    undefined,
106    "two groups are not one target",
107  );
108  assert.equal(
109    arrangementTarget(initial, ["0.0.0", "0.0.1"]),
110    undefined,
111    "members do not stand for their parent",
112  );
113  assert.deepEqual(arrangementTarget(initial, ["0"]), {
114    path: "0",
115    group: initial,
116  });
117  assert.equal(
118    arrangementTarget(initial, ["0.1"])?.group,
119    atPath(initial, "0.1"),
120  );
121});
122
123test("the groups an edit rearranged can be found again", () => {
124  const shelf = arrangeGroup(initial, "0.0", "Shelf");
125  const both = arrangeGroup(shelf, "0", "Switcher");
126  assert.deepEqual(changedArrangements(initial, initial), []);
127  assert.deepEqual(changedArrangements(initial, shelf), ["0.0"]);
128  assert.deepEqual(changedArrangements(both, shelf), ["0"]);
129  assert.deepEqual(changedArrangements(both, initial), ["0", "0.0"]);
130  // Compositions with different members are not rearrangements of each other.
131  assert.deepEqual(changedArrangements(initial, example("flat")), []);
132  assert.deepEqual(
133    changedArrangements(initial, ungroupMembers(shelf, "0.0")),
134    [],
135  );
136  assert.deepEqual(changedArrangements(shelf, example("shelf")), []);
137});
138
139test("stepping back through edits names the one group each step restores", () => {
140  const history = [initial];
141  for (const [path, kind] of [
142    ["0.0", "Shelf"],
143    ["0", "Switcher"],
144    ["0.0", "Switcher"],
145    ["0.1", "Shelf"],
146  ] as const)
147    history.push(arrangeGroup(history.at(-1)!, path, kind));
148  const restored = [];
149  while (history.length > 1) {
150    const current = history.pop()!;
151    const [path, ...others] = changedArrangements(current, history.at(-1)!);
152    assert.deepEqual(others, []);
153    const target = arrangementTarget(history.at(-1)!, [path!]);
154    restored.push(`${target?.path} ${target?.group.kind}`);
155  }
156  assert.deepEqual(restored, [
157    "0.1 Stack",
158    "0.0 Shelf",
159    "0 Stack",
160    "0.0 Stack",
161  ]);
162});
163
164test("a saved arrangement restores with the starting composition's own content", () => {
165  const arranged = arrangeGroup(
166    arrangeGroup(initial, "0.0", "Switcher"),
167    "0",
168    "Shelf",
169  );
170  const restored = restoreArrangement(stored(arranged), initial);
171  assert.deepEqual(restored, arranged);
172  assert.equal(atPath(restored!, "0.0.1"), atPath(initial, "0.0.1"));
173  assert.deepEqual(restoreArrangement(stored(initial), initial), initial);
174  // Only kinds are read: anything else on a saved group is dropped.
175  const decorated = stored(arranged) as Record<string, unknown>;
176  decorated.style = "position: fixed";
177  decorated.path = "0.9";
178  assert.deepEqual(restoreArrangement(decorated, initial), arranged);
179});
180
181test("saved state cannot regroup, reorder, replace or add content", () => {
182  const [first, second] = members(initial) as [Composition, Composition];
183  const [a, b, c] = members(first) as [Composition, Composition, Composition];
184  const text = (value: string): Composition => ({ kind: "Text", text: value });
185  const tampered: [string, unknown][] = [
186    ["regrouped", Stack(Stack(Stack(a, b), c), second)],
187    ["ungrouped", Stack(a, b, c, second)],
188    ["reordered members", Stack(Shelf(b, a, c), second)],
189    ["reordered groups", Stack(second, first)],
190    ["changed text", Stack(Stack(a, text("Run failed"), c), second)],
191    [
192      "changed leaf kind",
193      Stack(Stack(a, b, { kind: "Heading", text: "3 checks passed" }), second),
194    ],
195    ["added member", Stack(Stack(a, b, c, text("Extra")), second)],
196    ["removed member", Stack(Stack(a, b), second)],
197    ["added group", Stack(first, second, Stack(a, b))],
198    ["group replaced by content", Stack(text("All of it"), second)],
199    ["content replaced by a group", Stack(Stack(a, b, Stack(c, c)), second)],
200    ["unknown arrangement", { kind: "Grid", children: [first, second] }],
201    [
202      "unknown nested arrangement",
203      {
204        kind: "Stack",
205        children: [{ kind: "Text", children: [a, b, c] }, second],
206      },
207    ],
208    ["children not a list", { kind: "Stack", children: { length: 2 } }],
209    ["another exercise's content", example("event")],
210    ["nothing", null],
211    ["a list", [first, second]],
212    ["a string", "Stack"],
213  ];
214  for (const [label, value] of tampered)
215    assert.equal(restoreArrangement(stored(value), initial), undefined, label);
216});
217
218test("each exercise accepts only the edits it offers", () => {
219  // The grouping exercises still accept Stacks alone.
220  const flat = example("flat");
221  const grouped = groupMembers(flat, ["0.0", "0.1"]);
222  assert.deepEqual(restoreGrouping(stored(grouped), flat), grouped);
223  for (const kind of ["Shelf", "Switcher"] as const) {
224    assert.equal(
225      restoreGrouping(stored(arrangeGroup(grouped, "0.0", kind)), flat),
226      undefined,
227    );
228    assert.equal(
229      restoreGrouping(stored(arrangeGroup(flat, "0", kind)), flat),
230      undefined,
231    );
232  }
233  // The arrangement experiment accepts kinds, never a regrouping, even one
234  // that the grouping exercises would accept for the same content.
235  const regrouped = groupMembers(initial, ["0.0.0", "0.0.1"]);
236  assert.deepEqual(restoreGrouping(stored(regrouped), initial), regrouped);
237  assert.equal(restoreArrangement(stored(regrouped), initial), undefined);
238  assert.equal(
239    restoreArrangement(stored(Switcher(...members(flat))), flat)?.kind,
240    "Switcher",
241  );
242  assert.equal(restoreArrangement(stored(grouped), flat), undefined);
243});