@citizenplane/pimp 16.0.3 → 16.1.0

package/src/stories/CpRadio.stories.ts

@@ -4,8 +4,10 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 import CpRadio from '@/components/CpRadio.vue'
 
+const radioColors = ['accent', 'blue'] as const
+
 const meta = {
-  title: 'Form/CpRadio',
+  title: 'Atoms/CpRadio',
   component: CpRadio,
   argTypes: {
     modelValue: {
@@ -22,7 +24,7 @@ const meta = {
     },
     color: {
       control: 'select',
-      options: ['accent', 'blue'],
+      options: radioColors,
       description: 'Color variant of the radio',
     },
     autofocus: {
@@ -41,6 +43,23 @@ const sampleOptions = [
   { value: 'option3', label: 'Option 3' },
 ]
 
+const wrappedRender = (args: { modelValue?: string }) => ({
+  components: { CpRadio },
+  setup() {
+    const value = ref(args.modelValue)
+    return { args, value }
+  },
+  template: `
+    <div style="min-width: 400px; padding: 20px;">
+      <CpRadio v-model="value" v-bind="args" />
+    </div>
+  `,
+})
+
+/**
+ * Default radio group with three plain options. Use the controls to
+ * experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     modelValue: 'option1',
@@ -49,23 +68,13 @@ export const Default: Story = {
     color: 'accent',
     autofocus: false,
   },
-  render: (args) => ({
-    components: { CpRadio },
-    setup() {
-      const value = ref(args.modelValue)
-      return { args, value }
-    },
-    template: `
-      <div style="min-width: 400px; padding: 20px;">
-        <CpRadio
-          v-model="value"
-          v-bind="args"
-        />
-      </div>
-    `,
-  }),
+  render: wrappedRender,
 }
 
+/**
+ * Each option can provide a secondary `description` displayed under the
+ * label — great for presenting plans or multi-line choices.
+ */
 export const WithDescriptions: Story = {
   args: {
     ...Default.args,
@@ -77,6 +86,10 @@ export const WithDescriptions: Story = {
   },
 }
 
+/**
+ * Append a right-aligned piece of information through `additionalData`
+ * (e.g. price, unit, shortcut).
+ */
 export const WithAdditionalData: Story = {
   args: {
     ...Default.args,
@@ -88,7 +101,11 @@ export const WithAdditionalData: Story = {
   },
 }
 
-export const WithDisabledOptions: Story = {
+/**
+ * Disable individual options using their `disabled` flag — the value stays
+ * selectable on other rows.
+ */
+export const WithDisabledOption: Story = {
   args: {
     ...Default.args,
     options: [
@@ -97,23 +114,13 @@ export const WithDisabledOptions: Story = {
       { value: 'option3', label: 'Option 3' },
     ],
   },
-  render: (args) => ({
-    components: { CpRadio },
-    setup() {
-      const value = ref(args.modelValue)
-      return { args, value }
-    },
-    template: `
-      <div style="min-width: 400px; padding: 20px;">
-        <CpRadio
-          v-model="value"
-          v-bind="args"
-        />
-      </div>
-    `,
-  }),
+  render: wrappedRender,
 }
 
+/**
+ * A disabled option can still be the current value — useful when the user
+ * cannot change a pre-selected choice.
+ */
 export const CheckedDisabled: Story = {
   args: {
     ...Default.args,
@@ -124,23 +131,12 @@ export const CheckedDisabled: Story = {
     ],
     modelValue: 'option1',
   },
-  render: (args) => ({
-    components: { CpRadio },
-    setup() {
-      const value = ref(args.modelValue)
-      return { args, value }
-    },
-    template: `
-      <div style="min-width: 400px; padding: 20px;">
-        <CpRadio
-          v-model="value"
-          v-bind="args"
-        />
-      </div>
-    `,
-  }),
+  render: wrappedRender,
 }
 
+/**
+ * Combine `description` and `additionalData` for rich option rows.
+ */
 export const ComplexOptions: Story = {
   args: {
     ...Default.args,

package/src/stories/CpRadioGroup.stories.ts

@@ -4,8 +4,11 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 import CpRadioGroup from '@/components/CpRadioGroup.vue'
 
+const radioGroupSizes = ['md', 'lg'] as const
+const radioGroupDirections = ['vertical', 'horizontal'] as const
+
 const meta = {
-  title: 'Form/CpRadioGroup',
+  title: 'Molecules/CpRadioGroup',
   component: CpRadioGroup,
   argTypes: {
     modelValue: {
@@ -26,7 +29,7 @@ const meta = {
     },
     direction: {
       control: 'select',
-      options: ['vertical', 'horizontal'],
+      options: radioGroupDirections,
       description: 'Stack options vertically or place them in a row',
     },
     groupLabel: {
@@ -43,7 +46,7 @@ const meta = {
     },
     size: {
       control: 'select',
-      options: ['md', 'lg'],
+      options: radioGroupSizes,
       description: 'The size of the radio',
     },
   },
@@ -58,6 +61,23 @@ const sampleOptions = [
   { value: 'option3', label: 'Option 3' },
 ]
 
+const wrappedRender = (args: { modelValue?: string }) => ({
+  components: { CpRadioGroup },
+  setup() {
+    const value = ref(args.modelValue)
+    return { args, value }
+  },
+  template: `
+    <div style="min-width: 800px; padding: 20px;">
+      <CpRadioGroup v-model="value" v-bind="args" />
+    </div>
+  `,
+})
+
+/**
+ * Default radio group, stacked vertically. Use the controls to experiment
+ * with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     modelValue: 'option1',
@@ -78,16 +98,16 @@ export const Default: Story = {
     },
     template: `
       <div style="min-width: 800px; padding: 20px;">
-        <CpRadioGroup
-          v-model="value"
-          v-bind="args"
-        />
-        <p style="margin-top: 24px;font-size:12px;">modelValue: <code>{{ value }}</code></p>
+        <CpRadioGroup v-model="value" v-bind="args" />
+        <p style="margin-top: 24px; font-size: 12px;">modelValue: <code>{{ value }}</code></p>
       </div>
     `,
   }),
 }
 
+/**
+ * Arrange the options on a single row with `direction="horizontal"`.
+ */
 export const Horizontal: Story = {
   args: {
     ...Default.args,
@@ -95,6 +115,10 @@ export const Horizontal: Story = {
   },
 }
 
+/**
+ * Add a visible label and helper text describing the whole group. Setting
+ * `required` puts the asterisk on the group label.
+ */
 export const WithGroupLabel: Story = {
   args: {
     ...Default.args,
@@ -104,6 +128,10 @@ export const WithGroupLabel: Story = {
   },
 }
 
+/**
+ * Attach a `helperText` to individual options — useful for short
+ * explanations next to each choice.
+ */
 export const WithHelperText: Story = {
   args: {
     ...Default.args,
@@ -115,7 +143,10 @@ export const WithHelperText: Story = {
   },
 }
 
-export const WithDisabledOptions: Story = {
+/**
+ * Disable individual options; the rest of the group stays selectable.
+ */
+export const WithDisabledOption: Story = {
   args: {
     ...Default.args,
     options: [
@@ -124,23 +155,13 @@ export const WithDisabledOptions: Story = {
       { value: 'option3', label: 'Option 3' },
     ],
   },
-  render: (args) => ({
-    components: { CpRadioGroup },
-    setup() {
-      const value = ref(args.modelValue)
-      return { args, value }
-    },
-    template: `
-      <div style="min-width: 800px; padding: 20px;">
-        <CpRadioGroup
-          v-model="value"
-          v-bind="args"
-        />
-      </div>
-    `,
-  }),
+  render: wrappedRender,
 }
 
+/**
+ * A disabled option can still be the current value. Use this pattern for
+ * read-only pre-selections.
+ */
 export const CheckedDisabled: Story = {
   args: {
     ...Default.args,
@@ -151,19 +172,5 @@ export const CheckedDisabled: Story = {
     ],
     modelValue: 'option1',
   },
-  render: (args) => ({
-    components: { CpRadioGroup },
-    setup() {
-      const value = ref(args.modelValue)
-      return { args, value }
-    },
-    template: `
-      <div style="min-width: 800px; padding: 20px;">
-        <CpRadioGroup
-          v-model="value"
-          v-bind="args"
-        />
-      </div>
-    `,
-  }),
+  render: wrappedRender,
 }

package/src/stories/CpSelect.stories.ts

@@ -5,8 +5,14 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 import CpInput from '@/components/CpInput.vue'
 import CpSelect from '@/components/CpSelect.vue'
 
+import { docCellStyle, docLabelStyle, docRowColumnStyle } from '@/stories/documentationStyles'
+
+const selectSizes = ['sm', 'md', 'lg'] as const
+
+const selectStackStyle = `${docCellStyle} width: 100%; max-width: 360px;`
+
 const meta = {
-  title: 'Form/CpSelect',
+  title: 'Molecules/CpSelect',
   component: CpSelect,
   argTypes: {
     modelValue: {
@@ -47,7 +53,7 @@ const meta = {
     },
     size: {
       control: 'select',
-      options: ['sm', 'md', 'lg'],
+      options: selectSizes,
       description: 'The size of the select',
     },
     autocomplete: {
@@ -79,6 +85,9 @@ const sampleOptions = [
   { value: '4', label: 'Option 4' },
 ]
 
+/**
+ * Default select. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     label: 'Select Label',
@@ -101,51 +110,97 @@ export const Default: Story = {
     },
     template: `
       <div style="max-width: 400px; padding: 20px;">
-        <CpSelect
-          v-model="value"
-          v-bind="args"
-        />
+        <CpSelect v-model="value" v-bind="args" />
       </div>
     `,
   }),
 }
 
-export const WithError: Story = {
-  args: {
-    ...Default.args,
-    isInvalid: true,
-    errorMessage: 'This field is required',
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* Sizes                                                                      */
+/* -------------------------------------------------------------------------- */
 
-export const Required: Story = {
-  args: {
-    ...Default.args,
-    required: true,
-  },
+/**
+ * All sizes rendered side by side, from `sm` to `lg`.
+ */
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpSelect },
+    setup() {
+      const value = ref('3')
+      return { value, sampleOptions, selectSizes, docRowColumnStyle, selectStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div v-for="size in selectSizes" :key="size" :style="selectStackStyle">
+          <span :style="docLabelStyle">{{ size }}</span>
+          <CpSelect
+            v-model="value"
+            :size="size"
+            label="Select label"
+            :options="sampleOptions"
+            name="select-field"
+          />
+        </div>
+      </div>
+    `,
+  }),
 }
 
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    disabled: true,
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
 
-export const Small: Story = {
-  args: {
-    ...Default.args,
-    size: 'sm',
-  },
+/**
+ * Default, required, disabled and invalid states compared side by side.
+ */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpSelect },
+    setup() {
+      const value = ref('3')
+      return { value, sampleOptions, docRowColumnStyle, selectStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="selectStackStyle">
+          <span :style="docLabelStyle">Default</span>
+          <CpSelect v-model="value" label="Select label" :options="sampleOptions" name="s-default" />
+        </div>
+        <div :style="selectStackStyle">
+          <span :style="docLabelStyle">Required</span>
+          <CpSelect v-model="value" label="Select label" :options="sampleOptions" :required="true" name="s-required" />
+        </div>
+        <div :style="selectStackStyle">
+          <span :style="docLabelStyle">Disabled</span>
+          <CpSelect v-model="value" label="Select label" :options="sampleOptions" :disabled="true" name="s-disabled" />
+        </div>
+        <div :style="selectStackStyle">
+          <span :style="docLabelStyle">Invalid</span>
+          <CpSelect
+            v-model="value"
+            label="Select label"
+            :options="sampleOptions"
+            :is-invalid="true"
+            error-message="This field is required"
+            name="s-invalid"
+          />
+        </div>
+      </div>
+    `,
+  }),
 }
 
-export const Large: Story = {
-  args: {
-    ...Default.args,
-    size: 'lg',
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* Misc                                                                       */
+/* -------------------------------------------------------------------------- */
 
+/**
+ * Hides the default "Select an option" entry. Use this when an option must
+ * always be picked.
+ */
 export const WithoutDefaultOption: Story = {
   args: {
     ...Default.args,
@@ -153,6 +208,9 @@ export const WithoutDefaultOption: Story = {
   },
 }
 
+/**
+ * Long option labels are truncated with an ellipsis.
+ */
 export const WithLongOptions: Story = {
   args: {
     ...Default.args,
@@ -165,6 +223,10 @@ export const WithLongOptions: Story = {
   },
 }
 
+/**
+ * Combines a select and an input on the same line — for example a currency
+ * and an amount.
+ */
 export const NextToInput: Story = {
   args: {
     ...Default.args,
@@ -180,10 +242,7 @@ export const NextToInput: Story = {
     },
     template: `
       <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 10px; max-width: 400px; padding: 20px;">
-        <CpSelect
-          v-model="value"
-          v-bind="args"
-        />
+        <CpSelect v-model="value" v-bind="args" />
         <CpInput :size="args.size" label="Input Label" name="input-field" placeholder="Enter text here" v-model="textValue" />
       </div>
     `,

package/src/stories/CpSelectMenu.stories.ts

@@ -5,39 +5,21 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 import CpSelectMenu from '@/components/CpSelectMenu.vue'
 
 const meta = {
-  title: 'Form/CpSelectMenu',
+  title: 'Molecules/CpSelectMenu',
   component: CpSelectMenu,
   argTypes: {
-    values: {
-      control: 'object',
-      description: 'Array of options to display',
-    },
-    selectedValue: {
-      control: 'object',
-      description: 'Currently selected value',
-    },
-    hasFilter: {
-      control: 'boolean',
-      description: 'Whether to show search filter',
-    },
-    dropdownTitle: {
-      control: 'text',
-      description: 'Title text for the dropdown',
-    },
-    dropdownFilterPlaceholder: {
-      control: 'text',
-      description: 'Placeholder text for the filter input',
-    },
+    values: { control: 'object', description: 'Array of options to display' },
+    selectedValue: { control: 'object', description: 'Currently selected value' },
+    hasFilter: { control: 'boolean', description: 'Whether to show search filter' },
+    dropdownTitle: { control: 'text', description: 'Title text for the dropdown' },
+    dropdownFilterPlaceholder: { control: 'text', description: 'Placeholder text for the filter input' },
     dropdownEmptyViewPlaceholder: {
       control: 'text',
       description: 'Text to show when no options match the filter',
     },
-    closeOnSelect: {
-      control: 'boolean',
-      description: 'Whether to close dropdown after selection',
-    },
+    closeOnSelect: { control: 'boolean', description: 'Whether to close dropdown after selection' },
   },
-  decorators: [() => ({ template: '<div style="min-height: 30vh;"><story/></div>' })],
+  decorators: [() => ({ template: '<div style="min-height: 30vh;"><story /></div>' })],
 } satisfies Meta<typeof CpSelectMenu>
 
 export default meta
@@ -53,6 +35,10 @@ const sampleOptions = [
   { value: '7', label: 'Cherry' },
 ]
 
+/**
+ * Default select menu. Use the controls to experiment with each prop in
+ * isolation.
+ */
 export const Default: Story = {
   args: {
     values: sampleOptions,
@@ -79,53 +65,59 @@ export const Default: Story = {
       </div>
     `,
     methods: {
-      onUpdateSelectedValue: (data) => {
+      onUpdateSelectedValue(data: unknown) {
         args.selectedValue = data
       },
     },
   }),
 }
 
-const searchQuery = ref('')
-
+/**
+ * Enable `hasFilter` to render a search input above the list. The
+ * `@on-filter-change` event lets the caller filter its own options list.
+ */
 export const WithFilter: Story = {
   args: {
     ...Default.args,
     hasFilter: true,
     dropdownTitle: 'Search for a fruit',
-    selectedValue: { value: '1', label: 'Apple' },
-    values: sampleOptions,
   },
-  render: (args) => ({
-    components: { CpSelectMenu },
-    setup() {
-      const selectedValue = ref(args.selectedValue)
-      return { args, selectedValue }
-    },
-    template: `
-      <div style="max-width: 400px; padding: 20px;">
-        <CpSelectMenu
-          v-model:selectedValue="selectedValue"
-          v-bind="args"
-          @on-filter-change="onFilterChange"
-          @update:selected-value="onUpdateSelectedValue"
-        />
-      </div>
-    `,
-    methods: {
-      onFilterChange: (data) => {
-        searchQuery.value = data
-        args.values = sampleOptions.filter((option) =>
-          option.label.toLowerCase().includes(searchQuery.value.toLowerCase()),
-        )
+  render: (args) => {
+    const searchQuery = ref('')
+    return {
+      components: { CpSelectMenu },
+      setup() {
+        const selectedValue = ref(args.selectedValue)
+        return { args, selectedValue }
       },
-      onUpdateSelectedValue: (data) => {
-        args.selectedValue = data
+      template: `
+        <div style="max-width: 400px; padding: 20px;">
+          <CpSelectMenu
+            v-model:selectedValue="selectedValue"
+            v-bind="args"
+            @on-filter-change="onFilterChange"
+            @update:selected-value="onUpdateSelectedValue"
+          />
+        </div>
+      `,
+      methods: {
+        onFilterChange(data: string) {
+          searchQuery.value = data
+          args.values = sampleOptions.filter((option) =>
+            option.label.toLowerCase().includes(searchQuery.value.toLowerCase()),
+          )
+        },
+        onUpdateSelectedValue(data: unknown) {
+          args.selectedValue = data
+        },
       },
-    },
-  }),
+    }
+  },
 }
 
+/**
+ * Override the dropdown title via `dropdownTitle`.
+ */
 export const CustomTitle: Story = {
   args: {
     ...Default.args,