stack-site-builder 1.10.0

package/src/components/CollapsibleGrid.astro

@@ -0,0 +1,50 @@
+---
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Props {
+  lang: Lang;
+  count: number; // total number of cards in the slot
+}
+
+// Show the first 6 cards (3 rows × 2 cols); collapse the rest behind a toggle.
+// The 6-item cutoff is enforced in CSS (:nth-child(n+7)); keep them in sync.
+const LIMIT = 6;
+const { lang, count } = Astro.props;
+const t = useTranslations(lang);
+const extra = count - LIMIT;
+---
+
+<div class="mt-3" data-collapse-grid={extra > 0 ? '' : undefined}>
+  <div class="grid gap-3 sm:grid-cols-2" data-collapse-items>
+    <slot />
+  </div>
+  {
+    extra > 0 && (
+      <button
+        type="button"
+        data-collapse-toggle
+        class="mt-3 text-xs font-medium text-[var(--aas-accent)]"
+      >
+        <span data-more>{t('collapse.more').replace('{n}', String(extra))}</span>
+        <span data-less hidden>
+          {t('collapse.less')}
+        </span>
+      </button>
+    )
+  }
+</div>
+
+<script>
+  // Delegated toggle: reveal/hide the cards beyond the CSS cutoff. One listener
+  // covers every CollapsibleGrid on the page (the script is bundled once).
+  document.addEventListener('click', (e) => {
+    const target = e.target as HTMLElement | null;
+    const btn = target?.closest?.('[data-collapse-toggle]');
+    if (!btn) return;
+    const wrap = btn.closest('[data-collapse-grid]');
+    if (!wrap) return;
+    const expanded = wrap.toggleAttribute('data-expanded');
+    btn.querySelector('[data-more]')?.toggleAttribute('hidden', expanded);
+    btn.querySelector('[data-less]')?.toggleAttribute('hidden', !expanded);
+  });
+</script>

package/src/components/ConceptCard.astro

@@ -0,0 +1,59 @@
+---
+import { Image } from 'astro:assets';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { formatDate } from '../lib/dates';
+import { inlineMd } from '../lib/inline-md';
+import type { ImageMetadata } from 'astro';
+
+interface Props {
+  lang: Lang;
+  slug: string;
+  title: string;
+  description: string;
+  tags: string[];
+  image?: ImageMetadata;
+  imageAlt?: string;
+  version?: string;
+  updated?: Date;
+}
+
+const { lang, slug, title, description, tags, image, imageAlt, version, updated } = Astro.props;
+const t = useTranslations(lang);
+---
+
+<a
+  href={getRelativeLocaleUrl(lang, `concept/${slug}/`)}
+  data-name={title.toLowerCase()}
+  data-date={updated ? updated.toISOString() : ''}
+  class="aas-lift block overflow-hidden rounded-3xl border border-[var(--aas-border)] bg-[var(--aas-panel)] no-underline"
+>
+  {image && <Image src={image} alt={imageAlt ?? title} class="aspect-[16/9] w-full object-cover" />}
+  <div class="p-5">
+    {
+      (updated || version) && (
+        <p class="text-xs text-[var(--aas-muted)]">
+          {updated && <time datetime={updated.toISOString().slice(0, 10)}>{formatDate(updated, lang)}</time>}
+          {updated && version && <span> · </span>}
+          {version && <span>{t('meta.docVersion')} {version}</span>}
+        </p>
+      )
+    }
+    <h3 class="mt-1 text-lg font-semibold text-[var(--aas-text)]">{title}</h3>
+    <p
+      class="aas-md mt-2 text-sm leading-relaxed text-[var(--aas-muted)]"
+      set:html={inlineMd(description)}
+    />
+    {
+      tags.length > 0 && (
+        <div class="mt-3 flex flex-wrap gap-1.5">
+          {tags.slice(0, 4).map((tag) => (
+            <span class="rounded-full border border-[var(--aas-border)] px-2 py-0.5 text-xs text-[var(--aas-muted)]">
+              {tag}
+            </span>
+          ))}
+        </div>
+      )
+    }
+  </div>
+</a>

package/src/components/ConceptDetail.astro

