keystone_ui 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dcc3e30b080deb833cdbbcde6a946930de28fa541cb24fbdef2d83087eaca7c
-  data.tar.gz: 4c623f38dcbdd1f43371359af97b06fafd59796570267479db951236ac7daf85
+  metadata.gz: 77e17961bce047a1477df49c98660ff0484456e5add3eb78a59b67735296d91b
+  data.tar.gz: 75fa1c3b979a7490ea47423b5b5d64a075648ff203a9554af170a1dfc06865bf
 SHA512:
-  metadata.gz: 38add779239157bad1402f79b96cd66bf3219c39dac2e90b8d3b27eda892137bc1b2b5a0f5ed5df175e92b3963a90996fbc861d81b82667f87f711b37e08b7af
-  data.tar.gz: 4838c78a35737a4bdea3d3d847ddc7b60276a9630543990510a9ef0c2e67a52a34d0b87cf939b4d14a8213a9a0d52fe528615e232626c8b84de24d89158bc79f
+  metadata.gz: 5f1b133c91668e4fa4886c15f664588d2cec6fd972dae84caf199fd891aeb22c6e48c534f8274b5a64669fb02cd6adb09890f51b75656bd9943a2252b30555a8
+  data.tar.gz: 34db47e65e4304e7224557d1b29dc1abe8803edd920e851f4a9f8f456d680b71b78710fe2966fd2253b756373a6ca01197dbd1881ec53fa28b730c72e7516a0b

data/app/components/keystone/ui/action_menu_item_component.rb

@@ -5,16 +5,23 @@ module Keystone
     class ActionMenuItemComponent < ViewComponent::Base
       ITEM_CLASSES = "ks-menu-option block w-full text-left"
 
-      def initialize(label:, href:, method: :get)
+      def initialize(label:, href:, method: :get, confirm: nil)
         @label = label
         @href = href
         @method = method.to_sym
+        @confirm = confirm
+      end
+
+      def question
+        return @confirm if @confirm
+
+        "#{@label} this? This cannot be undone." if @method == :delete
       end
 
       def call
         return link_to(@label, @href, class: ITEM_CLASSES) if @method == :get
 
-        button_to(@href, method: @method, class: ITEM_CLASSES) { @label }
+        button_to(@href, method: @method, class: ITEM_CLASSES, form: { data: { turbo_confirm: question }.compact }) { @label }
       end
     end
   end

data/app/components/keystone/ui/checkbox_row_component.html.erb

@@ -1,7 +1,13 @@
-<label class="<%= row_classes %>">
+<label class="<%= row_classes %> relative"<%= ' data-controller="stat-card-info"'.html_safe if info? %>>
   <input type="checkbox" name="<%= name %>" value="<%= value %>" <%= "checked" if checked? %> class="<%= input_classes %>">
   <span>
-    <span class="<%= label_classes %>"><%= label %></span>
+    <span class="<%= header_classes %>">
+      <span class="<%= label_classes %>"><%= label %></span>
+      <% if info? %>
+        <button type="button" class="<%= info_button_classes %>" data-action="click->stat-card-info#toggle" aria-label="About <%= label %>"><%= info_icon.html_safe %></button>
+        <span class="<%= disclosure_classes %>" data-stat-card-info-target="panel"><%= info %></span>
+      <% end %>
+    </span>
     <% if hint? %>
       <span class="<%= hint_classes %>"><%= hint %></span>
     <% end %>

data/app/components/keystone/ui/checkbox_row_component.rb

@@ -7,14 +7,18 @@ module Keystone
       INPUT_CLASSES = "ks-checkbox-row-input size-4 shrink-0"
       LABEL_CLASSES = "ks-checkbox-row-label block text-sm"
       HINT_CLASSES = "ks-checkbox-row-hint block text-sm"
+      HEADER_CLASSES = RadioCardComponent::HEADER_CLASSES
+      INFO_BUTTON_CLASSES = RadioCardComponent::INFO_BUTTON_CLASSES
+      DISCLOSURE_CLASSES = RadioCardComponent::DISCLOSURE_CLASSES
 
