Remove readonly types from data-schema.ts (#2398)

## Summary:
See the [slack discussion] for more details. TL;DR:

- The `readonly` modifier in TypeScript simply removes mutating operations like
  `Array.push` and `obj.foo = 1` property assignment from a type.
- As such, it's best to think of it as an application of the [Interface
  Segregation Principle].
- That implies that `readonly` types are most appropriate in function parameters.
  There, they act as a promise that the function won't mutate its arguments.
- They may also be appropriate in return types **if** the function returns a
  frozen object or array, because frozen objects actually disallow mutation at
  runtime.
- In general, readonly types are **not** appropriate in the return types of
  functions, because they unnecessarily restrict the caller from mutating an
  object to which no one else holds a reference.
- That means readonly types are probably **not** appropriate for shared data types
  which may be used in _either_ parameters or return values.
- We weren't using readonly types consistently in `data-schema.ts` to begin with.
  We used them for arrays, but not for tuples or objects.
- For the sake of consistency, and to allow our `data-schema` types to be reused
  easily in different contexts, this PR replaces `ReadonlyArray` with `Array` in
  `data-schema.ts` and fixes the type errors that cascade out of that.

[slack discussion]: https://khanacademy.slack.com/archives/C01AZ9H8TTQ/p1744325813358959
[Interface Segregation Principle]: https://en.wikipedia.org/wiki/Interface_segregation_principle

Issue: LEMS-XXXX

## Test plan:

`pnpm tsc`

Author: benchristel

Reviewers: jeremywiebe, benchristel, handeyeco

Required Reviewers:

Approved By: jeremywiebe

Checks: ✅ 8 checks were successful

Pull Request URL: #2398

Author: benchristel

.changeset/bright-guests-march.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/perseus-core": major
+---
+
+Remove ReadonlyArray types from `@khanacademy/perseus-core` in favor of mutable arrays. Users should define separate readonly types if desired.

packages/perseus-core/src/data-schema.ts

