drop-spinner

Librería liviana para seleccionar aleatoriamente un elemento de una lista con una animación visual de "drop". Puedes usarla como función utilitaria o como Web Component. Diseñada para funcionar en navegadores, y con guardias para uso en entornos SSR (por ejemplo Next.js).

Instalación

npm install drop-spinner

Uso como función (navegador)

La función dropSpinner(options) en cliente montará temporalmente el componente <drop-spinner> en el DOM, ejecutará la animación y devolverá una Promise que se resuelve con el elemento seleccionado.

import { dropSpinner } from 'drop-spinner';

async function run() {
  const picked = await dropSpinner({
    items: ['🍎', '🍌', '🍇', '🍉'],
    animationSpeed: 1200,
    circleSize: 220,
    onPick: (item) => console.log('callback pick:', item),
  });
  console.log('Picked (promise):', picked);
}

run();

En entornos sin DOM (por ejemplo Node.js), dropSpinner mantiene un comportamiento síncrono y devuelve directamente el item elegido (y llamará onPick si se indicó).

Uso en Next.js (u otra app SSR)

El paquete exporta registerDropSpinner() para que registres el Web Component de forma segura solo en el cliente (evita errores en SSR). Recomiendo registrar el componente dentro de un useEffect.

Ejemplo con React / Next.js:

import { useEffect } from 'react';
import { registerDropSpinner, dropSpinner } from 'drop-spinner';

export default function Page() {
  useEffect(() => {
    // Registra el custom element solo en cliente
    registerDropSpinner();
  }, []);

  const handle = async () => {
    const result = await dropSpinner({ items: ['A', 'B', 'C'] });
    alert('Winner: ' + result);
  };

  return <button onClick={handle}>Sortear</button>;
}

Si prefieres usar el Web Component directamente en JSX/HTML, regístralo y luego insértalo en el DOM:

useEffect(() => registerDropSpinner(), []);

return (
  <div>
    <drop-spinner items='["🍎","🍌","🍇"]' animation-speed="1000" circle-size="200"></drop-spinner>
  </div>
);

Uso como Web Component (puro HTML)

1. Compila el paquete a JS (npm run build) y sirve los archivos.
2. Incluye el módulo en tu HTML o empaqueta el bundle en tu app cliente.

Ejemplo:

<script type="module" src="/path/to/DropSpinnerElement.js"></script>
<drop-spinner items='["🍎","🍌","🍇","🍉"]' animation-speed="1000" circle-size="200"></drop-spinner>
<script>
  document.querySelector('drop-spinner')?.addEventListener('pick', e => {
    console.log('picked event:', e.detail.item);
  });
</script>

También puedes llamar programáticamente al método pick() del componente (devuelve Promise):

const el = document.querySelector('drop-spinner');
el?.pick().then(item => console.log('picked by el.pick():', item));

API

Interfaz DropSpinnerOptions

interface DropSpinnerOptions {
  items: string[]; // elementos (texto o URLs de imagen)
  animationSpeed?: number; // ms, por defecto 1000
  circleSize?: number;     // px, por defecto 200
  onPick?: (item: string) => void; // callback opcional
}

Funciones exportadas

• dropSpinner(options) — En cliente devuelve Promise<string> que se resuelve con el elemento seleccionado tras la animación. En entornos sin DOM devuelve string (síncrono).
• registerDropSpinner() — Registra el custom element drop-spinner de forma segura en entornos cliente (útil en Next.js). Puedes llamarlo dentro de useEffect.

Web Component

• <drop-spinner> soporta los atributos items (JSON string), animation-speed y circle-size. También expone el método pick(): Promise<string> y emite un evento pick con detail.item.

Build & typings

El paquete usa tsup. Para compilar:

npm run build

Se generarán los bundles para CommonJS y ESM y las declaraciones .d.ts.

License

MIT