@ouestfrance/sipa-bms-ui 8.22.2 → 8.23.0

package/src/documentation/button/secondaryButton.mdx

@@ -1,17 +1,128 @@
-import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import Button from '../../components/button/BmsButton.vue';
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundSecondary,
+  DoSimpleSecondary,
+  DoDangerSecondary,
+  DoSmallSecondary,
+  DoIconStartSecondary,
+  DoIconEndSecondary,
+  DoSubmitSecondary,
+  DontLongLabelSecondary,
+  DoShortLabelSecondary,
+  DontSecondaryAsPrimary,
+  DoSecondaryForCancel,
+  DontTooManyIconsSecondary,
+  DoOneIconSecondary,
+  DontGenericLabelSecondary,
+  DoSpecificLabelSecondary,
+} from '../../components/button/BmsButton.stories.js';
 
 <Meta title="Documentation/Buttons/Secondary" />
 
 # <img src="./BmsIcon.png" /> Secondary Button
 
+The secondary button should represent secondary actions on a screen. They are used alongside primary buttons to create a clear hierarchy of actions. Secondary buttons are ideal for cancel actions, alternative options, or less important actions that don't require primary emphasis.
+
 ## Anatomy
 
 Buttons allow users to perform an action or to navigate to another page. They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.
+
 ![](./button/CoverSecondaryButton.png)
 
 ## Component
 
-## Usage
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundSecondary} />
+
+### Props
+
+<Controls of={PlaygroundSecondary} />
+
+## Usage Examples
+
+### ✅ Do: Simple secondary action button
+
+Use a clear, concise label (maximum 3 words) for secondary actions like cancel, back, or alternative options.
+
+<Canvas of={DoSimpleSecondary} />
+
+### ✅ Do: Button with icon at start
+
+Icons can help clarify the action. Place them at the start of the button.
+
+<Canvas of={DoIconStartSecondary} />
+
+### ✅ Do: Button with icon at end
+
+Place icons at the end for navigation or backward actions.
+
+<Canvas of={DoIconEndSecondary} />
+
+### ✅ Do: Submit button
+
+Use `submit` prop for form submissions when the secondary action is to submit.
+
+<Canvas of={DoSubmitSecondary} />
+
+### ✅ Do: Danger mode
+
+Use danger mode for destructive secondary actions that require caution.
+
+<Canvas of={DoDangerSecondary} />
+
+### ✅ Do: Small variant
+
+Use the small variant when space is limited.
+
+<Canvas of={DoSmallSecondary} />
 
 ## Rules
+
+### ⛔ Don't: Long labels
+
+Avoid long labels that exceed 3 words. Keep button text concise and action-oriented.
+
+**❌ Don't:**
+
+<Canvas of={DontLongLabelSecondary} />
+
+**✅ Do:**
+
+<Canvas of={DoShortLabelSecondary} />
+
+### ⛔ Don't: Use secondary as primary action
+
+Never use secondary buttons for the main action on a screen. Use primary buttons for the most important action.
+
+**❌ Don't:**
+
+<Canvas of={DontSecondaryAsPrimary} />
+
+**✅ Do:**
+
+<Canvas of={DoSecondaryForCancel} />
+
+### ⛔ Don't: Overuse of icons
+
+Don't overload buttons with multiple icons or decorative elements that don't add value.
+
+**❌ Don't:**
+
+<Canvas of={DontTooManyIconsSecondary} />
+
+**✅ Do:**
+
+<Canvas of={DoOneIconSecondary} />
+
+### ⛔ Don't: Generic labels
+
+Avoid generic labels like "Click here" or "Button". Use specific action verbs.
+
+**❌ Don't:**
+
+<Canvas of={DontGenericLabelSecondary} />
+
+**✅ Do:**
+
+<Canvas of={DoSpecificLabelSecondary} />

package/src/documentation/checkboxCaptionGroup.mdx

