keystone_ui 0.29.5 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5df45efe6cf162e4a96fa164e01d6ccdf623f8a84d14c530fd5dca4b42eec941
-  data.tar.gz: f1366496636edb0d10f9e50c4b75c4dddc21801634cce63ba67cf4bfe009dfd6
+  metadata.gz: 53f39974ced2866fb949b3bfbe0e1be0359977df8a890f9bf83e20b8a04cff11
+  data.tar.gz: 7dc3d1ae90c88bd89ccff1c67a861f6e391558605edb5aaaa136f3c674e47cb6
 SHA512:
-  metadata.gz: f249e58a7511397eab772a9e1c9c54c323c0583ddafe41c4da6741d54d8ee57e3590d9c400f75fbd7f5a71d4aa4b0fa30cb0f6223ee6ab817b0240ab539b976b
-  data.tar.gz: dd617c68d26134469be161339b9c0158a2cd39f4f95ee29d9f6e3546f85b4e60cc4009a2d30d431f31792c3dea9752489df8e48032493b5dde5ab872e5a12135
+  metadata.gz: ce349e68888fb9085cf9475eb3a96cb6dec23e193df5912905e559f5371dcb7d936d7e6b80a09d820fa28a91da0993c67add11578729dd37e62f25b3d7bac787
+  data.tar.gz: 37cfadba853c471e4ba8a4e9cf94c941e9a554151a76ba9bba4573b80bf80b49850ac713a55da7f148b3aabd6fb253a36b1089c5c132f0afa86d1072aa6e6216

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/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.30.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -323,10 +323,20 @@ 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_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:)` — 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
@@ -443,6 +453,12 @@ 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:`.
    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,16 @@ 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 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.29.5
+  version: 0.30.0
 platform: ruby
 authors:
 - Tyler Schneider