layered-ui-rails 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feb436fe39471f18e20438f335008dbd35eefa5035e7dc4c43b25bb410ad2dff
-  data.tar.gz: eff67adfb3a419be2b85077a00a17ac44c50edc7448f7190deff342002f41ed4
+  metadata.gz: a8e4d9560a90e896fb66753e342a555c9ce281764e2c3c7ac9d326a4a52d5ff4
+  data.tar.gz: 3c1f55587df50d2f0def13536b0adb3c8869682246932fd73ddcd146a63a4e38
 SHA512:
-  metadata.gz: 69a5f98979872031872c93c9b2ff93060955810be38785ab882e275a5f07524834b97bde9a1907877450861f540e9a7dfa56b3d43e1282dfb0f7682c60f157a4
-  data.tar.gz: e857eb7b2476475e535e27c0902b2549ebf9cd28a4232b1dc39630827f3e9ace63d9e8e540477e632eda99a923c03265f97bd4f6dbd93b479c04f07d60cadc86
+  metadata.gz: 99a8dff88d32df2645427d4802d64294744cfc51d185e3b7df7b1fbf25db5887472b654293c6ce3af78440be2730a809c73f37bf282e6166d47b39ec80e85530
+  data.tar.gz: 13f9cc999716982874cfc3a6eaff48e63a5c7a06b608e321692de90d573c74e2879229dec97bd6250f3afb5b4bdfd222fef6150643b92e7f38d77b2b28fb85f3

data/AGENTS.md

@@ -2,10 +2,6 @@
 
 Guidance for AI agents working in this repository.
 
-## Project
-
-**layered-ui-rails** - Rails 8+ engine gem: design tokens, Tailwind CSS, Stimulus controllers (theme, mobile nav, panel, modal, tabs). Pure frontend, no server-side logic.
-
 ## Architecture
 
 - **Entry:** `require "layered-ui-rails"` → `lib/layered/ui.rb` → `lib/layered/ui/engine.rb`

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-04-11
+
+### Added
+
+- Optional Ransack search helper (`l_ui_search_form`) with styled search form wrapping Ransack's `search_form_for`
+- Sort link helper (`l_ui_sort_link`) with styled header cells wrapping Ransack's `sort_link`
+- Stimulus controller (`l-ui--search-form`) for clear button and Turbo Frame targeting
+- Support for multiple independent Ransack collections on a single page using Turbo Frames and `search_key`
+- Graceful degradation when Ransack is not installed (visible warning in development, silent fallback in production)
+- Ransack integration documentation and search helper API reference pages in the dummy app
+
+### Changed
+
+- Updated gem description and summary to clarify that the engine is built on Tailwind CSS and integrates with Devise, Pagy, and Ransack
+
 ## [0.2.5] - 2026-04-09
 
 ### Changed

data/app/assets/tailwind/layered/ui/styles.css

@@ -943,6 +943,17 @@ pre.l-ui-surface {
          rounded-sm;
 }
 
