keystone_ui 0.12.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 702c1e314aec36dbb95ed4f5541c4bdab916eba0e92f19a85f74ff641ed183f0
-  data.tar.gz: 0252fa96678cb96ab89cae69ad368cc5139ef30ea3c2f8c4ffdfe880a1e511e9
+  metadata.gz: 903dfcff87cb63fce06692a39fb26b73af673f562f28f3b3ebf72b13b5280642
+  data.tar.gz: 7db5a26e387cc0c2b11a311c70e967ec977f5b1636c6d38bf8a42b28d5ffbd9a
 SHA512:
-  metadata.gz: 9e8be46029fad363c665045bec462c689ceeec5c5b31a4cdec2de99e1a0f661506d8dcc09585d4a1457c201174de5f46ff9bd730524fba0506b0403b28bf4bff
-  data.tar.gz: 22301b268679a53f5c128a1ef20b921cddedf8532f279e3c8065379d72e4a5eaeb64a27f0702bd06593ee4bcd224ab57d468c6c12f6748294061ed9634991021
+  metadata.gz: 574997b044dfcbb23b6aad3e74065b041d549d1be5a8629f5c08f792720f1fda5d988340516caa581f80c1455fcc3a32080174b8056f06a41c4fa58423236cbb
+  data.tar.gz: 30a7877baf982039cff72b9c8ad0dc879a8fdbc8362d8ec15cec9b7b48964aa8dc1786494b25e3c131e1c28a2c000054c33998011ea41b111da749e1863518f3

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

@@ -0,0 +1,11 @@
+<div class="<%= container_classes %>">
+  <% if label %>
+    <span class="<%= label_classes %>"><%= label %></span>
+  <% end %>
+  <span class="<%= goal_classes %>"><%= goal %></span>
+  <div class="<%= tank_classes %>">
+    <div class="<%= fill_classes %>" style="height: <%= fill_percent %>%"></div>
+  </div>
+  <span class="<%= actual_classes %>"><%= actual %></span>
+  <span class="<%= percent_classes %>"><%= percent %>%</span>
+</div>

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class BucketComponent < ViewComponent::Base
+      CONTAINER_CLASSES = "flex w-24 flex-col items-center gap-1"
+      LABEL_CLASSES = "text-center text-sm font-medium text-gray-700 dark:text-gray-300"
+      GOAL_CLASSES = "text-xs tabular-nums text-gray-500 dark:text-gray-400"
+      TANK_CLASSES = "flex h-40 w-full items-end overflow-hidden rounded-t-sm rounded-b-xl border-2 border-gray-300 bg-gray-50 dark:border-zinc-600 dark:bg-zinc-800"
+      ACTUAL_CLASSES = "text-sm font-semibold tabular-nums text-gray-900 dark:text-white"
+      PERCENT_CLASSES = "text-xs tabular-nums text-gray-500 dark:text-gray-400"
+      FILL_BASE_CLASSES = "w-full transition-all"
+      WITHIN_GOAL_FILL_CLASSES = "bg-accent-500"
+      OVER_GOAL_FILL_CLASSES = {
+        success: "bg-green-500",
+        warning: "bg-amber-500"
+      }.freeze
+
+      attr_reader :goal, :actual, :label
+
+      def initialize(goal:, actual:, label: nil, over: :success)
+        @goal = goal
+        @actual = actual
+        @label = label
+        @over_fill_classes = OVER_GOAL_FILL_CLASSES.fetch(over)
+      end
+
+      def percent
+        return 0 if goal.zero?
+
+        (actual.to_f / goal * 100).round
+      end
+
+      def fill_percent
+        [ percent, 100 ].min
+      end
+
+      def fill_classes
+        "#{FILL_BASE_CLASSES} #{fill_color_classes}"
+      end
+
+      def container_classes
+        CONTAINER_CLASSES
+      end
+
+      def label_classes
+        LABEL_CLASSES
+      end
+
+      def goal_classes
+        GOAL_CLASSES
+      end
+
+      def tank_classes
+        TANK_CLASSES
+      end
+
+      def actual_classes
+        ACTUAL_CLASSES
+      end
+
+      def percent_classes
+        PERCENT_CLASSES
+      end
+
+      private
+
+      def fill_color_classes
+        return @over_fill_classes if actual > goal
+
+        WITHIN_GOAL_FILL_CLASSES
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+<div class="<%= row_classes %>">
+  <% bucket_components.each do |bucket| %>
+    <%= render bucket %>
+  <% end %>
+</div>

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class BucketSeriesComponent < ViewComponent::Base
+      ROW_CLASSES = "flex flex-wrap justify-center gap-4 sm:justify-start"
+
+      def initialize(buckets:)
+        @buckets = buckets
+      end
+
+      def bucket_components
+        @buckets.map { |bucket| BucketComponent.new(**bucket) }
+      end
+
+      def row_classes
+        ROW_CLASSES
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@
         <span class="<%= label_classes %>"><%= layer.label %></span>
         <span class="<%= value_classes %>"><%= layer.value %></span>
       </div>
