@citizenplane/pimp 16.0.3 → 16.2.0

package/src/stories/CpHeading.stories.ts

@@ -1,67 +1,107 @@
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Args, Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpHeading from '@/components/CpHeading.vue'
 
+import { HeadingLevels } from '@/constants'
+import { docLabelStyle } from '@/stories/documentationStyles'
+
+const headingLevels = Object.values(HeadingLevels)
+const headingSizes = [100, 200, 300, 400, 500, 600, 700, 800, 900] as const
+
+const headingRowStyle = 'display: grid; grid-template-columns: 90px 1fr; gap: 16px; align-items: center;'
+
 const meta = {
-  title: 'Visual/CpHeading',
+  title: 'Atoms/CpHeading',
   component: CpHeading,
+  tags: ['deprecated'],
+  parameters: {
+    docs: {
+      description: {
+        component: '> ⚠️ **Deprecated.** `CpHeading` is kept for backwards compatibility only. Use CpText instead.',
+      },
+    },
+  },
   argTypes: {
     headingLevel: {
       control: 'select',
-      options: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      options: headingLevels,
       description: 'HTML heading level',
     },
     size: {
       control: 'select',
-      options: [100, 200, 300, 400, 500, 600, 700, 800, 900],
+      options: headingSizes,
       description: 'Size variant of the heading',
     },
   },
 } satisfies Meta<typeof CpHeading>
 
 export default meta
+
 type Story = StoryObj<typeof meta>
 
+/**
+ * @deprecated Default heading. Prefer native `<h1>`–`<h6>` styled with typography CSS variables.
+ */
 export const Default: Story = {
   args: {
-    headingLevel: 'h1',
+    headingLevel: HeadingLevels.H1,
     size: 500,
   },
-  render: (args) => ({
+  render: (args: Args) => ({
     components: { CpHeading },
     setup() {
       return { args }
     },
     template: `
       <div style="padding: 20px;">
-        <CpHeading v-bind="args">
-          Default Heading
-        </CpHeading>
+        <CpHeading v-bind="args">Default Heading</CpHeading>
       </div>
     `,
   }),
 }
 
-export const AllSizes: Story = {
+/* -------------------------------------------------------------------------- */
+/* Sizes                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * @deprecated All sizes stacked from `100` (smallest) to `900` (largest). The
+ * visual size is decoupled from the semantic HTML level.
+ */
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpHeading },
+    setup() {
+      return {
+        headingSizes,
+        headingRowStyle,
+        docLabelStyle,
+      }
+    },
     template: `
       <div style="padding: 20px; display: flex; flex-direction: column; gap: 16px;">
-        <CpHeading size="100">Size 100 Heading</CpHeading>
-        <CpHeading size="200">Size 200 Heading</CpHeading>
-        <CpHeading size="300">Size 300 Heading</CpHeading>
-        <CpHeading size="400">Size 400 Heading</CpHeading>
-        <CpHeading size="500">Size 500 Heading</CpHeading>
-        <CpHeading size="600">Size 600 Heading</CpHeading>
-        <CpHeading size="700">Size 700 Heading</CpHeading>
-        <CpHeading size="800">Size 800 Heading</CpHeading>
-        <CpHeading size="900">Size 900 Heading</CpHeading>
+        <div v-for="size in headingSizes" :key="size" :style="headingRowStyle">
+          <span :style="docLabelStyle">{{ size }}</span>
+          <CpHeading :size="size">Size {{ size }} Heading</CpHeading>
+        </div>
       </div>
     `,
   }),
 }
 
