@terrafirmagreg-team/kit 0.1.0 → 1.2.0

package/src/components/views/section.tsx

@@ -13,9 +13,11 @@ import { langContent } from '@terrafirmagreg-team/translate/server';
 import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
 import { readPageSource, translationState } from '@terrafirmagreg-team/translate/server';
 import { resolvePage, type SectionSource } from '@terrafirmagreg-team/kit/lib/page';
+import { localeLoader } from '@terrafirmagreg-team/kit/lib/locale/renderer';
 import { findNeighbour } from 'fumadocs-core/page-tree';
 import type {
   DatasetCatalog,
+  SectionKey,
   SectionPage,
   SectionTrees,
 } from '@terrafirmagreg-team/kit/types';
@@ -27,6 +29,7 @@ import type {
   ComponentType,
   ReactNode,
 } from 'react';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
 
 export interface SectionWorkspaceProps {
   page: SectionPage;
@@ -39,7 +42,7 @@ export interface SectionWorkspaceProps {
   history?: boolean;
 }
 
-export function SectionView({
+export function renderSectionWorkspace({
   source,
   slug,
   contentDir,
@@ -47,6 +50,8 @@ export function SectionView({
   catalog,
   history,
   workspace: Workspace,
+  page,
+  lang,
 }: {
   source: SectionSource;
   slug: string[] | undefined;
@@ -55,54 +60,93 @@ export function SectionView({
   catalog: DatasetCatalog;
   history?: boolean;
   workspace: ComponentType<SectionWorkspaceProps>;
+  page: SectionPage;
+  lang: Lang;
 }) {
   const { defaultLanguage } = loadLocaleRegistry();
+  let copied: 'untranslated' | 'partial' | undefined;
+  if (lang !== defaultLanguage) {
+    const fallback = resolvePage(source, slug, defaultLanguage)?.page as
+      | SectionPage
+      | undefined;
+    if (fallback && fallback !== page) {
+      const own = readPageSource(contentDir, page.path);
+      const original = readPageSource(contentDir, fallback.path);
+      if (own && original) {
+        const state = translationState(own, original);
+        if (state !== 'ok') copied = state;
+      }
+    }
+  }
+  const crumbs = sectionBreadcrumbItems(source, page, lang);
+  const datasetId = page.url.split('/').filter(Boolean)[1];
+  const tree = datasetId ? trees?.[lang]?.[datasetId] : undefined;
+  const neighbours = tree ? findNeighbour(tree, page.url) : undefined;
+  return (
+    <Workspace
+      page={page}
+      crumbs={crumbs}
+      footer={neighbours}
+      previews={sectionBreadcrumbPreviews(crumbs, lang, catalog)}
+      link={createRelativeLink(
+        source as LoaderOutput<LoaderConfig>,
+        page as unknown as Page,
+        (props) => (
+          <LinkPreview
+            preview={lookupPagePreview(catalog, props.href, lang)}
+            {...props}
+          />
+        ),
+      )}
+      contentDir={contentDir}
+      copied={copied}
+      history={history}
+    />
+  );
+}
+
+export async function SectionView({
+  section,
+  getSource,
+  slug,
+  contentDir,
+  trees,
+  catalog,
+  history,
+  workspace,
+}: {
+  section: SectionKey;
+  getSource: () => Promise<SectionSource>;
+  slug: string[] | undefined;
+  contentDir: string;
+  trees?: SectionTrees;
+  catalog: DatasetCatalog;
+  history?: boolean;
+  workspace: ComponentType<SectionWorkspaceProps>;
+}) {
+  const source = await getSource();
   const content = langContent(
     slug,
     (s, l) => resolvePage(source, s, l),
-    (page, lang) => {
-      const self = page as SectionPage;
-      let copied: 'untranslated' | 'partial' | undefined;
-      if (lang !== defaultLanguage) {
-        const fallback = resolvePage(source, slug, defaultLanguage)?.page as
-          | SectionPage
-          | undefined;
-        if (fallback && fallback !== self) {
-          const own = readPageSource(contentDir, self.path);
-          const original = readPageSource(contentDir, fallback.path);
-          if (own && original) {
-            const state = translationState(own, original);
-            if (state !== 'ok') copied = state;
-          }
-        }
-      }
-      const crumbs = sectionBreadcrumbItems(source, self, lang);
-      const datasetId = self.url.split('/').filter(Boolean)[1];
-      const tree = datasetId ? trees?.[lang]?.[datasetId] : undefined;
-      const neighbours = tree ? findNeighbour(tree, self.url) : undefined;
-      return (
-        <Workspace
-          page={self}
-          crumbs={crumbs}
-          footer={neighbours}
-          previews={sectionBreadcrumbPreviews(crumbs, lang, catalog)}
-          link={createRelativeLink(
-            source as LoaderOutput<LoaderConfig>,
-            page as Page,
-            (props) => (
-              <LinkPreview
-                preview={lookupPagePreview(catalog, props.href, lang)}
-                {...props}
-              />
-            ),
-          )}
-          contentDir={contentDir}
-          copied={copied}
-          history={history}
-        />
-      );
-    },
+    (page, lang) =>
+      renderSectionWorkspace({
+        source,
+        slug,
+        contentDir,
+        trees,
+        catalog,
+        history,
+        workspace,
+        page: page as SectionPage,
+        lang,
+      }),
   );
   if (!content) notFound();
-  return <LangContentSwitch content={content} />;
+  return (
+    <LangContentSwitch
+      content={content}
+      loadLang={localeLoader()?.bind(null, { section, slug })}
+    />
+  );
 }
+

package/src/components/workspace/content.tsx

@@ -51,3 +51,4 @@ export function WorkspaceFooter({
     />
   );
 }
+

package/src/components/workspace/index.ts

@@ -10,3 +10,4 @@ export {
   WorkspaceFooter,
 } from './content';
 export { WorkspacePagination } from './pagination';
+

package/src/components/workspace/pagination.tsx

@@ -62,7 +62,7 @@ function WorkspacePaginationItem({
         {!next && (
           <Icon className="size-3.5 transition-transform group-hover:-translate-x-0.5 rtl:rotate-180" />
         )}
-        {next ? t('ui.next_page') : t('ui.prev_page')}
+        {next ? t('Next Page', { note: 'ui.next_page' }) : t('Previous Page', { note: 'ui.prev_page' })}
         {next && (
           <Icon className="size-3.5 transition-transform group-hover:translate-x-0.5 rtl:rotate-180" />
         )}
@@ -71,3 +71,4 @@ function WorkspacePaginationItem({
     </Link>
   );
 }
+

package/src/components/workspace/workspace.tsx

@@ -146,3 +146,4 @@ export function Workspace({
     </TOCProvider>
   );
 }
+

package/src/hooks/use-catalog.ts

@@ -9,3 +9,4 @@ export function useSectionCatalog(): DatasetCatalog {
   if (!catalog) throw new Error('SectionCatalogContext is not provided');
   return catalog;
 }
+

package/src/hooks/use-current-dataset.ts

@@ -1,14 +1,24 @@
 'use client';
+import { useMemo } from 'react';
 import { usePathname } from 'next/navigation';
-import { parseDatasetRef, parseSectionLocation } from '@terrafirmagreg-team/kit/lib/location';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import {
+  type DatasetRef,
+  parseSectionLocation,
+  resolveDatasetRef,
+} from '@terrafirmagreg-team/sites/location';
 import type { SectionDataset } from '@terrafirmagreg-team/kit/types';
 
 export function useCurrentDataset(
   datasets: readonly SectionDataset[],
-): string | undefined {
+): DatasetRef | undefined {
   const pathname = usePathname();
+  const versionParam = useLocationSearchParams().get('version') ?? undefined;
   const { dataset } = parseSectionLocation(pathname);
-  if (!dataset) return undefined;
-  const { id } = parseDatasetRef(dataset);
-  return datasets.some((row) => row.id === id) ? dataset : undefined;
+  const meta = datasets.find((row) => row.id === dataset);
+  return useMemo(
+    () => dataset && meta ? resolveDatasetRef(dataset, versionParam, meta).ref : undefined,
+    [dataset, versionParam, meta],
+  );
 }
+

package/src/hooks/use-dataset-accent.ts

@@ -11,3 +11,4 @@ export function useDatasetAccent(accent?: string) {
     };
   }, [accent]);
 }
+

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

@@ -2,14 +2,14 @@
 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 { sectionTabs } from '@terrafirmagreg-team/sites/sections';
 import {
-  datasetRef,
   isDumpSection,
-  parseDatasetRef,
+  resolveDatasetRef,
   sectionUrl,
-} from '@terrafirmagreg-team/kit/lib/location';
+} from '@terrafirmagreg-team/sites/location';
 import { useCurrentDataset } from '@terrafirmagreg-team/kit/hooks/use-current-dataset';
+import { useSectionNames } from '@terrafirmagreg-team/kit/hooks/use-section-names';
 import { useVersionPreference } from '@terrafirmagreg-team/kit/hooks/use-version-pref';
 import type { LeftSidebarScope } from '@terrafirmagreg-team/kit/types';
 import type {
@@ -30,31 +30,33 @@ export function useNavOptions({ section, catalog }: LeftSidebarScope): {
   dataset: SwitcherProps;
 } {
   const t = useTranslations();
+  const sectionNames = useSectionNames();
   const current = useCurrentDataset(catalog[section]);
-  const baseId = current ? parseDatasetRef(current).id : undefined;
-  const pinned = current ? parseDatasetRef(current).version : undefined;
+  const baseId = current ? current.id : undefined;
+  const pinned = current ? current.version : undefined;
   const preferred = useVersionPreference(baseId);
   const version = pinned ?? preferred;
 
   const sectionOptions: SwitcherOption[] = useMemo(
     () =>
-      sectionConfig().sectionTabs.map(({ key, icon: Icon }) => {
+      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;
+        const pinned =
+          isDumpSection(key) && baseId
+            ? resolveDatasetRef(baseId, version, meta).pinned
+            : undefined;
+        const suffix = pinned ? `?version=${encodeURIComponent(pinned)}` : '';
         return {
           value: key,
-          title: t(`sections.${key}`),
-          description: t(`sections.desc.${key}`),
+          title: sectionNames[key]?.title ?? key,
+          description: sectionNames[key]?.desc,
           icon: Icon ? createElement(Icon) : undefined,
-          url: meta ? sectionUrl(key, pinnedRef) : sectionUrl(key),
+          url: meta ? `${sectionUrl(key, baseId)}${suffix}` : sectionUrl(key),
         };
       }),
-    [t, baseId, version, catalog],
+    [sectionNames, baseId, version, catalog],
   );
 
   const datasetOptions: SwitcherOption[] = useMemo(
@@ -73,12 +75,13 @@ export function useNavOptions({ section, catalog }: LeftSidebarScope): {
     section: {
       options: sectionOptions,
       selected: section,
-      placeholder: t('ui.select_section'),
+      placeholder: t('Select section', { note: 'ui.select_section' }),
     },
     dataset: {
       options: datasetOptions,
       selected: baseId,
-      placeholder: t('ui.select_dataset'),
+      placeholder: t('Select dataset', { note: 'ui.select_dataset' }),
     },
   };
 }
+

package/src/hooks/use-section-names.ts

@@ -0,0 +1,40 @@
+'use client';
+import { useMemo } from 'react';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+
+export function useSectionNames(): Record<
+  string,
+  { title: string; desc: string }
+> {
+  const t = useTranslations();
+  return useMemo(
+    () => ({
+      docs: {
+        title: t('Docs', { note: 'sections.docs' }),
+        desc: t('Documentation', { note: 'sections.desc.docs' }),
+      },
+      changelog: {
+        title: t('Changelog', { note: 'sections.changelog' }),
+        desc: t('Release history and version notes', {
+          note: 'sections.desc.changelog',
+        }),
+      },
+      recipe: {
+        title: t('Recipes', { note: 'sections.recipe' }),
+        desc: t('Crafting and processing recipes', {
+          note: 'sections.desc.recipe',
+        }),
+      },
+      quest: {
+        title: t('Quests', { note: 'sections.quest' }),
+        desc: t('Quest chapters and objectives', { note: 'sections.desc.quest' }),
+      },
+      guide: {
+        title: t('Guide', { note: 'sections.guide' }),
+        desc: t('Gameplay guide', { note: 'sections.desc.guide' }),
+      },
+    }),
+    [t],
+  );
+}
+

package/src/hooks/{toc.ts → use-toc.ts}

@@ -7,3 +7,4 @@ export const TOCContext = createContext<TOCItemType[]>([]);
 export function useTOCItems(): TOCItemType[] {
   return use(TOCContext);
 }
+

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

@@ -28,3 +28,4 @@ export function useVersionPreference(datasetId?: string): string | undefined {
     () => undefined,
   );
 }
+

package/src/hooks/use-versioned-dataset.ts

@@ -0,0 +1,21 @@
+'use client';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import {
+  resolveDatasetRef,
+  type DatasetVersionInfo,
+  type DatasetRef,
+} from '@terrafirmagreg-team/sites/location';
+
+const refs = new Map<string, DatasetRef | undefined>();
+
+export function useVersionedDataset(
+  id: string | undefined,
+  info?: DatasetVersionInfo,
+): DatasetRef | undefined {
+  const version = useLocationSearchParams().get('version') ?? undefined;
+  const key = `${id ?? ''} ${version ?? ''} ${info?.latest ?? ''} ${info?.versions?.join(',') ?? ''}`;
+  if (!refs.has(key))
+    refs.set(key, id ? resolveDatasetRef(id, version, info).ref : undefined);
+  return refs.get(key);
+}
+

package/src/lib/breadcrumb.ts

@@ -1,5 +1,6 @@
 import 'server-only';
 import type * as PageTree from 'fumadocs-core/page-tree';
+import { searchPath } from 'fumadocs-core/breadcrumb';
 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';
@@ -13,21 +14,6 @@ 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 : '';
 }
@@ -52,7 +38,7 @@ export function sectionBreadcrumbItems(
   const pageUrl = stripLangFromUrl(page.url, languages);
   if (folder.index?.url === pageUrl) return [];
 
-  const trail = findTrail(folder.children, pageUrl);
+  const trail = searchPath(folder.children, pageUrl);
   const items: SectionCrumb[] = [];
   for (const node of trail?.slice(0, -1) ?? []) {
     if (node.type === 'folder') {
@@ -76,3 +62,4 @@ export function sectionBreadcrumbPreviews(
   }
   return previews;
 }
+

package/src/lib/config.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react';
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
 import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
 import type {
   SectionKey,
@@ -6,13 +6,17 @@ import type {
 } from '@terrafirmagreg-team/kit/types';
 
 export type SectionDump = {
-  manifest: { languages?: readonly string[] };
-};
-
-export type SectionLegacyRoute = {
-  dataset: string;
-  path?: string;
-  overrides?: Record<string, string>;
+  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 = {
@@ -21,15 +25,6 @@ export type SectionConfigInput = {
   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,
@@ -39,6 +34,8 @@ export type SectionConfigInput = {
 
       repo?: `${string}/${string}`;
 
+      discussions?: { repoId: string; categoryId: string };
+
       crowdin?: string;
 
       links?: readonly {
@@ -54,33 +51,37 @@ export type SectionConfigInput = {
   sources: Partial<Record<SectionKey, SectionSourceEntry>>;
 
   dump?: {
-    discoverDatasets(): Promise<string[]>;
-    loadDataset(id: string): Promise<SectionDump | null | undefined>;
+    discoverDatasets(): Promise<DatasetRef[]>;
+    loadDataset(ref: DatasetRef): Promise<SectionDump | null | undefined>;
     hasContent: Record<string, (dump: SectionDump) => boolean>;
   };
 };
 
-let config: SectionConfigInput | undefined;
+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 {
-  config = { ...config, ...input } as SectionConfigInput;
+  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.',
+      '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>;
+  loadDump(dataset: DatasetRef): Promise<SectionDump | null | undefined>;
   loadVersions(
     datasetId: string,
   ): Promise<{ latest?: string; versions: string[] } | null>;
@@ -92,18 +93,19 @@ export const {
 } = createConfig<ClientDumpLoader>('ClientDump');
 
 export function createConfig<T>(label: string) {
-  let config: T | undefined;
   return {
     register(input: T) {
-      config = input;
+      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.`,
+          `${label} config is not registered: call register${label}Config() at app startup.`,
         );
       }
       return config;
     },
   };
 }
+

package/src/lib/dataset-links.ts

@@ -28,3 +28,4 @@ export const datasetLink = {
     icon: 'discord',
   }),
 };
+