pop_frame 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c97cbc621cda0a6f45a67e3eefd506adc5a5f3afa77d8f772b046e47a9eeb6f5
+  data.tar.gz: f897c73e4d3d9dc7a56bbe31456d6c3ef9794fbd9908ad2fb1c011f809b04419
+SHA512:
+  metadata.gz: 3cc96e33d4d42113337b7e158f67a6069c076bcd382f780bed30be103457e26709ad636baa80c73b67dd4856138c17a7a826dd0e87d3ea37a6231f7b2746d245
+  data.tar.gz: 16a5bdd0e5e4c0f8c470bda16dbfc10f1c3e4f7a33a51d3337ffd1adaf3dd33152f9a108b70c407d7387e5f44b90444baaed7d3b6cd1b607517d9d31f3e998c5

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+## [v0.1.0] Oct 9, 2026
+
+- `pop_frame_tag(id, src) { trigger }` renders a button that opens a native popover holding a Turbo
+  Frame. The frame loads `src` (anything `url_for` takes) the first time the popover opens, and
+  reloads in place on a morph refresh, staying open. `pop_frame.css` anchors the popover to its
+  button.
+
+[v0.1.0]: https://github.com/RoleModel/pop-frame/releases/tag/v0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 RoleModel Software
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,169 @@
+# Pop Frame
+
+<div>
+  <img src="https://github.com/RoleModel/pop-frame/actions/workflows/ci.yml/badge.svg" alt="CI">
+  <img src="https://img.shields.io/gem/v/pop_frame" alt="Gem Version">
+</div>
+<br/>
+
+A `turbo-frame` in a native popover, loaded the first time it opens.
+
+![title image](title_image.png)
+
+Popover libraries were built for browsers that couldn't open a popover, position it, or keep it
+from being clipped. Browsers can do all of that now. A JavaScript popover also has to be re-wired
+every time Turbo morphs the page; a native one is just HTML, so a morph leaves it alone.
+
+Pop Frame is one view helper and five lines of CSS. The browser handles the rest:
+
+- The [Popover API][mdn-popover] opens and closes it, closes it on Escape or an outside click, and
+  keeps `aria-expanded` up to date.
+- The [top layer][mdn-top-layer] keeps it above everything, so an `overflow` ancestor can't clip it.
+- [CSS anchor positioning][mdn-anchor] places it under the button that opened it.
+- Turbo loads the frame and refreshes it when the page morphs.
+
+There's no JavaScript to install, configure, or keep alive across morphs.
+
+## Installation
+
+```bash
+bundle add pop_frame
+```
+
+Then include the stylesheet. With Propshaft or Sprockets, add it to your layout:
+
+```erb
+<%= stylesheet_link_tag 'pop_frame' %>
+```
+
+If a JavaScript bundler builds your CSS (cssbundling-rails, webpack), copy
+[`pop_frame.css`](app/assets/stylesheets/pop_frame.css) into your own stylesheets instead.
+
+## Basic Usage
+
+Give `pop_frame_tag` an id for the frame and where to load it from. The block becomes the button's
+content. (Examples use [slim] syntax.)
+
+```ruby
+= pop_frame_tag dom_id(person, :week), person_week_path(person), class: 'btn' do
+  | This week
+```
+
+which renders
+
+```html
+<button type="button" popovertarget="person_1_week_popover" class="btn">This week</button>
+<div id="person_1_week_popover" class="pop-frame" popover="auto">
+  <turbo-frame id="person_1_week" src="/people/1/week" loading="lazy" refresh="morph">Loading…</turbo-frame>
+</div>
+```
+
+The response must contain a `turbo-frame` with the same id, as with any Turbo Frame:
+
+```ruby
+= turbo_frame_tag dom_id(@person, :week) do
+  = render 'people/week', person: @person
+```
+
+Nothing is fetched until the popover first opens. After that, it keeps its content between opens.
+Links and forms inside it navigate the frame, just as they would in any other `turbo-frame`.
+
+> [!TIP]
+> Each frame needs an id that's unique on the page. `dom_id` with a suffix, as above, is an easy way
+> to get one, even when the same record shows up in several places.
+
+## Options
+
+`pop_frame_tag(id, src, loading: 'Loading…', **button_options, &block)`
+
+| Argument         | Description                                                                         | Default      |
+| ---------------- | ----------------------------------------------------------------------------------- | ------------ |
+| `id`             | The frame's id. The popover's id is derived from it (`"#{id}_popover"`).            | required     |
+| `src`            | Where the frame loads from. Takes anything [`url_for`][url-for] does.               | required     |
+| `loading:`       | Shown until the frame loads: plain text, or markup like `render 'spinner'`.         | `'Loading…'` |
+| `button_options` | HTML options for the button (`class:`, `data:`, `aria:` and so on).                 | `{}`         |
+| `&block`         | The button's content.                                                               | required     |
+
+## Styling
+
+The stylesheet only positions the popover. Its look is up to you:
+
+```css
+/* the popover */
+.pop-frame { padding: 1rem; border-radius: 8px; box-shadow: 0 8px 24px #0002; }
+
+/* its button, while open */
+.btn:has(+ :popover-open) { outline: 2px solid royalblue; }
+
+/* the frame, while it loads */
+.pop-frame turbo-frame[busy] { opacity: 0.5; }
+```
+
+The popover opens below its button, aligned to the button's start edge, and flips to fit when it's
+near the edge of the screen. To place it differently, override `position-area` and
+`position-try-fallbacks` on `.pop-frame[popover]`.
+
+## Page Refreshes
+
+Pop Frame is built for pages that [refresh with morphing][turbo-morph]. When a save elsewhere on the
+page (or a broadcast) morphs it:
+
+- An open popover **stays open**, and its content is swapped for the fresh version as soon as it
+  arrives, with no flash of the loading state.
+- Popovers that were opened earlier and are now closed reload in the background, so they're current
+  the next time they open.
+- Popovers that were never opened stay unloaded.
+
+> [!NOTE]
+> Morph refreshes need `turbo_refreshes_with method: :morph` in the page's `<head>`. That helper
+> writes to `content_for(:head)`, so your layout has to `yield :head`. If it doesn't, use
+> `turbo_refresh_method_tag :morph` in the layout instead.
+
+## Browser Support
+
+The popover itself works anywhere the Popover API does (Baseline 2024). Positioning it under its
+button needs CSS anchor positioning: Chrome 125, Safari 26, Firefox 147. Older browsers still open
+the popover, just centered on the screen by the browser's default popover styles.
+
+Opening a popover from your own JavaScript with `showPopover()` leaves it with nothing to anchor to.
+Pass the button as its source, `popover.showPopover({ source: button })`, to keep it in place.
+
+## System Tests
+
+Because it's ordinary HTML, Capybara needs nothing special:
+
+```ruby
+click_on 'This week'
+
+within '.pop-frame' do
+  assert_text 'Week of Oct 12'
+end
+```
+
+## Development
+
+After cloning the repository, install dependencies with `bundle install`.
+
+Run the test suite with `bin/rails test:all`. Its system tests drive headless Chrome with [Cuprite].
+Lint with `bin/rubocop`.
+
+Run the dummy app's server on port 3000 with `bin/dev` (set `PORT` to change it). It's a page of
+popovers to try by hand.
+
+Releases are cut from the **Bump Version** workflow in the Actions tab. It takes the version bump and
+a changelog entry, then tags the release, publishes it on GitHub, and pushes the gem to RubyGems.
+
+## Acknowledgments
+
+**Pop Frame** is [MIT-licensed](MIT-LICENSE), open-source software from [RoleModel Software][rms].
+
+[RoleModel Software][rms] is a world-class, collaborative software development team dedicated to delivering the highest quality custom web and mobile software solutions while cultivating a work environment where community, family, learning, and mentoring flourish.
+
+[slim]: https://github.com/slim-template/slim
+[mdn-popover]: https://developer.mozilla.org/en-US/docs/Web/API/Popover_API
+[mdn-top-layer]: https://developer.mozilla.org/en-US/docs/Glossary/Top_layer
+[mdn-anchor]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning
+[url-for]: https://api.rubyonrails.org/classes/ActionView/RoutingUrlFor.html#method-i-url_for
+[turbo-morph]: https://turbo.hotwired.dev/handbook/page_refreshes
+[Cuprite]: https://github.com/rubycdp/cuprite
+[rms]: https://rolemodelsoftware.com/

