phoenix_live_view 1.2.0-rc.2 → 1.2.0

package/assets/js/phoenix_live_view/index.ts

@@ -1,312 +1,24 @@
 /*
-================================================================================
-Phoenix LiveView JavaScript Client
-================================================================================
-
-See the hexdocs at `https://hexdocs.pm/phoenix_live_view` for documentation.
-*/
+ * This is the documentation for the LiveView JavaScript client.
+ * It is a more low-level API documentation for advanced users.
+ * For a higher-level overview, [see the page on JavaScript interoperability](https://phoenix-live-view.hexdocs.pm/js-interop.html) instead.
+ *
+ * The main documentation can be found at `https://phoenix-live-view.hexdocs.pm`.
+ *
+ * @packageDocumentation
+ */
 
-import OriginalLiveSocket, { isUsedInput } from "./live_socket";
+import LiveSocket, { type LiveSocketOptions, isUsedInput } from "./live_socket";
 import DOM from "./dom";
 import { ViewHook } from "./view_hook";
 import View from "./view";
 import { logError } from "./utils";
 
-import type { EncodedJS, LiveSocketJSCommands } from "./js_commands";
-import type { Hook, HooksOptions } from "./view_hook";
-import type { Socket as PhoenixSocket } from "phoenix";
+import type { EncodedJS } from "./js_commands";
+import type { Hook, HooksOptions, HookInterface } from "./view_hook";
 import LiveUploader from "./live_uploader";
 
-/**
- * Options for configuring the LiveSocket instance.
- */
-export interface LiveSocketOptions {
-  /**
-   * Defaults for phx-debounce and phx-throttle.
-   */
-  defaults?: {
-    /** The millisecond phx-debounce time. Defaults 300 */
-    debounce?: number;
-    /** The millisecond phx-throttle time. Defaults 300 */
-    throttle?: number;
-  };
-  /**
-   * An object or function for passing connect params.
-   * The function receives the element associated with a given LiveView. For example:
-   *
-   *     (el) => {view: el.getAttribute("data-my-view-name", token: window.myToken}
-   *
-   */
-  params?:
-    | ((el: HTMLElement) => { [key: string]: any })
-    | { [key: string]: any };
-  /**
-   * The optional prefix to use for all phx DOM annotations.
-   *
-   * Defaults to "phx-".
-   */
-  bindingPrefix?: string;
-  /**
-   * Callbacks for LiveView hooks.
-   *
-   * See [Client hooks via `phx-hook`](https://hexdocs.pm/phoenix_live_view/js-interop.html#client-hooks-via-phx-hook) for more information.
-   */
-  hooks?: HooksOptions;
-  /** Callbacks for LiveView uploaders. */
-  uploaders?: { [key: string]: any }; // TODO: define more specifically
-  /** Delay in milliseconds before applying loading states. */
-  loaderTimeout?: number;
-  /** Delay in milliseconds before executing phx-disconnected commands. */
-  disconnectedTimeout?: number;
-  /** Maximum reloads before entering failsafe mode. */
-  maxReloads?: number;
-  /** Minimum time between normal reload attempts. */
-  reloadJitterMin?: number;
-  /** Maximum time between normal reload attempts. */
-  reloadJitterMax?: number;
-  /** Time between reload attempts in failsafe mode. */
-  failsafeJitter?: number;
-  /**
-   * Function to log debug information. For example:
-   *
-   *     (view, kind, msg, obj) => console.log(`${view.id} ${kind}: ${msg} - `, obj)
-   */
-  viewLogger?: (view: View, kind: string, msg: string, obj: any) => void;
-  /**
-   * Object mapping event names to functions for populating event metadata.
-   *
-   *     metadata: {
-   *       click: (e, el) => {
-   *         return {
-   *           ctrlKey: e.ctrlKey,
-   *           metaKey: e.metaKey,
-   *           detail: e.detail || 1,
-   *         }
-   *       },
-   *       keydown: (e, el) => {
-   *         return {
-   *           key: e.key,
-   *           ctrlKey: e.ctrlKey,
-   *           metaKey: e.metaKey,
-   *           shiftKey: e.shiftKey
-   *         }
-   *       }
-   *     }
-   *
-   */
-  metadata?: { [eventName: string]: (e: Event, el: HTMLElement) => object };
-  /**
-   * An optional Storage compatible object
-   * Useful when LiveView won't have access to `sessionStorage`. For example, This could
-   * happen if a site loads a cross-domain LiveView in an iframe.
-   *
-   * Example usage:
-   *
-   *     class InMemoryStorage {
-   *       constructor() { this.storage = {} }
-   *       getItem(keyName) { return this.storage[keyName] || null }
-   *       removeItem(keyName) { delete this.storage[keyName] }
-   *       setItem(keyName, keyValue) { this.storage[keyName] = keyValue }
-   *     }
-   */
-  sessionStorage?: Storage;
-  /**
-   * An optional Storage compatible object
-   * Useful when LiveView won't have access to `localStorage`.
-   *
-   * See `sessionStorage` for an example.
-   */
-  localStorage?: Storage;
-  /**
-   * If set to `true`, `phx-change` events will be blocked (will not fire)
-   * while the user is composing input using an IME (Input Method Editor).
-   * This is determined by the `e.isComposing` property on keyboard events,
-   * which is `true` when the user is in the process of entering composed characters (for example,
-   * when typing Japanese or Chinese using romaji or pinyin input methods).
-   * By default, `phx-change` will not be blocked during a composition session,
-   * but note that there were issues reported in older versions of Safari,
-   * where a LiveView patch to the input caused unexpected behavior.
-   *
-   * For more information, see
-   * - https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/isComposing
-   * - https://github.com/phoenixframework/phoenix_live_view/issues/3322
-   *
-   * Defaults to `false`.
-   */
-  blockPhxChangeWhileComposing?: boolean;
-  /** DOM callbacks. */
-  dom?: {
-    /**
-     * An optional function to modify the behavior of querying elements in JS commands.
-     * @param sourceEl - The source element, e.g. the button that was clicked.
-     * @param query - The query value.
-     * @param defaultQuery - A default query function that can be used if no custom query should be applied.
-     * @returns A list of DOM elements.
-     */
-    jsQuerySelectorAll?: (
-      sourceEl: HTMLElement,
-      query: string,
-      defaultQuery: () => Element[],
-    ) => Element[];
-    /**
-     * When defined, called with a start callback that needs to be called
-     * to perform the actual patch. Failing to call the start callback causes
-     * the page to become stuck.
-     *
-     * This can be used to delay patches in order to perform view transitions,
-     * for example:
-     *
-     * ```javascript
-     * let liveSocket = new LiveSocket("/live", Socket, {
-     *   dom: {
-     *     onDocumentPatch(start) {
-     *       document.startViewTransition(start);
-     *     }
-     *   }
-     * })
-     * ```
-     *
-     * It is strongly advised to call start as quickly as possible.
-     */
-    onDocumentPatch?: (start: () => void) => void;
-    /**
-     * Called immediately before a DOM patch is applied.
-     */
-    onPatchStart?: (container: HTMLElement) => void;
-    /**
-     * Called immediately after a DOM patch is applied.
-     */
-    onPatchEnd?: (container: HTMLElement) => void;
-    /**
-     * Called when a new DOM node is added.
-     */
-    onNodeAdded?: (node: Node) => void;
-    /**
-     * Called before an element is updated.
-     */
-    onBeforeElUpdated?: (fromEl: Element, toEl: Element) => void;
-  };
-  /** Allow passthrough of other options to the Phoenix Socket constructor. */
-  [key: string]: any;
-}
-
-/**
- * Interface describing the public API of a LiveSocket instance.
- */
-export interface LiveSocketInstanceInterface {
-  /**
-   * Returns the version of the LiveView client.
-   */
-  version(): string;
-  /**
-   * Returns true if profiling is enabled. See `enableProfiling` and `disableProfiling`.
-   */
-  isProfileEnabled(): boolean;
-  /**
-   * Returns true if debugging is enabled. See `enableDebug` and `disableDebug`.
-   */
-  isDebugEnabled(): boolean;
-  /**
-   * Returns true if debugging is disabled. See `enableDebug` and `disableDebug`.
-   */
-  isDebugDisabled(): boolean;
-  /**
-   * Enables debugging.
-   *
-   * When debugging is enabled, the LiveView client will log debug information to the console.
-   * See [Debugging client events](https://hexdocs.pm/phoenix_live_view/js-interop.html#debugging-client-events) for more information.
-   */
-  enableDebug(): void;
-  /**
-   * Enables profiling.
-   *
-   * When profiling is enabled, the LiveView client will log profiling information to the console.
-   */
-  enableProfiling(): void;
-  /**
-   * Disables debugging.
-   */
-  disableDebug(): void;
-  /**
-   * Disables profiling.
-   */
-  disableProfiling(): void;
-  /**
-   * Enables latency simulation.
-   *
-   * When latency simulation is enabled, the LiveView client will add a delay to requests and responses from the server.
-   * See [Simulating Latency](https://hexdocs.pm/phoenix_live_view/js-interop.html#simulating-latency) for more information.
-   */
-  enableLatencySim(upperBoundMs: number): void;
-  /**
-   * Disables latency simulation.
-   */
-  disableLatencySim(): void;
-  /**
-   * Returns the current latency simulation upper bound.
-   */
-  getLatencySim(): number | null;
-  /**
-   * Returns the Phoenix Socket instance.
-   */
-  getSocket(): PhoenixSocket;
-  /**
-   * Connects to the LiveView server.
-   */
-  connect(): void;
-  /**
-   * Disconnects from the LiveView server.
-   */
-  disconnect(callback?: () => void): void;
-  /**
-   * Can be used to replace the transport used by the underlying Phoenix Socket.
-   */
-  replaceTransport(transport: any): void;
-  /**
-   * Executes an encoded JS command, targeting the given element.
-   *
-   * See [`Phoenix.LiveView.JS`](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.JS.html) for more information.
-   */
-  execJS(
-    el: HTMLElement,
-    encodedJS: EncodedJS,
-    eventType?: string | null,
-  ): void;
-  /**
-   * Returns an object with methods to manipulate the DOM and execute JavaScript.
-   * The applied changes integrate with server DOM patching.
-   *
-   * See [JavaScript interoperability](https://hexdocs.pm/phoenix_live_view/js-interop.html) for more information.
-   */
-  js(): LiveSocketJSCommands;
-}
-
-/**
- * Interface describing the LiveSocket constructor.
- */
-export interface LiveSocketConstructor {
-  /**
-   * Creates a new LiveSocket instance.
-   *
-   * @param endpoint - The string WebSocket endpoint, ie, `"wss://example.com/live"`,
-   *                                               `"/live"` (inherited host & protocol)
-   * @param socket - the required Phoenix Socket class imported from "phoenix". For example:
-   *
-   *     import {Socket} from "phoenix"
-   *     import {LiveSocket} from "phoenix_live_view"
-   *     let liveSocket = new LiveSocket("/live", Socket, {...})
-   *
-   * @param opts - Optional configuration.
-   */
-  new (
-    endpoint: string,
-    socket: typeof PhoenixSocket,
-    opts?: LiveSocketOptions,
-  ): LiveSocketInstanceInterface;
-}
-
-// because LiveSocket is in JS (for now), we cast it to our defined TypeScript constructor.
-const LiveSocket = OriginalLiveSocket as unknown as LiveSocketConstructor;
+export type { LiveSocketOptions, HookInterface, HooksOptions, EncodedJS };
 
 /** Creates a hook instance for the given element and callbacks.
  *
@@ -332,6 +44,8 @@ const LiveSocket = OriginalLiveSocket as unknown as LiveSocketConstructor;
  * }
  *
  * @returns Returns the Hook instance for the custom element.
+ *
+ * @category JavaScript Hooks
  */
 function createHook(el: HTMLElement, callbacks: Hook): ViewHook {
   let existingHook = DOM.getCustomElHook(el);
@@ -377,6 +91,5 @@ export {
   createHook,
   ViewHook,
   Hook,
-  HooksOptions,
   getFileURLForUpload,
 };

package/assets/js/phoenix_live_view/js.js

@@ -114,7 +114,8 @@ const JS = {
       if (eventType === "change") {
         let { newCid, _target } = args;
         _target =
-          _target || (DOM.isFormInput(sourceEl) ? sourceEl.name : undefined);
+          _target ||
+          (DOM.isFormAssociated(sourceEl) ? sourceEl.name : undefined);
         if (_target) {
           pushOpts._target = _target;
         }

package/assets/js/phoenix_live_view/js_commands.ts

@@ -1,5 +1,6 @@
 import JS from "./js";
 import LiveSocket from "./live_socket";
+import { ensureSameOrigin } from "./utils";
 
 /**
  * An encoded JS command. Use functions in the `Phoenix.LiveView.JS` module on
@@ -17,29 +18,29 @@ type BaseOpts = {
   /**
    * The CSS transition classes to set.
    * Accepts a string of classes or a 3-tuple like:
-   * `["ease-out duration-300", "opacity-0", "opacity-100"]`
+   * `["ease-out duration-300", "opacity-0", "opacity-100"]`.
    */
   transition?: Transition;
-  /** The transition duration in milliseconds. Defaults 200. */
+  /** The transition duration in milliseconds. Defaults to `200`. */
   time?: number;
-  /** Whether to block UI during transition. Defaults `true`. */
+  /** Whether to block UI during transition. Defaults to `true`. */
   blocking?: boolean;
 };
 
 type ShowOpts = BaseOpts & {
-  /** The CSS display value to set. Defaults "block". */
+  /** The CSS display value to set. Defaults to `"block"`. */
   display?: string;
 };
 
 type ToggleOpts = {
-  /** The CSS display value to set. Defaults "block". */
+  /** The CSS display value to set. Defaults to `"block"`. */
   display?: string;
   /**
    * The CSS transition classes for showing.
    * Accepts either the string of classes to apply when toggling in, or
    * a 3-tuple containing the transition class, the class to apply
    * to start the transition, and the ending transition class, such as:
-   * `["ease-out duration-300", "opacity-0", "opacity-100"]`
+   * `["ease-out duration-300", "opacity-0", "opacity-100"]`.
    */
   in?: Transition;
   /**
@@ -47,7 +48,7 @@ type ToggleOpts = {
    * Accepts either string of classes to apply when toggling out, or
    * a 3-tuple containing the transition class, the class to apply
    * to start the transition, and the ending transition class, such as:
-   * `["ease-out duration-300", "opacity-100", "opacity-0"]`
+   * `["ease-out duration-300", "opacity-100", "opacity-0"]`.
    */
   out?: Transition;
   /** The transition duration in milliseconds. */
@@ -83,7 +84,7 @@ type NavigationOpts = {
  * Represents all possible JS commands that can be generated by the factory.
  * This is used as a base for LiveSocketJSCommands and HookJSCommands.
  */
-interface AllJSCommands {
+export interface AllJSCommands {
   /**
    * Executes an encoded JS command in the context of an element.
    * This version is for general use via liveSocket.js().
@@ -243,7 +244,7 @@ interface AllJSCommands {
 export default (
   liveSocket: LiveSocket,
   eventType: string | null,
-): AllJSCommands => {
+): LiveSocketJSCommands => {
   return {
     exec(el, encodedJS) {
       liveSocket.execJS(el, encodedJS, eventType);
@@ -355,6 +356,7 @@ export default (
       });
     },
     navigate(href, opts = {}) {
+      ensureSameOrigin(href, "navigate");
       const customEvent = new CustomEvent("phx:exec");
       liveSocket.historyRedirect(
         customEvent,
@@ -365,6 +367,7 @@ export default (
       );
     },
     patch(href, opts = {}) {
+      ensureSameOrigin(href, "patch");
       const customEvent = new CustomEvent("phx:exec");
       liveSocket.pushHistoryPatch(
         customEvent,