@citizenplane/pimp 16.0.3 → 16.2.0

package/src/stories/CpRadio.stories.ts

@@ -1,11 +1,13 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 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

@@ -1,11 +1,14 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 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

@@ -1,12 +1,18 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 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: {
@@ -70,6 +76,7 @@ const meta = {
 } satisfies Meta<typeof CpSelect>
 
 export default meta
+
 type Story = StoryObj<typeof meta>
 
 const sampleOptions = [
@@ -79,6 +86,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 +111,111 @@ 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,
+    },
   },
-}
-
-export const Disabled: Story = {
   args: {
     ...Default.args,
-    disabled: 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 Small: Story = {
-  args: {
-    ...Default.args,
-    size: 'sm',
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
 
-export const Large: Story = {
+/**
+ * Default, required, disabled and invalid states compared side by side.
+ */
+export const States: Story = {
+  parameters: {
+    controls: {
+      disable: true,
+    },
+  },
   args: {
     ...Default.args,
-    size: 'lg',
   },
+  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>
+    `,
+  }),
 }
 
+/* -------------------------------------------------------------------------- */
+/* 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 +223,9 @@ export const WithoutDefaultOption: Story = {
   },
 }
 
+/**
+ * Long option labels are truncated with an ellipsis.
+ */
 export const WithLongOptions: Story = {
   args: {
     ...Default.args,
@@ -165,6 +238,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 +257,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>
     `,