@citizenplane/pimp 16.0.3 → 16.2.0

package/src/stories/CpAlert.stories.ts

@@ -1,29 +1,27 @@
-import type { Args, Meta, StoryObj } from '@storybook/vue3'
+import type { Args, Meta, StoryObj } from '@storybook/vue3-vite'
 
 import CpAlert from '@/components/CpAlert.vue'
 
-import {
-  docCellStyle,
-  docLabelStyle,
-  docPageStyle,
-  docRowColumnStyle,
-  docSectionStyle,
-  docTitleStyle,
-} from '@/stories/documentationStyles'
+import { docCellStyle, docLabelStyle, docRowColumnStyle } from '@/stories/documentationStyles'
+
+const alertColors = ['neutral', 'accent', 'success', 'warning', 'error'] as const
+const alertTypes = ['expanded', 'inline'] as const
+
+const alertStackStyle = `${docCellStyle} width: 100%; min-width: 420px;`
 
 const meta = {
-  title: 'Feedback/CpAlert',
+  title: 'Molecules/CpAlert',
   component: CpAlert,
   argTypes: {
     color: {
       control: 'select',
-      options: ['neutral', 'accent', 'success', 'warning', 'error'],
+      options: alertColors,
       description: 'The color variant of the alert',
     },
     type: {
       control: 'select',
-      options: ['expanded', 'inline'],
-      description: 'The type of the alert',
+      options: alertTypes,
+      description: 'The layout type of the alert',
     },
     title: {
       control: 'text',
@@ -31,16 +29,16 @@ const meta = {
     },
     content: {
       control: 'text',
-      description: 'The text content of the alert',
+      description: 'The text content of the alert (expanded type only)',
     },
     icon: {
       control: 'select',
       options: ['', 'info', 'check', 'alert-triangle', 'x-octagon', 'bell', 'star'],
-      description: 'Custom icon override',
+      description: 'Custom icon override. Defaults to the color-specific icon when empty.',
     },
     isClosable: {
       control: 'boolean',
-      description: 'Whether the alert can be closed',
+      description: 'Whether the alert shows a close button',
     },
     primaryActionLabel: {
       control: 'text',
@@ -66,169 +64,208 @@ const defaultRender = (args: Args) => ({
   template: defaultTemplate,
 })
 
-export const Documentation: Story = {
-  args: {},
+/**
+ * Default alert with a neutral color, expanded layout, a title and a content
+ * message. Use the controls to experiment with each prop in isolation.
+ */
+export const Default: Story = {
+  args: {
+    color: 'neutral',
+    type: 'expanded',
+    title: 'Alert title',
+    content: 'This is an informational alert message.',
+    isClosable: false,
+    icon: undefined,
+    primaryActionLabel: undefined,
+    secondaryActionLabel: undefined,
+  },
+  render: defaultRender,
+}
+
+/* -------------------------------------------------------------------------- */
+/* Colors                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Every semantic color available for the alert, stacked vertically.
+ */
+export const Colors: Story = {
+  parameters: { controls: { disable: true } },
   render: () => ({
     components: { CpAlert },
-    setup: () => ({}),
+    setup() {
+      return { alertColors, docRowColumnStyle, alertStackStyle, docLabelStyle }
+    },
     template: `
-      <div>
-        <div style="${docPageStyle}">
-          <h1 style="margin: 0 0 32px 0; font-size: 28px; font-weight: 700; color: #111;">CpAlert</h1>
+      <div :style="docRowColumnStyle">
+        <div v-for="color in alertColors" :key="color" :style="alertStackStyle">
+          <span :style="docLabelStyle">{{ color }}</span>
+          <CpAlert
+            :color="color"
+            :title="color.charAt(0).toUpperCase() + color.slice(1) + ' alert'"
+            content="This is an informational alert message."
+          />
+        </div>
+      </div>
+    `,
+  }),
+}
 
-          <section style="${docSectionStyle}">
-            <h2 style="${docTitleStyle}">Color</h2>
-            <div style="${docRowColumnStyle}">
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">neutral</span>
-                <CpAlert color="neutral" title="Neutral alert" content="This is a neutral informational message." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">accent</span>
-                <CpAlert color="accent" title="Accent alert" content="This is an accent informational message." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">success</span>
-                <CpAlert color="success" title="Success alert" content="The operation completed successfully." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">warning</span>
-                <CpAlert color="warning" title="Warning alert" content="Please review before proceeding." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">error</span>
-                <CpAlert color="error" title="Error alert" content="Something went wrong. Please try again." is-closable />
-              </div>
-            </div>
-          </section>
+/* -------------------------------------------------------------------------- */
+/* Layout types                                                               */
+/* -------------------------------------------------------------------------- */
 
-          <section style="${docSectionStyle}">
-            <h2 style="${docTitleStyle}">Type</h2>
-            <div style="${docRowColumnStyle}">
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">Expanded (default)</span>
-                <CpAlert color="neutral" title="Neutral alert" content="This is a neutral informational message." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="accent" title="Accent alert" content="This is an accent informational message." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="success" title="Success alert" content="The operation completed successfully." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="warning" title="Warning alert" content="Please review before proceeding." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="error" title="Error alert" content="Something went wrong. Please try again." is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">inline</span>
-                <CpAlert color="neutral" type="inline" title="Neutral alert" is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="accent" type="inline" title="Accent alert" is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="success" type="inline" title="Success alert" is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="warning" type="inline" title="Warning alert" is-closable />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="error" type="inline" title="Error alert" is-closable />
-              </div>
-            </div>
-          </section>
+/**
+ * `expanded` stacks the title, content and actions vertically. `inline` keeps
+ * them on a single line and hides the content area — best for short messages.
+ */
+export const Types: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpAlert },
+    setup() {
+      return { alertTypes, docRowColumnStyle, alertStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div v-for="type in alertTypes" :key="type" :style="alertStackStyle">
+          <span :style="docLabelStyle">{{ type }}</span>
+          <CpAlert
+            color="accent"
+            :type="type"
+            title="Alert title"
+            content="This is an informational alert message."
+            primary-action-label="Action"
+          />
+        </div>
+      </div>
+    `,
+  }),
+}
 
-          <section style="${docSectionStyle}">
-            <h2 style="${docTitleStyle}">Text only</h2>
-            <div style="${docRowColumnStyle}">
-              <div style="${docCellStyle}">
-                <CpAlert color="accent" content="This is an accent informational message." is-closable />
-              </div>
-            </div>
-          </section>
+/* -------------------------------------------------------------------------- */
+/* Content combinations                                                       */
+/* -------------------------------------------------------------------------- */
 
-          <section style="${docSectionStyle}">
-            <h2 style="${docTitleStyle}">is-closable</h2>
-            <div style="${docRowColumnStyle}">
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">false</span>
-                <CpAlert color="accent" title="Not closable" content="This alert cannot be dismissed." @on-close="console.log('alert closed')" />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">true on expanded</span>
-                <CpAlert color="accent" title="Closable" content="This alert can be dismissed with the close button." :is-closable="true" @on-close="console.log('alert closed')" />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">true on inline</span>
-                <CpAlert color="accent" type="inline" title="Closable" :is-closable="true" @on-close="console.log('alert closed')" />
-              </div>
-            </div>
-          </section>
+/**
+ * The three supported content combinations: title only, content only, and
+ * both title and content.
+ */
+export const ContentLayouts: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpAlert },
+    setup() {
+      return { docRowColumnStyle, alertStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="alertStackStyle">
+          <span :style="docLabelStyle">Title only</span>
+          <CpAlert color="accent" title="Title only" />
+        </div>
+        <div :style="alertStackStyle">
+          <span :style="docLabelStyle">Content only</span>
+          <CpAlert color="accent" content="Only a description, without a title on top." />
+        </div>
+        <div :style="alertStackStyle">
+          <span :style="docLabelStyle">Title and content</span>
+          <CpAlert
+            color="accent"
+            title="Title and content"
+            content="The full layout with both title and description."
+          />
+        </div>
+      </div>
+    `,
+  }),
+}
 
-          <section style="${docSectionStyle}">
-            <h2 style="${docTitleStyle}">Actions</h2>
-            <div style="${docRowColumnStyle}">
-            <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">without actions</span>
-                <CpAlert color="accent" title="Without actions" />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">primary only</span>
-                <CpAlert color="accent" title="With primary action" content="This alert has a primary action button." primary-action-label="Confirm" is-closable @primary-action-click="console.log('primary action clicked')" />
-              </div>
-              <div style="${docCellStyle}">
-                <CpAlert color="accent" title="With primary action" type="inline" primary-action-label="Confirm" is-closable @primary-action-click="console.log('primary action clicked')" />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">primary + secondary</span>
-                <CpAlert color="accent" title="With both actions" content="This alert has primary and secondary action buttons." primary-action-label="Confirm" secondary-action-label="Cancel" is-closable @primary-action-click="console.log('primary action clicked')" @secondary-action-click="console.log('secondary action clicked')" />
-              </div>
-            </div>
-          </section>
+/* -------------------------------------------------------------------------- */
+/* Dismiss & actions                                                          */
+/* -------------------------------------------------------------------------- */
 
-          <section style="${docSectionStyle}">
-            <h2 style="${docTitleStyle}">Custom icon</h2>
-            <div style="${docRowColumnStyle}">
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">default icon (auto from color)</span>
-                <CpAlert color="success" title="Default icon" content="Icon is derived from the color prop." />
-              </div>
-              <div style="${docCellStyle}">
-                <span style="${docLabelStyle}">custom icon override</span>
-                <CpAlert color="success" icon="star" title="Custom icon" content="Icon is overridden with a star." />
-              </div>
-            </div>
-          </section>
+/**
+ * All dismiss and action affordances shown side by side: closable, primary
+ * action, secondary action, and both actions together.
+ */
+export const Actions: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => ({
+    components: { CpAlert },
+    setup() {
+      return { docRowColumnStyle, alertStackStyle, docLabelStyle }
+    },
+    template: `
+      <div :style="docRowColumnStyle">
+        <div :style="alertStackStyle">
+          <span :style="docLabelStyle">Closable</span>
+          <CpAlert
+            color="accent"
+            title="Closable alert"
+            content="Click the × to dismiss."
+            :is-closable="true"
+          />
+        </div>
+        <div :style="alertStackStyle">
+          <span :style="docLabelStyle">Primary action</span>
+          <CpAlert
+            color="accent"
+            title="Action required"
+            content="Use the primary action to move forward."
+            primary-action-label="Confirm"
+          />
+        </div>
+        <div :style="alertStackStyle">
+          <span :style="docLabelStyle">Secondary action</span>
+          <CpAlert
+            color="accent"
+            title="Optional action"
+            content="The secondary action is visually less prominent."
+            secondary-action-label="Learn more"
+          />
+        </div>
+        <div :style="alertStackStyle">
+          <span :style="docLabelStyle">Both actions</span>
+          <CpAlert
+            color="accent"
+            title="Choose what to do"
+            content="Two actions are shown side by side."
+            primary-action-label="Confirm"
+            secondary-action-label="Cancel"
+          />
         </div>
       </div>
     `,
   }),
-  parameters: {
-    controls: { disable: true },
-    docs: {
-      source: {
-        code: null,
-      },
-    },
-  },
 }
 
-export const Default: Story = {
+/* -------------------------------------------------------------------------- */
+/* Icon                                                                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Override the default color-specific icon with any icon name.
+ */
+export const CustomIcon: Story = {
   args: {
-    color: 'neutral',
-    type: 'expanded',
-    title: 'Alert title',
-    content: 'This is an informational alert message.',
-    isClosable: false,
-    icon: undefined,
-    primaryActionLabel: undefined,
-    secondaryActionLabel: undefined,
+    ...Default.args,
+    color: 'accent',
+    title: 'Custom icon',
+    content: 'Any icon from the design system can replace the default one.',
+    icon: 'bell',
   },
   render: defaultRender,
 }
 
+/* -------------------------------------------------------------------------- */
+/* Slots                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Customize every part of the alert using slots: `icon`, `title`, default
+ * (content), `primary-action` and `secondary-action`.
+ */
 export const WithSlots: Story = {
   args: {
     color: 'accent',