Improve Typescript type annotations (#92)

Also fix bug in applying roughjs_config styling.

CHANGELOG.md

@@ -17,6 +17,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 -   Fixed a bug where the `Download JSON` button would not download the JSON currently inside the input box.
 -   Made sure file input would reset when file input dialog was closed.
+-   Fixed a bug where the styles in `DisplaySettings.roughjs_config` were not applied.
 
 ### 📚 Documentation and demo website changes
 
@@ -27,6 +28,8 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### 🔧 Internal changes
 
+-   Added better typing.
+
 ## [0.3.2] - 2024-09-14
 
 ### ✨ Enhancements

docs/.gitignore

@@ -7,6 +7,7 @@
 # Generated files
 .docusaurus
 .cache-loader
+/docs/api
 
 # Misc
 .DS_Store

docs/docusaurus.config.js

@@ -145,7 +145,6 @@ const config = {
                 entryPoints: ["../memory-viz/src/user_functions.ts"],
                 readme: "none",
                 tsconfig: "../tsconfig.json",
-                out: "99-api",
             },
         ],
     ],

memory-viz/package.json

@@ -54,6 +54,7 @@
         "@types/jest": "^29.5.12",
         "@types/node": "^20.10.5",
         "babel-loader": "^9.1.0",
+        "csstype": "^3.1.3",
         "husky": "^9.1.5",
         "jest": "^29.7.0",
         "tmp": "^0.2.3",

memory-viz/src/automate.ts

@@ -1,17 +1,21 @@
 import { MemoryModel } from "./memory_model";
 import { config } from "./config";
-import { DrawnEntity } from "./types";
+import { DisplaySettings, DrawnEntity, Size, SortOptions } from "./types";
 
 /**
  * Draws the objects given in the path in an automated fashion.
  *
- * @param {DrawnEntity[]} objects - The list of objects that will be drawn on the canvas.
- * @param {Object} configuration - The configuration settings defined by the user.
- * @param {number} width - User-defined width of the canvas.
- * @returns {MemoryModel} - The memory model that is created according to the objects given in the path (the JSON
+ * @param objects - The list of objects that will be drawn on the canvas.
+ * @param configuration - The configuration settings defined by the user.
+ * @param width - User-defined width of the canvas.
+ * @returns - The memory model that is created according to the objects given in the path (the JSON
  * file)
  */
-function drawAutomated(objects: DrawnEntity[], width, configuration) {
+function drawAutomated(
+    objects: DrawnEntity[],
+    width: number,
+    configuration: Partial<DisplaySettings>
+): MemoryModel {
     const { stack_frames, other_items } = separateObjects(objects);
 
     // Assigning the objects with coordinates.
@@ -20,7 +24,7 @@ function drawAutomated(objects: DrawnEntity[], width, configuration) {
 
     // Determining the minimum width of the canvas.
     let min_width = 0;
-    let item_width;
+    let item_width: number;
     for (const item of other_items) {
         item_width = getSize(item).width;
         if (item_width > min_width) {
@@ -65,15 +69,22 @@ function drawAutomated(objects: DrawnEntity[], width, configuration) {
  * height for drawing the stack-frames. The returned collection of stack-frames is the augmented version
  * of the input such that the x and y coordinates of the stack-frames are determined automatically.
  *
- * @param {Object} configuration - The configuration set by the user.
- * @param {DrawnEntity[]} stack_frames - The list of stack-frames that will be drawn
+ * @param configuration - The configuration set by the user.
+ * @param stack_frames - The list of stack-frames that will be drawn
  * (without the specified x and y coordinates)
- * @returns {Object} - Returns the object consisting of three attributes as follows: stack-frames which will be drawn,
+ * @returns - Returns the object consisting of three attributes as follows: stack-frames which will be drawn,
  * the minimum required height of the canvas for drawing stack frames and required width for drawing all the stack
  * frames. Notably, the last two attributes will be useful in terms of dynamically deciding the width and the height
  * of the canvas.
  */
-function drawAutomatedStackFrames(stack_frames: DrawnEntity[], configuration) {
+function drawAutomatedStackFrames(
+    stack_frames: DrawnEntity[],
+    configuration: Partial<DisplaySettings>
+): {
+    StackFrames: DrawnEntity[];
+    requiredHeight: number;
+    requiredWidth: number;
+} {
     for (const req_prop of [
         "padding",
         "top_margin",
@@ -93,8 +104,8 @@ function drawAutomatedStackFrames(stack_frames: DrawnEntity[], configuration) {
     let draw_stack_frames = [];
 
     for (const stack_frame of stack_frames) {
-        let width;
-        let height;
+        let width: number;
+        let height: number;
 
         if (stack_frame.type !== ".blank-frame") {
             const size = getSize(stack_frame);
@@ -135,22 +146,22 @@ function drawAutomatedStackFrames(stack_frames: DrawnEntity[], configuration) {
  * desired canvas width, this function mutates the passed list to equip each object with coordinates (corresponding to
  * the top-left corner of the object's box in the canvas).
  *
- * @param {DrawnEntity[]} objs - list of objects in the format described in MemoryModel.drawAll
- * @param {number} max_width - the desired width of the canvas
- * @param {*} sort_by - the sorting criterion; must be "height" or "id", otherwise no sorting takes place.
- * @param {object} config_aut - additional configuration options, such as margins, paddings, e.t.c.
- * @param {number} sf_endpoint - the x-coordinate of the right edge of the stackframe column; this will determine
+ * @param objs - list of objects in the format described in MemoryModel.drawAll
+ * @param max_width - the desired width of the canvas
+ * @param sort_by - the sorting criterion; must be "height" or "id", otherwise no sorting takes place.
+ * @param config_aut - additional configuration options, such as margins, paddings, e.t.c.
+ * @param sf_endpoint - the x-coordinate of the right edge of the stackframe column; this will determine
  *                              where the object space begins.
- * @returns {object} the mutates list of objects (where each object is now equipped with x-y coordinates) and the
+ * @returns the mutates list of objects (where each object is now equipped with x-y coordinates) and the
  * dynamically determined height the canvas will need to be.
  */
 function drawAutomatedOtherItems(
     objs: DrawnEntity[],
-    max_width,
-    sort_by,
-    config_aut: any = {} /* to avoid undefined error */,
-    sf_endpoint
-) {
+    max_width: number,
+    sort_by: SortOptions,
+    config_aut: Partial<DisplaySettings>,
+    sf_endpoint: number
+): { objs: DrawnEntity[]; canvas_height: number; canvas_width: number } {
     for (const req_prop of [
         "padding",
         "top_margin",
@@ -184,15 +195,15 @@ function drawAutomatedOtherItems(
      * This "compare" function is created and assigned to the variable 'compareFunc' in the following switch statement.
      * @param a - an object in objs
      * @param b - another object in objs
-     * @returns {number} negative if 'a' is taller, 0 if they have the same height, and positive if 'b' is taller.
+     * @returns negative if 'a' is taller, 0 if they have the same height, and positive if 'b' is taller.
      */
-    let compareFunc;
+    let compareFunc: (a: DrawnEntity, b: DrawnEntity) => number;
 
     switch (sort_by) {
-        case "height":
+        case SortOptions.Height:
             compareFunc = compareByHeight;
             break;
-        case "id":
+        case SortOptions.Id:
             compareFunc = compareByID;
             break;
     }
@@ -205,7 +216,7 @@ function drawAutomatedOtherItems(
     let y_coord = config_aut.top_margin;
 
     // Once a row is occupied, we must establish its height to determine the y-coordinate of the next row's boxes.
-    let row_height;
+    let row_height: number;
     let curr_row_objects = [];
     for (const item of objs) {
         let hor_reach = x_coord + item.width + PADDING;
@@ -267,11 +278,14 @@ function drawAutomatedOtherItems(
  * The returned object has two attributes as 'stack_frames' and 'other_items'.
  * Each of these attributes are a list of objects that were originally given by the user.
  *
- * @param {DrawnEntity[]} objects - The list of objects, including stack-frames (if any) and other items, that
+ * @param objects - The list of objects, including stack-frames (if any) and other items, that
  * will be drawn
- * @returns {object} an object separating between stack-frames and the rest of the items.
+ * @returns an object separating between stack-frames and the rest of the items.
  */
-function separateObjects(objects: DrawnEntity[]) {
+function separateObjects(objects: DrawnEntity[]): {
+    stack_frames: DrawnEntity[];
+    other_items: DrawnEntity[];
+} {
     let stackFrames = [];
     let otherItems = [];
 
@@ -301,10 +315,10 @@ function separateObjects(objects: DrawnEntity[]) {
  * Return the dimensions that the passed object will have if drawn on a canvas (in the context of the MemoryModel class).
  * This function can be used to determine how much space an object box will take on canvas (like a dry-run), given the
  * implementations of the 'draw' methods in MemoryModel.
- * @param {DrawnEntity} obj - an object as specified in MemoryModel.drawAll, except that coordinates are missing.
- * @returns {object} the width and the height the drawn object would have.
+ * @param obj - an object as specified in MemoryModel.drawAll, except that coordinates are missing.
+ * @returns the width and the height the drawn object would have.
  */
-function getSize(obj: DrawnEntity) {
+function getSize(obj: DrawnEntity): Size {
     // The x and y values here are unimportant; 'obj' must simply have these properties for processing by 'drawAll'.
     obj.x = obj.x || 10;
     obj.y = obj.y || 10;
@@ -323,9 +337,9 @@ function getSize(obj: DrawnEntity) {
  * function, it will prioritize 'a' over 'b'), 0 if they are equally tall, and positive if 'b' is taller.
  * @param a - an object
  * @param b - another object
- * @returns {number} negative if 'a' is taller, 0 if they have the same height, and positive if 'b' is taller.
+ * @returns negative if 'a' is taller, 0 if they have the same height, and positive if 'b' is taller.
  */
-function compareByHeight(a, b) {
+function compareByHeight(a: DrawnEntity, b: DrawnEntity): number {
     return -(a.height - b.height);
 }
 
@@ -336,9 +350,9 @@ function compareByHeight(a, b) {
  * and positive if 'b.id' is larger.
  * @param a - an object
  * @param b - another object
- * @returns {number} negative if 'a.id' is larger, 0 if a.id == b.id, and positive if 'b.id' is larger.
+ * @returns negative if 'a.id' is larger, 0 if a.id == b.id, and positive if 'b.id' is larger.
  */
-function compareByID(a, b) {
+function compareByID(a: DrawnEntity, b: DrawnEntity): number {
     return a.id - b.id;
 }
 
@@ -348,9 +362,9 @@ function compareByID(a, b) {
  * 'b' is righter.
  * @param a - an object
  * @param b - another object
- * @returns {number} negative if 'a' is righter, 0 if 'a' and 'b' are equally right, and positive if b' is righter.
+ * @returns negative if 'a' is righter, 0 if 'a' and 'b' are equally right, and positive if b' is righter.
  */
-function compareByRightness(a, b) {
+function compareByRightness(a: DrawnEntity, b: DrawnEntity): number {
     const a_right_edge = a.x + a.width;
     const b_right_edge = b.x + b.width;
     return -(a_right_edge - b_right_edge);
@@ -362,9 +376,9 @@ function compareByRightness(a, b) {
  * 'b' is bottomer.
  * @param a - an object
  * @param b - another object
- * @returns {number} negative if 'a' is bottomer, 0 if 'a' and 'b' are equally bottom, and positive if b' is bottomer.
+ * @returns negative if 'a' is bottomer, 0 if 'a' and 'b' are equally bottom, and positive if b' is bottomer.
  */
-function compareByBottomness(a, b) {
+function compareByBottomness(a: DrawnEntity, b: DrawnEntity): number {
     const a_bottom_edge = a.y + a.height;
     const b_bottom_edge = b.y + b.height;
     return -(a_bottom_edge - b_bottom_edge);

memory-viz/src/config.ts

@@ -1,4 +1,6 @@
-export const config = {
+import { VisualizationConfig } from "./types";
+
+export const config: Partial<VisualizationConfig> = {
     rect_style: { stroke: "rgb(0, 0, 0)" },
     text_color: "rgb(0, 0, 0)", // Default text color
     value_color: "rgb(27, 14, 139)", // Text color for primitive values