achilles 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97bbd095ec5feda0679a77b020f80ad70ec59b202757af4d84e1c318643a4632
-  data.tar.gz: 40bdce2ca5420c29a4be44260e2655cfbca3e6357d294aa017454c0f90b9a642
+  metadata.gz: d860cd0be6faa8af39117c4dc6feadb2445f48ccfd687963a3a8eeddbe1c3b95
+  data.tar.gz: '09cdfabdfa0895b1a3c7a92726baf49cb234a9a716b8a1e3a65c7eb6e578904e'
 SHA512:
-  metadata.gz: d21a4690c44bfeb356544370465319b6b6d969731a07aa4f4a9e462e32038a57c53f63f2e6ee05b5b3959e86d1fe7f517b48acce6ab8d08266d9dd7de8589285
-  data.tar.gz: b1a8de0b8ed2beb3d564df46e35568958989b93b1ca5f8b2d4d89a93dadb40640b1d81c5ef0a0316a7c4016f7ed29da1382ef10b86bdf1103756075a6ec11293
+  metadata.gz: 7899f56529ad2a867a289b546241023e235a1d848d3a22ceb1a396fb92a515c9edeb3b50decdec7d37e952f9c5fc524326c8d1fc3456e78f5e1c7db5be53c10d
+  data.tar.gz: 7d43d1c196f608be65a27d42840cdd0a3f3bac7bb86870dec876b89bdbfdf63408465dabd265986322638300ab0d8287c3a747e2b2830ccc3c824bf74217318e

data/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 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
+
+- Added explicit `Application#start` and `Application#stop` lifecycle methods.
+- Added opt-in `Application#strictLifecycleErrors` handling for tests and
+  development.
+- Added browser system coverage for nested components inside Turbo form
+  replacement and Turbo Drive navigation.
+
+### Changed
+
+- `Application` no longer starts automatically from the constructor. Applications
+  should register component classes, then call `achilles.start()`. See
+  [docs/upgrading-to-1.1.0.md](docs/upgrading-to-1.1.0.md).
+- Elements with `data-component-class` must now have a non-empty `id`; invalid
+  component roots are skipped with a console error.
+- Component teardown now runs from child components to parent components.
+- Component parentage now follows DOM ancestry under the synthetic `Page` root.
+- Turbo lifecycle hooks are now attached by `start()` and removed by `stop()`.
+- Achilles now requires `turbo-rails` so Turbo importmap assets are available to
+  host applications.
+
 ## 1.0.0
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Code Of Conduct
+
+## Our Pledge
+
+We want Achilles to be a respectful, useful, and practical open source project.
+
+Everyone participating in the project is expected to communicate with clarity,
+patience, and respect. Disagreement is fine. Harassment, personal attacks, and
+abusive behavior are not.
+
+## Expected Behavior
+
+- Be respectful of differing experience levels and viewpoints.
+- Keep technical criticism focused on the code, design, or documentation.
+- Assume good intent, but be direct when something is unclear or risky.
+- Help keep issues and pull requests actionable.
+- Respect maintainers' time and project scope.
+
+## Unacceptable Behavior
+
+- Harassment, threats, or personal attacks.
+- Insults, slurs, or discriminatory language.
+- Public or private abuse of contributors or maintainers.
+- Publishing someone's private information without permission.
+- Repeated off-topic disruption after maintainers ask for the discussion to
+  stop or move elsewhere.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, reject pull requests, or block
+participants who violate this code of conduct.
+
+To report a concern, email:
+
+```text
+jey@jeygeethan.com
+```
+
+Reports will be reviewed privately. Please include relevant links, screenshots,
+or context when possible.
+
+## Scope
+
+This code of conduct applies to Achilles project spaces, including GitHub
+issues, pull requests, discussions, release comments, and private project
+communication with maintainers.

