rails_ui_guard 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e4b34d4a068c77ba4fb3bbdc856a8991c7adba96234a9a657eb62a34baa1bf9
-  data.tar.gz: cb7942f57e62aa72c62bda6051bc361c08ae50350a53455a980e15d8434fca2a
+  metadata.gz: b1d3f593e10f2bf16746f51585833c1498b43a021b60a02266b4882bf03e3663
+  data.tar.gz: 734f44236fe4bacf6ee8c0596ca5d6ca0274efe7c2688cf117fa6a31dc7ab3e6
 SHA512:
-  metadata.gz: 9bc6825f8d65d7055a21cc4ad5f0070188c3ee563a2afb78efff416febfd7fda94cf248a77bb81d5081c7637f9302b1ffc3f158ee712817503d67fd619f18f0b
-  data.tar.gz: 4bac57db93eb3c5d763c32ef856d164f918b1376e493a7dea74e4f52da20395300e989d3679831dcbf7615f476fcd801a54f492610cb1a42c62f770630d44fec
+  metadata.gz: 77118dc073830e7682eef8958f544c889ccc09cfb9e572059bbd89c39197ea68c03c04b7b6f714a0a2a3db4f1b057aaa2df07b71d83c81ada232f1f16feec8b5
+  data.tar.gz: a759443c0ba30faab1fb4b9604541c490f76bbebf65802f78088d4f7e4a34b21d0ed1bec28d707e59d0bae67c2e352482bc2356d553da54c94449c3778129bca

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2024-12-28
+
+### Enhanced
+- Improved overlay UI with better visual design
+- Enhanced color-coded headers (red for locked, yellow for under work)
+- Better icon display with rounded backgrounds
+- Improved message formatting and readability
+- Added action buttons (Go to Dashboard, Manage Access for admins)
+- Enhanced CSS with animations (fade-in, slide-up)
+- Better backdrop blur effects
+- More user-friendly default messages
+- Improved mobile responsiveness
+
+### Fixed
+- Better handling of feature status records
+- Improved variable scope in overlay partial
+
+## [0.1.0] - 2024-12-28
+
+### Added
+- Initial release of Rails UI Guard
+- Feature status management (Active, Locked, Under Work)
+- UI blur/overlay system (no JavaScript required)
+- Backend enforcement helpers
+- Sidebar status badges with icons
+- View helpers for rendering overlays
+- Controller helpers for enforcing access
+- Model concern for feature status management
+- Rails Engine integration
+- Migration generator
+- Active Admin integration support
+- Comprehensive documentation
+
+### Features
+- Per-tenant feature locking
+- Maintenance mode support
+- Mobile-safe and accessible UI
+- Rails 6/7/8 compatible
+- Polymorphic statusable support
+
+[0.1.1]: https://github.com/KapilDevPal/Rails-Ui-Guard/releases/tag/v0.1.1
+[0.1.0]: https://github.com/KapilDevPal/Rails-Ui-Guard/releases/tag/v0.1.0
+

data/GEM_SETUP_COMPLETE.md

