@antfu/design 0.1.0

package/utils/keybinding.ts

@@ -0,0 +1,199 @@
+/**
+ * Keyboard chord parsing + platform-aware display, adapted from ghfs's
+ * `parseKey`. Pure (the one environment touch, `isMac`, degrades gracefully on
+ * the server). Kept for the `Kbd` component; the command-registry pairing is
+ * deferred with the command palette.
+ */
+
+/**
+ * Whether the current environment is an Apple platform (macOS/iOS).
+ *
+ * Detected from `navigator.platform`/`userAgent`; `false` on the server or any
+ * non-Apple platform. Drives the `mod` alias (→ `meta` on Apple, `ctrl`
+ * elsewhere) and glyph vs. label display.
+ *
+ * @example
+ * isMac // → true on macOS, false on Windows/Linux/server
+ */
+export const isMac: boolean = typeof navigator !== 'undefined'
+  && /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent)
+
+export interface ParsedChord {
+  /** Modifiers, alphabetically ordered: `alt` | `ctrl` | `meta` | `shift`. */
+  modifiers: string[]
+  /** The final non-modifier key, e.g. `k`, `Enter`, `ArrowUp`, `/`. */
+  key: string
+}
+
+const MOD_ALIASES: Record<string, string> = {
+  mod: isMac ? 'meta' : 'ctrl',
+  cmd: 'meta',
+  command: 'meta',
+  super: 'meta',
+  win: 'meta',
+  meta: 'meta',
+  ctrl: 'ctrl',
+  control: 'ctrl',
+  alt: 'alt',
+  option: 'alt',
+  opt: 'alt',
+  shift: 'shift',
+}
+
+const KEY_ALIASES: Record<string, string> = {
+  esc: 'Escape',
+  escape: 'Escape',
+  enter: 'Enter',
+  return: 'Enter',
+  space: ' ',
+  tab: 'Tab',
+  up: 'ArrowUp',
+  down: 'ArrowDown',
+  left: 'ArrowLeft',
+  right: 'ArrowRight',
+}
+
+const MOD_ORDER = ['ctrl', 'alt', 'shift', 'meta']
+
+/**
+ * Parse a single chord like `mod+shift+k`.
+ *
+ * Splits on `+`, resolving modifier aliases (`mod`/`cmd`/`ctrl`/`alt`/`shift`,
+ * etc.) and key aliases (`esc`→`Escape`, `up`→`ArrowUp`, …). Modifiers are
+ * returned in canonical `ctrl, alt, shift, meta` order; the last non-modifier
+ * token becomes `key`. The platform-sensitive `mod` resolves to `meta` on Apple
+ * and `ctrl` elsewhere (see {@link isMac}).
+ *
+ * @param input - The chord string, e.g. `'mod+shift+k'`.
+ * @returns A {@link ParsedChord} with ordered `modifiers` and the final `key`.
+ *
+ * @example
+ * const chord = parseChord('mod+shift+k')
+ * chord.key // → 'k'
+ * chord.modifiers // → ['shift', 'meta'] on macOS, ['ctrl', 'shift'] elsewhere
+ */
+export function parseChord(input: string): ParsedChord {
+  const tokens = input.trim().split('+').map(t => t.trim()).filter(Boolean)
+  const modifiers = new Set<string>()
+  let key = ''
+  for (const token of tokens) {
+    const lower = token.toLowerCase()
+    if (lower in MOD_ALIASES)
+      modifiers.add(MOD_ALIASES[lower])
+    else
+      key = KEY_ALIASES[lower] ?? (token.length === 1 ? token.toLowerCase() : token)
+  }
+  return {
+    modifiers: MOD_ORDER.filter(m => modifiers.has(m)),
+    key,
+  }
+}
+
+/**
+ * Parse a whitespace-separated chord sequence (`g g`, `ctrl+k p`).
+ *
+ * Each whitespace-delimited token is parsed with {@link parseChord}, producing an
+ * ordered list of chords for multi-keystroke bindings.
+ *
+ * @param binding - The binding string, e.g. `'g g'` or `'ctrl+k p'`.
+ * @returns An array of {@link ParsedChord}, one per chord in the sequence.
+ *
+ * @example
+ * parseBinding('g g') // → [{ modifiers: [], key: 'g' }, { modifiers: [], key: 'g' }] (length 2)
+ */
+export function parseBinding(binding: string): ParsedChord[] {
+  return binding.trim().split(/\s+/).filter(Boolean).map(parseChord)
+}
+
+/**
+ * Canonical token for matching, e.g. `ctrl+shift+k`.
+ *
+ * Joins the (already ordered) modifiers and the lower-cased key with `+`,
+ * producing a stable string suitable for keying a binding map or comparing
+ * against {@link eventToToken}.
+ *
+ * @param chord - The parsed chord to serialize.
+ * @returns The canonical `+`-joined token.
+ *
+ * @example
+ * chordToken(parseChord('shift+ctrl+a')) // → 'ctrl+shift+a'
+ */
+export function chordToken(chord: ParsedChord): string {
+  return [...chord.modifiers, chord.key.toLowerCase()].join('+')
+}
+
+/**
+ * Token from a real keyboard event.
+ *
+ * Reads the event's modifier flags and `key`, applies the same key aliases and
+ * canonical modifier ordering as {@link parseChord}, and returns a token that
+ * can be compared directly against {@link chordToken}.
+ *
+ * @param event - The `KeyboardEvent` to serialize.
+ * @returns The canonical `+`-joined token for the event.
+ *
+ * @example
+ * // For a Ctrl+K keydown event:
+ * eventToToken(event) // → 'ctrl+k'
+ */
+export function eventToToken(event: KeyboardEvent): string {
+  const modifiers: string[] = []
+  if (event.ctrlKey)
+    modifiers.push('ctrl')
+  if (event.altKey)
+    modifiers.push('alt')
+  if (event.shiftKey)
+    modifiers.push('shift')
+  if (event.metaKey)
+    modifiers.push('meta')
+  const key = KEY_ALIASES[event.key.toLowerCase()] ?? event.key
+  return [...MOD_ORDER.filter(m => modifiers.includes(m)), key.toLowerCase()].join('+')
+}
+
+const GLYPHS_MAC: Record<string, string> = { meta: '⌘', ctrl: '⌃', alt: '⌥', shift: '⇧' }
+const LABELS: Record<string, string> = { meta: 'Win', ctrl: 'Ctrl', alt: 'Alt', shift: 'Shift' }
+const KEY_GLYPHS: Record<string, string> = {
+  'Enter': '↵',
+  'Escape': 'Esc',
+  'ArrowUp': '↑',
+  'ArrowDown': '↓',
+  'ArrowLeft': '←',
+  'ArrowRight': '→',
+  ' ': 'Space',
+}
+
+/**
+ * Render a chord into display tokens, e.g. `['⌘', '⇧', 'K']` on macOS.
+ *
+ * Modifiers become platform glyphs on Apple (`⌘ ⌃ ⌥ ⇧`) or word labels
+ * elsewhere (`Win`, `Ctrl`, `Alt`, `Shift`); the key becomes its glyph (e.g.
+ * `↵`, `↑`) or an upper-cased single character.
+ *
+ * @param chord - The parsed chord to render.
+ * @returns An array of display tokens, modifiers first then the key.
+ *
+ * @example
+ * chordDisplay(parseChord('ctrl+k'))
+ * // → ['⌃', 'K'] on macOS, ['Ctrl', 'K'] elsewhere
+ */
+export function chordDisplay(chord: ParsedChord): string[] {
+  const mods = chord.modifiers.map(m => isMac ? GLYPHS_MAC[m] : LABELS[m])
+  const key = KEY_GLYPHS[chord.key] ?? (chord.key.length === 1 ? chord.key.toUpperCase() : chord.key)
+  return [...mods, key]
+}
+
+/**
+ * Flatten a full binding sequence into display tokens.
+ *
+ * Parses the binding with {@link parseBinding} and concatenates each chord's
+ * {@link chordDisplay} tokens into a single flat array.
+ *
+ * @param binding - The binding string, e.g. `'ctrl+k'` or `'g g'`.
+ * @returns A flat array of display tokens for the whole sequence.
+ *
+ * @example
+ * bindingDisplay('ctrl+k') // → ['⌃', 'K'] on macOS, ['Ctrl', 'K'] elsewhere (non-empty)
+ */
+export function bindingDisplay(binding: string): string[] {
+  return parseBinding(binding).flatMap(chordDisplay)
+}

