@terrafirmagreg-team/guide 0.0.0-stage → 1.2.0

package/src/lib/paths.ts

@@ -0,0 +1,54 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { GuideCategoryRef } from '@terrafirmagreg-team/guide/types';
+import { guideHref as guideQueryHref } from '@terrafirmagreg-team/guide/lib/links';
+
+export function bareId(id: string): string {
+  const trimmed = id.replace(/^\/+|\/+$/g, '');
+  return trimmed.includes(':')
+    ? trimmed.slice(trimmed.indexOf(':') + 1)
+    : trimmed;
+}
+
+export function bookOptionId(modId: string, bookPath: string): string {
+  return `${modId}:${bookPath}`;
+}
+
+export function guideBookHref(
+  dataset: DatasetRef,
+  lang: Lang | undefined,
+  modId?: string,
+  bookPath?: string,
+  entryId?: string,
+  hash?: string,
+  categoryId?: string,
+): string {
+  const bookId = modId && bookPath ? bookOptionId(modId, bookPath) : undefined;
+  return guideQueryHref(dataset, lang, bookId, entryId, hash, categoryId);
+}
+
+export function guideCategoryHref(
+  dataset: DatasetRef,
+  lang: Lang | undefined,
+  modId: string,
+  bookPath: string,
+  category: { id: string },
+): string {
+  return guideBookHref(
+    dataset,
+    lang,
+    modId,
+    bookPath,
+    undefined,
+    undefined,
+    category.id,
+  );
+}
+
+export function isRootCategory(
+  _category: GuideCategoryRef,
+  _all: GuideCategoryRef[],
+): boolean {
+  return true;
+}
+

package/src/lib/preview.ts

@@ -0,0 +1,37 @@
+import { registerPreviewResolver } from '@terrafirmagreg-team/preview/lib';
+import { loadClientGuideBook } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { entryPreviewIcon } from '@terrafirmagreg-team/game/lib/preview';
+import type { PreviewResolverCtx } from '@terrafirmagreg-team/preview/lib';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+
+export async function guideLinkPreview({
+  parts,
+  query,
+  lang,
+}: PreviewResolverCtx): Promise<PagePreviewData | undefined> {
+  const dataset = {
+    id: parts[1] ?? '',
+    version: query.get('version') ?? undefined,
+  };
+  const bookId = query.get('book');
+  if (!dataset.id || !bookId) return undefined;
+  const index = await loadClientGuideBook(dataset, lang, bookId);
+  if (!index) return undefined;
+  const entryId = query.get('entry');
+  if (entryId) {
+    const entry = index.entries.find((row) => row.id === entryId);
+    if (!entry) return undefined;
+    return {
+      title: entry.name ?? entry.id,
+      icon: entryPreviewIcon(entry.icon, dataset),
+    };
+  }
+  return {
+    title: index.book?.name ?? bookId,
+    description: index.book?.landingText,
+    icon: entryPreviewIcon(index.book?.cover ?? undefined, dataset),
+  };
+}
+
+registerPreviewResolver('guide', guideLinkPreview);
+

package/src/lib/query.ts

@@ -0,0 +1,29 @@
+import type { GuideIndex } from '@terrafirmagreg-team/guide/types';
+
+type GuideQuery = {
+  bookId?: string;
+  entryId?: string;
+  categoryId?: string;
+};
+
+export function guideQueryFromParams(params: {
+  get(name: string): string | null;
+}): GuideQuery {
+  const book = params.get('book') ?? undefined;
+  const entry = params.get('entry') ?? undefined;
+  const category = params.get('cat') ?? undefined;
+  return {
+    ...(book ? { bookId: book } : {}),
+    ...(entry ? { entryId: entry } : {}),
+    ...(category ? { categoryId: category } : {}),
+  };
+}
+
+export function firstGuideEntryId(index: GuideIndex): string | undefined {
+  return (
+    index.categories.flatMap((category) =>
+      category.entries.map((entry) => entry.id),
+    )[0] ?? index.entries[0]?.id
+  );
+}
+

