keymaster monorepo

🌐 Language

• English (current)
• 中文

A modern keyboard shortcut library monorepo for React / Vue / Core utilities, supporting scoped binding, editor mode, and Electron scenarios.

Features • Installation • Quick Start • Packages & Versions • Monorepo Development • Publishing Process

---

✨ Features

• 🎯 Precise Shortcut Parsing: Supports key combinations, multi-key mapping, and cross-platform modifier key handling
• 🧠 Shared Core Module: @keekuun/keymaster-core unified management of parsing, matching, types, and utility functions
• 🧩 Scoped Binding (scopedElement): Only responds to shortcuts within specified containers / editors
• ✏️ Editor Mode (editorMode): Automatically preventDefault, suitable for editor-like products
• 🖥️ Electron Mode (electronMode): Extension points reserved for desktop applications
• ⚛️ React Hook Wrapper: useKeyBinding / useScopedKeyBinding / useEditorKeyBinding / useElectronKeyBinding
• 🧪 Vue Composition API: useKeyBindingVue / useScopedKeyBindingVue / useEditorKeyBindingVue / useElectronKeyBindingVue
• 📦 TypeScript First: Complete declaration files, automatically generated by vite-plugin-dts
• 📚 Complete Documentation Site: Interactive documentation based on VitePress, supporting multi-version management and online demos

---

📦 Installation

React Version:

npm install @keekuun/keymaster-react
# or
pnpm add @keekuun/keymaster-react
# or
yarn add @keekuun/keymaster-react

Vue Version:

npm install @keekuun/keymaster-vue
# or
pnpm add @keekuun/keymaster-vue
# or
yarn add @keekuun/keymaster-vue

Core Module (usually auto-installed as dependency, can also be used standalone):

npm install @keekuun/keymaster-core

---

🚀 Quick Start

React Basic Usage

import { useKeyBinding } from '@keekuun/keymaster-react';

function App() {
  useKeyBinding('ctrl+s', (event) => {
    event.preventDefault();
    console.log('Save operation');
  });

  return <div>Press Ctrl + S to save</div>;
}

Scoped Binding Example:

import { useRef } from 'react';
import { useScopedKeyBinding } from '@keekuun/keymaster-react';

function Editor() {
  const containerRef = useRef<HTMLDivElement | null>(null);

  useScopedKeyBinding(
    'ctrl+k',
    () => {
      console.log('Shortcut only works within container');
    },
    containerRef,
  );

  return <div ref={containerRef}>Ctrl + K only works here</div>;
}

Vue Basic Usage

<script setup lang="ts">
import { useKeyBindingVue } from '@keekuun/keymaster-vue';

useKeyBindingVue('ctrl+s', (event) => {
  event.preventDefault();
  console.log('Save operation');
});
</script>

<template>
  <div>Press Ctrl + S to save</div>
</template>

Editor Mode Example:

<script setup lang="ts">
import { ref } from 'vue';
import { useEditorKeyBindingVue } from '@keekuun/keymaster-vue';

const editorRef = ref<HTMLTextAreaElement | null>(null);

useEditorKeyBindingVue(
  'ctrl+s',
  () => {
    console.log('Save in editor, no browser default behavior');
  },
  editorRef.value || undefined,
);
</script>

<template>
  <textarea ref="editorRef" rows="6" cols="40" />
</template>

More examples (including Electron mode and advanced usage) can be found on the documentation site.

---

📦 Packages & Versions

The current monorepo contains the following sub-packages:

• @keekuun/keymaster-core: Core parsing / matching / type definition module
• @keekuun/keymaster-react: React Hook wrapper
• @keekuun/keymaster-vue: Vue Composition API wrapper
• keymaster-docs: Documentation and example site based on VitePress

Currently Published Versions

• @keekuun/keymaster-core: v0.5.0 - npm
• @keekuun/keymaster-react: v0.5.0 - npm
• @keekuun/keymaster-vue: v0.5.0 - npm

Documentation Site

• Online Documentation: https://keymaster-docs.vercel.app/
  • React Documentation: https://keymaster-docs.vercel.app/react/
  • Vue Documentation: https://keymaster-docs.vercel.app/vue/
  • Core Documentation: https://keymaster-docs.vercel.app/core/
  • Version Management: https://keymaster-docs.vercel.app/versions

Package Dependencies

@keekuun/keymaster-core (core module)
    ├── @keekuun/keymaster-react (depends on core)
    └── @keekuun/keymaster-vue (depends on core)

Important Notes:

• keymaster-core is a runtime dependency of keymaster-react and keymaster-vue
• When installing @keekuun/keymaster-react or @keekuun/keymaster-vue, @keekuun/keymaster-core will be automatically installed
• Only install @keekuun/keymaster-core separately if you need to use core utility functions alone

---

🧱 Monorepo Development

This repository uses pnpm workspace to manage the multi-package structure. Root directory scripts:

• pnpm build: Recursively build all packages (core / react / vue / docs)
• pnpm lint: Run ESLint checks for all packages and root directory
• pnpm lint:fix: Run ESLint auto-fix for all packages and root directory
• pnpm format: Check formatting with Prettier
• pnpm format:write: Auto-format with Prettier
• pnpm docs:dev: Start documentation dev server in apps/keymaster-docs
• pnpm docs:build: Build all libraries + documentation site
• pnpm docs:preview: Preview built documentation site

Before commit, Husky will automatically execute:

• ESLint auto-fix (all packages)
• Prettier auto-formatting

---

🚢 Publishing Process (Overview)

For detailed steps, see PUBLISH.md. Here's a brief overview:

1. Confirm code passes pnpm lint, pnpm test (if any), pnpm docs:build
2. Use standard-version to manage versions and CHANGELOG.md:
   • pnpm release: Patch version
   • pnpm release:minor: Minor version
   • pnpm release:major: Major version
3. Use publishing scripts to publish to npm:
   • pnpm publish:core
   • pnpm publish:react
   • pnpm publish:vue
   • Or pnpm publish:all to publish all three packages at once
4. Push code and tags, Vercel will automatically trigger documentation site update

---

📮 Feedback & Support

• Repository: https://github.com/Keekuun/keymaster
• Issue Reports / Feature Suggestions: Create entries in GitHub Issues
• Usage Questions & API Details: Refer to documentation site https://keymaster-docs.vercel.app/