power_grid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 375c1ae59e3f85bc75cc81e1d5a6ff83e721a6aa2889e0e2bfcf7c95036957b0
+  data.tar.gz: 7f2e36254faba5169556809115868a146b3c4610d4efe68538defef60026bb6a
+SHA512:
+  metadata.gz: 9de32b37843c0b4a2fc649d35c48bdb8bf55d13c6ecddb989d394b24e325f76caa6b93e6f695d9e2b86af62eeb98db4457b80df027eb4ae66a5487830b33fd1c
+  data.tar.gz: 49a17f93efe51b4e3a8a4b6f4a46cf0ad1117fb262479af8c77469a0f5cc7f1d0b0a8f4df453224a601fc7088ea7156a1f2639380a610611b85a7c22391e3957

data/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.0', '3.1', '3.2', '3.3']
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.7
+before_install: gem install bundler -v 2.1.4

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at bhavin.nandani@rackspace.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in power_grid.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,272 @@
+PATH
+  remote: .
+  specs:
+    power_grid (0.1.0)
+      importmap-rails
+      rails (>= 6.0)
+      turbo-rails
+      view_component
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.1.6)
+      actionpack (= 7.1.6)
+      activesupport (= 7.1.6)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (7.1.6)
+      actionpack (= 7.1.6)
+      activejob (= 7.1.6)
+      activerecord (= 7.1.6)
+      activestorage (= 7.1.6)
+      activesupport (= 7.1.6)
+      mail (>= 2.7.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.1.6)
+      actionpack (= 7.1.6)
+      actionview (= 7.1.6)
+      activejob (= 7.1.6)
+      activesupport (= 7.1.6)
+      mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
+      rails-dom-testing (~> 2.2)
+    actionpack (7.1.6)
+      actionview (= 7.1.6)
+      activesupport (= 7.1.6)
+      cgi
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    actiontext (7.1.6)
+      actionpack (= 7.1.6)
+      activerecord (= 7.1.6)
+      activestorage (= 7.1.6)
+      activesupport (= 7.1.6)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.1.6)
+      activesupport (= 7.1.6)
+      builder (~> 3.1)
+      cgi
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (7.1.6)
+      activesupport (= 7.1.6)
+      globalid (>= 0.3.6)
+    activemodel (7.1.6)
+      activesupport (= 7.1.6)
+    activerecord (7.1.6)
+      activemodel (= 7.1.6)
+      activesupport (= 7.1.6)
+      timeout (>= 0.4.0)
+    activestorage (7.1.6)
+      actionpack (= 7.1.6)
+      activejob (= 7.1.6)
+      activerecord (= 7.1.6)
+      activesupport (= 7.1.6)
+      marcel (~> 1.0)
+    activesupport (7.1.6)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      mutex_m
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (3.3.1)
+    builder (3.3.0)
+    capybara (3.39.2)
+      addressable
+      matrix
+      mini_mime (>= 0.1.3)
+      nokogiri (~> 1.8)
+      rack (>= 1.6.0)
+      rack-test (>= 0.6.3)
+      regexp_parser (>= 1.5, < 3.0)
+      xpath (~> 3.2)
+    cgi (0.5.1)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.5)
+    crass (1.0.6)
+    date (3.5.1)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    erb (4.0.4)
+      cgi (>= 0.3.3)
+    erubi (1.13.1)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    importmap-rails (2.0.3)
+      actionpack (>= 6.0.0)
+      activesupport (>= 6.0.0)
+      railties (>= 6.0.0)
+    io-console (0.8.1)
+    irb (1.15.3)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.9.0)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.1.0)
+    matrix (0.4.3)
+    method_source (1.1.0)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.9)
+    minitest (5.26.1)
+    mutex_m (0.3.0)
+    net-imap (0.4.22)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.5)
+    nokogiri (1.15.7)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.3.0)
+      date
+      stringio
+    public_suffix (5.1.1)
+    racc (1.8.1)
+    rack (3.2.4)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails (7.1.6)
+      actioncable (= 7.1.6)
+      actionmailbox (= 7.1.6)
+      actionmailer (= 7.1.6)
+      actionpack (= 7.1.6)
+      actiontext (= 7.1.6)
+      actionview (= 7.1.6)
+      activejob (= 7.1.6)
+      activemodel (= 7.1.6)
+      activerecord (= 7.1.6)
+      activestorage (= 7.1.6)
+      activesupport (= 7.1.6)
+      bundler (>= 1.15.0)
+      railties (= 7.1.6)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (7.1.6)
+      actionpack (= 7.1.6)
+      activesupport (= 7.1.6)
+      cgi
+      irb
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rake (12.3.3)
+    rdoc (6.17.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.11.3)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-rails (7.1.1)
+      actionpack (>= 7.0)
+      activesupport (>= 7.0)
+      railties (>= 7.0)
+      rspec-core (~> 3.13)
+      rspec-expectations (~> 3.13)
+      rspec-mocks (~> 3.13)
+      rspec-support (~> 3.13)
+    rspec-support (3.13.6)
+    securerandom (0.3.2)
+    sqlite3 (1.6.9)
+      mini_portile2 (~> 2.8.0)
+    stringio (3.1.9)
+    thor (1.4.0)
+    timeout (0.5.0)
+    tsort (0.2.0)
+    turbo-rails (2.0.12)
+      actionpack (>= 6.0.0)
+      railties (>= 6.0.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    view_component (3.24.0)
+      activesupport (>= 5.2.0, < 8.2)
+      concurrent-ruby (~> 1)
+      method_source (~> 1.0)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    xpath (3.2.0)
+      nokogiri (~> 1.8)
+    zeitwerk (2.6.18)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  capybara
+  power_grid!
+  rake (~> 12.0)
+  rspec (~> 3.0)
+  rspec-rails
+  sqlite3 (~> 1.6.0)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Bhavin Rackspace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# PowerGrid
+
+[![Gem Version](https://badge.fury.io/rb/power_grid.svg)](https://badge.fury.io/rb/power_grid)
+[![CI](https://github.com/bhavinNandani/power_grid/actions/workflows/ci.yml/badge.svg)](https://github.com/bhavinNandani/power_grid/actions/workflows/ci.yml)
+
+**PowerGrid** is a production-ready, server-side processed table component for Rails applications. It combines the raw performance of Active Record with the responsiveness of modern UI frameworks like Hotwire and Stimulus.
+
+Built with **ViewComponent**, **Turbo Frames**, **Stimulus**, and **TailwindCSS**, PowerGrid offers a premium, SPA-like experience without the complexity of a Javascript frontend framework.
+
+![PowerGrid UI Mockup](docs/assets/ui_mockup.png)
+
+## Features
+
+- 🏎 **Server-Side Processing**: Efficiently handles huge datasets using Active Record `offset` and `limit`.
+- ⚡️ **Hotwire Integration**: Instant sorting, filtering, and pagination updates via Turbo Frames.
+- 🔍 **Advanced Search**: 
+  - Multi-column search support.
+  - Search on **joined tables** via `sql_expression`.
+  - Automatic input debouncing.
+- 📄 **Smart Pagination**:
+  - Numbered pagination window (e.g., `1 2 ... 5 6 7 ... 10`).
+  - Dynamic **Per Page** limits.
+- 🔒 **Secure Scoping**: Supports `initial_scope` for tenant/user scoping (e.g., `current_user.posts`).
+- 🎨 **Visuals**:
+  - Professional "Slate" color palette.
+  - Fully responsive and Dark Mode compatible.
+- 🚀 **Optimization**: Built-in support for `includes` to automatically prevent N+1 queries.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'power_grid'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Quick Start
+
+### 1. Define your Grid
+
+Create a class that inherits from `PowerGrid::Base`. This class defines your data source and columns.
+
+```ruby
+# app/grids/users_grid.rb
+class UsersGrid < PowerGrid::Base
+  scope { User.all } 
+
+  # Basic columns
+  column :name, sortable: true, searchable: true
+  column :email, sortable: true, searchable: true
+  
+  # Column with block formatting (for badges, links, etc.)
+  column :status do |user|
+    tag.span(user.status.humanize, class: "badge badge-#{user.status}")
+  end
+end
+```
+
+### 2. Instantiate in Controller
+
+Initialize the grid in your controller action. You can pass an initial scope (like `current_user.posts`) to ensure security.
+
+```ruby
+# app/controllers/users_controller.rb
+def index
+  # @grid = UsersGrid.new(params)
+  # OR with scoping:
+  @grid = UsersGrid.new(params, initial_scope: current_user.posts)
+end
+```
+
+### 3. Render in View
+
+Render the `PowerGrid::TableComponent`, passing the grid instance.
+
+```erb
+<!-- app/views/users/index.html.erb -->
+<%= render PowerGrid::TableComponent.new(@grid) %>
+```
+
+## detailed API Reference
+
+### `column(name, options = {}, &block)`
+
+Defines a column in the table.
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `sortable` | `boolean` | If true, the column header will be clickable to sort. |
+| `searchable` | `boolean` | If true, the global search input will check this column using `LIKE`. |
+| `sql_expression` | `string` | The raw SQL column name to use for sorting/searching. Essential for joined tables (e.g., `"posts.title"`). |
+| `includes` | `symbol/array` | Association(s) to eager load when rendering this column to prevent N+1 queries. |
+
+**Example: Joined Column**
+```ruby
+column :"posts.title", 
+       searchable: true, 
+       sortable: true, 
+       sql_expression: "posts.title",
+       includes: :posts
+```
+
+### `scope { ... }`
+
+Defines the default Active Record scope. This is used if no `initial_scope` is passed to the initializer.
+
+```ruby
+scope { User.active.order(created_at: :desc) }
+```
+
+### `initialize(params, initial_scope: nil)`
+
+- `params`: The Rails `params` hash (required for sorting/filtering state).
+- `initial_scope`: Use this to pass context-aware relations, such as `current_account.invoices`. If provided, it overrides the class-level `scope`.
+
+## Frontend Configuration
+
+### TailwindCSS
+
+PowerGrid creates HTML with standard Tailwind utility classes (using the `slate` color palette). Ensure your Tailwind configuration scans your gem paths or includes utilities for:
+- Colors: `slate-50` to `slate-900`.
+- Spacing, Borders, Flexbox, Typography.
+
+### Hotwire & Stimulus
+
+Ensure your application has `turbo-rails` and `stimulus-rails` installed.
+The gem includes a Stimulus controller `power_grid--table_controller` which handles search input debouncing and auto-submission.
+
+If using **Importmap** (default in Rails 7+), this is configured automatically.
+If using **esbuild/webpack**, manually register the controller if needed, or ensure the gem's assets are in your load path.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bhavinNandani/power_grid.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/app/components/power_grid/table_component.html.erb

@@ -0,0 +1,127 @@
+<div class="power-grid-container w-full bg-white dark:bg-slate-900 rounded-lg shadow ring-1 ring-slate-900/5" data-controller="power-grid-table">
+  
+  <!-- Top Controls: Per Page & Search -->
+  <div class="flex flex-col sm:flex-row justify-between items-center p-4 border-b border-slate-200 dark:border-slate-700 space-y-3 sm:space-y-0">
+    <!-- Per Page -->
+    <div class="flex items-center text-sm text-slate-700 dark:text-slate-300">
+      <span class="mr-2">Show</span>
+      <%= form_with url: request.path, method: :get, data: { turbo_frame: "power_grid_table", turbo_action: "advance", power_grid_table_target: "form" }, class: "inline-block", id: "power_grid_form_#{request.path.parameterize}" do |f| %>
+        <% params.except(:per_page, :page).each do |key, value| %>
+          <%= hidden_field_tag key, value %>
+        <% end %>
+        <!-- Reset page to 1 on limit change -->
+        <%= hidden_field_tag :page, 1 %>
+        
+        <%= select_tag :per_page, options_for_select([10, 25, 50, 100], @grid.per_page), 
+            class: "mx-1 mt-1 block w-20 rounded-md border-slate-300 py-1.5 text-base focus:border-indigo-500 focus:outline-none focus:ring-indigo-500 sm:text-sm dark:bg-slate-800 dark:border-slate-600 dark:text-white", 
+            data: { action: "change->power-grid-table#search" } 
+        %>
+      <% end %>
+      <span class="ml-2">entries</span>
+    </div>
+
+    <!-- Search -->
+    <div class="w-full sm:w-auto">
+      <div class="relative rounded-md shadow-sm">
+        <label for="search" class="sr-only">Search</label>
+        <div class="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+          <svg class="h-5 w-5 text-slate-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+            <path fill-rule="evenodd" d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z" clip-rule="evenodd" />
+          </svg>
+        </div>
+        <%= text_field_tag :q, params[:q], placeholder: "Search...", 
+            class: "block w-full rounded-md border-0 py-1.5 pl-10 text-slate-900 ring-1 ring-inset ring-slate-300 placeholder:text-slate-400 focus:ring-2 focus:ring-inset focus:ring-indigo-600 sm:text-sm sm:leading-6 dark:bg-slate-800 dark:text-white dark:ring-slate-600 dark:placeholder-slate-500", 
+            data: { action: "input->power-grid-table#search" },
+            form: "power_grid_form_#{request.path.parameterize}" 
+        %>
+      </div>
+    </div>
+  </div>
+
+  <%= turbo_frame_tag "power_grid_table" do %>
+    <div class="overflow-x-auto">
+      <table class="min-w-full divide-y divide-slate-200 dark:divide-slate-700">
+        <thead class="bg-slate-50 dark:bg-slate-800/80">
+          <tr>
+            <% columns.each do |key, options| %>
+              <th scope="col" class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase tracking-wider dark:text-slate-400">
+                <% if options[:sortable] %>
+                  <%= link_to request.params.merge(order: key, dir: (params[:order] == key.to_s && params[:dir] == "asc" ? "desc" : "asc")), class: "group inline-flex items-center", data: { turbo_action: "advance" } do %>
+                    <%= key.to_s.humanize %>
+                    <span class="ml-2 flex-none rounded text-slate-400 group-hover:text-slate-600 dark:group-hover:text-slate-300">
+                      <% if params[:order] == key.to_s %>
+                        <%= params[:dir] == "asc" ? "▲" : "▼" %>
+                      <% else %>
+                        <svg class="h-4 w-4 opacity-0 group-hover:opacity-100" viewBox="0 0 20 20" fill="currentColor">
+                          <path fill-rule="evenodd" d="M10 3a.75.75 0 01.55.24l3.25 3.5a.75.75 0 11-1.1 1.02L10 4.852 7.3 7.76a.75.75 0 01-1.1-1.02l3.25-3.5A.75.75 0 0110 3zm-3.76 9.2a.75.75 0 011.06.04l2.7 2.908 2.7-2.908a.75.75 0 111.1 1.02l-3.25 3.5a.75.75 0 01-1.1 0l-3.25-3.5a.75.75 0 01.04-1.06z" clip-rule="evenodd" />
+                        </svg>
+                      <% end %>
+                    </span>
+                  <% end %>
+                <% else %>
+                  <%= key.to_s.humanize %>
+                <% end %>
+              </th>
+            <% end %>
+          </tr>
+        </thead>
+        <tbody class="bg-white divide-y divide-slate-200 dark:bg-slate-900 dark:divide-slate-700">
+          <% records.each_with_index do |record, index| %>
+            <tr class="<%= index.even? ? 'bg-white dark:bg-slate-900' : 'bg-slate-50 dark:bg-slate-800/50' %> hover:bg-slate-50 dark:hover:bg-slate-800 transition-colors">
+              <% columns.each do |key, options| %>
+                <td class="px-6 py-4 whitespace-nowrap text-sm text-slate-900 dark:text-slate-100">
+                  <% if options[:block] %>
+                    <%= options[:block].call(record) %>
+                  <% else %>
+                    <%= record.send(key) %>
+                  <% end %>
+                </td>
+              <% end %>
+            </tr>
+          <% end %>
+          <% if records.empty? %>
+            <tr>
+               <td colspan="<%= columns.size %>" class="px-6 py-10 text-center text-sm text-slate-500 dark:text-slate-400">
+                 No matching records found
+               </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+
+    <!-- Pagination Footer -->
+    <div class="flex items-center justify-between border-t border-slate-200 bg-white px-4 py-3 sm:px-6 dark:bg-slate-900 dark:border-slate-700">
+       <!-- Entries Info -->
+       <div class="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
+          <div>
+            <p class="text-sm text-slate-700 dark:text-slate-300">
+              Showing <span class="font-medium"><%= @grid.page_range_start %></span> to <span class="font-medium"><%= @grid.page_range_end %></span> of <span class="font-medium"><%= @grid.total_count %></span> entries
+            </p>
+          </div>
+          <div>
+            <!-- Numbered Pagination Controls -->
+             <nav class="isolate inline-flex -space-x-px rounded-md shadow-sm" aria-label="Pagination">
+               <% if @grid.current_page > 1 %>
+                 <%= link_to "Previous", request.params.merge(page: @grid.current_page - 1), class: "relative inline-flex items-center rounded-l-md px-2 py-2 text-slate-400 ring-1 ring-inset ring-slate-300 hover:bg-slate-50 focus:z-20 focus:outline-offset-0 dark:ring-slate-600 dark:hover:bg-slate-800", data: { turbo_action: "advance" } %>
+               <% end %>
+               
+               <% @grid.pagination_window.each do |page| %>
+                 <% if page == :gap %>
+                   <span class="relative inline-flex items-center px-4 py-2 text-sm font-semibold text-slate-700 ring-1 ring-inset ring-slate-300 focus:outline-offset-0 dark:text-slate-200 dark:ring-slate-600">...</span>
+                 <% elsif page == @grid.current_page %>
+                   <span class="relative z-10 inline-flex items-center bg-indigo-600 px-4 py-2 text-sm font-semibold text-white focus:z-20 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600"><%= page %></span>
+                 <% else %>
+                   <%= link_to page, request.params.merge(page: page), class: "relative inline-flex items-center px-4 py-2 text-sm font-semibold text-slate-900 ring-1 ring-inset ring-slate-300 hover:bg-slate-50 focus:z-20 focus:outline-offset-0 dark:text-slate-200 dark:ring-slate-600 dark:hover:bg-slate-800", data: { turbo_action: "advance" } %>
+                 <% end %>
+               <% end %>
+
+               <% if @grid.current_page < @grid.total_pages %>
+                 <%= link_to "Next", request.params.merge(page: @grid.current_page + 1), class: "relative inline-flex items-center rounded-r-md px-2 py-2 text-slate-400 ring-1 ring-inset ring-slate-300 hover:bg-slate-50 focus:z-20 focus:outline-offset-0 dark:ring-slate-600 dark:hover:bg-slate-800", data: { turbo_action: "advance" } %>
+               <% end %>
+            </nav>
+          </div>
+       </div>
+    </div>
+  <% end %>
+</div>

data/app/components/power_grid/table_component.rb

@@ -0,0 +1,29 @@
+require "view_component"
+
+module PowerGrid
+  class TableComponent < ViewComponent::Base
+    include Turbo::FramesHelper
+
+    def initialize(grid_or_class, params: nil)
+    if grid_or_class.is_a?(Class)
+      @grid = grid_or_class.new(params)
+    else
+      @grid = grid_or_class
+    end
+  end
+
+    def columns
+      @grid.class.defined_columns
+    end
+
+    def records
+      @grid.records
+    end
+
+    def sort_url(column, direction)
+      # TODO: Helper to generate URL with updated params
+      # For now just return hash or similar, we might need a helper that merges params
+      # We need request context or helpers provided by Rails
+    end
+  end
+end

data/app/javascript/controllers/power_grid/table_controller.js

@@ -0,0 +1,17 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = [ "form" ]
+
+  connect() {
+    console.log("PowerGrid Table Controller connected")
+    this.timeout = null
+  }
+
+  search() {
+    clearTimeout(this.timeout)
+    this.timeout = setTimeout(() => {
+      this.formTarget.requestSubmit()
+    }, 300)
+  }
+}

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "power_grid"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/power_grid/base.rb

@@ -0,0 +1,154 @@
+module PowerGrid
+  class Base
+    class << self
+      def scope(&block)
+        @scope_block = block
+      end
+
+      def column(name, **options, &block)
+        @columns ||= {}
+        @columns[name] = options.merge(block: block)
+      end
+
+      def filter(name, **options)
+        @filters ||= {}
+        @filters[name] = options
+      end
+
+      def defined_scope
+        @scope_block
+      end
+
+      def defined_columns
+        @columns || {}
+      end
+
+      def defined_filters
+        @filters || {}
+      end
+    end
+
+    attr_reader :params, :initial_scope
+
+    def initialize(params = {}, initial_scope: nil)
+      @params = params
+      @initial_scope = initial_scope
+    end
+
+    def records
+      @records ||= begin
+        scope = @initial_scope || instance_eval(&self.class.defined_scope)
+        scope = apply_includes(scope)
+        scope = apply_includes(scope)
+        scope = apply_search(scope)
+        scope = apply_sort(scope)
+        
+        # Capture total count after filtering but before pagination
+        @total_count = scope.count
+        
+        scope = apply_pagination(scope)
+        scope
+      end
+    end
+
+    def total_count
+      # Ensure records are loaded to populate @total_count
+      records unless defined?(@total_count)
+      @total_count
+    end
+
+    def current_page
+      (params[:page] || 1).to_i
+    end
+
+    def per_page
+      limit = (params[:per_page] || 10).to_i
+      limit > 100 ? 100 : limit # Cap at 100 for safety
+    end
+
+    def offset
+      (current_page - 1) * per_page
+    end
+
+    def page_range_start
+      return 0 if total_count == 0
+      offset + 1
+    end
+
+    def page_range_end
+      end_val = offset + per_page
+      end_val > total_count ? total_count : end_val
+    end
+
+    def total_pages
+      (total_count.to_f / per_page).ceil
+    end
+
+    def pagination_window(window: 2)
+      return (1..total_pages).to_a if total_pages <= (window * 2) + 5
+
+      current = current_page
+      last = total_pages
+      left = current - window
+      right = current + window
+
+      range = []
+      range << 1
+      range << :gap if left > 2
+      
+      (left..right).each do |i|
+        range << i if i > 1 && i < last
+      end
+      
+      range << :gap if right < last - 1
+      range << last
+      range
+    end
+
+    private
+
+    def apply_includes(scope)
+      includes_list = self.class.defined_columns.values.map { |opts| opts[:includes] }.compact
+      return scope if includes_list.empty?
+      
+      scope.includes(*includes_list)
+    end
+    def apply_pagination(scope)
+      scope.offset(offset).limit(per_page)
+    end
+
+
+    def apply_search(scope)
+      query = params[:q]
+      return scope if query.blank?
+
+      searchable_columns = self.class.defined_columns.select { |_, opts| opts[:searchable] }
+      return scope if searchable_columns.empty?
+
+      conditions = searchable_columns.map do |name, opts|
+        # If sql_expression is provided, use it. Otherwise use the column name (which might be table.col)
+        # We cast to text/string for generic like search if needed, but for now simple LIKE
+        col_expr = opts[:sql_expression] || name.to_s
+        "#{col_expr} LIKE :query"
+      end.join(" OR ")
+
+      scope.where(conditions, query: "%#{query}%")
+    end
+
+    def apply_sort(scope)
+      order_column = params[:order]
+      direction = params[:dir] || "asc"
+
+      return scope unless order_column.present?
+      
+      column_def = self.class.defined_columns[order_column.to_sym]
+      return scope unless column_def && column_def[:sortable]
+
+      # Use sql_expression for sorting if provided (useful for joined columns or calculated fields)
+      sort_expr = column_def[:sql_expression] || order_column
+      
+      scope.order(sort_expr => direction)
+    end
+
+  end
+end

data/lib/power_grid/engine.rb

@@ -0,0 +1,19 @@
+require "rails/all"
+require "rails/engine"
+require "turbo-rails"
+
+module PowerGrid
+  class Engine < ::Rails::Engine
+    isolate_namespace PowerGrid
+
+    initializer "power_grid.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/javascript")
+        app.config.assets.paths << root.join("app/components")
+      end
+    end
+
+    # Removed importmap auto-configuration to prevent "Is a directory" errors.
+    # Users can pin the controller manually if needed.
+  end
+end

data/lib/power_grid/version.rb

@@ -0,0 +1,3 @@
+module PowerGrid
+  VERSION = "0.1.0"
+end

data/lib/power_grid.rb

@@ -0,0 +1,9 @@
+require_relative "power_grid/version"
+require_relative "power_grid/base"
+require_relative "power_grid/engine"
+require "view_component"
+
+module PowerGrid
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/power_grid.gemspec

@@ -0,0 +1,38 @@
+require_relative 'lib/power_grid/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "power_grid"
+  spec.version       = PowerGrid::VERSION
+  spec.authors       = ["Bhavin Rackspace"]
+  spec.email         = ["bhavin.nandani@rackspace.com"]
+
+  spec.summary       = "A powerful, server-side processed table component for Rails."
+  spec.description   = "PowerGrid provides a view component based table with server-side sorting, filtering, and pagination."
+  spec.homepage      = "https://github.com/bhavinNandani/power_grid"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/bhavinNandani/power_grid"
+  spec.metadata["changelog_uri"] = "https://github.com/bhavinNandani/power_grid/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 6.1", "< 8.0"
+  spec.add_dependency "view_component", ">= 2.0", "< 4.0"
+  spec.add_dependency "turbo-rails", ">= 1.0", "< 3.0"
+  spec.add_dependency "importmap-rails", ">= 1.0", "< 3.0"
+
+  spec.add_development_dependency "sqlite3", "~> 1.6"
+  spec.add_development_dependency "rspec-rails", "~> 5.0"
+  spec.add_development_dependency "capybara", "~> 3.0"
+end

metadata

@@ -0,0 +1,191 @@
+--- !ruby/object:Gem::Specification
+name: power_grid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bhavin Rackspace
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: PowerGrid provides a view component based table with server-side sorting,
+  filtering, and pagination.
+email:
+- bhavin.nandani@rackspace.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/components/power_grid/table_component.html.erb
+- app/components/power_grid/table_component.rb
+- app/javascript/controllers/power_grid/table_controller.js
+- bin/console
+- bin/setup
+- docs/assets/ui_mockup.png
+- lib/power_grid.rb
+- lib/power_grid/base.rb
+- lib/power_grid/engine.rb
+- lib/power_grid/version.rb
+- power_grid.gemspec
+homepage: https://github.com/bhavinNandani/power_grid
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/bhavinNandani/power_grid
+  source_code_uri: https://github.com/bhavinNandani/power_grid
+  changelog_uri: https://github.com/bhavinNandani/power_grid/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A powerful, server-side processed table component for Rails.
+test_files: []