atomic_view 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 165a6c2614a15ffc294ecb82a4c969e73bdc9821e05f5cd11961b2bc8670d863
-  data.tar.gz: 19adaf0af4395f5880d1ad44a5f5fdb4b273d841a95ed5f072e88830c7521c18
+  metadata.gz: d26209da003c20d55578d1f8c1036c7f2d6d8f479e1eafadba499aebe8b417a6
+  data.tar.gz: '0781dfbfd8ddf9d8a1f2e5be5a13b1f2e3511cc776ba4feb39e439933885f1f7'
 SHA512:
-  metadata.gz: 5beeb078b1ea0fff91b7ad5b9e13c8f3336da75a4eeb1f37f0f4686e2556bd1896b1dc3d87d5d4d562de8fe3b819e20b312c9f556411d49258172afc43c23ffe
-  data.tar.gz: c69212fa8f25195f3724fa13a58db718235d0877379bd7ba7339c4354505d6e5af83430ca937ffd7957d137a4cd1496e3f272a1ee9ba8e358a39e7c9a5220bc7
+  metadata.gz: 242b73833f14000d4efdd0d41f2be4a5352bc8548fc8bfeddd90501578d8b351c85cfc034a9fc1d64f75809dc4fb206d02dfabc137aa81842d8408dfa4951c3b
+  data.tar.gz: f591c5a4004651687bdb6229c7b44a44b20084615c48e52d97cc378b339a67f6237ec33edbb8a80a3e2c41faba79b07055c4975749d846c0c2b05b5e287c871c

data/app/assets/javascripts/atomic_view/controllers/drawer_controller.js

@@ -0,0 +1,26 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values = { open: Boolean }
+
+  connect() {
+    this.element.addEventListener("click", this.closeOnBackdrop)
+    if (this.openValue) this.open()
+  }
+
+  disconnect() {
+    this.element.removeEventListener("click", this.closeOnBackdrop)
+  }
+
+  open() {
+    this.element.showModal()
+  }
+
+  close() {
+    this.element.close()
+  }
+
+  closeOnBackdrop = (event) => {
+    if (event.target === this.element) this.close()
+  }
+}

data/lib/atomic_view/components/drawer_component.html.erb

@@ -0,0 +1,27 @@
+<%= tag.dialog(**html_options, id: id, class: html_class, data: data_attributes) do %>
+  <div class="flex items-center justify-between gap-4 border-b border-border p-4">
+    <% if title.present? %>
+      <h2 class="font-body text-lg font-semibold text-foreground"><%= title %></h2>
+    <% end %>
+
+    <div class="ml-auto flex items-center gap-2">
+      <% if actions? %>
+        <%= actions %>
+      <% end %>
+
+      <%= tag.button(type: "button", class: "inline-flex shrink-0 items-center text-muted-foreground hover:text-foreground", data: {action: "click->atomic-view--drawer#close"}, aria: {label: "Close"}) do %>
+        <%= close_icon %>
+      <% end %>
+    </div>
+  </div>
+
+  <div class="flex-1 overflow-y-auto p-4 text-sm text-foreground">
+    <%= content %>
+  </div>
+
+  <% if footer? %>
+    <div class="flex justify-end gap-2 border-t border-border p-4">
+      <%= footer %>
+    </div>
+  <% end %>
+<% end %>

