@ouestfrance/sipa-bms-ui 8.22.2 → 8.23.0

package/src/documentation/radioGroup.mdx

@@ -1,34 +1,101 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
 import {
-  Canvas,
-  Meta,
-  Story,
-  Stories,
-  Controls,
-} from '@storybook/addon-docs/blocks';
-import { DefaultRow as InputRadioCaptionGroupRow } from '../components/form/BmsInputRadioGroup.stories.js';
-import { DefaultColumn as InputRadioCaptionGroupColumn } from '../components/form/BmsInputRadioGroup.stories.js';
+  PlaygroundRadioGroup,
+  DoWithClearLabels,
+  DoWithCaption,
+  DoWithColumnLayout,
+  DontNoLabel,
+  DoWithLabel,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+} from '../components/form/BmsInputRadioGroup.stories.js';
 
 <Meta title="Documentation/Fields/Radio Group" />
 
 # <img src="./BmsIcon.png" /> Radio Group
 
-A radio group consists of a set of interconnected radio buttons.
-
-![](./fields/CoverRadioGroup.png)
+A radio group consists of a set of interconnected radio buttons with a single caption that applies to all options. Radio groups are ideal when all options share the same context or when you need to provide general information that applies to the entire group rather than individual options.
 
 ## Anatomy
 
-![InputFile representation](./fields/RadioGroupRepresentation.png)
+Radio groups consist of a label that describes the overall choice, multiple radio button options, and a single caption that provides information applicable to all options. The group can be displayed in a row or column layout.
+
+![Radio Group representation](./fields/RadioGroupRepresentation.png)
 
 ## Component
 
-### Row representation
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundRadioGroup} />
+
+### Props
+
+<Controls of={PlaygroundRadioGroup} />
+
+## Usage Examples
+
+### ✅ Do: Radio group with clear labels
+
+Always provide clear, descriptive labels for each option that explain what the choice represents.
+
+<Canvas of={DoWithClearLabels} />
+
+### ✅ Do: Radio group with caption
+
+Use a caption to provide general information that applies to all options, such as instructions, requirements, or context that helps users understand the choice.
+
+<Canvas of={DoWithCaption} />
+
+### ✅ Do: Radio group in column layout
+
+Use the column layout when you have longer option labels, or when you want to display options vertically for better readability or when space is limited horizontally.
+
+<Canvas of={DoWithColumnLayout} />
+
+### ✅ Do: Radio group with error feedback
+
+Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.
+
+<Canvas of={DoWithErrorFeedback} />
+
+## Rules
+
+### ⛔ Don't: Missing labels
+
+Always provide a label for accessibility and clarity. Labels help screen readers and provide context about what choice is expected.
+
+**❌ Don't:**
+
+<Canvas of={DontNoLabel} />
+
+**✅ Do:**
+
+<Canvas of={DoWithLabel} />
+
+### ⛔ Don't: No error feedback
+
+Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.
+
+**❌ Don't:**
+
+<Canvas of={DontNoErrorFeedback} />
+
+**✅ Do:**
+
+<Canvas of={DoWithErrorFeedback} />
+
+## When to use Radio Group vs Radio Caption Group
+
+**Use Radio Group** when:
 
-<Canvas of={InputRadioCaptionGroupRow} args={{ label: 'toto' }} />
+- All options share the same context or information
+- You only need a single caption that applies to all options
+- Options are simple and self-explanatory without individual descriptions
 
-### Column representation
+**Use Radio Caption Group** when:
 
-<Canvas of={InputRadioCaptionGroupColumn} args={{ label: 'toto' }} />
-### Table of props
+- Each option needs its own specific information or description
+- You need to display different details for each choice (e.g., pricing, features, delivery times)
+- Options have distinct characteristics that require individual explanation
 
-<Controls of={InputRadioCaptionGroupRow} />
+The key difference is that Radio Group provides **one caption for the entire group**, while Radio Caption Group allows you to provide **individual captions for each option**.

package/src/documentation/search.mdx

