keystone_ui 0.30.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53f39974ced2866fb949b3bfbe0e1be0359977df8a890f9bf83e20b8a04cff11
-  data.tar.gz: 7dc3d1ae90c88bd89ccff1c67a861f6e391558605edb5aaaa136f3c674e47cb6
+  metadata.gz: 530dc14cf871e579dcccc21f769b304974a36af552e10e2a9eee6f0b90e531ae
+  data.tar.gz: 69ed4079d0a6fb130e50ba08afdf4b6c1ba37d8f25b035b06e686bdccdd5f1a3
 SHA512:
-  metadata.gz: ce349e68888fb9085cf9475eb3a96cb6dec23e193df5912905e559f5371dcb7d936d7e6b80a09d820fa28a91da0993c67add11578729dd37e62f25b3d7bac787
-  data.tar.gz: 37cfadba853c471e4ba8a4e9cf94c941e9a554151a76ba9bba4573b80bf80b49850ac713a55da7f148b3aabd6fb253a36b1089c5c132f0afa86d1072aa6e6216
+  metadata.gz: 4d2f5fc1618dbe5b16114c4475d8b0e987f8e0516ed80aecfaace0741ccdad791214ffa758dd65c742d946285b26277c1345963ff9e1fa7175b9b1ff67d21f67
+  data.tar.gz: bb6877b8c6e890e4010b679ad81fa07e00bde9ccbfc73d983d666c0a97ed8182833d150c7e4535e095e1ff5d98ffe7aa3c8cab067b366e2db7c313e6b29baa00

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

@@ -6,10 +6,10 @@ module Keystone
       EMPTY_CELL_CLASSES = "ks-table-cell-middle text-sm"
       BODY_CLASSES = "ks-table-body"
       HEAD_CLASSES = "ks-table-head"
-      WRAPPER_CLASSES = "ks-table overflow-hidden"
+      WRAPPER_CLASSES = "ks-table overflow-x-auto"
       HEADER_CLASSES_FIRST = "ks-table-header ks-table-header-first text-left text-sm"
       HEADER_CLASSES_MIDDLE = "ks-table-header ks-table-header-middle text-left text-sm"
-      HEADER_CLASSES_LAST = "ks-table-header-last"
+      HEADER_CLASSES_LAST = "ks-table-header ks-table-header-last text-right text-sm"
 
       ROW_CLASSES_FIRST = "ks-table-cell-first text-sm whitespace-nowrap"
       ROW_CLASSES_MIDDLE = "ks-table-cell-middle text-sm whitespace-nowrap"

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

@@ -0,0 +1 @@
+<span class="<%= classes %>"><%= text %></span>

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class FigureComponent < ViewComponent::Base
+      TONES = {
+        neutral: nil,
+        success: "ks-tone-success",
+        danger: "ks-tone-danger"
+      }.freeze
+
+      def initialize(text:, tone: :neutral)
+        @text = text
+        @tone = tone
+      end
+
+      attr_reader :text
+
+      def classes
+        [ "ks-figure", TONES.fetch(@tone) ].compact.join(" ")
+      end
+    end
+  end
+end

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

@@ -1,14 +1,35 @@
-<div class="<%= container_classes %>">
-  <% layers.each do |layer| %>
-    <% if layer.conversion_percent %>
-      <div class="<%= transition_classes %>">↓ <%= layer.conversion_percent %>%</div>
-    <% end %>
-    <div class="<%= layer_classes %>">
-      <div class="<%= row_classes %>">
-        <span class="<%= label_classes %>"><%= layer.label %></span>
+<% if joined? %>
+  <div class="<%= JOINED_CLASSES %>">
+    <% layers.each do |layer| %>
+      <% if layer.conversion_percent %>
+        <div></div>
+        <div class="<%= BAND_ROW_CLASSES %>">
+          <div class="<%= BAND_CLASSES %>" style="clip-path: <%= band_clip_path(layer) %>"></div>
+          <div class="<%= BAND_LABEL_ROW_CLASSES %>"><span class="<%= BAND_LABEL_CLASSES %>"><%= layer.conversion_percent %>%</span></div>
+        </div>
+      <% end %>
+      <div class="<%= WORDS_CLASSES %>">
         <span class="<%= value_classes %>"><%= layer.value %></span>