data/app/assets/stylesheets/pop_frame.css

@@ -0,0 +1,7 @@
+/* Anchored to the button that opened it, below and aligned to its start, flipping when it won't fit. */
+.pop-frame[popover] {
+  inset: auto;
+  margin: 4px 0 0;
+  position-area: block-end span-inline-end;
+  position-try-fallbacks: flip-block, flip-inline;
+}

data/lib/pop_frame/engine.rb

@@ -0,0 +1,12 @@
+module PopFrame
+  class Engine < ::Rails::Engine
+    initializer 'pop_frame.helper' do
+      ActiveSupport.on_load(:action_view) { include PopFrame::Helper }
+    end
+
+    # Propshaft puts every engine's app/assets on the load path by itself; Sprockets wants it named.
+    initializer 'pop_frame.assets' do |app|
+      app.config.assets.precompile << 'pop_frame.css' if app.config.respond_to?(:assets)
+    end
+  end
+end

data/lib/pop_frame/helper.rb

@@ -0,0 +1,16 @@
+module PopFrame
+  module Helper
+    # A button whose block is its content, opening a popover with a Turbo Frame that loads +src+
+    # (anything url_for takes) the first time it's shown, and reloads in place on a morph refresh.
+    def pop_frame_tag(id, src, loading: 'Loading…', **button_options, &)
+      popover_id = "#{id}_popover"
+
+      safe_join [
+        tag.button(type: 'button', popovertarget: popover_id, **button_options, &),
+        tag.div(id: popover_id, class: 'pop-frame', popover: 'auto') do
+          tag.turbo_frame(loading, id:, src: url_for(src), loading: 'lazy', refresh: 'morph')
+        end
+      ]
+    end
+  end
+end

data/lib/pop_frame/version.rb

@@ -0,0 +1,3 @@
+module PopFrame
+  VERSION = '0.1.0'
+end

data/lib/pop_frame.rb

@@ -0,0 +1,3 @@
+require 'pop_frame/version'
+require 'pop_frame/helper'
+require 'pop_frame/engine'

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: pop_frame
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Cohen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.0
+description: A view helper for a button that opens a lazily loaded Turbo Frame in
+  a native popover, anchored to the button with CSS. No JavaScript of its own.
+email:
+- andy.cohen@rolemodelsoftware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- app/assets/stylesheets/pop_frame.css
+- lib/pop_frame.rb
+- lib/pop_frame/engine.rb
+- lib/pop_frame/helper.rb
+- lib/pop_frame/version.rb
+homepage: https://github.com/RoleModel/pop-frame
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/RoleModel/pop-frame
+  source_code_uri: https://github.com/RoleModel/pop-frame
+  changelog_uri: https://github.com/RoleModel/pop-frame/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A Turbo Frame in a native popover, loaded when it opens.
+test_files: []