@ouestfrance/sipa-bms-ui 8.22.1 → 8.22.3

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} />

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} />