@@ -1,28 +1,100 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
 import {
-  Canvas,
-  Meta,
-  Story,
-  Stories,
-  Controls,
-} from '@storybook/addon-docs/blocks';
-import { Default as SearchInputDefault } from '../components/form/BmsSearch.stories.js';
+  PlaygroundSearch,
+  DoWithClearPlaceholder,
+  DoWithValue,
+  DoDisabled,
+  DontGenericPlaceholder,
+  DoSpecificPlaceholder,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+  DontNoPlaceholder,
+} from '../components/form/BmsSearch.stories.js';
 
 <Meta title="Documentation/Fields/Search" />
 
 # <img src="./BmsIcon.png" /> Search
 
-It allows users to enter text to perform a search among the data, content, or elements present in the interface they are viewing or the system.
+Search components allow users to enter text to perform a search among the data, content, or elements present in the interface they are viewing or the system. They provide a dedicated input field with a search icon, making it easy for users to find and filter information. Search components are essential for interfaces with large amounts of data or content that needs to be discoverable.
 
-![InputFile representation](./fields/CoverSearch.png)
+![Search representation](./fields/CoverSearch.png)
 
 ## Anatomy
 
-![InputFile representation](./fields/InputSearchRepresentation.png)
+Search components consist of several key elements: a search icon at the start to indicate the field's purpose, an input field where users type their search query, a clear button that appears when there is text to allow users to quickly reset the search, and placeholder text to guide users on what to search for.
+
+![Search representation](./fields/InputSearchRepresentation.png)
 
 ## Component
 
-<Canvas of={SearchInputDefault} args={{ label: 'toto' }} />
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundSearch} />
+
+### Props
+
+<Controls of={PlaygroundSearch} />
+
+## Usage Examples
+
+### ✅ Do: Search with clear placeholder
+
+Always provide a clear, descriptive placeholder that explains what users can search for. This helps users understand the scope of the search.
+
+<Canvas of={DoWithClearPlaceholder} />
+
+### ✅ Do: Search with value and clear button
+
+When users type a search query, a clear button appears automatically, allowing them to quickly reset the search. This improves the user experience.
+
+<Canvas of={DoWithValue} />
+
+### ✅ Do: Disabled state
+
+Use the disabled state when the search should not be editable, but the current search value should still be visible.
+
+<Canvas of={DoDisabled} />
+
+### ✅ Do: Search with error feedback
+
+Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix their search query.
+
+<Canvas of={DoWithErrorFeedback} />
+
+## Rules
+
+### ⛔ Don't: Generic placeholder
+
+Avoid generic placeholders like "Type here" or "Enter text". Use specific examples that guide users on what they can search for.
+
+**❌ Don't:**
+
+<Canvas of={DontGenericPlaceholder} />
+
+**✅ Do:**
+
+<Canvas of={DoSpecificPlaceholder} />
+
+### ⛔ Don't: No error feedback
+
+Always provide clear error messages when search validation fails. Help users understand what went wrong and how to fix their search query.
+
+**❌ Don't:**
+
+<Canvas of={DontNoErrorFeedback} />
+
+**✅ Do:**
+
+<Canvas of={DoWithErrorFeedback} />
+
+### ⛔ Don't: Search without placeholder
+
+Always provide a placeholder to guide users on what they can search for. By default we offer "Rechercher...".
+
+**❌ Don't:**
+
+<Canvas of={DontNoPlaceholder} />
 
-### Table of props
+**✅ Do:**
 
-<Controls of={SearchInputDefault} />
+<Canvas of={DoWithClearPlaceholder} />

package/src/documentation/select.mdx

@@ -1,31 +1,152 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
 import {
-  Canvas,
-  Meta,
-  Story,
-  Stories,
-  Controls,
-} from '@storybook/addon-docs/blocks';
-import { Default as FieldDefault } from '../plugins/field/FieldComponent.stories.js';
-import { Default as TextDefault } from '../components/form/BmsInputText.stories.js';
-import BmsInput from '../components/form/BmsInputText.vue';
-import { Default as SelectDefault } from '../components/form/BmsSelect.stories.js';
+  PlaygroundSelect,
+  DoWithLabel,
+  DoWithPlaceholder,
+  DoWithCaption,
+  DoDisabled,
+  DoLoading,
+  DontLongLabel,
+  DoShortLabel,
+  DontNoLabel,
+  DontGenericPlaceholder,
+  DoSpecificPlaceholder,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+  DontNoCaption,
+  DoWithHelpfulCaption,
+} from '../components/form/BmsSelect.stories.js';
 
 <Meta title="Documentation/Fields/Select" />
 
 # <img src="./BmsIcon.png" /> Select
 