+        <span class="<%= label_classes %>"><%= layer.label %></span>
+      </div>
+      <div class="<%= BLOCK_CLASSES %>">
+        <div class="<%= BLOCK_FILL_CLASSES %> <%= layer.color_classes %>" style="width: <%= layer.width_percent %>%"></div>
       </div>
-      <div class="<%= bar_classes %> <%= layer.color_classes %>" style="width: <%= layer.width_percent %>%"></div>
-    </div>
-  <% end %>
-</div>
+    <% end %>
+  </div>
+<% else %>
+  <div class="<%= container_classes %>">
+    <% layers.each do |layer| %>
+      <% if layer.conversion_percent %>
+        <div class="<%= transition_classes %>">↓ <%= layer.conversion_percent %>%</div>
+      <% end %>
+      <div class="<%= layer_classes %>">
+        <div class="<%= row_classes %>">
+          <span class="<%= label_classes %>"><%= layer.label %></span>
+          <span class="<%= value_classes %>"><%= layer.value %></span>
+        </div>
+        <div class="<%= bar_classes %> <%= layer.color_classes %>" style="width: <%= layer.width_percent %>%"></div>
+      </div>
+    <% end %>
+  </div>
+<% end %>

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

@@ -3,7 +3,7 @@
 module Keystone
   module Ui
     class FunnelComponent < ViewComponent::Base
-      Layer = Struct.new(:label, :value, :width_percent, :conversion_percent, :color_classes, keyword_init: true)
+      Layer = Struct.new(:label, :value, :width_percent, :conversion_percent, :color_classes, :previous_width_percent, keyword_init: true)
 
       CONTAINER_CLASSES = "ks-funnel"
       LAYER_CLASSES = "ks-funnel-layer"
@@ -12,6 +12,14 @@ module Keystone
       VALUE_CLASSES = "ks-funnel-value text-sm tabular-nums"
       BAR_CLASSES = "ks-funnel-bar h-8 transition-all"
       TRANSITION_CLASSES = "ks-funnel-transition text-center text-xs"
+      BAND_LABEL_ROW_CLASSES = "absolute inset-0 flex items-center justify-center"
+      BAND_ROW_CLASSES = "relative h-7"
+      BLOCK_FILL_CLASSES = "h-full"
+      BLOCK_CLASSES = "flex justify-center h-12"
+      WORDS_CLASSES = "flex flex-col justify-center"
+      BAND_LABEL_CLASSES = "ks-funnel-band-label text-xs"
+      BAND_CLASSES = "ks-funnel-band absolute inset-0"
+      JOINED_CLASSES = "ks-funnel-joined grid grid-cols-[max-content_1fr]"
       STEP_COLOR_CLASSES = {
         accent: "ks-funnel-bar-accent",
         sky: "ks-funnel-bar-sky",
@@ -20,10 +28,24 @@ module Keystone
         rose: "ks-funnel-bar-rose"
       }.freeze
 
-      attr_reader :steps
+      attr_reader :steps, :shape
+
+      def initialize(steps:, shape: :bars)
+        raise ArgumentError, "a funnel's shape is :bars or :joined, got #{shape.inspect}" unless %i[bars joined].include?(shape)
 
-      def initialize(steps:)
         @steps = steps
+        @shape = shape
+      end
+
+      def joined?
+        shape == :joined
+      end
+
+      def band_clip_path(layer)
+        top = (100 - layer.previous_width_percent) / 2.0
+        bottom = (100 - layer.width_percent) / 2.0
+
+        "polygon(#{format("%g%%", top)} 0, #{format("%g%%", 100 - top)} 0, #{format("%g%%", 100 - bottom)} 100%, #{format("%g%%", bottom)} 100%)"
       end
 
       def layers
