Merge cd408e7b21 into c31d4f5855

It's not clear In [Vue Guide](https://shoelace.style/frameworks/vue#installation), the user may not know where to apply the theme and base path set, so I add file hint like [React Guide](https://shoelace.style/frameworks/react#installation)

docs/pages/components/alert.md

@@ -247,6 +247,69 @@ const App = () => {
 };
 ```
 
+### Countdown
+
+Set the `countdown` attribute to display a loading bar that indicates the alert remaining time. This is useful for alerts with relatively long duration.
+
+```html:preview
+<div class="alert-countdown">
+  <sl-button variant="primary">Show Alert</sl-button>
+
+  <sl-alert variant="primary" duration="10000" countdown="rtl" closable>
+    <sl-icon slot="icon" name="info-circle"></sl-icon>
+    You're not stuck, the alert will close after a pretty long duration.
+  </sl-alert>
+</div>
+
+<script>
+  const container = document.querySelector('.alert-countdown');
+  const button = container.querySelector('sl-button');
+  const alert = container.querySelector('sl-alert');
+
+  button.addEventListener('click', () => alert.show());
+</script>
+
+<style>
+  .alert-countdown sl-alert {
+    margin-top: var(--sl-spacing-medium);
+  }
+</style>
+```
+
+```jsx:react
+import { useState } from 'react';
+import SlAlert from '@shoelace-style/shoelace/dist/react/alert';
+import SlButton from '@shoelace-style/shoelace/dist/react/button';
+import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+
+const css = `
+  .alert-countdown sl-alert {
+    margin-top: var(--sl-spacing-medium);
+  }
+`;
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <div className="alert-countdown">
+        <SlButton variant="primary" onClick={() => setOpen(true)}>
+          Show Alert
+        </SlButton>
+
+        <SlAlert variant="primary" duration="3000" countdown="rtl" open={open} closable onSlAfterHide={() => setOpen(false)}>
+          <SlIcon slot="icon" name="info-circle" />
+          You're not stuck, the alert will close after a pretty long duration.
+        </SlAlert>
+      </div>
+
+      <style>{css}</style>
+    </>
+  );
+};
+```
+
 ### Toast Notifications
 
 To display an alert as a toast notification, or "toast", create the alert and call its `toast()` method. This will move the alert out of its position in the DOM and into [the toast stack](#the-toast-stack) where it will be shown. Once dismissed, it will be removed from the DOM completely. To reuse a toast, store a reference to it and call `toast()` again later on.

docs/pages/frameworks/vue.md

@@ -23,6 +23,7 @@ npm install @shoelace-style/shoelace
 Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
 
 ```jsx
+// main.js or main.ts
 import '@shoelace-style/shoelace/dist/themes/light.css';
 import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
 

docs/pages/resources/changelog.md

@@ -12,7 +12,7 @@ Components with the <sl-badge variant="warning" pill>Experimental</sl-badge> bad
 
 New versions of Shoelace are released as-needed and generally occur when a critical mass of changes have accumulated. At any time, you can see what's coming in the next release by visiting [next.shoelace.style](https://next.shoelace.style).
 
