1
0
mirror of https://github.com/kognise/water.css.git synced 2025-02-23 13:23:54 +01:00

Update docs pt.1

This commit is contained in:
Felix 2020-05-28 14:40:02 -05:00
parent 2c29269710
commit 7e4251f5c1
3 changed files with 289 additions and 262 deletions

View File

@ -10,7 +10,6 @@
content="A drop-in collection of CSS styles to make simple websites like this just a little bit nicer."
/>
<!-- Icons generated with https://realfavicongenerator.net -->
<link rel="apple-touch-icon" sizes="180x180" href="./icons/apple-touch-icon.png" />
<link rel="icon" id="icon-16" type="image/png" sizes="16x16" href="./icons/favicon-16x16.png" />
<link rel="icon" id="icon-32" type="image/png" sizes="32x32" href="./icons/favicon-32x32.png" />
@ -24,17 +23,13 @@
<meta name="theme-color" content="#ffffff" />
<!-- Startup styles of water.css, so styles don't have to wait until JS is loaded -->
<link rel="preload" as="style" href="./water.css/dark-legacy.standalone.min.css" />
<link
rel="preload"
as="style"
media="(prefers-color-scheme: dark)"
href="./water.css/dark-legacy.standalone.min.css"
/>
<link rel="stylesheet" id="js-startup-stylesheet" href="./water.css/dark-legacy.min.css" />
<link rel="preload" as="style" href="./water.css/dark.min.css" />
<link rel="preload" as="style" href="./water.css/light.min.css" />
<link rel="stylesheet" id="js-startup-stylesheet" href="./water.css/water.min.css" />
<!-- Dynamic version of water.css, overwrites startup styles. JavaScript sets & updates href -->
<link rel="stylesheet" id="js-stylesheet" />
<!-- Custom styles for the documentation / version picker -->
<link rel="stylesheet" href="style.css" />
@ -48,7 +43,7 @@
/>
<meta
property="og:image"
content="https://raw.githubusercontent.com/kognise/water.css/29afc6c80a1a38123e47c8a50779faae97cc2a8b/assets/logo.png"
content="https://raw.githubusercontent.com/kognise/water.css/master/logo.png"
/>
<meta property="og:image:width" content="1154" />
<meta property="og:image:height" content="444" />
@ -87,16 +82,19 @@
<p>
Water.css is a drop-in collection of CSS styles to make simple websites like this just a
little bit nicer.
<br />
</p>
<p>
Now you can write your simple static site with nice semantic html, and Water.css will manage
the styling for you.
</p>
<div class="row">
<div>
<a href="#installation"><b>Get it already!</b></a>
<br />
<a href="https://github.com/kognise/water.css"><b>GitHub</b></a>
</div>
<a
href="https://www.producthunt.com/posts/water-css?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-water-css"
target="_blank"
@ -113,7 +111,56 @@
</div>
<h2>Installation</h2>
<include src="./versionpicker.html"></include>
<div id="installation" class="version-select">
<header class="row version-select-snippet">
<h3>Paste this into the <code>&lt;head&gt;</code> of your HTML:</h3>
<button type="button" id="copy-snippet">
Copy to clipboard
</button>
</header>
<pre><code id="link-snippet">Oh noes, the JavaScript hasn't loaded!</code></pre>
<h3>Options</h3>
<form id="theme-form">
<input type="radio" value="auto" checked name="theme" id="theme-auto" />
<label for="theme-auto">Automatic <span class="emoji">🌙</span> / <span class="emoji"></span></label>
<input type="radio" value="dark" name="theme" id="theme-dark" />
<label for="theme-dark">Dark theme <span class="emoji">🌙</span></label>
<input type="radio" value="light" name="theme" id="theme-light" />
<label for="theme-light">Light theme <span class="emoji"></span></label>
</form>
<table id="version-info">
<caption>
<h3>Version info</h3>
</caption>
<tbody>
<tr>
<th scope="row">File</th>
<td id="table-file-name"></td>
</tr>
<tr>
<th scope="row">Size (min + gzip)</th>
<td id="table-file-size"></td>
</tr>
<tr>
<th scope="row">Theme</th>
<td id="table-theme"></td>
</tr>
<tr>
<th scope="row">Browser support</th>
<td id="table-browser-support"></td>
</tr>
</tbody>
</table>
</div>
<h2 id="goals">Goals</h2>
<ul>