-export const SizeAndLevelCombination: Story = {
+/* -------------------------------------------------------------------------- */
+/* Semantic level                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * @deprecated The recommended pairing between semantic HTML level and visual
+ * size — but any combination is valid. Picking the right `headingLevel`
+ * matters for accessibility and document outline, while `size` controls the
+ * look.
+ */
+export const LevelAndSizePairing: Story = {
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpHeading },
     template: `

package/src/stories/CpIcon.stories.ts

@@ -1,8 +1,10 @@
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { Args, Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpIcon from '@/components/CpIcon.vue'
 
 import { CustomCpIcons } from '@/constants'
+import { docCellStyle, docLabelStyle, docRowWrapStyle } from '@/stories/documentationStyles'
+import { copyableClass, copyableCopiedClass, useCopier } from '@/stories/tokenUtils'
 
 const iconsOptions = [
   ...Object.keys(CustomCpIcons),
@@ -29,9 +31,12 @@ const iconsOptions = [
   'invalid-icon-name',
 ].sort()
 
+const iconSizes = [16, 24, 32, 48] as const
+
 const meta = {
-  title: 'Visual/CpIcon',
+  title: 'Foundations/CpIcon',
   component: CpIcon,
+  tags: ['!dev'],
   argTypes: {
     type: {
       control: 'select',
@@ -52,13 +57,16 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
+/**
+ * Default icon. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     type: 'check',
     size: 24,
     tag: 'i',
   },
-  render: (args) => ({
+  render: (args: Args) => ({
     components: { CpIcon },
     setup() {
       return { args }
@@ -71,42 +79,76 @@ export const Default: Story = {
   }),
 }
 
-export const DifferentSizes: Story = {
-  args: {
-    type: 'check',
-  },
-  render: (args) => ({
+/* -------------------------------------------------------------------------- */
+/* Sizes                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The icon scales freely through the `size` prop (pixel value). Below are
+ * the most common sizes used across the design system.
+ */
+export const Sizes: Story = {
+  args: { type: 'check' },
+  parameters: { controls: { disable: true } },
+  render: () => ({
     components: { CpIcon },
     setup() {
-      return { args }
+      return { iconSizes, docCellStyle, docLabelStyle, docRowWrapStyle }
     },
     template: `
-      <div style="padding: 20px; display: flex; align-items: center; gap: 16px;">
-        <CpIcon v-bind="{ ...args, size: 16 }" />
-        <CpIcon v-bind="{ ...args, size: 24 }" />
-        <CpIcon v-bind="{ ...args, size: 32 }" />
-        <CpIcon v-bind="{ ...args, size: 48 }" />
+      <div :style="docRowWrapStyle">
+        <div v-for="size in iconSizes" :key="size" :style="docCellStyle">
+          <span :style="docLabelStyle">{{ size }}px</span>
+          <CpIcon type="check" :size="size" />
+        </div>
       </div>
     `,
   }),
 }
 
+/* -------------------------------------------------------------------------- */
+/* Catalog                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Every available icon rendered on a neutral surface. Hover a cell to see
+ * the icon name.
+ */
 export const AllIcons: Story = {
-  args: {
-    type: 'check',
-  },
+  args: { type: 'check' },
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpIcon },
     setup() {
-      return { icons: iconsOptions }
+      const { copiedKey, copy } = useCopier()
+      return {
+        icons: iconsOptions,
+        copiedKey,
+        copy,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+      }
     },
     template: `
       <div style="padding: 20px; display: grid; grid-template-columns: repeat(4, minmax(100px, 3fr)); gap: 16px;">
-        <div v-for="icon in icons" style="display: flex; flex-direction: column; align-items: center;border: 1px solid #eee;border-radius: 4px;">
-          <span style="font-size: 12px; padding: 8px; word-break: break-word;">{{ icon }}</span>
-          <hr style="width: 100%; background-color: #eee; height: 1px; border: 0" />
+        <div
+          v-for="icon in icons"
+          :key="icon"
+          style="display: flex; flex-direction: column; align-items: center; border: 1px solid #eee; border-radius: 4px;"
+        >
+          <span
+            style="font-size: 12px; padding: 8px; word-break: break-word;"
+            :class="[copyClass, copiedKey === icon ? copiedClass : '']"
+            role="button"
+            tabindex="0"
+            :title="'Click to copy ' + icon"
+            @click="copy(icon)"
+            @keydown.enter.prevent="copy(icon)"
+            @keydown.space.prevent="copy(icon)"
+          >{{ copiedKey === icon ? 'Copied!' : icon }}</span>
+          <hr style="width: 100%; background-color: #eee; height: 1px; border: 0;" />
           <div style="padding: 20px;">
-            <CpIcon :key="icon" :type="icon" />
+            <CpIcon :type="icon" />
           </div>
         </div>
       </div>
@@ -114,22 +156,47 @@ export const AllIcons: Story = {
   }),
 }
 
