@terrafirmagreg-team/kit 0.0.0-stage → 1.2.0

package/src/lib/config.ts

@@ -0,0 +1,111 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type {
+  SectionKey,
+  SectionSourceEntry,
+} from '@terrafirmagreg-team/kit/types';
+
+export type SectionDump = {
+  manifest: {
+    languages?: readonly string[];
+    pack?: { version?: string | null } | null;
+  };
+  mods: readonly {
+    namespace: string;
+    books: readonly unknown[];
+    questData: string | null;
+    recipeCategories: string | null;
+    recipeIndex: string | null;
+  }[];
+};
+
+export type SectionConfigInput = {
+
+  basePath: string;
+  siteUrl: string;
+  previewRoute: string;
+  docsRoute: string;
+
+  datasetConfig: Record<
+    string,
+    {
+      accent?: string;
+      order?: number;
+
+      repo?: `${string}/${string}`;
+
+      discussions?: { repoId: string; categoryId: string };
+
+      crowdin?: string;
+
+      links?: readonly {
+        label: string;
+        url: string;
+        icon?: string;
+      }[];
+      guide?: { bookOrder?: readonly string[] };
+    }
+  >;
+  knownLanguages: readonly Lang[];
+
+  sources: Partial<Record<SectionKey, SectionSourceEntry>>;
+
+  dump?: {
+    discoverDatasets(): Promise<DatasetRef[]>;
+    loadDataset(ref: DatasetRef): Promise<SectionDump | null | undefined>;
+    hasContent: Record<string, (dump: SectionDump) => boolean>;
+  };
+};
+
+const registry = ((globalThis as Record<symbol, unknown>)[
+  Symbol.for('terrafirmagreg.config')
+] ??= new Map<string, unknown>()) as Map<string, unknown>;
+
+export function registerSectionConfig(
+  input: Partial<SectionConfigInput>,
+): void {
+  registry.set('section', {
+    ...(registry.get('section') as SectionConfigInput | undefined),
+    ...input,
+  });
+}
+
+export function sectionConfig(): SectionConfigInput {
+  const config = registry.get('section') as SectionConfigInput | undefined;
+  if (!config) {
+    throw new Error(
+      'Section config is not registered: call registerSectionConfig() at app startup.',
+    );
+  }
+  return config;
+}
+
+export type ClientDumpLoader = {
+  loadDump(dataset: DatasetRef): Promise<SectionDump | null | undefined>;
+  loadVersions(
+    datasetId: string,
+  ): Promise<{ latest?: string; versions: string[] } | null>;
+};
+
+export const {
+  register: registerClientDumpLoader,
+  get: clientDumpLoader,
+} = createConfig<ClientDumpLoader>('ClientDump');
+
+export function createConfig<T>(label: string) {
+  return {
+    register(input: T) {
+      registry.set(label, input);
+    },
+    get(): T {
+      const config = registry.get(label) as T | undefined;
+      if (!config) {
+        throw new Error(
+          `${label} config is not registered: call register${label}Config() at app startup.`,
+        );
+      }
+      return config;
+    },
+  };
+}
+

package/src/lib/dataset-links.ts

@@ -0,0 +1,31 @@
+export type DatasetLinkIcon = 'github' | 'curseforge' | 'modrinth' | 'discord';
+
+export type DatasetLink = {
+  label: string;
+  url: string;
+  icon?: DatasetLinkIcon;
+};
+
+export const datasetLink = {
+  github: (repo: `${string}/${string}`): DatasetLink => ({
+    label: 'GitHub',
+    url: `https://github.com/${repo}`,
+    icon: 'github',
+  }),
+  curseforge: (slug: string): DatasetLink => ({
+    label: 'CurseForge',
+    url: `https://www.curseforge.com/minecraft/modpacks/${slug}`,
+    icon: 'curseforge',
+  }),
+  modrinth: (slug: string): DatasetLink => ({
+    label: 'Modrinth',
+    url: `https://modrinth.com/modpack/${slug}`,
+    icon: 'modrinth',
+  }),
+  discord: (url: string): DatasetLink => ({
+    label: 'Discord',
+    url,
+    icon: 'discord',
+  }),
+};
+

package/src/lib/datasets.ts

