@terrafirmagreg-team/changelog 0.1.0 → 1.2.1

package/package.json

@@ -1,23 +1,40 @@
 {
   "name": "@terrafirmagreg-team/changelog",
-  "version": "0.1.0",
+  "version": "1.2.1",
   "type": "module",
+  "description": "Changelog section",
+  "license": "LGPL-3.0-only",
   "exports": {
+    "./components/*": [
+      "./src/components/*.tsx",
+      "./src/components/*/index.tsx",
+      "./src/components/*/index.ts"
+    ],
     "./lib/*": [
       "./src/lib/*.ts",
-      "./src/lib/*.tsx",
-      "./src/lib/*/index.ts",
-      "./src/lib/*/index.tsx"
+      "./src/lib/*/index.ts"
     ],
+    "./types/*": "./src/types/*.ts",
+    "./types": "./src/types/index.ts",
     "./locales": "./src/locales.ts"
   },
   "dependencies": {
+    "@terrafirmagreg-team/kit": "1.2.1",
+    "@terrafirmagreg-team/mdx": "1.2.1",
+    "@terrafirmagreg-team/translate": "1.2.1",
+    "@terrafirmagreg-team/ui": "1.2.1",
     "fumadocs-core": "16.17.8",
-    "@terrafirmagreg-team/kit": "0.1.0",
-    "@terrafirmagreg-team/translate": "0.1.0"
+    "lucide-react": "^0.577.0"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
   },
   "devDependencies": {
-    "@types/node": "^26.6.5"
+    "@types/mdx": "^2.0.14",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0"
   },
   "repository": {
     "type": "git",
@@ -28,9 +45,6 @@
     "access": "public"
   },
   "files": [
-    "src",
-    "styles",
-    "styles.css",
-    "locales"
+    "src"
   ]
 }

package/src/components/entries.tsx

@@ -0,0 +1,75 @@
+import { createRelativeLink } from '@terrafirmagreg-team/kit/components/relative-link';
+import { getMDXComponents } from '@terrafirmagreg-team/mdx/components/mdx-components';
+import { datasetCatalog } from '@terrafirmagreg-team/kit/lib/datasets';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { lookupPagePreview } from '@terrafirmagreg-team/kit/lib/preview/lookup';
+import { LinkPreview } from '@terrafirmagreg-team/ui/components/blocks/link/link-preview';
+import type { SectionSource } from '@terrafirmagreg-team/kit/lib/page';
+import type { SectionPage } from '@terrafirmagreg-team/kit/types';
+import type { LoaderConfig, LoaderOutput, Page } from 'fumadocs-core/source';
+import type { MDXContent } from 'mdx/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { ChangelogTimelineEntry } from './timeline';
+
+export async function timelineEntries(
+  source: SectionSource,
+  route: string,
+  dataset: string,
+  lang: Lang,
+  repo?: `${string}/${string}`,
+): Promise<ChangelogTimelineEntry[]> {
+  const catalog = await datasetCatalog();
+  const { defaultLanguage } = loadLocaleRegistry();
+  const byFile = new Map<string, { own?: SectionPage; fallback?: SectionPage }>();
+  for (const raw of source.getPages()) {
+    const page = raw as unknown as SectionPage;
+    if (page.slugs[0] !== dataset) continue;
+    const pageLang = (page.locale ?? page.slugs[1]) as Lang;
+    const key = page.slugs.slice(2).join('/');
+    const slot = byFile.get(key) ?? {};
+    if (pageLang === lang) slot.own = page;
+    else if (pageLang === defaultLanguage) slot.fallback = page;
+    byFile.set(key, slot);
+  }
+  const entries: ChangelogTimelineEntry[] = [];
+  for (const { own, fallback } of byFile.values()) {
+    const page = own ?? fallback;
+    if (!page) continue;
+    const pageLang = (page.locale ?? page.slugs[1] ?? lang) as Lang;
+    const data = page.data as {
+      date?: string | Date;
+      frontmatter?: { date?: string | Date };
+    };
+    const rawDate = data.date ?? data.frontmatter?.date;
+    if (!rawDate) continue;
+    const { body: MDX } = (await (
+      page.data as unknown as {
+        load(): Promise<{ body: MDXContent }>;
+      }
+    ).load()) as { body: MDXContent };
+    const link = createRelativeLink(
+      source as LoaderOutput<LoaderConfig>,
+      page as unknown as Page,
+      (props) => (
+        <LinkPreview
+          preview={lookupPagePreview(catalog, props.href, pageLang)}
+          {...props}
+        />
+      ),
+    );
+    const body = <MDX components={getMDXComponents({ a: link })} />;
+    const fileSlug = page.slugs.slice(2);
+    entries.push({
+      id: fileSlug.join('/'),
+      title: page.data.title,
+      date: new Date(rawDate),
+      url: `${route}/${dataset}/${fileSlug.join('/')}`,
+      releaseUrl: repo
+        ? `https://github.com/${repo}/releases/tag/${page.data.title}`
+        : undefined,
+      untranslated: !own,
+      body,
+    });
+  }
+  return entries;
+}

package/src/components/month-label.tsx

@@ -0,0 +1,9 @@
+'use client';
+import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { monthLabel } from '@terrafirmagreg-team/changelog/lib/format';
+
+export function ChangelogMonthLabel({ monthKey }: { monthKey: string }) {
+  const lang = useResolvedLang();
+  const [year, month] = monthKey.split('-').map(Number);
+  return <>{monthLabel(lang, new Date(Date.UTC(year, month - 1)))}</>;
+}

package/src/components/now-bar.tsx

@@ -0,0 +1,95 @@
+'use client';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { UntranslatedChip } from '@terrafirmagreg-team/ui/components/blocks/lang/untranslated-chip';
+import {
+  FloatBar,
+  FloatBarItem,
+} from '@terrafirmagreg-team/ui/components/blocks/viewer/float-bar';
+
+export type ChangelogNowItem = {
+  id: string;
+  untranslated?: boolean;
+};
+
+export function ChangelogNow({ items }: { items: ChangelogNowItem[] }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [activeId, setActiveId] = useState(items[0]?.id ?? null);
+
+  useEffect(() => {
+    const bar = ref.current;
+    const root = bar?.closest('[data-changelog-timeline]');
+    if (!bar || !root) return;
+
+    let tops: { id: string; top: number }[] = [];
+    const measure = () => {
+      const base = root.getBoundingClientRect().top;
+      tops = [...root.querySelectorAll<HTMLElement>('[data-release]')].map(
+        (li) => ({
+          id: li.id,
+          top: li.getBoundingClientRect().top - base,
+        }),
+      );
+    };
+
+    let raf = 0;
+    const update = () => {
+      raf = 0;
+      const y =
+        bar.getBoundingClientRect().top - root.getBoundingClientRect().top;
+      let active = tops[0]?.id ?? null;
+      for (const { id, top } of tops) {
+        if (top <= y) active = id;
+        else break;
+      }
+      setActiveId((prev) => (prev === active ? prev : active));
+    };
+    const schedule = () => {
+      if (!raf) raf = requestAnimationFrame(update);
+    };
+    const remeasure = () => {
+      measure();
+      schedule();
+    };
+    measure();
+    update();
+    document.addEventListener('scroll', schedule, {
+      capture: true,
+      passive: true,
+    });
+    window.addEventListener('resize', remeasure);
+    const observer = new ResizeObserver(remeasure);
+    observer.observe(root);
+    return () => {
+      document.removeEventListener('scroll', schedule, { capture: true });
+      window.removeEventListener('resize', remeasure);
+      observer.disconnect();
+      cancelAnimationFrame(raf);
+    };
+  }, []);
+
+  const current = useMemo(
+    () => items.find((entry) => entry.id === activeId) ?? null,
+    [items, activeId],
+  );
+
+  return (
+    <div
+      ref={ref}
+      className="not-prose pointer-events-none sticky top-[calc(var(--header-height,0px)+0.75rem)] z-10 h-0"
+    >
+      {current && (
+        <div className="absolute start-[7px] flex -translate-y-1/2 items-center gap-2">
+          <span className="size-3 shrink-0 rounded-full border-2 border-primary bg-background" />
+          <FloatBar className="pointer-events-auto">
+            <FloatBarItem className="gap-1.5">
+              <span className="font-semibold">{current.id}</span>
+              <span className={current.untranslated ? undefined : 'hidden'}>
+                <UntranslatedChip />
+              </span>
+            </FloatBarItem>
+          </FloatBar>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/timeline.tsx

@@ -0,0 +1,155 @@
+import Link from 'next/link';
+import { ExternalLink, Link as LinkIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+import { dayFormat, monthLabel } from '@terrafirmagreg-team/changelog/lib/format';
+import { ChangelogNow } from './now-bar';
+
+export interface ChangelogTimelineEntry {
+  id: string;
+  title: string;
+  date: Date;
+  url?: string;
+  releaseUrl?: string;
+  untranslated?: boolean;
+  body: ReactNode;
+}
+
+export type ChangelogMonth = {
+  key: string;
+  label: string;
+  items: ChangelogTimelineEntry[];
+};
+
+export function groupByMonth(
+  entries: ChangelogTimelineEntry[],
+  lang = 'en_us',
+): ChangelogMonth[] {
+  const months = new Map<string, ChangelogMonth>();
+  for (const entry of [...entries].sort(
+    (a, b) => b.date.getTime() - a.date.getTime(),
+  )) {
+    const key = `${entry.date.getUTCFullYear()}-${String(entry.date.getUTCMonth() + 1).padStart(2, '0')}`;
+    const month = months.get(key);
+    if (month) month.items.push(entry);
+    else
+      months.set(key, {
+        key,
+        label: monthLabel(lang, entry.date),
+        items: [entry],
+      });
+  }
+  return [...months.values()];
+}
+
+export const monthAnchor = (monthKey: string) => monthKey;
+
+export function ChangelogTimeline({
+  entries,
+  lang = 'en_us',
+}: {
+  entries: ChangelogTimelineEntry[];
+  lang?: string;
+}) {
+  const day = dayFormat(lang);
+  const latestId = entries.length
+    ? entries.reduce((a, b) => (b.date > a.date ? b : a)).id
+    : undefined;
+  const months = groupByMonth(entries, lang);
+  return (
+    <div data-changelog-timeline>
+      <ChangelogNow
+        items={months.flatMap((month) =>
+          month.items.map((entry) => ({
+            id: entry.id,
+            untranslated: entry.untranslated,
+          })),
+        )}
+      />
+      {months.map(({ key, label, items }) => (
+        <section
+          key={key}
+          className="ms-3 border-s-2 border-muted-foreground/25 ps-6 pb-8"
+        >
+          <h2
+            id={monthAnchor(key)}
+            className="not-prose scroll-mt-28 py-2 text-[11px] font-semibold tracking-[0.05em] text-muted-foreground/60"
+          >
+            {label}
+          </h2>
+          <ol className="mt-4 mb-0 list-none ps-0">
+            {items.map((entry) => (
+              <ChangelogItem
+                key={entry.id}
+                entry={entry}
+                day={day}
+                latest={entry.id === latestId}
+              />
+            ))}
+          </ol>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+function ChangelogItem({
+  entry,
+  day,
+  latest,
+}: {
+  entry: ChangelogTimelineEntry;
+  day: Intl.DateTimeFormat;
+  latest?: boolean;
+}) {
+  return (
+    <li
+      id={entry.id}
+      data-release
+      className="group scroll-mt-28 ps-0 pb-12 last:pb-0"
+    >
+      <time
+        dateTime={entry.date.toISOString()}
+        className="relative mb-1.5 block text-xs font-medium text-muted-foreground tabular-nums"
+      >
+        <span className="absolute -start-[25px] top-1/2 size-2.5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-primary bg-background rtl:translate-x-1/2" />
+        {day.format(entry.date)}
+      </time>
+      <h3 className="not-prose mb-3 flex items-center gap-2 text-lg font-semibold tracking-tight">
+        {latest && (
+          <span className="rounded-md bg-primary/10 px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-primary">
+            Latest
+          </span>
+        )}
+        {entry.url ? (
+          <Link
+            href={entry.url}
+            className="underline-offset-4 hover:text-primary hover:underline"
+          >
+            {entry.title}
+          </Link>
+        ) : (
+          entry.title
+        )}
+        {entry.releaseUrl && (
+          <a
+            href={entry.releaseUrl}
+            target="_blank"
+            rel="noreferrer"
+            aria-label="GitHub release"
+            className="text-muted-foreground hover:text-primary"
+          >
+            <ExternalLink className="size-3.5" />
+          </a>
+        )}
+        <a
+          href={`#${entry.id}`}
+          aria-label="Link to this release"
+          className="text-muted-foreground opacity-0 transition-opacity hover:text-primary group-hover:opacity-100"
+        >
+          <LinkIcon className="size-3.5" />
+        </a>
+      </h3>
+      <div className="text-sm text-muted-foreground">{entry.body}</div>
+    </li>
+  );
+}

package/src/components/views/timeline.tsx

@@ -0,0 +1,25 @@
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { SectionSource } from '@terrafirmagreg-team/kit/lib/page';
+import { timelineEntries } from '../entries';
+import { ChangelogTimeline } from '../timeline';
+
+export async function ChangelogTimelineView({
+  source,
+  route,
+  dataset,
+  lang,
+  repo,
+}: {
+  source: SectionSource;
+  route: string;
+  dataset: string;
+  lang: Lang;
+  repo?: `${string}/${string}`;
+}) {
+  return (
+    <ChangelogTimeline
+      entries={await timelineEntries(source, route, dataset, lang, repo)}
+      lang={lang}
+    />
+  );
+}

package/src/lib/format.ts

@@ -0,0 +1,20 @@
+export const bcp47 = (lang: string) => lang.replace('_', '-');
+
+const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
+
+export const monthFormat = (lang: string) =>
+  new Intl.DateTimeFormat(bcp47(lang), {
+    month: 'long',
+    year: 'numeric',
+    timeZone: 'UTC',
+  });
+
+export const monthLabel = (lang: string, date: Date) =>
+  capitalize(monthFormat(lang).format(date));
+
+export const dayFormat = (lang: string) =>
+  new Intl.DateTimeFormat(bcp47(lang), {
+    month: 'short',
+    day: 'numeric',
+    timeZone: 'UTC',
+  });

package/src/lib/remark.ts

@@ -0,0 +1,38 @@
+type MdNode = {
+  type: string;
+  depth?: number;
+  children?: { type?: string; value?: string; children?: unknown[] }[];
+};
+
+const STRIP_HEADING = /^(what'?s changed|new contributors)$/i;
+const FULL_CHANGELOG = /^\*?\*?full changelog\*?\*?/i;
+
+const text = (node: MdNode): string =>
+  (node.children ?? [])
+    .map((child) => child.value ?? text(child as MdNode))
+    .join('')
+    .trim();
+
+export const remarkStripAutoSections =
+  () =>
+  (tree: { children: MdNode[] }) => {
+    const out: MdNode[] = [];
+    let skipDepth = 0;
+    for (const node of tree.children) {
+      if (node.type === 'heading') {
+        const depth = node.depth ?? 2;
+        if (STRIP_HEADING.test(text(node))) {
+          skipDepth = depth;
+          continue;
+        }
+        if (skipDepth && depth <= skipDepth) skipDepth = 0;
+        if (skipDepth) continue;
+      } else if (skipDepth) {
+        continue;
+      }
+      if (node.type === 'paragraph' && FULL_CHANGELOG.test(text(node)))
+        continue;
+      out.push(node);
+    }
+    tree.children = out;
+  };

package/src/lib/trees.ts

@@ -0,0 +1,83 @@
+import type * as PageTree from 'fumadocs-core/page-tree';
+import type { SectionTrees } from '@terrafirmagreg-team/kit/types';
+
+const GROUP_NAME = /^(\d+)\.(\d+)\.x$/;
+
+const numbers = (value: string) => value.match(/\d+/g)?.map(Number) ?? [];
+
+const descByVersion = (a: PageTree.Node, b: PageTree.Node) => {
+  const an = numbers(String(a.name ?? ''));
+  const bn = numbers(String(b.name ?? ''));
+  for (let i = 0; i < Math.max(an.length, bn.length); i++) {
+    const diff = (bn[i] ?? 0) - (an[i] ?? 0);
+    if (diff) return diff;
+  }
+  return 0;
+};
+
+function groupVersionItems(root: PageTree.Root): PageTree.Root {
+  const children: PageTree.Node[] = [];
+  const groups = new Map<string, PageTree.Folder>();
+  for (const node of root.children) {
+    const title = node.type === 'page' ? String(node.name ?? '') : '';
+    const series = /^v?(\d+)\.(\d+)/.exec(title)?.slice(1, 3).join('.');
+    if (node.type !== 'page' || !series) {
+      children.push(node);
+      continue;
+    }
+    let folder = groups.get(series);
+    if (!folder) {
+      folder = {
+        $id: `${root.$id ?? 'root'}:${series}`,
+        type: 'folder',
+        name: `${series}.x`,
+        children: [],
+      };
+      groups.set(series, folder);
+      children.push(folder);
+    }
+    folder.children.push(node);
+  }
+  for (const folder of groups.values())
+    folder.children.sort(descByVersion);
+  const seriesOf = (node: PageTree.Node) =>
+    node.type === 'folder' && typeof node.name === 'string'
+      ? GROUP_NAME.exec(node.name)
+      : null;
+  children.sort((a, b) => {
+    const sa = seriesOf(a);
+    const sb = seriesOf(b);
+    return sa && sb
+      ? Number(sb[1]) - Number(sa[1]) || Number(sb[2]) - Number(sa[2])
+      : 0;
+  });
+  return { ...root, children };
+}
+
+const TIMELINE_NAMES: Record<string, string> = {
+  en_us: 'Timeline',
+  ru_ru: 'Таймлайн',
+};
+
+export const groupTrees =
+  (route: string, names: Record<string, string> = TIMELINE_NAMES) =>
+  (trees: SectionTrees): SectionTrees =>
+    Object.fromEntries(
+      Object.entries(trees).map(([lang, byDataset]) => [
+        lang,
+        Object.fromEntries(
+          Object.entries(byDataset).map(([id, root]) => {
+            const grouped = groupVersionItems(root);
+            const timeline: PageTree.Item = {
+              type: 'page',
+              name: names[lang] ?? 'Timeline',
+              url: `${route}/${id}`,
+            };
+            return [
+              id,
+              { ...grouped, children: [timeline, ...grouped.children] },
+            ];
+          }),
+        ),
+      ]),
+    );

package/src/locales/en_us.json

@@ -1,8 +1,4 @@
 {
-  "sections": {
-    "changelog": "Changelog",
-    "desc": {
-      "changelog": "Release history and version notes"
-    }
-  }
+  "Changelog(sections.changelog)": "Changelog",
+  "Release history and version notes(sections.desc.changelog)": "Release history and version notes"
 }

package/src/locales/ru_ru.json

@@ -1,8 +1,4 @@
 {
-  "sections": {
-    "changelog": "Список изменений",
-    "desc": {
-      "changelog": "История релизов и заметки к версиям"
-    }
-  }
+  "Changelog(sections.changelog)": "Список изменений",
+  "Release history and version notes(sections.desc.changelog)": "История релизов и заметки к версиям"
 }

package/src/locales.ts

@@ -3,3 +3,4 @@ import { createLocaleCatalog } from '@terrafirmagreg-team/translate/lib/locales'
 export const locales = createLocaleCatalog(
   import.meta.glob('./locales/*.json', { eager: true, import: 'default' }),
 );
+

package/src/lib/route.ts

@@ -1,2 +0,0 @@
-
-export const changelogRoute = '/changelog';

package/src/lib/tree.ts

@@ -1,41 +0,0 @@
-import type * as PageTree from 'fumadocs-core/page-tree';
-import type { SectionTrees } from '@terrafirmagreg-team/kit/types';
-
-function groupVersionItems(root: PageTree.Root): PageTree.Root {
-  const children: PageTree.Node[] = [];
-  const groups = new Map<string, PageTree.Folder>();
-  for (const node of root.children) {
-    const title = node.type === 'page' ? String(node.name ?? '') : '';
-    const series = /^v?(\d+)\.(\d+)/.exec(title)?.slice(1, 3).join('.');
-    if (node.type !== 'page' || !series) {
-      children.push(node);
-      continue;
-    }
-    let folder = groups.get(series);
-    if (!folder) {
-      folder = {
-        $id: `${root.$id ?? 'root'}:${series}`,
-        type: 'folder',
-        name: `${series}.x`,
-        children: [],
-      };
-      groups.set(series, folder);
-      children.push(folder);
-    }
-    folder.children.push(node);
-  }
-  return { ...root, children };
-}
-
-export const groupTrees = (trees: SectionTrees): SectionTrees =>
-  Object.fromEntries(
-    Object.entries(trees).map(([lang, byDataset]) => [
-      lang,
-      Object.fromEntries(
-        Object.entries(byDataset).map(([id, root]) => [
-          id,
-          groupVersionItems(root),
-        ]),
-      ),
-    ]),
-  );