@terrafirmagreg-team/kit 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@terrafirmagreg-team/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Fumadocs content engine",
+  "license": "LGPL-3.0-only",
+  "exports": {
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*/index.ts"
+    ],
+    "./types/*": "./src/types/*.ts",
+    "./hooks/*": [
+      "./src/hooks/*.ts",
+      "./src/hooks/*/index.ts"
+    ],
+    "./types": "./src/types/index.ts",
+    "./components/*": [
+      "./src/components/*.tsx",
+      "./src/components/*/index.tsx",
+      "./src/components/*/index.ts"
+    ],
+    "./locales": "./src/locales.ts"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.9.0",
+    "@icons-pack/react-simple-icons": "13.15.1",
+    "@terrafirmagreg-team/data": "1.2.0",
+    "@terrafirmagreg-team/mdx": "1.2.0",
+    "@terrafirmagreg-team/sites": "1.2.0",
+    "@terrafirmagreg-team/translate": "1.2.0",
+    "@terrafirmagreg-team/ui": "1.2.0",
+    "fumadocs-core": "16.17.8",
+    "lucide-react": "^0.577.0",
+    "server-only": "^0.0.1",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/mdx": "^2.0.14",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/kit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ]
 }

package/src/components/blocks/nav-title.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import type { ComponentProps } from 'react';
+
+import { uiConfig } from '@terrafirmagreg-team/ui/lib/config';
+import { SiteTitle } from '@terrafirmagreg-team/ui/components/blocks/nav/site-title';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { clientDumpLoader } from '@terrafirmagreg-team/kit/lib/config';
+import {
+  isDumpSection,
+  parseSectionLocation,
+} from '@terrafirmagreg-team/sites/location';
+import { setVersionPreference } from '@terrafirmagreg-team/kit/hooks/use-version-pref';
+import { useVersionedDataset } from '@terrafirmagreg-team/kit/hooks/use-versioned-dataset';
+import { VersionMenu } from '@terrafirmagreg-team/kit/components/version-menu';
+
+export function NavTitle({ className, ...props }: ComponentProps<'a'>) {
+  const { section, dataset } = parseSectionLocation(usePathname());
+  const datasetId = dataset;
+
+  const gameData = isDumpSection(section) && datasetId;
+  const versions = useAsyncValue(
+    gameData ? () => clientDumpLoader().loadVersions(datasetId) : false,
+    [datasetId],
+  );
+  const ref = useVersionedDataset(
+    gameData ? datasetId : undefined,
+    versions ?? undefined,
+  );
+  const version = useAsyncValue(
+    ref
+      ? () =>
+          clientDumpLoader()
+            .loadDump(ref)
+            .then((dump) => dump?.manifest.pack?.version ?? undefined)
+      : false,
+    [ref],
+  );
+  return (
+    <SiteTitle
+      href="/"
+      icon={uiConfig().brand?.icon ?? ''}
+      name={uiConfig().brand?.name ?? ''}
+      subtitle={
+        dataset && datasetId && gameData ? (
+          <VersionMenu
+            section={section}
+            datasetId={datasetId}
+            currentRef={ref ?? { id: datasetId }}
+            label={version}
+            versions={versions}
+            onSelect={(next) => setVersionPreference(datasetId, next)}
+          />
+        ) : undefined
+      }
+      className={className}
+      {...props}
+    />
+  );
+}
+

package/src/components/outline/dropdown.tsx