-Selects (or "dropdowns")," enable users to select from a list of options within a confined area. The available options within the list may vary depending on the context.
-
-![](./fields/CoverSelect.png)
+Selects (or "dropdowns") enable users to select from a list of options within a confined area. They are essential components for forms that require users to choose from predefined options, providing a way to select single values from a list. The available options within the list may vary depending on the context. Various options can be shown with the field to communicate selection requirements and provide feedback.
 
 ## Anatomy
 
+Select components consist of several key elements: a label that describes what information is needed, a select field that displays the selected value or placeholder, a dropdown icon to indicate it's a selectable field, placeholder text for guidance, captions for additional information, and error messages for validation feedback.
+
 ![](./fields/SelectRepresentation.png)
 
 ## Component
 
-<Canvas of={SelectDefault} args={{ label: 'toto' }} />
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundSelect} />
+
+### Props
+
+<Controls of={PlaygroundSelect} />
+
+## Usage Examples
+
+### ✅ Do: Simple select with label
+
+Always provide a clear, descriptive label that explains what information is expected.
+
+<Canvas of={DoWithLabel} />
+
+### ✅ Do: Select with placeholder
+
+Use placeholders to provide examples or guidance on what to select. Placeholders help users understand what action is expected.
+
+<Canvas of={DoWithPlaceholder} />
+
+### ✅ Do: Select with caption
+
+Use captions to provide additional context, help text, or important information about the selection.
+
+<Canvas of={DoWithCaption} />
+
+### ✅ Do: Disabled state
+
+Use the disabled state when the select should not be editable, but the value should still be visible.
+
+<Canvas of={DoDisabled} />
+
+### ✅ Do: Loading state
+
+Use the loading state to indicate that the select is processing data or waiting for options to load.
+
+<Canvas of={DoLoading} />
+
+### ✅ Do: Select with error feedback
+
+Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.
+
+<Canvas of={DoWithErrorFeedback} />
+
+## Rules
+
+### ⛔ Don't: Long labels
+
+Avoid overly long labels that make the form difficult to scan. Keep labels concise and clear.
+
+**❌ Don't:**
+
+<Canvas of={DontLongLabel} />
+
+**✅ Do:**
+
+<Canvas of={DoShortLabel} />
+
+### ⛔ Don't: Missing labels
+
+Always provide a label for accessibility and clarity. Labels help screen readers and provide context.
+
+**❌ Don't:**
+
+<Canvas of={DontNoLabel} />
+
+**✅ Do:**
+
+<Canvas of={DoWithLabel} />
+
+### ⛔ Don't: Generic placeholders
+
+Avoid generic placeholders like "Select" or "Choose". Use specific examples that guide the user.
+
+**❌ Don't:**
+
+<Canvas of={DontGenericPlaceholder} />
+
+**✅ Do:**
+
+<Canvas of={DoSpecificPlaceholder} />
+
+### ⛔ Don't: No error feedback
+
+Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.
+
+**❌ Don't:**
+
+<Canvas of={DontNoErrorFeedback} />
+
+**✅ Do:**
+
+<Canvas of={DoWithErrorFeedback} />
+
+### ⛔ Don't: Missing helpful captions
+
+When selection requirements are complex, provide captions to help users understand what's expected.
+
+**❌ Don't:**
+
+<Canvas of={DontNoCaption} />
+
+**✅ Do:**
+
+<Canvas of={DoWithHelpfulCaption} />
+
+### ⚠️ Note: When to use Radio instead of Select
+
+For a small number of options (especially 2 options), consider using the Radio component instead of Select. Radio buttons provide better visibility of all available options and require fewer interactions from users. Selects are better suited for longer lists of options (typically 5 or more) or when space is limited.
+
+**❌ Don't: Use Select with only 2 options**
+
+When you have only 2 options, a Select dropdown adds unnecessary complexity. Users have to click to see options that could be immediately visible.
 
-### Table of props
+**✅ Do: Use Radio for 2-3 options**
 
