@terrafirmagreg-team/kit 0.0.0-stage → 0.1.0

package/src/hooks/use-nav-options.ts

@@ -0,0 +1,84 @@
+'use client';
+import { type ReactNode, createElement, useMemo } from 'react';
+import { DynamicIcon, type IconName } from 'lucide-react/dynamic';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
+import {
+  datasetRef,
+  isDumpSection,
+  parseDatasetRef,
+  sectionUrl,
+} from '@terrafirmagreg-team/kit/lib/location';
+import { useCurrentDataset } from '@terrafirmagreg-team/kit/hooks/use-current-dataset';
+import { useVersionPreference } from '@terrafirmagreg-team/kit/hooks/use-version-pref';
+import type { LeftSidebarScope } from '@terrafirmagreg-team/kit/types';
+import type {
+  SwitcherOption,
+  SwitcherProps,
+} from '@terrafirmagreg-team/ui/types/nav';
+
+function datasetIcon(dataset: { icon?: IconName }): ReactNode {
+  if (!dataset.icon) return undefined;
+  return createElement(DynamicIcon, {
+    name: dataset.icon,
+    className: 'size-4 shrink-0',
+  });
+}
+
+export function useNavOptions({ section, catalog }: LeftSidebarScope): {
+  section: SwitcherProps;
+  dataset: SwitcherProps;
+} {
+  const t = useTranslations();
+  const current = useCurrentDataset(catalog[section]);
+  const baseId = current ? parseDatasetRef(current).id : undefined;
+  const pinned = current ? parseDatasetRef(current).version : undefined;
+  const preferred = useVersionPreference(baseId);
+  const version = pinned ?? preferred;
+
+  const sectionOptions: SwitcherOption[] = useMemo(
+    () =>
+      sectionConfig().sectionTabs.map(({ key, icon: Icon }) => {
+        const meta = baseId
+          ? catalog[key].find(({ id }) => id === baseId)
+          : undefined;
+        const pinnedRef =
+          isDumpSection(key) && version && meta?.versions?.includes(version)
+            ? datasetRef(baseId!, version)
+            : baseId;
+        return {
+          value: key,
+          title: t(`sections.${key}`),
+          description: t(`sections.desc.${key}`),
+          icon: Icon ? createElement(Icon) : undefined,
+          url: meta ? sectionUrl(key, pinnedRef) : sectionUrl(key),
+        };
+      }),
+    [t, baseId, version, catalog],
+  );
+
+  const datasetOptions: SwitcherOption[] = useMemo(
+    () =>
+      catalog[section].map((datasetItem) => ({
+        value: datasetItem.id,
+        title: datasetItem.title ?? datasetItem.id,
+        description: datasetItem.description,
+        icon: datasetIcon(datasetItem),
+        url: sectionUrl(section, datasetItem.id),
+      })),
+    [section, catalog],
+  );
+
+  return {
+    section: {
+      options: sectionOptions,
+      selected: section,
+      placeholder: t('ui.select_section'),
+    },
+    dataset: {
+      options: datasetOptions,
+      selected: baseId,
+      placeholder: t('ui.select_dataset'),
+    },
+  };
+}

package/src/hooks/use-version-pref.ts

@@ -0,0 +1,30 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import {
+  jsonCodec,
+  readStoredValue,
+  subscribeStoredValue,
+  writeStoredValue,
+} from '@terrafirmagreg-team/ui/lib/utils/stored-value';
+
+const STORAGE_KEY = 'tfg.dataset-versions';
+const codec = jsonCodec<Record<string, string>>({});
+
+export function setVersionPreference(datasetId: string, version?: string) {
+  const next = { ...readStoredValue(STORAGE_KEY, codec.read) };
+  if (version) next[datasetId] = version;
+  else delete next[datasetId];
+  writeStoredValue(STORAGE_KEY, next, codec.write);
+}
+
+export function useVersionPreference(datasetId?: string): string | undefined {
+  return useSyncExternalStore(
+    (onChange) => subscribeStoredValue(STORAGE_KEY, onChange),
+    () =>
+      datasetId
+        ? readStoredValue(STORAGE_KEY, codec.read)[datasetId]
+        : undefined,
+    () => undefined,
+  );
+}

