polymorph-ui-components 0.6.2 → 0.8.0

package/README.md

@@ -138,8 +138,15 @@ Each component documents its **complete** variable surface in [`docs/`](docs/).
 
 The same components compile to **framework-agnostic custom elements** — theming works identically because it's pure CSS.
 
+### From a CDN — no build step, no install
+
+The bundle is self-contained (the Svelte runtime is compiled in) and registers every `<pui-*>` element on import, so a single `<script>` tag in a plain `.html` file is enough:
+
 ```html
-<script type="module" src="polymorph-ui-components/wc"></script>
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/polymorph-ui-components@latest/dist-wc/index.js"
+></script>
 
 <pui-button text="Save"></pui-button>
 <pui-input placeholder="Search…"></pui-input>
@@ -152,7 +159,24 @@ The same components compile to **framework-agnostic custom elements** — themin
 </style>
 ```
 
-Drop them into React, Vue, Angular, Astro, or a plain `.html` file — no build step required.
+Pin an exact version for production — `…/polymorph-ui-components@<version>/dist-wc/index.js` — so a release can never change your page underneath you. [unpkg](https://unpkg.com) serves the same path if you prefer it:
+
+```
+https://cdn.jsdelivr.net/npm/polymorph-ui-components@<version>/dist-wc/index.js
+https://unpkg.com/polymorph-ui-components@<version>/dist-wc/index.js
+```
+
+### From npm, through a bundler
+
+```bash
+npm install polymorph-ui-components
+```
+
+```js
+import 'polymorph-ui-components/wc';
+```
+
+Either way, drop them into React, Vue, Angular, Astro, or a plain `.html` file.
 
 ---
 
@@ -200,6 +224,7 @@ Now you can ask: _"Using the polymorph-ui MCP, theme the Select to match my bran
 | **SplitInput**  | Segmented input (OTP / PIN) with paste distribution and auto-advance.                                                | [docs](docs/SplitInput.md)  |
 | **ColorPicker** | HSV color picker with pointer-drag saturation panel and hue slider.                                                  | [docs](docs/ColorPicker.md) |
 | **Calendar**    | Date / range picker with roving-tabindex grid and `Intl` formatting.                                                 | [docs](docs/Calendar.md)    |
+| **NumberStepper** | − value + control for quantities; shows a loader while an async `onchange` settles.                                | [docs](docs/NumberStepper.md) |
 
 </details>
 
@@ -209,7 +234,7 @@ Now you can ask: _"Using the polymorph-ui MCP, theme the Select to match my bran
 | Component                                 | Description                                                                                           |                                |
 | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------ |
 | **Modal**                                 | Dialog overlay with size/alignment, header, footer, transitions, scroll-lock, and back-press support. | [docs](docs/Modal.md)          |
-| **Sheet**                                 | Slide-in panel from any edge with header, scrollable body, footer, and focus trap.                    | [docs](docs/Sheet.md)          |
+| **Sheet**                                 | Slide-in panel from any edge with header, scrollable body, footer, focus trap and focus return.       | [docs](docs/Sheet.md)          |
 | **Menu**                                  | Dropdown action menu with keyboard navigation, typeahead, disabled/danger items, and separators.      | [docs](docs/Menu.md)           |
 | **ContextMenu**                           | Right-click menu with separators, disabled/danger items, and keyboard navigation.                     | [docs](docs/ContextMenu.md)    |
 | **CommandMenu**                           | Command palette (Ctrl/Cmd+K) with search, grouped commands, and keyboard navigation.                  | [docs](docs/CommandMenu.md)    |
@@ -244,7 +269,7 @@ Now you can ask: _"Using the polymorph-ui MCP, theme the Select to match my bran
 | **Pagination**         | Windowed page navigation with ellipsis truncation.                   | [docs](docs/Pagination.md)    |
 | **Stepper** / **Step** | Multi-step progress indicator with completed/active/pending states.  | [docs](docs/Stepper.md)       |
 | **Accordion**          | Collapsible container with CSS grid animation.                       | [docs](docs/Accordion.md)     |
-| **Carousel**           | Swipeable content slider with autoplay and pagination dots.          | [docs](docs/Carousel.md)      |
+| **Carousel**           | Swipeable slider with snippet or component slides, arrows, dots, seamless looping and autoplay that pauses on hover/focus. | [docs](docs/Carousel.md)      |
 | **Scroller**           | Overflowing list with arrow nav, gradient edges, and drag-to-scroll. | [docs](docs/Scroller.md)      |
 | **CheckListItem**      | Checklist row with checkbox, label, and checked state.               | [docs](docs/CheckListItem.md) |
 | **Toolbar**            | Header bar with back button, title, and customizable content areas.  | [docs](docs/Toolbar.md)       |
@@ -259,7 +284,7 @@ Now you can ask: _"Using the polymorph-ui MCP, theme the Select to match my bran
 | ------------------------------------------ | ----------------------------------------------------------------------- | ------------------------ |
 | **Toast**                                  | Animated slide-in notification with auto-dismiss and per-direction fly. | [docs](docs/Toast.md)    |
 | **Banner**                                 | Notification banner with icon snippet, link text, and dismiss.          | [docs](docs/Banner.md)   |
-| **Progress**                               | Animated horizontal progress bar (determinate / indeterminate).         | [docs](docs/Progress.md) |
+| **Progress**                               | Animated progress bar (determinate / indeterminate) with optional milestones. | [docs](docs/Progress.md) |
 | **Gauge**                                  | Full-circle ring gauge (0–100) with animated SVG arc.                   | [docs](docs/Gauge.md)    |
 | **Loader** / **LoadingDots** / **Shimmer** | Spinner, animated dots, and skeleton shimmer — all CSS-variable themed. | [docs](docs/Loader.md)   |
 

package/dist/Button/Button.svelte

@@ -110,9 +110,9 @@
     cursor: var(--button-disabled-cursor, not-allowed);
     opacity: var(--button-disabled-opacity, 0.4);
     color: var(--button-disabled-text-color, var(--button-text-color, #ffffff));
-    font-size: var(--button-disabled-font-size);
-    font-weight: var(--button-disabled-font-weight);
-    border: var(--button-disabled-border);
+    font-size: var(--button-disabled-font-size, var(--button-font-size, 14px));
+    font-weight: var(--button-disabled-font-weight, var(--button-font-weight, 500));
+    border: var(--button-disabled-border, var(--button-border, none));
     background: var(--button-disabled-background-color, var(--button-color, #18181b));
     text-decoration: var(--button-disabled-text-decoration, var(--button-text-decoration, none));
   }
@@ -131,7 +131,7 @@
     display: var(--button-text-display);
   }
 
-  button:hover {
+  button:hover:not(:disabled) {
     background: var(--button-hover-color, var(--button-color, #18181b));
     color: var(--button-hover-text-color, var(--button-text-color, #ffffff));
     border: var(--button-hover-border, var(--button-border, none));
@@ -139,7 +139,7 @@
     opacity: var(--button-hover-opacity, var(--button-opacity, 1));
   }
 
-  button:active {
+  button:active:not(:disabled) {
     transform: var(--button-active-transform);
   }
 

package/dist/Carousel/Carousel.svelte

@@ -1,180 +1,298 @@
 <script lang="ts">
-  import { onMount, onDestroy } from 'svelte';
+  import { flushSync } from 'svelte';
   import type { CarouselProperties } from './properties';
+  import Button from '../Button/Button.svelte';
+  import chevronLeftSvg from '../assets/chevron-left.svg?raw';
+  import chevronRightSvg from '../assets/chevron-right.svg?raw';
+
+  type Rotation = { enabled: boolean; interval: number; restarts: number };
 
   let {
-    views,
+    views = [],
+    count = 0,
+    slide,
     autoplay = false,
     autoplayInterval = 1000,
     showDots = false,
+    showArrows = false,
     isScrollableLast = false,
+    loop = false,
+    announce = true,
+    ariaLabel = 'Carousel',
+    previousLabel = 'Previous slide',
+    nextLabel = 'Next slide',
+    previousIcon,
+    nextIcon,
     testId,
     onkeydown,
     classes
   }: CarouselProperties = $props();
 
   let slidesDiv: HTMLDivElement | null = $state(null);
-  let intervalId: number;
-  let endTouch: number;
-  let startTouch: number;
-  let startMouse: number;
-  let endMouse: number;
-  let carouselWidth: string;
-  let carouselDiv: HTMLDivElement | null = $state(null);
-  let activeSlideIndex = $state(0);
-  let widthUnits: string;
+  let requestedIndex = $state(0);
+  let edge = $state<'none' | 'before' | 'after'>('none');
+  let hovered = $state(false);
+  let focused = $state(false);
+  let animate = $state(true);
+  let restarts = $state(0);
 
-  function handleDotKeydown(event: KeyboardEvent, index: number) {
-    if (event.key === 'Enter' || event.key === ' ') {
-      event.preventDefault();
-      moveSlideToIndex(index);
+  let total = $derived(typeof slide === 'function' ? count : views.length);
+  let activeSlideIndex = $derived(Math.min(requestedIndex, Math.max(total - 1, 0)));
+  let wraps = $derived(isScrollableLast || loop);
+  let seamless = $derived(loop && total > 1);
+  let trackPosition = $derived.by(() => {
+    if (!seamless) {
+      return activeSlideIndex;
     }
-    onkeydown?.(event);
-  }
-
-  function nextSlide() {
-    if (activeSlideIndex != views.length - 1 || isScrollableLast) {
-      activeSlideIndex++;
-      changeCurrentSlide();
-      if (autoplay) {
-        resetInterval();
-      }
+    if (edge === 'before') {
+      return 0;
     }
+    if (edge === 'after') {
+      return total + 1;
+    }
+    return activeSlideIndex + 1;
+  });
+  let rotating = $derived(autoplay && total > 1 && !hovered && !focused);
+
+  function hasTransition(): boolean {
+    return slidesDiv !== null && parseFloat(getComputedStyle(slidesDiv).transitionDuration) > 0;
   }
 
-  function previousSlide() {
-    if (activeSlideIndex != 0 || isScrollableLast) {
-      activeSlideIndex--;
-      changeCurrentSlide();
-      if (autoplay) {
-        resetInterval();
-      }
+  function snapFromClone() {
+    animate = false;
+    edge = 'none';
+    flushSync();
+    // Reading layout commits the jump before the transition is switched back on.
+    if (slidesDiv !== null) {
+      void slidesDiv.offsetWidth;
     }
+    animate = true;
   }
 
-  function changeCurrentSlide() {
-    if (activeSlideIndex > views.length - 1) {
-      activeSlideIndex = 0;
-    } else if (activeSlideIndex < 0) {
-      activeSlideIndex = views.length - 1;
+  function moveTo(target: number) {
+    if (edge !== 'none') {
+      snapFromClone();
+    }
+    if (wraps) {
+      requestedIndex = ((target % total) + total) % total;
+      edge = seamless && target < 0 ? 'before' : seamless && target >= total ? 'after' : 'none';
+    } else {
+      requestedIndex = Math.min(total - 1, Math.max(0, target));
     }
-    if (slidesDiv) {
-      slidesDiv.style.transform = `translateX(${
-        -activeSlideIndex * parseInt(carouselWidth)
-      }${widthUnits})`;
+    flushSync();
+    if (edge !== 'none' && !hasTransition()) {
+      snapFromClone();
     }
   }
 
-  function moveSlideToIndex(index: number) {
-    activeSlideIndex = index;
-    changeCurrentSlide();
+  function navigate(target: number) {
+    moveTo(target);
+    restarts += 1;
   }
 
-  function resetInterval() {
-    clearInterval(intervalId);
-    intervalId = window.setInterval(nextSlide, autoplayInterval);
+  function handleTransitionEnd(event: TransitionEvent) {
+    if (event.target === slidesDiv && event.propertyName === 'transform' && edge !== 'none') {
+      snapFromClone();
+    }
   }
 
-  function handleTouchStart(event: TouchEvent) {
-    if (event.touches.length > 0) {
-      const touch = event.touches.item(0);
-      if (touch !== null) {
-        startTouch = touch.clientX;
-      }
+  function handleDotKeydown(event: KeyboardEvent, index: number) {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      navigate(index);
     }
+    onkeydown?.(event);
   }
 
-  function handleTouchEnd(event: TouchEvent) {
-    if (event.changedTouches.length > 0) {
-      const changedTouch = event.changedTouches.item(0);
-      if (changedTouch !== null) {
-        endTouch = changedTouch.clientX;
-        if (startTouch - endTouch > 20) {
-          nextSlide();
-        } else {
-          if (endTouch - startTouch > 20) {
-            previousSlide();
-          }
-        }
-      }
+  function nextSlide() {
+    if (activeSlideIndex !== total - 1 || wraps) {
+      navigate(activeSlideIndex + 1);
     }
   }
 
-  function handleMouseDown(event: MouseEvent) {
-    if (typeof event.clientX !== 'undefined') {
-      startMouse = event.clientX;
+  function previousSlide() {
+    if (activeSlideIndex !== 0 || wraps) {
+      navigate(activeSlideIndex - 1);
     }
   }
 
-  function handeMouseUp(event: MouseEvent) {
-    if (typeof event.clientX !== 'undefined') {
-      endMouse = event.clientX;
-      if (startMouse - endMouse > 20) {
-        nextSlide();
-      } else {
-        if (endMouse - startMouse > 20) {
-          previousSlide();
-        }
-      }
+  function advance() {
+    if (rotating) {
+      moveTo(activeSlideIndex + 1);
     }
   }
 
-  function setWidthUnit(carouselWidth: string) {
-    widthUnits = carouselWidth.slice(-3);
-    if (/^-?\d+$/.test(widthUnits.at(0) ?? '')) {
-      widthUnits = widthUnits.slice(-2);
-    }
+  function rotation(_node: HTMLElement, initial: Rotation) {
+    let timer: number | null = null;
+    const stop = () => {
+      if (timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+    };
+    const start = (settings: Rotation) => {
+      stop();
+      if (settings.enabled) {
+        timer = window.setInterval(advance, settings.interval);
+      }
+    };
+    start(initial);
+    return { update: start, destroy: stop };
   }
 
-  onMount(() => {
-    if (carouselDiv) {
-      carouselWidth = getComputedStyle(carouselDiv).getPropertyValue('--carousel-width');
-      setWidthUnit(carouselWidth);
-      carouselDiv.addEventListener('touchstart', handleTouchStart);
-      carouselDiv.addEventListener('touchend', handleTouchEnd);
-      carouselDiv.addEventListener('mousedown', handleMouseDown);
-      carouselDiv.addEventListener('mouseup', handeMouseUp);
-    }
-    if (autoplay) {
-      intervalId = window.setInterval(nextSlide, autoplayInterval);
-    }
-  });
+  function swipe(node: HTMLElement) {
+    let startX = 0;
+    const finish = (endX: number) => {
+      if (startX - endX > 20) {
+        nextSlide();
+      } else if (endX - startX > 20) {
+        previousSlide();
+      }
+    };
+    const touchStart = (event: TouchEvent) => {
+      const touch = event.touches.item(0);
+      if (touch !== null) {
+        startX = touch.clientX;
+      }
+    };
+    const touchEnd = (event: TouchEvent) => {
+      const touch = event.changedTouches.item(0);
+      if (touch !== null) {
+        finish(touch.clientX);
+      }
+    };
+    const mouseDown = (event: MouseEvent) => {
+      startX = event.clientX;
+    };
+    const mouseUp = (event: MouseEvent) => {
+      finish(event.clientX);
+    };
+    node.addEventListener('touchstart', touchStart);
+    node.addEventListener('touchend', touchEnd);
+    node.addEventListener('mousedown', mouseDown);
+    node.addEventListener('mouseup', mouseUp);
+    return {
+      destroy() {
+        node.removeEventListener('touchstart', touchStart);
+        node.removeEventListener('touchend', touchEnd);
+        node.removeEventListener('mousedown', mouseDown);
+        node.removeEventListener('mouseup', mouseUp);
+      }
+    };
+  }
 
-  onDestroy(() => {
-    if (autoplay) {
-      clearInterval(intervalId);
+  function handleFocusOut(event: FocusEvent) {
+    const container = event.currentTarget;
+    if (
+      container instanceof Node &&
+      event.relatedTarget instanceof Node &&
+      container.contains(event.relatedTarget)
+    ) {
+      return;
     }
-  });
+    focused = false;
+  }
 </script>
 
-<div class="carousel-container {classes ?? ''}" data-pw={testId}>
-  {#if views.length > 0}
-    <div class="carousel" bind:this={carouselDiv}>
-      <div class="slidesDiv" bind:this={slidesDiv}>
-        {#each views as view, index (index)}
-          <div class="current-slide">
-            {#if typeof view.properties === 'object'}
-              <view.component properties={view.properties} />
+{#snippet renderSlide(index: number)}
+  {#if typeof slide === 'function'}
+    {@render slide(index)}
+  {:else}
+    {@const view = views.at(index)}
+    {#if typeof view === 'object'}
+      {#if typeof view.properties === 'object'}
+        <view.component properties={view.properties} />
+      {:else}
+        <view.component />
+      {/if}
+    {/if}
+  {/if}
+{/snippet}
+
+<div
+  class="carousel-container {classes ?? ''}"
+  role="region"
+  aria-roledescription="carousel"
+  aria-label={ariaLabel}
+  data-pw={testId}
+  use:rotation={{ enabled: autoplay && total > 1, interval: autoplayInterval, restarts }}
+  onmouseenter={() => (hovered = true)}
+  onmouseleave={() => (hovered = false)}
+  onfocusin={() => (focused = true)}
+  onfocusout={handleFocusOut}
+>
+  {#if total > 0}
+    <div class="carousel-row">
+      {#if showArrows && total > 1}
+        <div class="carousel-arrow">
+          <Button ariaLabel={previousLabel} onclick={previousSlide}>
+            {#if typeof previousIcon === 'function'}
+              {@render previousIcon()}
             {:else}
-              <view.component />
+              <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+              {@html chevronLeftSvg}
             {/if}
-          </div>
-        {/each}
+          </Button>
+        </div>
+      {/if}
+      <div class="carousel" use:swipe>
+        <div
+          class="slidesDiv"
+          class:animate
+          bind:this={slidesDiv}
+          style:transform="translateX({-trackPosition * 100}%)"
+          aria-live={announce && !rotating ? 'polite' : 'off'}
+          ontransitionend={handleTransitionEnd}
+        >
+          {#if seamless}
+            <div class="current-slide" aria-hidden="true" inert>
+              {@render renderSlide(total - 1)}
+            </div>
+          {/if}
+          {#each { length: total } as _, index (index)}
+            <div
+              class="current-slide"
+              role="group"
+              aria-roledescription="slide"
+              aria-label="{index + 1} of {total}"
+              aria-hidden={index !== activeSlideIndex}
+              inert={index !== activeSlideIndex}
+            >
+              {@render renderSlide(index)}
+            </div>
+          {/each}
+          {#if seamless}
+            <div class="current-slide" aria-hidden="true" inert>
+              {@render renderSlide(0)}
+            </div>
+          {/if}
+        </div>
       </div>
+      {#if showArrows && total > 1}
+        <div class="carousel-arrow">
+          <Button ariaLabel={nextLabel} onclick={nextSlide}>
+            {#if typeof nextIcon === 'function'}
+              {@render nextIcon()}
+            {:else}
+              <!-- eslint-disable-next-line svelte/no-at-html-tags -->
+              {@html chevronRightSvg}
+            {/if}
+          </Button>
+        </div>
+      {/if}
     </div>
   {/if}
   {#if showDots}
     <div class="dots-wrapper">
-      <!-- eslint-disable-next-line -->
-      {#each views as _, index}
+      {#each { length: total } as _, index (index)}
         <div
-          class={activeSlideIndex == index ? 'active-dot' : 'dot'}
-          onclick={() => moveSlideToIndex(index)}
+          class={activeSlideIndex === index ? 'active-dot' : 'dot'}
+          onclick={() => navigate(index)}
           onkeydown={(event) => handleDotKeydown(event, index)}
           role="button"
           tabindex="0"
           aria-label={`Go to slide ${index + 1}`}
-          aria-current={activeSlideIndex == index}
+          aria-current={activeSlideIndex === index}
         ></div>
       {/each}
     </div>
@@ -185,15 +303,21 @@
   .carousel-container {
     width: var(--carousel-width);
   }
+  .carousel-row {
+    display: flex;
+    align-items: center;
+    gap: var(--carousel-arrow-gap, 8px);
+  }
   .current-slide {
-    width: var(--carousel-width, 300px);
+    width: 100%;
     height: var(--carousel-height, 100px);
     flex-shrink: 0;
   }
   .carousel {
     box-shadow: var(--carousel-shadow);
     height: var(--carousel-height, 100px);
-    width: var(--carousel-width, 300px);
+    flex: 0 1 var(--carousel-width, 300px);
+    min-width: 0;
     overflow: hidden;
     border-radius: var(--carousel-border-radius, 0%);
   }
@@ -202,8 +326,24 @@
   }
   .slidesDiv {
     display: flex;
-    transform: translateX(0);
-    transition: transform 0.5s ease-in-out;
+  }
+  .slidesDiv.animate {
+    transition: transform var(--carousel-transition-duration, 0.5s)
+      var(--carousel-transition-easing, ease-in-out);
+  }
+  .carousel-arrow {
+    --button-color: var(--carousel-arrow-background, transparent);
+    --button-text-color: var(--carousel-arrow-color, currentColor);
+    --button-hover-color: var(--carousel-arrow-hover-background, transparent);
+    --button-padding: var(--carousel-arrow-padding, 4px);
+    --button-border: var(--carousel-arrow-border, none);
+    --button-border-radius: var(--carousel-arrow-border-radius, 999px);
+    display: flex;
+    flex-shrink: 0;
+  }
+  .carousel-arrow :global(svg) {
+    width: var(--carousel-arrow-size, 16px);
+    height: var(--carousel-arrow-size, 16px);
   }
   .dots-wrapper {
     gap: var(--carousel-dot-gap, 10px);
@@ -228,31 +368,12 @@
     background: var(--carousel-active-dot-color, currentColor);
     transition: 0.3s ease;
   }
-  /*
-  @media only screen and (max-width: 324px) {
 
-    .carousel-container {
-      width:270px;
-
-    }
-    .current-slide {
-    width: 270px;
-    }
-    .carousel {
-      width:270px;
+  @media (prefers-reduced-motion: reduce) {
+    .slidesDiv.animate,
+    .dot,
+    .active-dot {
+      transition-duration: 0s;
     }
   }
-
-  @media only screen and (max-width: 269px) {
-    .carousel-container {
-      width:240px;
-    }
-    .current-slide {
-    width: 240px;
-    }
-    .carousel {
-      width:240px;
-    }
-
-  } */
 </style>

package/dist/Carousel/properties.d.ts

@@ -1,17 +1,29 @@
-import type { Component } from 'svelte';
+import type { Component, Snippet } from 'svelte';
 export type CarouselView = {
     properties?: Record<string, unknown>;
     component: Component<Record<string, unknown>>;
 };
-export type CarouselProperties = CarouselEventProperties & OptionalCarouselProperties & MandatoryCarouselProperties;
+export type CarouselProperties = CarouselEventProperties & OptionalCarouselProperties;
+/** @deprecated `views` is optional now that slides can also come from the `slide` snippet. */
 export type MandatoryCarouselProperties = {
     views: CarouselView[];
 };
 export type OptionalCarouselProperties = {
+    views?: CarouselView[];
+    count?: number;
+    slide?: Snippet<[number]>;
     autoplay?: boolean;
     autoplayInterval?: number;
     showDots?: boolean;
+    showArrows?: boolean;
     isScrollableLast?: boolean;
+    loop?: boolean;
+    announce?: boolean;
+    ariaLabel?: string;
+    previousLabel?: string;
+    nextLabel?: string;
+    previousIcon?: Snippet;
+    nextIcon?: Snippet;
     testId?: string;
     classes?: string;
 };

package/dist/Combobox/Combobox.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { ComboboxProperties } from './properties';
 declare const Combobox: import("svelte").Component<ComboboxProperties, {
     getInputRef: () => HTMLInputElement | HTMLTextAreaElement | null;
-}, "value" | "open" | "inputValue" | "highlightedIndex">;
+}, "open" | "value" | "inputValue" | "highlightedIndex">;
 type Combobox = ReturnType<typeof Combobox>;
 export default Combobox;