@tanstack/hotkeys-devtools 0.0.1 → 0.1.0

package/src/components/ActionButtons.tsx

@@ -0,0 +1,25 @@
+import { HotkeyManager } from '@tanstack/hotkeys'
+import { useStyles } from '../styles/use-styles'
+import type { HotkeyRegistration } from '@tanstack/hotkeys'
+
+type ActionButtonsProps = {
+  registration: HotkeyRegistration
+}
+
+export function ActionButtons(props: ActionButtonsProps) {
+  const styles = useStyles()
+
+  const handleTrigger = () => {
+    const manager = HotkeyManager.getInstance()
+    manager.triggerRegistration(props.registration.id)
+  }
+
+  return (
+    <div class={styles().actionsRow}>
+      <button class={styles().actionButton} onMouseDown={handleTrigger}>
+        <span class={styles().actionDotGreen} />
+        Trigger
+      </button>
+    </div>
+  )
+}

package/src/components/DetailsPanel.tsx

@@ -0,0 +1,298 @@
+import { For, Show, createMemo } from 'solid-js'
+import { formatForDisplay } from '@tanstack/hotkeys'
+import { useStyles } from '../styles/use-styles'
+import { useHotkeysDevtoolsState } from '../HotkeysContextProvider'
+import { ActionButtons } from './ActionButtons'
+import type { ConflictBehavior, HotkeyRegistration } from '@tanstack/hotkeys'
+
+type DetailsPanelProps = {
+  selectedRegistration: () => HotkeyRegistration | null
+}
+
+function getTargetDescription(target: HTMLElement | Document | Window): string {
+  if (typeof document !== 'undefined' && target === document) {
+    return 'document'
+  }
+  if (typeof window !== 'undefined' && target === window) {
+    return 'window'
+  }
+  if (target instanceof HTMLElement) {
+    const tag = target.tagName.toLowerCase()
+    const id = target.id ? `#${target.id}` : ''
+    const cls = target.className
+      ? `.${target.className.split(' ').join('.')}`
+      : ''
+    return `${tag}${id}${cls}`
+  }
+  return 'element'
+}
+
+function findTargetConflicts(
+  registration: HotkeyRegistration,
+  all: Array<HotkeyRegistration>,
+): Array<HotkeyRegistration> {
+  return all.filter(
+    (other) =>
+      other.id !== registration.id &&
+      other.hotkey === registration.hotkey &&
+      other.options.eventType === registration.options.eventType &&
+      other.target === registration.target,
+  )
+}
+
+function findScopeConflicts(
+  registration: HotkeyRegistration,
+  all: Array<HotkeyRegistration>,
+): Array<HotkeyRegistration> {
+  return all.filter(
+    (other) =>
+      other.id !== registration.id &&
+      other.hotkey === registration.hotkey &&
+      other.options.eventType === registration.options.eventType &&
+      other.target !== registration.target,
+  )
+}
+
+function getConflictItemStyle(
+  behavior: ConflictBehavior,
+  isSameTarget: boolean,
+):
+  | 'conflictItem'
+  | 'conflictItemAllow'
+  | 'conflictItemError'
+  | 'conflictItemScope' {
+  if (!isSameTarget) return 'conflictItemScope'
+  if (behavior === 'allow') return 'conflictItemAllow'
+  if (behavior === 'error') return 'conflictItemError'
+  return 'conflictItem'
+}
+
+function getConflictLabel(
+  behavior: ConflictBehavior,
+  isSameTarget: boolean,
+): string {
+  if (!isSameTarget) return 'scope'
+  if (behavior === 'allow') return 'allowed'
+  if (behavior === 'error') return 'error'
+  if (behavior === 'replace') return 'replaced'
+  return 'warning'
+}
+
+export function DetailsPanel(props: DetailsPanelProps) {
+  const styles = useStyles()
+  const state = useHotkeysDevtoolsState()
+
+  return (
+    <div class={styles().stateDetails}>
+      <Show
+        when={props.selectedRegistration()}
+        fallback={
+          <div class={styles().noSelection}>
+            Select a hotkey from the list to view its details
+          </div>
+        }
+      >
+        {(reg) => {
+          const parsed = () => reg().parsedHotkey
+          const targetConflicts = createMemo(() =>
+            findTargetConflicts(reg(), state.registrations()),
+          )
+          const scopeConflicts = createMemo(() =>
+            findScopeConflicts(reg(), state.registrations()),
+          )
+          const allConflicts = createMemo(() => [
+            ...targetConflicts(),
+            ...scopeConflicts(),
+          ])
+          const conflictBehavior = (): ConflictBehavior =>
+            reg().options.conflictBehavior ?? 'warn'
+
+          // Build key parts for visual breakdown
+          const keyParts = createMemo(() => {
+            const parts: Array<string> = []
+            const p = parsed()
+            if (p.ctrl) parts.push('Ctrl')
+            if (p.shift) parts.push('Shift')
+            if (p.alt) parts.push('Alt')
+            if (p.meta) parts.push('Meta')
+            parts.push(p.key)
+            return parts
+          })
+
+          return (
+            <>
+              <div class={styles().stateHeader}>
+                <div class={styles().stateTitle}>
+                  {formatForDisplay(reg().hotkey)}
+                </div>
+                <div class={styles().infoGrid}>
+                  <div class={styles().infoLabel}>ID</div>
+                  <div class={styles().infoValueMono}>{reg().id}</div>
+                  <div class={styles().infoLabel}>Raw</div>
+                  <div class={styles().infoValueMono}>{reg().hotkey}</div>
+                  <div class={styles().infoLabel}>Target</div>
+                  <div class={styles().infoValueMono}>
+                    {getTargetDescription(reg().target)}
+                  </div>
+                </div>
+              </div>
+
+              <div class={styles().detailsGrid}>
+                {/* Key Breakdown */}
+                <div class={styles().detailSection}>
+                  <div class={styles().detailSectionHeader}>Key Breakdown</div>
+                  <div class={styles().keyBreakdown}>
+                    <For each={keyParts()}>
+                      {(part, i) => (
+                        <>
+                          <Show when={i() > 0}>
+                            <span class={styles().keyBreakdownPlus}>+</span>
+                          </Show>
+                          <span class={styles().keyCapLarge}>{part}</span>
+                        </>
+                      )}
+                    </For>
+                  </div>
+                </div>
+
+                {/* Actions */}
+                <div class={styles().detailSection}>
+                  <div class={styles().detailSectionHeader}>Actions</div>
+                  <ActionButtons registration={reg()} />
+                </div>
+
+                {/* Options */}
+                <div class={styles().detailSection}>
+                  <div class={styles().detailSectionHeader}>Options</div>
+                  <div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>enabled</span>
+                      <span
+                        class={
+                          reg().options.enabled !== false
+                            ? styles().optionValueTrue
+                            : styles().optionValueFalse
+                        }
+                      >
+                        {String(reg().options.enabled !== false)}
+                      </span>
+                    </div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>eventType</span>
+                      <span class={styles().optionValue}>
+                        {reg().options.eventType ?? 'keydown'}
+                      </span>
+                    </div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>preventDefault</span>
+                      <span
+                        class={
+                          reg().options.preventDefault
+                            ? styles().optionValueTrue
+                            : styles().optionValueFalse
+                        }
+                      >
+                        {String(!!reg().options.preventDefault)}
+                      </span>
+                    </div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>stopPropagation</span>
+                      <span
+                        class={
+                          reg().options.stopPropagation
+                            ? styles().optionValueTrue
+                            : styles().optionValueFalse
+                        }
+                      >
+                        {String(!!reg().options.stopPropagation)}
+                      </span>
+                    </div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>ignoreInputs</span>
+                      <span
+                        class={
+                          reg().options.ignoreInputs !== false
+                            ? styles().optionValueTrue
+                            : styles().optionValueFalse
+                        }
+                      >
+                        {String(reg().options.ignoreInputs !== false)}
+                      </span>
+                    </div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>requireReset</span>
+                      <span
+                        class={
+                          reg().options.requireReset
+                            ? styles().optionValueTrue
+                            : styles().optionValueFalse
+                        }
+                      >
+                        {String(!!reg().options.requireReset)}
+                      </span>
+                    </div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>conflictBehavior</span>
+                      <span class={styles().optionValue}>
+                        {conflictBehavior()}
+                      </span>
+                    </div>
+                    <div class={styles().optionRow}>
+                      <span class={styles().optionLabel}>hasFired</span>
+                      <span
+                        class={
+                          reg().hasFired
+                            ? styles().optionValueTrue
+                            : styles().optionValueFalse
+                        }
+                      >
+                        {String(reg().hasFired)}
+                      </span>
+                    </div>
+                  </div>
+                </div>
+
+                {/* Conflicts */}
+                <Show when={allConflicts().length > 0}>
+                  <div class={styles().detailSection}>
+                    <div class={styles().detailSectionHeader}>
+                      Conflicts ({allConflicts().length})
+                    </div>
+                    <div class={styles().conflictList}>
+                      <For each={targetConflicts()}>
+                        {(conflict) => {
+                          const itemStyle = () =>
+                            getConflictItemStyle(conflictBehavior(), true)
+                          const label = () =>
+                            getConflictLabel(conflictBehavior(), true)
+                          return (
+                            <div class={styles()[itemStyle()]}>
+                              <span>{label()}</span> {conflict.id}:{' '}
+                              {formatForDisplay(conflict.hotkey)} (
+                              {conflict.options.eventType ?? 'keydown'}) on{' '}
+                              {getTargetDescription(conflict.target)}
+                            </div>
+                          )
+                        }}
+                      </For>
+                      <For each={scopeConflicts()}>
+                        {(conflict) => (
+                          <div class={styles().conflictItemScope}>
+                            <span>scope</span> {conflict.id}:{' '}
+                            {formatForDisplay(conflict.hotkey)} (
+                            {conflict.options.eventType ?? 'keydown'}) on{' '}
+                            {getTargetDescription(conflict.target)}
+                          </div>
+                        )}
+                      </For>
+                    </div>
+                  </div>
+                </Show>
+              </div>
+            </>
+          )
+        }}
+      </Show>
+    </div>
+  )
+}

