achilles 1.0.0 → 1.1.1

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

@@ -16,6 +16,7 @@ class Application {
   _componentsClassMapper;
   _hooksManager;
   _domMutationObserver;
+  _started = false;
 
   constructor() {
     // Set the application while creating the object
@@ -53,12 +54,45 @@ class Application {
     return this._page;
   }
 
+  get strictLifecycleErrors() {
+    return this.componentRegistry.strictLifecycleErrors;
+  }
+
   // Setters
   set engine(engine) {
     this._engine = engine;
   }
 
+  set strictLifecycleErrors(value) {
+    this.componentRegistry.strictLifecycleErrors = value;
+  }
+
+  start() {
+    if (this._started) {
+      return;
+    }
+
+    this._started = true;
+    this._hooksManager.start();
+    this.setup();
+  }
+
+  stop() {
+    if (!this._started) {
+      return;
+    }
+
+    this._started = false;
+    this._hooksManager.stop();
+    this.teardown();
+    this._domMutationObserver.stop();
+  }
+
   setup() {
+    if (!this._started) {
+      return;
+    }
+
     this._domMutationObserver.stop();
     this.parseHtmlAndRegisterComponents();
     this.componentRegistry.callSetupForComponent(AppConstants.PageComponentId);
@@ -71,7 +105,10 @@ class Application {
     this.componentRegistry.callTeardownForComponent(AppConstants.PageComponentId);
     // Remove/deregister all components from page except Page
     this.deregisterAllComponentsExceptPage();
-    this._domMutationObserver.start();
+
+    if (this._started) {
+      this._domMutationObserver.start();
+    }
   }
 
   parseHtmlAndRegisterComponents() {
@@ -80,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/dom-mutation-observer/observer.js

@@ -1,6 +1,7 @@
 class Observer {
   _mutationObserver;
   _callback;
+  _callbackScheduled = false;
 
   constructor(callback) {
     this._callback = callback;
@@ -18,10 +19,19 @@ class Observer {
 
   stop() {
     this._mutationObserver.disconnect();
+    this._callbackScheduled = false;
   }
 
   domChangedCallback(mutationsList, observer) {
-    this._callback();
+    if (this._callbackScheduled) {
+      return;
+    }
+
+    this._callbackScheduled = true;
+    queueMicrotask(() => {
+      this._callbackScheduled = false;
+      this._callback();
+    });
   }
 }
 

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

@@ -2,25 +2,46 @@ class Turbo {
   _application;
   _setupCallback;
   _teardownCallback;
+  _setupHandler;
+  _teardownHandler;
+  _started = false;
 
   constructor(application, setupCallback, teardownCallback) {
     this._application = application;
     this._setupCallback = setupCallback;
     this._teardownCallback = teardownCallback;
-
-    this.setupEvents();
   }
 
   // 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() {
-    document.addEventListener("turbo:load", () => {
+  start() {
+    if (this._started) {
+      return;
+    }
+
+    this._setupHandler = () => {
       this._setupCallback();
-    });
+    };
 
-    document.addEventListener("turbo:before-render", () => {
+    this._teardownHandler = () => {
       this._teardownCallback();
-    });
+    };
+
+    document.addEventListener("turbo:load", this._setupHandler);
+    document.addEventListener("turbo:before-render", this._teardownHandler);
+    this._started = true;
+  }
+
+  stop() {
+    if (!this._started) {
+      return;
+    }
+
+    document.removeEventListener("turbo:load", this._setupHandler);
+    document.removeEventListener("turbo:before-render", this._teardownHandler);
+    this._setupHandler = null;
+    this._teardownHandler = null;
+    this._started = false;
   }
 }
 

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

@@ -2,8 +2,7 @@ class ComponentBase {
     parentComponentId;
     id;
     defaultParams;
-    setupExecuted = false;
-    teardownExecuted = false;
+    mounted = false;
 
     constructor(id, parentComponentId = 'Page', defaultParams = []) {
         this.id = id;
@@ -17,6 +16,24 @@ class ComponentBase {
     setup() {}
     teardown() {}
 
+    get setupExecuted() {
+        return this.mounted;
+    }
+
+    set setupExecuted(value) {
+        this.mounted = value;
+    }
+
+    get teardownExecuted() {
+        return !this.mounted;
+    }
+
+    set teardownExecuted(value) {
+        if(value === true) {
+            this.mounted = false;
+        }
+    }
+
     rootElement() {
         return this.rootNode();
     }

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

@@ -11,6 +11,10 @@ class ComponentParser {
         [...document.querySelectorAll('[data-component-class]')].forEach((elem) => {
             let klassName = elem.dataset.componentClass;
             if(klassName.trim() === '') { return; }
+            if(!this.hasValidId(elem)) {
+                console.error(`Component root element is missing an id. className: ${klassName} | Element:`, elem);
+                return;
+            }
 
             let klass = this._componentsClassMapper.getComponentClass(klassName);
             if(typeof klass === 'undefined' || klass === null) {
@@ -18,11 +22,11 @@ class ComponentParser {
                 console.error(elem);
                 return;
             }
-            if(elem.dataset.componentRegistered === 'true') {
+            if(elem.dataset.componentRegistered === 'true' && this._componentRegistry.getRegisteredComponent(elem.id)) {
                 return;
             }
             try {
-                let obj = new klass(elem.id, AppConstants.PageComponentId)
+                let obj = new klass(elem.id, this.parentComponentIdFor(elem))
                 this._componentRegistry.registerComponentByObj(obj);
             } catch (e) {
                 console.error(`Error parsing component. className: ${klassName} | Element ID: ${elem.id}`);
@@ -31,6 +35,22 @@ class ComponentParser {
             }
         })
     }
+
+    hasValidId(elem) {
+        return typeof elem.id === 'string' && elem.id.trim() !== '';
+    }
+
+    parentComponentIdFor(elem) {
+        let parent = elem.parentElement;
+        while(parent) {
+            if(parent.dataset?.componentClass && this.hasValidId(parent)) {
+                return parent.id;
+            }
+            parent = parent.parentElement;
+        }
+
+        return AppConstants.PageComponentId;
+    }
 }
 
 export { ComponentParser };

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

@@ -3,6 +3,7 @@ import { AppConstants } from "achilles/application/app_constants";
 // Contains all the registered components in a page at the current moment
 class ComponentsRegistry {
     _registeredComponents = {};
+    strictLifecycleErrors = false;
 
     matchingElementsForId(id) {
         return [...document.querySelectorAll('[id]')].filter((elem) => elem.id === id);
@@ -25,6 +26,14 @@ class ComponentsRegistry {
             // Component is already registered. So have to call deregister and teardown
             this.teardownAndDeregister(id);
         }
+        let parentComponent = null;
+        if(parentComponentId != null) {
+            parentComponent = this.getRegisteredComponent(parentComponentId);
+            if(!parentComponent) {
+                console.error(`Parent component not found while registering component. id: ${id} | parentComponentId: ${parentComponentId}. Skipping registering component`);
+                return;
+            }
+        }
 
         this._registeredComponents[id] = {
             id: id,
@@ -34,7 +43,6 @@ class ComponentsRegistry {
             subComponents: []
         };
         if(parentComponentId != null) {
-            let parentComponent = this.getRegisteredComponent(parentComponentId);
             parentComponent.subComponents.push(id);
         }
         this.elementForId(id)?.setAttribute('data-component-registered', 'true');
@@ -45,13 +53,17 @@ class ComponentsRegistry {
         if(!component)
             return;
 
+        [...component.subComponents].forEach((subComponentId) => {
+            this.deregisterComponent(subComponentId);
+        });
+
         let parentComponent = this.getRegisteredComponent(component.parentComponentId);
 
         if(parentComponent != null){
             parentComponent.subComponents = parentComponent.subComponents.filter(item => item !== id);
         }
 
-        this._registeredComponents[id] = null;
+        delete this._registeredComponents[id];
         this.elementForId(id)?.removeAttribute('data-component-registered');
     }
 
@@ -68,13 +80,13 @@ class ComponentsRegistry {
             return;
         }
 
-        // Call the objs default setup if its not executed already, if not skip to their children
-        if(component.obj.setup && component.obj.setupExecuted === false) {
+        // Call the objs default setup if it is not mounted already, then continue to children
+        if(component.obj.setup && component.obj.mounted === false) {
             try{
                 component.obj.setup(...component.defaultParams);
-                component.obj.setupExecuted = true;
+                component.obj.mounted = true;
             } catch(e) {
-                console.error(e);
+                this.handleLifecycleError(e);
             }
         }
 
@@ -89,20 +101,28 @@ class ComponentsRegistry {
         if(!component || !component.obj)
             return;
 
-        // Call the objs default teardown if not already executed, otherwise skip to its children
-        if(component.obj.teardown && component.obj.teardownExecuted === false) {
+        // Call teardown for all sub view_components before their parent
+        component.subComponents.forEach((subComponentId) => {
+            this.callTeardownForComponent(subComponentId);
+        });
+
+        // Call the objs default teardown if it is currently mounted
+        if(component.obj.teardown && component.obj.mounted === true) {
             try{
                 component.obj.teardown(...component.defaultParams);
-                component.obj.teardownExecuted = true;
+                component.obj.mounted = false;
             } catch(e) {
-                console.error(e);
+                this.handleLifecycleError(e);
             }
         }
+    }
 
-        // Call teardown for all sub view_components
-        component.subComponents.forEach((subComponentId) => {
-            this.callTeardownForComponent(subComponentId);
-        });
+    handleLifecycleError(error) {
+        console.error(error);
+
+        if(this.strictLifecycleErrors) {
+            throw error;
+        }
     }
 
     teardownAndDeregister(id) {

data/docs/core-js-gaps.md

@@ -0,0 +1,26 @@
+# Core JavaScript Gaps
+
+This is the current improvement backlog for Achilles core JavaScript. API
+reference docs should wait until the structure settles.
+
+## Completed
+
+- Added an explicit `Application#start` and `Application#stop` lifecycle.
+- Made Turbo event listeners removable.
+- Validated that component roots have non-empty ids before registration.
+- Changed teardown order so child components tear down before parent components.
+- Deleted deregistered registry entries instead of leaving `null` tombstones.
+- Batched mutation observer setup work with a microtask debounce.
+- Replaced one-way lifecycle flags with a `mounted` state while keeping
+  `setupExecuted` and `teardownExecuted` as compatibility aliases.
+- Added tests for missing ids, duplicate starts, listener cleanup,
+  child-before-parent teardown, dynamic insertion batching, deregistration, and
+  remounting a reused component instance.
+- Chose a DOM ancestry model for nested components under the single synthetic
+  `Page` root.
+- Split JavaScript tests by parser, registry, application, Turbo hooks, and
+  component base responsibility.
+- Added package/file-list regression coverage for the gemspec.
+- Added opt-in strict lifecycle error handling for tests and development.
+
+## Remaining Priority Gaps

data/docs/release-checklist.md

@@ -1,17 +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
-for file in $(find app/javascript/achilles -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+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
 ```
 
@@ -24,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:
 
@@ -44,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)