package/src/lib/recipe.ts

@@ -0,0 +1,31 @@
+import type { GuidePage } from '@terrafirmagreg-team/guide/types';
+import type { EmbedRecipe } from '@terrafirmagreg-team/guide/lib/embeds';
+import { stackDisplayName } from '@terrafirmagreg-team/game/lib/entry/display';
+
+export function recipeIds(page: GuidePage): string[] {
+  return (page.recipes ?? []).filter(
+    (id): id is string => typeof id === 'string' && Boolean(id),
+  );
+}
+
+export function recipeNameScope(
+  langMap: Record<string, string>,
+  recipe: EmbedRecipe,
+): Record<string, string> {
+  const ids = new Set<string>([recipe.id]);
+  for (const ing of [...recipe.inputs, ...recipe.outputs]) ids.add(ing.id);
+  for (const fill of Object.values(recipe.slots ?? {})) {
+    ids.add(fill.id);
+    for (const alt of fill.alternatives ?? []) ids.add(alt.id);
+  }
+  for (const widget of recipe.widgets ?? []) {
+    if (widget.type === 'slot') {
+      ids.add(widget.id);
+      for (const alt of widget.alternatives ?? []) ids.add(alt);
+    }
+  }
+  const names: Record<string, string> = { ...langMap };
+  for (const id of ids) names[id] = stackDisplayName(langMap, id);
+  return names;
+}
+

package/src/lib/reference/index.ts

