@terrafirmagreg-team/kit 0.0.0-stage → 0.1.0

package/src/lib/order.ts

@@ -0,0 +1,88 @@
+import type {
+  LoaderPlugin,
+  PageTreeBuilderContext,
+} from 'fumadocs-core/source';
+import type { Folder, Item, Node } from 'fumadocs-core/page-tree';
+
+type Storage = PageTreeBuilderContext['storage'];
+type NodeLike = Item | Folder;
+
+type PageFrontmatter = {
+  order?: number;
+  unlisted?: boolean;
+  defaultOpen?: boolean;
+  collapsible?: boolean;
+  link?: boolean;
+};
+
+function frontmatter(
+  storage: Storage,
+  filePath?: string,
+): PageFrontmatter | undefined {
+  if (!filePath) return undefined;
+  const file = storage.read(filePath);
+  return file?.format === 'page' ? (file.data as PageFrontmatter) : undefined;
+}
+
+function orderOf(storage: Storage, node: NodeLike): number {
+  const ref =
+    node.type === 'page'
+      ? node.$ref
+      : (node.index?.$ref ??
+        (node as Folder & { $indexRef?: string }).$indexRef);
+  const data = frontmatter(storage, ref);
+  return typeof data?.order === 'number' ? data.order : Number.MAX_SAFE_INTEGER;
+}
+
+function isUnlisted(storage: Storage, node: NodeLike): boolean {
+  const data = frontmatter(
+    storage,
+    node.type === 'page' ? node.$ref : node.index?.$ref,
+  );
+  return data?.unlisted === true;
+}
+
+function hasExplicitOrder(storage: Storage, metaPath?: string): boolean {
+  if (!metaPath) return false;
+  const file = storage.read(metaPath);
+  return (
+    file?.format === 'meta' &&
+    Array.isArray((file.data as { pages?: unknown }).pages)
+  );
+}
+
+function arrange(storage: Storage, children: Node[], metaPath?: string): Node[] {
+  const kept = children.filter(
+    (child) => child.type === 'separator' || !isUnlisted(storage, child),
+  );
+  if (hasExplicitOrder(storage, metaPath)) return kept;
+  return [...kept].sort(
+    (a, b) => orderOf(storage, a as NodeLike) - orderOf(storage, b as NodeLike),
+  );
+}
+
+export function orderPlugin(): LoaderPlugin {
+  return {
+    name: 'wiki:order',
+    transformPageTree: {
+      folder(node, _folderPath, metaPath) {
+        const indexRef = node.index?.$ref;
+        const index = frontmatter(this.storage, indexRef);
+        const next: Folder = {
+          ...node,
+          defaultOpen: index?.defaultOpen ?? node.defaultOpen,
+          collapsible: index?.collapsible ?? node.collapsible,
+          children: arrange(this.storage, node.children, metaPath),
+        };
+        if (index?.link === false && indexRef) {
+          delete next.index;
+          (next as Folder & { $indexRef?: string }).$indexRef = indexRef;
+        }
+        return next;
+      },
+      root(node) {
+        return { ...node, children: arrange(this.storage, node.children) };
+      },
+    },
+  };
+}

package/src/lib/pack-assets.ts

@@ -0,0 +1,45 @@
+import type { DocsImageProps } from '@terrafirmagreg-team/kit/types/mdx';
+
+export function packPublicUrl(pack: string, ...segments: string[]): string {
+  const rel = segments
+    .map((s) => s.replace(/^\/+/, '').replaceAll('\\', '/'))
+    .filter(Boolean)
+    .join('/');
+  return rel ? `/${pack}/${rel}` : `/${pack}`;
+}
+
+export function assetUrl(
+  pack: string,
+  modId: string,
+  ...pathSegments: string[]
+): string {
+  return packPublicUrl(pack, 'assets', modId, ...pathSegments);
+}
+
+export function resolveSrc(
+  props: Pick<DocsImageProps, 'src' | 'pack' | 'mod' | 'path'>,
+  packFallback?: string,
+): string | null {
+  if (props.src) {
+    const s = props.src.trim();
+    if (
+      s.startsWith('/') ||
+      s.startsWith('http://') ||
+      s.startsWith('https://')
+    ) {
+      return s;
+    }
+    return `/${s.replace(/^\/+/, '')}`;
+  }
+
+  const pack = props.pack ?? packFallback;
+  if (!pack) return null;
+
+  if (props.mod && props.path) {
+    return assetUrl(pack, props.mod, props.path);
+  }
+  if (props.path) {
+    return packPublicUrl(pack, props.path);
+  }
+  return null;
+}

