htmx 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd7f8848ffbbb9b0dda865c24c70f45f875e34a12ddb61a85e440e40b10415c1
-  data.tar.gz: 071faebe65dddd6017d61e27d8a9c340830983a92b892d2082bcd58dbdce3a5b
+  metadata.gz: ee8016cd8fd02737e4aad162cb344f30e3b2b87a86758551ef7eb8af1e95987a
+  data.tar.gz: e8dbf7897d7a0acf0403c8e828aac1934c63f9c95843c0c7a6e81fba458bb393
 SHA512:
-  metadata.gz: dd59012b00b6e3e602276d0ef2915b550384bb891d18d2d5b5cde20c795dc1dfe7e6e833bd10ebcbb2c9f07c19f34404437a2e88bf7ae61a0ea30438d58c0a71
-  data.tar.gz: 1e396b2e3ba527fe84144f17e3e72a1b2a0b0ebf8685b904c8d1cac59e488faee72bff69cb91838ff6640596c2cdf2313b9bd681b8f9fde55fa2198f9aa695af
+  metadata.gz: b030354b85254e808ae6dd58d87f388a428a2a1997e89912647cf3a0bcdff2335b28dc98b788dfc8aa0b17d415df6957773c1658f8826cfd60c7ffc6f2214024
+  data.tar.gz: bdeed94be9d9ba5c4d794955fbe289616b946eebe531518fcb91a4bbe6dca32eec0fcb64bde9eb77f3c10f51c20ae741d9a49d1b4a270c8a0e8393669110a899

data/README.adoc

@@ -2,7 +2,7 @@
 :toclevels: 5
 :figure-caption!:
 
-:htmx_link: link:https://htmx.org[HTMX]
+:htmx_link: link:https://htmx.org[htmx]
 :hypermedia_systems_link: link:https://hypermedia.systems[Hypermedia Systems]
 :hanami_link: link:https://hanamirb.org[Hanami]
 :roda_link: link:http://roda.jeremyevans.net[Roda]
@@ -22,14 +22,12 @@ already in hand
 ...and from {hypermedia_systems_link}:
 
 ____
-The goal of [HTMX] is not less JavaScript, but less code, more readable and hypermedia-friendly code.
+The goal of [htmx] is not less JavaScript, but less code, more readable and hypermedia-friendly code.
 ____
 
 
 This gem provides native Ruby support for the {htmx_link} JavaScript library so you can build sophisticated web applications using pure Hypermedia REST APIs while avoiding unnecessary bloat and complexity common with the JavaScript ecosystem. By building upon the original foundations of Hypermedia REST APIs, you can build rich web applications with no additional JavaScript!
 
-At the moment, the functionality of this gem is still in the early stages of development but the goal of this gem is to aid with the development of {htmx_link} applications.
-
 💡 This is used with the {hanamismith_link} gem when building {hanami_link} applications. Even better, you can play with the link:https://github.com/bkuhlmann/hemo[Hanami demo application] to learn more. Enjoy!
 
 toc::[]
@@ -80,7 +78,7 @@ require "htmx"
 
 == Usage
 
-One of the first tasks you'll want to tackle, when working with the {htmx_link} library, is building HTMX specific HTML attributes. This can be accomplished by using the `.[]` method. For example, when implementing a {hanami_link} view part, you could use the following:
+One of the first tasks you'll want to tackle, when working with the {htmx_link} library, is building htmx specific HTML attributes. This can be accomplished by using the `.[]` method. For example, when implementing a {hanami_link} view part, you could use the following:
 
 [source,ruby]
 ----
@@ -101,11 +99,11 @@ The above would produce the following:
 </button>
 ----
 
-Notice the appropriate HTMX `hx-target` and `hx-delete` attributes are built which are compatible with the {htmx_link} library while not having to manually prefix each one of these attributes with the `hx-` prefix. You can even use symbols, strings, or a mix of both as well.
+Notice the appropriate htmx `hx-target` and `hx-delete` attributes are built which are compatible with the {htmx_link} library while not having to manually prefix each one of these attributes with the `hx-` prefix. You can use symbols, strings, or a mix of both as well.
 
 === HTML Attribute Prefixes
 
-As shown above, building HTMX attributes takes minimal effort but if you'd prefer the HTML `data-` prefix, which the {htmx_link} library supports, you can customize by using the following:
+As shown above, building htmx attributes takes minimal effort but if you'd prefer the HTML `data-` prefix, which the {htmx_link} library supports, you can customize by using the following:
 
 [source,ruby]
 ----
@@ -132,7 +130,7 @@ This would then produce the following HTML code:
 </button>
 ----
 
-As you can see, the `data-hx-target` and `data-hx-delete` keys are used. These are definitely more verbose than the `hx-` keys. By the way, the `HTMX::Prefixer` is called when using the HTMX `.[]` as shown earlier. This means the following are equivalent:
+As you can see, the `data-hx-target` and `data-hx-delete` keys are used. These are definitely more verbose than the `hx-` keys. By the way, the `HTMX::Prefixer` is called when using the htmx `.[]` as shown earlier. This means the following are equivalent:
 
 [source,ruby]
 ----
@@ -151,7 +149,7 @@ HTMX::Prefixer.new "bogus"
 # Invalid prefix: "bogus". Use: "hx" or "data-hx". (HTMX::Error)
 ----
 
-Some {htmx_link} attributes use dashes. For those situations, you can use strings for keys or underscored symbols to produce the correct HTMX syntax. Here's and example using both a string and symbol for keys:
+Some {htmx_link} attributes use dashes. For those situations, you can use strings for keys or underscored symbols to produce the correct htmx syntax. Here's an example using both a string and symbol for keys:
 
 [source,ruby]
 ----
@@ -161,15 +159,15 @@ HTMX["swap-oob" => true, push_url: "/demo/123"]
 
 === HTTP Headers
 
-When working with HTTP requests/responses, especially HTTP headers, there are a few objects that can parse and make the data easier to work with. These objects are named accordingly: request and response. Here's how to use them.
+When working with HTTP requests/responses, especially HTTP headers, there are a couple of methods that can parse and make the data easier to work with. Here's how to use them.
 
-==== Request
+==== Requests
 
-The request object allows you to obtain a {data_link} object to interact with when parsing link:https://htmx.org/reference/#request_headers[HTMX HTTP request headers]. Example:
+The request object allows you to obtain a {data_link} object to interact with when parsing link:https://htmx.org/reference/#request_headers[htmx HTTP request headers]. Example:
 
 [source,ruby]
 ----
-HTMX::Headers::Request.new
+HTMX.request
 
 # <data HTMX::Headers::Request boosted=nil,
 #                              current_url=nil,
@@ -186,11 +184,18 @@ Notice you get a {data_link} instance where all members have the `HX-` prefix re
 
 [source,ruby]
 ----
-HTMX::Headers::Request.for request.env
+HTMX.request "HTTP_HX_BOOSTED" => "true",
+             "HTTP_HX_CURRENT_URL" => "/demo",
+             "HTTP_HX_HISTORY_RESTORE_REQUEST" => "false",
+             "HTTP_HX_PROMPT" => "Yes",
+             "HTTP_HX_REQUEST" => "true",
+             "HTTP_HX_TARGET" => "demo",
+             "HTTP_HX_TRIGGER_NAME" => "save",
+             "HTTP_HX_TRIGGER" => "demo"
 
 # <data HTMX::Headers::Request boosted="true",
 #                              current_url="/demo",
-#                              history_restore_request=nil,
+#                              history_restore_request="false",
 #                              prompt="Yes",
 #                              request="true",
 #                              target="demo",
@@ -199,15 +204,60 @@ HTMX::Headers::Request.for request.env
 # >
 ----
 
-With the above, the `.for` method plucks out only the HTMX specific headers which may or may not have values. Extra header keys, which are not specific to {htmx_link}, are ignored.
+As you can see, this method only plucks out the htmx specific headers which may or may not have values. Extra header keys, which are not specific to {htmx_link}, are ignored.
+
+As an added convenience, you can use predicate methods for boolean values. Example:
 
-==== Response
+[source,ruby]
+----
+headers = HTMX.request "HTTP_HX_BOOSTED" => "true",
+                       "HTTP_HX_CURRENT_URL" => "/demo",
+                       "HTTP_HX_HISTORY_RESTORE_REQUEST" => "false",
+                       "HTTP_HX_PROMPT" => "Yes",
+                       "HTTP_HX_REQUEST" => "true",
+                       "HTTP_HX_TARGET" => "demo",
+                       "HTTP_HX_TRIGGER_NAME" => "save",
+                       "HTTP_HX_TRIGGER" => "demo"
 
-The response object allows you to obtain a {data_link} object to interact with when parsing link:https://htmx.org/reference/#response_headers[HTMX HTTP response headers]. Example:
+headers.boosted?                  # true
+headers.confirmed?                # true
+headers.history_restore_request?  # false
+headers.request?                  # true
+----
+
+Use of `#confirmed?` is the only unique predicate method since it answers a boolean based on the truthiness of the `HTTP_HX_PROMPT` header. For further details, see `String#truthy?` as provided by the link:https://alchemists.io/projects/refinements#_truthy[Refinements] gem.
+
+Due to `HTML.request` delegating to the `HTMX::Headers::Request`, this means you can use the object directly. Specifically, you can obtain the record, key, or header depending on your needs. Example:
 
 [source,ruby]
 ----
-HTMX::Headers::Response.new
+HTMX::Headers::Request.for(**headers)                 # Identical to `HTMX.request`.
+HTMX::Headers::Request.key_for "HTTP_HX_CURRENT_URL"  # :current_url
+HTMX::Headers::Request.header_for :current_url        # "HTTP_HX_CURRENT_URL"
+----
+
+Should you not want to use `HTMX::Headers::Request`, you can use the request predicate methods instead. Example:
+
+[source,ruby]
+----
+headers = {}
+
+HTMX.request! headers, boosted: true, prompt: "Yes"
+# {"HTTP_HX_BOOSTED" => true, "HTTP_HX_PROMPT" => "Yes"}
+
+HTMX.request? headers, :prompt, "Yes"  # true
+HTMX.request? headers, :prompt, "On"   # false
+----
+
+💡 `HTMX.request!` is designed to mutate your original headers. Unknown attributes are merged as is.
+
+==== Responses
+
+The response object allows you to obtain a {data_link} object to interact with when parsing link:https://htmx.org/reference/#response_headers[htmx HTTP response headers]. Example:
+
+[source,ruby]
+----
+HTMX.response
 
 # <data HTMX::Headers::Response location=nil,
 #                               push_url=nil,
@@ -226,7 +276,16 @@ Notice you get a {data_link} instance where all members have the `HX-` prefix re
 
 [source,ruby]
 ----
-HTMX::Headers::Response.for response.headers
+HTMX.response "HX-Location" => "/",
+              "HX-Push-Url" => "/demo",
+              "HX-Redirect" => "/demo",
+              "HX-Refresh" => "true",
+              "HX-Replace-Url" => "/demo",
+              "HX-Reswap" => "none",
+              "HX-Retarget" => ".demo",
+              "HX-Trigger" => "demo",
+              "HX-Trigger-After-Settle" => "demo",
+              "HX-Trigger-After-Swap" => "demo"
 
 # <data HTMX::Headers::Response location="/",
 #                               push_url="/demo",
@@ -241,11 +300,44 @@ HTMX::Headers::Response.for response.headers
 # >
 ----
 