@@ -0,0 +1,41 @@
+import {
+  parseGuideReference,
+  resolveGuideReference,
+} from '@terrafirmagreg-team/guide/lib/reference/resolver';
+import type {
+  GuideReferenceContext,
+  PageRendererProps,
+} from '@terrafirmagreg-team/guide/types';
+
+export function referenceHref(
+  props: PageRendererProps,
+  target: string,
+): { href: string; external: boolean } | null {
+  if (/^https?:\/\//i.test(target)) return { href: target, external: true };
+  const reference = resolveGuideReference(parseGuideReference(target), {
+    dataset: props.dataset,
+    lang: props.lang,
+    modId: props.bookModId,
+    bookPath: props.bookPath,
+    categoryByEntry: props.categoryByEntry,
+    questLinks: props.questLinks,
+  });
+  return reference.href && reference.available
+    ? { href: reference.href, external: false }
+    : null;
+}
+
+export function guideLink(
+  node: { link?: string },
+  ctx: GuideReferenceContext,
+): { href: string | undefined; external: boolean } {
+  const target = node.link;
+  if (!target) return { href: undefined, external: false };
+  if (/^https?:\/\//i.test(target)) return { href: target, external: true };
+  const resolved = resolveGuideReference(parseGuideReference(target), ctx);
+  return {
+    href: resolved.available ? resolved.href : undefined,
+    external: false,
+  };
+}
+

package/src/lib/reference/resolver.ts

@@ -0,0 +1,88 @@
+import { guideEmbeds } from '@terrafirmagreg-team/guide/lib/embeds';
+import {
+  bareId,
+  guideBookHref,
+} from '@terrafirmagreg-team/guide/lib/paths';
+import type {
+  GuideReference,
+  GuideReferenceContext,
+  ResolvedGuideReference,
+} from '@terrafirmagreg-team/guide/types';
+
+export function parseGuideReference(target: string): GuideReference {
+  const [rawId, anchor] = target.replace(/\.json$/i, '').split('#', 2);
+  const [prefix, ...rest] = rawId.split(':');
+  if ((prefix === 'recipe' || prefix === 'quest') && rest.length) {
+    return { kind: prefix, id: rest.join(':'), anchor };
+  }
+  return { kind: 'guide', id: rawId.replace(/^guide:/, ''), anchor };
+}
+
+export function matchGuideEntryKey(
+  ids: Iterable<string>,
+  query: string,
+): string | undefined {
+  const keys = ids instanceof Set ? ids : new Set(ids);
+  if (keys.has(query)) return query;
+  const bare = bareId(query);
+  for (const key of keys) {
+    if (bareId(key) === bare) return key;
+  }
+  return undefined;
+}
+
+export function resolveGuideReference(
+  reference: GuideReference,
+  context: GuideReferenceContext,
+): ResolvedGuideReference {
+  switch (reference.kind) {
+    case 'guide': {
+      const entryId = matchGuideEntryKey(
+        context.categoryByEntry.keys(),
+        reference.id,
+      );
+      return {
+        ...reference,
+        href: entryId
+          ? guideBookHref(
+              context.dataset,
+              undefined,
+              context.modId,
+              context.bookPath,
+              entryId,
+              reference.anchor,
+            )
+          : guideBookHref(
+              context.dataset,
+              undefined,
+              context.modId,
+              context.bookPath,
+              bareId(reference.id),
+              reference.anchor,
+            ),
+        available: Boolean(entryId ?? reference.id),
+      };
+    }
+    case 'recipe': {
+      const href =
+        context.targets?.recipe?.(reference.id) ??
+        guideEmbeds().recipe?.href(context.dataset, undefined, { id: reference.id });
+      return { ...reference, href, available: Boolean(href) };
+    }
+    case 'quest': {
+      const hit = context.questLinks?.[reference.id];
+      const href = hit
+        ? guideEmbeds().quest?.href(context.dataset, undefined, {
+            category: hit.filename,
+            id: hit.questId,
+          })
+        : context.targets?.quest?.(reference.id);
+      return { ...reference, href, available: Boolean(href) };
+    }
+    default: {
+      const _exhaustive: never = reference.kind;
+      return _exhaustive;
+    }
+  }
+}
+

package/src/lib/search/filter.ts

@@ -0,0 +1,18 @@
+import { registerSearchHitFilter } from '@terrafirmagreg-team/search/lib';
+import type { SortedResult } from '@terrafirmagreg-team/ui/types/search';
+
+export function guideHitFilter(
+  params: URLSearchParams,
+): ((hit: SortedResult) => boolean) | undefined {
+  const book = params.get('book');
+  if (!book) return undefined;
+  return (hit) => {
+    const queryString = hit.url.split('?')[1];
+    if (!queryString) return true;
+    const docBook = new URLSearchParams(queryString).get('book');
+    return docBook === null || docBook === book;
+  };
+}
+
+registerSearchHitFilter('guide', guideHitFilter);
+

package/src/lib/search/index.ts

@@ -0,0 +1,183 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { AdvancedIndex } from 'fumadocs-core/search/server';
+import { dumpTextString, langString } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+import { formatGuide } from '@terrafirmagreg-team/guide/lib/format';
+import { isIndexPage } from '@terrafirmagreg-team/guide/lib/page-kind';
+import type { DumpIndex } from '@terrafirmagreg-team/dump/lib/dump/mods/dto';
+
+export type GuideIndex = AdvancedIndex & { locale: string };
+
+export interface DumpSource {
+  getJson(rel: string): Promise<unknown | undefined>;
+  getLang(lang: string): Promise<Record<string, string>>;
+}
+
+type DumpTextNode = Parameters<typeof dumpTextString>[1];
+
+function plainText(raw: string, macros?: Record<string, string>): string {
+  let out = '';
+  for (const node of formatGuide(raw, { macros })) {
+    if (node.type === 'break') out += '\n';
+    else out += (node.type === 'command' ? node.label : undefined) ?? node.value;
+  }
+  return out
+    .replace(/\s*\$\([^)]*$/, '')
+    .replace(/[ \t]*\n[ \t]*/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function resolveText(
+  map: Record<string, string>,
+  node: unknown,
+  macros?: Record<string, string>,
+): string | undefined {
+  if (typeof node === 'string') {
+    const bare =
+      node.startsWith('{') && node.endsWith('}')
+        ? node.slice(1, -1).trim()
+        : undefined;
+    const resolved = langString(map, node) ?? bare ?? (bare ? undefined : node);
+    return resolved ? plainText(resolved, macros) || undefined : undefined;
+  }
+  if (Array.isArray(node)) {
+    const parts = node
+      .map((item) => resolveText(map, item, macros))
+      .filter((part): part is string => Boolean(part));
+    return parts.length ? parts.join('\n') : undefined;
+  }
+  if (node && typeof node === 'object') {
+    const resolved = dumpTextString(map, node as DumpTextNode);
+    return resolved ? plainText(resolved, macros) || undefined : undefined;
+  }
+  return undefined;
+}
+
+interface RawPage {
+  anchor?: unknown;
+  title?: unknown;
+  texts?: unknown;
+}
+
+interface RawEntry {
+  display?: { name?: unknown };
+  pages?: RawPage[];
+}
+
+interface RawBook {
+  id?: unknown;
+  entries?: Record<string, string>;
+  macros?: Record<string, string>;
+}
+
+function entryIndex(
+  dataset: DatasetRef,
+  bookId: string,
+  entryId: string,
+  entry: RawEntry,
+  map: Record<string, string>,
+  lang: string,
+  macros?: Record<string, string>,
+) {
+  const title =
+    resolveText(map, entry.display?.name, macros) ??
+    entryId.split('/').pop() ??
+    entryId;
+  const contents = (entry.pages ?? [])
+    .map((page) => {
+      if (isIndexPage(page, map)) return null;
+      const heading = resolveText(map, page.title, macros);
+      const content = resolveText(map, page.texts, macros);
+      return content ? { heading: heading ?? title, content } : null;
+    })
+    .filter((c): c is { heading: string; content: string } => c !== null);
+  const body = contents.map((c) => c.content).join('\n');
+  if (!body && !title) return null;
+  const params = new URLSearchParams({ book: bookId, entry: entryId });
+  if (dataset.version) params.set('version', dataset.version);
+  const refKey = `${dataset.id}/${dataset.version ?? ''}`;
+  return {
+    title,
+    url: `/guide/${dataset.id}?${params}`,
+    id: `guide:${refKey}:${bookId}:${entryId}:${lang}`,
+    tag: `guide:${refKey}`,
+    locale: lang,
+    structuredData: { headings: [], contents },
+  };
+}
+
+async function bookIndexes(
+  dataset: DatasetRef,
+  dir: string,
+  bookId: string,
+  langs: string[],
+  source: DumpSource,
+): Promise<GuideIndex[]> {
+  const book = (await source.getJson(`${dir}/book.json`)) as
+    | RawBook
+    | undefined;
+  const buckets = book?.entries;
+  if (!buckets || typeof buckets !== 'object') return [];
+  const maps = new Map(
+    await Promise.all(
+      langs.map(
+        async (lang) => [lang, await source.getLang(lang)] as const,
+      ),
+    ),
+  );
+  const bucketDocs = new Map<string, Record<string, RawEntry> | undefined>();
+  await Promise.all(
+    [...new Set(Object.values(buckets))].map(async (rel) => {
+      bucketDocs.set(
+        rel,
+        (await source.getJson(`${dir}/${rel}`)) as
+          | Record<string, RawEntry>
+          | undefined,
+      );
+    }),
+  );
+  const out: GuideIndex[] = [];
+  for (const [entryId, rel] of Object.entries(buckets)) {
+    const entry = bucketDocs.get(rel)?.[entryId];
+    if (!entry) continue;
+    for (const lang of langs) {
+      const index = entryIndex(
+        dataset,
+        bookId,
+        entryId,
+        entry,
+        maps.get(lang) ?? {},
+        lang,
+        book.macros,
+      );
+      if (index) out.push(index);
+    }
+  }
+  return out;
+}
+
+export async function guideSearchIndexes(
+  dataset: DatasetRef,
+  dump: DumpIndex,
+  source: DumpSource,
+): Promise<GuideIndex[]> {
+  const langs = dump.manifest.languages?.length
+    ? dump.manifest.languages
+    : ['en_us'];
+  const out: GuideIndex[] = [];
+  for (const mod of dump.mods) {
+    for (const book of mod.books) {
+      out.push(
+        ...(await bookIndexes(dataset, book.dir, book.bookId, langs, source)),
+      );
+    }
+  }
+  const seen = new Set<string>();
+  return out.filter((index) => {
+    const key = `${index.locale}:${index.id}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+

package/src/lib/sprites.ts

@@ -0,0 +1,18 @@
+import { collectItemIds } from '@terrafirmagreg-team/guide/lib/data/parse';
+import type { GuideEntry } from '@terrafirmagreg-team/guide/types';
+
+export function spriteIdsFromEntry(entry: GuideEntry): string[] {
+  const ids: string[] = [];
+  if (entry.icon && entry.icon.kind !== 'texture') ids.push(entry.icon.id);
+  for (const page of entry.pages ?? []) {
+    ids.push(...collectItemIds(page.item), ...collectItemIds(page.icon));
+    if (typeof page.entity === 'string') ids.push(page.entity);
+    ids.push(
+      ...(page.recipes ?? []).filter(
+        (id): id is string => typeof id === 'string' && Boolean(id),
+      ),
+    );
+  }
+  return ids;
+}
+

package/src/lib/table.ts

@@ -0,0 +1,11 @@
+import type { GuideTableCell } from '@terrafirmagreg-team/guide/types';
+
+export function cssColor(value: string | undefined): string | undefined {
+  return value && /^0x[0-9a-f]{6}$/i.test(value) ? `#${value.slice(2)}` : value;
+}
+
+export function cellTexts(cell: GuideTableCell): string[] {
+  if (Array.isArray(cell.texts)) return cell.texts.filter(Boolean);
+  return typeof cell.text === 'string' && cell.text ? [cell.text] : [];
+}
+

package/src/lib/toc.ts

@@ -0,0 +1,138 @@
+import type { TOCItemType } from 'fumadocs-core/toc';
+import type { TaggedReference } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { langString } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+import { stackDisplayName } from '@terrafirmagreg-team/game/lib/entry/display';
+import {
+  classifyGuidePageType,
+  collectItemIds,
+  parseGuideIcon,
+  parseGuideItems,
+} from '@terrafirmagreg-team/guide/lib/data/parse';
+import type { GuidePage } from '@terrafirmagreg-team/guide/lib/data/dto';
+import { isIndexPage } from '@terrafirmagreg-team/guide/lib/page-kind';
+import type { GuideTocLabels } from '@terrafirmagreg-team/guide/types';
+
+function resourceIds(page: GuidePage): string[] {
+  return [
+    ...collectItemIds(page.item),
+    ...collectItemIds(page.icon),
+    page.entity,
+    ...(page.recipes ?? []),
+  ].filter((id): id is string => typeof id === 'string' && Boolean(id));
+}
+
+function localizedField(
+  map: Record<string, string>,
+  value: unknown,
+): string | undefined {
+  if (typeof value !== 'string' || !value) return undefined;
+  const resolved = langString(map, value);
+  if (resolved) return resolved;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.startsWith('{') && trimmed.endsWith('}')) return undefined;
+  return value;
+}
+
+function typeOf(page: GuidePage): string {
+  return (page.type ?? '').toLowerCase().trim();
+}
+
+export function pageTitle(
+  page: GuidePage,
+  langMap: Record<string, string> = {},
+  labels: GuideTocLabels = {},
+  entityNames?: Record<string, string>,
+): string | undefined {
+  const display =
+    page.display &&
+    typeof page.display === 'object' &&
+    !Array.isArray(page.display)
+      ? (page.display as Record<string, unknown>)
+      : undefined;
+  const fromFields =
+    localizedField(langMap, page.title) ??
+    localizedField(
+      langMap,
+      typeof display?.name === 'string' ? display.name : undefined,
+    ) ??
+    localizedField(langMap, page.name);
+  if (fromFields && fromFields !== page.entity) return fromFields;
+
+  const type = typeOf(page);
+  if (type === 'relations') return labels.related;
+  if (type === 'quest') return labels.objective;
+
+  for (const id of resourceIds(page)) {
+    const name = entityNames?.[id] ?? stackDisplayName(langMap, id);
+    if (name !== id) return name;
+  }
+  return undefined;
+}
+
+export function pageAnchor(
+  page: GuidePage,
+  index: number,
+  taken?: Set<string>,
+): string {
+  const anchor = typeof page.anchor === 'string' ? page.anchor.trim() : '';
+  if (anchor && !taken?.has(anchor)) {
+    taken?.add(anchor);
+    return anchor;
+  }
+  return `page-${index + 1}`;
+}
+
+export function pageAnchors(pages: GuidePage[] | undefined): string[] {
+  if (!pages?.length) return [];
+  const taken = new Set<string>();
+  return pages.map((page, i) => pageAnchor(page, i, taken));
+}
+
+export function pageIcon(page: GuidePage): TaggedReference | undefined {
+  return pageIcons(page)[0];
+}
+
+export function pageIcons(page: GuidePage): TaggedReference[] {
+  const kind = classifyGuidePageType(page.type);
+  if (kind === 'entity') return [];
+  const icon = parseGuideIcon(page.icon);
+  if (icon) return [icon];
+  return parseGuideItems(page.item);
+}
+
+export function guidePageTitles(
+  pages: GuidePage[] | undefined,
+  langMap: Record<string, string> = {},
+  labels: GuideTocLabels = {},
+  entityNames?: Record<string, string>,
+): (string | undefined)[] {
+  if (!pages?.length) return [];
+  return pages.map((page) =>
+    isIndexPage(page, langMap)
+      ? undefined
+      : pageTitle(page, langMap, labels, entityNames),
+  );
+}
+
+export function repeatedTitle(
+  titles: (string | undefined)[],
+  index: number,
+): boolean {
+  return index > 0 && titles[index] !== undefined && titles[index] === titles[index - 1];
+}
+
+export function guideToc(
+  pages: GuidePage[] | undefined,
+  langMap: Record<string, string> = {},
+  labels: GuideTocLabels = {},
+  entityNames?: Record<string, string>,
+): TOCItemType[] {
+  const titles = guidePageTitles(pages, langMap, labels, entityNames);
+  const anchors = pageAnchors(pages);
+  return titles.flatMap((title, i) => {
+    if (!title || repeatedTitle(titles, i)) return [];
+    return [{ title, url: `#${anchors[i]}`, depth: 2 }];
+  });
+}
+

package/src/locales/en_us.json

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

package/src/locales/ru_ru.json

@@ -0,0 +1,14 @@
+{
+  "Entity preview unavailable(guide.entity_unavailable)": "Превью сущности недоступно",
+  "Entry not found(guide.entry_missing)": "Запись не найдена",
+  "Gameplay guide(sections.desc.guide)": "Игровой гайд",
+  "Guide(sections.guide)": "Гайды",
+  "No recipes(guide.recipe_empty)": "Нет рецептов",
+  "Objective(guide.objective)": "Задача",
+  "Open(guide.link)": "Открыть",
+  "Quest(guide.quest)": "Квест",
+  "Related(guide.related)": "Связанное",
+  "Select book(ui.select_book)": "Выберите книгу",
+  "{count} entries(guide.entry_count)": "Записей: {count}",
+  "{count} pages(guide.page_count)": "Страниц: {count}"
+}