[feat]: <rh-code-block> extensions

[bennypowers]

Today at Office hours we took the decision to release a very basic version of code-block with bellsprout.

features we'll push off to bulbasaur:

• new variants of <rh-button>: icon button / FAB for copy
• syntax highlighting
• callout badges
• toolbar/container

We also have some usability questions we'd like to address:

• should copy button always be a FAB (i.e. floating over the codeblock, not slotted into the toolbar)
• is combining tabs with links/actions a usability problem for sighted keyboard users?

SO, basically the bellsprout version will be a gray box that formats a script of text

Originally posted by @bennypowers in #328 (comment)

[markcaron]

@coreyvickery can you provide @bennypowers with guidance on new color tokens for syntax highlighting?

[coreyvickery]

@bennypowers Here are new syntax highlighting colors based on our new color design tokens. Happy to do more work in other places to flesh these out.

Light theme

Red - red-50
Orange - orange-60
Yellow - yellow-60
Green - green-60
Blue - blue-50
Purple - purple-50
Black (text) - gray-95
Dark gray (secondary text) - gray-60
Light gray (lines/borders) - gray-30

Dark theme

Red - red-40
Orange - orange-40
Yellow - yellow-40
Green - green-40
Blue - blue-40
Purple - purple-30
White (text) - white
Dark gray (lines/borders) - gray-50
Light gray (secondary text) - gray-30

[markcaron]

Thanks, @coreyvickery!

@bennypowers, how far along are we with the rest of the work? Wondering if we can wrap this up in Caterpie or if we need to move it to the Chansey release?

[markcaron]

We discussed today in the Docs Overhaul meeting about adding a Show more / View code disclosure button to code blocks. This would be a good way to limit initial vertical height, and ease scanning and finding info.

[zeroedin]

We discussed today in the Docs Overhaul meeting about adding a Show more / View code disclosure button to code blocks. This would be a good way to limit initial vertical height, and ease scanning and finding info.

Here is a screenshot from salesforce lightning design system where they are doing something similar.

[coreyvickery]

@markcaron It's been a while since I've touched the design of this component (hence the XD link), but here are some examples of the Expand to full height feature (question about that below).

To get this completed ASAP, let me know where I need to provide additional design guidance or mock-ups. Maybe we need to have a separate call with Greg or Nikki to tackle some of Benny's usability questions. But first, can we finalize the list of features that we need to ship? This is Benny's list from above, I'm just adding more talking points.

• Toolbar
  • I think this feature needs to be tackled first
  • Is the goal that the next version of this component always includes a toolbar?
  • How do we decide on what's displayed by default? Text only? Tabs? Links?
    • Could there be code written to display different options?
• Copy button
  • What's the format? Text only or an icon button?
    • I know the link is the same, just scroll to see the different options
  • Is it always in the toolbar or is it a FAB in the light/dark gray container?
  • Does it have a tooltip?
• Callout numbers
  • Is this old mock-up sufficient or are more design explorations required?
• Syntax highlighting
  • I added values above that correspond to our color design tokens
  • Are they sufficient? Is using custom colors still the right approach?
• Expand to full height
  • Do we want to add this to the list of features we want to ship?
  • If so, I think this presumes that a minimum height value is needed, so I'll need to figure that out in order to give the right specs

cc @hellogreg

[coreyvickery]

Changes to make

• Copy button is always a FAB
• Only tabs on top
• Secondary toolbar/links on bottom (View demo, for example)
• Diagonal arrows icon for expand to full height? - OR - Expand to full height text in fade/gradient?
• Wrap text toggle or button
• Sample icon:

• Callout numbers
  • Explore new design NOW, code later
  • Toggle annotations?
  • Less visual noise

Near future

Syntax highlighting

• Issue
• Benny's comment

[nikkimk]

.@marionnegp and I met and tested colors with PrismJS's types. Here's what we found works best.

Light Theme

