jamdesk 1.1.115 → 1.1.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.115",
+  "version": "1.1.117",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/lib/docs-types.ts

@@ -547,11 +547,23 @@ export type MintlifyLayout = 'sidenav' | 'topnav';
 
 /**
  * Background configuration
+ *
+ * `decoration: "none"` disables the theme's default decoration — on Jam this
+ * removes the light-mode radial gradient. `color` overrides the theme's
+ * `--color-bg-primary` in light and dark mode. `gradient` tunes the Jam
+ * gradient (color, size, position, opacity); ignored when `decoration` is
+ * anything other than `gradient`, or on themes without a default gradient.
  */
 export interface BackgroundConfig {
   image?: string | { light: string; dark: string };
-  decoration?: 'gradient' | 'grid' | 'windows';
+  decoration?: 'gradient' | 'grid' | 'windows' | 'none';
   color?: ColorPair;
+  gradient?: {
+    color?: string;
+    size?: string;
+    position?: 'top center' | 'top left' | 'top right' | 'center';
+    opacity?: number;
+  };
 }
 
 /**

package/vendored/lib/layout-helpers.tsx

@@ -21,7 +21,7 @@ import {
   isPreloadedFont,
   getPrimaryFontFamily,
 } from '@/lib/fonts';
-import type { DocsConfig, FontConfig, LanguageCode } from '@/lib/docs-types';
+import type { BackgroundConfig, DocsConfig, FontConfig, LanguageCode } from '@/lib/docs-types';
 import { LinkPrefixProvider } from '@/lib/link-prefix-context';
 import { ProjectSlugProvider } from '@/lib/project-slug-context';
 import { getAnalyticsScript } from '@/lib/analytics-script';
@@ -155,6 +155,114 @@ export function generatePrimaryColorVariables(
 }`;
 }
 
+// Matches hex, rgb(), or hsl() — intentionally identical surface to the
+// `colorRegex` inside generatePrimaryColorVariables (and broader than the
+// schema's colorPairSchema, which is hex-only). Drift between these is
+// intentional: docs.json validation rejects rgb/hsl in color.{light,dark},
+// but at runtime we accept anything that looks valid to defend against
+// hand-written configs that bypass the validator.
+const BG_COLOR_REGEX =
+  /^(#[0-9a-f]{3}|#[0-9a-f]{6}|rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)|hsl\(\s*\d+\s*,\s*\d+%\s*,\s*\d+%\s*\))$/i;
+const BG_SIZE_REGEX = /^\d+(\.\d+)?(px|rem|em|vh|vw|%)$/;
+const BG_POSITION_ALLOWED = new Set([
+  'top center',
+  'top left',
+  'top right',
+  'center',
+]);
+
+/**
+ * Build a `<style>` body that overrides `--color-bg-primary` (light + dark)
+ * and exposes gradient knobs (`--jd-gradient-color/size/position/opacity`)
+ * to the Jam theme CSS. Returns `null` when nothing is configured or only
+ * invalid values were provided.
+ *
+ * `decoration: "none"` is NOT rendered here — it's wired through the body's
+ * `data-decoration` attribute so the gradient rules can opt out via :not().
+ */
+export function generateBackgroundVariables(
+  background: BackgroundConfig | undefined,
+): string | null {
+  if (!background) return null;
+
+  // When the gradient is opted out via decoration: "none", suppress all
+  // gradient-related CSS vars so they don't leak into other rules. The
+  // body[data-decoration="none"] selector already gates the Jam gradient
+  // off, but emitting orphan `--jd-gradient-*` vars on :root would let any
+  // future descendant rule pick them up. Keep :root clean.
+  const gradientDisabled = background.decoration === 'none';
+
+  // typeof guards defend the .trim() calls against callers that bypass Ajv
+  // (dashboard live-preview, hand-written configs). Contract is silent-drop.
+  const validateString = (value: unknown, regex: RegExp): string | null => {
+    if (typeof value !== 'string') return null;
+    const trimmed = value.trim();
+    return regex.test(trimmed) ? trimmed : null;
+  };
+
+  const validLight = validateString(background.color?.light, BG_COLOR_REGEX);
+  const validDark = validateString(background.color?.dark, BG_COLOR_REGEX);
+
+  const g = gradientDisabled ? undefined : background.gradient;
+  const validGradientColor = validateString(g?.color, BG_COLOR_REGEX);
+  const validGradientSize = validateString(g?.size, BG_SIZE_REGEX);
+  const validGradientPosition =
+    g?.position && BG_POSITION_ALLOWED.has(g.position) ? g.position : null;
+  const validGradientOpacity =
+    typeof g?.opacity === 'number' && g.opacity >= 0 && g.opacity <= 1
+      ? g.opacity
+      : null;
+
+  const rootLines: string[] = [];
+  if (validLight) rootLines.push(`  --color-bg-primary: ${validLight};`);
+  if (validGradientColor)
+    rootLines.push(`  --jd-gradient-color: ${validGradientColor};`);
+  if (validGradientSize)
+    rootLines.push(`  --jd-gradient-size: ${validGradientSize};`);
+  if (validGradientPosition)
+    rootLines.push(`  --jd-gradient-position: ${validGradientPosition};`);
+  if (validGradientOpacity !== null) {
+    // Pre-compute the three stop percentages so the CSS sees integers/clean
+    // decimals instead of `calc(0.12 * 66.67%)` → `8.0004%`. Some Blink/WebKit
+    // versions clamp fractional percentages on color-mix inputs.
+    // Stops scale proportionally from the peak opacity.
+    const roundedPct = (multiplier: number) =>
+      Math.round(validGradientOpacity * multiplier * 100) / 100; // 2-decimal precision
+    rootLines.push(`  --jd-gradient-opacity: ${validGradientOpacity};`);
+    // Also emit the pre-computed per-stop percentages so CSS doesn't need calc().
+    rootLines.push(`  --jd-gradient-stop-peak: ${roundedPct(100)}%;`);
+    rootLines.push(`  --jd-gradient-stop-mid: ${roundedPct(66.67)}%;`);
+    rootLines.push(`  --jd-gradient-stop-far: ${roundedPct(33.33)}%;`);
+  }
+
+  const darkLines: string[] = [];
+  if (validDark) darkLines.push(`  --color-bg-primary: ${validDark};`);
+
+  // Dev-only warning when both decoration:"none" and gradient:{...} are set —
+  // the gradient is silently ignored, which would confuse the customer.
+  if (
+    gradientDisabled &&
+    background.gradient &&
+    Object.keys(background.gradient).length > 0 &&
+    process.env.NODE_ENV === 'development'
+  ) {
+    console.warn(
+      '[bg-config] background.gradient is ignored because background.decoration is "none". Set decoration to "gradient" (or omit) to apply gradient tuning.',
+    );
+  }
+
+  if (rootLines.length === 0 && darkLines.length === 0) return null;
+
+  const blocks: string[] = [];
+  if (rootLines.length > 0) {
+    blocks.push(`:root {\n${rootLines.join('\n')}\n}`);
+  }
+  if (darkLines.length > 0) {
+    blocks.push(`.dark {\n${darkLines.join('\n')}\n}`);
+  }
+  return blocks.join('\n\n');
+}
+
 export function getFontClassName(
   themeName: ThemeName | undefined,
   customFonts?: FontConfig,
@@ -284,6 +392,12 @@ export async function DocsChrome({
     config.colors?.light,
     config.colors?.dark,
   );
+  const backgroundVariables = generateBackgroundVariables(config.background);
+  // 'gradient' | 'grid' | 'windows' | 'none' | undefined. Only "none" currently
+  // alters rendering (gates off Jam's light-mode gradient + chrome transparency).
+  // The other values are stored on the body as data-decoration="<value>" so future
+  // CSS rules can target them, but no rule consumes them yet.
+  const decoration = config.background?.decoration;
 
   const appearanceDefault = config.appearance?.default || 'system';
   const appearanceStrict = config.appearance?.strict || false;
@@ -494,6 +608,14 @@ export async function DocsChrome({
             {primaryColorVariables}
           </style>
         )}
+        {backgroundVariables && (
+          <style
+            precedence="jd-layout"
+            href={`jd-bg-${resolvedProjectSlug}`}
+          >
+            {backgroundVariables}
+          </style>
+        )}
         {customCss && (
           <style
             precedence="jd-layout"
@@ -510,7 +632,7 @@ export async function DocsChrome({
           />
         )}
       </head>
-      <body className={fontClassName} data-theme={themeName || 'jam'} suppressHydrationWarning>
+      <body className={fontClassName} data-theme={themeName || 'jam'} data-decoration={decoration || undefined} suppressHydrationWarning>
         {config.integrations?.gtm?.tagId && (
           <ConditionalGTM gtmId={config.integrations.gtm.tagId} />
         )}

package/vendored/schema/docs-schema.json

@@ -272,17 +272,51 @@
                             "enum": [
                                 "gradient",
                                 "grid",
-                                "windows"
+                                "windows",
+                                "none"
                             ],
-                            "description": "Choose a background decoration style. Options: `gradient`, `grid`, or `windows`"
+                            "description": "Background decoration style. Currently implemented: `gradient` (the default for Jam) and `none` (disables Jam's light-mode radial gradient). `grid` and `windows` are reserved for future Mintlify-compatible decorations and currently render as the theme default (no warning is emitted) — do not rely on them yet."
                         },
                         "color": {
                             "$ref": "#/definitions/colorPairSchema",
-                            "description": "Customize background colors for light and dark themes"
+                            "description": "Customize background colors for light and dark themes. Overrides the theme's default `--color-bg-primary`"
+                        },
+                        "gradient": {
+                            "type": "object",
+                            "properties": {
+                                "color": {
+                                    "type": "string",
+                                    "pattern": "^(#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})|rgb\\(\\s*\\d+\\s*,\\s*\\d+\\s*,\\s*\\d+\\s*\\)|hsl\\(\\s*\\d+\\s*,\\s*\\d+%\\s*,\\s*\\d+%\\s*\\))$",
+                                    "description": "Gradient color (hex, rgb, or hsl). Defaults to the theme primary color"
+                                },
+                                "size": {
+                                    "type": "string",
+                                    "pattern": "^\\d+(\\.\\d+)?(px|rem|em|vh|vw|%)$",
+                                    "description": "Gradient radius (e.g. `500px`, `60vh`). Defaults to `500px`"
+                                },
+                                "position": {
+                                    "type": "string",
+                                    "enum": [
+                                        "top center",
+                                        "top left",
+                                        "top right",
+                                        "center"
+                                    ],
+                                    "description": "Gradient origin position. Defaults to `top center`"
+                                },
+                                "opacity": {
+                                    "type": "number",
+                                    "minimum": 0,
+                                    "maximum": 1,
+                                    "description": "Peak gradient opacity at the center (0–1). Defaults to 0.12"
+                                }
+                            },
+                            "additionalProperties": false,
+                            "description": "Customize the theme's background gradient. Currently applies only to the Jam theme (light mode). Ignored when `decoration` is `none`"
                         }
                     },
                     "additionalProperties": false,
-                    "description": "Configure background images, colors, and decorative patterns"
+                    "description": "Configure background images, colors, decorative patterns, and gradient parameters"
                 },
                 "navbar": {
                     "type": "object",

package/vendored/themes/jam/variables.css

@@ -169,19 +169,29 @@
 
 /* ===== JAM THEME BACKGROUND GRADIENT (LIGHT MODE ONLY) ===== */
 /*
- * Radial gradient radiates from top center and fades to transparent by 500px.
- * Uses a lighter version of the primary color from docs.json (--color-primary).
- * Only applied in light mode - no gradient in dark mode.
+ * Radial gradient radiates from --jd-gradient-position and fades to transparent
+ * by --jd-gradient-size. All knobs are tunable via docs.json `background.gradient`.
+ * Light mode only — no gradient in dark mode.
  *
- * IMPORTANT: Scoped to data-theme="jam" so other themes don't inherit this.
+ * Scoped to data-theme="jam" so other themes don't inherit this. Gated on
+ * :not([data-decoration="none"]) so users can disable via
+ * `background.decoration: "none"`.
  *
- * Note: We override background-color from base.css and use background instead
- * to layer the gradient on top of the base color.
+ * Defaults (used when docs.json doesn't override):
+ *   --jd-gradient-color    : var(--color-primary, #2266C2)
+ *   --jd-gradient-size     : 500px
+ *   --jd-gradient-position : top center
+ *   --jd-gradient-opacity  : 0.12
+ *
+ * Browser support: parametric customization requires color-mix() (Chrome 111+,
+ * Firefox 113+, Safari 16.2+). Older browsers fall back to the static rgba
+ * gradient block below — they see the original look but cannot customize it.
  */
-body[data-theme="jam"]:not(.dark) {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) {
   /* Override solid background-color from base.css */
   background-color: transparent;
-  /* Fallback for browsers that don't support color-mix */
+  /* Fallback gradient (static, for browsers without color-mix). Older browsers
+     keep the original Jam look even if they ignore docs.json customization. */
   background:
     radial-gradient(
       circle 500px at top center,
@@ -195,80 +205,81 @@ body[data-theme="jam"]:not(.dark) {
   background-attachment: fixed;
 }
 
-/* Modern browsers: use color-mix to dynamically use --color-primary from docs.json */
-@supports (color-mix(in srgb, red, transparent)) {
-  body[data-theme="jam"]:not(.dark) {
+/* Modern browsers: parametric gradient consuming the CSS vars.
+   Stop percentages come from --jd-gradient-stop-{peak,mid,far} when opacity
+   is overridden; otherwise they fall back to the literal default percentages.
+   Pre-computing in TS avoids fractional-percentage edge cases in older Blink
+   (e.g., `calc(0.12 * 66.67%)` → 8.0004% can be clamped). */
+@supports (background: color-mix(in srgb, red, transparent)) {
+  html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) {
     background:
       radial-gradient(
-        circle 500px at top center,
-        color-mix(in srgb, var(--color-primary, #2266C2) 12%, transparent) 0%,
-        color-mix(in srgb, var(--color-primary, #2266C2) 8%, transparent) 30%,
-        color-mix(in srgb, var(--color-primary, #2266C2) 4%, transparent) 60%,
+        circle var(--jd-gradient-size, 500px) at var(--jd-gradient-position, top center),
+        color-mix(in srgb, var(--jd-gradient-color, var(--color-primary, #2266C2)) var(--jd-gradient-stop-peak, 12%), transparent) 0%,
+        color-mix(in srgb, var(--jd-gradient-color, var(--color-primary, #2266C2)) var(--jd-gradient-stop-mid, 8%), transparent) 30%,
+        color-mix(in srgb, var(--jd-gradient-color, var(--color-primary, #2266C2)) var(--jd-gradient-stop-far, 4%), transparent) 60%,
         transparent 100%
       ),
       var(--color-bg-primary, #ffffff);
+    background-repeat: no-repeat;
+    background-attachment: fixed;
   }
 }
 
-/* Make main content area and wrappers transparent in light mode so gradient shows through */
-/* Override the bg-[var(--color-bg-primary)] Tailwind classes */
-body[data-theme="jam"]:not(.dark) main {
+/* Make main content / wrappers / chrome transparent in light mode SO the gradient shows through.
+   Only applies when the gradient is active (gated on :not([data-decoration="none"])). */
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) main {
   background-color: transparent !important;
 }
 
-/* Target wrapper divs that contain the main content (exclude chat panel) */
-body[data-theme="jam"]:not(.dark) > div > div.flex:not([role="dialog"]):not(:has([data-chat-panel])) {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) > div > div.flex:not([role="dialog"]):not(:has([data-chat-panel])) {
   background-color: transparent !important;
 }
 
-body[data-theme="jam"]:not(.dark) > div > div.flex > main {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) > div > div.flex > main {
   background-color: transparent !important;
 }
 
-/* For sidebar-logo layout: target the content wrapper */
-body[data-theme="jam"]:not(.dark) div.flex-1.lg\:ml-\[300px\] {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) div.flex-1.lg\:ml-\[300px\] {
   background-color: transparent !important;
 }
 
-/* Make header transparent in light mode so gradient shows through */
-/* Override the bg-[var(--color-bg-primary)]/80 Tailwind class */
-body[data-theme="jam"]:not(.dark) header {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) header {
   background-color: transparent !important;
   background: transparent !important;
 }
 
-/* Make sidebar transparent in light mode so gradient shows through */
-/* Override the bg-[var(--color-bg-primary)] and bg-[var(--color-bg-sidebar)] Tailwind classes */
-/* Only on desktop - mobile needs solid background for overlay menu */
 @media (min-width: 1024px) {
-  body[data-theme="jam"]:not(.dark) aside {
+  html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) aside {
     background-color: transparent !important;
     background: transparent !important;
   }
 }
 
-/* ===== SCROLL-BASED GRADIENT AND HEADER CHANGES ===== */
-/* When user scrolls past 500px, hide gradient and make header solid */
+/* ===== SOLID-BG MODE (decoration: "none") ===== */
+/* Drop the gradient entirely; use --color-bg-primary as the flat body fill.
+   Chrome is left untouched — base.css already paints it with --color-bg-primary
+   because the transparent overrides above are gated off in this mode. */
+html:not(.dark) body[data-theme="jam"][data-decoration="none"] {
+  background: var(--color-bg-primary, #ffffff);
+}
 
-/* Smooth transition for gradient fade */
-body[data-theme="jam"]:not(.dark) {
+/* ===== SCROLL-BASED GRADIENT AND HEADER CHANGES ===== */
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) {
   transition: background 0.3s ease-out;
 }
 
-/* When scrolled: hide gradient, show solid background */
-body[data-theme="jam"]:not(.dark).scrolled {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]).scrolled {
   background: var(--color-bg-primary, #ffffff) !important;
 }
 
-/* When scrolled: make header solid so content doesn't show through */
-body[data-theme="jam"]:not(.dark).scrolled header {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]).scrolled header {
   background-color: var(--color-bg-primary) !important;
   background: var(--color-bg-primary) !important;
   transition: background 0.3s ease-out;
 }
 
-/* Smooth transition for header background */
-body[data-theme="jam"]:not(.dark) header {
+html:not(.dark) body[data-theme="jam"]:not([data-decoration="none"]) header {
   transition: background 0.3s ease-out;
 }