@citizenplane/pimp 16.0.3 → 16.1.0

package/src/stories/CpCheckbox.stories.ts

@@ -4,8 +4,12 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 import CpCheckbox from '@/components/CpCheckbox.vue'
 
+import { docCellStyle, docLabelStyle, docRowWrapStyle } from '@/stories/documentationStyles'
+
+const checkboxColors = ['accent', 'blue'] as const
+
 const meta = {
-  title: 'Form/CpCheckbox',
+  title: 'Atoms/CpCheckbox',
   component: CpCheckbox,
   argTypes: {
     modelValue: {
@@ -30,7 +34,7 @@ const meta = {
     },
     color: {
       control: 'select',
-      options: ['accent', 'blue'],
+      options: checkboxColors,
       description: 'Color variant of the checkbox',
     },
     reverseLabel: {
@@ -55,6 +59,9 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default checkbox. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     checkboxLabel: 'checkbox label',
@@ -74,29 +81,85 @@ export const Default: Story = {
     },
     template: `
       <div style="padding: 20px;">
-        <CpCheckbox
-          v-model="value"
-          v-bind="args"
-        />
+        <CpCheckbox v-model="value" v-bind="args" />
       </div>
     `,
   }),
 }
 
-export const Checked: Story = {
-  args: {
-    ...Default.args,
-    modelValue: true,
-  },
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Every state available for the checkbox, compared side by side.
+ */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpCheckbox },
+    setup() {
+      return { docCellStyle, docLabelStyle, docRowWrapStyle }
+    },
+    template: `
+      <div :style="docRowWrapStyle">
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Unchecked</span>
+          <CpCheckbox :model-value="false" checkbox-label="Label" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Checked</span>
+          <CpCheckbox :model-value="true" checkbox-label="Label" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Indeterminate</span>
+          <CpCheckbox :model-value="false" :indeterminate="true" checkbox-label="Label" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Disabled</span>
+          <CpCheckbox :model-value="false" :is-disabled="true" checkbox-label="Label" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Disabled checked</span>
+          <CpCheckbox :model-value="true" :is-disabled="true" checkbox-label="Label" />
+        </div>
+      </div>
+    `,
+  }),
 }
 
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    isDisabled: true,
-  },
+/* -------------------------------------------------------------------------- */
+/* Colors                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Color variants rendered side by side.
+ */
+export const Colors: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpCheckbox },
+    setup() {
+      return { checkboxColors, docCellStyle, docLabelStyle, docRowWrapStyle }
+    },
+    template: `
+      <div :style="docRowWrapStyle">
+        <div v-for="color in checkboxColors" :key="color" :style="docCellStyle">
+          <span :style="docLabelStyle">{{ color }}</span>
+          <CpCheckbox :model-value="true" :color="color" checkbox-label="Label" />
+        </div>
+      </div>
+    `,
+  }),
 }
 