package/utils/misc.ts

@@ -0,0 +1,141 @@
+/**
+ * Small design-system-specific helpers. Generic helpers (`clamp`, `toArray`, …)
+ * come from `@antfu/utils` — re-exported from `./index` rather than reimplemented
+ * here — so we ship only what's specific to this library.
+ */
+
+/**
+ * Whether a value represents a finite number.
+ *
+ * Finite numbers pass; numeric strings (after trimming, non-empty) pass; `NaN`,
+ * `Infinity`, empty/blank strings, and non-string/non-number values fail.
+ *
+ * @param value - The value to test.
+ * @returns `true` if `value` is a finite number or a numeric string.
+ *
+ * @example
+ * isNumeric('42') // → true
+ * isNumeric('x') // → false
+ */
+export function isNumeric(value: unknown): boolean {
+  if (typeof value === 'number')
+    return Number.isFinite(value)
+  if (typeof value !== 'string' || value.trim() === '')
+    return false
+  return !Number.isNaN(Number(value))
+}
+
+/**
+ * Format a number with its English ordinal suffix.
+ *
+ * Handles the 11–13 special cases (which take `th`) correctly.
+ *
+ * @param n - The number to format.
+ * @returns The number followed by its ordinal suffix, e.g. `'1st'`.
+ *
+ * @example
+ * nth(1) // → '1st'
+ * nth(22) // → '22nd'
+ * nth(23) // → '23rd'
+ */
+export function nth(n: number): string {
+  const s = ['th', 'st', 'nd', 'rd']
+  const v = n % 100
+  return `${n}${s[(v - 20) % 10] ?? s[v] ?? s[0]}`
+}
+
+/**
+ * Pick the singular or plural form based on a count.
+ *
+ * Returns `singular` only when `count` is exactly `1`; any other count (including
+ * `0`) uses the plural form.
+ *
+ * @param count - The count that decides the form.
+ * @param singular - The singular word.
+ * @param plural - The plural word. Defaults to `singular` + `'s'`.
+ * @returns The appropriate word for the count.
+ *
+ * @example
+ * pluralize(1, 'item') // → 'item'
+ * pluralize(2, 'item') // → 'items'
+ */
+export function pluralize(count: number, singular: string, plural = `${singular}s`): string {
+  return count === 1 ? singular : plural
+}
+
+/**
+ * Parse JSON without throwing, falling back on error.
+ *
+ * Returns the parsed value on success; on a parse error returns `fallback`
+ * (which is `undefined` when omitted).
+ *
+ * @param input - The JSON string to parse.
+ * @param fallback - Value to return if parsing fails. Defaults to `undefined`.
+ * @returns The parsed value, or `fallback` when parsing throws.
+ *
+ * @example
+ * safeJsonParse('{"a":1}') // → { a: 1 }
+ * safeJsonParse('oops', null) // → null
+ */
+export function safeJsonParse<T = unknown>(input: string, fallback?: T): T | undefined {
+  try {
+    return JSON.parse(input) as T
+  }
+  catch {
+    return fallback
+  }
+}
+
+/**
+ * Stringify a value as JSON but with unquoted keys where valid — for compact
+ * config display (`{ foo: 1, "a-b": 2 }`).
+ *
+ * Runs `JSON.stringify` then removes quotes from object keys that are valid
+ * bare JS identifiers; keys needing quotes (e.g. those with hyphens) are left
+ * quoted.
+ *
+ * @param value - The value to stringify.
+ * @param indent - Indentation passed to `JSON.stringify`. Defaults to `2`.
+ * @returns A JSON-like string with identifier keys unquoted.
+ *
+ * @example
+ * stringifyUnquoted({ foo: 1, 'a-b': 2 })
+ * // → '{\n  foo: 1,\n  "a-b": 2\n}' (contains `foo:`, keeps `"a-b"` quoted)
+ */
+export function stringifyUnquoted(value: unknown, indent = 2): string {
+  const json = JSON.stringify(value, null, indent)
+  return json.replace(/^(\s*)"([A-Z_$][\w$]*)":/gim, '$1$2:')
+}
+
+/**
+ * Memoize a single-argument function. The optional `getKey` derives a cache key
+ * (default identity), so reference-stable args dedupe correctly.
+ *
+ * Results are cached in a `Map` keyed by `getKey(arg)`; a cached result is
+ * returned on subsequent calls without re-invoking `fn`. The cache lives for the
+ * lifetime of the returned function and is never evicted.
+ *
+ * @param fn - The single-argument function to memoize.
+ * @param getKey - Derives the cache key from the argument. Defaults to identity (`a => a`).
+ * @returns A memoized wrapper with the same signature as `fn`.
+ *
+ * @example
+ * let calls = 0
+ * const double = makeCachedFunction((x: number) => { calls++; return x * 2 })
+ * double(2) // → 4 (calls === 1)
+ * double(2) // → 4 (cached; calls still 1)
+ */
+export function makeCachedFunction<A, R>(
+  fn: (arg: A) => R,
+  getKey: (arg: A) => unknown = a => a,
+): (arg: A) => R {
+  const cache = new Map<unknown, R>()
+  return (arg: A): R => {
+    const key = getKey(arg)
+    if (cache.has(key))
+      return cache.get(key)!
+    const result = fn(arg)
+    cache.set(key, result)
+    return result
+  }
+}

