Skip to content

Commit

Permalink
working on useObserver docs
Browse files Browse the repository at this point in the history
  • Loading branch information
shahabyazdi committed May 12, 2023
1 parent 1807b1b commit 5897a8d
Show file tree
Hide file tree
Showing 9 changed files with 340 additions and 18 deletions.
1 change: 1 addition & 0 deletions apps/website/src/components/examples/modals.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ function Modal({ title, body, id }) {
top: '50%',
transform: 'translate(-50%, -50%)',
borderRadius: '7px',
zIndex: 1,
}}
>
<div
Expand Down
62 changes: 62 additions & 0 deletions apps/website/src/components/examples/use_observer.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
import { useObserver, Observer } from 'rosma';

const observer = new Observer({ foo: 'bar', num1: 0, num2: 0 });

export function Example1() {
const { foo, setFoo } = useObserver(observer);

return (
<div>
<p>Foo: {foo}</p>
<button onClick={() => setFoo(foo === 'bar' ? 'baz' : 'bar')}>
Toggle Foo
</button>
</div>
);
}

export function Example2() {
const { foo, setFoo } = useObserver(observer);

return (
<div>
<p>Foo: {foo}</p>
<button onClick={() => setFoo((foo) => (foo === 'bar' ? 'baz' : 'bar'))}>
Toggle Foo
</button>
</div>
);
}

export function Example3() {
const { firstName, lastName, set } = useObserver(observer);

return (
<div>
<p>
Full Name: {firstName} {lastName}
</p>
<button onClick={() => set({ firstName: 'John', lastName: 'Doe' })}>
Set full name
</button>
</div>
);
}

