@terrafirmagreg-team/guide 0.0.0-stage → 1.2.0

package/src/lib/book/localize.ts

@@ -0,0 +1,77 @@
+import { langString } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+import type { DumpText } from '@terrafirmagreg-team/dump/lib/dump/contract/text';
+
+export type FallbackTracker = {
+  mark(key: string | undefined): void;
+  readonly flag: 'untranslated' | 'partial' | undefined;
+};
+
+export function fallbackTracker(
+  rawLang: Record<string, string> | undefined,
+): FallbackTracker | undefined {
+  if (!rawLang) return undefined;
+  let total = 0;
+  let missing = 0;
+  return {
+    mark(key) {
+      if (!key) return;
+      total += 1;
+      if (!langString(rawLang, key)) missing += 1;
+    },
+    get flag() {
+      if (!missing) return undefined;
+      return missing === total ? 'untranslated' : 'partial';
+    },
+  };
+}
+
+export function markTextKeys(
+  texts: DumpText[] | undefined,
+  tracker: FallbackTracker | undefined,
+) {
+  if (!tracker) return;
+  for (const text of texts ?? []) {
+    tracker.mark(text.translate);
+    markTextKeys(text.with, tracker);
+    markTextKeys(text.extra, tracker);
+  }
+}
+
+export function localize(
+  map: Record<string, string>,
+  key: string | undefined,
+  fallback: string,
+  tracker?: FallbackTracker,
+): string {
+  if (!key) return fallback;
+  tracker?.mark(key);
+  const bare =
+    key.startsWith('{') && key.endsWith('}') ? key.slice(1, -1).trim() : key;
+  return langString(map, key) ?? (bare !== key ? bare : fallback);
+}
+
+const LANG_KEY_WRAP = /^\{[^{}]+\}$/;
+
+export function localizeGuideValue(
+  value: unknown,
+  map: Record<string, string>,
+  tracker?: FallbackTracker,
+): unknown {
+  if (typeof value === 'string') {
+    if (!LANG_KEY_WRAP.test(value)) return value;
+    tracker?.mark(value);
+    return langString(map, value) ?? value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => localizeGuideValue(item, map, tracker));
+  }
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = localizeGuideValue(item, map, tracker);
+    }
+    return out;
+  }
+  return value;
+}
+

package/src/lib/book/raw.ts

@@ -0,0 +1,81 @@
+import { asTaggedReference } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { asDumpTextList } from '@terrafirmagreg-team/dump/lib/dump/contract/text';
+import type { DumpText } from '@terrafirmagreg-team/dump/lib/dump/contract/text';
+import type { TaggedReference } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { bareId } from '@terrafirmagreg-team/guide/lib/paths';
+
+export type RawRecord = Record<string, unknown>;
+
+export function numeric(value: unknown, fallback = 0): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+export function compareGuideOrder(
+  left: { id: string; order?: unknown },
+  right: { id: string; order?: unknown },
+) {
+  const sort = numeric(left.order) - numeric(right.order);
+  if (sort !== 0) return sort;
+  return left.id.localeCompare(right.id);
+}
+
+export function rawId(raw: RawRecord, fallback: string) {
+  return typeof raw.id === 'string' && raw.id ? raw.id : fallback;
+}
+
+export function stringField(
+  raw: RawRecord | undefined,
+  key: string,
+): string | undefined {
+  const value = raw?.[key];
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+export function displayRecord(
+  raw: RawRecord | undefined,
+): RawRecord | undefined {
+  const display = raw?.display;
+  return display && typeof display === 'object' && !Array.isArray(display)
+    ? (display as RawRecord)
+    : undefined;
+}
+
+export function urlSafeSlug(value: string): string {
+  return value
+    .trim()
+    .replaceAll('\\', '/')
+    .split('/')
+    .filter(Boolean)
+    .join('-')
+    .replace(/:/g, '-')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+}
+
+export function macrosFrom(
+  raw: RawRecord | undefined,
+): Record<string, string> | undefined {
+  if (!raw?.macros || typeof raw.macros !== 'object') return undefined;
+  const entries = Object.entries(raw.macros as RawRecord).filter(
+    (entry): entry is [string, string] => typeof entry[1] === 'string',
+  );
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
+export function asCover(value: unknown): TaggedReference | null {
+  return asTaggedReference(value) ?? null;
+}
+
+export function asLanding(value: unknown): DumpText[] {
+  return asDumpTextList(value) ?? [];
+}
+
+export function categoryMatches(
+  categoryId: string,
+  entryCategory: string | undefined,
+) {
+  if (!entryCategory) return false;
+  return bareId(entryCategory) === bareId(categoryId);
+}
+

package/src/lib/books.ts

@@ -0,0 +1,31 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
+import { listClientGuideBookSummaries } from '@terrafirmagreg-team/guide/lib/client/guides';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+type GuideBookSummary = Awaited<
+  ReturnType<typeof listClientGuideBookSummaries>
+>[number];
+
+function orderGuideBooks<T extends { bookId: string }>(
+  books: T[],
+  order: readonly string[] | undefined,
+): T[] {
+  if (!order?.length) return books;
+  const rank = new Map(order.map((id, i) => [id, i]));
+  return [...books].sort(
+    (a, b) =>
+      (rank.get(a.bookId) ?? order.length) - (rank.get(b.bookId) ?? order.length) ||
+      a.bookId.localeCompare(b.bookId),
+  );
+}
+
+export function listGuideBooks(
+  dataset: DatasetRef,
+  lang: Lang,
+): Promise<GuideBookSummary[]> {
+  return listClientGuideBookSummaries(dataset, lang).then((books) =>
+    orderGuideBooks(books, sectionConfig().datasetConfig[dataset.id]?.guide?.bookOrder),
+  );
+}
+

package/src/lib/breadcrumb.ts

@@ -0,0 +1,56 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { guideBookHref, guideCategoryHref } from '@terrafirmagreg-team/guide/lib/paths';
+import type { GuideCategory, GuideIndex, GuidePageKind } from '@terrafirmagreg-team/guide/types';
+
+export function categoryMap(
+  categories: GuideCategory[],
+): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const cat of categories) {
+    for (const entry of cat.entries) {
+      map.set(entry.id, cat.id);
+    }
+  }
+  return map;
+}
+
+export function guideBreadcrumbItems({
+  kind,
+  title,
+  dataset,
+  modId,
+  bookPath,
+  overview,
+  categoryId,
+}: {
+  kind: GuidePageKind;
+  title: string;
+  dataset: DatasetRef;
+  modId?: string;
+  bookPath?: string;
+  overview: GuideIndex | undefined;
+  categoryId?: string;
+}): Array<{ name: string; url?: string }> {
+  if (kind === 'pack') return [];
+  const bookName = overview?.book?.name ?? bookPath ?? '';
+  const bookHref =
+    modId && bookPath
+      ? guideBookHref(dataset, undefined, modId, bookPath)
+      : undefined;
+  if (kind === 'overview') return [];
+  const items: Array<{ name: string; url?: string }> = [];
+  if (bookName && bookHref) items.push({ name: bookName, url: bookHref });
+  const cat = overview?.categories.find((entry) => entry.id === categoryId);
+  if (cat && modId && bookPath) {
+    items.push({
+      name: cat.name,
+      url:
+        kind === 'entry'
+          ? guideCategoryHref(dataset, undefined, modId, bookPath, cat)
+          : undefined,
+    });
+  }
+  items.push({ name: title });
+  return items;
+}
+

package/src/lib/client/guides.ts