-      <div class="<%= bar_classes %>" style="width: <%= layer.width_percent %>%"></div>
+      <div class="<%= bar_classes %> <%= layer.color_classes %>" style="width: <%= layer.width_percent %>%"></div>
     </div>
   <% end %>
 </div>

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

@@ -3,15 +3,22 @@
 module Keystone
   module Ui
     class FunnelComponent < ViewComponent::Base
-      Layer = Struct.new(:label, :value, :width_percent, :conversion_percent, keyword_init: true)
+      Layer = Struct.new(:label, :value, :width_percent, :conversion_percent, :color_classes, keyword_init: true)
 
       CONTAINER_CLASSES = "space-y-2"
       LAYER_CLASSES = "space-y-1"
       ROW_CLASSES = "flex items-baseline justify-between gap-3"
-      LABEL_CLASSES = "text-sm font-medium text-surface-700 truncate"
-      VALUE_CLASSES = "text-sm font-semibold text-surface-900 tabular-nums"
-      BAR_CLASSES = "h-8 rounded-md bg-accent-500 transition-all"
-      TRANSITION_CLASSES = "py-1 text-center text-xs text-surface-500"
+      LABEL_CLASSES = "text-sm font-medium text-surface-700 truncate dark:text-surface-300"
+      VALUE_CLASSES = "text-sm font-semibold text-surface-900 tabular-nums dark:text-white"
+      BAR_CLASSES = "h-8 rounded-md transition-all"
+      TRANSITION_CLASSES = "py-1 text-center text-xs text-surface-500 dark:text-surface-400"
+      STEP_COLOR_CLASSES = {
+        accent: "bg-accent-500",
+        sky: "bg-sky-500",
+        violet: "bg-violet-500",
+        amber: "bg-amber-500",
+        rose: "bg-rose-500"
+      }.freeze
 
       attr_reader :steps
 
@@ -22,12 +29,13 @@ module Keystone
       def layers
         previous = nil
 
-        steps.map do |step|
+        steps.each_with_index.map do |step, index|
           layer = Layer.new(
             label: step[:label],
             value: step[:value],
             width_percent: width_percent(step[:value]),
-            conversion_percent: conversion_percent(step[:value], previous)
+            conversion_percent: conversion_percent(step[:value], previous),
+            color_classes: color_classes(step[:color], index)
           )
           previous = step[:value]
           layer
@@ -64,6 +72,12 @@ module Keystone
 
       private
 
+      def color_classes(color, index)
+        return STEP_COLOR_CLASSES.fetch(color) if color
+
+        STEP_COLOR_CLASSES.values[index % STEP_COLOR_CLASSES.size]
+      end
+
       def conversion_percent(value, previous)
         return nil if previous.nil?
         return 0 if previous.zero?

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

@@ -3,9 +3,9 @@
 module Keystone
   module Ui
     class ProgressComponent < ViewComponent::Base
-      TRACK_CLASSES = "w-full h-2 bg-surface-200 rounded-full overflow-hidden"
+      TRACK_CLASSES = "w-full h-2 bg-surface-200 rounded-full overflow-hidden dark:bg-surface-700"
       BAR_CLASSES = "h-full bg-accent-500 rounded-full transition-all"
-      LABEL_CLASSES = "mb-1 text-sm font-medium text-surface-700"
+      LABEL_CLASSES = "mb-1 text-sm font-medium text-surface-700 dark:text-surface-300"
 
       attr_reader :value, :max, :label
 

data/app/helpers/keystone_ui_helper.rb

@@ -193,6 +193,14 @@ module KeystoneUiHelper
     render Keystone::Ui::FunnelComponent.new(**args)
   end
 
+  def ui_bucket(**args)
+    render Keystone::Ui::BucketComponent.new(**args)
+  end
+
+  def ui_bucket_series(**args)
+    render Keystone::Ui::BucketSeriesComponent.new(**args)
+  end
+
   def ui_pipeline(**args)
     render Keystone::Ui::PipelineComponent.new(**args)
   end

data/lib/keystone_ui/safelist.rb

