Dialog Component

A NextJS component package for simplifying and standardizing the use of user dialog in NextJS apps. Supported features include:
- movable modal dialog box
- fully typed interface, with typing support in the dialog result for accessing items and buttons by name.
- configurable side effects: allow changes to an items value effect the values of other items or the the disabledness of buttons

Installation

Either 1) Use npx to run an example of the dialog component in a NextJS app:
``
$ npx hauke5/dialogexample
`
This will start a next development server.
Point a browser to http://localhost:3001/dialog to run the app.


Or 2) use git clone to install the component along with a usage example app in NextJS:
`
$ git clone https://github.com/Hauke5/DialogExample.git
`
This will install the required typescript components and support libraries, along with the usage example in app/dialog/DialogExample.tsx
To run the example manually, follow the git clone command with:
`
cd DialogExample # change into the newly created folder
npm i # install dependencies
npm run dev # run the development server
`
Again, point a browser to http://localhost:3001/dialog to run the app.

Usage

$3


A dialog is defined by the DialogConfig structure, consisting of
- a leading title to explain the purpose of the dialog to the user
- an optional description, accepting a ReactNode
- an optional list of dialog items, each consisting of a DialogItemConfig structure
- and a list of buttons to perform actions.

If not provided by the DialogConfig, A Cancel button will be automatically added by the component.

A simplest version of a dialog configuration might look like this:
`typescript
{
title: 'Simple Dialog Example:',
buttons:[
{ id:'OK'},
]
}
`


The ids for items and buttons are by default used as their labels. Alternatively, an optional label field can be specified:
`typescript
{
title: 'Example:',
items:[
{ id:'ValidItem', type:'number', initial: 0, label:'Enter Valid Number'}},
],
buttons:[
{ id:'OkButton', label:'OK'}},
]
}
`




Integrating Dialogs into Components


Add a

component at the end of React nodes in your component. It takes a callback function through which it provides an open function that can be stored in a Ref.

internally uses the html

tag, so stays invisible until opened, which happens below in runDialog when it is triggered by clicking on the Open Dialog button.

To open the dialog in code, call the open function provided by

with the dialog content structure and await the result. It provides
- the actionName, i.e. id of the button pressed (or, in some cases, an ID for some predefined dialog action such as double-clicking a file in a file selector field)
- an items object containing each of the item IDs, providing
- the type of the item's value
- the current value of the item,
- the isDefault status: false if the user has directly manipulated the item, and true if the value is either the initial value or the result of a sideEffect.
`typescript
function Component() {
const openDialog = useRef()

return

Open Dialog

openDialog.current=open} />

async function runDialog() {
if (openDialog.current) {
// open the dialog with dialogConfog as content
const result = await openDialog.current({
title: 'Example:',
items:[
{ id:'ValidItem', type:'number', initial: 0, label:'Enter Valid Number'}},
],
buttons:[
{ id:'OkButton', label:'OK'}},
]
})
// process the result action and item values
if (result.actionName==='Ok') {
const numberItem = result.items.ValidItem
const number = numberItem.value as number
const isDefault = numberItem.isDefault
...
}
}
}
}
`

Defining Side effects

Side effects are actions performed on the elements of a dialog box while the user manipulates them. For example, the disabled state of a button or the initial value of a dialog element can be made to change depending on the value of one or more other elements.

Two types of side effects are available:

$3

Add a disable function to a button configuration to tell the

whether the button should be active or disabled. The function will receive the same items object as is returned when the dialog closes
The following example disables the OkButton if the ValidItem value is 0
`typescript
...
buttons:[
{id:'OkButton', disable:(items) items.ValidItem.value===0},
]
...
`

$3

Add a sideEffect callback to an item configuration to have user-changes to the item value trigger updates to other items.
The callback will receive the current value of the item, as well as a reference to the set of all items.
In the example below, a sideEffect will be called each time the ValidItem number field changes. It will change the TextItem field, if it hasn't been explicitely set by the user, to read invalid number if the number value is 0, and valid number otherwise.
`typescript
{
title: 'Example:',
elements:[
{ id:'ValidItem', type:'number', initial: 0, label:'Enter Valid Number:',
sideEffect:(value, items)=>items.TextItem.isDefault
? {TextItem: value!==0? 'valid number' : 'invalid number' }
: {}
}},
{ id:'TextItem', type:'text', initial: 'invalid', label:'Number Comment:'}},
],
buttons:[
{ id:'OkButton', label:'OK'}},
]
}
`

Complex Example:

`typescript
{
title: 'Dialog Example With Side-Effects:',
description:

A complex dialog:

• Hint:You can move the box by dragging it in the title field.


• Side effects within the dialog:




• Ok Disabled: Enter a number other than 0 in the the Number field to enable the Ok button.


• Field auto-values:Changing the Number field automatically sets the Text field
  to valid or invalid depending on the Number field value,
  unless the user has manually changed it before




• Click the Ok button when available.
  The left box below will reflect the values from the dialog.

,
items:[
{id:'Date', type:'date', initial: new Date() },
{id:'Number', type:'number', initial: 0, label:'Enter Valid Number:', sideEffect:(value:number, items) =>
items.Text.isDefault
? {Text:(value !== 0)? 'valid number' : 'invalid number' }
: {}
},
{id:'Text', type:'text', initial: 'invalid', list:textFieldHistory},
{id:'Checkbox', type:'boolean',initial: false},
{id:'List', type:'select', initial: 'two', list:['one', 'two', 'three']},
],
buttons:[
{id:'Ok', disable:(values) => values.Number.value===0},
]
}
``