-<Controls of={SelectDefault} />
+For binary choices or a small number of options, Radio buttons allow users to see all options at once and make a selection with a single click.

package/src/documentation/tag.mdx

@@ -1,28 +1,108 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
 import {
-  Canvas,
-  Meta,
-  Story,
-  Stories,
-  Controls,
-} from '@storybook/addon-docs/blocks';
-import { Default as TagDefault } from '../components/form/BmsTag.stories.js';
+  PlaygroundTag,
+  DoWithClearContent,
+  DoWithDismissible,
+  DoWithActiveState,
+  DoWithDisabledState,
+  DoWithShortContent,
+  DontLongContent,
+  DontEmptyContent,
+  DoClearContent,
+  DontCantDismissWhenNeeded,
+  DoCanDismiss,
+} from '../components/form/BmsTag.stories.js';
 
 <Meta title="Documentation/Tag" />
 
 # <img src="./BmsIcon.png" /> Tag
 
-Tags are components that allow users to add differents options to forms or interfaces. A tag can be active or desactive by the user and closable (its the principal difference with Chips).
+Tags are interactive components that allow users to add, select, and remove options in forms or interfaces. Tags can be clicked to toggle their active state and can be dismissed (closed) by users. They are commonly used for filters, selections, categories, and removable items. Tags provide a way for users to interact with and manage multiple options in a compact, visual format.
 
 ![Tag representation](./tag/CoverTag.png)
 
 ## Anatomy
 
+Tags consist of a container with a border, text content, and an optional dismiss button. They can be in an active or inactive state, and can be disabled. Tags are designed to be interactive elements that users can click to toggle or dismiss.
+
 ![Tag representation](./tag/TagRepresentation.png)
 
 ## Component
 
-<Canvas of={TagDefault} args={{ label: 'toto' }} />
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundTag} />
+
+### Props
+
+<Controls of={PlaygroundTag} />
+
+## Usage Examples
+
+### ✅ Do: Tag with clear content
+
+Always provide clear, concise content that is easy to understand at a glance.
+
+<Canvas of={DoWithClearContent} />
+
+### ✅ Do: Tag with dismissible option
+
+Use dismissible tags when users need to remove items, such as filters or selected options.
+
+<Canvas of={DoWithDismissible} />
+
+### ✅ Do: Tag with active state
+
+Use the active state to indicate that a tag is currently selected or applied. Active tags have a filled background.
+
+<Canvas of={DoWithActiveState} />
+
+### ✅ Do: Tag with disabled state
+
+Use the disabled state when a tag should be visible but not interactive. This is useful for showing locked or unavailable options.
+
+<Canvas of={DoWithDisabledState} />
+
+### ✅ Do: Tag with short content
+
+Keep tag content short and concise. Tags are meant to display brief information that users can quickly scan and interact with.
+
+<Canvas of={DoWithShortContent} />
+
+## Rules
+
+### ⛔ Don't: Long content
+
+Avoid overly long content in tags. Long text makes tags difficult to read, breaks the layout, and defeats the purpose of compact, scannable elements.
+
+**❌ Don't:**
+
+<Canvas of={DontLongContent} />
+
+**✅ Do:**
+
+<Canvas of={DoWithShortContent} />
+
+### ⛔ Don't: Empty or unclear content
+
+Always provide meaningful content in tags. Empty tags or unclear labels don't provide value to users and make the interface confusing.
+
+**❌ Don't:**
+
+<Canvas of={DontEmptyContent} />
+
+**✅ Do:**
+
+<Canvas of={DoClearContent} />
+
+### ⛔ Don't: Tag that cannot be dismissed when it should
+
+If a tag represents something that users should be able to remove (like a filter or a selected option), make sure it can be dismissed. Non-dismissible tags should only be used for permanent or required items.
+
+**❌ Don't:**
+
+<Canvas of={DontCantDismissWhenNeeded} />
 
-### Table of props
+**✅ Do:**
 
-<Controls of={TagDefault} />
+<Canvas of={DoCanDismiss} />

package/src/documentation/textArea.mdx

