layered-ui-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0596cb85b0ecaf7e9efe534a5d7b7ff9e9c3f0848d1faf8972ce7f1e4617fb1b'
-  data.tar.gz: f03e28644cd462bcf5988d851d4f85ad177761fd37eea52ed404a4046b230404
+  metadata.gz: 0f1a66524b7aad7bb6cca544c4936735e286f2a1a2bccf620a47bd08c3c6b3ef
+  data.tar.gz: 779bb09a82b63891245d917c25c40f82e2e1c505291c3967daf0f1db4a4cbb94
 SHA512:
-  metadata.gz: 72a5b12ad90bd8997f03e7f9624af1ef3cfeeffc25db54a147c435bde91bb6ed49c353bf049210ec122eae10297db94b96d1918c88131acb13fac1786171feca
-  data.tar.gz: 150ccf137e7e41cb2181444b11c73cb3bb583ae3e1160b3f87cc70ee019acf34c688af70e6a09ad04b5ff756a5e8f7f72fd4e9afedbb408a052ad6b81cde41ca
+  metadata.gz: cbac626bf832dc7599b37a4234aac65e1f8cbd1282d1c2bda20e9df3c97319ed468adde98af047affa463895d0bdcf433bd6512af4ceef59c843eba21caf443d
+  data.tar.gz: f62ab50c0825ee0b152fd48b1c508750cbe04bff880217aa0a7ffa4663d54db3ab285d08546fcdc52117cac2817c2e66196d3f8b96bfff4a6f584c0671e52508

data/.claude/skills/layered-ui-rails/SKILL.md

@@ -102,6 +102,9 @@ Quick reference:
 | `l_ui_pagy(pagy)` | Styled pagination (requires pagy gem) |
 | `l_ui_search_form(query, url:, fields:, ...)` | Search form (requires ransack gem) |
 | `l_ui_sort_link(query, attribute, label = nil, ...)` | Sortable table header (requires ransack gem) |
+| `l_ui_table(records, columns:, caption:, ...)` | Styled accessible data table with optional sort and actions |
+| `l_ui_form(record, fields:, url:, method:)` | Complete form with fields, error summary, and submit |
+| `l_ui_normalise_field(record, config)` | Normalise a raw field config hash into canonical form |
 | `l_ui_user_signed_in?` | Check if user is authenticated |
 | `l_ui_current_user` | Current user object |
 

data/.claude/skills/layered-ui-rails/references/CSS.md

@@ -13,17 +13,28 @@ All classes use the `l-ui-` prefix with BEM naming. Use these in host app views.
 
 ## Buttons
 
+Standalone variants (use one of these, not combined with each other):
+
 ```
-.l-ui-button                Base button with padding and focus ring
-.l-ui-button--primary       Accent-coloured button
-.l-ui-button--outline       Bordered button
-.l-ui-button--outline-danger  Red bordered button
-.l-ui-button--full          Full-width button
-.l-ui-button--icon          Icon-only button (fixed size, no text)
-.l-ui-button--disabled      Disabled appearance
+.l-ui-button                  Plain button with padding and focus ring
+.l-ui-button--primary         Accent-coloured solid button
+.l-ui-button--danger          Solid red button (for destructive actions)
+.l-ui-button--outline         Bordered button
+.l-ui-button--outline-danger  Red bordered button (for destructive actions)
+.l-ui-button--icon            Icon-only button (fixed size, no text)
 .l-ui-button--navigation-toggle  Mobile navigation toggle
-.l-ui-button--panel-close   Panel close button
+.l-ui-button--panel-close     Panel close button
+```
+
+Modifiers (combine with a standalone variant above):
+
 ```
+.l-ui-button--full            Full-width (e.g. l-ui-button--primary l-ui-button--full)
+```
+
+Any button variant is automatically styled as disabled when the `disabled` HTML attribute is present - no extra class needed.
+
+For destructive actions use `l-ui-button--danger` (solid) or `l-ui-button--outline-danger` (bordered).
 
 ## Surfaces
 
