diff --git a/.formatter.exs b/.formatter.exs index 47616780b5..9fe16a0d0d 100644 --- a/.formatter.exs +++ b/.formatter.exs @@ -1,4 +1,17 @@ +locals_without_parens = [ + attr: 2, + attr: 3, + embed_templates: 1, + embed_templates: 2, + slot: 1, + slot: 2, + slot: 3 +] + [ import_deps: [:phoenix], - inputs: ["*.{ex,exs}", "{config,lib,test}/**/*.{ex,exs}"] + inputs: ["*.{ex,exs}", "{config,lib,test}/**/*.{ex,exs}"], + # TODO: Remove these on Phoenix v1.7 since Phoenix provides them already + locals_without_parens: locals_without_parens, + export: [locals_without_parens: locals_without_parens] ] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 9b771c287c..8f4faada97 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -19,7 +19,10 @@ assignees: '' ### Actual behavior ### Expected behavior diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 543059ee7e..0186031faf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,36 +13,25 @@ jobs: strategy: matrix: include: - - elixir: 1.7.4 - otp: 21.3.8.16 - - - elixir: 1.8.2 - otp: 21.3.8.16 - - - elixir: 1.9.4 - otp: 21.3.8.16 - - - elixir: 1.10.4 - otp: 21.3.8.16 - - - elixir: 1.11.4 - otp: 21.3.8.16 + - elixir: 1.12.0 + otp: 24.2 - - elixir: 1.11.4 - otp: 23.3 + - elixir: 1.13.2 + otp: 24.2 lint: lint - - elixir: 1.12.0 - otp: 23.3 - runs-on: ubuntu-latest steps: + - name: Install inotify-tools + run: | + sudo apt update + sudo apt install -y inotify-tools - name: Checkout uses: actions/checkout@v2 - name: Set up Elixir - uses: erlef/setup-elixir@v1 + uses: erlef/setup-beam@v1 with: elixir-version: ${{ matrix.elixir }} otp-version: ${{ matrix.otp }} @@ -90,10 +79,10 @@ jobs: uses: actions/checkout@v2 - name: Set up Elixir - uses: erlef/setup-elixir@v1 + uses: erlef/setup-beam@v1 with: - elixir-version: 1.11.4 - otp-version: 23.3.1 + elixir-version: 1.13.2 + otp-version: 24.2 - name: Restore deps and _build cache uses: actions/cache@v2 diff --git a/CHANGELOG.md b/CHANGELOG.md index fc1e7c07a8..bc1ece282a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,304 @@ # Changelog -## 0.17.0 +## 0.18.17 + +### Enhancements + * Support [`submitter`](https://developer.mozilla.org/en-US/docs/Web/API/SubmitEvent/submitter) on form submit events. + +## 0.18.16 (2023-02-23) + +### Enhancements + * Support streams in Live Components + * Optimize plug error translation when a Plug.Exception is raised over connected LiveView + +## Bug Fixes + * Fix formatter issues when there are multiple HTML comments + +## 0.18.15 (2023-02-16) + +### Bug Fixes + * Fix `JS.transition` applying incorrect classes + +### Enhancements + * Reset phx-feedback-for errors on `type="reset"` inputs and buttons + +## 0.18.14 (2023-02-14) + +### Bug Fixes + * Fix LiveViewTest failing to find main live view + +## 0.18.13 (2023-02-10) + +### Enhancements + * Improve error message when failing to use Phoenix.Component + +## 0.18.12 (2023-02-10) + +### Enhancements + * Introduce streams for efficiently handling large collections + * Allow replies from `:handle_event` lifecycle hooks + * Add `<.inputs_for>` component to `Phoenix.Component` + * Support replies on lifecycle `:handle_event` hooks + +### Bug Fixes + * Fix change tracking when re-assigning a defaulted attribute to same default value + * Fix upload drag and drop failing to worka after using file select dialog + * Fix form recovery when form's first input is phx-change + +## 0.18.11 (2023-01-19) + +### Bug Fixes + * Fix socket unloading connection for forms that have defaulted prevented + +## 0.18.10 (2023-01-18) + +### Bug Fixes + * Fix svg tags with href incorrectly unloading socket on click + * Fix form submits with `target="_blank"` incorrectly unloading socket on submit + +## 0.18.9 (2023-01-17) + +### Bug Fixes + * Fix regular form submits failing to be dispatched + +## 0.18.8 (2023-01-16) + +### Enhancements + * Restore scroll position on back when previous navigation was live patch + +### Bug Fixes + * Fix live layout not being applied until connected render + +## 0.18.7 (2023-01-13) + +### Bug Fixes + * Fix live layout not being applied when passed to `:live_session` during disconnect render + * Fix external anchor clicks and links with hashes incorrectly unloading socket + +## 0.18.6 (2023-01-09) + +### Bug Fixes + * Fix external anchor click unloading on external click + +## 0.18.5 (2023-01-09) + +### Bug Fixes + * Fix external anchor click unloading socket + +## 0.18.4 (2023-01-05) + +### Enhancements + * Support string upload name to support dynamically generated `allow_upload`'s + +### Bug Fixes + * Fix nested LiveView race condition on live patch causing nested child to skip updates in some cases + * Fix browser history showing incorrect title when using live navigation with `@page_title` + * Fix undefined _target param when using `JS.push` for form changes + * Fix `phx-no-feedback` missing from inputs added after a form submit + * Fix `phx-disconnected` events firing when navigating away or submitting external forms + +## 0.18.3 (2022-10-26) + +### Enhancements + * Add `embed_templates` to `Phoenix.Component` for embedding template files as function components + * Raise on global slot attributes + +### Bug Fixes + * Fix bug on slots when passing multiple slot entries with mix if/for syntax + +## 0.18.2 (2022-10-04) + +### Bug Fixes + * Fix match error when defining `:values` before `:default` + * Allow tuples in external redirects + * Fix race condition on dispatching click away when enter is pressed + * Fix formatter breaking inline blocks when surrounded by text without whitespace + +### Enhancements + * Add `intersperse` component for rendering a separator between an enumerable + +## 0.18.1 (2022-09-28) + +### Bug Fixes + * Fix phx-loading class being applied to dead views + * Fix `<.live_img_preview />` causing invalid attribute errors on uploads + * Do not fire phx events when element is disabled + +### Enhancements + * Support `:include` option to extend global attributes on a case-by-case basis + * Warn when accessing a variable binding defined outside of `~H` + +## 0.18.0 (2022-09-20) + +LiveView v0.18 includes a major new feature in the form of declarative assigns with new `attr` +and `slot` APIs for specifying which attributes a function component supports, the type, +and default values. Attributes and slots are compile-time verified and emit warnings (requires Elixir v1.14.0+). + +v0.18 includes a number of new function components which replace their EEx expression +counterparts `<%= ... %>`. For example, `live_redirect`, `live_patch`, and Phoenix.HTML's +`link` have been replaced by a unified `Phoenix.Component.link/1` function component: + + <.link href="https://myapp.com">my app + <.link navigate={@path}>remount + <.link patch={@path}>patch + +Those new components live in the `Phoenix.Component` module. `Phoenix.LiveView.Helpers` +itself has been soft deprecated and all relevant functionality has been migrated. +You must `import Phoenix.Component` where you previously imported `Phoenix.LiveView.Helpers` +when upgrading. You may also need to `import Phoenix.Component` where you also imported `Phoenix.LiveView` and some of its functions have been moved to `Phoenix.Component`. + +Additionally, the special `let` attribute on function components have been deprecated by +a `:let` usage. + +### Deprecations + - `live_redirect` - deprecate in favor of new `<.link navigate={..}>` component of `Phoenix.Component` + - `live_patch` - deprecate in favor of new `<.link patch={..}>` component of `Phoenix.Component` + - `push_redirect` - deprecate in favor of new `push_navigate` function on `Phoenix.LiveView` + +### Enhancements + - [Component] Add declarative assigns with compile-time verifications and warnings via `attr`/`slot` + - [Component] Add new attrs `:let` and `:for`, and `:if` with HTML tag, function component, and slot support. We still support `let` but the formatter will convert it to `:let` and soon it will be deprecated. + - [Component] Add `dynamic_tag` function component + - [Component] Add `link` function component + - [Component] Add `focus_wrap` function component to wrap focus around content like modals and dialogs for accessibility + - [Logger] Add new LiveView logger with telemetry instrumentation for lifecycle events + - [JS] Add new JS commands for `focus`, `focus_first`, `push_focus`, and `pop_focus` for accessibility + - [Socket] Support sharing `Phoenix.LiveView.Socket` with regular channels via `use Phoenix.LiveView.Socket` + - Add `_live_referer` connect param for handling `push_navigate` referal URL + - Add new `phx-connected` and `phx-disconnected` bindings for reacting to lifecycle changes + - Add dead view support for JS commands + - Add dead view support for hooks + +### Bug fixes + - Fix external upload issue where listeners are not cleaned up when an external failure happens on the client + - Do not debounce `phx-blur` + +## 0.17.12 (2022-09-20) + +### Enhancements + - Add support for upcoming Phoenix 1.7 flash interface + +## 0.17.11 (2022-07-11) + +### Enhancements + - Add `replaceTransport` to LiveSocket + +### Bug fixes + - Cancel debounced events from firing after a live navigation event + - Fix hash anchor failing to scroll to anchor element on live navigation + - Do not debounce `phx-blur` events + +## 0.17.10 (2022-05-25) + +### Bug fixes + - [Formatter] Preserve single quote delimiter on attrs + - [Formatter] Do not format inline elements surrounded by texts without whitespaces + - [Formatter] Keep text and eex along when there isn't a whitespace + - [Formatter] Fix intentional line breaks after eex expressions + - [Formatter] Handle self close tags as inline + - [Formatter] Do not format inline elements without whitespaces among them + - [Formatter] Do not format when attr contenteditable is present + +### Enhancements + - [Formatter] Introduce special attr phx-no-format to skip formatting + +## 0.17.9 (2022-04-07) + +### Bug fixes + - Fix sticky LiveViews failing to be patched during live navigation + - Do not raise on dynamic `phx-update` value + +## 0.17.8 (2022-04-06) + +### Enhancements + - Add HEEx formatter + - Support `phx-change` on individual inputs + - Dispatch `MouseEvent` on client + - Add `:bubbles` option to `JS.dispatch` to control event bubbling + - Expose underlying `liveSocket` instance on hooks + - Enable client debug by default on localhost + +### Bug fixes + - Fix hook and sticky LiveView issues caused by back-to-back live redirects from mount + - Fix hook destroyed callback failing to be invoked for children of phx-remove in some cases + - Do not failsafe reload the page on push timeout if disconnected + - Do not bubble navigation click events to regular phx-click's + - No longer generate `csrf_token` for forms without action, reducing the payload during phx-change/phx-submit events + +## 0.17.7 (2022-02-07) + +### Enhancements + - Optimize nested for comprehension diffs + +### Bug fixes + - Fix error when `live_redirect` links are clicked when not connected in certain cases + +## 0.17.6 (2022-01-18) + +### Enhancements + - Add `JS.set_attribute` and `JS.remove_attribute` + - Add `sticky: true` option to `live_render` to maintain a nested child on across live redirects + - Dispatch `phx:show-start`, `phx:show-end`, `phx:hide-start` and `phx:hide-end` on `JS.show|hide|toggle` + - Add `get_connect_info/2` that also works on disconnected render + - Add `LiveSocket` constructor options for configuration failsafe behavior via new `maxReloads`, `reloadJitterMin`, `reloadJitterMax`, `failsafeJitter` options + +### Bug fixes + - Show form errors after submit even when no changes occur on server + - Fix `phx-disable-with` failing to disable elements outside of forms + - Fix phx ref tracking leaving elements in awaiting state when targeting an external LiveView + - Fix diff on response failing to await for active transitions in certain cases + - Fix `phx-click-away` not respecting `phx-target` + - Fix "disconnect" broadcast failing to failsafe refresh the page + - Fix `JS.push` with `:target` failing to send to correct component in certain cases + +### Deprecations + - Deprecate `Phoenix.LiveView.get_connect_info/1` in favor of `get_connect_info/2` + - Deprecate `Phoenix.LiveViewTest.put_connect_info/2` in favor of calling the relevant functions in `Plug.Conn` + - Deprecate returning "raw" values from upload callbacks on `Phoenix.LiveView.consume_uploaded_entry/3` and `Phoenix.LiveView.consume_uploaded_entries/3`. The callback must return either `{:ok, value}` or `{:postpone, value}`. Returning any other value will emit a warning. + +## 0.17.5 (2021-11-02) + +### Bug fixes + - Do not trigger `phx-click-away` if element is not visible + - Fix `phx-remove` failing to tear down nested live children + +## 0.17.4 (2021-11-01) + +### Bug fixes + - Fix variable scoping issues causing various content block or duplication rendering bugs + +## 0.17.3 (2021-10-28) + +### Enhancements + - Support 3-tuple for JS class transitions to support staged animations where a transition class is applied with a starting and ending class + - Allow JS commands to be executed on DOM nodes outside of the LiveView container + +### Optimization + - Avoid duplicate statics inside comprehension. In previous versions, comprehensions were able to avoid duplication only in the content of their root. Now we recursively traverse all comprehension nodes and send the static only once for the whole comprehension. This should massively reduce the cost of sending comprehensions over the wire + +### Bug fixes + - Fix HTML engine bug causing expressions to be duplicated or not rendered correctly + - Fix HTML engine bug causing slots to not be re-rendered when they should have + - Fix form recovery being sent to wrong target + +## 0.17.2 (2021-10-22) + +### Bug fixes + - Fix HTML engine bug causing attribute expressions to be incorrectly evaluated in certain cases + - Fix show/hide/toggle custom display not being restored + - Fix default `to` target for `JS.show|hide|dispatch` + - Fix form input targeting + +## 0.17.1 (2021-10-21) + +### Bug fixes + - Fix SVG element support for `phx` binding interactions + +## 0.17.0 (2021-10-21) ### Breaking Changes -#### on_mount changes +#### `on_mount` changes The hook API introduced in LiveView 0.16 has been improved based on feedback. LiveView 0.17 removes the custom module-function callbacks for the @@ -50,10 +344,18 @@ atom `:default`. #### LEEx templates in stateful LiveComponents Stateful LiveComponents (where an `:id` is given) must now return HEEx templates -(`~H` sigil or `.heex` extension). LEEx temlates (`~L` sigil or `.leex` extension) +(`~H` sigil or `.heex` extension). LEEx templates (`~L` sigil or `.leex` extension) are no longer supported. This addresses bugs and allows stateful components to be rendered more efficiently client-side. +#### `phx-disconnected` class has been replaced with `phx-loading` + +Due to a bug in the newly released Safari 15, the previously used `.phx-disconnected` class has been replaced by a new `.phx-loading` class. The reason for the change is `phx.new` included a `.phx-disconnected` rule in the generated `app.css` which triggers the Safari bug. Renaming the class avoids applying the erroneous rule for existing applications. Folks can upgrade by simply renaming their `.phx-disconnected` rules to `.phx-loading`. + +#### `phx-capture-click` has been deprecated in favor of `phx-click-away` + +The new `phx-click-away` binding replaces `phx-capture-click` and is much more versatile because it can detect "click focus" being lost on containers. + #### Removal of previously deprecated functionality Some functionality that was previously deprecated has been removed: @@ -63,15 +365,23 @@ Some functionality that was previously deprecated has been removed: ### Enhancements - Allow slots in function components: they are marked as `<:slot_name>` and can be rendered with `<%= render_slot @slot_name %>` + - Add `JS` command for executing JavaScript utility operations on the client with an extended push API - Optimize string attributes: - If the attribute is a string interpolation, such as `
`, only the interpolation part is marked as dynamic - If the attribute can be empty, such as "class" and "style", keep the attribute name as static - Add a function component for rendering `Phoenix.LiveComponent`. Instead of `<%= live_component FormComponent, id: "form" %>`, you must now do: `<.live_component module={FormComponent} id="form" />` ### Bug fixes - - Add workaround for Safari bug causing img tags with srcset and video with autoplay to fail to render + - Fix LiveViews with form recovery failing to properly mount following a reconnect when preceded by a live redirect + - Fix stale session causing full redirect fallback when issuing a `push_redirect` from mount + - Add workaround for Safari bug causing `` tags with srcset and video with autoplay to fail to render - Support EEx interpolation inside HTML comments in HEEx templates + - Support HTML tags inside script tags (as in regular HTML) + - Raise if using quotes in attribute names + - Include the filename in error messages when it is not possible to parse interpolated attributes - Make sure the test client always sends the full URL on `live_patch`/`live_redirect`. This mirrors the behaviour of the JavaScript client + - Do not reload flash from session on `live_redirect`s + - Fix select drop-down flashes in Chrome when the DOM is patched during focus ### Deprecations - `<%= live_component MyModule, id: @user.id, user: @user %>` is deprecated in favor of `<.live_component module={MyModule} id={@user.id} user={@user} />`. Notice the new API requires using HEEx templates. This change allows us to further improve LiveComponent and bring new features such as slots to them. @@ -83,7 +393,7 @@ Some functionality that was previously deprecated has been removed: - Improve HEEx error messages - Relax HTML tag validation to support mixed case tags - Support self closing HTML tags - - Remove requirement for handle_params to be defined for lifecycle hooks + - Remove requirement for `handle_params` to be defined for lifecycle hooks ### Bug fixes - Fix pushes failing to include channel `join_ref` on messages @@ -97,10 +407,10 @@ Some functionality that was previously deprecated has been removed: ### Enhancements - Improve error messages on tokenization - - Improve error message if inner_block is missing + - Improve error message if `@inner_block` is missing ### Bug fixes - - Fix phx-change form recovery event being sent to wrong component on reconnect when component order changes + - Fix `phx-change` form recovery event being sent to wrong component on reconnect when component order changes ## 0.16.1 (2021-08-26) @@ -111,11 +421,11 @@ Some functionality that was previously deprecated has been removed: ### Bug fixes - Do not generate CSRF tokens for non-POST forms - - Do not add compile-time dependencies on on_mount declarations + - Do not add compile-time dependencies on `on_mount` declarations ## 0.16.0 (2021-08-10) -## # Security Considerations Upgrading from 0.15 +### Security Considerations Upgrading from 0.15 LiveView v0.16 optimizes live redirects by supporting navigation purely over the existing WebSocket connection. This is accomplished by the new @@ -149,7 +459,7 @@ and example usage. ### New HTML Engine -LiveView v0.16 introduces HEEx (HTML+EEx) templates and the concept of function +LiveView v0.16 introduces HEEx (HTML + EEx) templates and the concept of function components via `Phoenix.Component`. The new HEEx templates validate the markup in the template while also providing smarter change tracking as well as syntax conveniences to make it easier to build composable components. @@ -218,7 +528,7 @@ component named `form`: ```elixir ~H""" -<.form let={f} for={@changeset}> +<.form :let={f} for={@changeset}> <%= input f, :foo %> """ @@ -269,6 +579,13 @@ Change it to: import { LiveSocket } from "phoenix_live_view" ``` +Additionally on the client, the root LiveView element no longer exposes the +LiveView module name, therefore the `phx-view` attribute is never set. +Similarly, the `viewName` property of client hooks has been removed. + +Codebases calling a custom function `component/3` should rename it or specify its module to avoid a conflict, +as LiveView introduces a macro with that name and it is special cased by the underlying engine. + ### Enhancements - Introduce HEEx templates - Introduce `Phoenix.Component` @@ -287,12 +604,12 @@ import { LiveSocket } from "phoenix_live_view" ### Bug fixes - Make sure components are loaded on `render_component` to ensure all relevant callbacks are invoked - - Fix `Phoenix.LiveViewTest.page_title` returning nil in some cases + - Fix `Phoenix.LiveViewTest.page_title` returning `nil` in some cases - Fix buttons being re-enabled when explicitly set to disabled on server - Fix live patch failing to update URL when live patch link is patched again via `handle_params` within the same callback lifecycle - Fix `phx-no-feedback` class not applied when page is live-patched - - Fix `DOMException, querySelector, not a valid selector` when performing DOM lookups on non-stanard IDs - - Fix select dropdown flashing close/opened when assigns are updated on Chrome/MacOS + - Fix `DOMException, querySelector, not a valid selector` when performing DOM lookups on non-standard IDs + - Fix select dropdown flashing close/opened when assigns are updated on Chrome/macOS - Fix error with multiple `live_file_input` in one form - Fix race condition in `showError` causing null `querySelector` - Fix statics not resolving correctly across recursive diffs @@ -317,7 +634,7 @@ import { LiveSocket } from "phoenix_live_view" - Fix live patch failing to update URL when live patch link is patched again from `handle_params` - Fix regression in `LiveViewTest.render_upload/3` when using channel uploads and progress callback - Fix component uploads not being cleaned up on remove - - Fix KeyError on LiveView reconnect when an active upload was previously in progress + - Fix `KeyError` on LiveView reconnect when an active upload was previously in progress ### Enhancements - Support function components via `component/3` @@ -343,8 +660,8 @@ import { LiveSocket } from "phoenix_live_view" - Fix nested `live_render`'s causing remound of child LiveView even when ID does not change - Do not attempt push hook events unless connected - Fix preflighted refs causing `auto_upload: true` to fail to submit form - - Replace single upload entry when max_entires is 1 instead of accumulating multiple file selections - - Fix static_path in open_browser failing to load stylesheets + - Replace single upload entry when `max_entries` is 1 instead of accumulating multiple file selections + - Fix `static_path` in `open_browser` failing to load stylesheets ## 0.15.3 (2021-01-02) @@ -354,11 +671,11 @@ import { LiveSocket } from "phoenix_live_view" ## 0.15.2 (2021-01-01) ### Backwards incompatible changes - - Remove `beforeDestroy` from phx-hook callbacks + - Remove `beforeDestroy` from `phx-hook` callbacks ### Bug fixes - Fix form recovery failing to send input on first connection failure - - Fix hooks not getting remounted after liveview reconnect + - Fix hooks not getting remounted after LiveView reconnect - Fix hooks `reconnected` callback being fired with no prior disconnect ## 0.15.1 (2020-12-20) @@ -368,12 +685,12 @@ import { LiveSocket } from "phoenix_live_view" - Run `consume_uploaded_entries` in LiveView caller process ### Bug fixes - - Fix hooks not getting remounted after liveview recovery + - Fix hooks not getting remounted after LiveView recovery - Fix bug causing reload with jitter on timeout from previously closed channel - Fix component child nodes being lost when component patch goes from single root node to multiple child siblings - Fix `phx-capture-click` triggering on mouseup during text selection - Fix LiveView `push_event`'s not clearing up in components - - Fix textarea being patched by LV while focused + - Fix ` + + +
+ disconnected! +
+ + ` + document.body.innerHTML = "" + document.body.appendChild(div) + return div +} + + diff --git a/assets/test/utils_test.js b/assets/test/utils_test.js new file mode 100644 index 0000000000..08461c87d3 --- /dev/null +++ b/assets/test/utils_test.js @@ -0,0 +1,37 @@ +import {Socket} from "phoenix" +import { closestPhxBinding } from "phoenix_live_view/utils" +import LiveSocket from "phoenix_live_view/live_socket" +import { simulateJoinedView, liveViewDOM } from "./test_helpers" + +let setupView = (content) => { + let el = liveViewDOM(content) + global.document.body.appendChild(el) + let liveSocket = new LiveSocket("/live", Socket) + return simulateJoinedView(el, liveSocket) +} + +describe("utils", () => { + describe("closestPhxBinding", () => { + test("if an element's parent has a phx-click binding and is not disabled, return the parent", () => { + let view = setupView(` + + `) + let element = global.document.querySelector("#innerContent") + let parent = global.document.querySelector("#button") + expect(closestPhxBinding(element, "phx-click")).toBe(parent) + }) + + test("if an element's parent is disabled, return null", () => { + let view = setupView(` + + `) + let element = global.document.querySelector("#innerContent") + expect(closestPhxBinding(element, "phx-click")).toBe(null) + }) + }) +}) + diff --git a/assets/test/view_test.js b/assets/test/view_test.js index 3c5aa8c3e8..eaf330cd16 100644 --- a/assets/test/view_test.js +++ b/assets/test/view_test.js @@ -3,29 +3,9 @@ import LiveSocket from "phoenix_live_view/live_socket" import DOM from "phoenix_live_view/dom" import View from "phoenix_live_view/view" -import {tag, simulateJoinedView, stubChannel, rootContainer} from "./test_helpers" +import {tag, simulateJoinedView, stubChannel, rootContainer, liveViewDOM, simulateVisibility} from "./test_helpers" -function liveViewDOM(content){ - const div = document.createElement("div") - div.setAttribute("data-phx-view", "User.Form") - div.setAttribute("data-phx-session", "abc123") - div.setAttribute("id", "container") - div.setAttribute("class", "user-implemented-class") - div.innerHTML = content || ` -
- - - - - -
- ` - document.body.innerHTML = "" - document.body.appendChild(div) - return div -} - -describe("View + DOM", function (){ +describe("View + DOM", function(){ beforeEach(() => { submitBefore = HTMLFormElement.prototype.submit global.Phoenix = {Socket} @@ -51,7 +31,7 @@ describe("View + DOM", function (){ expect(view.rendered.get()).toEqual(updateDiff) }) - test("pushWithReply", function (){ + test("pushWithReply", function(){ expect.assertions(1) let liveSocket = new LiveSocket("/live", Socket) @@ -71,7 +51,7 @@ describe("View + DOM", function (){ view.pushWithReply(null, {target: el.querySelector("form")}, {value: "increment=1"}) }) - test("pushWithReply with update", function (){ + test("pushWithReply with update", function(){ let liveSocket = new LiveSocket("/live", Socket) let el = liveViewDOM() @@ -103,7 +83,7 @@ describe("View + DOM", function (){ expect(view.el.querySelector("form")).toBeTruthy() }) - test("pushEvent", function (){ + test("pushEvent", function(){ expect.assertions(3) let liveSocket = new LiveSocket("/live", Socket) @@ -126,7 +106,7 @@ describe("View + DOM", function (){ view.pushEvent("keyup", input, el, "click", {}) }) - test("pushEvent as checkbox not checked", function (){ + test("pushEvent as checkbox not checked", function(){ expect.assertions(1) let liveSocket = new LiveSocket("/live", Socket) @@ -147,7 +127,7 @@ describe("View + DOM", function (){ view.pushEvent("click", input, el, "toggle_me", {}) }) - test("pushEvent as checkbox when checked", function (){ + test("pushEvent as checkbox when checked", function(){ expect.assertions(1) let liveSocket = new LiveSocket("/live", Socket) @@ -170,7 +150,7 @@ describe("View + DOM", function (){ view.pushEvent("click", input, el, "toggle_me", {}) }) - test("pushEvent as checkbox with value", function (){ + test("pushEvent as checkbox with value", function(){ expect.assertions(1) let liveSocket = new LiveSocket("/live", Socket) @@ -194,30 +174,7 @@ describe("View + DOM", function (){ view.pushEvent("click", input, el, "toggle_me", {}) }) - test("pushKey", function (){ - expect.assertions(3) - - let liveSocket = new LiveSocket("/live", Socket) - let el = liveViewDOM() - let input = el.querySelector("input") - - let view = simulateJoinedView(el, liveSocket) - let channelStub = { - push(_evt, payload, _timeout){ - expect(payload.type).toBe("keydown") - expect(payload.event).toBeDefined() - expect(payload.value).toEqual({"key": "A", "value": "1"}) - return { - receive(){ return this } - } - } - } - view.channel = channelStub - - view.pushKey(input, el, "keydown", "move", {key: "A"}) - }) - - test("pushInput", function (){ + test("pushInput", function(){ expect.assertions(3) let liveSocket = new LiveSocket("/live", Socket) @@ -237,10 +194,10 @@ describe("View + DOM", function (){ } view.channel = channelStub - view.pushInput(input, el, null, "validate", input) + view.pushInput(input, el, null, "validate", {_target: input.name}) }) - test("formsForRecovery", function (){ + test("formsForRecovery", function(){ let view, html, liveSocket = new LiveSocket("/live", Socket) html = "
" @@ -270,8 +227,8 @@ describe("View + DOM", function (){ expect(view.formsForRecovery().length).toBe(0) }) - describe("submitForm", function (){ - test("submits payload", function (){ + describe("submitForm", function(){ + test("submits payload", function(){ expect.assertions(3) let liveSocket = new LiveSocket("/live", Socket) @@ -293,7 +250,33 @@ describe("View + DOM", function (){ view.submitForm(form, form, {target: form}) }) - test("disables elements after submission", function (){ + test("payload includes submitter when provided", function(){ + let liveSocket = new LiveSocket("/live", Socket) + let el = liveViewDOM() + let form = el.querySelector("form") + let btn = document.createElement("button") + btn.setAttribute("type", "submit") + btn.setAttribute("name", "btnName") + btn.setAttribute("value", "btnValue") + form.appendChild(btn) + + let view = simulateJoinedView(el, liveSocket) + let channelStub = { + push(_evt, payload, _timeout){ + expect(payload.type).toBe("form") + expect(payload.event).toBeDefined() + expect(payload.value).toBe("increment=1¬e=2&btnName=btnValue") + return { + receive(){ return this } + } + } + } + + view.channel = channelStub + view.submitForm(form, form, {target: form}, btn) + }) + + test("disables elements after submission", function(){ let liveSocket = new LiveSocket("/live", Socket) let el = liveViewDOM() let form = el.querySelector("form") @@ -303,13 +286,16 @@ describe("View + DOM", function (){ view.submitForm(form, form, {target: form}) expect(DOM.private(form, "phx-has-submitted")).toBeTruthy() + Array.from(form.elements).forEach(input => { + expect(DOM.private(input, "phx-has-submitted")).toBeTruthy() + }) expect(form.classList.contains("phx-submit-loading")).toBeTruthy() expect(form.querySelector("button").dataset.phxDisabled).toBeTruthy() expect(form.querySelector("input").dataset.phxReadonly).toBeTruthy() expect(form.querySelector("textarea").dataset.phxReadonly).toBeTruthy() }) - test("disables elements outside form", function (){ + test("disables elements outside form", function(){ let liveSocket = new LiveSocket("/live", Socket) let el = liveViewDOM(`
@@ -332,6 +318,21 @@ describe("View + DOM", function (){ expect(el.querySelector("input").dataset.phxReadonly).toBeTruthy() expect(el.querySelector("textarea").dataset.phxReadonly).toBeTruthy() }) + + test("disables elements", function(){ + let liveSocket = new LiveSocket("/live", Socket) + let el = liveViewDOM(` + + `) + let button = el.querySelector("button") + + let view = simulateJoinedView(el, liveSocket) + stubChannel(view) + + expect(button.disabled).toEqual(false) + view.pushEvent("click", button, el, "inc", {}) + expect(button.disabled).toEqual(true) + }) }) describe("phx-trigger-action", () => { @@ -373,7 +374,7 @@ describe("View + DOM", function (){ }) }) - describe("phx-update", function (){ + describe("phx-update", function(){ let childIds = () => Array.from(document.getElementById("list").children).map(child => parseInt(child.id)) let countChildNodes = () => document.getElementById("list").childNodes.length @@ -461,7 +462,7 @@ describe("View + DOM", function (){ expect(childIds()).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9]) // Make sure we don't have a memory leak when doing updates - let initalCount = countChildNodes() + let initialCount = countChildNodes() updateDynamics(view, [["1", "1"], ["2", "2"], ["3", "3"]] ) @@ -475,7 +476,7 @@ describe("View + DOM", function (){ [["1", "1"], ["2", "2"], ["3", "3"]] ) - expect(countChildNodes()).toBe(initalCount) + expect(countChildNodes()).toBe(initialCount) }) test("prepend", async () => { @@ -525,7 +526,7 @@ describe("View + DOM", function (){ expect(childIds()).toEqual([8, 9, 6, 7, 4, 5, 2, 3, 1]) // Make sure we don't have a memory leak when doing updates - let initalCount = countChildNodes() + let initialCount = countChildNodes() updateDynamics(view, [["1", "1"], ["2", "2"], ["3", "3"]] ) @@ -539,7 +540,7 @@ describe("View + DOM", function (){ [["1", "1"], ["2", "2"], ["3", "3"]] ) - expect(countChildNodes()).toBe(initalCount) + expect(countChildNodes()).toBe(initialCount) }) test("ignore", async () => { @@ -556,7 +557,7 @@ describe("View + DOM", function (){ }) let submitBefore -describe("View", function (){ +describe("View", function(){ beforeEach(() => { submitBefore = HTMLFormElement.prototype.submit global.Phoenix = {Socket} @@ -611,32 +612,44 @@ describe("View", function (){ test("showLoader and hideLoader", async () => { let liveSocket = new LiveSocket("/live", Socket) - let el = document.querySelector("[data-phx-view]") + let el = document.querySelector("[data-phx-session]") let view = simulateJoinedView(el, liveSocket) view.showLoader() - expect(el.classList.contains("phx-disconnected")).toBeTruthy() + expect(el.classList.contains("phx-loading")).toBeTruthy() expect(el.classList.contains("phx-connected")).toBeFalsy() expect(el.classList.contains("user-implemented-class")).toBeTruthy() view.hideLoader() - expect(el.classList.contains("phx-disconnected")).toBeFalsy() + expect(el.classList.contains("phx-loading")).toBeFalsy() expect(el.classList.contains("phx-connected")).toBeTruthy() }) - test("displayError", async () => { + test("displayError and hideLoader", done => { let liveSocket = new LiveSocket("/live", Socket) let loader = document.createElement("span") - let phxView = document.querySelector("[data-phx-view]") + let phxView = document.querySelector("[data-phx-session]") phxView.parentNode.insertBefore(loader, phxView.nextSibling) - let el = document.querySelector("[data-phx-view]") + let el = document.querySelector("[data-phx-session]") + let status = el.querySelector("#status") let view = simulateJoinedView(el, liveSocket) + + expect(status.style.display).toBe("none") view.displayError() - expect(el.classList.contains("phx-disconnected")).toBeTruthy() + expect(el.classList.contains("phx-loading")).toBeTruthy() expect(el.classList.contains("phx-error")).toBeTruthy() expect(el.classList.contains("phx-connected")).toBeFalsy() expect(el.classList.contains("user-implemented-class")).toBeTruthy() + window.requestAnimationFrame(() => { + expect(status.style.display).toBe("block") + simulateVisibility(status) + view.hideLoader() + window.requestAnimationFrame(() => { + expect(status.style.display).toBe("none") + done() + }) + }) }) test("join", async () => { @@ -678,7 +691,7 @@ describe("View", function (){ }) }) -describe("View Hooks", function (){ +describe("View Hooks", function(){ beforeEach(() => { global.document.body.innerHTML = liveViewDOM().outerHTML }) @@ -687,12 +700,45 @@ describe("View Hooks", function (){ global.document.body.innerHTML = "" }) + test("phx-mounted", done => { + let liveSocket = new LiveSocket("/live", Socket) + let el = liveViewDOM() + + let html = "

test mounted

" + el.innerHTML = html + + let view = simulateJoinedView(el, liveSocket) + + view.onJoin({ + rendered: { + s: [html], + fingerprint: 123 + } + }) + window.requestAnimationFrame(() => { + expect(document.getElementById("test").getAttribute("class")).toBe("new-class") + view.update({ + s: [html + "

test mounted

"], + fingerprint: 123 + }, []) + window.requestAnimationFrame(() => { + expect(document.getElementById("test").getAttribute("class")).toBe("new-class") + expect(document.getElementById("test2").getAttribute("class")).toBe("new-class2") + done() + }) + }) + }) + test("hooks", async () => { let upcaseWasDestroyed = false let upcaseBeforeUpdate = false + let hookLiveSocket let Hooks = { Upcase: { - mounted(){ this.el.innerHTML = this.el.innerHTML.toUpperCase() }, + mounted(){ + hookLiveSocket = this.liveSocket + this.el.innerHTML = this.el.innerHTML.toUpperCase() + }, beforeUpdate(){ upcaseBeforeUpdate = true }, updated(){ this.el.innerHTML = this.el.innerHTML + " updated" }, disconnected(){ this.el.innerHTML = "disconnected" }, @@ -728,6 +774,7 @@ describe("View Hooks", function (){ view.update({s: ["
"], fingerprint: 123}, []) expect(upcaseWasDestroyed).toBe(true) + expect(hookLiveSocket).toBeDefined() }) test("view destroyed", async () => { @@ -843,7 +890,6 @@ describe("View Hooks", function (){ function liveViewComponent(){ const div = document.createElement("div") - div.setAttribute("data-phx-view", "User.Form") div.setAttribute("data-phx-session", "abc123") div.setAttribute("id", "container") div.setAttribute("class", "user-implemented-class") @@ -860,7 +906,7 @@ function liveViewComponent(){ return div } -describe("View + Component", function (){ +describe("View + Component", function(){ beforeEach(() => { global.Phoenix = {Socket} global.document.body.innerHTML = liveViewComponent().outerHTML @@ -880,7 +926,7 @@ describe("View + Component", function (){ expect(view.targetComponentID(form, targetCtx)).toBe(0) }) - test("pushEvent", function (){ + test("pushEvent", function(){ expect.assertions(4) let liveSocket = new LiveSocket("/live", Socket) @@ -905,7 +951,7 @@ describe("View + Component", function (){ view.pushEvent("keyup", input, targetCtx, "click", {}) }) - test("pushInput", function (){ + test("pushInput", function(){ expect.assertions(6) let html = ` @@ -960,17 +1006,82 @@ describe("View + Component", function (){ view.channel.nextValidate({"user[first_name]": null, "user[last_name]": null, "_target": "user[first_name]"}) // we have to set this manually since it's set by a change event that would require more plumbing with the liveSocket in the test to hook up DOM.putPrivate(first_name, "phx-has-focused", true) - view.pushInput(first_name, el, null, "validate", first_name) + view.pushInput(first_name, el, null, "validate", {_target: first_name.name}) expect(el.querySelector(`[phx-feedback-for="${first_name.name}"`).classList.contains("phx-no-feedback")).toBeFalsy() expect(el.querySelector(`[phx-feedback-for="${last_name.name}"`).classList.contains("phx-no-feedback")).toBeTruthy() view.channel.nextValidate({"user[first_name]": null, "user[last_name]": null, "_target": "user[last_name]"}) DOM.putPrivate(last_name, "phx-has-focused", true) - view.pushInput(last_name, el, null, "validate", last_name) + view.pushInput(last_name, el, null, "validate", {_target: last_name.name}) expect(el.querySelector(`[phx-feedback-for="${first_name.name}"`).classList.contains("phx-no-feedback")).toBeFalsy() expect(el.querySelector(`[phx-feedback-for="${last_name.name}"`).classList.contains("phx-no-feedback")).toBeFalsy() }) + test("pushInput sets phx-no-feedback class on feedback elements for multiple select", function(){ + // a multiple select name attribute contains trailing square brackets [] to capture multiple options + let multiple_select_name = "user[allergies][]" + // the phx-feedback-for attribute typically doesn't contain trailing brackets + // because its value is often set with the result of Phoenix.HTML.input_name/2 + let multiple_select_phx_feedback_for_name = "user[allergies]" + let html = + ` + + + + + +
` + let liveSocket = new LiveSocket("/live", Socket) + let el = liveViewDOM(html) + let view = simulateJoinedView(el, liveSocket, html) + let channelStub = { + push(_evt, _payload, _timeout){ + return { + receive(_status, cb){ + let diff = { + s: [` +
+ + + + + + + +
+ `], + fingerprint: 345 + } + cb({diff}) + return this + } + } + } + } + view.channel = channelStub + + let first_name_input = view.el.querySelector("input#first_name") + let allergies_select = view.el.querySelector("select#allergies") + // we have to set this manually since it's set by a change event that would require more plumbing with the liveSocket in the test to hook up + DOM.putPrivate(first_name_input, "phx-has-focused", true) + view.pushInput(first_name_input, el, null, "validate", {_target: "user[first_name]"}) + expect(el.querySelector(`span[phx-feedback-for="user[first_name]"`).classList.contains("phx-no-feedback")).toBeFalsy() + expect(el.querySelector(`span[phx-feedback-for="user[allergies]"`).classList.contains("phx-no-feedback")).toBeTruthy() + + DOM.putPrivate(allergies_select, "phx-has-focused", true) + view.pushInput(allergies_select, el, null, "validate", {_target: "user[allergies][]"}) + expect(el.querySelector(`span[phx-feedback-for="user[first_name]"`).classList.contains("phx-no-feedback")).toBeFalsy() + expect(el.querySelector(`span[phx-feedback-for="user[allergies]"`).classList.contains("phx-no-feedback")).toBeFalsy() + }) + test("adds auto ID to prevent teardown/re-add", () => { let liveSocket = new LiveSocket("/live", Socket) let el = liveViewDOM() @@ -1057,10 +1168,9 @@ describe("View + Component", function (){ test("destroys children when they are removed by an update", () => { let id = "root" - let childHTML = `
` - let newChildHTML = `
` + let childHTML = `
` + let newChildHTML = `
` let el = document.createElement("div") - el.setAttribute("data-phx-view", "Root") el.setAttribute("data-phx-session", "abc123") el.setAttribute("id", id) document.body.appendChild(el) @@ -1086,12 +1196,12 @@ describe("View + Component", function (){ describe("undoRefs", () => { test("restores phx specific attributes awaiting a ref", () => { let content = ` - -
- + + + - +
`.trim() let liveSocket = new LiveSocket("/live", Socket) @@ -1101,11 +1211,11 @@ describe("View + Component", function (){ view.undoRefs(1) expect(el.innerHTML).toBe(` -
- + + - +
`.trim()) @@ -1125,10 +1235,11 @@ describe("View + Component", function (){ let liveSocket = new LiveSocket("/live", Socket) let el = rootContainer("") - let fromEl = tag("span", {"data-phx-ref": "1"}, "hello") + let fromEl = tag("span", {"data-phx-ref-src": el.id, "data-phx-ref": "1"}, "hello") let toEl = tag("span", {"class": "new"}, "world") DOM.putPrivate(fromEl, "data-phx-ref", toEl) + el.appendChild(fromEl) let view = simulateJoinedView(el, liveSocket) @@ -1151,7 +1262,8 @@ describe("View + Component", function (){ let view = simulateJoinedView(el, liveSocket) stubChannel(view) view.onJoin({rendered: {s: ["Hello"]}}) - view.update({s: ["Hello"]}, []) + + view.update({s: ["Hello"]}, []) let toEl = tag("span", {"id": "myhook", "phx-hook": "MyHook"}, "world") DOM.putPrivate(el.querySelector("#myhook"), "data-phx-ref", toEl) @@ -1165,8 +1277,8 @@ describe("View + Component", function (){ }) }) -describe("DOM", function (){ - it("mergeAttrs attributes", function (){ +describe("DOM", function(){ + it("mergeAttrs attributes", function(){ const target = document.createElement("target") target.type = "checkbox" target.id = "foo" @@ -1185,7 +1297,7 @@ describe("DOM", function (){ expect(target.id).toEqual("bar") }) - it("mergeAttrs with properties", function (){ + it("mergeAttrs with properties", function(){ const target = document.createElement("target") target.type = "checkbox" target.id = "foo" diff --git a/config/config.exs b/config/config.exs index cec6a3f648..6bdde661d0 100644 --- a/config/config.exs +++ b/config/config.exs @@ -1,4 +1,4 @@ -use Mix.Config +import Config config :phoenix, :json_library, Jason config :phoenix, :trim_on_html_eex_engine, false diff --git a/guides/client/bindings.md b/guides/client/bindings.md index 2a8d7ee64b..ae91e20736 100644 --- a/guides/client/bindings.md +++ b/guides/client/bindings.md @@ -16,15 +16,15 @@ callback, for example: | Binding | Attributes | |------------------------|------------| | [Params](#click-events) | `phx-value-*` | -| [Click Events](#click-events) | `phx-click`, `phx-capture-click` | +| [Click Events](#click-events) | `phx-click`, `phx-click-away` | | [Form Events](form-bindings.md) | `phx-change`, `phx-submit`, `phx-feedback-for`, `phx-disable-with`, `phx-trigger-action`, `phx-auto-recover` | -| [Focus/Blur Events](#focus-and-blur-events) | `phx-blur`, `phx-focus`, `phx-window-blur`, `phx-window-focus` | +| [Focus Events](#focus-and-blur-events) | `phx-blur`, `phx-focus`, `phx-window-blur`, `phx-window-focus` | | [Key Events](#key-events) | `phx-keydown`, `phx-keyup`, `phx-window-keydown`, `phx-window-keyup`, `phx-key` | -| [DOM Patching](dom-patching.md) | `phx-update` | +| [DOM Patching](dom-patching.md) | `phx-mounted`, `phx-update`, `phx-remove` | | [JS Interop](js-interop.md#client-hooks) | `phx-hook` | +| [Lifecycle Events](#lifecycle-events) | `phx-mounted`, `phx-disconnected`, `phx-connected` | | [Rate Limiting](#rate-limiting-events-with-debounce-and-throttle) | `phx-debounce`, `phx-throttle` | -| [Static tracking](`Phoenix.LiveView.static_changed?/1) | `phx-track-static` | -| [Loading states](js-interop.md#loading-state-and-errors) | `phx-page-loading` | +| [Static tracking](`Phoenix.LiveView.static_changed?/1`) | `phx-track-static` | ## Click Events @@ -32,6 +32,12 @@ The `phx-click` binding is used to send click events to the server. When any client event, such as a `phx-click` click is pushed, the value sent to the server will be chosen with the following priority: + * The `:value` specified in `Phoenix.LiveView.JS.push/3`, such as: + + ```heex +
+ ``` + * Any number of optional `phx-value-` prefixed attributes, such as:
@@ -43,9 +49,9 @@ sent to the server will be chosen with the following priority: If the `phx-value-` prefix is used, the server payload will also contain a `"value"` if the element's value attribute exists. - * When receiving a map on the server, the payload will also include user defined metadata - of the client event, or an empty map if none is set. For example, the following `LiveSocket` - client option would send the coordinates and `altKey` information for all clicks: + * The payload will also include any additional user defined metadata of the client event. + For example, the following `LiveSocket` client option would send the coordinates and + `altKey` information for all clicks: let liveSocket = new LiveSocket("/live", Socket, { params: {_csrf_token: csrfToken}, @@ -60,20 +66,17 @@ sent to the server will be chosen with the following priority: } }) - -The `phx-capture-click` event is just like `phx-click`, but instead of the click event -being dispatched to the closest `phx-click` element as it bubbles up through the DOM, the event -is dispatched as it propagates from the top of the DOM tree down to the target element. This is -useful when wanting to bind click events without receiving bubbled events from child UI elements. -Since capturing happens before bubbling, this can also be important for preparing or preventing -behaviour that will be applied during the bubbling phase. +The `phx-click-away` event is fired when a click event happens outside of the element. +This is useful for hiding toggled containers like drop-downs. ## Focus and Blur Events Focus and blur events may be bound to DOM elements that emit such events, using the `phx-blur`, and `phx-focus` bindings, for example: - +```heex + +``` To detect when the page itself has received focus or blur, `phx-window-focus` and `phx-window-blur` may be specified. These window @@ -82,19 +85,14 @@ level events may also be necessary if the element in consideration bindings, `phx-value-*` can be provided on the bound element, and those values will be sent as part of the payload. For example: -
- ... -
- -The following window-level bindings are supported: - - * `phx-window-focus` - * `phx-window-blur` - * `phx-window-keydown` - * `phx-window-keyup` +```heex +
+ ... +
+``` ## Key Events @@ -128,6 +126,9 @@ available options can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) or via the [Key Event Viewer](https://w3c.github.io/uievents/tools/key-event-viewer.html). +*Note*: it is possible for certain browser features like autofill to trigger key events +with no `"key"` field present in the value map sent to the server. For this reason, we +recommend always having a fallback catch-all event handler for LiveView key bindings. By default, the bound element will be the event listener, but a window-level binding may be provided via `phx-window-keydown` or `phx-window-keyup`, for example: @@ -150,14 +151,17 @@ for example: {:noreply, assign(socket, :temperature, new_temp)} end - def handle_event("update_temp", _key, socket) do + def handle_event("update_temp", _, socket) do {:noreply, socket} end ## Rate limiting events with Debounce and Throttle All events can be rate-limited on the client by using the -`phx-debounce` and `phx-throttle` bindings, with the following behavior: +`phx-debounce` and `phx-throttle` bindings, with the exception of the `phx-blur` +binding, which is fired immediately. + +Rate limited and debounced events have the following behavior: * `phx-debounce` - Accepts either an integer timeout value (in milliseconds), or `"blur"`. When an integer is provided, emitting the event is delayed by @@ -173,10 +177,12 @@ All events can be rate-limited on the client by using the For example, to avoid validating an email until the field is blurred, while validating the username at most every 2 seconds after a user changes the field: -
- - -
+```heex +
+ + +
+``` And to rate limit a volume up click to once every second: @@ -184,9 +190,11 @@ And to rate limit a volume up click to once every second: Likewise, you may throttle held-down keydown: -
- ... -
+```heex +
+ ... +
+``` Unless held-down keys are required, a better approach is generally to use `phx-keyup` bindings which only trigger on key up, thereby being self-limiting. @@ -203,17 +211,173 @@ The following specialized behavior is performed for forms and keydown bindings: * A `phx-keydown` binding is only throttled for key repeats. Unique keypresses back-to-back will dispatch the pressed key events. +## JS Commands + +LiveView bindings support a JavaScript command interface via the `Phoenix.LiveView.JS` module, which allows you to specify utility operations that execute on the client when firing `phx-` binding events, such as `phx-click`, `phx-change`, etc. Commands compose together to allow you to push events, add classes to elements, transition elements in and out, and more. +See the `Phoenix.LiveView.JS` documentation for full usage. + +For a small example of what's possible, imagine you want to show and hide a modal on the page without needing to make the round trip to the server to render the content: + +```heex + + + + + + + +``` + +Or if your UI library relies on classes to perform the showing or hiding: + +```heex + + + + + +``` + +Commands compose together. For example, you can push an event to the server and +immediately hide the modal on the client: + +```heex + + + +``` + +It is also useful to extract commands into their own functions: + +```elixir +alias Phoenix.LiveView.JS + +def hide_modal(js \\ %JS{}, selector) do + js + |> JS.push("modal-closed") + |> JS.remove_class("show", to: selector, transition: "fade-out") +end +``` + +```heex + +``` + +The `Phoenix.LiveView.JS.push/3` command is particularly powerful in allowing you to customize the event being pushed to the server. For example, imagine you start with a familiar `phx-click` which pushes a message to the server when clicked: + +```heex + +``` + +Now imagine you want to customize what happens when the `"clicked"` event is pushed, such as which component should be targeted, which element should receive css loading state classes, etc. This can be accomplished with options on the JS push command. For example: + +```heex + +``` + +See `Phoenix.LiveView.JS.push/3` for all supported options. + +## Lifecycle Events + +LiveView supports the `phx-mounted`, `phx-connected`, and `phx-disconnected` events to react to +different lifecycle events with JS commands. + +To execute commands when an element first appears on the page, you can leverage `phx-mounted`, +such as to animate a notice into view: + +```heex + +``` + +If `phx-mounted` is used on the initial page render, it will be invoked only after the initial WebSocket connection is established. + +To manage the connection lifecycle, you can combine `phx-disconnected` and `phx-connected` to show an element when the LiveView has lost its connection, and hide it when the connection recovers: + +```heex + +``` + +### LiveView vs static view + +`phx-connected` and `phx-disconnected` are only executed when operating +inside a LiveView container. For static templates, they will have no effect. + +For LiveView, the `phx-mounted` binding is executed as soon as the LiveView is +mounted with a connection. When using `phx-mounted` in static views, it is executed +as soon as the DOM is ready. + ## LiveView Specific Events The `lv:` event prefix supports LiveView specific features that are handled by LiveView without calling the user's `handle_event/3` callbacks. Today, the following events are supported: - - `lv:clear-flash` – clears the flash when sent to the server. If a + - `lv:clear-flash` – clears the flash when sent to the server. If a `phx-value-key` is provided, the specific key will be removed from the flash. For example: -

- <%= live_flash(@flash, :info) %> -

+```heex +

+ <%= live_flash(@flash, :info) %> +

+``` + +## Loading states and errors + +All `phx-` event bindings apply their own css classes when pushed. For example +the following markup: + +```heex + +``` + +On click, would receive the `phx-click-loading` class, and on keydown would receive +the `phx-keydown-loading` class. The css loading classes are maintained until an +acknowledgement is received on the client for the pushed event. + +In the case of forms, when a `phx-change` is sent to the server, the input element +which emitted the change receives the `phx-change-loading` class, along with the +parent form tag. The following events receive css loading classes: + + - `phx-click` - `phx-click-loading` + - `phx-change` - `phx-change-loading` + - `phx-submit` - `phx-submit-loading` + - `phx-focus` - `phx-focus-loading` + - `phx-blur` - `phx-blur-loading` + - `phx-window-keydown` - `phx-keydown-loading` + - `phx-window-keyup` - `phx-keyup-loading` + +Additionally, the following classes are applied to the LiveView's parent +container: + + - `"phx-connected"` - applied when the view has connected to the server + - `"phx-loading"` - applied when the view is not connected to the server + - `"phx-error"` - applied when an error occurs on the server. Note, this + class will be applied in conjunction with `"phx-loading"` if connection + to the server is lost. + +For navigation related loading states (both automatic and manual), see `phx-page-loading` as described in +[JavaScript interoperability: Live navigation events](js-interop.html#live-navigation-events). diff --git a/guides/client/dom-patching.md b/guides/client/dom-patching.md index 0def919c04..efdb087ee4 100644 --- a/guides/client/dom-patching.md +++ b/guides/client/dom-patching.md @@ -7,23 +7,34 @@ is useful for client-side interop with existing libraries that do their own DOM operations. The following `phx-update` values are supported: * `replace` - the default operation. Replaces the element with the contents + * `stream` - supports stream operations. Streams are used to manage large + collections in the UI without having to store the collection on the server * `ignore` - ignores updates to the DOM regardless of new content changes - * `append` - append the new DOM contents instead of replacing - * `prepend` - prepend the new DOM contents instead of replacing When using `phx-update`, a unique DOM ID must always be set in the -container. If using "append" or "prepend", a DOM ID must also be set -for each child. When appending or prepending elements containing an +container. If using "stream", a DOM ID must also be set +for each child. When inserting stream elements containing an ID already present in the container, LiveView will replace the existing -element with the new content instead appending or prepending a new -element. +element with the new content. See `Phoenix.LiveView.stream/3` for more +information. The "ignore" behaviour is frequently used when you need to integrate with another JS library. Note only the element contents are ignored, its attributes can still be updated. -The "append" and "prepend" feature is often used with "Temporary assigns" -to work with large amounts of data. Let's learn more. +To react to elements being mounted to the DOM, the `phx-mounted` binding +can be used. For example, to animate an element on mount: + +
+ +If `phx-mounted` is used on the initial page render, it will be invoked only +after the initial WebSocket connection is established. + +To react to elements being removed from the DOM, the `phx-remove` binding +may be specified, which can contain a `Phoenix.LiveView.JS` command to execute. + +*Note*: The `phx-remove` command is only executed for the removed parent element. +It does not cascade to children. ## Temporary assigns @@ -36,9 +47,11 @@ to be discarded after the client has been patched. Imagine you want to implement a chat application with LiveView. You could render each message like this: - <%= for message <- @messages do %> -

<%= message.username %>: <%= message.text %>

- <% end %> +```heex +<%= for message <- @messages do %> +

<%= message.username %>: <%= message.text %>

+<% end %> +``` Every time there is a new message, you would append it to the `@messages` assign and re-render all messages. @@ -70,13 +83,15 @@ In the template, we want to wrap all of the messages in a container and tag this content with `phx-update`. Remember, we must add an ID to the container as well as to each child: -
- <%= for message <- @messages do %> -

- <%= message.username %>: <%= message.text %> -

- <% end %> -
+```heex +
+ <%= for message <- @messages do %> +

+ <%= message.username %>: <%= message.text %> +

+ <% end %> +
+``` When the client receives new messages, it now knows to append to the old content rather than replace it. @@ -87,69 +102,12 @@ that is being sent to your LiveView like this: def handle_info({:update_message, message}, socket) do {:noreply, update(socket, :messages, fn messages -> [message | messages] end)} end - + You can add it to the list like you do with new messages. LiveView is aware that this -message was rendered on the client, even though the message itself is discarded on the +message was rendered on the client, even though the message itself is discarded on the server after it is rendered. -LiveView uses DOM ids to check if a message is rendered before or not. If an id is -rendered before, the DOM element is updated rather than appending or prepending a new node. +LiveView uses DOM ids to check if a message is rendered before or not. If an id is +rendered before, the DOM element is updated rather than appending or prepending a new node. Also, the order of elements is not changed. You can use it to show edited messages, show likes, or anything that would require an update to a rendered message. - -## Pitfall: temporary assigns to reset or control UI state - -Temporary assigns are useful when you want to render some data and -then discard it so LiveView no longer needs to keep it in memory. - -For this reason, a temporary assign is not re-rendered until it is -set again. This means that temporary assigns should not be used to -reset or control UI state. Let's see an example. - -Imagine you want to show an error message when the input is less than -3 chars. You can write this code: - -```elixir - def render(assigns) do - ~H""" - <%= if @too_short do %> - Input too short... - <% end %> - - Searched for: <%= @search %> -
- """ - end - - def mount(_params, _session, socket) do - {:ok, - assign(socket, too_short: false, search: ""), - temporary_assigns: [too_short: false]} - end - - def handle_event("search", %{"term" => term}, socket) do - # do not search if user provides less then 3 chars - if String.length(term) >= 3 do - {:noreply, assign(socket, search: term)} - else - {:noreply, assign(socket, too_short: true, search: term)} - end - end -``` - -The idea here is that, while the term is less than 3 characters, -we will set `@too_short` to true and show an error message in the -UI accordingly. We also set `@too_short` as a temporary assign, -so that it resets to `false` after every render. - -However, once a temporary assign resets to its original value, -it won't be re-rendered, unless we explicitly assign it to something -else. This means that the LiveView will never re-render the -`if` block and we will continue to show "Input too short..." even -after the input has 3 or more characters. - -The mistake here is using `:temporary_assigns` to reset or control -UI state, while `:temporary_assigns` should rather be used when we -don't have (or don't want to keep) certain data around. The fix is -to set `too_short: false` on the `if` branch, making sure it is -reset whenever the search input changes. diff --git a/guides/client/form-bindings.md b/guides/client/form-bindings.md index 88e3be018f..1d3f6d8aa5 100644 --- a/guides/client/form-bindings.md +++ b/guides/client/form-bindings.md @@ -1,58 +1,62 @@ # Form bindings -## A note about form helpers - -LiveView works with the existing `Phoenix.HTML` form helpers. -If you want to use helpers such as [`text_input/2`](`Phoenix.HTML.Form.text_input/2`), -etc. be sure to `use Phoenix.HTML` at the top of your LiveView. -If your application was generated with Phoenix v1.6, then `mix phx.new` -automatically uses `Phoenix.HTML` when you `use MyAppWeb, :live_view` or -`use MyAppWeb, :live_component` in your modules. - -Using the generated `:live_view` and `:live_component` helpers will also -`import MyAppWeb.ErrorHelpers`, a generated module where `error_tag/2` -resides (usually located at `lib/my_app_web/views/error_helpers.ex`). - -Since `ErrorHelpers` is generated into your app, it is yours -to modify – you may add additional helper functions here, such -as those recommended when rendering feedback for -[`upload_errors/1,2`](`Phoenix.LiveView.Helpers.upload_errors/2`). - ## Form Events To handle form changes and submissions, use the `phx-change` and `phx-submit` events. In general, it is preferred to handle input changes at the form level, where all form fields are passed to the LiveView's callback given any single input change. For example, to handle real-time form validation and -saving, your template would use both `phx_change` and `phx_submit` bindings: - - <.form let={f} for={@changeset} phx-change="validate" phx-submit="save"> - <%= label f, :username %> - <%= text_input f, :username %> - <%= error_tag f, :username %> - - <%= label f, :email %> - <%= text_input f, :email %> - <%= error_tag f, :email %> +saving, your form would use both `phx-change` and `phx-submit` bindings. +Let's get started with an example: + +```heex +<.form for={@form} phx-change="validate" phx-submit="save"> + <.input type="text" field={@form[:username]} /> + <.input type="email" field={@form[:email]} /> + + +``` + +`.form` is the function component defined in `Phoenix.Component.form/1`, +we recommend reading its documentation for more details on how it works +and all supported options. `.form` expects a `@form` assign, which can +be created from a changeset or user parameters via `Phoenix.Component.to_form/1`. + +`input/1` is a function component for rendering inputs, most often +defined in your own application, often encapsulating labelling, +error handling, and more. Here is a simple version to get started with: + + attr :field, Phoenix.HTML.FormField + attr :rest, include: ~w(type) + def input(assigns) do + ~H""" + + """ + end - <%= submit "Save" %> - +> ### The `CoreComponents` module {.info} +> +> If your application was generated with Phoenix v1.7, then `mix phx.new` +> automatically imports many ready-to-use function components, such as +> `.input` component with built-in features and styles. -Next, your LiveView picks up the events in `handle_event` callbacks: +With the form rendered, your LiveView picks up the events in `handle_event` +callbacks, to validate and attempt to save the parameter accordingly: def render(assigns) ... def mount(_params, _session, socket) do - {:ok, assign(socket, %{changeset: Accounts.change_user(%User{})})} + {:ok, assign(socket, form: to_form(Accounts.change_user(%User{}))} end def handle_event("validate", %{"user" => params}, socket) do - changeset = + form = %User{} |> Accounts.change_user(params) |> Map.put(:action, :insert) + |> to_form() - {:noreply, assign(socket, changeset: changeset)} + {:noreply, assign(socket, form: form)} end def handle_event("save", %{"user" => user_params}, socket) do @@ -61,16 +65,16 @@ Next, your LiveView picks up the events in `handle_event` callbacks: {:noreply, socket |> put_flash(:info, "user created") - |> redirect(to: Routes.user_path(MyAppWeb.Endpoint, MyAppWeb.User.ShowView, user))} + |> redirect(to: ~p"/users/#{user}")} {:error, %Ecto.Changeset{} = changeset} -> - {:noreply, assign(socket, changeset: changeset)} + {:noreply, assign(socket, form: to_form(changeset))} end end The validate callback simply updates the changeset based on all form input -values, then assigns the new changeset to the socket. If the changeset -changes, such as generating new errors, [`render/1`](`c:Phoenix.LiveView.render/1`) +values, then convert the changeset to a form and assign it to the socket. +If the form changes, such as generating new errors, [`render/1`](`c:Phoenix.LiveView.render/1`) is invoked and the form is re-rendered. Likewise for `phx-submit` bindings, the same callback is invoked and @@ -79,6 +83,27 @@ socket is annotated for redirect with `Phoenix.LiveView.redirect/2` to the new user page, otherwise the socket assigns are updated with the errored changeset to be re-rendered for the client. +You may wish for an individual input to use its own change event or to target +a different component. This can be accomplished by annotating the input itself +with `phx-change`, for example: + +``` +<.form for={@form} phx-change="validate" phx-submit="save"> + ... + <.input field={@form[:email]} phx-change="email_changed" phx-target={@myself} /> + +``` + +Then your LiveView or LiveComponent would handle the event: + +```elixir +def handle_event("email_changed", %{"user" => %{"email" => email}}, socket) do + ... +end +``` + +_Note_: only the individual input is sent as params for an input marked with `phx-change`. + ## `phx-feedback-for` For proper form error tag updates, the error tag must specify which @@ -88,27 +113,40 @@ Failing to add the `phx-feedback-for` attribute will result in displaying error messages for form fields that the user has not changed yet (e.g. required fields further down on the page). -For example, your `MyAppWeb.ErrorHelpers` may use this function: - - def error_tag(form, field) do - form.errors - |> Keyword.get_values(field) - |> Enum.map(fn error -> - content_tag(:span, translate_error(error), - class: "invalid-feedback", - phx_feedback_for: input_name(form, field) - ) - end) +For example, your `MyAppWeb.CoreComponents` may use this function: + + def input(assigns) do + ~H""" +
+ + <.error :for={msg <- @errors}><%%= msg %> +
+ """ + end + + def error(assigns) do + ~H""" +

+ + <%= render_slot(@inner_block) %> +

+ """ end Now, any DOM container with the `phx-feedback-for` attribute will receive a `phx-no-feedback` class in cases where the form fields has yet to receive -user input/focus. The following css rules are generated in new projects -to hide the errors: - - .phx-no-feedback.invalid-feedback, .phx-no-feedback .invalid-feedback { - display: none; - } +user input/focus. Using new CSS rules or tailwindcss variants allows you +errors to be shown, hidden, and styled as feedback changes. ## Number inputs @@ -118,7 +156,9 @@ from the client when an input is invalid, instead allowing the browser's native validation UI to drive user interaction. Once the input becomes valid, change and submit events will be sent normally. - +```heex + +``` This is known to have a plethora of problems including accessibility, large numbers are converted to exponential notation, and scrolling can accidentally increase or @@ -128,7 +168,9 @@ One alternative is the `inputmode` attribute, which may serve your application's and users much better. According to [Can I Use?](https://caniuse.com/#search=inputmode), the following is supported by 86% of the global market (as of Sep 2021): - +```heex + +``` ## Password inputs @@ -136,10 +178,21 @@ Password inputs are also special cased in `Phoenix.HTML`. For security reasons, password field values are not reused when rendering a password input tag. This requires explicitly setting the `:value` in your markup, for example: - <%= password_input f, :password, value: input_value(f, :password) %> - <%= password_input f, :password_confirmation, value: input_value(f, :password_confirmation) %> - <%= error_tag f, :password %> - <%= error_tag f, :password_confirmation %> +```heex +<.input field={f[:password]} value={input_value(f[:password].value)} /> +<.input field={f[:password_confirmation]} value={input_value(f[:password_confirmation].value)} /> +``` + +## Nested inputs + +Nested inputs are handled using `.inputs_for` function component. By default +it will add the necessary hidden input fields for tracking ids of Ecto associations. + +```heex +<.inputs_for :let={fp} field={f[:friends]}> + <.input field={fp[:name]} type="text"> + +``` ## File inputs @@ -147,12 +200,14 @@ LiveView forms support [reactive file inputs](uploads.md), including drag and drop support via the `phx-drop-target` attribute: -
- ... - <%= live_file_input @uploads.avatar %> -
+```heex +
+ ... + <.live_file_input upload={@uploads.avatar} /> +
+``` -See `Phoenix.LiveView.Helpers.live_file_input/2` for more. +See `Phoenix.Component.live_file_input/1` for more. ## Submitting the form action over HTTP @@ -163,10 +218,12 @@ submit before posting to a controller route for operations that require Plug session mutation. For example, in your LiveView template you can annotate the `phx-trigger-action` with a boolean assign: - <.form let={f} for={@changeset} - action={Routes.reset_password_path(@socket, :create)} - phx-submit="save", - phx-trigger-action={@trigger_submit}> +```heex +<.form :let={f} for={@changeset} + action={Routes.reset_password_path(@socket, :create)} + phx-submit="save" + phx-trigger-action={@trigger_submit}> +``` Then in your LiveView, you can toggle the assign to trigger the form with the current fields on next render: @@ -178,17 +235,18 @@ fields on next render: {:error, changeset} -> {:noreply, assign(socket, changeset: changeset)} - end + end end Once `phx-trigger-action` is true, LiveView disconnects and then submits the form. ## Recovery following crashes or disconnects -By default, all forms marked with `phx-change` will recover input values -automatically after the user has reconnected or the LiveView has remounted -after a crash. This is achieved by the client triggering the same `phx-change` -to the server as soon as the mount has been completed. +By default, all forms marked with `phx-change` and having `id` +attribute will recover input values automatically after the user has +reconnected or the LiveView has remounted after a crash. This is +achieved by the client triggering the same `phx-change` to the server +as soon as the mount has been completed. **Note:** if you want to see form recovery working in development, please make sure to disable live reloading in development by commenting out the @@ -206,7 +264,7 @@ to trigger for recovery, which will receive the form params as usual. For exampl imagine a LiveView wizard form where the form is stateful and built based on what step the user is on and by prior selections: -
+ On the server, the `"validate_wizard_step"` event is only concerned with the current client form data, but the server maintains the entire state of the wizard. @@ -225,6 +283,29 @@ above, which would wire up to the following server callbacks in your LiveView: To forgo automatic form recovery, set `phx-auto-recover="ignore"`. +## Resetting Forms + +To reset a LiveView form, you can use the standard `type="reset"` on a +form button or input. When clicked, the form inputs will be reset to their +original values, and Phoenix will hide errors for `phx-fedback-for` elements. +After the form is reset, a `phx-change` event is emitted with the `_target` param +containing the reset `name`. For example, the following element: + + + ... + +
+ +Can be handled on the server differently from your regular change function: + + def handle_event("changed", %{"_target" => ["reset"]} = params, socket) do + # handle form reset + end + + def handle_event("changed", params, socket) do + # handle regular form change + end + ## JavaScript client specifics The JavaScript client is always the source of truth for current input values. @@ -236,13 +317,15 @@ errors, or additive UX around the user's input values as they fill out a form. For these use cases, the `phx-change` input does not concern itself with disabling input editing while an event to the server is in flight. When a `phx-change` event is sent to the server, the input tag and parent form tag receive the -`phx-change-loading` css class, then the payload is pushed to the server with a +`phx-change-loading` CSS class, then the payload is pushed to the server with a `"_target"` param in the root payload containing the keyspace of the input name which triggered the change event. For example, if the following input triggered a change event: - +```heex + +``` The server's `handle_event/3` would receive a payload: @@ -264,12 +347,14 @@ On completion of server processing of the `phx-submit` event: 2. The last input with focus is restored (unless another input has received focus) 3. Updates are patched to the DOM as usual -To handle latent events, any HTML tag can be annotated with +To handle latent events, the ` +```heex + +``` You may also take advantage of LiveView's CSS loading state classes to swap out your form content while the form is submitting. For example, @@ -278,20 +363,47 @@ with the following rules in your `app.css`: .while-submitting { display: none; } .inputs { display: block; } - .phx-submit-loading { - .while-submitting { display: block; } - .inputs { display: none; } - } + .phx-submit-loading .while-submitting { display: block; } + .phx-submit-loading .inputs { display: none; } You can show and hide content with the following markup: -
-
Please wait while we save our content...
-
- -
-
+```heex +
+
Please wait while we save our content...
+
+ +
+
+``` Additionally, we strongly recommend including a unique HTML "id" attribute on the form. When DOM siblings change, elements without an ID will be replaced rather than moved, which can cause issues such as form fields losing focus. + +## Triggering `phx-` form events with JavaScript + +Often it is desirable to trigger an event on a DOM element without explicit +user interaction on the element. For example, a custom form element such as a +date picker or custom select input which utilizes a hidden input element to +store the selected state. + +In these cases, the event functions on the DOM API can be used, for example +to trigger a `phx-change` event: + +``` +document.getElementById("my-select").dispatchEvent( + new Event("input", {bubbles: true}) +) +``` + +When using a client hook, `this.el` can be used to determine the element as +outlined in the "Client hooks" documentation. + +It is also possible to trigger a `phx-submit` using a "submit" event: + +``` +document.getElementById("my-form").dispatchEvent( + new Event("submit", {bubbles: true, cancelable: true}) +) +``` diff --git a/guides/client/js-interop.md b/guides/client/js-interop.md index 700e23ab19..e90f77eb34 100644 --- a/guides/client/js-interop.md +++ b/guides/client/js-interop.md @@ -1,14 +1,15 @@ # JavaScript interoperability -As seen earlier, you start by instantiating a single LiveSocket to enable LiveView -client/server interaction, for example: +To enable LiveView client/server interaction, we instantiate a LiveSocket. For example: - import {Socket} from "phoenix" - import {LiveSocket} from "phoenix_live_view" +``` +import {Socket} from "phoenix" +import {LiveSocket} from "phoenix_live_view" - let csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content") - let liveSocket = new LiveSocket("/live", Socket, {params: {_csrf_token: csrfToken}}) - liveSocket.connect() +let csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content") +let liveSocket = new LiveSocket("/live", Socket, {params: {_csrf_token: csrfToken}}) +liveSocket.connect() +``` All options are passed directly to the `Phoenix.Socket` constructor, except for the following LiveView specific options: @@ -16,11 +17,11 @@ except for the following LiveView specific options: * `bindingPrefix` - the prefix to use for phoenix bindings. Defaults `"phx-"` * `params` - the `connect_params` to pass to the view's mount callback. May be a literal object or closure returning an object. When a closure is provided, - the function receives the view's phx-view name. - * `hooks` – a reference to a user-defined hooks namespace, containing client - callbacks for server/client interop. See the [Client hooks](#client-hooks) + the function receives the view's element. + * `hooks` – a reference to a user-defined hooks namespace, containing client + callbacks for server/client interop. See the [Client hooks](#client-hooks-via-phx-hook) section below for details. - * `uploaders` – a reference to a user-defined uploaders namespace, containing + * `uploaders` – a reference to a user-defined uploaders namespace, containing client callbacks for client-side direct-to-cloud uploads. See the [External Uploads guide](uploads-external.md) for details. @@ -32,13 +33,15 @@ Calling `enableDebug()` turns on debug logging which includes LiveView life-cycl payload events as they come and go from client to server. In practice, you can expose your instance on `window` for quick access in the browser's web console, for example: - // app.js - let liveSocket = new LiveSocket(...) - liveSocket.connect() - window.liveSocket = liveSocket +``` +// app.js +let liveSocket = new LiveSocket(...) +liveSocket.connect() +window.liveSocket = liveSocket - // in the browser's web console - >> liveSocket.enableDebug() +// in the browser's web console +>> liveSocket.enableDebug() +``` The debug state uses the browser's built-in `sessionStorage`, so it will remain in effect for as long as your browser session lasts. @@ -54,58 +57,38 @@ the `LiveSocket` instance includes `enableLatencySim(milliseconds)` and `disable functions which apply throughout the current browser session. The `enableLatencySim` function accepts an integer in milliseconds for the round-trip-time to the server. For example: - // app.js - let liveSocket = new LiveSocket(...) - liveSocket.connect() - window.liveSocket = liveSocket - - // in the browser's web console - >> liveSocket.enableLatencySim(1000) - [Log] latency simulator enabled for the duration of this browser session. - Call disableLatencySim() to disable - -## Loading state and errors - -By default, the following classes are applied to the LiveView's parent -container: - - - `"phx-connected"` - applied when the view has connected to the server - - `"phx-disconnected"` - applied when the view is not connected to the server - - `"phx-error"` - applied when an error occurs on the server. Note, this - class will be applied in conjunction with `"phx-disconnected"` if connection - to the server is lost. - -All `phx-` event bindings apply their own css classes when pushed. For example -the following markup: - - +``` +// app.js +let liveSocket = new LiveSocket(...) +liveSocket.connect() +window.liveSocket = liveSocket + +// in the browser's web console +>> liveSocket.enableLatencySim(1000) +[Log] latency simulator enabled for the duration of this browser session. + Call disableLatencySim() to disable +``` -On click, would receive the `phx-click-loading` class, and on keydown would receive -the `phx-keydown-loading` class. The css loading classes are maintained until an -acknowledgement is received on the client for the pushed event. +## Event listeners -In the case of forms, when a `phx-change` is sent to the server, the input element -which emitted the change receives the `phx-change-loading` class, along with the -parent form tag. The following events receive css loading classes: +LiveView emits several events to the browsers and allows developers to submit +their own events too. - - `phx-click` - `phx-click-loading` - - `phx-change` - `phx-change-loading` - - `phx-submit` - `phx-submit-loading` - - `phx-focus` - `phx-focus-loading` - - `phx-blur` - `phx-blur-loading` - - `phx-window-keydown` - `phx-keydown-loading` - - `phx-window-keyup` - `phx-keyup-loading` +### Live navigation events -For live page navigation via `live_redirect` and `live_patch`, as well as form +For live page navigation via `<.link navigate={...}>` and `<.link patch={...}>`, +their server-side equivalents `push_redirect` and `push_patch`, as well as form submits via `phx-submit`, the JavaScript events `"phx:page-loading-start"` and `"phx:page-loading-stop"` are dispatched on window. Additionally, any `phx-` event may dispatch page loading events by annotating the DOM element with `phx-page-loading`. This is useful for showing main page loading status, for example: - // app.js - import topbar from "topbar" - window.addEventListener("phx:page-loading-start", info => topbar.show()) - window.addEventListener("phx:page-loading-stop", info => topbar.hide()) +``` +// app.js +import topbar from "topbar" +window.addEventListener("phx:page-loading-start", info => topbar.show()) +window.addEventListener("phx:page-loading-stop", info => topbar.hide()) +``` Within the callback, `info.detail` will be an object that contains a `kind` key, with a value that depends on the triggering event: @@ -122,38 +105,70 @@ In the case of an `"element"` page loading event, the info will contain a `"target"` key containing the DOM element which triggered the page loading state. -## Triggering phx form events with JavaScript +### Handling server-pushed events -Often it is desirable to trigger an event on a DOM element without explicit -user interaction on the element. For example, a custom form element such as a -date picker or custom select input which utilizes a hidden input element to -store the selected state. +When the server uses `Phoenix.LiveView.push_event/3`, the event name +will be dispatched in the browser with the `phx:` prefix. For example, +imagine the following template where you want to highlight an existing +element from the server to draw the user's attention: + +```heex +
+ <%= item.title %> +
+``` -In these cases, the event functions on the DOM API can be used, for example -to trigger a `phx-change` event: +Next, the server can issue a highlight using the standard `push_event`: -```javascript -document.getElementById("my-select").dispatchEvent( - new Event("input", {bubbles: true}) -) +```elixir +def handle_info({:item_updated, item}, socket) do + {:noreply, push_event(socket, "highlight", %{id: "item-#{item.id}"})} +end ``` -When using a client hook, `this.el` can be used to determine the element as -outlined in the "Client hooks" documentation. +Finally, a window event listener can listen for the event and conditionally +execute the highlight command if the element matches: -It is also possible to trigger a `phx-submit` using a "submit" event: +``` +let liveSocket = new LiveSocket(...) +window.addEventListener(`phx:highlight`, (e) => { + let el = document.getElementById(e.detail.id) + if(el) { + // logic for highlighting + } +}) +``` + +If you desire, you can also integrate this functionality with Phoenix' +JS commands, executing JS commands for the given element whenever highlight +is triggered. First, update the element to embed the JS command into a data +attribute: + +```heex +
+ <%= item.title %> +
+``` + +Now, in the event listener, use `LiveSocket.execJS` to trigger all JS +commands in the new attribute: -```javascript -document.getElementById("my-form").dispatchEvent( - new Event("submit", {bubbles: true}) -) +``` +let liveSocket = new LiveSocket(...) +window.addEventListener(`phx:highlight`, (e) => { + document.querySelectorAll(`[data-highlight]`).forEach(el => { + if(el.id == e.detail.id){ + liveSocket.execJS(el, el.getAttribute("data-highlight")) + } + }) +}) ``` -## Client hooks +## Client hooks via `phx-hook` To handle custom client-side JavaScript when an element is added, updated, -or removed by the server, a hook object may be provided with the following -life-cycle callbacks: +or removed by the server, a hook object may be provided via `phx-hook`. +`phx-hook` must point to an object with the following life-cycle callbacks: * `mounted` - the element has been added to the DOM and its server LiveView has finished mounting @@ -166,14 +181,19 @@ life-cycle callbacks: * `disconnected` - the element's parent LiveView has disconnected from the server * `reconnected` - the element's parent LiveView has reconnected to the server +*Note:* When using hooks outside the context of a LiveView, `mounted` is the only +callback invoked, and only those elements on the page at DOM ready will be tracked. +For dynamic tracking of the DOM as elements are added, removed, and updated, a LiveView +should be used. + The above life-cycle callbacks have in-scope access to the following attributes: - * `el` - attribute referencing the bound DOM node, - * `viewName` - attribute matching the DOM node's phx-view value + * `el` - attribute referencing the bound DOM node + * `liveSocket` - the reference to the underlying `LiveSocket` instance * `pushEvent(event, payload, (reply, ref) => ...)` - method to push an event from the client to the LiveView server * `pushEventTo(selectorOrTarget, event, payload, (reply, ref) => ...)` - method to push targeted events from the client to LiveViews and LiveComponents. It sends the event to the LiveComponent or LiveView the `selectorOrTarget` is - defined in, where it's value can be either a query selector or an actual DOM element. If the query selector returns + defined in, where its value can be either a query selector or an actual DOM element. If the query selector returns more than one element it will send the event to all of them, even if all the elements are in the same LiveComponent or LiveView. * `handleEvent(event, (payload) => ...)` - method to handle an event pushed from the server @@ -181,7 +201,7 @@ The above life-cycle callbacks have in-scope access to the following attributes: * `uploadTo(selectorOrTarget, name, files)` - method to inject a list of file-like objects into an uploader. The hook will send the files to the uploader with `name` defined by [`allow_upload/3`](`Phoenix.LiveView.allow_upload/3`) on the server-side. Dispatching new uploads triggers an input change event which will be sent to the - LiveComponent or LiveView the `selectorOrTarget` is defined in, where it's value can be either a query selector or an + LiveComponent or LiveView the `selectorOrTarget` is defined in, where its value can be either a query selector or an actual DOM element. If the query selector returns more than one live file input, an error will be logged. For example, the markup for a controlled input for phone-number formatting could be written @@ -214,7 +234,9 @@ DOM management, the `LiveSocket` constructor accepts a `dom` option with an function just before the DOM patch operations occurs in LiveView. This allows external libraries to (re)initialize DOM elements or copy attributes as necessary as LiveView performs its own patch operations. The update operation cannot be cancelled or deferred, -and the return value is ignored. For example, the following option could be used to add +and the return value is ignored. + +For example, the following option could be used to add [Alpine.js](https://github.com/alpinejs/alpine) support to your project: let liveSocket = new LiveSocket("/live", Socket, { @@ -226,6 +248,17 @@ and the return value is ignored. For example, the following option could be used }, }) +You could also use the same approach to guarantee that some attributes set on the client-side are kept intact. +In the following example, all attributes starting with `data-js-` won't be replaced when the DOM is patched by LiveView: + + onBeforeElUpdated(from, to){ + for (const attr of from.attributes){ + if (attr.name.startsWith("data-js-")){ + to.setAttribute(attr.name, attr.value); + } + } + } + ### Client-server communication A hook can push events to the LiveView by using the `pushEvent` function and receive a @@ -237,7 +270,7 @@ hook element or by using `Phoenix.LiveView.push_event/3` on the server and `hand For example, to implement infinite scrolling, one can pass the current page using data attributes: -
+
And then in the client: @@ -268,7 +301,7 @@ And then on the client: } } -*Note*: events pushed from the server via `push_event` are global and will be dispatched +*Note*: remember events pushed from the server via `push_event` are global and will be dispatched to all active hooks on the client who are handling that event. *Note*: In case a LiveView pushes events and renders content, `handleEvent` callbacks are invoked after the page is updated. Therefore, if the LiveView redirects at the same time it pushes events, callbacks won't be invoked on the old page's elements. Callbacks would be invoked on the redirected page's newly mounted hook elements. diff --git a/guides/client/uploads-external.md b/guides/client/uploads-external.md index 8373783fd2..b74b554228 100644 --- a/guides/client/uploads-external.md +++ b/guides/client/uploads-external.md @@ -106,6 +106,26 @@ In order to enforce all of your file constraints when uploading to S3, it is necessary to perform a multipart form POST with your file data. +This guide assumes an existing S3 bucket with the correct CORS configuration +which allows uploading directly to the bucket. + +An example CORS config is: + +```js +[ + { + "AllowedHeaders": [ "*" ], + "AllowedMethods": [ "PUT", "POST" ], + "AllowedOrigins": [ your_domain_or_*_here ], + "ExposeHeaders": [] + } +] +``` + +More information on configuring CORS for S3 buckets is available at: + +https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html + > The following example uses a zero-dependency module > called [`SimpleS3Upload`](https://gist.github.com/chrismccord/37862f1f8b1f5148644b75d20d1cb073) > written by Chris McCord to generate pre-signed URLs for S3. @@ -133,7 +153,7 @@ defp presign_upload(entry, socket) do SimpleS3Upload.sign_form_upload(config, bucket, key: key, content_type: entry.client_type, - max_file_size: uploads.avatar.max_file_size, + max_file_size: uploads[entry.upload_config].max_file_size, expires_in: :timer.hours(1) ) diff --git a/guides/introduction/installation.md b/guides/introduction/installation.md index 50addf961d..85433bf105 100644 --- a/guides/introduction/installation.md +++ b/guides/introduction/installation.md @@ -1,8 +1,18 @@ # Installation -**Note:** Phoenix v1.5 comes with built-in support for LiveView apps. Just create -your application with `mix phx.new my_app --live`. If you are using earlier Phoenix -versions or your app already exists, keep on reading. +## New projects + +Phoenix v1.5+ comes with built-in support for LiveView apps. Just create +your application with `mix phx.new my_app --live`. The `--live` flag has +become the default on Phoenix v1.6. + +Once you've created a LiveView project, refer to [LiveView documentation](`Phoenix.LiveView`) +for further information on how to use it. + +## Existing projects + +If you are using a Phoenix version earlier than v1.5 or your app already exists, continue +with the following steps. The instructions below will serve if you are installing the latest stable version from Hex. To start using LiveView, add one of the following dependencies to your `mix.exs` @@ -13,7 +23,7 @@ If installing from Hex, use the latest version from there: ```elixir def deps do [ - {:phoenix_live_view, "~> 0.16.3"}, + {:phoenix_live_view, "~> 0.18"}, {:floki, ">= 0.30.0", only: :test} ] end @@ -46,26 +56,40 @@ Next, add the following imports to your web file in `lib/my_app_web.ex`: def view do quote do - ... - import Phoenix.LiveView.Helpers + # ... + import Phoenix.Component end end def router do quote do - ... + # ... import Phoenix.LiveView.Router end end ``` +In that same file, update your live_view layout configuration: + +```diff +# lib/my_app_web.ex + +def live_view do + use Phoenix.LiveView, +- layout: {MyAppWeb.LayoutView, "live.html"} ++ layout: {MyAppWeb.LayoutView, :live} + + unquote(view_helpers()) +end +``` + Then add the `Phoenix.LiveView.Router.fetch_live_flash/2` plug to your browser pipeline, in place of `:fetch_flash`: ```diff # lib/my_app_web/router.ex pipeline :browser do - ... + # ... plug :fetch_session - plug :fetch_flash + plug :fetch_live_flash @@ -118,14 +142,14 @@ Where `@session_options` are the options given to `plug Plug.Session` by using a Finally, ensure you have placed a CSRF meta tag inside the `` tag in your layout (`lib/my_app_web/templates/layout/app.html.*`) before `app.js` is included, like so: -```html -<%= csrf_meta_tag() %> +```heex + ``` and enable connecting to a LiveView socket in your `app.js` file. -```javascript +```js // assets/js/app.js import {Socket} from "phoenix" import {LiveSocket} from "phoenix_live_view" @@ -173,7 +197,7 @@ However, if you're adding `phoenix_live_view` to an umbrella project, the depend } ``` -Now run the next commands from your web app root: +Now run the next commands from the root of your web app project: ```bash npm install --prefix assets @@ -191,22 +215,23 @@ npm install --force phoenix_live_view --prefix assets LiveView does not use the default app layout. Instead, you typically call `put_root_layout` in your router to specify a layout that is used by both "regular" views and live views. In your router, do: ```elixir +# lib/my_app_web/router.ex + pipeline :browser do - ... + # ... plug :put_root_layout, {MyAppWeb.LayoutView, :root} - ... + # ... end ``` -The layout given to `put_root_layout` must use `<%= @inner_content %>` instead of `<%= render(@view_module, @view_template, assigns) %>`. It is typically very barebones, with mostly -`` and `` tags. For example: +The layout given to `put_root_layout` is typically very barebones, with mostly `` and `` tags. For example: -```elixir +```heex - <%= csrf_meta_tag() %> - <%= live_title_tag assigns[:page_title] || "MyApp" %> + + <%= assigns[:page_title] || "MyApp" %> "/> @@ -216,7 +241,7 @@ The layout given to `put_root_layout` must use `<%= @inner_content %>` instead o ``` -Once you have specified a root layout, "app.html.heex" will be rendered within your root layout for all non-LiveViews. You may also optionally define a "live.html.heex" layout to be used across all LiveViews, as we will describe in the next section. +Once you have specified a root layout, `app.html.heex` will be rendered within your root layout for all non-LiveViews. You may also optionally define a `live.html.heex` layout to be used across all LiveViews, as we will describe in the next section. Optionally, you can add a [`phx-track-static`](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html#static_changed?/1) to all `script` and `link` elements in your layout that use `src` and `href`. This way you can detect when new assets have been deployed by calling `static_changed?`. @@ -225,72 +250,6 @@ Optionally, you can add a [`phx-track-static`](https://hexdocs.pm/phoenix_live_v ``` -## phx.gen.live support - -While the above instructions are enough to install LiveView in a Phoenix app, if you want to use the `phx.gen.live` generators that come as part of Phoenix v1.5, you need to do one more change, as those generators assume your application was created with `mix phx.new --live`. - -The change is to define the `live_view` and `live_component` functions in your `my_app_web.ex` file, while refactoring the `view` function. At the end, they will look like this: - -```elixir - def view do - quote do - use Phoenix.View, - root: "lib/<%= lib_web_name %>/templates", - namespace: <%= web_namespace %> - - # Import convenience functions from controllers - import Phoenix.Controller, - only: [get_flash: 1, get_flash: 2, view_module: 1, view_template: 1] - - # Include shared imports and aliases for views - unquote(view_helpers()) - end - end - - def live_view do - quote do - use Phoenix.LiveView, - layout: {<%= web_namespace %>.LayoutView, "live.html"} - - unquote(view_helpers()) - end - end - - def live_component do - quote do - use Phoenix.LiveComponent - - unquote(view_helpers()) - end - end - - defp view_helpers do - quote do - # Use all HTML functionality (forms, tags, etc) - use Phoenix.HTML - - # Import LiveView helpers (live_render, live_component, live_patch, etc) - import Phoenix.LiveView.Helpers - - # Import basic rendering functionality (render, render_layout, etc) - import Phoenix.View - - import MyAppWeb.ErrorHelpers - import MyAppWeb.Gettext - alias MyAppWeb.Router.Helpers, as: Routes - end - end -``` - -Note that LiveViews are automatically configured to use a "live.html.heex" layout in this line: - -```elixir -use Phoenix.LiveView, - layout: {<%= web_namespace %>.LayoutView, "live.html"} -``` - -"layouts/root.html.heex" is shared by regular and live views, "app.html.heex" is rendered inside the root layout for regular views, and "live.html.heex" is rendered inside the root layout for LiveViews. "live.html.heex" typically starts out as a copy of "app.html.heex", but using the `@socket` assign instead of `@conn`. Check the [Live Layouts](live-layouts.md) guide for more information. - ## Progress animation If you want to show a progress bar as users perform live actions, we recommend using [`topbar`](https://github.com/buunguyen/topbar). @@ -304,14 +263,34 @@ $ npm install --prefix assets --save topbar Then customize LiveView to use it in your `assets/js/app.js`, right before the `liveSocket.connect()` call: ```js -import topbar from "topbar" - // Show progress bar on live navigation and form submits +import topbar from "topbar" topbar.config({barColors: {0: "#29d"}, shadowColor: "rgba(0, 0, 0, .3)"}) window.addEventListener("phx:page-loading-start", info => topbar.show()) window.addEventListener("phx:page-loading-stop", info => topbar.hide()) ``` +Alternatively, you can also delay showing the `topbar` and wait if the results do not appear within 200ms: + +```js +// Show progress bar on live navigation and form submits +import topbar from "topbar" +topbar.config({barColors: {0: "#29d"}, shadowColor: "rgba(0, 0, 0, .3)"}) +let topBarScheduled = undefined + +window.addEventListener("phx:page-loading-start", () => { + if(!topBarScheduled) { + topBarScheduled = setTimeout(() => topbar.show(), 200) + } +}) + +window.addEventListener("phx:page-loading-stop", () => { + clearTimeout(topBarScheduled) + topBarScheduled = undefined + topbar.hide() +}) +``` + ## Location for LiveView modules By convention your LiveView modules and `heex` templates should be placed in `lib/my_app_web/live/` directory. diff --git a/guides/server/assigns-eex.md b/guides/server/assigns-eex.md index 502f618d77..60623219d1 100644 --- a/guides/server/assigns-eex.md +++ b/guides/server/assigns-eex.md @@ -1,21 +1,18 @@ # Assigns and HEEx templates -All of the data in a LiveView is stored in the socket as assigns. -The `Phoenix.LiveView.assign/2` and `Phoenix.LiveView.assign/3` +All of the data in a LiveView is stored in the socket as assigns, which +is a server side struct in `Phoenix.LiveView.Socket`. Socket state is +never shared with the client beyond what your template renders. + +The `Phoenix.Component.assign/2` and `Phoenix.Component.assign/3` functions help store those values. Those values can be accessed in the LiveView as `socket.assigns.name` but they are accessed inside LiveView templates as `@name`. -`Phoenix.LiveView`'s built-in templates are identified by the `.heex` -extension (HTML EEx) or `~H` sigil. You can learn more about them -by checking the docs for `Phoenix.LiveView.Helpers.sigil_H/2`. -They are an extension of regular `.eex` templates with additional -features such as: - - * validation of HTML - * friendly-syntax for defining HTML components - * minimize the amount of data sent over the wire by splitting static and dynamic parts - * provide change tracking to avoid recomputing parts of the template that did not change +Phoenix template language is called HEEx (HTML+EEx). Those templates +are either files with the `.heex` extension or they are created +directly in source files via the `~H` sigil. You can learn more about +the HEEx syntax by checking the docs for [the `~H` sigil](`Phoenix.Component.sigil_H/2`). In this section, we are going to cover how LiveView minimizes the payload over the wire by understanding the interplay between @@ -27,7 +24,9 @@ When you first render a `.heex` template, it will send all of the static and dynamic parts of the template to the client. Imagine the following template: -

<%= expand_title(@title) %>

+```heex +

<%= expand_title(@title) %>

+``` It has two static parts, `

` and `

` and one dynamic part made of `expand_title(@title)`. Further rendering of this template @@ -42,9 +41,12 @@ nothing is sent. Change tracking also works when accessing map/struct fields. Take this template: -
- <%= @user.name %> -
+ +```heex +
+ <%= @user.name %> +
+``` If the `@user.name` changes but `@user.id` doesn't, then LiveView will re-render only `@user.name` and it will not execute or resend `@user.id` @@ -53,19 +55,26 @@ at all. The change tracking also works when rendering other templates as long as they are also `.heex` templates: - <%= render "child_template.html", assigns %> + +```heex +<%= render "child_template.html", assigns %> +``` Or when using function components: - <.show_name name={@user.name} /> +```heex +<.show_name name={@user.name} /> +``` The assign tracking feature also implies that you MUST avoid performing direct operations in the template. For example, if you perform a database query in your template: - <%= for user <- Repo.all(User) do %> - <%= user.name %> - <% end %> +```heex +<%= for user <- Repo.all(User) do %> + <%= user.name %> +<% end %> +``` Then Phoenix will never re-render the section above, even if the number of users in the database changes. Instead, you need to store the users as @@ -88,20 +97,24 @@ If the do/end block is given to a library function or user function, such as `content_tag`, change tracking won't work. For example, imagine the following template that renders a `div`: - <%= content_tag :div, id: "user_#{@id}" do %> - <%= @name %> - <%= @description %> - <% end %> +```heex +<%= content_tag :div, id: "user_#{@id}" do %> + <%= @name %> + <%= @description %> +<% end %> +``` LiveView knows nothing about `content_tag`, which means the whole `div` will be sent whenever any of the assigns change. Luckily, HEEx templates provide a nice syntax for building tags, so there is rarely a need to use `content_tag` inside `.heex` templates: -
- <%= @name %> - <%= @description %> -
+```heex +
+ <%= @name %> + <%= @description %> +
+``` The next pitfall is related to variables. Due to the scope of variables, LiveView has to disable change tracking whenever variables are used in the @@ -109,12 +122,16 @@ template, with the exception of variables introduced by Elixir basic `case`, `for`, and other block constructs. Therefore, you **must avoid** code like this in your LiveView templates: - <% some_var = @x + @y %> - <%= some_var %> +```heex +<% some_var = @x + @y %> +<%= some_var %> +``` Instead, use a function: - <%= sum(@x, @y) %> +```heex +<%= sum(@x, @y) %> +``` Similarly, **do not** define variables at the top of your `render` function: @@ -136,9 +153,11 @@ access variables is always executed on every render. This also applies to the constructs. For example, accessing the `post` variable defined by the comprehension below works as expected: - <%= for post <- @posts do %> - ... - <% end %> +```heex +<%= for post <- @posts do %> + ... +<% end %> +``` To sum up: diff --git a/guides/server/deployments.md b/guides/server/deployments.md new file mode 100644 index 0000000000..4f39be9323 --- /dev/null +++ b/guides/server/deployments.md @@ -0,0 +1,17 @@ +# Deployments + +One of the questions that arise from LiveView stateful model is what considerations are necessary when deploying a new version of LiveView. + +First off, whenever LiveView disconnects, it will automatically attempt to reconnect to the server using exponential back-off. This means it will try immediately, then wait 2s and try again, then 5s and so on. If you are deploying, this typically means the next reconnection will immediately succeed and your load balancer will automatically redirect to the new servers. + +However, your LiveView _may_ still have state that will be lost in this transition. How to deal with it? The good news is that there are a series of practices you can follow that will not only help with deployments but it will improve your application in general. + +1. Keep state in the query parameters when appropriate. For example, if your application has tabs and the user clicked a tab, instead of using `phx-click` and `c:handle_event/3` to manage it, you should implement it using `<.link patch={...}>` passing the tab name as parameter. You will then receive the new tab name `c:handle_params/3` which will set the relevant assign to choose which tab to display. You can even define specific URLs for each tab in your application router. By doing this, you will reduce the amount of server state, make tab navigation sharable via links, improving search engine indexing, and more. + +2. Consider storing other relevant state in the database. For example, if you are building a chat app and you want to store which messages have been read, you can store so in the database. Once the page is loaded, you retrieve the index of the last read message. This makes the application more robust, allow data to be synchronized across devices, etc. + +3. If your application uses forms (which is most likely true), keep in mind that Phoenix perform automatic form recovery: in case of disconnections, Phoenix will collect the form data and resubmit it on reconnection. This mechanism works out of the box for most forms but you may want to customize it or test it for your most complex forms. See the relevant section [in the "Form bindings" document](guides/client/form-bindings.md) to learn more. + +The idea is that: if you follow the practices above, most of your state is already handled within your app and therefore deployments should not bring additional concerns. Not only that, it will bring overall benefits to your app such as indexing, link sharing, device sharing, and so on. + +If you really have complex state that cannot be immediately handled, then you may need to resort to special strategies. This may be persisting "old" state to Redis/S3/Database and loading the new state on the new connections. Or you may take special care when migrating connections (for example, if you are building a game, you may want to wait for on-going sessions to finish before turning down the old server while routing new sessions to the new ones). Such cases will depend on your requirements (and they would likely exist regardless of which application stack you are using). diff --git a/guides/server/error-handling.md b/guides/server/error-handling.md index 157ea5d9a4..3b447308ec 100644 --- a/guides/server/error-handling.md +++ b/guides/server/error-handling.md @@ -66,7 +66,7 @@ check that the user has access to it like this: The code above builds a query that returns all organizations that belongs to the current user and then validates that the given "org_id" belongs to the user. If there is no such "org_id" or if the user has no access to it, an -`Ecto.NotFoundError` exception is raised. +`Ecto.NoResultsError` exception is raised. During a regular controller request, this exception will be converted to a 404 exception and rendered as a custom error page, as diff --git a/guides/server/live-layouts.md b/guides/server/live-layouts.md index b628e16962..ad74a31100 100644 --- a/guides/server/live-layouts.md +++ b/guides/server/live-layouts.md @@ -1,80 +1,38 @@ # Live layouts -*NOTE:* Make sure you've read the [Assigns and LiveEEx templates](assigns-eex.md) +*NOTE:* Make sure you've read the [Assigns and HEEx templates](assigns-eex.md) guide before moving forward. -When working with LiveViews, there are usually three layouts to be -considered: +From Phoenix v1.7, your application is made of two layouts: * the root layout - this is a layout used by both LiveView and regular views. This layout typically contains the `` definition alongside the head and body tags. Any content defined in the root layout will remain the same, even as you live navigate - across LiveViews. All LiveViews defined at the router must have - a root layout. The root layout is typically declared on the + across LiveViews. The root layout is typically declared on the router with `put_root_layout` and defined as "root.html.heex" - in your `MyAppWeb.LayoutView`. It may also be given via the - `:layout` option to the router's `live` macro. + in your layouts folder. It may also be given via the + `:root_layout` option to a `live_session` macro in the router. * the app layout - this is the default application layout which - is not included or used by LiveViews. It defaults to "app.html.heex" - in your `MyAppWeb.LayoutView`. + is rendered on both regular HTTP requests and LiveViews. + It defaults to "app.html.heex" - * the live layout - this is the layout which wraps a LiveView and - is rendered as part of the LiveView life-cycle. It must be opt-in - by passing the `:layout` option on `use Phoenix.LiveView`. It is - typically set to "live.html.heex"in your `MyAppWeb.LayoutView`. - -Overall, those layouts are found in `templates/layout` with the -following names: - - * root.html.heex - * app.html.heex - * live.html.heex - -> Note: if you are using earlier Phoenix versions, those layouts -> may use `.eex` and `.leex` extensions instead of `.heex`, but -> we have since then normalized on the latter. +Overall, those layouts are found in `components/layouts` and are +embedded within `MyAppWeb.Layouts`. All layouts must call `<%= @inner_content %>` to inject the content rendered by the layout. -The "root" layout is shared by both "app" and "live" layouts. -It is rendered only on the initial request and therefore it -has access to the `@conn` assign. The root layout must be defined -in your router: +The "root" layout is rendered only on the initial request and +therefore it has access to the `@conn` assign. The root layout +is typically defined in your router: plug :put_root_layout, {MyAppWeb.LayoutView, :root} -The "app" and "live" layouts are often small and similar to each -other, but the "app" layout uses the `@conn` and is used as part -of the regular request life-cycle. The "live" layout is part of -the LiveView and therefore has direct access to the `@socket`. - -For example, you can define a new `live.html.heex` layout with -dynamic content. You must use `@inner_content` where the output -of the actual template will be placed at: - -

<%= live_flash(@flash, :notice) %>

-

<%= live_flash(@flash, :error) %>

- <%= @inner_content %> - -To use the live layout, update your LiveView to pass the `:layout` -option to `use Phoenix.LiveView`: - - use Phoenix.LiveView, layout: {MyAppWeb.LayoutView, "live.html"} - -If you are using Phoenix v1.5, the layout is automatically set -when generating apps with the `mix phx.new --live` flag. - -The `:layout` option on `use` does not apply to LiveViews rendered -within other LiveViews. If you want to render child live views or -opt-in to a layout, use `:layout` as an option in mount: - - def mount(_params, _session, socket) do - socket = assign(socket, new_message_count: 0) - {:ok, socket, layout: {MyAppWeb.LayoutView, "live.html"}} - end +The "app.html.heex" layout is rendered with either `@conn` or +`@socket`. See the `def controller` and `def live_view` definitions +in your `MyAppWeb` to learn how it is included. *Note*: The live layout is always wrapped by the LiveView's `:container` tag. @@ -96,13 +54,19 @@ mount: Then access `@page_title` in the root layout: - <%= @page_title %> +```heex +<%= @page_title %> +``` -You can also use `Phoenix.LiveView.Helpers.live_title_tag/2` to support +You can also use the `Phoenix.Component.live_title/1` component to support adding automatic prefix and suffix to the page title when rendered and on subsequent updates: - <%= live_title_tag assigns[:page_title] || "Welcome", prefix: "MyApp – " %> +```heex + + <%= assigns[:page_title] || "Welcome" %> + +``` Although the root layout is not updated by LiveView, by simply assigning to `page_title`, LiveView knows you want the title to be updated: diff --git a/guides/server/live-navigation.md b/guides/server/live-navigation.md index 50d9d807f1..ca7fbb272a 100644 --- a/guides/server/live-navigation.md +++ b/guides/server/live-navigation.md @@ -6,20 +6,28 @@ With live navigation, the page is updated without a full page reload. You can trigger live navigation in two ways: - * From the client - this is done by replacing `Phoenix.HTML.Link.link/2` - by `Phoenix.LiveView.Helpers.live_patch/2` or - `Phoenix.LiveView.Helpers.live_redirect/2` + * From the client - this is done by passing either `patch={url}` or `navigate={url}` + to the `Phoenix.Component.link/1` component - * From the server - this is done by replacing `Phoenix.Controller.redirect/2` calls - by `Phoenix.LiveView.push_patch/2` or `Phoenix.LiveView.push_redirect/2`. + * From the server - this is done by by `Phoenix.LiveView.push_patch/2` or `Phoenix.LiveView.push_navigate/2`. -For example, in a template you may write: +For example, instead of writing the following in a template: - <%= live_patch "next", to: Routes.live_path(@socket, MyLive, @page + 1) %> +```heex +<.link href={~p"/pages/#{@page + 1}"}>Next +``` -or in a LiveView: +You would write: - {:noreply, push_patch(socket, to: Routes.live_path(socket, MyLive, page + 1))} +```heex +<.link patch={~p"/pages/#{@page + 1}"}>Next +``` + +Or in a LiveView: + +```elixir +{:noreply, push_patch(socket, to: ~p"/pages/#{@page + 1}")} +``` The "patch" operations must be used when you want to navigate to the current LiveView, simply updating the URL and the current parameters, @@ -28,45 +36,34 @@ without mounting a new LiveView. When patch is used, the invoked and the minimal set of changes are sent to the client. See the next section for more information. -The "redirect" operations must be used when you want to dismount the -current LiveView and mount a new one. In those cases, an Ajax request -is made to fetch the necessary information about the new LiveView, -which is mounted in place of the current one within the current layout. -While redirecting, a `phx-disconnected` class is added to the LiveView, -which can be used to indicate to the user a new page is being loaded. - -At the end of the day, regardless if you invoke [`link/2`](`Phoenix.HTML.Link.link/2`), -[`live_patch/2`](`Phoenix.LiveView.Helpers.live_patch/2`), -and [`live_redirect/2`](`Phoenix.LiveView.Helpers.live_redirect/2`) from the client, -or [`redirect/2`](`Phoenix.Controller.redirect/2`), -[`push_patch/2`](`Phoenix.LiveView.push_patch/2`), -and [`push_redirect/2`](`Phoenix.LiveView.push_redirect/2`) from the server, -the user will end-up on the same page. The difference between those is mostly -the amount of data sent over the wire: - - * [`link/2`](`Phoenix.HTML.Link.link/2`) and - [`redirect/2`](`Phoenix.Controller.redirect/2`) do full page reloads - - * [`live_redirect/2`](`Phoenix.LiveView.Helpers.live_redirect/2`) and - [`push_redirect/2`](`Phoenix.LiveView.push_redirect/2`) mounts a new LiveView while - keeping the current layout - - * [`live_patch/2`](`Phoenix.LiveView.Helpers.live_patch/2`) and - [`push_patch/2`](`Phoenix.LiveView.push_patch/2`) updates the current LiveView - and sends only the minimal diff while also maintaining the scroll position - -An easy rule of thumb is to stick with -[`live_redirect/2`](`Phoenix.LiveView.Helpers.live_redirect/2`) and -[`push_redirect/2`](`Phoenix.LiveView.push_redirect/2`) and use the patch -helpers only in the cases where you want to minimize the -amount of data sent when navigating within the same LiveView (for example, -if you want to change the sorting of a table while also updating the URL). +The "navigate" operations must be used when you want to dismount the +current LiveView and mount a new one. You can only "navigate" between +LiveViews in the same session. While redirecting, a `phx-loading` class +is added to the LiveView, which can be used to indicate to the user a +new page is being loaded. + +If you attempt to patch to another LiveView or navigate across live sessions, +a full page reload is triggered. This means your application continues to work, +in case your application structure changes and that's not reflected in the navigation. + +Here is a quick breakdown: + + * `<.link href={...}>` and [`redirect/2`](`Phoenix.Controller.redirect/2`) + are HTTP-based, work everywhere, and perform full page reloads + + * `<.link navigate={...}>` and [`push_navigate/2`](`Phoenix.LiveView.push_navigate/2`) + work across LiveViews in the same session. They mount a new LiveView + while keeping the current layout + + * `<.link patch={...}>` and [`push_patch/2`](`Phoenix.LiveView.push_patch/2`) + updates the current LiveView and sends only the minimal diff while also + maintaining the scroll position ## `handle_params/3` The [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) callback is invoked after [`mount/3`](`c:Phoenix.LiveView.mount/3`) and before the initial render. -It is also invoked every time [`live_patch/2`](`Phoenix.LiveView.Helpers.live_patch/2`) +It is also invoked every time `<.link patch={...}>` or [`push_patch/2`](`Phoenix.LiveView.push_patch/2`) are used. It receives the request parameters as first argument, the url as second, and the socket as third. @@ -78,7 +75,9 @@ the system and you define it in the router as: Now to add live sorting, you could do: - <%= live_patch "Sort by name", to: Routes.live_path(@socket, UserTable, %{sort_by: "name"}) %> +```heex +<.link patch={path(~p"/users", sort_by: "name")}>Sort by name +``` When clicked, since we are navigating to the current LiveView, [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) will be invoked. @@ -88,15 +87,18 @@ validate the user input and change the state accordingly: def handle_params(params, _uri, socket) do socket = case params["sort_by"] do - sort_by when sort_by in ~w(name company) -> assign(socket, sort_by: sort) + sort_by when sort_by in ~w(name company) -> assign(socket, sort_by: sort_by) _ -> socket end {:noreply, load_users(socket)} end -As with other `handle_*` callbacks, changes to the state inside -[`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) will trigger a server render. +Note we returned `{:noreply, socket}`, where `:noreply` means no +additional information is sent to the client. As with other `handle_*` +callbacks, changes to the state inside +[`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) will trigger +a new server render. Note the parameters given to [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) are the same as the ones given to [`mount/3`](`c:Phoenix.LiveView.mount/3`). @@ -104,55 +106,27 @@ So how do you decide which callback to use to load data? Generally speaking, data should always be loaded on [`mount/3`](`c:Phoenix.LiveView.mount/3`), since [`mount/3`](`c:Phoenix.LiveView.mount/3`) is invoked once per LiveView life-cycle. Only the params you expect to be changed via -[`live_patch/2`](`Phoenix.LiveView.Helpers.live_patch/2`) or +`<.link patch={...}>` or [`push_patch/2`](`Phoenix.LiveView.push_patch/2`) must be loaded on [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`). For example, imagine you have a blog. The URL for a single post is: "/blog/posts/:post_id". In the post page, you have comments and they are paginated. -You use [`live_patch/2`](`Phoenix.LiveView.Helpers.live_patch/2`) to update the shown +You use `<.link patch={...}>` to update the shown comments every time the user paginates, updating the URL to "/blog/posts/:post_id?page=X". In this example, you will access `"post_id"` on [`mount/3`](`c:Phoenix.LiveView.mount/3`) and the page of comments on [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`). -Furthermore, it is very important to not access the same parameters on both -[`mount/3`](`c:Phoenix.LiveView.mount/3`) and -[`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`). -For example, do NOT do this: - - def mount(%{"post_id" => post_id}, session, socket) do - # do something with post_id - end - - def handle_params(%{"post_id" => post_id, "page" => page}, url, socket) do - # do something with post_id and page - end - -If you do that, because [`mount/3`](`c:Phoenix.LiveView.mount/3`) is called once and -[`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) multiple times, the "post_id" -read on mount can get out of sync with the one in -[`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`). -So once a parameter is read on mount, it should not be read elsewhere. Instead, do this: - - def mount(%{"post_id" => post_id}, session, socket) do - # do something with post_id - end - - def handle_params(%{"sort_by" => sort_by}, url, socket) do - post_id = socket.assigns.post.id - # do something with sort_by - end - ## Replace page address LiveView also allows the current browser URL to be replaced. This is useful when you want certain events to change the URL but without polluting the browser's history. -This can be done by passing the `replace: true` option to any of the navigation helpers. +This can be done by passing the `<.link replace>` option to any of the navigation helpers. ## Multiple LiveViews in the same page LiveView allows you to have multiple LiveViews in the same page by calling -`Phoenix.LiveView.Helpers.live_render/3` in your templates. However, only +`Phoenix.Component.live_render/3` in your templates. However, only the LiveViews defined directly in your router can use the "Live Navigation" functionality described here. This is important because LiveViews work closely with your router, guaranteeing you can only navigate to known diff --git a/guides/server/security-model.md b/guides/server/security-model.md index e994bc03a2..b5ecb12f3f 100644 --- a/guides/server/security-model.md +++ b/guides/server/security-model.md @@ -2,7 +2,7 @@ LiveView begins its life-cycle as a regular HTTP request. Then a stateful connection is established. Both the HTTP request and the stateful connection -receives the client data via parameters and session. +receive the client data via parameters and session. This means that any session validation must happen both in the HTTP request (plug pipeline) and the stateful connection (LiveView mount). @@ -15,7 +15,7 @@ a user. Authorization is about telling if a user has access to a certain resource or feature in the system. In a regular web application, once a user is authenticated, for example by -entering his email and password, or by using a third-party service such as +entering their email and password, or by using a third-party service such as Google, Twitter, or Facebook, a token identifying the user is stored in the session, which is a cookie (a key-value pair) stored in the user's browser. @@ -37,8 +37,12 @@ sessions on the `mount` callback. Authorization rules generally happen on ## Mounting considerations -If you perform user authentication and confirmation on every HTTP request -via Plugs, such as this: +The [`mount/3`](`c:Phoenix.LiveView.mount/3`) callback is invoked both on +the initial HTTP mount and when LiveView is connected. Therefore, any +authentication performed during mount will cover all scenarios. + +If you perform user authentication and confirmation exclusively on HTTP +requests via Plugs, such as this: plug :ensure_user_authenticated plug :ensure_user_confirmed @@ -46,7 +50,7 @@ via Plugs, such as this: Then the [`mount/3`](`c:Phoenix.LiveView.mount/3`) callback of your LiveView should execute those same verifications: - def mount(params, %{"user_id" => user_id} = _session, socket) do + def mount(_params, %{"user_id" => user_id} = _session, socket) do socket = assign(socket, current_user: Accounts.get_user!(user_id)) socket = @@ -59,17 +63,20 @@ should execute those same verifications: {:ok, socket} end -LiveView v0.16 includes the `on_mount` (`Phoenix.LiveView.on_mount/1`) hook, +LiveView v0.17 includes the `on_mount` (`Phoenix.LiveView.on_mount/1`) hook, which allows you to encapsulate this logic and execute it on every mount, as you would with plug: defmodule MyAppWeb.UserLiveAuth do + import Phoenix.Component import Phoenix.LiveView + alias MyAppWeb.Accounts # from `mix phx.gen.auth` - def mount(params, %{"user_id" => user_id} = _session, socket) do - socket = assign_new(socket, :current_user, fn -> - Accounts.get_user!(user_id) - end) + def on_mount(:default, _params, %{"user_token" => user_token} = _session, socket) do + socket = + assign_new(socket, :current_user, fn -> + Accounts.get_user_by_session_token(user_token) + end) if socket.assigns.current_user.confirmed_at do {:cont, socket} @@ -79,18 +86,31 @@ as you would with plug: end end -and then use it on all relevant LiveViews: +We use [`assign_new/3`](`Phoenix.Component.assign_new/3`). This is a +convenience to avoid fetching the `current_user` multiple times across +LiveViews. + +Now we can use the hook whenever relevant: defmodule MyAppWeb.PageLive do - use Phoenix.LiveView + use MyAppWeb, :live_view on_mount MyAppWeb.UserLiveAuth ... end -Note in the snippet above we used [`assign_new/3`](`Phoenix.LiveView.assign_new/3`). -This is a convenience to avoid fetching the `current_user` multiple times across -LiveViews. +If you prefer, you can add the hook to `def live_view` under `MyAppWeb`, +to run it on all LiveViews by default: + + def live_view do + quote do + use Phoenix.LiveView, + layout: {MyAppWeb.LayoutView, :live} + + on_mount MyAppWeb.UserLiveAuth + unquote(html_helpers()) + end + end ## Events considerations @@ -108,7 +128,7 @@ described, one might implement this: on_mount MyAppWeb.UserLiveAuth - def mount(_params, session, socket) do + def mount(_params, _session, socket) do {:ok, load_projects(socket)} end @@ -255,7 +275,7 @@ a live session, then the `pipe_through` checks are not necessary. Declaring the `on_mount` on `live_session` is exactly the same as declaring it in each LiveView inside the `live_session`. It will be executed every time a LiveView is mounted, even after `live_redirect`s. -The important to keep in mind is: +The important concepts to keep in mind are: * If you have both LiveViews and regular web requests, then you must always authorize and authenticate your LiveViews (using diff --git a/guides/server/telemetry.md b/guides/server/telemetry.md index d5abb9d12a..73679aed3e 100644 --- a/guides/server/telemetry.md +++ b/guides/server/telemetry.md @@ -14,10 +14,10 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme %{ socket: Phoenix.LiveView.Socket.t, params: unsigned_params | :not_mounted_at_router, - session: map + session: map, + uri: String.t() | nil } - * `[:phoenix, :live_view, :mount, :stop]` - Dispatched by a `Phoenix.LiveView` when the [`mount/3`](`c:Phoenix.LiveView.mount/3`) callback completes successfully. @@ -30,10 +30,10 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme %{ socket: Phoenix.LiveView.Socket.t, params: unsigned_params | :not_mounted_at_router, - session: map + session: map, + uri: String.t() | nil } - * `[:phoenix, :live_view, :mount, :exception]` - Dispatched by a `Phoenix.LiveView` when an exception is raised in the [`mount/3`](`c:Phoenix.LiveView.mount/3`) callback. @@ -46,7 +46,8 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme kind: atom, reason: term, params: unsigned_params | :not_mounted_at_router, - session: map + session: map, + uri: String.t() | nil } * `[:phoenix, :live_view, :handle_params, :start]` - Dispatched by a `Phoenix.LiveView` @@ -64,7 +65,6 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme uri: String.t() } - * `[:phoenix, :live_view, :handle_params, :stop]` - Dispatched by a `Phoenix.LiveView` when the [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) callback completes successfully. @@ -81,7 +81,7 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme } * `[:phoenix, :live_view, :handle_params, :exception]` - Dispatched by a `Phoenix.LiveView` - when the when an exception is raised in the [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) callback. + when an exception is raised in the [`handle_params/3`](`c:Phoenix.LiveView.handle_params/3`) callback. * Measurement: @@ -112,7 +112,6 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme params: unsigned_params } - * `[:phoenix, :live_view, :handle_event, :stop]` - Dispatched by a `Phoenix.LiveView` when the [`handle_event/3`](`c:Phoenix.LiveView.handle_event/3`) callback completes successfully. @@ -144,7 +143,7 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme event: String.t(), params: unsigned_params } - + * `[:phoenix, :live_component, :handle_event, :start]` - Dispatched by a `Phoenix.LiveComponent` immediately before [`handle_event/3`](`c:Phoenix.LiveComponent.handle_event/3`) is invoked. @@ -161,7 +160,6 @@ LiveView currently exposes the following [`telemetry`](https://hexdocs.pm/teleme params: unsigned_params } - * `[:phoenix, :live_component, :handle_event, :stop]` - Dispatched by a `Phoenix.LiveComponent` when the [`handle_event/3`](`c:Phoenix.LiveComponent.handle_event/3`) callback completes successfully. diff --git a/guides/server/uploads.md b/guides/server/uploads.md index 4b416a0b88..8d416c8fbc 100644 --- a/guides/server/uploads.md +++ b/guides/server/uploads.md @@ -4,7 +4,7 @@ LiveView supports interactive file uploads with progress for both direct to server uploads as well as direct-to-cloud [external uploads](uploads-external.html) on the client. -### Built-in Features +## Built-in Features * Accept specification - Define accepted file types, max number of entries, max file size, etc. When the client @@ -17,7 +17,7 @@ both direct to server uploads as well as direct-to-cloud respond to progress, errors, cancellation, etc. * Drag and drop - Use the `phx-drop-target` attribute to - enable. See `Phoenix.LiveView.Helpers.live_file_input/2`. + enable. See `Phoenix.Component.live_file_input/1`. ## Allow uploads @@ -40,21 +40,21 @@ template. ## Render reactive elements -Use the `Phoenix.LiveView.Helpers.live_file_input/2` file -input generator to render a file input for the upload: +Use the `Phoenix.Component.live_file_input/1` component +to render a file input for the upload: -```elixir -# lib/my_app_web/live/upload_live.html.heex +```heex +<%!-- lib/my_app_web/live/upload_live.html.heex --%>
- <%= live_file_input @uploads.avatar %> + <.live_file_input upload={@uploads.avatar} />
``` > **Important:** You must bind `phx-submit` and `phx-change` on the form. -Note that while [`live_file_input/2`] +Note that while [`live_file_input/1`] allows you to set additional attributes on the file input, many attributes such as `id`, `accept`, and `multiple` will be set automatically based on the [`allow_upload/3`] spec. @@ -73,29 +73,28 @@ info, errors, etc. Let's look at an annotated example: -```elixir -# lib/my_app_web/live/upload_live.html.heex +```heex +<%!-- lib/my_app_web/live/upload_live.html.heex --%> -<%# use phx-drop-target with the upload ref to enable file drag and drop %> +<%!-- use phx-drop-target with the upload ref to enable file drag and drop --%>
-<%# render each avatar entry %> +<%!-- render each avatar entry --%> <%= for entry <- @uploads.avatar.entries do %>
- <%# Phoenix.LiveView.Helpers.live_img_preview/2 renders a client-side preview %> - <%= live_img_preview entry %> + <.live_img_preview entry={entry} />
<%= entry.client_name %>
- <%# entry.progress will update automatically for in-flight entries %> + <%!-- entry.progress will update automatically for in-flight entries --%> <%= entry.progress %>% - <%# a regular click event whose handler will invoke Phoenix.LiveView.cancel_upload/3 %> - + <%!-- a regular click event whose handler will invoke Phoenix.LiveView.cancel_upload/3 --%> + - <%# Phoenix.LiveView.Helpers.upload_errors/2 returns a list of error atoms %> + <%!-- Phoenix.Component.upload_errors/2 returns a list of error atoms --%> <%= for err <- upload_errors(@uploads.avatar, entry) do %>

<%= error_to_string(err) %>

<% end %> @@ -103,6 +102,11 @@ Let's look at an annotated example:
<% end %> +<%!-- Phoenix.Component.upload_errors/1 returns a list of error atoms --%> +<%= for err <- upload_errors(@uploads.avatar) do %> +

<%= error_to_string(err) %>

+<% end %> +
``` @@ -132,15 +136,22 @@ end Entries for files that do not match the [`allow_upload/3`] spec will contain errors. Use -`Phoenix.LiveView.Helpers.upload_errors/2` and your own +`Phoenix.Component.upload_errors/2` and your own helper function to render a friendly error message: ```elixir def error_to_string(:too_large), do: "Too large" -def error_to_string(:too_many_files), do: "You have selected too many files" def error_to_string(:not_accepted), do: "You have selected an unacceptable file type" ``` +For error messages that affect all entries, use +`Phoenix.Component.upload_errors/1`, and your own +helper function to render a friendly error message: + +```elixir +def error_to_string(:too_many_files), do: "You have selected too many files" +``` + ### Cancel an entry Upload entries may also be canceled, either programmatically @@ -156,7 +167,7 @@ end ## Consume uploaded entries -When the end-user submits a form containing a [`live_file_input/2`], +When the end-user submits a form containing a [`live_file_input/1`], the JavaScript client first uploads the file(s) before invoking the callback for the form's `phx-submit` event. @@ -171,8 +182,10 @@ def handle_event("save", _params, socket) do uploaded_files = consume_uploaded_entries(socket, :avatar, fn %{path: path}, _entry -> dest = Path.join([:code.priv_dir(:my_app), "static", "uploads", Path.basename(path)]) + # The `static/uploads` directory must exist for `File.cp!/2` + # and MyAppWeb.static_paths/0 should contain uploads to work,. File.cp!(path, dest) - Routes.static_path(socket, "/uploads/#{Path.basename(dest)}") + {:ok, ~p"/uploads/#{Path.basename(dest)}"} end) {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))} @@ -219,7 +232,7 @@ defmodule MyAppWeb.UploadLive do consume_uploaded_entries(socket, :avatar, fn %{path: path}, _entry -> dest = Path.join([:code.priv_dir(:my_app), "static", "uploads", Path.basename(path)]) File.cp!(path, dest) - Routes.static_path(socket, "/uploads/#{Path.basename(dest)}") + {:ok, ~p"/uploads/#{Path.basename(dest)}"} end) {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))} @@ -232,4 +245,4 @@ end ``` [`allow_upload/3`]: `Phoenix.LiveView.allow_upload/3` -[`live_file_input/2`]: `Phoenix.LiveView.Helpers.live_file_input/2` +[`live_file_input/1`]: `Phoenix.Component.live_file_input/1` diff --git a/guides/server/using-gettext.md b/guides/server/using-gettext.md index b5902e67a4..5adfa2e71e 100644 --- a/guides/server/using-gettext.md +++ b/guides/server/using-gettext.md @@ -1,22 +1,115 @@ # Using Gettext for internationalization For internationalization with [gettext](https://hexdocs.pm/gettext/Gettext.html), -the locale used within your Plug pipeline can be stored in the Plug session and -restored within your LiveView mount. For example, after user signs in or preference -changes, you can write the locale to the session: +you must call `Gettext.put_locale/2` on the LiveView mount callback to instruct +the LiveView which locale should be used for rendering the page. - def put_user_session(conn, current_user) do - locale = get_locale_for_user(current_user) +However, one question that has to be answered is how to retrieve the locale in +the first place. There are many approaches to solve this problem: + +1. The locale could be stored in the URL as a parameter +2. The locale could be stored in the session +3. The locale could be stored in the database + +We will briefly cover these approaches to provide some direction. + +## Locale from parameters + +You can say all URLs have a locale parameter. In your router: + + scope "/:locale" do + live ... + get ... + end + +Accessing a page without a locale should automatically redirect +to a URL with locale (the best locale could be fetched from +HTTP headers, which is outside of the scope of this guide). + +Then, assuming all URLs have a locale, you can set the Gettext +locale accordingly: + + def mount(%{"locale" => locale}, _session, socket) do Gettext.put_locale(MyApp.Gettext, locale) + {:ok, socket} + end + + +You can also use the [`on_mount`](`Phoenix.LiveView.on_mount/1`) hook to +automatically restore the locale for every LiveView in your application: + + defmodule MyAppWeb.RestoreLocale do + def on_mount(:default, %{"locale" => locale}, _session, socket) do + Gettext.put_locale(MyApp.Gettext, locale) + {:cont, socket} + end + + # catch-all case + def on_mount(:default, _params, _session, socket), do: {:cont, socket} + end + +Then, add this hook to `def live_view` under `MyAppWeb`, to run it on all +LiveViews by default: + + def live_view do + quote do + use Phoenix.LiveView, + layout: {MyAppWeb.LayoutView, :live} + + on_mount MyAppWeb.RestoreLocale + unquote(view_helpers()) + end + end + +Note that, because the Gettext locale is not stored in the assigns, if you +want to change the locale, you must use `<.link navigate={...} />`, instead +of simply patching the page. + +## Locale from session + +You may also store the locale in the Plug session. For example, in a controller +you might do: + + def put_user_session(conn, current_user) do + Gettext.put_locale(MyApp.Gettext, current_user.locale) conn |> put_session(:user_id, current_user.id) - |> put_session(:locale, locale) + |> put_session(:locale, current_user.locale) end -Then in your LiveView `mount/3`, you can restore the locale: +and then restore the locale from session within your LiveView mount: def mount(_params, %{"locale" => locale}, socket) do Gettext.put_locale(MyApp.Gettext, locale) {:ok, socket} end + +You can also encapsulate this in a hook, as done in the previous section. + +However, if the locale is stored in the session, you can only change it +by using regular controller requests. Therefore you should always use +`<.link to={...} />` to point to a controller that change the session +accordingly, reloading any LiveView. + +## Locale from database + +You may also allow users to store their locale configuration in the database. +Then, on `mount/3`, you can retrieve the user id from the session and load +the locale: + + def mount(_params, %{"user_id" => user_id}, socket) do + user = Users.get_user!(user_id) + Gettext.put_locale(MyApp.Gettext, user.locale) + {:ok, socket} + end + +In practice, you may end-up mixing more than one approach listed here. +For example, reading from the database is great once the user is logged in +but, before that happens, you may need to store the locale in the session +or in the URL. + +Similarly, you can keep the locale in the URL, but change the URL accordingly +to the user preferred locale once they sign in. Hopefully this guide gives +some suggestions on how to move forward and explore the best approach for your +application. diff --git a/lib/phoenix_component.ex b/lib/phoenix_component.ex index eb9b7efeff..bd7a3101e3 100644 --- a/lib/phoenix_component.ex +++ b/lib/phoenix_component.ex @@ -1,193 +1,363 @@ defmodule Phoenix.Component do @moduledoc ~S''' - API for function components. + Define reusable function components with HEEx templates. - A function component is any function that receives - an assigns map as argument and returns a rendered - struct built with [the `~H` sigil](`Phoenix.LiveView.Helpers.sigil_H/2`). - - Here is an example: + A function component is any function that receives an assigns + map as an argument and returns a rendered struct built with + [the `~H` sigil](`sigil_H/2`): defmodule MyComponent do use Phoenix.Component - # Optionally also bring the HTML helpers - # use Phoenix.HTML - def greet(assigns) do ~H""" -

Hello, <%= assigns.name %>

+

Hello, <%= @name %>!

""" end end - The component can be invoked as a regular function: + When invoked within a `~H` sigil or HEEx template file: - MyComponent.greet(%{name: "Jane"}) + ```heex + + ``` - But it is typically invoked using the function component - syntax from the `~H` sigil: - - ~H""" - - """ + The following HTML is rendered: - If the `MyComponent` module is imported or if the function - is defined locally, you can skip the module name: + ```html +

Hello, Jane!

+ ``` - ~H""" - <.greet name="Jane" /> - """ + If the function component is defined locally, or its module is imported, + then the caller can invoke the function directly without specifying the module: - Similar to any HTML tag inside the `~H` sigil, you can - interpolate attributes values too: + ```heex + <.greet name="Jane" /> + ``` - ~H""" - <.greet name={@user.name} /> - """ + For dynamic values, you can interpolate Elixir expressions into a function component: - You can learn more about the `~H` sigil [in its documentation](`Phoenix.LiveView.Helpers.sigil_H/2`). + ```heex + <.greet name={@user.name} /> + ``` - ## `use Phoenix.Component` + Function components can also accept blocks of HEEx content (more on this later): - Modules that define function components should call - `use Phoenix.Component` at the top. Doing so will import - the functions from both `Phoenix.LiveView` and - `Phoenix.LiveView.Helpers` modules. `Phoenix.LiveView` - and `Phoenix.LiveComponent` automatically invoke - `use Phoenix.Component` for you. + ```heex + <.card> +

This is the body of my card!

+ + ``` - You must avoid defining a module for each component. Instead, - we should use modules to group side-by-side related function - components. + Note how the `name` attribute automatically becomes the `@name` assign inside + function components. This can be further leveraged by using two higher-level + abstractions for us: attributes and slots. - ## Assigns + ## Attributes - While inside a function component, you must use `Phoenix.LiveView.assign/3` - and `Phoenix.LiveView.assign_new/3` to manipulate assigns, - so that LiveView can track changes to the assigns values. - For example, let's imagine a component that receives the first - name and last name and must compute the name assign. One option - would be: + `Phoenix.Component` provides the `attr/3` macro to declare what attributes the proceeding function + component expects to receive when invoked: - def show_name(assigns) do - assigns = assign(assigns, :name, assigns.first_name <> assigns.last_name) + attr :name, :string, required: true + def greet(assigns) do ~H""" -

Your name is: <%= @name %>

+

Hello, <%= @name %>!

""" end - However, when possible, it may be cleaner to break the logic over function - calls instead of precomputed assigns: + By calling `attr/3`, it is now clear that `greet/1` requires a string attribute called `name` + present in its assigns map to properly render. Failing to do so will result in a compilation + warning: + + ```heex + + + ``` + + Attributes can provide default values that are automatically merged into the assigns map: + + attr :name, :string, default: "Bob" + + Now you can invoke the function component without providing a value for `name`: + + ```heex + <.greet /> + ``` + + Rendering the following HTML: + + ```html +

Hello, Bob!

+ ``` - def show_name(assigns) do + Accessing an attribute which is required and does not have a default value will fail. + You must explicitly declare `default: nil` or assign a value programmatically with the + `assign_new/3` function. + + Multiple attributes can be declared for the same function component: + + attr :name, :string, required: true + attr :age, :integer, required: true + + def celebrate(assigns) do ~H""" -

Your name is: <%= full_name(@first_name, @last_name) %>

+

+ Happy birthday <%= @name %>! + You are <%= @age %> years old. +

""" end - defp full_name(first_name, last_name), do: first_name <> last_name + Allowing the caller to pass multiple values: - Another example is making an assign optional by providing - a default value: + ```heex + <.celebrate name={"Genevieve"} age={34} /> + ``` - def field_label(assigns) do - assigns = assign_new(assigns, :help, fn -> nil end) + Rendering the following HTML: - ~H""" - + Multiple function components can be defined in the same module, with different attributes. In the + following example, `` requires a `name`, but *does not* require a `title`, and + `` requires a `title`, but *does not* require a `name`. + + defmodule Components do + use Phoenix.Component + + attr :title, :string, required: true + + def heading(assigns) do + ~H""" +

<%= @title %>

+ """ + end + + attr :name, :string, required: true + + def greet(assigns) do + ~H""" +

Hello <%= @name %>

+ """ + end + end + + With the `attr/3` macro you have the core ingredients to create reusable function components. + But what if you need your function components to support dynamic attributes, such as common HTML + attributes to mix into a component's container? + + ## Global attributes + + Global attributes are a set of attributes that a function component can accept when it + declares an attribute of type `:global`. By default, the set of attributes accepted are those + attributes common to all standard HTML tags. + See [Global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes) + for a complete list of attributes. + + Once a global attribute is declared, any number of attributes in the set can be passed by + the caller without having to modify the function component itself. + + Below is an example of a function component that accepts a dynamic number of global attributes: + + attr :message, :string, required: true + attr :rest, :global + + def notification(assigns) do + ~H""" + <%= @message %> """ end - ## Slots + The caller can pass multiple global attributes (such as `phx-*` bindings or the `class` attribute): + + ```heex + <.notification message="You've got mail!" class="bg-green-200" phx-click="close" /> + ``` + + Rendering the following HTML: + + ```html + You've got mail! + ``` + + Note that the function component did not have to explicitly declare a `class` or `phx-click` + attribute in order to render. + + Global attributes can define defaults which are merged with attributes provided by the caller. + For example, you may declare a default `class` if the caller does not provide one: + + attr :rest, :global, default: %{class: "bg-blue-200"} + + Now you can call the function component without a `class` attribute: + + ```heex + <.notification message="You've got mail!" phx-click="close" /> + ``` + + Rendering the following HTML: + + ```html + You've got mail! + ``` + + Note that the global attribute cannot be provided directly and doing so will emit + a warning. In other words, this is invalid: + + ```heex + <.notification message="You've got mail!" rest={%{"phx-click" => "close"}} /> + ``` + + ### Included globals + + You may also specify which attributes are included in addition to the known globals + with the `:include` option. For example to support the `form` attribute on a button + component: + + ```elixir + # <.button form="my-form"/> + attr :rest, :global, include: ~w(form) + slot :inner_block + def button(assigns) do + ~H""" + + """ + end + ``` + + The `:include` option is useful to apply global additions on a case-by-case basis, + but sometimes you want to extend existing components with new global attributes, + such as Alpine.js' `x-` prefixes, which we'll outline next. + + ### Custom global attribute prefixes + + You can extend the set of global attributes by providing a list of attribute prefixes to + `use Phoenix.Component`. Like the default attributes common to all HTML elements, + any number of attributes that start with a global prefix will be accepted by function + components invoked by the current module. By default, the following prefixes are supported: + `phx-`, `aria-`, and `data-`. For example, to support the `x-` prefix used by + [Alpine.js](https://alpinejs.dev/), you can pass the `:global_prefixes` option to + `use Phoenix.Component`: + + use Phoenix.Component, global_prefixes: ~w(x-) - Slots is a mechanism to give HTML blocks to function components - as in regular HTML tags. + Now all function components invoked by this module will accept any number of attributes + prefixed with `x-`, in addition to the default global prefixes. - ### Default slots + You can learn more about attributes by reading the documentation for `attr/3`. - Any content you pass inside a component is assigned to a default slot - called `@inner_block`. For example, imagine you want to create a button - component like this: + ## Slots - <.button> - This renders inside the button! - + In addition to attributes, function components can accept blocks of HEEx content, referred to + as slots. Slots enable further customization of the rendered HTML, as the caller can pass the + function component HEEx content they want the component to render. `Phoenix.Component` provides + the `slot/3` macro used to declare slots for function components: - It is quite simple to do so. Simply define your component and call - `render_slot(@inner_block)` where you want to inject the content: + slot :inner_block, required: true def button(assigns) do ~H""" - """ end - In a nutshell, the contents given to the component is assigned to - the `@inner_block` assign and then we use `Phoenix.LiveView.Helpers.render_slot/2` - to render it. + The expression `render_slot(@inner_block)` renders the HEEx content. You can invoke this function + component like so: + + ```heex + <.button> + This renders inside the button! + + ``` + + Which renders the following HTML: + + ```html + + ``` + + Like the `attr/3` macro, using the `slot/3` macro will provide compile-time validations. + For example, invoking `button/1` without a slot of HEEx content will result in a compilation + warning being emitted: + + ```heex + <.button /> + + ``` + + ### The default slot + + The example above uses the default slot, accessible as an assign named `@inner_block`, to render + HEEx content via the `render_slot/2` function. - You can even have the component give a value back to the caller, - by using `let`. Imagine this component: + If the values rendered in the slot need to be dynamic, you can pass a second value back to the + HEEx content by calling `render_slot/2`: + + slot :inner_block, required: true + + attr :entries, :list, default: [] def unordered_list(assigns) do ~H"""
    <%= for entry <- @entries do %> -
  • <%= render_block(@inner_block, entry) %>
    • +
  • <%= render_slot(@inner_block, entry) %>
    • <% end %>
""" end - And now you can invoke it as: + When invoking the function component, you can use the special attribute `:let` to take the value + that the function component passes back and bind it to a variable: - <.unordered_list let={entry} entries={~w(apple banana cherry)}> - I like <%= entry %> - + ```heex + <.unordered_list :let={fruit} entries={~w(apples bananas cherries)}> + I like <%= fruit %>! + + ``` - ### Named slots + Rendering the following HTML: - Besides `@inner_block`, it is also possible to pass named slots - to the component. For example, imagine that you want to create - a modal component. The modal component has a header, a footer, - and the body of the modal, which we would use like this: + ```html +
    +
  • I like apples!
    • +
  • I like bananas!
    • +
  • I like cherries!
    • +
+ ``` - <.modal> - <:header> - This is the top of the modal. - + Now the separation of concerns is maintained: the caller can specify multiple values in a list + attribute without having to specify the HEEx content that surrounds and separates them. - This is the body - everything not in a - named slot goes to @inner_block. + ### Named slots - <:footer> - - - + In addition to the default slot, function components can accept multiple, named slots of HEEx + content. For example, imagine you want to create a modal that has a header, body, and footer: - The component itself could be implemented like this: + slot :header + slot :inner_block, required: true + slot :footer, required: true def modal(assigns) do ~H"""
- <%= render_slot(@header) %> + <%= render_slot(@header) || "Modal" %>
-
<%= render_slot(@inner_block) %>
-
<%= render_slot(@footer) %>
@@ -195,64 +365,577 @@ defmodule Phoenix.Component do """ end - If you want to make the `@header` and `@footer` optional, - you can assign them a default of an empty list at the top: + You can invoke this function component using the named slot HEEx syntax: + + ```heex + <.modal> + This is the body, everything not in a named slot is rendered in the default slot. + <:footer> + This is the bottom of the modal. + + + ``` + + Rendering the following HTML: + + ```html +
+
+ Modal. +
+
+ This is the body, everything not in a named slot is rendered in the default slot. +
+
+ This is the bottom of the modal. +
+
+ ``` + + As shown in the example above, `render_slot/1` returns `nil` when an optional slot + is declared and none is given. This can be used to attach default behaviour. + + ### Slot attributes + + Unlike the default slot, it is possible to pass a named slot multiple pieces of HEEx content. + Named slots can also accept attributes, defined by passing a block to the `slot/3` macro. + If multiple pieces of content are passed, `render_slot/2` will merge and render all the values. + + Below is a table component illustrating multiple named slots with attributes: + + slot :column, doc: "Columns with column labels" do + attr :label, :string, required: true, doc: "Column label" + end + + attr :rows, :list, default: [] + + def table(assigns) do + ~H""" + + + <%= for col <- @column do %> + + <% end %> + + <%= for row <- @rows do %> + + <%= for col <- @column do %> + + <% end %> + + <% end %> +
<%= col.label %>
<%= render_slot(col, row) %>
+ """ + end + + You can invoke this function component like so: + + ```heex + <.table rows={[%{name: "Jane", age: "34"}, %{name: "Bob", age: "51"}]}> + <:column :let={user} label="Name"> + <%= user.name %> + + <:column :let={user} label="Age"> + <%= user.age %> + + + ``` + + Rendering the following HTML: + + ```html + + + + + + + + + + + + + +
NameAge
Jane34
Bob51
+ ``` + + You can learn more about slots and the `slot/3` macro [in its documentation](`slot/3`). + + ### Embedding external template files + + The `embed_templates/1` macro can be used to embed `.html.heex` files + as function components. The directory path is based on the current + module (`__DIR__`), and a wildcard pattern may be used to select all + files within a directory tree. For example, imagine a directory listing: + + ├── components.ex + ├── cards + │ ├── pricing_card.html.heex + │ └── features_card.html.heex + + Then you can embed the page templates in your `components.ex` module + and call them like any other function component: + + defmodule MyAppWeb.Components do + use Phoenix.Component + + embed_templates "cards/*" + + def landing_hero(assigns) do + ~H""" + <.pricing_card /> + <.features_card /> + """ + end + end + + See `embed_templates/1` for more information, including declarative + assigns support for embedded templates. + ''' + + ## Functions + + alias Phoenix.LiveView.{Static, Socket} + @reserved_assigns Phoenix.Component.Declarative.__reserved__() + + @doc ~S''' + The `~H` sigil for writing HEEx templates inside source files. + + `HEEx` is a HTML-aware and component-friendly extension of Elixir Embedded + language (`EEx`) that provides: + + * Built-in handling of HTML attributes + + * An HTML-like notation for injecting function components + + * Compile-time validation of the structure of the template + + * The ability to minimize the amount of data sent over the wire + + * Out-of-the-box code formatting via `mix format` + + ## Example + + ~H""" +
+

Hello <%= @name %>

+ +
+ """ + + ## Syntax + + `HEEx` is built on top of Embedded Elixir (`EEx`). In this section, we are going to + cover the basic constructs in `HEEx` templates as well as its syntax extensions. + + ### Interpolation + + Both `HEEx` and `EEx` templates use `<%= ... %>` for interpolating code inside the body + of HTML tags: + + ```heex +

Hello, <%= @name %>

+ ``` + + Similarly, conditionals and other block Elixir constructs are supported: + + ```heex + <%= if @show_greeting? do %> +

Hello, <%= @name %>

+ <% end %> + ``` + + Note we don't include the equal sign `=` in the closing `<% end %>` tag + (because the closing tag does not output anything). + + There is one important difference between `HEEx` and Elixir's builtin `EEx`. + `HEEx` uses a specific annotation for interpolating HTML tags and attributes. + Let's check it out. + + ### HEEx extension: Defining attributes + + Since `HEEx` must parse and validate the HTML structure, code interpolation using + `<%= ... %>` and `<% ... %>` are restricted to the body (inner content) of the + HTML/component nodes and it cannot be applied within tags. + + For instance, the following syntax is invalid: + + ```heex +
+ ... +
+ ``` + + Instead do: + + ```heex +
+ ... +
+ ``` + + You can put any Elixir expression between `{ ... }`. For example, if you want + to set classes, where some are static and others are dynamic, you can using + string interpolation: + + ```heex +
+ ... +
+ ``` + + The following attribute values have special meaning: + + * `true` - if a value is `true`, the attribute is rendered with no value at all. + For example, `` is the same as ``; + + * `false` or `nil` - if a value is `false` or `nil`, the attribute is not rendered; + + * `list` (only for the `class` attribute) - each element of the list is processed + as a different class. `nil` and `false` elements are discarded. + + For multiple dynamic attributes, you can use the same notation but without + assigning the expression to any specific attribute. + + ```heex +
+ ... +
+ ``` + + The expression inside `{...}` must be either a keyword list or a map containing + the key-value pairs representing the dynamic attributes. + + You can pair this notation with `assigns_to_attributes/2` to strip out any internal + LiveView attributes and user-defined assigns from being expanded into the HTML tag: + + ```heex +
+ ... +
+ ``` + + The above would add all caller attributes into the HTML, but strip out LiveView + assigns like slots, as well as user-defined assigns like `:visible` that are not + meant to be added to the HTML itself. This approach is useful to allow a component + to accept arbitrary HTML attributes like class, ARIA attributes, etc. + + ### HEEx extension: Defining function components + + Function components are stateless components implemented as pure functions + with the help of the `Phoenix.Component` module. They can be either local + (same module) or remote (external module). + + `HEEx` allows invoking these function components directly in the template + using an HTML-like notation. For example, a remote function: + + ```heex + + ``` + + A local function can be invoked with a leading dot: + + ```heex + <.city name="Kraków"/> + ``` + + where the component could be defined as follows: + + defmodule MyApp.Weather do + use Phoenix.Component + + def city(assigns) do + ~H""" + The chosen city is: <%= @name %>. + """ + end + + def country(assigns) do + ~H""" + The chosen country is: <%= @name %>. + """ + end + end + + It is typically best to group related functions into a single module, as + opposed to having many modules with a single `render/1` function. Function + components support other important features, such as slots. You can learn + more about components in `Phoenix.Component`. + + ### HEEx extension: special attributes + + Apart from normal HTML attributes, HEEx also supports some special attributes + such as `:let` and `:for`. + + #### :let + + This is used by components and slots that want to yield a value back to the + caller. For an example, see how `form/1` works: + + ```heex + <.form :let={f} for={@form} phx-change="validate" phx-submit="save"> + <.input field={f[:username]} type="text" /> + ... + + ``` + + Notice how the variable `f`, defined by `.form` is used by your `input` component. + The `Phoenix.Component` module has detailed documentation on how to use and + implement such functionality. + + #### :if and :for + + It is a syntax sugar for `<%= if .. do %>` and `<%= for .. do %>` that can be + used in regular HTML, function components, and slots. + + For example in an HTML tag: + + ```heex + + + + +
<%= user.name %>
+ ``` + + The snippet above will only render the table if `@admin?` is true, + and generate a `tr` per user as you would expect from the collection. + + `:for` can be used similarly in function components: + + ```heex + <.error :for={msg <- @errors} message={msg}/> + ``` + + Which is equivalent to writing: + + ```heex + <%= for msg <- @errors do %> + <.error message={msg} /> + <% end %> + ``` + + And `:for` in slots behaves the same way: + + ```heex + <.table id="my-table" rows={@users}> + <:col :for={header <- @headers} :let={user}> + + +
<%= user[:header] %>
+ ``` + + You can also combine `:for` and `:if` for tags, components, and slot to act as a filter: + + ```heex + <.error :for={msg <- @errors} :if={msg != nil} message={msg} /> + ``` + + ## Code formatting + + You can automatically format HEEx templates (.heex) and `~H` sigils + using `Phoenix.LiveView.HTMLFormatter`. Please check that module + for more information. + ''' + @doc type: :macro + defmacro sigil_H({:<<>>, meta, [expr]}, []) do + unless Macro.Env.has_var?(__CALLER__, {:assigns, nil}) do + raise "~H requires a variable named \"assigns\" to exist and be set to a map" + end + + options = [ + engine: Phoenix.LiveView.TagEngine, + file: __CALLER__.file, + line: __CALLER__.line + 1, + caller: __CALLER__, + indentation: meta[:indentation] || 0, + source: expr, + tag_handler: Phoenix.LiveView.HTMLEngine + ] + + EEx.compile_string(expr, options) + end + + @doc ~S''' + Filters the assigns as a list of keywords for use in dynamic tag attributes. + + Useful for transforming caller assigns into dynamic attributes while + stripping reserved keys from the result. + + ## Examples + + Imagine the following `my_link` component which allows a caller + to pass a `new_window` assign, along with any other attributes they + would like to add to the element, such as class, data attributes, etc: + + ```heex + <.my_link to="/" id={@id} new_window={true} class="my-class">Home + ``` + + We could support the dynamic attributes with the following component: + + def my_link(assigns) do + target = if assigns[:new_window], do: "_blank", else: false + extra = assigns_to_attributes(assigns, [:new_window, :to]) - def modal(assigns) do assigns = assigns - |> assign_new(:header, fn -> [] end) - |> assign_new(:footer, fn -> [] end) + |> assign(:target, target) + |> assign(:extra, extra) ~H""" -
- ... + + <%= render_slot(@inner_block) %> + + """ end - ### Named slots with attributes + The above would result in the following rendered HTML: + + ```heex + Home + ``` + + The second argument (optional) to `assigns_to_attributes` is a list of keys to + exclude. It typically includes reserved keys by the component itself, which either + do not belong in the markup, or are already handled explicitly by the component. + ''' + def assigns_to_attributes(assigns, exclude \\ []) do + excluded_keys = @reserved_assigns ++ exclude + for {key, val} <- assigns, key not in excluded_keys, into: [], do: {key, val} + end + + @doc """ + Renders a LiveView within a template. + + This is useful in two situations: + + * When rendering a child LiveView inside a LiveView. + + * When rendering a LiveView inside a regular (non-live) controller/view. - It is also possible to pass the same named slot multiple - times and also give attributes to each of them. + ## Options - If multiple slot entries are defined for the same slot, - `render_slot/2` will automatically render all entries, - merging their contents. But sometimes we want more fine - grained control over each individual slot, including access - to their attributes. Let's see an example. Imagine we want - to implement a table component + * `:session` - a map of binary keys with extra session data to be serialized and sent + to the client. All session data currently in the connection is automatically available + in LiveViews. You can use this option to provide extra data. Remember all session data is + serialized and sent to the client, so you should always keep the data in the session + to a minimum. For example, instead of storing a User struct, you should store the "user_id" + and load the User when the LiveView mounts. + + * `:container` - an optional tuple for the HTML tag and DOM attributes to be used for the + LiveView container. For example: `{:li, style: "color: blue;"}`. By default it uses the module + definition container. See the "Containers" section below for more information. + + * `:id` - both the DOM ID and the ID to uniquely identify a LiveView. An `:id` is + automatically generated when rendering root LiveViews but it is a required option when + rendering a child LiveView. + + * `:sticky` - an optional flag to maintain the LiveView across live redirects, even if it is + nested within another LiveView. If you are rendering the sticky view within your live layout, + make sure that the sticky view itself does not use the same layout. You can do so by returning + `{:ok, socket, layout: false}` from mount. + + ## Examples + + When rendering from a controller/view, you can call: + + ```heex + <%= live_render(@conn, MyApp.ThermostatLive) %> + ``` + + Or: + + ```heex + <%= live_render(@conn, MyApp.ThermostatLive, session: %{"home_id" => @home.id}) %> + ``` + + Within another LiveView, you must pass the `:id` option: + + ```heex + <%= live_render(@socket, MyApp.ThermostatLive, id: "thermostat") %> + ``` + + ## Containers + + When a `LiveView` is rendered, its contents are wrapped in a container. By default, + the container is a `div` tag with a handful of `LiveView` specific attributes. + + The container can be customized in different ways: + + * You can change the default `container` on `use Phoenix.LiveView`: + + use Phoenix.LiveView, container: {:tr, id: "foo-bar"} + + * You can override the container tag and pass extra attributes when calling `live_render` + (as well as on your `live` call in your router): + + live_render socket, MyLiveView, container: {:tr, class: "highlight"} + + If you don't want the container to affect layout, you can use the CSS property + `display: contents` or a class that applies it, like Tailwind's `.contents`. + """ + def live_render(conn_or_socket, view, opts \\ []) + + def live_render(%Plug.Conn{} = conn, view, opts) do + case Static.render(conn, view, opts) do + {:ok, content, _assigns} -> + content + + {:stop, _} -> + raise RuntimeError, "cannot redirect from a child LiveView" + end + end + + def live_render(%Socket{} = parent, view, opts) do + Static.nested_render(parent, view, opts) + end + + @doc ~S''' + Renders a slot entry with the given optional `argument`. + + ```heex + <%= render_slot(@inner_block, @form) %> + ``` + + If the slot has no entries, nil is returned. + + If multiple slot entries are defined for the same slot,`render_slot/2` will automatically render + all entries, merging their contents. In case you want to use the entries' attributes, you need + to iterate over the list to access each slot individually. For example, imagine a table component: - <.table rows={@users}> - <:col let={user} label="Name"> - <%= user.name %> - + ```heex + <.table rows={@users}> + <:col :let={user} label="Name"> + <%= user.name %> + - <:col let={user} label="Address"> - <%= user.address %> - - + <:col :let={user} label="Address"> + <%= user.address %> + + + ``` - At the top level, we pass the rows as an assign and we define - a `:col` slot for each column we want in the table. Each - column also has a `label`, which we are going to use in the - table header. + At the top level, we pass the rows as an assign and we define a `:col` slot for each column we + want in the table. Each column also has a `label`, which we are going to use in the table header. - Inside the component, you can render the table with headers, - rows, and columns: + Inside the component, you can render the table with headers, rows, and columns: def table(assigns) do ~H"""
- <%= for col <- @col do %> - - <% end > - + + <% end %> + <%= for row <- @rows do %> <%= for col <- @col do %> - <%= render_slot(col, row) %> + <% end %> <% end %> @@ -260,17 +943,1853 @@ defmodule Phoenix.Component do """ end - Each named slot (including the `@inner_block`) is a list of maps, - where the map contains all slot attributes, allowing us to access - the label as `col.label`. This gives us complete control over how - we render them. ''' - - @doc false - defmacro __using__(_) do + defmacro render_slot(slot, argument \\ nil) do quote do - import Phoenix.LiveView - import Phoenix.LiveView.Helpers + unquote(__MODULE__).__render_slot__( + var!(changed, Phoenix.LiveView.Engine), + unquote(slot), + unquote(argument) + ) end end + + @doc false + def __render_slot__(_, [], _), do: nil + + def __render_slot__(changed, [entry], argument) do + call_inner_block!(entry, changed, argument) + end + + def __render_slot__(changed, entries, argument) when is_list(entries) do + assigns = %{entries: entries, changed: changed, argument: argument} + + ~H""" + <%= for entry <- @entries do %><%= call_inner_block!(entry, @changed, @argument) %><% end %> + """ + end + + def __render_slot__(changed, entry, argument) when is_map(entry) do + entry.inner_block.(changed, argument) + end + + defp call_inner_block!(entry, changed, argument) do + if !entry.inner_block do + message = "attempted to render slot <:#{entry.__slot__}> but the slot has no inner content" + raise RuntimeError, message + end + + entry.inner_block.(changed, argument) + end + + @doc """ + Returns the flash message from the LiveView flash assign. + + ## Examples + + ```heex +

<%= live_flash(@flash, :info) %>

+

<%= live_flash(@flash, :error) %>

+ ``` + """ + @doc deprecated: "Use Phoenix.Flash.get/2 in Phoenix v1.7+" + def live_flash(%_struct{} = other, _key) do + raise ArgumentError, "live_flash/2 expects a @flash assign, got: #{inspect(other)}" + end + + def live_flash(%{} = flash, key), do: Map.get(flash, to_string(key)) + + @doc """ + Returns the entry errors for an upload. + + The following error may be returned: + + * `:too_many_files` - The number of selected files exceeds the `:max_entries` constraint + + ## Examples + + def error_to_string(:too_many_files), do: "You have selected too many files" + + ```heex + <%= for err <- upload_errors(@uploads.avatar) do %> +
+ <%= error_to_string(err) %> +
+ <% end %> + ``` + """ + def upload_errors(%Phoenix.LiveView.UploadConfig{} = conf) do + for {ref, error} <- conf.errors, ref == conf.ref, do: error + end + + @doc """ + Returns the entry errors for an upload. + + The following errors may be returned: + + * `:too_large` - The entry exceeds the `:max_file_size` constraint + * `:not_accepted` - The entry does not match the `:accept` MIME types + + ## Examples + + def error_to_string(:too_large), do: "Too large" + def error_to_string(:not_accepted), do: "You have selected an unacceptable file type" + + ```heex + <%= for entry <- @uploads.avatar.entries do %> + <%= for err <- upload_errors(@uploads.avatar, entry) do %> +
+ <%= error_to_string(err) %> +
+ <% end %> + <% end %> + ``` + """ + def upload_errors( + %Phoenix.LiveView.UploadConfig{} = conf, + %Phoenix.LiveView.UploadEntry{} = entry + ) do + for {ref, error} <- conf.errors, ref == entry.ref, do: error + end + + @doc ~S''' + Assigns the given `key` with value from `fun` into `socket_or_assigns` if one does not yet exist. + + The first argument is either a LiveView `socket` or an `assigns` map from function components. + + This function is useful for lazily assigning values and sharing assigns. + We will cover both use cases next. + + ## Lazy assigns + + Imagine you have a function component that accepts a color: + + ```heex + <.my_component color="red" /> + ``` + + The color is also optional, so you can skip it: + + ```heex + <.my_component /> + ``` + + In such cases, the implementation can use `assign_new` to lazily + assign a color if none is given. Let's make it so it picks a random one + when none is given: + + def my_component(assigns) do + assigns = assign_new(assigns, :bg_color, fn -> Enum.random(~w(bg-red-200 bg-green-200 bg-blue-200)) end) + + ~H""" +
+ Example +
+ """ + end + + ## Sharing assigns + + It is possible to share assigns between the Plug pipeline and LiveView on disconnected render + and between LiveViews when connected. + + ### When disconnected + + When a user first accesses an application using LiveView, the LiveView is first rendered in its + disconnected state, as part of a regular HTML response. By using `assign_new` in the mount + callback of your LiveView, you can instruct LiveView to re-use any assigns already set in `conn` + during disconnected state. + + Imagine you have a Plug that does: + + # A plug + def authenticate(conn, _opts) do + if user_id = get_session(conn, :user_id) do + assign(conn, :current_user, Accounts.get_user!(user_id)) + else + send_resp(conn, :forbidden) + end + end + + You can re-use the `:current_user` assign in your LiveView during the initial render: + + def mount(_params, %{"user_id" => user_id}, socket) do + {:ok, assign_new(socket, :current_user, fn -> Accounts.get_user!(user_id) end)} + end + + In such case `conn.assigns.current_user` will be used if present. If there is no such + `:current_user` assign or the LiveView was mounted as part of the live navigation, where no Plug + pipelines are invoked, then the anonymous function is invoked to execute the query instead. + + ### When connected + + LiveView is also able to share assigns via `assign_new` within nested LiveView. If the parent + LiveView defines a `:current_user` assign and the child LiveView also uses `assign_new/3` to + fetch the `:current_user` in its `mount/3` callback, as above, the assign will be fetched from + the parent LiveView, once again avoiding additional database queries. + + Note that `fun` also provides access to the previously assigned values: + + assigns = + assigns + |> assign_new(:foo, fn -> "foo" end) + |> assign_new(:bar, fn %{foo: foo} -> foo <> "bar" end) + ''' + def assign_new(socket_or_assigns, key, fun) + + def assign_new(%Socket{} = socket, key, fun) when is_function(fun, 1) do + validate_assign_key!(key) + + case socket do + %{assigns: %{^key => _}} -> + socket + + %{private: %{assign_new: {assigns, keys}}} -> + # It is important to store the keys even if they are not in assigns + # because maybe the controller doesn't have it but the view does. + socket = put_in(socket.private.assign_new, {assigns, [key | keys]}) + + Phoenix.LiveView.Utils.force_assign( + socket, + key, + case assigns do + %{^key => value} -> value + %{} -> fun.(socket.assigns) + end + ) + + %{assigns: assigns} -> + Phoenix.LiveView.Utils.force_assign(socket, key, fun.(assigns)) + end + end + + def assign_new(%Socket{} = socket, key, fun) when is_function(fun, 0) do + validate_assign_key!(key) + + case socket do + %{assigns: %{^key => _}} -> + socket + + %{private: %{assign_new: {assigns, keys}}} -> + # It is important to store the keys even if they are not in assigns + # because maybe the controller doesn't have it but the view does. + socket = put_in(socket.private.assign_new, {assigns, [key | keys]}) + Phoenix.LiveView.Utils.force_assign(socket, key, Map.get_lazy(assigns, key, fun)) + + %{} -> + Phoenix.LiveView.Utils.force_assign(socket, key, fun.()) + end + end + + def assign_new(%{__changed__: changed} = assigns, key, fun) when is_function(fun, 1) do + case assigns do + %{^key => _} -> assigns + %{} -> Phoenix.LiveView.Utils.force_assign(assigns, changed, key, fun.(assigns)) + end + end + + def assign_new(%{__changed__: changed} = assigns, key, fun) when is_function(fun, 0) do + case assigns do + %{^key => _} -> assigns + %{} -> Phoenix.LiveView.Utils.force_assign(assigns, changed, key, fun.()) + end + end + + def assign_new(assigns, _key, fun) when is_function(fun, 0) or is_function(fun, 1) do + raise_bad_socket_or_assign!("assign_new/3", assigns) + end + + defp raise_bad_socket_or_assign!(name, assigns) do + extra = + case assigns do + %_{} -> + "" + + %{} -> + """ + You passed an assigns map that does not have the relevant change tracking \ + information. This typically means you are calling a function component by \ + hand instead of using the HEEx template syntax. If you are using HEEx, make \ + sure you are calling a component using: + + <.component attribute={value} /> + + If you are outside of HEEx and you want to test a component, use \ + Phoenix.LiveViewTest.render_component/2: + + Phoenix.LiveViewTest.render_component(&component/1, attribute: "value") + + """ + + _ -> + "" + end + + raise ArgumentError, + "#{name} expects a socket from Phoenix.LiveView/Phoenix.LiveComponent " <> + " or an assigns map from Phoenix.Component as first argument, got: " <> + inspect(assigns) <> extra + end + + @doc """ + Adds a `key`-`value` pair to `socket_or_assigns`. + + The first argument is either a LiveView `socket` or an `assigns` map from function components. + + ## Examples + + iex> assign(socket, :name, "Elixir") + + """ + def assign(socket_or_assigns, key, value) + + def assign(%Socket{} = socket, key, value) do + validate_assign_key!(key) + Phoenix.LiveView.Utils.assign(socket, key, value) + end + + def assign(%{__changed__: changed} = assigns, key, value) do + case assigns do + # force assign the key if the attribute was given with matching value + %{^key => ^value, __given__: given} when not is_map_key(given, key) -> + Phoenix.LiveView.Utils.force_assign(assigns, changed, key, value) + + %{^key => ^value} -> + assigns + + %{} -> + Phoenix.LiveView.Utils.force_assign(assigns, changed, key, value) + end + end + + def assign(assigns, _key, _val) do + raise_bad_socket_or_assign!("assign/3", assigns) + end + + @doc """ + Adds key-value pairs to assigns. + + The first argument is either a LiveView `socket` or an `assigns` map from function components. + + A keyword list or a map of assigns must be given as argument to be merged into existing assigns. + + ## Examples + + iex> assign(socket, name: "Elixir", logo: "💧") + iex> assign(socket, %{name: "Elixir"}) + + """ + def assign(socket_or_assigns, keyword_or_map) + when is_map(keyword_or_map) or is_list(keyword_or_map) do + Enum.reduce(keyword_or_map, socket_or_assigns, fn {key, value}, acc -> + assign(acc, key, value) + end) + end + + defp validate_assign_key!(:flash) do + raise ArgumentError, + ":flash is a reserved assign by LiveView and it cannot be set directly. " <> + "Use the appropriate flash functions instead." + end + + defp validate_assign_key!(_key), do: :ok + + @doc """ + Updates an existing `key` with `fun` in the given `socket_or_assigns`. + + The first argument is either a LiveView `socket` or an `assigns` map from function components. + + The update function receives the current key's value and returns the updated value. + Raises if the key does not exist. + + The update function may also be of arity 2, in which case it receives the current key's value + as the first argument and the current assigns as the second argument. + Raises if the key does not exist. + + ## Examples + + iex> update(socket, :count, fn count -> count + 1 end) + iex> update(socket, :count, &(&1 + 1)) + iex> update(socket, :max_users_this_session, fn current_max, %{users: users} -> + max(current_max, length(users)) + end) + """ + def update(socket_or_assigns, key, fun) + + def update(%Socket{assigns: assigns} = socket, key, fun) when is_function(fun, 2) do + update(socket, key, &fun.(&1, assigns)) + end + + def update(%Socket{assigns: assigns} = socket, key, fun) when is_function(fun, 1) do + case assigns do + %{^key => val} -> assign(socket, key, fun.(val)) + %{} -> raise KeyError, key: key, term: assigns + end + end + + def update(assigns, key, fun) when is_function(fun, 2) do + update(assigns, key, &fun.(&1, assigns)) + end + + def update(assigns, key, fun) when is_function(fun, 1) do + case assigns do + %{^key => val} -> assign(assigns, key, fun.(val)) + %{} -> raise KeyError, key: key, term: assigns + end + end + + def update(assigns, _key, fun) when is_function(fun, 1) or is_function(fun, 2) do + raise_bad_socket_or_assign!("update/3", assigns) + end + + @doc """ + Checks if the given key changed in `socket_or_assigns`. + + The first argument is either a LiveView `socket` or an `assigns` map from function components. + + ## Examples + + iex> changed?(socket, :count) + + """ + def changed?(socket_or_assigns, key) + + def changed?(%Socket{assigns: assigns}, key) do + Phoenix.LiveView.Utils.changed?(assigns, key) + end + + def changed?(%{__changed__: _} = assigns, key) do + Phoenix.LiveView.Utils.changed?(assigns, key) + end + + def changed?(assigns, _key) do + raise_bad_socket_or_assign!("changed?/2", assigns) + end + + @doc """ + Converts a given data structure to a `Phoenix.HTML.Form` + according to `Phoenix.HTML.FormData`. + + This is commonly used to convert a map or an Ecto changeset + into a form to be given to the `form/1` component. + + ## Creating a form from params + + If you want to create a form based on `handle_event` parameters, + you could do: + + def handle_event("submitted", params, socket) do + {:noreply, assign(socket, form: to_form(params))} + end + + When you pass a map to `to_form/1`, it assumes said map contains + the form parameters, which are expected to have string keys. + + You can also specify a name to nest the parameters: + + def handle_event("submitted", %{"user" => user_params}, socket) do + {:noreply, assign(socket, form: to_form(user_params, as: :user))} + end + + ## Creating a form from changesets + + When using changesets, the underlying data, form parameters, and + errors are retrieved from it. The `:as` option is automatically + computed too. For example, if you have a user schema: + + defmodule MyApp.Users.User do + use Ecto.Schema + + schema "..." do + ... + end + end + + And then you create a changeset which you pass to `to_form`: + + %MyApp.Blog.Post{} + |> Ecto.Changeset.change() + |> to_form() + + In this case, once the form is submitted, the parameters will + be available under `%{"post" => post_params}`. + + ## Options + + * `:as` - the `name` prefix to be used in form inputs + * `:id` - the `id` prefix to be used in form inputs + + The underlying data may accept additional options when + converted to forms. For example, a map accepts `:errors` + to list errors, but such option is not accepted by + changesets. + + If an existing `Phoenix.HTML.Form` struct is given, the + options below will override its existing values if given. + Then the remaining options are merged with the existing + form options. + """ + def to_form(data_or_params, options \\ []) + + def to_form(%Phoenix.HTML.Form{} = data, options) do + {name, id} = + case Keyword.fetch(options, :as) do + {:ok, as} -> + name = if as == nil, do: as, else: to_string(as) + {name, Keyword.get(options, :id) || name} + + :error -> + case Keyword.fetch(options, :id) do + {:ok, id} -> {data.name, id} + :error -> {data.name, data.id} + end + end + + {_as, options} = Keyword.pop(options, :as) + {errors, options} = Keyword.pop(options, :errors, data.errors) + options = Keyword.merge(data.options, options) + + %{data | errors: errors, id: id, name: name, options: options} + end + + def to_form(data, options) do + if is_atom(data) do + IO.warn(""" + Passing an atom to "for" in the form component is deprecated. + Instead of: + + <.form :let={f} for={#{inspect(data)}} ...> + + You might do: + + <.form :let={f} for={%{}} as={#{inspect(data)}} ...> + + Or, if you prefer, use to_form to create a form in your LiveView: + + assign(socket, form: to_form(%{}, as: #{inspect(data)})) + + and then use it in your templates (no :let required): + + <.form for={@form}> + """) + end + + Phoenix.HTML.FormData.to_form(data, options) + end + + @doc """ + Embeds external template files into the module as function components. + + ## Options + + * `:root` - The root directory to embed files. Defaults to the current + module's directory (`__DIR__`) + * `:suffix` - The string value to append to embedded function names. By + default, function names will be the name of the template file excluding + the format and engine. + + A wildcard pattern may be used to select all files within a directory tree. + For example, imagine a directory listing: + + ├── components.ex + ├── pages + │ ├── about_page.html.heex + │ └── welcome_page.html.heex + + Then to embed the page templates in your `components.ex` module: + + defmodule MyAppWeb.Components do + use Phoenix.Component + + embed_templates "pages/*" + end + + Now, your module will have an `about_page/1` and `welcome_page/1` function + component defined. Embedded templates also support declarative assigns + via bodyless function definitions, for example: + + defmodule MyAppWeb.Components do + use Phoenix.Component + + embed_templates "pages/*" + + attr :name, :string, required: true + def welcome_page(assigns) + + slot :header + def about_page(assigns) + end + + Multiple invocations of `embed_templates` is also supported, which can be + useful if you have more than one template format. For example: + + defmodule MyAppWeb.Emails do + use Phoenix.Component + + embed_templates "emails/*.html", suffix: "_html" + embed_templates "emails/*.text", suffix: "_text" + end + + Note: this function is the same as `Phoenix.Template.embed_templates/2`. + It is also provided here for convenience and documentation purposes. + Therefore, if you want to embed templates for other formats, which are + not related to `Phoenix.Component`, prefer to + `import Phoenix.Template, only: [embed_templates: 1]` than this module. + """ + @doc type: :macro + defmacro embed_templates(pattern, opts \\ []) do + quote bind_quoted: [pattern: pattern, opts: opts] do + Phoenix.Template.compile_all( + &Phoenix.Component.__embed__(&1, opts[:suffix]), + Path.expand(opts[:root] || __DIR__, __DIR__), + pattern + ) + end + end + + @doc false + def __embed__(path, suffix), + do: + path + |> Path.basename() + |> Path.rootname() + |> Path.rootname() + |> Kernel.<>(suffix || "") + + ## Declarative assigns API + + @doc false + defmacro __using__(opts \\ []) do + conditional = + if __CALLER__.module != Phoenix.LiveView.Helpers do + quote do: import(Phoenix.LiveView.Helpers) + end + + imports = + quote bind_quoted: [opts: opts] do + import Kernel, except: [def: 2, defp: 2] + import Phoenix.Component + import Phoenix.Component.Declarative + require Phoenix.Template + + for {prefix_match, value} <- Phoenix.Component.Declarative.__setup__(__MODULE__, opts) do + @doc false + def __global__?(unquote(prefix_match)), do: unquote(value) + end + end + + [conditional, imports] + end + + @doc ~S''' + Declares a function component slot. + + ## Arguments + + * `name` - an atom defining the name of the slot. Note that slots cannot define the same name + as any other slots or attributes declared for the same component. + + * `opts` - a keyword list of options. Defaults to `[]`. + + * `block` - a code block containing calls to `attr/3`. Defaults to `nil`. + + ### Options + + * `:required` - marks a slot as required. If a caller does not pass a value for a required slot, + a compilation warning is emitted. Otherwise, an omitted slot will default to `[]`. + + * `:doc` - documentation for the slot. Any slot attributes declared + will have their documentation listed alongside the slot. + + ### Slot Attributes + + A named slot may declare attributes by passing a block with calls to `attr/3`. + + Unlike attributes, slot attributes cannot accept the `:default` option. Passing one + will result in a compile warning being issued. + + ### The Default Slot + + The default slot can be declared by passing `:inner_block` as the `name` of the slot. + + Note that the `:inner_block` slot declaration cannot accept a block. Passing one will + result in a compilation error. + + ## Compile-Time Validations + + LiveView performs some validation of slots via the `:phoenix_live_view` compiler. + When slots are defined, LiveView will warn at compilation time on the caller if: + + * A required slot of a component is missing. + + * An unknown slot is given. + + * An unknown slot attribute is given. + + On the side of the function component itself, defining attributes provides the following + quality of life improvements: + + * Slot documentation is generated for the component. + + * Calls made to the component are tracked for reflection and validation purposes. + + ## Documentation Generation + + Public function components that define slots will have their docs injected into the function's + documentation, depending on the value of the `@doc` module attribute: + + * if `@doc` is a string, the slot docs are injected into that string. The optional placeholder + `[INSERT LVATTRDOCS]` can be used to specify where in the string the docs are injected. + Otherwise, the docs are appended to the end of the `@doc` string. + + * if `@doc` is unspecified, the slot docs are used as the default `@doc` string. + + * if `@doc` is `false`, the slot docs are omitted entirely. + + The injected slot docs are formatted as a markdown list: + + * `name` (required) - slot docs. Accepts attributes: + * `name` (`:type`) (required) - attr docs. Defaults to `:default`. + + By default, all slots will have their docs injected into the function `@doc` string. + To hide a specific slot, you can set the value of `:doc` to `false`. + + ## Example + + slot :header + slot :inner_block, required: true + slot :footer + + def modal(assigns) do + ~H""" +
+
+ <%= render_slot(@header) || "Modal" %> +
+
+ <%= render_slot(@inner_block) %> +
+
+ <%= render_slot(@footer) || submit_button() %> +
+
+ """ + end + + As shown in the example above, `render_slot/1` returns `nil` when an optional slot is declared + and none is given. This can be used to attach default behaviour. + ''' + @doc type: :macro + defmacro slot(name, opts, block) + + defmacro slot(name, opts, do: block) when is_atom(name) and is_list(opts) do + quote do + Phoenix.Component.Declarative.__slot__!( + __MODULE__, + unquote(name), + unquote(opts), + __ENV__.line, + __ENV__.file, + fn -> unquote(block) end + ) + end + end + + @doc """ + Declares a slot. See `slot/3` for more information. + """ + @doc type: :macro + defmacro slot(name, opts \\ []) when is_atom(name) and is_list(opts) do + {block, opts} = Keyword.pop(opts, :do, nil) + + quote do + Phoenix.Component.Declarative.__slot__!( + __MODULE__, + unquote(name), + unquote(opts), + __ENV__.line, + __ENV__.file, + fn -> unquote(block) end + ) + end + end + + @doc ~S''' + Declares attributes for a HEEx function components. + + ## Arguments + + * `name` - an atom defining the name of the attribute. Note that attributes cannot define the + same name as any other attributes or slots declared for the same component. + + * `type` - an atom defining the type of the attribute. + + * `opts` - a keyword list of options. Defaults to `[]`. + + ### Types + + An attribute is declared by its name, type, and options. The following types are supported: + + | Name | Description | + |-----------------|----------------------------------------------------------------------| + | `:any` | any term | + | `:string` | any binary string | + | `:atom` | any atom (including `true`, `false`, and `nil`) | + | `:boolean` | any boolean | + | `:integer` | any integer | + | `:float` | any float | + | `:list` | any list of any arbitrary types | + | `:map` | any map of any arbitrary types | + | `:global` | any common HTML attributes, plus those defined by `:global_prefixes` | + | A struct module | any module that defines a struct with `defstruct/1` | + + ### Options + + * `:required` - marks an attribute as required. If a caller does not pass the given attribute, + a compile warning is issued. + + * `:default` - the default value for the attribute if not provided. If this option is + not set and the attribute is not given, accessing the attribute will fail unless a + value is explicitly set with `assign_new/3`. + + * `:examples` - a non-exhaustive list of values accepted by the attribute, used for documentation + purposes. + + * `:values` - an exhaustive list of values accepted by the attributes. If a caller passes a literal + not contained in this list, a compile warning is issued. + + * `:doc` - documentation for the attribute. + + ## Compile-Time Validations + + LiveView performs some validation of attributes via the `:phoenix_live_view` compiler. + When attributes are defined, LiveView will warn at compilation time on the caller if: + + * A required attribute of a component is missing. + + * An unknown attribute is given. + + * You specify a literal attribute (such as `value="string"` or `value`, but not `value={expr}`) + and the type does not match. The following types currently support literal validation: + `:string`, `:atom`, `:boolean`, `:integer`, `:float`, `:map` and `:list`. + + * You specify a literal attribute and it is not a member of the `:values` list. + + LiveView does not perform any validation at runtime. This means the type information is mostly + used for documentation and reflection purposes. + + On the side of the LiveView component itself, defining attributes provides the following quality + of life improvements: + + * The default value of all attributes will be added to the `assigns` map upfront. + + * Attribute documentation is generated for the component. + + * Required struct types are annotated and emit compilation warnings. For example, if you specify + `attr :user, User, required: true` and then you write `@user.non_valid_field` in your template, + a warning will be emitted. + + * Calls made to the component are tracked for reflection and validation purposes. + + ## Documentation Generation + + Public function components that define attributes will have their attribute + types and docs injected into the function's documentation, depending on the + value of the `@doc` module attribute: + + * if `@doc` is a string, the attribute docs are injected into that string. The optional + placeholder `[INSERT LVATTRDOCS]` can be used to specify where in the string the docs are + injected. Otherwise, the docs are appended to the end of the `@doc` string. + + * if `@doc` is unspecified, the attribute docs are used as the default `@doc` string. + + * if `@doc` is `false`, the attribute docs are omitted entirely. + + The injected attribute docs are formatted as a markdown list: + + * `name` (`:type`) (required) - attr docs. Defaults to `:default`. + + By default, all attributes will have their types and docs injected into the function `@doc` + string. To hide a specific attribute, you can set the value of `:doc` to `false`. + + ## Example + + attr :name, :string, required: true + attr :age, :integer, required: true + + def celebrate(assigns) do + ~H""" +

+ Happy birthday <%= @name %>! + You are <%= @age %> years old. +

+ """ + end + ''' + @doc type: :macro + defmacro attr(name, type, opts \\ []) do + quote bind_quoted: [name: name, type: type, opts: opts] do + Phoenix.Component.Declarative.__attr__!( + __MODULE__, + name, + type, + opts, + __ENV__.line, + __ENV__.file + ) + end + end + + ## Components + + import Kernel, except: [def: 2, defp: 2] + import Phoenix.Component.Declarative + alias Phoenix.Component.Declarative + + # We need to bootstrap by hand to avoid conflicts. + [] = Declarative.__setup__(__MODULE__, []) + + attr = fn name, type, opts -> + Declarative.__attr__!(__MODULE__, name, type, opts, __ENV__.line, __ENV__.file) + end + + slot = fn name, opts -> + Declarative.__slot__!(__MODULE__, name, opts, __ENV__.line, __ENV__.file, fn -> nil end) + end + + @doc """ + A function component for rendering `Phoenix.LiveComponent` within a parent LiveView. + + While `LiveView`s can be nested, each LiveView starts its own process. A `LiveComponent` provides + similar functionality to `LiveView`, except they run in the same process as the `LiveView`, + with its own encapsulated state. That's why they are called stateful components. + + ## Attributes + + * `id` (`:string`) (required) - A unique identifier for the LiveComponent. Note the `id` won't + necessarily be used as the DOM `id`. That is up to the component to decide. + + * `module` (`:atom`) (required) - The LiveComponent module to render. + + Any additional attributes provided will be passed to the LiveComponent as a map of assigns. + See `Phoenix.LiveComponent` for more information. + + ## Examples + + ```heex + <.live_component module={MyApp.WeatherComponent} id="thermostat" city="Kraków" /> + ``` + """ + @doc type: :component + def live_component(assigns) + + def live_component(assigns) when is_map(assigns) do + id = assigns[:id] + + {module, assigns} = + assigns + |> Map.delete(:__changed__) + |> Map.pop(:module) + + if module == nil or not is_atom(module) do + raise ArgumentError, + ".live_component expects module={...} to be given and to be an atom, " <> + "got: #{inspect(module)}" + end + + if id == nil do + raise ArgumentError, ".live_component expects id={...} to be given, got: nil" + end + + case module.__live__() do + %{kind: :component} -> + %Phoenix.LiveView.Component{id: id, assigns: assigns, component: module} + + %{kind: kind} -> + raise ArgumentError, "expected #{inspect(module)} to be a component, but it is a #{kind}" + end + end + + def live_component(component) when is_atom(component) do + IO.warn( + "<%= live_component Component %> is deprecated, " <> + "please use <.live_component module={Component} id=\"hello\" /> inside HEEx templates instead" + ) + + Phoenix.LiveView.Helpers.__live_component__(component.__live__(), %{}, nil) + end + + @doc """ + Renders a title with automatic prefix/suffix on `@page_title` updates. + + [INSERT LVATTRDOCS] + + ## Examples + + ```heex + <.live_title prefix="MyApp – "> + <%= assigns[:page_title] || "Welcome" %> + + ``` + + ```heex + <.live_title suffix="- MyApp"> + <%= assigns[:page_title] || "Welcome" %> + + ``` + """ + @doc type: :component + attr.(:prefix, :string, + default: nil, + doc: "A prefix added before the content of `inner_block`." + ) + + attr.(:suffix, :string, default: nil, doc: "A suffix added after the content of `inner_block`.") + slot.(:inner_block, required: true, doc: "Content rendered inside the `title` tag.") + + def live_title(assigns) do + ~H""" + <%= @prefix %><%= render_slot(@inner_block) %><%= @suffix %> + """ + end + + @doc ~S''' + Renders a form. + + This function receives a form struct, generally created with `to_form/2`, + and generates the relevant form tags. It can be used either inside LiveView + or outside. + + ## Examples: inside LiveView + + Inside LiveViews, the `for={...}` attribute is generally a form struct + created with the `to_form/1` function. `to_form/1` expects either a map + or an [`Ecto.Changeset`](https://hexdocs.pm/ecto/Ecto.Changeset.html) + as the source of data. + + For example, you may use the parameters received in a + `c:Phoenix.LiveView.handle_event/3` callback to create an Ecto changeset + and then use `to_form/1` to convert it to a form. Then, in your templates, + you pass the `@form` as argument to `:for`: + + ```heex + <.form + for={@form} + phx-change="change_name" + > + <.input field={@form[:email]} /> + + ``` + + The `.input` component is generally defined as part of your own application + and adds all styling necessary: + + ```heex + def input(assigns) do + ~H""" + + """ + end + ``` + + A form accepts multiple options. For example, if you are doing file uploads + and you want to capture submissions, you might write instead: + + ```heex + <.form + for={@form} + multipart + phx-change="change_user" + phx-submit="save_user" + > + ... + + + ``` + + Notice how both examples use `phx-change`. The LiveView must implement the + `phx-change` event and store the input values as they arrive on change. + This is important because, if an unrelated change happens on the page, + LiveView should re-render the inputs with their updated values. Without `phx-change`, + the inputs would otherwise be cleared. Alternatively, you can use `phx-update="ignore"` + on the form to discard any updates. + + ### Using the `for` attribute + + The `for` attribute can also be a map or an Ecto.Changeset. In such cases, + a form will be created on the fly, and you can capture it using `:let`: + + ```heex + <.form + :let={form} + for={@changeset} + phx-change="change_user" + > + ``` + + However, such approach is discouraged in LiveView for two reasons: + + * LiveView can better optimize your code if you access the form fields + using `@form[:field]` rather than through the let-variable `form` + + * Ecto changesets are meant to be single use. By never storing the changeset + in the assign, you will be less tempted to use it across operations + + ### A note on `:errors` + + Even if `changeset.errors` is non-empty, errors will not be displayed in a + form if [the changeset + `:action`](https://hexdocs.pm/ecto/Ecto.Changeset.html#module-changeset-actions) + is `nil` or `:ignore`. + + This is useful for things like validation hints on form fields, e.g. an empty + changeset for a new form. That changeset isn't valid, but we don't want to + show errors until an actual user action has been performed. + + For example, if the user submits and a `Repo.insert/1` is called and fails on + changeset validation, the action will be set to `:insert` to show that an + insert was attempted, and the presence of that action will cause errors to be + displayed. The same is true for Repo.update/delete. + + If you want to show errors manually you can also set the action yourself, + either directly on the `Ecto.Changeset` struct field or by using + `Ecto.Changeset.apply_action/2`. Since the action can be arbitrary, you can + set it to `:validate` or anything else to avoid giving the impression that a + database operation has actually been attempted. + + ## Example: outside LiveView (regular HTTP requests) + + The `form` component can still be used to submit forms outside of LiveView. + In such cases, the `action` attribute MUST be given. Without said attribute, + the `form` method and csrf token are discarded. + + ```heex + <.form :let={f} for={@changeset} action={Routes.comment_path(:create, @comment)}> + <.input field={f[:body]} /> + + ``` + + In the example above, we passed a changeset to `for` and captured + the value using `:let={f}`. This approach is ok outside of LiveViews, + as there are no change tracking optimizations to consider. + + ### CSRF protection + + CSRF protection is a mechanism to ensure that the user who rendered + the form is the one actually submitting it. This module generates a + CSRF token by default. Your application should check this token on + the server to avoid attackers from making requests on your server on + behalf of other users. Phoenix by default checks this token. + + When posting a form with a host in its address, such as "//host.com/path" + instead of only "/path", Phoenix will include the host signature in the + token and validate the token only if the accessed host is the same as + the host in the token. This is to avoid tokens from leaking to third + party applications. If this behaviour is problematic, you can generate + a non-host specific token with `Plug.CSRFProtection.get_csrf_token/0` and + pass it to the form generator via the `:csrf_token` option. + + [INSERT LVATTRDOCS] + ''' + @doc type: :component + attr.(:for, :any, required: true, doc: "An existing form or the form source data.") + + attr.(:action, :string, + doc: """ + The action to submit the form on. + This attribute must be given if you intend to submit the form to a URL without LiveView. + """ + ) + + attr.(:as, :atom, + doc: """ + The server side parameter in which all params for this form + will be collected. For example, setting `as: :user_params` means + the parameters will be nested "user_params" in your `handle_event` + or `conn.params.user_params` for regular HTTP requests. + """ + ) + + attr.(:multipart, :boolean, + default: false, + doc: """ + Sets `enctype` to `multipart/form-data`. + Required when uploading files. + """ + ) + + attr.(:method, :string, + doc: """ + The HTTP method. + It is only used if an `:action` is given. If the method is not `get` nor `post`, + an input tag with name `_method` is generated alongside the form tag. + """ + ) + + attr.(:csrf_token, :any, + doc: """ + A token to authenticate the validity of requests. + One is automatically generated when an action is given and the method is not `get`. + When set to `false`, no token is generated. + """ + ) + + attr.(:errors, :list, + doc: """ + Use this to manually pass a keyword list of errors to the form, such as `@errors`. + This option is useful when a regular map is given as the form source and it will + make the errors available under `f.errors`. + """ + ) + + attr.(:rest, :global, + include: ~w(autocomplete name rel enctype novalidate target), + doc: "Additional HTML attributes to add to the form tag." + ) + + slot.(:inner_block, required: true, doc: "The content rendered inside of the form tag.") + + def form(assigns) do + action = assigns[:action] + + # We require for={...} to be given but we automatically handle nils for convenience + form_for = + case assigns[:for] do + nil -> %{} + other -> other + end + + form_options = assigns_to_attributes(Map.merge(assigns, assigns.rest), [:action, :for, :rest]) + + # Since FormData may add options, read the actual options from form + %{options: opts} = form = to_form(form_for, form_options) + + # By default, we will ignore action, method, and csrf token + # unless the action is given. + {attrs, hidden_method, csrf_token} = + if action do + {method, opts} = Keyword.pop(opts, :method) + {method, hidden_method} = form_method(method) + + {csrf_token, opts} = + Keyword.pop_lazy(opts, :csrf_token, fn -> + if method == "post" do + Plug.CSRFProtection.get_csrf_token_for(action) + end + end) + + {[action: action, method: method] ++ opts, hidden_method, csrf_token} + else + {opts, nil, nil} + end + + attrs = + case Keyword.pop(attrs, :multipart, false) do + {false, attrs} -> attrs + {true, attrs} -> Keyword.put(attrs, :enctype, "multipart/form-data") + end + + assigns = + assign(assigns, + form: form, + csrf_token: csrf_token, + hidden_method: hidden_method, + attrs: attrs + ) + + ~H""" + + <%= if @hidden_method && @hidden_method not in ~w(get post) do %> + + <% end %> + <%= if @csrf_token do %> + + <% end %> + <%= render_slot(@inner_block, @form) %> + + """ + end + + defp form_method(nil), do: {"post", nil} + defp form_method(method) when method in ~w(get post), do: {method, nil} + defp form_method(method) when is_binary(method), do: {"post", method} + + @doc """ + Renders nested form inputs for associations or embeds. + + [INSERT LVATTRDOCS] + + ## Examples + + ```heex + <.form + :let={f} + phx-change="change_name" + > + <.inputs_for :let={f_nested} field={f[:nested]}> + <.input type="text" field={f_nested[:name]} /> + + + ``` + """ + @doc type: :component + attr.(:field, Phoenix.HTML.FormField, + required: true, + doc: "A %Phoenix.HTML.Form{}/field name tuple, for example: {@form[:email]}." + ) + + attr.(:id, :string, + doc: """ + The id to be used in the form, defaults to the concatenation of the given + field to the parent form id. + """ + ) + + attr.(:as, :atom, + doc: """ + The name to be used in the form, defaults to the concatenation of the given + field to the parent form name. + """ + ) + + attr.(:default, :any, doc: "The value to use if none is available.") + + attr.(:prepend, :list, + doc: """ + The values to prepend when rendering. This only applies if the field value + is a list and no parameters were sent through the form. + """ + ) + + attr.(:append, :list, + doc: """ + The values to append when rendering. This only applies if the field value + is a list and no parameters were sent through the form. + """ + ) + + attr.(:skip_hidden, :boolean, + default: false, + doc: """ + Skip the automatic rendering of hidden fields to allow for more tight control + over the generated markup. + """ + ) + + slot.(:inner_block, required: true, doc: "The content rendered for each nested form.") + + def inputs_for(assigns) do + %Phoenix.HTML.FormField{field: field_name, form: form} = assigns.field + options = assigns |> Map.take([:id, :as, :default, :append, :prepend]) |> Keyword.new() + + options = + form.options + |> Keyword.take([:multipart]) + |> Keyword.merge(options) + + assigns = assign(assigns, :forms, form.impl.to_form(form.source, form, field_name, options)) + + ~H""" + <%= for finner <- @forms do %> + <%= unless @skip_hidden do %> + <%= for {name, value_or_values} <- finner.hidden, + name = name_for_value_or_values(finner, name, value_or_values), + value <- List.wrap(value_or_values) do %> + + <% end %> + <% end %> + <%= render_slot(@inner_block, finner) %> + <% end %> + """ + end + + defp name_for_value_or_values(form, field, values) when is_list(values) do + Phoenix.HTML.Form.input_name(form, field) <> "[]" + end + + defp name_for_value_or_values(form, field, _value) do + Phoenix.HTML.Form.input_name(form, field) + end + + @doc """ + Generates a link for live and href navigation. + + [INSERT LVATTRDOCS] + + ## Examples + + ```heex + <.link href="/">Regular anchor link + ``` + + ```heex + <.link navigate={Routes.page_path(@socket, :index)} class="underline">home + ``` + + ```heex + <.link navigate={Routes.live_path(@socket, MyLive, dir: :asc)} replace={false}> + Sort By Price + + ``` + + ```heex + <.link patch={Routes.page_path(@socket, :index, :details)}>view details + ``` + + ```heex + <.link href={URI.parse("https://elixir-lang.org")}>hello + ``` + + ```heex + <.link href="/the_world" method="delete" data-confirm="Really?">delete + ``` + + ## JavaScript dependency + + In order to support links where `:method` is not `"get"` or use the above data attributes, + `Phoenix.HTML` relies on JavaScript. You can load `priv/static/phoenix_html.js` into your + build tool. + + ### Data attributes + + Data attributes are added as a keyword list passed to the `data` key. The following data + attributes are supported: + + * `data-confirm` - shows a confirmation prompt before generating and submitting the form when + `:method` is not `"get"`. + + ### Overriding the default confirm behaviour + + `phoenix_html.js` does trigger a custom event `phoenix.link.click` on the clicked DOM element + when a click happened. This allows you to intercept the event on its way bubbling up + to `window` and do your own custom logic to enhance or replace how the `data-confirm` + attribute is handled. You could for example replace the browsers `confirm()` behavior with + a custom javascript implementation: + + ```javascript + // listen on document.body, so it's executed before the default of + // phoenix_html, which is listening on the window object + document.body.addEventListener('phoenix.link.click', function (e) { + // Prevent default implementation + e.stopPropagation(); + // Introduce alternative implementation + var message = e.target.getAttribute("data-confirm"); + if(!message){ return true; } + vex.dialog.confirm({ + message: message, + callback: function (value) { + if (value == false) { e.preventDefault(); } + } + }) + }, false); + ``` + + Or you could attach your own custom behavior. + + ```javascript + window.addEventListener('phoenix.link.click', function (e) { + // Introduce custom behaviour + var message = e.target.getAttribute("data-prompt"); + var answer = e.target.getAttribute("data-prompt-answer"); + if(message && answer && (answer != window.prompt(message))) { + e.preventDefault(); + } + }, false); + ``` + + The latter could also be bound to any `click` event, but this way you can be sure your custom + code is only executed when the code of `phoenix_html.js` is run. + + ## CSRF Protection + + By default, CSRF tokens are generated through `Plug.CSRFProtection`. + """ + @doc type: :component + attr.(:navigate, :string, + doc: """ + Navigates from a LiveView to a new LiveView. + The browser page is kept, but a new LiveView process is mounted and its content on the page + is reloaded. It is only possible to navigate between LiveViews declared under the same router + `Phoenix.LiveView.Router.live_session/3`. Otherwise, a full browser redirect is used. + """ + ) + + attr.(:patch, :string, + doc: """ + Patches the current LiveView. + The `handle_params` callback of the current LiveView will be invoked and the minimum content + will be sent over the wire, as any other LiveView diff. + """ + ) + + attr.(:href, :any, + doc: """ + Uses traditional browser navigation to the new location. + This means the whole page is reloaded on the browser. + """ + ) + + attr.(:replace, :boolean, + default: false, + doc: """ + When using `:patch` or `:navigate`, + should the browser's history be replaced with `pushState`? + """ + ) + + attr.(:method, :string, + default: "get", + doc: """ + The HTTP method to use with the link. This is intended for usage outside of LiveView + and therefore only works with the `href={...}` attribute. It has no effect on `patch` + and `navigate` instructions. + + In case the method is not `get`, the link is generated inside the form which sets the proper + information. In order to submit the form, JavaScript must be enabled in the browser. + """ + ) + + attr.(:csrf_token, :any, + default: true, + doc: """ + A boolean or custom token to use for links with an HTTP method other than `get`. + """ + ) + + attr.(:rest, :global, + include: ~w(download hreflang referrerpolicy rel target type), + doc: """ + Additional HTML attributes added to the `a` tag. + """ + ) + + slot.(:inner_block, + required: true, + doc: """ + The content rendered inside of the `a` tag. + """ + ) + + def link(%{navigate: to} = assigns) when is_binary(to) do + ~H""" + <%= render_slot(@inner_block) %> + """ + end + + def link(%{patch: to} = assigns) when is_binary(to) do + ~H""" + <%= render_slot(@inner_block) %> + """ + end + + def link(%{href: href} = assigns) when href != "#" and not is_nil(href) do + href = Phoenix.LiveView.Utils.valid_destination!(href, "<.link>") + assigns = assign(assigns, :href, href) + + ~H""" + <%= render_slot(@inner_block) %> + """ + end + + def link(%{} = assigns) do + ~H""" + <%= render_slot(@inner_block) %> + """ + end + + defp csrf_token(true, href), do: Plug.CSRFProtection.get_csrf_token_for(href) + defp csrf_token(false, _href), do: nil + defp csrf_token(csrf, _href) when is_binary(csrf), do: csrf + + @doc """ + Wraps tab focus around a container for accessibility. + + This is an essential accessibility feature for interfaces such as modals, dialogs, and menus. + + [INSERT LVATTRDOCS] + + ## Examples + + Simply render your inner content within this component and focus will be wrapped around the + container as the user tabs through the containers content: + + ```heex + <.focus_wrap id="my-modal" class="bg-white"> +
+ Are you sure? + + +
+ + ``` + """ + @doc type: :component + attr.(:id, :string, required: true, doc: "The DOM identifier of the container tag.") + + attr.(:rest, :global, doc: "Additional HTML attributes to add to the container tag.") + + slot.(:inner_block, required: true, doc: "The content rendered inside of the container tag.") + + def focus_wrap(assigns) do + ~H""" +
+ + <%= render_slot(@inner_block) %> + +
+ """ + end + + @doc """ + Generates a dynamically named HTML tag. + + Raises an `ArgumentError` if the tag name is found to be unsafe HTML. + + [INSERT LVATTRDOCS] + + ## Examples + + ```heex + <.dynamic_tag name="input" type="text"/> + ``` + + ```html + + ``` + + ```heex + <.dynamic_tag name="p">content + ``` + + ```html +

content

+ ``` + """ + @doc type: :component + attr.(:name, :string, required: true, doc: "The name of the tag, such as `div`.") + + attr.(:rest, :global, + doc: """ + Additional HTML attributes to add to the tag, ensuring proper escaping. + """ + ) + + slot.(:inner_block, []) + + def dynamic_tag(%{name: name, rest: rest} = assigns) do + tag_name = to_string(name) + + tag = + case Phoenix.HTML.html_escape(tag_name) do + {:safe, ^tag_name} -> + tag_name + + {:safe, _escaped} -> + raise ArgumentError, + "expected dynamic_tag name to be safe HTML, got: #{inspect(tag_name)}" + end + + assigns = + assigns + |> assign(:tag, tag) + |> assign(:escaped_attrs, Phoenix.HTML.attributes_escape(rest)) + + if assigns.inner_block != [] do + ~H""" + <%= {:safe, [?<, @tag]} %><%= @escaped_attrs %><%= {:safe, [?>]} %><%= render_slot(@inner_block) %><%= {:safe, [?<, ?/, @tag, ?>]} %> + """ + else + ~H""" + <%= {:safe, [?<, @tag]} %><%= @escaped_attrs %><%= {:safe, [?/, ?>]} %> + """ + end + end + + @doc """ + Builds a file input tag for a LiveView upload. + + ## Attributes + + * `:upload` - The `%Phoenix.LiveView.UploadConfig{}` struct. + + Arbitrary attributes may be passed to be applied to the file input tag. + + ## Drag and Drop + + Drag and drop is supported by annotating the droppable container with a `phx-drop-target` + attribute pointing to the DOM `id` of the file input. By default, the file input `id` is the + upload `ref`, so the following markup is all that is required for drag and drop support: + + ```heex +
+ + <.live_file_input upload={@uploads.avatar} /> +
+ ``` + + ## Examples + + ```heex + <.live_file_input upload={@uploads.avatar} /> + ``` + """ + @doc type: :component + def live_file_input(assigns) + + def live_file_input(%Phoenix.LiveView.UploadConfig{} = conf) do + IO.warn( + "live_file_input(upload) is deprecated, please use <.live_file_input upload={upload} /> instead" + ) + + Phoenix.LiveView.Helpers.live_file_input(conf, []) + end + + # TODO: Use attr when the backwards compatibility clause above is removed. + # attr :upload, Phoenix.LiveView.UploadConfig, required: true + # attr :rest, :global + def live_file_input(%{} = assigns) do + conf = + case assigns do + %{id: _} -> raise ArgumentError, "the :id cannot be overridden on a live_file_input" + %{upload: %Phoenix.LiveView.UploadConfig{} = conf} -> conf + %{} -> raise ArgumentError, "missing required :upload attribute to <.live_file_input/>" + end + + rest = assigns_to_attributes(assigns, [:upload]) + + rest = + if conf.max_entries > 1 do + Keyword.put(rest, :multiple, true) + else + rest + end + + assigns = + assign(assigns, + conf: conf, + rest: rest, + valid?: Enum.any?(conf.entries) && Enum.empty?(conf.errors), + done_entries: for(entry <- conf.entries, entry.done?, do: entry), + preflighted_entries: for(entry <- conf.entries, entry.preflighted?, do: entry) + ) + + ~H""" + + """ + end + + @doc """ + Generates an image preview on the client for a selected file. + + ## Examples + + ```heex + <%= for entry <- @uploads.avatar.entries do %> + <.live_img_preview entry={entry} width="75" /> + <% end %> + ``` + """ + @doc type: :component + def live_img_preview(assigns) + + def live_img_preview(%Phoenix.LiveView.UploadEntry{} = entry) do + IO.warn(""" + live_img_preview(entry) is deprecated, please use <.live_img_preview entry={entry} /> instead + """) + + live_img_preview(%{entry: entry}) + end + + # TODO: Use attr when the backwards compatibility clause above is removed. + # attr :entry, Phoenix.LiveView.UploadEntry, required: true + # attr :rest, :global + def live_img_preview(%{entry: %Phoenix.LiveView.UploadEntry{ref: ref} = entry} = assigns) do + rest = + assigns + |> assigns_to_attributes([:entry]) + |> Keyword.put_new_lazy(:id, fn -> "phx-preview-#{ref}" end) + + assigns = assign(assigns, entry: entry, ref: ref, rest: rest) + + ~H""" + + """ + end + + def live_img_preview(_assigns) do + raise ArgumentError, "missing required :entry attribute to <.live_img_preview/>" + end + + @doc """ + Intersperses separator slot between an enumerable. + + Useful when you need to add a separator between items such as when + rendering breadcrumbs for navigation. Provides each item to the + inner block. + + ## Examples + + ```heex + <.intersperse :let={item} enum={["home", "profile", "settings"]}> + <:separator> + | + + <%= item %> + + ``` + + Renders the following markup: + + home | profile | settings + """ + @doc type: :component + attr.(:enum, :any, required: true, doc: "the enumerable to intersperse with separators") + slot.(:inner_block, required: true, doc: "the inner_block to render for each item") + slot.(:separator, required: true, doc: "the slot for the separator") + + def intersperse(assigns) do + ~H""" + <%= for item <- Enum.intersperse(@enum, :separator) do %> + <%= if item == :separator do %> + <%= render_slot(@separator) %> + <% else %> + <%= render_slot(@inner_block, item) %> + <% end %> + <% end %> + """ + end end diff --git a/lib/phoenix_component/declarative.ex b/lib/phoenix_component/declarative.ex new file mode 100644 index 0000000000..1612802d3b --- /dev/null +++ b/lib/phoenix_component/declarative.ex @@ -0,0 +1,1249 @@ +defmodule Phoenix.Component.Declarative do + @moduledoc false + + ## Reserved assigns + + @reserved_assigns [ + :__changed__, + :__slot__, + :__given__, + :inner_block, + :myself, + :flash, + :socket + ] + + @doc false + def __reserved__, do: @reserved_assigns + + ## Global + + @global_prefixes ~w( + phx- + aria- + data- + ) + @globals ~w( + accesskey + alt + autocapitalize + autofocus + class + contenteditable + contextmenu + dir + draggable + enterkeyhint + exportparts + height + hidden + id + inputmode + is + itemid + itemprop + itemref + itemscope + itemtype + lang + nonce + onabort + onautocomplete + onautocompleteerror + onblur + oncancel + oncanplay + oncanplaythrough + onchange + onclick + onclose + oncontextmenu + oncuechange + ondblclick + ondrag + ondragend + ondragenter + ondragleave + ondragover + ondragstart + ondrop + ondurationchange + onemptied + onended + onerror + onfocus + oninput + oninvalid + onkeydown + onkeypress + onkeyup + onload + onloadeddata + onloadedmetadata + onloadstart + onmousedown + onmouseenter + onmouseleave + onmousemove + onmouseout + onmouseover + onmouseup + onmousewheel + onpause + onplay + onplaying + onprogress + onratechange + onreset + onresize + onscroll + onseeked + onseeking + onselect + onshow + onsort + onstalled + onsubmit + onsuspend + ontimeupdate + ontoggle + onvolumechange + onwaiting + part + placeholder + rel + role + slot + spellcheck + style + tabindex + target + title + translate + type + width + xml:base + xml:lang + ) + + @doc false + def __global__?(module, name, global_attr \\ nil) when is_atom(module) and is_binary(name) do + includes = global_attr && Keyword.get(global_attr.opts, :include, []) + + if function_exported?(module, :__global__?, 1) do + module.__global__?(name) or __global__?(name) or name in includes + else + __global__?(name) or name in includes + end + end + + for prefix <- @global_prefixes do + def __global__?(unquote(prefix) <> _), do: true + end + + for name <- @globals do + def __global__?(unquote(name)), do: true + end + + def __global__?(_), do: false + + ## Def overrides + + @doc false + defmacro def(expr, body) do + quote do + Kernel.def(unquote(annotate_def(:def, expr)), unquote(body)) + end + end + + @doc false + defmacro defp(expr, body) do + quote do + Kernel.defp(unquote(annotate_def(:defp, expr)), unquote(body)) + end + end + + defp annotate_def(kind, expr) do + case expr do + {:when, meta, [left, right]} -> {:when, meta, [annotate_call(kind, left), right]} + left -> annotate_call(kind, left) + end + end + + defp annotate_call(kind, {name, meta, [{:\\, default_meta, [left, right]}]}), + do: {name, meta, [{:\\, default_meta, [annotate_arg(kind, left), right]}]} + + defp annotate_call(kind, {name, meta, [arg]}), + do: {name, meta, [annotate_arg(kind, arg)]} + + defp annotate_call(_kind, left), + do: left + + defp annotate_arg(kind, {:=, meta, [{name, _, ctx} = var, arg]}) + when is_atom(name) and is_atom(ctx) do + {:=, meta, [var, quote(do: unquote(__MODULE__).__pattern__!(unquote(kind), unquote(arg)))]} + end + + defp annotate_arg(kind, {:=, meta, [arg, {name, _, ctx} = var]}) + when is_atom(name) and is_atom(ctx) do + {:=, meta, [quote(do: unquote(__MODULE__).__pattern__!(unquote(kind), unquote(arg))), var]} + end + + defp annotate_arg(kind, {name, meta, ctx} = var) when is_atom(name) and is_atom(ctx) do + {:=, meta, [quote(do: unquote(__MODULE__).__pattern__!(unquote(kind), _)), var]} + end + + defp annotate_arg(kind, arg) do + quote(do: unquote(__MODULE__).__pattern__!(unquote(kind), unquote(arg))) + end + + ## Attrs/slots + + @doc false + @valid_opts [:global_prefixes] + def __setup__(module, opts) do + {prefixes, invalid_opts} = Keyword.pop(opts, :global_prefixes, []) + + prefix_matches = + for prefix <- prefixes do + unless String.ends_with?(prefix, "-") do + raise ArgumentError, + "global prefixes for #{inspect(module)} must end with a dash, got: #{inspect(prefix)}" + end + + quote(do: {unquote(prefix) <> _, true}) + end + + if invalid_opts != [] do + raise ArgumentError, """ + invalid options passed to #{inspect(__MODULE__)}. + + The following options are supported: #{inspect(@valid_opts)}, got: #{inspect(invalid_opts)} + """ + end + + Module.register_attribute(module, :__attrs__, accumulate: true) + Module.register_attribute(module, :__slot_attrs__, accumulate: true) + Module.register_attribute(module, :__slots__, accumulate: true) + Module.register_attribute(module, :__slot__, accumulate: false) + Module.register_attribute(module, :__components_calls__, accumulate: true) + Module.put_attribute(module, :__components__, %{}) + Module.put_attribute(module, :on_definition, __MODULE__) + Module.put_attribute(module, :before_compile, __MODULE__) + + if prefix_matches == [] do + [] + else + prefix_matches ++ [quote(do: {_, false})] + end + end + + @doc false + def __slot__!(module, name, opts, line, file, block_fun) do + ensure_used!(module, line, file) + {doc, opts} = Keyword.pop(opts, :doc, nil) + + unless is_binary(doc) or is_nil(doc) or doc == false do + compile_error!(line, file, ":doc must be a string or false, got: #{inspect(doc)}") + end + + {required, opts} = Keyword.pop(opts, :required, false) + + unless is_boolean(required) do + compile_error!(line, file, ":required must be a boolean, got: #{inspect(required)}") + end + + Module.put_attribute(module, :__slot__, name) + + slot_attrs = + try do + block_fun.() + module |> Module.get_attribute(:__slot_attrs__) |> Enum.reverse() + after + Module.put_attribute(module, :__slot__, nil) + Module.delete_attribute(module, :__slot_attrs__) + end + + slot = %{ + name: name, + required: required, + opts: opts, + doc: doc, + line: line, + attrs: slot_attrs + } + + validate_slot!(module, slot, line, file) + Module.put_attribute(module, :__slots__, slot) + :ok + end + + defp validate_slot!(module, slot, line, file) do + slots = Module.get_attribute(module, :__slots__) || [] + + if Enum.find(slots, &(&1.name == slot.name)) do + compile_error!(line, file, """ + a duplicate slot with name #{inspect(slot.name)} already exists\ + """) + end + + if slot.name == :inner_block and slot.attrs != [] do + compile_error!(line, file, """ + cannot define attributes in a slot with name #{inspect(slot.name)} + """) + end + end + + @doc false + def __attr__!(module, name, type, opts, line, file) when is_atom(name) and is_list(opts) do + ensure_used!(module, line, file) + slot = Module.get_attribute(module, :__slot__) + + if name == :inner_block do + compile_error!( + line, + file, + "cannot define attribute called :inner_block. Maybe you wanted to use `slot` instead?" + ) + end + + if type == :global && slot do + compile_error!(line, file, "cannot define :global slot attributes") + end + + if type == :global and Keyword.has_key?(opts, :required) do + compile_error!(line, file, "global attributes do not support the :required option") + end + + if type == :global and Keyword.has_key?(opts, :values) do + compile_error!(line, file, "global attributes do not support the :values option") + end + + if type == :global and Keyword.has_key?(opts, :examples) do + compile_error!(line, file, "global attributes do not support the :examples option") + end + + if type != :global and Keyword.has_key?(opts, :include) do + compile_error!(line, file, ":include is only supported for :global attributes") + end + + {doc, opts} = Keyword.pop(opts, :doc, nil) + + unless is_binary(doc) or is_nil(doc) or doc == false do + compile_error!(line, file, ":doc must be a string or false, got: #{inspect(doc)}") + end + + {required, opts} = Keyword.pop(opts, :required, false) + + unless is_boolean(required) do + compile_error!(line, file, ":required must be a boolean, got: #{inspect(required)}") + end + + if required and Keyword.has_key?(opts, :default) do + compile_error!(line, file, "only one of :required or :default must be given") + end + + key = if slot, do: :__slot_attrs__, else: :__attrs__ + type = validate_attr_type!(module, key, slot, name, type, line, file) + validate_attr_opts!(slot, name, opts, line, file) + + if Keyword.has_key?(opts, :values) and Keyword.has_key?(opts, :examples) do + compile_error!(line, file, "only one of :values or :examples must be given") + end + + if Keyword.has_key?(opts, :values) do + validate_attr_values!(slot, name, type, opts[:values], line, file) + end + + if Keyword.has_key?(opts, :examples) do + validate_attr_examples!(slot, name, type, opts[:examples], line, file) + end + + if Keyword.has_key?(opts, :default) do + validate_attr_default!(slot, name, type, opts, line, file) + end + + attr = %{ + slot: slot, + name: name, + type: type, + required: required, + opts: opts, + doc: doc, + line: line + } + + Module.put_attribute(module, key, attr) + :ok + end + + @builtin_types [:boolean, :integer, :float, :string, :atom, :list, :map, :global] + @valid_types [:any] ++ @builtin_types + + defp validate_attr_type!(module, key, slot, name, type, line, file) when is_atom(type) do + attrs = Module.get_attribute(module, key) || [] + + cond do + Enum.find(attrs, fn attr -> attr.name == name end) -> + compile_error!(line, file, """ + a duplicate attribute with name #{attr_slot(name, slot)} already exists\ + """) + + existing = type == :global && Enum.find(attrs, fn attr -> attr.type == :global end) -> + compile_error!(line, file, """ + cannot define :global attribute #{inspect(name)} because one \ + is already defined as #{attr_slot(existing.name, slot)}. \ + Only a single :global attribute may be defined\ + """) + + true -> + :ok + end + + case Atom.to_string(type) do + "Elixir." <> _ -> {:struct, type} + _ when type in @valid_types -> type + _ -> bad_type!(slot, name, type, line, file) + end + end + + defp validate_attr_type!(_module, _key, slot, name, type, line, file) do + bad_type!(slot, name, type, line, file) + end + + defp bad_type!(slot, name, type, line, file) do + compile_error!(line, file, """ + invalid type #{inspect(type)} for attr #{attr_slot(name, slot)}. \ + The following types are supported: + + * any Elixir struct, such as URI, MyApp.User, etc + * one of #{Enum.map_join(@builtin_types, ", ", &inspect/1)} + * :any for all other types + """) + end + + defp attr_slot(name, nil), do: "#{inspect(name)}" + defp attr_slot(name, slot), do: "#{inspect(name)} in slot #{inspect(slot)}" + + defp validate_attr_default!(slot, name, type, opts, line, file) do + case {opts[:default], opts[:values]} do + {default, nil} -> + unless valid_value?(type, default) do + bad_default!(slot, name, type, default, line, file) + end + + {default, values} -> + unless default in values do + compile_error!(line, file, """ + expected the default value for attr #{attr_slot(name, slot)} to be one of #{inspect(values)}, \ + got: #{inspect(default)} + """) + end + end + end + + defp bad_default!(slot, name, type, default, line, file) do + compile_error!(line, file, """ + expected the default value for attr #{attr_slot(name, slot)} to be #{type_with_article(type)}, \ + got: #{inspect(default)} + """) + end + + defp validate_attr_values!(slot, name, type, values, line, file) do + unless is_enumerable(values) and not Enum.empty?(values) do + compile_error!(line, file, """ + :values must be a non-empty enumerable, got: #{inspect(values)} + """) + end + + for value <- values, + not valid_value?(type, value), + do: bad_value!(slot, name, type, value, line, file) + end + + defp is_enumerable(values) do + Enumerable.impl_for(values) != nil + end + + defp bad_value!(slot, name, type, value, line, file) do + compile_error!(line, file, """ + expected the values for attr #{attr_slot(name, slot)} to be #{type_with_article(type)}, \ + got: #{inspect(value)} + """) + end + + defp validate_attr_examples!(slot, name, type, examples, line, file) do + unless is_list(examples) and not Enum.empty?(examples) do + compile_error!(line, file, """ + :examples must be a non-empty list, got: #{inspect(examples)} + """) + end + + for example <- examples, + not valid_value?(type, example), + do: bad_example!(slot, name, type, example, line, file) + end + + defp bad_example!(slot, name, type, example, line, file) do + compile_error!(line, file, """ + expected the examples for attr #{attr_slot(name, slot)} to be #{type_with_article(type)}, \ + got: #{inspect(example)} + """) + end + + defp valid_value?(_type, nil), do: true + defp valid_value?(:any, _value), do: true + defp valid_value?(:string, value), do: is_binary(value) + defp valid_value?(:atom, value), do: is_atom(value) + defp valid_value?(:boolean, value), do: is_boolean(value) + defp valid_value?(:integer, value), do: is_integer(value) + defp valid_value?(:float, value), do: is_float(value) + defp valid_value?(:list, value), do: is_list(value) + defp valid_value?({:struct, mod}, value), do: is_struct(value, mod) + defp valid_value?(_type, _value), do: true + + defp validate_attr_opts!(slot, name, opts, line, file) do + for {key, _} <- opts, message = invalid_attr_message(key, slot) do + compile_error!(line, file, """ + invalid option #{inspect(key)} for attr #{attr_slot(name, slot)}. #{message}\ + """) + end + end + + defp invalid_attr_message(:include, inc) when is_list(inc) or is_nil(inc), do: nil + + defp invalid_attr_message(:include, other), + do: "include only supports a list of attributes, got: #{inspect(other)}" + + defp invalid_attr_message(:default, nil), do: nil + + defp invalid_attr_message(:default, _), + do: + ":default is not supported inside slot attributes, " <> + "instead use Map.get/3 with a default value when accessing a slot attribute" + + defp invalid_attr_message(:required, _), do: nil + defp invalid_attr_message(:values, _), do: nil + defp invalid_attr_message(:examples, _), do: nil + + defp invalid_attr_message(_key, nil), + do: "The supported options are: [:required, :default, :values, :examples]" + + defp invalid_attr_message(_key, _slot), + do: "The supported options inside slots are: [:required]" + + defp compile_error!(line, file, msg) do + raise CompileError, line: line, file: file, description: msg + end + + defmacro __pattern__!(kind, arg) do + {name, 1} = __CALLER__.function + {_slots, attrs} = register_component!(kind, __CALLER__, name, true) + + fields = + for %{name: name, required: true, type: {:struct, struct}} <- attrs do + {name, quote(do: %unquote(struct){})} + end + + if fields == [] do + arg + else + quote(do: %{unquote_splicing(fields)} = unquote(arg)) + end + end + + @doc false + def __on_definition__(env, kind, name, args, _guards, body) do + check? = not String.starts_with?(to_string(name), "__") + + cond do + check? and length(args) == 1 and body == nil -> + register_component!(kind, env, name, false) + + check? -> + attrs = pop_attrs(env) + + validate_misplaced_attrs!(attrs, env.file, fn -> + case length(args) do + 1 -> + "could not define attributes for function #{name}/1. " <> + "Please make sure that you have `use Phoenix.Component` and that the function has no default arguments" + + arity -> + "cannot declare attributes for function #{name}/#{arity}. Components must be functions with arity 1" + end + end) + + slots = pop_slots(env) + + validate_misplaced_slots!(slots, env.file, fn -> + case length(args) do + 1 -> + "could not define slots for function #{name}/1. " <> + "Components cannot be dynamically defined or have default arguments" + + arity -> + "cannot declare slots for function #{name}/#{arity}. Components must be functions with arity 1" + end + end) + + true -> + :ok + end + end + + @after_verify_supported Version.match?(System.version(), ">= 1.14.0-dev") + + @doc false + defmacro __before_compile__(env) do + attrs = pop_attrs(env) + + validate_misplaced_attrs!(attrs, env.file, fn -> + "cannot define attributes without a related function component" + end) + + slots = pop_slots(env) + + validate_misplaced_slots!(slots, env.file, fn -> + "cannot define slots without a related function component" + end) + + components = Module.get_attribute(env.module, :__components__) + components_calls = Module.get_attribute(env.module, :__components_calls__) |> Enum.reverse() + + names_and_defs = + for {name, %{kind: kind, attrs: attrs, slots: slots}} <- components do + attr_defaults = + for %{name: name, required: false, opts: opts} <- attrs, + Keyword.has_key?(opts, :default), + do: {name, Macro.escape(opts[:default])} + + slot_defaults = + for %{name: name, required: false} <- slots do + {name, []} + end + + defaults = attr_defaults ++ slot_defaults + + {global_name, global_default} = + case Enum.find(attrs, fn attr -> attr.type == :global end) do + %{name: name, opts: opts} -> {name, Macro.escape(Keyword.get(opts, :default, %{}))} + nil -> {nil, nil} + end + + attr_names = for(attr <- attrs, do: attr.name) + slot_names = for(slot <- slots, do: slot.name) + known_keys = attr_names ++ slot_names ++ @reserved_assigns + + def_body = + if global_name do + quote do + {assigns, caller_globals} = Map.split(assigns, unquote(known_keys)) + + globals = + case assigns do + %{unquote(global_name) => explicit_global_assign} -> explicit_global_assign + %{} -> Map.merge(unquote(global_default), caller_globals) + end + + merged = + %{unquote_splicing(defaults)} + |> Map.merge(assigns) + |> Map.put(:__given__, assigns) + + super(Phoenix.Component.assign(merged, unquote(global_name), globals)) + end + else + quote do + merged = + %{unquote_splicing(defaults)} + |> Map.merge(assigns) + |> Map.put(:__given__, assigns) + + super(merged) + end + end + + merge = + quote do + Kernel.unquote(kind)(unquote(name)(assigns)) do + unquote(def_body) + end + end + + {{name, 1}, merge} + end + + {names, defs} = Enum.unzip(names_and_defs) + + overridable = + if names != [] do + quote do + defoverridable unquote(names) + end + end + + def_components_ast = + quote do + def __components__() do + unquote(Macro.escape(components)) + end + end + + def_components_calls_ast = + if components_calls != [] and @after_verify_supported do + quote do + @after_verify {__MODULE__, :__phoenix_component_verify__} + + @doc false + def __phoenix_component_verify__(module) do + unquote(__MODULE__).__verify__(module, unquote(Macro.escape(components_calls))) + end + end + end + + {:__block__, [], [def_components_ast, def_components_calls_ast, overridable | defs]} + end + + defp register_component!(kind, env, name, check_if_defined?) do + slots = pop_slots(env) + attrs = pop_attrs(env) + + cond do + slots != [] or attrs != [] -> + check_if_defined? and raise_if_function_already_defined!(env, name, slots, attrs) + register_component_doc(env, kind, slots, attrs) + + for %{name: slot_name, line: line} <- slots, + Enum.find(attrs, &(&1.name == slot_name)) do + compile_error!(line, env.file, """ + cannot define a slot with name #{inspect(slot_name)}, as an attribute with that name already exists\ + """) + end + + components = + env.module + |> Module.get_attribute(:__components__) + # Sort by name as this is used when they are validated + |> Map.put(name, %{ + kind: kind, + attrs: Enum.sort_by(attrs, & &1.name), + slots: Enum.sort_by(slots, & &1.name) + }) + + Module.put_attribute(env.module, :__components__, components) + Module.put_attribute(env.module, :__last_component__, name) + {slots, attrs} + + Module.get_attribute(env.module, :__last_component__) == name -> + %{slots: slots, attrs: attrs} = Module.get_attribute(env.module, :__components__)[name] + {slots, attrs} + + true -> + {[], []} + end + end + + # Documentation handling + + defp register_component_doc(env, :def, slots, attrs) do + case Module.get_attribute(env.module, :doc) do + {_line, false} -> + :ok + + {line, doc} -> + Module.put_attribute(env.module, :doc, {line, build_component_doc(doc, slots, attrs)}) + + nil -> + Module.put_attribute(env.module, :doc, {env.line, build_component_doc(slots, attrs)}) + end + end + + defp register_component_doc(_env, :defp, _slots, _attrs) do + :ok + end + + defp build_component_doc(doc \\ "", slots, attrs) do + [left | right] = String.split(doc, "[INSERT LVATTRDOCS]") + + IO.iodata_to_binary([ + build_left_doc(left), + build_component_docs(slots, attrs), + build_right_doc(right) + ]) + end + + defp build_left_doc("") do + [""] + end + + defp build_left_doc(left) do + [left, ?\n] + end + + defp build_component_docs(slots, attrs) do + case {slots, attrs} do + {[], []} -> + [] + + {slots, [] = _attrs} -> + [build_slots_docs(slots)] + + {[] = _slots, attrs} -> + [build_attrs_docs(attrs)] + + {slots, attrs} -> + [build_attrs_docs(attrs), ?\n, build_slots_docs(slots)] + end + end + + defp build_slots_docs(slots) do + [ + "## Slots\n", + for slot <- slots, slot.doc != false, into: [] do + slot_attrs = + for slot_attr <- slot.attrs, + slot_attr.doc != false, + slot_attr.slot == slot.name, + do: slot_attr + + [ + "\n* ", + build_slot_name(slot), + build_slot_required(slot), + build_slot_doc(slot, slot_attrs) + ] + end + ] + end + + defp build_attrs_docs(attrs) do + [ + "## Attributes\n", + for attr <- attrs, attr.doc != false, attr.type != :global, into: [] do + [ + "\n* ", + build_attr_name(attr), + build_attr_type(attr), + build_attr_required(attr), + build_hyphen(attr), + build_attr_doc_and_default(attr, " "), + build_attr_values_or_examples(attr) + ] + end, + if Enum.any?(attrs, &(&1.type == :global)) do + "\nGlobal attributes are accepted." + else + "" + end + ] + end + + defp build_slot_name(%{name: name}) do + ["`", Atom.to_string(name), "`"] + end + + defp build_slot_doc(%{doc: nil}, []) do + [] + end + + defp build_slot_doc(%{doc: doc}, []) do + [" - ", build_doc(doc, " ", false)] + end + + defp build_slot_doc(%{doc: nil}, slot_attrs) do + [" - Accepts attributes:\n", build_slot_attrs_docs(slot_attrs)] + end + + defp build_slot_doc(%{doc: doc}, slot_attrs) do + [ + " - ", + build_doc(doc, " ", true), + "Accepts attributes:\n", + build_slot_attrs_docs(slot_attrs) + ] + end + + defp build_slot_attrs_docs(slot_attrs) do + for slot_attr <- slot_attrs do + [ + "\n * ", + build_attr_name(slot_attr), + build_attr_type(slot_attr), + build_attr_required(slot_attr), + build_hyphen(slot_attr), + build_attr_doc_and_default(slot_attr, " "), + build_attr_values_or_examples(slot_attr) + ] + end + end + + defp build_slot_required(%{required: true}) do + [" (required)"] + end + + defp build_slot_required(_slot) do + [] + end + + defp build_attr_name(%{name: name}) do + ["`", Atom.to_string(name), "` "] + end + + defp build_attr_type(%{type: {:struct, type}}) do + ["(`", inspect(type), "`)"] + end + + defp build_attr_type(%{type: type}) do + ["(`", inspect(type), "`)"] + end + + defp build_attr_required(%{required: true}) do + [" (required)"] + end + + defp build_attr_required(_attr) do + [] + end + + defp build_attr_doc_and_default(%{doc: doc, type: :global, opts: opts}, indent) do + case Keyword.fetch(opts, :include) do + {:ok, [_ | _] = inc} -> + if doc do + [build_doc(doc, indent, true), "Supports all globals plus: ", build_literal(inc), "."] + else + ["Supports all globals plus: ", build_literal(inc), "."] + end + + _ -> + if doc, do: [build_doc(doc, indent, false)], else: [] + end + end + + defp build_attr_doc_and_default(%{doc: doc, opts: opts}, indent) do + case Keyword.fetch(opts, :default) do + {:ok, default} -> + if doc do + [build_doc(doc, indent, true), "Defaults to ", build_literal(default), "."] + else + ["Defaults to ", build_literal(default), "."] + end + + :error -> + if doc, do: [build_doc(doc, indent, false)], else: [] + end + end + + defp build_doc(doc, indent, text_after?) do + doc = String.trim(doc) + [head | tail] = String.split(doc, ["\r\n", "\n"]) + dot = if String.ends_with?(doc, "."), do: [], else: [?.] + + tail = + Enum.map(tail, fn + "" -> "\n" + other -> [?\n, indent | other] + end) + + case tail do + # Single line + [] when text_after? -> + [[head | tail], dot, ?\s] + + [] -> + [[head | tail], dot] + + # Multi-line + _ when text_after? -> + [[head | tail], "\n\n", indent] + + _ -> + [[head | tail], "\n"] + end + end + + defp build_attr_values_or_examples(%{opts: [values: values]}) do + ["Must be one of ", build_literals_list(values, "or"), ?.] + end + + defp build_attr_values_or_examples(%{opts: [examples: examples]}) do + ["Examples include ", build_literals_list(examples, "and"), ?.] + end + + defp build_attr_values_or_examples(_attr) do + [] + end + + defp build_literals_list([literal], _condition) do + [build_literal(literal)] + end + + defp build_literals_list(literals, condition) do + literals + |> Enum.map_intersperse(", ", &build_literal/1) + |> List.insert_at(-2, [condition, " "]) + end + + defp build_literal(literal) do + [?`, inspect(literal, charlists: :as_list), ?`] + end + + defp build_hyphen(%{doc: doc}) when is_binary(doc) do + [" - "] + end + + defp build_hyphen(%{opts: []}) do + [] + end + + defp build_hyphen(%{opts: _opts}) do + [" - "] + end + + defp build_right_doc("") do + [] + end + + defp build_right_doc(right) do + [?\n, right] + end + + defp validate_misplaced_attrs!(attrs, file, message_fun) do + with [%{line: first_attr_line} | _] <- attrs do + compile_error!(first_attr_line, file, message_fun.()) + end + end + + defp validate_misplaced_slots!(slots, file, message_fun) do + with [%{line: first_slot_line} | _] <- slots do + compile_error!(first_slot_line, file, message_fun.()) + end + end + + defp pop_attrs(env) do + slots = Module.delete_attribute(env.module, :__attrs__) || [] + Enum.reverse(slots) + end + + defp pop_slots(env) do + slots = Module.delete_attribute(env.module, :__slots__) || [] + Enum.reverse(slots) + end + + defp raise_if_function_already_defined!(env, name, slots, attrs) do + if Module.defines?(env.module, {name, 1}) do + {:v1, _, meta, _} = Module.get_definition(env.module, {name, 1}) + + with [%{line: first_attr_line} | _] <- attrs do + compile_error!(first_attr_line, env.file, """ + attributes must be defined before the first function clause at line #{meta[:line]} + """) + end + + with [%{line: first_slot_line} | _] <- slots do + compile_error!(first_slot_line, env.file, """ + slots must be defined before the first function clause at line #{meta[:line]} + """) + end + end + end + + # Verification + + @doc false + def __verify__(module, component_calls) do + for %{component: {submod, fun}} = call <- component_calls, + function_exported?(submod, :__components__, 0), + component = submod.__components__()[fun], + do: verify(module, call, component) + + :ok + end + + defp verify( + caller_module, + %{slots: slots, attrs: attrs, root: root} = call, + %{slots: slots_defs, attrs: attrs_defs} = _component + ) do + {attrs, global_attr} = + Enum.reduce(attrs_defs, {attrs, nil}, fn attr_def, {attrs, global_attr} -> + %{name: name, required: required, type: type, opts: opts} = attr_def + attr_values = Keyword.get(opts, :values, nil) + {value, attrs} = Map.pop(attrs, name) + + case {type, value} do + # missing required attr + {_type, nil} when not root and required -> + message = "missing required attribute \"#{name}\" for component #{component_fa(call)}" + warn(message, call.file, call.line) + + # missing optional attr, or dynamic attr + {_type, nil} when root or not required -> + :ok + + # global attrs cannot be directly used + {:global, {line, _column, _type_value}} -> + message = + "global attribute \"#{name}\" in component #{component_fa(call)} may not be provided directly" + + warn(message, call.file, line) + + # attrs must be one of values + {_type, {line, _column, {_, type_value}}} when not is_nil(attr_values) -> + unless type_value in attr_values do + message = + "attribute \"#{name}\" in component #{component_fa(call)} must be one of #{inspect(attr_values)}, got: #{inspect(type_value)}" + + warn(message, call.file, line) + end + + # attrs must be of the declared type + {type, {line, _column, type_value}} -> + if value_ast_to_string = type_mismatch(type, type_value) do + message = + "attribute \"#{name}\" in component #{component_fa(call)} must be #{type_with_article(type)}, got: " <> + value_ast_to_string + + [warn(message, call.file, line)] + end + end + + {attrs, global_attr || (type == :global and attr_def)} + end) + + for {name, {line, _column, _type_value}} <- attrs, + !(global_attr && __global__?(caller_module, Atom.to_string(name), global_attr)) do + message = "undefined attribute \"#{name}\" for component #{component_fa(call)}" + warn(message, call.file, line) + end + + undefined_slots = + Enum.reduce(slots_defs, slots, fn slot_def, slots -> + %{name: slot_name, required: required, attrs: attrs} = slot_def + {slot_values, slots} = Map.pop(slots, slot_name) + + case slot_values do + # missing required slot + nil when required -> + message = "missing required slot \"#{slot_name}\" for component #{component_fa(call)}" + warn(message, call.file, call.line) + + # missing optional slot + nil -> + :ok + + # slot with attributes + _ -> + has_global? = Enum.any?(attrs, &(&1.type == :global)) + slot_attr_defs = Enum.into(attrs, %{}, &{&1.name, &1}) + required_attrs = for {attr_name, %{required: true}} <- slot_attr_defs, do: attr_name + + for %{attrs: slot_attrs, line: slot_line, root: false} <- slot_values, + attr_name <- required_attrs, + not Map.has_key?(slot_attrs, attr_name) do + message = + "missing required attribute \"#{attr_name}\" in slot \"#{slot_name}\" " <> + "for component #{component_fa(call)}" + + warn(message, call.file, slot_line) + end + + for %{attrs: slot_attrs} <- slot_values, + {attr_name, {line, _column, type_value}} <- slot_attrs do + case slot_attr_defs do + # slots cannot accept global attributes + %{^attr_name => %{type: :global}} -> + message = + "global attribute \"#{attr_name}\" in slot \"#{slot_name}\" " <> + "for component #{component_fa(call)} may not be provided directly" + + warn(message, call.file, line) + + # slot attrs must be one of values + %{^attr_name => %{type: _type, opts: [values: attr_values]}} + when is_tuple(type_value) and tuple_size(type_value) == 2 -> + {_, attr_value} = type_value + + unless attr_value in attr_values do + message = + "attribute \"#{attr_name}\" in slot \"#{slot_name}\" " <> + "for component #{component_fa(call)} must be one of #{inspect(attr_values)}, got: " <> + inspect(attr_value) + + warn(message, call.file, line) + end + + # slot attrs must be of the declared type + %{^attr_name => %{type: type}} -> + if value_ast_to_string = type_mismatch(type, type_value) do + message = + "attribute \"#{attr_name}\" in slot \"#{slot_name}\" " <> + "for component #{component_fa(call)} must be #{type_with_article(type)}, got: " <> + value_ast_to_string + + warn(message, call.file, line) + end + + # undefined slot attr + %{} -> + if attr_name == :inner_block or + (has_global? and __global__?(caller_module, Atom.to_string(attr_name))) do + :ok + else + message = + "undefined attribute \"#{attr_name}\" in slot \"#{slot_name}\" " <> + "for component #{component_fa(call)}" + + warn(message, call.file, line) + end + end + end + end + + slots + end) + + for {slot_name, slot_values} <- undefined_slots, + %{line: line} <- slot_values, + not implicit_inner_block?(slot_name, slots_defs) do + message = "undefined slot \"#{slot_name}\" for component #{component_fa(call)}" + warn(message, call.file, line) + end + + :ok + end + + defp implicit_inner_block?(slot_name, slots_defs) do + slot_name == :inner_block and length(slots_defs) > 0 + end + + defp type_mismatch(:any, _type_value), do: nil + defp type_mismatch(_type, :any), do: nil + defp type_mismatch(type, {type, _value}), do: nil + defp type_mismatch(:atom, {:boolean, _value}), do: nil + defp type_mismatch(_type, {_, value}), do: Macro.to_string(value) + + defp component_fa(%{component: {mod, fun}}) do + "#{inspect(mod)}.#{fun}/1" + end + + ## Shared helpers + + defp type_with_article(type) when type in [:atom, :integer], do: "an #{inspect(type)}" + defp type_with_article(type), do: "a #{inspect(type)}" + + # TODO: Provide column information in error messages + defp warn(message, file, line) do + IO.warn(message, file: file, line: line) + end + + defp ensure_used!(module, line, file) do + if !Module.get_attribute(module, :__attrs__) do + compile_error!( + line, + file, + "you must `use Phoenix.Component` to declare attributes. It is currently only imported." + ) + end + end +end diff --git a/lib/phoenix_live_component.ex b/lib/phoenix_live_component.ex index 6e3d1ed53f..13e4580936 100644 --- a/lib/phoenix_live_component.ex +++ b/lib/phoenix_live_component.ex @@ -1,11 +1,11 @@ defmodule Phoenix.LiveComponent do - @moduledoc """ + @moduledoc ~S''' LiveComponents are a mechanism to compartmentalize state, markup, and events in LiveView. - Components are defined by using `Phoenix.LiveComponent` and are used - by calling `Phoenix.LiveView.Helpers.live_component/1` in a parent LiveView. - Components run inside the LiveView process but have their own state and + LiveComponents are defined by using `Phoenix.LiveComponent` and are used + by calling `Phoenix.Component.live_component/1` in a parent LiveView. + They run inside the LiveView process but have their own state and life-cycle. For this reason, they are also often called "stateful components". This is a contrast to `Phoenix.Component`, also known as "function components", which are stateless. @@ -18,34 +18,40 @@ defmodule Phoenix.LiveComponent do use Phoenix.LiveComponent def render(assigns) do - ~H"\"" + ~H"""
<%= @content %>
- "\"" + """ end end - A component can be invoked as: + A LiveComponent is rendered as: <.live_component module={HeroComponent} id="hero" content={@content} /> - A component must receive the `:id` assign as argument, which is - used to uniquely identify the component. A component will be treated - as the same component as long as its `:id` does not change. + You must always pass the `module` and `id` attributes. The `id` will be + available as an assign and it must be used to uniquely identify the + component. All other attributes will be available as assigns inside the + LiveComponent. ## Life-cycle + ### Mount and update + Stateful components are identified by the component module and their ID. - Therefore, two different component modules with the same ID are different - components. This means we can often tie the component ID to some application - based ID: + Therefore, two stateful components with the same module and ID are treated + as the same component. We often tie the component ID to some application based ID: <.live_component module={UserComponent} id={@user.id} user={@user} /> - When [`live_component/1`](`Phoenix.LiveView.Helpers.live_component/1`) is called, + When [`live_component/1`](`Phoenix.Component.live_component/1`) is called, `c:mount/1` is called once, when the component is first added to the page. `c:mount/1` receives the `socket` as argument. Then `c:update/2` is invoked with all of the - assigns given to [`live_component/1`](`Phoenix.LiveView.Helpers.live_component/1`). + assigns given to [`live_component/1`](`Phoenix.Component.live_component/1`). If `c:update/2` is not defined all assigns are simply merged into the socket. + The assigns received as the first argument of the [`update/2`](`c:Phoenix.LiveComponent.update/2`) + callback will only include the _new_ assigns passed from this function. + Pre-existing assigns may be found in `socket.assigns`. + After the component is updated, `c:render/1` is called with all assigns. On first render, we get: @@ -55,24 +61,22 @@ defmodule Phoenix.LiveComponent do update(assigns, socket) -> render(assigns) - Note all stateful components require a single root element in the HTML template - and you will receive a warning otherwise. Furthermore, the given `:id` is not - necessarily used as the DOM ID. If you want to set a DOM ID, it is your - responsibility to do so when rendering: + The given `id` is not automatically used as the DOM ID. If you want to set + a DOM ID, it is your responsibility to do so when rendering: defmodule UserComponent do use Phoenix.LiveComponent def render(assigns) do - ~H"\"" + ~H"""
<%= @user.name %> -
- "\"" + + """ end end - ## Targeting Component Events + ### Events Stateful components can also implement the `c:handle_event/3` callback that works exactly the same as in LiveView. For a client event to @@ -110,15 +114,15 @@ defmodule Phoenix.LiveComponent do Dismiss - ## Preloading and update + ### Preloading and update Stateful components also support an optional `c:preload/1` callback. The `c:preload/1` callback is useful when multiple components of the same type are rendered on the page and you want to preload or augment their data in batches. - For each rendering, the optional `c:preload/1` and `c:update/2` callbacks - are called before `c:render/1`. + Once a LiveView renders a LiveComponent, the optional `c:preload/1` and + `c:update/2` callbacks are called before `c:render/1`. So on first render, the following callbacks will be invoked: @@ -169,17 +173,66 @@ defmodule Phoenix.LiveComponent do Finally, note that `c:preload/1` must return an updated `list_of_assigns`, keeping the assigns in the same order as they were given. + ### Summary + + All of the life-cycle events are summarized in the diagram below. + The bubble events in white are triggers that invoke the component. + In blue you have component callbacks, where the underlined names + represent required callbacks: + + ```mermaid + flowchart LR + *((start)):::event-.->P + WE([wait for parent changes]):::event-.->U + W([wait for events]):::event-.->H + + subgraph w[" "] + + subgraph i[" "] + direction TB + P(preload/1):::callback-->M + M(mount/1):::callback-->U + end + + U(update/2):::callback-->R + + subgraph j[" "] + direction TB + A --> |yes| R + H(handle_event/3):::callback-->A{any changes?}:::diamond + + end + + A --> |no| W + + end + + R(render/1):::callback_req-->W + + classDef event fill:#fff,color:#000,stroke:#000 + classDef diamond fill:#FFFF8C,color:#000,stroke:#000 + classDef callback fill:#66B2FF,color:#000,stroke-width:0 + classDef callback_req fill:#66B2FF,color:#000,stroke-width:0,text-decoration:underline + ``` + ## Slots - LiveComponent can also receive slots, in the same way as a `Phoenix.Component`. - See the docs for `Phoenix.Component` for more information. + LiveComponent can also receive slots, in the same way as a `Phoenix.Component`: + + <.live_component module={MyComponent} id={@data.id} > +
Inner content here
+ + + If the LiveComponent defines an `c:update/2`, be sure that the socket it returns + includes the `:inner_block` assign it received. + + See [the docs](Phoenix.Component.html#module-slots.md) for `Phoenix.Component` for more information. ## Live patches and live redirects - A template rendered inside a component can use `Phoenix.LiveView.Helpers.live_patch/2` - and `Phoenix.LiveView.Helpers.live_redirect/2` calls. The - [`live_patch/2`](`Phoenix.LiveView.Helpers.live_patch/2`) is always handled - by the parent`LiveView`, as components do not provide `handle_params`. + A template rendered inside a component can use `<.link patch={...}>` and + `<.link navigate={...}>`. Patches are always handled by the parent `LiveView`, + as components do not provide `handle_params`. ## Managing state @@ -200,12 +253,12 @@ defmodule Phoenix.LiveComponent do use Phoenix.LiveComponent def render(assigns) do - ~H"\"" + ~H""" <%= @card.title %> ... - "\"" + """ end ... @@ -218,7 +271,7 @@ defmodule Phoenix.LiveComponent do If the board LiveView is the source of truth, it will be responsible for fetching all of the cards in a board. Then it will call - [`live_component/1`](`Phoenix.LiveView.Helpers.live_component/1`) + [`live_component/1`](`Phoenix.Component.live_component/1`) for each card, passing the card struct as argument to `CardComponent`: <%= for card <- @cards do %> @@ -352,11 +405,11 @@ defmodule Phoenix.LiveComponent do use Phoenix.LiveComponent def render(assigns) do - ~H"\"" + ~H""" - "\"" + """ end def handle_event("click", _, socket) do @@ -365,16 +418,14 @@ defmodule Phoenix.LiveComponent do end end - Instead, it is much simpler to create a function: + Instead, it is much simpler to create a function component: - def my_button(text, click) do - assigns = %{text: text, click: click} - - ~H"\"" + def my_button(%{text: _, click: _} = assigns) do + ~H""" - "\"" + """ end If you keep components mostly as an application concern with @@ -383,40 +434,10 @@ defmodule Phoenix.LiveComponent do ## Limitations - ### Components require at least one HTML tag - - Components must only contain HTML tags at their root. At least one HTML - tag must be present. It is not possible to have components that render - only text or text mixed with tags at the root. - - ### Change tracking requirement - - Another limitation of components is that they must always be change - tracked. For example, if you render a component inside `content_tag`, like - this: - - <%= content_tag :div, @div_attrs do %> - <%= live_component SomeComponent, id: :example %> - <% end %> - - The component ends up enclosed by the `content_tag`, where LiveView - cannot track it. In such cases, you may receive an error such as: - - ** (ArgumentError) cannot convert component SomeComponent to HTML. - A component must always be returned directly as part of a LiveView template - - Luckily, there is little reason to use `content_tag` inside HEEx templates. - So instead you can do: + ### Live Components require a single HTML tag at the root -
- <%= live_component SomeComponent, id: :example %> -
- - They also work inside any function component, such as `form`: - - <.form let={f} for={@changeset} url="#"> - <%= live_component FormComponent, id: :form %> - + Live Components require a single HTML tag at the root. It is not possible + to have components that render only text or multiple tags. ### SVG support @@ -438,7 +459,7 @@ defmodule Phoenix.LiveComponent do `` tags to be nested, you can wrap the component content into an `` tag. This will ensure that it is correctly interpreted by the browser. - """ + ''' defmodule CID do @moduledoc """ @@ -461,16 +482,27 @@ defmodule Phoenix.LiveComponent do alias Phoenix.LiveView.Socket - defmacro __using__(_) do + @doc """ + Uses LiveComponent in the current module. + + use Phoenix.LiveComponent + + ## Options + + * `:global_prefixes` - the global prefixes to use for components. See + `Global Attributes` in `Phoenix.Component` for more information. + """ + defmacro __using__(opts \\ []) do quote do + import Phoenix.LiveView @behaviour Phoenix.LiveComponent - use Phoenix.Component - - require Phoenix.LiveView.Renderer @before_compile Phoenix.LiveView.Renderer + # Phoenix.Component must come last so its @before_compile runs last + use Phoenix.Component, Keyword.take(unquote(opts), [:global_prefixes]) + @doc false - def __live__, do: %{kind: :component, module: __MODULE__} + def __live__, do: %{kind: :component, module: __MODULE__, layout: false} end end diff --git a/lib/phoenix_live_view.ex b/lib/phoenix_live_view.ex index 0385731208..60cc55e344 100644 --- a/lib/phoenix_live_view.ex +++ b/lib/phoenix_live_view.ex @@ -14,12 +14,10 @@ defmodule Phoenix.LiveView do work of tracking changes and sending the relevant diffs to the browser. - At the end of the day, a LiveView is nothing more than a - process that receives events as messages and updates its - state. The state itself is nothing more than functional - and immutable Elixir data structures. The events are either - internal application messages (usually emitted by `Phoenix.PubSub`) - or sent by the client/browser. + A LiveView is just a process that receives events as messages and updates + its state. The state itself is nothing more than functional and immutable + Elixir data structures. The events are either internal application messages + (usually emitted by `Phoenix.PubSub`) or sent by the client/browser. LiveView is first rendered statically as part of regular HTTP requests, which provides quick times for "First Meaningful @@ -31,36 +29,6 @@ defmodule Phoenix.LiveView do and encode data on every request. The flipside is that LiveView uses more memory on the server compared to stateless requests. - ## Use cases - - There are many use cases where LiveView is an excellent - fit right now: - - * Handling of user interaction and inputs, buttons, and - forms - such as input validation, dynamic forms, - autocomplete, etc; - - * Events and updates pushed by server - such as - notifications, dashboards, etc; - - * Page and data navigation - such as navigating between - pages, pagination, etc can be built with LiveView - using the excellent live navigation feature set. - This reduces the amount of data sent over the wire, - gives developers full control over the LiveView - life-cycle, while controlling how the browser - tracks those changes in state; - - There are also use cases which are a bad fit for LiveView: - - * Animations - animations, menus, and general UI events - that do not need the server in the first place are a - bad fit for LiveView. Those can be achieved without - LiveView in multiple ways, such as with CSS and CSS - transitions, using LiveView hooks, or even integrating - with UI toolkits designed for this purpose, such as - Bootstrap, Alpine.JS, and similar. - ## Life-cycle A LiveView begins as a regular HTTP request and HTML response, @@ -69,43 +37,50 @@ defmodule Phoenix.LiveView do Any time a stateful view changes or updates its socket assigns, it is automatically re-rendered and the updates are pushed to the client. + Socket assigns are stateful values kept on the server side in + `Phoenix.LiveView.Socket`. This is different from the common stateless + HTTP pattern of sending the connection state to the client in the form + of a token or cookie and rebuilding the state on the server to service + every request. + You begin by rendering a LiveView typically from your router. When LiveView is first rendered, the `c:mount/3` callback is invoked with the current params, the current session and the LiveView socket. As in a regular request, `params` contains public data that can be modified by the user. The `session` always contains private data set by the application itself. The `c:mount/3` callback wires up socket - assigns necessary for rendering the view. After mounting, `c:render/1` + assigns necessary for rendering the view. After mounting, `c:handle_params/3` + is invoked so uri and query params are handled. Finally, `c:render/1` is invoked and the HTML is sent as a regular HTML response to the client. After rendering the static page, LiveView connects from the client to the server where stateful views are spawned to push rendered updates to the browser, and receive client events via `phx-` bindings. Just like - the first rendering, `c:mount/3` is invoked with params, session, - and socket state, where mount assigns values for rendering. However - in the connected client case, a LiveView process is spawned on - the server, pushes the result of `c:render/1` to the client and - continues on for the duration of the connection. If at any point - during the stateful life-cycle a crash is encountered, or the client - connection drops, the client gracefully reconnects to the server, - calling `c:mount/3` once again. + the first rendering, `c:mount/3`, is invoked with params, session, + and socket state. However in the connected client case, a LiveView process + is spawned on the server, runs `c:handle_params/3` again and then pushes + the result of `c:render/1` to the client and continues on for the duration + of the connection. If at any point during the stateful life-cycle a crash + is encountered, or the client connection drops, the client gracefully + reconnects to the server, calling `c:mount/3` and `c:handle_params/3` again. + + LiveView also allows attaching hooks to specific life-cycle stages with + `attach_hook/4`. ## Example Before writing your first example, make sure that Phoenix LiveView - is properly installed. If you are just getting started, this can - be easily done by running `mix phx.new my_app --live`. The `phx.new` - command with the `--live` flag will create a new project with - LiveView installed and configured. Otherwise, please follow the steps - in the [installation guide](installation.md) before continuing. + is properly installed. All applications generated with Phoenix v1.6 + and later come with LiveView installed and configured. For previously + existing projects, please follow the steps in the + [installation guide](installation.md) before continuing. A LiveView is a simple module that requires two callbacks: `c:mount/3` and `c:render/1`: defmodule MyAppWeb.ThermostatLive do - # If you generated an app with mix phx.new --live, - # the line below would be: use MyAppWeb, :live_view + # In Phoenix v1.6+ apps, the line below should be: use MyAppWeb, :live_view use Phoenix.LiveView def render(assigns) do @@ -125,7 +100,8 @@ defmodule Phoenix.LiveView do template, which stands for HTML+EEx. They are an extension of Elixir's builtin EEx templates, with support for HTML validation, syntax-based components, smart change tracking, and more. You can learn more about - the template syntax in `Phoenix.LiveView.Helpers.sigil_H/2`. + the template syntax in `Phoenix.Component.sigil_H/2` (note + `Phoenix.Component` is automatically imported when you use `Phoenix.LiveView`). Next, decide where you want to use your LiveView. @@ -142,38 +118,18 @@ defmodule Phoenix.LiveView do *Note:* the above assumes there is `plug :put_root_layout` call in your router that configures the LiveView layout. This call is - automatically included by `mix phx.new --live` and described in - the installation guide. If you don't want to configure a root layout, - you must pass `layout: {MyAppWeb.LayoutView, "app.html"}` as an - option to the `Phoenix.LiveView.Router.live/3` macro above. + automatically included in Phoenix v1.6 apps and described in + [the installation guide](installation.md#layouts). Alternatively, you can `live_render` from any template. In your view: - import Phoenix.LiveView.Helpers + import Phoenix.Component Then in your template:

Temperature Control

<%= live_render(@conn, MyAppWeb.ThermostatLive) %> - When a LiveView is rendered, all of the data currently stored in the - connection session (see `Plug.Conn.get_session/1`) will be given to - the LiveView. - - It is also possible to pass additional session information to the LiveView - through a `:session` option: - - # In the router - live "/thermostat", ThermostatLive, session: %{"extra_token" => "foo"} - - # In a view - <%= live_render(@conn, MyAppWeb.ThermostatLive, session: %{"extra_token" => "foo"}) %> - - Notice the `:session` uses string keys as a reminder that session data - is serialized and sent to the client. So you should always keep the data - in the session to a minimum. For example, instead of storing a User struct, - you should store the "user_id" and load the User when the LiveView mounts. - Once the LiveView is rendered, a regular HTML response is sent. In your app.js file, you should find the following: @@ -239,17 +195,6 @@ defmodule Phoenix.LiveView do `c:render/1` definition above and instead put the template code at `lib/my_app_web/live/thermostat_live.html.heex`. - Alternatively, you can keep the `c:render/1` callback but delegate to an - existing `Phoenix.View` module in your application. For example: - - defmodule MyAppWeb.ThermostatLive do - use Phoenix.LiveView - - def render(assigns) do - Phoenix.View.render(MyAppWeb.PageView, "page.html", assigns) - end - end - In all cases, each assign in the template will be accessible as `@assign`. You can learn more about [assigns and HEEx templates in their own guide](assigns-eex.md). @@ -268,16 +213,11 @@ defmodule Phoenix.LiveView do {:noreply, assign(socket, :temperature, new_temp)} end - | Binding | Attributes | - |------------------------|------------| - | [Params](bindings.md#click-events) | `phx-value-*` | - | [Click Events](bindings.md#click-events) | `phx-click`, `phx-capture-click` | - | [Focus/Blur Events](bindings.md#focus-and-blur-events) | `phx-blur`, `phx-focus`, `phx-window-blur`, `phx-window-focus` | - | [Key Events](bindings.md#key-events) | `phx-keydown`, `phx-keyup`, `phx-window-keydown`, `phx-window-keyup`, `phx-key` | - | [Form Events](form-bindings.md) | `phx-change`, `phx-submit`, `phx-feedback-for`, `phx-disable-with`, `phx-trigger-action`, `phx-auto-recover` | - | [Rate Limiting](bindings.md#rate-limiting-events-with-debounce-and-throttle) | `phx-debounce`, `phx-throttle` | - | [DOM Patching](dom-patching.md) | `phx-update` | - | [JS Interop](js-interop.md#client-hooks) | `phx-hook` | + To update UI state, for example, to open and close dropdowns, switch tabs, + etc, LiveView also supports JS commands (`Phoenix.LiveView.JS`), which + execute directly on the client without reaching the server. To learn more, + see [our bindings page](bindings.md) for a complete list of all LiveView + bindings as well as our [JavaScript interoperability guide](js-interop.md). ## Compartmentalize state, markup, and events in LiveView @@ -304,7 +244,7 @@ defmodule Phoenix.LiveView do Perhaps you want to move part of the state or part of the events in your LiveView to a separate module. For these cases, LiveView provides `Phoenix.LiveComponent`, which are rendered using - [`live_component/1`](`Phoenix.LiveView.Helpers.live_component/1`): + [`live_component/1`](`Phoenix.Component.live_component/1`): <.live_component module={UserComponent} id={user.id} user={user} /> @@ -316,14 +256,15 @@ defmodule Phoenix.LiveView do Finally, if you want complete isolation between parts of a LiveView, you can always render a LiveView inside another LiveView by calling - [`live_render/3`](`Phoenix.LiveView.Helpers.live_render/3`). This child LiveView + [`live_render/3`](`Phoenix.Component.live_render/3`). This child LiveView runs in a separate process than the parent, with its own callbacks. If a child LiveView crashes, it won't affect the parent. If the parent crashes, all children are terminated. When rendering a child LiveView, the `:id` option is required to uniquely identify the child. A child LiveView will only ever be rendered and mounted - a single time, provided its ID remains unchanged. + a single time, provided its ID remains unchanged. To force a child to re-mount + with new session data, a new ID must be provided. Given that a LiveView runs on its own process, it is an excellent tool for creating completely isolated UI elements, but it is a slightly expensive abstraction if @@ -351,7 +292,7 @@ defmodule Phoenix.LiveView do LiveView has many guides to help you on your journey. - ## Server-side + ### Server-side These guides focus on server-side functionality: @@ -364,7 +305,7 @@ defmodule Phoenix.LiveView do * [Uploads](uploads.md) * [Using Gettext for internationalization](using-gettext.md) - ## Client-side + ### Client-side These guides focus on LiveView bindings and client-side integration: @@ -375,7 +316,7 @@ defmodule Phoenix.LiveView do * [Uploads (External)](uploads-external.md) ''' - alias Phoenix.LiveView.{Socket, Route} + alias Phoenix.LiveView.{Socket, LiveStream} @type unsigned_params :: map @@ -406,32 +347,97 @@ defmodule Phoenix.LiveView do """ @callback mount( - unsigned_params() | :not_mounted_at_router, + params :: unsigned_params() | :not_mounted_at_router, session :: map, socket :: Socket.t() ) :: {:ok, Socket.t()} | {:ok, Socket.t(), keyword()} + @doc """ + Renders a template. + + This callback is invoked whenever LiveView detects + new content must be rendered and sent to the client. + + If you define this function, it must return a template + defined via the `Phoenix.Component.sigil_H/2`. + + If you don't define this function, LiveView will attempt + to render a template in the same directory as your LiveView. + For example, if you have a LiveView named `MyApp.MyCustomView` + inside `lib/my_app/live_views/my_custom_view.ex`, Phoenix + will look for a template at `lib/my_app/live_views/my_custom_view.html.heex`. + """ @callback render(assigns :: Socket.assigns()) :: Phoenix.LiveView.Rendered.t() + @doc """ + Invoked when the LiveView is terminating. + + In case of errors, this callback is only invoked if the LiveView + is trapping exits. See `c:GenServer.terminate/2` for more info. + """ @callback terminate(reason, socket :: Socket.t()) :: term when reason: :normal | :shutdown | {:shutdown, :left | :closed | term} + @doc """ + Invoked after mount and whenever there is a live patch event. + + It receives the current `params`, including parameters from + the router, the current `uri` from the client and the `socket`. + It is invoked after mount or whenever there is a live navigation + event caused by `push_patch/2` or `<.link patch={...}>`. + + It must always return `{:noreply, socket}`, where `:noreply` + means no additional information is sent to the client. + """ @callback handle_params(unsigned_params(), uri :: String.t(), socket :: Socket.t()) :: {:noreply, Socket.t()} + @doc """ + Invoked to handle events sent by the client. + + It receives the `event` name, the event payload as a map, + and the socket. + + It must return `{:noreply, socket}`, where `:noreply` means + no additional information is sent to the client, or + `{:reply, map(), socket}`, where the given `map()` is encoded + and sent as a reply to the client. + """ @callback handle_event(event :: binary, unsigned_params(), socket :: Socket.t()) :: {:noreply, Socket.t()} | {:reply, map, Socket.t()} + @doc """ + Invoked to handle calls from other Elixir processes. + + See `GenServer.call/3` and `c:GenServer.handle_call/3` + for more information. + """ @callback handle_call(msg :: term, {pid, reference}, socket :: Socket.t()) :: {:noreply, Socket.t()} | {:reply, term, Socket.t()} - @callback handle_info(msg :: term, socket :: Socket.t()) :: - {:noreply, Socket.t()} + @doc """ + Invoked to handle casts from other Elixir processes. + See `GenServer.cast/2` and `c:GenServer.handle_cast/2` + for more information. It must always return `{:noreply, socket}`, + where `:noreply` means no additional information is sent + to the process which cast the message. + """ @callback handle_cast(msg :: term, socket :: Socket.t()) :: {:noreply, Socket.t()} + @doc """ + Invoked to handle messages from other Elixir processes. + + See `Kernel.send/2` and `c:GenServer.handle_info/2` + for more information. It must always return `{:noreply, socket}`, + where `:noreply` means no additional information is sent + to the process which sent the message. + """ + @callback handle_info(msg :: term, socket :: Socket.t()) :: + {:noreply, Socket.t()} + @optional_callbacks mount: 3, terminate: 2, handle_params: 3, @@ -446,14 +452,17 @@ defmodule Phoenix.LiveView do use Phoenix.LiveView, namespace: MyAppWeb, container: {:tr, class: "colorized"}, - layout: {MyAppWeb.LayoutView, "live.html"} + layout: {MyAppWeb.LayoutView, :app}, + log: :info ## Options * `:namespace` - configures the namespace the `LiveView` is in * `:container` - configures the container the `LiveView` will be wrapped in * `:layout` - configures the layout the `LiveView` will be rendered in - + * `:log` - configures the log level for the `LiveView` + * `:global_prefixes` - the global prefixes to use for components. See + `Global Attributes` in `Phoenix.Component` for more information. """ defmacro __using__(opts) do # Expand layout if possible to avoid compile-time dependencies @@ -467,15 +476,16 @@ defmodule Phoenix.LiveView do end quote bind_quoted: [opts: opts] do + import Phoenix.LiveView @behaviour Phoenix.LiveView - use Phoenix.Component - - require Phoenix.LiveView.Renderer @before_compile Phoenix.LiveView.Renderer @phoenix_live_opts opts Module.register_attribute(__MODULE__, :phoenix_live_mount, accumulate: true) @before_compile Phoenix.LiveView + + # Phoenix.Component must come last so its @before_compile runs last + use Phoenix.Component, Keyword.take(opts, [:global_prefixes]) end end @@ -483,17 +493,14 @@ defmodule Phoenix.LiveView do opts = Module.get_attribute(env.module, :phoenix_live_opts) layout = - case opts[:layout] do - {mod, template} when is_atom(mod) and is_binary(template) -> - {mod, template} - - nil -> - nil - - other -> - raise ArgumentError, - ":layout expects a tuple of the form {MyLayoutView, \"my_template.html\"}, " <> - "got: #{inspect(other)}" + Phoenix.LiveView.Utils.normalize_layout(Keyword.get(opts, :layout, false), "use options") + + log = + case Keyword.fetch(opts, :log) do + {:ok, false} -> false + {:ok, log} when is_atom(log) -> log + :error -> :debug + _ -> raise ArgumentError, ":log expects an atom or false, got: #{inspect(opts[:log])}" end phoenix_live_mount = Module.get_attribute(env.module, :phoenix_live_mount) @@ -511,7 +518,8 @@ defmodule Phoenix.LiveView do kind: :view, module: env.module, layout: layout, - lifecycle: lifecycle + lifecycle: lifecycle, + log: log } quote do @@ -535,11 +543,11 @@ defmodule Phoenix.LiveView do multiple modules. Instead, pass a tuple and use pattern matching to handle different cases: - def on_mount(:admin, _params, _session, _socket) do + def on_mount(:admin, _params, _session, socket) do {:cont, socket} end - def on_mount(:user, _params, _session, _socket) do + def on_mount(:user, _params, _session, socket) do {:cont, socket} end @@ -562,15 +570,18 @@ defmodule Phoenix.LiveView do Ensures common `assigns` are applied to all LiveViews attaching this hook. "\"" import Phoenix.LiveView + import Phoenix.Component def on_mount(:default, _params, _session, socket) do {:cont, assign(socket, :page_title, "DemoWeb")} end - def on_mount(:user, _params, _session, socket) do + def on_mount(:user, params, session, socket) do + # code end - def on_mount(:admin, _params, _session, socket) do + def on_mount(:admin, params, session, socket) do + # code end end @@ -585,6 +596,7 @@ defmodule Phoenix.LiveView do pipe_through :browser live "/", PageLive, :index end + end live_session :authenticated, on_mount: {MyAppWeb.InitAssigns, :user} do scope "/", MyAppWeb do @@ -653,204 +665,13 @@ defmodule Phoenix.LiveView do """ def connected?(%Socket{transport_pid: transport_pid}), do: transport_pid != nil - @doc """ - Assigns the given `key` with value from `fun` into `socket_or_assigns` if - one does not yet exist. - - The first argument is either a LiveView `socket` or an `assigns` map from - function components. - - Useful for lazily assigning values and referencing parent assigns. - - ## Referencing parent assigns - - When a LiveView is mounted in a disconnected state, the `Plug.Conn` assigns - will be available for reference via `assign_new/3`, allowing assigns to - be shared for the initial HTTP request. The `Plug.Conn` assigns will not be - available during the connected mount. Likewise, nested LiveView children have - access to their parent's assigns on mount using `assign_new/3`, which allows - assigns to be shared down the nested LiveView tree. - - ## Examples - - # controller - conn - |> assign(:current_user, user) - |> LiveView.Controller.live_render(MyLive, session: %{"user_id" => user.id}) - - # LiveView mount - def mount(_params, %{"user_id" => user_id}, socket) do - {:ok, assign_new(socket, :current_user, fn -> Accounts.get_user!(user_id) end)} - end - - """ - def assign_new(socket_or_assigns, key, fun) - - def assign_new(%Socket{} = socket, key, fun) when is_function(fun, 0) do - validate_assign_key!(key) - - case socket do - %{assigns: %{^key => _}} -> - socket - - %{private: %{assign_new: {assigns, keys}}} -> - # It is important to store the keys even if they are not in assigns - # because maybe the controller doesn't have it but the view does. - socket = put_in(socket.private.assign_new, {assigns, [key | keys]}) - Phoenix.LiveView.Utils.force_assign(socket, key, Map.get_lazy(assigns, key, fun)) - - %{} -> - Phoenix.LiveView.Utils.force_assign(socket, key, fun.()) - end - end - - def assign_new(%{__changed__: changed} = assigns, key, fun) when is_function(fun, 0) do - case assigns do - %{^key => _} -> assigns - %{} -> Phoenix.LiveView.Utils.force_assign(assigns, changed, key, fun.()) - end - end - - def assign_new(assigns, _key, fun) when is_function(fun, 0) do - raise ArgumentError, - "assign_new/3 expects a socket or an assigns map from a function component as first argument, got: " <> - inspect(assigns) - end - - @doc """ - Adds a `key`-`value` pair to `socket_or_assigns`. - - The first argument is either a LiveView `socket` or an - `assigns` map from function components. - - ## Examples - - iex> assign(socket, :name, "Elixir") - - """ - def assign(socket_or_assigns, key, value) - - def assign(%Socket{} = socket, key, value) do - validate_assign_key!(key) - Phoenix.LiveView.Utils.assign(socket, key, value) - end - - def assign(%{__changed__: changed} = assigns, key, value) do - case assigns do - %{^key => ^value} -> - assigns - - %{} -> - Phoenix.LiveView.Utils.force_assign(assigns, changed, key, value) - end - end - - def assign(assigns, _key, _val) do - raise ArgumentError, - "assign/3 expects a socket or an assigns map from a function component as first argument, got: " <> - inspect(assigns) - end - - @doc """ - Adds key-value pairs to assigns. - - The first argument is either a LiveView `socket` or an - `assigns` map from function components. - - A keyword list or a map of assigns must be given as argument - to be merged into existing assigns. - - ## Examples - - iex> assign(socket, name: "Elixir", logo: "💧") - iex> assign(socket, %{name: "Elixir"}) - - """ - def assign(socket_or_assigns, keyword_or_map) - when is_map(keyword_or_map) or is_list(keyword_or_map) do - Enum.reduce(keyword_or_map, socket_or_assigns, fn {key, value}, acc -> - assign(acc, key, value) - end) - end - - defp validate_assign_key!(:flash) do - raise ArgumentError, - ":flash is a reserved assign by LiveView and it cannot be set directly. " <> - "Use the appropriate flash functions instead." - end - - defp validate_assign_key!(_key), do: :ok - - @doc """ - Updates an existing `key` with `fun` in the given `socket_or_assigns`. - - The first argument is either a LiveView `socket` or an - `assigns` map from function components. - - The update function receives the current key's value and - returns the updated value. Raises if the key does not exist. - - ## Examples - - iex> update(socket, :count, fn count -> count + 1 end) - iex> update(socket, :count, &(&1 + 1)) - """ - def update(socket_or_assigns, key, fun) - - def update(%Socket{assigns: assigns} = socket, key, fun) when is_function(fun, 1) do - case assigns do - %{^key => val} -> assign(socket, key, fun.(val)) - %{} -> raise KeyError, key: key, term: assigns - end - end - - def update(assigns, key, fun) when is_function(fun, 1) do - case assigns do - %{^key => val} -> assign(assigns, key, fun.(val)) - %{} -> raise KeyError, key: key, term: assigns - end - end - - def update(assigns, _key, fun) when is_function(fun, 1) do - raise ArgumentError, - "update/3 expects a socket or an assigns map from a function component as first argument, got: " <> - inspect(assigns) - end - - @doc """ - Checks if the given key changed in `socket_or_assigns`. - - The first argument is either a LiveView `socket` or an - `assigns` map from function components. - - ## Examples - - iex> changed?(socket, :count) - - """ - def changed?(socket_or_assigns, key) - - def changed?(%Socket{assigns: assigns}, key) do - Phoenix.LiveView.Utils.changed?(assigns, key) - end - - def changed?(%{__changed__: _} = assigns, key) do - Phoenix.LiveView.Utils.changed?(assigns, key) - end - - def changed?(assigns, _key) do - raise ArgumentError, - "changed?/2 expects a socket or an assigns map from a function component as first argument, got: " <> - inspect(assigns) - end - @doc """ Adds a flash message to the socket to be displayed. *Note*: While you can use `put_flash/3` inside a `Phoenix.LiveComponent`, components have their own `@flash` assigns. The `@flash` assign in a component is only copied to its parent LiveView if the component - calls `push_redirect/2` or `push_patch/2`. + calls `push_navigate/2` or `push_patch/2`. *Note*: You must also place the `Phoenix.LiveView.Router.fetch_live_flash/2` plug in your browser's pipeline in place of `fetch_flash` for LiveView flash @@ -889,15 +710,44 @@ defmodule Phoenix.LiveView do defdelegate clear_flash(socket, key), to: Phoenix.LiveView.Utils @doc """ - Pushes an event to the client to be consumed by hooks. + Pushes an event to the client. - *Note*: events will be dispatched to all active hooks on the client who are - handling the given `event`. Scoped events can be achieved by namespacing - your event names. + Events can be handled in two ways: - ## Examples + 1. They can be handled on `window` via `addEventListener`. + A "phx:" prefix will be added to the event name. + + 2. They can be handled inside a hook via `handleEvent`. + + Note that events are dispatched to all active hooks on the client who are + handling the given `event`. If you need to scope events, then this must + be done by namespacing them. + + ## Hook example + + If you push a "scores" event from your LiveView: {:noreply, push_event(socket, "scores", %{points: 100, user: "josé"})} + + A hook declared via `phx-hook` can handle it via `handleEvent`: + + this.handleEvent("scores", data => ...) + + ## `window` example + + All events are also dispatched on the `window`. This means you can handle + them by adding listeners. For example, if you want to remove an element + from the page, you can do this: + + {:noreply, push_event(socket, "remove-el", %{id: "foo-bar"})} + + And now in your app.js you can register and handle it: + + window.addEventListener( + "phx:remove-el", + e => document.getElementById(e.detail.id).remove() + ) + """ defdelegate push_event(socket, event, payload), to: Phoenix.LiveView.Utils @@ -945,7 +795,7 @@ defmodule Phoenix.LiveView do if entry.done? do uploaded_file = consume_uploaded_entry(socket, entry, fn %{} = meta -> - ... + {:ok, ...} end) {:noreply, put_flash(socket, :info, "file #{uploaded_file.name} uploaded")} @@ -1005,6 +855,11 @@ defmodule Phoenix.LiveView do it is guaranteed that all entries have completed before the submit event is invoked. Once entries are consumed, they are removed from the upload. + The function passed to consume may return a tagged tuple of the form + `{:ok, my_result}` to collect results about the consumed entries, or + `{:postpone, my_result}` to collect results, but postpone the file + consumption to be performed later. + ## Examples def handle_event("save", _params, socket) do @@ -1012,7 +867,7 @@ defmodule Phoenix.LiveView do consume_uploaded_entries(socket, :avatar, fn %{path: path}, _entry -> dest = Path.join("priv/static/uploads", Path.basename(path)) File.cp!(path, dest) - Routes.static_path(socket, "/uploads/#{Path.basename(dest)}") + {:ok, Routes.static_path(socket, "/uploads/#{Path.basename(dest)}")} end) {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))} end @@ -1030,6 +885,11 @@ defmodule Phoenix.LiveView do This is a lower-level feature than `consume_uploaded_entries/3` and useful for scenarios where you want to consume entries as they are individually completed. + Like `consume_uploaded_entries/3`, the function passed to consume may return + a tagged tuple of the form `{:ok, my_result}` to collect results about the + consumed entries, or `{:postpone, my_result}` to collect results, + but postpone the file consumption to be performed later. + ## Examples def handle_event("save", _params, socket) do @@ -1039,7 +899,7 @@ defmodule Phoenix.LiveView do consume_uploaded_entry(socket, entry, fn %{path: path} -> dest = Path.join("priv/static/uploads", Path.basename(path)) File.cp!(path, dest) - Routes.static_path(socket, "/uploads/#{Path.basename(dest)}") + {:ok, Routes.static_path(socket, "/uploads/#{Path.basename(dest)}")} end) end {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))} @@ -1062,15 +922,29 @@ defmodule Phoenix.LiveView do ## Options * `:to` - the path to redirect to. It must always be a local path - * `:external` - an external path to redirect to + * `:external` - an external path to redirect to. Either a string + or `{scheme, url}` to redirect to a custom scheme """ + def redirect(socket, opts \\ []) + def redirect(%Socket{} = socket, to: url) do validate_local_url!(url, "redirect/2") put_redirect(socket, {:redirect, %{to: url}}) end def redirect(%Socket{} = socket, external: url) do - put_redirect(socket, {:redirect, %{external: url}}) + case url do + {scheme, rest} -> + put_redirect(socket, {:redirect, %{external: "#{scheme}:#{rest}"}}) + + url when is_binary(url) -> + external_url = Phoenix.LiveView.Utils.valid_string_destination!(url, "redirect/2") + put_redirect(socket, {:redirect, %{external: external_url}}) + + other -> + raise ArgumentError, + "expected :external option in redirect/2 to be valid URL, got: #{inspect(other)}" + end end def redirect(%Socket{}, _) do @@ -1084,7 +958,7 @@ defmodule Phoenix.LiveView do immediately invoked to handle the change of params and URL state. Then the new state is pushed to the client, without reloading the whole page while also maintaining the current scroll position. - For live redirects to another LiveView, use `push_redirect/2`. + For live navigation to another LiveView, use `push_navigate/2`. ## Options @@ -1099,17 +973,34 @@ defmodule Phoenix.LiveView do """ def push_patch(%Socket{} = socket, opts) do - %{to: to} = opts = push_opts!(opts, "push_patch/2") + opts = push_opts!(opts, "push_patch/2") + put_redirect(socket, {:live, :patch, opts}) + end - case Route.live_link_info!(socket, socket.private.root_view, to) do - {:internal, %Route{params: params, action: action}} -> - put_redirect(socket, {:live, {params, action}, opts}) + @doc """ + Annotates the socket for navigation to another LiveView. - {:external, _uri} -> - raise ArgumentError, - "cannot push_patch/2 to #{inspect(to)} because the given path " <> - "does not point to the current root view #{inspect(socket.private.root_view)}" - end + The current LiveView will be shutdown and a new one will be mounted + in its place, without reloading the whole page. This can + also be used to remount the same LiveView, in case you want to start + fresh. If you want to navigate to the same LiveView without remounting + it, use `push_patch/2` instead. + + ## Options + + * `:to` - the required path to link to. It must always be a local path + * `:replace` - the flag to replace the current history or push a new state. + Defaults `false`. + + ## Examples + + {:noreply, push_navigate(socket, to: "/")} + {:noreply, push_navigate(socket, to: "/", replace: true)} + + """ + def push_navigate(%Socket{} = socket, opts) do + opts = push_opts!(opts, "push_navigate/2") + put_redirect(socket, {:live, :redirect, opts}) end @doc """ @@ -1133,6 +1024,8 @@ defmodule Phoenix.LiveView do {:noreply, push_redirect(socket, to: "/", replace: true)} """ + @doc deprecated: "Use push_navigate/2 instead" + # Deprecate in 0.19 def push_redirect(%Socket{} = socket, opts) do opts = push_opts!(opts, "push_redirect/2") put_redirect(socket, {:live, :redirect, opts}) @@ -1194,6 +1087,8 @@ defmodule Phoenix.LiveView do * `"_track_static"` - set automatically with a list of all href/src from tags with the `phx-track-static` annotation in them. If there are no such tags, nothing is sent + * `"_live_referer"` - sent by the client as the referer URL when a + live navigation has occurred from `push_navigate` or client link navigate. ## Examples @@ -1205,43 +1100,90 @@ defmodule Phoenix.LiveView do if connect_params = private[:connect_params] do if connected?(socket), do: connect_params, else: nil else - raise_connect_only!(socket, "connect_params") + raise_root_and_mount_only!(socket, "connect_params") + end + end + + @deprecated "use get_connect_info/2 instead" + def get_connect_info(%Socket{private: private} = socket) do + if connect_info = private[:connect_info] do + if connected?(socket), do: connect_info, else: nil + else + raise_root_and_mount_only!(socket, "connect_info") end end @doc """ - Accesses the connect info from the socket to use on connected mount. + Accesses a given connect info key from the socket. - Connect info are only sent when the client connects to the server and - only remain available during mount. `nil` is returned when called in a - disconnected state and a `RuntimeError` is raised if called after mount. + The following keys are supported: `:peer_data`, `:trace_context_headers`, + `:x_headers`, `:uri`, and `:user_agent`. + + The connect information is available only during mount. During disconnected + render, all keys are available. On connected render, only the keys explicitly + declared in your socket are available. See `Phoenix.Endpoint.socket/3` for + a complete description of the keys. ## Examples - First, when invoking the LiveView socket, you need to declare the - `connect_info` you want to receive. Typically, it includes at least - the session but it may include other keys, such as `:peer_data`. - See `Phoenix.Endpoint.socket/3`: + The first step is to declare the `connect_info` you want to receive. + Typically, it includes at least the session, but you must include all + other keys you want to access on connected mount, such as `:peer_data`: socket "/live", Phoenix.LiveView.Socket, websocket: [connect_info: [:peer_data, session: @session_options]] Those values can now be accessed on the connected mount as - `get_connect_info/1`: + `get_connect_info/2`: def mount(_params, _session, socket) do - if info = get_connect_info(socket) do - {:ok, assign(socket, ip: info.peer_data.address)} - else - {:ok, assign(socket, ip: nil)} - end + peer_data = get_connect_info(socket, :peer_data) + {:ok, assign(socket, ip: peer_data.address)} end + + If the key is not available, usually because it was not specified + in `connect_info`, it returns nil. """ - def get_connect_info(%Socket{private: private} = socket) do + def get_connect_info(%Socket{private: private} = socket, key) when is_atom(key) do if connect_info = private[:connect_info] do - if connected?(socket), do: connect_info, else: nil + case connect_info do + %Plug.Conn{} -> conn_connect_info(connect_info, key) + %{} -> connect_info[key] + end else - raise_connect_only!(socket, "connect_info") + raise_root_and_mount_only!(socket, "connect_info") + end + end + + defp conn_connect_info(conn, :peer_data) do + Plug.Conn.get_peer_data(conn) + end + + defp conn_connect_info(conn, :x_headers) do + for {header, _} = pair <- conn.req_headers, + String.starts_with?(header, "x-"), + do: pair + end + + defp conn_connect_info(conn, :trace_context_headers) do + for {header, _} = pair <- conn.req_headers, + header in ["traceparent", "tracestate"], + do: pair + end + + defp conn_connect_info(conn, :uri) do + %URI{ + scheme: to_string(conn.scheme), + query: conn.query_string, + port: conn.port, + host: conn.host, + path: conn.request_path + } + end + + defp conn_connect_info(conn, :user_agent) do + with {_, value} <- List.keyfind(conn.req_headers, "user-agent", 0) do + value end end @@ -1301,7 +1243,7 @@ defmodule Phoenix.LiveView do endpoint.config(:cache_static_manifest_latest) ) else - raise_connect_only!(socket, "static_changed?") + raise_root_and_mount_only!(socket, "static_changed?") end end @@ -1319,7 +1261,7 @@ defmodule Phoenix.LiveView do defp static_changed?(_, _), do: false - defp raise_connect_only!(socket, fun) do + defp raise_root_and_mount_only!(socket, fun) do if child?(socket) do raise RuntimeError, """ attempted to read #{fun} from a nested child LiveView #{inspect(socket.view)}. @@ -1352,7 +1294,7 @@ defmodule Phoenix.LiveView do [`preload/1`](`c:Phoenix.LiveComponent.preload/1`) then [`update/2`](`c:Phoenix.LiveComponent.update/2`) is invoked with the new assigns. If [`update/2`](`c:Phoenix.LiveComponent.update/2`) is not defined - all assigns are simply merged into the socket. + all assigns are simply merged into the socket. The assigns received as the first argument of the [`update/2`](`c:Phoenix.LiveComponent.update/2`) callback will only include the _new_ assigns passed from this function. Pre-existing assigns may be found in `socket.assigns`. While a component may always be updated from the parent by updating some parent assigns which will re-render the child, thus invoking @@ -1373,7 +1315,7 @@ defmodule Phoenix.LiveView do ... pid = self() - Task.async(fn -> + Task.start(fn -> # Do something asynchronously send_update(pid, Cart, id: "cart", status: "cancelled") end) @@ -1406,7 +1348,7 @@ defmodule Phoenix.LiveView do ... pid = self() - Task.async(fn -> + Task.start(fn -> # Do something asynchronously send_update_after(pid, Cart, [id: "cart", status: "cancelled"], 3000) end) @@ -1454,17 +1396,21 @@ defmodule Phoenix.LiveView do Hooks provide a mechanism to tap into key stages of the LiveView lifecycle in order to bind/update assigns, intercept events, patches, and regular messages when necessary, and to inject - common functionality. Hooks may be attached to any of the following - lifecycle stages: `:mount` (via `on_mount/1`), `:handle_params`, - `:handle_event`, and `:handle_info`. + common functionality. Use `attach_hook/1` on any of the following + lifecycle stages: `:handle_params`, `:handle_event`, `:handle_info`, and + `:after_render`. To attach a hook to the `:mount` stage, use `on_mount/1`. ## Return Values Lifecycle hooks take place immediately before a given lifecycle - callback is invoked on the LiveView. A hook may return `{:halt, socket}` - to halt the reduction, otherwise it must return `{:cont, socket}` so - the operation may continue until all hooks have been invoked for - the current stage. + callback is invoked on the LiveView. With the exception of `:after_render`, + a hook may return `{:halt, socket}` to halt the reduction, otherwise + it must return `{:cont, socket}` so the operation may continue until + all hooks have been invoked for the current stage. + + For `:after_render` hooks, the `socket` itself must be returned. + Any updates to the socket assigns *will not* trigger a new render + or diff calculation to the client. ## Halting the lifecycle @@ -1485,8 +1431,17 @@ defmodule Phoenix.LiveView do attach hooks to intercept specific events before detaching themselves, while allowing other events to continue normally. + ## Replying to events + + Hooks attached to the `:handle_event` stage are able to reply to client events + by returning `{:halt, reply, socket}`. This is useful especially for [JavaScript + interoperability](js-interop.html#client-hooks-via-phx-hook) because a client hook + can push an event and receive a reply. + ## Examples + Attaching and detaching a hook: + def mount(_params, _session, socket) do socket = attach_hook(socket, :my_hook, :handle_event, fn @@ -1500,6 +1455,38 @@ defmodule Phoenix.LiveView do {:ok, socket} end + + Replying to a client event: + + # JavaScript: + # let Hooks = {} + # Hooks.ClientHook = { + # mounted() { + # this.pushEvent("ClientHook:mounted", {hello: "world"}, (reply) => { + # console.log("received reply:", reply) + # }) + # } + # } + # let liveSocket = new LiveSocket("/live", Socket, {hooks: Hooks, ...}) + + def render(assigns) do + ~H"\"" +
+ "\"" + end + + def mount(_params, _session, socket) do + socket = + attach_hook(socket, :reply_on_client_hook_mounted, :handle_event, fn + "ClientHook:mounted", params, socket -> + {:halt, params, socket} + + _, _, socket -> + {:cont, socket} + end) + + {:ok, socket} + end """ defdelegate attach_hook(socket, name, stage, fun), to: Phoenix.LiveView.Lifecycle @@ -1519,4 +1506,206 @@ defmodule Phoenix.LiveView do end """ defdelegate detach_hook(socket, name, stage), to: Phoenix.LiveView.Lifecycle + + @doc ~S""" + Assigns a new stream to the socket. + + Streams are a mechanism for managing large collections on the client without + keeping the resources on the server. + + * `name` - The string or atom name of the key to place under the + `@streams` assign. + * `items` - The enumerable of items for initial insert + + The following options are supported: + + * `:dom_id` - The optional function to generate each stream item's DOM id. + The function accepts each stream item and converts the item to a string id. + By default, the `:id` field of a map or struct will be used if the item has + such a field, and will be prefixed by the `name` hyphenated with the id. + For example, the following definitions are equivalent: + + stream(socket, :songs, songs) + stream(socket, :songs, songs, dom_id: &("songs-#{&1.id}")) + + Once a stream is defined, a new `@streams` assign is available containing + the name of the defined streams. For example, in the above definition, the + stream may be referenced as `@streams.songs` in your template. Stream items + are temporary and freed from socket state as soon as they are rendered. + + ## Required DOM attributes + + For stream items to be trackable on the client, the following requirements + must be met: + + 1. The parent DOM container must include a `phx-update="stream"` attribute, + along with a unique DOM id. + 2. Each stream item must include its DOM id on the item's element. + + When consuming a stream in a template, the DOM id and item is passed as a tuple, + allowing convenient inclusion of the DOM id for each item. For example: + + ```heex +
+
<%= col.label %><%= col.label %>
<%= render_slot(col, row) %>
+ + + + + + +
<%= song.title %><%= song.duration %>
+ ``` + We consume the stream in a for comprehension by referencing the + `@streams.songs` assign. We used the computed DOM id to populate + the `` id, then we render the table row as usual. + + Now `stream_insert/3` and `stream_delete/3` may be issued and new rows will + be inserted or deleted from the client. + """ + def stream(socket, name, items, opts \\ []) do + opts = Keyword.merge(opts, id: Phoenix.LiveView.Utils.random_id()) + + socket + |> Phoenix.Component.assign_new(:streams, fn -> %{__changed__: MapSet.new()} end) + |> assign_stream(name, LiveStream.new(name, items, opts)) + |> attach_hook(name, :after_render, fn hook_socket -> + if name in hook_socket.assigns.streams.__changed__ do + Phoenix.Component.update(hook_socket, :streams, fn streams -> + streams + |> Map.update!(:__changed__, &MapSet.delete(&1, name)) + |> Map.update!(name, &LiveStream.prune(&1)) + end) + else + hook_socket + end + end) + end + + @doc """ + Inserts a new item or updates an existing item in the stream. + + By default, the item is appended to the parent DOM container. + The `:at` option may be provided to insert or update an item + to a particular index in the collection on the client. + + ## Examples + + Imagine you define a stream on mount with a single item: + + stream(socket, :songs, [%Song{id: 1, title: "Song 1"}]) + + Then, in a callback such as `handle_info` or `handle_event`, you + can append a new song: + + stream_insert(socket, :songs, %Song{id: 2, title: "Song 2"}) + + Or prepend a new song with `at: 0`: + + stream_insert(socket, :songs, %Song{id: 2, title: "Song 2"}, at: 0) + + Or updating an existing song, while also moving it to the top of the collection: + + stream_insert(socket, :songs, %Song{id: 1, title: "Song 1 updated"}, at: 0) + + ## Updating Items + + As shown, an existing item on the client can be updated by issuing a `stream_insert` for + the existing item. When the client updates an existing item with an "append" operation + (passing the `at: -1` option), the item will remain in the same location as it was + previously, and will not be moved to the end of the parent children. To both update an + existing item and move it to the end of a collection, issue a `stream_delete`, followed + by a `stream_insert`. For example: + + song = get_song!(id) + + socket + |> stream_delete(:songs, song) + |> stream_insert(:songs, song, at: -1) + + See `stream_delete/3` for more information on deleting items. + """ + def stream_insert(%Socket{} = socket, name, item, opts \\ []) do + at = Keyword.get(opts, :at, -1) + update_stream(socket, name, &LiveStream.insert_item(&1, item, at)) + end + + @doc """ + Deletes an item from the stream. + + The item's DOM is computed from the `:dom_id` provided in the `stream/3` definition. + Delete information for this DOM id is sent to the client and the item's element + is removed from the DOM, following the same behavior of element removal, such as + invoking `phx-remove` commands and executing client hook `destroyed()` callbacks. + + ## Examples + + def handle_event("delete", %{"id" => id}) + song = get_song!(id) + {:noreply, stream_delete(socket, :songs, song)} + end + + See `stream_delete_by_dom_id/3` to remove an item without requiring the + original datastructure. + """ + def stream_delete(socket, name, item) do + update_stream(socket, name, &LiveStream.delete_item(&1, item)) + end + + @doc ~S''' + Deletes an item from the stream given its computed DOM id. + + Behaves just like `stream_delete/3`, but accept the precomputed DOM id, + which allows deleting from a stream without fetching or building the original + stream datastructure. + + ## Examples + + def render(assigns) do + ~H""" + + + + + + + +
<%= song.title %>
+ """ + end + + def handle_event("delete", %{"id" => dom_id}) + {:noreply, stream_delete_by_dom_id(socket, :songs, dom_id)} + end + ''' + def stream_delete_by_dom_id(socket, name, id) do + update_stream(socket, name, &LiveStream.delete_item_by_dom_id(&1, id)) + end + + defp assign_stream(socket, name, %LiveStream{} = stream) do + Phoenix.Component.update(socket, :streams, fn streams -> + streams + |> Map.put(name, stream) + |> Map.update!(:__changed__, &MapSet.put(&1, name)) + end) + end + + defp update_stream(socket, name, func) do + Phoenix.Component.update(socket, :streams, fn streams -> + stream = + case Map.fetch(streams, name) do + {:ok, stream} -> stream + :error -> raise ArgumentError, "no stream with name #{inspect(name)} previously defined" + end + + streams + |> Map.put(name, func.(stream)) + |> Map.update!(:__changed__, &MapSet.put(&1, name)) + end) + end end diff --git a/lib/phoenix_live_view/application.ex b/lib/phoenix_live_view/application.ex index d80b7ea37b..e888ed6828 100644 --- a/lib/phoenix_live_view/application.ex +++ b/lib/phoenix_live_view/application.ex @@ -1,16 +1,11 @@ defmodule Phoenix.LiveView.Application do @moduledoc false - use Application - - require Logger - # TODO: Remove this whole module once we require Elixir v1.10+. - def start(_, _) do - if List.to_integer(:erlang.system_info(:otp_release)) < 21 do - Logger.error("Phoenix.LiveView requires Erlang/OTP 21+") - raise "Phoenix.LiveView requires Erlang/OTP 21+" - end + use Application - Supervisor.start_link([], strategy: :one_for_one) + @impl true + def start(_type, _args) do + Phoenix.LiveView.Logger.install() + Supervisor.start_link([], strategy: :one_for_one, name: Phoenix.LiveView.Supervisor) end end diff --git a/lib/phoenix_live_view/channel.ex b/lib/phoenix_live_view/channel.ex index 499e7aa475..6da404bfc7 100644 --- a/lib/phoenix_live_view/channel.ex +++ b/lib/phoenix_live_view/channel.ex @@ -9,6 +9,7 @@ defmodule Phoenix.LiveView.Channel do @prefix :phoenix @not_mounted_at_router :not_mounted_at_router + @max_host_size 253 def start_link({endpoint, from}) do hibernate_after = endpoint.config(:live_view)[:hibernate_after] || 15000 @@ -147,8 +148,17 @@ defmodule Phoenix.LiveView.Channel do entry = UploadConfig.get_entry_by_ref(upload_conf, entry_ref) if event = entry && upload_conf.progress_event do - {:noreply, new_socket} = event.(upload_conf.name, entry, new_socket) - {new_socket, {:ok, {msg.ref, %{}}, state}} + case event.(upload_conf.name, entry, new_socket) do + {:noreply, %Socket{} = new_socket} -> + {new_socket, {:ok, {msg.ref, %{}}, state}} + + other -> + raise ArgumentError, """ + expected #{inspect(upload_conf.name)} upload progress #{inspect(event)} to return {:noreply, Socket.t()} got: + + #{inspect(other)} + """ + end else {new_socket, {:ok, {msg.ref, %{}}, state}} end @@ -245,6 +255,17 @@ defmodule Phoenix.LiveView.Channel do handle_redirect(state, command, flash, nil) end + def handle_info({:phoenix_live_reload, _topic, _changed_file}, %{socket: socket} = state) do + Phoenix.CodeReloader.reload(socket.endpoint) + + new_socket = + Enum.reduce(socket.assigns, socket, fn {key, val}, socket -> + Utils.force_assign(socket, key, val) + end) + + handle_changed(state, new_socket, nil) + end + def handle_info(msg, %{socket: socket} = state) do msg |> view_handle_info(socket) @@ -260,8 +281,7 @@ defmodule Phoenix.LiveView.Channel do read_socket(state, cid, fn socket, _ -> result = with {:ok, uploads} <- Map.fetch(socket.assigns, :uploads), - {:ok, conf} <- Map.fetch(uploads, name), - do: {:ok, conf} + do: Map.fetch(uploads, name) {:reply, result, state} end) @@ -296,6 +316,30 @@ defmodule Phoenix.LiveView.Channel do |> handle_result({:handle_cast, 2, nil}, state) end + @impl true + def format_status(:terminate, [_pdict, state]) do + state + end + + def format_status(:normal, [_pdict, %{} = state]) do + %{topic: topic, socket: socket, components: {cid_to_component, _, _}} = state + %Socket{view: view, parent_pid: parent_pid, transport_pid: transport_pid} = socket + + [ + data: [ + {~c"LiveView", view}, + {~c"Parent pid", parent_pid}, + {~c"Transport pid", transport_pid}, + {~c"Topic", topic}, + {~c"Components count", map_size(cid_to_component)} + ] + ] + end + + def format_status(_, [_pdict, state]) do + [data: [{~c"State", state}]] + end + @impl true def terminate(reason, %{socket: socket}) do %{view: view} = socket @@ -345,6 +389,9 @@ defmodule Phoenix.LiveView.Channel do {:halt, %Socket{} = socket} -> {{:noreply, socket}, %{socket: socket, event: event, params: val}} + {:halt, reply, %Socket{} = socket} -> + {{:reply, reply, socket}, %{socket: socket, event: event, params: val}} + {:cont, %Socket{} = socket} -> case socket.view.handle_event(event, val, socket) do {:noreply, %Socket{} = socket} -> @@ -362,9 +409,21 @@ defmodule Phoenix.LiveView.Channel do end defp view_handle_info(msg, %{view: view} = socket) do + exported? = function_exported?(view, :handle_info, 2) + case Lifecycle.handle_info(msg, socket) do - {:halt, %Socket{} = socket} -> {:noreply, socket} - {:cont, %Socket{} = socket} -> view.handle_info(msg, socket) + {:cont, %Socket{} = socket} when exported? -> + view.handle_info(msg, socket) + + {:cont, %Socket{} = socket} when not exported? -> + Logger.debug( + "warning: undefined handle_info in #{inspect(view)}. Unhandled message: #{inspect(msg)}" + ) + + {:noreply, socket} + + {_, %Socket{} = socket} -> + {:noreply, socket} end end @@ -411,7 +470,9 @@ defmodule Phoenix.LiveView.Channel do {:live, :redirect, %{to: _to} = opts} -> {:live_redirect, copy_flash(new_state, Utils.get_flash(new_socket), opts), new_state} - {:live, {params, action}, %{to: to} = opts} -> + {:live, :patch, %{to: to} = opts} -> + {params, action} = patch_params_and_action!(new_socket, opts) + %{socket: new_socket} = new_state = drop_redirect(new_state) uri = build_uri(new_state, to) @@ -507,7 +568,14 @@ defmodule Phoenix.LiveView.Channel do defp unregister_upload(state, ref, entry_ref, cid) do write_socket(state, cid, nil, fn socket, _ -> conf = Upload.get_upload_by_ref!(socket, ref) - new_state = drop_upload_name(state, conf.name) + + new_state = + if Enum.count(conf.entries) == 1 do + drop_upload_name(state, conf.name) + else + state + end + {Upload.unregister_completed_entry_upload(socket, conf, entry_ref), {:ok, nil, new_state}} end) end @@ -653,14 +721,16 @@ defmodule Phoenix.LiveView.Channel do |> push_live_redirect(opts, ref, pending_diff_ack) |> stop_shutdown_redirect(:live_redirect, opts) - {:live, {params, action}, %{to: _to, kind: _kind} = opts} when root_pid == self() -> + {:live, :patch, %{to: _to, kind: _kind} = opts} when root_pid == self() -> + {params, action} = patch_params_and_action!(new_socket, opts) + new_state |> drop_redirect() |> maybe_push_pending_diff_ack(pending_diff_ack) |> Map.update!(:socket, &Utils.replace_flash(&1, flash)) |> sync_handle_params_with_live_redirect(params, action, opts, ref) - {:live, {_params, _action}, %{to: _to, kind: _kind}} = patch -> + {:live, :patch, %{to: _to, kind: _kind}} = patch -> send(new_socket.root_pid, {@prefix, :redirect, patch, flash}) {:diff, diff, new_state} = render_diff(new_state, new_socket, false) @@ -672,6 +742,21 @@ defmodule Phoenix.LiveView.Channel do end end + defp patch_params_and_action!(socket, %{to: to}) do + destructure [path, query], :binary.split(to, "?") + to = %{socket.host_uri | path: path, query: query} + + case Route.live_link_info!(socket, socket.private.root_view, to) do + {:internal, %Route{params: params, action: action}} -> + {params, action} + + {:external, _uri} -> + raise ArgumentError, + "cannot push_patch/2 to #{inspect(to)} because the given path " <> + "does not point to the current root view #{inspect(socket.private.root_view)}" + end + end + defp stop_shutdown_redirect(state, kind, opts) do send(state.socket.transport_pid, {:socket_close, self(), {kind, opts}}) {:stop, {:shutdown, {kind, opts}}, state} @@ -742,7 +827,13 @@ defmodule Phoenix.LiveView.Channel do end diff = Diff.render_private(socket, diff) - {:diff, diff, %{state | socket: Utils.clear_changed(socket), components: components}} + + new_socket = + socket + |> Lifecycle.after_render() + |> Utils.clear_changed() + + {:diff, diff, %{state | socket: new_socket, components: components}} end defp reply(state, {ref, extra}, status, payload) do @@ -756,7 +847,13 @@ defmodule Phoenix.LiveView.Channel do end defp push(state, event, payload) do - message = %Message{topic: state.topic, event: event, payload: payload, join_ref: state.join_ref} + message = %Message{ + topic: state.topic, + event: event, + payload: payload, + join_ref: state.join_ref + } + send(state.socket.transport_pid, state.serializer.encode!(message)) state end @@ -796,7 +893,7 @@ defmodule Phoenix.LiveView.Channel do 5) Define the CSRF meta tag inside the `` tag in your layout: - <%= csrf_meta_tag() %> + 6) Pass it forward in your app.js: @@ -808,10 +905,20 @@ defmodule Phoenix.LiveView.Channel do {:stop, :shutdown, :no_state} %{} -> - case authorize_session(verified, endpoint, params) do - {:ok, %Session{} = new_verified, route, url} -> - verified_mount(new_verified, route, url, params, from, phx_socket, connect_info) - + with {:ok, %Session{view: view} = new_verified, route, url} <- + authorize_session(verified, endpoint, params), + {:ok, config} <- load_live_view(view) do + verified_mount( + new_verified, + config, + route, + url, + params, + from, + phx_socket, + connect_info + ) + else {:error, :unauthorized} -> GenServer.reply(from, {:error, %{reason: "unauthorized"}}) {:stop, :shutdown, :no_state} @@ -834,23 +941,28 @@ defmodule Phoenix.LiveView.Channel do {:stop, :shutdown, :no_session} end - defp verify_flash(endpoint, %Session{} = verified, flash_token, connect_params) do - cond do - # flash_token is given by the client on live_redirects and has higher priority. - flash_token -> - Utils.verify_flash(endpoint, flash_token) - - # verified.flash comes from the disconnected render, therefore we only want - # to load it we are not inside a live redirect and if it is our first mount. - not verified.redirected? && connect_params["_mounts"] == 0 && verified.flash -> - verified.flash - - true -> - %{} - end - end - - defp verified_mount(%Session{} = verified, route, url, params, from, phx_socket, connect_info) do + defp load_live_view(view) do + # Make sure the view is loaded. Otherwise if the first request + # ever is a LiveView connection, the view won't be loaded and + # the mount/handle_params callbacks won't be invoked as they + # are optional, leading to errors. + {:ok, view.__live__()} + rescue + # If it fails, then the only possible answer is that the live + # view has been renamed. So we force the client to reconnect. + _ -> {:error, :stale} + end + + defp verified_mount( + %Session{} = verified, + config, + route, + url, + params, + from, + phx_socket, + connect_info + ) do %Session{ id: id, view: view, @@ -862,15 +974,6 @@ defmodule Phoenix.LiveView.Channel do router: router } = verified - # Make sure the view is loaded. Otherwise if the first request - # ever is a LiveView connection, the view won't be loaded and - # the mount/handle_params callbacks won't be invoked as they - # are optional, leading to errors. - config = view.__live__() - - live_session_on_mount = load_live_session_on_mount(route) - lifecycle = lifecycle(config, live_session_on_mount) - %Phoenix.Socket{ endpoint: endpoint, transport_pid: transport_pid @@ -881,7 +984,9 @@ defmodule Phoenix.LiveView.Channel do # Optional verified parts flash = verify_flash(endpoint, verified, params["flash"], connect_params) - socket_session = connect_info[:session] || %{} + + # connect_info is either a Plug.Conn during tests or a Phoenix.Socket map + socket_session = Map.get(connect_info, :session, %{}) Process.monitor(transport_pid) load_csrf_token(endpoint, socket_session) @@ -903,7 +1008,7 @@ defmodule Phoenix.LiveView.Channel do {params, host_uri, action} = case route do - %Route{} = route -> + %Route{uri: %URI{host: host}} = route when byte_size(host) <= @max_host_size -> {route.params, route.uri, route.action} nil -> @@ -911,16 +1016,30 @@ defmodule Phoenix.LiveView.Channel do end merged_session = Map.merge(socket_session, verified_user_session) + lifecycle = load_lifecycle(config, route) case mount_private(parent, root_view, assign_new, connect_params, connect_info, lifecycle) do {:ok, mount_priv} -> socket = Utils.configure_socket(socket, mount_priv, action, flash, host_uri) - socket - |> Utils.maybe_call_live_view_mount!(view, params, merged_session) - |> build_state(phx_socket) - |> maybe_call_mount_handle_params(router, url, params) - |> reply_mount(from, verified, route) + try do + socket + |> load_layout(route) + |> Utils.maybe_call_live_view_mount!(view, params, merged_session, url) + |> build_state(phx_socket) + |> maybe_call_mount_handle_params(router, url, params) + |> reply_mount(from, verified, route) + |> maybe_subscribe_to_live_reload() + rescue + exception -> + status = Plug.Exception.status(exception) + if status >= 400 and status < 500 do + GenServer.reply(from, {:error, %{reason: "reload", status: status}}) + {:stop, :shutdown, :no_state} + else + reraise(exception, __STACKTRACE__) + end + end {:error, :noproc} -> GenServer.reply(from, {:error, %{reason: "stale"}}) @@ -928,6 +1047,22 @@ defmodule Phoenix.LiveView.Channel do end end + defp verify_flash(endpoint, %Session{} = verified, flash_token, connect_params) do + cond do + # flash_token is given by the client on live_redirects and has higher priority. + flash_token -> + Utils.verify_flash(endpoint, flash_token) + + # verified.flash comes from the disconnected render, therefore we only want + # to load it we are not inside a live redirect and if it is our first mount. + not verified.redirected? && connect_params["_mounts"] == 0 && verified.flash -> + verified.flash + + true -> + %{} + end + end + defp load_csrf_token(endpoint, socket_session) do if token = socket_session["_csrf_token"] do state = Plug.CSRFProtection.dump_state_from_session(token) @@ -936,13 +1071,23 @@ defmodule Phoenix.LiveView.Channel do end end - defp load_live_session_on_mount(%Route{live_session: %{extra: %{on_mount: hooks}}}), do: hooks - defp load_live_session_on_mount(_), do: [] + defp load_lifecycle( + %{lifecycle: lifecycle}, + %Route{live_session: %{extra: %{on_mount: on_mount}}} + ) do + update_in(lifecycle.mount, &(on_mount ++ &1)) + end - defp lifecycle(%{lifecycle: lifecycle}, []), do: lifecycle + defp load_lifecycle(%{lifecycle: lifecycle}, _) do + lifecycle + end - defp lifecycle(%{lifecycle: lifecycle}, on_mount) do - %{lifecycle | mount: on_mount ++ lifecycle.mount} + defp load_layout(socket, %Route{live_session: %{extra: %{layout: layout}}}) do + put_in(socket.private[:live_layout], layout) + end + + defp load_layout(socket, _route) do + socket end defp mount_private(nil, root_view, assign_new, connect_params, connect_info, lifecycle) do @@ -966,7 +1111,7 @@ defmodule Phoenix.LiveView.Channel do connect_params: connect_params, connect_info: connect_info, assign_new: {parent_assigns, assign_new}, - phoenix_live_layout: false, + live_layout: false, lifecycle: lifecycle, root_view: root_view, __changed__: %{} @@ -978,8 +1123,6 @@ defmodule Phoenix.LiveView.Channel do end defp sync_with_parent(parent, assign_new) do - _ref = Process.monitor(parent) - try do GenServer.call(parent, {@prefix, :child_mount, self(), assign_new}) catch @@ -1041,7 +1184,7 @@ defmodule Phoenix.LiveView.Channel do end defp assign_action(socket, action) do - Phoenix.LiveView.assign(socket, :live_action, action) + Phoenix.Component.assign(socket, :live_action, action) end defp maybe_update_uploads(%Socket{} = socket, %{"uploads" => uploads} = payload) do @@ -1195,4 +1338,16 @@ defmodule Phoenix.LiveView.Channel do _ -> nil end end + + defp maybe_subscribe_to_live_reload({:noreply, state}) do + live_reload_config = state.socket.endpoint.config(:live_reload) + + if live_reload_config[:notify][:live_view] do + state.socket.endpoint.subscribe("live_view") + end + + {:noreply, state} + end + + defp maybe_subscribe_to_live_reload(response), do: response end diff --git a/lib/phoenix_live_view/controller.ex b/lib/phoenix_live_view/controller.ex index 9d0e9325e8..8603637fca 100644 --- a/lib/phoenix_live_view/controller.ex +++ b/lib/phoenix_live_view/controller.ex @@ -7,14 +7,15 @@ defmodule Phoenix.LiveView.Controller do alias Phoenix.LiveView.Socket @doc """ - Renders a live view from a Plug request and sends an HTML response. + Renders a live view from a Plug request and sends an HTML response + from within a controller. - Before rendering, the `@live_module` assign will be added to the - connection assigns for reference. + It also automatically sets the `@live_module` assign with the value + of the LiveView to be rendered. ## Options - See `Phoenix.LiveView.Helpers.live_render/3` for all supported options. + See `Phoenix.Component.live_render/3` for all supported options. ## Examples @@ -27,7 +28,7 @@ defmodule Phoenix.LiveView.Controller do def show(conn, %{"id" => thermostat_id}) do live_render(conn, ThermostatLive, session: %{ - "thermostat_id" => id, + "thermostat_id" => thermostat_id, "current_user_id" => get_session(conn, :user_id) }) end diff --git a/lib/phoenix_live_view/diff.ex b/lib/phoenix_live_view/diff.ex index 05bdab1aae..2aa8885839 100644 --- a/lib/phoenix_live_view/diff.ex +++ b/lib/phoenix_live_view/diff.ex @@ -4,7 +4,7 @@ defmodule Phoenix.LiveView.Diff do # handled here. @moduledoc false - alias Phoenix.LiveView.{Utils, Rendered, Comprehension, Component} + alias Phoenix.LiveView.{Utils, Rendered, Comprehension, Component, Lifecycle} @components :c @static :s @@ -12,6 +12,8 @@ defmodule Phoenix.LiveView.Diff do @events :e @reply :r @title :t + @template :p + @stream_id :stream # We use this to track which components have been marked # for deletion. If the component is used after being marked, @@ -38,48 +40,55 @@ defmodule Phoenix.LiveView.Diff do It only accepts a full render diff. """ def to_iodata(map, component_mapper \\ fn _cid, content -> content end) do - to_iodata(map, Map.get(map, @components, %{}), component_mapper) |> elem(0) + to_iodata(map, Map.get(map, @components, %{}), nil, component_mapper) |> elem(0) end - defp to_iodata(%{@dynamics => dynamics, @static => static}, components, mapper) do + defp to_iodata(%{@dynamics => dynamics, @static => static} = comp, components, template, mapper) do + static = template_static(static, template) + template = template || comp[@template] + Enum.map_reduce(dynamics, components, fn dynamic, components -> - many_to_iodata(static, dynamic, [], components, mapper) + many_to_iodata(static, dynamic, [], components, template, mapper) end) end - defp to_iodata(%{@static => static} = parts, components, mapper) do - one_to_iodata(static, parts, 0, [], components, mapper) + defp to_iodata(%{@static => static} = parts, components, template, mapper) do + static = template_static(static, template) + one_to_iodata(static, parts, 0, [], components, template, mapper) end - defp to_iodata(cid, components, mapper) when is_integer(cid) do + defp to_iodata(cid, components, _template, mapper) when is_integer(cid) do # Resolve component pointers and update the component entries components = resolve_components_xrefs(cid, components) - {iodata, components} = to_iodata(Map.fetch!(components, cid), components, mapper) + {iodata, components} = to_iodata(Map.fetch!(components, cid), components, nil, mapper) {mapper.(cid, iodata), components} end - defp to_iodata(binary, components, _mapper) when is_binary(binary) do + defp to_iodata(binary, components, _template, _mapper) when is_binary(binary) do {binary, components} end - defp one_to_iodata([last], _parts, _counter, acc, components, _mapper) do + defp one_to_iodata([last], _parts, _counter, acc, components, _template, _mapper) do {Enum.reverse([last | acc]), components} end - defp one_to_iodata([head | tail], parts, counter, acc, components, mapper) do - {iodata, components} = to_iodata(Map.fetch!(parts, counter), components, mapper) - one_to_iodata(tail, parts, counter + 1, [iodata, head | acc], components, mapper) + defp one_to_iodata([head | tail], parts, counter, acc, components, template, mapper) do + {iodata, components} = to_iodata(Map.fetch!(parts, counter), components, template, mapper) + one_to_iodata(tail, parts, counter + 1, [iodata, head | acc], components, template, mapper) end - defp many_to_iodata([shead | stail], [dhead | dtail], acc, components, mapper) do - {iodata, components} = to_iodata(dhead, components, mapper) - many_to_iodata(stail, dtail, [iodata, shead | acc], components, mapper) + defp many_to_iodata([shead | stail], [dhead | dtail], acc, components, template, mapper) do + {iodata, components} = to_iodata(dhead, components, template, mapper) + many_to_iodata(stail, dtail, [iodata, shead | acc], components, template, mapper) end - defp many_to_iodata([shead], [], acc, components, _mapper) do + defp many_to_iodata([shead], [], acc, components, _template, _mapper) do {Enum.reverse([shead | acc]), components} end + defp template_static(static, template) when is_integer(static), do: Map.fetch!(template, static) + defp template_static(static, _template) when is_list(static), do: static + defp resolve_components_xrefs(cid, components) do case components[cid] do %{@static => static} = diff when is_integer(static) -> @@ -126,8 +135,8 @@ defmodule Phoenix.LiveView.Diff do end def render(%{fingerprints: prints} = socket, %Rendered{} = rendered, components) do - {diff, prints, pending, components} = - traverse(socket, rendered, prints, %{}, components, true) + {diff, prints, pending, components, nil} = + traverse(socket, rendered, prints, %{}, components, nil, true) # cid_to_component is used by maybe_reuse_static and it must be a copy before changes. # However, given traverse does not change cid_to_component, we can read it now. @@ -137,7 +146,6 @@ defmodule Phoenix.LiveView.Diff do render_pending_components(socket, pending, cid_to_component, %{}, components) socket = %{socket | fingerprints: prints} - diff = maybe_put_title(diff, socket) {diff, cdiffs} = extract_events({diff, cdiffs}) @@ -233,9 +241,9 @@ defmodule Phoenix.LiveView.Diff do case cid_to_component do %{^cid => {component, _id, assigns, private, fingerprints}} -> - socket - |> configure_socket_for_component(assigns, private, fingerprints) - |> fun.(component) + socket + |> configure_socket_for_component(assigns, private, fingerprints) + |> fun.(component) %{} -> :error @@ -351,42 +359,66 @@ defmodule Phoenix.LiveView.Diff do defp traverse( socket, - %Rendered{fingerprint: fingerprint, dynamic: dynamic}, + %Rendered{fingerprint: fingerprint} = rendered, {fingerprint, children}, pending, components, + template, changed? ) do - {_counter, diff, children, pending, components} = - traverse_dynamic(socket, dynamic.(changed?), children, pending, components, changed?) + # If we are diff tracking, then template must be nil + nil = template + + {_counter, diff, children, pending, components, nil} = + traverse_dynamic( + socket, + invoke_dynamic(rendered, changed?), + children, + pending, + components, + nil, + changed? + ) - {diff, {fingerprint, children}, pending, components} + {diff, {fingerprint, children}, pending, components, nil} end defp traverse( socket, - %Rendered{fingerprint: fingerprint, static: static, dynamic: dynamic}, + %Rendered{fingerprint: fingerprint, static: static} = rendered, _, pending, components, + template, changed? ) do - {_counter, diff, children, pending, components} = - traverse_dynamic(socket, dynamic.(false), %{}, pending, components, changed?) + {_counter, diff, children, pending, components, template} = + traverse_dynamic( + socket, + invoke_dynamic(rendered, false), + %{}, + pending, + components, + template, + changed? + ) - {Map.put(diff, @static, static), {fingerprint, children}, pending, components} + {diff, template} = maybe_template_static(diff, fingerprint, static, template) + {diff, {fingerprint, children}, pending, components, template} end + # TODO: Remove me when stateless module components are removed defp traverse( socket, %Component{id: nil, component: component, assigns: assigns}, fingerprints_tree, pending, components, + template, changed? ) do rendered = component_to_rendered(socket, component, assigns, %{}) - traverse(socket, rendered, fingerprints_tree, pending, components, changed?) + traverse(socket, rendered, fingerprints_tree, pending, components, template, changed?) end defp traverse( @@ -395,58 +427,121 @@ defmodule Phoenix.LiveView.Diff do _fingerprints_tree, pending, components, + template, _changed? ) do {cid, pending, components} = traverse_component(socket, component, pending, components) - {cid, nil, pending, components} + {cid, nil, pending, components, template} end defp traverse( socket, - %Comprehension{dynamics: dynamics, fingerprint: fingerprint}, + %Comprehension{fingerprint: fingerprint, dynamics: dynamics, stream: stream_id}, fingerprint, pending, components, + template, _changed? ) do - {dynamics, {pending, components}} = - traverse_comprehension(socket, dynamics, pending, components) + # If we are diff tracking, then template must be nil + nil = template - {%{@dynamics => dynamics}, fingerprint, pending, components} + {dynamics, {pending, components, {_, comprehension_template}}} = + traverse_comprehension(socket, dynamics, pending, components, {%{}, %{}}) + + diff = + %{@dynamics => dynamics} + |> maybe_add_template(comprehension_template) + |> maybe_add_stream_id(stream_id) + + {diff, fingerprint, pending, components, nil} end - defp traverse(_socket, %Comprehension{dynamics: []}, _, pending, components, _changed?) do + defp traverse( + _socket, + %Comprehension{dynamics: []}, + _, + pending, + components, + template, + _changed? + ) do # The comprehension has no elements and it was not rendered yet, so we skip it. - {"", nil, pending, components} + {"", nil, pending, components, template} end defp traverse( socket, - %Comprehension{static: static, dynamics: dynamics, fingerprint: fingerprint}, + %Comprehension{fingerprint: print, static: static, dynamics: dynamics, stream: stream}, _, pending, components, + template, _changed? ) do - {dynamics, {pending, components}} = - traverse_comprehension(socket, dynamics, pending, components) + if template do + {dynamics, {pending, components, template}} = + traverse_comprehension(socket, dynamics, pending, components, template) - {%{@dynamics => dynamics, @static => static}, fingerprint, pending, components} + {diff, template} = maybe_template_static(%{@dynamics => dynamics}, print, static, template) + diff = maybe_add_stream_id(diff, stream) + + {diff, print, pending, components, template} + else + {dynamics, {pending, components, {_, comprehension_template}}} = + traverse_comprehension(socket, dynamics, pending, components, {%{}, %{}}) + + diff = + %{@dynamics => dynamics, @static => static} + |> maybe_add_template(comprehension_template) + |> maybe_add_stream_id(stream) + + {diff, print, pending, components, nil} + end end - defp traverse(_socket, nil, fingerprint_tree, pending, components, _changed?) do - {nil, fingerprint_tree, pending, components} + defp traverse(_socket, nil, fingerprint_tree, pending, components, template, _changed?) do + {nil, fingerprint_tree, pending, components, template} end - defp traverse(_socket, iodata, _, pending, components, _changed?) do - {IO.iodata_to_binary(iodata), nil, pending, components} + defp traverse(_socket, iodata, _, pending, components, template, _changed?) do + {IO.iodata_to_binary(iodata), nil, pending, components, template} end - defp traverse_dynamic(socket, dynamic, children, pending, components, changed?) do - Enum.reduce(dynamic, {0, %{}, children, pending, components}, fn - entry, {counter, diff, children, pending, components} -> - {serialized, child_fingerprint, pending, components} = - traverse(socket, entry, Map.get(children, counter), pending, components, changed?) + defp invoke_dynamic(%Rendered{caller: :not_available, dynamic: dynamic}, changed?) do + dynamic.(changed?) + end + + defp invoke_dynamic(%Rendered{caller: caller, dynamic: dynamic}, changed?) do + try do + dynamic.(changed?) + rescue + e -> + {mod, {function, arity}, file, line} = caller + entry = {mod, function, arity, file: String.to_charlist(file), line: line} + reraise e, inject_stacktrace(__STACKTRACE__, entry) + end + end + + defp inject_stacktrace([{__MODULE__, :invoke_dynamic, 2, _} | stacktrace], entry) do + [entry | Enum.drop_while(stacktrace, &(elem(&1, 0) == __MODULE__))] + end + + defp inject_stacktrace([head | tail], entry) do + [head | inject_stacktrace(tail, entry)] + end + + defp inject_stacktrace([], entry) do + [entry] + end + + defp traverse_dynamic(socket, dynamic, children, pending, components, template, changed?) do + Enum.reduce(dynamic, {0, %{}, children, pending, components, template}, fn + entry, {counter, diff, children, pending, components, template} -> + child = Map.get(children, counter) + + {serialized, child_fingerprint, pending, components, template} = + traverse(socket, entry, child, pending, components, template, changed?) # If serialized is nil, it means no changes. # If it is an empty map, then it means it is a rendered struct @@ -465,21 +560,44 @@ defmodule Phoenix.LiveView.Diff do Map.delete(children, counter) end - {counter + 1, diff, children, pending, components} + {counter + 1, diff, children, pending, components, template} end) end - defp traverse_comprehension(socket, dynamics, pending, components) do - Enum.map_reduce(dynamics, {pending, components}, fn list, acc -> - Enum.map_reduce(list, acc, fn rendered, {pending, components} -> - {diff, _, pending, components} = - traverse(socket, rendered, {nil, %{}}, pending, components, false) + defp traverse_comprehension(socket, dynamics, pending, components, template) do + Enum.map_reduce(dynamics, {pending, components, template}, fn rendereds, acc -> + Enum.map_reduce(rendereds, acc, fn rendered, {pending, components, template} -> + {diff, _, pending, components, template} = + traverse(socket, rendered, {nil, %{}}, pending, components, template, false) - {diff, {pending, components}} + {diff, {pending, components, template}} end) end) end + defp maybe_template_static(map, fingerprint, static, {print_to_pos, pos_to_static}) do + case print_to_pos do + %{^fingerprint => pos} -> + {Map.put(map, @static, pos), {print_to_pos, pos_to_static}} + + %{} -> + pos = map_size(pos_to_static) + pos_to_static = Map.put(pos_to_static, pos, static) + print_to_pos = Map.put(print_to_pos, fingerprint, pos) + {Map.put(map, @static, pos), {print_to_pos, pos_to_static}} + end + end + + defp maybe_template_static(map, _fingerprint, static, nil) do + {Map.put(map, @static, static), nil} + end + + defp maybe_add_template(map, template) when template == %{}, do: map + defp maybe_add_template(map, template), do: Map.put(map, @template, template) + + defp maybe_add_stream_id(diff, nil = _stream_id), do: diff + defp maybe_add_stream_id(diff, stream_id), do: Map.put(diff, @stream_id, stream_id) + ## Stateful components helpers defp traverse_component( @@ -595,8 +713,8 @@ defmodule Phoenix.LiveView.Diff do {changed?, linked_cid, prints} = maybe_reuse_static(rendered, socket, component, cids, components) - {diff, component_prints, pending, components} = - traverse(socket, rendered, prints, pending, components, changed?) + {diff, component_prints, pending, components, nil} = + traverse(socket, rendered, prints, pending, components, nil, changed?) diff = if linked_cid, do: Map.put(diff, @static, linked_cid), else: diff {%{socket | fingerprints: component_prints}, pending, diff, components} @@ -606,7 +724,9 @@ defmodule Phoenix.LiveView.Diff do socket = if changed? or events? do - Utils.clear_changed(socket) + socket + |> Lifecycle.after_render() + |> Utils.clear_changed() else socket end @@ -686,6 +806,7 @@ defmodule Phoenix.LiveView.Diff do socket.private |> Map.take([:conn_session, :root_view]) |> Map.put(:__changed__, %{}) + |> Map.put(:lifecycle, %Phoenix.LiveView.Lifecycle{}) socket = configure_socket_for_component(socket, assigns, private, new_fingerprints()) @@ -699,7 +820,7 @@ defmodule Phoenix.LiveView.Diff do socket | assigns: Map.put(assigns, :__changed__, %{}), private: private, - fingerprints: prints, + fingerprints: prints } end diff --git a/lib/phoenix_live_view/engine.ex b/lib/phoenix_live_view/engine.ex index c3ea256f54..f1b72a9702 100644 --- a/lib/phoenix_live_view/engine.ex +++ b/lib/phoenix_live_view/engine.ex @@ -59,9 +59,10 @@ defmodule Phoenix.LiveView.Comprehension do in `Phoenix.LiveView.Engine` docs. """ - defstruct [:static, :dynamics, :fingerprint] + defstruct [:static, :dynamics, :fingerprint, :stream] @type t :: %__MODULE__{ + stream: String.t() | atom() | nil, static: [String.t()], dynamics: [ [ @@ -74,6 +75,14 @@ defmodule Phoenix.LiveView.Comprehension do fingerprint: integer() } + @doc false + def __annotate__(comprehension, %Phoenix.LiveView.LiveStream{} = stream) do + inserts = for {id, at, _item} <- stream.inserts, into: %{}, do: {id, at} + Map.put(comprehension, :stream, [inserts, stream.deletes]) + end + + def __annotate__(comprehension, _collection), do: comprehension + defimpl Phoenix.HTML.Safe do def to_iodata(%Phoenix.LiveView.Comprehension{static: static, dynamics: dynamics}) do for dynamic <- dynamics, do: to_iodata(static, dynamic) @@ -102,7 +111,7 @@ defmodule Phoenix.LiveView.Rendered do in `Phoenix.LiveView.Engine` docs. """ - defstruct [:static, :dynamic, :fingerprint, :root] + defstruct [:static, :dynamic, :fingerprint, :root, caller: :not_available] @type t :: %__MODULE__{ static: [String.t()], @@ -116,7 +125,11 @@ defmodule Phoenix.LiveView.Rendered do | Phoenix.LiveView.Component.t() ]), fingerprint: integer(), - root: nil | true | false + root: nil | true | false, + caller: + :not_available + | {module(), function :: {atom(), non_neg_integer()}, file :: String.t(), + line :: pos_integer()} } defimpl Phoenix.HTML.Safe do @@ -150,7 +163,7 @@ defmodule Phoenix.LiveView.Engine do @moduledoc ~S""" An `EEx` template engine that tracks changes. - This is often used by `Phoenix.LiveView.HTMLEngine` which also adds + This is often used by `Phoenix.LiveView.TagEngine` which also adds HTML validation. In the documentation below, we will explain how it works internally. For user-facing documentation, see `Phoenix.LiveView`. @@ -282,11 +295,10 @@ defmodule Phoenix.LiveView.Engine do handled lazily by the diff algorithm. """ + alias Phoenix.HTML.Form @behaviour Phoenix.Template.Engine - # TODO: Use @impl true instead of @doc false when we require Elixir v1.12 - - @doc false + @impl true def compile(path, _name) do trim = Application.get_env(:phoenix, :trim_on_html_eex_engine, true) EEx.compile_file(path, engine: __MODULE__, line: 1, trim: trim) @@ -295,30 +307,35 @@ defmodule Phoenix.LiveView.Engine do @behaviour EEx.Engine @assigns_var Macro.var(:assigns, nil) - @doc false - def init(_opts) do + @impl true + def init(opts) do + # Phoenix.LiveView.TagEngine calls this engine in a non-linear order + # to evaluate slots, which can lead to variable conflicts. Therefore we + # use a counter to ensure all variable names are unique. %{ static: [], dynamic: [], - vars_count: 0 + counter: :counters.new(1, []), + caller: opts[:caller] } end - @doc false + @impl true def handle_begin(state) do %{state | static: [], dynamic: []} end - @doc false + @impl true def handle_end(state) do %{static: static, dynamic: dynamic} = state safe = {:safe, Enum.reverse(static)} {:__block__, [live_rendered: true], Enum.reverse([safe | dynamic])} end - @doc false + @impl true def handle_body(state, opts \\ []) do - {:ok, rendered} = to_rendered_struct(handle_end(state), {:untainted, %{}}, %{}, opts) + {:ok, rendered} = + to_rendered_struct(handle_end(state), {:untainted, %{}}, %{}, state.caller, opts) quote do require Phoenix.LiveView.Engine @@ -326,23 +343,21 @@ defmodule Phoenix.LiveView.Engine do end end - @doc false - def handle_text(state, text) do - handle_text(state, [], text) - end - - @doc false + @impl true def handle_text(state, _meta, text) do %{static: static} = state %{state | static: [text | static]} end - @doc false + @impl true def handle_expr(state, "=", ast) do - %{static: static, dynamic: dynamic, vars_count: vars_count} = state - var = Macro.var(:"arg#{vars_count}", __MODULE__) + %{static: static, dynamic: dynamic, counter: counter} = state + i = :counters.get(counter, 1) + var = Macro.var(:"v#{i}", __MODULE__) ast = quote do: unquote(var) = unquote(__MODULE__).to_safe(unquote(ast)) - %{state | dynamic: [ast | dynamic], static: [var | static], vars_count: vars_count + 1} + + :counters.add(counter, 1, 1) + %{state | dynamic: [ast | dynamic], static: [var | static]} end def handle_expr(state, "", ast) do @@ -356,11 +371,11 @@ defmodule Phoenix.LiveView.Engine do ## Entry point for rendered structs - defp to_rendered_struct(expr, vars, assigns, opts) do + defp to_rendered_struct(expr, vars, assigns, caller, opts) do with {:__block__, [live_rendered: true], entries} <- expr, {dynamic, [{:safe, static}]} <- Enum.split(entries, -1) do {block, static, dynamic, fingerprint} = - analyze_static_and_dynamic(static, dynamic, vars, assigns) + analyze_static_and_dynamic(static, dynamic, vars, assigns, caller) changed = quote generated: true do @@ -400,18 +415,18 @@ defmodule Phoenix.LiveView.Engine do end end - defp analyze_static_and_dynamic(static, dynamic, initial_vars, assigns) do + defp analyze_static_and_dynamic(static, dynamic, initial_vars, assigns, caller) do {block, _} = Enum.map_reduce(dynamic, initial_vars, fn to_safe_match(var, ast), vars -> vars = set_vars(initial_vars, vars) - {ast, keys, vars} = analyze_and_return_tainted_keys(ast, vars, assigns) - live_struct = to_live_struct(ast, vars, assigns) + {ast, keys, vars} = analyze_and_return_tainted_keys(ast, vars, assigns, caller) + live_struct = to_live_struct(ast, vars, assigns, caller) {to_conditional_var(keys, var, live_struct), vars} ast, vars -> vars = set_vars(initial_vars, vars) - {ast, vars, _} = analyze(ast, vars, assigns) + {ast, vars, _} = analyze(ast, vars, assigns, caller) {ast, vars} end) @@ -421,37 +436,46 @@ defmodule Phoenix.LiveView.Engine do ## Optimize possible expressions into live structs (rendered / comprehensions) - defp to_live_struct({:for, _, [_ | _]} = expr, vars, _assigns) do - with {:for, meta, [_ | _] = args} <- expr, + defp to_live_struct({:for, _, [_ | _]} = expr, vars, _assigns, caller) do + with {:for, meta, [gen | args]} <- expr, {filters, [[do: {:__block__, _, block}]]} <- Enum.split(args, -1), {dynamic, [{:safe, static}]} <- Enum.split(block, -1) do {block, static, dynamic, fingerprint} = - analyze_static_and_dynamic(static, dynamic, taint_vars(vars), %{}) + analyze_static_and_dynamic(static, dynamic, taint_vars(vars), %{}, caller) - for = {:for, meta, filters ++ [[do: {:__block__, [], block ++ [dynamic]}]]} + gen_var = Macro.unique_var(:for, __MODULE__) + {:<-, gen_meta, [gen_pattern, gen_collection]} = gen + gen_collection = quote(do: unquote(gen_var) = unquote(gen_collection)) + gen = {:<-, gen_meta, [gen_pattern, gen_var]} + for = {:for, meta, [gen | filters] ++ [[do: {:__block__, [], block ++ [dynamic]}]]} quote do - %Phoenix.LiveView.Comprehension{ - static: unquote(static), - dynamics: unquote(for), - fingerprint: unquote(fingerprint) - } + unquote(gen_collection) + + Phoenix.LiveView.Comprehension.__annotate__( + %Phoenix.LiveView.Comprehension{ + static: unquote(static), + dynamics: unquote(for), + fingerprint: unquote(fingerprint) + }, + unquote(gen_var) + ) end else _ -> to_safe(expr, true) end end - defp to_live_struct({left, meta, [_ | _] = args}, vars, assigns) do + defp to_live_struct({left, meta, [_ | _] = args}, vars, assigns, caller) do call = extract_call(left) args = - if classify_taint(call, args) in [:live, :render] do + if classify_taint(call, args) == :live do {args, [opts]} = Enum.split(args, -1) # The reason we can safely ignore assigns here is because # each branch in the live/render constructs are their own - # rendered struct and, if the rendered has a new fingerpint, + # rendered struct and, if the rendered has a new fingerprint, # then change tracking is fully disabled. # # For example, take this code: @@ -473,11 +497,11 @@ defmodule Phoenix.LiveView.Engine do # untainting, as the parent untainting is already causing # the block to be rendered and then we can proceed with # its own tainting. - {args, vars, _} = analyze_list(args, vars, assigns, []) + {args, vars, _} = analyze_list(args, vars, assigns, caller, []) opts = for {key, value} <- opts do - {key, maybe_block_to_rendered(value, vars)} + {key, maybe_block_to_rendered(value, vars, caller)} end args ++ [opts] @@ -488,36 +512,43 @@ defmodule Phoenix.LiveView.Engine do args = case {call, args} do # If we have a component, we provide change tracking to individual keys. - {:component, [fun, expr]} -> [fun, to_component_tracking(fun, expr, [], vars)] - {_, _} -> args + {:component, [fun, expr, metadata]} -> + [fun, to_component_tracking(meta, fun, expr, [], vars, caller), metadata] + + {_, _} -> + args end to_safe({left, meta, args}, true) end - defp to_live_struct(expr, _vars, _assigns) do + defp to_live_struct(expr, _vars, _assigns, _caller) do to_safe(expr, true) end + # TODO: Remove me when live_component/2/3 are removed defp extract_call({:., _, [{:__aliases__, _, [:Phoenix, :LiveView, :Helpers]}, func]}), do: func + defp extract_call({:., _, [{:__aliases__, _, [:Phoenix, :LiveView, :TagEngine]}, func]}), + do: func + defp extract_call(call), do: call - defp maybe_block_to_rendered([{:->, _, _} | _] = blocks, vars) do + defp maybe_block_to_rendered([{:->, _, _} | _] = blocks, vars, caller) do for {:->, meta, [args, block]} <- blocks do - {args, vars, assigns} = analyze_list(args, vars, %{}, []) + {args, vars, assigns} = analyze_list(args, vars, %{}, caller, []) - case to_rendered_struct(block, untaint_vars(vars), assigns, []) do + case to_rendered_struct(block, untaint_vars(vars), assigns, caller, []) do {:ok, rendered} -> {:->, meta, [args, rendered]} :error -> {:->, meta, [args, block]} end end end - defp maybe_block_to_rendered(block, vars) do - case to_rendered_struct(block, untaint_vars(vars), %{}, []) do + defp maybe_block_to_rendered(block, vars, caller) do + case to_rendered_struct(block, untaint_vars(vars), %{}, caller, []) do {:ok, rendered} -> rendered :error -> block end @@ -528,7 +559,7 @@ defmodule Phoenix.LiveView.Engine do end defp to_conditional_var(keys, var, live_struct) when keys == %{} do - quote do + quote generated: true do unquote(var) = case changed do %{} -> nil @@ -559,10 +590,10 @@ defmodule Phoenix.LiveView.Engine do [assign | tail] -> quote do unquote(__MODULE__).nested_changed_assign?( - unquote(@assigns_var), - changed, + unquote(tail), unquote(assign), - unquote(tail) + unquote(@assigns_var), + changed ) end end @@ -591,7 +622,7 @@ defmodule Phoenix.LiveView.Engine do ## Component keys change tracking - defp to_component_tracking(fun, expr, extra, vars) do + defp to_component_tracking(meta, fun, expr, extra, vars, caller) do # Separate static and dynamic parts {static, dynamic} = case expr do @@ -622,7 +653,7 @@ defmodule Phoenix.LiveView.Engine do for {key, value} <- static_extra, # We pass empty assigns because if this code is rendered, # it means that upstream assigns were change tracked. - {_, keys, _} = analyze_and_return_tainted_keys(value, vars, %{}), + {_, keys, _} = analyze_and_return_tainted_keys(value, vars, %{}, caller), # If keys are empty, it is never changed. keys != %{}, do: {key, to_component_keys(keys)} @@ -634,7 +665,7 @@ defmodule Phoenix.LiveView.Engine do Macro.escape(%{}) end - static = slots_to_rendered(static, vars) + static = slots_to_rendered(static, vars, caller, Keyword.get(meta, :slots, [])) cond do # We can't infer anything, so return the expression as is. @@ -658,7 +689,7 @@ defmodule Phoenix.LiveView.Engine do # Merge both static and dynamic. true -> - {_, keys, _} = analyze_and_return_tainted_keys(dynamic, vars, %{}) + {_, keys, _} = analyze_and_return_tainted_keys(dynamic, vars, %{}, caller) quote do unquote(__MODULE__).to_component_dynamic( @@ -713,29 +744,60 @@ defmodule Phoenix.LiveView.Engine do defp component_changed([path], assigns, changed) do case path do [key] -> changed_assign(changed, key) - [key | tail] -> nested_changed_assign(assigns, changed, key, tail) + [key | tail] -> nested_changed_assign(tail, key, assigns, changed) end end defp component_changed(entries, assigns, changed) do Enum.any?(entries, fn [key] -> changed_assign?(changed, key) - [key | tail] -> nested_changed_assign?(assigns, changed, key, tail) + [key | tail] -> nested_changed_assign?(tail, key, assigns, changed) end) end - defp slots_to_rendered(static, vars) do - Macro.postwalk(static, fn - {call, meta, [name, [do: block]]} = node -> - if extract_call(call) == :slot do - {call, meta, [name, [do: maybe_block_to_rendered(block, vars)]]} + defp slots_to_rendered(static, vars, caller, slots) do + for {key, value} <- static do + value = + if key in slots do + slot_to_rendered(value, key, vars, caller) else - node + value end - node -> - node - end) + {key, value} + end + end + + defp slot_to_rendered( + {:%{}, map_meta, [__slot__: key, inner_block: inner_block] ++ attrs} = maybe_slot, + key, + vars, + caller + ) do + with {call, meta, [^key, [do: block]]} <- inner_block, + :inner_block <- extract_call(call) do + inner_block = {call, meta, [key, [do: maybe_block_to_rendered(block, vars, caller)]]} + + {:%{}, map_meta, [__slot__: key, inner_block: inner_block] ++ attrs} + else + _ -> maybe_slot + end + end + + defp slot_to_rendered({left, meta, args}, key, vars, caller) do + {left, meta, slot_to_rendered(args, key, vars, caller)} + end + + defp slot_to_rendered({left, right}, key, vars, caller) do + {slot_to_rendered(left, key, vars, caller), slot_to_rendered(right, key, vars, caller)} + end + + defp slot_to_rendered(list, key, vars, caller) when is_list(list) do + Enum.map(list, &slot_to_rendered(&1, key, vars, caller)) + end + + defp slot_to_rendered(other, _key, _vars, _caller) do + other end ## Extracts binaries and variable from iodata @@ -776,174 +838,216 @@ defmodule Phoenix.LiveView.Engine do # because it is disabled under certain special forms. There is also # strong-tainting, which are always computed. Strong-tainting only happens # if the `assigns` variable is used. - defp analyze_and_return_tainted_keys(ast, vars, assigns) do - {ast, vars, assigns} = analyze(ast, vars, assigns) + defp analyze_and_return_tainted_keys(ast, vars, assigns, caller) do + {ast, vars, assigns} = analyze(ast, vars, assigns, caller) {tainted_assigns?, assigns} = Map.pop(assigns, __MODULE__, false) keys = if match?({:tainted, _}, vars) or tainted_assigns?, do: :all, else: assigns {ast, keys, vars} end - # Nested assign - defp analyze_assign({{:., dot_meta, [Access, :get]}, meta, [left, right]}, vars, assigns, nest) do - {args, vars, assigns} = - if Macro.quoted_literal?(right) do - {left, vars, assigns} = analyze_assign(left, vars, assigns, [{:access, right} | nest]) - {[left, right], vars, assigns} - else - {left, vars, assigns} = analyze(left, vars, assigns) - {right, vars, assigns} = analyze(right, vars, assigns) - {[left, right], vars, assigns} - end - - {{{:., dot_meta, [Access, :get]}, meta, args}, vars, assigns} - end - - defp analyze_assign({{:., dot_meta, [left, right]}, meta, []}, vars, assigns, nest) do - {left, vars, assigns} = analyze_assign(left, vars, assigns, [{:struct, right} | nest]) - {{{:., dot_meta, [left, right]}, meta, []}, vars, assigns} - end - - # Non-expanded assign - defp analyze_assign({:@, meta, [{name, _, context}]}, vars, assigns, nest) + # @name + defp analyze_assign({:@, meta, [{name, _, context}]}, vars, assigns, _caller, nest) when is_atom(name) and is_atom(context) do - expr = - quote line: meta[:line] || 0 do - unquote(__MODULE__).fetch_assign!(unquote(@assigns_var), unquote(name)) - end + expr = {{:., meta, [@assigns_var, name]}, [no_parens: true] ++ meta, []} + {expr, vars, Map.put(assigns, [name | nest], true)} + end + # assigns.name + defp analyze_assign( + {{:., _, [{:assigns, _, nil}, name]}, _, args} = expr, + vars, + assigns, + _caller, + nest + ) + when is_atom(name) and args in [[], nil] do {expr, vars, Map.put(assigns, [name | nest], true)} end - # Expanded assign access. The non-expanded form is handled on root, - # then all further traversals happen on the expanded form + # assigns[:name] defp analyze_assign( - {{:., _, [__MODULE__, :fetch_assign!]}, _, [{:assigns, _, nil}, name]} = expr, + {{:., _, [Access, :get]}, _, [{:assigns, _, nil}, name]} = expr, vars, assigns, + _caller, nest ) when is_atom(name) do {expr, vars, Map.put(assigns, [name | nest], true)} end - defp analyze_assign(expr, vars, assigns, _nest) do - analyze(expr, vars, assigns) + # Maybe: assigns.foo[:bar] + defp analyze_assign( + {{:., dot_meta, [Access, :get]}, meta, [left, right]}, + vars, + assigns, + caller, + nest + ) do + {args, vars, assigns} = + if Macro.quoted_literal?(right) do + {left, vars, assigns} = + analyze_assign(left, vars, assigns, caller, [{:access, right} | nest]) + + {[left, right], vars, assigns} + else + {left, vars, assigns} = analyze(left, vars, assigns, caller) + {right, vars, assigns} = analyze(right, vars, assigns, caller) + {[left, right], vars, assigns} + end + + {{{:., dot_meta, [Access, :get]}, meta, args}, vars, assigns} + end + + # Maybe: assigns.foo.bar + defp analyze_assign({{:., dot_meta, [left, right]}, meta, args}, vars, assigns, caller, nest) + when args in [[], nil] do + {left, vars, assigns} = analyze_assign(left, vars, assigns, caller, [{:struct, right} | nest]) + {{{:., dot_meta, [left, right]}, meta, []}, vars, assigns} end - # Delegates to analyze assign - defp analyze({{:., _, [Access, :get]}, _, [_, _]} = expr, vars, assigns) do - analyze_assign(expr, vars, assigns, []) + defp analyze_assign(expr, vars, assigns, caller, _nest) do + analyze(expr, vars, assigns, caller) end - defp analyze({{:., _, [_, _]}, _, []} = expr, vars, assigns) do - analyze_assign(expr, vars, assigns, []) + # Delegates to analyze assign + defp analyze({{:., _, [Access, :get]}, _, [_, _]} = expr, vars, assigns, caller) do + analyze_assign(expr, vars, assigns, caller, []) end - defp analyze({:@, _, [{name, _, context}]} = expr, vars, assigns) - when is_atom(name) and is_atom(context) do - analyze_assign(expr, vars, assigns, []) + defp analyze({{:., _, [_, _]}, _, args} = expr, vars, assigns, caller) when args in [[], nil] do + analyze_assign(expr, vars, assigns, caller, []) end - defp analyze( - {{:., _, [__MODULE__, :fetch_assign!]}, _, [{:assigns, _, nil}, name]} = expr, - vars, - assigns - ) - when is_atom(name) do - analyze_assign(expr, vars, assigns, []) + defp analyze({:@, _, [{name, _, context}]} = expr, vars, assigns, caller) + when is_atom(name) and is_atom(context) do + analyze_assign(expr, vars, assigns, caller, []) end # Assigns is a strong-taint - defp analyze({:assigns, _, nil} = expr, vars, assigns) do + defp analyze({:assigns, _, nil} = expr, vars, assigns, _caller) do {expr, vars, taint_assigns(assigns)} end # Our own vars are ignored. They appear from nested do/end in EEx templates. - defp analyze({_, _, __MODULE__} = expr, vars, assigns) do + defp analyze({_, _, __MODULE__} = expr, vars, assigns, _caller) do {expr, vars, assigns} end # Ignore underscore - defp analyze({:_, _, context} = expr, vars, assigns) when is_atom(context) do + defp analyze({:_, _, context} = expr, vars, assigns, _caller) when is_atom(context) do {expr, vars, assigns} end # Also skip special variables - defp analyze({name, _, context} = expr, vars, assigns) + defp analyze({name, _, context} = expr, vars, assigns, _caller) when name in [:__MODULE__, :__ENV__, :__STACKTRACE__, :__DIR__] and is_atom(context) do {expr, vars, assigns} end # Vars always taint unless we are in restricted mode. - defp analyze({name, _, context} = expr, {:restricted, map}, assigns) + defp analyze({name, meta, context} = expr, {:restricted, map}, assigns, caller) when is_atom(name) and is_atom(context) do if Map.has_key?(map, {name, context}) do + maybe_warn_taint(name, meta, context, caller) {expr, {:tainted, map}, assigns} else {expr, {:restricted, map}, assigns} end end - defp analyze({name, _, context} = expr, {_, map}, assigns) + defp analyze({name, meta, context} = expr, {_, map}, assigns, caller) when is_atom(name) and is_atom(context) do + maybe_warn_taint(name, meta, context, caller) {expr, {:tainted, Map.put(map, {name, context}, true)}, assigns} end # Ignore binary modifiers - defp analyze({:"::", meta, [left, right]}, vars, assigns) do - {left, vars, assigns} = analyze(left, vars, assigns) + defp analyze({:"::", meta, [left, right]}, vars, assigns, caller) do + {left, vars, assigns} = analyze(left, vars, assigns, caller) {{:"::", meta, [left, right]}, vars, assigns} end + # Handle for/with to consider the first generator. + # Ideally we would track all variables on the patterns and expand all generators + # but except for the unlikely scenario of combinations, all comprehensions will + # be using nested generators. + defp analyze({for_with, meta, [{:<-, arrow_meta, [left, right]} | args]}, vars, assigns, caller) + when for_with in [:for, :with] do + {right, vars, assigns} = analyze(right, vars, assigns, caller) + + {[left | args], vars, assigns} = + analyze_with_restricted_vars([left | args], vars, assigns, caller) + + {{for_with, meta, [{:<-, arrow_meta, [left, right]} | args]}, vars, assigns} + end + # Classify calls - defp analyze({left, meta, args} = expr, vars, assigns) do + defp analyze({left, meta, args}, vars, assigns, caller) do call = extract_call(left) case classify_taint(call, args) do - :always -> - case vars do - {:restricted, _} -> {expr, vars, assigns} - {_, map} -> {expr, {:tainted, map}, assigns} - end - - :render -> - {args, [opts]} = Enum.split(args, -1) - {args, vars, assigns} = analyze_list(args, vars, assigns, []) - {opts, vars, assigns} = analyze_with_restricted_vars(opts, vars, assigns) - {{left, meta, args ++ [opts]}, vars, assigns} + :special_form -> + code = quote do: unquote(__MODULE__).__raise__(unquote(call), unquote(length(args))) + {code, vars, assigns} :none -> - {left, vars, assigns} = analyze(left, vars, assigns) - {args, vars, assigns} = analyze_list(args, vars, assigns, []) + {left, vars, assigns} = analyze(left, vars, assigns, caller) + {args, vars, assigns} = analyze_list(args, vars, assigns, caller, []) {{left, meta, args}, vars, assigns} - # :never or :live - _ -> - {args, vars, assigns} = analyze_with_restricted_vars(args, vars, assigns) + :live -> + {args, [opts]} = Enum.split(args, -1) + {args, vars, assigns} = analyze_skip_assignment_list(args, vars, assigns, caller, []) + {opts, vars, assigns} = analyze_with_restricted_vars(opts, vars, assigns, caller) + {{left, meta, args ++ [opts]}, vars, assigns} + + :never -> + {args, vars, assigns} = analyze_with_restricted_vars(args, vars, assigns, caller) {{left, meta, args}, vars, assigns} end end - defp analyze({left, right}, vars, assigns) do - {left, vars, assigns} = analyze(left, vars, assigns) - {right, vars, assigns} = analyze(right, vars, assigns) + defp analyze({left, right}, vars, assigns, caller) do + {left, vars, assigns} = analyze(left, vars, assigns, caller) + {right, vars, assigns} = analyze(right, vars, assigns, caller) {{left, right}, vars, assigns} end - defp analyze([_ | _] = list, vars, assigns) do - analyze_list(list, vars, assigns, []) + defp analyze([_ | _] = list, vars, assigns, caller) do + analyze_list(list, vars, assigns, caller, []) end - defp analyze(other, vars, assigns) do + defp analyze(other, vars, assigns, _caller) do {other, vars, assigns} end - defp analyze_list([head | tail], vars, assigns, acc) do - {head, vars, assigns} = analyze(head, vars, assigns) - analyze_list(tail, vars, assigns, [head | acc]) + defp analyze_list([head | tail], vars, assigns, caller, acc) do + {head, vars, assigns} = analyze(head, vars, assigns, caller) + analyze_list(tail, vars, assigns, caller, [head | acc]) + end + + defp analyze_list([], vars, assigns, _caller, acc) do + {Enum.reverse(acc), vars, assigns} + end + + defp analyze_skip_assignment_list( + [{:=, meta, [left, right]} | tail], + vars, + assigns, + caller, + acc + ) do + {right, vars, assigns} = analyze(right, vars, assigns, caller) + analyze_skip_assignment_list(tail, vars, assigns, caller, [{:=, meta, [left, right]} | acc]) + end + + defp analyze_skip_assignment_list([head | tail], vars, assigns, caller, acc) do + {head, vars, assigns} = analyze(head, vars, assigns, caller) + analyze_skip_assignment_list(tail, vars, assigns, caller, [head | acc]) end - defp analyze_list([], vars, assigns, acc) do + defp analyze_skip_assignment_list([], vars, assigns, _caller, acc) do {Enum.reverse(acc), vars, assigns} end @@ -958,9 +1062,9 @@ defmodule Phoenix.LiveView.Engine do # tainted if it came from outside of the case/cond/with/fn/try. # So for those constructs we set the mode to restricted and stop # collecting vars. - defp analyze_with_restricted_vars(ast, {kind, map}, assigns) do + defp analyze_with_restricted_vars(ast, {kind, map}, assigns, caller) do {ast, {new_kind, _}, assigns} = - analyze(ast, {unless_tainted(kind, :restricted), map}, assigns) + analyze(ast, {unless_tainted(kind, :restricted), map}, assigns, caller) {ast, {unless_tainted(new_kind, kind), map}, assigns} end @@ -976,7 +1080,42 @@ defmodule Phoenix.LiveView.Engine do ## Callbacks + defp maybe_warn_taint(name, meta, context, caller) do + if caller && Macro.Env.has_var?(caller, {name, context}) do + message = """ + you are accessing the variable \"#{name}\" inside a LiveView template. + + Using variables in HEEx templates are discouraged as they disable change tracking. \ + You are only allowed to access variables defined by Elixir control-flow structures, \ + such as if/case/for, or those defined by the special attributes :let/:if/:for. \ + If you are shadowing a variable defined outside of the template using a control-flow \ + structure, you must choose a unique variable name within the template. + + Instead of: + + def add(assigns) do + result = assigns.a + assigns.b + ~H"the result is: <%= result %>" + end + + You must do: + + def add(assigns) do + assigns = assign(assigns, :result, assigns.a + assigns.b) + ~H"the result is: <%= @result %>" + end + """ + + line = meta[:line] || caller.line + IO.warn(message, Macro.Env.stacktrace(%{caller | line: line})) + end + end + defp fingerprint(block, static) do + # The fingerprint must be unique and we don’t check for collisions in the + # Diff module as doing so would be expensive. Therefore it is important + # that the algorithm we use here has a low number of collisions. + <> = [block | static] |> :erlang.term_to_binary() @@ -985,6 +1124,12 @@ defmodule Phoenix.LiveView.Engine do fingerprint end + @doc false + defmacro __raise__(special_form, arity) do + message = "cannot invoke special form #{special_form}/#{arity} inside HEEx templates" + reraise ArgumentError.exception(message), Macro.Env.stacktrace(__CALLER__) + end + @doc false defmacro to_safe(ast) do to_safe(ast, false) @@ -1010,8 +1155,7 @@ defmodule Phoenix.LiveView.Engine do # Calls to attributes escape is always safe defp to_safe( - {{:., _, [{:__aliases__, _, [:Phoenix, :HTML, :Tag]}, :attributes_escape]}, _, [_]} = - safe, + {{:., _, [{:__aliases__, _, [:Phoenix, :HTML]}, :attributes_escape]}, _, [_]} = safe, line, _extra_clauses? ) do @@ -1050,7 +1194,13 @@ defmodule Phoenix.LiveView.Engine do end @doc false - def changed_assign?(changed, name), do: changed_assign(changed, name) != false + def changed_assign?(changed, name) do + case changed do + %{^name => _} -> true + %{} -> false + nil -> true + end + end defp changed_assign(changed, name) do case changed do @@ -1061,14 +1211,14 @@ defmodule Phoenix.LiveView.Engine do end @doc false - def nested_changed_assign?(assigns, changed, head, tail), - do: nested_changed_assign(assigns, changed, head, tail) != false + def nested_changed_assign?(tail, head, assigns, changed), + do: nested_changed_assign(tail, head, assigns, changed) != false - defp nested_changed_assign(assigns, changed, head, tail) do + defp nested_changed_assign(tail, head, assigns, changed) do case changed do %{^head => changed} -> case assigns do - %{^head => assigns} -> recur_changed_assign(assigns, changed, tail) + %{^head => assigns} -> recur_changed_assign(tail, assigns, changed) %{} -> true end @@ -1080,19 +1230,23 @@ defmodule Phoenix.LiveView.Engine do end end - defp recur_changed_assign(assigns, changed, [{:struct, head} | tail]) do - recur_changed_assign(assigns, changed, head, tail) + defp recur_changed_assign([{:struct, head} | tail], assigns, changed) do + recur_changed_assign(tail, head, assigns, changed) + end + + defp recur_changed_assign([{:access, head}], %Form{} = form1, %Form{} = form2) do + Form.input_changed?(form1, form2, head) end - defp recur_changed_assign(assigns, changed, [{:access, head} | tail]) do + defp recur_changed_assign([{:access, head} | tail], assigns, changed) do if match?(%_{}, assigns) or match?(%_{}, changed) do true else - recur_changed_assign(assigns, changed, head, tail) + recur_changed_assign(tail, head, assigns, changed) end end - defp recur_changed_assign(assigns, changed, head, []) do + defp recur_changed_assign([], head, assigns, changed) do case {assigns, changed} do {%{^head => value}, %{^head => value}} -> false {_, %{^head => value}} when is_map(value) -> value @@ -1100,80 +1254,48 @@ defmodule Phoenix.LiveView.Engine do end end - defp recur_changed_assign(assigns, changed, head, tail) do + defp recur_changed_assign(tail, head, assigns, changed) do case {assigns, changed} do {%{^head => assigns_value}, %{^head => changed_value}} -> - recur_changed_assign(assigns_value, changed_value, tail) + recur_changed_assign(tail, assigns_value, changed_value) {_, _} -> true end end - @doc false - def fetch_assign!(assigns, key) do - case assigns do - %{^key => val} -> - val - - %{} when key == :inner_block -> - raise ArgumentError, """ - assign @#{key} not available in template. - - This means a component requires a do-block or HTML children to - be given as argument but none were given. For example, instead of: - - <.component /> - - You must do: - - <.component> - more content - - - Available assigns: #{inspect(Enum.map(assigns, &elem(&1, 0)))} - """ - - %{} -> - raise ArgumentError, """ - assign @#{key} not available in template. - - Please make sure all proper assigns have been set. If you are - calling a component, make sure you are passing all required - assigns as arguments. - - Available assigns: #{inspect(Enum.map(assigns, &elem(&1, 0)))} - """ - end - end - - # For case/if/unless, we are not leaking the variable given as argument, - # such as `if var = ... do`. This does not follow Elixir semantics, but - # yields better optimizations. + # For case/if/unless in particular, we are not leaking the + # variables defined in arguments, such as `if var = ... do`. + # This does not follow Elixir semantics, but yields better + # optimizations. defp classify_taint(:case, [_, _]), do: :live defp classify_taint(:if, [_, _]), do: :live defp classify_taint(:unless, [_, _]), do: :live defp classify_taint(:cond, [_]), do: :live defp classify_taint(:try, [_]), do: :live defp classify_taint(:receive, [_]), do: :live + + # with/for are specially handled during analyze defp classify_taint(:with, _), do: :live + defp classify_taint(:for, _), do: :live + + # Constructs from Phoenix and TagEngine + defp classify_taint(:inner_block, [_, [do: _]]), do: :live + defp classify_taint(:render_layout, [_, _, _, [do: _]]), do: :live # TODO: Remove me when live_component/2/3 are removed - defp classify_taint(:live_component, [_, [do: _]]), do: :render - defp classify_taint(:live_component, [_, _, [do: _]]), do: :render - defp classify_taint(:slot, [_, [do: _]]), do: :render - defp classify_taint(:render_layout, [_, _, _, [do: _]]), do: :render - - defp classify_taint(:alias, [_]), do: :always - defp classify_taint(:import, [_]), do: :always - defp classify_taint(:require, [_]), do: :always - defp classify_taint(:alias, [_, _]), do: :always - defp classify_taint(:import, [_, _]), do: :always - defp classify_taint(:require, [_, _]), do: :always + defp classify_taint(:live_component, [_, [do: _]]), do: :live + defp classify_taint(:live_component, [_, _, [do: _]]), do: :live + + # Special forms are forbidden and raise. + defp classify_taint(:alias, [_]), do: :special_form + defp classify_taint(:import, [_]), do: :special_form + defp classify_taint(:require, [_]), do: :special_form + defp classify_taint(:alias, [_, _]), do: :special_form + defp classify_taint(:import, [_, _]), do: :special_form + defp classify_taint(:require, [_, _]), do: :special_form defp classify_taint(:&, [_]), do: :never - defp classify_taint(:for, _), do: :never defp classify_taint(:fn, _), do: :never - defp classify_taint(_, _), do: :none end diff --git a/lib/phoenix_live_view/helpers.ex b/lib/phoenix_live_view/helpers.ex index 6941c900f4..13dfec667a 100644 --- a/lib/phoenix_live_view/helpers.ex +++ b/lib/phoenix_live_view/helpers.ex @@ -1,12 +1,8 @@ defmodule Phoenix.LiveView.Helpers do - @moduledoc """ - A collection of helpers to be imported into your views. - """ - - # TODO: Convert all functions with the `live_` prefix to function components? + @moduledoc false + import Phoenix.Component - alias Phoenix.LiveView - alias Phoenix.LiveView.{Component, Socket, Static} + alias Phoenix.LiveView.{Component, Socket} @doc """ Provides `~L` sigil with HTML safe Live EEx syntax inside source files. @@ -29,214 +25,12 @@ defmodule Phoenix.LiveView.Helpers do EEx.compile_string(expr, options) end - @doc ~S''' - Provides `~H` sigil with HTML-safe and HTML-aware syntax inside source files. - - > Note: `HEEx` requires Elixir >= `1.12.0` in order to provide accurate - > file:line:column information in error messages. Earlier Elixir versions will - > work but will show inaccurate error messages. - - `HEEx` is a HTML-aware and component-friendly extension of `EEx` that provides: - - * Built-in handling of HTML attributes - * An HTML-like notation for injecting function components - * Compile-time validation of the structure of the template - * The ability to minimize the amount of data sent over the wire - - ## Example - - ~H""" -
-

Hello <%= @name %>

- -
- """ - - ## Syntax - - `HEEx` is built on top of Embedded Elixir (`EEx`), a templating syntax that uses - `<%= ... %>` for interpolating results. In this section, we are going to cover the - basic constructs in `HEEx` templates as well as its syntax extensions. - - ### Interpolation - - Both `HEEx` and `EEx` templates use `<%= ... %>` for interpolating code inside the body - of HTML tags: - -

Hello, <%= @name %>

- - Similarly, conditionals and other block Elixir constructs are supported: - - <%= if @show_greeting? do %> -

Hello, <%= @name %>

- <% end %> - - Note we don't include the equal sign `=` in the closing `<% end %>` tag - (because the closing tag does not output anything). - - There is one important difference between `HEEx` and Elixir's builtin `EEx`. - `HEEx` uses a specific annotation for interpolating HTML tags and attributes. - Let's check it out. - - ### HEEx extension: Defining attributes - - Since `HEEx` must parse and validate the HTML structure, code interpolation using - `<%= ... %>` and `<% ... %>` are restricted to the body (inner content) of the - HTML/component nodes and it cannot be applied within tags. - - For instance, the following syntax is invalid: - -
- ... -
- - Instead do: - -
- ... -
- - You can put any Elixir expression between `{ ... }`. For example, if you want - to set classes, where some are static and others are dynamic, you can using - string interpolation: - -
- ... -
- - For multiple dynamic attributes, you can use the same notation but without - assigning the expression to any specific attribute. - -
- ... -
- - The expression inside `{...}` must be either a keyword list or a map containing - the key-value pairs representing the dynamic attributes. - - ### HEEx extension: Defining function components - - Function components are stateless components implemented as pure functions - with the help of the `Phoenix.Component` module. They can be either local - (same module) or remote (external module). - - `HEEx` allows invoking these function components directly in the template - using an HTML-like notation. For example, a remote function: - - - - A local function can be invoked with a leading dot: - - <.city name="Kraków"/> - - where the component could be defined as follows: - - defmodule MyApp.Weather do - use Phoenix.Component - - def city(assigns) do - ~H""" - The chosen city is: <%= @name %>. - """ - end - - def country(assigns) do - ~H""" - The chosen country is: <%= @name %>. - """ - end - end - - It is typically best to group related functions into a single module, as - opposed to having many modules with a single `render/1` function. Function - components support other important features, such as slots. You can learn - more about components in `Phoenix.Component`. - ''' - defmacro sigil_H({:<<>>, meta, [expr]}, []) do - options = [ - engine: Phoenix.LiveView.HTMLEngine, - file: __CALLER__.file, - line: __CALLER__.line + 1, - module: __CALLER__.module, - indentation: meta[:indentation] || 0 - ] - - EEx.compile_string(expr, options) - end - - @doc ~S''' - Filters the assigns as a list of keywords for use in dynamic tag attributes. - - Useful for transforming caller assigns into dynamic attributes while - stripping reserved keys from the result. - - ## Examples - - Imagine the following `my_link` component which allows a caller - to pass a `new_window` assign, along with any other attributes they - would like to add to the element, such as class, data attributes, etc: - - <.my_link href="/" id={@id} new_window={true} class="my-class">Home - - We could support the dynamic attributes with the following component: - - def my_link(assigns) do - target = if assigns[:new_window], do: "_blank", else: false - extra = assigns_to_attributes(assigns, [:new_window]) - - assigns = - assigns - |> Phoenix.LiveView.assign(:target, target) - |> Phoenix.LiveView.assign(:extra, extra) - - ~H""" - - <%= render_slot(@inner_block) %> - - """ - end - - The optional second argument to `assigns_to_attributes` takes a list of keys to exclude - which will typically be the keys reserved by the component itself which either - do not belong in the markup, or are already handled explicitly by the component. - ''' - def assigns_to_attributes(assigns, exclude \\ []) do - excluded_keys = [:__changed__, :__slot__, :inner_block] ++ exclude - for {key, val} <- assigns, key not in excluded_keys, into: [], do: {key, val} - end - - @doc false + @doc deprecated: "Use link/1 instead" def live_patch(opts) when is_list(opts) do live_link("patch", Keyword.fetch!(opts, :do), Keyword.delete(opts, :do)) end - @doc """ - Generates a link that will patch the current LiveView. - - When navigating to the current LiveView, - `c:Phoenix.LiveView.handle_params/3` is - immediately invoked to handle the change of params and URL state. - Then the new state is pushed to the client, without reloading the - whole page while also maintaining the current scroll position. - For live redirects to another LiveView, use `live_redirect/2`. - - ## Options - - * `:to` - the required path to link to. - * `:replace` - the flag to replace the current history or push a new state. - Defaults `false`. - - All other options are forwarded to the anchor tag. - - ## Examples - - <%= live_patch "home", to: Routes.page_path(@socket, :index) %> - <%= live_patch "next", to: Routes.live_path(@socket, MyLive, @page + 1) %> - <%= live_patch to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %> - Sort By Price - <% end %> - - """ + @doc deprecated: "Use <.link> instead" def live_patch(text, opts) def live_patch(%Socket{}, _) do @@ -256,41 +50,12 @@ defmodule Phoenix.LiveView.Helpers do live_link("patch", text, opts) end - @doc false + @doc deprecated: "Use <.link> instead" def live_redirect(opts) when is_list(opts) do live_link("redirect", Keyword.fetch!(opts, :do), Keyword.delete(opts, :do)) end - @doc """ - Generates a link that will redirect to a new LiveView of the same live session. - - The current LiveView will be shut down and a new one will be mounted - in its place, without reloading the whole page. This can - also be used to remount the same LiveView, in case you want to start - fresh. If you want to navigate to the same LiveView without remounting - it, use `live_patch/2` instead. - - *Note*: The live redirects are only supported between two LiveViews defined - under the same live session. See `Phoenix.LiveView.Router.live_session/3` for - more details. - - ## Options - - * `:to` - the required path to link to. - * `:replace` - the flag to replace the current history or push a new state. - Defaults `false`. - - All other options are forwarded to the anchor tag. - - ## Examples - - <%= live_redirect "home", to: Routes.page_path(@socket, :index) %> - <%= live_redirect "next", to: Routes.live_path(@socket, MyLive, @page + 1) %> - <%= live_redirect to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %> - Sort By Price - <% end %> - - """ + @doc deprecated: "Use <.link> instead" def live_redirect(text, opts) def live_redirect(%Socket{}, _) do @@ -321,134 +86,11 @@ defmodule Phoenix.LiveView.Helpers do opts |> Keyword.update(:data, data, &Keyword.merge(&1, data)) |> Keyword.put(:href, uri) + |> Keyword.delete(:to) - Phoenix.HTML.Tag.content_tag(:a, Keyword.delete(opts, :to), do: block_or_text) - end - - @doc """ - Renders a LiveView within an originating plug request or - within a parent LiveView. - - ## Options - - * `:session` - the map of extra session data to be serialized - and sent to the client. Note that all session data currently in - the connection is automatically available in LiveViews. You - can use this option to provide extra data. Also note that the keys - in the session are strings keys, as a reminder that data has - to be serialized first. - * `:container` - an optional tuple for the HTML tag and DOM - attributes to be used for the LiveView container. For example: - `{:li, style: "color: blue;"}`. By default it uses the module - definition container. See the "Containers" section below for more - information. - * `:id` - both the DOM ID and the ID to uniquely identify a LiveView. - An `:id` is automatically generated when rendering root LiveViews - but it is a required option when rendering a child LiveView. - * `:router` - an optional router that enables this LiveView to - perform live navigation. Only a single LiveView in a page may - have the `:router` set. LiveViews defined at the router with - the `live` macro automatically have the `:router` option set. - - ## Examples - - # within eex template - <%= live_render(@conn, MyApp.ThermostatLive) %> - - # within leex template - <%= live_render(@socket, MyApp.ThermostatLive, id: "thermostat") %> - - ## Containers - - When a `LiveView` is rendered, its contents are wrapped in a container. - By default, said container is a `div` tag with a handful of `LiveView` - specific attributes. - - The container can be customized in different ways: - - * You can change the default `container` on `use Phoenix.LiveView`: - - use Phoenix.LiveView, container: {:tr, id: "foo-bar"} - - * You can override the container tag and pass extra attributes when - calling `live_render` (as well as on your `live` call in your router): - - live_render socket, MyLiveView, container: {:tr, class: "highlight"} - - """ - def live_render(conn_or_socket, view, opts \\ []) - - def live_render(%Plug.Conn{} = conn, view, opts) do - case Static.render(conn, view, opts) do - {:ok, content, _assigns} -> - content - - {:stop, _} -> - raise RuntimeError, "cannot redirect from a child LiveView" - end - end - - def live_render(%Socket{} = parent, view, opts) do - Static.nested_render(parent, view, opts) - end - - @doc """ - A function component for rendering `Phoenix.LiveComponent` - within a parent LiveView. - - While `LiveView`s can be nested, each LiveView starts its - own process. A `LiveComponent` provides similar functionality - to `LiveView`, except they run in the same process as the - `LiveView`, with its own encapsulated state. That's why they - are called stateful components. - - See `Phoenix.LiveComponent` for more information. + assigns = %{opts: opts, content: block_or_text} - ## Examples - - `.live_component` requires the component `:module` and its - `:id` to be given: - - <.live_component module={MyApp.WeatherComponent} id="thermostat" city="Kraków" /> - - The `:id` is used to identify this `LiveComponent` throughout the - LiveView lifecycle. Note the `:id` won't necessarily be used as the - DOM ID. That's up to the component. - """ - def live_component(assigns) when is_map(assigns) do - id = assigns[:id] - - {module, assigns} = - assigns - |> Map.delete(:__changed__) - |> Map.pop(:module) - - if module == nil or not is_atom(module) do - raise ArgumentError, - ".live_component expects module={...} to be given and to be an atom, " <> - "got: #{inspect(module)}" - end - - if id == nil do - raise ArgumentError, ".live_component expects id={...} to be given, got: nil" - end - - case module.__live__() do - %{kind: :component} -> - %Component{id: id, assigns: assigns, component: module} - - %{kind: kind} -> - raise ArgumentError, "expected #{inspect(module)} to be a component, but it is a #{kind}" - end - end - - def live_component(component) when is_atom(component) do - IO.warn( - "<%= live_component Component %> is deprecated, " <> - "please use <.live_component module={Component} id=\"hello\" /> inside HEEx templates instead" - ) - - Phoenix.LiveView.Helpers.__live_component__(component.__live__(), %{}, nil) + ~H|<%= @content %>| end @doc """ @@ -464,15 +106,19 @@ defmodule Phoenix.LiveView.Helpers do 2. Then instead of: - <%= live_component MyModule, id: "hello" do %> - ... - <% end %> + ``` + <%= live_component MyModule, id: "hello" do %> + ... + <% end %> + ``` You should do: - <.live_component module={MyModule} id="hello"> - ... - + ``` + <.live_component module={MyModule} id="hello"> + ... + + ``` 3. If your component is using `render_block/2`, replace it by `render_slot/2` @@ -549,45 +195,13 @@ defmodule Phoenix.LiveView.Helpers do raise "expected #{inspect(module)} to be a component, but it is a #{kind}" end - @doc """ - Renders a component defined by the given function. - - This function is rarely invoked directly by users. Instead, it is used by `~H` - to render `Phoenix.Component`s. For example, the following: - - - - It the same as: - - <%= component(&MyApp.Weather.city/1, name: "Kraków") %> - - """ - def component(func, assigns \\ []) - when (is_function(func, 1) and is_list(assigns)) or is_map(assigns) do - assigns = - case assigns do - %{__changed__: _} -> assigns - _ -> assigns |> Map.new() |> Map.put_new(:__changed__, nil) - end - - case func.(assigns) do - %Phoenix.LiveView.Rendered{} = rendered -> - rendered - - %Phoenix.LiveView.Component{} = component -> - component - - other -> - raise RuntimeError, """ - expected #{inspect(func)} to return a %Phoenix.LiveView.Rendered{} struct - - Ensure your render function uses ~H to define its template. - - Got: - - #{inspect(other)} - - """ + defp rewrite_do!(do_block, key, caller) do + if Macro.Env.has_var?(caller, {:assigns, nil}) do + # TODO: make __inner_block__ private once this is removed. + Phoenix.LiveView.TagEngine.__inner_block__(do_block, key) + else + raise ArgumentError, + "cannot use live_component because the assigns var is unbound/unset" end end @@ -613,300 +227,16 @@ defmodule Phoenix.LiveView.Helpers do def __render_block__([%{inner_block: fun}]), do: fun def __render_block__(fun), do: fun - @doc ~S''' - Renders a slot entry with the given optional `argument`. - - <%= render_slot(@inner_block, @form) %> - - If multiple slot entries are defined for the same slot, - `render_slot/2` will automatically render all entries, - merging their contents. In case you want to use the entries' - attributes, you need to iterate over the list to access each - slot individually. - - For example, imagine a table component: - - <.table rows={@users}> - <:col let={user} label="Name"> - <%= user.name %> - - - <:col let={user} label="Address"> - <%= user.address %> - - - - At the top level, we pass the rows as an assign and we define - a `:col` slot for each column we want in the table. Each - column also has a `label`, which we are going to use in the - table header. - - Inside the component, you can render the table with headers, - rows, and columns: - - def table(assigns) do - ~H""" - - - <% end > - - <%= for row <- @rows do %> - - <%= for col <- @col do %> - <%= render_slot(col, row) %> - <% end %> - - <% end %> -
- <%= for col <- @col do %> - <%= col.label %>
- """ - end - - ''' - defmacro render_slot(slot, argument \\ nil) do - quote do - unquote(__MODULE__).__render_slot__( - var!(changed, Phoenix.LiveView.Engine), - unquote(slot), - unquote(argument) - ) - end - end - - @doc false - def __render_slot__(_, [], _), do: "" - - def __render_slot__(changed, [entry], argument) do - call_inner_block!(entry, changed, argument) - end - - def __render_slot__(changed, entries, argument) when is_list(entries) do - assigns = %{} - - ~H""" - <%= for entry <- entries do %><%= call_inner_block!(entry, changed, argument) %><% end %> - """ - end - - def __render_slot__(changed, entry, argument) when is_map(entry) do - entry.inner_block.(changed, argument) - end - - defp call_inner_block!(entry, changed, argument) do - if !entry.inner_block do - message = "attempted to render slot <:#{entry.__slot__}> but the slot has no inner content" - raise RuntimeError, message - end - - entry.inner_block.(changed, argument) - end - - @doc """ - Defines a slot's inner block. - - This macro is mostly used by HTML engines that provides - a `slot` implementation and rarely called directly. - - If you're using HEEx templates, you should use its higher - level `<:slot>` notation instead. See `Phoenix.Component` - for more information. - """ - defmacro slot(name, do: do_block) do - rewrite_do!(do_block, name, __CALLER__) - end - - defp rewrite_do!(do_block, key, caller) do - if Macro.Env.has_var?(caller, {:assigns, nil}) do - rewrite_do(do_block, key) - else - raise ArgumentError, - "cannot use component/live_component because the assigns var is unbound/unset" - end - end - - defp rewrite_do([{:->, meta, _} | _] = do_block, key) do - inner_fun = {:fn, meta, do_block} - - quote do - fn parent_changed, arg -> - var!(assigns) = - unquote(__MODULE__).__assigns__(var!(assigns), unquote(key), parent_changed) - - _ = var!(assigns) - unquote(inner_fun).(arg) - end - end - end - - defp rewrite_do(do_block, key) do - quote do - fn parent_changed, arg -> - var!(assigns) = - unquote(__MODULE__).__assigns__(var!(assigns), unquote(key), parent_changed) - - _ = var!(assigns) - unquote(do_block) - end - end - end - - @doc false - def __assigns__(assigns, key, parent_changed) do - # If the component is in its initial render (parent_changed == nil) - # or the slot/block key in the parent_changed is true, then we render - # the function with the assigns as is. - # - # Otherwise, we will set changed to an empty list, which is the same - # as marking everything as not changed. This is correct because - # parent_changed will always be marked as changed whenever any of the - # assigns it references inside is changed. It will also be marked as - # changed if it has any variable (such as the ones coming from let). - if is_nil(parent_changed) or parent_changed[key] == true do - assigns - else - Map.put(assigns, :__changed__, %{}) - end - end - - @doc """ - Returns the flash message from the LiveView flash assign. - - ## Examples - -

<%= live_flash(@flash, :info) %>

-

<%= live_flash(@flash, :error) %>

- """ - def live_flash(%_struct{} = other, _key) do - raise ArgumentError, "live_flash/2 expects a @flash assign, got: #{inspect(other)}" + @doc deprecated: "Use <.live_img_preview /> instead" + def live_img_preview(entry, opts) do + live_img_preview(Enum.into(opts, %{entry: entry})) end - def live_flash(%{} = flash, key), do: Map.get(flash, to_string(key)) - - @doc """ - Returns the entry errors for an upload. - - The following errors may be returned: - - * `:too_many_files` - The number of selected files exceeds the `:max_entries` constraint - - ## Examples - - def error_to_string(:too_many_files), do: "You have selected too many files" - - <%= for err <- upload_errors(@uploads.avatar) do %> -
- <%= error_to_string(err) %> -
- <% end %> - """ - def upload_errors(%Phoenix.LiveView.UploadConfig{} = conf) do - for {ref, error} <- conf.errors, ref == conf.ref, do: error - end - - @doc """ - Returns the entry errors for an upload. - - The following errors may be returned: - - * `:too_large` - The entry exceeds the `:max_file_size` constraint - * `:not_accepted` - The entry does not match the `:accept` MIME types - - ## Examples - - def error_to_string(:too_large), do: "Too large" - def error_to_string(:not_accepted), do: "You have selected an unacceptable file type" - - <%= for entry <- @uploads.avatar.entries do %> - <%= for err <- upload_errors(@uploads.avatar, entry) do %> -
- <%= error_to_string(err) %> -
- <% end %> - <% end %> - """ - def upload_errors( - %Phoenix.LiveView.UploadConfig{} = conf, - %Phoenix.LiveView.UploadEntry{} = entry - ) do - for {ref, error} <- conf.errors, ref == entry.ref, do: error - end - - @doc """ - Generates an image preview on the client for a selected file. - - ## Examples - - <%= for entry <- @uploads.avatar.entries do %> - <%= live_img_preview entry, width: 75 %> - <% end %> - """ - def live_img_preview(%Phoenix.LiveView.UploadEntry{ref: ref} = entry, opts \\ []) do - attrs = - Keyword.merge(opts, - id: "phx-preview-#{ref}", - data_phx_upload_ref: entry.upload_ref, - data_phx_entry_ref: ref, - data_phx_hook: "Phoenix.LiveImgPreview", - data_phx_update: "ignore" - ) - - assigns = LiveView.assign(%{__changed__: nil}, attrs: attrs) - - ~H"" - end - - @doc """ - Builds a file input tag for a LiveView upload. - - Options may be passed through to the tag builder for custom attributes. - - ## Drag and Drop - - Drag and drop is supported by annotating the droppable container with a `phx-drop-target` - attribute pointing to the DOM ID of the file input. By default, the file input ID is the - upload `ref`, so the following markup is all that is required for drag and drop support: - -
- ... - <%= live_file_input @uploads.avatar %> -
- - ## Examples - - <%= live_file_input @uploads.avatar %> - """ - def live_file_input(%Phoenix.LiveView.UploadConfig{} = conf, opts \\ []) do - if opts[:id], do: raise(ArgumentError, "the :id cannot be overridden on a live_file_input") - - opts = - if conf.max_entries > 1 do - Keyword.put(opts, :multiple, true) - else - opts - end - - preflighted_entries = for entry <- conf.entries, entry.preflighted?, do: entry - done_entries = for entry <- conf.entries, entry.done?, do: entry - valid? = Enum.any?(conf.entries) && Enum.empty?(conf.errors) - - Phoenix.HTML.Tag.content_tag( - :input, - "", - Keyword.merge(opts, - type: "file", - id: conf.ref, - name: conf.name, - accept: if(conf.accept != :any, do: conf.accept), - phx_hook: "Phoenix.LiveFileUpload", - data_phx_update: "ignore", - data_phx_upload_ref: conf.ref, - data_phx_active_refs: Enum.map_join(conf.entries, ",", & &1.ref), - data_phx_done_refs: Enum.map_join(done_entries, ",", & &1.ref), - data_phx_preflighted_refs: Enum.map_join(preflighted_entries, ",", & &1.ref), - data_phx_auto_upload: valid? && conf.auto_upload? - ) - ) + @doc deprecated: "Use <.live_file_input /> instead" + def live_file_input(%Phoenix.LiveView.UploadConfig{} = conf, opts) when is_list(opts) do + require Phoenix.LiveViewTest + assigns = Enum.into(opts, %{upload: conf}) + {:safe, Phoenix.LiveViewTest.render_component(&live_file_input/1, assigns)} end @doc """ @@ -914,143 +244,22 @@ defmodule Phoenix.LiveView.Helpers do ## Examples - <%= live_title_tag assigns[:page_title] || "Welcome", prefix: "MyApp – " %> + <%= live_title_tag assigns[:page_title] || "Welcome", prefix: "MyApp – " %> - <%= live_title_tag assigns[:page_title] || "Welcome", suffix: " – MyApp" %> + <%= live_title_tag assigns[:page_title] || "Welcome", suffix: " – MyApp" %> """ + @doc deprecated: "Use <.live_title> instead" def live_title_tag(title, opts \\ []) do - title_tag(title, opts[:prefix], opts[:suffix], opts) - end - - defp title_tag(title, nil = _prefix, "" <> suffix, _opts) do - Phoenix.HTML.Tag.content_tag(:title, title <> suffix, data: [suffix: suffix]) - end - - defp title_tag(title, "" <> prefix, nil = _suffix, _opts) do - Phoenix.HTML.Tag.content_tag(:title, prefix <> title, data: [prefix: prefix]) - end - - defp title_tag(title, "" <> pre, "" <> post, _opts) do - Phoenix.HTML.Tag.content_tag(:title, pre <> title <> post, data: [prefix: pre, suffix: post]) - end - - defp title_tag(title, _prefix = nil, _postfix = nil, []) do - Phoenix.HTML.Tag.content_tag(:title, title) - end - - defp title_tag(_title, _prefix = nil, _suffix = nil, opts) do - raise ArgumentError, - "live_title_tag/2 expects a :prefix and/or :suffix option, got: #{inspect(opts)}" - end - - @doc """ - Renders a form function component. - - This function is built on top of `Phoenix.HTML.Form.form_for/4`. For - more information about options and how to build inputs, see - `Phoenix.HTML.Form`. - - ## Options - - The `:for` assign is the form's source data and the optional `:action` - assign can be provided for the form's action. Additionally accepts - the same options as `Phoenix.HTML.Form.form_for/4` as optional assigns: - - * `:as` - the server side parameter in which all params for this - form will be collected (i.e. `as: :user_params` would mean all fields - for this form will be accessed as `conn.params.user_params` server - side). Automatically inflected when a changeset is given. - - * `:method` - the HTTP method. If the method is not "get" nor "post", - an input tag with name `_method` is generated along-side the form tag. - Defaults to "post". - - * `:multipart` - when true, sets enctype to "multipart/form-data". - Required when uploading files - - * `:csrf_token` - for "post" requests, the form tag will automatically - include an input tag with name `_csrf_token`. When set to false, this - is disabled - - * `:errors` - use this to manually pass a keyword list of errors to the form - (for example from `conn.assigns[:errors]`). This option is only used when a - connection is used as the form source and it will make the errors available - under `f.errors` - - * `:id` - the ID of the form attribute. If an ID is given, all form inputs - will also be prefixed by the given ID - - All further assigns will be passed to the form tag. - - ## Examples - - <.form let={f} for={@changeset}> - <%= text_input f, :name %> - - - <.form let={user_form} for={@changeset} as="user" multipart {@extra}> - <%= text_input user_form, :name %> - - """ - def form(assigns) do - # Extract options and then to the same call as form_for - action = assigns[:action] || "#" - form_for = assigns[:for] || raise ArgumentError, "missing :for assign to form" - form_options = assigns_to_attributes(assigns, [:action, :for]) - - # Since FormData may add options, read the actual options from form - %{options: opts} = - form = %Phoenix.HTML.Form{ - Phoenix.HTML.FormData.to_form(form_for, form_options) - | action: action - } - - # And then process method, csrf_token, and multipart as in form_tag - {method, opts} = Keyword.pop(opts, :method, "post") - {method, hidden_method} = form_method(method) - - {csrf_token, opts} = - Keyword.pop_lazy(opts, :csrf_token, fn -> - if method == "post", do: Phoenix.HTML.Tag.csrf_token_value(action) - end) - - opts = - case Keyword.pop(opts, :multipart, false) do - {false, opts} -> opts - {true, opts} -> Keyword.put(opts, :enctype, "multipart/form-data") - end - - # Finally we can render the form - assigns = - LiveView.assign(assigns, - form: form, - csrf_token: csrf_token, - hidden_method: hidden_method, - attrs: [action: action, method: method] ++ opts - ) + assigns = %{title: title, prefix: opts[:prefix], suffix: opts[:suffix]} ~H""" -
- <%= if @hidden_method && @hidden_method not in ~w(get post) do %> - - <% end %> - <%= if @csrf_token do %> - - <% end %> - <%= render_slot(@inner_block, @form) %> -
+ <%= @title %> """ end - defp form_method(method) when method in ~w(get post), do: {method, nil} - defp form_method(method) when is_binary(method), do: {"post", method} - defp is_assign?(assign_name, expression) do match?({:@, _, [{^assign_name, _, _}]}, expression) or match?({^assign_name, _, _}, expression) or - match?( - {{:., _, [Phoenix.LiveView.Engine, :fetch_assign!]}, _, [{:assigns, _, _}, ^assign_name]}, - expression - ) + match?({{:., _, [{:assigns, _, nil}, ^assign_name]}, _, []}, expression) end end diff --git a/lib/phoenix_live_view/html_algebra.ex b/lib/phoenix_live_view/html_algebra.ex new file mode 100644 index 0000000000..82e42bfca4 --- /dev/null +++ b/lib/phoenix_live_view/html_algebra.ex @@ -0,0 +1,566 @@ +defmodule Phoenix.LiveView.HTMLAlgebra do + @moduledoc false + + import Inspect.Algebra, except: [format: 2] + + # TODO: Remove it after versions before Elixir 1.13 are no longer supported. + @compile {:no_warn_undefined, Code} + + @languages ~w(style script) + + # The formatter has two modes: + # + # * :normal + # * :preserve - for preserving text in 
, " <> rest, line, column, buffer, acc, state) do
     acc = [
-      {:tag_close, "script", %{line: line, column: column}}
-      | text_to_acc(buffer, acc, line, column)
+      {:close, :tag, "script", %{line: line, column: column, inner_location: {line, column}}}
+      | text_to_acc(buffer, acc, line, column, [])
     ]
 
     handle_text(rest, line, column + 9, [], acc, state)
@@ -134,29 +202,69 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
   end
 
   defp handle_script(<<>>, line, column, buffer, acc, _state) do
-    ok(text_to_acc(buffer, acc, line, column), :script)
+    ok(text_to_acc(buffer, acc, line, column, []), :script)
+  end
+
+  ## handle_style
+
+  defp handle_style("" <> rest, line, column, buffer, acc, state) do
+    acc = [
+      {:close, :tag, "style", %{line: line, column: column, inner_location: {line, column}}}
+      | text_to_acc(buffer, acc, line, column, [])
+    ]
+
+    handle_text(rest, line, column + 9, [], acc, state)
+  end
+
+  defp handle_style("\r\n" <> rest, line, _column, buffer, acc, state) do
+    handle_style(rest, line + 1, state.column_offset, ["\r\n" | buffer], acc, state)
+  end
+
+  defp handle_style("\n" <> rest, line, _column, buffer, acc, state) do
+    handle_style(rest, line + 1, state.column_offset, ["\n" | buffer], acc, state)
+  end
+
+  defp handle_style(<>, line, column, buffer, acc, state) do
+    handle_style(rest, line, column + 1, [char_or_bin(c) | buffer], acc, state)
+  end
+
+  defp handle_style(<<>>, line, column, buffer, acc, _state) do
+    ok(text_to_acc(buffer, acc, line, column, []), :style)
   end
 
   ## handle_comment
 
-  defp handle_comment("\r\n" <> rest, line, _column, buffer, acc, state) do
-    handle_comment(rest, line + 1, state.column_offset, ["\r\n" | buffer], acc, state)
+  defp handle_comment(rest, line, column, buffer, acc, state) do
+    case handle_comment(rest, line, column, buffer, state) do
+      {:text, rest, line, column, buffer} ->
+        state = update_in(state.context, &[:comment_end | &1])
+        handle_text(rest, line, column, buffer, acc, state)
+
+      {:ok, line_end, column_end, buffer} ->
+        acc = text_to_acc(buffer, acc, line_end, column_end, state.context)
+        # We do column - 4 to point to the opening " <> rest, line, column, buffer, acc, state) do
-    handle_text(rest, line, column + 3, ["-->" | buffer], acc, state)
+  defp handle_comment("-->" <> rest, line, column, buffer, _state) do
+    {:text, rest, line, column + 3, ["-->" | buffer]}
   end
 
-  defp handle_comment(<>, line, column, buffer, acc, state) do
-    handle_comment(rest, line, column + 1, [char_or_bin(c) | buffer], acc, state)
+  defp handle_comment(<>, line, column, buffer, state) do
+    handle_comment(rest, line, column + 1, [char_or_bin(c) | buffer], state)
   end
 
-  defp handle_comment(<<>>, line, column, buffer, acc, _state) do
-    ok(text_to_acc(buffer, acc, line, column), {:comment, line, column})
+  defp handle_comment(<<>>, line, column, buffer, _state) do
+    {:ok, line, column, buffer}
   end
 
   ## handle_tag_open
@@ -164,12 +272,24 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
   defp handle_tag_open(text, line, column, acc, state) do
     case handle_tag_name(text, column, []) do
       {:ok, name, new_column, rest} ->
-        acc = if strip_tag?(name), do: strip_text_token_partially(acc), else: acc
-        acc = [{:tag_open, name, [], %{line: line, column: column - 1}} | acc]
-        handle_maybe_tag_open_end(rest, line, new_column, acc, state)
+        meta = %{line: line, column: column - 1, inner_location: nil, tag_name: name}
 
-      {:error, message} ->
-        raise ParseError, file: state.file, line: line, column: column, description: message
+        case state.tag_handler.classify_type(name) do
+          {:error, message} ->
+            raise_syntax_error!(message, meta, state)
+
+          {type, name} ->
+            acc = [{type, name, [], meta} | acc]
+            handle_maybe_tag_open_end(rest, line, new_column, acc, state)
+        end
+
+      :error ->
+        message =
+          "expected tag name after <. If you meant to use < as part of a text, use < instead"
+
+        meta = %{line: line, column: column}
+
+        raise_syntax_error!(message, meta, state)
     end
   end
 
@@ -178,16 +298,31 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
   defp handle_tag_close(text, line, column, acc, state) do
     case handle_tag_name(text, column, []) do
       {:ok, name, new_column, ">" <> rest} ->
-        acc = [{:tag_close, name, %{line: line, column: column - 2}} | acc]
-        rest = if strip_tag?(name), do: String.trim_leading(rest), else: rest
-        handle_text(rest, line, new_column + 1, [], acc, state)
+        meta = %{
+          line: line,
+          column: column - 2,
+          inner_location: {line, column - 2},
+          tag_name: name
+        }
+
+        case state.tag_handler.classify_type(name) do
+          {:error, message} ->
+            raise_syntax_error!(message, meta, state)
+
+          {type, name} ->
+            acc = [{:close, type, name, meta} | acc]
+            handle_text(rest, line, new_column + 1, [], acc, state)
+        end
 
       {:ok, _, new_column, _} ->
         message = "expected closing `>`"
-        raise ParseError, file: state.file, line: line, column: new_column, description: message
+        meta = %{line: line, column: new_column}
+        raise_syntax_error!(message, meta, state)
 
-      {:error, message} ->
-        raise ParseError, file: state.file, line: line, column: column, description: message
+      :error ->
+        message = "expected tag name after " <> rest, line, column, acc, state) do
-    acc = reverse_attrs(acc)
+    acc = reverse_attrs(acc, line, column + 2)
     handle_text(rest, line, column + 2, [], put_self_close(acc), state)
   end
 
   defp handle_maybe_tag_open_end(">" <> rest, line, column, acc, state) do
-    case reverse_attrs(acc) do
-      [{:tag_open, "script", _, _} | _] = acc ->
+    case reverse_attrs(acc, line, column + 1) do
+      [{:tag, "script", _, _} | _] = acc ->
         handle_script(rest, line, column + 1, [], acc, state)
 
+      [{:tag, "style", _, _} | _] = acc ->
+        handle_style(rest, line, column + 1, [], acc, state)
+
       acc ->
         handle_text(rest, line, column + 1, [], acc, state)
     end
@@ -286,11 +424,12 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
   defp handle_attribute(text, line, column, acc, state) do
     case handle_attr_name(text, column, []) do
       {:ok, name, new_column, rest} ->
-        acc = put_attr(acc, name)
+        acc = put_attr(acc, name, %{line: line, column: column})
         handle_maybe_attr_value(rest, line, new_column, acc, state)
 
       {:error, message, column} ->
-        raise ParseError, file: state.file, line: line, column: column, description: message
+        meta = %{line: line, column: column}
+        raise_syntax_error!(message, meta, state)
     end
   end
 
@@ -299,11 +438,14 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
   defp handle_root_attribute(text, line, column, acc, state) do
     case handle_interpolation(text, line, column, [], state) do
       {:ok, value, new_line, new_column, rest, state} ->
-        acc = put_attr(acc, :root, {:expr, value, %{line: line, column: column}})
+        meta = %{line: line, column: column}
+        acc = put_attr(acc, :root, meta, {:expr, value, meta})
         handle_maybe_tag_open_end(rest, new_line, new_column, acc, state)
 
-      {:error, message, line, column} ->
-        raise ParseError, file: state.file, line: line, column: column, description: message
+      {:error, message} ->
+        # We do column - 1 to point to the opening {
+        meta = %{line: line, column: column - 1}
+        raise_syntax_error!(message, meta, state)
     end
   end
 
@@ -383,7 +525,8 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
       "invalid attribute value after `=`. Expected either a value between quotes " <>
         "(such as \"value\" or \'value\') or an Elixir expression between curly brackets (such as `{expr}`)"
 
-    raise ParseError, file: state.file, line: line, column: column, description: message
+    meta = %{line: line, column: column}
+    raise_syntax_error!(message, meta, state)
   end
 
   ## handle_attr_value_quote
@@ -427,7 +570,8 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
     Where @some_attributes must be a keyword list or a map.
     """
 
-    raise ParseError, file: state.file, line: line, column: column, description: message
+    meta = %{line: line, column: column}
+    raise_syntax_error!(message, meta, state)
   end
 
   ## handle_attr_value_as_expr
@@ -438,8 +582,10 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
         acc = put_attr_value(acc, {:expr, value, %{line: line, column: column}})
         handle_maybe_tag_open_end(rest, new_line, new_column, acc, state)
 
-      {:error, message, line, column} ->
-        raise ParseError, file: state.file, line: line, column: column, description: message
+      {:error, message} ->
+        # We do column - 1 to point to the opening {
+        meta = %{line: line, column: column - 1}
+        raise_syntax_error!(message, meta, state)
     end
   end
 
@@ -480,8 +626,8 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
     handle_interpolation(rest, line, column + 1, [char_or_bin(c) | buffer], state)
   end
 
-  defp handle_interpolation(<<>>, line, column, _buffer, _state) do
-    {:error, "expected closing `}` for expression", line, column}
+  defp handle_interpolation(<<>>, _line, _column, _buffer, _state) do
+    {:error, "expected closing `}` for expression"}
   end
 
   ## helpers
@@ -496,30 +642,49 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
     IO.iodata_to_binary(Enum.reverse(buffer))
   end
 
-  defp text_to_acc([], acc, _line, _column),
+  defp text_to_acc(buffer, acc, line, column, context)
+
+  defp text_to_acc([], acc, _line, _column, _context),
     do: acc
 
-  defp text_to_acc(buffer, acc, line, column),
-    do: [{:text, buffer_to_string(buffer), %{line_end: line, column_end: column}} | acc]
+  defp text_to_acc(buffer, acc, line, column, context) do
+    meta = %{line_end: line, column_end: column}
 
-  defp put_attr([{:tag_open, name, attrs, meta} | acc], attr, value \\ nil) do
-    attrs = [{attr, value} | attrs]
-    [{:tag_open, name, attrs, meta} | acc]
+    meta =
+      if context = get_context(context) do
+        Map.put(meta, :context, trim_context(context))
+      else
+        meta
+      end
+
+    [{:text, buffer_to_string(buffer), meta} | acc]
+  end
+
+  defp trim_context([:comment_start, :comment_end | [_ | _] = rest]), do: trim_context(rest)
+  defp trim_context(rest), do: rest
+
+  defp get_context([]), do: nil
+  defp get_context(context), do: Enum.reverse(context)
+
+  defp put_attr([{type, name, attrs, meta} | acc], attr, attr_meta, value \\ nil) do
+    attrs = [{attr, value, attr_meta} | attrs]
+    [{type, name, attrs, meta} | acc]
   end
 
-  defp put_attr_value([{:tag_open, name, [{attr, _value} | attrs], meta} | acc], value) do
-    attrs = [{attr, value} | attrs]
-    [{:tag_open, name, attrs, meta} | acc]
+  defp put_attr_value([{type, name, [{attr, _value, attr_meta} | attrs], meta} | acc], value) do
+    attrs = [{attr, value, attr_meta} | attrs]
+    [{type, name, attrs, meta} | acc]
   end
 
-  defp reverse_attrs([{:tag_open, name, attrs, meta} | acc]) do
+  defp reverse_attrs([{type, name, attrs, meta} | acc], line, column) do
     attrs = Enum.reverse(attrs)
-    [{:tag_open, name, attrs, meta} | acc]
+    meta = %{meta | inner_location: {line, column}}
+    [{type, name, attrs, meta} | acc]
   end
 
-  defp put_self_close([{:tag_open, name, attrs, meta} | acc]) do
+  defp put_self_close([{type, name, attrs, meta} | acc]) do
     meta = Map.put(meta, :self_close, true)
-    [{:tag_open, name, attrs, meta} | acc]
+    [{type, name, attrs, meta} | acc]
   end
 
   defp push_brace(state, pos) do
@@ -530,10 +695,6 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
     {pos, %{state | braces: braces}}
   end
 
-  # Strip space before slots
-  defp strip_tag?(":" <> _), do: true
-  defp strip_tag?(_), do: false
-
   defp strip_text_token_fully(tokens) do
     with [{:text, text, _} | rest] <- tokens,
          "" <- String.trim_leading(text) do
@@ -543,14 +704,11 @@ defmodule Phoenix.LiveView.HTMLTokenizer do
     end
   end
 
-  defp strip_text_token_partially(tokens) do
-    with [{:text, text, meta} | rest] <- tokens do
-      case String.trim_leading(text) do
-        "" -> strip_text_token_partially(rest)
-        text -> [{:text, text, meta} | rest]
-      end
-    else
-      _ -> tokens
-    end
+  defp raise_syntax_error!(message, meta, state) do
+    raise ParseError,
+      file: state.file,
+      line: meta.line,
+      column: meta.column,
+      description: message <> ParseError.code_snippet(state.source, meta, state.indentation)
   end
 end
diff --git a/lib/phoenix_live_view/upload.ex b/lib/phoenix_live_view/upload.ex
index fd472b80d8..06707a63e5 100644
--- a/lib/phoenix_live_view/upload.ex
+++ b/lib/phoenix_live_view/upload.ex
@@ -9,7 +9,8 @@ defmodule Phoenix.LiveView.Upload do
   @doc """
   Allows an upload.
   """
-  def allow_upload(%Socket{} = socket, name, opts) when is_atom(name) and is_list(opts) do
+  def allow_upload(%Socket{} = socket, name, opts)
+      when (is_atom(name) or is_binary(name)) and is_list(opts) do
     case uploaded_entries(socket, name) do
       {[], []} ->
         :ok
@@ -37,7 +38,7 @@ defmodule Phoenix.LiveView.Upload do
   @doc """
   Disallows a previously allowed upload.
   """
-  def disallow_upload(%Socket{} = socket, name) when is_atom(name) do
+  def disallow_upload(%Socket{} = socket, name) when is_atom(name) or is_binary(name) do
     case uploaded_entries(socket, name) do
       {[], []} ->
         uploads = socket.assigns[:uploads] || %{}
@@ -70,11 +71,16 @@ defmodule Phoenix.LiveView.Upload do
   """
   def cancel_upload(socket, name, entry_ref) do
     upload_config = Map.fetch!(socket.assigns[:uploads] || %{}, name)
-    %UploadEntry{} = entry = UploadConfig.get_entry_by_ref(upload_config, entry_ref)
 
-    upload_config
-    |> UploadConfig.cancel_entry(entry)
-    |> update_uploads(socket)
+    case UploadConfig.get_entry_by_ref(upload_config, entry_ref) do
+      %UploadEntry{} = entry ->
+        upload_config
+        |> UploadConfig.cancel_entry(entry)
+        |> update_uploads(socket)
+
+      _ ->
+        raise ArgumentError, "no entry in upload \"#{inspect(name)}\" with ref \"#{entry_ref}\""
+    end
   end
 
   @doc """
@@ -279,16 +285,43 @@ defmodule Phoenix.LiveView.Upload do
         |> Enum.map(fn entry ->
           meta = Map.fetch!(conf.entry_refs_to_metas, entry.ref)
 
-          cond do
-            is_function(func, 1) -> func.(meta)
-            is_function(func, 2) -> func.(meta, entry)
+          result =
+            cond do
+              is_function(func, 1) -> func.(meta)
+              is_function(func, 2) -> func.(meta, entry)
+            end
+
+          case result do
+            {:ok, return} ->
+              {entry.ref, return}
+
+            {:postpone, return} ->
+              {:postpone, return}
+
+            return ->
+              IO.warn("""
+              consuming uploads requires a return signature matching:
+
+                  {:ok, value} | {:postpone, value}
+
+              got:
+
+                  #{inspect(return)}
+              """)
+
+              {entry.ref, return}
           end
         end)
 
-      entry_refs = for entry <- entries, do: entry.ref
-      Phoenix.LiveView.Channel.drop_upload_entries(conf, entry_refs)
+      consumed_refs =
+        Enum.flat_map(results, fn
+          {:postpone, _result} -> []
+          {ref, _result} -> [ref]
+        end)
+
+      Phoenix.LiveView.Channel.drop_upload_entries(conf, consumed_refs)
 
-      results
+      Enum.map(results, fn {_ref, result} -> result end)
     else
       entries
       |> Enum.map(fn entry -> {entry, UploadConfig.entry_pid(conf, entry)} end)
diff --git a/lib/phoenix_live_view/upload_channel.ex b/lib/phoenix_live_view/upload_channel.ex
index f02571adf4..dace0c458c 100644
--- a/lib/phoenix_live_view/upload_channel.ex
+++ b/lib/phoenix_live_view/upload_channel.ex
@@ -15,12 +15,37 @@ defmodule Phoenix.LiveView.UploadChannel do
     case GenServer.call(pid, :consume_start, @timeout) do
       {:ok, file_meta} ->
         try do
-          cond do
-            is_function(func, 1) -> func.(file_meta)
-            is_function(func, 2) -> func.(file_meta, entry)
+          result =
+            cond do
+              is_function(func, 1) -> func.(file_meta)
+              is_function(func, 2) -> func.(file_meta, entry)
+            end
+
+          case result do
+            {:ok, return} ->
+              GenServer.call(pid, :consume_done, @timeout)
+              return
+
+            {:postpone, return} ->
+              return
+
+            return ->
+              IO.warn """
+              consuming uploads requires a return signature matching:
+
+                  {:ok, value} | {:postpone, value}
+
+              got:
+
+                  #{inspect(return)}
+              """
+              GenServer.call(pid, :consume_done, @timeout)
+              return
           end
-        after
-          GenServer.call(pid, :consume_done, @timeout)
+        rescue
+          exception ->
+            GenServer.call(pid, :consume_done, @timeout)
+            reraise(exception, __STACKTRACE__)
         end
 
       {:error, :in_progress} ->
diff --git a/lib/phoenix_live_view/upload_config.ex b/lib/phoenix_live_view/upload_config.ex
index f7aaa5267f..d219a5063f 100644
--- a/lib/phoenix_live_view/upload_config.ex
+++ b/lib/phoenix_live_view/upload_config.ex
@@ -15,6 +15,7 @@ defmodule Phoenix.LiveView.UploadEntry do
             done?: false,
             cancelled?: false,
             client_name: nil,
+            client_relative_path: nil,
             client_size: nil,
             client_type: nil,
             client_last_modified: nil
@@ -29,6 +30,7 @@ defmodule Phoenix.LiveView.UploadEntry do
           done?: boolean(),
           cancelled?: boolean(),
           client_name: String.t() | nil,
+          client_relative_path: String.t() | nil,
           client_size: integer() | nil,
           client_type: String.t() | nil,
           client_last_modified: integer() | nil
@@ -62,20 +64,18 @@ defmodule Phoenix.LiveView.UploadConfig do
 
   @too_many_files :too_many_files
 
-  if Version.match?(System.version(), ">= 1.8.0") do
-    @derive {Inspect,
-             only: [
-               :name,
-               :ref,
-               :entries,
-               :max_entries,
-               :max_file_size,
-               :accept,
-               :errors,
-               :auto_upload?,
-               :progress_event
-             ]}
-  end
+  @derive {Inspect,
+           only: [
+             :name,
+             :ref,
+             :entries,
+             :max_entries,
+             :max_file_size,
+             :accept,
+             :errors,
+             :auto_upload?,
+             :progress_event
+           ]}
 
   defstruct name: nil,
             cid: :unregistered,
@@ -128,7 +128,7 @@ defmodule Phoenix.LiveView.UploadConfig do
   # we require a random_ref in order to ensure unique calls to `allow_upload`
   # invalidate old uploads on the client and expire old tokens for the same
   # upload name
-  def build(name, random_ref, [_ | _] = opts) when is_atom(name) do
+  def build(name, random_ref, [_ | _] = opts) when is_atom(name) or is_binary(name) do
     {html_accept, acceptable_types, acceptable_exts} =
       case Keyword.fetch(opts, :accept) do
         {:ok, [_ | _] = accept} ->
@@ -243,9 +243,7 @@ defmodule Phoenix.LiveView.UploadConfig do
           raise ArgumentError, """
           invalid :chunk_timeout value provided to allow_upload.
 
-          Only a positive integer in milliseconds is supported (Defaults to #{
-            @default_chunk_timeout
-          } ms). Got:
+          Only a positive integer in milliseconds is supported (Defaults to #{@default_chunk_timeout} ms). Got:
 
           #{inspect(other)}
           """
@@ -521,6 +519,7 @@ defmodule Phoenix.LiveView.UploadConfig do
       upload_ref: conf.ref,
       upload_config: conf.name,
       client_name: Map.fetch!(client_entry, "name"),
+      client_relative_path: Map.get(client_entry, "relative_path"),
       client_size: Map.fetch!(client_entry, "size"),
       client_type: Map.fetch!(client_entry, "type"),
       client_last_modified: Map.get(client_entry, "last_modified")
@@ -634,7 +633,6 @@ defmodule Phoenix.LiveView.UploadConfig do
     case entry_pid(conf, entry) do
       channel_pid when is_pid(channel_pid) ->
         Phoenix.LiveView.UploadChannel.cancel(channel_pid)
-
         update_entry(conf, entry.ref, fn entry -> %UploadEntry{entry | cancelled?: true} end)
 
       _ ->
diff --git a/lib/phoenix_live_view/utils.ex b/lib/phoenix_live_view/utils.ex
index 3563f166b9..bfbdc529ed 100644
--- a/lib/phoenix_live_view/utils.ex
+++ b/lib/phoenix_live_view/utils.ex
@@ -10,6 +10,26 @@ defmodule Phoenix.LiveView.Utils do
 
   @max_flash_age :timer.seconds(60)
 
+  @valid_uri_schemes [
+    "http:",
+    "https:",
+    "ftp:",
+    "ftps:",
+    "mailto:",
+    "news:",
+    "irc:",
+    "gopher:",
+    "nntp:",
+    "feed:",
+    "telnet:",
+    "mms:",
+    "rtsp:",
+    "svn:",
+    "tel:",
+    "fax:",
+    "xmpp:"
+  ]
+
   @doc """
   Assigns a value if it changed.
   """
@@ -64,6 +84,7 @@ defmodule Phoenix.LiveView.Utils do
   @doc """
   Checks if the given assign changed.
   """
+  def changed?(%Socket{} = socket, assign), do: changed?(socket.assigns, assign)
   def changed?(%{__changed__: nil}, _assign), do: true
   def changed?(%{__changed__: changed}, assign), do: Map.has_key?(changed, assign)
 
@@ -125,6 +146,32 @@ defmodule Phoenix.LiveView.Utils do
     |> drop_private([:connect_info, :connect_params, :assign_new])
   end
 
+  @doc """
+  Validate and normalizes the layout.
+  """
+  def normalize_layout(false, _warn_ctx), do: false
+
+  def normalize_layout({mod, layout}, _warn_ctx) when is_atom(mod) and is_atom(layout) do
+    {mod, Atom.to_string(layout)}
+  end
+
+  def normalize_layout({mod, layout}, warn_ctx) when is_atom(mod) and is_binary(layout) do
+    root_template = Path.rootname(layout)
+
+    IO.warn(
+      "passing a string as a layout template in #{warn_ctx} is deprecated, please pass " <>
+        "{#{inspect(mod)}, :#{root_template}} instead of {#{inspect(mod)}, \"#{root_template}.html\"}"
+    )
+
+    {mod, root_template}
+  end
+
+  def normalize_layout(other, _warn_ctx) do
+    raise ArgumentError,
+          ":layout expects a tuple of the form {MyLayoutView, :my_template} or false, " <>
+            "got: #{inspect(other)}"
+  end
+
   @doc """
   Renders the view with socket into a rendered struct.
   """
@@ -141,8 +188,8 @@ defmodule Phoenix.LiveView.Utils do
         assigns = put_in(assigns[:inner_content], inner_content)
         assigns = put_in(assigns.__changed__[:inner_content], true)
 
-        layout_template
-        |> layout_mod.render(assigns)
+        layout_mod
+        |> Phoenix.Template.render(to_string(layout_template), "html", assigns)
         |> check_rendered!(layout_mod)
 
       false ->
@@ -280,20 +327,20 @@ defmodule Phoenix.LiveView.Utils do
     attempted to live patch while mounting.
 
     a LiveView cannot be mounted while issuing a live patch to the client. \
-    Use push_redirect/2 or redirect/2 instead if you wish to mount and redirect.
+    Use push_navigate/2 or redirect/2 instead if you wish to mount and redirect.
     """
   end
 
   @doc """
   Calls the `c:Phoenix.LiveView.mount/3` callback, otherwise returns the socket as is.
   """
-  def maybe_call_live_view_mount!(%Socket{} = socket, view, params, session) do
+  def maybe_call_live_view_mount!(%Socket{} = socket, view, params, session, uri \\ nil) do
     %{any?: any?, exported?: exported?} = Lifecycle.stage_info(socket, view, :mount, 3)
 
     if any? do
       :telemetry.span(
         [:phoenix, :live_view, :mount],
-        %{socket: socket, params: params, session: session},
+        %{socket: socket, params: params, session: session, uri: uri},
         fn ->
           socket =
             case Lifecycle.mount(params, session, socket) do
@@ -305,7 +352,7 @@ defmodule Phoenix.LiveView.Utils do
             end
             |> handle_mount_result!({:mount, 3, view})
 
-          {socket, %{socket: socket, params: params, session: session}}
+          {socket, %{socket: socket, params: params, session: session, uri: uri}}
         end
       )
     else
@@ -347,7 +394,7 @@ defmodule Phoenix.LiveView.Utils do
     """
   end
 
-  defp validate_mount_redirect!({:live, {_, _}, _}), do: raise_bad_mount_and_live_patch!()
+  defp validate_mount_redirect!({:live, :patch, _}), do: raise_bad_mount_and_live_patch!()
   defp validate_mount_redirect!(_), do: :ok
 
   @doc """
@@ -404,7 +451,8 @@ defmodule Phoenix.LiveView.Utils do
         end
 
       if socket.redirected do
-        raise "cannot redirect socket on update/2"
+        raise "cannot redirect socket on update. Redirect before `update/2` is called" <>
+                " or use `send/2` and redirect in the `handle_info/2` response"
       end
 
       socket
@@ -455,18 +503,8 @@ defmodule Phoenix.LiveView.Utils do
     """
   end
 
-  defp do_mount_opt(socket, :layout, {mod, template}) when is_atom(mod) and is_binary(template) do
-    %Socket{socket | private: Map.put(socket.private, :phoenix_live_layout, {mod, template})}
-  end
-
-  defp do_mount_opt(socket, :layout, false) do
-    %Socket{socket | private: Map.put(socket.private, :phoenix_live_layout, false)}
-  end
-
-  defp do_mount_opt(_socket, :layout, bad_layout) do
-    raise ArgumentError,
-          "the :layout mount option expects a tuple of the form {MyLayoutView, \"my_template.html\"}, " <>
-            "got: #{inspect(bad_layout)}"
+  defp do_mount_opt(socket, :layout, layout) do
+    put_in(socket.private[:live_layout], normalize_layout(layout, "mount options"))
   end
 
   defp do_mount_opt(socket, :temporary_assigns, temp_assigns) do
@@ -494,12 +532,43 @@ defmodule Phoenix.LiveView.Utils do
 
   defp layout(socket, view) do
     case socket.private do
-      %{phoenix_live_layout: layout} -> layout
-      %{} -> view.__live__()[:layout] || false
+      %{live_layout: layout} -> layout
+      %{} -> view.__live__()[:layout]
     end
   end
 
   defp flash_salt(endpoint_mod) when is_atom(endpoint_mod) do
     "flash:" <> salt!(endpoint_mod)
   end
+
+  def valid_destination!(%URI{} = uri, context) do
+    valid_destination!(URI.to_string(uri), context)
+  end
+
+  def valid_destination!({:safe, to}, context) do
+    {:safe, valid_string_destination!(IO.iodata_to_binary(to), context)}
+  end
+
+  def valid_destination!({other, to}, _context) when is_atom(other) do
+    [Atom.to_string(other), ?:, to]
+  end
+
+  def valid_destination!(to, context) do
+    valid_string_destination!(IO.iodata_to_binary(to), context)
+  end
+
+  for scheme <- @valid_uri_schemes do
+    def valid_string_destination!(unquote(scheme) <> _ = string, _context), do: string
+  end
+
+  def valid_string_destination!(to, context) do
+    if not match?("/" <> _, to) and String.contains?(to, ":") do
+      raise ArgumentError, """
+      unsupported scheme given to #{context}. In case you want to link to an
+      unknown or unsafe scheme, such as javascript, use a tuple: {:javascript, rest}
+      """
+    else
+      to
+    end
+  end
 end
diff --git a/mix.exs b/mix.exs
index b551980e63..d69cdb26eb 100644
--- a/mix.exs
+++ b/mix.exs
@@ -1,16 +1,16 @@
 defmodule Phoenix.LiveView.MixProject do
   use Mix.Project
 
-  @version "0.17.0-dev"
+  @version "0.18.16"
 
   def project do
     [
       app: :phoenix_live_view,
       version: @version,
-      elixir: "~> 1.7",
+      elixir: "~> 1.12",
       start_permanent: Mix.env() == :prod,
       elixirc_paths: elixirc_paths(Mix.env()),
-      compilers: compilers(Mix.env()),
+      test_options: [docs: true],
       package: package(),
       xref: [exclude: [Floki]],
       deps: deps(),
@@ -24,46 +24,90 @@ defmodule Phoenix.LiveView.MixProject do
     ]
   end
 
-  defp compilers(:test), do: [:phoenix] ++ Mix.compilers()
-  defp compilers(_), do: Mix.compilers()
-
   defp elixirc_paths(:test), do: ["lib", "test/support"]
   defp elixirc_paths(_), do: ["lib"]
 
   def application do
     [
-      extra_applications: [:logger],
-      mod: {Phoenix.LiveView.Application, []}
+      mod: {Phoenix.LiveView.Application, []},
+      extra_applications: [:logger]
     ]
   end
 
   defp deps do
     [
-      {:phoenix, "~> 1.5.9 or ~> 1.6.0"},
-      {:phoenix_html, "~> 3.0"},
+      {:phoenix, "~> 1.6.15 or ~> 1.7.0"},
+      {:phoenix_view, "~> 2.0", optional: true},
+      {:phoenix_template, "~> 1.0"},
+      {:phoenix_html, "~> 3.3"},
       {:esbuild, "~> 0.2", only: :dev},
       {:telemetry, "~> 0.4.2 or ~> 1.0"},
       {:jason, "~> 1.0", optional: true},
-      {:ex_doc, "~> 0.22", only: :docs},
       {:floki, "~> 0.30.0", only: :test},
+      {:ex_doc, "~> 0.29", only: :docs},
+      {:makeup_eex, ">= 0.1.1", only: :docs},
       {:html_entities, ">= 0.0.0", only: :test},
+      {:phoenix_live_reload, "~> 1.4.1", only: :test}
     ]
   end
 
   defp docs do
     [
-      main: "Phoenix.LiveView",
+      main: "Phoenix.Component",
       source_ref: "v#{@version}",
       source_url: "https://github.com/phoenixframework/phoenix_live_view",
       extra_section: "GUIDES",
       extras: extras(),
       groups_for_extras: groups_for_extras(),
-      groups_for_modules: groups_for_modules()
+      groups_for_modules: groups_for_modules(),
+      groups_for_functions: [
+        Components: &(&1[:type] == :component),
+        Macros: &(&1[:type] == :macro)
+      ],
+      skip_undefined_reference_warnings_on: ["CHANGELOG.md"],
+      before_closing_body_tag: &before_closing_body_tag/1
     ]
   end
 
+  defp before_closing_body_tag(:html) do
+    """
+    
+    
+    """
+  end
+
+  defp before_closing_body_tag(_), do: ""
+
   defp extras do
     [
+      "CHANGELOG.md",
       "guides/introduction/installation.md",
       "guides/client/bindings.md",
       "guides/client/form-bindings.md",
@@ -92,18 +136,19 @@ defmodule Phoenix.LiveView.MixProject do
   defp groups_for_modules do
     # Ungrouped Modules:
     #
+    # Phoenix.Component
+    # Phoenix.LiveComponent
     # Phoenix.LiveView
     # Phoenix.LiveView.Controller
-    # Phoenix.LiveView.Helpers
+    # Phoenix.LiveView.JS
     # Phoenix.LiveView.Router
-    # Phoenix.LiveView.Socket
     # Phoenix.LiveViewTest
 
     [
-      "Components": [
-        Phoenix.Component,
-        Phoenix.LiveComponent,
-        Phoenix.LiveComponent.CID
+      Configuration: [
+        Phoenix.LiveView.HTMLFormatter,
+        Phoenix.LiveView.Logger,
+        Phoenix.LiveView.Socket
       ],
       "Testing structures": [
         Phoenix.LiveViewTest.Element,
@@ -115,7 +160,9 @@ defmodule Phoenix.LiveView.MixProject do
         Phoenix.LiveView.UploadEntry
       ],
       "Plugin API": [
+        Phoenix.LiveComponent.CID,
         Phoenix.LiveView.Engine,
+        Phoenix.LiveView.TagEngine,
         Phoenix.LiveView.HTMLEngine,
         Phoenix.LiveView.Component,
         Phoenix.LiveView.Rendered,
@@ -128,10 +175,13 @@ defmodule Phoenix.LiveView.MixProject do
     [
       maintainers: ["Chris McCord", "José Valim", "Gary Rennie", "Alex Garibay", "Scott Newcomer"],
       licenses: ["MIT"],
-      links: %{github: "https://github.com/phoenixframework/phoenix_live_view"},
+      links: %{
+        Changelog: "https://hexdocs.pm/phoenix_live_view/changelog.html",
+        GitHub: "https://github.com/phoenixframework/phoenix_live_view"
+      },
       files:
         ~w(assets/js lib priv) ++
-          ~w(CHANGELOG.md LICENSE.md mix.exs package.json README.md)
+          ~w(CHANGELOG.md LICENSE.md mix.exs package.json README.md .formatter.exs)
     ]
   end
 
diff --git a/mix.lock b/mix.lock
index 53482c7910..d83d82d77a 100644
--- a/mix.lock
+++ b/mix.lock
@@ -1,20 +1,26 @@
 %{
-  "castore": {:hex, :castore, "0.1.11", "c0665858e0e1c3e8c27178e73dffea699a5b28eb72239a3b2642d208e8594914", [:mix], [], "hexpm", "91b009ba61973b532b84f7c09ce441cba7aa15cb8b006cf06c6f4bba18220081"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.13", "0c98163e7d04a15feb62000e1a891489feb29f3d10cb57d4f845c405852bbef8", [:mix], [], "hexpm", "d602c26af3a0af43d2f2645613f65841657ad6efc9f0e361c3b6c06b578214ba"},
-  "esbuild": {:hex, :esbuild, "0.2.0", "51e6ec981584324179dbd707a37277a334cffceddca1be57fbe7dc0161921657", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}], "hexpm", "2aa1bf4f08b60a2b5a874f11b3d778d0d8e734714060fd71ef52e21ef2aebe16"},
-  "ex_doc": {:hex, :ex_doc, "0.25.1", "4b736fa38dc76488a937e5ef2944f5474f3eff921de771b25371345a8dc810bc", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "3200b0a69ddb2028365281fbef3753ea9e728683863d8cdaa96580925c891f67"},
-  "floki": {:hex, :floki, "0.30.0", "22ebbe681a5d3777cdd830ca091b1b806d33c3449c26312eadca7f7be685c0c8", [:mix], [{:html_entities, "~> 0.5.0", [hex: :html_entities, repo: "hexpm", optional: false]}], "hexpm", "a9e128a4ca9bb71f11affa315b6768a9ad326d5996ff1e92acf1d7a01a10076a"},
+  "castore": {:hex, :castore, "0.1.18", "deb5b9ab02400561b6f5708f3e7660fc35ca2d51bfc6a940d2f513f89c2975fc", [:mix], [], "hexpm", "61bbaf6452b782ef80b33cdb45701afbcf0a918a45ebe7e73f1130d661e66a06"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.30", "0b938aa5b9bafd455056440cdaa2a79197ca5e693830b4a982beada840513c5f", [:mix], [], "hexpm", "3b5385c2d36b0473d0b206927b841343d25adb14f95f0110062506b300cd5a1b"},
+  "esbuild": {:hex, :esbuild, "0.5.0", "d5bb08ff049d7880ee3609ed5c4b864bd2f46445ea40b16b4acead724fb4c4a3", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}], "hexpm", "f183a0b332d963c4cfaf585477695ea59eef9a6f2204fdd0efa00e099694ffe5"},
+  "ex_doc": {:hex, :ex_doc, "0.29.1", "b1c652fa5f92ee9cf15c75271168027f92039b3877094290a75abcaac82a9f77", [:mix], [{:earmark_parser, "~> 1.4.19", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "b7745fa6374a36daf484e2a2012274950e084815b936b1319aeebcf7809574f6"},
+  "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
+  "floki": {:hex, :floki, "0.30.1", "75d35526d3a1459920b6e87fdbc2e0b8a3670f965dd0903708d2b267e0904c55", [:mix], [{:html_entities, "~> 0.5.0", [hex: :html_entities, repo: "hexpm", optional: false]}], "hexpm", "e9c03524447d1c4cbfccd672d739b8c18453eee377846b119d4fd71b1a176bb8"},
   "html_entities": {:hex, :html_entities, "0.5.2", "9e47e70598da7de2a9ff6af8758399251db6dbb7eebe2b013f2bbd2515895c3c", [:mix], [], "hexpm", "c53ba390403485615623b9531e97696f076ed415e8d8058b1dbaa28181f4fdcc"},
-  "jason": {:hex, :jason, "1.2.2", "ba43e3f2709fd1aa1dce90aaabfd039d000469c05c56f0b8e31978e03fa39052", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "18a228f5f0058ee183f29f9eae0805c6e59d61c3b006760668d8d18ff0d12179"},
-  "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.15.1", "b5888c880d17d1cc3e598f05cdb5b5a91b7b17ac4eaf5f297cb697663a1094dd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "db68c173234b07ab2a07f645a5acdc117b9f99d69ebf521821d89690ae6c6ec8"},
+  "jason": {:hex, :jason, "1.4.0", "e855647bc964a44e2f67df589ccf49105ae039d4179db7f6271dfd3843dc27e6", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "79a3791085b2a0f743ca04cec0f7be26443738779d09302e01318f97bdb82121"},
+  "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
+  "makeup_eex": {:hex, :makeup_eex, "0.1.1", "89352d5da318d97ae27bbcc87201f274504d2b71ede58ca366af6a5fbed9508d", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.16", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_html, "~> 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d111a0994eaaab09ef1a4b3b313ef806513bb4652152c26c0d7ca2be8402a964"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.0", "f8c570a0d33f8039513fbccaf7108c5d750f47d8defd44088371191b76492b0b", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "28b2cbdc13960a46ae9a8858c4bebdec3c9a6d7b4b9e7f4ed1502f8159f338e7"},
   "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
-  "mime": {:hex, :mime, "1.6.0", "dabde576a497cef4bbdd60aceee8160e02a6c89250d6c0b29e56c0dfb00db3d2", [:mix], [], "hexpm", "31a1a8613f8321143dde1dafc36006a17d28d02bdfecb9e95a880fa7aabd19a7"},
-  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
-  "phoenix": {:hex, :phoenix, "1.5.9", "a6368d36cfd59d917b37c44386e01315bc89f7609a10a45a22f47c007edf2597", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_html, "~> 2.13 or ~> 3.0", [hex: :phoenix_html, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 2.0", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:plug, "~> 1.10", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 1.0 or ~> 2.2", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:plug_crypto, "~> 1.1.2 or ~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "7e4bce20a67c012f1fbb0af90e5da49fa7bf0d34e3a067795703b74aef75427d"},
-  "phoenix_html": {:hex, :phoenix_html, "3.0.0", "b50048ea6be552af0f19218f703b1cc6c182f569fb28f8a849056e452a2bfed5", [:mix], [{:plug, "~> 1.5", [hex: :plug, repo: "hexpm", optional: true]}], "hexpm", "373d054f29812c5ba98096762cacfc320c5e484bfb40501511e39f662c2cd1c7"},
-  "phoenix_pubsub": {:hex, :phoenix_pubsub, "2.0.0", "a1ae76717bb168cdeb10ec9d92d1480fec99e3080f011402c0a2d68d47395ffb", [:mix], [], "hexpm", "c52d948c4f261577b9c6fa804be91884b381a7f8f18450c5045975435350f771"},
-  "plug": {:hex, :plug, "1.12.1", "645678c800601d8d9f27ad1aebba1fdb9ce5b2623ddb961a074da0b96c35187d", [:mix], [{:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.1.1 or ~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.3 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "d57e799a777bc20494b784966dc5fbda91eb4a09f571f76545b72a634ce0d30b"},
-  "plug_crypto": {:hex, :plug_crypto, "1.2.2", "05654514ac717ff3a1843204b424477d9e60c143406aa94daf2274fdd280794d", [:mix], [], "hexpm", "87631c7ad914a5a445f0a3809f99b079113ae4ed4b867348dd9eec288cecb6db"},
-  "telemetry": {:hex, :telemetry, "0.4.3", "a06428a514bdbc63293cd9a6263aad00ddeb66f608163bdec7c8995784080818", [:rebar3], [], "hexpm", "eb72b8365ffda5bed68a620d1da88525e326cb82a75ee61354fc24b844768041"},
+  "makeup_html": {:hex, :makeup_html, "0.1.0", "b0228fda985e311d8f0d25bed58f8280826633a38d7448cabdd723e116165bcf", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "0ca44e7dcb8d933e010740324470dd8ec947243b51304bd34b8165ef3281edc2"},
+  "mime": {:hex, :mime, "2.0.3", "3676436d3d1f7b81b5a2d2bd8405f412c677558c81b1c92be58c00562bb59095", [:mix], [], "hexpm", "27a30bf0db44d25eecba73755acf4068cbfe26a4372f9eb3e4ea3a45956bff6b"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.2.3", "244836e6e3f1200c7f30cb56733fd808744eca61fd182f731eac4af635cc6d0b", [:mix], [], "hexpm", "c8d789e39b9131acf7b99291e93dae60ab48ef14a7ee9d58c6964f59efb570b0"},
+  "phoenix": {:hex, :phoenix, "1.6.15", "0a1d96bbc10747fd83525370d691953cdb6f3ccbac61aa01b4acb012474b047d", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 2.0", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:phoenix_view, "~> 1.0 or ~> 2.0", [hex: :phoenix_view, repo: "hexpm", optional: false]}, {:plug, "~> 1.10", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.2", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:plug_crypto, "~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "d70ab9fbf6b394755ea88b644d34d79d8b146e490973151f248cacd122d20672"},
+  "phoenix_html": {:hex, :phoenix_html, "3.3.0", "bf451c71ebdaac8d2f40d3b703435e819ccfbb9ff243140ca3bd10c155f134cc", [:mix], [{:plug, "~> 1.5", [hex: :plug, repo: "hexpm", optional: true]}], "hexpm", "272c5c1533499f0132309936c619186480bafcc2246588f99a69ce85095556ef"},
+  "phoenix_live_reload": {:hex, :phoenix_live_reload, "1.4.1", "2aff698f5e47369decde4357ba91fc9c37c6487a512b41732818f2204a8ef1d3", [:mix], [{:file_system, "~> 0.2.1 or ~> 0.3", [hex: :file_system, repo: "hexpm", optional: false]}, {:phoenix, "~> 1.4", [hex: :phoenix, repo: "hexpm", optional: false]}], "hexpm", "9bffb834e7ddf08467fe54ae58b5785507aaba6255568ae22b4d46e2bb3615ab"},
+  "phoenix_pubsub": {:hex, :phoenix_pubsub, "2.1.1", "ba04e489ef03763bf28a17eb2eaddc2c20c6d217e2150a61e3298b0f4c2012b5", [:mix], [], "hexpm", "81367c6d1eea5878ad726be80808eb5a787a23dee699f96e72b1109c57cdd8d9"},
+  "phoenix_template": {:hex, :phoenix_template, "1.0.1", "85f79e3ad1b0180abb43f9725973e3b8c2c3354a87245f91431eec60553ed3ef", [:mix], [{:phoenix_html, "~> 2.14.2 or ~> 3.0", [hex: :phoenix_html, repo: "hexpm", optional: true]}], "hexpm", "157dc078f6226334c91cb32c1865bf3911686f8bcd6bcff86736f6253e6993ee"},
+  "phoenix_view": {:hex, :phoenix_view, "2.0.1", "a653e3d9d944aace0a064e4a13ad473ffa68f7bc4ca42dbf83cc1d464f1fb295", [:mix], [{:phoenix_html, "~> 2.14.2 or ~> 3.0", [hex: :phoenix_html, repo: "hexpm", optional: true]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", optional: false]}], "hexpm", "6c358e2cefc5f341c728914b867c556bbfd239fed9e881bac257d70cb2b8a6f6"},
+  "plug": {:hex, :plug, "1.14.0", "ba4f558468f69cbd9f6b356d25443d0b796fbdc887e03fa89001384a9cac638f", [:mix], [{:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.1.1 or ~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.3 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "bf020432c7d4feb7b3af16a0c2701455cbbbb95e5b6866132cb09eb0c29adc14"},
+  "plug_crypto": {:hex, :plug_crypto, "1.2.3", "8f77d13aeb32bfd9e654cb68f0af517b371fb34c56c9f2b58fe3df1235c1251a", [:mix], [], "hexpm", "b5672099c6ad5c202c45f5a403f21a3411247f164e4a8fab056e5cd8a290f4a2"},
+  "telemetry": {:hex, :telemetry, "1.2.1", "68fdfe8d8f05a8428483a97d7aab2f268aaff24b49e0f599faa091f1d4e7f61c", [:rebar3], [], "hexpm", "dad9ce9d8effc621708f99eac538ef1cbe05d6a874dd741de2e689c47feafed5"},
 }
diff --git a/package.json b/package.json
index 21d905deb4..b6d89d7b53 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "phoenix_live_view",
-  "version": "0.16.3",
+  "version": "0.18.16",
   "description": "The Phoenix LiveView JavaScript client.",
   "license": "MIT",
   "module": "./priv/static/phoenix_live_view.esm.js",
diff --git a/priv/static/phoenix_live_view.cjs.js b/priv/static/phoenix_live_view.cjs.js
index 621f8e4bb7..f77356c869 100644
--- a/priv/static/phoenix_live_view.cjs.js
+++ b/priv/static/phoenix_live_view.cjs.js
@@ -14,7 +14,8 @@ __export(exports, {
 // js/phoenix_live_view/constants.js
 var CONSECUTIVE_RELOADS = "consecutive-reloads";
 var MAX_RELOADS = 10;
-var RELOAD_JITTER = [1e3, 3e3];
+var RELOAD_JITTER_MIN = 5e3;
+var RELOAD_JITTER_MAX = 1e4;
 var FAILSAFE_JITTER = 3e4;
 var PHX_EVENT_CLASSES = [
   "phx-click-loading",
@@ -30,6 +31,7 @@ var PHX_LIVE_LINK = "data-phx-link";
 var PHX_TRACK_STATIC = "track-static";
 var PHX_LINK_STATE = "data-phx-link-state";
 var PHX_REF = "data-phx-ref";
+var PHX_REF_SRC = "data-phx-ref-src";
 var PHX_TRACK_UPLOADS = "track-uploads";
 var PHX_UPLOAD_REF = "data-phx-upload-ref";
 var PHX_PREFLIGHTED_REFS = "data-phx-preflighted-refs";
@@ -38,10 +40,10 @@ var PHX_DROP_TARGET = "drop-target";
 var PHX_ACTIVE_ENTRY_REFS = "data-phx-active-refs";
 var PHX_LIVE_FILE_UPDATED = "phx:live-file:updated";
 var PHX_SKIP = "data-phx-skip";
-var PHX_REMOVE = "data-phx-remove";
+var PHX_PRUNE = "data-phx-prune";
 var PHX_PAGE_LOADING = "page-loading";
 var PHX_CONNECTED_CLASS = "phx-connected";
-var PHX_DISCONNECTED_CLASS = "phx-disconnected";
+var PHX_DISCONNECTED_CLASS = "phx-loading";
 var PHX_NO_FEEDBACK_CLASS = "phx-no-feedback";
 var PHX_ERROR_CLASS = "phx-error";
 var PHX_PARENT_ID = "data-phx-parent-id";
@@ -50,11 +52,12 @@ var PHX_ROOT_ID = "data-phx-root-id";
 var PHX_TRIGGER_ACTION = "trigger-action";
 var PHX_FEEDBACK_FOR = "feedback-for";
 var PHX_HAS_FOCUSED = "phx-has-focused";
-var FOCUSABLE_INPUTS = ["text", "textarea", "number", "email", "password", "search", "tel", "url", "date", "time"];
+var FOCUSABLE_INPUTS = ["text", "textarea", "number", "email", "password", "search", "tel", "url", "date", "time", "datetime-local", "color", "range"];
 var CHECKABLE_INPUTS = ["checkbox", "radio"];
 var PHX_HAS_SUBMITTED = "phx-has-submitted";
 var PHX_SESSION = "data-phx-session";
 var PHX_VIEW_SELECTOR = `[${PHX_SESSION}]`;
+var PHX_STICKY = "data-phx-sticky";
 var PHX_STATIC = "data-phx-static";
 var PHX_READONLY = "data-phx-readonly";
 var PHX_DISABLED = "data-phx-disabled";
@@ -64,6 +67,7 @@ var PHX_HOOK = "hook";
 var PHX_DEBOUNCE = "debounce";
 var PHX_THROTTLE = "throttle";
 var PHX_UPDATE = "update";
+var PHX_STREAM = "stream";
 var PHX_KEY = "key";
 var PHX_PRIVATE = "phxPrivate";
 var PHX_AUTO_RECOVER = "auto-recover";
@@ -71,6 +75,7 @@ var PHX_LV_DEBUG = "phx:live-socket:debug";
 var PHX_LV_PROFILE = "phx:live-socket:profiling";
 var PHX_LV_LATENCY_SIM = "phx:live-socket:latency-sim";
 var PHX_PROGRESS = "progress";
+var PHX_MOUNTED = "mounted";
 var LOADER_TIMEOUT = 1;
 var BEFORE_UNLOAD_LOADER_TIMEOUT = 200;
 var BINDING_PREFIX = "phx-";
@@ -88,6 +93,8 @@ var COMPONENTS = "c";
 var EVENTS = "e";
 var REPLY = "r";
 var TITLE = "t";
+var TEMPLATES = "p";
+var STREAM = "stream";
 
 // js/phoenix_live_view/entry_uploader.js
 var EntryUploader = class {
@@ -139,7 +146,10 @@ var EntryUploader = class {
 
 // js/phoenix_live_view/utils.js
 var logError = (msg, obj) => console.error && console.error(msg, obj);
-var isCid = (cid) => typeof cid === "number";
+var isCid = (cid) => {
+  let type = typeof cid;
+  return type === "number" || type === "string" && /^(0|[1-9]\d*)$/.test(cid);
+};
 function detectDuplicateIds() {
   let ids = new Set();
   let elems = document.querySelectorAll("*[id]");
@@ -164,7 +174,7 @@ var clone = (obj) => {
 };
 var closestPhxBinding = (el, binding, borderEl) => {
   do {
-    if (el.matches(`[${binding}]`)) {
+    if (el.matches(`[${binding}]`) && !el.disabled) {
       return el;
     }
     el = el.parentElement || el.parentNode;
@@ -294,8 +304,35 @@ var DOM = {
   isPhxDestroyed(node) {
     return node.id && DOM.private(node, "destroyed") ? true : false;
   },
+  wantsNewTab(e) {
+    let wantsNewTab = e.ctrlKey || e.shiftKey || e.metaKey || e.button && e.button === 1;
+    return wantsNewTab || e.target.getAttribute("target") === "_blank";
+  },
+  isUnloadableFormSubmit(e) {
+    return !e.defaultPrevented && !this.wantsNewTab(e);
+  },
+  isNewPageHref(href, currentLocation) {
+    let url;
+    try {
+      url = new URL(href);
+    } catch (e) {
+      try {
+        url = new URL(href, currentLocation);
+      } catch (e2) {
+        return true;
+      }
+    }
+    if (url.host === currentLocation.host && url.protocol === currentLocation.protocol) {
+      if (url.pathname === currentLocation.pathname && url.search === currentLocation.search) {
+        return url.hash === "" && !url.href.endsWith("#");
+      }
+    }
+    return true;
+  },
   markPhxChildDestroyed(el) {
-    el.setAttribute(PHX_SESSION, "");
+    if (this.isPhxChild(el)) {
+      el.setAttribute(PHX_SESSION, "");
+    }
     this.putPrivate(el, "destroyed", true);
   },
   findPhxChildrenInFragment(html, parentId) {
@@ -309,16 +346,20 @@ var DOM = {
   isPhxUpdate(el, phxUpdate, updateTypes) {
     return el.getAttribute && updateTypes.indexOf(el.getAttribute(phxUpdate)) >= 0;
   },
+  findPhxSticky(el) {
+    return this.all(el, `[${PHX_STICKY}]`);
+  },
   findPhxChildren(el, parentId) {
     return this.all(el, `${PHX_VIEW_SELECTOR}[${PHX_PARENT_ID}="${parentId}"]`);
   },
   findParentCIDs(node, cids) {
     let initial = new Set(cids);
-    return cids.reduce((acc, cid) => {
+    let parentCids = cids.reduce((acc, cid) => {
       let selector = `[${PHX_COMPONENT}="${cid}"] [${PHX_COMPONENT}]`;
       this.filterWithinSameLiveView(this.all(node, selector), node).map((el) => parseInt(el.getAttribute(PHX_COMPONENT))).forEach((childCID) => acc.delete(childCID));
       return acc;
     }, initial);
+    return parentCids.size === 0 ? new Set(cids) : parentCids;
   },
   filterWithinSameLiveView(nodes, parent) {
     if (parent.querySelector(PHX_VIEW_SELECTOR)) {
@@ -349,17 +390,29 @@ var DOM = {
     }
     el[PHX_PRIVATE][key] = value;
   },
+  updatePrivate(el, key, defaultVal, updateFunc) {
+    let existing = this.private(el, key);
+    if (existing === void 0) {
+      this.putPrivate(el, key, updateFunc(defaultVal));
+    } else {
+      this.putPrivate(el, key, updateFunc(existing));
+    }
+  },
   copyPrivates(target, source) {
     if (source[PHX_PRIVATE]) {
-      target[PHX_PRIVATE] = clone(source[PHX_PRIVATE]);
+      target[PHX_PRIVATE] = source[PHX_PRIVATE];
     }
   },
   putTitle(str) {
     let titleEl = document.querySelector("title");
-    let { prefix, suffix } = titleEl.dataset;
-    document.title = `${prefix || ""}${str}${suffix || ""}`;
+    if (titleEl) {
+      let { prefix, suffix } = titleEl.dataset;
+      document.title = `${prefix || ""}${str}${suffix || ""}`;
+    } else {
+      document.title = str;
+    }
   },
-  debounce(el, event, phxDebounce, defaultDebounce, phxThrottle, defaultThrottle, callback) {
+  debounce(el, event, phxDebounce, defaultDebounce, phxThrottle, defaultThrottle, asyncFilter, callback) {
     let debounce = el.getAttribute(phxDebounce);
     let throttle = el.getAttribute(phxThrottle);
     if (debounce === "") {
@@ -396,10 +449,18 @@ var DOM = {
           } else {
             callback();
             this.putPrivate(el, THROTTLED, true);
-            setTimeout(() => this.triggerCycle(el, DEBOUNCE_TRIGGER), timeout);
+            setTimeout(() => {
+              if (asyncFilter()) {
+                this.triggerCycle(el, DEBOUNCE_TRIGGER);
+              }
+            }, timeout);
           }
         } else {
-          setTimeout(() => this.triggerCycle(el, DEBOUNCE_TRIGGER, currentCycle), timeout);
+          setTimeout(() => {
+            if (asyncFilter()) {
+              this.triggerCycle(el, DEBOUNCE_TRIGGER, currentCycle);
+            }
+          }, timeout);
         }
         let form = el.form;
         if (form && this.once(form, "bind-debounce")) {
@@ -442,14 +503,26 @@ var DOM = {
   },
   discardError(container, el, phxFeedbackFor) {
     let field = el.getAttribute && el.getAttribute(phxFeedbackFor);
-    let input = field && container.querySelector(`[id="${field}"], [name="${field}"]`);
+    let input = field && container.querySelector(`[id="${field}"], [name="${field}"], [name="${field}[]"]`);
     if (!input) {
       return;
     }
-    if (!(this.private(input, PHX_HAS_FOCUSED) || this.private(input.form, PHX_HAS_SUBMITTED))) {
+    if (!(this.private(input, PHX_HAS_FOCUSED) || this.private(input, PHX_HAS_SUBMITTED))) {
       el.classList.add(PHX_NO_FEEDBACK_CLASS);
     }
   },
+  resetForm(form, phxFeedbackFor) {
+    Array.from(form.elements).forEach((input) => {
+      let query = `[${phxFeedbackFor}="${input.id}"],
+                   [${phxFeedbackFor}="${input.name}"],
+                   [${phxFeedbackFor}="${input.name.replace(/\[\]$/, "")}"]`;
+      this.deletePrivate(input, PHX_HAS_FOCUSED);
+      this.deletePrivate(input, PHX_HAS_SUBMITTED);
+      this.all(document, query, (feedbackEl) => {
+        feedbackEl.classList.add(PHX_NO_FEEDBACK_CLASS);
+      });
+    });
+  },
   showError(inputEl, phxFeedbackFor) {
     if (inputEl.id || inputEl.name) {
       this.all(inputEl.form, `[${phxFeedbackFor}="${inputEl.id}"], [${phxFeedbackFor}="${inputEl.name}"]`, (el) => {
@@ -460,8 +533,16 @@ var DOM = {
   isPhxChild(node) {
     return node.getAttribute && node.getAttribute(PHX_PARENT_ID);
   },
-  dispatchEvent(target, eventString, detail = {}) {
-    let event = new CustomEvent(eventString, { bubbles: true, cancelable: true, detail });
+  isPhxSticky(node) {
+    return node.getAttribute && node.getAttribute(PHX_STICKY) !== null;
+  },
+  firstPhxChild(el) {
+    return this.isPhxChild(el) ? el : this.all(el, `[${PHX_PARENT_ID}]`)[0];
+  },
+  dispatchEvent(target, name, opts = {}) {
+    let bubbles = opts.bubbles === void 0 ? true : !!opts.bubbles;
+    let eventOpts = { bubbles, cancelable: true, detail: opts.detail || {} };
+    let event = name === "click" ? new MouseEvent("click", eventOpts) : new CustomEvent(name, eventOpts);
     target.dispatchEvent(event);
   },
   cloneNode(node, html) {
@@ -499,7 +580,7 @@ var DOM = {
   },
   mergeFocusedInput(target, source) {
     if (!(target instanceof HTMLSelectElement)) {
-      DOM.mergeAttrs(target, source, { except: ["value"] });
+      DOM.mergeAttrs(target, source, { exclude: ["value"] });
     }
     if (source.readOnly) {
       target.setAttribute("readonly", true);
@@ -533,14 +614,6 @@ var DOM = {
       el.checked = el.getAttribute("checked") !== null;
     }
   },
-  syncPropsToAttrs(el) {
-    if (el instanceof HTMLSelectElement) {
-      let selectedItem = el.options.item(el.selectedIndex);
-      if (selectedItem && selectedItem.getAttribute("selected") === null) {
-        selectedItem.setAttribute("selected", "");
-      }
-    }
-  },
   isTextualInput(el) {
     return FOCUSABLE_INPUTS.indexOf(el.type) >= 0;
   },
@@ -552,6 +625,7 @@ var DOM = {
     if (ref === null) {
       return true;
     }
+    let refSrc = fromEl.getAttribute(PHX_REF_SRC);
     if (DOM.isFormInput(fromEl) || fromEl.getAttribute(disableWith) !== null) {
       if (DOM.isUploadInput(fromEl)) {
         DOM.mergeAttrs(fromEl, toEl, { isIgnored: true });
@@ -563,6 +637,7 @@ var DOM = {
         fromEl.classList.contains(className) && toEl.classList.add(className);
       });
       toEl.setAttribute(PHX_REF, ref);
+      toEl.setAttribute(PHX_REF_SRC, refSrc);
       return true;
     }
   },
@@ -586,7 +661,7 @@ removing illegal node: "${(childNode.outerHTML || childNode.nodeValue).trim()}"
     }
   },
   replaceRootContainer(container, tagName, attrs) {
-    let retainedAttrs = new Set(["id", PHX_SESSION, PHX_STATIC, PHX_MAIN]);
+    let retainedAttrs = new Set(["id", PHX_SESSION, PHX_STATIC, PHX_MAIN, PHX_ROOT_ID]);
     if (container.tagName.toLowerCase() === tagName.toLowerCase()) {
       Array.from(container.attributes).filter((attr) => !retainedAttrs.has(attr.name.toLowerCase())).forEach((attr) => container.removeAttribute(attr.name));
       Object.keys(attrs).filter((name) => !retainedAttrs.has(name.toLowerCase())).forEach((attr) => container.setAttribute(attr, attrs[attr]));
@@ -599,6 +674,39 @@ removing illegal node: "${(childNode.outerHTML || childNode.nodeValue).trim()}"
       container.replaceWith(newContainer);
       return newContainer;
     }
+  },
+  getSticky(el, name, defaultVal) {
+    let op = (DOM.private(el, "sticky") || []).find(([existingName]) => name === existingName);
+    if (op) {
+      let [_name, _op, stashedResult] = op;
+      return stashedResult;
+    } else {
+      return typeof defaultVal === "function" ? defaultVal() : defaultVal;
+    }
+  },
+  deleteSticky(el, name) {
+    this.updatePrivate(el, "sticky", [], (ops) => {
+      return ops.filter(([existingName, _]) => existingName !== name);
+    });
+  },
+  putSticky(el, name, op) {
+    let stashedResult = op(el);
+    this.updatePrivate(el, "sticky", [], (ops) => {
+      let existingIndex = ops.findIndex(([existingName]) => name === existingName);
+      if (existingIndex >= 0) {
+        ops[existingIndex] = [name, op, stashedResult];
+      } else {
+        ops.push([name, op, stashedResult]);
+      }
+      return ops;
+    });
+  },
+  applyStickyOperations(el) {
+    let ops = DOM.private(el, "sticky");
+    if (!ops) {
+      return;
+    }
+    ops.forEach(([name, op, _stashed]) => this.putSticky(el, name, op));
   }
 };
 var dom_default = DOM;
@@ -660,6 +768,7 @@ var UploadEntry = class {
     return this._isDone;
   }
   error(reason = "failed") {
+    this.fileEl.removeEventListener(PHX_LIVE_FILE_UPDATED, this._onElUpdated);
     this.view.pushFileProgress(this.fileEl, this.ref, { error: reason });
     LiveUploader.clearFiles(this.fileEl);
   }
@@ -679,6 +788,7 @@ var UploadEntry = class {
     return {
       last_modified: this.file.lastModified,
       name: this.file.name,
+      relative_path: this.file.webkitRelativePath,
       size: this.file.size,
       type: this.file.type,
       ref: this.ref
@@ -733,7 +843,9 @@ var LiveUploader = class {
       let uploadRef = inputEl.getAttribute(PHX_UPLOAD_REF);
       fileData[uploadRef] = fileData[uploadRef] || [];
       entry.ref = this.genFileRef(file);
+      entry.last_modified = file.lastModified;
       entry.name = file.name || entry.ref;
+      entry.relative_path = file.webkitRelativePath;
       entry.type = file.type;
       entry.size = file.size;
       fileData[uploadRef].push(entry);
@@ -748,12 +860,15 @@ var LiveUploader = class {
   static untrackFile(inputEl, file) {
     dom_default.putPrivate(inputEl, "files", dom_default.private(inputEl, "files").filter((f) => !Object.is(f, file)));
   }
-  static trackFiles(inputEl, files) {
+  static trackFiles(inputEl, files, dataTransfer) {
     if (inputEl.getAttribute("multiple") !== null) {
       let newFiles = files.filter((file) => !this.activeFiles(inputEl).find((f) => Object.is(f, file)));
       dom_default.putPrivate(inputEl, "files", this.activeFiles(inputEl).concat(newFiles));
       inputEl.value = null;
     } else {
+      if (dataTransfer && dataTransfer.files.length > 0) {
+        inputEl.files = dataTransfer.files;
+      }
       dom_default.putPrivate(inputEl, "files", files);
     }
   }
@@ -804,6 +919,62 @@ var LiveUploader = class {
   }
 };
 
+// js/phoenix_live_view/aria.js
+var ARIA = {
+  focusMain() {
+    let target = document.querySelector("main h1, main, h1");
+    if (target) {
+      let origTabIndex = target.tabIndex;
+      target.tabIndex = -1;
+      target.focus();
+      target.tabIndex = origTabIndex;
+    }
+  },
+  anyOf(instance, classes) {
+    return classes.find((name) => instance instanceof name);
+  },
+  isFocusable(el, interactiveOnly) {
+    return el instanceof HTMLAnchorElement && el.rel !== "ignore" || el instanceof HTMLAreaElement && el.href !== void 0 || !el.disabled && this.anyOf(el, [HTMLInputElement, HTMLSelectElement, HTMLTextAreaElement, HTMLButtonElement]) || el instanceof HTMLIFrameElement || (el.tabIndex > 0 || !interactiveOnly && el.tabIndex === 0 && el.getAttribute("tabindex") !== null && el.getAttribute("aria-hidden") !== "true");
+  },
+  attemptFocus(el, interactiveOnly) {
+    if (this.isFocusable(el, interactiveOnly)) {
+      try {
+        el.focus();
+      } catch (e) {
+      }
+    }
+    return !!document.activeElement && document.activeElement.isSameNode(el);
+  },
+  focusFirstInteractive(el) {
+    let child = el.firstElementChild;
+    while (child) {
+      if (this.attemptFocus(child, true) || this.focusFirstInteractive(child, true)) {
+        return true;
+      }
+      child = child.nextElementSibling;
+    }
+  },
+  focusFirst(el) {
+    let child = el.firstElementChild;
+    while (child) {
+      if (this.attemptFocus(child) || this.focusFirst(child)) {
+        return true;
+      }
+      child = child.nextElementSibling;
+    }
+  },
+  focusLast(el) {
+    let child = el.lastElementChild;
+    while (child) {
+      if (this.attemptFocus(child) || this.focusLast(child)) {
+        return true;
+      }
+      child = child.previousElementSibling;
+    }
+  }
+};
+var aria_default = ARIA;
+
 // js/phoenix_live_view/hooks.js
 var Hooks = {
   LiveFileUpload: {
@@ -842,6 +1013,18 @@ var Hooks = {
     destroyed() {
       URL.revokeObjectURL(this.url);
     }
+  },
+  FocusWrap: {
+    mounted() {
+      this.focusStart = this.el.firstElementChild;
+      this.focusEnd = this.el.lastElementChild;
+      this.focusStart.addEventListener("focus", () => aria_default.focusLast(this.el));
+      this.focusEnd.addEventListener("focus", () => aria_default.focusFirst(this.el));
+      this.el.addEventListener("phx:show-end", () => this.el.focus());
+      if (window.getComputedStyle(this.el).display !== "none") {
+        aria_default.focusFirst(this.el);
+      }
+    }
   }
 };
 var hooks_default = Hooks;
@@ -1114,6 +1297,8 @@ function morphdomFactory(morphAttrs2) {
       } else {
         toNode = toElement(toNode);
       }
+    } else if (toNode.nodeType === DOCUMENT_FRAGMENT_NODE$1) {
+      toNode = toNode.firstElementChild;
     }
     var getNodeKey = options.getNodeKey || defaultGetNodeKey;
     var onBeforeNodeAdded = options.onBeforeNodeAdded || noop;
@@ -1123,6 +1308,10 @@ function morphdomFactory(morphAttrs2) {
     var onBeforeNodeDiscarded = options.onBeforeNodeDiscarded || noop;
     var onNodeDiscarded = options.onNodeDiscarded || noop;
     var onBeforeElChildrenUpdated = options.onBeforeElChildrenUpdated || noop;
+    var skipFromChildren = options.skipFromChildren || noop;
+    var addChild = options.addChild || function(parent, child) {
+      return parent.appendChild(child);
+    };
     var childrenOnly = options.childrenOnly === true;
     var fromNodesLookup = Object.create(null);
     var keyedRemovalList = [];
@@ -1223,6 +1412,7 @@ function morphdomFactory(morphAttrs2) {
       }
     }
     function morphChildren(fromEl, toEl) {
+      var skipFrom = skipFromChildren(fromEl);
       var curToNodeChild = toEl.firstChild;
       var curFromNodeChild = fromEl.firstChild;
       var curToNodeKey;
@@ -1234,7 +1424,7 @@ function morphdomFactory(morphAttrs2) {
         while (curToNodeChild) {
           toNextSibling = curToNodeChild.nextSibling;
           curToNodeKey = getNodeKey(curToNodeChild);
-          while (curFromNodeChild) {
+          while (!skipFrom && curFromNodeChild) {
             fromNextSibling = curFromNodeChild.nextSibling;
             if (curToNodeChild.isSameNode && curToNodeChild.isSameNode(curFromNodeChild)) {
               curToNodeChild = toNextSibling;
@@ -1291,7 +1481,9 @@ function morphdomFactory(morphAttrs2) {
             curFromNodeChild = fromNextSibling;
           }
           if (curToNodeKey && (matchingFromEl = fromNodesLookup[curToNodeKey]) && compareNodeNames(matchingFromEl, curToNodeChild)) {
-            fromEl.appendChild(matchingFromEl);
+            if (!skipFrom) {
+              addChild(fromEl, matchingFromEl);
+            }
             morphEl(matchingFromEl, curToNodeChild);
           } else {
             var onBeforeNodeAddedResult = onBeforeNodeAdded(curToNodeChild);
@@ -1302,7 +1494,7 @@ function morphdomFactory(morphAttrs2) {
               if (curToNodeChild.actualize) {
                 curToNodeChild = curToNodeChild.actualize(fromEl.ownerDocument || doc);
               }
-              fromEl.appendChild(curToNodeChild);
+              addChild(fromEl, curToNodeChild);
               handleNodeAdded(curToNodeChild);
             }
           }
@@ -1380,15 +1572,19 @@ var DOMPatch = class {
       }
     });
   }
-  constructor(view, container, id, html, targetCID) {
+  constructor(view, container, id, html, streams, targetCID) {
     this.view = view;
     this.liveSocket = view.liveSocket;
     this.container = container;
     this.id = id;
     this.rootID = view.root.id;
     this.html = html;
+    this.streams = streams;
+    this.streamInserts = {};
     this.targetCID = targetCID;
     this.cidPatch = isCid(this.targetCID);
+    this.pendingRemoves = [];
+    this.phxRemove = this.liveSocket.binding("remove");
     this.callbacks = {
       beforeadded: [],
       beforeupdated: [],
@@ -1396,7 +1592,8 @@ var DOMPatch = class {
       afteradded: [],
       afterupdated: [],
       afterdiscarded: [],
-      afterphxChildAdded: []
+      afterphxChildAdded: [],
+      aftertransitionsDiscarded: []
     };
   }
   before(kind, callback) {
@@ -1412,8 +1609,10 @@ var DOMPatch = class {
     this.callbacks[`after${kind}`].forEach((callback) => callback(...args));
   }
   markPrunableContentForRemoval() {
-    dom_default.all(this.container, "[phx-update=append] > *, [phx-update=prepend] > *", (el) => {
-      el.setAttribute(PHX_REMOVE, "");
+    let phxUpdate = this.liveSocket.binding(PHX_UPDATE);
+    dom_default.all(this.container, `[${phxUpdate}=${PHX_STREAM}]`, (el) => el.innerHTML = "");
+    dom_default.all(this.container, `[${phxUpdate}=append] > *, [${phxUpdate}=prepend] > *`, (el) => {
+      el.setAttribute(PHX_PRUNE, "");
     });
   }
   perform() {
@@ -1438,11 +1637,41 @@ var DOMPatch = class {
     this.trackBefore("added", container);
     this.trackBefore("updated", container, container);
     liveSocket.time("morphdom", () => {
+      this.streams.forEach(([inserts, deleteIds]) => {
+        this.streamInserts = Object.assign(this.streamInserts, inserts);
+        deleteIds.forEach((id) => {
+          let child = container.querySelector(`[id="${id}"]`);
+          if (child) {
+            if (!this.maybePendingRemove(child)) {
+              child.remove();
+              this.onNodeDiscarded(child);
+            }
+          }
+        });
+      });
       morphdom_esm_default(targetContainer, diffHTML, {
         childrenOnly: targetContainer.getAttribute(PHX_COMPONENT) === null,
         getNodeKey: (node) => {
           return dom_default.isPhxDestroyed(node) ? null : node.id;
         },
+        skipFromChildren: (from) => {
+          return from.getAttribute(phxUpdate) === PHX_STREAM;
+        },
+        addChild: (parent, child) => {
+          let streamAt = child.id ? this.streamInserts[child.id] : void 0;
+          if (streamAt === void 0) {
+            return parent.appendChild(child);
+          }
+          dom_default.putPrivate(child, PHX_STREAM, true);
+          if (streamAt === 0) {
+            parent.insertAdjacentElement("afterbegin", child);
+          } else if (streamAt === -1) {
+            parent.appendChild(child);
+          } else if (streamAt > 0) {
+            let sibling = Array.from(parent.children)[streamAt];
+            parent.insertBefore(child, sibling);
+          }
+        },
         onBeforeNodeAdded: (el) => {
           this.trackBefore("added", el);
           return el;
@@ -1457,22 +1686,23 @@ var DOMPatch = class {
             externalFormTriggered = el;
           }
           dom_default.discardError(targetContainer, el, phxFeedbackFor);
-          if (dom_default.isPhxChild(el) && view.ownsElement(el)) {
+          if (dom_default.isPhxChild(el) && view.ownsElement(el) || dom_default.isPhxSticky(el) && view.ownsElement(el.parentNode)) {
             this.trackAfter("phxChildAdded", el);
           }
           added.push(el);
         },
-        onNodeDiscarded: (el) => {
-          if (dom_default.isPhxChild(el)) {
-            liveSocket.destroyViewByEl(el);
-          }
-          this.trackAfter("discarded", el);
-        },
+        onNodeDiscarded: (el) => this.onNodeDiscarded(el),
         onBeforeNodeDiscarded: (el) => {
-          if (el.getAttribute && el.getAttribute(PHX_REMOVE) !== null) {
+          if (el.getAttribute && el.getAttribute(PHX_PRUNE) !== null) {
             return true;
           }
-          if (el.parentNode !== null && dom_default.isPhxUpdate(el.parentNode, phxUpdate, ["append", "prepend"]) && el.id) {
+          if (dom_default.private(el, PHX_STREAM)) {
+            return false;
+          }
+          if (el.parentElement !== null && dom_default.isPhxUpdate(el.parentElement, phxUpdate, ["append", "prepend"]) && el.id) {
+            return false;
+          }
+          if (this.maybePendingRemove(el)) {
             return false;
           }
           if (this.skipCIDSibling(el)) {
@@ -1485,16 +1715,21 @@ var DOMPatch = class {
             externalFormTriggered = el;
           }
           updates.push(el);
+          this.maybeReOrderStream(el);
         },
         onBeforeElUpdated: (fromEl, toEl) => {
           dom_default.cleanChildNodes(toEl, phxUpdate);
           if (this.skipCIDSibling(toEl)) {
             return false;
           }
-          if (dom_default.isIgnored(fromEl, phxUpdate)) {
+          if (dom_default.isPhxSticky(fromEl)) {
+            return false;
+          }
+          if (dom_default.isIgnored(fromEl, phxUpdate) || fromEl.form && fromEl.form.isSameNode(externalFormTriggered)) {
             this.trackBefore("updated", fromEl, toEl);
             dom_default.mergeAttrs(fromEl, toEl, { isIgnored: true });
             updates.push(fromEl);
+            dom_default.applyStickyOperations(fromEl);
             return false;
           }
           if (fromEl.type === "number" && (fromEl.validity && fromEl.validity.badInput)) {
@@ -1505,6 +1740,7 @@ var DOMPatch = class {
               this.trackBefore("updated", fromEl, toEl);
               updates.push(fromEl);
             }
+            dom_default.applyStickyOperations(fromEl);
             return false;
           }
           if (dom_default.isPhxChild(toEl)) {
@@ -1514,23 +1750,25 @@ var DOMPatch = class {
               fromEl.setAttribute(PHX_SESSION, prevSession);
             }
             fromEl.setAttribute(PHX_ROOT_ID, this.rootID);
+            dom_default.applyStickyOperations(fromEl);
             return false;
           }
           dom_default.copyPrivates(toEl, fromEl);
           dom_default.discardError(targetContainer, toEl, phxFeedbackFor);
-          dom_default.syncPropsToAttrs(toEl);
           let isFocusedFormEl = focused && fromEl.isSameNode(focused) && dom_default.isFormInput(fromEl);
-          if (isFocusedFormEl && !this.forceFocusedSelectUpdate(fromEl, toEl)) {
+          if (isFocusedFormEl && fromEl.type !== "hidden") {
             this.trackBefore("updated", fromEl, toEl);
             dom_default.mergeFocusedInput(fromEl, toEl);
             dom_default.syncAttrsToProps(fromEl);
             updates.push(fromEl);
+            dom_default.applyStickyOperations(fromEl);
             return false;
           } else {
             if (dom_default.isPhxUpdate(toEl, phxUpdate, ["append", "prepend"])) {
               appendPrependUpdates.push(new DOMPostMorphRestorer(fromEl, toEl, toEl.getAttribute(phxUpdate)));
             }
             dom_default.syncAttrsToProps(toEl);
+            dom_default.applyStickyOperations(toEl);
             this.trackBefore("updated", fromEl, toEl);
             return true;
           }
@@ -1549,15 +1787,65 @@ var DOMPatch = class {
     dom_default.dispatchEvent(document, "phx:update");
     added.forEach((el) => this.trackAfter("added", el));
     updates.forEach((el) => this.trackAfter("updated", el));
+    this.transitionPendingRemoves();
     if (externalFormTriggered) {
-      liveSocket.disconnect();
+      liveSocket.unload();
       externalFormTriggered.submit();
     }
     return true;
   }
-  forceFocusedSelectUpdate(fromEl, toEl) {
-    let isSelect = ["select", "select-one", "select-multiple"].find((t) => t === fromEl.type);
-    return fromEl.multiple === true || isSelect && fromEl.innerHTML != toEl.innerHTML;
+  onNodeDiscarded(el) {
+    if (dom_default.isPhxChild(el) || dom_default.isPhxSticky(el)) {
+      this.liveSocket.destroyViewByEl(el);
+    }
+    this.trackAfter("discarded", el);
+  }
+  maybePendingRemove(node) {
+    if (node.getAttribute && node.getAttribute(this.phxRemove) !== null) {
+      this.pendingRemoves.push(node);
+      return true;
+    } else {
+      return false;
+    }
+  }
+  maybeReOrderStream(el) {
+    let streamAt = el.id ? this.streamInserts[el.id] : void 0;
+    if (streamAt === void 0) {
+      return;
+    }
+    dom_default.putPrivate(el, PHX_STREAM, true);
+    if (streamAt === 0) {
+      el.parentElement.insertBefore(el, el.parentElement.firstElementChild);
+    } else if (streamAt > 0) {
+      let children = Array.from(el.parentElement.children);
+      let oldIndex = children.indexOf(el);
+      if (streamAt >= children.length - 1) {
+        el.parentElement.appendChild(el);
+      } else {
+        let sibling = children[streamAt];
+        if (oldIndex > streamAt) {
+          el.parentElement.insertBefore(el, sibling);
+        } else {
+          el.parentElement.insertBefore(el, sibling.nextElementSibling);
+        }
+      }
+    }
+  }
+  transitionPendingRemoves() {
+    let { pendingRemoves, liveSocket } = this;
+    if (pendingRemoves.length > 0) {
+      liveSocket.transitionRemoves(pendingRemoves);
+      liveSocket.requestDOMUpdate(() => {
+        pendingRemoves.forEach((el) => {
+          let child = dom_default.firstPhxChild(el);
+          if (child) {
+            liveSocket.destroyViewByEl(child);
+          }
+          el.remove();
+        });
+        this.trackAfter("transitionsDiscarded", pendingRemoves);
+      });
+    }
   }
   isCIDPatch() {
     return this.cidPatch;
@@ -1599,6 +1887,9 @@ var DOMPatch = class {
       return diffContainer.outerHTML;
     }
   }
+  indexOf(parent, child) {
+    return Array.from(parent.children).indexOf(child);
+  }
 };
 
 // js/phoenix_live_view/rendered.js
@@ -1619,13 +1910,14 @@ var Rendered = class {
     return this.viewId;
   }
   toString(onlyCids) {
-    return this.recursiveToString(this.rendered, this.rendered[COMPONENTS], onlyCids);
+    let [str, streams] = this.recursiveToString(this.rendered, this.rendered[COMPONENTS], onlyCids);
+    return [str, streams];
   }
   recursiveToString(rendered, components = rendered[COMPONENTS], onlyCids) {
     onlyCids = onlyCids ? new Set(onlyCids) : null;
-    let output = { buffer: "", components, onlyCids };
-    this.toOutputBuffer(rendered, output);
-    return output.buffer;
+    let output = { buffer: "", components, onlyCids, streams: new Set() };
+    this.toOutputBuffer(rendered, null, output);
+    return [output.buffer, output.streams];
   }
   componentCIDs(diff) {
     return Object.keys(diff[COMPONENTS] || {}).map((i) => parseInt(i));
@@ -1650,8 +1942,8 @@ var Rendered = class {
       for (let cid in newc) {
         newc[cid] = this.cachedFindComponent(cid, newc[cid], oldc, newc, cache);
       }
-      for (var key in newc) {
-        oldc[key] = newc[key];
+      for (let cid in newc) {
+        oldc[cid] = newc[cid];
       }
       diff[COMPONENTS] = newc;
     }
@@ -1690,7 +1982,8 @@ var Rendered = class {
     for (let key in source) {
       let val = source[key];
       let targetVal = target[key];
-      if (isObject(val) && val[STATIC] === void 0 && isObject(targetVal)) {
+      let isObjVal = isObject(val);
+      if (isObjVal && val[STATIC] === void 0 && isObject(targetVal)) {
         this.doMutableMerge(targetVal, val);
       } else {
         target[key] = val;
@@ -1709,7 +2002,8 @@ var Rendered = class {
     return merged;
   }
   componentToString(cid) {
-    return this.recursiveCIDToString(this.rendered[COMPONENTS], cid);
+    let [str, streams] = this.recursiveCIDToString(this.rendered[COMPONENTS], cid);
+    return [str, streams];
   }
   pruneCIDs(cids) {
     cids.forEach((cid) => delete this.rendered[COMPONENTS][cid]);
@@ -1720,33 +2014,50 @@ var Rendered = class {
   isNewFingerprint(diff = {}) {
     return !!diff[STATIC];
   }
-  toOutputBuffer(rendered, output) {
+  templateStatic(part, templates) {
+    if (typeof part === "number") {
+      return templates[part];
+    } else {
+      return part;
+    }
+  }
+  toOutputBuffer(rendered, templates, output) {
     if (rendered[DYNAMICS]) {
-      return this.comprehensionToBuffer(rendered, output);
+      return this.comprehensionToBuffer(rendered, templates, output);
     }
     let { [STATIC]: statics } = rendered;
+    statics = this.templateStatic(statics, templates);
     output.buffer += statics[0];
     for (let i = 1; i < statics.length; i++) {
-      this.dynamicToBuffer(rendered[i - 1], output);
+      this.dynamicToBuffer(rendered[i - 1], templates, output);
       output.buffer += statics[i];
     }
   }
-  comprehensionToBuffer(rendered, output) {
-    let { [DYNAMICS]: dynamics, [STATIC]: statics } = rendered;
+  comprehensionToBuffer(rendered, templates, output) {
+    let { [DYNAMICS]: dynamics, [STATIC]: statics, [STREAM]: stream } = rendered;
+    let [_inserts, deleteIds] = stream || [{}, []];
+    statics = this.templateStatic(statics, templates);
+    let compTemplates = templates || rendered[TEMPLATES];
     for (let d = 0; d < dynamics.length; d++) {
       let dynamic = dynamics[d];
       output.buffer += statics[0];
       for (let i = 1; i < statics.length; i++) {
-        this.dynamicToBuffer(dynamic[i - 1], output);
+        this.dynamicToBuffer(dynamic[i - 1], compTemplates, output);
         output.buffer += statics[i];
       }
     }
+    if (stream !== void 0 && (rendered[DYNAMICS].length > 0 || deleteIds.length > 0)) {
+      rendered[DYNAMICS] = [];
+      output.streams.add(stream);
+    }
   }
-  dynamicToBuffer(rendered, output) {
+  dynamicToBuffer(rendered, templates, output) {
     if (typeof rendered === "number") {
-      output.buffer += this.recursiveCIDToString(output.components, rendered, output.onlyCids);
+      let [str, streams] = this.recursiveCIDToString(output.components, rendered, output.onlyCids);
+      output.buffer += str;
+      output.streams = new Set([...output.streams, ...streams]);
     } else if (isObject(rendered)) {
-      this.toOutputBuffer(rendered, output);
+      this.toOutputBuffer(rendered, templates, output);
     } else {
       output.buffer += rendered;
     }
@@ -1754,7 +2065,8 @@ var Rendered = class {
   recursiveCIDToString(components, cid, onlyCids) {
     let component = components[cid] || logError(`no component for CID ${cid}`, components);
     let template = document.createElement("template");
-    template.innerHTML = this.recursiveToString(component, components, onlyCids);
+    let [html, streams] = this.recursiveToString(component, components, onlyCids);
+    template.innerHTML = html;
     let container = template.content;
     let skip = onlyCids && !onlyCids.has(cid);
     let [hasChildNodes, hasChildComponents] = Array.from(container.childNodes).reduce(([hasNodes, hasComponents], child, i) => {
@@ -1789,12 +2101,12 @@ within:
     }, [false, false]);
     if (!hasChildNodes && !hasChildComponents) {
       logError("expected at least one HTML element tag inside a component, but the component is empty:\n", template.innerHTML.trim());
-      return this.createSpan("", cid).outerHTML;
+      return [this.createSpan("", cid).outerHTML, streams];
     } else if (!hasChildNodes && hasChildComponents) {
       logError("expected at least one HTML element tag directly inside a component, but only subcomponents were found. A component must render at least one HTML tag directly inside itself.", template.innerHTML.trim());
-      return template.innerHTML;
+      return [template.innerHTML, streams];
     } else {
-      return template.innerHTML;
+      return [template.innerHTML, streams];
     }
   }
   createSpan(text, cid) {
@@ -1816,7 +2128,7 @@ var ViewHook = class {
   }
   constructor(view, el, callbacks) {
     this.__view = view;
-    this.__liveSocket = view.liveSocket;
+    this.liveSocket = view.liveSocket;
     this.__callbacks = callbacks;
     this.__listeners = new Set();
     this.__isDisconnected = false;
@@ -1860,13 +2172,13 @@ var ViewHook = class {
   }
   handleEvent(event, callback) {
     let callbackRef = (customEvent, bypass) => bypass ? event : callback(customEvent.detail);
-    window.addEventListener(`phx:hook:${event}`, callbackRef);
+    window.addEventListener(`phx:${event}`, callbackRef);
     this.__listeners.add(callbackRef);
     return callbackRef;
   }
   removeHandleEvent(callbackRef) {
     let event = callbackRef(null, true);
-    window.removeEventListener(`phx:hook:${event}`, callbackRef);
+    window.removeEventListener(`phx:${event}`, callbackRef);
     this.__listeners.delete(callbackRef);
   }
   upload(name, files) {
@@ -1880,8 +2192,211 @@ var ViewHook = class {
   }
 };
 
+// js/phoenix_live_view/js.js
+var focusStack = null;
+var JS = {
+  exec(eventType, phxEvent, view, sourceEl, defaults) {
+    let [defaultKind, defaultArgs] = defaults || [null, {}];
+    let commands = phxEvent.charAt(0) === "[" ? JSON.parse(phxEvent) : [[defaultKind, defaultArgs]];
+    commands.forEach(([kind, args]) => {
+      if (kind === defaultKind && defaultArgs.data) {
+        args.data = Object.assign(args.data || {}, defaultArgs.data);
+      }
+      this.filterToEls(sourceEl, args).forEach((el) => {
+        this[`exec_${kind}`](eventType, phxEvent, view, sourceEl, el, args);
+      });
+    });
+  },
+  isVisible(el) {
+    return !!(el.offsetWidth || el.offsetHeight || el.getClientRects().length > 0);
+  },
+  exec_dispatch(eventType, phxEvent, view, sourceEl, el, { to, event, detail, bubbles }) {
+    detail = detail || {};
+    detail.dispatcher = sourceEl;
+    dom_default.dispatchEvent(el, event, { detail, bubbles });
+  },
+  exec_push(eventType, phxEvent, view, sourceEl, el, args) {
+    if (!view.isConnected()) {
+      return;
+    }
+    let { event, data, target, page_loading, loading, value, dispatcher } = args;
+    let pushOpts = { loading, value, target, page_loading: !!page_loading };
+    let targetSrc = eventType === "change" && dispatcher ? dispatcher : sourceEl;
+    let phxTarget = target || targetSrc.getAttribute(view.binding("target")) || targetSrc;
+    view.withinTargets(phxTarget, (targetView, targetCtx) => {
+      if (eventType === "change") {
+        let { newCid, _target, callback } = args;
+        _target = _target || (dom_default.isFormInput(sourceEl) ? sourceEl.name : void 0);
+        if (_target) {
+          pushOpts._target = _target;
+        }
+        targetView.pushInput(sourceEl, targetCtx, newCid, event || phxEvent, pushOpts, callback);
+      } else if (eventType === "submit") {
+        targetView.submitForm(sourceEl, targetCtx, event || phxEvent, pushOpts);
+      } else {
+        targetView.pushEvent(eventType, sourceEl, targetCtx, event || phxEvent, data, pushOpts);
+      }
+    });
+  },
+  exec_navigate(eventType, phxEvent, view, sourceEl, el, { href, replace }) {
+    view.liveSocket.historyRedirect(href, replace ? "replace" : "push");
+  },
+  exec_patch(eventType, phxEvent, view, sourceEl, el, { href, replace }) {
+    view.liveSocket.pushHistoryPatch(href, replace ? "replace" : "push", sourceEl);
+  },
+  exec_focus(eventType, phxEvent, view, sourceEl, el) {
+    window.requestAnimationFrame(() => aria_default.attemptFocus(el));
+  },
+  exec_focus_first(eventType, phxEvent, view, sourceEl, el) {
+    window.requestAnimationFrame(() => aria_default.focusFirstInteractive(el) || aria_default.focusFirst(el));
+  },
+  exec_push_focus(eventType, phxEvent, view, sourceEl, el) {
+    window.requestAnimationFrame(() => focusStack = el || sourceEl);
+  },
+  exec_pop_focus(eventType, phxEvent, view, sourceEl, el) {
+    window.requestAnimationFrame(() => {
+      if (focusStack) {
+        focusStack.focus();
+      }
+      focusStack = null;
+    });
+  },
+  exec_add_class(eventType, phxEvent, view, sourceEl, el, { names, transition, time }) {
+    this.addOrRemoveClasses(el, names, [], transition, time, view);
+  },
+  exec_remove_class(eventType, phxEvent, view, sourceEl, el, { names, transition, time }) {
+    this.addOrRemoveClasses(el, [], names, transition, time, view);
+  },
+  exec_transition(eventType, phxEvent, view, sourceEl, el, { time, transition }) {
+    this.addOrRemoveClasses(el, [], [], transition, time, view);
+  },
+  exec_toggle(eventType, phxEvent, view, sourceEl, el, { display, ins, outs, time }) {
+    this.toggle(eventType, view, el, display, ins, outs, time);
+  },
+  exec_show(eventType, phxEvent, view, sourceEl, el, { display, transition, time }) {
+    this.show(eventType, view, el, display, transition, time);
+  },
+  exec_hide(eventType, phxEvent, view, sourceEl, el, { display, transition, time }) {
+    this.hide(eventType, view, el, display, transition, time);
+  },
+  exec_set_attr(eventType, phxEvent, view, sourceEl, el, { attr: [attr, val] }) {
+    this.setOrRemoveAttrs(el, [[attr, val]], []);
+  },
+  exec_remove_attr(eventType, phxEvent, view, sourceEl, el, { attr }) {
+    this.setOrRemoveAttrs(el, [], [attr]);
+  },
+  show(eventType, view, el, display, transition, time) {
+    if (!this.isVisible(el)) {
+      this.toggle(eventType, view, el, display, transition, null, time);
+    }
+  },
+  hide(eventType, view, el, display, transition, time) {
+    if (this.isVisible(el)) {
+      this.toggle(eventType, view, el, display, null, transition, time);
+    }
+  },
+  toggle(eventType, view, el, display, ins, outs, time) {
+    let [inClasses, inStartClasses, inEndClasses] = ins || [[], [], []];
+    let [outClasses, outStartClasses, outEndClasses] = outs || [[], [], []];
+    if (inClasses.length > 0 || outClasses.length > 0) {
+      if (this.isVisible(el)) {
+        let onStart = () => {
+          this.addOrRemoveClasses(el, outStartClasses, inClasses.concat(inStartClasses).concat(inEndClasses));
+          window.requestAnimationFrame(() => {
+            this.addOrRemoveClasses(el, outClasses, []);
+            window.requestAnimationFrame(() => this.addOrRemoveClasses(el, outEndClasses, outStartClasses));
+          });
+        };
+        el.dispatchEvent(new Event("phx:hide-start"));
+        view.transition(time, onStart, () => {
+          this.addOrRemoveClasses(el, [], outClasses.concat(outEndClasses));
+          dom_default.putSticky(el, "toggle", (currentEl) => currentEl.style.display = "none");
+          el.dispatchEvent(new Event("phx:hide-end"));
+        });
+      } else {
+        if (eventType === "remove") {
+          return;
+        }
+        let onStart = () => {
+          this.addOrRemoveClasses(el, inStartClasses, outClasses.concat(outStartClasses).concat(outEndClasses));
+          let stickyDisplay = display || this.defaultDisplay(el);
+          dom_default.putSticky(el, "toggle", (currentEl) => currentEl.style.display = stickyDisplay);
+          window.requestAnimationFrame(() => {
+            this.addOrRemoveClasses(el, inClasses, []);
+            window.requestAnimationFrame(() => this.addOrRemoveClasses(el, inEndClasses, inStartClasses));
+          });
+        };
+        el.dispatchEvent(new Event("phx:show-start"));
+        view.transition(time, onStart, () => {
+          this.addOrRemoveClasses(el, [], inClasses.concat(inEndClasses));
+          el.dispatchEvent(new Event("phx:show-end"));
+        });
+      }
+    } else {
+      if (this.isVisible(el)) {
+        window.requestAnimationFrame(() => {
+          el.dispatchEvent(new Event("phx:hide-start"));
+          dom_default.putSticky(el, "toggle", (currentEl) => currentEl.style.display = "none");
+          el.dispatchEvent(new Event("phx:hide-end"));
+        });
+      } else {
+        window.requestAnimationFrame(() => {
+          el.dispatchEvent(new Event("phx:show-start"));
+          let stickyDisplay = display || this.defaultDisplay(el);
+          dom_default.putSticky(el, "toggle", (currentEl) => currentEl.style.display = stickyDisplay);
+          el.dispatchEvent(new Event("phx:show-end"));
+        });
+      }
+    }
+  },
+  addOrRemoveClasses(el, adds, removes, transition, time, view) {
+    let [transition_run, transition_start, transition_end] = transition || [[], [], []];
+    if (transition_run.length > 0) {
+      let onStart = () => this.addOrRemoveClasses(el, transition_start.concat(transition_run), []);
+      let onDone = () => this.addOrRemoveClasses(el, adds.concat(transition_end), removes.concat(transition_run).concat(transition_start));
+      return view.transition(time, onStart, onDone);
+    }
+    window.requestAnimationFrame(() => {
+      let [prevAdds, prevRemoves] = dom_default.getSticky(el, "classes", [[], []]);
+      let keepAdds = adds.filter((name) => prevAdds.indexOf(name) < 0 && !el.classList.contains(name));
+      let keepRemoves = removes.filter((name) => prevRemoves.indexOf(name) < 0 && el.classList.contains(name));
+      let newAdds = prevAdds.filter((name) => removes.indexOf(name) < 0).concat(keepAdds);
+      let newRemoves = prevRemoves.filter((name) => adds.indexOf(name) < 0).concat(keepRemoves);
+      dom_default.putSticky(el, "classes", (currentEl) => {
+        currentEl.classList.remove(...newRemoves);
+        currentEl.classList.add(...newAdds);
+        return [newAdds, newRemoves];
+      });
+    });
+  },
+  setOrRemoveAttrs(el, sets, removes) {
+    let [prevSets, prevRemoves] = dom_default.getSticky(el, "attrs", [[], []]);
+    let alteredAttrs = sets.map(([attr, _val]) => attr).concat(removes);
+    let newSets = prevSets.filter(([attr, _val]) => !alteredAttrs.includes(attr)).concat(sets);
+    let newRemoves = prevRemoves.filter((attr) => !alteredAttrs.includes(attr)).concat(removes);
+    dom_default.putSticky(el, "attrs", (currentEl) => {
+      newRemoves.forEach((attr) => currentEl.removeAttribute(attr));
+      newSets.forEach(([attr, val]) => currentEl.setAttribute(attr, val));
+      return [newSets, newRemoves];
+    });
+  },
+  hasAllClasses(el, classes) {
+    return classes.every((name) => el.classList.contains(name));
+  },
+  isToggledOut(el, outClasses) {
+    return !this.isVisible(el) || this.hasAllClasses(el, outClasses);
+  },
+  filterToEls(sourceEl, { to }) {
+    return to ? dom_default.all(document, to) : [sourceEl];
+  },
+  defaultDisplay(el) {
+    return { tr: "table-row", td: "table-cell" }[el.tagName.toLowerCase()] || "block";
+  }
+};
+var js_default = JS;
+
 // js/phoenix_live_view/view.js
-var serializeForm = (form, meta = {}) => {
+var serializeForm = (form, meta, onlyNames = []) => {
   let formData = new FormData(form);
   let toRemove = [];
   formData.forEach((val, key, _index) => {
@@ -1892,7 +2407,9 @@ var serializeForm = (form, meta = {}) => {
   toRemove.forEach((key) => formData.delete(key));
   let params = new URLSearchParams();
   for (let [key, val] of formData.entries()) {
-    params.append(key, val);
+    if (onlyNames.length === 0 || onlyNames.indexOf(key) >= 0) {
+      params.append(key, val);
+    }
   }
   for (let metaKey in meta) {
     params.append(metaKey, meta[metaKey]);
@@ -1900,7 +2417,8 @@ var serializeForm = (form, meta = {}) => {
   return params.toString();
 };
 var View = class {
-  constructor(el, liveSocket, parentView, flash) {
+  constructor(el, liveSocket, parentView, flash, liveReferer) {
+    this.isDead = false;
     this.liveSocket = liveSocket;
     this.flash = flash;
     this.parent = parentView;
@@ -1917,7 +2435,8 @@ var View = class {
     this.joinCount = this.parent ? this.parent.joinCount - 1 : 0;
     this.joinPending = true;
     this.destroyed = false;
-    this.joinCallback = function() {
+    this.joinCallback = function(onDone) {
+      onDone && onDone();
     };
     this.stopCallback = function() {
     };
@@ -1931,14 +2450,12 @@ var View = class {
       return {
         redirect: this.redirect ? this.href : void 0,
         url: this.redirect ? void 0 : this.href || void 0,
-        params: this.connectParams(),
+        params: this.connectParams(liveReferer),
         session: this.getSession(),
         static: this.getStatic(),
         flash: this.flash
       };
     });
-    this.showLoader(this.liveSocket.loaderTimeout);
-    this.bindChannel();
   }
   setHref(href) {
     this.href = href;
@@ -1948,15 +2465,16 @@ var View = class {
     this.href = href;
   }
   isMain() {
-    return this.liveSocket.main === this;
+    return this.el.hasAttribute(PHX_MAIN);
   }
-  connectParams() {
+  connectParams(liveReferer) {
     let params = this.liveSocket.params(this.el);
     let manifest = dom_default.all(document, `[${this.binding(PHX_TRACK_STATIC)}]`).map((node) => node.src || node.href).filter((url) => typeof url === "string");
     if (manifest.length > 0) {
       params["_track_static"] = manifest;
     }
     params["_mounts"] = this.joinCount;
+    params["_live_referer"] = liveReferer;
     return params;
   }
   isConnected() {
@@ -1992,9 +2510,6 @@ var View = class {
     this.el.classList.remove(PHX_CONNECTED_CLASS, PHX_DISCONNECTED_CLASS, PHX_ERROR_CLASS);
     this.el.classList.add(...classes);
   }
-  isLoading() {
-    return this.el.classList.contains(PHX_DISCONNECTED_CLASS);
-  }
   showLoader(timeout) {
     clearTimeout(this.loaderTimer);
     if (timeout) {
@@ -2006,9 +2521,13 @@ var View = class {
       this.setContainerClasses(PHX_DISCONNECTED_CLASS);
     }
   }
+  execAll(binding) {
+    dom_default.all(this.el, `[${binding}]`, (el) => this.liveSocket.execJS(el, el.getAttribute(binding)));
+  }
   hideLoader() {
     clearTimeout(this.loaderTimer);
     this.setContainerClasses(PHX_CONNECTED_CLASS);
+    this.execAll(this.binding("connected"));
   }
   triggerReconnected() {
     for (let id in this.viewHooks) {
@@ -2018,16 +2537,20 @@ var View = class {
   log(kind, msgCallback) {
     this.liveSocket.log(this, kind, msgCallback);
   }
+  transition(time, onStart, onDone = function() {
+  }) {
+    this.liveSocket.transition(time, onStart, onDone);
+  }
   withinTargets(phxTarget, callback) {
-    if (phxTarget instanceof HTMLElement) {
+    if (phxTarget instanceof HTMLElement || phxTarget instanceof SVGElement) {
       return this.liveSocket.owner(phxTarget, (view) => callback(view, phxTarget));
     }
-    if (/^(0|[1-9]\d*)$/.test(phxTarget)) {
+    if (isCid(phxTarget)) {
       let targets = dom_default.findComponentNodeList(this.el, phxTarget);
       if (targets.length === 0) {
         logError(`no component found matching phx-target of ${phxTarget}`);
       } else {
-        callback(this, targets[0]);
+        callback(this, parseInt(phxTarget));
       }
     } else {
       let targets = Array.from(document.querySelectorAll(phxTarget));
@@ -2040,11 +2563,10 @@ var View = class {
   applyDiff(type, rawDiff, callback) {
     this.log(type, () => ["", clone(rawDiff)]);
     let { diff, reply, events, title } = Rendered.extract(rawDiff);
+    callback({ diff, reply, events });
     if (title) {
-      dom_default.putTitle(title);
+      window.requestAnimationFrame(() => dom_default.putTitle(title));
     }
-    callback({ diff, reply, events });
-    return reply;
   }
   onJoin(resp) {
     let { rendered, container } = resp;
@@ -2058,7 +2580,7 @@ var View = class {
     browser_default.dropLocal(this.liveSocket.localStorage, window.location.pathname, CONSECUTIVE_RELOADS);
     this.applyDiff("mount", rendered, ({ diff, events }) => {
       this.rendered = new Rendered(this.id, diff);
-      let html = this.renderContainer(null, "join");
+      let [html, streams] = this.renderContainer(null, "join");
       this.dropPendingRefs();
       let forms = this.formsForRecovery(html);
       this.joinCount++;
@@ -2066,21 +2588,24 @@ var View = class {
         forms.forEach(([form, newForm, newCid], i) => {
           this.pushFormRecovery(form, newCid, (resp2) => {
             if (i === forms.length - 1) {
-              this.onJoinComplete(resp2, html, events);
+              this.onJoinComplete(resp2, html, streams, events);
             }
           });
         });
       } else {
-        this.onJoinComplete(resp, html, events);
+        this.onJoinComplete(resp, html, streams, events);
       }
     });
   }
   dropPendingRefs() {
-    dom_default.all(this.el, `[${PHX_REF}]`, (el) => el.removeAttribute(PHX_REF));
+    dom_default.all(document, `[${PHX_REF_SRC}="${this.id}"][${PHX_REF}]`, (el) => {
+      el.removeAttribute(PHX_REF);
+      el.removeAttribute(PHX_REF_SRC);
+    });
   }
-  onJoinComplete({ live_patch }, html, events) {
+  onJoinComplete({ live_patch }, html, streams, events) {
     if (this.joinCount > 1 || this.parent && !this.parent.isJoinPending()) {
-      return this.applyJoinPatch(live_patch, html, events);
+      return this.applyJoinPatch(live_patch, html, streams, events);
     }
     let newChildren = dom_default.findPhxChildrenInFragment(html, this.id).filter((toEl) => {
       let fromEl = toEl.id && this.el.querySelector(`[id="${toEl.id}"]`);
@@ -2092,39 +2617,35 @@ var View = class {
     });
     if (newChildren.length === 0) {
       if (this.parent) {
-        this.root.pendingJoinOps.push([this, () => this.applyJoinPatch(live_patch, html, events)]);
+        this.root.pendingJoinOps.push([this, () => this.applyJoinPatch(live_patch, html, streams, events)]);
         this.parent.ackJoin(this);
       } else {
         this.onAllChildJoinsComplete();
-        this.applyJoinPatch(live_patch, html, events);
+        this.applyJoinPatch(live_patch, html, streams, events);
       }
     } else {
-      this.root.pendingJoinOps.push([this, () => this.applyJoinPatch(live_patch, html, events)]);
+      this.root.pendingJoinOps.push([this, () => this.applyJoinPatch(live_patch, html, streams, events)]);
     }
   }
   attachTrueDocEl() {
     this.el = dom_default.byId(this.id);
     this.el.setAttribute(PHX_ROOT_ID, this.root.id);
   }
-  dispatchEvents(events) {
-    events.forEach(([event, payload]) => {
-      window.dispatchEvent(new CustomEvent(`phx:hook:${event}`, { detail: payload }));
+  execNewMounted() {
+    dom_default.all(this.el, `[${this.binding(PHX_HOOK)}], [data-phx-${PHX_HOOK}]`, (hookEl) => {
+      this.maybeAddNewHook(hookEl);
     });
+    dom_default.all(this.el, `[${this.binding(PHX_MOUNTED)}]`, (el) => this.maybeMounted(el));
   }
-  applyJoinPatch(live_patch, html, events) {
+  applyJoinPatch(live_patch, html, streams, events) {
     this.attachTrueDocEl();
-    let patch = new DOMPatch(this, this.el, this.id, html, null);
+    let patch = new DOMPatch(this, this.el, this.id, html, streams, null);
     patch.markPrunableContentForRemoval();
     this.performPatch(patch, false);
     this.joinNewChildren();
-    dom_default.all(this.el, `[${this.binding(PHX_HOOK)}], [data-phx-${PHX_HOOK}]`, (hookEl) => {
-      let hook = this.addHook(hookEl);
-      if (hook) {
-        hook.__mounted();
-      }
-    });
+    this.execNewMounted();
     this.joinPending = false;
-    this.dispatchEvents(events);
+    this.liveSocket.dispatchEvents(events);
     this.applyPendingUpdates();
     if (live_patch) {
       let { kind, to } = live_patch;
@@ -2145,18 +2666,38 @@ var View = class {
       return hook;
     }
   }
+  maybeMounted(el) {
+    let phxMounted = el.getAttribute(this.binding(PHX_MOUNTED));
+    let hasBeenInvoked = phxMounted && dom_default.private(el, "mounted");
+    if (phxMounted && !hasBeenInvoked) {
+      this.liveSocket.execJS(el, phxMounted);
+      dom_default.putPrivate(el, "mounted", true);
+    }
+  }
+  maybeAddNewHook(el, force) {
+    let newHook = this.addHook(el);
+    if (newHook) {
+      newHook.__mounted();
+    }
+  }
   performPatch(patch, pruneCids) {
-    let destroyedCIDs = [];
+    let removedEls = [];
     let phxChildrenAdded = false;
     let updatedHookIds = new Set();
     patch.after("added", (el) => {
       this.liveSocket.triggerDOM("onNodeAdded", [el]);
-      let newHook = this.addHook(el);
-      if (newHook) {
-        newHook.__mounted();
+      this.maybeAddNewHook(el);
+      if (el.getAttribute) {
+        this.maybeMounted(el);
+      }
+    });
+    patch.after("phxChildAdded", (el) => {
+      if (dom_default.isPhxSticky(el)) {
+        this.liveSocket.joinRootViews();
+      } else {
+        phxChildrenAdded = true;
       }
     });
-    patch.after("phxChildAdded", (_el) => phxChildrenAdded = true);
     patch.before("updated", (fromEl, toEl) => {
       let hook = this.triggerBeforeUpdateHook(fromEl, toEl);
       if (hook) {
@@ -2169,18 +2710,34 @@ var View = class {
       }
     });
     patch.after("discarded", (el) => {
-      let cid = this.componentID(el);
-      if (isCid(cid) && destroyedCIDs.indexOf(cid) === -1) {
-        destroyedCIDs.push(cid);
+      if (el.nodeType === Node.ELEMENT_NODE) {
+        removedEls.push(el);
       }
-      let hook = this.getHook(el);
-      hook && this.destroyHook(hook);
     });
+    patch.after("transitionsDiscarded", (els) => this.afterElementsRemoved(els, pruneCids));
     patch.perform();
+    this.afterElementsRemoved(removedEls, pruneCids);
+    return phxChildrenAdded;
+  }
+  afterElementsRemoved(elements, pruneCids) {
+    let destroyedCIDs = [];
+    elements.forEach((parent) => {
+      let components = dom_default.all(parent, `[${PHX_COMPONENT}]`);
+      let hooks = dom_default.all(parent, `[${this.binding(PHX_HOOK)}]`);
+      components.concat(parent).forEach((el) => {
+        let cid = this.componentID(el);
+        if (isCid(cid) && destroyedCIDs.indexOf(cid) === -1) {
+          destroyedCIDs.push(cid);
+        }
+      });
+      hooks.concat(parent).forEach((hookEl) => {
+        let hook = this.getHook(hookEl);
+        hook && this.destroyHook(hook);
+      });
+    });
     if (pruneCids) {
       this.maybePushComponentsDestroyed(destroyedCIDs);
     }
-    return phxChildrenAdded;
   }
   joinNewChildren() {
     dom_default.findPhxChildren(this.el, this.id).forEach((el) => this.joinChild(el));
@@ -2228,16 +2785,17 @@ var View = class {
     }
   }
   onAllChildJoinsComplete() {
-    this.joinCallback();
-    this.pendingJoinOps.forEach(([view, op]) => {
-      if (!view.isDestroyed()) {
-        op();
-      }
+    this.joinCallback(() => {
+      this.pendingJoinOps.forEach(([view, op]) => {
+        if (!view.isDestroyed()) {
+          op();
+        }
+      });
+      this.pendingJoinOps = [];
     });
-    this.pendingJoinOps = [];
   }
   update(diff, events) {
-    if (this.isJoinPending() || this.liveSocket.hasPendingLink()) {
+    if (this.isJoinPending() || this.liveSocket.hasPendingLink() && this.root.isMain()) {
       return this.pendingDiffs.push({ diff, events });
     }
     this.rendered.mergeDiff(diff);
@@ -2253,12 +2811,12 @@ var View = class {
       });
     } else if (!isEmpty(diff)) {
       this.liveSocket.time("full patch complete", () => {
-        let html = this.renderContainer(diff, "update");
-        let patch = new DOMPatch(this, this.el, this.id, html, null);
+        let [html, streams] = this.renderContainer(diff, "update");
+        let patch = new DOMPatch(this, this.el, this.id, html, streams, null);
         phxChildrenAdded = this.performPatch(patch, true);
       });
     }
-    this.dispatchEvents(events);
+    this.liveSocket.dispatchEvents(events);
     if (phxChildrenAdded) {
       this.joinNewChildren();
     }
@@ -2267,15 +2825,15 @@ var View = class {
     return this.liveSocket.time(`toString diff (${kind})`, () => {
       let tag = this.el.tagName;
       let cids = diff ? this.rendered.componentCIDs(diff).concat(this.pruningCIDs) : null;
-      let html = this.rendered.toString(cids);
-      return `<${tag}>${html}`;
+      let [html, streams] = this.rendered.toString(cids);
+      return [`<${tag}>${html}`, streams];
     });
   }
   componentPatch(diff, cid) {
     if (isEmpty(diff))
       return false;
-    let html = this.rendered.componentToString(cid);
-    let patch = new DOMPatch(this, this.el, this.id, html, cid);
+    let [html, streams] = this.rendered.componentToString(cid);
+    let patch = new DOMPatch(this, this.el, this.id, html, streams, cid);
     let childrenAdded = this.performPatch(patch, true);
     return childrenAdded;
   }
@@ -2310,19 +2868,28 @@ var View = class {
   applyPendingUpdates() {
     this.pendingDiffs.forEach(({ diff, events }) => this.update(diff, events));
     this.pendingDiffs = [];
+    this.eachChild((child) => child.applyPendingUpdates());
+  }
+  eachChild(callback) {
+    let children = this.root.children[this.id] || {};
+    for (let id in children) {
+      callback(this.getChildById(id));
+    }
   }
   onChannel(event, cb) {
     this.liveSocket.onChannel(this.channel, event, (resp) => {
       if (this.isJoinPending()) {
         this.root.pendingJoinOps.push([this, () => cb(resp)]);
       } else {
-        cb(resp);
+        this.liveSocket.requestDOMUpdate(() => cb(resp));
       }
     });
   }
   bindChannel() {
     this.liveSocket.onChannel(this.channel, "diff", (rawDiff) => {
-      this.applyDiff("update", rawDiff, ({ diff, events }) => this.update(diff, events));
+      this.liveSocket.requestDOMUpdate(() => {
+        this.applyDiff("update", rawDiff, ({ diff, events }) => this.update(diff, events));
+      });
     });
     this.onChannel("redirect", ({ to, flash }) => this.onRedirect({ to, flash }));
     this.onChannel("live_patch", (redir) => this.onLivePatch(redir));
@@ -2331,9 +2898,7 @@ var View = class {
     this.channel.onClose((reason) => this.onClose(reason));
   }
   destroyAllChildren() {
-    for (let id in this.root.children[this.id]) {
-      this.getChildById(id).destroy();
-    }
+    this.eachChild((child) => child.destroy());
   }
   onLiveRedirect(redir) {
     let { to, kind, flash } = redir;
@@ -2354,17 +2919,33 @@ var View = class {
   isDestroyed() {
     return this.destroyed;
   }
+  joinDead() {
+    this.isDead = true;
+  }
   join(callback) {
-    if (!this.parent) {
+    this.showLoader(this.liveSocket.loaderTimeout);
+    this.bindChannel();
+    if (this.isMain()) {
       this.stopCallback = this.liveSocket.withPageLoading({ to: this.href, kind: "initial" });
     }
-    this.joinCallback = () => callback && callback(this.joinCount);
+    this.joinCallback = (onDone) => {
+      onDone = onDone || function() {
+      };
+      callback ? callback(this.joinCount, onDone) : onDone();
+    };
     this.liveSocket.wrapPush(this, { timeout: false }, () => {
-      return this.channel.join().receive("ok", (data) => !this.isDestroyed() && this.onJoin(data)).receive("error", (resp) => !this.isDestroyed() && this.onJoinError(resp)).receive("timeout", () => !this.isDestroyed() && this.onJoinError({ reason: "timeout" }));
+      return this.channel.join().receive("ok", (data) => {
+        if (!this.isDestroyed()) {
+          this.liveSocket.requestDOMUpdate(() => this.onJoin(data));
+        }
+      }).receive("error", (resp) => !this.isDestroyed() && this.onJoinError(resp)).receive("timeout", () => !this.isDestroyed() && this.onJoinError({ reason: "timeout" }));
     });
   }
   onJoinError(resp) {
-    if (resp.reason === "unauthorized" || resp.reason === "stale") {
+    if (resp.reason === "reload") {
+      this.log("error", () => [`failed mount with ${resp.status}. Falling back to page request`, resp]);
+      return this.onRedirect({ to: this.href });
+    } else if (resp.reason === "unauthorized" || resp.reason === "stale") {
       this.log("error", () => ["unauthorized live_redirect. Falling back to page request", resp]);
       return this.onRedirect({ to: this.href });
     }
@@ -2379,13 +2960,15 @@ var View = class {
       return this.onLiveRedirect(resp.live_redirect);
     }
     this.log("error", () => ["unable to join", resp]);
-    return this.liveSocket.reloadWithJitter(this);
+    if (this.liveSocket.isConnected()) {
+      this.liveSocket.reloadWithJitter(this);
+    }
   }
   onClose(reason) {
     if (this.isDestroyed()) {
       return;
     }
-    if (this.isJoinPending() && document.visibilityState !== "hidden" || this.liveSocket.hasPendingLink() && reason !== "leave") {
+    if (this.liveSocket.hasPendingLink() && reason !== "leave") {
       return this.liveSocket.reloadWithJitter(this);
     }
     this.destroyAllChildren();
@@ -2399,27 +2982,30 @@ var View = class {
   }
   onError(reason) {
     this.onClose(reason);
-    this.log("error", () => ["view crashed", reason]);
+    if (this.liveSocket.isConnected()) {
+      this.log("error", () => ["view crashed", reason]);
+    }
     if (!this.liveSocket.isUnloaded()) {
       this.displayError();
     }
   }
   displayError() {
     if (this.isMain()) {
-      dom_default.dispatchEvent(window, "phx:page-loading-start", { to: this.href, kind: "error" });
+      dom_default.dispatchEvent(window, "phx:page-loading-start", { detail: { to: this.href, kind: "error" } });
     }
     this.showLoader();
     this.setContainerClasses(PHX_DISCONNECTED_CLASS, PHX_ERROR_CLASS);
+    this.execAll(this.binding("disconnected"));
   }
   pushWithReply(refGenerator, event, payload, onReply = function() {
   }) {
     if (!this.isConnected()) {
       return;
     }
-    let [ref, [el]] = refGenerator ? refGenerator() : [null, []];
+    let [ref, [el], opts] = refGenerator ? refGenerator() : [null, [], {}];
     let onLoadingDone = function() {
     };
-    if (el && el.getAttribute(this.binding(PHX_PAGE_LOADING)) !== null) {
+    if (opts.page_loading || el && el.getAttribute(this.binding(PHX_PAGE_LOADING)) !== null) {
       onLoadingDone = this.liveSocket.withPageLoading({ kind: "element", target: el });
     }
     if (typeof payload.cid !== "number") {
@@ -2427,33 +3013,43 @@ var View = class {
     }
     return this.liveSocket.wrapPush(this, { timeout: true }, () => {
       return this.channel.push(event, payload, PUSH_TIMEOUT).receive("ok", (resp) => {
-        let hookReply = null;
-        if (ref !== null) {
-          this.undoRefs(ref);
-        }
+        let finish = (hookReply) => {
+          if (resp.redirect) {
+            this.onRedirect(resp.redirect);
+          }
+          if (resp.live_patch) {
+            this.onLivePatch(resp.live_patch);
+          }
+          if (resp.live_redirect) {
+            this.onLiveRedirect(resp.live_redirect);
+          }
+          if (ref !== null) {
+            this.undoRefs(ref);
+          }
+          onLoadingDone();
+          onReply(resp, hookReply);
+        };
         if (resp.diff) {
-          hookReply = this.applyDiff("update", resp.diff, ({ diff, events }) => {
-            this.update(diff, events);
+          this.liveSocket.requestDOMUpdate(() => {
+            this.applyDiff("update", resp.diff, ({ diff, reply, events }) => {
+              this.update(diff, events);
+              finish(reply);
+            });
           });
+        } else {
+          finish(null);
         }
-        if (resp.redirect) {
-          this.onRedirect(resp.redirect);
-        }
-        if (resp.live_patch) {
-          this.onLivePatch(resp.live_patch);
-        }
-        if (resp.live_redirect) {
-          this.onLiveRedirect(resp.live_redirect);
-        }
-        onLoadingDone();
-        onReply(resp, hookReply);
       });
     });
   }
   undoRefs(ref) {
-    dom_default.all(this.el, `[${PHX_REF}="${ref}"]`, (el) => {
+    if (!this.isConnected()) {
+      return;
+    }
+    dom_default.all(document, `[${PHX_REF_SRC}="${this.id}"][${PHX_REF}="${ref}"]`, (el) => {
       let disabledVal = el.getAttribute(PHX_DISABLED);
       el.removeAttribute(PHX_REF);
+      el.removeAttribute(PHX_REF_SRC);
       if (el.getAttribute(PHX_READONLY) !== null) {
         el.readOnly = false;
         el.removeAttribute(PHX_READONLY);
@@ -2479,35 +3075,50 @@ var View = class {
       }
     });
   }
-  putRef(elements, event) {
+  putRef(elements, event, opts = {}) {
     let newRef = this.ref++;
     let disableWith = this.binding(PHX_DISABLE_WITH);
+    if (opts.loading) {
+      elements = elements.concat(dom_default.all(document, opts.loading));
+    }
     elements.forEach((el) => {
       el.classList.add(`phx-${event}-loading`);
       el.setAttribute(PHX_REF, newRef);
+      el.setAttribute(PHX_REF_SRC, this.el.id);
       let disableText = el.getAttribute(disableWith);
       if (disableText !== null) {
         if (!el.getAttribute(PHX_DISABLE_WITH_RESTORE)) {
           el.setAttribute(PHX_DISABLE_WITH_RESTORE, el.innerText);
         }
-        el.innerText = disableText;
+        if (disableText !== "") {
+          el.innerText = disableText;
+        }
+        el.setAttribute("disabled", "");
       }
     });
-    return [newRef, elements];
+    return [newRef, elements, opts];
   }
   componentID(el) {
     let cid = el.getAttribute && el.getAttribute(PHX_COMPONENT);
     return cid ? parseInt(cid) : null;
   }
-  targetComponentID(target, targetCtx) {
-    if (target.getAttribute(this.binding("target"))) {
+  targetComponentID(target, targetCtx, opts = {}) {
+    if (isCid(targetCtx)) {
+      return targetCtx;
+    }
+    let cidOrSelector = target.getAttribute(this.binding("target"));
+    if (isCid(cidOrSelector)) {
+      return parseInt(cidOrSelector);
+    } else if (targetCtx && (cidOrSelector !== null || opts.target)) {
       return this.closestComponentID(targetCtx);
     } else {
       return null;
     }
   }
   closestComponentID(targetCtx) {
-    if (targetCtx) {
+    if (isCid(targetCtx)) {
+      return targetCtx;
+    } else if (targetCtx) {
       return maybe(targetCtx.closest(`[${PHX_COMPONENT}]`), (el) => this.ownsElement(el) && this.componentID(el));
     } else {
       return null;
@@ -2518,8 +3129,8 @@ var View = class {
       this.log("hook", () => ["unable to push hook event. LiveView not connected", event, payload]);
       return false;
     }
-    let [ref, els] = this.putRef([], "hook");
-    this.pushWithReply(() => [ref, els], "event", {
+    let [ref, els, opts] = this.putRef([], "hook");
+    this.pushWithReply(() => [ref, els, opts], "event", {
       type: "hook",
       event,
       value: payload,
@@ -2527,36 +3138,42 @@ var View = class {
     }, (resp, reply) => onReply(reply, ref));
     return ref;
   }
-  extractMeta(el, meta) {
+  extractMeta(el, meta, value) {
     let prefix = this.binding("value-");
     for (let i = 0; i < el.attributes.length; i++) {
+      if (!meta) {
+        meta = {};
+      }
       let name = el.attributes[i].name;
       if (name.startsWith(prefix)) {
         meta[name.replace(prefix, "")] = el.getAttribute(name);
       }
     }
     if (el.value !== void 0) {
+      if (!meta) {
+        meta = {};
+      }
       meta.value = el.value;
       if (el.tagName === "INPUT" && CHECKABLE_INPUTS.indexOf(el.type) >= 0 && !el.checked) {
         delete meta.value;
       }
     }
+    if (value) {
+      if (!meta) {
+        meta = {};
+      }
+      for (let key in value) {
+        meta[key] = value[key];
+      }
+    }
     return meta;
   }
-  pushEvent(type, el, targetCtx, phxEvent, meta) {
-    this.pushWithReply(() => this.putRef([el], type), "event", {
+  pushEvent(type, el, targetCtx, phxEvent, meta, opts = {}) {
+    this.pushWithReply(() => this.putRef([el], type, opts), "event", {
       type,
       event: phxEvent,
-      value: this.extractMeta(el, meta),
-      cid: this.targetComponentID(el, targetCtx)
-    });
-  }
-  pushKey(keyElement, targetCtx, kind, phxEvent, meta) {
-    this.pushWithReply(() => this.putRef([keyElement], kind), "event", {
-      type: kind,
-      event: phxEvent,
-      value: this.extractMeta(keyElement, meta),
-      cid: this.targetComponentID(keyElement, targetCtx)
+      value: this.extractMeta(el, meta, opts.value),
+      cid: this.targetComponentID(el, targetCtx, opts)
     });
   }
   pushFileProgress(fileEl, entryRef, progress, onReply = function() {
@@ -2571,11 +3188,16 @@ var View = class {
       }, onReply);
     });
   }
-  pushInput(inputEl, targetCtx, forceCid, phxEvent, eventTarget, callback) {
+  pushInput(inputEl, targetCtx, forceCid, phxEvent, opts, callback) {
     let uploads;
     let cid = isCid(forceCid) ? forceCid : this.targetComponentID(inputEl.form, targetCtx);
-    let refGenerator = () => this.putRef([inputEl, inputEl.form], "change");
-    let formData = serializeForm(inputEl.form, { _target: eventTarget.name });
+    let refGenerator = () => this.putRef([inputEl, inputEl.form], "change", opts);
+    let formData;
+    if (inputEl.getAttribute(this.binding("change"))) {
+      formData = serializeForm(inputEl.form, { _target: opts._target }, [inputEl.name]);
+    } else {
+      formData = serializeForm(inputEl.form, { _target: opts._target });
+    }
     if (dom_default.isUploadInput(inputEl) && inputEl.files && inputEl.files.length > 0) {
       LiveUploader.trackFiles(inputEl, Array.from(inputEl.files));
     }
@@ -2605,19 +3227,19 @@ var View = class {
   triggerAwaitingSubmit(formEl) {
     let awaitingSubmit = this.getScheduledSubmit(formEl);
     if (awaitingSubmit) {
-      let [_el, _ref, callback] = awaitingSubmit;
+      let [_el, _ref, _opts, callback] = awaitingSubmit;
       this.cancelSubmit(formEl);
       callback();
     }
   }
   getScheduledSubmit(formEl) {
-    return this.formSubmits.find(([el, _callback]) => el.isSameNode(formEl));
+    return this.formSubmits.find(([el, _ref, _opts, _callback]) => el.isSameNode(formEl));
   }
-  scheduleSubmit(formEl, ref, callback) {
+  scheduleSubmit(formEl, ref, opts, callback) {
     if (this.getScheduledSubmit(formEl)) {
       return true;
     }
-    this.formSubmits.push([formEl, ref, callback]);
+    this.formSubmits.push([formEl, ref, opts, callback]);
   }
   cancelSubmit(formEl) {
     this.formSubmits = this.formSubmits.filter(([el, ref, _callback]) => {
@@ -2629,7 +3251,7 @@ var View = class {
       }
     });
   }
-  pushFormSubmit(formEl, targetCtx, phxEvent, onReply) {
+  disableForm(formEl, opts = {}) {
     let filterIgnored = (el) => {
       let userIgnored = closestPhxBinding(el, `${this.binding(PHX_UPDATE)}=ignore`, el.form);
       return !(userIgnored || closestPhxBinding(el, "data-phx-update=ignore", el.form));
@@ -2639,33 +3261,35 @@ var View = class {
     };
     let filterButton = (el) => el.tagName == "BUTTON";
     let filterInput = (el) => ["INPUT", "TEXTAREA", "SELECT"].includes(el.tagName);
-    let refGenerator = () => {
-      let formElements = Array.from(formEl.elements);
-      let disables = formElements.filter(filterDisables);
-      let buttons = formElements.filter(filterButton).filter(filterIgnored);
-      let inputs = formElements.filter(filterInput).filter(filterIgnored);
-      buttons.forEach((button) => {
-        button.setAttribute(PHX_DISABLED, button.disabled);
-        button.disabled = true;
-      });
-      inputs.forEach((input) => {
-        input.setAttribute(PHX_READONLY, input.readOnly);
-        input.readOnly = true;
-        if (input.files) {
-          input.setAttribute(PHX_DISABLED, input.disabled);
-          input.disabled = true;
-        }
-      });
-      formEl.setAttribute(this.binding(PHX_PAGE_LOADING), "");
-      return this.putRef([formEl].concat(disables).concat(buttons).concat(inputs), "submit");
-    };
+    let formElements = Array.from(formEl.elements);
+    let disables = formElements.filter(filterDisables);
+    let buttons = formElements.filter(filterButton).filter(filterIgnored);
+    let inputs = formElements.filter(filterInput).filter(filterIgnored);
+    buttons.forEach((button) => {
+      button.setAttribute(PHX_DISABLED, button.disabled);
+      button.disabled = true;
+    });
+    inputs.forEach((input) => {
+      input.setAttribute(PHX_READONLY, input.readOnly);
+      input.readOnly = true;
+      if (input.files) {
+        input.setAttribute(PHX_DISABLED, input.disabled);
+        input.disabled = true;
+      }
+    });
+    formEl.setAttribute(this.binding(PHX_PAGE_LOADING), "");
+    return this.putRef([formEl].concat(disables).concat(buttons).concat(inputs), "submit", opts);
+  }
+  pushFormSubmit(formEl, targetCtx, phxEvent, opts, onReply) {
+    let refGenerator = () => this.disableForm(formEl, opts);
     let cid = this.targetComponentID(formEl, targetCtx);
     if (LiveUploader.hasUploadsInProgress(formEl)) {
       let [ref, _els] = refGenerator();
-      return this.scheduleSubmit(formEl, ref, () => this.pushFormSubmit(formEl, targetCtx, phxEvent, onReply));
+      let push = () => this.pushFormSubmit(formEl, targetCtx, phxEvent, opts, onReply);
+      return this.scheduleSubmit(formEl, ref, opts, push);
     } else if (LiveUploader.inputsAwaitingPreflight(formEl).length > 0) {
       let [ref, els] = refGenerator();
-      let proxyRefGen = () => [ref, els];
+      let proxyRefGen = () => [ref, els, opts];
       this.uploadFiles(formEl, targetCtx, ref, cid, (_uploads) => {
         let formData = serializeForm(formEl, {});
         this.pushWithReply(proxyRefGen, "event", {
@@ -2676,7 +3300,7 @@ var View = class {
         }, onReply);
       });
     } else {
-      let formData = serializeForm(formEl);
+      let formData = serializeForm(formEl, {});
       this.pushWithReply(refGenerator, "event", {
         type: "form",
         event: phxEvent,
@@ -2730,30 +3354,40 @@ var View = class {
     } else if (inputs.length > 1) {
       logError(`duplicate live file inputs found matching the name "${name}"`);
     } else {
-      dom_default.dispatchEvent(inputs[0], PHX_TRACK_UPLOADS, { files: filesOrBlobs });
+      dom_default.dispatchEvent(inputs[0], PHX_TRACK_UPLOADS, { detail: { files: filesOrBlobs } });
     }
   }
   pushFormRecovery(form, newCid, callback) {
     this.liveSocket.withinOwners(form, (view, targetCtx) => {
-      let input = form.elements[0];
+      let input = Array.from(form.elements).find((el) => {
+        return dom_default.isFormInput(el) && el.type !== "hidden" && !el.hasAttribute(this.binding("change"));
+      });
       let phxEvent = form.getAttribute(this.binding(PHX_AUTO_RECOVER)) || form.getAttribute(this.binding("change"));
-      view.pushInput(input, targetCtx, newCid, phxEvent, input, callback);
+      js_default.exec("change", phxEvent, view, input, ["push", { _target: input.name, newCid, callback }]);
     });
   }
   pushLinkPatch(href, targetEl, callback) {
     let linkRef = this.liveSocket.setPendingLink(href);
     let refGen = targetEl ? () => this.putRef([targetEl], "click") : null;
-    this.pushWithReply(refGen, "live_patch", { url: href }, (resp) => {
-      if (resp.link_redirect) {
-        this.liveSocket.replaceMain(href, null, callback, linkRef);
-      } else {
-        if (this.liveSocket.commitPendingLink(linkRef)) {
-          this.href = href;
+    let fallback = () => this.liveSocket.redirect(window.location.href);
+    let push = this.pushWithReply(refGen, "live_patch", { url: href }, (resp) => {
+      this.liveSocket.requestDOMUpdate(() => {
+        if (resp.link_redirect) {
+          this.liveSocket.replaceMain(href, null, callback, linkRef);
+        } else {
+          if (this.liveSocket.commitPendingLink(linkRef)) {
+            this.href = href;
+          }
+          this.applyPendingUpdates();
+          callback && callback(linkRef);
         }
-        this.applyPendingUpdates();
-        callback && callback(linkRef);
-      }
-    }).receive("timeout", () => this.liveSocket.redirect(window.location.href));
+      });
+    });
+    if (push) {
+      push.receive("timeout", fallback);
+    } else {
+      fallback();
+    }
   }
   formsForRecovery(html) {
     if (this.joinCount === 0) {
@@ -2765,7 +3399,7 @@ var View = class {
     return dom_default.all(this.el, `form[${phxChange}]`).filter((form) => form.id && this.ownsElement(form)).filter((form) => form.elements.length > 0).filter((form) => form.getAttribute(this.binding(PHX_AUTO_RECOVER)) !== "ignore").map((form) => {
       let newForm = template.content.querySelector(`form[id="${form.id}"][${phxChange}="${form.getAttribute(phxChange)}"]`);
       if (newForm) {
-        return [form, newForm, this.componentID(newForm)];
+        return [form, newForm, this.targetComponentID(newForm)];
       } else {
         return [form, null, null];
       }
@@ -2791,12 +3425,17 @@ var View = class {
     }
   }
   ownsElement(el) {
-    return el.getAttribute(PHX_PARENT_ID) === this.id || maybe(el.closest(PHX_VIEW_SELECTOR), (node) => node.id) === this.id;
+    let parentViewEl = el.closest(PHX_VIEW_SELECTOR);
+    return el.getAttribute(PHX_PARENT_ID) === this.id || parentViewEl && parentViewEl.id === this.id || !parentViewEl && this.isDead;
   }
-  submitForm(form, targetCtx, phxEvent) {
+  submitForm(form, targetCtx, phxEvent, opts = {}) {
     dom_default.putPrivate(form, PHX_HAS_SUBMITTED, true);
+    let phxFeedback = this.liveSocket.binding(PHX_FEEDBACK_FOR);
+    let inputs = Array.from(form.elements);
+    inputs.forEach((input) => dom_default.putPrivate(input, PHX_HAS_SUBMITTED, true));
     this.liveSocket.blurActiveElement(this);
-    this.pushFormSubmit(form, targetCtx, phxEvent, () => {
+    this.pushFormSubmit(form, targetCtx, phxEvent, opts, () => {
+      inputs.forEach((input) => dom_default.showError(input, phxFeedback));
       this.liveSocket.restorePreviouslyActiveFocus();
     });
   }
@@ -2814,7 +3453,7 @@ var LiveSocket = class {
       a phoenix Socket must be provided as the second argument to the LiveSocket constructor. For example:
 
           import {Socket} from "phoenix"
-          import LiveSocket from "phoenix_live_view"
+          import {LiveSocket} from "phoenix_live_view"
           let liveSocket = new LiveSocket("/live", Socket, {...})
       `);
     }
@@ -2829,6 +3468,8 @@ var LiveSocket = class {
     this.prevActive = null;
     this.silenced = false;
     this.main = null;
+    this.outgoingMainEl = null;
+    this.clickStartedAtTarget = null;
     this.linkRef = 1;
     this.roots = {};
     this.href = window.location.href;
@@ -2837,10 +3478,16 @@ var LiveSocket = class {
     this.hooks = opts.hooks || {};
     this.uploaders = opts.uploaders || {};
     this.loaderTimeout = opts.loaderTimeout || LOADER_TIMEOUT;
+    this.reloadWithJitterTimer = null;
+    this.maxReloads = opts.maxReloads || MAX_RELOADS;
+    this.reloadJitterMin = opts.reloadJitterMin || RELOAD_JITTER_MIN;
+    this.reloadJitterMax = opts.reloadJitterMax || RELOAD_JITTER_MAX;
+    this.failsafeJitter = opts.failsafeJitter || FAILSAFE_JITTER;
     this.localStorage = opts.localStorage || window.localStorage;
     this.sessionStorage = opts.sessionStorage || window.sessionStorage;
     this.boundTopLevelEvents = false;
     this.domCallbacks = Object.assign({ onNodeAdded: closure(), onBeforeElUpdated: closure() }, opts.dom || {});
+    this.transitions = new TransitionSet();
     window.addEventListener("pagehide", (_e) => {
       this.unloaded = true;
     });
@@ -2856,6 +3503,9 @@ var LiveSocket = class {
   isDebugEnabled() {
     return this.sessionStorage.getItem(PHX_LV_DEBUG) === "true";
   }
+  isDebugDisabled() {
+    return this.sessionStorage.getItem(PHX_LV_DEBUG) === "false";
+  }
   enableDebug() {
     this.sessionStorage.setItem(PHX_LV_DEBUG, "true");
   }
@@ -2863,7 +3513,7 @@ var LiveSocket = class {
     this.sessionStorage.setItem(PHX_LV_PROFILE, "true");
   }
   disableDebug() {
-    this.sessionStorage.removeItem(PHX_LV_DEBUG);
+    this.sessionStorage.setItem(PHX_LV_DEBUG, "false");
   }
   disableProfiling() {
     this.sessionStorage.removeItem(PHX_LV_PROFILE);
@@ -2884,11 +3534,19 @@ var LiveSocket = class {
     return this.socket;
   }
   connect() {
+    if (window.location.hostname === "localhost" && !this.isDebugDisabled()) {
+      this.enableDebug();
+    }
     let doConnect = () => {
       if (this.joinRootViews()) {
         this.bindTopLevelEvents();
         this.socket.connect();
+      } else if (this.main) {
+        this.socket.connect();
+      } else {
+        this.bindTopLevelEvents({ dead: true });
       }
+      this.joinDeadView();
     };
     if (["complete", "loaded", "interactive"].indexOf(document.readyState) >= 0) {
       doConnect();
@@ -2897,8 +3555,28 @@ var LiveSocket = class {
     }
   }
   disconnect(callback) {
+    clearTimeout(this.reloadWithJitterTimer);
     this.socket.disconnect(callback);
   }
+  replaceTransport(transport) {
+    clearTimeout(this.reloadWithJitterTimer);
+    this.socket.replaceTransport(transport);
+    this.connect();
+  }
+  execJS(el, encodedJS, eventType = null) {
+    this.owner(el, (view) => js_default.exec(eventType, encodedJS, view, el));
+  }
+  unload() {
+    if (this.unloaded) {
+      return;
+    }
+    if (this.main && this.isConnected()) {
+      this.log(this.main, "socket", () => ["disconnect for page nav"]);
+    }
+    this.unloaded = true;
+    this.destroyAllViews();
+    this.disconnect();
+  }
   triggerDOM(kind, args) {
     this.domCallbacks[kind](...args);
   }
@@ -2920,13 +3598,19 @@ var LiveSocket = class {
       debug(view, kind, msg, obj);
     }
   }
+  requestDOMUpdate(callback) {
+    this.transitions.after(callback);
+  }
+  transition(time, onStart, onDone = function() {
+  }) {
+    this.transitions.addTransition(time, onStart, onDone);
+  }
   onChannel(channel, event, cb) {
     channel.on(event, (data) => {
       let latency = this.getLatencySim();
       if (!latency) {
         cb(data);
       } else {
-        console.log(`simulating ${latency}ms of latency from server to client`);
         setTimeout(() => cb(data), latency);
       }
     });
@@ -2935,7 +3619,7 @@ var LiveSocket = class {
     let latency = this.getLatencySim();
     let oldJoinCount = view.joinCount;
     if (!latency) {
-      if (opts.timeout) {
+      if (this.isConnected() && opts.timeout) {
         return push().receive("timeout", () => {
           if (view.joinCount === oldJoinCount && !view.isDestroyed()) {
             this.reloadWithJitter(view, () => {
@@ -2947,7 +3631,6 @@ var LiveSocket = class {
         return push();
       }
     }
-    console.log(`simulating ${latency}ms of latency from client to server`);
     let fakePush = {
       receives: [],
       receive(kind, cb) {
@@ -2963,17 +3646,24 @@ var LiveSocket = class {
     return fakePush;
   }
   reloadWithJitter(view, log) {
-    view.destroy();
+    clearTimeout(this.reloadWithJitterTimer);
     this.disconnect();
-    let [minMs, maxMs] = RELOAD_JITTER;
+    let minMs = this.reloadJitterMin;
+    let maxMs = this.reloadJitterMax;
     let afterMs = Math.floor(Math.random() * (maxMs - minMs + 1)) + minMs;
     let tries = browser_default.updateLocal(this.localStorage, window.location.pathname, CONSECUTIVE_RELOADS, 0, (count) => count + 1);
-    log ? log() : this.log(view, "join", () => [`encountered ${tries} consecutive reloads`]);
-    if (tries > MAX_RELOADS) {
-      this.log(view, "join", () => [`exceeded ${MAX_RELOADS} consecutive reloads. Entering failsafe mode`]);
-      afterMs = FAILSAFE_JITTER;
+    if (tries > this.maxReloads) {
+      afterMs = this.failsafeJitter;
     }
-    setTimeout(() => {
+    this.reloadWithJitterTimer = setTimeout(() => {
+      if (view.isDestroyed() || view.isConnected()) {
+        return;
+      }
+      view.destroy();
+      log ? log() : this.log(view, "join", () => [`encountered ${tries} consecutive reloads`]);
+      if (tries > this.maxReloads) {
+        this.log(view, "join", () => [`exceeded ${this.maxReloads} consecutive reloads. Entering failsafe mode`]);
+      }
       if (this.hasPendingLink()) {
         window.location = this.pendingLink;
       } else {
@@ -2999,6 +3689,18 @@ var LiveSocket = class {
   channel(topic, params) {
     return this.socket.channel(topic, params);
   }
+  joinDeadView() {
+    let body = document.body;
+    if (body && !this.isPhxView(body) && !this.isPhxView(document.firstElementChild)) {
+      let view = this.newRootView(body);
+      view.setHref(this.getHref());
+      view.joinDead();
+      if (!this.main) {
+        this.main = view;
+      }
+      window.requestAnimationFrame(() => view.execNewMounted());
+    }
+  }
   joinRootViews() {
     let rootsFound = false;
     dom_default.all(document, `${PHX_VIEW_SELECTOR}:not([${PHX_PARENT_ID}])`, (rootEl) => {
@@ -3006,7 +3708,7 @@ var LiveSocket = class {
         let view = this.newRootView(rootEl);
         view.setHref(this.getHref());
         view.join();
-        if (rootEl.getAttribute(PHX_MAIN)) {
+        if (rootEl.hasAttribute(PHX_MAIN)) {
           this.main = view;
         }
       }
@@ -3015,46 +3717,55 @@ var LiveSocket = class {
     return rootsFound;
   }
   redirect(to, flash) {
-    this.disconnect();
+    this.unload();
     browser_default.redirect(to, flash);
   }
   replaceMain(href, flash, callback = null, linkRef = this.setPendingLink(href)) {
-    let oldMainEl = this.main.el;
-    let newMainEl = dom_default.cloneNode(oldMainEl, "");
+    let liveReferer = this.currentLocation.href;
+    this.outgoingMainEl = this.outgoingMainEl || this.main.el;
+    let newMainEl = dom_default.cloneNode(this.outgoingMainEl, "");
     this.main.showLoader(this.loaderTimeout);
     this.main.destroy();
-    this.main = this.newRootView(newMainEl, flash);
+    this.main = this.newRootView(newMainEl, flash, liveReferer);
     this.main.setRedirect(href);
-    this.main.join((joinCount) => {
+    this.transitionRemoves();
+    this.main.join((joinCount, onDone) => {
       if (joinCount === 1 && this.commitPendingLink(linkRef)) {
-        oldMainEl.replaceWith(newMainEl);
-        callback && callback();
+        this.requestDOMUpdate(() => {
+          dom_default.findPhxSticky(document).forEach((el) => newMainEl.appendChild(el));
+          this.outgoingMainEl.replaceWith(newMainEl);
+          this.outgoingMainEl = null;
+          callback && requestAnimationFrame(callback);
+          onDone();
+        });
+      }
+    });
+  }
+  transitionRemoves(elements) {
+    let removeAttr = this.binding("remove");
+    elements = elements || dom_default.all(document, `[${removeAttr}]`);
+    elements.forEach((el) => {
+      if (document.body.contains(el)) {
+        this.execJS(el, el.getAttribute(removeAttr), "remove");
       }
     });
   }
   isPhxView(el) {
     return el.getAttribute && el.getAttribute(PHX_SESSION) !== null;
   }
-  newRootView(el, flash) {
-    let view = new View(el, this, null, flash);
+  newRootView(el, flash, liveReferer) {
+    let view = new View(el, this, null, flash, liveReferer);
     this.roots[view.id] = view;
     return view;
   }
   owner(childEl, callback) {
-    let view = maybe(childEl.closest(PHX_VIEW_SELECTOR), (el) => this.getViewByEl(el));
+    let view = maybe(childEl.closest(PHX_VIEW_SELECTOR), (el) => this.getViewByEl(el)) || this.main;
     if (view) {
       callback(view);
     }
   }
   withinOwners(childEl, callback) {
-    this.owner(childEl, (view) => {
-      let phxTarget = childEl.getAttribute(this.binding("target"));
-      if (phxTarget === null) {
-        callback(view, childEl);
-      } else {
-        view.withinTargets(phxTarget, callback);
-      }
-    });
+    this.owner(childEl, (view) => callback(view, childEl));
   }
   getViewByEl(el) {
     let rootId = el.getAttribute(PHX_ROOT_ID);
@@ -3068,10 +3779,14 @@ var LiveSocket = class {
       this.roots[id].destroy();
       delete this.roots[id];
     }
+    this.main = null;
   }
   destroyViewByEl(el) {
     let root = this.getRootById(el.getAttribute(PHX_ROOT_ID));
-    if (root) {
+    if (root && root.id === el.id) {
+      root.destroy();
+      delete this.roots[root.id];
+    } else if (root) {
       root.destroyDescendent(el.id);
     }
   }
@@ -3113,11 +3828,19 @@ var LiveSocket = class {
       this.prevActive.blur();
     }
   }
-  bindTopLevelEvents() {
+  bindTopLevelEvents({ dead } = {}) {
     if (this.boundTopLevelEvents) {
       return;
     }
     this.boundTopLevelEvents = true;
+    this.socket.onClose((event) => {
+      if (event && event.code === 1001) {
+        return this.unload();
+      }
+      if (event && event.code === 1e3 && this.main) {
+        return this.reloadWithJitter(this.main);
+      }
+    });
     document.body.addEventListener("click", function() {
     });
     window.addEventListener("pageshow", (e) => {
@@ -3127,25 +3850,32 @@ var LiveSocket = class {
         window.location.reload();
       }
     }, true);
-    this.bindNav();
+    if (!dead) {
+      this.bindNav();
+    }
     this.bindClicks();
-    this.bindForms();
-    this.bind({ keyup: "keyup", keydown: "keydown" }, (e, type, view, target, targetCtx, phxEvent, _phxTarget) => {
-      let matchKey = target.getAttribute(this.binding(PHX_KEY));
+    if (!dead) {
+      this.bindForms();
+    }
+    this.bind({ keyup: "keyup", keydown: "keydown" }, (e, type, view, targetEl, phxEvent, eventTarget) => {
+      let matchKey = targetEl.getAttribute(this.binding(PHX_KEY));
       let pressedKey = e.key && e.key.toLowerCase();
       if (matchKey && matchKey.toLowerCase() !== pressedKey) {
         return;
       }
-      view.pushKey(target, targetCtx, type, phxEvent, { key: e.key, ...this.eventMeta(type, e, target) });
+      let data = { key: e.key, ...this.eventMeta(type, e, targetEl) };
+      js_default.exec(type, phxEvent, view, targetEl, ["push", { data }]);
     });
-    this.bind({ blur: "focusout", focus: "focusin" }, (e, type, view, targetEl, targetCtx, phxEvent, phxTarget) => {
-      if (!phxTarget) {
-        view.pushEvent(type, targetEl, targetCtx, phxEvent, this.eventMeta(type, e, targetEl));
+    this.bind({ blur: "focusout", focus: "focusin" }, (e, type, view, targetEl, phxEvent, eventTarget) => {
+      if (!eventTarget) {
+        let data = { key: e.key, ...this.eventMeta(type, e, targetEl) };
+        js_default.exec(type, phxEvent, view, targetEl, ["push", { data }]);
       }
     });
     this.bind({ blur: "blur", focus: "focus" }, (e, type, view, targetEl, targetCtx, phxEvent, phxTarget) => {
-      if (phxTarget && !phxTarget !== "window") {
-        view.pushEvent(type, targetEl, targetCtx, phxEvent, this.eventMeta(type, e, targetEl));
+      if (phxTarget === "window") {
+        let data = this.eventMeta(type, e, targetEl);
+        js_default.exec(type, phxEvent, view, targetEl, ["push", { data }]);
       }
     });
     window.addEventListener("dragover", (e) => e.preventDefault());
@@ -3159,7 +3889,7 @@ var LiveSocket = class {
       if (!dropTarget || dropTarget.disabled || files.length === 0 || !(dropTarget.files instanceof FileList)) {
         return;
       }
-      LiveUploader.trackFiles(dropTarget, files);
+      LiveUploader.trackFiles(dropTarget, files, e.dataTransfer);
       dropTarget.dispatchEvent(new Event("input", { bubbles: true }));
     });
     this.on(PHX_TRACK_UPLOADS, (e) => {
@@ -3204,17 +3934,17 @@ var LiveSocket = class {
         let windowBinding = this.binding(`window-${event}`);
         let targetPhxEvent = e.target.getAttribute && e.target.getAttribute(binding);
         if (targetPhxEvent) {
-          this.debounce(e.target, e, () => {
-            this.withinOwners(e.target, (view, targetCtx) => {
-              callback(e, event, view, e.target, targetCtx, targetPhxEvent, null);
+          this.debounce(e.target, e, browserEventName, () => {
+            this.withinOwners(e.target, (view) => {
+              callback(e, event, view, e.target, targetPhxEvent, null);
             });
           });
         } else {
           dom_default.all(document, `[${windowBinding}]`, (el) => {
             let phxEvent = el.getAttribute(windowBinding);
-            this.debounce(el, e, () => {
-              this.withinOwners(el, (view, targetCtx) => {
-                callback(e, event, view, el, targetCtx, phxEvent, "window");
+            this.debounce(el, e, browserEventName, () => {
+              this.withinOwners(el, (view) => {
+                callback(e, event, view, el, phxEvent, "window");
               });
             });
           });
@@ -3223,35 +3953,53 @@ var LiveSocket = class {
     }
   }
   bindClicks() {
+    window.addEventListener("click", (e) => this.clickStartedAtTarget = e.target);
     this.bindClick("click", "click", false);
     this.bindClick("mousedown", "capture-click", true);
   }
   bindClick(eventName, bindingName, capture) {
     let click = this.binding(bindingName);
     window.addEventListener(eventName, (e) => {
-      if (!this.isConnected()) {
-        return;
-      }
       let target = null;
       if (capture) {
         target = e.target.matches(`[${click}]`) ? e.target : e.target.querySelector(`[${click}]`);
       } else {
-        target = closestPhxBinding(e.target, click);
+        let clickStartedAtTarget = this.clickStartedAtTarget || e.target;
+        target = closestPhxBinding(clickStartedAtTarget, click);
+        this.dispatchClickAway(e, clickStartedAtTarget);
+        this.clickStartedAtTarget = null;
       }
       let phxEvent = target && target.getAttribute(click);
       if (!phxEvent) {
+        let href = e.target instanceof HTMLAnchorElement ? e.target.getAttribute("href") : null;
+        if (!capture && href !== null && !dom_default.wantsNewTab(e) && dom_default.isNewPageHref(href, window.location)) {
+          this.unload();
+        }
         return;
       }
       if (target.getAttribute("href") === "#") {
         e.preventDefault();
       }
-      this.debounce(target, e, () => {
-        this.withinOwners(target, (view, targetCtx) => {
-          view.pushEvent("click", target, targetCtx, phxEvent, this.eventMeta("click", e, target));
+      this.debounce(target, e, "click", () => {
+        this.withinOwners(target, (view) => {
+          js_default.exec("click", phxEvent, view, target, ["push", { data: this.eventMeta("click", e, target) }]);
         });
       });
     }, capture);
   }
+  dispatchClickAway(e, clickStartedAt) {
+    let phxClickAway = this.binding("click-away");
+    dom_default.all(document, `[${phxClickAway}]`, (el) => {
+      if (!(el.isSameNode(clickStartedAt) || el.contains(clickStartedAt))) {
+        this.withinOwners(e.target, (view) => {
+          let phxEvent = el.getAttribute(phxClickAway);
+          if (js_default.isVisible(el)) {
+            js_default.exec("click", phxEvent, view, el, ["push", { data: this.eventMeta("click", e, e.target) }]);
+          }
+        });
+      }
+    });
+  }
   bindNav() {
     if (!browser_default.canPushState()) {
       return;
@@ -3272,49 +4020,71 @@ var LiveSocket = class {
       }
       let { type, id, root, scroll } = event.state || {};
       let href = window.location.href;
-      if (this.main.isConnected() && (type === "patch" && id === this.main.id)) {
-        this.main.pushLinkPatch(href, null);
-      } else {
-        this.replaceMain(href, null, () => {
-          if (root) {
-            this.replaceRootHistory();
-          }
-          if (typeof scroll === "number") {
-            setTimeout(() => {
-              window.scrollTo(0, scroll);
-            }, 0);
-          }
-        });
-      }
+      this.requestDOMUpdate(() => {
+        if (this.main.isConnected() && (type === "patch" && id === this.main.id)) {
+          this.main.pushLinkPatch(href, null, () => {
+            this.maybeScroll(scroll);
+          });
+        } else {
+          this.replaceMain(href, null, () => {
+            if (root) {
+              this.replaceRootHistory();
+            }
+            this.maybeScroll(scroll);
+          });
+        }
+      });
     }, false);
     window.addEventListener("click", (e) => {
       let target = closestPhxBinding(e.target, PHX_LIVE_LINK);
       let type = target && target.getAttribute(PHX_LIVE_LINK);
-      let wantsNewTab = e.metaKey || e.ctrlKey || e.button === 1;
-      if (!type || !this.isConnected() || !this.main || wantsNewTab) {
+      if (!type || !this.isConnected() || !this.main || dom_default.wantsNewTab(e)) {
         return;
       }
       let href = target.href;
       let linkState = target.getAttribute(PHX_LINK_STATE);
       e.preventDefault();
+      e.stopImmediatePropagation();
       if (this.pendingLink === href) {
         return;
       }
-      if (type === "patch") {
-        this.pushHistoryPatch(href, linkState, target);
-      } else if (type === "redirect") {
-        this.historyRedirect(href, linkState);
-      } else {
-        throw new Error(`expected ${PHX_LIVE_LINK} to be "patch" or "redirect", got: ${type}`);
-      }
+      this.requestDOMUpdate(() => {
+        if (type === "patch") {
+          this.pushHistoryPatch(href, linkState, target);
+        } else if (type === "redirect") {
+          this.historyRedirect(href, linkState);
+        } else {
+          throw new Error(`expected ${PHX_LIVE_LINK} to be "patch" or "redirect", got: ${type}`);
+        }
+        let phxClick = target.getAttribute(this.binding("click"));
+        if (phxClick) {
+          this.requestDOMUpdate(() => this.execJS(target, phxClick, "click"));
+        }
+      });
     }, false);
   }
+  maybeScroll(scroll) {
+    if (typeof scroll === "number") {
+      requestAnimationFrame(() => {
+        window.scrollTo(0, scroll);
+      });
+    }
+  }
+  dispatchEvent(event, payload = {}) {
+    dom_default.dispatchEvent(window, `phx:${event}`, { detail: payload });
+  }
+  dispatchEvents(events) {
+    events.forEach(([event, payload]) => this.dispatchEvent(event, payload));
+  }
   withPageLoading(info, callback) {
-    dom_default.dispatchEvent(window, "phx:page-loading-start", info);
-    let done = () => dom_default.dispatchEvent(window, "phx:page-loading-stop", info);
+    dom_default.dispatchEvent(window, "phx:page-loading-start", { detail: info });
+    let done = () => dom_default.dispatchEvent(window, "phx:page-loading-stop", { detail: info });
     return callback ? callback(done) : done;
   }
   pushHistoryPatch(href, linkState, targetEl) {
+    if (!this.isConnected()) {
+      return browser_default.redirect(href);
+    }
     this.withPageLoading({ to: href, kind: "patch" }, (done) => {
       this.main.pushLinkPatch(href, targetEl, (linkRef) => {
         this.historyPatch(href, linkState, linkRef);
@@ -3330,6 +4100,13 @@ var LiveSocket = class {
     this.registerNewLocation(window.location);
   }
   historyRedirect(href, linkState, flash) {
+    if (!this.isConnected()) {
+      return browser_default.redirect(href, flash);
+    }
+    if (/^\/$|^\/[^\/]+.*$/.test(href)) {
+      let { protocol, host } = window.location;
+      href = `${protocol}//${host}${href}`;
+    }
     let scroll = window.scrollY;
     this.withPageLoading({ to: href, kind: "redirect" }, (done) => {
       this.replaceMain(href, flash, () => {
@@ -3353,25 +4130,52 @@ var LiveSocket = class {
   }
   bindForms() {
     let iterations = 0;
+    let externalFormSubmitted = false;
+    this.on("submit", (e) => {
+      let phxSubmit = e.target.getAttribute(this.binding("submit"));
+      let phxChange = e.target.getAttribute(this.binding("change"));
+      if (!externalFormSubmitted && phxChange && !phxSubmit) {
+        externalFormSubmitted = true;
+        e.preventDefault();
+        this.withinOwners(e.target, (view) => {
+          view.disableForm(e.target);
+          window.requestAnimationFrame(() => {
+            if (dom_default.isUnloadableFormSubmit(e)) {
+              this.unload();
+            }
+            e.target.submit();
+          });
+        });
+      }
+    }, true);
     this.on("submit", (e) => {
       let phxEvent = e.target.getAttribute(this.binding("submit"));
       if (!phxEvent) {
+        if (dom_default.isUnloadableFormSubmit(e)) {
+          this.unload();
+        }
         return;
       }
       e.preventDefault();
       e.target.disabled = true;
-      this.withinOwners(e.target, (view, targetCtx) => view.submitForm(e.target, targetCtx, phxEvent));
+      this.withinOwners(e.target, (view) => {
+        js_default.exec("submit", phxEvent, view, e.target, ["push", {}]);
+      });
     }, false);
     for (let type of ["change", "input"]) {
       this.on(type, (e) => {
+        let phxChange = this.binding("change");
         let input = e.target;
-        let phxEvent = input.form && input.form.getAttribute(this.binding("change"));
+        let inputEvent = input.getAttribute(phxChange);
+        let formEvent = input.form && input.form.getAttribute(phxChange);
+        let phxEvent = inputEvent || formEvent;
         if (!phxEvent) {
           return;
         }
         if (input.type === "number" && input.validity && input.validity.badInput) {
           return;
         }
+        let dispatcher = inputEvent ? input : input.form;
         let currentIterations = iterations;
         iterations++;
         let { at, type: lastType } = dom_default.private(input, "prev-iteration") || {};
@@ -3379,24 +4183,40 @@ var LiveSocket = class {
           return;
         }
         dom_default.putPrivate(input, "prev-iteration", { at: currentIterations, type });
-        this.debounce(input, e, () => {
-          this.withinOwners(input.form, (view, targetCtx) => {
+        this.debounce(input, e, type, () => {
+          this.withinOwners(dispatcher, (view) => {
             dom_default.putPrivate(input, PHX_HAS_FOCUSED, true);
             if (!dom_default.isTextualInput(input)) {
               this.setActiveElement(input);
             }
-            view.pushInput(input, targetCtx, null, phxEvent, e.target);
+            js_default.exec("change", phxEvent, view, input, ["push", { _target: e.target.name, dispatcher }]);
           });
         });
       }, false);
     }
+    this.on("reset", (e) => {
+      let form = e.target;
+      dom_default.resetForm(form, this.binding(PHX_FEEDBACK_FOR));
+      let input = Array.from(form.elements).find((el) => el.type === "reset");
+      window.requestAnimationFrame(() => {
+        input.dispatchEvent(new Event("input", { bubbles: true, cancelable: false }));
+      });
+    });
   }
-  debounce(el, event, callback) {
+  debounce(el, event, eventType, callback) {
+    if (eventType === "blur" || eventType === "focusout") {
+      return callback();
+    }
     let phxDebounce = this.binding(PHX_DEBOUNCE);
     let phxThrottle = this.binding(PHX_THROTTLE);
     let defaultDebounce = this.defaults.debounce.toString();
     let defaultThrottle = this.defaults.throttle.toString();
-    dom_default.debounce(el, event, phxDebounce, defaultDebounce, phxThrottle, defaultThrottle, callback);
+    this.withinOwners(el, (view) => {
+      let asyncFilter = () => !view.isDestroyed() && document.body.contains(el);
+      dom_default.debounce(el, event, phxDebounce, defaultDebounce, phxThrottle, defaultThrottle, asyncFilter, () => {
+        callback();
+      });
+    });
   }
   silenceEvents(callback) {
     this.silenced = true;
@@ -3411,4 +4231,49 @@ var LiveSocket = class {
     });
   }
 };
+var TransitionSet = class {
+  constructor() {
+    this.transitions = new Set();
+    this.pendingOps = [];
+  }
+  reset() {
+    this.transitions.forEach((timer) => {
+      clearTimeout(timer);
+      this.transitions.delete(timer);
+    });
+    this.flushPendingOps();
+  }
+  after(callback) {
+    if (this.size() === 0) {
+      callback();
+    } else {
+      this.pushPendingOp(callback);
+    }
+  }
+  addTransition(time, onStart, onDone) {
+    onStart();
+    let timer = setTimeout(() => {
+      this.transitions.delete(timer);
+      onDone();
+      this.flushPendingOps();
+    }, time);
+    this.transitions.add(timer);
+  }
+  pushPendingOp(op) {
+    this.pendingOps.push(op);
+  }
+  size() {
+    return this.transitions.size;
+  }
+  flushPendingOps() {
+    if (this.size() > 0) {
+      return;
+    }
+    let op = this.pendingOps.shift();
+    if (op) {
+      op();
+      this.flushPendingOps();
+    }
+  }
+};
 //# sourceMappingURL=phoenix_live_view.cjs.js.map
diff --git a/priv/static/phoenix_live_view.cjs.js.map b/priv/static/phoenix_live_view.cjs.js.map
index 5ec8d2278a..5a970106cb 100644
--- a/priv/static/phoenix_live_view.cjs.js.map
+++ b/priv/static/phoenix_live_view.cjs.js.map
@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../assets/js/phoenix_live_view/index.js", "../../assets/js/phoenix_live_view/constants.js", "../../assets/js/phoenix_live_view/entry_uploader.js", "../../assets/js/phoenix_live_view/utils.js", "../../assets/js/phoenix_live_view/browser.js", "../../assets/js/phoenix_live_view/dom.js", "../../assets/js/phoenix_live_view/upload_entry.js", "../../assets/js/phoenix_live_view/live_uploader.js", "../../assets/js/phoenix_live_view/hooks.js", "../../assets/js/phoenix_live_view/dom_post_morph_restorer.js", "../../assets/node_modules/morphdom/dist/morphdom-esm.js", "../../assets/js/phoenix_live_view/dom_patch.js", "../../assets/js/phoenix_live_view/rendered.js", "../../assets/js/phoenix_live_view/view_hook.js", "../../assets/js/phoenix_live_view/view.js", "../../assets/js/phoenix_live_view/live_socket.js"],
-  "sourcesContent": ["/*\n================================================================================\nPhoenix LiveView JavaScript Client\n================================================================================\n\nSee the hexdocs at `https://hexdocs.pm/phoenix_live_view` for documentation.\n\n*/\n\nimport LiveSocket from \"./live_socket\"\nexport {\n  LiveSocket\n}\n", "\nexport const CONSECUTIVE_RELOADS = \"consecutive-reloads\"\nexport const MAX_RELOADS = 10\nexport const RELOAD_JITTER = [1000, 3000]\nexport const FAILSAFE_JITTER = 30000\nexport const PHX_EVENT_CLASSES = [\n  \"phx-click-loading\", \"phx-change-loading\", \"phx-submit-loading\",\n  \"phx-keydown-loading\", \"phx-keyup-loading\", \"phx-blur-loading\", \"phx-focus-loading\"\n]\nexport const PHX_COMPONENT = \"data-phx-component\"\nexport const PHX_LIVE_LINK = \"data-phx-link\"\nexport const PHX_TRACK_STATIC = \"track-static\"\nexport const PHX_LINK_STATE = \"data-phx-link-state\"\nexport const PHX_REF = \"data-phx-ref\"\nexport const PHX_TRACK_UPLOADS = \"track-uploads\"\nexport const PHX_UPLOAD_REF = \"data-phx-upload-ref\"\nexport const PHX_PREFLIGHTED_REFS = \"data-phx-preflighted-refs\"\nexport const PHX_DONE_REFS = \"data-phx-done-refs\"\nexport const PHX_DROP_TARGET = \"drop-target\"\nexport const PHX_ACTIVE_ENTRY_REFS = \"data-phx-active-refs\"\nexport const PHX_LIVE_FILE_UPDATED = \"phx:live-file:updated\"\nexport const PHX_SKIP = \"data-phx-skip\"\nexport const PHX_REMOVE = \"data-phx-remove\"\nexport const PHX_PAGE_LOADING = \"page-loading\"\nexport const PHX_CONNECTED_CLASS = \"phx-connected\"\nexport const PHX_DISCONNECTED_CLASS = \"phx-disconnected\"\nexport const PHX_NO_FEEDBACK_CLASS = \"phx-no-feedback\"\nexport const PHX_ERROR_CLASS = \"phx-error\"\nexport const PHX_PARENT_ID = \"data-phx-parent-id\"\nexport const PHX_MAIN = \"data-phx-main\"\nexport const PHX_ROOT_ID = \"data-phx-root-id\"\nexport const PHX_TRIGGER_ACTION = \"trigger-action\"\nexport const PHX_FEEDBACK_FOR = \"feedback-for\"\nexport const PHX_HAS_FOCUSED = \"phx-has-focused\"\nexport const FOCUSABLE_INPUTS = [\"text\", \"textarea\", \"number\", \"email\", \"password\", \"search\", \"tel\", \"url\", \"date\", \"time\"]\nexport const CHECKABLE_INPUTS = [\"checkbox\", \"radio\"]\nexport const PHX_HAS_SUBMITTED = \"phx-has-submitted\"\nexport const PHX_SESSION = \"data-phx-session\"\nexport const PHX_VIEW_SELECTOR = `[${PHX_SESSION}]`\nexport const PHX_STATIC = \"data-phx-static\"\nexport const PHX_READONLY = \"data-phx-readonly\"\nexport const PHX_DISABLED = \"data-phx-disabled\"\nexport const PHX_DISABLE_WITH = \"disable-with\"\nexport const PHX_DISABLE_WITH_RESTORE = \"data-phx-disable-with-restore\"\nexport const PHX_HOOK = \"hook\"\nexport const PHX_DEBOUNCE = \"debounce\"\nexport const PHX_THROTTLE = \"throttle\"\nexport const PHX_UPDATE = \"update\"\nexport const PHX_KEY = \"key\"\nexport const PHX_PRIVATE = \"phxPrivate\"\nexport const PHX_AUTO_RECOVER = \"auto-recover\"\nexport const PHX_LV_DEBUG = \"phx:live-socket:debug\"\nexport const PHX_LV_PROFILE = \"phx:live-socket:profiling\"\nexport const PHX_LV_LATENCY_SIM = \"phx:live-socket:latency-sim\"\nexport const PHX_PROGRESS = \"progress\"\nexport const LOADER_TIMEOUT = 1\nexport const BEFORE_UNLOAD_LOADER_TIMEOUT = 200\nexport const BINDING_PREFIX = \"phx-\"\nexport const PUSH_TIMEOUT = 30000\nexport const LINK_HEADER = \"x-requested-with\"\nexport const RESPONSE_URL_HEADER = \"x-response-url\"\nexport const DEBOUNCE_TRIGGER = \"debounce-trigger\"\nexport const THROTTLED = \"throttled\"\nexport const DEBOUNCE_PREV_KEY = \"debounce-prev-key\"\nexport const DEFAULTS = {\n  debounce: 300,\n  throttle: 300\n}\n\n// Rendered\nexport const DYNAMICS = \"d\"\nexport const STATIC = \"s\"\nexport const COMPONENTS = \"c\"\nexport const EVENTS = \"e\"\nexport const REPLY = \"r\"\nexport const TITLE = \"t\"\n", "import {\n  logError\n} from \"./utils\"\n\nexport default class EntryUploader {\n  constructor(entry, chunkSize, liveSocket){\n    this.liveSocket = liveSocket\n    this.entry = entry\n    this.offset = 0\n    this.chunkSize = chunkSize\n    this.chunkTimer = null\n    this.uploadChannel = liveSocket.channel(`lvu:${entry.ref}`, {token: entry.metadata()})\n  }\n\n  error(reason){\n    clearTimeout(this.chunkTimer)\n    this.uploadChannel.leave()\n    this.entry.error(reason)\n  }\n\n  upload(){\n    this.uploadChannel.onError(reason => this.error(reason))\n    this.uploadChannel.join()\n      .receive(\"ok\", _data => this.readNextChunk())\n      .receive(\"error\", reason => this.error(reason))\n  }\n\n  isDone(){ return this.offset >= this.entry.file.size }\n\n  readNextChunk(){\n    let reader = new window.FileReader()\n    let blob = this.entry.file.slice(this.offset, this.chunkSize + this.offset)\n    reader.onload = (e) => {\n      if(e.target.error === null){\n        this.offset += e.target.result.byteLength\n        this.pushChunk(e.target.result)\n      } else {\n        return logError(\"Read error: \" + e.target.error)\n      }\n    }\n    reader.readAsArrayBuffer(blob)\n  }\n\n  pushChunk(chunk){\n    if(!this.uploadChannel.isJoined()){ return }\n    this.uploadChannel.push(\"chunk\", chunk)\n      .receive(\"ok\", () => {\n        this.entry.progress((this.offset / this.entry.file.size) * 100)\n        if(!this.isDone()){\n          this.chunkTimer = setTimeout(() => this.readNextChunk(), this.liveSocket.getLatencySim() || 0)\n        }\n      })\n  }\n}\n", "import {\n  PHX_VIEW_SELECTOR\n} from \"./constants\"\n\nimport EntryUploader from \"./entry_uploader\"\n\nexport let logError = (msg, obj) => console.error && console.error(msg, obj)\n\nexport let isCid = (cid) => typeof(cid) === \"number\"\n\nexport function detectDuplicateIds(){\n  let ids = new Set()\n  let elems = document.querySelectorAll(\"*[id]\")\n  for(let i = 0, len = elems.length; i < len; i++){\n    if(ids.has(elems[i].id)){\n      console.error(`Multiple IDs detected: ${elems[i].id}. Ensure unique element ids.`)\n    } else {\n      ids.add(elems[i].id)\n    }\n  }\n}\n\nexport let debug = (view, kind, msg, obj) => {\n  if(view.liveSocket.isDebugEnabled()){\n    console.log(`${view.id} ${kind}: ${msg} - `, obj)\n  }\n}\n\n// wraps value in closure or returns closure\nexport let closure = (val) => typeof val === \"function\" ? val : function (){ return val }\n\nexport let clone = (obj) => { return JSON.parse(JSON.stringify(obj)) }\n\nexport let closestPhxBinding = (el, binding, borderEl) => {\n  do {\n    if(el.matches(`[${binding}]`)){ return el }\n    el = el.parentElement || el.parentNode\n  } while(el !== null && el.nodeType === 1 && !((borderEl && borderEl.isSameNode(el)) || el.matches(PHX_VIEW_SELECTOR)))\n  return null\n}\n\nexport let isObject = (obj) => {\n  return obj !== null && typeof obj === \"object\" && !(obj instanceof Array)\n}\n\nexport let isEqualObj = (obj1, obj2) => JSON.stringify(obj1) === JSON.stringify(obj2)\n\nexport let isEmpty = (obj) => {\n  for(let x in obj){ return false }\n  return true\n}\n\nexport let maybe = (el, callback) => el && callback(el)\n\nexport let channelUploader = function (entries, onError, resp, liveSocket){\n  entries.forEach(entry => {\n    let entryUploader = new EntryUploader(entry, resp.config.chunk_size, liveSocket)\n    entryUploader.upload()\n  })\n}\n", "let Browser = {\n  canPushState(){ return (typeof (history.pushState) !== \"undefined\") },\n\n  dropLocal(localStorage, namespace, subkey){\n    return localStorage.removeItem(this.localKey(namespace, subkey))\n  },\n\n  updateLocal(localStorage, namespace, subkey, initial, func){\n    let current = this.getLocal(localStorage, namespace, subkey)\n    let key = this.localKey(namespace, subkey)\n    let newVal = current === null ? initial : func(current)\n    localStorage.setItem(key, JSON.stringify(newVal))\n    return newVal\n  },\n\n  getLocal(localStorage, namespace, subkey){\n    return JSON.parse(localStorage.getItem(this.localKey(namespace, subkey)))\n  },\n\n  updateCurrentState(callback){\n    if(!this.canPushState()){ return }\n    history.replaceState(callback(history.state || {}), \"\", window.location.href)\n  },\n\n  pushState(kind, meta, to){\n    if(this.canPushState()){\n      if(to !== window.location.href){\n        if(meta.type == \"redirect\" && meta.scroll){\n          // If we're redirecting store the current scrollY for the current history state.\n          let currentState = history.state || {}\n          currentState.scroll = meta.scroll\n          history.replaceState(currentState, \"\", window.location.href)\n        }\n\n        delete meta.scroll // Only store the scroll in the redirect case.\n        history[kind + \"State\"](meta, \"\", to || null) // IE will coerce undefined to string\n        let hashEl = this.getHashTargetEl(window.location.hash)\n\n        if(hashEl){\n          hashEl.scrollIntoView()\n        } else if(meta.type === \"redirect\"){\n          window.scroll(0, 0)\n        }\n      }\n    } else {\n      this.redirect(to)\n    }\n  },\n\n  setCookie(name, value){\n    document.cookie = `${name}=${value}`\n  },\n\n  getCookie(name){\n    return document.cookie.replace(new RegExp(`(?:(?:^|.*;\\s*)${name}\\s*\\=\\s*([^;]*).*$)|^.*$`), \"$1\")\n  },\n\n  redirect(toURL, flash){\n    if(flash){ Browser.setCookie(\"__phoenix_flash__\", flash + \"; max-age=60000; path=/\") }\n    window.location = toURL\n  },\n\n  localKey(namespace, subkey){ return `${namespace}-${subkey}` },\n\n  getHashTargetEl(maybeHash){\n    let hash = maybeHash.toString().substring(1)\n    if(hash === \"\"){ return }\n    return document.getElementById(hash) || document.querySelector(`a[name=\"${hash}\"]`)\n  }\n}\n\nexport default Browser\n", "import {\n  CHECKABLE_INPUTS,\n  DEBOUNCE_PREV_KEY,\n  DEBOUNCE_TRIGGER,\n  FOCUSABLE_INPUTS,\n  PHX_COMPONENT,\n  PHX_EVENT_CLASSES,\n  PHX_HAS_FOCUSED,\n  PHX_HAS_SUBMITTED,\n  PHX_MAIN,\n  PHX_NO_FEEDBACK_CLASS,\n  PHX_PARENT_ID,\n  PHX_PRIVATE,\n  PHX_REF,\n  PHX_SESSION,\n  PHX_STATIC,\n  PHX_UPLOAD_REF,\n  PHX_VIEW_SELECTOR,\n  THROTTLED\n} from \"./constants\"\n\nimport {\n  clone,\n  logError\n} from \"./utils\"\n\nlet DOM = {\n  byId(id){ return document.getElementById(id) || logError(`no id found for ${id}`) },\n\n  removeClass(el, className){\n    el.classList.remove(className)\n    if(el.classList.length === 0){ el.removeAttribute(\"class\") }\n  },\n\n  all(node, query, callback){\n    if(!node){ return [] }\n    let array = Array.from(node.querySelectorAll(query))\n    return callback ? array.forEach(callback) : array\n  },\n\n  childNodeLength(html){\n    let template = document.createElement(\"template\")\n    template.innerHTML = html\n    return template.content.childElementCount\n  },\n\n  isUploadInput(el){ return el.type === \"file\" && el.getAttribute(PHX_UPLOAD_REF) !== null },\n\n  findUploadInputs(node){ return this.all(node, `input[type=\"file\"][${PHX_UPLOAD_REF}]`) },\n\n  findComponentNodeList(node, cid){\n    return this.filterWithinSameLiveView(this.all(node, `[${PHX_COMPONENT}=\"${cid}\"]`), node)\n  },\n\n  isPhxDestroyed(node){\n    return node.id && DOM.private(node, \"destroyed\") ? true : false\n  },\n\n  markPhxChildDestroyed(el){\n    el.setAttribute(PHX_SESSION, \"\")\n    this.putPrivate(el, \"destroyed\", true)\n  },\n\n  findPhxChildrenInFragment(html, parentId){\n    let template = document.createElement(\"template\")\n    template.innerHTML = html\n    return this.findPhxChildren(template.content, parentId)\n  },\n\n  isIgnored(el, phxUpdate){\n    return (el.getAttribute(phxUpdate) || el.getAttribute(\"data-phx-update\")) === \"ignore\"\n  },\n\n  isPhxUpdate(el, phxUpdate, updateTypes){\n    return el.getAttribute && updateTypes.indexOf(el.getAttribute(phxUpdate)) >= 0\n  },\n\n  findPhxChildren(el, parentId){\n    return this.all(el, `${PHX_VIEW_SELECTOR}[${PHX_PARENT_ID}=\"${parentId}\"]`)\n  },\n\n  findParentCIDs(node, cids){\n    let initial = new Set(cids)\n    return cids.reduce((acc, cid) => {\n      let selector = `[${PHX_COMPONENT}=\"${cid}\"] [${PHX_COMPONENT}]`\n\n      this.filterWithinSameLiveView(this.all(node, selector), node)\n        .map(el => parseInt(el.getAttribute(PHX_COMPONENT)))\n        .forEach(childCID => acc.delete(childCID))\n\n      return acc\n    }, initial)\n  },\n\n  filterWithinSameLiveView(nodes, parent){\n    if(parent.querySelector(PHX_VIEW_SELECTOR)){\n      return nodes.filter(el => this.withinSameLiveView(el, parent))\n    } else {\n      return nodes\n    }\n  },\n\n  withinSameLiveView(node, parent){\n    while(node = node.parentNode){\n      if(node.isSameNode(parent)){ return true }\n      if(node.getAttribute(PHX_SESSION) !== null){ return false }\n    }\n  },\n\n  private(el, key){ return el[PHX_PRIVATE] && el[PHX_PRIVATE][key] },\n\n  deletePrivate(el, key){ el[PHX_PRIVATE] && delete (el[PHX_PRIVATE][key]) },\n\n  putPrivate(el, key, value){\n    if(!el[PHX_PRIVATE]){ el[PHX_PRIVATE] = {} }\n    el[PHX_PRIVATE][key] = value\n  },\n\n  copyPrivates(target, source){\n    if(source[PHX_PRIVATE]){\n      target[PHX_PRIVATE] = clone(source[PHX_PRIVATE])\n    }\n  },\n\n  putTitle(str){\n    let titleEl = document.querySelector(\"title\")\n    let {prefix, suffix} = titleEl.dataset\n    document.title = `${prefix || \"\"}${str}${suffix || \"\"}`\n  },\n\n  debounce(el, event, phxDebounce, defaultDebounce, phxThrottle, defaultThrottle, callback){\n    let debounce = el.getAttribute(phxDebounce)\n    let throttle = el.getAttribute(phxThrottle)\n    if(debounce === \"\"){ debounce = defaultDebounce }\n    if(throttle === \"\"){ throttle = defaultThrottle }\n    let value = debounce || throttle\n    switch(value){\n      case null: return callback()\n\n      case \"blur\":\n        if(this.once(el, \"debounce-blur\")){\n          el.addEventListener(\"blur\", () => callback())\n        }\n        return\n\n      default:\n        let timeout = parseInt(value)\n        let trigger = () => throttle ? this.deletePrivate(el, THROTTLED) : callback()\n        let currentCycle = this.incCycle(el, DEBOUNCE_TRIGGER, trigger)\n        if(isNaN(timeout)){ return logError(`invalid throttle/debounce value: ${value}`) }\n        if(throttle){\n          let newKeyDown = false\n          if(event.type === \"keydown\"){\n            let prevKey = this.private(el, DEBOUNCE_PREV_KEY)\n            this.putPrivate(el, DEBOUNCE_PREV_KEY, event.key)\n            newKeyDown = prevKey !== event.key\n          }\n\n          if(!newKeyDown && this.private(el, THROTTLED)){\n            return false\n          } else {\n            callback()\n            this.putPrivate(el, THROTTLED, true)\n            setTimeout(() => this.triggerCycle(el, DEBOUNCE_TRIGGER), timeout)\n          }\n        } else {\n          setTimeout(() => this.triggerCycle(el, DEBOUNCE_TRIGGER, currentCycle), timeout)\n        }\n\n\n        let form = el.form\n        if(form && this.once(form, \"bind-debounce\")){\n          form.addEventListener(\"submit\", () => {\n            Array.from((new FormData(form)).entries(), ([name]) => {\n              let input = form.querySelector(`[name=\"${name}\"]`)\n              this.incCycle(input, DEBOUNCE_TRIGGER)\n              this.deletePrivate(input, THROTTLED)\n            })\n          })\n        }\n        if(this.once(el, \"bind-debounce\")){\n          el.addEventListener(\"blur\", () => this.triggerCycle(el, DEBOUNCE_TRIGGER))\n        }\n    }\n  },\n\n  triggerCycle(el, key, currentCycle){\n    let [cycle, trigger] = this.private(el, key)\n    if(!currentCycle){ currentCycle = cycle }\n    if(currentCycle === cycle){\n      this.incCycle(el, key)\n      trigger()\n    }\n  },\n\n  once(el, key){\n    if(this.private(el, key) === true){ return false }\n    this.putPrivate(el, key, true)\n    return true\n  },\n\n  incCycle(el, key, trigger = function (){ }){\n    let [currentCycle] = this.private(el, key) || [0, trigger]\n    currentCycle++\n    this.putPrivate(el, key, [currentCycle, trigger])\n    return currentCycle\n  },\n\n  discardError(container, el, phxFeedbackFor){\n    let field = el.getAttribute && el.getAttribute(phxFeedbackFor)\n    // TODO: Remove id lookup after we update Phoenix to use input_name instead of input_id\n    let input = field && container.querySelector(`[id=\"${field}\"], [name=\"${field}\"]`)\n    if(!input){ return }\n\n    if(!(this.private(input, PHX_HAS_FOCUSED) || this.private(input.form, PHX_HAS_SUBMITTED))){\n      el.classList.add(PHX_NO_FEEDBACK_CLASS)\n    }\n  },\n\n  showError(inputEl, phxFeedbackFor){\n    if(inputEl.id || inputEl.name){\n      this.all(inputEl.form, `[${phxFeedbackFor}=\"${inputEl.id}\"], [${phxFeedbackFor}=\"${inputEl.name}\"]`, (el) => {\n        this.removeClass(el, PHX_NO_FEEDBACK_CLASS)\n      })\n    }\n  },\n\n  isPhxChild(node){\n    return node.getAttribute && node.getAttribute(PHX_PARENT_ID)\n  },\n\n  dispatchEvent(target, eventString, detail = {}){\n    let event = new CustomEvent(eventString, {bubbles: true, cancelable: true, detail: detail})\n    target.dispatchEvent(event)\n  },\n\n  cloneNode(node, html){\n    if(typeof (html) === \"undefined\"){\n      return node.cloneNode(true)\n    } else {\n      let cloned = node.cloneNode(false)\n      cloned.innerHTML = html\n      return cloned\n    }\n  },\n\n  mergeAttrs(target, source, opts = {}){\n    let exclude = opts.exclude || []\n    let isIgnored = opts.isIgnored\n    let sourceAttrs = source.attributes\n    for(let i = sourceAttrs.length - 1; i >= 0; i--){\n      let name = sourceAttrs[i].name\n      if(exclude.indexOf(name) < 0){ target.setAttribute(name, source.getAttribute(name)) }\n    }\n\n    let targetAttrs = target.attributes\n    for(let i = targetAttrs.length - 1; i >= 0; i--){\n      let name = targetAttrs[i].name\n      if(isIgnored){\n        if(name.startsWith(\"data-\") && !source.hasAttribute(name)){ target.removeAttribute(name) }\n      } else {\n        if(!source.hasAttribute(name)){ target.removeAttribute(name) }\n      }\n    }\n  },\n\n  mergeFocusedInput(target, source){\n    // skip selects because FF will reset highlighted index for any setAttribute\n    if(!(target instanceof HTMLSelectElement)){ DOM.mergeAttrs(target, source, {except: [\"value\"]}) }\n    if(source.readOnly){\n      target.setAttribute(\"readonly\", true)\n    } else {\n      target.removeAttribute(\"readonly\")\n    }\n  },\n\n  hasSelectionRange(el){\n    return el.setSelectionRange && (el.type === \"text\" || el.type === \"textarea\")\n  },\n\n  restoreFocus(focused, selectionStart, selectionEnd){\n    if(!DOM.isTextualInput(focused)){ return }\n    let wasFocused = focused.matches(\":focus\")\n    if(focused.readOnly){ focused.blur() }\n    if(!wasFocused){ focused.focus() }\n    if(this.hasSelectionRange(focused)){\n      focused.setSelectionRange(selectionStart, selectionEnd)\n    }\n  },\n\n  isFormInput(el){ return /^(?:input|select|textarea)$/i.test(el.tagName) && el.type !== \"button\" },\n\n  syncAttrsToProps(el){\n    if(el instanceof HTMLInputElement && CHECKABLE_INPUTS.indexOf(el.type.toLocaleLowerCase()) >= 0){\n      el.checked = el.getAttribute(\"checked\") !== null\n    }\n  },\n\n  syncPropsToAttrs(el){\n    if(el instanceof HTMLSelectElement){\n      let selectedItem = el.options.item(el.selectedIndex)\n      if(selectedItem && selectedItem.getAttribute(\"selected\") === null){\n        selectedItem.setAttribute(\"selected\", \"\")\n      }\n    }\n  },\n\n  isTextualInput(el){ return FOCUSABLE_INPUTS.indexOf(el.type) >= 0 },\n\n  isNowTriggerFormExternal(el, phxTriggerExternal){\n    return el.getAttribute && el.getAttribute(phxTriggerExternal) !== null\n  },\n\n  syncPendingRef(fromEl, toEl, disableWith){\n    let ref = fromEl.getAttribute(PHX_REF)\n    if(ref === null){ return true }\n\n    if(DOM.isFormInput(fromEl) || fromEl.getAttribute(disableWith) !== null){\n      if(DOM.isUploadInput(fromEl)){ DOM.mergeAttrs(fromEl, toEl, {isIgnored: true}) }\n      DOM.putPrivate(fromEl, PHX_REF, toEl)\n      return false\n    } else {\n      PHX_EVENT_CLASSES.forEach(className => {\n        fromEl.classList.contains(className) && toEl.classList.add(className)\n      })\n      toEl.setAttribute(PHX_REF, ref)\n      return true\n    }\n  },\n\n  cleanChildNodes(container, phxUpdate){\n    if(DOM.isPhxUpdate(container, phxUpdate, [\"append\", \"prepend\"])){\n      let toRemove = []\n      container.childNodes.forEach(childNode => {\n        if(!childNode.id){\n          // Skip warning if it's an empty text node (e.g. a new-line)\n          let isEmptyTextNode = childNode.nodeType === Node.TEXT_NODE && childNode.nodeValue.trim() === \"\"\n          if(!isEmptyTextNode){\n            logError(\"only HTML element tags with an id are allowed inside containers with phx-update.\\n\\n\" +\n              `removing illegal node: \"${(childNode.outerHTML || childNode.nodeValue).trim()}\"\\n\\n`)\n          }\n          toRemove.push(childNode)\n        }\n      })\n      toRemove.forEach(childNode => childNode.remove())\n    }\n  },\n\n  replaceRootContainer(container, tagName, attrs){\n    let retainedAttrs = new Set([\"id\", PHX_SESSION, PHX_STATIC, PHX_MAIN])\n    if(container.tagName.toLowerCase() === tagName.toLowerCase()){\n      Array.from(container.attributes)\n        .filter(attr => !retainedAttrs.has(attr.name.toLowerCase()))\n        .forEach(attr => container.removeAttribute(attr.name))\n\n      Object.keys(attrs)\n        .filter(name => !retainedAttrs.has(name.toLowerCase()))\n        .forEach(attr => container.setAttribute(attr, attrs[attr]))\n\n      return container\n\n    } else {\n      let newContainer = document.createElement(tagName)\n      Object.keys(attrs).forEach(attr => newContainer.setAttribute(attr, attrs[attr]))\n      retainedAttrs.forEach(attr => newContainer.setAttribute(attr, container.getAttribute(attr)))\n      newContainer.innerHTML = container.innerHTML\n      container.replaceWith(newContainer)\n      return newContainer\n    }\n  }\n}\n\nexport default DOM\n", "import {\n  PHX_ACTIVE_ENTRY_REFS,\n  PHX_LIVE_FILE_UPDATED,\n  PHX_PREFLIGHTED_REFS\n} from \"./constants\"\n\nimport {\n  channelUploader,\n  logError\n} from \"./utils\"\n\nimport LiveUploader from \"./live_uploader\"\n\nexport default class UploadEntry {\n  static isActive(fileEl, file){\n    let isNew = file._phxRef === undefined\n    let activeRefs = fileEl.getAttribute(PHX_ACTIVE_ENTRY_REFS).split(\",\")\n    let isActive = activeRefs.indexOf(LiveUploader.genFileRef(file)) >= 0\n    return file.size > 0 && (isNew || isActive)\n  }\n\n  static isPreflighted(fileEl, file){\n    let preflightedRefs = fileEl.getAttribute(PHX_PREFLIGHTED_REFS).split(\",\")\n    let isPreflighted = preflightedRefs.indexOf(LiveUploader.genFileRef(file)) >= 0\n    return isPreflighted && this.isActive(fileEl, file)\n  }\n\n  constructor(fileEl, file, view){\n    this.ref = LiveUploader.genFileRef(file)\n    this.fileEl = fileEl\n    this.file = file\n    this.view = view\n    this.meta = null\n    this._isCancelled = false\n    this._isDone = false\n    this._progress = 0\n    this._lastProgressSent = -1\n    this._onDone = function (){ }\n    this._onElUpdated = this.onElUpdated.bind(this)\n    this.fileEl.addEventListener(PHX_LIVE_FILE_UPDATED, this._onElUpdated)\n  }\n\n  metadata(){ return this.meta }\n\n  progress(progress){\n    this._progress = Math.floor(progress)\n    if(this._progress > this._lastProgressSent){\n      if(this._progress >= 100){\n        this._progress = 100\n        this._lastProgressSent = 100\n        this._isDone = true\n        this.view.pushFileProgress(this.fileEl, this.ref, 100, () => {\n          LiveUploader.untrackFile(this.fileEl, this.file)\n          this._onDone()\n        })\n      } else {\n        this._lastProgressSent = this._progress\n        this.view.pushFileProgress(this.fileEl, this.ref, this._progress)\n      }\n    }\n  }\n\n  cancel(){\n    this._isCancelled = true\n    this._isDone = true\n    this._onDone()\n  }\n\n  isDone(){ return this._isDone }\n\n  error(reason = \"failed\"){\n    this.view.pushFileProgress(this.fileEl, this.ref, {error: reason})\n    LiveUploader.clearFiles(this.fileEl)\n  }\n\n  //private\n\n  onDone(callback){\n    this._onDone = () => {\n      this.fileEl.removeEventListener(PHX_LIVE_FILE_UPDATED, this._onElUpdated)\n      callback()\n    }\n  }\n\n  onElUpdated(){\n    let activeRefs = this.fileEl.getAttribute(PHX_ACTIVE_ENTRY_REFS).split(\",\")\n    if(activeRefs.indexOf(this.ref) === -1){ this.cancel() }\n  }\n\n  toPreflightPayload(){\n    return {\n      last_modified: this.file.lastModified,\n      name: this.file.name,\n      size: this.file.size,\n      type: this.file.type,\n      ref: this.ref\n    }\n  }\n\n  uploader(uploaders){\n    if(this.meta.uploader){\n      let callback = uploaders[this.meta.uploader] || logError(`no uploader configured for ${this.meta.uploader}`)\n      return {name: this.meta.uploader, callback: callback}\n    } else {\n      return {name: \"channel\", callback: channelUploader}\n    }\n  }\n\n  zipPostFlight(resp){\n    this.meta = resp.entries[this.ref]\n    if(!this.meta){ logError(`no preflight upload response returned with ref ${this.ref}`, {input: this.fileEl, response: resp}) }\n  }\n}\n", "import {\n  PHX_DONE_REFS,\n  PHX_PREFLIGHTED_REFS,\n  PHX_UPLOAD_REF\n} from \"./constants\"\n\nimport {\n} from \"./utils\"\n\nimport DOM from \"./dom\"\nimport UploadEntry from \"./upload_entry\"\n\nlet liveUploaderFileRef = 0\n\nexport default class LiveUploader {\n  static genFileRef(file){\n    let ref = file._phxRef\n    if(ref !== undefined){\n      return ref\n    } else {\n      file._phxRef = (liveUploaderFileRef++).toString()\n      return file._phxRef\n    }\n  }\n\n  static getEntryDataURL(inputEl, ref, callback){\n    let file = this.activeFiles(inputEl).find(file => this.genFileRef(file) === ref)\n    callback(URL.createObjectURL(file))\n  }\n\n  static hasUploadsInProgress(formEl){\n    let active = 0\n    DOM.findUploadInputs(formEl).forEach(input => {\n      if(input.getAttribute(PHX_PREFLIGHTED_REFS) !== input.getAttribute(PHX_DONE_REFS)){\n        active++\n      }\n    })\n    return active > 0\n  }\n\n  static serializeUploads(inputEl){\n    let files = this.activeFiles(inputEl)\n    let fileData = {}\n    files.forEach(file => {\n      let entry = {path: inputEl.name}\n      let uploadRef = inputEl.getAttribute(PHX_UPLOAD_REF)\n      fileData[uploadRef] = fileData[uploadRef] || []\n      entry.ref = this.genFileRef(file)\n      entry.name = file.name || entry.ref\n      entry.type = file.type\n      entry.size = file.size\n      fileData[uploadRef].push(entry)\n    })\n    return fileData\n  }\n\n  static clearFiles(inputEl){\n    inputEl.value = null\n    inputEl.removeAttribute(PHX_UPLOAD_REF)\n    DOM.putPrivate(inputEl, \"files\", [])\n  }\n\n  static untrackFile(inputEl, file){\n    DOM.putPrivate(inputEl, \"files\", DOM.private(inputEl, \"files\").filter(f => !Object.is(f, file)))\n  }\n\n  static trackFiles(inputEl, files){\n    if(inputEl.getAttribute(\"multiple\") !== null){\n      let newFiles = files.filter(file => !this.activeFiles(inputEl).find(f => Object.is(f, file)))\n      DOM.putPrivate(inputEl, \"files\", this.activeFiles(inputEl).concat(newFiles))\n      inputEl.value = null\n    } else {\n      DOM.putPrivate(inputEl, \"files\", files)\n    }\n  }\n\n  static activeFileInputs(formEl){\n    let fileInputs = DOM.findUploadInputs(formEl)\n    return Array.from(fileInputs).filter(el => el.files && this.activeFiles(el).length > 0)\n  }\n\n  static activeFiles(input){\n    return (DOM.private(input, \"files\") || []).filter(f => UploadEntry.isActive(input, f))\n  }\n\n  static inputsAwaitingPreflight(formEl){\n    let fileInputs = DOM.findUploadInputs(formEl)\n    return Array.from(fileInputs).filter(input => this.filesAwaitingPreflight(input).length > 0)\n  }\n\n  static filesAwaitingPreflight(input){\n    return this.activeFiles(input).filter(f => !UploadEntry.isPreflighted(input, f))\n  }\n\n  constructor(inputEl, view, onComplete){\n    this.view = view\n    this.onComplete = onComplete\n    this._entries =\n      Array.from(LiveUploader.filesAwaitingPreflight(inputEl) || [])\n        .map(file => new UploadEntry(inputEl, file, view))\n\n    this.numEntriesInProgress = this._entries.length\n  }\n\n  entries(){ return this._entries }\n\n  initAdapterUpload(resp, onError, liveSocket){\n    this._entries =\n      this._entries.map(entry => {\n        entry.zipPostFlight(resp)\n        entry.onDone(() => {\n          this.numEntriesInProgress--\n          if(this.numEntriesInProgress === 0){ this.onComplete() }\n        })\n        return entry\n      })\n\n    let groupedEntries = this._entries.reduce((acc, entry) => {\n      let {name, callback} = entry.uploader(liveSocket.uploaders)\n      acc[name] = acc[name] || {callback: callback, entries: []}\n      acc[name].entries.push(entry)\n      return acc\n    }, {})\n\n    for(let name in groupedEntries){\n      let {callback, entries} = groupedEntries[name]\n      callback(entries, onError, resp, liveSocket)\n    }\n  }\n}\n", "import {\n  PHX_ACTIVE_ENTRY_REFS,\n  PHX_LIVE_FILE_UPDATED,\n  PHX_PREFLIGHTED_REFS,\n  PHX_UPLOAD_REF\n} from \"./constants\"\n\nimport LiveUploader from \"./live_uploader\"\n\nlet Hooks = {\n  LiveFileUpload: {\n    activeRefs(){ return this.el.getAttribute(PHX_ACTIVE_ENTRY_REFS) },\n\n    preflightedRefs(){ return this.el.getAttribute(PHX_PREFLIGHTED_REFS) },\n\n    mounted(){ this.preflightedWas = this.preflightedRefs() },\n\n    updated(){\n      let newPreflights = this.preflightedRefs()\n      if(this.preflightedWas !== newPreflights){\n        this.preflightedWas = newPreflights\n        if(newPreflights === \"\"){\n          this.__view.cancelSubmit(this.el.form)\n        }\n      }\n\n      if(this.activeRefs() === \"\"){ this.el.value = null }\n      this.el.dispatchEvent(new CustomEvent(PHX_LIVE_FILE_UPDATED))\n    }\n  },\n\n  LiveImgPreview: {\n    mounted(){\n      this.ref = this.el.getAttribute(\"data-phx-entry-ref\")\n      this.inputEl = document.getElementById(this.el.getAttribute(PHX_UPLOAD_REF))\n      LiveUploader.getEntryDataURL(this.inputEl, this.ref, url => {\n        this.url = url\n        this.el.src = url\n      })\n    },\n    destroyed(){\n      URL.revokeObjectURL(this.url)\n    }\n  }\n}\n\nexport default Hooks\n", "import {\n  maybe\n} from \"./utils\"\n\nimport DOM from \"./dom\"\n\nexport default class DOMPostMorphRestorer {\n  constructor(containerBefore, containerAfter, updateType){\n    let idsBefore = new Set()\n    let idsAfter = new Set([...containerAfter.children].map(child => child.id))\n\n    let elementsToModify = []\n\n    Array.from(containerBefore.children).forEach(child => {\n      if(child.id){ // all of our children should be elements with ids\n        idsBefore.add(child.id)\n        if(idsAfter.has(child.id)){\n          let previousElementId = child.previousElementSibling && child.previousElementSibling.id\n          elementsToModify.push({elementId: child.id, previousElementId: previousElementId})\n        }\n      }\n    })\n\n    this.containerId = containerAfter.id\n    this.updateType = updateType\n    this.elementsToModify = elementsToModify\n    this.elementIdsToAdd = [...idsAfter].filter(id => !idsBefore.has(id))\n  }\n\n  // We do the following to optimize append/prepend operations:\n  //   1) Track ids of modified elements & of new elements\n  //   2) All the modified elements are put back in the correct position in the DOM tree\n  //      by storing the id of their previous sibling\n  //   3) New elements are going to be put in the right place by morphdom during append.\n  //      For prepend, we move them to the first position in the container\n  perform(){\n    let container = DOM.byId(this.containerId)\n    this.elementsToModify.forEach(elementToModify => {\n      if(elementToModify.previousElementId){\n        maybe(document.getElementById(elementToModify.previousElementId), previousElem => {\n          maybe(document.getElementById(elementToModify.elementId), elem => {\n            let isInRightPlace = elem.previousElementSibling && elem.previousElementSibling.id == previousElem.id\n            if(!isInRightPlace){\n              previousElem.insertAdjacentElement(\"afterend\", elem)\n            }\n          })\n        })\n      } else {\n        // This is the first element in the container\n        maybe(document.getElementById(elementToModify.elementId), elem => {\n          let isInRightPlace = elem.previousElementSibling == null\n          if(!isInRightPlace){\n            container.insertAdjacentElement(\"afterbegin\", elem)\n          }\n        })\n      }\n    })\n\n    if(this.updateType == \"prepend\"){\n      this.elementIdsToAdd.reverse().forEach(elemId => {\n        maybe(document.getElementById(elemId), elem => container.insertAdjacentElement(\"afterbegin\", elem))\n      })\n    }\n  }\n}\n", "var DOCUMENT_FRAGMENT_NODE = 11;\n\nfunction morphAttrs(fromNode, toNode) {\n    var toNodeAttrs = toNode.attributes;\n    var attr;\n    var attrName;\n    var attrNamespaceURI;\n    var attrValue;\n    var fromValue;\n\n    // document-fragments dont have attributes so lets not do anything\n    if (toNode.nodeType === DOCUMENT_FRAGMENT_NODE || fromNode.nodeType === DOCUMENT_FRAGMENT_NODE) {\n      return;\n    }\n\n    // update attributes on original DOM element\n    for (var i = toNodeAttrs.length - 1; i >= 0; i--) {\n        attr = toNodeAttrs[i];\n        attrName = attr.name;\n        attrNamespaceURI = attr.namespaceURI;\n        attrValue = attr.value;\n\n        if (attrNamespaceURI) {\n            attrName = attr.localName || attrName;\n            fromValue = fromNode.getAttributeNS(attrNamespaceURI, attrName);\n\n            if (fromValue !== attrValue) {\n                if (attr.prefix === 'xmlns'){\n                    attrName = attr.name; // It's not allowed to set an attribute with the XMLNS namespace without specifying the `xmlns` prefix\n                }\n                fromNode.setAttributeNS(attrNamespaceURI, attrName, attrValue);\n            }\n        } else {\n            fromValue = fromNode.getAttribute(attrName);\n\n            if (fromValue !== attrValue) {\n                fromNode.setAttribute(attrName, attrValue);\n            }\n        }\n    }\n\n    // Remove any extra attributes found on the original DOM element that\n    // weren't found on the target element.\n    var fromNodeAttrs = fromNode.attributes;\n\n    for (var d = fromNodeAttrs.length - 1; d >= 0; d--) {\n        attr = fromNodeAttrs[d];\n        attrName = attr.name;\n        attrNamespaceURI = attr.namespaceURI;\n\n        if (attrNamespaceURI) {\n            attrName = attr.localName || attrName;\n\n            if (!toNode.hasAttributeNS(attrNamespaceURI, attrName)) {\n                fromNode.removeAttributeNS(attrNamespaceURI, attrName);\n            }\n        } else {\n            if (!toNode.hasAttribute(attrName)) {\n                fromNode.removeAttribute(attrName);\n            }\n        }\n    }\n}\n\nvar range; // Create a range object for efficently rendering strings to elements.\nvar NS_XHTML = 'http://www.w3.org/1999/xhtml';\n\nvar doc = typeof document === 'undefined' ? undefined : document;\nvar HAS_TEMPLATE_SUPPORT = !!doc && 'content' in doc.createElement('template');\nvar HAS_RANGE_SUPPORT = !!doc && doc.createRange && 'createContextualFragment' in doc.createRange();\n\nfunction createFragmentFromTemplate(str) {\n    var template = doc.createElement('template');\n    template.innerHTML = str;\n    return template.content.childNodes[0];\n}\n\nfunction createFragmentFromRange(str) {\n    if (!range) {\n        range = doc.createRange();\n        range.selectNode(doc.body);\n    }\n\n    var fragment = range.createContextualFragment(str);\n    return fragment.childNodes[0];\n}\n\nfunction createFragmentFromWrap(str) {\n    var fragment = doc.createElement('body');\n    fragment.innerHTML = str;\n    return fragment.childNodes[0];\n}\n\n/**\n * This is about the same\n * var html = new DOMParser().parseFromString(str, 'text/html');\n * return html.body.firstChild;\n *\n * @method toElement\n * @param {String} str\n */\nfunction toElement(str) {\n    str = str.trim();\n    if (HAS_TEMPLATE_SUPPORT) {\n      // avoid restrictions on content for things like `Hi` which\n      // createContextualFragment doesn't support\n      //