@webjsdev/ui 0.3.16 → 0.4.0

package/packages/registry/components/slider.ts

@@ -0,0 +1,333 @@
+/**
+ * Slider: pick a number, or a range, on a track. Tier 1 and Tier 2.
+ *
+ * Tier 1: `sliderClass()` styles one native `<input type="range">`, which is
+ * all a single value needs and works with no JavaScript at all.
+ *
+ * Tier 2: `<ui-slider>` ENHANCES one native range input per thumb (D13). You
+ * author the inputs, so without JavaScript the page shows them and the form
+ * submits them. With JavaScript the element hides them (visually only: they
+ * still submit and reset with the form) and draws shadcn's track, range and
+ * thumbs, writing every move back into the inputs. Two inputs make a range,
+ * and a thumb never passes its neighbour.
+ *
+ * shadcn parity:
+ *   Slider                   → <ui-slider orientation> around one
+ *                              <input type="range" min max step value> per thumb
+ *   defaultValue / value     → each input's value
+ *   min / max / step         → the inputs' own attributes (read from the first)
+ *   disabled                 → `disabled` on the inputs
+ *   onValueChange            → `ui-value-change` ({ detail: { value: number[] } });
+ *                              each input also fires `input`
+ *   onValueCommit            → `ui-value-commit` ({ detail: { value: number[] } });
+ *                              each moved input also fires `change`
+ *
+ * Keyboard (as Radix's): ArrowRight / ArrowUp step up, ArrowLeft / ArrowDown
+ * step down (ArrowLeft / ArrowRight swap under `dir="rtl"`), PageUp / PageDown
+ * and Shift with an arrow move ten steps, Home / End go to the ends. A press
+ * on the track moves the nearest thumb there and drags it.
+ *
+ * A11y (handled by the element, plus your part): each thumb is a focusable
+ * `role="slider"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and
+ * `aria-orientation`, named by its input's `<label>`s or `aria-label`, and a
+ * label click focuses its thumb. Your part: a name for every input, which for
+ * a range means one per thumb ("Minimum price", "Maximum price").
+ *
+ * @example
+ * ```html
+ * <input type="range" class=${sliderClass()} min="0" max="100" value="50" aria-label="Volume">
+ *
+ * <ui-slider>
+ *   <input type="range" class=${sliderClass()} name="min" min="0" max="100" step="5" value="25" aria-label="Minimum">
+ *   <input type="range" class=${sliderClass()} name="max" min="0" max="100" step="5" value="75" aria-label="Maximum">
+ * </ui-slider>
+ * ```
+ */
+import { WebComponent, html, prop, signal, nothing } from '@webjsdev/core';
+import { ensureId } from '../lib/utils.ts';
+
+/** One native `<input type="range">`, styled to match the drawn slider. */
+export function sliderClass(): string {
+  return [
+    'h-4 w-full cursor-pointer appearance-none bg-transparent disabled:cursor-not-allowed disabled:opacity-50',
+    'focus-visible:outline-hidden',
+    '[&::-webkit-slider-runnable-track]:h-1.5 [&::-webkit-slider-runnable-track]:rounded-full [&::-webkit-slider-runnable-track]:bg-muted',
+    '[&::-webkit-slider-thumb]:-mt-[5px] [&::-webkit-slider-thumb]:size-4 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:border [&::-webkit-slider-thumb]:border-primary [&::-webkit-slider-thumb]:bg-white [&::-webkit-slider-thumb]:shadow-sm',
+    'focus-visible:[&::-webkit-slider-thumb]:ring-4 focus-visible:[&::-webkit-slider-thumb]:ring-ring/50',
+    '[&::-moz-range-track]:h-1.5 [&::-moz-range-track]:rounded-full [&::-moz-range-track]:bg-muted',
+    '[&::-moz-range-progress]:h-1.5 [&::-moz-range-progress]:rounded-full [&::-moz-range-progress]:bg-primary',
+    '[&::-moz-range-thumb]:size-4 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:border [&::-moz-range-thumb]:border-primary [&::-moz-range-thumb]:bg-white [&::-moz-range-thumb]:shadow-sm',
+  ].join(' ');
+}
+
+/** The drawn slider's root (the element applies them). */
+export const sliderRootClass = (): string =>
+  'cn-slider relative flex w-full touch-none items-center select-none data-[disabled]:opacity-50 data-[orientation=vertical]:h-full data-[orientation=vertical]:w-auto data-[orientation=vertical]:flex-col';
+/** The track (the element applies them). */
+export const sliderTrackClass = (): string =>
+  'cn-slider-track relative grow overflow-hidden data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full';
+/** The filled range (the element applies them). */
+export const sliderRangeClass = (): string =>
+  'cn-slider-range absolute select-none data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full';
+/** A thumb (the element applies them). */
+export const sliderThumbClass = (): string =>
+  'cn-slider-thumb block shrink-0 select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50';
+
+// The visual-only hide the select uses: still submitted and reset with the form.
+const HIDDEN_CONTROL =
+  'position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;opacity:0;pointer-events:none;overflow:hidden;';
+
+export class UiSlider extends WebComponent({
+  orientation: prop<'horizontal' | 'vertical'>(String, { reflect: true }),
+}) {
+  readonly #enhanced = signal(false);
+  _observer: MutationObserver | null = null;
+  _waiting: MutationObserver | null = null;
+  _form: HTMLFormElement | null = null;
+  _saved = new Map<HTMLInputElement, string | null>();
+  _drag = -1;
+  _moved = new Set<number>();
+
+  constructor() {
+    super();
+    this.orientation = 'horizontal';
+  }
+
+  /** The native range inputs, one per thumb. */
+  inputs(): HTMLInputElement[] {
+    return Array.from(this.querySelectorAll<HTMLInputElement>('input[type="range"]'));
+  }
+
+  /** The current values, one per thumb. */
+  get value(): number[] {
+    return this.inputs().map((i) => Number(i.value));
+  }
+
+  connectedCallback(): void {
+    super.connectedCallback?.();
+    queueMicrotask(() => {
+      if (this._enhance() || this._waiting) return;
+      this._waiting = new MutationObserver(() => {
+        if (this._enhance()) { this._waiting?.disconnect(); this._waiting = null; }
+      });
+      this._waiting.observe(this, { childList: true, subtree: true });
+    });
+  }
+
+  disconnectedCallback(): void {
+    this._waiting?.disconnect();
+    this._observer?.disconnect();
+    for (const [input, style] of this._saved) {
+      input.removeEventListener('focus', this._onInputFocus);
+      if (style !== null) input.setAttribute('style', style);
+      else input.removeAttribute('style');
+      input.removeAttribute('aria-hidden');
+      input.removeAttribute('tabindex');
+    }
+    this._saved.clear();
+    this._form?.removeEventListener('reset', this._onReset);
+    super.disconnectedCallback?.();
+  }
+
+  /** Take over from the native inputs. True once it has (or already had). */
+  _enhance(): boolean {
+    if (this.#enhanced.get()) return true;
+    const inputs = this.inputs();
+    if (!inputs.length) return false;
+    for (const input of inputs) {
+      const style = input.getAttribute('style');
+      this._saved.set(input, style);
+      input.setAttribute('style', (style ?? '') + HIDDEN_CONTROL);
+      input.setAttribute('aria-hidden', 'true');
+      input.tabIndex = -1;
+      input.addEventListener('focus', this._onInputFocus);
+    }
+    this._form = inputs[0].form;
+    this._form?.addEventListener('reset', this._onReset);
+    this._observer = new MutationObserver(() => { this.requestUpdate(); });
+    for (const input of inputs) this._observer.observe(input, { attributes: true });
+    this.#enhanced.set(true);
+    return true;
+  }
+
+  _onReset = (): void => {
+    queueMicrotask(() => { this.requestUpdate(); });
+  };
+
+  // A label click focuses the hidden input; the user means its thumb.
+  _onInputFocus = (e: Event): void => {
+    const i = this.inputs().indexOf(e.target as HTMLInputElement);
+    this._thumbs()[i]?.focus();
+  };
+
+  _thumbs(): HTMLElement[] {
+    return Array.from(this.querySelectorAll<HTMLElement>('[data-slot="slider-thumb"]'));
+  }
+
+  _bounds(): { min: number; max: number; step: number } {
+    const first = this.inputs()[0];
+    const min = Number(first?.min || 0);
+    const max = Number(first?.max || 100);
+    const step = Number(first?.step) > 0 ? Number(first.step) : 1;
+    return { min, max: max > min ? max : min + 1, step };
+  }
+
+  _rtl(): boolean {
+    return typeof getComputedStyle === 'function' && getComputedStyle(this).direction === 'rtl';
+  }
+
+  render() {
+    if (!this.#enhanced.get()) {
+      return html`<div data-slot="slider" data-orientation=${this.orientation || 'horizontal'} class="grid gap-2"><slot></slot></div>`;
+    }
+    const vertical = this.orientation === 'vertical';
+    const orientation = vertical ? 'vertical' : 'horizontal';
+    const inputs = this.inputs();
+    const { min, max } = this._bounds();
+    const pct = (v: number) => ((Math.min(max, Math.max(min, v)) - min) / (max - min)) * 100;
+    const values = inputs.map((i) => Number(i.value));
+    const disabled = inputs.some((i) => i.disabled);
+    const lo = values.length > 1 ? pct(Math.min(...values)) : 0;
+    const hi = pct(Math.max(...values));
+    const rangeStyle = vertical
+      ? `bottom:${lo}%;top:${100 - hi}%`
+      : `inset-inline-start:${lo}%;inset-inline-end:${100 - hi}%`;
+    const flip = this._rtl() ? 1 : -1;
+    return html`<div
+      data-slot="slider"
+      data-orientation=${orientation}
+      ?data-disabled=${disabled}
+      class=${sliderRootClass()}
+      @pointerdown=${this._onPointerDown}
+      @pointermove=${this._onPointerMove}
+      @pointerup=${this._onPointerUp}
+      @pointercancel=${this._onPointerUp}
+    ><slot></slot><span data-slot="slider-track" data-orientation=${orientation} class=${sliderTrackClass()}><span
+      data-slot="slider-range" data-orientation=${orientation} class=${sliderRangeClass()} style=${rangeStyle}
+    ></span></span>${inputs.map((input, i) => {
+      const p = pct(values[i]);
+      // At P% along the track, shifted back by P% of its own size, so a
+      // thumb sits inside the track at both ends, as Radix's does.
+      const place = vertical
+        ? `position:absolute;bottom:${p}%;transform:translateY(${p}%)`
+        : `position:absolute;inset-inline-start:${p}%;transform:translateX(${flip * p}%)`;
+      const labels = input.labels ? Array.from(input.labels).map((l) => ensureId(l, 'ui-slider-label')) : [];
+      return html`<span style=${place}><span
+        data-slot="slider-thumb"
+        role="slider"
+        tabindex=${input.disabled ? '-1' : '0'}
+        aria-valuemin=${String(min)}
+        aria-valuemax=${String(max)}
+        aria-valuenow=${String(values[i])}
+        aria-valuetext=${input.getAttribute('aria-valuetext') || nothing}
+        aria-orientation=${orientation}
+        aria-labelledby=${labels.length ? labels.join(' ') : nothing}
+        aria-label=${!labels.length && input.getAttribute('aria-label') ? input.getAttribute('aria-label') : nothing}
+        aria-disabled=${input.disabled ? 'true' : nothing}
+        ?data-disabled=${input.disabled}
+        data-orientation=${orientation}
+        class=${sliderThumbClass()}
+        @keydown=${(e: KeyboardEvent) => this._onKeyDown(e, i)}
+      ></span></span>`;
+    })}</div>`;
+  }
+
+  /** Move thumb `i` to `raw`, snapped to the step and kept between its neighbours. */
+  _set(i: number, raw: number): boolean {
+    const inputs = this.inputs();
+    const input = inputs[i];
+    if (!input || input.disabled) return false;
+    const { min, max, step } = this._bounds();
+    let v = Math.round((raw - min) / step) * step + min;
+    v = Number(v.toFixed(10));
+    const lower = i > 0 ? Number(inputs[i - 1].value) : min;
+    const upper = i < inputs.length - 1 ? Number(inputs[i + 1].value) : max;
+    v = Math.min(Math.max(v, lower, min), upper, max);
+    if (Number(input.value) === v) return false;
+    input.value = String(v);
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    this._moved.add(i);
+    this.requestUpdate();
+    this.dispatchEvent(new CustomEvent('ui-value-change', { bubbles: true, detail: { value: this.value } }));
+    return true;
+  }
+
+  // The end of a gesture: a key press, or a pointer release.
+  _commit(): void {
+    if (!this._moved.size) return;
+    const inputs = this.inputs();
+    for (const i of this._moved) inputs[i]?.dispatchEvent(new Event('change', { bubbles: true }));
+    this._moved.clear();
+    this.dispatchEvent(new CustomEvent('ui-value-commit', { bubbles: true, detail: { value: this.value } }));
+  }
+
+  _onKeyDown(e: KeyboardEvent, i: number): void {
+    const { min, max, step } = this._bounds();
+    const v = Number(this.inputs()[i]?.value);
+    const big = step * 10;
+    const rtl = this._rtl() && this.orientation !== 'vertical';
+    const up = (n: number) => this._set(i, v + n);
+    let handled = true;
+    switch (e.key) {
+      case 'ArrowUp': up(e.shiftKey ? big : step); break;
+      case 'ArrowDown': up(-(e.shiftKey ? big : step)); break;
+      case 'ArrowRight': up((rtl ? -1 : 1) * (e.shiftKey ? big : step)); break;
+      case 'ArrowLeft': up((rtl ? 1 : -1) * (e.shiftKey ? big : step)); break;
+      case 'PageUp': up(big); break;
+      case 'PageDown': up(-big); break;
+      case 'Home': this._set(i, min); break;
+      case 'End': this._set(i, max); break;
+      default: handled = false;
+    }
+    if (!handled) return;
+    e.preventDefault();
+    this._commit();
+  }
+
+  // The value under a pointer position, from the track's box.
+  _valueAt(e: PointerEvent): number {
+    const track = this.querySelector<HTMLElement>('[data-slot="slider-track"]');
+    const { min, max } = this._bounds();
+    if (!track) return min;
+    const r = track.getBoundingClientRect();
+    let t: number;
+    if (this.orientation === 'vertical') t = (r.bottom - e.clientY) / r.height;
+    else t = this._rtl() ? (r.right - e.clientX) / r.width : (e.clientX - r.left) / r.width;
+    return min + Math.min(1, Math.max(0, t)) * (max - min);
+  }
+
+  _onPointerDown = (e: PointerEvent): void => {
+    const inputs = this.inputs();
+    if (!inputs.length || inputs.every((i) => i.disabled) || e.button !== 0) return;
+    const v = this._valueAt(e);
+    const values = inputs.map((i) => Number(i.value));
+    // The nearest thumb; between two at the same spot, the one the press is
+    // past, so a range collapsed to one point can still be pulled apart.
+    let best = 0;
+    values.forEach((x, i) => {
+      const d = Math.abs(x - v);
+      const bestD = Math.abs(values[best] - v);
+      if (d < bestD || (d === bestD && v > x)) best = i;
+    });
+    if (inputs[best].disabled) return;
+    e.preventDefault();
+    this._drag = best;
+    // A pointer the engine does not track (a synthetic one) cannot be captured.
+    try { (e.currentTarget as HTMLElement).setPointerCapture?.(e.pointerId); } catch { /* drag without capture */ }
+    this._set(best, v);
+    this._thumbs()[best]?.focus();
+  };
+
+  _onPointerMove = (e: PointerEvent): void => {
+    if (this._drag < 0) return;
+    this._set(this._drag, this._valueAt(e));
+  };
+
+  _onPointerUp = (e: PointerEvent): void => {
+    if (this._drag < 0) return;
+    this._drag = -1;
+    try { (e.currentTarget as HTMLElement).releasePointerCapture?.(e.pointerId); } catch { /* already released */ }
+    this._commit();
+  };
+}
+UiSlider.register('ui-slider');

package/packages/registry/components/sonner.ts

@@ -23,6 +23,19 @@
  *   `action`:      { label, onClick } | undefined. Renders an action button.
  *   `cancel`:      { label, onClick } | undefined. Renders a cancel button.
  *                  Both buttons dismiss the toast after running their onClick.
+ *   `position`:    one of the viewport positions. The toast shows at that
+ *                  corner instead of the viewport's own (shadcn's per-toast
+ *                  `position`).
+ *
+ * Firing a toast with no script of your own: any element carrying
+ * `data-toast="<message>"` fires one when clicked, as shadcn's demos do with
+ * `onClick={() => toast(...)}`. A mounted `<ui-sonner>` handles the clicks
+ * for the whole page through one delegated listener. The optional attributes
+ * are `data-toast-type` (`success` | `error` | `info` | `warning` |
+ * `loading`), `data-toast-description`, `data-toast-position`,
+ * `data-toast-duration` (ms), and `data-toast-action` (a button label; the
+ * button dismisses the toast). Put it on a real `<button type="button">` so it
+ * is focusable and fires from the keyboard too.
  *
  * Events: none dispatched (consumers act on the id returned by `toast()`).
  *