@@ -0,0 +1,99 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundCheckboxCaptionGroup,
+  DoWithClearLabels,
+  DoWithHelpfulCaptions,
+  DoWithColumnLayout,
+  DontNoLabel,
+  DoWithLabel,
+  DontNoCaptions,
+  DoWithErrorFeedback,
+} from '../components/form/BmsInputCheckboxCaptionGroup.stories.js';
+
+<Meta title="Documentation/Fields/Checkbox Caption Group" />
+
+# <img src="./BmsIcon.png" /> Checkbox Caption Group
+
+A checkbox caption group consists of a set of interconnected checkboxes where each option can have its own caption. This allows you to provide specific information or descriptions for each individual choice. Checkbox caption groups are ideal when each option needs its own contextual information, such as pricing details, feature descriptions, or specific instructions for each choice. Unlike radio groups, checkboxes allow users to select multiple options.
+
+## Anatomy
+
+Checkbox caption groups consist of a label that describes the overall choice, multiple checkbox 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.
+
+## Component
+
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundCheckboxCaptionGroup} />
+
+### Props
+
+<Controls of={PlaygroundCheckboxCaptionGroup} />
+
+## Usage Examples
+
+### ✅ Do: Checkbox caption group with clear labels
+
+Always provide clear, descriptive labels for each option that explain what the choice represents.
+
+<Canvas of={DoWithClearLabels} />
+
+### ✅ Do: Checkbox 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: Checkbox 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: Checkbox 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 choices are 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 Checkbox Caption Group vs Checkbox Group
+
+**Use Checkbox Caption Group** when:
+
+- 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
+
+**Use Checkbox Group** when:
+
+- 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
+
+The key difference is that Checkbox Caption Group allows you to provide **individual captions for each option**, while Checkbox Group provides **one caption for the entire group**.

package/src/documentation/checkboxGroup.mdx

@@ -0,0 +1,99 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundCheckboxGroup,
+  DoWithClearLabels,
+  DoWithCaption,
+  DoWithColumnLayout,
+  DontNoLabel,
+  DoWithLabel,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+} from '../components/form/BmsInputCheckboxGroup.stories.js';
+
+<Meta title="Documentation/Fields/Checkbox Group" />
+
+# <img src="./BmsIcon.png" /> Checkbox Group
+
+A checkbox group consists of a set of interconnected checkboxes with a single caption that applies to all options. Checkbox 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. Unlike radio groups, checkboxes allow users to select multiple options.
+
+## Anatomy
+
+Checkbox groups consist of a label that describes the overall choice, multiple checkbox options, and a single caption that provides information applicable to all options. The group can be displayed in a row or column layout.
+
+## Component
+
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundCheckboxGroup} />
+
+### Props
+
+<Controls of={PlaygroundCheckboxGroup} />
+
+## Usage Examples
+
+### ✅ Do: Checkbox group with clear labels
+
+Always provide clear, descriptive labels for each option that explain what the choice represents.
+
+<Canvas of={DoWithClearLabels} />
+
+### ✅ Do: Checkbox 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: Checkbox 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: Checkbox 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 choices are 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 Checkbox Group vs Checkbox Caption Group
+
+**Use Checkbox Group** when:
+
+- 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
+
+**Use Checkbox Caption Group** when:
+
+- 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
+
+The key difference is that Checkbox Group provides **one caption for the entire group**, while Checkbox Caption Group allows you to provide **individual captions for each option**.

package/src/documentation/chip.mdx

@@ -1,28 +1,102 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
 import {
-  Canvas,
-  Meta,
-  Story,
-  Stories,
-  Controls,
-} from '@storybook/addon-docs/blocks';
-import { Default as ChipDefault } from '../components/form/BmsChip.stories.js';
+  PlaygroundChip,
+  DoWithClearContent,
+  DoWithAppropriateColor,
+  DoWithShortContent,
+  DoWithStatusColor,
+  DontLongContent,
+  DoShortContent,
+  DontInappropriateColor,
+  DoAppropriateColor,
+  DontEmptyContent,
+  DoClearContent,
+} from '../components/form/BmsChip.stories.js';
 
 <Meta title="Documentation/Chip" />
 
 # <img src="./BmsIcon.png" /> Chip
 
-A Chip is a component to make data representation, there is no actions attached to him.
+A Chip is a component to make data representation, there is no actions attached to him. Chips are compact elements that represent an input, attribute, or action. They are commonly used to display status, categories, tags, or other metadata. Chips help users quickly scan and understand information at a glance.
 
 ![Chip representation](./chip/CoverChips.png)
 
 ## Anatomy
 
