Class: DocsKit::Shortcut

Inherits:
Object
  • Object
show all
Defined in:
lib/docs_kit/shortcut.rb

Overview

A parsed keyboard shortcut for the docs-search palette — one entry of DocsKit.configuration.search_shortcuts. A site writes shortcut STRINGS ("mod+k", "/", "s", "ctrl+shift+f") and this turns each into a key + modifier set that three places share: the config surface, the server-rendered hint (#label), and the docs-nav matcher (#to_h, serialized to JSON).

DocsKit::Shortcut.parse("mod+k").label   # => "Ctrl K"  (JS swaps to "⌘K" on mac)
DocsKit::Shortcut.parse("mod+k").to_h    # => { "key" => "k", "mod" => true, ... }

"mod" is the PLATFORM modifier — ⌘ on mac, Ctrl elsewhere — left abstract here (the server can't know the OS) and resolved in the browser by docs-nav. Use "mod" for the "primary command" chord so one config works on every platform; use explicit "ctrl"/"meta" only when you truly mean that physical key.

Modifier tokens (case-insensitive): mod, ctrl/control, shift, alt/option, cmd/command/meta. The final token is the key (single char or a named key like "escape"); a string with no key (e.g. "mod+") is unparseable and yields nil.

Constant Summary collapse

MODIFIER_ALIASES =

Canonical modifier token → the flag it sets.

{
  "mod" => :mod,
  "ctrl" => :ctrl, "control" => :ctrl,
  "shift" => :shift,
  "alt" => :alt, "option" => :alt,
  "cmd" => :meta, "command" => :meta, "meta" => :meta
}.freeze
LABEL_ORDER =

The order modifiers appear in a #label (matches the common convention).

%i[mod ctrl meta alt shift].freeze
MODIFIER_LABELS =

Human labels for the modifier flags in a #label. "mod" renders as the majority default "Ctrl"; docs-nav swaps it to "⌘" on mac.

{ mod: "Ctrl", ctrl: "Ctrl", meta: "Meta", alt: "Alt", shift: "Shift" }.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key, mods) ⇒ Shortcut

key: the final key token (lowercased). mods: a Set of modifier flag symbols.



56
57
58
59
60
 
# File 'lib/docs_kit/shortcut.rb', line 56

def initialize(key, mods)
  @key = key
  @mods = mods
  freeze
end

Instance Attribute Details

#key ⇒ Object (readonly)

Returns the value of attribute key.



53
54
55
 
# File 'lib/docs_kit/shortcut.rb', line 53

def key
  @key
end

Class Method Details

.parse(string) ⇒ Object

Parse one shortcut string → a Shortcut, or nil when there's no key to bind.



39
40
41
42
43
44
45
46
 
# File 'lib/docs_kit/shortcut.rb', line 39

def self.parse(string)
  tokens = string.to_s.downcase.split("+").map(&:strip).reject(&:empty?)
  key = tokens.pop
  return if key.nil? || MODIFIER_ALIASES.key?(key)

  mods = tokens.filter_map { |token| MODIFIER_ALIASES[token] }.to_set
  new(key, mods)
end

.parse_list(strings) ⇒ Object

Parse a list of shortcut strings, dropping any that don't parse.



49
50
51
 
# File 'lib/docs_kit/shortcut.rb', line 49

def self.parse_list(strings)
  Array(strings).filter_map { |string| parse(string) }
end

Instance Method Details

#==(other) ⇒ Object 



87
88
89
 
# File 'lib/docs_kit/shortcut.rb', line 87

def ==(other)
  other.is_a?(Shortcut) && to_h == other.to_h
end

#alt? ⇒ Boolean

Returns:

  • (Boolean) 


65
 
# File 'lib/docs_kit/shortcut.rb', line 65

def alt? = @mods.include?(:alt)

#ctrl? ⇒ Boolean

Returns:

  • (Boolean) 


63
 
# File 'lib/docs_kit/shortcut.rb', line 63

def ctrl? = @mods.include?(:ctrl)

#label ⇒ Object

The badge text: modifiers (in LABEL_ORDER) then the key. In a CHORD (with a modifier) a single-char key is uppercased for legibility ("mod+k" → "Ctrl K"); a BARE key is shown exactly as authored ("/", "s"). A named key (e.g. "escape") is left as-is either way.



72
73
74
75
 
# File 'lib/docs_kit/shortcut.rb', line 72

def label
  mods = LABEL_ORDER.select { |flag| @mods.include?(flag) }.map { |flag| MODIFIER_LABELS[flag] }.uniq
  (mods << key_label(chord: !mods.empty?)).join(" ")
end

#meta? ⇒ Boolean

Returns:

  • (Boolean) 


66
 
# File 'lib/docs_kit/shortcut.rb', line 66

def meta? = @mods.include?(:meta)

#mod? ⇒ Boolean

Returns:

  • (Boolean) 


62
 
# File 'lib/docs_kit/shortcut.rb', line 62

def mod? = @mods.include?(:mod)

#shift? ⇒ Boolean

Returns:

  • (Boolean) 


64
 
# File 'lib/docs_kit/shortcut.rb', line 64

def shift? = @mods.include?(:shift)

#to_h ⇒ Object Also known as: as_json

The shape docs-nav matches a keydown against (booleans always present so the JSON is uniform). String keys → clean JSON without symbol quoting.



79
80
81
82
83
84
 
# File 'lib/docs_kit/shortcut.rb', line 79

def to_h
  {
    "key" => key, "mod" => mod?, "ctrl" => ctrl?,
    "shift" => shift?, "alt" => alt?, "meta" => meta?
  }
end