drop-spinner

drop-spinner es una librería ligera para seleccionar elementos al azar con una interfaz visual opcional. Está pensada para ser usada como componente React, como utilidad programática y (opcionalmente) como Web Component. El paquete está preparado para publicarse en npm y es compatible con entornos SSR como Next.js.

Contenido del README:

• Instalación
• Uso rápido (React)
• Uso en Next.js (SSR)
• Uso programático
• API
• Build y publicación
• Ejemplo local

Instalación

npm install drop-spinner

Nota: el paquete debe declarar react y react-dom como peerDependencies. Asegúrate de instalarlos en tu proyecto consumidor.

Uso rápido — Componente React

import { RandomImagePicker, ImageOption } from 'drop-spinner';

const items: ImageOption[] = [
  { name: 'Apple', url: '/img/apple.png' },
  { name: 'Banana', url: '/img/banana.png' },
  { name: 'Cherry' }
];

export default function Page() {
  return <RandomImagePicker items={items} />;
}

El componente es sencillo: recibe items: ImageOption[] y muestra el elemento seleccionado (o un texto si no hay imagen). ImageOption es { name: string; url?: string }.

Uso en Next.js / SSR

Si usas características que dependen del DOM (registro de Web Components o utilidades que montan nodos), registra el componente solo en el cliente:

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

export default function Page() {
  useEffect(() => {
    if (typeof registerDropSpinner === 'function') registerDropSpinner();
  }, []);

  async function handlePick() {
    const result = await dropSpinner({ items: ['A','B','C'] });
    alert('Picked: ' + result);
  }

  return <button onClick={handlePick}>Pick</button>;
}

Registra el Web Component (si existe) dentro de useEffect para evitar fallos en SSR (no existe window en el servidor).

Uso programático

La utilidad dropSpinner(options) permite invocar la selección programáticamente. En cliente retorna una Promise que se resuelve tras la animación; en entornos sin DOM puede comportarse de forma síncrona.

import { dropSpinner } from 'drop-spinner';

const winner = await dropSpinner({
  items: ['🍎','🍌','🍇'],
  animationSpeed: 1200,
  circleSize: 200,
  onPick: (item) => console.log('picked', item)
});

API (resumen)

• RandomImagePicker — componente React. Props:

  • items: ImageOption[]

• getRandomItem(items: ImageOption[]): ImageOption | undefined — devuelve un item aleatorio o undefined si la lista está vacía.

• dropSpinner(options: DropSpinnerOptions) — función útil para lanzar la selección con animación.

• registerDropSpinner() — registra el Web Component en el cliente (si el paquete lo exporta).

Tipos importantes:

• ImageOption = { name: string; url?: string }
• DropSpinnerOptions = { items: string[] | ImageOption[]; animationSpeed?: number; circleSize?: number; onPick?: (item: any) => void }

Build y publicación

El proyecto usa tsup para generar bundles ESM/CJS y tipados.

Antes de publicar:

1. Asegúrate de que package.json tiene los campos name, version, main, module, types y exports correctamente configurados.
2. Ejecuta:

npm run build

3. Comprueba el contenido del paquete:

npm pack --dry-run

4. Publica en npm:

npm publish --access public

Recomendación: mantener react/react-dom en peerDependencies y @types/react en devDependencies.

Ejemplo local (Next.js)

El repositorio incluye un ejemplo minimal en example/next-app. Para ejecutarlo localmente:

cd example/next-app
npm install
npm run dev

El ejemplo está configurado para usar el paquete local empaquetado (tarball) como dependencia de desarrollo.

Limpieza y publicación segura

• Añade .npmignore para excluir código fuente y archivos de desarrollo del paquete publicado.
• Añade .gitignore para evitar subir node_modules, artefactos de build y tarballs.

Contribuciones

PRs y issues son bienvenidos. Incluye tests y actualiza README.md si cambias la API.

Licencia

MIT