keystone_ui 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2d9cae890778efeef3333b64e2e04fa14955d60171b99d1f0fced2d64d0d8aa
-  data.tar.gz: 45bb649fa4211a143e3e5c987332de6b2849423f52bcb04765120f49aff9ba87
+  metadata.gz: 0ebdae8cec6c4c1ac5a5d9e0ba2c2f81af46ac2bcd2d1537dce3ac039287a895
+  data.tar.gz: 3729bc3f9486e0adca2a21482bf493c832506d36c0e5bb9e98a50bba7a70e49a
 SHA512:
-  metadata.gz: 193b52fdb0006bb35f2d58e50934755a3917b4f34348051a3d64a7b5b1eda768005c9dd74c7638ba585cd2fcc46f923730816f08a04f078d46e0132405cd310d
-  data.tar.gz: d2aa6186b582a92554c1c58139351e2ebb67c8682908bbbb849d72d2fa117cb6e92f0124cb024e0d1a9ea1cc85d138eb1f4f9da08f1cb5bcbf81cd72ae32c6c0
+  metadata.gz: 1091cd7bb197a64a0ceb327906932e191e11e19bbcdc2559283cfde82573a7ad36adc4a6b1c2e430fef41eeb421642e6d3779ca1879a172d009098e98a4cfbba
+  data.tar.gz: 2d532adcf2a254df72de1e82383f4f373a520c03503adbf31c9c45b881c2a0f8296348bb0f581b3360e8b7ff505fd22431a41f7fef6042fc15681cbf97242833

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

@@ -0,0 +1,11 @@
+<div class="<%= WRAPPER_CLASSES %>" data-controller="dropdown">
+  <button type="button"
+          data-action="click->dropdown#toggle click@window->dropdown#hide"
+          class="<%= BUTTON_CLASSES %>"
+          aria-label="Actions">
+    <%= ELLIPSIS_ICON.html_safe %>
+  </button>
+  <div data-dropdown-target="menu" class="<%= DROPDOWN_CLASSES %>">
+    <%= content %>
+  </div>
+</div>

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class ActionMenuComponent < ViewComponent::Base
+      WRAPPER_CLASSES = "relative inline-block"
+      BUTTON_CLASSES = MobileActionsComponent::BUTTON_CLASSES
+      DROPDOWN_CLASSES = MobileActionsComponent::DROPDOWN_CLASSES
+      ELLIPSIS_ICON = MobileActionsComponent::ELLIPSIS_ICON
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class ActionMenuItemComponent < ViewComponent::Base
+      ITEM_CLASSES = "ks-menu-option block w-full text-left"
+
+      def initialize(label:, href:, method: :get)
+        @label = label
+        @href = href
+        @method = method.to_sym
+      end
+
+      def call
+        return link_to(@label, @href, class: ITEM_CLASSES) if @method == :get
+
+        button_to(@href, method: @method, class: ITEM_CLASSES) { @label }
+      end
+    end
+  end
+end

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

@@ -43,7 +43,9 @@
             <% end %>
             <% if actions? %>
               <td class="<%= Keystone::Ui::DataTableComponent::ROW_CLASSES_LAST %>">
-                <%= capture(item, &@actions_block) %>
+                <%= render Keystone::Ui::ActionMenuComponent.new do %>
+                  <%= capture(item, &@actions_block) %>
+                <% end %>
               </td>
             <% end %>
           </tr>

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

@@ -12,6 +12,13 @@
           <%= @action[:label] %>
         </a>
       <% end %>
+      <% if @menu.any? %>
+        <%= render Keystone::Ui::ActionMenuComponent.new do %>
+          <% @menu.each do |item| %>
+            <%= render Keystone::Ui::ActionMenuItemComponent.new(**item) %>
+          <% end %>
+        <% end %>
+      <% end %>
     </div>
   <% end %>
   <%= content %>

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

@@ -9,10 +9,11 @@ module Keystone
       SUBTITLE_CLASSES = "ks-section-subtitle"
       ACTION_CLASSES = "ks-section-action"
 
-      def initialize(title: nil, subtitle: nil, action: nil, spacing: :md, class: nil)
+      def initialize(title: nil, subtitle: nil, action: nil, menu: [], spacing: :md, class: nil)
         @title = title
         @subtitle = subtitle
         @action = action
+        @menu = menu
         @spacing = spacing
         @extra_classes = binding.local_variable_get(:class)
       end

data/app/helpers/keystone_ui_helper.rb

@@ -125,6 +125,14 @@ module KeystoneUiHelper
     render Keystone::Ui::MobileHeaderComponent.new(**args)
   end
 
+  def ui_action_menu(**args, &block)
+    render Keystone::Ui::ActionMenuComponent.new(**args), &block
+  end
+
+  def ui_action_menu_item(**args)
+    render Keystone::Ui::ActionMenuItemComponent.new(**args)
+  end
+
   def ui_mobile_actions(**args, &block)
     render Keystone::Ui::MobileActionsComponent.new(**args), &block
   end

data/lib/keystone_ui/safelist.rb

