Hello, ${name}
`,\n});\nGreeting.setDomApi(LitDomApi);\n\nconst greeting = new Greeting({ model: { name: 'Sam' } });\ngreeting.render();\ngreeting.destroy();\n```\n\nThis uses the default DataApi, which serializes plain values unchanged. Observable Models/Collections need their [DataApi configuration](/docs/integrations/setup.md#configure-once). Data changes do not automatically render a View; select the events and response explicitly.\n\n## Root attributes\n\n`renderAttributes()` reevaluates `attributes`, `id`, and `className`, applies them to `el`, and returns the View. It does not render a template, rebuild children, rebind UI, or emit render events. It does nothing while destroying or destroyed.\n\nWhen creating a root, Marionette applies these declarations once. A supplied root is untouched until an explicit `renderAttributes()`. The native DomApi removes attributes whose value is `null`, leaves `undefined` and omitted keys unchanged, and stringifies other values. `id` and `className` override the corresponding entries in `attributes` when declared. Calling `render()` does not refresh these root declarations.\n\n## UI bindings\n\nDeclare `ui` as `{ name: 'selector' }` or a function returning that map. After binding, `ui` contains query results; Marionette retains the selectors for rebinding. Use `@ui.name` in DOM event/trigger keys and View Region selectors to reuse them.\n\n| Method | Contract |\n| --- | --- |\n| `$(selector)` | Queries descendants of `el`; the root itself is excluded by the native DomApi. Returns the provider's query type (native: static `NodeList`). |\n| `getUI(name)` | Returns the bound query result or `undefined` for an unknown name. Throws if no UI map was declared or it has not been bound. Use `[0]` when the first native element is needed. |\n| `bindUIElements()` → `this` | Resolves the UI map and queries the current DOM, including Behavior UI. Normally automatic after rendering or construction with existing contents. No-op while destroying/destroyed. |\n| `unbindUIElements()` → `this` | Releases query bindings and restores the selector declarations, including Behavior UI. Destruction does this automatically. |\n| `normalizeUIString(value, bindings?)` | Returns a string with `@ui.name` references replaced by selectors. |\n| `normalizeUIKeys(map, bindings?)` | Returns a new map with normalized keys; nullish input returns `{}`. |\n| `normalizeUIValues(map, property?, bindings?)` | Normalizes string values or a named property of object values **in place** and returns the same map. |\n\nNormalization uses the View's original selector map unless an explicit map is provided. An empty or undeclared `@ui` name throws. Bound queries are snapshots; manually changed contents need rebinding before querying through `getUI` again.\n\n## DOM events\n\n`events` maps `'event selector'` to a callback or View method name. For example, `events: { 'click .save': 'save' }` calls the View's `save` handler for a delegated click. Omit the selector to listen on the root. Callbacks run with the View as `this` and receive the DOM event.\n\nWith the native delegator, `event.currentTarget` is the View's root element. `event.delegateTarget` is the nearest matching descendant on the event path: use it to read the control matched by the selector, even when a click originated inside that control. The root is not a selector match. `focus` and `blur` use capture.\n\n`triggers` maps the same DOM keys to a View event name or `{ event, preventDefault, stopPropagation }`. A trigger calls `view.triggerMethod(eventName, view, domEvent, ...extraArguments)`. Both prevention flags default to `true`; set either to `false` to allow that browser behavior. `events` handlers do not receive these automatic prevention calls.\n\nBoth maps may be functions evaluated on the View. `@ui` selectors are resolved before delegation. A missing named handler is an error.\n\n| Method | Contract |\n| --- | --- |\n| `delegateEvents(events?)` → `this` | Removes existing View/Behavior DOM handlers, refreshes child event maps, then binds the explicit event map or current `events`, plus current `triggers` and Behavior DOM handlers. Use after changing declarations. |\n| `undelegateEvents()` → `this` | Releases View and Behavior DOM handlers. |\n\nBoth methods are no-ops while destroying/destroyed. Construction delegates automatically; destruction releases handlers automatically. Detaching a live View preserves its DOM bindings. Rendering does not reread changed event declarations.\n\n## Data bindings\n\n`modelEvents` and `collectionEvents` map source event names to callback functions or View method names; either map may be returned from a function. Bindings use the configured `Data.subscribe`, preserve source arguments, and invoke callbacks with the View as `this`. A plain object/array can supply template data, but the default DataApi requires an `on`/`off` source when an event map is present. Use the appropriate adapter for observable data.\n\n`delegateEntityEvents()` releases previous model/collection bindings, then binds current declarations, including Behaviors, and returns the View. `undelegateEntityEvents()` releases those subscriptions and returns the View. Construction binds them after `initialize`; destruction releases them.\n\nReplacing a View's model or collection after construction does not change its existing subscriptions. Assign the new source or event map, then call `delegateEntityEvents()` to release the old bindings and observe the current declarations. Repeated delegation replaces bindings rather than accumulating them. Use `undelegateEntityEvents()` when observation should stop without rebinding. Render explicitly if the new source should be displayed immediately.\n\nObservable model changes do not automatically update the View's rendered contents. Choose the response in `modelEvents` or `collectionEvents`: for a small View, `modelEvents: { change: 'render' }` rerenders on change. On a layout View, that also resets its Regions and destroys their children; see [View rendering](/docs/api/view.md#rendering-and-status).\n\nThese bindings do not own or destroy the model/collection. State bindings have separate ownership and delivery rules: see [state](/docs/api/shared/state.md).\n\n## Child events\n\nThe owning View/CollectionView can handle events from its immediate managed children:\n\n| Declaration | Behavior |\n| --- | --- |\n| `childViewEvents: { eventName: handler }` | Calls a parent method name or callback with the parent as `this` and the child's original event arguments. |\n| `childViewTriggers: { eventName: parentEvent }` | Calls `parent.triggerMethod(parentEvent, ...originalArguments)`. |\n| `childViewEventPrefix: 'child'` | Forwards every child event as `child:eventName` through `triggerMethod`. Defaults to `false`; set `false` to disable prefix forwarding. |\n\nEach declaration may be a function evaluated on the parent. When all apply, the order is the mapped handler, mapped parent event, then prefixed event. No child argument is added: a DOM `triggers` event already supplies its View, while `child.trigger('selected', id)` supplies only `id`. Define explicit mappings at each level when forwarding through nested composition.\n\nThe maps are prepared during construction and refreshed by `delegateEvents()`. Region/CollectionView ownership establishes forwarding and releases it when the child leaves. See [subscription cleanup](/docs/api/shared/events.md#cleanup) for native destruction and listener ownership.\n\n## Behavior composition\n\n`behaviors` accepts an array or named object containing Behavior constructors or `{ behaviorClass: BehaviorClass, ...options }` entries. A function can return either shape. Names organize the definitions; the View does not expose a public lookup-by-name API. Nested Behavior definitions are composed onto the same host.\n\nMarionette constructs each Behavior with `(options, view)`. Behaviors share the host's fixed element and data sources; their DOM events, triggers, UI and entity bindings join the host's lifecycle. Host UI selectors override Behavior selectors with the same name. Behavior DOM triggers emit on the host. Host events are forwarded through each Behavior's `triggerMethod`, including an initialization notification after the host is initialized. Host destruction releases Behaviors and their owned state; it delivers the host's destroy notification to them.\n\nThis defines the View's accepted composition option. The [Behavior reference](/docs/api/behavior.md) covers its own APIs, forwarded hooks, and direct versus host destruction.\n\n## Class configuration\n\nConfigure a subclass before creating its instances. Each setter returns that class and changes its prototype configuration. Descendants inherit configuration unless they override it; changing a subclass does not modify the parent class.\n\n| Static method | Effect |\n| --- | --- |\n| `setRenderer(renderer)` | Replaces `_renderHtml` with a function `(template, data) → output`, invoked with the View as `this`. Pass a usable renderer; omitting it assigns `undefined` and does not restore the default. |\n| `setDomApi(mixin)` | Shallow-merges methods over the class's existing `Dom` provider, preserving unspecified methods. Controls root creation, queries, attributes, content insertion, and DOM attachment operations. |\n| `setDataApi(mixin)` | Shallow-merges methods over `Data`. A View uses `serialize`, `models`, and `subscribe`; CollectionView also uses collection identity/observation operations. |\n| `setStateApi(mixin)` | Shallow-merges methods over `State`. See [state configuration](/docs/api/shared/state.md). |\n| `setEventDelegator(delegator)` | Replaces `EventDelegator`. Its `delegate({ eventName, selector, handler, rootEl })` must return the cleanup function used when undelegating/destroying. |\n\n`Dom`, `Data`, `State`, `EventDelegator`, and `_renderHtml` are the instance-visible configuration slots. Prefer setters for class configuration; `Dom`, `Data`, `State`, `EventDelegator`, `_renderHtml`, and `monitorViewEvents` are not recognized constructor options. `_renderHtml` is the renderer extension slot despite its underscore; `attachElContent` is the insertion extension point.\n\nThe [setup recipe](/docs/integrations/setup.md#configure-once) uses top-level setters to configure all relevant default classes together. See [runtime configuration](/docs/api/runtime.md) for isolated families and setter scope, [rendering/DOM providers](/docs/api/providers/dom.md) for authoring interfaces, and [data/state providers](/docs/api/providers/data.md) for observation and disposal.\n\n## Types\n\nImport these types from `marionette`:\n\n- `DOMEvents`: event-key map to callbacks or method names. `DOMTriggers`: event-key map to `TriggerDefinition`; `TriggerOptions` describes object triggers.\n- `UISelectors`: string selector map. `UIBindings`: that map or a function returning it. Query results follow `ViewInstance`'s `Query` type.\n- `Bindings`: source event map used by model, collection, and state bindings.\n- `BehaviorDefinition`, `BehaviorDefinitions`, `BehaviorOptionsDefinition`: the constructor/options entry, collection of entries, and object-entry shape.\n- `Renderer${message}
`,\n templateContext() { return { message: this.message }; }\n});\nLitMessage.setDomApi(LitDomApi);\nconst MorphMessage = View.extend({\n template: () => 'Hello
'\n});\nMorphMessage.setDomApi(MorphdomDomApi);\nconst lit = new LitMessage();\nlit.message = 'Hello';\nlit.render();\nconst morph = new MorphMessage().render();\n```\n\n### Morphdom\n\n`MorphdomDomApi` supplies `setContents(el, html)` for an HTML string, `null`, or `undefined`; nullish values clear the contents. An empty root receives the HTML directly. Existing contents are reconciled with Morphdom's `childrenOnly` behavior and normal matching rules, including element IDs. Matching elements can survive repeated renders; the root always remains. Use trusted HTML or an application template system that handles untrusted values safely.\n\n### Lit HTML\n\n`LitDomApi` supplies `setContents(el, value)`, `notifyAttach(el)`, and `notifyDetach(el)`. Templates can return Lit values such as `html` results. The first explicit render replaces existing contents; it does not hydrate them. Subsequent renders update the same marked range.\n\nThe notification methods connect/disconnect Lit directives through the stored root part. Marionette's attachment monitoring calls them when managed through Regions; keep `monitorViewEvents` enabled on the View and its ancestors. If monitoring is disabled or its handlers are removed, the application must deliver these notifications itself. Overrides of lifecycle methods must preserve parent behavior.\n\nDetach and destruction disconnect directive resources. Destruction can also release resources from a failed explicit render; failed construction does not roll back initialization. Release the previous View owner before adopting its element in another View. Lit event handlers use Lit's element receiver; use a closure when a handler needs View or application state.\n\n## jQuery\n\n`JQueryDomApi` overlays these DOM operations; it does not create `$el` or change View ownership. `getUI(name)` returns a jQuery collection under this adapter. If the application needs `$el`, initialize it with `$(this.el)`; the root is fixed for the View's lifetime.\n\n| Method | Contract |\n| --- | --- |\n| `findEl(el, selector)` | Returns a jQuery collection of descendants. Supports `Element` or `Document` roots. |\n| `detachEl(el)` | Detaches the element while retaining jQuery data and listeners. |\n| `setContents(el, html)` | Uses jQuery `.html()`; a nullish value clears contents. |\n| `appendContents(el, contents)` | Appends accepted jQuery HTML/node/collection content to an Element or DocumentFragment. |\n| `detachContents(el)` | Detaches children while retaining their jQuery data and listeners; keeps the root. |\n\n```js\nimport { View } from 'marionette';\nimport $ from 'jquery';\nimport JQueryDomApi from '@mnjs/adapters/dom/jquery';\n\nconst Controls = View.extend({\n template: () => '',\n ui: { open: 'button' }\n});\nControls.setDomApi(JQueryDomApi);\nconst view = new Controls().render();\nconst button = view.getUI('open');\nbutton.attr('aria-label', 'Open details');\n```\n\nTo combine jQuery query/attachment operations with Lit or Morphdom contents, call `setDomApi` with jQuery first and the content adapter second. Setters overlay supplied methods; the last supplied implementation wins. Other DOM operations retain their configured defaults.\n\n## TypeScript\n\nThe default exports carry their provider method types. XState additionally exports `XStateActorEventOptions` and `XStateActorApiOptions${description}
\n `,\n});\n```\n\nOrdinary Lit interpolation renders these values as text, including characters such as `<`. No HTML escaping helper is needed. A View supplied with a Model receives its attributes as template data.\n\nA **provider** implements a Marionette contract such as DataApi, StateApi or DomApi. An **adapter** connects a particular library to that contract; for example, `LitDomApi` adapts Lit rendering. Installing an adapter does not configure it.\n\n## Observable data and API access\n\n`@mnjs/data` provides local observable Models and Collections. Use it alongside an API layer for fetching and persistence, or replace it with another data solution and the corresponding Marionette integration. Models and Collections do not provide an HTTP client, server synchronization, or a complete application data architecture.\n\nFor [initial feature data](/docs/api/application.md#prepare-before-showing-ui), an Application can import its API module directly, await the request in `prepareStart`, and return a Collection built from the response attributes. The successful result reaches `onStart`. If the API layer already supplies a compatible observable source, use it directly.\n\n```js\nimport { Model, Collection } from '@mnjs/data';\n\nconst item = new Model({ id: 'alpha', title: 'First item' });\nconst items = new Collection([item]);\nitem.set('title', 'Updated item');\n```\n\nUse [Model and Collection](/docs/packages/data.md) for attribute updates, membership, identity, events, and local disposal. A View can observe Model changes through `modelEvents`; CollectionView observes membership changes through DataApi. Reading data into a template alone does not subscribe to later attribute changes.\n\nUse [state ownership](/docs/api/shared/state.md) when an Application or View needs its own observable state. With StateApi configured, `createState` can return a Model whose disposal belongs to the owner. Passing `{ state }` borrows an existing source instead.\n\n\n[Canonical source](/docs/markdown/docs/integrations/setup.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/framework-migration.md", "title": "Migrate from another UI framework", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/framework-migration/", "markdownUrl": "https://marionettejs.com/docs/guides/framework-migration.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/framework-migration.md", "sourceSha256": "cc41122b1459a8390ae30e9523c97cfb0b6eb328174b597d8429067001d77101", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "b28384f7a8cc0397c46b4e6b65206e2e58cb9cd92dc55ee204360bb6d7ec29c2", "markdown": "\n\n# Migrate from another UI framework\n\nPreserve the application's observable behavior while designing a native Marionette\nownership tree. Translating each Vue component, React hook, or store into a similar\nMarionette file can preserve the old architecture's problems. Decide who owns data,\nUI, readiness, and mutations before choosing the order of implementation.\n\nThis guide targets **5.0.0**.\nUse [matching packages](/docs/quick-start.md#install-matching-packages) and their\ninstalled contracts. For an existing Marionette v4 app, use the separate\n[v4 migration guide](/docs/guides/migration.md).\n\n## 1. Inventory behavior before implementation\n\nBuild a journey matrix from the running original app and its public contracts.\nFor each journey, record the entry URL, role/permissions, inputs, visible outcomes,\nAPI methods/payloads, failure cases, and evidence. Include direct links, navigation,\nsearch/filter/sort, edits, uploads, empty states, keyboard/focus, persistence after\nreload, and work interrupted by navigation. Identify cross-feature behavior such\nas a rename appearing in both a list and an open detail panel.\n\nKeep known baseline bugs explicit: record the reproduction and decide whether to\npreserve it temporarily or fix it intentionally with a changed expectation. A\nfailing original journey is evidence, not permission to omit the feature. Separate\nobserved behavior from intended behavior where they differ.\n\nRun the original through its **public UI against a controlled backend** before\nbuilding the replacement. Reuse those same journey tests against the replacement\nby changing its base URL and startup configuration. Prefer accessible roles,\nlabels, URLs, visible state, and recorded API contracts. Avoid Vue component\ninstances, React internals, store getters, private Marionette fields, or selectors\nthat encode the old component tree. A small public test-id contract can identify\ncontrols without making their component layout part of the specification.\n\nControl test accounts, permissions, fixture reset, request delays, rejection,\nand out-of-order completion. Check that a successful edit survives reload and\nthat forbidden edits fail at the backend as well as being unavailable in the UI.\nKeep backend contract tests alongside browser journeys; local mocks cannot prove\nserver permissions or real payload compatibility. Review test changes separately:\ndo not weaken assertions or add skips to make the replacement pass. Deliberately\nbreak a representative response or interaction and confirm the test fails.\n\n## 2. Draw the final ownership tree independently\n\nUse [architecture](/docs/architecture.md) to define the target tree from domain\nlifetimes and user journeys. The old source is evidence for business rules and\nedge cases; its folders and component boundaries do not decide the final tree.\n\nFor a record workspace, distinguish lifetime ownership from screen placement:\n\n```text\nLifetime owners\nWorkspaceApplication\n├─ ShellView — persistent root UI\n└─ registered RecordApplication\n ├─ draft — shared workflow state\n └─ RecordPageView — feature root UI\nRecordService — transport, serialization and persistence contracts\n\nScreen placement\nShellView\n└─ destination Region ← RecordApplication.showView()\n └─ RecordPageView\n ├─ editor Region → TitleEditorView (borrows draft)\n └─ summary Region → SummaryView (latest loaded title)\n```\n\nWorkspaceApplication registers RecordApplication and explicitly starts/stops it;\nregistration alone neither starts nor awaits a child. ShellView owns the destination\nRegion used to place the feature's root View. Emptying that Region removes UI but\ndoes not stop the Application or end its ongoing authority: the feature owner must\nstop or destroy it when ending the run. After showing the ShellView instance `shell`, pass\n`shell.getRegion('destination')` as `region` to the child instance's\n`start({ region, id })`. The\n[asynchronous routing example](/docs/guides/routing.md#route-to-asynchronous-features) shows the\ncomplete shell-to-child handoff;\n[child Application ownership](/docs/api/application.md#child-applications) explains\nregistration and cleanup.\n\nAn Application coordinates a feature lifetime; a View owns presentation and local\ninteraction; a Region places and disposes its child. Use CollectionView for repeated\nrecords that need independent children. A View can call its model/API layer to save\na local edit; an async call alone does not justify an Application. Put shared\nworkflow decisions and work that survives panel replacement with a surviving owner.\n\nFor every source or operation, record:\n\n| Decision | Example |\n| --- | --- |\n| Owner and borrowers | RecordApplication owns its draft; editor borrows it. A shared record cache belongs to the session/service lifetime. |\n| Mutation authority | Editor updates draft title; feature coordinates publishing; service persists. Siblings emit intent instead of editing each other's DOM. |\n| Readiness | `prepareStart(options, { signal })` loads required data; `onStart` applies only the current result. |\n| Retention | Restart preserves shell/input; Region replacement destroys its outgoing View; stop destroys root UI but retains Application state. |\n| Cancellation and release | Pass preparation signal to transport. Give ongoing saves their own cancellation/concurrency policy and end external effects at their owner. |\n\n`start()` and `restart()` resolve `true` on success, `false` when superseded or\ncancelled, or when a stopping/terminal owner prevents activation. Current\npreparation or startup-callback failures reject; synchronous failures do not roll\nback completed work. `stop()` and `destroy()` are synchronous;\nnotification hooks do not await Promises. The preparation signal ends with that\noperation, so it is not an ongoing feature-lifetime signal. Avoid application side\neffects during preparation that could commit after cancellation. See\n[Application](/docs/api/application.md), [retained restart](/docs/guides/retained-restart.md), and\n[routing](/docs/guides/routing.md) for complete lifecycle/error boundaries.\n\nA supplied state source is borrowed; `createState()` establishes owned state.\nDeclare what survives panel replacement, route exit, stop, and reload separately.\nChoose one writer or an explicit conflict policy for each shared mutation. Model\nobservation and server persistence are separate capabilities: optional [@mnjs/data](/docs/packages/data.md)\nhas no `Model.save()` or `fetch()` contract. Do not assume Backbone methods.\n\n## 3. Choose the migration strategy deliberately\n\nA replacement branch can have incomplete routes while the correct architecture is\nbeing built. Full parity is the final goal; keeping a hybrid app functional at\nevery intermediate checkpoint is not a default requirement. Preserve the runnable\noriginal as the baseline and record unavailable replacement journeys honestly.\n\nChoose **leaf-first** when a leaf has a clean DOM/data boundary and its replacement\nwill be reused unchanged in the target tree. A date picker or independent panel\nmay qualify. Do not start there merely because leaves are small: dependencies on\nold stores, parent effects, or component conventions can turn every leaf into a\ncompatibility project. Build those leaves inside the replacement shell when\ncoexistence is unnecessary; hosting a leaf in the running original requires the\nbridge ownership and deletion criteria below.\n\nChoose a **native feature-family replacement** when the old tree obscures ownership\nor when no production coexistence is required. Establish the shell, service boundary,\nand one representative journey, then migrate related behavior in broad batches:\nrecord list/filter/detail; editing/validation/persistence; permission-sensitive\ncommands; navigation/recovery. Each batch includes its data, UI, effects and tests,\nrather than converting files individually. This avoids repeatedly inventing the\nsame authority and cleanup rules across dozens of components.\n\nPilot a representative risk early: an editable record with a shared list/detail,\na permission boundary, delayed readiness, navigation away, and retry. Use it to\nchallenge the ownership plan before scaling. A trivial static page is useful for\ninstallation, but does not validate migration architecture.\n\nIf production must run both frameworks, use [existing UI](/docs/guides/existing-ui.md) for an\nexplicit host boundary: one owner per DOM subtree, public inputs/events, cleanup\nbefore removing the mount, and no sibling DOM access. Record the bridge owner,\nwhy coexistence is required, the consuming routes, and the concrete condition for\ndeleting the bridge and its dependencies. Keep the bridge at that boundary rather\nthan teaching every new View the old framework's store or lifecycle.\n\n## 4. Work through a native ownership example\n\nThis invented Vue-like sketch combines readiness, UI and draft authority in a\ncomponent. It is illustrative pseudocode, not an executable Vue recipe:\n\n```text\nRecordPage.vue\n setup(): obtain route id and global store\n watch(route.id): fetch record, overwrite store, reset form\n component state: title draft and request/loading flags\n template: title editor + summary + reload button\n child callbacks: write global store and query parent's DOM\n unmount(): cancel component request\n```\n\nThe native replacement below separates readiness from local interaction. It uses\nLit for safe text interpolation and stable input updates, and observable state\nfrom `@mnjs/data`. Follow [setup](/docs/integrations/setup.md) for matching companion\npackages. `GET /records/42.json` returns `{ \"title\": string }`; API access stays in\n`loadRecord`, which can move into the application's service module. See\n[production deployment](/docs/guides/production.md#serve-direct-links-deliberately) for HTTPS\nand direct-link requirements.\n\n```js\nimport { Application, View } from 'marionette';\nimport { Model, DataApi, StateApi } from '@mnjs/data';\nimport LitDomApi from '@mnjs/adapters/dom/lit-html';\nimport { html } from 'lit-html';\nimport { live } from 'lit-html/directives/live.js';\n\nasync function loadRecord(id, signal) {\n const response = await fetch(`/records/${encodeURIComponent(id)}.json`, { signal });\n if (!response.ok) throw new Error('Could not load record.');\n return response.json();\n}\nconst PageView = View.extend({\n template: () => html`\n \n `,\n regions: { editor: '.editor', summary: '.summary' },\n triggers: { 'click .reload': 'reload' },\n}).setDomApi(LitDomApi);\nconst TitleEditorView = View.extend({\n template: ({ title }) => html`\n `,\n ui: { title: '.title' },\n events: { 'input @ui.title': 'editTitle' },\n modelEvents: { 'change:title': 'render' },\n editTitle() { this.model.set('title', this.getUI('title')[0].value); },\n}).setDataApi(DataApi).setDomApi(LitDomApi);\nconst SummaryView = View.extend({\n template: ({ loadedTitle, error }) => html`\nLoaded title: ${loadedTitle}
${error}
`,\n modelEvents: { 'change:loadedTitle': 'render', 'change:error': 'render' },\n}).setDataApi(DataApi).setDomApi(LitDomApi);\n\nconst RecordApplication = Application.extend({\n createState() { return new Model({ title: '', loadedTitle: '', error: '' }); },\n viewEvents: { reload: 'reloadRecord' },\n prepareStart({ id }, { signal }) { return loadRecord(id, signal); },\n onStart(_app, { id }, record) {\n this.recordId = id;\n const state = this.getState();\n state.set({ loadedTitle: record.title, error: '' });\n if (this.getView()) return;\n state.set('title', record.title);\n const page = this.setView(new PageView());\n page.showChildView('editor', new TitleEditorView({ model: state }));\n page.showChildView('summary', new SummaryView({ model: state }));\n this.showView();\n },\n reloadRecord() {\n return this.restart({ id: this.recordId }).catch(error => {\n this.getState().set('error', error.message);\n });\n },\n}).setStateApi(StateApi);\n\nconst mount = document.createElement('main');\ndocument.body.append(mount);\nconst app = new RecordApplication({ region: { el: mount } });\nawait app.start({ id: '42' });\n```\n\nReload repeats readiness for the **same record**. Only SummaryView updates; the\npage and editor stay owned by their Regions, and unfinished input survives. The\neditor's `ui` map gives its owned control one name instead of repeated\n`querySelector` calls. Read `getUI('title')[0]` after binding; bindings rebind on\nrender and are snapshots, so do not keep a stale element across replacement.\nThe editor observes title changes so external updates also appear. Its rerender\nretains the input through the chosen Lit integration and `live()` binding; verify\nfocus and caret behavior before substituting another renderer.\n\nCalling `start({ id: next })` on an active Application resolves `true` without\nrepeating preparation or applying the new options. This example supports restart\nonly for its current record; a different-id restart would retain the old draft\nbeside the new loaded title.\n\nA route to another record needs a deliberate draft policy: retain drafts by id,\nask before discarding, or stop/start to reconstruct. Do not use this same-record\nreload as an implicit navigation policy. This example resets the draft from loaded\ndata after stop/start, although the Application retains its state source. Preserving\ndrafts across reconstruction requires an explicit policy, such as drafts keyed by id.\nFor initial readiness failure, the caller\nhandles rejection and stops the failed run before error presentation; the\n[routing example](/docs/guides/routing.md#route-to-asynchronous-features) supplies that boundary.\n`reloadRecord` reports current lifecycle rejections, including startup-callback\nfailures; it is not a load-only error classifier. Reporting feedback does not roll\nback partial updates or establish safe recovery from callback bugs. Follow the\n[Application failure contract](/docs/api/application.md#preparation-cancellation-and-failure)\nwhen deciding the application's recovery and diagnostic policy.\n\nThis example has no save operation: adding one requires the service's write\ncontract and a decision about cancellation, duplicate submissions, conflict, and\nwhich surviving owner receives completion. See [local editing](/docs/guides/local-editing.md).\n\n## 5. Use separate architecture and behavior gates\n\nAt each feature-family checkpoint, review **source** for the intended ownership,\nmutation authority, cancellation, stable UI bindings, and removed compatibility\npaths. Then run the reusable **behavior tests** against the integrated replacement.\nPassing interactions can hide a replacement that still delegates to the old app;\na clean source tree can still break a journey. Neither gate replaces the other.\n\nKeep one short checkpoint record in the application's existing project notes:\n\n```text\nBatch: record editing\nDecisions: feature owns draft; service persists; same-record reload retains editor\nEvidence: exact revision/packages, commands, environment, journey results\nOpen failures: permission revocation during save; unimplemented bulk edit route\nCoverage boundary: real backend tested for save; conflict path still mocked\nNext: resolve conflict policy, complete bulk edit, rerun list/detail/save together\n```\n\nExercise true integration across feature families: direct URL → readiness → edit\n→ save → list/detail update → navigation → reload; also auth expiry and permission\nchanges, rapid route changes, slow responses, stop/start, and repeated attachment\nwhere widgets/listeners depend on it. Use a real browser for focus, keyboard,\nhistory and editable-state behavior. Component tests and screenshots support this\ncoverage but do not establish it. Report baseline failures separately from new\nregressions and explicitly unimplemented routes. Test counts and converted file\ncounts are progress measures, never completion claims.\n\n## 6. Audit the final replacement\n\nThe replacement is complete when every required journey passes its recorded\nexpectation, updated for documented intentional changes, and every baseline bug\nhas a recorded disposition. No required route remains unimplemented; checkpoint\nfailures are resolved or recorded as intentional behavior changes. Re-run the full\njourney matrix and backend contract checks against the production entrypoint and controlled backend, including the interruption and\nfailure cases. Review changed expectations independently from implementation.\nAudit source imports,\ndynamic imports, route lazy chunks, build plugins, manifests/lockfile, and the\nactual generated bundle/module graph. Remove the old framework, adapters, stores,\nbridges, obsolete entrypoints, unused styles, and dependencies when no required\nconsumer remains. A green suite does not prove removal; verify the new app cannot\nreach or invoke the old implementation, including through lazy routes.\n\nPreserve applicable public licenses and attribution for reused source/assets.\nUse public examples or authorized project code; do not copy private application\nsource into public documentation or fixtures. The public\n[Marionette RealWorld example at a pinned revision](https://github.com/marionettejs/marionette-realworld-example-app/tree/34ceaa5987c1e80dfa6b6f2285cb9fcb5296ce04)\nis a reference to inspect, not proof of parity for another application.\n\n## Agent checklist\n\n- Pin original/replacement revisions, package contract, backend fixtures and known bugs.\n- Run portable journey tests on the original; check their ability to catch breakage.\n- Define target owners, borrowers, writers and cancellation before converting code.\n- Choose leaf-first or native feature batches with a reason; document bridge deletion only if needed.\n- Pilot representative risk, then complete related behavior in broad batches.\n- Review architecture and test changes separately from integrated behavior results.\n- Record decisions, exact evidence, incomplete routes and open failures at checkpoints.\n- Complete every required journey against recorded expectations, documenting intentional changes; resolve open failures and prove old-framework removal in imports, dependencies and bundles.\n\n## Further reading\n\n[Playwright best practices](https://playwright.dev/docs/best-practices) covers\nuser-facing locators, isolated test state, controlled data, and retrying assertions\nfor the reusable browser journeys.\n\n[Addy Osmani's Brownfield Agentic Engineering](https://addyosmani.com/blog/brownfield-agentic-engineering/)\nexplains characterization, durable context, and completing migration units with\nold dependencies removed.\n[Anthropic's migration guide](https://claude.com/blog/ai-code-migration)\ndescribes a portable behavior judge, checking that it detects broken behavior,\nand distinguishing translation from architectural redesign. Apply those verification\nprinciples to UI journeys while using Marionette's installed contracts for the\nreplacement architecture.\n\n\n[Canonical source](/docs/markdown/docs/guides/framework-migration.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/migration.md", "title": "Migrate from Marionette v4", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/migration/", "markdownUrl": "https://marionettejs.com/docs/guides/migration.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/migration.md", "sourceSha256": "5e0f72c9da11b024c6cbba37d676ebbcc05548ca53b8f4d12a0215c3f67da7a9", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "6b7c3cab3bd08d8323a445af2180bf35f69273e4f9fb7fd256240ed965c88db5", "markdown": "\n\n# Migrate from v4 to v5\n\nUpgrade one application and its messaging participants together. Start from a working v4 application with checks for its important interactions, then change installation and integration setup before changing feature ownership. This guide covers common v4 application code; custom providers and low-level overrides should also be checked against their [reference contracts](/docs/api.md).\n\nFor an agent-assisted upgrade, give the agent this guide and the\n[agent entrypoint](/docs/agents.md), plus the application's entrypoint and existing\nbehavior checks. Have it inspect the installed package's docs, migrate one\nrepresentative feature, and run the checks in section 4 before repeating the\nchanges elsewhere. Keep data-layer replacement separate from the framework\nupgrade unless the application needs both.\n\n## 1. Replace installation and configure integrations\n\nReplace `backbone.marionette` with the matching `marionette` v5 release. Follow [package installation](/docs/quick-start.md#install-matching-packages) for the current package artifacts and companion versions. If you already use named imports, change their package path. Replace default namespace imports with named imports: `import { Application, View, MnObject, Radio } from 'marionette'`. The former namespace's `Object` alias becomes `MnObject`.\n\nCore supplies native DOM operations and accepts plain objects and static arrays. Backbone, jQuery, and Underscore are no longer required by core. Remove a dependency only when the application itself no longer uses it.\n\nConfigure the data sources and rendering your application actually uses in one setup module, imported before constructing consumers:\n\n- An existing Backbone application can retain its Models, Collections, and persistence operations. Import `BackboneApi` from `@mnjs/adapters/backbone`, then call `setDataApi(BackboneApi)`. Call `setStateApi(BackboneApi)` separately when owners use Backbone state. This connects existing data without changing Backbone objects or their native methods.\n- For new observable data, [@mnjs/data](/docs/packages/data.md) provides local Models and Collections. Use its `DataApi` and, when needed, `StateApi` as described in [setup](/docs/integrations/setup.md). Fetching and persistence remain separate concerns. Replacing Backbone's `save`, `fetch`, or server-side `destroy` requires a deliberate data-layer change.\n- The default renderer calls a template function with its data; it does not compile template selector strings. Preserve an application template compiler through `setRenderer` when needed. For Lit templates, configure `LitDomApi` from `@mnjs/adapters/dom/lit-html` with `setDomApi`.\n- Code requiring jQuery query or content methods can explicitly select `JQueryDomApi` from `@mnjs/adapters/dom/jquery`. This adapter does not create `$el` or restore jQuery event delegation. Its peer requirement is jQuery 4; verify application plugins before selecting it.\n\nSee [adapters](/docs/packages/adapters.md) for installation, provider behavior, and tested peers. Ordinary applications can use the default runtime setters; [runtime configuration](/docs/api/runtime.md) also supports class-specific setup and isolation.\n\nReplace every `backbone.radio` import with the selected runtime's Radio in the same upgrade, including publishers and requesters outside Marionette classes. The old and new buses have independent channels, so leaving either participant on the old bus disconnects communication. Default-runtime code can import `Radio` from `marionette`; isolated runtime code must use that runtime's `Radio`. Replace `Radio.DEBUG = true` with `Radio.setDebug()`. `Radio.log` and `Radio.debugLog` remain assignable logging hooks. See [Radio](/docs/packages/radio.md) for registry scope and request/reply methods.\n\n### Import and configure existing Backbone data\n\nThis upgrade retains Backbone persistence. Change every Radio participant together:\n\n```diff\n-import Mn from 'backbone.marionette';\n-import Radio from 'backbone.radio';\n+import { View, Radio, setDataApi } from 'marionette';\n+import BackboneApi from '@mnjs/adapters/backbone';\n+setDataApi(BackboneApi);\n\n-const Editor = Mn.View.extend({ modelEvents: { change: 'render' } });\n+const Editor = View.extend({ modelEvents: { change: 'render' } });\n```\n\n### Replace jQuery event assumptions\n\nNative delegated events require explicit cancellation. `getUI()` still returns a\ncollection, so select its element before using DOM properties:\n\n```diff\n onSave(event) {\n- const title = this.getUI('title').val();\n+ event.preventDefault();\n+ const title = this.getUI('title')[0].value;\n this.model.save({ title });\n- return false;\n }\n```\n\nThis example assumes the Backbone provider above and a single named input. Add\n`event.stopPropagation()` when stopping propagation was part of the intended v4\nbehavior; cancelling a form submission alone does not require it.\n\n## 2. Update Views and composition\n\nThe root remains fixed for each View's lifetime. Resolve selector strings to actual elements before supplying `el`; unwrap an existing jQuery element with `[0]`. To use a different root, destroy the old View and construct a new one. Regions still accept selector strings as mount points.\n\n| Existing code or assumption | v5 change |\n| --- | --- |\n| `setElement(...)`, inherited `remove()` | Construct with the intended `el`; use `destroy()` for complete teardown. |\n| `$el`, jQuery methods on `ui.name`, `getUI(...)`, or `this.$(selector)` | Native UI queries return array-like collections. Use `this.getUI('name')[0]` for one element. With the jQuery DOM adapter, UI queries return jQuery collections; create `$(this.el)` explicitly if the application needs a root wrapper. |\n| jQuery delegated events, `return false`, event namespaces | Native handlers receive a DOM event. Use `event.delegateTarget` for a selector match and explicit `preventDefault()` / `stopPropagation()` when needed. Core does not inherit singular `delegate` / `undelegate` helpers. |\n| `children.findByModelCid(model.cid)` | Use `children.findByModel(model)`. For an explicit provider key, use `findByKey(key)`; keys come from the configured DataApi, not necessarily a Backbone `cid`. |\n| `viewComparator: false` to ignore collection reordering ([v4.1.3 example](https://github.com/marionettejs/backbone.marionette/blob/v4.1.3/docs/marionette.collectionview.md#defining-the-viewcomparator)) | Also set `sortWithCollection: false`; disabling the comparator alone does not disable v5 source reorder notifications. |\n| Collection-only templates reading `items` | Read `models`, the array of serialized model values. This change applies to a View's collection template data. |\n| `region.show(stringOrOptions)` or `showChildView(name, template)` | Construct the intended View explicitly and pass its instance. |\n| `getRegion`, `getRegions`, or `hasRegion` implicitly rendering a layout | These are inspection methods. Use `showChildView` for composition, or explicitly render before showing directly through a selector Region. |\n| View Region registration/removal events | Put setup alongside registration and observe the Region's own destruction when needed. The View's `add:region` / `remove:region` notifications are removed. |\n| Global `setEnabled` / `isEnabled` calls | Remove the registry. Configure `childViewEventPrefix` on the View and `preventDefault` / `stopPropagation` on individual trigger definitions. Move application settings to explicit configuration or state. |\n| Lifecycle hooks supplied as constructor options | Define hooks on the class or instance. `triggerMethod` resolves instance/prototype methods. |\n| `bind` / `unbind`, or space-separated framework event names | Use `on` / `off`. Each event or request name is literal; use maps or separate calls for multiple names. Backbone sources retain their own native event semantics. |\n| Root imports of target-first utility wrappers | Prefer the object's method, or use the receiver-based functions from [@mnjs/utils](/docs/packages/utils.md). |\n\nThe UI query and native DOM handler changes also apply to Behaviors; their element and delegated interactions belong to the host View. See [Behavior](/docs/api/behavior.md) for that contract.\n\nKeep root attributes distinct from template contents. `renderAttributes()` refreshes declared root attributes; `render()` refreshes contents. Native attribute removal requires `null`, and boolean HTML attributes should be present or absent rather than assigned `false`. Set live input values through DOM properties. See [View bindings](/docs/api/shared/view-bindings.md) for templates, attributes, UI, and events.\n\nFor CollectionView customizations, `attachHtml(els, container)` receives a native container. The child container supports iteration and its documented helpers; replace removed Underscore aliases or iteratee shorthand with explicit callbacks/native array operations. Sorting and filtering retain their public methods and callback forms; verify the [CollectionView reference](/docs/api/collection-view.md) when overriding them. After changing a Model attribute used by a comparator or filter, call `list.sort()` or `list.filter()` explicitly. This applies to both `@mnjs/data` and Backbone Models. Filtering still detaches rows without destroying them, and `children` still describes the presented set. These are presentation operations, not collection membership changes.\n\n## 3. Make feature readiness and ownership explicit\n\nIn v4, `Application.start()` fired notifications synchronously on every call and returned the Application. v5 adds `stop()`, `restart()`, and `isRunning()`. Await `start()` and `restart()`: they return `Promise${title}
\n `,\n ui: { title: '.title' },\n events: { 'input @ui.title': 'editTitle' },\n modelEvents: { 'change:title': 'render' },\n editTitle() {\n this.model.set('title', this.getUI('title')[0].value);\n },\n}).setDataApi(DataApi).setDomApi(LitDomApi);\n```\n\n## `test/summary-application.mjs`\n\nReadiness stays with the Application. The feature requests `/summary.json`, which returns an object with a string `title`. Tests replace `fetch` to hold, resolve, or reject this boundary without a network or arbitrary delay.\n\n```js\nimport { Application, View } from 'marionette';\nimport LitDomApi from '@mnjs/adapters/dom/lit-html';\nimport { html } from 'lit-html';\n\nconst SummaryView = View.extend({\n template: ({ title }) => html`Replacement
' });\n region.show(replacement);\n\n assert.equal(editor.isDestroyed(), true);\n assert.equal(oldRoot.isConnected, false);\n assert.equal(region.currentView, replacement);\n assert.equal(model.isDestroyed(), false);\n const renderCount = renders.mock.callCount();\n model.set('title', 'Still borrowed');\n assert.equal(renders.mock.callCount(), renderCount);\n assert.equal(oldRoot.querySelector('.preview').textContent, 'Original');\n input.value = 'Removed control';\n input.dispatchEvent(new window.Event('input', { bubbles: true }));\n assert.equal(model.get('title'), 'Still borrowed');\n assert.equal(mount.textContent, 'Replacement');\n});\n\ntest('readiness precedes activation and stop destroys the screen', async t => {\n const mount = document.body.appendChild(document.createElement('section'));\n const request = Promise.withResolvers();\n t.mock.method(globalThis, 'fetch', () => request.promise);\n const app = new SummaryApplication({ region: { el: mount } });\n t.after(() => { app.destroy(); mount.remove(); });\n const starting = app.start();\n assert.equal(app.isRunning(), false);\n assert.equal(mount.childElementCount, 0);\n request.resolve(new Response(JSON.stringify({ title: 'Ready summary' })));\n assert.equal(await starting, true);\n assert.equal(app.isRunning(), true);\n assert.equal(mount.querySelector('h1').textContent, 'Ready summary');\n const screen = app.getView();\n\n assert.equal(app.stop(), true);\n assert.equal(app.isRunning(), false);\n assert.equal(screen.isDestroyed(), true);\n assert.equal(mount.childElementCount, 0);\n const region = app.getRegion();\n assert.equal(app.destroy(), true);\n assert.equal(app.isDestroyed(), true);\n assert.equal(region.isDestroyed(), true);\n});\n\ntest('failed readiness leaves an initially stopped feature without a screen', async t => {\n const mount = document.body.appendChild(document.createElement('section'));\n const failure = new Error('Unavailable');\n t.mock.method(globalThis, 'fetch', async () => { throw failure; });\n const app = new SummaryApplication({ region: { el: mount } });\n t.after(() => { app.destroy(); mount.remove(); });\n await assert.rejects(app.start(), error => error === failure);\n assert.equal(app.isRunning(), false);\n assert.equal(app.getView(), undefined);\n assert.equal(mount.childElementCount, 0);\n});\n\ntest('stop cancels pending readiness and an obsolete result cannot show UI', async t => {\n const mount = document.body.appendChild(document.createElement('section'));\n const request = Promise.withResolvers();\n let preparationSignal;\n t.mock.method(globalThis, 'fetch', (_url, { signal }) => {\n preparationSignal = signal;\n return request.promise;\n });\n const app = new SummaryApplication({ region: { el: mount } });\n t.after(() => { app.destroy(); mount.remove(); });\n const starting = app.start();\n app.stop();\n assert.equal(preparationSignal.aborted, true);\n request.resolve(new Response(JSON.stringify({ title: 'Obsolete summary' })));\n assert.equal(await starting, false);\n assert.equal(app.isRunning(), false);\n assert.equal(mount.childElementCount, 0);\n});\n```\n\nThe render spy checks that a disposed editor no longer reacts to its borrowed Model. Unchanged DOM alone could miss a leaked callback because a destroyed View ignores rendering. For a View that updates through another public handler, observe that handler or its external effect instead.\n\nRun from the application root with the DOM preload:\n\n```sh\nnode --import ./test/dom.mjs --test --test-reporter=tap ./test/app.test.mjs\n```\n\nThese tests do not need an HTTP server, timers, or a complete application. The pending fetch mock deliberately ignores cancellation so the final test verifies that a superseded startup cannot activate the feature. Failed preparation is handled by the caller through the rejected `start()` Promise. Tests for an application's chosen error presentation belong alongside that application's UI.\n\n## Add browser checks where they matter\n\nJSDOM verifies DOM changes, delegated events, public lifecycle outcomes, and cleanup. It cannot establish real layout, focus and caret behavior while typing, browser navigation, or accessibility quality. Add browser tests for those user interactions and run them against your built consumer bundle. Test the behavior your application promises, including the chosen renderer and data provider.\n\nIn your application, import your application setup first, then the real View and Application modules and test their promised public behavior with these patterns. See [local editing](/docs/guides/local-editing.md), [retained restart](/docs/guides/retained-restart.md), and [tooling](/docs/tooling.md) for related contracts and checks.\n\n\n[Canonical source](/docs/markdown/docs/guides/testing.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/typescript.md", "title": "Use TypeScript in an application", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/typescript/", "markdownUrl": "https://marionettejs.com/docs/guides/typescript.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/typescript.md", "sourceSha256": "baba4c8483115fd7a6bb16089f38e5666f9c0f632079b531a107ee48b1ed6285", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "78766b415b2b0bc2da727ca75f0a3659d5fecef6ed6b25e55f398525cd0ac359", "markdown": "\n\n# Practical TypeScript\n\nMarionette and the companion packages ship declarations with their public entrypoints. Use strict TypeScript checking and the DOM library for browser code. Your bundler's module-resolution settings still apply; see [consumer tooling](/docs/tooling.md) for a checked project setup.\n\n## Constructors, instances, options, and state\n\n`View` is a constructor value. A constructor created with `View.extend` keeps the options declared by its `initialize` method, custom methods, and the state returned by `createState`. Use `typeof` for the constructor and `InstanceType` for its instance. Broader public types such as `ViewInstance` are useful at boundaries that only need core methods; they do not describe your custom methods.\n\n```ts\nimport { View } from 'marionette';\n\ntype CounterOptions = { label: string };\nconst CounterView = View.extend({\n tagName: 'button',\n template: false,\n initialize(options: CounterOptions) {\n this.el.textContent = options.label;\n },\n createState() { return { count: 0 }; },\n events: { click: 'increment' },\n increment() { this.getState().count++; },\n label() { return this.options.label; }\n});\n\ntype CounterConstructor = typeof CounterView;\ntype Counter = InstanceType${title}
\n `,\n templateContext() { return this.getState(); },\n ui: { title: '.title' },\n createState() { return { title: 'Untitled' }; },\n events: { 'input @ui.title': 'editTitle' },\n editTitle(event: DelegatedEvent) {\n const input = event.delegateTarget;\n if (!(input instanceof HTMLInputElement)) { return; }\n this.getState().title = input.value;\n this.render();\n },\n focusTitle() {\n const input = this.getUI('title')?.[0];\n if (input instanceof HTMLInputElement) { input.focus(); }\n }\n});\nEditorView.setDomApi(LitDomApi);\nconst editor = new EditorView().render();\ndocument.body.append(editor.el);\neditor.focusTitle();\n```\n\nThe element checks establish what the code uses: `value` and `focus`. They also handle missing UI bindings. These types do not guarantee the selector exists in every template. Event maps use string names; TypeScript does not verify that a method annotation matches every event payload. Interaction tests verify that delivery. No Application is needed for this View's local interaction. Use [local editing](/docs/guides/local-editing.md) when a borrowed Model supplies the data.\n\n## Readiness results and lifecycle completion\n\nAn Application's `prepareStart` returns data required before activation. `onStart` receives that resolved result as its third argument. The public `start` and `restart` operations return `Promise${title}
\n `,\n ui: { title: '.title', preview: '.preview' },\n events: { 'input @ui.title': 'editTitle' },\n modelEvents: { 'change:title': 'render' },\n editTitle() {\n this.model.set('title', this.getUI('title')[0].value);\n }\n});\n\nconst model = new Model({ title: 'Untitled' });\nconst region = new Region({ el: '#editor' });\nconst editor = new TitleEditor({ model });\nregion.show(editor);\n```\n\nThe input event changes the Model, whose observable change renders the View with Lit. Lit updates the existing nodes. Its `live` binding compares against the input's current DOM value, so typing keeps focus and selection while an external Model update changes the same input. Lit owns both the input binding and preview content; do not replace its interpolated content manually.\n\nThis is immediate local editing, with no separate draft or Save operation. If the selected data solution supplies a persistence method, a View can save its own model as part of a local interaction. `@mnjs/data` has no `save()` method; integrate an API layer or choose another data solution for persistence. Coordinate shared decisions, navigation, or readiness in an owner with the corresponding lifetime; see [architecture](/docs/architecture.md).\n\nWhen the panel closes, `region.empty()` destroys the editor and removes its model subscriptions. The supplied Model remains alive: the code that created or shared it decides when it should be destroyed. Destroy the Region when its owner finishes.\n\n## Keep a draft until Save succeeds\n\nFor an explicit Save interaction, keep input in View-owned state and update the supplied Model only after the API accepts it. The draft belongs to this editor's lifetime, so the View can own the request too. This independent example assumes `PATCH /api/titles/:id` accepts JSON `{ title }` and returns JSON `{ title }` containing the accepted value. The API function supplies persistence; optional `@mnjs/data` supplies observable attributes and has no `save()` method.\n\n```js\nimport { Region, View, setDataApi, setDomApi, setStateApi } from 'marionette';\nimport { DataApi, Model, StateApi } from '@mnjs/data';\nimport LitDomApi from '@mnjs/adapters/dom/lit-html';\nimport { html } from 'lit-html';\nimport { live } from 'lit-html/directives/live.js';\n\nsetDataApi(DataApi);\nsetDomApi(LitDomApi);\nsetStateApi(StateApi);\n\nasync function saveTitle(id, title, signal) {\n const response = await fetch(`/api/titles/${encodeURIComponent(id)}`, {\n method: 'PATCH', signal,\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ title })\n });\n if (!response.ok) throw new Error('Save failed');\n return (await response.json()).title;\n}\n\nconst DraftEditor = View.extend({\n createState() {\n return new Model({\n draftTitle: this.model.get('title'), saving: false, status: '', error: ''\n });\n },\n stateEvents: { change: 'render' },\n templateContext() { return this.getState().toObject(); },\n template: ({ draftTitle, saving, status, error }) => html`\n \n `,\n ui: { title: '.title' },\n events: { 'input @ui.title': 'editDraft', 'submit form': 'save' },\n editDraft() {\n const state = this.getState();\n if (state.get('saving')) return;\n state.set({ draftTitle: this.getUI('title')[0].value, status: '' });\n },\n async save(event) {\n event?.preventDefault();\n const state = this.getState();\n if (this.isDestroyed() || state.get('saving')) return false;\n const request = new AbortController();\n this.saveRequest = request;\n state.set({ saving: true, status: 'Saving…', error: '' });\n let title;\n try {\n title = await saveTitle(this.model.get('id'), state.get('draftTitle'), request.signal);\n } catch {\n if (this.saveRequest !== request || this.isDestroyed()) return false;\n this.saveRequest = undefined;\n state.set({ saving: false, status: '', error: 'Could not save. Your draft is still here; try again.' });\n return false;\n }\n if (this.saveRequest !== request || this.isDestroyed()) return false;\n this.saveRequest = undefined;\n this.model.set('title', title);\n state.set({ draftTitle: title, saving: false, status: 'Saved.' });\n return true;\n },\n onBeforeDestroy() {\n const request = this.saveRequest;\n this.saveRequest = undefined;\n request?.abort();\n }\n});\n\nconst mount = document.createElement('section');\ndocument.body.append(mount);\nconst savedTitle = new Model({ id: 1, title: 'Original' });\nconst draftRegion = new Region({ el: mount });\nconst draftEditor = new DraftEditor({ model: savedTitle });\ndraftRegion.show(draftEditor);\n```\n\nTyping changes only the draft. During Save the input is read-only, and repeated submissions are ignored. The button stays focusable, with `aria-disabled` announcing its pending state. Failure preserves the draft, input nodes, and supplied Model so the user can retry. Success commits the API's accepted title and displays it in the input. External Model changes do not overwrite an open draft; this example starts a new draft when a new editor is created.\n\n`draftRegion.empty()` destroys the editor and its owned state while leaving `savedTitle` alive. Every asynchronous completion checks that it still belongs to the live editor, including transports that ignore abort. Cancellation prevents a late result from changing local state; it does not guarantee that the server undoes a save. Destroy the Region and remove the mount when their owner finishes.\n\n## Check the behavior\n\nType into the input and verify the preview updates without losing focus. Update the Model externally and verify both elements change. Empty the Region, change the Model again, and verify the removed editor no longer reacts. See [tooling](/docs/tooling.md) for package checks and debugging.\n\nFor the draft example, type and verify `savedTitle` stays unchanged until Save succeeds. Fail a request, then retry the same draft. Close the editor during Save and verify a late response cannot update the supplied Model or detached input.\n\n\n[Canonical source](/docs/markdown/docs/guides/local-editing.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/retained-restart.md", "title": "Restart readiness while retaining UI", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/retained-restart/", "markdownUrl": "https://marionettejs.com/docs/guides/retained-restart.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/retained-restart.md", "sourceSha256": "c331277f256ab66f281c55a80a20c4829f815f26845d1efafac3818557f18190", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "550cac341f34c8275d9c9692c12391b6e83386e6d2efc8556259be8eac3bfca1", "markdown": "\n\n# Restart readiness while retaining UI\n\nUse `Application.restart()` to load readiness again while keeping the feature active. Pending preparation retains the root, child Applications, subscriptions, and state event delivery. Successful `onStart` code decides what changes on screen.\n\nThis dashboard reloads a summary while preserving its page and unfinished notes. `GET /summary.json` returns `{ \"openTasks\": number }`. API transport is separate from the optional `@mnjs/data` observable state. Install the packages in [setup](/docs/integrations/setup.md).\n\n## Construct the shell once\n\n```js\nimport { Application, View, setDataApi, setDomApi } from 'marionette';\nimport { Model, DataApi, StateApi } from '@mnjs/data';\nimport LitDomApi from '@mnjs/adapters/dom/lit-html';\nimport { html } from 'lit-html';\n\nsetDataApi(DataApi);\nsetDomApi(LitDomApi);\n\nasync function loadSummary(signal) {\n const response = await fetch('/summary.json', { signal });\n if (!response.ok) throw new Error('Could not load the summary.');\n return response.json();\n}\n\nconst PageView = View.extend({\n template: () => html`\n \n `,\n regions: { summary: '.summary', notes: '.notes' },\n triggers: { 'click .reload': 'reload' },\n});\nconst SummaryView = View.extend({\n template: ({ openTasks, loading, error }) => html`\nOpen tasks: ${openTasks}
\n${loading ? 'Loading…' : error}
`,\n modelEvents: { change: 'render' },\n});\nconst NotesView = View.extend({\n template: () => html``,\n});\n\nconst DashboardApplication = Application.extend({\n createState() { return new Model({ openTasks: 0, loading: false, error: '' }); },\n viewEvents: { reload: 'reloadSummary' },\n onBeforeStart() { this.getState().set({ loading: true, error: '' }); },\n prepareStart(_options, { signal }) { return loadSummary(signal); },\n onStart(_app, _options, summary) {\n const state = this.getState();\n state.set({ openTasks: summary.openTasks, loading: false, error: '' });\n if (this.getView()) return;\n const page = this.setView(new PageView());\n page.showChildView('summary', new SummaryView({ model: state }));\n page.showChildView('notes', new NotesView());\n this.showView();\n },\n reloadSummary() {\n return this.restart().catch(error => {\n this.getState().set({ loading: false, error: error.message });\n });\n },\n}).setStateApi(StateApi);\n\nconst mount = document.createElement('main');\ndocument.body.append(mount);\nconst app = new DashboardApplication({ region: { el: mount } });\nawait app.start();\n```\n\nApplication owns the Model created by `createState`; SummaryView borrows it. Each successful result updates that Model. Only SummaryView renders again. PageView, NotesView, and the textarea retain their identity and unfinished input. `viewEvents` connects the page's intent once; restart does not install another listener.\n\n`reloadSummary` is the button's error boundary around `restart()`. It adds no request controller or concurrency layer. Initial `start()` failure rejects to its caller before the page exists. A failed reload leaves the running page and previous summary available and shows the error in its status area.\n\n## Let preparation discard obsolete results\n\nEach restart supersedes pending preparation, aborts its signal, and resolves the previous call `false`. Only the current successful result reaches `onStart`, even when a transport ignores abort. Applying data there prevents obsolete requests from changing the summary. The current failure rejects; the button's handler reports it. A cancelled call never reaches that catch handler.\n\nPass the preparation signal to the transport. After preparation completes, that signal is no longer a lifetime signal. Independent operations such as saving a draft need their own cancellation policy; they do not belong in readiness merely to acquire one.\n\n## End the run deliberately\n\n`stop()` synchronously cancels preparation and destroys the page and its child Views. A later `start()` loads again and builds a new page. `destroy()` also disposes registered children and owned state. An [external host](/docs/guides/existing-ui.md) must stop or destroy its feature when removing its mount; removing DOM alone does not end Application authority.\n\nRestart itself does not render or replace Views. Calling `setView(new PageView())` unconditionally in `onStart`, or rendering the existing PageView again, would replace its child UI and lose the notes. Preserve the shell and update the source or Region that changed. Use `app.stop(); await app.start(options)` when full reconstruction or a new host is intended.\n\nThe notes here are local input. If they must survive stopping or leaving the page, give the draft a longer-lived owner.\n\n[Application lifecycle](/docs/api/application.md) · [State ownership](/docs/api/shared/state.md) · [View rendering](/docs/api/view.md#rendering-and-status)\n\n\n[Canonical source](/docs/markdown/docs/guides/retained-restart.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/existing-html.md", "title": "Add behavior to existing HTML", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/existing-html/", "markdownUrl": "https://marionettejs.com/docs/guides/existing-html.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/existing-html.md", "sourceSha256": "024ec76fab9e8a7d64153f35453aa4ae436d03d718a9669bb8ca9e518b1371e7", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "51e7d0d723d3c2478ddad5ea7fbbcbbac9ffe98a712ee8351305186b4bb71a60", "markdown": "\n\n# Add behavior to existing HTML\n\nA View can adopt server-rendered or static markup. Set `el` to the existing root and `template: false` to retain its contents. No renderer or data package is needed for this example.\n\nStart with this HTML:\n\n```html\nWelcome.
`,\n}).setDomApi(LitDomApi);\nconst AboutView = View.extend({\n template: () => html`About this application.
`,\n}).setDomApi(LitDomApi);\nconst NotFoundView = View.extend({\n template: () => html`${body}
`,\n}).setDomApi(LitDomApi);\nconst ContentView = View.extend({\n template: ({ title, body }) => html`${body}
`,\n}).setDomApi(LitDomApi);\nconst ErrorView = View.extend({\n template: ({ message }) => html`\n${message}
\n `,\n triggers: { 'click .retry': 'retry' },\n}).setDomApi(LitDomApi);\n\nconst PageApplication = Application.extend({\n async prepareStart({ route }, { signal }) {\n const response = await fetch(`/pages/${route.slice(1)}.json`, { signal });\n if (!response.ok) throw new Error('The page request failed.');\n return response.json();\n },\n onStart(_app, _options, page) {\n this.showView(new ContentView({ model: page }));\n document.title = page.title;\n },\n});\n\nconst NavigationApplication = Application.extend({\n childApps: { page: PageApplication },\n onStart() {\n if (this.getView()) return;\n this.showView(new ShellView());\n this.onHashChange = () => {\n this.navigationTask = this.showRoute();\n this.navigationTask.catch(error => console.error(error));\n };\n window.addEventListener('hashchange', this.onHashChange);\n this.onHashChange();\n },\n async showRoute() {\n if (!this.isRunning()) return false;\n const route = window.location.hash || '#home';\n if (route === this.currentRoute) return false;\n this.currentRoute = route;\n const child = this.getChildApp('page');\n child.stop();\n const region = this.getView().getRegion('content');\n if (route !== '#home' && route !== '#about') {\n document.title = 'Page not found';\n region.show(new MessageView({ model: {\n title: 'Page not found', body: 'Choose Home or About.',\n } }));\n return true;\n }\n document.title = 'Loading page…';\n region.show(new MessageView({ model: {\n title: 'Loading page…', body: 'Please wait.',\n } }));\n try {\n return await child.start({ region, route });\n } catch (error) {\n child.stop();\n this.currentRoute = undefined;\n document.title = 'Could not load page';\n const errorView = new ErrorView({ model: { message: error.message } });\n this.listenTo(errorView, { retry: this.onHashChange });\n region.show(errorView);\n return false;\n }\n },\n onBeforeStop() {\n this.currentRoute = undefined;\n window.removeEventListener('hashchange', this.onHashChange);\n },\n});\n\nconst mount = document.createElement('div');\ndocument.body.append(mount);\nconst app = new NavigationApplication({ region: { el: mount } });\nawait app.start();\n```\n\nThe URL selects the destination as soon as it changes. A failed request keeps that URL and shows an error View; Retry dispatches the current URL again. An unknown fragment shows a not-found View. Repeating a route that is loading or ready leaves it alone.\n\nThe owner stops the outgoing child before starting the next destination. Stopping the child cancels its pending start, which resolves `false`; obsolete failures do not reject that cancelled call. The next destination starts a new preparation. Stopping the outgoing child aborts its preparation signal; an obsolete result cannot activate even if the transport ignores abort. A rejected start is stopped before error presentation replaces its UI.\n\n`await app.start()` activates the shell; `navigationTask` tracks the separately started page transition. The child loads readiness data in `prepareStart` and renders it in `onStart`.\n\nStop is unconditional here: `onBeforeStop` removes the Window subscription before child teardown. Stop destroys the shell; a later start creates a new one and reads the current URL. Restart retains the shell, the Window listener, and the current child run. Destroy also disposes the registered child. See [Application composition](/docs/api/application.md#child-applications) and [consumer testing](/docs/guides/testing.md).\n\n## Check navigation\n\nTest direct links, link clicks, Back/Forward, unknown routes, and repeat selection. Verify shell identity survives page changes, outgoing pages are destroyed, and stop/start removes and reinstalls one URL subscription; restart retains that single subscription. Use a real browser for history and focus behavior.\n\n\n[Canonical source](/docs/markdown/docs/guides/routing.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/lists.md", "title": "Show, sort, and filter a list", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/lists/", "markdownUrl": "https://marionettejs.com/docs/guides/lists.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/lists.md", "sourceSha256": "0733bd54d05d8c7979c720684aa8506b8737b19dbbb5100f0d2797ab0af39ae7", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "148524293e75ad81f3b12a2669df16cd0c970741ffee72f21d06ce5db360dfd8", "markdown": "\n\n# Show, sort, and filter a list\n\nUse CollectionView for repeated children that share one placement rule. A surrounding View can own the list's local controls and Region. Add an Application when the feature needs API readiness or broader coordination; sorting a displayed list does not require one.\n\nThis catalog uses the optional `@mnjs/data` Collection for observable membership. Fetching and persistence need an API layer or another data provider. Install the rendering and data packages from [setup](/docs/integrations/setup.md).\n\n## Own the controls and repeated rows\n\n```js\nimport { CollectionView, Region, View } from 'marionette';\nimport { Collection, DataApi } from '@mnjs/data';\nimport LitDomApi from '@mnjs/adapters/dom/lit-html';\nimport { html } from 'lit-html';\n\nconst ItemView = View.extend({\n tagName: 'li',\n template: ({ label }) => html`\n ${label}\n `,\n modelEvents: { change: 'render' },\n}).setDataApi(DataApi).setDomApi(LitDomApi);\nconst EmptyView = View.extend({\n tagName: 'li',\n template: () => html`No matching items.`,\n}).setDomApi(LitDomApi);\nconst ItemList = CollectionView.extend({\n tagName: 'ul',\n childView: ItemView,\n emptyView: EmptyView,\n viewComparator: 'label',\n}).setDataApi(DataApi);\nconst CatalogView = View.extend({\n template: () => html`\n \n \n `,\n regions: { items: '.items' },\n ui: { available: '.available' },\n events: { 'change @ui.available': 'filterItems', 'click .reverse': 'reverseItems' },\n onRender() {\n this.descending = false;\n this.getUI('available')[0].checked = false;\n this.list = new ItemList({ collection: this.options.items });\n this.showChildView('items', this.list);\n },\n filterItems() {\n this.list.setFilter(this.getUI('available')[0].checked ? { available: true } : null);\n },\n reverseItems() {\n this.descending = !this.descending;\n this.list.setComparator(this.descending ?\n (left, right) => right.model.get('label').localeCompare(left.model.get('label')) : 'label');\n },\n}).setDomApi(LitDomApi);\n\nconst items = new Collection([\n { id: 'a', label: 'Apricot', available: true },\n { id: 'b', label: 'Blueberry', available: false },\n]);\nconst catalog = new CatalogView({ items });\nconst mount = document.createElement('section');\ndocument.body.append(mount);\nconst region = new Region({ el: mount });\nregion.show(catalog);\n```\n\nThe outer Region owns CatalogView; its named Region owns ItemList; the list owns rows and its empty View. The collection is borrowed. Destroy the outer Region when this feature ends, then dispose data according to the lifetime of the code that created it.\n\nThe notes fields are temporary DOM input. Sorting moves the existing rows; filtering detaches excluded rows and retains their Views and input values. Returning a row preserves its nodes, but leaving the document can lose focus. When a filter hides the focused row, choose a focus destination such as the filter control. See [accessibility and rendering](/docs/guides/accessibility-rendering.md).\n\n## Update without rebuilding everything\n\n| Change | Operation | Effect |\n| --- | --- | --- |\n| Add or remove a member | `items.add(...)` / `items.remove(...)` | Creates/destroys affected rows and retains surviving rows. Removing membership does not destroy the Model. |\n| Change a displayed attribute | `model.set(...)` | This example's `modelEvents` renders that row. |\n| Change an attribute used by sorting/filtering | Then call `catalog.list.sort()` / `filter()` | Recomputes presentation; an `@mnjs/data` Model change does not automatically rerun the parent criteria. |\n| Show all rows | `catalog.list.removeFilter()` | Restores retained hidden rows. |\n| Replace the membership snapshot | `items.reset(...)` | Destroys and rebuilds rows, including rows for retained Models. |\n\nFor a group of additions or removals, use `items.add([...])` or `items.remove([...])` rather than calling the method in a loop. When membership changes, the `@mnjs/data` Collection emits one aggregate update per call, so CollectionView reconciles once per call instead of once per item while retaining surviving rows. Use `reset` for a whole replacement snapshot; its row destruction makes it unsuitable for preserving input or focus.\n\nAvoid full `list.render()` to apply a filter or sort: it rebuilds managed rows. Rendering CatalogView again also destroys its Region children; this example deliberately resets its local controls when rebuilding the list. If notes must survive those operations or navigation, put the draft in an appropriately owned data source.\n\nAn empty presentation can mean all rows are filtered out even when the collection has members. `emptyView` describes that presentation, rather than storing an empty record in the collection. Give it a root valid for the container, such as `li` inside `ul`.\n\n## Identity and scale\n\nThe configured DataApi determines keys and collection observation. With `@mnjs/data`, the key is Model `cid`; reusing a server `id` in a new Model does not reuse the old row. Other providers must supply stable unique keys, but a replacement model object still replaces its View.\n\n`list.children` describes the currently presented rows, excluding hidden rows and the empty View. Save a row reference before hiding it when checking identity. CollectionView is not a virtualized viewport: hidden rows remain alive. For large datasets, choose paging or a measured windowing solution based on the application's needs.\n\n## Check the behavior\n\nEnter notes, sort, hide and restore that row, and check the same input and value return. Add/remove members and verify surviving row identity and outgoing destruction. With Available only selected, call `items.at(0).set('available', false)` and `catalog.list.filter()` to filter every row out; verify empty presentation without changing collection length. Finish by destroying the Region and checking that no borrowed data was destroyed or continues rendering the old list. [CollectionView reference](/docs/api/collection-view.md) defines the full contract; [consumer testing](/docs/guides/testing.md) gives a test setup.\n\n\n[Canonical source](/docs/markdown/docs/guides/lists.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/widgets.md", "title": "Integrate an imperative control", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/widgets/", "markdownUrl": "https://marionettejs.com/docs/guides/widgets.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/widgets.md", "sourceSha256": "cf8cc28d52bcac0c849d4a1e9e771beb987b5c834ed7cd94f44a77c0aedaa009", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "8ad9d2fb584e8174de7ca8b9a23ab27adc12c8d8a94c685cef90e95ff8edbc6f", "markdown": "\n\n# Integrate an imperative control\n\nKeep a control's DOM and cleanup with the View that owns its element. A one-off control can stay in that View. Use a [Behavior](/docs/api/behavior.md) when multiple Views genuinely share the same integration.\n\nThis example uses the browser's native dialog API. It needs no renderer, data package, Application, or widget wrapper. Show the View through a Region before opening the dialog: [`showModal()` requires a connected element](https://html.spec.whatwg.org/multipage/interactive-elements.html#dom-dialog-showmodal).\n\n```js\nimport { Region, View } from 'marionette';\n\nconst HelpView = View.extend({\n template: () => `\n \n \n `,\n ui: { open: '.open-help', dialog: 'dialog' },\n events: { 'click @ui.open': 'openDialog' },\n openDialog() {\n this.getUI('dialog')[0].showModal();\n },\n closeDialog() {\n const dialog = this.el.querySelector('dialog');\n if (dialog && dialog.open) dialog.close();\n },\n onDomRemove() {\n this.closeDialog();\n },\n onBeforeDestroy() {\n this.closeDialog();\n },\n});\n\nconst mount = document.body.appendChild(document.createElement('section'));\nconst region = new Region({ el: mount });\nconst help = new HelpView();\nregion.show(help);\n```\n\nThe native dialog owns modal display, focus handling, Escape dismissal, and its closing form. The View owns the interaction that opens it and closes it before its markup is removed. This is local presentation; no broader feature lifecycle is needed.\n\n## Match the control to the View lifecycle\n\nWith normal View monitoring, `onDomRemove` runs before an attached View re-renders or detaches. Closing there releases the modal while its element is still connected. `onBeforeDestroy` also covers terminal disposal, including a View already detached. Cleanup can run more than once; closing an already closed dialog does nothing.\n\nFor an external editor, chart, or other package, follow that package's actual API instead of treating the dialog as its adapter:\n\n- Create DOM-independent resources in `initialize`. Bind to freshly rendered elements in `onRender`.\n- Create or measure controls that require a connected element in `onAttach`, or `onDomRefresh` if they also need updating after an attached render. An adopted, already attached element gets no construction-time attach event; initialize that case explicitly.\n- Dispose or release bindings before the renderer replaces their elements. Suspend work on detachment if the View can return; re-establish it when attached again.\n- Release terminal resources in `onBeforeDestroy`, even when the View was never attached. Let the package's ownership rules determine whether disposal may be repeated.\n\nKeep the renderer and external control from both updating the same subtree. Use the package's documented change events to update local data or emit user intent, and release its subscriptions or global handlers when its owner ends. See the [View lifecycle reference](/docs/api/view.md#lifecycle-hooks-and-events) for hook arguments and ordering.\n\n## Reuse through a Behavior\n\nA Behavior receives its host's render, attach, detach, and destroy notifications, so the same integration hooks can be reused when their assumptions match each host. The host still owns its DOM.\n\nDirect `behavior.destroy()` emits no independent destroy notification. If an integration can be removed separately from its host, release its external resources in an override of `destroy` and delegate to `Behavior.prototype.destroy.call(this)`. Make that cleanup repeat-safe; relying only on forwarded `onBeforeDestroy` leaves direct removal uncovered. See [Behavior disposal](/docs/api/behavior.md#destruction-and-nested-behaviors) for the full contract.\n\n## Check the actual browser behavior\n\nOpen Help and verify focus enters the dialog. Close it with the form button and with Escape. Open it again before rendering, detaching, or destroying the View and verify it closes before removal. A detached View remains reusable: re-show it through the Region and verify Help opens again. `region.empty()` destroys the View; destroy the Region when its owner finishes.\n\nRun these modal checks in a browser. JSDOM can check the mounted markup and Marionette ownership transitions, but it does not supply the dialog's modal methods here. See [consumer testing](/docs/guides/testing.md) for testing boundaries.\n\n\n[Canonical source](/docs/markdown/docs/guides/widgets.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/accessibility-rendering.md", "title": "Accessibility and rendering", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/accessibility-rendering/", "markdownUrl": "https://marionettejs.com/docs/guides/accessibility-rendering.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/accessibility-rendering.md", "sourceSha256": "e197de86f7c0905901a7bbebb45438f96e67de54929e11277d74fcf5e7f1a3ef", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "176380a4f946ee37ffa9ae4066741b6bdeeba144db083206139c08ce2f42eabd", "markdown": "\n\n# Accessibility and rendering\n\nMarionette manages View lifetimes and placement. Your templates and interaction design determine accessible names, keyboard behavior, and where focus goes when content changes.\n\n## Start with semantic controls\n\nUse a native `button` for an action and a link with `href` for navigation. Label form fields visibly, keep document order meaningful, and preserve a visible focus indicator. A native button supplies keyboard activation, so a delegated `click` handler can serve pointer and keyboard users without duplicating Enter and Space handlers.\n\nFor a toggle button, keep its label stable and update `aria-pressed`. The [WAI button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/) describes keyboard activation and focus behavior.\n\nThis View owns only local display state. Its class-scoped Lit adapter updates the same template's elements when the user toggles the setting.\n\n```js\nimport { Region, View } from 'marionette';\nimport LitDomApi from '@mnjs/adapters/dom/lit-html';\nimport { html } from 'lit-html';\n\nconst NotificationSettings = View.extend({\n tagName: 'section',\n createState() { return { title: 'Notifications', muted: false }; },\n templateContext() { return this.getState(); },\n template: ({ title, muted }) => html`\n${muted ? 'Notifications are muted.' : 'Notifications are enabled.'}
\n `,\n ui: { heading: '.heading', mute: '.mute' },\n events: { 'click @ui.mute': 'toggleMuted' },\n toggleMuted() {\n const state = this.getState();\n state.muted = !state.muted;\n this.render();\n },\n focusHeading() { this.getUI('heading')[0].focus(); }\n});\nNotificationSettings.setDomApi(LitDomApi);\n\nconst mount = document.createElement('main');\ndocument.body.append(mount);\nconst region = new Region({ el: mount });\nconst settings = new NotificationSettings();\nregion.show(settings);\n```\n\nThis is local state, with no persistence claim. When a server-backed setting belongs to a wider feature, give the save and failure workflow to its appropriate owner. The toggle's pressed state conveys the immediate local change; do not add announcements that repeat the control's own feedback without a reason.\n\n## Retain focus during updates; choose it during replacement\n\nThe toggle does not dismiss its context, so focus should remain on the button. Lit can retain the existing nodes when this View renders the same template again. Changing template branches, removing an element, or choosing an insertion provider that replaces descendants can still remove the focused node. Test the actual rendering behavior you use.\n\nShowing a different View in a [Region](/docs/api/region.md#showing-a-view) destroys the current View and removes its content. Marionette does not choose a focus destination. For a user-requested screen transition, show the new View, then focus its heading or an appropriate first control. For example, another `NotificationSettings` instance named `nextSettings` can use `region.show(nextSettings); nextSettings.focusHeading();` after the transition is accepted. The heading's `tabindex=\"-1\"` permits programmatic focus without adding an extra Tab stop.\n\nKeep this focus decision with the owner performing the transition. An unrelated background update should not move focus to a new heading. If a dialog closes, returning to its opener may be the appropriate policy instead. Follow the [WAI guidance on predictable focus](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_discernable_predictable) and test the resulting keyboard sequence.\n\n## Keep text and raw HTML boundaries explicit\n\nMarionette's native DOM provider inserts template strings with `innerHTML`. It treats a string as HTML, so interpolating untrusted text into that string is unsafe. Use `textContent` for direct text updates or a template system that handles text interpolation.\n\nOrdinary string values in Lit child expressions, such as this example's title, become text. See [Lit expressions](https://lit.dev/docs/templates/expressions/#primitive-values). Raw HTML insertion, including Lit's [`unsafeHTML`](https://lit.dev/docs/templates/directives/#unsafehtml), requires trusted or sanitized HTML at the application's boundary. URL attributes also need the application's allowed-URL policy; text interpolation is not a complete security policy.\n\nChoose an integration whose output matches the [renderer and DOM provider](/docs/api/providers/dom.md) contract. Keep renderer-owned nodes under that renderer's control rather than overwriting their contents independently.\n\n## Verify the user-visible behavior\n\nUse browser interaction tests to Tab to the button, activate it with Enter and Space, and check both `aria-pressed` and visible feedback. Confirm the same button remains focused through the local update. Then replace the View through its Region, verify the old View is destroyed, and check that the transition owner moves focus to the intended new destination.\n\nInclude a text value containing HTML-like characters and verify it stays text. Test with keyboard navigation and assistive technology for your complete application; these focused checks do not establish accessibility conformance. See [consumer testing](/docs/guides/testing.md) for test setup and [retained restart](/docs/guides/retained-restart.md) for updates that preserve a larger page.\n\n\n[Canonical source](/docs/markdown/docs/guides/accessibility-rendering.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/guides/production.md", "title": "Build and deploy an application", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/guides/production/", "markdownUrl": "https://marionettejs.com/docs/guides/production.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/guides/production.md", "sourceSha256": "9e6e921f87c3ec2d2aa602911f2d20ac78e43e3c6df4b3c41806131d983ad715", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "c488fe9e57e11cb372f7c6dc92ab7f83c2b6c64d530398b7227433c643ee68fa", "markdown": "\n\n# Build and deploy an application\n\nDeploy the application bundle with its configured providers and verify it through the server that will serve users. Marionette manages UI ownership and lifecycle; your bundler and server provide the build and delivery boundaries.\n\n## Keep installed packages coherent\n\nThese docs target **5.0.0**. Follow the [quick start](/docs/quick-start.md) to install matching package versions; keep the lockfile and use the documentation bundled with that installation. Verify your application against that exact installation before deployment.\n\nUse named ESM imports from `marionette` and the documented adapter subpaths. Build against installed packages rather than repository source aliases. Include the template engine required by the chosen adapter. Choose observable data and API access through [setup](/docs/integrations/setup.md).\n\nConfigure providers before constructing consumers. A shared setup module suits one class family; class setters such as `View.extend(...).setDomApi(LitDomApi)` suit a configured subclass. Configure CollectionView and its child View classes when both consume that adapter. Use an isolated runtime when independently configured features coexist. [Runtime configuration](/docs/api/runtime.md) explains these scopes; changing providers on live instances does not rebuild them.\n\n## Build the browser artifact\n\nIn the quick-start project, run `npm run build` and deploy the resulting `dist` directory. Preview that output locally with `npx vite preview`; Vite's preview server is for local verification. Configure the bundler's public base when serving from a subdirectory, and check the emitted asset URLs at that location. See Vite's [deployment guide](https://vite.dev/guide/static-deploy.html) and [public base configuration](https://vite.dev/guide/build.html#public-base-path).\n\nRun the application's lint and TypeScript checks separately from bundling. The [tooling guide](/docs/tooling.md) supplies installed-package configurations. A successful build does not establish readiness, cleanup, or browser interaction behavior; [consumer tests](/docs/guides/testing.md) exercise those boundaries.\n\n## Handle startup at its owner\n\nPut required asynchronous readiness in Application `prepareStart`, pass its signal to cancellable requests, and connect the ready UI in synchronous `onStart`. The caller of `start()` handles rejection and decides whether to show an error, offer retry, or end the feature. Retain the Application so the owner can call synchronous `stop()` for reuse or `destroy()` when its lifetime ends.\n\nSee the [Application failure contract](/docs/api/application.md#preparation-cancellation-and-failure) for cancellation, partial activation and lifecycle results.\n\nUse [retained restart](/docs/guides/retained-restart.md) to repeat preparation while preserving the active page. Create retained shells once and update only the source or child Region that changed. Embedded features follow the [existing UI ownership boundary](/docs/guides/existing-ui.md); their host must end the feature before removing its mounting content.\n\n## Serve direct links deliberately\n\nServe the application and API over HTTPS in production. Relative fetch URLs use the application's origin.\n\nFor path-based navigation, serve the application entry for recognized document routes, including direct visits and reloads. Keep asset and API handling separate: a missing JavaScript file or API resource must retain its appropriate error response rather than receiving application HTML. Test an unknown document route according to your chosen server/client not-found policy. Fragment routing does not require a separate server path for each fragment. The [navigation guide](/docs/guides/routing.md) covers URL ownership.\n\nPublish an entry document with the assets it references. Choose caching rules that allow clients to obtain a coherent build, and check an upgrade from a previously loaded version as well as a clean visit. Include the deployed base path and API origin in those checks.\n\n## Check the deployed application\n\nVerify a clean load, direct route reload, navigation, missing asset/API responses, failed readiness and retry, and feature removal while preparation is pending. Exercise keyboard interaction and focus in a real browser. Preserve errors with their stack and Marionette diagnostic code so the [installed lookup](/docs/tooling.md#look-up-a-diagnostic) matches the runtime.\n\nThe framework's browser test configuration runs Chromium, Firefox and WebKit through Playwright. Its browser transpilation query is `baseline widely available`. Those choices describe the repository's validation and transpilation profile; they do not establish behavior in every browser/device or supply missing browser APIs. Select and test your application's actual browser targets with its renderer, providers and deployed bundle.\n\n\n[Canonical source](/docs/markdown/docs/guides/production.md) · [Source identity](/docs/manifest.json)\n" }, { "id": "docs/records.md", "title": "Build a records feature", "section": "Guides", "kind": "guide", "url": "https://marionettejs.com/docs/records/", "markdownUrl": "https://marionettejs.com/docs/records.md", "sourceUrl": "https://marionettejs.com/docs/markdown/docs/records.md", "sourceSha256": "d28300ebf2c56c1819e4c890daa07c5e395934fc2f472984cdaf73af74144ffc", "sourceRevision": "0f2284ad4bbfe8c82ce82714471697a68c2acaeb", "sha256": "9fadc8ee813a1247a2691ee87705082f909b31e94eac42de5d88e8b44af3829c", "markdown": "\n\n# Build a records feature\n\nBuild a feature that loads records and shows the selected record beside its list. The [runnable example](/docs/source/examples/records/README.md) also reloads without replacing the layout, retries failures, and closes/reopens the feature. The excerpts below come from that example; follow the source links for the complete modules.\n\n## Run it\n\nThe source is included with these docs; the commands here use the repository checkout. For an application using installed packages, follow the [quick start](/docs/quick-start.md) and [setup reference](/docs/integrations/setup.md).\n\nThis repository example uses the pinned Node 24 contributor toolchain. Packaged applications follow the [consumer Node LTS policy](/docs/quick-start.md). From the framework repository root:\n\n```sh\nnpm ci --ignore-scripts\nnpm --prefix examples/records ci --ignore-scripts\nnpm --prefix examples/records run dev\n```\n\nOpen