Unified Standard Elements Enhancement Package

[pklaschka]

Based on my recent showcase on the Typst Discord Server of enhancing the standard #image element (see the example below), I'd like to open a discussion on whether there should be a unified "standard element enhancements" package maintained under this GitHub organization and overall governed by the community. While I'm not sure yet if that's a good idea, I have come to believe that it would be a terrible idea to have these kinds of enhancements be individual packages.

Proposal

Considering that:

1. Typst allows for standard elements to be "overridden" by custom definitions, allowing for (non-breaking) enhancements (see example below);
2. Distributing these kinds of enhancements as individual packages would create a messy ecosystem with different documents importing different sets of enhancements, adding unnecessary complexity to writing Typst documents;
3. Enhancing the features of core elements fundamentally differs from use-cases of other domain-specific features;
4. This GitHub organization provides the best space to create a recognized, community-driven "standard" set of Typst enhancements.

I propose:

1. To create a package under typst-community that combines a set of enhancements for Typst and can be imported from a single package.
2. The package shall contain enhancements of core Typst elements (such as #image(), #figure(), etc.) which can be imported all at once or individually from the package.
3. Any enhancements shall be non-breaking, meaning any previously possible usage of the elements must have the exact same result as without the enhancement. Elements can only be amended with additional (optional) arguments, which can then change their behavior.
4. Enhancements included in the package shall not be opinionated in terms of the domain of their usage. For example, if the use-case of an enhancement is only common in a specific field of research, and a different behavior of the enhancement would be common and expected by users of other fields, it should not be included in the package.

Example

The following non-breaking enhancement allows #image elements to quickly be converted to a figure by providing an (optional) second argument containing a caption.

Library / Package Code

#let original-image = image

#let image = (..args) => {
  let positional-args = args.pos()

  let is-figure = positional-args.len() > 1

  if is-figure {
    let src = positional-args.at(0)
    let caption = positional-args.at(1)
    
    figure(original-image(src, ..args.named()), caption: caption)
  } else {
    original-image(..args)
  }
}

Usage

#import "@preview/community-element-enhancements": *
// or: #import "@preview/community-element-enhancements": image, original-image

#image("test.png", width: 30%) // images still work "normally"
#image("test.png", width: 30%)[
  This becomes a figure with this text as caption
]<fig:abc> // labels also work here

See @fig:abc.

[jamesrswift]

If I understand correctly, a package for Syntax sugars?

[pklaschka]

Yes (-ish?). I'm not 100% sure I would call it syntax sugar, since it doesn't add any new syntax (which would also be possible with RegEx based show rules, but wouldn't be in the scope of the package), so calling it that might be a bit misleading. I guess it might be considered "semantic sugar / enhancements", although I've never seen that term used before 🤔.

Apart from the semantics of what to call it, though: yes. A set of "commonly useful" shorthands that shouldn't be added to the Typst Core (as having core Typst converting an #image to a #figure automatically would be extremely confusing).

[EpicEricEE]

I'd like to mention that overriding element functions has the big disadvantage that set/show-rules can no longer be applied properly, as the new functions then are not element functions anymore.

[pklaschka]

True – good point. I hadn't considered that this might become a problem since with the #image example, this wouldn't be an issue (as I don't think using #set for a figure caption gets used (at least in most cases).

#show rules would still affect the original element, of course. While this is something that the package documentation needs to make clear, I consider that to be a positive thing, though, since otherwise, compatibility of other packages would depend on that (similar to how in the web world, a lot of the JS ecosystem depended on jQuery for the longest time), which I don't think should happen here.

For named arguments (where it would be common to have set rules, after all), it might be a good idea to prefix them (e.g., c-[...] for "community"), which would allow for the documentation to mention that either c--prefixed attributes can't be set using #set rules or alternatively have to be set through some other mechanism provided by the package (if there was a requirement to allow setting defaults).

So overall (as I said: I'm still unsure myself about this idea), I think this is definitely something that needs to be considered, but it probably wouldn't be a showstopper (as there are likely solutions that make it easy to differentiate these features, and thus, explain them to users).

[pklaschka]

On another note, I think this makes it even more important for such packages, if they should even exist at all, to live in a unified package. That at least allows for conventions like the ones mentioned above to differentiate them.

[emilyyyylime]

The real problem is that currently, simply having the image function in scope prevents you from writing set image(..) (at least I think)

[pklaschka]

The real problem is that currently, simply having the image function in scope prevents you from writing set image(..) (at least I think)

Ah, ok – makes sense. I just checked and verified that this is indeed the case. While there are ways to work around that, this does indeed have a considerable impact on the feasibility of a great developer experience in such a package.

[sitandr]

Sorry for the long text, TLDR: idea is good, but that shouldn't be an std enhancement package, but probably a one for composing std functions.

Considering the discussion above about the applicability of show rules if this function is in scope, I would like to suggest a different solution.

What you are doing there is not "enhancing" the standard library function. There are cases that would make it harder to work with image (eg. show rules or autocomplete), and there are many cases where this change would be irrelevant: using images for logos, inline, special math symbols, backgrounds and so on.

What you are doing there is combining (composing) standard library functions into a new one, in your case: figure + image (with some clever argument management). Indeed, this is a very useful combination.

It could be even upgraded easily by including figure other named arguments. Luckily, they don't even intersect with image ones, so could be easily added (and I think it could be a useful addition).

---

So what I want to say is that we shouldn't enhance the standard library functions. They are very good on their own, each one for a very wide usage range. If possible, they should be upgraded on compiler level (if the change makes sense).

But the idea of having a package that combines these functions may be pretty good. That way we could have fig-image function (or maybe just fimage) that takes selected arguments. However, I can't think of others really common compositions.

An alternative solution: you can write a package with a single function, a function that allows to easily combine functions into one with needed arguments. That way it could be like:

// syntax is arguable

#fimage = compose(figure, "caption", image)
#fimage("path.png", "Caption", width: 70%)

// Let's use the same idea for coloring links

#clink = compose(text, "fill", link)
#clink("url.com", "Link text", green)
#clink("bad.com", "Link text", red)

In case of links this function isn't really needed, but I'm sure there are lots of examples where this "argument management" is important.

In the latter case this package could also include tools for other arguments management, like converting positional <-> named, arguments preprocessing, like mapping or changing the default (like set, but creating new function without any context management) and so on.