keystone_ui 0.17.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0dc7211df561f52f213d69e2733292b883fd7bb31cb6bc203ba581e90c5022
-  data.tar.gz: e95919dc9707abaae6d12837d193ace1bed9a16b8f5d00c0758f0f2a6c82cf23
+  metadata.gz: 19d3d7682e2b19ea8bdeadd90f50b0668db2587e21c891c220fdbb5af56a3780
+  data.tar.gz: dafd5905c87e5723538ffd9f581b3e6edafe6d8a248a5364580191350778fe82
 SHA512:
-  metadata.gz: 6f0ccf38449bfa1c327f0abfc4e4bf818f80859a90ff19a6a5f680b43ba6790de67502d218ba7cfba32a019ff1ee96c4ab0653ffaca5bfaa97b6beb226110d18
-  data.tar.gz: 6019b1917c3736e6323cf5c924be7e0a7e5a2d3686aa3d371bf520f548046e7a7bdf42dccc6afcc5664693d558c77482cf4f7061c05fc383e81e6effd48ecb7e
+  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

@@ -46,7 +46,7 @@ module KeystoneUiHelper
   end
 
   def keystone_theme_attributes
-    keystone_theme_choice.html_attributes_markup.html_safe
+    keystone_theme_choice.html_attributes.merge(keystone_look_choice.html_attributes).map { |name, value| %(#{name}="#{value}") }.join(" ").html_safe
   end
 
   def ui_copy_button(**args)
@@ -213,9 +213,18 @@ 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
     KeystoneUi::ThemeChoice.new(cookies[KeystoneUi::ThemeChoice::COOKIE], supplied: KeystoneUi.configuration.supplied_theme_mode(self))
   end
+
+  def keystone_look_choice
+    config = KeystoneUi.configuration
+    KeystoneUi::LookChoice.new(looks: config.looks.keys, default: config.default_look, supplied: config.supplied_look(self))
+  end
 end

data/lib/keystone_ui/configuration.rb

@@ -2,14 +2,28 @@
 
 module KeystoneUi
   class Configuration
-    attr_accessor :accent, :surface, :theme_mode_supplier
-    attr_reader :tailwind_imports, :tailwind_sources
+    attr_accessor :accent, :surface, :theme_mode_supplier, :look_supplier
+    attr_reader :tailwind_imports, :tailwind_sources, :looks, :default_look
 
     def initialize
       @accent = :blue
       @surface = :zinc
       @tailwind_imports = []
       @tailwind_sources = []
+      @looks = {}
+    end
+
+    def default_look=(name)
+      @default_look = name&.to_s
+    end
+
+    def register_look(name, path)
+      @looks[name.to_s] = path.to_s
+      @tailwind_imports << path.to_s
+    end
+
+    def supplied_look(view)
+      look_supplier&.call(view)&.to_s
     end
 
     def supplied_theme_mode(view)

data/lib/keystone_ui/look_choice.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class LookChoice
+    def initialize(looks:, default:, supplied: nil)
+      @looks = looks
+      @default = default
+      @supplied = supplied
+    end
+
+    def name
+      [ @supplied, @default ].find { |candidate| @looks.include?(candidate) }
+    end
+
+    def html_attributes
+      name ? { "data-look" => name } : {}
+    end
+  end
+end

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.17.0"
+  VERSION = "0.19.0"
 end

data/lib/keystone_ui.rb

@@ -4,6 +4,7 @@ require "view_component"
 require "keystone_ui/styles"
 require "keystone_ui/configuration"
 require "keystone_ui/theme_choice"
+require "keystone_ui/look_choice"
 require "keystone_ui/engine"
 require "keystone_ui/version"
 

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,10 +89,18 @@ 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
+  default, each used only when registered. The layout's `<html>` tag carries
+  `data-look="<name>"`, and a registered look file scopes its variables to
+  `:root[data-look="<name>"]`. A host with no registered looks gets no
+  `data-look`. Registering and choosing looks is set up through the install
+  local.
 - **Light, dark, system and custom themes.** Every component has dark-mode
   styling. The theme is chosen in this order: the user's choice stored in a
   cookie, then a mode another gem supplies, then light. System leaves the page
@@ -93,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

@@ -1,6 +1,6 @@
 ---
 name: keystone_ui-install
-description: Use to hook Keystone UI into a project — adding the gem, running the install generator to wire Tailwind, the Stimulus controllers and the layout's theme attributes, and configuring the palette, the theme mode supplier and extra Tailwind imports and sources.
+description: Use to hook Keystone UI into a project — adding the gem, running the install generator to wire Tailwind, the Stimulus controllers and the layout's theme attributes, and configuring the palette, the theme mode supplier, registered looks and extra Tailwind imports and sources.
 tools: Bash, Read, Edit
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -22,13 +22,18 @@ built on ViewComponent; hook it in before building any screen with those helpers
   `surface` (palette names, `:blue` and `:zinc` unless set),
   `theme_mode_supplier` (a callable that supplies a light, dark, system or
   custom mode),
+  `register_look` (a look's CSS file by name), `default_look` and
+  `look_supplier` (which registered look a page gets),
   and the `tailwind_imports` and `tailwind_sources` lists (extra CSS files and
   scan paths added to the Tailwind build).
 - `keystone_theme_attributes` — a layout helper placed inside the `<html>` tag.
   It writes `data-theme="light"`, `data-theme="dark"` or `data-theme="custom"`
   for the page's mode, and writes nothing for system so the page follows the
   operating system. The mode is the `keystone_theme` cookie's choice, then the
-  configured `theme_mode_supplier`, then light.
+  configured `theme_mode_supplier`, then light. It also writes
+  `data-look="<name>"` for the page's look: the `look_supplier`'s name, then
+  `default_look`, each used only when registered. With no look registered it
+  writes no `data-look`.
 
 ## How to use it
 
@@ -146,11 +151,15 @@ 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.
 
+   To offer several looks and choose one per page, register them by name in
+   step 7 rather than importing them here.
+
 7. Write `config/initializers/keystone_ui.rb` only if one of the settings below
    is wanted. Ask the developer about each rather than adding any by default.
    The engine reads the configuration after initializers have run, so this file
@@ -163,6 +172,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
      config.accent = :emerald
      config.surface = :slate
      config.theme_mode_supplier = ->(view) { view.current_user&.theme }
+     config.register_look :compact, "/absolute/path/to/compact.css"
+     config.default_look = :compact
+     config.look_supplier = ->(view) { view.current_user&.look }
      config.tailwind_imports << "/absolute/path/to/extra.css"
      config.tailwind_sources << "/absolute/path/to/components/**/*.{erb,rb}"
    end
@@ -180,6 +192,14 @@ built on ViewComponent; hook it in before building any screen with those helpers
      `data-theme="custom"`. The theme toggle does not offer custom, so only a
      supplier sets it. Ask the developer which gem or code supplies custom and
      its colors before returning it.
+   - `register_look :name, path` — registers a look file by name and appends it
+     to `tailwind_imports`, so `keystone_source.css` imports it. A look offered
+     this way scopes its variables to `:root[data-look="<name>"]` instead of
+     `:root`, so several can be imported at once.
+   - `default_look = :name` — the look a page gets when nothing else chooses one.
+   - `look_supplier` — a callable that receives the view and returns a look
+     name for the request. A name that is not registered, or `nil`, leaves the
+     page on the default look.
    - `tailwind_imports` and `tailwind_sources` — lists to append to, never
      assign. Each import becomes an `@import` line and each source becomes an
      `@source` line in `keystone_source.css` on the next boot. They are for

data/the_local/interface.yml

@@ -57,6 +57,7 @@ develop:
   - ui_pipeline
   - ui_code
   - ui_disclosure
+  - ui_calculation
   - ui_theme_toggle
   - Keystone::Ui::Column
 
@@ -64,6 +65,7 @@ sources:
   - lib/generators/keystone/install_generator.rb
   - lib/keystone_ui/configuration.rb
   - lib/keystone_ui/theme_choice.rb
+  - lib/keystone_ui/look_choice.rb
   - app/helpers/keystone_ui_helper.rb
   - app/components/keystone/ui/accordion_component.rb
   - app/components/keystone/ui/alert_component.rb
@@ -84,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.17.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
@@ -184,6 +186,7 @@ files:
 - lib/keystone_ui/configuration.rb
 - lib/keystone_ui/engine.rb
 - lib/keystone_ui/leftover_stylesheet.rb
+- lib/keystone_ui/look_choice.rb
 - lib/keystone_ui/safelist.rb
 - lib/keystone_ui/source_css.rb
 - lib/keystone_ui/theme_choice.rb