improved typing

speed-highlight · Jan 5, 2024 · 096ccd6 · 096ccd6
1 parent c2e1baf
commit 096ccd6
Show file tree

Hide file tree

Showing 7 changed files with 61 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -6,10 +6,10 @@ Light, fast, and easy to use, dependencies free javascript syntax highlighter, w
 
 ## Light 📦
 
- * The core is about **1kB** (gzipped & minified)
- * Languages definition are from **a few bytes** to **1kB**
- * Themes are about **1kB**
- * Language rules needed are automatically loaded
+- The core is about **1kB** (gzipped & minified)
+- Languages definition are from **a few bytes** to **1kB**
+- Themes are about **1kB**
+- Language rules needed are automatically loaded
 
 ## Fast ⚡
 
@@ -20,24 +20,28 @@ Blazing fast highlighting using regex
 ### Web
 
 Style/theme (in the header of your html file):
+
 ```html
 <link rel="stylesheet" href="/path/dist/themes/default.css">
 ```
 
 In the body of your html file:
+
 ```html
 <div class='shj-lang-[code-language]'>[code]</div>
 or
 <code class='shj-lang-[code-language]'>[inline code]</code>
 ```
 
 Highlight the code (in your javascript):
+
 ```js
 import { highlightAll } from '/path/dist/index.js'
 highlightAll();
 ```
 
 Auto language detection
+
 ```js
 import { highlightElement } from '../src/index.js';
 import { detectLanguage } from '../src/detect.js';
@@ -47,6 +51,7 @@ highlightElement(elm, detectLanguage(code));
 ```
 
 Load custom language
+
 ```js
 import { loadLanguage } from '../src/index.js';
 
@@ -59,6 +64,7 @@ loadLanguage('language-name', customLanguage);
 <link rel="stylesheet" href="https://unpkg.com/@speed-highlight/core/dist/themes/default.css">
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/speed-highlight/core/dist/themes/default.css">
 ```
+
 ```js
 import ... from 'https://unpkg.com/@speed-highlight/core/dist/index.js'
 import ... from 'https://cdn.jsdelivr.net/gh/speed-highlight/core/dist/index.js'
@@ -95,36 +101,45 @@ printHighlight('console.log("hello")', 'js')
 Speed-highlight JS is a lighter and faster version of prism that share a similar API
 
 ### Style
+
 Remove the prism stylesheet in the head of your html file
 Clone this repository or use a cdn to load our stylesheet
+
 ```diff
 <head>
--	<link href="themes/prism.css" rel="stylesheet" />
-+	<link rel="stylesheet" href="https://unpkg.com/@speed-highlight/core/dist/themes/default.css">
+-  <link href="themes/prism.css" rel="stylesheet" />
++  <link rel="stylesheet" href="https://unpkg.com/@speed-highlight/core/dist/themes/default.css">
 </head>
 ```
 
 ### Script
+
 For the script part remove the prism.js script and replace it by a import and a call to `highlightAll`
+
 ```diff
 <body>
--	<script src="prism.js"></script>
+-  <script src="prism.js"></script>
 +<script>
-+	import { highlightAll } from 'https://unpkg.com/@speed-highlight/core/dist/index.js'
-+	highlightAll()
++  import { highlightAll } from 'https://unpkg.com/@speed-highlight/core/dist/index.js'
++  highlightAll()
 +</script>
 </body>
 ```
+
 If you want to highlight only a specific element you can use the `highlightElement` function instead
 
 ### Code block
+
 For the code blocks replace the `<pre><code>` by only one `<div>`
 And use `shj-lang-` prefix instead of `language-` for the class property
+
 ```diff
 -<pre><code class="language-css">p { color: red }</code></pre>
 +<div class="shj-lang-css">p { color: red }</div>
 ```
+
 And for inline code block you just have to change the class property
+
 ```diff
 -<code class="language-css">p { color: red }</code>
 +<code class="shj-lang-css">p { color: red }</code>

diff --git a/examples/index.html b/examples/index.html
@@ -12,7 +12,17 @@
 			margin: 0 auto
 		}
 		.fira {font: 18px 'Fira Code', monospace !important}
