Merge pull request #1152 from kufu/add-guideline-combobox

Comboboxのガイドラインを追加

content/articles/products/components/combo-box/index.mdx

@@ -0,0 +1,10 @@
+---
+title: 'ComboBox'
+description: '選択肢の中から値を選択するコンポーネントです。Selectとは異なり、テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。単一の値を選択できる SingleComboBox と複数の値を選択できる MultiComboBox に分かれています。'
+---
+import { PageIndex } from '@Components/article/PageIndex'
+
+選択肢の中から値を選択するコンポーネントです。[Select](/products/components/select/)とは異なり、テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。
+単一の値を選択できるSingleComboBoxと複数の値を選択できるMultiComboBoxに分かれています。
+
+<PageIndex path="/products/components/combo-box/" excludes={[]} heading="h2" />

content/articles/products/components/combo-box/multi-combo-box.mdx

@@ -0,0 +1,113 @@
+---
+title: 'MultiComboBox'
+description: '選択肢の中から複数の値を選択するコンポーネントです。テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。'
+---
+import { ComponentStory } from '@Components/ComponentStory'
+import { ComponentPropsTable } from '@Components/ComponentPropsTable'
+import { DoAndDont } from '@Components/DoAndDont'
+import { StaticImage } from '@Components/StaticImage'
+import multiComboBoxDo from './images/multi-combo-box-do.png'
+import multiComboBoxDont from './images/multi-combo-box-dont.png'
+import {
+  MultiComboBox,
+  Cluster
+} from 'smarthr-ui'
+
+選択肢の中から複数の値を選択するコンポーネントです。テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。
+
+<ComponentStory name="MultiCombobox" />
+
+## 使用上の注意
+
+### ユースケースに応じてコンポーネントを使い分ける
+
+#### 複数選択の場合に使用する
+
+値を単一選択させたい場合は[SingleComboBox](/products/components/combo-box/single-combo-box/)を使用してください。
+
+#### 選択肢が6個以上の場合に使用する
+
+選択肢の数が6個以上で、ユーザーにテキスト入力で値を追加させたり、値を絞り込んで選択させたい場合はMultiComboBoxを使用します。
+
+選択肢が5個以下であれば、初期状態で選択肢が一覧できる[CheckBox](/products/components/check-box/)を使用してください。
+ただし、CheckBoxを配置する十分なスペースがない場合は、MultiComboBoxの使用を検討します。
+
+### 入力補助のヒントメッセージとしてプレースホルダを使用しない
+
+MultiComboBoxで入力補助のヒントメッセージを表示したい場合は`dropdownHelpMessage`や[FormControl](/products/components/form-control/)の`helpMessage`を使用し、プレースホルダ（`placeholder`）は使用しないでください。プレースホルダを使用した場合、テキスト入力するとプレースホルダの内容が確認できなくなるため、入力補助として成立しないためです。
+
+`dropdownHelpMessage`はドロップダウンパネルを表示したときのみ表示されるため、ヒントメッセージを常に表示したい場合は、[FormControl](/products/components/form-control/)の`helpMessage`を使用してください。
+
+<Cluster gap={1}>
+  <DoAndDont
+    type="do"
+    img={<StaticImage src={multiComboBoxDo} alt="Do" width="346" />}
+    label={<Text>ユーザーがテキストを入力しても入力補助<br/>としてヒントメッセージを確認できる</Text>}
+  />
+  <DoAndDont
+    type="dont"
+    img={<StaticImage src={multiComboBoxDont} alt="Dont" width="346" />}
+    label={<Text>ユーザーがテキストを入力するとプレース<br/>ホルダが確認できなくなり、入力補助とし<br/>て機能しない</Text>}
+  />
+</Cluster>
+
+## 状態
+
+### 無効（disabled）
+
+入力および選択操作ができない状態を表現したスタイルです。
+
+MultiComboBoxに`disabled`を適用すると、テキスト入力不可になりドロップダウンパネルも表示されないため、ユーザーが選択肢を確認できなくなる点に注意してください。
+
+```tsx editable codeBlock noIframe
+<>
+  <MultiComboBox
+    name="disabled"
+    items={[
+      { label: 'option 1', value: 'value-1' },
+      { label: 'option 2', value: 'value-2' },
+      { label: 'option 3', value: 'value-3' }
+    ]}
+    selectedItems={[
+      { label: 'option 1', value: 'value-1' }
+    ]}
+    dropdownHelpMessage="Disabled なコンボボックス"
+    disabled
+  />
+</>
+```
+
+ユーザーはなぜ無効になっているのかわからないことがあります。[権限による表示制御](/products/design-patterns/access-control-pattern/)のデザインパターンを参考にして、そもそも無効ではなくフォーム自体を非表示にしたり、無効状態の理由を付近に表示することを検討してください。
+
+### 選択肢にない値の追加
+
+入力された値がリストにない場合、追加して選択できる状態を表現したスタイルです。
+
+ユーザーがその場で選択肢を追加できるようにしたい場合は、MultiComboBoxに`creatable`を適用してコールバック関数`onAdd`を適切に実装してください。
+
+```tsx editable codeBlock noIframe
+<>
+  <MultiComboBox
+    name="onAdd"
+    items={[
+      { label: 'option 1', value: 'value-1' },
+      { label: 'option 2', value: 'value-2' },
+      { label: 'option 3', value: 'value-3' }
+    ]}
+    selectedItems={[
+      { label: 'option 1', value: 'value-1' }
+    ]}
+    dropdownHelpMessage="新しいアイテムを追加できます。"
+    creatable
+    onAdd={(label) => {
+      console.log(`Added: ${label}`)
+    }}
+    data-test="multi-combobox-creatable"
+  />
+</>
+```
+
+## Props
+
+<ComponentPropsTable name="MultiComboBox" showTitle />
+

