@terrafirmagreg-team/kit 0.0.0-stage → 1.2.0

package/src/components/workspace/content.tsx

@@ -0,0 +1,54 @@
+'use client';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import type { ComponentProps } from 'react';
+
+export function WorkspaceBody({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="workspace-body"
+      {...props}
+      className={cn('prose flex-1', className)}
+    />
+  );
+}
+
+export function WorkspaceDescription({
+  children,
+  className,
+  ...props
+}: ComponentProps<'p'>) {
+  if (children === undefined) return null;
+  return (
+    <p
+      data-slot="workspace-description"
+      {...props}
+      className={cn('mb-8 text-lg text-muted-foreground', className)}
+    >
+      {children}
+    </p>
+  );
+}
+
+export function WorkspaceTitle({ className, ...props }: ComponentProps<'h1'>) {
+  return (
+    <h1
+      data-slot="workspace-title"
+      {...props}
+      className={cn('text-[1.75em] font-semibold', className)}
+    />
+  );
+}
+
+export function WorkspaceFooter({
+  className,
+  ...props
+}: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="workspace-footer"
+      className={cn('mt-auto empty:hidden', className)}
+      {...props}
+    />
+  );
+}
+

package/src/components/workspace/index.ts

@@ -0,0 +1,13 @@
+export type {
+  WorkspacePaginationItems,
+  WorkspaceProps,
+} from './workspace';
+export { Workspace } from './workspace';
+export {
+  WorkspaceBody,
+  WorkspaceDescription,
+  WorkspaceTitle,
+  WorkspaceFooter,
+} from './content';
+export { WorkspacePagination } from './pagination';
+

package/src/components/workspace/pagination.tsx

@@ -0,0 +1,74 @@
+'use client';
+import { type ComponentProps, useMemo } from 'react';
+import { usePathname } from 'next/navigation';
+import Link from '@terrafirmagreg-team/ui/components/blocks/nav/link';
+import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react';
+import { useFooterItems } from '@terrafirmagreg-team/ui/hooks/use-tree';
+import { useLocationSearch } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { isNavItemActive } from '@terrafirmagreg-team/ui/lib/utils/nav-active';
+import type { WorkspacePaginationItems } from './workspace';
+
+export function WorkspacePagination({
+  items,
+  className,
+  ...props
+}: ComponentProps<'nav'> & { items?: WorkspacePaginationItems }) {
+  const footerList = useFooterItems();
+  const pathname = usePathname();
+  const search = useLocationSearch();
+  const { previous, next } = useMemo(() => {
+    if (items) return items;
+    const idx = footerList.findIndex((item) =>
+      isNavItemActive(item.url, pathname, search),
+    );
+    if (idx === -1) return {};
+    return { previous: footerList[idx - 1], next: footerList[idx + 1] };
+  }, [footerList, items, pathname, search]);
+
+  if (!previous && !next) return null;
+  return (
+    <nav
+      data-slot="workspace-pagination"
+      className={cn('@container grid grid-cols-2 gap-3 mt-8', className)}
+      {...props}
+    >
+      {previous && <WorkspacePaginationItem item={previous} next={false} />}
+      {next && <WorkspacePaginationItem item={next} next />}
+    </nav>
+  );
+}
+
+function WorkspacePaginationItem({
+  item,
+  next,
+}: {
+  item: NonNullable<WorkspacePaginationItems['previous']>;
+  next: boolean;
+}) {
+  const t = useTranslations();
+  const Icon = next ? ArrowRightIcon : ArrowLeftIcon;
+
+  return (
+    <Link
+      href={item.url}
+      className={cn(
+        'group flex flex-col gap-1 rounded-2xl border p-4 text-sm transition-colors hover:bg-accent/40 @max-md:col-span-full',
+        next && 'col-start-2 items-end text-end',
+      )}
+    >
+      <span className="inline-flex items-center gap-1.5 text-muted-foreground">
+        {!next && (
+          <Icon className="size-3.5 transition-transform group-hover:-translate-x-0.5 rtl:rotate-180" />
+        )}
+        {next ? t('Next Page', { note: 'ui.next_page' }) : t('Previous Page', { note: 'ui.prev_page' })}
+        {next && (
+          <Icon className="size-3.5 transition-transform group-hover:translate-x-0.5 rtl:rotate-180" />
+        )}
+      </span>
+      <span className="font-medium">{item.name}</span>
+    </Link>
+  );
+}
+

