kss-modern 1.3.0 → 1.5.0

package/README.md

@@ -6,7 +6,7 @@ A modern, KSS-compatible styleguide generator. Parses KSS comment blocks from CS
 
 - KSS-compatible comment parsing from CSS/SCSS files
 - Live component previews with modifier variants
-- Per-section theme dropdown (`Themes:`) to switch previews between the default and themed views
+- Theme dropdowns — a global one in the header (`previewThemes` option) and per-section ones (`Themes:`) — switch previews between the default and themed views, optionally loading a stylesheet per theme
 - Pug template support via worker thread pool
 - Color palette and icon gallery documentation
 - Figma embed integration with light/dark theme sync

package/dist/node/lib/index.d.mts

@@ -99,7 +99,37 @@ declare function createLogger(tag?: string): Logger;
 /** Shared styleguide logger instance. */
 declare const logger: Logger;
 
-interface StyleguideConfiguration {
+/** The styleguide's accent colour: one value, or one per color scheme. */
+type StyleguideBrandColor = string | {
+    light: string;
+    dark: string;
+};
+/**
+ * One entry of the header's **Theme** dropdown — an alternative theme context the previews can be
+ * shown in, not a color scheme (that is the separate System/Light/Dark toggle).
+ */
+interface PreviewTheme {
+    /**
+     * The theme's class or class list — `'theme-midnight'`, `'.theme-midnight.compact'` — added to
+     * the `<html>` of every preview iframe while the theme is selected.
+     */
+    value: string;
+    /** The label shown in the dropdown. */
+    label: string;
+    /**
+     * Stylesheets loaded into a preview while this theme is selected, layered on top of
+     * `html.assets.css` (they are never replaced). Every preview document carries a `<link>` for
+     * each of these from the start — inert until the theme is selected — so switching costs no
+     * request and shows no flash.
+     *
+     * The CSS is keyed on the theme's class list, so a section's `Themes:` entry gets the same
+     * stylesheets as soon as it resolves to the same classes (`.theme-midnight` here and in the
+     * KSS comment); a section theme that matches no configured entry simply loads no extra CSS.
+     */
+    css?: string[];
+}
+/** Every styleguide option except the accent colour, which carries the deprecated `theme` alias. */
+interface StyleguideOptions {
     mode: 'development' | 'production';
     outDir: string;
     contentDir: `${string}/`;
@@ -108,10 +138,21 @@ interface StyleguideConfiguration {
     launchInEditor?: boolean | {
         rootDir: string;
     };
-    theme: string | {
-        light: string;
-        dark: string;
-    };
+    /** The themes offered by the header's **Theme** dropdown. */
+    previewThemes?: PreviewTheme[];
+    /** @deprecated Renamed to `previewThemes`, to tell it apart from `brandColor`. */
+    themes?: PreviewTheme[];
+    /**
+     * Reload a preview iframe when its theme changes, instead of swapping the theme's classes and
+     * stylesheets into the loaded document.
+     *
+     * Off by default: the in-place swap is instant and keeps the preview's state. Turn it on when a
+     * preview's own JavaScript reads styling at startup — components that measure, canvas/chart
+     * rendering, web components that snapshot tokens on connect — and so needs to run again against
+     * the new theme. A preview is reloaded only when the visitor actually changes a theme, never on
+     * the initial page load.
+     */
+    reloadPreviewsOnThemeChange?: boolean;
     logoSignet?: {
         href: string;
     } | {
@@ -135,6 +176,35 @@ interface StyleguideConfiguration {
         ogImage?: (section: in2Section) => string;
     };
 }
+/**
+ * The styleguide configuration. The accent colour is required under one of its two names:
+ * `brandColor`, or the deprecated `theme`.
+ *
+ * `theme` never had anything to do with the preview themes; it is the colour behind
+ * `<meta name="theme-color">`, the generated favicons and the styleguide UI's highlight — hence
+ * the rename, which also ends its collision with `themes` / `previewThemes`.
+ */
+type StyleguideConfiguration = (StyleguideOptions & {
+    brandColor: StyleguideBrandColor;
+    theme?: never;
+}) | (StyleguideOptions & {
+    /** @deprecated Renamed to `brandColor` — this is the accent colour, not a preview theme. */
+    theme: StyleguideBrandColor;
+    brandColor?: never;
+});
+/**
+ * A configuration with the deprecated aliases resolved away. Everything past
+ * {@link resolveConfiguration} works with this, so no internal code has to know about the old names.
+ */
+interface ResolvedStyleguideConfiguration extends StyleguideOptions {
+    brandColor: StyleguideBrandColor;
+    previewThemes: PreviewTheme[];
+}
+/**
+ * Resolve the deprecated `theme` / `themes` aliases into `brandColor` / `previewThemes`, warning
+ * once per option. Idempotent, so the public entry points can each call it without re-warning.
+ */
+declare function resolveConfiguration(config: StyleguideConfiguration | ResolvedStyleguideConfiguration): ResolvedStyleguideConfiguration;
 interface StyleguideBuildOutput {
     errors?: {
         overwrittenSectionsIds?: string[];
@@ -188,7 +258,7 @@ declare function parseStyleguide(contentDir: StyleguideConfiguration['contentDir
  * Full build: parse, compile every section, and write all fullpage + preview files. Returns the
  * reusable context so the watcher can perform targeted incremental rebuilds afterwards.
  */
-declare function buildAll(config: StyleguideConfiguration): Promise<{
+declare function buildAll(input: StyleguideConfiguration | ResolvedStyleguideConfiguration): Promise<{
     errors: StyleguideBuildOutput['errors'];
     context: StyleguideContext;
 }>;
@@ -202,7 +272,7 @@ declare function buildStyleguide(config: StyleguideConfiguration): Promise<Style
  * (cache-aware), re-resolve <insert-markup>, and rewrite just their fullpage + owning preview files.
  * `changedSectionIds` are the sections whose pug (or a dependency) changed.
  */
-declare function rebuildSections(config: StyleguideConfiguration, context: StyleguideContext, changedSectionIds: Iterable<string>): Promise<void>;
+declare function rebuildSections(config: ResolvedStyleguideConfiguration, context: StyleguideContext, changedSectionIds: Iterable<string>): Promise<void>;
 /**
  * What triggered a {@link watchStyleguide} rebuild:
  * - `structural` — a CSS/SCSS/Markdown edit that can change section structure; the whole styleguide is rebuilt.
@@ -217,11 +287,11 @@ type StyleguideChange = {
 };
 /**
  * Builds the styleguide and watches for changes
- * @param config - The configuration for the styleguide
+ * @param input - The configuration for the styleguide
  * @param onChange - Optional callback invoked after each rebuild, with the change that triggered it
  * @param onError - Optional callback function to call when an error occurs while building the styleguide
  */
-declare function watchStyleguide(config: StyleguideConfiguration, onChange?: (change: StyleguideChange) => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
+declare function watchStyleguide(input: StyleguideConfiguration | ResolvedStyleguideConfiguration, onChange?: (change: StyleguideChange) => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
 
-export { buildAll, buildStyleguide, createLogger, logger, parseStyleguide, rebuildSections, watchStyleguide };
-export type { LogBox, Logger, StyleguideChange, StyleguideConfiguration, StyleguideContext };
+export { buildAll, buildStyleguide, createLogger, logger, parseStyleguide, rebuildSections, resolveConfiguration, watchStyleguide };
+export type { LogBox, Logger, PreviewTheme, ResolvedStyleguideConfiguration, StyleguideBrandColor, StyleguideChange, StyleguideConfiguration, StyleguideContext };

package/dist/node/lib/index.d.ts

@@ -99,7 +99,37 @@ declare function createLogger(tag?: string): Logger;
 /** Shared styleguide logger instance. */
 declare const logger: Logger;
 
-interface StyleguideConfiguration {
+/** The styleguide's accent colour: one value, or one per color scheme. */
+type StyleguideBrandColor = string | {
+    light: string;
+    dark: string;
+};
+/**
+ * One entry of the header's **Theme** dropdown — an alternative theme context the previews can be
+ * shown in, not a color scheme (that is the separate System/Light/Dark toggle).
+ */
+interface PreviewTheme {
+    /**
+     * The theme's class or class list — `'theme-midnight'`, `'.theme-midnight.compact'` — added to
+     * the `<html>` of every preview iframe while the theme is selected.
+     */
+    value: string;
+    /** The label shown in the dropdown. */
+    label: string;
+    /**
+     * Stylesheets loaded into a preview while this theme is selected, layered on top of
+     * `html.assets.css` (they are never replaced). Every preview document carries a `<link>` for
+     * each of these from the start — inert until the theme is selected — so switching costs no
+     * request and shows no flash.
+     *
+     * The CSS is keyed on the theme's class list, so a section's `Themes:` entry gets the same
+     * stylesheets as soon as it resolves to the same classes (`.theme-midnight` here and in the
+     * KSS comment); a section theme that matches no configured entry simply loads no extra CSS.
+     */
+    css?: string[];
+}
+/** Every styleguide option except the accent colour, which carries the deprecated `theme` alias. */
+interface StyleguideOptions {
     mode: 'development' | 'production';
     outDir: string;
     contentDir: `${string}/`;
@@ -108,10 +138,21 @@ interface StyleguideConfiguration {
     launchInEditor?: boolean | {
         rootDir: string;
     };
-    theme: string | {
-        light: string;
-        dark: string;
-    };
+    /** The themes offered by the header's **Theme** dropdown. */
+    previewThemes?: PreviewTheme[];
+    /** @deprecated Renamed to `previewThemes`, to tell it apart from `brandColor`. */
+    themes?: PreviewTheme[];
+    /**
+     * Reload a preview iframe when its theme changes, instead of swapping the theme's classes and
+     * stylesheets into the loaded document.
+     *
+     * Off by default: the in-place swap is instant and keeps the preview's state. Turn it on when a
+     * preview's own JavaScript reads styling at startup — components that measure, canvas/chart
+     * rendering, web components that snapshot tokens on connect — and so needs to run again against
+     * the new theme. A preview is reloaded only when the visitor actually changes a theme, never on
+     * the initial page load.
+     */
+    reloadPreviewsOnThemeChange?: boolean;
     logoSignet?: {
         href: string;
     } | {
@@ -135,6 +176,35 @@ interface StyleguideConfiguration {
         ogImage?: (section: in2Section) => string;
     };
 }
+/**
+ * The styleguide configuration. The accent colour is required under one of its two names:
+ * `brandColor`, or the deprecated `theme`.
+ *
+ * `theme` never had anything to do with the preview themes; it is the colour behind
+ * `<meta name="theme-color">`, the generated favicons and the styleguide UI's highlight — hence
+ * the rename, which also ends its collision with `themes` / `previewThemes`.
+ */
+type StyleguideConfiguration = (StyleguideOptions & {
+    brandColor: StyleguideBrandColor;
+    theme?: never;
+}) | (StyleguideOptions & {
+    /** @deprecated Renamed to `brandColor` — this is the accent colour, not a preview theme. */
+    theme: StyleguideBrandColor;
+    brandColor?: never;
+});
+/**
+ * A configuration with the deprecated aliases resolved away. Everything past
+ * {@link resolveConfiguration} works with this, so no internal code has to know about the old names.
+ */
+interface ResolvedStyleguideConfiguration extends StyleguideOptions {
+    brandColor: StyleguideBrandColor;
+    previewThemes: PreviewTheme[];
+}
+/**
+ * Resolve the deprecated `theme` / `themes` aliases into `brandColor` / `previewThemes`, warning
+ * once per option. Idempotent, so the public entry points can each call it without re-warning.
+ */
+declare function resolveConfiguration(config: StyleguideConfiguration | ResolvedStyleguideConfiguration): ResolvedStyleguideConfiguration;
 interface StyleguideBuildOutput {
     errors?: {
         overwrittenSectionsIds?: string[];
@@ -188,7 +258,7 @@ declare function parseStyleguide(contentDir: StyleguideConfiguration['contentDir
  * Full build: parse, compile every section, and write all fullpage + preview files. Returns the
  * reusable context so the watcher can perform targeted incremental rebuilds afterwards.
  */
-declare function buildAll(config: StyleguideConfiguration): Promise<{
+declare function buildAll(input: StyleguideConfiguration | ResolvedStyleguideConfiguration): Promise<{
     errors: StyleguideBuildOutput['errors'];
     context: StyleguideContext;
 }>;
@@ -202,7 +272,7 @@ declare function buildStyleguide(config: StyleguideConfiguration): Promise<Style
  * (cache-aware), re-resolve <insert-markup>, and rewrite just their fullpage + owning preview files.
  * `changedSectionIds` are the sections whose pug (or a dependency) changed.
  */
-declare function rebuildSections(config: StyleguideConfiguration, context: StyleguideContext, changedSectionIds: Iterable<string>): Promise<void>;
+declare function rebuildSections(config: ResolvedStyleguideConfiguration, context: StyleguideContext, changedSectionIds: Iterable<string>): Promise<void>;
 /**
  * What triggered a {@link watchStyleguide} rebuild:
  * - `structural` — a CSS/SCSS/Markdown edit that can change section structure; the whole styleguide is rebuilt.
@@ -217,11 +287,11 @@ type StyleguideChange = {
 };
 /**
  * Builds the styleguide and watches for changes
- * @param config - The configuration for the styleguide
+ * @param input - The configuration for the styleguide
  * @param onChange - Optional callback invoked after each rebuild, with the change that triggered it
  * @param onError - Optional callback function to call when an error occurs while building the styleguide
  */
-declare function watchStyleguide(config: StyleguideConfiguration, onChange?: (change: StyleguideChange) => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
+declare function watchStyleguide(input: StyleguideConfiguration | ResolvedStyleguideConfiguration, onChange?: (change: StyleguideChange) => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
 
-export { buildAll, buildStyleguide, createLogger, logger, parseStyleguide, rebuildSections, watchStyleguide };
-export type { LogBox, Logger, StyleguideChange, StyleguideConfiguration, StyleguideContext };
+export { buildAll, buildStyleguide, createLogger, logger, parseStyleguide, rebuildSections, resolveConfiguration, watchStyleguide };
+export type { LogBox, Logger, PreviewTheme, ResolvedStyleguideConfiguration, StyleguideBrandColor, StyleguideChange, StyleguideConfiguration, StyleguideContext };

package/dist/node/lib/index.mjs

@@ -1353,6 +1353,7 @@ async function generateFullPageFile(data) {
   const computedStyleTags = data.css.filter((entry) => entry.type !== "overwriteStyleguide").map((css) => {
     return `<link rel="stylesheet" type="text/css" href="${css.src}">`;
   }).join("\n");
+  const computedThemeStyleTags = (data.previewThemes ?? []).flatMap((theme) => (theme.css ?? []).map((src) => ({ src, classList: themeClassList(theme.value) }))).filter((entry) => entry.classList).map((entry) => `<link rel="stylesheet" type="text/css" href="${entry.src}" media="not all" data-theme-css="${sanitizeSpecialCharacters(entry.classList)}">`).join("\n");
   const content = `
 <!DOCTYPE html>
 <html lang="${data.page.lang}"${data.page.htmlclass ? ` class="scroll-smooth ${data.page.htmlclass}"` : ""} data-styleguide-dark-mode="${supportsDarkMode}">
@@ -1364,12 +1365,13 @@ async function generateFullPageFile(data) {
     <meta name="generator" content="styleguide">
     <link rel="icon" type="image/svg+xml" href="/styleguide-assets/favicon/fullpage.svg">
     ${data.ogImageUrl ? `<meta property="og:image" content="${data.ogImageUrl}">` : ""}
-    ${typeof data.theme === "object" && "dark" in data.theme && "light" in data.theme ? `
-          <meta name="theme-color" media="(prefers-color-scheme: light)" content="${data.theme.light}">
-          <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${data.theme.dark}">
-      ` : `<meta name="theme-color" content="${data.theme}">`}
-    <script type="module" src="/styleguide-assets/fullpage-B7IV3eSt.js"><\/script>
+    ${typeof data.brandColor === "object" && "dark" in data.brandColor && "light" in data.brandColor ? `
+          <meta name="theme-color" media="(prefers-color-scheme: light)" content="${data.brandColor.light}">
+          <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${data.brandColor.dark}">
+      ` : `<meta name="theme-color" content="${data.brandColor}">`}
+    <script type="module" src="/styleguide-assets/fullpage-DSD6-0qF.js"><\/script>
     ${computedStyleTags}
+    ${computedThemeStyleTags}
 </head>
 <body${data.page.bodyclass ? ` class="${data.page.bodyclass}"` : ""}>
     ${data.html}
@@ -1435,6 +1437,7 @@ function getHeaderHtml(config) {
         </button>
 
         <div class="flex gap-4">
+          ${config.previewThemes.length > 0 ? renderGlobalThemeSelect(config.previewThemes) : ""}
           ${config.mode === "development" && config.launchInEditor ? `
               <form class="hidden editor-select md:block">
                 <fieldset class="flex items-center rounded-3xl border border-styleguide-border">
@@ -1612,19 +1615,19 @@ function renderTab(data, aside = "") {
     </div>
   `;
 }
-function renderThemeSelect(section, themes) {
-  const selectId = `theme-select-${sectionSanitizeId(section.id)}`;
+function renderThemeSelectControl(id, themes, scope) {
+  const wrapperClass = scope === "global" ? "hidden md:inline-flex" : "inline-flex";
   return `
-    <div class="inline-flex items-center gap-2 text-sm">
-        <label for="${selectId}" class="select-none">Theme</label>
+    <div class="${wrapperClass} items-center gap-2 text-sm">
+        <label for="${id}" class="select-none">Theme</label>
         <span class="relative inline-flex">
             <select
-                id="${selectId}"
-                class="section-theme-select appearance-none cursor-pointer rounded-md border py-1.5 pl-3 pr-8 text-sm transition duration-200 border-styleguide-border bg-styleguide-bg-highlight hover:text-styleguide-highlight focus:text-styleguide-highlight focus-visible:outline focus-visible:outline-blue-600"
-                data-section-theme-select
+                id="${id}"
+                class="appearance-none cursor-pointer rounded-md border py-1.5 pl-3 pr-8 text-sm transition duration-200 border-styleguide-border bg-styleguide-bg-highlight hover:text-styleguide-highlight focus:text-styleguide-highlight focus-visible:outline focus-visible:outline-blue-600"
+                data-${scope}-theme-select
             >
                 <option value="">Default</option>
-                ${themes.map((theme) => `<option value="${sanitizeSpecialCharacters(themeClassList(theme.value))}">${sanitizeSpecialCharacters(theme.description)}</option>`).join("\n")}
+                ${themes.map((theme) => `<option value="${sanitizeSpecialCharacters(themeClassList(theme.value))}">${sanitizeSpecialCharacters(theme.label)}</option>`).join("\n")}
             </select>
             <svg class="pointer-events-none absolute top-1/2 right-2.5 size-3.5 -translate-y-1/2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
                 <path fill-rule="evenodd" d="M4.22 6.22a.75.75 0 0 1 1.06 0L8 8.94l2.72-2.72a.75.75 0 1 1 1.06 1.06l-3.25 3.25a.75.75 0 0 1-1.06 0L4.22 7.28a.75.75 0 0 1 0-1.06Z" clip-rule="evenodd"/>
@@ -1633,6 +1636,16 @@ function renderThemeSelect(section, themes) {
     </div>
   `;
 }
+function renderGlobalThemeSelect(themes) {
+  return renderThemeSelectControl("global-theme-select", themes, "global");
+}
+function renderThemeSelect(section, themes) {
+  return renderThemeSelectControl(
+    `theme-select-${sectionSanitizeId(section.id)}`,
+    themes.map((theme) => ({ value: theme.value, label: theme.description })),
+    "section"
+  );
+}
 function getMainContentHtml(secondLevelSection, config) {
   let output = "";
   function renderSection(section) {
@@ -2208,7 +2221,7 @@ async function generatePreviewFile(data) {
   const shouldRenderMetaDescription = data.page.description && data.page.description.length > 0 && !(data.page.description.includes("<") && data.page.description.includes(">"));
   const content = `
 <!DOCTYPE html>
-<html lang="${data.page.lang}" class="scroll-smooth">
+<html lang="${data.page.lang}" class="scroll-smooth"${data.reloadPreviewsOnThemeChange ? " data-reload-previews-on-theme-change" : ""}>
 <head>
     <title>${sanitizeSpecialCharacters(data.page.title)}</title>
     ${data.page.description && shouldRenderMetaDescription ? `<meta name="description" content="${data.page.description.replaceAll(`'`, "").replaceAll(`"`, "")}">` : ""}
@@ -2217,10 +2230,10 @@ async function generatePreviewFile(data) {
     <meta name="generator" content="styleguide">
     <link rel="icon" type="image/svg+xml" href="/styleguide-assets/favicon/preview.svg">
     ${data.ogImageUrl ? `<meta property="og:image" content="${data.ogImageUrl}">` : ""}
-    ${typeof data.theme === "object" && "dark" in data.theme && "light" in data.theme ? `
-          <meta name="theme-color" media="(prefers-color-scheme: light)" content="${data.theme.light}">
-          <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${data.theme.dark}">
-      ` : `<meta name="theme-color" content="${data.theme}">`}
+    ${typeof data.brandColor === "object" && "dark" in data.brandColor && "light" in data.brandColor ? `
+          <meta name="theme-color" media="(prefers-color-scheme: light)" content="${data.brandColor.light}">
+          <meta name="theme-color" media="(prefers-color-scheme: dark)" content="${data.brandColor.dark}">
+      ` : `<meta name="theme-color" content="${data.brandColor}">`}
     <link rel="stylesheet" type="text/css" href="/styleguide-assets/kss-modern-Cg1aeKi1.css">
     <script>
   //#region client/lib/iframe-resize.ts
@@ -2384,7 +2397,7 @@ document.addEventListener("DOMContentLoaded", () => {
 //#endregion
 ;
 <\/script>
-    <script type="module" src="/styleguide-assets/preview-CWqxR9nN.js"><\/script>
+    <script type="module" src="/styleguide-assets/preview-CCjPdowU.js"><\/script>
     <link rel="preload" href="/styleguide-assets/fonts/geist-mono-latin-400-normal.woff2" as="font" type="font/woff2" crossorigin="anonymous">
     <link rel="preload" href="/styleguide-assets/fonts/geist-mono-latin-600-normal.woff2" as="font" type="font/woff2" crossorigin="anonymous">
     <link rel="preload" href="/styleguide-assets/fonts/geist-mono-latin-300-normal.woff2" as="font" type="font/woff2" crossorigin="anonymous">
@@ -2394,7 +2407,7 @@ document.addEventListener("DOMContentLoaded", () => {
     ${computedStyleTags}
     <style>
         :root {
-            --styleguide-color-theme-highlight: ${typeof data.theme === "string" ? data.theme : `light-dark(${data.theme.light}, ${data.theme.dark})`};
+            --styleguide-color-theme-highlight: ${typeof data.brandColor === "string" ? data.brandColor : `light-dark(${data.brandColor.light}, ${data.brandColor.dark})`};
         }
     </style>
 </head>
@@ -2584,6 +2597,28 @@ function watchStyleguideForChanges(watchPath, handlers) {
   });
 }
 
+const warnedDeprecations = /* @__PURE__ */ new Set();
+function warnDeprecatedOption(deprecated, replacement) {
+  if (warnedDeprecations.has(deprecated))
+    return;
+  warnedDeprecations.add(deprecated);
+  logger.warn(`\`${deprecated}\` is deprecated and will be removed in the next major \u2014 rename it to \`${replacement}\`.`);
+}
+function resolveConfiguration(config) {
+  const { theme, themes, ...options } = config;
+  if (theme !== void 0)
+    warnDeprecatedOption("theme", "brandColor");
+  if (themes !== void 0)
+    warnDeprecatedOption("themes", "previewThemes");
+  const brandColor = options.brandColor ?? theme;
+  if (brandColor === void 0)
+    throw new Error("Styleguide configuration is missing `brandColor` (the styleguide accent colour).");
+  return {
+    ...options,
+    brandColor,
+    previewThemes: options.previewThemes ?? themes ?? []
+  };
+}
 async function parseStyleguide(contentDir) {
   const styleguideContentPaths = await glob(`${contentDir}/**/*.{css,scss}`);
   const styleguideContent = await Promise.all(
@@ -2654,8 +2689,9 @@ async function writeFullPageFile(config, baseDirectory, section) {
       },
       css: config.html.assets.css,
       js: config.html.assets.js,
+      previewThemes: config.previewThemes,
       html: htmlMarkup,
-      theme: config.theme,
+      brandColor: config.brandColor,
       deactivateDarkMode: config.deactivateDarkMode,
       ogImageUrl: config.plugins?.ogImage ? config.plugins.ogImage(section) : void 0
     });
@@ -2712,8 +2748,9 @@ function writePreviewFile(config, context, firstLevelIndex, secondLevelIndex) {
       alerts: getAlerts(),
       preloadIframes
     },
-    theme: config.theme,
+    brandColor: config.brandColor,
     deactivateDarkMode: config.deactivateDarkMode,
+    reloadPreviewsOnThemeChange: config.reloadPreviewsOnThemeChange,
     ogImageUrl: config.plugins?.ogImage ? config.plugins.ogImage(secondLevelSection) : void 0
   });
 }
@@ -2794,9 +2831,9 @@ async function buildContext(config) {
   };
 }
 const ASSETS_MARKER_FILE = ".kss-modern-assets";
-function getAssetsBuildId(theme) {
+function getAssetsBuildId(brandColor) {
   return `kss-modern-Cg1aeKi1.css
-${JSON.stringify(theme)}
+${JSON.stringify(brandColor)}
 `;
 }
 async function readAssetsBuildId(markerPath) {
@@ -2818,17 +2855,18 @@ async function copyStyleguideAssets(config) {
   const assetsDirectoryPath = findAssetsDirectoryPath();
   const assetsDirectoryOutputPath = path.join(config.outDir, "styleguide-assets");
   const markerPath = path.join(assetsDirectoryOutputPath, ASSETS_MARKER_FILE);
-  const expectedBuildId = getAssetsBuildId(config.theme);
+  const expectedBuildId = getAssetsBuildId(config.brandColor);
   const currentBuildId = await readAssetsBuildId(markerPath);
   if (currentBuildId === expectedBuildId) {
     return;
   }
   await fs.remove(assetsDirectoryOutputPath);
   await fs.copy(assetsDirectoryPath, assetsDirectoryOutputPath);
-  await generateFaviconFiles(assetsDirectoryOutputPath, config.theme);
+  await generateFaviconFiles(assetsDirectoryOutputPath, config.brandColor);
   await fs.writeFile(markerPath, expectedBuildId);
 }
-async function buildAll(config) {
+async function buildAll(input) {
+  const config = resolveConfiguration(input);
   if (config.mode === "production" && await fs.exists(config.outDir)) {
     const files = await glob(`${config.outDir}/**/*.html`);
     await Promise.all(files.map((file) => fs.remove(file)));
@@ -2915,7 +2953,8 @@ async function rebuildSections(config, context, changedSectionIds) {
   }
   await Promise.all(writeTasks);
 }
-async function watchStyleguide(config, onChange, onError) {
+async function watchStyleguide(input, onChange, onError) {
+  const config = resolveConfiguration(input);
   const initialBuild = await buildAll(config);
   if (onError && initialBuild.errors) {
     onError(initialBuild.errors);
@@ -2955,4 +2994,4 @@ async function watchStyleguide(config, onChange, onError) {
   });
 }
 
-export { buildAll, buildStyleguide, logger, parseStyleguide, rebuildSections, watchStyleguide };
+export { buildAll, buildStyleguide, logger, parseStyleguide, rebuildSections, resolveConfiguration, watchStyleguide };

package/dist/styleguide-assets/.vite/manifest.json

@@ -11,12 +11,20 @@
     "file": "code-highlight-Fm7cxf-E.js",
     "name": "code-highlight"
   },
+  "_preview-theme-DIgnwL5g.js": {
+    "file": "preview-theme-DIgnwL5g.js",
+    "name": "preview-theme",
+    "imports": [
+      "_theme-document-CtY2qFyJ.js",
+      "_section-previews-CnlrC8Gz.js"
+    ]
+  },
   "_rolldown-runtime-B1bRi_D7.js": {
     "file": "rolldown-runtime-B1bRi_D7.js",
     "name": "rolldown-runtime"
   },
-  "_section-previews-V4M5aSu6.js": {
-    "file": "section-previews-V4M5aSu6.js",
+  "_section-previews-CnlrC8Gz.js": {
+    "file": "section-previews-CnlrC8Gz.js",
     "name": "section-previews"
   },
   "_shared-hGcWlnRM.js": {
@@ -27,18 +35,23 @@
     "file": "signal-ZVBNTRLw.js",
     "name": "signal"
   },
+  "_theme-document-CtY2qFyJ.js": {
+    "file": "theme-document-CtY2qFyJ.js",
+    "name": "theme-document"
+  },
   "_utils-DtB-AzJa.js": {
     "file": "utils-DtB-AzJa.js",
     "name": "utils"
   },
   "client/fullpage.ts": {
-    "file": "fullpage-B7IV3eSt.js",
+    "file": "fullpage-DSD6-0qF.js",
     "name": "fullpage",
     "src": "client/fullpage.ts",
     "isEntry": true,
     "imports": [
       "_rolldown-runtime-B1bRi_D7.js",
-      "_shared-hGcWlnRM.js"
+      "_shared-hGcWlnRM.js",
+      "_theme-document-CtY2qFyJ.js"
     ],
     "dynamicImports": [
       "node_modules/axe-core/axe.js",
@@ -46,14 +59,14 @@
     ]
   },
   "client/lib/a11y-report.ts": {
-    "file": "a11y-report-DJQyYaLp.js",
+    "file": "a11y-report-BFnWMaWr.js",
     "name": "a11y-report",
     "src": "client/lib/a11y-report.ts",
     "isDynamicEntry": true,
     "imports": [
       "_utils-DtB-AzJa.js",
       "_audit-runner-Ch009v98.js",
-      "_section-previews-V4M5aSu6.js"
+      "_section-previews-CnlrC8Gz.js"
     ]
   },
   "client/lib/clipboard.ts": {
@@ -73,8 +86,17 @@
     "src": "client/lib/editor-select.ts",
     "isDynamicEntry": true
   },
+  "client/lib/global-theme-select.ts": {
+    "file": "global-theme-select-DCnqGEUr.js",
+    "name": "global-theme-select",
+    "src": "client/lib/global-theme-select.ts",
+    "isDynamicEntry": true,
+    "imports": [
+      "_preview-theme-DIgnwL5g.js"
+    ]
+  },
   "client/lib/html-validator.ts": {
-    "file": "html-validator-Cp2OkhS9.js",
+    "file": "html-validator-sgeZtEeH.js",
     "name": "html-validator",
     "src": "client/lib/html-validator.ts",
     "isDynamicEntry": true,
@@ -83,7 +105,7 @@
       "_utils-DtB-AzJa.js",
       "_shared-hGcWlnRM.js",
       "_audit-runner-Ch009v98.js",
-      "_section-previews-V4M5aSu6.js"
+      "_section-previews-CnlrC8Gz.js"
     ]
   },
   "client/lib/icons.ts": {
@@ -97,12 +119,13 @@
     ]
   },
   "client/lib/section-theme-select.ts": {
-    "file": "section-theme-select-ygaSXIuK.js",
+    "file": "section-theme-select-CVOwp7VZ.js",
     "name": "section-theme-select",
     "src": "client/lib/section-theme-select.ts",
     "isDynamicEntry": true,
     "imports": [
-      "_section-previews-V4M5aSu6.js"
+      "_section-previews-CnlrC8Gz.js",
+      "_preview-theme-DIgnwL5g.js"
     ]
   },
   "client/preview-inline.ts": {
@@ -112,7 +135,7 @@
     "isEntry": true
   },
   "client/preview.ts": {
-    "file": "preview-CWqxR9nN.js",
+    "file": "preview-CCjPdowU.js",
     "name": "preview",
     "src": "client/preview.ts",
     "isEntry": true,
@@ -128,6 +151,7 @@
       "client/lib/html-validator.ts",
       "client/lib/icons.ts",
       "client/lib/clipboard.ts",
+      "client/lib/global-theme-select.ts",
       "client/lib/section-theme-select.ts",
       "client/lib/editor-select.ts"
     ]

package/dist/styleguide-assets/{a11y-report-DJQyYaLp.js → a11y-report-BFnWMaWr.js}

@@ -1,6 +1,6 @@
 import { r as e } from "./utils-DtB-AzJa.js";
 import { a as t, i as n, n as r, o as i, r as a } from "./audit-runner-Ch009v98.js";
-import { n as o, t as s } from "./section-previews-V4M5aSu6.js";
+import { n as o, r as s } from "./section-previews-CnlrC8Gz.js";
 //#region client/lib/a11y-report.ts
 var c = {
 	violations: ["violations", "incomplete"],
@@ -10,8 +10,8 @@ function l(t) {
 	return e(t.trim()).replace(/^section-/, "");
 }
 function u() {
-	return Array.from(document.querySelectorAll(s)).flatMap((e) => {
-		let { base: t, modifiers: n } = o(e);
+	return Array.from(document.querySelectorAll(o)).flatMap((e) => {
+		let { base: t, modifiers: n } = s(e);
 		if (!t) return [];
 		let r = Number.parseInt(e.dataset.sourceLine ?? "", 10);
 		return [{