@ouestfrance/sipa-bms-ui 8.22.2 → 8.23.0

package/src/documentation/inputText.mdx

@@ -0,0 +1,183 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundInputText,
+  DoWithLabel,
+  DoWithPlaceholder,
+  DoWithCaption,
+  DoWithIconStart,
+  DoWithIconEnd,
+  DoWithIcons,
+  DoDisabled,
+  DoLoading,
+  DoWithMaxLength,
+  DoWithMinMaxLength,
+  DontLongLabel,
+  DoShortLabel,
+  DontNoLabel,
+  DontGenericPlaceholder,
+  DoSpecificPlaceholder,
+  DontTooManyIcons,
+  DoOneIcon,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+  DontNoCaption,
+  DoWithHelpfulCaption,
+} from '../components/form/BmsInputText.stories.js';
+
+<Meta title="Documentation/Fields/Input Text" />
+
+# <img src="./BmsIcon.png" /> Input Text
+
+Text fields allow users to input custom text entries with a keyboard. They are essential components for forms and data collection, providing a way for users to enter text, numbers, dates, and other information. Various options can be shown with the field to communicate input requirements and provide feedback.
+
+## Anatomy
+
+Text inputs consist of several key elements: a label that describes what information is needed, an input field where users type, optional icons for visual cues, placeholder text for guidance, captions for additional information, and error messages for validation feedback.
+
+![](./fields/InputRepresentation.png)
+
+## Component
+
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundInputText} />
+
+### Props
+
+<Controls of={PlaygroundInputText} />
+
+## Usage Examples
+
+### ✅ Do: Simple input with label
+
+Always provide a clear, descriptive label that explains what information is expected.
+
+<Canvas of={DoWithLabel} />
+
+### ✅ Do: Input with placeholder
+
+Use placeholders to provide examples or format hints. Placeholders disappear when the user starts typing.
+
+<Canvas of={DoWithPlaceholder} />
+
+### ✅ Do: Input with caption
+
+Use captions to provide additional context, help text, or format requirements.
+
+<Canvas of={DoWithCaption} />
+
+### ✅ Do: Input with icon at start
+
+Icons at the start can help clarify the type of information expected or provide visual context.
+
+<Canvas of={DoWithIconStart} />
+
+### ✅ Do: Input with icon at end
+
+Icons at the end are useful for actions like clearing the field, showing/hiding passwords, or indicating status.
+
+<Canvas of={DoWithIconEnd} />
+
+### ✅ Do: Input with both icons
+
+Use both icons when you need to provide context at the start and an action at the end.
+
+<Canvas of={DoWithIcons} />
+
+### ✅ Do: Disabled state
+
+Use the disabled state when the input 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 input is processing data or waiting for a response.
+
+<Canvas of={DoLoading} />
+
+### ✅ Do: Input with max length
+
+Use maxlength to limit the number of characters. The component will show a warning when the limit is reached.
+
+<Canvas of={DoWithMaxLength} />
+
+### ✅ Do: Input with min and max length
+
+Use both minlength and maxlength to enforce a specific range of characters.
+
+<Canvas of={DoWithMinMaxLength} />
+
+## 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: Overuse of icons
+
+Don't overload inputs with multiple icons that don't add value. Use icons purposefully.
+
+**❌ Don't:**
+
+<Canvas of={DontTooManyIcons} />
+
+**✅ Do:**
+
+<Canvas of={DoOneIcon} />
+
+### ⛔ 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 input requirements are complex, provide captions to help users understand what's expected.
+
+**❌ Don't:**
+
+<Canvas of={DontNoCaption} />
+
+**✅ Do:**
+
+<Canvas of={DoWithHelpfulCaption} />

package/src/documentation/layout/form.mdx

@@ -0,0 +1,74 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundForm,
+  DoWithOrganizedSections,
+  DoWithActions,
+  DontNoActions,
+  DoWithActionsButton,
+  DontNoSectionTitles,
+  DoWithSectionTitles,
+} from '../../components/layout/BmsForm.stories.js';
+
+<Meta title="Documentation/Layout/Form" />
+
+# <img src="../BmsIcon.png" /> Form
+
+Form is a layout component that organizes form fields into sections and provides a consistent structure for form actions. It allows you to group related fields together using named slots and automatically positions action buttons at the bottom of the form. The component helps create well-organized, scannable forms with clear visual separation between sections.
+
+## Anatomy
+
+Form components consist of multiple named slots for organizing form fields into logical sections, and an actions slot for form submission buttons. Each section should have a clear title (typically an h2 heading) that describes the purpose of the fields within that section. Each section is visually separated, and the actions are consistently positioned at the bottom of the form.
+
+## Component
+
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundForm} />
+
+### Props
+
+<Controls of={PlaygroundForm} />
+
+## Usage Examples
+
+### ✅ Do: Form with organized sections
+
+Organize form fields into logical sections using named slots. This makes the form easier to scan and understand.
+
+<Canvas of={DoWithOrganizedSections} />
+
+**Note on sections:** Using sections is not mandatory. They are particularly useful for improving readability when a form becomes too long. As a general guideline, consider using sections when you have more than 5 fields, as this helps users better understand and navigate the form structure.
+
+### ✅ Do: Form with actions
+
+Always provide action buttons (Submit, Cancel, etc.) in the actions slot. This gives users a clear way to submit or cancel the form.
+
+<Canvas of={DoWithActions} />
+
+## Rules
+
+### ⛔ Don't: Form without section titles
+
+Always provide a clear title for each section of the form. Section titles help users understand the purpose of each group of fields and make the form easier to scan and navigate.
+
+**Note on section titles:** If your form has only one section, you don't need to add a title to that section. The page title should be sufficient in this case. Section titles are most useful when you have multiple sections to distinguish between different groups of fields.
+
+**❌ Don't:**
+
+<Canvas of={DontNoSectionTitles} />
+
+**✅ Do:**
+
+<Canvas of={DoWithSectionTitles} />
+
+### ⛔ Don't: Form without actions
+
+Always provide action buttons for forms. Without actions, users cannot submit or cancel the form, creating a poor user experience.
+
+**❌ Don't:**
+
+<Canvas of={DontNoActions} />
+
+**✅ Do:**
+
+<Canvas of={DoWithActionsButton} />