package/src/components/workspace/workspace.tsx

@@ -0,0 +1,149 @@
+'use client';
+import type { ComponentProps, ReactNode } from 'react';
+import { usePathname } from 'next/navigation';
+import type * as PageTree from '@terrafirmagreg-team/translate/types/tree';
+import type { TOCItemType } from '@terrafirmagreg-team/kit/components/toc/base';
+import { TOCProvider } from '@terrafirmagreg-team/kit/components/toc/base';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+import {
+  RightSidebarOutline,
+  WorkspaceOutlineDropdown,
+  WorkspaceOutlinePopover,
+  type OutlineProps,
+  type WorkspaceOutlinePopoverProps,
+} from '@terrafirmagreg-team/kit/components/outline';
+import { LeftSidebarExpand } from '@terrafirmagreg-team/ui/components/layouts/left-sidebar';
+import { Breadcrumb } from '@terrafirmagreg-team/ui/components/blocks/nav/breadcrumb';
+import { WorkspaceFooter } from './content';
+import { WorkspacePagination } from './pagination';
+
+export type WorkspacePaginationItems = {
+  previous?: Pick<PageTree.Item, 'name' | 'description' | 'url'>;
+  next?: Pick<PageTree.Item, 'name' | 'description' | 'url'>;
+};
+
+export type WorkspaceProps = ComponentProps<'article'> & {
+  toc?: TOCItemType[];
+
+  full?: boolean;
+  outline?: OutlineProps & { enabled?: boolean; single?: boolean };
+  outlinePopover?: WorkspaceOutlinePopoverProps & { enabled?: boolean };
+  breadcrumb?: {
+    items?: { name: string; url?: string }[];
+    previews?: Record<string, PagePreviewData>;
+  };
+  pagination?: { items?: WorkspacePaginationItems } | false;
+
+  actions?: ReactNode;
+
+  footer?: ReactNode;
+};
+
+export function Workspace({
+  toc = [],
+  full = false,
+  outline = {},
+  outlinePopover = {},
+  breadcrumb,
+  pagination = {},
+  actions,
+  footer,
+  className,
+  children,
+  ...props
+}: WorkspaceProps) {
+  const { enabled: outlineEnabled = !full, single, ...outlineProps } = outline;
+  const { enabled: popoverEnabled = Boolean(toc.length > 0 || outlinePopover.header || outlinePopover.footer), ...popoverProps } = outlinePopover;
+  const crumbs = breadcrumb?.items ?? [];
+  const hasCrumbs = crumbs.length > 0;
+  const pathname = usePathname();
+
+  return (
+    <TOCProvider
+      single={single}
+      toc={outlineEnabled || popoverEnabled ? toc : []}
+    >
+      <div
+        data-slot="workspace-outline-popover"
+        className="sticky top-[calc(var(--banner-height,0px)+var(--header-height))] z-30 [grid-area:toc-popover] self-start md:hidden"
+      >
+        {popoverEnabled && <WorkspaceOutlinePopover {...popoverProps} />}
+        <div className="absolute inset-x-2 top-full h-[calc(var(--layout-height)_-_var(--header-height)_-_100%)] rounded-t-2xl border-x border-t outline-8 outline-card [clip-path:inset(0_-8px_-8px)] bg-origin-border bg-linear-to-b from-background to-transparent to-[16px] pointer-events-none" />
+      </div>
+      <div
+        key={pathname}
+        id="page-panel"
+        data-slot="workspace-panel"
+        className="@container relative flex flex-col min-w-0 min-h-0 [grid-area:main] mx-2 bg-background md:ms-0 md:my-2 md:overflow-clip md:rounded-2xl md:border md:shadow-sm print:overflow-visible"
+      >
+        <header
+          data-slot="workspace-header"
+          className={cn(
+            'absolute inset-x-0 top-0 z-10 flex items-center gap-1.5 h-(--header-height) ps-6 pe-4 bg-linear-to-b from-background to-transparent pointer-events-none *:pointer-events-auto max-md:hidden',
+            hasCrumbs || popoverEnabled ? 'from-50%' : 'to-40%',
+          )}
+        >
+          <LeftSidebarExpand />
+          {hasCrumbs && (
+            <Breadcrumb
+              items={crumbs}
+              previews={breadcrumb?.previews}
+            />
+          )}
+          {popoverEnabled && (
+            <div
+              className={cn(
+                'flex items-center gap-1.5 min-w-0 transition-[opacity,visibility] duration-300 motion-reduce:transition-none',
+                outlineEnabled &&
+                  'invisible opacity-0 @max-5xl:visible @max-5xl:opacity-100 @max-5xl:transition-none',
+              )}
+            >
+              {hasCrumbs && (
+                <span className="text-sm text-muted-foreground/50">/</span>
+              )}
+              <WorkspaceOutlineDropdown {...popoverProps} />
+            </div>
+          )}
+          <div data-slot="workspace-actions" className="ms-auto">
+            {actions}
+          </div>
+        </header>
+        <div
+          data-slot="workspace-scroll"
+          className="flex flex-1 items-start px-4 md:min-h-0 md:pt-(--header-height) md:px-[max(--spacing(6),calc((100%_-_var(--page-width)_-_var(--toc-width))/2))] md:overflow-y-auto md:overscroll-y-contain md:scrollbar-thin md:scrollbar-gutter-stable md:[--docs-height:calc(var(--layout-height)_-_var(--spacing)*4_-_2px_-_var(--header-height))]"
+        >
+          <article
+            id="page"
+            data-slot="workspace"
+            data-full={full}
+            className={cn(
+              'flex flex-col gap-4 w-full min-w-0 max-w-(--page-width) pt-6 pb-8',
+              className,
+            )}
+            {...props}
+          >
+            {hasCrumbs && (
+              <Breadcrumb
+                items={crumbs}
+                previews={breadcrumb?.previews}
+                className="md:hidden"
+              />
+            )}
+            {children}
+            {pagination !== false || footer ? (
+              <WorkspaceFooter>
+                {pagination !== false && (
+                  <WorkspacePagination items={pagination.items} />
+                )}
+                {footer}
+              </WorkspaceFooter>
+            ) : null}
+          </article>
+          {outlineEnabled && <RightSidebarOutline {...outlineProps} />}
+        </div>
+      </div>
+    </TOCProvider>
+  );
+}
+

