Ensure codeblocks use accessible colors #183

andyfeller · 2025-02-19T15:21:47Z

This commit leverages cli fork of charmbracelet/glamour with enhancement for configuring chroma formatter.

It includes simple tests that enabling gh accessible features causes codeblocks to be downsampled to base 16 ANSI colors.

This commit leverages `cli` fork of `charmbracelet/glamour` with enhancement for configuring `chroma` formatter. It includes simple tests that enabling `gh` accessible features causes codeblocks to be downsampled to base 16 ANSI colors.

andyfeller · 2025-02-19T15:32:31Z

Looking back at the changes in the PR versus cli/cli#9821, I'm confirming the need to remove the replace and change all of the import statements to use our fork until we can get the changes accepted upstream.

jtmcg

Could you link the fork changes, @andyfeller? I'd find it helpful so we understand what this is introducing from the fork.

pkg/markdown/markdown_test.go

pkg/markdown/markdown.go

andyfeller · 2025-02-20T15:48:17Z

Going to close this PR for the moment because there is a bit more work to do with changing this to use our fork of glamour with import paths.

Will continue responding to comments in the mean time. 👍

@williammartin

This commit is v2 approach to testing for accessible colors and codeblock rendering using an in-house approach to identifying ANSI escape sequences and analyzing them for color depth. After talking with @williammartin, this is likely going to be refactored a third time leveraging a module to help with parsing escape sequences from text.

This commit is focused on PR feedback around codeblock testing and simplifying related code: 1. Use of new `WithOptions(...TermRendererOption) TermRendererOption` to clean up `WithTheme()` The `glamour` TermRendererOption pattern has a limitation that users cannot compose multiple options without duplicating code or building one-off anonymous functions. However, this commit takes advantage of an enhancement in cli/glamour#3 that allows users to leverage a helper to avoid building one-offs. 1. Use of new `leaanthony/go-ansi-parser` dependency for parsing ANSI escape sequences and display attributes In v1 of `markdown_test.go`, the codeblock tests were very simple, testing the result of output of markdown rendering against a string of ANSI escape sequences. The concern raised is that this was testing the result rather than behavior wanted. In v2 of `markdown_test.go`, the codeblock tests were refactored to use regex to extract and analyze ANSI escape sequences and display attributes. The concern raised was that this was a lot of logic to build and maintain and might benefit from a dependency that could do it. In v3 of `markdown_test.go`, a combination of v1 and v2 approaches for 1) testing that theme appropriate colors are used and 2) testing that ensures accessible display options are used when accessible experience is enabled

andyfeller · 2025-02-25T14:40:54Z

@jtmcg @williammartin : Thank you both for feedback while iterating on this PR! 🙇 I'm reopening it after iterating on feedback to make some improvements but also wanting to make the case for certain concerns.

Important

This PR is dependent on changes in cli/glamour#3 and has been updated to use the latest commit SHA from andyfeller/multi-options.

Changes

Use of new WithOptions(...TermRendererOption) TermRendererOption to clean up WithTheme()

The glamour TermRendererOption pattern has a limitation that users cannot compose multiple options without duplicating code or building one-off anonymous functions.

However, this commit takes advantage of an enhancement in Update forked module name, paths, and docs to be imported; support for applying multiple options in a TermRendererOption glamour#3 that allows users to leverage a helper to avoid building one-offs. This results in a generic solution to the problem we face with WithTheme needing to set multiple options from a single place.
Use of new leaanthony/go-ansi-parser dependency for parsing ANSI escape sequences and display attributes

c5336a5 was my initial effort in refactoring the markdown codeblock tests to generically check ANSI escape codes using regular expressions to identify and parse escape sequences.

While discussing the test with @williammartin, he suggested leaanthony/go-ansi-parse as an alternative versus building and maintaining our own logic.
Expanding markdown_test.go to cover accessible color testing while still testing glamour and chroma output

There are 2 concerns I have around glamour and chroma as we implement accessible markdown rendering:
1. style-appropriate colors are used
2. 4-bit, base 16 ANSI colors are used when we ask for them.
In the original PR, only tests concerned with the former existed. While useful, I agree that they were very situational and maybe a little difficult to grok / maintain. However, they also highlighted important aspects of glamour and chroma around registry caching and how if we don't look at these colors we are likely to have low visibility colors used when not appropriate.

Now, we have a 2nd suite of tests that cover the latter that more generically test ANSI escape sequences for accessibility concerns.

andyfeller · 2025-02-25T15:24:52Z

Thoughts about testing codeblocks

One of the concerns originally raised around the codeblock color testing was that it was hard to grok and maintain:

go-gh/pkg/markdown/markdown_test.go

Lines 153 to 178 in 2b16a44

    
           { 
        
           	name:    "when the light theme is selected, the codeblock renders using 8-bit colors", 
        
           	text:    codeBlock, 
        
           	theme:   "light", 
        
           	wantOut: "\x1b[0m\x1b[38;5;235mfmt\x1b[0m\x1b[38;5;210m.\x1b[0m\x1b[38;5;35mPrintln\x1b[0m\x1b[38;5;210m(\x1b[0m\x1b[38;5;95m\"Hello, world!\"\x1b[0m\x1b[38;5;210m)\x1b[0m", 
        
           }, 
        
           { 
        
           	name:    "when the dark theme is selected, the codeblock renders using 8-bit colors", 
        
           	text:    codeBlock, 
        
           	theme:   "dark", 
        
           	wantOut: "\x1b[0m\x1b[38;5;251mfmt\x1b[0m\x1b[38;5;187m.\x1b[0m\x1b[38;5;42mPrintln\x1b[0m\x1b[38;5;187m(\x1b[0m\x1b[38;5;173m\"Hello, world!\"\x1b[0m\x1b[38;5;187m)\x1b[0m", 
        
           }, 
        
           { 
        
           	name:             "when the accessible env var is set and the light theme is selected, the codeblock renders using 4-bit colors", 
        
           	text:             codeBlock, 
        
           	theme:            "light", 
        
           	accessibleEnvVar: "true", 
        
           	wantOut:          "\x1b[0m\x1b[30mfmt\x1b[0m\x1b[33m.\x1b[0m\x1b[36mPrintln\x1b[0m\x1b[33m(\x1b[0m\x1b[90m\"Hello, world!\"\x1b[0m\x1b[33m)\x1b[0m", 
        
           }, 
        
           { 
        
           	name:             "when the accessible env var is set and the dark theme is selected, the codeblock renders using 4-bit colors", 
        
           	text:             codeBlock, 
        
           	theme:            "dark", 
        
           	accessibleEnvVar: "true", 
        
           	wantOut:          "\x1b[0m\x1b[37mfmt\x1b[0m\x1b[37m.\x1b[0m\x1b[36mPrintln\x1b[0m\x1b[37m(\x1b[0m\x1b[33m\"Hello, world!\"\x1b[0m\x1b[37m)\x1b[0m", 
        
           },

The concern being the difficulty of reading ANSI escape sequences like:

"\x1b[0m\x1b[38;5;235mfmt\x1b[0m\x1b[38;5;210m.\x1b[0m\x1b[38;5;35mPrintln\x1b[0m\x1b[38;5;210m(\x1b[0m\x1b[38;5;95m\"Hello, world!\"\x1b[0m\x1b[38;5;210m)\x1b[0m"

I 💯 agree this isn't ideal and thus experimented with a couple different forms which I'm unsure are legitimately better:

fmt.Sprintf(...)

From Ensure codeblocks use accessible colors #183 (comment):

	reset                                            = "\x1b[0m"
	glamourLightCodeBlock_8bitRaisinBlackColorSeq    = "\x1b[38;5;235m"
	glamourLightCodeBlock_8bitVividTangerineColorSeq = "\x1b[38;5;210m"
	glamourLightCodeBlock_8bitJadeColorSeq           = "\x1b[38;5;35m"
	glamourLightCodeBlock_8bitCopperRoseColorSeq     = "\x1b[38;5;95m"

fmt.Sprintf("%[1]s%[2]sfmt%[1]s%[3]s.%[1]s%[4]sPrintln%[1]s%[3]s(%[1]s%[5]s\"Hello, world!\"%[1]s%[3]s)%[1]s", reset, glamourLightCodeBlock_8bitRaisinBlackColorSeq, glamourLightCodeBlock_8bitVividTangerineColorSeq, glamourLightCodeBlock_8bitJadeColorSeq, glamourLightCodeBlock_8bitCopperRoseColorSeq)

text/template

t, err := template.New("codeblock").Parse(`{{.Reset}}{{.Package}}fmt{{.Reset}}{{.Operator}}.{{.Reset}}{{.Func}}Println{{.Reset}}{{.Operator}}({{.Reset}}{{.Literal}}\"Hello, world!\"{{.Reset}}{{.Operator}}){{.Reset}}`)

