feat(components): added CodeBlock component (#DS-5224)

package.json

@@ -89,6 +89,7 @@
     "eslint-plugin-react-hooks": "^7.1.1",
     "fs-extra": "^11.3.0",
     "globals": "^17.9.0",
+    "highlight.js": "^11.11.1",
     "husky": "^9.1.6",
     "jsdom": "^25.0.1",
     "lightningcss": "^1.29.3",

packages/components/package.json

@@ -20,6 +20,10 @@
       "types": "./dist/markdown.d.ts",
       "default": "./dist/markdown.js"
     },
+    "./code-block": {
+      "types": "./dist/code-block.d.ts",
+      "default": "./dist/code-block.js"
+    },
     "./style.css": "./dist/style.css"
   },
   "type": "module",
@@ -46,6 +50,7 @@
   "peerDependencies": {
     "@koobiq/design-tokens": "^3.17.2",
     "@koobiq/react-icons": "^12.1.1",
+    "highlight.js": "^11.0.0",
     "react": "18.x || 19.x",
     "react-dom": "18.x || 19.x",
     "react-markdown": "^10.1.0",
@@ -57,6 +62,9 @@
     },
     "remark-gfm": {
       "optional": true
+    },
+    "highlight.js": {
+      "optional": true
     }
   }
 }

packages/components/src/code-block.ts

@@ -0,0 +1 @@
+export * from './components/CodeBlock';

packages/components/src/components/CodeBlock/CodeBlock.mdx

@@ -0,0 +1,170 @@
+import {
+  Alert,
+  Meta,
+  Story,
+  Status,
+} from '../../../../../.storybook/components';
+
+import * as Stories from './CodeBlock.stories';
+
+<Meta of={Stories} />
+
+# CodeBlock
+
+<Status variant="experimental" />
+
+`CodeBlock` is a component that displays reformatted text content with syntax highlighting.
+
+<Alert title="Note">
+  For syntax highlighting, the
+  [`highlight.js@^11`](https://github.com/highlightjs/highlight.js/tree/stable-11) peer dependency is required:
+
+```bash
+npm install highlight.js@^11
+```
+
+</Alert>
+
+### Configuring highlight.js
+
+By default, `CodeBlock` lazily loads the full `highlight.js` bundle with all languages (~1 MB). To
+reduce bundle size, wrap the app (or a part of it) with `CodeBlock.HighlightConfigProvider` and specify
+only the languages you need:
+
+```tsx
+const highlightConfig = {
+  core: () => import('highlight.js/lib/core'),
+  languages: {
+    typescript: () => import('highlight.js/lib/languages/typescript'),
+    css: () => import('highlight.js/lib/languages/css'),
+    xml: () => import('highlight.js/lib/languages/xml'),
+  },
+  fallbackLanguage: 'plaintext',
+};
+
+function App() {
+  return (
+    <CodeBlock.HighlightConfigProvider config={highlightConfig}>
+      <CodeBlock files={files} />
+    </CodeBlock.HighlightConfigProvider>
+  );
+}
+```
+
+Languages are loaded lazily on first use. Note that `html` is an alias of `xml` in `highlight.js`, so
+register `xml` to enable HTML syntax highlighting. Pass a stable (module-level or memoized) `config`
+object — `CodeBlock` reuses one shared `highlight.js` instance for the app, keyed by that reference.
+
+See the full list of supported languages in the
+[highlight.js documentation](https://highlightjs.readthedocs.io/en/stable/supported-languages.html).
+
+### Line numbers
+
+Numbering lines is useful for referencing a specific location in the document. Line numbers are
+disabled by default and can be enabled using the `hasLineNumbers` prop.
+
+<Story of={Stories.Overview} />
+
+### Header with title
+
+In the header, use `renderTabLabel` to render a document name or the detected syntax. A shadow appears
+under the header when the code content is scrolled.
+
+<Story of={Stories.HeaderPinned} />
+
+### Changing the block height
+
+The block can expand to fill the available screen area if reviewing the code is one of the main tasks
+in the interface. When screen space is limited or the code only supplements the main content, use
+`maxHeight` to constrain it.
+
+For compactness, use `viewAll` to show a portion of the document with the option to reveal everything.
+The block increases in height so all the code is visible, avoiding double scrolling. The wrap setting
+is preserved when collapsing and expanding the block.
+
+<Story of={Stories.WithMaxHeight} />
+
+### Soft line wrap
+
+By default, lines don't wrap. Pre-configure the mode using `softWrap`, or let users control it with a
+toggle button in the action panel by enabling `canToggleSoftWrap`.
+
+The icon in the button represents the future state after activation and changes after the wrap mode
+is toggled.
+
+<Story of={Stories.WithSoftWrap} />
+
+### Displaying multiple documents
+
+Multiple documents are placed in the block as tabs. The tab title is formed from the `filename` field.
+Tabs can be hidden using `hideTabs`, and the active tab can be set using `activeFileIndex` or
+`defaultActiveFileIndex`.
+
+Tabs are hidden automatically for a single document with an empty `filename`.
+
+<Story of={Stories.WithTabs} />
+
+The tab header is displayed without a shadow by default. If content extends beyond the available area,
+a shadow appears under the header when the code content is scrolled.
+
+<Story of={Stories.WithTabsAndShadow} />
+
+### Visual styling
+
+Two visual styles are available: an outlined block (default), or a filled block with a background that
+contrasts with the page. The filled style prevents the block from getting lost on a screen with varied
+content and is configured using `isFilled`.
+
+<Story of={Stories.WithFilled} />
+
+### Without borders
+
+When the code block should fill an entire container or screen, use `hideBorder` to remove its border.
+
+<Story of={Stories.WithNoBorder} />
+
+### Action panel
+
+The action panel is located in the upper-right corner of the block and remains fixed while scrolling.
+The component configuration determines which actions are available.
+
+The panel is always visible when tabs are shown and on touch devices. When tabs are hidden, it appears
+on hover or focus on other devices. `alwaysShowActionBar` keeps the panel visible regardless of tabs or
+hover and is disabled by default.
+
+```tsx
+<CodeBlock files={files} hideTabs alwaysShowActionBar />
+```
+
+#### Changing wrap mode
+
+The user can toggle the wrap mode using a button. This option is disabled by default and can be enabled
+using `canToggleSoftWrap`.
+
+```tsx
+<CodeBlock files={files} canToggleSoftWrap />
+```
+
+#### Downloading the document
+
+The user can download the document using an action that is disabled by default and can be enabled with
+`canDownload`. The file name and extension are taken from `filename`; when it is empty,
+`fallbackFileName` is used instead (`code` by default).
+
+```tsx
+<CodeBlock files={files} canDownload />
+```
+
+#### Copying the document text
+
+The user can copy the document text by default. Use `hideCopyButton` to hide this action.
+
+```tsx
+<CodeBlock files={files} hideCopyButton />
+```
+
+#### Opening the document in an external system
+
+The address is taken from the `link` field. The link opens in a new tab.
+
+<Story of={Stories.WithLink} />