js_admin 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b816de43bee7878c7eccf7acb2a158b304cbfbbb80bd65566329303fea76c0e2
-  data.tar.gz: 5c760edf388ea5dfc66985197ca48f99d79cfd4af9923635c98e4d93217856fc
+  metadata.gz: bacbc059bd6ee6d36d9ad35c5fa86b8cb258b4d1fda939bf3bd98b269f74c7ea
+  data.tar.gz: ef27365d7d4d61abfb48a114bcd9a1eb3a5f569b943a2369951f12e4e78aef22
 SHA512:
-  metadata.gz: 753fd6b7de19253fc292b4f32654231cda74211c131a07080128cdd3290b9acd8229b3c7f320c5bb32a7248113bff3b04062cf4bbcfc1d4b5d39bcbbd6de57a3
-  data.tar.gz: 1b26bb7126e1404f1bd0d85f8ab6693eee2b94c029e9c0e4c0a5775d7b921af3e0d68407b22ba7c3e7c41fbb17e63852f6b83a43a9bc24972f46798a906279b0
+  metadata.gz: bccfe7a4bc553ff4581f6a31a4beb244fe47a39cec17a3d851b527ff74f8d2b3d8d12aa0e3f71a85ac74b2bbcd4bccddb919327cb8235c4688fa37483cc91973
+  data.tar.gz: 79370d4f7c372a9527924c0768f641109424b24c55fb42ef2f16011702f518b04560201c5b3c43c2200c860a60a447f1edf72ce542f33da2d53a3ab2af5a74aa

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.0 - 2026-10-18
+
+- Add host application authentication and authorization callbacks as an alternative to Basic Auth.
+- Reject conflicting or incomplete authentication configuration with localized errors.
+- Add English and Korean I18n translations for the JSAdmin interface.
+- Add `select_options` configuration to render a column as a select with static or callable choices.
+
+## 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,138 @@ 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.
 
-Optional model filtering:
+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. |
+| `field_select_options` | `{}` | Select choices by model and column. Register them with `select_options`. |
+| `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. |
+| `authenticate_with` | `nil` | Controller-context callback delegated to the host application's authentication. |
+| `authorize_with` | `nil` | Optional controller-context callback that returns whether the authenticated user may access JSAdmin. |
+
+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
+  config.select_options "Post", category: -> { Category.pluck(:name) }
+end
+```
+
+`select_options` renders the column as a select. Pass an array or a callable;
+callables are evaluated each time the form renders. Choices can be values or
+`[label, value]` pairs.
+
+## Authentication
+
+JSAdmin works without authentication unless Basic Auth credentials or an
+authentication callback are configured. Choose exactly one of the following
+authentication strategies.
+
+For HTTP Basic Auth, configure both username and password:
+
+```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
+```
+
+To delegate authentication to the host application, provide a callback instead.
+JSAdmin controllers inherit from the host application's `ApplicationController`,
+and the callback runs in the controller context:
+
+```ruby
+# config/initializers/js_admin.rb
+JSAdmin.configure do |config|
+  config.authenticate_with do
+    authenticate_user!
+  end
+
+  config.authorize_with do
+    current_user&.admin?
+  end
 end
 ```
 
+`authorize_with` is optional. When configured, returning `false` responds with
+`403 Forbidden`. Basic Auth and `authenticate_with` cannot be configured
+together. Partial Basic Auth credentials and `authorize_with` without
+`authenticate_with` also raise `JSAdmin::ConfigurationError`.
+
+For production apps, you can alternatively mount JSAdmin inside the host
+application's admin authentication constraint.
+
+## Internationalization
+
+JSAdmin follows the host application's `I18n.locale`.
+
+Supported locales:
+
+| Locale | Language |
+| --- | --- |
+| `en` | English |
+| `ko` | 한국어 |
+
+The translations cover the interface, CRUD notices, configuration errors, and
+generator messages. Host applications can override any key under the
+`js_admin` namespace.
+
 ## Field Mapping
 
 JSAdmin maps database columns to inputs automatically:
@@ -56,6 +164,7 @@ JSAdmin maps database columns to inputs automatically:
 | `boolean` | checkbox |
 | `integer`, `bigint`, `float`, `decimal` | number input |
 | `date`, `datetime`, `time` | matching date/time input |
+| `select_options` configured column | select |
 | Rails enum | select |
 | `belongs_to` foreign key | select |
 | other columns | text input |
@@ -63,14 +172,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.
 
-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.
+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.
 
-## Contributing
-Contribution directions go here.
+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.
+
+Run a one-off browser check:
+
+```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,48 @@
+require "digest"
+
 module JSAdmin
-  class ApplicationController < ActionController::Base
+  class ApplicationController < ::ApplicationController
+    before_action :authenticate_js_admin
+    before_action :authorize_js_admin
+
+    private
+
+    def authenticate_js_admin
+      case JSAdmin.configuration.authentication_strategy
+      when :basic_auth
+        authenticate_basic_auth
+      when :callback
+        instance_exec(&JSAdmin.configuration.authentication_callback)
+      end
+    end
+
+    def authenticate_basic_auth
+      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 authorize_js_admin
+      callback = JSAdmin.configuration.authorization_callback
+      return unless callback
+      return if instance_exec(&callback)
+
+      head :forbidden
+    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
@@ -20,7 +18,8 @@ module JSAdmin
       @record = @resource.new_record(resource_params)
 
       if @record.save
-        redirect_to resource_path(@resource.model_id, @record), notice: "#{@resource.singular_label} was created."
+        redirect_to resource_path(@resource.model_id, @record),
+                    notice: t("js_admin.resources.notices.created", resource: @resource.singular_label)
       else
         render :new, status: :unprocessable_entity
       end
@@ -31,7 +30,8 @@ module JSAdmin
 
     def update
       if @record.update(resource_params)
-        redirect_to resource_path(@resource.model_id, @record), notice: "#{@resource.singular_label} was updated."
+        redirect_to resource_path(@resource.model_id, @record),
+                    notice: t("js_admin.resources.notices.updated", resource: @resource.singular_label)
       else
         render :edit, status: :unprocessable_entity
       end
@@ -39,7 +39,15 @@ module JSAdmin
 
     def destroy
       @record.destroy
-      redirect_to resources_path(@resource.model_id), notice: "#{@resource.singular_label} was deleted."
+      message = t("js_admin.resources.notices.deleted", resource: @resource.singular_label)
+
+      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 +60,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)