@@ -47,6 +58,7 @@ All classes use the `l-ui-` prefix with BEM naming. Use these in host app views.
 .l-ui-form__field            Input/textarea styling
 .l-ui-form__errors           Error summary box
 .l-ui-form__errors-list      Bulleted error list
+.l-ui-form__actions          Right-aligned action button container (full-width buttons on mobile)
 .l-ui-form__field-error      Individual field error message
 .l-ui-form__hint             Field hint text
 .l-ui-form__required         Required indicator (*)

data/.claude/skills/layered-ui-rails/references/HELPERS.md

@@ -120,6 +120,87 @@ Returns a `<th>` element with sort link and ARIA sort attributes.
 </table>
 ```
 
+## Table
+
+```ruby
+l_ui_table(records, columns:, caption: nil, actions: nil,
+           actions_label: "Actions", query: nil, url: nil, turbo_frame: nil)
+```
+
+- `records` (ActiveRecord::Relation or Array) - the collection to render
+- `columns` (Array<Hash>) - column definitions (see below)
+- `caption` (String, optional) - visually hidden table caption for accessibility
+- `actions` (Proc, optional) - receives (record), returns action cell content
+- `actions_label` (String) - header text for the actions column, default "Actions"
+- `query` (Ransack::Search, optional) - enables sortable column headers
+- `url` (String, optional) - sort link URL (passed to `l_ui_sort_link`)
+- `turbo_frame` (String, optional) - turbo frame target for sort links
+
+Column options:
+- `attribute` (Symbol) - used for label generation and sort links
+- `label` (String, optional) - custom header text; defaults to humanised attribute
+- `primary` (Boolean, optional) - renders as `<th scope="row">`; defaults to first column
+- `sortable` (Boolean, optional) - show sort link when `query:` is provided; defaults to true
+- `render` (Proc, required) - receives (record), returns cell content
+
+### `l_ui_format_datetime(value)`
+
+Formats a date/time value as `"%-d %b %Y, %H:%M"` (e.g. "15 Apr 2026, 10:30"). Returns `nil` for `nil` input. Useful inside `render:` procs for date columns.
+
+```erb
+<%= l_ui_table(@users,
+  columns: [
+    { attribute: :name, primary: true, render: ->(r) { link_to r.name, user_path(r) } },
+    { attribute: :email, render: ->(r) { r.email } },
+    { attribute: :created_at, label: "Joined", render: ->(r) { l_ui_format_datetime(r.created_at) } },
+  ],
+  actions: ->(r) { link_to "Edit", edit_user_path(r) },
+  caption: "Users",
+  query: @q,
+  turbo_frame: "users") %>
+```
+
+## Form
+
+```ruby
+l_ui_form(record, fields:, url:, method: nil)
+```
+
+- `record` (ActiveRecord) - the model instance
+- `fields` (Array<Hash>) - field definitions (see below)
+- `url` (String) - form action URL
+- `method` (Symbol, optional) - HTTP method override
+
+Renders a complete form with all fields, error summary, and submit button via the `layered/ui/managed_resource/form` partial.
+
+Field options:
+- `attribute` (Symbol) - model attribute
+- `as` (Symbol, optional) - field type; auto-detected from column type. Supported: `:string`, `:text`, `:email`, `:number`, `:date`, `:datetime`, `:select`, `:checkbox`, `:hidden`
+- `label` (String, optional) - custom label text; defaults to humanised attribute
+- `required` (Boolean, optional) - marks field as required; default false
+- `hint` (String, optional) - help text below the field
+- `collection` (Array, optional) - required for `:select` type; e.g. `[['Label', value], ...]`
+- `placeholder` (String, optional) - input placeholder text
+
+```erb
+<%= l_ui_form(@post,
+  fields: [
+    { attribute: :title, required: true },
+    { attribute: :body, as: :text },
+    { attribute: :category, as: :select, collection: Category.pluck(:name, :id) },
+    { attribute: :published, as: :checkbox },
+  ],
+  url: posts_path) %>
+```
+
+### Form utility helpers
+
+```ruby
+l_ui_normalise_field(record, config)  # Normalise a raw field config into canonical form
+l_ui_field_error_id(record, attribute)  # Error element ID for aria-describedby
+l_ui_field_hint_id(record, attribute)   # Hint element ID for aria-describedby
+```
+
 ## Authentication
 
 ```ruby

