Hds::CodeEditor Website updates
#2626
Draft
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
@majedelass Looking good! Left a few notes.
One thing that caught me off guard, though, was the sections for "Active line highlighting" and "Bracket highlighting." I don't know that they're necessary. They aren't guidelines the consumer should follow or options they can choose from, but examples of styling for functional embedded features. Do others think this should be documented within the guidelines?
| description: A code editor with syntax highlighting, change history, and keyboard navigation. | ||
| caption: A code editor with syntax highlighting, change history, and keyboard navigation. | ||
| links: | ||
| figma: https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67166-37020&t=w8xQlWxzH7bwXLe2-1 |
There was a problem hiding this comment.
@majedelass This will also need to be updated. It currently links to the CodeBlock page.
website/docs/components/code-editor/partials/guidelines/guidelines.md
Outdated
Show resolved
Hide resolved
website/docs/components/code-editor/partials/guidelines/guidelines.md
Outdated
Show resolved
Hide resolved
jorytindall
reviewed
Jan 9, 2025
|
|
||
| ### Contextual components | ||
|
|
||
| #### [CB].Title |
There was a problem hiding this comment.
Should the contextual component be this instead? Maybe this is a result of copy-pasta from the CodeBlock?
Suggested change
| #### [CB].Title | |
| #### [CE].Title |
| </C.Property> | ||
| </Doc::ComponentApi> | ||
|
|
||
| #### [CB].Description |
There was a problem hiding this comment.
Same question here
Suggested change
| #### [CB].Description | |
| #### [CE].Description |
|
|
||
| <Doc::ComponentApi as |C|> | ||
| <C.Property @name="yield"> | ||
| Accepts complex content, such as logic/conditionals, HTML elements, other Ember components, etc. Content inherits its style. Styling is applied for simple HTML elements, such as `strong`, `em`, `a`, `code/pre`. Consumers will need to style other HTML tags if used as children |
There was a problem hiding this comment.
I personally had to re-read this a few times to grasp it, I think what was confusing me was "Content inherits its style", which is then followed by the rest of the styling information, which seems somewhat contradictory? I also could totally be misunderstanding this
Suggested change
| Accepts complex content, such as logic/conditionals, HTML elements, other Ember components, etc. Content inherits its style. Styling is applied for simple HTML elements, such as `strong`, `em`, `a`, `code/pre`. Consumers will need to style other HTML tags if used as children | |
| Accepts complex content, such as logic/conditionals, HTML elements, other Ember components, etc. Styling is applied for simple HTML elements, such as `strong`, `em`, `a`, `code/pre`. Consumers will need to style other HTML tags if used as children |
|
|
||
| <Doc::ComponentApi as |C|> | ||
| <C.Property @name="yield"> | ||
| Accepts complex content, such as logic/conditionals, HTML elements, other Ember components, etc. Content inherits its style. Styling is applied for simple HTML elements, such as `strong`, `em`, `a`, `code/pre`. Consumers will need to style other HTML tags if used as children. |
There was a problem hiding this comment.
Same question about "Content inherits its style", if this is still relevant, feel free to disregard.
website/docs/components/code-editor/partials/guidelines/guidelines.md
Outdated
Show resolved
Hide resolved
website/docs/components/code-editor/partials/guidelines/guidelines.md
Outdated
Show resolved
Hide resolved
website/docs/components/code-editor/partials/guidelines/guidelines.md
Outdated
Show resolved
Hide resolved
website/docs/components/code-editor/partials/guidelines/guidelines.md
Outdated
Show resolved
Hide resolved
website/docs/components/code-editor/partials/specifications/anatomy.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Jory Tindall <[email protected]>
zamoore
force-pushed
the
alex-ju/code-editor-codemirror-spike
branch
from
bab037d to
17733cf
Compare
zamoore
force-pushed
the
alex-ju/code-editor-codemirror-spike
branch
from
2e45538 to
6c4cbee
Compare
shleewhite
reviewed
Jan 9, 2025
website/docs/components/code-editor/partials/guidelines/guidelines.md
Outdated
Show resolved
Hide resolved
|
|
||
| This provides an accessible name for the Code Editor so that a user and assistive technology can understand its purpose. | ||
|
|
||
|  |
There was a problem hiding this comment.
Suggestion: We can shorten this up a bit.
Suggested change
|  | |
|  |
|
|
||
| !!! Do | ||
|
|
||
| This provides an accessible name for the Code Editor so that a user and assistive technology can understand its purpose. |
There was a problem hiding this comment.
Suggestion: one important thing to know is that the accessible name is not provided by just having the text in the DOM. Either the code editor needs to have aria-label or have aria-labelledby set to the id of the title.
@zamoore set up aria-labelledby to work automatically if you use the CE title component, but it wont work if the title is custom.
|
|
||
| Sometimes it may be necessary to use the Code Editor in a more dense layout or nested within another component. | ||
|
|
||
|  |
There was a problem hiding this comment.
Suggested change
|  | |
|  |
|
|
||
|
|
||
| Assuming a user would understand the intent of the Code Editor without providing an accessible name will cause confusion and fail on accessibility requirements. | ||
|  |
There was a problem hiding this comment.
Suggested change
|  | |
|  |
|
|
||
| !!! Warning | ||
|
|
||
| The Code Editor has limited support for dark mode styles. Buttons have pre-defined dark mode styles, but all other components require manual color adjustments until a dark mode theme is released. Please contact the Design Systems Team for help translating components into dark mode. |
There was a problem hiding this comment.
Suggestion: link to the contact page here
|
|
||
| Some elements or functions outside the Code Editor may affect the content within the Code Editor. In this case, we recommend turning off the header to couple the editor with the nearby elements. | ||
|
|
||
|  |
There was a problem hiding this comment.
Suggested change
|  | |
|  |
|
|
||
| When a user is editing code on a single line, a highlight will be present to emphasize their location in the Code Editor. | ||
|
|
||
|  |
There was a problem hiding this comment.
Suggested change
|  | |
|  |
| ### Applying syntax highlighting | ||
|
|
||
| If you wish to create custom examples using the Code Editor, we publish all of the relevant syntax highlighting variables in the [HDS Components v2.0](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67166-37020&t=gWdKy44MzTP4cTRo-1) library. However, due to the number of languages supported by the component, the color variables use a generic naming schema (e.g., cyan, red, purple) to remain as agnostic as possible when being applied to different languages. | ||
| For more details around syntax visit the [specifications](https://helios.hashicorp.design/components/code-editor?tab=specifications). |
There was a problem hiding this comment.
Just this should work
Suggested change
| For more details around syntax visit the [specifications](https://helios.hashicorp.design/components/code-editor?tab=specifications). | |
| For more details around syntax visit the [specifications](/components/code-editor?tab=specifications). |
| @@ -0,0 +1,29 @@ | |||
| ## Anatomy | |||
|
|
|||
|  | |||
There was a problem hiding this comment.
Suggested change
|  | |
|  |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
📌 Summary
If merged, this PR will add Website documentation for the new
Hds::CodeEditorcomponent added in #2573.🛠️ Detailed description
TBD
📸 Screenshots
TBD
🔗 External links
Jira ticket: HDS-4311
💬 Please consider using conventional comments when reviewing this PR.