@@ -51,6 +51,8 @@ module Keystone
       Keystone::Ui::FormComponent,
       Keystone::Ui::FileUploadComponent,
       Keystone::Ui::FunnelComponent,
+      Keystone::Ui::BucketComponent,
+      Keystone::Ui::BucketSeriesComponent,
       Keystone::Ui::PipelineComponent,
       Keystone::Ui::CodeComponent,
       Keystone::Ui::DisclosureComponent,

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -29,17 +29,23 @@ this one's.
 
 Every entry point is a view helper called from ERB. Keywords with defaults are
 optional; the rest are required. Symbol options are validated — an unrecognized
-one raises at render time.
+one raises at render time. Two exceptions: `ui_page`'s `padding:` treats any
+value other than `:none` as `:standard`, and `ui_pipeline`'s box `accent:` falls
+back to `:muted`.
+
+Six helpers — `ui_page`, `ui_section`, `ui_page_header`, `ui_card`, `ui_alert`,
+`ui_badge` — also accept `class:`, a string of classes appended to the helper's
+outer element. See Conventions before using it.
 
 ### Page shells and layout
 
-- `ui_page(max_width: :full, padding: :standard, top_offset: nil)` — takes a
-  block. The outer wrapper for a screen. `max_width:` `:sm` `:md` `:lg` `:xl`
-  `:full` (anything but `:full` also centers); `padding:` `:standard` or `:none`;
-  `top_offset:` `:sm` `:md` `:lg` `:xl` to clear a fixed navbar.
-- `ui_section(title: nil, subtitle: nil, action: nil, spacing: :md)` — takes a
-  block. A titled block of content with an optional right-aligned link.
-  `action:` is `{ label:, href: }`; `spacing:` `:sm` `:md` `:lg`.
+- `ui_page(max_width: :full, padding: :standard, top_offset: nil, class: nil)` —
+  takes a block. The outer wrapper for a screen. `max_width:` `:sm` `:md` `:lg`
+  `:xl` `:full`; `padding:` `:standard` or `:none`; `top_offset:` `:sm` `:md`
+  `:lg` `:xl` to clear a fixed navbar.
+- `ui_section(title: nil, subtitle: nil, action: nil, spacing: :md, class: nil)`
+  — takes a block. A titled block of content with an optional right-aligned
+  link. `action:` is `{ label:, href: }`; `spacing:` `:sm` `:md` `:lg`.
 - `ui_panel(padding: :md, radius: :lg, shadow: true)` — takes a block. A bordered
   card surface. `padding:` `:sm` `:md` `:lg`; `radius:` `:md` `:lg` `:xl`.
 - `ui_grid(cols: { default: 1 }, gap: :md, gap_x: nil, gap_y: nil)` — takes a
@@ -48,10 +54,10 @@ one raises at render time.
   `:xl`; passing `gap_x:`/`gap_y:` replaces `gap:` entirely.
 - `ui_card_link(href:, padding: :md, shadow: true)` — takes a block. A whole
   panel that is one link. `padding:` `:sm` `:md` `:lg`.
-- `ui_card(title:, summary:, link:, cta: "Read more", edge_to_edge: false)` — a
-  fixed title/summary/CTA card. `edge_to_edge: true` drops the side border and
+- `ui_card(title:, summary:, link:, cta: "Read more", edge_to_edge: false, class: nil)`
+  — a fixed title/summary/CTA card. `edge_to_edge: true` drops the side border and
   corner rounding below `sm:` so it spans the full width on mobile.
-- `ui_page_header(title:, subtitle: nil, action_url: nil, action_label: "Add new")`
+- `ui_page_header(title:, subtitle: nil, action_url: nil, action_label: "Add new", class: nil)`
   — takes a block yielding the header. Desktop-only page title (hidden below
   `sm:`). Call `header.action { ... }` in the block to place a custom control on
   the right; only what `action` receives is rendered. Passing `action_url:`
@@ -93,10 +99,14 @@ one raises at render time.
 - `ui_form_field(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [])`
   — 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`. `label:` defaults to the humanized attribute name.
-  `options:` is for `:select` and takes `[[label, value], ...]`; a non-required
-  select gets a leading blank option. A `:checkbox` submits `"0"` when unchecked
-  and `"1"` when checked, and pre-checks when `value:` is `"1"`. `errors:` is an
+  `:checkbox` `:select`. `attribute:` is used verbatim as the input's `name`, so
+  pass the full param name the controller expects, e.g. `"quote[title]"`, and
+  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
+  `: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.
 - `ui_input(name:, type: :text, value: nil, placeholder: nil, disabled: false, min: nil, max: nil, step: nil)`
   — a bare styled input with no label. `type:` `:text` `:number` `:email`
