keystone_ui 0.75.0 → 0.77.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6255269764037507da7aeffe23291ddceefb9e418d99ba7fe02f25616a162e42
4
- data.tar.gz: 93a985c80b1f16d968719874b0db5838958a3d8a184e60ceae4081796d57f445
3
+ metadata.gz: 27865b2e7f95837a7c915aea020f129702dd705cea1dbc53cfb65f54039de0ac
4
+ data.tar.gz: fc80893a3e533c51f238cc4ac4e2162f567557a3ebb620fd959ab46be72dd196
5
5
  SHA512:
6
- metadata.gz: 84a9e06052c60efcdbcca6451ef323d586a9f02ca6dc61841b5d4f25746cf690d73899624986bb2c5824054d41686e3f61f736ceaf9e8bcce3ec6450c22d05d5
7
- data.tar.gz: 6737b46c2482e27b48c1bd6cc1d03da0fb2bd834c5d3f58f03ee1f64b1e60159b6e859404559ddc989327b9907d1a89116b08aff309afc5c5d5cf9e3ed6aec2d
6
+ metadata.gz: 5f7f08636bb8c78b3f5e8036f4decf9fa5781628c9d4fba01c748a409fb421840295b0914ae64629a8a9fbfdab0cf64f3f7fa4fa94494ef8dc3ad0ad4fb25c54
7
+ data.tar.gz: bd4a3ff320b6628a12bdf0a2678542885bbb1b679aecc8e0d5d8e89cc05280417631db2945f5eac98794352321765d66be7ae0d4a55d6ff3c8df40becf1eb039
@@ -0,0 +1,36 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Keystone
4
+ module Ui
5
+ class BottomActionComponent < ViewComponent::Base
6
+ BAR_CLASSES = "ks-bottom-action sm:hidden hotwire-native:hidden print:hidden"
7
+ SPACER_CLASSES = "sm:hidden hotwire-native:hidden print:hidden"
8
+ BAR_COPY_CLASSES = "!static invisible"
9
+ TAB_BAR_ROOM_CLASSES = "hidden h-(--ks-bottom-nav-height) [body:has(.ks-bottom-nav)_&]:block"
10
+
11
+ def render?
12
+ content_for?(:mobile_action_url)
13
+ end
14
+
15
+ def call
16
+ safe_join([ tag.div(class: BAR_CLASSES) { render button }, spacer ])
17
+ end
18
+
19
+ private
20
+
21
+ def spacer
22
+ tag.div(class: SPACER_CLASSES, inert: true, data: { bottom_action_spacer: true }) do
23
+ safe_join([ tag.div(class: "#{BAR_CLASSES} #{BAR_COPY_CLASSES}") { render button }, tag.div(class: TAB_BAR_ROOM_CLASSES) ])
24
+ end
25
+ end
26
+
27
+ def button
28
+ ButtonComponent.new(label: content_for(:mobile_action_label), href: content_for(:mobile_action_url), method: action_method, full_width: true)
29
+ end
30
+
31
+ def action_method
32
+ content_for?(:mobile_action_method) ? content_for(:mobile_action_method).to_sym : :get
33
+ end
34
+ end
35
+ end
36
+ end
@@ -0,0 +1,17 @@
1
+ <div class="flex flex-col gap-3">
2
+ <% entries.each do |entry| %>
3
+ <div data-timeline-row>
4
+ <div class="<%= ROW_TEXT_CLASSES %>">
5
+ <span data-timeline-label><%= entry[:label] %></span>
6
+ <span data-timeline-duration><%= duration(entry) %></span>
7
+ </div>
8
+ <div class="<%= TRACK_CLASSES %>">
9
+ <div class="<%= BAR_CLASSES %>" data-timeline-bar style="<%= bar_style(entry) %>"></div>
10
+ </div>
11
+ </div>
12
+ <% end %>
13
+ <div class="<%= AXIS_CLASSES %>">
14
+ <span data-timeline-axis-start><%= axis_start_label %></span>
15
+ <span data-timeline-axis-end><%= total_duration %></span>
16
+ </div>
17
+ </div>
@@ -0,0 +1,56 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Keystone
4
+ module Ui
5
+ class TimelineComponent < ViewComponent::Base
6
+ TRACK_CLASSES = "ks-progress-track relative w-full h-2 overflow-hidden"
7
+ BAR_CLASSES = "ks-progress-bar absolute inset-y-0"
8
+ ROW_TEXT_CLASSES = "ks-meter-label flex justify-between text-sm"
9
+ AXIS_CLASSES = "ks-meter-label flex justify-between text-xs"
10
+
11
+ attr_reader :entries
12
+
13
+ def initialize(entries:)
14
+ @entries = entries
15
+ end
16
+
17
+ def bar_style(entry)
18
+ "left: #{percent(entry[:started_at] - axis_start)}%; width: #{percent(entry[:ended_at] - entry[:started_at])}%"
19
+ end
20
+
21
+ def duration(entry)
22
+ written_duration(entry[:ended_at] - entry[:started_at])
23
+ end
24
+
25
+ def total_duration
26
+ written_duration(axis_end - axis_start)
27
+ end
28
+
29
+ def axis_start_label
30
+ written_duration(0)
31
+ end
32
+
33
+ private
34
+
35
+ def written_duration(seconds)
36
+ hours, rest = seconds.round.divmod(3600)
37
+ minutes, seconds = rest.divmod(60)
38
+ parts = [ [ hours, "h" ], [ minutes, "m" ], [ seconds, "s" ] ].drop_while { |amount, _| amount.zero? }
39
+ parts = [ [ 0, "s" ] ] if parts.empty?
40
+ parts.map { |amount, unit| "#{amount}#{unit}" }.join(" ")
41
+ end
42
+
43
+ def axis_start
44
+ @axis_start ||= entries.map { |entry| entry[:started_at] }.min
45
+ end
46
+
47
+ def axis_end
48
+ @axis_end ||= entries.map { |entry| entry[:ended_at] }.max
49
+ end
50
+
51
+ def percent(seconds)
52
+ format("%g", (seconds / (axis_end - axis_start) * 100).round(2))
53
+ end
54
+ end
55
+ end
56
+ end
@@ -25,6 +25,10 @@ module KeystoneUiHelper
25
25
  render Keystone::Ui::BarChartComponent.new(**args)
