keystone_ui 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88ffa01b58c46bdab1ddcf7657b1b60e3caf4320519cb64e5bcf6dfc59e047c9
-  data.tar.gz: 151698597ec642c7a410e5835d4b66f3c5b17a1fc778c995f9b583d912e565df
+  metadata.gz: e0ee212f207d337a71bacb75feeb208b87dce778bae0d0f1f3eae6c579edffc7
+  data.tar.gz: feddfc10e16f72a89a15b0c5c9b35caf22e5c579205d954d483e21093fb3ab59
 SHA512:
-  metadata.gz: 97232de923802fef99483afbdfc76ecc8cac4a7220ed40e97aa4d19426fb885b0d5c012b587ec7e94cd980042fb27d70b99d832e332addd608e4d41645901618
-  data.tar.gz: 7b6cf8260919c664248a7246eda7d917e580d6d709737eb83b2d27d7e9e67e37c45fb4302061b8d824cf5e96bd20af403eb07e9f3c6c78f6e4571920f3d0ff6a
+  metadata.gz: 8444ed3845fb6be74e214ffad7c57f19221a48b7ccf023bd252506eafbc53588bbd76378a2cb19174ea293c3304ae66edc90509b9209ba9ba9d8565282e021fa
+  data.tar.gz: ebef332e0bdda943a4a95bb72e7f6b0e2b5d2f0de6bca13b623bc3d8fe7432d9d605b58810a208fa73eea0523a3b795f4a2ba657df036b790fd0a9837d0314a9

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

@@ -0,0 +1,10 @@
+<span class="block">
+  <% lines.each do |line| %>
+    <span class="<%= Keystone::Ui::BreakdownComponent::LINE_CLASSES %>">
+      <span class="<%= Keystone::Ui::BreakdownComponent::AMOUNT_CLASSES %>"><%= line[:amount] %></span>&nbsp;<span class="<%= Keystone::Ui::BreakdownComponent::LABEL_CLASSES %>"><%= line[:label] %></span>
+    </span>
+  <% end %>
+  <span class="<%= Keystone::Ui::BreakdownComponent::TOTAL_CLASSES %>">
+    <span class="<%= Keystone::Ui::BreakdownComponent::AMOUNT_CLASSES %>"><%= total[:amount] %></span>&nbsp;<span class="<%= Keystone::Ui::BreakdownComponent::LABEL_CLASSES %>"><%= total[:label] %></span>
+  </span>
+</span>

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class BreakdownComponent < ViewComponent::Base
+      LINE_CLASSES = "ks-breakdown-line block"
+      AMOUNT_CLASSES = "ks-breakdown-amount inline-block w-24 text-right tabular-nums"
+      LABEL_CLASSES = "ks-breakdown-label"
+      TOTAL_CLASSES = "ks-breakdown-total ks-stat-card-emphasis block"
+
+      attr_reader :lines, :total
+
+      def initialize(lines:, total:)
+        @lines = lines
+        @total = total
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+<span class="relative inline-flex" data-controller="stat-card-info">
+  <button type="button" class="<%= button_classes %>" data-action="click->stat-card-info#toggle" aria-label="More about this"><%= icon.html_safe %></button>
+  <span class="<%= summary_classes %>"<%= ' data-stat-card-info-target="panel"'.html_safe unless content? %>><%= summary %></span>
+  <% if content? %>
+    <span class="<%= detail_classes %>" data-stat-card-info-target="panel"><%= content %></span>
+  <% end %>
+</span>

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class InfoComponent < ViewComponent::Base
+      BUTTON_CLASSES = RadioCardComponent::INFO_BUTTON_CLASSES
+      ICON = RadioCardComponent::INFO_ICON
+      SUMMARY_CLASSES = "ks-info-summary #{RadioCardComponent::DISCLOSURE_CLASSES} w-64"
+      DETAIL_CLASSES = "ks-info-detail ks-radio-card-disclosure hidden absolute top-full right-0 z-20 w-72 text-sm"
+
+      def initialize(summary:)
+        @summary = summary
+      end
+
+      attr_reader :summary
+
+      def summary_classes
+        SUMMARY_CLASSES
+      end
+
+      def detail_classes
+        DETAIL_CLASSES
+      end
+
+      def button_classes
+        BUTTON_CLASSES
+      end
+
+      def icon
+        ICON
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui_helper.rb

@@ -229,6 +229,14 @@ module KeystoneUiHelper
     render Keystone::Ui::CalculationComponent.new(**args)
   end
 
+  def ui_info(**args, &block)
+    render(Keystone::Ui::InfoComponent.new(**args), &block)
+  end
+
+  def ui_breakdown(**args)
+    render Keystone::Ui::BreakdownComponent.new(**args)
+  end
+
   private
 
   def keystone_theme_choice

data/lib/keystone_ui/safelist.rb

@@ -61,7 +61,9 @@ module Keystone
       Keystone::Ui::ThemeToggleComponent,
       Keystone::Ui::CalculationComponent,
       Keystone::Ui::DesktopBackLinkComponent,
-      Keystone::Ui::BreadcrumbsComponent
+      Keystone::Ui::BreadcrumbsComponent,
+      Keystone::Ui::InfoComponent,
+      Keystone::Ui::BreakdownComponent
     ].freeze
 
     # Constants that hold non-CSS values (e.g. HTML input type maps)

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -269,6 +269,23 @@ outer element. See Conventions before using it.
   — with the result right-aligned. Every value is printed as given, so format
   numbers and currency before passing them. Place it directly under the figure
   it explains, such as a `ui_stat_card`.
+- `ui_info(summary:)` — an info button, named "More about this" for screen
+  readers, placed inline beside the thing it explains. `summary:` is a short
+  line of text shown in a floating panel while the button is hovered. The block
+  is optional and holds the full detail. With a block, tapping or clicking the
+  button toggles a second floating panel holding the block's content, and the
+  summary stays hover-only. With no block, tapping the button toggles the
+  summary itself. Both panels render inside a `<span>`, so the block may hold
+  text and inline elements only, such as a `ui_breakdown`, and never a `<div>`,
+  list or table. Toggling needs the gem's Stimulus controllers registered.
+- `ui_breakdown(lines:, total:)` — no block. A list of amounts ending in their
+  total. `lines:` is `[{ amount:, label: }, ...]` and `total:` is one
+  `{ amount:, label: }`, both required. Each line renders its amount
+  right-aligned in a fixed-width column with its label beside it, and the total
+  renders last, emphasized. Every value is printed as given and nothing is
+  added up, so compute the total and format numbers and currency before
+  passing them. It renders inline elements only, so it can sit inside a
+  `ui_info` block.
 - `ui_accordion(items: [])` — a stack of independently expandable rows. `items:`
   is `[{ question:, answer: }, ...]`.
 - `ui_tab_switcher(tabs:)` — takes a block. `tabs:` is an array of label strings;
@@ -397,6 +414,11 @@ 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.
+   To explain a figure or label that is not a stat card, put `ui_info` beside
+   it, with the one-line explanation as `summary:` and, when the figure is a
+   sum of parts, a `ui_breakdown` in its block. Which amounts the breakdown
+   lists, and the wording of the summary, are the app's own, so ask the
+   developer rather than pick.
    A field whose value must be one of a fixed list is a `:select` with
    `options:`, and a field that accepts any text and offers common values is a
    text field with `suggestions:`. Which one a field is, and which values it

data/the_local/agents/keystone_ui-info.md

@@ -14,7 +14,8 @@ Keystone UI is a Rails engine gem that supplies a host app's visual layer as a
 library of view helpers built on ViewComponent. Screens are built from named
 pieces — page shells, sections, panels, grids, form fields, data tables,
 navigation bars, breadcrumbs, cards, stat tiles, charts, funnels, goal buckets, pipelines,
-banners, the calculation behind a figure — instead of hand-written ERB and
+banners, the calculation behind a figure, a breakdown of amounts and their
+total, an info button — instead of hand-written ERB and
 Tailwind. Every class the UI renders lives inside the gem, in frozen constants,
 so the look is defined in one place.
 
@@ -88,6 +89,17 @@ holds the catalog.
   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.
+- **Standalone info button.** The same info button can be placed on its own,
+  beside anything. It takes a short summary, which is required, and shows it
+  when the button is hovered. Given nothing more, a tap shows the summary too.
+  Given a block of further detail, a tap opens that detail instead, in a panel
+  under the button, and the summary stays the hover text.
+- **A breakdown is text.** A breakdown lists amounts, each beside a label
+  saying what it is, and ends with a total set apart from the lines above it.
+  Every line and the total are an amount and a label, passed as
+  already-formatted text and shown as written. The component adds nothing up,
+  so the total is whatever it is given. It has no button and no hidden state of
+  its own, and it can be placed inside an info button's detail.
 - **Suggestions.** A form field can carry a list of suggested values. The
   browser offers them while the field's text is typed, and the user can still
   enter a value that is not on the list. This applies to a field with a typed

data/the_local/interface.yml

@@ -61,6 +61,8 @@ develop:
   - ui_code
   - ui_disclosure
   - ui_calculation
+  - ui_info
+  - ui_breakdown
   - ui_theme_toggle
   - Keystone::Ui::Column
 
@@ -93,6 +95,10 @@ sources:
   - app/components/keystone/ui/data_table_component.html.erb
   - app/components/keystone/ui/disclosure_component.rb
   - app/components/keystone/ui/calculation_component.rb
+  - app/components/keystone/ui/info_component.rb
+  - app/components/keystone/ui/info_component.html.erb
+  - app/components/keystone/ui/breakdown_component.rb
+  - app/components/keystone/ui/breakdown_component.html.erb
   - app/components/keystone/ui/feature_grid_component.rb
   - app/components/keystone/ui/file_upload_component.rb
   - app/components/keystone/ui/form_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -87,6 +87,8 @@ files:
 - app/components/keystone/ui/bottom_nav_item_component.rb
 - app/components/keystone/ui/breadcrumbs_component.html.erb
 - app/components/keystone/ui/breadcrumbs_component.rb
+- app/components/keystone/ui/breakdown_component.html.erb
+- app/components/keystone/ui/breakdown_component.rb
 - app/components/keystone/ui/bucket_component.html.erb
 - app/components/keystone/ui/bucket_component.rb
 - app/components/keystone/ui/bucket_series_component.html.erb
@@ -136,6 +138,8 @@ files:
 - app/components/keystone/ui/grid_component.rb
 - app/components/keystone/ui/hero_component.html.erb
 - app/components/keystone/ui/hero_component.rb
+- app/components/keystone/ui/info_component.html.erb
+- app/components/keystone/ui/info_component.rb
 - app/components/keystone/ui/input_component.html.erb
 - app/components/keystone/ui/input_component.rb
 - app/components/keystone/ui/line_chart_component.html.erb