[Feature] Create default Styler for attributed string rendering
#177
Conversation
|
@iwasrobbed I'm not familiar with slather but it appears that you can't generate and merge multiple coverage reports. I believe it is possible with Codecov. What do you want to do here? |
|
Hey @johnxnguyen 👋 I'll take a swing at the code coverage merging. This looks good to merge otherwise! 🙇Thanks for the monumental amount of work and thought that went into this. It's a well thought out implementation and will act as a great foundation for people to continue building upon |
|
@iwasrobbed thanks! Sorry it took so long, lately I could only work on it in the mornings before work. I'm just glad it's done and people can start using it. |
Codecov Report
@@ Coverage Diff @@
## master #177 +/- ##
=========================================
Coverage ? 70.23%
=========================================
Files ? 53
Lines ? 1038
Branches ? 0
=========================================
Hits ? 729
Misses ? 309
Partials ? 0
Continue to review full report at Codecov.
|
|
Looks like that last commit finally did the trick (~70% coverage) 😅 CI test reporting is always a maze to get right. Feel free to merge whenever you're ready and thank you again! |
ghost
mentioned this pull request
|
Could you guys document this a little bit more please? There's some convenient API's here, but I have to dig right into the interface and the PRs to try to piece them together. Actually if you're ok with it I can make the PR on the readme? |
Stylerfor attributed string rendering #138What’s in this PR?
It’s finally here! This PR contains a base implementation of the
Stylerprotocol introduce in #132. With this default implementation, it will quick and easy to render attributed strings via the AST. My hope is that the implementation is flexible and broad enough to cover the majority of styling needs.Overview
I did my best to ensure that all block elements preserved the styling of inline elements, which themselves also preserve other inline elements.
List formatting was particularly tricky, but I managed to support right aligned item markers up to a specified width as well as indentation for nested lists.
As a bonus, code blocks are rendered in colored background container, just like in Github (more on that below).
Configurability
The
Stylersupports three main axes of configurable attributes: fonts, text color and paragraph styling. These different types of attributes are grouped together into collections:FontCollection,ColorCollection,ParagraphStyleCollection. This allows the user to easily specify related attributes in a single place. For example, one font collection could be for static fonts, another for dynamic fonts. Or separate color collections for light and dark mode.These collections are further grouped together into the
DownStylerConfigurationstruct, so that different configurations can be swapped for different rendering styles. The configuration also contains a group of other options, used to configure the appearance of the custom attributes.Custom Attributes
Unfortunately, not all markdown elements can be visually represented using an
NSAttributedString. These include the stripes for block quotes, the horizontal rule for thematic breaks, and the inset background container for code blocks. In order to render these elements, I defined some custom attributes.In order to render these attributes, a custom layout manager is required. The
DownLayoutManagercan be wired up to an existing text view subclass to support custom attributes, or alternatively one could use theDownTextView, which is a preconfiguredTextKitstack that will automatically render markdown content (with custom attributes) whenever thetextproperty is set.Down Text View & Debug Text View
While working on the implementation I used a variation of
DownLayoutManagerthat draws the boundaries of line fragments. Line fragments are the bounding rectangles in which lines are laid out. TheDownDebugLayoutManagerwill indicate the line rect fragments (the rect containing the line) in red. The used line rect fragments (the rect enclosing the text within a line fragment) are drawn in blue.I’ve exposed
DownDebugLayoutManagerandDownDebugTextViewbecause they’re useful tools to help specify the properties affecting paragraph styling.API Breaking Changes
Some of the API declared in #132 needed to be adjusted to grant the
Stylermore information to work with. These include adding arguments for the nest depth for lists and quotes, the prefix length for list items, and a new style method for the list item prefix.Note
Images aren’t yet supported (they appear just like links), but I’d like to add the support next.
Inline code elements don’t have colored backgrounds yet, but I may add support for that too at a later date.
Finally, having mostly worked with iOS, I developed this primarily from an iOS point of view. Nonetheless, the default styler works across the other platforms too.