@citizenplane/pimp 16.0.2 → 16.1.0

package/src/stories/CpTelInput.stories.ts

@@ -1,9 +1,11 @@
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Args, Meta, StoryObj } from '@storybook/vue3'
 
 import CpTelInput from '@/components/CpTelInput.vue'
 
+const telInputSizes = ['md', 'lg'] as const
+
 const meta = {
-  title: 'Form/CpTelInput',
+  title: 'Molecules/CpTelInput',
   component: CpTelInput,
   argTypes: {
     telModel: {
@@ -12,7 +14,7 @@ const meta = {
     },
     size: {
       control: 'select',
-      options: ['md', 'lg'],
+      options: telInputSizes,
       description: 'The size of the input',
     },
   },
@@ -21,28 +23,28 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  args: {
-    telModel: '',
+const defaultRender = (args: Args) => ({
+  components: { CpTelInput },
+  setup() {
+    return { args }
   },
-  render: (args) => ({
-    components: { CpTelInput },
-    setup() {
-      return { args }
-    },
-    template: `<CpTelInput v-bind="args" />`,
-  }),
+  template: '<CpTelInput v-bind="args" />',
+})
+
+/**
+ * Default telephone input with a country selector. Use the controls to
+ * experiment with each prop in isolation.
+ */
+export const Default: Story = {
+  args: { telModel: '' },
+  render: defaultRender,
 }
 
+/**
+ * Pre-select a country via the `defaultCountry` ISO-2 code (e.g. `us`,
+ * `fr`, `gb`).
+ */
 export const WithDefaultCountry: Story = {
-  args: {
-    defaultCountry: 'us',
-  },
-  render: (args) => ({
-    components: { CpTelInput },
-    setup() {
-      return { args }
-    },
-    template: `<CpTelInput v-bind="args" />`,
-  }),
+  args: { defaultCountry: 'us' },
+  render: defaultRender,
 }

package/src/stories/CpText.stories.ts

@@ -0,0 +1,131 @@
+import type { Args, Meta, StoryObj } from '@storybook/vue3'
+
+import CpText from '@/components/CpText.vue'
+import type { CpTextSize, CpTextWeight } from '@/components/CpText.vue'
+
+import { docLabelStyle } from '@/stories/documentationStyles'
+
+const textSizes = [
+  'xs',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  '2xl',
+  '3xl',
+  '4xl',
+  '5xl',
+  '6xl',
+  '7xl',
+  '8xl',
+  '9xl',
+] as const satisfies readonly CpTextSize[]
+
+const weights = [400, 500, 600, 700] as const satisfies readonly CpTextWeight[]
+
+const rowStyle = 'display: grid; grid-template-columns: 56px 1fr; gap: 16px; align-items: center;'
+
+const sizesRowStyle = 'display: flex; align-items: center; gap: 16px; width: max-content;'
+
+const meta = {
+  title: 'Atoms/CpText',
+  component: CpText,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Typography primitive for body and UI copy. Pairs each `size` with the matching `--cp-text-size-*` and `--cp-line-height-*` design tokens. Override the root element with `tag` (defaults to `p`).',
+      },
+    },
+  },
+  argTypes: {
+    tag: {
+      control: 'text',
+      description: 'Root HTML tag (default: `p`).',
+    },
+    size: {
+      control: 'select',
+      options: textSizes,
+      description: 'Scale step from `xs` through `9xl`; maps to typography CSS variables.',
+    },
+    weight: {
+      control: 'select',
+      options: [undefined, ...weights],
+      description: 'Font weight from 400 to 700.',
+    },
+  },
+} satisfies Meta<typeof CpText>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    size: 'md',
+  },
+  render: (args: Args) => ({
+    components: { CpText },
+    setup() {
+      return { args }
+    },
+    template: `
+      <div style="padding: 20px;">
+        <CpText v-bind="args">Body text using the size and line-height tokens.</CpText>
+      </div>
+    `,
+  }),
+}
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true }, layout: 'padded' },
+  render: () => ({
+    components: { CpText },
+    setup() {
+      return { textSizes, sizesRowStyle, docLabelStyle }
+    },
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 12px; overflow-x: auto; max-width: 100%;">
+        <div v-for="size in textSizes" :key="size" :style="sizesRowStyle">
+          <span :style="docLabelStyle + ' flex: 0 0 56px;'">{{ size }}</span>
+          <CpText :size="size" style="white-space: nowrap;">A design system offers guidelines and components for consistent visuals and better user experience.</CpText>
+        </div>
+      </div>
+    `,
+  }),
+}
+
+export const Weights: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpText },
+    setup() {
+      return { weights, rowStyle, docLabelStyle }
+    },
+    template: `
+      <div style="padding: 20px; display: flex; flex-direction: column; gap: 12px;">
+        <div v-for="w in weights" :key="w" :style="rowStyle">
+          <span :style="docLabelStyle">{{ w }}</span>
+          <CpText :weight="w">Create a harmonious user experience</CpText>
+        </div>
+      </div>
+    `,
+  }),
+}
+
+export const CustomTag: Story = {
+  args: {
+    tag: 'span',
+    size: 'sm',
+  },
+  render: (args: Args) => ({
+    components: { CpText },
+    setup() {
+      return { args }
+    },
+    template: `
+      <div style="padding: 20px;">
+        <p>Inline text: <CpText v-bind="args">styled snippet</CpText> inside a paragraph.</p>
+      </div>
+    `,
+  }),
+}

package/src/stories/CpTextarea.stories.ts

@@ -4,8 +4,12 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 
 import CpTextarea from '@/components/CpTextarea.vue'
 
+import { docCellStyle, docLabelStyle, docRowColumnStyle } from '@/stories/documentationStyles'
+
+const textareaStackStyle = `${docCellStyle} width: 100%; max-width: 360px;`
+
 const meta = {
-  title: 'Form/CpTextarea',
+  title: 'Atoms/CpTextarea',
   component: CpTextarea,
   argTypes: {
     modelValue: {
@@ -50,6 +54,9 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default textarea. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     label: 'Textarea Label',
@@ -64,37 +71,63 @@ export const Default: Story = {
     },
     template: `
       <div style="max-width: 400px; padding: 20px;">
-        <CpTextarea
-          v-model="value"
-          v-bind="args"
-        />
+        <CpTextarea v-model="value" v-bind="args" />
       </div>
     `,
   }),
 }
 
-export const WithError: Story = {
-  args: {
-    ...Default.args,
-    isInvalid: true,
-    errorMessage: 'This field is required',
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
 
-export const Required: Story = {
-  args: {
-    ...Default.args,
-    required: true,
-  },
+/**
+ * Default, required, disabled and invalid states compared side by side.
+ */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpTextarea },
+    setup() {
+      const value = ref('')
+      return { value, docRowColumnStyle, textareaStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="textareaStackStyle">
+          <span :style="docLabelStyle">Default</span>
+          <CpTextarea v-model="value" label="Textarea label" placeholder="Enter your message here" />
+        </div>
+        <div :style="textareaStackStyle">
+          <span :style="docLabelStyle">Required</span>
+          <CpTextarea v-model="value" label="Textarea label" placeholder="Enter your message here" :required="true" />
+        </div>
+        <div :style="textareaStackStyle">
+          <span :style="docLabelStyle">Disabled</span>
+          <CpTextarea v-model="value" label="Textarea label" placeholder="Enter your message here" :disabled="true" />
+        </div>
+        <div :style="textareaStackStyle">
+          <span :style="docLabelStyle">Invalid</span>
+          <CpTextarea
+            v-model="value"
+            label="Textarea label"
+            placeholder="Enter your message here"
+            :is-invalid="true"
+            error-message="This field is required"
+          />
+        </div>
+      </div>
+    `,
+  }),
 }
 
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    disabled: true,
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* Variants                                                                   */
+/* -------------------------------------------------------------------------- */
 