data/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing
+
+Thanks for taking the time to improve Achilles.
+
+Achilles is intentionally small. Contributions should keep the public API clear,
+the Rails + Turbo integration reliable, and the documentation practical for
+applications that already use the gem.
+
+## Local Setup
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the dummy Rails app:
+
+```bash
+bin/rails server
+```
+
+Open:
+
+```text
+http://localhost:3000/
+```
+
+The dummy app includes a working counter component that exercises the basic
+Achilles flow.
+
+## Test Commands
+
+Run the Rails and JavaScript lifecycle tests:
+
+```bash
+bin/rails test
+```
+
+Run the browser system test:
+
+```bash
+bin/rails test:system
+```
+
+Run JavaScript syntax checks:
+
+```bash
+for file in $(find app/javascript/achilles test/dummy/app/javascript -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+```
+
+Run the dummy app asset precompile check:
+
+```bash
+RAILS_ENV=test bin/rails app:assets:precompile
+```
+
+Run the full local verification set:
+
+```bash
+bin/rails test
+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
+```
+
+## System Test Browser Requirements
+
+System tests use Selenium with headless Chrome.
+
+On CI, GitHub's Ubuntu runner provides Chrome. Locally, set these environment
+variables if Chrome or chromedriver are installed in non-standard locations:
+
+```bash
+CHROME_BIN=/path/to/chrome CHROMEDRIVER_PATH=/path/to/chromedriver bin/rails test:system
+```
+
+If Chrome is not available, the system test base skips browser tests cleanly.
+
+## Pull Request Guidelines
+
+- Keep changes scoped.
+- Add or update tests for behavior changes.
+- Update the README or docs for public API changes.
+- Add or update an upgrade guide for changes existing applications must make.
+- Mention breaking changes clearly in the pull request.
+- Do not introduce a new runtime dependency without explaining why it belongs in
+  a small lifecycle gem.
+- Prefer browser DOM APIs in Achilles internals.
+- Keep jQuery usage out of Achilles internals. Applications may still use jQuery
+  explicitly in their own components.
+
+## Public API Expectations
+
+Treat these as public API:
+
+- `Application`
+- `ComponentBase`
+- `ComponentsClassMapper`
+- `data-component-class`
+- `setup()`
+- `teardown()`
+- `rootElement()`
+- `rootNode()`
+- `rootElementSelector()`
+
+Changes to these APIs need tests, documentation, and changelog notes.
+
+## Release Process
+
+Use [docs/release-checklist.md](docs/release-checklist.md) for prereleases and
+final releases.
+
+Maintainer release ownership and project decision guidelines are documented in
+[MAINTAINERS.md](MAINTAINERS.md).
+
+Before releasing:
+
+- confirm CI is green
+- run the full local verification set
+- build the gem with `gem build achilles.gemspec`
+- test release candidates in at least one real application

data/MAINTAINERS.md

@@ -0,0 +1,53 @@
+# Maintainers
+
+Achilles is maintained as a small, stable Rails + Turbo lifecycle gem.
+
+The maintainer goal is to keep the public API easy to understand, the runtime
+surface small, and releases safe for applications that already depend on the
+gem.
+
+## Decision Making
+
+Maintainers should prefer changes that:
+
+- preserve the small public API
+- improve reliability across Rails, Turbo, and importmap applications
+- reduce hidden runtime dependencies
+- make migration or debugging easier for existing applications
+- include tests for changed behavior
+
+Breaking changes are acceptable when they make the project simpler, safer, or
+more predictable. They should be documented in `CHANGELOG.md`, covered by tests,
+and called out in migration notes when existing applications need code changes.
+
+## Release Ownership
+
+Before publishing a release, a maintainer should:
+
+- confirm CI is green
+- run the local verification set in `CONTRIBUTING.md`
+- follow `docs/release-checklist.md`
+- test release candidates in at least one real Rails application when behavior
+  changes affect runtime integration
+
+Patch releases should be narrow and low risk. Minor releases can add compatible
+APIs or documentation improvements. Major releases may remove deprecated
+behavior or tighten public contracts.
+
+## Security Reports
+
+Security reports should follow `SECURITY.md`. Reports are handled privately
+until there is a fix or a clear public response.
+
+## Community Standards
+
+Project participation is covered by `CODE_OF_CONDUCT.md`. Maintainers may close
+issues, reject pull requests, edit discussions, or block participants when
+needed to keep the project focused and respectful.
+
+## Adding Maintainers
+
+New maintainers should already have a history of useful issues, documentation,
+or code contributions. They should understand the project scope, support the
+public API expectations in `CONTRIBUTING.md`, and be comfortable reviewing
+changes conservatively.

data/README.md

@@ -1,12 +1,53 @@
 # Achilles
 
 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.
+It is an explicit component-class alternative to Stimulus for teams that prefer
+plain JavaScript classes mapped directly 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.
+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
+need page-specific JavaScript for menus, forms, filters, widgets, charts, and
+small interaction islands.
+
+Achilles keeps that JavaScript close to the DOM without requiring controller
+naming conventions or a build step. You register classes explicitly, mark the
+HTML root node, and implement lifecycle methods.
+
+Use Achilles when you want:
+
+- explicit JavaScript classes instead of controller naming conventions
+- lifecycle hooks that match Turbo navigation
+- no internal jQuery dependency
+- no JavaScript build step
+- predictable setup and teardown for server-rendered UI
+- simple dynamic DOM registration through `MutationObserver`
+
+## Achilles vs Stimulus
+
+Stimulus is a strong default for many Rails apps. Achilles is intentionally
+smaller and more explicit.
+
+| Concern | Achilles | Stimulus |
+| --- | --- | --- |
+| Class registration | Explicit mapper registration | File and identifier conventions |
+| DOM marker | `data-component-class` | `data-controller` |
+| Root element API | `this.rootElement()` | `this.element` |
+| Lifecycle | `setup()` and `teardown()` | `connect()` and `disconnect()` |
+| Targets/actions | Use standard DOM APIs | Built-in targets/actions |
+| Dependency | Rails, Turbo, Importmap | Hotwire Stimulus |
+
+Choose Achilles if you want a tiny lifecycle layer with explicit class mapping.
+Choose Stimulus if you want its controller ecosystem, targets, values, actions,
+and conventions.
 
 ## Requirements
 