@@ -0,0 +1,156 @@
+# ✅ Rails UI Guard Gem - Setup Complete!
+
+Your gem is ready to be pushed to GitHub and published to RubyGems.
+
+## 📁 Gem Structure
+
+```
+rails_ui_guard_gem/
+├── lib/
+│   ├── rails_ui_guard.rb                    # Main entry point
+│   └── rails_ui_guard/
+│       ├── version.rb                         # Version number
+│       ├── engine.rb                          # Rails Engine
+│       ├── controller_helpers.rb              # Controller helpers
+│       ├── view_helpers.rb                    # View helpers
+│       ├── concerns/
+│       │   └── feature_statusable.rb          # Model concern
+│       ├── app/
+│       │   ├── models/
+│       │   │   └── rails_ui_guard/
+│       │   │       └── feature_status.rb      # FeatureStatus model
+│       │   └── views/
+│       │       └── rails_ui_guard/
+│       │           └── shared/
+│       │               └── _module_overlay.html.erb
+│       └── generators/
+│           └── rails_ui_guard/
+│               └── install/                  # Install generator
+├── rails_ui_guard.gemspec                    # Gem specification
+├── README.md                                  # Documentation
+├── CHANGELOG.md                               # Version history
+├── LICENSE.txt                                # MIT License
+├── Gemfile                                    # Development dependencies
+├── Rakefile                                   # Rake tasks
+├── .gitignore                                 # Git ignore rules
+└── setup_gem.sh                               # Setup script
+```
+
+## 🚀 Quick Start - Push to GitHub
+
+### Option 1: Use the setup script
+
+```bash
+cd rails_ui_guard_gem
+./setup_gem.sh
+```
+
+Then follow the printed instructions.
+
+### Option 2: Manual steps
+
+```bash
+cd rails_ui_guard_gem
+
+# Initialize git (if not done)
+git init
+git branch -M main
+
+# Add all files
+git add .
+
+# Commit
+git commit -m "Initial commit: Rails UI Guard v0.1.0"
+
+# Add remote
+git remote add origin https://github.com/KapilDevPal/Rails-Ui-Guard.git
+
+# Push
+git push -u origin main
+```
+
+## 📦 Build and Test Gem
+
+```bash
+# Build the gem
+gem build rails_ui_guard.gemspec
+
+# Install locally to test
+gem install rails_ui_guard-0.1.0.gem --local
+
+# Test in a Rails app
+cd /path/to/test/app
+# Add to Gemfile: gem 'rails_ui_guard', path: '/path/to/rails_ui_guard_gem'
+bundle install
+rails generate rails_ui_guard:install
+rails db:migrate
+```
+
+## 📤 Publish to RubyGems
+
+1. **Sign up** at https://rubygems.org
+2. **Get your API key** from https://rubygems.org/profile/edit
+3. **Push the gem**:
+
+```bash
+gem push rails_ui_guard-0.1.0.gem
+```
+
+## 📝 Using the Gem
+
+### From GitHub
+
+```ruby
+# Gemfile
+gem 'rails_ui_guard', git: 'https://github.com/KapilDevPal/Rails-Ui-Guard.git'
+```
+
+### From RubyGems (after publishing)
+
+```ruby
+# Gemfile
+gem 'rails_ui_guard'
+```
+
+### Installation
+
+```bash
+bundle install
+rails generate rails_ui_guard:install
+rails db:migrate
+```
+
+## ✨ Features Included
+
+- ✅ Complete gem structure
+- ✅ Rails Engine integration
+- ✅ Migration generator
+- ✅ Model concern for feature status
+- ✅ Controller helpers
+- ✅ View helpers
+- ✅ UI overlay partial
+- ✅ Status badges
+- ✅ Comprehensive README
+- ✅ MIT License
+- ✅ CHANGELOG
+- ✅ GitHub Actions CI (optional)
+
+## 📚 Documentation
+
+- **README.md** - Complete usage guide
+- **PUSH_TO_GITHUB.md** - Step-by-step GitHub push instructions
+- **CHANGELOG.md** - Version history
+
+## 🎉 Next Steps
+
+1. ✅ Review the gem structure
+2. ✅ Test building the gem
+3. ✅ Push to GitHub
+4. ✅ Test in a sample Rails app
+5. ✅ Publish to RubyGems (optional)
+6. ✅ Share with the community!
+
+---
+
+**Happy coding! 🚀**
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Kapil Dev Pal
+
+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/PUSH_TO_GITHUB.md

@@ -0,0 +1,90 @@
+# How to Push Rails UI Guard to GitHub
+
+## Step 1: Navigate to the gem directory
+
+```bash
+cd rails_ui_guard_gem
+```
+
+## Step 2: Initialize Git (if not already done)
+
+```bash
+git init
+git branch -M main
+```
+
+## Step 3: Add all files
+
+```bash
+git add .
+```
+
+## Step 4: Make initial commit
+
+```bash
+git commit -m "Initial commit: Rails UI Guard v0.1.0 - Feature locking and status management system for Rails"
+```
+
+## Step 5: Add GitHub remote
+
+```bash
+git remote add origin https://github.com/KapilDevPal/Rails-Ui-Guard.git
+```
+
+## Step 6: Push to GitHub
+
+```bash
+git push -u origin main
+```
+
+## Step 7: Build and test the gem locally
+
+```bash
+gem build rails_ui_guard.gemspec
+gem install rails_ui_guard-0.1.0.gem --local
+```
+
+## Step 8: Publish to RubyGems (optional)
+
+First, sign up at https://rubygems.org and get your API key.
+
+```bash
+gem push rails_ui_guard-0.1.0.gem
+```
+
+## Quick Setup Script
+
+You can also use the provided setup script:
+
+```bash
+./setup_gem.sh
+```
+
+Then follow the instructions it prints.
+
+## Using the Gem
+
+### From GitHub
+
+Add to your Gemfile:
+
+```ruby
+gem 'rails_ui_guard', git: 'https://github.com/KapilDevPal/Rails-Ui-Guard.git'
+```
+
+### From RubyGems (after publishing)
+
+Add to your Gemfile:
+
+```ruby
+gem 'rails_ui_guard'
+```
+
+Then:
+
+```bash
+bundle install
+rails generate rails_ui_guard:install
+rails db:migrate
+```
+

data/README.md

