hotkeys-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e144f56e44055cc18278c5250a6297519b873bde607c51b24dd5521a40f176e
+  data.tar.gz: 601a217fb719cffca22d8869eee811cf2052d3f63d45e5a46f0b94812bc8605d
+SHA512:
+  metadata.gz: 72d1774b2efa3e4c85a6fddf37729a91e16c36e455a8d8cd4e5e519d680e20ccb71515e51899f7e7cbe45321ac5baacf190b02770ae995810299060f5c8968ea
+  data.tar.gz: a96373911237b3d209f714a9088762c78cc7f7a209b4c16fdd1740d9d5647fbf7f94a5ed61a0c501ed9c4a27582ff1a6e39d7867a82526c419d23937b27bf5d5

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2024-12-02
+
+Initial release.
+
+### Added
+
+- `hotkey` option for `link_to`, `button_to`, and `button_tag` helpers
+- `hotkey(*keys)` helper for explicit data attribute generation
+- `hotkey_label(*keys)` for platform-aware keyboard shortcut labels
+- `hotkey_hint(*keys)` for rendering `<kbd>` elements
+- Dual binding for `:ctrl` modifier (Ctrl on Windows/Linux, Cmd on Mac)
+- Focus action support via `hotkey(:key, action: :focus)`
+- Rails generator for installing Stimulus controller
+- Demo app for testing with Playwright

data/README.md

