@terrafirmagreg-team/guide 0.0.0-stage → 1.2.0

package/src/components/views/page/view.tsx

@@ -0,0 +1,279 @@
+import { EntryProvider } from '@terrafirmagreg-team/game/hooks/use-entry-context';
+import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
+import {
+  Workspace,
+  WorkspaceBody,
+  WorkspaceDescription,
+  WorkspaceTitle,
+} from '@terrafirmagreg-team/kit/components/workspace';
+import { guideConfig } from '@terrafirmagreg-team/guide/lib/config';
+import { GithubInfo } from '@terrafirmagreg-team/ui/components/blocks/git/github-info';
+import { sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
+import { categoryMap, guideBreadcrumbItems } from '@terrafirmagreg-team/guide/lib/breadcrumb';
+import { guideToc } from '@terrafirmagreg-team/guide/lib/toc';
+import { GuideText } from '@terrafirmagreg-team/guide/components/views/text';
+import { GuideOverviewBody } from '@terrafirmagreg-team/guide/components/views/page/overview-body';
+import { GuideCategoryBody } from '@terrafirmagreg-team/guide/components/views/page/category-body';
+import { GuideEntryBody } from '@terrafirmagreg-team/guide/components/views/page/entry-body';
+import { guideMessage } from '@terrafirmagreg-team/guide/lib/messages';
+import { CommentsSlot } from '@terrafirmagreg-team/discussions/components/comments';
+import {
+  guideBookHref,
+  guideCategoryHref,
+} from '@terrafirmagreg-team/guide/lib/paths';
+import type { GuideIndex, GuidePagePayload } from '@terrafirmagreg-team/guide/types';
+
+type NavItem = { name: string; url: string };
+
+function guideNavItems(
+  payload: GuidePagePayload,
+  overview: GuideIndex | undefined,
+): { previous?: NavItem; next?: NavItem } {
+  const modId = payload.bookModId ?? payload.modId;
+  const bookPath = payload.bookPath;
+  if (!overview || !modId || !bookPath) return {};
+  const { dataset, lang } = payload;
+  const chain: NavItem[] = [];
+  if (overview.book)
+    chain.push({
+      name: overview.book.name,
+      url: guideBookHref(dataset, lang, modId, bookPath),
+    });
+  for (const category of overview.categories) {
+    chain.push({
+      name: category.name,
+      url: guideCategoryHref(dataset, lang, modId, bookPath, category),
+    });
+    for (const entry of category.entries)
+      chain.push({
+        name: entry.name,
+        url: guideBookHref(dataset, lang, modId, bookPath, entry.id),
+      });
+  }
+  const current =
+    payload.kind === 'entry' && payload.entry
+      ? guideBookHref(dataset, lang, modId, bookPath, payload.entry.id)
+      : payload.kind === 'category' && payload.categoryId
+        ? guideCategoryHref(dataset, lang, modId, bookPath, {
+            id: payload.categoryId,
+          })
+        : payload.kind === 'overview'
+          ? guideBookHref(dataset, lang, modId, bookPath)
+          : undefined;
+  const index = current
+    ? chain.findIndex((item) => item.url === current)
+    : -1;
+  return {
+    previous: index > 0 ? chain[index - 1] : undefined,
+    next:
+      index >= 0 && index < chain.length - 1 ? chain[index + 1] : undefined,
+  };
+}
+
+export function GuidePageView({
+  payload,
+  langMap,
+}: {
+  payload: GuidePagePayload;
+  langMap: Record<string, string>;
+}) {
+  const { dataset, lang, kind } = payload;
+  const overview: GuideIndex | undefined =
+    payload.book !== undefined || payload.categories !== undefined
+      ? {
+          status: payload.book ? 'ready' : 'missing',
+          root: '',
+          modId: payload.bookModId ?? payload.modId ?? '',
+          bookPath: payload.bookPath,
+          book: payload.book ?? null,
+          categories: payload.categories ?? [],
+          entries: payload.entries ?? [],
+          language: lang,
+          isFallback: false,
+        }
+      : undefined;
+  const categories = overview
+    ? categoryMap(overview.categories)
+    : new Map<string, string>();
+  const labels = {
+    related: guideMessage(payload.messages, 'guide.related'),
+    objective: guideMessage(payload.messages, 'guide.objective'),
+  };
+
+  let toc: ReturnType<typeof guideToc> | undefined;
+  let body: React.ReactNode = null;
+
+  switch (kind) {
+    case 'pack':
+      break;
+    case 'overview':
+      if (overview) {
+        body = (
+          <GuideOverviewBody
+            dataset={dataset}
+            lang={lang}
+            modId={payload.modId}
+            bookPath={payload.bookPath}
+            overview={overview}
+            categories={categories}
+            langMap={langMap}
+            questLinks={payload.questLinks}
+            previews={payload.previews}
+            messages={payload.messages}
+          />
+        );
+      }
+      break;
+    case 'category':
+      body = (
+        <GuideCategoryBody
+          dataset={dataset}
+          lang={lang}
+          modId={payload.modId}
+          bookPath={payload.bookPath}
+          overview={overview}
+          categoryId={payload.categoryId}
+          messages={payload.messages}
+        />
+      );
+      break;
+    case 'entry':
+      toc = guideToc(
+        payload.entry?.pages,
+        langMap,
+        labels,
+        payload.extras?.entityNames,
+      );
+      body = overview && payload.bookPath && (
+        <GuideEntryBody
+          dataset={dataset}
+          lang={lang}
+          bookPath={payload.bookPath}
+          overview={overview}
+          entry={payload.entry}
+          categories={categories}
+          langMap={langMap}
+          extras={payload.extras}
+          questLinks={payload.questLinks}
+          previews={payload.previews}
+          messages={payload.messages}
+        />
+      );
+      break;
+    default: {
+      const _exhaustive: never = kind;
+      body = <p>{String(_exhaustive)}</p>;
+    }
+  }
+
+  const copied =
+    payload.entry?.translation ??
+    overview?.categories.find((item) => item.id === payload.categoryId)
+      ?.translation ??
+    payload.book?.translation;
+
+  const crumbs = guideBreadcrumbItems({
+    kind,
+    title: payload.title,
+    dataset,
+    modId: payload.modId,
+    bookPath: payload.bookPath,
+    overview,
+    categoryId: payload.categoryId,
+  });
+
+  const datasetConf =
+    sectionConfig().datasetConfig[dataset.id];
+  const repoSlug = datasetConf?.repo?.split('/');
+  const mdQuery = new URLSearchParams();
+  if (payload.modId && payload.bookPath) {
+    mdQuery.set('book', `${payload.modId}:${payload.bookPath}`);
+  }
+  if (kind === 'entry' && payload.entry) {
+    mdQuery.set('entry', payload.entry.id);
+  } else if (kind === 'category' && payload.categoryId) {
+    mdQuery.set('cat', payload.categoryId);
+  }
+  mdQuery.set('lang', lang);
+  const mdUrl = `/guide/${dataset.id}.md?${mdQuery}`;
+
+  const nav = guideNavItems(payload, overview);
+  const {
+    PageActions,
+    UntranslatedCallout,
+  } = guideConfig().components;
+
+  return (
+    <EntryProvider dataset={dataset} lang={lang} langMap={langMap}>
+      <Workspace
+        toc={toc ?? []}
+        className="min-h-full"
+        breadcrumb={{ items: crumbs, previews: payload.previews }}
+        pagination={{ items: nav }}
+      >
+        <UntranslatedCallout copied={copied} />
+        <WorkspaceTitle>
+          {kind === 'entry' && payload.previewIcon ? (
+            <span className="inline-flex items-center gap-2">
+              <Entry
+                id={payload.previewIcon}
+                kind={payload.previewKind}
+                name={payload.title}
+                href={false}
+                tooltip={false}
+              />
+              {payload.title}
+            </span>
+          ) : (
+            payload.title
+          )}
+        </WorkspaceTitle>
+        {payload.description ? (
+          <WorkspaceDescription className="mb-0">
+            <GuideText
+              text={payload.description}
+              dataset={dataset}
+              lang={lang}
+              modId={payload.modId}
+              bookPath={payload.bookPath}
+              categoryByEntry={categories}
+              macros={overview?.book?.macros}
+              langMap={langMap}
+              questLinks={payload.questLinks}
+              previews={payload.previews}
+            />
+          </WorkspaceDescription>
+        ) : null}
+        <div className="flex flex-row gap-2 items-center border-b pb-6">
+          <PageActions
+            copied={copied}
+            crowdinUrl={datasetConf?.crowdin}
+            title={payload.title}
+            mdUrl={mdUrl}
+            githubUrl={
+              datasetConf?.repo
+                ? `https://github.com/${datasetConf.repo}`
+                : undefined
+            }
+          />
+        </div>
+        {kind === 'pack' && repoSlug ? (
+          <GithubInfo
+            owner={repoSlug[0]}
+            repo={repoSlug[1]}
+            className="not-prose mb-6 w-full"
+          />
+        ) : null}
+        <WorkspaceBody>
+          <div data-md-root className="contents">
+            {body}
+          </div>
+        </WorkspaceBody>
+        <CommentsSlot
+          page={`guide:${dataset.id}:${payload.modId}:${payload.bookPath}:${payload.entry?.id ?? payload.categoryId ?? 'book'}#${lang}`}
+        />
+      </Workspace>
+    </EntryProvider>
+  );
+}
+

package/src/components/views/text.tsx

@@ -0,0 +1,132 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { Fragment, type ReactNode } from 'react';
+import { LinkPreview } from '@terrafirmagreg-team/ui/components/blocks/link/link-preview';
+import { guideLink } from '@terrafirmagreg-team/guide/lib/reference';
+import { formatGuide } from '@terrafirmagreg-team/guide/lib/format';
+import { keybindLabels } from '@terrafirmagreg-team/guide/lib/format';
+import { Kbd } from '@terrafirmagreg-team/ui/components/ui/kbd';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@terrafirmagreg-team/ui/components/ui/tooltip';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import type { GuideFormatOptions } from '@terrafirmagreg-team/guide/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+const LINK_STYLE = 'text-primary underline underline-offset-2';
+
+export function GuideText({
+  text,
+  dataset,
+  lang,
+  modId,
+  bookPath,
+  categoryByEntry,
+  macros,
+  langMap,
+  keybinds,
+  questLinks,
+  previews,
+}: {
+  text: string;
+  dataset?: DatasetRef;
+  lang?: Lang;
+  modId?: string;
+  bookPath?: string;
+} & Omit<GuideFormatOptions, 'dataset' | 'lang' | 'modId' | 'bookPath'>) {
+  if (!text) return null;
+  const nodes = formatGuide(text, {
+    dataset,
+    lang,
+    modId,
+    bookPath,
+    categoryByEntry,
+    macros,
+    langMap,
+    keybinds,
+    questLinks,
+    previews,
+  });
+  const children: ReactNode[] = [];
+  for (const [index, node] of nodes.entries()) {
+    let el: ReactNode = null;
+    if (node.type === 'break') {
+      el = <br />;
+    } else if (node.type === 'keybind') {
+      const { label, title } = keybindLabels(
+        node.value,
+        langMap ?? {},
+        keybinds ?? {},
+      );
+      el = (
+        <Tooltip>
+          <TooltipTrigger render={<Kbd>{label}</Kbd>} />
+          <TooltipContent>{title}</TooltipContent>
+        </Tooltip>
+      );
+    } else if (node.type === 'command') {
+      el = <code className="font-mono text-sm">{node.value}</code>;
+    } else if (node.type === 'text') {
+      el = node.value;
+    }
+    if (el === null) continue;
+    if (node.type === 'text' && node.styles?.length) {
+      el = (
+        <span
+          className={cn(
+            node.styles.includes('bold') && 'font-bold',
+            node.styles.includes('italic') && 'italic',
+            node.styles.includes('underline') && 'underline',
+            node.styles.includes('strike') && 'line-through',
+          )}
+        >
+          {el}
+        </span>
+      );
+    }
+    if (node.type === 'text' && node.color) {
+      el = <span style={{ color: node.color }}>{el}</span>;
+    }
+    if (node.type === 'text' && node.link) {
+      const { href, external } = guideLink(node, {
+        dataset: dataset ?? { id: '' },
+        lang: lang ?? 'en_us',
+        modId: modId ?? '',
+        bookPath: bookPath ?? '',
+        categoryByEntry: categoryByEntry ?? new Map(),
+        questLinks,
+      });
+      el = href ? (
+        <LinkPreview
+          preview={previews?.[href]}
+          href={href}
+          variant="raw"
+          className={LINK_STYLE}
+          {...(external ? { target: '_blank', rel: 'noreferrer' } : {})}
+        >
+          {el}
+        </LinkPreview>
+      ) : (
+        el
+      );
+    }
+    if (node.type === 'text' && node.tooltip) {
+      el = (
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <span className="cursor-help underline decoration-dotted underline-offset-4">
+                {el}
+              </span>
+            }
+          />
+          <TooltipContent>{node.tooltip}</TooltipContent>
+        </Tooltip>
+      );
+    }
+    children.push(<Fragment key={index}>{el}</Fragment>);
+  }
+  return <>{children}</>;
+}
+