+/* -------------------------------------------------------------------------- */
+/* Variants                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Add a helper text below the label.
+ */
 export const WithHelper: Story = {
   args: {
     ...Default.args,
@@ -104,13 +167,9 @@ export const WithHelper: Story = {
   },
 }
 
-export const Blue: Story = {
-  args: {
-    ...Default.args,
-    color: 'blue',
-  },
-}
-
+/**
+ * Display the label before the checkbox using `reverseLabel`.
+ */
 export const Reversed: Story = {
   args: {
     ...Default.args,
@@ -118,7 +177,16 @@ export const Reversed: Story = {
   },
 }
 
-export const Indeterminate: Story = {
+/* -------------------------------------------------------------------------- */
+/* Group patterns                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Parent-child checkbox pattern using the `indeterminate` state to represent
+ * a partial selection.
+ */
+export const ParentChildGroup: Story = {
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpCheckbox },
     setup() {
@@ -175,7 +243,7 @@ export const Indeterminate: Story = {
           />
         </div>
         <div style="margin-top: 16px; padding: 12px; background: #f5f5f5; border-radius: 4px; font-size: 14px;">
-          <strong>Current state: </strong> 
+          <strong>Current state: </strong>
           <span v-if="parentState.indeterminate" style="color: #ff9800;">Indeterminate (some selected)</span>
           <span v-else-if="parentState.checked" style="color: #4caf50;">All selected</span>
           <span v-else style="color: #757575;">None selected</span>
@@ -185,7 +253,11 @@ export const Indeterminate: Story = {
   }),
 }
 
+/**
+ * Multiple checkboxes bound to the same v-model array act as a group.
+ */
 export const CheckboxGroup: Story = {
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpCheckbox },
     setup() {
@@ -217,6 +289,9 @@ export const CheckboxGroup: Story = {
   }),
 }
 
+/**
+ * Replace the label with custom content using the default slot.
+ */
 export const CustomContent: Story = {
   args: {
     ...Default.args,
@@ -230,10 +305,7 @@ export const CustomContent: Story = {
     },
     template: `
       <div style="padding: 20px;">
-        <CpCheckbox
-          v-model="value"
-          v-bind="args"
-        >
+        <CpCheckbox v-model="value" v-bind="args">
           <div style="display: flex; flex-direction: column; gap: 4px;">
             <span style="font-weight: 500;">Custom Content</span>
             <span style="font-size: 14px; color: #666;">With multiple lines and styling</span>

package/src/stories/CpContextualMenu.stories.ts

@@ -6,13 +6,13 @@ import CpButton from '@/components/CpButton.vue'
 import CpContextualMenu from '@/components/CpContextualMenu.vue'
 
 const meta = {
-  title: 'Menu/CpContextualMenu',
+  title: 'Molecules/CpContextualMenu',
   component: CpContextualMenu,
   parameters: {
     docs: {
       description: {
         component:
-          'A component that displays airline logos using IATA codes. Fetches logos from Kiwi.com CDN and displays them with customizable sizes.',
+          'A popover menu anchored to a trigger. Items support icons, critical styling, separators and async loading states.',
       },
     },
   },
@@ -26,14 +26,17 @@ const meta = {
       },
     },
   },
-  tags: ['autodocs'],
 } satisfies Meta<typeof CpContextualMenu>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Click the trigger to open a menu featuring an async "Download" action,
+ * a separator and a critical "Delete" action.
+ */
 export const Default: Story = {
-  render: (args) => ({
+  render: () => ({
     components: { CpButton, CpContextualMenu },
     setup() {
       const menu = ref<InstanceType<typeof CpContextualMenu>>()
@@ -53,9 +56,7 @@ export const Default: Story = {
             isLoading.value = false
           },
         },
-        {
-          separator: true,
-        },
+        { separator: true },
         {
           label: 'Delete',
           icon: 'trash-2',
@@ -64,7 +65,7 @@ export const Default: Story = {
         },
       ])
 
-      return { args, menu, showMenu, isLoading, items }
+      return { menu, showMenu, isLoading, items }
     },
     template: `
       <CpButton @click="showMenu">Open menu</CpButton>

package/src/stories/CpDate.stories.ts

@@ -4,8 +4,12 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 import CpDate from '@/components/CpDate.vue'
 
+import { docCellStyle, docLabelStyle, docRowColumnStyle } from '@/stories/documentationStyles'
+
+const dateStackStyle = `${docCellStyle} width: 100%; max-width: 360px;`
+
 const meta = {
-  title: 'Form/CpDate',
+  title: 'Atoms/CpDate',
   component: CpDate,
   argTypes: {
     size: {
@@ -63,6 +67,9 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default date input. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     label: 'Date',
@@ -89,33 +96,53 @@ export const Default: Story = {
   }),
 }
 
-export const Required: Story = {
-  args: {
-    ...Default.args,
-    label: 'Required Date',
-    required: true,
-    displayErrorMessage: false,
-  },
-}
-
-export const WithError: Story = {
-  args: {
-    ...Default.args,
-    label: 'Date with Error',
-    isInvalid: true,
-    required: true,
-    errorMessage: 'Please enter a valid date',
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
 
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    label: 'Disabled Date',
-    disabled: true,
-  },
+/**
+ * Default, required, disabled and invalid states compared side by side.
+ */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpDate },
+    setup() {
+      const date = ref('')
+      return { date, docRowColumnStyle, dateStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="dateStackStyle">
+          <span :style="docLabelStyle">Default</span>
+          <CpDate v-model="date" label="Date" />
+        </div>
+        <div :style="dateStackStyle">
+          <span :style="docLabelStyle">Required</span>
+          <CpDate v-model="date" label="Date" :required="true" :display-error-message="false" />
+        </div>
+        <div :style="dateStackStyle">
+          <span :style="docLabelStyle">Disabled</span>
+          <CpDate v-model="date" label="Date" :disabled="true" />
+        </div>
+        <div :style="dateStackStyle">
+          <span :style="docLabelStyle">Invalid</span>
+          <CpDate
+            v-model="date"
+            label="Date"
+            :is-invalid="true"
+            :required="true"
+            error-message="Please enter a valid date"
+          />
+        </div>
+      </div>
+    `,
+  }),
 }
 
+/**
+ * Combines a date input with a text input on the same line.
+ */
 export const NextToInput: Story = {
   args: {
     label: 'Date',

package/src/stories/CpDatepicker.stories.ts

@@ -1,86 +1,59 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Args, Meta, StoryObj } from '@storybook/vue3'
 
 import CpDatepicker from '@/components/CpDatepicker.vue'
 
+const datepickerModes = ['single', 'range'] as const
+
 const meta = {
-  title: 'Form/CpDatepicker',
+  title: 'Organisms/CpDatepicker',
   component: CpDatepicker,
-
   argTypes: {
     mode: {
       control: 'select',
-      options: ['single', 'range'],
+      options: datepickerModes,
       description: 'Selection mode: single date or date range',
     },
     closeAfterSelect: {
       control: 'boolean',
       description: 'Whether to close the picker after selection',
     },
-    label: {
-      control: 'text',
-      description: 'Label text for the datepicker',
-    },
-    placeholder: {
-      control: 'text',
-      description: 'Placeholder text for the input',
-    },
-    isError: {
-      control: 'boolean',
-      description: 'Whether the field is in an invalid state',
-    },
-    errorMessage: {
-      control: 'text',
-      description: 'Custom error message to display',
-    },
-    initDateOne: {
-      control: 'text',
-      description: 'Initial first date (YYYY-MM-DD)',
-    },
-    initDateTwo: {
-      control: 'text',
-      description: 'Initial second date for range mode (YYYY-MM-DD)',
-    },
-    minDate: {
-      control: 'text',
-      description: 'Minimum allowed date',
-    },
-    maxDate: {
-      control: 'text',
-      description: 'Maximum allowed date',
-    },
-    allowPastDates: {
-      control: 'boolean',
-      description: 'Whether to allow selecting past dates',
-    },
-    isInline: {
-      control: 'boolean',
-      description: 'Whether to display the picker inline',
-    },
-    singleMonth: {
-      control: 'boolean',
-      description: 'Whether to show only one month',
-    },
-    locale: {
-      control: 'text',
-      description: 'Locale for date formatting',
-    },
+    label: { control: 'text', description: 'Label text for the datepicker' },
+    placeholder: { control: 'text', description: 'Placeholder text for the input' },
+    isError: { control: 'boolean', description: 'Whether the field is in an invalid state' },
+    errorMessage: { control: 'text', description: 'Custom error message to display' },
+    initDateOne: { control: 'text', description: 'Initial first date (YYYY-MM-DD)' },
+    initDateTwo: { control: 'text', description: 'Initial second date for range mode (YYYY-MM-DD)' },
+    minDate: { control: 'text', description: 'Minimum allowed date' },
+    maxDate: { control: 'text', description: 'Maximum allowed date' },
+    allowPastDates: { control: 'boolean', description: 'Whether to allow selecting past dates' },
+    isInline: { control: 'boolean', description: 'Whether to display the picker inline' },
+    singleMonth: { control: 'boolean', description: 'Whether to show only one month' },
+    locale: { control: 'text', description: 'Locale for date formatting' },
   },
 } satisfies Meta<typeof CpDatepicker>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-const defaultTemplate = `
-  <div style="height: 35vh; max-width: 600px; padding: 20px;">
-    <CpDatepicker
-      v-bind="args"
-      @dates="(selectedDates) => dates = selectedDates"
-    />
-  </div>
-`
+const datepickerRender = (args: Args) => ({
+  components: { CpDatepicker },
+  setup() {
+    const dates = ref([])
+    return { args, dates }
+  },
+  template: `
+    <div style="height: 35vh; max-width: 600px; padding: 20px;">
+      <CpDatepicker v-bind="args" @dates="(selectedDates) => dates = selectedDates" />
+    </div>
+  `,
+})
 
+/**
+ * Default single-date picker. Use the controls to experiment with each
+ * prop in isolation.
+ */
 export const Default: Story = {
   args: {
     mode: 'single',
@@ -91,16 +64,12 @@ export const Default: Story = {
     isInline: false,
     singleMonth: false,
   },
-  render: (args) => ({
-    components: { CpDatepicker },
-    setup() {
-      const dates = ref([])
-      return { args, dates }
-    },
-    template: defaultTemplate,
-  }),
+  render: datepickerRender,
 }
 
+/**
+ * Range mode lets the user pick a start and end date.
+ */
 export const DateRange: Story = {
   args: {
     ...Default.args,
@@ -108,12 +77,12 @@ export const DateRange: Story = {
     label: 'Select Date Range',
     placeholder: 'Choose date range',
   },
-  render: (args) => ({
-    ...Default.render(args),
-    template: defaultTemplate,
-  }),
+  render: datepickerRender,
 }
 
+/**
+ * Invalid state with a custom error message.
+ */
 export const WithError: Story = {
   args: {
     ...Default.args,
@@ -121,44 +90,44 @@ export const WithError: Story = {
     isError: true,
     errorMessage: 'Please select a valid date',
   },
-  render: (args) => ({
-    ...Default.render(args),
-    template: defaultTemplate,
-  }),
+  render: datepickerRender,
 }
 
+/**
+ * Pre-populate the picker with an initial date through `initDateOne`
+ * (and `initDateTwo` in range mode).
+ */
 export const WithInitialDates: Story = {
   args: {
     ...Default.args,
     initDateOne: '2024-03-15',
     label: 'Datepicker with Initial Date',
   },
-  render: (args) => ({
-    ...Default.render(args),
-    template: defaultTemplate,
-  }),
+  render: datepickerRender,
 }
 
+/**
+ * Show a single month at a time instead of the default two-month layout —
+ * useful for narrow spaces.
+ */
 export const SingleMonth: Story = {
   args: {
     ...Default.args,
     singleMonth: true,
     label: 'Single Month View',
   },
-  render: (args) => ({
-    ...Default.render(args),
-    template: defaultTemplate,
-  }),
+  render: datepickerRender,
 }
 
+/**
+ * By default the picker blocks past dates. Set `allowPastDates` to `true`
+ * to let the user pick any date.
+ */
 export const AllowPastDates: Story = {
   args: {
     ...Default.args,
     allowPastDates: true,
     label: 'Allow Past Dates',
   },
-  render: (args) => ({
-    ...Default.render(args),
-    template: defaultTemplate,
-  }),
+  render: datepickerRender,
 }

package/src/stories/CpDialog.stories.ts

@@ -5,7 +5,7 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 import CpDialog from '@/components/CpDialog.vue'
 
 const meta = {
-  title: 'Navigation/CpDialog',
+  title: 'Organisms/CpDialog',
   component: CpDialog,
   argTypes: {
     maxWidth: {
@@ -19,6 +19,11 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default dialog featuring every common part: title and subtitle slots,
+ * body content and a footer slot. Use the controls to experiment with each
+ * prop in isolation.
+ */
 export const Default: Story = {
   args: {
     maxWidth: 600,
@@ -47,6 +52,10 @@ export const Default: Story = {
   }),
 }
 
+/**
+ * Pass the title and subtitle as plain strings through props instead of
+ * slots — the simplest way to compose a dialog.
+ */
 export const TitleSubtitleWithProps: Story = {
   args: {
     maxWidth: 600,
@@ -73,6 +82,9 @@ export const TitleSubtitleWithProps: Story = {
   }),
 }
 
+/**
+ * Dialog with only body content — no title, subtitle or header.
+ */
 export const ContentOnly: Story = {
   args: {
     maxWidth: 600,
@@ -96,6 +108,11 @@ export const ContentOnly: Story = {
   }),
 }
 
+/**
+ * Provide rich title and subtitle through slots. Use `titleTag`/
+ * `subtitleTag` to change the underlying element (e.g. `div` to allow
+ * flex content).
+ */
 export const TitleSubtitleWithSlots: Story = {
   args: {
     maxWidth: 560,
@@ -132,6 +149,10 @@ export const TitleSubtitleWithSlots: Story = {
   }),
 }
 
+/**
+ * Enable `isClosableOnClickOutside` so the dialog dismisses when the user
+ * clicks the backdrop.
+ */
 export const ClosableOnClickOutside: Story = {
   args: {
     maxWidth: 600,