+Chips consist of a container with background color, text content, and optional color coding to convey meaning. They are designed to be compact and visually distinct while maintaining readability.
+
 ![Chip representation](./chip/ChipRepresentation.png)
 
 ## Component
 
-<Canvas of={ChipDefault} args={{ label: 'toto' }} />
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundChip} />
+
+### Props
+
+<Controls of={PlaygroundChip} />
+
+## Usage Examples
+
+### ✅ Do: Chip with clear content
+
+Always provide clear, concise content that is easy to understand at a glance.
+
+<Canvas of={DoWithClearContent} />
+
+### ✅ Do: Chip with appropriate color
+
+Use colors that match the semantic meaning of the content. Green for success/active, red for errors/danger, orange for warnings, etc.
+
+<Canvas of={DoWithAppropriateColor} />
+
+### ✅ Do: Chip with short content
+
+Keep chip content short and concise. Chips are meant to display brief information, not long descriptions.
+
+<Canvas of={DoWithShortContent} />
+
+### ✅ Do: Chip with status color
+
+Use color coding to quickly convey status information. This helps users understand the state without reading the text.
+
+<Canvas of={DoWithStatusColor} />
+
+## Rules
+
+### ⛔ Don't: Long content
+
+Avoid overly long content in chips. Long text makes chips difficult to read, breaks the layout, and defeats the purpose of compact data representation.
+
+**❌ Don't:**
+
+<Canvas of={DontLongContent} />
+
+**✅ Do:**
+
+<Canvas of={DoShortContent} />
+
+### ⛔ Don't: Inappropriate color usage
+
+Don't use colors that contradict the semantic meaning of the content. This can confuse users and lead to misunderstandings.
+
+**❌ Don't:**
+
+<Canvas of={DontInappropriateColor} />
+
+**✅ Do:**
+
+<Canvas of={DoAppropriateColor} />
+
+### ⛔ Don't: Empty or unclear content
+
+Always provide meaningful content in chips. Empty chips or unclear labels don't provide value to users.
+
+**❌ Don't:**
+
+<Canvas of={DontEmptyContent} />
 
-### Table of props
+**✅ Do:**
 
-<Controls of={ChipDefault} />
+<Canvas of={DoClearContent} />

package/src/documentation/inputCode.mdx

@@ -0,0 +1,97 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
+import {
+  PlaygroundInputCode,
+  DoWithClearLabel,
+  DoWithHtmlType,
+  DoWithJsonType,
+  DoWithCaption,
+  DoDisabled,
+  DontNoLabel,
+  DoWithLabel,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+} from '../components/form/BmsInputCode.stories.js';
+
+<Meta title="Documentation/Fields/Input Code" />
+
+# <img src="./BmsIcon.png" /> Input Code
+
+Input Code is a component for editing code with syntax highlighting and validation. It provides a code editor interface powered by CodeMirror, supporting HTML and JSON formats. The component includes automatic syntax validation for JSON and syntax highlighting for both HTML and JSON. It is ideal for configuration forms, template editing, or any scenario where users need to input and edit code.
+
+## Anatomy
+
+Input code components consist of several key elements: a label that describes what code is expected, a code editor with syntax highlighting, automatic validation for JSON (with error indicators), optional captions for additional information, and error messages for validation feedback.
+
+## Component
+
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundInputCode} />
+
+### Props
+
+<Controls of={PlaygroundInputCode} />
+
+## Usage Examples
+
+### ✅ Do: Input code with clear label
+
+Always provide a clear, descriptive label that explains what type of code is expected (HTML, JSON, etc.).
+
+<Canvas of={DoWithClearLabel} />
+
+### ✅ Do: Input code with HTML type
+
+Use the HTML type when users need to edit HTML templates or markup. The editor provides HTML syntax highlighting.
+
+<Canvas of={DoWithHtmlType} />
+
+### ✅ Do: Input code with JSON type and validation
+
+Use the JSON type when users need to edit JSON configuration. The editor provides JSON syntax highlighting and automatic validation with error indicators.
+
+<Canvas of={DoWithJsonType} />
+
+### ✅ Do: Input code with caption
+
+Use captions to provide additional context, such as format requirements, examples, or validation rules.
+
+<Canvas of={DoWithCaption} />
+
+### ✅ Do: Disabled state
+
+Use the disabled state when the code should not be editable, but the current code should still be visible.
+
+<Canvas of={DoDisabled} />
+
+### ✅ Do: Input code with error feedback
+
+Always provide clear error messages when validation fails. For JSON, syntax errors are automatically detected and displayed.
+
+<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 code is expected.
+
+**❌ Don't:**
+
+<Canvas of={DontNoLabel} />
+
+**✅ Do:**
+
+<Canvas of={DoWithLabel} />
+
+### ⛔ Don't: No error feedback
+
+Always provide clear error messages when validation fails. For JSON, the editor automatically detects syntax errors, but you should also provide custom error messages when needed.
+
+**❌ Don't:**
+
+<Canvas of={DontNoErrorFeedback} />
+
+**✅ Do:**
+
+<Canvas of={DoWithErrorFeedback} />

