achilles 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d393e3c7e9d04d6a472ba4e41c727fffca5fa3088f5d064a08a0f9cd4b2bfcf2
-  data.tar.gz: 911efcf9ddc72755b3b26b9a8ae3d0a5538d4d33ba2f8476d6c4ae4c8aa54e8e
+  metadata.gz: d860cd0be6faa8af39117c4dc6feadb2445f48ccfd687963a3a8eeddbe1c3b95
+  data.tar.gz: '09cdfabdfa0895b1a3c7a92726baf49cb234a9a716b8a1e3a65c7eb6e578904e'
 SHA512:
-  metadata.gz: a480a6ca6a9b154cdf723aa53560a1caa2a82f41f569a3e2d79dafbd80e50d1dea7a9c9b18d29f69c8eb9d693af79b358929929b9842a014645eaf939105dea5
-  data.tar.gz: 52f50f6c02b169e7d592363571da480961aa6ac52a856aaca72dc3f26f4e5c557e9b5c918e24f18bdfec6d5d37685936e49678e093ea182d4dc8730bad6d898c
+  metadata.gz: 7899f56529ad2a867a289b546241023e235a1d848d3a22ceb1a396fb92a515c9edeb3b50decdec7d37e952f9c5fc524326c8d1fc3456e78f5e1c7db5be53c10d
+  data.tar.gz: 7d43d1c196f608be65a27d42840cdd0a3f3bac7bb86870dec876b89bdbfdf63408465dabd265986322638300ab0d8287c3a747e2b2830ccc3c824bf74217318e

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to Achilles will be documented in this file.
 
+## 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,10 @@ 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.1`. 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 release note](docs/releases/v1.1.1.md).
+
 ## Why Achilles?
 
 Rails and Turbo make server-rendered interfaces productive, but many apps still
@@ -79,6 +83,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 +115,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 +156,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
@@ -158,8 +186,17 @@ 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.
 - `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 +215,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 +257,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 +272,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 GitHub release draft is
+available at [docs/releases/v1.1.1.md](docs/releases/v1.1.1.md).
+
 ## Upgrading From 0.1.3
 
 Achilles `1.0.0` changes `rootElement()` to return a DOM element. It no longer
@@ -255,9 +302,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/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){

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/upgrading.md

@@ -10,6 +10,11 @@ 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.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.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: achilles
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Jey Geethan
@@ -90,6 +90,8 @@ 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/upgrading-to-1.1.0.md
 - docs/upgrading.md
 - docs/v1-roadmap.md