feat: SyntaxHighlightElement.config getter/setter

- Configure the custom element via config setter
- Expose configuration object

Author: andreruffert

index.html

@@ -30,6 +30,7 @@
       }
     </style>
     <script>
+      // Global namespace config
       window.she = window.she || {};
       window.she.config = {
         // Define languages to support
@@ -92,16 +93,35 @@
 
     <script type="module">
       /**
-       * Option 1. autoload - default
+       * Option 1. autoload - default with global namespace config
        */
       import '/src/index.js'
 
       /**
-       * Option 2.a. Opt out of prism autoload by manually importing prism core
+       * Option 2. configure with `SyntaxHighlightElement.config` and `?define=false` import query param
+       */
+      // import { SyntaxHighlightElement } from '/src/index.js?define=false';
+      // SyntaxHighlightElement.config = {
+      //   // Define languages to support
+      //   languages: ['html', 'css', 'js', 'jsx', 'md'],
+      //   // Language specific token type overwrites
+      //   languageTokens: {
+      //     css: ['important'],
+      //     md: ['title', 'list'],
+      //   },
+      //   // Customize setup/tokenize methods
+      //   // async setup() {},
+      //   // tokenize: () => [],
+      // };
+      // SyntaxHighlightElement.define();
+
+      /**
+       * Option 3.a. Opt out of prism autoload by manually importing prism core
        */
        // import 'prismjs/components/prism-core'
+
       /**
-       * Option 2.b. Load lang deps manually (without dependency resolution)
+       * Option 3.b. Load lang deps manually (without dependency resolution)
        */
       // import 'prismjs/components/prism-markup'
       // import 'prismjs/components/prism-css'

src/config.js

@@ -1,37 +1,23 @@
-import { NAMESPACE } from './constants';
-import { loadPrismCore, loadPrismLanguage, tokenize, tokenTypes } from './tokenizer/prism';
+import { setup, tokenize, tokenTypes } from './tokenizer/prism';
 
 /**
  * @typedef Config
  * @type {object}
- * @property {string[]} languages - Syntax language grammars to autoload.
- * @property {string[]} tokenTypes - Language token types.
- * @property {{[key: string]: string[]}} languageTokens - Language specific token types.
+ * @property {string[]} languages - List of languages to support for syntax highlighting.
+ * @property {string[]} tokenTypes - Token types used during lexing/parsing.
+ * @property {{[key: string]: string[]}} languageTokens - Mapping of language names to their specific tokenization rules.
  * @property {function} setup - Runs before the custom element gets defined in the registry.
- * @property {function} tokenize - Used to tokenize the text.
+ * @property {function} tokenize - Tokenize text based on the specified language grammar
  */
 
-/** @type {Config} */
-export const config = Object.assign(
-  {
-    languages: ['markup', 'css', 'javascript'],
-    tokenTypes,
-    languageTokens: {},
-    async setup() {
-      try {
-        if (!window.Prism) {
-          const prismBaseUrl = 'https://cdn.jsdelivr.net/npm/prismjs@1.30.0';
-          await loadPrismCore(prismBaseUrl);
-          await loadPrismLanguage({
-            baseUrl: prismBaseUrl,
-            language: config.languages,
-          });
-        }
-      } catch (error) {
-        console.error(error);
-      }
-    },
-    tokenize,
-  },
-  window[NAMESPACE]?.config || {},
-);
+/**
+ * Default configuration object.
+ * @type {Config}
+ */
+export const configDefaults = {
+  languages: ['markup', 'css', 'javascript'],
+  tokenTypes,
+  languageTokens: {},
+  setup,
+  tokenize,
+};

src/index.js

@@ -1,5 +1,5 @@
 import { NAMESPACE } from './constants';
-import { SyntaxHighlightElement } from './syntax-highlight-element';
+import SyntaxHighlightElement from './syntax-highlight-element';
 import { setupTokenHighlights } from './utils';
 
 export { SyntaxHighlightElement, setupTokenHighlights };

src/syntax-highlight-element.js

@@ -1,21 +1,50 @@
-import { config } from './config';
+/** @import { Config } from './config.js' */
+
+import { configDefaults } from './config';
+import { NAMESPACE } from './constants';
 import { setupTokenHighlights } from './utils';
 
-export class SyntaxHighlightElement extends HTMLElement {
+export default class Component extends HTMLElement {
   static async define(tagName = 'syntax-highlight', registry = customElements) {
     if (!CSS.highlights) {
       console.info('The CSS Custom Highlight API is not supported in this browser.');
       return;
     }
 
     if (!registry.get(tagName)) {
-      typeof config?.setup === 'function' && (await config.setup());
-      setupTokenHighlights(config.tokenTypes, { languageTokens: config.languageTokens });
-      registry.define(tagName, SyntaxHighlightElement);
-      return SyntaxHighlightElement;
+      // Setup custom element
+      typeof Component.#config?.setup === 'function' && (await Component.#config.setup());
+      setupTokenHighlights(Component.#config.tokenTypes, {
+        languageTokens: Component.#config.languageTokens,
+      });
+      registry.define(tagName, Component);
+      return Component;
     }
   }
 
+  /**
+   * Configuration object with default values.
+   * Merge defaults with global namespace config.
+   * @type {Config}
+   * */
+  static #config = Object.assign(configDefaults, window[NAMESPACE]?.config || {});
+
+  /**
+   * Configuration object
+   * @type {Config}
+   */
+  static get config() {
+    return Component.#config;
+  }
+
+  /**
+   * Modify configuration object
+   * @param {Config} properties
+   */
+  static set config(properties) {
+    Component.#config = Object.assign(Component.#config, properties);
+  }
+
   #internals;
   #highlights = new Set();
 
@@ -56,8 +85,8 @@ export class SyntaxHighlightElement extends HTMLElement {
    */
   paintTokenHighlights() {
     // Tokenize the text
-    const tokens = config.tokenize(this.contentElement.innerText, this.language) || [];
-    const languageTokenTypes = config.languageTokens?.[this.language] || [];
+    const tokens = Component.#config.tokenize(this.contentElement.innerText, this.language) || [];
+    const languageTokenTypes = Component.#config.languageTokens?.[this.language] || [];
 
     // Paint highlights
     let pos = 0;

src/tokenizer/prism.js

@@ -1,11 +1,40 @@
 /**
+ * Asynchronously sets up the Prism tokenizer if not already available.
+ * Runs before the custom element gets defined in the registry.
  *
- * @param {string} text - The text to tokenize.
- * @param {string} language - The syntax language grammar.
- * @returns {Array} - An array of flattened prismjs tokens.
+ * Loads Prism core and specified language grammars from a CDN.
+ * Safe to call multiple times; will only load once.
+ *
+ * @async
+ * @function setup
+ * @returns {Promise<void>} Resolves when Prism and required languages are loaded, or rejects on network/error.
+ * @throws {Error} Logs errors to console if loading fails.
+ */
+export async function setup() {
+  try {
+    if (!window.Prism) {
+      const prismBaseUrl = 'https://cdn.jsdelivr.net/npm/prismjs@1.30.0';
+      await loadPrismCore(prismBaseUrl);
+      await loadPrismLanguage({
+        baseUrl: prismBaseUrl,
+        language: SyntaxHighlightElement.config.languages,
+      });
+    }
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+/**
+ * Tokenizes a given text using Prism.js based on the specified language grammar.
+ *
+ * @function tokenize
+ * @param {string} text - The text string to tokenize.
+ * @param {string} language - The language name associated with the code.
+ * @returns {Array<Object>} A flat array of prismjs tokens representing the tokenized code.
  */
 export function tokenize(text, language) {
-  const lang = window.Prism.languages[language] || undefined;
+  const lang = window.Prism?.languages[language] || undefined;
   if (!lang) {
     console.warn(`window.Prism.languages.${language} is undefined.`);
     return [];