examples.js

/**
 * GraphCompose showcase site — renders the category-driven gallery
 * from docs/examples.json. Generated by ShowcaseSync from
 * examples/target/generated-pdfs/.
 *
 * Author-side workflow:
 *   1) Add a new example .java under examples/.../com/demcha/examples/
 *      following the category subfolder convention
 *      (templates/<group>, features/<group>, flagships).
 *   2) Wire the example into GenerateAllExamples.
 *   3) Add a metadata entry in ShowcaseMetadata.java.
 *   4) Run GenerateAllExamples then ShowcaseSync — the new card
 *      appears here automatically without any HTML edits.
 */
(function () {
  'use strict';

  const MANIFEST_URL = 'examples.json';
  const CONTENT = document.getElementById('showcase-content');
  const SEARCH = document.getElementById('showcase-search');
  const FILTERS = document.getElementById('showcase-filters');

  // Hand-picked highlights — one strong tile from each category
  // shown at the top of #showcase so first-time visitors see the
  // most visually striking work immediately, instead of having to
  // scroll past 15 plain cover letters to find the cinematic
  // proposal or the canvas demo.
  const HIGHLIGHT_IDS = [
    'project-proposal-cinematic',
    'master-showcase',
    'invoice-cinematic',
    'cv-sidebar-portrait',
    'business-report',
    'canvas-layer-showcase',
    'cv-monogram-sidebar',
    'table-advanced'
  ];

  // category id -> short label shown as a badge on each tile.
  const CATEGORY_BADGE = {
    templates: 'Template',
    features: 'Feature',
    flagships: 'Flagship'
  };

  // Groups whose card grid is collapsed by default to "first 4
  // visible + Show all (N)" — protects the page from the 15-letter
  // cover letter wall while still letting users browse the full set.
  const COLLAPSE_GROUPS = new Set(['coverletter']);
  const COLLAPSED_VISIBLE = 4;

  let manifest = null;
  let activeCategory = 'all';
  let activeQuery = '';

  fetch(MANIFEST_URL, { cache: 'no-cache' })
    .then(r => {
      if (!r.ok) throw new Error('Manifest fetch failed: ' + r.status);
      return r.json();
    })
    .then(data => {
      manifest = data;
      injectFullItemListJsonLd();
      render();
    })
    .catch(err => {
      CONTENT.innerHTML =
        '<p class="showcase-error">Could not load showcase manifest. ' +
        'Run <code>ShowcaseSync</code> in the examples module then refresh.</p>';
      console.error(err);
    });

  // After the manifest loads, append a full ItemList JSON-LD block
  // listing every example. The static head ships only 7 entries
  // (so crawlers without JS still see structured data); this
  // upgrade gives Googlebot the complete 51-item catalogue once the
  // page renders.
  function injectFullItemListJsonLd() {
    if (!manifest || !document.head) return;
    const baseUrl = 'https://demchaav.github.io/GraphCompose/';
    const items = [];
    let position = 1;
    for (const category of manifest.categories || []) {
      for (const group of category.groups || []) {
        for (const ex of group.examples || []) {
          if (!ex || !ex.id) continue;
          const item = {
            '@type': 'ListItem',
            position: position++,
            name: ex.title || ex.id,
            url: ex.pdf ? baseUrl + ex.pdf : baseUrl
          };
          if (ex.description) item.description = ex.description;
          if (ex.screenshot) item.image = baseUrl + ex.screenshot;
          items.push(item);
        }
      }
    }
    const data = {
      '@context': 'https://schema.org',
      '@type': 'ItemList',
      name: 'GraphCompose showcase examples',
      description: 'Full searchable catalogue of GraphCompose example PDFs (templates, features, flagships).',
      numberOfItems: items.length,
      itemListElement: items
    };
    const script = document.createElement('script');
    script.type = 'application/ld+json';
    script.dataset.injected = 'examples-itemlist';
    script.textContent = JSON.stringify(data);
    document.head.appendChild(script);
  }

  if (FILTERS) {
    FILTERS.addEventListener('click', e => {
      const btn = e.target.closest('button[data-category]');
      if (!btn) return;
      activeCategory = btn.dataset.category || 'all';
      FILTERS.querySelectorAll('.filter-pill').forEach(b => {
        b.classList.toggle('is-active', b === btn);
      });
      render();
    });
  }

  if (SEARCH) {
    SEARCH.addEventListener('input', e => {
      activeQuery = (e.target.value || '').trim().toLowerCase();
      render();
    });
  }

  // Build an { id -> {example, categoryId} } lookup so highlight
  // tiles can resolve their data without rerunning the search loop.
  function buildIndex() {
    const idx = new Map();
    for (const category of manifest.categories || []) {
      for (const group of category.groups || []) {
        for (const example of group.examples || []) {
          if (example && example.id) {
            idx.set(example.id, { example, categoryId: category.id, groupId: group.id });
          }
        }
      }
    }
    return idx;
  }

  function render() {
    if (!manifest) return;
    const fragments = [];
    let total = 0;
    const index = buildIndex();

    // Highlights strip: rendered when no search query is active and
    // the user hasn't drilled into a single category. Once they
    // start filtering, hide the strip — they're past the wow stage
    // and into "find the specific one" territory.
    const showHighlights =
        !activeQuery && activeCategory === 'all';
    if (showHighlights) {
      const tiles = [];
      for (const id of HIGHLIGHT_IDS) {
        const hit = index.get(id);
        if (hit) tiles.push(renderHighlight(hit.example, hit.categoryId));
      }
      if (tiles.length > 0) {
        fragments.push(renderHighlightsStrip(tiles));
      }
    }

    for (const category of manifest.categories || []) {
      if (activeCategory !== 'all' && activeCategory !== category.id) {
        continue;
      }
      const groupBlocks = [];
      let categoryCount = 0;
      for (const group of category.groups || []) {
        const matching = (group.examples || []).filter(matchesQuery);
        if (matching.length === 0) continue;
        categoryCount += matching.length;
        groupBlocks.push(renderGroup(group, matching));
      }
      if (categoryCount === 0) continue;
      total += categoryCount;
      fragments.push(renderCategory(category, groupBlocks, categoryCount));
    }

    if (total === 0) {
      CONTENT.innerHTML =
        '<p class="showcase-empty">No examples match the current filter or search query.</p>';
      return;
    }
    CONTENT.innerHTML = fragments.join('\n');
    afterRender();
  }

  // Post-render hook: wire scroll arrows on the highlights strip
  // (only meaningful once the actual DOM exists and we can measure
  // overflow). Runs after every render() so it picks up the strip
  // appearing/disappearing on filter changes.
  function afterRender() {
    initHighlightsArrows();
  }

  function initHighlightsArrows() {
    const strip = CONTENT.querySelector('.highlights-strip');
    if (!strip) return;
    // Skip if we already attached arrows on a previous render.
    if (strip.dataset.arrowsReady === '1') return;
    strip.dataset.arrowsReady = '1';

    const wrapper = strip.parentElement;
    if (!wrapper) return;
    wrapper.classList.add('has-strip-arrows');

    const left = document.createElement('button');
    left.type = 'button';
    left.className = 'strip-arrow strip-arrow-left';
    left.setAttribute('aria-label', 'Scroll featured examples left');
    left.innerHTML = '&#x2039;';

    const right = document.createElement('button');
    right.type = 'button';
    right.className = 'strip-arrow strip-arrow-right';
    right.setAttribute('aria-label', 'Scroll featured examples right');
    right.innerHTML = '&#x203A;';

    const tileStep = () => {
      const tile = strip.querySelector('.highlight-tile');
      if (!tile) return 320;
      const styles = window.getComputedStyle(strip);
      const gap = parseFloat(styles.columnGap || styles.gap || '0') || 0;
      return tile.getBoundingClientRect().width + gap;
    };

    left.addEventListener('click', () => {
      strip.scrollBy({ left: -tileStep(), behavior: 'smooth' });
    });
    right.addEventListener('click', () => {
      strip.scrollBy({ left: tileStep(), behavior: 'smooth' });
    });

    const updateArrowState = () => {
      const max = strip.scrollWidth - strip.clientWidth;
      const overflow = max > 4;
      wrapper.classList.toggle('strip-overflow', overflow);
      left.disabled = strip.scrollLeft <= 2;
      right.disabled = strip.scrollLeft >= max - 2;
    };

    strip.addEventListener('scroll', updateArrowState, { passive: true });
    window.addEventListener('resize', updateArrowState, { passive: true });

    wrapper.appendChild(left);
    wrapper.appendChild(right);
    // Initial state once layout settles.
    requestAnimationFrame(updateArrowState);
  }

  function renderHighlightsStrip(tiles) {
    return [
      '<section class="showcase-highlights" aria-labelledby="highlights-heading">',
      '  <header class="highlights-heading">',
      '    <h3 id="highlights-heading">Featured</h3>',
      '    <p class="highlights-sub">A spread across templates, features, and flagships &mdash; click any tile to zoom.</p>',
      '  </header>',
      '  <div class="highlights-strip" role="list">',
      tiles.join('\n'),
      '  </div>',
      '</section>'
    ].join('\n');
  }

  function renderHighlight(ex, categoryId) {
    const screenshot = ex.screenshot || '';
    const pdf = ex.pdf || '';
    const code = ex.code || '#';
    const badge = CATEGORY_BADGE[categoryId] || '';
    return [
      '<article class="highlight-tile" data-id="' + escAttr(ex.id || '') + '" role="listitem">',
      '  <button type="button" class="highlight-preview"',
      '          data-action="lightbox"',
      '          data-screenshot="' + escAttr(screenshot) + '"',
      '          data-pdf="' + escAttr(pdf) + '"',
      '          data-code="' + escAttr(code) + '"',
      '          data-title="' + escAttr(ex.title || ex.id || '') + '"',
      '          aria-label="Open preview for ' + escAttr(ex.title || ex.id || '') + '">',
      screenshot
        ? '    <img loading="lazy" decoding="async" width="595" height="842" src="' + escAttr(screenshot) + '" alt="' + escAttr(ex.title || '') + ' preview">'
        : '    <div class="example-preview-fallback">PDF</div>',
      badge ? '    <span class="highlight-badge">' + escHtml(badge) + '</span>' : '',
      '  </button>',
      '  <div class="highlight-meta">',
      '    <h5 class="highlight-title">' + escHtml(ex.title || ex.id || '') + '</h5>',
      '    <p class="highlight-desc">' + escHtml(ex.description || '') + '</p>',
      '  </div>',
      '</article>'
    ].join('\n');
  }

  function matchesQuery(example) {
    if (!activeQuery) return true;
    const haystack = [
      example.id || '',
      example.title || '',
      example.description || '',
      (example.tags || []).join(' ')
    ].join(' ').toLowerCase();
    return haystack.includes(activeQuery);
  }

  function renderCategory(category, groupBlocks, count) {
    const sectionId = category.id + '-section';
    return [
      '<section class="showcase-category" id="' + escAttr(sectionId) + '">',
      '  <header class="category-heading">',
      '    <h3>' + escHtml(category.label) + '</h3>',
      '    <span class="category-count">' + count + ' example' + (count === 1 ? '' : 's') + '</span>',
      '  </header>',
      groupBlocks.join('\n'),
      '</section>'
    ].join('\n');
  }

  function renderGroup(group, examples) {
    const collapsible = COLLAPSE_GROUPS.has(group.id) && examples.length > COLLAPSED_VISIBLE;
    const groupClass = collapsible
      ? 'showcase-group is-collapsible is-collapsed'
      : 'showcase-group';
    const dataAttr = collapsible
      ? ' data-visible="' + COLLAPSED_VISIBLE + '"'
      : '';
    const toggle = collapsible
      ? '    <button type="button" class="group-toggle" data-action="toggle-group">'
        + 'Show all <span class="group-toggle-count">' + examples.length + '</span> &darr;'
        + '</button>'
      : '';
    return [
      '  <section class="' + groupClass + '"' + dataAttr + '>',
      '    <header class="group-heading"><h4>' + escHtml(group.label) + '</h4>',
      '    <span class="group-count">' + examples.length + '</span></header>',
      '    <div class="examples-grid">',
      examples.map(renderCard).join('\n'),
      '    </div>',
      toggle,
      '  </section>'
    ].join('\n');
  }

  function renderCard(ex) {
    const tags = (ex.tags || [])
      .map(t => '<span class="tag">' + escHtml(t) + '</span>').join('');
    const screenshot = ex.screenshot || '';
    const pdf = ex.pdf || '';
    const code = ex.code || '#';
    const altText = buildAlt(ex);
    return [
      '<article class="example-card" data-id="' + escAttr(ex.id || '') + '">',
      '  <button type="button" class="example-preview"',
      '          data-action="lightbox"',
      '          data-screenshot="' + escAttr(screenshot) + '"',
      '          data-pdf="' + escAttr(pdf) + '"',
      '          data-code="' + escAttr(code) + '"',
      '          data-title="' + escAttr(ex.title || ex.id || '') + '"',
      '          aria-label="Open preview for ' + escAttr(ex.title || ex.id || '') + '">',
      screenshot
        ? '    <img loading="lazy" decoding="async" width="595" height="842" src="' + escAttr(screenshot) + '" alt="' + escAttr(altText) + '">'
        : '    <div class="example-preview-fallback">PDF</div>',
      '    <span class="example-zoom-hint">Click to zoom</span>',
      '  </button>',
      '  <div class="example-body">',
      '    <h5 class="example-title">' + escHtml(ex.title || ex.id || '') + '</h5>',
      '    <p class="example-desc">' + escHtml(ex.description || '') + '</p>',
      tags ? '    <div class="example-tags">' + tags + '</div>' : '',
      '    <div class="example-actions">',
      '      <a class="example-action" href="' + escAttr(pdf) + '" target="_blank" rel="noopener" aria-label="Open PDF">View PDF</a>',
      '      <a class="example-action example-action-ghost" href="' + escAttr(code) + '" target="_blank" rel="noopener" aria-label="Open source on GitHub">View Code</a>',
      '    </div>',
      '  </div>',
      '</article>'
    ].join('\n');
  }

  // Build a descriptive img alt: prefer "{title} — {first sentence
  // of description}" so screen-reader users + image-search crawlers
  // get more than just "X preview".
  function buildAlt(ex) {
    const title = (ex.title || ex.id || '').trim();
    let desc = (ex.description || '').trim();
    if (desc) {
      // Strip trailing period, take only first sentence, cap length.
      const sentenceEnd = desc.search(/[.!?](\s|$)/);
      if (sentenceEnd > 0) desc = desc.slice(0, sentenceEnd);
      if (desc.length > 110) desc = desc.slice(0, 107).trim() + '...';
      return title + ' — ' + desc;
    }
    return title + ' preview';
  }

  // === Lightbox ===
  // Click a preview card -> open a full-size modal with the
  // screenshot. Esc / click outside / close button to dismiss.
  let lightbox = null;
  function ensureLightbox() {
    if (lightbox) return lightbox;
    lightbox = document.createElement('div');
    lightbox.className = 'lightbox';
    lightbox.setAttribute('role', 'dialog');
    lightbox.setAttribute('aria-modal', 'true');
    lightbox.setAttribute('aria-hidden', 'true');
    lightbox.innerHTML = [
      '<div class="lightbox-backdrop" data-close></div>',
      '<div class="lightbox-frame">',
      '  <header class="lightbox-header">',
      '    <h4 class="lightbox-title"></h4>',
      '    <div class="lightbox-actions">',
      '      <a class="example-action lightbox-pdf-link" target="_blank" rel="noopener" aria-label="Open PDF">Open PDF</a>',
      '      <a class="example-action example-action-ghost lightbox-code-link" target="_blank" rel="noopener" aria-label="Open source on GitHub">View Code</a>',
      '      <button class="lightbox-close" type="button" aria-label="Close" data-close>&times;</button>',
      '    </div>',
      '  </header>',
      '  <div class="lightbox-body">',
      '    <img class="lightbox-image" alt="">',
      '  </div>',
      '</div>'
    ].join('\n');
    document.body.appendChild(lightbox);
    lightbox.addEventListener('click', e => {
      if (e.target.closest('[data-close]')) {
        closeLightbox();
      }
    });
    document.addEventListener('keydown', e => {
      if (e.key === 'Escape' && lightbox.classList.contains('is-open')) {
        closeLightbox();
      }
    });
    return lightbox;
  }
  function openLightbox(screenshot, pdf, code, title) {
    const lb = ensureLightbox();
    lb.querySelector('.lightbox-image').src = screenshot;
    lb.querySelector('.lightbox-image').alt = title + ' preview';
    lb.querySelector('.lightbox-title').textContent = title;
    lb.querySelector('.lightbox-pdf-link').href = pdf;
    const codeLink = lb.querySelector('.lightbox-code-link');
    if (code && code !== '#') {
      codeLink.href = code;
      codeLink.style.display = '';
    } else {
      codeLink.style.display = 'none';
    }
    lb.classList.add('is-open');
    lb.setAttribute('aria-hidden', 'false');
    document.body.classList.add('lightbox-open');
  }
  function closeLightbox() {
    if (!lightbox) return;
    lightbox.classList.remove('is-open');
    lightbox.setAttribute('aria-hidden', 'true');
    document.body.classList.remove('lightbox-open');
  }
  document.addEventListener('click', e => {
    // Group expand/collapse (oversized groups like Cover Letter).
    const toggleBtn = e.target.closest('[data-action="toggle-group"]');
    if (toggleBtn) {
      const group = toggleBtn.closest('.showcase-group');
      if (group) {
        const collapsed = group.classList.toggle('is-collapsed');
        const total = group.querySelectorAll('.example-card').length;
        toggleBtn.innerHTML = collapsed
          ? 'Show all <span class="group-toggle-count">' + total + '</span> &darr;'
          : 'Show fewer &uarr;';
      }
      return;
    }

    const trigger = e.target.closest('[data-action="lightbox"]');
    if (!trigger) return;
    e.preventDefault();
    const screenshot = trigger.dataset.screenshot;
    const pdf = trigger.dataset.pdf;
    const code = trigger.dataset.code;
    const title = trigger.dataset.title;
    if (screenshot) {
      openLightbox(screenshot, pdf, code, title);
    } else if (pdf) {
      window.open(pdf, '_blank');
    }
  });

  function escHtml(s) {
    return String(s)
      .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
      .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
  }

  function escAttr(s) {
    return escHtml(s);
  }
})();