achilles 0.1.2 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e608754044dbae7232ab87fd3a22fa03442f981eee6f049e2837cca1688db921
-  data.tar.gz: 536cf192f098d9fb27b40da3173b43229fc5f214d029707aae59bf5bef711e58
+  metadata.gz: e7490e9d3a5cb570991cffdc696869bc4db9910ad6811125f9b6f5e50939bf8f
+  data.tar.gz: 1cadeacf7fad25b4c22d5e061276928847de011e23ceac333935531906b1fef9
 SHA512:
-  metadata.gz: 5add5c1de1c4979cd42ed1718e72e635894b356b695901ad3e51b9577b37b557f78de7b0aebc5d74375ecb2c061afc37849466c5eecbcfe4ad21460cc9049828
-  data.tar.gz: 568fc4e820541696e7a42be31f4a2874eff8cccb76b82502aa4ccce4a5fd7c6f6bc15213a21cdaceae59174f799e305ebae4d6c7fc56aeba32212a534eedb3f9
+  metadata.gz: 801f4fbe6e267497ab2fda085bd36721f99cdde505616db473eef536517c9957789ed1fe956c6fa7361d94293dbd945d511aff96f772fb89f94a4966e2e27ad6
+  data.tar.gz: 0a8df7b78adb9516753e5b592551f3f76f6d0d06331d603d897e6efab627224e87ca97ed6704283979fc861102308aacb2bc389a91bc138de3c053dde7c60491

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to Achilles will be documented in this file.
+
+## 1.0.0.rc1
+
+### Added
+
+- Added `importmap-rails` as an explicit runtime dependency.
+- Added `rootNode()` as an alias for a component's DOM element.
+- Added Turbo teardown support through `turbo:before-render`.
+- Added JavaScript lifecycle behavior tests for parser, registry, Turbo hooks,
+  dynamic DOM insertion, setup idempotence, teardown idempotence, missing
+  elements, and root lookup.
+- Added GitHub Actions CI for Rails tests, JavaScript syntax checks, and dummy
+  app asset precompile.
+- Added v1 roadmap and migration documentation.
+
+### Changed
+
+- Replaced Achilles' internal jQuery usage with browser DOM APIs.
+- Updated README with real installation, usage, lifecycle, and contribution
+  instructions.
+- Fixed dummy app asset manifest linkage for asset precompile.
+- Removed deprecated Rails statistics rake task loading.
+
+### Breaking Changes
+
+- `rootElement()` now always returns the DOM element for the component id.
+- `rootElement()` no longer returns a jQuery object when `window.$` is present.
+- Applications that want jQuery should wrap the DOM element explicitly with
+  `$(this.rootElement())`.
+- Achilles internals are independent from jQuery.
+
+## 0.1.3
+
+Tagged as the last known pre-v1 baseline.

data/README.md

@@ -1,28 +1,111 @@
 # Achilles
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+Achilles is a small JavaScript lifecycle layer for Rails + Turbo applications.
+It is positioned as a simpler alternative to Stimulus for apps that prefer
+explicit component classes mapped to DOM nodes.
+
+Achilles scans the page for elements with `data-component-class`, instantiates
+the matching JavaScript class, and calls `setup` and `teardown` as Turbo renders
+new pages.
+
+## Requirements
+
+- Rails 7.0.2.3 or newer
+- Turbo Rails
+- Importmap Rails
 
 ## Installation
-Add this line to your application's Gemfile:
+
+Add Achilles to your application's Gemfile:
 
 ```ruby
 gem "achilles"
 ```
 
-And then execute:
+Then install:
+
 ```bash
-$ bundle
+bundle install
 ```
 
