@citizenplane/pimp 16.0.3 → 16.2.0

package/src/stories/CpToast.stories.ts

@@ -1,19 +1,46 @@
 import { useToast } from 'primevue/usetoast'
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 import { CpToastTypes } from '@/constants/CpToastTypes'
 
 import CpToast from '@/components/CpToast.vue'
 
-const meta: Meta<typeof CpToast> = {
-  title: 'Feedback/CpToast',
+type CpToastPosition =
+  | 'bottom-center'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'center'
+  | 'top-center'
+  | 'top-left'
+  | 'top-right'
+
+/** `CpToast` has no `defineProps`; layout props are passed through to PrimeVue `Toast`. */
+type CpToastStoryArgs = {
+  enableHaptics?: boolean
+  group?: string
+  position?: CpToastPosition
+}
+
+const toastPositions = [
+  'center',
+  'top-left',
+  'top-center',
+  'top-right',
+  'bottom-left',
+  'bottom-center',
+  'bottom-right',
+] as const
+
+const meta = {
+  title: 'Molecules/CpToast',
   component: CpToast,
   argTypes: {
     position: {
       control: { type: 'select' },
-      options: ['center', 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'],
+      options: toastPositions,
+      description: 'Where to anchor the toast stack on the screen',
     },
   },
   args: {
@@ -21,13 +48,17 @@ const meta: Meta<typeof CpToast> = {
     group: undefined,
     enableHaptics: false,
   },
-}
+} satisfies Meta<CpToastStoryArgs>
 
 export default meta
 
-type Story = StoryObj<typeof CpToast>
+type Story = StoryObj<CpToastStoryArgs>
 
-export const Default: Story = {
+/**
+ * Trigger toasts of every severity using the `useToast()` composable.
+ * Buttons in the canvas call `toast.add()` with a different `severity`.
+ */
+export const Severities: Story = {
   render: (args) => ({
     components: { CpToast },
     setup() {
@@ -35,115 +66,54 @@ export const Default: Story = {
 
       const baseOptions = {
         severity: CpToastTypes.SECONDARY,
-        summary: `Hello i'm a cpToast !`,
+        summary: "Hello i'm a cpToast!",
         detail: 'This is a cpToast description.',
         enableHaptics: true,
       }
 
-      const notifySecondary = () => toast.add({ ...baseOptions })
-
-      const notifyInfo = () => {
-        toast.add({
-          ...baseOptions,
-          severity: CpToastTypes.INFO,
-        })
-      }
+      const notify = (severity: string) => toast.add({ ...baseOptions, severity })
 
-      const notifyError = () => {
-        toast.add({
-          ...baseOptions,
-          severity: CpToastTypes.ERROR,
-        })
-      }
-      const notifySuccess = () => {
-        toast.add({
-          ...baseOptions,
-          severity: CpToastTypes.SUCCESS,
-        })
-      }
-      const notifyWarning = () => {
-        toast.add({
-          ...baseOptions,
-          severity: CpToastTypes.WARNING,
-        })
-      }
-
-      return { args, notifySecondary, notifyInfo, notifyError, notifySuccess, notifyWarning }
+      return { args, notify }
     },
     template: `
       <div style="padding: 16px;">
-
         <CpToast v-bind="args" />
 
-        <div style="display:flex; gap: 12px; align-items:center;">
-          <button
-            type="button"
-            @click="notifySecondary"
-            style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor:pointer;"
-          >
-            Show secondary toast
-          </button>
-
-          <button
-            type="button"
-            @click="notifyInfo"
-            style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor:pointer;"
-          >
-            Show info toast
-          </button>
-
-          <button
-            type="button"
-            @click="notifyError"
-            style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor:pointer;"
-          >
-            Show error toast
-          </button>
-
-          <button
-            type="button"
-            @click="notifySuccess"
-            style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor:pointer;"
-          >
-            Show success toast
-          </button>
-
-          <button
-            type="button"
-            @click="notifyWarning"
-            style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor:pointer;"
-          >
-            Show warning toast
-          </button>
+        <div style="display: flex; gap: 12px; align-items: center; flex-wrap: wrap;">
+          <button type="button" @click="notify('secondary')" style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor: pointer;">Secondary</button>
+          <button type="button" @click="notify('info')" style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor: pointer;">Info</button>
+          <button type="button" @click="notify('success')" style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor: pointer;">Success</button>
+          <button type="button" @click="notify('warning')" style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor: pointer;">Warning</button>
+          <button type="button" @click="notify('error')" style="padding: 8px 12px; border-radius: 8px; border: 1px solid #ddd; cursor: pointer;">Error</button>
         </div>
 
-        <p style="margin-top:12px; color:#666;">
-          This story demonstrates triggering notifications only via <code>useToast()</code>.
+        <p style="margin-top: 12px; color: #666;">
+          Toasts are triggered via <code>useToast()</code>.
         </p>
       </div>
     `,
   }),
 }
 
+/**
+ * Toasts with a `life` (auto-close) duration can optionally render a
+ * countdown bar via the `showTimer` option.
+ */
 export const WithTimer: Story = {
-  args: {
-    ...Default.args,
-  },
   render: (args) => ({
     components: { CpToast },
     setup() {
       const toast = useToast()
-
       const showTimer = ref(false)
 
       const notifyWithTimer = () => {
         toast.add({
           severity: CpToastTypes.INFO,
-          summary: "Hello i'm a cpToast with a timer !",
+          summary: "Hello i'm a cpToast with a timer!",
           detail: 'This is a cpToast description.',
           life: 2500,
           showTimer: showTimer.value,
-        })
+        } as never)
       }
 
       return { args, notifyWithTimer, showTimer }
@@ -151,20 +121,21 @@ export const WithTimer: Story = {
     template: `
       <div style="padding: 16px;">
         <CpToast v-bind="args" />
-
         <cp-button @click="notifyWithTimer">Show toast with timer</cp-button>
-        <div style="margin-top: 24px">
-          <cp-switch v-model="showTimer" label="Show timer bar ?"</cp-switch>
+        <div style="margin-top: 24px;">
+          <cp-switch v-model="showTimer" label="Show timer bar?" />
         </div>
       </div>
     `,
   }),
 }
 
+/**
+ * Pass `primaryAction` / `secondaryAction` to render buttons inside the
+ * toast. Each action exposes a label, optional icons and an `onClick`
+ * callback.
+ */
 export const WithActions: Story = {
-  args: {
-    ...Default.args,
-  },
   render: (args) => ({
     components: { CpToast },
     setup() {
@@ -173,23 +144,19 @@ export const WithActions: Story = {
       const notifyWithActions = () => {
         toast.add({
           severity: CpToastTypes.INFO,
-          summary: "Hello i'm a cpToast with actions !",
+          summary: "Hello i'm a cpToast with actions!",
           detail: 'This is a cpToast description.',
           primaryAction: {
             label: 'Primary action',
             leadingIcon: 'user',
-            onClick: () => {
-              console.log('Primary action clicked')
-            },
+            onClick: () => console.log('Primary action clicked'),
           },
           secondaryAction: {
             label: 'Secondary action',
             trailingIcon: 'arrow-right',
-            onClick: () => {
-              console.log('Secondary action clicked')
-            },
+            onClick: () => console.log('Secondary action clicked'),
           },
-        })
+        } as never)
       }
 
       return { args, notifyWithActions }
@@ -197,37 +164,36 @@ export const WithActions: Story = {
     template: `
       <div style="padding: 16px;">
         <CpToast v-bind="args" />
-
         <cp-button @click="notifyWithActions">Show toast with actions</cp-button>
       </div>
     `,
   }),
 }
 
-export const WithPositions: Story = {
-  args: {
-    ...Default.args,
-  },
+/**
+ * The toast stack is positioned via the `position` prop on the
+ * `<CpToast>` mount point. Update the control to try every anchor.
+ */
+export const Positions: Story = {
   render: (args) => ({
     components: { CpToast },
     setup() {
       const toast = useToast()
 
-      const notifyWithPositions = () => {
+      const notify = () => {
         toast.add({
           severity: CpToastTypes.INFO,
-          summary: "Hello i'm a cpToast with positions !",
+          summary: "Hello i'm a cpToast!",
           detail: 'This is a cpToast description.',
         })
       }
 
-      return { args, notifyWithPositions }
+      return { args, notify }
     },
     template: `
       <div style="padding: 16px;">
         <CpToast v-bind="args" />
-
-        <cp-button @click="notifyWithPositions">Show toast with positions</cp-button>
+        <cp-button @click="notify">Show toast</cp-button>
       </div>
     `,
   }),

package/src/stories/CpTooltip.stories.ts

@@ -1,9 +1,12 @@
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Args, Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpTooltip from '@/components/CpTooltip.vue'
 
+const tooltipColors = ['accent', 'neutral'] as const
+const tooltipPlacements = ['top', 'right', 'bottom', 'left'] as const
+
 const meta = {
-  title: 'Feedback/CpTooltip',
+  title: 'Atoms/CpTooltip',
   component: CpTooltip,
   argTypes: {
     content: {
@@ -16,12 +19,12 @@ const meta = {
     },
     color: {
       control: 'select',
-      options: ['accent', 'neutral'],
+      options: tooltipColors,
       description: 'The color variant',
     },
     placement: {
       control: 'select',
-      options: ['top', 'right', 'bottom', 'left'],
+      options: tooltipPlacements,
       description: 'The placement of the tooltip',
     },
     distance: {
@@ -34,53 +37,53 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+const paddedRender = (args: Args) => ({
+  components: { CpTooltip },
+  setup() {
+    return { args }
+  },
+  template: `
+    <div style="padding: 100px; text-align: center;">
+      <CpTooltip v-bind="args">
+        <button>Hover me</button>
+      </CpTooltip>
+    </div>
+  `,
+})
+
+/**
+ * Default tooltip. Hover the trigger to reveal it. Use the controls to
+ * experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     content: 'Tooltip content',
     placement: 'top',
     distance: 8,
   },
-  render: (args) => ({
-    components: { CpTooltip },
-    setup() {
-      return { args }
-    },
-    template: `
-      <div style="padding: 100px; text-align: center;">
-        <CpTooltip v-bind="args">
-          <button>Hover me</button>
-        </CpTooltip>
-      </div>
-    `,
-  }),
+  render: paddedRender,
 }
 
-export const AllPlacements: Story = {
-  render: (args) => ({
+/* -------------------------------------------------------------------------- */
+/* Placements                                                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * All four placements rendered on one page. Tooltips flip automatically if
+ * they don't fit on the chosen side.
+ */
+export const Placements: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
     components: { CpTooltip },
     setup() {
-      return { args }
+      return { tooltipPlacements }
     },
     template: `
-      <div style="display: flex; flex-direction: column; gap: 20px; padding: 100px;">
-        <div>
-          <CpTooltip content="Top tooltip" placement="top">
-            <button>Top</button>
-          </CpTooltip>
-        </div>
-        <div>
-          <CpTooltip content="Right tooltip" placement="right">
-            <button>Right</button>
-          </CpTooltip>
-        </div>
-        <div>
-          <CpTooltip content="Bottom tooltip" placement="bottom">
-            <button>Bottom</button>
-          </CpTooltip>
-        </div>
-        <div>
-          <CpTooltip content="Left tooltip" placement="left">
-            <button>Left</button>
+      <div style="display: flex; gap: 32px; padding: 100px; justify-content: center; flex-wrap: wrap;">
+        <div v-for="placement in tooltipPlacements" :key="placement">
+          <CpTooltip :content="placement + ' tooltip'" :placement="placement">
+            <button>{{ placement }}</button>
           </CpTooltip>
         </div>
       </div>
@@ -88,11 +91,17 @@ export const AllPlacements: Story = {
   }),
 }
 
+/* -------------------------------------------------------------------------- */
+/* Content                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Pass rich HTML content via the `#content` slot — perfect for links,
+ * formatting or small compositions.
+ */
 export const WithHTMLContent: Story = {
-  args: {
-    placement: 'top',
-  },
-  render: (args) => ({
+  args: { placement: 'top' },
+  render: (args: Args) => ({
     components: { CpTooltip },
     setup() {
       return { args }
@@ -110,55 +119,51 @@ export const WithHTMLContent: Story = {
   }),
 }
 
-export const WithSubcontentSlot: Story = {
-  args: {
-    content: 'Main content',
-    placement: 'top',
-  },
-  render: (args) => ({
-    components: { CpTooltip },
-    setup() {
-      return { args }
-    },
-    template: `
-      <div style="padding: 100px; text-align: center;">
-        <CpTooltip v-bind="args">
-          <button type="button">Hover me</button>
-          <template #subcontent>
-            <p>Optional subcontent via slot, it can be a long text to see how it works and includes <b>HTML</b> <u>tags</u></p>
-          </template>
-        </CpTooltip>
-      </div>
-    `,
-  }),
-}
-
-export const WithSubcontentProp: Story = {
+/**
+ * A secondary line of content displayed below the main content. Can be
+ * provided as a `subcontent` prop or through the `#subcontent` slot.
+ */
+export const WithSubcontent: Story = {
   args: {
     content: 'Main content',
     subcontent: 'Optional subcontent via prop',
     placement: 'top',
   },
-  render: (args) => ({
+  render: (args: Args) => ({
     components: { CpTooltip },
     setup() {
       return { args }
     },
     template: `
-      <div style="padding: 100px; text-align: center;">
-        <CpTooltip v-bind="args">
-          <button type="button">Hover me</button>
-        </CpTooltip>
+      <div style="display: flex; gap: 48px; padding: 100px; justify-content: center; flex-wrap: wrap;">
+        <div>
+          <CpTooltip v-bind="args">
+            <button type="button">Subcontent via prop</button>
+          </CpTooltip>
+        </div>
+        <div>
+          <CpTooltip :content="args.content" :placement="args.placement">
+            <button type="button">Subcontent via slot</button>
+            <template #subcontent>
+              <p>Optional subcontent via slot, includes <b>HTML</b> <u>tags</u></p>
+            </template>
+          </CpTooltip>
+        </div>
       </div>
     `,
   }),
 }
 
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * When `disabled` is `true` the tooltip never appears, even on hover.
+ */
 export const Disabled: Story = {
-  args: {
-    disabled: true,
-  },
-  render: (args) => ({
+  args: { disabled: true },
+  render: (args: Args) => ({
     components: { CpTooltip },
     setup() {
       return { args }
@@ -166,7 +171,7 @@ export const Disabled: Story = {
     template: `
       <div style="padding: 100px; text-align: center;">
         <CpTooltip v-bind="args" content="You should not see me">
-          <div type="button">Disabled</div>
+          <div>Disabled trigger</div>
         </CpTooltip>
       </div>
     `,

package/src/stories/CpTransitionCounter.stories.ts

@@ -1,6 +1,6 @@
 import { computed, ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpButton from '@/components/CpButton.vue'
 import CpIcon from '@/components/CpIcon.vue'
@@ -24,6 +24,10 @@ const rowStyle = 'padding: 24px; display: inline-flex; align-items: center; just
 
 const counterTextStyle = 'font-weight: bold; font-size: 4.5rem; line-height: 1; font-variant-numeric: tabular-nums;'
 
+/**
+ * Counter transition that animates number changes. Use the +/- buttons
+ * (or the `duration` control) to see the slide-in / slide-out behaviour.
+ */
 export const Default: Story = {
   args: {
     duration: 150,

package/src/stories/CpTransitionExpand.stories.ts

@@ -1,6 +1,6 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpTransitionExpand from '@/components/CpTransitionExpand.vue'
 
@@ -17,6 +17,10 @@ type Story = StoryObj<typeof meta>
 
 const wrapperStyle = 'display: flex; flex-direction: column; align-items: center; gap: 12px;'
 
+/**
+ * Animated height expansion. Wrap any element in `<CpTransitionExpand>`
+ * and toggle its rendering with `v-if` to smoothly expand/collapse.
+ */
 export const Default: Story = {
   render: () => ({
     components: { CpTransitionExpand },
@@ -35,14 +39,11 @@ export const Default: Story = {
         </CpButton>
 
         <CpTransitionExpand>
-          <div v-if="isExpanded" style="
-            background: #F3F4F6;
-            border-radius: 6px;
-          ">
+          <div v-if="isExpanded" style="background: #F3F4F6; border-radius: 6px; padding: 16px;">
             <h3 style="margin: 0 0 8px 0;">Expanded Content</h3>
             <p style="margin: 0;">
-              This content will smoothly expand and collapse with a nice animation.
-              The height transition is handled automatically by the CpTransitionExpand component.
+              This content smoothly expands and collapses. The height transition is handled
+              automatically by the CpTransitionExpand component.
             </p>
           </div>
         </CpTransitionExpand>
@@ -51,6 +52,10 @@ export const Default: Story = {
   }),
 }
 
+/**
+ * The transition works with content of any height — no manual value
+ * needed.
+ */
 export const WithLongContent: Story = {
   render: () => ({
     components: { CpTransitionExpand },

package/src/stories/CpTransitionListItems.stories.ts

@@ -1,6 +1,6 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 import type { MenuItem } from 'primevue/menuitem'
 
 import CpButton from '@/components/CpButton.vue'
@@ -51,6 +51,11 @@ const fabWrapperStyle = {
   alignItems: 'flex-end',
 }
 
+/**
+ * Animate list insertions, removals and reorders with FLIP-based
+ * transitions. Use the + / shuffle buttons to see the enter, leave and
+ * move animations.
+ */
 export const Default: Story = {
   args: {
     disableOnLoad: false,

package/src/stories/CpTransitionSize.stories.ts

@@ -1,6 +1,6 @@
 import { computed, ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpButton from '@/components/CpButton.vue'
 import CpTransitionSize from '@/components/CpTransitionSize.vue'
@@ -21,6 +21,10 @@ type Story = StoryObj<typeof meta>
 
 const wrapperStyle = 'display: flex; flex-direction: column; align-items: center; gap: 12px;'
 
+/**
+ * Animate a button's width when its inner label changes. Click the
+ * button to swap between a short and a longer label.
+ */
 export const Default: Story = {
   args: {
     type: 'width',
@@ -50,6 +54,10 @@ export const Default: Story = {
   }),
 }
 
+/**
+ * Height mode — smoothly animates a dialog's body height as the step
+ * content (and therefore its size) changes.
+ */
 export const HeightTransition: Story = {
   args: {
     type: 'height',

package/src/stories/CpTransitionSlide.stories.ts

@@ -1,6 +1,6 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpButton from '@/components/CpButton.vue'
 import CpTransitionSlide from '@/components/CpTransitionSlide.vue'
@@ -28,6 +28,10 @@ const wrapperStyle = 'display: flex; flex-direction: column; align-items: center
 const panelStyle =
   'min-width: 260px; max-width: 320px; padding: 20px; border-radius: 12px; background: #f3f4f6; text-align: center;'
 
+/**
+ * Slide between two panels. The `slideTo` prop controls direction
+ * (`top` or `left`) and `mode` follows Vue's `<Transition mode>` rules.
+ */
 export const Toggle: Story = {
   name: 'Toggle',
   args: {