@citizenplane/pimp 16.0.3 → 16.1.0

package/src/stories/CpSwitch.stories.ts

@@ -4,8 +4,12 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 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

@@ -8,7 +8,7 @@ import CpTable from '@/components/CpTable.vue'
 import { PAGINATION_FORMATS } from '@/constants'
 
 const meta = {
-  title: 'Data display/CpTable',
+  title: 'Organisms/CpTable',
   component: CpTable,
   parameters: {
     backgrounds: {
@@ -34,6 +34,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,
@@ -66,6 +70,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 +89,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 +100,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 +110,9 @@ export const Loading: Story = {
   },
 }
 
+/**
+ * Empty dataset — the `noResultPlaceholder` copy replaces the rows.
+ */
 export const Empty: Story = {
   args: {
     ...Default.args,
@@ -101,6 +120,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 +135,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,
@@ -152,6 +179,12 @@ 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,
@@ -219,6 +252,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,
@@ -267,6 +304,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,
@@ -321,6 +362,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,
@@ -371,6 +416,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,
@@ -393,6 +442,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,

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'
 
 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" />',
   }),
 }

package/src/stories/CpTabs.stories.ts

@@ -6,7 +6,7 @@ import type { Args, Meta, StoryObj } from '@storybook/vue3'
 import CpTabs from '@/components/CpTabs.vue'
 
 const meta = {
-  title: 'Navigation/CpTabs',
+  title: 'Molecules/CpTabs',
   component: CpTabs,
   argTypes: {
     defaultActiveIndex: {
@@ -28,15 +28,18 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-const defaultTemplate = '<CpTabs v-bind="args" @on-tab-click="args.onOnTabClick" />'
 const defaultRender = (args: Args) => ({
   components: { CpTabs },
   setup() {
     return { args }
   },
-  template: defaultTemplate,
+  template: '<CpTabs v-bind="args" @on-tab-click="args.onOnTabClick" />',
 })
 
+/**
+ * Default tabs rendered from an array of `{ title }` objects. Use the
+ * controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     defaultActiveIndex: 0,
@@ -47,6 +50,10 @@ export const Default: Story = {
   render: defaultRender,
 }
 
+/**
+ * Tabs augmented with leading icons through the `icon` property on each
+ * tab object.
+ */
 export const WithIcons: Story = {
   args: {
     ...Default.args,
@@ -59,6 +66,10 @@ export const WithIcons: Story = {
   render: defaultRender,
 }
 
+/**
+ * Tabs that display a count badge on the right — typically used for
+ * notifications or list sizes.
+ */
 export const WithCounts: Story = {
   args: {
     ...Default.args,
@@ -71,6 +82,9 @@ export const WithCounts: Story = {
   render: defaultRender,
 }
 
+/**
+ * Icons and counts combined on the same tab.
+ */
 export const WithIconsAndCounts: Story = {
   args: {
     ...Default.args,
@@ -83,6 +97,10 @@ export const WithIconsAndCounts: Story = {
   render: defaultRender,
 }
 
+/**
+ * Tabs nested inside a dialog — verifies the integration with overlay
+ * surfaces and the focus ring behaviour.
+ */
 export const InDialog: Story = {
   args: {
     ...Default.args,
@@ -105,7 +123,7 @@ export const InDialog: Story = {
           <CpTabs v-bind="args" @on-tab-click="args.onOnTabClick" v-if="isVisible" />
         </cp-dialog>
       </cp-transition-dialog>
-      <div style="display: flex; justify-content: center; align-items: center; min-height: 240px; min-width:240px;">
+      <div style="display: flex; justify-content: center; align-items: center; min-height: 240px; min-width: 240px;">
         <cp-button @click="isVisible = !isVisible">Open dialog</cp-button>
       </div>
     `,