refactor: add proper typing

dist/docs/script.js

@@ -1,2 +1,2 @@
-"use strict";var e="https://cdn.jsdelivr.net/gh/kognise/water.css/dist/",t={"dark.min.css":1.4,"dark.standalone.min.css":1.31,"dark-legacy.min.css":2.487,"dark-legacy.standalone.min.css":1.16,"light.min.css":1.4,"light.standalone.min.css":1.3,"light-legacy.min.css":.178+1.16+1.15,"light-legacy.standalone.min.css":1.15},n=function(e){var t=e.theme,n=e.isLegacy,r=e.isStandalone;return"".concat(t).concat(n?"-legacy":"").concat(r?".standalone":"",".min.css")},r=function(t){var r=t.theme,s=t.isLegacy,i=t.isStandalone,a=n({theme:r,isLegacy:s,isStandalone:i}),c='<link rel="stylesheet" href="'.concat(e).concat(a,'">');if(!s||i)return c;var o="dark"===r?"light":"dark";return(function(t,n,r){return'\n\x3c!-- Preload the required stylesheets (optional) --\x3e\n<link rel="preload" as="style" href="'.concat(e).concat(t,'">\n<link rel="preload" as="style" href="').concat(e).concat(n,'" media="(prefers-color-scheme: ').concat(r,')">')}(n({theme:r,isLegacy:!0,isStandalone:!0}),n({theme:o,isLegacy:!0,isStandalone:!0}),o)+"\n\n"+c).trim()},s={_phImage:document.querySelector("#js-producthunt"),_stylesheet:document.querySelector("#js-stylesheet"),updateStylesheet:function(e){this._stylesheet.href=e},updateProductHunt:function(e){this._phImage.src=this._phImage.src.replace(/dark|light/,e)},update:function(e,t){var r=e.theme,s=e.isStandalone,i="../"+n(e),a=s?r:t||r;this.updateStylesheet(i),this.updateProductHunt(a)}},i=function(e,t){var n=matchMedia("(prefers-color-scheme: ".concat(e,")"));n.addListener(function(e){return t(e.matches)}),t(n.matches)};new Vue({el:"#installation",filters:{capitalize:function(e){return e.charAt(0).toUpperCase()+e.slice(1)}},data:{versionOptions:{theme:"dark",isStandalone:!1,isLegacy:!1},preferedColorScheme:null,copyStatus:null},computed:{selectedVersion:function(){return{fileName:n(this.versionOptions),fileSize:(e=this.versionOptions,t[n(e)]||0).toFixed(2),fileSnippet:r(this.versionOptions)};var e}},created:function(){var e=this;i("dark",function(t){return t&&(e.preferedColorScheme="dark")}),i("light",function(t){return t&&(e.preferedColorScheme="light")}),this.preferedColorScheme&&s.updateProductHunt(this.preferedColorScheme)},methods:{copyToClipboard:function(){var e=this;Promise.resolve().then(function(){return clipboard.writeText(e.selectedVersion.fileSnippet)}).then(function(){return e.copyStatus="success"}).catch(function(){return e.copyStatus="failed"}),setTimeout(function(){return e.copyStatus=void 0},1e3)}},watch:{preferedColorScheme:function(e){s.update(this.versionOptions,e)},versionOptions:{deep:!0,handler:function(e){s.update(e,this.preferedColorScheme)}}}});
+"use strict";var e=window,t="https://cdn.jsdelivr.net/gh/kognise/water.css/dist/",n={"dark.min.css":1.4,"dark.standalone.min.css":1.31,"dark-legacy.min.css":2.487,"dark-legacy.standalone.min.css":1.16,"light.min.css":1.4,"light.standalone.min.css":1.3,"light-legacy.min.css":.178+1.16+1.15,"light-legacy.standalone.min.css":1.15},s=function(e){var t=e.theme,n=e.isLegacy?"-legacy":"",s=e.isStandalone?".standalone":"";return"".concat(t).concat(n).concat(s,".min.css")},r=function(e){var n=e.theme,r=e.isLegacy,i=e.isStandalone,c=s({theme:n,isLegacy:r,isStandalone:i}),a='<link rel="stylesheet" href="'.concat(t).concat(c,'">');return!r||i?a:(function(e){var n=e.theme,r=e.isLegacy,i=e.isStandalone,c="dark"===n?"light":"dark",a=s({theme:c,isLegacy:r,isStandalone:i});return'\n\x3c!-- Preload the required stylesheets (optional) --\x3e\n<link rel="preload" as="style" href="'.concat(t).concat(s({theme:n,isLegacy:r,isStandalone:i}),'">\n<link rel="preload" as="style" href="').concat(t).concat(a,'" media="(prefers-color-scheme: ').concat(c,')">')}({theme:n,isLegacy:r,isStandalone:!0})+"\n\n"+a).trim()},i={_productHunt:document.querySelector("#js-producthunt"),_stylesheet:document.querySelector("#js-stylesheet"),_updateProductHunt:function(e){this._productHunt.src=this._productHunt.src.replace(/dark|light/,e)},_updateStylesheet:function(e){this._stylesheet.href="../"+e},update:function(e,t){var n=e.isStandalone?e.theme:t||e.theme;this._updateStylesheet(s(e)),this._updateProductHunt(n)}},c=function(t,n){var s=e.matchMedia("(prefers-color-scheme: ".concat(t,")"));s.addListener(function(e){return n(e.matches)}),n(s.matches)};new e.Vue({el:"#installation",filters:{capitalize:function(e){return e.charAt(0).toUpperCase()+e.slice(1)}},data:{versionOptions:{theme:"dark",isStandalone:!1,isLegacy:!1},preferedColorScheme:null,copyStatus:null},computed:{selectedVersion:function(){return{fileName:s(this.versionOptions),fileSize:(e=this.versionOptions,n[s(e)]||0).toFixed(2),fileSnippet:r(this.versionOptions)};var e}},created:function(){var e=this;c("dark",function(t){return t&&(e.preferedColorScheme="dark")}),c("light",function(t){return t&&(e.preferedColorScheme="light")}),this.preferedColorScheme&&i._updateProductHunt(this.preferedColorScheme)},methods:{copyToClipboard:function(){var t=this;Promise.resolve().then(function(){return e.clipboard.writeText(t.selectedVersion.fileSnippet)}).then(function(){return t.copyStatus="success"}).catch(function(){return t.copyStatus="failed"}),setTimeout(function(){return t.copyStatus=null},1e3)}},watch:{preferedColorScheme:function(e){i.update(this.versionOptions,e)},versionOptions:{deep:!0,handler:function(e){i.update(e,this.preferedColorScheme)}}}});
 //# sourceMappingURL=script.js.map