content/articles/products/components/combo-box/single-combo-box.mdx

@@ -0,0 +1,107 @@
+---
+title: 'SingleComboBox'
+description: '選択肢の中から単一の値を選択するコンポーネントです。テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。'
+---
+import { ComponentStory } from '@Components/ComponentStory'
+import { ComponentPropsTable } from '@Components/ComponentPropsTable'
+import { DoAndDont } from '@Components/DoAndDont'
+import { StaticImage } from '@Components/StaticImage'
+import singleComboBoxDo from './images/single-combo-box-do.png'
+import singleComboBoxDont from './images/single-combo-box-dont.png'
+import {
+  SingleComboBox,
+  Cluster
+} from 'smarthr-ui'
+
+選択肢の中から単一の値を選択するコンポーネントです。テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。
+
+<ComponentStory name="SingleCombobox" />
+
+## 使用上の注意
+
+### ユースケースに応じてコンポーネントを使い分ける
+
+#### 単一選択の場合に使用する
+
+値を複数選択させたい場合は[MultiComboBox](/products/components/combo-box/multi-combo-box/)を使用してください。
+
+#### 選択肢が6個以上の場合に使用する
+
+選択肢の数が6個以上で、ユーザーにテキスト入力で値を追加させたり、値を絞り込んで選択させたい場合はSingleComboBoxを使用します。
+
+選択肢が5個以下であれば、初期状態で選択肢が一覧できる[RadioButton](/products/components/radio-button/)を使用してください。
+ただし、RadioButtonを配置する十分スペースがない場合は、SingleComboBoxや[Select](/products/components/select/)の使用を検討します。
+
+### 入力補助のヒントメッセージとしてプレースホルダを使用しない
+
+SingleComboBoxで入力補助のヒントメッセージを表示したい場合は`dropdownHelpMessage`や[FormControl](/products/components/form-control/)の`helpMessage`を使用し、プレースホルダ（`placeholder`）は使用しないでください。プレースホルダを使用した場合、テキスト入力するとプレースホルダの内容が確認できなくなるため、入力補助として成立しないためです。
+
+`dropdownHelpMessage`はドロップダウンパネルを表示したときのみ表示されるため、ヒントメッセージを常に表示したい場合は、[FormControl](/products/components/form-control/)の`helpMessage`を使用してください。
+
+<Cluster gap={1}>
+  <DoAndDont
+    type="do"
+    img={<StaticImage src={singleComboBoxDo} alt="Do" width="346" />}
+    label={<Text>ユーザーがテキストを入力しても入力補助<br/>としてヒントメッセージを確認できる</Text>}
+  />
+  <DoAndDont
+    type="dont"
+    img={<StaticImage src={singleComboBoxDont} alt="Dont" width="346" />}
+    label={<Text>ユーザーがテキストを入力するとプレース<br/>ホルダが確認できなくなり、入力補助とし<br/>て機能しない</Text>}
+  />
+</Cluster>
+
+## 状態
+
+### 無効（disabled）
+
+入力および選択操作ができない状態を表現したスタイルです。
+
+SingleComboBoxに`disabled`を適用すると、テキスト入力不可になりドロップダウンパネルも表示されないため、ユーザーが選択肢を確認できなくなる点に注意してください。
+
+```tsx editable codeBlock noIframe
+<>
+  <SingleComboBox
+    name="disabled"
+    items={[
+      { label: 'option 1', value: 'value-1' },
+      { label: 'option 2', value: 'value-2' },
+      { label: 'option 3', value: 'value-3' }
+    ]}
+    selectedItem={{ label: 'option 1', value: 'value-1' }}
+    dropdownHelpMessage="テキスト入力で検索できます。"
+    disabled
+  />
+</>
+```
+
+ユーザーはなぜ無効になっているのかわからないことがあります。[権限による表示制御](/products/design-patterns/access-control-pattern/)のデザインパターンを参考にして、そもそも無効ではなくフォーム自体を非表示にしたり、無効状態の理由を付近に表示することを検討してください。
+
+### 選択肢にない値の追加
+
+入力された値がリストにない場合、追加して選択できる状態を表現したスタイルです。
+
+ユーザーがその場で選択肢を追加できるようにしたい場合は、SingleComboBoxに`creatable`を適用してコールバック関数`onAdd`を適切に実装してください。
+
+```tsx editable codeBlock noIframe
+<>
+  <SingleComboBox
+    name="onAdd"
+    items={[
+      { label: 'option 1', value: 'value-1' },
+      { label: 'option 2', value: 'value-2' },
+      { label: 'option 3', value: 'value-3' }
+    ]}
+    selectedItem={{ label: 'option 1', value: 'value-1' }}
+    dropdownHelpMessage="テキスト入力で検索できます。"
+    creatable
+    onAdd={(label) => {
+      console.log(`Added: ${label}`)
+    }}
+  />
+</>
+```
+
+## Props
+
+<ComponentPropsTable name="SingleComboBox" showTitle />

content/articles/products/components/select.mdx

@@ -26,9 +26,9 @@ import { ComponentStory } from '@Components/ComponentStory'
 
 ユーザーの設定や条件によって選択肢の数が増減するなど、実装時に数を固定できない場合は、想定される最大数を考慮して使用するコンポーネントを判断してください。
 
-### ComboBoxとの使い分け
+### SingleComboBoxとの使い分け
 
-単一選択かつ、ユーザーに選択肢をフィルタリングさせたい場合は[ComboBox](/products/components/combo-box/)の使用を検討してください。
+単一選択かつ、ユーザーに選択肢をフィルタリングさせたい場合は[SingleComboBox](/products/components/combo-box/single-combo-box/)の使用を検討してください。
 
 ## Props