+/**
+ * Enforce a character limit; a counter is shown below the field.
+ */
 export const WithMaxLength: Story = {
   args: {
     ...Default.args,
@@ -104,6 +137,9 @@ export const WithMaxLength: Story = {
   },
 }
 
+/**
+ * Adjust the number of visible rows through the `rows` prop.
+ */
 export const CustomRows: Story = {
   args: {
     ...Default.args,

package/src/stories/CpToast.stories.ts

@@ -7,13 +7,24 @@ import { CpToastTypes } from '@/constants/CpToastTypes'
 
 import CpToast from '@/components/CpToast.vue'
 
+const toastPositions = [
+  'center',
+  'top-left',
+  'top-center',
+  'top-right',
+  'bottom-left',
+  'bottom-center',
+  'bottom-right',
+] as const
+
 const meta: Meta<typeof CpToast> = {
-  title: 'Feedback/CpToast',
+  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: {
@@ -27,7 +38,11 @@ export default meta
 
 type Story = StoryObj<typeof CpToast>
 
-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,111 +50,50 @@ 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 notify = (severity: string) => toast.add({ ...baseOptions, severity })
 
-      const notifyInfo = () => {
-        toast.add({
-          ...baseOptions,
-          severity: CpToastTypes.INFO,
-        })
-      }
-
-      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,
@@ -151,20 +105,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,21 +128,17 @@ 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'),
           },
         })
       }
@@ -197,37 +148,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>
     `,
   }),