@@ -107,9 +117,10 @@ one raises at render time.
   — a bare styled select. `options:` is `[[label, value], ...]`;
   `include_blank:` is the text of a leading empty option.
 - `ui_multi_select(name:, label:, options:, selected: [])` — a dropdown of
-  checkboxes all posting under `name`. `options:` is `[[label, value], ...]`;
-  the trigger reads "All <label>" when nothing is checked and "N selected"
-  otherwise.
+  checkboxes all posting under `name`, used verbatim; pass an array name such as
+  `"status[]"` so every checked value arrives. `options:` is
+  `[[label, value], ...]`; `selected:` is the values to pre-check. The trigger
+  reads "All <label>" when nothing is checked and "N selected" otherwise.
 - `ui_file_upload(name:, label: nil, accept: nil, multiple: false, hint: nil)` —
   a drop zone with drag-and-drop and selected-file feedback. Requires the
   enclosing form to be multipart.
@@ -155,9 +166,10 @@ one raises at render time.
   — renders an `<a>` when `href:` is given and a `<button>` otherwise. `variant:`
   `:primary` `:secondary` `:danger`; `size:` `:sm` `:md` `:lg`; `type:` applies
   only to the button form.
-- `ui_badge(label:, variant: :neutral)` — a pill. `variant:` `:neutral`
-  `:success` `:danger` `:warning` `:info`.
-- `ui_alert(message:, type: :info, title: nil, dismissible: false)` — a banner.
+- `ui_badge(label:, variant: :neutral, class: nil)` — a pill. `variant:`
+  `:neutral` `:success` `:danger` `:warning` `:info`.
+- `ui_alert(message:, type: :info, title: nil, dismissible: false, class: nil)` —
+  a banner.
   `type:` `:info` `:success` `:warning` `:error`. `dismissible: true` adds a
   close control.
 - `ui_progress(value:, max:, label: nil)` — a labeled progress bar. The percent
@@ -185,14 +197,19 @@ one raises at render time.
   tab dispatches a `tab-switcher:change` event carrying the clicked index —
   showing and hiding the matching panels is the app's job.
 - `ui_modal(title:, size: :md)` — takes a block holding the body. `size:` `:sm`
-  `:md` `:lg` `:xl`. Renders hidden; it closes on its own close button and on a
-  backdrop click, but the app must supply the control that opens it by targeting
-  the modal controller's `open` action.
+  `:md` `:lg` `:xl`. Renders hidden, and closes on its own close button and on a
+  backdrop click. Nothing in the gem opens it: the modal's outermost element
+  carries the `hidden` class, and the app's own code must remove that class to
+  show it. A `data-action="modal#open"` placed outside the modal does nothing.
 - `ui_swipe_deck(items:, empty_title: "All done!", empty_subtitle: nil)` — takes
   a block yielding the deck. Call `deck.item { |item| ... }` in the block to
-  render one card's face. Accepting a card dispatches `swipe-deck:complete` and
-  rejecting dispatches `swipe-deck:skip`, both carrying the item's id — the app
-  must listen and persist the outcome.
+  render one card's face. Accepting a card (button or swipe right) dispatches a
+  bubbling `swipe-deck:complete` event and rejecting (button or swipe left)
+  dispatches `swipe-deck:skip`. Both carry `detail.itemId` — the item's `id`, or
+  its position in `items:` when it has none — and `detail.card`; `complete` also
+  carries `detail.value`, read from an input inside the card's face marked
+  `data-swipe-deck-value`, or `null`. The app must listen and persist the
+  outcome.
 
 ### Charts and analytics
 
@@ -200,10 +217,27 @@ one raises at render time.
   `:sm` `:md` `:lg`.
 - `ui_line_chart(series:, labels:, height: :md)` — a line chart. `labels:` is the
   x-axis labels; `series:` is `[{ name:, data:, color:, dashed: }, ...]` where