+/* Search */
+
+.l-ui-search__inline {
+  @apply flex items-center
+         gap-2;
+
+  .l-ui-form__field {
+    @apply mt-0;
+  }
+}
+
 /* Switch */
 
 .l-ui-switch {
@@ -1113,6 +1124,16 @@ pre.l-ui-surface {
          text-right;
 }
 
+.l-ui-table__sort-link {
+  @apply inline-flex items-center gap-1
+         no-underline
+         text-foreground;
+}
+
+.l-ui-table__sort-indicator {
+  @apply text-foreground-muted;
+}
+
 .l-ui-table__body {
   @apply h-full
          bg-background

data/app/helpers/layered/ui/ransack_helper.rb

@@ -0,0 +1,137 @@
+module Layered
+  module Ui
+    module RansackHelper
+      # Renders a styled Ransack search form.
+      #
+      # Simple usage (single input searching across fields):
+      #   l_ui_search_form(@q, url: users_path, fields: [:name, :email])
+      #
+      # Custom usage (full control via block):
+      #   l_ui_search_form(@q, url: users_path) do |f|
+      #     render "layered_ui/shared/search_field", form: f, field: :name_cont, label: "Name"
+      #     f.submit "Go", class: "l-ui-button--primary"
+      #   end
+      def l_ui_search_form(query, url: nil, fields: [], predicate: :cont, combinator: :or, label: "Search", placeholder: nil, button: "Search", clear: nil, turbo_frame: nil, html: {}, &block)
+        result = require_ransack("l_ui_search_form") { |msg| tag.p(msg, class: "l-ui-notice--warning") }
+        return result unless result == true
+
+        scope = query.context&.search_key || :q
+        turbo_action = "advance"
+        html = html.merge(class: ["l-ui-form", html[:class]].compact.join(" "))
+
+        if turbo_frame
+          existing_data = (html[:data] || {}).symbolize_keys
+          existing_controller = existing_data[:controller]
+          controller = [existing_controller, "l-ui--search-form"].compact.join(" ")
+          existing_action = existing_data[:action]
+          action = [existing_action, "submit->l-ui--search-form#preserve"].compact.join(" ")
+          turbo_action = existing_data[:turbo_action] || turbo_action
+
+          html[:data] = existing_data.except(:controller, :action, :l_ui__search_form_scope_value).merge(
+            turbo_frame: turbo_frame, turbo_action: turbo_action,
+            controller: controller, action: action,
+            l_ui__search_form_scope_value: scope
+          )
+        end
+
+        if block
+          search_form_for(query, url: url, html: html, as: scope, &block)
+        else
+          raise ArgumentError, "l_ui_search_form requires at least one field in simple mode (e.g. fields: [:name])" if fields.empty?
+
+          combined_field = fields.map(&:to_s).join("_#{combinator}_") + "_#{predicate}"
+          placeholder ||= "Search by #{fields.map { |f| f.to_s.humanize.downcase }.join(', ')}"
+
+          search_form_for(query, url: url, html: html, as: scope) do |f|
+            f.label(combined_field, label, class: "l-ui-sr-only") +
+              tag.div(class: "l-ui-search__inline") do
+                content = f.text_field(combined_field, class: "l-ui-form__field", placeholder: placeholder) +
+                  f.submit(button, class: "l-ui-button--primary")
+                if clear
+                  raise ArgumentError, "l_ui_search_form requires an explicit url: when clear: is set" unless url
+                  clear_options = { class: "l-ui-button--outline" }
+                  clear_options[:data] = { turbo_frame: turbo_frame, turbo_action: turbo_action, action: "click->l-ui--search-form#clear" } if turbo_frame
+                  content += link_to(clear == true ? "Clear" : clear, url, **clear_options)
+                end
+                content
+              end
+          end
+        end
+      end
+
+      SORT_INDICATORS = {
+        "asc"  => { symbol: "▲", label: ", sorted ascending",  aria: "ascending" },
+        "desc" => { symbol: "▼", label: ", sorted descending", aria: "descending" }
+      }.freeze
+
+      # Renders a styled, accessible Ransack sort header cell.
+      #
+      # Returns a +<th>+ element containing a sort link and an accessible sort
+      # direction indicator. The +aria-sort+ attribute is set on the +<th>+
+      # so screen readers announce the current sort state.
+      #
+      # Usage:
+      #   l_ui_sort_link(@q, :name)
+      #   l_ui_sort_link(@q, :name, "Full name")
+      #   l_ui_sort_link(@q, :created_at, "Joined", default_order: :desc)
+      #   l_ui_sort_link(@q, :name, html: { data: { turbo_action: "replace" } })
+      def l_ui_sort_link(query, attribute, label = nil, default_order: nil, turbo_frame: nil, html: {})
+        label ||= attribute.to_s.humanize
+        link_class = ["l-ui-table__sort-link", html[:class]].compact.join(" ")
+
+        result = require_ransack("l_ui_sort_link") { |msg| tag.th(tag.span(label, title: msg), class: "l-ui-table__header-cell", scope: "col") }
+        return (result || tag.th(label, class: "l-ui-table__header-cell", scope: "col")) unless result == true
+
+        current_dir = sort_direction_for(query, attribute)
+        indicator = SORT_INDICATORS[current_dir]
+        aria_sort = indicator&.dig(:aria) || "none"
+
+        url = sort_url(query, attribute, { default_order: default_order }.compact)
+        link_html = html.except(:class)
+        if turbo_frame
+          existing_data = (link_html[:data] || {}).symbolize_keys
+          link_html[:data] = existing_data.merge(turbo_frame: turbo_frame, turbo_action: existing_data[:turbo_action] || "advance")
+        end
+        link = link_to(url, **link_html, class: link_class) do
+          parts = [label]
+          if indicator
+            parts << tag.span(indicator[:symbol], aria: { hidden: true }, class: "l-ui-table__sort-indicator")
+            parts << tag.span(indicator[:label], class: "l-ui-sr-only")
+          end
+          safe_join(parts)
+        end
+
+        tag.th(link, class: "l-ui-table__header-cell l-ui-table__header-cell--sortable",
+               scope: "col", aria: { sort: aria_sort })
+      end
+
+      private
+
+      def ransack_available?
+        defined?(Ransack)
+      end
+
+      # Returns +true+ if Ransack is available. In development, returns the
+      # block's result so the caller can render a visible fallback. In
+      # production/test, logs and returns +nil+.
+      def require_ransack(helper_name)
+        return true if ransack_available?
+
+        message = "#{helper_name} requires the ransack gem. Add `gem \"ransack\"` to your Gemfile."
+
+        if Rails.env.development?
+          return yield(message)
+        end
+
+        Rails.logger.warn("[layered-ui-rails] #{message} The output has been hidden.")
+        nil
+      end
+
+      def sort_direction_for(query, attribute)
+        return unless query.respond_to?(:sorts)
+        sort = query.sorts.detect { |s| s.name == attribute.to_s }
+        sort&.dir
+      end
+    end
+  end
+end

data/app/javascript/layered_ui/controllers/l_ui/search_form_controller.js

@@ -0,0 +1,47 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Preserves query params from other search scopes when a scoped form submits
+// or its clear link is clicked.
+//
+// When multiple Ransack collections share one page, each form only knows about
+// its own fields. This controller reads the current URL at submit time and
+// injects hidden inputs for params that belong to other scopes, so the
+// resulting URL reflects the full state of all collections. The clear action
+// rewrites the clear link's href to include the same preserved params.
+export default class extends Controller {
+  static values = { scope: String }
+
+  preserve(event) {
+    this.element.querySelectorAll("[data-l-ui-preserved]").forEach(el => el.remove())
+
+    for (const [key, value] of this.#otherParams()) {
+      const input = document.createElement("input")
+      input.type = "hidden"
+      input.name = key
+      input.value = value
+      input.setAttribute("data-l-ui-preserved", "")
+      this.element.appendChild(input)
+    }
+  }
+
+  clear(event) {
+    const link = event.currentTarget
+    const preserved = this.#otherParams()
+    const base = link.href.split("?")[0]
+    const qs = preserved.toString()
+    link.href = qs ? `${base}?${qs}` : base
+  }
+
+  #otherParams() {
+    const currentParams = new URLSearchParams(window.location.search)
+    const scope = this.scopeValue
+    const result = new URLSearchParams()
+
+    for (const [key, value] of currentParams) {
+      if (key === scope || key.startsWith(scope + "[") || key === "commit") continue
+      result.append(key, value)
+    }
+
+    return result
+  }
+}

data/app/javascript/layered_ui/index.js

@@ -5,8 +5,10 @@ import PanelController from "layered_ui/controllers/l_ui/panel_controller"
 import PanelResizeController from "layered_ui/controllers/l_ui/panel_resize_controller"
 import PanelButtonController from "layered_ui/controllers/l_ui/panel_button_controller"
 import ModalController from "layered_ui/controllers/l_ui/modal_controller"
+import SearchFormController from "layered_ui/controllers/l_ui/search_form_controller"
 import TabsController from "layered_ui/controllers/l_ui/tabs_controller"
 
+application.register("l-ui--search-form", SearchFormController)
 application.register("l-ui--theme", ThemeController)
 application.register("l-ui--navigation", NavigationController)
 application.register("l-ui--panel", PanelController)

data/app/views/layered_ui/shared/_search_field.html.erb

@@ -0,0 +1,6 @@
+<% placeholder = local_assigns.fetch(:placeholder, nil) %>
+
+<div class="l-ui-form__group">
+  <%= form.label field, label, class: "l-ui-label" %>
+  <%= form.text_field field, class: "l-ui-form__field", **(placeholder ? { placeholder: placeholder } : {}) %>
+</div>

data/app/views/layered_ui/shared/_search_select.html.erb

@@ -0,0 +1,8 @@
+<% include_blank = local_assigns.fetch(:include_blank, "Any") %>
+
+<div class="l-ui-form__group">
+  <%= form.label field, label, class: "l-ui-label" %>
+  <div class="l-ui-select-wrapper">
+    <%= form.select field, options, { include_blank: include_blank }, class: "l-ui-select" %>
+  </div>
+</div>

data/config/importmap.rb

@@ -11,5 +11,6 @@ pin "layered_ui/controllers/l_ui/navigation_controller", to: "layered_ui/control
 pin "layered_ui/controllers/l_ui/panel_controller", to: "layered_ui/controllers/l_ui/panel_controller.js"
 pin "layered_ui/controllers/l_ui/panel_resize_controller", to: "layered_ui/controllers/l_ui/panel_resize_controller.js"
 pin "layered_ui/controllers/l_ui/panel_button_controller", to: "layered_ui/controllers/l_ui/panel_button_controller.js"
+pin "layered_ui/controllers/l_ui/search_form_controller", to: "layered_ui/controllers/l_ui/search_form_controller.js"
 pin "layered_ui/controllers/l_ui/tabs_controller", to: "layered_ui/controllers/l_ui/tabs_controller.js"
 pin "layered_ui/controllers/l_ui/theme_controller", to: "layered_ui/controllers/l_ui/theme_controller.js"

data/lib/layered/ui/engine.rb

@@ -29,6 +29,7 @@ module Layered
           helper Layered::Ui::AuthenticationHelper
           helper Layered::Ui::NavigationHelper
           helper Layered::Ui::PaginationHelper
+          helper Layered::Ui::RansackHelper
         end
       end
 

data/lib/layered/ui/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.2.5"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - layered.ai
@@ -107,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: ransack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -149,9 +163,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: An open source Rails 8+ engine that provides WCAG 2.2 AA compliant design
-  tokens, Tailwind CSS utilities, and Stimulus controllers for theme switching, mobile
-  navigation, slide-out panels, modals, and tabs.
+description: An open source Rails 8+ engine built on Tailwind CSS, providing customisable
+  WCAG 2.2 AA compliant design tokens, utility classes, and Stimulus controllers for
+  theme switching, mobile navigation, slide-out panels, modals, and tabs. Integrates
+  with the gems you already use (Devise, Pagy, Ransack).
 email:
 - support@layered.ai
 executables: []
@@ -192,11 +207,13 @@ files:
 - app/helpers/layered/ui/authentication_helper.rb
 - app/helpers/layered/ui/navigation_helper.rb
 - app/helpers/layered/ui/pagination_helper.rb
+- app/helpers/layered/ui/ransack_helper.rb
 - app/javascript/layered_ui/controllers/l_ui/modal_controller.js
 - app/javascript/layered_ui/controllers/l_ui/navigation_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_button_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_resize_controller.js
+- app/javascript/layered_ui/controllers/l_ui/search_form_controller.js
 - app/javascript/layered_ui/controllers/l_ui/tabs_controller.js
 - app/javascript/layered_ui/controllers/l_ui/theme_controller.js
 - app/javascript/layered_ui/index.js
@@ -218,6 +235,8 @@ files:
 - app/views/layered_ui/shared/_field_error.html.erb
 - app/views/layered_ui/shared/_form_errors.html.erb
 - app/views/layered_ui/shared/_label.html.erb
+- app/views/layered_ui/shared/_search_field.html.erb
+- app/views/layered_ui/shared/_search_select.html.erb
 - app/views/layouts/layered_ui/_header.html.erb
 - app/views/layouts/layered_ui/_navigation.html.erb
 - app/views/layouts/layered_ui/_notice.html.erb
@@ -272,6 +291,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Open source, minimalist, responsive, accessible UI system with light and
-  dark theme support.
+summary: Open source, minimalist Tailwind-based UI system for Rails with responsive,
+  accessible components and light/dark themes.
 test_files: []