+/**
+ * Same catalog rendered on a colored surface to verify that icons inherit
+ * the current text color.
+ */
 export const AllIconsColored: Story = {
-  args: {
-    type: 'check',
-  },
+  args: { type: 'check' },
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpIcon },
     setup() {
-      return { icons: iconsOptions }
+      const { copiedKey, copy } = useCopier()
+      return {
+        icons: iconsOptions,
+        copiedKey,
+        copy,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+      }
     },
     template: `
       <div style="padding: 20px; display: grid; grid-template-columns: repeat(4, minmax(100px, 3fr)); gap: 16px;">
-        <div v-for="icon in icons" style="display: flex; flex-direction: column; align-items: center;border: 1px solid #eee;border-radius: 4px;">
-          <span style="font-size: 12px; padding: 8px; word-break: break-word;">{{ icon }}</span>
-          <hr style="width: 100%; background-color: #eee; height: 1px; border: 0" />
-          <div style="padding: 20px; color: green;background-color: #f0fdf4;width: 100%;display: flex;align-items: center;justify-content: center;height: 100%;">
-            <CpIcon :key="icon" :type="icon" />
+        <div
+          v-for="icon in icons"
+          :key="icon"
+          style="display: flex; flex-direction: column; align-items: center; border: 1px solid #eee; border-radius: 4px;"
+        >
+          <span
+            style="font-size: 12px; padding: 8px; word-break: break-word;"
+            :class="[copyClass, copiedKey === icon ? copiedClass : '']"
+            role="button"
+            tabindex="0"
+            :title="'Click to copy ' + icon"
+            @click="copy(icon)"
+            @keydown.enter.prevent="copy(icon)"
+            @keydown.space.prevent="copy(icon)"
+          >{{ copiedKey === icon ? 'Copied!' : icon }}</span>
+          <hr style="width: 100%; background-color: #eee; height: 1px; border: 0;" />
+          <div
+            style="padding: 20px; color: green; background-color: #f0fdf4; width: 100%; display: flex; align-items: center; justify-content: center; height: 100%;"
+          >
+            <CpIcon :type="icon" />
           </div>
         </div>
       </div>

package/src/stories/CpInput.stories.ts

@@ -1,12 +1,30 @@
 import { ref } from 'vue'
 
-import type { Meta, StoryObj } from '@storybook/vue3'
+import type { ComponentPropsAndSlots, Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpIcon from '@/components/CpIcon.vue'
 import CpInput from '@/components/CpInput.vue'
 
+import { docCellStyle, docLabelStyle, docRowColumnStyle } from '@/stories/documentationStyles'
+
+/** Native attributes forwarded to the inner `<input>` (not declared as Vue props). */
+type CpInputPassthroughAttrs = {
+  autocomplete?: string
+  disabled?: boolean
+  placeholder?: string
+  required?: boolean
+  type?: string
+}
+
+type CpInputStoryArgs = ComponentPropsAndSlots<typeof CpInput> & CpInputPassthroughAttrs
+
+const inputSizes = ['sm', 'md', 'lg'] as const
+const inputTypes = ['text', 'email', 'password', 'number', 'tel', 'url'] as const
+
+const inputStackStyle = `${docCellStyle} width: 100%; max-width: 360px;`
+
 const meta = {
-  title: 'Form/CpInput',
+  title: 'Atoms/CpInput',
   component: CpInput,
   argTypes: {
     modelValue: {
@@ -15,12 +33,12 @@ const meta = {
     },
     size: {
       control: 'select',
-      options: ['sm', 'md', 'lg'],
+      options: inputSizes,
       description: 'The size of the input',
     },
     type: {
       control: 'select',
-      options: ['text', 'email', 'password', 'number', 'tel', 'url'],
+      options: inputTypes,
       description: 'The type of input',
     },
     label: {
@@ -52,11 +70,19 @@ const meta = {
       description: 'Autocomplete attribute value',
     },
   },
-} satisfies Meta<typeof CpInput>
+} satisfies Meta<CpInputStoryArgs>
 
 export default meta
-type Story = StoryObj<typeof meta>
 
+// Use explicit args type: `StoryObj<typeof meta>` would re-infer args from `component` only
+// and drop native attributes passed through `$attrs`.
+type Story = StoryObj<CpInputStoryArgs>
+
+type StoryArgs = Partial<CpInputStoryArgs>
+
+/**
+ * Default input. Use the controls to experiment with each prop in isolation.
+ */
 export const Default: Story = {
   args: {
     label: 'Input Label',
@@ -72,7 +98,7 @@ export const Default: Story = {
     isSearch: false,
     help: '',
   },
-  render: (args) => ({
+  render: (args: StoryArgs) => ({
     components: { CpInput },
     setup() {
       const value = ref('')
@@ -80,64 +106,127 @@ export const Default: Story = {
     },
     template: `
       <div style="max-width: 400px; padding: 20px;">