package/src/hooks/use-catalog.ts

@@ -0,0 +1,12 @@
+'use client';
+import { createContext, useContext } from 'react';
+import type { DatasetCatalog } from '@terrafirmagreg-team/kit/types';
+
+export const SectionCatalogContext = createContext<DatasetCatalog | null>(null);
+
+export function useSectionCatalog(): DatasetCatalog {
+  const catalog = useContext(SectionCatalogContext);
+  if (!catalog) throw new Error('SectionCatalogContext is not provided');
+  return catalog;
+}
+

package/src/hooks/use-current-dataset.ts

@@ -0,0 +1,24 @@
+'use client';
+import { useMemo } from 'react';
+import { usePathname } from 'next/navigation';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import {
+  type DatasetRef,
+  parseSectionLocation,
+  resolveDatasetRef,
+} from '@terrafirmagreg-team/sites/location';
+import type { SectionDataset } from '@terrafirmagreg-team/kit/types';
+
+export function useCurrentDataset(
+  datasets: readonly SectionDataset[],
+): DatasetRef | undefined {
+  const pathname = usePathname();
+  const versionParam = useLocationSearchParams().get('version') ?? undefined;
+  const { dataset } = parseSectionLocation(pathname);
+  const meta = datasets.find((row) => row.id === dataset);
+  return useMemo(
+    () => dataset && meta ? resolveDatasetRef(dataset, versionParam, meta).ref : undefined,
+    [dataset, versionParam, meta],
+  );
+}
+

package/src/hooks/use-dataset-accent.ts

@@ -0,0 +1,14 @@
+'use client';
+import { useLayoutEffect } from 'react';
+
+export function useDatasetAccent(accent?: string) {
+  useLayoutEffect(() => {
+    if (!accent) return;
+    const root = document.documentElement;
+    root.style.setProperty('--color-link-accent', accent);
+    return () => {
+      root.style.removeProperty('--color-link-accent');
+    };
+  }, [accent]);
+}
+

package/src/hooks/use-nav-options.ts

