@terrafirmagreg-team/guide 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@terrafirmagreg-team/guide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Guide/books section",
+  "license": "LGPL-3.0-only",
+  "exports": {
+    "./components/*": [
+      "./src/components/*.tsx",
+      "./src/components/*/index.tsx",
+      "./src/components/*/index.ts"
+    ],
+    "./hooks/*": [
+      "./src/hooks/*.ts",
+      "./src/hooks/*/index.ts"
+    ],
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*/index.ts"
+    ],
+    "./types/*": "./src/types/*.ts",
+    "./types": "./src/types/index.ts",
+    "./locales": "./src/locales.ts"
+  },
+  "dependencies": {
+    "@terrafirmagreg-team/data": "1.2.0",
+    "@terrafirmagreg-team/discussions": "1.2.0",
+    "@terrafirmagreg-team/dump": "1.2.0",
+    "@terrafirmagreg-team/game": "1.2.0",
+    "@terrafirmagreg-team/kit": "1.2.0",
+    "@terrafirmagreg-team/mdx": "1.2.0",
+    "@terrafirmagreg-team/preview": "1.2.0",
+    "@terrafirmagreg-team/search": "1.2.0",
+    "@terrafirmagreg-team/sites": "1.2.0",
+    "@terrafirmagreg-team/translate": "1.2.0",
+    "@terrafirmagreg-team/ui": "1.2.0",
+    "fumadocs-core": "16.17.8",
+    "lucide-react": "^0.577.0"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/guide"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ]
 }

package/src/components/book-switcher.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { useMemo } from 'react';
+import { BookOpen } from 'lucide-react';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import { guideQueryFromParams } from '@terrafirmagreg-team/guide/lib/query';
+import { listGuideBooks } from '@terrafirmagreg-team/guide/lib/books';
+import { guideHref } from '@terrafirmagreg-team/guide/lib/links';
+import { parseSectionLocation } from '@terrafirmagreg-team/sites/location';
+import { Switcher } from '@terrafirmagreg-team/ui/components/blocks/nav/switcher';
+
+function oneLineLanding(text: string | undefined) {
+  if (!text) return undefined;
+  const stripped = text.replace(/\$\([^)]*\)/g, ' ').replace(/\s+/g, ' ').trim();
+  return stripped || undefined;
+}
+
+export function GuideBookSwitcher() {
+  const t = useTranslations();
+  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 books = useAsyncValue(
+    dataset ? () => listGuideBooks(dataset, lang) : undefined,
+    [dataset, lang],
+  );
+  if (!books || books.length < 2 || !dataset) return null;
+  return (
+    <Switcher
+      options={books.map((book) => ({
+        value: book.bookId,
+        title: book.name,
+        description: oneLineLanding(book.landingText),
+        icon: <BookOpen className="size-4" />,
+        url: guideHref(dataset, lang, book.bookId),
+      }))}
+      selected={bookId}
+      placeholder={t('Select book', { note: 'ui.select_book' })}
+    />
+  );
+}
+

package/src/components/mdx/guide-entry.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { useContext } from 'react';
+import { parseSectionLocation } from '@terrafirmagreg-team/sites/location';
+import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
+import { useEntryContext } from '@terrafirmagreg-team/game/hooks/use-entry-context';
+import { ResolvedLangContext } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { findClientGuideEntry } from '@terrafirmagreg-team/guide/lib/client/guides';
+import type { GuideDirectiveProps } from '@terrafirmagreg-team/game/types/entry';
+
+export function GuideEntry({
+  id,
+  dataset: datasetProp,
+  name,
+  modId,
+  bookPath,
+  entry: entryOpt,
+  ...rest
+}: GuideDirectiveProps) {
+  const ctx = useEntryContext();
+  const pathname = usePathname();
+  const locId = parseSectionLocation(pathname).dataset;
+  const dataset =
+    datasetProp ?? ctx?.dataset ?? (locId ? { id: locId } : undefined);
+  const lang = useContext(ResolvedLangContext)?.lang;
+  const hit = useAsyncValue(
+    dataset && lang && id
+      ? () => findClientGuideEntry(dataset, lang, id)
+      : false,
+    [dataset, lang, id],
+  );
+  return (
+    <Entry
+      kind="guide"
+      id={hit?.entry.id ?? id}
+      dataset={dataset}
+      name={name ?? hit?.entry.name}
+      icon={hit?.entry.icon}
+      modId={modId ?? hit?.modId}
+      bookPath={bookPath ?? hit?.bookPath}
+      entry={entryOpt ?? hit?.entry.id}
+      {...rest}
+    />
+  );
+}
+