data := map[string]string{
    "Reset": "\x1b[0m",
    "Package": "\x1b[38;5;235m",
    "Operator": "\x1b[38;5;210m",
    "Func": "\x1b[38;5;35m",
    "Literal: "\x1b[38;5;95m",
}

var buf bytes.Buffer
err = t.Execute(&buf, data)
if err != nil {
    panic(err)
}

result := buf.String()

I have 2 concerns with the above alternatives:

There is significantly more code to understand and reason about
Some of these alternatives would affect the design of Test_Render, potentially adding to brittleness between test use cases

For these reasons, I kept the original v1 forms of the codeblock tests checking for specific color usage for confidence that reasonably contrasting colors relative to the theme are being displayed. If there is some other form these can take that is appropriate for testing without being a significant lift, then I appreciate suggestions.

jtmcg

A couple of questions and two suggestions, but otherwise this is looking good 👍 I have no further ideas about making the escape codes easier to grok other than what we already discussed, so 🤷

pkg/markdown/markdown.go

pkg/markdown/markdown_test.go

@jtmcg

After discussing the changing nature of the tests with @jtmcg, this commit renames the test functions to make it apparent their purposes: testing we get the colors we want separate from checking for accessibility concerns. In addition, there were a number of other improvements to be more idiomatic.

jtmcg

Great stuff! Thanks for all the back and forth. This really came together 👍

jtmcg · 2025-02-27T20:25:07Z

pkg/markdown/markdown_test.go

+	goCodeBlock := heredoc.Docf(`
+		%[1]s%[1]s%[1]sgo
+		package main
+
+		import (
+			"fmt"
+		)
+
+		func main() {
+			fmt.Println("Hello, world!")
+		}
+		%[1]s%[1]s%[1]s
+	`, "`")
+
+	shellCodeBlock := heredoc.Docf(`
+		%[1]s%[1]s%[1]sshell
+		# list all repositories for a user
+		$ gh api graphql --paginate -f query='
+			query($endCursor: String) {
+				viewer {
+					repositories(first: 100, after: $endCursor) {
+						nodes { nameWithOwner }
+						pageInfo {
+							hasNextPage
+							endCursor
+						}
+					}
+				}
+			}
+		'
+		%[1]s%[1]s%[1]s
+	`)


Note: These big, formatted text blocks give me anxiety in testing 😅 However, as long as we aren't asserting text matching on either of these (which we aren't currently) I feel alright about it. Trying to sort through the ANSI output of this to debug tests would be a nightmare and is why the matching strings I added in Test_RenderColor are so short

That is a fair line in the sand :nod: I tend to value DRYing things up a little where reasonable that doesn't add brittleness. If these tests change, then I would hope this approach is revisited and changed to fit the evolving need. 💯

pkg/markdown/markdown_test.go

Ensure codeblocks use accessible colors

e61b6d6

This commit leverages `cli` fork of `charmbracelet/glamour` with enhancement for configuring `chroma` formatter. It includes simple tests that enabling `gh` accessible features causes codeblocks to be downsampled to base 16 ANSI colors.

andyfeller requested a review from jtmcg February 19, 2025 15:21

jtmcg reviewed Feb 19, 2025

View reviewed changes

pkg/markdown/markdown_test.go Outdated Show resolved Hide resolved

jtmcg reviewed Feb 19, 2025

View reviewed changes

pkg/markdown/markdown.go Outdated Show resolved Hide resolved

andyfeller closed this Feb 20, 2025

andyfeller added 2 commits February 24, 2025 14:37

andyfeller reopened this Feb 25, 2025

jtmcg reviewed Feb 25, 2025

View reviewed changes

pkg/markdown/markdown.go Show resolved Hide resolved

pkg/markdown/markdown_test.go Outdated Show resolved Hide resolved

pkg/markdown/markdown_test.go Outdated Show resolved Hide resolved

pkg/markdown/markdown_test.go Outdated Show resolved Hide resolved

andyfeller requested a review from jtmcg February 27, 2025 19:19

jtmcg approved these changes Feb 27, 2025

View reviewed changes

andyfeller merged commit 0136321 into accessible-colors Feb 27, 2025
8 checks passed

andyfeller deleted the andyfeller/accessible-colors-chroma branch February 27, 2025 20:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Ensure codeblocks use accessible colors #183

Ensure codeblocks use accessible colors #183

andyfeller commented Feb 19, 2025

andyfeller commented Feb 19, 2025 •

edited

Loading

jtmcg left a comment

andyfeller commented Feb 20, 2025

andyfeller commented Feb 25, 2025

andyfeller commented Feb 25, 2025 •

edited

Loading

jtmcg left a comment

jtmcg left a comment

jtmcg Feb 27, 2025

andyfeller Feb 27, 2025

Ensure codeblocks use accessible colors #183

Ensure codeblocks use accessible colors #183

Conversation

andyfeller commented Feb 19, 2025

andyfeller commented Feb 19, 2025 • edited Loading

jtmcg left a comment

Choose a reason for hiding this comment

andyfeller commented Feb 20, 2025

andyfeller commented Feb 25, 2025

Changes

andyfeller commented Feb 25, 2025 • edited Loading

Thoughts about testing codeblocks

jtmcg left a comment

Choose a reason for hiding this comment

jtmcg left a comment

Choose a reason for hiding this comment

jtmcg Feb 27, 2025

Choose a reason for hiding this comment

andyfeller Feb 27, 2025

Choose a reason for hiding this comment

andyfeller commented Feb 19, 2025 •

edited

Loading

andyfeller commented Feb 25, 2025 •

edited

Loading