🤖 Merge PR DefinitelyTyped#51296 phoenix_live_view 0.15.4: support for uploaders by @pzingg

* phoenix_live_view v0.14.2

* Bump to 0.15.4, add uploaders option, UploadEntryInterface, LiveViewUploader… (#1)

* Bump to 0.15.4, add uploaders, UploadEntryInterface, LiveViewUploaderMeta

* Provide a URL for documentation

* phoenix_live_view: added tests and lint (DefinitelyTyped#2)

* updated methods, closer type signatures

* lint and test

* reopen PR for phoenix_live_view 0.15

Author: pzingg

types/phoenix_live_view/index.d.ts

@@ -1,8 +1,11 @@
-// Type definitions for phoenix_live_view 0.14
+// Type definitions for phoenix_live_view 0.15
 // Project: https://github.com/phoenixframework/phoenix_live_view
 // Definitions by: Peter Zingg <https://github.com/pzingg>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
+// Version 0.15.4 added options and interfaces for LiveView uploads
+// See: https://hexdocs.pm/phoenix_live_view/uploads.html
+
 import { Socket, SocketConnectOption } from 'phoenix';
 
 export interface Defaults {
@@ -32,6 +35,7 @@ export interface SocketOptions {
   hooks?: object;
   loaderTimeout?: number;
   params?: object;
+  uploaders?: object;
   viewLogger?: ViewLogger;
 }
 
@@ -42,7 +46,6 @@ export class LiveSocket {
   constructor(url: string, phxSocket: any, opts: SocketOptions);
 
   // public
-
   connect(): void;
   disableDebug(): void;
   disableLatencySim(): void;
@@ -54,67 +57,66 @@ export class LiveSocket {
   getLatencySim(): number | null;
   getSocket(): Socket;
   isDebugEnabled(): boolean;
-  isPhxView(el: HTMLElement): boolean;
   isProfileEnabled(): boolean;
 
   // private
-
-  // channel(topic: string, params: any): Channel;
-  // binding(kind: any): string;
-  // bind(events: any[], callback: BindCallback): void;
+  // bind(events: string[], callback: BindCallback): void;
+  // bindClick(eventName: string, bindingName: string, capture: boolean): void;
   // bindClicks(): void;
   // bindForms(): void;
+  // binding(kind: string): string;
   // bindNav(): void;
   // bindTopLevelEvents(): void;
   // blurActiveElement(): void;
+  // channel(topic: string, params: any): Channel;
   // commitPendingLink(linkRef: number): boolean;
-  // debounce(el: HTMLElement, event: string, callback: any): void;
+  // debounce(el: HTMLElement, event: Event, callback: any): void;
   // destroyAllViews(): void;
   // destroyViewByEl(el: HTMLElement): void;
   // dropActiveElement(view: View): void;
-  // eventMeta(eventName: string, e: any, targetEl: HTMLElement): object;
-  // getActiveElement(): HTMLElement;
+  // eventMeta(eventName: string, e: Event, targetEl: HTMLElement): object;
+  // getActiveElement(): Element;
   // getBindingPrefix(): string;
   // getHookCallbacks(hookName: string): any;
   // getHref(): string;
   // getRootById(id: string): any;
   // getViewByEl(el: HTMLElement): any;
   // hasPendingLink(): boolean;
-  // historyPatch(href: string, linkState: any): void;
-  // historyRedirect(href: string, linkState: any, flash: any): void;
+  // historyPatch(href: string, linkState: string): void;
+  // historyRedirect(href: string, linkState: string, flash: string): void;
   // isConnected(): boolean;
+  // isPhxView(el: HTMLElement): boolean;
   // isUnloaded(): boolean;
-  // joinRootView(el: HTMLElement, href: string, flash: any, callback: any): View;
+  // joinRootView(el: HTMLElement, href: string, flash: string, callback: (view: View, joinCount: number) => void): View;
   // joinRootViews(): boolean;
   // log(view: View, kind: string, msgCallback: () => [any, any]): void;
   // on(event: string, callback: (e: Event) => void): void;
-  // onChannel(channel: any, event: any, cb: (data: any) => void): void;
+  // onChannel(channel: Channel, event: string, cb: (data: any) => void): void;
   // owner(childEl: HTMLElement, callback: (view: View) => void): void;
   // pushHistoryPatch(href: string, linkState: any, targetEl: HTMLElement): void;
-  // redirect(to: string, flash: any): void;
+  // redirect(to: string, flash: string): void;
   // registerNewLocation(newLocation: Location): boolean;
-  // reloadWithJitter(view: any): void;
-  // replaceMain(href: string, flash: any, callback?: any, linkRef?: any): void;
+  // reloadWithJitter(view: View): void;
+  // replaceMain(href: string, flash: string, callback?: any, linkRef?: number): void;
   // replaceRootHistory(): void;
   // restorePreviouslyActiveFocus(): void;
-  // setActiveElement(target: HTMLElement): void;
+  // setActiveElement(target: Element): void;
   // setPendingLink(href: string): number;
   // silenceEvents(callback: () => void): void;
   // time(name: string, func: () => any): any;
   // triggerDOM(kind: string, args: any): void;
   // withinOwners(childEl: HTMLElement, callback: (view: View, el: HTMLElement) => void): void;
   // withPageLoading(info: Event, callback: any): any;
-  // wrapPush(push: any): any;
+  // wrapPush(view: View, opts: any, push: () => any): any;
 }
 
 export class Rendered {
   constructor(viewId: string, rendered: any);
 
   // public
-
   componentCIDs(diff: any): number[];
   componentToString(cid: number): string;
-  expandStatics(diff: any): void;
+  doRecursiveMerge(target: any, source: any): void;
   getComponent(diff: any, cid: number): any;
   isComponentOnlyDiff(diff: any): boolean;
   mergeDiff(diff: any): void;
@@ -125,7 +127,6 @@ export class Rendered {
   toString(onlyCids?: number[]): string;
 
   // private
-
   // comprehensionToBuffer(rendered: any, output: any): void;
   // createSpan(text: string, cid: number): HTMLSpanElement;
   // dynamicToBuffer(rendered: any, output: any): void;
@@ -135,7 +136,7 @@ export class Rendered {
   // toOutputBuffer(rendered: any, output: object): any;
 }
 
-export interface ViewHookInterface {
+export interface ViewHook {
   el: HTMLElement;
   viewName: string;
   pushEvent(event: string, payload: object, onReply?: (reply: any, ref: number) => any): void;
@@ -153,77 +154,112 @@ export interface ViewHookInterface {
 }
 
 export class View {
-  constructor(el: HTMLElement, liveSocket: LiveSocket, parentView: View, href: string, o: any);
+  constructor(el: HTMLElement, liveSocket: LiveSocket, parentView: View, href: string, flash: string);
 
-  ackJoin(child: any): void;
+  // public?
+  ackJoin(child: View): void;
   addHook(el: HTMLElement): void;
-  applyJoinPatch(live_patch: any, html: any, events: Array<[string, object]>): void;
+  applyDiff(type: string, rawDiff: any, callback: any): any;
+  applyJoinPatch(live_patch: any, html: string, events: Array<[string, object]>): void;
   applyPendingUpdates(): void;
   attachTrueDocEl(): void;
   bindChannel(): void;
   binding(kind: string): any;
+  cancelSubmit(formEl: HTMLElement): void;
   closestComponentID(targetCtx: object | null): number | null;
   componentID(el: HTMLElement): number | null;
   componentPatch(diff: any, cid: number): boolean;
   connectParams(): object;
   destroy(callback?: () => void): void;
   destroyAllChildren(): void;
   destroyDescendent(id: string): any;
-  destroyHook(hook: ViewHookInterface): void;
-  displayError(): void;
+  destroyHook(hook: ViewHook): void;
   dispatchEvents(events: Array<[string, object]>): void;
+  displayError(): void;
   dropPendingRefs(): void;
   expandURL(to: string): string;
   extractMeta(el: HTMLElement, meta: object): object;
   formsForRecovery(html: string): HTMLElement[];
   getChildById(id: string): any;
   getDescendentByEl(el: HTMLElement): any;
-  getHook(el: HTMLElement): ViewHookInterface;
-  getSession(): string;
+  getHook(el: HTMLElement): ViewHook;
+  getScheduledSubmit(formEl: HTMLElement): any;
+  getSession(): any;
   getStatic(): string | null;
   hideLoader(): void;
   isConnected(): boolean;
   isDestroyed(): boolean;
   isJoinPending(): boolean;
   isLoading(): boolean;
   isMain(): boolean;
-  join(callback?: (view: View, joinCount: number) => void): any;
+  join(callback: any): void;
   joinChild(el: HTMLElement): any;
   joinNewChildren(): void;
   log(kind: string, msgCallback: any): void;
   maybePushComponentsDestroyed(destroyedCIDs: number[]): any;
   name(): string;
   onAllChildJoinsComplete(): void;
   onChannel(event: string, cb: (resp: any) => void): void;
-  onClose(): void;
-  onError(reason: any): void;
+  onClose(reason: string): void;
+  onError(reason: string): void;
   onJoin(resp: object): void;
-  onJoinComplete(resp: object, html: any, events: Array<[string, object]>): void;
+  onJoinComplete(resp: object, html: string, events: Array<[string, object]>): void;
   onJoinError(resp: object): void;
   onLivePatch(redir: object): void;
   onLiveRedirect(redir: object): void;
   onRedirect(redir: object): void;
   ownsElement(el: HTMLElement): boolean;
   performPatch(patch: any, pruneCids: boolean): boolean;
   pushEvent(type: string, el: HTMLElement, targetCtx: object | null, phxEvent: string, meta: object): void;
+  pushFileProgress(fileEl: HTMLElement, entryRef: string, progress: number, onReply?: () => void): void;
   pushFormRecovery(form: HTMLElement, callback: any): void;
-  pushFormSubmit(inputEl: HTMLElement, targetCtx: object | null, kind: string, phxEvent: string, onReply: any): void;
-  pushHookEvent(targetCtx: object | null, event: string, payload: object): void;
-  pushInput(inputEl: HTMLElement, targetCtx: object | null, kind: string, phxEvent: string, callback: any): void;
+  pushFormSubmit(formEl: HTMLElement, targetCtx: object | null, phxEvent: string, onReply: any): void;
+  pushHookEvent(targetCtx: object | null, event: string, payload: object, onReply: any): void;
+  pushInput(inputEl: HTMLElement, targetCtx: object | null, phxEvent: string, callback: any): void;
   pushKey(keyElement: HTMLElement, targetCtx: object | null, kind: string, phxEvent: string, meta: object): void;
   pushLinkPatch(href: string, targetEl: HTMLElement, callback: any): void;
-  pushWithReply(refGenerator: any, event: string, payload: object, onReply: any): any;
+  pushWithReply(refGenerator: any, event: string, payload: object, onReply?: () => void): any;
   putRef(elements: HTMLElement[], event: string): [number, HTMLElement[]];
   renderContainer(diff: any, kind: string): string;
-  setContainerClasses(...classes: any[]): void;
+  scheduleSubmit(formEl: HTMLElement, ref: number, callback: any): boolean;
+  setContainerClasses(...classes: string[]): void;
   showLoader(timeout?: number): void;
   submitForm(form: HTMLElement, targetCtx: object | null, phxEvent: string): void;
   targetComponentID(target: HTMLElement, targetCtx?: object): number | null;
-  triggerBeforeUpdate(fromEl: HTMLElement, toEl: HTMLElement): any;
+  triggerAwaitingSubmit(formEl: HTMLElement): void;
+  triggerBeforeUpdateHook(fromEl: HTMLElement, toEl: HTMLElement): any;
   triggerReconnected(): void;
-  triggerUpdatedHook(hook: any): void;
-  update(diff: any, events: Array<[string, object]>): void;
   undoRefs(ref: number): void;
+  update(diff: any, events: Array<[string, object]>): void;
+  uploadFiles(formEl: HTMLElement, targetCtx: object | null, ref: number, cid: number, onComplete: any): void;
+  withinTargets(phxTarget: string, callback: any): void;
+}
+
+export interface LiveViewFile extends File {
+  _phxRef?: string;
+}
+
+export class UploadEntry {
+  constructor(fileEl: HTMLInputElement, file: LiveViewFile, view: View);
+
+  fileEl: HTMLInputElement;
+  file: LiveViewFile;
+  view: View;
+  meta: object | null;
+  metadata: () => object | null;
+  progress: (progress: number) => void;
+  cancel: () => void;
+  isDone: () => boolean;
+  error: (reason: string) => void;
+}
+
+export interface LiveViewUploaderMeta {
+  path: string;
+  ref: string;
+  name: string;
+  type: string;
+  size: number;
+  last_modified?: number;
 }
 
 export function debug(view: View, kind: string, msg: object, obj: object): void;
@@ -233,43 +269,55 @@ export namespace Browser {
   function dropLocal(namespace: string, subkey: string): any;
   function fetchPage(href: string, callback: (status: number, resp?: string) => any): any;
   function getCookie(name: string): string;
-  function getHashTargetEl(hash: any): HTMLElement | null;
+  function getHashTargetEl(maybeHash: any): HTMLElement | null;
   function getLocal(namespace: string, subkey: string): any;
   function localKey(namespace: string, subkey: string): string;
-  function pushState(kind: any, meta: any, to: string): void;
-  function redirect(toURL: string, flash: any): void;
+  function pushState(kind: string, meta: object, to: string): void;
+  function redirect(toURL: string, flash: string): void;
   function setCookie(name: string, value: string): void;
+  function updateCurrentState(callback: any): void;
   function updateLocal(namespace: string, subkey: string, initial: any, func: (current: any) => any): any;
 }
 
 export namespace DOM {
   function all(node: Node, query: string, callback: (el: HTMLElement) => HTMLElement): HTMLElement[];
   function byId(id: string): HTMLElement | void;
-  function cleanChildNodes(container: any, phxUpdate: any): void;
-  function cloneNode(node: Node, html: any): Node;
+  function childNodeLength(html: string): number;
+  function cleanChildNodes(container: Node, phxUpdate: string): void;
+  function cloneNode(node: Node, html: string): Node;
   function copyPrivates(target: HTMLElement, source: HTMLElement): void;
   function debounce(el: HTMLElement, event: Event, phxDebounce: string, defaultDebounce: string | null, phxThrottle: string, defaultThrottle: string | null, callback: () => any): any;
   function deletePrivate(el: HTMLElement, key: string): void;
-  function discardError(container: HTMLElement, el: HTMLElement, phxFeedbackFor: string): void;
+  function discardError(container: Node, el: HTMLElement, phxFeedbackFor: string): void;
   function dispatchEvent(target: Node, eventString: string, detail?: object): void;
+  function filterWithinSameLiveView(nodes: Node[], parent: any): any;
   function findComponentNode(node: Node, cid: number): HTMLElement[];
   function findParentCIDs(node: Node, cids: number[]): Set<number>;
   function findPhxChildren(el: HTMLElement, parentId: string): HTMLElement[];
   function findPhxChildrenInFragment(html: string, parentId: string): HTMLElement[];
+  function findUploadInputs(node: Node): void | any[];
+  function hasSelectionRange(el: HTMLElement): boolean;
   function incCycle(el: HTMLElement, key: string, trigger?: any): number;
   function isFormInput(el: HTMLElement): boolean;
+  function isIgnored(el: HTMLElement, phxUpdate: string): boolean;
   function isNowTriggerFormExternal(el: HTMLElement, phxTriggerExternal: string): boolean;
-  function isPhxChild(el: HTMLElement): boolean;
-  function isPhxUpdate(el: HTMLElement, phxUpdate: any, updateTypes: string[]): boolean;
+  function isPhxChild(el: Node): boolean;
+  function isPhxDestroyed(node: Node): boolean;
+  function isPhxUpdate(el: Node, phxUpdate: string, updateTypes: string[]): boolean;
   function isTextualInput(el: HTMLElement): boolean;
+  function isUploadInput(el: HTMLElement): boolean;
+  function markPhxChildDestroyed(el: HTMLElement): void;
   function mergeAttrs(target: HTMLElement, source: HTMLElement, exclude?: string[]): void;
   function mergeFocusedInput(target: HTMLElement, source: HTMLElement): void;
   function once(el: HTMLElement, key: string): boolean;
+  function private(el: HTMLElement, key: string): any;
   function putPrivate(el: HTMLElement, key: string, value: any): void;
   function putTitle(str: string): void;
   function removeClass(el: HTMLElement, className: string): void;
   function restoreFocus(focused: HTMLElement, selectionStart: number, selectionEnd: number): void;
+  function showError(inputEl: HTMLElement, phxFeedbackFor: string): void;
   function syncAttrsToProps(el: HTMLElement): void;
-  function syncPendingRef(ref: number | null, fromEl: HTMLElement, toEl: HTMLElement): boolean;
+  function syncPendingRef(fromEl: HTMLElement, toEl: HTMLElement, disableWith: string): boolean;
   function triggerCycle(el: HTMLElement, key: string, currentCycle?: number): void;
+  function withinSameLiveView(node: Node, parent: Node): boolean;
 }

types/phoenix_live_view/phoenix_live_view-tests.ts

@@ -0,0 +1,45 @@
+import { Socket } from "phoenix";
+import { LiveSocket, SocketOptions, ViewHook, UploadEntry } from "phoenix_live_view";
+
+function test_socket() {
+  // Hooks
+  const testHook = {
+    mounted() {
+      const hook = this as unknown as ViewHook;
+      console.log('TestHook mounted');
+      hook.pushEvent('hook-mounted', { name: 'testHook' },
+        (reply, ref) => {
+          console.log(`Got hook-mounted reply ${JSON.stringify(reply)} ref ${ref}`);
+        });
+    }
+  };
+
+  // Uploaders
+  function testUploader(entries: UploadEntry[], _onViewError: any) {
+    entries.forEach(entry => {
+      console.log(`file: ${entry.file.name}`);
+      console.log(`meta: ${JSON.stringify(entry.meta)}`);
+    });
+  }
+
+  const MyHooks = {
+    test: testHook
+  };
+
+  const MyUploaders = {
+    test: testUploader
+  };
+
+  const opts: SocketOptions = {
+    params: {
+      _csrf_token: '1234'
+    },
+    hooks: MyHooks,
+    uploaders: MyUploaders
+  };
+
+  const liveSocket = new LiveSocket("/live", Socket, opts);
+  liveSocket.enableDebug();
+  liveSocket.enableProfiling();
+  liveSocket.connect();
+}

types/phoenix_live_view/tsconfig.json

@@ -18,6 +18,7 @@
         "forceConsistentCasingInFileNames": true
     },
     "files": [
-        "index.d.ts"
+        "index.d.ts",
+        "phoenix_live_view-tests.ts"
     ]
 }