@@ -0,0 +1,78 @@
+# Hotkeys Rails
+
+Keyboard shortcuts for Hotwire apps. No dependencies. No configuration. Just HTML.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "hotkeys-rails"
+```
+
+Run:
+
+```sh
+bundle install
+rails generate hotkeys_rails:install
+```
+
+## Usage
+
+```erb
+<%= link_to "Back", root_path, hotkey: :esc %>
+<%= button_to "New Card", cards_path, hotkey: :c %>
+<%= button_tag "Save", hotkey: [:ctrl, :enter] %>
+```
+
+The `:ctrl` modifier binds both Ctrl (Windows/Linux) and Cmd (Mac).
+
+### Visual Hints
+
+```erb
+<%= link_to cards_path, hotkey: :c do %>
+  Add a card <%= hotkey_hint(:c) %>
+<% end %>
+```
+
+### Labels for Tooltips
+
+```erb
+<%= button_tag "Save",
+      title: "Save (#{hotkey_label(:ctrl, :enter)})",
+      hotkey: [:ctrl, :enter] %>
+```
+
+### Focus Instead of Click
+
+```erb
+<%= text_field_tag :search, data: hotkey(:f, action: :focus) %>
+```
+
+### Works with Other Data Attributes
+
+```erb
+<%= link_to "Edit", edit_path,
+      hotkey: :e,
+      data: { turbo_frame: "modal" } %>
+```
+
+## Helpers
+
+- `hotkey(*keys)` - Returns data attributes for Stimulus controller
+- `hotkey_label(*keys)` - Platform-aware label (⌘ on Mac, Ctrl+ elsewhere)
+- `hotkey_hint(*keys)` - Renders `<kbd>` element with hide-on-touch class
+
+## How It Works
+
+This gem overrides `link_to`, `button_to`, and `button_tag` to support the `:hotkey` option. When you use `hotkey: :esc`, it extracts the option and merges the Stimulus data attributes into the element.
+
+If you prefer explicit control, use the `hotkey()` helper directly:
+
+```erb
+<%= link_to "Back", root_path, data: hotkey(:esc) %>
+```
+
+## License
+
+MIT

data/lib/generators/hotkeys_rails/install_generator.rb

@@ -0,0 +1,15 @@
+require "rails/generators"
+
+module HotkeysRails
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def copy_controller
+      copy_file "hotkey_controller.js", "app/javascript/controllers/hotkey_controller.js"
+    end
+
+    def copy_stylesheet
+      copy_file "hotkey.css", "app/assets/stylesheets/hotkey.css"
+    end
+  end
+end

data/lib/generators/hotkeys_rails/templates/hotkey.css

@@ -0,0 +1,16 @@
+kbd {
+  border: 1px solid currentColor;
+  border-radius: 0.3em;
+  box-shadow: 0 0.1em 0 currentColor;
+  font-family: ui-monospace, monospace;
+  font-size: 0.8em;
+  font-weight: 600;
+  opacity: 0.7;
+  padding: 0 0.4em;
+}
+
+@media (any-hover: none) {
+  .hide-on-touch {
+    display: none;
+  }
+}

data/lib/generators/hotkeys_rails/templates/hotkey_controller.js

@@ -0,0 +1,22 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  click(event) {
+    if (this.#shouldHandle(event)) {
+      event.preventDefault()
+      this.element.click()
+    }
+  }
+
+  focus(event) {
+    if (this.#shouldHandle(event)) {
+      event.preventDefault()
+      this.element.focus()
+    }
+  }
+
+  #shouldHandle(event) {
+    return !event.defaultPrevented &&
+           !event.target.closest("input, textarea, [contenteditable]")
+  }
+}

data/lib/hotkeys_rails/engine.rb

@@ -0,0 +1,9 @@
+module HotkeysRails
+  class Engine < ::Rails::Engine
+    initializer "hotkeys_rails.helper" do
+      ActiveSupport.on_load(:action_view) do
+        include HotkeysRails::Helper
+      end
+    end
+  end
+end

data/lib/hotkeys_rails/helper.rb

@@ -0,0 +1,99 @@
+module HotkeysRails
+  module Helper
+    # Returns data attributes for Stimulus hotkey controller
+    #
+    # hotkey(:esc)
+    # # => { controller: "hotkey", action: "keydown.esc@document->hotkey#click" }
+    #
+    # hotkey(:ctrl, :enter)
+    # # => { controller: "hotkey", action: "keydown.ctrl+enter@document->hotkey#click keydown.meta+enter@document->hotkey#click" }
+    #
+    def hotkey(*keys, action: :click)
+      keys = keys.flatten.map(&:to_s)
+
+      actions = if keys.include?("ctrl")
+        chord = keys.join("+")
+        meta_chord = keys.map { |k| k == "ctrl" ? "meta" : k }.join("+")
+        "keydown.#{chord}@document->hotkey##{action} keydown.#{meta_chord}@document->hotkey##{action}"
+      else
+        "keydown.#{keys.join("+")}@document->hotkey##{action}"
+      end
+
+      { controller: "hotkey", action: actions }
+    end
+
+    # Platform-aware label for keyboard shortcuts
+    #
+    # hotkey_label(:ctrl, :enter)
+    # # => "⌘Return" on Mac, "Ctrl+Enter" elsewhere
+    #
+    def hotkey_label(*keys)
+      keys.flatten.map do |key|
+        case key.to_s
+        when "ctrl"  then mac? ? "⌘" : "Ctrl+"
+        when "meta"  then mac? ? "⌘" : "Win+"
+        when "alt"   then mac? ? "⌥" : "Alt+"
+        when "shift" then mac? ? "⇧" : "Shift+"
+        when "enter" then mac? ? "Return" : "Enter"
+        when "esc"   then "Esc"
+        else key.to_s.upcase
+        end
+      # Mac symbols (⌘⌥⇧) don't need + separator, Windows modifiers do (Ctrl+, Alt+, Shift+)
+      # gsub removes trailing + from Mac symbols: "⌘+" -> "⌘"
+      end.join.gsub(/[⌘⌥⇧]\+/, &:chop)
+    end
+
+    # Renders <kbd> element with hide-on-touch class
+    #
+    # hotkey_hint(:ctrl, :s)
+    # # => <kbd class="hide-on-touch">⌘S</kbd>
+    #
+    def hotkey_hint(*keys)
+      content_tag(:kbd, hotkey_label(*keys), class: "hide-on-touch")
+    end
+
+    def link_to(name = nil, options = nil, html_options = nil, &block)
+      if block_given?
+        # link_to(url, html_options) { content }
+        html_options = extract_hotkey_option(options)
+        super(name, html_options, &block)
+      else
+        # link_to(name, url, html_options)
+        html_options = extract_hotkey_option(html_options)
+        super(name, options, html_options)
+      end
+    end
+
+    def button_to(name = nil, options = nil, html_options = nil, &block)
+      html_options = extract_hotkey_option(html_options)
+      super
+    end
+
+    def button_tag(content_or_options = nil, options = nil, &block)
+      if content_or_options.is_a?(Hash)
+        options = extract_hotkey_option(content_or_options)
+        super(nil, options, &block)
+      else
+        options = extract_hotkey_option(options)
+        super(content_or_options, options, &block)
+      end
+    end
+
+    private
+
+    def extract_hotkey_option(html_options)
+      return {} if html_options.nil?
+      html_options = html_options.dup
+
+      if hotkey_keys = html_options.delete(:hotkey)
+        html_options[:data] = (html_options[:data] || {}).merge(hotkey(*Array(hotkey_keys)))
+      end
+
+      html_options
+    end
+
+    def mac?
+      request.user_agent.to_s.include?("Mac")
+    end
+  end
+end

data/lib/hotkeys_rails/version.rb

@@ -0,0 +1,3 @@
+module HotkeysRails
+  VERSION = "0.1.0"
+end

data/lib/hotkeys_rails.rb

@@ -0,0 +1,6 @@
+require_relative "hotkeys_rails/version"
+require_relative "hotkeys_rails/helper"
+require_relative "hotkeys_rails/engine" if defined?(Rails::Engine)
+
+module HotkeysRails
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: hotkeys-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kieran Klaassen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: No dependencies. No configuration. Just HTML.
+email:
+- kieran@kieranklaassen.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/generators/hotkeys_rails/install_generator.rb
+- lib/generators/hotkeys_rails/templates/hotkey.css
+- lib/generators/hotkeys_rails/templates/hotkey_controller.js
+- lib/hotkeys_rails.rb
+- lib/hotkeys_rails/engine.rb
+- lib/hotkeys_rails/helper.rb
+- lib/hotkeys_rails/version.rb
+homepage: https://github.com/kieranklaassen/hotkeys-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kieranklaassen/hotkeys-rails
+  source_code_uri: https://github.com/kieranklaassen/hotkeys-rails
+  changelog_uri: https://github.com/kieranklaassen/hotkeys-rails/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Keyboard shortcuts for Hotwire apps
+test_files: []