View File

@ -1,187 +1,237 @@
// @ts-check
/** @typedef {'dark' | 'light'} Theme */
/** @typedef {keyof typeof FILE_SIZES} FileName */
/** @typedef {'success' | 'failed'} CopyStatus */
/**
* @typedef {Object} VersionOptions Configurable options for water.css versions
* @prop {Theme} theme
* @prop {boolean} isLegacy
* @prop {boolean} isStandalone
*/
/**
* @typedef {Object} Libraries External packages exposed on `window` (loaded through `<script>`)
* @prop {typeof import('vue').default} Vue
* @prop {Clipboard} clipboard
* @prop {import('favicon-mode-switcher')} faviconModeSwitcher
*/
/**
* @typedef {Object} VueData State used by the version picker
* @prop {VersionOptions} versionOptions
* @prop {?CopyStatus} copyStatus
* @prop {?Theme} preferedColorScheme
*/
const cdnBase = 'https://cdn.jsdelivr.net/npm/water.css@2/dist/'
const localBase = './water.css/'
/** Reference to global window, but with properties for loaded libraries. */
const w = /** @type {Window & Libraries} */ (window)
const queryParams = new URLSearchParams(w.location.search)
const supportsCssVars = typeof CSS !== 'undefined' && CSS.supports('color', 'var(--clr)')
/** The base URI from where the docs page loads the CSS files. */
const DEV_BASE = './water.css/'
/** The base URI from where instructions show to load the CSS files. */
const CDN_BASE = 'https://cdn.jsdelivr.net/npm/water.css@2/dist/'
/** An object mapping the (minified + gzipped) fileSize in KB to a fileName. */
const FILE_SIZES = {
'dark.min.css': 1.4,
'dark.standalone.min.css': 1.31,
'dark-legacy.min.css': 0.177 + 1.16 + 1.15,
'dark-legacy.standalone.min.css': 1.16,
'light.min.css': 1.4,
'light.standalone.min.css': 1.3,
'light-legacy.min.css': 0.178 + 1.16 + 1.15,
'light-legacy.standalone.min.css': 1.15
const fileSizes = {
dark: 2.3,
light: 2.29,
auto: 2.96
}
/** 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`)
const themeForm = document.getElementById('theme-form')
const linkSnippet = document.getElementById('link-snippet')
const stylesheet = document.getElementById('js-stylesheet')
const startupStylesheet = document.getElementById('js-startup-stylesheet')
const table = {
fileName: document.getElementById('table-file-name'),
fileSize: document.getElementById('table-file-size'),
theme: document.getElementById('table-theme'),
browserSupport: document.getElementById('table-browser-support')
}
/** Takes in version options and returns the corresponding file size in KB. */
const getFileSize = (/** @type {VersionOptions} */ options) => FILE_SIZES[getFileName(options)] || 0
const updateTheme = () => {
const theme = themeForm.theme.value
const fileName = `${theme === 'auto' ? 'water' : theme}.min.css`
const cdnUrl = `${cdnBase}${fileName}`
const localUrl = `${localBase}${fileName}`
/** 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 })
stylesheet.href = localUrl
return `
<!-- Preload the required stylesheets (optional) -->
<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})">`
}
linkSnippet.innerText = `<link rel="stylesheet" href="${cdnUrl}">`
table.fileName.innerText = fileName
table.fileSize.innerText = `${fileSizes[theme].toFixed(2)} kb`
/** 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 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 = {
_productHunt: /** @type {HTMLImageElement} */ (document.querySelector('#js-producthunt')),
_stylesheet: /** @type {HTMLLinkElement} */ (document.querySelector('#js-stylesheet')),
_removeStartupStylesheet: () => {
const startupStylesheet = document.head.querySelector('#js-startup-stylesheet')
if (startupStylesheet) document.head.removeChild(startupStylesheet)
externalElements._stylesheet.removeEventListener('load', externalElements._removeStartupStylesheet)
},
_updateProductHunt: (/** @type {Theme} */ theme) => {
externalElements._productHunt.src = externalElements._productHunt.src.replace(/dark|light/, theme)
},
_updateStylesheet: (/** @type {FileName} */ fileName) => {
externalElements._stylesheet.href = DEV_BASE + fileName
},
/** Sets up listener to remove startup version of water.css when right one loads, then updates */
init: (/** @type {VersionOptions} */ options, /** @type {?Theme} */ preferedTheme) => {
externalElements._stylesheet.addEventListener('load', externalElements._removeStartupStylesheet)
externalElements.update(options, preferedTheme)
},
/** 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
externalElements._updateStylesheet(getFileName(options))
externalElements._updateProductHunt(displayedTheme)
if (theme === 'auto') {
table.theme.innerHTML = 'Defaults to dark, but respects user-defined theme settings. Detected via <code>prefers-color-scheme</code>'
table.browserSupport.innerHTML = `
All current browsers
(<a href="https://caniuse.com/#feat=css-variables" target="_blank">support for CSS Custom Properties</a>)
`
} else {
table.theme.innerText = `Theme is forced to ${theme}`
table.browserSupport.innerText = 'All browsers (including Internet Explorer)'
}
}
/**
* 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)
}
themeForm.addEventListener('input', updateTheme)
const themeFromParams = queryParams.get('theme')
/** @type {VersionOptions} */
const initialVersionOptions = {
theme: themeFromParams === 'dark' || themeFromParams === 'light' ? themeFromParams : 'dark',
isLegacy: queryParams.has('legacy') || !supportsCssVars,
isStandalone: queryParams.has('standalone')
}
updateTheme()
startupStylesheet.remove()
new w.Vue({ // eslint-disable-line no-new
el: '#installation',
filters: {
capitalize: (/** @type {string} */ str) => str.charAt(0).toUpperCase() + str.slice(1)
},
/** @type {VueData} */
data: {
versionOptions: initialVersionOptions,
preferedColorScheme: null,
copyStatus: null
},
computed: {
/** @returns {boolean} */
isOverwritten () {
const { isStandalone, theme } = this.versionOptions
if (isStandalone || !this.preferedColorScheme) return false
return theme !== this.preferedColorScheme
},
/** @returns {{ fileName: string, fileSize: string, fileSnippet: string }} */
selectedVersion () {
return {
fileName: getFileName(this.versionOptions),
fileSize: getFileSize(this.versionOptions).toFixed(2),
fileSnippet: getFileSnippet(this.versionOptions)
}
}
},
created () {
createColorSchemeListener('dark', match => match && (this.preferedColorScheme = 'dark'))
createColorSchemeListener('light', match => match && (this.preferedColorScheme = 'light'))
// // @ts-check
// /** @typedef {'dark' | 'light'} Theme */
// /** @typedef {keyof typeof FILE_SIZES} FileName */
// /** @typedef {'success' | 'failed'} CopyStatus */
// /**
// * @typedef {Object} VersionOptions Configurable options for water.css versions
// * @prop {Theme} theme
// * @prop {boolean} isLegacy
// * @prop {boolean} isStandalone
// */
// /**
// * @typedef {Object} Libraries External packages exposed on `window` (loaded through `<script>`)
// * @prop {typeof import('vue').default} Vue
// * @prop {Clipboard} clipboard
// * @prop {import('favicon-mode-switcher')} faviconModeSwitcher
// */
// /**
// * @typedef {Object} VueData State used by the version picker
// * @prop {VersionOptions} versionOptions
// * @prop {?CopyStatus} copyStatus
// * @prop {?Theme} preferedColorScheme
// */
externalElements.init(this.versionOptions, this.preferedColorScheme)
},
methods: {
getTooltipMessage (/** @type {Theme} */ theme) {
if (this.versionOptions.theme === theme && this.isOverwritten) {
return 'Your theme selection is currently overwritten by the theme setting on your device.'
} else return "Selected theme can be overwritten by theme setting on user's device."
},
copyToClipboard () {
Promise.resolve()
.then(() => w.clipboard.writeText(this.selectedVersion.fileSnippet))
.then(() => (this.copyStatus = 'success'))
.catch(() => (this.copyStatus = 'failed'))
setTimeout(() => (this.copyStatus = null), 1000)
}
},
watch: {
preferedColorScheme (/** @type {Theme} */ nextScheme) {
externalElements.update(this.versionOptions, nextScheme)
},
versionOptions: {
deep: true,
handler (/** @type {VersionOptions} */ nextOptions) {
externalElements.update(nextOptions, this.preferedColorScheme)
}
}
}
})
// /** Reference to global window, but with properties for loaded libraries. */
// const w = /** @type {Window & Libraries} */ (window)
// const queryParams = new URLSearchParams(w.location.search)
// const supportsCssVars = typeof CSS !== 'undefined' && CSS.supports('color', 'var(--clr)')
// /** The base URI from where the docs page loads the CSS files. */
// const DEV_BASE = './water.css/'
// /** The base URI from where instructions show to load the CSS files. */
// const CDN_BASE = 'https://cdn.jsdelivr.net/npm/water.css@2/dist/'
// /** An object mapping the (minified + gzipped) fileSize in KB to a fileName. */
// const FILE_SIZES = {
// 'dark.min.css': 1.4,
// 'dark.standalone.min.css': 1.31,
// 'dark-legacy.min.css': 0.177 + 1.16 + 1.15,
// 'dark-legacy.standalone.min.css': 1.16,
// 'light.min.css': 1.4,
// 'light.standalone.min.css': 1.3,
// 'light-legacy.min.css': 0.178 + 1.16 + 1.15,
// 'light-legacy.standalone.min.css': 1.15
// }
// /** 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`)
// }
// /** 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 })
// return `
// <!-- Preload the required stylesheets (optional) -->
// <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})">`
// }
// /** 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 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 = {
// _productHunt: /** @type {HTMLImageElement} */ (document.querySelector('#js-producthunt')),
// _stylesheet: /** @type {HTMLLinkElement} */ (document.querySelector('#js-stylesheet')),
// _removeStartupStylesheet: () => {
// const startupStylesheet = document.head.querySelector('#js-startup-stylesheet')
// if (startupStylesheet) document.head.removeChild(startupStylesheet)
// externalElements._stylesheet.removeEventListener('load', externalElements._removeStartupStylesheet)
// },
// _updateProductHunt: (/** @type {Theme} */ theme) => {
// externalElements._productHunt.src = externalElements._productHunt.src.replace(/dark|light/, theme)
// },
// _updateStylesheet: (/** @type {FileName} */ fileName) => {
// externalElements._stylesheet.href = DEV_BASE + fileName
// },
// /** Sets up listener to remove startup version of water.css when right one loads, then updates */
// init: (/** @type {VersionOptions} */ options, /** @type {?Theme} */ preferedTheme) => {
// externalElements._stylesheet.addEventListener('load', externalElements._removeStartupStylesheet)
// externalElements.update(options, preferedTheme)
// },
// /** 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
// externalElements._updateStylesheet(getFileName(options))
// externalElements._updateProductHunt(displayedTheme)
// }
// }
// /**
// * 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)
// }
// const themeFromParams = queryParams.get('theme')
// /** @type {VersionOptions} */
// const initialVersionOptions = {
// theme: themeFromParams === 'dark' || themeFromParams === 'light' ? themeFromParams : 'dark',
// isLegacy: queryParams.has('legacy') || !supportsCssVars,
// isStandalone: queryParams.has('standalone')
// }
// new w.Vue({ // eslint-disable-line no-new
// el: '#installation',
// filters: {
// capitalize: (/** @type {string} */ str) => str.charAt(0).toUpperCase() + str.slice(1)
// },
// /** @type {VueData} */
// data: {
// versionOptions: initialVersionOptions,
// preferedColorScheme: null,
// copyStatus: null
// },
// computed: {
// /** @returns {boolean} */
// isOverwritten () {
// const { isStandalone, theme } = this.versionOptions
// if (isStandalone || !this.preferedColorScheme) return false
// return theme !== this.preferedColorScheme
// },
// /** @returns {{ fileName: string, fileSize: string, fileSnippet: string }} */
// selectedVersion () {
// return {
// fileName: getFileName(this.versionOptions),
// fileSize: getFileSize(this.versionOptions).toFixed(2),
// fileSnippet: getFileSnippet(this.versionOptions)
// }
// }
// },
// created () {
// createColorSchemeListener('dark', (match) => match && (this.preferedColorScheme = 'dark'))
// createColorSchemeListener('light', (match) => match && (this.preferedColorScheme = 'light'))
// externalElements.init(this.versionOptions, this.preferedColorScheme)
// },
// methods: {
// getTooltipMessage (/** @type {Theme} */ theme) {
// if (this.versionOptions.theme === theme && this.isOverwritten) {
// return 'Your theme selection is currently overwritten by the theme setting on your device.'
// } else return "Selected theme can be overwritten by theme setting on user's device."
// },
// copyToClipboard () {
// Promise.resolve()
// .then(() => w.clipboard.writeText(this.selectedVersion.fileSnippet))
// .then(() => (this.copyStatus = 'success'))
// .catch(() => (this.copyStatus = 'failed'))
// setTimeout(() => (this.copyStatus = null), 1000)
// }
// },
// watch: {
// preferedColorScheme (/** @type {Theme} */ nextScheme) {
// externalElements.update(this.versionOptions, nextScheme)
// },
// versionOptions: {
// deep: true,
// handler (/** @type {VersionOptions} */ nextOptions) {
// externalElements.update(nextOptions, this.preferedColorScheme)
// }
// }
// }
// })

View File

@ -10,61 +10,33 @@ html {
overflow: hidden;
}
.version-select__snippet h3 {
.version-select-snippet h3 {
margin: 1rem 2.5rem 1rem 0;
}
/* Make the ✔ / ❌ Emoji appear next to the button */
.version-select__snippet__btn {
#copy-snippet {
position: relative;
margin: 0 2px 0 auto;
margin-right: 2px;
overflow: visible;
}
.version-select__snippet__btn span {
#copy-snippet span {
position: absolute;
left: -2rem;
display: inline-block;
transform: scale(1.3);
}
.version-select__options > label {
white-space: pre;
}
.version-select__options > label:not(:last-of-type) {
#theme-form > label:not(:last-of-type) {
margin-right: 1rem;
}
.version-select__options__additional,
.version-select__options__additional > *:not(summary) {
display: block;
margin: 1rem 0;
}
.version-select__options__additional summary {
outline: none;
cursor: pointer;
font-weight: 600;
}
.version-select__options__additional summary:hover span,
.version-select__options__additional summary:focus span {
text-decoration: underline;
}
.version-select__info caption {
text-align: left;
}
.version-select__info th {
border: none;
vertical-align: top;
#version-info th {
width: 35%;
}
body > footer {
padding-top: 2rem;
display: flex;
justify-content: flex-end;
align-items: flex-end;
@ -96,45 +68,3 @@ body > footer {
Helvetica Neue,
sans-serif;
}
.opacity-4 {
opacity: 0.4;
}
.opacity-7 {
opacity: 0.76;
}
.tooltip {
position: relative;
cursor: help;
}
.tooltip::after {
content: '';
position: absolute;
left: 0;
bottom: -4px;
width: 100%;
border-width: 0 0 1.5px;
border-style: dotted;
}
/* For the bounce transitions of code snippet and copy success Emoji */
.v-enter,
.v-leave-to {
transform: scale(0) !important;
}
.v-enter-active,
.v-leave-active {
transition: transform 220ms cubic-bezier(0.175, 0.885, 0.32, 1.275);
}
[v-cloak] > * {
display: none;
}
[v-cloak]::after {
content: 'Version picker is loading...';
}