26
26
  end
27
27
 
28
+ def ui_timeline(**args)
29
+ render Keystone::Ui::TimelineComponent.new(**args)
30
+ end
31
+
28
32
  def ui_cta_banner(**args, &block)
29
33
  render Keystone::Ui::CtaBannerComponent.new(**args), &block
30
34
  end
@@ -157,6 +161,10 @@ module KeystoneUiHelper
157
161
  render Keystone::Ui::MobileActionComponent.new
158
162
  end
159
163
 
164
+ def ui_bottom_action
165
+ render Keystone::Ui::BottomActionComponent.new
166
+ end
167
+
160
168
  def ui_navbar(**args, &block)
161
169
  render Keystone::Ui::NavbarComponent.new(**args), &block
162
170
  end
@@ -51,6 +51,7 @@ module Keystone
51
51
  Keystone::Ui::FormPageComponent,
52
52
  Keystone::Ui::MobileActionsComponent,
53
53
  Keystone::Ui::MobileActionComponent,
54
+ Keystone::Ui::BottomActionComponent,
54
55
  Keystone::Ui::MobileHeaderComponent,
55
56
  Keystone::Ui::ShowPageComponent,
56
57
  Keystone::Ui::OptionCardComponent,
@@ -74,6 +75,7 @@ module Keystone
74
75
  Keystone::Ui::CodeComponent,
75
76
  Keystone::Ui::DisclosureComponent,
76
77
  Keystone::Ui::ThemeToggleComponent,
78
+ Keystone::Ui::TimelineComponent,
77
79
  Keystone::Ui::CalculationComponent,
78
80
  Keystone::Ui::DesktopBackLinkComponent,
79
81
  Keystone::Ui::BreadcrumbsComponent,
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module KeystoneUi
4
- VERSION = "0.75.0"
4
+ VERSION = "0.77.0"
5
5
  end
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: keystone_ui-develop
3
- description: Use PROACTIVELY for building or editing screens in a Rails app that has keystone_ui — page shells with Back links and breadcrumbs, forms and fields, a search field that picks a record or enters a new one, data tables with saved columns, desktop navigation, sidebars and bottom tabs, action menus for a record's Edit and Delete, dashboards with stat cards, charts, funnels and goal buckets, amounts shown in green or red as a gain or loss, pictures held to half the screen, info buttons and breakdowns, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
3
+ description: Use PROACTIVELY for building or editing screens in a Rails app that has keystone_ui — page shells with Back links and breadcrumbs, forms and fields, a search field that picks a record or enters a new one, data tables with saved columns, desktop navigation, sidebars and bottom tabs, a page's main action as a phone top-bar icon or a button fixed to the bottom of the screen, action menus for a record's Edit and Delete, dashboards with stat cards, charts, funnels, goal buckets and timelines of timed steps, amounts shown in green or red as a gain or loss, pictures held to half the screen, info buttons and breakdowns, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
4
4
  tools: Bash, Read, Write, Edit, Grep
