keystone_ui 0.26.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9326e16fe4c64a14c5887cd37a4dee97f6a5683572c5170312f9696f0826b1f
-  data.tar.gz: 1f4b15310af0f3fd7ef1523137eb7f35b7697cddf64a3d0326259ae2d3b480c0
+  metadata.gz: 88ffa01b58c46bdab1ddcf7657b1b60e3caf4320519cb64e5bcf6dfc59e047c9
+  data.tar.gz: 151698597ec642c7a410e5835d4b66f3c5b17a1fc778c995f9b583d912e565df
 SHA512:
-  metadata.gz: b8d0630ea4fc5547a6f1644fcb73b61630189baae97fe6b2525847b5a8858a28b7db0bcc5d841f4c03541d3f985e99a8eb07f0fe3330ffa6450c90e1d9680081
-  data.tar.gz: e26a899b093a8f678c60b43dfe6a8e3d92a2d52c0f38accd1b3421649d99ed36800ad9c3c2a201ba4857c069d5af1c66afb094ad05c182cacfa5cf590fb80546
+  metadata.gz: 97232de923802fef99483afbdfc76ecc8cac4a7220ed40e97aa4d19426fb885b0d5c012b587ec7e94cd980042fb27d70b99d832e332addd608e4d41645901618
+  data.tar.gz: 7b6cf8260919c664248a7246eda7d917e580d6d709737eb83b2d27d7e9e67e37c45fb4302061b8d824cf5e96bd20af403eb07e9f3c6c78f6e4571920f3d0ff6a

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

@@ -1,7 +1,13 @@
-<label class="<%= row_classes %>">
+<label class="<%= row_classes %> relative"<%= ' data-controller="stat-card-info"'.html_safe if info? %>>
   <input type="checkbox" name="<%= name %>" value="<%= value %>" <%= "checked" if checked? %> class="<%= input_classes %>">
   <span>
-    <span class="<%= label_classes %>"><%= label %></span>
+    <span class="<%= header_classes %>">
+      <span class="<%= label_classes %>"><%= label %></span>
+      <% if info? %>
+        <button type="button" class="<%= info_button_classes %>" data-action="click->stat-card-info#toggle" aria-label="About <%= label %>"><%= info_icon.html_safe %></button>
+        <span class="<%= disclosure_classes %>" data-stat-card-info-target="panel"><%= info %></span>
+      <% end %>
+    </span>
     <% if hint? %>
       <span class="<%= hint_classes %>"><%= hint %></span>
     <% end %>

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

@@ -7,14 +7,18 @@ module Keystone
       INPUT_CLASSES = "ks-checkbox-row-input size-4 shrink-0"
       LABEL_CLASSES = "ks-checkbox-row-label block text-sm"
       HINT_CLASSES = "ks-checkbox-row-hint block text-sm"
+      HEADER_CLASSES = RadioCardComponent::HEADER_CLASSES
+      INFO_BUTTON_CLASSES = RadioCardComponent::INFO_BUTTON_CLASSES
+      DISCLOSURE_CLASSES = RadioCardComponent::DISCLOSURE_CLASSES
 
-      attr_reader :name, :value, :label, :hint
+      attr_reader :name, :value, :label, :hint, :info
 
-      def initialize(name:, value:, label:, hint: nil, checked: false)
+      def initialize(name:, value:, label:, hint: nil, info: nil, checked: false)
         @name = name
         @value = value
         @label = label
         @hint = hint
+        @info = info
         @checked = checked
       end
 
@@ -26,6 +30,22 @@ module Keystone
         !@hint.nil?
       end
 
+      def info?
+        !@info.nil?
+      end
+
+      def info_button_classes
+        INFO_BUTTON_CLASSES
+      end
+
+      def disclosure_classes
+        DISCLOSURE_CLASSES
+      end
+
+      def info_icon
+        RadioCardComponent::INFO_ICON
+      end
+
       def row_classes
         ROW_CLASSES
       end
@@ -34,6 +54,10 @@ module Keystone
         INPUT_CLASSES
       end
 
+      def header_classes
+        HEADER_CLASSES
+      end
+
       def label_classes
         LABEL_CLASSES
       end

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

@@ -22,6 +22,13 @@
     </select>
   <% else %>
     <%= tag.input(**input_options) %>
+    <% if suggestions? %>
+      <datalist id="<%= suggestions_id %>">
+        <% suggestions.each do |suggestion| %>
+          <option value="<%= suggestion %>"></option>
+        <% end %>
+      </datalist>
+    <% end %>
   <% end %>
 
   <% if hint? %>

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

@@ -11,7 +11,7 @@ module Keystone
       CHECKBOX_CLASSES = "ks-checkbox"
       CHECKBOX_WRAPPER_CLASSES = "ks-form-field-checkbox flex items-center"
 
-      def initialize(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false)
+      def initialize(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false, suggestions: [])
         @attribute = attribute
         @label = label
         @type = type
@@ -26,6 +26,7 @@ module Keystone
         @errors = Array(errors)
         @include_blank = include_blank.to_s
         @disabled = disabled
