@kubex/zinc 0.0.2 → 1.0.0

package/docs/_utilities/cem.cjs

@@ -0,0 +1,89 @@
+const customElementsManifest = require('../../dist/custom-elements.json');
+
+//
+// Export it here so we can import it elsewhere and use the same version
+//
+module.exports.customElementsManifest = customElementsManifest;
+
+//
+// Gets all components from custom-elements.json and returns them in a more documentation-friendly format.
+//
+module.exports.getAllComponents = function ()
+{
+  const allComponents = [];
+
+  customElementsManifest.modules?.forEach(module =>
+  {
+    module.declarations?.forEach(declaration =>
+    {
+      if(declaration.customElement)
+      {
+        // Generate the dist path based on the src path and attach it to the component
+        declaration.path = module.path.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
+
+        // Remove members that are private or don't have a description
+        const members = declaration.members?.filter(member => member.description && member.privacy !== 'private');
+        const methods = members?.filter(prop => prop.kind === 'method' && prop.privacy !== 'private');
+        const properties = members?.filter(prop =>
+        {
+          // Look for a corresponding attribute
+          const attribute = declaration.attributes?.find(attr => attr.fieldName === prop.name);
+          if(attribute)
+          {
+            prop.attribute = attribute.name || attribute.fieldName;
+          }
+
+          return prop.kind === 'field' && prop.privacy !== 'private';
+        });
+        allComponents.push({
+          ...declaration,
+          methods,
+          properties
+        });
+      }
+    });
+  });
+
+  // Build dependency graphs
+  allComponents.forEach(component =>
+  {
+    const dependencies = [];
+
+    // Recursively fetch sub-dependencies
+    function getDependencies(tag)
+    {
+      const cmp = allComponents.find(c => c.tagName === tag);
+      if(!cmp || !Array.isArray(component.dependencies))
+      {
+        return;
+      }
+
+      cmp.dependencies?.forEach(dependentTag =>
+      {
+        if(!dependencies.includes(dependentTag))
+        {
+          dependencies.push(dependentTag);
+        }
+        getDependencies(dependentTag);
+      });
+    }
+
+    getDependencies(component.tagName);
+
+    component.dependencies = dependencies.sort();
+  });
+
+  // Sort by name
+  return allComponents.sort((a, b) =>
+  {
+    if(a.name < b.name)
+    {
+      return -1;
+    }
+    if(a.name > b.name)
+    {
+      return 1;
+    }
+    return 0;
+  });
+};

package/docs/_utilities/code-previews.cjs