-  `color:` and `dashed:` are optional. `height:` `:sm` `:md` `:lg`.
-- `ui_funnel(steps:)` — a conversion funnel. `steps:` is `[{ label:, value: }, ...]`
-  in order. Bar widths are relative to the first step; the caption between two
-  layers is the step-to-step conversion. Divide-by-zero safe, no JavaScript.
+  `color:` (a CSS color string for the line) and `dashed: true` are optional.
+  `height:` `:sm` `:md` `:lg`.
+- `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_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**
+  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
+  `over: :warning`, and any other symbol raises. No JavaScript.
+- `ui_bucket_series(buckets:)` — a row of buckets that wraps onto more rows on
+  narrow screens. `buckets:` is an array of hashes, each taking the same keywords
+  as `ui_bucket`, e.g. `[{ goal: 10, actual: 7, label: "Mon" }, ...]`.
 - `ui_pipeline(title:, boxes:, links:, subtitle: nil)` — a staged flow diagram
   for event flows, approval chains, or state machines. `boxes:` is
   `[{ label:, count:, accent:, action: }, ...]` where `count:` and `accent:`
@@ -281,8 +315,13 @@ one raises at render time.
   layered onto a helper's output fight the component and drift the moment the gem
   updates. The gem owns spacing, color, borders, radius, shadow, and dark mode.
 - **Never restyle a helper from the outside** — no wrapper div that overrides its
-  padding or width, no `class:` smuggled through, no CSS targeting its markup.
-  Choose a different option symbol instead, or say the helper does not fit.
+  padding or width, no CSS targeting its markup. Choose a different option
+  symbol instead, or say the helper does not fit.
+- **`class:` needs the developer's approval.** The six helpers that accept it
+  append whatever it holds to their outer element, so it can override anything
+  the gem sets. Before passing it, name the class and the reason to the
+  developer and wait for a yes; if the same class keeps being needed, it is a
+  missing option in the gem.
 - **Semantic color only.** Themed color is `accent-*` (the brand hue) and
   `surface-*` (the neutral family). Never write a literal color into a view;
   changing the palette is install-local territory.

data/the_local/agents/keystone_ui-info.md

@@ -1,81 +1,89 @@
 ---
 name: keystone_ui-info
-description: Use to learn what Keystone UI offers — what the component system covers, its layout and color model, and the vocabulary the install and develop locals assume.
+description: Use to learn what Keystone UI offers — what the component system covers, its layout, color and theme model, and the vocabulary the install and develop locals assume.
 tools: Read
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
 
-This local explains Keystone UI and hands you off to the local that does the
-work. It changes nothing and gives no steps.
+This local explains Keystone UI and sends you to the local that does the work.
+It changes nothing and gives no steps.
 
 ## What Keystone UI is
 
-Keystone UI is a Rails engine gem that supplies a host app's entire visual
-layer as a library of view helpers built on ViewComponent. Screens are composed
-out of named pieces — page shells, sections, panels, grids, form fields, data
-tables, navigation bars, cards, charts, banners — instead of hand-written ERB
-and Tailwind. Every class the UI renders lives inside the gem, in frozen
-constants, so the look is owned in one place.
+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.
 
-Reach for it whenever you are building or changing a screen in an app that has
-it installed. The point is to stop UI drift: two pages built from the same
-helpers cannot disagree about spacing, color, or dark-mode treatment, and a
-change to a component updates every page at once. It is mobile-first by
-construction — components ship distinct mobile and desktop treatments (a bottom
-tab bar and mobile header on small screens, a full navigation bar above the
-`lg:` breakpoint), which matters because these apps are often viewed in a native
-webview.
+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
+cannot disagree about spacing, color or dark-mode treatment, and a change to a
+component updates every page that uses it. It is mobile-first — components ship
+separate mobile and desktop treatments (a bottom tab bar and mobile header on
+small screens, a full navigation bar from the `lg:` breakpoint up), because
+these apps are often viewed in a native webview.
 
 ## Interface
 
 This local declares no commands. The two working surfaces belong elsewhere:
 
-- **Getting the gem into a host app** — adding it, wiring Tailwind and Stimulus,
-  setting the palette, refreshing the generated reference → **`keystone_ui-install`**.
+- **Getting the gem into a host app** — adding it, wiring Tailwind, Stimulus and
+  the theme attributes on the layout, setting the palette → **`keystone_ui-install`**.
 - **Building UI with it** — which helper renders what, what keywords it takes,
   how helpers nest → **`keystone_ui-develop`**.
 
 ## How to use it
 
-One decision: is the app already wearing Keystone UI?
+One decision: is Keystone UI already set up in the app?
 
-- No, or it is out of date → **`keystone_ui-install`**.
+- No, or the setup is out of date → **`keystone_ui-install`**.
 - Yes, and you have a screen to build or edit → **`keystone_ui-develop`**. Do not
   hand-write ERB or Tailwind for UI it covers.
 
-Questions about which piece fits a scenario are also answered by the develop
-local — it owns the catalog.
+Questions about which piece fits a scenario also go to the develop local, which
+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
-  host app should not name a component class directly.
-- **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) are configured
-  entirely by keyword arguments. Composite pieces such as the navigation bar
-  expose named slots rather than a single block.
-- **Options are symbols, and the accepted set is per-component.** Appearance is
+  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
+  configured entirely by keyword arguments. The navigation bar exposes named
+  slots instead of a single block.
+- **Options are symbols, and each component accepts its own set.** Appearance is
   chosen by name — `variant:`, `size:`, `type:`, `padding:`, `spacing:`,
-  `max_width:`, `radius:` — on a small t-shirt scale (`:sm` … `:xl`) or a short
-  semantic list. Do not assume one global vocabulary: a button's `variant:` and
-  a badge's `variant:` accept different symbols, and `padding:` means different
-  things on a page shell than on a panel. The develop local carries the real
-  values. An unrecognized symbol raises rather than degrading silently, so a
-  wrong guess fails loudly at render time.
+  `max_width:`, `radius:` — on a size scale (`:sm` … `:xl`) or a short list of
+  named choices. A button's `variant:` and a badge's `variant:` accept
+  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.
 - **Semantic color, not literal color.** The themed hue is `accent-*` and the
-  themed neutral family is `surface-*` — Tailwind v4 CSS custom properties
-  defaulting to blue and zinc, so retheming an app is a token change, not a
-  component change. Older components still reach for Tailwind's stock
-  `gray-*`/`zinc-*` neutrals directly; the accent hue is themed throughout.
-  Dark-mode variants are already built into every component. Changing the
-  defaults is install-local territory.
+  themed neutral family is `surface-*`, both CSS custom properties whose
+  defaults (blue and zinc) come from the keystone_ui-styles gem. Retheming an
+  app changes those values, not the components. Some components still use
+  Tailwind's stock `gray-*` and `zinc-*` neutrals, or fixed status colors such
+  as green and amber, directly. Changing the defaults belongs to the install
+  local.
+- **Light, dark and system 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 to follow the
+  operating system.
 - **Tailwind classes are static strings.** Class names are never interpolated,
-  so Tailwind's scanner can see them; the host needs tailwindcss-rails v4+ and
-  the engine tells Tailwind where to look.
+  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
+  instead. The host needs tailwindcss-rails v4+, and the engine tells Tailwind
+  at boot where the component files are.
 - **Interactivity is Stimulus.** Dropdowns, modals, dismissible alerts, file
-  uploads, tab switchers, column pickers, clipboard copy and similar behavior
-  ship with the gem as Stimulus controllers registered in one call at install —
-  a host writes no JavaScript to use them.
-- Ruby >= 3.2. ViewComponent >= 2.0.
+  uploads, the color picker, the multi-select, tab switchers, accordions, the
+  swipe deck, column pickers, stat card info panels, line charts, clipboard copy
+  and the theme toggle ship with the gem as Stimulus controllers registered once
+  at install. A host writes no JavaScript to use them. Components that post
+  somewhere, such as the column picker and the pipeline, post to endpoints the
+  host app owns.
+- Ruby >= 3.2. ViewComponent >= 2.0 and < 5.

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 and Stimulus, and setting the accent/surface palette.
+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.
 tools: Bash, Read, Edit
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -15,16 +15,21 @@ built on ViewComponent; hook it in before building any screen with those helpers
 
 ## Interface
 
-- `bin/rails generate keystone:install` — sets up the host's Tailwind entry point
-  and registers the gem's Stimulus controllers. Idempotent, and safe to re-run.
-- `KeystoneUi.configure` — a block yielding `accent` and `surface`, the names of
-  the palettes the app wants (`:blue` and `:zinc` unless set).
+- `bin/rails generate keystone:install` — sets up the host's Tailwind entry
+  point, registers the gem's Stimulus controllers, and adds the theme attributes
+  to the layout's `<html>` tag. Safe to re-run.
+- `KeystoneUi.configure` — a block yielding the configuration: `accent` and
+  `surface` (palette names, `:blue` and `:zinc` unless set),
+  `theme_mode_supplier` (a callable that supplies a light, dark or system mode),
+  and the `tailwind_imports` and `tailwind_sources` lists (extra CSS files and
+  scan paths added to the Tailwind build).
 
 ## How to use it
 
 1. Confirm the prerequisites: Ruby >= 3.2 and **tailwindcss-rails v4+** in the
-   host app. The gem brings ViewComponent with it. Tailwind does not have to be
-   initialized first — the generator creates the stylesheet if it is missing.
+   host app. The gem brings ViewComponent and keystone_ui-styles with it.
+   Tailwind does not have to be initialized first, because the generator creates
+   the stylesheet if it is missing.
 
 2. Add the gem to the Gemfile and install it:
 
@@ -45,31 +50,45 @@ built on ViewComponent; hook it in before building any screen with those helpers
    bin/rails generate keystone:install
    ```
 
