keystone_ui 0.76.0 → 0.78.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: 83cb8847534e6d738d9100c1d2ac5042d481dfcfc40f04c99f108bfd155ef4ce
4
- data.tar.gz: 1707b5be58e4b7b2a9cae7a0a3fab60a0f823e5a0fe3ae6decf8795d28dbdd53
3
+ metadata.gz: 1caef93fc9a8ea85b3cb62b32540c5e13331092dfaf11b954bc9bdf0ed3f4cc6
4
+ data.tar.gz: 22c5443af455f0aef44503f7d1b2a9203a95c879f0dfbf16a393964b215dcbf0
5
5
  SHA512:
6
- metadata.gz: f71a4a8d8a2b3a8d44093c7673958dfdfb64221f86fcf84460b3141a800c364525f3bca044a586cc5eaa4b16916d68a0c221f28e967a1f08c6c1d5470dfcc4fc
7
- data.tar.gz: fa87049702215deaa3a8d44ded3171efff9f840c837f2fea09bfd293cf4c6719bc395bb791dd434cb1bae584f394eee7b943d14b9f8cc639b2bca82766501f90
6
+ metadata.gz: 81b1ce2589195e37bd88d677930b3d3d94e00a6609eecd6c44ed290970605d0de4febfd25d098177d8207a08eb8f371252c9d9c7f048c23645d2ba2964f035dd
7
+ data.tar.gz: 3fa5d47c0b4d4da2ead387a0e8c52dc4067afbc4dcf13693f16b0fc32ac28f31654ac0af290a26d061101fb220dd8ca0904f56ec983960e4b580057e5e430912
@@ -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,28 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Keystone
4
+ module Ui
5
+ class StatusDotComponent < ViewComponent::Base
6
+ STATE_CLASSES = {
7
+ neutral: "ks-status-dot-neutral",
8
+ success: "ks-status-dot-success",
9
+ danger: "ks-status-dot-danger",
10
+ warning: "ks-status-dot-warning",
11
+ info: "ks-status-dot-info"
12
+ }.freeze
13
+
14
+ LABEL_CLASSES = "sr-only"
15
+
16
+ def initialize(state:, label:)
17
+ raise ArgumentError, "Unknown status dot state #{state.inspect}, expected one of #{STATE_CLASSES.keys.join(', ')}" unless STATE_CLASSES.key?(state)
18
+
19
+ @state = state
20
+ @label = label
21
+ end
22
+
23
+ def call
24
+ tag.span(class: "ks-status-dot #{STATE_CLASSES[@state]}") { tag.span(@label, class: LABEL_CLASSES) }
25
+ end
26
+ end
27
+ end
28
+ end
@@ -161,6 +161,10 @@ module KeystoneUiHelper
161
161
  render Keystone::Ui::MobileActionComponent.new
162
162
  end
163
163
 
164
+ def ui_bottom_action
165
+ render Keystone::Ui::BottomActionComponent.new
166
+ end
167
+
164
168
  def ui_navbar(**args, &block)
165
169
  render Keystone::Ui::NavbarComponent.new(**args), &block
166
170
  end
@@ -201,6 +205,10 @@ module KeystoneUiHelper
201
205
  render Keystone::Ui::ProgressComponent.new(**args)
202
206
  end
203
207
 
208
+ def ui_status_dot(**args)
209
+ render Keystone::Ui::StatusDotComponent.new(**args)
210
+ end
211
+
204
212
  def ui_settings_link(**args)
205
213
  render Keystone::Ui::SettingsLinkComponent.new(**args)
206
214
  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,
@@ -75,6 +76,7 @@ module Keystone
75
76
  Keystone::Ui::DisclosureComponent,
76
77
  Keystone::Ui::ThemeToggleComponent,
77
78
  Keystone::Ui::TimelineComponent,
79
+ Keystone::Ui::StatusDotComponent,
78
80
  Keystone::Ui::CalculationComponent,
79
81
  Keystone::Ui::DesktopBackLinkComponent,
80
82
  Keystone::Ui::BreadcrumbsComponent,
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module KeystoneUi
4
- VERSION = "0.76.0"
4
+ VERSION = "0.78.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, 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.
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, status dots coloured by state, 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.
@@ -66,6 +67,7 @@ not available in the app yet, that is `keystone_ui-install`'s job.
66
67
  - `ui_column_picker` — a Columns menu that saves which columns are hidden and their order to an app endpoint.