@@ -0,0 +1,98 @@
+let count = 1;
+
+function escapeHtml(str)
+{
+  return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/**
+ * Turns code fields with the :preview suffix into interactive code previews.
+ */
+module.exports = function (doc, options)
+{
+  options = {
+    within: 'body', // the element containing the code fields to convert
+    ...options
+  };
+
+  const within = doc.querySelector(options.within);
+  if(!within)
+  {
+    return doc;
+  }
+
+  within.querySelectorAll('[class*=":preview"]').forEach(code =>
+  {
+    const pre = code.closest('pre');
+    if(!pre)
+    {
+      return;
+    }
+    const adjacentPre = pre.nextElementSibling?.tagName.toLowerCase() === 'pre' ? pre.nextElementSibling : null;
+    const sourceGroupId = `code-preview-source-group-${count}`;
+    const isExpanded = code.getAttribute('class').includes(':expanded');
+
+    count++;
+
+    const codePreview = `
+      <div class="code-preview ${isExpanded ? 'code-preview--expanded' : ''}">
+        <div class="code-preview__preview">
+          ${code.textContent}
+          <div class="code-preview__resizer">
+            <zn-icon src="drag_indicator"></zn-icon>
+          </div>
+        </div>
+
+        <div class="code-preview__source-group" id="${sourceGroupId}">
+          <div class="code-preview__source code-preview__source--html">
+            <pre><code class="language-html">${escapeHtml(code.textContent)}</code></pre>
+          </div>
+        </div>
+
+        <div class="code-preview__buttons">
+          <button
+            type="button"
+            class="code-preview__button code-preview__toggle"
+            aria-expanded="${isExpanded ? 'true' : 'false'}"
+            aria-controls="${sourceGroupId}">
+            Source
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round">
+              <polyline points="6 9 12 15 18 9"></polyline>
+            </svg>
+          </button>
+        </div>
+      </div>
+    `;
+
+    pre.insertAdjacentHTML('afterend', codePreview);
+    pre.remove();
+
+    if(adjacentPre)
+    {
+      adjacentPre.remove();
+    }
+  });
+
+  // Wrap code preview scripts in anonymous helpers so they don't run in the global scope
+  doc.querySelectorAll('.code-preview__preview script').forEach(script =>
+  {
+    if(script.type === 'module')
+    {
+      // Modules are already scoped
+      script.textContent = script.innerHTML;
+    }
+    else
+    {
+      // Wrap non-modules in an anonymous function so they don't run in the global scope
+      script.textContent = `(() => { ${script.innerHTML} })();`;
+    }
+  });
+
+  return doc;
+};

package/docs/_utilities/copy-code-buttons.cjs

@@ -0,0 +1,26 @@
+let codeBlockId = 0;
+
+/**
+ * Adds copy code buttons to code fields. The provided doc should be a document object provided by JSDOM. The same
+ * document will be returned with the appropriate DOM manipulations.
+ */
+module.exports = function (doc)
+{
+  doc.querySelectorAll('pre > code').forEach(code =>
+  {
+    const pre = code.closest('pre');
+    const button = doc.createElement('zn-copy-button');
+
+    if(!code.id)
+    {
+      code.id = `code-block-${++codeBlockId}`;
+    }
+
+    button.classList.add('copy-code-button');
+    button.setAttribute('from', code.id);
+
+    pre.append(button);
+  });
+
+  return doc;
+};

package/docs/_utilities/external-links.cjs

@@ -0,0 +1,53 @@
+const {isExternalLink} = require('./strings.cjs');
+
+/**
+ * Transforms external links to make them safer and optionally add a target. The provided doc should be a document
+ * object provided by JSDOM. The same document will be returned with the appropriate DOM manipulations.
+ */
+module.exports = function (doc, options)
+{
+  options = {
+    className: 'external-link', // the class name to add to links
+    noopener: true, // sets rel="noopener"
+    noreferrer: true, // sets rel="noreferrer"
+    ignore: () => false, // callback function to filter links that should be ignored
+    within: 'body', // element that contains the target links
+    target: '', // sets the target attribute
+    ...options
+  };
+
+  const within = doc.querySelector(options.within);
+
+  if(within)
+  {
+    within.querySelectorAll('a').forEach(link =>
+    {
+      if(isExternalLink(link) && !options.ignore(link))
+      {
+        link.classList.add(options.className);
+
+        const rel = [];
+        if(options.noopener)
+        {
+          rel.push('noopener');
+        }
+        if(options.noreferrer)
+        {
+          rel.push('noreferrer');
+        }
+
+        if(rel.length)
+        {
+          link.setAttribute('rel', rel.join(' '));
+        }
+
+        if(options.target)
+        {
+          link.setAttribute('target', options.target);
+        }
+      }
+    });
+  }
+
+  return doc;
+};

package/docs/_utilities/highlight-code.cjs

@@ -0,0 +1,74 @@
+const Prism = require('prismjs');
+const PrismLoader = require('prismjs/components/index.js');
+
+PrismLoader('diff');
+PrismLoader.silent = true;
+
+/** Highlights a code string. */
+function highlight(code, language)
+{
+  const alias = language.replace(/^diff-/, '');
+  const isDiff = /^diff-/i.test(language);
+
+  // Auto-load the target language
+  if(!Prism.languages[alias])
+  {
+    PrismLoader(alias);
+
+    if(!Prism.languages[alias])
+    {
+      throw new Error(`Unsupported language for code highlighting: "${language}"`);
+    }
+  }
+
+  // Register diff-* languages to use the diff grammar
+  if(isDiff)
+  {
+    Prism.languages[language] = Prism.languages.diff;
+  }
+
+  return Prism.highlight(code, Prism.languages[language], language);
+}
+
+/**
+ * Highlights all code fields that have a language parameter. If the language has a colon in its name, the first chunk
+ * will be the language used and additional chunks will be applied as classes to the `<pre>`. For example, a code field
+ * tagged with "html:preview" will be rendered as `<pre class="language-html preview">`.
+ *
+ * The provided doc should be a document object provided by JSDOM. The same document will be returned with the
+ * appropriate DOM manipulations.
+ */
+module.exports = function (doc)
+{
+  doc.querySelectorAll('pre > code[class]').forEach(code =>
+  {
+    // Look for class="language-*" and split colons into separate classes
+    code.classList.forEach(className =>
+    {
+      if(className.startsWith('language-'))
+      {
+        //
+        // We use certain suffixes to indicate code previews, expanded states, etc. The class might look something like
+        // this:
+        //
+        //  class="language-html:preview:expanded"
+        //
+        // The language will always come first, so we need to drop the "language-" prefix and everything after the first
+        // color to get the highlighter language.
+        //
+        const language = className.replace(/^language-/, '').split(':')[0];
+
+        try
+        {
+          code.innerHTML = highlight(code.textContent ?? '', language);
+        }
+        catch(err)
+        {
+          // Language not found, skip it
+        }
+      }
+    });
+  });
+
+  return doc;
+};

package/docs/_utilities/markdown.cjs

@@ -0,0 +1,74 @@
+const MarkdownIt = require('markdown-it');
+const markdownItContainer = require('markdown-it-container');
+const markdownItIns = require('markdown-it-ins');
+const markdownItKbd = require('markdown-it-kbd');
+const markdownItMark = require('markdown-it-mark');
+const markdownItReplaceIt = require('markdown-it-replace-it');
+
+const markdown = MarkdownIt({
+  html: true,
+  xhtmlOut: false,
+  breaks: false,
+  langPrefix: 'language-',
+  linkify: false,
+  typographer: false
+});
+
+// Third-party plugins
+markdown.use(markdownItContainer);
+markdown.use(markdownItIns);
+markdown.use(markdownItKbd);
+markdown.use(markdownItMark);
+markdown.use(markdownItReplaceIt);
+
+// Callouts
+['tip', 'warning', 'danger'].forEach(type =>
+{
+  markdown.use(markdownItContainer, type, {
+    render: function (tokens, idx)
+    {
+      if(tokens[idx].nesting === 1)
+      {
+        return `<div role="alert" class="callout callout--${type}">`;
+      }
+      return '</div>\n';
+    }
+  });
+});
+
+// Asides
+markdown.use(markdownItContainer, 'aside', {
+  render: function (tokens, idx)
+  {
+    if(tokens[idx].nesting === 1)
+    {
+      return `<aside>`;
+    }
+    return '</aside>\n';
+  }
+});
+
+// Details
+markdown.use(markdownItContainer, 'details', {
+  validate: params => params.trim().match(/^details\s+(.*)$/),
+  render: (tokens, idx) =>
+  {
+    const m = tokens[idx].info.trim().match(/^details\s+(.*)$/);
+    if(tokens[idx].nesting === 1)
+    {
+      return `<details>\n<summary><span>${markdown.utils.escapeHtml(m[1])}</span></summary>\n`;
+    }
+    return '</details>\n';
+  }
+});
+
+// Replace [#1234] with a link to GitHub issues
+markdownItReplaceIt.replacements.push({
+  name: 'github-issues',
+  re: /\[#([0-9]+)\]/gs,
+  sub: '<a href="https://github.com/kubex/zinc/issues/$1">#$1</a>',
+  html: true,
+  default: true
+});
+
+module.exports = markdown;

package/docs/_utilities/prettier.cjs

@@ -0,0 +1,26 @@
+const { format } = require('prettier');
+
+/** Formats markup using prettier. */
+module.exports = function (content, options) {
+  options = {
+    arrowParens: 'avoid',
+    bracketSpacing: true,
+    htmlWhitespaceSensitivity: 'css',
+    insertPragma: false,
+    bracketSameLine: false,
+    jsxSingleQuote: false,
+    parser: 'html',
+    printWidth: 120,
+    proseWrap: 'preserve',
+    quoteProps: 'as-needed',
+    requirePragma: false,
+    semi: true,
+    singleQuote: true,
+    tabWidth: 2,
+    trailingComma: 'none',
+    useTabs: false,
+    ...options
+  };
+
+  return format(content, options);
+};

package/docs/_utilities/replacer.cjs

@@ -0,0 +1,24 @@
+/**
+ * @typedef {object} Replacement
+ * @property {string | RegExp} pattern
+ * @property {string} replacement
+ */
+
+/**
+ * @typedef {Array<Replacement>} Replacements
+ */
+
+/**
+ * @param {String} rawContent
+ * @param {Replacements} replacements
+ */
+module.exports = function (rawContent, replacements)
+{
+  let content = rawContent;
+  replacements.forEach(replacement =>
+  {
+    content = content.replaceAll(replacement.pattern, replacement.replacement);
+  });
+
+  return content;
+};

package/docs/_utilities/scrolling-tables.cjs

@@ -0,0 +1,23 @@
+/**
+ * Turns headings into clickable, deep linkable anchors. The provided doc should be a document object provided by JSDOM.
+ * The same document will be returned with the appropriate DOM manipulations.
+ */
+module.exports = function (doc, options)
+{
+  const tables = [...doc.querySelectorAll('table')];
+
+  options = {
+    className: 'table-scroll', // the class name to add to the table's container
+    ...options
+  };
+
+  tables.forEach(table =>
+  {
+    const div = doc.createElement('div');
+    div.classList.add(options.className);
+    table.insertAdjacentElement('beforebegin', div);
+    div.append(table);
+  });
+
+  return doc;
+};

package/docs/_utilities/strings.cjs

@@ -0,0 +1,16 @@
+const slugify = require('slugify');
+
+/** Creates a slug from an arbitrary string of text. */
+module.exports.createSlug = function (text) {
+  return slugify(String(text), {
+    remove: /[^\w|\s]/g,
+    lower: true
+  });
+};
+
+/** Determines whether or not a link is external. */
+module.exports.isExternalLink = function (link) {
+  // We use the "internal" hostname when initializing JSDOM so we know that those are local links
+  if (!link.hostname || link.hostname === 'internal') return false;
+  return true;
+};

package/docs/_utilities/table-of-contents.cjs

@@ -0,0 +1,48 @@
+/**
+ * Generates an in-page table of contents based on headings.
+ */
+module.exports = function (doc, options)
+{
+  options = {
+    levels: ['h2'], // headings to include (they must have an id)
+    container: 'nav', // the container to append links to
+    listItem: true, // if true, links will be wrapped in <li>
+    within: 'body', // the element containing the headings to summarize
+    ...options
+  };
+
+  const container = doc.querySelector(options.container);
+  const within = doc.querySelector(options.within);
+  const headingSelector = options.levels.map(h => `${h}[id]`).join(', ');
+
+  if(!container || !within)
+  {
+    return doc;
+  }
+
+  within.querySelectorAll(headingSelector).forEach(heading =>
+  {
+    const listItem = doc.createElement('li');
+    const link = doc.createElement('a');
+    const level = heading.tagName.slice(1);
+
+    link.href = `#${heading.id}`;
+    link.textContent = heading.textContent;
+
+    if(options.listItem)
+    {
+      // List item + link
+      listItem.setAttribute('data-level', level);
+      listItem.append(link);
+      container.append(listItem);
+    }
+    else
+    {
+      // Link only
+      link.setAttribute('data-level', level);
+      container.append(link);
+    }
+  });
+
+  return doc;
+};

package/docs/_utilities/typography.cjs

@@ -0,0 +1,24 @@
+const smartquotes = require('smartquotes');
+
+smartquotes.replacements.push([/---/g, '\u2014']); // em dash
+smartquotes.replacements.push([/--/g, '\u2013']); // en dash
+smartquotes.replacements.push([/\.\.\./g, '\u2026']); // ellipsis
+smartquotes.replacements.push([/\(c\)/gi, '\u00A9']); // copyright
+smartquotes.replacements.push([/\(r\)/gi, '\u00AE']); // registered trademark
+smartquotes.replacements.push([/\?!/g, '\u2048']); // ?!
+smartquotes.replacements.push([/!!/g, '\u203C']); // !!
+smartquotes.replacements.push([/\?\?/g, '\u2047']); // ??
+smartquotes.replacements.push([/([0-9]\s?)-(\s?[0-9])/g, '$1\u2013$2']); // number ranges use en dash
+
+/**
+ * Improves typography by adding smart quotes and similar corrections within the specified element(s).
+ *
+ * The provided doc should be a document object provided by JSDOM. The same document will be returned with the
+ * appropriate DOM manipulations.
+ */
+module.exports = function (doc, selector = 'body')
+{
+  const elements = [...doc.querySelectorAll(selector)];
+  elements.forEach(el => smartquotes.element(el));
+  return doc;
+};