@@ -0,0 +1,68 @@
+'use client';
+import { Popover } from '@base-ui/react/popover';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { ChevronDownIcon } from 'lucide-react';
+import { useState } from 'react';
+import { OutlineActiveHeading, OutlineList, OutlineProgress } from './list';
+import type { WorkspaceOutlineDropdownProps } from '@terrafirmagreg-team/kit/types/outline';
+
+export function WorkspaceOutlineDropdown({
+  trigger,
+  content,
+  header,
+  footer,
+  ...props
+}: WorkspaceOutlineDropdownProps) {
+  const t = useTranslations();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger
+        {...trigger}
+        className={cn(
+          'flex items-center gap-2 min-w-0 h-8 px-1.5 -mx-1.5 rounded-lg text-start text-sm transition-colors',
+          open
+            ? 'bg-accent text-accent-foreground'
+            : 'text-muted-foreground hover:bg-accent/60 hover:text-accent-foreground',
+          trigger?.className,
+        )}
+      >
+        <OutlineProgress className="shrink-0" />
+        <OutlineActiveHeading
+          fallback={t('On this page', { note: 'ui.on_this_page' })}
+          activeClassName="text-foreground"
+        />
+        <ChevronDownIcon
+          className={cn('size-3.5 shrink-0 transition-transform', open && 'rotate-180')}
+        />
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Positioner
+          align="start"
+          sideOffset={8}
+          positionMethod="fixed"
+          className="z-50"
+        >
+          <Popover.Popup
+            {...content}
+            className={cn(
+              'flex flex-col w-88 max-w-(--available-width) max-h-[min(28rem,var(--available-height))] p-3 rounded-2xl border bg-popover text-popover-foreground shadow-xl outline-none origin-(--transform-origin) transition-[opacity,scale] duration-150 ease-[cubic-bezier(0.22,1,0.36,1)] data-starting-style:opacity-0 data-starting-style:scale-95 data-ending-style:opacity-0 data-ending-style:scale-95 motion-reduce:transition-none',
+              content?.className,
+            )}
+          >
+            {header}
+            <OutlineList
+              {...props}
+              className="py-1"
+              onSelect={() => setOpen(false)}
+            />
+            {footer}
+          </Popover.Popup>
+        </Popover.Positioner>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}
+

package/src/components/outline/index.ts

@@ -0,0 +1,11 @@
+export type {
+  OutlineStyle,
+  OutlineContent,
+  OutlineProps,
+  WorkspaceOutlineDropdownProps,
+  WorkspaceOutlinePopoverProps,
+} from '@terrafirmagreg-team/kit/types/outline';
+export { Outline, RightSidebarOutline } from './outline';
+export { WorkspaceOutlinePopover } from './popover';
+export { WorkspaceOutlineDropdown } from './dropdown';
+

package/src/components/outline/list.tsx

@@ -0,0 +1,121 @@
+'use client';
+import { type TOCItemInfo, useTOCSelector } from '@terrafirmagreg-team/kit/components/toc/base';
+import { useTOCItems } from '@terrafirmagreg-team/kit/hooks/use-toc';
+import * as Base from '@terrafirmagreg-team/kit/components/toc/base';
+import * as OutlineDefault from '@terrafirmagreg-team/kit/components/toc/default';
+import * as OutlineClerk from '@terrafirmagreg-team/kit/components/toc/clerk';
+import * as OutlineBlock from '@terrafirmagreg-team/kit/components/toc/block';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import {
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+  useState,
+} from 'react';
+import type { OutlineStyle } from '@terrafirmagreg-team/kit/types/outline';
+
+const variants = {
+  normal: OutlineDefault,
+  clerk: OutlineClerk,
+  block: OutlineBlock,
+};
+
+const selectTopmost = (items: TOCItemInfo[]) =>
+  items.find((item) => item.active)?.original;
+const selectProgress = (items: TOCItemInfo[]) =>
+  (items.findLastIndex((item) => item.active) + 1) / Math.max(1, items.length);
+
+export function OutlineList({
+  style = 'block',
+  list,
+  className,
+  onSelect,
+}: OutlineStyle & { className?: string; onSelect?: () => void }) {
+  const items = useTOCItems();
+  const { TOCItems, TOCItem, TOCEmpty } = variants[style];
+
+  return (
+    <Base.TOCScrollArea className={className}>
+      <TOCItems {...list}>
+        {items.length === 0 && <TOCEmpty />}
+        {items.map((item) => (
+          <TOCItem key={item.url} item={item} onClick={onSelect} />
+        ))}
+      </TOCItems>
+    </Base.TOCScrollArea>
+  );
+}
+
+export function OutlineActiveHeading({
+  fallback,
+  className,
+  activeClassName,
+}: {
+  fallback: ReactNode;
+  className?: string;
+  activeClassName?: string;
+}) {
+  const items = useTOCItems();
+  const active = useTOCSelector(selectTopmost);
+  const [shown, setShown] = useState({ item: active, roll: 1 });
+  if (shown.item !== active) {
+    setShown({
+      item: active,
+      roll: items.indexOf(active!) >= items.indexOf(shown.item!) ? 1 : -1,
+    });
+  }
+
+  return (
+    <span
+      className={cn('flex min-w-0 overflow-hidden', active && activeClassName, className)}
+    >
+      <span
+        key={active?.url}
+        className="truncate motion-safe:animate-roll-in"
+        style={{ '--roll': shown.roll } as CSSProperties}
+      >
+        {active ? active.title : fallback}
+      </span>
+    </span>
+  );
+}
+
+export function OutlineProgress({
+  size = 16,
+  ...props
+}: ComponentProps<'svg'> & { size?: number }) {
+  const value = useTOCSelector(selectProgress);
+  const circle = {
+    cx: size / 2,
+    cy: size / 2,
+    r: size / 2 - 1.5,
+    fill: 'none',
+    strokeWidth: 1.5,
+  };
+  const circumference = 2 * Math.PI * circle.r;
+
+  return (
+    <svg
+      role="progressbar"
+      viewBox={`0 0 ${size} ${size}`}
+      width={size}
+      height={size}
+      aria-valuenow={value}
+      aria-valuemin={0}
+      aria-valuemax={1}
+      {...props}
+    >
+      <circle {...circle} className="stroke-current/25" />
+      <circle
+        {...circle}
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeDasharray={circumference}
+        strokeDashoffset={circumference * (1 - value)}
+        transform={`rotate(-90 ${circle.cx} ${circle.cy})`}
+        className="transition-[stroke-dashoffset] duration-300"
+      />
+    </svg>
+  );
+}
+