Variable	Color
--rh-code-block-default-color	gray-95
--rh-code-block-background	gray-10
--rh-code-block-selected-text-background	blue-10
--rh-code-block-comment-color	gray-60
--rh-code-block-comment-block-color	gray-60
--rh-code-block-doctype-color	gray-60
--rh-code-block-cdata-color	gray-60
--rh-code-block-punctuation-color	gray-40
--rh-code-block-namespace-color	gray-95
--rh-code-block-property-color	purple-50
--rh-code-block-tag-color	purple-50
--rh-code-block-boolean-color	purple-50
--rh-code-block-number-color	purple-50
--rh-code-block-constant-color	purple-50
--rh-code-block-symbol-color	purple-50
--rh-code-block-deleted-color	purple-50
--rh-code-block-function-name-color	purple-50
--rh-code-block-selector-color	teal-60
--rh-code-block-attr-name-color	teal-60
--rh-code-block-string-color	teal-60
--rh-code-block-character-color	teal-60
--rh-code-block-built-in-color	teal-60
--rh-code-block-inserted-color	teal-60
--rh-code-block-operator-color	yellow-60
--rh-code-block-entity-color	yellow-60
--rh-code-block-url-color	yellow-60
--rh-code-block-string-color	yellow-60
--rh-code-block-at-rule-color	blue-60
--rh-code-block-attr-value-color	blue-60
--rh-code-block-keyword-color	blue-60
--rh-code-block-function-color	red-60
--rh-code-block-class-name-color	red-60
--rh-code-block-regex-color	orange-60
--rh-code-block-important-color	orange-60
--rh-code-block-variable-color	orange-60

Dark theme

Variable	Color
--rh-code-block-default-color	gray-20
--rh-code-block-background	gray-70
--rh-code-block-selected-text-background	gray-95
--rh-code-block-comment-color	gray-50
--rh-code-block-comment-block-color	gray-50
--rh-code-block-doctype-color	gray-50
--rh-code-block-cdata-color	gray-50
--rh-code-block-punctuation-color	gray-20
--rh-code-block-namespace-color	red-40
--rh-code-block-property-color	yellow-40
--rh-code-block-tag-color	red-10
--rh-code-block-boolean-color	orange-40
--rh-code-block-number-color	orange-40
--rh-code-block-constant-color	yellow-40
--rh-code-block-symbol-color	yellow-40
--rh-code-block-deleted-color	red-40
--rh-code-block-function-name-color	teal-20
--rh-code-block-selector-color	purple-30
--rh-code-block-attr-name-color	red-40
--rh-code-block-string-color	green-40
--rh-code-block-character-color	green-40
--rh-code-block-built-in-color	purple-30
--rh-code-block-inserted-color	green-40
--rh-code-block-operator-color	blue-40
--rh-code-block-entity-color	blue-40
--rh-code-block-url-color	blue-40
--rh-code-block-string-color	green-40
--rh-code-block-at-rule-color	purple-30
--rh-code-block-attr-value-color	green-40
--rh-code-block-keyword-color	purple-30
--rh-code-block-function-color	orange-40
--rh-code-block-class-name-color	yellow-40
--rh-code-block-regex-color	green-40
--rh-code-block-important-color	purple-30
--rh-code-block-variable-color	green-40

[bennypowers]

Notes from 2024-03-07

• add to codeblock

  • show more expand button
  • fabs for copy and wrap (default to pre)
  • demos for callout tags
  • line numbers (always)

• add to docs:

  • card with tab bar and panels for code languages
  • external links in footer
  • switch for callouts in footer
  • callout legend beneath card (manual, at least for now)

[bennypowers]

proposal:

1. gather all the token names we'd need to write a prism.js theme
2. gather all the token names we'd need to write a highlight.js theme
3. gather all the token names we'd need to write a treesitter theme
4. decide on the common denominators we want to support from steps 1-3
5. publish our syntax token names

WDYT of that approach @marionnegp ?

[marionnegp]

Sounds good to me. We should still be able to use the token names from Nikki's comment.

[bennypowers]

we got syntax highlighting in for clefairy, moving the leftovers to cubone