-
+		.shj-multiline.header {padding: 20px;}
+		.shj-multiline.header:before {
+			content: attr(data-lang);
+			color: #58f;
+			display: block;
+			padding: 10px 20px;
+			background: #58f3;
+			border-radius: 5px;
+			margin-bottom: 20px
+		}
+
 		body {margin: 0}
 		html {background: #001220}
 		h1 {
@@ -55,7 +65,7 @@
 <body>
 	<svg viewBox="0 0 900 100" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1"><rect x="0" y="0" width="900" height="100" fill="#001220"></rect><path d="M0 90L21.5 83.2C43 76.3 86 62.7 128.8 54.5C171.7 46.3 214.3 43.7 257.2 45.2C300 46.7 343 52.3 385.8 59.8C428.7 67.3 471.3 76.7 514.2 77.2C557 77.7 600 69.3 642.8 65.7C685.7 62 728.3 63 771.2 61.8C814 60.7 857 57.3 878.5 55.7L900 54L900 0L878.5 0C857 0 814 0 771.2 0C728.3 0 685.7 0 642.8 0C600 0 557 0 514.2 0C471.3 0 428.7 0 385.8 0C343 0 300 0 257.2 0C214.3 0 171.7 0 128.8 0C86 0 43 0 21.5 0L0 0Z" fill="#fa7268"></path><path d="M0 70L21.5 71.7C43 73.3 86 76.7 128.8 73.3C171.7 70 214.3 60 257.2 57C300 54 343 58 385.8 62.2C428.7 66.3 471.3 70.7 514.2 68.3C557 66 600 57 642.8 57.5C685.7 58 728.3 68 771.2 71.7C814 75.3 857 72.7 878.5 71.3L900 70L900 0L878.5 0C857 0 814 0 771.2 0C728.3 0 685.7 0 642.8 0C600 0 557 0 514.2 0C471.3 0 428.7 0 385.8 0C343 0 300 0 257.2 0C214.3 0 171.7 0 128.8 0C86 0 43 0 21.5 0L0 0Z" fill="#f16367"></path><path d="M0 33L21.5 34.3C43 35.7 86 38.3 128.8 43.2C171.7 48 214.3 55 257.2 55.7C300 56.3 343 50.7 385.8 44.5C428.7 38.3 471.3 31.7 514.2 32.7C557 33.7 600 42.3 642.8 48.2C685.7 54 728.3 57 771.2 59.3C814 61.7 857 63.3 878.5 64.2L900 65L900 0L878.5 0C857 0 814 0 771.2 0C728.3 0 685.7 0 642.8 0C600 0 557 0 514.2 0C471.3 0 428.7 0 385.8 0C343 0 300 0 257.2 0C214.3 0 171.7 0 128.8 0C86 0 43 0 21.5 0L0 0Z" fill="#e85467"></path><path d="M0 52L21.5 47.7C43 43.3 86 34.7 128.8 30.5C171.7 26.3 214.3 26.7 257.2 29.2C300 31.7 343 36.3 385.8 40.5C428.7 44.7 471.3 48.3 514.2 46.8C557 45.3 600 38.7 642.8 38C685.7 37.3 728.3 42.7 771.2 45.3C814 48 857 48 878.5 48L900 48L900 0L878.5 0C857 0 814 0 771.2 0C728.3 0 685.7 0 642.8 0C600 0 557 0 514.2 0C471.3 0 428.7 0 385.8 0C343 0 300 0 257.2 0C214.3 0 171.7 0 128.8 0C86 0 43 0 21.5 0L0 0Z" fill="#de4467"></path><path d="M0 31L21.5 29.8C43 28.7 86 26.3 128.8 27.7C171.7 29 214.3 34 257.2 34.3C300 34.7 343 30.3 385.8 27.2C428.7 24 471.3 22 514.2 19.2C557 16.3 600 12.7 642.8 15.5C685.7 18.3 728.3 27.7 771.2 27.8C814 28 857 19 878.5 14.5L900 10L900 0L878.5 0C857 0 814 0 771.2 0C728.3 0 685.7 0 642.8 0C600 0 557 0 514.2 0C471.3 0 428.7 0 385.8 0C343 0 300 0 257.2 0C214.3 0 171.7 0 128.8 0C86 0 43 0 21.5 0L0 0Z" fill="#d23467"></path><path d="M0 24L21.5 22.5C43 21 86 18 128.8 17.2C171.7 16.3 214.3 17.7 257.2 17.8C300 18 343 17 385.8 15.5C428.7 14 471.3 12 514.2 12.2C557 12.3 600 14.7 642.8 14.2C685.7 13.7 728.3 10.3 771.2 10.3C814 10.3 857 13.7 878.5 15.3L900 17L900 0L878.5 0C857 0 814 0 771.2 0C728.3 0 685.7 0 642.8 0C600 0 557 0 514.2 0C471.3 0 428.7 0 385.8 0C343 0 300 0 257.2 0C214.3 0 171.7 0 128.8 0C86 0 43 0 21.5 0L0 0Z" fill="#c62368"></path></svg>
 	<main><h1>Speed-highlight JS</h1></main>
-	
+
 	<script type="module">
 		import { highlightElement } from '../src/index.js'
 		import { detectLanguage } from '../src/detect.js'
@@ -108,7 +118,7 @@
 
 		new Radio('theme', theme => stylesheet.href = `../src/themes/${theme}.css`, themesBrowser)
 		new Checkbox('detect language', on => { detect = on; highlight(lang.selected) }, container)
-		new Checkbox('header mode', mode => code.classList.toggle('shj-mode-header', mode), container)
+		new Checkbox('header mode', mode => code.classList.toggle('header', mode), container)
 		new Checkbox('use fira font', use => code.classList.toggle('fira', use), container).on = true
 		new Checkbox('hide line numbering', ln => { hideLineNumbers = ln; highlight(lang.selected) }, container).on = true
 

diff --git a/examples/worker.html b/examples/worker.html
@@ -7,7 +7,7 @@
 	<link rel="stylesheet" href="../src/themes/atom-dark.css">
 </head>
 <body>
-	<div class="shj-lang-js shj-multiline shj-mode-noheader" id="code">this.code = 'highlighted on a web worker';
+	<div class="shj-lang-js shj-multiline" id="code">this.code = 'highlighted on a web worker';
 this.isAwesome = new Boolean(.5);</div>
 	<script type="module">
 		const code = document.querySelector('#code');

diff --git a/src/detect.js b/src/detect.js
@@ -41,7 +41,7 @@ const languages = [
  * Try to find the language the given code belong to
  *
  * @function detectLanguage
- * @param {String} code The code
+ * @param {string} code The code
  * @returns {ShjLanguage} The language of the code
  */
 export const detectLanguage = code => {

diff --git a/src/index.js b/src/index.js
@@ -40,7 +40,7 @@ const langs = {},
 	 *
 	 * @function
 	 * @ignore
-	 * @param {String} str The content (need to be sanitized)
+	 * @param {string} str The content (need to be sanitized)
 	 * @param {ShjToken} [token] The type of token
 	 * @returns A HMTL string
 	 */
@@ -50,9 +50,9 @@ const langs = {},
  * Find the tokens in the given code and call the given callback
  *
  * @function tokenize
- * @param {String} src The code
+ * @param {string} src The code
  * @param {ShjLanguage|Array} lang The language of the code
- * @param {function(String, ShjToken=):void} token The callback function
+ * @param {function(string, ShjToken=):void} token The callback function
  * this function will be given
  * * the text of the token
  * * the type of the token
@@ -118,11 +118,11 @@ export async function tokenize(src, lang, token) {
  *
  * @async
  * @function highlightText
- * @param {String} src The code
+ * @param {string} src The code
  * @param {ShjLanguage} lang The language of the code
  * @param {Boolean} [multiline=true] If it is multiline, it will add a wrapper for the line numbering and header
  * @param {ShjOptions} [opt={}] Customization options
- * @returns {Promise<String>} The highlighted string
+ * @returns {Promise<string>} The highlighted string
  */
 export async function highlightText(src, lang, multiline = true, opt = {}) {
 	let tmp = ''
@@ -147,7 +147,7 @@ export async function highlightElement(elm, lang = elm.className.match(/shj-lang
 	let txt = elm.textContent;
 	mode ??= `${elm.tagName == 'CODE' ? 'in' : (txt.split('\n').length < 2 ? 'one' : 'multi')}line`;
 	elm.dataset.lang = lang;
-	elm.className = `${[...elm.classList].filter(className => !className.startsWith('shj-') || className.startsWith('shj-mode-')).join(' ')} shj-lang-${lang} shj-${mode}`;
+	elm.className = `${[...elm.classList].filter(className => !className.startsWith('shj-')).join(' ')} shj-lang-${lang} shj-${mode}`;
 	elm.innerHTML = await highlightText(txt, lang, mode == 'multiline', opt);
 }
 
@@ -163,12 +163,23 @@ export let highlightAll = async (opt) =>
 		.querySelectorAll('[class*="shj-lang-"]')
 		.forEach(elm => highlightElement(elm, undefined, undefined, opt))
 
+/**
+ * @typedef {{ match: RegExp, type: string }
+ *   | { match: RegExp, sub: string | ShjLanguageDefinition | (code:string) => ShjLanguageComponent }
+ *   | { expand: string }
+ * } ShjLanguageComponent
+ */
+
+/**
+ * @typedef {ShjLanguageComponent[]} ShjLanguageDefinition
+ */
+
 /**
  * Load a language and add it to the langs object
  *
  * @function loadLanguage
- * @param {String} languageName The name of the language
- * @param {ShjLanguage} language The language
+ * @param {string} languageName The name of the language
+ * @param {{ default: ShjLanguageDefinition }} language The language
  */
 export let loadLanguage = (languageName, language) => {
 	langs[languageName] = language;

diff --git a/src/terminal.js b/src/terminal.js
@@ -21,9 +21,9 @@ let theme = import('./themes/default.js');
  *
  * @async
  * @function highlightText
- * @param {String} src The code
+ * @param {string} src The code
  * @param {ShjLanguage} lang The language of the code
- * @returns {Promise<String>} The highlighted string
+ * @returns {Promise<string>} The highlighted string
  */
 export const highlightText = async (src, lang) => {
 	let res = '', themeMap = (await theme).default;
@@ -38,7 +38,7 @@ export const highlightText = async (src, lang) => {
  *
  * @async
  * @function printHighlight
- * @param {String} src The code
+ * @param {string} src The code
  * @param {ShjLanguage} lang The language of the code
  */
 export const printHighlight = async (src, lang) => console.log(await highlightText(src, lang));

diff --git a/src/themes/default.css b/src/themes/default.css
@@ -69,14 +69,3 @@
 	padding: 5px 7px;
 	border-radius: 5px
 }
-
-.shj-multiline.shj-mode-header {padding: 20px;}
-.shj-multiline.shj-mode-header:before {
-	content: attr(data-lang);
-	color: #58f;
-	display: block;
-	padding: 10px 20px;
-	background: #58f3;
-	border-radius: 5px;
-	margin-bottom: 20px
-}