package/src/components/HeldKeysTopbar.tsx

@@ -0,0 +1,42 @@
+import { For, Show } from 'solid-js'
+import { formatKeyForDebuggingDisplay } from '@tanstack/hotkeys'
+import { useStyles } from '../styles/use-styles'
+import { useHotkeysDevtoolsState } from '../HotkeysContextProvider'
+
+export function HeldKeysBar() {
+  const styles = useStyles()
+  const state = useHotkeysDevtoolsState()
+
+  return (
+    <div class={styles().heldKeysBar}>
+      <span class={styles().heldKeysBarHeader}>Held</span>
+      <div class={styles().heldKeysBarList}>
+        <Show
+          when={state.heldKeys().length > 0}
+          fallback={<span class={styles().noKeysHeld}>--</span>}
+        >
+          <For each={state.heldKeys()}>
+            {(key) => {
+              const code = () => state.heldCodes()[key]
+              const label = () => formatKeyForDebuggingDisplay(key)
+              const codeLabel = () => {
+                const c = code()
+                return c
+                  ? formatKeyForDebuggingDisplay(c, { source: 'code' })
+                  : undefined
+              }
+              return (
+                <span class={styles().keyCap}>
+                  <span>{label()}</span>
+                  <Show when={codeLabel() && codeLabel() !== key}>
+                    <span class={styles().keyCapCode}>{codeLabel()}</span>
+                  </Show>
+                </span>
+              )
+            }}
+          </For>
+        </Show>
+      </div>
+    </div>
+  )
+}