package/src/lib/page.ts

@@ -0,0 +1,108 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { createGetUrl } from 'fumadocs-core/source';
+import { firstLocalizedPage } from '@terrafirmagreg-team/translate/server';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { stripLangFromUrl, toInternalSlugs, toPublicSlug } from '@terrafirmagreg-team/translate/lib/slug';
+import { sectionConfig } from './config';
+import { sectionDatasets } from './datasets';
+import type { SectionKey, SectionPage, SectionSource } from '@terrafirmagreg-team/kit/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export type { SectionSource } from '@terrafirmagreg-team/kit/types';
+
+const canonicalUrl = (pathname: string): string =>
+  new URL(
+    pathname.startsWith('/') ? pathname : `/${pathname}`,
+    sectionConfig().siteUrl,
+  ).toString();
+
+let imageUrl: ReturnType<typeof createGetUrl> | undefined;
+const getImageUrl = () =>
+  (imageUrl ??= createGetUrl(sectionConfig().previewRoute));
+
+function getDatasetImageUrl(section: string, dataset: string) {
+  const segments = [section, dataset, 'image.png'];
+  return { segments, url: getImageUrl()(segments) };
+}
+
+export function getPage<S extends SectionSource>(
+  source: S,
+  slug: string[] | undefined,
+  lang: Lang,
+): ReturnType<S['getPage']> {
+  return source.getPage(toInternalSlugs(slug, lang)) as ReturnType<S['getPage']>;
+}
+
+export function resolvePage<S extends SectionSource>(
+  source: S,
+  slug: string[] | undefined,
+  lang: Lang,
+) {
+  const { defaultLanguage } = loadLocaleRegistry();
+  const exact = getPage(source, slug, lang);
+  if (exact) return { page: exact, isFallback: false as const };
+  if (lang === defaultLanguage) return undefined;
+  const fallback = getPage(source, slug, defaultLanguage);
+  if (!fallback) return undefined;
+  return { page: fallback, isFallback: true as const };
+}
+
+export async function generateDatasetParams(
+  section: SectionKey,
+  source: SectionSource,
+): Promise<{ slug: string[] }[]> {
+  const params = generateParams(source);
+  const seen = new Set(params.map((row) => row.slug.join('/')));
+  for (const { id } of await sectionDatasets(section)) {
+    if (!seen.has(id)) {
+      seen.add(id);
+      params.push({ slug: [id] });
+    }
+  }
+  return params.length ? params : [{ slug: ['_'] }];
+}
+
+function generateParams(source: SectionSource): { slug: string[] }[] {
+  const languages = [...sectionConfig().knownLanguages];
+  const seen = new Set<string>();
+  const params: { slug: string[] }[] = [];
+  for (const page of source.getPages()) {
+    const slug = toPublicSlug(page.slugs, languages);
+    const key = slug.join('/');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    params.push({ slug });
+  }
+  return params;
+}
+
+export async function sectionMetadata(
+  section: SectionKey,
+  source: SectionSource,
+  slug: string[] | undefined,
+): Promise<Metadata> {
+  const page = firstLocalizedPage(slug, (s, l) => getPage(source, s, l));
+  if (!page) notFound();
+  const doc = page as SectionPage;
+  const languages = sectionConfig().knownLanguages;
+
+  const url = canonicalUrl(stripLangFromUrl(doc.url, [...languages]));
+  return {
+    title: doc.data.title,
+    description: doc.data.description,
+    alternates: { canonical: url },
+    openGraph: {
+      type: 'article',
+      url,
+      title: doc.data.title,
+      description: doc.data.description,
+      images: getDatasetImageUrl(section, doc.slugs[0]).url,
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: doc.data.title,
+      description: doc.data.description,
+    },
+  };
+}

package/src/lib/pin-tree.ts

