katalyst-tables 3.5.1 → 3.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3814f29f662d5198c08b423d4f7ac76a07e327588f601fcc163adaa239f7b842
-  data.tar.gz: 24c1a6a392a570cd2338b1d3501a8d6a10c3f96f0d445aafb64b0fa541764e06
+  metadata.gz: 67d99ce2d2301f9752494026a850f959582c8526629c9958e6cc9a330097012a
+  data.tar.gz: 3a17c798586675a6ac31d737e0b15700217c37ce39d93d9bea4db1a88489ddf0
 SHA512:
-  metadata.gz: ec8aeebe3f1470b3cc1f0d15802cabf82365d91646b70ea9dabbbb1ad7fca2cde1d983014bbb84bdfd6af0ad3a0fd85305ae33e00de38ed789b105ce5f6b7aae
-  data.tar.gz: 7b630dde2814a741df30c2dac1c5e21ed23a6137a588413044172ba8b658287462fb7a860d961d8f489ad4be1fe4207b4aab203419bfc2c7ed65cfc6a1437965
+  metadata.gz: 67282005deb832f18264557f4bb0334fabc53594325af5503e5a5839c8759f95f75fdabddef0c5d627ea38f281068540c78811f693f9319477d1aba74bb65882
+  data.tar.gz: b1158053505b7c836c96f7b1e0bb0e65578e45bc7d8f16c7fc1708059e69712e7809e3bd0a7bcfebd7091531ebbe1713140d0ed35b8ec70e1c0c490915dd1295

data/README.md

@@ -1,267 +1,10 @@
-# Katalyst::Tables
+# Katalyst Tables
 
-Tools for building HTML tables from ActiveRecord collections.
+A library for viewing and interacting with database tables in Ruby on Rails.
 
