keystone_ui 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a7d6bdda07417d6d7f13bde323a8fc8dd26034ff1d10ac2824f223c52cbfb92
-  data.tar.gz: 45f44c67ef941fd3434323ad6ac4f68401966f1b10c395b168f5d81ecea5aee2
+  metadata.gz: 19d3d7682e2b19ea8bdeadd90f50b0668db2587e21c891c220fdbb5af56a3780
+  data.tar.gz: dafd5905c87e5723538ffd9f581b3e6edafe6d8a248a5364580191350778fe82
 SHA512:
-  metadata.gz: f228e0e8d779f7c55c67f6da15ff8491a290ca0da0f5272930fa3c63059a682a071dddc76e4e8fb860812a2d3d9448a5df9478bd97eafcb961bf7cc2b79fcaf7
-  data.tar.gz: 34f974483319d1ed08c947b11bf8128777a2f690bbc71fce1cba5f680c08fbfcc77d7d4ff39bbc745287df9f13f84a5d17fe675b575e6f4235d24977eaf84a9d
+  metadata.gz: 0ee13705c4e25ef9c471d11005dfc081069acfb204482055198e35e1ddf131e836755769e42b26a3ec88e7f452e8ed47068b660430ad2d812eaaf72aeb734fb9
+  data.tar.gz: d48180384c5199e133b23792a0b8fdd569347f9800abe0edf49ecf18dcccad7aee3b3419133e6fb4b9ced574280e0eb7659bdf60fd920b9596008cbb0870de6b

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

@@ -0,0 +1,19 @@
+<%= render Keystone::Ui::DisclosureComponent.new do |disclosure| %>
+  <% disclosure.with_summary_content(summary) %>
+  <div class="<%= GROUPS_CLASSES %>">
+    <% groups.each do |group| %>
+      <div>
+        <% if group.title %>
+          <p class="<%= TITLE_CLASSES %>"><%= group.title %></p>
+        <% end %>
+        <div class="<%= LINES_CLASSES %>">
+          <% group.lines.each do |line| %>
+            <span class="<%= LINE_CLASSES %>"><%= line.label %></span>
+            <span class="<%= LINE_CLASSES %>"><%= line.working %></span>
+            <span class="<%= RESULT_CLASSES %>"><%= line.result %></span>
+          <% end %>
+        </div>
+      </div>
+    <% end %>
+  </div>
+<% end %>

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class CalculationComponent < ViewComponent::Base
+      Group = Struct.new(:title, :lines, keyword_init: true)
+      Line = Struct.new(:label, :working, :result, keyword_init: true)
+
+      TITLE_CLASSES = "ks-label text-sm"
+      LINE_CLASSES = "ks-hint text-sm"
+      LINES_CLASSES = "grid grid-cols-[auto_1fr_auto] ks-grid-gap-sm"
+      RESULT_CLASSES = "ks-hint text-sm text-right"
+      GROUPS_CLASSES = "grid ks-grid-gap-md"
+
+      attr_reader :groups, :summary
+
+      def initialize(groups:, summary: "How this is worked out")
+        @groups = groups.map { |group| Group.new(title: group[:title], lines: group.fetch(:lines).map { |line| Line.new(**line) }) }
+        @summary = summary
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui_helper.rb

@@ -213,6 +213,10 @@ module KeystoneUiHelper
     render Keystone::Ui::DisclosureComponent.new(**args), &block
   end
 
+  def ui_calculation(**args)
+    render Keystone::Ui::CalculationComponent.new(**args)
+  end
+
   private
 
   def keystone_theme_choice

data/lib/keystone_ui/safelist.rb

@@ -56,7 +56,8 @@ module Keystone
       Keystone::Ui::PipelineComponent,
       Keystone::Ui::CodeComponent,
       Keystone::Ui::DisclosureComponent,
-      Keystone::Ui::ThemeToggleComponent
+      Keystone::Ui::ThemeToggleComponent,
+      Keystone::Ui::CalculationComponent
     ].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.18.0"
+  VERSION = "0.19.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -198,6 +198,15 @@ outer element. See Conventions before using it.
 - `ui_disclosure(open: false)` — takes a block yielding the component. Fill its
   `summary` slot with the clickable header; the rest of the block is the body.
   Native `<details>` — no JavaScript.
+- `ui_calculation(groups:, summary: "How this is worked out")` — no block. Shows
+  how a figure was reached, closed by default under a row reading `summary:`.
+  `groups:` is `[{ title:, lines: [{ label:, working:, result: }, ...] }, ...]`;
+  `title:` is optional, `lines:` is required and a group without it raises
+  `KeyError`, and a line with any key other than those three raises
+  `ArgumentError`. Each line renders as three columns — label, working, result
+  — 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_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;
@@ -298,6 +307,9 @@ outer element. See Conventions before using it.
    `ui_data_table` over a hand-built `<table>`, `ui_stat_card` over a panel with
    text in it. To make a stat card clickable, pass `href:` — never wrap it in
    `ui_card_link`, because a tap on the info button would then follow the link.
+   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.
 
 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

@@ -14,8 +14,9 @@ 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, cards, stat tiles, charts, funnels, goal buckets, pipelines,
-banners — 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.
+banners, the calculation behind a figure — 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.
 
 Reach for it whenever you build or change a screen in an app that has it
 installed. It exists to stop UI drift: two pages built from the same helpers
