achilles 1.0.0 → 1.1.1

data/docs/upgrading-to-1.1.0.md

@@ -0,0 +1,144 @@
+# Upgrading To 1.1.0
+
+This guide covers application-facing changes in Achilles `1.1.0`.
+
+## Application Startup
+
+Achilles applications must now be started explicitly.
+
+Before:
+
+```js
+import { Application } from "achilles/application/application";
+import { MenuComponent } from "components/menu_component";
+
+const achilles = new Application();
+achilles.componentsClassMapper.addComponentClass("MenuComponent", MenuComponent);
+```
+
+After:
+
+```js
+import { Application } from "achilles/application/application";
+import { MenuComponent } from "components/menu_component";
+
+const achilles = new Application();
+achilles.componentsClassMapper.addComponentClass("MenuComponent", MenuComponent);
+achilles.start();
+```
+
+Call `start()` after registering component classes. This lets applications
+control when Achilles parses the DOM and attaches Turbo lifecycle hooks.
+
+## Stopping An Application
+
+Applications that create temporary Achilles instances can now call:
+
+```js
+achilles.stop();
+```
+
+`stop()` removes Turbo lifecycle hooks and stops observing DOM mutations.
+
+Most Rails applications only need one long-lived Achilles instance and do not
+need to call `stop()` manually.
+
+## Search Checklist
+
+In each application, search for Achilles construction:
+
+```bash
+rg "new Application"
+```
+
+For every application instance, confirm component classes are registered before
+calling `start()`.
+
+## Component Root Ids
+
+Every element with `data-component-class` must have a non-empty `id`.
+
+Before:
+
+```erb
+<div data-component-class="MenuComponent"></div>
+```
+
+After:
+
+```erb
+<div id="menu" data-component-class="MenuComponent"></div>
+```
+
+Achilles uses component root ids as registry keys. Components without ids are
+skipped and reported in the browser console.
+
+Search for component roots without ids:
+
+```bash
+rg "data-component-class"
+```
+
+## Nested Components
+
+Achilles now builds the component tree from DOM ancestry.
+
+- `Page` remains the single synthetic root component.
+- A component's parent is its nearest ancestor element with
+  `data-component-class`.
+- If no component ancestor exists, the parent is `Page`.
+
+For example:
+
+```erb
+<div id="dashboard" data-component-class="DashboardComponent">
+  <div id="filters" data-component-class="FiltersComponent"></div>
+</div>
+```
+
+The component tree is:
+
+```text
+Page
+dashboard
+filters
+```
+
+## Teardown Order
+
+Component teardown now runs from children to parents.
+
+Before this change, a parent component's `teardown()` could run before its child
+components. Now child components clean up first, and the parent cleans up after
+its subtree.
+
+Review parent components whose `teardown()` removes DOM nodes, shared event
+targets, third-party widgets, or state that child components also use during
+cleanup.
+
+## Strict Lifecycle Errors
+
+By default, Achilles logs `setup()` and `teardown()` errors and keeps the page
+running.
+
+Tests and development environments can opt into strict lifecycle errors:
+
+```js
+const achilles = new Application();
+achilles.strictLifecycleErrors = true;
+```
+
+When strict mode is enabled, `setup()` and `teardown()` errors are still logged
+and then re-raised.
+
+## Manual Test Checklist
+
+After updating an application:
+
+- boot the app
+- open a page with Achilles components
+- confirm component `setup()` methods run
+- navigate with Turbo to another page and back
+- confirm `teardown()` still runs before Turbo renders a new page
+- insert any dynamic component markup the app supports
+- check the browser console for Achilles errors

data/docs/upgrading.md

@@ -0,0 +1,31 @@
+# Upgrading Achilles
+
+Use this page as the entry point for application upgrades.
+
+Achilles should have an upgrade note for every release that changes application
+setup, component markup, lifecycle behavior, or public APIs.
+
+## Current Upgrade Notes
+
+- [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:
+
+1. Read the guide for the target version.
+2. Upgrade one application first.
+3. Run the application's test suite.
+4. Visit pages with Achilles components.
+5. Verify Turbo navigation and dynamically inserted components.
+6. Check the browser console for lifecycle, missing component class, or duplicate
+   id errors.
+
+For breaking changes, prefer testing a release candidate in a real application
+before upgrading every project.

data/lib/achilles/version.rb

@@ -1,3 +1,3 @@
 module Achilles
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 end

data/lib/achilles.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: achilles
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Jey Geethan
@@ -60,9 +60,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- MAINTAINERS.md
 - MIT-LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - app/assets/config/achilles/manifest.js
 - app/assets/stylesheets/achilles/application.css
 - app/controllers/achilles/application_controller.rb
@@ -83,8 +87,13 @@ files:
 - app/views/layouts/achilles/application.html.erb
 - config/importmap.rb
 - config/routes.rb
+- 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
 - lib/achilles.rb
 - lib/achilles/engine.rb