tests/switcher-coordinator.test.ts

1import { test } from "node:test";
2import assert from "node:assert/strict";
3import {
4  SwitcherCoordinator,
5  arrangementAttribute,
6  arrangementFor,
7  fitTolerance,
8  switcherCoordinator,
9  type SwitcherDecision,
10} from "../documentation/components/source/switcher-coordinator.ts";
11
12/** Stands in for a box: records attribute writes so tests can count them. */
13class Box {
14  readonly writes: string[] = [];
15  #arrangement: string | null = null;
16  getAttribute(name: string) {
17    return name === arrangementAttribute ? this.#arrangement : null;
18  }
19  setAttribute(name: string, value: string) {
20    assert.equal(name, arrangementAttribute);
21    this.#arrangement = value;
22    this.writes.push(value);
23  }
24  get arrangement() {
25    return this.#arrangement;
26  }
27}
28
29/** A ResizeObserver whose deliveries the test controls. */
30class Deliveries {
31  static created: Deliveries[] = [];
32  readonly targets = new Set<object>();
33  readonly #callback: ResizeObserverCallback;
34  constructor(callback: ResizeObserverCallback) {
35    this.#callback = callback;
36    Deliveries.created.push(this);
37  }
38  observe(target: object) {
39    this.targets.add(target);
40  }
41  unobserve(target: object) {
42    this.targets.delete(target);
43  }
44  disconnect() {
45    this.targets.clear();
46  }
47  /** Each report is `[target, inline size, block size]`. */
48  deliver(...reports: (readonly [object, number, number])[]) {
49    const entries = reports.map(([target, inlineSize, blockSize]) => ({
50      target,
51      contentBoxSize: [{ inlineSize, blockSize }],
52    }));
53    this.#callback(
54      entries as unknown as ResizeObserverEntry[],
55      this as unknown as ResizeObserver,
56    );
57  }
58}
59const Observer = Deliveries as unknown as typeof ResizeObserver;
60
61function setup() {
62  const coordinator = new SwitcherCoordinator(Observer);
63  const observer = Deliveries.created.at(-1)!;
64  const add = () => {
65    const switcher = new Box(),
66      slot = new Box(),
67      requirement = new Box();
68    const unregister = coordinator.register({
69      switcher,
70      slot,
71      requirement,
72    } as unknown as Parameters<SwitcherCoordinator["register"]>[0]);
73    return { switcher, slot, requirement, unregister };
74  };
75  return { coordinator, observer, add };
76}
77
78test("a row that exactly fits is a row, with only sub-pixel slack", () => {
79  assert.equal(arrangementFor(414.58334, 414.58334), "row");
80  assert.equal(arrangementFor(414.58334, 600), "row");
81  // One fixed-point layout unit of disagreement between two boxes is noise.
82  assert.equal(arrangementFor(414.59375, 414.578125), "row");
83  assert.equal(arrangementFor(415, 414), "column");
84  assert.equal(arrangementFor(100 + 2 * fitTolerance, 100), "column");
85});
86
87test("a Switcher is decided from its two reported sizes, whichever arrives first", () => {
88  for (const order of ["slot first", "requirement first", "together"]) {
89    const { observer, add } = setup();
90    const { switcher, slot, requirement } = add();
91    const wide = [slot, 500, 0] as const,
92      needs = [requirement, 400, 21] as const;
93    if (order === "together") observer.deliver(needs, wide);
94    else if (order === "slot first") {
95      observer.deliver(wide);
96      assert.equal(switcher.arrangement, null, "no requirement yet");
97      observer.deliver(needs);
98    } else {
99      // An unreported slot is zero wide, as it is to the browser's observer.
100      observer.deliver(needs);
101      assert.equal(switcher.arrangement, "column");
102      observer.deliver(wide);
103    }
104    assert.equal(switcher.arrangement, "row", order);
105  }
106});
107
108test("the arrangement is written only when it changes", () => {
109  const { observer, add } = setup();
110  const { switcher, slot, requirement } = add();
111  observer.deliver([slot, 500, 0], [requirement, 400, 21]);
112  for (const width of [480, 460, 440, 401, 400])
113    observer.deliver([slot, width, 0]);
114  assert.deepEqual(switcher.writes, ["row"]);
115  observer.deliver([slot, 399, 0]);
116  observer.deliver([slot, 380, 0]);
117  observer.deliver([slot, 400, 0]);
118  assert.deepEqual(switcher.writes, ["row", "column", "row"]);
119});
120
121test("a changed requirement reaches the decision at a fixed slot width", () => {
122  const { observer, add } = setup();
123  const { switcher, slot, requirement } = add();
124  observer.deliver([slot, 454.573, 0], [requirement, 414.58334, 21]);
125  assert.equal(switcher.arrangement, "row");
126  // A longer label, a late font, or a larger gap resizes only the copy.
127  observer.deliver([requirement, 791.44794, 21]);
128  assert.equal(switcher.arrangement, "column");
129  observer.deliver([requirement, 414.58334, 21]);
130  assert.equal(switcher.arrangement, "row");
131});
132
133test("the same sizes give the same arrangement by any route", () => {
134  const reach = (...widths: number[]) => {
135    const { observer, add } = setup();
136    const outer = add(),
137      inner = add();
138    observer.deliver(
139      [outer.requirement, 544, 21],
140      [inner.requirement, 414, 21],
141    );
142    for (const width of widths)
143      observer.deliver([inner.slot, width, 0], [outer.slot, width, 0]);
144    return [outer.switcher.arrangement, inner.switcher.arrangement];
145  };
146  const mounted = reach(900);
147  assert.deepEqual(mounted, ["row", "row"]);
148  assert.deepEqual(reach(160, 900), mounted);
149  assert.deepEqual(reach(160, 300, 440, 580, 720, 900), mounted);
150  assert.deepEqual(reach(900, 160, 480), ["column", "row"]);
151  assert.deepEqual(reach(480), ["column", "row"]);
152});
153
154test("a hidden Switcher keeps its arrangement and is decided afresh when shown", () => {
155  const { observer, add } = setup();
156  const { switcher, slot, requirement } = add();
157  observer.deliver([slot, 500, 0], [requirement, 400, 21]);
158  // display: none reports both boxes as 0×0.
159  observer.deliver([slot, 0, 0], [requirement, 0, 0]);
160  assert.deepEqual(switcher.writes, ["row"], "hiding is not a failure to fit");
161  // Shown again in a narrower slot with longer content.
162  observer.deliver([requirement, 450, 21], [slot, 420, 0]);
163  assert.deepEqual(switcher.writes, ["row", "column"]);
164  // A Switcher that mounts hidden publishes nothing until it is rendered.
165  const late = add();
166  observer.deliver([late.slot, 0, 0], [late.requirement, 0, 0]);
167  assert.equal(late.switcher.arrangement, null);
168});
169
170test("a rendered copy with nothing in it is a requirement of zero", () => {
171  const { observer, add } = setup();
172  const { switcher, slot, requirement } = add();
173  observer.deliver([slot, 0, 0], [requirement, 0, 1]);
174  assert.equal(switcher.arrangement, "row");
175});
176
177test("unregistering stops observation and ignores entries already queued", () => {
178  const { coordinator, observer, add } = setup();
179  const first = add(),
180    second = add();
181  assert.equal(coordinator.size, 2);
182  assert.equal(observer.targets.size, 4);
183  first.unregister();
184  first.unregister();
185  assert.equal(coordinator.size, 1);
186  assert.deepEqual(
187    [...observer.targets],
188    [second.slot, second.requirement],
189    "only the remaining Switcher is observed",
190  );
191  observer.deliver([first.slot, 500, 0], [first.requirement, 400, 21]);
192  assert.equal(first.switcher.arrangement, null);
193  second.unregister();
194  assert.equal(coordinator.size, 0);
195  assert.equal(observer.targets.size, 0);
196});
197
198test("one Switcher cannot be registered twice, and can be registered again after cleanup", () => {
199  const { coordinator, add } = setup();
200  const { switcher, slot, requirement, unregister } = add();
201  const again = () =>
202    coordinator.register({
203      switcher,
204      slot,
205      requirement,
206    } as unknown as Parameters<SwitcherCoordinator["register"]>[0]);
207  assert.throws(again, /already registered/);
208  unregister();
209  again()();
210  assert.equal(coordinator.size, 0);
211});
212
213test("the trace reports each delivery, including decisions that wrote nothing", () => {
214  const { coordinator, observer, add } = setup();
215  const { switcher, slot, requirement } = add();
216  const seen: SwitcherDecision[][] = [];
217  coordinator.trace = (decisions) => seen.push([...decisions]);
218  observer.deliver([slot, 500, 0], [requirement, 400, 21]);
219  observer.deliver([slot, 450, 0]);
220  observer.deliver([slot, 0, 0], [requirement, 0, 0]);
221  assert.deepEqual(
222    seen.map(([decision]) => decision),
223    [
224      {
225        switcher,
226        slot: 500,
227        requirement: 400,
228        arrangement: "row",
229        written: true,
230      },
231      {
232        switcher,
233        slot: 450,
234        requirement: 400,
235        arrangement: "row",
236        written: false,
237      },
238      {
239        switcher,
240        slot: 0,
241        requirement: undefined,
242        arrangement: undefined,
243        written: false,
244      },
245    ],
246  );
247});
248
249test("a document has one coordinator and one observer, however many roots use it", () => {
250  const before = Deliveries.created.length;
251  const page = {
252    defaultView: { ResizeObserver: Observer },
253  } as unknown as Document;
254  const other = {
255    defaultView: { ResizeObserver: Observer },
256  } as unknown as Document;
257  assert.equal(switcherCoordinator(page), switcherCoordinator(page));
258  assert.notEqual(switcherCoordinator(page), switcherCoordinator(other));
259  assert.equal(Deliveries.created.length, before + 2);
260  assert.throws(
261    () => switcherCoordinator({ defaultView: null } as unknown as Document),
262    /window/,
263  );
264});