andamiojs 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 1.0.0, 2026-10-08
+
+The npm package name changes from `backbone.andamio` to `andamiojs`.
+The project name remains Andamio.js. The browser namespace remains `Andamio`.
+The browser bundles are `lib/andamio.js` and `lib/andamio.min.js`.
+
+### Compatibility changes
+
+- Require Backbone 1.6.1 or later in the 1.x series and Underscore 1.13.8 or later in the 1.x series.
+- Support jQuery 3.7.1 and 4.0.0.
+- Require Node `^22.22.2 || ^24.15.0 || >=26.0.0` for the development tools.
+- Replace the Grunt tasks and incomplete app build template with npm scripts.
+- Give child model defaults precedence over parent defaults.
+- Evaluate computed properties in `get()` and `toJSON()`.
+- Give the first matching route in the configured array priority.
+- Make `remove()` close tracked child views.
+- Report missing, ambiguous, and duplicate region targets as errors.
+
+### Fixes and additions
+
+- Fix CommonJS and AMD loading, data event rebinding, and shared view configuration cleanup.
+- Fix collection insertion and sort order, failed-render cleanup, region reuse, and route aliases.
+- Add application shutdown, history options, and empty redirect targets.
+- Update dependencies and commit a dependency lockfile.
+- Add 30 tests, CI, dependency update checks, API documentation, and a task sample app.
+
+See the [project review](docs/review.md) for validation results and the full compatibility notes.

