varvara-typedoc-theme 0.1.2 → 0.2.0

package/README.md

@@ -1,15 +1,16 @@
 # Varvara TypeDoc Theme
 
-Varvara TypeDoc Theme is a [custom theme](https://typedoc.org/documents/Development.Custom_Themes.html) for TypeDoc, designed to provide an seamless documentation experience for TypeScript projects.
+_View a_ [_live example here_](https://marcmarine.github.io/western-signs).
 
-[![license](https://img.shields.io/github/license/marcmarine/varvara-js)](https://github.com/marcmarine/varvara-js/blob/main/LICENSE)
+Varvara TypeDoc Theme is a custom theme for TypeDoc, designed to provide a seamless documentation experience for TypeScript projects.
 
-## Prerequisites
-
-Ensure TypeDoc is [installed](https://typedoc.org/index.html#quick-start) in your project.
+[![NPM Version](https://img.shields.io/npm/v/varvara-typedoc-theme)](https://www.npmjs.com/package/varvara-typedoc-theme)
+[![GitHub License](https://img.shields.io/github/license/marcmarine/varvara-js)](https://github.com/marcmarine/varvara-js/blob/main/LICENSE)
 
 ## Installation
 
+Ensure TypeDoc is [installed](https://typedoc.org/index.html#quick-start) in your project.
+
 Install the Varvara TypeDoc theme as a development dependency:
 
 ```bash
@@ -55,6 +56,53 @@ export default config
 > [!IMPORTANT]
 > The theme must be explicitly specified. If not set, the plugin will not be loaded by default.
 
+### Customization
+
+Add custom styling by specifying an extra CSS file using the [customCss](https://typedoc.org/documents/Options.Output.html#customcss) option:
+
+```bash
+npx typedoc --customCss ./styles/custom.css
+```
+
+Varvara CSS provides variables to customize the theme appearance:
+
+```css
+/* custom.css */
+
+@media (prefers-color-scheme: light) {
+  :root {
+    --va-color-foreground: DimGray;
+    --va-color-background: WhiteSmoke;
+    --va-border-color: Gainsboro;
+    --va-space-ratio: 0.5;
+  }
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --va-color-foreground: Silver;
+    --va-color-background: MidnightBlue;
+    --va-border-color: RoyalBlue;
+    --va-space-ratio: 0.5;
+  }
+}
+
+[data-theme='light'] {
+  --va-color-foreground: DimGray;
+  --va-color-background: WhiteSmoke;
+  --va-border-color: Gainsboro;
+  --va-space-ratio: 0.5;
+}
+
+[data-theme='dark'] {
+  --va-color-foreground: Silver;
+  --va-color-background: MidnightBlue;
+  --va-border-color: RoyalBlue;
+  --va-space-ratio: 0.5;
+}
+```
+
+See the [documentation](https://varvara.js.org/variables) for the complete list of available properties.
+
 ## Contributing
 
 Feel free to explore, test, and provide feedback. Your contribution is highly appreciated as we work towards improving and stabilizing the project.

package/assets/overrides.css

@@ -1,22 +1,9 @@
-:root {
-  --va-collapse-tree-indentation: var(--va-space-4);
-}
-
-html[data-theme='light'] {
-  --va-color-foreground: #29353d;
-  --va-color-background: #f3f5f7;
-  --va-border-color: lightgray;
-}
-html[data-theme='dark'] {
-  --va-color-foreground: #b3ccd6;
-  --va-color-background: #2a303c;
-}
-
 @media (prefers-color-scheme: light) {
   :root {
     --va-color-foreground: #29353d;
     --va-color-background: #f3f5f7;
-    --va-border-color: lightgray;
+    --va-border-color: LightGray;
+    --va-color-primary: RoyalBlue;
   }
 }
 
@@ -24,14 +11,34 @@ html[data-theme='dark'] {
   :root {
     --va-color-foreground: #b3ccd6;
     --va-color-background: #2a303c;
+    --va-border-color: LightSlateGray;
+    --va-color-primary: LightSkyBlue;
   }
 }
 
+[data-theme='light'] {
+  --va-color-foreground: #29353d;
+  --va-color-background: #f3f5f7;
+  --va-border-color: LightGray;
+  --va-color-primary: RoyalBlue;
+}
+
+[data-theme='dark'] {
+  --va-color-foreground: #b3ccd6;
+  --va-color-background: #2a303c;
+  --va-border-color: LightSlateGray;
+  --va-color-primary: LightSkyBlue;
+}
+
 body {
   background-color: var(--va-color-background);
   color: var(--va-color-foreground);
 }
 
+a {
+  color: var(--va-color-primary);
+}
+
 .va-button:has(.version-badge) {
   position: relative;
 }
@@ -162,7 +169,7 @@ footer {
 }
 
 .container {
-  padding: 0 1.5rem;
+  padding: 0 var(--va-space-8);
 }
 
 @media (max-width: 769px) {
@@ -187,9 +194,10 @@ footer {
   .container-main {
     grid-template-areas: 'header content' 'sidebar content';
     grid-auto-rows: auto 1fr;
+    margin: var(--va-space-8) 0;
   }
   .container {
-    padding: 0 2rem;
+    padding: 0 var(--va-space-8);
   }
 }
 
@@ -202,8 +210,8 @@ footer {
   }
   .page-menu,
   .site-menu {
-    top: 2rem;
-    max-height: calc(100vh - 4rem);
+    top: var(--va-space-8);
+    max-height: calc(100vh - calc(var(--va-space-8) * 2));
   }
 }
 

package/dist/index.js

@@ -89,21 +89,28 @@ function sidebar(context) {
   };
 }
 
-// src/partials/pageSidebar.tsx
+// src/partials/navigation.tsx
 import {
   JSX as JSX3,
   ReflectionFlag
 } from "typedoc";
 function pageSidebar(context) {
   return (props) => {
+    return /* @__PURE__ */ JSX3.createElement("div", {
+      class: "va-button-group"
+    }, context.settings(), context.pageNavigation(props));
+  };
+}
+var flagOptionNameToReflectionFlag = {
+  protected: ReflectionFlag.Protected,
+  private: ReflectionFlag.Private,
+  external: ReflectionFlag.External,
+  inherited: ReflectionFlag.Inherited
+};
+function settings(context) {
+  return () => {
     const defaultFilters = context.options.getValue("visibilityFilters");
     const visibilityOptions = [];
-    const flagOptionNameToReflectionFlag = {
-      protected: ReflectionFlag.Protected,
-      private: ReflectionFlag.Private,
-      external: ReflectionFlag.External,
-      inherited: ReflectionFlag.Inherited
-    };
     for (const key of Object.keys(defaultFilters)) {
       if (key.startsWith("@")) {
         const filterName = key.substring(1).replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
@@ -112,25 +119,7 @@ function pageSidebar(context) {
         visibilityOptions.push(buildFilterItem(context, key, context.internationalization.flagString(flagOptionNameToReflectionFlag[key]), defaultFilters[key]));
       }
     }
-    if (!props.pageSections.some((sect) => sect.headings.length)) {
-      return /* @__PURE__ */ JSX3.createElement(JSX3.Fragment, null);
-    }
-    const sections = [];
-    for (const section of props.pageSections) {
-      if (section.title) {
-        sections.push(/* @__PURE__ */ JSX3.createElement("details", {
-          open: true,
-          class: "va-collapse tsd-accordion"
-        }, /* @__PURE__ */ JSX3.createElement("summary", {
-          "data-key": `section-${section.title}`
-        }, section.title), buildSectionNavigation(context, section.headings)));
-      } else {
-        sections.push(buildSectionNavigation(context, section.headings));
-      }
-    }
-    return /* @__PURE__ */ JSX3.createElement("div", {
-      class: "va-button-group"
-    }, /* @__PURE__ */ JSX3.createElement("details", {
+    return /* @__PURE__ */ JSX3.createElement("details", {
       class: "va-collapse settings tsd-accordion",
       open: false
     }, /* @__PURE__ */ JSX3.createElement("summary", null, context.i18n.theme_settings()), visibilityOptions.length && /* @__PURE__ */ JSX3.createElement("div", {
@@ -150,10 +139,7 @@ function pageSidebar(context) {
       value: "light"
     }, context.i18n.theme_light()), /* @__PURE__ */ JSX3.createElement("option", {
       value: "dark"
-    }, context.i18n.theme_dark())))), /* @__PURE__ */ JSX3.createElement("details", {
-      open: false,
-      class: "va-collapse page-navigation tsd-accordion"
-    }, /* @__PURE__ */ JSX3.createElement("summary", null, context.i18n.theme_on_this_page()), sections));
+    }, context.i18n.theme_dark()))));
   };
 }
 function buildSectionNavigation(context, headings) {
@@ -201,6 +187,30 @@ function buildFilterItem(context, name, displayName, defaultValue) {
     checked: defaultValue
   }), context.icons.checkbox(), /* @__PURE__ */ JSX3.createElement("span", null, displayName)));
 }
+function pageNavigation(context) {
+  return (props) => {
+    if (!props.pageSections.some((sect) => sect.headings.length)) {
+      return /* @__PURE__ */ JSX3.createElement(JSX3.Fragment, null);
+    }
+    const sections = [];
+    for (const section of props.pageSections) {
+      if (section.title) {
+        sections.push(/* @__PURE__ */ JSX3.createElement("details", {
+          open: true,
+          class: "va-collapse tsd-accordion"
+        }, /* @__PURE__ */ JSX3.createElement("summary", {
+          "data-key": `section-${section.title}`
+        }, section.title), buildSectionNavigation(context, section.headings)));
+      } else {
+        sections.push(buildSectionNavigation(context, section.headings));
+      }
+    }
+    return /* @__PURE__ */ JSX3.createElement("details", {
+      open: false,
+      class: "va-collapse page-navigation tsd-accordion"
+    }, /* @__PURE__ */ JSX3.createElement("summary", null, context.i18n.theme_on_this_page()), sections);
+  };
+}
 
 // src/partials/toolbar.tsx
 import {
@@ -332,15 +342,9 @@ function layout(context) {
   }), /* @__PURE__ */ JSX5.createElement("link", {
     rel: "stylesheet",
     href: context.relativeURL("assets/highlight.css", true)
-  }), context.options.getValue("customCss") && /* @__PURE__ */ JSX5.createElement("link", {
-    rel: "stylesheet",
-    href: context.relativeURL("assets/custom.css", true)
   }), /* @__PURE__ */ JSX5.createElement("script", {
     defer: true,
     src: context.relativeURL("assets/main.js", true)
-  }), context.options.getValue("customJs") && /* @__PURE__ */ JSX5.createElement("script", {
-    defer: true,
-    src: context.relativeURL("assets/custom.js", true)
   }), /* @__PURE__ */ JSX5.createElement("script", {
     async: true,
     src: context.relativeURL("assets/icons.js", true),
@@ -357,7 +361,13 @@ function layout(context) {
     async: true,
     src: context.relativeURL("assets/hierarchy.js", true),
     id: "tsd-hierarchy-script"
-  }), context.hook("head.end", context)), /* @__PURE__ */ JSX5.createElement("body", null, context.hook("body.begin", context), /* @__PURE__ */ JSX5.createElement("script", null, /* @__PURE__ */ JSX5.createElement(JSX5.Raw, {
+  }), context.hook("head.end", context), context.options.getValue("customCss") && /* @__PURE__ */ JSX5.createElement("link", {
+    rel: "stylesheet",
+    href: context.relativeURL("assets/custom.css", true)
+  }), context.options.getValue("customJs") && /* @__PURE__ */ JSX5.createElement("script", {
+    defer: true,
+    src: context.relativeURL("assets/custom.js", true)
+  })), /* @__PURE__ */ JSX5.createElement("body", null, context.hook("body.begin", context), /* @__PURE__ */ JSX5.createElement("script", null, /* @__PURE__ */ JSX5.createElement(JSX5.Raw, {
     html: 'document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";'
   })), /* @__PURE__ */ JSX5.createElement("div", {
     class: "container container-main"
@@ -428,6 +438,8 @@ class VarvaraThemeContext extends DefaultThemeRenderContext3 {
     this.toolbar = toolbar(this);
     this.defaultLayout = layout(this);
     this.sidebar = sidebar(this);
+    this.settings = settings(this);
+    this.pageNavigation = pageNavigation(this);
   }
   footer = () => footer(this);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "varvara-typedoc-theme",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "author": "Marc Mariné <shenobi@gmail.com>",
   "repository": {
     "type": "git",