@terrafirmagreg-team/guide 1.2.2 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrafirmagreg-team/guide",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "type": "module",
   "description": "Guide/books section",
   "license": "LGPL-3.0-only",
@@ -24,17 +24,17 @@
   "dependencies": {
     "@terrafirmagreg-team/data": "1.2.1",
     "@terrafirmagreg-team/discussions": "1.2.3",
-    "@terrafirmagreg-team/dump": "1.2.1",
-    "@terrafirmagreg-team/game": "1.2.2",
-    "@terrafirmagreg-team/kit": "1.2.2",
-    "@terrafirmagreg-team/mdx": "1.2.1",
+    "@terrafirmagreg-team/dump": "1.2.2",
+    "@terrafirmagreg-team/game": "1.2.3",
+    "@terrafirmagreg-team/kit": "1.2.4",
+    "@terrafirmagreg-team/mdx": "1.2.2",
     "@terrafirmagreg-team/preview": "1.2.1",
-    "@terrafirmagreg-team/search": "1.2.2",
+    "@terrafirmagreg-team/search": "1.2.3",
     "@terrafirmagreg-team/sites": "1.2.1",
-    "@terrafirmagreg-team/translate": "1.2.3",
-    "@terrafirmagreg-team/ui": "1.2.2",
-    "fumadocs-core": "16.17.8",
-    "lucide-react": "^0.577.0"
+    "@terrafirmagreg-team/translate": "1.2.4",
+    "@terrafirmagreg-team/ui": "1.2.3",
+    "fumadocs-core": "16.17.10",
+    "lucide-react": "^1.63.0"
   },
   "peerDependencies": {
     "next": ">=15",

package/src/components/mdx/multiblock.tsx

@@ -22,7 +22,7 @@ export type MdxMultiblockProps = {
   name?: string;
   spec?: string;
   label?: string;
-  dataset?: DatasetRef;
+  dataset?: DatasetRef | string;
   title?: string;
 };
 
@@ -36,10 +36,17 @@ export function MdxMultiblock({
 }: MdxMultiblockProps) {
   const pathname = usePathname();
   const locId = parseSectionLocation(pathname).dataset;
-  const dataset = useMemo<DatasetRef>(
-    () => datasetProp ?? { id: locId ?? '' },
-    [datasetProp, locId],
-  );
+  const dataset = useMemo<DatasetRef>(() => {
+    if (typeof datasetProp === 'string') {
+      const trimmed = datasetProp.trim();
+      try {
+        return JSON.parse(trimmed) as DatasetRef;
+      } catch {
+        return { id: trimmed };
+      }
+    }
+    return datasetProp ?? { id: locId ?? '' };
+  }, [datasetProp, locId]);
   const lang = useContext(ResolvedLangContext)?.lang;
   const dumpLoc = useDumpLocation(dataset);
   const resolveResource = useMemo(

package/src/components/views/browser.tsx

@@ -5,25 +5,40 @@ import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-
 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 { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
 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 { WorkspaceBody } from '@terrafirmagreg-team/ui/components/layouts/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 { getGuideSource } from '@terrafirmagreg-team/guide/lib/source';
 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 GuideBrowserFallback() {
+  return (
+    <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>
+  );
+}
+
 export function GuideBrowser({
   dataset: id,
   datasetTitle,
@@ -43,8 +58,9 @@ export function GuideBrowser({
     () => guideQueryFromParams(params),
     [params],
   );
+  const source = getGuideSource();
   const books = useAsyncValue(
-    () => listGuideBooks(dataset, lang),
+    () => source.books(dataset, lang),
     [dataset, lang],
   );
   const langMap = useLangMap(dataset, lang);
@@ -69,17 +85,18 @@ export function GuideBrowser({
     [t],
   );
 
+  const resolved = useResolvedLang();
   const canonical = useAsyncValue(
     books && !bookId
       ? async () => {
           const book = books[0];
           if (!book) return undefined;
-          const index = await loadClientGuideBook(dataset, lang, book.bookId);
+          const index = await source.book(dataset, lang, book.bookId);
           const first = index ? firstGuideEntryId(index) : undefined;
-          return guideHref(dataset, lang, book.bookId, first);
+          return guideHref(dataset, resolved, book.bookId, first);
         }
       : undefined,
-    [books, bookId, dataset, lang],
+    [books, bookId, dataset, lang, resolved],
   );
 
   useEffect(() => {
@@ -89,7 +106,7 @@ export function GuideBrowser({
   const payload = useAsyncValue(
     langMap && bookId
       ? () =>
-          loadClientGuidePayload(
+          source.payload(
             dataset,
             lang,
             bookId,
@@ -109,24 +126,7 @@ export function GuideBrowser({
   }, [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 <GuideBrowserFallback />;
   }
   return <GuidePageView payload={payload} langMap={langMap} />;
 }

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

@@ -18,12 +18,12 @@ export function RelationPage(props: PageRendererProps) {
   if (!ids.length) return null;
   return (
     <ul className="space-y-1">
-      {ids.map((id) => {
+      {ids.map((id, index) => {
         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">
+          <li key={`${id}:${index}`} className="flex items-center gap-2">
             {ref?.icon ? (
               <Entry
                 id={ref.icon.id}

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

@@ -90,10 +90,10 @@ export function TablePage(props: PageRendererProps) {
                     style={{ backgroundColor: cssColor(value?.fill) }}
                   >
                     <span className="inline-flex flex-wrap items-center gap-1">
-                      {items.map((id) => (
+                      {items.map((id, index) => (
                         <Entry
                           kind="item"
-                          key={id}
+                          key={`${id}:${index}`}
                           id={id}
                           name={id}
                           size="sm"

package/src/components/views/landing.tsx

@@ -0,0 +1,32 @@
+import { Suspense } from 'react';
+import { WorkspaceBody } from '@terrafirmagreg-team/ui/components/layouts/workspace';
+import type {
+  SectionLandingProps,
+  SectionLandingView,
+} from '@terrafirmagreg-team/kit/components/views/routes';
+import type { GuideSource } from '@terrafirmagreg-team/guide/lib/source';
+import {
+  GuideBrowser,
+  GuideBrowserFallback,
+} from '@terrafirmagreg-team/guide/components/views/browser';
+
+export function guideLanding({
+  page,
+  lang,
+}: SectionLandingProps<GuideSource>): SectionLandingView {
+  return {
+    node: (
+      <WorkspaceBody className="viewport-body">
+        <Suspense fallback={<GuideBrowserFallback />}>
+          <GuideBrowser
+            dataset={page.dataset.id}
+            datasetTitle={page.datasetTitle ?? page.dataset.id}
+            lang={lang}
+            versions={page.versions}
+          />
+        </Suspense>
+      </WorkspaceBody>
+    ),
+    workspace: { pagination: false },
+  };
+}

package/src/components/views/layout.tsx

@@ -0,0 +1,14 @@
+import { Layout } from '@terrafirmagreg-team/kit/components/layouts/layout';
+import type { SectionLayoutViewProps } from '@terrafirmagreg-team/kit/components/views/routes';
+import { GuideBookSwitcher } from '@terrafirmagreg-team/guide/components/book-switcher';
+import { useGuideLeftSidebarTree } from '@terrafirmagreg-team/guide/hooks/use-left-sidebar-tree';
+
+export function GuideLayout(props: SectionLayoutViewProps) {
+  return (
+    <Layout
+      {...props}
+      useTree={useGuideLeftSidebarTree}
+      sidebar={{ feature: GuideBookSwitcher }}
+    />
+  );
+}

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

@@ -1,11 +1,16 @@
+'use client';
+import { useMemo } from 'react';
 import { EntryProvider } from '@terrafirmagreg-team/game/hooks/use-entry-context';
 import { Entry } from '@terrafirmagreg-team/game/components/entry/entry';
 import {
-  Workspace,
+  useWorkspaceSlots,
+  type WorkspaceSlots,
+} from '@terrafirmagreg-team/kit/components/views/frame';
+import {
   WorkspaceBody,
   WorkspaceDescription,
   WorkspaceTitle,
-} from '@terrafirmagreg-team/kit/components/workspace';
+} from '@terrafirmagreg-team/ui/components/layouts/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';
@@ -203,14 +208,21 @@ export function GuidePageView({
     UntranslatedCallout,
   } = guideConfig().components;
 
+  const slots = useMemo<WorkspaceSlots>(
+    () => ({
+      toc: toc ?? [],
+      breadcrumb: { items: crumbs, previews: payload.previews },
+      pagination: { items: nav },
+      full: false,
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [payload, langMap],
+  );
+  useWorkspaceSlots(slots, [slots]);
+
   return (
     <EntryProvider dataset={dataset} lang={lang} langMap={langMap}>
-      <Workspace
-        toc={toc ?? []}
-        className="min-h-full"
-        breadcrumb={{ items: crumbs, previews: payload.previews }}
-        pagination={{ items: nav }}
-      >
+      <div className="flex flex-col gap-4 min-h-full">
         <UntranslatedCallout copied={copied} />
         <WorkspaceTitle>
           {kind === 'entry' && payload.previewIcon ? (
@@ -272,7 +284,7 @@ export function GuidePageView({
         <CommentsSlot
           page={`guide:${dataset.id}:${payload.modId}:${payload.bookPath}:${payload.entry?.id ?? payload.categoryId ?? 'book'}#${lang}`}
         />
-      </Workspace>
+      </div>
     </EntryProvider>
   );
 }

package/src/lib/breadcrumb.ts

@@ -50,7 +50,7 @@ export function guideBreadcrumbItems({
           : undefined,
     });
   }
-  items.push({ name: title });
+  if (kind !== 'category' || !cat) items.push({ name: title });
   return items;
 }
 

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

@@ -93,9 +93,7 @@ export async function loadClientGuidePayload(
     title: entry?.name ?? category?.name ?? overview.book?.name ?? bookId,
     modId: bookModId,
     bookPath,
-    description: entry
-      ? undefined
-      : (category?.description ?? overview.book?.landingText),
+    description: entry ? undefined : category?.description,
     previewIcon:
       entry?.icon?.id ?? category?.icon?.id ?? overview.book?.cover?.id,
     previewKind: entry?.icon?.kind ?? category?.icon?.kind,

package/src/lib/format.ts

@@ -191,6 +191,23 @@ export function formatGuide(
   return out;
 }
 
+export function guidePlainText(
+  raw: string,
+  options: GuideFormatOptions = {},
+): string {
+  return formatGuide(raw, options)
+    .map((node) =>
+      node.type === 'break'
+        ? ' '
+        : 'value' in node
+          ? node.value
+          : '',
+    )
+    .join('')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+}
+
 export function guideFormatOpts(props: PageRendererProps) {
   return {
     dataset: props.dataset,

package/src/lib/multiblock/url.ts

@@ -3,8 +3,8 @@ import { asRecord, asString } from '@terrafirmagreg-team/dump/lib/dump/contract/
 import { splitDumpId } from '@terrafirmagreg-team/dump/lib/dump/paths';
 import { modelPublicUrl } from '@terrafirmagreg-team/dump/lib/dump/assets/urls';
 import {
-  clientDumpJson,
   dumpModelUrl,
+  multiblockModelIndex,
 } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
 import { loadDatasetDump } from '@terrafirmagreg-team/dump/lib/dump/mods/load';
 import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
@@ -29,10 +29,7 @@ const multiblockIndex = createDatasetCache(async (dataset: DatasetRef) => {
   const entries = await Promise.all(
     (dump?.mods ?? []).map(async (ns) => {
       const index = asRecord(
-        await clientDumpJson(
-          dataset,
-          `data/${ns.namespace}/models/multiblock.json`,
-        ),
+        await multiblockModelIndex(dataset, ns.namespace),
       );
       return Object.entries(index ?? {}).map(
         ([id, rel]) => [id, { ns: ns.namespace, rel: asString(rel) }] as const,

package/src/lib/preview.ts

@@ -1,5 +1,6 @@
 import { registerPreviewResolver } from '@terrafirmagreg-team/preview/lib';
 import { loadClientGuideBook } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { guidePlainText } from '@terrafirmagreg-team/guide/lib/format';
 import { entryPreviewIcon } from '@terrafirmagreg-team/game/lib/preview';
 import type { PreviewResolverCtx } from '@terrafirmagreg-team/preview/lib';
 import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
@@ -8,6 +9,7 @@ export async function guideLinkPreview({
   parts,
   query,
   lang,
+  langMap,
 }: PreviewResolverCtx): Promise<PagePreviewData | undefined> {
   const dataset = {
     id: parts[1] ?? '',
@@ -28,7 +30,12 @@ export async function guideLinkPreview({
   }
   return {
     title: index.book?.name ?? bookId,
-    description: index.book?.landingText,
+    description: index.book?.landingText
+      ? guidePlainText(index.book.landingText, {
+          macros: index.book?.macros,
+          langMap,
+        })
+      : undefined,
     icon: entryPreviewIcon(index.book?.cover ?? undefined, dataset),
   };
 }

package/src/lib/recipe.ts

@@ -3,9 +3,13 @@ import type { EmbedRecipe } from '@terrafirmagreg-team/guide/lib/embeds';
 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),
-  );
+  return [
+    ...new Set(
+      (page.recipes ?? []).filter(
+        (id): id is string => typeof id === 'string' && Boolean(id),
+      ),
+    ),
+  ];
 }
 
 export function recipeNameScope(

package/src/lib/source.ts

@@ -0,0 +1,13 @@
+import { listGuideBooks } from '@terrafirmagreg-team/guide/lib/books';
+import { loadClientGuideBook } from '@terrafirmagreg-team/guide/lib/client/guides';
+import { loadClientGuidePayload } from '@terrafirmagreg-team/guide/lib/client-payload';
+
+export function getGuideSource() {
+  return {
+    books: listGuideBooks,
+    book: loadClientGuideBook,
+    payload: loadClientGuidePayload,
+  };
+}
+
+export type GuideSource = ReturnType<typeof getGuideSource>;