feat(docs): Dark mode docs (Style section and Dark Plugin)

Author: rstoenescu

docs/src/assets/menu.js

@@ -486,6 +486,11 @@ const style = [
     badge: 'new',
     path: 'theme-builder'
   },
+  {
+    name: 'Dark Mode',
+    badge: 'new',
+    path: 'dark-mode'
+  },
   {
     name: 'Spacing',
     path: 'spacing'
@@ -655,6 +660,11 @@ const plugins = [
     name: 'Cookies',
     path: 'cookies'
   },
+  {
+    name: 'Dark',
+    path: 'dark',
+    badge: 'new'
+  },
   {
     name: 'Dialog',
     path: 'dialog'

docs/src/pages/quasar-plugins/app-fullscreen.md

@@ -48,7 +48,7 @@ On some phones this will have little effect:
 It all depends on the Web Fullscreen API support of the platform the code is running on.
 :::
 
-### Watching for fullscreen changes
+## Watching for fullscreen changes
 
 ``` vue
 <template>...</template>

docs/src/pages/quasar-plugins/app-visibility.md

@@ -20,5 +20,21 @@ import { AppVisibility } from 'quasar'
 
 <doc-example title="AppVisibility" file="AppVisibility/Basic" />
 
+## Watching for status change
+
+``` vue
+<template>...</template>
+
+<script>
+export default {
+  watch: {
+    '$q.appVisibile' (val) {
+      console.log(val ? 'App became visible' : 'App went in the background')
+    }
+  }
+}
+</script>
+```
+
 ## AppVisibility API
 <doc-api file="AppVisibility" />

docs/src/pages/quasar-plugins/dark.md

@@ -0,0 +1,88 @@
+---
+title: Dark Plugin
+desc: A Quasar plugin to toggle or configure the Dark Mode state of your app.
+badge: v1.3+
+---
+
+::: tip
+For a better understanding of this Quasar plugin, please head to the Style & Identity [Dark Mode](/style/dark-mode) page.
+:::
+
+## Installation
+This plugin is automatically installed. No need to do anything but directly use it.
+
+## Usage
+
+### Inside of a Vue file
+
+``` js
+// get status
+console.log(this.$q.dark.isActive)
+
+// set status
+this.$q.dark.set(true) // or "false" or "auto"
+```
+
+On a **SSR build**, you can set this from a `created` hook from your `/src/App.vue`:
+
+```
+export default {
+  // ...
+
+  created () {
+    this.$q.dark.set(true)
+  }
+}
+```
+
+### Outside of a Vue file
+
+``` js
+// Warning! This method will not
+// work on SSR builds.
+
+import { Dark } from 'quasar'
+
+// get status
+console.log(Dark.isActive)
+
+// set status
+Dark.set(true) // or "false" or "auto"
+```
+
+### Through quasar.conf.js
+
+You can also use `/quasar.conf.js` to set the Dark mode status:
+
+```js
+framework: {
+  config: {
+    dark: 'auto' // or Boolean true/false
+  }
+}
+```
+
+## Note about SSR
+
+When on a SSR build:
+* `import { Dark } from 'quasar'` method of using Dark mode will not error out but it will not work (won't do anything). But you can use the other two ways (see previous section). We recommend through quasar.conf.js.
+* It's preferred to avoid setting Dark mode to 'auto' for SSR builds. It's because the client dark mode preference cannot be inferred, so SSR will always render in light mode then when the client takes over, it will switch to Dark (if it will be the case). As a result, a quick flicker of the screen will occur.
+
+## Watching for status change
+
+``` vue
+<template>...</template>
+
+<script>
+export default {
+  watch: {
+    '$q.dark.isActive' (val) {
+      console.log(val ? 'On dark mode' : 'On light mode')
+    }
+  }
+}
+</script>
+```
+
+## Dark API
+<doc-api file="Dark" />

docs/src/pages/style/dark-mode.md

@@ -0,0 +1,37 @@
+---
+title: Dark Mode
+desc: Handle dark mode with Quasar.
+badge: v1.3+
+---
+
+Dark Mode is a supplemental mode that can be used to display mostly dark surfaces on the UI. The design reduces the light emitted by device screens while maintaining the minimum color contrast ratios required for readability.
+
+The advantages of Dark Mode are that:
+* it enhances visual ergonomics by reducing eye strain.
+* Provides comfort of use at night or in dark environments.
+* It conserves battery power mainly if the device screen is OLED or AMOLED, thereby enabling device usage for longer periods without charging.
+
+## What it does
+
+1. It sets a default dark background for the pages (that you can easily override through CSS with the `body.body--dark` selector)
+2. All Quasar components with a `dark` property will have it automatically set to `true`. No need to do it manually.
+
+The auto-detection works by looking at `prefers-color-scheme: dark` media query and it's dynamic. If the client browser/platform switches to/from Dark mode while your app is running, it will also update Quasar's Dark mode (if Dark mode is set to `auto`).
+
+## How to use it
+
+You can easily switch between Dark mode and light mode (which is default) through the [Dark Plugin](/quasar-plugins/dark).
+
+## How to style your app
+
+Since your app can be in Dark mode or not, you can easily style it by taking advantage of the `body` tag attached CSS class: `body--light` or `body--dark`. That is if you want to support both modes.
+
+```css
+.body--light {
+  /* ... */
+}
+
+.body--dark {
+  /* ... */
+}
+```

ui/src/plugins/Dark.json

@@ -0,0 +1,25 @@
+{
+  "injection": "$q.dark",
+
+  "props": {
+    "isActive": {
+      "type": "Boolean",
+      "desc": "Is Dark mode active?",
+      "reactive": true
+    }
+  },
+
+  "methods": {
+    "set": {
+      "desc": "Set dark mode status",
+      "params": {
+        "status": {
+          "type": [ "Boolean", "String" ],
+          "desc": "Dark mode status",
+          "values": [ true, false, "auto" ],
+          "required": true
+        }
+      }
+    }
+  }
+}