Add small canvas sample

[nojaf]

Trying out the sample from https://www.youtube.com/watch?v=2osWIorQDMU
It was immediately apparent that CanvasAPI is currently incomplete.
This will unfortunately be the case for a lot of cases.

[nojaf]

fillStyle is a property that can be multiple things:

"properties": {
          "property": {
            "fillStyle": {
              "name": "fillStyle",
              "type": [
                {
                  "type": "DOMString",
                  "nullable": false
                },
                {
                  "type": "CanvasGradient",
                  "nullable": false
                },
                {
                  "type": "CanvasPattern",
                  "nullable": false
                }
              ],
              "nullable": false,
              "static": false,
              "stringifier": false,
              "readonly": false,
              "secureContext": false,
              "mdnUrl": "https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/fillStyle"
            }
          },

This is a gap in the current approach:

• It is impossible to model this as a unboxed variant
• The property can only be defined once, so we can't have multiple versions of that.

Workaround I see here is get and set functions.

type canvasRenderingContext2D

type canvasGradient

type canvasPattern

@get external fillStyle : canvasRenderingContext2D => string = "fillStyle"
@get external fillStyleAsCanvasGradient : canvasRenderingContext2D => canvasGradient = "fillStyle"

let c : canvasRenderingContext2D = %todo
let fs = c->fillStyle
let fs2 = c->fillStyleAsCanvasGradient

@set external setFillStyle : (canvasRenderingContext2D,string) => unit = "fillStyle"

setFillStyle(c, "red")

While the setter is fine, the getter could still be unsafe if the wrong assumption is made.

[nojaf]

Some other train of thought to model this:

type canvasGradient

type canvasPattern

type fillStyle

external instanceof: 't => string = "instanceof"
external unsafeCast: 't => 'u = "%identity"

let castWhen = condition => t => condition(t) ? Some(unsafeCast(t)) : None

module FillStyle = {
  external fromString: string => fillStyle = "%identity"
  external fromCanvasGradient: canvasGradient => fillStyle = "%identity"
  external fromCanvasPattern: canvasGradient => fillStyle = "%identity"

  let asString: fillStyle => option<string> = castWhen(t =>
    Type.typeof(t) == #string
  )

  let asCanvasGradient: fillStyle => option<canvasGradient> = castWhen(t =>
    instanceof(t) == "CanvasGradient"
  )

  let asCanvasPattern: fillStyle => option<canvasPattern> = castWhen(t =>
    instanceof(t) === "CanvasPattern"
  )
}

type canvasRenderingContext2D = {fillStyle: fillStyle}

let c: canvasRenderingContext2D = %todo

let fs = c.fillStyle

switch FillStyle.asString(c.fillStyle) {
| None => Console.log("no string")
| Some(v) => Console.log(`value is ${v}`)
}

[zth]

Here's a pretty common way to model this:

If it's just about setting a value, it's easy to model with an abstract type and makers, just like you did above:

type canvasGradient
type canvasPattern

module FillStyle = {
  type t

  external fromString: string => t = "%identity"
  external fromCanvasGradient: canvasGradient => t = "%identity"
  external fromCanvasPattern: canvasGradient => t = "%identity"
}

let x: xx = {
  fillStyle: FillStyle.fromString("red"),
}

The tooling is also built to handle this scenario, so if you do completions at fillStyle: <com> you'll get this, which is quite helpful:

Now, if you also want to decode this into something usable, you indeed need to drop into unsafe land. I like to do it just with %raw:

type canvasGradient
type canvasPattern

module FillStyle = {
  type t
  
  external fromString: string => t = "%identity"
  external fromCanvasGradient: canvasGradient => t = "%identity"
  external fromCanvasPattern: canvasGradient => t = "%identity"
  
  @tag("type")
  type decoded = String(string) | CanvasGradient(canvasGradient) | CanvasPattern(canvasPattern)
  
  let decode: t => decoded = %raw(`function decodeFillStyle(t) {
    if (t instanceof CanvasGradient) {
        return {type: "CanvasGradient", _0: t};
    } else if (t instanceof CanvasPattern) {
        return {type: "CanvasPattern", _0: t};
    } else {
        return {type: "String", _0: t};
    }
  }`)
}

type xx = {fillStyle: FillStyle.t}

let x: xx = {
  fillStyle: FillStyle.fromString("red"),
}

switch x.fillStyle->FillStyle.decode {
| String(s) => Console.log(s)
| CanvasGradient(g) => Console.log(g)
| CanvasPattern(p) => Console.log(p)
}

This obviously isn't great, but still pretty OK I'd say given that it's contained in there. Tooling helps a bit here as well, although we could make this more accessible:

[nojaf]

Thanks, this is very insightful!
I'm not sure what users will do with fillStyle.
Maybe read, maybe write. This is a more common problem with this project, it is hard to say upfront what user will do precisely.
I'd say both should be possible.

[nojaf]

@zth would you mind reviewing this?

Please focus on the new test, approach to fillStyle and getContext modelling.
Does this seems reasonable?

[nojaf]

@zth I'm gonna merge this, sorry for my lack of patience.
I've add a great deal of lore in the contributing section of the docs.
Feel free to point out any remarks you might have, we can always revisit things later.