@citizenplane/pimp 16.0.3 → 16.1.0

package/src/stories/CpItemActions.stories.ts

@@ -6,7 +6,7 @@ import type { MenuItem } from 'primevue/menuitem'
 import CpItemActions from '@/components/CpItemActions.vue'
 
 const meta = {
-  title: 'Menu/CpItemActions',
+  title: 'Molecules/CpItemActions',
   component: CpItemActions,
   argTypes: {
     actions: {
@@ -19,27 +19,19 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Contextual action menu attached to a list item. The `cp-item-actions-trigger`
+ * attribute on the parent element lets clicks through to the item while
+ * still opening the menu on the trigger button.
+ */
 export const Default: Story = {
   render: () => ({
     components: { CpItemActions },
     setup() {
-      const actions: MenuItem[] = ref([
-        {
-          icon: 'edit',
-          label: 'Action 1',
-          command: () => alert('Action 1 clicked'),
-        },
-        {
-          icon: 'download',
-          label: 'Action 3',
-          command: () => alert('Action 3 clicked'),
-        },
-        {
-          icon: 'trash-2',
-          label: 'Action 2',
-          command: () => alert('Action 2 clicked'),
-          isCritical: true,
-        },
+      const actions = ref<MenuItem[]>([
+        { icon: 'edit', label: 'Action 1', command: () => alert('Action 1 clicked') },
+        { icon: 'download', label: 'Action 3', command: () => alert('Action 3 clicked') },
+        { icon: 'trash-2', label: 'Action 2', command: () => alert('Action 2 clicked'), isCritical: true },
       ])
 
       const listItems = [1, 2, 3, 4]
@@ -57,15 +49,18 @@ export const Default: Story = {
     },
     template: `
       <div style="padding: 20px; display: flex; flex-direction: column; gap: 16px; min-width: 400px;">
-      <ul>
-        <li  v-for="(item, index) in listItems" :key="item" :style="listItemStyle" @click="parentClick" cp-item-actions-trigger>
-          <p>Item {{ index + 1 }}</p>
-          <CpItemActions
-            size="xs"
-            :actions="actions"
-          />
-        </li>
-      </ul>
+        <ul>
+          <li
+            v-for="(item, index) in listItems"
+            :key="item"
+            :style="listItemStyle"
+            cp-item-actions-trigger
+            @click="parentClick"
+          >
+            <p>Item {{ index + 1 }}</p>
+            <CpItemActions size="xs" :actions="actions" />
+          </li>
+        </ul>
       </div>
     `,
   }),

package/src/stories/CpLoader.stories.ts

@@ -2,18 +2,23 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 import CpLoader from '@/components/CpLoader.vue'
 
+import { docCellStyle, docLabelStyle, docRowWrapStyle } from '@/stories/documentationStyles'
+
+const loaderSizes = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const
+const loaderColors = ['neutral', 'accent', 'error', 'warning', 'success'] as const
+
 const meta = {
-  title: 'Visual/CpLoader',
+  title: 'Atoms/CpLoader',
   component: CpLoader,
   argTypes: {
     size: {
       control: 'select',
-      options: ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'],
+      options: loaderSizes,
       description: 'Size of the loader in pixels',
     },
     color: {
       control: 'select',
-      options: ['neutral', 'accent', 'error', 'warning', 'success'],
+      options: loaderColors,
       description: 'The color variant of the loader',
     },
     duration: {
@@ -26,8 +31,51 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default loader. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
-  args: {
-    color: 'neutral',
-  },
+  args: { color: 'neutral' },
+}
+
+/**
+ * Every size rendered side by side.
+ */
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpLoader },
+    setup() {
+      return { loaderSizes, docCellStyle, docLabelStyle, docRowWrapStyle }
+    },
+    template: `
+      <div :style="docRowWrapStyle">
+        <div v-for="size in loaderSizes" :key="size" :style="docCellStyle">
+          <span :style="docLabelStyle">{{ size }}</span>
+          <CpLoader :size="size" color="accent" />
+        </div>
+      </div>
+    `,
+  }),
+}
+
+/**
+ * All semantic colors rendered side by side.
+ */
+export const Colors: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpLoader },
+    setup() {
+      return { loaderColors, docCellStyle, docLabelStyle, docRowWrapStyle }
+    },
+    template: `
+      <div :style="docRowWrapStyle">
+        <div v-for="color in loaderColors" :key="color" :style="docCellStyle">
+          <span :style="docLabelStyle">{{ color }}</span>
+          <CpLoader :color="color" size="lg" />
+        </div>
+      </div>
+    `,
+  }),
 }

package/src/stories/CpMenuItem.stories.ts

@@ -2,8 +2,13 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 import CpMenuItem from '@/components/CpMenuItem.vue'
 
+import { docLabelStyle, docRowColumnStyle } from '@/stories/documentationStyles'
+
+const menuItemCellStyle = 'display: flex; flex-direction: column; gap: 8px; width: 260px;'
+const menuItemFrameStyle = 'width: 260px; border: 1px solid #e5e5e5; border-radius: 8px;'
+
 const meta = {
-  title: 'Menu/CpMenuItem',
+  title: 'Atoms/CpMenuItem',
   component: CpMenuItem,
   argTypes: {
     label: {
@@ -49,6 +54,9 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default menu item. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     label: 'Edit',
@@ -75,30 +83,48 @@ export const Default: Story = {
   }),
 }
 
-export const Critical: Story = {
-  args: {
-    ...Default.args,
-    label: 'Delete',
-    icon: 'trash-2',
-    isCritical: true,
-    command: () => alert('Delete clicked'),
-  },
-}
-
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    label: 'Archive',
-    icon: 'archive',
-    isDisabled: true,
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
 
-export const Loading: Story = {
-  args: {
-    ...Default.args,
-    label: 'Download',
-    icon: 'download',
-    isLoading: true,
-  },
+/**
+ * Every state available for a menu item: default, critical (destructive),
+ * disabled and loading.
+ */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpMenuItem },
+    setup() {
+      return { docRowColumnStyle, menuItemCellStyle, menuItemFrameStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="menuItemCellStyle">
+          <span :style="docLabelStyle">Default</span>
+          <div :style="menuItemFrameStyle">
+            <CpMenuItem label="Edit" icon="edit-3" />
+          </div>
+        </div>
+        <div :style="menuItemCellStyle">
+          <span :style="docLabelStyle">Critical</span>
+          <div :style="menuItemFrameStyle">
+            <CpMenuItem label="Delete" icon="trash-2" :is-critical="true" />
+          </div>
+        </div>
+        <div :style="menuItemCellStyle">
+          <span :style="docLabelStyle">Disabled</span>
+          <div :style="menuItemFrameStyle">
+            <CpMenuItem label="Archive" icon="archive" :is-disabled="true" />
+          </div>
+        </div>
+        <div :style="menuItemCellStyle">
+          <span :style="docLabelStyle">Loading</span>
+          <div :style="menuItemFrameStyle">
+            <CpMenuItem label="Download" icon="download" :is-loading="true" />
+          </div>
+        </div>
+      </div>
+    `,
+  }),
 }

package/src/stories/CpMultiselect.stories.ts

@@ -51,69 +51,33 @@ const airlineOptions: IOption[] = [
 ]
 
 const meta = {
-  title: 'Form/CpMultiSelect',
+  title: 'Organisms/CpMultiSelect',
   component: CpMultiselect,
   argTypes: {
-    label: {
-      control: 'text',
-      description: 'Label of the select',
-    },
-    required: {
-      control: 'boolean',
-      description: 'Whether the select is required',
-    },
-    name: {
-      control: 'text',
-      description: 'Name of the select',
-    },
-    placeholder: {
-      control: 'text',
-      description: 'Placeholder of the select',
-    },
-    isInvalid: {
-      control: 'boolean',
-      description: 'Whether the select is invalid',
-    },
-    multiple: {
-      control: 'boolean',
-      description: 'Whether the select should be multiple',
-    },
-    options: {
-      control: 'object',
-      description: 'Options of the select',
-    },
-    errorMessage: {
-      control: 'text',
-      description: 'Error message of the select',
-    },
-    disabled: {
-      control: 'boolean',
-      description: 'Whether the select is disabled',
-    },
-    isLoading: {
-      control: 'boolean',
-      description: 'Whether the select is loading',
-    },
-    emptyMessage: {
-      control: 'text',
-      description: 'Message displayed when no options are found',
-    },
-    trackBy: {
-      control: 'text',
-      description: 'Property to track the selected option',
-    },
-    size: {
-      control: 'select',
-      options: ['sm', 'md'],
-      description: 'Size of the multiselect',
-    },
+    label: { control: 'text', description: 'Label of the select' },
+    required: { control: 'boolean', description: 'Whether the select is required' },
+    name: { control: 'text', description: 'Name of the select' },
+    placeholder: { control: 'text', description: 'Placeholder of the select' },
+    isInvalid: { control: 'boolean', description: 'Whether the select is invalid' },
+    multiple: { control: 'boolean', description: 'Whether the select should be multiple' },
+    options: { control: 'object', description: 'Options of the select' },
+    errorMessage: { control: 'text', description: 'Error message of the select' },
+    disabled: { control: 'boolean', description: 'Whether the select is disabled' },
+    isLoading: { control: 'boolean', description: 'Whether the select is loading' },
+    emptyMessage: { control: 'text', description: 'Message displayed when no options are found' },
+    trackBy: { control: 'text', description: 'Property to track the selected option' },
+    size: { control: 'select', options: ['sm', 'md'], description: 'Size of the multiselect' },
   },
 } satisfies Meta<typeof CpMultiselect>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const DefaultSearchHandler: Story = {
+/**
+ * Single-value multiselect with the built-in search filter. The `#prefix`
+ * slot adds an icon before the input.
+ */
+export const Single: Story = {
   args: {
     placeholder: 'Select a supplier',
     multiple: false,
@@ -128,7 +92,7 @@ export const DefaultSearchHandler: Story = {
       return { args, selectedSupplier }
     },
     template: `
-      <div style="padding: 20px;width: 25rem;">
+      <div style="padding: 20px; width: 25rem;">
         <CpMultiselect v-model="selectedSupplier" v-bind="args">
           <template #prefix>
             <cp-partner-badge type="supplier" size="sm" />
@@ -139,7 +103,12 @@ export const DefaultSearchHandler: Story = {
   }),
 }
 
-export const Multiple: Story = {
+/**
+ * Multi-value selection with an async search handler. Selected options are
+ * rendered as chips and can be customized through `#tag-leading-icon` and
+ * `#option`.
+ */
+export const MultipleWithAsyncSearch: Story = {
   args: {
     required: false,
     name: 'select',
@@ -176,7 +145,7 @@ export const Multiple: Story = {
       return { args, selectedAirlines, dynamicOptions, handleSearch, isLoading }
     },
     template: `
-      <div style="padding: 20px;max-width: 25rem;">
+      <div style="padding: 20px; max-width: 25rem;">
         <CpMultiselect v-model="selectedAirlines" v-bind="args" :options="dynamicOptions" :is-loading="isLoading" @search="handleSearch">
           <template #prefix>
             <cp-partner-badge type="airline" size="sm" />
@@ -196,6 +165,10 @@ export const Multiple: Story = {
   }),
 }
 
+/**
+ * Invalid state with a label, required indicator and an error message
+ * underneath the input.
+ */
 export const Invalid: Story = {
   args: {
     placeholder: 'Select a supplier',
@@ -213,7 +186,7 @@ export const Invalid: Story = {
       return { args, selectedSupplier }
     },
     template: `
-      <div style="padding: 20px;max-width: 25rem;">
+      <div style="padding: 20px; max-width: 25rem;">
         <CpMultiselect v-model="selectedSupplier" v-bind="args">
           <template #prefix>
             <cp-partner-badge type="supplier" size="sm" />
@@ -230,6 +203,10 @@ export const Invalid: Story = {
   }),
 }
 
+/**
+ * Disabled state — the field is non-interactive and its menu cannot be
+ * opened.
+ */
 export const Disabled: Story = {
   args: {
     placeholder: 'Select a supplier',
@@ -244,7 +221,7 @@ export const Disabled: Story = {
       return { args, selectedSupplier }
     },
     template: `
-      <div style="padding: 20px;max-width: 25rem;">
+      <div style="padding: 20px; max-width: 25rem;">
         <CpMultiselect v-model="selectedSupplier" v-bind="args">
           <template #prefix>
             <cp-icon type="airport-terminal" size="16" />
@@ -261,6 +238,10 @@ export const Disabled: Story = {
   }),
 }
 
+/**
+ * Free-form tag input. `withoutTypeahead` removes the search affordance so
+ * users can enter arbitrary values that become chips.
+ */
 export const WithoutTypeahead: Story = {
   args: {
     placeholder: 'Select a supplier',
@@ -275,18 +256,18 @@ export const WithoutTypeahead: Story = {
       return { args, selectedSupplier }
     },
     template: `
-      <div style="padding: 20px;max-width: 25rem;">
+      <div style="padding: 20px; max-width: 25rem;">
         <CpMultiselect v-model="selectedSupplier" v-bind="args">
-        <template #chip="{ value, removeCallback }">
-          <slot name="tag" :option="value" :remove="removeCallback">
-            <cp-badge class="cpMultiselect__tag" is-clearable size="sm" @on-clear="removeCallback">
-              <template #leading-icon>
-                <slot name="tag-leading-icon" :option="value" />
-              </template>
-              {{ value }}
-            </cp-badge>
-          </slot>
-        </template>
+          <template #chip="{ value, removeCallback }">
+            <slot name="tag" :option="value" :remove="removeCallback">
+              <cp-badge class="cpMultiselect__tag" is-clearable size="sm" @on-clear="removeCallback">
+                <template #leading-icon>
+                  <slot name="tag-leading-icon" :option="value" />
+                </template>
+                {{ value }}
+              </cp-badge>
+            </slot>
+          </template>
           <template #tag="{ option, remove }">
             <cp-badge class="cpMultiselect__tag" is-clearable size="sm" @on-clear="remove">
               {{ option }}

package/src/stories/CpPartnerBadge.stories.ts

@@ -3,9 +3,12 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 import CpPartnerBadge from '@/components/CpPartnerBadge.vue'
 
 import { PartnerTypes } from '@/constants'
+import { docCellStyle, docLabelStyle, docRowWrapStyle } from '@/stories/documentationStyles'
+
+const partnerSizes = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl'] as const
 
 const meta = {
-  title: 'Visual/CpPartnerBadge',
+  title: 'Atoms/CpPartnerBadge',
   component: CpPartnerBadge,
   parameters: {
     docs: {
@@ -27,7 +30,7 @@ const meta = {
     },
     size: {
       control: 'select',
-      options: ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl'],
+      options: partnerSizes,
       description: 'The size of the badge',
       table: {
         type: { summary: 'string' },
@@ -50,6 +53,10 @@ const defaultRender = (args) => ({
   template: defaultTemplate,
 })
 
+/**
+ * Default partner badge. Use the controls to experiment with each prop in
+ * isolation.
+ */
 export const Default: Story = {
   args: {
     type: PartnerTypes.OTA,
@@ -57,86 +64,65 @@ export const Default: Story = {
   render: defaultRender,
 }
 
-export const OTA: Story = {
-  args: {
-    type: PartnerTypes.OTA,
-  },
-  render: defaultRender,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Partner badge for Online Travel Agencies (OTA) with orange background and OTA icon.',
-      },
-    },
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* Types                                                                      */
+/* -------------------------------------------------------------------------- */
 
-export const Airline: Story = {
-  args: {
-    type: PartnerTypes.AIRLINE,
-  },
-  render: defaultRender,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Partner badge for Airlines with blue background and airline icon.',
-      },
-    },
-  },
-}
-
-export const Supplier: Story = {
-  args: {
-    type: PartnerTypes.SUPPLIER,
-  },
-  render: defaultRender,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Partner badge for Suppliers with purple background and supplier icon.',
-      },
+/**
+ * Every partner type rendered side by side. Each type gets its own icon and
+ * background color.
+ */
+export const Types: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpPartnerBadge },
+    setup() {
+      const entries = Object.entries(PartnerTypes)
+      return { entries, docCellStyle, docLabelStyle, docRowWrapStyle }
     },
-  },
+    template: `
+      <div :style="docRowWrapStyle">
+        <div v-for="[name, type] in entries" :key="type" :style="docCellStyle">
+          <span :style="docLabelStyle">{{ name.toLowerCase() }}</span>
+          <CpPartnerBadge :type="type" />
+        </div>
+      </div>
+    `,
+  }),
 }
 
-export const ThirdParty: Story = {
-  args: {
-    type: PartnerTypes.THIRDPARTY,
-  },
-  render: defaultRender,
-  parameters: {
-    docs: {
-      description: {
-        story: 'Partner badge for Third Party partners with pink background and share icon.',
-      },
-    },
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* Sizes                                                                      */
+/* -------------------------------------------------------------------------- */
 
-export const AllTypes: Story = {
+/**
+ * All sizes rendered side by side, from `2xs` to `4xl`.
+ */
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpPartnerBadge },
     setup() {
-      return { PartnerTypes }
+      return { partnerSizes, PartnerTypes, docCellStyle, docLabelStyle, docRowWrapStyle }
     },
     template: `
-      <div style="display: flex; gap: 16px; align-items: center;">
-        <CpPartnerBadge :type="PartnerTypes.OTA" />
-        <CpPartnerBadge :type="PartnerTypes.AIRLINE" />
-        <CpPartnerBadge :type="PartnerTypes.SUPPLIER" />
-        <CpPartnerBadge :type="PartnerTypes.THIRDPARTY" />
+      <div :style="docRowWrapStyle">
+        <div v-for="size in partnerSizes" :key="size" :style="docCellStyle">
+          <span :style="docLabelStyle">{{ size }}</span>
+          <CpPartnerBadge :type="PartnerTypes.OTA" :size="size" />
+        </div>
       </div>
     `,
   }),
-  parameters: {
-    docs: {
-      description: {
-        story: 'All partner badge types displayed together for comparison.',
-      },
-    },
-  },
 }
 
+/* -------------------------------------------------------------------------- */
+/* Slots                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Override the default icon through the `#icon` slot.
+ */
 export const WithCustomIcon: Story = {
   render: () => ({
     components: { CpPartnerBadge },
@@ -151,11 +137,4 @@ export const WithCustomIcon: Story = {
       </CpPartnerBadge>
     `,
   }),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Partner badge with a custom icon using the icon slot.',
-      },
-    },
-  },
 }