stack-site-builder 1.10.0

package/src/components/SampleIndex.astro

@@ -0,0 +1,464 @@
+---
+// The samples hub: one card per samples/<folder>/ mini-project, titled and
+// excerpted from the locale-appropriate README. A single-column list with a
+// client-side control bar — free-text search, a "source tools" multi-select,
+// and a sort toggle (default newest first) — paginated 5 at a time. All state
+// mirrors into the URL (?q, ?tools, ?sort, ?page) and it degrades to
+// "show everything" without JS. Cards link to the per-sample page.
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import ChevronDown from './ChevronDown.astro';
+import { listProjects } from '../lib/project';
+import { getStacks, slugOf } from '../lib/stacks';
+import { getArticles } from '../lib/articles';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Props {
+  lang: Lang;
+}
+
+const { lang } = Astro.props;
+const t = useTranslations(lang);
+
+// Which catalog tools each sample is built with — the same frontmatter the
+// sample page derives its backlinks from, inverted folder → tools: the tool of
+// every stack that ships the folder (via `projects`), plus the `related` tools
+// declared on that stack's or an article's project entry.
+const stacks = await getStacks(lang);
+const articles = await getArticles(lang);
+const nameBySlug = new Map(stacks.map((s) => [slugOf(s), s.data.name]));
+
+const toolsByFolder = new Map<string, Set<string>>();
+const addTool = (folder: string, slug: string) => {
+  const set = toolsByFolder.get(folder) ?? new Set<string>();
+  set.add(slug);
+  toolsByFolder.set(folder, set);
+};
+for (const s of stacks) {
+  for (const p of s.data.projects) {
+    const folder = typeof p === 'string' ? p : p.folder;
+    addTool(folder, slugOf(s));
+    if (typeof p !== 'string') p.related.forEach((r) => addTool(folder, r));
+  }
+}
+for (const a of articles) {
+  const p = a.data.project;
+  if (!p || typeof p === 'string') continue;
+  p.related.forEach((r) => addTool(p.folder, r));
+}
+
+// Newest first, then by name — matches the client's default 'recent' sort, so
+// the server render and the initial client sort agree (no reorder flash). Only
+// tools that resolve to a real catalog entry are kept.
+const projects = listProjects(lang)
+  .map((p) => ({
+    ...p,
+    tools: [...(toolsByFolder.get(p.folder) ?? [])].filter((slug) => nameBySlug.has(slug)),
+  }))
+  .sort((a, b) => b.date.localeCompare(a.date) || a.name.localeCompare(b.name, lang));
+
+// The union of tools actually used across samples, as the filter's options.
+const toolFacet = [...new Set(projects.flatMap((p) => p.tools))]
+  .map((slug) => ({ slug, name: nameBySlug.get(slug) ?? slug }))
+  .sort((a, b) => a.name.localeCompare(b.name, lang));
+
+const sortOptions = [
+  { key: 'recent', label: t('sort.recent') },
+  { key: 'alpha', label: t('sort.alpha') },
+];
+// What the free-text search matches: the title (name + folder), the body
+// (excerpt), or both. `all` is the default.
+const scopeOptions = [
+  { key: 'all', label: t('sample.searchAll') },
+  { key: 'title', label: t('sample.searchTitle') },
+  { key: 'body', label: t('sample.searchBody') },
+];
+
+function formatDate(iso: string): string {
+  const [y, m, d] = iso.split('-').map(Number);
+  if (!y || !m || !d) return iso;
+  return new Intl.DateTimeFormat(lang === 'ko' ? 'ko-KR' : 'en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC',
+  }).format(new Date(Date.UTC(y, m - 1, d)));
+}
+
+const summaryClass =
+  'flex cursor-pointer items-center gap-1.5 rounded-lg border border-[var(--aas-border)] bg-[var(--aas-panel)] px-3 py-1.5 text-sm text-[var(--aas-text)]';
+const menuClass =
+  'absolute z-10 mt-1 max-h-72 min-w-[12rem] overflow-y-auto rounded-lg border border-[var(--aas-border)] bg-[var(--aas-panel)] p-1 shadow-lg';
+const optClass =
+  'flex w-full items-center justify-between gap-2 rounded px-2 py-1.5 text-left text-sm hover:bg-[var(--aas-tint)] aria-[current=true]:font-semibold aria-[current=true]:text-[var(--aas-accent)] aria-[pressed=true]:font-semibold aria-[pressed=true]:text-[var(--aas-accent)]';
+---
+
+<section class="py-6">
+  <h1 class="text-4xl font-bold tracking-tight">{t('sample.title')}</h1>
+  <p class="mt-3 max-w-2xl text-lg text-[var(--aas-muted)]">{t('sample.tagline')}</p>
+</section>
+
+{
+  projects.length > 0 && (
+    <div class="mt-2 flex flex-wrap items-center gap-2" data-sample-controls>
+      <details class="aas-dd">
+        <summary class={summaryClass}>
+          <span data-scope-label>{scopeOptions[0].label}</span>
+          <ChevronDown class="text-[var(--aas-muted)]" />
+        </summary>
+        <ul class={`${menuClass} left-0`}>
+          {scopeOptions.map((o, i) => (
+            <li>
+              <button
+                type="button"
+                data-scope={o.key}
+                aria-current={i === 0 ? 'true' : 'false'}
+                class={optClass}
+              >
+                {o.label}
+                <span data-check aria-hidden="true" class="opacity-0">
+                  ✓
+                </span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      </details>
+
+      <input
+        type="search"
+        data-sample-q
+        placeholder={t('sample.search')}
+        aria-label={t('sample.search')}
+        class="min-w-[10rem] flex-1 rounded-lg border border-[var(--aas-border)] bg-[var(--aas-panel)] px-3 py-1.5 text-sm text-[var(--aas-text)] placeholder:text-[var(--aas-muted)]"
+      />
+
+      {toolFacet.length > 0 && (
+        <details class="aas-dd">
+          <summary class={summaryClass}>
+            <span class="text-[var(--aas-muted)]">{t('sample.tools')}</span>
+            <span
+              data-tools-count
+              hidden
+              class="rounded bg-[var(--aas-accent)] px-1.5 text-xs font-semibold text-white"
+            />
+            <ChevronDown class="text-[var(--aas-muted)]" />
+          </summary>
+          <ul class={`${menuClass} left-0`}>
+            {toolFacet.map((tf) => (
+              <li>
+                <button type="button" data-tool-opt={tf.slug} aria-pressed="false" class={optClass}>
+                  {tf.name}
+                  <span data-check aria-hidden="true" class="opacity-0">
+                    ✓
+                  </span>
+                </button>
+              </li>
+            ))}
+          </ul>
+        </details>
+      )}
+
+      <button
+        type="button"
+        data-sample-clear
+        hidden
+        class="rounded-lg px-2 py-1.5 text-sm text-[var(--aas-muted)] hover:text-[var(--aas-text)]"
+      >
+        {t('filter.clear')}
+      </button>
+
+      <details class="aas-dd ml-auto">
+        <summary class={summaryClass}>
+          <span class="text-[var(--aas-muted)]">{t('sort.label')}:</span>
+          <span data-sort-label>{sortOptions[0].label}</span>
+          <ChevronDown class="text-[var(--aas-muted)]" />
+        </summary>
+        <ul class={`${menuClass} right-0`}>
+          {sortOptions.map((o, i) => (
+            <li>
+              <button
+                type="button"
+                data-sort={o.key}
+                aria-current={i === 0 ? 'true' : 'false'}
+                class={optClass}
+              >
+                {o.label}
+                <span data-check aria-hidden="true" class="opacity-0">
+                  ✓
+                </span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      </details>
+    </div>
+  )
+}
+
+{/* min-h reserves five card rows (5 × h-20 + 4 gaps) so a short last page
+    doesn't pull the pager up; the script drops it when nothing matches. */}
+<ul class="mt-4 grid min-h-[27.5rem] grid-cols-[minmax(0,1fr)] content-start gap-2.5" data-sample-grid>
+  {
+    projects.map((p) => (
+      <li
+        class="min-w-0"
+        data-sample-card
+        data-name={p.name}
+        data-date={p.date}
+        data-title={`${p.name} ${p.folder}`.toLowerCase()}
+        data-body={p.excerpt.toLowerCase()}
+        data-tools={p.tools.join(' ')}
+      >
+        <a
+          href={getRelativeLocaleUrl(lang, `sample/${p.folder}/`)}
+          class="aas-lift flex h-20 flex-col justify-center gap-1 overflow-hidden rounded-2xl border border-[var(--aas-border)] bg-[var(--aas-panel)] px-4 no-underline"
+        >
+          <span class="flex items-center gap-2">
+            <span class="min-w-0 truncate font-semibold text-[var(--aas-text)]">{p.name}</span>
+            <span class="ml-auto shrink-0 text-xs text-[var(--aas-muted)]">{formatDate(p.date)}</span>
+          </span>
+          <span class="flex items-center gap-2 text-xs">
+            <code class="shrink-0 rounded bg-[var(--aas-tint)] px-1.5 py-0.5 text-[var(--aas-muted)]">
+              samples/{p.folder}
+            </code>
+            {p.excerpt && (
+              <span class="min-w-0 truncate text-[var(--aas-muted)] opacity-60">{p.excerpt}</span>
+            )}
+          </span>
+        </a>
+      </li>
+    ))
+  }
+</ul>
+
+{/* Swapped in for the list when nothing matches — same five-row height, so
+    the pager and footer stay put. */}
+<p data-sample-empty hidden class="mt-4 flex min-h-[27.5rem] items-center justify-center text-sm text-[var(--aas-muted)]">
+  {t('sample.noResults')}
+</p>
+
+<nav data-pager aria-label="Pagination" class="mt-8 flex flex-wrap items-center justify-center gap-1.5"></nav>
+
+<script>
+  const bar = document.querySelector<HTMLElement>('[data-sample-controls]');
+  const grid = document.querySelector<HTMLElement>('[data-sample-grid]');
+  if (bar && grid) {
+    const PAGE = 5;
+    const DEFAULT_SORT = 'recent';
+    const cards = Array.from(grid.querySelectorAll<HTMLElement>('[data-sample-card]'));
+    const qInput = bar.querySelector<HTMLInputElement>('[data-sample-q]');
+    const scopeBtns = Array.from(bar.querySelectorAll<HTMLButtonElement>('[data-scope]'));
+    const scopeLabel = bar.querySelector<HTMLElement>('[data-scope-label]');
+    const toolBtns = Array.from(bar.querySelectorAll<HTMLButtonElement>('[data-tool-opt]'));
+    const toolsCount = bar.querySelector<HTMLElement>('[data-tools-count]');
+    const clearBtn = bar.querySelector<HTMLButtonElement>('[data-sample-clear]');
+    const sortBtns = Array.from(bar.querySelectorAll<HTMLButtonElement>('[data-sort]'));
+    const sortLabel = bar.querySelector<HTMLElement>('[data-sort-label]');
+    const pager = document.querySelector<HTMLElement>('[data-pager]');
+    const emptyEl = document.querySelector<HTMLElement>('[data-sample-empty]');
+
+    let q = '';
+    let scope = 'all';
+    const tools = new Set<string>();
+    let sort = DEFAULT_SORT;
+    let page = 1;
+
+    const byName = (a: HTMLElement, b: HTMLElement) =>
+      (a.dataset.name ?? '').localeCompare(b.dataset.name ?? '');
+    const comparator = () =>
+      sort === 'alpha'
+        ? byName
+        : (a: HTMLElement, b: HTMLElement) =>
+            (b.dataset.date ?? '').localeCompare(a.dataset.date ?? '') || byName(a, b);
+
+    function matches(card: HTMLElement) {
+      if (q) {
+        const title = card.dataset.title ?? '';
+        const body = card.dataset.body ?? '';
+        const hit =
+          scope === 'title' ? title.includes(q) : scope === 'body' ? body.includes(q) : title.includes(q) || body.includes(q);
+        if (!hit) return false;
+      }
+      if (tools.size) {
+        const ts = (card.dataset.tools ?? '').split(' ').filter(Boolean);
+        // A sample matches only if it uses ALL of the selected tools.
+        if (![...tools].every((t) => ts.includes(t))) return false;
+      }
+      return true;
+    }
+
+    function pageButton(label: string, target: number, opts: { current?: boolean; disabled?: boolean } = {}) {
+      const b = document.createElement('button');
+      b.type = 'button';
+      b.textContent = label;
+      b.dataset.page = String(target);
+      b.disabled = !!opts.disabled;
+      b.setAttribute('aria-current', opts.current ? 'page' : 'false');
+      b.className =
+        'min-w-9 rounded-lg border border-[var(--aas-border)] bg-[var(--aas-panel)] px-3 py-1.5 text-sm text-[var(--aas-text)] hover:bg-[var(--aas-tint)] disabled:pointer-events-none disabled:opacity-40 aria-[current=page]:border-[var(--aas-accent)] aria-[current=page]:font-semibold aria-[current=page]:text-[var(--aas-accent)]';
+      return b;
+    }
+
+    function renderPager(pages: number) {
+      if (!pager) return;
+      pager.replaceChildren();
+      // Page numbers in fixed groups of PAGE; the arrows jump a whole group
+      // (‹ → last page of the previous group, › → first of the next). The
+      // pager renders even for a single page (just "1", arrows disabled) so
+      // the layout below the list never jumps. A short group is padded to
+      // five slots with invisible placeholders, split evenly so the numbers
+      // stay centered while the arrows keep their exact position.
+      const start = Math.floor((page - 1) / PAGE) * PAGE + 1;
+      const end = Math.min(pages, start + PAGE - 1);
+      const missing = PAGE - (end - start + 1);
+      const padLeft = Math.floor(missing / 2);
+      const ghost = () => {
+        const b = pageButton('0', 0, { disabled: true });
+        b.classList.add('invisible');
+        return b;
+      };
+      pager.appendChild(pageButton('«', 1, { disabled: page === 1 }));
+      pager.appendChild(pageButton('‹', start - 1, { disabled: start === 1 }));
+      for (let i = 0; i < padLeft; i++) pager.appendChild(ghost());
+      for (let i = start; i <= end; i++) pager.appendChild(pageButton(String(i), i, { current: i === page }));
+      for (let i = 0; i < missing - padLeft; i++) pager.appendChild(ghost());
+      pager.appendChild(pageButton('›', end + 1, { disabled: end >= pages }));
+      pager.appendChild(pageButton('»', pages, { disabled: page === pages }));
+    }
+
+    function render() {
+      const visible = cards.filter(matches).sort(comparator());
+      visible.forEach((c) => grid!.appendChild(c)); // reorder to sorted order
+      const pages = Math.max(1, Math.ceil(visible.length / PAGE));
+      if (page > pages) page = pages;
+      const start = (page - 1) * PAGE;
+      cards.forEach((c) => {
+        c.style.display = 'none';
+      });
+      visible.forEach((c, i) => {
+        c.style.display = i >= start && i < start + PAGE ? '' : 'none';
+      });
+      // Zero matches: swap the (height-reserving) list for the equally tall
+      // empty-state message so nothing below moves.
+      grid!.style.display = visible.length === 0 ? 'none' : '';
+      if (emptyEl) emptyEl.hidden = visible.length !== 0;
+      renderPager(pages);
+    }
+
+    function updateToolUI() {
+      for (const b of toolBtns) {
+        const on = tools.has(b.dataset.toolOpt ?? '');
+        b.setAttribute('aria-pressed', String(on));
+        b.querySelector<HTMLElement>('[data-check]')?.classList.toggle('opacity-0', !on);
+      }
+      if (toolsCount) {
+        toolsCount.textContent = String(tools.size);
+        toolsCount.hidden = tools.size === 0;
+      }
+      if (clearBtn) clearBtn.hidden = q.length === 0 && tools.size === 0;
+    }
+
+    function updateSortUI() {
+      for (const b of sortBtns) {
+        const on = (b.dataset.sort ?? DEFAULT_SORT) === sort;
+        b.setAttribute('aria-current', String(on));
+        b.querySelector<HTMLElement>('[data-check]')?.classList.toggle('opacity-0', !on);
+        if (on && sortLabel) sortLabel.textContent = b.textContent?.replace('✓', '').trim() ?? '';
+      }
+    }
+
+    function updateScopeUI() {
+      for (const b of scopeBtns) {
+        const on = (b.dataset.scope ?? 'all') === scope;
+        b.setAttribute('aria-current', String(on));
+        b.querySelector<HTMLElement>('[data-check]')?.classList.toggle('opacity-0', !on);
+        if (on && scopeLabel) scopeLabel.textContent = b.textContent?.replace('✓', '').trim() ?? '';
+      }
+    }
+
+    function syncUrl() {
+      const url = new URL(location.href);
+      const set = (k: string, v: string) =>
+        v ? url.searchParams.set(k, v) : url.searchParams.delete(k);
+      set('q', qInput?.value.trim() ?? '');
+      set('scope', scope === 'all' ? '' : scope);
+      set('tools', [...tools].join(','));
+      set('sort', sort === DEFAULT_SORT ? '' : sort);
+      set('page', page === 1 ? '' : String(page));
+      history.replaceState(null, '', url);
+    }
+
+    qInput?.addEventListener('input', () => {
+      q = qInput.value.trim().toLowerCase();
+      page = 1;
+      updateToolUI();
+      render();
+      syncUrl();
+    });
+    for (const b of toolBtns) {
+      b.addEventListener('click', () => {
+        const slug = b.dataset.toolOpt ?? '';
+        if (tools.has(slug)) tools.delete(slug);
+        else tools.add(slug);
+        page = 1;
+        updateToolUI();
+        render();
+        syncUrl();
+      });
+    }
+    for (const b of scopeBtns) {
+      b.addEventListener('click', () => {
+        scope = b.dataset.scope ?? 'all';
+        page = 1;
+        updateScopeUI();
+        render();
+        syncUrl();
+        b.closest('details')?.removeAttribute('open');
+      });
+    }
+    for (const b of sortBtns) {
+      b.addEventListener('click', () => {
+        sort = b.dataset.sort ?? DEFAULT_SORT;
+        page = 1;
+        updateSortUI();
+        render();
+        syncUrl();
+        b.closest('details')?.removeAttribute('open');
+      });
+    }
+    clearBtn?.addEventListener('click', () => {
+      if (qInput) qInput.value = '';
+      q = '';
+      tools.clear();
+      page = 1;
+      updateToolUI();
+      render();
+      syncUrl();
+    });
+    pager?.addEventListener('click', (e) => {
+      const b = (e.target as HTMLElement).closest<HTMLButtonElement>('[data-page]');
+      if (!b || b.disabled) return;
+      page = Number(b.dataset.page);
+      render();
+      syncUrl();
+      window.scrollTo({ top: 0 });
+    });
+
+    // Restore state from the URL.
+    const params = new URLSearchParams(location.search);
+    const rawQ = params.get('q') ?? '';
+    if (qInput) qInput.value = rawQ;
+    q = rawQ.trim().toLowerCase();
+    const wantScope = params.get('scope');
+    if (wantScope && scopeBtns.some((b) => b.dataset.scope === wantScope)) scope = wantScope;
+    (params.get('tools') ?? '').split(',').filter(Boolean).forEach((slug) => tools.add(slug));
+    const wantSort = params.get('sort');
+    if (wantSort && sortBtns.some((b) => b.dataset.sort === wantSort)) sort = wantSort;
+    const wantPage = Number(params.get('page'));
+    if (Number.isFinite(wantPage) && wantPage > 0) page = wantPage;
+    updateToolUI();
+    updateSortUI();
+    updateScopeUI();
+    render();
+  }
+</script>

package/src/components/SamplePage.astro

@@ -0,0 +1,95 @@
+---
+// A sample's own page at sample/<folder>/ — the same viewer the stack impl tab
+// and article embeds use (locale-aware README, file tree, highlighted files),
+// plus "used by" backlinks to every stack and article that ships this folder.
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import Breadcrumb from './Breadcrumb.astro';
+import MermaidLoader from './MermaidLoader.astro';
+import ProjectViewer from './ProjectViewer.astro';
+import TocRail from './TocRail.astro';
+import { renderProjects } from '../lib/project';
+import { getStacks, slugOf, type ToolRef } from '../lib/stacks';
+import { getArticles, articleSlugOf } from '../lib/articles';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Props {
+  lang: Lang;
+  folder: string;
+}
+
+const { lang, folder } = Astro.props;
+const t = useTranslations(lang);
+
+const projects = await renderProjects([folder], lang);
+
+// "Used by" backlinks, derived from frontmatter that references this folder:
+// a stack's `projects` list or an article's `project` field. Related-tool
+// cards are NOT shown here — that association lives in the referencing page's
+// frontmatter, not in the sample itself, so it belongs on those pages.
+const stacks = await getStacks(lang);
+const articles = await getArticles(lang);
+
+const usedByStacks = stacks.filter((s) =>
+  s.data.projects.some((p) => (typeof p === 'string' ? p : p.folder) === folder),
+);
+const usedByArticles = articles.filter((a) => {
+  const p = a.data.project;
+  return p !== undefined && (typeof p === 'string' ? p : p.folder) === folder;
+});
+
+const related = new Map<string, ToolRef[]>();
+
+// The fixed right rail: the README's h2/h3 as the TOC + the clickable file list.
+const project = projects[0];
+const tocItems = project?.headings ?? [];
+const projectFiles = project ? { folder: project.folder, files: project.files } : undefined;
+
+const crumbs = [
+  { label: t('sample.title'), href: getRelativeLocaleUrl(lang, 'sample/') },
+  { label: `samples/${folder}` },
+];
+const usedBy = [
+  ...usedByStacks.map((s) => ({
+    label: s.data.name,
+    href: getRelativeLocaleUrl(lang, `stack/${slugOf(s)}/`),
+  })),
+  ...usedByArticles.map((a) => ({
+    label: a.data.title,
+    href: getRelativeLocaleUrl(lang, `article/${articleSlugOf(a)}/`),
+  })),
+];
+---
+
+<Breadcrumb segments={crumbs} />
+
+{/* Content + the same fixed right rail an article page has (README TOC,
+    related tools, file list). `embedded` drops the viewer's inline sidebar at
+    rail widths so the files aren't listed twice; aas-reading gives the README
+    body the same serif reading typography the articles and stack tabs use. */}
+<div class="mt-6 flex items-start gap-8">
+  <div class="aas-reading min-w-0 flex-1">
+    <ProjectViewer lang={lang} projects={projects} related={related} embedded />
+  </div>
+  <TocRail lang={lang} items={tocItems} projectFiles={projectFiles} />
+</div>
+
+{
+  usedBy.length > 0 && (
+    <aside class="mt-10 border-t border-[var(--aas-border)] pt-6">
+      <h2 class="text-sm font-semibold tracking-wide text-[var(--aas-muted)] uppercase">
+        {t('sample.usedBy')}
+      </h2>
+      <ul class="mt-3 space-y-2">
+        {usedBy.map((u) => (
+          <li>
+            <a href={u.href} class="text-[var(--aas-accent)] no-underline hover:underline">
+              {u.label}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </aside>
+  )
+}
+
+<MermaidLoader />

package/src/components/SampleProject.astro

@@ -0,0 +1,56 @@
+---
+// Inline, full-width callout linking to a sample's own page, for use inside an
+// article's MDX body, e.g.
+//   <SampleProject folder="tavily_1" />
+// Styled like <ArticleLink/> (accent left-bar callout with a label + date):
+// the full viewer — locale-aware README, file tree, highlighted files — lives
+// on the linked sample page instead of being embedded in the article.
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { listProjects } from '../lib/project';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Props {
+  folder: string;
+}
+
+const { folder } = Astro.props;
+const lang: Lang = Astro.currentLocale === 'ko' ? 'ko' : 'en';
+const t = useTranslations(lang);
+const target = listProjects(lang).find((p) => p.folder === folder);
+
+function formatDate(iso: string): string {
+  const [y, m, d] = iso.split('-').map(Number);
+  if (!y || !m || !d) return iso;
+  return new Intl.DateTimeFormat(lang === 'ko' ? 'ko-KR' : 'en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC',
+  }).format(new Date(Date.UTC(y, m - 1, d)));
+}
+---
+
+{
+  target && (
+    <a
+      href={getRelativeLocaleUrl(lang, `sample/${target.folder}/`)}
+      class="aas-lift mt-3 flex items-start gap-4 rounded-xl border border-l-4 p-4 no-underline"
+      style="border-color: var(--aas-border); border-left-color: var(--aas-accent); background: var(--aas-panel);"
+    >
+      <div class="min-w-0 flex-1">
+        <span class="block text-xs font-semibold tracking-wide text-[var(--aas-accent)] uppercase">
+          {t('sample.related')}
+        </span>
+        <span class="mt-0.5 block font-semibold text-[var(--aas-text)]">{target.name}</span>
+        {target.excerpt && (
+          <span class="mt-1 block text-sm text-[var(--aas-muted)]">{target.excerpt}</span>
+        )}
+        <span class="mt-1.5 flex flex-wrap items-center gap-2 text-xs text-[var(--aas-muted)]">
+          <code class="rounded bg-[var(--aas-tint)] px-1.5 py-0.5">samples/{target.folder}</code>
+          <span>{formatDate(target.date)}</span>
+        </span>
+      </div>
+      <span aria-hidden="true" class="shrink-0 text-xl text-[var(--aas-accent)]">&rarr;</span>
+    </a>
+  )
+}

package/src/components/Slide.astro

@@ -0,0 +1,36 @@
+---
+import type { ImageMetadata } from 'astro';
+
+// One slide in a deck. Authored in a deck's MDX as <Slide>…</Slide>; the deck
+// page (src/components/DeckView.astro) lays these out as a horizontal
+// scroll-snap presentation.
+//
+//   <Slide>             a normal slide (marked `default`; title pinned to top)
+//   <Slide class="cover">   title slide (centered, large)
+//   <Slide class="center">  short slide, vertically centered
+//   <Slide toc={false}>     keep this slide's headings out of the deck TOC
+//   <Slide bg={img}>        full-bleed background image (import it first); a
+//                           scrim + light text keep the content legible
+//   <Slide source="…">      small citation in the bottom-right corner (≤2 lines)
+interface Props {
+  class?: string;
+  /** Include this slide's headings in the deck's table of contents. */
+  toc?: boolean;
+  /** Full-bleed background image (an imported ImageMetadata). */
+  bg?: ImageMetadata;
+  /** A short source / citation, shown small in the slide's bottom-right corner. */
+  source?: string;
+}
+const { class: cls = 'default', toc = true, bg, source } = Astro.props;
+---
+
+<section
+  class:list={['aas-slide', cls, bg && 'has-bg']}
+  data-no-toc={toc ? undefined : ''}
+  style={bg ? `background-image: url(${bg.src})` : undefined}
+>
+  <div class="aas-slide-inner">
+    <slot />
+  </div>
+  {source && <p class="aas-slide-source">{source}</p>}
+</section>