data/AGENTS.md

@@ -23,7 +23,7 @@ Guidance for AI agents working in this repository.
 - Use normal dashes '-' not long ones '—'
 - Locale: Favour en-GB (British English), unless terms are defined by technical standards (e.g. LICENSE, COLOR).
 - Titles: capitalise first word only (e.g. "This title")
-- Document new styles in the dummy app
+- Document new styles in the dummy app. When adding a new CSS class or helper, add a working example to the relevant dummy app documentation page (in `test/dummy/app/views/pages/`) following the existing style (heading, description paragraph, live example, "View code" modal). Update the relevant skill reference file in `.claude/skills/layered-ui-rails/references/` to include the new class or helper.
 - Use l-ui classes only in engine views, with no additional Tailwind utilities, as Tailwind classes referenced only inside the engine will not be generated by the host app’s build
 - Dummy app documentation pages may use additional Tailwind utilities, but should favour l-ui classes where possible
 - Importmap for JS (no bundler)

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-04-19
+
+### Added
+
+- `l-ui-form__actions` CSS class for right-aligned form action buttons that stack full-width on mobile
+- `l_ui_format_datetime` helper for consistent date/time formatting in table cells
+
+### Changed
+
+- Collapsible surface padding moved from container to summary/content elements for better open/closed spacing
+- `.l-ui-surface__summary` now prevents text selection with `select-none`
+- Markdown `pre` background changed from `bg-surface-active` to `bg-surface`
+- `l-ui-button--danger` is now a standalone variant (no longer requires a base button class)
+- `l_ui_table` now requires a `render:` proc on every column - the helper no longer auto-extracts values via `public_send`/hash access or auto-formats dates
+- `l_ui_table` no longer renders with an implicit top margin - wrap in a utility class if spacing is needed
+- `l_ui_form` submit button now uses `l-ui-form__actions` wrapper for right-aligned, mobile-responsive layout
+- `l-ui-form` no longer renders with an implicit top margin - wrap in a utility class if spacing is needed
+- Disabled button styling is now automatic via the `disabled` HTML attribute on any button variant - no extra class needed
+
+### Removed
+
+- `l-ui-button--disabled` modifier class - use the `disabled` HTML attribute instead
+
 ## [0.4.0] - 2026-04-14
 
 ### Added

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

@@ -352,7 +352,7 @@
 
 .l-ui-markdown pre {
   @apply my-3 p-3
-         bg-surface-active
+         bg-surface
          rounded-md
          overflow-x-auto;
 }
@@ -750,6 +750,12 @@
          text-foreground;
 }
 
+.l-ui-button--danger {
+  @apply button
+         bg-danger
+         text-white;
+}
+
 .l-ui-button--outline-danger {
   @apply button
          border border-danger
@@ -780,7 +786,8 @@
          transition-colors;
 }
 