@@ -83,6 +96,7 @@ interface ToastOptions {
   duration?: number;
   action?: { label: string; onClick: () => void };
   cancel?: { label: string; onClick: () => void };
+  position?: SonnerPosition;
 }
 
 interface ToastItem extends ToastOptions {
@@ -126,9 +140,47 @@ function makeToast(message: string, opts: ToastOptions = {}, type: ToastType = '
     duration: opts.duration ?? (type === 'loading' ? 0 : 4000),
     action: opts.action,
     cancel: opts.cancel,
+    position: opts.position,
   });
 }
 
+const TOAST_TYPES = ['default', 'success', 'error', 'info', 'warning', 'loading'];
+
+/**
+ * A click on (or inside) an element carrying `data-toast` fires the toast it
+ * describes. One listener serves the page, however many viewports are
+ * mounted, and it routes through the same bus `toast()` uses.
+ */
+function onToastClick(e: Event): void {
+  const target = e.target as Element | null;
+  const el = target && typeof target.closest === 'function' ? target.closest('[data-toast]') : null;
+  if (!el) return;
+  const message = el.getAttribute('data-toast') || '';
+  if (!message) return;
+  const rawType = el.getAttribute('data-toast-type') || 'default';
+  const type = (TOAST_TYPES.includes(rawType) ? rawType : 'default') as ToastType;
+  const position = el.getAttribute('data-toast-position') as SonnerPosition | null;
+  const duration = Number(el.getAttribute('data-toast-duration'));
+  const action = el.getAttribute('data-toast-action');
+  makeToast(message, {
+    description: el.getAttribute('data-toast-description') || undefined,
+    position: position && position in POSITIONS ? position : undefined,
+    duration: el.hasAttribute('data-toast-duration') && Number.isFinite(duration) ? duration : undefined,
+    action: action ? { label: action, onClick: () => {} } : undefined,
+  }, type);
+}
+
+/** Install the page's one `data-toast` listener, counted per mounted viewport. */
+function holdToastClicks(): () => void {
+  const g = globalThis as unknown as { __webjsSonnerClicks?: number };
+  if (!g.__webjsSonnerClicks) document.addEventListener('click', onToastClick);
+  g.__webjsSonnerClicks = (g.__webjsSonnerClicks ?? 0) + 1;
+  return () => {
+    g.__webjsSonnerClicks = (g.__webjsSonnerClicks ?? 1) - 1;
+    if (!g.__webjsSonnerClicks) document.removeEventListener('click', onToastClick);
+  };
+}
+
 export function toast(message: string, opts?: ToastOptions): string | number {
   return makeToast(message, opts, 'default');
 }
