@ouestfrance/sipa-bms-ui 8.22.1 → 8.22.3

package/src/documentation/layout/table.mdx

@@ -0,0 +1,111 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundTable,
+  DoWithSearch,
+  DoWithoutSearch,
+  DoWithFilters,
+  DoWithoutFilters,
+  DoWithCustomActions,
+  DoWithActionIcons,
+  DoWithSearchAndFilters,
+  DoWithSearchFiltersAndActions,
+  DoWithRowSelection,
+} from '../../components/table/BmsTable.stories.js';
+
+<Meta title="Documentation/Layout/Table" />
+
+# <img src="../BmsIcon.png" /> Table
+
+Table is a comprehensive component for displaying structured data in rows and columns. It provides powerful features including search, filtering, sorting, pagination, and row selection. Tables are essential for displaying large amounts of data in an organized and interactive way, allowing users to find, filter, and manipulate information efficiently.
+
+## Anatomy
+
+Table components consist of several key elements: column headers (with optional sorting), data rows, a search bar (optional), filter controls (optional), custom action buttons (optional), pagination controls, and selection checkboxes (when selectable). The table can display data in normal or dense mode, and supports various interaction patterns.
+
+## Component
+
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundTable} />
+
+### Props
+
+<Controls of={PlaygroundTable} />
+
+## Usage Examples
+
+### ✅ Do: Table with search
+
+Enable search functionality when users need to quickly find specific data within the table. The search bar allows users to filter rows by any column value.
+
+<Canvas of={DoWithSearch} />
+
+### ✅ Do: Table without search
+
+Disable search when the table contains a small amount of data or when search functionality is not needed. This simplifies the interface and reduces visual clutter.
+
+<Canvas of={DoWithoutSearch} />
+
+### ✅ Do: Table with filters
+
+Use filters when users need to filter data by specific criteria (e.g., status, category, date range). Filters provide more precise control than search and are ideal for structured filtering.
+
+<Canvas of={DoWithFilters} />
+
+### ✅ Do: Table without filters
+
+Omit filters when the data doesn't require structured filtering or when the table is simple enough that search alone is sufficient.
+
+<Canvas of={DoWithoutFilters} />
+
+### ✅ Do: Table with custom actions
+
+Add custom action tags when users need quick filter options or preset filters. Tags provide a visual way to apply common filters automatically. Custom actions appear in the table header.
+
+<Canvas of={DoWithCustomActions} />
+
+### ✅ Do: Table with action icons
+
+Add action icons (edit, delete, etc.) in a dedicated actions column when users need to perform actions on individual rows. Action icons provide quick access to row-level operations.
+
+<Canvas of={DoWithActionIcons} />
+
+### ✅ Do: Table with search and filters
+
+Combine search and filters when users need both quick text search and structured filtering. This provides maximum flexibility for finding and organizing data.
+
+<Canvas of={DoWithSearchAndFilters} />
+
+### ✅ Do: Table with search, filters and actions
+
+Use all three features (search, filters, and actions) when the table is complex and users need comprehensive data management capabilities.
+
+<Canvas of={DoWithSearchFiltersAndActions} />
+
+### ✅ Do: Table with row selection
+
+Enable row selection when users need to select one or multiple rows to perform actions on them. Selection checkboxes appear in the first column, and selected rows are highlighted.
+
+<Canvas of={DoWithRowSelection} />
+
+## Rules
+
+### When to use search
+
+- **Use search** when users need to quickly find specific text across multiple columns
+- **Don't use search** when the table is very small (fewer than 10 rows) or when filtering by specific criteria is more appropriate
+
+### When to use filters
+
+- **Use filters** when users need to filter by specific structured criteria (status, category, date ranges, etc.)
+- **Don't use filters** when the data is simple and search alone is sufficient, or when filtering would add unnecessary complexity
+
+### When to use custom actions
+
+- **Use custom actions** when users need quick filter options or preset filters. Tags are ideal for common filter presets that users frequently apply
+- **Don't use custom actions** when no quick filters are needed or when all filtering can be handled through the filter panel
+
+### When to use row selection
+
+- **Use row selection** when users need to select one or multiple rows to perform actions on them (delete, export, bulk edit, etc.)
+- **Don't use row selection** when no bulk operations are needed or when actions should be performed individually on each row

package/src/documentation/radioCaptionGroup.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/BmsInputRadioCaptionGroup.stories.js';
-import { DefaultColumn as InputRadioCaptionGroupColumn } from '../components/form/BmsInputRadioCaptionGroup.stories.js';
+  PlaygroundRadioCaptionGroup,
+  DoWithClearLabels,
+  DoWithHelpfulCaptions,
+  DoWithColumnLayout,
+  DontNoLabel,
+  DoWithLabel,
+  DontNoCaptions,
+  DoWithErrorFeedback,
+} from '../components/form/BmsInputRadioCaptionGroup.stories.js';
 
 <Meta title="Documentation/Fields/Radio Caption Group" />
 
-# <img src="./BmsIcon.png" /> Radio Group
+# <img src="./BmsIcon.png" /> Radio Caption Group
 
-A radio caption group consists of a set of interconnected radio buttons. But the caption is set on earch radio input.
-
-![](./fields/CoverRadioCaptionGroup.png)
+A radio caption group consists of a set of interconnected radio buttons where each option can have its own caption. This allows you to provide specific information or descriptions for each individual choice. Radio caption groups are ideal when each option needs its own contextual information, such as pricing details, feature descriptions, or specific instructions for each choice.
 
 ## Anatomy
 
-![InputFile representation](./fields/RadioCaptionGroupRepresentation.png)
+Radio caption groups consist of a label that describes the overall choice, multiple radio button options, and individual captions under each option that provide specific information about that choice. The group can be displayed in a row or column layout.
+
+![Radio Caption Group representation](./fields/RadioCaptionGroupRepresentation.png)
 
 ## Component
 
-### Row representation
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundRadioCaptionGroup} />
+
+### Props
+
+<Controls of={PlaygroundRadioCaptionGroup} />
+
+## Usage Examples
+
+### ✅ Do: Radio caption group with clear labels
+
+Always provide clear, descriptive labels for each option that explain what the choice represents.
+
+<Canvas of={DoWithClearLabels} />
+
+### ✅ Do: Radio caption group with helpful captions
+
+Use captions to provide specific information for each option, such as pricing, features, or additional context that helps users make an informed decision.
+
+<Canvas of={DoWithHelpfulCaptions} />
+
+### ✅ Do: Radio caption group in column layout
+
+Use the column layout when you have longer option labels or captions, or when you want to display options vertically for better readability.
+
+<Canvas of={DoWithColumnLayout} />
+
+### ✅ Do: Radio caption 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 captions when needed
+
+When each option has specific information that users need to know (pricing, features, descriptions), provide captions for each option. Without captions, users may not have enough information to make an informed choice.
+
+**❌ Don't:**
+
+<Canvas of={DontNoCaptions} />
+
+**✅ Do:**
+
+<Canvas of={DoWithHelpfulCaptions} />
+
+## When to use Radio Caption Group vs Radio Group
+
+**Use Radio Caption Group** when:
 
-<Canvas of={InputRadioCaptionGroupRow} args={{ label: 'toto' }} />
+- 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
 
-### Column representation
+**Use Radio Group** when:
 
-<Canvas of={InputRadioCaptionGroupColumn} args={{ label: 'toto' }} />
-### Table of props
+- 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
 
-<Controls of={InputRadioCaptionGroupRow} />
+The key difference is that Radio Caption Group allows you to provide **individual captions for each option**, while Radio Group provides **one caption for the entire group**.

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.