bonsaif-ui 0.1.156 → 0.1.158

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## 0.1.155 - 2026-09-29
+## 0.1.157 - 2026-10-01
+
+- `SpotlightTour`: recorrido por spotlight para onboarding, ayuda o una guía interna. Incluye `useSpotlightTour`, ejemplo en la documentación y un prompt para pedirle a la IA que lo monte en una vista.
+
+## 0.1.156 - 2026-09-29
 
 - `DataTable`: el menú Filtrar / columnas se ancla al **header de la columna** (alineado a la izquierda), no al icono. Evita que el popover se corra hacia la izquierda cuando el menú es más ancho que el botón.
 - `DataTable`: al marcar **Seleccionar todo**, elegir **cualquier opción** del checklist, o al refrescar filas, el menú **ya no salta a la esquina**; reancla al header vivo e ignora rects inválidos tras el re-render (aplica a cualquier tabla con `DataTable`).
@@ -9,6 +13,10 @@
 - `DataTable`: el checklist del filtro ya no muestra **duplicados** con el mismo texto (p. ej. nombre cacheado + `userId` con el mismo label); prefiere el id estable.
 - `DataTable`: persiste el catálogo acumulado del checklist (`filterOptionValues` / labels) junto con los filtros. Al recargar con un filtro activo (p. ej. solo Alain) siguen visibles el resto de opciones para poder sumarlas.
 
+## 0.1.155 - 2026-09-29
+
+- Misma línea de mejoras de filtros/menú; publicada como **0.1.156**.
+
 ## 0.1.154 - 2026-09-29
 
 - `DataTable`: el primer clic en un valor del filtro de columna **incluye solo ese valor** (las demás opciones del checklist siguen visibles gracias a la caché de 0.1.153). Desmarcar y volver a marcar vuelve a filtrar.

package/README.md

@@ -41,6 +41,7 @@ For Next.js consumers using a local package or monorepo setup, add `transpilePac
 | Show tabular records | `DataTable`, `Pagination` | Sorting, selection, loading, empty state, column width behavior, and paging. |
 | Confirm or edit in context | `Drawer`, `Modal`, `ConfirmDialog` | Overlays with consistent chrome and guardrails for unsaved changes. |
 | Preview images fullscreen | `ImageLightbox`, `ImageLightboxHost` | Free zoom (may pixelate), pan, counter, and multi-slide navigation. |
+| Walk someone through a screen | `SpotlightTour` | Spotlight overlay that highlights existing elements one step at a time. |
 | Explain status | `Alert`, `StatusBadge`, `StatusSelect`, `EmptyState`, `LoadingState` | Clear operational feedback for data states and workflows. |
 | Compose related modules | `DynamicDetailTabs` | Parent-detail layout with lazy loaded child modules. |
 
@@ -256,6 +257,7 @@ function AccountFormExample() {
 - `CopyButton`, `CopyLinkButton`: clipboard utilities.
 - `Modal`, `Drawer`, `ConfirmDialog`: overlays and confirmations.
 - `ImageLightbox`, `ImageLightboxHost`: fullscreen image viewer with theme tokens, free zoom (may pixelate), pan, optional `loop` / `showThumbnails`, and open/close FLIP animation from the clicked image (`originRect`).
+- `SpotlightTour`: spotlight walkthrough for onboarding, help, or an internal guide. It highlights elements already on the page.
 - `MouseTooltip`: lightweight hover tooltip.
 
 #### Image lightbox
@@ -277,6 +279,64 @@ import { ImageLightbox, ImageLightboxHost } from "bonsaif-ui";
 </ImageLightboxHost>
 ```
 
+#### Spotlight tour
+
+Use `SpotlightTour` to explain a screen in place: onboarding, contextual help, or a development guide. Mark each region with `data-tour` and point a step at that selector. `StepWizard` remains the component for a multi-step form.
+
+`useSpotlightTour(storageKey)` opens the tour on the first visit. Pass the same `storageKey` to `SpotlightTour`. Closing it (skip, done, Escape, or a click outside) stores `"done"` in `localStorage`. A manual button can open it again.
+
+If a step highlights something inside a drawer or modal, open that overlay in `onStepChange` and close it when the step changes away. The tour remeasures the target.
+
+```tsx
+import { Button, SpotlightTour, useSpotlightTour, type SpotlightTourStep } from "bonsaif-ui";
+
+const steps: SpotlightTourStep[] = [
+  {
+    id: "search",
+    title: "Search a record",
+    target: '[data-tour="search"]',
+    placement: "bottom",
+    body: <p>Filter the list without leaving the page.</p>,
+  },
+];
+
+export function ClientsTour() {
+  const tour = useSpotlightTour("my-app:clients:tour:v1");
+
+  return (
+    <>
+      <div data-tour="search">{/* existing search */}</div>
+      <Button aria-label="Show guide" onClick={tour.openTour}>
+        Guide
+      </Button>
+      <SpotlightTour
+        steps={steps}
+        open={tour.open}
+        onOpenChange={tour.setOpen}
+        storageKey="my-app:clients:tour:v1"
+        label="Clients"
+      />
+    </>
+  );
+}
+```
+
+Prompt to ask an AI to add the tour to a view:
+
+```text
+Agrega un recorrido guiado con SpotlightTour de bonsaif-ui en esta vista. No construyas un overlay propio ni uses otra librería de tours.
+
+1. Importa SpotlightTour, useSpotlightTour y el tipo SpotlightTourStep desde "bonsaif-ui". El botón que abre el recorrido también es Button de bonsaif-ui.
+2. Marca cada zona a explicar con data-tour="un-id" en el elemento real de la vista (buscador, tabla, acción, drawer, etc.). El selector del paso es target: '[data-tour="un-id"]'.
+3. Define un arreglo SpotlightTourStep. Cada paso lleva id, title, body (ReactNode), target y placement ("top" | "bottom" | "left" | "right" | "auto"). caption es opcional: una ruta de archivo o una nota corta.
+4. Abre el recorrido con estado controlado. useSpotlightTour("app:vista:tour:v1") lo abre solo la primera vez. Pasa el mismo storageKey a SpotlightTour. Al cerrar (Saltar, Listo, Escape o clic fuera) guarda "done" en localStorage. Un botón manual, con aria-label, debe poder abrirlo otra vez con openTour().
+5. Si un paso señala algo que está dentro de un drawer o modal, ábrelo en onStepChange cuando step.id coincida y ciérralo al salir de ese paso. El tour vuelve a medir el target.
+6. El texto de los pasos va en un arreglo junto a la vista, no en SQL, servicios ni API routes. label es el nombre del recorrido (por ejemplo "Clientes" o "Guía de desarrollo"), no dejes el default si la pantalla ya tiene un nombre claro.
+7. No inventes un componente equivalente. Reutiliza SpotlightTour.
+```
+
+The same prompt is on the `SpotlightTour` page of `npm run docs`, with a copy button.
+
 #### Drawer Unsaved Changes Guard
 
 Use `hasUnsavedChanges` when a drawer edits data and must not close silently. When the prop is `true`, the drawer intercepts its own close controls: backdrop click, Escape, the X button, and the default Cancel button. It shows a confirmation modal and only calls `onClose` after the user confirms that unsaved data can be discarded.