diff --git a/content/articles/products/components/combo-box.mdx b/content/articles/products/components/combo-box.mdx deleted file mode 100644 index e9a8bff29..000000000 --- a/content/articles/products/components/combo-box.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: 'ComboBox' -description: '選択肢をリスト形式で持ち、ユーザーが入力によって選択肢を絞り込んだり追加したりできるコンポーネントです。' ---- -import { ComponentPropsTable } from '@Components/ComponentPropsTable' -import { ComponentStory } from '@Components/ComponentStory' - -選択肢をリスト形式で持ち、ユーザーが入力によって選択肢を絞り込んだり追加したりできるコンポーネントです。 - -1つしか選択できない SingleComboBox と複数選択できる MultiComboBox に分かれています。 - - - -## Props - - - - - diff --git a/content/articles/products/components/combo-box/images/multi-combo-box-do.png b/content/articles/products/components/combo-box/images/multi-combo-box-do.png new file mode 100644 index 000000000..b1f91581a Binary files /dev/null and b/content/articles/products/components/combo-box/images/multi-combo-box-do.png differ diff --git a/content/articles/products/components/combo-box/images/multi-combo-box-dont.png b/content/articles/products/components/combo-box/images/multi-combo-box-dont.png new file mode 100644 index 000000000..54d7544d6 Binary files /dev/null and b/content/articles/products/components/combo-box/images/multi-combo-box-dont.png differ diff --git a/content/articles/products/components/combo-box/images/single-combo-box-do.png b/content/articles/products/components/combo-box/images/single-combo-box-do.png new file mode 100644 index 000000000..404aaa850 Binary files /dev/null and b/content/articles/products/components/combo-box/images/single-combo-box-do.png differ diff --git a/content/articles/products/components/combo-box/images/single-combo-box-dont.png b/content/articles/products/components/combo-box/images/single-combo-box-dont.png new file mode 100644 index 000000000..099d6d015 Binary files /dev/null and b/content/articles/products/components/combo-box/images/single-combo-box-dont.png differ diff --git a/content/articles/products/components/combo-box/index.mdx b/content/articles/products/components/combo-box/index.mdx new file mode 100644 index 000000000..c74184f9b --- /dev/null +++ b/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に分かれています。 + + \ No newline at end of file diff --git a/content/articles/products/components/combo-box/multi-combo-box.mdx b/content/articles/products/components/combo-box/multi-combo-box.mdx new file mode 100644 index 000000000..b080cc8c1 --- /dev/null +++ b/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' + +選択肢の中から複数の値を選択するコンポーネントです。テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。 + + + +## 使用上の注意 + +### ユースケースに応じてコンポーネントを使い分ける + +#### 複数選択の場合に使用する + +値を単一選択させたい場合は[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`を使用してください。 + + + } + label={ユーザーがテキストを入力しても入力補助
としてヒントメッセージを確認できる} + /> + } + label={ユーザーがテキストを入力するとプレース
ホルダが確認できなくなり、入力補助とし
て機能しない} + /> + + +## 状態 + +### 無効（disabled） + +入力および選択操作ができない状態を表現したスタイルです。 + +MultiComboBoxに`disabled`を適用すると、テキスト入力不可になりドロップダウンパネルも表示されないため、ユーザーが選択肢を確認できなくなる点に注意してください。 + +```tsx editable codeBlock noIframe +<> + + +``` + +ユーザーはなぜ無効になっているのかわからないことがあります。[権限による表示制御](/products/design-patterns/access-control-pattern/)のデザインパターンを参考にして、そもそも無効ではなくフォーム自体を非表示にしたり、無効状態の理由を付近に表示することを検討してください。 + +### 選択肢にない値の追加 + +入力された値がリストにない場合、追加して選択できる状態を表現したスタイルです。 + +ユーザーがその場で選択肢を追加できるようにしたい場合は、MultiComboBoxに`creatable`を適用してコールバック関数`onAdd`を適切に実装してください。 + +```tsx editable codeBlock noIframe +<> + { + console.log(`Added: ${label}`) + }} + data-test="multi-combobox-creatable" + /> + +``` + +## Props + + + diff --git a/content/articles/products/components/combo-box/single-combo-box.mdx b/content/articles/products/components/combo-box/single-combo-box.mdx new file mode 100644 index 000000000..250378c69 --- /dev/null +++ b/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' + +選択肢の中から単一の値を選択するコンポーネントです。テキスト入力によって選択肢を絞り込んだり、選択肢に新たな値を追加できます。 + + + +## 使用上の注意 + +### ユースケースに応じてコンポーネントを使い分ける + +#### 単一選択の場合に使用する + +値を複数選択させたい場合は[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`を使用してください。 + + + } + label={ユーザーがテキストを入力しても入力補助
としてヒントメッセージを確認できる} + /> + } + label={ユーザーがテキストを入力するとプレース
ホルダが確認できなくなり、入力補助とし
て機能しない} + /> + + +## 状態 + +### 無効（disabled） + +入力および選択操作ができない状態を表現したスタイルです。 + +SingleComboBoxに`disabled`を適用すると、テキスト入力不可になりドロップダウンパネルも表示されないため、ユーザーが選択肢を確認できなくなる点に注意してください。 + +```tsx editable codeBlock noIframe +<> + + +``` + +ユーザーはなぜ無効になっているのかわからないことがあります。[権限による表示制御](/products/design-patterns/access-control-pattern/)のデザインパターンを参考にして、そもそも無効ではなくフォーム自体を非表示にしたり、無効状態の理由を付近に表示することを検討してください。 + +### 選択肢にない値の追加 + +入力された値がリストにない場合、追加して選択できる状態を表現したスタイルです。 + +ユーザーがその場で選択肢を追加できるようにしたい場合は、SingleComboBoxに`creatable`を適用してコールバック関数`onAdd`を適切に実装してください。 + +```tsx editable codeBlock noIframe +<> + { + console.log(`Added: ${label}`) + }} + /> + +``` + +## Props + + diff --git a/content/articles/products/components/select.mdx b/content/articles/products/components/select.mdx index f8a93aa46..e96e0e3ac 100644 --- a/content/articles/products/components/select.mdx +++ b/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