@terrafirmagreg-team/guide 0.0.0-stage → 0.1.0

package/src/lib/tree/index.ts

@@ -0,0 +1,117 @@
+import 'server-only';
+import { createElement } from 'react';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
+import { loadMergedLangMap } from '@terrafirmagreg-team/game/lib/dump/assets/lang/load';
+import { asRecord, asString } from '@terrafirmagreg-team/game/lib/dump/contract/read';
+import { loadDatasetDump } from '@terrafirmagreg-team/game/lib/dump/mods/load';
+import { clientDumpJson } from '@terrafirmagreg-team/game/lib/dump/client/dump';
+import { keyTreeNode } from '@terrafirmagreg-team/translate/server';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { encodeQueryValue } from '@terrafirmagreg-team/translate/lib/url';
+import { sectionUrl } from '@terrafirmagreg-team/kit/lib/location';
+import { bookOptionId } from '@terrafirmagreg-team/guide/lib/paths';
+import { bookSlug, toBook } from '@terrafirmagreg-team/guide/lib/book';
+import { sectionDatasets } from '@terrafirmagreg-team/kit/lib/datasets';
+import type { GuideBookJson, GuideBookRef } from '@terrafirmagreg-team/guide/lib/data/dto';
+import type { SectionTrees } from '@terrafirmagreg-team/kit/types';
+
+function bookIcon(
+  dataset: string,
+  raw: GuideBookJson | undefined,
+): React.ReactNode {
+  const cover = asRecord(raw?.cover);
+  const coverId = asString(cover?.id) ?? undefined;
+  if (!coverId) return undefined;
+  return createElement(
+    'span',
+    {
+      'data-icon': true,
+      className:
+        'inline-flex size-3.5 shrink-0 items-center justify-center overflow-hidden',
+    },
+    createElement(Entry, {
+      dataset,
+      id: coverId,
+      kind: 'item',
+      size: 14,
+      href: false,
+      tooltip: false,
+      missing: 'hide',
+    }),
+  );
+}
+
+function bookLeaf(
+  dataset: string,
+  ref: GuideBookRef,
+  slug: string,
+  raw: GuideBookJson | undefined,
+  map: Record<string, string>,
+): PageTree.Item {
+  const book = toBook(raw, ref, slug, map);
+  const bookId = bookOptionId(ref.modId, ref.bookPath);
+  return keyTreeNode({
+    type: 'page',
+    name: book.name,
+    url: `${sectionUrl('guide', dataset)}?book=${encodeQueryValue(bookId)}`,
+    icon: bookIcon(dataset, raw),
+    $id: `${dataset}/book/${bookId}`,
+  }) as PageTree.Item;
+}
+
+async function datasetBookLeaves(
+  dataset: string,
+  langMap: Record<string, string>,
+): Promise<PageTree.Node[]> {
+  const dump = await loadDatasetDump(dataset);
+  if (!dump) return [];
+  const taken = new Set<string>();
+  const leaves: PageTree.Node[] = [];
+  for (const mod of dump.mods) {
+    const raws = await Promise.all(
+      mod.books.map((ref) =>
+        clientDumpJson(dataset, `${ref.dir}/book.json`).then(
+          (raw) => asRecord(raw) as GuideBookJson | undefined,
+        ),
+      ),
+    );
+    for (const [i, ref] of mod.books.entries()) {
+      const raw = raws[i];
+      if (!raw) continue;
+      let slug = bookSlug(raw, ref);
+      if (taken.has(slug)) {
+        let n = 2;
+        while (taken.has(`${slug}-${n}`)) n += 1;
+        slug = `${slug}-${n}`;
+      }
+      taken.add(slug);
+      leaves.push(bookLeaf(dataset, ref, slug, raw, langMap));
+    }
+  }
+  return leaves;
+}
+
+let cached: Promise<SectionTrees> | undefined;
+
+export function guideTrees(): Promise<SectionTrees> {
+  cached ??= buildGuideTrees();
+  return cached;
+}
+
+async function buildGuideTrees(): Promise<SectionTrees> {
+  const { defaultLanguage } = loadLocaleRegistry();
+  const datasets = await sectionDatasets('guide');
+  const trees: SectionTrees = {};
+  for (const { id, title: datasetTitle, languages } of datasets) {
+    for (const lang of languages ?? [defaultLanguage]) {
+      const map = await loadMergedLangMap(id, lang);
+      (trees[lang] ??= {})[id] = {
+        name: datasetTitle ?? id,
+        children: await datasetBookLeaves(id, map),
+        $id: `guide/${id}/${lang}`,
+      } satisfies PageTree.Root;
+    }
+  }
+  return trees;
+}

