trackops 1.0.0 → 1.1.0

package/ui/js/icons.js

@@ -0,0 +1,104 @@
+/**
+ * icons.js — SVG paths de React Icons (Flat / Line) como constantes
+ * Stack vanilla: sin React, sin dependencias externas.
+ * Se usan los paths SVG de heroicons + lucide-style wrappers.
+ * Uso: icons.render('dashboard', 20) → <svg>...</svg>
+ */
+
+const PATHS = {
+  // ── Navegación ──
+  dashboard: `<rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/>`,
+  tasks:     `<path d="M9 5H7a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2h-2"/><rect x="9" y="3" width="6" height="4" rx="1"/><path d="m9 12 2 2 4-4"/>`,
+  board:     `<rect x="3" y="3" width="5" height="18" rx="1"/><rect x="11" y="3" width="5" height="12" rx="1"/><rect x="19" y="3" width="5" height="15" rx="1"/>`, // adjusted
+  execution: `<polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/>`,
+  insights:  `<line x1="18" y1="20" x2="18" y2="10"/><line x1="12" y1="20" x2="12" y2="4"/><line x1="6" y1="20" x2="6" y2="14"/>`,
+  settings:  `<circle cx="12" cy="12" r="3"/><path d="M19.1 6.9a2.83 2.83 0 0 1 0 4L17 13l-1.4-1.4 2.1-2.1a.83.83 0 0 0 0-1.2L16.4 7l-2.1 2.1L13 7.8l2.1-2.1a.83.83 0 0 0-1.2 0L12.7 6l-1.4 1.4L9.2 5.3a2.83 2.83 0 0 1 4-4L15.3 3.4l1.4 1.4 2.1-2.1L19.1 3a2.83 2.83 0 0 1 4 4l-2.1 2.1 1.4 1.4L24.5 8.8a2.83 2.83 0 0 1-4 4l-2.1-2.1-1.4 1.4 2.1 2.1a.83.83 0 0 1 0 1.2L17.4 17l2.1 2.1a.83.83 0 0 1-1.2 0L16.2 17l-1.4 1.4 2.1 2.1a2.83 2.83 0 0 1-4 4l-2.1-2.1-1.4 1.4 2.1 2.1a.83.83 0 0 1 0 1.2L10.7 26l2.1 2.1a.83.83 0 0 1-1.2 0L9.5 26l-1.4-1.4L5.9 26.7a2.83 2.83 0 0 1-4-4L4 20.6l1.4-1.4-2.1-2.1A2.83 2.83 0 0 1 7.3 13l2.1 2.1 1.4-1.4L8.7 11.6A2.83 2.83 0 0 1 13 7.6l2.1 2.1 1.4-1.4L14.4 6.2A2.83 2.83 0 0 1 19.1 6.9Z"/>`,
+
+  // ── General ──
+  help:      `<circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><line x1="12" y1="17" x2="12.01" y2="17"/>`,
+  logout:    `<path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4"/><polyline points="16 17 21 12 16 7"/><line x1="21" y1="12" x2="9" y2="12"/>`,
+  console:   `<polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/>`,
+  infinity:  `<path d="M12 12c-2-2.5-4-4-6-4a4 4 0 0 0 0 8c2 0 4-1.5 6-4z"/><path d="M12 12c2 2.5 4 4 6 4a4 4 0 0 0 0-8c-2 0-4 1.5-6 4z"/>`,
+
+  // ── Acciones ──
+  plus:      `<line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/>`,
+  check:     `<polyline points="20 6 9 17 4 12"/>`,
+  x:         `<line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>`,
+  edit:      `<path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/>`,
+  trash:     `<polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M10 11v6"/><path d="M14 11v6"/><path d="M9 6V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2"/>`,
+  copy:      `<rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>`,
+  refresh:   `<polyline points="23 4 23 10 17 10"/><path d="M20.49 15a9 9 0 1 1-2.12-9.36L23 10"/>`,
+  sync:      `<path d="M21 2v6h-6"/><path d="M3 12a9 9 0 0 1 15-6.7L21 8"/><path d="M3 22v-6h6"/><path d="M21 12a9 9 0 0 1-15 6.7L3 16"/>`,
+  search:    `<circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/>`,
+  filter:    `<polygon points="22 3 2 3 10 12.46 10 19 14 21 14 12.46 22 3"/>`,
+  sort:      `<line x1="21" y1="10" x2="7" y2="10"/><line x1="21" y1="6" x2="3" y2="6"/><line x1="21" y1="14" x2="3" y2="14"/><line x1="21" y1="18" x2="7" y2="18"/>`,
+  menu:      `<line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="18" x2="21" y2="18"/>`,
+  arrowUp:   `<line x1="12" y1="19" x2="12" y2="5"/><polyline points="5 12 12 5 19 12"/>`,
+  arrowDown: `<line x1="12" y1="5" x2="12" y2="19"/><polyline points="19 12 12 19 5 12"/>`,
+  arrowRight:`<line x1="5" y1="12" x2="19" y2="12"/><polyline points="12 5 19 12 12 19"/>`,
+  chevronDown:`<polyline points="6 9 12 15 18 9"/>`,
+  externalLink:`<path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/>`,
+
+  // ── Tiempo / cronómetro ──
+  clock:     `<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/>`,
+  play:      `<polygon points="5 3 19 12 5 21 5 3"/>`,
+  pause:     `<rect x="6" y="4" width="4" height="16"/><rect x="14" y="4" width="4" height="16"/>`,
+  stop:      `<rect x="3" y="3" width="18" height="18" rx="2"/>`,
+  timer:     `<circle cx="12" cy="13" r="8"/><path d="M12 9v4l2 2"/><path d="M5 3 2 6"/><path d="m22 6-3-3"/><path d="M6.38 18.7 4 21"/><path d="M17.64 18.67 20 21"/>`,
+
+  // ── Git / Repo ──
+  gitBranch: `<line x1="6" y1="3" x2="6" y2="15"/><circle cx="18" cy="6" r="3"/><circle cx="6" cy="18" r="3"/><path d="M18 9a9 9 0 0 1-9 9"/>`,
+  gitCommit: `<circle cx="12" cy="12" r="4"/><line x1="1.05" y1="12" x2="7" y2="12"/><line x1="17.01" y1="12" x2="22.96" y2="12"/>`,
+  gitMerge:  `<circle cx="18" cy="18" r="3"/><circle cx="6" cy="6" r="3"/><path d="M6 21V9a9 9 0 0 0 9 9"/>`,
+
+  // ── Información / estado ──
+  alertCircle: `<circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/>`,
+  alertTriangle:`<path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/>`,
+  checkCircle: `<path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/>`,
+  info:        `<circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/>`,
+  shield:      `<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>`,
+  zap:         `<polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2"/>`,
+  trending:    `<polyline points="23 6 13.5 15.5 8.5 10.5 1 18"/><polyline points="17 6 23 6 23 12"/>`,
+  target:      `<circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="6"/><circle cx="12" cy="12" r="2"/>`,
+
+  // ── Ficheros / docs ──
+  fileText:  `<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/><polyline points="10 9 9 9 8 9"/>`,
+  folder:    `<path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/>`,
+  download:  `<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/>`,
+
+  // ── Layout ──
+  maximize:   `<path d="M8 3H5a2 2 0 0 0-2 2v3m18 0V5a2 2 0 0 0-2-2h-3m0 18h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3"/>`,
+  columns:    `<rect x="3" y="3" width="18" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/>`,
+  terminal2:  `<polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/>`,
+  package:    `<line x1="16.5" y1="9.4" x2="7.5" y2="4.21"/><path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><polyline points="3.27 6.96 12 12.01 20.73 6.96"/><line x1="12" y1="22.08" x2="12" y2="12"/>`,
+};
+
+/**
+ * Renderiza un SVG icon
+ * @param {string} name - nombre del icono
+ * @param {number} [size=18] - tamaño en px
+ * @param {string} [className=''] - clases adicionales
+ * @returns {string} HTML string del SVG
+ */
+export function icon(name, size = 18, className = '') {
+  const paths = PATHS[name];
+  if (!paths) {
+    // Icono fallback: círculo vacío
+    return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="${className}" aria-hidden="true"><circle cx="12" cy="12" r="10" opacity="0.3"/></svg>`;
+  }
+  return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="${className}" aria-hidden="true">${paths}</svg>`;
+}
+
+/**
+ * Crea un elemento SVG icon insertado en el DOM
+ * @param {string} name
+ * @param {number} [size=18]
+ * @returns {SVGElement}
+ */
+export function iconEl(name, size = 18) {
+  const wrapper = document.createElement('span');
+  wrapper.innerHTML = icon(name, size);
+  return wrapper.firstElementChild;
+}
+
+export default { icon, iconEl };

package/ui/js/onboarding.js

@@ -0,0 +1,439 @@
+/**
+ * onboarding.js — Tour interactivo tipo spotlight
+ *
+ * Técnica: un div con box-shadow gigante rodea el target,
+ * dejando solo ese elemento visible. El tooltip-bocadillo
+ * tiene una flecha CSS que apunta directamente al target.
+ */
+
+import * as state from './state.js';
+import { t } from './i18n.js';
+
+const STORAGE_KEY = 'trackops-onboarding-v2';
+
+/* ── PASOS ──────────────────────────────────────────────────────────────── */
+
+const STEPS = [
+  // 0 — Bienvenida (sin target)
+  {
+    titleKey: 'ui.onboarding.welcome.title',
+    descKey: 'ui.onboarding.welcome.desc',
+    target:   null,
+    view:     null,
+    pos:      'center',
+  },
+
+  // 1 — Sidebar / navegación
+  {
+    titleKey: 'ui.onboarding.nav.title',
+    descKey: 'ui.onboarding.nav.desc',
+    target:   '#sidebar',
+    view:     'overview',
+    pos:      'right',
+  },
+
+  // 2 — KPI cards
+  {
+    titleKey: 'ui.onboarding.kpi.title',
+    descKey: 'ui.onboarding.kpi.desc',
+    target:   '.kpi-grid',
+    view:     'overview',
+    pos:      'bottom',
+  },
+
+  // 3 — Gráfico de actividad
+  {
+    titleKey: 'ui.onboarding.activity.title',
+    descKey: 'ui.onboarding.activity.desc',
+    target:   '.chart-card',
+    view:     'overview',
+    pos:      'bottom',
+  },
+
+  // 4 — Donut de progreso
+  {
+    titleKey: 'ui.onboarding.progress.title',
+    descKey: 'ui.onboarding.progress.desc',
+    target:   '.donut-wrapper',
+    view:     'overview',
+    pos:      'left',
+  },
+
+  // 5 — Time Tracker
+  {
+    titleKey: 'ui.onboarding.time.title',
+    descKey: 'ui.onboarding.time.desc',
+    target:   '.time-tracker-card',
+    view:     'overview',
+    pos:      'top',
+  },
+
+  // 6 — Topbar: búsqueda
+  {
+    titleKey: 'ui.onboarding.search.title',
+    descKey: 'ui.onboarding.search.desc',
+    target:   '.topbar-search',
+    view:     'overview',
+    pos:      'bottom',
+  },
+
+  // 7 — Board (Kanban)
+  {
+    titleKey: 'ui.onboarding.board.title',
+    descKey: 'ui.onboarding.board.desc',
+    target:   '.board-grid',
+    view:     'board',
+    pos:      'top',
+  },
+
+  // 8 — Editor de tareas
+  {
+    titleKey: 'ui.onboarding.tasks.title',
+    descKey: 'ui.onboarding.tasks.desc',
+    target:   '.task-list',
+    view:     'tasks',
+    pos:      'right',
+  },
+
+  // 9 — Ejecución / Consola
+  {
+    titleKey: 'ui.onboarding.execution.title',
+    descKey: 'ui.onboarding.execution.desc',
+    target:   '.terminal-surface',
+    view:     'execution',
+    pos:      'top',
+  },
+
+  // 10 — Analytics
+  {
+    titleKey: 'ui.onboarding.insights.title',
+    descKey: 'ui.onboarding.insights.desc',
+    target:   '.health-grid',
+    view:     'insights',
+    pos:      'bottom',
+  },
+
+  // 11 — AI Skill Hub
+  {
+    titleKey: 'ui.onboarding.skills.title',
+    descKey: 'ui.onboarding.skills.desc',
+    target:   '#view-skills',
+    view:     'skills',
+    pos:      'right',
+  },
+
+  // 12 — Theme toggle
+  {
+    titleKey: 'ui.onboarding.theme.title',
+    descKey: 'ui.onboarding.theme.desc',
+    target:   '#theme-toggle-btn',
+    view:     'overview',
+    pos:      'bottom',
+  },
+
+  // 13 — Fin
+  {
+    titleKey: 'ui.onboarding.done.title',
+    descKey: 'ui.onboarding.done.desc',
+    target:   null,
+    view:     null,
+    pos:      'center',
+  },
+];
+
+/* ── ESTADO ──────────────────────────────────────────────────────────────── */
+
+let _step      = 0;
+let _spotlight = null;
+let _tooltip   = null;
+let _active    = false;
+let _ring      = null;
+let _escHandler = null;
+
+/* ── API PÚBLICA ─────────────────────────────────────────────────────────── */
+
+export function init() {
+  _spotlight = document.getElementById('onboarding-spotlight');
+  _tooltip   = document.getElementById('onboarding-tooltip');
+  if (!_spotlight || !_tooltip) return;
+
+  _bindStaticEvents();
+
+  if (!localStorage.getItem(STORAGE_KEY)) {
+    setTimeout(show, 900);
+  }
+}
+
+export function show() {
+  _step   = 0;
+  _active = true;
+  _spotlight.classList.remove('is-hidden');
+  _tooltip.classList.remove('is-hidden');
+  _renderStep();
+}
+
+export function finish() {
+  _active = false;
+  localStorage.setItem(STORAGE_KEY, '1');
+  _spotlight.classList.add('is-hidden');
+  _tooltip.classList.add('is-hidden');
+  _clearRing();
+  _clearSpotlight();
+  if (_escHandler) {
+    document.removeEventListener('keydown', _escHandler);
+    _escHandler = null;
+  }
+  state.update('onboardingDone', true);
+}
+
+export function reset() {
+  localStorage.removeItem(STORAGE_KEY);
+}
+
+/* ── RENDERIZADO ─────────────────────────────────────────────────────────── */
+
+async function _renderStep() {
+  if (!_active) return;
+  const step   = STEPS[_step];
+  const total  = STEPS.length;
+  const isLast = _step === total - 1;
+  const isFirst = _step === 0;
+
+  // Navegar a la vista correcta antes de medir el target
+  if (step.view) {
+    const router = await import('./router.js');
+    if (router.current() !== step.view) {
+      await router.navigate(step.view);
+      // Esperar al siguiente frame para que el DOM esté pintado
+      await _nextFrame(120);
+    }
+  }
+
+  // Actualizar contenido del tooltip
+  document.getElementById('ob-step-label').textContent = t('ui.onboarding.step', { current: _step + 1, total }, `Step ${_step + 1} of ${total}`);
+  document.getElementById('ob-title').textContent       = t(step.titleKey, {}, step.titleKey);
+  document.getElementById('ob-desc').textContent        = t(step.descKey, {}, step.descKey);
+  document.getElementById('ob-prev').textContent        = t('ui.onboarding.prev', {}, 'Previous');
+  document.getElementById('ob-next').textContent        = isLast ? t('ui.onboarding.start', {}, 'Start') : t('ui.onboarding.next', {}, 'Next →');
+  document.getElementById('ob-prev').style.visibility  = isFirst ? 'hidden' : 'visible';
+
+  // Dots
+  const dotsEl = document.getElementById('ob-dots');
+  if (dotsEl) {
+    dotsEl.innerHTML = STEPS.map((_, i) =>
+      `<span class="ob-dot ${i === _step ? 'is-active' : ''}" aria-hidden="true"></span>`
+    ).join('');
+  }
+
+  // Mostrar tooltip con animación de entrada oculta temporalmente (para no saltar)
+  _tooltip.classList.remove('ob-enter');
+  _clearRing();
+
+  // Posicionar
+  if (step.target) {
+    const targetEl = _findTarget(step.target, step.view);
+    if (targetEl) {
+      // Hacer scroll suave para centrar el elemento en el viewport
+      targetEl.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'center' });
+      await _nextFrame(400); // Esperar que termine el scroll
+      _applySpotlight(targetEl);
+      _applyRing(targetEl);
+      _positionTooltip(targetEl, step.pos);
+      _mostrarTooltip();
+      return;
+    }
+  }
+
+  // Sin target → centrado
+  _clearSpotlight();
+  _positionCenter();
+  _mostrarTooltip();
+}
+
+function _mostrarTooltip() {
+  void _tooltip.offsetWidth; // reflow
+  _tooltip.classList.add('ob-enter');
+}
+
+/* ── SPOTLIGHT ───────────────────────────────────────────────────────────── */
+
+function _applySpotlight(el) {
+  const PADDING = 10;
+  const rect = el.getBoundingClientRect();
+
+  // El spotlight es el propio elemento; usamos box-shadow inmenso para oscurecer el resto
+  _spotlight.style.cssText = `
+    position: fixed;
+    left:   ${rect.left   - PADDING}px;
+    top:    ${rect.top    - PADDING}px;
+    width:  ${rect.width  + PADDING * 2}px;
+    height: ${rect.height + PADDING * 2}px;
+    border-radius: 12px;
+    box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.72);
+    z-index: var(--z-onboard);
+    pointer-events: none;
+    transition: all 280ms cubic-bezier(0.16, 1, 0.3, 1);
+  `;
+}
+
+function _clearSpotlight() {
+  _spotlight.style.cssText = `
+    position: fixed;
+    inset: 0;
+    box-shadow: 0 0 0 9999px rgba(0,0,0,0.72);
+    z-index: var(--z-onboard);
+    pointer-events: none;
+    background: transparent;
+    border-radius: 0;
+  `;
+}
+
+/* ── RING ANIMADO alrededor del target ───────────────────────────────────── */
+
+function _applyRing(el) {
+  _clearRing();
+  const PADDING = 10;
+  const rect = el.getBoundingClientRect();
+
+  _ring = document.createElement('div');
+  _ring.className = 'onboarding-ring';
+  _ring.setAttribute('aria-hidden', 'true');
+  _ring.style.cssText = `
+    position: fixed;
+    left:   ${rect.left   - PADDING}px;
+    top:    ${rect.top    - PADDING}px;
+    width:  ${rect.width  + PADDING * 2}px;
+    height: ${rect.height + PADDING * 2}px;
+    border-radius: 14px;
+    border: 2px solid var(--accent);
+    z-index: calc(var(--z-onboard) + 1);
+    pointer-events: none;
+    animation: ob-ring-pulse 1.8s ease-in-out infinite;
+  `;
+  document.body.appendChild(_ring);
+}
+
+function _clearRing() {
+  if (_ring) {
+    _ring.remove();
+    _ring = null;
+  }
+}
+
+/* ── POSICIONAMIENTO DEL TOOLTIP ─────────────────────────────────────────── */
+
+function _positionCenter() {
+  _tooltip.removeAttribute('data-pos');
+  _tooltip.style.cssText = `
+    position: fixed;
+    left: 50%;
+    top:  50%;
+    transform: translate(-50%, -50%);
+    z-index: calc(var(--z-onboard) + 2);
+  `;
+}
+
+function _positionTooltip(el, preferredPos) {
+  const MARGIN  = 18;
+  const TW      = 420; // Más ancho para acomodar navegación + botones
+  const TH      = 220;
+  const PADDING = 10;
+  const rect    = el.getBoundingClientRect();
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+
+  // Determinar la mejor posición disponible
+  const available = {
+    right:  vw - rect.right  - PADDING >= TW + MARGIN,
+    left:   rect.left - PADDING         >= TW + MARGIN,
+    bottom: vh - rect.bottom - PADDING  >= TH + MARGIN,
+    top:    rect.top   - PADDING        >= TH + MARGIN,
+  };
+
+  let pos = preferredPos;
+  if (!available[pos]) {
+    // Fallback en orden de preferencia
+    pos = ['right', 'left', 'bottom', 'top'].find(p => available[p]) || 'bottom';
+  }
+
+  let left, top;
+
+  switch (pos) {
+    case 'right':
+      left = rect.right + PADDING + MARGIN;
+      top  = rect.top + rect.height / 2 - TH / 2;
+      break;
+    case 'left':
+      left = rect.left - PADDING - MARGIN - TW;
+      top  = rect.top + rect.height / 2 - TH / 2;
+      break;
+    case 'bottom':
+      left = rect.left + rect.width / 2 - TW / 2;
+      top  = rect.bottom + PADDING + MARGIN;
+      break;
+    case 'top':
+      left = rect.left + rect.width / 2 - TW / 2;
+      top  = rect.top - PADDING - MARGIN - TH;
+      break;
+  }
+
+  // Clamp dentro del viewport
+  left = Math.max(MARGIN, Math.min(left, vw - TW - MARGIN));
+  top  = Math.max(MARGIN, Math.min(top,  vh - TH - MARGIN));
+
+  _tooltip.setAttribute('data-pos', pos);
+  _tooltip.style.cssText = `
+    position: fixed;
+    left: ${left}px;
+    top:  ${top}px;
+    width: ${TW}px;
+    z-index: calc(var(--z-onboard) + 2);
+    transform: none;
+  `;
+}
+
+/* ── EVENTOS ─────────────────────────────────────────────────────────────── */
+
+function _bindStaticEvents() {
+  const tooltip = _tooltip;
+  if (!tooltip) return;
+
+  tooltip.addEventListener('click', e => {
+    const btn = e.target.closest('button[id]');
+    if (!btn) return;
+    if (btn.id === 'ob-next') _advance(1);
+    if (btn.id === 'ob-prev') _advance(-1);
+    if (btn.id === 'ob-skip') finish();
+  });
+
+  // Escape para cerrar
+  _escHandler = e => {
+    if (e.key === 'Escape' && _active) finish();
+  };
+  document.addEventListener('keydown', _escHandler);
+
+  // Clic en el backdrop (fuera del tooltip) → cerrar
+  _spotlight.addEventListener('click', finish);
+}
+
+function _advance(dir) {
+  if (dir > 0 && _step === STEPS.length - 1) {
+    finish();
+    return;
+  }
+  _step = Math.max(0, Math.min(_step + dir, STEPS.length - 1));
+  _renderStep();
+}
+
+/* ── UTILS ───────────────────────────────────────────────────────────────── */
+
+function _findTarget(selector, _view) {
+  // Intentar el selector tal cual
+  let el = document.querySelector(selector);
+  if (el) return el;
+  return null;
+}
+
+function _nextFrame(ms = 60) {
+  return new Promise(res => setTimeout(res, ms));
+}

