@docpensieve/components 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/components",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "DocPensieve global MDX components, usable without import: Card, Columns, Tooltip, Tree, Skill, TimeTimer, LogoIcon, ScrollToTop",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/shared": "0.1.3"
+    "@docpensieve/shared": "0.1.5"
   },
   "peerDependencies": {
     "react": "^19"

package/src/classes.js

@@ -35,6 +35,26 @@ export function getThemeClasses() {
   return themeClasses;
 }
 
+/**
+ * Framework of the active theme, announced alongside the class table. Empty
+ * until then.
+ */
+let themeFramework = '';
+
+/**
+ * Declares the framework of the active theme, which `ForTheme` reads.
+ *
+ * @param {string} [framework]
+ */
+export function setThemeFramework(framework = '') {
+  themeFramework = framework;
+}
+
+/** @returns {string} The active framework, or `''` when none was announced. */
+export function getThemeFramework() {
+  return themeFramework;
+}
+
 /**
  * Converts a slot name into a fallback class.
  *

package/src/for-theme.js

@@ -0,0 +1,45 @@
+/**
+ * Content kept for one theme only.
+ *
+ * A page that shows how to style a component cannot say the same thing to
+ * every site: with the utility theme, the look comes from its classes; with
+ * the custom theme, from classes the project writes itself. `ForTheme` keeps
+ * each variant for the site whose theme matches, at build time — the other
+ * one does not even reach the HTML. Changing the theme in the configuration
+ * therefore changes what the pages show, without editing them.
+ *
+ * @module @docpensieve/components/for-theme
+ */
+
+import { Fragment, createElement as h } from 'react';
+
+import { DocPensieveError, THEME_FRAMEWORKS } from '@docpensieve/shared';
+
+import { getThemeFramework } from './classes.js';
+
+/**
+ * Renders its children only when the site's theme is `framework`.
+ *
+ * @param {{ framework?: string, children?: any }} props
+ * @returns {any}
+ * @throws {DocPensieveError} For a framework the configuration does not know,
+ *   or when no theme was announced.
+ */
+export function ForTheme({ framework, children }) {
+  if (!framework || !THEME_FRAMEWORKS.includes(framework)) {
+    throw new DocPensieveError(`<ForTheme> does not know the framework "${framework ?? ''}".`, {
+      hint: `framework expects one of: ${THEME_FRAMEWORKS.join(', ')}.`,
+    });
+  }
+
+  // Rendering nothing here would drop every variant: a page emptied without
+  // a word.
+  const active = getThemeFramework();
+  if (!active) {
+    throw new DocPensieveError('<ForTheme> was rendered before any theme was announced.', {
+      hint: 'The generator announces the theme with setThemeFramework() before rendering.',
+    });
+  }
+
+  return active === framework ? h(Fragment, null, children) : null;
+}

package/src/index.js

@@ -9,7 +9,15 @@
  * @module @docpensieve/components
  */
 
-export { classNames, cls, fallbackClass, getThemeClasses, setThemeClasses } from './classes.js';
+export {
+  classNames,
+  cls,
+  fallbackClass,
+  getThemeClasses,
+  getThemeFramework,
+  setThemeClasses,
+  setThemeFramework,
+} from './classes.js';
 export { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
 export { Column, Columns } from './columns.js';
 export { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
@@ -18,6 +26,7 @@ export { Tree, TreeItem } from './tree.js';
 export { ScrollToTop } from './scroll-to-top.js';
 export { SKILL_SHAPES, Skill } from './skill.js';
 export { LogoIcon } from './logo-icon.js';
+export { ForTheme } from './for-theme.js';
 export { componentsCss } from './styles.js';
 export { getSiteContext, resolveFile, resolveUrl, setSiteContext } from './site.js';
 export { builtinComponents, createRegistry, listComponentNames } from './registry.js';

package/src/registry.js

@@ -9,6 +9,7 @@
 
 import { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
 import { Column, Columns } from './columns.js';
+import { ForTheme } from './for-theme.js';
 import { LogoIcon } from './logo-icon.js';
 import { ScrollToTop } from './scroll-to-top.js';
 import { Skill } from './skill.js';
@@ -37,6 +38,7 @@ export const builtinComponents = {
   ScrollToTop,
   Skill,
   LogoIcon,
+  ForTheme,
 };
 
 /**

package/types/classes.d.ts

@@ -17,6 +17,14 @@
 export declare function setThemeClasses(classes?: Record<string, string>): void;
 /** @returns {Record<string, string>} The current table, for inspection. */
 export declare function getThemeClasses(): Record<string, string>;
+/**
+ * Declares the framework of the active theme, which `ForTheme` reads.
+ *
+ * @param {string} [framework]
+ */
+export declare function setThemeFramework(framework?: string): void;
+/** @returns {string} The active framework, or `''` when none was announced. */
+export declare function getThemeFramework(): string;
 /**
  * Converts a slot name into a fallback class.
  *

package/types/for-theme.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Content kept for one theme only.
+ *
+ * A page that shows how to style a component cannot say the same thing to
+ * every site: with the utility theme, the look comes from its classes; with
+ * the custom theme, from classes the project writes itself. `ForTheme` keeps
+ * each variant for the site whose theme matches, at build time — the other
+ * one does not even reach the HTML. Changing the theme in the configuration
+ * therefore changes what the pages show, without editing them.
+ *
+ * @module @docpensieve/components/for-theme
+ */
+/**
+ * Renders its children only when the site's theme is `framework`.
+ *
+ * @param {{ framework?: string, children?: any }} props
+ * @returns {any}
+ * @throws {DocPensieveError} For a framework the configuration does not know,
+ *   or when no theme was announced.
+ */
+export declare function ForTheme({ framework, children }: {
+    framework?: string;
+    children?: any;
+}): any;

package/types/index.d.ts

@@ -8,7 +8,7 @@
  *
  * @module @docpensieve/components
  */
-export { classNames, cls, fallbackClass, getThemeClasses, setThemeClasses } from './classes.js';
+export { classNames, cls, fallbackClass, getThemeClasses, getThemeFramework, setThemeClasses, setThemeFramework, } from './classes.js';
 export { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
 export { Column, Columns } from './columns.js';
 export { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
@@ -17,6 +17,7 @@ export { Tree, TreeItem } from './tree.js';
 export { ScrollToTop } from './scroll-to-top.js';
 export { SKILL_SHAPES, Skill } from './skill.js';
 export { LogoIcon } from './logo-icon.js';
+export { ForTheme } from './for-theme.js';
 export { componentsCss } from './styles.js';
 export { getSiteContext, resolveFile, resolveUrl, setSiteContext } from './site.js';
 export { builtinComponents, createRegistry, listComponentNames } from './registry.js';