@citizenplane/pimp 16.0.2 → 16.1.0

package/src/stories/CpAccordion.stories.ts

@@ -6,15 +6,6 @@ import type { MenuItem } from 'primevue/menuitem'
 import type { CpAccordionBaseProps } from '@/components/CpAccordion.vue'
 import CpAccordion from '@/components/CpAccordion.vue'
 
-import {
-  docCellStyle,
-  docLabelStyle,
-  docPageStyle,
-  docRowColumnStyle,
-  docSectionStyle,
-  docTitleStyle,
-} from '@/stories/documentationStyles'
-
 /** Storybook controls: component props remain a discriminated union in `CpAccordion.vue`. */
 type CpAccordionStoryArgs = CpAccordionBaseProps & {
   actions?: MenuItem[]
@@ -37,7 +28,7 @@ const defaultStoryActions: MenuItem[] = [
 ]
 
 const meta = {
-  title: 'Visual/CpAccordion',
+  title: 'Molecules/CpAccordion',
   component: CpAccordion,
   argTypes: {
     title: {
@@ -50,16 +41,16 @@ const meta = {
     },
     hideActionTrigger: {
       control: 'boolean',
-      description: 'Whether to hide the action trigger',
+      description: 'Whether to hide the inline action trigger (leading icon mode)',
     },
     iconPosition: {
       control: 'select',
       options: ['leading', 'trailing'],
-      description: 'Chevron icon position',
+      description: 'Chevron icon position. `trailing` disables actions.',
     },
     quickOptionsLimit: {
       control: 'number',
-      description: 'Number of quick options to display',
+      description: 'Number of quick-access actions to display inline',
     },
     actions: {
       control: 'object',
@@ -74,7 +65,9 @@ type Story = StoryObj<typeof meta>
 
 const sampleContentStyle =
   'padding: 16px; font-size: 13px; color: #374151; background: repeating-linear-gradient(45deg, #fff9c4, #fff9c4 4px, #fffde7 4px, #fffde7 8px);'
-const highlightedSlotStyle = 'background: #fff9c4;'
+
+const wrapperStyle =
+  'box-sizing: border-box; width: 100%; max-width: 1200px; margin: 0 auto; padding: 20px; width: 500px;'
 
 const defaultRender = (args: Args) => ({
   components: { CpAccordion },
@@ -93,10 +86,10 @@ const defaultRender = (args: Args) => ({
       return args
     })
 
-    return { accordionArgs, sampleContentStyle }
+    return { accordionArgs, sampleContentStyle, wrapperStyle }
   },
   template: `
-    <div style="box-sizing: border-box; width: 100%; max-width: 1200px; margin: 0 auto; padding: 20px; width: 500px;">
+    <div :style="wrapperStyle">
       <CpAccordion v-bind="accordionArgs">
         <div :style="sampleContentStyle" />
       </CpAccordion>
@@ -104,163 +97,199 @@ const defaultRender = (args: Args) => ({
   `,
 })
 
-export const Documentation: Story = {
+/**
+ * Default accordion with a leading chevron icon, open by default and two quick actions.
+ */
+export const Default: Story = {
   args: {
-    title: 'I have title.',
+    title: 'I have a title.',
+    defaultOpenState: true,
+    iconPosition: 'leading',
+    quickOptionsLimit: 2,
+    hideActionTrigger: false,
+    actions: defaultStoryActions,
   },
-  render: () => ({
-    components: { CpAccordion },
-    setup: () => ({
-      docPageStyle,
-      docSectionStyle,
-      docTitleStyle,
-      docRowColumnStyle,
-      docCellStyle,
-      docLabelStyle,
-      sampleContentStyle,
-      highlightedSlotStyle,
-      actions: defaultStoryActions,
-    }),
-    template: `
-      <div :style="docPageStyle">
-        <h1 style="margin: 0 0 24px 0; font-size: 28px; font-weight: 700; color: #111827;">CpAccordion</h1>
+  render: defaultRender,
+}
 
-        <section :style="docSectionStyle">
-          <h2 :style="docTitleStyle">Is Open</h2>
-          <div :style="docRowColumnStyle">
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">false</span>
-              <CpAccordion title="I have title." :default-open-state="false" icon-position="trailing">
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">true</span>
-              <CpAccordion title="I have title." :default-open-state="true" icon-position="trailing">
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-          </div>
-        </section>
+/* -------------------------------------------------------------------------- */
+/* Icon position                                                              */
+/* -------------------------------------------------------------------------- */
 
-        <h2 style="margin: 0 0 16px 0; font-size: 16px; font-weight: 600; color: #111827;">
-          Unpublished Base: <span style="font-weight: 700;">Accordion Header</span>
-        </h2>
+/**
+ * The chevron is rendered at the beginning of the header. This is the default.
+ * Actions can be combined with this layout.
+ */
+export const LeadingIcon: Story = {
+  args: {
+    ...Default.args,
+    iconPosition: 'leading',
+    title: 'Leading chevron',
+  },
+  render: defaultRender,
+}
 
-        <section :style="docSectionStyle">
-          <h2 :style="docTitleStyle">Style</h2>
-          <div :style="docRowColumnStyle">
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">Leading Chevron</span>
-              <CpAccordion title="DIDA TRAVEL" :default-open-state="false" icon-position="leading">
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">Trailing Chevron</span>
-              <CpAccordion title="DIDA TRAVEL" :default-open-state="false" icon-position="trailing">
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-          </div>
-        </section>
+/**
+ * The chevron is rendered at the end of the header. This variant is
+ * action-less by design (the component enforces it through its prop types).
+ */
+export const TrailingIcon: Story = {
+  args: {
+    title: 'Trailing chevron',
+    defaultOpenState: false,
+    iconPosition: 'trailing',
+    quickOptionsLimit: 0,
+  },
+  render: defaultRender,
+}
 
-        <section :style="docSectionStyle">
-          <h2 :style="docTitleStyle">Actions</h2>
-          <div :style="docRowColumnStyle">
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">Default</span>
-              <CpAccordion title="DIDA TRAVEL" :default-open-state="false" icon-position="leading" :actions="actions" :quick-options-limit="3">
-                <template #trailing-slot>
-                  This is a trailing slot
-                </template>
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">Hide Action Trigger</span>
-              <CpAccordion
-                title="DIDA TRAVEL"
-                :default-open-state="false"
-                icon-position="leading"
-                style="background: var(--cp-background-primary-hover);"
-                :actions="actions"
-                :quick-options-limit="3"
-                hide-action-trigger
-              >
-                <template #trailing-slot>
-                  This is a trailing slot
-                </template>
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-          </div>
-        </section>
+/* -------------------------------------------------------------------------- */
+/* Open state                                                                 */
+/* -------------------------------------------------------------------------- */
 
-        <section :style="docSectionStyle">
-          <h2 :style="docTitleStyle">Has Leading Slot</h2>
-          <div :style="docRowColumnStyle">
-            <div :style="docCellStyle">
-              <CpAccordion title="DIDA TRAVEL" :default-open-state="false" icon-position="leading" :actions="actions" :quick-options-limit="3">
-                <template #leading-slot>
-                  <span :style="highlightedSlotStyle">I have text.</span>
-                </template>
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-            <div :style="docCellStyle">
-              <CpAccordion title="DIDA TRAVEL" :default-open-state="false" icon-position="trailing">
-                <template #leading-slot>
-                  <span :style="highlightedSlotStyle">I have text.</span>
-                </template>
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-          </div>
-        </section>
+/**
+ * The accordion renders open on first mount.
+ */
+export const OpenByDefault: Story = {
+  args: {
+    ...Default.args,
+    defaultOpenState: true,
+    title: 'Open on mount',
+  },
+  render: defaultRender,
+}
 
-        <section :style="docSectionStyle">
-          <h2 :style="docTitleStyle">Has Trailing Slot</h2>
-          <div :style="docRowColumnStyle">
-            <div :style="docCellStyle">
-              <CpAccordion title="DIDA TRAVEL" :default-open-state="false" icon-position="leading">
-                <template #trailing-slot>
-                  <span :style="highlightedSlotStyle">I have text.</span>
-                </template>
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-             <div :style="docCellStyle">
-              <CpAccordion title="DIDA TRAVEL" :default-open-state="false" icon-position="trailing">
-                <template #trailing-slot>
-                  <span :style="highlightedSlotStyle">I have text.</span>
-                </template>
-                <div :style="sampleContentStyle" />
-              </CpAccordion>
-            </div>
-          </div>
-        </section>
-      </div>
-    `,
-  }),
-  parameters: {
-    controls: { disable: true },
-    docs: {
-      source: {
-        code: null,
-      },
-    },
+/**
+ * The accordion renders closed on first mount.
+ */
+export const ClosedByDefault: Story = {
+  args: {
+    ...Default.args,
+    defaultOpenState: false,
+    title: 'Closed on mount',
   },
+  render: defaultRender,
 }
 
-export const Default: Story = {
+/* -------------------------------------------------------------------------- */
+/* Actions & quick options                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Pass `actions` (a `MenuItem[]`) to reveal a contextual menu on hover/focus.
+ * Only available in `leading` icon mode.
+ */
+export const WithActions: Story = {
+  args: {
+    ...Default.args,
+    title: 'Accordion with a contextual menu',
+    quickOptionsLimit: 0,
+    actions: defaultStoryActions,
+  },
+  render: defaultRender,
+}
+
+/**
+ * Use `quickOptionsLimit` to display N action triggers inline at the start of
+ * the header in addition to the overflow menu.
+ */
+export const WithQuickOptions: Story = {
+  args: {
+    ...Default.args,
+    title: 'With quick options',
+    quickOptionsLimit: 2,
+    actions: defaultStoryActions,
+  },
+  render: defaultRender,
+}
+
+/**
+ * Same as `WithActions`, but the inline action trigger (the `…` button) is
+ * hidden. Useful when actions are surfaced elsewhere.
+ */
+export const HideActionTrigger: Story = {
   args: {
-    title: 'I have title.',
+    ...Default.args,
+    title: 'Action trigger hidden',
+    hideActionTrigger: true,
+    actions: defaultStoryActions,
+  },
+  render: defaultRender,
+}
+
+/**
+ * An accordion without any inline actions.
+ */
+export const WithoutActions: Story = {
+  args: {
+    title: 'Plain accordion',
     defaultOpenState: true,
     iconPosition: 'leading',
-    quickOptionsLimit: 2,
+    quickOptionsLimit: 0,
     hideActionTrigger: false,
-    actions: defaultStoryActions,
+    actions: [],
   },
   render: defaultRender,
 }
+
+/* -------------------------------------------------------------------------- */
+/* Slots                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The `leading-slot` lets you append rich content next to the title
+ * (e.g. meta, badges).
+ */
+export const WithLeadingSlot: Story = {
+  args: {
+    ...Default.args,
+    title: 'Accordion with leading slot',
+    actions: [],
+    quickOptionsLimit: 0,
+  },
+  render: (args: Args) => ({
+    components: { CpAccordion },
+    setup() {
+      return { args, sampleContentStyle, wrapperStyle }
+    },
+    template: `
+      <div :style="wrapperStyle">
+        <CpAccordion v-bind="args">
+          <template #leading-slot>
+            <span style="font-size: 12px; color: #6b7280; margin-top: 4px;">Additional context below the title</span>
+          </template>
+          <div :style="sampleContentStyle" />
+        </CpAccordion>
+      </div>
+    `,
+  }),
+}
+
+/**
+ * The `trailing-slot` is shown on the right of the header. It supports any
+ * custom content (e.g. timestamps, counters).
+ */
+export const WithTrailingSlot: Story = {
+  args: {
+    ...Default.args,
+    title: 'Accordion with trailing slot',
+    actions: [],
+    quickOptionsLimit: 0,
+  },
+  render: (args: Args) => ({
+    components: { CpAccordion },
+    setup() {
+      return { args, sampleContentStyle, wrapperStyle }
+    },
+    template: `
+      <div :style="wrapperStyle">
+        <CpAccordion v-bind="args">
+          <template #trailing-slot>
+            <span style="font-size: 12px; color: #6b7280;">Last edit · 2 min ago</span>
+          </template>
+          <div :style="sampleContentStyle" />
+        </CpAccordion>
+      </div>
+    `,
+  }),
+}

package/src/stories/CpAccordionGroup.stories.ts

@@ -6,18 +6,12 @@ import type { MenuItem } from 'primevue/menuitem'
 import CpAccordion from '@/components/CpAccordion.vue'
 import CpAccordionGroup from '@/components/CpAccordionGroup.vue'
 
-import {
-  docCellStyle,
-  docLabelStyle,
-  docPageStyle,
-  docRowColumnStyle,
-  docSectionStyle,
-  docTitleStyle,
-} from '@/stories/documentationStyles'
-
 const sampleContentStyle =
   'padding: 16px; font-size: 13px; color: #374151; background: repeating-linear-gradient(45deg, #fff9c4, #fff9c4 4px, #fffde7 4px, #fffde7 8px);'
 
+const wrapperStyle =
+  'box-sizing: border-box; width: 100%; max-width: 1200px; margin: 0 auto; padding: 24px; width: 500px;'
+
 type CpAccordionGroupStoryArgs = {
   itemActions: MenuItem[]
   itemDefaultOpenState: boolean
@@ -43,7 +37,7 @@ const defaultItemActions: MenuItem[] = [
 ]
 
 const meta = {
-  title: 'Visual/CpAccordionGroup',
+  title: 'Molecules/CpAccordionGroup',
   component: CpAccordionGroup,
   argTypes: {
     variant: {
@@ -110,10 +104,10 @@ const defaultRender = (args: Args) => ({
       }
     })
 
-    return { accordionBind, args, sampleContentStyle }
+    return { accordionBind, args, sampleContentStyle, wrapperStyle }
   },
   template: `
-    <div style="box-sizing: border-box; width: 100%; max-width: 1200px; margin: 0 auto; padding: 24px; width: 500px;">
+    <div :style="wrapperStyle">
       <CpAccordionGroup :variant="args.variant">
         <CpAccordion
           v-for="i in 3"
@@ -128,91 +122,13 @@ const defaultRender = (args: Args) => ({
   `,
 })
 
-export const Documentation: Story = {
-  args: {
-    variant: 'default',
-  },
-  render: () => ({
-    components: { CpAccordion, CpAccordionGroup },
-    setup: () => ({
-      docPageStyle,
-      docSectionStyle,
-      docTitleStyle,
-      docRowColumnStyle,
-      docCellStyle,
-      docLabelStyle,
-      sampleContentStyle,
-    }),
-    template: `
-      <div :style="docPageStyle">
-        <h1 style="margin: 0 0 24px 0; font-size: 28px; font-weight: 700; color: #111827;">CpAccordionGroup</h1>
-
-        <section :style="docSectionStyle">
-          <h2 :style="docTitleStyle">Style</h2>
-          <div :style="docRowColumnStyle">
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">Minimal</span>
-              <CpAccordionGroup variant="minimal">
-                <CpAccordion key="doc-default-1" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-                <CpAccordion key="doc-default-2" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-                <CpAccordion key="doc-default-3" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-              </CpAccordionGroup>
-            </div>
-
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">Default</span>
-              <CpAccordionGroup variant="default">
-                <CpAccordion key="doc-bb-1" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-                <CpAccordion key="doc-bb-2" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-                <CpAccordion key="doc-bb-3" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-              </CpAccordionGroup>
-            </div>
-
-            <div :style="docCellStyle">
-              <span :style="docLabelStyle">Primary</span>
-              <CpAccordionGroup variant="primary">
-                <CpAccordion key="doc-gb-1" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-                <CpAccordion key="doc-gb-2" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-                <CpAccordion key="doc-gb-3" title="DIDA TRAVEL" icon-position="leading">
-                   <div :style="sampleContentStyle" />
-                 </CpAccordion>
-              </CpAccordionGroup>
-            </div>
-          </div>
-        </section>
-      </div>
-    `,
-  }),
-  parameters: {
-    controls: { disable: true },
-    docs: {
-      source: {
-        code: null,
-      },
-    },
-  },
-}
-
+/**
+ * Default accordion group rendered with the `default` variant.
+ */
 export const Default: Story = {
   args: {
     variant: 'default',
-    itemTitle: 'DIDA TRAVEL',
+    itemTitle: 'Accordion',
     itemDefaultOpenState: false,
     itemIconPosition: 'leading',
     itemQuickOptionsLimit: 2,
@@ -221,3 +137,43 @@ export const Default: Story = {
   },
   render: defaultRender,
 }
+
+/* -------------------------------------------------------------------------- */
+/* Variants                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Minimal variant: no container border, no separators between items. Use when
+ * the grouping is implicit in the surrounding layout.
+ */
+export const Minimal: Story = {
+  args: {
+    ...Default.args,
+    variant: 'minimal',
+  },
+  render: defaultRender,
+}
+
+/**
+ * Default variant: thin separator lines between items, no outer border.
+ * This is the most common variant.
+ */
+export const DefaultVariant: Story = {
+  args: {
+    ...Default.args,
+    variant: 'default',
+  },
+  render: defaultRender,
+}
+
+/**
+ * Primary variant: the group is wrapped in a rounded card with an outer border
+ * and separators between items.
+ */
+export const Primary: Story = {
+  args: {
+    ...Default.args,
+    variant: 'primary',
+  },
+  render: defaultRender,
+}