keystone_ui 0.29.5 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5df45efe6cf162e4a96fa164e01d6ccdf623f8a84d14c530fd5dca4b42eec941
-  data.tar.gz: f1366496636edb0d10f9e50c4b75c4dddc21801634cce63ba67cf4bfe009dfd6
+  metadata.gz: a6c7e18e911657e41ed1a4eff2133400015bd7a58e0c437f6886d219173f01fa
+  data.tar.gz: 91b2f652bb7313d9cda361e126e969d06b64827e80118888a73cce3840471f68
 SHA512:
-  metadata.gz: f249e58a7511397eab772a9e1c9c54c323c0583ddafe41c4da6741d54d8ee57e3590d9c400f75fbd7f5a71d4aa4b0fa30cb0f6223ee6ab817b0240ab539b976b
-  data.tar.gz: dd617c68d26134469be161339b9c0158a2cd39f4f95ee29d9f6e3546f85b4e60cc4009a2d30d431f31792c3dea9752489df8e48032493b5dde5ab872e5a12135
+  metadata.gz: 466ea8fbb32ed4683db9537a52d7ba41d667f79dfa52aec27aaab85f5fc14b872fcc03b7d880136936133685fdc1af5f839aa4392c5ba698af62694e4a5832b0
+  data.tar.gz: 435630df203142fa669f0d93333e6b2637b2d4ec2d25b6e8fa1a7aa00e54ba5fdace3a3416905c144f706f18373ad78b8b11c067f5d1a62ee6453655358b4b77

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

@@ -6,9 +6,26 @@ const loadChart = async () => {
   return Chart
 }
 
