radiant-docs 0.1.49 → 0.1.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "radiant-docs",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "CLI tool for previewing Radiant documentation locally",
   "type": "module",
   "bin": {

package/template/src/components/SidebarGroup.astro

@@ -22,7 +22,7 @@ const currentPrefix = parentSlug ? `${parentSlug}/${groupSlug}` : groupSlug;
   <div class:list={["text-sm font-semibold mb-2 flex items-center gap-2 px-2"]}>
     {item.icon && <Icon name={item.icon} class="size-4 text-neutral-500" />}
     {item.group}
-    {item.tag && <Tag>{item.tag}</Tag>}
+    {item.tag && <Tag tag={item.tag} />}
   </div>
 
   <ul>

package/template/src/components/SidebarLink.astro

@@ -3,13 +3,13 @@ import { buildMdxPageHref, deriveTitleFromEntryId } from "../lib/utils";
 import Icon from "./ui/Icon.astro";
 import Tag from "./ui/Tag.astro";
 import { getCollection } from "astro:content";
-import { getConfig } from "../lib/validation";
+import { getConfig, type NavTag } from "../lib/validation";
 
 interface Props {
   path: string;
   groupSlug?: string;
   icon?: string | null;
-  tag?: string;
+  tag?: NavTag;
   title?: string;
 }
 
@@ -61,6 +61,6 @@ const isActive = currentPath === targetPath;
   <div class="flex items-center gap-2">
     {icon && <Icon name={icon} class="size-4 opacity-75" />}
     {text}
-    {tag && <Tag>{tag}</Tag>}
+    {tag && <Tag tag={tag} />}
   </div>
 </a>

package/template/src/components/SidebarSubgroup.astro

@@ -82,7 +82,7 @@ const containsActivePage = item.pages.some((child) => {
     <div class="flex items-center gap-2">
       {item.icon && <Icon name={item.icon} class="size-4 opacity-75" />}
       {item.group}
-      {item.tag && <Tag>{item.tag}</Tag>}
+      {item.tag && <Tag tag={item.tag} />}
     </div>
     <svg
       xmlns="http://www.w3.org/2000/svg"

package/template/src/components/sidebar/SidebarEndpointLink.astro

@@ -2,13 +2,14 @@
 import Tag from "../ui/Tag.astro";
 import { buildOpenApiEndpointHref } from "../../lib/utils";
 import { methodColors } from "../../lib/utils";
+import type { NavTag } from "../../lib/validation";
 
 interface Props {
   method: string;
   path: string;
   summary?: string;
   title?: string;
-  tag?: string;
+  tag?: NavTag;
   parentSlug?: string;
 }
 
@@ -49,6 +50,6 @@ const isActive = currentPath === targetPath;
   </span>
   <div class="flex items-center gap-2 min-w-0">
     <span>{text}</span>
-    {tag && <Tag>{tag}</Tag>}
+    {tag && <Tag tag={tag} />}
   </div>
 </a>

package/template/src/components/ui/Tag.astro

@@ -1,5 +1,67 @@
+---
+import {
+  getConfig,
+  type NavTag,
+  type ThemeColorByMode,
+} from "../../lib/validation";
+
+interface Props {
+  tag?: NavTag;
+  color?: string | ThemeColorByMode;
+}
+
+const { tag, color } = Astro.props;
+const config = await getConfig();
+
+function getTagText(value: NavTag | undefined): string | undefined {
+  if (typeof value === "string") return value;
+  return value?.text;
+}
+
+function getTagColor(
+  value: NavTag | undefined,
+): string | ThemeColorByMode | undefined {
+  if (typeof value === "object" && value !== null) {
+    return value.color;
+  }
+  return undefined;
+}
+
+function resolveColorByMode(
+  value: string | ThemeColorByMode | undefined,
+): { light: string; dark: string } | undefined {
+  if (typeof value === "string") {
+    return { light: value, dark: value };
+  }
+
+  const light = value?.light ?? value?.dark;
+  const dark = value?.dark ?? value?.light;
+  if (!light || !dark) return undefined;
+
+  return { light, dark };
+}
+
+const text = getTagText(tag);
+const configuredColor =
+  color ?? getTagColor(tag) ?? config.theme?.tag?.color ?? undefined;
+const resolvedColor = resolveColorByMode(configuredColor);
+const colorStyle = resolvedColor
+  ? `--rd-tag-color-light:${resolvedColor.light};--rd-tag-color-dark:${resolvedColor.dark};`
+  : undefined;
+---
+
 <span
-  class="text-[9px] bg-blue-100/70 text-blue-800/90 border border-blue-800/10 px-1.5 py-px rounded-full tracking-wide font-semibold shrink-0 normal-case"
+  class="rd-tag text-[9px] border px-[5px] py-[2px] rounded-full tracking-wide leading-none font-medium shrink-0"
+  style={colorStyle}
 >
-  <slot />
+  {text ? text : <slot />}
 </span>
+
+<style>
+  .rd-tag {
+    --rd-tag-color: var(--rd-tag-color-light, var(--color-theme));
+    background-color: color-mix(in oklab, var(--rd-tag-color) 8%, transparent);
+    border-color: color-mix(in oklab, var(--rd-tag-color) 0%, transparent);
+    color: color-mix(in oklab, var(--rd-tag-color) 95%, transparent);
+  }
+</style>

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

@@ -282,7 +282,7 @@ const renderedCodeLinesHtml = normalizedTokenLines
 >
   <div
     class:list={[
-      "w-full max-w-full min-w-0 bg-(--rd-code-surface)",
+      "w-full max-w-full min-w-0",
       parsedInCodeGroup
         ? "rounded-tr-none rounded-xl"
         : parsedFlushTop

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

@@ -98,7 +98,7 @@ const isInitiallyExpanded = shouldShowAllCode || totalLineCount <= visibleLines;
       >
         <button
           type="button"
-          class="pointer-events-auto inline-flex h-8 items-center justify-center rounded-xl [corner-shape:superellipse(1.2)] border-[0.5px] border-neutral-900/10 dark:border-white/8 bg-linear-to-br from-white via-white/10 to-neutral-900/5 dark:from-white/7 dark:via-white/6 dark:to-white/2 px-3 text-sm font-medium text-neutral-600 hover:text-neutral-900 dark:text-neutral-300/90 hover:dark:text-neutral-200 transition-colors duration-200 hover:bg-neutral-50/80 cursor-pointer dark:hover:bg-neutral-700/30 shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-4px_rgba(0,0,0,0.08)] dark:shadow-[0_-0.5px_0px_rgba(255,255,255,0.15),0_5px_12px_-4px_rgba(0,0,0,0.6)]"
+          class="pointer-events-auto inline-flex h-8 items-center justify-center rounded-xl [corner-shape:superellipse(1.2)] border-[0.5px] border-neutral-900/10 dark:border-white/8 bg-linear-to-br from-white via-white/10 to-neutral-900/5 dark:from-white/7 dark:via-white/6 dark:to-white/2 px-3 text-sm font-medium text-neutral-600 hover:text-neutral-900 dark:text-neutral-300/90 hover:dark:text-neutral-200 transition-colors duration-200 hover:bg-neutral-50/80 cursor-pointer dark:hover:bg-neutral-700/30 shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-4px_rgba(0,0,0,0.08)] dark:shadow-[0_-0.5px_0px_rgba(255,255,255,0.15),0_5px_12px_-4px_rgba(0,0,0,0.18)]"
           data-rd-preview-expand
         >
           View code

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

@@ -114,7 +114,23 @@ function isConstrainedWidthValue(value: unknown): boolean {
   return true;
 }
 
+function toCssWidthValue(value: unknown): string | undefined {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0) return undefined;
+    return `${value}px`;
+  }
+
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim();
+  if (!normalized) return undefined;
+
+  return /^-?\d*\.?\d+$/.test(normalized) ? `${normalized}px` : normalized;
+}
+
 const hasCustomImageWidth = isConstrainedWidthValue(rawWidth);
+const contentWidthStyle = hasCustomImageWidth
+  ? `width: ${toCssWidthValue(rawWidth) ?? "auto"};`
+  : undefined;
 
 const slotCaptionHtml = Astro.slots.has("default")
   ? (await Astro.slots.render("default")).trim()
@@ -240,45 +256,46 @@ const hasCaption = slotCaptionHtml.length > 0;
   }"
 >
   <div
-    class="overflow-hidden rounded-[11px]"
+    class:list={["max-w-full", !hasCustomImageWidth && "w-full"]}
+    style={contentWidthStyle}
   >
-    <img
-      {...lightImageAttrs}
-      x-ref="lightImg"
-      title={title}
-      class:list={[
-        "h-auto my-0! block transition-opacity",
-        hasDarkSource && "dark:hidden",
-        zoomEnabled && "cursor-zoom-in",
-        hasCustomImageWidth ? "max-w-full" : "w-full",
-      ]}
-      :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
-      @click={zoomEnabled ? "zoom()" : undefined}
-    />
+    <div class="overflow-hidden rounded-[11px]">
+      <img
+        {...lightImageAttrs}
+        x-ref="lightImg"
+        title={title}
+        class:list={[
+          "h-auto my-0! block w-full transition-opacity",
+          hasDarkSource && "dark:hidden",
+          zoomEnabled && "cursor-zoom-in",
+        ]}
+        :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
+        @click={zoomEnabled ? "zoom()" : undefined}
+      />
+      {
+        darkImageAttrs && (
+          <img
+            {...darkImageAttrs}
+            x-ref="darkImg"
+            title={title}
+            class:list={[
+              "h-auto my-0! hidden w-full transition-opacity dark:block",
+              zoomEnabled && "cursor-zoom-in",
+            ]}
+            :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
+            @click={zoomEnabled ? "zoom()" : undefined}
+          />
+        )
+      }
+    </div>
     {
-      darkImageAttrs && (
-        <img
-          {...darkImageAttrs}
-          x-ref="darkImg"
-          title={title}
-          class:list={[
-            "h-auto my-0! hidden transition-opacity dark:block",
-            zoomEnabled && "cursor-zoom-in",
-            hasCustomImageWidth ? "max-w-full" : "w-full",
-          ]}
-          :class="showZoomed ? 'opacity-0 duration-0' : 'opacity-100 duration-300'"
-          @click={zoomEnabled ? "zoom()" : undefined}
-        />
+      hasCaption && (
+        <figcaption class="prose-rules mt-1! xs:mt-1.5! max-w-none! *:max-w-none! text-center text-xs! xs:text-sm! text-neutral-500 dark:text-neutral-400 leading-relaxed px-2">
+          <Fragment set:html={slotCaptionHtml} />
+        </figcaption>
       )
     }
   </div>
-  {
-    hasCaption && (
-      <figcaption class="prose-rules mt-1! xs:mt-1.5! max-w-none! *:max-w-none! text-center text-xs! xs:text-sm! text-neutral-500 dark:text-neutral-400 leading-relaxed px-2">
-        <Fragment set:html={slotCaptionHtml} />
-      </figcaption>
-    )
-  }
 
   {
     zoomEnabled && (

package/template/src/lib/validation.ts

@@ -131,7 +131,7 @@ const INTERNAL_ONLY_COMPONENTS = new Set(["ComponentPreview"]);
 export type NavPage = {
   page: string;
   icon?: string | null;
-  tag?: string;
+  tag?: NavTag;
   title?: string;
 };
 export type NavOpenApiPageRef = {
@@ -141,14 +141,14 @@ export type NavOpenApiPageRef = {
 export type NavOpenApiPage = {
   openapi: NavOpenApiPageRef;
   title?: string;
-  tag?: string;
+  tag?: NavTag;
 };
 export type NavGroup = {
   group: string;
   pages: (string | NavPage | NavGroup | NavOpenApiPage)[];
   icon?: string | null;
   expanded?: boolean; // need to add this logic
-  tag?: string;
+  tag?: NavTag;
 };
 export type NavOpenApi = {
   source: string;
@@ -199,6 +199,16 @@ export type Logo = {
   href?: string;
   pill?: string | false;
 };
+export type ThemeColorByMode = {
+  light?: string;
+  dark?: string;
+};
+export type NavTag =
+  | string
+  | {
+      text: string;
+      color?: string | ThemeColorByMode;
+    };
 export const BASE_COLOR_OPTIONS = [
   "slate",
   "gray",
@@ -217,10 +227,6 @@ export type BaseColorByMode = {
 };
 export const DEFAULT_THEME_COLOR_LIGHT = "#171717";
 export const DEFAULT_THEME_COLOR_DARK = "#f5f5f5";
-export type ThemeColorByMode = {
-  light?: string;
-  dark?: string;
-};
 export type CardCoverTheme = {
   colors?: string[];
   colorSeed?: string;
@@ -241,11 +247,15 @@ export type CodeSyntaxThemeConfig =
 export type CodeTheme = {
   syntaxTheme?: CodeSyntaxThemeConfig;
 };
+export type TagTheme = {
+  color?: string | ThemeColorByMode;
+};
 export type DocsTheme = {
   baseColor?: BaseColorOption | BaseColorByMode;
   themeColor?: string | ThemeColorByMode;
   card?: CardTheme;
   code?: CodeTheme;
+  tag?: TagTheme;
 };
 export type AssistantIcon = {
   src?: string;
@@ -428,6 +438,71 @@ function normalizeThemeColorConfig(
   };
 }
 
+function normalizeNavTagConfig(
+  value: unknown,
+  currentPath: Path,
+  label: string,
+): NavTag | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  if (typeof value === "string") {
+    const trimmedText = value.trim();
+    if (trimmedText.length === 0) {
+      throwConfigError(`${label} cannot be empty.`, currentPath);
+    }
+    return trimmedText;
+  }
+
+  checkType(value, "object", currentPath, label);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throwConfigError(
+      `${label} must be a string or an object with text and optional color.`,
+      currentPath,
+    );
+  }
+
+  const tagConfig = value as Record<string, unknown>;
+  const allowedKeys = new Set(["text", "color"]);
+  for (const key of Object.keys(tagConfig)) {
+    if (!allowedKeys.has(key)) {
+      throwConfigError(`${label} object only supports 'text' and 'color'.`, [
+        ...currentPath,
+        key,
+      ]);
+    }
+  }
+
+  checkType(tagConfig.text, "string", [...currentPath, "text"], `${label} text`);
+  if (typeof tagConfig.text !== "string") {
+    throwConfigError(`${label} text must be a string.`, [
+      ...currentPath,
+      "text",
+    ]);
+  }
+
+  const trimmedText = tagConfig.text.trim();
+  if (trimmedText.length === 0) {
+    throwConfigError(`${label} text cannot be empty.`, [
+      ...currentPath,
+      "text",
+    ]);
+  }
+
+  const color =
+    tagConfig.color !== undefined
+      ? normalizeThemeColorConfig(
+          tagConfig.color,
+          [...currentPath, "color"],
+          `${label} color`,
+        )
+      : undefined;
+
+  return {
+    text: trimmedText,
+    ...(color !== undefined ? { color } : {}),
+  };
+}
+
 function normalizeHexColorArray(
   value: unknown,
   currentPath: Path,
@@ -909,6 +984,7 @@ async function validateNavigationNode(
     checkType(item.expanded, "boolean", [...path, "expanded"], "Expanded");
 
     validateIcon(item.icon, [...path, "icon"]);
+    item.tag = normalizeNavTagConfig(item.tag, [...path, "tag"], "Group tag");
 
     // Check if pages array exists and validate children
     if (!item.pages)
@@ -947,6 +1023,7 @@ async function validateNavigationNode(
 
     // Validate optional title
     checkType(item.title, "string", [...path, "title"], "Page title");
+    item.tag = normalizeNavTagConfig(item.tag, [...path, "tag"], "Page tag");
 
     // Check D.2/D.3: Page cannot have group properties
     if ("expanded" in item)
@@ -971,7 +1048,11 @@ async function validateNavigationNode(
 
     await validateNavOpenApiPage(item.openapi, [...path, "openapi"]);
     checkType(item.title, "string", [...path, "title"], "Open API page title");
-    checkType(item.tag, "string", [...path, "tag"], "Open API page tag");
+    item.tag = normalizeNavTagConfig(
+      item.tag,
+      [...path, "tag"],
+      "Open API page tag",
+    );
 
     if ("expanded" in item)
       throwConfigError("Open API page items cannot have 'expanded'.", [
@@ -1855,6 +1936,37 @@ function validateTheme(theme: DocsConfig["theme"]): void {
     }
   }
 
+  if (theme.tag !== undefined) {
+    checkType(theme.tag, "object", ["theme", "tag"], "Theme tag");
+    if (
+      typeof theme.tag !== "object" ||
+      theme.tag === null ||
+      Array.isArray(theme.tag)
+    ) {
+      throwConfigError("Theme tag must be an object.", ["theme", "tag"]);
+    }
+
+    const tagTheme = theme.tag as TagTheme & Record<string, unknown>;
+    const allowedTagKeys = new Set(["color"]);
+    for (const key of Object.keys(tagTheme)) {
+      if (!allowedTagKeys.has(key)) {
+        throwConfigError("Theme tag configuration only supports 'color'.", [
+          "theme",
+          "tag",
+          key,
+        ]);
+      }
+    }
+
+    if (tagTheme.color !== undefined) {
+      tagTheme.color = normalizeThemeColorConfig(
+        tagTheme.color,
+        ["theme", "tag", "color"],
+        "Theme tag color",
+      );
+    }
+  }
+
   if (theme.card !== undefined) {
     checkType(theme.card, "object", ["theme", "card"], "Theme card");
     if (