-With the above, the `.for` method plucks out only the HTMX specific headers which may or may not have values. Extra header keys, which are not specific to {htmx_link}, are ignored.
+As you can see, this method only plucks out the htmx specific headers which may or may not have values. Extra header keys, which are not specific to {htmx_link}, are ignored.
+
+There is also a refresh predicate method that'll answer a boolean for convenience. Example:
+
+[source,ruby]
+----
+headers = HTMX.response "HX-Refresh" => "true"
+
+headers.refresh? # true
+----
+
+Due to `HTML.response` delegating to the `HTMX::Headers::Response`, this means you can use the object directly. Specifically, you can obtain the record, key, or header depending on your needs. Example:
+
+[source,ruby]
+----
+HTMX::Headers::Response.for(**headers)         # Identical to `HTMX.response`.
+HTMX::Headers::Response.key_for "HX-Location"  # :location
+HTMX::Headers::Response.header_for :location   # "HX-Location"
+----
+
+Should you not want to use `HTMX::Headers::Response`, you can use the response predicate methods instead. Example:
+
+[source,ruby]
+----
+headers = {}
+
+HTMX.response! headers, location: "/", push_url: "/test"
+# {"HX-Location" => "/", "HX-Push-Url" => "/test"}
+
+HTMX.response? headers, :push_url, "/test"   # true
+HTMX.response? headers, :push_url, "/other"  # false
+----
+
+💡 `HTMX.response!` is designed to mutate your original headers. Unknown attributes are merged as is.
 
 === Errors
 
-As you've probably picked up by now, any/all errors issued by this gem will be an instance of the `HTMX::Error` class which inherits from `StandardError`. you can use this classification to catch and deal with these errors in your own implementation as desired.
+Any/all errors issued by this gem will be an instance of the `HTMX::Error` class which inherits from `StandardError`. You can use this classification to catch and deal with these errors in your own implementation as desired.
 
 == Development
 

data/htmx.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "htmx"
-  spec.version = "2.3.0"
+  spec.version = "2.4.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/htmx"

data/lib/htmx/headers/request.rb

@@ -1,36 +1,20 @@
 # frozen_string_literal: true
 
+require "refinements/string"
+
 module HTMX
   module Headers
-    REQUEST_KEY_MAP = {
-      "HTTP_HX_BOOSTED" => :boosted,
-      "HTTP_HX_CURRENT_URL" => :current_url,
-      "HTTP_HX_HISTORY_RESTORE_REQUEST" => :history_restore_request,
-      "HTTP_HX_PROMPT" => :prompt,
-      "HTTP_HX_REQUEST" => :request,
-      "HTTP_HX_TARGET" => :target,
-      "HTTP_HX_TRIGGER_NAME" => :trigger_name,
-      "HTTP_HX_TRIGGER" => :trigger
-    }.freeze
-
     # Models the supported HTMX request headers.
-    Request = Data.define(
-      :boosted,
-      :current_url,
-      :history_restore_request,
-      :prompt,
-      :request,
-      :target,
-      :trigger_name,
-      :trigger
-    ) do
-      def self.for(key_map: REQUEST_KEY_MAP, **attributes)
+    Request = Data.define(*REQUEST_MAP.keys) do
+      using Refinements::String
+
+      def self.for(key_map: REQUEST_MAP.invert, **attributes)
         new(**attributes.slice(*key_map.keys).transform_keys!(key_map))
       end
 
-      def self.key_for(header, key_map: REQUEST_KEY_MAP) = key_map.fetch header
+      def self.key_for(header, key_map: REQUEST_MAP.invert) = key_map.fetch header
 
-      def self.header_for(key, key_map: REQUEST_KEY_MAP.invert) = key_map.fetch key
+      def self.header_for(key, key_map: REQUEST_MAP) = key_map.fetch key
 
       def initialize boosted: nil,
                      current_url: nil,
@@ -42,6 +26,14 @@ module HTMX
                      trigger: nil
         super
       end
+
+      def boosted? = boosted == "true"
+
+      def confirmed? = prompt ? prompt.truthy? : false
+
+      def history_restore_request? = history_restore_request == "true"
+
+      def request? = request == "true"
     end
   end
 end

data/lib/htmx/headers/response.rb

@@ -2,39 +2,15 @@
 
 module HTMX
   module Headers
