[EuiCodeBlock] Add new `lineNumbers.annotations` API #6580

cee-chen · 2023-02-07T23:22:25Z

Summary

This PR implements a new annotations API for EuiCodeBlock, with the primary purpose of aiding the @elastic/docs-engineering team and new Elastic docs efforts.

Example usage:

<EuiCodeBlock
  lineNumbers={{
    annotations: {
      1: <>A <b>special</b> note about this line</>,
      9: 'Also accepts quick plaintext notes',
    }
  }}
>
  {}
</EuiCodeBlock>

QA

QA link: https://eui.elastic.co/pr_6580/#/editors-syntax/code#line-numbers

General checklist

Checked in both light and dark modes
Checked in mobile
Checked in Chrome, Safari, Edge, and Firefox
Props have proper autodocs (using @default if default values are missing) and playground toggles
Added documentation
Added or updated jest and cypress tests
Checked for accessibility including keyboard-only and screenreader modes
Updated the Figma library counterpart
A changelog entry exists and is marked appropriately

~~- [ ] Checked Code Sandbox works for any docs examples~~
~~- [ ] Checked for breaking changes and labeled appropriately~~

- reusable component specific to EuiCodeBlock only (including icon) + tweak code block line styles to accommodate new annotation icons

- via a custom `type: annotation` object - making the annotation button an accessible child of the `lineNumber` element requires removing the `aria-hidden` from the wrapper, and creating a new child that has `aria-hidden` on it (hence the new lineNumberWrapper stlyes and snapshot markup changes) - TBD: figuring out accessible line number + highlight announcements would be great, but is out of scope for this PR

- ensuring that virtualized and fullscreen annotations are both tested, since there isn't an example of that currently in our docs + fix fun bug found during E2E tests where Escape keypresses would also close fullscreen - TDD works!

cee-chen · 2023-02-07T23:29:19Z

@miukimiu Do you mind updating the Figma library with this new design/functionality, and of course providing any UI/UX feedback or change requests for this PR?

@glitteringkatie If you have the time, a quick engineering code review would be appreciated! Doesn't need to be super in-depth as I went very very extra on writing tests for this functionality, but figured you might be interested 👀

kibanamachine · 2023-02-07T23:55:07Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_6580/

elizabetdev

Thanks @cee-chen,

I tested in Chrome, Safari, Edge, and Firefox. I tested using the keyboard navigation and mouse.

I pushed 1da9d83 to improve the icon color contrast in dark mode:

I also added motion on hover and focus. I used the same animation that we have on other buttons:

From a design perspective LGTM! 🎉

Let me know if the changes sound good.

kibanamachine · 2023-02-08T16:19:44Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_6580/

cee-chen · 2023-02-08T17:33:26Z

Absolutely lovely changes! Thank you Elizabet!

I'm going to go ahead and merge - if you could check off the Figma checklist item whenever you've added this to the Figma library (if applicable) that would be super helpful.

Katie, feel free to leave any comments or code review still - I can always open a follow-up PR if you notice anything!

glitteringkatie · 2023-02-14T00:12:20Z

src/components/code/code_block_annotations.tsx

+      }
+      css={styles.euiCodeBlockAnnotation}
+      zIndex={Number(euiTheme.levels.mask) + 1} // Ensure fullscreen annotation popovers sit above the mask
+      anchorPosition="leftCenter"


Thank you for this component!

Literally only comment is a nit:

We'd prefer this to be downLeft. There isn't necessarily a lot of space to the left of code blocks and then it defaults to rightCenter and covers up the code snippet it is annotating. I guess you could make the same argument for multi-line annotations but I think the more common case is one line so we'd rather optimize for that.

I'm totally good with that! Do you want to make a super quick PR with that change? 🙌