-Or install it yourself as:
-```bash
-$ gem install achilles
+## Usage
+
+Create one Achilles application instance and register your component classes:
+
+```js
+// app/javascript/application.js
+import { Application } from "achilles/application/application";
+import { CounterComponent } from "components/counter_component";
+
+const achilles = new Application();
+achilles.componentsClassMapper.addComponentClass("CounterComponent", CounterComponent);
+```
+
+Create components by extending `ComponentBase`:
+
+```js
+// app/javascript/components/counter_component.js
+import { ComponentBase } from "achilles/components/component_base";
+
+class CounterComponent extends ComponentBase {
+  setup() {
+    this.rootElement().addEventListener("click", this.increment);
+  }
+
+  teardown() {
+    this.rootElement().removeEventListener("click", this.increment);
+  }
+
+  increment = () => {
+    this.rootElement().textContent = Number(this.rootElement().textContent) + 1;
+  }
+}
+
+export { CounterComponent };
 ```
 
+Mark the component root in your view:
+
+```erb
+<button id="counter" data-component-class="CounterComponent">0</button>
+```
+
+Every component root must have a unique `id`. Achilles uses that id to register
+the component, find its root element, and avoid running setup twice for the same
+DOM node.
+
+## Lifecycle
+
+- `setup` runs after `turbo:load` and after new matching DOM nodes are inserted.
+- `teardown` runs before Turbo renders a new page.
+- `rootElement()` returns the DOM element for the component id.
+- `rootNode()` is an alias for `rootElement()`.
+- `rootElementSelector()` returns a CSS selector for the component id.
+
+## Timezone
+
+If the page includes an element with `data-app-timezone`, Achilles exposes the
+value through `achilles.timezone.timezoneString`.
+
+```erb
+<div data-app-timezone="<%= Time.zone.tzinfo.name %>"></div>
+```
+
+If no timezone is present, Achilles falls back to `Etc/UTC`.
+
 ## Contributing
-Contribution directions go here.
+
+Run the test suite with:
+
+```bash
+bin/rails test
+```
+
+## Migration
+
+Applications upgrading from `0.1.3` should read the
+[v1 migration guide](docs/migrating-from-0.1.3-to-v1.md).
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Achilles is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -3,6 +3,4 @@ require "bundler/setup"
 APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
-load "rails/tasks/statistics.rake"
-
 require "bundler/gem_tasks"

data/app/javascript/achilles/application/dom-mutation-observer/observer.js

@@ -13,7 +13,7 @@ class Observer {
 
   start() {
     // Listen on html instead of body since turbo replaces body and the observer stops after one page transition
-    this._mutationObserver.observe($('html')[0], this.config());
+    this._mutationObserver.observe(document.documentElement, this.config());
   }
 
   stop() {

data/app/javascript/achilles/application/hooks-manager/turbo.js

@@ -14,22 +14,13 @@ class Turbo {
   // Setups relevant hooks to the page for component lifecycles. This depends on the framework being used.
   // Here we are using turbo drive, so hooking into that.
   setupEvents() {
-    // Events registering
-    // Turbolinks lifecycle ref: https://sevos.io/2017/02/27/turbolinks-lifecycle-explained.html
-    // Render is not called on initial page load. So execute only once during page load
-    $(document).on("turbo:load", () => {
-      console.log('[achilles] turbo load event')
+    document.addEventListener("turbo:load", () => {
       this._setupCallback();
     });
 
-    // // Render is called before each page transition. But its not called on initial page load. That's why we need 'load'
-    // $(document).on("turbo:render", () => {
-    //   this._setupCallback();
-    // });
-    //
-    // $(document).on("turbo:before-render", () => {
-    //   this._teardownCallback();
-    // });
+    document.addEventListener("turbo:before-render", () => {
+      this._teardownCallback();
+    });
   }
 }
 

data/app/javascript/achilles/application/timezone/timezone.js

@@ -11,7 +11,7 @@ class Timezone {
   }
 
   getTimezoneFromHtml() {
-    this._timezoneString = $("div[data-app-timezone]").data("app-timezone") || "Etc/UTC";
+    this._timezoneString = document.querySelector("[data-app-timezone]")?.dataset.appTimezone || "Etc/UTC";
   }
 }
 

data/app/javascript/achilles/components/component_base.js

@@ -18,10 +18,18 @@ class ComponentBase {
     teardown() {}
 
     rootElement() {
-        return $(this.rootElementSelector());
+        return this.rootNode();
+    }
+
+    rootNode() {
+        return document.getElementById(this.id);
     }
 
     rootElementSelector() {
+        if(window.CSS && typeof window.CSS.escape === 'function') {
+            return `#${window.CSS.escape(this.id)}`;
+        }
+
         return `#${this.id}`;
     }
 }

data/app/javascript/achilles/components/component_parser.js