@@ -39,8 +80,12 @@ import { CounterComponent } from "components/counter_component";
 
 const achilles = new Application();
 achilles.componentsClassMapper.addComponentClass("CounterComponent", CounterComponent);
+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
@@ -70,17 +115,151 @@ 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
+
+Achilles watches the document for inserted component markup. If Turbo Streams,
+custom JavaScript, or another UI flow adds a matching element, Achilles parses
+and sets it up automatically.
+
+```erb
+<div id="notification-42" data-component-class="NotificationComponent">
+  Saved successfully
+</div>
+```
+
+```js
+import { ComponentBase } from "achilles/components/component_base";
+
+class NotificationComponent extends ComponentBase {
+  setup() {
+    this.timeout = window.setTimeout(() => {
+      this.rootElement().remove();
+    }, 3000);
+  }
+
+  teardown() {
+    window.clearTimeout(this.timeout);
+  }
+}
+
+export { NotificationComponent };
+```
+
+Register the component class once:
+
+```js
+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
+[examples/README.md](examples/README.md) for the files and local run command.
 
 ## 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.
+- `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
+
+### `Application`
+
+The top-level Achilles application object.
+
+```js
+import { Application } from "achilles/application/application";
+
+const achilles = new Application();
+achilles.start();
+```
+
+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
+application instance should remove its Turbo hooks and stop observing the DOM.
+
+### `ComponentsClassMapper`
+
+Maps `data-component-class` values to JavaScript classes.
+
+```js
+achilles.componentsClassMapper.addComponentClass("MenuComponent", MenuComponent);
+```
+
+### `ComponentBase`
+
+Base class for application components.
+
+```js
+import { ComponentBase } from "achilles/components/component_base";
+
+class MenuComponent extends ComponentBase {
+  setup() {}
+  teardown() {}
+}
+```
+
+Useful methods:
+
+- `setup()`: override to initialize behavior.
+- `teardown()`: override to clean up behavior before Turbo renders a new page.
+- `rootElement()`: returns the component root DOM element.
+- `rootNode()`: alias for `rootElement()`.
+- `rootElementSelector()`: returns a CSS selector for the component id.
+
+### Component Markup
+
+```erb
+<div id="account-menu" data-component-class="MenuComponent"></div>
+```
+
+The `data-component-class` value must match a class registered with
+`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
 
@@ -93,18 +272,73 @@ 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
+returns a jQuery object when `window.$` is present.
+
+Old jQuery-style code:
+
+```js
+this.rootElement().addClass("is-open");
+```
+
+Use DOM APIs:
+
+```js
+this.rootElement().classList.add("is-open");
+```
+
+Or wrap explicitly if the application still uses jQuery:
+
+```js
+$(this.rootElement()).addClass("is-open");
+```
+
+Applications upgrading from `0.1.3` should also read the
+[v1 migration guide](docs/migrating-from-0.1.3-to-v1.md).
+
 ## Contributing
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test commands, pull request
+guidelines, and release notes. Project participation is covered by the
+[code of conduct](CODE_OF_CONDUCT.md). Maintainer responsibilities are described
+in [MAINTAINERS.md](MAINTAINERS.md).
+
 Run the test suite with:
 
 ```bash
 bin/rails test
 ```
 
-## Migration
+Run the browser system test with:
 
-Applications upgrading from `0.1.3` should read the
-[v1 migration guide](docs/migrating-from-0.1.3-to-v1.md).
+```bash
+bin/rails test:system
+```
+
+Run the JavaScript syntax check with:
+
+```bash
+for file in $(find app/javascript/achilles -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+```
+
+Run the dummy app asset precompile check with:
+
+```bash
+RAILS_ENV=test bin/rails app:assets:precompile
+```
+
+## Security
+
+Report security issues privately. See [SECURITY.md](SECURITY.md).
 
 ## License
 

data/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest minor release of Achilles `1.x` receives security fixes.
+
+| Version | Supported |
+| --- | --- |
+| `1.x` | Yes |
+| `< 1.0` | No |
+
+## Reporting A Vulnerability
+
+Please do not open a public GitHub issue for security vulnerabilities.
+
+Report security issues by email:
+
+```text
+jey@jeygeethan.com
+```
+
+Include:
+
+- affected Achilles version
+- Rails version
+- Ruby version
+- a description of the vulnerability
+- reproduction steps or proof of concept
+- whether the issue is already public
+
+## Response Expectations
+
+You should receive an acknowledgement within 7 days.
+
+If the issue is confirmed, the fix will be prepared privately when practical and
+released with a changelog entry that gives users enough information to upgrade
+without exposing unnecessary exploit details before a fix is available.
+
+## Scope
+
+Security reports are most useful when they involve Achilles behavior directly,
+including:
+
+- unsafe DOM lifecycle behavior
+- asset/importmap packaging issues
+- Rails engine integration issues
+- behavior that could cause applications to execute unintended JavaScript
+
+General application security issues in apps that use Achilles should be reported
+to those applications instead.