[wip] implementation [skip netlify]

.eslintignore

···
-site/static/js/theme.js
+site/static/js/preferences.js

.gitignore

···
 public
 .DS_Store
 
-site/assets/js/theme.js
-site/_assets/js/theme.js
+site/assets/js/*
+site/_assets/js/*
 site/_includes/styles/*.css
 site/_includes/_styles/*.css
 site/styles/*.css

scripts/ColorScheme.svelte

···
+<script>
+   import { stringIsTheme, Theme } from './preferences'
+   import { assert } from './utils'
+
+   const themes = [Theme.System, Theme.Light, Theme.Dark] as const
+
+   const descriptions: Record<Theme, string> = {
+      system: 'match <abbr title="operating system">OS</abbr>',
+      light: 'light',
+      dark: 'dark',
+   }
+
+   function selectTheme(event: Event) {
+      assert(event.target instanceof HTMLInputElement, 'badly configured theme chooser')
+      assert(stringIsTheme(event.target.value), 'badly configured theme component')
+
+      onSelectTheme(event.target.value)
+   }
+
+   export let selectedTheme: Theme
+   export let onSelectTheme: (newTheme: Theme) => void
+</script>
+
+<fieldset>
+   <legend>Color scheme</legend>
+
+   {#each themes as theme}
+      <label for={theme}>{@html descriptions[theme]}</label>
+      <input
+         type="radio"
+         name="theme"
+         id={theme}
+         value={theme}
+         on:input={selectTheme}
+         checked={theme === selectedTheme}
+      />
+   {/each}
+</fieldset>

scripts/Icons/Adjust.svelte

···
+<svg
+   viewBox="0 0 15 15"
+   fill="none"
+   xmlns="http://www.w3.org/2000/svg"
+   width="15"
+   height="15"
+>
+   <path
+      d="M2.5 7.5H0m15 5h-2.5m2.5-10H8.5m-2 0H0m4.5 5H15m-4.5 5H0m10.5-2v4h2v-4h-2zm-8-5v4h2v-4h-2zm4-5v4h2v-4h-2z"
+      stroke="currentColor"
+   />
+</svg>

scripts/Icons/Close.svelte

···
+<svg
+   viewBox="0 0 15 15"
+   fill="none"
+   xmlns="http://www.w3.org/2000/svg"
+   width="15"
+   height="15"
+>
+   <path d="M1.5 1.5l12 12m-12 0l12-12" stroke="currentColor" />
+</svg>

scripts/Preferences.svelte

···
+<script>
+   import ColorScheme from './ColorScheme.svelte'
+   import Adjust from './Icons/Adjust.svelte'
+   import Close from './Icons/Close.svelte'
+   import ReadingMode from './ReadingMode.svelte'
+
+   import {
+      Theme,
+      loadPreferences,
+      persistTheme,
+      persistReadingMode,
+   } from './preferences'
+
+   let showPreferences = false
+   let { theme = Theme.System, readingMode = false } = loadPreferences()
+
+   // At initialization, make sure the initial values are set correctly.
+   persistTheme(theme)
+   persistReadingMode(readingMode)
+
+   const updateTheme = (newTheme: Theme) => {
+      persistTheme(newTheme)
+      theme = newTheme
+   }
+
+   const updateReadingMode = (newValue: boolean) => {
+      persistReadingMode(newValue)
+      readingMode = newValue
+   }
+</script>
+
+{#if !showPreferences}
+   <button on:click={(_) => (showPreferences = true)} class="preferences-button"><Adjust
+      /></button>
+{/if}
+
+{#if showPreferences}
+   <div class="panel">
+      <button
+         on:click={(_) => (showPreferences = false)}
+         class="preferences-button preferences-button--close"
+      >
+         <Close />
+      </button>
+
+      <form>
+         <ColorScheme selectedTheme={theme} onSelectTheme={updateTheme} />
+         <ReadingMode inReadingMode={readingMode} onSetReadingMode={updateReadingMode} />
+      </form>
+   </div>
+{/if}

scripts/ReadingMode.svelte

···
+<script lang="typescript">
+   import { assert } from './utils'
+
+   function setReadingMode(event: Event) {
+      assert(event.target instanceof HTMLInputElement, 'badly configured reading mode')
+      onSetReadingMode(event.target.checked)
+   }
+
+   export let onSetReadingMode: (newValue: boolean) => void
+   export let inReadingMode: boolean
+</script>
+
+<fieldset>
+   <label for="reading-mode">Reading mode</label>
+   <input
+      type="checkbox"
+      name="reading-mode"
+      id="reading-mode"
+      checked={inReadingMode}
+      on:change={setReadingMode}
+   />
+</fieldset>

scripts/main.js

···
+import Preferences from './Preferences.svelte'
+import { selectorFor } from './utils'
+
+const preferences = new Preferences({
+   target: document.querySelector(selectorFor('preferences')),
+})
+
+export default preferences

scripts/preferences.ts

···
+import { assert, selectorFor } from './utils'
+
+const ROOT_EL = document.querySelector(selectorFor('root'))
+assert(ROOT_EL instanceof HTMLElement, 'missing root element')
+
+const PREFERENCES_EL = document.querySelector(selectorFor('preferences'))
+assert(PREFERENCES_EL instanceof HTMLElement, 'missing preferences mount element')
+PREFERENCES_EL.classList.remove('no-js-hidden')
+
+export interface Preferences {
+   theme: Theme
+   readingMode: boolean
+}
+
+export enum Theme {
+   System = 'system',
+   Light = 'light',
+   Dark = 'dark',
+}
+
+const THEME_VALUES: string[] = [Theme.System, Theme.Light, Theme.Dark]
+
+export const stringIsTheme = (s: string): s is Theme => THEME_VALUES.includes(s)
+
+/**
+   Update the style class on the root (`html`) element.
+
+   @param root The `html` element
+   @param newTheme The new theme to set on that `html` element.
+ */
+const updateThemeClass = (newTheme: Theme): void => {
+   THEME_VALUES.forEach((className) => ROOT_EL.classList.remove(className))
+   if (newTheme !== Theme.System) ROOT_EL.classList.add(newTheme)
+}
+
+const updateReadingModeClass = (inReadingMode: boolean): void => {
+   if (inReadingMode) {
+      ROOT_EL.classList.add('reading-mode')
+   } else {
+      ROOT_EL.classList.remove('reading-mode')
+   }
+}
+
+const enum LocalStorage {
+   Theme = 'sympolymathesy:theme',
+   ReadingMode = 'sympolymathesy:reading-mode',
+}
+
+// If the user chooses to follow the OS, simply delete the key from local storage: there
+// is no need to *store* "use the OS".
+const saveThemePreference = (theme: Theme): void =>
+   theme === Theme.System
+      ? localStorage.removeItem(LocalStorage.Theme)
+      : localStorage.setItem(LocalStorage.Theme, theme)
+
+const saveReadingModePreference = (inReadingMode: boolean): void =>
+   inReadingMode
+      ? localStorage.setItem(LocalStorage.ReadingMode, 'true')
+      : localStorage.removeItem(LocalStorage.ReadingMode)
+
+export const loadPreferences = (): Preferences => {
+   const themeFromStorage = localStorage.getItem(LocalStorage.Theme)
+   const theme =
+      themeFromStorage && stringIsTheme(themeFromStorage)
+         ? themeFromStorage
+         : Theme.System
+
+   const readingMode = localStorage.getItem(LocalStorage.ReadingMode) === 'true'
+
+   return { theme, readingMode }
+}
+
+export const persistTheme = (newTheme: Theme): void => {
+   updateThemeClass(newTheme)
+   saveThemePreference(newTheme)
+}
+
+export const persistReadingMode = (inReadingMode: boolean): void => {
+   updateReadingModeClass(inReadingMode)
+   saveReadingModePreference(inReadingMode)
+}