package/src/documentation/inputFile.mdx

@@ -1,28 +1,105 @@
+import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
 import {
-  Canvas,
-  Meta,
-  Story,
-  Stories,
-  Controls,
-} from '@storybook/addon-docs/blocks';
-import { Empty as InputFileDefault } from '../components/form/BmsInputFile.stories.js';
+  PlaygroundInputFile,
+  DoWithClearLabel,
+  DoWithCaption,
+  DoWithAcceptFilter,
+  DoDisabled,
+  DontNoLabel,
+  DoWithLabel,
+  DontNoErrorFeedback,
+  DoWithErrorFeedback,
+  DontNoCaption,
+} from '../components/form/BmsInputFile.stories.js';
 
 <Meta title="Documentation/Fields/Input File" />
 
 # <img src="./BmsIcon.png" /> Input File
 
-InputFile is a component for uploading one file. After upload its show the result.
-
-![InputFile representation](./fields/CoverInputFile.png)
+InputFile is a component for uploading one file. After upload, it shows the result. The component supports drag and drop functionality, file type filtering, size limits, and displays uploaded files with previews for images. It provides a user-friendly way to upload files in forms and interfaces.
 
 ## Anatomy
 
+Input file components consist of several key elements: a label that describes what file is expected, a drop area where users can drag and drop files or click to browse, an optional caption for additional information like file size limits or accepted types, error messages for validation feedback, and a file preview area that shows uploaded files with the ability to remove them.
+
 ![InputFile representation](./fields/InputMediaRepresentation.png)
 
 ## Component
 
-<Canvas of={InputFileDefault} args={{ label: 'toto' }} />
+Use the controls below to interact with the component and see how it behaves with different configurations.
+
+<Canvas of={PlaygroundInputFile} />
+
+### Props
+
+<Controls of={PlaygroundInputFile} />
+
+## Usage Examples
+
+### ✅ Do: Input file with clear label
+
+Always provide a clear, descriptive label that explains what type of file is expected.
+
+<Canvas of={DoWithClearLabel} />
+
+### ✅ Do: Input file with caption
+
+Use captions to provide additional context, such as file size limits, accepted file types, or format requirements.
+
+<Canvas of={DoWithCaption} />
+
+### ✅ Do: Input file with accept filter
+
+Use the accept prop to restrict file types. This helps users understand what files they can upload and prevents invalid uploads.
+
+<Canvas of={DoWithAcceptFilter} />
+
+### ✅ Do: Disabled state
+
+Use the disabled state when the file upload should not be available, but the current state should still be visible.
+
+<Canvas of={DoDisabled} />
+
+### ✅ Do: Input file 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 file 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} />
+
+### ⛔ Don't: No caption for file requirements
+
+When file requirements are specific (size limits, file types, etc.), provide captions to help users understand what's expected.
+
+**❌ Don't:**
+
+<Canvas of={DontNoCaption} />
 
-### Table of props
+**✅ Do:**
 
-<Controls of={InputFileDefault} />
+<Canvas of={DoWithCaption} />