keystone_ui 0.40.0 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50be7dcd619f5461a74ec4c8b7d2d6e09deb955af9b17817b1ef690f842f5a07
-  data.tar.gz: 1148f6cf6bba00291658cec6c0672eeae3500093ebbffec67bbbc412fabe72eb
+  metadata.gz: 28436277e0b304a48d5093a2220bb1df0e04f94315f085781e93cb34207ea654
+  data.tar.gz: 82bb8f8de9b4132f47da04e7ab3423ba3c73e216b2ae79659f8709b52888bfde
 SHA512:
-  metadata.gz: 884b4a4d0b72cf66bc76d5e94af4322a65f1b82aa81a5fba5b6b3f3fbad865524d6dd7fb75dce0a33d1fec8e88e41691a4a57b045e5d920751b3c6fe1453e545
-  data.tar.gz: ca9f20d6ef81510e165a8c6a938e6a2cc0cb37dfc1c426b97f17e1695686521727d5e0336809084761d8c0e59f90aef425fe912878d79661e44fa89e4d12137b
+  metadata.gz: 3e63c3495c2b1709109cb25584e9a9e5c5b7fcaef4cfb1cc1e948641b5ae06a22acc3703f52d038d69a7371b57d39a554d75a8ac671e90662f525734979ab8fd
+  data.tar.gz: 8941b3263e4944bbfc4e6d6dbc8eb82f74908ee51b922f9c6f61b6cb9c4af869171c22b8e5cbdc4bef6e7c238e740d2f531b143cd5abaddba2a5d73b36d34b1a

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

@@ -11,18 +11,92 @@ 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) } } }
+const DATED_AXIS = { type: "linear", bounds: "data" }
+const DATED_TICKS = { precision: 0, callback: dayLabel }
+const DATED_TOOLTIP = { callbacks: { title: ([point]) => dayLabel(point.parsed.x) } }
+
+const tooltip = (theme) => ({
+  backgroundColor: theme.surface,
+  borderColor: theme.border,
+  borderWidth: 1,
+  titleColor: theme.text,
+  bodyColor: theme.text
+})
+
+const DRAW_IN_MILLISECONDS = 600
+
+const pointStep = (context) => DRAW_IN_MILLISECONDS / context.chart.data.datasets[context.datasetIndex].data.length
+
+const drawsIn = (context) => context.type === "data" && context.mode === "default"
+
+const drawIn = {
+  x: {
+    type: "number",
+    easing: "linear",
+    from: NaN,
+    duration: (context) => (drawsIn(context) ? pointStep(context) : 0),
+    delay: (context) => (drawsIn(context) ? context.index * pointStep(context) : 0)
+  },
+  y: { duration: 0 }
 }
 