-.l-ui-button--disabled {
+[class*="l-ui-button--"]:disabled,
+.l-ui-button:disabled {
   @apply opacity-50
          cursor-not-allowed;
 }
@@ -854,11 +861,13 @@ pre.l-ui-surface {
 
 .l-ui-surface--collapsible {
   @apply surface
+         p-0
          bg-surface;
 }
 
 .l-ui-surface--collapsible-active {
   @apply surface
+         p-0
          bg-surface-active;
 }
 
@@ -867,24 +876,30 @@ pre.l-ui-surface {
   &[open] > .l-ui-surface__summary .l-ui-surface__chevron {
     @apply rotate-90;
   }
+
+  &.l-ui-surface--sm {
+    @apply p-0;
+  }
 }
 
 .l-ui-surface--sm {
   @apply p-3;
 
   .l-ui-surface__summary {
-    @apply text-sm font-semibold;
+    @apply p-3
+           text-sm font-semibold;
   }
 
   .l-ui-surface__content {
-    @apply pt-3;
+    @apply px-3 pb-3;
   }
 }
 
 .l-ui-surface__summary {
   @apply flex items-center justify-between
+         p-4
          font-bold
-         list-none cursor-pointer focus-ring;
+         list-none cursor-pointer select-none focus-ring;
 
   &::-webkit-details-marker {
     display: none;
@@ -896,13 +911,13 @@ pre.l-ui-surface {
 }
 
 .l-ui-surface__content {
-  @apply pt-4;
+  @apply px-4 pb-4;
 }
 
 /* Form */
 
 .l-ui-form {
-  @apply w-full mt-4;
+  @apply w-full;
 }
 
 .l-ui-form__errors-list {
@@ -916,6 +931,15 @@ pre.l-ui-surface {
   @apply mt-4;
 }
 
+.l-ui-form__actions {
+  @apply flex flex-col gap-2 justify-end
+         mt-8;
+
+  @media (min-width: 768px) {
+    @apply flex-row;
+  }
+}
+
 .l-ui-form__group--large-gap {
   @apply mt-8;
 }

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

@@ -1,11 +1,19 @@
 module Layered
   module Ui
     module TableHelper
+      # Formats a date/time value for display in a table cell.
+      #
+      #   l_ui_format_datetime(record.created_at) # => "15 Apr 2026, 10:30"
+      def l_ui_format_datetime(value)
+        value&.strftime("%-d %b %Y, %H:%M")
+      end
+
       # Renders a styled, accessible data table.
       #
       # Use this helper in any view to render a table with the engine's
-      # +l-ui-table+ styles. It supports custom cell rendering via procs,
-      # an optional actions column, and Ransack sort links.
+      # +l-ui-table+ styles. Every column must supply a +render:+ proc
+      # that receives a record and returns cell content - the helper does
+      # not extract or format data itself.
       #
       #   l_ui_table(@personas,
       #     columns: [
@@ -17,15 +25,11 @@ module Layered
       #   )
       #
       # Column options:
-      #   attribute: (Symbol)  Model attribute for data and label generation.
+      #   attribute: (Symbol)  Used for label generation and sort links.
       #   label:     (String)  Custom header text. Defaults to humanised attribute.
       #   primary:   (Boolean) Renders as <th scope="row">. Defaults to first column.
       #   sortable:  (Boolean) Show sort link when query: is provided. Defaults to true.
-      #   render:    (Proc)    Receives (record), returns cell content.
-      #
-      # When no +render:+ proc is given, the cell value is extracted via
-      # +record[attribute]+ for hashes or +record.public_send(attribute)+
-      # for objects, with automatic date formatting.
+      #   render:    (Proc)    Required. Receives (record), returns cell content.
       #
       # Pass +query:+ (a Ransack search object) and +turbo_frame:+ to enable
       # sortable column headers via +l_ui_sort_link+.
@@ -67,7 +71,7 @@ module Layered
 
         caption_tag = caption ? tag.caption(caption, class: "l-ui-sr-only") : nil
         table = tag.table(class: "l-ui-table") { safe_join([caption_tag, thead, tbody].compact) }
-        tag.div(table, class: "l-ui-container--table l-ui-utility--mt-lg")
+        tag.div(table, class: "l-ui-container--table")
       end
 
       private
@@ -75,6 +79,12 @@ module Layered
       def normalise_table_columns(columns)
         has_primary = columns.any? { |c| c[:primary] }
         columns.each_with_index.map do |col, i|
+          unless col[:render]
+            raise ArgumentError,
+                  "Column #{col[:attribute].inspect} is missing a :render proc. " \
+                  "Every column must supply render: ->(record) { ... }"
+          end
+
           {
             attribute: col[:attribute],
             label: col[:label] || col[:attribute].to_s.humanize,
@@ -86,12 +96,7 @@ module Layered
       end
 
       def table_cell(record, col)
-        if col[:render]
-          value = col[:render].call(record)
-        else
-          raw = record.is_a?(Hash) ? record[col[:attribute]] : record.public_send(col[:attribute])
-          value = raw.respond_to?(:strftime) ? raw.strftime("%-d %b %Y %H:%M") : raw
-        end
+        value = col[:render].call(record)
 
         if col[:primary]
           tag.th(value, class: "l-ui-table__cell--primary", scope: "row")

data/app/views/devise/confirmations/new.html.erb

@@ -2,7 +2,7 @@
   <div class="l-ui-page--width-constrained">
     <h1>Resend confirmation instructions</h1>
 
-    <%= form_with(model: resource, as: resource_name, url: confirmation_path(resource_name), method: :post, class: 'l-ui-form') do |f| %>
+    <%= form_with(model: resource, as: resource_name, url: confirmation_path(resource_name), method: :post, class: 'l-ui-form l-ui-utility--mt-md') do |f| %>
       <%= render 'layered_ui/shared/form_errors', item: resource %>
 
       <div class="l-ui-form__group">

data/app/views/devise/passwords/edit.html.erb

@@ -2,7 +2,7 @@
   <div class="l-ui-page--width-constrained">
     <h1>Change your password</h1>
 
-    <%= form_with(model: resource, as: resource_name, url: password_path(resource_name), method: :put, class: 'l-ui-form') do |f| %>
+    <%= form_with(model: resource, as: resource_name, url: password_path(resource_name), method: :put, class: 'l-ui-form l-ui-utility--mt-md') do |f| %>
       <%= render 'layered_ui/shared/form_errors', item: resource %>
       <%= f.hidden_field :reset_password_token %>
 

data/app/views/devise/passwords/new.html.erb

@@ -2,7 +2,7 @@
   <div class="l-ui-page--width-constrained">
     <h1>Forgot your password?</h1>
 
-    <%= form_with(model: resource, as: resource_name, url: password_path(resource_name), method: :post, class: 'l-ui-form') do |f| %>
+    <%= form_with(model: resource, as: resource_name, url: password_path(resource_name), method: :post, class: 'l-ui-form l-ui-utility--mt-md') do |f| %>
       <%= render 'layered_ui/shared/form_errors', item: resource %>
 
       <div class="l-ui-form__group">

data/app/views/devise/registrations/new.html.erb

@@ -2,7 +2,7 @@
   <div class="l-ui-page--width-constrained">
     <h1>Register</h1>
 
-    <%= form_with(model: resource, as: resource_name, url: registration_path(resource_name), class: 'l-ui-form') do |f| %>
+    <%= form_with(model: resource, as: resource_name, url: registration_path(resource_name), class: 'l-ui-form l-ui-utility--mt-md') do |f| %>
       <%= render 'layered_ui/shared/form_errors', item: resource %>
 
       <% if resource.class.column_names.include?('name') %>

data/app/views/devise/sessions/new.html.erb

@@ -2,7 +2,7 @@
   <div class="l-ui-page--width-constrained">
     <h1>Login</h1>
 
-    <%= form_with(model: resource, as: resource_name, url: session_path(resource_name), class: 'l-ui-form') do |f| %>
+    <%= form_with(model: resource, as: resource_name, url: session_path(resource_name), class: 'l-ui-form l-ui-utility--mt-md') do |f| %>
       <%= render 'layered_ui/shared/form_errors', item: resource %>
 
       <div class="l-ui-form__group">

data/app/views/devise/unlocks/new.html.erb

@@ -2,7 +2,7 @@
   <div class="l-ui-page--width-constrained">
     <h1>Resend unlock instructions</h1>
 
-    <%= form_with(model: resource, as: resource_name, url: unlock_path(resource_name), method: :post, class: 'l-ui-form') do |f| %>
+    <%= form_with(model: resource, as: resource_name, url: unlock_path(resource_name), method: :post, class: 'l-ui-form l-ui-utility--mt-md') do |f| %>
       <%= render 'layered_ui/shared/form_errors', item: resource %>
 
       <div class="l-ui-form__group">

data/app/views/layered/ui/managed_resource/_form.html.erb

@@ -9,7 +9,7 @@
     <%= render "layered/ui/managed_resource/field", form: f, record: record, config: config %>
   <% end %>
 
-  <div class="l-ui-form__group">
+  <div class="l-ui-form__actions">
     <%= f.submit(record.new_record? ? "Create" : "Save changes",
                  class: "l-ui-button l-ui-button--primary") %>
   </div>

data/lib/layered/ui/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - layered.ai