@terrafirmagreg-team/kit 0.0.0-stage → 1.2.0

package/src/components/toc/default.tsx

@@ -0,0 +1,334 @@
+'use client';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { mergeRefs } from '@terrafirmagreg-team/ui/lib/utils/merge-refs';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import * as Primitive from './base';
+import { useTOCItems } from '@terrafirmagreg-team/kit/hooks/use-toc';
+
+interface SvgResult {
+  content: ReactNode;
+  width: number;
+  height: number;
+  d: string;
+  itemLineLengths: [number, number][];
+  positions: [number, number, number][];
+}
+
+export interface TOCItemsProps extends ComponentProps<'div'> {
+  thumbBox?: boolean;
+}
+
+export function TOCItems({
+  ref,
+  className,
+  thumbBox = true,
+  children,
+  ...props
+}: TOCItemsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const items = useTOCItems();
+  const [svg, setSvg] = useState<SvgResult | null>(null);
+
+  const onPrint = useCallback(() => {
+    const container = containerRef.current;
+    if (!container || container.clientHeight === 0) return;
+    if (items.length === 0) {
+      setSvg(null);
+      return;
+    }
+
+    let w = 0;
+    let h = 0;
+    let d = '';
+    const positions: [number, number, number][] = [];
+    const output: ReactNode[] = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      const element = container.querySelector<HTMLElement>(`a[href="${item.url}"]`);
+      if (!element) continue;
+      const styles = getComputedStyle(element);
+      const x = getLineOffset(item.depth) + 0.5;
+      const top = element.offsetTop + parseFloat(styles.paddingTop);
+      const bottom =
+        element.offsetTop + element.clientHeight - parseFloat(styles.paddingBottom);
+
+      w = Math.max(x + 8, w);
+      h = Math.max(h, bottom);
+      if (i === 0) d += ` M${x} ${top} L${x} ${bottom}`;
+      else {
+        const [, upperBottom, upperX] = i > 0 ? positions[i - 1] : [0, 0, 0];
+        d += ` C ${upperX} ${top - 4} ${x} ${upperBottom + 4} ${x} ${top} L${x} ${bottom}`;
+      }
+
+      if (item._step !== undefined)
+        output.push(
+          <g key={i} transform={`translate(${x}, ${(top + bottom) / 2})`}>
+            <circle cx="0" cy="0" r="8" className="fill-primary" />
+            <text
+              x="0"
+              y="0"
+              textAnchor="middle"
+              alignmentBaseline="central"
+              dominantBaseline="middle"
+              className="fill-primary-foreground font-medium text-xs leading-none font-mono rtl:-scale-x-100"
+            >
+              {item._step}
+            </text>
+          </g>,
+        );
+      positions.push([top, bottom, x]);
+    }
+
+    output.unshift(
+      <path
+        key="path"
+        d={d}
+        className="stroke-primary"
+        strokeWidth="1"
+        fill="none"
+      />,
+    );
+
+    const itemLineLengths: [number, number][] = [];
+    if (thumbBox) {
+      const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      path.setAttribute('d', d);
+      const n = path.getTotalLength();
+      for (let i = 0; i < positions.length; i++) {
+        const [top, bottom] = positions[i];
+        let l =
+          i > 0 ? itemLineLengths[i - 1][1] + (top - positions[i - 1][1]) : top;
+        while (l < n && path.getPointAtLength(l).y < top) l++;
+        itemLineLengths.push([l, l + bottom - top]);
+      }
+    }
+
+    setSvg({ content: output, width: w, height: h, d, itemLineLengths, positions });
+  }, [items, thumbBox]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const observer = new ResizeObserver(onPrint);
+    observer.observe(container);
+    onPrint();
+    return () => {
+      observer.unobserve(container);
+    };
+  }, [onPrint]);
+
+  return (
+    <div
+      ref={mergeRefs(containerRef, ref)}
+      className={cn('relative flex flex-col', className)}
+      {...props}
+    >
+      {svg && <ThumbTrack computed={svg} thumbBox={thumbBox} />}
+      {children}
+    </div>
+  );
+}
+
+export function TOCEmpty() {
+  const t = useTranslations();
+  return (
+    <div className="rounded-lg border bg-card p-3 text-xs text-muted-foreground">
+      {t('No Headings', { note: 'ui.no_headings' })}
+    </div>
+  );
+}
+
+function ThumbTrack({
+  computed,
+  thumbBox,
+}: {
+  computed: SvgResult;
+  thumbBox: boolean;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const previousRef = useRef<{
+    startIdx: number;
+    endIdx: number;
+    isUp: boolean;
+  } | null>(null);
+  const tocInfo = Primitive.useTOC();
+
+  function calculate(
+    items: Primitive.TOCItemInfo[],
+    previous: { startIdx: number; endIdx: number; isUp: boolean } | null,
+  ): [CSSProperties, typeof previous] {
+    const out: Record<string, string> = {};
+    const startIdx = items.findIndex((item) => item.active);
+    if (startIdx === -1) return [out, previous];
+    const endIdx = items.findLastIndex((item) => item.active);
+
+    out['--track-top'] = `${computed.positions[startIdx][0]}px`;
+    out['--track-bottom'] = `${computed.positions[endIdx][1]}px`;
+
+    if (thumbBox) {
+      let isUp = false;
+      if (previous) {
+        isUp =
+          previous.startIdx > startIdx ||
+          previous.endIdx > endIdx ||
+          (previous.startIdx === startIdx &&
+            previous.endIdx === endIdx &&
+            previous.isUp);
+      }
+      const next = { startIdx, endIdx, isUp };
+      out['--offset-distance'] = isUp
+        ? `${computed.itemLineLengths[startIdx][0]}px`
+        : `${computed.itemLineLengths[endIdx][1]}px`;
+      out['--opacity'] =
+        items[isUp ? startIdx : endIdx].original._step !== undefined ? '0' : '1';
+      return [out as CSSProperties, next];
+    }
+    return [out as CSSProperties, previous];
+  }
+
+  Primitive.useTOCListener((items) => {
+    const element = ref.current;
+    if (!element) return;
+    const [style, next] = calculate(items, previousRef.current);
+    previousRef.current = next;
+    for (const [k, v] of Object.entries(style))
+      element.style.setProperty(k, v);
+  });
+
+  return (
+    <div
+      ref={ref}
+      className="absolute top-0 inset-s-0 origin-center rtl:-scale-x-100"
+      style={{
+        width: computed.width,
+        height: computed.height,
+        ...calculate(tocInfo.get(), null)[0],
+      }}
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        viewBox={`0 0 ${computed.width} ${computed.height}`}
+        className="absolute transition-[clip-path]"
+        style={{
+          width: computed.width,
+          height: computed.height,
+          clipPath: `polygon(0 var(--track-top,0), 100% var(--track-top,0), 100% var(--track-bottom,0), 0 var(--track-bottom,0))`,
+        }}
+      >
+        {computed.content}
+      </svg>
+      {thumbBox && (
+        <div
+          className="absolute left-0 size-1 bg-primary rounded-full [offset-distance:var(--offset-distance,0)] opacity-(--opacity,0) transition-[opacity,offset-distance]"
+          style={{ offsetPath: `path("${computed.d}")` }}
+        />
+      )}
+    </div>
+  );
+}
+
+const BASE = 8;
+
+function getItemOffset(depth: number): number {
+  if (depth <= 2) return 20;
+  if (depth === 3) return 32;
+  return 44;
+}
+
+function getLineOffset(depth: number): number {
+  if (depth <= 2) return BASE;
+  if (depth === 3) return 16;
+  return 24;
+}
+
+export function TOCItem({
+  item,
+  ...props
+}: Primitive.TOCItemProps & { item: Primitive.TOCItemType }) {
+  const items = useTOCItems();
+  const { isFirst, isLast, svg } = useMemo(() => {
+    const index = items.indexOf(item);
+    const isFirst = index === 0;
+    const isLast = index === items.length - 1;
+    const l1 = getLineOffset(item.depth);
+    const l0 = isFirst ? l1 : getLineOffset(items[index - 1].depth);
+    const l2 = isLast ? l1 : getLineOffset(items[index + 1].depth);
+
+    return {
+      isFirst,
+      isLast,
+      svg: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          className={cn(
+            'absolute -top-1.5 inset-s-0 bottom-0 h-[calc(100%+--spacing(1.5))] -z-1 rtl:-scale-x-100',
+            l1 !== l2 && 'h-full bottom-1.5',
+          )}
+          style={{ width: Math.max(l0, l1) + 9 }}
+        >
+          {l0 !== l1 && (
+            <path
+              d={`M ${l0 + 0.5} 0 C ${l0 + 0.5} 8 ${l1 + 0.5} 4 ${l1 + 0.5} 12`}
+              stroke="black"
+              strokeWidth="1"
+              fill="none"
+              className="stroke-foreground/10"
+            />
+          )}
+          <line
+            x1={l1 + 0.5}
+            y1={l0 === l1 ? '6' : '12'}
+            x2={l1 + 0.5}
+            y2="100%"
+            strokeWidth="1"
+            className="stroke-foreground/10"
+          />
+          {item._step !== undefined && (
+            <g transform={`translate(${l1 + 0.5}, ${l1 === l2 ? '3' : '6'})`}>
+              <circle cx="0" cy="50%" r="8" className="fill-muted" />
+              <text
+                x="0"
+                y="50%"
+                textAnchor="middle"
+                alignmentBaseline="central"
+                dominantBaseline="middle"
+                className="fill-muted-foreground font-medium text-xs leading-none font-mono rtl:-scale-x-100"
+              >
+                {item._step}
+              </text>
+            </g>
+          )}
+        </svg>
+      ),
+    };
+  }, [items, item]);
+
+  return (
+    <Primitive.TOCItem
+      href={item.url}
+      {...props}
+      className={cn(
+        'prose prose-sm relative py-1.5 scroll-m-4 text-muted-foreground hover:text-accent-foreground transition-colors wrap-anywhere data-[active=true]:text-primary',
+        isFirst && 'pt-0',
+        isLast && 'pb-0',
+        props.className,
+      )}
+      style={{ paddingInlineStart: getItemOffset(item.depth), ...props.style }}
+    >
+      {svg}
+      {item.title}
+    </Primitive.TOCItem>
+  );
+}
+

