@citizenplane/pimp 16.0.3 → 16.1.0

package/src/stories/Shadows.stories.ts

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import type { Token } from '@/stories/tokenUtils'
+import {
+  copyableClass,
+  copyableCopiedClass,
+  readTokens,
+  sortTokensBySize,
+  tokenTableClass,
+  useCopier,
+} from '@/stories/tokenUtils'
+
+const meta: Meta = {
+  title: 'Foundations/Shadows',
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    controls: { disable: true },
+    docs: { source: { code: null } },
+  },
+}
+
+export default meta
+
+type Story = StoryObj
+
+const previewStyle = (tokenName: string): string =>
+  `width: 160px; height: 80px; background: #ffffff; border-radius: 8px; box-shadow: var(${tokenName});`
+
+const makeSectionStory = (loader: () => Token[]): Story => ({
+  render: () => ({
+    setup() {
+      const { copiedKey, copy } = useCopier()
+      return {
+        tokens: loader(),
+        copiedKey,
+        copy,
+        tableClass: tokenTableClass,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+        preview: (tokenName: string) => previewStyle(tokenName),
+      }
+    },
+    template: `
+      <table v-if="tokens.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 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>{{ token.value }}</td>
+            <td class="cp-token-table__preview">
+              <div :style="preview(token.name)"></div>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <div v-else style="padding: 12px 0; color: #9ca3af; font-size: 12px;">No tokens</div>
+    `,
+  }),
+})
+
+/**
+ * Drop shadows ordered from the most to the least prominent. Use them to
+ * lift cards, popovers and menus off the surface.
+ */
+export const DropShadows: Story = makeSectionStory(() =>
+  sortTokensBySize(readTokens(['--cp-shadows-'], [/-inset$/, /^--cp-shadows-overlay$/, /^--cp-shadows-side-panel$/])),
+)
+
+/**
+ * Inset shadows sit inside the element. Useful for pressed states and
+ * recessed surfaces like form fields.
+ */
+export const InsetShadows: Story = makeSectionStory(() => sortTokensBySize(readTokens([/^--cp-shadows-.*-inset$/])))
+
+/**
+ * Dedicated shadow for the side panel container.
+ */
+export const SidePanel: Story = makeSectionStory(() => readTokens(['--cp-shadows-side-panel']))
+
+/**
+ * Multi-layered shadow used for modals and full-screen overlays.
+ */
+export const Overlay: Story = makeSectionStory(() => readTokens(['--cp-shadows-overlay']))

package/src/stories/Typography.mdx

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

package/src/stories/Typography.stories.ts

