/**
 * HOA Management System — Module Setup Guide
 *
 * Generic, reusable per-module onboarding card. Used by any module to render
 * a collapsible "How to use this module" checklist with progress tracking
 * and per-step "Go" action buttons.
 *
 * Strict rules:
 *   - Token-driven. No hard-coded colors.
 *   - DOM is a single self-contained block — drop into any container.
 *   - Dark-mode aware via [data-theme="dark"] on existing semantic tokens.
 *   - Brand color (HOA green) used for completed steps + progress bar.
 *
 * Markup contract (rendered by App.renderModuleGuide()):
 *
 *   <div class="module-guide" data-guide-key="payments">
 *     <header class="module-guide-header">
 *       <div>
 *         <h2 class="module-guide-title">{title} Guide</h2>
 *         <p class="module-guide-subtitle">{N of M steps completed}</p>
 *       </div>
 *       <button class="module-guide-close" aria-label="Dismiss guide">
 *         <i class="bi bi-x-lg"></i>
 *       </button>
 *     </header>
 *     <div class="module-guide-progress" role="progressbar"
 *          aria-valuemin="0" aria-valuemax="100" aria-valuenow="{pct}">
 *       <div class="module-guide-progress-bar" style="width:{pct}%"></div>
 *     </div>
 *     <ol class="module-guide-steps">
 *       <li class="module-guide-step is-done|is-active|is-pending">
 *         <span class="module-guide-step-circle">
 *           <i class="bi bi-check-lg"></i>  // or step number
 *         </span>
 *         <div class="module-guide-step-body">
 *           <h3 class="module-guide-step-title">{label}</h3>
 *           <p class="module-guide-step-desc">{description}</p>
 *         </div>
 *         <button class="module-guide-step-action" data-mg-step="0">Go</button>
 *       </li>
 *       ...
 *     </ol>
 *   </div>
 */

.module-guide {
    --mg-radius: 16px;
    --mg-radius-sm: 10px;
    --mg-radius-pill: 999px;
    --mg-ease: cubic-bezier(0.4, 0, 0.2, 1);
    --mg-transition: 0.2s var(--mg-ease);
    --mg-circle-size: 32px;
    --mg-track-color: var(--bg-subtle);
    --mg-fill-color: var(--brand-primary);
    --mg-font: "Figtree", "Inter", -apple-system, BlinkMacSystemFont,
               "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;

    display: block;
    background: var(--bg-surface);
    border: 1px solid var(--brand-primary-border);
    border-radius: var(--mg-radius);
    box-shadow: var(--shadow-xs);
    padding: 18px 22px;
    margin-bottom: 18px;
    font-family: var(--mg-font);
    color: var(--text-primary);
    transition: box-shadow var(--mg-transition);
    animation: mgSlideIn 0.3s var(--mg-ease);
}
.module-guide:hover { box-shadow: var(--shadow-sm); }

@keyframes mgSlideIn {
    from { opacity: 0; transform: translateY(-6px); }
    to   { opacity: 1; transform: translateY(0); }
}

/* ── Header ──────────────────────────────────────────────────────────── */
.module-guide-header {
    display: flex;
    align-items: flex-start;
    justify-content: space-between;
    gap: 16px;
    margin-bottom: 10px;
}

.module-guide-title {
    font-size: 1.05rem;
    font-weight: 700;
    letter-spacing: -0.015em;
    color: var(--text-primary);
    margin: 0;
}

.module-guide-subtitle {
    font-size: 0.8rem;
    color: var(--text-secondary);
    margin: 2px 0 0;
    font-weight: 500;
}

.module-guide-close {
    background: transparent;
    border: none;
    color: var(--text-muted);
    width: 30px;
    height: 30px;
    border-radius: 8px;
    display: inline-flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
    flex-shrink: 0;
    transition: background var(--mg-transition),
                color var(--mg-transition);
}
.module-guide-close:hover {
    background: var(--bg-hover);
    color: var(--text-primary);
}
.module-guide-close:focus-visible {
    outline: none;
    box-shadow: var(--shadow-focus);
}

/* ── Progress bar ────────────────────────────────────────────────────── */
.module-guide-progress {
    height: 6px;
    background: var(--mg-track-color);
    border-radius: var(--mg-radius-pill);
    overflow: hidden;
    margin-bottom: 14px;
}
.module-guide-progress-bar {
    height: 100%;
    background: var(--mg-fill-color);
    border-radius: var(--mg-radius-pill);
    transition: width 0.5s var(--mg-ease);
    min-width: 0;
}

/* ── Steps list ──────────────────────────────────────────────────────── */
.module-guide-steps {
    list-style: none;
    padding: 0;
    margin: 0;
}

