|
| 1 | +## Usage |
| 2 | + |
| 3 | +### When to use |
| 4 | + |
| 5 | +- When a user needs to create code from scratch. |
| 6 | +- When code requires modification from an existing source. |
| 7 | + |
| 8 | +### When not to use |
| 9 | + |
| 10 | +- As a read-only reference for code, use the [Code Block](/components/code-block) instead. |
| 11 | + |
| 12 | +## Standalone |
| 13 | + |
| 14 | +The `isStandalone` property increases the portability of the Code Editor to ensure that it can be used in different contexts. For example, a common use case of the Code Editor is in a “standalone” context, which can be part of a form or multi-step process and is generally a part of the normal layout flow. |
| 15 | + |
| 16 | + |
| 17 | + |
| 18 | +Sometimes it may be necessary to use the Code Editor in a more dense layout or nested within another component. |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +## Header |
| 23 | + |
| 24 | +An optional header is available within the Code Editor. It consists of three sections that can be toggled as needed: |
| 25 | + |
| 26 | +- the text content that includes the title and description |
| 27 | +- an actions container for secondary actions |
| 28 | +- a custom content section for adding primary actions |
| 29 | + |
| 30 | +### When to use a title and description |
| 31 | + |
| 32 | +A title and description provides additional contextual information for the Code Editor. An accessible name is mandatory and can either be provided by the title or by an external text element. |
| 33 | + |
| 34 | +!!! Do |
| 35 | + |
| 36 | +Provide an accessible name for the Code Editor so that users of assistive technology can understand its purpose. |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +!!! |
| 41 | + |
| 42 | +!!! Dont |
| 43 | + |
| 44 | +Assume all users will understand the purpose of the Code Editor without providing an accessible name. Not providing one may cause confusion and is an accessibility failure. |
| 45 | + |
| 46 | + |
| 47 | +!!! |
| 48 | + |
| 49 | +## Secondary actions |
| 50 | + |
| 51 | +The secondary actions section supports two optional buttons: the [Copy Button](/components/copy/button), and a “full screen” button. The Copy Button copies the content of the Code Editor to the clipboard, while the full screen button toggles the size of the Code Editor from inline view to full screen. |
| 52 | + |
| 53 | + |
| 54 | + |
| 55 | +## Custom actions |
| 56 | + |
| 57 | +This space is intended for custom primary actions. Primary actions are those which are necessary for the user to complete their work. |
| 58 | + |
| 59 | + |
| 60 | + |
| 61 | +Here is an example of a custom action to reveal secrets. |
| 62 | + |
| 63 | + |
| 64 | + |
| 65 | + |
| 66 | +!!! Warning |
| 67 | + |
| 68 | +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](about/support) for help translating components into dark mode. |
| 69 | + |
| 70 | +!!! |
| 71 | + |
| 72 | +## External elements |
| 73 | + |
| 74 | +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 visually couple the editor with the nearby controlling elements. |
| 75 | + |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +## Active line highlighting |
| 80 | + |
| 81 | +When a user edits a line of code, a highlight will display to show their location within the Code Editor. |
| 82 | + |
| 83 | + |
| 84 | + |
| 85 | +When a user selects a piece of code, the active line highlight no longer displays although the line number of the last line of the selection will be highlighted. |
| 86 | + |
| 87 | + |
| 88 | + |
| 89 | +## Bracket highlighting |
| 90 | + |
| 91 | +The Code Editor automatically closes open quotes and brackets as the user types. When the user’s cursor is next to a bracket, the bracket will highlight to show the start and end of the pair. |
| 92 | + |
| 93 | + |
| 94 | + |
| 95 | +## Language |
| 96 | + |
| 97 | +Language determines how syntax highlighting is applied and formatted within the editor but is handled a bit differently between the Ember and Figma components. |
| 98 | + |
| 99 | +The **Ember** component uses [CodeMirror](https://codemirror.net/) to handle syntax highlighting and comes with a pre-defined set of [languages](/components/code-editor?tab=code#language-1). |
| 100 | + |
| 101 | +In **Figma** we provide a handful of example languages intended as visual examples. Syntax highlighting in Figma is a non-trivial process and requires the manual application of color styles to each “type” of code. You are still able to add a custom code snippet to the Figma component by typing/pasting into the text layer, but syntax highlighting will not be automatically applied. |
| 102 | + |
| 103 | +### Applying syntax highlighting |
| 104 | + |
| 105 | +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. |
| 106 | +For more details around syntax, visit the [specifications](/components/code-editor?tab=specifications). |
0 commit comments