@@ -0,0 +1,35 @@
+import type * as PageTree from 'fumadocs-core/page-tree';
+
+function pinUrl(url: string, from: string, to: string): string {
+  const next = url[from.length];
+  return url.startsWith(from) &&
+    (next === undefined || next === '/' || next === '?' || next === '#')
+    ? `${to}${url.slice(from.length)}`
+    : url;
+}
+
+export function pinTreeDataset(
+  tree: PageTree.Root,
+  section: string,
+  datasetId: string,
+  version: string,
+): PageTree.Root {
+  const from = `/${section}/${datasetId}`;
+  const to = `${from}@${version}`;
+  const pinNode = (node: PageTree.Node): PageTree.Node => {
+    if (node.type === 'page') {
+      return { ...node, url: pinUrl(node.url, from, to) };
+    }
+    if (node.type === 'folder') {
+      return {
+        ...node,
+        index: node.index
+          ? { ...node.index, url: pinUrl(node.index.url, from, to) }
+          : node.index,
+        children: node.children.map(pinNode),
+      };
+    }
+    return node;
+  };
+  return { ...tree, children: tree.children.map(pinNode) };
+}

package/src/lib/preview/index.ts

@@ -0,0 +1,8 @@
+export {
+  loadClientPreviews,
+  registerPreviewResolver,
+  resolveLinkPreview,
+  type PreviewResolver,
+  type PreviewResolverCtx,
+  type PreviewResolverOptions,
+} from './resolvers';

package/src/lib/preview/lookup.ts

