Tree style builder

[nicoburns]

• Builds on top of https://github.com/linebender/parley/pull/84 which should be merged first to preserve history

Changes made

• Entire unresolved style struct

  • Adds an "unresolved style struct" (TextStyle) to style/mod.rs
  • The new TreeBuilder allows you to directly pass an entire style struct (rather than just "changed styles" relative to a previous node in the tree) as this is easier for integrating with Stylo which already resolves inherited styles. So I have added an "unresolved" version of the style struct to allow this API to still plug into the other parts of Parley's style resolution functionality.
  • Adds a correspondingresolve_entire_style_set method to LayoutContext to convert TextStyle into ResolvedStyle.

• Moved code

  • Moves the RangedBuilder from context.rs to a new builder.rs module (as there are now two builders, justifying a separate module).
  • Extract most of RangedBuilder::build_into into a standalone build_into_layout function (builder.rs) that can be shared between the ranged and tree builders.
  • Moves the RangedStyle and RangedProperty types from resolve/range.rs to resolve/mod.rs. These types are shared between the RangedBuilder and the TreeBuilder.

• Tree builder

  • Adds a TreeBuilder (also to builder.rs). This mostly delegates to TreeStyleBuilder
  • Add a TreeStyleBuilder (resolve/tree.rs). This is the vast majority of the new code
  • The TreeStyleBuilder implements HTML-style whitespace collapsing (opt-in). This probably ought to become a style rather than being a flag on the style builder.
  • Updated swash example to optionally use the tree builder (depending on command line opt)

[nicoburns]

This one is nearly ready, but needs a bit of cleanup in the tree builder code.

[nicoburns]

@dfrg @xorgy Pinging you on this one as it's been a couple of months, I can see that other work on parley is starting to happen, and I am keen to get this merged before it starts to generate conflicts. I'm also keen to do some api documentation / re-export work on Parley and then get a 0.2.0 crates.io release out, which I consider this to be blocking. I do understand that you're busy and that this may not be top priority though.

If it helps:

This PR is actually much smaller and simpler than #84. I have also updated the PR description with a high-level description of the changes which may help with reviewing. I could also split the changes out into separate commits if that would help?

If I were to self-review I suspect I might point out:

• That the whitespace collapsing is a bit awkward:
  • It could probably be made a style rather than a flag on the TreeStyleBuilder (I could attempt that change if that's considered important)
  • It doesn't currently integrate well with editing functionality (it would be nice to support this properly, but perhaps for now we could simply document this - in the usual case you wouldn't want to mix these two features anyway)
• There is a bunch of commented out debug code (this is in line with other parts of parley atm and is quite helpful for debugging, but could be removed (or converted to tracing calls?) if it's considered a problem).

[dfrg]

Thanks for the ping.

After some thought, and given that you’ve been actively using this code in Blitz, I’m leaning toward landing as is with the caveat that much of this is likely to be superseded with work I’ve been doing on refactoring the text analysis code. The downside is more churn in the future on your end but the upside is support for span margins/borders/padding and a new pull style API for styles so you have more control. Hopefully that’s compelling.

With that in mind, I’d recommend not investing a lot of effort into improving documentation as things are likely to change soon.

[nicoburns]

@dfrg

I’m leaning toward landing as is with the caveat that much of this is likely to be superseded with work I’ve been doing on refactoring the text analysis code.

That would be great!

The downside is more churn in the future on your end but the upside is support for span margins/borders/padding and a new pull style API for styles so you have more control.

I am excited to see what you come up with, and definitely keen for changes that lead to a more complete implementation of the web model (and I'm guessing structural improvements to the code too). API churn isn't really a big deal for us: I'm familiar enough with the code at this point that I'm confident in being able to adapt to any changes. Regression in terms of feature set would be more problematic (if there was no longer a way to do something that was previously possible and that we are relying on) .

With that in mind, I’d recommend not investing a lot of effort into improving documentation as things are likely to change soon.

The doc changes I have in mind are pretty basic:

• Basic one-line description for key types
• Re-exporting a bunch of (most) types from the top-level of the crate, with #[doc(inline)] for important types
• A couple of paragraphs of explanation and a usage example (a pared down version of one of the examples) in the lib.rs module documentation.

I feel like a couple of hours spent on those kind of changes would put us in pretty good shape for a 0.2 release, and would bring us much more in line with cosmic-text in terms of first impressions and ease of getting started.

---

Beyond that, there are also a few features that I might be interested in working on soon:

• A style property to control emergency line-breaking behaviour (wrap vs overflow)
• Vertical alignment (and a corresponding style property) + user-specified baselines for inline boxes
• Floats

My feeling is that the first two (and perhaps even floats) probably wouldn't clash too much with your changes as they deal primarily with the layout code? But if you think it would be better to hold off then I will (I don't suppose you have any kind of estimated timeline for these changes landing / being published?)

[nicoburns]

I've rebased on latest main:

• Fixed conflicts
• Fixed it to work with the new vello_editor example
• Updated it to pass the latest clippy lints