diff --git a/.changeset/clever-kangaroos-mate.md b/.changeset/clever-kangaroos-mate.md new file mode 100644 index 0000000000..1eb14b063c --- /dev/null +++ b/.changeset/clever-kangaroos-mate.md @@ -0,0 +1,5 @@ +--- +"@khanacademy/perseus": patch +--- + +Make all types in `perseus-types.ts` originate from it (no longer import Mafs types) diff --git a/packages/perseus/src/perseus-types.ts b/packages/perseus/src/perseus-types.ts index d6b73bc3c3..97248e90aa 100644 --- a/packages/perseus/src/perseus-types.ts +++ b/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"; /**