@@ -6,6 +6,7 @@ export type {
     InteractiveMarkerType,
     Relationship,
     Alignment,
+    RecursiveReadonly,
 } from "./types";
 export type {
     KeypadKey,

packages/perseus-core/src/index.ts

@@ -115,7 +115,7 @@ export type KeypadType = "FRACTION" | "EXPRESSION";
 
 export type KeypadConfiguration = {
     keypadType: KeypadType;
-    extraKeys?: ReadonlyArray<KeypadKey>;
+    extraKeys?: KeypadKey[];
     times?: boolean;
     scientific?: boolean;
 };

packages/perseus-core/src/keypad.ts

@@ -1,6 +1,8 @@
 import {array, enumeration} from "../general-purpose-parsers";
 import {defaulted} from "../general-purpose-parsers/defaulted";
 
+import type {LegacyButtonSets} from "../../data-schema";
+
 export const parseLegacyButtonSet = enumeration(
     "basic",
     "basic+div",
@@ -17,5 +19,5 @@ export const parseLegacyButtonSets = defaulted(
     // NOTE(benchristel): I copied the default buttonSets from
     // expression.tsx. See the parse-perseus-json/README.md for
     // an explanation of why we want to duplicate the default here.
-    () => ["basic", "trig", "prealgebra", "logarithms"] as const,
+    (): LegacyButtonSets => ["basic", "trig", "prealgebra", "logarithms"],
 );

packages/perseus-core/src/parse-perseus-json/perseus-parsers/legacy-button-sets.ts

@@ -26,7 +26,7 @@ export type KEScore = {
 // Base marker, with the props that are set by the editor.
 export type MarkerType = {
     // The list of correct answers expected for the marker.
-    answers: ReadonlyArray<string>;
+    answers: string[];
     // The marker title or description.
     label: string;
     // The marker coordinates on the question image as percent of image size.
@@ -37,7 +37,7 @@ export type MarkerType = {
 // Additional props that are set when user interacts with the marker.
 export type InteractiveMarkerType = MarkerType & {
     // The user selected list of answers, used to grade the question.
-    selected?: ReadonlyArray<string>;
+    selected?: string[];
     // Reveal the correctness state of the user selected answers for the marker.
     showCorrectness?: "correct" | "incorrect";
     focused?: boolean;
@@ -55,3 +55,7 @@ export type Alignment =
     | "float-left"
     | "float-right"
     | "full-width";
+
+export type RecursiveReadonly<T> = {
+    readonly [K in keyof T]: RecursiveReadonly<T[K]>;
+};

packages/perseus-core/src/types.ts

@@ -29,9 +29,9 @@ export function shuffle<T>(
     array: ReadonlyArray<T>,
     randomSeed: number | RNG,
     ensurePermuted = false,
-): ReadonlyArray<T> {
+): T[] {
     // Always return a copy of the input array
-    const shuffled = _.clone(array);
+    const shuffled = [...array];
 
     // Handle edge cases (input array is empty or uniform)
     if (
@@ -57,9 +57,7 @@ export function shuffle<T>(
             const newEnd = Math.floor(random() * top);
             const temp = shuffled[newEnd];
 
-            // @ts-expect-error - TS2542 - Index signature in type 'readonly T[]' only permits reading.
             shuffled[newEnd] = shuffled[top - 1];
-            // @ts-expect-error - TS2542 - Index signature in type 'readonly T[]' only permits reading.
             shuffled[top - 1] = temp;
         }
     } while (ensurePermuted && _.isEqual(array, shuffled));

packages/perseus-core/src/utils/random-util.ts

@@ -82,7 +82,7 @@ export type UserInputStatus = "correct" | "incorrect" | "incomplete";
 export type PerseusCategorizerRubric = {
     // The correct answers where index relates to the items and value relates
     // to the category.  e.g. [0, 1, 0, 1, 2]
-    values: ReadonlyArray<number>;
+    values: number[];
 } & PerseusCategorizerValidationData;
 
 export type PerseusCategorizerUserInput = {
@@ -91,7 +91,7 @@ export type PerseusCategorizerUserInput = {
 
 export type PerseusCategorizerValidationData = {
     // Translatable text; a list of items to categorize. e.g. ["banana", "yellow", "apple", "purple", "shirt"]
-    items: ReadonlyArray<string>;
+    items: string[];
 };
 
 export type PerseusCSProgramUserInput = {
@@ -100,16 +100,16 @@ export type PerseusCSProgramUserInput = {
 };
 
 export type PerseusDropdownRubric = {
-    choices: ReadonlyArray<PerseusDropdownChoice>;
+    choices: Array<PerseusDropdownChoice>;
 };
 
 export type PerseusDropdownUserInput = {
     value: number;
 };
 
 export type PerseusExpressionRubric = {
-    answerForms: ReadonlyArray<PerseusExpressionAnswerForm>;
-    functions: ReadonlyArray<string>;
+    answerForms: Array<PerseusExpressionAnswerForm>;
+    functions: string[];
 };
 
 export type PerseusExpressionUserInput = string;
@@ -162,29 +162,29 @@ export type PerseusInteractiveGraphRubric = {
 export type PerseusInteractiveGraphUserInput = PerseusGraphType;
 
 export type PerseusLabelImageRubric = {
-    markers: ReadonlyArray<{
-        answers: ReadonlyArray<string>;
+    markers: Array<{
+        answers: string[];
         label: string;
     }>;
 };
 
 export type PerseusLabelImageUserInput = {
-    markers: ReadonlyArray<{
-        selected?: ReadonlyArray<string>;
+    markers: Array<{
+        selected?: string[];
         label: string;
     }>;
 };
 
 export type PerseusMatcherRubric = {
     // Translatable Text; Static concepts to show in the left column. e.g. ["Fruit", "Color", "Clothes"]
-    left: ReadonlyArray<string>;
+    left: string[];
     // Translatable Markup; Values that represent the concepts to be correlated with the concepts.  e.g. ["Red", "Shirt", "Banana"]
-    right: ReadonlyArray<string>;
+    right: string[];
 };
 
 export type PerseusMatcherUserInput = {
-    left: ReadonlyArray<string>;
-    right: ReadonlyArray<string>;
+    left: string[];
+    right: string[];
 };
 
 export type PerseusMatrixRubric = {
@@ -201,7 +201,7 @@ export type PerseusMatrixUserInput = {
 export type PerseusNumberLineRubric = {
     correctRel: string | null | undefined;
     correctX: number;
-    range: ReadonlyArray<number>;
+    range: number[];
     initialX: number | null | undefined;
     isInequality: boolean;
 };
@@ -211,12 +211,12 @@ export type PerseusNumberLineUserInput = {
     numLinePosition: number;
     rel: Relationship | "eq";
     numDivisions: number;
-    divisionRange: ReadonlyArray<number>;
+    divisionRange: number[];
 };
 
 export type PerseusNumericInputRubric = {
     // A list of all the possible correct and incorrect answers
-    answers: ReadonlyArray<PerseusNumericInputAnswer>;
+    answers: PerseusNumericInputAnswer[];
     // A coefficient style number allows the student to use - for -1 and an empty string to mean 1.
     coefficient: boolean;
 };
@@ -228,46 +228,46 @@ export type PerseusNumericInputUserInput = {
 export type PerseusOrdererRubric = PerseusOrdererWidgetOptions;
 
 export type PerseusOrdererUserInput = {
-    current: ReadonlyArray<string>;
+    current: string[];
 };
 
 export type PerseusPlotterRubric = {
     // The Y values that represent the correct answer expected
-    correct: ReadonlyArray<number>;
+    correct: number[];
 } & PerseusPlotterValidationData;
 
 export type PerseusPlotterValidationData = {
     // The Y values the graph should start with
-    starting: ReadonlyArray<number>;
+    starting: number[];
 };
 
-export type PerseusPlotterUserInput = ReadonlyArray<number>;
+export type PerseusPlotterUserInput = number[];
 
 export type PerseusRadioRubric = {
     // The choices provided to the user.
-    choices: ReadonlyArray<PerseusRadioChoice>;
+    choices: PerseusRadioChoice[];
 };
 
 export type PerseusRadioUserInput = {
-    choicesSelected: ReadonlyArray<boolean>;
+    choicesSelected: boolean[];
 };
 
 export type PerseusSorterRubric = {
     // Translatable Text; The correct answer (in the correct order). The user will see the cards in a randomized order.
-    correct: ReadonlyArray<string>;
+    correct: string[];
 };
 
 export type PerseusSorterUserInput = {
-    options: ReadonlyArray<string>;
+    options: string[];
     changed: boolean;
 };
 
 export type PerseusTableRubric = {
     // Translatable Text; A 2-dimensional array of text to populate the table with
-    answers: ReadonlyArray<ReadonlyArray<string>>;
+    answers: string[][];
 };
 
-export type PerseusTableUserInput = ReadonlyArray<ReadonlyArray<string>>;
+export type PerseusTableUserInput = string[][];
 
 export interface RubricRegistry {
     categorizer: PerseusCategorizerRubric;
@@ -352,7 +352,7 @@ export type UserInputMap = MakeWidgetMap<UserInputRegistry>;
 /**
  * deprecated prefer using UserInputMap
  */
-export type UserInputArray = ReadonlyArray<
+export type UserInputArray = Array<
     UserInputArray | UserInput | null | undefined
 >;
 

packages/perseus-core/src/validation.types.ts

@@ -16,12 +16,12 @@ function deriveExtraKeys(
     widgetOptions: PerseusExpressionWidgetOptions,
 ): KeypadConfiguration["extraKeys"] {
     if (widgetOptions.extraKeys) {
-        return widgetOptions.extraKeys as ReadonlyArray<KeypadKey>;
+        return widgetOptions.extraKeys;
     }
 
     // If there are no extra symbols available, we include Pi anyway, so
     // that the "extra symbols" button doesn't appear empty.
-    const defaultKeys: ReadonlyArray<KeypadKey> = ["PI"];
+    const defaultKeys: KeypadKey[] = ["PI"];
 
     if (widgetOptions.answerForms == null) {
         return defaultKeys;

packages/perseus-core/src/widgets/expression/derive-extra-keys.ts

@@ -38,8 +38,8 @@ export const shuffleMatcher = (
 
 // TODO(LEMS-2841): Can shorten to shuffleMatcher after above function removed
 function shuffleMatcherWithRandom(data: MatcherShuffleInfo): {
-    left: ReadonlyArray<string>;
-    right: ReadonlyArray<string>;
+    left: string[];
+    right: string[];
 } {
     // Use the same random() function to shuffle both columns sequentially
     let left;

packages/perseus-core/src/widgets/matcher/matcher-util.ts

@@ -10,8 +10,8 @@ import CoordinatePairInput from "../../../components/coordinate-pair-input";
 import type {Coord} from "@khanacademy/perseus";
 
 type Props = {
-    startCoords: ReadonlyArray<Coord>;
-    onChange: (startCoords: ReadonlyArray<Coord>) => void;
+    startCoords: Coord[];
+    onChange: (startCoords: Coord[]) => void;
 };
 
 const StartCoordsPoint = (props: Props) => {

packages/perseus-editor/src/widgets/interactive-graph-editor/start-coords/start-coords-point.tsx

@@ -25,7 +25,7 @@ import type {
 
 type Props = {
     // List of answer choices to label question image with.
-    choices: ReadonlyArray<string>;
+    choices: string[];
     // The question image properties.
     imageAlt: string;
     imageUrl: string;

packages/perseus-editor/src/widgets/label-image-editor.tsx

@@ -162,8 +162,6 @@ export default class Marker extends React.Component<Props, State> {
 
                             <OptionGroup
                                 onSelected={this.handleSelectAnswer}
-                                // TODO(WB-1096): make selectedValues immutable in wonder-blocks
-                                // @ts-expect-error - TS2769 - No overload matches this call.
                                 selectedValues={answers}
                             >
                                 {choices.map((choice) => (

packages/perseus-editor/src/widgets/label-image/marker.tsx

@@ -15,7 +15,7 @@ import type {PerseusLabelImageWidgetOptions} from "@khanacademy/perseus-core";
 
 type Props = {
     // The list of possible answers in a specific order.
-    choices: ReadonlyArray<string>;
+    choices: string[];
     // The question image properties.
     imageUrl: string;
     imageWidth: number;

packages/perseus-editor/src/widgets/label-image/question-markers.tsx

@@ -101,7 +101,7 @@ class ChoiceEditor extends React.Component<ChoiceEditorProps> {
 type RadioEditorProps = {
     apiOptions: APIOptions;
     countChoices: boolean;
-    choices: ReadonlyArray<PerseusRadioChoice>;
+    choices: PerseusRadioChoice[];
     displayCount: number;
     randomize: boolean;
     hasNoneOfTheAbove: boolean;

packages/perseus-editor/src/widgets/radio/editor.tsx

@@ -11,7 +11,7 @@ describe("scoreCategorizer", () => {
 
         const userInput = {
             values: [1, 3],
-        } as const;
+        };
         const score = scoreCategorizer(userInput, rubric);
 
         expect(score).toHaveBeenAnsweredCorrectly();
@@ -25,7 +25,7 @@ describe("scoreCategorizer", () => {
 
         const userInput = {
             values: [2, 3],
-        } as const;
+        };
         const score = scoreCategorizer(userInput, rubric);
 
         expect(score).toHaveBeenAnsweredIncorrectly();

packages/perseus-score/src/widgets/categorizer/score-categorizer.test.ts

@@ -10,7 +10,7 @@ describe("validateCategorizer", () => {
 
         const userInput = {
             values: [2],
-        } as const;
+        };
         const score = validateCategorizer(userInput, validationData);
 
         expect(score).toHaveInvalidInput("INVALID_SELECTION_ERROR");
@@ -23,7 +23,7 @@ describe("validateCategorizer", () => {
 
         const userInput = {
             values: [2, 4],
-        } as const;
+        };
         const score = validateCategorizer(userInput, validationData);
 
         expect(score).toBeNull();

packages/perseus-score/src/widgets/categorizer/validate-categorizer.test.ts

@@ -168,8 +168,9 @@ function scoreInteractiveGraph(
             // eq() comparison but _.isEqual(0, -0) is false, so we'll use
             // eq() anyway. The sort should be fine because it'll stringify
             // it and -0 converted to a string is "0"
+            // TODO(benchristel): once we drop support for Safari 15, use
+            // toSorted here to avoid mutating the input arrays!
             guess?.sort();
-            // @ts-expect-error - TS2339 - Property 'sort' does not exist on type 'readonly Coord[]'.
             correct.sort();
             if (approximateDeepEqual(guess, correct)) {
                 return {