@@ -49,9 +50,10 @@ holds the catalog.
 
 - **Helpers, not classes.** Every piece of UI is a view helper prefixed `ui_`,
   called from ERB. The one layout helper that is not prefixed `ui_` writes the
-  theme onto the page's `html` tag, and it belongs to the install local. Components live under the `Keystone::Ui` namespace, but a
-  host app does not name a component class directly. The one exception is the
-  table column value object, which is passed as an argument and renders nothing.
+  theme onto the page's `html` tag, and it belongs to the install local.
+  Components live under the `Keystone::Ui` namespace, but a host app does not
+  name a component class directly. The one exception is the table column value
+  object, which is passed as an argument and renders nothing.
 - **Containers take blocks, leaves take keywords.** Helpers that wrap content
   (page shells, sections, panels, grids, forms, tables) yield a block. Helpers
   that render one thing (a button, a badge, a field, a stat, a bucket) are
@@ -67,6 +69,11 @@ holds the catalog.
 - **Figures are numbers.** Components that measure or compare values, such as
   progress bars, funnels and buckets, do arithmetic on them. Pass a number, not
   a formatted string such as `"9,000"`. A bucket raises on one.
+- **A calculation is text.** The calculation behind a figure is the opposite
+  case. It is a list of groups, each with an optional title and its lines, and
+  each line is a label, the working and the result. They are passed as
+  already-formatted text and shown as written. The component does no
+  arithmetic, and it is closed by default under a quiet summary row.
 - **Semantic color, not literal color.** The themed hue is `accent-*` and the
   themed neutral family is `surface-*`, both CSS custom properties whose
   defaults (blue and zinc) come from the keystone_ui-styles gem. Retheming an
@@ -82,9 +89,10 @@ holds the catalog.
   theme toggle, checkbox row, radio card, option card, file upload and colour
   picker read these variables. So do the data display components: stat card,
   chart card, card link, CTA banner, feature grid, hero, data table, code,
-  accordion, disclosure, tab switcher, progress, funnel, bucket, pipeline and
-  swipe deck. So do the navigation components: navbar, nav item, nav dropdown,
-  bottom nav, mobile header and settings link. A host imports its look after `keystone_source.css`, and a gem ships one through
+  accordion, disclosure, calculation, tab switcher, progress, funnel, bucket,
+  pipeline and swipe deck. So do the navigation components: navbar, nav item,
+  nav dropdown, bottom nav, mobile header and settings link. A host imports its
+  look after `keystone_source.css`, and a gem ships one through
   `tailwind_imports`, both set up through the install local.
 - **Registered looks.** Looks can also be registered by name, and each page
   gets one: the name another gem supplies for the request, then the configured
@@ -100,9 +108,8 @@ holds the catalog.
   gem defines. The theme toggle does not offer it, so a page reaches it when
   another gem supplies it. On a Turbo visit, the page being shown sets the
   theme, so a change to the mode on the server shows up without a full reload.
-  Marking the layout with the theme is set up through
-  the install local, and placing the toggle on a screen goes through the develop
-  local.
+  Marking the layout with the theme is set up through the install local, and
+  placing the toggle on a screen goes through the develop local.
 - **Tailwind classes are static strings.** Class names are never interpolated,
   so Tailwind's scanner can find them. Widths and heights that depend on data,
   such as a progress bar or a bucket's fill, are set with an inline style

data/the_local/agents/keystone_ui-install.md

@@ -151,7 +151,8 @@ built on ViewComponent; hook it in before building any screen with those helpers
    checkbox row, radio card, option card, file upload and colour picker read
    these variables. So do the data display components: stat card, chart card,
    card link, CTA banner, feature grid, hero, data table, code, accordion,
-   disclosure, tab switcher, progress, funnel, bucket, pipeline and swipe deck.
+   disclosure, calculation, tab switcher, progress, funnel, bucket, pipeline and
+   swipe deck.
    So do the navigation components: navbar, nav item, nav dropdown, bottom nav,
    mobile header and settings link. The keystone_ui-styles README lists every
    variable and its default.

data/the_local/interface.yml

@@ -57,6 +57,7 @@ develop:
   - ui_pipeline
   - ui_code
   - ui_disclosure
+  - ui_calculation
   - ui_theme_toggle
   - Keystone::Ui::Column
 
@@ -85,6 +86,7 @@ sources:
   - app/components/keystone/ui/cta_banner_component.rb
   - app/components/keystone/ui/data_table_component.rb
   - app/components/keystone/ui/disclosure_component.rb
+  - app/components/keystone/ui/calculation_component.rb
   - 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.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -87,6 +87,8 @@ files:
 - app/components/keystone/ui/bucket_series_component.rb
 - app/components/keystone/ui/button_component.html.erb
 - app/components/keystone/ui/button_component.rb
+- app/components/keystone/ui/calculation_component.html.erb
+- app/components/keystone/ui/calculation_component.rb
 - app/components/keystone/ui/card_component.html.erb
 - app/components/keystone/ui/card_component.rb
 - app/components/keystone/ui/card_link_component.html.erb