data/lib/atomic_view/components/drawer_component.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    # Drawer
+    #
+    # A side panel built on the native `<dialog>` element -- same structural
+    # trick as `ModalComponent` (see that component for the rationale), just
+    # pinned to one edge of the viewport (`side: :left`/`:right`, default
+    # `:right`) and stretched to full height instead of centered. `<dialog>`
+    # still gets focus-trap, `::backdrop` styling, and Esc-to-close for free;
+    # `atomic-view--drawer` (see
+    # `app/assets/javascripts/atomic_view/controllers/drawer_controller.js`)
+    # layers on `open`/`close` plus closing when the backdrop itself (not the
+    # content box) is clicked -- identical to Modal's controller.
+    #
+    # Layout is a fixed header (title, an optional `actions` slot for e.g. a
+    # secondary action button, and an always-present close button) and an
+    # optional fixed footer (`renders_one :footer`, typically Cancel/Confirm
+    # buttons) around a body that scrolls independently -- the body is the
+    # component's default slot (the block passed to `render`).
+    #
+    # A footer Confirm button that needs to submit a `form_with` in the body
+    # can't be nested inside it -- they're siblings, in separate header/
+    # body/footer containers. Give the form an explicit `id:` instead, and
+    # point the button at it with HTML5's `form="..."` attribute, which
+    # associates a button with a form by id no matter where in the DOM the
+    # button actually lives:
+    #
+    #   render(DrawerComponent.new(id: "product-drawer", title: "Add a product")) do |drawer|
+    #     drawer.with_footer do
+    #       render ButtonComponent.new(nil, "Add product", {type: "submit", form: "product-drawer-form"})
+    #     end
+    #
+    #     form_with(model: @product, id: "product-drawer-form") { |form| ... }
+    #   end
+    #
+    # == Turbo Streams: same content, opened two different ways
+    #
+    # A drawer's body is often "a page" -- e.g. a New Product form -- that
+    # should also work as an ordinary full-page route for a direct link,
+    # bookmark, or reload. Both cases render the exact same
+    # `DrawerComponent.new(id: "...", open: true) { ... }` call; the
+    # difference is only what's *around* it:
+    #
+    #   * Direct visit (e.g. GET /products/new): render the underlying page
+    #     (the product list) as normal, with this drawer -- `open: true` --
+    #     included in that same response, already showing on top of it.
+    #   * Opened from elsewhere via Turbo Streams: the triggering link/form
+    #     targets `format: :turbo_stream`, and the response replaces or
+    #     updates a container already sitting on the page with a fresh
+    #     render of this same component (again `open: true`):
+    #
+    #       <%= turbo_stream.update("product-drawer", render(
+    #             AtomicView::Components::DrawerComponent.new(id: "product-drawer-dialog", open: true, title: "Add a product") do
+    #               render "products/form"
+    #             end
+    #           )) %>
+    #
+    # Either way, Turbo inserts a brand new `<dialog>` node, so
+    # `atomic-view--drawer` never needs a bespoke "please open now" event to
+    # bridge the two cases -- `connect()` sees `open: true` and calls
+    # `showModal()` itself every time, whether that's on first paint or after
+    # a Turbo Stream swap. Closing it (backdrop click, Esc, or a Cancel
+    # button) is just `dialog.close()` -- the page behind it, already in the
+    # same document, is simply what's left after the drawer's gone; give the
+    # host app's own controller the job of updating the URL back if that
+    # matters.
+    class DrawerComponent < AtomicView::Component
+      renders_one :actions
+      renders_one :footer
+
+      attr_reader :id, :title, :side, :open
+
+      def initialize(id:, title: nil, side: :right, open: false, **options)
+        super()
+        @id = id
+        @title = title
+        @side = side
+        @open = open
+        @options = options
+      end
+
+      def html_options
+        @options.except(:class, :data)
+      end
+
+      def html_class
+        class_names(
+          # `hidden`/`open:flex` (not a bare `flex`) -- the dialog needs
+          # `display:flex` once shown (for the header/body/footer column
+          # layout), but a bare `flex` utility class is author-origin CSS
+          # that would permanently beat the user-agent stylesheet's
+          # `dialog:not([open]) { display: none }`, leaving the "closed"
+          # dialog fully rendered (and eating clicks) at all times. The
+          # `open:` variant (targeting the `[open]` attribute the browser
+          # itself adds/removes on showModal()/close()) keeps it hidden
+          # until actually shown, same as Modal gets for free by not
+          # setting `display` at all.
+          "m-0 hidden h-dvh max-h-none w-full flex-col bg-surface p-0 text-foreground shadow-panel open:flex backdrop:bg-backdrop sm:max-w-lg",
+          side_classes,
+          @options[:class]
+        )
+      end
+
+      def data_attributes
+        attributes = (@options[:data] || {}).merge(controller: "atomic-view--drawer")
+        attributes["atomic-view--drawer-open-value"] = true if open
+        attributes
+      end
+
+      def close_icon
+        icon("x-mark", variant: :mini, options: {class: "size-5"}).to_s.html_safe
+      end
+
+      private
+
+      def side_classes
+        (side == :left) ? "inset-y-0 left-0 right-auto" : "inset-y-0 right-0 left-auto"
+      end
+    end
+  end
+end

data/lib/atomic_view/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AtomicView
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomic_view
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Joel Warrington
@@ -143,6 +143,7 @@ files:
 - app/assets/javascripts/atomic_view/controllers/auto_submit_controller.js
 - app/assets/javascripts/atomic_view/controllers/chip_controller.js
 - app/assets/javascripts/atomic_view/controllers/command_palette_controller.js
+- app/assets/javascripts/atomic_view/controllers/drawer_controller.js
 - app/assets/javascripts/atomic_view/controllers/dropdown_controller.js
 - app/assets/javascripts/atomic_view/controllers/gantt_controller.js
 - app/assets/javascripts/atomic_view/controllers/hotkey_controller.js
@@ -200,6 +201,8 @@ files:
 - lib/atomic_view/components/date_select_component.rb
 - lib/atomic_view/components/datetime_local_field_component.rb
 - lib/atomic_view/components/datetime_select_component.rb
+- lib/atomic_view/components/drawer_component.html.erb
+- lib/atomic_view/components/drawer_component.rb
 - lib/atomic_view/components/dropdown_component.html.erb
 - lib/atomic_view/components/dropdown_component.rb
 - lib/atomic_view/components/email_field_component.rb