package/src/components/HotkeyList.tsx

@@ -0,0 +1,248 @@
+import { For, Show, createEffect, createMemo, createSignal, on } from 'solid-js'
+import clsx from 'clsx'
+import { formatForDisplay } from '@tanstack/hotkeys'
+import { useStyles } from '../styles/use-styles'
+import { useHotkeysDevtoolsState } from '../HotkeysContextProvider'
+import type { ConflictBehavior, HotkeyRegistration } from '@tanstack/hotkeys'
+
+type HotkeyListProps = {
+  selectedId: () => string | null
+  setSelectedId: (id: string | null) => void
+}
+
+function getTargetLabel(target: HTMLElement | Document | Window): string {
+  if (typeof document !== 'undefined' && target === document) {
+    return 'document'
+  }
+  if (typeof window !== 'undefined' && target === window) {
+    return 'window'
+  }
+  if (target instanceof HTMLElement) {
+    return target.tagName.toLowerCase()
+  }
+  return 'element'
+}
+
+function getTargetTooltip(target: HTMLElement | Document | Window): string {
+  if (typeof document !== 'undefined' && target === document) {
+    return 'Listening on document'
+  }
+  if (typeof window !== 'undefined' && target === window) {
+    return 'Listening on window'
+  }
+  if (target instanceof HTMLElement) {
+    const tag = target.tagName.toLowerCase()
+    const parts: Array<string> = [tag]
+    if (target.id) {
+      parts.push(`id="${target.id}"`)
+    }
+    if (target.className) {
+      const classes = target.className.split(/\s+/).filter(Boolean).join(', ')
+      parts.push(`class="${classes}"`)
+    }
+    // Collect data- attributes
+    const dataAttrs = Array.from(target.attributes)
+      .filter((attr) => attr.name.startsWith('data-'))
+      .map((attr) => `${attr.name}="${attr.value}"`)
+    if (dataAttrs.length > 0) {
+      parts.push(...dataAttrs)
+    }
+    return `Listening on ${parts.join(' ')}`
+  }
+  return 'Listening on element'
+}
+
+function findTargetConflicts(
+  registration: HotkeyRegistration,
+  all: Array<HotkeyRegistration>,
+): Array<HotkeyRegistration> {
+  return all.filter(
+    (other) =>
+      other.id !== registration.id &&
+      other.hotkey === registration.hotkey &&
+      other.options.eventType === registration.options.eventType &&
+      other.target === registration.target,
+  )
+}
+
+function findScopeConflicts(
+  registration: HotkeyRegistration,
+  all: Array<HotkeyRegistration>,
+): Array<HotkeyRegistration> {
+  return all.filter(
+    (other) =>
+      other.id !== registration.id &&
+      other.hotkey === registration.hotkey &&
+      other.options.eventType === registration.options.eventType &&
+      other.target !== registration.target,
+  )
+}
+
+export function HotkeyList(props: HotkeyListProps) {
+  const styles = useStyles()
+  const state = useHotkeysDevtoolsState()
+
+  const registrations = createMemo(() => state.registrations())
+
+  return (
+    <>
+      <div class={styles().panelHeader}>Hotkeys ({registrations().length})</div>
+      <div class={styles().hotkeyList}>
+        <For each={registrations()}>
+          {(reg) => {
+            const targetConflicts = () =>
+              findTargetConflicts(reg, registrations())
+            const scopeConflicts = () =>
+              findScopeConflicts(reg, registrations())
+
+            const hasTargetConflict = () => targetConflicts().length > 0
+            const hasScopeConflict = () => scopeConflicts().length > 0
+
+            const conflictBehavior = (): ConflictBehavior =>
+              reg.options.conflictBehavior ?? 'warn'
+
+            const targetConflictBadge = () => {
+              const behavior = conflictBehavior()
+              const c = targetConflicts()
+              if (behavior === 'allow') {
+                return {
+                  style: 'badgeAllow' as const,
+                  label: '~',
+                  tooltip: `Allowed: ${c.length} other binding${c.length > 1 ? 's' : ''} on same key and target (conflictBehavior: allow)`,
+                }
+              }
+              if (behavior === 'error') {
+                return {
+                  style: 'badgeError' as const,
+                  label: '!',
+                  tooltip: `Error: ${c.length} conflicting binding${c.length > 1 ? 's' : ''} on same key and target (conflictBehavior: error)`,
+                }
+              }
+              // 'warn' (default) or 'replace' (replacement already happened, but show warn-style if somehow present)
+              return {
+                style: 'badgeConflict' as const,
+                label: '!',
+                tooltip: `Warning: ${c.length} other binding${c.length > 1 ? 's' : ''} on same key and target`,
+              }
+            }
+
+            const scopeConflictTooltip = () => {
+              const c = scopeConflicts()
+              return `Info: ${c.length} binding${c.length > 1 ? 's' : ''} with same key on different target${c.length > 1 ? 's' : ''}`
+            }
+
+            const enabled = () => reg.options.enabled !== false
+
+            // Look up trigger count reactively from the registrations list
+            // (reg is a stable object ref; the list re-derives on store change)
+            const triggerCount = () =>
+              registrations().find((r) => r.id === reg.id)?.triggerCount ??
+              reg.triggerCount
+
+            // Track trigger count changes for pulse animation
+            const [prevCount, setPrevCount] = createSignal(reg.triggerCount)
+            const [pulsing, setPulsing] = createSignal(false)
+
+            createEffect(
+              on(triggerCount, (current) => {
+                if (current > prevCount()) {
+                  setPulsing(true)
+                  setTimeout(() => setPulsing(false), 600)
+                }
+                setPrevCount(current)
+              }),
+            )
+
+            return (
+              <div
+                class={clsx(
+                  styles().hotkeyRow,
+                  props.selectedId() === reg.id && styles().hotkeyRowSelected,
+                  pulsing() && styles().hotkeyRowTriggered,
+                )}
+                onClick={() => props.setSelectedId(reg.id)}
+              >
+                <span class={styles().hotkeyLabel}>
+                  {formatForDisplay(reg.hotkey)}
+                </span>
+                <Show when={triggerCount() > 0}>
+                  <span class={styles().triggerCount}>x{triggerCount()}</span>
+                </Show>
+                <div class={styles().hotkeyBadges}>
+                  {hasTargetConflict() && (
+                    <span
+                      class={clsx(
+                        styles().badge,
+                        styles()[targetConflictBadge().style],
+                        styles().tooltip,
+                      )}
+                    >
+                      {targetConflictBadge().label}
+                      <span class={styles().tooltipText} data-tooltip>
+                        {targetConflictBadge().tooltip}
+                      </span>
+                    </span>
+                  )}
+                  {hasScopeConflict() && (
+                    <span
+                      class={clsx(
+                        styles().badge,
+                        styles().badgeInfo,
+                        styles().tooltip,
+                      )}
+                    >
+                      i
+                      <span class={styles().tooltipText} data-tooltip>
+                        {scopeConflictTooltip()}
+                      </span>
+                    </span>
+                  )}
+                  <span
+                    class={clsx(
+                      styles().badge,
+                      enabled()
+                        ? styles().badgeEnabled
+                        : styles().badgeDisabled,
+                      styles().tooltip,
+                    )}
+                  >
+                    {enabled() ? 'on' : 'off'}
+                    <span class={styles().tooltipText} data-tooltip>
+                      {enabled() ? 'Hotkey is enabled' : 'Hotkey is disabled'}
+                    </span>
+                  </span>
+                  <span
+                    class={clsx(
+                      styles().badge,
+                      (reg.options.eventType ?? 'keydown') === 'keydown'
+                        ? styles().badgeKeydown
+                        : styles().badgeKeyup,
+                      styles().tooltip,
+                    )}
+                  >
+                    {reg.options.eventType ?? 'keydown'}
+                    <span class={styles().tooltipText} data-tooltip>
+                      Fires on {reg.options.eventType ?? 'keydown'} event
+                    </span>
+                  </span>
+                  <span
+                    class={clsx(
+                      styles().badge,
+                      styles().badgeTarget,
+                      styles().tooltip,
+                    )}
+                  >
+                    {getTargetLabel(reg.target)}
+                    <span class={styles().tooltipText} data-tooltip>
+                      {getTargetTooltip(reg.target)}
+                    </span>
+                  </span>
+                </div>
+              </div>
+            )
+          }}
+        </For>
+      </div>
+    </>
+  )
+}