5
5
  scope: UI — pages, forms, tables, navigation, dashboards
6
6
  ---
@@ -44,6 +44,7 @@ not available in the app yet, that is `keystone_ui-install`'s job.
44
44
  - `ui_mobile_header` — a mobile back arrow and a title beside it.
45
45
  - `ui_mobile_actions` — an ellipsis menu of actions shown only below `lg:`.
46
46
  - `ui_mobile_action` — a plus icon link to the action a screen's page header publishes, for the phone top bar.
47
+ - `ui_bottom_action` — a full-width button for the action a screen's page header publishes, in a bar fixed to the bottom of a phone screen.
47
48
  - `ui_action_menu` — an ellipsis menu of actions shown at every screen size.
48
49
  - `ui_action_menu_item` — one action in an action menu, as a link or a button sending a method.
49
50
  - `ui_settings_link` — a full-width settings row with a chevron.
@@ -95,6 +96,7 @@ not available in the app yet, that is `keystone_ui-install`'s job.
95
96
  - `ui_funnel` — a conversion funnel drawn as bars or one joined shape.
96
97
  - `ui_bucket` — an upright container filled toward a goal.
97
98
  - `ui_bucket_series` — a wrapping row of buckets.
99
+ - `ui_timeline` — rows of timed steps, each a bar placed by its start and end on one shared time axis.
98
100
  - `ui_pipeline` — a staged flow diagram with buttons and breakable links that post to the app.
99
101
  - `ui_hero` — a marketing hero with title, call-to-action buttons and an aside.
100
102
  - `ui_cta_banner` — a marketing banner holding call-to-action buttons.
@@ -309,6 +311,20 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
309
311
  a Hotwire Native web view, so give native users another way to reach the
310
312
  action, such as `ui_mobile_actions`. The layout must also write the
311
313
  `hotwire-native` class on `<html>` and declare that Tailwind variant.
314
+ - `ui_bottom_action` takes no keywords and no block. It draws the
315
+ `action_url:` a screen gives `ui_page_header` as a full-width `ui_button`
316
+ labelled with its `action_label:`, in a bar fixed to the bottom of the
317
+ screen, above `ui_bottom_nav` on a page that has one. With
318
+ `action_method:` the button sends that method as `ui_button` does, so it
319
+ cannot sit inside a form. It draws nothing when the screen gives no
320
+ `action_url:`, so call it after `ui_page_header` has run, such as in the
321
+ layout after `yield`. It is hidden from `sm:` up, inside a Hotwire Native
322
+ web view and in print, like `ui_mobile_action`. It also draws an invisible
323
+ copy of the bar in the page's flow, plus the bottom nav's height when the
324
+ page has a `ui_bottom_nav`, so the page's last content scrolls clear of
325
+ both. Add no padding of your own for them. It and `ui_mobile_action`
326
+ draw the same action, so ask the developer which one a screen shows on a
327
+ phone.
312
328
  - `ui_settings_link(label:, href:)` renders one settings row.
313
329
  - `ui_theme_toggle` takes no keywords and no block. Its buttons switch the
314
330
  theme at once and store the choice in the `keystone_theme` cookie for a
@@ -690,6 +706,16 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
690
706
  the fill turns green with `over: :success` or amber with `over: :warning`.
691
707
  - `ui_bucket_series(buckets:)` takes an array of hashes with the keywords
692
708
  of `ui_bucket`, such as `[{ goal: 10, actual: 7, label: "Mon" }, ...]`.
709
+ - `ui_timeline(entries:)` takes no block. `entries:` is
710
+ `[{ label:, started_at:, ended_at: }, ...]` in the order to list them,
711
+ with both times as `Time` values. The axis runs from the earliest
712
+ `started_at` to the latest `ended_at`. Each entry is one row: its label
713
+ and its duration on one line, then a track with a bar placed at its start
714
+ and as wide as its share of the axis. Under the rows the axis reads `0s`
715
+ on the left and the whole span on the right. Durations are written as
716
+ `1h 0m 5s`, leaving out leading zero units, and a zero duration is `0s`.
717
+ It needs at least one entry and a span longer than zero, so do not render
718
+ it for an empty list or for entries that all start and end at one moment.
693
719
  - `ui_pipeline(title:, boxes:, links:, subtitle: nil)` — `boxes:` is