-   It touches two host files:
+   It touches three host files:
 
-   - `app/assets/tailwind/application.css` — creates it with
-     `@import "tailwindcss";` and `@import "./keystone_source.css";` if absent;
-     otherwise injects the Keystone import after the Tailwind one and strips
-     superseded Keystone lines from older installs.
+   - `app/assets/tailwind/application.css` — if absent, it is created holding
+     `@import "tailwindcss";` and `@import "./keystone_source.css";`. If present,
+     the Keystone import is added on the line after `@import "tailwindcss";`, and
+     Keystone lines left by older installs are removed.
    - `app/javascript/controllers/index.js` — appends
      `import { registerControllers } from "keystone_ui/index"` and
      `registerControllers(application)`.
-
-   Read its output. If it reports that `app/javascript/controllers/index.js` was
-   not found, ask the developer where the Stimulus application is set up and add
-   those two lines there — without them, dropdowns, modals, file uploads, the
-   column picker and the other interactive components do nothing.
+   - `app/views/layouts/application.html.erb` — adds
+     `<%= keystone_theme_attributes %>` inside the `<html` tag, which writes the
+     light or dark mode onto the page.
+
+   Read its output for two warnings:
+
+   - `app/javascript/controllers/index.js not found` — ask the developer where
+     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.
+   - `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
+     the page loads.
+
+   The CSS step only adds the Keystone import if `application.css` contains the
+   exact line `@import "tailwindcss";` followed by a line break. If the output
+   says nothing about the import and the line is not in the file, add
+   `@import "./keystone_source.css";` directly under the Tailwind import by hand.
 
 4. Restart the app (or rebuild assets). On boot the engine writes
-   `app/assets/tailwind/keystone_source.css`, which points Tailwind at the
-   component files and pulls in the gem's theme and component CSS. It is written
-   only when `application.css` exists **and** contains
-   `@import "./keystone_source.css";` — if the file never appears, that import is
-   missing.
+   `app/assets/tailwind/keystone_source.css`, which imports the gem's theme and
+   component CSS and points Tailwind at the component files. It is written only
+   when `application.css` exists **and** contains
+   `@import "./keystone_source.css";`, so if the file never appears, that import
+   is missing.
 
 5. Keep the generated file out of git. It holds absolute paths to the gem on the
-   machine that booted the app, and is rewritten on every boot — dev server, CI,
-   and `assets:precompile` alike. Add to `.gitignore`:
+   machine that booted the app, and is rewritten on every boot, which includes
+   the dev server, CI and `assets:precompile`. Add to `.gitignore`:
 
    ```
    app/assets/tailwind/keystone_source.css
@@ -77,10 +96,10 @@ built on ViewComponent; hook it in before building any screen with those helpers
 
    Only the `@import` line in `application.css` belongs in the repo.
 
-6. Settle the palette. Out of the box the accent scale is blue and the surface
-   scale is zinc, with no configuration required. To change them statically, add
-   an `@theme` block to `application.css` **after** the two imports and override
-   only the shades the app uses:
+6. Settle the palette. Without configuration the accent scale is blue and the
+   surface scale is zinc. To change them statically, add an `@theme` block to
+   `application.css` **after** the two imports and override only the shades the
+   app uses:
 
    ```css
    @import "tailwindcss";
@@ -95,12 +114,14 @@ built on ViewComponent; hook it in before building any screen with those helpers
    Both scales run 50 through 950. Every component picks the values up with no
    component changes.
 
-   This is a decision, not a default to assume: fixed app-wide colors set in CSS,
-   or per-user colors generated at runtime by a companion theming gem. Ask the
-   developer which the app wants before wiring either.
+   This is a decision to put to the developer: fixed app-wide colors set in CSS,
+   or per-user colors generated at runtime by a companion theming gem. Ask which
+   the app wants before wiring either.
 
-7. Only if a companion gem or engine reads the palette choice, declare it in
-   `config/initializers/keystone_ui.rb`:
+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
+   is where the block goes.
 
    ```ruby
    require "keystone_ui"
@@ -108,30 +129,45 @@ built on ViewComponent; hook it in before building any screen with those helpers
    KeystoneUi.configure do |config|
      config.accent = :emerald
      config.surface = :slate
