New Styling Proposal

[fenjalien]

The current system can be a bit confusing and restrictive, so @johannes-wolf and I have had some thoughts about taking inspiration from CSS styling. I want to layout my ideas for it here. Ideally we would want to use Typst's selectors. However you cannot "select" custom functions, but this will hopefully happen once custom types have been implemented.

The what

The idea is to have a simplified version of CSS with the bare minimum to make it work (no complicated bits) and modified to fit in with Typst. Ideally the default behaviour should be whatever the CSS default is unless it doesn't make sense to apply it.

• Each element will get some metadata
  • type: The type of element e.g. line
  • name: The name of the element
  • class: Additional string(s) that identify or group the element. Can be user-defined or added by cetz. e.g. "red lines", "fillable"
• Users will then pass styling in some format (discussed below) that contains a selector and its associated styles.
  • into set-style to be specific (could be renamed)
  • inline styles would remain the same as they act as overrides
• Elements will then be styled based on a comparison of the selector and its metadata.
  • https://developer.mozilla.org/en-US/docs/Web/CSS/Cascade
  • https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity

Styling Input Format

• Has two parts the selector and the style
  • selector contains information about which elements should be selected
  • style contains information about how to style the element

set-style(selector: (type: "line"), style: (stroke: blue))

• This could be quite verbose so some shorthand might be possible
  • allow positional parameters instead of named, first would be the selector the second is style.

Selector fields

• type: A string that will match on the type of element

  • "line"

• name: A string that will match on elements that have this user-defined name

  • Equivalent to HTML's id

• class: A string or a list of strings that will match on elements that have this class

  • "fillable"

• attribute: Elements with the specified attributes

  • Not sure about this one as all attributes could just be styles?
  • Best use might be elements with a certain coordinate or coordinate in this quadrant

• child/parent: A selector that will match on elements with a child or parent that matches the given selector.

  • Could be used for marks on a line
  • Equivalent to CSS's child combinator >

• This again could be quite verbose

  • Symbols could be used but I don't want them to become standard as it introduces additional syntax for new users to learn.
  • Could have one of the fields as the "default" if no fields are given
    • would nominate type as its closest to the current method.

The how

At the moment I see two possibilities:

1. We write the cascading and specificity algorithms ourselves
   • There is lots of documentation on MDN about it (see the links above)
   • A lot of effort that could be buggy/difficult to support
   • Would allow "easy" function selectors/styles
2. We find an external library that can do it for us and implement it as a plugin
   • Not sure if this would work as plugins are pretty new
   • Would require working in a different language (ideally rust)
   • Could allow external .css files to be imported
   • means we don't have to deal with "business" logic, we just have to handle the parsing sides
   • Might have already found a possible candidate: https://lib.rs/crates/selectors
   • wouldn't allow functions/callbacks (at least on selectors, might be possible on styling)

To conclude

This would be a BIG undertaking but honestly the current implementation is just to naïve. One concern I do have is by having something this big, what do we do when/if set rules come to custom functions? or custom elements?

Feel free to add suggestions or ask questions!

[johannes-wolf]

Answer to questions from the PR:

does this mean set-style can only change one style at a time? Before I could set styles for multiple style roots.

Yes, with this implementation this is no longer possible.
What do you think of something like:

set-style(("<selector>", (a: 1, b: 2, ...)), "<selector-2>", (a: 2, b: 3, ..))

For setting multiple roots at once?

Why use the > syntax? Is this inspired by CSS selectors? Why not use dot-notation for nested styles?

Yes, this is CSS inspired, and should be changed to .. I had implemented class and id matching but removed it again.

[fenjalien]

For set-style I would prefer the use of named parameters over positional. It would make it more verbose for the user. What would you think of requiring a selector key in the style dict? Then if the user wants to set multiple styles with one set-style we could allow a positional sink of dictionaries.

set-style(selector: "...", fill: ...)
// and
set-style((selector: "1", ...), (selector: "2", ...))

It would also make handling them in code a bit nicer.

Do you plan to only implement a type selector first? I would be okay with this as a string type could become shorthand for the type key in a selector. How easy would it be with what you currently have to implement additional selectors? (I'm particularly interested in class and name).

I don't like allowing only special syntax in selectors. If multiple types are to be selected, allow an array of strings. If parent/children are to be selected provide an explicit key for them. Only then I would be happy with a shorthand.

I'm also not sure about style-element as a function, it feels... janky. Could it be combined with group?

[jneug]

In general, I would favor not adding too much complexity. Adding a CSS compatible system or even different selectors with custom syntax seems to add a lot of complexity for users and maintainers for not much gain. The suggested system with nested styles seems to be enough for most of the currently common use-cases.

Some of the suggested additions seem valid. Adding a type key to elements might be useful for filtering the element array for certain elements. I can imagine use-cases that modify only rectangles for some effect. (In finite for example, I implemented layouts as special groups that only modify the location of states and no other elements.)

I can see the ideas above distilled into a much more simple class system. Elements have a number of classes attached to them. The styling selectors can use nested classes with a dot notation, like bezier.mark or transition.label.

The element type and name are automatically added as classes to each element. For example, group1.line would set styles for every element of type line in the group named group1.

Setting multiple styles could be done by giving (selector: styles) pairs to set-style:

set-style(
  "stroke": 2pt + red,
  "group1.stroke": 1pt + green,
  "bezier.mark" : ...
)

[johannes-wolf]

I am also in favor of keeping it simple. The current master has a fix and slight modification of the current system, with the same API. If that works and resolves the bugs/strange inheritance behavior, I suggest keeping it the way it is. I first thought that the current system cannot be fixed and therefore wanted to change it to a class-based design.