package/src/lib/breadcrumb.ts

@@ -0,0 +1,78 @@
+import 'server-only';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { stripLangFromUrl } from '@terrafirmagreg-team/translate/lib/slug';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { localizePageTree } from '@terrafirmagreg-team/translate/server';
+import { sectionConfig } from './config';
+import { lookupPagePreview } from './preview/lookup';
+import { datasetId } from './tree';
+import type { SectionSource } from './page';
+import type { DatasetCatalog, SectionPage } from '@terrafirmagreg-team/kit/types';
+
+export type SectionCrumb = { name: string; url?: string };
+
+function findTrail(
+  nodes: readonly PageTree.Node[],
+  url: string,
+): PageTree.Node[] | undefined {
+  for (const node of nodes) {
+    if (node.type === 'page' && node.url === url) return [node];
+    if (node.type === 'folder') {
+      if (node.index?.url === url) return [node];
+      const inner = findTrail(node.children, url);
+      if (inner) return [node, ...inner];
+    }
+  }
+  return undefined;
+}
+
+function nodeName(name: unknown): string {
+  return typeof name === 'string' ? name : '';
+}
+
+export function sectionBreadcrumbItems(
+  source: SectionSource,
+  page: SectionPage,
+  lang: Lang,
+): SectionCrumb[] {
+  const languages = [...sectionConfig().knownLanguages];
+  const tree = localizePageTree(source.getPageTree(), lang, {
+    languages,
+    fallbackLanguage: loadLocaleRegistry().defaultLanguage,
+  });
+  const dataset = page.slugs[0];
+  const folder = tree.children.find(
+    (node): node is PageTree.Folder =>
+      node.type === 'folder' && datasetId(node) === dataset,
+  );
+  if (!folder) return [{ name: page.data.title }];
+
+  const pageUrl = stripLangFromUrl(page.url, languages);
+  if (folder.index?.url === pageUrl) return [];
+
+  const trail = findTrail(folder.children, pageUrl);
+  const items: SectionCrumb[] = [];
+  for (const node of trail?.slice(0, -1) ?? []) {
+    if (node.type === 'folder') {
+      items.push({ name: nodeName(node.name), url: node.index?.url });
+    }
+  }
+  items.push({ name: page.data.title });
+  return items;
+}
+
+export function sectionBreadcrumbPreviews(
+  items: readonly SectionCrumb[],
+  lang: Lang,
+  catalog: DatasetCatalog,
+): Record<string, PagePreviewData> {
+  const previews: Record<string, PagePreviewData> = {};
+  for (const item of items) {
+    if (!item.url) continue;
+    const preview = lookupPagePreview(catalog, item.url, lang);
+    if (preview) previews[item.url] = preview;
+  }
+  return previews;
+}

package/src/lib/config.ts