.module-guide-step {
    display: flex;
    align-items: flex-start;
    gap: 14px;
    padding: 14px 0;
    border-top: 1px solid var(--border-default);
    transition: background var(--mg-transition);
}
.module-guide-step:first-child { border-top: none; padding-top: 4px; }
.module-guide-step:last-child  { padding-bottom: 4px; }

/* Step circle */
.module-guide-step-circle {
    width: var(--mg-circle-size);
    height: var(--mg-circle-size);
    border-radius: 50%;
    display: inline-flex;
    align-items: center;
    justify-content: center;
    flex-shrink: 0;
    font-size: 0.85rem;
    font-weight: 700;
    line-height: 1;
    color: var(--text-inverse);
    box-shadow: var(--shadow-xs);
    transition: background var(--mg-transition),
                transform var(--mg-transition);
}

/* Done step — brand green check */
.module-guide-step.is-done .module-guide-step-circle {
    background: var(--brand-primary);
    color: var(--brand-on-primary);
}
.module-guide-step.is-done .module-guide-step-circle i {
    font-size: 0.95rem;
}

/* Active step — brand-tinted blue (use info token to differentiate) */
.module-guide-step.is-active .module-guide-step-circle {
    background: var(--color-blue-500);
    color: var(--color-white);
}

/* Pending step — muted gray */
.module-guide-step.is-pending .module-guide-step-circle {
    background: var(--bg-subtle);
    color: var(--text-secondary);
    box-shadow: none;
    border: 1px solid var(--border-default);
}

/* Step body */
.module-guide-step-body {
    flex: 1;
    min-width: 0;
}

.module-guide-step-title {
    font-size: 0.92rem;
    font-weight: 700;
    color: var(--text-primary);
    margin: 0 0 3px;
    line-height: 1.35;
    letter-spacing: -0.005em;
}

/* Done step title — strikethrough + muted */
.module-guide-step.is-done .module-guide-step-title {
    text-decoration: line-through;
    color: var(--text-muted);
    font-weight: 600;
}

.module-guide-step-desc {
    font-size: 0.84rem;
    color: var(--text-secondary);
    margin: 0;
    line-height: 1.5;
}
.module-guide-step.is-done .module-guide-step-desc {
    color: var(--text-muted);
}

/* Step action button — only shown on the active step typically */
.module-guide-step-action {
    flex-shrink: 0;
    align-self: center;
    background: var(--color-blue-500);
    color: var(--color-white) !important;
    border: 1px solid var(--color-blue-500);
    border-radius: var(--mg-radius-sm);
    font-size: 0.78rem;
    font-weight: 700;
    padding: 6px 16px;
    text-decoration: none;
    cursor: pointer;
    display: inline-flex;
    align-items: center;
    gap: 4px;
    transition: background var(--mg-transition),
                border-color var(--mg-transition),
                transform var(--mg-transition),
                box-shadow var(--mg-transition);
}
.module-guide-step-action:hover {
    background: var(--color-blue-600);
    border-color: var(--color-blue-600);
    color: var(--color-white) !important;
    transform: translateY(-1px);
    box-shadow: var(--shadow-sm);
}
.module-guide-step-action:focus-visible {
    outline: none;
    box-shadow: var(--shadow-focus);
}

/* Optional secondary "View Guide" action variant — outlined */
.module-guide-step-action.is-secondary {
    background: transparent;
    color: var(--color-blue-600) !important;
    border-color: var(--color-blue-300, var(--color-blue-400));
}
.module-guide-step-action.is-secondary:hover {
    background: var(--bg-info);
    color: var(--color-blue-700) !important;
}

/* ── Collapsed variant — completed guides shrink to a one-line acknowledgment */
.module-guide.is-complete {
    background: var(--brand-primary-subtle);
    border-color: var(--brand-primary);
}
.module-guide.is-complete .module-guide-progress { display: none; }
.module-guide.is-complete .module-guide-steps { display: none; }
.module-guide.is-complete .module-guide-title::before {
    content: "\2713  ";
    color: var(--brand-primary);
    font-weight: 700;
}

/* ── Responsive ──────────────────────────────────────────────────────── */
@media (max-width: 640px) {
    .module-guide { padding: 14px 16px; }
    .module-guide-step { gap: 10px; }
    .module-guide-step-action {
        padding: 5px 12px;
        font-size: 0.74rem;
    }
}

/* ── Reduced motion ──────────────────────────────────────────────────── */
@media (prefers-reduced-motion: reduce) {
    .module-guide,
    .module-guide-progress-bar,
    .module-guide-step,
    .module-guide-step-circle,
    .module-guide-step-action,
    .module-guide-close {
        animation: none !important;
        transition: none !important;
    }
}

/* ── Print — hide guides ─────────────────────────────────────────────── */
@media print {
    .module-guide { display: none !important; }
}