@terrafirmagreg-team/guide 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@terrafirmagreg-team/guide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    "./components/*": [
+      "./src/components/*.tsx",
+      "./src/components/*.ts",
+      "./src/components/*/index.tsx",
+      "./src/components/*/index.ts"
+    ],
+    "./hooks/*": [
+      "./src/hooks/*.ts",
+      "./src/hooks/*.tsx",
+      "./src/hooks/*/index.ts",
+      "./src/hooks/*/index.tsx"
+    ],
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*.tsx",
+      "./src/lib/*/index.ts",
+      "./src/lib/*/index.tsx"
+    ],
+    "./types/*": "./src/types/*.ts",
+    "./types": "./src/types/index.ts",
+    "./locales": "./src/locales.ts"
+  },
+  "dependencies": {
+    "fumadocs-core": "16.17.8",
+    "lucide-react": "^1.63.0",
+    "@terrafirmagreg-team/game": "0.1.0",
+    "@terrafirmagreg-team/quest": "0.1.0",
+    "@terrafirmagreg-team/recipe": "0.1.0",
+    "@terrafirmagreg-team/translate": "0.1.0",
+    "@terrafirmagreg-team/ui": "0.1.0",
+    "@terrafirmagreg-team/kit": "0.1.0",
+    "@terrafirmagreg-team/comments": "0.1.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",
+    "styles",
+    "styles.css"
+  ]
 }

package/src/components/book-switcher.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+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 { useLocationSearch } 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/kit/lib/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 } = parseSectionLocation(usePathname());
+  const lang = useResolvedLang();
+  const { bookId } = guideQueryFromParams(
+    new URLSearchParams(useLocationSearch()),
+  );
+  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('ui.select_book')}
+    />
+  );
+}

package/src/components/views/browser.tsx