-export const chartOptions = (dated) => ({
+const axisText = (theme) => ({ color: theme.mutedText, font: { size: 11, family: theme.font } })
+
+export const chartOptions = (dated, theme = {}, animated = false) => ({
   responsive: true,
   maintainAspectRatio: false,
   interaction: { mode: "index", intersect: false },
-  ...(dated ? DATED_OPTIONS : {})
+  ...(animated ? { animations: drawIn } : { animation: false }),
+  elements: { line: { borderWidth: 1.5 }, point: { radius: 0, hoverRadius: 4 } },
+  scales: {
+    x: { ...(dated ? DATED_AXIS : {}), grid: { display: false }, ticks: { ...(dated ? DATED_TICKS : {}), ...axisText(theme) } },
+    y: { border: { display: false }, grid: { color: theme.border }, ticks: axisText(theme) }
+  },
+  plugins: { tooltip: { ...(dated ? DATED_TOOLTIP : {}), ...tooltip(theme) } }
 })
 
+const LIGHT_THEMES = ["light", "custom"]
+
+export const isDarkMode = (theme, prefersDark) => theme === "dark" || (prefersDark && !LIGHT_THEMES.includes(theme))
+
+const CHART_COLOR_COUNT = 5
+
+const INHERITED_FONTS = ["", "inherit"]
+
+export const themeColors = (read, dark, inheritedFont) => {
+  const variable = (name) => read(dark ? `${name}-dark` : name)
+  const bodyFont = read("--ks-font-body")
+  return {
+    series: Array.from({ length: CHART_COLOR_COUNT }, (_, index) => variable(`--ks-color-chart-${index + 1}`)),
+    border: variable("--ks-color-border"),
+    surface: variable("--ks-color-surface"),
+    text: variable("--ks-color-text"),
+    mutedText: variable("--ks-color-text-muted"),
+    font: INHERITED_FONTS.includes(bodyFont) ? inheritedFont : bodyFont
+  }
+}
+
+export const styleDatasets = (datasets, theme, resolve) => {
+  let uncolored = 0
+  return datasets.map((dataset) => {
+    const color = dataset.borderColor ? resolve(dataset.borderColor) : theme.series[uncolored++ % theme.series.length]
+    return { ...dataset, borderColor: color, pointHoverBackgroundColor: color }
+  })
+}
+
+export const watchTheme = ({ document, matchMedia, MutationObserver }, onChange) => {
+  const observer = new MutationObserver(onChange)
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme", "data-look"] })
+  observer.observe(document.head, { childList: true, subtree: true, characterData: true })
+  const darkPreference = matchMedia("(prefers-color-scheme: dark)")
+  darkPreference.addEventListener("change", onChange)
+
+  return () => {
+    observer.disconnect()
+    darkPreference.removeEventListener("change", onChange)
+  }
+}
+
 export default class extends Controller {
   static targets = ["canvas"]
   static values = { data: Object, dated: Boolean }
@@ -31,27 +105,38 @@ export default class extends Controller {
     const Chart = await loadChart()
     if (!this.element.isConnected) return
 
+    const { theme, resolve } = this.readTheme()
+    this.animated = !matchMedia("(prefers-reduced-motion: reduce)").matches
     this.chart = new Chart(this.canvasTarget, {
       type: "line",
-      data: this.resolveColors(this.dataValue),
-      options: chartOptions(this.datedValue)
+      data: { ...this.dataValue, datasets: styleDatasets(this.dataValue.datasets, theme, resolve) },
+      options: chartOptions(this.datedValue, theme, this.animated)
     })
+    this.stopWatchingTheme = watchTheme({ document, matchMedia: (query) => matchMedia(query), MutationObserver }, () => this.redraw())
   }
 
   disconnect() {
+    this.stopWatchingTheme?.()
     this.chart?.destroy()
   }
 
-  resolveColors(data) {
+  redraw() {
+    const { theme, resolve } = this.readTheme()
+    const styled = styleDatasets(this.dataValue.datasets, theme, resolve)
+    this.chart.data.datasets.forEach((dataset, index) => Object.assign(dataset, styled[index]))
+    this.chart.options = chartOptions(this.datedValue, theme, this.animated)
+    this.chart.update("none")
+  }
+
+  readTheme() {
     const styles = getComputedStyle(this.element)
+    const read = (name) => styles.getPropertyValue(name).trim()
     const resolve = (color) => {
       const match = typeof color === "string" && color.match(/^var\((--[^)]+)\)$/)
-      return match ? styles.getPropertyValue(match[1]).trim() || color : color
+      return match ? read(match[1]) || color : color
     }
 
-    data.datasets.forEach((dataset) => {
-      if (dataset.borderColor) dataset.borderColor = resolve(dataset.borderColor)
-    })
-    return data
+    const dark = isDarkMode(document.documentElement.dataset.theme, matchMedia("(prefers-color-scheme: dark)").matches)
+    return { theme: themeColors(read, dark, styles.fontFamily), resolve }
   }
 }

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

@@ -0,0 +1 @@
+<p class="ks-caption"><%= text %></p>

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class CaptionComponent < ViewComponent::Base
+      attr_reader :text
+
+      def initialize(text:)
+        @text = text
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+<% if note %>
+  <div class="ks-heading-row">
+    <h2 class="<%= classes %>"><%= text %></h2>
+    <span class="ks-heading-note"><%= note %></span>
+  </div>
+<% else %>
+  <h2 class="<%= classes %>"><%= text %></h2>
+<% end %>

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class HeadingComponent < ViewComponent::Base
+      SIZE_CLASSES = { sm: "ks-heading-sm", md: "ks-heading-md", lg: "ks-heading-lg" }.freeze
+
+      attr_reader :text, :note
+
+      def initialize(text:, size: :md, note: nil)
+        @text = text
+        @note = note
+        @size = size
+      end
+
+      def classes
+        [ "ks-heading", SIZE_CLASSES.fetch(@size) ].join(" ")
+      end
+    end
+  end
+end

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

@@ -7,12 +7,19 @@
       <div class="<%= SIDEBAR_LOGO_CLASSES %>"><%= logo %></div>
     <% end %>
     <% groups.each do |group| %>
-      <details class="<%= SIDEBAR_GROUP_CLASSES %>"<%= " open" if group.active %>>
-        <summary class="<%= sidebar_group_label_classes(group) %>"><%= group.label %></summary>
-        <% group.tabs.each do |tab| %>
-          <a class="<%= sidebar_tab_classes(tab) %>" href="<%= tab.href %>"><%= tab.label %></a>
-        <% end %>
-      </details>
+      <% if group.standalone %>
+        <% tab = group.tabs.first %>
+        <a class="<%= sidebar_tab_classes(tab) %>" href="<%= tab.href %>"><%= tab.label %></a>
+      <% else %>
+        <details class="<%= SIDEBAR_GROUP_CLASSES %>"<%= " open" if group.active %>>
+          <summary class="<%= sidebar_group_label_classes(group) %>"><%= group.label %></summary>
+          <div class="<%= SIDEBAR_GROUP_TABS_CLASSES %>">
+            <% group.tabs.each do |tab| %>
+              <a class="<%= sidebar_tab_classes(tab) %>" href="<%= tab.href %>"><%= tab.label %></a>
+            <% end %>
+          </div>
+        </details>
+      <% end %>
     <% end %>
     <% if menus? %>
       <div class="<%= SIDEBAR_MENUS_CLASSES %>"><%= menus %></div>
@@ -33,9 +40,14 @@
   <% end %>
   <% navbar.with_desktop_links do %>
     <% groups.each do |group| %>
-      <%= render Keystone::Ui::NavDropdownComponent.new(title: group.label, area: group.label, active: group.active) do %>
-        <% group.tabs.each do |tab| %>
-          <%= render Keystone::Ui::NavItemComponent.new(label: tab.label, href: tab.href, active: tab.active) %>
+      <% if group.standalone %>
+        <% tab = group.tabs.first %>
+        <%= render Keystone::Ui::NavItemComponent.new(label: tab.label, href: tab.href, active: tab.active) %>
+      <% else %>
+        <%= render Keystone::Ui::NavDropdownComponent.new(title: group.label, area: group.label, active: group.active) do %>
+          <% group.tabs.each do |tab| %>
+            <%= render Keystone::Ui::NavItemComponent.new(label: tab.label, href: tab.href, active: tab.active) %>
+          <% end %>
         <% end %>
       <% end %>
     <% end %>

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

@@ -11,6 +11,7 @@ module Keystone
       SIDEBAR_LOGO_CLASSES = "ks-sidebar-logo"
       SIDEBAR_GROUP_CLASSES = "flex flex-col"
       SIDEBAR_GROUP_LABEL_CLASSES = "ks-sidebar-group-label"
+      SIDEBAR_GROUP_TABS_CLASSES = "ks-sidebar-group-tabs"
       SIDEBAR_TAB_CLASSES = "ks-sidebar-tab"
       ACTIVE_CLASS = "active"
       SIDEBAR_MENUS_CLASSES = [

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

@@ -0,0 +1 @@
+<p class="ks-paragraph"><%= text %></p>

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class ParagraphComponent < ViewComponent::Base
+      attr_reader :text
+
+      def initialize(text:)
+        @text = text
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui_helper.rb

@@ -237,6 +237,18 @@ module KeystoneUiHelper
     render Keystone::Ui::FigureComponent.new(**args)
   end
 
+  def ui_heading(**args)
+    render Keystone::Ui::HeadingComponent.new(**args)
+  end
+
+  def ui_caption(**args)
+    render Keystone::Ui::CaptionComponent.new(**args)
+  end
+
+  def ui_paragraph(**args)
+    render Keystone::Ui::ParagraphComponent.new(**args)
+  end
+
   def ui_info(**args, &block)
     render(Keystone::Ui::InfoComponent.new(**args), &block)
   end

data/lib/keystone_ui/configuration.rb

@@ -31,6 +31,12 @@ module KeystoneUi
       @navigation_groups << group
     end
 
+    def navigation_tab(key, label:, href:, permitted:)
+      group = NavigationGroup.new(label, standalone: true)
+      group.tab(key, label: label, href: href, permitted: permitted)
+      @navigation_groups << group
+    end
+
     def supplied_look(view)
       look_supplier&.call(view)&.to_s
     end

data/lib/keystone_ui/navigation_group.rb

@@ -10,11 +10,16 @@ module KeystoneUi
 
     attr_reader :label, :tabs
 
-    def initialize(label)
+    def initialize(label, standalone: false)
       @label = label
+      @standalone = standalone
       @tabs = []
     end
 
+    def standalone?
+      @standalone
+    end
+
     def tabs_permitted_for(view)
       tabs.select { |tab| tab.permitted.call(view) }
     end

data/lib/keystone_ui/safelist.rb

@@ -14,7 +14,9 @@ module Keystone
       Keystone::Ui::LineChartComponent,
       Keystone::Ui::CtaBannerComponent,
       Keystone::Ui::FeatureGridComponent,
+      Keystone::Ui::CaptionComponent,
       Keystone::Ui::FigureComponent,
+      Keystone::Ui::HeadingComponent,
       Keystone::Ui::HeroComponent,
       Keystone::Ui::ModalComponent,
       Keystone::Ui::SelectComponent,
@@ -32,6 +34,7 @@ module Keystone
       Keystone::Ui::TextareaComponent,
       Keystone::Ui::FormFieldComponent,
       Keystone::Ui::PageHeaderComponent,
+      Keystone::Ui::ParagraphComponent,
       Keystone::Ui::AlertComponent,
       Keystone::Ui::NavDropdownComponent,
       Keystone::Ui::NavItemComponent,

data/lib/keystone_ui/version.rb

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

data/lib/keystone_ui/visible_navigation.rb

@@ -4,7 +4,7 @@ require "keystone_ui/navigation_order"
 
 module KeystoneUi
   class VisibleNavigation
-    Group = Struct.new(:label, :tabs, :active, keyword_init: true)
+    Group = Struct.new(:label, :tabs, :active, :standalone, keyword_init: true)
     Tab = Struct.new(:label, :href, :active, keyword_init: true)
 
     def initialize(declared_groups, view:, saved_order:, current_tab:)
@@ -28,7 +28,7 @@ module KeystoneUi
 
     def visible_group(group, tabs)
       visible_tabs = tabs.map { |tab| visible_tab(tab) }
-      Group.new(label: group.label, tabs: visible_tabs, active: visible_tabs.any?(&:active))
+      Group.new(label: group.label, tabs: visible_tabs, active: visible_tabs.any?(&:active), standalone: group.standalone?)
     end
 
     def visible_tab(tab)

data/the_local/agents/keystone_ui-develop.md

@@ -63,6 +63,9 @@ not available in the app yet, that is `keystone_ui-install`'s job.
 - `ui_button` — a link or a button styled as a button.
 - `ui_badge` — a coloured pill holding a short label.
 - `ui_figure` — one amount as inline text, coloured as a gain or a loss.
+- `ui_heading` — a heading at one of three sizes, with an optional short note on its right.
+- `ui_caption` — small uppercase muted text placed above a title or a figure.
+- `ui_paragraph` — a paragraph of running text.
 - `ui_alert` — a banner message, optionally dismissible.
 - `ui_progress` — a labelled progress bar.
 - `ui_stat_card` — a single metric tile with optional change, link and info button.
@@ -197,7 +200,10 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
      it goes around `yield`. It draws the tabs the app declares with
      `config.navigation_group` as a top bar of menus from `lg:` up, then the
      content, and below `lg:` it draws only the content. It leaves out tabs
-     whose permission check fails and groups with no tab left.
+     whose permission check fails and groups with no tab left. A tab declared
+     outside any group with `config.navigation_tab` is drawn as a plain link
+     in the top bar and as a plain tab with no group label in the sidebar,
+     which does not open or close.
    - Inside its block, `navigation.with_logo do ... end` puts the app's logo at
      the left of the top bar, and `navigation.with_menus do ... end` puts menus
      such as the account menu at its right, so the layout draws no second bar.
@@ -394,6 +400,10 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
    - `ui_disclosure(open: false)` takes a block yielding the component. Fill
      its `summary` slot with the header, and the rest of the block is the body.
    - `ui_accordion(items: [])` — `items:` is `[{ question:, answer: }, ...]`.
+   - `ui_heading(text:, size: :md, note: nil)` — `size:` is `:sm` `:md` `:lg`,
+     and `note:` puts a short muted note at the right end of the heading's row.
+   - `ui_caption(text:)` shows small uppercase muted text above a title or a figure.
+   - `ui_paragraph(text:)` shows running text.
 
 10. Explain figures.
 

data/the_local/agents/keystone_ui-install.md

@@ -31,6 +31,8 @@ built on ViewComponent; hook it in before building any screen with those helpers
   saves to, and the navigation's placement under the key `:navigation`),
   `navigation_group` (a labelled group of desktop tabs that the navigation
   helper draws, each tab declared with `tab key, label:, href:, permitted:`),
+  `navigation_tab` (a single desktop tab outside any group, declared with
+  `navigation_tab key, label:, href:, permitted:`),
   `current_tab_supplier` (a callable that supplies the key of the declared tab
   the current page belongs to, so the navigation marks it and its group
   active),
@@ -324,6 +326,11 @@ built on ViewComponent; hook it in before building any screen with those helpers
      `href:`, when two tabs share a key, or when a group has no tabs. Drawing
      the declared groups in the layout is done with the navigation helper,
      which belongs to `keystone_ui-develop`.
+   - `navigation_tab key, label:, href:, permitted:` — declares one tab
+     outside any group, such as a Console or Clients tab, in its place among
+     the groups. The navigation helper draws it as a plain link in the top bar
+     and as a plain tab with no group label in the sidebar. A saved `"order"`
+     names it under `"group"` by its label.
    - `current_tab_supplier` — a callable that receives the view and returns the
      key of the declared tab the current page belongs to, or `nil`.
      The navigation shows that tab and its group as active in the top bar and

data/the_local/interface.yml

@@ -64,6 +64,9 @@ develop:
   - ui_calculation
   - ui_info
   - ui_figure
+  - ui_heading
+  - ui_caption
+  - ui_paragraph
   - ui_breakdown
   - ui_theme_toggle
   - Keystone::Ui::Column

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.42.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.15.0
+        version: 0.19.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.15.0
+        version: 0.19.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -98,6 +98,8 @@ files:
 - 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/caption_component.html.erb
+- app/components/keystone/ui/caption_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
@@ -139,6 +141,8 @@ files:
 - app/components/keystone/ui/funnel_component.rb
 - app/components/keystone/ui/grid_component.html.erb
 - app/components/keystone/ui/grid_component.rb
+- app/components/keystone/ui/heading_component.html.erb
+- app/components/keystone/ui/heading_component.rb
 - app/components/keystone/ui/hero_component.html.erb
 - app/components/keystone/ui/hero_component.rb
 - app/components/keystone/ui/info_component.html.erb
@@ -171,6 +175,8 @@ files:
 - app/components/keystone/ui/page_header_component.rb
 - app/components/keystone/ui/panel_component.html.erb
 - app/components/keystone/ui/panel_component.rb
+- app/components/keystone/ui/paragraph_component.html.erb
+- app/components/keystone/ui/paragraph_component.rb
 - app/components/keystone/ui/pipeline_component.html.erb
 - app/components/keystone/ui/pipeline_component.rb
 - app/components/keystone/ui/progress_component.html.erb