Update the open dialog API with more options. (#14)

Signed-off-by: Mikhail Aheichyk <[email protected]>

Author: maheichyk

src/ModuleApi.ts

@@ -19,6 +19,7 @@ import React from "react";
 import { PlainSubstitution, TranslationStringsObject } from "./types/translations";
 import { DialogContent, DialogProps } from "./components/DialogContent";
 import { AccountAuthInfo } from "./types/AccountAuthInfo";
+import { ModuleUiDialogOptions } from "./types/ModuleUiDialogOptions";
 
 /**
  * A module API surface for the react-sdk. Provides a stable API for modules to
@@ -46,14 +47,16 @@ export interface ModuleApi {
 
     /**
      * Opens a dialog in the client.
-     * @param title The title of the dialog
+     * @param initialTitleOrOptions Initial options for the dialog. Can be the title of the dialog, or a
+     *                              configuration object. Note that the dialog implementation may later
+     *                              modify its own options via the {@link DialogProps.setOptions} callback.
      * @param body The function which creates a body component for the dialog.
-     * @param props Optional props to provide to the dialog.
+     * @param props Optional props to provide to {@link body}, in addition to the common set in {@link DialogProps}.
      * @returns Whether the user submitted the dialog or closed it, and the model returned by the
      * dialog component if submitted.
      */
     openDialog<M extends object, P extends DialogProps = DialogProps, C extends DialogContent<P> = DialogContent<P>>(
-        title: string,
+        initialTitleOrOptions: string | ModuleUiDialogOptions,
         body: (props: P, ref: React.RefObject<C>) => React.ReactNode,
         props?: Omit<P, keyof DialogProps>,
     ): Promise<{ didOkOrSubmit: boolean, model: M }>;

src/components/DialogContent.tsx

@@ -17,16 +17,44 @@ limitations under the License.
 import * as React from "react";
 import { ModuleApi } from "../ModuleApi";
 import { PlainSubstitution } from "../types/translations";
+import { ModuleUiDialogOptions } from "../types/ModuleUiDialogOptions";
 
+/** React properties for dialog content implementations based on {@link DialogContent} */
 export interface DialogProps {
+    /**
+     * A reference to the active Module API.
+     */
     moduleApi: ModuleApi;
+
+    /**
+     * Callback to update the dialog options.
+     * 
+     * Dialog content implementations can call this to update any of the options that were
+     * originally set via {@link ModuleApi.openDialog}.
+     * 
+     * @param options - The updates that should be applied to the dialog options. Any properties
+     * not set in the {@link options} are left unchanged.
+     */
+    setOptions(options: Partial<ModuleUiDialogOptions>): void;
+
+    /**
+     * Cancel the dialog programmatically.
+     */
+    cancel(): void;
 }
 
+/** State of {@link DialogContent} */
 export interface DialogState {
     busy: boolean;
     error?: string;
 }
 
+/**
+ * Base class for the content of a Dialog.
+ * 
+ * The `body` callback passed to {@link ModuleApi.openDialog} should return an instance of a
+ * class based on this.
+ */
 export abstract class DialogContent<P extends DialogProps = DialogProps, S extends DialogState = DialogState, M extends object = {}>
     extends React.PureComponent<P, S> {
 

src/types/ModuleUiDialogOptions.ts

@@ -0,0 +1,42 @@
+/*
+Copyright 2023 Mikhail Aheichyk
+Copyright 2023 Nordeck IT + Consulting GmbH.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * Options for {@link ModuleApi#openDialog}.
+ */
+export interface ModuleUiDialogOptions {
+    /**
+     * The title of the dialog.
+     */
+    title: string;
+
+    /**
+     * The label of the action button. If unset, a default label will be used.
+     */
+    actionLabel?: string;
+
+    /**
+     * The label of the cancel button. If unset, a default label will be used.
+     */
+    cancelLabel?: string;
+
+    /**
+     * Enable or disable the action button when the dialog is created.
+     * @defaultValue The default is `true`
+     */
+    canSubmit?: boolean;
+}