package/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2013 Denis Ciccale (@tdecs)
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions of
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,4 +1,68 @@
-# Temporary Holding Version
+# Andamio.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+<img src="andamiojs-logo.png" width="400" height="67" alt="Andamio.js logo">
+
+Andamio adds view lifecycle management, regions, collection views, and application routing to [Backbone.js](https://backbonejs.org/).
+
+## Run the sample app
+
+Use Node 22.22.2 or later in the 22.x series, Node 24.15.0 or later in the 24.x series, or Node 26 or later.
+
+From a checkout of this repository, run:
+
+```sh
+npm ci
+npm run example
+```
+
+Open [the local sample](http://127.0.0.1:3000). Add a task, mark it complete, and move between the Tasks and About pages.
+Tasks stay in memory until you reload the page. The sample uses local dependencies and requires no external service.
+To use another port, run `PORT=3001 npm run example`.
+
+## Use the library
+
+The package name is `andamiojs`. The browser namespace is `Andamio`.
+
+```sh
+npm install andamiojs
+```
+
+The supported peers are Backbone 1.6.1, Underscore 1.13.8, and jQuery 3.7.1 or 4.0.0.
+
+For a browser app, load jQuery, Underscore, Backbone, and `lib/andamio.js` in that order.
+The browser build exposes `Andamio` and `Backbone.Andamio`.
+The minified build is `lib/andamio.min.js`.
+
+For CommonJS, import the package and configure Backbone's DOM library before you create a view.
+
+```js
+const Backbone = require('backbone');
+const Andamio = require('andamiojs');
+Backbone.$ = require('jquery');
+```
+
+Models and collections work without a DOM. Views require a browser or a DOM environment.
+AMD loaders resolve `underscore` and `backbone` before they run the Andamio factory.
+See the [API reference](docs/api.md) for configuration and the [sample source](examples/todos/app.js) for a complete app.
+
+## Check and build changes
+
+```sh
+npm run check
+npm audit
+npm run build
+npm pack --dry-run
+```
+
+`npm run check` runs ESLint and the Node tests with coverage.
+The tests use real Backbone, jQuery, and jsdom. They also load the sample over HTTP and exercise its task and route behavior.
+`npm run build` generates the browser and CommonJS bundle, the minified bundle, and its source map in `lib/`.
+Edit `src/` and rebuild the bundles. The old Grunt tasks and incomplete `build/` app template have been removed.
+
+See the [project review](docs/review.md) for confirmed defects, security audit results, compatibility changes, and remaining work.
+
+## Author and license
+
+Denis Ciccale. Logo by Javier López.
+
+[MIT license](LICENSE.txt).

package/docs/api.md

@@ -0,0 +1,151 @@
+# Andamio API reference
+
+All view, model, collection, router, and application classes support Backbone's `extend` method.
+`Andamio.$` reads and writes `Backbone.$`.
+
+## Model and Collection
+
+`Andamio.Model` extends `Backbone.Model`.
+Its `defaults` include `ready: false`. Defaults merge across the prototype chain, with child values taking precedence.
+The merge is shallow. A function-valued `defaults` runs with the model as `this`.
+Model options are available as `model.options`.
+
+`setReady()` sets the `ready` attribute to `true`.
+`isReady()` returns `true` by default. A subclass can override it to use `this.get('ready')` or another readiness condition.
+`load()` does nothing by default. A router calls it with the matched route parameters.
+
+`computedProperties` maps names to functions or constant values.
+A computed function runs with the attributes object as `this`.
+`get(name)` evaluates the computed value. `toJSON()` includes the evaluated value.
+Computed functions do not become attributes. They do not emit separate change events.
+A computed name takes precedence over a stored attribute with the same name.
+
+```js
+var Person = Andamio.Model.extend({
+	computedProperties: {
+		fullName: function () { return this.first + ' ' + this.last; }
+	}
+});
+```
+
+`Andamio.Collection` extends `Backbone.Collection`. Its model is `Andamio.Model`.
+Its `load()` does nothing by default.
+
+## View and ItemView
+
+`Andamio.View` extends `Backbone.View`.
+`close()` closes tracked subviews and region views, removes the element, and stops event listeners.
+`remove()` performs the same cleanup. Repeated calls have no further effect.
+`render()` restores declarative event handlers when a closed view reopens.
+Custom render methods can call `Andamio.View.prototype.render.call(this)` to restore these handlers.
+Custom listeners created in `initialize()` require their own setup when a view reopens.
+
+`modelEvents` and `collectionEvents` map event names to handler method names or callback functions.
+A string can contain several method names separated by spaces.
+Either map can be a function that returns the map.
+`delegateEvents()` replaces previous declarative bindings.
+`undelegateEvents()` removes declarative DOM and data bindings.
+
+`addSubview(key, view)` tracks a view instance or creates a view from a constructor.
+Replacing a subview closes the previous view.
+The `subviews` configuration can contain constructors or instances.
+Each parent has its own configuration map. Instances supplied on a prototype still refer to the same view, so use constructors for independent subviews.
+Subview factories create new instances when a closed parent renders again.
+Existing instances can render again if their lifecycle supports reuse.
+
+`Andamio.ItemView` adds template rendering.
+`template` is a function that receives serialized data and returns HTML.
+The model supplies data when present. Otherwise, a collection supplies `{items: collection.toJSON()}`.
+A view with neither supplies `{}`.
+`serializeData()` can override this behavior.
+
+`render()` renders the template, creates configured subviews, binds regions, resolves UI selectors, and calls `afterRender()`.
+Rendering again closes views in the previous regions before it replaces the HTML.
+`ui` maps names to selectors. After render, each value is a jQuery object scoped to the view.
+Closing the view restores the selectors.
+Each descendant with a `data-region` attribute creates an entry in `view.regions` with that attribute's name.
+Region names must be unique within a view.
+
+A prototype `model` or `collection` constructor creates an instance during view construction.
+A `collectionView` constructor creates a tracked subview named `collectionView` when the item view has a collection.
+The item view passes that collection to the subview. The parent places the subview through a region or its own rendering code.
+
+## CollectionView
+
+`Andamio.CollectionView` extends `Andamio.View`.
+`itemView` is the constructor for each model's child view.
+`itemViewOptions` is an options object or a function of the model and its index.
+The child receives the model plus these options.
+`children` contains child views in collection order.
+
+The view responds to collection `add`, `remove`, `reset`, and `sort` events.
+A full render closes existing children and builds new children in a document fragment.
+Rendering calls `afterRender()` when defined.
+`isEmpty()` returns `true` when the collection is absent or empty.
+`closeChildren()` closes and removes all child views.
+
+`buildItemView`, `renderItemView`, `appendHtml`, and `appendBuffer` provide rendering extension points.
+Custom `appendHtml` methods receive the collection view, child view, and index.
+Custom methods must support the buffering state during full renders.
+
+## Region
+
+A region accepts an `el` name, a DOM element, or a `$el` jQuery object.
+An `el` string matches a `data-region` value. It is not a CSS selector.
+A region must resolve to exactly one element.
+
+`show(view)` renders and inserts the view. It closes the previous view when the view changes.
+It emits `show` with the view, then calls `onShow(view)` when defined.
+`currentView` contains the shown view before these notifications.
+`close()` closes or removes the current view and clears `currentView`.
+It calls `onClose()` when defined.
+`reset()` closes the view and clears the cached DOM lookup.
+Regions mix in `Backbone.Events`. `stopListening()` releases listeners that the region created.
+
+## Router
+
+`Andamio.Router` extends `Backbone.Router` with an array of route objects.
+Each route has `url` and either `view` or `redirectTo`.
+`url` is a Backbone route pattern or an array of patterns.
+`name` is optional. The first declared matching route has priority.
+
+```js
+var Router = Andamio.Router.extend({
+	routes: [
+		{url: 'tasks/:id', name: 'task', view: TaskView},
+		{url: '', name: 'home', view: HomeView},
+		{url: '*path', redirectTo: ''}
+	]
+});
+```
+
+A match creates a new view, then calls its model's `load()` or its collection's `load()`.
+The model takes precedence when both are present.
+The data object also receives `urlParams`.
+Backbone supplies decoded path parameters and a final query-string argument.
+Loading is synchronous from the router's perspective. A returned promise does not delay navigation.
+Apps handle loading indicators, errors, and cancellation in their own models and views.
+
+The router emits `navigate(view, url, urlParams)` with the matched pattern.
+A redirect uses `trigger: true` and `replace: true`. An empty redirect target is valid.
+`close()` removes this router's history handlers and stops its listeners.
+Closing a router does not stop Backbone's shared history.
+
+## Application
+
+`new Andamio.Application(options)` copies configuration and creates `vent`, a Backbone event emitter.
+The default `container` is the `main` selector. The default page region `el` is `page`.
+
+`start({appView, router})` accepts constructors or instances.
+It renders the app view in the container, connects router navigation to the page region, and starts Backbone history.
+`historyOptions` supplies Backbone history options.
+If the fragment is empty, a route with `default: true` supplies the initial URL.
+For URL aliases, the first alias is the default URL.
+`initialize()` runs after this startup sequence.
+`start()` without options calls only `initialize()`.
+
+`vent` emits `navigate` with the shown page view.
+`stop()` closes the page region and app view, closes an Andamio router, stops history, and releases application listeners.
+A plain Backbone router supplies no `close()` method, so its history handlers remain its owner's responsibility.
+Only one Backbone history can run at a time.
+Starting an app router while history is active throws before it replaces the app view.

package/docs/audit-summary.json

@@ -0,0 +1,34 @@
+{
+  "date": "2026-10-08",
+  "baselineCommit": "97546c0",
+  "before": {
+    "root": {
+      "info": 0,
+      "low": 1,
+      "moderate": 2,
+      "high": 13,
+      "critical": 6,
+      "total": 22
+    },
+    "build": {
+      "info": 0,
+      "low": 2,
+      "moderate": 3,
+      "high": 23,
+      "critical": 7,
+      "total": 35
+    }
+  },
+  "after": {
+    "info": 0,
+    "low": 0,
+    "moderate": 0,
+    "high": 0,
+    "critical": 0,
+    "total": 0
+  },
+  "commands": [
+    "npm install --package-lock-only --ignore-scripts",
+    "npm audit --json"
+  ]
+}

package/docs/review.md

@@ -0,0 +1,129 @@
+# Project review, 8 October 2026
+
+This review covers every source module, the generated library, both original package manifests, the Grunt tasks, and the README.
+The starting commit was `97546c0`. The working tree was clean.
+The project had no tests, no dependency lockfile, no package entry point, and no completed API documentation.
+
+## Confirmed defects and fixes
+
+| Area | Original behavior | Change |
+| --- | --- | --- |
+| Module loading | The outer factory used `_` and `Backbone` before CommonJS or AMD resolved them. Requiring the package also had no `main` entry. | Resolve dependencies before initialization. Add the package entry. Test browser, CommonJS, AMD, and minified loading. |
+| DOM library | Source modules referenced a global `$` even when Backbone had its own DOM library. `Andamio.$` was a stale copy. | Use `Andamio.$`, which reads and writes `Backbone.$`. |
+| Model defaults | Construction mutated prototype defaults. Parent defaults overwrote child values. Function-valued defaults were not merged correctly. | Merge defaults into a fresh instance object. Child values take precedence. |
+| Computed properties | Functions became raw attributes and remained functions in serialized data. | Evaluate computed values in `get()` and `toJSON()`. Use current attributes as the callback context. |
+| Data event bindings | Repeated `delegateEvents()` calls added duplicate listeners. Function-valued event maps were unsupported. | Store the actual callbacks and replace previous bindings. Validate handlers before binding. |
+| Event removal | A missing handler could call `stopListening` with an undefined callback and remove unrelated listeners. | Skip unresolved handlers during unbinding. |
+| Shared view configuration | Cleanup deleted keys from shared UI and subview maps. Later instances lost their configuration. | Keep instance maps and restore selectors without mutating shared configuration. |
+| Subviews and regions | Late subviews could disappear on rerender. Replacing a subview did not close it. Region views survived replacement of their HTML. | Track additions, close replaced subviews, and close previous region views before rerender. |
+| View removal | Backbone's `remove()` bypassed Andamio child cleanup. Closed views lost declarative handlers on reuse. | Make `remove()` perform lifecycle cleanup. Restore declarative handlers when render reopens a view. |
+| Collection order | Insertion at index zero appended the view at the end. Sort events did not update the DOM. | Keep children and DOM in collection order. Render after sort. |
+| Collection render failure | A child template exception left buffering active and retained child views. | Close partial children and reset the buffer before propagating the error. |
+| Region lifecycle | `onShow` omitted the view argument. Showing an already closed current view could leave its element detached. `close()` retained an externally closed view. | Pass the view, reattach it when required, and clear stale references. |
+| Region lookup | Missing or multiple targets failed silently. Region names became CSS selector text. Duplicate names overwrote regions. | Require one target, compare names literally, and reject duplicate names in a view. |
+| Route matching | Later generic routes could override earlier specific routes. Aliases reported the first alias instead of the matched pattern. Empty redirect targets were ignored. | Preserve declaration priority, use a callback per alias, and accept empty redirects. |
+| Application lifecycle | `start()` without arguments failed. Default alias arrays passed directly to navigation. There was no shutdown method. | Accept omitted options, choose the first default alias, support history options, and add `stop()`. |
+| Build template | The separate CoffeeScript build referenced missing app files and an undefined `tplmin` task. | Replace it with a runnable task sample and a small HTTP server. |
+
+Three defects were reproduced directly against the original generated build with current Backbone and jQuery.
+A child default of `child` became `parent`.
+One change event called its handler three times after two explicit delegations.
+Inserting `A` before `B` produced DOM text `BA`.
+
+## Dependency and security results
+
+The initial audits used `npm install --package-lock-only --ignore-scripts`, followed by `npm audit --json`, in each original package directory.
+The audit counts include vulnerable packages reached through other dependencies. The two original graphs overlap, so their counts must not be added.
+
+| Dependency graph | Low | Moderate | High | Critical | Total |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Original library build | 1 | 2 | 13 | 6 | 22 |
+| Original app build template | 2 | 3 | 23 | 7 | 35 |
+| Updated locked project | 0 | 0 | 0 | 0 | 0 |
+
+The original vulnerable paths included Grunt, JSHint, UglifyJS, Lodash, Underscore, and old filesystem and HTTP utilities.
+The update removes the obsolete Grunt dependency graphs instead of overriding their transitive packages.
+The new build uses Node filesystem APIs and Terser.
+The project has a committed lockfile, ESLint, CI, and Dependabot configuration for npm and GitHub Actions.
+The CI actions use verified release commit hashes.
+
+The development dependencies were checked against the npm registry's stable `latest` tags on the review date.
+
+| Dependency | Version |
+| --- | --- |
+| Backbone | 1.6.1 |
+| Underscore | 1.13.8 |
+| jQuery | 4.0.0 |
+| jsdom | 30.1.2 |
+| Terser | 5.51.2 |
+| ESLint | 10.12.0 |
+| @eslint/js | 10.0.1 |
+| globals | 17.13.0 |
+
+Peer dependency ranges require current Backbone and Underscore. jQuery 3.7.1 remains supported alongside jQuery 4.
+The [jQuery 4 release notes](https://blog.jquery.com/2026/01/17/jquery-4-0-0/) describe its compatibility changes.
+The [Backbone reference](https://backbonejs.org/) defines the upstream model, router, history, and view contracts.
+A zero audit result means that npm reported no known advisories for this locked graph at the review time.
+It does not establish that application templates, remote data, or host app code are safe.
+
+## Validation
+
+`npm run check` runs ESLint and 30 tests with Node coverage.
+The library bundle has approximately 96% line coverage and 91% branch coverage.
+The combined report includes the development server and has approximately 95% line coverage.
+VM-based browser and AMD checks execute both readable and minified bundles.
+The coverage tool does not attribute those VM executions to the readable bundle, so some loader lines appear uncovered.
+
+All 30 tests passed in each local compatibility combination.
+
+| Node version | jQuery 3.7.1 | jQuery 4.0.0 |
+| --- | --- | --- |
+| 22.23.3 | Passed | Passed |
+| 24.21.0 | Passed | Passed |
+| 26.11.1 | Passed | Passed |
+
+These runtimes were installed in temporary directories. The user's global Node installation was not changed.
+The initial review used local validation. The release also requires the GitHub CI matrix to pass.
+
+The tests cover module loading, default inheritance, computed data, template escaping, data and DOM events, view reuse, subview cleanup, regions, collection order, render failures, route parameters, redirects, and application shutdown.
+The sample integration test serves actual dependencies over HTTP.
+It adds a task containing HTML, checks that the HTML remains text, completes a task, navigates away and back, removes a task, and follows an unknown route.
+
+The sample also passed a manual check in the Codex browser.
+Task creation and completion updated the visible count.
+Navigation preserved task state. The browser reported no warning or error messages.
+`npm pack --dry-run` checks the package file list.
+The build has no date-dependent banner and produces deterministic outputs.
+CI checks that a rebuild leaves the committed bundles unchanged.
+
+## Compatibility changes before a release
+
+This release uses the package name `andamiojs` and version `1.0.0`.
+Version `1.0.0` starts the release history for the new npm package name.
+The repository retains its historical `1.2.8` Git tag.
+The compatibility notes below describe changes from that historical code.
+The package name replaces `backbone.andamio`. Browser bundles now use `lib/andamio.js`, `lib/andamio.min.js`, and `lib/andamio.map`.
+
+- The development tools require Node `^22.22.2 || ^24.15.0 || >=26.0.0`. `.nvmrc` selects the current Node 24 release.
+- Older Backbone and Underscore versions are outside the declared peer ranges.
+- The Grunt entry points and the incomplete `build/` template are removed. The npm scripts replace them.
+- Child defaults now override parent defaults.
+- Computed properties return values and do not appear as raw functions in `attributes`.
+- The first matching route in the array wins. Place specific routes before catch-all routes.
+- Missing, ambiguous, or duplicate regions now throw descriptive errors.
+- `remove()` closes child views. Code that intentionally detached a live view with `remove()` needs a different operation.
+- Custom listeners created in `initialize()` are not recreated automatically when a closed view reopens.
+
+## Remaining opportunities
+
+These items need an API or product decision. They are not hidden test failures.
+
+1. Add a network sample for asynchronous `load()`. The router currently navigates immediately and does not await a promise. Cover failed fetches, late responses after navigation, and cancellation before defining a framework policy.
+2. Add browser CI for navigation focus, keyboard interaction, and narrow viewports. The current DOM integration test does not verify layout or every browser's event behavior.
+3. Add a persistent sample if the project needs to teach storage or server integration. The task sample deliberately stores data in memory.
+4. Consider an ESM entry and TypeScript declarations when there is a consuming app. The current package uses a CommonJS entry plus browser and AMD builds.
+5. Define whether computed values need their own change events and whether `isReady()` should use the `ready` attribute. Existing readiness behavior remains available for subclasses to override.
+6. Expand collection rendering tests before adding empty views, filtered lists, or nested collection containers. The current implementation rebuilds children on sort and reset.
+7. Decide whether routers should support instance reuse after `close()` and cleanup of manually registered routes. Current cleanup tracks routes from the configured array.
+
+Before publication, review these compatibility changes and run the consuming app against the new build.