@terrafirmagreg-team/guide 0.0.0-stage → 0.1.0

package/src/lib/paths.ts

@@ -0,0 +1,52 @@
+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: string,
+  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: string,
+  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,33 @@
+import { registerPreviewResolver } from '@terrafirmagreg-team/kit/lib/preview';
+import { loadClientGuideBook } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { entryPreviewIcon } from '@terrafirmagreg-team/game/lib/preview';
+import type { PreviewResolverCtx } from '@terrafirmagreg-team/kit/lib/preview';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+
+export async function guideLinkPreview({
+  parts,
+  query,
+  lang,
+}: PreviewResolverCtx): Promise<PagePreviewData | undefined> {
+  const dataset = parts[1];
+  const bookId = query.get('book');
+  if (!dataset || !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,28 @@
+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,30 @@
+import type { GuidePage } from '@terrafirmagreg-team/guide/types';
+import type { Recipe } from '@terrafirmagreg-team/recipe/lib/data/dto';
+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: Recipe,
+): 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,40 @@
+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 { recipeHref } from '@terrafirmagreg-team/recipe/lib/links';
+import { questHref } from '@terrafirmagreg-team/quest/lib/links';
+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) ??
+        recipeHref(context.dataset, undefined, { id: reference.id });
+      return { ...reference, href, available: Boolean(href) };
+    }
+    case 'quest': {
+      const hit = context.questLinks?.[reference.id];
+      const href = hit
+        ? questHref(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,17 @@
+import { registerSearchHitFilter } from '@terrafirmagreg-team/kit/lib/search';
+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,156 @@
+import type { AdvancedIndex } from 'fumadocs-core/search/server';
+import { dumpTextString, langString } from '@terrafirmagreg-team/game/lib/dump/assets/lang/names';
+import { isIndexPage } from '@terrafirmagreg-team/guide/lib/page-kind';
+import type { DumpIndex } from '@terrafirmagreg-team/game/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 resolveText(
+  map: Record<string, string>,
+  node: unknown,
+): string | undefined {
+  if (typeof node === 'string') {
+    const bare =
+      node.startsWith('{') && node.endsWith('}')
+        ? node.slice(1, -1).trim()
+        : undefined;
+    return langString(map, node) ?? bare ?? (bare ? undefined : node);
+  }
+  if (Array.isArray(node)) {
+    const parts = node
+      .map((item) => resolveText(map, item))
+      .filter((part): part is string => Boolean(part));
+    return parts.length ? parts.join('\n') : undefined;
+  }
+  if (node && typeof node === 'object') {
+    return dumpTextString(map, node as DumpTextNode) || 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>;
+}
+
+function entryIndex(
+  dataset: string,
+  bookId: string,
+  entryId: string,
+  entry: RawEntry,
+  map: Record<string, string>,
+  lang: string,
+) {
+  const title =
+    resolveText(map, entry.display?.name) ?? entryId.split('/').pop() ?? entryId;
+  const contents = (entry.pages ?? [])
+    .map((page) => {
+      if (isIndexPage(page, map)) return null;
+      const heading = resolveText(map, page.title);
+      const content = resolveText(map, page.texts);
+      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;
+  return {
+    title,
+    url: `/guide/${dataset}?book=${bookId}&entry=${entryId}`,
+    id: `guide:${dataset}:${bookId}:${entryId}:${lang}`,
+    tag: `guide:${dataset}`,
+    locale: lang,
+    structuredData: { headings: [], contents },
+  };
+}
+
+async function bookIndexes(
+  dataset: string,
+  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,
+      );
+      if (index) out.push(index);
+    }
+  }
+  return out;
+}
+
+export async function guideSearchIndexes(
+  dataset: string,
+  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,17 @@
+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,10 @@
+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,137 @@
+import type { TOCItemType } from 'fumadocs-core/toc';
+import type { TaggedReference } from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import { langString } from '@terrafirmagreg-team/game/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/lib/tree/children.ts

@@ -0,0 +1,70 @@
+import { createElement } from 'react';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
+import { encodeQueryValue } from '@terrafirmagreg-team/translate/lib/url';
+import { sectionUrl } from '@terrafirmagreg-team/kit/lib/location';
+import { bookOptionId, guideCategoryHref } from '@terrafirmagreg-team/guide/lib/paths';
+import type { GuideIndex } from '@terrafirmagreg-team/guide/types';
+import type { TaggedReference } from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+
+function nodeIcon(
+  dataset: string,
+  icon: TaggedReference | undefined,
+  name: string,
+): React.ReactNode {
+  if (!icon?.id) 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: icon.id,
+      kind: icon.kind,
+      name,
+      size: 14,
+      href: false,
+      tooltip: false,
+      missing: 'hide',
+    }),
+  );
+}
+
+export function guideTreeChildren(
+  dataset: string,
+  index: GuideIndex,
+): PageTree.Node[] {
+  const bookId =
+    index.bookId ??
+    (index.modId && index.bookPath
+      ? bookOptionId(index.modId, index.bookPath)
+      : undefined);
+  return index.categories.map((category): PageTree.Folder => ({
+    type: 'folder',
+    name: category.name,
+    icon: nodeIcon(dataset, category.icon, category.name),
+    index: {
+      type: 'page',
+      name: category.name,
+      url: guideCategoryHref(
+        dataset,
+        undefined,
+        index.modId,
+        index.bookPath ?? '',
+        category,
+      ),
+      $id: `${dataset}/${index.modId}/${index.bookPath}/${category.id}#index`,
+    },
+    $id: `${dataset}/${index.modId}/${index.bookPath}/${category.id}`,
+    children: category.entries.map((entry): PageTree.Item => ({
+      type: 'page',
+      name: entry.name,
+      url: `${sectionUrl('guide', dataset)}?book=${encodeQueryValue(bookId ?? '')}&entry=${encodeQueryValue(entry.id)}`,
+      icon: nodeIcon(dataset, entry.icon, entry.name),
+      $id: `${dataset}/${index.modId}/${index.bookPath}/${category.id}/${entry.id}`,
+    })),
+  }));
+}