documentation/components/source/arrangement.ts

1/**
2 * Changing how a group arranges its members.
3 *
4 * An arrangement edit replaces one group's primitive and nothing else: the
5 * group keeps the same members, in the same order, at the same paths. That is
6 * why a saved arrangement can be validated against the starting composition
7 * position by position.
8 */
9import type { Composition, Group, Primitive } from "./composition.ts";
10import { atPath, replaceAt } from "./grouping.ts";
11
12export const arrangements: readonly Primitive[] = [
13  "Stack",
14  "Shelf",
15  "Switcher",
16];
17
18export function isArrangement(value: unknown): value is Primitive {
19  return arrangements.some((kind) => kind === value);
20}
21
22/** What each arrangement promises, whatever it looks like at one width. */
23export const arrangementContracts: Record<Primitive, string> = {
24  Stack: "A Stack keeps its members in one column at any width.",
25  Shelf:
26    "A Shelf keeps its members in one row, and scrolls when the row needs more room.",
27  Switcher:
28    "A Switcher uses one row when all its members fit, and one column when they do not.",
29};
30
31/** The group a selection names, when it names exactly one group. A leaf, a
32 * stale path or several paths name none; a leaf never stands for its parent. */
33export function arrangementTarget(
34  tree: Composition,
35  paths: readonly string[],
36): { readonly path: string; readonly group: Group } | undefined {
37  const [path, ...others] = paths;
38  if (path === undefined || others.length) return undefined;
39  const group = atPath(tree, path);
40  return group && "children" in group ? { path, group } : undefined;
41}
42
43/**
44 * Gives the group at `path` another arrangement. Every member is the same
45 * object as before. Choosing the arrangement a group already has returns
46 * `tree` itself, so a caller can tell that nothing changed.
47 */
48export function arrangeGroup(
49  tree: Composition,
50  path: string,
51  kind: Primitive,
52): Composition {
53  const target = arrangementTarget(tree, [path]);
54  if (!target) throw new Error("Select a group to change its arrangement.");
55  if (target.group.kind === kind) return tree;
56  return replaceAt(tree, path, { kind, children: target.group.children });
57}
58
59/** Paths of the groups arranged differently in two compositions with the
60 * same members. Compositions with different members have no such paths. */
61export function changedArrangements(
62  before: Composition,
63  after: Composition,
64): string[] {
65  const changed: string[] = [];
66  function compare(a: Composition, b: Composition, path: string): boolean {
67    if (!("children" in a) || !("children" in b))
68      return (
69        !("children" in a) &&
70        !("children" in b) &&
71        a.kind === b.kind &&
72        a.text === b.text
73      );
74    if (a.children.length !== b.children.length) return false;
75    if (a.kind !== b.kind) changed.push(path);
76    return a.children.every((child, index) =>
77      compare(child, b.children[index]!, `${path}.${index}`),
78    );
79  }
80  return compare(before, after, "0") ? changed : [];
81}
82
83/**
84 * Reads a saved arrangement of `initial`. Only group kinds are taken from the
85 * saved value. Its nesting, leaf kinds, text and order must match `initial`
86 * exactly, and the result is built from `initial`'s own leaves, so saved data
87 * cannot regroup, reorder, replace or add content.
88 */
89export function restoreArrangement(
90  saved: unknown,
91  initial: Composition,
92): Composition | undefined {
93  function restore(value: unknown, node: Composition): Composition | undefined {
94    if (!value || typeof value !== "object") return undefined;
95    const record = value as Record<string, unknown>;
96    if (!("children" in node))
97      return record.kind === node.kind && record.text === node.text
98        ? node
99        : undefined;
100    if (
101      !isArrangement(record.kind) ||
102      !Array.isArray(record.children) ||
103      record.children.length !== node.children.length
104    )
105      return undefined;
106    const children: Composition[] = [];
107    for (const [index, member] of node.children.entries()) {
108      const child = restore(record.children[index], member);
109      if (!child) return undefined;
110      children.push(child);
111    }
112    return { kind: record.kind, children };
113  }
114  return restore(saved, initial);
115}