package/src/components/version-menu.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+import { CheckIcon, ChevronDown } from 'lucide-react';
+import { useLocationSearchParams } from '@terrafirmagreg-team/ui/hooks/page/use-location-search';
+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 { type DatasetRef, sectionUrl } from '@terrafirmagreg-team/sites/location';
+
+import type { SectionKey } from '@terrafirmagreg-team/kit/types';
+
+export function VersionMenu({
+  section,
+  datasetId,
+  currentRef,
+  label,
+  versions,
+  onSelect,
+}: {
+  section?: SectionKey;
+  datasetId: string;
+
+  currentRef: DatasetRef;
+
+  label?: string;
+  versions: { versions: string[]; latest?: string } | null | undefined;
+
+  onSelect?: (version: string | undefined) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const pinned = currentRef.version;
+  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 rounded-sm outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring">
+        {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: DatasetRef;
+  section?: SectionKey;
+  onSelect?: (version: string | undefined) => void;
+}) {
+  const { Link } = useUiComponents();
+  const t = useTranslations();
+
+  const current = useLocationSearchParams();
+  return ordered.map((version) => {
+    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();
+    return (
+      <DropdownMenuItem
+        key={version}
+        closeOnClick
+        render={
+          section ? (
+            <Link
+              href={`${sectionUrl(section, datasetId)}${q ? `?${q}` : ''}`}
+            />
+          ) : undefined
+        }
+        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('latest', { note: 'ui.version_latest' })}
+            </span>
+          )}
+        </span>
+        {selected && <CheckIcon className="size-3.5 text-primary" />}
+      </DropdownMenuItem>
+    );
+  });
+}
+

