docs: advocate using IArray instead of Vec in component properties

Author: Madoshakalaka

website/docs/advanced-topics/immutable.mdx

@@ -18,6 +18,16 @@ achieve this we usually wrap things in `Rc`.
 Immutable types are a great fit for holding property's values because they can
 be cheaply cloned when passed from component to component.
 
+## Common Immutable Types
+
+Yew recommends using the following immutable types from the `implicit-clone` crate:
+
+- `IString` (aliased as `AttrValue` in Yew) - for strings instead of `String`
+- `IArray<T>` - for arrays/vectors instead of `Vec<T>` 
+- `IMap<K, V>` - for maps instead of `HashMap<K, V>`
+
+These types are either reference-counted (`Rc`) or static references, making them very cheap to clone.
+
 ## Further reading
 
 - [Immutable example](https://github.com/yewstack/yew/tree/master/examples/immutable)

website/docs/concepts/function-components/properties.mdx

@@ -341,9 +341,9 @@ These include, but are not limited to:
    **Why is this bad?** Interior mutability (such as with `RefCell`, `Mutex`, etc.) should
    _generally_ be avoided. It can cause problems with re-renders (Yew doesn't know when the state has changed)
    so you may have to manually force a render. Like all things, it has its place. Use it with caution.
-3. Using `Vec` type instead of `IArray`. <br />
-   **Why is this bad?** `Vec`, just like `String`, can also be expensive to clone. `IArray` is either
-   a reference-counted slice (`Rc<T>`) or a `&'static [T]`, thus very cheap to clone.<br />
+3. Using `Vec<T>` type instead of `IArray<T>`. <br />
+   **Why is this bad?** `Vec<T>`, just like `String`, can also be expensive to clone. `IArray<T>` is either
+   a reference-counted slice (`Rc<[T]>`) or a `&'static [T]`, thus very cheap to clone.<br />
    **Note**: `IArray` can be imported from [implicit-clone](https://crates.io/crates/implicit-clone)
    See that crate to learn more.
 4. You tell us. Did you run into an edge-case you wish you knew about earlier? Feel free to create an issue

website/i18n/ja/docusaurus-plugin-content-docs/current/advanced-topics/immutable.mdx

@@ -13,6 +13,16 @@ React と同様に、プロパティは祖先から子孫に伝播されます
 
 イミュータブルタイプは、コンポーネント間でプロパティの値を低コストでクローンできるため、プロパティの値を保持するのに最適です。
 
+## 一般的なイミュータブルタイプ
+
+Yew は `implicit-clone` クレートから以下のイミュータブルタイプの使用を推奨しています：
+
+- `IString`（Yew では `AttrValue` としてエイリアス化）- `String` の代わりに文字列用
+- `IArray<T>` - `Vec<T>` の代わりに配列・ベクター用
+- `IMap<K, V>` - `HashMap<K, V>` の代わりにマップ用
+
+これらのタイプは参照カウント（`Rc`）または静的参照のいずれかであり、非常に安価にクローンできます。
+
 ## さらに読む
 
 - [イミュータブルの例](https://github.com/yewstack/yew/tree/master/examples/immutable)

website/i18n/ja/docusaurus-plugin-content-docs/current/concepts/function-components/properties.mdx

@@ -329,8 +329,8 @@ fn main() {
    **注意**：`AttrValue` は内部的には [implicit-clone](https://crates.io/crates/implicit-clone) からの `IString` です。詳細はそのパッケージを参照してください。
 2. 内部可変性を使用する。 <br />
    **なぜ悪いのか？** 内部可変性（例えば `RefCell`、`Mutex` など）は _通常_ 避けるべきです。これにより再レンダリングの問題が発生する可能性があり（Yewは状態が変更されたことを認識しません）、手動で再レンダリングを強制する必要があるかもしれません。すべてのものと同様に、適切な使用場所があります。慎重に使用してください。
-3. `Vec` 型を `IArray` の代わりに使用する。 <br />
-   **なぜ悪いのか？** `Vec` も `String` と同様にクローンのコストが高いです。`IArray` は参照カウントされたスライス (`Rc<T>`) または `&'static [T]` であり、非常に安価にクローンできます。<br />
+3. `Vec<T>` 型を `IArray<T>` の代わりに使用する。 <br />
+   **なぜ悪いのか？** `Vec<T>` も `String` と同様にクローンのコストが高いです。`IArray<T>` は参照カウントされたスライス (`Rc<[T]>`) または `&'static [T]` であり、非常に安価にクローンできます。<br />
    **注意**：`IArray` は [implicit-clone](https://crates.io/crates/implicit-clone) からインポートできます。詳細はそのパッケージを参照してください。
 4. 新しい発見があるかもしれません。早く知っておきたかったエッジケースに遭遇しましたか？問題を作成するか、このドキュメントに修正のPRを提供してください。
 

website/i18n/ja/docusaurus-plugin-content-docs/version-0.21/advanced-topics/immutable.mdx

@@ -0,0 +1,29 @@
+---
+title: 'イミュータブルタイプ'
+description: 'Yew のイミュータブルデータ構造'
+---
+
+## イミュータブルタイプとは？
+
+これらのタイプは、インスタンス化はできるが値を変更することはできないタイプです。値を更新するには、新しい値をインスタンス化する必要があります。
+
+## なぜイミュータブルタイプを使用するのですか？
+
+React と同様に、プロパティは祖先から子孫に伝播されます。これは、各コンポーネントが更新されるたびにプロパティが存在する必要があることを意味します。したがって、プロパティは理想的には簡単にクローンできるべきです。これを実現するために、通常は `Rc` にラップします。
+
+イミュータブルタイプは、コンポーネント間でプロパティの値を低コストでクローンできるため、プロパティの値を保持するのに最適です。
+
+## 一般的なイミュータブルタイプ
+
+Yew は `implicit-clone` クレートから以下のイミュータブルタイプの使用を推奨しています：
+
+- `IString`（Yew では `AttrValue` としてエイリアス化）- `String` の代わりに文字列用
+- `IArray<T>` - `Vec<T>` の代わりに配列・ベクター用
+- `IMap<K, V>` - `HashMap<K, V>` の代わりにマップ用
+
+これらのタイプは参照カウント（`Rc`）または静的参照のいずれかであり、非常に安価にクローンできます。
+
+## さらに読む
+
+- [イミュータブルの例](https://github.com/yewstack/yew/tree/master/examples/immutable)
+- [Crate `implicit-clone`](https://docs.rs/implicit-clone/)

website/i18n/ja/docusaurus-plugin-content-docs/version-0.21/concepts/function-components/properties.mdx

@@ -0,0 +1,291 @@
+---
+title: 'プロパティ (Properties)'
+description: '親子コンポーネントの通信'
+---
+
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+:::note
+
+プロパティ (Properties) は通常 "Props" と略されます。
+
+:::
+
+プロパティ (Properties) はコンポーネントのパラメータであり、Yew はこれらのパラメータを監視できます。
+
+コンポーネントのプロパティで型を使用する前に、その型は `Properties` トレイトを実装している必要があります。
+
+## リアクティブ性
+
+再レンダリング時に、Yew は仮想DOMを調整する際にプロパティが変更されたかどうかを確認し、ネストされたコンポーネントを再レンダリングする必要があるかどうかを判断します。これにより、Yew は非常にリアクティブなフレームワークと見なされます。親コンポーネントからの変更は常に下位に伝播し、ビューはプロパティ/状態からのデータと常に同期します。
+
+:::tip
+
+まだ [チュートリアル](../../tutorial) を完了していない場合は、このリアクティブ性を自分でテストしてみてください！
+
+:::
+
+## 派生マクロ
+
+Yew は、構造体に `Properties` トレイトを簡単に実装できる派生マクロを提供します。
+
+`Properties` を派生する型は、Yew がデータ比較を行えるように `PartialEq` も実装している必要があります。
+
+```rust
+use yew::Properties;
+
+#[derive(Properties, PartialEq)]
+pub struct Props {
+    pub is_loading: bool,
+}
+```
+
+## 関数コンポーネントでの使用
+
+属性 `#[function_component]` は、関数の引数で Props を選択的に受け取ることを可能にします。それらを提供するには、`html!` マクロ内の属性を通じて割り当てることができます。
+
+<Tabs>
+  <TabItem value="with-props" label="With Props">
+
+```rust
+use yew::{function_component, html, Html, Properties};
+
+#[derive(Properties, PartialEq)]
+pub struct Props {
+    pub is_loading: bool,
+}
+
+#[function_component]
+fn HelloWorld(props: &Props) -> Html {
+    html! { <>{"Am I loading? - "}{props.is_loading.clone()}</> }
+}
+
+// そしてプロパティを提供します
+#[function_component]
+fn App() -> Html {
+    html! {<HelloWorld is_loading={true} />}
+}
+
+```
+
+  </TabItem>
+  <TabItem value="no-props" label="No Props">
+
+```rust
+use yew::{function_component, html, Html};
+
+
+
+
+
+#[function_component]
+fn HelloWorld() -> Html {
+    html! { "Hello world" }
+}
+
+// 提供するプロパティはありません
+#[function_component]
+fn App() -> Html {
+    html! {<HelloWorld />}
+}
+
+```
+
+  </TabItem>
+</Tabs>
+
+## 派生マクロフィールド属性
+
+`Properties` を派生する際、デフォルトではすべてのフィールドが必須です。
+以下の属性を使用すると、親コンポーネントがそれらを設定しなかった場合にデフォルト値を提供することができます。
+
+:::tip
+属性は Rustdoc によって生成されたドキュメントには表示されません。属性のドキュメント文字列には、その属性がオプションであるかどうか、および特定のデフォルト値があるかどうかを記載する必要があります。
+:::
+
+<Tabs>
+  <TabItem value="prop_or_default" label="#[prop_or_default]">
+
+`Default` トレイトを使用して、フィールド型のデフォルト値でプロパティ値を初期化します。
+
+```rust
+use yew::{function_component, html, Html, Properties};
+
+#[derive(Properties, PartialEq)]
+pub struct Props {
+    // highlight-start
+    #[prop_or_default]
+    // highlight-end
+    pub is_loading: bool,
+}
+
+#[function_component]
+fn HelloWorld(props: &Props) -> Html {
+    if props.is_loading.clone() {
+        html! { "Loading" }
+    } else {
+        html! { "Hello world" }
+    }
+}
+
+// デフォルト値を使用する
+#[function_component]
+fn Case1() -> Html {
+    html! {<HelloWorld />}
+}
+// またはデフォルト値を上書きしない
+#[function_component]
+fn Case2() -> Html {
+    html! {<HelloWorld is_loading={true} />}
+}
+```
+
+  </TabItem>
+  <TabItem value="prop_or_value" label="#[prop_or(value)]">
+
+`value` を使用してプロパティ値を初期化します。`value` はフィールド型を返す任意の式である可能性があります。
+例えば、ブールプロパティをデフォルトで `true` にするには、属性 `#[prop_or(true)]` を使用します。プロパティが構築されるときに、式が評価され、明示的な値が与えられていない場合に適用されます。
+
+```rust
+use yew::{function_component, html, Html, Properties};
+
+#[derive(Properties, PartialEq)]
+pub struct Props {
+    // highlight-start
+    #[prop_or("Bob".to_string())]
+    // highlight-end
+    pub name: String,
+}
+
+#[function_component]
+fn HelloWorld(props: &Props) -> Html {
+    html! {<>{"Hello world"}{props.name.clone()}</>}
+}
+
+// デフォルト値を使用する
+#[function_component]
+fn Case1() -> Html {
+    html! {<HelloWorld />}
+}
+// またはデフォルト値を上書きしない
+#[function_component]
+fn Case2() -> Html {
+    html! {<HelloWorld name={"Sam".to_string()} />}
+}
+```
+
+  </TabItem>
+  <TabItem value="prop_or_else_function" label="#[prop_or_else(function)]">
+
+属性値を初期化するために `function` を呼び出します。`function` は `FnMut() -> T` シグネチャを持つ必要があり、ここで `T` はフィールドの型です。このプロパティに明示的な値が与えられていない場合、その関数が呼び出されます。
+
+```rust
+use yew::{function_component, html, Html, Properties};
+
+fn create_default_name() -> String {
+    "Bob".to_string()
+}
+
+#[derive(Properties, PartialEq)]
+pub struct Props {
+    // highlight-start
+    #[prop_or_else(create_default_name)]
+    // highlight-end
+    pub name: String,
+}
+
+#[function_component]
+fn HelloWorld(props: &Props) -> Html {
+    html! {<>{"Hello world"}{props.name.clone()}</>}
+}
+
+// デフォルト値を使用する
+#[function_component]
+fn Case1() -> Html {
+    html! {<HelloWorld />}
+}
+// またはデフォルト値を上書きしない
+#[function_component]
+fn Case2() -> Html {
+    html! {<HelloWorld name={"Sam".to_string()} />}
+}
+```
+
+  </TabItem>
+</Tabs>
+
+## Properties のパフォーマンスオーバーヘッド
+
+内部プロパティは参照カウントされたスマートポインタとして渡されます。これにより、コンポーネントツリー内のプロパティに対して共有ポインタが1つだけ渡されるため、プロパティ全体をクローンする高コストを節約できます。
+
+:::tip
+`AttrValue` はプロパティ値に使用するカスタムタイプであり、これにより String やその他のクローンコストが高いタイプとして定義する必要がなくなります。
+:::
+
+## Props マクロ
+
+`yew::props!` マクロを使用すると、`html!` マクロと同じ方法でプロパティを構築できます。
+
+このマクロは構造体の式と同じ構文を使用しますが、プロパティや基本式 (`Foo { ..base }`) を使用することはできません。タイプパスはプロパティ (`path::to::Props`) に直接指すことも、コンポーネントの関連プロパティ (`MyComp::Properties`) に指すこともできます。
+
+```rust
+use yew::{function_component, html, Html, Properties, props, virtual_dom::AttrValue};
+
+#[derive(Properties, PartialEq)]
+pub struct Props {
+    #[prop_or(AttrValue::from("Bob"))]
+    pub name: AttrValue,
+}
+
+#[function_component]
+fn HelloWorld(props: &Props) -> Html {
+    html! {<>{"Hello world"}{props.name.clone()}</>}
+}
+
+#[function_component]
+fn App() -> Html {
+    // highlight-start
+    let pre_made_props = props! {
+        Props {} // 名前属性を指定する必要はありません
+    };
+    // highlight-end
+    html! {<HelloWorld ..pre_made_props />}
+}
+```
+
+## 評価順序
+
+属性は指定された順序で評価されます。以下の例を参照してください：
+
+```rust
+#[derive(yew::Properties, PartialEq)]
+struct Props { first: usize, second: usize, last: usize }
+
+fn main() {
+    let mut g = 1..=3;
+    let props = yew::props!(Props { first: g.next().unwrap(), second: g.next().unwrap(), last: g.next().unwrap() });
+
+    assert_eq!(props.first, 1);
+    assert_eq!(props.second, 2);
+    assert_eq!(props.last, 3);
+}
+```
+
+## アンチパターン
+
+ほとんどのRust型はプロパティとして渡すことができますが、避けるべきアンチパターンがいくつかあります。これらには以下が含まれますが、これに限定されません：
+
+1. `String` 型を `AttrValue` の代わりに使用する。 <br />
+   **なぜ悪いのか？** `String` のクローンは高コストです。プロパティ値がフックやコールバックと一緒に使用される場合、通常クローンが必要です。`AttrValue` は参照カウントされた文字列 (`Rc<str>`) または `&'static str` であり、非常に安価にクローンできます。<br />
+   **注意**：`AttrValue` は内部的には [implicit-clone](https://crates.io/crates/implicit-clone) からの `IString` です。詳細はそのパッケージを参照してください。
+2. 内部可変性を使用する。 <br />
+   **なぜ悪いのか？** 内部可変性（例えば `RefCell`、`Mutex` など）は _通常_ 避けるべきです。これにより再レンダリングの問題が発生する可能性があり（Yewは状態が変更されたことを認識しません）、手動で再レンダリングを強制する必要があるかもしれません。すべてのものと同様に、適切な使用場所があります。慎重に使用してください。
+3. `Vec<T>` 型を `IArray<T>` の代わりに使用する。 <br />
+   **なぜ悪いのか？** `Vec<T>` も `String` と同様にクローンのコストが高いです。`IArray<T>` は参照カウントされたスライス (`Rc<[T]>`) または `&'static [T]` であり、非常に安価にクローンできます。<br />
+   **注意**：`IArray<T>` は [implicit-clone](https://crates.io/crates/implicit-clone) からインポートできます。詳細はそのパッケージを参照してください。
+4. 新しい発見があるかもしれません。早く知っておきたかったエッジケースに遭遇しましたか？問題を作成するか、このドキュメントに修正のPRを提供してください。
+
+## yew-autoprops
+
+[yew-autoprops](https://crates.io/crates/yew-autoprops) は実験的なパッケージで、関数の引数に基づいて動的にProps構造体を作成することを可能にします。プロパティ構造体が再利用されない場合、これは有用かもしれません。

website/i18n/ja/docusaurus-plugin-content-docs/version-0.22/advanced-topics/immutable.mdx

@@ -13,6 +13,16 @@ React と同様に、プロパティは祖先から子孫に伝播されます
 
 イミュータブルタイプは、コンポーネント間でプロパティの値を低コストでクローンできるため、プロパティの値を保持するのに最適です。
 
+## 一般的なイミュータブルタイプ
+
+Yew は `implicit-clone` クレートから以下のイミュータブルタイプの使用を推奨しています：
+
+- `IString`（Yew では `AttrValue` としてエイリアス化）- `String` の代わりに文字列用
+- `IArray<T>` - `Vec<T>` の代わりに配列・ベクター用
+- `IMap<K, V>` - `HashMap<K, V>` の代わりにマップ用
+
+これらのタイプは参照カウント（`Rc`）または静的参照のいずれかであり、非常に安価にクローンできます。
+
 ## さらに読む
 
 - [イミュータブルの例](https://github.com/yewstack/yew/tree/master/examples/immutable)