+     config.theme_mode_supplier = ->(view) { view.current_user&.theme }
+     config.tailwind_imports << "/absolute/path/to/extra.css"
+     config.tailwind_sources << "/absolute/path/to/components/**/*.{erb,rb}"
    end
    ```
 
-   Keystone UI itself stores these names and renders from the CSS custom
-   properties regardless — setting them changes no color on its own. Colors move
-   when the custom properties in step 6 move. The engine reads host configuration
-   after initializers have run, so the initializer is the correct home for the
-   block.
+   - `accent` and `surface` — set these only when a companion gem or engine
+     reads the palette choice. Keystone UI stores the names and changes no color
+     from them, because colors come from the CSS custom properties in step 6.
+   - `theme_mode_supplier` — a callable that receives the view and returns
+     `"light"`, `"dark"` or `"system"`. It supplies the mode when the user has
+     not picked one with the theme toggle, since the `keystone_theme` cookie that
+     the toggle writes takes precedence. Any other return value, or no supplier,
+     falls back to light.
+   - `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
+     another gem or engine whose CSS or templates must be in the same Tailwind
+     build, and that gem normally appends its own entries.
 
 ## Conventions
 
-- **Verify the install before building anything on it.** `application.css` holds
-  both imports; `app/assets/tailwind/keystone_source.css` exists after a boot;
-  the Stimulus setup calls `registerControllers(application)`. Then load one page
-  that renders a `ui_*` helper and confirm it is styled and that an interactive
-  piece (a dropdown, a dismissible alert) responds.
+- **Verify the install before building anything on it.** Check four things:
+  `application.css` holds both imports, `app/assets/tailwind/keystone_source.css`
+  exists after a boot, the Stimulus setup calls `registerControllers(application)`,
+  and the layout's `<html>` tag contains `<%= keystone_theme_attributes %>`. Then
+  load one page that renders a `ui_*` helper and confirm it is styled and that an
+  interactive component (a dropdown, a dismissible alert) responds.
 - **Importmap is the supported JS path.** For apps configured with importmap the
-  gem pins its own controllers — and the charting library they need — on boot, so
+  gem pins its own controllers, and the charting library they need, on boot, so
   the host pins nothing. If the app bundles JavaScript instead (esbuild, bun,
-  webpack), the appended `keystone_ui/index` import has no pin behind it — surface
-  this to the developer rather than guessing at a bundler configuration.
-- **Re-run the generator after upgrading the gem.** It clears out superseded
-  install lines and reports "already up to date" when there is nothing to do.
+  webpack), the appended `keystone_ui/index` import has nothing pinned behind
+  it. Tell the developer rather than guessing at a bundler configuration.
+- **Re-run the generator after upgrading the gem.** It removes superseded install
+  lines and reports that each file is already up to date when there is nothing
+  to do.
 - **New components need no re-run.** Tailwind rescans the gem on each build, so
   components added by a later version are styled on the next boot.
-- Building UI with the helpers — which helper to use, what keywords it takes — is
-  out of scope here and belongs to `keystone_ui-develop`.
+- On boot the engine deletes `app/assets/builds/tailwind/keystone_ui_engine.css`
+  if an older install left it there. Do not recreate it.
+- Building UI with the helpers, including which helper to use and what keywords
+  it takes, is out of scope here and belongs to `keystone_ui-develop`.

data/the_local/interface.yml

@@ -51,6 +51,8 @@ develop:
   - ui_form
   - ui_file_upload
   - ui_funnel
+  - ui_bucket
+  - ui_bucket_series
   - ui_pipeline
   - ui_code
   - ui_disclosure
@@ -85,6 +87,8 @@ sources:
   - app/components/keystone/ui/form_field_component.rb
   - app/components/keystone/ui/form_page_component.rb
   - app/components/keystone/ui/funnel_component.rb
+  - app/components/keystone/ui/bucket_component.rb
+  - app/components/keystone/ui/bucket_series_component.rb
   - app/components/keystone/ui/grid_component.rb
   - app/components/keystone/ui/hero_component.rb
   - app/components/keystone/ui/input_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.13.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -81,6 +81,10 @@ files:
 - app/components/keystone/ui/bottom_nav_component.rb
 - app/components/keystone/ui/bottom_nav_item_component.html.erb
 - app/components/keystone/ui/bottom_nav_item_component.rb
+- app/components/keystone/ui/bucket_component.html.erb
+- app/components/keystone/ui/bucket_component.rb
+- app/components/keystone/ui/bucket_series_component.html.erb
+- 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/card_component.html.erb