package/src/components/mdx/multiblock.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import { useContext, useMemo } from 'react';
+import { usePathname } from 'next/navigation';
+import {
+  type DatasetRef,
+  parseSectionLocation,
+} from '@terrafirmagreg-team/sites/location';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { useDumpLocation } from '@terrafirmagreg-team/game/hooks/use-dump-location';
+import { ResolvedLangContext } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { createDumpAssetResolver } from '@terrafirmagreg-team/dump/lib/dump/assets/urls';
+import { asMultiblock } from '@terrafirmagreg-team/guide/lib/meta';
+import { glbFor } from '@terrafirmagreg-team/guide/lib/multiblock/url';
+import { loadMultiblockNameIndex } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { multiblockKey } from '@terrafirmagreg-team/guide/lib/multiblock';
+import { MultiblockVisual } from '@terrafirmagreg-team/guide/components/views/kind/media';
+import type { GuideMultiblock } from '@terrafirmagreg-team/guide/types';
+
+export type MdxMultiblockProps = {
+  id?: string;
+  name?: string;
+  spec?: string;
+  label?: string;
+  dataset?: DatasetRef;
+  title?: string;
+};
+
+export function MdxMultiblock({
+  id,
+  name,
+  spec,
+  label,
+  dataset: datasetProp,
+  title,
+}: MdxMultiblockProps) {
+  const pathname = usePathname();
+  const locId = parseSectionLocation(pathname).dataset;
+  const dataset = useMemo<DatasetRef>(
+    () => datasetProp ?? { id: locId ?? '' },
+    [datasetProp, locId],
+  );
+  const lang = useContext(ResolvedLangContext)?.lang;
+  const dumpLoc = useDumpLocation(dataset);
+  const resolveResource = useMemo(
+    () => createDumpAssetResolver(dataset),
+    [dataset],
+  );
+  const namedSpec = useAsyncValue(
+    dataset && lang && name
+      ? async () =>
+          (await loadMultiblockNameIndex(dataset, lang))[
+            name.trim().toLowerCase()
+          ]
+      : false,
+    [dataset, lang, name],
+  );
+  const value = useMemo<string | GuideMultiblock | undefined>(() => {
+    if (spec) {
+      try {
+        return JSON.parse(spec) as GuideMultiblock;
+      } catch {
+        return undefined;
+      }
+    }
+    if (name) return namedSpec;
+    return id;
+  }, [id, name, spec, namedSpec]);
+  const key = multiblockKey(asMultiblock(value));
+  const src = useAsyncValue(
+    dataset && key
+      ? () => glbFor(dataset, '', asMultiblock(value), lang)
+      : false,
+    [dataset, key, lang, dumpLoc],
+  );
+  const glbs = src && key ? { [key]: src } : undefined;
+  return (
+    <MultiblockVisual
+      value={value}
+      title={title ?? label ?? id ?? name}
+      glbs={glbs}
+      resolveResource={resolveResource}
+    />
+  );
+}
+

package/src/components/tree/children.tsx

@@ -0,0 +1,75 @@
+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 {
+  type DatasetRef,
+  sectionUrl,
+  versionSuffix,
+} from '@terrafirmagreg-team/sites/location';
+import { bookOptionId, guideCategoryHref } from '@terrafirmagreg-team/guide/lib/paths';
+import type { GuideIndex } from '@terrafirmagreg-team/guide/types';
+import type { TaggedReference } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+
+function nodeIcon(
+  dataset: DatasetRef,
+  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: DatasetRef,
+  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.id}/${dataset.version ?? ''}/${index.modId}/${index.bookPath}/${category.id}#index`,
+    },
+    $id: `${dataset.id}/${dataset.version ?? ''}/${index.modId}/${index.bookPath}/${category.id}`,
+    children: category.entries.map((entry): PageTree.Item => ({
+      type: 'page',
+      name: entry.name,
+      url: `${sectionUrl('guide', dataset.id)}?book=${encodeQueryValue(bookId ?? '')}&entry=${encodeQueryValue(entry.id)}${versionSuffix(dataset)}`,
+      icon: nodeIcon(dataset, entry.icon, entry.name),
+      $id: `${dataset.id}/${dataset.version ?? ''}/${index.modId}/${index.bookPath}/${category.id}/${entry.id}`,
+    })),
+  }));
+}
+

package/src/components/tree/index.tsx