+        @suggestions = Array(suggestions)
       end
 
       def label_text
@@ -83,8 +84,21 @@ module Keystone
         options[:max] = @max unless @max.nil?
         options[:step] = @step unless @step.nil?
         options[:disabled] = true if @disabled
+        options[:list] = suggestions_id if suggestions?
         options
       end
+
+      def suggestions?
+        @suggestions.any?
+      end
+
+      def suggestions
+        @suggestions
+      end
+
+      def suggestions_id
+        "#{@attribute.to_s.parameterize}-suggestions"
+      end
     end
   end
 end

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

@@ -1,7 +1,13 @@
-<label class="inline-block cursor-pointer">
+<label class="inline-block cursor-pointer relative"<%= ' data-controller="stat-card-info"'.html_safe if info? %>>
   <input type="radio" name="<%= name %>" value="<%= value %>" <%= "checked" if checked? %> class="peer sr-only">
   <span class="<%= classes %>">
-    <span class="<%= label_classes %>"><%= label %></span>
+    <span class="<%= header_classes %>">
+      <span class="<%= label_classes %>"><%= label %></span>
+      <% if info? %>
+        <button type="button" class="<%= info_button_classes %>" data-action="click->stat-card-info#toggle" aria-label="About <%= label %>"><%= info_icon.html_safe %></button>
+        <span class="<%= disclosure_classes %>" data-stat-card-info-target="panel"><%= info %></span>
+      <% end %>
+    </span>
     <% if hint? %>
       <span class="<%= hint_classes %>"><%= hint %></span>
     <% end %>

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

@@ -5,16 +5,21 @@ module Keystone
     class RadioCardComponent < ViewComponent::Base
       BASE_CLASSES = "ks-radio-card inline-flex flex-col cursor-pointer transition"
       HIGHLIGHT_CLASSES = "ks-radio-card-highlight"
+      HEADER_CLASSES = "ks-radio-card-header flex items-start justify-between"
       LABEL_CLASSES = "ks-radio-card-label block"
       HINT_CLASSES = "ks-radio-card-hint block text-sm"
+      INFO_BUTTON_CLASSES = "ks-radio-card-info peer shrink-0"
+      DISCLOSURE_CLASSES = "ks-radio-card-disclosure hidden peer-hover:block absolute inset-x-0 top-full z-10 text-sm"
+      INFO_ICON = Keystone::Ui::StatCardComponent::INFO_ICON
 
-      attr_reader :name, :value, :label, :hint
+      attr_reader :name, :value, :label, :hint, :info
 
-      def initialize(name:, value:, label:, hint: nil, checked: false)
+      def initialize(name:, value:, label:, hint: nil, info: nil, checked: false)
         @name = name
         @value = value
         @label = label
         @hint = hint
+        @info = info
         @checked = checked
       end
 
@@ -26,10 +31,30 @@ module Keystone
         !@hint.nil?
       end
 
+      def info?
+        !@info.nil?
+      end
+
+      def info_button_classes
+        INFO_BUTTON_CLASSES
+      end
+
+      def info_icon
+        INFO_ICON
+      end
+
+      def disclosure_classes
+        DISCLOSURE_CLASSES
+      end
+
       def classes
         "#{BASE_CLASSES} #{HIGHLIGHT_CLASSES}"
       end
 
+      def header_classes
+        HEADER_CLASSES
+      end
+
       def label_classes
         LABEL_CLASSES
       end

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -146,7 +146,7 @@ outer element. See Conventions before using it.
   The `<form>` wrapper. `method:` may be `:patch`/`:put`/`:delete` and is
   translated for Rails. Set `multipart: true` when the form contains a file
   upload.
-- `ui_form_field(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false)`
+- `ui_form_field(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [], include_blank: nil, disabled: false, suggestions: [])`
   — a labeled field with hint and error text. This is the default way to render
   an input. `type:` `:text` `:number` `:email` `:password` `:date` `:textarea`
   `:checkbox` `:select`. `attribute:` is used verbatim as the input's `name`, so
@@ -159,7 +159,12 @@ outer element. See Conventions before using it.
   it. Never add your own empty choice to `options:` as well. A
   `:checkbox` renders its label beside the box, submits `"0"` when unchecked and
   `"1"` when checked, and pre-checks when `value:` is `"1"`. `errors:` is an
-  array of message strings.
+  array of message strings. `suggestions:` is an array of strings the browser
+  offers while the field's text is typed, and the user can still type a value
+  that is not in it. It applies to `:text`, `:number`, `:email`, `:password`
+  and `:date` fields, and a `:textarea`, `:checkbox` or `:select` ignores it.
+  The suggestion list's `id` is built from `attribute:`, so two fields with
+  suggestions on one screen need different `attribute:` values.
 - `ui_input(name:, type: :text, value: nil, placeholder: nil, disabled: false, min: nil, max: nil, step: nil)`
   — a bare styled input with no label. `type:` `:text` `:number` `:email`
   `:password` `:date`.