package/utils/path.ts

@@ -0,0 +1,243 @@
+/**
+ * Module-id / file-path parsing. Generalized from the byte-for-byte duplicate
+ * that lives in both nuxt-devtools and vite-devtools, including the `.pnpm`
+ * decoding used to render readable package paths.
+ */
+
+/**
+ * Normalize Windows backslashes to forward slashes.
+ *
+ * @param path - The file path or module id to normalize.
+ * @returns The path with every `\` replaced by `/`.
+ *
+ * @example
+ * normalizeModulePath('C:\\x\\y') // → 'C:/x/y'
+ */
+export function normalizeModulePath(path: string): string {
+  return path.replace(/\\/g, '/')
+}
+
+/**
+ * Whether a path passes through a `node_modules` directory.
+ *
+ * Normalizes separators first, so Windows paths are handled.
+ *
+ * @param path - The file path or module id to test.
+ * @returns `true` if a `node_modules` segment is present.
+ *
+ * @example
+ * isNodeModulePath('/x/node_modules/foo/index.js') // → true
+ * isNodeModulePath('/x/src/a.ts') // → false
+ */
+export function isNodeModulePath(path: string): boolean {
+  return /\bnode_modules\b/.test(normalizeModulePath(path))
+}
+
+/**
+ * Whether an id looks like a bare package specifier (not a relative/absolute path).
+ *
+ * Rejects empty strings, ids starting with `.` or `/`, protocol-prefixed ids
+ * (`foo:`), and Windows drive paths; otherwise requires a valid (optionally
+ * scoped) npm package name shape.
+ *
+ * @param id - The module id to test.
+ * @returns `true` if `id` is a bare package specifier.
+ *
+ * @example
+ * isPackageName('foo') // → true
+ * isPackageName('@scope/name') // → true
+ * isPackageName('./foo') // → false
+ * isPackageName('/abs/path') // → false
+ */
+export function isPackageName(id: string): boolean {
+  if (!id || id.startsWith('.') || id.startsWith('/') || /^[a-z]+:/i.test(id) || /^[a-z]:[\\/]/i.test(id))
+    return false
+  return /^(?:@[\w.-]+\/)?[\w.-]+(?:\/[\w.-]+)*$/.test(id)
+}
+
+export interface PnpmPackageInfo {
+  name: string
+  version: string
+}
+
+/**
+ * Decode a `.pnpm` directory segment like `foo@1.2.3`, `@scope+name@1.2.3` or
+ * `foo@1.2.3_peer@4` into `{ name, version }`.
+ *
+ * Strips any `_peer@...` suffix, splits name from version at the last `@`, and
+ * decodes pnpm's `@scope+name` scope encoding back to `@scope/name`. Returns
+ * `undefined` when no version `@` is present.
+ *
+ * @param segment - The raw `.pnpm` segment to decode.
+ * @returns A {@link PnpmPackageInfo}, or `undefined` if the segment has no version.
+ *
+ * @example
+ * parsePnpmSegment('@scope+name@1.2.3_react@18') // → { name: '@scope/name', version: '1.2.3' }
+ * parsePnpmSegment('foo@1.2.3') // → { name: 'foo', version: '1.2.3' }
+ */
+export function parsePnpmSegment(segment: string): PnpmPackageInfo | undefined {
+  // Strip peer-dependency suffix (`_react@18...`).
+  const base = segment.split('_')[0]
+  const at = base.lastIndexOf('@')
+  if (at <= 0)
+    return undefined
+  const rawName = base.slice(0, at)
+  const version = base.slice(at + 1)
+  // pnpm encodes scopes as `@scope+name` (sometimes without the leading `@`).
+  let name = rawName
+  if (rawName.includes('+')) {
+    name = rawName.replace('+', '/')
+    if (!name.startsWith('@'))
+      name = `@${name}`
+  }
+  return { name, version }
+}
+
+/**
+ * Extract `{ name, version }` from a path that traverses a `.pnpm` store.
+ *
+ * Finds the segment immediately after `.pnpm/` and decodes it via
+ * {@link parsePnpmSegment}. Returns `undefined` when the path has no `.pnpm`
+ * directory.
+ *
+ * @param path - The file path to inspect.
+ * @returns A {@link PnpmPackageInfo}, or `undefined` if not a `.pnpm` path.
+ *
+ * @example
+ * getPnpmPackageInfoFromPath('/x/node_modules/.pnpm/foo@1.2.3/node_modules/foo/i.js')
+ * // → { name: 'foo', version: '1.2.3' }
+ */
+export function getPnpmPackageInfoFromPath(path: string): PnpmPackageInfo | undefined {
+  const match = normalizeModulePath(path).match(/\.pnpm\/([^/]+)/)
+  if (!match)
+    return undefined
+  return parsePnpmSegment(match[1])
+}
+
+/**
+ * Get the package name from a `node_modules` path (`.../node_modules/@scope/name/dist/x` → `@scope/name`).
+ *
+ * Prefers a `.pnpm`-decoded name when present; otherwise reads the segment(s)
+ * after the last `node_modules/`, keeping the `@scope/name` pair for scoped
+ * packages. Returns `undefined` when the path is not inside `node_modules`.
+ *
+ * @param path - The file path to inspect.
+ * @returns The package name, or `undefined` if none can be resolved.
+ *
+ * @example
+ * getModuleNameFromPath('/x/node_modules/@scope/name/dist/i.js') // → '@scope/name'
+ * getModuleNameFromPath('/x/node_modules/foo/index.js') // → 'foo'
+ * getModuleNameFromPath('/x/src/a.ts') // → undefined
+ */
+export function getModuleNameFromPath(path: string): string | undefined {
+  const normalized = normalizeModulePath(path)
+  const pnpm = getPnpmPackageInfoFromPath(normalized)
+  if (pnpm)
+    return pnpm.name
+  const idx = normalized.lastIndexOf('node_modules/')
+  if (idx === -1)
+    return undefined
+  const rest = normalized.slice(idx + 'node_modules/'.length)
+  const segments = rest.split('/')
+  return segments[0].startsWith('@') ? `${segments[0]}/${segments[1]}` : segments[0]
+}
+
+/**
+ * Collapse a `.pnpm/<pkg>@ver/node_modules/<pkg>` chunk to `~`, leaving the tail.
+ *
+ * Replaces everything up to and including the inner `node_modules/` of a `.pnpm`
+ * store path with the `replacement` prefix, yielding a short, readable path.
+ *
+ * @param path - The file path to collapse.
+ * @param replacement - The prefix to substitute for the store chunk. Defaults to `'~/'`.
+ * @returns The path with the `.pnpm` store prefix replaced.
+ *
+ * @example
+ * collapsePnpmPath('/x/node_modules/.pnpm/foo@1.2.3/node_modules/foo/index.js')
+ * // → '~/foo/index.js'
+ */
+export function collapsePnpmPath(path: string, replacement = '~/'): string {
+  return normalizeModulePath(path).replace(/.*\.pnpm\/[^/]+\/node_modules\//, replacement)
+}
+
+export interface RelativeModulePathOptions {
+  /** Prefix substituted for a `.pnpm` store chunk. Defaults to `'~/'`. */
+  pnpmCollapse?: string
+  /** Beyond this many `../` levels, return the absolute path instead. Defaults to `3`. */
+  maxUp?: number
+}
+
+/**
+ * Make a module id readable relative to a project root: trims the root prefix,
+ * decodes `.pnpm` to `~`, and keeps absolute past 3 levels of `../`.
+ *
+ * `.pnpm` paths are collapsed via {@link collapsePnpmPath}; if the id lives under
+ * `root`, the root prefix is stripped and a `./` prefix added; otherwise a
+ * `../`-relative path is synthesized, falling back to the absolute path once it
+ * would need more than `maxUp` (default 3) `../` hops.
+ *
+ * @param id - The module id or file path to make relative.
+ * @param root - The project root to make the path relative to.
+ * @param options - See {@link RelativeModulePathOptions}.
+ * @returns A readable, root-relative path.
+ *
+ * @example
+ * relativeModulePath('/root/src/a.ts', '/root') // → './src/a.ts'
+ * relativeModulePath('/root/pkg/b.ts', '/root/app') // → '../pkg/b.ts'
+ */
+export function relativeModulePath(id: string, root: string, options: RelativeModulePathOptions = {}): string {
+  const { pnpmCollapse = '~/', maxUp = 3 } = options
+  const path = normalizeModulePath(id)
+  const normRoot = normalizeModulePath(root).replace(/\/$/, '')
+  if (path.includes('.pnpm/'))
+    return collapsePnpmPath(path, pnpmCollapse)
+  if (!normRoot)
+    return path
+  if (path === normRoot)
+    return '.'
+  if (path.startsWith(`${normRoot}/`)) {
+    const rest = path.slice(normRoot.length + 1)
+    return rest.startsWith('.') ? rest : `./${rest}`
+  }
+  // Outside the root: synthesize `../`, but bail to absolute past `maxUp` hops.
+  const rootParts = normRoot.split('/')
+  const pathParts = path.split('/')
+  let common = 0
+  while (common < rootParts.length && common < pathParts.length && rootParts[common] === pathParts[common])
+    common++
+  const up = rootParts.length - common
+  if (up > maxUp || common === 0)
+    return path
+  return `${'../'.repeat(up)}${pathParts.slice(common).join('/')}`
+}
+
+export interface ReadablePath {
+  /** Display path. */
+  path: string
+  /** Resolved package name when the path lives in `node_modules`. */
+  moduleName?: string
+}
+
+/**
+ * Build a display path plus resolved package name for a module id.
+ *
+ * Combines {@link relativeModulePath} for the display path with
+ * {@link getModuleNameFromPath} (only for `node_modules` paths) for the package
+ * name.
+ *
+ * @param path - The module id or file path.
+ * @param root - The project root used to relativize the display path.
+ * @param options - Forwarded to {@link relativeModulePath}.
+ * @returns A {@link ReadablePath} with `path` and, for dependencies, `moduleName`.
+ *
+ * @example
+ * parseReadablePath('/x/node_modules/foo/index.js', '/x')
+ * // → { path: './node_modules/foo/index.js', moduleName: 'foo' }
+ */
+export function parseReadablePath(path: string, root: string, options?: RelativeModulePathOptions): ReadablePath {
+  const moduleName = isNodeModulePath(path) ? getModuleNameFromPath(path) : undefined
+  return {
+    path: relativeModulePath(path, root, options),
+    moduleName,
+  }
+}