@terrafirmagreg-team/kit 0.0.0-stage → 0.1.0

package/src/lib/search/sources.ts

@@ -0,0 +1,19 @@
+import type { SearchClient } from 'fumadocs-core/search/client';
+
+export type SearchClientSourceCtx = {
+  refs: string[];
+  locale: string;
+  tag?: string | string[];
+};
+
+export type SearchClientSource = (ctx: SearchClientSourceCtx) => SearchClient;
+
+const sources: SearchClientSource[] = [];
+
+export function registerSearchClientSource(source: SearchClientSource): void {
+  sources.push(source);
+}
+
+export function getSearchClientSources(): readonly SearchClientSource[] {
+  return sources;
+}

package/src/lib/search/structured.ts

@@ -0,0 +1,23 @@
+import type { StructuredData } from 'fumadocs-core/mdx-plugins';
+
+type StructuredPageData = Record<string, unknown>;
+
+export async function pageStructuredData(
+  data: StructuredPageData,
+): Promise<StructuredData> {
+  const raw = data.structuredData;
+  if (typeof raw === 'function') {
+    return (raw as () => Promise<StructuredData> | StructuredData)();
+  }
+  if (typeof data.load === 'function') {
+    const loaded = await (
+      data.load as () => Promise<{ structuredData?: StructuredData }>
+    )();
+    if (!loaded.structuredData) {
+      throw new Error('Cannot find structured data from page');
+    }
+    return loaded.structuredData;
+  }
+  if (!raw) throw new Error('Cannot find structured data from page');
+  return raw as StructuredData;
+}

package/src/lib/section/schema.ts

@@ -0,0 +1,36 @@
+import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
+import { z, type ZodRawShape } from 'zod';
+
+export function sectionDocsConfig(
+  dir: string,
+  schemaFields: ZodRawShape = {},
+): {
+  dir: string;
+  docs: {
+    schema: ReturnType<typeof pageSchema.extend>;
+    postprocess: { includeProcessedMarkdown: true };
+  };
+  meta: { schema: typeof metaSchema };
+} {
+  return {
+    dir,
+    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,40 @@
+import { llms, loader, type StaticSource } from 'fumadocs-core/source';
+import { sectionDatasets } from '@terrafirmagreg-team/kit/lib/datasets';
+import { orderPlugin } from '@terrafirmagreg-team/kit/lib/order';
+import { renderSectionMarkdown } from '@terrafirmagreg-team/kit/lib/markdown';
+import { localizedDatasetTrees } from '@terrafirmagreg-team/kit/lib/tree';
+import type { SectionTrees } from '@terrafirmagreg-team/kit/types';
+
+type SectionSource = StaticSource;
+
+export function createSectionSource<S extends SectionSource>(options: {
+  route: string;
+
+  section: string;
+  source: S;
+
+  postTrees?: (trees: SectionTrees) => SectionTrees;
+}) {
+  const { route, section, source: fumadocsSource, postTrees } = options;
+  const source = loader({
+    baseUrl: route,
+    source: fumadocsSource,
+    plugins: [orderPlugin()],
+  });
+  const markdown = llms(source as never, {
+    renderPage: renderSectionMarkdown as (
+      page: unknown,
+    ) => Promise<string>,
+  }) as { page(page: unknown): Promise<string> };
+
+  let cached: Promise<SectionTrees> | undefined;
+  const trees = (): Promise<SectionTrees> => {
+    cached ??= sectionDatasets(section).then((datasets) => {
+      const built = localizedDatasetTrees(source, datasets);
+      return postTrees ? postTrees(built) : built;
+    });
+    return cached;
+  };
+
+  return { route, source, markdown, trees };
+}

package/src/lib/sources.ts

@@ -0,0 +1,21 @@
+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,60 @@
+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,16 @@
+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,10 @@
+{
+  "ui": {
+    "select_section": "Select section",
+    "select_dataset": "Select dataset",
+    "view_markdown": "View as Markdown",
+    "copy_error": "Failed to copy",
+    "search_everywhere": "Everywhere",
+    "version_latest": "latest"
+  }
+}

package/src/locales/ru_ru.json

@@ -0,0 +1,10 @@
+{
+  "ui": {
+    "select_section": "Выберите раздел",
+    "select_dataset": "Выберите набор данных",
+    "view_markdown": "Просмотр Markdown",
+    "copy_error": "Не удалось скопировать",
+    "search_everywhere": "Везде",
+    "version_latest": "последняя"
+  }
+}

package/src/locales.ts

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

package/src/types/index.ts

@@ -0,0 +1,83 @@
+import type { MDXProps } from 'mdx/types';
+import type { TOCItemType } from 'fumadocs-core/toc';
+import type * as PageTree from 'fumadocs-core/page-tree';
+import type { ComponentType, ReactNode } 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 = string;
+
+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: {
+    body: (props: MDXProps) => ReactNode | Promise<ReactNode>;
+    toc: TOCItemType[];
+    full?: boolean;
+    title: string;
+    description?: string;
+    comments?: boolean;
+    redirect?: string;
+    authors?: string[];
+    gitChangelog?:
+      | boolean
+      | {
+          disableChangelog?: boolean;
+          disableContributors?: boolean;
+        };
+  };
+  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: string;
+  datasetTitle?: string;
+  lang: Lang;
+};
+
+export type SectionSourceEntry = {
+  source: SectionSource;
+  markdown: { page(page: unknown): Promise<string> };
+};

package/src/types/mdx.ts

@@ -0,0 +1,55 @@
+import type { ComponentProps } from 'react';
+
+
+export interface MdastNode {
+  type: string;
+  data?: Record<string, unknown>;
+  children?: MdastNode[];
+  [key: string]: unknown;
+}
+
+export interface DirectiveNode extends MdastNode {
+  type: 'containerDirective' | 'leafDirective' | 'textDirective';
+  name: string;
+  attributes?: Record<string, string | boolean | undefined>;
+}
+
+export type JsxAttributeValue =
+  | string
+  | boolean
+  | {
+      type: 'mdxJsxAttributeValueExpression';
+      value: string;
+      data?: { estree?: Record<string, unknown> };
+    };
+
+export interface JsxAttribute {
+  type: 'mdxJsxAttribute';
+  name: string;
+  value: JsxAttributeValue;
+}
+
+export interface JsxElement {
+  type: 'mdxJsxFlowElement';
+  name: string;
+  attributes: JsxAttribute[];
+  children: MdastNode[];
+}
+
+export type DocsImageProps = {
+
+  src?: string;
+
+  pack?: string;
+
+  mod?: string;
+
+  path?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  caption?: string;
+
+  defaultPack?: string;
+} & Omit<ComponentProps<'img'>, 'src' | 'alt' | 'width' | 'height' | 'className'>;

package/src/types/turndown-plugin-gfm.d.ts

@@ -0,0 +1,9 @@
+declare module 'turndown-plugin-gfm' {
+  import type { Plugin } from 'turndown';
+
+  export const gfm: Plugin;
+  export const highlightedCodeBlock: Plugin;
+  export const strikethrough: Plugin;
+  export const tables: Plugin;
+  export const taskListItems: Plugin;
+}

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.