-## Next
+## 2.15.1
 
 - Fixed a bug in `<sl-radio-group>` where if a click did not contain a `<sl-radio>` it would show a console error. [#2009]
 - Fixed a bug in `<sl-split-panel>` that caused it not to recalculate it's position when going from being `display: none;` to its original display value. [#1942]

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@shoelace-style/shoelace",
-  "version": "2.15.0",
+  "version": "2.15.1",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@shoelace-style/shoelace",
-      "version": "2.15.0",
+      "version": "2.15.1",
       "license": "MIT",
       "dependencies": {
         "@ctrl/tinycolor": "^4.0.2",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shoelace-style/shoelace",
   "description": "A forward-thinking library of web components.",
-  "version": "2.15.0",
+  "version": "2.15.1",
   "homepage": "https://github.com/shoelace-style/shoelace",
   "author": "Cory LaViska",
   "license": "MIT",

src/components/alert/alert.component.ts

@@ -4,7 +4,7 @@ import { getAnimation, setDefaultAnimation } from '../../utilities/animation-reg
 import { HasSlotController } from '../../internal/slot.js';
 import { html } from 'lit';
 import { LocalizeController } from '../../utilities/localize.js';
-import { property, query } from 'lit/decorators.js';
+import { property, query, state } from 'lit/decorators.js';
 import { waitForEvent } from '../../internal/event.js';
 import { watch } from '../../internal/watch.js';
 import componentStyles from '../../styles/component.styles.js';
@@ -45,11 +45,15 @@ export default class SlAlert extends ShoelaceElement {
   static dependencies = { 'sl-icon-button': SlIconButton };
 
   private autoHideTimeout: number;
+  private remainingTimeInterval: number;
+  private countdownAnimation?: Animation;
   private readonly hasSlotController = new HasSlotController(this, 'icon', 'suffix');
   private readonly localize = new LocalizeController(this);
 
   @query('[part~="base"]') base: HTMLElement;
 
+  @query('.alert__countdown-elapsed') countdownElement: HTMLElement;
+
   /**
    * Indicates whether or not the alert is open. You can toggle this attribute to show and hide the alert, or you can
    * use the `show()` and `hide()` methods and this attribute will reflect the alert's open state.
@@ -69,14 +73,56 @@ export default class SlAlert extends ShoelaceElement {
    */
   @property({ type: Number }) duration = Infinity;
 
+  /**
+   * Enables a countdown that indicates the remaining time the alert will be displayed.
+   * Typically used to indicate the remaining time before a whole app refresh.
+   */
+  @property({ type: String, reflect: true }) countdown?: 'rtl' | 'ltr';
+
+  @state() private remainingTime = this.duration;
+
   firstUpdated() {
     this.base.hidden = !this.open;
   }
 
   private restartAutoHide() {
+    this.handleCountdownChange();
     clearTimeout(this.autoHideTimeout);
+    clearInterval(this.remainingTimeInterval);
     if (this.open && this.duration < Infinity) {
       this.autoHideTimeout = window.setTimeout(() => this.hide(), this.duration);
+      this.remainingTime = this.duration;
+      this.remainingTimeInterval = window.setInterval(() => {
+        this.remainingTime -= 100;
+      }, 100);
+    }
+  }
+
+  private pauseAutoHide() {
+    this.countdownAnimation?.pause();
+    clearTimeout(this.autoHideTimeout);
+    clearInterval(this.remainingTimeInterval);
+  }
+
+  private resumeAutoHide() {
+    if (this.duration < Infinity) {
+      this.autoHideTimeout = window.setTimeout(() => this.hide(), this.remainingTime);
+      this.remainingTimeInterval = window.setInterval(() => {
+        this.remainingTime -= 100;
+      }, 100);
+      this.countdownAnimation?.play();
+    }
+  }
+
+  private handleCountdownChange() {
+    if (this.open && this.duration < Infinity && this.countdown) {
+      const { countdownElement } = this;
+      const start = '100%';
+      const end = '0';
+      this.countdownAnimation = countdownElement.animate([{ width: start }, { width: end }], {
+        duration: this.duration,
+        easing: 'linear'
+      });
     }
   }
 
@@ -84,10 +130,6 @@ export default class SlAlert extends ShoelaceElement {
     this.hide();
   }
 
-  private handleMouseMove() {
-    this.restartAutoHide();
-  }
-
   @watch('open', { waitUntilFirstUpdate: true })
   async handleOpenChange() {
     if (this.open) {
@@ -109,6 +151,7 @@ export default class SlAlert extends ShoelaceElement {
       this.emit('sl-hide');
 
       clearTimeout(this.autoHideTimeout);
+      clearInterval(this.remainingTimeInterval);
 
       await stopAnimations(this.base);
       const { keyframes, options } = getAnimation(this, 'alert.hide', { dir: this.localize.dir() });
@@ -151,6 +194,7 @@ export default class SlAlert extends ShoelaceElement {
    */
   async toast() {
     return new Promise<void>(resolve => {
+      this.handleCountdownChange();
       if (toastStack.parentElement === null) {
         document.body.append(toastStack);
       }
@@ -188,6 +232,7 @@ export default class SlAlert extends ShoelaceElement {
           alert: true,
           'alert--open': this.open,
           'alert--closable': this.closable,
+          'alert--has-countdown': !!this.countdown,
           'alert--has-icon': this.hasSlotController.test('icon'),
           'alert--primary': this.variant === 'primary',
           'alert--success': this.variant === 'success',
@@ -197,7 +242,8 @@ export default class SlAlert extends ShoelaceElement {
         })}
         role="alert"
         aria-hidden=${this.open ? 'false' : 'true'}
-        @mousemove=${this.handleMouseMove}
+        @mouseenter=${this.pauseAutoHide}
+        @mouseleave=${this.resumeAutoHide}
       >
         <div part="icon" class="alert__icon">
           <slot name="icon"></slot>
@@ -220,6 +266,21 @@ export default class SlAlert extends ShoelaceElement {
               ></sl-icon-button>
             `
           : ''}
+
+        <div role="timer" class="alert__timer">${this.remainingTime}</div>
+
+        ${this.countdown
+          ? html`
+              <div
+                class=${classMap({
+                  alert__countdown: true,
+                  'alert__countdown--ltr': this.countdown === 'ltr'
+                })}
+              >
+                <div class="alert__countdown-elapsed"></div>
+              </div>
+            `
+          : ''}
       </div>
     `;
   }

src/components/alert/alert.styles.ts

@@ -22,6 +22,7 @@ export default css`
     line-height: 1.6;
     color: var(--sl-color-neutral-700);
     margin: inherit;
+    overflow: hidden;
   }
 
   .alert:not(.alert--has-icon) .alert__icon,
@@ -37,6 +38,10 @@ export default css`
     padding-inline-start: var(--sl-spacing-large);
   }
 
+  .alert--has-countdown {
+    border-bottom: none;
+  }
+
   .alert--primary {
     border-top-color: var(--sl-color-primary-600);
   }
@@ -91,4 +96,47 @@ export default css`
     font-size: var(--sl-font-size-medium);
     padding-inline-end: var(--sl-spacing-medium);
   }
+
+  .alert__countdown {
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    width: 100%;
+    height: calc(var(--sl-panel-border-width) * 3);
+    background-color: var(--sl-panel-border-color);
+    display: flex;
+  }
+
+  .alert__countdown--ltr {
+    justify-content: flex-end;
+  }
+
+  .alert__countdown .alert__countdown-elapsed {
+    height: 100%;
+    width: 0;
+  }
+
+  .alert--primary .alert__countdown-elapsed {
+    background-color: var(--sl-color-primary-600);
+  }
+
+  .alert--success .alert__countdown-elapsed {
+    background-color: var(--sl-color-success-600);
+  }
+
+  .alert--neutral .alert__countdown-elapsed {
+    background-color: var(--sl-color-neutral-600);
+  }
+
+  .alert--warning .alert__countdown-elapsed {
+    background-color: var(--sl-color-warning-600);
+  }
+
+  .alert--danger .alert__countdown-elapsed {
+    background-color: var(--sl-color-danger-600);
+  }
+
+  .alert__timer {
+    display: none;
+  }
 `;