694
720
  `[{ label:, count:, accent:, action: }, ...]`, with `accent:` one of
695
721
  `:amber` `:emerald` `:danger` `:muted`, and `action:` is
@@ -782,7 +808,7 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
782
808
  and swipe deck render only what is registered through the object they yield,
783
809
  so anything else emitted in their block is dropped.
784
810
  - **Check both screen sizes.** Page headers with no badges or menu, mobile headers, mobile actions,
785
- bottom navigation, breadcrumbs and `ui_navigation`'s bars render on one side
811
+ the bottom action, bottom navigation, breadcrumbs and `ui_navigation`'s bars render on one side
786
812
  of `lg:` or `sm:` only, so a screen needs both treatments.
787
813
  - Out of scope: installing or upgrading the gem, its configuration, the theme
788
814
  attributes on the layout, and the palette, which belong to
@@ -13,7 +13,7 @@ nothing and gives no steps.
13
13
  keystone_ui is a Rails engine gem that supplies a host app's UI as view helpers
14
14
  built on ViewComponent. Screens are built from named pieces — page shells,
15
15
  sections, panels, grids, forms and fields, search dropdowns, data tables, navigation, cards, stat
16
- tiles, charts, funnels, goal buckets, pipelines, breakdowns and info buttons —
16
+ tiles, charts, timelines, funnels, goal buckets, pipelines, breakdowns and info buttons —
17
17
  instead of hand-written ERB and Tailwind. Every class the UI renders lives in the
18
18
  gem, so two pages built from the same helpers cannot disagree about spacing,
19
19
  colour or dark-mode treatment, and a change to a component reaches every page
@@ -57,8 +57,10 @@ One decision: is keystone_ui set up in the app?
57
57
  - **Options are symbols.** Appearance is chosen by name, such as `variant:`,
58
58
  `size:` or `padding:`, and each component accepts its own set. Most raise on a
59
59
  symbol they do not know, so a wrong guess fails at render time.
60
- - **Numbers and text are different inputs.** Progress bars, funnels and buckets
61
- do arithmetic, so they take numbers, and a bucket raises on `"9,000"`. A
60
+ - **Numbers and text are different inputs.** Progress bars, funnels, buckets
61
+ and timelines do arithmetic, so they take numbers, and a bucket raises on
62
+ `"9,000"`. A timeline takes each row's start and end as times and works out
63
+ every duration, bar position and its axis from them. A
62
64
  breakdown, a calculation and a toned figure take already-formatted text, show
63
65
  it as written and add nothing up.
64
66
  - **Going back.** A form or show page shell needs a way back: a back link, a
@@ -91,6 +93,14 @@ One decision: is keystone_ui set up in the app?
91
93
  submits an empty id and shows the new record's fields the page placed inside
92
94
  the dropdown, and picking a match afterwards hides them again. The arrow keys
93
95
  move through the list, Enter picks, and Escape closes it.
96
+ - **A page's main action on a phone.** A page header can name one main action:
97
+ a label, an address and an optional HTTP method. The header shows it as a
98
+ button and also publishes it to the layout. Below `sm:` the layout can show it
99
+ again as a plus icon in the top bar, or as a full-width button in a bar fixed
100
+ to the bottom of the screen, above the bottom tab bar when the page has one. The page leaves room under
101
+ its last content so the bar does not cover it. Both forms show nothing when
102
+ the header names no action, and both are hidden inside a Hotwire Native web
103
+ view and in print.
94
104
  - **Action menus.** Each action is a label, an address and an HTTP method. A
95
105
  plain visit is a link, and any other method is a button, so an action that
96
106
  changes data is never a bare link. A delete asks for confirmation by default.
@@ -117,4 +127,4 @@ One decision: is keystone_ui set up in the app?
117
127
  Stimulus controllers, so a host writes no JavaScript. Components that post,
118
128
  such as the column picker and the pipeline, post to endpoints the host or
119
129
  another gem owns.
120
- - Ruby >= 3.2, ViewComponent >= 2.0 and < 5, keystone_ui-styles >= 0.29.0.
130
+ - Ruby >= 3.2, ViewComponent >= 2.0 and < 5, keystone_ui-styles >= 0.34.0.
@@ -50,7 +50,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
50
50
  ## How to use it
