Merge: CSS bundling and new themes (PR #2291)

.gitignore

@@ -16,3 +16,4 @@ examples/webwork/minimal/generated/*
 **/cli.log
 **/rsbuild
 **/build
+**/node_modules/

css/README.md

@@ -0,0 +1,69 @@
+# Notes on CSS structure and development
+
+PreTeXt books expect to use a `theme.css` file for its styling. SCSS is used to build that CSS file.
+
+A few themes (the default-modern one and legacy ones that predate SCSS overhaul) are provided "prerolled" in `css/dist`. These can be used without rebuilding from SCSS and even gently modified via the appending of CSS `variables` to customize things like `primary-color`.
+
+Other themes, or using `options` to more substantially change a "prerolled" theme, require that the theme is rebuilt.
+
+## Building
+
+If a book's theme requires building, the pretext script or CLI should handle all of the build details. If you are using the CLI, it should handle installing the build tools as well. If you are using the pretext script, you will need to [install Node and the build script dependencies manually](../script/cssbuilder/README.md#installing-node-and-dependencies)
+
+For more advanced use, including rebuilding themes by hand, see the [CSS Builder script README](../script/cssbuilder/README.md)
+
+### Installing NPM
+
+You will need to [install node](https://nodejs.org/en/download/package-manager).
+
+Install the needed dependencies by switching to the `pretext/script/cssbuilder` and doing `npm install`.
+
+Run `npm run build` to build all the default targets to the output directory (default is `pretext/css/dist`). You can change the directory the build product is produced into with `-o PATH`. If using a relative path, make sure to specify it from the `cssbuilder` folder.
+
+## Folders
+
+### colors
+
+Color palettes that ideally can be used across multiple themes, though it is not expected every palette will be available in every theme. These are all designed to produce a variable `$colors` containing a map of variable definitions. The theme is responsible for turning that map into CSS variables via the `scss-to-css` function.
+
+If a shared palette needs slight modifications by a given theme, the theme can simply override the individual variables (or add new ones). See the comment in `theme-default-modern` for an example.
+
+### components
+
+Shared files that are (or are expected to be) used across many **targets**.
+
+Some of these files are in need of refactoring and modularization.
+
+See README.md in subfolders of `components/` for tips on organization of subcomponents.
+
+### dist
+
+Built CSS ready for inclusion by pretext.
+
+Files in the directory **should not be modified by hand**. The CSS build script in `script/cssbuilder` will produce these files from the items in the `targets` directory.
+
+### fonts
+
+Mechanisms for selection of fonts by a theme
+
+### legacy
+
+Files only used by legacy (pre scss) styles
+
+### targets
+
+Root targets that produce a CSS file. Anything that represents a self-contained final product belongs here.
+
+Any files that are designed only to be used in one target also belong here, grouped with the target they belong to. For example, if `foo.scss` is only intended to be used by the `reveal` target, that file should be placed in the `revealjs` folder.
+
+### other
+
+CSS that is not a part of producing PreTeXt volumes and is not bundled into any target in `dist/` e.g. CSS related to the PreTeXt catalog.
+
+## File "ownership", @use, and copy/paste
+
+Files in the `target` folder are considered "owned" by the folder they are in. When making changes to those files you are encouraged to think about other targets in the same "family" that may @use the files, but are not expected to go out of your way to fix issues in those other targets that result from the changes.
+
+Files in `components` are "shared". Changes to them should consider (and test) all targets that @use the component.
+
+There is a balancing act between the complexity of the include tree for targets and avoiding duplication of effort. Avoid coping/pasting large numbers of rules from one target to another. If you want to reuse some of the rules from another target, consider factoring out those rules into a `component` that the old file and your new one can both @use. But doing so to reuse a small number of CSS rules likely creates more complexity than simply duplicating those rules in your target.

css/colors/_color-helpers.scss

@@ -0,0 +1,77 @@
+// This file contains functions and mixins for working with colors in SCSS
+
+@use "sass:map";
+
+@mixin set-root-colors($colors, $dark-colors: null) {
+  :root {
+    color-scheme: light;
+    // prevent variable leak through to dark
+    &:not(.dark-mode) {
+      @include scss-to-css($colors);
+    }
+  }
+
+  @if $dark-colors {
+    :root.dark-mode {
+      color-scheme: dark;
+      @include scss-to-css($dark-colors);
+    }
+  }
+}
+
+// Renders a map of SCSS variables as CSS variables
+@mixin scss-to-css($colors) {
+  @each $name, $value in $colors {
+    --#{$name}: #{$value};
+  }
+}
+
+// Create a map of colors that blend $color with $other at $mix-amounts
+// The resulting map will have keys of the form 'color-other-10'
+// Indicating 10% of other mixed into color
+@function mixes($color, $other, $mix-amounts) {
+  $result: ();
+
+  @each $i in $mix-amounts {
+    $result: map.set($result, '#{$color}-#{$other}-#{$i}', 'color-mix(in oklab, var(--#{$color}), #{$other} #{$i}%)');
+  }
+
+  @return $result;
+}
+
+$std-mixes: (1, 2, 3, 4, 5, 10, 15, 20, 25, 30, 35, 40, 50, 60, 65, 70, 75, 80, 85, 90, 95, 96, 97, 98, 99);
+
+// Creates a map of color blends for a given color
+// By default it creates blends with black, white, and gray at $std-mixes amounts
+// Mixing is done using css color-mix function so that if a theme file has the base
+// css variable overridden, the blends will be updated accordingly
+@function get-blends($color, $shades: $std-mixes, $tints: $std-mixes, $tones: $std-mixes, ) {
+  $shades: mixes($color, black, $std-mixes);
+  $tints: mixes($color, white, $std-mixes);
+  $tones: mixes($color, gray, $std-mixes);
+
+  $blends: map.merge(
+    $tints,
+    $shades
+  );
+
+  $blends: map.merge(
+    $blends,
+    $tones
+  );
+  @return $blends;
+}
+
+//--------------------------------------------------------------------------
+// https://jonnykates.medium.com/automating-colour-contrast-ratios-with-sass-e201f3b52797
+
+@function text-contrast($color, $light: #ffffff, $dark: #000000) {
+  $color-brightness: round((red($color) * 299) + (green($color) * 587) + (blue($color) * 114) / 1000);
+  $light-color: round((red(#ffffff) * 299) + (green(#ffffff) * 587) + (blue(#ffffff) * 114) / 1000);
+  @if abs($color-brightness) < calc($light-color / 2){
+    @return $light;
+  } @else {
+    @return $dark;
+  }
+}
+//--------------------------------------------------------------------------

css/colors/_color-vars.scss

@@ -0,0 +1,156 @@
+/*
+  Master list of color variables and default values.
+  Variables are defined in SCSS to allow for calculation of values. They are
+  then converted to CSS variables for use in the HTML so authors can, if
+  need be, override them with custom CSS.
+
+  Any new variable should be added to this file and either defined to another
+  variable or given a reasonable default value for the red-blue default theme.
+
+  Variables should be semantic, not descriptive
+  i.e. --link-color, not --pretty-blue
+*/
+
+@use "sass:map";
+
+// ==============================================================================
+// Light theme
+
+// ==============================================================================
+// Page structures
+
+$colors: (
+  // Background of page (gutters if any)
+  "page-color": white,
+  // Background of content area
+  "content-background": white,
+  // Border around content area - also possibly used for internal borders
+  "page-border-color": #ccc,
+
+  // ------------------------------------------------------------------------------
+  // Banner/nav related
+
+  "doc-title-color": #932919,
+  "byline-color": #333,
+  "banner-background": #fafafa,
+  "navbar-background": #ededed,
+  "footer-background": var(--banner-background),
+
+  // ------------------------------------------------------------------------------
+  // TOC related
+
+  "toc-border-color": #666,
+  "toc-background": var(--content-background),
+
+  "tocitem-background": var(--toc-background),
+  "toc-text-color": var(--body-text-color),
+
+  // highlight styles are used for hover
+  "tocitem-highlight-background": #671d12,
+  "tocitem-highlight-text-color": white,
+  "tocitem-highlight-border-color": var(--toc-border-color),
+
+  // active styles are used for the current toc item
+  "tocitem-active-background": #671d12,
+  "tocitem-active-text-color": white,
+  "tocitem-active-border-color": var(--toc-border-color),
+
+  // level based colors for TOC
+  // levels are not necessarily all used
+  // see the toc-basics.scss for how these are determined
+  "toclevel1-background": var(--content-background),
+  "toclevel1-text-color": var(--toc-text-color),
+  "toclevel2-background": var(--content-background),
+  "toclevel2-text-color": var(--toc-text-color),
+  "toclevel3-background": var(--content-background),
+  "toclevel3-text-color": var(--toc-text-color),
+
+
+  // ==============================================================================
+  // Content
+  // ==============================================================================
+
+  // ------------------------------------------------------------------------------
+  // Text & titles
+
+  "body-text-color": #000,
+  "body-title-color": #000,
+
+  "ptx-image-bg": transparent,
+  "activated-content-bg": rgba(241, 185, 255, 30%),
+
+  "summary-link-background": var(--button-background),
+  "summary-link-text-color": var(--button-text-color),
+  "summary-link-hover-background": var(--button-hover-background),
+  "summary-link-hover-text-color": var(--button-hover-text-color),
+
+  // ------------------------------------------------------------------------------
+  // Links & knowls
+
+  "link-text-color": #2B5F82,
+  "link-background": transparent,
+  "link-active-text-color": var(--link-text-color),
+  "link-active-background": #cad2e1,
+
+  "link-alt-text-color": #A62E1C,
+  "link-alt-background": transparent,
+  "link-alt-active-text-color": var(--link-alt-text-color),
+  "link-alt-active-background": #e3d1ce,
+
+  "knowl-link-color": var(--link-text-color),
+  "knowl-background": #f5f8ff,
+  "knowl-border-color": #e0e9ff,
+  "knowl-nested-1-background": #f5f5ff,
+  "knowl-nested-2-background": #fffff5,
+  "knowl-nested-3-background": #f5ffff,
+  "knowl-nested-4-background": #fff5f5,
+
+  // ------------------------------------------------------------------------------
+  // Blocks
+
+  // Fall back generic block colors:
+  "block-body-background": var(--content-background),
+  "block-border-color": var(--knowl-border-color),
+  "block-head-color": var(--body-text-color),
+
+  // See below for specific block types
+
+  // ------------------------------------------------------------------------------
+  // Buttons & Widgets
+
+  "button-background": #ededed,
+  "button-text-color": #333333,
+  "button-border-color": #ccc,
+  "button-hover-background": #c7c7c7,
+  "button-hover-text-color": var(--button-text-color),
+  "code-inline": #ededed,
+
+  "dropdown-background": var(--content-background),
+  "dropdown-border-color": var(--toc-border-color),
+  "dropdown-text-color": var(--toc-text-color),
+  "dropdown-hover-background": var(--tocitem-active-background),
+  "dropdown-hover-text-color": var(--tocitem-active-text-color),
+);
+
+// ==============================================================================
+// Block types
+
+// Variables for specific block types should look like those below. In this file
+// only "top level" blocks from the -like families are defined. 
+// Other themes/color palettes may define
+// more specific ones - see palette_quad_chunks.scss for an example.
+
+// block-types based on those in entities.ent
+$block-types: "assemblage-like", "definition-like", "theorem-like", "theorem-like", "axiom-like", "remark-like", "computation-like", "openproblem-like", "aside-like", "proof-like", "example-like", "project-like", "goal-like", "solution-like";
+// TODO - "proof" should probably be updated to "proof-like" in HTML css
+
+@each $block in $block-types {
+  $colors: map.merge(
+    $colors,
+    (
+      // define background and border, but default to generic block colors
+      "#{$block}-body-background": var(--block-body-background),
+      "#{$block}-border-color": var(--block-border-color),
+    )
+  );
+}