@terrafirmagreg-team/kit 1.2.3 → 1.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrafirmagreg-team/kit",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "type": "module",
   "description": "Fumadocs content engine",
   "license": "LGPL-3.0-only",
@@ -25,12 +25,12 @@
     "@base-ui/react": "^1.9.0",
     "@icons-pack/react-simple-icons": "13.15.1",
     "@terrafirmagreg-team/data": "1.2.1",
-    "@terrafirmagreg-team/mdx": "1.2.1",
+    "@terrafirmagreg-team/mdx": "1.2.2",
     "@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.4",
+    "fumadocs-core": "16.17.10",
+    "lucide-react": "^1.63.0",
     "server-only": "^0.0.1",
     "zod": "4.6.7"
   },

package/src/components/layouts/layout.tsx

@@ -0,0 +1,192 @@
+'use client';
+import {
+  useMemo,
+  type ComponentProps,
+  type ComponentType,
+  type ReactNode,
+} from 'react';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { Layout as UiLayout } from '@terrafirmagreg-team/ui/components/layouts/layout';
+import {
+  LeftSidebar,
+  LeftSidebarActions,
+  LeftSidebarLanguage,
+  LeftSidebarSearch,
+  LeftSidebarSeparator,
+} from '@terrafirmagreg-team/ui/components/layouts/left-sidebar';
+import { Switcher } from '@terrafirmagreg-team/ui/components/blocks/nav/switcher';
+import {
+  SiteMenu,
+  type SiteMenuItem,
+} from '@terrafirmagreg-team/ui/components/blocks/nav/site-menu';
+import { buttonVariants } from '@terrafirmagreg-team/ui/components/ui/button';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { Globe } from 'lucide-react';
+import {
+  SiCurseforge,
+  SiDiscord,
+  SiGithub,
+  SiModrinth,
+} from '@icons-pack/react-simple-icons';
+import { usePathname } from 'next/navigation';
+import { ReadabilityMenu } from '@terrafirmagreg-team/ui/components/blocks/readability/menu';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { useLocaleRegistry } from '@terrafirmagreg-team/translate/hooks/use-locale-registry';
+import { LangLocalesScope } from '@terrafirmagreg-team/translate/provider';
+import { localeItems } from '@terrafirmagreg-team/translate/create';
+import { siteLinks } from '@terrafirmagreg-team/sites';
+import { useCurrentDataset } from '@terrafirmagreg-team/kit/hooks/use-current-dataset';
+import { useDatasetAccent } from '@terrafirmagreg-team/kit/hooks/use-dataset-accent';
+import { useNavOptions } from '@terrafirmagreg-team/kit/hooks/use-nav-options';
+import { pinTreeDataset } from '@terrafirmagreg-team/kit/lib/pin-tree';
+import { layoutDeps, sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
+import type {
+  DatasetCatalog,
+  LeftSidebarSlotProps,
+  SectionKey,
+  SectionTrees,
+} from '@terrafirmagreg-team/kit/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export type LayoutProps = {
+  section: SectionKey;
+  trees: SectionTrees;
+  catalog: DatasetCatalog;
+
+  useTree?: (tree: PageTree.Root) => PageTree.Root;
+  sidebar?: Pick<LeftSidebarSlotProps, 'feature'>;
+  navTitle?: ComponentType<ComponentProps<'a'>>;
+  children?: ReactNode;
+};
+
+const NAV_KEYS = new Set(['book', 'cat', 'entry', 'category', 'type']);
+
+const LINK_ICONS: Record<string, ReactNode> = {
+  github: <SiGithub />,
+  curseforge: <SiCurseforge />,
+  modrinth: <SiModrinth />,
+  discord: <SiDiscord />,
+};
+
+const identityTree = (tree: PageTree.Root) => tree;
+
+export function Layout({
+  section,
+  trees,
+  catalog,
+  useTree = identityTree,
+  sidebar,
+  navTitle,
+  children,
+}: LayoutProps) {
+  const t = useTranslations();
+  const { defaultLanguage } = useLocaleRegistry();
+  const lang: Lang = useResolvedLang();
+  const current = useCurrentDataset(catalog[section]);
+  const baseId = current ? current.id : undefined;
+  const pinned = current ? current.version : undefined;
+  const meta = catalog[section].find((item) => item.id === baseId);
+  useDatasetAccent(meta?.accent);
+  const nav = useNavOptions({ section, catalog });
+  const pathname = usePathname();
+  const deps = layoutDeps();
+  deps.trackView?.(pathname);
+  const commentsItem =
+    (deps.commentsMenuItem?.() as SiteMenuItem | false | null) ?? false;
+  const Feature = sidebar?.feature;
+  const scoped = baseId
+    ? (trees[lang]?.[baseId] ?? trees[defaultLanguage]?.[baseId])
+    : undefined;
+  const serverTree = scoped ?? {
+    name: section,
+    children: [],
+    $id: `${section}:empty`,
+  };
+  const tree = useTree(serverTree);
+  const pinnedTree = useMemo(
+    () =>
+      pinned && baseId
+        ? pinTreeDataset(tree, section, baseId, pinned)
+        : tree,
+    [tree, section, baseId, pinned],
+  );
+  const locales = meta?.languages ? localeItems(meta.languages) : undefined;
+  const links = baseId
+    ? sectionConfig().datasetConfig[baseId]?.links
+    : undefined;
+  const menuItems: (SiteMenuItem | 'separator' | false)[] = [
+    commentsItem,
+    { label: t('Website', { note: 'ui.website' }), icon: <Globe />, url: siteLinks.website },
+    'separator',
+    { label: 'Discord', icon: <SiDiscord />, url: siteLinks.discord, external: true },
+    { label: 'GitHub', icon: <SiGithub />, url: siteLinks.github, external: true },
+    {
+      label: 'CurseForge',
+      icon: <SiCurseforge />,
+      url: siteLinks.curseforge,
+      external: true,
+    },
+    {
+      label: 'Modrinth',
+      icon: <SiModrinth />,
+      url: siteLinks.modrinth,
+      external: true,
+    },
+  ];
+
+  const layout = (
+    <UiLayout
+      tree={pinnedTree}
+      navTitle={navTitle}
+      sidebar={
+        <LeftSidebar
+          navKeys={NAV_KEYS}
+          menu={<SiteMenu label={t('Site menu', { note: 'ui.site_menu' })} items={menuItems} />}
+          footer={
+            <>
+              <LeftSidebarLanguage />
+              <LeftSidebarActions settings={ReadabilityMenu}>
+                {links?.map((link) => (
+                  <a
+                    key={link.label}
+                    href={link.url}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    aria-label={link.label}
+                    className={cn(
+                      buttonVariants({ variant: 'ghost', size: 'icon-sm' }),
+                      'text-muted-foreground [&_svg]:size-4',
+                    )}
+                  >
+                    {link.icon ? LINK_ICONS[link.icon] : link.label}
+                  </a>
+                ))}
+              </LeftSidebarActions>
+            </>
+          }
+          controls={
+            <>
+              <LeftSidebarSearch />
+              <Switcher {...nav.section} />
+              <Switcher {...nav.dataset} />
+              {Feature ? (
+                <>
+                  <LeftSidebarSeparator />
+                  <Feature />
+                </>
+              ) : null}
+            </>
+          }
+        />
+      }
+    >
+      {children}
+    </UiLayout>
+  );
+  return locales ? (
+    <LangLocalesScope locales={locales}>{layout}</LangLocalesScope>
+  ) : (
+    layout
+  );
+}