@@ -0,0 +1,109 @@
+import type { ComponentType } from 'react';
+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[] };
+};
+
+export type SectionLegacyRoute = {
+  dataset: string;
+  path?: string;
+  overrides?: Record<string, string>;
+};
+
+export type SectionConfigInput = {
+
+  basePath: string;
+  siteUrl: string;
+  previewRoute: string;
+  docsRoute: string;
+  legacyRoutes: Record<string, SectionLegacyRoute>;
+
+  sectionTabs: readonly {
+    key: SectionKey;
+    url: string;
+    icon?: ComponentType<{ className?: string }>;
+  }[];
+
+  dumpSections?: readonly SectionKey[];
+
+  datasetConfig: Record<
+    string,
+    {
+      accent?: string;
+      order?: number;
+
+      repo?: `${string}/${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<string[]>;
+    loadDataset(id: string): Promise<SectionDump | null | undefined>;
+    hasContent: Record<string, (dump: SectionDump) => boolean>;
+  };
+};
+
+let config: SectionConfigInput | undefined;
+
+export function registerSectionConfig(
+  input: Partial<SectionConfigInput>,
+): void {
+  config = { ...config, ...input } as SectionConfigInput;
+}
+
+export function sectionConfig(): SectionConfigInput {
+  if (!config) {
+    throw new Error(
+      'Section config is not registered — call registerSectionConfig() at app startup.',
+    );
+  }
+  return config;
+}
+
+export type ClientDumpLoader = {
+  loadDump(dataset: string): Promise<{
+    manifest: { pack?: { version?: string | null } | null };
+  } | 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) {
+  let config: T | undefined;
+  return {
+    register(input: T) {
+      config = input;
+    },
+    get(): T {
+      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,30 @@
+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,211 @@
+import 'server-only';
+import { dynamicIconImports } from 'lucide-react/dynamic';
+import { sectionConfig } from './config';
+import { sections } from './sources';
+import { datasetId } from './tree';
+import { loadLocaleRegistry, sortLangCodes } from '@terrafirmagreg-team/translate/server';
+import { parseDatasetRef } from './location';
+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, Map<string, Record<string, unknown>>>();
+
+function staticSectionMeta(
+  section: SectionKey,
+): Map<string, Record<string, unknown>> {
+  let meta = sectionMeta.get(section);
+  if (meta) return meta;
+  meta = new Map();
+  const source = sections[section]?.source;
+  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) meta.set(id, data);
+    }
+  }
+  sectionMeta.set(section, meta);
+  return meta;
+}
+
+function contentSectionDatasets(section: SectionKey): SectionDataset[] {
+  const source = sections[section]?.source;
+  if (!source) return [];
+  const languages = new Map<string, Set<string>>();
+  for (const page of source.getPages()) {
+    const [dataset, lang] = page.slugs;
+    if (!dataset || !lang) continue;
+    let set = languages.get(dataset);
+    if (!set) languages.set(dataset, (set = new Set()));
+    set.add(lang);
+  }
+  const meta = staticSectionMeta(section);
+  return [...languages.keys()].map((id) => ({
+    id,
+    languages: datasetLanguages([...(languages.get(id) ?? [])]),
+    ...metaFields(meta.get(id) ?? {}),
+    ...datasetAppearance(id),
+  }));
+}
+
+function datasetMeta(
+  section: SectionKey,
+  id: string,
+): Omit<SectionDataset, 'id' | 'languages'> {
+  const meta = 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 bySection = new Map<SectionKey, Promise<SectionDataset[]>>();
+
+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(
+  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 } = parseDatasetRef(ref);
+    if (version) {
+      const list = versions.get(id) ?? [];
+      list.push(version);
+      versions.set(id, list);
+    }
+  }
+  const ids = refs.filter((ref) => !parseDatasetRef(ref).version);
+  const usable = await Promise.all(
+    ids.map(async (id) => {
+      const index = await dump.loadDataset(id);
+      if (!index || !hasContent(index)) return null;
+      return {
+        id,
+        languages: datasetLanguages(index.manifest.languages ?? []),
+      };
+    }),
+  );
+  return usable
+    .filter((row): row is { id: string; languages: Lang[] } => row !== null)
+    .map(({ id, languages }) => ({
+      id,
+      languages,
+      ...(versions.get(id)?.length
+        ? { versions: versions.get(id)!.sort(compareVersions).reverse() }
+        : {}),
+      ...datasetMeta('docs', id),
+      ...datasetAppearance(id),
+    }))
+    .sort(datasetOrder);
+}
+
+export function sectionDatasets(
+  section: SectionKey,
+): Promise<SectionDataset[]> {
+  let cached = bySection.get(section);
+  if (!cached) {
+    const hasContent = sectionConfig().dump?.hasContent[section];
+    if (hasContent) {
+      cached = dumpDatasets(hasContent);
+      bySection.set(section, cached);
+      return cached;
+    }
+    const rows = contentSectionDatasets(section);
+    rows.sort(datasetOrder);
+    cached = Promise.resolve(rows);
+    bySection.set(section, cached);
+  }
+  return cached;
+}
+
+export async function defaultDataset(
+  section: SectionKey,
+): Promise<string | undefined> {
+  return (await sectionDatasets(section))[0]?.id;
+}
+
+export function findDataset(
+  datasets: readonly SectionDataset[],
+  ref: string,
+): SectionDataset | undefined {
+  const { id, version } = parseDatasetRef(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 resolveDatasetRef(
+  section: SectionKey,
+  ref: string,
+): Promise<SectionDataset | undefined> {
+  return findDataset(await sectionDatasets(section), ref);
+}
+
+export async function datasetSlugs(section: SectionKey): Promise<string[]> {
+  return (await sectionDatasets(section)).flatMap(({ id, versions }) => [
+    id,
+    ...(versions ?? []).map((version) => `${id}@${version}`),
+  ]);
+}
+
+let catalogCached: Promise<DatasetCatalog> | undefined;
+
+export function datasetCatalog(): Promise<DatasetCatalog> {
+  catalogCached ??= Promise.all(
+    sectionConfig().sectionTabs.map(
+      async ({ key }) => [key, await sectionDatasets(key)] as const,
+    ),
+  ).then((rows) => Object.fromEntries(rows) as DatasetCatalog);
+  return catalogCached;
+}

package/src/lib/landing.ts

@@ -0,0 +1,46 @@
+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, 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: ref,
+    datasetTitle: meta.title ?? meta.id,
+    lang,
+  };
+}
+
+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,15 @@
+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/legacy.ts

@@ -0,0 +1,18 @@
+import { sectionConfig } from './config';
+
+export function legacyTarget(pathname: string): string | undefined {
+  const { docsRoute, legacyRoutes } = sectionConfig();
+  const prefixes = Object.keys(legacyRoutes).sort((a, b) => b.length - a.length);
+  const parts = pathname.split('/').filter(Boolean);
+  const prefix = prefixes.find((p) => p === parts[0] || p === `${parts[0]}/${parts[2]}`);
+  if (!prefix) return undefined;
+  const prefixParts = prefix.split('/');
+  const lang = parts[1];
+  const rest = parts.slice(prefixParts.length + 1).join('/');
+  const route = legacyRoutes[prefix];
+  const override = route.overrides?.[rest];
+  const target =
+    override ??
+    `${docsRoute}/${route.dataset}${[route.path, rest].filter(Boolean).map((p) => `/${p}`).join('')}`;
+  return lang ? `${target}?lang=${lang}` : target;
+}

package/src/lib/location.ts

@@ -0,0 +1,63 @@
+import { sectionConfig } from './config';
+import type { SectionKey } from '@terrafirmagreg-team/kit/types';
+
+let urls: Record<SectionKey, string> | undefined;
+const sectionUrls = () =>
+  (urls ??= Object.fromEntries(
+    sectionConfig().sectionTabs.map(({ key, url }) => [key, url]),
+  ) as Record<SectionKey, string>);
+
+let keys: Set<SectionKey> | undefined;
+const sectionKeys = () =>
+  (keys ??= new Set(sectionConfig().sectionTabs.map(({ key }) => key)));
+
+export function sectionUrl(section: SectionKey, dataset?: string): string {
+  const base = sectionUrls()[section];
+  return dataset ? `${base}/${dataset}` : base;
+}
+
+export function isSectionKey(value: string | undefined): value is SectionKey {
+  return value !== undefined && sectionKeys().has(value);
+}
+
+export type SectionLocation = {
+  section?: SectionKey;
+
+  dataset?: string;
+};
+
+export function isDumpSection(section: SectionKey | undefined): boolean {
+  return (
+    section !== undefined &&
+    (sectionConfig().dumpSections ?? []).includes(section)
+  );
+}
+
+export function dumpSectionKeys(): readonly SectionKey[] {
+  return sectionConfig().dumpSections ?? [];
+}
+
+export function parseDatasetRef(ref: string): {
+  id: string;
+  version?: string;
+} {
+  const decoded = decodeURIComponent(ref);
+  const at = decoded.lastIndexOf('@');
+  if (at <= 0 || at === decoded.length - 1) return { id: decoded };
+  return { id: decoded.slice(0, at), version: decoded.slice(at + 1) };
+}
+
+export function datasetRef(id: string, version?: string): string {
+  return version ? `${id}@${version}` : id;
+}
+
+export function parseSectionLocation(pathname: string): SectionLocation {
+  const { basePath } = sectionConfig();
+  const path =
+    basePath && pathname.startsWith(basePath)
+      ? pathname.slice(basePath.length)
+      : pathname;
+  const [section, dataset] = path.split('/').filter(Boolean);
+  if (!isSectionKey(section)) return {};
+  return { section, dataset };
+}