scripts/tsconfig.json

···
+{
+   "extends": "../tsconfig.base.json",
+   "compilerOptions": {
+      "removeComments": true,
+      "lib": ["dom", "es2019"],
+      "noEmit": false,
+      "inlineSources": true,
+      "sourceMap": true,
+      "baseUrl": "scripts"
+   },
+   "files": ["preferences.ts"],
+   "include": ["scripts"]
+}

scripts/utils.ts

···
+export const selectorFor = (item: string): string => `[data-sympolymathesy="${item}"]`
+
+export function assert(pred: unknown, message: string): asserts pred {
+   if (!pred) {
+      throw new Error(message)
+   }
+}

site/_includes/base.njk

···
 {% import 'components/social.njk' as social %}
 
 <!DOCTYPE html>
-<html>
+<html data-sympolymathesy='root'>
    <head>
       <meta charset='utf-8'/>
       <meta http-equiv='X-UA-Compatible' content='IE=edge'>
···
          <link rel='alternate' href='/essays/feed.json' type='application/json' title='Essays - Sympolymathesy (JSON)'>
          <link rel='alternate' href='/journal/feed.json' type='application/json' title='Journal - Sympolymathesy (JSON)'>
          <link rel='alternate' href='/library/feed.json' type='application/json' title='Library - Sympolymathesy (JSON)'>