package/src/components/toc/base.tsx

@@ -4,8 +4,9 @@ import {
   ScrollProvider,
   type AnchorProviderProps,
 } from 'fumadocs-core/toc';
-import { useRef, type ComponentProps } from 'react';
+import { useMemo, useRef, type ComponentProps } from 'react';
 import { TOCContext } from '@terrafirmagreg-team/kit/hooks/use-toc';
+import { tocTitle } from '@terrafirmagreg-team/kit/lib/toc-title';
 import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
 import { mergeRefs } from '@terrafirmagreg-team/ui/lib/utils/merge-refs';
 
@@ -32,9 +33,13 @@ export type {
 export type TOCProviderProps = AnchorProviderProps;
 
 export function TOCProvider({ toc, children, ...props }: TOCProviderProps) {
+  const items = useMemo(
+    () => toc?.map((item) => ({ ...item, title: tocTitle(item) })),
+    [toc],
+  );
   return (
-    <TOCContext value={toc}>
-      <AnchorProvider toc={toc} {...props}>
+    <TOCContext value={items}>
+      <AnchorProvider toc={items} {...props}>
         {children}
       </AnchorProvider>
     </TOCContext>

package/src/components/toc/page.tsx

@@ -0,0 +1,32 @@
+'use client';
+import type { ReactNode } from 'react';
+import { TOCProvider } from '@terrafirmagreg-team/kit/components/toc/base';
+import type { TOCItemType } from 'fumadocs-core/toc';
+
+export function PageToc({
+  toc = [],
+  single,
+  popover,
+  outline,
+  children,
+}: {
+  toc?: TOCItemType[];
+  single?: boolean;
+  popover?: ReactNode;
+  outline?: ReactNode;
+  children?: ReactNode;
+}) {
+  return (
+    <TOCProvider single={single} toc={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"
+      >
+        {popover}
+        <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>
+      {children}
+      {outline}
+    </TOCProvider>
+  );
+}

package/src/components/version-menu.tsx

@@ -1,8 +1,9 @@
 'use client';
 
 import { CheckIcon, ChevronDown } from 'lucide-react';
+import { useRouter } from 'next/navigation';
 import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
-import { useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -12,6 +13,7 @@ import {
 import { useUiComponents } from '@terrafirmagreg-team/ui/provider';
 import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
 import { type DatasetRef, sectionUrl } from '@terrafirmagreg-team/sites/location';
+import { clientDumpLoader } from '@terrafirmagreg-team/kit/lib/config';
 
 import type { SectionKey } from '@terrafirmagreg-team/kit/types';
 
@@ -88,30 +90,48 @@ function VersionMenuItems({
 }) {
   const { Link } = useUiComponents();
   const t = useTranslations();
+  const router = useRouter();
 
   const current = useLocationSearchParams();
-  return ordered.map((version) => {
+  const hrefs = useMemo(
+    () =>
+      ordered.map((version) => {
+        const params = new URLSearchParams(current);
+        if (version === latest) params.delete('version');
+        else params.set('version', version);
+        const q = params.toString();
+        return section
+          ? `${sectionUrl(section, datasetId)}${q ? `?${q}` : ''}`
+          : undefined;
+      }),
+    [ordered, current, latest, section, datasetId],
+  );
+  useEffect(() => {
+    if (!section) return;
+    for (const href of hrefs) {
+      if (href) router.prefetch(href);
+    }
+  }, [hrefs, section, router]);
+  return ordered.map((version, index) => {
     const isLatest = version === latest;
     const selected = currentRef.id === datasetId &&
       currentRef.version === (isLatest ? undefined : version);
-    const params = new URLSearchParams(current);
-    if (isLatest) params.delete('version');
-    else params.set('version', version);
-    const q = params.toString();
+    const href = hrefs[index];
     return (
       <DropdownMenuItem
         key={version}
         closeOnClick
         render={
-          section ? (
-            <Link
-              href={`${sectionUrl(section, datasetId)}${q ? `?${q}` : ''}`}
-            />
-          ) : undefined
+          section && href ? <Link href={href} /> : undefined
         }
         onClick={
           onSelect ? () => onSelect(isLatest ? undefined : version) : undefined
         }
+        onPointerEnter={() =>
+          clientDumpLoader().warm?.(
+            isLatest ? { id: datasetId } : { id: datasetId, version },
+          )
+        }
         className="gap-2 px-2.5 py-1.5 text-xs"
       >
         <span className="flex min-w-0 flex-1 flex-col">

package/src/components/views/frame.tsx

@@ -0,0 +1,140 @@
+'use client';
+import {
+  createContext,
+  use,
+  useEffect,
+  useState,
+  type ReactNode,
+} from 'react';
+import { PageToc } from '@terrafirmagreg-team/kit/components/toc/page';
+import { Workspace } from '@terrafirmagreg-team/ui/components/layouts/workspace';
+import {
+  RightSidebarOutline,
+  WorkspaceOutlineDropdown,
+  WorkspaceOutlinePopover,
+} from '@terrafirmagreg-team/kit/components/outline';
+import type {
+  OutlineProps,
+  WorkspaceOutlinePopoverProps,
+} from '@terrafirmagreg-team/kit/types/outline';
+import type { TOCItemType } from 'fumadocs-core/toc';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import type { WorkspaceProps } from '@terrafirmagreg-team/ui/components/layouts/workspace';
+
+export interface WorkspaceSlots {
+  toc?: TOCItemType[];
+  outline?: ReactNode;
+  breadcrumb?: WorkspaceProps['breadcrumb'];
+  pagination?: WorkspaceProps['pagination'];
+  full?: boolean;
+}
+
+export interface WorkspaceViewProps extends WorkspaceSlots {
+  outlineProps?: OutlineProps & { enabled?: boolean; single?: boolean };
+  outlinePopover?: WorkspaceOutlinePopoverProps & { enabled?: boolean };
+  actions?: ReactNode;
+  footer?: ReactNode;
+  className?: string;
+}
+
+export interface PageFrameProps extends WorkspaceViewProps {
+  children?: ReactNode;
+}
+
+const WorkspaceSlotsContext = createContext<
+  (slots: WorkspaceSlots | null) => void
+>(() => {});
+
+export function useWorkspaceSlots(
+  slots: WorkspaceSlots | null,
+  deps: readonly unknown[],
+) {
+  const set = use(WorkspaceSlotsContext);
+  useEffect(() => {
+    set(slots);
+    return () => set(null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [set, ...deps]);
+}
+
+export function PageFrame({
+  toc = [],
+  outline,
+  outlineProps = {},
+  outlinePopover = {},
+  breadcrumb,
+  pagination = {},
+  full = false,
+  actions,
+  footer,
+  className,
+  children,
+  ...props
+}: PageFrameProps) {
+  const [slots, setSlots] = useState<WorkspaceSlots | null>(null);
+  const effToc = slots?.toc ?? toc;
+  const effOutline = slots?.outline ?? outline;
+  const effBreadcrumb = slots?.breadcrumb ?? breadcrumb;
+  const effPagination = slots?.pagination ?? pagination;
+  const effFull = slots?.full ?? full;
+  const {
+    enabled: outlineEnabledProp,
+    single,
+    ...oProps
+  } = outlineProps;
+  const outlineEnabled =
+    outlineEnabledProp ?? (!effFull || (slots?.toc?.length ?? 0) > 0);
+  const { enabled: popoverEnabledProp, ...pProps } = outlinePopover;
+  const popoverEnabled =
+    popoverEnabledProp ??
+    Boolean(
+      effToc.length > 0 || outlinePopover.header || outlinePopover.footer,
+    );
+  const hasCrumbs = (effBreadcrumb?.items?.length ?? 0) > 0;
+
+  return (
+    <WorkspaceSlotsContext value={setSlots}>
+      <PageToc
+        single={single}
+        toc={outlineEnabled || popoverEnabled ? effToc : []}
+        popover={
+          popoverEnabled ? (
+            <WorkspaceOutlinePopover {...pProps} />
+          ) : undefined
+        }
+        outline={
+          effOutline ??
+          (outlineEnabled ? <RightSidebarOutline {...oProps} /> : undefined)
+        }
+      >
+        <Workspace
+          full={effFull}
+          breadcrumb={effBreadcrumb}
+          pagination={effPagination}
+          actions={actions}
+          footer={footer}
+          className={className}
+          outlineDropdown={
+            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 {...pProps} />
+              </div>
+            ) : undefined
+          }
+          {...props}
+        >
+          {children}
+        </Workspace>
+      </PageToc>
+    </WorkspaceSlotsContext>
+  );
+}

package/src/components/views/routes.tsx

@@ -6,9 +6,11 @@ import { flattenTree } from 'fumadocs-core/page-tree';
 import { LangRedirect } from '@terrafirmagreg-team/ui/components/blocks/lang/redirect';
 import { LangContentSwitch } from '@terrafirmagreg-team/ui/components/blocks/lang/content';
 import {
-  Workspace,
-  type WorkspaceProps,
-} from '@terrafirmagreg-team/kit/components/workspace';
+  renderSectionView,
+  renderSectionWorkspace,
+  type SectionPageView,
+  type SectionPageViewFn,
+} from '@terrafirmagreg-team/kit/components/views/section';
 import { baseOptions } from '@terrafirmagreg-team/kit/lib/layout';
 import {
   datasetCatalog,
@@ -31,10 +33,6 @@ import {
   registerLocaleRenderer,
 } from '@terrafirmagreg-team/kit/lib/locale/renderer';
 import { canonicalUrl } from '@terrafirmagreg-team/kit/lib/urls';
-import {
-  renderSectionWorkspace,
-  type SectionWorkspaceProps,
-} from '@terrafirmagreg-team/kit/components/views/section';
 import { sectionUrl } from '@terrafirmagreg-team/sites/location';
 import { langContent, loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
 import type {
@@ -46,6 +44,7 @@ import type {
   SectionSource,
   SectionTrees,
 } from '@terrafirmagreg-team/kit/types';
+import type { SectionFeatures } from '@terrafirmagreg-team/kit/types/features';
 import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
 
 export interface SectionLayoutViewProps {
@@ -58,29 +57,37 @@ export interface SectionLayoutViewProps {
   children?: ReactNode;
 }
 
-export interface SectionLandingView {
-  node: ReactNode;
-  workspace?: WorkspaceProps;
+export type SectionLandingView = SectionPageView;
+
+export interface SectionLandingProps<TSource = unknown> {
+  page: DatasetLanding;
+  lang: Lang;
+  route: string;
+  source: TSource;
+  trees?: SectionTrees;
+  catalog: DatasetCatalog;
+  contentDir: string;
+  history?: boolean;
+  features?: SectionFeatures;
 }
 
-export interface SectionRoutesOptions<S extends SectionKey> {
+export interface SectionRoutesOptions<
+  S extends SectionKey,
+  TSource = SectionSource,
+> {
   section: S;
   trees?: () => Promise<SectionTrees>;
-  source?: {
-    getSource: () => Promise<SectionSource>;
-    contentDir: string;
+  source: {
+    getSource: () => TSource | Promise<TSource>;
+    contentDir?: string;
     history?: boolean;
   };
-  sidebar?: {
-    feature?: ComponentType;
-    useTree?: (tree: PageTree.Root) => PageTree.Root;
-  };
+  features?: SectionFeatures;
   layout: ComponentType<SectionLayoutViewProps>;
   landing?: (
-    page: DatasetLanding,
-    lang: Lang,
+    props: SectionLandingProps<TSource>,
   ) => SectionLandingView | Promise<SectionLandingView>;
-  page?: ComponentType<SectionWorkspaceProps>;
+  page?: SectionPageViewFn;
 }
 
 interface RouteParams {
@@ -97,25 +104,28 @@ export function createSectionRedirect(section: SectionKey) {
   };
 }
 
-export function createSectionRoutes<S extends SectionKey>({
+export function createSectionRoutes<
+  S extends SectionKey,
+  TSource = SectionSource,
+>({
   section,
   trees,
   source,
-  sidebar,
+  features,
   layout: LayoutView,
   landing,
   page: PageView,
-}: SectionRoutesOptions<S>) {
+}: SectionRoutesOptions<S, TSource>) {
   const resolve =
-    (src: SectionSource | undefined, datasets: readonly SectionDataset[]) =>
+    (src: TSource, datasets: readonly SectionDataset[]) =>
     (slug: string[] | undefined, lang: Lang): Resolved => {
       if (slug?.length === 1) {
         if (!findDataset(datasets, { id: slug[0] })) return undefined;
         if (landing) {
           const page = getDatasetLanding(section, slug, lang, datasets);
           if (!page) return undefined;
-          if (!src) return { page, isFallback: false };
-          const own = src
+          if (!PageView) return { page, isFallback: false };
+          const own = (src as SectionSource)
             .getPages()
             .some(
               (p) =>
@@ -125,11 +135,11 @@ export function createSectionRoutes<S extends SectionKey>({
           return { page, isFallback: !own };
         }
       }
-      return src ? resolvePage(src, slug, lang) : undefined;
+      return PageView ? resolvePage(src as SectionSource, slug, lang) : undefined;
     };
 
   const render = async (
-    src: SectionSource | undefined,
+    src: TSource,
     slug: string[] | undefined,
     resolvedTrees: SectionTrees | undefined,
     catalog: DatasetCatalog,
@@ -137,17 +147,28 @@ export function createSectionRoutes<S extends SectionKey>({
     lang: Lang,
   ): Promise<ReactNode> => {
     if (slug?.length === 1 && landing) {
-      const view = await landing(page as DatasetLanding, lang);
-      return <Workspace {...view.workspace}>{view.node}</Workspace>;
+      const view = await landing({
+        page: page as DatasetLanding,
+        lang,
+        route: sectionUrl(section),
+        source: src,
+        trees: resolvedTrees,
+        catalog,
+        contentDir: source.contentDir ?? `content/${section}`,
+        history: source.history,
+        features,
+      });
+      return renderSectionView(view);
     }
-    if (!src || !PageView) return null;
+    if (!PageView) return null;
     return renderSectionWorkspace({
-      source: src,
+      source: src as SectionSource,
       slug,
-      contentDir: source?.contentDir ?? `content/${section}`,
+      contentDir: source.contentDir ?? `content/${section}`,
       trees: resolvedTrees,
       catalog,
-      history: source?.history,
+      history: source.history,
+      features,
       workspace: PageView,
       page: page as SectionPage,
       lang,
@@ -156,13 +177,13 @@ export function createSectionRoutes<S extends SectionKey>({
 
   registerLocaleRenderer(section, {
     resolve: async (slug, lang) =>
-      resolve(await source?.getSource(), await sectionDatasets(section))(
+      resolve(await source.getSource(), await sectionDatasets(section))(
         slug,
         lang,
       ),
     render: async (page, slug, lang) =>
       render(
-        await source?.getSource(),
+        await source.getSource(),
         slug,
         await trees?.(),
         await datasetCatalog(),
@@ -182,8 +203,6 @@ export function createSectionRoutes<S extends SectionKey>({
         section={section}
         trees={resolvedTrees}
         catalog={catalog}
-        useTree={sidebar?.useTree}
-        sidebar={{ feature: sidebar?.feature }}
         navTitle={slots?.navTitle}
       >
         {children}
@@ -194,13 +213,13 @@ export function createSectionRoutes<S extends SectionKey>({
   async function Page({ params }: RouteParams) {
     const { slug } = await params;
     const [src, datasets] = await Promise.all([
-      source?.getSource(),
+      source.getSource(),
       sectionDatasets(section),
     ]);
 
-    if (slug?.length === 1 && src && !landing) {
+    if (slug?.length === 1 && !landing && PageView) {
       const { defaultLanguage } = loadLocaleRegistry();
-      if (!getPage(src, slug, defaultLanguage)) {
+      if (!getPage(src as SectionSource, slug, defaultLanguage)) {
         const resolvedTrees = trees ? await trees() : undefined;
         const first = flattenTree(
           resolvedTrees?.[defaultLanguage]?.[slug[0]]?.children ?? [],
@@ -236,9 +255,9 @@ export function createSectionRoutes<S extends SectionKey>({
   }
 
   function generateStaticParams() {
-    if (source) {
-      return source.getSource().then((src) =>
-        generateDatasetParams(section, src),
+    if (PageView) {
+      return Promise.resolve(source.getSource()).then((src) =>
+        generateDatasetParams(section, src as SectionSource),
       );
     }
     return generateDatasetLandingParams(section);
@@ -262,7 +281,8 @@ export function createSectionRoutes<S extends SectionKey>({
         },
       };
     }
-    const src = await source?.getSource();
+    if (!PageView) return {};
+    const src = (await source.getSource()) as SectionSource | undefined;
     if (src) {
       const { defaultLanguage } = loadLocaleRegistry();
       if (slug?.length === 1 && !landing && !getPage(src, slug, defaultLanguage))

package/src/components/views/section.tsx

@@ -1,7 +1,5 @@
 import { createRelativeLink } from '@terrafirmagreg-team/kit/components/relative-link';
 import type { LoaderConfig, LoaderOutput, Page } from 'fumadocs-core/source';
-import { notFound } from 'next/navigation';
-import { LangContentSwitch } from '@terrafirmagreg-team/ui/components/blocks/lang/content';
 import { LinkPreview } from '@terrafirmagreg-team/ui/components/blocks/link/link-preview';
 import { lookupPagePreview } from '@terrafirmagreg-team/kit/lib/preview/lookup';
 import {
@@ -9,26 +7,24 @@ import {
   sectionBreadcrumbPreviews,
   type SectionCrumb,
 } from '@terrafirmagreg-team/kit/lib/breadcrumb';
-import { langContent } from '@terrafirmagreg-team/translate/server';
 import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
 import { readPageSource, translationState } from '@terrafirmagreg-team/translate/server';
 import { resolvePage, type SectionSource } from '@terrafirmagreg-team/kit/lib/page';
-import { localeLoader } from '@terrafirmagreg-team/kit/lib/locale/renderer';
 import { findNeighbour } from 'fumadocs-core/page-tree';
+import { stripLangFromUrl } from '@terrafirmagreg-team/translate/lib/slug';
+import { sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
 import type {
   DatasetCatalog,
-  SectionKey,
   SectionPage,
   SectionTrees,
 } from '@terrafirmagreg-team/kit/types';
-import type { WorkspacePaginationItems } from '@terrafirmagreg-team/kit/components/workspace';
+import { PageFrame } from '@terrafirmagreg-team/kit/components/views/frame';
+import type { WorkspaceViewProps } from '@terrafirmagreg-team/kit/components/views/frame';
+import type { WorkspacePaginationItems } from '@terrafirmagreg-team/ui/components/layouts/workspace';
+import type { SectionFeatures } from '@terrafirmagreg-team/kit/types/features';
 import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
 import type { TranslationState } from '@terrafirmagreg-team/translate/server';
-import type {
-  ComponentProps,
-  ComponentType,
-  ReactNode,
-} from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
 
 export interface SectionWorkspaceProps {
@@ -40,16 +36,31 @@ export interface SectionWorkspaceProps {
   previews?: Record<string, PagePreviewData>;
   footer?: WorkspacePaginationItems;
   history?: boolean;
+  features?: SectionFeatures;
+}
+
+export interface SectionPageView {
+  node: ReactNode;
+  workspace?: WorkspaceViewProps;
+}
+
+export function renderSectionView(view: SectionPageView) {
+  return <PageFrame {...view.workspace}>{view.node}</PageFrame>;
 }
 
-export function renderSectionWorkspace({
+export type SectionPageViewFn = (
+  props: SectionWorkspaceProps,
+) => SectionPageView | Promise<SectionPageView>;
+
+export async function renderSectionWorkspace({
   source,
   slug,
   contentDir,
   trees,
   catalog,
   history,
-  workspace: Workspace,
+  features,
+  workspace: pageView,
   page,
   lang,
 }: {
@@ -59,7 +70,8 @@ export function renderSectionWorkspace({
   trees?: SectionTrees;
   catalog: DatasetCatalog;
   history?: boolean;
-  workspace: ComponentType<SectionWorkspaceProps>;
+  features?: SectionFeatures;
+  workspace: SectionPageViewFn;
   page: SectionPage;
   lang: Lang;
 }) {
@@ -81,72 +93,30 @@ export function renderSectionWorkspace({
   const crumbs = sectionBreadcrumbItems(source, page, lang);
   const datasetId = page.url.split('/').filter(Boolean)[1];
   const tree = datasetId ? trees?.[lang]?.[datasetId] : undefined;
-  const neighbours = tree ? findNeighbour(tree, page.url) : undefined;
-  return (
-    <Workspace
-      page={page}
-      crumbs={crumbs}
-      footer={neighbours}
-      previews={sectionBreadcrumbPreviews(crumbs, lang, catalog)}
-      link={createRelativeLink(
-        source as LoaderOutput<LoaderConfig>,
-        page as unknown as Page,
-        (props) => (
-          <LinkPreview
-            preview={lookupPagePreview(catalog, props.href, lang)}
-            {...props}
-          />
-        ),
-      )}
-      contentDir={contentDir}
-      copied={copied}
-      history={history}
-    />
-  );
-}
-
-export async function SectionView({
-  section,
-  getSource,
-  slug,
-  contentDir,
-  trees,
-  catalog,
-  history,
-  workspace,
-}: {
-  section: SectionKey;
-  getSource: () => Promise<SectionSource>;
-  slug: string[] | undefined;
-  contentDir: string;
-  trees?: SectionTrees;
-  catalog: DatasetCatalog;
-  history?: boolean;
-  workspace: ComponentType<SectionWorkspaceProps>;
-}) {
-  const source = await getSource();
-  const content = langContent(
-    slug,
-    (s, l) => resolvePage(source, s, l),
-    (page, lang) =>
-      renderSectionWorkspace({
-        source,
-        slug,
-        contentDir,
-        trees,
-        catalog,
-        history,
-        workspace,
-        page: page as SectionPage,
-        lang,
-      }),
-  );
-  if (!content) notFound();
-  return (
-    <LangContentSwitch
-      content={content}
-      loadLang={localeLoader()?.bind(null, { section, slug })}
-    />
-  );
+  const pageUrl = stripLangFromUrl(page.url, [
+    ...sectionConfig().knownLanguages,
+  ]);
+  const neighbours = tree ? findNeighbour(tree, pageUrl) : undefined;
+  const view = await pageView({
+    page,
+    crumbs,
+    footer: neighbours,
+    previews: sectionBreadcrumbPreviews(crumbs, lang, catalog),
+    link: createRelativeLink(
+      source as LoaderOutput<LoaderConfig>,
+      page as unknown as Page,
+      (props) => (
+        <LinkPreview
+          preview={lookupPagePreview(catalog, props.href, lang)}
+          {...props}
+        />
+      ),
+    ),
+    contentDir,
+    copied,
+    history,
+    features,
+  });
+  return renderSectionView(view);
 }
 

package/src/lib/config.ts

@@ -80,11 +80,25 @@ export function sectionConfig(): SectionConfigInput {
   return config;
 }
 
+export interface LayoutDeps {
+  trackView?: (pathname: string) => void;
+  commentsMenuItem?: () => unknown;
+}
+
+export function registerLayoutDeps(input: LayoutDeps): void {
+  registry.set('layoutDeps', input);
+}
+
+export function layoutDeps(): LayoutDeps {
+  return (registry.get('layoutDeps') as LayoutDeps | undefined) ?? {};
+}
+
 export type ClientDumpLoader = {
   loadDump(dataset: DatasetRef): Promise<SectionDump | null | undefined>;
   loadVersions(
     datasetId: string,
   ): Promise<{ latest?: string; versions: string[] } | null>;
+  warm?(dataset: DatasetRef): void;
 };
 
 export const {

package/src/lib/embeds.ts

@@ -0,0 +1,20 @@
+import type { SectionEmbeds } from '@terrafirmagreg-team/kit/types/embeds';
+
+export type SectionEmbedId = keyof SectionEmbeds;
+
+type EmbedOf<K extends SectionEmbedId> = NonNullable<SectionEmbeds[K]>;
+
+const registry = ((globalThis as Record<symbol, unknown>)[
+  Symbol.for('terrafirmagreg.embeds')
+] ??= new Map<SectionEmbedId, unknown>()) as Map<SectionEmbedId, unknown>;
+
+export function registerSectionEmbed<K extends SectionEmbedId>(
+  id: K,
+  embed: EmbedOf<K>,
+): void {
+  registry.set(id, embed);
+}
+
+export function sectionEmbeds(): SectionEmbeds {
+  return Object.fromEntries(registry) as SectionEmbeds;
+}

package/src/lib/toc-title.ts

@@ -0,0 +1,34 @@
+import {
+  Children,
+  cloneElement,
+  createElement,
+  Fragment,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+function unwrap(node: ReactNode): ReactNode {
+  return Children.map(node, (child) => {
+    if (!isValidElement(child)) return child;
+    const element = child as ReactElement<{
+      href?: unknown;
+      children?: ReactNode;
+    }>;
+    if (element.props.href !== undefined) {
+      return unwrap(element.props.children);
+    }
+    if (element.props.children !== undefined) {
+      return cloneElement(
+        element,
+        undefined,
+        unwrap(element.props.children),
+      );
+    }
+    return child;
+  });
+}
+
+export function tocTitle(item: { title: ReactNode }): ReactNode {
+  return createElement(Fragment, null, unwrap(item.title));
+}

package/src/types/features.ts

@@ -0,0 +1,19 @@
+import type { SectionPage } from '@terrafirmagreg-team/kit/types';
+import type { TranslationState } from '@terrafirmagreg-team/translate/server';
+import type { ReactNode } from 'react';
+
+export interface SectionPageContext {
+  page: SectionPage;
+  filePath: string;
+  datasetId?: string;
+  copied?: TranslationState;
+  history?: boolean;
+}
+
+export interface SectionFeatures {
+  fileUrl?: (filePath: string) => string;
+  actionsRight?: (ctx: SectionPageContext) => ReactNode;
+  wrapBody?: (body: ReactNode, ctx: SectionPageContext) => ReactNode;
+  footer?: (ctx: SectionPageContext) => ReactNode;
+  comments?: (ctx: SectionPageContext) => ReactNode;
+}

package/src/components/workspace/content.tsx

@@ -1,54 +0,0 @@
-'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

@@ -1,13 +0,0 @@
-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

@@ -1,74 +0,0 @@
-'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

@@ -1,149 +0,0 @@
-'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>
-  );
-}
-