-    RESPONSE_KEY_MAP = {
-      "HX-Location" => :location,
-      "HX-Push-Url" => :push_url,
-      "HX-Redirect" => :redirect,
-      "HX-Refresh" => :refresh,
-      "HX-Replace-Url" => :replace_url,
-      "HX-Reswap" => :reswap,
-      "HX-Retarget" => :retarget,
-      "HX-Trigger" => :trigger,
-      "HX-Trigger-After-Settle" => :trigger_after_settle,
-      "HX-Trigger-After-Swap" => :trigger_after_swap
-    }.freeze
-
     # Models the supported HTMX response headers.
-    Response = Data.define(
-      :location,
-      :push_url,
-      :redirect,
-      :refresh,
-      :replace_url,
-      :reswap,
-      :retarget,
-      :trigger,
-      :trigger_after_settle,
-      :trigger_after_swap
-    ) do
-      def self.for(key_map: RESPONSE_KEY_MAP, **attributes)
+    Response = Data.define(*RESPONSE_MAP.keys) do
+      def self.for(key_map: RESPONSE_MAP.invert, **attributes)
         new(**attributes.slice(*key_map.keys).transform_keys!(key_map))
       end
 
-      def self.key_for(header, key_map: RESPONSE_KEY_MAP) = key_map.fetch header
+      def self.key_for(header, key_map: RESPONSE_MAP.invert) = key_map.fetch header
 
-      def self.header_for(key, key_map: RESPONSE_KEY_MAP.invert) = key_map.fetch key
+      def self.header_for(key, key_map: RESPONSE_MAP) = key_map.fetch key
 
       def initialize location: nil,
                      push_url: nil,
@@ -48,6 +24,8 @@ module HTMX
                      trigger_after_swap: nil
         super
       end
+
+      def refresh? = refresh == "true"
     end
   end
 end

data/lib/htmx.rb

@@ -11,6 +11,30 @@ end
 
 # Main namespace.
 module HTMX
+  REQUEST_MAP = {
+    boosted: "HTTP_HX_BOOSTED",
+    current_url: "HTTP_HX_CURRENT_URL",
+    history_restore_request: "HTTP_HX_HISTORY_RESTORE_REQUEST",
+    prompt: "HTTP_HX_PROMPT",
+    request: "HTTP_HX_REQUEST",
+    target: "HTTP_HX_TARGET",
+    trigger_name: "HTTP_HX_TRIGGER_NAME",
+    trigger: "HTTP_HX_TRIGGER"
+  }.freeze
+
+  RESPONSE_MAP = {
+    location: "HX-Location",
+    push_url: "HX-Push-Url",
+    redirect: "HX-Redirect",
+    refresh: "HX-Refresh",
+    replace_url: "HX-Replace-Url",
+    reswap: "HX-Reswap",
+    retarget: "HX-Retarget",
+    trigger: "HX-Trigger",
+    trigger_after_settle: "HX-Trigger-After-Settle",
+    trigger_after_swap: "HX-Trigger-After-Swap"
+  }.freeze
+
   def self.loader registry = Zeitwerk::Registry
     @loader ||= registry.loaders.each.find { |loader| loader.tag == File.basename(__FILE__, ".rb") }
   end
@@ -19,4 +43,18 @@ module HTMX
     @prefixer ||= Prefixer.new
     @prefixer.call(...)
   end
+
+  def self.request(**) = Headers::Request.for(**)
+
+  def self.request!(headers, **attributes) = headers.merge! attributes.transform_keys!(REQUEST_MAP)
+
+  def self.request?(headers, key, value) = headers[REQUEST_MAP[key]] == value
+
+  def self.response(**) = Headers::Response.for(**)
+
+  def self.response!(headers, **attributes)
+    headers.merge! attributes.transform_keys!(RESPONSE_MAP)
+  end
+
+  def self.response?(headers, key, value) = headers[RESPONSE_MAP[key]] == value
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: htmx
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -104,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: An augmenter and companion to the HTMX JavaScript library.
 test_files: []