js_admin 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b816de43bee7878c7eccf7acb2a158b304cbfbbb80bd65566329303fea76c0e2
-  data.tar.gz: 5c760edf388ea5dfc66985197ca48f99d79cfd4af9923635c98e4d93217856fc
+  metadata.gz: e58cee8e95f86b47a5487366c9bb11691c14ad57da5a8fbb5d9f3522b49c7372
+  data.tar.gz: e47f66d3d176de880706e7fd52deb86d03ba058bf63bc75b9d702ba4e20f0814
 SHA512:
-  metadata.gz: 753fd6b7de19253fc292b4f32654231cda74211c131a07080128cdd3290b9acd8229b3c7f320c5bb32a7248113bff3b04062cf4bbcfc1d4b5d39bcbbd6de57a3
-  data.tar.gz: 1b26bb7126e1404f1bd0d85f8ab6693eee2b94c029e9c0e4c0a5775d7b921af3e0d68407b22ba7c3e7c41fbb17e63852f6b83a43a9bc24972f46798a906279b0
+  metadata.gz: cd4ee8893dea3b7a19998cf43923919491a6b5fbbda3865b4efb2b127b7d3e851da0d790a9e3be30dceaa84e9b97990b1672c13db3a9c7621f484091f3f07ad4
+  data.tar.gz: 1c149b1cca178d1850fc1a78051d1b59af102d3323a4c38f57c93fd3952652cd37c1e0657bd65da3973b81ab3aaaf0f0da94ff6517e14d8e5846202c47df0d10

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.0 - 2026-07-18
+
+- Change the default mount path to `/admin`.
+- Add optional HTTP Basic Auth configuration.
+- Generate a commented `config/initializers/js_admin.rb` during installation.
+- Pin JSAdmin JavaScript through `importmap-rails` during installation.
+- Add sidebar model navigation with namespace grouping.
+- Use Turbo Frames, Turbo Streams, and Stimulus controllers for the admin shell.
+- Add fixed header/sidebar layout, dark mode support, and improved Tailwind UI spacing.
+- Add compact pagination controls and set the default page size to 10 records.
+- Add `View`, `Edit`, and `Delete` actions to resource tables.
+- Render form validation errors inline without Rails `field_with_errors` layout wrappers.
+- Add sandbox setup for browser testing with richer demo models and seed data.
+- Add AGENTS/CLAUDE project guidance files for LLM-assisted development.
+
 ## 0.0.1 - 2026-07-12
 
 - Initial release for RubyGems publishing test.

data/README.md

@@ -1,19 +1,20 @@
 # JSAdmin
 
-JSAdmin is a mountable Rails engine that exposes Active Record models through
-a generic CRUD UI. It discovers models from the host Rails application and builds
+JSAdmin is a mountable Rails engine that exposes Active Record models through a
+generic CRUD UI. It discovers models from the host Rails application and builds
 forms from database column metadata.
 
-> 2026-07-12 기준 RubyGems API에서 `js_admin`은 등록되지 않은 이름으로 확인했습니다. 공개 배포 직전에는 다시 한 번 점유 여부를 확인하세요.
+It is built for Rails 8.1+, Tailwind CSS, and Hotwire-compatible Rails helpers.
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "js_admin", path: "../js_admin"
+gem "js_admin"
 ```
 
-And then execute:
+Install and mount the engine:
 
 ```bash
 bundle install
@@ -21,31 +22,91 @@ bin/rails generate js_admin:install
 bin/rails tailwindcss:engines
 ```
 
-The install generator mounts the engine at `/js_admin` and imports the engine
-Tailwind entrypoint when `app/assets/tailwind/application.css` exists.
+The install generator mounts JSAdmin at `/admin`, pins JSAdmin's JavaScript in
+`config/importmap.rb`, and imports the engine Tailwind entrypoint when
+`app/assets/tailwind/application.css` exists. You can choose another mount path:
+
+```bash
+bin/rails generate js_admin:install --path=/backoffice
+bin/rails tailwindcss:engines
+```
+
+JSAdmin uses `importmap-rails` for JavaScript loading. Rails 8 default apps
+already include `config/importmap.rb`; if it was removed, run
+`bin/rails importmap:install` before running `js_admin:install`.
+
+The generator adds these pins when they are missing:
+
+```ruby
+pin "@hotwired/turbo-rails", to: "turbo.min.js"
+pin "@hotwired/stimulus", to: "stimulus.min.js"
+pin "js_admin", to: "js_admin/application.js", preload: true
+pin "js_admin/controllers/theme_controller", to: "js_admin/controllers/theme_controller.js", preload: true
+pin "js_admin/controllers/flash_controller", to: "js_admin/controllers/flash_controller.js", preload: true
+```
 
 ## Usage
 
-Open:
+Open the mounted path:
 
 ```text
