Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/t-ski/html-sourcecode-element
Rich HTML source code element with a native API. Try yourself: https://jsfiddle.net/uy17badq
https://github.com/t-ski/html-sourcecode-element
code-editor code-element code-snippets html native-api
Last synced: about 10 hours ago
JSON representation
Rich HTML source code element with a native API. Try yourself: https://jsfiddle.net/uy17badq
- Host: GitHub
- URL: https://github.com/t-ski/html-sourcecode-element
- Owner: t-ski
- License: mit
- Created: 2022-07-30T21:31:54.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-07-03T20:58:40.000Z (5 months ago)
- Last Synced: 2024-10-06T09:23:12.806Z (about 1 month ago)
- Topics: code-editor, code-element, code-snippets, html, native-api
- Language: JavaScript
- Homepage: https://gist.github.com/t-ski/13ffeede61ee5a9229cececf9f36c138
- Size: 25.8 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HTMLSourceCodeElement
 
 
Rich HTML code element with a native API.
[1. Integration](#%EF%B8%8F-integration)
[2. Attributes](#%EF%B8%8F-attributes)
[2.1 `copy`](#copy)
[2.2 `edit`](#edit)
[2.3 `type`](#type)
[2.4 `language`](#language)
[2.5 `scroll`](#scroll)
[3. Themes](#%EF%B8%8F-themes)
[3.1 `min`](#min)
[3.2 `common`](#common)
[3.3 `outline`](#outline)
[4. Syntax Highlighting](#-syntax-highlighting)
[4.1 `glitch`](#glitch)
[4.2 `matrix`](#matrix)
[4.3 `reef`](#reef)
## ⬇️ Integration
#### via CDN
`recommended`
``` html
```
- `` is a placeholder for an element theme identifier ([browse Themes](#%EF%B8%8F-themes)).
- `` specifies an optional syntax highlighting scheme ([browse Highlighting](#-syntax-highlighting)).
#### via NPM
``` console
npm i @t-ski/html-sourcecode-element
```
``` ts
default function(theme: string = "min", highlighting?: string);
```
``` js
import HTMLSourceCodeElement from "@t-ski/html-sourcecode-element";
HTMLSourceCodeElement("common", "glitch");
```
> ⚠️ Integration via NPM serves ECMAScript module type bundlers.
#### Usage
``` html
print('Hello, world!')
`
```
> ℹ️ Anything slotted within the `` is interpreted as code contents. HTML code does in particular not have to be escaped – except for script tags.
## ☑️ Attributes
#### `copy`
``` html
```
Make element copyable by hover activated button.
#### `edit`
``` html
```
Make element editable like a script editor.
#### `scroll`
``` html
```
Make element scrollable at horizontal overflow, instead of wrap.
#### `type`
``` html
```
Make element as if a human would type the code.
#### `language`
``` html
```
Specify language to help with highlighting (if necessary).
#### `maxheight`
``` html
```
Specify maximum amount of lines after which to enable vertical scroll.
> ℹ️ A minimum of `5` lines are shown when used with `type`.
---
### 💻 Attributes API
The DOM class `HTMLSourceCodeElement` is associated with the `` tag. The DOM class provides a static configuration function to override certain attributes globally.
``` ts
HTMLSourceCodeElement
.globalAttrs(attrs: { [name: string]: boolean; });
```
``` js
HTMLSourceCodeElement
.globalAttrs({
copy: true,
edit: false
});
```
> ℹ️ A global attributes configuration does not invert, but override individual attributes.
## 🖼️ Themes
#### `min`
``` html
```
Minimal editor theme.
<div>
<a href="#themes"><img src="./readme/light.min.png" width="400"></a>
 
<a href="#themes"><img src="./readme/dark.min.png" width="400"></a>
<br><br>
</div>
#### `common`
``` html
<script src="…/HTMLSourceCodeElement.common[.<syntax>].js">
```
<div>
<a href="#themes"><img src="./readme/light.common.png" width="400"></a>
 
<a href="#themes"><img src="./readme/dark.common.png" width="400"></a>
<br><br>
</div>
#### `outline`
``` html
<script src="…/HTMLSourceCodeElement.outline[.<syntax>].js">
```
<div>
<a href="#themes"><img src="./readme/light.outline.png" width="400"></a>
 
<a href="#themes"><img src="./readme/dark.outline.png" width="400"></a>
<br><br>
</div>
#### `opaque`
``` html
<script src="…/HTMLSourceCodeElement.opaque[.<syntax>].js">
```
<div>
<a href="#themes"><img src="./readme/light.opaque.png" width="400"></a>
 
<a href="#themes"><img src="./readme/dark.opaque.png" width="400"></a>
<br><br>
</div>
---
### 💻 Theme API
Using the `addStylesheet()` method, custom styles can be injected into the `<source-code>` shadow DOM. The method exists both statically on `HTMLSourceCodeElement`, as well as on each individual instance. The method must be passed a URL to a stylesheet. Alternatively, an existing `<link>` or `<style>` element can be reused through a reference.
``` ts
(HTMLSourceCodeElement|instanceof HTMLSourceCodeElement)
.addStylesheet(stylesheet: HTMLStyleElement|HTMLLinkElement|string);
```
In a stylesheet, the `:host` selector refers to the encompassing `<source-code>`. The internals of the shadow DOM base on the following markup:
``` html
<div class="edit"></div>
<code class="display">
<table>
<tr class="line" *>
<td class="line-number">
<span>
<!-- Individual line number -->
</span>
</td>
<td class="line-code">
<pre mirror>
<!-- Individual line code -->
</pre>
</td>
</tr>
</table>
</code>
<button type="button" class="copy">Copy</span>
```
#### Color Scheme
Themes adopt the colour scheme preferred by the user. Manually adjustable color schemes, however, can use the static `setColorScheme()` method. This way, a specific color scheme can be enforced globally.
``` ts
HTMLSourceCodeElement.setColorScheme("light" | "dark" | "auto");
```
## 🎨 Syntax Highlighting
Syntax highlighting is an optional addition to the basic API. In fact, it requires [highlight.js](https://highlightjs.org/) to work:
``` html
<head>
<script src="https://unpkg.com/@highlightjs/cdn-assets/highlight.min.js">
document.addEventListener("DOMContentLoaded", () => {
HTMLSourceCodeElement.on("highlight", (code, language) => {
return language
? hljs.highlight(code, { language }).value
: hljs.highlightAuto(code).value);
});
});
```
#### `glitch`
``` html
```
<div>
<a href="#themes"><img src="./readme/light.glitch.png" width="400"></a>
 
<a href="#themes"><img src="./readme/dark.glitch.png" width="400"></a>
</div>
#### `matrix`
``` html
<script src="…/HTMLSourceCodeElement.<theme>.matrix.js">
```
<div>
<a href="#themes"><img src="./readme/light.matrix.png" width="400"></a>
 
<a href="#themes"><img src="./readme/dark.matrix.png" width="400"></a>
</div>
#### `reef`
``` html
<script src="…/HTMLSourceCodeElement.<theme>.reef.js">
```
<div>
<a href="#themes"><img src="./readme/light.reef.png" width="400"></a>
 
<a href="#themes"><img src="./readme/dark.reef.png" width="400"></a>
</div>
---
### 💻 Config API
The `HTMLSourceCodeElement` provides reasonable commons for abstract visual or behavioural aspects. For instance, the tab width is two spaces by common. However, such aspects can be manipulated in a fashion similar to defining global attributes.
``` ts
HTMLSourceCodeElement
.config(overrides: { [name: string]: unknown; });
```
``` js
HTMLSourceCodeElement
.config({
tabWidth: 4
});
```
### 💻 Events API
The `HTMLSourceCodeElement` DOM class provides a static API to handle events in a custom fashion.
``` ts
HTMLSourceCodeElement
.on(event: string, cb: (...args: unknown[]) => unknown)
```
#### on `copy`
``` ts
HTMLSourceCodeElement.on("copy", (dom: {
host: HTMLSourceCodeElement;
edit: HTMLDivElement;
display: HTMLSourceCodeElement;
table: HTMLTableElement;
copy: HTMLButtonElement;
}) => void)
```
Callback fires whenever code is copied. The callback is passed the respective element's shadow DOM key elements. The DOM might be used to to reflect that the code was in fact copied.
#### on `highlight`
``` ts
HTMLSourceCodeElement.on("highlight", cb: (code: string, language?: string) => string)
```
Callback fires whenever code is rendered. The callback is passed the respective raw code to highlight. If the respective element has an assigned `language` attribute that value is also passed.
##
<sub>© Thassilo Martin Schiepanski</sub>