phlex-reactive 0.14.4 → 0.15.0

data/lib/phlex/reactive/shortcut.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # A page-level keyboard shortcut (issue #357), the value behind
+    # `on(..., shortcut:)` and `on_client(:keydown, ..., shortcut:)`.
+    #
+    #   Shortcut.parse("mod+z")                          # String form
+    #   Shortcut.parse({ keys: "esc", in_editable: true }) # Hash form
+    #
+    # `mod` is meta on Apple platforms and ctrl elsewhere. Stimulus has no
+    # "either" modifier (its key filter compares all four modifier flags
+    # exactly), so a `mod` chord renders TWO descriptors, a meta twin and a ctrl
+    # twin, and the client runs only the twin for its platform. Stimulus keeps
+    # the key filtering; the client adds the platform check, the editable-target
+    # guard and preventDefault.
+    #
+    # Validation is loud, at render: Stimulus reports an unknown key token by
+    # throwing at keypress time, which is too late to notice.
+    class Shortcut
+      MODIFIERS = %w[mod meta ctrl alt shift].freeze
+      # Stimulus's default keyMappings: the named keys plus a-z and 0-9.
+      NAMED_KEYS = %w[enter tab esc space up down left right home end page_up page_down].freeze
+      HASH_KEYS = %i[keys in_editable].freeze
+
+      private_constant :MODIFIERS, :NAMED_KEYS, :HASH_KEYS
+
+      attr_reader :keys
+
+      def self.parse(spec)
+        case spec
+        when String then new(spec, in_editable: false)
+        when Hash then from_hash(spec)
+        else
+          raise ArgumentError,
+            "shortcut: takes a String (\"mod+z\") or a Hash ({ keys: \"esc\", in_editable: true }), " \
+            "got #{spec.inspect}"
+        end
+      end
+
+      def self.from_hash(spec)
+        keys = spec[:keys]
+        in_editable = spec.fetch(:in_editable, false)
+        unless (spec.keys - HASH_KEYS).empty? && keys.is_a?(String)
+          raise ArgumentError,
+            "shortcut: as a Hash takes keys: (a String, e.g. \"esc\") and an optional " \
+            "in_editable: (true/false), got #{spec.inspect}"
+        end
+        unless [true, false].include?(in_editable)
+          raise ArgumentError, "shortcut: in_editable: is true or false, got #{in_editable.inspect}"
+        end
+
+        new(keys, in_editable:)
+      end
+      private_class_method :from_hash
+
+      def initialize(keys, in_editable:)
+        tokens = keys.downcase.split("+").map(&:strip)
+        @in_editable = in_editable
+        @keys = canonical(keys, tokens).freeze
+        freeze
+      end
+
+      # The Stimulus key filters to bind: the meta and ctrl twins for a `mod`
+      # chord, else the chord itself.
+      def filters
+        return [@keys] unless @keys.start_with?("mod+")
+
+        %w[meta ctrl].map { @keys.sub("mod", it) }
+      end
+
+      # The wire form the client reads (data-reactive-shortcut-param, or the
+      # on_client record's "shortcut"): the canonical String, or the Hash form
+      # when the shortcut also fires inside editable targets.
+      def param = @in_editable ? { "keys" => @keys, "inEditable" => true } : @keys
+
+      private
+
+      def canonical(source, tokens)
+        mods = tokens.select { MODIFIERS.include?(it) }
+        key = tokens - MODIFIERS
+        validate!(source, mods, key)
+        [*MODIFIERS.select { mods.include?(it) }, key.first].join("+")
+      end
+
+      def validate!(source, mods, key)
+        raise ArgumentError, "shortcut: #{source.inspect} must name exactly one key (e.g. \"mod+z\")" unless key.size == 1
+        raise ArgumentError, "shortcut: #{source.inspect} repeats a modifier" unless mods.uniq.size == mods.size
+        if mods.include?("mod") && mods.intersect?(%w[meta ctrl])
+          raise ArgumentError,
+            "shortcut: #{source.inspect} combines mod with meta/ctrl — mod already is meta on Apple " \
+            "platforms and ctrl elsewhere"
+        end
+        return if known_key?(key.first)
+
+        raise ArgumentError,
+          "shortcut: #{source.inspect} has an unknown key #{key.first.inspect} — use a letter, a digit, " \
+          "or one of #{NAMED_KEYS.join(", ")} (Stimulus's default key map; custom keyMappings are not " \
+          "known on the server, bind those with event: and window: instead)"
+      end
+
+      def known_key?(key) = NAMED_KEYS.include?(key) || key.match?(/\A[a-z0-9]\z/)
+    end
+  end
+end

data/lib/phlex/reactive/streamable.rb

@@ -37,10 +37,13 @@ module Phlex
       # Focus ops steal focus in every subscriber's tab (issue #96); submit
       # (issue #226) would force-submit every subscriber's form; paste_into
       # (issue #228) would read every subscriber's clipboard; check_group
