@terrafirmagreg-team/kit 0.0.0-stage → 1.2.0

package/src/lib/pin-tree.ts

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

package/src/lib/preview/lookup.ts

@@ -0,0 +1,51 @@
+import 'server-only';
+import { resolveLang } from '@terrafirmagreg-team/translate/lib/code';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
+import { isSectionKey } from '@terrafirmagreg-team/sites/location';
+import { resolvePage } from '@terrafirmagreg-team/kit/lib/page';
+import { sections } from '@terrafirmagreg-team/kit/lib/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 source = section.getSourceSync?.();
+  if (!source) return undefined;
+  const resolved = resolvePage(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/section/schema.ts

@@ -0,0 +1,32 @@
+import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
+import { z, type ZodRawShape } from 'zod';
+
+export function sectionDocsConfig(schemaFields: ZodRawShape = {}): {
+  docs: {
+    schema: ReturnType<typeof pageSchema.extend>;
+    postprocess: { includeProcessedMarkdown: true };
+  };
+  meta: { schema: typeof metaSchema };
+} {
+  return {
+    docs: {
+      schema: pageSchema.extend({
+        order: z.number().optional(),
+        unlisted: z.boolean().optional(),
+        comments: z.boolean().optional(),
+        redirect: z.string().optional(),
+        defaultOpen: z.boolean().optional(),
+        collapsible: z.boolean().optional(),
+        link: z.boolean().optional(),
+        ...schemaFields,
+      }),
+      postprocess: {
+        includeProcessedMarkdown: true,
+      },
+    },
+    meta: {
+      schema: metaSchema,
+    },
+  };
+}
+

package/src/lib/section/source.ts

@@ -0,0 +1,77 @@
+import {
+  dynamicLoader,
+  llms,
+  type DynamicSource,
+  type LoaderConfig,
+  type LoaderOutput,
+} from 'fumadocs-core/source';
+import { sectionDatasets } from '@terrafirmagreg-team/kit/lib/datasets';
+import { sectionConfig } from '@terrafirmagreg-team/kit/lib/config';
+import { orderPlugin } from '@terrafirmagreg-team/kit/lib/order';
+import { renderSectionMarkdown } from '@terrafirmagreg-team/mdx/lib/markdown';
+import { localizedDatasetTrees } from '@terrafirmagreg-team/kit/lib/tree';
+import type { SectionTrees } from '@terrafirmagreg-team/kit/types';
+import type { SectionKey } from '@terrafirmagreg-team/sites/location';
+
+const LOCALE_SEGMENT = /^[a-z]{2,3}_[a-z]{2,4}$/;
+
+export function createSectionSource(options: {
+  route: string;
+
+  section: SectionKey;
+  source: DynamicSource;
+
+  postTrees?: (trees: SectionTrees) => SectionTrees;
+}) {
+  const { route, section, source: dynamicSource, postTrees } = options;
+  const source: DynamicSource = {
+    ...dynamicSource,
+    files: async () => {
+      const known = new Set(sectionConfig().knownLanguages);
+      return (await dynamicSource.files()).filter(
+        (file) =>
+          !file.path
+            .split('/')
+            .some((seg) => LOCALE_SEGMENT.test(seg) && !known.has(seg)),
+      );
+    },
+  };
+  const loader = dynamicLoader(source, {
+    baseUrl: route,
+    plugins: [orderPlugin()],
+  });
+  let resolved: LoaderOutput<LoaderConfig> | undefined;
+  const getSource = async () => {
+    resolved = (await loader.get()) as unknown as LoaderOutput<LoaderConfig>;
+    return resolved;
+  };
+  const getSourceSync = () => resolved;
+  const markdown = {
+    page: async (page: unknown) =>
+      llms((await getSource()) as never, {
+        renderPage: renderSectionMarkdown as (
+          page: unknown,
+        ) => Promise<string>,
+      }).page(page as never),
+  };
+
+  let cached:
+    | { source: LoaderOutput<LoaderConfig>; trees: Promise<SectionTrees> }
+    | undefined;
+  const trees = (): Promise<SectionTrees> =>
+    getSource().then((source) => {
+      if (cached?.source === source) return cached.trees;
+      const built = (async () => {
+        const result = localizedDatasetTrees(
+          source,
+          await sectionDatasets(section),
+        );
+        return postTrees ? postTrees(result) : result;
+      })();
+      cached = { source, trees: built };
+      return built;
+    });
+
+  return { route, getSource, getSourceSync, markdown, trees };
+}
+

package/src/lib/sources.ts

@@ -0,0 +1,22 @@
+import { sectionConfig } from './config';
+import type { SectionKey, SectionSourceEntry } from '@terrafirmagreg-team/kit/types';
+
+export const sections: Partial<Record<SectionKey, SectionSourceEntry>> =
+  new Proxy(
+    {},
+    {
+      get: (_, key: string) => sectionConfig().sources[key as SectionKey],
+      has: (_, key: string) =>
+        Object.hasOwn(sectionConfig().sources ?? {}, key as string),
+      ownKeys: () => Reflect.ownKeys(sectionConfig().sources ?? {}),
+      getOwnPropertyDescriptor: (_, key: string) =>
+        Object.hasOwn(sectionConfig().sources, key)
+          ? {
+              enumerable: true,
+              configurable: true,
+              value: sectionConfig().sources[key as SectionKey],
+            }
+          : undefined,
+    },
+  );
+

package/src/lib/tree.ts

@@ -0,0 +1,61 @@
+import type * as PageTree from 'fumadocs-core/page-tree';
+import { localizePageTree } from '@terrafirmagreg-team/translate/server';
+import { loadLocaleRegistry } from '@terrafirmagreg-team/translate/server';
+import { sectionConfig } from './config';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { SectionDataset, SectionTrees } from '@terrafirmagreg-team/kit/types';
+import type { SectionSource } from './page';
+
+export function datasetId(node: PageTree.Folder): string | undefined {
+  const segment = node.index?.url.split('/').filter(Boolean)[1];
+  if (segment) return segment;
+  const segments = node.$id?.split('/').filter(Boolean);
+  return segments?.[segments.length - 1];
+}
+
+function datasetTree(
+  tree: PageTree.Root,
+  id: string,
+  lang: Lang,
+): PageTree.Root {
+  const folder = tree.children.find(
+    (node): node is PageTree.Folder =>
+      node.type === 'folder' && datasetId(node) === id,
+  );
+  if (!folder) return { name: id, children: [], $id: `${id}:${lang}` };
+  return { name: folder.name, children: folder.children, $id: `${id}:${lang}` };
+}
+
+export function localizedDatasetTrees(
+  source: SectionSource,
+  datasets: readonly SectionDataset[],
+): SectionTrees {
+  const { defaultLanguage } = loadLocaleRegistry();
+  const tree = source.getPageTree();
+  const options = {
+    languages: [...sectionConfig().knownLanguages],
+    fallbackLanguage: defaultLanguage,
+  };
+  const localized = new Map<string, PageTree.Root>();
+  const localize = (lang: Lang) => {
+    let out = localized.get(lang);
+    if (!out) {
+      out = localizePageTree(tree, lang, options);
+      localized.set(lang, out);
+    }
+    return out;
+  };
+  const trees: SectionTrees = {};
+  for (const dataset of datasets) {
+    for (const lang of dataset.languages ?? [defaultLanguage]) {
+      const code = lang as Lang;
+      (trees[code] ??= {})[dataset.id] = datasetTree(
+        localize(code),
+        dataset.id,
+        code,
+      );
+    }
+  }
+  return trees;
+}
+

package/src/lib/urls.ts

@@ -0,0 +1,17 @@
+import { createGetUrl } from 'fumadocs-core/source';
+import { sectionConfig } from './config';
+
+export function canonicalUrl(pathname: string): string {
+  const path = pathname.startsWith('/') ? pathname : `/${pathname}`;
+  return new URL(path, sectionConfig().siteUrl).toString();
+}
+
+export function getDatasetImageUrl(section: string, dataset: string) {
+  const segments = [section, dataset, 'image.png'];
+
+  return {
+    segments,
+    url: createGetUrl(sectionConfig().previewRoute)(segments),
+  };
+}
+

package/src/locales/en_us.json

@@ -0,0 +1,7 @@
+{
+  "Failed to copy(ui.copy_error)": "Failed to copy",
+  "Select dataset(ui.select_dataset)": "Select dataset",
+  "Select section(ui.select_section)": "Select section",
+  "View as Markdown(ui.view_markdown)": "View as Markdown",
+  "latest(ui.version_latest)": "latest"
+}

package/src/locales/ru_ru.json

@@ -0,0 +1,7 @@
+{
+  "Failed to copy(ui.copy_error)": "Не удалось скопировать",
+  "Select dataset(ui.select_dataset)": "Выберите набор данных",
+  "Select section(ui.select_section)": "Выберите раздел",
+  "View as Markdown(ui.view_markdown)": "Просмотр Markdown",
+  "latest(ui.version_latest)": "последняя"
+}

package/src/locales.ts

@@ -0,0 +1,6 @@
+import { createLocaleCatalog } from '@terrafirmagreg-team/translate/lib/locales';
+
+export const locales = createLocaleCatalog(
+  import.meta.glob('./locales/*.json', { eager: true, import: 'default' }),
+);
+

package/src/types/embeds.ts

@@ -0,0 +1,54 @@
+import type { ComponentType } from 'react';
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export type EmbedRecipe = {
+  id: string;
+  w?: number | null;
+  inputs: { id: string }[];
+  outputs: { id: string }[];
+  slots?: Record<
+    string,
+    { id: string; alternatives?: { id: string }[] }
+  >;
+  widgets?: {
+    type: string;
+    id: string;
+    alternatives?: string[];
+  }[];
+};
+
+export type EmbedRecipeCardProps = {
+  id: string;
+  recipe: EmbedRecipe;
+  dataset: DatasetRef;
+  lang: Lang;
+  langMap: Record<string, string>;
+};
+
+export type EmbedQuestLocation = { filename: string; questId: string };
+
+export type SectionEmbeds = {
+  quest?: {
+    href(
+      dataset: DatasetRef,
+      lang: Lang | undefined,
+      ref: { category: string; id: string },
+    ): string;
+    findLocation(
+      dataset: DatasetRef,
+      questId: string,
+    ): Promise<EmbedQuestLocation | undefined>;
+  };
+  recipe?: {
+    href(
+      dataset: DatasetRef,
+      lang: Lang | undefined,
+      ref: { id: string },
+    ): string;
+    cardImageUrl(dataset: DatasetRef, id: string): string | undefined;
+    load(dataset: DatasetRef, id: string): Promise<EmbedRecipe | undefined>;
+    title(recipe: EmbedRecipe, langMap: Record<string, string>): string;
+    Card: ComponentType<EmbedRecipeCardProps>;
+  };
+};

package/src/types/index.ts

@@ -0,0 +1,87 @@
+import type { DatasetRef, SectionKey } from '@terrafirmagreg-team/sites/location';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import type { ComponentType } from 'react';
+import type { IconName } from 'lucide-react/dynamic';
+import type { Page } from 'fumadocs-core/source';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export type { SectionKey } from '@terrafirmagreg-team/sites/location';
+
+export type SectionUrl = string;
+
+export type SectionDataset = {
+  id: string;
+  title?: string;
+  description?: string;
+  icon?: IconName;
+  accent?: string;
+
+  versions?: string[];
+
+  languages?: Lang[];
+};
+
+export type DatasetCatalog = Record<SectionKey, SectionDataset[]>;
+
+export type LeftSidebarScope = {
+  section: SectionKey;
+  catalog: DatasetCatalog;
+};
+
+export type LeftSidebarSlotProps = LeftSidebarScope & {
+
+  feature?: ComponentType;
+};
+
+export type SectionTrees = Record<Lang, Record<string, PageTree.Root>>;
+
+export type SectionPage = {
+  data: {
+    title: string;
+    description?: string;
+    full?: boolean;
+    comments?: boolean;
+    redirect?: string;
+    authors?: string[];
+    gitChangelog?:
+      | boolean
+      | {
+          disableChangelog?: boolean;
+          disableContributors?: boolean;
+        };
+    load?(): Promise<unknown>;
+    content?: string;
+    structuredData?: unknown;
+    frontmatter?: Record<string, unknown>;
+  };
+  path: string;
+  slugs: string[];
+  url: string;
+  locale?: string;
+};
+
+export type SectionSource = {
+  getPage(slugs: string[] | undefined, language?: string): unknown;
+  getPages(language?: string): Page[];
+  getPageTree(locale?: string): PageTree.Root;
+  getNodeMeta?(
+    node: PageTree.Folder | PageTree.Root,
+    language?: string,
+  ): unknown;
+};
+
+export type DatasetLanding = {
+  title: string;
+  description?: string;
+  dataset: DatasetRef;
+  datasetTitle?: string;
+  lang: Lang;
+  versions?: string[];
+};
+
+export type SectionSourceEntry = {
+  getSource: () => Promise<SectionSource>;
+  getSourceSync?: () => SectionSource | undefined;
+  markdown: { page(page: unknown): Promise<string> };
+};
+

package/src/types/outline.ts

@@ -0,0 +1,30 @@
+import type { ComponentProps, ReactNode } from 'react';
+import type * as OutlineDefault from '@terrafirmagreg-team/kit/components/toc/default';
+import type * as OutlineClerk from '@terrafirmagreg-team/kit/components/toc/clerk';
+import type * as OutlineBlock from '@terrafirmagreg-team/kit/components/toc/block';
+
+export type OutlineStyle =
+  | { style?: 'block'; list?: OutlineBlock.TOCItemsProps }
+  | { style: 'normal'; list?: OutlineDefault.TOCItemsProps }
+  | { style: 'clerk'; list?: OutlineClerk.TOCItemsProps };
+
+export type OutlineContent = {
+
+  header?: ReactNode;
+
+  footer?: ReactNode;
+} & OutlineStyle;
+
+export type OutlineProps = OutlineContent & {
+  container?: ComponentProps<'div'>;
+};
+
+export type WorkspaceOutlineDropdownProps = OutlineContent & {
+  trigger?: ComponentProps<'button'>;
+  content?: ComponentProps<'div'>;
+};
+
+export type WorkspaceOutlinePopoverProps = WorkspaceOutlineDropdownProps & {
+  container?: ComponentProps<'div'>;
+};
+

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.