package/src/hooks/use-left-sidebar-tree.ts

@@ -0,0 +1,28 @@
+'use client';
+import { usePathname } from 'next/navigation';
+import { useMemo } from 'react';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { useLastValue } from '@terrafirmagreg-team/ui/hooks/use-last-value';
+import { useGuideTree } from '@terrafirmagreg-team/guide/hooks/use-tree';
+import { guideQueryFromParams } from '@terrafirmagreg-team/guide/lib/query';
+import { parseSectionLocation } from '@terrafirmagreg-team/sites/location';
+
+export function useGuideLeftSidebarTree(tree: PageTree.Root): PageTree.Root {
+  const { dataset: datasetId } = parseSectionLocation(usePathname());
+  const lang = useResolvedLang();
+  const params = useLocationSearchParams();
+  const { bookId } = guideQueryFromParams(params);
+  const version = params.get('version') ?? undefined;
+  const dataset = useMemo(
+    () => (datasetId ? { id: datasetId, version } : undefined),
+    [datasetId, version],
+  );
+  const runtime = useLastValue(
+    useGuideTree(dataset, lang, bookId),
+    dataset?.id ?? '',
+  );
+  return runtime ?? tree;
+}
+

package/src/hooks/use-tree.ts

@@ -0,0 +1,35 @@
+'use client';
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { loadClientGuideBook } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { listGuideBooks } from '@terrafirmagreg-team/guide/lib/books';
+import { guideTreeChildren } from '@terrafirmagreg-team/guide/components/tree/children';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export function useGuideTree(
+  dataset: DatasetRef | undefined,
+  lang: Lang,
+  bookId: string | undefined,
+): PageTree.Root | undefined {
+  return useAsyncValue(
+    dataset
+      ? async () => {
+          const summaries = await listGuideBooks(dataset, lang);
+          if (!summaries.length) return undefined;
+          const resolvedId = bookId ?? summaries[0]?.bookId;
+          const index = resolvedId
+            ? await loadClientGuideBook(dataset, lang, resolvedId)
+            : undefined;
+          return {
+            name: 'guide',
+            children: index ? guideTreeChildren(dataset, index) : [],
+            $id: `guide/${dataset.id}/${dataset.version ?? ''}/${resolvedId ?? 'none'}/${lang}`,
+          } satisfies PageTree.Root;
+        }
+      : undefined,
+    [dataset, lang, bookId],
+  );
+}
+

