@ouestfrance/sipa-bms-ui 8.22.2 → 8.22.3

package/src/components/table/BmsTable.stories.js

@@ -1,11 +1,15 @@
 import BmsTable from '@/components/table/BmsTable.vue';
 import BmsButton from '@/components/button/BmsButton.vue';
 import BmsIconButton from '@/components/button/BmsIconButton.vue';
-import { Save, Trash } from 'lucide-vue-next';
+import { BmsTag } from '@/index';
+import { Save, Trash, Pencil } from 'lucide-vue-next';
 
 export default {
   title: 'Composants/table/Table',
   component: BmsTable,
+  parameters: {
+    chromatic: { disable: true },
+  },
   argTypes: {
     disableSearch: {
       control: { type: 'boolean' },
@@ -1088,3 +1092,245 @@ WithActionColumnAndChildElement.args = {
   selectedItems: [],
   selectable: true,
 };
+
+// Simple template for documentation
+const SimpleTemplate = (args) => ({
+  components: {
+    BmsTable,
+    BmsButton,
+    BmsTag,
+  },
+  setup() {
+    return { args };
+  },
+  template: `
+  <BmsTable v-bind="args">
+    <template v-if="args.hasCustomAction" #custom-action>
+      <div style="display: flex; gap: 8px;">
+        <BmsTag 
+          v-for="tag in args.filterTags" 
+          :key="tag.id"
+          :active="tag.active"
+          @click="tag.onClick"
+        >
+          {{ tag.label }}
+        </BmsTag>
+      </div>
+    </template>
+  </BmsTable>
+  `,
+});
+
+// Common headers and items for documentation examples
+const commonHeaders = [
+  {
+    label: 'Name',
+    key: 'name',
+    align: 'start',
+    sortable: true,
+  },
+  {
+    label: 'Email',
+    key: 'email',
+    align: 'start',
+  },
+  {
+    label: 'Status',
+    key: 'status',
+    align: 'center',
+  },
+];
+
+const commonItems = [
+  { name: 'John Doe', email: 'john@example.com', status: 'Active' },
+  { name: 'Jane Smith', email: 'jane@example.com', status: 'Active' },
+  { name: 'Bob Johnson', email: 'bob@example.com', status: 'Inactive' },
+  { name: 'Alice Williams', email: 'alice@example.com', status: 'Active' },
+  { name: 'Charlie Brown', email: 'charlie@example.com', status: 'Pending' },
+];
+
+// Playground with default values for documentation
+export const PlaygroundTable = SimpleTemplate.bind({});
+PlaygroundTable.parameters = { chromatic: { disable: true } };
+PlaygroundTable.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [],
+  hasCustomAction: false,
+};
+
+// Do: Table with search
+export const DoWithSearch = SimpleTemplate.bind({});
+DoWithSearch.parameters = { chromatic: { disable: true } };
+DoWithSearch.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [],
+  hasCustomAction: false,
+};
+
+// Do: Table without search
+export const DoWithoutSearch = SimpleTemplate.bind({});
+DoWithoutSearch.parameters = { chromatic: { disable: true } };
+DoWithoutSearch.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: true,
+  filters: [],
+  hasCustomAction: false,
+};
+
+// Do: Table with filters
+export const DoWithFilters = SimpleTemplate.bind({});
+DoWithFilters.parameters = { chromatic: { disable: true } };
+DoWithFilters.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [
+    {
+      label: 'Status',
+      key: 'status',
+      type: 'select',
+      selectOptions: [
+        { label: 'Active', value: 'Active' },
+        { label: 'Inactive', value: 'Inactive' },
+        { label: 'Pending', value: 'Pending' },
+      ],
+    },
+  ],
+  hasCustomAction: false,
+};
+
+// Do: Table without filters
+export const DoWithoutFilters = SimpleTemplate.bind({});
+DoWithoutFilters.parameters = { chromatic: { disable: true } };
+DoWithoutFilters.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [],
+  hasCustomAction: false,
+};
+
+// Do: Table with custom actions (filter tags)
+export const DoWithCustomActions = SimpleTemplate.bind({});
+DoWithCustomActions.parameters = { chromatic: { disable: true } };
+DoWithCustomActions.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [],
+  hasCustomAction: true,
+  filterTags: [
+    { id: '1', label: 'Active', active: true, onClick: () => {} },
+    { id: '2', label: 'Inactive', active: false, onClick: () => {} },
+    { id: '3', label: 'Pending', active: false, onClick: () => {} },
+  ],
+};
+
+// Do: Table with action icons
+const TemplateWithActionIcons = (args) => ({
+  components: {
+    BmsTable,
+    BmsIconButton,
+    Pencil,
+    Trash,
+  },
+  setup() {
+    return { args };
+  },
+  template: `
+  <BmsTable v-bind="args">
+    <template #actions="{ row, isChildElement }">
+      <template v-if="isChildElement">
+        <span style="color: var(--bms-grey-50);">No actions</span>
+      </template>
+      <template v-else>
+        <div style="display: flex; gap: 8px;">
+          <BmsIconButton><Pencil/></BmsIconButton>
+          <BmsIconButton mode="danger"><Trash/></BmsIconButton>
+        </div>
+      </template>
+    </template>
+  </BmsTable>
+  `,
+});
+
+export const DoWithActionIcons = TemplateWithActionIcons.bind({});
+DoWithActionIcons.args = {
+  headers: [
+    ...commonHeaders,
+    {
+      label: 'Actions',
+      key: 'actions',
+      action: true,
+    },
+  ],
+  items: commonItems,
+  disableSearch: false,
+  filters: [],
+};
+
+// Do: Table with search and filters
+export const DoWithSearchAndFilters = SimpleTemplate.bind({});
+DoWithSearchAndFilters.parameters = { chromatic: { disable: true } };
+DoWithSearchAndFilters.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [
+    {
+      label: 'Status',
+      key: 'status',
+      type: 'select',
+      selectOptions: [
+        { label: 'Active', value: 'Active' },
+        { label: 'Inactive', value: 'Inactive' },
+        { label: 'Pending', value: 'Pending' },
+      ],
+    },
+  ],
+  hasCustomAction: false,
+};
+
+// Do: Table with search, filters and actions
+export const DoWithSearchFiltersAndActions = SimpleTemplate.bind({});
+DoWithSearchFiltersAndActions.parameters = { chromatic: { disable: true } };
+DoWithSearchFiltersAndActions.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [
+    {
+      label: 'Status',
+      key: 'status',
+      type: 'select',
+      selectOptions: [
+        { label: 'Active', value: 'Active' },
+        { label: 'Inactive', value: 'Inactive' },
+        { label: 'Pending', value: 'Pending' },
+      ],
+    },
+  ],
+  hasCustomAction: true,
+  filterTags: [
+    { id: '1', label: 'Active', active: true, onClick: () => {} },
+    { id: '2', label: 'Inactive', active: false, onClick: () => {} },
+  ],
+};
+
+// Do: Table with row selection
+export const DoWithRowSelection = SimpleTemplate.bind({});
+DoWithRowSelection.parameters = { chromatic: { disable: true } };
+DoWithRowSelection.args = {
+  headers: commonHeaders,
+  items: commonItems,
+  disableSearch: false,
+  filters: [],
+  hasCustomAction: false,
+  selectable: true,
+  selectedItems: [],
+};

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