+const MILLISECONDS_IN_A_DAY = 86_400_000
+
+export const dayLabel = (day) =>
+  new Date(day * MILLISECONDS_IN_A_DAY).toLocaleDateString("en-US", { timeZone: "UTC", month: "short", day: "numeric", year: "numeric" })
+
+const DATED_OPTIONS = {
+  scales: { x: { type: "linear", bounds: "data", ticks: { precision: 0, callback: dayLabel } } },
+  plugins: { tooltip: { callbacks: { title: ([point]) => dayLabel(point.parsed.x) } } }
+}
+
+export const chartOptions = (dated) => ({
+  responsive: true,
+  maintainAspectRatio: false,
+  interaction: { mode: "index", intersect: false },
+  ...(dated ? DATED_OPTIONS : {})
+})
+
 export default class extends Controller {
   static targets = ["canvas"]
-  static values = { data: Object }
+  static values = { data: Object, dated: Boolean }
 
   async connect() {
     const Chart = await loadChart()
@@ -17,11 +34,7 @@ export default class extends Controller {
     this.chart = new Chart(this.canvasTarget, {
       type: "line",
       data: this.resolveColors(this.dataValue),
-      options: {
-        responsive: true,
-        maintainAspectRatio: false,
-        interaction: { mode: "index", intersect: false }
-      }
+      options: chartOptions(this.datedValue)
     })
   }
 

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

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

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

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

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

@@ -1,3 +1,3 @@
-<div class="<%= container_classes %>" data-controller="line-chart" data-line-chart-data-value="<%= chart_data_json %>">
+<div class="<%= container_classes %>" data-controller="line-chart" data-line-chart-data-value="<%= chart_data_json %>" data-line-chart-dated-value="<%= dated? %>">
   <canvas class="max-w-full" data-line-chart-target="canvas"></canvas>
 </div>

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "date"
 require "json"
 
 module Keystone
@@ -12,21 +13,29 @@ module Keystone
       }.freeze
 
       DASH_PATTERN = [ 6, 6 ].freeze
+      EPOCH = Date.new(1970, 1, 1)
+
+      def initialize(series:, labels: nil, dates: nil, height: :md)
+        raise ArgumentError, "a line chart takes labels: or dates:" unless labels.nil? ^ dates.nil?
 
-      def initialize(series:, labels:, height: :md)
         @series = series
         @labels = labels
+        @dates = dates
         @height = height
       end
 
       def chart_data
-        { labels: @labels, datasets: @series.map { |s| dataset_for(s) } }
+        { labels: @labels, datasets: @series.map { |s| dataset_for(s) } }.compact
       end
 
       def chart_data_json
         chart_data.to_json
       end
 
+      def dated?
+        !@dates.nil?
+      end
+
       def height_class
         HEIGHT_CLASSES.fetch(@height)
       end
@@ -38,11 +47,17 @@ module Keystone
       private
 
       def dataset_for(series)
-        dataset = { label: series[:name], data: series[:data] }
+        dataset = { label: series[:name], data: points_for(series[:data]) }
         dataset[:borderColor] = series[:color] if series[:color]
         dataset[:borderDash] = DASH_PATTERN if series[:dashed]
         dataset
       end
+
+      def points_for(values)
+        return values unless @dates
+
+        @dates.zip(values).map { |date, value| { x: (date.to_date - EPOCH).to_i, y: value } }
+      end
     end
   end
 end

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -323,17 +323,34 @@ outer element. See Conventions before using it.
 
 - `ui_chart_card(title:, height: :md)` — takes a block holding a chart. `height:`
   `: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:` (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_line_chart(series:, labels: nil, dates: nil, height: :md)` — a line chart
+  with one line per series. `series:` is
+  `[{ name:, data:, color:, dashed: }, ...]` where `data:` is the array of
+  values, and `color:` (a CSS color string for the line) and `dashed: true` are
+  optional. `height:` `:sm` `:md` `:lg`. Pass exactly one of `labels:` and
+  `dates:` for the horizontal axis: passing both, or neither, raises
+  `ArgumentError`. `labels:` is an array of strings, one per value, spaced
+  evenly and shown as written. `dates:` is an array of `Date`, `Time` or
+  `DateTime` values, one per value, matched to each series' `data:` by
+  position. A dated chart places each point by its day, so a gap of a week is
+  seven times as wide as a gap of a day. Its axis runs from the first day to
+  the last, marks only whole days, and reads each day as a date such as
+  "Oct 2, 2026", which is also the heading a hovered point shows. The time of
+  day is dropped, so pass one value per day.
+- `ui_funnel(steps:, shape: :bars)` — a conversion funnel. `steps:` is
+  `[{ label:, value:, color: }, ...]` in order, with `color:` optional. Each
+  step's width is its value as a share of the first step's value, and the
+  percent shown between two steps is the second step's value divided by the
+  first's. Each step takes the next colour in the order `:accent` `:sky`
+  `:violet` `:amber` `:rose`, starting again after `:rose`; a step passing one
+  of those symbols as `color:` uses it instead, and any other symbol raises.
+  Values are printed as given. Divide-by-zero safe, no JavaScript. `shape:`
+  `:bars` draws one bar per step, left-aligned, with the label and value on a
+  row above it and a `↓ N%` caption between two bars. `shape: :joined` draws
+  one shape: each step's value over its label in a column on the left, each
+  step's block centred at its width, and between two blocks a neutral band
+  that narrows from the block above to the block below, with the percent on it.
+  Any other `shape:` raises `ArgumentError`.
 - `ui_bucket(goal:, actual:, label: nil, over: :success)` — an upright container
   for one target, filled from the bottom toward `goal:`. It shows the optional
   `label` on top, then `goal`, the container, `actual`, and the percent reached.
@@ -443,6 +460,18 @@ outer element. See Conventions before using it.
    On a radio card or a checkbox row, text every reader needs to choose goes in `hint:` and
    text only some will want goes in `info:`. Which is which is the app's own
    wording, so ask the developer rather than pick.
+   For a line chart, pass `dates:` when each value belongs to a calendar day
+   and `labels:` when the horizontal axis is anything else, such as week names
+   or categories. With `dates:`, a day with no value leaves a wider gap between
+   its neighbours rather than a point at zero. Whether a missing day is left
+   out or passed as a zero is the app's own rule, so ask the developer rather
+   than pick. Never format dates into strings and pass them as `labels:`.
+   For a funnel, whether it is drawn as separate bars or as one joined shape
+   is the developer's choice, so ask before passing `shape:`. If a joined
+   funnel shows its blocks but no band between them, the app's
+   keystone_ui-styles version does not define the `ks-funnel-band` classes, so
+   stop and hand that part to `keystone_ui-install`, and add no classes to fix
+   it.
    Put the actions on a record, such as Edit and Delete, in an action menu
    rather than in a row of buttons: `menu:` on the `ui_section` that shows the
    record, `table.actions` for a table row, or `ui_action_menu` anywhere else.

data/the_local/agents/keystone_ui-info.md

@@ -129,6 +129,23 @@ 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 funnel has two shapes.** Both size each step against the first step and
+  show the percent carried from one step to the next. The default draws one bar
+  per step, each with its label and value on a row above it. The joined shape
+  draws the steps as one figure: each step's value and label sit in a column on
+  the left, each step is a block centred at its width, and a neutral band
+  between two blocks narrows from one width to the next and holds the percent.
+  Any other shape raises `ArgumentError`. Neither shape needs JavaScript.
+- **A line chart is labelled or dated.** A line chart draws one line per
+  series, and each series is a name and its values, with an optional colour
+  and an optional dashed line. Its horizontal axis is given one of two ways,
+  never both and never neither, and the wrong combination raises
+  `ArgumentError`. Labels are text, one per value, spaced evenly and shown as
+  written. Dates are one day per value, and a dated chart places each point by
+  its day, so a gap of a week is seven times as wide as a gap of a day. A dated
+  axis runs from the first day to the last, marks only whole days, and reads
+  each day as a date such as "Oct 2, 2026", which is also what a hovered point
+  shows. A time of day is dropped, so a dated chart has one position per day.
 - **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

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.8.0 or later with it.
+   host app. The gem brings ViewComponent and keystone_ui-styles 0.9.0 or later with it.
    Tailwind does not have to be initialized first, because the generator creates
    the stylesheet if it is missing.
 

data/the_local/interface.yml

@@ -98,6 +98,7 @@ sources:
   - app/components/keystone/ui/info_component.rb
   - app/components/keystone/ui/info_component.html.erb
   - app/assets/javascripts/keystone_ui/info_controller.js
+  - app/assets/javascripts/keystone_ui/line_chart_controller.js
   - app/components/keystone/ui/breakdown_component.rb
   - app/components/keystone/ui/breakdown_component.html.erb
   - app/components/keystone/ui/feature_grid_component.rb
@@ -111,6 +112,7 @@ sources:
   - app/components/keystone/ui/breadcrumbs_component.rb
   - app/components/keystone/ui/breadcrumbs_component.html.erb
   - app/components/keystone/ui/funnel_component.rb
+  - app/components/keystone/ui/funnel_component.html.erb
   - app/components/keystone/ui/bucket_component.rb
   - app/components/keystone/ui/bucket_series_component.rb
   - app/components/keystone/ui/grid_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.29.5
+  version: 0.31.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement