From c828a2eb6f1b69ea62780ea100003b81c137585f Mon Sep 17 00:00:00 2001
From: Aristotelis <5459332+glutanimate@users.noreply.github.com>
Date: Fri, 20 Oct 2023 01:36:46 +0200
Subject: [PATCH] Add APIs for IO card rendering (#2739)

* Refactor: Add index to shapes package

* Add shape draw callback API to setupImageCloze

* Expose IO drawing API, switch away from image cloze naming

We currently use "image occlusion" in most places, but some references to "image cloze" still remain. For consistency's sake and to make it easier to quickly find IO-related code, this commit replaces all remaining references to "image cloze", only maintaining those required for backwards compatibility with existing note types.

* Add cloze ordinal to shapes

* Do not mutate original shapes during (de)normalization

Mutating shapes would be a recipe for trouble when combined with IO API use by external consumers.

(makeNormal(makeAbsolute(makeNormal())) is not idempotent,
and keeping track of the original state would introduce
additional complexity with no discernible performance benefit
or otherwise.)

* Tweak IO API, allowing modifications to ShapeProperties

* Tweak drawShape parameters

* Switch method order

For consistency with previous implementation

* Run Rust formatters

* Simplify position (de)normalization

---------

Co-authored-by: Glutanimate <glutanimate@users.noreply.github.com>
---
 proto/anki/image_occlusion.proto        |   4 +-
 rslib/src/image_occlusion/imagedata.rs  |   9 +-
 rslib/src/image_occlusion/notetype.rs   |   2 +-
 ts/image-occlusion/review.ts            | 139 ++++++++++++++++--------
 ts/image-occlusion/shapes/base.ts       |  40 +++++--
 ts/image-occlusion/shapes/ellipse.ts    |  26 +++--
 ts/image-occlusion/shapes/from-cloze.ts |   1 +
 ts/image-occlusion/shapes/index.ts      |   9 ++
 ts/image-occlusion/shapes/polygon.ts    |  34 ++++--
 ts/image-occlusion/shapes/rectangle.ts  |  26 +++--
 ts/image-occlusion/shapes/text.ts       |  28 +++--
 ts/image-occlusion/shapes/to-cloze.ts   |   3 +-
 ts/reviewer/index.ts                    |   5 +-
 ts/reviewer/reviewer_extras.ts          |   7 +-
 14 files changed, 228 insertions(+), 105 deletions(-)
 create mode 100644 ts/image-occlusion/shapes/index.ts

diff --git a/proto/anki/image_occlusion.proto b/proto/anki/image_occlusion.proto
index 82f7d38ce..79ea2fe9f 100644
--- a/proto/anki/image_occlusion.proto
+++ b/proto/anki/image_occlusion.proto
@@ -64,7 +64,7 @@ message GetImageOcclusionNoteResponse {
     repeated ImageOcclusionProperty properties = 2;
   }
 
-  message ImageClozeNote {
+  message ImageOcclusionNote {
     bytes image_data = 1;
     repeated ImageOcclusion occlusions = 2;
     string header = 3;
@@ -73,7 +73,7 @@ message GetImageOcclusionNoteResponse {
   }
 
   oneof value {
-    ImageClozeNote note = 1;
+    ImageOcclusionNote note = 1;
     string error = 2;
   }
 }
diff --git a/rslib/src/image_occlusion/imagedata.rs b/rslib/src/image_occlusion/imagedata.rs
index 3ec3a49ee..17613344c 100644
--- a/rslib/src/image_occlusion/imagedata.rs
+++ b/rslib/src/image_occlusion/imagedata.rs
@@ -6,7 +6,7 @@ use std::path::PathBuf;
 
 use anki_io::metadata;
 use anki_io::read_file;
-use anki_proto::image_occlusion::get_image_occlusion_note_response::ImageClozeNote;
+use anki_proto::image_occlusion::get_image_occlusion_note_response::ImageOcclusionNote;
 use anki_proto::image_occlusion::get_image_occlusion_note_response::Value;
 use anki_proto::image_occlusion::AddImageOcclusionNoteRequest;
 use anki_proto::image_occlusion::GetImageForOcclusionResponse;
@@ -82,9 +82,12 @@ impl Collection {
         Ok(GetImageOcclusionNoteResponse { value: Some(value) })
     }
 
-    pub fn get_image_occlusion_note_inner(&mut self, note_id: NoteId) -> Result<ImageClozeNote> {
+    pub fn get_image_occlusion_note_inner(
+        &mut self,
+        note_id: NoteId,
+    ) -> Result<ImageOcclusionNote> {
         let note = self.storage.get_note(note_id)?.or_not_found(note_id)?;
-        let mut cloze_note = ImageClozeNote::default();
+        let mut cloze_note = ImageOcclusionNote::default();
 
         let fields = note.fields();
 
diff --git a/rslib/src/image_occlusion/notetype.rs b/rslib/src/image_occlusion/notetype.rs
index 0f94c5e6d..488a29cfd 100644
--- a/rslib/src/image_occlusion/notetype.rs
+++ b/rslib/src/image_occlusion/notetype.rs
@@ -99,7 +99,7 @@ pub(crate) fn image_occlusion_notetype(tr: &I18n) -> Notetype {
 </div>
 <script>
 try {{
-    anki.setupImageCloze();
+    anki.imageOcclusion.setup();
 }} catch (exc) {{
     document.getElementById("err").innerHTML = `{err_loading}<br><br>${{exc}}`;
 }}
diff --git a/ts/image-occlusion/review.ts b/ts/image-occlusion/review.ts
index cc715ea88..73f647677 100644
--- a/ts/image-occlusion/review.ts
+++ b/ts/image-occlusion/review.ts
@@ -4,23 +4,50 @@
 import * as tr from "@tslib/ftl";
 
 import { optimumPixelSizeForCanvas } from "./canvas-scale";
-import type { Shape } from "./shapes/base";
-import { Ellipse } from "./shapes/ellipse";
-import { extractShapesFromRenderedClozes } from "./shapes/from-cloze";
-import { Polygon } from "./shapes/polygon";
-import { Rectangle } from "./shapes/rectangle";
-import { Text } from "./shapes/text";
+import { Shape } from "./shapes";
+import { Ellipse, extractShapesFromRenderedClozes, Polygon, Rectangle, Text } from "./shapes";
 import { TEXT_BACKGROUND_COLOR, TEXT_FONT_FAMILY, TEXT_PADDING } from "./tools/lib";
 import type { Size } from "./types";
 
-export function setupImageCloze(): void {
-    window.addEventListener("load", () => {
-        window.addEventListener("resize", setupImageCloze);
-    });
-    window.requestAnimationFrame(setupImageClozeInner);
+export type DrawShapesData = {
+    activeShapes: Shape[];
+    inactiveShapes: Shape[];
+    properties: ShapeProperties;
+};
+
+export type DrawShapesFilter = (
+    data: DrawShapesData,
+    context: CanvasRenderingContext2D,
+) => DrawShapesData | void;
+
+export type DrawShapesCallback = (
+    data: DrawShapesData,
+    context: CanvasRenderingContext2D,
+) => void;
+
+export const imageOcclusionAPI = {
+    setup: setupImageOcclusion,
+    drawShape,
+    Ellipse,
+    Polygon,
+    Rectangle,
+    Shape,
+    Text,
+};
+
+interface SetupImageOcclusionOptions {
+    onWillDrawShapes?: DrawShapesFilter;
+    onDidDrawShapes?: DrawShapesCallback;
 }
 
-function setupImageClozeInner(): void {
+function setupImageOcclusion(setupOptions?: SetupImageOcclusionOptions): void {
+    window.addEventListener("load", () => {
+        window.addEventListener("resize", () => setupImageOcclusion(setupOptions));
+    });
+    window.requestAnimationFrame(() => setupImageOcclusionInner(setupOptions));
+}
+
+function setupImageOcclusionInner(setupOptions?: SetupImageOcclusionOptions): void {
     const canvas = document.querySelector(
         "#image-occlusion-canvas",
     ) as HTMLCanvasElement | null;
@@ -28,7 +55,6 @@ function setupImageClozeInner(): void {
         return;
     }
 
-    const ctx: CanvasRenderingContext2D = canvas.getContext("2d")!;
     const container = document.getElementById(
         "image-occlusion-container",
     ) as HTMLDivElement;
@@ -56,47 +82,74 @@ function setupImageClozeInner(): void {
         button.addEventListener("click", toggleMasks);
     }
 
-    drawShapes(canvas, ctx);
+    drawShapes(canvas, setupOptions?.onWillDrawShapes, setupOptions?.onDidDrawShapes);
 }
 
 function drawShapes(
     canvas: HTMLCanvasElement,
-    ctx: CanvasRenderingContext2D,
+    onWillDrawShapes?: DrawShapesFilter,
+    onDidDrawShapes?: DrawShapesCallback,
 ): void {
-    const properties = getShapeProperties();
+    const context: CanvasRenderingContext2D = canvas.getContext("2d")!;
     const size = canvas;
-    for (const shape of extractShapesFromRenderedClozes(".cloze")) {
-        drawShape(ctx, size, shape, properties, true);
+
+    let activeShapes = extractShapesFromRenderedClozes(".cloze");
+    let inactiveShapes = extractShapesFromRenderedClozes(".cloze-inactive");
+    let properties = getShapeProperties();
+
+    const processed = onWillDrawShapes?.({ activeShapes, inactiveShapes, properties }, context);
+    if (processed) {
+        activeShapes = processed.activeShapes;
+        inactiveShapes = processed.inactiveShapes;
+        properties = processed.properties;
     }
-    for (const shape of extractShapesFromRenderedClozes(".cloze-inactive")) {
-        if (shape.occludeInactive) {
-            drawShape(ctx, size, shape, properties, false);
-        }
+
+    for (const shape of activeShapes) {
+        drawShape({
+            context,
+            size,
+            shape,
+            fill: properties.activeShapeColor,
+            stroke: properties.activeBorder.color,
+            strokeWidth: properties.activeBorder.width,
+        });
     }
+    for (const shape of inactiveShapes.filter((s) => s.occludeInactive)) {
+        drawShape({
+            context,
+            size,
+            shape,
+            fill: properties.inActiveShapeColor,
+            stroke: properties.inActiveBorder.color,
+            strokeWidth: properties.inActiveBorder.width,
+        });
+    }
+
+    onDidDrawShapes?.({ activeShapes, inactiveShapes, properties }, context);
 }
 
-function drawShape(
-    ctx: CanvasRenderingContext2D,
-    size: Size,
-    shape: Shape,
-    properties: ShapeProperties,
-    active: boolean,
-): void {
-    shape.makeAbsolute(size);
+interface DrawShapeParameters {
+    context: CanvasRenderingContext2D;
+    size: Size;
+    shape: Shape;
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+}
 
-    const { color, border } = active
-        ? {
-            color: properties.activeShapeColor,
-            border: properties.activeBorder,
-        }
-        : {
-            color: properties.inActiveShapeColor,
-            border: properties.inActiveBorder,
-        };
+function drawShape({
+    context: ctx,
+    size,
+    shape,
+    fill,
+    stroke,
+    strokeWidth,
+}: DrawShapeParameters): void {
+    shape = shape.toAbsolute(size);
 
-    ctx.fillStyle = color;
-    ctx.strokeStyle = border.color;
-    ctx.lineWidth = border.width;
+    ctx.fillStyle = fill;
+    ctx.strokeStyle = stroke;
+    ctx.lineWidth = strokeWidth;
     if (shape instanceof Rectangle) {
         ctx.fillRect(shape.left, shape.top, shape.width, shape.height);
         ctx.strokeRect(shape.left, shape.top, shape.width, shape.height);
@@ -175,7 +228,7 @@ function topLeftOfPoints(points: { x: number; y: number }[]): {
     return { x: left, y: top };
 }
 
-type ShapeProperties = {
+export type ShapeProperties = {
     activeShapeColor: string;
     inActiveShapeColor: string;
     activeBorder: { width: number; color: string };
diff --git a/ts/image-occlusion/shapes/base.ts b/ts/image-occlusion/shapes/base.ts
index a6ce8246e..e93aacb46 100644
--- a/ts/image-occlusion/shapes/base.ts
+++ b/ts/image-occlusion/shapes/base.ts
@@ -23,14 +23,18 @@ export class Shape {
      * question side.
      */
     occludeInactive = false;
+    /* Cloze ordinal */
+    ordinal = 0;
 
     constructor(
-        { left = 0, top = 0, fill = SHAPE_MASK_COLOR, occludeInactive = false }: ConstructorParams<Shape> = {},
+        { left = 0, top = 0, fill = SHAPE_MASK_COLOR, occludeInactive = false, ordinal = 0 }: ConstructorParams<Shape> =
+            {},
     ) {
         this.left = left;
         this.top = top;
         this.fill = fill;
         this.occludeInactive = occludeInactive;
+        this.ordinal = ordinal;
     }
 
     /** Format numbers and remove default values, for easier serialization to
@@ -46,18 +50,36 @@ export class Shape {
     }
 
     toFabric(size: Size): fabric.ForCloze {
-        this.makeAbsolute(size);
-        return new fabric.Object(this);
+        const absolute = this.toAbsolute(size);
+        return new fabric.Object(absolute);
     }
 
-    makeNormal(size: Size): void {
-        this.left = xToNormalized(size, this.left);
-        this.top = yToNormalized(size, this.top);
+    normalPosition(size: Size) {
+        return {
+            left: xToNormalized(size, this.left),
+            top: yToNormalized(size, this.top),
+        };
     }
 
-    makeAbsolute(size: Size): void {
-        this.left = xFromNormalized(size, this.left);
-        this.top = yFromNormalized(size, this.top);
+    toNormal(size: Size): Shape {
+        return new Shape({
+            ...this,
+            ...this.normalPosition(size),
+        });
+    }
+
+    absolutePosition(size: Size) {
+        return {
+            left: xFromNormalized(size, this.left),
+            top: yFromNormalized(size, this.top),
+        };
+    }
+
+    toAbsolute(size: Size): Shape {
+        return new Shape({
+            ...this,
+            ...this.absolutePosition(size),
+        });
     }
 }
 
diff --git a/ts/image-occlusion/shapes/ellipse.ts b/ts/image-occlusion/shapes/ellipse.ts
index c1fcbb722..bd2d81baf 100644
--- a/ts/image-occlusion/shapes/ellipse.ts
+++ b/ts/image-occlusion/shapes/ellipse.ts
@@ -28,20 +28,26 @@ export class Ellipse extends Shape {
     }
 
     toFabric(size: Size): fabric.Ellipse {
-        this.makeAbsolute(size);
-        return new fabric.Ellipse(this);
+        const absolute = this.toAbsolute(size);
+        return new fabric.Ellipse(absolute);
     }
 
-    makeNormal(size: Size): void {
-        super.makeNormal(size);
-        this.rx = xToNormalized(size, this.rx);
-        this.ry = yToNormalized(size, this.ry);
+    toNormal(size: Size): Ellipse {
+        return new Ellipse({
+            ...this,
+            ...super.normalPosition(size),
+            rx: xToNormalized(size, this.rx),
+            ry: yToNormalized(size, this.ry),
+        });
     }
 
-    makeAbsolute(size: Size): void {
-        super.makeAbsolute(size);
-        this.rx = xFromNormalized(size, this.rx);
-        this.ry = yFromNormalized(size, this.ry);
+    toAbsolute(size: Size): Ellipse {
+        return new Ellipse({
+            ...this,
+            ...super.absolutePosition(size),
+            rx: xFromNormalized(size, this.rx),
+            ry: yFromNormalized(size, this.ry),
+        });
     }
 }
 
diff --git a/ts/image-occlusion/shapes/from-cloze.ts b/ts/image-occlusion/shapes/from-cloze.ts
index f018dc771..3cd6413c7 100644
--- a/ts/image-occlusion/shapes/from-cloze.ts
+++ b/ts/image-occlusion/shapes/from-cloze.ts
@@ -51,6 +51,7 @@ function extractShapeFromRenderedCloze(cloze: HTMLDivElement): Shape | null {
     }
     const props = {
         occludeInactive: cloze.dataset.occludeinactive === "1",
+        ordinal: parseInt(cloze.dataset.ordinal!),
         left: cloze.dataset.left,
         top: cloze.dataset.top,
         width: cloze.dataset.width,
diff --git a/ts/image-occlusion/shapes/index.ts b/ts/image-occlusion/shapes/index.ts
new file mode 100644
index 000000000..c4673bfc7
--- /dev/null
+++ b/ts/image-occlusion/shapes/index.ts
@@ -0,0 +1,9 @@
+// Copyright: Ankitects Pty Ltd and contributors
+// License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html
+
+export { Shape } from "./base";
+export { Ellipse } from "./ellipse";
+export { extractShapesFromRenderedClozes } from "./from-cloze";
+export { Polygon } from "./polygon";
+export { Rectangle } from "./rectangle";
+export { Text } from "./text";
diff --git a/ts/image-occlusion/shapes/polygon.ts b/ts/image-occlusion/shapes/polygon.ts
index f07a886f1..d2d0adc44 100644
--- a/ts/image-occlusion/shapes/polygon.ts
+++ b/ts/image-occlusion/shapes/polygon.ts
@@ -25,23 +25,37 @@ export class Polygon extends Shape {
     }
 
     toFabric(size: Size): fabric.Polygon {
-        this.makeAbsolute(size);
-        return new fabric.Polygon(this.points, this);
+        const absolute = this.toAbsolute(size);
+        return new fabric.Polygon(absolute.points, absolute);
     }
 
-    makeNormal(size: Size): void {
-        super.makeNormal(size);
+    toNormal(size: Size): Polygon {
+        const points: Point[] = [];
         this.points.forEach((p) => {
-            p.x = xToNormalized(size, p.x);
-            p.y = yToNormalized(size, p.y);
+            points.push({
+                x: xToNormalized(size, p.x),
+                y: yToNormalized(size, p.y),
+            });
+        });
+        return new Polygon({
+            ...this,
+            ...super.normalPosition(size),
+            points,
         });
     }
 
-    makeAbsolute(size: Size): void {
-        super.makeAbsolute(size);
+    toAbsolute(size: Size): Polygon {
+        const points: Point[] = [];
         this.points.forEach((p) => {
-            p.x = xFromNormalized(size, p.x);
-            p.y = yFromNormalized(size, p.y);
+            points.push({
+                x: xFromNormalized(size, p.x),
+                y: yFromNormalized(size, p.y),
+            });
+        });
+        return new Polygon({
+            ...this,
+            ...super.absolutePosition(size),
+            points,
         });
     }
 }
diff --git a/ts/image-occlusion/shapes/rectangle.ts b/ts/image-occlusion/shapes/rectangle.ts
index 2b79da162..df061fe45 100644
--- a/ts/image-occlusion/shapes/rectangle.ts
+++ b/ts/image-occlusion/shapes/rectangle.ts
@@ -28,20 +28,26 @@ export class Rectangle extends Shape {
     }
 
     toFabric(size: Size): fabric.Rect {
-        this.makeAbsolute(size);
-        return new fabric.Rect(this);
+        const absolute = this.toAbsolute(size);
+        return new fabric.Rect(absolute);
     }
 
-    makeNormal(size: Size): void {
-        super.makeNormal(size);
-        this.width = xToNormalized(size, this.width);
-        this.height = yToNormalized(size, this.height);
+    toNormal(size: Size): Rectangle {
+        return new Rectangle({
+            ...this,
+            ...super.normalPosition(size),
+            width: xToNormalized(size, this.width),
+            height: yToNormalized(size, this.height),
+        });
     }
 
-    makeAbsolute(size: Size): void {
-        super.makeAbsolute(size);
-        this.width = xFromNormalized(size, this.width);
-        this.height = yFromNormalized(size, this.height);
+    toAbsolute(size: Size): Rectangle {
+        return new Rectangle({
+            ...this,
+            ...super.absolutePosition(size),
+            width: xFromNormalized(size, this.width),
+            height: yFromNormalized(size, this.height),
+        });
     }
 }
 
diff --git a/ts/image-occlusion/shapes/text.ts b/ts/image-occlusion/shapes/text.ts
index c61dd6a10..743aeff62 100644
--- a/ts/image-occlusion/shapes/text.ts
+++ b/ts/image-occlusion/shapes/text.ts
@@ -37,25 +37,31 @@ export class Text extends Shape {
     }
 
     toFabric(size: Size): fabric.IText {
-        this.makeAbsolute(size);
-        return new fabric.IText(this.text, {
-            ...this,
+        const absolute = this.toAbsolute(size);
+        return new fabric.IText(absolute.text, {
+            ...absolute,
             fontFamily: TEXT_FONT_FAMILY,
             backgroundColor: TEXT_BACKGROUND_COLOR,
             padding: TEXT_PADDING,
         });
     }
 
-    makeNormal(size: Size): void {
-        super.makeNormal(size);
-        this.scaleX = xToNormalized(size, this.scaleX);
-        this.scaleY = yToNormalized(size, this.scaleY);
+    toNormal(size: Size): Text {
+        return new Text({
+            ...this,
+            ...super.normalPosition(size),
+            scaleX: xToNormalized(size, this.scaleX),
+            scaleY: yToNormalized(size, this.scaleY),
+        });
     }
 
-    makeAbsolute(size: Size): void {
-        super.makeAbsolute(size);
-        this.scaleX = xFromNormalized(size, this.scaleX);
-        this.scaleY = yFromNormalized(size, this.scaleY);
+    toAbsolute(size: Size): Text {
+        return new Text({
+            ...this,
+            ...super.absolutePosition(size),
+            scaleX: xFromNormalized(size, this.scaleX),
+            scaleY: yFromNormalized(size, this.scaleY),
+        });
     }
 }
 
diff --git a/ts/image-occlusion/shapes/to-cloze.ts b/ts/image-occlusion/shapes/to-cloze.ts
index 6ace61ea5..d584ea590 100644
--- a/ts/image-occlusion/shapes/to-cloze.ts
+++ b/ts/image-occlusion/shapes/to-cloze.ts
@@ -108,7 +108,7 @@ function fabricObjectToBaseShapeOrShapes(
         shape.top = newPosition.y;
     }
 
-    shape.makeNormal(size);
+    shape = shape.toNormal(size);
     return shape;
 }
 
@@ -151,6 +151,7 @@ function shapeOrShapesToCloze(
     } else {
         ordinal = index + 1;
     }
+    shapeOrShapes.ordinal = ordinal;
     text = `{{c${ordinal}::image-occlusion:${type}${text}}}<br>`;
 
     return text;
diff --git a/ts/reviewer/index.ts b/ts/reviewer/index.ts
index 7825f8472..13b2dacf8 100644
--- a/ts/reviewer/index.ts
+++ b/ts/reviewer/index.ts
@@ -9,12 +9,13 @@ import "css-browser-selector/css_browser_selector.min";
 
 export { default as $, default as jQuery } from "jquery/dist/jquery";
 
-import { setupImageCloze } from "../image-occlusion/review";
+import { imageOcclusionAPI } from "../image-occlusion/review";
 import { mutateNextCardStates } from "./answering";
 
 globalThis.anki = globalThis.anki || {};
 globalThis.anki.mutateNextCardStates = mutateNextCardStates;
-globalThis.anki.setupImageCloze = setupImageCloze;
+globalThis.anki.imageOcclusion = imageOcclusionAPI;
+globalThis.anki.setupImageCloze = imageOcclusionAPI.setup; // deprecated
 
 import { bridgeCommand } from "@tslib/bridgecommand";
 import { registerPackage } from "@tslib/runtime-require";
diff --git a/ts/reviewer/reviewer_extras.ts b/ts/reviewer/reviewer_extras.ts
index 9d15a6fb7..2898aedf6 100644
--- a/ts/reviewer/reviewer_extras.ts
+++ b/ts/reviewer/reviewer_extras.ts
@@ -5,13 +5,14 @@
 @typescript-eslint/no-explicit-any: "off",
  */
 
-// A standalone bundle that adds mutateNextCardStates and setupImageCloze
+// A standalone bundle that adds mutateNextCardStates and the image occlusion API
 // to the anki namespace. When all clients are using reviewer.js directly, we
 // can get rid of this.
 
-import { setupImageCloze } from "../image-occlusion/review";
+import { imageOcclusionAPI } from "../image-occlusion/review";
 import { mutateNextCardStates } from "./answering";
 
 globalThis.anki = globalThis.anki || {};
 globalThis.anki.mutateNextCardStates = mutateNextCardStates;
-globalThis.anki.setupImageCloze = setupImageCloze;
+globalThis.anki.imageOcclusion = imageOcclusionAPI;
+globalThis.anki.setupImageCloze = imageOcclusionAPI.setup; // deprecated