update docs

2023-06-12 12:48:15 -04:00 · 2023-06-12 12:48:15 -04:00 · 68b982a744
commit 68b982a744
--- a/cspell.json
+++ b/cspell.json
@ -18,6 +18,7 @@
    "CACHEABLE",
    "callout",
    "callouts",
+    "cdndir",
    "chatbubble",
    "checkmark",
    "claviska",
--- a/docs/_includes/component.njk
+++ b/docs/_includes/component.njk
@ -39,15 +39,15 @@
    {% if component.summary %}
      {{ component.summary | markdownInline | safe }}
    {% endif %}
-  </p>  
-  
+  </p>
+
  {# Markdown content #}
  {{ content | safe }}

  {# Importing #}
  <h2>Importing</h2>
  <p>
-    If you're using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use 
+    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>

@ -59,18 +59,18 @@

    <sl-tab-panel name="script">
      <p>
-        To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">the CDN</a> 
+        To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">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/@shoelace-style/shoelace@{{ meta.version }}/dist/{{ component.path }}&quot;&gt;&lt;/script&gt;</code></pre>
+      <pre><code class="language-html">&lt;script type=&quot;module&quot; src=&quot;https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/cdn/{{ component.path }}&quot;&gt;&lt;/script&gt;</code></pre>
    </sl-tab-panel>

    <sl-tab-panel name="import">
      <p>
-        To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">the CDN</a> 
+        To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">the CDN</a>
        using a JavaScript import:
      </p>
-      <pre><code class="language-js">import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/dist/{{ component.path }}';</code></pre>
+      <pre><code class="language-js">import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/cdn/{{ component.path }}';</code></pre>
    </sl-tab-panel>

    <sl-tab-panel name="bundler">
@ -337,11 +337,11 @@
    <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 %}
+{% endblock %}
--- a/docs/assets/scripts/code-previews.js
+++ b/docs/assets/scripts/code-previews.js
@ -180,7 +180,7 @@
      // HTML templates
      if (!isReact) {
        htmlTemplate =
-          `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/dist/shoelace.js"></script>\n` +
+          `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/cdn/shoelace.js"></script>\n` +
          `\n${htmlExample}`;
        jsTemplate = '';
      }
@ -191,7 +191,7 @@
        jsTemplate =
          `import React from 'https://cdn.skypack.dev/react@${reactVersion}';\n` +
          `import ReactDOM from 'https://cdn.skypack.dev/react-dom@${reactVersion}';\n` +
-          `import { setBasePath } from 'https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}/dist/utilities/base-path';\n` +
+          `import { setBasePath } from 'https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}/cdn/utilities/base-path';\n` +
          `\n` +
          `// Set the base path for Shoelace assets\n` +
          `setBasePath('https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}/dist/')\n` +
@ -202,7 +202,7 @@

      // CSS templates
      cssTemplate =
-        `@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/dist/themes/${
+        `@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/cdn/themes/${
          isDark ? 'dark' : 'light'
        }.css';\n` +
        '\n' +
--- a/docs/pages/frameworks/angular.md
+++ b/docs/pages/frameworks/angular.md
@ -22,7 +22,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin
 import '@shoelace-style/shoelace/dist/themes/light.css';
 import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';

-setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
+setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/');
 ```

 :::tip
@ -85,4 +85,4 @@ Now you can start using Shoelace components in your app!

 :::tip
 Are you using Shoelace with Angular? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md)
-:::
+:::
--- a/docs/pages/frameworks/react.md
+++ b/docs/pages/frameworks/react.md
@ -23,7 +23,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin
 import '@shoelace-style/shoelace/dist/themes/light.css';
 import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';

-setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
+setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/');
 ```

 :::tip
@ -151,4 +151,4 @@ For more details, refer to Jest's [`transformIgnorePatterns` customization](http

 :::tip
 Are you using Shoelace with React? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/react.md)
-:::
+:::
--- a/docs/pages/frameworks/vue-2.md
+++ b/docs/pages/frameworks/vue-2.md
@ -26,7 +26,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin
 import '@shoelace-style/shoelace/dist/themes/light.css';
 import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';

-setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
+setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/');
 ```

 :::tip
@ -104,4 +104,4 @@ Now you can use the `v-sl-model` directive to keep your data in sync!

 :::tip
 Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue-2.md)
-:::
+:::
--- a/docs/pages/frameworks/vue.md
+++ b/docs/pages/frameworks/vue.md
@ -26,7 +26,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin
 import '@shoelace-style/shoelace/dist/themes/light.css';
 import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';

-setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
+setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/');
 ```

 :::tip
@ -124,4 +124,4 @@ Here is an example:
    <sl-button variant="primary" @click=" drawerIsOpen = false">Close</sl-button>
  </div>
 </sl-drawer>
-```
+```
--- a/docs/pages/getting-started/installation.md
+++ b/docs/pages/getting-started/installation.md
@ -22,8 +22,8 @@ While convenient, autoloading may lead to a [Flash of Undefined Custom Elements]

 <!-- prettier-ignore -->
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css" />
-<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace-autoloader.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/themes/light.css" />
+<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/shoelace-autoloader.js"></script>
 ```

 </sl-tab-panel>
@ -33,8 +33,8 @@ While convenient, autoloading may lead to a [Flash of Undefined Custom Elements]
 The traditional CDN loader registers all Shoelace elements up front. Note that, if you're only using a handful of components, it will be much more efficient to stick with the autoloader. However, you can also [cherry pick](#cherry-picking) components if you want to load specific ones up front.

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

 </sl-tab-panel>
@ -45,7 +45,7 @@ The traditional CDN loader registers all Shoelace elements up front. Note that,
 The code above will load the light theme. If you want to use the [dark theme](/getting-started/themes#dark-theme) instead, update the stylesheet as shown below and add `<html class="sl-theme-dark">` to your page.

 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/themes/dark.css" />
 ```

 ### Light & Dark Theme