-      attr_reader :name, :value, :label, :hint
+      attr_reader :name, :value, :label, :hint, :info
 
-      def initialize(name:, value:, label:, hint: nil, checked: false)
+      def initialize(name:, value:, label:, hint: nil, info: nil, checked: false)
         @name = name
         @value = value
         @label = label
         @hint = hint
+        @info = info
         @checked = checked
       end
 
@@ -26,6 +30,22 @@ module Keystone
         !@hint.nil?
       end
 
+      def info?
+        !@info.nil?
+      end
+
+      def info_button_classes
+        INFO_BUTTON_CLASSES
+      end
+
+      def disclosure_classes
+        DISCLOSURE_CLASSES
+      end
+
+      def info_icon
+        RadioCardComponent::INFO_ICON
+      end
+
       def row_classes
         ROW_CLASSES
       end
@@ -34,6 +54,10 @@ module Keystone
         INPUT_CLASSES
       end
 
+      def header_classes
+        HEADER_CLASSES
+      end
+
       def label_classes
         LABEL_CLASSES
       end

data/app/components/keystone/ui/radio_card_component.html.erb

@@ -1,7 +1,13 @@
-<label class="inline-block cursor-pointer">
+<label class="inline-block cursor-pointer relative"<%= ' data-controller="stat-card-info"'.html_safe if info? %>>
   <input type="radio" name="<%= name %>" value="<%= value %>" <%= "checked" if checked? %> class="peer sr-only">
   <span class="<%= classes %>">
-    <span class="<%= label_classes %>"><%= label %></span>
+    <span class="<%= header_classes %>">
+      <span class="<%= label_classes %>"><%= label %></span>
+      <% if info? %>
+        <button type="button" class="<%= info_button_classes %>" data-action="click->stat-card-info#toggle" aria-label="About <%= label %>"><%= info_icon.html_safe %></button>
+        <span class="<%= disclosure_classes %>" data-stat-card-info-target="panel"><%= info %></span>
+      <% end %>
+    </span>
     <% if hint? %>
       <span class="<%= hint_classes %>"><%= hint %></span>
     <% end %>

data/app/components/keystone/ui/radio_card_component.rb

@@ -5,16 +5,21 @@ module Keystone
     class RadioCardComponent < ViewComponent::Base
       BASE_CLASSES = "ks-radio-card inline-flex flex-col cursor-pointer transition"
       HIGHLIGHT_CLASSES = "ks-radio-card-highlight"
+      HEADER_CLASSES = "ks-radio-card-header flex items-start justify-between"
       LABEL_CLASSES = "ks-radio-card-label block"
       HINT_CLASSES = "ks-radio-card-hint block text-sm"
+      INFO_BUTTON_CLASSES = "ks-radio-card-info peer shrink-0"
+      DISCLOSURE_CLASSES = "ks-radio-card-disclosure hidden peer-hover:block absolute inset-x-0 top-full z-10 text-sm"
+      INFO_ICON = Keystone::Ui::StatCardComponent::INFO_ICON
 
-      attr_reader :name, :value, :label, :hint
+      attr_reader :name, :value, :label, :hint, :info
 
-      def initialize(name:, value:, label:, hint: nil, checked: false)
+      def initialize(name:, value:, label:, hint: nil, info: nil, checked: false)
         @name = name
         @value = value
         @label = label
         @hint = hint
+        @info = info
         @checked = checked
       end
 
@@ -26,10 +31,30 @@ module Keystone
         !@hint.nil?
       end
 
+      def info?
+        !@info.nil?
+      end
+
+      def info_button_classes
+        INFO_BUTTON_CLASSES
+      end
+
+      def info_icon
+        INFO_ICON
+      end
+
+      def disclosure_classes
+        DISCLOSURE_CLASSES
+      end
+
       def classes
         "#{BASE_CLASSES} #{HIGHLIGHT_CLASSES}"
       end
 
+      def header_classes
+        HEADER_CLASSES
+      end
+
       def label_classes
         LABEL_CLASSES
       end

