keystone_ui 0.14.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19985a6e534c22e09228551a7b42fdce26c07108512510302e0943d78bbbd220
-  data.tar.gz: 2ab28d0ba73793eada71a4164a876c491c11c48fe34e1e779cd4e47b4e0c5874
+  metadata.gz: 60fbc4a896b71babee643443b4583435ffa85d0b1be67324afdc901169807f68
+  data.tar.gz: e83753c421f5e7095b552fc39776c982c823273665bd10dee5f5a769df39c204
 SHA512:
-  metadata.gz: 3977daa450ed35f50d903ed792260ba8559b52826aca4882941f1c73185dd6b5b99f3fbb007ae7d7b0fc37d866bd0201f162ad979dd4cf409c1f944a34165d4c
-  data.tar.gz: 4598172f5ab465a6c4e81a6b16f1e55206b93a2865598dbbc9d27f49b1bcd7ff029aff2ac104cc9f532bb3774a971324066b83052f244bc1a40848df552ea781
+  metadata.gz: 56fb8e5421b4cb2e9669af2dec0a452ee7c58f316b10f63ce6ea0096ecfd347fbaf01708613a23a00365c9d0e88d7576fbd46c83e13509d5ff9f823f22e9c688
+  data.tar.gz: 70375887467d685ddf82dc96074ec99d3ce43694ad53bf022d315083478e9f21238099528924e133d9bdb425410d8727a8873c8db8119531843fa39a3eb97106

data/app/assets/javascripts/keystone_ui/index.js

@@ -13,6 +13,7 @@ import StatCardInfoController from "keystone_ui/stat_card_info_controller"
 import AutoSubmitController from "keystone_ui/auto_submit_controller"
 import LineChartController from "keystone_ui/line_chart_controller"
 import ThemeToggleController from "keystone_ui/theme_toggle_controller"
+import { keepPageThemeInStep } from "keystone_ui/page_theme"
 
 export function registerControllers(application) {
   application.register("color-picker", ColorPickerController)
@@ -30,6 +31,7 @@ export function registerControllers(application) {
   application.register("auto-submit", AutoSubmitController)
   application.register("line-chart", LineChartController)
   application.register("theme-toggle", ThemeToggleController)
+  keepPageThemeInStep()
 }
 
 export { ColorPickerController, MultiSelectController, SwipeDeckController, ColumnPickerController, FileUploadController, DropdownController, DismissController, ModalController, ClipboardController, TabSwitcherController, AccordionController, StatCardInfoController, AutoSubmitController, LineChartController }

data/app/assets/javascripts/keystone_ui/page_theme.js

@@ -0,0 +1,13 @@
+export function keepPageThemeInStep(page = document) {
+  page.addEventListener("turbo:before-render", ({ detail }) => {
+    const next = detail.newBody.closest("html")
+    if (!next) return
+
+    const theme = next.dataset.theme
+    if (theme) {
+      page.documentElement.dataset.theme = theme
+    } else {
+      delete page.documentElement.dataset.theme
+    }
+  })
+}

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

@@ -19,8 +19,8 @@ module Keystone
       attr_reader :goal, :actual, :label
 
       def initialize(goal:, actual:, label: nil, over: :success)
-        @goal = goal
-        @actual = actual
+        @goal = number(:goal, goal)
+        @actual = number(:actual, actual)
         @label = label
         @over_fill_classes = OVER_GOAL_FILL_CLASSES.fetch(over)
       end
@@ -65,6 +65,12 @@ module Keystone
 
       private
 
+      def number(name, value)
+        return value if value.is_a?(Numeric)
+
+        raise ArgumentError, "#{name} must be a number, got #{value.inspect}"
+      end
+
       def fill_color_classes
         return @over_fill_classes if actual > goal
 

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

@@ -15,7 +15,7 @@
     <textarea name="<%= @attribute %>" rows="3" class="<%= Keystone::Ui::TextareaComponent::BASE_CLASSES %>"<% if @placeholder %> placeholder="<%= @placeholder %>"<% end %>><%= @value %></textarea>
   <% elsif select? %>
     <select name="<%= @attribute %>" class="<%= Keystone::Ui::SelectComponent::BASE_CLASSES %>">
-      <% unless required? %><option value=""></option><% end %>
+      <% unless required? %><option value=""><%= blank_option_text %></option><% end %>
       <% select_options.each do |label, value| %>
         <option value="<%= value %>" <%= "selected" if @value.to_s == value.to_s %>><%= label %></option>
       <% end %>

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

@@ -11,7 +11,7 @@ module Keystone
       CHECKBOX_CLASSES = "ks-checkbox"
       CHECKBOX_WRAPPER_CLASSES = "flex items-center gap-2"
 
-      def initialize(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [])
+      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)
         @attribute = attribute
         @label = label
         @type = type
