Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/heppokofrontend/html-code-block-element
This is a code block generator with syntax highlighting and copy button.
https://github.com/heppokofrontend/html-code-block-element
code-highlight code-highlighter custom-elements syntax-highlighting web-component
Last synced: 8 days ago
JSON representation
This is a code block generator with syntax highlighting and copy button.
- Host: GitHub
- URL: https://github.com/heppokofrontend/html-code-block-element
- Owner: heppokofrontend
- License: mit
- Created: 2021-07-29T18:51:53.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-21T12:59:34.000Z (over 1 year ago)
- Last Synced: 2023-05-21T13:35:52.244Z (over 1 year ago)
- Topics: code-highlight, code-highlighter, custom-elements, syntax-highlighting, web-component
- Language: TypeScript
- Homepage:
- Size: 1.68 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# <code-block>
[](LICENSE) [](https://www.npmjs.com/package/@heppokofrontend/html-code-block-element) [](https://www.webcomponents.org/element/heppokofrontend/html-code-block-element) [](https://www.jsdelivr.com/package/npm/@heppokofrontend/html-code-block-element) [](https://codeclimate.com/github/heppokofrontend/html-code-block-element/maintainability) [](https://codeclimate.com/github/heppokofrontend/html-code-block-element/test_coverage) [](https://snyk.io/test/npm/@heppokofrontend/html-code-block-element)
[](https://snyk.io/advisor/npm-package/@heppokofrontend/html-code-block-element)
Code block custom element with syntax highlighting and copy button.
It has [highlight.js](https://www.npmjs.com/package/highlight.js?activeTab=readme) for syntax highlighting.
## Usage
DEMO:
```html
<script>console.log(true);</script>
```
### In browser
It can be used by loading html-code-block-element.common.min.js and one CSS theme.
The highlight.js style is available on CDN. You can also download the JS and CSS from the respective repositories and load them into your page.
```html
```
There are three versions of this library available.
- `html-code-block-element.common.min.js` - One that supports only the popular languages.
- `html-code-block-element.all.min.js` - One that enables [all languages](https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md) supported by highligh.js.
- `html-code-block-element.core.min.js` - For developers who want to do their own `hljs.registerLanguage()`.
#### Example
**Note:** The textarea element cannot be included in the content of the textarea element. If you want to include it, please use HTML Entity for the tag.
```html
console.log(true);
```
or
```html
<script>console.log(true);</script>
```
#### Assumption specifications
- **Categories:**
- [Flow content](https://html.spec.whatwg.org/multipage/dom.html#flow-content-2).
- [Palpable content](https://html.spec.whatwg.org/multipage/dom.html#palpable-content-2).
- **Contexts in which this element can be used:**
- Where flow content is expected.
- **Content model:**
- [Text](https://html.spec.whatwg.org/multipage/dom.html#text-content) or one [textarea](https://html.spec.whatwg.org/multipage/form-elements.html#the-textarea-element) element
- **Tag omission in text/html:**
- Neither tag is omissible.
- **Content attributes:**
- [Global attributes](https://html.spec.whatwg.org/multipage/dom.html#global-attributes)
- `controls` - Show controls
- `notrim` - Does't remove whitespace from both ends of a source
- `label` - Give the code block a unique name. If omitted, it will always have the accessible name "Code Block".
- `language` - Language name of the code. If omitted, it will be detected automatically.
- **Accessibility considerations:**
- [No corresponding role](https://w3c.github.io/html-aria/#dfn-no-corresponding-role)
- `role` attribute is not allowed
- `aria-*` attribute is not allowed
#### DOM interface
```java
[Exposed=Window]
interface HTMLCodeBlockElement : HTMLElement {
[HTMLConstructor] constructor();
[CEReactions] attribute boolean controls;
[CEReactions] attribute boolean notrim;
[CEReactions] attribute DOMString label;
[CEReactions] attribute DOMString language;
[CEReactions] attribute DOMString value;
};
```
### In development
#### Installation:
```shell
npm install --save @heppokofrontend/html-code-block-element
```
#### Usage:
The `customElements.define()` will also be included.
```javascript
// For highlighting, `highlight.js/lib/common` will be used.
import '@heppokofrontend/html-code-block-element';
// For highlighting, `highlight.js` will be used.
import '@heppokofrontend/html-code-block-element/dist/index.all';
// For highlighting, `highlight.js/lib/code` will be used.
import '@heppokofrontend/html-code-block-element/dist/index.core';
```
If you are using purely constructors:
```javascript
import HTMLCodeBlockElement from '@heppokofrontend/html-code-block-element/dist/class/HTMLCodeBlockElement';
```
#### Use in React
This package contains the global type files for React.
- `React.CodeBlockHTMLAttributes`
- `code-block` in `JSX.IntrinsicElements`
\* CSS needs to be loaded separately.
```tsx
// CodeBlock.tsx
import {CodeBlockProps} from '@heppokofrontend/html-code-block-element/dist/manual';
import styleSheet from '@heppokofrontend/html-code-block-element/dist/styleSheet';
import hljs from 'highlight.js/lib/common';
import Head from 'next/head';
import {useEffect} from 'react';
declare module 'react' {
// A type for the properties of a function component
interface CodeBlockHTMLAttributes extends HTMLAttributes {
/** The accessible name of code block */
label?: string | undefined;
/** The Language name */
language?: string | undefined;
/** The flag to display the UI */
controls?: boolean;
}
}
declare global {
// A type for JSX markup
namespace JSX {
interface IntrinsicElements {
'code-block': CodeBlockProps;
}
}
}
type Props = Omit, 'className'>;
let isLoaded = false;
export const CodeBlock = ({children, ...props}: Props) => {
useEffect(() => {
const loadWebComponent = async () => {
const {HTMLCodeBlockElement, createHighlightCallback} = await import(
'@heppokofrontend/html-code-block-element/dist/manual'
);
HTMLCodeBlockElement.highlight = createHighlightCallback(hljs);
customElements.define('code-block', HTMLCodeBlockElement);
};
if (!isLoaded) {
isLoaded = true;
loadWebComponent();
}
}, []);
return (
<>
{styleSheet}
{children}
>
);
};
```
#### Use as constructor
Manual setup:
```js
// 1. Import
import hljs from 'highlight.js/lib/core';
import javascript from 'highlight.js/lib/languages/javascript';
import HTMLCodeBlockElement from '@heppokofrontend/html-code-block-element/dist/class/HTMLCodeBlockElement';
// or import { HTMLCodeBlockElement } from '@heppokofrontend/html-code-block-element';
// Support JavaScript
hljs.registerLanguage('javascript', javascript);
// 2. Set endgine
/**
* Example: Callback to be called internally
* @param {string} src - Source code string for highlight
* @param {{ language: string }} options - Option for highlight
* @returns {{ markup: string }} - Object of the highlight result
*/
HTMLCodeBlockElement.highlight = function (src, options) {
if (
// Verifying the existence of a language
options?.language &&
hljs.getLanguage(options.language)
) {
const {value} = hljs.highlight(src, options);
return {
markup: value,
};
}
return {
markup: hljs.highlightAuto(src).value,
};
};
// 3. Define
customElements.define('code-block', HTMLCodeBlockElement);
// 4. Make
const cbElm = new HTMLCodeBlockElement();
// 5. Assign
cbElm.language = 'javascript';
cbElm.label = 'your label';
cbElm.value = `const hoge = true;
console.log(hoge);`;
// 6. Append
document.body.append(cbElm); // Render at the same time
```
##### Syntax
No params.
```js
new HTMLCodeBlockElement();
```
## Support browser
- Chrome
- Safari
- Firefox
- Edge