radiant-docs 0.1.39 → 0.1.40

package/template/src/components/user/Image.astro

@@ -1,28 +1,54 @@
 ---
-import type { HTMLAttributes } from "astro/types";
-import { validateProps } from "../../lib/component-error";
+import { validateNoUnknownProps, validateProps } from "../../lib/component-error";
 import { renderMarkdown } from "../../lib/utils";
 import { resolveStaticAssetUrl } from "../../lib/static-asset-url";
 
-interface Props extends HTMLAttributes<"img"> {
+interface Props {
   src: string;
+  alt?: string;
+  title?: string;
+  width?: number | string;
   zoom?: boolean;
 }
 
-const { title, zoom = true, ...attrs } = Astro.props as Props;
+const imageProps = Astro.props as Record<string, unknown>;
+
+validateNoUnknownProps(
+  "Image",
+  imageProps,
+  ["src", "alt", "title", "width", "zoom"],
+  Astro.url.pathname,
+);
+
+validateProps(
+  "Image",
+  imageProps,
+  {
+    src: { required: true, type: "string" },
+    alt: { type: "string" },
+    title: { type: "string" },
+    width: { type: ["number", "string"] },
+    zoom: { type: "boolean" },
+  },
+  Astro.url.pathname,
+);
+
+const { src, alt, title, width, zoom = true } = imageProps as Props;
 const zoomEnabled = zoom !== false;
-const attrsRecord = attrs as Record<string, unknown>;
-if (typeof attrsRecord.src === "string") {
-  attrsRecord.src = resolveStaticAssetUrl(attrsRecord.src);
+const resolvedSrc = resolveStaticAssetUrl(src);
+const rawWidth = width;
+const imageAttrs: Record<string, unknown> = { src: resolvedSrc };
+if (typeof alt === "string") {
+  imageAttrs.alt = alt;
+}
+if (width !== undefined) {
+  imageAttrs.width = width;
+}
+
+const zoomAttrs: Record<string, unknown> = { src: resolvedSrc };
+if (typeof alt === "string") {
+  zoomAttrs.alt = alt;
 }
-const rawStyle = attrsRecord.style;
-const rawWidth = attrsRecord.width;
-const zoomAttrs: Record<string, unknown> = { ...attrsRecord };
-delete zoomAttrs.style;
-delete zoomAttrs.width;
-delete zoomAttrs.height;
-delete zoomAttrs.class;
-delete zoomAttrs.className;
 
 function isConstrainedWidthValue(value: unknown): boolean {
   if (typeof value === "number") {
@@ -55,48 +81,12 @@ function isConstrainedWidthValue(value: unknown): boolean {
   return true;
 }
 
-function hasStyleWidthConstraint(styleValue: unknown): boolean {
-  if (typeof styleValue === "string") {
-    const widthMatch = styleValue.match(/(?:^|;)\s*width\s*:\s*([^;]+)/i);
-    const maxWidthMatch = styleValue.match(
-      /(?:^|;)\s*max-width\s*:\s*([^;]+)/i,
-    );
-
-    return (
-      isConstrainedWidthValue(widthMatch?.[1]) ||
-      isConstrainedWidthValue(maxWidthMatch?.[1])
-    );
-  }
-
-  if (!styleValue || typeof styleValue !== "object") return false;
-  const styleObject = styleValue as Record<string, unknown>;
-
-  return (
-    isConstrainedWidthValue(styleObject.width) ||
-    isConstrainedWidthValue(styleObject.maxWidth) ||
-    isConstrainedWidthValue(styleObject["max-width"])
-  );
-}
-
-const hasCustomImageWidth =
-  isConstrainedWidthValue(rawWidth) || hasStyleWidthConstraint(rawStyle);
+const hasCustomImageWidth = isConstrainedWidthValue(rawWidth);
 
 const captionHtml =
   typeof title === "string" && title.trim().length > 0
     ? (await renderMarkdown(title)).replace(/^<p>([\s\S]*)<\/p>\n?$/, "$1")
     : "";
-
-validateProps(
-  "Image",
-  Astro.props as Record<string, any>,
-  {
-    src: { required: true, type: "string" },
-    alt: { type: "string" },
-    title: { type: "string" },
-    zoom: { type: "boolean" },
-  },
-  Astro.url.pathname,
-);
 ---
 
 <figure
@@ -207,7 +197,7 @@ validateProps(
     class="overflow-hidden rounded-xl border border-neutral-200 dark:border-neutral-800 bg-neutral-100 dark:bg-(--rd-code-surface)"
   >
     <img
-      {...attrs}
+      {...imageAttrs}
       x-ref="img"
       title={title}
       class:list={[

package/template/src/layouts/Layout.astro

@@ -7,11 +7,18 @@ import googleSansLatinExtWoff2 from "../assets/fonts/google-sans-flex/latin-ext.
 import geistMonoLatinWoff2 from "../assets/fonts/geist-mono/latin.woff2?url";
 import geistMonoLatinExtWoff2 from "../assets/fonts/geist-mono/latin-ext.woff2?url";
 import Sidebar from "../components/Sidebar.astro";
-import { getConfig } from "../lib/validation";
+import colors from "tailwindcss/colors";
+import {
+  DEFAULT_THEME_COLOR_DARK,
+  DEFAULT_THEME_COLOR_LIGHT,
+  getConfig,
+  type BaseColorOption,
+} from "../lib/validation";
 import Header from "../components/Header.astro";
 import Footer from "../components/Footer.astro";
 import AskAiWidget from "../components/chat/AskAiWidget";
 import { ClientRouter } from "astro:transitions";
+import { prependBasePath, stripBasePath, withBasePath } from "../lib/base-path";
 import { resolveStaticAssetUrl } from "../lib/static-asset-url";
 
 interface Props {
@@ -36,6 +43,117 @@ function routePathToOgImagePath(routePath: string): string {
 
 const { pageTitle, pageDescription } = Astro.props as Props;
 const config = await getConfig();
+const themeBaseColor = config.theme?.baseColor ?? "neutral";
+const themeThemeColor = config.theme?.themeColor;
+const lightBaseColor: BaseColorOption =
+  typeof themeBaseColor === "string" ? themeBaseColor : themeBaseColor.light;
+const darkBaseColor: BaseColorOption =
+  typeof themeBaseColor === "string" ? themeBaseColor : themeBaseColor.dark;
+const lightThemeColor =
+  typeof themeThemeColor === "string"
+    ? themeThemeColor
+    : (themeThemeColor?.light ?? DEFAULT_THEME_COLOR_LIGHT);
+const darkThemeColor =
+  typeof themeThemeColor === "string"
+    ? themeThemeColor
+    : (themeThemeColor?.dark ?? DEFAULT_THEME_COLOR_DARK);
+const neutralColorShades = [
+  "50",
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900",
+  "950",
+] as const;
+const paletteColors = colors as unknown as Record<
+  string,
+  Record<(typeof neutralColorShades)[number], string>
+>;
+const getNeutralPaletteVariables = (baseColor: BaseColorOption): string[] => {
+  const palette = paletteColors[baseColor] ?? paletteColors.neutral;
+  return [
+    `--color-neutral: ${palette["500"]};`,
+    ...neutralColorShades.map(
+      (shade) => `--color-neutral-${shade}: ${palette[shade]};`,
+    ),
+  ];
+};
+function normalizeHexColorToRgb(
+  hexColor: string,
+): { r: number; g: number; b: number } | null {
+  const normalized = hexColor.replace("#", "").trim();
+  if (/^[a-fA-F0-9]{3,4}$/.test(normalized)) {
+    const [r, g, b] = normalized.split("");
+    if (!r || !g || !b) return null;
+    return {
+      r: Number.parseInt(`${r}${r}`, 16),
+      g: Number.parseInt(`${g}${g}`, 16),
+      b: Number.parseInt(`${b}${b}`, 16),
+    };
+  }
+
+  if (/^[a-fA-F0-9]{6,8}$/.test(normalized)) {
+    return {
+      r: Number.parseInt(normalized.slice(0, 2), 16),
+      g: Number.parseInt(normalized.slice(2, 4), 16),
+      b: Number.parseInt(normalized.slice(4, 6), 16),
+    };
+  }
+
+  return null;
+}
+
+function getThemeForegroundColor(hexColor: string): "#ffffff" | "#111827" {
+  const rgb = normalizeHexColorToRgb(hexColor);
+  if (!rgb) return "#ffffff";
+
+  const toLinear = (channel: number): number => {
+    const normalized = channel / 255;
+    return normalized <= 0.03928
+      ? normalized / 12.92
+      : ((normalized + 0.055) / 1.055) ** 2.4;
+  };
+
+  const luminance =
+    0.2126 * toLinear(rgb.r) +
+    0.7152 * toLinear(rgb.g) +
+    0.0722 * toLinear(rgb.b);
+  return luminance > 0.45 ? "#111827" : "#ffffff";
+}
+
+const getThemeColorVariables = (themeColor: string): string[] => {
+  const foreground = getThemeForegroundColor(themeColor);
+  const iconFilter = foreground === "#ffffff" ? "invert(1)" : "none";
+
+  return [
+    `--color-theme: ${themeColor};`,
+    `--color-theme-foreground: ${foreground};`,
+    `--color-theme-icon-filter: ${iconFilter};`,
+    "--color-theme-top: color-mix(in oklab, var(--color-theme) 88%, white);",
+    "--color-theme-bottom: color-mix(in oklab, var(--color-theme) 90%, black);",
+  ];
+};
+const lightNeutralVariables = getNeutralPaletteVariables(lightBaseColor);
+const darkNeutralVariables = getNeutralPaletteVariables(darkBaseColor);
+const lightThemeColorVariables = getThemeColorVariables(lightThemeColor);
+const darkThemeColorVariables = getThemeColorVariables(darkThemeColor);
+const neutralPaletteCss = [
+  "html[data-theme='light'], html:not(.dark):not([data-theme='dark']) {",
+  ...[...lightNeutralVariables, ...lightThemeColorVariables].map(
+    (declaration) => `  ${declaration.replace(/;$/, " !important;")}`,
+  ),
+  "}",
+  "html.dark, html[data-theme='dark'] {",
+  ...[...darkNeutralVariables, ...darkThemeColorVariables].map(
+    (declaration) => `  ${declaration.replace(/;$/, " !important;")}`,
+  ),
+  "}",
+].join("\n");
 const resolvedPageTitle = pageTitle?.trim();
 const resolvedPageDescription =
   typeof pageDescription === "string" && pageDescription.trim().length > 0
@@ -48,12 +166,13 @@ const resolvedMetaDescription = resolvedPageDescription ?? fallbackDescription;
 const documentTitle = resolvedPageTitle
   ? `${resolvedPageTitle} | ${config.title}`
   : `${config.title} Docs`;
+const routePathname = stripBasePath(Astro.url.pathname);
 const canonicalUrl = new URL(
-  Astro.url.pathname,
+  prependBasePath(routePathname),
   Astro.site ?? Astro.url,
 ).toString();
 const ogImageUrl = new URL(
-  resolveStaticAssetUrl(routePathToOgImagePath(Astro.url.pathname)),
+  resolveStaticAssetUrl(routePathToOgImagePath(routePathname)),
   Astro.site ?? Astro.url,
 );
 const ogImageHref = ogImageUrl.toString();
@@ -64,21 +183,21 @@ const parsedOrgTier = Number.parseInt(
 const orgTier =
   Number.isFinite(parsedOrgTier) && parsedOrgTier > 0 ? parsedOrgTier : 1;
 const isDev = import.meta.env.DEV;
-const askAiDevHost = (import.meta.env.ASK_AI_DEV_HOST ?? "").toString().trim();
-const askAiDevProxySecret = (import.meta.env.ASK_AI_DEV_PROXY_SECRET ?? "")
+const askAiDevHost = (import.meta.env.ASK_AI_DEV_HOST ?? "s").toString().trim();
+const askAiDevProxySecret = (import.meta.env.ASK_AI_DEV_PROXY_SECRET ?? "s")
   .toString()
   .trim();
 const hasAskAiDevConfig =
   askAiDevHost.length > 0 && askAiDevProxySecret.length > 0;
 const askAiEnabled = isDev || orgTier >= 3;
 const askAiChatAvailable = isDev ? hasAskAiDevConfig : orgTier >= 3;
-let askAiApiPath = "/_platform/ask-ai";
+let askAiApiPath = withBasePath("/_platform/ask-ai");
 
 if (isDev && hasAskAiDevConfig) {
   try {
     askAiApiPath = new URL("/_platform/ask-ai", askAiDevHost).toString();
   } catch {
-    askAiApiPath = "/_platform/ask-ai";
+    askAiApiPath = withBasePath("/_platform/ask-ai");
   }
 }
 ---
@@ -86,6 +205,7 @@ if (isDev && hasAskAiDevConfig) {
 <!doctype html>
 <html lang="en">
   <head>
+    <style is:inline is:global set:html={neutralPaletteCss}></style>
     <ClientRouter />
     <script is:inline>
       const applyTheme = () => {
@@ -115,6 +235,96 @@ if (isDev && hasAskAiDevConfig) {
       // Run on initial load
       applyTheme();
     </script>
+    <script is:inline>
+      (() => {
+        const isEmbedded = window.self !== window.top;
+        const isEmbedMode =
+          new URLSearchParams(window.location.search).get("embed") === "1";
+
+        if (!isEmbedMode || !isEmbedded) {
+          if (isEmbedMode && !isEmbedded) {
+            console.info("[iframe-ready] skipping: not embedded iframe");
+          }
+          return;
+        }
+
+        console.info("[iframe-ready] init", {
+          href: window.location.href,
+          embedded: isEmbedded,
+        });
+
+        const readySentSessionKey = "radiant_docs_iframe_ready_sent";
+        const hasSentReady = () => {
+          try {
+            const sent = sessionStorage.getItem(readySentSessionKey) === "1";
+            console.info("[iframe-ready] session flag read", {
+              key: readySentSessionKey,
+              sent,
+            });
+            return sent;
+          } catch {
+            console.warn(
+              "[iframe-ready] failed to read sessionStorage flag",
+              readySentSessionKey,
+            );
+            return false;
+          }
+        };
+        const markReadySent = () => {
+          try {
+            sessionStorage.setItem(readySentSessionKey, "1");
+            console.info("[iframe-ready] session flag set", {
+              key: readySentSessionKey,
+              value: "1",
+            });
+          } catch {
+            // Ignore storage failures (privacy mode, disabled storage, etc.)
+            console.warn(
+              "[iframe-ready] failed to set sessionStorage flag",
+              readySentSessionKey,
+            );
+          }
+        };
+
+        const notifyParentReady = () => {
+          const readyUrl = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+          console.info("[iframe-ready] posting IFRAME_READY", { readyUrl });
+          window.parent.postMessage(
+            {
+              type: "IFRAME_READY",
+              url: readyUrl,
+            },
+            "*",
+          );
+        };
+
+        const handleReadyRequest = (event) => {
+          const payload = event.data;
+          if (!payload || typeof payload !== "object") return;
+
+          if (payload.type === "IFRAME_READY_REQUEST") {
+            console.info("[iframe-ready] received IFRAME_READY_REQUEST");
+            notifyParentReady();
+          }
+        };
+
+        window.addEventListener("message", handleReadyRequest);
+
+        if (!hasSentReady()) {
+          const notifyParentReadyOnce = () => {
+            if (hasSentReady()) return;
+            markReadySent();
+            notifyParentReady();
+          };
+
+          if (document.readyState === "complete") notifyParentReadyOnce();
+          else
+            window.addEventListener("load", notifyParentReadyOnce, {
+              once: true,
+            });
+        }
+      })();
+    </script>
     <link
       rel="preload"
       href={googleSansLatinWoff2}

package/template/src/lib/base-path.ts

@@ -0,0 +1,98 @@
+const EXTERNAL_PROTOCOL_REGEX = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+
+declare global {
+  // Set by astro.config.mjs so build-time MDX remark plugins can see the
+  // configured base before Astro injects import.meta.env.BASE_URL.
+  var __RADIANT_DOCS_BASE_PATH__: string | undefined;
+}
+
+export function normalizeBasePath(value: string | null | undefined): string {
+  const trimmed = value?.trim() ?? "";
+  if (!trimmed || trimmed === "/") return "";
+
+  const pathname = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const normalized = pathname.replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+  return normalized === "/" ? "" : normalized;
+}
+
+export function getDocsBasePath(): string {
+  const astroBasePath = normalizeBasePath(import.meta.env.BASE_URL);
+  return (
+    astroBasePath ||
+    normalizeBasePath(globalThis.__RADIANT_DOCS_BASE_PATH__)
+  );
+}
+
+function splitPathSuffix(value: string): { pathname: string; suffix: string } {
+  const match = value.match(/^([^?#]*)(.*)$/);
+  return {
+    pathname: match?.[1] ?? value,
+    suffix: match?.[2] ?? "",
+  };
+}
+
+function isExternalOrDocumentLocalHref(value: string): boolean {
+  if (!value) return true;
+  if (value.startsWith("#") || value.startsWith("?")) return true;
+  if (value.startsWith("//")) return true;
+  if (value.startsWith("./") || value.startsWith("../")) return true;
+  return EXTERNAL_PROTOCOL_REGEX.test(value);
+}
+
+function applyBasePath(
+  href: string,
+  options: { preserveAlreadyPrefixed: boolean },
+): string {
+  const value = href.trim();
+  if (!value || isExternalOrDocumentLocalHref(value)) {
+    return href;
+  }
+
+  const basePath = getDocsBasePath();
+  if (!basePath) {
+    return value;
+  }
+
+  const { pathname, suffix } = splitPathSuffix(value);
+  const normalizedPathname = pathname.startsWith("/")
+    ? pathname
+    : `/${pathname}`;
+
+  if (
+    options.preserveAlreadyPrefixed &&
+    (normalizedPathname === basePath ||
+      normalizedPathname.startsWith(`${basePath}/`))
+  ) {
+    return `${normalizedPathname}${suffix}`;
+  }
+
+  if (normalizedPathname === "/") {
+    return `${basePath}${suffix}`;
+  }
+
+  return `${basePath}${normalizedPathname}${suffix}`;
+}
+
+export function withBasePath(href: string): string {
+  return applyBasePath(href, { preserveAlreadyPrefixed: true });
+}
+
+export function prependBasePath(href: string): string {
+  return applyBasePath(href, { preserveAlreadyPrefixed: false });
+}
+
+export function stripBasePath(pathname: string): string {
+  const value = pathname || "/";
+  const basePath = getDocsBasePath();
+  if (!basePath) return value;
+
+  if (value === basePath) {
+    return "/";
+  }
+
+  if (value.startsWith(`${basePath}/`)) {
+    return value.slice(basePath.length) || "/";
+  }
+
+  return value;
+}

package/template/src/lib/component-error.ts

@@ -85,27 +85,33 @@ export function validateType(
   componentName: string,
   propName: string,
   value: unknown,
-  expectedType: "string" | "number" | "boolean" | "object" | "array",
+  expectedType:
+    | "string"
+    | "number"
+    | "boolean"
+    | "object"
+    | "array"
+    | readonly ("string" | "number" | "boolean" | "object" | "array")[],
   pathname: string
 ): void {
   // Skip if undefined (optional props)
   if (value === undefined) return;
 
-  let isValid = false;
-
-  if (expectedType === "array") {
-    isValid = Array.isArray(value);
-  } else {
-    isValid = typeof value === expectedType;
-  }
+  const expectedTypes = Array.isArray(expectedType)
+    ? expectedType
+    : [expectedType];
+  const isValid = expectedTypes.some((type) =>
+    type === "array" ? Array.isArray(value) : typeof value === type
+  );
 
   if (!isValid) {
     const sourceFile = getSourceFile(pathname);
     const actualType = Array.isArray(value) ? "array" : typeof value;
+    const expectedTypeLabel = expectedTypes.join(" or ");
     throw new Error(
       formatError(
         componentName,
-        `Invalid prop "${propName}": expected ${expectedType}, got ${actualType}`,
+        `Invalid prop "${propName}": expected ${expectedTypeLabel}, got ${actualType}`,
         sourceFile
       )
     );
@@ -123,10 +129,43 @@ export function validateType(
  */
 export type PropSchema = {
   required?: boolean;
-  type?: "string" | "number" | "boolean" | "object" | "array";
+  type?:
+    | "string"
+    | "number"
+    | "boolean"
+    | "object"
+    | "array"
+    | readonly ("string" | "number" | "boolean" | "object" | "array")[];
   enum?: readonly string[];
 };
 
+/**
+ * Validates that no unsupported props are passed to a component.
+ */
+export function validateNoUnknownProps(
+  componentName: string,
+  props: Record<string, unknown>,
+  allowedProps: readonly string[],
+  pathname: string
+): void {
+  const allowed = new Set(allowedProps);
+  const unknownProps = Object.keys(props).filter((key) => !allowed.has(key));
+
+  if (unknownProps.length === 0) return;
+
+  const sourceFile = getSourceFile(pathname);
+  const unknownLabel = unknownProps.map((name) => `"${name}"`).join(", ");
+  const allowedLabel = allowedProps.map((name) => `"${name}"`).join(", ");
+  const propLabel = unknownProps.length === 1 ? "prop" : "props";
+  throw new Error(
+    formatError(
+      componentName,
+      `Unsupported ${propLabel}: ${unknownLabel}. Allowed props: ${allowedLabel}`,
+      sourceFile
+    )
+  );
+}
+
 export function validateProps(
   componentName: string,
   props: Record<string, unknown>,