-/js_admin
+/admin
 ```
 
-By default, JSAdmin lists every concrete Active Record model with an existing
-database table. No per-model field setup is required.
+The home page is intentionally empty. Model navigation lives in the sidebar.
+By default, JSAdmin exposes every concrete Active Record model with an existing
+database table. Namespaced models are grouped under namespace dropdowns. No
+per-model field setup is required.
+
+The UI includes a fixed header, fixed desktop sidebar, dark mode toggle, compact
+pagination controls, and inline form validation errors. The default page size is
+10 records.
+
+The install generator also creates `config/initializers/js_admin.rb` with
+commented configuration examples. JSAdmin works without changing that file.
+
+Available configuration options:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `included_models` | `[]` | Model names/classes to expose. Empty means every discovered concrete Active Record model. |
+| `excluded_models` | `[]` | Model names/classes to hide after discovery. |
+| `records_per_page` | `10` | Number of records shown per resource index page. |
+| `association_limit` | `100` | Maximum number of associated records loaded into a `belongs_to` select. |
+| `display_name_methods` | `%i[name title email username id]` | Methods tried in order when displaying records in tables and select labels. |
+| `basic_auth_username` | `nil` | HTTP Basic Auth username. Auth is disabled unless username and password are both present. |
+| `basic_auth_password` | `nil` | HTTP Basic Auth password. |
+| `basic_auth_realm` | `"JSAdmin"` | HTTP Basic Auth realm. |
 
-Optional model filtering:
+Example:
 
 ```ruby
 # config/initializers/js_admin.rb
 JSAdmin.configure do |config|
   config.include_models User, Post
   config.exclude_models AuditLog