@@ -0,0 +1,262 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { asRecord, asString } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { joinDumpRel } from '@terrafirmagreg-team/dump/lib/dump/paths';
+import { bareId } from '@terrafirmagreg-team/guide/lib/paths';
+import type { GuideEntry } from '@terrafirmagreg-team/guide/types';
+import type { GuideMultiblock } from '@terrafirmagreg-team/guide/lib/data/dto';
+import type {
+  GuideBookJson,
+  GuideBookRef,
+} from '@terrafirmagreg-team/guide/lib/data/dto';
+import {
+  bookSlug,
+  indexBookRows,
+  toBook,
+  type BookRows,
+} from '@terrafirmagreg-team/guide/lib/book';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { GuideIndex } from '@terrafirmagreg-team/guide/types';
+import {
+  clientDumpJson,
+  clientDumpLang,
+  clientDumpLangRaw,
+} from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { loadDatasetDump } from '@terrafirmagreg-team/dump/lib/dump/mods/load';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+type BookRow = {
+  ref: GuideBookRef;
+  slug: string;
+  raw?: GuideBookJson;
+};
+
+const listedBookRows = createDatasetCache(
+  async (dataset: DatasetRef): Promise<BookRow[]> => {
+    const dump = await loadDatasetDump(dataset);
+    if (!dump) return [];
+    const raws = await Promise.all(
+      dump.mods.flatMap((mod) =>
+        mod.books.map(async (ref) => ({
+          ref,
+          raw: asRecord(
+            await clientDumpJson(dataset, `${ref.dir}/book.json`),
+          ) as GuideBookJson | undefined,
+        })),
+      ),
+    );
+    const rows: BookRow[] = [];
+    const taken = new Set<string>();
+    for (const { ref, raw } of raws) {
+      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);
+      rows.push({ ref, slug, raw });
+    }
+    return rows;
+  },
+);
+
+function listedBodies(
+  bookDir: string,
+  index: Record<string, unknown> | undefined,
+): { files: string[]; ids: string[] } {
+  const files: string[] = [];
+  const ids: string[] = [];
+  const seen = new Set<string>();
+  for (const [id, value] of Object.entries(index ?? {})) {
+    if (!id || typeof value !== 'string' || !value) continue;
+    const rel = joinDumpRel(`${bookDir}/x`, value);
+    if (!rel) continue;
+    ids.push(id);
+    if (!seen.has(rel)) {
+      seen.add(rel);
+      files.push(rel);
+    }
+  }
+  return { files, ids };
+}
+
+async function bookRows(
+  dataset: DatasetRef,
+  row: BookRow,
+  lang: Lang,
+): Promise<BookRows | null> {
+  if (!row.raw) return null;
+  const bookDir = row.ref.dir;
+  const listed = row.raw as Record<string, unknown>;
+  const entryList = listedBodies(
+    bookDir,
+    listed.entries as Record<string, unknown> | undefined,
+  );
+  const categoryList = listedBodies(
+    bookDir,
+    listed.categories as Record<string, unknown> | undefined,
+  );
+  const bucketDocs = new Map<string, Record<string, unknown>>();
+  const categoryDocs = new Map<string, Record<string, unknown>>();
+  await Promise.all([
+    ...entryList.files.map(async (rel) => {
+      const doc = asRecord(await clientDumpJson(dataset, rel));
+      if (doc) bucketDocs.set(rel, doc);
+    }),
+    ...categoryList.files.map(async (rel) => {
+      const doc = asRecord(await clientDumpJson(dataset, rel));
+      if (doc) categoryDocs.set(rel, doc);
+    }),
+  ]);
+  const entries: BookRows['entries'] = [];
+  for (const [id, value] of Object.entries(
+    (listed.entries as Record<string, unknown> | undefined) ?? {},
+  )) {
+    if (!id || typeof value !== 'string' || !value) continue;
+    const rel = joinDumpRel(`${bookDir}/x`, value);
+    const body = rel ? bucketDocs.get(rel)?.[id] : undefined;
+    if (body && typeof body === 'object' && !Array.isArray(body)) {
+      entries.push({ id, raw: body as Record<string, unknown> });
+    }
+  }
+  entries.sort((a, b) => a.id.localeCompare(b.id));
+  const categories: BookRows['categories'] = [];
+  for (const [id, value] of Object.entries(
+    (listed.categories as Record<string, unknown> | undefined) ?? {},
+  )) {
+    if (!id || typeof value !== 'string' || !value) continue;
+    const rel = joinDumpRel(`${bookDir}/x`, value);
+    const raw = rel ? categoryDocs.get(rel) : undefined;
+    if (raw) categories.push({ id, raw });
+  }
+  categories.sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    ref: row.ref,
+    slug: row.slug,
+    raw: row.raw,
+    entries,
+    categories,
+    contentLanguage: lang,
+    isFallback: false,
+  };
+}
+
+export const loadClientGuideBook = createDatasetCache(
+  async (
+    dataset: DatasetRef,
+    lang: Lang,
+    bookSlugValue: string,
+  ): Promise<GuideIndex | null> => {
+    const row = (await listedBookRows(dataset)).find(
+      (entry) =>
+        entry.slug === bookSlugValue || entry.ref.bookId === bookSlugValue,
+    );
+    if (!row) return null;
+    const [rows, langMap, rawLang] = await Promise.all([
+      bookRows(dataset, row, lang),
+      clientDumpLang(dataset, lang),
+      clientDumpLangRaw(dataset, lang),
+    ]);
+    if (!rows) return null;
+    return indexBookRows(rows, dataset, lang, langMap, rawLang);
+  },
+  (dataset, lang, bookSlugValue) => `${dataset.id}/${dataset.version ?? ''}${lang}${bookSlugValue}`,
+);
+
+export type ClientGuideEntryHit = {
+  entry: GuideEntry;
+  modId?: string;
+  bookPath?: string;
+};
+
+export async function findClientGuideEntry(
+  dataset: DatasetRef,
+  lang: Lang,
+  entryId: string,
+): Promise<ClientGuideEntryHit | undefined> {
+  const needle = bareId(entryId);
+  const nameNeedle = entryId.trim().toLowerCase();
+  for (const row of await listedBookRows(dataset)) {
+    const entries = (row.raw as Record<string, unknown> | undefined)?.entries;
+    const overview = await loadClientGuideBook(dataset, lang, row.slug);
+    const match =
+      entries && typeof entries === 'object'
+        ? Object.keys(entries).find(
+            (key) => bareId(key) === needle || key === entryId,
+          )
+        : undefined;
+    const entry = overview?.entries.find(
+      (item) =>
+        item.id === match ||
+        bareId(item.id) === needle ||
+        item.name?.trim().toLowerCase() === nameNeedle,
+    );
+    if (entry) {
+      return {
+        entry,
+        modId: overview?.modId,
+        bookPath: overview?.bookPath,
+      };
+    }
+  }
+  return undefined;
+}
+
+export const loadMultiblockNameIndex = createDatasetCache(
+  async (
+    dataset: DatasetRef,
+    lang: Lang,
+  ): Promise<Record<string, GuideMultiblock>> => {
+    const index: Record<string, GuideMultiblock> = {};
+    const put = (key: string | undefined, spec: GuideMultiblock) => {
+      const normalized = key?.trim().toLowerCase();
+      if (normalized) index[normalized] ??= spec;
+    };
+    for (const row of await listedBookRows(dataset)) {
+      const overview = await loadClientGuideBook(dataset, lang, row.slug);
+      for (const entry of overview?.entries ?? []) {
+        for (const page of entry.pages ?? []) {
+          const spec = page?.multiblock;
+          if (!spec) continue;
+          const display = asRecord(
+            (page as Record<string, unknown>).display,
+          );
+          put(asString(display?.name) ?? page.name ?? page.title, spec);
+          put(entry.id, spec);
+          put(entry.name, spec);
+        }
+      }
+    }
+    return index;
+  },
+);
+
+export async function listClientGuideBookSummaries(
+  dataset: DatasetRef,
+  lang: Lang,
+): Promise<
+  Array<{
+    modId: string;
+    bookId: string;
+    slug: string;
+    name: string;
+    landingText?: string;
+  }>
+> {
+  const langMap = await clientDumpLang(dataset, lang);
+  const rows = await listedBookRows(dataset);
+  return rows
+    .map((row) => {
+      const book = toBook(row.raw, row.ref, row.slug, langMap);
+      return {
+        modId: row.ref.modId,
+        bookId: row.ref.bookId,
+        slug: row.slug,
+        name: book.name,
+        ...(book.landingText ? { landingText: book.landingText } : {}),
+      };
+    })
+    .sort((a, b) => a.bookId.localeCompare(b.bookId));
+}
+