package/ui/js/router.js

@@ -0,0 +1,125 @@
+/**
+ * router.js — Navegación entre vistas
+ * Gestiona qué vista está activa en #view-container
+ * y sincroniza el estado activo en el sidebar.
+ */
+
+import * as state from './state.js';
+
+/** @type {Map<string, function(): HTMLElement|string>} */
+const _registry = new Map();
+let _currentView = null;
+let _container = null;
+
+/**
+ * Registra una vista
+ * @param {string} id - identificador único de la vista
+ * @param {function(): Promise<HTMLElement|string>} factory - función que devuelve el contenido
+ */
+export function register(id, factory) {
+  _registry.set(id, factory);
+}
+
+/**
+ * Inicializa el router
+ * @param {HTMLElement} container - #view-container
+ */
+export function init(container) {
+  _container = container;
+
+  // Navegación por hash
+  window.addEventListener('hashchange', _handleHash);
+
+  // Clic en nav-items del sidebar (delegación)
+  document.addEventListener('click', e => {
+    const item = e.target.closest('[data-view]');
+    if (!item || !item.dataset.view) return;
+    e.preventDefault();
+    navigate(item.dataset.view);
+  });
+}
+
+/**
+ * Navega a una vista
+ * @param {string} viewId
+ * @param {boolean} [updateHash=true]
+ */
+export async function navigate(viewId, updateHash = true) {
+  if (!_registry.has(viewId)) {
+    console.warn(`[router] Vista desconocida: "${viewId}"`);
+    return;
+  }
+
+  _currentView = viewId;
+  state.update('activeView', viewId);
+
+  // Actualizar hash sin trigger de hashchange
+  if (updateHash && window.location.hash !== `#${viewId}`) {
+    history.replaceState(null, '', `#${viewId}`);
+  }
+
+  // Actualizar clases activas en sidebar
+  document.querySelectorAll('[data-view]').forEach(item => {
+    item.classList.toggle('is-active', item.dataset.view === viewId);
+  });
+
+  // Renderizar contenido
+  if (_container) {
+    _container.innerHTML = '<div style="padding:2rem"><div class="spinner"></div></div>';
+    try {
+      const factory = _registry.get(viewId);
+      const content = await factory();
+      if (typeof content === 'string') {
+        _container.innerHTML = content;
+      } else if (content instanceof HTMLElement) {
+        _container.innerHTML = '';
+        _container.appendChild(content);
+      }
+      // Scroll to top
+      _container.scrollTop = 0;
+      // Focus para a11y (skip-link target)
+      _container.focus({ preventScroll: true });
+    } catch (err) {
+      console.error('[router] Error cargando vista:', err);
+      _container.innerHTML = `
+        <div class="empty-state" style="margin:2rem">
+          <p>Error al cargar la vista <strong>${viewId}</strong></p>
+          <p style="font-size:0.8rem;font-family:var(--font-mono)">${err.message}</p>
+        </div>`;
+    }
+  }
+}
+
+/**
+ * Refresca la vista actual (re-renderizado)
+ */
+export async function refresh() {
+  if (_currentView) {
+    await navigate(_currentView, false);
+  }
+}
+
+/**
+ * Obtiene la vista activa
+ */
+export function current() { return _currentView; }
+
+/**
+ * Handler de hashchange
+ */
+function _handleHash() {
+  const hash = window.location.hash.slice(1);
+  if (hash && _registry.has(hash) && hash !== _currentView) {
+    navigate(hash, false);
+  }
+}
+
+/**
+ * Carga la vista inicial desde el hash o usa la vista por defecto
+ * @param {string} [defaultView='overview']
+ */
+export async function start(defaultView = 'overview') {
+  const hash = window.location.hash.slice(1);
+  const initial = hash && _registry.has(hash) ? hash : defaultView;
+  await navigate(initial, true);
+}