-      # (issue #342) would tick or clear every subscriber's selection. They
+      # (issue #342) would tick or clear every subscriber's selection; presence
+      # (issue #358) would write every subscriber's presence state. They
       # belong to the actor's own reply (reply.js) or gesture (on_client / a
       # reducer's $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
-      BROADCAST_REFUSED_OPS = %w[focus focus_first submit paste_into persist_state persist_clear check_group].freeze
+      BROADCAST_REFUSED_OPS = %w[
+        focus focus_first submit paste_into persist_state persist_clear check_group presence
+      ].freeze
 
       # The broadcast_to verb kwargs (issue #185) → their Turbo stream action.
       # SELF-TARGETING verbs derive the target from the component's #id (require a
@@ -193,7 +196,8 @@ module Phlex
               "broadcast_to(js:) refuses actor-only op(s) #{refused.join(", ")} — broadcasting focus " \
               "steals it in every subscriber's tab; broadcasting submit force-submits every " \
               "subscriber's form; broadcasting paste_into reads every subscriber's clipboard; " \
-              "broadcasting check_group ticks or clears every subscriber's selection. " \
+              "broadcasting check_group ticks or clears every subscriber's selection; " \
+              "broadcasting presence writes every subscriber's presence state. " \
               "These are actor concerns (reply.js / on_client / $ops)."
           end
 

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.14.4"
+    VERSION = "0.15.0"
   end
 end

data/lib/phlex/reactive.rb

@@ -66,6 +66,12 @@ module Phlex
     # authorization method / mark_authorized! / declare skip_verify_authorized).
     class AuthorizationNotVerified < Error; end
 
+    # Raised when a feature needs a transport capability the app does not have
+    # (issue #358: reactive_presence without a pgbus that keys presence by
+    # connection). Loud at first render, with the requirement in the message —
+    # there is no degraded mode to fall back to.
+    class ConfigurationError < Error; end
+
     # Purpose string bound into every identity token's signature so a token
     # minted for phlex-reactive can't be replayed against another verifier use.
     IDENTITY_PURPOSE = "phlex-reactive/identity"
@@ -1283,6 +1289,10 @@ loader.do_not_eager_load("#{__dir__}/reactive/engine.rb")
 # boot. The constant autoloads on first reference, which only happens behind
 # Phlex::Reactive.defer_push_capable? (that gate requires ActiveJob::Base).
 loader.do_not_eager_load("#{__dir__}/reactive/deferred_render_job.rb")
+# The presence roster's render job (issue #358), for the same reason: it is
+# only referenced behind Phlex::Reactive::Presence.capable? (which requires
+# ActiveJob::Base).
+loader.do_not_eager_load("#{__dir__}/reactive/presence_render_job.rb")
 loader.setup
 
 require "phlex/reactive/engine" if defined?(Rails::Engine)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.14.4
+  version: 0.15.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -158,6 +158,9 @@ files:
 - app/javascript/phlex/reactive/features/persist.js
 - app/javascript/phlex/reactive/features/persist.min.js
 - app/javascript/phlex/reactive/features/persist.min.js.map
+- app/javascript/phlex/reactive/features/presence.js
+- app/javascript/phlex/reactive/features/presence.min.js
+- app/javascript/phlex/reactive/features/presence.min.js.map
 - app/javascript/phlex/reactive/features/sortable.js
 - app/javascript/phlex/reactive/features/sortable.min.js
 - app/javascript/phlex/reactive/features/sortable.min.js.map
@@ -195,6 +198,7 @@ files:
 - lib/phlex/reactive/component/helpers.rb
 - lib/phlex/reactive/component/identity.rb
 - lib/phlex/reactive/component/lazy.rb
+- lib/phlex/reactive/component/presence_declaration.rb
 - lib/phlex/reactive/component/registry.rb
 - lib/phlex/reactive/component/selection.rb
 - lib/phlex/reactive/component/sortable.rb
@@ -222,10 +226,16 @@ files:
 - lib/phlex/reactive/param_schema.rb
 - lib/phlex/reactive/pending.rb
 - lib/phlex/reactive/pending/markup.rb
+- lib/phlex/reactive/presence.rb
+- lib/phlex/reactive/presence/component_methods.rb
+- lib/phlex/reactive/presence/roster.rb
+- lib/phlex/reactive/presence/transport.rb
+- lib/phlex/reactive/presence_render_job.rb
 - lib/phlex/reactive/reply.rb
 - lib/phlex/reactive/response.rb
 - lib/phlex/reactive/settle.rb
 - lib/phlex/reactive/settles.rb
+- lib/phlex/reactive/shortcut.rb
 - lib/phlex/reactive/show_conditions.rb
 - lib/phlex/reactive/stream.rb
 - lib/phlex/reactive/streamable.rb