coupdoeil 1.0.0.pre.alpha.4 → 1.0.0.pre.alpha.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12d3b61e5972da42e39ac301ef83d8a20a8ff02decc9640385481f60707a9e32
-  data.tar.gz: 7c90f6aea07ee9af9fc2b1392b42d543c2db1a0fae268f7720819e439ac3803d
+  metadata.gz: 8cf1f24d6bf5ecba5a2a0487f53df3ed465135370e1c31c92d011bab992e0329
+  data.tar.gz: 741a0143b46f6a624a47833a2bd44eb772d8bb4416db47e43a1f5dd822e781a8
 SHA512:
-  metadata.gz: 205c669038b3603c5e261555493a0398891ef7cdcc19ddbfdf5118fb4809af286fb74c2ef5b845a4a1a0e891ee36f9715552c6485406495ef60e0acaf6b24e89
-  data.tar.gz: 6e598fc91d2a4abc3dba804b08d992e030eb5c7339099bbb2423c544e41b469d7b709b6540ce4cf68567495abaec8af704a7ddbcebd75814509fedce68988e00
+  metadata.gz: df2e1ccc9312186ed3cc9a3751f4d07c6c0c9b2ad91e02071c3b68b79586f0d2050581dd7afd2784d13c1204485c4c2ec6d775bcf3a13b1a98f9ff523273faea
+  data.tar.gz: 188140fe0cc420094febd3d468fc75b7c3c5d8026dae3c3d10194485f7b359d66046f7aff93a9a56cfa8f797d5a3046215e65a33119e71251cedeed62979bd6a

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.5"
 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.5
 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