export function Example4() {
const { num1, num2, set } = useObserver(observer);

return (
<div>
<p>num1:{num1}</p>
<p>num2:{num2}</p>
<button
onClick={() =>
set(({ num1, num2 }) => ({ num1: num1 + 1, num2: num2 + 1 }))
}
>
increment
</button>
</div>
);
}
1 change: 1 addition & 0 deletions apps/website/src/components/sidebar/data.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ export const sidebar = [
{ name: 'Usage', path: '/usage' },
{ name: 'Multiple destructuring', path: '/multiple-destructuring' },
{ name: 'Different initial values', path: '/different-initial-values' },
{ name: 'useObserver hook', path: '/use-observer' },
{ name: 'Observer', path: '/observer' },
{ name: 'Multiple observers', path: '/multiple-observers' },
{ name: 'Subscribe for state changes', path: '/subscribe' },
Expand Down
117 changes: 117 additions & 0 deletions apps/website/src/docs/use-observer.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
import {
Example1,
Example2,
Example3,
Example4,
} from '@/components/examples/use_observer';

export const meta = {
keywords: 'useObserver.keywords',
};

# useObserver

useObserver.description

```js
import { useObserver } from 'rosma';

export default function Example() {
const { foo, setFoo } = useObserver('bar');

return (
<div>
<p>Foo: {foo}</p>
<button onClick={() => setFoo(foo === 'bar' ? 'baz' : 'bar')}>
Toggle Foo
</button>
</div>
);
}
```

<Example1 />

useObserver.explain

## Get the previous value from the setter

useObserver.previousValue.description

```js
import { useObserver } from 'rosma';

export default function Example() {
const { foo, setFoo } = useObserver('bar');

return (
<div>
<p>Foo: {foo}</p>
<button
onClick={() => setFoo((prevFoo) => (prevFoo === 'bar' ? 'baz' : 'bar'))}
>
Toggle Foo
</button>
</div>
);
}
```

<Example2 />

useObserver.previousValue.explain

## Set multiple values at same time

useObserver.multipleValues.description

```js
export function Example() {
const { firstName, lastName, set } = useObserver('');

return (
<div>
<p>
Full Name: {firstName} {lastName}
</p>
<button onClick={() => set({ firstName: 'John', lastName: 'Doe' })}>
Set full name
</button>
</div>
);
}
```

<Example3 />

useObserver.multipleValues.explain

## Passing function to `set` as parameter

useObserver.setFunction.description

```js
export function Example4() {
const { num1, num2, set } = useObserver(0);

return (
<div>
<p>num1: {num1}</p>
<p>num2: {num2}</p>
<button
onClick={() =>
set(({ num1, num2 }) => ({ num1: num1 + 1, num2: num2 + 1 }))
}
>
increment
</button>
</div>
);
}
```

useObserver.setFunction.explain

<Example4 />

**Keywords**: useObserver.keywords
4 changes: 4 additions & 0 deletions apps/website/src/docs/with-state.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ import Counter, {
CountNumber,
} from '@/components/examples/with_state';

export const meta = {
keywords: 'withState.keywords',
};

# withState

withState.description
Expand Down
59 changes: 59 additions & 0 deletions apps/website/src/locales/en/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -347,5 +347,64 @@
"setNumber"
]
]
},
"useObserver": {
"description": [
"`useObserver` is a React hook that allows you to observe changes to state variables and trigger a re-render of your component when those variables change.",
"When you use useObserver, you can provide an initial value for a variable, and that variable will be added to the global state. If the variable already exists in the state, useObserver will return the existing value.",
"In addition to the value of the variable, useObserver also provides a setter function that you can use to update the value of the variable. When you call the setter function, useObserver will update the state with the new value and trigger a re-render of your component.",
"Here's an example of how to use useObserver:"
],
"explain": [
"In this example, useObserver is used to create a variable named `foo` with an initial value of `bar`. The `setFoo` function is used to update the value of foo whenever the `Toggle Foo` button is clicked.",
"By using `useObserver`, the component will automatically re-render whenever the value of foo changes, ensuring that the UI stays in sync with the state."
],
"previousValue": {
"description": [
"In some cases, we may need to reference the previous value of a state variable when setting a new value. To achieve this, we can pass a function to the setter function returned by `useObserver`, which will receive the previous value as an argument.",
"Here's an example of how to use a function to set a new value based on the previous value:"
],
"explain": [
"In this example, we use the `setFoo` function to set the value of `foo` based on its previous value. The function passed to setFoo receives the previous value of `foo` as an argument, which we can reference as `prevFoo`. We then use a ternary operator to toggle the value of foo between `'bar'` and `'baz'`.",
"By using a function to set the value of `foo`, we can ensure that the new value is based on the previous value, prevents unnecessary re-renders of the component and enhances the readability of the code."
]
},
"multipleValues": {
"description": [
"In some cases, you may need to set multiple state values at once. Instead of calling each setter function individually, you can use the `set` function returned by `useObserver` to set multiple state values at the same time.",
"Here's an example of how to set multiple state values using the `set` function:"
],
"explain": [
"In this example, we use the `set` function to set the `firstName` and `lastName` state values at the same time. We pass an object with the new values for both state values to the set function.",
"By setting multiple state values at the same time using the `set` function, we can avoid issues with stale state values that may arise from setting each state value individually."
]
},
"setFunction": {
"description": [
"Just like you can pass a function to a setter to update the state based on the previous state value, you can also pass a function to the `set` function to update multiple state values based on the current state.",
"When using a function with `set`, you'll get the entire current state object as the argument. This can be useful if you want to update multiple state values based on the current state.",
"Here's an example of using a function with `set` to increment two state values at once:"
],
"explain": [
"In this example, we use the `set` function to update both `num1` and `num2` state values based on their current values. We pass a function that receives the current state object as its argument and returns a new object with updated values for num1 and num2.",
"Using a function with `set` can be useful when you need to update multiple state values at once, based on their current values."
]
},
"keywords": [
[
"useObserver",
"React hook",
"state variables",
"re-render",
"setter",
"previous value",
"set function",
"multiple values",
"set state with function",
"update state",
"useState",
"UI synchronization"
]
]
}
}
65 changes: 63 additions & 2 deletions apps/website/src/locales/fa/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@
"Different initial values": "مقادیر اولیه متفاوت",
"Observer": "کلاس مشاهده گر",
"Multiple observers": "استفاده از چند مشاهده گر",
"Subscribe for state changes": "نظارت بر تغییرات استیت"
"Subscribe for state changes": "نظارت بر تغییرات استیت",
"useObserver hook": "هوک useObserver"
},
"home": {
"description": [
Expand Down Expand Up @@ -349,6 +350,63 @@
]
]
},
"useObserver": {
"description": [
"useObserver یک هوک React است که تغییرات اخیر در مقادیری که از آن دریافت می‌کنید را رصد می‌کند و با تغییرات آن مقادیر، کامپوننت شما را مجدداً رندر می‌کند.",
"در هنگام استفاده از useObserver، شما می‌توانید برای متغیری که دریافت می‌کنید، یک مقدار اولیه در نظر بگیرید. اگر این متغیر قبلاً در استیت تعریف نشده باشد، مقدار اولیه شما در استیت برای آن متغیر ثبت می‌شود. اما اگر قبلاً یک مقدار برای آن متغیر موجود باشد، متغیر دریافتی از useObserver با همان مقدار قبلی مقداردهی می‌شود.",
"علاوه بر مقدار متغیر، useObserver یک تابع setter (تنظیم کننده) نیز برای آن متغیر ارائه می‌دهد که می‌توانید از آن برای به‌روزرسانی مقدار متغیر استفاده کنید. با فراخوانی تابع setter، useObserver وضعیت استیت را با مقدار جدید به‌روز می‌کند و باعث میشود که کامپوننت شما مجدداً رندر شود.",
"در اینجا یک مثال از نحوه استفاده از useObserver آورده شده است:"
],
"explain": [
"در این مثال از useObserver برای ثبت یک متغیر در استیت، به نام foo با مقدار اولیه bar استفاده شده است. همانطور که مشاهده میشود در کنار مقدار foo یک تابع setter با نام setFoo از useObserver دریافت شده تا با استفاده از آن، بعد از کلیک شدن روی دکمه Toggle Foo مقدار foo در استیت را به روز رسانی کنیم."
],
"previousValue": {
"description": [
"در زمان تنظیم یک مقدار جدید، ممکن است نیاز داشته باشیم به مقدار قبلی آن متغیر در استیت دسترسی داشته باشیم. برای رسیدن به این هدف، می‌توانیم یک تابع را به عنوان پارامتر به تابع setter که از useObserver دریافت می‌کنیم، ارسال کنیم. این تابع مقدار قبلی متغیر را به عنوان ورودی دریافت کرده و مقدار جدید آن متغیر را برای ثبت شدن در استیت بر میگرداند.",
"در اینجا یک مثال از نحوه استفاده از یک تابع برای دریافت مقدار قبلی متغیر از استیت و تنظیم مقدار جدید آمده است."
],
"explain": [
"در این مثال از تابع setFoo برای تنظیم مقدار foo بر اساس مقدار قبلی آن استفاده می‌کنیم. تابع ارسال شده به setFoo مقدار قبلی foo را به عنوان آرگومان دریافت می‌کند و ما می‌توانیم آن را به عنوان prevFoo نامگذاری کنیم. سپس از یک عملگر شرطی برای تغییر مقدار foo بین 'bar' و 'baz' استفاده می‌کنیم.",
"با استفاده از تابع برای تنظیم مقدار foo، مطمئن می‌شویم که مقدار جدید بر اساس مقدار قبلی تنظیم می‌شود و میتوانیم از مسائلی که ممکن است در تنظیم استیت به صورت async پیش بیاید، جلوگیری کنیم."
]
},
"multipleValues": {
"description": [
"در برخی موارد، ممکن است لازم باشد که چندین متغیر را به صورت همزمان در استیت مقداردهی کنیم. در چنین حالتی، به جای فراخوانی تابع تنظیم کننده برای هر متغیر به صورت جداگانه، می‌توانیم از تابع set که توسط useObserver برگردانده می‌شود، استفاده کنیم.",
"در مثال زیر، نحوه تنظیم همزمان چندین مقدار در استیت با استفاده از تابع set نمایش داده شده است:"
],
"explain": [
"در این مثال، از تابع `set` برای تنظیم مقادیر `firstName` و `lastName` به صورت همزمان استفاده می‌کنیم. با ارسال یک شی حاوی مقادیر جدید برای هر دو متغیر به تابع `set`، می‌توانیم آن‌ها را به روز کنیم.",
"استفاده از تابع `set` برای تنظیم چندین مقدار حالت به صورت همزمان، باعث جلوگیری از رندر اضافی شده و افزایش خوانایی کد می‌شود.",
"همانطور که می توانید یک تابع را به یک تنظیم کننده ارسال کنید تا وضعیت را بر اساس مقدار حالت قبلی به روز کند، همچنین می توانید یک تابع را به تابع set ارسال کنید تا چندین مقدار حالت را بر اساس وضعیت فعلی به روز کند."
]
},
"setFunction": {
"description": [
"همانطور که می‌توانید یک تابع را به یک تنظیم‌کننده ارسال کنید تا وضعیت را بر اساس مقدار قبلی آن متغیر به‌روز کند، می‌توانید یک تابع را به تابع `set` ارسال کنید تا مقدار چندین متغیر را بر اساس وضعیت فعلی استیت به‌روز کند.",
"هنگام ارسال یک تابع با `set`، شما تمام شیء استیت فعلی را به عنوان آرگومان دریافت خواهید کرد. این می‌تواند وقتی مفید است که می‌خواهید چندین مقدار استیت را بر اساس وضعیت فعلی آن به‌روز کنید.",
"در زیر مثالی از ارسال یک تابع به `set` برای افزایش همزمان مقدار دو متغیر در استیت آورده شده است."
],
"explain": [
"در این مثال، از تابع `set` برای به روز رسانی مقادیر متغیرهای num1 و num2 بر اساس مقادیر فعلی آنها استفاده می‌کنیم. ما یک تابع را ارسال می‌کنیم که شیء استیت فعلی را به عنوان آرگومان دریافت کرده و یک شیء جدید با مقادیر به روز شده برای num1 و num2 را برمی‌گرداند.",
"استفاده از یک تابع با `set` می‌تواند زمانی مفید باشد که شما نیاز دارید چندین مقدار استیت را به طور همزمان بر اساس مقادیر فعلی آنها به روز کنید."
]
},
"keywords": [
[
"useObserver",
"هوک ری اکت",
"مقادیر استیت",
"رندر مجدد",
"تنظیم کننده",
"استیت قبلی",
"فانکشن تنظیم کننده",
"تنظیم استیت با فانکشن",
"بروزرسانی استیت",
"useState"
]
]
},
"Demo": "پیش نمایش",
"Counter App": "برنامه شمارنده",
"No Order for Variables": "امکان جابجایی متغیر ها",
Expand All @@ -370,5 +428,8 @@
"Subscribing inside the React component": "رصد تغییرات داخل کامپوننت ری اکت",
"subscribing for more than one value": "رصد تغییرات چند مقدار",
"Subscribing for every state changes": "نظارت بر تمامی مقادیر",
"Custom observer and withState": "observer سفارشی همراه با withState"
"Custom observer and withState": "observer سفارشی همراه با withState",
"Get the previous value from the setter": "دریافت مقدار قبلی از تابع تنظیم کننده",
"Set multiple values at same time": "تنظیم چند مقدار به صورت همزمان",
"Passing function to `set` as parameter": "ارسال یک تابع به `set` به عنوان پارامتر"
}
Loading

0 comments on commit 5897a8d

Please sign in to comment.