brew-js-react 0.5.1 → 0.5.2

package/dialog.d.ts

@@ -1,35 +1,116 @@
 export type DialogCloseCallback<T> = (value?: T) => Promise<void>;
 
 export interface DialogState<T> {
+    /**
+     * Gets the root element of the dialog.
+     */
     readonly root: HTMLElement;
+    /**
+     * Opens the dialog.
+     *
+     * It will receive result from {@link DialogState.close} or {@link DialogRenderComponentProps.closeDialog} when the dialog is properly closed.
+     * Otherwise in cases such as being closed due to lost of focus, result value will always be `undefined`.
+     */
     open: () => Promise<T | undefined>;
-    close: DialogCloseCallback<T>;
+    /**
+     * Closes the dialog, with optional result value.
+     *
+     * This method is different from {@link DialogRenderComponentProps.closeDialog} that {@link DialogBaseProps.onCommit} will not be called.
+     */
+    close: (value?: T) => Promise<void>;
 }
 
-export interface DialogBaseProps<T> {
+export interface DialogBaseProps<T, V = T> {
+    /**
+     * Specifies dialog title.
+     * This property is intended to be handled by {@link DialogOptions.onRender} or {@link DialogOptions.wrapper}.
+     */
     title?: string;
+    /**
+     * CSS class names to be added to root element.
+     */
     className?: string;
+    /**
+     * Whether to show close button in the dialog.
+     * This property is intended to be handled by {@link DialogOptions.onRender} or {@link DialogOptions.wrapper}.
+     */
     showCloseButton?: boolean;
+    /**
+     * Whether confirmation should be prompted when user leaves the page.
+     */
     preventLeave?: boolean;
+    /**
+     * Whether navigation within single-paged app should be prevented.
+     */
     preventNavigation?: boolean;
+    /**
+     * Whether the dialog is modal.
+     */
     modal?: boolean;
-    onCommit?: (value: T | undefined) => void;
+    /**
+     * Whether flyout content will be initially focused.
+     * Default is `true` if source element is not an text input element.
+     *
+     * If a CSS selector is given, the first matched element will be focused; otherwise
+     * the first focusable element will be focused.
+     */
+    focus?: boolean | string;
+    /**
+     * Callback to perform asynchronous action when user confirms the dialog.
+     *
+     * The callback will receive value sent from {@link DialogRenderComponentProps.closeDialog},
+     * and will send resolved value to promise returned by {@link DialogState.open}.
+     *
+     * The dialog will be held open until the returned promise resolves.
+     * When the promise rejects, the dialog will remain open.
+     */
+    onCommit?: (value: V | undefined) => T | Promise<T> | void;
+    /**
+     * Callback to be invoked when dialog has opened.
+     */
     onOpen?: (root: HTMLElement) => void;
+    /**
+     * Callback to be invoked when dialog has closed, after outro animation and before React DOM is unmounted.
+     */
     onClose?: (root: HTMLElement) => void;
 }
 
-export interface DialogRenderComponentProps<T, P = {}> extends DialogBaseProps<T>, P {
-    closeDialog: DialogCloseCallback<T>;
+export interface DialogRenderComponentProps<T, V = T> extends DialogBaseProps<T, V> {
+    /**
+     * Commits the dialog, with optional result value.
+     *
+     * When {@link DialogBaseProps.onCommit} is specified, it is invoked with the value passed in.
+     * Dialog will be closed when async operation is completed, or remain open if the operation failed.
+     */
+    closeDialog: (value?: V) => Promise<void>;
 }
 
-export interface DialogOptions<T, P = {}> extends DialogBaseProps<T> {
-    onRender: React.FC<DialogRenderComponentProps<T, P>>;
+export interface DialogOptions<T, V = T> extends DialogBaseProps<T, V> {
+    /**
+     * A callback that render dialog contents.
+     */
+    onRender: React.FC<DialogRenderComponentProps<T, V> & this>;
+    /**
+     * Specifies wrapper component that envelops content from {@link DialogOptions.onRender},
+     * which is useful for reusable layout for dialogs.
+     */
+    wrapper?: React.FC<React.PropsWithChildren<DialogRenderComponentProps<T, V> & this>>;
 }
 
-export interface DialogProps<T> extends React.PropsWithChildren<DialogBaseProps<T>> {
+export interface DialogProps<T, V = T> extends React.PropsWithChildren<DialogBaseProps<T, V>> {
+    /**
+     * A boolean flag controlling whether dialog is open.
+     */
     isOpen: boolean;
 }
 
-export function createDialog<T = any, P = {}>(props: DialogOptions<T, P> & { wrapper?: React.FC<React.PropsWithChildren<DialogRenderComponentProps<T, P>>> }): DialogState<T>;
+/**
+ * Creates a controller to render dialog.
+ * @param props A dictionary containing options.
+ */
+export function createDialog<T = any, V = T>(props: DialogOptions<T, V>): DialogState<T>;
 
-export function Dialog<T>(props: DialogProps<T>): JSX.Element;
+/**
+ * Renders a dialog declaratively.
+ */
+export function Dialog<T, V = T>(props: DialogProps<T, V>): JSX.Element;

package/dialog.js

@@ -1,7 +1,7 @@
 import { createElement, useEffect, useState } from "react";
 import ReactDOM from "react-dom";
 import ReactDOMClient from "./include/external/react-dom-client.js";
-import { always, either, extend, makeAsync, noop, pipe, setImmediate } from "./include/zeta-dom/util.js";
+import { either, extend, makeAsync, noop, pick, pipe, resolve } from "./include/zeta-dom/util.js";
 import { containsOrEquals, removeNode, setClass } from "./include/zeta-dom/domUtil.js";
 import dom from "./include/zeta-dom/dom.js";
 import { lock, notifyAsync, preventLeave, subscribeAsync } from "./include/zeta-dom/domLock.js";
@@ -17,7 +17,11 @@ export function createDialog(props) {
     var promise;
 
     dom.on(root, {
+        flyoutshow: function () {
+            (props.onOpen || noop)(root);
+        },
         flyouthide: function () {
+            promise = null;
             removeNode(root);
             (props.onClose || noop)(root);
             if (props.onRender) {
@@ -31,7 +35,7 @@ export function createDialog(props) {
             setClass(root, 'loading', false);
         }
     });
-    subscribeAsync(root);
+    subscribeAsync(root, true);
 
     return {
         root: root,
@@ -45,7 +49,6 @@ export function createDialog(props) {
             dom.retainFocus(dom.activeElement, root);
             if (props.modal) {
                 root.setAttribute('is-modal', '');
-                dom.setModal(root);
             }
             if (props.onRender) {
                 var dialogProps = extend({}, props, {
@@ -60,20 +63,15 @@ export function createDialog(props) {
                     content = createElement(props.wrapper, dialogProps, content);
                 }
                 reactRoot.render(content);
-                setImmediate(function () {
-                    dom.focus(root);
-                });
             }
-            promise = openFlyout(root);
+            promise = resolve().then(function () {
+                return openFlyout(root, null, pick(props, ['focus']));
+            });
             if (props.preventLeave) {
                 preventLeave(root, promise);
             } else if (props.preventNavigation) {
                 lock(root, promise);
             }
-            always(promise, function () {
-                promise = null;
-            });
-            (props.onOpen || noop)(root);
             return promise;
         }
     };

package/dist/brew-js-react.js

@@ -1,4 +1,4 @@
-/*! brew-js-react v0.5.1 | (c) misonou | https://misonou.github.io */
+/*! brew-js-react v0.5.2 | (c) misonou | https://misonou.github.io */
 (function webpackUniversalModuleDefinition(root, factory) {
 	if(typeof exports === 'object' && typeof module === 'object')
 		module.exports = factory(require("brew-js"), require("react"), require("react-dom"), require("zeta-dom"), require("zeta-dom-react"), require("waterpipe"), require("jquery"));
@@ -355,6 +355,7 @@ var domUtil_lib$util = external_commonjs_zeta_dom_commonjs2_zeta_dom_amd_zeta_do
     createNodeIterator = domUtil_lib$util.createNodeIterator,
     createTreeWalker = domUtil_lib$util.createTreeWalker,
     bind = domUtil_lib$util.bind,
+    bindOnce = domUtil_lib$util.bindOnce,
     bindUntil = domUtil_lib$util.bindUntil,
     dispatchDOMMouseEvent = domUtil_lib$util.dispatchDOMMouseEvent,
     removeNode = domUtil_lib$util.removeNode,
@@ -443,7 +444,11 @@ function createDialog(props) {
 
   var promise;
   zeta_dom_dom.on(root, {
+    flyoutshow: function flyoutshow() {
+      (props.onOpen || noop)(root);
+    },
     flyouthide: function flyouthide() {
+      promise = null;
       removeNode(root);
       (props.onClose || noop)(root);
 
@@ -458,7 +463,7 @@ function createDialog(props) {
       setClass(root, 'loading', false);
     }
   });
-  subscribeAsync(root);
+  subscribeAsync(root, true);
   return {
     root: root,
     close: _closeDialog,
@@ -473,7 +478,6 @@ function createDialog(props) {
 
       if (props.modal) {
         root.setAttribute('is-modal', '');
-        zeta_dom_dom.setModal(root);
       }
 
       if (props.onRender) {
@@ -491,12 +495,11 @@ function createDialog(props) {
         }
 
         reactRoot.render(content);
-        setImmediate(function () {
-          zeta_dom_dom.focus(root);
-        });
       }
 
-      promise = openFlyout(root);
+      promise = resolve().then(function () {
+        return openFlyout(root, null, pick(props, ['focus']));
+      });
 
       if (props.preventLeave) {
         preventLeave(root, promise);
@@ -504,10 +507,6 @@ function createDialog(props) {
         lock(root, promise);
       }
 
-      always(promise, function () {
-        promise = null;
-      });
-      (props.onOpen || noop)(root);
       return promise;
     }
   };
@@ -1636,7 +1635,7 @@ definePrototype(FlyoutToggleMixin, ClassNameMixin, {
     var self = this;
     FlyoutToggleMixinSuper.initElement.call(self, element, state);
     self.onDispose(zeta_dom_dom.on(element, 'click', function () {
-      toggleFlyout(self.flyoutMixin.elements()[0], element);
+      toggleFlyout(self.flyoutMixin.elements()[0], element, self.flyoutMixin.flyoutOptions);
     }));
   }
 });
@@ -1656,6 +1655,7 @@ function FlyoutMixin() {
   self.isFlyoutOpened = false;
   self.animating = false;
   self.visible = false;
+  self.initialFocus = undefined;
   self.toggle = new FlyoutToggleMixin(self);
   self.onDispose(function () {
     self.isFlyoutOpened = false;
@@ -1663,6 +1663,16 @@ function FlyoutMixin() {
   });
 }
 definePrototype(FlyoutMixin, ClassNameMixin, {
+  get flyoutOptions() {
+    var options = {};
+
+    if (this.initialFocus !== undefined) {
+      options.focus = this.initialFocus;
+    }
+
+    return options;
+  },
+
   next: function next() {
     this.effects = undefined;
     return FlyoutMixinSuper.next.call(this);
@@ -1689,7 +1699,7 @@ definePrototype(FlyoutMixin, ClassNameMixin, {
   open: function open(value) {
     var element = this.elements()[0];
     valueMap.set(element, value);
-    return openFlyout(element);
+    return openFlyout(element, null, this.flyoutOptions);
   },
   close: function close(value) {
     return closeFlyout(this.elements()[0], value);