radiant-docs 0.1.40 → 0.1.42

package/template/src/lib/validation.ts

@@ -110,6 +110,9 @@ const AVAILABLE_COMPONENTS = [
   "Step",
   "Accordion",
   "AccordionGroup",
+  "Card",
+  "Column",
+  "Columns",
   "Image",
   "CodeGroup",
   "ComponentPreview",
@@ -166,6 +169,7 @@ export type NavbarItem = {
   text: string;
   href: string;
   icon?: string | null;
+  color?: string | ThemeColorByMode;
 };
 export type HiddenPageRoute = {
   filePath: string;
@@ -208,17 +212,51 @@ 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 CardCoverTheme = {
+  colors?: string[];
+  colorSeed?: string;
+};
+export type CardButtonTheme = {
+  color?: string | ThemeColorByMode;
+};
+export type CardTheme = {
+  cover?: CardCoverTheme;
+  button?: CardButtonTheme;
 };
 export type DocsTheme = {
   baseColor?: BaseColorOption | BaseColorByMode;
   themeColor?: string | ThemeColorByMode;
+  card?: CardTheme;
+};
+export type AssistantIcon = {
+  src?: string;
+  color?: string;
+};
+export type AssistantButtonSize = "small" | "default";
+export type AssistantButtonConfig = {
+  size?: AssistantButtonSize;
+  color?: string | ThemeColorByMode;
+};
+export type AssistantNavbarButtonConfig = {
+  enabled?: boolean;
+  text?: string;
+  color?: string | ThemeColorByMode;
+};
+export type AssistantConfig = {
+  button?: AssistantButtonConfig;
+  navbarButton?: AssistantNavbarButtonConfig;
+  heading?: string;
+  questions?: string[];
+  icon?: AssistantIcon;
 };
 export type DocsConfig = {
   title: string;
   logo?: Logo;
   theme?: DocsTheme;
+  assistant?: AssistantConfig;
   home?: string;
   navigation: NavigationItem;
   navbar?: {
@@ -292,6 +330,125 @@ 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 normalizeThemeColorConfig(
+  value: unknown,
+  currentPath: Path,
+  label: string,
+): string | ThemeColorByMode {
+  if (typeof value === "string") {
+    return normalizeHexColor(value, currentPath, label);
+  }
+
+  checkType(value, "object", currentPath, label);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throwConfigError(
+      `${label} must be a string or an object with light/dark values.`,
+      currentPath,
+    );
+  }
+
+  const colorByMode = value as Record<string, unknown>;
+  const allowedKeys = new Set(["light", "dark"]);
+  for (const key of Object.keys(colorByMode)) {
+    if (!allowedKeys.has(key)) {
+      throwConfigError(`${label} object only supports 'light' and 'dark'.`, [
+        ...currentPath,
+        key,
+      ]);
+    }
+  }
+
+  const light =
+    colorByMode.light !== undefined
+      ? normalizeHexColor(colorByMode.light, [...currentPath, "light"], label)
+      : undefined;
+  const dark =
+    colorByMode.dark !== undefined
+      ? normalizeHexColor(colorByMode.dark, [...currentPath, "dark"], label)
+      : undefined;
+
+  if (light === undefined && dark === undefined) {
+    throwConfigError(
+      `${label} object must include 'light', 'dark', or both.`,
+      currentPath,
+    );
+  }
+
+  return {
+    ...(light !== undefined ? { light } : {}),
+    ...(dark !== undefined ? { dark } : {}),
+  };
+}
+
+function normalizeHexColorArray(
+  value: unknown,
+  currentPath: Path,
+  label: string,
+): string[] {
+  checkType(value, "array", currentPath, label);
+  if (!Array.isArray(value)) {
+    throwConfigError(`${label} must be an array.`, currentPath);
+  }
+
+  if (value.length < 1 || value.length > 4) {
+    throwConfigError(`${label} must include 1 to 4 colors.`, currentPath);
+  }
+
+  return value.map((color, index) =>
+    normalizeHexColor(color, [...currentPath, index], `${label} ${index + 1}`),
+  );
+}
+
+function normalizeSeedValue(
+  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);
+  }
+
+  return trimmedValue;
+}
+
 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 +527,11 @@ function normalizeInternalPageHref(
     return null;
   }
 
-  const filePath = normalizeDocsPagePath(normalizedPathname, currentPath, label);
+  const filePath = normalizeDocsPagePath(
+    normalizedPathname,
+    currentPath,
+    label,
+  );
   validateFileExistence(filePath, currentPath);
 
   return {
@@ -1172,6 +1333,21 @@ function validateNavbarItem(
 
   // Optional property
   validateIcon(item.icon, [...currentPath, "icon"]);
+  if (item.color !== undefined) {
+    if (currentPath[0] !== "navbar" || currentPath[1] !== "primary") {
+      throwConfigError(
+        "Navbar item color is only supported on navbar.primary.",
+        [...currentPath, "color"],
+      );
+    }
+
+    item.color = normalizeThemeColorConfig(
+      item.color,
+      [...currentPath, "color"],
+      "Navbar primary color",
+    );
+  }
+
   return hiddenPageRoute;
 }
 
@@ -1222,10 +1398,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 +1648,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(
@@ -1499,12 +1718,122 @@ function validateTheme(theme: DocsConfig["theme"]): void {
     }
   }
 
+  if (theme.card !== undefined) {
+    checkType(theme.card, "object", ["theme", "card"], "Theme card");
+    if (
+      typeof theme.card !== "object" ||
+      theme.card === null ||
+      Array.isArray(theme.card)
+    ) {
+      throwConfigError("Theme card must be an object.", ["theme", "card"]);
+    }
+
+    const cardTheme = theme.card as CardTheme & Record<string, unknown>;
+    const allowedCardKeys = new Set(["cover", "button"]);
+    for (const key of Object.keys(cardTheme)) {
+      if (!allowedCardKeys.has(key)) {
+        throwConfigError(
+          "Theme card configuration only supports 'cover' and 'button'.",
+          ["theme", "card", key],
+        );
+      }
+    }
+
+    if (cardTheme.cover !== undefined) {
+      checkType(
+        cardTheme.cover,
+        "object",
+        ["theme", "card", "cover"],
+        "Theme card cover",
+      );
+      if (
+        typeof cardTheme.cover !== "object" ||
+        cardTheme.cover === null ||
+        Array.isArray(cardTheme.cover)
+      ) {
+        throwConfigError("Theme card cover must be an object.", [
+          "theme",
+          "card",
+          "cover",
+        ]);
+      }
+
+      const coverTheme = cardTheme.cover as CardCoverTheme &
+        Record<string, unknown>;
+      const allowedCoverKeys = new Set(["colors", "colorSeed"]);
+      for (const key of Object.keys(coverTheme)) {
+        if (!allowedCoverKeys.has(key)) {
+          throwConfigError(
+            "Theme card cover configuration only supports 'colors' and 'colorSeed'.",
+            ["theme", "card", "cover", key],
+          );
+        }
+      }
+
+      if (coverTheme.colors !== undefined) {
+        coverTheme.colors = normalizeHexColorArray(
+          coverTheme.colors,
+          ["theme", "card", "cover", "colors"],
+          "Theme card cover colors",
+        );
+      }
+
+      if (coverTheme.colorSeed !== undefined) {
+        coverTheme.colorSeed = normalizeSeedValue(
+          coverTheme.colorSeed,
+          ["theme", "card", "cover", "colorSeed"],
+          "Theme card cover color seed",
+        );
+      }
+    }
+
+    if (cardTheme.button !== undefined) {
+      checkType(
+        cardTheme.button,
+        "object",
+        ["theme", "card", "button"],
+        "Theme card button",
+      );
+      if (
+        typeof cardTheme.button !== "object" ||
+        cardTheme.button === null ||
+        Array.isArray(cardTheme.button)
+      ) {
+        throwConfigError("Theme card button must be an object.", [
+          "theme",
+          "card",
+          "button",
+        ]);
+      }
+
+      const buttonTheme = cardTheme.button as CardButtonTheme &
+        Record<string, unknown>;
+      const allowedButtonKeys = new Set(["color"]);
+      for (const key of Object.keys(buttonTheme)) {
+        if (!allowedButtonKeys.has(key)) {
+          throwConfigError(
+            "Theme card button configuration only supports 'color'.",
+            ["theme", "card", "button", key],
+          );
+        }
+      }
+
+      if (buttonTheme.color !== undefined) {
+        buttonTheme.color = normalizeThemeColorConfig(
+          buttonTheme.color,
+          ["theme", "card", "button", "color"],
+          "Theme card button color",
+        );
+      }
+    }
+  }
+
   if (theme.themeColor === undefined) {
     return;
   }
 
   if (typeof theme.themeColor === "string") {
-    theme.themeColor = normalizeThemeColor(
+    theme.themeColor = normalizeHexColor(
       theme.themeColor,
       ["theme", "themeColor"],
       "Theme color",
@@ -1538,7 +1867,7 @@ function validateTheme(theme: DocsConfig["theme"]): void {
 
   const light =
     themeColorByMode.light !== undefined
-      ? normalizeThemeColor(
+      ? normalizeHexColor(
           themeColorByMode.light,
           ["theme", "themeColor", "light"],
           "Theme color light",
@@ -1546,7 +1875,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 +1890,308 @@ 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",
+    "navbarButton",
+    "heading",
+    "questions",
+    "icon",
+  ]);
+  for (const key of Object.keys(assistant)) {
+    if (!allowedAssistantKeys.has(key)) {
+      throwConfigError(
+        "Assistant configuration only supports 'button', 'navbarButton', 'heading', 'questions', 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", "color"]);
+    for (const key of Object.keys(assistant.button)) {
+      if (!allowedButtonKeys.has(key)) {
+        throwConfigError(
+          "Assistant button configuration only supports 'size' and 'color'.",
+          ["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.button.color !== undefined) {
+      assistant.button.color = normalizeThemeColorConfig(
+        assistant.button.color,
+        ["assistant", "button", "color"],
+        "Assistant button color",
+      );
+    }
+  }
+
+  if (assistant.navbarButton !== undefined) {
+    checkType(
+      assistant.navbarButton,
+      "object",
+      ["assistant", "navbarButton"],
+      "Assistant navbar button configuration",
+    );
+    if (
+      typeof assistant.navbarButton !== "object" ||
+      assistant.navbarButton === null ||
+      Array.isArray(assistant.navbarButton)
+    ) {
+      throwConfigError(
+        "Assistant navbar button configuration must be an object.",
+        ["assistant", "navbarButton"],
+      );
+    }
+
+    const allowedNavbarButtonKeys = new Set(["enabled", "text", "color"]);
+    for (const key of Object.keys(assistant.navbarButton)) {
+      if (!allowedNavbarButtonKeys.has(key)) {
+        throwConfigError(
+          "Assistant navbar button configuration only supports 'enabled', 'text', and 'color'.",
+          ["assistant", "navbarButton", key],
+        );
+      }
+    }
+
+    if (assistant.navbarButton.enabled !== undefined) {
+      checkType(
+        assistant.navbarButton.enabled,
+        "boolean",
+        ["assistant", "navbarButton", "enabled"],
+        "Assistant navbar button enabled",
+      );
+      if (typeof assistant.navbarButton.enabled !== "boolean") {
+        throwConfigError(
+          "Assistant navbar button enabled must be a boolean.",
+          ["assistant", "navbarButton", "enabled"],
+        );
+      }
+    }
+
+    if (assistant.navbarButton.text !== undefined) {
+      checkType(
+        assistant.navbarButton.text,
+        "string",
+        ["assistant", "navbarButton", "text"],
+        "Assistant navbar button text",
+      );
+      if (typeof assistant.navbarButton.text !== "string") {
+        throwConfigError("Assistant navbar button text must be a string.", [
+          "assistant",
+          "navbarButton",
+          "text",
+        ]);
+      }
+
+      const trimmedText = assistant.navbarButton.text.trim();
+      if (trimmedText.length === 0) {
+        throwConfigError("Assistant navbar button text cannot be empty.", [
+          "assistant",
+          "navbarButton",
+          "text",
+        ]);
+      }
+      assistant.navbarButton.text = trimmedText;
+    }
+
+    if (assistant.navbarButton.color !== undefined) {
+      assistant.navbarButton.color = normalizeThemeColorConfig(
+        assistant.navbarButton.color,
+        ["assistant", "navbarButton", "color"],
+        "Assistant navbar button color",
+      );
+    }
+  }
+
+  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.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 +2391,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);