data/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.25.0"
+  VERSION = "0.27.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -120,12 +120,15 @@ outer element. See Conventions before using it.
 - `ui_action_menu` — no keywords, takes a block. An ellipsis (⋯) button that
   opens a dropdown of actions, shown at every screen size. Fill the block with
   `ui_action_menu_item` calls.
-- `ui_action_menu_item(label:, href:, method: :get)` — one entry in an action
-  menu. With `method: :get` it is a link to `href`. Any other method, such as
-  `:post`, `:patch` or `:delete`, renders a button inside its own small form
-  that sends that method to `href`, so never place such an item inside a
-  `ui_form` block, since a form cannot contain another form. It asks for no
-  confirmation before sending.
+- `ui_action_menu_item(label:, href:, method: :get, confirm: nil)` — one entry
+  in an action menu. With `method: :get` it is a link to `href`. Any other
+  method, such as `:post`, `:patch` or `:delete`, renders a button inside its
+  own small form that sends that method to `href`, so never place such an item
+  inside a `ui_form` block, since a form cannot contain another form.
+  `confirm:` is a question Turbo asks before the item sends. With no
+  `confirm:`, a `method: :delete` item asks "<label> this? This cannot be
+  undone.", and every other method sends without asking. A `method: :get` item
+  is a plain link and ignores `confirm:`.
 - `ui_mobile_actions` — no keywords, takes a block. An ellipsis dropdown for
   mobile actions; the block holds the menu items. Hidden above `lg:`. Use
   `ui_action_menu` instead when the actions must also be reachable on desktop.
@@ -175,13 +178,24 @@ outer element. See Conventions before using it.
   enclosing form to be multipart.
 - `ui_color_picker(name:, value: "#000000", label: nil)` — a swatch that opens a
   hue/saturation panel and writes the hex into a hidden input named `name`.
-- `ui_radio_card(name:, value:, label:, hint: nil, checked: false)` — a
-  selectable card backed by a real radio input; selection styling is pure CSS.
-- `ui_checkbox_row(name:, value:, label:, hint: nil, checked: false)` — a real
-  checkbox with its label and optional hint inside one `<label>`, so a tap
-  anywhere on the row toggles the box. A checked row submits `value` under
+- `ui_radio_card(name:, value:, label:, hint: nil, info: nil, checked: false)`
+  — a selectable card backed by a real radio input; selection styling is pure
+  CSS. `hint:` is a line of text always shown under the label. `info:` is
+  longer text about the option, kept hidden: passing it adds an info button on
+  the row with the label, named "About <label>" for screen readers, and the
+  text shows in a panel floating below the card while the button is hovered,
+  and tapping the button toggles it. With no `info:` the card has no info
+  button.
+- `ui_checkbox_row(name:, value:, label:, hint: nil, info: nil, checked: false)`
+  — a real checkbox with its label and optional hint inside one `<label>`, so a
+  tap anywhere on the row toggles the box. A checked row submits `value` under
   `name`; give several rows the same array name, e.g. `"shown[]"`, to submit the
-  checked values as a list. An unchecked row submits nothing. No JavaScript.
+  checked values as a list. An unchecked row submits nothing. `hint:` is a line
+  of text always shown under the label. `info:` works as it does on
+  `ui_radio_card`: passing it adds an info button on the line with the label,
+  named "About <label>" for screen readers, and the text shows in a panel
+  floating below the row while the button is hovered, and tapping the button
+  toggles it. With no `info:` the row has no info button.
 - `ui_option_card(name:, value:, selected: false, input_data: {}, label_data: {})`
   — takes a block. A radio whose visible body is whatever the block renders.
   `input_data:`/`label_data:` become `data-*` attributes on the input and label.
@@ -378,12 +392,16 @@ outer element. See Conventions before using it.
    To show the arithmetic behind a figure, put `ui_calculation` under it rather
    than a hand-built list. Which lines and groups to show is the app's own
    calculation, so ask the developer which steps a reader needs to see.
+   On a radio card or a checkbox row, text every reader needs to choose goes in `hint:` and
+   text only some will want goes in `info:`. Which is which is the app's own
+   wording, so ask the developer rather than pick.
    Put the actions on a record, such as Edit and Delete, in an action menu
    rather than in a row of buttons: `menu:` on the `ui_section` that shows the
    record, `table.actions` for a table row, or `ui_action_menu` anywhere else.
-   An item that deletes or changes data sends without asking for
-   confirmation, so ask the developer whether that action needs a confirmation
-   step before adding it.
+   A delete item asks for confirmation on its own, so pass `confirm:` only
+   when the developer wants different wording. A `:post`, `:patch` or `:put`
+   item sends without asking, so ask the developer whether that action needs
+   a question, and pass it as `confirm:` if it does.
 
 6. For a table, decide how columns are declared. Use `{ key: "Label" }` hashes
    when every column is plain. Switch the whole set to `Keystone::Ui::Column`

data/the_local/agents/keystone_ui-info.md

@@ -78,9 +78,16 @@ holds the catalog.
   of actions, shown at every screen size. The mobile action menu is the one
   hidden from `lg:` up. Each action is a label, an address and an HTTP method.
   A plain visit renders as a link. Any other method renders as a button that
-  sends that method, so an action that changes data is never a bare link. A
-  data table puts each row's actions in one action menu at the end of the row,
+  sends that method, so an action that changes data is never a bare link. An
+  action can carry a question that Turbo asks before it runs. A delete asks
+  "<label> this? This cannot be undone." unless it is given its own question,
+  and other actions ask nothing unless given one. A data table puts each row's actions in one action menu at the end of the row,
   and a section can carry an action menu in its header beside its title.
+- **Info panels.** A stat card, a radio card and a checkbox row can each carry
+  extra text about themselves. Given that text, the piece shows an info button,
+  and the text stays hidden until the button is hovered or tapped. A piece
+  given no such text shows no button. On a radio card and a checkbox row the
+  button sits on the line with the label.
 - **Options are symbols, and each component accepts its own set.** Appearance is
   chosen by name — `variant:`, `size:`, `type:`, `padding:`, `spacing:`,
   `max_width:`, `radius:` — on a size scale (`:sm` … `:xl`) or a short list of
@@ -139,7 +146,7 @@ holds the catalog.
   at boot where the component files are.
 - **Interactivity is Stimulus.** Dropdowns, modals, dismissible alerts, file
   uploads, the color picker, the multi-select, tab switchers, accordions, the
-  swipe deck, column pickers, stat card info panels, line charts, clipboard copy
+  swipe deck, column pickers, info panels, line charts, clipboard copy
   and the theme toggle ship with the gem as Stimulus controllers registered once
   at install. A host writes no JavaScript to use them. Components that post
   somewhere, such as the column picker and the pipeline, post to endpoints the

data/the_local/agents/keystone_ui-install.md

@@ -215,8 +215,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
      A page that passes no Back link goes back to the trail's last link. A page
      that passes its own trail or Back link keeps it. With no supplier, or a
      `nil` return, the page shows its Back link. Return `nil`, not an empty
-     array, for a page with no trail, because an empty array replaces the
-     page's Back link with breadcrumbs holding only its title.
+     array, for a page with no trail. An empty array replaces the page's Back
+     link with breadcrumbs holding only its title, and on a page that passes
+     no Back link it raises `KeystoneUi::MissingBackLink`.
    - Every form and show page must end up with a Back link. A page that passes
      no Back link and no trail, and gets no trail from the supplier, raises
      `KeystoneUi::MissingBackLink` naming the page's title when it renders.

data/the_local/interface.yml

@@ -128,6 +128,7 @@ sources:
   - app/components/keystone/ui/theme_toggle_component.rb
   - app/components/keystone/ui/progress_component.rb
   - app/components/keystone/ui/radio_card_component.rb
+  - app/components/keystone/ui/radio_card_component.html.erb
   - app/components/keystone/ui/section_component.rb
   - app/components/keystone/ui/section_component.html.erb
   - app/components/keystone/ui/select_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement