keystone_ui 0.27.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77e17961bce047a1477df49c98660ff0484456e5add3eb78a59b67735296d91b
-  data.tar.gz: 75fa1c3b979a7490ea47423b5b5d64a075648ff203a9554af170a1dfc06865bf
+  metadata.gz: e0ee212f207d337a71bacb75feeb208b87dce778bae0d0f1f3eae6c579edffc7
+  data.tar.gz: feddfc10e16f72a89a15b0c5c9b35caf22e5c579205d954d483e21093fb3ab59
 SHA512:
-  metadata.gz: 5f1b133c91668e4fa4886c15f664588d2cec6fd972dae84caf199fd891aeb22c6e48c534f8274b5a64669fb02cd6adb09890f51b75656bd9943a2252b30555a8
-  data.tar.gz: 34db47e65e4304e7224557d1b29dc1abe8803edd920e851f4a9f8f456d680b71b78710fe2966fd2253b756373a6ca01197dbd1881ec53fa28b730c72e7516a0b
+  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/form_field_component.html.erb

@@ -22,6 +22,13 @@
     </select>
   <% else %>
     <%= tag.input(**input_options) %>
+    <% if suggestions? %>
+      <datalist id="<%= suggestions_id %>">
+        <% suggestions.each do |suggestion| %>
+          <option value="<%= suggestion %>"></option>
+        <% end %>
+      </datalist>
+    <% end %>
   <% end %>
 
   <% if hint? %>

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

@@ -11,7 +11,7 @@ module Keystone
       CHECKBOX_CLASSES = "ks-checkbox"
       CHECKBOX_WRAPPER_CLASSES = "ks-form-field-checkbox flex items-center"
 
-      def initialize(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false)
+      def initialize(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false, suggestions: [])
         @attribute = attribute
         @label = label
         @type = type
@@ -26,6 +26,7 @@ module Keystone
         @errors = Array(errors)
         @include_blank = include_blank.to_s
         @disabled = disabled
+        @suggestions = Array(suggestions)
       end
 
       def label_text
@@ -83,8 +84,21 @@ module Keystone
         options[:max] = @max unless @max.nil?
         options[:step] = @step unless @step.nil?
         options[:disabled] = true if @disabled
+        options[:list] = suggestions_id if suggestions?
         options
       end
+
+      def suggestions?
+        @suggestions.any?
+      end
+
+      def suggestions
+        @suggestions
+      end
+
+      def suggestions_id
+        "#{@attribute.to_s.parameterize}-suggestions"
+      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.27.0"
+  VERSION = "0.29.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -146,7 +146,7 @@ outer element. See Conventions before using it.
   The `<form>` wrapper. `method:` may be `:patch`/`:put`/`:delete` and is
   translated for Rails. Set `multipart: true` when the form contains a file
   upload.
-- `ui_form_field(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false)`
+- `ui_form_field(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false, suggestions: [])`
   — a labeled field with hint and error text. This is the default way to render
   an input. `type:` `:text` `:number` `:email` `:password` `:date` `:textarea`
   `:checkbox` `:select`. `attribute:` is used verbatim as the input's `name`, so
@@ -159,7 +159,12 @@ outer element. See Conventions before using it.
   it. Never add your own empty choice to `options:` as well. A
   `:checkbox` renders its label beside the box, submits `"0"` when unchecked and
   `"1"` when checked, and pre-checks when `value:` is `"1"`. `errors:` is an
-  array of message strings.
+  array of message strings. `suggestions:` is an array of strings the browser
+  offers while the field's text is typed, and the user can still type a value
+  that is not in it. It applies to `:text`, `:number`, `:email`, `:password`
+  and `:date` fields, and a `:textarea`, `:checkbox` or `:select` ignores it.
+  The suggestion list's `id` is built from `attribute:`, so two fields with
+  suggestions on one screen need different `attribute:` values.
 - `ui_input(name:, type: :text, value: nil, placeholder: nil, disabled: false, min: nil, max: nil, step: nil)`
   — a bare styled input with no label. `type:` `:text` `:number` `:email`
   `:password` `:date`.
@@ -264,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;
@@ -392,6 +414,15 @@ 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
+   suggests, is the app's own rule, so ask the developer rather than pick.
    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.

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,23 @@ 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
+  input, such as text, number, email, password or date. A textarea, select or
+  checkbox field ignores the list, and a field given no list offers nothing.
+  It needs no JavaScript.
 - **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

data/the_local/agents/keystone_ui-install.md

@@ -40,7 +40,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
 ## How to use it
 
 1. Confirm the prerequisites: Ruby >= 3.2 and **tailwindcss-rails v4+** in the
-   host app. The gem brings ViewComponent and keystone_ui-styles 0.6.0 or later with it.
+   host app. The gem brings ViewComponent and keystone_ui-styles 0.8.0 or later with it.
    Tailwind does not have to be initialized first, because the generator creates
    the stylesheet if it is missing.
 

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.27.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