@@ -0,0 +1,241 @@
+import 'server-only';
+import { dynamicIconImports } from 'lucide-react/dynamic';
+import { sectionConfig } from './config';
+import { sections } from './sources';
+import { datasetId } from './tree';
+import { createAsyncCache } from '@terrafirmagreg-team/data/lib/async-cache';
+import { loadLocaleRegistry, sortLangCodes } from '@terrafirmagreg-team/translate/server';
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { sectionTabs } from '@terrafirmagreg-team/sites/sections';
+import type {
+  DatasetCatalog,
+  SectionDataset,
+  SectionKey,
+} from '@terrafirmagreg-team/kit/types';
+import type { SectionDump } from './config';
+import type { IconName } from 'lucide-react/dynamic';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+const sectionMeta = new Map<
+  SectionKey,
+  Promise<Map<string, Record<string, unknown>>>
+>();
+
+function staticSectionMeta(
+  section: SectionKey,
+): Promise<Map<string, Record<string, unknown>>> {
+  let meta = sectionMeta.get(section);
+  if (meta) return meta;
+  meta = (async () => {
+    const map = new Map<string, Record<string, unknown>>();
+    const source = await sections[section]?.getSource();
+    if (source) {
+      for (const node of source.getPageTree().children) {
+        if (node.type !== 'folder') continue;
+        const id = datasetId(node);
+        const data = id
+          ? (source.getNodeMeta?.(node) as { data?: Record<string, unknown> })
+              ?.data
+          : undefined;
+        if (id && data) map.set(id, data);
+      }
+    }
+    return map;
+  })();
+  sectionMeta.set(section, meta);
+  meta.catch(() => {
+    if (sectionMeta.get(section) === meta) sectionMeta.delete(section);
+  });
+  return meta;
+}
+
+async function contentSectionDatasets(
+  section: SectionKey,
+): Promise<SectionDataset[]> {
+  const source = await sections[section]?.getSource();
+  if (!source) return [];
+  const languages = new Map<string, Set<string>>();
+  for (const page of source.getPages()) {
+    const [dataset, lang] = page.path.split('/');
+    if (!dataset || !lang) continue;
+    let set = languages.get(dataset);
+    if (!set) languages.set(dataset, (set = new Set()));
+    set.add(lang);
+  }
+  const meta = await staticSectionMeta(section);
+  return [...languages.keys()].map((id) => ({
+    id,
+    languages: datasetLanguages([...(languages.get(id) ?? [])]),
+    ...metaFields(meta.get(id) ?? {}),
+    ...datasetAppearance(id),
+  }));
+}
+
+async function datasetMeta(
+  section: SectionKey,
+  id: string,
+): Promise<Omit<SectionDataset, 'id' | 'languages'>> {
+  const meta = (await staticSectionMeta(section)).get(id);
+  return meta ? metaFields(meta) : {};
+}
+
+function metaFields(
+  meta: Record<string, unknown>,
+): Omit<SectionDataset, 'id' | 'languages'> {
+  const { title, description, icon } = meta;
+  return {
+    title: typeof title === 'string' ? title : undefined,
+    description: typeof description === 'string' ? description : undefined,
+    icon:
+      typeof icon === 'string' && icon in dynamicIconImports
+        ? (icon as IconName)
+        : undefined,
+  };
+}
+
+function datasetAppearance(id: string) {
+  return { accent: sectionConfig().datasetConfig[id]?.accent };
+}
+
+function datasetLanguages(languages: readonly string[]): Lang[] {
+  if (languages.length) return sortLangCodes(languages) as Lang[];
+  return [loadLocaleRegistry().defaultLanguage as Lang];
+}
+
+const DUMP_DATASETS_TTL = 60_000;
+
+const dumpSectionDatasets = createAsyncCache(
+  async (section: SectionKey, hasContent: (dump: SectionDump) => boolean) =>
+    dumpDatasets(section, hasContent),
+  (section) => section,
+  DUMP_DATASETS_TTL,
+);
+
+const contentSectionDatasetsCached = createAsyncCache(
+  async (section: SectionKey): Promise<SectionDataset[]> => {
+    const rows = await contentSectionDatasets(section);
+    rows.sort(datasetOrder);
+    return rows;
+  },
+  (section) => section,
+);
+
+function datasetOrder(a: SectionDataset, b: SectionDataset): number {
+  const cfg = sectionConfig().datasetConfig;
+  const order = (cfg[a.id]?.order ?? 0) - (cfg[b.id]?.order ?? 0);
+  return order !== 0 ? order : a.id.localeCompare(b.id);
+}
+
+function compareVersions(a: string, b: string): number {
+  const pa = a.split('.');
+  const pb = b.split('.');
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d =
+      (Number.parseInt(pa[i] ?? '0', 10) || 0) -
+      (Number.parseInt(pb[i] ?? '0', 10) || 0);
+    if (d) return d;
+  }
+  return a.localeCompare(b);
+}
+
+async function dumpDatasets(
+  section: SectionKey,
+  hasContent: (dump: SectionDump) => boolean,
+): Promise<SectionDataset[]> {
+  const dump = sectionConfig().dump;
+  if (!dump) return [];
+  const refs = await dump.discoverDatasets();
+  const versions = new Map<string, string[]>();
+  for (const ref of refs) {
+    const { id, version } = ref;
+    if (version) {
+      const list = versions.get(id) ?? [];
+      list.push(version);
+      versions.set(id, list);
+    }
+  }
+  const ids = refs.filter((ref) => !ref.version);
+  const usable = await Promise.all(
+    ids.map(async (ref) => {
+      const { id } = ref;
+      const index = await dump.loadDataset(ref);
+      if (!index || !hasContent(index)) return null;
+      return {
+        id,
+        languages: datasetLanguages(index.manifest.languages ?? []),
+      };
+    }),
+  );
+  return (
+    await Promise.all(
+      usable
+        .filter((row): row is { id: string; languages: Lang[] } => row !== null)
+        .map(async ({ id, languages }) => ({
+          id,
+          languages,
+          ...(versions.get(id)?.length
+            ? { versions: versions.get(id)!.sort(compareVersions).reverse() }
+            : {}),
+          ...(await datasetMeta(section, id).then((meta) =>
+            Object.values(meta).some((value) => value !== undefined)
+              ? meta
+              : datasetMeta('docs', id),
+          )),
+          ...datasetAppearance(id),
+        })),
+      )
+  ).sort(datasetOrder);
+}
+
+export function sectionDatasets(
+  section: SectionKey,
+): Promise<SectionDataset[]> {
+  const hasContent = sectionConfig().dump?.hasContent[section];
+  return hasContent
+    ? dumpSectionDatasets(section, hasContent)
+    : contentSectionDatasetsCached(section);
+}
+
+export async function defaultDataset(
+  section: SectionKey,
+): Promise<string | undefined> {
+  return (await sectionDatasets(section))[0]?.id;
+}
+
+export function findDataset(
+  datasets: readonly SectionDataset[],
+  ref: DatasetRef,
+): SectionDataset | undefined {
+  const { id, version } = ref;
+  const meta = datasets.find((row) => row.id === id);
+  if (!meta) return undefined;
+  if (version && !meta.versions?.includes(version)) return undefined;
+  return meta;
+}
+
+export async function resolveDatasetMeta(
+  section: SectionKey,
+  ref: DatasetRef,
+): Promise<SectionDataset | undefined> {
+  return findDataset(await sectionDatasets(section), ref);
+}
+
+export async function datasetSlugs(section: SectionKey): Promise<string[]> {
+  return (await sectionDatasets(section)).map(({ id }) => id);
+}
+
+const datasetCatalogCached = createAsyncCache(
+  async (): Promise<DatasetCatalog> =>
+    Promise.all(
+      sectionTabs.map(
+        async ({ key }) => [key, await sectionDatasets(key)] as const,
+      ),
+    ).then((rows) => Object.fromEntries(rows) as DatasetCatalog),
+  () => 'catalog',
+  DUMP_DATASETS_TTL,
+);
+
+export function datasetCatalog(): Promise<DatasetCatalog> {
+  return datasetCatalogCached();
+}
+

package/src/lib/landing.ts

@@ -0,0 +1,48 @@
+import 'server-only';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { datasetSlugs, findDataset } from './datasets';
+import type {
+  DatasetLanding,
+  SectionDataset,
+  SectionKey,
+} from '@terrafirmagreg-team/kit/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export function getDatasetLanding(
+  section: SectionKey,
+  slug: string[] | undefined,
+  lang: Lang,
+  datasets: readonly SectionDataset[],
+): DatasetLanding | undefined {
+  if (!slug || slug.length !== 1) return undefined;
+  const [ref] = slug;
+  const meta = findDataset(datasets, { id: ref });
+  if (!meta) return undefined;
+  const { messages, defaultLanguage } = loadLocaleRegistry();
+  const table = messages[lang] ?? messages[defaultLanguage] ?? {};
+  return {
+    title: table[`sections.${section}`] ?? section,
+    description: table[`sections.desc.${section}`],
+    dataset: { id: ref },
+    datasetTitle: meta.title ?? meta.id,
+    lang,
+    ...(meta.versions ? { versions: meta.versions } : {}),
+  };
+}
+
+export function resolveDatasetLanding(
+  section: SectionKey,
+  slug: string[] | undefined,
+  lang: Lang,
+  datasets: readonly SectionDataset[],
+): { page: DatasetLanding; isFallback: boolean } | undefined {
+  const page = getDatasetLanding(section, slug, lang, datasets);
+  return page ? { page, isFallback: false } : undefined;
+}
+
+export async function generateDatasetLandingParams(
+  section: SectionKey,
+): Promise<{ slug: string[] }[]> {
+  return (await datasetSlugs(section)).map((ref) => ({ slug: [ref] }));
+}
+