package/src/lib/client-payload/extras.ts

@@ -0,0 +1,103 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { stackDisplayName } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+import { loadClientModAtlases } from '@terrafirmagreg-team/dump/lib/dump/client/atlases';
+import { loadClientKeybinds } from '@terrafirmagreg-team/dump/lib/dump/client/keybinds';
+import { guideEmbeds } from '@terrafirmagreg-team/guide/lib/embeds';
+import { loadClientRegistry } from '@terrafirmagreg-team/dump/lib/dump/client/registry';
+import { parseStackId } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { spriteIdsFromEntry } from '@terrafirmagreg-team/guide/lib/sprites';
+import { recipeIds } from '@terrafirmagreg-team/guide/lib/recipe';
+import { asMultiblock } from '@terrafirmagreg-team/guide/lib/meta';
+import { glbFor } from '@terrafirmagreg-team/guide/lib/multiblock/url';
+import { multiblockKey } from '@terrafirmagreg-team/guide/lib/multiblock';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { GuideEntry, GuideEntryExtras } from '@terrafirmagreg-team/guide/types';
+import { type QuestLinks, collectPageLinks } from './links';
+
+export async function entryExtras(
+  dataset: DatasetRef,
+  lang: Lang,
+  langMap: Record<string, string>,
+  bookModId: string,
+  bookPath: string,
+  categoryByEntry: Map<string, string>,
+  questLinks: QuestLinks,
+  hrefs: Set<string>,
+  entry: GuideEntry,
+): Promise<GuideEntryExtras> {
+  const pages = entry.pages ?? [];
+  const recipes: GuideEntryExtras['recipes'] = {};
+  const entities: GuideEntryExtras['entities'] = {};
+  const entityNames: GuideEntryExtras['entityNames'] = {};
+  const glbs: GuideEntryExtras['glbs'] = {};
+  const registry = await loadClientRegistry(dataset, 'entities');
+
+  await Promise.all(
+    pages.map(async (page) => {
+      await Promise.all(
+        recipeIds(page).map(async (id) => {
+          const recipe = await guideEmbeds().recipe?.load(dataset, id);
+          if (recipe) recipes[id] = recipe;
+        }),
+      );
+      const entityId =
+        typeof page.entity === 'string' ? page.entity : undefined;
+      if (entityId) {
+        entityNames[entityId] = stackDisplayName(
+          langMap,
+          entityId,
+          'entity',
+          registry.get(entityId)?.display?.name,
+        );
+        const parsed = parseStackId(entityId);
+        const record = parsed?.id ? registry.get(parsed.id) : undefined;
+        if (parsed?.id && record) entities[parsed.id] = record;
+      }
+      await collectPageLinks(
+        dataset,
+        lang,
+        bookModId,
+        bookPath,
+        categoryByEntry,
+        questLinks,
+        hrefs,
+        page,
+      );
+      await Promise.all(
+        [asMultiblock(page.model ?? page.multiblock), ...(page.multiblocks ?? []).map(asMultiblock)].map(
+          async (spec) => {
+            const key = multiblockKey(spec);
+            if (!key || glbs[key]) return;
+            const url = await glbFor(dataset, bookModId, spec);
+            if (url) glbs[key] = url;
+          },
+        ),
+      );
+    }),
+  );
+
+  const spriteIds = spriteIdsFromEntry(entry);
+  const atlasMods = [
+    ...new Set(
+      spriteIds
+        .map((id) => id.replace(/^#/, '').split(':', 2)[0])
+        .filter(Boolean),
+    ),
+  ];
+  const atlasEntries = await Promise.all(
+    atlasMods.map(
+      async (modId) =>
+        [modId, await loadClientModAtlases(dataset, modId)] as const,
+    ),
+  );
+
+  return {
+    atlases: Object.fromEntries(atlasEntries),
+    keybinds: await loadClientKeybinds(dataset),
+    recipes,
+    entities,
+    entityNames,
+    glbs,
+  };
+}
+