@@ -0,0 +1,127 @@
+import 'server-only';
+import { createElement } from 'react';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
+import { loadMergedLangMap } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/load';
+import { asRecord, asString } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { loadDatasetDump } from '@terrafirmagreg-team/dump/lib/dump/mods/load';
+import { DUMP_POINTER_TTL } from '@terrafirmagreg-team/dump/lib/dump/json-reader';
+import { createAsyncCache } from '@terrafirmagreg-team/data/lib/async-cache';
+import { clientDumpJson } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { keyTreeNode } from '@terrafirmagreg-team/translate/server';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { encodeQueryValue } from '@terrafirmagreg-team/translate/lib/url';
+import {
+  type DatasetRef,
+  sectionUrl,
+  versionSuffix,
+} from '@terrafirmagreg-team/sites/location';
+import { bookOptionId } from '@terrafirmagreg-team/guide/lib/paths';
+import { bookSlug, toBook } from '@terrafirmagreg-team/guide/lib/book';
+import { sectionDatasets } from '@terrafirmagreg-team/kit/lib/datasets';
+import type { GuideBookJson, GuideBookRef } from '@terrafirmagreg-team/guide/lib/data/dto';
+import type { SectionTrees } from '@terrafirmagreg-team/kit/types';
+
+function bookIcon(
+  dataset: DatasetRef,
+  raw: GuideBookJson | undefined,
+): React.ReactNode {
+  const cover = asRecord(raw?.cover);
+  const coverId = asString(cover?.id) ?? undefined;
+  if (!coverId) 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: coverId,
+      kind: 'item',
+      size: 14,
+      href: false,
+      tooltip: false,
+      missing: 'hide',
+    }),
+  );
+}
+
+function bookLeaf(
+  dataset: DatasetRef,
+  ref: GuideBookRef,
+  slug: string,
+  raw: GuideBookJson | undefined,
+  map: Record<string, string>,
+): PageTree.Item {
+  const book = toBook(raw, ref, slug, map);
+  const bookId = bookOptionId(ref.modId, ref.bookPath);
+  return keyTreeNode({
+    type: 'page',
+    name: book.name,
+    url: `${sectionUrl('guide', dataset.id)}?book=${encodeQueryValue(bookId)}${versionSuffix(dataset)}`,
+    icon: bookIcon(dataset, raw),
+    $id: `${dataset.id}/${dataset.version ?? ''}/book/${bookId}`,
+  }) as PageTree.Item;
+}
+
+async function datasetBookLeaves(
+  dataset: DatasetRef,
+  langMap: Record<string, string>,
+): Promise<PageTree.Node[]> {
+  const dump = await loadDatasetDump(dataset);
+  if (!dump) return [];
+  const taken = new Set<string>();
+  const leaves: PageTree.Node[] = [];
+  for (const mod of dump.mods) {
+    const raws = await Promise.all(
+      mod.books.map((ref) =>
+        clientDumpJson(dataset, `${ref.dir}/book.json`).then(
+          (raw) => asRecord(raw) as GuideBookJson | undefined,
+        ),
+      ),
+    );
+    for (const [i, ref] of mod.books.entries()) {
+      const raw = raws[i];
+      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);
+      leaves.push(bookLeaf(dataset, ref, slug, raw, langMap));
+    }
+  }
+  return leaves;
+}
+
+const guideTreesCache = createAsyncCache(
+  async (): Promise<SectionTrees> => buildGuideTrees(),
+  () => 'guide-trees',
+  DUMP_POINTER_TTL,
+);
+
+export function guideTrees(): Promise<SectionTrees> {
+  return guideTreesCache();
+}
+
+async function buildGuideTrees(): Promise<SectionTrees> {
+  const { defaultLanguage } = loadLocaleRegistry();
+  const datasets = await sectionDatasets('guide');
+  const trees: SectionTrees = {};
+  for (const { id, title: datasetTitle, languages } of datasets) {
+    for (const lang of languages ?? [defaultLanguage]) {
+      const map = await loadMergedLangMap({ id }, lang);
+      (trees[lang] ??= {})[id] = {
+        name: datasetTitle ?? id,
+        children: await datasetBookLeaves({ id }, map),
+        $id: `guide/${id}/${lang}`,
+      } satisfies PageTree.Root;
+    }
+  }
+  return trees;
+}
+

package/src/components/views/browser.tsx