package/src/lib/layout.ts

@@ -0,0 +1,16 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { uiConfig } from '@terrafirmagreg-team/ui/lib/config';
+import { NavTitle } from '@terrafirmagreg-team/kit/components/blocks/nav-title';
+
+export interface BaseLayoutProps {
+  nav?: { title?: string };
+  slots?: { navTitle?: (props: ComponentProps<'a'>) => ReactNode };
+}
+
+export function baseOptions(): BaseLayoutProps {
+  return {
+    nav: { title: uiConfig().brand?.name },
+    slots: { navTitle: NavTitle },
+  };
+}
+

package/src/lib/locale/renderer.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export type LocaleScope = { section: string; slug?: string[] };
+
+export type LocaleResolve = (
+  slug: string[] | undefined,
+  lang: Lang,
+) => Promise<{ page: unknown; isFallback: boolean } | undefined>;
+
+export type LocaleRender = (
+  page: unknown,
+  slug: string[] | undefined,
+  lang: Lang,
+) => ReactNode | Promise<ReactNode>;
+
+export type LocaleLoadResult = { node: ReactNode; missing: boolean } | null;
+
+export type LocaleLoader = (
+  scope: LocaleScope,
+  lang: Lang,
+) => Promise<LocaleLoadResult>;
+
+const renderers = new Map<
+  string,
+  { resolve: LocaleResolve; render: LocaleRender }
+>();
+
+export function registerLocaleRenderer(
+  section: string,
+  entry: { resolve: LocaleResolve; render: LocaleRender },
+): void {
+  renderers.set(section, entry);
+}
+
+export function localeRenderer(section: string) {
+  return renderers.get(section);
+}
+
+let loader: LocaleLoader | undefined;
+
+export function registerLocaleLoader(next: LocaleLoader): void {
+  loader = next;
+}
+
+export function localeLoader(): LocaleLoader | undefined {
+  return loader;
+}
+

package/src/lib/order.ts

@@ -0,0 +1,89 @@
+import type {
+  LoaderPlugin,
+  PageTreeBuilderContext,
+} from 'fumadocs-core/source';
+import type { Folder, Item, Node } from 'fumadocs-core/page-tree';
+
+type Storage = PageTreeBuilderContext['storage'];
+type NodeLike = Item | Folder;
+
+type PageFrontmatter = {
+  order?: number;
+  unlisted?: boolean;
+  defaultOpen?: boolean;
+  collapsible?: boolean;
+  link?: boolean;
+};
+
+function frontmatter(
+  storage: Storage,
+  filePath?: string,
+): PageFrontmatter | undefined {
+  if (!filePath) return undefined;
+  const file = storage.read(filePath);
+  return file?.format === 'page' ? (file.data as PageFrontmatter) : undefined;
+}
+
+function orderOf(storage: Storage, node: NodeLike): number {
+  const ref =
+    node.type === 'page'
+      ? node.$ref
+      : (node.index?.$ref ??
+        (node as Folder & { $indexRef?: string }).$indexRef);
+  const data = frontmatter(storage, ref);
+  return typeof data?.order === 'number' ? data.order : Number.MAX_SAFE_INTEGER;
+}
+
+function isUnlisted(storage: Storage, node: NodeLike): boolean {
+  const data = frontmatter(
+    storage,
+    node.type === 'page' ? node.$ref : node.index?.$ref,
+  );
+  return data?.unlisted === true;
+}
+
+function hasExplicitOrder(storage: Storage, metaPath?: string): boolean {
+  if (!metaPath) return false;
+  const file = storage.read(metaPath);
+  return (
+    file?.format === 'meta' &&
+    Array.isArray((file.data as { pages?: unknown }).pages)
+  );
+}
+
+function arrange(storage: Storage, children: Node[], metaPath?: string): Node[] {
+  const kept = children.filter(
+    (child) => child.type === 'separator' || !isUnlisted(storage, child),
+  );
+  if (hasExplicitOrder(storage, metaPath)) return kept;
+  return [...kept].sort(
+    (a, b) => orderOf(storage, a as NodeLike) - orderOf(storage, b as NodeLike),
+  );
+}
+
+export function orderPlugin(): LoaderPlugin {
+  return {
+    name: 'wiki:order',
+    transformPageTree: {
+      folder(node, _folderPath, metaPath) {
+        const indexRef = node.index?.$ref;
+        const index = frontmatter(this.storage, indexRef);
+        const next: Folder = {
+          ...node,
+          defaultOpen: index?.defaultOpen ?? node.defaultOpen,
+          collapsible: index?.collapsible ?? node.collapsible,
+          children: arrange(this.storage, node.children, metaPath),
+        };
+        if (index?.link === false && indexRef) {
+          delete next.index;
+          (next as Folder & { $indexRef?: string }).$indexRef = indexRef;
+        }
+        return next;
+      },
+      root(node) {
+        return { ...node, children: arrange(this.storage, node.children) };
+      },
+    },
+  };
+}
+