@@ -0,0 +1,102 @@
+---
+import { render } from 'astro:content';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { getArticles, articleSlugOf, type ArticleEntry } from '../lib/articles';
+import { getConcepts, conceptSlugOf, conceptToolSlugs, type ConceptEntry } from '../lib/concepts';
+import { inlineMd } from '../lib/inline-md';
+import { Image } from 'astro:assets';
+import { useTranslations, type Lang } from '../i18n/ui';
+import MermaidLoader from './MermaidLoader.astro';
+import TocRail from './TocRail.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import { conceptTree, conceptCatOf } from '@aas-data/concept-categories';
+import RelatedTools from './RelatedTools.astro';
+import RelatedConcepts from './RelatedConcepts.astro';
+import RelatedArticles from './RelatedArticles.astro';
+
+interface Props {
+  entry: ConceptEntry;
+  lang: Lang;
+}
+
+const { entry, lang } = Astro.props;
+const t = useTranslations(lang);
+const { Content, headings } = await render(entry);
+const data = entry.data;
+const tocItems = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+const bodyHasMermaid = (entry.body ?? '').includes('```mermaid');
+
+// Related sections (cards), like a stack detail page: the tools this concept
+// uses (flattened from its role groups), sibling concepts, and linked writing.
+const articles = await getArticles(lang);
+const articleBySlug = new Map(articles.map((a) => [articleSlugOf(a), a]));
+const relatedArticles = data.articles
+  .map((sl) => articleBySlug.get(sl))
+  .filter(Boolean) as ArticleEntry[];
+
+const concepts = await getConcepts(lang);
+const conceptBySlug = new Map(concepts.map((c) => [conceptSlugOf(c), c]));
+const relatedConcepts = data.related
+  .map((sl) => conceptBySlug.get(sl))
+  .filter(Boolean) as ConceptEntry[];
+
+const fmtDate = (d: Date) =>
+  new Intl.DateTimeFormat(lang === 'ko' ? 'ko-KR' : 'en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC',
+  }).format(d);
+
+// Breadcrumb: All concepts › category › subcategory… (each segment linked).
+const crumbs = [
+  { label: t('concept.backToConcepts'), href: getRelativeLocaleUrl(lang, 'concept/') },
+  ...conceptTree.pathOf(conceptCatOf(data.category)).map((c) => ({
+    label: c.label[lang],
+    href: getRelativeLocaleUrl(lang, `concept/category/${c.id}/`),
+  })),
+];
+---
+
+<Breadcrumb segments={crumbs} />
+
+<header class="mt-4 pb-6">
+  <h1 class="text-3xl font-bold tracking-tight">{data.title}</h1>
+  {
+    (data.version || data.updated) && (
+      <p class="mt-1 text-sm text-[var(--aas-muted)]">
+        {data.version && <span>{t('meta.docVersion')} {data.version}</span>}
+        {data.version && data.updated && <span> · </span>}
+        {data.updated && (
+          <span>
+            {t('concept.updated')} {fmtDate(data.updated)}
+          </span>
+        )}
+      </p>
+    )
+  }
+  <p class="mt-2 aas-md text-lg whitespace-pre-line text-[var(--aas-muted)]" set:html={inlineMd(data.description)} />
+  {
+    data.image && (
+      <Image
+        src={data.image}
+        alt={data.imageAlt ?? data.title}
+        class="mt-5 aspect-[2/1] w-full rounded-2xl border border-[var(--aas-border)] object-cover"
+      />
+    )
+  }
+</header>
+
+<RelatedConcepts lang={lang} concepts={relatedConcepts} />
+
+<div class="mt-8 flex items-start gap-8">
+  <article class="prose max-w-none aas-reading min-w-0 flex-1">
+    <Content />
+  </article>
+  <TocRail lang={lang} items={tocItems} />
+</div>
+
+<RelatedTools lang={lang} slugs={conceptToolSlugs(entry)} />
+<RelatedArticles lang={lang} articles={relatedArticles} />
+
+{bodyHasMermaid && <MermaidLoader />}

package/src/components/ConceptIndex.astro

@@ -0,0 +1,143 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import ConceptCard from './ConceptCard.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import ListControls from './ListControls.astro';
+import ArrowUpRight from './ArrowUpRight.astro';
+
+const PAGE = 12;
+import { conceptTree, conceptCatOf } from '@aas-data/concept-categories';
+import { getConcepts, conceptSlugOf, type ConceptEntry } from '../lib/concepts';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+// Doubles as the concept index (no `categoryId` → all concepts, grouped by
+// category) and a category browse page (`categoryId` → that category, with a
+// breadcrumb, its direct concepts, and a section per subcategory).
+interface Props {
+  lang: Lang;
+  categoryId?: string;
+}
+
+const { lang, categoryId } = Astro.props;
+const t = useTranslations(lang);
+// Default order is most-recently-updated first (matches the ListControls
+// default), so the server render and the client sort agree — no reflow on load.
+const all = (await getConcepts(lang)).sort(
+  (a, b) =>
+    (b.data.updated?.getTime() ?? 0) - (a.data.updated?.getTime() ?? 0) ||
+    a.data.title.localeCompare(b.data.title),
+);
+const catUrl = (cid: string) => getRelativeLocaleUrl(lang, `concept/category/${cid}/`);
+
+const itemsIn = (cid: string): ConceptEntry[] => {
+  const ids = new Set(conceptTree.descendantIds(cid));
+  return all.filter((c) => ids.has(conceptCatOf(c.data.category)));
+};
+
+const node = categoryId ? conceptTree.map.get(categoryId) : undefined;
+const sections = node ? conceptTree.childrenOf(node.id) : conceptTree.roots;
+const direct = node ? all.filter((c) => conceptCatOf(c.data.category) === node.id) : [];
+
+// A leaf category page shows one flat list — that grid gets ?page= pagination.
+// Index and parent-category pages stay grouped overviews: each section is
+// capped to PAGE cards with a "see all" link to the fuller list.
+const isLeaf = !!node && sections.length === 0;
+
+const path = node ? conceptTree.pathOf(node.id) : [];
+const crumbs = node
+  ? [
+      { label: t('concept.backToConcepts'), href: getRelativeLocaleUrl(lang, 'concept/') },
+      ...path.map((c, i) => ({
+        label: c.label[lang],
+        href: i === path.length - 1 ? undefined : catUrl(c.id),
+      })),
+    ]
+  : [];
+
+const card = (c: ConceptEntry) => ({
+  lang,
+  slug: conceptSlugOf(c),
+  title: c.data.title,
+  description: c.data.description,
+  tags: c.data.tags,
+  image: c.data.image,
+  imageAlt: c.data.imageAlt,
+  version: c.data.version,
+  updated: c.data.updated,
+});
+---
+
+{
+  node ? (
+    <>
+      <Breadcrumb segments={crumbs} />
+      <header class="mt-4">
+        <h1 class="text-3xl font-bold tracking-tight">{node.label[lang]}</h1>
+        <p class="mt-2 max-w-2xl text-lg text-[var(--aas-muted)]">
+          {node.detail?.[lang] ?? node.description[lang]}
+        </p>
+      </header>
+    </>
+  ) : (
+    <section class="py-6">
+      <h1 class="text-4xl font-bold tracking-tight">{t('concept.title')}</h1>
+      <p class="mt-3 max-w-2xl text-lg text-[var(--aas-muted)]">{t('concept.tagline')}</p>
+    </section>
+  )
+}
+
+{all.length === 0 && <p class="mt-8 text-[var(--aas-muted)]">{t('concept.empty')}</p>}
+
+{all.length > 0 && <div class="mt-6"><ListControls lang={lang} /></div>}
+
+{
+  direct.length > 0 && (
+    <div
+      class="mt-4 grid gap-5 sm:grid-cols-2 lg:grid-cols-3"
+      data-sortgrid
+      data-paginate={isLeaf ? true : undefined}
+      data-page-size={isLeaf ? PAGE : undefined}
+    >
+      {direct.map((c) => (
+        <ConceptCard {...card(c)} />
+      ))}
+    </div>
+  )
+}
+
+{
+  sections.map((cat) => {
+    const items = itemsIn(cat.id);
+    return (
+      items.length > 0 && (
+        <section class="mt-8">
+          <h2 class="text-2xl font-semibold">
+            <a
+              href={catUrl(cat.id)}
+              class="text-[var(--aas-text)] no-underline hover:text-[var(--aas-accent)]"
+            >
+              {cat.label[lang]}
+              <ArrowUpRight size={20} class="ml-1 text-[var(--aas-muted)]" />
+            </a>
+          </h2>
+          <p class="mt-1 text-sm text-[var(--aas-muted)]">{cat.description[lang]}</p>
+          <div class="mt-4 grid gap-5 sm:grid-cols-2 lg:grid-cols-3" data-sortgrid>
+            {items.slice(0, PAGE).map((c) => (
+              <ConceptCard {...card(c)} />
+            ))}
+          </div>
+          {items.length > PAGE && (
+            <a
+              href={catUrl(cat.id)}
+              class="mt-3 inline-block text-sm font-medium text-[var(--aas-accent)] no-underline"
+            >
+              {t('list.seeAll').replace('{n}', String(items.length))} &rarr;
+            </a>
+          )}
+        </section>
+      )
+    );
+  })
+}
+
+{isLeaf && <nav data-pager aria-label="Pagination" class="mt-8 flex flex-wrap items-center justify-center gap-1.5" />}

package/src/components/ConceptLink.astro

@@ -0,0 +1,43 @@
+---
+// An inline, full-width callout linking to another concept, for use inside a
+// concept's MDX body, e.g.
+//   <ConceptLink slug="agent-tools" />
+// Visually distinct from the <Tools/> mini-cards: an accent-tinted bar with the
+// target concept's title + description and a → affordance. Locale is resolved
+// from the current page (concepts are served under /<lang>/...).
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { getConcepts, conceptSlugOf, type ConceptEntry } from '../lib/concepts';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { inlineMd } from '../lib/inline-md';
+
+interface Props {
+  slug: string;
+}
+
+const { slug } = Astro.props;
+const lang: Lang = Astro.currentLocale === 'ko' ? 'ko' : 'en';
+const t = useTranslations(lang);
+const concepts = await getConcepts(lang);
+const target = concepts.find((c) => conceptSlugOf(c) === slug) as ConceptEntry | undefined;
+---
+
+{
+  target && (
+    <a
+      href={getRelativeLocaleUrl(lang, `concept/${conceptSlugOf(target)}/`)}
+      class="aas-lift mt-3 flex items-center gap-4 rounded-xl border p-4 no-underline"
+      style="background: color-mix(in srgb, var(--aas-accent) 7%, var(--aas-panel)); border-color: color-mix(in srgb, var(--aas-accent) 30%, transparent);"
+    >
+      <div class="min-w-0 flex-1">
+        <span class="block text-xs font-semibold tracking-wide text-[var(--aas-accent)] uppercase">
+          {t('concept.learnMore')}
+        </span>
+        <span class="mt-0.5 block font-semibold text-[var(--aas-text)]">{target.data.title}</span>
+        <span class="aas-md mt-1 block text-sm text-[var(--aas-muted)]" set:html={inlineMd(target.data.description)} />
+      </div>
+      <span aria-hidden="true" class="shrink-0 text-xl text-[var(--aas-accent)]">
+        &rarr;
+      </span>
+    </a>
+  )
+}

package/src/components/ConceptTools.astro

@@ -0,0 +1,49 @@
+---
+// Inline tool cards for use inside a concept's MDX body, e.g.
+//   <Tools slugs={["langgraph", "crewai"]} />
+// Renders the same mini-cards as the catalog's "related tools", resolving the
+// locale from the current page (concepts are served under /<lang>/...).
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { getStacks, slugOf, type StackEntry } from '../lib/stacks';
+import { categoryMap } from '@aas-data/categories';
+import ToolAvatar from './ToolAvatar.astro';
+import type { Lang } from '../i18n/ui';
+
+interface Props {
+  slugs: string[] | string;
+}
+
+const { slugs } = Astro.props;
+const list = Array.isArray(slugs)
+  ? slugs
+  : String(slugs)
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+const lang: Lang = Astro.currentLocale === 'ko' ? 'ko' : 'en';
+const stacks = await getStacks(lang);
+const bySlug = new Map(stacks.map((s) => [slugOf(s), s]));
+const tools = list.map((s) => bySlug.get(s)).filter(Boolean) as StackEntry[];
+---
+
+{
+  tools.length > 0 && (
+    <div class="mt-3 grid gap-3 sm:grid-cols-2">
+      {tools.map((e) => (
+        <a
+          href={getRelativeLocaleUrl(lang, `stack/${slugOf(e)}/`)}
+          class="aas-lift flex items-center gap-3 rounded-xl border border-[var(--aas-border)] bg-[var(--aas-panel)] p-3 no-underline"
+        >
+          <ToolAvatar name={e.data.name} logo={e.data.logo} logoDark={e.data.logoDark} category={e.data.category} size={36} />
+          <div class="min-w-0">
+            <span class="block truncate font-semibold text-[var(--aas-text)]">{e.data.name}</span>
+            <span class="block truncate text-xs text-[var(--aas-muted)]">
+              {categoryMap.get(e.data.category)?.label[lang]}
+            </span>
+          </div>
+        </a>
+      ))}
+    </div>
+  )
+}