@@ -0,0 +1,87 @@
+'use client';
+import { type ReactNode, createElement, useMemo } from 'react';
+import { DynamicIcon, type IconName } from 'lucide-react/dynamic';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { sectionTabs } from '@terrafirmagreg-team/sites/sections';
+import {
+  isDumpSection,
+  resolveDatasetRef,
+  sectionUrl,
+} from '@terrafirmagreg-team/sites/location';
+import { useCurrentDataset } from '@terrafirmagreg-team/kit/hooks/use-current-dataset';
+import { useSectionNames } from '@terrafirmagreg-team/kit/hooks/use-section-names';
+import { useVersionPreference } from '@terrafirmagreg-team/kit/hooks/use-version-pref';
+import type { LeftSidebarScope } from '@terrafirmagreg-team/kit/types';
+import type {
+  SwitcherOption,
+  SwitcherProps,
+} from '@terrafirmagreg-team/ui/types/nav';
+
+function datasetIcon(dataset: { icon?: IconName }): ReactNode {
+  if (!dataset.icon) return undefined;
+  return createElement(DynamicIcon, {
+    name: dataset.icon,
+    className: 'size-4 shrink-0',
+  });
+}
+
+export function useNavOptions({ section, catalog }: LeftSidebarScope): {
+  section: SwitcherProps;
+  dataset: SwitcherProps;
+} {
+  const t = useTranslations();
+  const sectionNames = useSectionNames();
+  const current = useCurrentDataset(catalog[section]);
+  const baseId = current ? current.id : undefined;
+  const pinned = current ? current.version : undefined;
+  const preferred = useVersionPreference(baseId);
+  const version = pinned ?? preferred;
+
+  const sectionOptions: SwitcherOption[] = useMemo(
+    () =>
+      sectionTabs.map(({ key, icon: Icon }) => {
+        const meta = baseId
+          ? catalog[key].find(({ id }) => id === baseId)
+          : undefined;
+        const pinned =
+          isDumpSection(key) && baseId
+            ? resolveDatasetRef(baseId, version, meta).pinned
+            : undefined;
+        const suffix = pinned ? `?version=${encodeURIComponent(pinned)}` : '';
+        return {
+          value: key,
+          title: sectionNames[key]?.title ?? key,
+          description: sectionNames[key]?.desc,
+          icon: Icon ? createElement(Icon) : undefined,
+          url: meta ? `${sectionUrl(key, baseId)}${suffix}` : sectionUrl(key),
+        };
+      }),
+    [sectionNames, baseId, version, catalog],
+  );
+
+  const datasetOptions: SwitcherOption[] = useMemo(
+    () =>
+      catalog[section].map((datasetItem) => ({
+        value: datasetItem.id,
+        title: datasetItem.title ?? datasetItem.id,
+        description: datasetItem.description,
+        icon: datasetIcon(datasetItem),
+        url: sectionUrl(section, datasetItem.id),
+      })),
+    [section, catalog],
+  );
+
+  return {
+    section: {
+      options: sectionOptions,
+      selected: section,
+      placeholder: t('Select section', { note: 'ui.select_section' }),
+    },
+    dataset: {
+      options: datasetOptions,
+      selected: baseId,
+      placeholder: t('Select dataset', { note: 'ui.select_dataset' }),
+    },
+  };
+}
+

package/src/hooks/use-section-names.ts

@@ -0,0 +1,40 @@
+'use client';
+import { useMemo } from 'react';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+
+export function useSectionNames(): Record<
+  string,
+  { title: string; desc: string }
+> {
+  const t = useTranslations();
+  return useMemo(
+    () => ({
+      docs: {
+        title: t('Docs', { note: 'sections.docs' }),
+        desc: t('Documentation', { note: 'sections.desc.docs' }),
+      },
+      changelog: {
+        title: t('Changelog', { note: 'sections.changelog' }),
+        desc: t('Release history and version notes', {
+          note: 'sections.desc.changelog',
+        }),
+      },
+      recipe: {
+        title: t('Recipes', { note: 'sections.recipe' }),
+        desc: t('Crafting and processing recipes', {
+          note: 'sections.desc.recipe',
+        }),
+      },
+      quest: {
+        title: t('Quests', { note: 'sections.quest' }),
+        desc: t('Quest chapters and objectives', { note: 'sections.desc.quest' }),
+      },
+      guide: {
+        title: t('Guide', { note: 'sections.guide' }),
+        desc: t('Gameplay guide', { note: 'sections.desc.guide' }),
+      },
+    }),
+    [t],
+  );
+}
+

package/src/hooks/use-toc.ts

@@ -0,0 +1,10 @@
+'use client';
+import type { TOCItemType } from 'fumadocs-core/toc';
+import { createContext, use } from 'react';
+
+export const TOCContext = createContext<TOCItemType[]>([]);
+
+export function useTOCItems(): TOCItemType[] {
+  return use(TOCContext);
+}
+