@@ -24,6 +24,7 @@ module Keystone
         @value = value
         @options = options
         @errors = Array(errors)
+        @include_blank = include_blank.to_s
       end
 
       def label_text
@@ -66,6 +67,10 @@ module Keystone
         @options
       end
 
+      def blank_option_text
+        @include_blank
+      end
+
       def input_options
         options = { name: @attribute.to_s, class: Keystone::Ui::InputComponent::BASE_CLASSES }
         unless textarea?

data/config/importmap.rb

@@ -14,6 +14,7 @@ pin "keystone_ui/stat_card_info_controller", to: "keystone_ui/stat_card_info_con
 pin "keystone_ui/auto_submit_controller", to: "keystone_ui/auto_submit_controller.js"
 pin "keystone_ui/line_chart_controller", to: "keystone_ui/line_chart_controller.js"
 pin "keystone_ui/theme_toggle_controller", to: "keystone_ui/theme_toggle_controller.js"
+pin "keystone_ui/page_theme", to: "keystone_ui/page_theme.js"
 
 # Chart.js for the line-chart controller, so host apps don't pin it themselves.
 # Vendored as a single self-contained bundle (deps inlined, no external imports).

data/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.14.0"
+  VERSION = "0.15.1"
 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, dashboards, charts, marketing sections — 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, dashboards, charts, 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
 ---
@@ -89,6 +89,12 @@ outer element. See Conventions before using it.
 - `ui_mobile_actions` — no keywords, takes a block. An ellipsis dropdown for
   mobile actions; the block holds the menu items. Hidden above `lg:`.
 - `ui_settings_link(label:, href:)` — a full-width settings row with a chevron.
+- `ui_theme_toggle` — no keywords, no block. A row of three buttons, Light, Dark
+  and System, that switches the page's theme at once and remembers the choice in
+  the `keystone_theme` cookie for a year. System follows the operating system.
+  The button for the page's current mode renders pressed. When the current mode
+  is a custom palette supplied by another gem, no button is pressed, because the
+  toggle does not offer custom.
 
 ### Forms
 
@@ -96,7 +102,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: [])`
+- `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)`
   — 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
@@ -104,7 +110,9 @@ outer element. See Conventions before using it.
   pass `label:` whenever the attribute is a nested name. `label:` defaults to the
   attribute with underscores turned to spaces and the first letter capitalized.
   `options:` is for `:select` and takes `[[label, value], ...]`; `value:` picks
-  the selected option, and a non-required select gets a leading blank option. A
+  the selected option, and a non-required select gets a leading empty option,
+  worded by `include_blank:` (for example `"Not set yet"`) or left blank without
+  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.
@@ -229,8 +237,12 @@ outer element. See Conventions before using it.
 - `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.
-  `goal` and `actual` are printed exactly as given, so pass numbers already
-  formatted as needed. The percent is `actual / goal * 100` rounded and **not**
+  `goal` and `actual` must be numbers: a string such as `"9,000"`, or `nil`,
+  raises `ArgumentError` at render time. They are printed as Ruby prints them,
+  with no thousands separators, so `9000` shows as `9000` and `9000.0` as
+  `9000.0`. A value read from a decimal column is a `BigDecimal`, which prints
+  as `0.9e4`, so convert it with `to_i` or `to_f` first. The percent is
+  `actual / goal * 100` rounded and **not**
   clamped (so 150% shows as 150%), and it is 0 when `goal` is zero. The fill
   stops at the top once the goal is reached. Within the goal the fill uses the
   accent colour; over it the fill turns green with `over: :success` or amber with
@@ -301,7 +313,15 @@ outer element. See Conventions before using it.
    routes or a persistence strategy — put the choice to the developer, then
    implement what they pick.
 
