Document perseus-types.ts file

packages/perseus/src/perseus-types.ts

@@ -1,14 +1,40 @@
-// TODO(FEI-4010): Remove `Perseus` prefix for all types here
-// TODO(FEI-4011): Use types generated by https://github.com/jaredly/generate-perseus-flowtypes
+/**
+ * The Perseus "data schema" file.
+ *
+ * This file, and the types in it, represents the "data schema" that Perseus
+ * uses. The @khanacademy/perseus-editor package edits and produces objects
+ * that conform to the types in this file. Similarly, the top-level renderers
+ * in @khanacademy/perseus, consume objects that conform to these types.
+ *
+ * WARNING: This file should not import any types from elsewhere so that it is
+ * easy to reason about changes that alter the Perseus schema. This helps
+ * ensure that it is not changed accidentally when upgrading a dependant
+ * package or other part of Perseus code. Note that TypeScript does type
+ * checking via something called "structural typing". This means that as long
+ * as the shape of a type matches, the name it goes by doesn't matter. As a
+ * result, a `Coord` type that looks like this `[x: number, y: number]` is
+ * _identical_, in TypeScript's eyes, to this `Vector2` type `[x: number, y:
+ * number]`. Also, with tuples, the labels for each entry is ignored, so `[x:
+ * number, y: number]` is compatible with `[min: number, max: number]`. The
+ * labels are for humans, not TypeScript. :)
+ *
+ * If you make changes to types in this file, be very sure that:
+ *
+ *   a) the changes are backwards compatible. If they are not, old data from
+ *      previous versions of the "schema" could become unrenderable, or worse,
+ *      introduce hard-to-diagnose bugs.
+ *   b) the parsing code (`util/parse-perseus-json/`) is updated to handle
+ *      the new format _as well as_ the old format.
+ */
 
-import type {Coord} from "./interactive2/types";
-import type {Interval, vec} from "mafs";
+// TODO(FEI-4010): Remove `Perseus` prefix for all types here
 
-// Range is replaced within this file with Interval, but it is used elsewhere
-// and exported from the package, so we need to keep it around.
+export type Coord = [x: number, y: number];
+export type Interval = [min: number, max: number];
+export type Vector2 = Coord; // Same name as Mafs
 export type Range = Interval;
-export type Size = [number, number];
-export type CollinearTuple = [vec.Vector2, vec.Vector2];
+export type Size = [width: number, height: number];
+export type CollinearTuple = [Vector2, Vector2];
 export type ShowSolutions = "all" | "selected" | "none";
 
 /**