Document perseus-types.ts file #1975
Conversation
| 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]; |
There was a problem hiding this comment.
These changes are to "internalize" all types into this file instead of importing them from "outside". This means that if we upgrade Mafs and a type changes, we won't be implicitly breaking the schema. We'd still have type mismatches here in Perseus, but we'd then be able to rationalize the differences between our schema (this file) and the changed types.
jeremywiebe
requested review from
benchristel,
SonicScrewdriver,
nishasy,
mark-fitzgerald,
handeyeco,
Myranae,
catandthemachines and
anakaren-rojas
npm Snapshot: PublishedGood news!! We've packaged up the latest commit from this PR (928851a) and published it to npm. You Example: yarn add @khanacademy/perseus@PR1975If you are working in Khan Academy's webapp, you can run: ./dev/tools/bump_perseus_version.sh -t PR1975 |
|
Size Change: +591 B (+0.05%) Total Size: 1.29 MB
ℹ️ View Unchanged
|
|
|
||
| import type {Coord} from "./interactive2/types"; | ||
| import type {Interval, vec} from "mafs"; | ||
| // TODO(FEI-4010): Remove `Perseus` prefix for all types here |
There was a problem hiding this comment.
Do we even still want to remove the Perseus prefix for all the types here?
There was a problem hiding this comment.
I believe we still could, yes. Today, some of these type names get quite wordy.
But, I don't think we need to deal with that now.
| * 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. |
There was a problem hiding this comment.
My only feedback is that this seems to confident. It does represent all permutations of the data or it should?
But if you feel confident then just 🚢
There was a problem hiding this comment.
It's aspirational. :) The new parsing code validates against these types and so I think it's a fair statement.
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @khanacademy/[email protected] ### Patch Changes - [#1975](#1975) [`335615bab`](335615b) Thanks [@jeremywiebe](https://github.com/jeremywiebe)! - Make all types in `perseus-types.ts` originate from it (no longer import Mafs types) - [#1953](#1953) [`acd8bd566`](acd8bd5) Thanks [@daniellewhyte](https://github.com/daniellewhyte)! - [Dropdown] Change logic for aria-label ## @khanacademy/[email protected] ### Patch Changes - Updated dependencies \[[`335615bab`](335615b), [`acd8bd566`](acd8bd5)]: - @khanacademy/[email protected]
Summary:
The
perseus-types.tsfile is special in the Perseus project. It represents the data that is saved out of editors and consumed by the Perseus rendering system. As a result, we need to be extremely careful when making changes to it. I've added a JSDoc comment to the top of the file that (hopefully) explains the file and some cautions to take into account when making changes.Issue: LEMS-2561
Test plan:
Read the comments and let me know if they make sense and are clear. I'm happy to make further edits. :)