achilles 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d393e3c7e9d04d6a472ba4e41c727fffca5fa3088f5d064a08a0f9cd4b2bfcf2
-  data.tar.gz: 911efcf9ddc72755b3b26b9a8ae3d0a5538d4d33ba2f8476d6c4ae4c8aa54e8e
+  metadata.gz: b4d4c63799a2a26d7d7a819ec2e17559de59d80be593e5b28d2cc6445864ccda
+  data.tar.gz: 8fe623f377d068436dc08beed221ad293ed85159a46930aa5868e24aece5a1ca
 SHA512:
-  metadata.gz: a480a6ca6a9b154cdf723aa53560a1caa2a82f41f569a3e2d79dafbd80e50d1dea7a9c9b18d29f69c8eb9d693af79b358929929b9842a014645eaf939105dea5
-  data.tar.gz: 52f50f6c02b169e7d592363571da480961aa6ac52a856aaca72dc3f26f4e5c557e9b5c918e24f18bdfec6d5d37685936e49678e093ea182d4dc8730bad6d898c
+  metadata.gz: 5a1b4835b8cc60697ac3eb8d44e23c8799f76fa0d82f9a481b6a1a8cbdfe77373b91e1443dfcb62b6d733430bae427cd5bf624b3390f8a4f59ce5c632e223292
+  data.tar.gz: f6eed0197de6d71b6c74f4dfedf63920207f798fd4260a1d22076d7459587624fa2aa3d6fa88dc51d90fbe3be2735b687265122eb1222a67cfe25d9a94960f66

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to Achilles will be documented in this file.
 
+## 1.1.2
+
+### Fixed
+
+- Fixed Turbo Frame rendering so registered components in the outgoing frame are
+  torn down and deregistered immediately before Turbo invokes the frame renderer.
+
+## 1.1.1
+
+### Fixed
+
+- Fixed Turbo browser history restoration so components restored from cached DOM
+  are registered and set up again when their registry entries were already
+  removed.
+- Fixed component subtree deregistration so child components are removed with
+  their parent and cannot block later re-registration.
+- Added browser system coverage for back, forward, restored nested components,
+  restored form-field listeners, Turbo-replaced form restoration, and duplicate
+  listener prevention.
+
 ## 1.1.0
 
 ### Added

data/README.md

@@ -8,6 +8,11 @@ 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 or new component markup is inserted.
 
+Current applications should use Achilles `1.1.2`. If you are upgrading an
+existing app, start with the [1.1.0 upgrade guide](docs/upgrading-to-1.1.0.md)
+and then read the [1.1.1](docs/releases/v1.1.1.md) and
+[1.1.2](docs/releases/v1.1.2.md) release notes.
+
 ## Why Achilles?
 
 Rails and Turbo make server-rendered interfaces productive, but many apps still
@@ -79,6 +84,9 @@ achilles.componentsClassMapper.addComponentClass("CounterComponent", CounterComp
 achilles.start();
 ```
 
+Call `start()` after registering component classes. Achilles parses the current
+page and attaches Turbo lifecycle hooks when the application starts.
+
 Create components by extending `ComponentBase`:
 
 ```js
@@ -108,9 +116,10 @@ Mark the component root in your view:
 <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.
+Every component root must have a non-empty unique `id`. Achilles uses that id to
+register the component, find its root element, and avoid running setup twice for
+the same DOM node. Components without ids are skipped and reported in the browser
+console.
 
 ## Dynamic Components
 
@@ -148,6 +157,26 @@ Register the component class once:
 achilles.componentsClassMapper.addComponentClass("NotificationComponent", NotificationComponent);
 ```
 
+## Nested Components
+
+Achilles keeps a component tree rooted at a single synthetic `Page` component.
+A component's parent is its nearest ancestor element with `data-component-class`.
+If there is no component ancestor, its parent is `Page`.
+
+```erb
+<div id="dashboard" data-component-class="DashboardComponent">
+  <div id="filters" data-component-class="FiltersComponent"></div>
+</div>
+```
+
+This creates the following component tree:
+
+```text
+Page
+dashboard
+filters
+```
+
 ## Example App
 
 The dummy Rails app includes a working counter component. See
@@ -157,9 +186,21 @@ The dummy Rails app includes a working counter component. See
 
 - `setup()` runs after `turbo:load` and after new matching DOM nodes are inserted.
 - `teardown()` runs before Turbo renders a new page.
+- Before Turbo renders replacement content in a frame, Achilles tears down and
+  deregisters registered components in the outgoing frame from children to
+  parents.
 - `setup()` and `teardown()` are called once per registered component instance.
+- Parent components are set up before their children.
+- Child components are torn down before their parents.
 - Components that attach listeners, timers, observers, subscriptions, or widgets
   should clean them up in `teardown()`.
+- Lifecycle errors are logged and swallowed by default so one broken component
+  does not stop the page. Enable strict mode in tests or development when errors
+  should be re-raised:
+
+```js
+achilles.strictLifecycleErrors = true;
+```
 
 ## API Reference
 
@@ -178,6 +219,7 @@ Useful properties:
 
 - `componentsClassMapper`: register component classes by name.
 - `componentRegistry`: inspect or manage registered component instances.
+- `strictLifecycleErrors`: re-raise lifecycle errors after logging them.
 - `timezone`: access the configured app timezone.
 
 Call `start()` after registering component classes. Call `stop()` when an
@@ -219,7 +261,9 @@ Useful methods:
 ```
 
 The `data-component-class` value must match a class registered with
-`componentsClassMapper`.
+`componentsClassMapper`. The element must also have a non-empty unique `id`.
+Nested components are parented by DOM ancestry, with top-level components
+parented by the synthetic `Page` component.
 
 ## Timezone
 
@@ -232,6 +276,13 @@ value through `achilles.timezone.timezoneString`.
 
 If no timezone is present, Achilles falls back to `Etc/UTC`.
 
+## Upgrading
+
+Applications upgrading to `1.1.0` should read the
+[1.1.0 upgrade guide](docs/upgrading-to-1.1.0.md). The complete upgrade index
+lives in [docs/upgrading.md](docs/upgrading.md), and the current release note is
+available at [docs/releases/v1.1.2.md](docs/releases/v1.1.2.md).
+
 ## Upgrading From 0.1.3
 
 Achilles `1.0.0` changes `rootElement()` to return a DOM element. It no longer
@@ -255,9 +306,8 @@ Or wrap explicitly if the application still uses jQuery:
 $(this.rootElement()).addClass("is-open");
 ```
 
-Applications upgrading Achilles should start with the
-[upgrade guide](docs/upgrading.md). Applications upgrading from `0.1.3` should
-also read the [v1 migration guide](docs/migrating-from-0.1.3-to-v1.md).
+Applications upgrading from `0.1.3` should also read the
+[v1 migration guide](docs/migrating-from-0.1.3-to-v1.md).
 
 ## Contributing
 

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

@@ -117,8 +117,8 @@ class Application {
   }
 
   deregisterAllComponentsExceptPage() {
-    let pageComponent = this.componentRegistry.getRegisteredComponent(AppConstants.PageComponentId)
-    pageComponent.subComponents.forEach((subComponentId) => {
+    let pageComponent = this.componentRegistry.getRegisteredComponent(AppConstants.PageComponentId);
+    [...pageComponent.subComponents].forEach((subComponentId) => {
       this.componentRegistry.deregisterComponent(subComponentId);
     })
   }

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

@@ -4,6 +4,7 @@ class Turbo {
   _teardownCallback;
   _setupHandler;
   _teardownHandler;
+  _frameRenderHandler;
   _started = false;
 
   constructor(application, setupCallback, teardownCallback) {
@@ -27,8 +28,24 @@ class Turbo {
       this._teardownCallback();
     };
 
+    this._frameRenderHandler = (event) => {
+      const frame = event.target;
+      const originalRender = event.detail?.render;
+
+      if (!frame || typeof originalRender !== "function") {
+        return;
+      }
+
+      const componentRegistry = this._application.componentRegistry;
+      event.detail.render = function(...args) {
+        componentRegistry.teardownAndDeregisterWithin(frame);
+        return Reflect.apply(originalRender, this, args);
+      };
+    };
+
     document.addEventListener("turbo:load", this._setupHandler);
     document.addEventListener("turbo:before-render", this._teardownHandler);
+    document.addEventListener("turbo:before-frame-render", this._frameRenderHandler);
     this._started = true;
   }
 
@@ -39,8 +56,10 @@ class Turbo {
 
     document.removeEventListener("turbo:load", this._setupHandler);
     document.removeEventListener("turbo:before-render", this._teardownHandler);
+    document.removeEventListener("turbo:before-frame-render", this._frameRenderHandler);
     this._setupHandler = null;
     this._teardownHandler = null;
+    this._frameRenderHandler = null;
     this._started = false;
   }
 }

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

@@ -22,7 +22,7 @@ class ComponentParser {
                 console.error(elem);
                 return;
             }
-            if(elem.dataset.componentRegistered === 'true') {
+            if(elem.dataset.componentRegistered === 'true' && this._componentRegistry.getRegisteredComponent(elem.id)) {
                 return;
             }
             try {

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

@@ -53,6 +53,10 @@ class ComponentsRegistry {
         if(!component)
             return;
 
+        [...component.subComponents].forEach((subComponentId) => {
+            this.deregisterComponent(subComponentId);
+        });
+
         let parentComponent = this.getRegisteredComponent(component.parentComponentId);
 
         if(parentComponent != null){
@@ -126,6 +130,39 @@ class ComponentsRegistry {
         this.deregisterComponent(id);
     }
 
+    teardownAndDeregisterWithin(rootElement) {
+        if(!rootElement || typeof rootElement.contains !== 'function')
+            return;
+
+        Object.values(this._registeredComponents)
+            .filter((component) => {
+                if(component.id === AppConstants.PageComponentId)
+                    return false;
+
+                let element = this.elementForId(component.id);
+                return element && rootElement.contains(element);
+            })
+            .sort((firstComponent, secondComponent) => {
+                return this.elementDepth(secondComponent.id) - this.elementDepth(firstComponent.id);
+            })
+            .forEach((component) => {
+                if(this.getRegisteredComponent(component.id))
+                    this.teardownAndDeregister(component.id);
+            });
+    }
+
+    elementDepth(id) {
+        let depth = 0;
+        let element = this.elementForId(id);
+
+        while(element?.parentElement) {
+            depth += 1;
+            element = element.parentElement;
+        }
+
+        return depth;
+    }
+
     elementNotFound(id) {
         console.error('Cannot find element while setup, so teardown & deregister. id: ' + id);
         this.teardownAndDeregister(id);

data/docs/release-checklist.md

@@ -1,18 +1,29 @@
 # Release Checklist
 
-Use this checklist for `1.0.0.rc1` and future releases.
+Use this checklist for every Achilles release. Replace `VERSION` with the
+version being prepared, for example `1.1.0`.
 
-## Before Building
+## Before Finalizing The Version
 
+- Confirm the release type: patch, minor, major, or prerelease.
 - Confirm `lib/achilles/version.rb` has the intended version.
 - Confirm `CHANGELOG.md` has an entry for the intended version.
+- Confirm application-facing changes have an upgrade note in `docs/upgrading.md`.
+- Confirm release notes exist in `docs/releases/` when the release needs a
+  GitHub release body.
+- Confirm package file expectations are covered by `test/gemspec_files_test.rb`
+  when adding source or documentation files.
+
+## Before Building
+
 - Confirm CI is green on GitHub.
 - Run the local verification commands:
 
 ```bash
 bin/rails test
+node --test test/javascript/*_test.mjs
+for file in $(rg --files app/javascript/achilles test/dummy/app/javascript test/javascript | rg "\.(js|mjs)$"); do node --input-type=module --check < "$file" || exit 1; done
 bin/rails test:system
-for file in $(find app/javascript/achilles test/dummy/app/javascript -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
 RAILS_ENV=test bin/rails app:assets:precompile
 ```
 
@@ -25,13 +36,13 @@ gem build achilles.gemspec
 Confirm the generated gem name matches the intended version:
 
 ```bash
-ls achilles-*.gem
+ls achilles-VERSION.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.
+Before a broad rollout, test the built gem in at least one real Rails + Turbo
+application that already uses Achilles.
 
 Check:
 
@@ -45,30 +56,37 @@ Check:
 - 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())`.
+For releases with breaking or compatibility-sensitive behavior, test one app
+first, then roll out to the rest of the maintained apps gradually.
 
 ## Publish A Prerelease
 
-Only publish `1.0.0.rc1` after local checks and GitHub CI pass.
+Publish a prerelease only when the release needs real-app validation before a
+final tag.
 
 ```bash
-gem push achilles-1.0.0.rc1.gem
-git tag v1.0.0.rc1
-git push origin v1.0.0.rc1
+git tag vVERSION
+git push origin vVERSION
+gem push achilles-VERSION.gem
 ```
 
-## Publish Final v1.0.0
+Mark the GitHub release as a prerelease and include the matching release notes.
 
-Publish final `1.0.0` only after at least one real application has successfully
-tested the release candidate.
+## Publish A Final Release
+
+Publish a final release after local checks, GitHub CI, packaging verification,
+and real-app testing are complete.
+
+```bash
+git tag vVERSION
+git push origin vVERSION
+gem push achilles-VERSION.gem
+```
 
-Before final release:
+After pushing:
 
-- 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`
+- Create or update the GitHub release for `vVERSION`.
+- Paste the release note from `docs/releases/vVERSION.md` when one exists, for
+  example `docs/releases/v1.1.0.md`.
+- Link the release back to the upgrade guide for application-facing changes.
+- Confirm the pushed gem is visible on RubyGems.

data/docs/releases/v1.1.0.md

@@ -0,0 +1,74 @@
+# Achilles 1.1.0
+
+Achilles `1.1.0` tightens the application lifecycle for Rails + Turbo apps and
+adds stronger nested-component behavior. This release is intended for existing
+Achilles users who want explicit startup, safer teardown ordering, and better
+runtime behavior around Turbo navigation and dynamic markup.
+
+## Upgrade First
+
+This release includes application-facing changes. Before upgrading an existing
+app, read the full guide:
+
+- [Upgrading to 1.1.0](../upgrading-to-1.1.0.md)
+
+The most important change is explicit application startup:
+
+```js
+const achilles = new Application();
+achilles.componentsClassMapper.addComponentClass("MenuComponent", MenuComponent);
+achilles.start();
+```
+
+Call `start()` after registering component classes. Achilles no longer starts
+from the `Application` constructor.
+
+## Highlights
+
+- Added explicit `Application#start` and `Application#stop` lifecycle methods.
+- Added `Application#strictLifecycleErrors` for tests and development.
+- Component parentage now follows DOM ancestry under the synthetic `Page` root.
+- Component teardown now runs from children to parents.
+- Elements with `data-component-class` must have a non-empty `id`; invalid roots
+  are skipped with a browser-console error.
+- Achilles now requires `turbo-rails`, so Turbo importmap assets are available
+  to host applications.
+- Added browser system coverage for nested components inside Turbo form
+  replacement and Turbo Drive navigation.
+
+## Breaking Or Compatibility-Sensitive Changes
+
+Applications should check these items before updating:
+
+- Search for `new Application` and make sure each Achilles instance calls
+  `start()` after all component classes are registered.
+- Search for `data-component-class` and make sure every component root has a
+  non-empty unique `id`.
+- Review parent components whose `teardown()` removes DOM nodes, shared event
+  targets, widgets, or state that child components also use during cleanup.
+- If you have tests that should fail on lifecycle errors, enable strict mode:
+
+```js
+achilles.strictLifecycleErrors = true;
+```
+
+## Verification
+
+This release line was verified with:
+
+```bash
+bin/rails test
+node --test test/javascript/*_test.mjs
+bin/rails test:system
+RAILS_ENV=test bin/rails app:assets:precompile
+gem build achilles.gemspec
+```
+
+One real application has also been updated successfully. Continue testing in
+your own Rails + Turbo apps before rolling the update through every project.
+
+## Links
+
+- [Changelog](../../CHANGELOG.md)
+- [Upgrade index](../upgrading.md)
+- [1.1.0 upgrade guide](../upgrading-to-1.1.0.md)

data/docs/releases/v1.1.1.md

@@ -0,0 +1,46 @@
+# Achilles 1.1.1
+
+Achilles `1.1.1` is a patch release for Rails + Turbo applications using
+browser history restoration. It fixes restored component markup that appeared on
+screen after browser back or forward navigation but no longer had active
+Achilles event listeners.
+
+## Who Should Upgrade
+
+Upgrade from `1.1.0` if your application uses Turbo Drive navigation and users
+can return to Achilles-managed pages with the browser back or forward buttons.
+
+There are no new application setup requirements in this patch release. Apps
+upgrading from versions before `1.1.0` should still read the
+[1.1.0 upgrade guide](../upgrading-to-1.1.0.md).
+
+## Fixed
+
+- Restored Turbo-cached DOM with stale `data-component-registered="true"` flags
+  is now parsed correctly when Achilles no longer has a matching registry entry.
+- Deregistering a parent component now deregisters its child component subtree,
+  preventing orphaned child registry entries from blocking future setup.
+- Page-level deregistration now iterates over a stable copy of child component
+  ids while the registry is being mutated.
+
+## Verification
+
+This release was verified with:
+
+```bash
+bin/rails test
+node --test test/javascript/*_test.mjs
+bin/rails test:system
+RAILS_ENV=test bin/rails app:assets:precompile
+gem build achilles.gemspec
+```
+
+The system suite includes browser back, browser forward, restored nested
+components, restored form-field listeners, restored Turbo-replaced forms, and
+duplicate listener prevention.
+
+## Links
+
+- [Changelog](../../CHANGELOG.md)
+- [Upgrade index](../upgrading.md)
+- [1.1.0 upgrade guide](../upgrading-to-1.1.0.md)

data/docs/releases/v1.1.2.md

@@ -0,0 +1,58 @@
+# Achilles 1.1.2
+
+Achilles `1.1.2` is a patch release for Rails + Turbo applications using Turbo
+Frames. It fixes late component cleanup when Turbo replaces frame content.
+
+## Who Should Upgrade
+
+Upgrade from `1.1.0` or `1.1.1` if your application registers
+Achilles-managed components inside a Turbo Frame or on the frame root itself.
+
+There are no new application setup requirements in this patch release. Apps
+upgrading from versions before `1.1.0` should still read the
+[1.1.0 upgrade guide](../upgrading-to-1.1.0.md).
+
+## Fixed
+
+- Registered components in an outgoing Turbo Frame are now torn down and
+  deregistered immediately before Turbo invokes the frame renderer.
+- Cleanup runs from children to parents and includes the frame root when it is
+  registered as a component.
+- The original Turbo renderer keeps its receiver, arguments, return value, and
+  error behavior.
+- Incoming components continue to register through the existing DOM observer,
+  while ordinary non-Turbo removal behavior remains unchanged.
+- Starting and stopping an Achilles application manages the frame-render
+  listener without creating duplicates.
+
+## Compatibility
+
+This backward-compatible `1.1.x` patch intentionally moves frame-contained
+teardown earlier, while the outgoing component elements are still present,
+instead of relying on missing-element recovery after replacement.
+
+Achilles continues to require Turbo Rails `2.0.11` or newer. This release does
+not add dependencies or require an application migration.
+
+## Verification
+
+This release was verified with:
+
+```bash
+bin/rails test
+node --test test/javascript/*_test.mjs
+for file in $(rg --files app/javascript/achilles test/dummy/app/javascript test/javascript | rg "\.(js|mjs)$"); do node --input-type=module --check < "$file" || exit 1; done
+bin/rails test:system
+RAILS_ENV=test bin/rails app:assets:precompile
+gem build achilles.gemspec
+```
+
+The system suite covers a native Turbo Frame replacement with a registered
+frame root, nested outgoing components, incoming component registration and
+interaction, and browser-console error checks.
+
+## Links
+
+- [Changelog](../../CHANGELOG.md)
+- [Upgrade index](../upgrading.md)
+- [1.1.0 upgrade guide](../upgrading-to-1.1.0.md)

data/docs/upgrading.md

@@ -10,6 +10,12 @@ setup, component markup, lifecycle behavior, or public APIs.
 - [Upgrading to 1.1.0](upgrading-to-1.1.0.md)
 - [Migrating from 0.1.3 to v1](migrating-from-0.1.3-to-v1.md)
 
+## Release Notes
+
+- [Achilles 1.1.2](releases/v1.1.2.md)
+- [Achilles 1.1.1](releases/v1.1.1.md)
+- [Achilles 1.1.0](releases/v1.1.0.md)
+
 ## Upgrade Policy
 
 Before upgrading an existing application:

data/lib/achilles/version.rb

@@ -1,3 +1,3 @@
 module Achilles
-  VERSION = "1.1.0"
+  VERSION = "1.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: achilles
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
 - Jey Geethan
@@ -90,6 +90,9 @@ files:
 - docs/core-js-gaps.md
 - docs/migrating-from-0.1.3-to-v1.md
 - docs/release-checklist.md
+- docs/releases/v1.1.0.md
+- docs/releases/v1.1.1.md
+- docs/releases/v1.1.2.md
 - docs/upgrading-to-1.1.0.md
 - docs/upgrading.md
 - docs/v1-roadmap.md