-## Installation
+## Documentation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem "katalyst-tables" 
-```
-
-And then execute:
-
-    $ bundle install
-
-Add the Gem's javascript and CSS to your build pipeline. This assumes that
-you're using `rails-dartsass` and `importmaps` to manage your assets.
-
-```javascript
-// app/javascript/controllers/application.js
-import { application } from "controllers/application";
-import tables from "@katalyst/tables";
-application.load(tables);
-```
-
-```scss
-// app/assets/stylesheets/application.scss
-@use "@katalyst/tables";
-```
-
-## Usage
-
-This gem provides entry points for backend and frontend concerns:
-* `Katalyst::TableComponent` can be used render encapsulated tables,
-* `Katalyst::SummaryTableComponent` can be used render a record using the table syntax,
-* `Katalyst::Tables::Frontend` provides `table_with` for inline table generation,
-* `Katalyst::Tables::Collection::Base` provides a default entry point for
-  building collections in your controller actions
-* `Katalyst::Tables::Collection::Query` provides build-in query parsing and filtering
-  based on the attributes defined in your collection.
-
-### Frontend
-
-Add `include Katalyst::Tables::Frontend` to your `ApplicationHelper` or similar.
-
-You can use the `table_with` helper to generate a table inline in your view without explicitly interacting with the
-table component. This is the preferred approach when creating tables. However, if the table is complex or you need to 
-reuse it, you should consider moving the definition of the row into a partial.
-
-```erb
-<%= table_with collection: @people do |row, person| %>
-  <% row.text :name do |cell| %>
-    <%= link_to cell.value, [:edit, person] %>
-  <% end %>
-  <% row.text :email %>
-<% end %>
-```
-
-By not providing a block to the `table_with` call, the gem will look for a partial called `_person.html+row.erb` to
-render each row:
-
-```erb
-<%# locals: { row:, person: nil } %>
-<% row.text :name do |cell| %>
-  <%= link_to cell.value, [:edit, person] %>
-<% end %>
-<% row.text :email %>
-```
-
-The table will call your block / partial once per row and accumulate the cells
-you generate into rows, including a header row:
-
-```html
-
-<table>
-  <thead>
-  <tr>
-    <th>Name</th>
-    <th>Email</th>
-  </tr>
-  </thead>
-  <tbody>
-  <tr>
-    <td><a href="/people/1/edit">Alice</a></td>
-    <td>alice@acme.org</td>
-  </tr>
-  <tr>
-    <td><a href="/people/2/edit">Bob</a></td>
-    <td>bob@acme.org</td>
-  </tr>
-  </tbody>
-</table>
-```
-
-You can customize the partial and/or the name of the resource in a similar style
-to view partials:
-
-```erb
-<%= table_with(collection: @employees, as: :person, partial: "person") %>
-```
-
-### HTML Attributes
-
-You can add custom attributes on table, row, and cell tags.
-
-The table tag takes attributes passed to `table_with` helper, similar to `form_with`:
-
-```erb
-<%= table_with(collection: @people, id: "people-table")
-```
-
-Cells support the same approach:
-
-```erb
-<%= row.text :name, class: "name" %>
-```
-
-Rows do not get called directly, so instead you can assign to `html_attributes` on the row builder to customize row tag
-generation.
-
-```erb
-<% row.update_html_attributes(id: person.id) if row.body? %>
-```
-
-Note: because the row builder gets called to generate the header row, you may need to guard calls that access the
-`person` directly as shown in the previous example. You could also check whether `person` is present.
-
-### Headers
-
-Tables will automatically generate a header row for you by calling your row partial or provided block with no object.
-During this call, `row.header?` is true, `row.body?` is false, and the object (`person`) is nil.
-
-All cells generated in the table header iteration will automatically be header cells, but you can also make header cells
-in your body rows by passing `heading: true` when you generate the cell.
-
-```erb
-<% row.number :id, heading: true %>
-```
-
-The table header cells default to showing the capitalized column name, but you can customize this in one of two ways:
-
-* Set the value inline
-    ```erb
-    <% row.number :id, label: "ID" %>
-    ```
-* Define a translation for the attribute
-    ```yml
-    # en.yml
-    activerecord:
-      attributes:
-        person:
-          id: "ID"
-    ```
-  
-Note: if the cell is given a block, it is not called during the header pass. This
-is because the block is assumed to be for generating data for the body, not the
-header. We suggest you set `label` instead.
-
-#### Cell values
-
-If you do not provide a value when you call the cell builder, the attribute you
-provide will be retrieved from the current item and the result will be rendered in
-the table cell. This is often all you need to do, but if you do want to customise
-the value you can pass a block instead:
-
-```erb
-<% row.text :status do %>
-  <%= person.password.present? ? "Active" : "Invited" %>
-<% end %>
-```
-
-In the context of the block you have access the cell component if you simply
-want to extend the default behaviour:
-
-```erb
-<%# @type [Katalyst::Tables::CellComponent] cell %>
-<% row.text :name do |cell| %>
-  <%= link_to cell, person %>
-<% end %>
-```
-
-You can also update `html_attributes` on the cell builder, similar to the row
-builder, see `katalyst-html-attributes` for details.
-
-## Collections
-
-The `Katalyst::Tables::Collection::Base` class provides a convenient way to
-manage collections in your controller actions. It is designed to be used with
-Pagy for pagination and provides built-in sorting when used with ActiveRecord
-collections. Sorting and Pagination are off by default, you can either set them
-on creation or create a custom `Collection` class that sets them on by default:
-
-```ruby
-# in #index
-Katalyst::Tables::Collection::Base.new(sorting: "name asc", pagination: true)
-# or as a nested class in your controller
-class Collection < Katalyst::Tables::Collection::Base
-  config.sorting = "name asc" # requires models have a name attribute
-  config.pagination = true
-end
-```
-
-Collections can be passed directly to `table_with` method and it will automatically
-detect features such as sorting and generate the appropriate table header links.
-
-```erb
-<%= table_with(collection:) %>
-```
-
-### Query
-
-Include `Katalyst::Tables::Collection::Query` into your collection to add automatic
-query parsing and filtering based on the configured attributes. For example:
-
-```ruby
-class Collection < Katalyst::Tables::Collection::Base
-  include Katalyst::Tables::Collection::Query
-  
-  attribute :first_name, :string
-  attribute :created_at, :date
-end
-```
-
-With this definition and a text-input named `query`, your users can write tagged
-query expressions such as `first_name:Aaron` or `created_at:>2024-01-01` and these
-will be automatically parsed and applied to the collection attribute, and the collection
-will automatically generate and apply ActiveRecord conditions to filter the given scope.
-
-There's also a frontend utility, `table_query_with(collection:)` that will generate the form
-and show a modal that helps users to interact with the query interface. More details available
-in the [query](docs/query.md) documentation.
-
-## Summary tables
-You can use the `Katalyst::SummaryTableComponent` to render a single record utilizing all the functionality from the 
-`Katalyst::TableComponent`. 
-
-```erb
-<%= summary_table_with model: @person do |row| %>
-  <% row.text :name %>
-  <% row.text :email %>
-<% end %>
-```
-
-## Extensions
-
-The following extensions are available and activated by default:
-
-* [Filtering](docs/filtering.md) - adds automatic collection filtering based on attributes 
-* [Query](docs/query.md) - adds human-friendly text filtering that populates collection attributes 
-* [Identifiable](docs/identifiable.md) - adds default dom ids to the table and data rows.
-* [Orderable](docs/orderable.md) - adds bulk-update for 'ordinal' columns via dragging rows in the table.
-* [Pagination](docs/pagination.md) - handles paginating of data in the collection.
-* [Selectable](docs/selectable.md) - adds bulk-action support for rows in the table.
-* [Sortable](docs/sortable.md) - table column headers that can be sorted will be wrapped in links.
-* [Customization](docs/customization.md) - customize the table and cell rendering.
-
-You can disable extensions by altering the `Katalyst::Tables.config.component_extensions` before initialization.
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
-
-To install this gem onto your local machine, run `bundle exec rake install`.
+See [katalyst.github.io/tables](https://katalyst.github.io/tables/) for documentation.
 
 ## Contributing
 
@@ -269,4 +12,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/kataly
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Katalyst Tables is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/stylesheets/katalyst/tables/_query.scss

@@ -54,7 +54,6 @@
   box-shadow:
     0 3px 6px rgba(0, 0, 0, 0.16),
     0 3px 6px rgba(0, 0, 0, 0.23);
-  margin-top: 0.5rem;
   background: white;
   border-radius: 4px;
   z-index: 1;
@@ -77,7 +76,7 @@
   .content {
     grid-area: content;
     padding-inline: 1rem;
-    padding-block: 0.5rem 0;
+    padding-block: 0.5rem;
   }
 
   ul {
@@ -96,10 +95,13 @@
     }
   }
 
-  .footer {
+  footer {
     grid-area: footer;
     display: flex;
-    justify-content: flex-end;
-    padding-block: 1rem;
+    justify-content: flex-start;
+    padding-inline: 1rem;
+    padding-block: 0.5rem;
+    border-top: 1px solid #d3d3d3;
+    font-size: small;
   }
 }

data/app/components/katalyst/tables/pagy_nav_component.rb

@@ -7,7 +7,11 @@ module Katalyst
       # Expect to see NoMethodError failures if pagy is not available
       "Pagy::Frontend".safe_constantize&.tap { |pagy| include(pagy) }
 
-      attr_reader :pagy_options
+      def self.pagy_legacy?
+        Pagy::VERSION.scan(/\d+/).first.to_i <= 8
+      end
+
+      delegate :pagy_legacy?, to: :class
 
       def initialize(collection: nil, pagy: nil, **pagy_options)
         super()
@@ -24,9 +28,19 @@ module Katalyst
         pagy_nav(@pagy, **pagy_options).html_safe # rubocop:disable Rails/OutputSafety
       end
 
+      def pagy_options
+        default_pagy_options.merge(@pagy_options)
+      end
+
       def inspect
         "#<#{self.class.name} pagy: #{@pagy.inspect}>"
       end
+
+      private
+
+      def default_pagy_options
+        pagy_legacy? ? {} : { anchor_string: 'data-turbo-action="replace"' }
+      end
     end
   end
 end

data/app/components/katalyst/tables/query/modal_component.html.erb

@@ -16,9 +16,11 @@
       </ul>
     <% end %>
   </div>
-  <% if footer? %>
-    <footer>
+  <footer>
+    <% if footer? %>
       <%= footer %>
-    </footer>
-  <% end %>
+    <% else %>
+      <a href="https://katalyst.github.io/tables/users/queries" target="_blank">Search syntax</a>
+    <% end %>
+  </footer>
 <% end %>

data/app/controllers/concerns/katalyst/tables/backend.rb

@@ -8,6 +8,7 @@ module Katalyst
 
       included do
         class_attribute :_default_table_component, instance_accessor: false
+        class_attribute :_default_table_pagination_component, instance_accessor: false
         class_attribute :_default_table_query_component, instance_accessor: false
         class_attribute :_default_summary_table_component, instance_accessor: false
       end
@@ -21,6 +22,14 @@ module Katalyst
           self._default_table_component = component
         end
 
+        # Set the table pagination component to be used as the default for all tables
+        # in the views rendered by this controller and its subclasses.
+        #
+        # @param component [Class] the table pagination component class to use
+        def default_table_pagination_component(component)
+          self._default_table_pagination_component = component
+        end
+
         # Set the table query component to be used as the default for all tables
         # in the views rendered by this controller and its subclasses.
         #
@@ -44,6 +53,11 @@ module Katalyst
         self.class._default_table_component
       end
 
+      # Default table pagination component for this controller
+      def default_table_pagination_component
+        self.class._default_table_pagination_component
+      end
+
       # Default table query component for this controller
       def default_table_query_component
         self.class._default_table_query_component

data/app/helpers/katalyst/tables/frontend.rb

@@ -55,6 +55,14 @@ module Katalyst
         render(Selectable::FormComponent.new(collection:, id:, primary_key:), &)
       end
 
+      # Construct pagination navigation for the current page. Defaults to pagy_nav.
+      #
+      # @param collection [Katalyst::Tables::Collection::Core] the collection to render
+      def table_pagination_with(collection:, **)
+        component ||= default_table_pagination_component_class
+        render(component.new(collection:, **))
+      end
+
       # Construct a new query interface for filtering the current page.
       #
       # @param collection [Katalyst::Tables::Collection::Core] the collection to render
@@ -85,6 +93,11 @@ module Katalyst
         component.respond_to?(:constantize) ? component.constantize : component
       end
 
+      def default_table_pagination_component_class
+        component = controller.try(:default_table_pagination_component) || PagyNavComponent
+        component.respond_to?(:constantize) ? component.constantize : component
+      end
+
       def default_table_query_component_class
         component = controller.try(:default_table_query_component) || QueryComponent
         component.respond_to?(:constantize) ? component.constantize : component

data/app/models/concerns/katalyst/tables/collection/pagination.rb

@@ -37,12 +37,12 @@ module Katalyst
         def paginate_options
           opts = @paginate.is_a?(Hash) ? @paginate : {}
           opts = opts.dup
-          opts[:anchor_string] ||= anchor_string
-          opts
-        end
 
-        def anchor_string
-          "data-turbo-action=\"replace\""
+          if PagyNavComponent.pagy_legacy?
+            opts[:anchor_string] ||= "data-turbo-action=\"replace\""
+          end
+
+          opts
         end
 
         class Paginate # :nodoc:
@@ -57,7 +57,7 @@ module Katalyst
           def call(collection)
             @collection = @app.call(collection)
             if collection.paginate?
-              @collection.pagination, @collection.items = pagy(@collection.items, collection.paginate_options.dup)
+              @collection.pagination, @collection.items = pagy(@collection.items, **collection.paginate_options)
             end
             @collection
           end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: katalyst-tables
 version: !ruby/object:Gem::Version
-  version: 3.5.1
+  version: 3.5.3
 platform: ruby
 authors:
 - Katalyst Interactive
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-07-18 00:00:00.000000000 Z
+date: 2024-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: katalyst-html-attributes