docs/script.js

@@ -1,10 +1,12 @@
-/**
- * Type definition for the version object used throughout the code
- * @typedef {Object} VersionOptions
- * @prop {'dark' | 'light'} theme
- * @prop {boolean} isLegacy
- * @prop {boolean} isStandalone
- */
+// @ts-check
+/** @typedef {'dark' | 'light'} Theme */
+/** @typedef {keyof typeof FILE_SIZES} FileName */
+/** @typedef {'success' | 'failed'} CopyStatus */
+/** @typedef {{ Vue: typeof import('vue').default, clipboard: Clipboard }} Libraries */
+/** @typedef {{ theme: Theme, isLegacy: boolean, isStandalone: boolean }} VersionOptions */
+
+/** Reference to global window, but with properties for loaded libraries. */
+const w = /** @type {Window & Libraries} */ (window)
 
 /** The base URI from where the docs page loads the CSS files. */
 const DEV_BASE = '../'
@@ -23,74 +25,90 @@ const FILE_SIZES = {
   'light-legacy.standalone.min.css': 1.15,
 }
 
-/** @param {VersionOptions} options */
-const getFileName = ({ theme, isLegacy, isStandalone }) => {
-  return `${theme}${isLegacy ? '-legacy' : ''}${isStandalone ? '.standalone' : ''}.min.css`
+/** Takes in version options and returns the respective CSS file name. */
+const getFileName = (/** @type {VersionOptions} */ { theme, isLegacy, isStandalone }) => {
+  const legacySuffix = isLegacy ? '-legacy' : ''
+  const standaloneExt = isStandalone ? '.standalone' : ''
+  return /** @type {FileName} */ (`${theme}${legacySuffix}${standaloneExt}.min.css`)
 }
 
-/** @param {VersionOptions} options */
-const getFileSize = options => {
-  return FILE_SIZES[getFileName(options)] || 0
-}
+/** Takes in version options and returns the corresponding file size in KB. */
+const getFileSize = (/** @type {VersionOptions} */ options) => FILE_SIZES[getFileName(options)] || 0
+
+/** Takes in version options and returns an HTML snippet that preloads the main stylesheet and
+ *  conditionally preloads the alternative stylesheet (if the alternative theme is active). */
+const getFilePreloadSnippet = (/** @type {VersionOptions} */ { theme, isLegacy, isStandalone }) => {
+  const alternativeTheme = theme === 'dark' ? 'light' : 'dark'
+  const alternativeFile = getFileName({ theme: alternativeTheme, isLegacy, isStandalone })
 
-const getFilePreloadSnippet = (mainFileName, altFileName, altTheme) => {
   return `
 <!-- Preload the required stylesheets (optional) -->
-<link rel="preload" as="style" href="${CDN_BASE}${mainFileName}">
-<link rel="preload" as="style" href="${CDN_BASE}${altFileName}" media="(prefers-color-scheme: ${altTheme})">`
+<link rel="preload" as="style" href="${CDN_BASE}${getFileName({ theme, isLegacy, isStandalone })}">
+<link rel="preload" as="style" href="${CDN_BASE}${alternativeFile}" media="(prefers-color-scheme: ${alternativeTheme})">`
 }
 
-/** @param {VersionOptions} options */
-const getFileSnippet = ({ theme, isLegacy, isStandalone }) => {
+/** Takes in version options and returns the code snippet instructing users how to load the file. */
+const getFileSnippet = (/** @type {VersionOptions} */ { theme, isLegacy, isStandalone }) => {
   const fileName = getFileName({ theme, isLegacy, isStandalone })
   const stylesheetSnippet = `<link rel="stylesheet" href="${CDN_BASE}${fileName}">`
 
   if (!isLegacy || isStandalone) return stylesheetSnippet
 
-  const altTheme = theme === 'dark' ? 'light' : 'dark'
-  const mainStandaloneFile = getFileName({ theme, isLegacy: true, isStandalone: true })
-  const altStandaloneFile = getFileName({ theme: altTheme, isLegacy: true, isStandalone: true })
-  const preloadSnippet = getFilePreloadSnippet(mainStandaloneFile, altStandaloneFile, altTheme)
-
+  const preloadSnippet = getFilePreloadSnippet({ theme, isLegacy, isStandalone: true })
   return (preloadSnippet + '\n\n' + stylesheetSnippet).trim()
 }
 
+/** Handles elements external to the version picker that still need to be kept
+ *  up to date with the current version, e.g. switching images from dark to light. */
 const externalElements = {
-  _phImage: document.querySelector('#js-producthunt'),
-  _stylesheet: document.querySelector('#js-stylesheet'),
-
-  updateStylesheet(href) {
-    this._stylesheet.href = href
+  _productHunt: /** @type {HTMLImageElement} */ (document.querySelector('#js-producthunt')),
+  _stylesheet: /** @type {HTMLLinkElement} */ (document.querySelector('#js-stylesheet')),
+  _updateProductHunt(/** @type {Theme} */ theme) {
+    this._productHunt.src = this._productHunt.src.replace(/dark|light/, theme)
   },
-  updateProductHunt(theme) {
-    this._phImage.src = this._phImage.src.replace(/dark|light/, theme)
+  _updateStylesheet(/** @type {FileName} */ fileName) {
+    this._stylesheet.href = DEV_BASE + fileName
   },
-  /** @param {VersionOptions} options @param {'dark' | 'light'} [preferedColorScheme] */
-  update(options, preferedColorScheme) {
-    const { theme, isStandalone } = options
-    const href = DEV_BASE + getFileName(options)
-    const visibleTheme = isStandalone ? theme : preferedColorScheme || theme
 
-    this.updateStylesheet(href)
-    this.updateProductHunt(visibleTheme)
+  /** Takes current version + the user's prefered scheme and updates all external elements. */
+  update(/** @type {VersionOptions} */ options, /** @type {?Theme} */ preferedTheme) {
+    const displayedTheme = options.isStandalone ? options.theme : preferedTheme || options.theme
+
+    this._updateStylesheet(getFileName(options))
+    this._updateProductHunt(displayedTheme)
   },
 }
 
-const createColorSchemeListener = (theme, queryHandler) => {
-  const mediaQuery = matchMedia(`(prefers-color-scheme: ${theme})`)
+/**
+ * Sets up a media query for the given color scheme and runs the callback on change.
+ * @param {Theme} scheme
+ * @param {(matches: boolean) => any} queryHandler
+ */
+const createColorSchemeListener = (scheme, queryHandler) => {
+  const mediaQuery = w.matchMedia(`(prefers-color-scheme: ${scheme})`)
   mediaQuery.addListener(query => queryHandler(query.matches))
   queryHandler(mediaQuery.matches)
 }
 
-new Vue({
+/** @typedef {Object} VueData
+ * @prop {VersionOptions} versionOptions
+ * @prop {?CopyStatus} copyStatus
+ * @prop {?Theme} preferedColorScheme
+ */
+
+new w.Vue({
   el: '#installation',
-  filters: { capitalize: str => str.charAt(0).toUpperCase() + str.slice(1) },
+  filters: {
+    capitalize: (/** @type {string} */ str) => str.charAt(0).toUpperCase() + str.slice(1),
+  },
+  /** @type {VueData} */
   data: {
-    versionOptions: { theme: 'dark', isStandalone: false, isLegacy: false },
+    versionOptions: { theme: /** @type {Theme} */ ('dark'), isStandalone: false, isLegacy: false },
     preferedColorScheme: null,
     copyStatus: null,
   },
   computed: {
+    /** @returns {{ fileName: string, fileSize: string, fileSnippet: string }} */
     selectedVersion() {
       return {
         fileName: getFileName(this.versionOptions),
@@ -103,24 +121,24 @@ new Vue({
     createColorSchemeListener('dark', match => match && (this.preferedColorScheme = 'dark'))
     createColorSchemeListener('light', match => match && (this.preferedColorScheme = 'light'))
 
-    if (this.preferedColorScheme) externalElements.updateProductHunt(this.preferedColorScheme)
+    if (this.preferedColorScheme) externalElements._updateProductHunt(this.preferedColorScheme)
   },
   methods: {
     copyToClipboard() {
       Promise.resolve()
-        .then(() => clipboard.writeText(this.selectedVersion.fileSnippet))
+        .then(() => w.clipboard.writeText(this.selectedVersion.fileSnippet))
         .then(() => (this.copyStatus = 'success'))
         .catch(() => (this.copyStatus = 'failed'))
-      setTimeout(() => (this.copyStatus = undefined), 1000)
+      setTimeout(() => (this.copyStatus = null), 1000)
     },
   },
   watch: {
-    preferedColorScheme(nextScheme) {
+    preferedColorScheme(/** @type {Theme} */ nextScheme) {
       externalElements.update(this.versionOptions, nextScheme)
     },
     versionOptions: {
       deep: true,
-      handler(nextOptions) {
+      handler(/** @type {VersionOptions} */ nextOptions) {
         externalElements.update(nextOptions, this.preferedColorScheme)
       },
     },

package.json

@@ -45,7 +45,8 @@
     "postcss-color-mod-function": "^3.0.3",
     "postcss-css-variables": "^0.12.0",
     "postcss-import": "^12.0.1",
-    "posthtml-include": "^1.2.0"
+    "posthtml-include": "^1.2.0",
+    "vue": "^2.6.10"
   },
   "browserslist": [
     "defaults AND not android 4.4.3"

yarn.lock

@@ -6459,6 +6459,11 @@ vinyl@^2.0.0:
     remove-trailing-separator "^1.0.1"
     replace-ext "^1.0.0"
 
+vue@^2.6.10:
+  version "2.6.10"
+  resolved "https://registry.yarnpkg.com/vue/-/vue-2.6.10.tgz#a72b1a42a4d82a721ea438d1b6bf55e66195c637"
+  integrity sha512-ImThpeNU9HbdZL3utgMCq0oiMzAkt1mcgy3/E6zWC/G6AaQoeuFdsl9nDhTDU3X1R6FK7nsIUuRACVcjI+A2GQ==
+
 w3c-hr-time@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/w3c-hr-time/-/w3c-hr-time-1.0.1.tgz#82ac2bff63d950ea9e3189a58a65625fedf19045"