documentation/components/source/composition.ts

1export type Primitive = "Stack" | "Shelf" | "Switcher";
2export type LeafKind = "Text" | "Heading" | "Meta";
3export type Composition =
4  | { readonly kind: Primitive; readonly children: readonly Composition[] }
5  | { readonly kind: LeafKind; readonly text: string };
6export type Group = Extract<Composition, { readonly kind: Primitive }>;
7export const exampleNames = [
8  "flat",
9  "nested",
10  "grouped",
11  "shelf",
12  "switcher",
13  "nested-switcher",
14  "article",
15  "event",
16  "investigation",
17] as const;
18export type ExampleName = (typeof exampleNames)[number];
19export const Stack = (...children: Composition[]): Composition => ({
20  kind: "Stack",
21  children,
22});
23export const Shelf = (...children: Composition[]): Composition => ({
24  kind: "Shelf",
25  children,
26});
27export const Switcher = (...children: Composition[]): Composition => ({
28  kind: "Switcher",
29  children,
30});
31const Text = (text: string): Composition => ({ kind: "Text", text });
32const Heading = (text: string): Composition => ({ kind: "Heading", text });
33const Meta = (text: string): Composition => ({ kind: "Meta", text });
34export function example(
35  name: ExampleName,
36  label = "Run lasted 4m 1s",
37): Composition {
38  const a = Text("Execution completed"),
39    b = Text(label),
40    c = Text("Remediation Plan proposed"),
41    d = Text("Awaiting approval");
42  switch (name) {
43    case "flat":
44      return Stack(a, b, c, d);
45    case "nested":
46      return Stack(Stack(a, b), Stack(c, d));
47    // The Switcher example's facts with every group a Stack: the starting
48    // point for choosing arrangements.
49    case "grouped":
50      return Stack(Stack(a, b, Text("3 checks passed")), Stack(c, d));
51    case "shelf":
52      return Stack(Shelf(a, b), Stack(c, d));
53    case "switcher":
54      return Stack(Switcher(a, b, Text("3 checks passed")), Stack(c, d));
55    case "nested-switcher":
56      return Switcher(Switcher(a, b, Text("Three checks passed")), d);
57    case "investigation":
58      return Stack(
59        Heading("Request-log queries exceed 30-second runtime budget"),
60        Text("Investigation completed"),
61        Text("Investigation updated: Nov 18, 10:34 AM"),
62        Text("Remediation Plan: Bound the request-log query"),
63        Text("Remediation Plan awaiting approval"),
64        Text("Destination: investigation session"),
65      );
66    case "event":
67      return Stack(
68        Text("Neighborhood repair café"),
69        Text("Saturday, 10 am–1 pm"),
70        Text("Maple Street Library"),
71        Text("Free; book a table by Friday"),
72        Text("Tell us about access needs when you book"),
73      );
74    case "article":
75      return Stack(
76        Stack(
77          Heading("Reading the sky"),
78          Text("A field guide to noticing the weather"),
79          Shelf(Meta("Mara Ellis"), Meta("19 November")),
80        ),
81        Stack(
82          Text(
83            "A forecast tells you what may happen. Looking outside tells you what is happening here.",
84          ),
85          Stack(
86            Text("Before you leave, look for:"),
87            Stack(
88              Text("Clouds building above the hills"),
89              Text("A change in the direction of the wind"),
90            ),
91          ),
92        ),
93      );
94  }
95}
96export interface SourceToken {
97  readonly text: string;
98  readonly tone?: "primitive" | "string";
99  readonly path?: string;
100  readonly kind?: Composition["kind"];
101}
102export interface SourceLine {
103  readonly depth: number;
104  readonly tokens: readonly SourceToken[];
105  readonly path?: string;
106}
107function leafTokens(value: Composition, path: string): SourceToken[] {
108  if ("children" in value) throw new Error("Expected a leaf");
109  return [
110    { text: value.kind, path, kind: value.kind },
111    { text: "(", path },
112    { text: JSON.stringify(value.text), tone: "string", path },
113    { text: ")", path },
114  ];
115}
116export function declaration(
117  value: Composition,
118  path = "0",
119  depth = 0,
120  printWidth = 80,
121): SourceLine[] {
122  const pad = { text: "  ".repeat(depth) };
123  if (!("children" in value)) {
124    const tokens = leafTokens(value, path);
125    if (
126      depth * 2 + tokens.reduce((size, token) => size + token.text.length, 0) <=
127      printWidth
128    )
129      return [{ tokens: [pad, ...tokens], path, depth }];
130    return [
131      { tokens: [pad, ...tokens.slice(0, 2)], path, depth },
132      {
133        tokens: [{ text: "  ".repeat(depth + 1) }, tokens[2]!],
134        path,
135        depth: depth + 1,
136      },
137      { tokens: [pad, tokens[3]!], path, depth },
138    ];
139  }
140  const head: SourceToken[] = [
141    pad,
142    { text: value.kind, tone: "primitive", path, kind: value.kind },
143    { text: "(" },
144  ];
145  if (value.children.every((child) => !("children" in child))) {
146    value.children.forEach((child, index) => {
147      if (index) head.push({ text: ", " });
148      head.push(...leafTokens(child, `${path}.${index}`));
149    });
150    head.push({ text: ")" });
151    if (head.reduce((size, token) => size + token.text.length, 0) <= printWidth)
152      return [{ tokens: head, path, depth }];
153    // The flat form did not fit. Keep the same tokens/paths in a broken group.
154    head.splice(3);
155  }
156  const lines: SourceLine[] = [{ tokens: head, path, depth }];
157  value.children.forEach((child, index) => {
158    const childLines = declaration(
159      child,
160      `${path}.${index}`,
161      depth + 1,
162      printWidth - (index < value.children.length - 1 ? 1 : 0),
163    );
164    if (index < value.children.length - 1) {
165      const last = childLines.at(-1)!;
166      childLines[childLines.length - 1] = {
167        ...last,
168        tokens: [...last.tokens, { text: "," }],
169      };
170    }
171    lines.push(...childLines);
172  });
173  lines.push({ tokens: [pad, { text: ")" }], path, depth });
174  return lines;
175}