@terrafirmagreg-team/guide 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,112 @@
+import { loadClientGuideBook } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { uiConfig } from '@terrafirmagreg-team/ui/lib/config';
+import { categoryMap } from '@terrafirmagreg-team/guide/lib/breadcrumb';
+import { bareId, guideBookHref } from '@terrafirmagreg-team/guide/lib/paths';
+import { questHref } from '@terrafirmagreg-team/quest/lib/links';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type {
+  GuideMessages,
+  GuidePagePayload,
+} from '@terrafirmagreg-team/guide/types';
+import { entryExtras } from './extras';
+import { type QuestLinks, collectTextLinks } from './links';
+
+export async function loadClientGuidePayload(
+  dataset: string,
+  lang: Lang,
+  bookId: string | undefined,
+  entryId: string | undefined,
+  categoryId: string | undefined,
+  langMap: Record<string, string>,
+  messages: GuideMessages,
+): Promise<GuidePagePayload | undefined> {
+  if (!bookId) return undefined;
+  const overview = await loadClientGuideBook(dataset, lang, bookId);
+  if (!overview || overview.status !== 'ready') return undefined;
+
+  const entry = entryId
+    ? overview.entries.find(
+        (item) => item.id === entryId || bareId(item.id) === bareId(entryId),
+      )
+    : undefined;
+  const category =
+    !entry && categoryId
+      ? overview.categories.find((item) => item.id === categoryId)
+      : undefined;
+  const kind = entry ? 'entry' : category ? 'category' : 'overview';
+  const categoryByEntry = categoryMap(overview.categories);
+  const bookModId = overview.modId;
+  const bookPath = overview.bookPath ?? '';
+
+  const questLinks: QuestLinks = {};
+  const hrefs = new Set<string>();
+  const linkCtx = { lang, modId: bookModId, bookPath, categoryByEntry };
+  await collectTextLinks(
+    dataset,
+    questLinks,
+    hrefs,
+    linkCtx,
+    category?.description ?? overview.book?.landingText,
+  );
+  hrefs.add(guideBookHref(dataset, undefined, bookModId, bookPath));
+  const entryCat = entry
+    ? overview.categories.find((cat) =>
+        cat.entries.some((row) => row.id === entry.id),
+      )
+    : undefined;
+  const firstEntry = entryCat?.entries[0]?.id;
+  if (firstEntry) {
+    hrefs.add(
+      guideBookHref(dataset, undefined, bookModId, bookPath, firstEntry),
+    );
+  }
+
+  const extras = entry
+    ? await entryExtras(
+        dataset,
+        lang,
+        langMap,
+        bookModId,
+        bookPath,
+        categoryByEntry,
+        questLinks,
+        hrefs,
+        entry,
+      )
+    : undefined;
+  for (const hit of Object.values(questLinks)) {
+    hrefs.add(
+      questHref(dataset, undefined, {
+        category: hit.filename,
+        id: hit.questId,
+      }),
+    );
+  }
+
+  const previews = await uiConfig().loadPagePreviews?.(lang, langMap, hrefs) ?? {};
+  const payloadCategoryId = entry ? entryCat?.id : category?.id;
+
+  return {
+    kind,
+    dataset,
+    lang,
+    title: entry?.name ?? category?.name ?? overview.book?.name ?? bookId,
+    modId: bookModId,
+    bookPath,
+    description: entry
+      ? undefined
+      : (category?.description ?? overview.book?.landingText),
+    previewIcon:
+      entry?.icon?.id ?? category?.icon?.id ?? overview.book?.cover?.id,
+    previewKind: entry?.icon?.kind ?? category?.icon?.kind,
+    categoryId: payloadCategoryId,
+    bookModId,
+    book: overview.book,
+    categories: overview.categories,
+    entries: overview.entries.map(({ pages: _pages, ...stub }) => stub),
+    ...(entry ? { entry, extras } : {}),
+    ...(Object.keys(questLinks).length ? { questLinks } : {}),
+    ...(Object.keys(previews).length ? { previews } : {}),
+    messages,
+  };
+}

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