51
51
 
52
52
  1. Confirm the prerequisites: Ruby >= 3.2 and **tailwindcss-rails v4+** in the
53
- host app. The gem brings ViewComponent and keystone_ui-styles 0.29.0 or later with it.
53
+ host app. The gem brings ViewComponent and keystone_ui-styles 0.34.0 or later with it.
54
54
  Tailwind does not have to be initialized first, because the generator creates
55
55
  the stylesheet if it is missing.
56
56
 
@@ -166,7 +166,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
166
166
  these variables. So do the data display components: stat card, chart card,
167
167
  card link, CTA banner, feature grid, hero, data table, code, accordion,
168
168
  disclosure, calculation, info button, breakdown, figure, tab switcher, progress,
169
- funnel, bucket, pipeline and swipe deck.
169
+ timeline, funnel, bucket, pipeline and swipe deck.
170
170
  So do the navigation components: navbar, nav item, nav dropdown, bottom nav,
171
171
  mobile header and settings link. The desktop "Back" link and the breadcrumbs
172
172
  on form and show pages use the mobile header's back link variables. The
@@ -12,6 +12,7 @@ develop:
12
12
  - ui_chart_card
13
13
  - ui_line_chart
14
14
  - ui_bar_chart
15
+ - ui_timeline
15
16
  - ui_cta_banner
16
17
  - ui_feature_grid
17
18
  - ui_hero
@@ -41,6 +42,7 @@ develop:
41
42
  - ui_mobile_header
42
43
  - ui_mobile_actions
43
44
  - ui_mobile_action
45
+ - ui_bottom_action
44
46
  - ui_action_menu
45
47
  - ui_action_menu_item
46
48
  - ui_navbar
@@ -147,6 +149,7 @@ sources:
147
149
  - app/components/keystone/ui/line_chart_component.rb
148
150
  - app/components/keystone/ui/mobile_actions_component.rb
149
151
  - app/components/keystone/ui/mobile_action_component.rb
152
+ - app/components/keystone/ui/bottom_action_component.rb
150
153
  - app/components/keystone/ui/action_menu_component.rb
151
154
  - app/components/keystone/ui/action_menu_item_component.rb
152
155
  - app/components/keystone/ui/mobile_header_component.rb
@@ -184,3 +187,5 @@ sources:
184
187
  - app/components/keystone/ui/swipe_deck_component.rb
185
188
  - app/components/keystone/ui/tab_switcher_component.rb
186
189
  - app/components/keystone/ui/textarea_component.rb
190
+ - app/components/keystone/ui/timeline_component.rb
191
+ - app/components/keystone/ui/timeline_component.html.erb
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: keystone_ui
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.75.0
4
+ version: 0.77.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
15
15
  requirements:
16
16
  - - ">="
17
17
  - !ruby/object:Gem::Version
18
- version: 0.33.0
18
+ version: 0.34.0
19
19
  type: :runtime
20
20
  prerelease: false
21
21
  version_requirements: !ruby/object:Gem::Requirement
22
22
  requirements:
23
23
  - - ">="
24
24
  - !ruby/object:Gem::Version
25
- version: 0.33.0
25
+ version: 0.34.0
26
26
  - !ruby/object:Gem::Dependency
27
27
  name: view_component
28
28
  requirement: !ruby/object:Gem::Requirement
@@ -87,6 +87,7 @@ files:
87
87
  - app/components/keystone/ui/badge_component.rb
88
88
  - app/components/keystone/ui/bar_chart_component.html.erb
89
89
  - app/components/keystone/ui/bar_chart_component.rb
90
+ - app/components/keystone/ui/bottom_action_component.rb
90
91
  - app/components/keystone/ui/bottom_nav_component.html.erb
91
92
  - app/components/keystone/ui/bottom_nav_component.rb
92
93
  - app/components/keystone/ui/bottom_nav_item_component.html.erb
@@ -221,6 +222,8 @@ files:
221
222
  - app/components/keystone/ui/textarea_component.rb
222
223
  - app/components/keystone/ui/theme_toggle_component.html.erb
223
224
  - app/components/keystone/ui/theme_toggle_component.rb
225
+ - app/components/keystone/ui/timeline_component.html.erb
226
+ - app/components/keystone/ui/timeline_component.rb
224
227
  - app/components/keystone/ui/value_list_component.html.erb
225
228
  - app/components/keystone/ui/value_list_component.rb
226
229
  - app/helpers/keystone_ui_helper.rb