-         <link rel='alternate' href='/photos/feed.json' type='application/json' title='Elsewhere - Sympolymathesy (JSON)'>
-         <link rel='alternate' href='/elsewhere/feed.json' type='application/json' title='Elsewhere - Sympolymathesy (JSON)'>
+         <link rel='alternate' href='/photos/feed.json' type='application/json' title='Photos - Sympolymathesy (JSON)'>
          <link rel='alternate' href='/notes/feed.json' type='application/json' title='Notes - Sympolymathesy (JSON)'>
+         <link rel='alternate' href='/elsewhere/feed.json' type='application/json' title='Elsewhere - Sympolymathesy (JSON)'>
       {% endif -%}
 
       <link rel='alternate' href='/feed.xml' type='application/atom+xml' title='Sympolymathesy (Atom)'>
···
          <link rel='alternate' href='/essays/feed.xml' type='application/atom+xml' title='Essays - Sympolymathesy (Atom)'>
          <link rel='alternate' href='/journal/feed.xml' type='application/atom+xml' title='Journal - Sympolymathesy (Atom)'>
          <link rel='alternate' href='/library/feed.xml' type='application/atom+xml' title='Library - Sympolymathesy (Atom)'>
-         <link rel='alternate' href='/photos/feed.xml' type='application/atom+xml' title='Elsewhere - Sympolymathesy (Atom)'>
-         <link rel='alternate' href='/elsewhere/feed.xml' type='application/atom+xml' title='Elsewhere - Sympolymathesy (Atom)'>
+         <link rel='alternate' href='/photos/feed.xml' type='application/atom+xml' title='Photos - Sympolymathesy (Atom)'>
          <link rel='alternate' href='/notes/feed.xml' type='application/atom+xml' title='Notes - Sympolymathesy (Atom)'>
+         <link rel='alternate' href='/elsewhere/feed.xml' type='application/atom+xml' title='Elsewhere - Sympolymathesy (Atom)'>
       {% endif -%}
 
       {% for link in config.author.links -%}
···
 
       {% block extra_links %}{% endblock extra_links %}
 
-      {% block meta %}{{ social.meta(page, config) }}
-      {% endblock meta%}
+      <link rel='preload' as='script' type='application/javascript' href='/assets/js/main.js'>
+
+      {% block meta %}{{ social.meta(page, config) }}{% endblock meta%}
    </head>
    <body>
       <main>
···
             {%- endfor -%}
          </ul>
       </nav>
+
+      <div data-sympolymathesy='preferences' class='preferences no-js-hidden'></div>
+      <script src='/assets/js/main.js'></script>
    </body>
-</html>
+</html>

site/_includes/styles/_layout.scss

···
    --padding: #{ms(-8)};
    margin: var(--padding);
    width: calc(100% - 2 * var(--padding));