-        <CpInput
-          v-model="value"
-          v-bind="args"
-        />
+        <CpInput 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 } },
+  render: () => ({
+    components: { CpInput },
+    setup() {
+      const value = ref('')
+      return { value, inputSizes, docRowColumnStyle, inputStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div v-for="size in inputSizes" :key="size" :style="inputStackStyle">
+          <span :style="docLabelStyle">{{ size }}</span>
+          <CpInput v-model="value" :size="size" label="Input label" placeholder="Enter text here" />
+        </div>
+      </div>
+    `,
+  }),
 }
 
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    disabled: true,
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* States                                                                     */
+/* -------------------------------------------------------------------------- */
 
-export const Email: Story = {
-  args: {
-    ...Default.args,
-    type: 'email',
-    label: 'Email Address',
-    placeholder: 'Enter your email',
-  },
+/**
+ * Default, required, disabled and invalid states compared side by side.
+ */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpInput },
+    setup() {
+      const value = ref('')
+      return { value, docRowColumnStyle, inputStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">Default</span>
+          <CpInput v-model="value" label="Input label" placeholder="Enter text here" />
+        </div>
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">Required</span>
+          <CpInput v-model="value" label="Input label" placeholder="Enter text here" :required="true" />
+        </div>
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">Disabled</span>
+          <CpInput v-model="value" label="Input label" placeholder="Enter text here" :disabled="true" />
+        </div>
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">Invalid</span>
+          <CpInput
+            v-model="value"
+            label="Input label"
+            placeholder="Enter text here"
+            :is-invalid="true"
+            error-message="This field is required"
+          />
+        </div>
+      </div>
+    `,
+  }),
 }
 
-export const Password: Story = {
-  args: {
-    ...Default.args,
-    type: 'password',
-    label: 'Password',
-    placeholder: 'Enter your password',
-  },
-}
+/* -------------------------------------------------------------------------- */
+/* Types                                                                      */
+/* -------------------------------------------------------------------------- */
 
-export const Number: Story = {
-  args: {
-    ...Default.args,
-    type: 'number',
-    label: 'Amount',
-    placeholder: 'Enter amount',
-  },
+/**
+ * Native HTML input types wired to the appropriate keyboard and validation.
+ */
+export const Types: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpInput },
+    setup() {
+      const value = ref('')
+      return { value, docRowColumnStyle, inputStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">text</span>
+          <CpInput v-model="value" type="text" label="Name" placeholder="Your full name" />
+        </div>
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">email</span>
+          <CpInput v-model="value" type="email" label="Email address" placeholder="you@example.com" />
+        </div>
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">password</span>
+          <CpInput v-model="value" type="password" label="Password" placeholder="Enter your password" />
+        </div>
+        <div :style="inputStackStyle">
+          <span :style="docLabelStyle">number</span>
+          <CpInput v-model="value" type="number" label="Amount" placeholder="Enter amount" />
+        </div>
+      </div>
+    `,
+  }),
 }
 
+/* -------------------------------------------------------------------------- */
+/* Help & tooltip                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Attach a help text under the field and a tooltip next to the label.
+ */
 export const HelpAndTooltip: Story = {
   args: {
     ...Default.args,
@@ -146,6 +235,13 @@ export const HelpAndTooltip: Story = {
   },
 }
 
+/* -------------------------------------------------------------------------- */
+/* Variants                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Search input with a built-in icon.
+ */
 export const Search: Story = {
   args: {
     ...Default.args,
@@ -153,6 +249,9 @@ export const Search: Story = {
   },
 }
 
+/**
+ * Input masked with a pattern (phone numbers, card numbers, etc.).
+ */
 export const Mask: Story = {
   args: {
     ...Default.args,
@@ -161,11 +260,12 @@ export const Mask: Story = {
   },
 }
 
+/**
+ * Slot icons on either side of the input.
+ */
 export const WithIcon: Story = {
-  args: {
-    ...Default.args,
-  },
-  render: (args) => ({
+  args: { ...Default.args },
+  render: (args: StoryArgs) => ({
     components: { CpInput, CpIcon },
     setup() {
       const value = ref('')
@@ -173,10 +273,7 @@ export const WithIcon: Story = {
     },
     template: `
       <div style="max-width: 400px; padding: 20px;">
-        <CpInput
-          v-model="value"
-          v-bind="args"
-        >
+        <CpInput v-model="value" v-bind="args">
           <template #trailing-icon>
             <CpIcon type="users" />
           </template>
@@ -189,11 +286,13 @@ export const WithIcon: Story = {
   }),
 }
 
+/**
+ * Use the icon slots to render unit labels, perfect for currencies or
+ * measurement units.
+ */
 export const WithUnits: Story = {
-  args: {
-    ...Default.args,
-  },
-  render: (args) => ({
+  args: { ...Default.args },
+  render: (args: StoryArgs) => ({
     components: { CpInput },
     setup() {
       const value = ref('')
@@ -201,11 +300,7 @@ export const WithUnits: Story = {
     },
     template: `
       <div style="display: flex; flex-direction: column; gap: 10px; max-width: 400px; padding: 20px;">
-        <CpInput
-          v-model="value"
-          mask="####"
-          v-bind="args"
-        >
+        <CpInput v-model="value" mask="####" v-bind="args">
           <template #leading-icon>
             €
           </template>
@@ -214,11 +309,7 @@ export const WithUnits: Story = {
           </template>
         </CpInput>
 
-        <CpInput
-          v-model="value"
-          mask="####"
-          v-bind="args"
-        >
+        <CpInput v-model="value" mask="####" v-bind="args">
           <template #leading-icon>
             kg
           </template>