@citizenplane/pimp 16.0.3 → 16.2.0

package/src/stories/CpSwitch.stories.ts

@@ -1,11 +1,15 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpSwitch from '@/components/CpSwitch.vue'
 
+import { docCellStyle, docLabelStyle, docRowWrapStyle } from '@/stories/documentationStyles'
+
+const switchColors = ['blue', 'purple'] as const
+
 const meta = {
-  title: 'Form/CpSwitch',
+  title: 'Atoms/CpSwitch',
   component: CpSwitch,
   argTypes: {
     autofocus: {
@@ -14,7 +18,7 @@ const meta = {
     },
     color: {
       control: 'select',
-      options: ['blue', 'purple'],
+      options: switchColors,
       description: 'Color variant of the switch',
     },
     disabled: {
@@ -55,6 +59,9 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default switch. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     label: 'Label',
@@ -74,100 +81,121 @@ export const Default: Story = {
     },
     template: `
       <div style="padding: 20px;">
-        <CpSwitch
-          v-model="value"
-          v-bind="args"
-        />
+        <CpSwitch v-model="value" v-bind="args" />
       </div>
     `,
   }),
 }
 
-export const WithHaptics: Story = {
-  args: {
-    ...Default.args,
-    enableHaptics: true,
-  },
-  render: (args) => ({
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Off, on, disabled off and disabled on compared side by side.
+ */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
     components: { CpSwitch },
     setup() {
-      const value = ref(false)
-      return { args, value }
+      return { docCellStyle, docLabelStyle, docRowWrapStyle }
     },
     template: `
-      <div style="padding: 20px;">
-        <CpSwitch
-          v-model="value"
-          v-bind="args"
-        />
+      <div :style="docRowWrapStyle">
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Off</span>
+          <CpSwitch :model-value="false" label="Label" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">On</span>
+          <CpSwitch :model-value="true" label="Label" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Disabled off</span>
+          <CpSwitch :model-value="false" :disabled="true" label="Label" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">Disabled on</span>
+          <CpSwitch :model-value="true" :disabled="true" label="Label" />
+        </div>
       </div>
     `,
   }),
 }
 
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    disabled: true,
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* Colors                                                                     */
+/* -------------------------------------------------------------------------- */
 
-export const DisabledChecked: Story = {
-  args: {
-    ...Default.args,
-    disabled: true,
-    modelValue: true,
-  },
-}
-
-export const Required: Story = {
-  args: {
-    ...Default.args,
-    isRequired: true,
-  },
-  render: (args) => ({
+/**
+ * Color variants rendered side by side.
+ */
+export const Colors: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
     components: { CpSwitch },
     setup() {
-      const value = ref(false)
-      return { args, value }
+      return { switchColors, docCellStyle, docLabelStyle, docRowWrapStyle }
     },
     template: `
-      <div style="padding: 20px;">
-        <CpSwitch
-          v-model="value"
-          v-bind="args"
-        />
+      <div :style="docRowWrapStyle">
+        <div v-for="color in switchColors" :key="color" :style="docCellStyle">
+          <span :style="docLabelStyle">{{ color }}</span>
+          <CpSwitch :model-value="true" :color="color" label="Label" />
+        </div>
       </div>
     `,
   }),
 }
 
-export const Reversed: Story = {
-  args: {
-    ...Default.args,
-    reverseLabel: true,
-  },
-  render: (args) => ({
+/* -------------------------------------------------------------------------- */
+/* Sizes                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The switch inherits its size from the font-size of its container. Wrap it
+ * inside a `transform: scale()` to obtain smaller or larger switches.
+ */
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
     components: { CpSwitch },
     setup() {
-      const value = ref(false)
-      return { args, value }
+      const values = ref({
+        sm: false,
+        md: true,
+        lg: false,
+      })
+      return { values }
     },
     template: `
-      <div style="padding: 20px;">
-        <CpSwitch
-          v-model="value"
-          v-bind="args"
-        />
+      <div style="padding: 20px; display: flex; flex-direction: column; gap: 20px;">
+        <div style="transform: scale(0.8); transform-origin: left center;">
+          <CpSwitch v-model="values.sm" label="Height 16px" />
+        </div>
+        <div>
+          <CpSwitch v-model="values.md" label="Height 20px" />
+        </div>
+        <div style="transform: scale(1.2); transform-origin: left center;">
+          <CpSwitch v-model="values.lg" label="Height 24px" />
+        </div>
       </div>
     `,
   }),
 }
 
-export const WithHelper: Story = {
+/* -------------------------------------------------------------------------- */
+/* Variants                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Display the label before the switch using `reverseLabel`.
+ */
+export const Reversed: Story = {
   args: {
     ...Default.args,
-    helper: 'This is a helper text that provides additional information',
+    reverseLabel: true,
   },
   render: (args) => ({
     components: { CpSwitch },
@@ -177,42 +205,54 @@ export const WithHelper: Story = {
     },
     template: `
       <div style="padding: 20px;">
-        <CpSwitch
-          v-model="value"
-          v-bind="args"
-        />
+        <CpSwitch v-model="value" v-bind="args" />
       </div>
     `,
   }),
 }
 
-export const WithTooltip: Story = {
-  args: {
-    ...Default.args,
-    tooltip: 'This is a tooltip text',
-  },
-  render: (args) => ({
+/**
+ * Add a helper text, a tooltip next to the label, or both.
+ */
+export const HelpAndTooltip: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
     components: { CpSwitch },
     setup() {
-      const value = ref(false)
-      return { args, value }
+      const values = ref({ helper: false, tooltip: false, both: false })
+      return { values, docCellStyle, docLabelStyle, docRowWrapStyle }
     },
     template: `
-      <div style="padding: 20px;">
-        <CpSwitch
-          v-model="value"
-          v-bind="args"
-        />
+      <div :style="docRowWrapStyle">
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">With helper</span>
+          <CpSwitch v-model="values.helper" label="Label" helper="This is a helper text that provides additional information" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">With tooltip</span>
+          <CpSwitch v-model="values.tooltip" label="Label" tooltip="This is a tooltip text" />
+        </div>
+        <div :style="docCellStyle">
+          <span :style="docLabelStyle">With both</span>
+          <CpSwitch
+            v-model="values.both"
+            label="Label"
+            helper="This is a helper text"
+            tooltip="This is a tooltip text"
+          />
+        </div>
       </div>
     `,
   }),
 }
 
-export const WithHelperAndTooltip: Story = {
+/**
+ * Triggers a haptic feedback on supported devices when toggled.
+ */
+export const WithHaptics: Story = {
   args: {
     ...Default.args,
-    helper: 'This is a helper text that provides additional information',
-    tooltip: 'This is a tooltip text',
+    enableHaptics: true,
   },
   render: (args) => ({
     components: { CpSwitch },
@@ -222,16 +262,21 @@ export const WithHelperAndTooltip: Story = {
     },
     template: `
       <div style="padding: 20px;">
-        <CpSwitch
-          v-model="value"
-          v-bind="args"
-        />
+        <CpSwitch v-model="value" v-bind="args" />
       </div>
     `,
   }),
 }
 
+/* -------------------------------------------------------------------------- */
+/* Group                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Multiple switches bound together, sharing the same `groupName`.
+ */
 export const SwitchGroup: Story = {
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpSwitch },
     setup() {
@@ -239,59 +284,16 @@ export const SwitchGroup: Story = {
         switch1: false,
         switch2: true,
         switch3: false,
+        switch4: false,
       })
       return { switches }
     },
     template: `
       <div style="padding: 20px; display: flex; flex-direction: column; gap: 16px;">
-        <CpSwitch
-          v-model="switches.switch1"
-          label="First Switch"
-          group-name="switch-group"
-        />
-        <CpSwitch
-          v-model="switches.switch2"
-          label="Second Switch"
-          group-name="switch-group"
-        />
-        <CpSwitch
-          v-model="switches.switch3"
-          label="Third Switch"
-          group-name="switch-group"
-          disabled
-        />
-        <CpSwitch
-          v-model="switches.switch4"
-          label="Fourth Switch"
-          group-name="switch-group"
-        />
-      </div>
-    `,
-  }),
-}
-
-export const Sizes: Story = {
-  render: () => ({
-    components: { CpSwitch },
-    setup() {
-      const values = ref({
-        sm: false,
-        md: true,
-        lg: false,
-      })
-      return { values }
-    },
-    template: `
-      <div style="padding: 20px; display: flex; flex-direction: column; gap: 20px;">
-        <div style="transform: scale(0.8); transform-origin: left center;">
-          <CpSwitch v-model="values.sm" label="Height 16px" />
-        </div>
-        <div>
-          <CpSwitch v-model="values.md" label="Height 20px" />
-        </div>
-        <div style="transform: scale(1.2); transform-origin: left center;">
-          <CpSwitch v-model="values.lg" label="Height 24px" />
-        </div>
+        <CpSwitch v-model="switches.switch1" label="First Switch" group-name="switch-group" />
+        <CpSwitch v-model="switches.switch2" label="Second Switch" group-name="switch-group" />
+        <CpSwitch v-model="switches.switch3" label="Third Switch" group-name="switch-group" disabled />
+        <CpSwitch v-model="switches.switch4" label="Fourth Switch" group-name="switch-group" />
       </div>
     `,
   }),

package/src/stories/CpTable.stories.ts

@@ -1,14 +1,14 @@
 import { action } from 'storybook/actions'
 import { ref, computed } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpTable from '@/components/CpTable.vue'
 
 import { PAGINATION_FORMATS } from '@/constants'
 
 const meta = {
-  title: 'Data display/CpTable',
+  title: 'Organisms/CpTable',
   component: CpTable,
   parameters: {
     backgrounds: {
@@ -22,8 +22,11 @@ const meta = {
 } satisfies Meta<typeof CpTable>
 
 export default meta
+
 type Story = StoryObj<typeof meta>
 
+type TableStoryArgs = NonNullable<Story['args']>
+
 const sampleColumns = ['name', 'age', 'email', 'status']
 
 const sampleData = [
@@ -34,6 +37,10 @@ const sampleData = [
   { name: 'Charlie Wilson', age: 42, email: 'charlie@example.com', status: 'Inactive', date: '2026-01-05' },
 ]
 
+/**
+ * Default table with sample columns and rows. Use the controls to
+ * experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     columns: sampleColumns,
@@ -53,7 +60,7 @@ export const Default: Story = {
     onOnNextClick: action('on-next-click'),
     onOnColumnsChanged: action('on-columns-changed'),
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       return { args }
@@ -66,6 +73,11 @@ export const Default: Story = {
   }),
 }
 
+/**
+ * Enable the column manager so users can show/hide, pin and reorder
+ * columns. Individual columns expose `isHidden`, `isProtected` and
+ * `isFull` flags to control the initial layout.
+ */
 export const EnableColumnEdition: Story = {
   args: {
     ...Default.args,
@@ -80,6 +92,10 @@ export const EnableColumnEdition: Story = {
   },
 }
 
+/**
+ * Rows become interactive — hover highlights and the `onRowClick` event
+ * fires on click.
+ */
 export const ClickableRows: Story = {
   args: {
     ...Default.args,
@@ -87,6 +103,9 @@ export const ClickableRows: Story = {
   },
 }
 
+/**
+ * Loading state — skeleton rows are displayed while the data is fetched.
+ */
 export const Loading: Story = {
   args: {
     ...Default.args,
@@ -94,6 +113,9 @@ export const Loading: Story = {
   },
 }
 
+/**
+ * Empty dataset — the `noResultPlaceholder` copy replaces the rows.
+ */
 export const Empty: Story = {
   args: {
     ...Default.args,
@@ -101,6 +123,10 @@ export const Empty: Story = {
   },
 }
 
+/**
+ * Configure pagination through the `pagination` prop. `format` switches
+ * between `PAGES` and alternative formats.
+ */
 export const WithPagination: Story = {
   args: {
     ...Default.args,
@@ -112,6 +138,10 @@ export const WithPagination: Story = {
   },
 }
 
+/**
+ * Group rows by providing an array of `{ groupBy, rows }` objects. A
+ * custom `#groupBy` slot renders the section header.
+ */
 export const WithGroupBy: Story = {
   args: {
     ...Default.args,
@@ -129,7 +159,7 @@ export const WithGroupBy: Story = {
       },
     ],
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       return { args }
@@ -152,13 +182,19 @@ export const WithGroupBy: Story = {
   }),
 }
 
+/**
+ * Attach per-row actions through `rowOptions`. `quickOptionsLimit`
+ * controls how many actions appear inline before the overflow menu; each
+ * action can be async (`isAsync` + `isLoading`) or critical
+ * (`isCritical`).
+ */
 export const WithCustomRowOptions: Story = {
   args: {
     ...Default.args,
     enableRowOptions: true,
     enableColumnEdition: true,
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       const isEditLoading = ref(false)
@@ -176,7 +212,7 @@ export const WithCustomRowOptions: Story = {
           icon: 'edit-2',
           isAsync: true,
           isLoading: isEditLoading.value,
-          action: async (payload) => {
+          action: async (payload: Record<string, unknown>) => {
             isEditLoading.value = true
             console.log('Edit', payload)
             await new Promise((resolve) => setTimeout(resolve, 2000))
@@ -188,7 +224,7 @@ export const WithCustomRowOptions: Story = {
           label: 'Disable',
           icon: 'history',
           isDisabled: true,
-          action: (payload) => console.log('History', payload),
+          action: (payload: Record<string, unknown>) => console.log('History', payload),
         },
         {
           id: 'delete',
@@ -219,6 +255,10 @@ export const WithCustomRowOptions: Story = {
   }),
 }
 
+/**
+ * Rows without a "primary" action — every option lives in the overflow
+ * menu. Useful when actions are secondary to the row click.
+ */
 export const WithoutDefaultAction: Story = {
   args: {
     ...Default.args,
@@ -226,7 +266,7 @@ export const WithoutDefaultAction: Story = {
     quickOptionsLimit: 2,
     enableColumnEdition: true,
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       const isEditLoading = ref(false)
@@ -267,6 +307,10 @@ export const WithoutDefaultAction: Story = {
   }),
 }
 
+/**
+ * Setting `quickOptionsLimit: 0` forces the primary action to appear
+ * inline without any overflow menu.
+ */
 export const WithOnlyDefaultAction: Story = {
   args: {
     ...Default.args,
@@ -274,7 +318,7 @@ export const WithOnlyDefaultAction: Story = {
     enableColumnEdition: true,
     quickOptionsLimit: 0,
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       const isEditLoading = ref(false)
@@ -292,7 +336,7 @@ export const WithOnlyDefaultAction: Story = {
           icon: 'edit-2',
           isAsync: true,
           isLoading: isEditLoading.value,
-          action: async (payload) => {
+          action: async (payload: Record<string, unknown>) => {
             isEditLoading.value = true
             console.log('Edit', payload)
             await new Promise((resolve) => setTimeout(resolve, 2000))
@@ -321,6 +365,10 @@ export const WithOnlyDefaultAction: Story = {
   }),
 }
 
+/**
+ * When the table overflows horizontally, a subtle scroll cue appears on
+ * the right edge to hint at the extra content.
+ */
 export const ScrollCue: Story = {
   args: {
     ...Default.args,
@@ -358,7 +406,7 @@ export const ScrollCue: Story = {
       },
     ],
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       return { args }
@@ -371,6 +419,10 @@ export const ScrollCue: Story = {
   }),
 }
 
+/**
+ * A row can override the column layout with `{ fullWidth: '...' }` to
+ * spread a single cell across the whole table (e.g. summaries or notes).
+ */
 export const FullWidthRow: Story = {
   args: {
     ...Default.args,
@@ -380,7 +432,7 @@ export const FullWidthRow: Story = {
       { name: 'Jane Smith', age: 25, email: 'jane@example.com', status: 'Inactive' },
     ],
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       return { args }
@@ -393,6 +445,10 @@ export const FullWidthRow: Story = {
   }),
 }
 
+/**
+ * Mark a row as selected by adding `isSelected: true`. The row adopts a
+ * highlighted background.
+ */
 export const SelectedRow: Story = {
   args: {
     ...Default.args,
@@ -402,7 +458,7 @@ export const SelectedRow: Story = {
       { name: 'Bob Johnson', age: 35, email: 'bob@example.com', status: 'Active' },
     ],
   },
-  render: (args) => ({
+  render: (args: TableStoryArgs) => ({
     components: { CpTable },
     setup() {
       return { args }

package/src/stories/CpTableEmptyState.stories.ts

@@ -1,9 +1,9 @@
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Args, Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpTableEmptyState from '@/components/CpTableEmptyState.vue'
 
 const meta = {
-  title: 'Data display/CpTableEmptyState',
+  title: 'Molecules/CpTableEmptyState',
   component: CpTableEmptyState,
   argTypes: {
     placeholder: {
@@ -12,24 +12,28 @@ const meta = {
     },
   },
   decorators: [
-    () => ({ template: '<div style="padding: 20px; border-radius: 8px; background-color: #fff;"><story/></div>' }),
+    () => ({
+      template: '<div style="padding: 20px; border-radius: 8px; background-color: #fff;"><story /></div>',
+    }),
   ],
 } satisfies Meta<typeof CpTableEmptyState>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Empty-state block rendered inside a table when no rows match the
+ * current filters. Use the controls to experiment with each prop.
+ */
 export const Default: Story = {
   args: {
     placeholder: 'No results found',
   },
-  render: (args) => ({
+  render: (args: Args) => ({
     components: { CpTableEmptyState },
     setup() {
       return { args }
     },
-    template: `
-      <CpTableEmptyState v-bind="args" />
-    `,
+    template: '<CpTableEmptyState v-bind="args" />',
   }),
 }