@@ -159,11 +211,11 @@ toast.promise = <T,>(p: Promise<T>, opts: { loading: string; success: string; er
 // --------------------------------------------------------------------------
 
 const POSITIONS = {
-  'top-right': 'top-4 right-4',
-  'top-left': 'top-4 left-4',
+  'top-right': 'top-4 end-4',
+  'top-left': 'top-4 start-4',
   'top-center': 'top-4 left-1/2 -translate-x-1/2',
-  'bottom-right': 'bottom-4 right-4',
-  'bottom-left': 'bottom-4 left-4',
+  'bottom-right': 'bottom-4 end-4',
+  'bottom-left': 'bottom-4 start-4',
   'bottom-center': 'bottom-4 left-1/2 -translate-x-1/2',
 } as const;
 
@@ -184,9 +236,10 @@ const TYPE_ICON_COLOR: Record<ToastType, string> = {
 export class UiSonner extends WebComponent({
   position: prop<SonnerPosition>(String, { reflect: true }),
 }) {
-  items = signal<ToastItem[]>([]);
+  readonly items = signal<ToastItem[]>([]);
 
   _disposeBeforeCache?: () => void;
+  _releaseClicks?: () => void;
 
   constructor() {
     super();
@@ -198,10 +251,13 @@ export class UiSonner extends WebComponent({
     // Clear pending toasts before a back/forward snapshot so a restored page
     // does not show stale toasts that should have auto-dismissed (#766).
     this._disposeBeforeCache = onBeforeCache(() => this.items.set([]));
+    this._releaseClicks = holdToastClicks();
   }
 
   disconnectedCallback(): void {
     this._disposeBeforeCache?.();
+    this._releaseClicks?.();
+    this._releaseClicks = undefined;
     super.disconnectedCallback?.();
   }
 
@@ -235,6 +291,7 @@ export class UiSonner extends WebComponent({
       duration: opts.duration ?? (type === 'loading' ? 0 : 4000),
       action: opts.action,
       cancel: opts.cancel,
+      position: opts.position,
     });
     return id;
   }
@@ -251,7 +308,16 @@ export class UiSonner extends WebComponent({
   }
 
   render() {
-    const pos = POSITIONS[this.position] ?? POSITIONS['bottom-right'];
+    const own = this.position in POSITIONS ? this.position : 'bottom-right';
+    const items = this.items.get();
+    // A toast with its own position shows at that corner, in a region of its
+    // own; the viewport's region stays in the DOM from the first render.
+    const elsewhere = [...new Set(items.map((i) => i.position).filter((p): p is SonnerPosition => !!p && p !== own && p in POSITIONS))];
+    return html`${this._region(own, items.filter((i) => !i.position || i.position === own || !(i.position in POSITIONS)))}${elsewhere.map((p) => this._region(p, items.filter((i) => i.position === p)))}`;
+  }
+
+  _region(position: SonnerPosition, items: ToastItem[]) {
+    const pos = POSITIONS[position];
     // The container is a persistent live region: it is in the DOM from the
     // first render (even with zero toasts), so a screen reader announces
     // each toast as it is inserted. It is polite, and it is the ONLY live
@@ -266,6 +332,7 @@ export class UiSonner extends WebComponent({
     // polite viewport, and its second live root is the accepted cost.
     return html`<div
       data-slot="sonner"
+      data-position=${position}
       role="region"
       aria-label="Notifications"
       aria-live="polite"
@@ -274,7 +341,7 @@ export class UiSonner extends WebComponent({
       class=${`pointer-events-none fixed z-[100] flex flex-col gap-2 ${pos}`}
     >
       ${repeat(
-        this.items.get(),
+        items,
         (item) => item.id,
         // The role is BRANCHED rather than written as a nullish hole. A hole
         // that evaluates to null serves role="" from the server renderer while

package/packages/registry/components/spinner.ts

@@ -0,0 +1,66 @@
+/**
+ * Spinner: an animated busy indicator. Tier-1 helpers, `spinnerClass()` for
+ * the classes and `spinner()` for the whole inline SVG (the Lucide
+ * loader-circle path, so no icon package is needed). It inherits the text
+ * colour through `currentColor`, so it matches whatever it sits in.
+ *
+ * shadcn parity:
+ *   Spinner  → spinner({ class, label })   (the inline SVG)
+ *            → spinnerClass()              (the classes, for your own SVG)
+ *
+ * Size it with a size utility: `spinner({ class: 'size-6' })` replaces the
+ * default `size-4`.
+ *
+ * Design tokens used: none (it draws in `currentColor`).
+ *
+ * A11y (required for accessible output):
+ *   `spinner()` renders `role="status"` + `aria-label="Loading"`, so a
+ *   standalone spinner is announced. Pass `label` for a more specific name
+ *   (`spinner({ label: 'Loading invoices' })`).
+ *   Inside a BUTTON while a save is running, mark the button itself busy:
+ *   `disabled` (so a second click cannot submit twice) plus `aria-busy="true"`,
+ *   and keep a visible text label ("Saving"). The button's text already says
+ *   what is happening, so pass `decorative: true`, which renders the SVG with
+ *   `aria-hidden="true"` and no role, rather than nesting a second live status
+ *   inside the button's name. Re-enable the button and drop `aria-busy` when
+ *   the save settles, and report the outcome somewhere that is announced (a
+ *   toast, or the form's error text).
+ *   A spinner that replaces a whole region is better as a skeleton when the
+ *   final layout is known, with `aria-busy="true"` on the region.
+ *
+ * @example
+ * ```html
+ * <div class="flex items-center gap-2 text-sm text-muted-foreground">
+ *   ${spinner()} Loading invoices
+ * </div>
+ *
+ * <button class=${buttonClass()} type="submit" disabled aria-busy="true">
+ *   ${spinner({ decorative: true })} Saving
+ * </button>
+ * ```
+ */
+import { html, nothing } from '@webjsdev/core';
+import { cn } from '../lib/utils.ts';
+
+/** Spinner classes: `size-4` plus `animate-spin`. Apply to your own `<svg>`. */
+export const spinnerClass = (): string => 'size-4 animate-spin';
+
+/**
+ * The spinner as an inline SVG template. `class` is merged over
+ * `spinnerClass()` (a later size utility wins), `label` names it (default
+ * "Loading"), and `decorative` hides it from assistive tech for use beside
+ * visible text such as a busy button's label.
+ */
+export function spinner(opts: { class?: string; label?: string; decorative?: boolean; icon?: 'inline-start' | 'inline-end' } = {}) {
+  const cls = cn(spinnerClass(), opts.class);
+  // shadcn's `data-icon`, which a button or badge reads to tighten its padding
+  // on the spinner's side. Left out, the attribute is omitted.
+  const icon = opts.icon ?? nothing;
+  // Branched rather than a nullish `role=${...}` hole: the server renderer
+  // stringifies a null attribute value, so a single template would serve
+  // `role=""` on the decorative form.
+  if (opts.decorative) {
+    return html`<svg data-slot="spinner" data-icon=${icon} aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
+  }
+  return html`<svg data-slot="spinner" data-icon=${icon} role="status" aria-label=${opts.label ?? 'Loading'} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
+}