@@ -8,25 +8,25 @@ class ComponentParser {
     }
 
     parse() {
-        [...$('*[data-component-class]')].forEach((elem) => {
-            let klassName = $(elem).data('component-class');
+        [...document.querySelectorAll('[data-component-class]')].forEach((elem) => {
+            let klassName = elem.dataset.componentClass;
             if(klassName.trim() === '') { return; }
 
             let klass = this._componentsClassMapper.getComponentClass(klassName);
             if(typeof klass === 'undefined' || klass === null) {
                 console.error(`Component class not found: ${klassName} | Element:`);
-                console.error($(elem));
+                console.error(elem);
                 return;
             }
-            if($(elem).data('component-registered') === true) {
+            if(elem.dataset.componentRegistered === 'true') {
                 return;
             }
             try {
-                let obj = new klass($(elem).attr('id'), AppConstants.PageComponentId)
+                let obj = new klass(elem.id, AppConstants.PageComponentId)
                 this._componentRegistry.registerComponentByObj(obj);
             } catch (e) {
-                console.error(`Error parsing component. className: ${klassName} | Element ID: ${$(elem).attr('id')}`);
-                console.error($(elem));
+                console.error(`Error parsing component. className: ${klassName} | Element ID: ${elem.id}`);
+                console.error(elem);
                 console.error(e);
             }
         })

data/app/javascript/achilles/components/components_registry.js

@@ -4,12 +4,20 @@ import { AppConstants } from "achilles/application/app_constants";
 class ComponentsRegistry {
     _registeredComponents = {};
 
+    matchingElementsForId(id) {
+        return [...document.querySelectorAll('[id]')].filter((elem) => elem.id === id);
+    }
+
+    elementForId(id) {
+        return document.getElementById(id);
+    }
+
     registerComponentByObj(obj) {
         this.registerComponent(obj.id, obj, obj.defaultParams, obj.parentComponentId);
     }
 
     registerComponent(id, obj, defaultParams, parentComponentId) {
-        if($(`[id=${id}]`).length > 1) {
+        if(this.matchingElementsForId(id).length > 1) {
             console.error(`Error while registering component: There are more than one elements with the same id: ${id}. Skipping registering component`);
             return;
         }
@@ -29,7 +37,7 @@ class ComponentsRegistry {
             let parentComponent = this.getRegisteredComponent(parentComponentId);
             parentComponent.subComponents.push(id);
         }
-        $(`#${id}`).attr('data-component-registered', 'true');
+        this.elementForId(id)?.setAttribute('data-component-registered', 'true');
     }
 
     deregisterComponent(id) {
@@ -44,7 +52,7 @@ class ComponentsRegistry {
         }
 
         this._registeredComponents[id] = null;
-        $(`#${id}`).removeAttr('data-component-registered');
+        this.elementForId(id)?.removeAttribute('data-component-registered');
     }
 
     getRegisteredComponent(id) {
@@ -55,7 +63,7 @@ class ComponentsRegistry {
         let component = this.getRegisteredComponent(id);
         if(!component || !component.obj)
             return;
-        if(id !== AppConstants.PageComponentId && $('#' + id).length === 0) {
+        if(id !== AppConstants.PageComponentId && this.elementForId(id) === null) {
             this.elementNotFound(id);
             return;
         }

data/docs/migrating-from-0.1.3-to-v1.md

@@ -0,0 +1,120 @@
+# Migrating From 0.1.3 To v1
+
+This guide is for applications already using Achilles `0.1.3`.
+
+The recommended path is to first adopt the compatibility release, then test the
+v1 release candidate in one real application before upgrading every app.
+
+## Upgrade Strategy
+
+1. Upgrade one application at a time.
+2. Run the app locally with Turbo navigation enabled.
+3. Visit pages with Achilles components.
+4. Watch the browser console for missing component classes, duplicate ids, and
+   lifecycle errors.
+5. Verify that components still clean up event listeners on navigation.
+6. Repeat the same checks after dynamically inserting component markup.
+
+## Compatibility Release Checklist
+
+These changes should be safe for existing `0.1.3` applications:
+
+- `importmap-rails` is declared as an Achilles dependency.
+- Achilles calls `teardown()` before Turbo renders a new page.
+- Achilles internals no longer require jQuery.
+- `rootNode()` is available for new code.
+- `rootElement()` returns the component's DOM element in v1.
+
+Use the compatibility release to review component code that expects
+`rootElement()` to return a jQuery object.
+
+## v1 Breaking API Direction
+
+In v1, component code should use DOM APIs:
+
+```js
+class MenuComponent extends ComponentBase {
+  setup() {
+    this.rootElement().addEventListener("click", this.toggle);
+  }
+
+  teardown() {
+    this.rootElement().removeEventListener("click", this.toggle);
+  }
+
+  toggle = () => {
+    this.rootElement().classList.toggle("is-open");
+  }
+}
+```
+
+Avoid relying on `rootElement()` returning a jQuery object:
+
+```js
+// Old style
+this.rootElement().addClass("is-open");
+
+// v1 style
+this.rootElement().classList.add("is-open");
+```
+
+If an application still wants to use jQuery inside its own component code, keep
+that dependency in the application and wrap `rootElement()` explicitly:
+
+```js
+$(this.rootElement()).addClass("is-open");
+```
+
+## Component Markup
+
+Every Achilles component root must have a unique `id` and a
+`data-component-class` value that matches a registered component class:
+
+```erb
+<div id="account-menu" data-component-class="MenuComponent"></div>
+```
+
+Duplicate ids are invalid HTML and Achilles will skip registering those
+components.
+
+## Lifecycle Changes To Verify
+
+Achilles calls:
+
+- `setup()` after `turbo:load`
+- `setup()` when matching component markup is inserted dynamically
+- `teardown()` before Turbo renders a new page
+
+Review every component for setup work that must be undone in teardown:
+
+- event listeners
+- timers
+- observers
+- third-party widgets
+- subscriptions
+- global document/window handlers
+
+## Search Checklist
+
+In each application, search for:
+
+```bash
+rg "rootElement\\("
+rg "\\$\\(this\\.root"
+rg "data-component-class"
+```
+
+Convert jQuery-style `rootElement()` usage to DOM APIs or explicit jQuery
+wrapping before testing v1.
+
+## When To Test v1.0.0.rc1
+
+Test the release candidate after:
+
+- the application passes its own test suite
+- all obvious `rootElement()` usages have been reviewed
+- pages with Achilles components work across Turbo navigation
+- dynamic components are verified manually or by system tests
+
+Do not upgrade every application at once. Test one representative app first,
+then move the rest after the migration path is proven.

data/docs/release-checklist.md

@@ -0,0 +1,73 @@
+# Release Checklist
+
+Use this checklist for `1.0.0.rc1` and future releases.
+
+## Before Building
+
+- Confirm `lib/achilles/version.rb` has the intended version.
+- Confirm `CHANGELOG.md` has an entry for the intended version.
+- Confirm CI is green on GitHub.
+- Run the local verification commands:
+
+```bash
+bin/rails test
+for file in $(find app/javascript/achilles -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+RAILS_ENV=test bin/rails app:assets:precompile
+```
+
+## Build The Gem
+
+```bash
+gem build achilles.gemspec
+```
+
+Confirm the generated gem name matches the intended version:
+
+```bash
+ls achilles-*.gem
+```
+
+## Test In A Real Application
+
+In one application that currently uses Achilles `0.1.3`, point the Gemfile to
+the local checkout or install the built prerelease gem.
+
+Check:
+
+- app boot
+- importmap rendering
+- pages with Achilles components
+- Turbo navigation between pages
+- dynamic component insertion
+- browser console errors
+- components that use `rootElement()`
+- components that attach window, document, timer, observer, or third-party
+  widget state
+
+For v1, `rootElement()` returns a DOM element. If a component expects a jQuery
+object, update it to use DOM APIs or wrap explicitly with
+`$(this.rootElement())`.
+
+## Publish A Prerelease
+
+Only publish `1.0.0.rc1` after local checks and GitHub CI pass.
+
+```bash
+gem push achilles-1.0.0.rc1.gem
+git tag v1.0.0.rc1
+git push origin v1.0.0.rc1
+```
+
+## Publish Final v1.0.0
+
+Publish final `1.0.0` only after at least one real application has successfully
+tested the release candidate.
+
+Before final release:
+
+- update `lib/achilles/version.rb` to `1.0.0`
+- update `CHANGELOG.md` from `1.0.0.rc1` to `1.0.0`
+- run all local checks
+- confirm GitHub CI is green
+- build and push `achilles-1.0.0.gem`
+- tag `v1.0.0`

data/docs/v1-roadmap.md

@@ -0,0 +1,68 @@
+# Achilles v1 Roadmap
+
+This document tracks the work needed before publishing Achilles `1.0.0`.
+The goal is a stable open source release that is safe to evaluate in real Rails
+applications, even if it intentionally removes legacy behavior from the `0.x`
+line.
+
+## Product Direction
+
+Achilles is a small JavaScript lifecycle layer for Rails + Turbo applications.
+It gives teams explicit component classes mapped to DOM nodes without requiring
+Stimulus controller conventions or a JavaScript build step.
+
+## v1 Public API
+
+The v1 API should be small and documented:
+
+- `Application`
+- `ComponentBase`
+- `ComponentsClassMapper`
+- DOM discovery through `data-component-class`
+- component root lookup through `rootElement()`
+- `rootNode()` as an alias for `rootElement()`
+- CSS selector lookup through `rootElementSelector()`
+- lifecycle hooks: `setup()` and `teardown()`
+- Turbo integration through `turbo:load` and `turbo:before-render`
+
+## Planned Breaking Changes
+
+- Make `rootElement()` return the component's DOM element.
+- Keep `rootNode()` as an alias for `rootElement()`.
+- Remove the jQuery return behavior from `rootElement()`.
+- Keep Achilles internals independent from jQuery.
+- Require every component root to have a unique `id`.
+- Treat setup and teardown as idempotent lifecycle operations managed by
+  Achilles.
+
+## Release Gates
+
+Do not publish `1.0.0` until these are true:
+
+- Rails test suite passes.
+- JavaScript lifecycle tests cover parser, registry, Turbo hooks, root lookup,
+  setup idempotence, teardown idempotence, missing elements, and dynamic DOM
+  insertion.
+- Dummy app asset precompile passes.
+- README includes install, usage, lifecycle, dynamic DOM, migration, and API
+  reference sections.
+- `CHANGELOG.md` documents all breaking changes from `0.1.3`.
+- CI runs tests on supported Ruby and Rails versions.
+- At least one real application has tested the release candidate.
+
+## Release Plan
+
+1. Publish a compatibility release in the `0.x` line with dependency and
+   lifecycle fixes.
+2. Create a `v1.0.0.rc1` prerelease after the v1 API and tests are complete.
+3. Test `v1.0.0.rc1` in existing applications.
+4. Publish `1.0.0` only after the migration guide and real-app testing are done.
+
+Follow the [release checklist](release-checklist.md) when building and testing
+release candidates.
+
+## Current Recommendation
+
+Do not push `v1.0.0` yet. The project is ready for a compatibility release, but
+`1.0.0` should wait for the final v1 API cleanup and real-application testing
+through a release candidate.

data/lib/achilles/version.rb

@@ -1,3 +1,3 @@
 module Achilles
-  VERSION = "0.1.2"
+  VERSION = "1.0.0.rc1"
 end

data/lib/achilles.rb

@@ -1,4 +1,5 @@
 require "achilles/version"
+require "importmap-rails"
 require "achilles/engine"
 
 module Achilles

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: achilles
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Jey Geethan
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,13 +23,43 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 7.0.2.3
-description: A simple js library to make your turbo apps work better
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.11
+description: A small JavaScript lifecycle layer for Rails and Turbo applications,
+  positioned as an explicit component-class alternative to Stimulus.
 email:
 - jey@jeygeethan.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -54,6 +83,9 @@ files:
 - app/views/layouts/achilles/application.html.erb
 - config/importmap.rb
 - config/routes.rb
+- docs/migrating-from-0.1.3-to-v1.md
+- docs/release-checklist.md
+- docs/v1-roadmap.md
 - lib/achilles.rb
 - lib/achilles/engine.rb
 - lib/achilles/version.rb
@@ -63,10 +95,8 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/RocketApex/achilles
   source_code_uri: https://github.com/RocketApex/achilles
-  changelog_uri: https://github.com/RocketApex/achilles
-post_install_message:
+  changelog_uri: https://github.com/RocketApex/achilles/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -74,15 +104,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 4.0.11
 specification_version: 4
-summary: Js library as an alternative to stimulus
+summary: JavaScript component lifecycle for Rails and Turbo apps
 test_files: []