@supatent/supatent-docs 0.1.0

package/runtime/src/framework/rendering.ts

@@ -0,0 +1,445 @@
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkDirective from "remark-directive";
+import remarkRehype from "remark-rehype";
+import rehypeRaw from "rehype-raw";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
+import rehypeStringify from "rehype-stringify";
+import { visit } from "unist-util-visit";
+import { markdownToSearchText } from "./markdown-search-text";
+
+type MdastNode = {
+  type?: string;
+  name?: string;
+  lang?: string | null;
+  meta?: string | null;
+  data?: {
+    hName?: string;
+    hProperties?: Record<string, unknown>;
+  };
+  children?: unknown[];
+};
+
+type HastNode = {
+  type?: string;
+  tagName?: string;
+  value?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+};
+
+type SanitizeAttribute = string | [string, ...(string | RegExp | boolean)[]];
+
+const sanitizeSchema = {
+  ...defaultSchema,
+  attributes: {
+    ...defaultSchema.attributes,
+    img: [
+      ...(((defaultSchema.attributes?.img ?? []) as unknown[]) as SanitizeAttribute[]),
+      "width",
+      "height",
+      "loading",
+      "decoding",
+    ],
+  },
+};
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[`*_~()[\]]/g, "")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-");
+}
+
+function textFromNode(node: unknown): string {
+  if (!node || typeof node !== "object") {
+    return "";
+  }
+
+  const typedNode = node as {
+    value?: unknown;
+    children?: unknown[];
+  };
+
+  if (typeof typedNode.value === "string") {
+    return typedNode.value;
+  }
+
+  if (Array.isArray(typedNode.children)) {
+    return typedNode.children.map(textFromNode).join("");
+  }
+
+  return "";
+}
+
+function normalizeTabLabel(value: string | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+
+  const normalized = value.trim().replace(/^["']|["']$/g, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+function fallbackTabLabel(lang: string | null | undefined, index: number): string {
+  const normalized = typeof lang === "string" ? lang.trim() : "";
+  if (normalized.length > 0) {
+    return normalized;
+  }
+  return `Code ${index}`;
+}
+
+function labelFromMeta(meta: string | null | undefined): string | null {
+  if (typeof meta !== "string") {
+    return null;
+  }
+
+  const bracket = meta.match(/\[([^\]]+)\]/);
+  if (bracket) {
+    return normalizeTabLabel(bracket[1]);
+  }
+
+  const keyed = meta.match(
+    /\b(?:label|tab|title)\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s]+))/i,
+  );
+  if (!keyed) {
+    return null;
+  }
+
+  return normalizeTabLabel(keyed[1] ?? keyed[2] ?? keyed[3]);
+}
+
+function toClassNames(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === "string");
+  }
+  if (typeof value === "string") {
+    return value.split(/\s+/).filter(Boolean);
+  }
+  return [];
+}
+
+function labelFromCodeNode(
+  codeNode: HastNode | undefined,
+  index: number,
+): string {
+  if (!codeNode || !codeNode.properties) {
+    return `Code ${index}`;
+  }
+
+  const labeled = normalizeTabLabel(
+    typeof codeNode.properties.title === "string" ? codeNode.properties.title : undefined,
+  );
+  if (labeled) {
+    return labeled;
+  }
+
+  const classes = toClassNames(codeNode.properties.className);
+  const languageClass = classes.find((className) => className.startsWith("language-"));
+  if (languageClass) {
+    return languageClass.slice("language-".length);
+  }
+
+  return `Code ${index}`;
+}
+
+function hasCodeGroupMarker(idValue: unknown): boolean {
+  if (typeof idValue === "string") {
+    return idValue.includes("docs-code-group-");
+  }
+  if (Array.isArray(idValue)) {
+    return idValue.some(
+      (entry) => typeof entry === "string" && entry.includes("docs-code-group-"),
+    );
+  }
+  return false;
+}
+
+function isElement(node: HastNode | undefined, tagName: string): boolean {
+  return node?.type === "element" && node.tagName === tagName;
+}
+
+function remarkCodeGroupDirectives() {
+  return (tree: unknown) => {
+    let groupIndex = 0;
+
+    visit(tree as never, "containerDirective", (node: unknown) => {
+      const typedNode = node as MdastNode;
+      if (typedNode.name !== "code-group") {
+        return;
+      }
+
+      groupIndex += 1;
+
+      const data = typedNode.data ?? (typedNode.data = {});
+      data.hName = "div";
+      data.hProperties = {
+        ...(data.hProperties ?? {}),
+        id: `docs-code-group-${groupIndex}`,
+      };
+
+      if (!Array.isArray(typedNode.children)) {
+        return;
+      }
+
+      let codeIndex = 0;
+      for (const childNode of typedNode.children) {
+        const codeNode = childNode as MdastNode;
+        if (codeNode.type !== "code") {
+          continue;
+        }
+
+        codeIndex += 1;
+        const label =
+          labelFromMeta(codeNode.meta) ?? fallbackTabLabel(codeNode.lang, codeIndex);
+
+        const codeData = codeNode.data ?? (codeNode.data = {});
+        codeData.hProperties = {
+          ...(codeData.hProperties ?? {}),
+          title: label,
+        };
+      }
+    });
+  };
+}
+
+function rehypeCodeGroups() {
+  return (tree: unknown) => {
+    let renderedGroupCount = 0;
+
+    visit(tree as never, "element", (node: unknown) => {
+      const groupNode = node as HastNode;
+      if (groupNode.tagName !== "div") {
+        return;
+      }
+
+      if (!hasCodeGroupMarker(groupNode.properties?.id)) {
+        return;
+      }
+
+      const children = Array.isArray(groupNode.children) ? groupNode.children : [];
+      const codeBlocks = children.filter((child) => isElement(child, "pre"));
+
+      if (codeBlocks.length === 0) {
+        return;
+      }
+
+      renderedGroupCount += 1;
+
+      const tabs: HastNode[] = [];
+      const panels: HastNode[] = [];
+
+      for (let index = 0; index < codeBlocks.length; index += 1) {
+        const preNode = codeBlocks[index];
+        const preChildren = Array.isArray(preNode.children) ? preNode.children : [];
+        const codeNode = preChildren.find((child) => isElement(child, "code"));
+        const label = labelFromCodeNode(codeNode, index + 1);
+
+        const tabId = `docs-code-tab-${renderedGroupCount}-${index + 1}`;
+        const panelId = `docs-code-panel-${renderedGroupCount}-${index + 1}`;
+        const active = index === 0;
+
+        tabs.push({
+          type: "element",
+          tagName: "button",
+          properties: {
+            type: "button",
+            className: active
+              ? ["docs-code-tab", "docs-code-tab-active"]
+              : ["docs-code-tab"],
+            role: "tab",
+            id: tabId,
+            ariaControls: panelId,
+            ariaSelected: active ? "true" : "false",
+            tabIndex: active ? 0 : -1,
+            dataCodeTab: "",
+            dataCodeIndex: String(index),
+          },
+          children: [{ type: "text", value: label }],
+        });
+
+        if (codeNode?.properties) {
+          delete codeNode.properties.title;
+        }
+
+        const preProperties = preNode.properties ?? (preNode.properties = {});
+        preProperties.className = [...toClassNames(preProperties.className), "docs-code-pre"];
+
+        panels.push({
+          type: "element",
+          tagName: "section",
+          properties: {
+            className: ["docs-code-panel"],
+            id: panelId,
+            role: "tabpanel",
+            ariaLabelledBy: tabId,
+            hidden: !active,
+            dataCodePanel: "",
+            dataCodeIndex: String(index),
+          },
+          children: [
+            {
+              type: "element",
+              tagName: "div",
+              properties: {
+                className: ["docs-code-window"],
+              },
+              children: [
+                {
+                  type: "element",
+                  tagName: "div",
+                  properties: {
+                    className: ["docs-code-window-chrome"],
+                    ariaHidden: "true",
+                  },
+                  children: [
+                    {
+                      type: "element",
+                      tagName: "span",
+                      properties: {
+                        className: ["docs-code-window-dot"],
+                      },
+                      children: [],
+                    },
+                    {
+                      type: "element",
+                      tagName: "span",
+                      properties: {
+                        className: ["docs-code-window-dot"],
+                      },
+                      children: [],
+                    },
+                    {
+                      type: "element",
+                      tagName: "span",
+                      properties: {
+                        className: ["docs-code-window-dot"],
+                      },
+                      children: [],
+                    },
+                  ],
+                },
+                {
+                  type: "element",
+                  tagName: "div",
+                  properties: {
+                    className: ["docs-code-window-content"],
+                  },
+                  children: [
+                    preNode,
+                    {
+                      type: "element",
+                      tagName: "button",
+                      properties: {
+                        type: "button",
+                        className: ["docs-code-copy"],
+                        dataCodeCopy: "",
+                        dataCodeCopyLabel: "Copy",
+                        dataCodeCopiedLabel: "Copied",
+                        ariaLabel: "Copy code block",
+                      },
+                      children: [{ type: "text", value: "Copy" }],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        });
+      }
+
+      groupNode.properties = {
+        className: ["docs-code-group"],
+      };
+
+      groupNode.children = [
+        {
+          type: "element",
+          tagName: "div",
+          properties: {
+            className: ["docs-code-tabs"],
+            role: "tablist",
+            ariaLabel: "Code examples",
+          },
+          children: tabs,
+        },
+        {
+          type: "element",
+          tagName: "div",
+          properties: {
+            className: ["docs-code-panels"],
+          },
+          children: panels,
+        },
+      ];
+    });
+  };
+}
+
+function rehypeHeadingIds() {
+  return (tree: unknown) => {
+    visit(tree as never, "element", (node: unknown) => {
+      const typedNode = node as {
+        tagName?: string;
+        properties?: Record<string, unknown>;
+        children?: unknown[];
+      };
+
+      if (typedNode.tagName !== "h2" && typedNode.tagName !== "h3") {
+        return;
+      }
+
+      const headingText = textFromNode({ children: typedNode.children ?? [] });
+      const id = slugify(headingText);
+      if (!id) {
+        return;
+      }
+
+      typedNode.properties = {
+        ...(typedNode.properties ?? {}),
+        id,
+      };
+    });
+  };
+}
+
+function createMarkdownProcessor(enableDirectives: boolean) {
+  const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm);
+
+  if (enableDirectives) {
+    processor.use(remarkDirective).use(remarkCodeGroupDirectives);
+  }
+
+  return processor
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeRaw)
+    .use(rehypeHeadingIds)
+    .use(rehypeSanitize, sanitizeSchema)
+    .use(rehypeCodeGroups)
+    .use(rehypeStringify);
+}
+
+const markdownProcessor = createMarkdownProcessor(false);
+const markdownProcessorWithDirectives = createMarkdownProcessor(true);
+const codeGroupDirectivePattern = /(^|\n):::\s*code-group\b/;
+
+function selectMarkdownProcessor(markdown: string) {
+  if (codeGroupDirectivePattern.test(markdown)) {
+    return markdownProcessorWithDirectives;
+  }
+  return markdownProcessor;
+}
+
+export async function renderMarkdownToHtml(markdown: string): Promise<string> {
+  const result = await selectMarkdownProcessor(markdown).process(markdown);
+  return String(result);
+}
+
+export function markdownToPlainText(markdown: string): string {
+  return markdownToSearchText(markdown);
+}

package/runtime/src/framework/repository.ts

@@ -0,0 +1,255 @@
+import { z } from "zod";
+import {
+  createClient,
+  type ContentItem,
+  type SupatentClient,
+} from "@supatent/client";
+import type {
+  DocsCategory,
+  DocsDataMode,
+  DocsFrameworkConfig,
+  DocsPage,
+  DocsSettings,
+} from "./types";
+import { DocsFrameworkError, toDocsFrameworkError } from "./errors";
+
+export type DocsReadOptions = {
+  publishedOnly?: boolean;
+  resolveMarkdownAssets?: boolean;
+};
+
+export type DocsRepository = {
+  getSettings(locale: string): Promise<DocsSettings | null>;
+  getCategories(locale: string, options?: DocsReadOptions): Promise<DocsCategory[]>;
+  getPages(locale: string, options?: DocsReadOptions): Promise<DocsPage[]>;
+  getPageBySlugLocale(
+    slug: string,
+    locale: string,
+    options?: DocsReadOptions,
+  ): Promise<DocsPage | null>;
+};
+
+export type DocsRepositoryOptions = {
+  dataMode?: DocsDataMode;
+};
+
+const pageFieldsSchema = z
+  .object({
+    title: z.string().min(1),
+    body: z.string(),
+    category: z.string().min(1),
+    order: z.preprocess(
+      (value) => {
+        if (typeof value === "string") {
+          return Number(value);
+        }
+        return value;
+      },
+      z.number().finite(),
+    ),
+  })
+  .passthrough();
+
+const categoryFieldsSchema = z
+  .object({
+    title: z.string().min(1),
+    order: z.preprocess(
+      (value) => {
+        if (typeof value === "string") {
+          return Number(value);
+        }
+        return value;
+      },
+      z.number().finite(),
+    ),
+  })
+  .passthrough();
+
+function normalizePage(item: ContentItem<Record<string, unknown>>): DocsPage {
+  const parsedFields = pageFieldsSchema.safeParse(item.data);
+  if (!parsedFields.success) {
+    const issues = parsedFields.error.issues.map((issue) => issue.message).join("; ");
+    throw new DocsFrameworkError(
+      "DATA_ERROR",
+      `Invalid page content shape for slug "${item.slug}": ${issues}`,
+    );
+  }
+
+  return {
+    slug: item.slug,
+    title: parsedFields.data.title,
+    body: parsedFields.data.body,
+    category: parsedFields.data.category,
+    order: parsedFields.data.order,
+    locale: item.locale,
+  };
+}
+
+function normalizeCategory(item: ContentItem<Record<string, unknown>>): DocsCategory {
+  const parsedFields = categoryFieldsSchema.safeParse(item.data);
+  if (!parsedFields.success) {
+    const issues = parsedFields.error.issues.map((issue) => issue.message).join("; ");
+    throw new DocsFrameworkError(
+      "DATA_ERROR",
+      `Invalid category content shape for slug "${item.slug}": ${issues}`,
+    );
+  }
+
+  return {
+    slug: item.slug,
+    title: parsedFields.data.title,
+    order: parsedFields.data.order,
+    locale: item.locale,
+  };
+}
+
+function sortPages(pages: DocsPage[]): DocsPage[] {
+  return [...pages].sort((a, b) => {
+    if (a.order === b.order) {
+      return a.slug.localeCompare(b.slug);
+    }
+    return a.order - b.order;
+  });
+}
+
+function sortCategories(categories: DocsCategory[]): DocsCategory[] {
+  return [...categories].sort((a, b) => {
+    if (a.order === b.order) {
+      return a.slug.localeCompare(b.slug);
+    }
+    return a.order - b.order;
+  });
+}
+
+async function resolvePageMarkdownAssets(
+  client: SupatentClient,
+  page: DocsPage,
+  options: DocsReadOptions,
+): Promise<DocsPage> {
+  if (!options.resolveMarkdownAssets) {
+    return page;
+  }
+
+  const resolvedBody = await client.resolveMarkdown(page.body);
+  if (resolvedBody === page.body) {
+    return page;
+  }
+
+  return {
+    ...page,
+    body: resolvedBody,
+  };
+}
+
+export function createSupatentDocsRepository(
+  config: DocsFrameworkConfig,
+  options: DocsRepositoryOptions = {},
+): DocsRepository {
+  const dataMode = options.dataMode ?? config.supatent.dataMode;
+  const clientByLocale = new Map<string, SupatentClient>();
+
+  function getClient(locale: string): SupatentClient {
+    const cacheKey = locale;
+    const existing = clientByLocale.get(cacheKey);
+    if (existing) {
+      return existing;
+    }
+
+    const client = createClient({
+      baseUrl: config.supatent.baseUrl,
+      projectSlug: config.supatent.projectSlug,
+      apiKey: config.supatent.apiKey,
+      preview: dataMode === "draft",
+      locale,
+      cache: {
+        maxAge: dataMode === "draft" ? 0 : config.supatent.cache.maxAge,
+        staleWhileRevalidate:
+          dataMode === "draft" ? 0 : config.supatent.cache.staleWhileRevalidate,
+      },
+    });
+
+    clientByLocale.set(cacheKey, client);
+    return client;
+  }
+
+  async function runSafely<T>(operation: () => Promise<T>): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      throw toDocsFrameworkError(error);
+    }
+  }
+
+  return {
+    async getSettings(locale) {
+      return runSafely(async () => {
+        const content = await getClient(locale)
+          .schema<Record<string, unknown>>(config.schemas.settings)
+          .first();
+
+        if (!content) {
+          return null;
+        }
+
+        return content.data as DocsSettings;
+      });
+    },
+
+    async getCategories(locale, options = {}) {
+      return runSafely(async () => {
+        const items = await getClient(locale)
+          .schema<Record<string, unknown>>(config.schemas.category)
+          .all();
+
+        const filtered = options.publishedOnly
+          ? items.filter((item) => item.publishedAt !== null)
+          : items;
+
+        return sortCategories(filtered.map(normalizeCategory));
+      });
+    },
+
+    async getPages(locale, options = {}) {
+      return runSafely(async () => {
+        const client = getClient(locale);
+        const items = await client
+          .schema<Record<string, unknown>>(config.schemas.page)
+          .all();
+
+        const filtered = options.publishedOnly
+          ? items.filter((item) => item.publishedAt !== null)
+          : items;
+
+        const pages = filtered.map(normalizePage);
+        if (!options.resolveMarkdownAssets) {
+          return sortPages(pages);
+        }
+
+        const resolvedPages = await Promise.all(
+          pages.map((page) => resolvePageMarkdownAssets(client, page, options)),
+        );
+
+        return sortPages(resolvedPages);
+      });
+    },
+
+    async getPageBySlugLocale(slug, locale, options = {}) {
+      return runSafely(async () => {
+        const client = getClient(locale);
+        const item = await client
+          .schema<Record<string, unknown>>(config.schemas.page)
+          .bySlug(slug);
+
+        if (!item) {
+          return null;
+        }
+
+        if (options.publishedOnly && item.publishedAt === null) {
+          return null;
+        }
+
+        return resolvePageMarkdownAssets(client, normalizePage(item), options);
+      });
+    },
+  };
+}