package/src/locales/en_us.json

@@ -0,0 +1,22 @@
+{
+  "guide": {
+    "entry_count": "{count} entries",
+    "page_count": "{count} pages",
+    "entry_missing": "Entry not found",
+    "entity_unavailable": "Entity preview unavailable",
+    "link": "Open",
+    "objective": "Objective",
+    "quest": "Quest",
+    "recipe_empty": "No recipes",
+    "related": "Related"
+  },
+  "ui": {
+    "select_book": "Select book"
+  },
+  "sections": {
+    "guide": "Guide",
+    "desc": {
+      "guide": "Gameplay guide"
+    }
+  }
+}

package/src/locales/ru_ru.json

@@ -0,0 +1,22 @@
+{
+  "guide": {
+    "entry_count": "Записей: {count}",
+    "page_count": "Страниц: {count}",
+    "entry_missing": "Запись не найдена",
+    "entity_unavailable": "Превью сущности недоступно",
+    "link": "Открыть",
+    "objective": "Задача",
+    "quest": "Квест",
+    "recipe_empty": "Нет рецептов",
+    "related": "Связанное"
+  },
+  "ui": {
+    "select_book": "Выберите книгу"
+  },
+  "sections": {
+    "guide": "Гайды",
+    "desc": {
+      "guide": "Игровой гайд"
+    }
+  }
+}

package/src/locales.ts

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

package/src/types/index.ts

