radiant-docs 0.1.40 → 0.1.41

package/template/src/lib/validation.ts

@@ -208,17 +208,33 @@ export type BaseColorByMode = {
 export const DEFAULT_THEME_COLOR_LIGHT = "#171717";
 export const DEFAULT_THEME_COLOR_DARK = "#f5f5f5";
 export type ThemeColorByMode = {
-  light: string;
-  dark: string;
+  light?: string;
+  dark?: string;
 };
 export type DocsTheme = {
   baseColor?: BaseColorOption | BaseColorByMode;
   themeColor?: string | ThemeColorByMode;
 };
+export type AssistantIcon = {
+  src?: string;
+  color?: string;
+};
+export type AssistantButtonSize = "small" | "default";
+export type AssistantButtonConfig = {
+  size?: AssistantButtonSize;
+};
+export type AssistantConfig = {
+  button?: AssistantButtonConfig;
+  heading?: string;
+  questions?: string[];
+  themeColor?: string | ThemeColorByMode;
+  icon?: AssistantIcon;
+};
 export type DocsConfig = {
   title: string;
   logo?: Logo;
   theme?: DocsTheme;
+  assistant?: AssistantConfig;
   home?: string;
   navigation: NavigationItem;
   navbar?: {
@@ -292,6 +308,38 @@ function checkType(
   }
 }
 
+function normalizeHexColor(
+  value: unknown,
+  currentPath: Path,
+  label: string,
+): string {
+  checkType(value, "string", currentPath, label);
+  if (typeof value !== "string") {
+    throwConfigError(`${label} must be a string.`, currentPath);
+  }
+
+  const trimmedValue = value.trim();
+  if (trimmedValue.length === 0) {
+    throwConfigError(`${label} cannot be empty.`, currentPath);
+  }
+
+  const normalizedValue = trimmedValue.startsWith("#")
+    ? trimmedValue
+    : `#${trimmedValue}`;
+  if (
+    !/^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/.test(
+      normalizedValue,
+    )
+  ) {
+    throwConfigError(
+      `${label} must be a valid hex color (for example: #1d4ed8).`,
+      currentPath,
+    );
+  }
+
+  return normalizedValue.toLowerCase();
+}
+
 function validateFileExistence(filePath: string, currentPath: Path): void {
   // Assuming relative path from DOCS_DIR and .mdx extension
   const fullPath = path.join(DOCS_DIR, `${filePath}.mdx`);
@@ -370,7 +418,11 @@ function normalizeInternalPageHref(
     return null;
   }
 
-  const filePath = normalizeDocsPagePath(normalizedPathname, currentPath, label);
+  const filePath = normalizeDocsPagePath(
+    normalizedPathname,
+    currentPath,
+    label,
+  );
   validateFileExistence(filePath, currentPath);
 
   return {
@@ -1222,10 +1274,85 @@ function validateLogoImagePath(
 
   if (!fs.existsSync(fullPath)) {
     throwConfigError(
-      `${label} file not found. Expected: ${normalizedPath} (relative to content/docs folder)`,
+      `${label} file not found. Expected: ${normalizedPath}`,
+      currentPath,
+    );
+  }
+}
+
+function validateAssistantIconSource(
+  iconSource: unknown,
+  currentPath: Path,
+): string {
+  checkType(iconSource, "string", currentPath, "Assistant icon source");
+  if (typeof iconSource !== "string") {
+    throwConfigError("Assistant icon source must be a string.", currentPath);
+  }
+
+  const trimmedSource = iconSource.trim();
+  if (trimmedSource.length === 0) {
+    throwConfigError("Assistant icon source cannot be empty.", currentPath);
+  }
+
+  if (isUrl(trimmedSource)) {
+    throwConfigError(
+      "Assistant icon source must be a local image path relative to docs.json.",
+      currentPath,
+    );
+  }
+
+  if (trimmedSource.includes(":")) {
+    throwConfigError(
+      `Invalid assistant icon source: "${trimmedSource}". Assistant icons must be local image files, not Iconify icon names.`,
+      currentPath,
+    );
+  }
+
+  if (
+    trimmedSource.startsWith("//") ||
+    trimmedSource.startsWith("#") ||
+    trimmedSource.startsWith("?") ||
+    trimmedSource.startsWith("./") ||
+    trimmedSource.startsWith("../")
+  ) {
+    throwConfigError(
+      "Assistant icon source must be a local image path relative to docs.json.",
+      currentPath,
+    );
+  }
+
+  const parsed = new URL(trimmedSource, "https://docs.invalid/");
+  const validExtensions = [
+    ".svg",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".gif",
+    ".ico",
+    ".avif",
+  ];
+  const hasValidExtension = validExtensions.some((ext) =>
+    parsed.pathname.toLowerCase().endsWith(ext),
+  );
+  if (!hasValidExtension) {
+    throwConfigError(
+      "Assistant icon source must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif, .ico, .avif).",
+      currentPath,
+    );
+  }
+
+  const normalizedPath = parsed.pathname.replace(/^\/+/, "");
+  const fullPath = path.join(DOCS_DIR, normalizedPath);
+
+  if (!fs.existsSync(fullPath)) {
+    throwConfigError(
+      `Assistant icon source file not found. Expected: ${normalizedPath}`,
       currentPath,
     );
   }
+
+  return trimmedSource;
 }
 
 function validateLogoVariant(
@@ -1397,38 +1524,6 @@ function validateTheme(theme: DocsConfig["theme"]): void {
     return normalizedBaseColor as BaseColorOption;
   };
 
-  const normalizeThemeColor = (
-    value: unknown,
-    currentPath: Path,
-    label: string,
-  ): string => {
-    checkType(value, "string", currentPath, label);
-    if (typeof value !== "string") {
-      throwConfigError(`${label} must be a string.`, currentPath);
-    }
-
-    const trimmedValue = (value as string).trim();
-    if (trimmedValue.length === 0) {
-      throwConfigError(`${label} cannot be empty.`, currentPath);
-    }
-
-    const normalizedValue = trimmedValue.startsWith("#")
-      ? trimmedValue
-      : `#${trimmedValue}`;
-    if (
-      !/^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/.test(
-        normalizedValue,
-      )
-    ) {
-      throwConfigError(
-        `${label} must be a valid hex color (for example: #1d4ed8).`,
-        currentPath,
-      );
-    }
-
-    return normalizedValue.toLowerCase();
-  };
-
   if (theme.baseColor !== undefined) {
     if (typeof theme.baseColor === "string") {
       theme.baseColor = normalizeBaseColor(
@@ -1504,7 +1599,7 @@ function validateTheme(theme: DocsConfig["theme"]): void {
   }
 
   if (typeof theme.themeColor === "string") {
-    theme.themeColor = normalizeThemeColor(
+    theme.themeColor = normalizeHexColor(
       theme.themeColor,
       ["theme", "themeColor"],
       "Theme color",
@@ -1538,7 +1633,7 @@ function validateTheme(theme: DocsConfig["theme"]): void {
 
   const light =
     themeColorByMode.light !== undefined
-      ? normalizeThemeColor(
+      ? normalizeHexColor(
           themeColorByMode.light,
           ["theme", "themeColor", "light"],
           "Theme color light",
@@ -1546,7 +1641,7 @@ function validateTheme(theme: DocsConfig["theme"]): void {
       : undefined;
   const dark =
     themeColorByMode.dark !== undefined
-      ? normalizeThemeColor(
+      ? normalizeHexColor(
           themeColorByMode.dark,
           ["theme", "themeColor", "dark"],
           "Theme color dark",
@@ -1561,11 +1656,292 @@ function validateTheme(theme: DocsConfig["theme"]): void {
   }
 
   theme.themeColor = {
-    light: light ?? DEFAULT_THEME_COLOR_LIGHT,
-    dark: dark ?? DEFAULT_THEME_COLOR_DARK,
+    ...(light !== undefined ? { light } : {}),
+    ...(dark !== undefined ? { dark } : {}),
   };
 }
 
+function validateAssistant(assistant: DocsConfig["assistant"]): void {
+  if (assistant === undefined) return;
+
+  checkType(assistant, "object", ["assistant"], "Assistant configuration");
+  if (
+    typeof assistant !== "object" ||
+    assistant === null ||
+    Array.isArray(assistant)
+  ) {
+    throwConfigError("Assistant configuration must be an object.", [
+      "assistant",
+    ]);
+  }
+
+  const allowedAssistantKeys = new Set([
+    "button",
+    "heading",
+    "questions",
+    "themeColor",
+    "icon",
+  ]);
+  for (const key of Object.keys(assistant)) {
+    if (!allowedAssistantKeys.has(key)) {
+      throwConfigError(
+        "Assistant configuration only supports 'button', 'heading', 'questions', 'themeColor', and 'icon'.",
+        ["assistant", key],
+      );
+    }
+  }
+
+  if (assistant.button !== undefined) {
+    checkType(
+      assistant.button,
+      "object",
+      ["assistant", "button"],
+      "Assistant button configuration",
+    );
+    if (
+      typeof assistant.button !== "object" ||
+      assistant.button === null ||
+      Array.isArray(assistant.button)
+    ) {
+      throwConfigError("Assistant button configuration must be an object.", [
+        "assistant",
+        "button",
+      ]);
+    }
+
+    const allowedButtonKeys = new Set(["size"]);
+    for (const key of Object.keys(assistant.button)) {
+      if (!allowedButtonKeys.has(key)) {
+        throwConfigError(
+          "Assistant button configuration only supports 'size'.",
+          ["assistant", "button", key],
+        );
+      }
+    }
+
+    if (assistant.button.size !== undefined) {
+      checkType(
+        assistant.button.size,
+        "string",
+        ["assistant", "button", "size"],
+        "Assistant button size",
+      );
+      if (typeof assistant.button.size !== "string") {
+        throwConfigError("Assistant button size must be a string.", [
+          "assistant",
+          "button",
+          "size",
+        ]);
+      }
+
+      const trimmedSize = assistant.button.size.trim();
+      if (trimmedSize !== "small" && trimmedSize !== "default") {
+        throwConfigError(
+          "Assistant button size must be either 'small' or 'default'.",
+          ["assistant", "button", "size"],
+        );
+      }
+      assistant.button.size = trimmedSize;
+    }
+  }
+
+  if (assistant.heading !== undefined) {
+    checkType(
+      assistant.heading,
+      "string",
+      ["assistant", "heading"],
+      "Assistant heading",
+    );
+    if (typeof assistant.heading !== "string") {
+      throwConfigError("Assistant heading must be a string.", [
+        "assistant",
+        "heading",
+      ]);
+    }
+
+    const trimmedHeading = assistant.heading.trim();
+    if (trimmedHeading.length === 0) {
+      throwConfigError("Assistant heading cannot be empty.", [
+        "assistant",
+        "heading",
+      ]);
+    }
+    assistant.heading = trimmedHeading;
+  }
+
+  if (assistant.questions !== undefined) {
+    checkType(
+      assistant.questions,
+      "array",
+      ["assistant", "questions"],
+      "Assistant questions",
+    );
+    if (!Array.isArray(assistant.questions)) {
+      throwConfigError("Assistant questions must be an array.", [
+        "assistant",
+        "questions",
+      ]);
+    }
+
+    if (assistant.questions.length > 3) {
+      throwConfigError("Assistant questions can include at most 3 questions.", [
+        "assistant",
+        "questions",
+      ]);
+    }
+
+    assistant.questions = assistant.questions.map((question, index) => {
+      checkType(
+        question,
+        "string",
+        ["assistant", "questions", String(index)],
+        "Assistant question",
+      );
+      if (typeof question !== "string") {
+        throwConfigError("Assistant question must be a string.", [
+          "assistant",
+          "questions",
+          String(index),
+        ]);
+      }
+
+      const trimmedQuestion = question.trim();
+      if (trimmedQuestion.length === 0) {
+        throwConfigError(
+          "Assistant question cannot be empty.",
+          ["assistant", "questions", String(index)],
+        );
+      }
+
+      return trimmedQuestion;
+    });
+  }
+
+  if (assistant.themeColor !== undefined) {
+    if (typeof assistant.themeColor === "string") {
+      assistant.themeColor = normalizeHexColor(
+        assistant.themeColor,
+        ["assistant", "themeColor"],
+        "Assistant theme color",
+      );
+    } else {
+      checkType(
+        assistant.themeColor,
+        "object",
+        ["assistant", "themeColor"],
+        "Assistant theme color",
+      );
+      if (
+        typeof assistant.themeColor !== "object" ||
+        assistant.themeColor === null ||
+        Array.isArray(assistant.themeColor)
+      ) {
+        throwConfigError(
+          "Assistant theme color must be a string or an object with light/dark values.",
+          ["assistant", "themeColor"],
+        );
+      }
+
+      const assistantThemeColorByMode = assistant.themeColor as Record<
+        string,
+        unknown
+      >;
+      const allowedThemeColorKeys = new Set(["light", "dark"]);
+      for (const key of Object.keys(assistantThemeColorByMode)) {
+        if (!allowedThemeColorKeys.has(key)) {
+          throwConfigError(
+            "Assistant theme color object only supports 'light' and 'dark'.",
+            ["assistant", "themeColor", key],
+          );
+        }
+      }
+
+      const light =
+        assistantThemeColorByMode.light !== undefined
+          ? normalizeHexColor(
+              assistantThemeColorByMode.light,
+              ["assistant", "themeColor", "light"],
+              "Assistant theme color light",
+            )
+          : undefined;
+      const dark =
+        assistantThemeColorByMode.dark !== undefined
+          ? normalizeHexColor(
+              assistantThemeColorByMode.dark,
+              ["assistant", "themeColor", "dark"],
+              "Assistant theme color dark",
+            )
+          : undefined;
+
+      if (!light && !dark) {
+        throwConfigError(
+          "Assistant theme color object must include 'light', 'dark', or both.",
+          ["assistant", "themeColor"],
+        );
+      }
+
+      assistant.themeColor = {
+        ...(light !== undefined ? { light } : {}),
+        ...(dark !== undefined ? { dark } : {}),
+      };
+    }
+  }
+
+  if (assistant.icon === undefined) return;
+
+  checkType(
+    assistant.icon,
+    "object",
+    ["assistant", "icon"],
+    "Assistant icon",
+  );
+  if (
+    typeof assistant.icon !== "object" ||
+    assistant.icon === null ||
+    Array.isArray(assistant.icon)
+  ) {
+    throwConfigError("Assistant icon must be an object.", [
+      "assistant",
+      "icon",
+    ]);
+  }
+
+  const allowedIconKeys = new Set(["src", "color"]);
+  for (const key of Object.keys(assistant.icon)) {
+    if (!allowedIconKeys.has(key)) {
+      throwConfigError(
+        "Assistant icon only supports 'src' and 'color'.",
+        ["assistant", "icon", key],
+      );
+    }
+  }
+
+  if (
+    assistant.icon.src === undefined &&
+    assistant.icon.color === undefined
+  ) {
+    throwConfigError(
+      "Assistant icon must include 'src', 'color', or both.",
+      ["assistant", "icon"],
+    );
+  }
+
+  if (assistant.icon.src !== undefined) {
+    assistant.icon.src = validateAssistantIconSource(
+      assistant.icon.src,
+      ["assistant", "icon", "src"],
+    );
+  }
+
+  if (assistant.icon.color !== undefined) {
+    assistant.icon.color = normalizeHexColor(
+      assistant.icon.color,
+      ["assistant", "icon", "color"],
+      "Assistant icon color",
+    );
+  }
+}
+
 function validateHome(home: DocsConfig["home"]): string | undefined {
   if (home === undefined) return undefined;
 
@@ -1765,6 +2141,7 @@ async function validateConfig(config: any): Promise<DocsConfig> {
   validateTitle(config.title);
   validateLogo(config.logo);
   validateTheme(config.theme);
+  validateAssistant(config.assistant);
   await validateNavigation(config.navigation);
   config.home = validateHome(config.home);
 

package/template/src/pages/-/assistant/embed.js.ts

@@ -0,0 +1,15 @@
+import { renderAssistantEmbedScript } from "../../../lib/assistant-embed-script";
+import { getConfig } from "../../../lib/validation";
+
+export const prerender = true;
+
+export async function GET(): Promise<Response> {
+  const config = await getConfig();
+
+  return new Response(renderAssistantEmbedScript(config), {
+    headers: {
+      "Content-Type": "application/javascript; charset=utf-8",
+      "Cache-Control": "no-cache, max-age=0, must-revalidate",
+    },
+  });
+}

package/template/src/pages/-/assistant/panel.astro

@@ -0,0 +1,5 @@
+---
+import AssistantEmbedPanelPage from "../../../components/chat/AssistantEmbedPanelPage.astro";
+---
+
+<AssistantEmbedPanelPage />

package/template/src/pages/404.astro

@@ -9,10 +9,10 @@ import Layout from "../layouts/Layout.astro";
   pageDescription="The page you requested could not be found."
 >
   <section
-    class="mx-auto mt-8 h-full my-auto flex max-w-xl flex-col items-center gap-5 rounded-2xl bg-background px-6 py-10 text-center"
+    class="mx-auto mt-20 h-full my-auto flex max-w-xl flex-col items-center gap-5 rounded-2xl text-center"
   >
     <p
-      class="font-mono text-sm font-medium tracking-[0.22em] text-neutral-500 uppercase dark:text-neutral-400 border px-1 py-px pr-0.5 rounded"
+      class="rounded border border-neutral-200 bg-neutral-50 px-1 py-px pr-0.5 font-mono text-sm font-medium tracking-[0.22em] text-neutral-500 uppercase dark:border-neutral-800 dark:bg-neutral-900/60 dark:text-neutral-400"
     >
       404
     </p>
@@ -27,7 +27,7 @@ import Layout from "../layouts/Layout.astro";
     <div class="flex flex-wrap items-center justify-center gap-3">
       <button
         type="button"
-        class="inline-flex items-center justify-center gap-1.5 rounded-lg [corner-shape:superellipse(1.2)] border shadow-xs px-4 py-2 text-sm font-medium text-neutral-700/85 hover:text-neutral-700 cursor-pointer"
+        class="inline-flex items-center justify-center gap-1.5 rounded-lg [corner-shape:superellipse(1.2)] border border-neutral-200 bg-white px-4 py-2 text-sm font-medium text-neutral-700/85 shadow-xs transition hover:bg-neutral-50 hover:text-neutral-700 dark:border-neutral-800 dark:bg-neutral-900/60 dark:text-neutral-300 dark:hover:bg-neutral-800/70 dark:hover:text-neutral-100 cursor-pointer"
         onclick="history.back()"
       >
         <Icon name="lucide:arrow-big-left-dash" class="size-4" />
@@ -35,7 +35,7 @@ import Layout from "../layouts/Layout.astro";
       </button>
       <a
         href={withBasePath("/")}
-        class="inline-flex items-center justify-center gap-2 rounded-lg [corner-shape:superellipse(1.2)] border border-border px-4 py-2 text-sm font-[350] dark:font-[450] text-white bg-linear-to-b from-neutral-900/85 to-neutral-900 dark:from-neutral-100 dark:to-neutral-200 shadow-sm"
+        class="inline-flex items-center justify-center gap-2 rounded-lg [corner-shape:superellipse(1.2)] border border-border bg-linear-to-b from-neutral-900/85 to-neutral-900 px-4 py-2 text-sm font-[350] text-white shadow-sm transition hover:opacity-95 dark:from-neutral-100 dark:to-neutral-200 dark:font-[450] dark:text-neutral-950"
       >
         <Icon name="lucide:house" class="size-4" />
         Take me home