+   transition: 0.7s margin ease-out, 0.7s max-width ease-out;
 }
 
 @media screen {
···
 
       @media (min-height: 600px) {
          main {
-            transition: 0.7s margin ease-out, 0.7s max-width ease-out;
             --padding: #{ms(-1)};
 
             margin: {
···
             top: 0;
             right: 0;
             bottom: 0;
+            transition: 0.7s right ease-out;
          }
 
          .reading-mode {
             main {
-               transition: 0.7s margin ease-out, 0.7s max-width ease-out;
                --padding: 0.25em;
                max-width: calc(100vw - 0.5em - 2px);
             }
 
             nav {
                right: -25vw;
+               transition: 0.7s right ease-out;
             }
          }
       }

site/_includes/styles/_utils.scss

···
-@import './utils/no-break';
+@import './utils/no-break';
+@import './utils/no-js-hidden';

site/_includes/styles/components/_preferences.scss

···
+.preferences {
+   font: var(--sans);
+   position: absolute;
+   top: 1em;
+   right: 1em;
+}
+
+.preferences-button {
+   position: absolute;
+   top: 0;
+   right: 0;
+}

site/_includes/styles/style.scss

···
 @import './components';
 @import './layout';
 @import './typography';
+@import './utils';

site/_includes/styles/utils/_no-js-hidden.scss

···
+.no-js-hidden {
+   display: none;
+}

site/journal/notes-on-color-scheme-handling.md site/journal/2020/Color Schemes.md

···
 ---
 title: Color Schemes!
 subtitle: >
-    A few notes on pairing <code>prefers-color-scheme</code> and user configurability.
-date: 2019-12-07T11:45
+    A few notes on pairing `prefers-color-scheme` and user configurability.
+date: 2020-12-30T12:00
 tags:
 - JavaScript
 - TypeScript
···
 
 ---
 
-When redesigning this site, I knew I wanted to take advantage of macOS' and Windows' recent ability to support dark mode in the website (with the new CSS media query [`prefers-color-scheme`]). However, I also knew that I wanted to make things user-configurable. As same time I publish this post, I have also added a tiny bit of JavaScript to the site that lets users override their operating system default to view the site in its light or dark theme as they please.
-
-[`prefers-color-scheme`]: TODO
+When redesigning this site, I knew I wanted to take advantage of macOS' and Windows' recently-added ability to support dark mode in the website (with the new <abbr title="cascading style sheets">CSS</abbr> media query [`prefers-color-scheme`]). However, I also knew that I wanted to make it user-configurable. It took me over a year, but at last—at the same time as same time I publish this post—I have also added a tiny bit of JavaScript to the site that lets users override their operating system default to view the site in its light or dark theme as they please.
 
-*[CSS]: cascading style sheets
+[`prefers-color-scheme`]: http://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
 
 As is my habit when I deal with a question of how to implement something like this, I built out a table to capture how this should work:
 
···
 | dark                   | light               | light  |
 | dark                   | dark                | dark   |
 
-This isn't complicated, <i>per se</i>… but it it *does* require some thought to make sure it works just right and that the CSS and JS interact correctly.
-
-*[JS]: JavaScript
+This isn't complicated, <i>per se</i>… but it it *does* require some thought to make sure it works just right and that the <abbr>CSS</abbr> and <abbr title="JavaScript">JS</abbr> interact correctly.
 
-## CSS
+## <abbr>CSS</abbr>
 
-On the CSS side of things, it was important that there be *one* definition of what the light and dark color schemes are, and then that the `prefers-color-scheme` and a CSS class both use that same definition. That way, I don't have to try to keep multiple definitions in sync.
+On the <abbr>CSS</abbr> side of things, it was important that there be *one* definition of what the light and dark color schemes are, and then that the `prefers-color-scheme` and a <abbr>CSS</abbr> class both use that same definition. That way, I don't have to try to keep multiple definitions in sync.
 
-To make this work, I combined the power of [CSS Custom Properties] and an [SCSS] mixin. The custom properties define the set of colors in play throughout the site: foreground, background, borders, link colors, etc. The mixin then applies those custom properties to the style selectors. As a simplified example:
+To make this work, I combined the power of [<abbr>CSS</abbr> Custom Properties][custom-properties] and an [<abbr title="sassy CSS">SCSS</abbr>][SCSS] mixin. The custom properties define the set of colors in play throughout the site: foreground, background, borders, link colors, etc. The mixin then applies those custom properties to the style selectors. As a simplified example:
 
 ```scss
 @mixin light {
···
 }
 ```
 
-[CSS Custom Properties]: TODO
-[SCSS]: TODO
-
-*[SCSS]: TODO
+[custom-properties]: http://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+[SCSS]: https://sass-lang.com
 
 ## JavaScript
 
-Because I did the hard work of pushing all the complexity into the CSS, the JS ends up being very simple. It only really has two responsibilities:
+Because I did the hard work of pushing all the complexity into the <abbr>CSS</abbr>, the <abbr>JS</abbr> ends up being very simple. It only really has two responsibilities:
 
-1. setting or clearing the `.light` or `.dark` classes when the user interacts with the UI element
+1. setting or clearing the `.light` or `.dark` classes when the user interacts with the <abbr title="user interface">UI</abbr> element
 2. if the user has specified an override, storing that decision somewhere to look it up when the site loads
-
-*[UI]: user interface
 
 ### Responding to the user setting
 

svelte.config.js

···
       // enable run-time checks when not in production
       dev: !production,
    }),