@@ -0,0 +1,48 @@
+import 'server-only';
+import { resolveLang } from '@terrafirmagreg-team/translate/lib/code';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { sectionConfig } from '../config';
+import { isSectionKey } from '../location';
+import { resolvePage } from '../page';
+import { sections } from '../sources';
+import type {
+  DatasetCatalog,
+  SectionKey,
+  SectionPage,
+} from '@terrafirmagreg-team/kit/types';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export function lookupPagePreview(
+  catalog: DatasetCatalog,
+  href: string | undefined,
+  lang?: Lang,
+): PagePreviewData | undefined {
+  if (!href || /^(https?:|mailto:|\/\/|#)/i.test(href)) return undefined;
+  const [withoutHash] = href.split('#');
+  const [pathname, qs] = withoutHash.split('?');
+  if (!pathname.startsWith('/')) return undefined;
+
+  const { defaultLanguage } = loadLocaleRegistry();
+  const parts = pathname.split('/').filter(Boolean);
+  if (!isSectionKey(parts[0])) return undefined;
+
+  const section = sections[parts[0]];
+  if (!section) return undefined;
+  const dataset = catalog[parts[0] as SectionKey]?.find(
+    (row) => row.id === parts[1],
+  );
+  const pageLang = resolveLang(
+    new URLSearchParams(qs).get('lang') ?? lang,
+    dataset?.languages ?? [...sectionConfig().knownLanguages],
+    defaultLanguage,
+  );
+  const resolved = resolvePage(section.source, parts.slice(1), pageLang);
+  const page = resolved?.page as SectionPage | undefined;
+  if (!page) return undefined;
+  return {
+    title: page.data.title,
+    description: page.data.description,
+    icon: dataset?.icon ? { type: 'icon', name: dataset.icon } : undefined,
+  };
+}

package/src/lib/preview/og.tsx

@@ -0,0 +1,115 @@
+import { ImageResponse } from 'next/og';
+import type { ReactNode } from 'react';
+import type { ImageResponseOptions } from 'next/dist/compiled/@vercel/og/types';
+
+interface GenerateProps {
+  title: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  primaryColor?: string;
+  primaryTextColor?: string;
+  site?: ReactNode;
+}
+
+export function generateOGImage(options: GenerateProps & ImageResponseOptions): ImageResponse {
+  const { title, description, icon, site, primaryColor, primaryTextColor, ...rest } = options;
+
+  return new ImageResponse(
+    generate({
+      title,
+      description,
+      icon,
+      site,
+      primaryTextColor,
+      primaryColor,
+    }),
+    {
+      width: 1200,
+      height: 630,
+      ...rest,
+    },
+  );
+}
+
+export function generate({
+  primaryColor = 'rgba(255,150,255,0.3)',
+  primaryTextColor = 'rgb(255,150,255)',
+  icon = (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="56"
+      height="56"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="lucide lucide-book-icon lucide-book"
+    >
+      <circle cx="12" cy="12" r="11" stroke={primaryTextColor} strokeWidth="2" />
+    </svg>
+  ),
+  ...props
+}: GenerateProps) {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        width: '100%',
+        height: '100%',
+        color: 'white',
+        padding: '4rem',
+        backgroundColor: '#0c0c0c',
+        borderBottom: `18px solid ${primaryColor}`,
+      }}
+    >
+      <p
+        style={{
+          fontWeight: 800,
+          fontSize: '82px',
+          margin: 0,
+        }}
+      >
+        {props.title}
+      </p>
+      <p
+        style={{
+          fontSize: '52px',
+          color: 'rgba(240,240,240,0.8)',
+          margin: 0,
+          marginTop: '16px',
+          paddingBottom: '28px',
+          borderBottom: `10px dashed ${primaryColor}`,
+        }}
+      >
+        {props.description}
+      </p>
+
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'row',
+          alignItems: 'center',
+          gap: '20px',
+          marginTop: 'auto',
+          color: primaryTextColor,
+        }}
+      >
+        {icon}
+        {props.site && (
+          <p
+            style={{
+              fontSize: '56px',
+              fontWeight: 600,
+              margin: 0,
+            }}
+          >
+            {props.site}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/lib/preview/resolvers.ts

@@ -0,0 +1,98 @@
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+
+export interface PreviewResolverCtx {
+
+  parts: string[];
+  query: URLSearchParams;
+  lang: Lang;
+  langMap: Record<string, string>;
+}
+
+export type PreviewResolver = (
+  ctx: PreviewResolverCtx,
+) => Promise<PagePreviewData | undefined>;
+
+export interface PreviewResolverOptions {
+
+  langMap?: (dataset: string, lang: Lang) => Promise<Record<string, string>>;
+}
+
+const resolvers = new Map<
+  string,
+  { resolve: PreviewResolver; langMap?: PreviewResolverOptions['langMap'] }
+>();
+
+export function registerPreviewResolver(
+  section: string,
+  resolve: PreviewResolver,
+  options?: PreviewResolverOptions,
+): void {
+  resolvers.set(section, { resolve, langMap: options?.langMap });
+}
+
+function parseHref(href: string | undefined) {
+  if (!href || /^(https?:|mailto:|\/\/|#)/i.test(href)) return undefined;
+  const [withoutHash] = href.split('#');
+  const [pathname, qs] = withoutHash.split('?');
+  if (!pathname.startsWith('/')) return undefined;
+  return {
+    withoutHash,
+    query: new URLSearchParams(qs),
+    parts: pathname.split('/').filter(Boolean),
+  };
+}
+
+export async function resolveLinkPreview(
+  href: string,
+  lang?: string,
+): Promise<PagePreviewData | undefined> {
+  const parsed = parseHref(href);
+  if (!parsed) return undefined;
+  const resolvedLang = (parsed.query.get('lang') ?? lang) as Lang | undefined;
+  const entry = resolvers.get(parsed.parts[0] ?? '');
+  if (entry && resolvedLang) {
+    const dataset = parsed.parts[1];
+    if (!dataset) return undefined;
+    const langMap = entry.langMap
+      ? await entry.langMap(dataset, resolvedLang)
+      : {};
+    return entry.resolve({
+      parts: parsed.parts,
+      query: parsed.query,
+      lang: resolvedLang,
+      langMap,
+    });
+  }
+  const res = await fetch(
+    `/api/preview?href=${encodeURIComponent(parsed.withoutHash)}${
+      resolvedLang ? `&lang=${encodeURIComponent(resolvedLang)}` : ''
+    }`,
+  );
+  if (!res.ok) return undefined;
+  return ((await res.json()) ?? undefined) as PagePreviewData | undefined;
+}
+
+export async function loadClientPreviews(
+  lang: Lang,
+  langMap: Record<string, string>,
+  hrefs: Iterable<string>,
+): Promise<Record<string, PagePreviewData>> {
+  const out: Record<string, PagePreviewData> = {};
+  await Promise.all(
+    [...hrefs].map(async (href) => {
+      const parsed = parseHref(href);
+      if (!parsed) return;
+      const entry = resolvers.get(parsed.parts[0] ?? '');
+      if (!entry) return;
+      const preview = await entry.resolve({
+        parts: parsed.parts,
+        query: parsed.query,
+        lang,
+        langMap,
+      });
+      if (preview) out[href] = preview;
+    }),
+  );
+  return out;
+}

package/src/lib/search/config.ts

@@ -0,0 +1,13 @@
+import type { LangConfig } from '@terrafirmagreg-team/translate/lang';
+import { createConfig } from '@terrafirmagreg-team/kit/lib/config';
+import type { LocalizedIndex } from './indexes';
+
+export interface SearchConfig {
+
+  indexes(): Promise<LocalizedIndex[]>;
+
+  i18n(): LangConfig;
+}
+
+export const { register: registerSearchConfig, get: searchConfig } =
+  createConfig<SearchConfig>('Search');

package/src/lib/search/filters.ts

@@ -0,0 +1,22 @@
+import type { SortedResult } from '@terrafirmagreg-team/ui/types/search';
+
+export type SearchHitFilter = (hit: SortedResult) => boolean;
+export type SearchHitFilterFactory = (
+  params: URLSearchParams,
+) => SearchHitFilter | undefined;
+
+const hitFilters = new Map<string, SearchHitFilterFactory>();
+
+export function registerSearchHitFilter(
+  section: string,
+  factory: SearchHitFilterFactory,
+): void {
+  hitFilters.set(section, factory);
+}
+
+export function searchHitFilter(
+  section: string,
+  params: URLSearchParams,
+): SearchHitFilter | undefined {
+  return hitFilters.get(section)?.(params);
+}

package/src/lib/search/index.ts

@@ -0,0 +1,19 @@
+export { mergeClients } from './merge';
+export { pageStructuredData } from './structured';
+export {
+  buildSearchIndexes,
+  type LocalizedIndex,
+  type SearchIndexPage,
+  type SearchPageSource,
+} from './indexes';
+export {
+  registerSearchConfig,
+  searchConfig,
+  type SearchConfig,
+} from './config';
+export {
+  registerSearchHitFilter,
+  searchHitFilter,
+  type SearchHitFilter,
+  type SearchHitFilterFactory,
+} from './filters';

package/src/lib/search/indexes.ts

@@ -0,0 +1,43 @@
+import type { AdvancedIndex } from 'fumadocs-core/search/server';
+import { stripLangFromUrl } from '@terrafirmagreg-team/translate/lib/slug';
+import { pageStructuredData } from './structured';
+
+export type LocalizedIndex = AdvancedIndex & { locale: string };
+
+export interface SearchIndexPage {
+  slugs: string[];
+  url: string;
+  data: { title?: string; description?: string };
+}
+
+export interface SearchPageSource {
+  source: { getPages(): SearchIndexPage[] };
+}
+
+export async function buildSearchIndexes(
+  sources: Record<string, SearchPageSource | undefined>,
+  languages: readonly string[],
+): Promise<LocalizedIndex[]> {
+  const rows = (
+    await Promise.all(
+      Object.entries(sources).flatMap(([section, entry]) =>
+        entry?.source.getPages().map(async (page) => {
+          const [dataset, lang] = page.slugs;
+          if (!dataset || !lang) return null;
+          return {
+            title: page.data.title ?? page.url,
+            description: page.data.description,
+            url: stripLangFromUrl(page.url, [...languages]),
+            id: page.url,
+            tag: `${section}:${dataset}`,
+            locale: lang,
+            structuredData: await pageStructuredData(
+              page.data as Record<string, unknown>,
+            ),
+          } satisfies LocalizedIndex;
+        }) ?? [],
+      ),
+    )
+  ).filter((index) => index !== null);
+  return rows;
+}

package/src/lib/search/merge.ts

@@ -0,0 +1,22 @@
+import type { SearchClient } from 'fumadocs-core/search/client';
+
+export function mergeClients(...clients: SearchClient[]): SearchClient {
+  return {
+    deps: clients.flatMap((client) => client.deps ?? []),
+    async search(query) {
+      const lists = await Promise.all(
+        clients.map((client) => client.search(query)),
+      );
+      const seen = new Set<string>();
+      const out = [];
+      for (const list of lists) {
+        for (const hit of list) {
+          if (seen.has(hit.id)) continue;
+          seen.add(hit.id);
+          out.push(hit);
+        }
+      }
+      return out;
+    },
+  };
+}

package/src/lib/search/server.ts

@@ -0,0 +1,18 @@
+import 'server-only';
+import { createI18nSearchAPI } from 'fumadocs-core/search/server';
+import { searchConfig } from './config';
+
+async function createSearchApi() {
+  const config = searchConfig();
+  return createI18nSearchAPI('advanced', {
+    i18n: config.i18n(),
+    indexes: await config.indexes(),
+  });
+}
+
+let cached: ReturnType<typeof createSearchApi> | undefined;
+
+export function loadSearchApi() {
+  cached ??= createSearchApi();
+  return cached;
+}