@@ -35,7 +57,8 @@ module Keystone
             value: step[:value],
             width_percent: width_percent(step[:value]),
             conversion_percent: conversion_percent(step[:value], previous),
-            color_classes: color_classes(step[:color], index)
+            color_classes: color_classes(step[:color], index),
+            previous_width_percent: previous && width_percent(previous)
           )
           previous = step[:value]
           layer

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

@@ -1,4 +1,4 @@
-<span class="inline-flex" data-controller="info" data-action="click@window->info#hide scroll@window->info#close">
+<span class="<%= wrapper_classes %>" data-controller="info" data-action="click@window->info#hide scroll@window->info#close">
   <button type="button" class="<%= button_classes %>" data-info-target="button" data-action="mouseenter->info#peek mouseleave->info#unpeek click->info#toggle" aria-label="More about this"><%= icon.html_safe %></button>
   <span class="<%= summary_classes %>" data-info-target="summary"><%= summary %></span>
   <% if content? %>

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

@@ -14,6 +14,12 @@ module Keystone
 
       attr_reader :summary
 
+      WRAPPER_CLASSES = "inline-flex align-middle"
+
+      def wrapper_classes
+        WRAPPER_CLASSES
+      end
+
       def summary_classes
         SUMMARY_CLASSES
       end

data/app/helpers/keystone_ui_helper.rb

@@ -229,6 +229,10 @@ module KeystoneUiHelper
     render Keystone::Ui::CalculationComponent.new(**args)
   end
 
+  def ui_figure(**args)
+    render Keystone::Ui::FigureComponent.new(**args)
+  end
+
   def ui_info(**args, &block)
     render(Keystone::Ui::InfoComponent.new(**args), &block)
   end

data/lib/keystone_ui/safelist.rb

@@ -14,6 +14,7 @@ module Keystone
       Keystone::Ui::LineChartComponent,
       Keystone::Ui::CtaBannerComponent,
       Keystone::Ui::FeatureGridComponent,
+      Keystone::Ui::FigureComponent,
       Keystone::Ui::HeroComponent,
       Keystone::Ui::ModalComponent,
       Keystone::Ui::SelectComponent,

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -1,6 +1,6 @@
 ---
 name: keystone_ui-develop
-description: Use PROACTIVELY for building or editing screens in a Rails app that has Keystone UI — pages, forms, tables, navigation, action menus for a record's Edit and Delete, dashboards, charts, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
+description: Use PROACTIVELY for building or editing screens in a Rails app that has Keystone UI — pages, forms, tables, navigation, action menus for a record's Edit and Delete, dashboards, charts, amounts shown in green or red as a gain or loss, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
 tools: Read, Write, Edit, Grep
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -213,7 +213,9 @@ outer element. See Conventions before using it.
   `columns:` accepts plain `{ key: "Label" }` hashes or `Keystone::Ui::Column`
   objects. In the block, `table.link(:column_key) { |item| url }` turns that
   column's cells into links and `table.actions { |item| ... }` appends a