package/src/components/views/dataset.tsx

@@ -0,0 +1,72 @@
+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/sites/location';
+import { canonicalUrl } from '@terrafirmagreg-team/kit/lib/urls';
+import type { DatasetLanding, SectionKey } from '@terrafirmagreg-team/kit/types';
+import { localeLoader } from '@terrafirmagreg-team/kit/lib/locale/renderer';
+import { langContent } from '@terrafirmagreg-team/translate/server';
+
+interface DatasetPageParams {
+  params: Promise<{ slug?: string[] }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}
+
+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
+        key={[section, ...(slug ?? [])].join('/')}
+        content={content}
+        loadLang={localeLoader()?.bind(null, { section, slug })}
+      />
+    );
+  }
+
+  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,152 @@
+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 { localeLoader } from '@terrafirmagreg-team/kit/lib/locale/renderer';
+import { findNeighbour } from 'fumadocs-core/page-tree';
+import type {
+  DatasetCatalog,
+  SectionKey,
+  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';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+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 renderSectionWorkspace({
+  source,
+  slug,
+  contentDir,
+  trees,
+  catalog,
+  history,
+  workspace: Workspace,
+  page,
+  lang,
+}: {
+  source: SectionSource;
+  slug: string[] | undefined;
+  contentDir: string;
+  trees?: SectionTrees;
+  catalog: DatasetCatalog;
+  history?: boolean;
+  workspace: ComponentType<SectionWorkspaceProps>;
+  page: SectionPage;
+  lang: Lang;
+}) {
+  const { defaultLanguage } = loadLocaleRegistry();
+  let copied: 'untranslated' | 'partial' | undefined;
+  if (lang !== defaultLanguage) {
+    const fallback = resolvePage(source, slug, defaultLanguage)?.page as
+      | SectionPage
+      | undefined;
+    if (fallback && fallback !== page) {
+      const own = readPageSource(contentDir, page.path);
+      const original = readPageSource(contentDir, fallback.path);
+      if (own && original) {
+        const state = translationState(own, original);
+        if (state !== 'ok') copied = state;
+      }
+    }
+  }
+  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 })}
+    />
+  );
+}
+