@@ -0,0 +1,181 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import type { ProbeProperty, Token } from '@/stories/tokenUtils'
+import {
+  copyableClass,
+  copyableCopiedClass,
+  getTokenPixels,
+  readTokens,
+  sortTokensBySize,
+  splitRemPx,
+  tokenTableClass,
+  useCopier,
+} from '@/stories/tokenUtils'
+
+const meta: Meta = {
+  title: 'Foundations/Typography',
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    controls: { disable: true },
+    docs: { source: { code: null } },
+  },
+}
+
+export default meta
+
+type Story = StoryObj
+
+type PreviewKind = 'letter-spacing' | 'line-height' | 'text-size'
+
+const previewStyle = (kind: PreviewKind, tokenName: string): string => {
+  const ref = `var(${tokenName})`
+  switch (kind) {
+    case 'text-size':
+      return `font-size: ${ref}; line-height: 1.1; color: #36384d;`
+    case 'line-height':
+      return `font-size: 14px; line-height: ${ref}; color: #36384d; max-width: 280px; width:280px; display:block; white-space: initial;`
+    case 'letter-spacing':
+      return `font-size: 14px; letter-spacing: ${ref}; color: #36384d;`
+  }
+}
+
+const sampleForKind = (kind: PreviewKind): string => {
+  switch (kind) {
+    case 'text-size':
+      return 'The quick brown fox'
+    case 'line-height':
+      return 'Cras mattis consectetur purus sit amet fermentum. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.'
+    case 'letter-spacing':
+      return 'AVERAGE spacing sample'
+  }
+}
+
+/**
+ * Raw text sizes, sorted from the biggest to the smallest. Prefer the
+ * semantic `--cp-text-*-size` tokens (Text scale) in application code.
+ */
+export const TextSize: Story = {
+  render: () => ({
+    setup() {
+      const tokens = sortTokensBySize(readTokens(['--cp-text-size-']))
+      const { copiedKey, copy } = useCopier()
+      return {
+        tokens,
+        copiedKey,
+        copy,
+        tableClass: tokenTableClass,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+        preview: (tokenName: string) => previewStyle('text-size', tokenName),
+        sample: sampleForKind('text-size'),
+        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">
+              <span :style="preview(token.name)">{{ sample }}</span>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <div v-else style="padding: 12px 0; color: #9ca3af; font-size: 12px;">No tokens</div>
+    `,
+  }),
+}
+
+type ValueSectionArgs = { kind: 'letter-spacing' | 'line-height'; loader: () => Token[] }
+
+const makeValueStory = ({ kind, loader }: ValueSectionArgs): Story => ({
+  render: () => ({
+    setup() {
+      const { copiedKey, copy } = useCopier()
+      const probeProperty: ProbeProperty = kind
+      return {
+        kind,
+        tokens: loader(),
+        copiedKey,
+        copy,
+        tableClass: tokenTableClass,
+        copyClass: copyableClass,
+        copiedClass: copyableCopiedClass,
+        preview: (k: PreviewKind, tokenName: string) => previewStyle(k, tokenName),
+        sample: (k: PreviewKind) => sampleForKind(k),
+        px: (tokenName: string) => getTokenPixels(tokenName, probeProperty) ?? '—',
+      }
+    },
+    template: `
+      <table v-if="tokens.length > 0" :class="tableClass">
+        <thead>
+          <tr>
+            <th scope="col">Token</th>
+            <th scope="col">Value</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>{{ token.value }}</td>
+            <td>{{ px(token.name) }}</td>
+            <td class="cp-token-table__preview">
+              <span :style="preview(kind, token.name)">{{ sample(kind) }}</span>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <div v-else style="padding: 12px 0; color: #9ca3af; font-size: 12px;">No tokens</div>
+    `,
+  }),
+})
+
+/**
+ * Raw line-heights. The gradient line marks the baseline of each sample.
+ */
+export const LineHeight: Story = makeValueStory({
+  kind: 'line-height',
+  loader: () => sortTokensBySize(readTokens(['--cp-line-height-'])),
+})
+
+/**
+ * Letter-spacing (tracking) scale.
+ */
+export const LetterSpacing: Story = makeValueStory({
+  kind: 'letter-spacing',
+  loader: () => sortTokensBySize(readTokens(['--cp-letter-spacing-'])),
+})

package/src/stories/documentationStyles.ts

@@ -1,16 +1,8 @@
-export const docPageStyle =
-  'padding: 24px; background: #f3f4f6; min-height: 100vh; width: 70vw; box-sizing: border-box;'
-
-export const docSectionStyle =
-  'background: #fff; border-radius: 8px; padding: 24px; margin-bottom: 28px; box-shadow: 0 1px 3px rgba(0,0,0,0.08);'
-
-export const docTitleStyle =
-  'margin: 0 0 16px 0; font-size: 12px; font-weight: 600; color: #6b7280; text-transform: uppercase; letter-spacing: 0.05em;'
-
 export const docRowWrapStyle = 'display: flex; flex-wrap: wrap; gap: 24px 32px; align-items: flex-end;'
 
 export const docRowColumnStyle = 'display: flex; flex-direction: column; gap: 24px;'
 
-export const docCellStyle = 'display: flex; flex-direction: column; gap: 10px; align-items: flex-start;'
+export const docCellStyle =
+  'display: flex; flex-direction: column; gap: 10px; align-items: flex-start; justify-content: space-between; align-self: stretch;'
 
 export const docLabelStyle = 'font-size: 12px; color: #6b7280;'

package/src/stories/tokenUtils.ts

@@ -0,0 +1,259 @@
+import { ref } from 'vue'
+
+export type Token = { name: string; value: string }
+
+export async function copyText(text: string): Promise<boolean> {
+  if (typeof navigator === 'undefined' || typeof window === 'undefined') return false
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text)
+      return true
+    }
+  } catch {
+    // fall through to fallback
+  }
+  try {
+    const textarea = document.createElement('textarea')
+    textarea.value = text
+    textarea.setAttribute('readonly', '')
+    textarea.style.position = 'fixed'
+    textarea.style.opacity = '0'
+    document.body.appendChild(textarea)
+    textarea.select()
+    const ok = document.execCommand('copy')
+    document.body.removeChild(textarea)
+    return ok
+  } catch {
+    return false
+  }
+}
+
+export function useCopier() {
+  const copiedKey = ref<null | string>(null)
+  let timer: null | ReturnType<typeof setTimeout> = null
+
+  const copy = async (key: string, text: string = key) => {
+    const ok = await copyText(text)
+    if (!ok) return
+    if (timer) clearTimeout(timer)
+    copiedKey.value = key
+    timer = setTimeout(() => {
+      copiedKey.value = null
+    }, 1200)
+  }
+
+  return { copiedKey, copy }
+}
+
+type MatcherFn = (name: string) => boolean
+type Matcher = string | RegExp | MatcherFn
+
+const toMatcherFn = (m: Matcher): MatcherFn => {
+  if (typeof m === 'function') return m
+  if (m instanceof RegExp) return (name: string) => m.test(name)
+  return (name: string) => name.startsWith(m)
+}
+
+export function readTokens(include: Matcher[], exclude: Matcher[] = []): Token[] {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return []
+  const styles = getComputedStyle(document.documentElement)
+  const includeFns = include.map(toMatcherFn)
+  const excludeFns = exclude.map(toMatcherFn)
+  const out: Token[] = []
+  for (let i = 0; i < styles.length; i++) {
+    const name = styles[i]
+    if (!name.startsWith('--cp-')) continue
+    if (!includeFns.some((fn) => fn(name))) continue
+    if (excludeFns.some((fn) => fn(name))) continue
+    out.push({ name, value: styles.getPropertyValue(name).trim() })
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+export type ProbeProperty = 'letter-spacing' | 'line-height' | 'width'
+
+/**
+ * Apply a token as the given CSS property on a hidden probe element and read
+ * back the computed value. Defaults to `width`, which is the right choice for
+ * length tokens (rem/px). Use `line-height` or `letter-spacing` to resolve
+ * values that depend on the current font size.
+ */
+export function getTokenPixels(tokenName: string, property: ProbeProperty = 'width'): null | string {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return null
+  const probe = document.createElement('div')
+  probe.style.position = 'absolute'
+  probe.style.visibility = 'hidden'
+  probe.style.pointerEvents = 'none'
+  probe.style.fontSize = '16px'
+  if (property === 'width') {
+    probe.style.width = `var(${tokenName})`
+  } else if (property === 'line-height') {
+    probe.style.lineHeight = `var(${tokenName})`
+    probe.textContent = 'M'
+  } else {
+    probe.style.letterSpacing = `var(${tokenName})`
+  }
+  document.body.appendChild(probe)
+  const style = getComputedStyle(probe)
+  let computed: string
+  if (property === 'width') computed = style.width
+  else if (property === 'line-height') computed = style.lineHeight
+  else computed = style.letterSpacing
+  document.body.removeChild(probe)
+  if (!computed || computed === 'auto' || computed === 'normal') return null
+  return computed
+}
+
+const tshirtRank: Record<string, number> = {
+  none: -1,
+  '3xs': 0,
+  '2xs': 1,
+  xs: 2,
+  sm: 3,
+  'sm-md': 3.5,
+  md: 4,
+  'md-lg': 4.5,
+  lg: 5,
+  xl: 6,
+  '2xl': 7,
+  '3xl': 8,
+  '4xl': 9,
+  '5xl': 10,
+  '6xl': 11,
+  '7xl': 12,
+  '8xl': 13,
+  '9xl': 14,
+  full: 9999,
+}
+
+function extractSizeRank(name: string): null | number {
+  const parts = name.replace(/^--cp-/, '').split('-')
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const one = parts[i]
+    const two = i > 0 ? `${parts[i - 1]}-${one}` : null
+    if (two && two in tshirtRank) return tshirtRank[two]
+    if (one in tshirtRank) return tshirtRank[one]
+  }
+  return null
+}
+
+function parsePxNumber(px: null | string): null | number {
+  if (!px) return null
+  const m = px.match(/^(-?\d+(?:\.\d+)?)px$/)
+  return m ? parseFloat(m[1]) : null
+}
+
+export function sortTokensBySize(tokens: Token[], direction: 'asc' | 'desc' = 'desc'): Token[] {
+  const factor = direction === 'desc' ? -1 : 1
+  return [...tokens].sort((a, b) => {
+    const rankA = extractSizeRank(a.name)
+    const rankB = extractSizeRank(b.name)
+    if (rankA !== null && rankB !== null && rankA !== rankB) {
+      return factor * (rankA - rankB)
+    }
+    if (rankA !== null && rankB === null) return -1
+    if (rankA === null && rankB !== null) return 1
+    const pxA = parsePxNumber(getTokenPixels(a.name))
+    const pxB = parsePxNumber(getTokenPixels(b.name))
+    if (pxA !== null && pxB !== null && pxA !== pxB) {
+      return factor * (pxA - pxB)
+    }
+    return a.name.localeCompare(b.name)
+  })
+}
+
+export const copyableClass = 'cp-copyable'
+
+export const copyableCopiedClass = 'cp-copyable--copied'
+
+export const tokenTableClass = 'cp-token-table'
+
+/**
+ * Split a token value into a rem part and a px part. When the raw value is
+ * expressed in rem, both columns are filled (value in rem + computed px).
+ * Otherwise the value goes into whichever column matches its unit.
+ */
+export function splitRemPx(token: Token): { px: string; rem: string } {
+  const value = token.value.trim()
+  const resolvedPx = getTokenPixels(token.name) ?? ''
+  const dash = '—'
+  const isRem = /^-?\d*\.?\d+rem$/.test(value)
+  if (isRem) {
+    return { rem: value, px: resolvedPx || dash }
+  }
+  const isPx = /^-?\d*\.?\d+px$/.test(value)
+  if (isPx) {
+    return { rem: dash, px: value }
+  }
+  return { rem: dash, px: resolvedPx || dash }
+}
+
+function ensureFoundationStyles(): void {
+  if (typeof document === 'undefined') return
+  const id = 'cp-foundation-styles'
+  if (document.getElementById(id)) return
+  const style = document.createElement('style')
+  style.id = id
+  style.textContent = `
+    .${copyableClass} {
+      cursor: pointer;
+      border-radius: 4px;
+      padding: 2px 6px;
+      margin: -2px -6px;
+      transition: background-color 0.15s ease, color 0.15s ease;
+      position: relative;
+    }
+    .${copyableClass}:hover {
+      background-color: #eef0ff;
+    }
+    .${copyableClass}:focus-visible {
+      outline: 2px solid #6366f1;
+      outline-offset: 2px;
+    }
+    .${copyableClass}.${copyableCopiedClass} {
+      background-color: #dcfce7;
+      color: #065f46;
+    }
+    .${tokenTableClass} {
+      width: 100%;
+      border-collapse: collapse;
+      text-align: left;
+    }
+    .${tokenTableClass} thead th {
+      font-family: ui-sans-serif, system-ui, sans-serif;
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      color: #6b7280;
+      padding: 10px 12px;
+      border-bottom: 1px solid #e5e7eb;
+      background: #f9fafb;
+    }
+    .${tokenTableClass} tbody td {
+      padding: 10px 12px;
+      border-bottom: 1px solid #f1f2f6;
+      vertical-align: middle;
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 12px;
+      color: #6b7280;
+      word-break: break-all;
+      white-space: nowrap;
+    }
+    .${tokenTableClass} tbody td:first-child {
+      color: #111;
+    }
+    .${tokenTableClass} tbody tr:last-child td {
+      border-bottom: none;
+    }
+    .${tokenTableClass} tbody td.cp-token-table__preview {
+      width: 1%;
+      white-space: nowrap;
+    }
+  `
+  document.head.appendChild(style)
+}
+
+if (typeof document !== 'undefined') {
+  ensureFoundationStyles()
+}