coupdoeil 1.0.0.pre.alpha.4 → 1.0.0.pre.alpha.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12d3b61e5972da42e39ac301ef83d8a20a8ff02decc9640385481f60707a9e32
-  data.tar.gz: 7c90f6aea07ee9af9fc2b1392b42d543c2db1a0fae268f7720819e439ac3803d
+  metadata.gz: b2b90ff5e94bfa7b2b0653c2dcb7f97846cf0b8e76602c7c6fa275f3c5d8be90
+  data.tar.gz: c28079fdcf56d63cb67e7d78692e2830272b977983965201d2ae1a28739c654e
 SHA512:
-  metadata.gz: 205c669038b3603c5e261555493a0398891ef7cdcc19ddbfdf5118fb4809af286fb74c2ef5b845a4a1a0e891ee36f9715552c6485406495ef60e0acaf6b24e89
-  data.tar.gz: 6e598fc91d2a4abc3dba804b08d992e030eb5c7339099bbb2423c544e41b469d7b709b6540ce4cf68567495abaec8af704a7ddbcebd75814509fedce68988e00
+  metadata.gz: 2c0af99048fb580402bd29858e0881e4facef9f8ee1401f296dc3a35c7e3d1b9ad970decf069ee6da5972fbd9b12c1c8d928cbe618ea939d254d0f1068c1e7cf
+  data.tar.gz: 52a24662d6c205377095e6a1be1cb805b46e8d2e70d0a14c4cdfe98fbc898e286113b81d13abdc6fbe44647abef4436fab082adf0ade014159ec50f8cddfb820

data/README.md

@@ -1,6 +1,88 @@
 # Coupdoeil
 A framework to easily handle hovercards.
 
-## Usage
+## Documentation
+See [coupdoeil.org](https://coupdoeil.org) for full documentation.
 
-See [documentation](https://coupdoeil.org)
+## Overview
+
+### What is a Coupdoeil::Hovercard?
+
+Hovercards are ruby objects used to easily build powerful popups (from basic tooltips to full dialog hovercards).
+They are mostly inspired by GitHub hovercards (like hovering on a link to a repo, or a username)
+and Wikipedia popups (when hovering a link to another wikipedia article).
+
+Click to toggle examples
+<details>
+    <summary><i>A quick look on a contact details</i></summary>
+    <img src="https://coupdoeil.org/overview-example.gif" alt="hovercard example" />
+</details>
+<details>
+    <summary><i>A form in a popup</i></summary>
+    <img src="https://coupdoeil.org/overview-example-2.gif" alt="hovercard example" />
+</details>
+[See more use-cases](https://coupdoeil.org/case-studies.html)
+
+The current implementation takes inspiration from both ViewComponent and ActionMailer, to make it as easy as possible to use while offering a wide range of possibilities.
+
+```ruby
+# app/hovercards/contact_hovercard.rb
+class ContactHovercard < Coupdoeil::Hovercard
+  def details
+    @contact = params[:contact]
+  end
+end
+```
+
+```erb
+<%# app/hovercards/contact_hovercard/details.html.erb %>
+<div class="contact-details">
+  <%= image_tag @contact.avatar %>
+  <strong><%= @contact.first_name %> <%= @contact.last_name %></strong>
+  <!-- ... -->
+</div>
+```
+
+Which is embedded by doing so:
+
+```erb
+<%# app/views/messages/show.html.erb %>
+<div>
+    <span>From: </span>
+    <%= coupdoeil_hovercard_tag ContactHovercard.with(contact: @contact).details do %>
+      <span class="contact-pill"><%= @contact.email %></span>
+    <% end %>
+</div>
+```
+
+### Why use Coupdoeil hovercards?
+
+The concept of 'quick look' allowed by hovercards can really improve UX by avoiding the need to navigate to another page and back again just to check summary for a resource.
+It also permits to hiding until use some parts of UI like small forms, or quick actions in a list of elements.
+
+The most common examples of such hovercard are on GitHub (when hovering over a link to a repo, user profile, a PR, etc.) or on
+Wikipedia (when hovering over a link to another article).
+
+While basic popups implementations can be made with simple helpers, data-attributes, and a bit of JavaScript,
+it tends to get too complex over time and often not handle enough edge-cases to be used everywhere it could improve UX.
+
+`Coupdoeil::Hovercard` offers a way to easily encapsulate and power up hovercards rendering logic.
+It allows a lot of customization possibilities (see [options](https://coupdoeil.org/opts.html)) and promotes re-usability by using an API similar to
+parameterized ActionMailer (see [Why does it look like a mailer?](https://coupdoeil.org/architectural-decisions.html#why-does-it-look-like-a-mailer)).
+
+This gem also tries to handle all known issues of such hovercards, such as
+the user's mouse quickly leaving and re-entering hovercard without closing it,
+preventing opening of an hovercard if mouse did not stop on it, etc.
+
+### Performances
+
+By default, an hovercard content is not loaded until it is needed.
+It means the DOM is not cluttered with 'maybe to be used' HTML, hidden in template tags or data-attributes.
+However, params have to be present in HTML so they are sent for rendering the hovercard (eg: a record id),
+so try passing as few as required to build it later during render.
+Also, hovercards are cached so the fetch happens only the first time an hovercard is open.
+
+When needed, hovercards can still be preloaded and included in DOM on initial page load. See [preload option](https://coupdoeil.org/options/loading.html).
+
+## Licence 
+Coupdoeil is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT)

data/lib/coupdoeil/version.rb

@@ -1,3 +1,3 @@
 module Coupdoeil
-  VERSION = "1.0.0-alpha.4"
+  VERSION = "1.0.0-alpha.6"
 end

data/lib/coupdoeil.rb

@@ -2,5 +2,5 @@ require "coupdoeil/version"
 require "coupdoeil/engine"
 
 module Coupdoeil
-  # Your code goes here...
+  extend ActiveSupport::Autoload
 end

data/lib/generators/coupdoeil/install/install_generator.rb

@@ -19,7 +19,7 @@ class Coupdoeil::InstallGenerator < Rails::Generators::Base
     if Rails.root.join("config/importmap.rb").exist?
       append_to_importmap
     elsif Rails.root.join("package.json").exist?
-      raise "package.json not supported yet!"
+      add_with_node
     else
       puts "You must either be running with node (package.json) or importmap-rails (config/importmap.rb) to use this gem."
     end
@@ -42,6 +42,18 @@ class Coupdoeil::InstallGenerator < Rails::Generators::Base
     append_to_file "app/javascript/application.js", %(import "coupdoeil"\n)
   end
 
+  def add_with_node
+    if Rails.root.join("app/javascript/application.js").exist?
+      say "Import Coupdoeil"
+      append_to_file "app/javascript/application.js", %(import "coupdoeil"\n)
+    else
+      say "You must import coupdoeil in your JavaScript entrypoint file", :red
+    end
+
+    say "Install Coupdoeil"
+    run "yarn add coupdoeil"
+  end
+
   def import_stylesheet
     puts "To use Coupdoeil hovercard style, add to your layout's head:"
     puts ""

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: coupdoeil
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha.4
+  version: 1.0.0.pre.alpha.6
 platform: ruby
 authors:
 - PageHey
 bindir: bin
 cert_chain: []
-date: 2025-05-22 00:00:00.000000000 Z
+date: 2025-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -85,6 +85,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Easy and powerful hovercard system for Ruby On Rails.
 email:
 - pagehey@pm.me