@kubex/zinc 0.0.3 → 1.0.1

package/docs/_includes/component.njk

@@ -0,0 +1,340 @@
+{% extends "default.njk" %}
+
+{# Find the component based on the `tag` front matter #}
+{% set component = getComponent('zn-' + page.fileSlug) %}
+
+{% block content %}
+  {# Determine the badge variant #}
+  {% if component.status == 'stable' %}
+    {% set badgeVariant = 'primary' %}
+  {% elseif component.status == 'experimental' %}
+    {% set badgeVariant = 'warning' %}
+  {% elseif component.status == 'planned' %}
+    {% set badgeVariant = 'neutral' %}
+  {% elseif component.status == 'deprecated' %}
+    {% set badgeVariant = 'danger' %}
+  {% else %}
+    {% set badgeVariant = 'neutral' %}
+  {% endif %}
+
+  {# Header #}
+  <header class="component-header">
+    <h1>{{ component.name | classNameToComponentName }}</h1>
+
+    <div class="component-header__tag">
+      <code>&lt;{{ component.tagName }}&gt; | {{ component.name }}</code>
+    </div>
+
+    <div class="component-header__info">
+      <zn-chip type="info">
+        Since {{ component.since or '?' }}
+      </zn-chip>
+      <zn-chip type="{{ badgeVariant }}" style="text-transform: capitalize;">
+        {{ component.status }}
+      </zn-chip>
+    </div>
+  </header>
+
+  <p class="component-summary">
+    {% if component.summary %}
+      {{ component.summary | markdownInline | safe }}
+    {% endif %}
+  </p>
+
+  {# Markdown content #}
+  {{ content | safe }}
+
+  <h2>Importing</h2>
+  <p>
+    If you're using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use
+    any of the following snippets to <a href="/getting-started/installation#cherry-picking">cherry pick</a> this
+    component.
+  </p>
+
+  <zn-collapsible caption="Script">
+    <p>
+      To import this component from <a href="https://www.jsdelivr.com/package/npm/@kubex/zinc">the CDN</a>
+      using a script tag:
+    </p>
+    <pre><code class="language-html">&lt;script type=&quot;module&quot; src=&quot;https://cdn.jsdelivr.net/npm/@kubex/zinc@{{ meta.version }}/dist/{{ component.path }}&quot;&gt;&lt;/script&gt;</code></pre>
+  </zn-collapsible>
+
+  <zn-collapsible caption="JavaScript">
+    <p>
+      To import this component from <a href="https://www.jsdelivr.com/package/npm/@kubex/zinc">the CDN</a>
+      using a JavaScript import:
+    </p>
+    <pre><code
+        class="language-js">import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@{{ meta.version }}/dist/{{ component.path }}';</code></pre>
+  </zn-collapsible>
+
+  <zn-collapsible caption="Bundler">
+    <p>
+      To import this component using <a href="/getting-started/installation#bundling">a bundler</a>:
+    </p>
+    <pre><code class="language-js">import '@kubex/zinc/dist/{{ component.path }}';</code></pre>
+  </zn-collapsible>
+
+  {# Slots #}
+  {% if component.slots.length %}
+    <h2>Slots</h2>
+
+    <table>
+      <thead>
+      <tr>
+        <th class="table-name">Name</th>
+        <th class="table-description">Description</th>
+      </tr>
+      </thead>
+      <tbody>
+      {% for slot in component.slots %}
+        <tr>
+          <td class="nowrap">
+            {% if slot.name %}
+              <code>{{ slot.name }}</code>
+            {% else %}
+              (default)
+            {% endif %}
+          </td>
+          <td>{{ slot.description | markdownInline | safe }}</td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+
+    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#slots') }}">using slots</a>.</em></p>
+  {% endif %}
+
+  {# Properties #}
+  {% if component.properties.length %}
+    <h2>Properties</h2>
+
+    <table>
+      <thead>
+      <tr>
+        <th class="table-name">Name</th>
+        <th class="table-description">Description</th>
+        <th class="table-reflects">Reflects</th>
+        <th class="table-type">Type</th>
+        <th class="table-default">Default</th>
+      </tr>
+      </thead>
+      <tbody>
+      {% for prop in component.properties %}
+        <tr>
+          <td>
+            <code class="nowrap">{{ prop.name }}</code>
+            {% if prop.attribute | length > 0 %}
+              {% if prop.attribute != prop.name %}
+                <br>
+                <zn-tooltip content="This attribute is different from its property">
+                  <small>
+                    <code class="nowrap">
+                      {{ prop.attribute }}
+                    </code>
+                  </small>
+                </zn-tooltip>
+              {% endif %}
+            {% endif %}
+          </td>
+          <td>
+            {{ prop.description | markdownInline | safe }}
+          </td>
+          <td style="text-align: center;">
+            {% if prop.reflects %}
+              <zn-icon label="yes" src="check"></zn-icon>
+            {% endif %}
+          </td>
+          <td>
+            {% if prop.type.text %}
+              <code>{{ prop.type.text | trimPipes | markdownInline | safe }}</code>
+            {% else %}
+              -
+            {% endif %}
+          </td>
+          <td>
+            {% if prop.default %}
+              <code>{{ prop.default | markdownInline | safe }}</code>
+            {% else %}
+              -
+            {% endif %}
+          </td>
+        </tr>
+      {% endfor %}
+      <tr>
+        <td class="nowrap"><code>updateComplete</code></td>
+        <td>
+          A read-only promise that resolves when the component has
+          <a href="/getting-started/usage?#component-rendering-and-updating">finished updating</a>.
+        </td>
+        <td></td>
+        <td></td>
+        <td></td>
+      </tr>
+      </tbody>
+    </table>
+
+    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#attributes-and-properties') }}">attributes and
+          properties</a>.</em></p>
+  {% endif %}
+
+  {# Events #}
+  {% if component.events.length %}
+    <h2>Events</h2>
+
+    <table>
+      <thead>
+      <tr>
+        <th class="table-name" data-flavor="html">Name</th>
+        <th class="table-name" data-flavor="react">React Event</th>
+        <th class="table-description">Description</th>
+        <th class="table-event-detail">Event Detail</th>
+      </tr>
+      </thead>
+      <tbody>
+      {% for event in component.events %}
+        <tr>
+          <td data-flavor="html"><code class="nowrap">{{ event.name }}</code></td>
+          <td data-flavor="react"><code class="nowrap">{{ event.reactName }}</code></td>
+          <td>{{ event.description | markdownInline | safe }}</td>
+          <td>
+            {% if event.type.text %}
+              <code>{{ event.type.text | trimPipes }}</code>
+            {% else %}
+              -
+            {% endif %}
+          </td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+
+    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#events') }}">events</a>.</em></p>
+  {% endif %}
+
+  {# Methods #}
+  {% if component.methods.length %}
+    <h2>Methods</h2>
+
+    <table>
+      <thead>
+      <tr>
+        <th class="table-name">Name</th>
+        <th class="table-description">Description</th>
+        <th class="table-arguments">Arguments</th>
+      </tr>
+      </thead>
+      <tbody>
+      {% for method in component.methods %}
+        <tr>
+          <td class="nowrap"><code>{{ method.name }}()</code></td>
+          <td>{{ method.description | markdownInline | safe }}</td>
+          <td>
+            {% if method.parameters.length %}
+              <code>
+                {% for param in method.parameters %}
+                  {{ param.name }}: {{ param.type.text | trimPipes }}{% if not loop.last %},{% endif %}
+                {% endfor %}
+              </code>
+            {% else %}
+              -
+            {% endif %}
+          </td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+
+    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#methods') }}">methods</a>.</em></p>
+  {% endif %}
+
+  {# Custom Properties #}
+  {% if component.cssProperties.length %}
+    <h2>Custom Properties</h2>
+
+    <table>
+      <thead>
+      <tr>
+        <th class="table-name">Name</th>
+        <th class="table-description">Description</th>
+        <th class="table-default">Default</th>
+      </tr>
+      </thead>
+      <tbody>
+      {% for cssProperty in component.cssProperties %}
+        <tr>
+          <td class="nowrap"><code>{{ cssProperty.name }}</code></td>
+          <td>{{ cssProperty.description | markdownInline | safe }}</td>
+          <td>{{ cssProperty.default }}</td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+
+    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/customizing#custom-properties') }}">customizing CSS
+          custom properties</a>.</em></p>
+  {% endif %}
+
+  {# CSS Parts #}
+  {% if component.cssParts.length %}
+    <h2>Parts</h2>
+
+    <table>
+      <thead>
+      <tr>
+        <th class="table-name">Name</th>
+        <th class="table-description">Description</th>
+      </tr>
+      </thead>
+      <tbody>
+      {% for cssPart in component.cssParts %}
+        <tr>
+          <td class="nowrap"><code>{{ cssPart.name }}</code></td>
+          <td>{{ cssPart.description | markdownInline | safe }}</td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+
+    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/customizing/#css-parts') }}">customizing CSS parts</a>.</em>
+    </p>
+  {% endif %}
+
+  {# Animations #}
+  {% if component.animations.length %}
+    <h2>Animations</h2>
+
+    <table>
+      <thead>
+      <tr>
+        <th class="table-name">Name</th>
+        <th class="table-description">Description</th>
+      </tr>
+      </thead>
+      <tbody>
+      {% for animation in component.animations %}
+        <tr>
+          <td class="nowrap"><code>{{ animation.name }}</code></td>
+          <td>{{ animation.description | markdownInline | safe }}</td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+
+    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/customizing#animations') }}">customizing
+          animations</a>.</em></p>
+  {% endif %}
+
+  {# Dependencies #}
+  {% if component.dependencies.length %}
+    <h2>Dependencies</h2>
+
+    <p>This component automatically imports the following dependencies.</p>
+
+    <ul>
+      {% for dependency in component.dependencies %}
+        <li><code>&lt;{{ dependency }}&gt;</code></li>
+      {% endfor %}
+    </ul>
+  {% endif %}
+{% endblock %}

package/docs/_includes/default.njk

@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<html
+  lang="en"
+  data-layout="{{ layout }}"
+  data-zinc-version="{{ meta.version }}">
+<head>
+  {# Metadata #}
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <meta name="description" content="{{ meta.description }}"/>
+  <title>{{ meta.title }}</title>
+
+  {# Opt out of Turbo caching #}
+  <meta name="turbo-cache-control">
+
+  {# Twitter Cards #}
+  <meta name="twitter:card" content="summary"/>
+  <meta name="twitter:creator" content="kubex"/>
+  <meta name="twitter:image" content="{{ assetUrl(meta.image, true) }}"/>
+
+  {# OpenGraph #}
+  <meta property="og:url" content="{{ rootUrl(page.url, true) }}"/>
+  <meta property="og:title" content="{{ meta.title }}"/>
+  <meta property="og:description" content="{{ meta.description }}"/>
+  <meta property="og:image" content="{{ assetUrl(meta.image, true) }}"/>
+
+  {# Stylesheets #}
+  <link rel="stylesheet" href="{{ assetUrl('styles/docs.css') }}"/>
+  <link rel="stylesheet" href="{{ assetUrl('styles/code-previews.css') }}"/>
+  <link rel="stylesheet" href="{{ assetUrl('styles/search.css') }}"/>
+
+  {# Zinc #}
+  <script type="module" src="/dist/zn.min.js"></script>
+  <link rel="stylesheet" href="/dist/zn.min.css"/>
+
+  {# Scripts #}
+  <script src="{{ assetUrl('scripts/turbo.js') }}" type="module"></script>
+  <script src="{{ assetUrl('scripts/docs.js') }}" defer></script>
+  <script src="{{ assetUrl('scripts/code-previews.js') }}" defer></script>
+  <script src="{{ assetUrl('scripts/lunr.js') }}" defer></script>
+  <script src="{{ assetUrl('scripts/search.js') }}" defer></script>
+</head>
+<body>
+<a id="skip-to-main" class="visually-hidden" href="#main-content" data-smooth-link="false">
+  Skip to main content
+</a>
+
+{# Menu toggle #}
+<button id="menu-toggle" type="button" aria-label="Menu">
+  <svg width="148" height="148" viewBox="0 0 148 148" xmlns="http://www.w3.org/2000/svg">
+    <g stroke="currentColor" stroke-width="18" fill="none" fill-rule="evenodd" stroke-linecap="round">
+      <path d="M9.5 125.5h129M9.5 74.5h129M9.5 23.5h129"></path>
+    </g>
+  </svg>
+</button>
+
+{# Icon toolbar #}
+<div id="icon-toolbar">
+  {# GitHub #}
+  <a href="https://github.com/kubex/zinc" title="View zinc on GitHub">
+    <zn-icon src="code"></zn-icon>
+  </a>
+
+  {# Theme selector #}
+  <zn-dropdown id="theme-selector" placement="bottom-end" distance="3">
+    <zn-button slot="trigger" size="content" color="transparent" title="Press \ to toggle">
+      <zn-icon class="only-light" src="light_mode"></zn-icon>
+      <zn-icon class="only-dark" src="dark_mode"></zn-icon>
+    </zn-button>
+    <zn-menu>
+      <zn-menu-item type="checkbox" value="light">Light</zn-menu-item>
+      <zn-menu-item type="checkbox" value="dark">Dark</zn-menu-item>
+      <zn-menu-item type="checkbox" value="auto">System</zn-menu-item>
+    </zn-menu>
+  </zn-dropdown>
+</div>
+
+{# Content #}
+<aside id="sidebar" data-preserve-scroll>
+  <header>
+    <a href="/">
+      <img src="{{ assetUrl('images/watermark.svg') }}" alt="zinc"/>
+    </a>
+    <div class="sidebar-version">
+      {{ meta.version }}
+    </div>
+  </header>
+
+  <div class="sidebar-buttons">
+    <zn-button size="small" class="repo-button repo-button--github" href="https://github.com/kubex/zinc"
+               target="_blank" icon="folder_open" color="secondary">
+      Code
+    </zn-button>
+    <zn-button size="small" class="repo-button repo-button--star" color="secondary"
+               href="https://github.com/kubex/zinc/stargazers" target="_blank" icon="star">
+      Star
+    </zn-button>
+  </div>
+
+  <zn-button icon="search"
+             class="search-box"
+             color="transparent"
+             size="small"
+             type="button"
+             title="Press / to search"
+             aria-label="Search"
+             data-plugin="search">
+    <span>Search</span>
+  </zn-button>
+
+  <nav>
+    {% include 'sidebar.njk' %}
+  </nav>
+</aside>
+
+{# Content #}
+<main>
+  <a id="main-content"></a>
+  <article id="content"
+           class="content{% if toc %} content--with-toc{% endif %}{% if fullWidth %} content--full-width{% endif %}">
+    {% if toc %}
+      <div class="content__toc">
+        <ul>
+          <li class="top"><a href="#">{{ meta.title }}</a></li>
+        </ul>
+      </div>
+    {% endif %}
+
+    <div class="content__body">
+      {% block content %}
+        {{ content | safe }}
+      {% endblock %}
+    </div>
+  </article>
+</main>
+</body>
+</html>

package/docs/_includes/sidebar.njk

@@ -0,0 +1,24 @@
+<ul>
+  <li>
+    <h2>Tutorials</h2>
+    <ul>
+      <li><a href="/getting-started/form-controls">Form Controls</a></li>
+      <li><a href="/getting-started/form-examples">Form Examples</a></li>
+      <li><a href="/getting-started/table-examples">Table Examples</a></li>
+      <li><a href="/getting-started/example-layout">Example Layout</a></li>
+      <li><a href="/getting-started/example-page">Example Page</a></li>
+    </ul>
+  </li>
+  <li>
+    <h2>Components</h2>
+    <ul>
+      {% for component in meta.components %}
+        <li>
+          <a href="/components/{{ component.tagName | removeZNPrefix }}">
+            {{ component.name | classNameToComponentName }}
+          </a>
+        </li>
+      {% endfor %}
+    </ul>
+  </li>
+</ul>

package/docs/_utilities/active-links.cjs

@@ -0,0 +1,41 @@
+function normalizePathname(pathname)
+{
+  // Remove /index.html
+  if(pathname.endsWith('/index.html'))
+  {
+    pathname = pathname.replace(/\/index\.html/, '');
+  }
+
+  // Remove trailing slashes
+  return pathname.replace(/\/$/, '');
+}
+
+/**
+ * Adds a class name to links that are currently active.
+ */
+module.exports = function (doc, options)
+{
+  options = {
+    className: 'active-link', // the class to add to active links
+    pathname: undefined, // the current pathname to compare
+    within: 'body', // element containing the target links
+    ...options
+  };
+
+  const within = doc.querySelector(options.within);
+
+  if(!within)
+  {
+    return doc;
+  }
+
+  within.querySelectorAll('a').forEach(link =>
+  {
+    if(normalizePathname(options.pathname) === normalizePathname(link.pathname))
+    {
+      link.classList.add(options.className);
+    }
+  });
+
+  return doc;
+};

package/docs/_utilities/anchor-headings.cjs

@@ -0,0 +1,74 @@
+const {createSlug} = require('./strings.cjs');
+
+/**
+ * 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)
+{
+  options = {
+    levels: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'], // the headings to convert
+    className: 'anchor-heading', // the class name to add
+    within: 'body', // the element containing the target headings
+    ...options
+  };
+
+  const within = doc.querySelector(options.within);
+
+  if(!within)
+  {
+    return doc;
+  }
+
+  within.querySelectorAll('h1, h2, h3, h4, h5, h6').forEach(heading =>
+  {
+    const hasAnchor = heading.querySelector('a');
+    const anchor = doc.createElement('a');
+    let id = heading.textContent ?? '';
+    let suffix = 0;
+
+    // Skip heading levels we don't care about
+    if(!options.levels?.includes(heading.tagName.toLowerCase()))
+    {
+      return;
+    }
+
+    // Convert dots to underscores
+    id = id.replace(/\./g, '_');
+
+    // Turn it into a slug
+    id = createSlug(id);
+
+    // Make sure it starts with a letter
+    if(!/^[a-z]/i.test(id))
+    {
+      id = `id_${id}`;
+    }
+
+    // Make sure the id is unique
+    const originalId = id;
+    while(doc.getElementById(id) !== null)
+    {
+      id = `${originalId}-${++suffix}`;
+    }
+
+    if(hasAnchor || !id)
+    {
+      return;
+    }
+
+    heading.setAttribute('id', id);
+    anchor.setAttribute('href', `#${encodeURIComponent(id)}`);
+    anchor.setAttribute('aria-label', `Direct link to "${heading.textContent}"`);
+
+    if(options.className)
+    {
+      heading.classList.add(options.className);
+    }
+
+    // Append the anchor
+    heading.append(anchor);
+  });
+
+  return doc;
+};