Merge pull request #483 from jpudysz/docs/beta-5

docs: beta 5
jpudysz · Jan 20, 2025 · 65fac6e · 65fac6e
2 parents ef67633 + b709b4d
commit 65fac6e
Show file tree

Hide file tree

Showing 28 changed files with 1,240 additions and 324 deletions.
diff --git a/README.md b/README.md
@@ -59,12 +59,12 @@ Then follow [installation guides](https://unistyl.es/v3/start/getting-started) f
 <a href="https://github.com/happyfloat">
      <img src="https://avatars.githubusercontent.com/u/186333704?s=200&v=4" height="70px" width="70px" alt="happyfloat" />
 </a>
-<a href="https://github.com/hyoban">
-     <img src="https://avatars.githubusercontent.com/u/38493346?v=4" height="70px" width="70px" alt="hyoban" />
-</a>
 <a href="https://github.com/oscklm">
      <img src="https://avatars.githubusercontent.com/u/22825865?v=4" height="70px" width="70px" alt="oscklm" />
 </a>
+<a href="https://github.com/giovannilondero">
+     <img src="https://avatars.githubusercontent.com/u/10998991?v=4" height="70px" width="70px" alt="giovannilondero" />
+</a>
 
 ## Past sponsors
 
@@ -86,6 +86,9 @@ Then follow [installation guides](https://unistyl.es/v3/start/getting-started) f
 <a href="https://github.com/abanobboles">
      <img src="https://avatars.githubusercontent.com/u/9078953?v=4" height="70px" width="70px" alt="abanobboles" />
 </a>
+<a href="https://github.com/hyoban">
+     <img src="https://avatars.githubusercontent.com/u/38493346?v=4" height="70px" width="70px" alt="hyoban" />
+</a>
 
 ## Sponsor my work
 

diff --git a/cxx/core/HostUnistyle.cpp b/cxx/core/HostUnistyle.cpp
@@ -53,13 +53,13 @@ void HostUnistyle::set(jsi::Runtime& rt, const jsi::PropNameID& propNameId, cons
 
 jsi::Function HostUnistyle::createAddVariantsProxyFunction(jsi::Runtime& rt) {
     auto useVariantsFnName = jsi::PropNameID::forUtf8(rt, helpers::ADD_VARIANTS_FN);
-    auto parser = parser::Parser(this->_unistylesRuntime);
 
-    return jsi::Function::createFromHostFunction(rt, useVariantsFnName, 1, [this, &parser](jsi::Runtime &rt, const jsi::Value &thisVal, const jsi::Value *arguments, size_t count){
+    return jsi::Function::createFromHostFunction(rt, useVariantsFnName, 1, [this](jsi::Runtime &rt, const jsi::Value &thisVal, const jsi::Value *arguments, size_t count){
         helpers::assertThat(rt, count == 1, "Unistyles: useVariants expected to be called with one argument.");
         helpers::assertThat(rt, arguments[0].isObject(), "Unistyles: useVariants expected to be called with object.");
 
         Variants variants = helpers::variantsToPairs(rt, arguments[0].asObject(rt));
+        parser::Parser parser = parser::Parser(this->_unistylesRuntime);
 
         helpers::enumerateJSIObject(rt, thisVal.asObject(rt), [this, &parser, &rt, &variants](const std::string& name, jsi::Value& value){
             if (name == helpers::ADD_VARIANTS_FN || !this->_stylesheet->unistyles.contains(name)) {

diff --git a/cxx/hybridObjects/HybridStyleSheet.cpp b/cxx/hybridObjects/HybridStyleSheet.cpp
@@ -77,13 +77,19 @@ jsi::Value HybridStyleSheet::configure(jsi::Runtime &rt, const jsi::Value &thisV
 }
 
 jsi::Value HybridStyleSheet::init(jsi::Runtime &rt, const jsi::Value &thisVal, const jsi::Value *arguments, size_t count) {
+    if (this->isInitialized) {
+        return jsi::Value::undefined();
+    }
+
     // create new state
     auto& registry = core::UnistylesRegistry::get();
 
     registry.createState(rt);
 
     loadExternalMethods(thisVal, rt);
     registerHooks(rt);
+
+    this->isInitialized = true;
 
     return jsi::Value::undefined();
 }

diff --git a/cxx/hybridObjects/HybridStyleSheet.h b/cxx/hybridObjects/HybridStyleSheet.h
@@ -73,6 +73,7 @@ struct HybridStyleSheet: public HybridUnistylesStyleSheetSpec {
     void onImeChange(UnistylesNativeMiniRuntime miniRuntime);
     void notifyJSListeners(std::vector<UnistyleDependency>& dependencies);
 
+    bool isInitialized = false;
     double __unid = -1;
     std::vector<std::unique_ptr<const std::function<void(std::vector<UnistyleDependency>&)>>> _changeListeners{};
     std::shared_ptr<HybridUnistylesRuntime> _unistylesRuntime;

diff --git a/docs/.astro/settings.json b/docs/.astro/settings.json
@@ -1,5 +1,5 @@
 {
 	"_variables": {
-		"lastUpdateCheck": 1733737796859
+		"lastUpdateCheck": 1737126711469
 	}
 }
diff --git a/docs/.astro/types.d.ts b/docs/.astro/types.d.ts
@@ -1,2 +1,2 @@
 /// <reference types="astro/client" />
-/// <reference path="astro/content.d.ts" />
+/// <reference path="content.d.ts" />
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -82,11 +82,12 @@ export default defineConfig({
                 {
                     label: 'Guides',
                     items: [
+                        { label: 'Merging styles', slug: 'v3/guides/merging-styles', badge: 'New!' },
                         { label: 'Theming', slug: 'v3/guides/theming' },
                         { label: 'Avoiding Keyboard', slug: 'v3/guides/avoiding-keyboard' },
                         { label: 'Expo Router', slug: 'v3/guides/expo-router' },
                         { label: 'Custom web', slug: 'v3/guides/custom-web', badge: 'WIP' },
-                        { label: 'Server side rendering', slug: 'v3/guides/server-side-rendering', badge: 'WIP' },
+                        { label: 'Server side rendering', slug: 'v3/guides/server-side-rendering', badge: 'New!' },
                     ]
                 },
                 {
@@ -101,9 +102,11 @@ 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 Only Features', slug: 'v3/references/web-only' },
-                        { label: 'Scoped theme', slug: 'v3/references/scoped-theme', badge: 'New!' },
-                        { label: 'withUnistyles', slug: 'v3/references/with-unistyles',  badge: 'New!' },
+                        { label: 'Web Only Features', slug: 'v3/references/web-only', badge: 'Updated' },
+                        { label: 'Scoped theme', slug: 'v3/references/scoped-theme' },
+                        { label: 'Update 3rd party views', slug: 'v3/references/3rd-party-views', badge: 'New!' },
+                        { label: 'withUnistyles', slug: 'v3/references/with-unistyles' },
+                        { label: 'useUnistyles', slug: 'v3/references/use-unistyles', badge: 'New!' },
                         { label: 'Display and Hide', slug: 'v3/references/display-hide' },
                         { label: 'Edge to edge', slug: 'v3/references/edge-to-edge' },
                         { label: 'Dimensions', slug: 'v3/references/dimensions' },
@@ -114,7 +117,7 @@ export default defineConfig({
                     label: 'Other',
                     items: [
                         { label: 'How to report a bug?', slug: 'v3/other/how-to-report-bug' },
-                        { label: 'Babel plugin', slug: 'v3/other/babel-plugin' },
+                        { label: 'Babel plugin', slug: 'v3/other/babel-plugin', badge: 'Updated' },
                         { label: 'Dependencies', slug: 'v3/other/dependencies' },
                         { label: 'For library authors', slug: 'v3/other/for-library-authors' },
                         { label: 'For sponsors', slug: 'v3/other/for-sponsors' },

diff --git a/docs/package.json b/docs/package.json
@@ -12,9 +12,9 @@
   "dependencies": {
     "@astrojs/check": "0.9.4",
     "@astrojs/sitemap": "3.2.1",
-    "@astrojs/starlight": "0.29.2",
-    "@fontsource-variable/nunito": "5.1.0",
-    "astro": "4.16.13",
+    "@astrojs/starlight": "0.30.5",
+    "@fontsource-variable/nunito": "5.1.1",
+    "astro": "5.1.4",
     "astro-expressive-code": "0.38.3",
     "astro-seo": "0.8.4",
     "autoprefixer": "10.4.20",

diff --git a/docs/src/content/docs/v3/guides/merging-styles.mdx b/docs/src/content/docs/v3/guides/merging-styles.mdx
@@ -0,0 +1,68 @@
+---
+title: Merging styles
+description: Learn about how to merge styles with Unistyles 3.0
+---
+
+import { Card, Aside } from '@astrojs/starlight/components'
+import Seo from '../../../../components/Seo.astro'
+
+<Seo
+    seo={{
+        title: 'Merging unistyles',
+        description: 'Learn about how to merge styles with Unistyles 3.0'
+    }}
+>
+
+While using Unistyles, it's crucial to understand how styles need to be merged and why it is so important.
+
+### Introduction
+
+In the early versions of Unistyles 3.0, we tried to solve this issue with a Babel plugin. However, it was too complex to maintain various edge cases (especially with `Pressable`), and developers frequently encountered many `Unistyles: Style is not bound!` errors.
+
+With the new approach, we shift the responsibility of merging styles to the user. In other words, the Babel plugin will no longer convert your style tags from objects to arrays.
+
+### How to merge multiple styles
+
+Unistyles doesn't provide any extra API for merging styles. Instead, we encourage you to use the `[]` syntax supported by React Native components.
+
+```tsx
+<View style={[styles.container, styles.container2]} />
+```
+
+If Unistyles detects that you've used the spread operator and the styles have no attached C++ state, it will:
+- Restore the state on the C++ side
+- Merge styles in an unpredictable order (as we lose order information)
+- Warn you in `__DEV__` mode about this
+
+<Aside title="Example error" type="caution">
+Unistyles: We detected a style object with 2 Unistyles styles. This might cause no updates or unpredictable behavior. Please check the `style` prop for `View` and use array syntax instead of object syntax.
+</Aside>
+
+When you see this warning, your component will render correctly, but any new event that re-computes your styles could:
+- Output incorrect styles due to the unknown order of merging
+- Not update at all if, during the merging process, you altered props that were previously listening for changes
+
+It's critical to ship Unistyles 3.0 apps without this warning, as it can cause unexpected behavior.
+
+### Spreading a single Unistyle
+
+Another problematic case is spreading a single Unistyle and merging it, e.g., with inline styles:
+
+```tsx
+<View style={{...styles.container, ...{ backgroundColor: 'red' }}} />
+```
+
+Although we can restore the C++ state for `styles.container`, we cannot identify that `backgroundColor: red` should override the `backgroundColor` used in `styles.container`. The order of merging will be preserved until the first re-computation of styles.
+
+Also, keep in mind that restoring the C++ state takes unnecessary extra time, so it's better to avoid it.
+
+### Summary
+
+- Use the `[]` syntax to merge styles
+- Avoid spreading Unistyles
+- Avoid merging your styles with the spread operator
+- Unistyles will warn you about this in `__DEV__` mode
+
+With this new approach, you're in control of merging your styles.
+
+</Seo>
diff --git a/docs/src/content/docs/v3/guides/server-side-rendering.mdx b/docs/src/content/docs/v3/guides/server-side-rendering.mdx
@@ -3,7 +3,7 @@ title: SSR
 description: Learn about SSR with Unistyles 3.0
 ---
 
-import { Card } from '@astrojs/starlight/components'
+import { Card, Aside } from '@astrojs/starlight/components'
 import Seo from '../../../../components/Seo.astro'
 
 <Seo
@@ -13,6 +13,55 @@ import Seo from '../../../../components/Seo.astro'
     }}
 >
 
-🚧 Work is progress. Guide will be released soon.
+Unistyles 3.0 is fully compatible with Next.js Server Side Rendering (SSR). We're supporting both client and server components.
 
+### Usage
+
+To use server-side rendered styles, create following **client side** component:
+
+```tsx title="Style.tsx" /useServerUnistyles/ /useServerInsertedHTML/ /'use client'/
+'use client'
+
+import { PropsWithChildren } from 'react'
+import { useServerUnistyles } from 'react-native-unistyles/server'
+import { useServerInsertedHTML } from 'next/navigation'
+import './unistyles'
+
+export const Style = ({ children }: PropsWithChildren) => {
+    const unistyles = useServerUnistyles()
+
+    useServerInsertedHTML(() => unistyles)
+
+    return <>{children}</>
+}
+```
+
+With the component in place, make sure it wraps your body's children:
+
+```diff lang="tsx" title="layout.tsx"
++ import '../unistyles'
++ import { Style } from '../Style'
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>
++        <Style>
+            {children}
++        </Style>
+      </body>
+    </html>
+  );
+}
+```
+
+<Aside>
+The `unistyles.ts` file is where Unistyles is configured. For more details, refer to the [configuration guide](/v3/start/configuration).
+</Aside>
+
+With this setup, we will ensure that Unistyles is initialized correctly and injects CSS on the server side.
 </Seo>
diff --git a/docs/src/content/docs/v3/guides/theming.mdx b/docs/src/content/docs/v3/guides/theming.mdx
@@ -129,6 +129,26 @@ const styles = StyleSheet.create(theme => ({
 }))
 ```
 
+Other, discouraged way is to access it in the hook `useUnistyles`:
+
+```tsx /useUnistyles/
+import { useUnistyles } from 'react-native-unistyles'
+
+const MyComponent = () => {
+    const { theme } = useUnistyles()
+
+    return (
+        <Text>
+            My theme is {theme.colors.primary}
+        </Text>
+    )
+}
+```
+
+:::caution
+`useUnistyles` is not recommended as it will re-render your component on every change of the theme
+:::
+
 ### Get the current theme name
 
 To get the current theme name, import `UnistylesRuntime`: