@citizenplane/pimp 16.0.3 → 16.1.0

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'
 
 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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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: {

package/src/stories/CpTransitionTabContent.stories.ts

@@ -36,6 +36,10 @@ const layoutStyle = 'display: flex; flex-direction: column; gap: 20px; min-width
 const panelStyle =
   'min-height: 120px; padding: 20px; border-radius: 12px; background: #f3f4f6; font-size: 15px; line-height: 1.5;'
 
+/**
+ * Directional slide between tab panels. `direction` is driven by the
+ * current vs. previous tab index to slide forward or backward.
+ */
 export const Default: Story = {
   args: {
     duration: 300,

package/src/stories/Dimensions.mdx

@@ -0,0 +1,9 @@
+import { Meta, Title, Description, Stories } from '@storybook/addon-docs/blocks'
+
+import * as DimensionsStories from './Dimensions.stories'
+
+<Meta of={DimensionsStories} />
+
+<Title />
+<Description />
+<Stories />

package/src/stories/Dimensions.stories.ts

@@ -0,0 +1,119 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import type { Token } from '@/stories/tokenUtils'
+import {
+  copyableClass,
+  copyableCopiedClass,
+  readTokens,
+  sortTokensBySize,
+  splitRemPx,
+  tokenTableClass,
+  useCopier,
+} from '@/stories/tokenUtils'
+
+const meta: Meta = {
+  title: 'Foundations/Dimensions',
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    controls: { disable: true },
+    docs: { source: { code: null } },
+  },
+}
+
+export default meta
+
+type Story = StoryObj
+
+type DimensionKind = 'bar' | 'none' | 'radius' | 'square'
+
+const previewStyle = (kind: DimensionKind, tokenName: string): string => {
+  const ref = `var(${tokenName})`
+  switch (kind) {
+    case 'bar':
+      return `height: 12px; width: ${ref}; max-width: 100%; background: var(--cp-background-accent-solid, #603dfd); border-radius: 4px;`
+    case 'radius':
+      return `width: 56px; height: 56px; background: var(--cp-background-accent-primary, #eaecff); border: 1px solid var(--cp-border-accent-primary, #ccd0ff); border-radius: ${ref};`
+    case 'square':
+      return `width: ${ref}; height: ${ref}; background: var(--cp-background-accent-solid, #603dfd); border-radius: 2px;`
+    case 'none':
+      return ''
+  }
+}
+
+type SectionArgs = { kind: DimensionKind; prefix: string }
+
+const makeSectionStory = (section: SectionArgs): Story => ({
+  render: () => ({
+    setup() {
+      const tokens = sortTokensBySize(readTokens([section.prefix]))
+      const { copiedKey, copy } = useCopier()
+      return {
+        kind: section.kind,
+        tokens,
+        copiedKey,
+        copy,
+        tableClass: tokenTableClass,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+        preview: (kind: DimensionKind, tokenName: string) => previewStyle(kind, tokenName),
+        split: (token: Token) => splitRemPx(token),
+      }
+    },
+    template: `
+      <table v-if="tokens.length > 0" :class="tableClass">
+        <thead>
+          <tr>
+            <th scope="col">Token</th>
+            <th scope="col">rem</th>
+            <th scope="col">px</th>
+            <th scope="col">Preview</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="token in tokens" :key="token.name">
+            <td>
+              <span
+                :class="[copyClass, copiedKey === token.name ? copiedClass : '']"
+                role="button"
+                tabindex="0"
+                :title="'Click to copy ' + token.name"
+                @click="copy(token.name)"
+                @keydown.enter.prevent="copy(token.name)"
+                @keydown.space.prevent="copy(token.name)"
+              >{{ copiedKey === token.name ? 'Copied!' : token.name }}</span>
+            </td>
+            <td>{{ split(token).rem }}</td>
+            <td>{{ split(token).px }}</td>
+            <td class="cp-token-table__preview">
+              <div :style="preview(kind, token.name)"></div>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <div v-else style="padding: 12px 0; color: #9ca3af; font-size: 12px;">No tokens</div>
+    `,
+  }),
+})
+
+/**
+ * Responsive breakpoints. These values match the `min-width` media queries
+ * the design system uses to adapt layouts.
+ */
+export const Breakpoint: Story = makeSectionStory({ prefix: '--cp-breakpoint-', kind: 'none' })
+
+/**
+ * Border radius scale, from sharp corners to fully rounded pill shapes.
+ */
+export const Radius: Story = makeSectionStory({ prefix: '--cp-radius-', kind: 'radius' })
+
+/**
+ * Spacing scale used for padding, margin and gap. Rendered as horizontal
+ * bars to compare relative widths.
+ */
+export const Spacing: Story = makeSectionStory({ prefix: '--cp-spacing-', kind: 'bar' })
+
+/**
+ * Width tokens used for icons, avatars and small fixed-size surfaces.
+ */
+export const Width: Story = makeSectionStory({ prefix: '--cp-width-', kind: 'square' })

package/src/stories/Easings.mdx

@@ -0,0 +1,9 @@
+import { Meta, Title, Description, Stories } from '@storybook/addon-docs/blocks'
+
+import * as EasingsStories from './Easings.stories'
+
+<Meta of={EasingsStories} />
+
+<Title />
+<Description />
+<Stories />

package/src/stories/Easings.stories.ts

@@ -0,0 +1,101 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { copyableClass, copyableCopiedClass, readTokens, tokenTableClass, useCopier } from '@/stories/tokenUtils'
+
+const meta: Meta = {
+  title: 'Foundations/Easings',
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    controls: { disable: true },
+    docs: { source: { code: null } },
+  },
+}
+
+export default meta
+
+type Story = StoryObj
+
+/**
+ * Cubic-bezier curves used for the design-system transitions. Hover (or
+ * focus) any track to play the animation and compare curves side by side.
+ */
+export const Curves: Story = {
+  render: () => ({
+    setup() {
+      const easings = readTokens(['--cp-easing-'])
+      const { copiedKey, copy } = useCopier()
+      return {
+        easings,
+        copiedKey,
+        copy,
+        tableClass: tokenTableClass,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+        ballStyle: (tokenName: string) => `transition-timing-function: var(${tokenName});`,
+      }
+    },
+    template: `
+      <div>
+        <style>
+          .cp-easing-track {
+            position: relative;
+            width: 220px;
+            height: 36px;
+            background: #f3f4f6;
+            border-radius: 18px;
+            overflow: hidden;
+          }
+          .cp-easing-ball {
+            position: absolute;
+            top: 4px;
+            left: 4px;
+            width: 28px;
+            height: 28px;
+            border-radius: 50%;
+            background: var(--cp-background-accent-solid, #603dfd);
+            transition-property: transform;
+            transition-duration: 900ms;
+            transform: translateX(0);
+          }
+          .cp-easing-track:hover .cp-easing-ball,
+          .cp-easing-track:focus-within .cp-easing-ball {
+            transform: translateX(184px);
+          }
+        </style>
+        <p style="margin: 0 0 12px 0; color: #6b7280; font-size: 12px;">Hover a track to play the transition.</p>
+        <table v-if="easings.length > 0" :class="tableClass">
+          <thead>
+            <tr>
+              <th scope="col">Token</th>
+              <th scope="col">Value</th>
+              <th scope="col">Preview</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="token in easings" :key="token.name">
+              <td>
+                <span
+                  :class="[copyClass, copiedKey === token.name ? copiedClass : '']"
+                  role="button"
+                  tabindex="0"
+                  :title="'Click to copy ' + token.name"
+                  @click="copy(token.name)"
+                  @keydown.enter.prevent="copy(token.name)"
+                  @keydown.space.prevent="copy(token.name)"
+                >{{ copiedKey === token.name ? 'Copied!' : token.name }}</span>
+              </td>
+              <td>{{ token.value }}</td>
+              <td class="cp-token-table__preview">
+                <div class="cp-easing-track" tabindex="0">
+                  <div class="cp-easing-ball" :style="ballStyle(token.name)"></div>
+                </div>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+        <div v-else style="padding: 12px 0; color: #9ca3af; font-size: 12px;">No tokens</div>
+      </div>
+    `,
+  }),
+}

package/src/stories/FocusRings.mdx

@@ -0,0 +1,9 @@
+import { Meta, Title, Description, Stories } from '@storybook/addon-docs/blocks'
+
+import * as FocusRingsStories from './FocusRings.stories'
+
+<Meta of={FocusRingsStories} />
+
+<Title />
+<Description />
+<Stories />

package/src/stories/FocusRings.stories.ts

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { copyableClass, copyableCopiedClass, readTokens, tokenTableClass, useCopier } from '@/stories/tokenUtils'
+
+const meta: Meta = {
+  title: 'Foundations/Focus Rings',
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    controls: { disable: true },
+    docs: { source: { code: null } },
+  },
+}
+
+export default meta
+
+type Story = StoryObj
+
+const previewStyle = (tokenName: string): string =>
+  `display: inline-flex; align-items: center; justify-content: center; height: 40px; padding: 0 18px; border-radius: 8px; background: #ffffff; border: 1px solid #e9eaf6; color: #36384d; font-size: 14px; box-shadow: var(${tokenName});`
+
+/**
+ * Composite focus-ring tokens (one token per color role). Each token is a
+ * multi-layered `box-shadow` that produces a consistent, accessible focus
+ * outline when applied to an element.
+ */
+export const Composite: Story = {
+  render: () => ({
+    setup() {
+      const composites = readTokens([/^--cp-shadow-focus-ring-[^-]+$/])
+      const { copiedKey, copy } = useCopier()
+      return {
+        composites,
+        copiedKey,
+        copy,
+        tableClass: tokenTableClass,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+        preview: (tokenName: string) => previewStyle(tokenName),
+      }
+    },
+    template: `
+      <table v-if="composites.length > 0" :class="tableClass">
+        <thead>
+          <tr>
+            <th scope="col">Token</th>
+            <th scope="col">Value</th>
+            <th scope="col">Preview</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="token in composites" :key="token.name">
+            <td>
+              <span
+                :class="[copyClass, copiedKey === token.name ? copiedClass : '']"
+                role="button"
+                tabindex="0"
+                :title="'Click to copy ' + token.name"
+                @click="copy(token.name)"
+                @keydown.enter.prevent="copy(token.name)"
+                @keydown.space.prevent="copy(token.name)"
+              >{{ copiedKey === token.name ? 'Copied!' : token.name }}</span>
+            </td>
+            <td>{{ token.value }}</td>
+            <td class="cp-token-table__preview">
+              <span :style="preview(token.name)">Focused</span>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <div v-else style="padding: 12px 0; color: #9ca3af; font-size: 12px;">No tokens</div>
+    `,
+  }),
+}

package/src/stories/Shadows.mdx

@@ -0,0 +1,9 @@
+import { Meta, Title, Description, Stories } from '@storybook/addon-docs/blocks'
+
+import * as ShadowsStories from './Shadows.stories'
+
+<Meta of={ShadowsStories} />
+
+<Title />
+<Description />
+<Stories />