Merge branch 'alpha-build' into next

2026-01-12 12:09:26 +00:00 · 2024-06-18 13:51:50 -04:00
parent 25d7e83e68 8fa942375a
commit c031efe84f
11 changed files with 112 additions and 42 deletions
--- a/docs/.eleventy.js
+++ b/docs/.eleventy.js
@@ -14,9 +14,16 @@ import { getComponents } from './_utils/manifest.js';
 import process from 'process';

 const packageData = JSON.parse(await readFile('./package.json', 'utf-8'));
+const isAlpha = process.argv.includes('--alpha');
 const isDeveloping = process.argv.includes('--develop');

 export default function (eleventyConfig) {
+  // NOTE - alpha setting removes certain pages
+  if (isAlpha) {
+    eleventyConfig.ignores.add('**/components/page.md');
+    eleventyConfig.ignores.add('**/experimental/**');
+  }
+
  // Add template data
  eleventyConfig.addGlobalData('package', packageData);

@@ -33,9 +40,7 @@ export default function (eleventyConfig) {

  // Shortcodes - {% shortCode arg1, arg2 %}
  eleventyConfig.addShortcode('cdnUrl', location => {
-    return (
-      `https://cdn.jsdelivr.net/npm/@shoelace-style/webawesome@${packageData.version}/` + location.replace(/^\//, '')
-    );
+    return `https://early.webawesome.com/webawesome@${packageData.version}/` + location.replace(/^\//, '');
  });

  // Helpers
--- a/docs/_includes/base.njk
+++ b/docs/_includes/base.njk
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en" data-version="{{ package.version }}">
+<html lang="en" data-cdn-url="{% cdnUrl %}">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
--- a/docs/_layouts/component.njk
+++ b/docs/_layouts/component.njk
@@ -274,6 +274,7 @@

  <wa-tab-group label="How would you like to import this component?">
    <wa-tab slot="nav" panel="cdn">CDN</wa-tab>
+    <wa-tab slot="nav" panel="npm">npm</wa-tab>
    <wa-tab slot="nav" panel="react">React</wa-tab>
    <wa-tab-panel name="cdn">
      <p>
@@ -281,11 +282,17 @@
      </p>
      <pre><code class="language-js">import '{% cdnUrl component.path %}';</code></pre>
    </wa-tab-panel>
+    <wa-tab-panel name="npm">
+      Coming soon!
+    </wa-tab-panel>
    <wa-tab-panel name="react">
+      Coming soon!
+      {# NOTE - disabled for alpha
      <p>
        To manually import this component from React, use the following code.
      </p>
      <pre><code class="language-js">import '@shoelace-style/webawesome/react/{{ component.tagName | stripPrefix }}';</code></pre>
+      #}
    </wa-tab-panel>
  </wa-tab-group>
 {% endblock %}
--- a/docs/assets/scripts/code-examples.js
+++ b/docs/assets/scripts/code-examples.js
@@ -15,12 +15,13 @@ document.addEventListener('click', event => {
  if (pen) {
    const codeExample = pen.closest('.code-example');
    const code = codeExample.querySelector('code');
-    const version = document.documentElement.dataset.version;
+    const cdnUrl = document.documentElement.dataset.cdnUrl;
    const html =
-      `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/webawesome@${version}/dist/webawesome.loader.js"></script>` +
+      `<script type="module" src="${cdnUrl}dist/webawesome.loader.js"></script>` + `\n\n` + `${code.textContent}`;
+    const css =
+      `import '${cdnUrl}/dist/themes/default.css';` +
      `\n\n` +
-      `${code.textContent}`;
-    const css = 'body {\n  font: 16px sans-serif;\n  padding: 1rem;\n}\n';
+      `body {\n  font: 16px sans-serif;\n  padding: 1rem;\n}\n`;
    const js = '';

    const form = document.createElement('form');
--- a/docs/docs/installation.md
+++ b/docs/docs/installation.md
@@ -4,15 +4,26 @@ description: Choose the installation method that works best for you.
 layout: page
 ---

-You can load Web Awesome via CDN or by installing it locally. If you're using a framework, make sure to check out the pages for [React](/frameworks/react), [Vue](/frameworks/vue), and [Angular](/frameworks/angular) for additional information.
+Welcome to the Web Awesome alpha release for early backers! 👋
+
+==This is a very early alpha release!== For this preview, we're only offering access to the free components through a temporary CDN. Please be aware: Things can change Things can break. You probably shouldn't be using this software in production yet! But fear not, we're working hard to polish up the free stuff you see here _plus_ all the great stuff we have planned for Web Awesome Pro!
+
+==To be clear, this release _only_ includes a preview the components in Web Awesome Free!==
+
+Thank you so much for backing us!
+
+- [Report a bug](https://github.com/shoelace-style/webawesome-alpha/issues)
+- [Get help / ask a question](https://github.com/shoelace-style/webawesome-alpha/discussions)
+
+---

 ## Autoloading via CDN (Easiest)

 The autoloader is the easiest way to use Web Awesome. A lightweight script watches the DOM for unregistered Web Awesome elements and lazy loads them for you — even if they're added dynamically.

 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/default.css" />
-<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/autoloader.js"></script>
+<link rel="stylesheet" href="{% cdnUrl 'dist/themes/default.css' %}" />
+<script type="module" src="{% cdnUrl 'dist/autoloader.js' %}"></script>
 ```

 Now you can [start using Web Awesome!](/getting-started/usage)
@@ -25,16 +36,16 @@ While convenient, autoloading may lead to a [Flash of Undefined Custom Elements]

 Some components rely on assets (icons, images, etc.) and Web Awesome needs to know where they're located. For convenience, Web Awesome will try to auto-detect the correct location based on the script you've loaded it from. This assumes assets are colocated with `autoloader.js` and will "just work" for most users.

-If you're using the CDN, you can skip this section. However, if you're [cherry picking](#cherry-picking) or bundling Web Awesome, you'll need to set the base path. You can do this one of two ways.
+==If you're using the CDN, you can skip this section.== However, if you're [cherry picking](#cherry-picking) or bundling Web Awesome, you'll need to set the base path. You can do this one of two ways.

 ```html
 <!-- Option 1: the data-webawesome attribute -->
-<script src="bundle.js" data-webawesome="/path/to/web-awesome/%NPMDIR%"></script>
+<script src="bundle.js" data-webawesome="/path/to/web-awesome/dist"></script>

 <!-- Option 2: the setBasePath() method -->
 <script type="module">
-  import { setBasePath } from '/path/to/web-awesome/%NPMDIR%/webawesome.js';
-  setBasePath('/path/to/web-awesome/%NPMDIR%');
+  import { setBasePath } from '/path/to/web-awesome/dist/webawesome.js';
+  setBasePath('/path/to/web-awesome/dist');
 </script>
 ```

@@ -44,7 +55,7 @@ Most of the magic behind assets is handled internally by Web Awesome, but if you

 ```html
 <script type="module">
-  import { getBasePath, setBasePath } from '/path/to/web-awesome/%NPMDIR%/webawesome.js';
+  import { getBasePath, setBasePath } from '/path/to/web-awesome/dist/webawesome.js';

  setBasePath('/path/to/assets');

@@ -68,8 +79,8 @@ Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You

 <!-- Option 2: the setKitCode() method -->
 <script type="module">
-  import { setKitCode } from '/path/to/web-awesome/%NPMDIR%/webawesome.js';
-  setBasePath('/path/to/web-awesome/%NPMDIR%');
+  import { setKitCode } from '/path/to/web-awesome/dist/webawesome.js';
+  setBasePath('/path/to/web-awesome/dist');
 </script>
 ```

@@ -80,10 +91,10 @@ Cherry picking will only the components you need up front, while limiting the nu
 Here's an example that loads only the button component.

 ```html
-<link rel="stylesheet" href="/path/to/web-awesome/%NPMDIR%/themes/default.css" />
+<link rel="stylesheet" href="/path/to/web-awesome/dist/themes/default.css" />

-<script type="module" data-webawesome="/path/to/web-awesome/%NPMDIR%">
-  import '/path/to/web-awesome/%NPMDIR%/components/button/button.js';
+<script type="module" data-webawesome="/path/to/web-awesome/dist">
+  import '/path/to/web-awesome/dist/components/button/button.js';

  // <wa-button> is ready to use!
 </script>
--- a/docs/docs/localization.md
+++ b/docs/docs/localization.md
@@ -22,12 +22,43 @@ Through the magic of a mutation observer, changing the `lang` attribute will aut

 ## Available Translations

-Web Awesome ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation. To see a list of all available translations in the latest version, [refer to this directory](https://github.com/shoelace-style/shoelace/tree/current/src/translations).
+Web Awesome ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation.

-The location of translations depends on how you're consuming Web Awesome.
+Available translations include:

- If you're using the CDN, [import them from the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace?path=%CDNDIR%%2Ftranslations)
- If you're using a bundler, import them from `@shoelace-style/shoelace/%NPMDIR%/translations/[lang].js`
+<div style="columns: 3; gap: 1rem; margin-block-end: 1.5rem;">
+
+- ar
+- da
+- de-ch
+- de
+- en-gb
+- en
+- es
+- fa
+- fr
+- he
+- hr
+- hu
+- id
+- ja
+- nl
+- pl
+- pt
+- ru
+- sl
+- sv
+- tr
+- zh-cn
+- zh-tw
+
+</div>
+
+You can import translations using the following syntax, where `<code>` is replaced with any language code shown above.
+
+```js
+import '{% cdnUrl "dist/translations/<code>.js" %}';
+```

 You do not need to load translations up front. You can import them dynamically even after updating the `lang` attribute. Once a translation is registered, localized components will update automatically.

@@ -98,9 +129,9 @@ You can provide your own translations if you have specific needs or if you don't

 Let's create a Spanish translation as an example. The following assumes you're using TypeScript, but you can also create translations with regular JavaScript.

-```js
-import { registerTranslation } from '@shoelace-style/shoelace/dist/utilities/localize';
-import type { Translation } from '@shoelace-style/shoelace/dist/utilities/localize';
+```ts
+import { registerTranslation } from 'path/to/webawesome/dist/utilities/localize';
+import type { Translation } from 'path/to/webawesome/dist/utilities/localize';

 const translation: Translation = {
  $code: 'es',
--- a/docs/docs/themes.md
+++ b/docs/docs/themes.md
@@ -9,7 +9,7 @@ Web Awesome is designed to be highly customizable through pure CSS. Out of the b
 In essence, a theme is a stylesheet that uses the Web Awesome API to define custom properties and apply custom styles to components. To create a theme, you will need a decent understanding of CSS, including [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and the [`::part` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).

 :::info
-For component developers, built-in themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `/%NPMDIR%/themes/*.styles.js`.
+For component developers, built-in themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `/dist/themes/*.styles.js`.
 :::

 ## Theme Basics
@@ -34,7 +34,7 @@ To activate a theme, import it and apply the theme's class to the `<html>` eleme
 ```html
 <html class="wa-theme-default-dark">
  <head>
-    <link rel="stylesheet" href="path/to/webawesome/%NPMDIR%/themes/default.css" />
+    <link rel="stylesheet" href="path/to/webawesome/dist/themes/default.css" />
  </head>

  <body>
@@ -54,7 +54,7 @@ You can activate different themes and styles on various containers throughout th
 ```html
 <html>
  <head>
-    <link rel="stylesheet" href="path/to/shoelace/%NPMDIR%/themes/default.css" />
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/default.css" />
  </head>

  <body>