@@ -0,0 +1,101 @@
+import {
+  findClientQuestLocation,
+  type ClientQuestLocation,
+} from '@terrafirmagreg-team/quest/lib/client/quest';
+import { classify, pageTexts } from '@terrafirmagreg-team/guide/lib/page-kind';
+import { formatGuide } from '@terrafirmagreg-team/guide/lib/format';
+import {
+  parseGuideReference,
+  resolveGuideReference,
+} from '@terrafirmagreg-team/guide/lib/reference/resolver';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { GuidePage } from '@terrafirmagreg-team/guide/types';
+
+export type QuestLinks = Record<string, ClientQuestLocation>;
+
+async function collectQuestLink(
+  dataset: string,
+  questLinks: QuestLinks,
+  target: string | undefined,
+  force = false,
+): Promise<void> {
+  if (!target || /^https?:\/\//i.test(target)) return;
+  const ref = parseGuideReference(target);
+  if (!force && ref.kind !== 'quest') return;
+  if (questLinks[ref.id]) return;
+  const hit = await findClientQuestLocation(dataset, ref.id);
+  if (hit) questLinks[ref.id] = hit;
+}
+
+export async function collectTextLinks(
+  dataset: string,
+  questLinks: QuestLinks,
+  hrefs: Set<string>,
+  ctx: {
+    lang: Lang;
+    modId?: string;
+    bookPath?: string;
+    categoryByEntry: Map<string, string>;
+  },
+  text: string | undefined,
+): Promise<void> {
+  if (!text) return;
+  for (const node of formatGuide(text, {})) {
+    const link = 'link' in node ? node.link : undefined;
+    if (!link) continue;
+    await collectQuestLink(dataset, questLinks, link);
+    if (/^https?:\/\//i.test(link)) continue;
+    const resolved = resolveGuideReference(parseGuideReference(link), {
+      dataset,
+      lang: ctx.lang,
+      modId: ctx.modId ?? '',
+      bookPath: ctx.bookPath ?? '',
+      categoryByEntry: ctx.categoryByEntry,
+      questLinks,
+    });
+    if (resolved.href) hrefs.add(resolved.href);
+  }
+}
+
+export async function collectPageLinks(
+  dataset: string,
+  lang: Lang,
+  bookModId: string,
+  bookPath: string,
+  categoryByEntry: Map<string, string>,
+  questLinks: QuestLinks,
+  hrefs: Set<string>,
+  page: GuidePage,
+): Promise<void> {
+  const ctx = { lang, modId: bookModId, bookPath, categoryByEntry };
+  if (classify(page.type) === 'quest') {
+    await collectQuestLink(
+      dataset,
+      questLinks,
+      page.trigger || page.quest || page.link,
+      true,
+    );
+  }
+  await collectTextLinks(dataset, questLinks, hrefs, ctx, page.title);
+  for (const text of pageTexts(page)) {
+    await collectTextLinks(dataset, questLinks, hrefs, ctx, text);
+  }
+  for (const target of [
+    page.url,
+    page.link,
+    page.entry,
+    ...(page.entries ?? []),
+  ]) {
+    if (!target || /^https?:\/\//i.test(target)) continue;
+    await collectQuestLink(dataset, questLinks, target);
+    const resolved = resolveGuideReference(parseGuideReference(target), {
+      dataset,
+      lang,
+      modId: bookModId,
+      bookPath,
+      categoryByEntry,
+      questLinks,
+    });
+    if (resolved.href) hrefs.add(resolved.href);
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,46 @@
+import type { ComponentType } from 'react';
+import type { TranslationState } from '@terrafirmagreg-team/translate/server';
+import { createConfigRegistry, uiConfig } from '@terrafirmagreg-team/ui/lib/config';
+import '@terrafirmagreg-team/guide/lib/preview';
+import '@terrafirmagreg-team/guide/lib/search/filter';
+
+export type GuidePageActionsProps = {
+  copied?: TranslationState;
+  crowdinUrl?: string;
+  title: string;
+  mdUrl?: string;
+  githubUrl?: string;
+};
+
+export type GuideConfigInput = {
+  appName?: string;
+  components?: {
+    PageActions?: ComponentType<GuidePageActionsProps>;
+    UntranslatedCallout?: ComponentType<{ copied?: TranslationState }>;
+  };
+};
+
+export type GuideConfig = {
+  appName: string;
+  components: {
+    PageActions: ComponentType<GuidePageActionsProps>;
+    UntranslatedCallout: ComponentType<{ copied?: TranslationState }>;
+  };
+};
+
+const { register: registerGuideConfig, get: guideConfig } = createConfigRegistry<
+  GuideConfigInput,
+  GuideConfig
+>((overrides) => ({
+  appName: overrides.appName ?? uiConfig().brand?.name ?? '',
+  components: {
+    PageActions: (overrides.components?.PageActions ??
+      uiConfig().components?.PageActions) as ComponentType<GuidePageActionsProps>,
+    UntranslatedCallout: (overrides.components?.UntranslatedCallout ??
+      uiConfig().components?.UntranslatedCallout) as ComponentType<{
+      copied?: TranslationState;
+    }>,
+  },
+}));
+
+export { registerGuideConfig, guideConfig };

package/src/lib/data/dto.ts

@@ -0,0 +1,77 @@
+import type { TaggedReference } from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import type { DumpText } from '@terrafirmagreg-team/game/lib/dump/contract/text';
+import type { GuideBookRef } from '@terrafirmagreg-team/game/lib/dump/mods/dto';
+import type { DataGuidesBook } from '@terrafirmagreg-team/game/lib/dump/gen';
+
+export type { GuideBookRef };
+
+export type GuideBookJson = Omit<
+  DataGuidesBook,
+  'categories' | 'cover' | 'display' | 'entries' | 'macros' | 'order'
+> & {
+  display?: {
+    name?: string;
+    landing?: DumpText[];
+  };
+  cover?: TaggedReference | null;
+  order?: number;
+  macros?: Record<string, unknown>;
+  categories?: Record<string, unknown>;
+  entries?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+export type GuideMultiblock = {
+  pattern?: string[][];
+  mapping?: Record<string, unknown>;
+};
+
+export type GuideTableLegend = {
+  color?: string;
+  texts?: string[];
+  text?: string;
+};
+
+export type GuideTableCell = {
+  fill?: string;
+  bold?: boolean;
+  texts?: string[];
+  text?: string;
+  item?: unknown;
+};
+
+export type GuidePage = {
+  type?: string;
+  text?: string;
+  texts?: string[];
+  title?: string;
+  name?: string;
+  images?: string[];
+  image?: string;
+  recipes?: string[];
+  item?: unknown;
+  icon?: unknown;
+  entity?: string;
+  url?: string;
+  link?: string;
+  link_text?: string;
+  entry?: string;
+  entries?: string[];
+  trigger?: string;
+  quest?: string;
+  multiblock?: GuideMultiblock;
+  model?: string;
+  multiblocks?: Array<string | GuideMultiblock>;
+  columns?: string[] | number;
+  rows?: string[][];
+  strings?: Array<string | GuideTableCell | Array<string | GuideTableCell>>;
+  legend?: GuideTableLegend[];
+  fill?: boolean;
+  enable_visualize?: boolean;
+  border?: boolean;
+  anchor?: string;
+  scale?: number;
+  offset?: number;
+  rotate?: boolean;
+  [key: string]: unknown;
+};

package/src/lib/data/parse.ts

@@ -0,0 +1,93 @@
+import {
+  asTaggedReference,
+  stackIdFromRef,
+  type TaggedReference,
+} from '@terrafirmagreg-team/game/lib/dump/contract/ref';
+import { asString } from '@terrafirmagreg-team/game/lib/dump/contract/read';
+import { referenceFrom, type ResourceKind } from '@terrafirmagreg-team/game/lib/dump/contract/kind';
+
+function itemstackIds(value: string): string[] {
+  return value
+    .split(',')
+    .map((part) => part.trim())
+    .map((part) => (part.startsWith('tag:') ? `#${part.slice(4)}` : part))
+    .filter(
+      (part) =>
+        part && (part.startsWith('#') || part.includes(':')) && !part.endsWith('.png'),
+    );
+}
+
+export function collectItemIds(value: unknown): string[] {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.flatMap(collectItemIds);
+  if (typeof value === 'string') return itemstackIds(value);
+  const tagged = asTaggedReference(value);
+  if (tagged) {
+    if (
+      tagged.kind === 'item' ||
+      tagged.kind === 'itemTag' ||
+      tagged.kind === 'block' ||
+      tagged.kind === 'blockTag'
+    ) {
+      return [stackIdFromRef(tagged)];
+    }
+    return [];
+  }
+  if (typeof value === 'object') {
+    const row = value as Record<string, unknown>;
+    if ('item' in row) return collectItemIds(row.item);
+    const tag = asString(row.tag);
+    if (tag) return collectItemIds(`#${tag}`);
+    const id = asString(row.id);
+    if (id) return collectItemIds(id);
+  }
+  return [];
+}
+
+export function parseGuideIcon(value: unknown): TaggedReference | undefined {
+  if (!value) return undefined;
+  const ref = referenceFrom(value);
+  if (ref) return ref;
+  if (typeof value !== 'string') return undefined;
+  const id = value.trim();
+  if (!id) return undefined;
+  return { kind: id.endsWith('.png') ? 'texture' : 'item', id };
+}
+
+const GUIDE_ITEM_KINDS: readonly TaggedReference['kind'][] = [
+  'item',
+  'block',
+  'itemTag',
+  'blockTag',
+  'fluidTag',
+  'entityTag',
+];
+
+export function parseGuideItems(value: unknown): TaggedReference[] {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.flatMap(parseGuideItems);
+  if (typeof value === 'string') {
+    return itemstackIds(value).map((id) =>
+      id.startsWith('#')
+        ? { kind: 'itemTag' as const, id }
+        : { kind: 'item' as const, id },
+    );
+  }
+  const ref = parseGuideIcon(value);
+  return ref && GUIDE_ITEM_KINDS.includes(ref.kind) ? [ref] : [];
+}
+
+export function classifyGuidePageType(type: string | undefined): ResourceKind | undefined {
+  switch ((type ?? '').toLowerCase().trim()) {
+    case 'entity':
+      return 'entity';
+    case 'item':
+      return 'item';
+    case 'block':
+      return 'block';
+    case 'fluid':
+      return 'fluid';
+    default:
+      return undefined;
+  }
+}

package/src/lib/dump.ts

@@ -0,0 +1,5 @@
+import type { DumpIndex } from '@terrafirmagreg-team/game/lib/dump/mods/dto';
+
+export function guideDumpHasContent(dump: DumpIndex): boolean {
+  return dump.mods.some((mod) => mod.books.length > 0);
+}

package/src/lib/format.ts

@@ -0,0 +1,231 @@
+import type {
+  GuideFormatNode,
+  GuideFormatOptions,
+  PageRendererProps,
+} from '@terrafirmagreg-team/guide/types';
+import { MC_FORMAT_COLORS } from '@terrafirmagreg-team/game/lib/dump/contract/text';
+import { langString } from '@terrafirmagreg-team/game/lib/dump/assets/lang/names';
+
+type State = {
+  styles: string[];
+  color?: string;
+  link?: string;
+  tooltip?: string;
+};
+
+function macroReplacement(
+  name: string,
+  token: string,
+  macros: Record<string, string>,
+): string | undefined {
+  const found = macros[name] ?? macros[token] ?? macros[`$(${name})`];
+  if (found !== undefined && found !== token) return found;
+  return undefined;
+}
+
+function expandMacros(
+  raw: string,
+  macros: Record<string, string> | undefined,
+) {
+  let value = raw;
+  const replacements = macros ?? {};
+  for (let depth = 0; depth < 16; depth++) {
+    let changed = false;
+    value = value.replace(/\$\(([A-Za-z0-9_.-]+)\)/g, (token, name) => {
+      const replacement = macroReplacement(name, token, replacements);
+      if (replacement === undefined) return token;
+      changed = true;
+      return replacement;
+    });
+    if (!changed || value.length > 100_000) return value.slice(0, 100_000);
+  }
+  return value;
+}
+
+function appendText(out: GuideFormatNode[], value: string, state: State) {
+  if (!value) return;
+  value = value.replace(/[◼■⬛]/g, '$&︎');
+  const parts = value.split(/(§[0-9a-fk-or])/i);
+  let active = { ...state, styles: [...state.styles] };
+  for (const part of parts) {
+    const code = /^§([0-9a-fk-or])$/i.exec(part)?.[1]?.toLowerCase();
+    if (!code) {
+      if (part) out.push({ type: 'text', value: part, ...active });
+      continue;
+    }
+    if (code === 'r') {
+      active = { styles: [] };
+    } else if (code in MC_FORMAT_COLORS) {
+      active.color = MC_FORMAT_COLORS[code];
+    } else {
+      const style =
+        code === 'l'
+          ? 'bold'
+          : code === 'o'
+            ? 'italic'
+            : code === 'm'
+              ? 'strike'
+              : code === 'n'
+                ? 'underline'
+                : code === 'k'
+                  ? 'obfuscated'
+                  : undefined;
+      if (style && !active.styles.includes(style)) active.styles.push(style);
+    }
+  }
+}
+
+function pushStyle(state: State, style: string) {
+  return state.styles.includes(style)
+    ? state
+    : { ...state, styles: [...state.styles, style] };
+}
+
+function colorFor(token: string): string | undefined {
+  if (/^#[0-9a-f]{6}$/i.test(token)) return token;
+  if (/^#[0-9a-f]{3}$/i.test(token)) {
+    return `#${token[1]}${token[1]}${token[2]}${token[2]}${token[3]}${token[3]}`;
+  }
+  if (/^0x[0-9a-f]{6}$/i.test(token)) return `#${token.slice(2)}`;
+  if (token.length === 1) return MC_FORMAT_COLORS[token.toLowerCase()];
+  const named: Record<string, string> = {
+    thing: '#449900',
+    item: '#bb00bb',
+    header: 'var(--color-foreground)',
+  };
+  return named[token];
+}
+
+const styleAliases: Record<string, string> = {
+  bold: 'bold',
+  italic: 'italic',
+  strike: 'strike',
+  strikethrough: 'strike',
+  obfuscated: 'obfuscated',
+  underline: 'underline',
+  l: 'bold',
+  o: 'italic',
+  m: 'strike',
+  n: 'underline',
+  k: 'obfuscated',
+};
+
+export function formatGuide(
+  raw: string,
+  options: GuideFormatOptions = {},
+): GuideFormatNode[] {
+  const out: GuideFormatNode[] = [];
+  const source = expandMacros(raw, options.macros);
+  let state: State = { styles: [] };
+  let last = 0;
+  const tokens = /\$\(([^)]*)\)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = tokens.exec(source)) !== null) {
+    appendText(out, source.slice(last, match.index), state);
+    last = tokens.lastIndex;
+    const token = (match[1] ?? '').trim();
+    if (!token || token === 'reset' || token === 'clear') {
+      state = { styles: [] };
+      continue;
+    }
+    if (token === 'br' || token === 'br2') {
+      const breaks = token === 'br2' ? 2 : 1;
+      for (let index = 0; index < breaks; index++)
+        out.push({ type: 'break' });
+      continue;
+    }
+    const li = /^li(\d*)$/.exec(token);
+    if (li) {
+      out.push({ type: 'break' });
+      const level = li[1] ? Number(li[1]) : 1;
+      appendText(out, `${'  '.repeat(Math.max(level, 1) - 1)}• `, state);
+      continue;
+    }
+    if (token === '/l') {
+      state = { ...state, link: undefined };
+      continue;
+    }
+    if (token === '/t') {
+      state = { ...state, tooltip: undefined };
+      continue;
+    }
+    if (token.startsWith('k:')) {
+      out.push({ type: 'keybind', value: token.slice(2) });
+      continue;
+    }
+    if (token.startsWith('command:')) {
+      out.push({ type: 'command', value: token.slice(8) });
+      continue;
+    }
+    if (token.startsWith('l:') || token.startsWith('url:')) {
+      state = { ...state, link: token.slice(token.indexOf(':') + 1) };
+      continue;
+    }
+    if (token.startsWith('t:') || token.startsWith('tooltip:')) {
+      state = {
+        ...state,
+        tooltip: token.slice(token.indexOf(':') + 1),
+      };
+      continue;
+    }
+    if (token === 'playername') {
+      appendText(out, 'Player', state);
+      continue;
+    }
+    if (token === 'p') {
+      out.push({ type: 'break' });
+      continue;
+    }
+    const color = colorFor(token);
+    if (color) {
+      state = { ...state, color };
+      continue;
+    }
+    const style = styleAliases[token];
+    if (style) {
+      state = pushStyle(state, style);
+    }
+  }
+  appendText(out, source.slice(last), state);
+  return out;
+}
+
+export function guideFormatOpts(props: PageRendererProps) {
+  return {
+    dataset: props.dataset,
+    lang: props.lang,
+    modId: props.bookModId,
+    bookPath: props.bookPath,
+    categoryByEntry: props.categoryByEntry,
+    macros: props.book?.macros,
+    langMap: props.langMap,
+    keybinds: props.keybinds,
+    questLinks: props.questLinks,
+    previews: props.previews,
+  };
+}
+
+function prettyKeyId(id: string): string {
+  return id
+    .replace(/^key\.(?:keyboard\.|mouse\.|categories\.)?/i, '')
+    .replace(/[._]+/g, ' ')
+    .trim()
+    .replace(/\b[a-z]/g, (ch) => ch.toUpperCase());
+}
+
+export function keybindLabels(
+  bindId: string,
+  langMap: Record<string, string>,
+  keybinds: Record<string, string>,
+): { label: string; title: string } {
+  const defaultKey = keybinds[bindId];
+  const keyName = defaultKey
+    ? (langString(langMap, defaultKey) ?? prettyKeyId(defaultKey))
+    : undefined;
+  const bindName = langString(langMap, bindId) ?? prettyKeyId(bindId);
+  return {
+    label: keyName ?? bindName,
+    title: bindName,
+  };
+}

package/src/lib/links.ts

@@ -0,0 +1,2 @@
+
+export { guideHref } from '@terrafirmagreg-team/game/lib/entry/href';