@ -56,21 +56,21 @@ If you want to load the light or dark theme based on the user's `prefers-color-s
 <link
  rel="stylesheet"
  media="(prefers-color-scheme:light)"
-  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css"
+  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/themes/light.css"
 />
 <link
  rel="stylesheet"
  media="(prefers-color-scheme:dark)"
-  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css"
+  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/themes/dark.css"
  onload="document.documentElement.classList.add('sl-theme-dark');"
 />
 ```

 Now you can [start using Shoelace!](/getting-started/usage)

-## Local Installation
+## NPM installation

-If you don't want to use the CDN, you can install Shoelace locally with the following command.
+If you don't want to use the CDN, you can install Shoelace from NPM with the following command.

 ```bash
 npm install @shoelace-style/shoelace
@ -110,20 +110,26 @@ However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Sh
 ```

 :::tip
-The library also exports a `getBasePath()` method you can use to reference assets.
+When setting a basePath, and easy way to check if it was down properly is by checking if an icon exists.
+
+For example, if I set the basePath to `/dist`, I should be able to go to:
+
+`https://<my-site>/dist/assets/icons/arrow-left.svg` and the browser should show me the SVG.
+
+Shoelace also exports a `getBasePath()` method you can use to reference assets.
 :::

 ## Cherry Picking

-Cherry picking can be done from [the CDN](#cdn-installation-easiest) or your [local installation](#local-installation). This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component.
+Cherry picking can be done from [the CDN](#cdn-installation-easiest) or from [NPM](#npm-installation). This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component.

 Here's an example that loads only the button component. Again, if you're not using a module resolver, you'll need to adjust the path to point to the folder Shoelace is in.

 ```html
-<link rel="stylesheet" href="/path/to/shoelace/dist/themes/light.css" />
+<link rel="stylesheet" href="/path/to/shoelace/cdn/themes/light.css" />

 <script type="module" data-shoelace="/path/to/shoelace/dist">
-  import '@shoelace-style/shoelace/dist/components/button/button.js';
+  import '@shoelace-style/shoelace/cdn/components/button/button.js';

  // <sl-button> is ready to use!
 </script>
@ -173,3 +179,19 @@ setBasePath('/path/to/shoelace/dist');
 :::warning
 Component modules include side effects for registration purposes. Because of this, importing directly from `@shoelace-style/shoelace` may result in a larger bundle size than necessary. For optimal tree shaking, always cherry pick, i.e. import components and utilities from their respective files, as shown above.
 :::
+
+## The difference between CDN and NPM
+
+You'll notice above that the CDN links all start with `/cdn/<path>` and imports using NPM use `/dist/<path>`.
+The `/cdn` files use a different bundle from `/dist`. `/cdn` files come "prebundled" which means all dependencies are
+inlined so you do not need to worry about loading any additional libraries. `/dist` does **NOT** prebundle dependencies
+allowing for your bundler of choice to more efficiently deduplicate dependencies resulting in smaller overall bundles
+and greater code sharing.
+
+TLDR:
+
+- `@shoelace-style/shoelace/cdn` is for CDN
+- `@shoelace-style/shoelace/dist` is for NPM
+
+This change was introduced in `v2.5.0` to address issues around installations from NPM
+loading multiple versions of libraries such as the Lit  web component library which Shoelace uses internally.
--- a/docs/pages/getting-started/themes.md
+++ b/docs/pages/getting-started/themes.md
@ -127,7 +127,7 @@ The dark theme works by taking the light theme's [color tokens](/tokens/color) a
 To install the dark theme, add the following to the `<head>` section of your page.

 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/themes/dark.css" />
 ```

 To activate the theme, apply the `sl-theme-dark` class to the `<html>` element.
@ -146,4 +146,4 @@ Shoelace doesn't try to auto-detect the user's light/dark mode preference. This
 - Allow the user to override the setting in your app
 - Remember the user's preference and restore it on subsequent logins

-Shoelace avoids using the `prefers-color-scheme` media query because not all apps support dark mode, and it would break things for the ones that don't.
+Shoelace avoids using the `prefers-color-scheme` media query because not all apps support dark mode, and it would break things for the ones that don't.
--- a/docs/pages/index.md
+++ b/docs/pages/index.md
@ -41,8 +41,8 @@ Add the following code to your page.

 <!-- prettier-ignore -->
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css" />
-<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace-autoloader.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/themes/light.css" />
+<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/shoelace-autoloader.js"></script>
 ```

 Now you have access to all of Shoelace's components! Try adding a button:
@ -137,4 +137,4 @@ Special thanks to the following projects and individuals that help make Shoelace
 - Positioning of dropdowns, tooltips, et al is handled by [Floating UI](https://floating-ui.com/)
 - Animations are courtesy of [animate.css](https://animate.style/)
 - Search is powered by [Lunr](https://lunrjs.com/)
- The Shoelace logo was designed with a single shoelace by [Adam K Olson](https://twitter.com/adamkolson)
+- The Shoelace logo was designed with a single shoelace by [Adam K Olson](https://twitter.com/adamkolson)