## Summary `eui@75.0.0` ⏩ `eui@75.1.0` --- ## [`75.1.0`](https://github.com/elastic/eui/tree/v75.1.0) - Added padding to `EuiStep` title to better align with icon ([#6555](elastic/eui#6555)) - Added a new `lineNumbers.annotations` API to `EuiCodeBlock`. This new feature displays an informational icon next to the specified line number(s), providing more context via popover ([#6580](elastic/eui#6580)) **Bug fixes** - Fixed bug in `EuiRange` where styles were applied incorrectly when custom ticks were passed but `showTicks` were false ([#6588](elastic/eui#6588)) - Fixed `fleetApp` and `agentApp` icons that were swapped ([#6590](elastic/eui#6590)) **CSS-in-JS conversions** - Converted `EuiSteps` to Emotion; Removed `$euiStepStatusColorsToFade`, `$euiStepNumberSize`, `$euiStepNumberSmallSize`, and `$euiStepNumberMargin` ([#6555](elastic/eui#6555))

cee-chen added 4 commits February 7, 2023 14:59

Set up baseline EuiCodeBlockAnnotation sub-component

ebf7886

- reusable component specific to EuiCodeBlock only (including icon) + tweak code block line styles to accommodate new annotation icons

Set up API & documentation

fd9d198

Add E2E tests for annotation behavior/combinations

5809d2e

- ensuring that virtualized and fullscreen annotations are both tested, since there isn't an example of that currently in our docs + fix fun bug found during E2E tests where Escape keypresses would also close fullscreen - TDD works!

cee-chen requested review from elizabetdev and glitteringkatie February 7, 2023 23:22

changelog

5b21f8b

cee-chen mentioned this pull request Feb 7, 2023

[EuiCodeBlock][a11y] Should line numbers be audible to screen readers? #5380

Closed

Design review

1da9d83

elizabetdev approved these changes Feb 8, 2023

View reviewed changes

elizabetdev mentioned this pull request Feb 8, 2023

[EuiCodeBlock] Add new annotations feature #6574

Closed

11 tasks

cee-chen merged commit f3cb9db into elastic:main Feb 8, 2023

cee-chen deleted the code-annotations branch February 8, 2023 17:36

glitteringkatie reviewed Feb 14, 2023

View reviewed changes

cee-chen mentioned this pull request Feb 14, 2023

Upgrade EUI to v75.1.0 elastic/kibana#151200

Merged

glitteringkatie mentioned this pull request Feb 14, 2023

[EuiCodeBlock] Anchor annotation down left #6600

Merged

2 tasks

cee-chen mentioned this pull request Jun 1, 2023

[EuiCodeBlock] Fix line numbers appearing in copied content #6824

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[EuiCodeBlock] Add new `lineNumbers.annotations` API #6580

[EuiCodeBlock] Add new `lineNumbers.annotations` API #6580

cee-chen commented Feb 7, 2023 •

edited

Loading

cee-chen commented Feb 7, 2023

kibanamachine commented Feb 7, 2023

elizabetdev left a comment

kibanamachine commented Feb 8, 2023

cee-chen commented Feb 8, 2023

glitteringkatie Feb 14, 2023

cee-chen Feb 14, 2023

glitteringkatie Feb 14, 2023

glitteringkatie Feb 14, 2023

[EuiCodeBlock] Add new lineNumbers.annotations API #6580

[EuiCodeBlock] Add new lineNumbers.annotations API #6580

Conversation

cee-chen commented Feb 7, 2023 • edited Loading

Summary

QA

General checklist

cee-chen commented Feb 7, 2023

kibanamachine commented Feb 7, 2023

elizabetdev left a comment

Choose a reason for hiding this comment

kibanamachine commented Feb 8, 2023

cee-chen commented Feb 8, 2023

glitteringkatie Feb 14, 2023

Choose a reason for hiding this comment

cee-chen Feb 14, 2023

Choose a reason for hiding this comment

glitteringkatie Feb 14, 2023

Choose a reason for hiding this comment

glitteringkatie Feb 14, 2023

Choose a reason for hiding this comment

[EuiCodeBlock] Add new `lineNumbers.annotations` API #6580

[EuiCodeBlock] Add new `lineNumbers.annotations` API #6580

cee-chen commented Feb 7, 2023 •

edited

Loading