package/src/components/outline/outline.tsx

@@ -0,0 +1,50 @@
+'use client';
+import { useTOCItems } from '@terrafirmagreg-team/kit/hooks/use-toc';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { TextIcon } from 'lucide-react';
+import {
+  RightSidebarPanel,
+  RightSidebarPortal,
+} from '@terrafirmagreg-team/ui/components/layouts/right-sidebar';
+import { OutlineList } from './list';
+import type { OutlineProps } from '@terrafirmagreg-team/kit/types/outline';
+
+export function Outline({ container, header, footer, ...props }: OutlineProps) {
+  const t = useTranslations();
+  const items = useTOCItems();
+  if (items.length === 0 && !header && !footer) return;
+
+  return (
+    <div
+      data-slot="outline"
+      {...container}
+      className={cn('flex min-h-0 flex-col overflow-clip', container?.className)}
+    >
+      {header}
+      <h3 className="inline-flex items-center gap-1.5 text-sm text-muted-foreground">
+        <TextIcon className="size-4" />
+        {t('On this page', { note: 'ui.on_this_page' })}
+      </h3>
+      <OutlineList {...props} />
+      {footer}
+    </div>
+  );
+}
+
+export function RightSidebarOutline({ container, ...props }: OutlineProps) {
+  return (
+    <RightSidebarPortal>
+      <RightSidebarPanel className="pt-8 pb-4">
+        <Outline
+          {...props}
+          container={{
+            ...container,
+            className: cn('flex-1', container?.className),
+          }}
+        />
+      </RightSidebarPanel>
+    </RightSidebarPortal>
+  );
+}
+

package/src/components/outline/popover.tsx

