Merge pull request #357 from jpudysz/milestone/3.0-web-docs

docs: web docs

docs/astro.config.mjs

@@ -96,7 +96,7 @@ export default defineConfig({
                         { label: 'Variants', slug: 'v3/references/variants' },
                         { label: 'Compound Variants', slug: 'v3/references/compound-variants' },
                         { label: 'Web styles', slug: 'v3/references/web-styles' },
-                        { label: 'Web classes', slug: 'v3/references/web-classes' },
+                        { label: 'Web Only Features', slug: 'v3/references/web-only' },
                     ]
                 },
                 {

docs/src/content/docs/v3/references/web-only.mdx

@@ -0,0 +1,122 @@
+---
+title: Web Only Features
+description: Learn about web only features in Unistyles 3.0
+---
+
+Unistyles comes with some web only features which are not available on React Native side.
+
+- [Web only styles](#web-styles)
+- [Pseudo selectors and elements](#pseudo-elements)
+- [Injecting custom classNames](#injecting-custom-classnames)
+
+## Web Styles
+
+In Unistyles you can use web specific styles for your web app under `_web` key.
+
+```ts
+const styles = StyleSheet.create({
+   container: {
+    flex: 1,
+    // Web only styles:
+    _web: {
+      display: 'grid',
+    }
+   }
+})
+```
+
+Under `_web` key you can pass any valid CSS Property and value that matches `CSSProperties` type from React.
+
+Keep in mind that under `_web` you can't use React Native specific styles.
+
+```ts
+const styles = StyleSheet.create({
+   container: {
+    flex: 1,
+    _web: {
+      display: 'grid',
+      // Error:
+      transform: [{ translateX: 10 }],
+   }
+})
+```
+
+`transform` property on the web should be a string:
+
+```diff lang="ts"
+const styles = StyleSheet.create({
+   container: {
+    flex: 1,
+    _web: {
+      display: 'grid',
+      // Error:
+-      transform: [{ translateX: 10 }],
++      transform: 'translateX(10px)',
+   }
+})
+```
+
+You can also use variants, breakpoints and other Unistyles features under the `_web` key!
+
+## Pseudo elements
+
+Unistyles also introduces you with a way to use pseudo elements and selectors in your web styles.
+
+```ts
+const styles = StyleSheet.create(theme => ({
+   button: {
+    backgroundColor: theme.colors.button,
+    _web: {
+      _hover: {
+        backgroundColor: theme.colors.hovered,
+      },
+      _before: {
+        content: '"🦄"',
+      }
+    }
+   },
+}))
+```
+
+Every pseudo element and selector is included under the `_web` key. As you can see `:` & `::` were replaced with `_` for easier usage.
+
+## Injecting custom classNames
+
+If you want to write some part of your app with plain CSS you can add custom classNames to your styles.
+
+```ts
+const styles = StyleSheet.create({
+   container: {
+    flex: 1,
+    _web: {
+      _classNames: 'my-custom-class',
+    }
+   }
+})
+```
+
+`_classNames` key under the `_web` key will be injected to the DOM element as a className. You can pass string or array of strings into it.
+
+```diff lang="ts"
+const styles = StyleSheet.create({
+   container: {
+    flex: 1,
+    _web: {
+-      _classNames: 'my-custom-class',
++      _classNames: ['my-custom-class', 'my-other-class'],
+    }
+   }
+})
+```
+
+Or pass them conditionally with dynamic functions:
+
+```ts
+const styles = StyleSheet.create({
+   button: (isPrimary: boolean) => ({
+    _web: {
+        _classNames: isPrimary ? 'primary-button' : 'secondary-button',
+    }
+   })
+})
+```

docs/src/content/docs/v3/references/web-styles.mdx

@@ -3,4 +3,100 @@ title: Web styles
 description: Learn about web styles in Unistyles 3.0
 ---
 
-import { Card } from '@astrojs/starlight/components'
+We've made Unistyles web completely undependent from React Native Web by creating our custom web parser which generates CSS from your StyleSheet's.
+
+## How it works
+
+The web parser generates classNames based on your config and assigns them to the given DOM element. This results in zero redundant styles!
+
+In addition we're generating media queries based on provided `breakpoints` instead of recalculating them on every app's resize.
+
+```ts
+const styles = StyleSheet.create({
+   container: {
+    flex: 1,
+   },
+   text: {
+    fontSize: {
+        xs: 28,
+        lg: 40
+    },
+   },
+   parentContainer: {
+    flex: 1,
+   }
+})
+```
+
+```css
+.unistyles-1u0egm6 {
+  flex: 1;
+}
+
+@media (min-width: 0px) {
+  .unistyles-kaoph5 {
+    font-size: 32px;
+  }
+}
+
+@media (min-width: 1200px) {
+  .unistyles-kaoph5 {
+    font-size: 40px;
+  }
+}
+```
+
+## Updating styles
+
+When your changing your app's theme Unistyles will simply update your CSS without any re-render, the same goes for dynamic functions & variants.
+
+```ts
+const styles = StyleSheet.create(theme => ({
+    container: {
+        flex: 1,
+        backgroundColor: theme.colors.background
+    }
+}))
+```
+
+```css
+.unistyles-1u0egm6 {
+  flex: 1;
+  background-color: #000;
+}
+```
+
+Now let's update theme to a light one:
+
+```ts
+UnistylesRuntime.setTheme('light')
+```
+
+And voila, the CSS is now updated:
+
+```css
+.unistyles-1u0egm6 {
+  flex: 1;
+  background-color: #fff;
+}
+```
+
+## Limitations
+
+Because we're using the custom parser we can't return your styles directly since React Native Web will parse them in that case.
+Keep that in mind when using `StyleSheet.create` in your web app.
+
+```ts
+const styles = StyleSheet.create({
+    container: {
+        flex: 1
+    }
+})
+
+// Will result in an empty object, because we build classes instead of inline styles
+console.log(styles) // {}
+```
+
+## Web Only Features
+
+Unistyles also provides you with some web only features, read more about them [here](/v3/references/web-only).

docs/src/styles/docs.css

@@ -25,11 +25,11 @@
     color: var(--white);
 }
 
-a[aria-current="page"] {
+a[aria-current="page"], a[aria-current="page"]:hover {
     background-color: rgba(255, 255, 255, 0.05);
     border: 1px solid rgba(255, 255, 255, 0.2);
     border-radius: 8px;
-    color: var(--sl-color-accent);
+    color: var(--sl-color-accent)!important;
 }
 
 a[aria-current="page"]:hover {
@@ -68,7 +68,7 @@ figcaption.header {
     border-bottom: 1px solid var(--border)!important;
 }
 
-.top-level > li > details > ul > li {
+.top-level > li > details > ul > li:nth-child(1) {
     padding-top: 16px;
 }