-   // we'll extract any component CSS out into
-   // a separate file — better for performance
-   // css: (css) => {
-   //    css.write('public/bundle.css')
-   // },
 }

tsconfig.base.json

···
+{
+   "compilerOptions": {
+      /* Basic Options */
+      "target": "es2019",
+      "module": "commonjs",
+      "lib": ["es2019"] /* Specify library files to be included in the compilation. */,
+      "checkJs": true /* Report errors in .js files. */,
+      "allowJs": true,
+
+      /* Strict Type-Checking Options */
+      "strict": true /* Enable all strict type-checking options. */,
+
+      /* Additional Checks */
+      "noUnusedLocals": true /* Report errors on unused locals. */,
+      "noUnusedParameters": true /* Report errors on unused parameters. */,
+      "noImplicitReturns": true /* Report error when not all code paths in function return a value. */,
+      "noFallthroughCasesInSwitch": true /* Report errors for fallthrough cases in switch statement. */,
+
+      /* Module Resolution Options */
+      "baseUrl": "./" /* Base directory to resolve non-absolute module names. */,
+      "paths": {
+         "*": ["types/*"]
+      } /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */,
+      // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
+      "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+      // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */
+
+      /* Source Map Options */
+      // "sourceRoot": "",                      /* Specify the location where debugger should locate TypeScript files instead of source locations. */
+      // "mapRoot": "",                         /* Specify the location where debugger should locate map files instead of generated locations. */
+      // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
+      // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
+
+      /* Experimental Options */
+      "experimentalDecorators": true /* Enables experimental support for ES7 decorators. */
+   }
+}

tsconfig.json

···
 {
+   "extends": "./tsconfig.base.json",
    "compilerOptions": {
-      /* Basic Options */
-      "target": "es2018" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */,
-      "module": "commonjs" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */,
-      "lib": ["es2019"] /* Specify library files to be included in the compilation. */,
-      "checkJs": true /* Report errors in .js files. */,
-      "allowJs": true,
-      // "declaration": true,                   /* Generates corresponding '.d.ts' file. */
-      // "declarationMap": true,                /* Generates a sourcemap for each corresponding '.d.ts' file. */
-      // "sourceMap": true,                     /* Generates corresponding '.map' file. */
-      // "outFile": "./",                       /* Concatenate and emit output to single file. */
-      // "outDir": "./",                        /* Redirect output structure to the directory. */
-      // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
-      // "composite": true,                     /* Enable project compilation */
-      // "incremental": true,                   /* Enable incremental compilation */
-      // "tsBuildInfoFile": "./",               /* Specify file to store incremental compilation information */
-      // "removeComments": true,                /* Do not emit comments to output. */
-      "noEmit": true /* Do not emit outputs. (BECAUSE WE'RE USING TS-NODE!) */,
-      // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
-      // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
-      // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */
-
-      /* Strict Type-Checking Options */
-      "strict": true /* Enable all strict type-checking options. */,
-
-      /* Additional Checks */
-      "noUnusedLocals": true /* Report errors on unused locals. */,
-      "noUnusedParameters": true /* Report errors on unused parameters. */,
-      "noImplicitReturns": true /* Report error when not all code paths in function return a value. */,
-      "noFallthroughCasesInSwitch": true /* Report errors for fallthrough cases in switch statement. */,
-
-      /* Module Resolution Options */
-      "moduleResolution": "node" /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */,
-      "baseUrl": "./" /* Base directory to resolve non-absolute module names. */,
-      "paths": {
-         "*": ["types/*"]
-      } /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */,
-      // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
-      "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
-      // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */
-
-      /* Source Map Options */
-      // "sourceRoot": "",                      /* Specify the location where debugger should locate TypeScript files instead of source locations. */
-      // "mapRoot": "",                         /* Specify the location where debugger should locate map files instead of generated locations. */
-      // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
-      // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
-
-      /* Experimental Options */
-      "experimentalDecorators": true /* Enables experimental support for ES7 decorators. */
+      "module": "commonjs",
+      "noEmit": true /* Do not emit outputs. (BECAUSE WE'RE USING TS-NODE!) */
    },
    "include": ["site/**/*.11ty.js", "lib", "eleventy", "types", ".eleventy.ts"],
    "exclude": ["site/_data/build.js"]