package/src/documentation/layout/headerTitle.mdx

@@ -0,0 +1,124 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundHeaderTitle,
+  DoWithClearTitle,
+  DoWithLabel,
+  DoWithActions,
+  DoWithSecondaryAction,
+  DoWithSubtitle,
+  DoWithHelperLinks,
+  DontNoTitle,
+  DoWithTitle,
+  DontLongTitle,
+  DoShortTitle,
+  DontTwoPrimaryButtons,
+  DontInvertedButtonOrder,
+} from '../../components/layout/BmsHeaderTitle.stories.js';
+
+<Meta title="Documentation/Layout/Header Title" />
+
+# <img src="../BmsIcon.png" /> Header Title
+
+Header Title is a component that provides a consistent structure for page headers. It displays a title, optional label, helper links, and action buttons. The component helps create a unified header experience across the application, providing space for logos, titles, subtitles, and action buttons in a well-organized layout.
+
+## Anatomy
+
+Header Title components consist of several key elements: an optional logo slot, a label (optional prefix text), the main title (h1), optional helper links (documentation and activity), an optional after-title slot for secondary actions, an actions slot for primary actions, and an optional subtitle slot for additional context.
+
+## Component
+
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundHeaderTitle} />
+
+### Props
+
+<Controls of={PlaygroundHeaderTitle} />
+
+## Usage Examples
+
+### ✅ Do: Header title with clear title
+
+Always provide a clear, descriptive title that accurately represents the page content.
+
+<Canvas of={DoWithClearTitle} />
+
+### ✅ Do: Header title with label
+
+Use a label to provide context or categorization for the title, such as the resource type or section name.
+
+<Canvas of={DoWithLabel} />
+
+### ✅ Do: Header title with actions
+
+Use the actions slot to place primary action buttons in the header, aligned to the right.
+
+<Canvas of={DoWithActions} />
+
+### ✅ Do: Header title with secondary action
+
+When you need multiple actions, place the secondary action button to the left of the primary action button. This follows the standard pattern where the primary action is on the right.
+
+<Canvas of={DoWithSecondaryAction} />
+
+### ✅ Do: Header title with subtitle
+
+Use the subtitle slot to provide additional context or description about the page.
+
+<Canvas of={DoWithSubtitle} />
+
+### ✅ Do: Header title with helper links
+
+Use helper links to provide quick access to documentation or activity logs related to the page.
+
+<Canvas of={DoWithHelperLinks} />
+
+## Rules
+
+### ⛔ Don't: Missing title
+
+Always provide a title for the header. The title is the primary identifier for the page and is essential for user orientation.
+
+**❌ Don't:**
+
+<Canvas of={DontNoTitle} />
+
+**✅ Do:**
+
+<Canvas of={DoWithTitle} />
+
+### ⛔ Don't: Too long title
+
+Avoid overly long titles that make the header difficult to read and break the layout. Keep titles concise and clear.
+
+**❌ Don't:**
+
+<Canvas of={DontLongTitle} />
+
+**✅ Do:**
+
+<Canvas of={DoShortTitle} />
+
+### ⛔ Don't: Two primary buttons
+
+Avoid using multiple primary buttons. Use a secondary button for the less important action to maintain visual hierarchy and clarity.
+
+**❌ Don't:**
+
+<Canvas of={DontTwoPrimaryButtons} />
+
+**✅ Do:**
+
+<Canvas of={DoWithSecondaryAction} />
+
+### ⛔ Don't: Inverted button order
+
+Always place the secondary action button to the left of the primary action button. The primary action should be on the right, following standard UI patterns.
+
+**❌ Don't:**
+
+<Canvas of={DontInvertedButtonOrder} />
+
+**✅ Do:**
+
+<Canvas of={DoWithSecondaryAction} />

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**.