@kubex/zinc 0.0.2 → 1.0.0

package/docs/assets/styles/search.css

@@ -0,0 +1,347 @@
+/* Search plugin */
+:root,
+:root.zn-theme-dark {
+  --docs-search-box-background: var(--zn-color-neutral-0);
+  --docs-search-box-border-width: 1px;
+  --docs-search-box-border-color: var(--zn-color-neutral-300);
+  --docs-search-box-color: var(--zn-color-neutral-600);
+  --docs-search-dialog-background: var(--zn-color-neutral-0);
+  --docs-search-border-width: var(--docs-border-width);
+  --docs-search-border-color: var(--docs-border-color);
+  --docs-search-text-color: var(--zn-color-neutral-900);
+  --docs-search-text-color-muted: rgb(var(--zn-text));
+  --docs-search-font-weight-normal: var(--zn-font-weight-normal);
+  --docs-search-font-weight-semibold: var(--zn-font-weight-semibold);
+  --docs-search-border-radius: calc(2 * var(--docs-border-radius));
+  --docs-search-accent-color: var(--zn-color-primary-600);
+  --docs-search-icon-color: rgb(var(--zn-text));
+  --docs-search-icon-color-active: var(--zn-color-neutral-600);
+  --docs-search-shadow: var(--docs-shadow-x-large);
+  --docs-search-result-background-hover: var(--zn-color-neutral-100);
+  --docs-search-result-color-hover: var(--zn-color-neutral-900);
+  --docs-search-result-background-active: var(--zn-color-primary-600);
+  --docs-search-result-color-active: var(--zn-color-neutral-0);
+  --docs-search-focus-ring: var(--zn-focus-ring);
+  --docs-search-overlay-background: rgb(0 0 0 / 0.33);
+}
+
+:root.zn-theme-dark {
+  --docs-search-overlay-background: rgb(71 71 71 / 0.33);
+}
+
+body.search-visible {
+  padding-right: var(--docs-search-scroll-lock-size) !important;
+  overflow: hidden !important;
+}
+
+/* Search box */
+.search-box {
+  flex: 1 1 auto;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  border-radius: 9999px;
+  background: var(--docs-search-box-background);
+  border: solid var(--docs-search-box-border-width) var(--docs-search-box-border-color);
+  font: inherit;
+  color: var(--docs-search-box-color);
+  padding: var(--zn-spacing-2x-small) var(--zn-spacing-x-small);
+  margin: var(--zn-spacing-small) 0;
+  cursor: pointer;
+}
+
+.search-box span {
+  flex: 1 1 auto;
+  width: 1rem;
+  height: 1rem;
+  text-align: left;
+  line-height: 1;
+  margin: 0 0.75rem;
+}
+
+.search-box:focus {
+  outline: none;
+}
+
+.search-box:focus-visible {
+  outline: var(--docs-search-focus-ring);
+}
+
+/* Site search */
+.search {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 9999;
+}
+
+.search[hidden] {
+  display: none;
+}
+
+.search__overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: var(--docs-search-overlay-background);
+  z-index: -1;
+}
+
+.search__dialog {
+  width: 100%;
+  height: 100%;
+  max-width: none;
+  max-height: none;
+  background: transparent;
+  border: none;
+  padding: 0;
+  margin: 0;
+}
+
+.search__dialog:focus {
+  outline: none;
+}
+
+.search__dialog::backdrop {
+  display: none;
+}
+
+/* Fixes an iOS Safari 16.4 bug that draws the parent element's border radius incorrectly when showing/hiding results */
+.search__header {
+  background-color: var(--docs-search-dialog-background);
+  border-radius: var(--docs-search-border-radius);
+}
+
+.search--has-results .search__header {
+  border-radius: var(--docs-search-border-radius) var(--docs-search-border-radius) 0 0;
+}
+
+.search__content {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: 500px;
+  max-height: calc(100vh - 20rem);
+  background-color: rgb(var(--zn-panel));
+  border-radius: var(--docs-search-border-radius);
+  box-shadow: var(--docs-search-shadow);
+  padding: 0;
+  margin: 10rem auto;
+}
+
+@media screen and (max-width: 900px) {
+  .search__content {
+    max-width: calc(100% - 2rem);
+    max-height: calc(90svh);
+    margin: 4vh 1rem;
+  }
+}
+
+.search__input-wrapper {
+  display: flex;
+  align-items: center;
+}
+
+.search__input-wrapper zn-icon {
+  width: 1.5rem;
+  height: 1.5rem;
+  flex: 0 0 auto;
+  color: var(--docs-search-icon-color);
+  margin: 0 1rem;
+}
+
+.search__clear-button {
+  display: flex;
+  background: none !important;
+  border: none !important;
+  font: inherit !important;
+  padding: 0 !important;
+  margin: 0 !important;
+  cursor: pointer;
+}
+
+.search__clear-button[hidden] {
+  display: none;
+}
+
+.search__clear-button:active zn-icon {
+  color: var(--docs-search-icon-color-active);
+}
+
+.search__input {
+  flex: 1 1 auto !important;
+  min-width: 0 !important;
+  border: none !important;
+  font: inherit !important;
+  font-size: 1.5rem !important;
+  font-weight: var(--docs-search-font-weight-normal) !important;
+  color: var(--docs-search-text-color) !important;
+  background: transparent !important;
+  outline: none !important;
+  margin: 0 !important;
+}
+
+.search__input {
+  box-shadow: none !important;
+}
+
+.search__input::placeholder {
+  color: var(--docs-search-text-color-muted);
+}
+
+.search__input::-webkit-search-decoration,
+.search__input::-webkit-search-cancel-button,
+.search__input::-webkit-search-results-button,
+.search__input::-webkit-search-results-decoration {
+  display: none !important;
+}
+
+.search__input:focus,
+.search__input:focus-visible {
+  outline: none !important;
+}
+
+.search__body {
+  flex: 1 1 auto;
+  overflow: auto;
+}
+
+.search--has-results .search__body {
+  border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
+}
+
+.search__results {
+  display: none;
+  line-height: 1.2;
+  list-style: none;
+  padding: 0.5rem 0;
+  margin: 0;
+}
+
+.search--has-results .search__results {
+  display: block;
+}
+
+.search__results a {
+  display: block;
+  text-decoration: none;
+  padding: 0.5rem 1.5rem;
+}
+
+.search__results a:focus-visible {
+  outline: var(--docs-search-focus-ring);
+}
+
+.search__results li a:hover,
+.search__results li a:hover small {
+  background-color: var(--docs-search-result-background-hover);
+  color: var(--docs-search-result-color-hover);
+}
+
+.search__results li[data-selected='true'] a,
+.search__results li[data-selected='true'] a * {
+  outline: none;
+  background-color: var(--docs-search-result-background-active);
+  color: var(--docs-search-result-color-active);
+}
+
+.search__results h3 {
+  font-weight: var(--docs-search-font-weight-semibold);
+  margin: 0;
+}
+
+.search__results small {
+  display: block;
+  color: var(--docs-search-text-color-muted);
+}
+
+.search__result {
+  padding: 0;
+  margin: 0;
+}
+
+.search__result a {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+.search__result-icon {
+  flex: 0 0 auto;
+  display: flex;
+  color: var(--docs-search-text-color-muted);
+}
+
+.search__result-icon zn-icon {
+  font-size: 1.5rem;
+}
+
+.search__result__details {
+  width: calc(100% - 3rem);
+}
+
+.search__result-title,
+.search__result-description,
+.search__result-url {
+  max-width: 400px;
+  line-height: 1.3;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.search__result-title {
+  font-size: 1.2rem;
+  font-weight: var(--docs-search-font-weight-semibold);
+  color: var(--docs-search-accent-color);
+}
+
+.search__result-description {
+  font-size: 0.875rem;
+  color: var(--docs-search-text-color);
+}
+
+.search__result-url {
+  font-size: 0.875rem;
+  color: var(--docs-search-text-color-muted);
+}
+
+.search__empty {
+  display: none;
+  border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
+  text-align: center;
+  color: var(--docs-search-text-color-muted);
+  padding: 2rem;
+}
+
+.search--no-results .search__empty {
+  display: block;
+}
+
+.search__footer {
+  display: flex;
+  justify-content: center;
+  gap: 2rem;
+  border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
+  border-bottom-left-radius: inherit;
+  border-bottom-right-radius: inherit;
+  padding: 1rem;
+}
+
+.search__footer small {
+  color: var(--docs-search-text-color-muted);
+}
+
+.search__footer small kbd:last-of-type {
+  margin-right: 0.25rem;
+}
+
+@media screen and (max-width: 900px) {
+  .search__footer {
+    display: none;
+  }
+}

package/docs/eleventy.config.cjs

@@ -0,0 +1,262 @@
+/* eslint-disable no-invalid-this */
+const fs = require('fs');
+const path = require('path');
+const lunr = require('lunr');
+const {capitalCase} = require('change-case');
+const {JSDOM} = require('jsdom');
+const {customElementsManifest, getAllComponents} = require('./_utilities/cem.cjs');
+const zincFlavoredMarkdown = require('./_utilities/markdown.cjs');
+const activeLinks = require('./_utilities/active-links.cjs');
+const anchorHeadings = require('./_utilities/anchor-headings.cjs');
+const codePreviews = require('./_utilities/code-previews.cjs');
+const copyCodeButtons = require('./_utilities/copy-code-buttons.cjs');
+const externalLinks = require('./_utilities/external-links.cjs');
+const highlightCodeBlocks = require('./_utilities/highlight-code.cjs');
+const tableOfContents = require('./_utilities/table-of-contents.cjs');
+const prettier = require('./_utilities/prettier.cjs');
+const scrollingTables = require('./_utilities/scrolling-tables.cjs');
+const typography = require('./_utilities/typography.cjs');
+const replacer = require('./_utilities/replacer.cjs');
+
+const assetsDir = 'assets';
+const outDir = 'dist';
+const allComponents = getAllComponents();
+let hasBuiltSearchIndex = false;
+
+module.exports = function (eleventyConfig)
+{
+  //
+  // Global data
+  //
+  eleventyConfig.addGlobalData('baseUrl', 'https://zinc.style'); // the production URL
+  eleventyConfig.addGlobalData('layout', 'default'); // make 'default' the default layout
+  eleventyConfig.addGlobalData('toc', true); // enable the table of contents
+  eleventyConfig.addGlobalData('meta', {
+    title:       'Zinc ',
+    description: 'A design system for building modern web applications',
+    version:     customElementsManifest.package.version,
+    components:  allComponents,
+    outdir:      outDir
+  });
+
+  //
+  // Layout aliases
+  //
+  eleventyConfig.addLayoutAlias('default', 'default.njk');
+
+  //
+  // Copy assets
+  //
+  eleventyConfig.addPassthroughCopy(assetsDir);
+  eleventyConfig.setServerPassthroughCopyBehavior('passthrough'); // emulates passthrough copy during --serve
+
+  //
+  // Functions
+  //
+
+  // Generates a URL relative to the site's root
+  eleventyConfig.addNunjucksGlobal('rootUrl', (value = '', absolute = false) =>
+  {
+    value = path.join('/', value);
+    value = value.replace(/\/+$/, '');
+    return absolute ? new URL(value, eleventyConfig.globalData.baseUrl).toString() : value;
+  });
+
+  // Generates a URL relative to the site's asset directory
+  eleventyConfig.addNunjucksGlobal('assetUrl', (value = '', absolute = false) =>
+  {
+    value = path.join(`/${assetsDir}`, value);
+    return absolute ? new URL(value, eleventyConfig.globalData.baseUrl).toString() : value;
+  });
+
+  // Fetches a specific component's metadata
+  eleventyConfig.addNunjucksGlobal('getComponent', tagName =>
+  {
+    const component = allComponents.find(c => c.tagName === tagName);
+    if(!component)
+    {
+      throw new Error(
+        `Unable to find a component called "${tagName}". Make sure the file name is the same as the component's tag ` +
+        `name (minus the zn- prefix).`
+      );
+    }
+    return component;
+  });
+
+  //
+  // Custom markdown syntaxes
+  //
+  eleventyConfig.setLibrary('md', zincFlavoredMarkdown);
+
+  //
+  // Filters
+  //
+  eleventyConfig.addFilter('markdown', content =>
+  {
+    return zincFlavoredMarkdown.render(content);
+  });
+
+  eleventyConfig.addFilter('markdownInline', content =>
+  {
+    return zincFlavoredMarkdown.renderInline(content);
+  });
+
+  // Trims whitespace and pipes from the start and end of a string. Useful for CEM types, which can be pipe-delimited.
+  // With Prettier 3, this means a leading pipe will exist if the line wraps.
+  eleventyConfig.addFilter('trimPipes', content =>
+  {
+    return typeof content === 'string' ? content.replace(/^(\s|\|)/g, '').replace(/(\s|\|)$/g, '') : content;
+  });
+
+  eleventyConfig.addFilter('classNameToComponentName', className =>
+  {
+    let name = capitalCase(className.replace(/^Zn/, ''));
+    if(name === 'Qr Code')
+    {
+      name = 'QR Code';
+    } // manual override
+    return name;
+  });
+
+  eleventyConfig.addFilter('removeZNPrefix', tagName =>
+  {
+    return tagName.replace(/^zn-/, '');
+  });
+
+  //
+  // Transforms
+  //
+  eleventyConfig.addTransform('html-transform', function (rawContent)
+  {
+    let content = replacer(rawContent, [
+      {pattern: '%VERSION%', replacement: customElementsManifest.package.version},
+      {pattern: '%OUTDIR%', replacement: outDir}
+    ]);
+
+    // Parse the template and get a Document object
+    const doc = new JSDOM(content, {
+      // We must set a default URL so links are parsed with a hostname. Let's use a bogus TLD so we can easily
+      // identify which ones are internal and which ones are external.
+      url: `https://internal/`
+    }).window.document;
+
+    // DOM transforms
+    activeLinks(doc, {pathname: this.page.url});
+    anchorHeadings(doc, {
+      within: '#content .content__body',
+      levels: ['h2', 'h3', 'h4', 'h5']
+    });
+    tableOfContents(doc, {
+      levels:    ['h2', 'h3'],
+      container: '#content .content__toc > ul',
+      within:    '#content .content__body'
+    });
+    codePreviews(doc);
+    externalLinks(doc, {target: '_blank'});
+    highlightCodeBlocks(doc);
+    scrollingTables(doc);
+    copyCodeButtons(doc); // must be after codePreviews + highlightCodeBlocks
+    typography(doc, '#content');
+
+    // Serialize the Document object to an HTML string and prepend the doctype
+    content = `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
+
+    // String transforms
+    content = prettier(content);
+
+    return content;
+  });
+
+  //
+  // Build a search index
+  //
+  eleventyConfig.on('eleventy.after', ({results}) =>
+  {
+    // We only want to build the search index on the first run so all pages get indexed.
+    if(hasBuiltSearchIndex)
+    {
+      return;
+    }
+
+    const map = {};
+    const searchIndexFilename = path.join(eleventyConfig.dir.output, assetsDir, 'search.json');
+    const lunrInput = path.resolve('../node_modules/lunr/lunr.min.js');
+    const lunrOutput = path.join(eleventyConfig.dir.output, assetsDir, 'scripts/lunr.js');
+    const searchIndex = lunr(function ()
+    {
+      // The search index uses these field names extensively, so shortening them can save some serious bytes. The
+      // initial index file went from 468 KB => 401 KB by using single-character names!
+      this.ref('id'); // id
+      this.field('t', {boost: 50}); // title
+      this.field('h', {boost: 25}); // headings
+      this.field('c'); // content
+
+      results.forEach((result, index) =>
+      {
+        const url = path
+          .join('/', path.relative(eleventyConfig.dir.output, result.outputPath))
+          .replace(/\\/g, '/') // convert backslashes to forward slashes
+          .replace(/\/index.html$/, ''); // convert trailing /index.html to /
+        const doc = new JSDOM(result.content, {
+          // We must set a default URL so links are parsed with a hostname. Let's use a bogus TLD so we can easily
+          // identify which ones are internal and which ones are external.
+          url: `https://internal/`
+        }).window.document;
+        const content = doc.querySelector('#content');
+
+        // Get title and headings
+        const title = (doc.querySelector('title')?.textContent || path.basename(result.outputPath)).trim();
+        const headings = [...content.querySelectorAll('h1, h2, h3, h4')]
+          .map(heading => heading.textContent)
+          .join(' ')
+          .replace(/\s+/g, ' ')
+          .trim();
+
+        // Remove code blocks and whitespace from content
+        [...content.querySelectorAll('code[class|=language]')].forEach(code => code.remove());
+        const textContent = content.textContent.replace(/\s+/g, ' ').trim();
+
+        // Update the index and map
+        this.add({id: index, t: title, h: headings, c: textContent});
+        map[index] = {title, url};
+      });
+    });
+
+    // Copy the Lunr search client and write the index
+    fs.mkdirSync(path.dirname(lunrOutput), {recursive: true});
+    fs.copyFileSync(lunrInput, lunrOutput);
+    fs.writeFileSync(searchIndexFilename, JSON.stringify({searchIndex, map}), 'utf-8');
+
+    hasBuiltSearchIndex = true;
+  });
+
+  //
+  // Send a signal to stdout that lets the build know we've reached this point
+  //
+  eleventyConfig.on('eleventy.after', () =>
+  {
+    console.log('[eleventy.after]');
+  });
+
+  //
+  // Dev server options (see https://www.11ty.dev/docs/dev-server/#options)
+  //
+  eleventyConfig.setServerOptions({
+    domDiff: false, // disable dom diffing so custom elements don't break on reload,
+    port:    4000,// if port 4000 is taken, 11ty will use the next one available
+    watch:   ['dist/**/*'] // additional files to watch that will trigger server updates (array of paths or globs)
+  });
+
+  //
+  // 11ty config
+  //
+  return {
+    dir:                    {
+      input:    'pages',
+      output:   '../_site',
+      includes: '../_includes' // resolved relative to the input dir
+    },
+    markdownTemplateEngine: 'njk', // use Nunjucks instead of Liquid for markdown files
+    templateEngineOverride: ['njk'] // just Nunjucks and then markdown
+  };
+};