@@ -0,0 +1,77 @@
+'use client';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@terrafirmagreg-team/ui/components/ui/collapsible';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { ChevronDownIcon } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+import { useTreePath } from '@terrafirmagreg-team/ui/hooks/use-tree';
+import { OutlineActiveHeading, OutlineList, OutlineProgress } from './list';
+import type { WorkspaceOutlinePopoverProps } from '@terrafirmagreg-team/kit/types/outline';
+
+export function WorkspaceOutlinePopover({
+  container,
+  trigger,
+  content,
+  header,
+  footer,
+  ...props
+}: WorkspaceOutlinePopoverProps) {
+  const t = useTranslations();
+  const page = useTreePath().at(-1);
+  const ref = useRef<HTMLElement>(null);
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    if (!open) return;
+    const onClick = (e: MouseEvent) => {
+      if (e.target instanceof Node && !ref.current?.contains(e.target))
+        setOpen(false);
+    };
+
+    window.addEventListener('click', onClick);
+    return () => window.removeEventListener('click', onClick);
+  }, [open]);
+
+  return (
+    <Collapsible
+      open={open}
+      onOpenChange={setOpen}
+      {...container}
+      className={cn('max-md:layout:[--toc-popover-height:--spacing(10)]', container?.className)}
+    >
+      <header ref={ref} className="bg-card">
+        <CollapsibleTrigger
+          {...trigger}
+          className={cn(
+            'flex w-full h-10 items-center gap-2.5 px-4 text-start text-sm text-muted-foreground focus-visible:outline-none',
+            trigger?.className,
+          )}
+        >
+          <OutlineProgress
+            size={18}
+            className={cn('shrink-0', open && 'text-primary')}
+          />
+          <OutlineActiveHeading
+            fallback={page?.name ?? t('On this page', { note: 'ui.on_this_page' })}
+            className={cn('flex-1 transition-colors', open && 'text-foreground')}
+          />
+          <ChevronDownIcon
+            className={cn('size-4 shrink-0 mx-0.5 transition-transform', open && 'rotate-180')}
+          />
+        </CollapsibleTrigger>
+        <CollapsibleContent {...content}>
+          <div className="flex flex-col px-4 max-h-[50vh]">
+            {header}
+            <OutlineList {...props} onSelect={() => setOpen(false)} />
+            {footer}
+          </div>
+        </CollapsibleContent>
+      </header>
+    </Collapsible>
+  );
+}
+

package/src/components/page-actions.tsx

