layered-ui-rails 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 272ff1df79793bfe6c59ed6b4ea2ae12a82e8a7b51b5efcc770987b7387ca2c0
-  data.tar.gz: 21bf4840c729bf7d56cbb0971ab49f45fc24d301166f046c31c1164deeea0c56
+  metadata.gz: a8e4d9560a90e896fb66753e342a555c9ce281764e2c3c7ac9d326a4a52d5ff4
+  data.tar.gz: 3c1f55587df50d2f0def13536b0adb3c8869682246932fd73ddcd146a63a4e38
 SHA512:
-  metadata.gz: 2bba00f8ff4ff4e0b65b96c95ed438325ff50f93bd14c3f81d6274616d921cf196a0350c8780b85866609a4de090f51ba1434e0ee204d68fcb52b230edf72ab3
-  data.tar.gz: e31d63c421a1d3faa076c76f6a15b09f9465e2456fa9d04a024496e3e83790eb18e192193ec54842655382c81989789d36773dda3aa657f3cb27e23962653f07
+  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,7 +2,27 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
-## Unreleased
+## [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
+
+- Reduced form field text size from `text-base` (16px) to `text-sm` (14px) on desktop; remains 16px on mobile to prevent iOS auto-zoom
+- Increased form hint text size from `text-xs` (12px) to `text-sm` (14px)
 
 ## [0.2.4] - 2026-04-06
 

data/README.md

@@ -106,7 +106,7 @@ For dynamic theming (e.g. per-tenant branding), use `content_for :l_ui_head` to
 > <% end %>
 > ```
 
-See the [Colors documentation](https://layered-ui-rails.layered.ai/pages/layout_colors) for the full list of tokens.
+See the [Colors documentation](https://layered-ui-rails.layered.ai/layout_colors) for the full list of tokens.
 
 ## Customising logos and icons
 
@@ -186,6 +186,8 @@ kamal deploy
 
 This project is still in its early days. We welcome issues, feedback, and ideas - they genuinely help shape the direction of the project. That said, we're holding off on accepting pull requests until after the 1.0 release so we can stay focused on getting the core foundations right. Once we're there, we'd love to open things up to broader contributions. Thanks for your patience and interest!
 
+- [CLA.md](CLA.md) - contributor license agreement
+
 ## License
 
 Released under the [Apache 2.0 License](LICENSE).
@@ -196,6 +198,3 @@ Copyright 2026 LAYERED AI LIMITED (UK company number: 17056830). See [NOTICE](NO
 
 The source code is fully open, but the layered.ai name, logo, and brand assets are trademarks of LAYERED AI LIMITED. The Apache 2.0 license does not grant rights to use the layered.ai branding. Forks and redistributions must use a distinct name. See [TRADEMARK.md](TRADEMARK.md) for the full policy.
 
-## Contributing
-
-- [CLA.md](CLA.md) - contributor license agreement

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

@@ -901,16 +901,21 @@ pre.l-ui-surface {
 
 .l-ui-form__hint {
   @apply mt-2
-         text-xs text-foreground-muted;
+         text-sm text-foreground-muted;
 }
 
 @utility form__field {
   @apply block
          w-full px-3 py-2.5 min-h-[44px]
+         /* text-base at mobile; text-sm at md+ */
          text-base font-inter
          text-foreground
          border border-border-control rounded-sm
          focus-ring;
+
+  @media (min-width: 768px) {
+    @apply text-sm;
+  }
 }
 
 .l-ui-form__field {
@@ -938,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 {
@@ -1108,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.4"
+    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.4
+  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: []