package/src/hooks/use-version-pref.ts

@@ -0,0 +1,31 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import {
+  jsonCodec,
+  readStoredValue,
+  subscribeStoredValue,
+  writeStoredValue,
+} from '@terrafirmagreg-team/ui/lib/utils/stored-value';
+
+const STORAGE_KEY = 'tfg.dataset-versions';
+const codec = jsonCodec<Record<string, string>>({});
+
+export function setVersionPreference(datasetId: string, version?: string) {
+  const next = { ...readStoredValue(STORAGE_KEY, codec.read) };
+  if (version) next[datasetId] = version;
+  else delete next[datasetId];
+  writeStoredValue(STORAGE_KEY, next, codec.write);
+}
+
+export function useVersionPreference(datasetId?: string): string | undefined {
+  return useSyncExternalStore(
+    (onChange) => subscribeStoredValue(STORAGE_KEY, onChange),
+    () =>
+      datasetId
+        ? readStoredValue(STORAGE_KEY, codec.read)[datasetId]
+        : undefined,
+    () => undefined,
+  );
+}
+

package/src/hooks/use-versioned-dataset.ts

@@ -0,0 +1,21 @@
+'use client';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+import {
+  resolveDatasetRef,
+  type DatasetVersionInfo,
+  type DatasetRef,
+} from '@terrafirmagreg-team/sites/location';
+
+const refs = new Map<string, DatasetRef | undefined>();
+
+export function useVersionedDataset(
+  id: string | undefined,
+  info?: DatasetVersionInfo,
+): DatasetRef | undefined {
+  const version = useLocationSearchParams().get('version') ?? undefined;
+  const key = `${id ?? ''} ${version ?? ''} ${info?.latest ?? ''} ${info?.versions?.join(',') ?? ''}`;
+  if (!refs.has(key))
+    refs.set(key, id ? resolveDatasetRef(id, version, info).ref : undefined);
+  return refs.get(key);
+}
+

package/src/lib/breadcrumb.ts

@@ -0,0 +1,65 @@
+import 'server-only';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { searchPath } from 'fumadocs-core/breadcrumb';
+import { stripLangFromUrl } from '@terrafirmagreg-team/translate/lib/slug';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { localizePageTree } from '@terrafirmagreg-team/translate/server';
+import { sectionConfig } from './config';
+import { lookupPagePreview } from './preview/lookup';
+import { datasetId } from './tree';
+import type { SectionSource } from './page';
+import type { DatasetCatalog, SectionPage } from '@terrafirmagreg-team/kit/types';
+
+export type SectionCrumb = { name: string; url?: string };
+
+function nodeName(name: unknown): string {
+  return typeof name === 'string' ? name : '';
+}
+
+export function sectionBreadcrumbItems(
+  source: SectionSource,
+  page: SectionPage,
+  lang: Lang,
+): SectionCrumb[] {
+  const languages = [...sectionConfig().knownLanguages];
+  const tree = localizePageTree(source.getPageTree(), lang, {
+    languages,
+    fallbackLanguage: loadLocaleRegistry().defaultLanguage,
+  });
+  const dataset = page.slugs[0];
+  const folder = tree.children.find(
+    (node): node is PageTree.Folder =>
+      node.type === 'folder' && datasetId(node) === dataset,
+  );
+  if (!folder) return [{ name: page.data.title }];
+
+  const pageUrl = stripLangFromUrl(page.url, languages);
+  if (folder.index?.url === pageUrl) return [];
+
+  const trail = searchPath(folder.children, pageUrl);
+  const items: SectionCrumb[] = [];
+  for (const node of trail?.slice(0, -1) ?? []) {
+    if (node.type === 'folder') {
+      items.push({ name: nodeName(node.name), url: node.index?.url });
+    }
+  }
+  items.push({ name: page.data.title });
+  return items;
+}
+
+export function sectionBreadcrumbPreviews(
+  items: readonly SectionCrumb[],
+  lang: Lang,
+  catalog: DatasetCatalog,
+): Record<string, PagePreviewData> {
+  const previews: Record<string, PagePreviewData> = {};
+  for (const item of items) {
+    if (!item.url) continue;
+    const preview = lookupPagePreview(catalog, item.url, lang);
+    if (preview) previews[item.url] = preview;
+  }
+  return previews;
+}
+