@@ -0,0 +1,202 @@
+'use client';
+import { type ComponentProps } from 'react';
+import {
+  Check,
+  ChevronDown,
+  Copy,
+  ExternalLinkIcon,
+  Languages,
+  TextIcon,
+} from 'lucide-react';
+import { SiGithub } from '@icons-pack/react-simple-icons';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { Button } from '@terrafirmagreg-team/ui/components/ui/button';
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+} from '@terrafirmagreg-team/ui/components/ui/popover';
+import { ItemRow } from '@terrafirmagreg-team/ui/components/blocks/list/row';
+import { useUntranslated } from '@terrafirmagreg-team/ui/hooks/use-lang';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { useCopyButton } from '@terrafirmagreg-team/ui/hooks/use-copy-button';
+import {
+  openPageMarkdown,
+  pageMarkdown,
+} from '@terrafirmagreg-team/mdx/lib/markdown';
+import type { TranslationState } from '@terrafirmagreg-team/translate/server';
+
+function ActionButton({
+  className,
+  ...props
+}: ComponentProps<typeof Button>) {
+  return (
+    <Button
+      variant="secondary"
+      size="sm"
+      className={cn(
+        'gap-2 border-foreground/10 hover:bg-background dark:hover:bg-accent [&_svg]:size-3.5 [&_svg]:text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function MarkdownCopyButton({
+  getMarkdown,
+  ...props
+}: ComponentProps<'button'> & {
+  getMarkdown: () => Promise<string>;
+}) {
+  const t = useTranslations();
+  const { isLoading, checked, error, onClick } = useCopyButton(getMarkdown);
+
+  return (
+    <ActionButton
+      disabled={isLoading}
+      aria-live="polite"
+      onClick={onClick}
+      {...props}
+    >
+      {checked ? <Check /> : <Copy />}
+      {props.children ??
+        (error
+          ? t('Failed to copy', { note: 'ui.copy_error' })
+          : checked
+            ? t('Copied Markdown', { note: 'ui.copied_markdown' })
+            : t('Copy Markdown', { note: 'ui.copy_markdown' }))}
+    </ActionButton>
+  );
+}
+
+export function CopyPageMarkdown({ title }: { title: string }) {
+  return (
+    <MarkdownCopyButton
+      getMarkdown={() =>
+        pageMarkdown(document.querySelector('[data-md-root]'), title)
+      }
+    />
+  );
+}
+
+export function CrowdinButton({ url }: { url: string }) {
+  const t = useTranslations();
+  return (
+    <ActionButton
+      nativeButton={false}
+      render={<a href={url} target="_blank" rel="noreferrer" />}
+    >
+      <Languages />
+      {t('Translate on Crowdin', { note: 'untranslated.translate' })}
+    </ActionButton>
+  );
+}
+
+export function UntranslatedActions({
+  copied,
+  crowdinUrl,
+}: {
+  copied?: TranslationState;
+  crowdinUrl?: string;
+}) {
+  const missing = useUntranslated();
+  if (!crowdinUrl || (!missing && !copied)) return null;
+  return <CrowdinButton url={crowdinUrl} />;
+}
+
+export function ViewOptionsPopover({
+  githubUrl,
+  title,
+  mdUrl,
+  ...props
+}: ComponentProps<typeof PopoverTrigger> & {
+  githubUrl?: string;
+  title?: string;
+  mdUrl?: string;
+}) {
+  const t = useTranslations();
+  const items = [
+    githubUrl && {
+      title: t('Open in GitHub', { note: 'ui.open_github' }),
+      href: githubUrl,
+      icon: <SiGithub color="currentColor" className="size-4" />,
+    },
+    (mdUrl || title !== undefined) && {
+      title: t('View as Markdown', { note: 'ui.view_markdown' }),
+      ...(mdUrl
+        ? { href: mdUrl }
+        : {
+            onClick: () =>
+              void openPageMarkdown(
+                document.querySelector('[data-md-root]'),
+                title!,
+              ),
+          }),
+      icon: <TextIcon className="size-4" />,
+    },
+  ].filter((v) => !!v);
+  if (!items.length) return null;
+
+  return (
+    <Popover>
+      <PopoverTrigger
+        {...props}
+        render={
+          <Button
+            variant="secondary"
+            size="sm"
+            className="border-foreground/10 hover:bg-background dark:hover:bg-accent"
+          />
+        }
+        className={(state) =>
+          cn(
+            'gap-2 data-[popup-open]:bg-accent data-[popup-open]:text-accent-foreground',
+            typeof props.className === 'function' ? props.className(state) : props.className,
+          )
+        }
+      >
+        {props.children ?? t('Open', { note: 'ui.open' })}
+        <ChevronDown className="size-3.5 text-muted-foreground" />
+      </PopoverTrigger>
+      <PopoverContent className="flex flex-col">
+        {items.map((item) => (
+          <ItemRow
+            key={item.title}
+            {...('href' in item
+              ? { href: item.href, target: '_blank', rel: 'noreferrer noopener' }
+              : { onClick: item.onClick })}
+            media={item.icon}
+            title={item.title}
+            trailing={
+              <ExternalLinkIcon className="size-3.5 text-muted-foreground" />
+            }
+          />
+        ))}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export function PageActions({
+  copied,
+  crowdinUrl,
+  title,
+  mdUrl,
+  githubUrl,
+}: {
+  copied?: TranslationState;
+  crowdinUrl?: string;
+  title: string;
+  mdUrl?: string;
+  githubUrl?: string;
+}) {
+  return (
+    <>
+      <CopyPageMarkdown title={title} />
+      <ViewOptionsPopover title={title} mdUrl={mdUrl} githubUrl={githubUrl} />
+      <UntranslatedActions copied={copied} crowdinUrl={crowdinUrl} />
+    </>
+  );
+}
+

package/src/components/relative-link.tsx

@@ -0,0 +1,19 @@
+import type { LoaderConfig, LoaderOutput, Page } from 'fumadocs-core/source';
+import type { ComponentProps, ReactNode } from 'react';
+import Link from 'fumadocs-core/link';
+
+export function createRelativeLink<C extends LoaderConfig>(
+  source: LoaderOutput<C>,
+  page: Page | C['page'],
+  OverrideLink: (props: ComponentProps<'a'>) => ReactNode = Link,
+): (props: ComponentProps<'a'>) => ReactNode | Promise<ReactNode> {
+  return async function RelativeLink({ href, ...props }) {
+    return (
+      <OverrideLink
+        href={href ? source.resolveHref(href, page) : href}
+        {...props}
+      />
+    );
+  };
+}
+