@splunk/react-ui 5.7.0 → 5.8.0

package/docs-llm/Code.md

@@ -0,0 +1,292 @@
+# Code
+
+## Overview
+
+
+> Image: Illustration of the Code component displaying inline and block code examples.
+
+
+## When to use this component
+- To display pieces of code, command-line instructions, or technical values in a way that visually distinguishes them from surrounding content.
+
+## When to use another component
+- For short, inline technical values (such as a command or variable name), consider using `Typography` with monospace styling applied.
+
+### Check out
+- [Typography][1]
+
+## Behaviors
+- Renders as a block-level element.
+- Applies syntax highlighting based on the specified `language` prop.
+- Preserves indentation and formatting.
+- Optionally shows vertical indentation guides when the `showIndentGuide` prop is set to `true`. This can improve readability for deeply nested code (e.g., JSON or XML).
+
+> Image: Example of the Code component showing JavaScript code with indentation guides.
+
+
+## Usage
+- Choose the appropriate language identifier to enable correct syntax highlighting.
+
+> Image: Two examples of the Code component showing JavaScript code. The example on the left uses the correct value for the language prop. The example on the right shows the language prop incorrectly set to 
+
+
+## Content
+- Use proper syntax and indentation to ensure readability and clarity.
+- Provide a clear and meaningful code example—avoid placeholder text unless needed for layout purposes.
+- Do not localize code content.
+
+[1]: ./Typography
+
+## Examples
+
+
+### Default Javascript
+
+```typescript
+import React from 'react';
+
+import Code from '@splunk/react-ui/Code';
+
+const source = `
+function multiply(a, b) {
+    if (typeof a !== 'number' || typeof b !== 'number') {
+        throw new TypeError('Expected two numbers');
+    }
+
+    const result = a * b;
+
+    return result;
+}
+
+export default multiply;
+`.trim();
+
+
+function Default() {
+    return <Code value={source} />;
+}
+
+export default Default;
+```
+
+
+
+### Customize Container
+
+```typescript
+import React from 'react';
+
+import Code from '@splunk/react-ui/Code';
+
+const source = `
+function multiply(a, b) {
+    if (typeof a !== 'number' || typeof b !== 'number') {
+        throw new TypeError('Expected two numbers');
+    }
+
+    const result = a * b;
+
+    return result;
+}
+
+export default multiply;
+`.trim();
+
+
+function CustomizeContainer() {
+    return <Code containerAppearance="section" value={source} />;
+}
+
+export default CustomizeContainer;
+```
+
+
+
+### Without indent guideline
+
+```typescript
+import React from 'react';
+
+import Code from '@splunk/react-ui/Code';
+
+const source = `
+function multiply(a, b) {
+    if (typeof a !== 'number' || typeof b !== 'number') {
+        throw new TypeError('Expected two numbers');
+    }
+
+    const result = a * b;
+
+    return result;
+}
+
+export default multiply;
+`.trim();
+
+
+function HideIndent() {
+    return <Code value={source} showIndentGuide={false} />;
+}
+
+export default HideIndent;
+```
+
+
+
+### With line numbers
+
+```typescript
+import React from 'react';
+
+import Code from '@splunk/react-ui/Code';
+
+const source = `
+function multiply(a, b) {
+    if (typeof a !== 'number' || typeof b !== 'number') {
+        throw new TypeError('Expected two numbers');
+    }
+
+    const result = a * b;
+
+    return result;
+}
+
+export default multiply;
+`.trim();
+
+
+function LineNumbers() {
+    return <Code showLineNumbers value={source} />;
+}
+
+export default LineNumbers;
+```
+
+
+
+### With line numbers and custom start
+
+```typescript
+import React from 'react';
+
+import Code from '@splunk/react-ui/Code';
+
+const source = `
+function multiply(a, b) {
+    if (typeof a !== 'number' || typeof b !== 'number') {
+        throw new TypeError('Expected two numbers');
+    }
+
+    const result = a * b;
+
+    return result;
+}
+
+export default multiply;
+`.trim();
+
+
+function LineNumbersCustomStart() {
+    return <Code showLineNumbers lineNumberStart={120} value={source} />;
+}
+
+export default LineNumbersCustomStart;
+```
+
+
+
+### With line highlighting
+
+```typescript
+import React from 'react';
+
+import Code from '@splunk/react-ui/Code';
+
+const source = `
+function multiply(a, b) {
+    if (typeof a !== 'number' || typeof b !== 'number') {
+        throw new TypeError('Expected two numbers');
+    }
+
+    const result = a * b;
+
+    return result;
+}
+
+export default multiply;
+`.trim();
+
+
+function LineHighlights() {
+    return <Code lineHighlights="2-4,6" value={source} />;
+}
+
+export default LineHighlights;
+```
+
+
+
+### Non-Javascript syntax highlighting
+
+```typescript
+import React from 'react';
+
+import Code from '@splunk/react-ui/Code';
+
+const css = `
+/* An example of a css file */
+
+.pre {
+    @mixin reset block;
+
+    line-height: 17px;
+    text-align: left;
+    tab-size: 4;
+    white-space: pre;
+    word-spacing: normal;
+    word-break: normal;
+    word-wrap: normal;
+    hyphens: none;
+    overflow-x: auto;
+    margin-bottom: 1.3em;
+
+    &::selection {
+        background: color($focusColor a(12%) s(100%));
+    }
+}
+`.trim();
+
+
+function Language() {
+    return <Code value={css} language="css" />;
+}
+
+export default Language;
+```
+
+
+
+
+## API
+
+
+### Code API
+
+#### Props
+
+| Name | Type | Required | Default | Description |
+|------|------|------|------|------|
+| containerAppearance | 'none' \| 'section' | no | 'none' | Change the style of the Code container. |
+| elementRef | React.Ref<HTMLPreElement> | no |  | A React ref which is set to the DOM element when the component mounts and null when it unmounts. |
+| language | \| 'bash' \| 'c' \| 'clike' \| 'cpp' \| 'cs' \| 'csharp' \| 'css' \| 'html' \| 'javascript' \| 'js' \| 'json' \| 'jsx' \| 'markup' \| 'mathml' \| 'plain' \| 'plaintext' \| 'powershell' \| 'py' \| 'python' \| 'sh' \| 'shell' \| 'splunk-spl' \| 'sql' \| 'svg' \| 'text' \| 'ts' \| 'tsx' \| 'txt' \| 'typescript' \| 'xml' \| 'yaml' \| 'yml' | no |  | Applies syntax highlighting for a specific programming language. |
+| languageFallback | \| 'bash' \| 'c' \| 'clike' \| 'cpp' \| 'cs' \| 'csharp' \| 'css' \| 'html' \| 'javascript' \| 'js' \| 'json' \| 'jsx' \| 'markup' \| 'mathml' \| 'plain' \| 'plaintext' \| 'powershell' \| 'py' \| 'python' \| 'sh' \| 'shell' \| 'splunk-spl' \| 'sql' \| 'svg' \| 'text' \| 'ts' \| 'tsx' \| 'txt' \| 'typescript' \| 'xml' \| 'yaml' \| 'yml' | no | 'javascript' | In cases where `language` is not valid `Code` will use this value as the fallback for `language`. |
+| lineHighlights | string | no |  | Accepts a comma separated list of line numbers or line number ranges to highlight. example: `2,4-5` will highlight lines 2, 4 and 5. |
+| lineNumberStart | number | no |  | Optional start number when showLineNumbers is true. |
+| showIndentGuide | boolean | no | true | Displays the indent guideline. |
+| showLineNumbers | boolean | no |  | Displays line numbers. |
+| value | string | no | '' | Inserts code content into the code block. |
+
+
+
+
+