@@ -0,0 +1,215 @@
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { DatasetLanding } from '@terrafirmagreg-team/kit/types';
+import type { DumpText } from '@terrafirmagreg-team/game/lib/dump/contract/text';
+import type {
+  ReferenceKind,
+  TaggedReference,
+} from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import type { GuidePage } from '@terrafirmagreg-team/guide/lib/data/dto';
+import type { AtlasBundle } from '@terrafirmagreg-team/game/lib/dump/assets/atlas/dto';
+import type { Recipe } from '@terrafirmagreg-team/recipe/lib/data/dto';
+import type { DumpEntityEntry } from '@terrafirmagreg-team/game/lib/dump/data/registry/dto';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+
+export type {
+  GuideMultiblock,
+  GuidePage,
+  GuideTableCell,
+  GuideTableLegend,
+} from '@terrafirmagreg-team/guide/lib/data/dto';
+
+export type GuideEntry = {
+  id: string;
+  name?: string;
+  category?: string;
+  icon?: TaggedReference;
+  pages?: GuidePage[];
+  order?: number;
+  contentLanguage?: Lang;
+
+  translation?: 'untranslated' | 'partial';
+};
+
+export type GuideEntryRef = {
+  id: string;
+  name: string;
+  icon?: TaggedReference;
+  pageCount?: number;
+  order?: number;
+  translation?: 'untranslated' | 'partial';
+};
+
+export type GuideCategory = {
+  id: string;
+  name: string;
+  description?: string;
+  icon?: TaggedReference;
+  entries: GuideEntryRef[];
+  order?: number;
+  translation?: 'untranslated' | 'partial';
+};
+
+export type GuideBook = {
+  id?: string;
+  slug: string;
+  name: string;
+  description?: string;
+  landing: DumpText[];
+  landingText?: string;
+  cover: TaggedReference | null;
+  macros?: Record<string, string>;
+  translation?: 'untranslated' | 'partial';
+};
+
+export type GuideIndex = {
+  status: 'missing' | 'ready';
+  root: string;
+  modId: string;
+  bookId?: string;
+  bookPath?: string;
+  bookSlug?: string;
+  book: GuideBook | null;
+  categories: GuideCategory[];
+  entries: GuideEntry[];
+  language: Lang;
+  isFallback: boolean;
+};
+
+type GuideMultiblockDef = {
+  id: string;
+  pattern?: string[][];
+  mapping?: Record<string, unknown>;
+  glb?: string;
+  error?: string | null;
+};
+
+type GuideEntityRender = {
+  path?: string;
+  scale?: number;
+  offset?: number;
+  width?: number;
+  height?: number;
+};
+
+export type GuideBookMeta = {
+  bookId?: string;
+  name?: string;
+  multiblockDefs?: GuideMultiblockDef[];
+  entityRenders?: Record<string, GuideEntityRender>;
+};
+
+export type GuideFormatNode =
+  | {
+      type: 'text';
+      value: string;
+      styles: string[];
+      color?: string;
+      link?: string;
+      tooltip?: string;
+    }
+  | { type: 'break' }
+  | { type: 'keybind'; value: string }
+  | { type: 'command'; value: string; label?: string };
+
+export type GuideFormatOptions = {
+  dataset?: string;
+  lang?: Lang;
+  modId?: string;
+  bookPath?: string;
+  categoryByEntry?: Map<string, string>;
+  macros?: Record<string, string>;
+  langMap?: Record<string, string>;
+  keybinds?: Record<string, string>;
+  questLinks?: Record<string, { filename: string; questId: string }>;
+  previews?: Record<string, PagePreviewData>;
+};
+
+export type GuideCategoryRef = {
+  id: string;
+};
+
+type GuideReferenceKind = 'guide' | 'recipe' | 'quest';
+
+export type GuideReference = {
+  kind: GuideReferenceKind;
+  id: string;
+  anchor?: string;
+};
+
+export type ResolvedGuideReference = GuideReference & {
+  href?: string;
+  available: boolean;
+};
+
+export type GuideReferenceContext = {
+  dataset: string;
+  lang: Lang;
+  modId: string;
+  bookPath: string;
+  categoryByEntry: Map<string, string>;
+  questLinks?: Record<string, { filename: string; questId: string }>;
+  targets?: Partial<
+    Record<'recipe' | 'quest', (id: string) => string | undefined>
+  >;
+};
+
+export type GuideTocLabels = {
+  related?: string;
+  objective?: string;
+};
+
+export type GuidePageKind = 'pack' | 'overview' | 'category' | 'entry';
+
+export type GuidePageData = DatasetLanding;
+
+export type PageRendererProps = {
+  dataset: string;
+  lang: Lang;
+  bookPath: string;
+  page: GuidePage;
+  atlases?: Record<string, AtlasBundle>;
+  meta: GuideBookMeta;
+  bookModId: string;
+  categoryByEntry: Map<string, string>;
+  langMap: Record<string, string>;
+  entryRefs: Map<string, GuideEntryRef>;
+  keybinds?: Record<string, string>;
+  book?: GuideBook | null;
+  extras?: GuideEntryExtras;
+  questLinks?: Record<string, { filename: string; questId: string }>;
+  previews?: Record<string, PagePreviewData>;
+  messages: GuideMessages;
+};
+
+export type GuideMessages = Record<string, string>;
+
+export type GuideEntryExtras = {
+  atlases: Record<string, AtlasBundle>;
+  keybinds: Record<string, string>;
+  recipes: Record<string, Recipe>;
+  entities: Record<string, DumpEntityEntry>;
+  entityNames: Record<string, string>;
+  glbs: Record<string, string>;
+};
+
+export type GuidePagePayload = {
+  kind: GuidePageKind;
+  dataset: string;
+  lang: Lang;
+  title: string;
+  modId?: string;
+  bookPath?: string;
+  description?: string;
+  previewIcon?: string;
+  previewKind?: ReferenceKind;
+  categoryId?: string;
+  bookModId?: string;
+  book?: GuideBook | null;
+  categories?: GuideCategory[];
+  entries?: GuideEntry[];
+  entry?: GuideEntry;
+  extras?: GuideEntryExtras;
+  questLinks?: Record<string, { filename: string; questId: string }>;
+  previews?: Record<string, PagePreviewData>;
+  messages: GuideMessages;
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.