keystone_ui 0.31.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6c7e18e911657e41ed1a4eff2133400015bd7a58e0c437f6886d219173f01fa
-  data.tar.gz: 91b2f652bb7313d9cda361e126e969d06b64827e80118888a73cce3840471f68
+  metadata.gz: 530dc14cf871e579dcccc21f769b304974a36af552e10e2a9eee6f0b90e531ae
+  data.tar.gz: 69ed4079d0a6fb130e50ba08afdf4b6c1ba37d8f25b035b06e686bdccdd5f1a3
 SHA512:
-  metadata.gz: 466ea8fbb32ed4683db9537a52d7ba41d667f79dfa52aec27aaab85f5fc14b872fcc03b7d880136936133685fdc1af5f839aa4392c5ba698af62694e4a5832b0
-  data.tar.gz: 435630df203142fa669f0d93333e6b2637b2d4ec2d25b6e8fa1a7aa00e54ba5fdace3a3416905c144f706f18373ad78b8b11c067f5d1a62ee6453655358b4b77
+  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/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.31.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
@@ -453,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

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,7 +136,7 @@ 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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -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