@@ -0,0 +1,243 @@
+# Rails UI Guard
+
+[![Gem Version](https://badge.fury.io/rb/rails_ui_guard.svg)](https://badge.fury.io/rb/rails_ui_guard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Feature locking and status management system for Rails multi-tenant applications.
+
+Rails UI Guard provides a clean way to lock/unlock features, show maintenance overlays, and enforce backend security for modules in multi-tenant Rails applications.
+
+## Features
+
+- ✅ **Per-tenant feature status management** (Active, Locked, Under Work)
+- ✅ **UI blur/overlay system** (no JavaScript required)
+- ✅ **Backend enforcement** for security
+- ✅ **Sidebar status badges** with icons
+- ✅ **Reusable view helpers and partials**
+- ✅ **Rails 6/7/8 compatible**
+- ✅ **Mobile-safe and accessible**
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_ui_guard', git: 'https://github.com/KapilDevPal/Rails-Ui-Guard.git'
+```
+
+Or if published to RubyGems:
+
+```ruby
+gem 'rails_ui_guard'
+```
+
+Then execute:
+
+```bash
+$ bundle install
+```
+
+Run the generator to create the migration and initializer:
+
+```bash
+$ rails generate rails_ui_guard:install
+$ rails db:migrate
+```
+
+## Quick Start
+
+### 1. Include in your model (e.g., School)
+
+```ruby
+class School < ApplicationRecord
+  include RailsUiGuard::FeatureStatusable
+  has_feature_status
+end
+```
+
+### 2. Include in ApplicationController
+
+```ruby
+class ApplicationController < ActionController::Base
+  include RailsUiGuard::ControllerHelpers
+end
+```
+
+### 3. Use in your controllers
+
+```ruby
+class FeesController < ApplicationController
+  before_action :set_current_school
+  before_action -> { enforce_feature_access("fee_management") }
+  
+  def index
+    @module_status = current_school.module_status("fee_management")
+    # ... rest of action
+  end
+end
+```
+
+### 4. Add to your layout
+
+```erb
+<!-- app/views/layouts/application.html.erb -->
+<%= render_module_overlay(@module_status) %>
+```
+
+### 5. Add status badges to sidebar (optional)
+
+```erb
+<!-- app/views/shared/_sidebar.html.erb -->
+<% feature_key = app_module.name.parameterize(separator: '_') %>
+<% module_status = current_school.module_status(feature_key) %>
+<%= rails_ui_guard_status_badge(module_status) %>
+```
+
+## Feature States
+
+### Active (`:active`)
+- Module is fully accessible and functional
+- No restrictions or overlays
+
+### Locked (`:locked`)
+- Module is not enabled for this tenant
+- Page content is blurred with lock overlay
+- All interactions blocked
+- Backend actions are blocked
+
+### Under Work (`:under_work`)
+- Module is temporarily unavailable (maintenance)
+- Page content is blurred with maintenance overlay
+- All interactions blocked
+- Backend actions are blocked
+
+## Usage Examples
+
+### Setting Feature Status
+
+```ruby
+# In Rails console or admin panel
+school = School.find_by(name: "Demo School")
+
+# Lock a feature
+school.set_feature_status("fee_management", :locked, 
+  message: "Fee Management is not available in your plan.",
+  help_text: "Contact sales@example.com to upgrade.")
+
+# Set to under work
+school.set_feature_status("fee_management", :under_work,
+  message: "Fee Management is under maintenance. Expected completion: 2:00 PM.")
+
+# Set to active
+school.set_feature_status("fee_management", :active)
+```
+
+### Checking Feature Status
+
+```ruby
+school.module_status("fee_management")  # => :active, :locked, or :under_work
+school.feature_active?("fee_management")  # => true/false
+school.feature_locked?("fee_management")  # => true/false
+school.feature_under_work?("fee_management")  # => true/false
+```
+
+### Controller Helpers
+
+```ruby
+# Set feature status (for overlay display)
+rails_ui_guard_set_feature!("fee_management")
+
+# Enforce active status (blocks non-active)
+rails_ui_guard_enforce_active!("fee_management")
+```
+
+### View Helpers
+
+```erb
+<!-- Status badge -->
+<%= rails_ui_guard_status_badge(module_status) %>
+
+<!-- Wrap content with blur/overlay -->
+<%= rails_ui_guard_wrap(status: @module_status, feature_key: "fee_management") do %>
+  <!-- Content here -->
+<% end %>
+
+<!-- Render overlay -->
+<%= render_module_overlay(@module_status) %>
+```
+
+## Active Admin Integration
+
+The gem includes an Active Admin resource for managing feature statuses. To use it, create:
+
+```ruby
+# app/admin/feature_statuses.rb
+ActiveAdmin.register RailsUiGuard::FeatureStatus, as: "FeatureStatus" do
+  menu label: "Module Lock & Status", priority: 5
+  
+  permit_params :statusable_type, :statusable_id, :feature_key, :status, :message, :help_text
+  
+  # ... rest of configuration
+end
+```
+
+See the [full documentation](https://github.com/KapilDevPal/Rails-Ui-Guard) for complete Active Admin setup.
+
+## Security
+
+⚠️ **Important**: The UI blur/overlay is **UX only**. Backend enforcement is **mandatory** and cannot be bypassed by disabling JavaScript or manipulating the DOM.
+
+Always use `enforce_feature_access` in your controllers:
+
+```ruby
+before_action -> { enforce_feature_access("fee_management") }
+```
+
+## Requirements
+
+- Ruby >= 2.7.0
+- Rails >= 6.0, < 9.0
+- ActiveRecord >= 6.0, < 9.0
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+$ bundle install
+$ rake test
+```
+
+To build and install the gem:
+
+```bash
+$ gem build rails_ui_guard.gemspec
+$ gem install rails_ui_guard-0.1.0.gem
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/KapilDevPal/Rails-Ui-Guard.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Author
+
+**Kapil Dev Pal**
+
+- GitHub: [@KapilDevPal](https://github.com/KapilDevPal)
+- Email: kapildevpal@gmail.com
+
+## Support
+
+For questions or issues:
+1. Check the [documentation](https://github.com/KapilDevPal/Rails-Ui-Guard)
+2. Open an [issue](https://github.com/KapilDevPal/Rails-Ui-Guard/issues)
+3. Contact the maintainer
+
+---
+
+Made with ❤️ for the Rails community
+

data/lib/generators/rails_ui_guard/install/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsUiGuard
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates Rails UI Guard migration and initializer"
+
+      def create_migration
+        migration_template(
+          "create_rails_ui_guard_feature_statuses.rb.erb",
+          "db/migrate/create_rails_ui_guard_feature_statuses.rb"
+        )
+      end
+
+      def create_initializer
+        copy_file "rails_ui_guard.rb", "config/initializers/rails_ui_guard.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end
+

data/lib/generators/rails_ui_guard/install/templates/README

@@ -0,0 +1,32 @@
+Rails UI Guard has been installed!
+
+Next steps:
+
+1. Run the migration:
+   rails db:migrate
+
+2. Include in your model (e.g., School):
+   class School < ApplicationRecord
+     include RailsUiGuard::FeatureStatusable
+     has_feature_status
+   end
+
+3. Include in ApplicationController:
+   class ApplicationController < ActionController::Base
+     include RailsUiGuard::ControllerHelpers
+   end
+
+4. Use in your controllers:
+   class FeesController < ApplicationController
+     before_action -> { enforce_feature_access("fee_management") }
+     
+     def index
+       @module_status = current_school.module_status("fee_management")
+     end
+   end
+
+5. Add to your layout (app/views/layouts/application.html.erb):
+   <%= render_module_overlay(@module_status) %>
+
+For complete documentation, see: https://github.com/KapilDevPal/Rails-Ui-Guard
+

data/lib/generators/rails_ui_guard/install/templates/create_rails_ui_guard_feature_statuses.rb.erb

@@ -0,0 +1,21 @@
+class CreateRailsUiGuardFeatureStatuses < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :rails_ui_guard_feature_statuses, id: :uuid do |t|
+      t.references :statusable, polymorphic: true, null: false, type: :uuid, index: true
+      t.string :feature_key, null: false
+      t.string :status, null: false, default: "active"
+      t.text :message
+      t.text :help_text
+
+      t.timestamps
+    end
+
+    add_index :rails_ui_guard_feature_statuses, 
+              [:statusable_type, :statusable_id, :feature_key], 
+              unique: true, 
+              name: "index_rails_ui_guard_feature_statuses_unique"
+    add_index :rails_ui_guard_feature_statuses, :feature_key
+    add_index :rails_ui_guard_feature_statuses, :status
+  end
+end
+

data/lib/generators/rails_ui_guard/install/templates/rails_ui_guard.rb

@@ -0,0 +1,6 @@
+# Load Rails UI Guard gem
+# This ensures the gem is loaded early in the Rails boot process
+if defined?(Rails)
+  require "rails_ui_guard"
+end
+

data/lib/rails_ui_guard/app/models/rails_ui_guard/feature_status.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RailsUiGuard
+  # DB-backed feature status record.
+  #
+  # This is the source of truth for per-tenant module/sub-module availability.
+  #
+  # - statusable: typically School (multi-tenant), but polymorphic for extensibility.
+  # - feature_key: stable string key for the module/submodule (e.g. "Fee Management" or "fees_module")
+  # - status: :active | :locked | :under_work (extensible)
+  class FeatureStatus < ::ApplicationRecord
+    self.table_name = "rails_ui_guard_feature_statuses"
+
+    belongs_to :statusable, polymorphic: true
+
+    validates :feature_key, presence: true
+    validates :status, presence: true
+    validates :feature_key, uniqueness: { scope: %i[statusable_type statusable_id] }
+
+    # Keep statuses as strings for easy future expansion without migrations.
+    STATUSES = %w[active locked under_work].freeze
+
+    validates :status, inclusion: { in: STATUSES }
+
+    def active?
+      status == "active"
+    end
+
+    def locked?
+      status == "locked"
+    end
+
+    def under_work?
+      status == "under_work"
+    end
+
+    def self.ransackable_attributes(_auth_object = nil)
+      %w[id statusable_type statusable_id feature_key status message help_text created_at updated_at]
+    end
+
+    def self.ransackable_associations(_auth_object = nil)
+      %w[statusable]
+    end
+  end
+end
+
+

data/lib/rails_ui_guard/app/views/rails_ui_guard/shared/_module_overlay.html.erb

@@ -0,0 +1,99 @@
+<%# Enhanced user-friendly overlay with lock details %>
+<%# This provides a transparent overlay with clear messaging when modules are locked or under maintenance %>
+
+<% 
+  status = module_status&.to_sym || :active
+  feature_key = feature_key&.to_s
+  
+  # Determine icon, title, and colors based on status
+  case status
+  when :locked
+    icon = "🔒"
+    title = "Module Locked"
+    bg_color = "bg-red-500"
+    text_color = "text-red-700"
+    border_color = "border-red-300"
+    icon_bg = "bg-red-100"
+  when :under_work
+    icon = "🚧"
+    title = "Under Maintenance"
+    bg_color = "bg-yellow-500"
+    text_color = "text-yellow-700"
+    border_color = "border-yellow-300"
+    icon_bg = "bg-yellow-100"
+  else
+    # Should not render if active, but just in case
+    return
+  end
+  
+  # Get custom message or use default
+  message = feature_status&.message.presence
+  if message.blank?
+    case status
+    when :locked
+      message = "This module is currently locked and not available for your school. Please contact your administrator for more information."
+    when :under_work
+      message = "This module is currently under maintenance. We're working hard to bring it back online soon. Please check back later."
+    else
+      message = "This module is currently unavailable."
+    end
+  end
+  help_text = feature_status&.help_text
+%>
+
+<div class="rails-ui-guard-overlay fixed inset-0 flex items-center justify-center z-[10000] pointer-events-auto" 
+     style="background: rgba(0, 0, 0, 0.6); backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px);">
+  <div class="rails-ui-guard-overlay-content bg-white rounded-2xl shadow-2xl max-w-md w-full mx-4 transform transition-all duration-300 scale-100 <%= border_color %> border-2">
+    <!-- Header with Icon -->
+    <div class="<%= bg_color %> rounded-t-xl px-6 py-4 flex items-center space-x-4">
+      <div class="<%= icon_bg %> rounded-full p-3 flex items-center justify-center">
+        <span class="text-3xl"><%= icon %></span>
+      </div>
+      <div class="flex-1">
+        <h2 class="text-xl font-bold text-white"><%= title %></h2>
+        <% if feature_key.present? %>
+          <p class="text-sm text-white opacity-90 mt-1">
+            <%= feature_key.humanize %>
+          </p>
+        <% end %>
+      </div>
+    </div>
+    
+    <!-- Content -->
+    <div class="px-6 py-6">
+      <div class="<%= text_color %> mb-4">
+        <p class="text-base leading-relaxed whitespace-pre-wrap"><%= message %></p>
+      </div>
+      
+      <% if help_text.present? %>
+        <div class="mt-4 pt-4 border-t border-gray-200">
+          <p class="text-sm text-gray-600 leading-relaxed whitespace-pre-wrap">
+            <strong class="text-gray-800">Need Help?</strong><br>
+            <%= help_text %>
+          </p>
+        </div>
+      <% end %>
+      
+      <!-- Action Buttons -->
+      <div class="mt-6 flex flex-col sm:flex-row gap-3">
+        <% if defined?(root_path) %>
+          <%= link_to root_path, 
+              class: "flex-1 px-4 py-2 bg-gray-100 hover:bg-gray-200 text-gray-700 rounded-lg font-medium text-center transition-colors duration-200" do %>
+            <i class="fas fa-home mr-2"></i>
+            Go to Dashboard
+          <% end %>
+        <% end %>
+        
+        <% if defined?(current_user) && (current_user&.respond_to?(:super_admin?) && current_user&.super_admin?) || (current_user&.respond_to?(:school_head?) && current_user&.school_head?) %>
+          <% if defined?(admin_feature_statuses_path) %>
+            <%= link_to admin_feature_statuses_path, 
+                class: "flex-1 px-4 py-2 #{bg_color} hover:opacity-90 text-white rounded-lg font-medium text-center transition-opacity duration-200" do %>
+              <i class="fas fa-cog mr-2"></i>
+              Manage Access
+            <% end %>
+          <% end %>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>

data/lib/rails_ui_guard/concerns/feature_statusable.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Concern to add feature status methods to models (e.g., School)
+# Provides module_status(feature_key) method that returns :active, :locked, or :under_work
+module RailsUiGuard::FeatureStatusable
+  extend ActiveSupport::Concern
+
+  # Returns the FeatureStatus record (if present) for a given feature_key.
+  # Useful for retrieving message/help_text in the UI overlay.
+  def feature_status_record(feature_key)
+    feature_key = feature_key.to_s
+    feature_statuses.find_by(feature_key: feature_key)
+  end
+
+  # Returns the status of a feature/module for this record
+  # @param feature_key [String, Symbol] The key identifying the feature/module
+  # @return [Symbol] :active, :locked, or :under_work
+  def module_status(feature_key)
+    feature_key = feature_key.to_s
+    
+    # Check if there's a feature_status record for this feature
+    status_record = feature_status_record(feature_key)
+    return status_record.status.to_sym if status_record
+    
+    # Fallback: Check module_access if it exists (backward compatibility)
+    if respond_to?(:module_accesses)
+      module_access = module_accesses.joins(:app_module).find_by(app_modules: { name: feature_key })
+      if module_access
+        return module_access.granted? ? :active : :locked
+      end
+    end
+    
+    # Default to active if no status is set
+    :active
+  end
+
+  # Check if a feature is active
+  def feature_active?(feature_key)
+    module_status(feature_key) == :active
+  end
+
+  # Check if a feature is locked
+  def feature_locked?(feature_key)
+    module_status(feature_key) == :locked
+  end
+
+  # Check if a feature is under work
+  def feature_under_work?(feature_key)
+    module_status(feature_key) == :under_work
+  end
+
+  # Set the status of a feature
+  def set_feature_status(feature_key, status, message: nil, help_text: nil)
+    status_record = feature_statuses.find_or_initialize_by(feature_key: feature_key.to_s)
+    status_record.status = status.to_s
+    status_record.message = message if message.present?
+    status_record.help_text = help_text if help_text.present?
+    status_record.save!
+  end
+
+  class_methods do
+    # Include this in your model to add feature status support
+    # Requires has_many :feature_statuses association
+    def has_feature_status
+      has_many :feature_statuses, 
+               class_name: 'RailsUiGuard::FeatureStatus',
+               dependent: :destroy,
+               as: :statusable
+    end
+  end
+end
+

data/lib/rails_ui_guard/controller_helpers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RailsUiGuard
+  # Controller helpers for enforcing feature/module access (backend security)
+  #
+  # Pattern:
+  #   class FeesController < ApplicationController
+  #     before_action -> { rails_ui_guard_set_feature!("Fee Management") }
+  #     before_action -> { rails_ui_guard_enforce_active!("Fee Management") }, only: [:create, :update, :destroy]
+  #   end
+  #
+  # Notes:
+  # - Read actions can render normally (UX overlay will blur/freeze if locked)
+  # - Write actions MUST be blocked server-side to prevent URL/API bypass
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :rails_ui_guard_current_school
+    end
+
+    # Override by defining `current_school` in ApplicationController (you already have this).
+    def rails_ui_guard_current_school
+      respond_to?(:current_school) ? current_school : nil
+    end
+
+    # Sets instance variables used by the layout overlay:
+    # - @feature_key
+    # - @module_status  (:active | :locked | :under_work | ...)
+    # - @feature_status_record (optional, provides message/help_text)
+    def rails_ui_guard_set_feature!(feature_key)
+      @feature_key = feature_key.to_s
+      school = rails_ui_guard_current_school
+
+      if school&.respond_to?(:module_status)
+        @module_status = school.module_status(@feature_key)
+        if school.respond_to?(:feature_status_record)
+          @feature_status_record = school.feature_status_record(@feature_key)
+        end
+      else
+        @module_status = :active
+        @feature_status_record = nil
+      end
+    end
+
+    # Backend enforcement: blocks non-active access for critical actions.
+    #
+    # - For HTML: redirect back (or to root) with a clear flash
+    # - For JSON: returns 403
+    def rails_ui_guard_enforce_active!(feature_key, redirect_to: nil)
+      school = rails_ui_guard_current_school
+      status = school&.respond_to?(:module_status) ? school.module_status(feature_key) : :active
+      return if status.to_sym == :active
+
+      message =
+        case status.to_sym
+        when :locked
+          "This feature is not enabled for your school."
+        when :under_work
+          "This feature is temporarily unavailable (maintenance/under work)."
+        else
+          "This feature is currently unavailable."
+        end
+
+      respond_to do |format|
+        format.html do
+          flash[:alert] = message
+          target = redirect_to || (request.referer.presence || main_app.root_path)
+          redirect_to target
+        end
+        format.json { render json: { error: message, feature_status: status }, status: :forbidden }
+        format.any  { head :forbidden }
+      end
+    end
+  end
+end
+
+

data/lib/rails_ui_guard/engine.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RailsUiGuard
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsUiGuard
+    engine_name "rails_ui_guard"
+
+    # Configure paths for views, models, and assets
+    config.autoload_paths << root.join("app", "models")
+    
+    paths["app/views"] = root.join("app", "views")
+    paths["app/models"] = root.join("app", "models")
+    paths["app/helpers"] = root.join("app", "helpers")
+    paths["app/assets"] = root.join("app", "assets")
+
+    # Load the FeatureStatus model after Rails is fully initialized
+    # This ensures ApplicationRecord is available
+    config.to_prepare do
+      require root.join("app", "models", "rails_ui_guard", "feature_status") unless defined?(RailsUiGuard::FeatureStatus)
+    end
+
+    # Make view helpers available globally
+    initializer "rails_ui_guard.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include RailsUiGuard::ViewHelpers
+      end
+    end
+
+    # Make controller helpers available and register view helpers
+    initializer "rails_ui_guard.controller_helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include RailsUiGuard::ControllerHelpers
+      end
+    end
+
+    # Register helpers so they're available in all views
+    initializer "rails_ui_guard.register_helpers" do
+      ActiveSupport.on_load(:action_controller) do
+        helper RailsUiGuard::ViewHelpers
+      end
+    end
+  end
+end
+
+

data/lib/rails_ui_guard/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RailsUiGuard
+  VERSION = "0.1.1"
+end
+

data/lib/rails_ui_guard/view_helpers.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RailsUiGuard
+  # View helpers for the blur + overlay UX.
+  #
+  # This is intentionally **no-JS**. The UI lock is UX only; backend enforcement
+  # must still be done with `rails_ui_guard_enforce_active!` for write actions.
+  module ViewHelpers
+    # Wrap arbitrary content with a blur/freeze overlay when status != :active.
+    #
+    # Usage (recommended in layout):
+    #
+    #   <%= rails_ui_guard_wrap(status: @module_status, feature_key: @feature_key, feature_status: @feature_status_record) do %>
+    #     <%= yield %>
+    #   <% end %>
+    #
+    def rails_ui_guard_wrap(status:, feature_key: nil, feature_status: nil, &block)
+      status = status&.to_sym
+      content = capture(&block)
+
+      return content if status.nil? || status == :active
+
+      blurred_classes = "rails-ui-guard-blur rails-ui-guard-opacity rails-ui-guard-block-pointer"
+      # `inert` prevents focus/keyboard interaction in modern browsers (no JS needed).
+      inert_attr = "inert"
+
+      safe_join(
+        [
+          content_tag(:div, class: "relative") do
+            safe_join(
+              [
+                content_tag(:div, content, class: blurred_classes, **{ inert: inert_attr }),
+                render(
+                  "rails_ui_guard/shared/module_overlay",
+                  module_status: status,
+                  feature_key: feature_key,
+                  feature_status: feature_status
+                )
+              ]
+            )
+          end
+        ]
+      )
+    end
+
+    # Optional: show lock/maintenance badge for menu items.
+    def rails_ui_guard_status_badge(status)
+      status = status&.to_sym
+      return "" if status.nil? || status == :active
+
+      label, classes, icon =
+        case status
+        when :locked
+          ["Locked", "bg-gray-700 text-gray-200", "🔒"]
+        when :under_work
+          ["Under Work", "bg-yellow-700 text-yellow-100", "🚧"]
+        else
+          ["Unavailable", "bg-red-700 text-red-100", "⚠️"]
+        end
+
+      content_tag(:span, class: "ml-auto flex items-center gap-1 text-[10px] px-2 py-0.5 rounded #{classes}") do
+        safe_join([
+          content_tag(:span, icon, class: "text-xs"),
+          content_tag(:span, label)
+        ])
+      end
+    end
+  end
+end
+
+

data/lib/rails_ui_guard.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# rails_ui_guard
+#
+# Feature locking and status management system for Rails multi-tenant applications.
+#
+# This gem provides:
+# - A DB-driven feature-status model (per-tenant)
+# - Controller guards (backend enforcement)
+# - View helpers + reusable overlay partial (UX blur/lock; no JS)
+#
+# See README.md for installation and usage instructions.
+
+require "active_support"
+
+# Ensure namespace exists even if files are loaded out-of-order.
+module RailsUiGuard
+end
+
+# Core pieces (required early so models can safely `include RailsUiGuard::...`)
+require_relative "rails_ui_guard/concerns/feature_statusable"
+require_relative "rails_ui_guard/app/models/rails_ui_guard/feature_status"
+
+require_relative "rails_ui_guard/version"
+require_relative "rails_ui_guard/controller_helpers"
+require_relative "rails_ui_guard/view_helpers"
+
+# Engine hooks views/helpers into the host app and configures autoloading
+require_relative "rails_ui_guard/engine" if defined?(Rails)
+

data/rails_ui_guard.gemspec

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_ui_guard/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rails_ui_guard"
+  spec.version       = RailsUiGuard::VERSION
+  spec.authors       = ["Kapil Dev Pal"]
+  spec.email         = ["kapildevpal@gmail.com"]
+
+  spec.summary       = "Feature locking and status management system for Rails multi-tenant applications"
+  spec.description   = <<~DESC
+    Rails UI Guard provides a clean way to lock/unlock features, show maintenance overlays, 
+    and enforce backend security for modules in multi-tenant Rails applications.
+    
+    Features:
+    - Per-tenant feature status management (Active, Locked, Under Work)
+    - UI blur/overlay system (no JavaScript required)
+    - Backend enforcement for security
+    - Sidebar status badges
+    - Reusable view helpers and partials
+    - Rails 6/7/8 compatible
+  DESC
+  spec.homepage      = "https://github.com/KapilDevPal/Rails-Ui-Guard"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}.git"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "false"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile Rakefile])
+    end
+  rescue
+    # If git is not available, include all files
+    Dir.glob("**/*", File::FNM_DOTMATCH).reject do |f|
+      File.directory?(f) || 
+      f.start_with?("bin/", "test/", "spec/", ".git", "Gemfile", "Rakefile") ||
+      f.end_with?(".gem")
+    end
+  end
+  
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 6.0", "< 9.0"
+  spec.add_dependency "activerecord", ">= 6.0", "< 9.0"
+end
+

data/setup_gem.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# Rails UI Guard Gem Setup Script
+# This script helps set up the gem for GitHub and RubyGems
+
+set -e
+
+echo "🚀 Setting up Rails UI Guard gem..."
+
+# Check if git is initialized
+if [ ! -d ".git" ]; then
+    echo "📦 Initializing git repository..."
+    git init
+    git branch -M main
+fi
+
+# Add all files
+echo "📝 Adding files to git..."
+git add .
+
+# Build the gem
+echo "🔨 Building gem..."
+gem build rails_ui_guard.gemspec
+
+echo "✅ Gem setup complete!"
+echo ""
+echo "Next steps:"
+echo "1. Review the gem: gem install rails_ui_guard-*.gem --local"
+echo "2. Add remote: git remote add origin https://github.com/KapilDevPal/Rails-Ui-Guard.git"
+echo "3. Commit: git commit -m 'Initial commit: Rails UI Guard v0.1.0'"
+echo "4. Push: git push -u origin main"
+echo "5. Publish to RubyGems: gem push rails_ui_guard-*.gem"
+

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: rails_ui_guard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kapil Dev Pal
-autorequire:
 bindir: exe
 cert_chain: []
 date: 2025-12-28 00:00:00.000000000 Z
@@ -60,7 +59,26 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- CHANGELOG.md
+- GEM_SETUP_COMPLETE.md
+- LICENSE.txt
+- PUSH_TO_GITHUB.md
+- README.md
+- lib/generators/rails_ui_guard/install/install_generator.rb
+- lib/generators/rails_ui_guard/install/templates/README
+- lib/generators/rails_ui_guard/install/templates/create_rails_ui_guard_feature_statuses.rb.erb
+- lib/generators/rails_ui_guard/install/templates/rails_ui_guard.rb
+- lib/rails_ui_guard.rb
+- lib/rails_ui_guard/app/models/rails_ui_guard/feature_status.rb
+- lib/rails_ui_guard/app/views/rails_ui_guard/shared/_module_overlay.html.erb
+- lib/rails_ui_guard/concerns/feature_statusable.rb
+- lib/rails_ui_guard/controller_helpers.rb
+- lib/rails_ui_guard/engine.rb
+- lib/rails_ui_guard/version.rb
+- lib/rails_ui_guard/view_helpers.rb
+- rails_ui_guard.gemspec
+- setup_gem.sh
 homepage: https://github.com/KapilDevPal/Rails-Ui-Guard
 licenses:
 - MIT
@@ -69,7 +87,6 @@ metadata:
   source_code_uri: https://github.com/KapilDevPal/Rails-Ui-Guard.git
   changelog_uri: https://github.com/KapilDevPal/Rails-Ui-Guard/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'false'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -84,8 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Feature locking and status management system for Rails multi-tenant applications
 test_files: []