@@ -178,13 +183,24 @@ outer element. See Conventions before using it.
   enclosing form to be multipart.
 - `ui_color_picker(name:, value: "#000000", label: nil)` — a swatch that opens a
   hue/saturation panel and writes the hex into a hidden input named `name`.
-- `ui_radio_card(name:, value:, label:, hint: nil, checked: false)` — a
-  selectable card backed by a real radio input; selection styling is pure CSS.
-- `ui_checkbox_row(name:, value:, label:, hint: nil, checked: false)` — a real
-  checkbox with its label and optional hint inside one `<label>`, so a tap
-  anywhere on the row toggles the box. A checked row submits `value` under
+- `ui_radio_card(name:, value:, label:, hint: nil, info: nil, checked: false)`
+  — a selectable card backed by a real radio input; selection styling is pure
+  CSS. `hint:` is a line of text always shown under the label. `info:` is
+  longer text about the option, kept hidden: passing it adds an info button on
+  the row with the label, named "About <label>" for screen readers, and the
+  text shows in a panel floating below the card while the button is hovered,
+  and tapping the button toggles it. With no `info:` the card has no info
+  button.
+- `ui_checkbox_row(name:, value:, label:, hint: nil, info: nil, checked: false)`
+  — a real checkbox with its label and optional hint inside one `<label>`, so a
+  tap anywhere on the row toggles the box. A checked row submits `value` under
   `name`; give several rows the same array name, e.g. `"shown[]"`, to submit the
-  checked values as a list. An unchecked row submits nothing. No JavaScript.
+  checked values as a list. An unchecked row submits nothing. `hint:` is a line
+  of text always shown under the label. `info:` works as it does on
+  `ui_radio_card`: passing it adds an info button on the line with the label,
+  named "About <label>" for screen readers, and the text shows in a panel
+  floating below the row while the button is hovered, and tapping the button
+  toggles it. With no `info:` the row has no info button.
 - `ui_option_card(name:, value:, selected: false, input_data: {}, label_data: {})`
   — takes a block. A radio whose visible body is whatever the block renders.
   `input_data:`/`label_data:` become `data-*` attributes on the input and label.
@@ -381,6 +397,13 @@ outer element. See Conventions before using it.
    To show the arithmetic behind a figure, put `ui_calculation` under it rather
    than a hand-built list. Which lines and groups to show is the app's own
    calculation, so ask the developer which steps a reader needs to see.
+   A field whose value must be one of a fixed list is a `:select` with
+   `options:`, and a field that accepts any text and offers common values is a
+   text field with `suggestions:`. Which one a field is, and which values it
+   suggests, is the app's own rule, so ask the developer rather than pick.
+   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.
    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

@@ -83,6 +83,17 @@ holds the catalog.
   "<label> this? This cannot be undone." unless it is given its own question,
   and other actions ask nothing unless given one. A data table puts each row's actions in one action menu at the end of the row,
   and a section can carry an action menu in its header beside its title.
+- **Info panels.** A stat card, a radio card and a checkbox row can each carry
+  extra text about themselves. Given that text, the piece shows an info button,
+  and the text stays hidden until the button is hovered or tapped. A piece
+  given no such text shows no button. On a radio card and a checkbox row the
+  button sits on the line with the label.
+- **Suggestions.** A form field can carry a list of suggested values. The
+  browser offers them while the field's text is typed, and the user can still
+  enter a value that is not on the list. This applies to a field with a typed
+  input, such as text, number, email, password or date. A textarea, select or
+  checkbox field ignores the list, and a field given no list offers nothing.
+  It needs no JavaScript.
 - **Options are symbols, and each component accepts its own set.** Appearance is
   chosen by name — `variant:`, `size:`, `type:`, `padding:`, `spacing:`,
   `max_width:`, `radius:` — on a size scale (`:sm` … `:xl`) or a short list of
@@ -141,7 +152,7 @@ holds the catalog.
   at boot where the component files are.
 - **Interactivity is Stimulus.** Dropdowns, modals, dismissible alerts, file
   uploads, the color picker, the multi-select, tab switchers, accordions, the
-  swipe deck, column pickers, stat card info panels, line charts, clipboard copy
+  swipe deck, column pickers, info panels, line charts, clipboard copy
   and the theme toggle ship with the gem as Stimulus controllers registered once
   at install. A host writes no JavaScript to use them. Components that post
   somewhere, such as the column picker and the pipeline, post to endpoints the

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.6.0 or later with it.
+   host app. The gem brings ViewComponent and keystone_ui-styles 0.8.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

@@ -128,6 +128,7 @@ sources:
   - app/components/keystone/ui/theme_toggle_component.rb
   - app/components/keystone/ui/progress_component.rb
   - app/components/keystone/ui/radio_card_component.rb
+  - app/components/keystone/ui/radio_card_component.html.erb
   - app/components/keystone/ui/section_component.rb
   - app/components/keystone/ui/section_component.html.erb
   - app/components/keystone/ui/select_component.rb

metadata

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