-8. Read back what you wrote and delete every Tailwind class and inline `style`
+8. To let users pick light or dark, place `ui_theme_toggle`. Where it goes — a
+   settings screen, the navbar's `desktop_right` or a mobile menu — is the
+   developer's choice, so ask before placing it. It only stays correct across
+   page loads and Turbo visits when the app's layout already writes the theme
+   onto its `html` tag and the gem's Stimulus controllers are registered. If the
+   layout's `<html` tag carries nothing for the theme, stop and hand that part to
+   `keystone_ui-install`.
+
+9. Read back what you wrote and delete every Tailwind class and inline `style`
    you added. If the result still needs one, that is a signal the wrong helper
    was chosen — go back to step 5. Bring it to the developer only if no helper
    fits.

data/the_local/agents/keystone_ui-info.md

@@ -47,8 +47,9 @@ holds the catalog.
 
 ## Conventions
 
-- **Helpers, not classes.** Every entry point is a view helper prefixed `ui_`,
-  called from ERB. Components live under the `Keystone::Ui` namespace, but a
+- **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.
 - **Containers take blocks, leaves take keywords.** Helpers that wrap content
@@ -63,6 +64,9 @@ 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
+  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.
 - **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
@@ -75,7 +79,11 @@ holds the catalog.
   cookie, then a mode another gem supplies, then light. System leaves the page
   to follow the operating system. Custom marks the page for a palette another
   gem defines. The theme toggle does not offer it, so a page reaches it when
-  another gem supplies it.
+  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.
 - **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

@@ -24,6 +24,11 @@ built on ViewComponent; hook it in before building any screen with those helpers
   custom mode),
   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.
 
 ## How to use it
 
@@ -61,8 +66,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
      `import { registerControllers } from "keystone_ui/index"` and
      `registerControllers(application)`.
    - `app/views/layouts/application.html.erb` — adds
-     `<%= keystone_theme_attributes %>` inside the `<html` tag, which writes the
-     light, dark or custom mode onto the page.
+     `<%= keystone_theme_attributes %>` directly after the first `<html` in the
+     file, so the tag reads `<html <%= keystone_theme_attributes %> ...>`. A
+     layout that already contains the call is left unchanged.
 
    Read its output for two warnings:
 
@@ -70,6 +76,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
      the Stimulus application is set up and add those two lines there. Without
      them, dropdowns, modals, file uploads, the column picker, the theme toggle
      and the other interactive components do nothing.
+     `registerControllers(application)` also copies `data-theme` from each page
+     Turbo renders onto the `<html>` tag. Without it, a Turbo visit keeps the
+     theme of the first page loaded.
    - `app/views/layouts/application.html.erb not found` — ask the developer which
      layout the app renders and add `<%= keystone_theme_attributes %>` to its
      `<html>` tag. Without it, a saved light or dark choice is not applied when

data/the_local/interface.yml

@@ -3,6 +3,7 @@ scope: UI — pages, forms, tables, navigation, dashboards
 install:
   - bin/rails generate keystone:install
   - KeystoneUi.configure
+  - keystone_theme_attributes
 
 develop:
   - ui_accordion
@@ -56,11 +57,13 @@ develop:
   - ui_pipeline
   - ui_code
   - ui_disclosure
+  - ui_theme_toggle
   - Keystone::Ui::Column
 
 sources:
   - lib/generators/keystone/install_generator.rb
   - lib/keystone_ui/configuration.rb
+  - lib/keystone_ui/theme_choice.rb
   - app/helpers/keystone_ui_helper.rb
   - app/components/keystone/ui/accordion_component.rb
   - app/components/keystone/ui/alert_component.rb
@@ -105,6 +108,7 @@ sources:
   - app/components/keystone/ui/page_header_component.rb
   - app/components/keystone/ui/panel_component.rb
   - app/components/keystone/ui/pipeline_component.rb
+  - app/components/keystone/ui/theme_toggle_component.rb
   - app/components/keystone/ui/progress_component.rb
   - app/components/keystone/ui/radio_card_component.rb
   - app/components/keystone/ui/section_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Tyler Schneider
@@ -64,6 +64,7 @@ files:
 - app/assets/javascripts/keystone_ui/line_chart_controller.js
 - app/assets/javascripts/keystone_ui/modal_controller.js
 - app/assets/javascripts/keystone_ui/multi_select_controller.js
+- app/assets/javascripts/keystone_ui/page_theme.js
 - app/assets/javascripts/keystone_ui/stat_card_info_controller.js
 - app/assets/javascripts/keystone_ui/swipe_deck_controller.js
 - app/assets/javascripts/keystone_ui/tab_switcher_controller.js