@@ -0,0 +1,124 @@
+'use client';
+
+import { useEffect, useMemo } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+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';
+
+const MESSAGE_KEYS: readonly string[] = [
+  'guide.related',
+  'guide.objective',
+  'guide.link',
+  'guide.quest',
+  'guide.recipe_empty',
+  'guide.entity_unavailable',
+  'guide.entry_missing',
+  'guide.entry_count',
+  'guide.page_count',
+];
+
+export function GuideBrowser({
+  dataset,
+  datasetTitle,
+  lang,
+}: {
+  dataset: string;
+  datasetTitle: string;
+  lang: Lang;
+}) {
+  const t = useTranslations();
+  const router = useRouter();
+  const params = useSearchParams();
+  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>(
+    () => Object.fromEntries(MESSAGE_KEYS.map((key) => [key, t(key)])),
+    [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} />;
+}

package/src/components/views/entry/pages.tsx

@@ -0,0 +1,186 @@
+import type { ReactNode } from 'react';
+import { PageText } from '@terrafirmagreg-team/guide/components/views/page/text';
+import {
+  EntityPage,
+  ImagePage,
+  MultiMultiblockPage,
+  MultiblockPage,
+  MultiblockVisual,
+} from '@terrafirmagreg-team/guide/components/views/kind/media';
+import {
+  LinkPage,
+  QuestPage,
+  RelationPage,
+} from '@terrafirmagreg-team/guide/components/views/kind/links';
+import {
+  RecipePage,
+  SpotlightPage,
+} from '@terrafirmagreg-team/guide/components/views/kind/recipe';
+import { TablePage } from '@terrafirmagreg-team/guide/components/views/kind/table';
+import { UnknownPage } from '@terrafirmagreg-team/guide/components/views/kind/unknown';
+import type { PageRendererProps } from '@terrafirmagreg-team/guide/types';
+import type { AtlasBundle } from '@terrafirmagreg-team/game/lib/dump/assets/atlas/dto';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import { guideMessage } from '@terrafirmagreg-team/guide/lib/messages';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+import type { GuideBookMeta } from '@terrafirmagreg-team/guide/types';
+import type {
+  GuideBook,
+  GuideEntryExtras,
+  GuideEntryRef,
+  GuideMessages,
+  GuidePage,
+} from '@terrafirmagreg-team/guide/types';
+import {
+  guidePageTitles,
+  pageAnchors,
+  pageIcons,
+  repeatedTitle,
+} from '@terrafirmagreg-team/guide/lib/toc';
+import { classify, isIndexPage, type PageKind, pageTexts } from '@terrafirmagreg-team/guide/lib/page-kind';
+import {
+  EntryGroup,
+  GROUP_CYCLE_MS,
+} from '@terrafirmagreg-team/game/components/entry/group';
+import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
+
+const renderers: Record<
+  Exclude<PageKind, 'empty' | 'text'>,
+  (props: PageRendererProps) => ReactNode
+> = {
+  image: ImagePage,
+  recipe: RecipePage,
+  spotlight: SpotlightPage,
+  entity: EntityPage,
+  multiblock: MultiblockPage,
+  multimultiblock: MultiMultiblockPage,
+  link: LinkPage,
+  relations: RelationPage,
+  quest: QuestPage,
+  table: TablePage,
+  unknown: UnknownPage,
+};
+
+export function EntryPages({
+  dataset,
+  lang,
+  bookPath,
+  pages,
+  atlases,
+  meta,
+  bookModId,
+  categoryByEntry,
+  book,
+  langMap,
+  entryRefs,
+  keybinds,
+  extras,
+  questLinks,
+  previews,
+  messages,
+}: {
+  dataset: string;
+  lang: Lang;
+  bookPath: string;
+  pages: GuidePage[];
+  atlases?: Record<string, AtlasBundle>;
+  meta?: GuideBookMeta;
+  bookModId: string;
+  categoryByEntry: Map<string, string>;
+  book?: GuideBook | null;
+  langMap: Record<string, string>;
+  entryRefs: Map<string, GuideEntryRef>;
+  keybinds?: Record<string, string>;
+  extras?: GuideEntryExtras;
+  questLinks?: Record<string, { filename: string; questId: string }>;
+  previews?: Record<string, PagePreviewData>;
+  messages: GuideMessages;
+}) {
+  const titles = guidePageTitles(
+    pages,
+    langMap,
+    {
+      related: guideMessage(messages, 'guide.related'),
+      objective: guideMessage(messages, 'guide.objective'),
+    },
+    extras?.entityNames,
+  );
+  const anchors = pageAnchors(pages);
+  return (
+    <div className="space-y-6">
+      {pages.map((page, index) => {
+        if (isIndexPage(page, langMap)) return null;
+        const kind = classify(page.type);
+        const attachedValue =
+          kind === 'multiblock' || kind === 'multimultiblock'
+            ? undefined
+            : (page.model ?? page.multiblock);
+        if (kind === 'empty' && !attachedValue && !pageTexts(page).length) {
+          return null;
+        }
+        const rendererProps: PageRendererProps = {
+          dataset,
+          lang,
+          bookPath,
+          page,
+          atlases,
+          meta: meta ?? {},
+          bookModId,
+          categoryByEntry,
+          langMap,
+          entryRefs,
+          keybinds,
+          book,
+          extras,
+          questLinks,
+          previews,
+          messages,
+        };
+        const Renderer =
+          kind === 'text' || kind === 'empty' ? undefined : renderers[kind];
+        const heading =
+          kind === 'image' || repeatedTitle(titles, index)
+            ? undefined
+            : titles[index];
+        const icons = pageIcons(page);
+        return (
+          <section
+            key={index}
+            id={anchors[index]}
+            className="scroll-mt-20 space-y-3"
+          >
+            {heading ? (
+              <h2 className="flex items-center gap-2 text-xl font-semibold">
+                {icons.length > 1 ? (
+                  <EntryGroup members={icons} size="lg" cycle={GROUP_CYCLE_MS} />
+                ) : icons[0] ? (
+                  <Entry
+                    id={icons[0].id}
+                    kind={icons[0].kind}
+                    dataset={dataset}
+                    name={heading}
+                    href={false}
+                    tooltip={false}
+                    missing="hide"
+                  />
+                ) : null}
+                {heading}
+              </h2>
+            ) : null}
+            {attachedValue ? (
+              <MultiblockVisual
+                value={attachedValue}
+                title={
+                  typeof page.name === 'string' ? page.name : undefined
+                }
+                glbs={extras?.glbs}
+              />
+            ) : null}
+            {Renderer ? <Renderer {...rendererProps} /> : null}
+            <PageText {...rendererProps} />
+          </section>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,60 @@
+import { EntryPages } from '@terrafirmagreg-team/guide/components/views/entry/pages';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type {
+  GuideBook,
+  GuideEntry,
+  GuideEntryExtras,
+  GuideEntryRef,
+  GuideMessages,
+} from '@terrafirmagreg-team/guide/types';
+
+export function EntryView({
+  dataset,
+  lang,
+  bookPath,
+  entry,
+  bookModId,
+  categoryByEntry,
+  book,
+  langMap,
+  entryRefs,
+  extras,
+  questLinks,
+  previews,
+  messages,
+}: {
+  dataset: string;
+  lang: Lang;
+  bookPath: string;
+  entry: GuideEntry;
+  bookModId: string;
+  categoryByEntry: Map<string, string>;
+  book?: GuideBook | null;
+  langMap: Record<string, string>;
+  entryRefs: Map<string, GuideEntryRef>;
+  extras?: GuideEntryExtras;
+  questLinks?: Record<string, { filename: string; questId: string }>;
+  previews?: Record<string, PagePreviewData>;
+  messages: GuideMessages;
+}) {
+  return (
+    <EntryPages
+      dataset={dataset}
+      lang={lang}
+      bookPath={bookPath}
+      pages={entry.pages ?? []}
+      atlases={extras?.atlases}
+      bookModId={bookModId}
+      categoryByEntry={categoryByEntry}
+      book={book}
+      langMap={langMap}
+      entryRefs={entryRefs}
+      keybinds={extras?.keybinds}
+      extras={extras}
+      questLinks={questLinks}
+      previews={previews}
+      messages={messages}
+    />
+  );
+}

package/src/components/views/kind/links.tsx

@@ -0,0 +1,111 @@
+import { LinkPreview } from '@terrafirmagreg-team/ui/components/blocks/link/link-preview';
+import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
+import { questHref } from '@terrafirmagreg-team/quest/lib/links';
+import { guideMessage } from '@terrafirmagreg-team/guide/lib/messages';
+import {
+  entryLabel,
+  entryRef,
+  spriteName,
+} from '@terrafirmagreg-team/guide/lib/names';
+import { referenceHref } from '@terrafirmagreg-team/guide/lib/reference';
+import { parseGuideReference } from '@terrafirmagreg-team/guide/lib/reference/resolver';
+import type { PageRendererProps } from '@terrafirmagreg-team/guide/types';
+
+export function RelationPage(props: PageRendererProps) {
+  const ids = (props.page.entries ?? []).filter(
+    (value): value is string => typeof value === 'string' && Boolean(value),
+  );
+  if (!ids.length) return null;
+  return (
+    <ul className="space-y-1">
+      {ids.map((id) => {
+        const resolved = referenceHref(props, id);
+        const ref = entryRef(props.entryRefs, id);
+        const name = entryLabel(props.entryRefs, props.langMap, id);
+        return (
+          <li key={id} className="flex items-center gap-2">
+            {ref?.icon ? (
+              <Entry
+                id={ref.icon.id}
+                kind={ref.icon.kind}
+                dataset={props.dataset}
+                size="sm"
+                href={false}
+                tooltip={false}
+              />
+            ) : null}
+            {resolved ? (
+              <LinkPreview
+                variant="text"
+                href={resolved.href}
+                preview={props.previews?.[resolved.href]}
+              >
+                {name}
+              </LinkPreview>
+            ) : (
+              <span className="text-muted-foreground">{name}</span>
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+export function LinkPage(props: PageRendererProps) {
+  const target = props.page.url || props.page.link || props.page.entry || '';
+  const resolved = target ? referenceHref(props, target) : null;
+  const label =
+    (typeof props.page.link_text === 'string' && props.page.link_text) ||
+    (typeof props.page.text === 'string' && props.page.text) ||
+    (typeof props.page.name === 'string' && props.page.name) ||
+    target ||
+    guideMessage(props.messages, 'guide.link');
+  return (
+    <p>
+      {resolved ? (
+        <LinkPreview
+          variant="chip"
+          solid
+          href={resolved.href}
+          preview={props.previews?.[resolved.href]}
+        >
+          {label}
+        </LinkPreview>
+      ) : (
+        <span className="text-muted-foreground">{label}</span>
+      )}
+    </p>
+  );
+}
+
+export function QuestPage({
+  dataset,
+  page,
+  lang,
+  langMap,
+  atlases,
+  questLinks,
+  previews,
+  messages,
+}: PageRendererProps) {
+  const id = page.trigger || page.quest || page.link;
+  const hit = id ? questLinks?.[parseGuideReference(id).id] : undefined;
+  const href = hit
+    ? questHref(dataset, lang, { category: hit.filename, id: hit.questId })
+    : undefined;
+  const name = id ? spriteName(dataset, langMap, atlases, id) : '—';
+  const label = id && name !== id ? name : <code>{name}</code>;
+  return (
+    <p className="text-sm text-muted-foreground">
+      {guideMessage(messages, 'guide.quest')}:{' '}
+      {href ? (
+        <LinkPreview href={href} preview={previews?.[href]}>
+          {label}
+        </LinkPreview>
+      ) : (
+        label
+      )}
+    </p>
+  );
+}