-  config.records_per_page = 50
+  config.records_per_page = 10
 end
 ```
 
+## Authentication
+
+JSAdmin works without authentication unless Basic Auth credentials are
+configured. When both username and password are set, every JSAdmin request
+requires HTTP Basic Auth.
+
+```ruby
+# config/initializers/js_admin.rb
+JSAdmin.configure do |config|
+  config.basic_auth_username = ENV["JS_ADMIN_BASIC_AUTH_USERNAME"]
+  config.basic_auth_password = ENV["JS_ADMIN_BASIC_AUTH_PASSWORD"]
+  config.basic_auth_realm = "JSAdmin"
+end
+```
+
+For production apps, you can also mount JSAdmin inside the host application's
+admin authentication constraint when you need app-level authorization.
+
 ## Field Mapping
 
 JSAdmin maps database columns to inputs automatically:
@@ -63,14 +124,113 @@ JSAdmin maps database columns to inputs automatically:
 Primary keys, timestamps, STI inheritance columns, readonly attributes, and
 generated columns are not editable.
 
-## Security
+## Hotwire Scope
+
+JSAdmin depends on `importmap-rails`, `turbo-rails`, and `stimulus-rails` so it
+works naturally in modern Rails apps using the Rails default Hotwire setup.
+
+The admin shell keeps the header and sidebar stable while the main CRUD area is
+wrapped in a Turbo Frame. Sidebar navigation, resource links, forms, and
+pagination update that frame instead of replacing the whole page. Delete actions
+can respond with Turbo Streams to refresh the flash region and resource list.
+
+Stimulus controllers manage the dark mode toggle and auto-dismiss flash
+messages. The selected theme is persisted in storage and a cookie so the engine
+layout can render the initial dark class without inline JavaScript.
+
+## Validation Errors
+
+Form validation errors are rendered inside the form next to the matching field.
+JSAdmin renders form controls directly so Rails' default `field_with_errors`
+wrapper does not break the Tailwind grid layout. Errors that do not belong to an
+editable field are shown at the top of the form.
+
+## Development
+
+Run the test suite:
+
+```bash
+bundle install
+bundle exec rails test
+```
+
+Build the gem locally:
+
+```bash
+gem build js_admin.gemspec
+```
+
+### Dummy App
+
+This repository includes `test/dummy` as the Rails engine test app. It is used by
+the test suite and should stay small.
+
+You can run it manually for functional checks:
+
+```bash
+bin/rails db:prepare
+bin/rails server
+```
+
+Open:
+
+```text
+http://localhost:3000/admin
+```
+
+### Sandbox App
+
+Use `sandbox/` when you want to verify the real installation flow in a fresh
+Rails app. The sandbox directory is ignored by Git.
+
+Create a sandbox app wired to this local checkout:
+
+```bash
+bin/setup_sandbox
+```
+
+The setup script creates several demo models, including a namespaced model, seeds
+sample records, and runs an initial Tailwind build.
 
-Zero model configuration is convenient, but it is dangerous to expose without
-authentication. In production, mount the engine inside your app's admin
-authentication constraint.
+Run a one-off browser check:
 
-## Contributing
-Contribution directions go here.
+```bash
+cd sandbox
+bin/rails server
+```
+
+For iterative UI/CSS development, run the Rails server and Tailwind watcher
+together:
+
+```bash
+cd sandbox
+bin/dev
+```
+
+Open:
+
+```text
+http://localhost:3000/admin
+```
+
+Rebuild it from scratch:
+
+```bash
+rm -rf sandbox
+bin/setup_sandbox
+```
+
+## Release
+
+Releases are published to RubyGems through GitHub Actions and RubyGems Trusted
+Publishing. To release a new version, update `lib/js_admin/version.rb`, update
+`CHANGELOG.md`, and push a matching tag:
+
+```bash
+git tag v0.0.2
+git push origin v0.0.2
+```
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/javascripts/js_admin/application.js

@@ -0,0 +1,13 @@
+import "@hotwired/turbo-rails"
+import { Application } from "@hotwired/stimulus"
+import ThemeController from "js_admin/controllers/theme_controller"
+import FlashController from "js_admin/controllers/flash_controller"
+
+const application = window.Stimulus || window.JSAdminStimulus || Application.start()
+
+if (!window.Stimulus) {
+  window.JSAdminStimulus = application
+}
+
+application.register("js-admin-theme", ThemeController)
+application.register("js-admin-flash", FlashController)

data/app/assets/javascripts/js_admin/controllers/flash_controller.js

@@ -0,0 +1,23 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values = {
+    timeout: { type: Number, default: 4000 }
+  }
+
+  connect() {
+    this.timeoutId = window.setTimeout(() => this.dismiss(), this.timeoutValue)
+  }
+
+  disconnect() {
+    window.clearTimeout(this.timeoutId)
+  }
+
+  dismiss() {
+    this.element.classList.add("opacity-0", "translate-y-1")
+
+    window.setTimeout(() => {
+      this.element.remove()
+    }, 300)
+  }
+}

data/app/assets/javascripts/js_admin/controllers/theme_controller.js

@@ -0,0 +1,62 @@
+import { Controller } from "@hotwired/stimulus"
+
+const THEME_STORAGE_KEY = "js_admin_theme"
+const THEME_COOKIE_NAME = "js_admin_theme"
+const THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365
+
+export default class extends Controller {
+  static targets = ["toggle"]
+
+  connect() {
+    this.applyPreferredTheme()
+    this.syncToggle()
+  }
+
+  toggle() {
+    const enabled = !document.documentElement.classList.contains("dark")
+
+    document.documentElement.classList.toggle("dark", enabled)
+    this.persistTheme(enabled)
+    this.syncToggle()
+  }
+
+  syncToggle() {
+    if (!this.hasToggleTarget) return
+
+    this.toggleTarget.setAttribute("aria-pressed", document.documentElement.classList.contains("dark"))
+  }
+
+  persistTheme(enabled) {
+    const theme = enabled ? "dark" : "light"
+
+    try {
+      localStorage.setItem(THEME_STORAGE_KEY, theme)
+    } catch (_error) {
+    }
+
+    document.cookie = `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; SameSite=Lax`
+  }
+
+  applyPreferredTheme() {
+    const storedTheme = this.storedTheme()
+    const darkEnabled = storedTheme === "dark" || (!storedTheme && window.matchMedia("(prefers-color-scheme: dark)").matches)
+
+    document.documentElement.classList.toggle("dark", darkEnabled)
+  }
+
+  storedTheme() {
+    try {
+      return localStorage.getItem(THEME_STORAGE_KEY) || this.cookieTheme()
+    } catch (_error) {
+      return this.cookieTheme()
+    }
+  }
+
+  cookieTheme() {
+    const themeCookie = document.cookie
+      .split("; ")
+      .find((cookie) => cookie.startsWith(`${THEME_COOKIE_NAME}=`))
+
+    return themeCookie?.split("=")[1]
+  }
+}

data/app/assets/tailwind/js_admin/engine.css

@@ -1,4 +1,8 @@
 @import "tailwindcss";
 
+@custom-variant dark (&:where(.dark, .dark *));
+
+@source "../../../views/layouts/js_admin/**/*.erb";
 @source "../../../views/js_admin/**/*.erb";
 @source "../../../helpers/js_admin/**/*.rb";
+@source "../../../assets/javascripts/js_admin/**/*.js";

data/app/controllers/js_admin/application_controller.rb

@@ -1,4 +1,32 @@
+require "digest"
+
 module JSAdmin
   class ApplicationController < ActionController::Base
+    before_action :authenticate_basic_auth
+
+    private
+
+    def authenticate_basic_auth
+      return unless JSAdmin.configuration.basic_auth_enabled?
+
+      authenticate_or_request_with_http_basic(basic_auth_realm) do |username, password|
+        secure_compare(username, JSAdmin.configuration.basic_auth_username) &&
+          secure_compare(password, JSAdmin.configuration.basic_auth_password)
+      end
+    end
+
+    def basic_auth_realm
+      realm = JSAdmin.configuration.basic_auth_realm.to_s
+      return "JSAdmin" if realm.empty?
+
+      realm
+    end
+
+    def secure_compare(provided_value, expected_value)
+      ActiveSupport::SecurityUtils.secure_compare(
+        Digest::SHA256.hexdigest(provided_value.to_s),
+        Digest::SHA256.hexdigest(expected_value.to_s)
+      )
+    end
   end
 end

data/app/controllers/js_admin/home_controller.rb

@@ -0,0 +1,6 @@
+module JSAdmin
+  class HomeController < ApplicationController
+    def index
+    end
+  end
+end

data/app/controllers/js_admin/resources_controller.rb

@@ -4,9 +4,7 @@ module JSAdmin
     before_action :set_record, only: %i[show edit update destroy]
 
     def index
-      @page = [ params.fetch(:page, 1).to_i, 1 ].max
-      @records = @resource.records(page: @page)
-      @total_count = @resource.count
+      load_records
     end
 
     def show
@@ -39,7 +37,15 @@ module JSAdmin
 
     def destroy
       @record.destroy
-      redirect_to resources_path(@resource.model_id), notice: "#{@resource.singular_label} was deleted."
+      message = "#{@resource.singular_label} was deleted."
+
+      respond_to do |format|
+        format.turbo_stream do
+          flash.now[:notice] = message
+          load_records
+        end
+        format.html { redirect_to resources_path(@resource.model_id), notice: message }
+      end
     end
 
     private
@@ -52,6 +58,13 @@ module JSAdmin
       @record = @resource.find(params[:id])
     end
 
+    def load_records
+      @total_count = @resource.count
+      @total_pages = @resource.total_pages(total_count: @total_count)
+      @page = [ [ params.fetch(:page, 1).to_i, 1 ].max, @total_pages ].min
+      @records = @resource.records(page: @page)
+    end
+
     def resource_params
       params
         .fetch(@resource.param_key, ActionController::Parameters.new)