@@ -1,27 +1,140 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
 import {
-  Canvas,
-  Meta,
-  Story,
-  Stories,
-  Controls,
-} from '@storybook/addon-docs/blocks';
-import { Default as TextAreaDefault } from '../components/form/BmsTextArea.stories.js';
+  PlaygroundTextArea,
+  DoWithLabel,
+  DoWithPlaceholder,
+  DoWithCaption,
+  DoDisabled,
+  DoLoading,
+  DontLongLabel,
+  DoShortLabel,
+  DontNoLabel,
+  DontGenericPlaceholder,
+  DoSpecificPlaceholder,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+  DontNoCaption,
+  DoWithHelpfulCaption,
+} from '../components/form/BmsTextArea.stories.js';
 
 <Meta title="Documentation/Fields/Text Area" />
 
 # <img src="./BmsIcon.png" /> Text Area
 
-Text area allows users to input and edit multiple lines of text such as paragraphs, comments, or descriptions.
-![InputFile representation](./fields/CoverTextArea.png)
+Text area allows users to input and edit multiple lines of text such as paragraphs, comments, or descriptions. They are essential components for forms that require longer text entries, providing a way for users to enter detailed information, feedback, or multi-line content. Various options can be shown with the field to communicate input requirements and provide feedback.
 
 ## Anatomy
 
-![InputFile representation](./fields/InputTextAreaRepresentation.png)
+Text areas consist of several key elements: a label that describes what information is needed, a textarea field where users type multiple lines of text, placeholder text for guidance, captions for additional information, and error messages for validation feedback.
+
+![](./fields/InputTextAreaRepresentation.png)
 
 ## Component
 
-<Canvas of={TextAreaDefault} args={{ label: 'toto' }} />
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundTextArea} />
+
+### Props
+
+<Controls of={PlaygroundTextArea} />
+
+## Usage Examples
+
+### ✅ Do: Simple textarea with label
+
+Always provide a clear, descriptive label that explains what information is expected.
+
+<Canvas of={DoWithLabel} />
+
+### ✅ Do: Textarea with placeholder
+
+Use placeholders to provide examples or format hints. Placeholders disappear when the user starts typing.
+
+<Canvas of={DoWithPlaceholder} />
+
+### ✅ Do: Textarea with caption
+
+Use captions to provide additional context, help text, or format requirements such as character limits.
+
+<Canvas of={DoWithCaption} />
+
+### ✅ Do: Disabled state
+
+Use the disabled state when the textarea should not be editable, but the value should still be visible.
+
+<Canvas of={DoDisabled} />
+
+### ✅ Do: Loading state
+
+Use the loading state to indicate that the textarea is processing data or waiting for a response.
+
+<Canvas of={DoLoading} />
+
+### ✅ Do: Textarea with error feedback
+
+Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.
+
+<Canvas of={DoWithErrorFeedback} />
+
+## Rules
+
+### ⛔ Don't: Long labels
+
+Avoid overly long labels that make the form difficult to scan. Keep labels concise and clear.
+
+**❌ Don't:**
+
+<Canvas of={DontLongLabel} />
+
+**✅ Do:**
+
+<Canvas of={DoShortLabel} />
+
+### ⛔ Don't: Missing labels
+
+Always provide a label for accessibility and clarity. Labels help screen readers and provide context.
+
+**❌ Don't:**
+
+<Canvas of={DontNoLabel} />
+
+**✅ Do:**
+
+<Canvas of={DoWithLabel} />
+
+### ⛔ Don't: Generic placeholders
+
+Avoid generic placeholders like "Enter text" or "Type here". Use specific examples that guide the user.
+
+**❌ Don't:**
+
+<Canvas of={DontGenericPlaceholder} />
+
+**✅ Do:**
+
+<Canvas of={DoSpecificPlaceholder} />
+
+### ⛔ Don't: No error feedback
+
+Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.
+
+**❌ Don't:**
+
+<Canvas of={DontNoErrorFeedback} />
+
+**✅ Do:**
+
+<Canvas of={DoWithErrorFeedback} />
+
+### ⛔ Don't: Missing helpful captions
+
+When textarea requirements are complex, provide captions to help users understand what's expected.
+
+**❌ Don't:**
+
+<Canvas of={DontNoCaption} />
 
-### Table of props
+**✅ Do:**
 
-<Controls of={TextAreaDefault} />
+<Canvas of={DoWithHelpfulCaption} />