-  right-aligned actions column. Each row's actions render inside an action
+  right-aligned actions column. With no actions column, the last data
+  column's header and cells are both right-aligned, so put the column of
+  amounts last to line them up under their header. Each row's actions render inside an action
   menu, so the `actions` block holds `ui_action_menu_item` calls and nothing
   else, never buttons or bare links. Sorting requires all three of `sort:` (the
   current column key), `sort_direction:` (`:asc`/`:desc`), and `sort_url:` (a
@@ -238,6 +240,13 @@ outer element. See Conventions before using it.
   only to the button form.
 - `ui_badge(label:, variant: :neutral, class: nil)` — a pill. `variant:`
   `:neutral` `:success` `:danger` `:warning` `:info`.
+- `ui_figure(text:, tone: :neutral)` — no block. One figure, such as an amount,
+  as inline text with no pill or box around it. `tone:` `:neutral` prints it in
+  the surrounding text colour, `:success` in green and `:danger` in red; any
+  other symbol raises `KeyError`. `text:` is printed as given, so format
+  numbers, currency and any minus sign before passing it. Its output can be
+  passed anywhere a string is shown, such as a `ui_data_table` cell value or
+  column label.
 - `ui_alert(message:, type: :info, title: nil, dismissible: false, class: nil)` —
   a banner.
   `type:` `:info` `:success` `:warning` `:error`. `dismissible: true` adds a
@@ -270,7 +279,8 @@ outer element. See Conventions before using it.
   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
+  readers, placed inline beside the thing it explains, and sits level with the
+  middle of the text beside it. `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
@@ -337,13 +347,20 @@ outer element. See Conventions before using it.
   the last, marks only whole days, and reads each day as a date such as
   "Oct 2, 2026", which is also the heading a hovered point shows. The time of
   day is dropped, so pass one value per day.
-- `ui_funnel(steps:)` — a conversion funnel. `steps:` is
-  `[{ label:, value:, color: }, ...]` in order, with `color:` optional. Bar
-  widths are relative to the first step; the caption between two layers is the
-  step-to-step conversion. Each bar takes the next colour in the order
-  `:accent` `:sky` `:violet` `:amber` `:rose`, starting again after `:rose`; a
-  step passing one of those symbols as `color:` uses it instead, and any other
-  symbol raises. Divide-by-zero safe, no JavaScript.
+- `ui_funnel(steps:, shape: :bars)` — a conversion funnel. `steps:` is
+  `[{ label:, value:, color: }, ...]` in order, with `color:` optional. Each
+  step's width is its value as a share of the first step's value, and the
+  percent shown between two steps is the second step's value divided by the
+  first's. Each step takes the next colour in the order `:accent` `:sky`
+  `:violet` `:amber` `:rose`, starting again after `:rose`; a step passing one
+  of those symbols as `color:` uses it instead, and any other symbol raises.
+  Values are printed as given. Divide-by-zero safe, no JavaScript. `shape:`
+  `:bars` draws one bar per step, left-aligned, with the label and value on a
+  row above it and a `↓ N%` caption between two bars. `shape: :joined` draws
+  one shape: each step's value over its label in a column on the left, each
+  step's block centred at its width, and between two blocks a neutral band
+  that narrows from the block above to the block below, with the percent on it.
+  Any other `shape:` raises `ArgumentError`.
 - `ui_bucket(goal:, actual:, label: nil, over: :success)` — an upright container
   for one target, filled from the bottom toward `goal:`. It shows the optional
   `label` on top, then `goal`, the container, `actual`, and the percent reached.
@@ -446,6 +463,13 @@ outer element. See Conventions before using it.
    text with no columns and no separate total, the app's keystone_ui-styles
    version does not define the `ks-breakdown` classes, so stop and hand that
    part to `keystone_ui-install` as well, and add no classes to fix it.
+   To show an amount as a gain or a loss, use `ui_figure` with `tone:` rather
+   than a `ui_badge` or a colour class. Which amounts are coloured, and whether
+   a value counts as a gain or a loss, is the app's own rule, so ask the
+   developer rather than pick. If a figure with `:success` or `:danger` shows in
+   the plain text colour, the app's keystone_ui-styles version does not define
+   the `ks-figure` and `ks-tone-*` classes, so stop and hand that part to
+   `keystone_ui-install`, and add no classes to fix it.
    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
@@ -459,6 +483,12 @@ outer element. See Conventions before using it.
    its neighbours rather than a point at zero. Whether a missing day is left
    out or passed as a zero is the app's own rule, so ask the developer rather
    than pick. Never format dates into strings and pass them as `labels:`.
+   For a funnel, whether it is drawn as separate bars or as one joined shape
+   is the developer's choice, so ask before passing `shape:`. If a joined
+   funnel shows its blocks but no band between them, the app's
+   keystone_ui-styles version does not define the `ks-funnel-band` classes, so
+   stop and hand that part to `keystone_ui-install`, and add no classes to fix
+   it.
    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.

data/the_local/agents/keystone_ui-info.md

@@ -15,7 +15,7 @@ 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, a breakdown of amounts and their
-total, an info button — instead of hand-written ERB and
+total, a figure coloured as a gain or a loss, 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,7 +88,8 @@ holds the catalog.
   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.
+  button sits on the line with the label. Wherever it is placed, the button
+  sits level with the text beside it.
 - **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.
@@ -113,6 +114,15 @@ holds the catalog.
   of its own, so a breakdown looks right only with a keystone_ui-styles version
   that defines those classes. It has no button and no hidden state of
   its own, and it can be placed inside an info button's detail.
+- **A toned figure is text.** A figure shows one amount inline, in plain text
+  or in the success or danger colour, so it reads as a gain or a loss without a
+  badge around it. The amount is passed as already-formatted text and shown as
+  written, and the tone is chosen by name. An unknown tone raises at render
+  time. The colours come from keystone_ui-styles, so a figure shows its tone
+  only with a keystone_ui-styles version that defines those classes.
+- **The last table column is right-aligned.** In a data table with no actions
+  column, the last column's header is right-aligned like the cells beneath it,
+  so a figure or total placed in that header lines up with the figures below.
 - **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
@@ -126,9 +136,16 @@ holds the catalog.
   different symbols, and the develop local carries the real values. Most
   components raise on a symbol they do not know, so a wrong guess fails at
   render time.
-- **Figures are numbers.** Components that measure or compare values, such as
+- **Measured values 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 funnel has two shapes.** Both size each step against the first step and
+  show the percent carried from one step to the next. The default draws one bar
+  per step, each with its label and value on a row above it. The joined shape
+  draws the steps as one figure: each step's value and label sit in a column on
+  the left, each step is a block centred at its width, and a neutral band
+  between two blocks narrows from one width to the next and holds the percent.
+  Any other shape raises `ArgumentError`. Neither shape needs JavaScript.
 - **A line chart is labelled or dated.** A line chart draws one line per
   series, and each series is a name and its values, with an optional colour
   and an optional dashed line. Its horizontal axis is given one of two ways,

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.9.0 or later with it.
+   host app. The gem brings ViewComponent and keystone_ui-styles 0.10.0 or later with it.
    Tailwind does not have to be initialized first, because the generator creates
    the stylesheet if it is missing.
 
@@ -153,7 +153,7 @@ 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, calculation, info button, breakdown, tab switcher, progress,
+   disclosure, calculation, info button, breakdown, figure, 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 desktop "Back" link and the breadcrumbs

data/the_local/interface.yml

@@ -62,11 +62,13 @@ develop:
   - ui_disclosure
   - ui_calculation
   - ui_info
+  - ui_figure
   - ui_breakdown
   - ui_theme_toggle
   - Keystone::Ui::Column
 
 sources:
+  - app/components/keystone/ui/figure_component.rb
   - lib/generators/keystone/install_generator.rb
   - lib/keystone_ui/configuration.rb
   - lib/keystone_ui/missing_back_link.rb
@@ -112,6 +114,7 @@ sources:
   - app/components/keystone/ui/breadcrumbs_component.rb
   - app/components/keystone/ui/breadcrumbs_component.html.erb
   - app/components/keystone/ui/funnel_component.rb
+  - app/components/keystone/ui/funnel_component.html.erb
   - app/components/keystone/ui/bucket_component.rb
   - app/components/keystone/ui/bucket_series_component.rb
   - app/components/keystone/ui/grid_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +125,8 @@ files:
 - app/components/keystone/ui/disclosure_component.rb
 - app/components/keystone/ui/feature_grid_component.html.erb
 - app/components/keystone/ui/feature_grid_component.rb
+- app/components/keystone/ui/figure_component.html.erb
+- app/components/keystone/ui/figure_component.rb
 - app/components/keystone/ui/file_upload_component.html.erb
 - app/components/keystone/ui/file_upload_component.rb
 - app/components/keystone/ui/form_component.html.erb