package/src/lib/page.ts

@@ -0,0 +1,109 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { createGetUrl } from 'fumadocs-core/source';
+import { firstLocalizedPage } from '@terrafirmagreg-team/translate/server';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { stripLangFromUrl, toInternalSlugs, toPublicSlug } from '@terrafirmagreg-team/translate/lib/slug';
+import { sectionConfig } from './config';
+import { sectionDatasets } from './datasets';
+import type { SectionKey, SectionPage, SectionSource } from '@terrafirmagreg-team/kit/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export type { SectionSource } from '@terrafirmagreg-team/kit/types';
+
+const canonicalUrl = (pathname: string): string =>
+  new URL(
+    pathname.startsWith('/') ? pathname : `/${pathname}`,
+    sectionConfig().siteUrl,
+  ).toString();
+
+let imageUrl: ReturnType<typeof createGetUrl> | undefined;
+const getImageUrl = () =>
+  (imageUrl ??= createGetUrl(sectionConfig().previewRoute));
+
+function getDatasetImageUrl(section: string, dataset: string) {
+  const segments = [section, dataset, 'image.png'];
+  return { segments, url: getImageUrl()(segments) };
+}
+
+export function getPage<S extends SectionSource>(
+  source: S,
+  slug: string[] | undefined,
+  lang: Lang,
+): ReturnType<S['getPage']> {
+  return source.getPage(toInternalSlugs(slug, lang)) as ReturnType<S['getPage']>;
+}
+
+export function resolvePage<S extends SectionSource>(
+  source: S,
+  slug: string[] | undefined,
+  lang: Lang,
+) {
+  const { defaultLanguage } = loadLocaleRegistry();
+  const exact = getPage(source, slug, lang);
+  if (exact) return { page: exact, isFallback: false as const };
+  if (lang === defaultLanguage) return undefined;
+  const fallback = getPage(source, slug, defaultLanguage);
+  if (!fallback) return undefined;
+  return { page: fallback, isFallback: true as const };
+}
+
+export async function generateDatasetParams(
+  section: SectionKey,
+  source: SectionSource,
+): Promise<{ slug: string[] }[]> {
+  const params = generatePageParams(source);
+  const seen = new Set(params.map((row) => row.slug.join('/')));
+  for (const { id } of await sectionDatasets(section)) {
+    if (!seen.has(id)) {
+      seen.add(id);
+      params.push({ slug: [id] });
+    }
+  }
+  return params.length ? params : [{ slug: ['_'] }];
+}
+
+export function generatePageParams(source: SectionSource): { slug: string[] }[] {
+  const languages = [...sectionConfig().knownLanguages];
+  const seen = new Set<string>();
+  const params: { slug: string[] }[] = [];
+  for (const page of source.getPages()) {
+    const slug = toPublicSlug(page.slugs, languages);
+    const key = slug.join('/');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    params.push({ slug });
+  }
+  return params;
+}
+
+export async function sectionMetadata(
+  section: SectionKey,
+  source: SectionSource,
+  slug: string[] | undefined,
+): Promise<Metadata> {
+  const page = firstLocalizedPage(slug, (s, l) => getPage(source, s, l));
+  if (!page) notFound();
+  const doc = page as SectionPage;
+  const languages = sectionConfig().knownLanguages;
+
+  const url = canonicalUrl(stripLangFromUrl(doc.url, [...languages]));
+  return {
+    title: doc.data.title,
+    description: doc.data.description,
+    alternates: { canonical: url },
+    openGraph: {
+      type: 'article',
+      url,
+      title: doc.data.title,
+      description: doc.data.description,
+      images: getDatasetImageUrl(section, doc.slugs[0]).url,
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: doc.data.title,
+      description: doc.data.description,
+    },
+  };
+}
+