@@ -6,6 +6,8 @@ module Keystone
     # The safelist_spec verifies this list matches Keystone::Ui components.
     COMPONENTS = [
       Keystone::Ui::AccordionComponent,
+      Keystone::Ui::ActionMenuComponent,
+      Keystone::Ui::ActionMenuItemComponent,
       Keystone::Ui::TabSwitcherComponent,
       Keystone::Ui::StatCardComponent,
       Keystone::Ui::ChartCardComponent,

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -1,6 +1,6 @@
 ---
 name: keystone_ui-develop
-description: Use PROACTIVELY for building or editing screens in a Rails app that has Keystone UI — pages, forms, tables, navigation, dashboards, charts, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
+description: Use PROACTIVELY for building or editing screens in a Rails app that has Keystone UI — pages, forms, tables, navigation, action menus for a record's Edit and Delete, dashboards, charts, marketing sections, a light/dark theme switch — MUST BE USED instead of hand-writing ERB and Tailwind for UI.
 tools: Read, Write, Edit, Grep
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -45,9 +45,13 @@ outer element. See Conventions before using it.
   `:lg` `:xl` to clear a fixed navbar. When `ui_form_page` or `ui_show_page` was
   called earlier on the same screen, `ui_page` renders their back link or
   breadcrumbs, and the form page's title, at its top, above the block.
-- `ui_section(title: nil, subtitle: nil, action: nil, spacing: :md, class: nil)`
+- `ui_section(title: nil, subtitle: nil, action: nil, menu: [], spacing: :md, class: nil)`
   — takes a block. A titled block of content with an optional right-aligned
   link. `action:` is `{ label:, href: }`; `spacing:` `:sm` `:md` `:lg`.
+  `menu:` is `[{ label:, href:, method: }, ...]`, each hash taking the keywords
+  of `ui_action_menu_item`, and renders an action menu at the right of the
+  header. The header, and with it `action:` and `menu:`, renders only when
+  `title:` is given.
 - `ui_panel(padding: :md, radius: :lg, shadow: true)` — takes a block. A bordered
   card surface. `padding:` `:sm` `:md` `:lg`; `radius:` `:md` `:lg` `:xl`.
 - `ui_grid(cols: { default: 1 }, gap: :md, gap_x: nil, gap_y: nil)` — takes a
@@ -113,8 +117,18 @@ outer element. See Conventions before using it.
 - `ui_mobile_header(title:, back_url:, subtitle: nil)` — a back chevron plus
   centered title for mobile; hidden above `lg:`. Place it in the navbar's
   `mobile_left` slot.
+- `ui_action_menu` — no keywords, takes a block. An ellipsis (⋯) button that
+  opens a dropdown of actions, shown at every screen size. Fill the block with
+  `ui_action_menu_item` calls.
+- `ui_action_menu_item(label:, href:, method: :get)` — one entry in an action
+  menu. With `method: :get` it is a link to `href`. Any other method, such as
+  `:post`, `:patch` or `:delete`, renders a button inside its own small form
+  that sends that method to `href`, so never place such an item inside a
+  `ui_form` block, since a form cannot contain another form. It asks for no
+  confirmation before sending.
 - `ui_mobile_actions` — no keywords, takes a block. An ellipsis dropdown for
-  mobile actions; the block holds the menu items. Hidden above `lg:`.
+  mobile actions; the block holds the menu items. Hidden above `lg:`. Use
+  `ui_action_menu` instead when the actions must also be reachable on desktop.
 - `ui_settings_link(label:, href:)` — a full-width settings row with a chevron.
 - `ui_theme_toggle` — no keywords, no block. A row of three buttons, Light, Dark
   and System, that switches the page's theme at once and remembers the choice in
@@ -180,7 +194,9 @@ outer element. See Conventions before using it.
   `columns:` accepts plain `{ key: "Label" }` hashes or `Keystone::Ui::Column`
   objects. In the block, `table.link(:column_key) { |item| url }` turns that
   column's cells into links and `table.actions { |item| ... }` appends a
-  right-aligned actions column. Sorting requires all three of `sort:` (the
+  right-aligned actions column. Each row's actions render inside an action
+  menu, so the `actions` block holds `ui_action_menu_item` calls and nothing
+  else, never buttons or bare links. Sorting requires all three of `sort:` (the
   current column key), `sort_direction:` (`:asc`/`:desc`), and `sort_url:` (a
   lambda taking `(column_key, direction)` and returning a URL); headers then
   render as links that flip direction. `hidden_columns:` drops columns
@@ -362,6 +378,12 @@ 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.
+   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.
+   An item that deletes or changes data sends without asking for
+   confirmation, so ask the developer whether that action needs a confirmation
+   step before adding it.
 
 6. For a table, decide how columns are declared. Use `{ key: "Label" }` hashes
    when every column is plain. Switch the whole set to `Keystone::Ui::Column`
@@ -421,7 +443,8 @@ outer element. See Conventions before using it.
   through it, so anything else emitted inside their block is discarded.
 - **Mobile is not an afterthought.** Several helpers render only on one side of
   the `lg:` (or `sm:`) breakpoint — page headers, mobile headers, mobile actions,
-  bottom navigation, breadcrumbs. A screen needs both treatments; check the small viewport
+  bottom navigation, breadcrumbs. The action menu is the exception and shows at
+  every size. A screen needs both treatments; check the small viewport
   before calling it done.
 - Out of scope for this local: installing or upgrading the gem, changing the
   palette or theme defaults, and editing the components themselves. Building a

data/the_local/agents/keystone_ui-info.md

@@ -74,6 +74,13 @@ holds the catalog.
   that render one thing (a button, a badge, a field, a stat, a bucket) are
   configured entirely by keyword arguments. The navigation bar exposes named
   slots instead of a single block.
+- **Action menus.** An action menu is an ellipsis button that opens a dropdown
+  of actions, shown at every screen size. The mobile action menu is the one
+  hidden from `lg:` up. Each action is a label, an address and an HTTP method.
+  A plain visit renders as a link. Any other method renders as a button that
+  sends that method, so an action that changes data is never a bare link. 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.
 - **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
@@ -100,7 +107,7 @@ holds the catalog.
   keystone_ui-styles 0.6.0 or later: corner radius, font, label weight, border
   width, padding and colours. Each colour variable has a `-dark` partner read
   on a dark page. Buttons, panels, cards, alerts, badges, form fields, the
-  modal, the mobile action menu, the column picker, multi select, copy button,
+  modal, the action menu, the mobile action menu, the column picker, multi select, copy button,
   theme toggle, checkbox row, radio card, option card, file upload and colour
   picker read these variables. So do the data display components: stat card,
   chart card, card link, CTA banner, feature grid, hero, data table, code,

data/the_local/agents/keystone_ui-install.md

@@ -83,9 +83,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
      the Stimulus application is set up and add those two lines there. Without
      them, dropdowns, modals, file uploads, the column picker, the theme toggle
      and the other interactive components do nothing.
-     `registerControllers(application)` also copies `data-theme` from each page
-     Turbo renders onto the `<html>` tag. Without it, a Turbo visit keeps the
-     theme of the first page loaded.
+     `registerControllers(application)` also copies `data-theme` and `data-look`
+     from each page Turbo renders onto the `<html>` tag. Without it, a Turbo
+     visit keeps the theme and look of the first page loaded.
    - `app/views/layouts/application.html.erb not found` — ask the developer which
      layout the app renders and add `<%= keystone_theme_attributes %>` to its
      `<html>` tag. Without it, a saved light or dark choice is not applied when
@@ -149,7 +149,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
    ```
 
    Buttons, panels, cards, alerts, badges, form fields, the modal, the mobile
-   action menu, the column picker, multi select, copy button, theme toggle,
+   action menu, the action menu, the column picker, multi select, copy button, theme toggle,
    checkbox row, radio card, option card, file upload and colour picker read
    these variables. So do the data display components: stat card, chart card,
    card link, CTA banner, feature grid, hero, data table, code, accordion,

data/the_local/interface.yml

@@ -36,6 +36,8 @@ develop:
   - ui_breadcrumbs
   - ui_mobile_header
   - ui_mobile_actions
+  - ui_action_menu
+  - ui_action_menu_item
   - ui_navbar
   - ui_nav_item
   - ui_nav_dropdown
@@ -88,6 +90,7 @@ sources:
   - app/components/keystone/ui/copy_button_component.rb
   - app/components/keystone/ui/cta_banner_component.rb
   - app/components/keystone/ui/data_table_component.rb
+  - app/components/keystone/ui/data_table_component.html.erb
   - app/components/keystone/ui/disclosure_component.rb
   - app/components/keystone/ui/calculation_component.rb
   - app/components/keystone/ui/feature_grid_component.rb
@@ -108,6 +111,8 @@ sources:
   - app/components/keystone/ui/input_component.rb
   - app/components/keystone/ui/line_chart_component.rb
   - app/components/keystone/ui/mobile_actions_component.rb
+  - app/components/keystone/ui/action_menu_component.rb
+  - app/components/keystone/ui/action_menu_item_component.rb
   - app/components/keystone/ui/mobile_header_component.rb
   - app/components/keystone/ui/modal_component.rb
   - app/components/keystone/ui/multi_select_component.rb
@@ -124,6 +129,7 @@ sources:
   - app/components/keystone/ui/progress_component.rb
   - app/components/keystone/ui/radio_card_component.rb
   - app/components/keystone/ui/section_component.rb
+  - app/components/keystone/ui/section_component.html.erb
   - app/components/keystone/ui/select_component.rb
   - app/components/keystone/ui/settings_link_component.rb
   - app/components/keystone/ui/show_page_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -73,6 +73,9 @@ files:
 - app/assets/tailwind/keystone_ui_engine/grid_safelist.css
 - app/components/keystone/ui/accordion_component.html.erb
 - app/components/keystone/ui/accordion_component.rb
+- app/components/keystone/ui/action_menu_component.html.erb
+- app/components/keystone/ui/action_menu_component.rb
+- app/components/keystone/ui/action_menu_item_component.rb
 - app/components/keystone/ui/alert_component.html.erb
 - app/components/keystone/ui/alert_component.rb
 - app/components/keystone/ui/badge_component.html.erb