turbo-scroll 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23360c1f88090467e027eea7b95d0e26124eaf84a88a6b61d92ff4383e5c7547
-  data.tar.gz: 1c530abf7d4c18357db082d3c537ccc11304d9a25b18a38566b9df52762f67c1
+  metadata.gz: e965fd74ecaa27efa5443fd7c585381a5e10a03c1b30ae5ab3ded35bd658ccdc
+  data.tar.gz: 991df0ca43b6e75535a7994b51fc68b01773e1d420bda91cf847f65a8f88213f
 SHA512:
-  metadata.gz: 5655f6dfb6f34dd1811713562de9c19bf0af16acdd3a2e10d1652e9eea90d42f2bc5139eacabf130a91fa06ff7e4a577408c4739426e7059d200deb3494946bb
-  data.tar.gz: da875aded8920791a105d033078d89c394acc08fb5fc056049256cb3707fd3fc0cd1d9849cb8e09136da2640c7262b1bc2d675384e5731c9d5e0f71f152ced50
+  metadata.gz: e8e69ff2b35a7f55edbd879cad95f5ed25a73b0d0a173bc5e18de0e8e6979dc8aaa834acc2e971799fac4a41bbedc072fa6ee9ab05411a2cbb963bb3e2266de4
+  data.tar.gz: 43a7739af26ba8aa9ed34661150906186be692447723b0b7462ef43144a70cc8cad2e6f2af92936f17bcf8c239801dcd3f32e01787f3b1f3854c0446459a90db

data/README.md

@@ -1,8 +1,21 @@
+[![Gem Version](https://badge.fury.io/rb/turbo-scroll.svg)](https://badge.fury.io/rb/turbo-scroll)
+
 # TurboScroll
 
 TurboScroll is a minimalistic gem that provides infinite scrolling for Rails based applications
 using Turbo.
 
+Why a new gem? Leveraging Turbo we can build a very small and efficient implementation
+for infinite page scrolling without extra dependencies.
+
+It's made to be independent from your choice of pagination.
+You can use the [next-pageable](https://github.com/allcrux/next-pageable) gem, which
+is another minimalistic gem for very basic paging leveraging Rails concerns, to just
+provide the functionality you need for infinite scrolling and avoiding a count query
+on each page request (Your main page might still do a count query but you won't
+be repeating them when requesting next page data behind the scenes.)
+
+
 Underlying it depends on ViewComponent and Slim but these are not forced upon the user.
 
 ## Usage
@@ -11,99 +24,176 @@ Underlying it depends on ViewComponent and Slim but these are not forced upon th
 
 Make sure your index action responds both to html and turbo_stream
 
-```
-    respond_to do |format|
-      format.html
-      format.turbo_stream
-    end
+```rb
+@articles = Article.scoped.paginate(params[:page]) # next-pageable
+
+respond_to do |format|
+  format.html
+  format.turbo_stream
+end
 ```
 
 ### index.html.erb|slim
 
-In your index page, make sure you have a DOM element with ID `infinite`
-and render inside of it your initial page content.
+The simplest is to use the `turbo_scroll_auto` helper and
+nest inside your initial infinite content. This will wrap the
+content with an element with id #infinite that will be
+used to append new content to for infinite scrolling.
 
-At the bottom of your page, add the infinite scrolling loader
-by calling the `turbo_scroll_loader` helper and passing the next page index
-if a next page is present.
 
-You could use the [next_pageable](https://github.com/allcrux/next_pageable) gem
-but one can also use any other pagination gem of choice.
+```slim
+= turbo_scroll_auto page: @articles.next_page_index
+  - @articles.each do |article|
+    = article
+```
 
-#### Slim Example
+Alternatively, in your index page, make sure you have a DOM element with ID `infinite`
+and render inside of it your initial page content.
 
+At the bottom of your page, add the infinite scrolling loader
+by calling the `turbo_scroll_auto` helper and passing the next page index
+if a next page is present.
 
-```
+```slim
 #infinite
   - @articles.each do |article|
     = article
 
-= turbo_scroll_loader(page: @articles.next_page_index)
+= turbo_scroll_auto page: @articles.next_page_index
 ```
 
+This gem currently assumes that the page parameter is called `page`, so in
+your controller make sure you use that parameter for selecting
+the records for a given page.
+
+When the loader component becomes visible, it will do 2 things
+
+- append the next page to the #infinite dom id
+- update the loader to load the next page (when present)
+
 If you want to use a different ID, you'll have to pass it on in turbo_stream response.
 
 ### index.turbo_stream.erb|slim
 
-Your turbo_stream response can use the `turbo_scroll_update` helper to
+Your turbo_stream response can use the `turbo_scroll_auto_stream` helper to
 append the next page content and update the current loader with a
 loader for the next page.
 
-When using the [next_pageable](https://github.com/allcrux/next_pageable) gem
+When using the [next-pageable](https://github.com/allcrux/next-pageable) gem
 the next_page_index is already present on the collection when a next page exists.
 
-```
-= turbo_scroll_update page: @articles.next_page_index
+```slim
+= turbo_scroll_auto_stream page: @articles.next_page_index
   - @articles.each do |article|
     = article
 ```
 
+### More variant (no auto loading, just simple 'more' loading)
+
+```slim
+= turbo_scroll_more page: @articles.next_page_index
+  = render(Articles::Row.with_collection(@articles))
+```
+
+Your turbo_stream response can use the `turbo_scroll_more_stream` helper to
+append the next page content and update the current more loader with a
+more loader for the next page.
+
+articles\index.turbo_stream.slim
+
+```slim
+= turbo_scroll_more_stream page: @articles.next_page_index
+  = render Articles::Row.with_collection(@articles)
+```
+
+### An HTML table alternative for table layouts using CSS grids
+
+As HTML is pretty picky on the tags allowed inside 'table', 'tr', 'td', etc you
+can consider using CSS grid as an alternative.
+
+```css
+.article.row {
+  display: grid;
+  grid-template-columns: minmax(0, 2fr) minmax(0, 2fr) minmax(0, 8fr) minmax(0, 2fr) minmax(0, 1fr) 3em;
+  max-width: 100%;
+  width: 100%;
+}
+
+.article.row .col {
+  height: 2.75rem;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+}
+
+.article.row .col-head {
+  font-weight: bolder;
+}
+
+.article.row .col-filter {
+  padding-left: 0rem;
+  padding-right: 0rem;
+}
+
+.article.row .align-right {
+  justify-content: right;
+}
+
+.article.row.striped:nth-child(2n+1) {
+  background-color: #EEEEEE;
+}
+```
+
+which would go hand in hand with this partial for a record row
+
+```slim
+.article.row.striped
+  .col = article.articlenumber
+  .col = article.barcode
+  .col = article.description
+  .col = article.supplier
+  .col.align-right = article.price.print
+  .col.align-right
+    a.btn.btn-sm.btn-secondary href=edit_article_path(article)
+      i.bi.bi-pencil
+```
+
+
 ### Using a different DOM ID
 
 In case you want or need to use a different DOM ID you
-can pass it on as an extra param to the `turbo_scroll_update` helper.
+can pass it on as an extra param to the `turbo_scroll_auto_stream` helper.
 
 The below example illustrates this for the case where your
 DOM ID is `#scroll`.
 
 index.html.slim
 
-```
-#scroll
+```slim
+= turbo_scroll_auto page: @articles.next_page_index, id: :scroll
   - @articles.each do |article|
     = article
-
-= turbo_scroll_loader(page: @articles.next_page_index)
 ```
 
 index.turbo_stream.slim
 
-```
-= turbo_scroll_update page: @articles.next_page_index, infinite_dom_id: :scroll
+```slim
+= turbo_scroll_auto_stream page: @articles.next_page_index, infinite_dom_id: :scroll
   - @articles.each do |article|
     = article
 ```
 
-
-
-### index.
-
 ## Installation
-Add this line to your application's Gemfile:
 
-```ruby
-gem "turbo-scroll"
-```
+Install the gem and add to the application's Gemfile by executing:
 
-And then execute:
-```bash
-$ bundle
-```
+    $ bundle add turbo-scroll
 
-Or install it yourself as:
-```bash
-$ gem install turbo-scroll
-```
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install turbo-scroll
 
 ## License
 

data/Rakefile

@@ -1,3 +1,5 @@
 require "bundler/setup"
 
 require "bundler/gem_tasks"
+
+task default: %i[rubocop]

data/lib/locales/en.yml

@@ -0,0 +1,4 @@
+---
+en:
+  click_here: Click <a href="%{next_page_path}">here</a> to force load the next page.
+  more: More

data/lib/locales/fr.yml

@@ -0,0 +1,4 @@
+---
+fr:
+  click_here: Cliquez <a href="%{next_page_path}">ici</a> pour charger la page suivante.
+  more: Plus

data/lib/locales/nl.yml

@@ -0,0 +1,4 @@
+---
+nl:
+  click_here: Klik <a href="%{next_page_path}">hier</a> voor de volgende pagina.
+  more: Meer

data/lib/locales/ro.yml

@@ -0,0 +1,4 @@
+---
+ro:
+  click_here: Faceți clic <a href="%{next_page_path}">aici</a> pentru a încărca pagina următoare.
+  more: More

data/lib/locales/vn.yml

@@ -0,0 +1,4 @@
+---
+vn:
+  click_here: Nhấp vào <a href="%{next_page_path}">đây</a> để tải trang tiếp theo.
+  more: Xem thêm

data/lib/turbo-scroll/auto.html.slim

@@ -0,0 +1,5 @@
+= turbo_frame_tag loader_dom_id, src: next_page_stream_path, loading: "lazy", target: "_top"
+  .page-loading
+    p == I18n.t(".click_here", next_page_path: next_page_path)
+    - if loading_indicator
+      = render(TurboScroll::SpinLoader.new())

data/lib/turbo-scroll/auto.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "turbo-rails"
+
+class TurboScroll::Auto < ViewComponent::Base
+  include Turbo::FramesHelper
+
+  attr_reader :page, :loader_dom_id, :loading_indicator
+
+  def initialize(page:, loader_dom_id: :loader, loading_indicator: true)
+    @page = page
+    @loader_dom_id = loader_dom_id
+    @loading_indicator = loading_indicator
+  end
+
+  def query_params
+    @query_params ||=
+      request.query_parameters.except(:page, :raw, :format)
+  end
+
+  def next_page_path
+    url_for(page: page, **query_params)
+  end
+
+  def next_page_stream_path
+    url_for(format: :turbo_stream, page: page, **query_params)
+  end
+
+  def render?
+    page
+  end
+end

data/lib/turbo-scroll/{loader.scss → auto.scss}

@@ -1,6 +1,9 @@
 .page-loading {
   height: 15.5em;
   padding-top: 4em;
+  display: flex;
+  justify-content: center;
+  align-items: center;
 }
 
 .page-loading p {

data/lib/turbo-scroll/auto_stream.html.slim

@@ -0,0 +1,7 @@
+= turbo_stream.append(infinite_dom_id)
+  = content
+
+= turbo_stream.replace(loader_dom_id)
+  = render(TurboScroll::Auto.new(page: page, \
+                                 loader_dom_id: loader_dom_id, \
+                                 loading_indicator: loading_indicator))

data/lib/turbo-scroll/auto_stream.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "turbo-rails"
+
+class TurboScroll::AutoStream < ViewComponent::Base
+  include Turbo::FramesHelper
+  include Turbo::StreamsHelper
+
+  attr_reader :page, :loader_dom_id, :infinite_dom_id, :loading_indicator
+
+  def initialize(page:, loader_dom_id: :loader, loading_indicator:, infinite_dom_id: :infinite)
+    @page = page
+    @infinite_dom_id = infinite_dom_id
+    @loading_indicator = loading_indicator
+    @loader_dom_id = loader_dom_id
+  end
+end

data/lib/turbo-scroll/more.html.slim

@@ -0,0 +1,12 @@
+turbo-frame id=loader_dom_id
+  a.more href=next_page_path onclick="more('#{next_page_stream_path}')" =I18n.t(".more")
+
+  javascript:
+    function more(url) {
+      event.preventDefault();
+      fetch(url)
+        .then(response => response.text())
+        .then(html => Turbo.renderStreamMessage(html))
+        .catch(error => console.warn('Something went wrong.', error));
+    }
+

data/lib/turbo-scroll/{loader.rb → more.rb}

@@ -2,13 +2,14 @@
 
 require "turbo-rails"
 
-class TurboScroll::Loader < ViewComponent::Base
+class TurboScroll::More < ViewComponent::Base
   include Turbo::FramesHelper
 
-  attr_reader :page
+  attr_reader :page, :loader_dom_id
 
-  def initialize(page:)
+  def initialize(page:, loader_dom_id: :loader)
     @page = page
+    @loader_dom_id = loader_dom_id
   end
 
   def query_params
@@ -28,4 +29,3 @@ class TurboScroll::Loader < ViewComponent::Base
     page
   end
 end
-

data/lib/turbo-scroll/more_stream.html.slim

@@ -0,0 +1,5 @@
+= turbo_stream.append(infinite_dom_id)
+  = content
+
+= turbo_stream.replace(loader_dom_id)
+  = render(TurboScroll::More.new(page: page, loader_dom_id: loader_dom_id))

data/lib/turbo-scroll/more_stream.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "turbo-rails"
+
+class TurboScroll::MoreStream < ViewComponent::Base
+  include Turbo::FramesHelper
+  include Turbo::StreamsHelper
+
+  attr_reader :page, :loader_dom_id, :infinite_dom_id
+
+  def initialize(page:, loader_dom_id: :loader, infinite_dom_id: :infinite)
+    @page = page
+    @loader_dom_id = loader_dom_id
+    @infinite_dom_id = infinite_dom_id
+  end
+end

data/lib/turbo-scroll/railtie.rb

@@ -1,13 +1,17 @@
 module TurboScroll
   class Railtie < ::Rails::Railtie
     initializer "turbo-scrolls.load_components" do
-      require_relative "update"
-      require_relative "loader"
+      require_relative "auto"
+      require_relative "auto_stream"
+      require_relative "more"
+      require_relative "more_stream"
+      require_relative "spin_loader"
     end
-    initializer "turbo-scrolls.view_helpers" do
+    initializer "turbo-scrolls.view_helpers" do |app|
       ActiveSupport.on_load(:action_view) do
         include TurboScroll::ViewHelpers
       end
+      app.config.i18n.load_path += Dir[File.expand_path(File.join(File.dirname(__FILE__), '../locales', '*.yml')).to_s]
     end
   end
 end

data/lib/turbo-scroll/spin_loader.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "turbo-rails"
+
+class TurboScroll::SpinLoader < ViewComponent::Base
+  #
+  def initialize()
+  end
+end

data/lib/turbo-scroll/spin_loader.slim

@@ -0,0 +1,50 @@
+css:
+  .loader {
+    display: inline-block;
+    position: relative;
+    width: 45px;
+    height: 45px;
+    margin: auto;
+  }
+  .loader div {
+    box-sizing: border-box;
+    display: block;
+    position: absolute;
+    width: 32px;
+    height: 32px;
+    margin: 8px 0px;
+    border: 3px solid #00afd4;
+    border-radius: 50%;
+    animation: loader 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite;
+    border-color: #00afd4 transparent transparent transparent;
+  }
+  .loader div:nth-child(1) {
+    animation-delay: -0.45s;
+  }
+  .loader div:nth-child(2) {
+    animation-delay: -0.3s;
+  }
+  .loader div:nth-child(3) {
+    animation-delay: -0.15s;
+  }
+  .page-loading {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+  }
+
+  @keyframes loader {
+    0% {
+      transform: rotate(0deg);
+    }
+    100% {
+      transform: rotate(360deg);
+    }
+  }
+
+.loader
+  div
+  div
+  div
+  div

data/lib/turbo-scroll/version.rb

@@ -1,3 +1,3 @@
 module TurboScroll
-  VERSION = "0.1.0"
+  VERSION = "0.1.4"
 end

data/lib/turbo-scroll.rb

@@ -3,12 +3,50 @@ require "turbo-scroll/railtie" if defined?(Rails::Railtie)
 
 module TurboScroll
   module ViewHelpers
-    def turbo_scroll_loader(page:)
-      render(TurboScroll::Loader.new(page: page))
+
+    #
+    def turbo_scroll_auto(page:, loader_dom_id: :loader, loading_indicator: true, id: :infinite, &block)
+      if block_given?
+        safe_concat(%{<div id="#{id}">})
+        concat(capture(&block))
+        safe_concat("</div>")
+      end
+      render(TurboScroll::Auto.new(page: page, loader_dom_id: loader_dom_id, loading_indicator: loading_indicator))
+    end
+
+    #
+    def turbo_scroll_more(page:, loader_dom_id: :loader, id: :infinite, &block)
+      if block_given?
+        safe_concat(%{<div id="#{id}">})
+        concat(capture(&block))
+        safe_concat("</div>")
+      end
+      render(TurboScroll::More.new(page: page, loader_dom_id: loader_dom_id))
+    end
+
+    #
+    def turbo_scroll_auto_stream(page:, loader_dom_id: :loader, infinite_dom_id: :infinite, loading_indicator: true, &block)
+      render(
+        TurboScroll::AutoStream.new(
+          page: page,
+          loader_dom_id: loader_dom_id,
+          infinite_dom_id: infinite_dom_id,
+          loading_indicator: loading_indicator
+        ),
+        &block
+      )
     end
 
-    def turbo_scroll_update(page:, infinite_dom_id: :infinite, &block)
-      render(TurboScroll::Update.new(page: page, infinite_dom_id: infinite_dom_id), &block)
+    #
+    def turbo_scroll_more_stream(page:, loader_dom_id: :loader, infinite_dom_id: :infinite, &block)
+      render(
+        TurboScroll::MoreStream.new(
+          page: page,
+          loader_dom_id: loader_dom_id,
+          infinite_dom_id: infinite_dom_id
+        ),
+        &block
+      )
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turbo-scroll
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.4
 platform: ruby
 authors:
 - Koen handekyn
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-05 00:00:00.000000000 Z
+date: 2022-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -66,7 +66,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4'
-description: Description of TurboScroll.
+description: TurboScroll is a minimalistic gem that provides infinite scrolling for
+  Rails based applications using Turbo.
 email:
 - koen@handekyn.com
 executables: []
@@ -76,14 +77,24 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- lib/tasks/turbo_scroll_tasks.rake
+- lib/locales/en.yml
+- lib/locales/fr.yml
+- lib/locales/nl.yml
+- lib/locales/ro.yml
+- lib/locales/vn.yml
 - lib/turbo-scroll.rb
-- lib/turbo-scroll/loader.html.slim
-- lib/turbo-scroll/loader.rb
-- lib/turbo-scroll/loader.scss
+- lib/turbo-scroll/auto.html.slim
+- lib/turbo-scroll/auto.rb
+- lib/turbo-scroll/auto.scss
+- lib/turbo-scroll/auto_stream.html.slim
+- lib/turbo-scroll/auto_stream.rb
+- lib/turbo-scroll/more.html.slim
+- lib/turbo-scroll/more.rb
+- lib/turbo-scroll/more_stream.html.slim
+- lib/turbo-scroll/more_stream.rb
 - lib/turbo-scroll/railtie.rb
-- lib/turbo-scroll/update.html.slim
-- lib/turbo-scroll/update.rb
+- lib/turbo-scroll/spin_loader.rb
+- lib/turbo-scroll/spin_loader.slim
 - lib/turbo-scroll/version.rb
 homepage: https://github.com/allcrux/turbo-scroll
 licenses:
@@ -93,6 +104,7 @@ metadata:
   homepage_uri: https://github.com/allcrux/turbo-scroll
   source_code_uri: https://github.com/allcrux/turbo-scroll
   changelog_uri: https://github.com/allcrux/turbo-scroll/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -111,5 +123,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Summary of TurboScroll.
+summary: Modern infinite page scrolling for Rails.
 test_files: []

data/lib/tasks/turbo_scroll_tasks.rake

@@ -1,4 +0,0 @@
-# desc "Explaining what the task does"
-# task :turbo-scroll do
-#   # Task goes here
-# end

data/lib/turbo-scroll/loader.html.slim

@@ -1,3 +0,0 @@
-= turbo_frame_tag :infinite_loader, src: next_page_stream_path, loading: "lazy", target: "_top"
-  .page-loading
-    p ==t(".click_here", next_page_path: next_page_path)

data/lib/turbo-scroll/update.html.slim

@@ -1,5 +0,0 @@
-= turbo_stream.append(infinite_dom_id)
-  = content
-
-= turbo_stream.replace(:infinite_loader)
-  = render(TurboScroll::Loader.new(page: page))

data/lib/turbo-scroll/update.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require "turbo-rails"
-
-class TurboScroll::Update < ViewComponent::Base
-  include Turbo::FramesHelper
-  include Turbo::StreamsHelper
-
-  attr_reader :page
-  attr_reader :infinite_dom_id
-
-  def initialize(page:, infinite_dom_id: :infinite)
-    @page = page
-    @infinite_dom_id = infinite_dom_id
-  end
-end
-