@terrafirmagreg-team/kit 0.0.0-stage → 0.1.0

package/src/components/version-menu.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import { CheckIcon, ChevronDown } from 'lucide-react';
+import { useSearchParams } from 'next/navigation';
+import { useState } from 'react';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@terrafirmagreg-team/ui/components/ui/dropdown-menu';
+import { useUiComponents } from '@terrafirmagreg-team/ui/provider';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { datasetRef, sectionUrl } from '@terrafirmagreg-team/kit/lib/location';
+
+import type { SectionKey } from '@terrafirmagreg-team/kit/types';
+
+export function VersionMenu({
+  section,
+  datasetId,
+  currentRef,
+  label,
+  versions,
+  onSelect,
+}: {
+  section?: SectionKey;
+  datasetId: string;
+
+  currentRef: string;
+
+  label?: string;
+  versions: { versions: string[]; latest?: string } | null | undefined;
+
+  onSelect?: (version: string | undefined) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const pinned =
+    currentRef !== datasetId
+      ? currentRef.slice(datasetId.length + 1)
+      : undefined;
+  const shown = label ?? pinned;
+  const text = shown ? `v${shown}` : datasetId;
+  if (!versions || versions.versions.length < 2 || (!section && !onSelect)) {
+    return <>{text}</>;
+  }
+  const ordered = [...versions.versions].sort((a, b) =>
+    b.localeCompare(a, undefined, { numeric: true }),
+  );
+  if (versions.latest) {
+    const i = ordered.indexOf(versions.latest);
+    if (i > 0) ordered.unshift(ordered.splice(i, 1)[0]);
+  }
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen} modal={false}>
+      <DropdownMenuTrigger className="inline-flex items-center gap-0.5 outline-none hover:text-foreground">
+        {text}
+        <ChevronDown className="size-3" />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        side="bottom"
+        align="start"
+        className="max-h-36 min-w-32"
+      >
+        {}
+        <VersionMenuItems
+          ordered={ordered}
+          latest={versions.latest}
+          datasetId={datasetId}
+          currentRef={currentRef}
+          section={section}
+          onSelect={onSelect}
+        />
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+function VersionMenuItems({
+  ordered,
+  latest,
+  datasetId,
+  currentRef,
+  section,
+  onSelect,
+}: {
+  ordered: string[];
+  latest: string | undefined;
+  datasetId: string;
+  currentRef: string;
+  section?: SectionKey;
+  onSelect?: (version: string | undefined) => void;
+}) {
+  const { Link } = useUiComponents();
+  const t = useTranslations();
+
+  const search = useSearchParams().toString();
+  return ordered.map((version) => {
+    const isLatest = version === latest;
+    const ref = isLatest ? datasetId : datasetRef(datasetId, version);
+    return (
+      <DropdownMenuItem
+        key={version}
+        closeOnClick
+        render={
+          onSelect ? undefined : (
+            <Link
+              href={`${sectionUrl(section!, ref)}${search ? `?${search}` : ''}`}
+            />
+          )
+        }
+        onClick={
+          onSelect ? () => onSelect(isLatest ? undefined : version) : undefined
+        }
+        className="gap-2 px-2.5 py-1.5 text-xs"
+      >
+        <span className="flex min-w-0 flex-1 flex-col">
+          <span className="font-medium">v{version}</span>
+          {isLatest && (
+            <span className="text-2xs text-muted-foreground">
+              {t('ui.version_latest')}
+            </span>
+          )}
+        </span>
+        {ref === currentRef && <CheckIcon className="size-3.5 text-primary" />}
+      </DropdownMenuItem>
+    );
+  });
+}

package/src/components/views/dataset.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+import { LangContentSwitch } from '@terrafirmagreg-team/ui/components/blocks/lang/content';
+import {
+  generateDatasetLandingParams,
+  getDatasetLanding,
+  resolveDatasetLanding,
+} from '@terrafirmagreg-team/kit/lib/landing';
+import { sectionDatasets } from '@terrafirmagreg-team/kit/lib/datasets';
+import { sectionUrl } from '@terrafirmagreg-team/kit/lib/location';
+import { canonicalUrl } from '@terrafirmagreg-team/kit/lib/urls';
+import type { DatasetLanding, SectionKey } from '@terrafirmagreg-team/kit/types';
+import { langContent } from '@terrafirmagreg-team/translate/server';
+
+interface DatasetPageParams {
+  params: Promise<{ slug?: string[] }>;
+}
+
+export function createDatasetLandingPage<S extends SectionKey>(
+  section: S,
+  render: (page: DatasetLanding) => ReactNode,
+) {
+  async function Page({ params }: DatasetPageParams) {
+    const { slug } = await params;
+    const datasets = await sectionDatasets(section);
+    const content = langContent(
+      slug,
+      (s, l) => resolveDatasetLanding(section, s, l, datasets),
+      render,
+    );
+    if (!content) notFound();
+    return <LangContentSwitch content={content} />;
+  }
+
+  function generateStaticParams() {
+    return generateDatasetLandingParams(section);
+  }
+
+  async function generateMetadata({
+    params,
+  }: DatasetPageParams): Promise<Metadata> {
+    const { slug } = await params;
+    const page = getDatasetLanding(
+      section,
+      slug,
+      'en_us',
+      await sectionDatasets(section),
+    );
+    if (!page) notFound();
+    return {
+      title: page.title,
+      description: page.description,
+      alternates: {
+        canonical: canonicalUrl(
+          `${sectionUrl(section)}/${(slug ?? []).join('/')}`,
+        ),
+      },
+    };
+  }
+
+  return { Page, generateStaticParams, generateMetadata };
+}

package/src/components/views/section.tsx

@@ -0,0 +1,108 @@
+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 {
+  sectionBreadcrumbItems,
+  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 { findNeighbour } from 'fumadocs-core/page-tree';
+import type {
+  DatasetCatalog,
+  SectionPage,
+  SectionTrees,
+} from '@terrafirmagreg-team/kit/types';
+import type { WorkspacePaginationItems } from '@terrafirmagreg-team/kit/components/workspace';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+import type { TranslationState } from '@terrafirmagreg-team/translate/server';
+import type {
+  ComponentProps,
+  ComponentType,
+  ReactNode,
+} from 'react';
+
+export interface SectionWorkspaceProps {
+  page: SectionPage;
+  link: (props: ComponentProps<'a'>) => ReactNode | Promise<ReactNode>;
+  contentDir: string;
+  copied?: TranslationState;
+  crumbs?: SectionCrumb[];
+  previews?: Record<string, PagePreviewData>;
+  footer?: WorkspacePaginationItems;
+  history?: boolean;
+}
+
+export function SectionView({
+  source,
+  slug,
+  contentDir,
+  trees,
+  catalog,
+  history,
+  workspace: Workspace,
+}: {
+  source: SectionSource;
+  slug: string[] | undefined;
+  contentDir: string;
+  trees?: SectionTrees;
+  catalog: DatasetCatalog;
+  history?: boolean;
+  workspace: ComponentType<SectionWorkspaceProps>;
+}) {
+  const { defaultLanguage } = loadLocaleRegistry();
+  const content = langContent(
+    slug,
+    (s, l) => resolvePage(source, s, l),
+    (page, lang) => {
+      const self = page as SectionPage;
+      let copied: 'untranslated' | 'partial' | undefined;
+      if (lang !== defaultLanguage) {
+        const fallback = resolvePage(source, slug, defaultLanguage)?.page as
+          | SectionPage
+          | undefined;
+        if (fallback && fallback !== self) {
+          const own = readPageSource(contentDir, self.path);
+          const original = readPageSource(contentDir, fallback.path);
+          if (own && original) {
+            const state = translationState(own, original);
+            if (state !== 'ok') copied = state;
+          }
+        }
+      }
+      const crumbs = sectionBreadcrumbItems(source, self, lang);
+      const datasetId = self.url.split('/').filter(Boolean)[1];
+      const tree = datasetId ? trees?.[lang]?.[datasetId] : undefined;
+      const neighbours = tree ? findNeighbour(tree, self.url) : undefined;
+      return (
+        <Workspace
+          page={self}
+          crumbs={crumbs}
+          footer={neighbours}
+          previews={sectionBreadcrumbPreviews(crumbs, lang, catalog)}
+          link={createRelativeLink(
+            source as LoaderOutput<LoaderConfig>,
+            page as Page,
+            (props) => (
+              <LinkPreview
+                preview={lookupPagePreview(catalog, props.href, lang)}
+                {...props}
+              />
+            ),
+          )}
+          contentDir={contentDir}
+          copied={copied}
+          history={history}
+        />
+      );
+    },
+  );
+  if (!content) notFound();
+  return <LangContentSwitch content={content} />;
+}

package/src/components/workspace/content.tsx

@@ -0,0 +1,53 @@
+'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,12 @@
+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,73 @@
+'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('ui.next_page') : t('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,148 @@
+'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/toc.ts

@@ -0,0 +1,9 @@
+'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-catalog.ts

@@ -0,0 +1,11 @@
+'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,14 @@
+'use client';
+import { usePathname } from 'next/navigation';
+import { parseDatasetRef, parseSectionLocation } from '@terrafirmagreg-team/kit/lib/location';
+import type { SectionDataset } from '@terrafirmagreg-team/kit/types';
+
+export function useCurrentDataset(
+  datasets: readonly SectionDataset[],
+): string | undefined {
+  const pathname = usePathname();
+  const { dataset } = parseSectionLocation(pathname);
+  if (!dataset) return undefined;
+  const { id } = parseDatasetRef(dataset);
+  return datasets.some((row) => row.id === id) ? dataset : undefined;
+}

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

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