feat: add ability to have arrows of different colors on a board

[loicraux]

Summary

Add ability to have arrows of different colors on a board.

Note

This pull request was not generated by an AI.

Description

The added new feature is the ability to draw arrows of different colors on a board. The user is introduced this new feature by being allowed to pass triplets instead of pairs as elements of the array given for the arrows option. The third (and optional) element of the triplet would be the color of the arrow.

The other ways to pass a value to the arrows option as an array of strings (for example, ("e2 e4", "e7 e5") or, more compactly, ("e2e4", "e7e5")) remain unchanged.

For example, one is now able to pass to the arrows option such an array : (("e2", "e4", rgb("#a1d3e7")), ("e7", "e5", teal),("d2", "d4"))... If no third color element is passed then the default color specified by arrow-fill is used.

Implementation

I updated in src/lib.typ the arrow parsing logic to support triplets in the arrows array: (start, end, color).

• If a triplet is provided, the third element is used as the color for that specific arrow.
• If a pair (start, end) or a string definition is provided, it falls back to the default arrow-fill color.

Tests

I have added a new test in src/api.typ to test this new feature :

#bnp.board(
  bnp.starting-position,
  arrow-fill: orange,
  arrows: (
    ("e2", "e4", purple),
    ("e7", "e5", green),
    ("d2", "d4"), // Default arrow-fill color
    "d7 d5", // Default arrow-fill color
    "g1f3", // Default arrow-fill color
  ),
)

Also no other already test did break during build with python3 ./build.py. This change is backward compatible.

Documentation

I have updated src/README.md to document this new feature

Related issue

Closes #17

[MDLC01]

Thanks for the pull request! Ideally, all arrow-* parameters should be able to be specified individually for each arrow.

In terms of API, I was thinking the best way would be through an arrow function (maybe a more specific name could be used to prevent conflict with sym.arrow and other packages) with the following signature:

arrow(
  // Positional.
  start: square,
  end: square,
  // Named (default is always `auto`).
  fill: auto | color | gradient | tiling,
  thickness: auto | length,
  base-offset: auto | length,
)

where square is the usual way to describe a square with a string (e.g., "c4"). Ideally, end should also be optional, in which case start would be like "d8c8" or "d8 c8".

Then, the arrows argument on board would accept a list of arrows, where an arrow is:

• either a string describing the arrow (like right now),
• or a pair of squares (like allowed currently as well),
• or the result of a call to arrow.

In the future, this arrow function should clearly be a custom element, and then the default parameters would be specified using set rules. But for now, this is the best we can do.

[loicraux]

Ok, I get your idea @MDLC01 , I agree it's better in terms of API. I'll try to find a moment next week to implement the same...