package/src/lib/book/convert.ts

@@ -0,0 +1,75 @@
+import { dumpTextLines } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+import type {
+  GuideBookJson,
+  GuideBookRef,
+} from '@terrafirmagreg-team/guide/lib/data/dto';
+import type { GuideBook } from '@terrafirmagreg-team/guide/types';
+import {
+  type FallbackTracker,
+  fallbackTracker,
+  localize,
+  localizeGuideValue,
+  markTextKeys,
+} from './localize';
+import {
+  asCover,
+  asLanding,
+  displayRecord,
+  macrosFrom,
+  stringField,
+  urlSafeSlug,
+} from './raw';
+
+function bookName(
+  raw: GuideBookJson | undefined,
+  ref: GuideBookRef,
+  slug: string,
+  langMap: Record<string, string>,
+  tracker?: FallbackTracker,
+): string {
+  const display = displayRecord(raw);
+  const nameKey = stringField(display, 'name');
+  return nameKey
+    ? localize(langMap, nameKey, nameKey, tracker)
+    : (stringField(raw, 'id') ?? ref.bookId ?? slug);
+}
+
+export function toBook(
+  raw: GuideBookJson | undefined,
+  ref: GuideBookRef,
+  slug: string,
+  langMap: Record<string, string>,
+  rawLang?: Record<string, string>,
+): GuideBook {
+  const display = displayRecord(raw);
+  const landing = asLanding(display?.landing);
+  const tracker = fallbackTracker(rawLang);
+  markTextKeys(landing, tracker);
+  return {
+    id: stringField(raw, 'id') ?? ref.bookId,
+    slug,
+    name: bookName(raw, ref, slug, langMap, tracker),
+    description: localizeGuideValue(
+      stringField(raw, 'subtitle'),
+      langMap,
+      tracker,
+    ) as string | undefined,
+    landing,
+    landingText: landing.length
+      ? dumpTextLines(langMap, landing).join('\n')
+      : undefined,
+    cover: asCover(raw?.cover),
+    macros: macrosFrom(raw),
+    ...(tracker?.flag ? { translation: tracker.flag } : {}),
+  };
+}
+
+export function bookSlug(
+  raw: GuideBookJson | undefined,
+  ref: GuideBookRef,
+): string {
+  const explicit = stringField(raw, 'slug');
+  if (explicit) return urlSafeSlug(explicit);
+  return urlSafeSlug(ref.bookPath);
+}
+