67
68
  - `ui_button` — a link or a button styled as a button, or a button sending a POST, PATCH or DELETE request.
68
69
  - `ui_badge` — a coloured pill holding a short label.
70
+ - `ui_status_dot` — a small dot coloured by state, with its label read only by screen readers.
69
71
  - `ui_figure` — one amount as inline text, coloured as a gain or a loss.
70
72
  - `ui_picture` — an image never taller than half the screen, optionally opening its full-size file.
71
73
  - `ui_heading` — a heading at one of three sizes, with an optional short note on its right.
@@ -310,6 +312,20 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
310
312
  a Hotwire Native web view, so give native users another way to reach the
311
313
  action, such as `ui_mobile_actions`. The layout must also write the
312
314
  `hotwire-native` class on `<html>` and declare that Tailwind variant.
315
+ - `ui_bottom_action` takes no keywords and no block. It draws the
316
+ `action_url:` a screen gives `ui_page_header` as a full-width `ui_button`
317
+ labelled with its `action_label:`, in a bar fixed to the bottom of the
318
+ screen, above `ui_bottom_nav` on a page that has one. With
319
+ `action_method:` the button sends that method as `ui_button` does, so it
320
+ cannot sit inside a form. It draws nothing when the screen gives no
321
+ `action_url:`, so call it after `ui_page_header` has run, such as in the
322
+ layout after `yield`. It is hidden from `sm:` up, inside a Hotwire Native
323
+ web view and in print, like `ui_mobile_action`. It also draws an invisible
324
+ copy of the bar in the page's flow, plus the bottom nav's height when the
325
+ page has a `ui_bottom_nav`, so the page's last content scrolls clear of
326
+ both. Add no padding of your own for them. It and `ui_mobile_action`
327
+ draw the same action, so ask the developer which one a screen shows on a
328
+ phone.
313
329
  - `ui_settings_link(label:, href:)` renders one settings row.
314
330
  - `ui_theme_toggle` takes no keywords and no block. Its buttons switch the
315
331
  theme at once and store the choice in the `keystone_theme` cookie for a
@@ -587,6 +603,13 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
587
603
  the developer which version of an uploaded image each address points at.
588
604
  - `ui_badge(label:, variant: :neutral, class: nil)` — `variant:` is
589
605
  `:neutral` `:success` `:danger` `:warning` `:info`.
606
+ - `ui_status_dot(state:, label:)` — `state:` is `:neutral` `:success`
607
+ `:danger` `:warning` `:info`, and any other value raises `ArgumentError`
608
+ naming it. `label:` is not shown on screen and is read out by screen
609
+ readers, so pass words that say what the state means. The dot takes the
610
+ colour of a `ui_badge` of the same name. Use it where a badge's words
611
+ would crowd the row, such as beside a name in a list, and ask the
612
+ developer which states a record has and what each one means.
590
613
  - `ui_alert(message:, type: :info, title: nil, dismissible: false, class: nil)`
591
614
  — `type:` is `:info` `:success` `:warning` `:error`, and `dismissible: true`
592
615
  adds a close button.
@@ -767,7 +790,8 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
767
790
  shows nothing, a breakdown in one run of text, a `:success` or `:danger`
768
791
  figure in plain colour, a joined funnel with no band, a locked column the
769
792
  others show through, a Columns menu with no greyed name for a hidden
770
- column, or a table row whose caret does not open its detail — the app's Stimulus controllers or keystone_ui-styles version are
793
+ column, a table row whose caret does not open its detail, or a status dot
794
+ that draws nothing — the app's Stimulus controllers or keystone_ui-styles version are
771
795
  out of date. Stop and hand that part to `keystone_ui-install`, and add no
772
796
  classes to fix it.
773
797
 
@@ -793,7 +817,7 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
793
817
  and swipe deck render only what is registered through the object they yield,
794
818
  so anything else emitted in their block is dropped.
795
819
  - **Check both screen sizes.** Page headers with no badges or menu, mobile headers, mobile actions,
796
- bottom navigation, breadcrumbs and `ui_navigation`'s bars render on one side
820
+ the bottom action, bottom navigation, breadcrumbs and `ui_navigation`'s bars render on one side
797
821
  of `lg:` or `sm:` only, so a screen needs both treatments.
798
822
  - Out of scope: installing or upgrading the gem, its configuration, the theme
799
823
  attributes on the layout, and the palette, which belong to
@@ -12,8 +12,8 @@ nothing and gives no steps.
12
12
 
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
- sections, panels, grids, forms and fields, search dropdowns, data tables, navigation, cards, stat
16
- tiles, charts, timelines, funnels, goal buckets, pipelines, breakdowns and info buttons —
15
+ sections, panels, grids, forms and fields, search dropdowns, data tables, navigation, cards,
16
+ badges, status dots, stat 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
@@ -93,9 +93,22 @@ One decision: is keystone_ui set up in the app?
93
93
  submits an empty id and shows the new record's fields the page placed inside
94
94
  the dropdown, and picking a match afterwards hides them again. The arrow keys
95
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.
96
104
  - **Action menus.** Each action is a label, an address and an HTTP method. A
97
105
  plain visit is a link, and any other method is a button, so an action that
98
106
  changes data is never a bare link. A delete asks for confirmation by default.
107
+ - **Status states.** A badge and a status dot share five states: neutral,
108
+ success, danger, warning and info. A badge shows its label as text. A status
109
+ dot shows only its state's colour, for places with no room for text, and its label
110
+ is read only by screen readers. A status dot raises `ArgumentError` on any
111
+ other state.
99
112
  - **Semantic colour.** The themed hue is `accent-*` and the themed neutrals are
100
113
  `surface-*`, CSS custom properties whose defaults (blue and zinc) come from
101
114
  the keystone_ui-styles gem. Retheming changes those values, not the
@@ -119,4 +132,4 @@ One decision: is keystone_ui set up in the app?
119
132
  Stimulus controllers, so a host writes no JavaScript. Components that post,
120
133
  such as the column picker and the pipeline, post to endpoints the host or
121
134
  another gem owns.
122
- - Ruby >= 3.2, ViewComponent >= 2.0 and < 5, keystone_ui-styles >= 0.33.0.
135
+ - 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.33.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
 
@@ -18,6 +18,7 @@ develop:
18
18
  - ui_hero
19
19
  - ui_modal
20
20
  - ui_badge
21
+ - ui_status_dot
21
22
  - ui_copy_button
22
23
  - ui_card
23
24
  - ui_button
@@ -42,6 +43,7 @@ develop:
42
43
  - ui_mobile_header
43
44
  - ui_mobile_actions
44
45
  - ui_mobile_action
46
+ - ui_bottom_action
45
47
  - ui_action_menu
46
48
  - ui_action_menu_item
47
49
  - ui_navbar
@@ -102,6 +104,7 @@ sources:
102
104
  - app/components/keystone/ui/link_list_component.rb
103
105
  - app/components/keystone/ui/link_list_component.html.erb
104
106
  - app/components/keystone/ui/badge_component.rb
107
+ - app/components/keystone/ui/status_dot_component.rb
105
108
  - app/components/keystone/ui/bottom_nav_component.rb
106
109
  - app/components/keystone/ui/bottom_nav_item_component.rb
107
110
  - app/components/keystone/ui/button_component.rb
@@ -148,6 +151,7 @@ sources:
148
151
  - app/components/keystone/ui/line_chart_component.rb
149
152
  - app/components/keystone/ui/mobile_actions_component.rb
150
153
  - app/components/keystone/ui/mobile_action_component.rb
154
+ - app/components/keystone/ui/bottom_action_component.rb
151
155
  - app/components/keystone/ui/action_menu_component.rb
152
156
  - app/components/keystone/ui/action_menu_item_component.rb
153
157
  - app/components/keystone/ui/mobile_header_component.rb
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.76.0
4
+ version: 0.78.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
@@ -213,6 +214,7 @@ files:
213
214
  - app/components/keystone/ui/sortable_list_component.rb
214
215
  - app/components/keystone/ui/stat_card_component.html.erb
215
216
  - app/components/keystone/ui/stat_card_component.rb
217
+ - app/components/keystone/ui/status_dot_component.rb
216
218
  - app/components/keystone/ui/swipe_deck_component.html.erb
217
219
  - app/components/keystone/ui/swipe_deck_component.rb
218
220
  - app/components/keystone/ui/tab_switcher_component.html.erb