@terrafirmagreg-team/kit 0.1.0 → 1.2.1

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

@@ -1,12 +1,11 @@
-import type { MDXProps } from 'mdx/types';
-import type { TOCItemType } from 'fumadocs-core/toc';
+import type { DatasetRef, SectionKey } from '@terrafirmagreg-team/sites/location';
 import type * as PageTree from 'fumadocs-core/page-tree';
-import type { ComponentType, ReactNode } from 'react';
+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 = string;
+export type { SectionKey } from '@terrafirmagreg-team/sites/location';
 
 export type SectionUrl = string;
 
@@ -38,11 +37,9 @@ 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;
+    full?: boolean;
     comments?: boolean;
     redirect?: string;
     authors?: string[];
@@ -52,6 +49,10 @@ export type SectionPage = {
           disableChangelog?: boolean;
           disableContributors?: boolean;
         };
+    load?(): Promise<unknown>;
+    content?: string;
+    structuredData?: unknown;
+    frontmatter?: Record<string, unknown>;
   };
   path: string;
   slugs: string[];
@@ -72,12 +73,15 @@ export type SectionSource = {
 export type DatasetLanding = {
   title: string;
   description?: string;
-  dataset: string;
+  dataset: DatasetRef;
   datasetTitle?: string;
   lang: Lang;
+  versions?: string[];
 };
 
 export type SectionSourceEntry = {
-  source: SectionSource;
+  getSource: () => Promise<SectionSource>;
+  getSourceSync?: () => SectionSource | undefined;
   markdown: { page(page: unknown): Promise<string> };
 };
+

package/src/{components/outline/types.ts → types/outline.ts}

@@ -27,3 +27,4 @@ export type WorkspaceOutlineDropdownProps = OutlineContent & {
 export type WorkspaceOutlinePopoverProps = WorkspaceOutlineDropdownProps & {
   container?: ComponentProps<'div'>;
 };
+

package/src/components/docs-image.tsx

@@ -1,49 +0,0 @@
-import { ImageZoom } from '@terrafirmagreg-team/ui/components/mdx/image-zoom';
-import { resolveSrc } from '@terrafirmagreg-team/kit/lib/pack-assets';
-import type { DocsImageProps } from '@terrafirmagreg-team/kit/types/mdx';
-
-export function DocsImage({
-  src,
-  pack,
-  mod,
-  path,
-  alt = '',
-  width,
-  height,
-  className,
-  caption,
-  defaultPack: pagePack,
-  ...rest
-}: DocsImageProps) {
-  const packHint = pack ?? pagePack;
-  const resolved = resolveSrc({ src, pack, mod, path }, packHint);
-  if (!resolved) {
-    return (
-      <p className="not-prose text-sm text-muted-foreground">
-        Missing image source (set <code>src</code> or <code>mod</code>+
-        <code>path</code>; pack defaults from the docs slug).
-      </p>
-    );
-  }
-
-  const w = Number(width) || 960;
-  const h = Number(height) || 540;
-
-  return (
-    <figure className="not-prose my-4 space-y-2">
-      <ImageZoom
-        src={resolved}
-        alt={alt}
-        width={w}
-        height={h}
-        className={className}
-        {...rest}
-      />
-      {caption ? (
-        <figcaption className="text-center text-sm text-muted-foreground">
-          {caption}
-        </figcaption>
-      ) : null}
-    </figure>
-  );
-}

package/src/components/search/dialog.tsx

@@ -1,145 +0,0 @@
-'use client';
-import {
-  SearchDialog as SearchDialogRoot,
-  SearchDialogClose,
-  SearchDialogContent,
-  SearchDialogFooter,
-  SearchDialogHeader,
-  SearchDialogIcon,
-  SearchDialogInput,
-  SearchDialogList,
-  SearchDialogOverlay,
-  SearchTagsList,
-  SearchTagsListItem,
-  type SharedProps,
-} from '@terrafirmagreg-team/ui/components/blocks/search/dialog';
-import {
-  useDocsSearch,
-  type SearchClient,
-} from 'fumadocs-core/search/client';
-import { staticClient } from 'fumadocs-core/search/client/orama-static';
-import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
-import { usePathname } from 'next/navigation';
-import { useMemo, useState } from 'react';
-import { Skeleton } from '@terrafirmagreg-team/ui/components/ui/skeleton';
-import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
-import { useSectionCatalog } from '@terrafirmagreg-team/kit/hooks/use-catalog';
-import {
-  dumpSectionKeys,
-  isDumpSection,
-  parseDatasetRef,
-  parseSectionLocation,
-} from '@terrafirmagreg-team/kit/lib/location';
-import { searchHitFilter, mergeClients } from '@terrafirmagreg-team/kit/lib/search';
-import { getSearchClientSources } from '@terrafirmagreg-team/kit/lib/search/sources';
-
-type Scope = 'dataset' | 'section' | 'all';
-
-export function SearchDialog(props: SharedProps & { api: string }) {
-  const locale = useResolvedLang();
-  const t = useTranslations();
-  const catalog = useSectionCatalog();
-  const pathname = usePathname();
-  const { section, dataset: locationDataset } =
-    parseSectionLocation(pathname);
-  const dataset = locationDataset
-    ? parseDatasetRef(locationDataset).id
-    : undefined;
-  const scopeKey = `${section ?? ''}/${locationDataset ?? ''}`;
-  const defaultScope: Scope = dataset
-    ? 'dataset'
-    : section
-      ? 'section'
-      : 'all';
-  const [picked, setPicked] = useState<{ key: string; value: Scope }>();
-  const scope = picked?.key === scopeKey ? picked.value : defaultScope;
-  const setScope = (value: Scope) => setPicked({ key: scopeKey, value });
-
-  const tag = useMemo((): string | string[] | undefined => {
-    if (!section || scope === 'all') return undefined;
-    if (scope === 'dataset' && dataset) {
-      return `${section}:${dataset}`;
-    }
-    const ids = catalog[section].map(({ id }) => `${section}:${id}`);
-    return ids.length > 0 ? ids : `${section}:`;
-  }, [scope, section, dataset, catalog]);
-
-  const client = useMemo((): SearchClient => {
-    const content = staticClient({ locale, tag, from: props.api });
-
-    const scopedSections =
-      scope === 'all'
-        ? dumpSectionKeys()
-        : section && isDumpSection(section)
-          ? [section]
-          : [];
-    const refs = scopedSections.flatMap((sec) =>
-      (catalog[sec] ?? []).map(({ id }) =>
-        sec === section && id === dataset && locationDataset
-          ? locationDataset
-          : id,
-      ),
-    );
-    const extra = getSearchClientSources().map((make) =>
-      make({ refs, locale, tag }),
-    );
-    return mergeClients(content, ...extra);
-  }, [locale, tag, section, scope, dataset, locationDataset, catalog, props.api]);
-  const { search, setSearch, query } = useDocsSearch({ client });
-  const items = useMemo(() => {
-    const list = query.data !== 'empty' ? (query.data ?? []) : [];
-    const hitFilter =
-      section && typeof window !== 'undefined'
-        ? searchHitFilter(
-            section,
-            new URLSearchParams(window.location.search),
-          )
-        : undefined;
-    return hitFilter ? list.filter(hitFilter) : list;
-  }, [query.data, section]);
-  const datasetMeta = catalog[section ?? 'docs']?.find(
-    ({ id }) => id === dataset,
-  );
-
-  return (
-    <SearchDialogRoot search={search} onSearchChange={setSearch} isLoading={query.isLoading} {...props}>
-      <SearchDialogOverlay />
-      <SearchDialogContent>
-        <SearchDialogHeader>
-          <SearchDialogIcon />
-          <SearchDialogInput />
-          <SearchDialogClose />
-        </SearchDialogHeader>
-        {query.isLoading ? (
-          <div className="flex flex-col gap-1.5 p-3">
-            <Skeleton className="h-9 w-full" />
-            <Skeleton className="h-9 w-5/6" />
-            <Skeleton className="h-9 w-4/6" />
-          </div>
-        ) : (
-          <SearchDialogList items={items.length ? items : null} />
-        )}
-        {section && (
-          <SearchDialogFooter>
-            <SearchTagsList
-              tag={scope}
-              onTagChange={(value) => setScope((value as Scope) ?? 'all')}
-            >
-              {dataset && (
-                <SearchTagsListItem value="dataset">
-                  {datasetMeta?.title ?? dataset}
-                </SearchTagsListItem>
-              )}
-              <SearchTagsListItem value="section">
-                {t(`sections.${section}`)}
-              </SearchTagsListItem>
-              <SearchTagsListItem value="all">
-                {t('ui.search_everywhere')}
-              </SearchTagsListItem>
-            </SearchTagsList>
-          </SearchDialogFooter>
-        )}
-      </SearchDialogContent>
-    </SearchDialogRoot>
-  );
-}

package/src/lib/legacy.ts

@@ -1,18 +0,0 @@
-import { sectionConfig } from './config';
-
-export function legacyTarget(pathname: string): string | undefined {
-  const { docsRoute, legacyRoutes } = sectionConfig();
-  const prefixes = Object.keys(legacyRoutes).sort((a, b) => b.length - a.length);
-  const parts = pathname.split('/').filter(Boolean);
-  const prefix = prefixes.find((p) => p === parts[0] || p === `${parts[0]}/${parts[2]}`);
-  if (!prefix) return undefined;
-  const prefixParts = prefix.split('/');
-  const lang = parts[1];
-  const rest = parts.slice(prefixParts.length + 1).join('/');
-  const route = legacyRoutes[prefix];
-  const override = route.overrides?.[rest];
-  const target =
-    override ??
-    `${docsRoute}/${route.dataset}${[route.path, rest].filter(Boolean).map((p) => `/${p}`).join('')}`;
-  return lang ? `${target}?lang=${lang}` : target;
-}

package/src/lib/location.ts

@@ -1,63 +0,0 @@
-import { sectionConfig } from './config';
-import type { SectionKey } from '@terrafirmagreg-team/kit/types';
-
-let urls: Record<SectionKey, string> | undefined;
-const sectionUrls = () =>
-  (urls ??= Object.fromEntries(
-    sectionConfig().sectionTabs.map(({ key, url }) => [key, url]),
-  ) as Record<SectionKey, string>);
-
-let keys: Set<SectionKey> | undefined;
-const sectionKeys = () =>
-  (keys ??= new Set(sectionConfig().sectionTabs.map(({ key }) => key)));
-
-export function sectionUrl(section: SectionKey, dataset?: string): string {
-  const base = sectionUrls()[section];
-  return dataset ? `${base}/${dataset}` : base;
-}
-
-export function isSectionKey(value: string | undefined): value is SectionKey {
-  return value !== undefined && sectionKeys().has(value);
-}
-
-export type SectionLocation = {
-  section?: SectionKey;
-
-  dataset?: string;
-};
-
-export function isDumpSection(section: SectionKey | undefined): boolean {
-  return (
-    section !== undefined &&
-    (sectionConfig().dumpSections ?? []).includes(section)
-  );
-}
-
-export function dumpSectionKeys(): readonly SectionKey[] {
-  return sectionConfig().dumpSections ?? [];
-}
-
-export function parseDatasetRef(ref: string): {
-  id: string;
-  version?: string;
-} {
-  const decoded = decodeURIComponent(ref);
-  const at = decoded.lastIndexOf('@');
-  if (at <= 0 || at === decoded.length - 1) return { id: decoded };
-  return { id: decoded.slice(0, at), version: decoded.slice(at + 1) };
-}
-
-export function datasetRef(id: string, version?: string): string {
-  return version ? `${id}@${version}` : id;
-}
-
-export function parseSectionLocation(pathname: string): SectionLocation {
-  const { basePath } = sectionConfig();
-  const path =
-    basePath && pathname.startsWith(basePath)
-      ? pathname.slice(basePath.length)
-      : pathname;
-  const [section, dataset] = path.split('/').filter(Boolean);
-  if (!isSectionKey(section)) return {};
-  return { section, dataset };
-}

package/src/lib/markdown/dom.ts

@@ -1,90 +0,0 @@
-'use client';
-import TurndownService from 'turndown';
-import { gfm } from 'turndown-plugin-gfm';
-
-const service = new TurndownService({
-  headingStyle: 'atx',
-  codeBlockStyle: 'fenced',
-  bulletListMarker: '-',
-});
-service.use(gfm);
-service.remove([
-  'script',
-  'style',
-  'noscript',
-  'template',
-  'button',
-  'select',
-  'nav',
-  'aside',
-  'footer',
-]);
-service.remove(
-  (node) =>
-    node.nodeName === 'SVG' ||
-    (node instanceof HTMLImageElement &&
-      (node.src.startsWith('data:') ||
-        (node.width > 0 && node.width <= 48))) ||
-    (node instanceof HTMLElement && node.dataset.mdSkip !== undefined),
-);
-
-function decodedUrl(raw: string): string {
-  const url = raw.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
-    let decoded: string;
-    try {
-      decoded = decodeURIComponent(run);
-    } catch {
-      return run;
-    }
-    return /[/?#&=%+]/.test(decoded) ? run : decoded;
-  });
-  return /[\s<>()]/.test(url) ? `<${url}>` : url;
-}
-
-service.addRule('decodedLink', {
-  filter: 'a',
-  replacement(content, node) {
-    const anchor = node as HTMLAnchorElement;
-    const href = anchor.getAttribute('href');
-    if (!href) return content;
-    const title = anchor.getAttribute('title');
-    const titlePart = title ? ` "${title.replace(/"/g, '\"')}"` : '';
-    return `[${content}](${decodedUrl(href)}${titlePart})`;
-  },
-});
-service.addRule('decodedImage', {
-  filter: 'img',
-  replacement(_content, node) {
-    const image = node as HTMLImageElement;
-    const src = image.getAttribute('src');
-    if (!src) return '';
-    const alt = image.getAttribute('alt') ?? '';
-    const title = image.getAttribute('title');
-    const titlePart = title ? ` "${title.replace(/"/g, '\\"')}"` : '';
-    return `![${alt}](${decodedUrl(src)}${titlePart})`;
-  },
-});
-
-export function domToMarkdown(root: Element | null | undefined): string {
-  if (!root) return '';
-  return service.turndown(root as HTMLElement);
-}
-
-export function pageMarkdown(
-  root: Element | null | undefined,
-  title: string,
-): Promise<string> {
-  return Promise.resolve(`# ${title}\n\n${domToMarkdown(root)}`);
-}
-
-export async function openPageMarkdown(
-  root: Element | null | undefined,
-  title: string,
-): Promise<void> {
-  const markdown = await pageMarkdown(root, title);
-  const url = URL.createObjectURL(
-    new Blob([markdown], { type: 'text/markdown;charset=utf-8' }),
-  );
-  window.open(url, '_blank', 'noopener');
-  setTimeout(() => URL.revokeObjectURL(url), 60_000);
-}

package/src/lib/markdown/index.ts

@@ -1,13 +0,0 @@
-export * from './dom';
-export * from './providers';
-
-export async function renderSectionMarkdown(page: {
-  data: {
-    title?: string;
-    getText: (type: 'processed' | 'raw') => Promise<string>;
-  };
-}) {
-  return `# ${page.data.title}
-
-${await page.data.getText('processed')}`;
-}

package/src/lib/markdown/providers.ts

@@ -1,25 +0,0 @@
-import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
-
-export interface MarkdownProviderCtx {
-
-  slugs: string[];
-  lang: Lang;
-}
-
-export type MarkdownProvider = (
-  req: Request,
-  ctx: MarkdownProviderCtx,
-) => Promise<Response | undefined>;
-
-const providers = new Map<string, MarkdownProvider>();
-
-export function registerMarkdownProvider(
-  section: string,
-  provider: MarkdownProvider,
-): void {
-  providers.set(section, provider);
-}
-
-export function markdownProvider(section: string): MarkdownProvider | undefined {
-  return providers.get(section);
-}

package/src/lib/mdx/accordions.ts

@@ -1,93 +0,0 @@
-import {
-  contentChildren,
-  extractDirectiveLabel,
-  extractLeafLabel,
-  jsxAttr,
-  walkContainers,
-  type DirectiveNode,
-  type JsxAttribute,
-  type JsxElement,
-  type MdastNode,
-} from './directive-utils.ts';
-
-export function remarkAccordions() {
-  return (tree: MdastNode) => {
-    walkContainers(tree, (directive) => {
-      if (directive.name === 'accordion' || directive.name === 'details') {
-        wrapSingle(directive);
-        return false;
-      }
-      if (directive.name === 'accordions') {
-        toAccordions(directive);
-        return false;
-      }
-    });
-  };
-}
-
-function toAccordion(node: DirectiveNode): JsxElement {
-  return {
-    type: 'mdxJsxFlowElement',
-    name: 'Accordion',
-    attributes: [jsxAttr('title', extractDirectiveLabel(node))],
-    children: contentChildren(node),
-  };
-}
-
-function wrapSingle(node: DirectiveNode): void {
-  Object.assign(node, {
-    type: 'mdxJsxFlowElement',
-    name: 'Accordions',
-    attributes: [],
-    children: [toAccordion(node)],
-  });
-}
-
-function accordionsAttributes(node: DirectiveNode): JsxAttribute[] {
-  const attrs = node.attributes ?? {};
-  const out: JsxAttribute[] = [];
-  const isMultiple =
-    attrs.multiple === true ||
-    attrs.multiple === '' ||
-    attrs.type === 'multiple';
-
-  if (isMultiple) out.push(jsxAttr('multiple', true));
-
-  for (const [name, value] of Object.entries(attrs)) {
-    if (name === 'type' || name === 'multiple') continue;
-    out.push({ type: 'mdxJsxAttribute', name, value: value ?? true });
-  }
-
-  return out;
-}
-
-function toAccordions(node: DirectiveNode): void {
-  const items: JsxElement[] = [];
-  let current: JsxElement | undefined;
-
-  for (const item of node.children ?? []) {
-    if (
-      item.type === 'leafDirective' &&
-      (item as { name?: string }).name === 'accordion'
-    ) {
-      current = {
-        type: 'mdxJsxFlowElement',
-        name: 'Accordion',
-        attributes: [jsxAttr('title', extractLeafLabel(item))],
-        children: [],
-      };
-      items.push(current);
-      continue;
-    }
-
-    current?.children.push(item);
-  }
-
-  Object.assign(node, {
-    type: 'mdxJsxFlowElement',
-    name: 'Accordions',
-    attributes: accordionsAttributes(node),
-    children: items,
-  });
-}
-

package/src/lib/mdx/banner.ts

@@ -1,52 +0,0 @@
-import {
-  estreeBoolean,
-  estreeStringArray,
-  jsxExpression,
-  walkContainers,
-  type DirectiveNode,
-  type MdastNode,
-} from './directive-utils.ts';
-
-
-export function remarkBanner() {
-  return (tree: MdastNode) => {
-    walkContainers(tree, (directive) => {
-      if (directive.name !== 'banner') return;
-      Object.assign(directive, {
-        type: 'mdxJsxFlowElement',
-        name: 'Banner',
-        attributes: [
-          {
-            type: 'mdxJsxAttribute',
-            name: 'changeLayout',
-            value: jsxExpression(estreeBoolean(false)),
-          },
-          ...toAttributes(directive),
-        ],
-        children: directive.children,
-      });
-      return false;
-    });
-  };
-}
-
-function toAttributes(directive: DirectiveNode) {
-  return Object.entries(directive.attributes ?? {})
-    .filter(([name]) => name !== 'id')
-    .map(([name, value]) => {
-      if (name === 'rainbowColors' && typeof value === 'string') {
-        const colors = value
-          .split(',')
-          .map((color) => color.trim())
-          .filter(Boolean);
-        return {
-          type: 'mdxJsxAttribute' as const,
-          name,
-          value: jsxExpression(estreeStringArray(colors)),
-        };
-      }
-      return { type: 'mdxJsxAttribute' as const, name, value: value ?? true };
-    });
-}
-
-