package/src/lib/book/index-rows.ts

@@ -0,0 +1,136 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { parseGuideIcon } from '@terrafirmagreg-team/guide/lib/data/parse';
+import type {
+  GuideBookJson,
+  GuideBookRef,
+} from '@terrafirmagreg-team/guide/lib/data/dto';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type {
+  GuideCategory,
+  GuideEntry,
+  GuideEntryRef,
+  GuideIndex,
+} from '@terrafirmagreg-team/guide/types';
+import { toBook } from './convert';
+import { fallbackTracker, localize, localizeGuideValue } from './localize';
+import {
+  type RawRecord,
+  categoryMatches,
+  compareGuideOrder,
+  displayRecord,
+  numeric,
+  rawId,
+  stringField,
+} from './raw';
+
+function toEntry(
+  raw: RawRecord,
+  fallbackId: string,
+  langMap: Record<string, string>,
+  contentLanguage: Lang,
+  rawLang?: Record<string, string>,
+): GuideEntry {
+  const id = rawId(raw, fallbackId);
+  const display = displayRecord(raw);
+  const nameKey = stringField(display, 'name');
+  const tracker = fallbackTracker(rawLang);
+  return {
+    id,
+    name: nameKey ? localize(langMap, nameKey, nameKey, tracker) : id,
+    category: typeof raw.category === 'string' ? raw.category : undefined,
+    icon: parseGuideIcon(raw.icon),
+    pages: Array.isArray(raw.pages)
+      ? (localizeGuideValue(raw.pages, langMap, tracker) as GuideEntry['pages'])
+      : [],
+    order: numeric(raw.order),
+    contentLanguage,
+    ...(tracker?.flag ? { translation: tracker.flag } : {}),
+  };
+}
+
+function toCategory(
+  raw: RawRecord,
+  fallbackId: string,
+  langMap: Record<string, string>,
+  rawLang?: Record<string, string>,
+): Omit<GuideCategory, 'entries'> {
+  const id = rawId(raw, fallbackId);
+  const nameKey = stringField(raw, 'name');
+  const tracker = fallbackTracker(rawLang);
+  return {
+    id,
+    name: nameKey ? localize(langMap, nameKey, nameKey, tracker) : id,
+    description: localizeGuideValue(
+      stringField(raw, 'description'),
+      langMap,
+      tracker,
+    ) as string | undefined,
+    icon: parseGuideIcon(raw.icon),
+    order: numeric(raw.order),
+    ...(tracker?.flag ? { translation: tracker.flag } : {}),
+  };
+}
+
+function refsForCategory(
+  category: Omit<GuideCategory, 'entries'>,
+  entries: GuideEntry[],
+): GuideEntryRef[] {
+  const matches = entries
+    .filter((entry) => categoryMatches(category.id, entry.category))
+    .sort(compareGuideOrder);
+  return matches.map((entry) => ({
+    id: entry.id,
+    name: entry.name ?? entry.id,
+    icon: entry.icon,
+    pageCount: entry.pages?.length,
+    order: entry.order,
+    ...(entry.translation ? { translation: entry.translation } : {}),
+  }));
+}
+
+export type BookRows = {
+  ref: GuideBookRef;
+  slug: string;
+  raw?: GuideBookJson;
+  entries: Array<{ id: string; raw: RawRecord }>;
+  categories: Array<{ id: string; raw: RawRecord }>;
+  contentLanguage: Lang;
+  isFallback: boolean;
+};
+
+export function indexBookRows(
+  rows: BookRows,
+  dataset: DatasetRef,
+  lang: Lang,
+  langMap: Record<string, string>,
+  rawLang?: Record<string, string>,
+): GuideIndex {
+  const { ref, slug, raw } = rows;
+  const entries = rows.entries.map((entryRow) =>
+    toEntry(entryRow.raw, entryRow.id, langMap, rows.contentLanguage, rawLang),
+  );
+  const categoryRows = rows.categories.map((categoryRow) =>
+    toCategory(categoryRow.raw, categoryRow.id, langMap, rawLang),
+  );
+  const categories: GuideCategory[] = categoryRows
+    .sort(compareGuideOrder)
+    .map((category) => ({
+      ...category,
+      entries: refsForCategory(category, entries),
+    }));
+  const book = toBook(raw, ref, slug, langMap, rawLang);
+  return {
+    status: categories.length || book.name ? 'ready' : 'missing',
+    root: ref.dir,
+    modId: ref.modId,
+    bookId: ref.bookId,
+    bookPath: ref.bookPath,
+    bookSlug: slug,
+    book,
+    categories,
+    entries: entries.sort(compareGuideOrder),
+    language: lang,
+    isFallback: rows.isFallback,
+  };
+}
+

package/src/lib/book/index.ts

@@ -0,0 +1,3 @@
+export { bookSlug, toBook } from './convert';
+export { type BookRows, indexBookRows } from './index-rows';
+