@@ -0,0 +1,133 @@
+'use client';
+import { useEffect, useMemo } from 'react';
+import { useRouter } from 'next/navigation';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { useVersionedDataset } from '@terrafirmagreg-team/kit/hooks/use-versioned-dataset';
+import { useLangMap } from '@terrafirmagreg-team/game/hooks/use-lang-map';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { Skeleton } from '@terrafirmagreg-team/ui/components/ui/skeleton';
+import {
+  Workspace,
+  WorkspaceBody,
+} from '@terrafirmagreg-team/kit/components/workspace';
+import { GuidePageView } from '@terrafirmagreg-team/guide/components/views/page/view';
+import {
+  firstGuideEntryId,
+  guideQueryFromParams,
+} from '@terrafirmagreg-team/guide/lib/query';
+import { loadClientGuidePayload } from '@terrafirmagreg-team/guide/lib/client-payload';
+import { listGuideBooks } from '@terrafirmagreg-team/guide/lib/books';
+import { loadClientGuideBook } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { guideHref } from '@terrafirmagreg-team/guide/lib/links';
+import { guideConfig } from '@terrafirmagreg-team/guide/lib/config';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { GuideMessages } from '@terrafirmagreg-team/guide/types';
+
+export function GuideBrowser({
+  dataset: id,
+  datasetTitle,
+  lang,
+  versions,
+}: {
+  dataset: string;
+  datasetTitle: string;
+  lang: Lang;
+  versions?: readonly string[];
+}) {
+  const t = useTranslations();
+  const router = useRouter();
+  const params = useLocationSearchParams();
+  const dataset = useVersionedDataset(id, { versions }) ?? { id };
+  const { bookId, entryId, categoryId } = useMemo(
+    () => guideQueryFromParams(params),
+    [params],
+  );
+  const books = useAsyncValue(
+    () => listGuideBooks(dataset, lang),
+    [dataset, lang],
+  );
+  const langMap = useLangMap(dataset, lang);
+  const messages = useMemo<GuideMessages>(
+    () => ({
+      'guide.related': t('Related', { note: 'guide.related' }),
+      'guide.objective': t('Objective', { note: 'guide.objective' }),
+      'guide.link': t('Open', { note: 'guide.link' }),
+      'guide.quest': t('Quest', { note: 'guide.quest' }),
+      'guide.recipe_empty': t('No recipes', { note: 'guide.recipe_empty' }),
+      'guide.entity_unavailable': t('Entity preview unavailable', {
+        note: 'guide.entity_unavailable',
+      }),
+      'guide.entry_missing': t('Entry not found', {
+        note: 'guide.entry_missing',
+      }),
+      'guide.entry_count': t('{count} entries', {
+        note: 'guide.entry_count',
+      }),
+      'guide.page_count': t('{count} pages', { note: 'guide.page_count' }),
+    }),
+    [t],
+  );
+
+  const canonical = useAsyncValue(
+    books && !bookId
+      ? async () => {
+          const book = books[0];
+          if (!book) return undefined;
+          const index = await loadClientGuideBook(dataset, lang, book.bookId);
+          const first = index ? firstGuideEntryId(index) : undefined;
+          return guideHref(dataset, lang, book.bookId, first);
+        }
+      : undefined,
+    [books, bookId, dataset, lang],
+  );
+
+  useEffect(() => {
+    if (canonical) router.replace(canonical);
+  }, [canonical, router]);
+
+  const payload = useAsyncValue(
+    langMap && bookId
+      ? () =>
+          loadClientGuidePayload(
+            dataset,
+            lang,
+            bookId,
+            entryId,
+            categoryId,
+            langMap,
+            messages,
+          )
+      : undefined,
+    [dataset, lang, bookId, entryId, categoryId, langMap, messages],
+  );
+
+  useEffect(() => {
+    if (payload?.title) {
+      document.title = `${payload.title} · ${datasetTitle} | ${guideConfig().appName}`;
+    }
+  }, [payload?.title, datasetTitle]);
+
+  if (!bookId || !payload || !langMap) {
+    return (
+      <Workspace toc={[]}>
+        <WorkspaceBody className="flex flex-col gap-3">
+          <Skeleton className="h-3.5 w-44" />
+          <Skeleton className="mt-1 h-8 w-2/3 max-w-sm" />
+          <Skeleton className="h-4 w-full max-w-md" />
+          <Skeleton className="h-4 w-4/5 max-w-sm" />
+          <div className="mt-6 flex flex-col gap-2.5">
+            <Skeleton className="h-4 w-full" />
+            <Skeleton className="h-4 w-[92%]" />
+            <Skeleton className="h-4 w-[96%]" />
+            <Skeleton className="h-32 w-full" />
+            <Skeleton className="h-4 w-[88%]" />
+            <Skeleton className="h-4 w-3/4" />
+          </div>
+        </WorkspaceBody>
+      </Workspace>
+    );
+  }
+  return <GuidePageView payload={payload} langMap={langMap} />;
+}
+