package/docs/pages/components/absolute-container.md

@@ -0,0 +1,35 @@
+---
+meta:
+  title: Absolute Container
+  description:
+layout: component
+---
+
+```html:preview
+
+<zn-sidebar>
+  <div style="display: flex; flex-direction: column; position: relative;">
+    This is content on the outside
+    <zn-absolute-container>
+      <div style="background-color: var(--zn-color-amber-100); height: 400px; width: 100%; position: absolute;">
+        This is the content of the absoloute
+      </div>
+    </zn-absolute-container>
+  </div>
+</zn-sidebar>
+```
+
+## Examples
+
+The absolute container is used to wrap absolute elements, that would otherwise cause problems with the dom.
+
+```html:preview
+
+<div style="display: flex; position: relative;">
+  <zn-absolute-container>
+    <div style="background-color: var(--zn-color-amber-100); height: 400px; width: 100%; position: absolute;">
+      This is the content of the absoloute
+    </div>
+  </zn-absolute-container>
+</div>
+```

package/docs/pages/components/action-bar.md

@@ -0,0 +1,58 @@
+---
+meta:
+  title: Action Bar
+  description:
+layout: component
+---
+
+```html:preview
+
+<zn-action-bar>
+
+  <zn-dropdown distance="5" slot="menu">
+    <zn-button slot="trigger" color="transparent" icon-position="right" icon="arrow_drop_down">Category 1
+    </zn-button>
+    <zn-menu>
+      <zn-menu-item>Item 1</zn-menu-item>
+      <zn-menu-item>Item 2</zn-menu-item>
+    </zn-menu>
+  </zn-dropdown>
+
+  <zn-dropdown distance="5" slot="menu">
+    <zn-button slot="trigger" color="transparent" icon-position="right" icon="arrow_drop_down">Category 2
+    </zn-button>
+    <zn-menu>
+      <zn-menu-item>Item 1</zn-menu-item>
+      <zn-menu-item>Item 2</zn-menu-item>
+    </zn-menu>
+  </zn-dropdown>
+  
+  <zn-expanding-action icon="edit_note"
+                       method="fill"
+                       count-uri="/note/count"
+                       slot="actions"
+                       prefetch>
+    Hello there
+  </zn-expanding-action>
+
+  <zn-expanding-action icon="new_label"
+                       content-uri="/test"
+                       method="drop"
+                       slot="actions">
+    <p>This is the content here, this will probably be loaded from one of the URIs.</p>
+    <p>if count uri is set, use that to retrieve the number to display as a notification
+      if prefetch is set, we need to lod the uri which should have the count with it.</p>
+  </zn-expanding-action>
+
+</zn-action-bar>
+```
+
+## Examples
+
+### First Example
+
+TODO
+
+### Second Example
+
+TODO